* 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>
36 KiB
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,SessionExportServiceover 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… runsBugReportFlow(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 checklistImportReviewPrompt/Dialogs/ImportReviewContent, aDataGridwith 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 of11_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 offlineInfoBarwith Retry,SnackbarPresenterandContentDialogHost. The Dashboard shows the Agent status card (HelloAck/StatusAck, every valueN/Auntil answered); Games, Compare and Logs are empty states; Settings has Appearance (theme + language, both persisted insettings— D16'sui.theme/ui.language). The App startsFrameLedger.Agent.exe --servebeside 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/TrayHostoverTrayViewModel(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 (onePauseCapture/ResumeCapturerequest; the state shown is thePauseAck's, never assumed), Agent status (the Dashboard), Exit (a real exit throughShellHost.Quit, whatever minimize-to-tray says); a left click opens the window. Minimize to tray on close hides the live window whenui.minimize_to_trayis 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 (TrayViewModelTestsasserts 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):
ISnackbarServicesnackbar, 4 s. - In-app, persistent (Agent offline, PawnIO missing, update downloaded):
ui:InfoBarbanner 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/SafetyNoticessubscribes to the pipe's events and turnsCaptureRefused,SafetyUnhookandCaptureDegradedintoSafetyNotices the shell renders as anItemsControlofui:InfoBars inMainWindowrow 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 theSafety_*family (Safety_Refused_Named_Formatwith the family and the signal,_Unnamed,_CouldNotVerify,Safety_Unhooked_Format) followed on a refusal byNotice_Refused_Recording("the session is still recorded — duration and hardware telemetry — with every frame-derived value at N/A"). The one button isSafety_RecordWithoutMeasuringon 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
InfoBartemplate has noContentPresenter, so the action button above — placed as the InfoBar's Content, the only dismissal onceIsClosable="False"removed the X — was never rendered. The view model was right and the screen was wrong.Styles/FrameLedger.xamlnow 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 byPagesLoadTests.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 →— "not detected" was two states, and they need two looks (2026-09-03,144 FPS03_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 FPSas 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 measured
- 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_modenames a technology andfg_factoris 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 printedN/A → N/A FPS (×0.0 FG)— a factor nobody counted — while the game page saidDLSS-Gand the grid said N/A. Now:304 FPSas Presented FPS with a ⚠ warning chip "DLSS-G active — factor not counted", tooltip = the row'sfg_refusalin 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 readsDLSS-G · factor not counted; Displayed and FG× sayN/A(no factor exists, and it is not a measured none). Never the word "Native", never a factor. Thefg_runtime_loadedchip also names the module now (FG runtime loaded (sl.dlss_g.dll) — may include generated frames) fromfg_runtime_census, as this rule always asked.FpsPresentation.FrameGenerationLabelis the one place the page and the live card build the label. - Tables get three columns (Native / Displayed / FG×); Displayed and FG× render
—whenfg_mode = noneandN/Awhen 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 asInfoBadge: 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), measuredrenderW×H → outputW×Hwith upscaler + quality, RT-active dot, CPU/GPU temp, per-process VRAM, sparkline (last 120 s) fed bySessionProgress. 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:Cardrow).
Built 2026-09-14 (P3 PR-5): the Agent card, the live card, the recent list, the totals. The live card is
LiveCaptureViewModelover the pipe'sSessionStarted/SessionProgress/SessionCompleted(marshalled through the capturedSynchronizationContext): game, tier badge, elapsed, theFpsReadoutat 1 Hz under the display rule (Presented FPS with its census chip until frame generation is measured), the measuredrenderW×H → outputW×Hwith 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,SummariseByGameAsyncplaytime,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:AutoSuggestBoxsearch.- 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:CardControlwithToggleSwitch): 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, anInfoBarexplains and offers manual re-enable.
- Header: cover, name, publisher, version, platform, engine+version, API + Present Mode of last session,
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:CardActioncards 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.exedropped on the page (a.lnkneeds the shell-link reader, later); FR-1.4 throughWpf.Ui.Controls.MessageBoxwith 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'sFpsReadout, the three chips resolved with the annotation and the game default —Application.TriState.TriStateResolution), Edit… (FR-1.3, aContentDialogbadging detected fields), Supports (fromcapability_flags;empty until P4's scan writes it, and the card says sowritten by the Agent's detection sweep since P4 PR-1, 2026-09-14 — the rule ids as product names viaCapabilityNames, "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 isOneWayfrom the row and its command runsHookingConsent; a refusal, a mismatch or a failure is a persistentInfoBaron the page (never a toast); a blocked row disables the switch withSafety_Blocked_Toggle_Formatinline; an unverified pre-scan leaves it enabled and says so; auto-disabled showsSafety_AutoDisabled_Formatwith the re-enable button. Sessions tab: theDataGridof FR-6.1 — every Tier-2 cell that is Tier-1-only readsN/A, a measured-none Displayed / FG× reads—, both with tooltips. Frametime / Distribution / Trend / Sensors / Latency say which build brings them (PR-6, PR-7).PagesLoadTestsloads 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 aXamlParseExceptionat first navigation.
- Tabs (WPF
TabControl, Fluent-styled):- 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. - Frametime — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
- Distribution — FPS histogram + percentile curve of selected session(s).
- 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).
- Sensors — temp/load/power/VRAM timelines per session; per-process VRAM and adapter-wide VRAM as separate, differently-labelled series.
- Latency (Tier 1 + Reflex only) — PC latency timeline, avg/p95.
- Sessions —
Built 2026-09-14 (P3 PR-7): tabs 2–6. Frametime and Distribution show the session selected in the Sessions tab (the same
FrametimeChart/DistributionChartas 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 ofsettings_changed_midsessionsessions 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-presentvram_proc(a held 1 Hz sample) and the adapter-widevram_adaptersensor as two differently-labelled series. Latency: thelatency_usblob 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 secondaryFluentWindowwith its ownContentDialogHost), 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 throughTriStateResolutionand click into FR-8.3's dialog (TriStateOverridePrompt: measured / Yes / No / N/A, "also this game's default"); the override lands onsession_annotations, the measurement stays, clearing restores it. Bars: crash (Error), safety unhook (Warning). Charts (Charts/):SessionSeriesLoaderdecodes the blobs once — cumulative time, the generated and gap bits, the application-frame view withDomain.Metrics.StutterDetectorover it (the stored count's own rule), segments mapped from frame index to seconds, sensors aligned tot_mswith −1 dropped;FrametimeChartdraws 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 wherepso_createdsays 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;DistributionChartdraws 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 with03_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 throughPlot.SavePng. Tags (comma-separated, de-duplicated) and notes save to the annotation row. FR-3.8 is an in-app notice onSessionCompleted(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).
CompareViewModelover the last 200 sessions across games: aDataGridpicker with a checkbox column (Compare enabled at 2–5), the FR-6.4 warning icon per row; Compare asksIMixedTierPrompt(aContentDialog, default button Cancel) when the selection mixes tiers and compares nothing on a decline; a comparison that proceeds carriesCompare_Mixed_Legendas the plot's title and anInfoBar.CompareChartoverlays 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 throughPlot.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).
LogsViewModeloverServices/LogTail: the newest file of the chosen source (App / Agent) read withFileShare.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 plainui:TextBox, not anAutoSuggestBox— there is nothing to suggest. The view is a read-onlyTextBoxin 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 inPagesLoadTests.
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.
SettingsViewModeloverApplication.Settings.RegisteredSettings(the registry of06_DATA_MODEL§Settings registry — every write is onesettingsrow, 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 aCardExpanderwhose header is the toggle and whose state line says "All hooking is off" / "Per-game settings decide" — it ishooking.kill_switch, the gate's fourth input (CaptureSessionconsults 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 isgames.hook_enabledas the ledger has it, and its per-row "Turn off" isHookingConsent.DisableAsync—SetHookEnabled { enabled: false }over the pipe, the Agent clears the column, the App never writes a hook-state column (D15;SettingsViewModelTestsasserts the row is still enabled after a fake Agent acked); the Vulkan layer row readsHelloAck.VulkanLayerRegisteredand says "unknown" without a HelloAck; the safety link opens19_SAFETY_AND_ANTICHEAT.mdat the public repository in the user's browser (nothing is fetched). Recording: minimum session length, sensor interval and raw-series retention asui: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 fromHelloAck.Elevatedwith 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" isInfrastructure.Startup.RunAtLogon— this user'sHKCU\…\Runvalue, 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.channelis read by PR-5's updater (beta = GitHub pre-releases), andupdate.auto_check— the startup check, on by default — sits beside it. Logging:log.debugmoves this app'sLoggingLevelSwitchat 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 inPagesLoadTests.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 anda game has hooking ona hook-enabled game references the Vulkan loader (P4 PR-2, 2026-09-14:HookedGameViewModel.UsesVulkanfromcapability_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
- Legal Gate (FR-11): four documents, scrollable, links to GitHub-hosted versions, single Accept.
- 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. - 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.
- Optional library import.
Built 2026-09-14 (P3 PR-9).
Windows/FirstRunWindowaroundControls/FirstRunContentoverFirstRunViewModel, shown byApplicationHostServicebefore the shell wheneverServices/LegalGatesays 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 rootLICENSEas 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 forrelease.yml), a list on the left, the text in a read-only box, "View on GitHub" per document, one Accept that writes fourlegal_acceptancerows with each document's own**Version:**line (GPL-3.0-onlyfor 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 fromHelloAckas 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 inPagesLoadTests.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 mostDecimator.DefaultBuckets × 2points per series per draw whatever the session size (DecimatorTestsover 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).