Wayfinder map: SnipIT Fluent Suite redesign

[aksOps]

Destination

A risk-cleared, decision-complete route for the SnipIT Fluent Suite redesign (pivoted 2026-08-13 from the earlier black-glass chromeless direction, on a user-supplied reference design): Fluent/WinUI visual language via .NET 9 WPF ThemeMode following system Light/Dark, zero added dependencies; a hub window (Capture / History / Library / Settings nav); an editor with persistent toolbar + Export; continuity capture per #21 (pinned overlay, chip bar, morph); trust layer per #24/#25 (filmstrip, shelf); machine-checked accessibility. Done when the remaining decisions are closed and a phased implementation spec is ready for /writing-plans.

Superseded by the pivot: "fully chromeless day one" (editor now has a persistent toolbar; summoned popup + ghost overlay demoted to power-user extras).

Notes

• Repo constraints: pure PowerShell 7.5+ / WPF / .NET 9, zero external deps, single-file distribution. Authoritative sources src/ + xaml/; never edit generated SnipIT.ps1; regenerate via Build-SnipIT.ps1. All UI changes must stay drivable through the TestAction seams. See AGENTS.md.
• Skills to consult per session: frontend-design (visual direction), mattpocock-skills:prototype (mocks — a RenderTargetBitmap screenshot driver already exists from the 2026-08-13 session), mattpocock-skills:grilling + domain-modeling (decision tickets), mattpocock-skills:research (research tickets).
• Standing preference: premium, interactive, accessible; accessibility guarantees must be machine-checked in the existing harness where possible, real Narrator/NVDA validation where not.
• Planning only: tickets resolve decisions. Implementation happens after handoff to /writing-plans.

Decisions so far

• Spike: prove the clean-crop-while-visible invariant (WDA_EXCLUDEFROMCAPTURE) — GO on real Win11: layered visible overlay accepted affinity 0x11 and CopyFromScreen came back clean; production must assert the call per-HWND with close-then-crop fallback; cross-machine bounds pending research.

• Research: WDA_EXCLUDEFROMCAPTURE documented guarantees and driver/DWM caveats — trustworthy on build 19041+ (DWM-composition enforcement, same-process included); pre-19041 silently degrades to WDA_MONITOR (black rectangle in crop) so gate on build + BOOL return with SW_HIDE fallback; IDD/virtual displays hide the overlay from the user; RDP unverified. Full findings: docs/research/wda-excludefromcapture.md on local branch research/wda-excludefromcapture.

• Research: UIA LiveRegion and AutomationPeer behavior in PowerShell-hosted WPF — feasible without custom peers: raise LiveRegionChanged via public RaiseAutomationEvent after each text change (element in window tree, not template; UI thread, window shown); no focus/activation gate documented; ListBox items announce selection + position free; RaiseNotificationEvent is the .NET 9 fallback. Findings: docs/research/wpf-uia-livesetting.md on local branch research/wpf-uia-livesetting.

• Spike: WPF Popup focus and per-monitor DPI viability for summoned tools — GO for Popup (no in-canvas pivot): real-input harness passed focus/typing/placement/dismissal on standalone and single-file builds identically. Mitigations required: nudge popup on owner move; explicit Escape + deactivate close handling for StaysOpen=false; Relative placement for keyboard summon. Side-finding: app silently runs SYSTEM_AWARE DPI (SetProcessDpiAwarenessContext denied under pwsh manifest) — tracked outside this map.

• Decide: morph architecture — two-window storyboard, single-HWND host, or cross-fade fallback — two-window storyboard chosen (SYSTEM_AWARE DPI kills the jump risk; single-HWND is the documented pivot); runtime degrade ladder gates WDA on build+BOOL with close-then-crop cross-fade; chip bar Copy·Save·Pin·Edit with live re-crop in v1; retake = reverse morph.

• Decide: filmstrip History model and snapshot label taxonomy — 9-type label taxonomy as proposed, 50-snapshot cap, text-only items, scrub blocked during draft; UndoStack/RedoStack collapse into indexed History.

• Decide: respawn shelf — retention, disk format, privacy stance — 5 captures, flattened PNG only, FIFO ring, opt-in OFF by default; shelf writes before preview takes bitmap ownership.

• Prototype: chromeless editor mock — destination bar, command popup, ghost overlay — resolved by user reference design: Fluent look, system Light/Dark, persistent toolbar; black-glass variants archived as the alternative direction.

• Spike: .NET 9 WPF Fluent ThemeMode under PowerShell host — GO, zero added dependencies: Fluent loads from the shared runtime, ThemeMode settable via reflection, Light+Dark verified; wiring rule = set window-level ThemeMode and bind window Background to ApplicationBackgroundBrush.

• Brand palette (user-locked, 2026-08-13, supersedes the earlier bench-brass note) — #035ba3 accent, #909496 neutral, #043d19 positive (storage meter), #a60707 destructive (reserved), #000000 text/ground; dark theme uses a true-black ground; white only as text-on-accent and light-surface necessity. Applied via Fluent accent resource-key overrides (prototype/editor-variants branch).

• Decide: hub window information architecture — nav as mocked; Scrolling card shown disabled ("soon"); hub is home, tray/hotkey stay the fast path and never slow capture.

• Decide: History/Library surface and storage consent — first-run consent card at first capture (amends Decide: respawn shelf — retention, disk format, privacy stance #25); shelf + Library are one disk store; declined = session-only with enable affordances.

• Decide: Fluent editor toolbar and command table — toolbar/props-row/keys locked per approved mock; ink swatches are content colors; one command table generates every surface.

• Decide: pin-to-screen surface behavior — drag/scale/opacity-wheel, double-click closes, unlimited pins, restart persistence only with the consent-gated store, Copy/Save/Edit/Close menu, fully keyboard-operable.

• Check: LiveRegion narration from the never-activated overlay (NVDA/Narrator) — all channels spoken in a live Narrator session (polite, assertive, NotificationEvent); overlay activation state is a non-issue; NVDA re-check deferred to the a11y validation phase.

• Decide: keyboard-capture state machine and narration wiring — parallel input machine writes the mouse path's fields; Tab cycles targets, arrows move (Shift 10px, Alt = edge), Enter/Esc through the shared commit path; terse polite narration, assertive only for commit/cancel; hints generated from the handler table.

Not yet specified

• Fluent restyle of settings/about/widget/tray surfaces — mechanics proven by the ThemeMode spike (Spike: .NET 9 WPF Fluent ThemeMode under PowerShell host #30); pure implementation work for the spec.

• A11y validation protocol (real screen-reader session script, high-contrast pass).

• Final phase ordering and the /writing-plans handoff package.

Out of scope

• Scrolling capture engine (auto-scroll + stitch) — hub shows a disabled card; the engine is a future map of its own (per Decide: hub window information architecture #31).

• Tray pet / crumple-fling gestures / sound cues — charm reads as toy against the premium goal.

• Smart edge-snap annotations via bitmap edge detection or OCR — beyond zero-dependency scope for this effort.

• In-situ settings editing (right-click loupe to tune, etc.) — low pain, whole-surface rewrite.

• Usage telemetry / personal-best stats.