Files
frameledger/docs/08_UI.md
T
poli0981andClaude Fable 5.1 e16185f60e feat(app): the first .resx family with its generator and gate, and the App shell -- Generic Host, FluentWindow, the Agent pill over the pipe, theme + language persisted (P3 PR-2) (#155)
resx: src/FrameLedger.App/Strings.resx + .vi + .ja (65 keys; ja machine-drafted,
marked `review`), tools/resx-gen.ps1 writing the committed Strings.Designer.cs (the
SDK-style WPF project runs no ResXFileCodeGenerator), tools/resx-audit.ps1 as
build.ps1 step 15: -SelfTest (11 fixture cases, 9 red) then live. Per family:
identifier keys, non-empty neutral values, EXACT key sets in vi/ja, Safety_* in ja
marked `safety: human review required` with the English verbatim (that is how "shown
as en until signed" is true by construction) or `safety: reviewed by <name>`, and the
accessor current. No family under src/ is red, not green.

App: Generic Host per 16_WPFUI §App bootstrap; FluentWindow with the Agent pill in
the TitleBar, the Menu row (unbuilt items say so in a snackbar), NavigationView with
Settings in the footer, the offline InfoBar + Retry, SnackbarPresenter,
ContentDialogHost. Theme (Light/Dark/System + SystemThemeWatcher) and language
(rebuilds the shell in the new culture) persisted in `settings` under D16's
ui.theme/ui.language through SqliteSettingsStore -- the App opens ledger.db directly
(06_DATA_MODEL §Writer ownership, D15). Services.AgentConnection is 07_IPC §Client
behavior as a state machine over PipeClient: 8 x 250 ms, start
FrameLedger.Agent.exe --serve beside the App when absent, Hello/GetStatus, keepalive,
the event stream, retry every 5 s. Dashboard shows the Agent card with N/A until
answered; Games/Compare/Logs are empty states. Serilog logs/ui-.log per 10_LOGGING.

Three things 16_WPFUI now records: MainWindow is transient with
ShutdownMode=OnExplicitShutdown and the host lifetime ending the process; the run is
one Task from a synchronous OnStartup (async void overrides are VSTHRD100 here); and
ApplicationThemeManager.Apply(..., updateAccent: true) must precede the first
window's XAML or the accent resources are missing at first Measure (measured:
XamlParseException 'SystemAccentColorPrimary').

tests/FrameLedger.App.Tests (16): every key resolves in en/vi/ja and the satellites
really load; the accessor's keys are the resx's; appearance settings round-trip; the
connection against an in-process PipeServer -- Missing with nothing to start,
Connected on Hello, Starting -> Connected through a launcher that brings the server
up, Offline then Connected again when it returns. First window measured at 1.3 s.

Docs corrected in place: 09_I18N (generator, audit as built, the ja Safety_* rule),
12_BUILD line 15, 13_CI_CD, CLAUDE.md (App is the shell; resx-audit exists),
08_UI §Shell built note, 16_WPFUI deviations + gotcha, 10_LOGGING ui log, HANDOFF
§P3 row 2 struck (Shared's family waits for PR-4 on purpose). CHANGELOG.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 12:45:40 +07:00

14 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).

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 (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.

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".
  • 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).

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.
    • 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.

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.

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.

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).

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.

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.

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).