Repository map#
| Path | Responsibility |
|---|---|
src\Hotshot.Core |
Pure net10.0 settings, portable preference merge/persistence, filename tokens, history/search, hotkeys, and shared models. No Windows APIs. |
src\Hotshot.Capture |
GDI/window capture, image encoding, clipboard, monitor/window enumeration, and capture pixel handling. |
src\Hotshot.Recording |
Windows.Graphics.Capture, D3D11/Vortice, Media Foundation H.264/AAC MP4 encoding, and WASAPI/NAudio audio. |
src\Hotshot.Gif |
MP4 decoding, quantization, and managed GIF writing. |
src\Hotshot.Editor |
Reusable Win2D annotation UI, document model, rendering, and export. |
src\Hotshot.App |
Tray lifecycle, global shortcuts, capture overlay, WinUI settings/workspace, AI descriptions, native agent bridge, and updates. |
src\Hotshot.Mcp |
Separate stdio MCP companion; talks to the native app through a local named pipe. |
tests |
Unit suites, isolated/native integration harnesses, media fixtures, and UI Automation smoke checks. |
agents |
Coding-agent documentation, plugin/marketplace assets, launchers, and portable skills. |
build |
Logo/icon generation and installer, managed-portable, and update-feed packaging. |
.github\workflows |
x64/ARM64 CI and Release Please/package/publish automation. |
Keep portable logic in Core, Windows/media work in its corresponding library, and app coordination in App. See AGENTS.md for the repository's concise implementation guide.
Design and implementation rules#
Preserve the user experience#
Captures are silent: no automatic preview/editor window. Clipboard delivery comes before disk saving. Tray activation opens or focuses the filename-based workspace without selecting the newest capture.
Keep settings native and adaptive, with title-bar search, grouped cards, and automatic validated persistence. Prefer existing Windows Community Toolkit controls and helpers over inventing parallel UI patterns. Do not block the UI thread with encoding, disk access, or long-running work.
Show actionable errors. A protected, unavailable, or changed capture target must not turn into a different screenshot or a success-shaped fallback.
Follow the codebase#
Use the configured C# version, nullable annotations, file-scoped namespaces, and sealed classes by default. Reuse existing helpers and keep changes scoped to the requested behavior.
Win32 interop uses source-generated [LibraryImport] in project-specific Native*.cs files; COM, D3D, and Media Foundation use Vortice. Libraries must not contain .xaml files: build reusable library UI in code because unpackaged PRI merging is fragile. XAML is allowed in the app.
Capture coordinates are physical pixels. Maintain Per-Monitor V2 DPI behavior, including negative virtual-screen coordinates, mixed display scales, and target changes between enumeration and capture.
Protect data and permissions#
User data belongs in %AppData%\Hotshot, not the installer-owned %LocalAppData%\Hotshot directory. Keep persistence atomic, recoverable, and backward-compatible; never repair a settings/history problem by silently resetting user data.
Portable OneDrive preferences are a whitelist. Capture/runtime paths, microphone IDs, counters, layouts, project baseline IDs, cloud-AI enable/review choices, and all agent permissions stay local. Invalid shared files and conflicting edits must remain recoverable. A local OneDrive file is not proof of completed cloud transport.
Cloud image analysis and agent/history access are opt-in. Do not enable them through migration, roaming settings, a test fixture, or an agent request. Review/redaction must not leak private originals or old text metadata through a flattened export.
Do not add credentials, private screenshots, app-data dumps, generated binaries, or machine-specific paths to commits. Keep automatic update restarts behind the existing idle/unsaved-work checks.
Respect compatibility decisions#
Windows Community Toolkit's preview dependency is intentionally pinned for the split WinUI/Windows App SDK 2.x packages. Older stable Toolkit packages introduce conflicting App SDK 1.6 build targets; do not replace the pin without proving compatibility.
The MCP companion targets plain net10.0 to avoid unnecessary Windows SDK projection payload. The app uses the bundled Copilot runtime over stdio. Packaging removes an in-process-only alias only after verifying that its bytes match; do not replace this with an unchecked binary deletion or shared-runtime shortcut.