If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/QL-Win/QuickLook shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 7 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live QL-Win/QuickLook repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/QL-Win/QuickLook.

What it runs against: a local clone of QL-Win/QuickLook — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in QL-Win/QuickLook | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of QL-Win/QuickLook. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/QL-Win/QuickLook.git
#   cd QuickLook
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of QL-Win/QuickLook and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "QL-Win/QuickLook(\\.git)?\\b" \\
  && ok "origin remote is QL-Win/QuickLook" \\
  || miss "origin remote is not QL-Win/QuickLook (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f ".github/workflows/msbuild.yml" \\
  && ok ".github/workflows/msbuild.yml" \\
  || miss "missing critical file: .github/workflows/msbuild.yml"
test -f "Build/AppxManifest.xml" \\
  && ok "Build/AppxManifest.xml" \\
  || miss "missing critical file: Build/AppxManifest.xml"
test -f "Build/micasetup.json" \\
  && ok "Build/micasetup.json" \\
  || miss "missing critical file: Build/micasetup.json"
test -f ".gitmodules" \\
  && ok ".gitmodules" \\
  || miss "missing critical file: .gitmodules"
test -f "CHANGELOG.md" \\
  && ok "CHANGELOG.md" \\
  || miss "missing critical file: CHANGELOG.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/QL-Win/QuickLook"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

QuickLook is a Windows port of macOS's Quick Look feature that enables instant file preview by pressing Space in Windows Explorer. Written primarily in C# (1.7M lines) with C++ shims (172K lines) and DirectX/HLSL rendering, it provides quick previews of images, documents, videos, and archives without opening dedicated applications—a powerful productivity tool that ships as a shell integration. Monolithic but layered: core C# application logic sits in the main project; C++ interop shims (172K lines) handle Windows shell integration and low-level preview rendering; HLSL shaders (2168 lines) drive DirectX preview rendering. Assets in Build/Assets/ support packaging (AppxManifest.xml implies UWP/MSIX distribution). PowerShell scripts likely handle build orchestration.

Windows power users and explorers who frequently browse file systems and want instant previews (like macOS users enjoy), plus system integrators who contribute plugins to support additional file formats. Developers working on Windows shell extensions and file format handlers.

Actively maintained and production-ready. The repo shows strong engagement with GitHub workflows (MSBuild CI/CD in .github/workflows/msbuild.yml), organized issue templates, and structured releases. However, the exact commit frequency and test coverage are not visible in the file list provided—the presence of AppVeyor and GitHub Actions suggests continuous integration is taken seriously.

Risk factors: shell integration complexity (interfacing deeply with Windows Explorer via C++ bridges) means breaking changes in Windows versions can require rapid fixes; the codebase mixes C# and C++ which increases maintenance burden and onboarding friction. No visible test suite structure in the top-60 files suggests testing discipline may be underdocumented. Single-language-dominant (C# at 1.7M lines) suggests most contributors focus on that area.

Active development indicated by structured GitHub workflows and CI/CD setup (.github/workflows/msbuild.yml). The presence of copilot-instructions.md suggests recent modernization efforts. Specific PR/issue activity not visible in file list, but the .appveyor.yml and msbuild.yml suggest continuous integration is a priority.

Clone the repo: git clone https://github.com/QL-Win/QuickLook.git && cd QuickLook. Install dependencies via .NET SDK (inferred from C# dominance); open QuickLook.sln in Visual Studio or use dotnet build. Use MSBuild or the provided GitHub Actions workflow as your reference: see .github/workflows/msbuild.yml for exact build steps.

Daily commands: After cloning and restoring NuGet packages: open QuickLook.sln in Visual Studio 2019+ and build (Ctrl+Shift+B), or use msbuild QuickLook.sln from the command line. The GitHub Actions workflow (msbuild.yml) shows the canonical build: it restores NuGet, builds the solution, and packages it. For local testing, the built .exe in the output directory can be run directly or installed via MSIX.

• .github/workflows/msbuild.yml — CI/CD pipeline that builds and packages the QuickLook application; essential for understanding deployment and release process
• Build/AppxManifest.xml — Windows App Package manifest defining application identity, capabilities, and entry points; required reading for understanding app configuration
• Build/micasetup.json — Build configuration for the installer and setup process; critical for understanding how the application is packaged and distributed
• .gitmodules — Git submodule dependencies that indicate external plugin or library dependencies; essential for understanding the full project structure
• CHANGELOG.md — Version history and feature changelog; provides context on project evolution and backwards compatibility concerns
• OPTIONS.md — Configuration options documentation; describes all user-configurable settings and their behavior

