# 08 — UI WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:TitleBar`, a thin classic **Menu bar** (file-level operations), and a left **`ui:NavigationView`** (`PaneDisplayMode="LeftFluent"`) as primary navigation. Light/Dark/System themes via `ApplicationThemeManager` + `SystemThemeWatcher`; Mica backdrop on Windows 11 with automatic solid fallback on Windows 10. All XAML follows `16_WPFUI_SYNTAX.md` — that doc is mandatory reading before writing views. ## Shell ``` ┌────────────────────────────────────────────────────┐ │ ⬡ FrameLedger — □ ✕ │ ← ui:TitleBar (Mica, Snap Layouts) │ File Tools Help │ ← classic Menu row (Fluent-styled) ├───┬────────────────────────────────────────────────┤ │ ▦ │ │ │ 🎮│ │ │ ⇄ │ NavigationView content │ │ ≡ │ (pages via INavigationService) │ │ │ │ │ ⚙ │ [InfoBar area · SnackbarPresenter] │ └───┴────────────────────────────────────────────────┘ status: Agent state shown as a pill in TitleBar trailing content + Dashboard card ``` **NavigationView items:** Dashboard · Games · Compare · Logs — `Settings` lives in `FooterMenuItems`. Icons from `SymbolIcon` (Fluent System Icons; pick from the `SymbolRegular` enum — see 16 §Icons). **Menu bar** - **File:** Add game… · Import library (Steam / GOG / Epic / itch.io) · Export ▸ (Session CSV / Session JSON / Chart PNG) · Exit - **Tools:** Agent status… · Update detection rules · Vulkan layer registration… · Open data folder · Database maintenance… - **Help:** Check for updates · Report a bug… · Documentation · About FrameLedger (App / Developer / Third-party licenses tabs) The Menu sits in its own row **below** the TitleBar (never inside the drag region — 16 §Gotchas). > **Menu bar as of 2026-09-14 (P4 PR-3).** File ▸ Export is the submenu this section specifies — Session CSV / > Session JSON write the session last selected on a Sessions tab or opened in a summary window > (`Services/SessionSelection`, `SessionExportService` over the summary window's own writers; no selection says > so in the strip), Chart PNG opens that session's summary window, where the plot is. Help ▸ Documentation opens > the README (`IssueLink.Documentation`; `docs/` is developer-facing). Help ▸ Report a bug… runs > `BugReportFlow` (`10_LOGGING` §Bug report flow steps 2–4). Tools ▸ Update detection rules is PR-1's. **File ▸ > Import library… is PR-4's** (`ImportLibraryFlow` → the review checklist `ImportReviewPrompt` / `Dialogs/ImportReviewContent`, > a `DataGrid` with a tick column like Compare's picker — store, game, the executable to add, a note for > "already in the library" / "no executable found" / "guessed — check it"; Add selected lands every row hooking > off and shows the Games page; `05_DETECTION` §Platform signatures built note). **Help ▸ Check for updates is PR-5's** (`Update/UpdateService.CheckInteractivelyAsync`, the > dialogs of `11_UPDATER` §Flow; a downloaded update is the shell's persistent InfoBar with the one button, > disabled while a session runs — FR-12 — and "update available" is a tray balloon only while the window is off > screen). Still "later build": Tools ▸ Database maintenance. > > **Built 2026-09-13 (P3 PR-2): the shell, and only the shell.** `FluentWindow`, the TitleBar with the > Agent pill as trailing content, the Menu row (every item that a later slice builds says so in a 4 s > snackbar rather than doing nothing), the NavigationView with the four items and Settings in the footer, > the offline `InfoBar` with Retry, `SnackbarPresenter` and `ContentDialogHost`. The Dashboard shows the > Agent status card (`HelloAck`/`StatusAck`, every value `N/A` until answered); Games, Compare and Logs > are empty states; Settings has Appearance (theme + language, both persisted in `settings` — D16's > `ui.theme`/`ui.language`). The App starts `FrameLedger.Agent.exe --serve` beside itself when the pipe > is absent (`07_IPC` §Client behavior, 8 × 250 ms) and shows **Missing** when there is no Agent to start. > Measured on the dev box: first window at 1.3 s from process start (NFR-4's 2 s). ~~The tray is PR-8's.~~ > **Tray built 2026-09-14 (P3 PR-8b).** `Services/TrayHost` over `TrayViewModel` (no WPF in the view model, > `TrayViewModelTests`): the four icons are drawn at start (`TrayIcons`, a PNG inside an in-memory `.ico`, > because H.NotifyIcon 2.4.1 converts only file-backed image sources) and follow the pipe's session events — > ● when any running session is Tier 1, ◐ when sessions run and none is measured, ⏸ when the Agent reports > paused, the ring otherwise; the tooltip names the game. Menu: Open, Pause/Resume capture (one > `PauseCapture`/`ResumeCapture` request; the state shown is the `PauseAck`'s, never assumed), Agent status (the > Dashboard), Exit (a real exit through `ShellHost.Quit`, whatever minimize-to-tray says); a left click opens the > window. **Minimize to tray on close** hides the live window when `ui.minimize_to_tray` is on and a tray icon > exists (`WindowClosePolicy`); a language rebuild's old window is unaffected. **FR-3.8's balloon** — "Session > saved — — click to view" — is raised only while the window is off screen; on screen, the Dashboard's > snackbar carries the same event (one event, exactly one channel), and its click opens the summary window. > A safety event is never a balloon (`TrayViewModelTests` asserts it). Tools ▸ Agent status… and Tools ▸ Vulkan > layer registration… now navigate (Dashboard, Settings) instead of saying "not yet". **Tray (H.NotifyIcon):** icon states idle / ● capturing (T1 hooked) / ◐ recording only (T2 — nothing measured) / ⏸ paused; menu: Open, Pause/Resume capture, Agent status, Exit. Closing the window minimizes to tray when enabled. ## Notifications policy - **In-app, transient** (rules updated, export done, non-fatal capture warning): `ISnackbarService` snackbar, 4 s. - **In-app, persistent** (Agent offline, PawnIO missing, update downloaded): `ui:InfoBar` banner pinned above content with action button. - **System-level, app possibly minimized** (session saved with "View" action, capture error while in tray, update available): tray balloon/toast via H.NotifyIcon. - One event → exactly one channel; never duplicate the same event across snackbar *and* tray. **Exception — safety events are never toasts.** `CaptureRefused`, `SafetyUnhook`, and hook auto-disable get a **dedicated dialog or persistent `ui:InfoBar`** with the specific signal named in plain language ("Easy Anti-Cheat was detected in this game — FrameLedger will not inject into it"), a link to the safety documentation, and a one-click "capture without injection instead" action. These must never be dismissible-by-timeout: the user needs to understand why their data changed fidelity, or why capture stopped mid-session. ~~The "capture without injection instead" action is **Tier 2, which needs an elevated Agent**~~ — **rewritten 2026-08-28, and the button's whole meaning changed.** There is no no-injection measurement, so this action cannot be offered as an alternative way to measure. What it may offer is **recording the session anyway**: duration, hardware telemetry and the reason nothing was measured. It needs no elevation. **Label it for what it does** — "record this session without measuring it" — because a button that says "capture without injection" beside a refusal reads as a second measurement path, and the previous wording was corrected once already for exactly that. > **Built 2026-09-14 (P3 PR-8a).** `Services/SafetyNotices` subscribes to the pipe's events and turns > `CaptureRefused`, `SafetyUnhook` and `CaptureDegraded` into `SafetyNotice`s the shell renders as an > `ItemsControl` of `ui:InfoBar`s in `MainWindow` row 2, under the Agent banner and above every page — Error for > a refusal and an unhook, Warning for a degrade, `IsClosable="False"`, no timeout. The text is the `Safety_*` > family (`Safety_Refused_Named_Format` with the family and the signal, `_Unnamed`, `_CouldNotVerify`, > `Safety_Unhooked_Format`) followed on a refusal by `Notice_Refused_Recording` ("the session is still recorded — > duration and hardware telemetry — with every frame-derived value at N/A"). The one button is > `Safety_RecordWithoutMeasuring` on a refusal and Dismiss otherwise; it removes the notice and does nothing > else, because the Agent already records Tier 2 on a refusal (owner decision 2026-08-28) — the button is the > user's acknowledgement, not a second request. `CaptureError` (non-fatal) goes to the 4 s strip. The safety > documentation link lives on the Settings page's Capture section rather than in every notice. Tests: > `SafetyNoticesTests` (the three kinds, the sentence per refusal reason, the strip for errors, nothing for a > session event, dismiss only by the user). > > **Corrected 2026-09-14, after the owner saw a red bar with no way out.** WPF UI 4.3.0's `InfoBar` template has > **no `ContentPresenter`**, so the action button above — placed as the InfoBar's Content, the only dismissal once > `IsClosable="False"` removed the X — was never rendered. The view model was right and the screen was wrong. > `Styles/FrameLedger.xaml` now carries the upstream template verbatim plus the presenter (`16_WPFUI_SYNTAX` > §Gotchas), the same fix reaching the Agent-offline banner's Retry and the game page's Re-enable. Guarded by > `PagesLoadTests.TheInfoBarTemplateRendersItsContent`, which renders both templates and fails when upstream > gains a presenter — the signal to delete the copy. ## FPS display rule (global, FR-4.2 / CLAUDE.md rule 6) Reusable control `FpsReadout` (custom control styled with WPF UI theme brushes): - ~~FG **not** detected → `144 FPS`~~ — **"not detected" was two states, and they need two looks (2026-09-03, `03_METRICS` §Rung 0's qualifier):** - FG **measured `none`** (a hook ran and saw no frame generation — no producer exists yet) → `144 FPS`, nothing else. - FG **not measured** (`fg_mode = N/A`, every title today) → `144 FPS` as **Presented FPS**, with a mandatory qualifier chip from the runtime census: muted **"FG not observed"** when no frame-generation runtime was loaded in the process (tooltip: *"no frame-generation runtime was loaded; this number cannot include in-process generated frames — statically linked FSR3-FG and driver-level AFMF excepted"*), or a **⚠ warning chip "FG runtime loaded — may include generated frames"** naming the module when one was. Never the word "Native", never a factor, never `—`. - FG detected → **`62 → 118 FPS (×1.9 FG)`** — Native first and visually primary (`FontTypography="Subtitle"`), Displayed second, factor as a small accent chip. Tooltip: "Native: frames rendered by the game · Displayed: frames shown on screen incl. generated frames". - **FG identified, count refused (2026-09-14 — a fourth shape, `FpsReadoutKind.IdentifiedUncounted`).** `fg_mode` names a technology and `fg_factor` is NULL: the owner's Black Myth: Wukong and Onimusha rows, where the tags named DLSS-G and the token count did not resolve. Until this date the readout fell into the "detected" shape and printed **`N/A → N/A FPS (×0.0 FG)`** — a factor nobody counted — while the game page said `DLSS-G ` and the grid said N/A. Now: **`304 FPS`** as Presented FPS with a **⚠ warning chip "DLSS-G active — factor not counted"**, tooltip = the row's `fg_refusal` in plain words ("no application-frame token was counted", "the frame-generation state changed mid-session", …) plus "read it as Displayed, not Native"; the game page's measured row reads **`DLSS-G · factor not counted`**; Displayed and FG× say `N/A` (no factor exists, and it is not a measured none). Never the word "Native", never a factor. The `fg_runtime_loaded` chip also **names the module** now (`FG runtime loaded (sl.dlss_g.dll) — may include generated frames`) from `fg_runtime_census`, as this rule always asked. `FpsPresentation.FrameGenerationLabel` is the one place the page and the live card build the label. - Tables get three columns (Native / Displayed / FG×); Displayed and FG× render `—` when `fg_mode = none` and **`N/A` when it is not measured** — the two are different negatives and the table must not collapse them. The Native column carries the Presented figure with its qualifier when FG is not measured. - Charts: Native series default; "Displayed" toggle appears only when displayed data exists (FR-5.4). ## Tri-state feature chips (RT / PT / RR) `TriStateChip` custom control (WPF UI has no Chip primitive — build on `Border` + theme brushes, 16 §Custom controls): **Yes** = filled (accent) · **No** = outlined · **N/A** = dashed outline, muted foreground. Suffix icon shows source: 🔍 detected · ✎ manual · ↧ inherited. Click → `ui:Flyout` to override (session-level) with "set as default for this game" checkbox (FR-8.3). Chips appear on session rows, session summary header, and game header. ## Screens All screens are `Page`s registered with the navigation page provider and navigated via `INavigationService` (16 §Navigation). ViewModels via CommunityToolkit.Mvvm, injected through DI (`INavigableView` pattern). ### Dashboard - Agent status `ui:CardControl` (state, capability badges as `InfoBadge`: telemetry source, Vulkan layer, ~~ETW fallback~~, PawnIO/CPU-temp, elevation — Repair button on error). - **Live capture card** (visible during capture): game name, **tier badge**, elapsed, live `FpsReadout` (5 s rolling), **measured** `renderW×H → outputW×H` with upscaler + quality, RT-active dot, CPU/GPU temp, per-process VRAM, sparkline (last 120 s) fed by `SessionProgress`. Tier 1 shows measured settings — this is the payoff of hooking and should read as facts, not guesses. - Recent sessions list (last 10 across games) → click opens session summary. - Totals strip: games tracked, total playtime, sessions this week (`ui:Card` row). > **Built 2026-09-14 (P3 PR-5): the Agent card, the live card, the recent list, the totals.** The live card > is `LiveCaptureViewModel` over the pipe's `SessionStarted` / `SessionProgress` / `SessionCompleted` > (marshalled through the captured `SynchronizationContext`): game, tier badge, elapsed, the `FpsReadout` at > 1 Hz under the display rule (Presented FPS with its census chip until frame generation is measured), the > measured `renderW×H → outputW×H` with upscaler + quality, the RT chip, GPU/CPU temperature, per-process VRAM. > The sparkline is PR-6's. Recent = `ISessionRepository.ListRecentAsync(10)` with game names; a completed > session reloads the lists (the row is in SQLite, `07_IPC` §Client behavior). Totals = the library's games, > `SummariseByGameAsync` playtime, `CountSinceAsync(now − 7 d)`. Capability badges and the Repair button are > PR-8's with the Agent section. ### Games (grid → detail) - `GridView`-style panel of cover cards (`ui:CardAction`): name, platform badge, engine badge, total playtime, last played, mini trend sparkline (avg Native FPS last 10 sessions). Sort/filter/`ui:AutoSuggestBox` search. - **Game detail:** - Header: cover, name, publisher, version, platform, engine+version, API + Present Mode of last session, `FpsReadout` (lifetime avg), TriState chips, Edit button. - **Two clearly separated rows** (`05_DETECTION` §Capability hints — conflating these was the old design's core mistake): - **Supports** — greyed capability chips from files on disk ("Supports DLSS-G", "Supports XeSS"). Static inference. - **Last session measured** — accent chips with real values ("DLSS Quality · 1440p → 2160p", "Frame Generation DLSS-G ×1.9", "Ray Tracing: Yes"). Measured. - **Hooking control** (`ui:CardControl` with `ToggleSwitch`): off by default. Turning it on opens the consent dialog (FR-2.1). When the static anti-cheat pre-scan blocked it, the switch is **disabled** with the reason shown inline and no way to force it. When auto-disabled after crashes, an `InfoBar` explains and offers manual re-enable. > **Built 2026-09-14 (P3 PR-5): the grid, the detail page's header, the two rows, the hooking control and > the Sessions tab.** Grid: `ui:CardAction` cards with platform / engine / hooking badges, sessions, playtime, > last played (the sparkline is PR-6's); search and sort in memory; FR-1.1 by File ▸ Add game…, the page's > button, or an `.exe` dropped on the page (a `.lnk` needs the shell-link reader, later); FR-1.4 through > `Wpf.Ui.Controls.MessageBox` with **Keep sessions / Delete sessions too**, revoking consent over the pipe > FIRST when it was on. Detail: header (name, publisher · version · store · engine, last session's date and > API, the last hooked session's `FpsReadout`, the three chips resolved with the annotation and the game > default — `Application.TriState.TriStateResolution`), Edit… (FR-1.3, a `ContentDialog` badging detected > fields), **Supports** (from `capability_flags`; ~~empty until P4's scan writes it, and the card says so~~ **written by the Agent's detection sweep since P4 PR-1, 2026-09-14** — the rule ids as product names via `CapabilityNames`, "not scanned yet" only until the Agent's next tick) beside > **Last session measured** (upscaler · resolution, frame generation, the non-N/A chips — accent pills, from the > hooks). Hooking: the toggle is `OneWay` from the row and its command runs `HookingConsent`; a refusal, a > mismatch or a failure is a persistent `InfoBar` on the page (never a toast); a blocked row disables the > switch with `Safety_Blocked_Toggle_Format` inline; an unverified pre-scan leaves it enabled and says so; > auto-disabled shows `Safety_AutoDisabled_Format` with the re-enable button. Sessions tab: the `DataGrid` of > FR-6.1 — every Tier-2 cell that is Tier-1-only reads `N/A`, a measured-none Displayed / FG× reads `—`, both > with tooltips. Frametime / Distribution / Trend / Sensors / Latency say which build brings them (PR-6, PR-7). > `PagesLoadTests` loads every page and both control templates under the real theme dictionaries on an STA > thread, so a binding typo is red in CI rather than a `XamlParseException` at first navigation. - Tabs (WPF `TabControl`, Fluent-styled): 1. **Sessions** — `DataGrid`: date, duration, **tier badge (T1/T2)**, Native, Displayed, FG×, 1% Low, 0.1% Low, resolution + upscaler, max GPU temp, API, chips, ⚠ crash badge, tags. Row → Session summary. Multi-select → "Compare". Tier-2 rows render `—` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why. 2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis). 3. **Distribution** — FPS histogram + percentile curve of selected session(s). 4. **Trend** — metric-over-date line (selector: Native avg / Displayed avg / 1% Low / 0.1% Low / max GPU temp), vertical **hardware-change markers** with tooltip "GPU driver 572.16 → 576.02" (FR-6.3). 5. **Sensors** — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series. 6. **Latency** *(Tier 1 + Reflex only)* — PC latency timeline, avg/p95. > **Built 2026-09-14 (P3 PR-7): tabs 2–6.** Frametime and Distribution show the session selected in the > Sessions tab (the same `FrametimeChart` / `DistributionChart` as the summary window; a Tier-2 or > retention-swept selection says why there is nothing). **Trend**: `Charts/TrendSeriesBuilder` — one point per > hooked session oldest first under the selector (Average = Native where frame generation was measured and > Presented where it was not, the note beside the chart says so; Displayed only where measured; the lows; max > GPU °C), FR-6.4's exclusion of `settings_changed_midsession` sessions by default with the toggle and the > excluded count, and FR-6.3's markers — labelled dashed lines wherever two consecutive sessions' hardware > snapshots differ in GPU driver, GPU, CPU, display mode or OS ("GPU driver: 572.16 → 576.02"). **Sensors**: > GPU core / hotspot °C, load % and power W (right axis) on one plot; VRAM on another with the game's own > per-present `vram_proc` (a held 1 Hz sample) and the adapter-wide `vram_adapter` sensor as two > differently-labelled series. **Latency**: the `latency_us` blob with the stored avg / p95 lines, shown only > when Reflex reported (`reflex_active`); otherwise the tab says so. ### Session summary (secondary `FluentWindow`, also the post-session toast target) Stat cards (Avg uses `FpsReadout`, Median, 1% Low, 0.1% Low, Min/Max, σ, stutter %, duration), TriState chips, API/PresentMode/upscaler line, crash `InfoBar` (Severity=Error) when `crashed`, frametime chart, sensor strip, tags/notes editor, Export buttons. > **Built 2026-09-14 (P3 PR-6).** `Windows/SessionSummaryWindow` (a secondary `FluentWindow` with its own > `ContentDialogHost`), opened from a Sessions-tab row (double-click or Open) and from the Dashboard's recent > list. Stat cards read the STORED aggregates — never recomputed — with the lows labelled *(presented)* when > frame generation was not measured (`03_METRICS`); a Tier-2 session shows N/A cards, a sentence, and no > charts. Chips resolve through `TriStateResolution` and click into FR-8.3's dialog (`TriStateOverridePrompt`: > measured / Yes / No / N/A, "also this game's default"); the override lands on `session_annotations`, the > measurement stays, clearing restores it. Bars: crash (`Error`), safety unhook (`Warning`). Charts > (`Charts/`): `SessionSeriesLoader` decodes the blobs once — cumulative time, the generated and gap bits, the > application-frame view with `Domain.Metrics.StutterDetector` over it (the stored count's own rule), segments > mapped from frame index to seconds, sensors aligned to `t_ms` with −1 dropped; `FrametimeChart` draws the > application-frame series (the every-present series behind the FR-5.4 toggle, shown only when generated frames > exist), stutter markers coloured by cause where `pso_created` says PSO compile (FR-5.5; the VRAM-budget cause > has no per-frame source yet), the segment ribbon as alternating spans when there is more than one segment, > and GPU temperature / load on the right axis behind the sensor toggle; `DistributionChart` draws the FPS > histogram and the percentile curve (`Domain.Metrics.Percentile`, so the two lows are two points on it). > **FR-5.3:** `Charts/Decimator` — every bucket's min and max in order, ≤ 4000 points per series per draw, a > 500k-point series keeps its spike and its dip (`DecimatorTests`). Zoom and pan are ScottPlot's. > **FR-9:** `SessionExporter` — the CSV with `03_METRICS` §Export schema's column line verbatim and the `#` > header block (tier, api, hardware, the tri-states with sources, the segments, the 1 Hz VRAM note), > InvariantCulture throughout, no rows for Tier 2; the JSON (`frameledger-session/1`: metadata, the row as > aggregates with N/A omitted, segments, the annotation); PNG through `Plot.SavePng`. Tags (comma-separated, > de-duplicated) and notes save to the annotation row. **FR-3.8** is an in-app notice on `SessionCompleted` > (saved / discarded); the tray toast with "View" arrives with the tray (PR-8). ### Compare Session picker (2–5, cross-game allowed) → overlaid percentile curves + stat table with best-value highlighting; FG columns always show Native and Displayed separately. Export PNG. **Mixed-tier guard (FR-6.2):** selecting sessions from different capture tiers shows a blocking `ContentDialog` explaining that they measured different things; proceeding stamps the chart with a tier legend and greys out metrics unavailable in the lower tier. Sessions with `settings_changed_midsession` carry a warning icon and are excluded from trend lines by default. > **Built 2026-09-14 (P3 PR-7).** `CompareViewModel` over the last 200 sessions across games: a `DataGrid` > picker with a checkbox column (Compare enabled at 2–5), the FR-6.4 warning icon per row; **Compare** asks > `IMixedTierPrompt` (a `ContentDialog`, default button Cancel) when the selection mixes tiers and compares > nothing on a decline; a comparison that proceeds carries `Compare_Mixed_Legend` as the plot's title and an > `InfoBar`. `CompareChart` overlays one percentile curve per hooked session (`Charts/PercentileCurve`, the > distribution tab's own); the stat table is one row per metric — Native, Displayed and Presented FPS as three > separate rows (never one column), Median, the lows, stutter time %, max GPU °C, duration — with the best > value of each row bold and accent-coloured (higher wins for FPS, lower for temperature and stutter; N/A is > never best), and a Tier-2 session's cells at N/A. Export PNG through `Plot.SavePng`. ### Logs Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:AutoSuggestBox`), pause-scroll; buttons: Open logs folder, Export bug bundle (routes to 10_LOGGING flow). > **Built 2026-09-14 (P3 PR-8a).** `LogsViewModel` over `Services/LogTail`: the newest file of the chosen source > (App / Agent) read with `FileShare.ReadWrite` — Serilog keeps it open — capped at the last 2 MB with the partial > first line dropped, refreshed every 2 s while the page is on screen (the page's Loaded/Unloaded start and stop > the timer) and never while paused; the level filter reads the `[HH:mm:ss.fff LVL]` prefix of 10_LOGGING's > template (continuation lines such as stack frames keep only under All); the search is a plain `ui:TextBox`, not > an `AutoSuggestBox` — there is nothing to suggest. The view is a read-only `TextBox` in Consolas that scrolls to > the end on every refresh unless paused. "Export bug bundle" is 10_LOGGING's step 2 and nothing more (see there). > The status line says shown / total / file. Tests: `LogTailTests`, `LogsViewModelTests`, and the page renders in > `PagesLoadTests`. ### Settings Sections per FR-10 using the WPF UI settings idiom: `ui:CardControl`/`ui:CardExpander` rows with `ToggleSwitch`, `ComboBox`, `ui:NumberBox` (numeric inputs — min session length, sensor interval, retention). Language switch applies immediately (09_I18N). Theme selector (Light/Dark/System) drives `ApplicationThemeManager` (16 §Theming). **Capture section (top, most important):** the global **hooking kill switch** (`ToggleSwitch`, prominent) with a one-line summary of what it does; a list of games currently hook-enabled with a per-game revoke; Vulkan layer registration state + Register/Unregister; a link to the safety documentation. Turning the global switch off must take effect immediately, including for the Vulkan layer. Agent section: elevation state with a plain explanation of what elevation *optionally* unlocks (CPU temperature, elevated-game attach — ~~ETW fallback~~, which no longer exists) and that it is **not required by any capture tier**; task state, Register/Repair/Remove task, "Start agent at logon", background capture toggle. Privacy: online-metadata opt-in with plain-language explanation. Legal: reopen documents. > **Built 2026-09-14 (P3 PR-8a), with three rows deferred to PR-8b and one to PR-9.** `SettingsViewModel` over > `Application.Settings.RegisteredSettings` (the registry of `06_DATA_MODEL` §Settings registry — every write is > one `settings` row, and a key the Agent reads gets the 4 s "Applied. The capture agent reads it at the next > session start" line, D16). **Capture, first:** the kill switch as a `CardExpander` whose header is the toggle > and whose state line says "All hooking is off" / "Per-game settings decide" — it is `hooking.kill_switch`, the > gate's fourth input (`CaptureSession` consults it at every 30 s re-scan, so a running measured session stops at > its next scan; nothing else needs pushing); the hook-enabled list is `games.hook_enabled` as the ledger has it, > and its per-row "Turn off" is `HookingConsent.DisableAsync` — `SetHookEnabled { enabled: false }` over the > pipe, the Agent clears the column, the App never writes a hook-state column (D15; `SettingsViewModelTests` > asserts the row is still enabled after a fake Agent acked); the Vulkan layer row reads > `HelloAck.VulkanLayerRegistered` and says "unknown" without a HelloAck; the safety link opens > `19_SAFETY_AND_ANTICHEAT.md` at the public repository in the user's browser (nothing is fetched). > **Recording:** minimum session length, sensor interval and raw-series retention as `ui:NumberBox`es bounded by > the registry; a value outside the range is refused in place (the previous value comes back, a warning names the > range, nothing is written); background capture as a toggle with the honest sentence (recorded, measured only if > hook-enabled and not Vulkan). **Agent:** the elevation state from `HelloAck.Elevated` with the paragraph above > (not required by any tier; unlocks CPU temperature through PawnIO and attaching to elevated games); the logon > task row says the scheduled task arrives with the tray build. **Window:** "Start FrameLedger with Windows" is > `Infrastructure.Startup.RunAtLogon` — this user's `HKCU\…\Run` value, quoted executable path, never HKLM — > and the Run entry is the truth the toggle loads from; "Minimize to tray on close" is stored now and honoured > when the tray exists. **Privacy:** `privacy.online_metadata`, off by default, with the network sentence. > **Updates:** `update.channel` is read by PR-5's updater (beta = GitHub pre-releases), and `update.auto_check` — the startup check, on by default — sits beside it. **Logging:** `log.debug` moves this app's `LoggingLevelSwitch` at > once; the Agent has no reader for the key yet, and the row says so. **Legal:** reopen is a "not yet" line > until PR-9's gate exists. ~~Register/Unregister the layer, Register/Repair/Remove the task~~ — PR-8b, with the > Agent flags they need. Tests: `SettingsViewModelTests` (seven cases), `RunAtLogonTests` (Infrastructure, under > a test's own value name), and the page renders in `PagesLoadTests`. > > **8b built 2026-09-14.** The Vulkan layer row gained **Register / Unregister** and the logon task row > **Register / Repair / Remove**; each button runs the Agent's flag as a child process (`IAgentTool` → > `FrameLedger.Agent.exe --register-vklayer` / `--unregister-vklayer` / `--install-task` / `--uninstall-task`) > and then re-reads the machine (`IMaintenanceState`: the HKCU key, Task Scheduler) — the text shown is what the > machine holds, never what the button assumed. Register is enabled only while the layer DLL is staged, the > registration is absent and ~~a game has hooking on~~ **a hook-enabled game references the Vulkan loader (P4 PR-2, > 2026-09-14: `HookedGameViewModel.UsesVulkan` from `capability_flags`)** (the same rule the Agent's reconciler > enforces on its own after every consent change and every sweep — the button is the repair tool, `12_BUILD` > §The Vulkan layer is not registered at install time); Repair appears > when the task's action names another path (a moved install). "Minimize to tray on close" is honoured. ### First-run flow 1. Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept. 2. Agent setup: runs **unelevated by default** — a short, honest paragraph explains that elevation is optional and unlocks CPU temperature and elevated-game attach. ~~and the Tier-2 ETW fallback. It must be explicit that **without elevation there is no Tier 2**~~ — **struck 2026-08-28: no tier needs elevation, so there is nothing to warn about here.** Capability check results shown afterwards. ~~with Tier-2 availability listed as its own badge~~ — there is no availability to report. 3. Hooking explainer: what Tier 1 vs Tier 2 means — **and it must be explicit that Tier 2 measures nothing**, because the honest version of this screen is the one where a user who declines knows what they are declining — and that hooking stays off until enabled per game. 4. Optional library import. > **Built 2026-09-14 (P3 PR-9).** `Windows/FirstRunWindow` around `Controls/FirstRunContent` over > `FirstRunViewModel`, shown by `ApplicationHostService` **before the shell** whenever `Services/LegalGate` > says so — a first run, or a document whose version moved — and by Settings ▸ "Reopen the legal documents" > in read-only mode. **(1) The gate:** the four documents ride in the assembly (`LegalDocuments`: `legal/EULA.md`, > the root `LICENSE` as the GPLv3 text, `legal/DISCLAIMER.md`, `legal/PRIVACY_POLICY.md`, embedded at build so the > App shows the text this build was reviewed with; HTML authoring comments stripped; `{{RELEASE_DATE}}` left for > `release.yml`), a list on the left, the text in a read-only box, "View on GitHub" per document, **one Accept** > that writes four `legal_acceptance` rows with each document's own `**Version:**` line (`GPL-3.0-only` for the > licence), and Decline, which ends the host — the shell never appears. Closing the window without deciding is a > decline. **(2) Agent setup:** the honest paragraph (unelevated by default; elevation optional, unlocks CPU > temperature and elevated-game attach, required by no tier) and the facts from `HelloAck` as they arrive — > state, version, telemetry source, overlay build, CPU temperature, elevated — N/A until the Agent answers. > **(3) The explainer:** the consent dialog's own reviewed Tier 1 / Tier 2 paragraphs (`Safety_Consent_Hooked` / > `_NotHooked`, so the two screens cannot drift), that hooking stays off until enabled per game, and that the > Disclaimer states the risk. **(4)** ~~the import placeholder (P4)~~ **since P4 PR-4 (2026-09-14) a real pointer: the stores' libraries are imported from File ▸ Import library… once inside, every row hooking off** (the step itself stays text — the review dialog needs the shell's dialog host, which the first-run window has not). D8 unchanged: the gate is not a consent > precondition. Tests: `LegalDocumentsTests`, `FirstRunViewModelTests` (required on empty, one Accept = four > rows at the documents' versions, a moved version re-shows only that document, decline/close write nothing, > read-only records nothing, the Agent facts), the two steps rendered in `PagesLoadTests`. > > **NFR-4, measured 2026-09-14 on the dev box (Debug build, warm disk):** the first window (the shell, or the > first-run window on a first run) is logged every run as "shown N ms after process start" — 1.3–1.5 s for the > shell across PR-2 to PR-8b's smoke runs and 0.83 s for the first-run window on PR-9's, under the 2 s ceiling; a 100-session game's list + annotations query is a few > milliseconds (`SqliteSessionQueryTests`, ceiling 500 ms asserted); charts draw at most `Decimator.DefaultBuckets × 2` > points per series per draw whatever the session size (`DecimatorTests` over 500 000 points), which is what keeps > pan/zoom interactive. The Win10 22H2 visual pass is the owner's (NFR-8, no VM here). ## UX rules - Empty states for every list ("No sessions yet — launch a tracked game and FrameLedger will do the rest"). - All destructive actions confirm via `Wpf.Ui.Controls.MessageBox` (async — 16 §Dialogs): delete game/sessions, DB maintenance. - Notifications strictly per the policy above (snackbar / InfoBar / tray). - Keyboard: NavigationView items Ctrl+1…5; grids fully navigable; Esc closes flyouts/dialogs. - No blocking dialogs during capture; errors surface as InfoBars/tray toasts. - Charts and stat numbers use culture-aware formatting per active UI culture (09); colors only from theme resources or the per-theme chart palette (16 §ScottPlot).