Files
frameledger/docs/08_UI.md
T
poli0981andClaude Opus 5 1776a22907 feat(app): Velopack, the updater with FR-12 as its shape, release.yml, and one VERSION source (P4 PR-5) (#174)
* feat(app): Velopack, the updater with FR-12 as its shape, release.yml, and one VERSION source (P4 PR-5)

The updater of 11_UPDATER behind an IUpdateClient port (VelopackUpdateClient over Velopack 1.2.0's
GitHub source; stable = releases GitHub does not mark pre-release, beta adds them): the startup silent
check 5 s after start for an installed copy with update.auto_check on, Help > Check for updates with
the dialogs and the six error rows, the background download (a checksum failure retried once), and the
apply -- refused while any session runs, Deferred until the last SessionCompleted, then Shutdown to the
Agent, the connection's relaunch held, the pipe watched until it drops, WaitExitThenApplyUpdates, the
host ended. Program.Main runs VelopackApp first; the uninstall hook stops the Agent, unregisters the
layer, removes the logon task and asks about the data folder.

The package id is FrameLedger.App, not FrameLedger: Velopack installs into and deletes
%LOCALAPPDATA%\<packId>, which with the documented id is the data folder holding ledger.db.

VERSION at the root feeds Directory.Build.props and the native CMake project; versioninfo-check
compares every binary against it. release.yml gates the tag against VERSION and CHANGELOG
(tools/release-notes.ps1), substitutes {{RELEASE_DATE}}, runs the identical gate, publishes, asserts
the published tree, packs, checksums and releases.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(app): the private constant's name, Velopack's copyright as its package states it, and the measured pack

- UpdateService: _idleState (IDE1006, the repository's private-field rule; dotnet format caught it).
- legal/licenses/velopack-MIT.txt and THIRD_PARTY_NOTICES: the copyright line is the package's own
  <copyright> field ("Velopack Ltd."), not a name written from memory.
- 12_BUILD / 13_CI_CD / CHANGELOG: vpk pack 1.2.0 run by hand over the published tree -- Setup 104 MB,
  VelopackApp.Run() verified in Program.Main.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 23:56:55 +07:00

36 KiB
Raw Blame History

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 SafetyNotices the shell renders as an ItemsControl of ui:InfoBars 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 Pages registered with the navigation page provider and navigated via INavigationService (16 §Navigation). ViewModels via CommunityToolkit.Mvvm, injected through DI (INavigableView<TViewModel> 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:NumberBoxes 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).