• QuickLook Core Service (C#, .NET Framework, Windows API) — File watching, plugin discovery/loading, preview window lifecycle, caching
  • Failure mode: Service crashes → Space key does nothing; user cannot preview files
• Format Plugins (DLL) (Language/framework varies per plugin (C#, C++, etc.)) — Convert file bytes to previewable content (image, text, metadata render)
  • Failure mode: Plugin crash → Core app may crash; specific format becomes unpreviewable
• Windows Shell Integration (Windows Registry, Shell Extensions API) — Registry hooks for File Explorer context menu and Space key binding
  • Failure mode: Registration fails → App appears not installed; no explorer integration
• AppX Installer/Update System (Windows App Store, MSIX/AppX package format) — Install to Program Files, register app with OS, auto-update mechanism
  • Failure mode: Package corruption → App uninstallable or fails to launch
• Preview Cache (File system cache (likely local AppData)) — Persistent disk cache of thumbnail and preview images for performance
  • Failure mode: Cache corruption → Stale previews shown; user must manually clear cache

• File Explorer → QuickLook Core — File path and metadata when user presses Space
• QuickLook Core → Format Plugin — File handle or byte stream for rendering
• Format Plugin → Preview Window UI — Rendered image, text, or structured content
• Preview Content → Cache Storage — Thumbnail/preview saved for quick re-access
• Cache Storage → Preview Window — Retrieved cached preview on file re-selection (instant display)

Add a New File Format Plugin

1. Create a new plugin repository as a Git submodule in .gitmodules (.gitmodules)
2. Use the standard QLPlugin.ico as the plugin icon template (QLPlugin.ico)
3. Build the plugin as a Windows DLL following QuickLook plugin architecture (.github/workflows/msbuild.yml)
4. Register the plugin in AppxManifest.xml if needed for app-integrated formats (Build/AppxManifest.xml)

Update Application Configuration

1. Document new configuration options in OPTIONS.md (OPTIONS.md)
2. Update the version and capabilities in AppxManifest.xml (Build/AppxManifest.xml)
3. Add entry to version history in CHANGELOG.md (CHANGELOG.md)
4. Update installer configuration if needed (Build/micasetup.json)

Release New Application Version

1. Update CHANGELOG.md with version details and breaking changes (CHANGELOG.md)
2. Update application version in AppxManifest.xml (Build/AppxManifest.xml)
3. Trigger build pipeline which runs automatically on commit (.github/workflows/msbuild.yml)
4. The workflow will package the app using micasetup.json configuration (Build/micasetup.json)

• Windows AppX/MSIX Packaging — Provides modern distribution through Windows App Store, enables automatic updates, and ensures code signing for security
• Plugin DLL Architecture — Allows extensible format support without rebuilding core app; plugins can be developed independently and distributed separately
• Windows Shell Integration (File Explorer hook) — Enables native Space-key activation matching macOS Quick Look; requires deep OS integration
• Git Submodules for Plugins — Decouples plugin development from core app; each plugin maintains own versioning and release cycle

• Plugin-based architecture vs. monolithic application

  • Why: Allows community to contribute format support without core team oversight
  • Consequence: Plugin quality/security varies; complex dependency management via submodules

• Windows-only implementation (AppX/Explorer integration)

  • Why: Native performance and seamless OS integration only possible on Windows
  • Consequence: Cannot support Linux/macOS; ties implementation to Windows APIs

• GPL license

  • Why: Open source transparency and community contribution
  • Consequence: Restricts use in proprietary software; commercial plugins must also be GPL

• Cross-platform support (Windows-only)
• Real-time collaboration or network preview sharing
• Plugin sandboxing (plugins run with app privileges)
• Full file editing capabilities (preview-only, not editor)
• Support for encrypted or password-protected archives without user interaction

• Tight coupling between plugin interface and core app (Medium) — Plugin architecture (implied by submodule structure): Plugins likely depend on fixed DLL interface; changes to core require recompilation of all plugins
• Single Windows-only API dependency (Low) — Entire codebase (Shell Integration, MSIX, File Explorer hooks): No abstraction layer for OS-specific features; impossible to port or support other OSes without rewrite
• Certificate-based signing with committed keys (High) — Build/sideload.pfx, Build/sideload.crt, Build/sideload.key: Private signing keys committed to repository (even if marked .gitignore, presence is a risk); should use secure key storage

• Plugin loading at runtime (undefined) — First preview request of an unseen format requires DLL discovery,

Shell integration deeply couples to Windows version and Explorer behavior—changes in Windows 11 may require C++ shim updates. MSIX/AppX packaging requires signing certificates for Store distribution (check AppxManifest.xml for signing config). Git submodules must be cloned recursively (git clone --recursive) or dependencies fail silently. DirectX shaders require compilation; HLSL toolchain must be present (typically bundled in Visual Studio). No obvious environment variables or required services in the file list, but shell integration may require administrator privileges or registry modifications.

• Windows Shell Extensions (IShellExtInit, IContextMenu) — QuickLook integrates into Explorer via shell extension APIs; understanding COM interfaces and the Windows shell namespace is critical for debugging activation and context-menu behavior.
• DirectX 11 Rendering Pipeline & HLSL Shaders — Preview rendering uses GPU-accelerated effects (inferred from 2168 lines of HLSL); understanding rasterization, pixel shaders, and framebuffer management is essential for performance tuning and custom preview effects.
• MSIX/AppX Package Format & Code Signing — AppxManifest.xml and Build/ structure indicate distribution via Windows Store or MSIX; understanding package identity, capabilities declarations, and code signing is required for deployment and shell integration registration.
• COM Interop (C# ↔ C++ Bridge) — The 172K lines of C++ likely expose COM interfaces consumed by C# WPF; understanding marshaling, SAFEARRAY, and COM lifetime management is vital for avoiding memory leaks and native crashes.
• Windows Registry & ShellEx Registration — File preview activation likely depends on registry entries under HKCR.ext\ShellEx; understanding registration paths, ProgID mappings, and elevation manifest is critical for debugging handler discovery.
• Plugin Architecture & Assembly Loading (MAF or custom) — The diversity of supported formats (images, docs, video, archives) suggests dynamic plugin loading; understanding AppDomain marshaling or .NET Core AssemblyLoadContext is essential for extending format support safely.
• WPF Rendering & RenderTargetBitmap — C# preview UI likely uses WPF for layout; understanding dependency properties, element trees, and offscreen rendering (RenderTargetBitmap) is needed for custom preview panes and transitions.

• jqlang/jq — Not directly related to QuickLook's core, but QuickLook likely previews JSON files; jq is a reference for robust file format parsing patterns.
• ShareX/ShareX — Another Windows shell integration tool (screen capture / file sharing); demonstrates C# + shell hook patterns and installer/MSIX strategy relevant to QuickLook's distribution.
• files-community/Files — Modern Windows file manager; shares QuickLook's goal of enhancing Explorer UX and uses similar C# / Windows shell integration techniques.
• M2Team/NanaZip — Windows context-menu shell integration for archives; demonstrates C++ COM interop patterns and MSIX packaging that QuickLook relies on for activation.
• apple/macos-samples — Apple's official Quick Look implementation reference samples; useful for understanding the original macOS feature that QuickLook emulates.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for automated asset validation

The repo has extensive asset files (Build/Assets/) with multiple scale variants (scale-100 through scale-400) and format variants (altform-unplated, targetsize variants). There's no visible CI validation that these assets are present, correctly named, and match the AppxManifest.xml references. This prevents accidental asset deletions or naming inconsistencies during contributions.

• [ ] Create .github/workflows/asset-validation.yml to validate all required asset scales exist
• [ ] Reference Build/AppxManifest.xml to extract required asset definitions
• [ ] Validate file naming conventions match scale patterns (scale-100, scale-125, etc.)
• [ ] Ensure no orphaned assets exist without manifest references
• [ ] Run on PR submissions to catch asset breakage early

Create plugin development testing guide and validation utility

QuickLook uses a plugin system (evidenced by QLPlugin.ico and the plugin-centric architecture), but there's no visible documentation or automated tests for plugin developers. New contributors extending functionality need clear guidance on plugin testing, manifest validation, and integration points.

• [ ] Document plugin architecture in a new docs/PLUGIN_DEVELOPMENT.md file
• [ ] Create a PowerShell script (Build/validate-plugin.ps1) to validate plugin manifests and dependencies
• [ ] Add unit test project for plugin loader/registry (if not present)
• [ ] Reference Dependencies/Config snippet in documentation with actual plugin examples
• [ ] Add plugin validation step to .github/workflows/msbuild.yml

Implement CODE_OWNERS file with plugin ecosystem mapping

The repo structure suggests multiple file preview handlers (images, documents, etc.), but there's no CODEOWNERS file to clarify ownership boundaries. This makes it unclear which maintainers own specific preview handlers or plugin categories, causing contribution friction and review delays.

• [ ] Create .github/CODEOWNERS file mapping plugin directories to maintainers
• [ ] Define code owners for Build/ assets and AppxManifest.xml configuration
• [ ] Establish owners for .github/workflows/ CI/CD processes
• [ ] Document in CONTRIBUTING.md how to find the right reviewer using CODEOWNERS
• [ ] Reference in PULL_REQUEST_TEMPLATE.md to guide contributors to correct reviewers

• Add unit tests for C# preview handlers (no test directory visible in top 60 files)—create a QuickLook.Tests/ with NUnit or xUnit tests for image, document, and archive preview logic.
• Document the plugin architecture in a CONTRIBUTING.md—currently no visible plugins/ directory structure or onboarding docs for adding custom format handlers; clarify the entry points and API contracts.
• Create a diagnostic/troubleshooting guide for shell integration failures—capture common issues (shell extension not registering, permissions, Windows version compatibility) in a TROUBLESHOOTING.md with reproduction steps and fixes.

The codebase has significant security concerns related to hardcoded cryptographic material stored in the repository. The presence of SSL/TLS private keys (sideload.key, sideload.pfx) and certificates is a critical issue requiring immediate remediation. Additional concerns include lack of visible dependency management documentation and asset integrity verification. Without detailed code review of the application logic, potential injection vulnerabilities cannot be fully assessed. The project should implement secure secrets management, automated dependency scanning, and cryptographic asset verification before production deployment.

• High · Hardcoded SSL/TLS Certificates and Keys in Repository — Build/sideload.crt, Build/sideload.key, Build/sideload.pfx. The repository contains hardcoded SSL/TLS certificates and private keys (sideload.crt, sideload.key, sideload.pfx) in the Build directory. These files should never be committed to version control as they can be used to impersonate the application or perform man-in-the-middle attacks. Fix: 1. Immediately revoke these certificates. 2. Remove the files from git history using git filter-branch or BFG Repo-Cleaner. 3. Store certificates/keys in secure credential management systems (Azure Key Vault, GitHub Secrets, etc.). 4. Add *.key, *.pfx, and *.crt to .gitignore. 5. Use environment-specific certificate management for builds.
• Medium · OpenSSL Configuration File in Repository — Build/openssl-sign.cnf. The Build/openssl-sign.cnf file is present in the repository. While configuration files are less sensitive than keys, they may contain signing instructions or reference sensitive data that could aid in reverse engineering the signing process. Fix: Review the contents of this file. If it contains sensitive signing configurations, move it to secure build infrastructure. Consider moving OpenSSL configurations to build-time injected secrets rather than repository artifacts.
• Medium · Potential Insecure Asset Handling — Build/Assets/, QuickLook.Appx/Images/. The codebase contains numerous image and asset files without evidence of integrity verification. If these assets are loaded from external sources or can be modified, they could be exploited for code injection or malware distribution. Fix: 1. Implement cryptographic integrity verification (SHA-256 hashing) for all assets. 2. Sign assets with code-signing certificates. 3. Validate asset integrity at runtime before loading. 4. Use content security policies for image loading.
• Medium · Missing Dependency Manifest Information — Repository root / Package dependencies. No Package.json, requirements.txt, pom.xml, or other dependency manifest files were provided in the analysis. This makes it impossible to verify that all dependencies are up-to-date and free from known vulnerabilities. Fix: 1. Provide complete dependency manifests for all languages used. 2. Implement automated dependency scanning with tools like GitHub Dependabot, Snyk, or OWASP Dependency-Check. 3. Establish a process for regular dependency updates and security patching. 4. Use Software Composition Analysis (SCA) tools in CI/CD pipeline.
• Low · Insufficient Security Documentation — Repository root. While PRIVACY.md exists, there is no dedicated SECURITY.md file documenting security policies, vulnerability disclosure procedures, or security best practices for contributors. Fix: Create a SECURITY.md file that includes: 1. Security policy and guidelines. 2. Vulnerability disclosure/reporting procedures. 3. Supported security patch versions. 4. Security contact information. 5. Known security considerations for end-users.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.