Compare commits

...
Author SHA1 Message Date
poli0981andClaude Opus 5.5 fe14c4c0fc release: 0.1.0-beta.20 - the CHANGELOG section, release lines, HANDOFF's beta.20 section and owner-only item 16 (beta.20 PR-2)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-12, the
same evening as beta.19): "tung bản beta20 rồi đóng phiên hẳn". The release
carries #299: a Ren'Py game's engine version from the engine's own
renpy/vc_version.py (rules 2026.10.3, Privacy Policy 2.9).

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.20] - 2026-10-12, with its
  summary and "Updating from 0.1.0-beta.19" (Privacy 2.9 shown once; every
  game read again for its engine); tools/release-notes.ps1 -Version
  0.1.0-beta.20 extracts it (957 characters).
- The accuracy block's release line (legal/ACCURACY.md, embedded in README
  and the Disclaimer; accuracy-check green), README's release lines and
  count, LIMITATIONS' version.
- HANDOFF: beta.19's START HERE struck; the beta.20 section - the owner's
  two words, no new decision (the 2.9 wording was shown with #299), the
  traps (keyboxd's I/O error, the owner's live rules copied aside and back,
  looping a touched test class); owner-only item 16 (Bound Between Desks
  reads Ren'Py 8.5.0; Privacy 2.9 once; the ja string).

Gates run locally on this tree: accuracy-check, wiki-check (self-test and
27 pages), notice-check, test-artifacts, release-notes. The code is #299's,
whose tree passed ./build.ps1 (325 s) and CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 18:58:28 +07:00
poli0981andClaude Opus 5.5 4ae563c97e feat(detection): the engine version of Ren'Py games, read from the engine's own version file (beta.20 PR-1) (#299)
The owner asked (2026-10-12, after beta.19's Unity, Godot and RPG Maker
versions) for the version of Ren'Py games. The renpy rule had no version
extractor.

Ren'Py ships its engine as Python beside the game's launcher, and
renpy/vc_version.py names its release: version = '8.5.0.25111603', beside
branch, nightly, official and version_name. Measured read-only on the
owner's one Ren'Py install, Bound Between Desks (Steam): 109 bytes, the
same number the game's log.txt printed at its last start; the launcher has
no version resource (spike-notes §18).

- Rules 2026.10.3: renpy -> {"type": "renpy_build"}; the schema's enum of
  code-decided extractors gains it. Every entry is read again once.
- Domain: RenPyBuildFacts + RenPyVersion.Decide keep MAJOR.MINOR.PATCH,
  as Ren'Py names its releases (the fourth number is the build), source
  renpy_vc_version; VersionExtractorType.RenPyBuild; the evaluator leaves
  it to the detector, as the other code-decided types.
- Application: IGameFileProbe.ReadRenPyBuildAsync; StaticGameDetector
  makes the one second read for a Ren'Py match.
- Infrastructure: RenPyBuildReader reads the first 4 KiB of
  renpy/vc_version.py beside the executable, its version line only.
- App: the game page says "Ren'Py 8.5.0" and that it was read from the
  engine's version file (en/vi/ja, ja marked review); a Ren'Py row whose
  file names no version says "Not found in the game's files".
- Privacy Policy 2.9: §4's list of the version marks an engine keeps in
  its own files names Ren'Py's (legal-drift-history). The Legal Gate shows
  it once at the next update.
- The accuracy block (ACCURACY, README, DISCLAIMER), LIMITATIONS,
  05_DETECTION §Engine version - Ren'Py, 06_DATA_MODEL, 08_UI, CHANGELOG.
- HANDOFF: owner-only item 15 struck, passed 2026-10-12 (the owner's
  report, and the Agent's log for the removal: one check at 18:04:00 took
  three session-less entries); the rules-reseed trap gains the backup the
  session made of the owner's two rules files.

Through the shipped pipeline (StaticGameDetector over GameFileProbe, read
only): Bound Between Desks renpy 8.5.0 renpy_vc_version in 79 ms; Dialoop,
Plethora of Bullets 2, A Doll's Locket and City of Bones read as before.

Tests: RenPyVersionTests (the measured value; the build dropped; shapes
that are not a version), EngineBuildReadersTests (the measured file beside
the launcher; no file, a version_name only, past the bounded head),
StaticGameDetectorTests (one read for the matched engine),
GameDetailViewModelTests and FormatsTests (the page's words).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 18:41:13 +07:00
poli0981andClaude Opus 5.5 3e9028c139 release: 0.1.0-beta.19 - the CHANGELOG section, release lines, HANDOFF's beta.19 section and owner-only item 15 (beta.19 PR-5) (#296)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-12) asked for
four items; the train is #292 (the import never takes a helper; D56), #293
(Change executable... opens in the game's folder), #294 (Unity, Godot and RPG
Maker versions; rules 2026.10.2; Privacy Policy 2.8) and #295 (an uninstalled
game with no session leaves the library; D55), then the two follow-ups of
#295's review the owner asked for as separate PRs: #297 (one notice per check;
the Games page shows its newest read) and #298 (the presence probe's
unreadable-folder tests).

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.19] - 2026-10-12, with its summary
  and "Updating from 0.1.0-beta.18" (Privacy 2.8 shown once; every game read
  again for its engine; the removal switch to turn off first if wanted; an
  entry made for a helper is re-pointed by hand); tools/release-notes.ps1
  -Version 0.1.0-beta.19 extracts it.
- The accuracy block's release line (legal/ACCURACY.md, embedded in README and
  the Disclaimer; accuracy-check green), README's release lines and count,
  LIMITATIONS' version.
- HANDOFF: beta.18's START HERE struck; the beta.19 section - D55, D56, the
  existing entry not rewritten, the owner's two train instructions; the traps
  (a store's own pick can be a helper, substring helpers never overrule a
  store, Godot's string past the scan and Unity's FileVersion string, Exists
  answering false for what it may not see, the locked signing key, the
  mechanical ones, what the pre-merge review of #295 found, looping a touched
  test class, the rules reseed); owner-only item 15.

Release rehearsal: release.yml dispatched on the branch (run 38226132220)
green - FL_BUILD_ID from the clean checkout, buildid-check ok over 4 native
binaries, a 2.35 MB delta from 0.1.0-beta.18 (28 of 460 files patched).
The final tree passed ./build.ps1 (ALL GATES PASSED in 284 s).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 17:13:55 +07:00
poli0981andClaude Opus 5.5 59e8ea4967 test(infrastructure): a game folder Windows will not list is never gone (beta.19 PR-7) (#298)
The presence probe (#295, D55) decides whether an entry's executable is
gone — FileGone, the one answer that lets the Agent remove the entry — or
merely unreadable. File.Exists and Directory.Exists say false for what
they may not look at, so the probe asks listings: the file in its folder's,
a folder that reads as missing in its parent's, and a listing it is refused
is Unknown. The review of #295 found those two branches untested.

ExecutablePresenceProbeTests now denies the current user rights on real
folders and gives them back in a finally (the owner can always change the
access list):

- ListDirectory denied on the game folder: the executable there and a
  Gone.exe there are both Unknown, and Present again once it lists;
- ListDirectory + ReadAttributes denied on the game folder and
  ListDirectory on the library folder it is in: Directory.Exists says false
  for the game folder, and the probe still says Unknown.

Each skips (Assert.SkipUnless) when the process can list what it is denied
— a backup privilege enabled — rather than asserting something else.

Measured red on this machine: with the folder listing replaced by
File.Exists the first test fails (Present for a folder that will not list);
with the parent-listing check dropped the second fails with FileGone, the
answer that would have removed an installed game. Both restored.

FR-1.8 (02_SPEC) names the case.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 17:03:21 +07:00
poli0981andClaude Opus 5.5 89aae82432 fix(app): one check's removals are said once, after one read of the library (beta.19 PR-6) (#297)
The Agent removes an uninstalled, session-less entry by itself since this
train (D55), and says each removal in its own GameRemoved event. One check
that removes several sends them milliseconds apart, and the Games page on
screen showed a snackbar and started a full library read for each. WPF UI
4.3.0's SnackbarService keeps one snackbar and shows every message at once
in it (Show(true) -> SnackbarPresenter.ImmediatelyDisplay, read from the
4.3.0 assembly), so only the last name stayed on screen.

The page now waits GamesViewModel.RemovalSettle (one second, over an
injected TimeProvider) after the first removal for the rest of the check,
reads the library once and says them in one notice: the game's name as
before, or the count, five names and how many more
(Games_Removed_Many_Format, Games_Removed_More_Format; en/vi/ja, ja marked
review). A removal heard during the read starts the next notice. The game
page's own handling of its entry is unchanged.

Tests: GamesViewModelTests — the single removal waits, then says the one
name; three removals in one check make one wait, one notice naming all
three and the remaining card; six name five and "1 more". Both over a
clock whose timers fire when the test says so.

Docs: 08_UI §Games; CHANGELOG's D55 entry.

fix(app): the Games page shows its newest read of the library (beta.19 PR-6)

Reads of the library overlap - a session that ends, an import, a removal -
and each awaits its executable checks off the UI thread. The read that
started first could finish last, its checks waiting on a slow drive, and
its older list was shown over the newer one: after the Agent removed a
game, an overlapping older read put the removed game's card back until the
next read.

Found by running GamesViewModelTests in a loop while the release train was
gated: one local run in about 165 failed. The pre-existing
ACardSaysWhetherItsExecutableIsThereAndWhy starts its own two reads (the
constructor's and an explicit one), and the first could be applied last.

GamesViewModel.LoadAsync now numbers each read (Interlocked) and shows it
only if no newer read began meanwhile. The executable check is injectable
(Func<string, bool>, default GameLibrary.ExecutableExists) so a test can
hold one read's check.

Tests:
- GamesViewModelTests.AnOlderReadThatFinishesLastIsNotShownOverANewerOne
  holds the first read in its check (bounded waits, so a broken test
  fails rather than hangs), lets a newer read list two games, then lets
  the first finish. It goes red without the guard ("found 1").
- ACardSaysWhetherItsExecutableIsThereAndWhy awaits the page's first read
  before adding the games it lists.

Measured: 10 runs of the class green and the whole App suite 599/599.

Docs: 08_UI §Games; CHANGELOG Fixed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 16:49:59 +07:00
poli0981andClaude Opus 5.5 c1a9e16cc4 feat(agent): a game that is no longer installed and has no session leaves the library by itself (beta.19 PR-4, D55) (#295)
The owner asked (2026-10-12) whether the Agent removes games whose executable
is gone, and if not, to remove them when no session was recorded. It did not:
D41 (2026-10-03) marked them Not installed and removed nothing. Owner decision
D55 amends it: removed after ten minutes, behind a Settings switch on by
default.

- UninstalledEntryPrune (Application/Watch), asked by DetectionSweep about an
  entry whose executable stayed unreadable after the relocator: the file gone
  at sweeps >= 10 minutes apart at the same path (counted in memory - a restart
  only delays it), the switch on (retention.remove_uninstalled_games, read at
  every sweep), not recording and no .partial waiting (the merge's busy test),
  and no anti-cheat block, exception grant or failed-trial mark (rule 2 and
  D38: an uninstall must not be how a block or "never again" disappears).
- ExecutablePresenceProbe tells what ExecutableIdentity.Read's null runs
  together: a drive not connected, nothing left of the path but the drive's
  root (a different disk under the same letter), a folder Windows will not list
  (asked of the parent's listing, since Exists answers false for both) - and
  FileGone, the only answer that removes: the file gone from a folder that is
  still there, or the game's folder gone from one that is.
- SqliteGamePrune: one DELETE that holds every stored condition in the same
  statement - same row, same path, in the library, NOT EXISTS a session, no
  block, no grant, no trial mark - so a session finalized meanwhile wins.
- IPC GameRemoved (additive): the Games page on screen reloads and says why in
  the snackbar; a game page showing that entry reloads into its not-found state.
- Settings > Data > Remove uninstalled games (off in a viewer like every
  Agent-read setting; its strip says the Agent reads it within 15 seconds).
  Strings en/vi/ja (ja marked review).
- Docs: 02_SPEC FR-1.8, 06_DATA_MODEL (writer ownership, settings registry),
  07_IPC, 08_UI, 19_SAFETY, the guide's data, screens and settings pages.

A self-review after the gate (before the merge): the presence probe asks the entry's own
drive (VolumeRoots.IsReady: the type first, so a dead share is never asked whether it is
ready) instead of listing every drive per entry; an entry the delete refused is asked again
after an hour (its sessions may since have been deleted) rather than never; 06_DATA_MODEL's
cross-reference names the 19_SAFETY section that exists. The vi and ja switch texts name the
pill as those languages show it (“Chưa cài”, “未インストール”).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:50:26 +07:00
poli0981andClaude Opus 5.5 a53ebee683 feat(detection): the engine version of Unity, Godot and RPG Maker games, read from their own files (beta.19 PR-3) (#294)
The owner's request of 2026-10-12. Rules 2026.10.1 gave: Unity's
pe_file_version stored UnityPlayer.dll's FileVersion string as it is
(2022.3.39.5118735 - the build number where the release letter belongs);
Godot's strings_regex scanned the executable's first 8 MiB while the
"Godot Engine v..." string sits 57-78 MB into both exports on the owner's
disk, so it never read one; both RPG Maker rules had version: null.

Measured read-only on 23 installs first (spike-notes section 17), then decided
in code as Unreal's is since beta.10:

- Rules 2026.10.2: unity_build, godot_build, rpgmaker_build - extractor types
  that take no parameter (the schema's enum beside unreal_build).
  StaticGameDetector makes one second read for the engine that matched;
  RuleEvaluator answers null for them as for unreal_build.
- Domain: UnityVersion (player ProductVersion, else the data file's header,
  else the player's numeric version), GodotVersion (a data pack's header,
  beside the executable or appended to it, else the executable's version
  while it is still Godot's; a zero patch dropped, as Godot names it),
  RpgMakerVersion (MZ/MV core-script header; the RGSS library Game.ini names
  -> XP/VX/VX Ace, its version or the one its name carries). New
  EngineVersionSource ids name the witness - and the maker.
- Infrastructure: UnityBuildReader, GodotBuildReader, RpgMakerBuildReader -
  version resources and at most a few kilobytes of any file; RPG Maker's files
  beside the executable or up to two folders above, as RpgMakerTitle looks.
- App: Formats.Engine(id, source) and EngineWithVersion - "RPG Maker MZ
  1.10.0", "RPG Maker VX Ace (RGSS 3.0.1)", "Unity 2022.3.39f1", "Godot 4.4.1"
  on the page, the subtitle and the card; the Engine version row says what
  each was read from, and "Not found in the game's files" once read. Strings
  en/vi/ja (ja marked review).
- Privacy Policy 2.8: section 4 names the version marks an engine keeps in its
  own files (the owner-approved wording), which also covers two reads that were
  never stated (UnityPlayer.dll's version, an RPG Maker title). The accuracy
  block, LIMITATIONS, 05_DETECTION, 06_DATA_MODEL, 08_UI and
  legal-drift-history say the same.

The shipped pipeline over the owner's installs (read-only): Unity 15 of 15,
Godot 2 of 2, RPG Maker 6 of 6, every one as measured; 24 ms to 4.1 s per
entry on the USB drive, nearly all of it the install's walk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:40:00 +07:00
poli0981andClaude Opus 5.5 3f798ad364 feat(app): Change executable... opens in the game's own folder (beta.19 PR-2) (#293)
The owner's request of 2026-10-12: the file dialog of Change executable...
opened wherever the last file dialog was, and the pick is almost always
another file of the same install.

GameFolder.StartFolder derives the folder from the row's path - the only
place one is stored: the install folder a store boundary names (InstallRoot:
steamapps\common\X, GOG Galaxy\Games\X, Epic Games\X, GamesInstalled\X), above
an Unreal package's <Project>\Binaries\Win64 where no boundary is recognised,
else the executable's folder; the nearest folder still there when that one is
gone (a Not installed entry); null for a drive that is not connected, where
Windows opens its last folder. It asks the file system, so the page runs it off
the UI thread. IGamePicker.PickExecutable takes the folder; Add game passes
none and keeps Windows' own choice.

Tests: GameFolderTests (each layout, a gone folder, an absent drive),
GameDetailViewModelTests.ChangingTheExecutableOpensThePickInTheGamesOwnFolder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:25:07 +07:00
poli0981andClaude Opus 5.5 38fdb6bd32 fix(import): a helper a store names is never the game, and an NW.js runtime outranks its launcher (beta.19 PR-1) (#292)
The owner's A Doll's Locket - Remake (itch 5085165, RPG Maker MZ) was imported as
Dolls Locket\notification_helper.exe. The pick was butler's verdict, taken as is:
butler stores a filtered verdict - the shallowest candidates, minus those whose
manifest asks for elevation - and does not rank what is left, so with the 213 MB
DollsLocket.exe launcher asking for administrator and the NW.js runtime a level
deeper in css\, the helper was the whole verdict (read from the owner's butler.db,
read-only).

- ItchLibrarySource skips a verdict candidate whose whole name is a runtime helper
  (ExecutableLocator.RuntimeHelperNames) or that sits in a Unity plugin folder; with
  nothing left the locator guesses and the review marks the row guessed. Whole
  names, not the locator's fragments: "node" is inside Nodebuster.
- ExecutableLocator ranks an executable beside nw.dll + package.json as an NW.js
  runtime (owner decision D56): below the Unity and Unreal layouts, above a name
  match. On the owner's disk it now picks css\Game.exe for Doll's Locket and
  swiftshader\Game.exe for HELLO, HELLO WORLD! (what D28 chose by hand); every other
  install it was run over picks what it picked before. notification_helper, nwjc
  and chromedriver join the helper fragments.
- LibraryImporter matches a store title to an entry by platform + store id as well
  as by path, so a corrected guess does not offer the same game a second time; the
  existing entry is re-pointed with Change executable... (nothing rewrites it).

HANDOFF owner-only item 14 (beta.18 on real hardware) is struck: passed 2026-10-08.

* fix(import): a store title is its entry by store id also when the entry's executable is inside the title's folder (beta.19 PR-1)

Found in a self-review after the stack's gate: the platform an import writes
is badged "detected", and the detection sweep refreshes it with what its own
rules find - an itch build that ships steam_api64.dll reads as Steam. Matching
the store id under the same platform only would then offer the same itch
title again beside its entry. The id now matches under the same platform, or
with the entry's executable inside the title's install folder; the same number
under another platform elsewhere is another store's numbering and stays a new
candidate (LibraryImporterTests.TheSameStoreIdInsideTheTitlesFolderIsTheSameTitleWhateverThePlatformReadsAs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 15:10:47 +07:00
poli0981andClaude Opus 5.5 6ed7851d90 test(capturehost): the Vulkan launch case asks the harness before the host runs; the target-exit case holds 15 s (beta.18 PR-5) (#290)
The two CaptureHost end-to-end races that failed beta.18's CI (both re-run green), taken at the owner's request
(2026-10-07) before the tag.

LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing failed #288 (run 37627351438) with
"session: RefusedByGuard / verdict: ModuleScanFailed  a module list came back incomplete". A hosted runner has the
Vulkan loader and no device, so the harness exits 77 with a "[SKIP]" line; the test read that line, or the session's
LaunchTargetExited, off the HOST's output. The runner is elevated, so the host starts the harness through
CreateProcessWithTokenW (UnelevatedProcess), which hands the child no stdout: the line never reached the host's output,
and when the guard's scan hit the dying harness the test failed instead of skipping. It now runs the plain harness
itself first (`--vulkan --hold-presenting 1`, bounded at 60 s), skips on 77 with the harness's own line, and otherwise
runs in full with no skip after the host - once the harness has presented here, every failure is real.
Measured: on this machine (a device) both cases pass, the Vulkan one in full; with the probe's ICDs hidden
(VK_DRIVER_FILES / VK_ICD_FILENAMES at a missing file, a throwaway edit) it skips in 0.66 s:
"[SKIP] vkCreateInstance failed (no ICD, or no surface extensions)".

WhenTheTargetExitsTheHostStopsAndSaysWhy failed #286 (run 37619719203) with TargetNotRunning: the host resolves its
target once, as it starts, and a host slower than the harness's 6 s hold found it gone (recorded since 2026-09-21).
The host prints nothing until its session ends, so there is no "attached" to wait for; the hold is 15 s, a margin.

The class's remark said CI does not run it; CI has, since 2026-09-06 - corrected in place. Docs: 13_CI_CD (the flake
tally), HANDOFF (beta.18's trap, struck to fixed), CHANGELOG [0.1.0-beta.18] (this ships in that tag).

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 23:39:14 +07:00
poli0981andClaude Opus 5.5 dadcacf1a0 release: 0.1.0-beta.18 - the CHANGELOG section with how to update from beta.17, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's beta.18 section and owner-only item 14 (beta.18 PR-4) (#289)
* fix(release): the natives carry the clean checkout's build id - read before the date substitution, handed to CMake, read back out of the binaries (beta.18 PR-3)

The chip from beta.17, open since beta.4 (HANDOFF §0.1.0-beta.4, "Found and NOT fixed"): the owner's Dashboard read
"Overlay build v0.1.0-beta.17-dirty", and beta.16's the same. The release run's own log says why:
"RELEASE_DATE = 2026-10-07 in 3 file(s)" and, 22 s later, "FL_BUILD_ID = v0.1.0-beta.17-dirty". release.yml writes the
release date into the tracked legal/*.md before the gate, and CMake's configure reads `git describe --dirty` after it.
CI's own checkout is clean (main's last run: "FL_BUILD_ID = 15b4c6b0ecc1").

- release.yml: a step before the substitution reads describe from the clean checkout (12 digits, as CMake does),
  refuses one that is already dirty or longer than 31 characters, and exports FL_BUILD_ID. After the publish,
  tools/buildid-check.ps1 reads it back out of the four natives that compile it.
- src/native/FrameLedger.Shm/CMakeLists.txt: the environment's FL_BUILD_ID is taken as given, after a check for the
  characters a C string literal carries without escaping; otherwise describe as before. Its comment said a released
  build was exact - "CI configures and builds once from a clean checkout" - corrected in place.
- tools/buildid-check.ps1 (new): looks for the id as the C string it is compiled as (characters + NUL) in each
  binary's bytes; nothing is loaded - loading the Overlay would run its DllMain. -SelfTest, eight cases, both
  directions, runs in the gate (build.ps1 'buildid-check').

Measured here: ./build.ps1 native with FL_BUILD_ID=b18-envtest.1+x_y printed "FL_BUILD_ID = b18-envtest.1+x_y", and
buildid-check over the four built DLLs: "ok - 4 native binaries carry 'b18-envtest.1+x_y'"; with FL_BUILD_ID='bad "id"'
the configure stopped ("holds a character no build id has"). On this branch's own describe (dirty, "+"), the tool
refused the id itself and found it in all four binaries.

Docs: 12_BUILD (§Release-time token substitution; gate 14c), 13_CI_CD (§release.yml), HANDOFF (§0.1.0-beta.4's bullet
struck, dated), CLAUDE.md (tools), wiki Releasing, CHANGELOG [Unreleased].

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

* release: 0.1.0-beta.18 - the CHANGELOG section with how to update from beta.17, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's beta.18 section and owner-only item 14 (beta.18 PR-4)

VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-07) asked for beta.18 - the two chips beta.17 left and
the page text that blends into the dark window; the train follows beta.17's: merge on green CI, then the signed tag
v0.1.0-beta.18 on the merge commit. wiki.yml publishes the wiki after the Release run succeeds.

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.18] - 2026-10-07, with its summary and "Updating from 0.1.0-beta.17";
  tools/release-notes.ps1 -Version 0.1.0-beta.18 extracts it (3948 characters).
- The accuracy block's release line (legal/ACCURACY.md, embedded in README and the Disclaimer; accuracy-check green),
  README's release lines and count, LIMITATIONS' version.
- HANDOFF: beta.17's START HERE struck; the beta.18 section - no new decisions; the traps (a page in the NavigationView
  inherits nothing; the accent is not in the theme dictionary; the gate's own refusals look like findings on the wire;
  Safety_Consent_* strings are versioned with the disclosure; a release's natives were -dirty by its own hand; the
  CaptureHost e2e flake met again); owner-only item 14.

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

* docs(handoff): the beta.18 traps name the Vulkan launch e2e race that failed #288's CI

On an elevated runner the harness starts through CreateProcessWithTokenW, its "[SKIP]" line never reaches the host's
output, and a guard scan that hits the exiting harness (ModuleScanFailed) fails the test instead of skipping it.
Re-run; the deterministic fix is a task.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 21:06:45 +07:00
poli0981andClaude Opus 5.5 1d0e8407bd fix(release): the natives carry the clean checkout's build id - read before the date substitution, handed to CMake, read back out of the binaries (beta.18 PR-3) (#288)
The chip from beta.17, open since beta.4 (HANDOFF §0.1.0-beta.4, "Found and NOT fixed"): the owner's Dashboard read
"Overlay build v0.1.0-beta.17-dirty", and beta.16's the same. The release run's own log says why:
"RELEASE_DATE = 2026-10-07 in 3 file(s)" and, 22 s later, "FL_BUILD_ID = v0.1.0-beta.17-dirty". release.yml writes the
release date into the tracked legal/*.md before the gate, and CMake's configure reads `git describe --dirty` after it.
CI's own checkout is clean (main's last run: "FL_BUILD_ID = 15b4c6b0ecc1").

- release.yml: a step before the substitution reads describe from the clean checkout (12 digits, as CMake does),
  refuses one that is already dirty or longer than 31 characters, and exports FL_BUILD_ID. After the publish,
  tools/buildid-check.ps1 reads it back out of the four natives that compile it.
- src/native/FrameLedger.Shm/CMakeLists.txt: the environment's FL_BUILD_ID is taken as given, after a check for the
  characters a C string literal carries without escaping; otherwise describe as before. Its comment said a released
  build was exact - "CI configures and builds once from a clean checkout" - corrected in place.
- tools/buildid-check.ps1 (new): looks for the id as the C string it is compiled as (characters + NUL) in each
  binary's bytes; nothing is loaded - loading the Overlay would run its DllMain. -SelfTest, eight cases, both
  directions, runs in the gate (build.ps1 'buildid-check').

Measured here: ./build.ps1 native with FL_BUILD_ID=b18-envtest.1+x_y printed "FL_BUILD_ID = b18-envtest.1+x_y", and
buildid-check over the four built DLLs: "ok - 4 native binaries carry 'b18-envtest.1+x_y'"; with FL_BUILD_ID='bad "id"'
the configure stopped ("holds a character no build id has"). On this branch's own describe (dirty, "+"), the tool
refused the id itself and found it in all four binaries.

Docs: 12_BUILD (§Release-time token substitution; gate 14c), 13_CI_CD (§release.yml), HANDOFF (§0.1.0-beta.4's bullet
struck, dated), CLAUDE.md (tools), wiki Releasing, CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:53:00 +07:00
poli0981andClaude Opus 5.5 a48e99b6c1 fix(app): every notice says what happened in words - the gate's own refusals, a familyless refusal, a re-scan that could not look, a stop mid-session (beta.18 PR-2) (#287)
The chip from beta.17 (found while writing the guide), measured on the Agent's own events. Three notices printed what
only the code knows:

- Disable all hooking: the gate labels its own refusals where a finding carries its family, so the notice read
  "kill switch was detected in this game (the global 'disable all hooking' switch is on (FR-2.4); ...). FrameLedger
  will not inject into it, and nothing overrides that." A game blocked before read "previously blocked was detected
  in this game (AntiCheatFile|NetEase Yidun|NEP2.dll)". The gate's refusals are said as the end now
  (Formats.EndReasonText: "All hooking is switched off in Settings, so nothing was measured."), never as a finding.
- A refusal no family names read "The anti-cheat guard did not hook this game: reason RefusedByGuard." The Agent sends
  the guard's reason for every refusal (RecordedSessionEvents.GuardReasonOf; beside a family only, until now), and the
  sentence is the guard's words ("... the game is 32-bit, and the hook runs in 64-bit games only."). An older agent's
  reads End_RefusedByGuard.
- A 30 s re-scan that could not look while the game ran read "Capture stopped: Access is denied. was detected while
  the game was running"; it reads Safety_Unhooked_Unnamed_Format ("... the game's process could not be opened ...").
- CaptureDegraded printed its reason raw and said the session went on: "The hook stopped (WriterSelfDisabled); the
  session continues without measuring." A stop ends the session (07_IPC). The notice is the end's sentence;
  Notice_Degraded_Unknown_Format names only a reason this build has no words for.

And the rest of the chip:
- Turning the kill switch on said "Applied. The capture agent reads it at the next session start."; a measured session
  stops at its next safety scan, within 30 s (CaptureOptions.ScanInterval), and Settings_KillSwitch_Applied_On says so.
- Turn off / the game page's switch / withdrawing an exception with no agent said "Nothing was enabled." - the enable
  path's words (Safety_Consent_AgentUnavailable, left as is: changing a Safety_Consent_* string's meaning would bump
  the consent disclosure). Agent_NotConnected_NothingChanged.
- The viewer (--data-dir, D52) left the user-mode exception option, the three Recording numbers and the update channel
  live; every setting the Agent reads is off there now, held by the registry (ViewerModeTests).
- 08_UI listed a "PawnIO missing" banner that was never built.

Tests, red on the unfixed code first (12 App, 1 Application):
- NoticesFromTheAgentTests builds each event as the Agent does - the gate's verdict (HookedCaptureGate, kill switch),
  the native facade's (AntiCheatVerdict.FromNative), RecordedSessionEvents.PublishReason, the wire's codec - walks
  every refusal and every stop, and refuses an enum's name, a requirement's id or "reason X" in any notice. The
  notices' tests had only raised events written by hand ("GuardBlocked", "HookFaulted"), which no Agent sends.
- RecordedSessionEventsTests.BothSafetyEventsCarryTheGuardsReasonWheneverItRefused; SettingsViewModelTests (the kill
  switch's two strips, Turn off); ViewerModeTests.EverySettingTheAgentReadsIsOffInAViewer and the channel's row;
  ReasonTextTests' familyless refusal now as the Agent sends it.

Strings: three new App keys and one Shared (Safety_Unhooked_Unnamed_Format, ja = the English until reviewed), one App
key renamed; en/vi/ja. Docs: 07_IPC (guardReason, CaptureDegraded), 08_UI (§Notifications policy, the viewer, the
kill switch's strip, PawnIO), HANDOFF (beta.17's list corrected in place), CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 20:12:26 +07:00
poli0981andClaude Opus 5.5 b42d94bf1d fix(app): page titles read in the dark theme - every page sets the text colour the navigation Frame does not pass (beta.18 PR-1) (#286)
The owner's screenshots of 0.1.0-beta.17 (2026-10-07, dark theme): every page's title and section headings - Dashboard,
Recent sessions, Games, Compare, Pick 2 to 5 sessions, Settings and its groups, Logs - near-black on the dark window.
beta.16's screenshot shows the same.

Cause: a page is shown in WPF UI's NavigationViewContentPresenter, which is a Frame, and Frame.Init sets
InheritanceBehavior.SkipToAppNow - the window's Foreground stops there. A TextBlock that sets no colour falls to the
default, which WPF UI 4.3.0's TextBlockMetadata overrides to Brushes.Black. Cards, grids and controls set their own in
their templates; the bare titles and headings did not (19 texts on six pages, 1.29:1). It came and went: a page on
screen during a theme switch did take the window's new colour, and each navigation makes a new page that does not.

- Pages/*.xaml: every Page root sets Foreground="{DynamicResource TextFillColorPrimaryBrush}".
- AccessibilityTests.EveryPageSetsItsOwnTextColour: every Page root in the App's XAML sets it. Red before: all six.
- PagesLoadTests.EveryTextIsReadableInBothThemes (Dark, Light): every surface hosted as the App hosts it - a page in
  the presenter, a window as itself, anything else in an unshown FluentWindow - and every text that shows >= 3:1 over
  the colour painted under it. Red before in Dark: the 19 titles and headings at 1.29:1; Light green.
- PagesLoadTests.Hosted puts a page in the presenter, so EveryTextFollowsAThemeSwitch checks the App's real host too.
  Until now it laid pages out straight in a window, whose colour they inherited - green over the black titles. Red
  before, both ways: a page made after the switch stayed black. It now pairs texts by their place in the tree and
  compares what shows (a switch re-applies the template of a DataGrid's collapsed scroll bar and select-all corner).
  An Appearance="Secondary" put back on one Settings text still turns it red, both ways.
- Visuals.UnderTheme switches as the App does: the accent resources derived for the theme from Windows' default accent,
  then the dictionary, and the application's own resources put back after. The accent is not in a theme dictionary, so
  a Light check measured the dark theme's link blue on the light window (1.9:1) - a colour the App never shows.
  ContrastTests uses it too; it passed systemAccentColor: true, which reads the machine's own accent palette.
- Docs: 16_WPFUI_SYNTAX (a theming bullet, a Gotchas entry), 08_UI §Contrast (the fifth hole), 14_TESTING (a page is
  measured in the Frame; a theme brings its accent), wiki App UI development, CHANGELOG [Unreleased].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 19:50:14 +07:00
poli0981andClaude Opus 5.5 15b4c6b0ec release: 0.1.0-beta.17 - the CHANGELOG section with how to update from beta.16, the accuracy block's release line, README's release lines, LIMITATIONS' version, HANDOFF's beta.17 section with D53-D54 and owner-only item 13 (beta.17 PR-5) (#285)
VERSION stays 0.1.0: the tag's numeric core. The owner (2026-10-07) approved the train end to end: merge on green CI,
then the signed tag v0.1.0-beta.17 on the merge commit. wiki.yml publishes the wiki after the Release run succeeds.

- CHANGELOG: [Unreleased] becomes [0.1.0-beta.17] - 2026-10-07, with its summary and "Updating from 0.1.0-beta.16";
  tools/release-notes.ps1 -Version 0.1.0-beta.17 extracts it.
- The accuracy block's release line (legal/ACCURACY.md, embedded in README and the Disclaimer; accuracy-check green),
  README's release lines and count, LIMITATIONS' version.
- HANDOFF: beta.16's START HERE struck; the beta.17 section - D53 (the wiki's source is the repository, published by
  wiki.yml), D54 (the guide is the wiki's End-user half, twelve pages), the traps (ui:TextBlock Appearance pins a brush;
  a Loaded class handler is not a load hook; the wiki's branch and the read-only default token; gating a stack from the
  main checkout), the findings left as tasks; owner-only item 13.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:55:24 +07:00
poli0981andClaude Opus 5.5 2c967b3d63 docs(wiki): the developer half of the wiki, built from the repository and published at each release (beta.17 PR-4, D53) (#284)
* docs(guide): the user guide looks things up too - the screens, every setting, troubleshooting, a glossary (beta.17 PR-3, D54)

The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D54):
the End-user part IS the user guide, one source - shown in the App under Help > User guide and, from PR-4, on the
wiki. Four pages join it after the FAQ, each written from the code it describes (labels, defaults, ranges and messages
read in SettingsPage.xaml, SettingsRegistry, Strings.resx and the view models):

- guide/07-screens.md - the badge and banners, every menu item, Dashboard, Games, a game's page, the session summary,
  Compare, Logs, the tray icon, keyboard and mouse.
- guide/08-settings.md - every setting the Settings page shows, in its order: what it does, its default, and which
  ones the agent reads.
- guide/09-troubleshooting.md - what you see, what it means, what to do: the agent, a game recorded but not measured
  (each "Why:"), N/A figures, "How it ended", updates, the database, the viewer, reporting a problem.
- guide/10-glossary.md - the words the App shows, A to Z.

guide/README.md lists them in the App's order (EmbeddedDocuments.GuidePages). The first run's "Your library" step named
"File > Import library... on the Games page"; File is the main window's menu and the Games page has no import button -
fixed in en/vi/ja (vi names the menu as shown, "Tep").

Tests (GuideDocumentsTests), each shown to bite on a deliberately broken page:
- EveryLinkToASectionNamesAHeadingOfItsPage - every section link, within a page, to another guide page, Limitations or
  a document, against the anchors the App's renderer gives the target (it replaces the one-anchor check);
- TheContentsListThePagesInTheAppsOrder;
- TheSettingsPageOfTheGuideNamesEverySetting - every Settings_*_Label the Settings page binds, in English;
- TheScreensPageOfTheGuideNamesEveryPageAndMenuItem - every Nav_* and Menu_* of the main window.
MarkdownRendererTests counts the guide's twelve pages.

Docs: CLAUDE.md and 08_UI ("eight short English pages" struck, the tests named; the consent dialog's button is "Keep
hooking off", not "Keep it off"), CHANGELOG [Unreleased].

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

* docs(wiki): the developer half of the wiki, built from the repository and published at each release (beta.17 PR-4, D53)

The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D53):
the wiki's source lives in the repository and the Wiki tab is a copy, published when a release is made; the End-user
half is the user guide (PR-3, D54). The Wiki tab existed with one placeholder page.

- wiki/: Home (two doors), _Sidebar, and eleven short developer pages - Developers (where to start, where status lives),
  Architecture (a mermaid diagram, the processes, the two tiers, a frame's way to the screen), Repository map, Build and
  test (the gates in one table), Contributor rules (the nine rules in plain words, what will never be built, every
  pull request), Capture pipeline, Metrics (and the display rules), Data and IPC, App UI development (the WPF UI traps,
  this train's two included), Releasing, Developer glossary. Each links to its full document and states no status.
- tools/wiki-build.ps1: names each page (a guide page after its first heading; guide/README.md is User-guide,
  LIMITATIONS.md Limitations), rewrites links between pages to page names and every other repository link to GitHub at
  -Ref, drops each page's first heading, writes _Footer.md naming the ref. Refuses a link to a missing file, folder or
  section, two sources for one page, a page nothing leads to, a sidebar out of the guide's order, a backticked path in a
  wiki/ page that names nothing, and a version written into a wiki/ page. -SelfTest: nine cases, both directions.
- build.ps1: the wiki-check gate after notice-check (self-test, then -Check).
- .github/workflows/wiki.yml: on workflow_run of Release (success, started by a pushed v* tag - a rehearsal never
  publishes) and by hand (ref, publish). Checks out head_sha, links at the tag, uploads the pages, and publishes with
  gh auth setup-git + a clone of <repo>.wiki.git + push HEAD:master, only when something changed. contents: write, since
  the repository's default token is read-only. Separate from release.yml so a wiki failure is never a red release and
  can be re-run.
- Docs: README (the wiki, both halves), docs/README.md (the wiki; "D1...D46" corrected), CONTRIBUTING (where
  documentation lives), CLAUDE.md (wiki/ and wiki-build), 12_BUILD (gate 13d), 13_CI_CD (wiki.yml, five repo-local
  workflows, the owner's wiki-editing setting), CHANGELOG [Unreleased].

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 10:18:43 +00:00
poli0981andClaude Opus 5.5 1722a4ef56 docs(guide): the user guide looks things up too - the screens, every setting, troubleshooting, a glossary (beta.17 PR-3, D54) (#283)
The owner (2026-10-07): "a complete wiki, concise and easy, split into End-user and Dev". Decided the same day (D54):
the End-user part IS the user guide, one source - shown in the App under Help > User guide and, from PR-4, on the
wiki. Four pages join it after the FAQ, each written from the code it describes (labels, defaults, ranges and messages
read in SettingsPage.xaml, SettingsRegistry, Strings.resx and the view models):

- guide/07-screens.md - the badge and banners, every menu item, Dashboard, Games, a game's page, the session summary,
  Compare, Logs, the tray icon, keyboard and mouse.
- guide/08-settings.md - every setting the Settings page shows, in its order: what it does, its default, and which
  ones the agent reads.
- guide/09-troubleshooting.md - what you see, what it means, what to do: the agent, a game recorded but not measured
  (each "Why:"), N/A figures, "How it ended", updates, the database, the viewer, reporting a problem.
- guide/10-glossary.md - the words the App shows, A to Z.

guide/README.md lists them in the App's order (EmbeddedDocuments.GuidePages). The first run's "Your library" step named
"File > Import library... on the Games page"; File is the main window's menu and the Games page has no import button -
fixed in en/vi/ja (vi names the menu as shown, "Tep").

Tests (GuideDocumentsTests), each shown to bite on a deliberately broken page:
- EveryLinkToASectionNamesAHeadingOfItsPage - every section link, within a page, to another guide page, Limitations or
  a document, against the anchors the App's renderer gives the target (it replaces the one-anchor check);
- TheContentsListThePagesInTheAppsOrder;
- TheSettingsPageOfTheGuideNamesEverySetting - every Settings_*_Label the Settings page binds, in English;
- TheScreensPageOfTheGuideNamesEveryPageAndMenuItem - every Nav_* and Menu_* of the main window.
MarkdownRendererTests counts the guide's twelve pages.

Docs: CLAUDE.md and 08_UI ("eight short English pages" struck, the tests named; the consent dialog's button is "Keep
hooking off", not "Keep it off"), CHANGELOG [Unreleased].

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 17:02:13 +07:00
poli0981andClaude Opus 5.5 b18d7dc80e fix(app): hide scroll bars reaches every scroller - a ScrollChanged class handler beside Loaded (beta.17 PR-2) (#282)
The owner's screenshot of 0.1.0-beta.16 (2026-10-07): with Settings > Window > Hide scroll bars on, the Dashboard still
drew its scroll bar while Settings did not.

Cause, read in dotnet/wpf: BroadcastEventHelper.OnBroadcastCallback raises Loaded only on elements whose
SubtreeHasLoadedChangeHandler is set, and FrameworkElement.ThisHasLoadedChangeEventHandler counts instance handlers,
style EventSetters, template triggers and FEF handlers - not EventManager class handlers. ScrollBarHiding (beta.14)
had one class handler on ScrollViewer.Loaded, plus a walk of the open windows when the toggle changes; the flag is
applied before the first window, so the walk never helped at start-up. WPF UI 4.3.0's ToggleSwitch, CheckBox and
ProgressRing templates carry a Loaded EventTrigger, so Settings' scroller loaded and was hidden; the Dashboard (cards,
text, borders) never loaded as far as the option knew.

- Services/ScrollBarHiding: a class handler on ScrollViewer.ScrollChangedEvent (handledEventsToo), calling the same
  idempotent Set. Every scroller raises it from its first layout, inside ContextLayoutManager.UpdateLayout, so the
  bar is gone before the first frame; the Loaded handler stays. Doc comment and App.xaml.cs comment corrected.
- ScrollBarHidingTests.AScrollerLaidOutWithNoLoadedEventIsHidden: red before (Auto).
- ScrollBarHidingTests.EverySurfaceShownWithTheOptionOnDrawsNoBar: every page navigated in WPF UI's presenter, the
  first run, About, the user guide, a session's summary and every dialog's content, each shown in a real window off
  the screen with the option on first. Red before: the Dashboard's ScrollViewer, Game detail's sessions DataGrid
  (horizontal), the first run's ListBox and MarkdownView, About's ScrollViewer, the user guide's ListBox and
  MarkdownView. Settings and Logs were already hidden (the control); the check requires Dashboard, Settings, Logs and
  the user guide to have something to scroll.
- ScrollBarHidingTests.WpfRaisesLoadedOnlyWhereASubtreeListensForIt: the harness against WPF - a scroller with its own
  Loaded class handler is not called holding a Border, and is holding a CheckBox.
- Docs: 08_UI §Settings (the false "reaches every scroller" struck and dated), 16_WPFUI_SYNTAX §Gotchas (a class
  handler on Loaded is not a load hook), 14_TESTING, CHANGELOG [Unreleased].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 16:40:17 +07:00
147 changed files with 6801 additions and 283 deletions

No files matched your search

+19
View File
@@ -116,6 +116,22 @@ jobs:
"dry_run=$($dry.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
Write-Host "$(if ($dry) { 'DRY RUN of' } else { 'releasing' }) $full (pre-release: $pre)"
# The Overlay's build id is `git describe --dirty` at CMake's configure
# (src/native/FrameLedger.Shm/CMakeLists.txt), and the next step edits tracked
# files: every release until beta.18 shipped "<tag>-dirty". So the id is read
# here, from the clean checkout, and handed to CMake through the environment;
# buildid-check reads it back out of the published binaries.
- name: Build id (the clean checkout)
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
$id = "$(git describe --always --dirty --abbrev=12)".Trim()
if ($LASTEXITCODE -ne 0 -or -not $id) { throw 'git describe failed' }
if ($id.EndsWith('-dirty')) { throw "the checkout is dirty before the release has touched it: $id" }
if ($id.Length -gt 31) { throw "build id '$id' is $($id.Length) characters; FlShmHandshake::buildId holds 31" }
"FL_BUILD_ID=$id" >> $env:GITHUB_ENV
Write-Host "FL_BUILD_ID = $id"
# 12_BUILD §Release-time token substitution: the effective date of a legal
# document is the date it ships. The only placeholder that survives into the
# repository, substituted here and nowhere else; the App embeds legal/*.md at
@@ -200,6 +216,9 @@ jobs:
# beta.14 (D50): the managed half too - the eight managed binaries, carrying the tag's full version.
./tools/versioninfo-check.ps1 -BuildDir out/app -ManagedDir out/app -ExpectedProductVersion '${{ steps.version.outputs.version }}'
if ($LASTEXITCODE -ne 0) { throw 'versioninfo-check over the published tree' }
# beta.18: the native binaries carry the build id read from the clean checkout, exactly - never "<tag>-dirty".
./tools/buildid-check.ps1 -BuildDir out/app -Expected $env:FL_BUILD_ID
if ($LASTEXITCODE -ne 0) { throw 'buildid-check over the published tree' }
$size = (Get-ChildItem out/app -Recurse -File | Measure-Object Length -Sum).Sum / 1MB
Write-Host ("published tree: {0:N0} MB" -f $size)
+100
View File
@@ -0,0 +1,100 @@
# The GitHub Wiki is a copy of the repository's own pages (D53/D54, the owner, 2026-10-07): wiki/ (Home, the sidebar,
# the developer pages) and guide/ (the user guide, which is the End-user part) with LIMITATIONS.md, assembled and checked
# by tools/wiki-build.ps1 - the check build.ps1 runs as `wiki-check`. A page edited on the Wiki tab is overwritten here;
# edit wiki/ or guide/ instead (docs/13_CI_CD.md §wiki.yml).
#
# Separate from release.yml on purpose. The release stays as it was and its dry run stays a pure rehearsal; a wiki that
# fails to publish is a red run of its own, re-run on its own, never a red release. A step after `gh release create`
# could never be re-run at all: the release would already exist.
#
# A release that release.yml creates with GITHUB_TOKEN fires no `release` event for other workflows. `workflow_run` does
# fire - the Release run itself was started by the owner's tag push - and it runs THIS file as it is on main, so the job
# checks out the commit the release was built from (head_sha) and links the repository's files at the tag (head_branch).
name: Wiki
on:
workflow_run:
workflows: [Release]
types: [completed]
workflow_dispatch:
inputs:
ref:
description: 'Branch, tag or commit to build the wiki from; repository files are linked at this ref'
required: true
default: main
type: string
publish:
description: 'Publish to the Wiki tab (off: build, check and upload the pages only)'
required: true
default: false
type: boolean
# The repository's default token is read-only; pushing to <repo>.wiki.git needs contents: write.
permissions:
contents: write
concurrency:
group: wiki
cancel-in-progress: false
jobs:
wiki:
# A rehearsal of release.yml (workflow_dispatch) never publishes the wiki: only a run started by a pushed v* tag
# that succeeded.
if: >-
github.event_name == 'workflow_dispatch' ||
(github.event.workflow_run.conclusion == 'success' &&
github.event.workflow_run.event == 'push' &&
startsWith(github.event.workflow_run.head_branch, 'v'))
runs-on: windows-latest
timeout-minutes: 10
env:
# Values reach the scripts through the environment only, never pasted into them.
WIKI_REF: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_branch }}
WIKI_PUBLISH: ${{ github.event_name == 'workflow_run' || inputs.publish }}
steps:
- uses: actions/checkout@v7
with:
ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.event.workflow_run.head_sha }}
persist-credentials: false
- name: Build and check the wiki
shell: pwsh
run: |
$ErrorActionPreference = 'Stop'
./tools/wiki-build.ps1 -Ref $env:WIKI_REF -Out out/wiki
if ($LASTEXITCODE -ne 0) { throw 'wiki-build failed' }
- name: Upload the pages
uses: actions/upload-artifact@v7
with:
name: wiki-${{ github.run_id }}
path: out/wiki/**
if-no-files-found: error
retention-days: 14
- name: Publish to the Wiki tab
if: env.WIKI_PUBLISH == 'true'
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
run: |
$ErrorActionPreference = 'Stop'
gh auth setup-git
if ($LASTEXITCODE -ne 0) { throw 'gh auth setup-git failed' }
git clone --depth 1 "https://github.com/$env:GITHUB_REPOSITORY.wiki.git" wiki-repo
if ($LASTEXITCODE -ne 0) { throw 'cloning the wiki failed - it must have one page created on github.com first' }
Get-ChildItem wiki-repo -Force | Where-Object Name -ne '.git' | Remove-Item -Recurse -Force
Copy-Item out/wiki/* wiki-repo -Recurse
Set-Location wiki-repo
git add -A
git diff --cached --quiet
if ($LASTEXITCODE -eq 0) { Write-Host "The wiki already shows $env:WIKI_REF; nothing to publish."; exit 0 }
git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' commit -q -m "wiki: $env:WIKI_REF"
if ($LASTEXITCODE -ne 0) { throw 'commit failed' }
# The wiki repository's branch is master (git ls-remote, 2026-10-07).
git push origin HEAD:master
if ($LASTEXITCODE -ne 0) { throw 'push failed' }
Write-Host "Published the wiki at $env:WIKI_REF"
+141
View File
@@ -28,12 +28,153 @@ numeric core and does not move; the heading is the full version — corrected 20
## [Unreleased]
## [0.1.0-beta.20] - 2026-10-12
**The twentieth pre-release: the engine version of Ren'Py games.** The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.19`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
Policy (2.9) is shown once for you to accept. Every game is read once more for its engine (detection rules `2026.10.3`).
### Added
- **The engine version of Ren'Py games**, as Unity's, Godot's and RPG Maker's have been shown since beta.19 — on the game's
page with what it was read from, the engine's own `renpy/vc_version.py`: *Ren'Py 8.5.0*. A game whose engine names no
version there reads as not found. Every game is read once more after the update (detection rules `2026.10.3`;
`docs/05_DETECTION.md` §Engine version — Ren'Py).
- **The Privacy Policy (version 2.9)** names that file among the version marks it reads; it is shown once for you to
accept.
## [0.1.0-beta.19] - 2026-10-12
**The nineteenth pre-release: an imported game that is its own runtime and not a helper, Change executable… in the game's
folder, the engine version of Unity, Godot and RPG Maker games, and games you uninstalled leaving the library by
themselves.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.18`:** Help ▸ Check for updates, then *Restart to update* with no game running. The Privacy
Policy (2.8) is shown once for you to accept. Every game is read once more for its engine (detection rules `2026.10.2`).
The agent removes the entries of games you uninstalled that have no sessions, about ten minutes after it sees them gone —
turn **Settings ▸ Data ▸ Remove uninstalled games** off first if you want them kept. An entry an earlier import made for a
helper is not changed: re-point it with *Change executable…*.
### Added
- **The engine version of Unity, Godot and RPG Maker games**, as Unreal Engine's has been shown since beta.10 — on the game's
page with what it was read from, and the maker on the library card too: *Unity 2022.3.39f1* (from the player library,
else its data file; a game whose data file is encrypted reads without the release letter, *2019.4.40*), *Godot 4.4.1*
(from its data pack), *RPG Maker MZ 1.10.0* and *MV 1.6.2* (from the core script), *RPG Maker VX Ace (RGSS 3.0.1)*
(from the runtime library its `Game.ini` names — that number is the library's, not the editor's). A Unity version used
to read as its library's build number (`2022.3.39.5118735`), and a Godot one was never found. Every game is read once
more after the update (detection rules `2026.10.2`). RPG Maker 2000/2003 is not recognised (`docs/05_DETECTION.md`
§Engine version — Unity, Godot, RPG Maker).
- **The Privacy Policy (version 2.8)** names the files those versions are read from, and two that were already read and
never named (Unity's player library and an RPG Maker game's title); it is shown once for you to accept.
- **A game you uninstalled leaves the library by itself** when it has no sessions: the agent removes an entry whose `.exe`
has been gone for ten minutes, if its drive is connected and the folder it was installed in is still there — an
unplugged or re-lettered drive never counts — and never one where anti-cheat was found. A game with sessions stays, with
them, and reads *Not installed* as before. The Games page says so when it happens — once, naming them, for all the games
one check removes; **Settings ▸ Data ▸ Remove uninstalled games** turns it off (`docs/02_SPEC.md` FR-1.8).
### Changed
- **Change executable… opens in the game's own folder** — the install folder a store made (`steamapps\common\<game>`
and the like), or above an Unreal game's `Binaries\Win64`, else the folder the executable is in — instead of wherever
the last file dialog was. For a game whose folder is gone it opens at the nearest folder still there
(`docs/08_UI.md` §Games).
### Fixed
- **An imported game is no longer one of its helpers, and an RPG Maker MV/MZ game behind a launcher is its runtime.**
A Doll's Locket - Remake (itch) was added as `notification_helper.exe`, NW.js's notification helper, because the itch
app's own record named only that file (it leaves out a launcher that asks for administrator and anything a folder
deeper) and the import took it as the game. A helper named by the store is skipped now and the executable is guessed —
the import list says so — and the guess takes the executable beside NW.js's `nw.dll` and `package.json`, the process
that draws (`css\Game.exe` there; its launcher asks for administrator, so it is measured with *Run the agent as
administrator* on). The import also no longer offers a store's game again when the library has it at another
executable: an entry already there is re-pointed with *Change executable…* (`docs/05_DETECTION.md` §Library import).
- **The Games page shows its newest read of the library.** When two reads overlapped — a session ending while an import
added games — the one that started first could finish last and be shown, an older list until the next read.
## [0.1.0-beta.18] - 2026-10-07
**The eighteenth pre-release: every page readable in the dark theme, notices that say what happened in words, and a
release whose build no longer calls itself dirty.** The same unsigned installer: verify its hash against
`SHA256SUMS.txt`, then *More info → Run anyway*.
**Updating from `0.1.0-beta.17`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
### Fixed
- **Page titles and section headings read in the dark theme again.** Every page's title and its section headings — Dashboard,
Recent sessions, Games, Compare, Settings and each of its groups, Logs — were drawn near-black on the dark window
(owner's screenshots of beta.17; beta.16 had it too). A page is shown in WPF UI's navigation Frame, which passes no text
colour into the page, and a text that sets none is black; a page open during a theme switch picked the right colour up,
and the next one navigated to did not. Every page now sets the theme's text colour itself. `AccessibilityTests.EveryPageSetsItsOwnTextColour`
and `PagesLoadTests.EveryTextIsReadableInBothThemes` (every surface hosted as the App hosts it, ≥ 3:1 in both themes)
went red on the unfixed pages first; the theme-switch check now hosts pages in the Frame too, and its harness derives the
accent for each theme as the App does (`docs/08_UI.md` §Contrast, `docs/16_WPFUI_SYNTAX.md` §Gotchas, `docs/14_TESTING.md`).
- **Every notice says what happened in words.** With *Disable all hooking* on, a game's notice read "kill switch was
detected in this game (the global 'disable all hooking' switch is on (FR-2.4); …)" — it reads "All hooking is switched
off in Settings, so nothing was measured." now, and a game blocked before reads as that, not as a finding. A refusal no
anti-cheat names read "… reason RefusedByGuard." and is said in the guard's words ("the game is 32-bit, and the hook
runs in 64-bit games only"); the agent sends the guard's reason for every refusal (`docs/07_IPC.md`). A safety re-scan
that could not look while the game ran read "Access is denied. was detected" and says the check could not be made. And
*Measurement stopped* printed "The hook stopped (WriterSelfDisabled); the session continues without measuring." — it
says why in a sentence, and no longer that the session went on: a stop ends it. `NoticesFromTheAgentTests` builds the
agent's own events for every refusal and every stop and went red with each text above (`docs/08_UI.md` §Notifications policy).
- **Disable all hooking says when it applies.** Turning it on said "The capture agent reads it at the next session start";
a game being measured stops at its next safety scan, within 30 seconds, and the message says so.
- **Turning hooking off with no agent says nothing changed** — Settings' *Turn off*, the game page's switch and a
withdrawn exception said "Nothing was enabled.", the enabling path's words.
- **A viewer over a copy leaves every agent setting alone.** The user-mode exception option, the three Recording numbers
and the update channel stayed live in `--data-dir`, where no agent reads them (`ViewerModeTests`).
- `docs/08_UI.md` listed a "PawnIO missing" banner that was never built; struck, with the banners that do exist.
- **A release's overlay build no longer calls itself dirty.** The Dashboard read *Overlay build v0.1.0-beta.17-dirty* (and
beta.16's, and every release's before): the release workflow writes the release date into the legal documents before
the build, and the build id was read from the tree after that. It is read from the clean checkout first and handed to
the build, and `tools/buildid-check.ps1` reads it back out of the published binaries (`docs/12_BUILD.md` §Release-time
token substitution). Nothing changes for a game: both sides of the ring's handshake always carried the same id.
- **Two end-to-end tests no longer fail CI by a race** (developers only). The Vulkan launch test asks the test harness
whether this machine can present through Vulkan before it starts the capture host: on GitHub's runners the harness's
own "skip" line never reached the host's output, and a scan of the exiting harness failed the test instead of skipping
it. The target-exit test holds its harness 15 seconds instead of 6, the margin a slow runner's host needed
(`docs/13_CI_CD.md`).
## [0.1.0-beta.17] - 2026-10-07
**The seventeenth pre-release: text that keeps up with a change of theme, scroll bars hidden everywhere when you ask, a
user guide that answers more, and a wiki.** The same unsigned installer: verify its hash against `SHA256SUMS.txt`, then
*More info → Run anyway*.
**Updating from `0.1.0-beta.16`:** Help ▸ Check for updates, then *Restart to update* with no game running. Nothing in
the database changes and nothing is shown again for you to accept; sessions already stored keep their status.
### Fixed
- **Text keeps up with a change of theme.** After switching between Light and Dark, the descriptions and captions of the
page in view — Settings above all, where the theme is chosen — kept the old theme's colour: light grey on white, or dark
grey on dark. Every such text now follows the switch, on every page, window and dialog (`08_UI` §Contrast,
`16_WPFUI_SYNTAX` §Gotchas).
- **Hide scroll bars hides every scroll bar.** With Settings ▸ Window ▸ Hide scroll bars on, the Dashboard still drew its
scroll bar — and so did the first run, About, the user guide and a game's wide sessions table; only screens with a
switch or a tick box on them lost theirs. Every scroller follows the option now, and still scrolls with the wheel, the
keyboard and touch (`08_UI` §Settings, `16_WPFUI_SYNTAX` §Gotchas).
- **The first run names the right place to import your library.** Its last step said *File ▸ Import library… on the
Games page*; File is the main window's menu, and the Games page has no such button. In Vietnamese it now names the menu
as it is shown (*Tệp*).
### Added
- **The user guide looks things up too.** Four pages join it, in Help ▸ User guide: *The screens* (every page, menu,
button and shortcut), *Every setting* (what each one does and its default), *When something goes wrong* (what you see,
what it means, what to do) and *Words FrameLedger uses*. Tests now fail when a setting or a menu item is added without
its line in the guide, or a link names a section that does not exist.
- **A wiki.** The project's [wiki](https://github.com/poli0981/frameledger/wiki) has two halves: the user guide, the
same pages the app shows, and short pages for developers — the architecture, the repository, building and testing,
the rules every change keeps, capture, metrics, data, the app's UI and releasing — each linking to its full document.
It is published from the repository whenever a release is made (`wiki.yml`), so it always matches the newest
release, and `./build.ps1 check` fails on any link in it that leads nowhere (`13_CI_CD` §wiki.yml).
## [0.1.0-beta.16] - 2026-10-06
+9 -2
View File
@@ -138,7 +138,9 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# gen-ac-floor, hookinventory-check, license-check, license-gather
# (+ license-overrides/), notice-check, package-closure-check,
# release-notes, rules-validate, test-artifacts-check, vendor-exports,
# versioninfo-check, vklayer-blastradius, fps-impact-runbook
# versioninfo-check, vklayer-blastradius, fps-impact-runbook,
# wiki-build (beta.17: builds and checks the wiki; the wiki-check gate),
# buildid-check (beta.18: the release's build id in the shipped natives)
# (six names added 2026-10-04)
# (PowerShell). This line used to name three, one of which
# — resx-audit — ~~does not exist~~ exists since 2026-09-13 with
@@ -151,8 +153,13 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# stats, signer, Vulkan layer; fl-baseline-probe;
# vendor-stubs/ -> fixture DLLs with the vendors' export names
rules/detection-rules.json # engine/platform/capability + anticheat blocklist
guide/ # the user guide (beta.12, D44): eight short English pages for players, embedded in the
guide/ # the user guide (beta.12, D44): ~~eight~~ short English pages for players, embedded in the
# App (Help > User guide); README.md is its contents. docs/ is for developers.
# (twelve since beta.17, D54: the screens, every setting, troubleshooting, a glossary;
# and the guide is the wiki's End-user part)
wiki/ # the wiki's own pages (beta.17, D53): Home, _Sidebar, the developer pages. wiki.yml
# publishes them with guide/ and LIMITATIONS.md to the Wiki tab at a release;
# tools/wiki-build.ps1 assembles and checks them (build.ps1 wiki-check)
docs/ legal/ legal/licenses/
```
+5
View File
@@ -27,6 +27,11 @@ That is the whole quality gate, and continuous integration runs the identical sc
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). `docs/12_BUILD.md` describes each
step and the build profiles. Run it in your main checkout: a fresh `git worktree` cannot configure the native build.
Documentation lives in three places: `guide/` for players (shown in the app and on the wiki), `wiki/` for the wiki's own
pages, and `docs/` for developers. A change a player would notice updates `guide/`; a change to how the code is put
together updates `docs/` — and the `wiki/` page that summarises it, if that page now says something else.
`./build.ps1 check` builds the wiki and fails on a link that leads nowhere.
Never point a build of your own at the data FrameLedger records into (`%LOCALAPPDATA%\FrameLedger`): a newer build
migrates the database, and the released one cannot read it back. To look at real data, copy the folder and start
`FrameLedger.exe --data-dir <copy>` — a viewer that starts no Agent and changes nothing on the PC (`docs/12_BUILD.md`
+10 -3
View File
@@ -5,7 +5,7 @@ hooking on for — and reading the graphics calls the game makes. That is why it
resolution, the upscaler, frame generation and ray tracing apart. It is also where its limits come from. This
page lists them in plain words; each item links to the document that has the details.
*Beta software: this page describes version 0.1.0-beta.16.*
*Beta software: this page describes version 0.1.0-beta.20.*
## Games it will not measure
@@ -117,8 +117,15 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
- The exact version is read for **Unreal Engine 4 and 5** games, from the game's executable file on disk.
A studio can remove or rename what it is read from; then the page says the version was not found.
**Unreal Engine 3 and older are not recognised.** Other engines show a version only where their files
state one. ([Detection](docs/05_DETECTION.md))
**Unreal Engine 3 and older are not recognised.**
- Since beta.19 also **Unity**, **Godot** and **RPG Maker** (MV, MZ, XP, VX, VX Ace): from the engine's own files —
Unity's player library or data file, Godot's data pack, RPG Maker's core script or the runtime library its `Game.ini`
names. A Unity game whose data file is encrypted shows the version without its release letter (`2019.4.40`, not
`2019.4.40f1`); an XP, VX or VX Ace game shows its runtime library's number, which is not the editor's.
**RPG Maker 2000 and 2003 are not recognised.**
- Since beta.20 also **Ren'Py**: from the engine's own version file (`renpy/vc_version.py`); a Ren'Py game whose engine
names no version there shows none. Other engines show a version only where their files state one.
([Detection](docs/05_DETECTION.md))
## Sensors
+14 -7
View File
@@ -5,12 +5,14 @@
> No telemetry. No accounts. All data stays on your machine.
**New here? Start with the [user guide](guide/README.md)** — install, record a game, read your results, stay safe with
anti-cheat, and look after your data, a page each. What FrameLedger cannot do is on one page:
[Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User guide, Help ▸ Limitations).
anti-cheat, and look after your data, a page each, then every screen, every setting and what to do when something goes
wrong. What FrameLedger cannot do is on one page: [Limitations](LIMITATIONS.md). Both are in the app too (Help ▸ User
guide, Help ▸ Limitations), and on the project's [wiki](https://github.com/poli0981/frameledger/wiki) with the developer
pages.
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-10-06.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.16`** (2026-10-06), an unsigned installer built from that tag with its
> **pre-release is `0.1.0-beta.20`** (2026-10-12), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -61,8 +63,11 @@ anti-cheat, and look after your data, a page each. What FrameLedger cannot do is
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
> files state.
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
> player library or its data file — without the release letter where only the library's number is readable),
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
> once a second from Windows' own counters, from outside the game, in every session: a game
@@ -161,7 +166,7 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
## Install
> **The latest pre-release is `v0.1.0-beta.16` (2026-10-06); before it `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
> **The latest pre-release is `v0.1.0-beta.20` (2026-10-12); before it `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read `CHANGELOG.md`'s section for the one you install — what it measures, what it does not yet, and how to update — before installing. A source build is `docs/12_BUILD.md`.
1. Download the latest `FrameLedger.App-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases). It installs into `%LOCALAPPDATA%\FrameLedger.App`; your data stays in `%LOCALAPPDATA%\FrameLedger`, and uninstalling asks before touching it.
2. SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then **More info → Run anyway**.
@@ -191,6 +196,8 @@ FrameLedger is GPL-3.0-only free software, and you are welcome to build it, chan
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reports: [`SECURITY.md`](SECURITY.md).
- **Fork or redistribute:** [`FORKING.md`](FORKING.md) — what the GPL asks of anyone who distributes builds, and the names
a fork must change so it does not share FrameLedger's update feed, install folder, data, pipe or Vulkan layer.
- **Find your way around:** the [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages are short, and each
links to the document it summarises ([`wiki/`](wiki/) is their source).
- **Read the design:** the developer documentation is in [`docs/`](docs/). Start with [`CLAUDE.md`](CLAUDE.md), then
[`docs/19_SAFETY_AND_ANTICHEAT.md`](docs/19_SAFETY_AND_ANTICHEAT.md) — which constrains everything else — then
[`docs/01_ARCHITECTURE.md`](docs/01_ARCHITECTURE.md).
@@ -208,4 +215,4 @@ GPU telemetry is layered so the project never depends on a proprietary vendor li
---
**Status:** pre-release (beta). Sixteen tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
**Status:** pre-release (beta). Twenty tagged pre-releases so far; see `CHANGELOG.md` for what each one changed and the accuracy block at the top of this file for what is and is not measured. It is not feature-complete, it certainly still has bugs, and `legal/DISCLAIMER.md` §0 says what that means for you.
+15
View File
@@ -464,6 +464,15 @@ function Invoke-ProjectGates {
Invoke-Checked 'notice-check (self-test)' { & $noticeTool -SelfTest }
Invoke-Checked 'notice-check' { & $noticeTool -RepoRoot $repo }
# beta.17 (D53/D54): the GitHub Wiki is built from wiki/, guide/ and LIMITATIONS.md, and wiki.yml publishes it when a
# release is made. A link or a section that leads nowhere, a page nothing leads to, a sidebar out of the guide's
# order, a path that names nothing or a version written into a page is red here, not on the published wiki.
# Self-test first (nine cases, both directions), then the live assembly into a temporary folder.
Write-Step 'wiki-check'
$wikiTool = Join-Path $repo 'tools/wiki-build.ps1'
Invoke-Checked 'wiki-check (self-test)' { & $wikiTool -RepoRoot $repo -SelfTest }
Invoke-Checked 'wiki-check' { & $wikiTool -RepoRoot $repo -Check }
Write-Step 'changelog-check'
$changelogTool = Join-Path $repo 'tools/changelog-check.ps1'
if (Test-Path $changelogTool) {
@@ -479,6 +488,12 @@ function Invoke-ProjectGates {
Write-Step 'release-notes'
Invoke-Checked 'release-notes (self-test)' { & (Join-Path $repo 'tools/release-notes.ps1') -SelfTest }
# beta.18: the build id a release hands CMake (read from the clean checkout before the date substitution edits
# legal/*.md) is read back out of the published native binaries by release.yml. Self-test only here — the live
# pass needs that id, which only a release has (12_BUILD §Release-time token substitution).
Write-Step 'buildid-check'
Invoke-Checked 'buildid-check (self-test)' { & (Join-Path $repo 'tools/buildid-check.ps1') -SelfTest }
# 09_I18N's gate, built with the first .resx family (P3 PR-2, 2026-09-13): every key in en/vi/ja, ja
# Safety_* marked for human review, the generated accessor current. Self-test first (at least four
# cases must go red), then the live pass; a tree with no family is red, not skipped.
+1
View File
@@ -11,6 +11,7 @@ Requirement IDs (`FR-x`, `NFR-x`) are referenced by other docs, commits, and tes
- FR-1.4 Remove game (asks whether to keep or delete its sessions).
- FR-1.5 "Supports" row shows shipped-capability hints (DLSS/FSR/XeSS/FG) — visually distinct from measured per-session values (`05_DETECTION` §Capability hints).
- FR-1.7 Delete all sessions (beta.11, owner decision D40): of one game from its page, or of every game from Settings ▸ Data, after a confirmation that says how many — with their frame and sensor series and notes; the library, the settings and every consent stay. The Agent deletes them (the rows are its, `06_DATA_MODEL` §Writer ownership) and refuses while a session it would delete under is being recorded.
- FR-1.8 Uninstalled games leave the library by themselves (beta.19, owner decision D55, amending D41): an entry whose executable has been gone for ten minutes — its drive connected and the folder it was installed in still there, so an unplugged or re-lettered drive never counts, and neither does a folder Windows will not list (`ExecutablePresenceProbeTests`) — and that has no session (stored, being recorded or waiting to be recovered) is removed by the Agent, behind Settings ▸ Data ▸ *Remove uninstalled games* (on by default). Never an entry carrying an anti-cheat block, an exception or a failed-trial mark (FR-2.2, rule 2). The App is told (`GameRemoved`).
- FR-1.6 Recording switch per entry (2026-09-23, HANDOFF D29): off, the program is not watched at all — no session, no measurement, no injection — and a session of it that is running stops. On by default; entries an old import made for Steam's own tools start with it off. The library card says "Not recorded".
### FR-2 Hooking consent & control (new, safety-critical — see `19_SAFETY`)
+88 -4
View File
@@ -143,12 +143,12 @@ Recorded as a residual risk, not as a solved problem.
| Engine | Signals | Version |
|---|---|---|
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | FileVersion of `UnityPlayer.dll` |
| Unity | `UnityPlayer.dll` sibling **or** `<Exe>_Data/` dir | `unity_build` (since 2026-10-12, §Engine version — Unity, Godot, RPG Maker): the player library's ProductVersion, the data file's header, the library's numeric version. ~~FileVersion of `UnityPlayer.dll`~~ — the string as it is, `2022.3.39.5118735`, the build number where the release letter belongs |
| Unreal 4/5 | exe matches `*-Win64-Shipping.exe` **or** `*/Content/Paks/*.pak` | `unreal_build` (since 2026-09-27, §Engine version): the shipping executable's numeric file version and the engine's branch name inside it. ~~ProductVersion regex `\+\+UE(4\|5)\+Release-(\d+\.\d+)`~~ — two capture groups, of which the evaluator returns the first, so every Unreal version it ever stored was a bare `4` or `5` |
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | strings regex `Godot Engine v(\d+\.\d+[\.\d]*)` |
| Godot | `.pck` sibling **or** `strings_contains("Godot Engine v")` | `godot_build` (since 2026-10-12): a data pack's header, beside the executable or appended to it. ~~strings regex `Godot Engine v(\d+\.\d+[\.\d]*)`~~ — the string sits 57–78 MB into a real export, past the 8 MiB scan, so it never read one |
| GameMaker | `data.win` | `N/A` |
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `N/A` — the `.js` header needs a `from` that `strings_regex` lacks |
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `N/A` — one rule, the variant unnamed |
| RPG Maker MV/MZ | `nw.dll` **and** `package.json` siblings (since 2026-09-16) | `rpgmaker_build` (since 2026-10-12): the core script's header, which also names the maker (MZ or MV). ~~`N/A` — the `.js` header needs a `from` that `strings_regex` lacks~~ |
| RPG Maker XP/VX/VX Ace | `RGSS1*`/`RGSS2*`/`RGSS3*.dll` sibling **or** a `*.rgssad`/`*.rgss2a`/`*.rgss3a` archive (since 2026-09-16) | `rpgmaker_build` (since 2026-10-12): the RGSS library `Game.ini` names — its generation names the maker (XP, VX, VX Ace), its version is the library's. ~~`N/A` — one rule, the variant unnamed~~ |
| RE Engine (Capcom) | `re_chunk_000.pak` sibling, the exact name (since 2026-09-23) | `N/A` |
| FromSoftware | a `*.bhd` **and** a `*.bdt` sibling (since 2026-09-23) | `N/A` |
| Ren'Py | `renpy/` dir **or** `*.rpa` | ~~`renpy/__init__` strings / `log.txt` first line~~ `N/A` *(corrected 2026-10-04: no extractor — `strings_regex` reads only the executable)* |
@@ -246,6 +246,67 @@ numbered release lines to report. A version the user typed is never overwritten
`2026.09.6` change the key, so every library entry is read again once; schema 0015 removes the bare `4`/`5` the old rule
wrote, where detection wrote it.
### Engine version — Unity, Godot, RPG Maker (beta.19, 2026-10-12, rules 2026.10.2)
The owner asked for the version of RPG Maker, Unity and Godot games ("if possible"). What the rules gave: Unity's
`pe_file_version` stored `UnityPlayer.dll`'s FileVersion string as it is (`2022.3.39.5118735`, the build number where the
release letter belongs); Godot's `strings_regex` scanned the executable's first 8 MiB, and in both Godot exports on the
owner's disk the `Godot Engine v…` string sits 57–78 MB in, so it never read one; both RPG Maker rules had `version: null`.
**Measured before anything was written, read-only, on 23 installs** (`spike-notes` §17), and decided in code as Unreal's
is — three extractor types that take no parameter (`unity_build`, `godot_build`, `rpgmaker_build`; the schema's enum),
one second read by `StaticGameDetector` for the engine that matched, a decider in `Domain.Detection` and the witness in
`games.engine_version_source`:
| Engine | Witness, strongest first | Source id | On the owner's disk |
|---|---|---|---|
| Unity | `UnityPlayer.dll`'s ProductVersion is an editor version (`2022.3.39f1 (4e1b…)` → `2022.3.39f1`) | `unity_player` | 13 of 15 |
| | the header of `<Game>_Data\globalgamemanagers` (first 256 bytes) names one | `unity_data` | A Space for the Unbound, 2019.4.1f1 |
| | the library's numeric file version, MAJOR.MINOR.PATCH and no release letter — Unity's own binary, so the engine's, only shorter | `unity_player_file` | GIRLS' FRONTLINE 2 (data file encrypted), 2019.4.40 |
| Godot | the 20-byte header of the data pack beside the executable (`<exe>.pck`, else the only `.pck` there): `GDPC`, format, MAJOR, MINOR, PATCH | `godot_pck` | both: 4.2.2, 4.4.1 |
| | the same header of a pack appended to the executable, found through its 12-byte trailer (size + `GDPC`) | `godot_pck_embedded` | none (synthetic files only) |
| | the executable's ProductVersion while its ProductName is still `Godot Engine` (a project that set its own carries the game's: 衔蝶 `0.1.0.3`) | `godot_exe` | — |
| RPG Maker MV/MZ | line 2 of the core script: `js/rmmz_core.js` → MZ, `www/js/rpg_core.js` or `js/rpg_core.js` → MV (first 4 KiB) | `rpgmaker_mz_core`, `rpgmaker_mv_core` | MZ 1.10.0; MV 1.6.2, 1.6.2, 1.6.1 |
| RPG Maker XP/VX/VX Ace | the RGSS library `Game.ini`'s `Library=` names: RGSS1 → XP, RGSS2 → VX, RGSS3 → VX Ace; its numeric version when it is its generation's, else the one its name carries (`RGSS301` → 3.0.1) | `rgss1_library`, `rgss2_library`, `rgss3_library` | VX Ace 3.0.1, twice |
A Godot version leaves out a zero patch, as Godot names its releases (4.3, 4.2.2). The App names the maker from the
witness — the two RPG Maker rules each cover several makers — and says that an RGSS number is the runtime library's, not
the editor's: *RPG Maker MZ 1.10.0*, *RPG Maker VX Ace (RGSS 3.0.1)* (`Formats.Engine(id, source)`,
`Formats.EngineWithVersion`); the game page's *Engine version* row says what each version was read from, and *Not found in
the game's files* once the sweep has read a row of these engines and found none.
**Where it is read.** Beside the row's executable first: `UnityPlayer.dll` (else the shallowest one the walk listed) and
`<exe>_Data` (else a `*_Data` beside that player); `<exe>.pck`. RPG Maker's files are looked for beside the executable and
up to two folders above it, as `RpgMakerTitle` already looked for a title — a launcher-fronted game keeps its runtime in
a subfolder (A Doll's Locket's `css\`, HELLO, HELLO WORLD!'s `swiftshader\`); a `Library=` that points outside the ini's
folder is named and not read. Version resources and at most a few kilobytes of any file; the whole detection of one entry
measured 24 ms to 4.1 s on the owner's USB drive, nearly all of it the install's walk, once per executable and rules
version. The Privacy Policy says so since 2.8 (§4).
**What it is not.** RPG Maker 2000/2003 is not detected at all (no install to measure, no rule). XP and VX libraries are
read by the VX Ace rule's reader unmeasured. A Unity build older than 2019 keeps its player in the executable (no
`UnityPlayer.dll`): its data file's header is the only witness. Rules `2026.10.2` change the detection key, so every
library entry is read again once; a Unity row keeps the old raw string only if none of its witnesses can be read now.
### Engine version — Ren'Py (beta.20, 2026-10-12, rules 2026.10.3)
The owner asked for the version of Ren'Py games once beta.19's were on screen. The `renpy` rule had no version extractor
(`version: null`). Ren'Py ships its engine as Python beside the game's launcher, and `renpy/vc_version.py` names its
release — `version = '8.5.0.25111603'`, beside `branch`, `nightly`, `official` and `version_name`. Measured 2026-10-12 on
the owner's one Ren'Py install, Bound Between Desks (Steam): 109 bytes, and the game's own `log.txt` printed
`Ren'Py 8.5.0.25111603` at its last start; the launcher carries no version resource (`spike-notes` §18).
**What is read and how it is decided.** `renpy_build` (`RenPyBuildReader`): the first 4 KiB of `renpy/vc_version.py`
beside the row's executable, its `version` line only (`version_name` is not it). `RenPyVersion.Decide` keeps
MAJOR.MINOR.PATCH — Ren'Py names its releases by those three; the fourth is the build — and records `renpy_vc_version`.
The page says *Ren'Py 8.5.0* and that it was read from the engine's version file; a Ren'Py row whose file names no
version says *Not found in the game's files*. Through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`)
Bound Between Desks read `8.5.0` in 79 ms, and the Unity, Godot and RPG Maker installs read as before. The Privacy
Policy names the file since 2.9 (§4). Rules `2026.10.3` change the detection key, so every library entry is read again
once.
**What it is not.** Nothing else is guessed from: a Ren'Py game whose `vc_version.py` names no version, or that ships its
engine compiled only, reads as not found. One Ren'Py install was measured.
### Platform signatures & metadata
| Platform | Signals | Metadata |
@@ -293,6 +354,29 @@ wrote, where detection wrote it.
> is fetched (CLAUDE.md rule 8's "opt-in store metadata" is the online lookup, which does not exist). First-run
> step 4 now points at File ▸ Import library… rather than saying "later build".
> **beta.19 (owner report 2026-10-12): a store's own pick can be a helper, and a launcher is not the game.** The owner's
> A Doll's Locket - Remake (itch 5085165, RPG Maker MZ) was imported as `Dolls Locket\notification_helper.exe` — NW.js's
> toast helper. The pick was **butler's verdict**, taken as is: butler stores a *filtered* verdict (the shallowest
> candidates, minus those whose manifest asks for elevation) and does not rank what is left, and on that install the
> 213 MB `DollsLocket.exe` launcher asks for administrator while the NW.js runtime sits a level deeper in `css\`, so the
> helper was the whole verdict (read from the owner's `butler.db`, read-only). Three changes:
> **(1)** a verdict candidate whose whole name is a runtime helper (`ExecutableLocator.RuntimeHelperNames`:
> `notification_helper`, `crashpad_handler`, `UnityCrashHandler64/32`, `CrashReportClient`, NW.js's `nwjc` and
> `chromedriver`) or that sits in a Unity plugin folder is skipped, and with nothing left the locator guesses and the
> review marks the row *guessed* — whole names, because the locator's fragments are inside real games' names (`node` in
> *Nodebuster*) and a store's pick is overruled only when it cannot be the game; the locator's `HelperFragments` gain the
> same three NW.js names. **(2)** The locator ranks **an executable beside `nw.dll` + `package.json`** — the `rpgmaker_mv`
> rule's own signal — as an NW.js runtime (owner decision D56), below the Unity and Unreal layouts (an NW.js folder can
> be a tool shipped beside such a game) and above a name match (the launcher in front of the runtime is named after the
> install): the install's guess is `css\Game.exe`, the process that draws, as D28 pointed HELLO, HELLO WORLD!'s entry at
> its runtime by hand. That runtime starts elevated (its launcher asks for administrator), so it is measured with the
> admin mode on (D34). **(3)** Discovery matches a store title to an entry by **platform + store id** as well as by
> path: the entry an earlier import made at another executable is "already in the library" (the log names its path),
> so a corrected guess never adds the same game a second time — that entry is re-pointed with Change executable…, and
> nothing rewrites it by itself (D25/D27). Tests: `ExecutableLocatorTests.AnNwjsRuntimeBeatsTheLauncherNamedAfterTheInstallAndItsHelpersAreDropped`,
> `StoreLibrarySourcesTests.ItchSkipsAVerdictCandidateThatIsARuntimeHelper` (the verdict as stored),
> `LibraryImporterTests.AStoreTitleAlreadyInTheLibraryAtAnotherExecutableIsNotOfferedAgain`.
**Publisher/version order:** store manifest → PE `CompanyName`/`ProductVersion` → *(opt-in)* Steam `appdetails` lookup, cached 7 days. *(Since beta.8 the PE versions are stored beside the store's rather than instead of it — §What the files say about themselves; the page labels a store's value with its store, "Steam build 20374416".)*
## Capability hints (explicitly labelled as such)
+7 -3
View File
@@ -2,7 +2,7 @@
`%LOCALAPPDATA%\FrameLedger\ledger.db`. Pragmas: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=5000`. `Microsoft.Data.Sqlite` + Dapper; all writes in explicit transactions.
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It is the one Agent write that deletes a `games` row; it never touches a consent column. **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself *(for Delete all sessions; FR-1.4's removal is the App's own cascade, above — corrected 2026-10-04)*. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; ~~never a `hook_*` column~~ **and two downgrades** *(corrected 2026-10-04)*: *Change executable* (2026-09-21, `GameLibrary.ChangeExecutableAsync`) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and *Remove game ▸ Delete sessions too* (FR-1.4) deletes the `games` row, cascading to its sessions, segments, blobs and annotations), `session_annotations` (tags, notes, and since schema 0002 the FR-8.3 overrides — which is WHY they are on this table and not on `sessions`), `settings`, `legal_acceptance`. Both read everything. The ports say the same in their names: `IGameRepository.UpdateMetadataAsync` / `SetTriStateDefaultAsync` / `RemoveAsync`, `ISessionAnnotationRepository`, `RegisteredSettings`, `ILegalAcceptanceStore.RecordAsync` (all P3 PR-3).
**Writer ownership:** Agent writes `sessions`, `session_segments`, `frame_blobs`, `sensor_blobs`, `hardware_snapshots`, the hook-state columns on `games`, **and since P4 PR-1 (2026-09-14) the *detected* columns on `games`** — `engine`, `engine_version`, `platform` under the per-field provenance rule (`05_DETECTION` §Caching: a `user` field is never touched), `capability_flags` whole, and the cache key `detection_rules_version` / `detection_exe_size_bytes` / `detection_exe_mtime_ms`, and since schema 0011 (2026-09-25) the executable's own facts `exe_machine` / `exe_file_version` / `exe_product_version` / `library_versions`, written whole like the flags — through `IGameRepository.ApplyDetectionAsync` only. The UI and the Agent were both already writers of `games`; this adds columns to the Agent's half, not a third writer (HANDOFF §P4). **And since P4 PR-4 the UI's library import writes `platform`, `store_id` and `game_version` through `ApplyStoreMetadataAsync`** — the same per-field provenance rule, badged `detected` (a store's record is not the user's typing), on columns the UI already owned. **And since 2026-09-23 the Agent's relocator merges two entries for one executable under two drive letters** (`IGameMerge`, HANDOFF D26, `19_SAFETY` §A moved drive is the same executable): in one transaction it re-parents the dropped entry's `sessions` to the survivor (before the delete — `sessions.game_id` cascades), carries a block or a crash auto-disable still in force to the survivor (`hook_enabled` only ever to 0; `hook_blocked_reason` is copied, never originated or cleared), adds the crash counts, deletes the dropped `games` row, and then moves the survivor to the file's path (after the delete — `exe_path` is UNIQUE). It was the one Agent write that deletes a `games` row until beta.19; it never touches a consent column. **And since beta.19 (2026-10-12, D55) the Agent removes an entry whose game is no longer installed** (`IGamePrune`, `SqliteGamePrune`, asked by the detection sweep through `UninstalledEntryPrune`): one `DELETE` that holds every stored condition in the same statement — the same row at the same path, `removed_at` NULL, no session stored (`NOT EXISTS` on `sessions` — nothing cascades), no `hook_blocked_reason`, `hook_prescan_state` not `blocked`, no `ac_exception_at` and no `ac_exception_trial_failed_at` — behind `retention.remove_uninstalled_games`; a block, a grant and D38's mark are never removed with their entry (`19_SAFETY` §What a finding does to the game, *What clears it*). **And since 2026-09-23 the UI writes `record_sessions`** (schema 0009, FR-1.6): the entry's recording switch, which the Agent only reads — off, the watcher does not watch for the program. The script's one data change switches it off for entries an old import made for Steam's own tools (`SteamLibrarySource.KnownTools`, the ids as of the script); a twin merge keeps it off when either twin had it off. **And since 2026-09-25 the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) writes the hook-state columns of every entry, not only of those the user asked to hook** — `hook_prescan_state`, and on a finding `hook_enabled = 0` and `hook_blocked_reason` — and its own key, `hook_prescan_rules_version` / `hook_prescan_exe_size_bytes` / `hook_prescan_exe_mtime_ms` (schema 0010), through `IGameConsentStore.RecordPreScanAsync` only: columns that were already the Agent's, never over a block, never a new row. **And since 2026-09-26 (schema 0014, D33) the Agent writes the user-mode exception's columns** — `ac_exception_*` on `games` through `IGameConsentStore` only (eligibility from the sweep, a grant from the `SetAntiCheatException` command, every end), and `sessions.ac_exception_family` with the session — the grant only after the user accepted its disclosure in the UI, which asks and never writes. **And since 2026-10-03 (beta.11, D40) the Agent deletes sessions on request** — every session of one game or of every game, `DeleteSessions` over the pipe, through `ISessionRepository.DeleteSessionsAsync` in one transaction (segments, blobs and annotations cascade), never while one is being recorded; the UI asks and never deletes a session row itself *(for Delete all sessions; FR-1.4's removal is the App's own cascade, above — corrected 2026-10-04)*. **Maintenance (P4 PR-7) adds no writer:** the retention sweep on demand is the Agent's, asked over the pipe; the UI's `VACUUM` rewrites pages with the same contents and changes no row (§Retention built note). UI writes `games` (user-editable fields — since P3 PR-3 that is the FR-1.3 metadata, the `*_default` tri-states, and `removed_at`; ~~never a `hook_*` column~~ **and two downgrades** *(corrected 2026-10-04)*: *Change executable* (2026-09-21, `GameLibrary.ChangeExecutableAsync`) turns hooking off, clears the consent and pre-scan columns and ends an exception grant — it never writes a block or a grant — and *Remove game ▸ DeLine truncated
## Schema (v2 — hook architecture)
@@ -47,8 +47,11 @@ CREATE TABLE games (
store_id TEXT,
engine TEXT, engine_version TEXT,
-- (schema 0015, ALTERed last) engine_version_source TEXT: where engine_version came from — a
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version, or the rule's
-- extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
-- Domain.Detection.EngineVersionSource id (unreal_branch_file | unreal_branch | unreal_file_version; since beta.19
-- unity_player | unity_data | unity_player_file | godot_pck | godot_pck_embedded | godot_exe | rpgmaker_mz_core |
-- rpgmaker_mv_core | rgss1_library | rgss2_library | rgss3_library — the RPG Maker ids also name the maker; since
-- beta.20 renpy_vc_version; or the
-- rule's extractor type); NULL for a version the user typed. Written with the version only (05_DETECTION §Engine version)
publisher TEXT, game_version TEXT,
cover_path TEXT, notes TEXT,
removed_at INTEGER, -- schema 0002 (P3 PR-3): FR-1.4 "remove, keep sessions" — the row stays
@@ -440,6 +443,7 @@ switch's rule); integers are invariant-culture within an inclusive range; choice
| `capture.min_session_s` | int | `30` | 5–600 | Agent, per session (FR-3.6) |
| `telemetry.interval_ms` | int | `1000` | 500–2000 | Agent, per session (FR-3.5) |
| `retention.raw_sessions_per_game` | int | `20` | 0–10000; **0 = unlimited** | Agent, per session (§Retention) |
| `retention.remove_uninstalled_games` | bool | `1` | | Agent, at every detection sweep (beta.19, D55, FR-1.8): on, an entry whose executable has been gone for ten minutes — its drive connected, the folder it was installed in still there — and that has no session and no anti-cheat block or exception is removed; off, it stays and reads *Not installed* (D41's behaviour) |
| `update.channel` | choice | ~~`stable`~~ `auto` (beta.14, D47) | `auto` · `stable` · `beta` | UI (P4 PR-5 reads it: `beta` = GitHub pre-releases too; `auto` follows the running copy, a pre-release asking for pre-releases — `11_UPDATER` §The update audit) |
| `update.auto_check` | bool | `1` | | UI (P4 PR-5: the startup silent check, `11_UPDATER` §Flow "if enabled") |
| `privacy.online_metadata` | bool | `0` | | *reserved* — no consumer and, since 2026-09-16, no toggle on Settings either: the store request it would enable has no code (CLAUDE.md rule 8), and PRIVACY_POLICY 2.2 removed the row that described it |
+3 -2
View File
@@ -406,9 +406,10 @@ Unchanged in spirit from v1, bumped to `v2` for the new message set.
| `SessionHeld` | A→UI | **Added 2026-09-23.** 1 Hz while a client listens, for a session held unhooked only: `{ sessionGuid, elapsedS, gpuTempC?, cpuTempC?, gpuLoadPct?, cpuLoadPct?, gameVramDedicatedMb?, gameRamPrivateMb? }` — how long it has run and the machine's sensors (and since beta.12 the game process's own memory, read from outside it — optional, an older client ignores them). **Never `SessionProgress`**: its `presents5s`, `presentedQualifier` and `fgMode` are required, and zeros there would put measured-looking numbers on the wire for a session that measures nothing (rule 6 has nothing to show and shows nothing) |
| `SessionProgress` | A→UI | 1 Hz: `{ sessionGuid, elapsedS, presents5s, presentedFps5s?, presentedQualifier, nativeFps5s?, displayedFps5s?, fgFactor?, fgMode, upscaler?, upscalerQuality?, upscalerDriverReported?, renderW/H?, outputW/H?, rtActive?, gpuTempC?, cpuTempC?, cpuLoadPct?, vramProcMb?, latencyUs?, fgRefusal?, fgRuntimeCensus?, gameVramDedicatedMb?, gameRamPrivateMb? }` (the last two added 2026-10-03, beta.12, optional: the game process's dedicated GPU memory and private working set, MiB, from the newest telemetry tick; `vramProcMb` stays reserved for the in-process figure and has no producer) — a 5 s rolling window over the ring through the SAME Domain calculators the row uses (`SessionProgressCalculator`, D13). **`upscalerDriverReported` added 2026-09-21, optional:** `dlss` when the NVIDIA driver reports an NGX super-resolution feature created and evaluated in the target (`03_METRICS` §The driver-reported rung), so the live card says `DLSS (driver-reported)` where no hook can name the upscaler; identity only. **`cpuLoadPct` added 2026-09-21, optional** (CPU time busy over the last telemetry tick, 0–100; `cpuTempC` has a producer from the same date, present only when the Agent is elevated with PawnIO). **Two fields added 2026-09-14, both optional (an older client ignores them, §C):** `fgRefusal` is the row's `fg_refusal` (schema 0003) — present when `fgMode` names a technology and `fgFactor` is absent, so the live card can say "DLSS-G active — factor not counted" rather than N/A; `fgRuntimeCensus` is the raw census so the `fg_runtime_loaded` chip can name the module. **Rule 6 at the wire (2026-09-13):** `nativeFps5s` / `displayedFps5s` / `fgFactor` are present only when frame generation was measured in the window; otherwise `presentedFps5s` stands alone with `presentedQualifier` (`census_not_run` · `no_fg_runtime` · `fg_runtime_loaded` · `none_withheld`, the row's `presented_qualifier` from the same function). Every unmeasured field is absent, never 0. Suppressed when no client is connected |
| `SessionCompleted` | A→UI | `{ sessionGuid, sessionId?, exitStatus, tier, finalize, reason, gameId?, gameName? }` — UI loads the full row from SQLite; `sessionId` is null and `finalize` is `discarded` when the row was not stored (under the minimum length), or `game_removed` when its entry was removed with its sessions while it ran (2026-09-23), or **`faulted` when the session's task threw before it could finalize** (2026-09-23: it follows the `CaptureError SessionFaulted`, with `exitStatus` `interrupted` and `reason` `SessionFaulted`, so the live card and the tray let go of a session that no longer runs; the `.partial` stays for recovery); `exitStatus` is the row's vocabulary (`normal` · `crashed` · `unhooked_safety` · `degraded`); `reason` is the loop's `SessionEndReason`. **`gameId` / `gameName` added 2026-09-23, optional:** the entry the session was stored under — the finalizer's owner when it re-keyed a session whose entry was removed, else the one it started under — so the notice names the session that completed, not whatever the live card last showed |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff, guardReason? }` — **`guardReason` (beta.13, optional)** is the guard's own reason when it named a family; `BlockedService` / `BlockedDriver` is a finding on the PC, not in the game, and the notice says so (§S23-3); `reason` stays the session's end reason — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch`, `PreScanCouldNotVerify` and, since 2026-09-21 (beta.4), `TargetUnreadable` — a protected process the Agent could not open (added 2026-10-04) — `PreScanCouldNotVerify` with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
| `CaptureRefused` | A→UI | `{ gameId, gameName, reason, family?, signal?, hookingTurnedOff, guardReason? }` — **`guardReason` (beta.13, optional)** is the guard's own reason ~~when it named a family~~ **whenever it refused (beta.18; beside a family only until then)**: `BlockedService` / `BlockedDriver` is a finding on the PC, not in the game, and the notice says so (§S23-3), and a refusal no family names is said in the guard's words (`Formats.GuardSentence`) — it printed the end's name, "reason RefusedByGuard"; `reason` stays the session's end reason — **guard fired**; `hookingTurnedOff` (2026-09-22) is true when the finding turned the game's hooking off (`19_SAFETY` §What a finding does to the game); UI shows the plain-language explanation — ~~and the Tier-2 offer~~; there is no alternative measurement to offer, only the option to record the session unmeasured (`08_UI` §Safety events). *(Built: for `RefusedByGuard`, `RefusedPreviouslyBlocked`, `RefusedKillSwitch`, `PreScanCouldNotVerify` and, since 2026-09-21 (beta.4), `TargetUnreadable` — a protected process the Agent could not open (added 2026-10-04) — `PreScanCouldNotVerify` with no family, because "could not verify" is neither a hit nor a pass; `family`/`signal` are the verdict's. A game merely not enabled or not consented raises nothing: that is an ordinary Tier-2 row, not a refusal to explain.)* |
| `CaptureDegraded` | A→UI | `{ sessionGuid, from: 1, to: 2, reason }` — Tier 1 → Tier 2 mid-flight, or overlay self-disabled. **Under a two-rung ladder this means measurement STOPPED**, not that it continued at lower fidelity, and the notice must say so. *(Since beta.18 it says the end in words, `Formats.EndReasonText`; it printed `reason` raw — "The hook stopped (WriterSelfDisabled); the session continues without measuring" — and a stop ends the session, it does not continue it.)* *(Built: `SupervisionLost`, `WriterSelfDisabled`, `WriterStoppedBlocklisted`, `WriterNeverInstalledHooks`, `SupervisionFaulted`, `KillSwitchEngaged` — `RecordedSessionEvents.Classify` is the table.)* |
| `SafetyUnhook` | A→UI | `{ sessionGuid, family?, signal?, hookingTurnedOff, guardReason? }` — `guardReason` as on `CaptureRefused` (beta.13) — anti-cheat appeared mid-session; prominent UI notice; `hookingTurnedOff` as on `CaptureRefused`. *(Built: the verdict that FIRED, not the pass that started the session — `CaptureOutcome.Verdict` carries the supervisor's last verdict on this reason since 2026-09-13.)* |
| `GameRemoved` | A→UI | `{ gameId, gameName?, exePath, reason }` — **since beta.19 (D55):** the Agent removed a library entry by itself; `reason` is `uninstalled` (its executable gone for ten minutes from a folder that is still there, no session, no anti-cheat block or exception — `06_DATA_MODEL` §Writer ownership). Not a session event. The Games page on screen reloads and says so; a game page showing that entry reloads into its not-found state. Additive: a client that does not know the type ignores it (§Versioning). |
| `HookingTurnedOff` | A→UI | `{ gameId, gameName?, reason, family?, signal? }` — **since 2026-09-25 (beta.8):** the Agent's pre-scan of the library (`19_SAFETY` §What a finding does to the game) found anti-cheat in a game whose hooking the user had turned on, and turned it off. Not a session event — no session is running — so the UI's notice carries no "record without measuring" action, only Dismiss (`SafetyNoticeKind.HookingOff`). A finding on a game whose hooking was already off sends nothing: its page and its library card change, nothing the user switched on did. Additive: a client that does not know the type ignores it (§Versioning). |
| `CaptureError` | A→UI | `{ sessionGuid?, code, message }` — `InjectFailed`, `RingVersionMismatch`, `AttachRefused`, ~~`EtwAccessDenied`~~ (struck 2026-09-13 with the tier), ~~`PresentMonMissing`~~ (retired with the tool, 2026-08-27 — a code naming an implementation nobody chose), `TelemetryUnavailable`, `DbWriteFailed`, `SessionFaulted` (the session's task threw before finalize; the `.partial` stays for recovery, and ~~no `SessionCompleted` follows~~ a `SessionCompleted` with `finalize: faulted` follows since 2026-09-23). *(Built: `RingVersionMismatch` for a layout / record-size / build-id refusal — the "restart the game after an update" case — `AttachRefused` for the rest of the ring's refusals, `InjectFailed` for a target that could not be started, pinned, read or singled out.)* |
| `Ping`/`Pong` | ~~both~~ UI→A | 15 s keepalive, **client-driven** (built 2026-09-13): the client pings, the Agent answers; the Agent initiates nothing on an idle connection |
+87 -13
View File
@@ -27,7 +27,10 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
> `ViewerModeTests`); the pill reads *Viewer — no Agent*, a persistent InfoBar names the folder, and every control that
> would ask the Agent or change the PC is disabled — hooking, the exception's grant and withdrawal, re-enabling, Delete
> all sessions, the kill switch, the admin mode, the logon task, the Vulkan layer, Start with Windows, the automatic
> update check, Help ▸ Check for updates, Tools ▸ Update detection rules and the tray's Pause. The profile's own folder
> update check, Help ▸ Check for updates, Tools ▸ Update detection rules and the tray's Pause — and, since beta.18,
> every setting the Agent reads (the user-mode exception option and the three Recording numbers had been missed, and a
> change said the capture agent would read it) and the update channel beside the update check
> (`ViewerModeTests.EverySettingTheAgentReadsIsOffInAViewer`). The profile's own folder
> is refused however it is spelled (case, separators, a relative path, a junction), as is a folder that does not exist;
> a refusal is a message box and exit 2. The viewer's folder is its own single-instance key, so it runs beside the
> profile's App. D6 is unchanged: the Agent's `--data-dir` stays under `--console`.
@@ -44,12 +47,16 @@ WPF + **WPF UI (Wpf.Ui, Fluent)**. Shell = `ui:FluentWindow` with custom `ui:Tit
> rendered — below; corrected 2026-10-04). It is information, not one of FR-11's documents:
> nothing is accepted or recorded, and the Disclaimer points at it.
>
> **Help ▸ User guide, beta.12 (D44).** `guide/` — eight short English pages for players (install, record a game, read
> your results, anti-cheat and safety, your data, questions and answers, the terms in plain words) — embedded in the
> **Help ▸ User guide, beta.12 (D44).** `guide/` — ~~eight~~ short English pages for players (install, record a game, read
> your results, anti-cheat and safety, your data, questions and answers, the terms in plain words; *since beta.17, D54,
> also the screens, every setting, what to do when something goes wrong and the words the App uses — twelve pages,
> and the wiki's End-user part*) — embedded in the
> App (`Services.EmbeddedDocuments.Guide`, titles from each page's first heading) and shown in a `Windows/DocumentWindow`
> with a page list, Limitations last; a link between guide pages opens the page in the window. Help ▸ Documentation is
> *Online documentation*: the README at this build's source. `GuideDocumentsTests` holds every page listed and titled and
> every link leading somewhere.
> every link leading somewhere — and since beta.17 every section link (against the anchors the App's renderer gives the
> target), the contents in the App's order, and that *Every setting* and *The screens* name every setting the Settings
> page shows and every page and menu item of the main window.
>
> **Documents are rendered, beta.12 (owner request 4, D45).** Every Markdown document the App shows — the Legal Gate's
> three texts, Help ▸ Limitations, the update notes, About's documents — is drawn by `Markdown/MarkdownRenderer`
@@ -124,7 +131,7 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
## 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.
- **In-app, persistent** (Agent offline, ~~PawnIO missing,~~ update downloaded, a viewer's folder, the safety notices): `ui:InfoBar` banner pinned above content with action button. *(Corrected 2026-10-07: no PawnIO banner was ever built — CPU temperature reads N/A, and Settings ▸ System says it needs the admin mode and PawnIO; the viewer's banner (D52) and the safety notices were missing from the list.)*
- **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.
@@ -163,6 +170,26 @@ The Menu sits in its own row **below** the TitleBar (never inside the drag regio
> reads as before. Tests: `SafetyNoticesTests.AServiceOrDriverIsOnThisPcAndAModuleIsInThisGame`,
> `…AnUnhookSaysWhereTheFindingWasAndPromisesNoReEnable`, `Tier2ReasonTests`.
>
> **Every notice in words — beta.18** (found while writing the guide, beta.17). Three texts printed what only the code
> knows. The gate's own refusals — *Disable all hooking*, a game blocked before — carry the gate's label where a finding
> carries its family, and the kill switch's notice read *"kill switch was detected in this game (the global 'disable all
> hooking' switch is on (FR-2.4); …). FrameLedger will not inject into it, and nothing overrides that."* They are said as
> the session's end now (`Formats.EndReasonText`: "All hooking is switched off in Settings, so nothing was measured."),
> never as a finding. A refusal no family names read *"The anti-cheat guard did not hook this game: reason
> RefusedByGuard."*: the events carry the guard's own reason for every refusal since (`07_IPC`), and the sentence is its
> words — "… the game is 32-bit, and the hook runs in 64-bit games only."; an older Agent's reads `End_RefusedByGuard`.
> A 30 s re-scan that could not look while the game still ran read *"Capture stopped: Access is denied. was detected while
> the game was running"*; it reads `Safety_Unhooked_Unnamed_Format` ("Capture stopped while the game was running — the
> game's process could not be opened — and FrameLedger unhooked."). And `CaptureDegraded` printed its reason raw and said
> the session went on — *"The hook stopped (WriterSelfDisabled); the session continues without measuring."* — where a stop
> ends it: the notice is the end's own sentence ("The measuring hook turned itself off after repeated faults, so measuring
> stopped."), and `Notice_Degraded_Unknown_Format` names only a reason this build has no words for. Tests:
> `NoticesFromTheAgentTests` builds each event as the Agent does — the gate's verdicts, the native facade's
> (`AntiCheatVerdict.FromNative`), `RecordedSessionEvents.PublishReason`, the wire's codec — walks every refusal and every
> stop, and refuses an enum's name, a requirement's id or "reason X" in any notice; it went red on the unfixed code with
> exactly the texts above. Until then the notices' tests raised events written by hand ("GuardBlocked", "HookFaulted", a
> guard reason sent as the end), which no Agent sends.
>
> **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.
@@ -245,7 +272,17 @@ All screens are `Page`s registered with the navigation page provider and navigat
> since (`ImportLibraryFlow.RunAsync(onlyNew: true)`: *No new games* and no checklist when there are none), and every entry
> whose executable is not on disk carries a **Not installed** pill — its tooltip is the game page's own sentence for it,
> the drive that is not connected or the path the file is gone from (`GameLibrary.ExecutableExists` and
> `Formats.ExecutableMissingText`, asked off the UI thread on every listing, never stored; nothing is removed for it). **The page reloads by itself** while it is on screen when a session ends (`SessionCompleted`) or an
> `Formats.ExecutableMissingText`, asked off the UI thread on every listing, never stored; ~~nothing is removed for it~~
> *since beta.19 (D55) the Agent removes such an entry by itself after ten minutes when it has no session and no
> anti-cheat block or exception, and its drive is connected — Settings ▸ Data ▸ Remove uninstalled games, on by default; the
> page on screen hears `GameRemoved`, reloads and says so in the snackbar (`Games_Removed_Format`); one with sessions keeps
> its pill. One check removes its games in one event each, milliseconds apart: the page waits `GamesViewModel.RemovalSettle`
> (one second) after the first, then reads the library once and says them all in one notice — the count, five names and
> how many more, `Games_Removed_Many_Format`. It said each and reloaded each, and WPF UI 4.3.0's `SnackbarService` shows every
> message at once in its one snackbar, so only the last name stayed on screen. And only the newest read of the library is
> shown: reads overlap — a session that ends, an import, a removal — and the one that started first could finish last,
> its executable checks waiting on a slow drive, and put back a removed game's card (`GamesViewModel.LoadAsync`,
> `GamesViewModelTests.AnOlderReadThatFinishesLastIsNotShownOverANewerOne`)*). **The page reloads by itself** while it is on screen when a session ends (`SessionCompleted`) or an
> import adds games (`LibraryChanges` — navigating to the page already on screen does nothing in WPF UI 4.3.0, so an
> import from the menu never showed until the page was left). **Import** (FR-1.2): the games already in the library — at
> this path or under another drive letter — are hidden by default (*Show the N games already in the library* brings them
@@ -272,7 +309,10 @@ All screens are `Page`s registered with the navigation page provider and navigat
> fields), **the row's executable path under the subtitle and Change executable… since 2026-09-21** (a store import
> guesses the executable and everything downstream is keyed on it; the pick re-points the row, which comes back
> hooking-off and unconsented like a new game, consent revoked over the pipe first, a block never cleared —
> `05_DETECTION` §Library import), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), ~~**the guard-bypass switch since 2026-09-21**~~ **withdrawn 2026-09-22** (the card, its dialog, the session mark and the export line are gone; a blocked row's toggle is disabled and `Safety_Blocked_Toggle_Format` is the whole story; a refusal or unhook notice that turned hooking off ends with `Safety_HookingTurnedOff` — `19_SAFETY` §What a finding does to the game), **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
> `05_DETECTION` §Library import; **since beta.19 the file dialog opens in the game's own folder** — `GameFolder.StartFolder`:
> the store boundary's install folder (`InstallRoot`), an Unreal package's root above `<Project>\Binaries\Win64`, else
> the executable's folder, and the nearest folder still there when that one is gone; nothing for a drive that is not
> connected, where Windows opens its last folder; owner request 2026-10-12, `GameFolderTests`), **one App per data folder since 2026-09-21** (`Services.SingleInstance`: a named mutex and a named event keyed on a hash of the data directory, claimed in `Program.Main` after Velopack's hooks and before any window; a later start sets the event and exits 0, and the first instance brings its window forward through `ShellHost.Reveal` — from the tray too. Nothing stopped a second App before: the owner's log shows two started 360 ms apart, two tray icons, a second log file. `--diag` never claims), ~~**the guard-bypass switch since 2026-09-21**~~ **withdrawn 2026-09-22** (the card, its dialog, the session mark and the export line are gone; a blocked row's toggle is disabled and `Safety_Blocked_Toggle_Format` is the whole story; a refusal or unhook notice that turned hooking off ends with `Safety_HookingTurnedOff` — `19_SAFETY` §What a finding does to the game), **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
@@ -347,6 +387,14 @@ All screens are `Page`s registered with the navigation page provider and navigat
> `FormatsTests`, and the page renders in `PagesLoadTests`. **The Details card's *NVIDIA App override* row** (same day)
> is the newest session that read a driver profile, in the same words; no row where none did. Tests:
> `NvidiaOverridesTests`, `GameDetailViewModelTests.TheDetailsCardNamesTheNvidiaAppsOverridesFromTheNewestSessionThatReadThem`.
> **The *Engine* row carries the version, and an *Engine version* row says what it was read from** (beta.10 for Unreal;
> beta.19 for Unity, Godot and RPG Maker; beta.20 for Ren'Py — `05_DETECTION` §Engine version): the player library, the
> data file's header, a data pack, a core script, the RGSS library `Game.ini` names or Ren'Py's `renpy/vc_version.py`, and
> *Not found in the game's files* once the Agent has
> read such a title and found none. RPG Maker's witness names the maker on the page, the subtitle and the library card
> (*RPG Maker MZ 1.10.0*, *RPG Maker VX Ace (RGSS 3.0.1)*; `Formats.Engine(id, source)`). Tests:
> `GameDetailViewModelTests.TheDetailsCardSaysWhatAUnityGodotOrRpgMakerVersionWasReadFrom`,
> `FormatsTests.TheVersionsWitnessNamesTheMakerAndRgssSaysWhoseNumberItIs`.
- 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".~~ (not built; Compare's own picker chooses) Tier-2 rows render ~~`—`~~ `N/A` (not blank, not zero) in Tier-1-only columns, with a tooltip explaining why *(corrected 2026-10-04: as built — `—` means a measured none, §FPS display rule)*.
2. **Frametime** — ScottPlot timeline of selected session (decimated), stutter markers, sensor overlay toggle (temp on right axis).
@@ -604,13 +652,19 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
### Settings
> **beta.14 (owner request 2026-10-05: "an option to hide the scroll bars but still scroll").** The Window section has
> **Hide scroll bars** (`ui.hide_scrollbars`, off by default). A bar's visibility is bound inside its scroller's template,
> which no style reaches, so `Services.ScrollBarHiding` sets the scrollers themselves: one class handler on
> `ScrollViewer`'s Loaded (registered at start beside `DialogKeyboard`) reaches every scroller the App shows, those inside a
> DataGrid, a TextBox, a rendered document and a dialog included. While on, an axis that is `Auto` or `Visible` becomes
> which no style reaches, so `Services.ScrollBarHiding` sets the scrollers themselves: ~~one class handler on
> `ScrollViewer`'s Loaded (registered at start beside `DialogKeyboard`) reaches every scroller the App shows~~ class
> handlers on `ScrollViewer`'s ScrollChanged and Loaded (registered at start beside `DialogKeyboard`) reach every scroller
> the App shows *(corrected 2026-10-07, beta.17, the owner's screenshot of the Dashboard with its bar: WPF raises Loaded
> only where a subtree listens for it with a handler of its own, and a class handler is not one — `16_WPFUI_SYNTAX`
> §Gotchas. Settings, full of toggle switches whose template listens, lost its bar; the Dashboard, the first run, About,
> the user guide and a game's wide sessions table kept theirs. Every scroller raises ScrollChanged from its first layout)*,
> those inside a DataGrid, a TextBox, a rendered document and a dialog included. While on, an axis that is `Auto` or `Visible` becomes
> `Hidden` — WPF's "no bar, still scrolls": wheel, keyboard and touch — and its own value is kept on it; a `Disabled` axis is
> never touched (it lays its content out at the viewport's width). The toggle applies to the open windows at once, and off
> puts every kept value back. Tests: `ScrollBarHidingTests` (on hides every bar and the wheel still scrolls; off restores
> each; a scroller that loads later follows), `SettingsViewModelTests.HidingScrollBars…`.
> each; a scroller that loads later follows; since beta.17 a scroller laid out with no Loaded at all, and every page,
> window and dialog shown in a real window with the option on), `SettingsViewModelTests.HidingScrollBars…`.
> **beta.11 (owner request 2026-10-03: "remove the Settings rows that have no button or similar").** Every row has a control
> now: the *Games with hooking on* card shows only while a game has hooking on (its empty sentence is gone); the *Elevation*
@@ -618,6 +672,10 @@ Tail view of `ui-*.log` / `agent-*.log` (toggle), level filter, search (`ui:Auto
> sentence under the language row is gone. A **Data** section has one row, **Delete all sessions…** (FR-1.7): the
> confirmation names how many, the Agent deletes them (`DeleteSessions`), and the strip says what happened or why nothing
> was deleted (a session being recorded, no agent, an older agent). Tests: `SettingsViewModelTests.DeleteAllSessionsAsksWithTheTotalThenGoesThroughTheAgent`.
> **Since beta.19 (D55) the Data section's first row is *Remove uninstalled games*** (`retention.remove_uninstalled_games`,
> on by default, off in a viewer like every setting the Agent reads): its strip says the Agent reads it within 15 seconds
> (`Settings_RemoveUninstalled_Applied`), not at the next session — the detection sweep reads it at every pass. Tests:
> `ViewerModeTests.EverySettingTheAgentReadsIsOffInAViewer`, `GuideDocumentsTests.TheSettingsPageOfTheGuideNamesEverySetting`.
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.
@@ -639,7 +697,8 @@ Agent section: elevation state with a plain explanation of what elevation *optio
> **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
> session start" line, D16 — but for turning the kill switch on, which says a game being measured stops at its next
> safety scan, within 30 seconds: beta.18; until then it said the next session start). **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,
@@ -759,7 +818,8 @@ the requirement was one bullet under §UX rules, and nothing checked it.
| **Arrows, Home/End, Page Up/Down** | Move within a `DataGrid` (Sessions, Compare picker, Import checklist) | `DataGrid` defaults |
| **Esc** | Closes the open `ContentDialog` or `MessageBox` with no result — the same as its Close/Cancel button | `DialogKeyboard`, one class handler per dialog type registered at start-up |
**Esc is the Close button, never the primary one.** On the consent dialog (FR-2.1) that is "Keep it off": nothing is
**Esc is the Close button, never the primary one.** On the consent dialog (FR-2.1) that is ~~"Keep it off"~~ "Keep hooking
off" *(the button's text, corrected 2026-10-07)*: nothing is
stamped. A dialog that offers no Close button is not dismissed by Esc, and the Legal Gate (FR-11) is a window of its own
(`FirstRunWindow`) with explicit Decline and Accept, on which Esc does nothing. WPF UI 4.3.0 handles no key in
either dialog type (its `ContentDialog.cs` and `MessageBox.cs` at tag 4.3.0 have no key handler — read 2026-09-15),
@@ -834,6 +894,20 @@ palette per theme, chosen with the theme).
> summary, every dialog's content and the safety InfoBar, made under one theme, switched, and compared text by text with
> the same surface made fresh under the other — both ways). Both went red on the unfixed XAML, the second with 146 stale
> texts each way, before they went green.
>
> **A fifth hole, closed 2026-10-07 (beta.18; the owner's screenshots of beta.17 in the dark theme: every page's title and
> section headings near-black on the dark window — beta.16's screenshot shows it too).** This text had no colour of ours,
> because it had none. A page is shown in WPF UI's `NavigationViewContentPresenter`, a `Frame`, and a Frame passes no
> inherited value into its page (`InheritanceBehavior.SkipToAppNow`), so a text that sets no colour falls to the TextBlock
> default, which WPF UI 4.3.0 makes black (`16_WPFUI_SYNTAX` §Gotchas). Cards, grids and controls set their own; the bare
> titles and headings did not: 19 texts on the six pages at 1.29:1. Every check above laid a page out straight in a
> window, whose text colour the page then inherited — a page the App never draws — and a page on screen during a theme
> switch did take the window's colour, while each navigation makes a new one that does not, so it came and went. Every
> page sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"` on its root. Held two ways:
> `AccessibilityTests.EveryPageSetsItsOwnTextColour`, and `PagesLoadTests.EveryTextIsReadableInBothThemes` — every
> surface hosted as the App hosts it, a page in the presenter, and every text that shows ≥ 3:1 over the colour painted
> under it, in both themes. `EveryTextFollowsAThemeSwitch` hosts its pages in the presenter too since, and went red with
> them: a page made after a switch stayed black. All three went red on the unfixed XAML before they went green.
### DPI
+12
View File
@@ -272,6 +272,16 @@ substitutes it with ~~the tag date~~ the run's UTC date (corrected 2026-10-04) w
address — is resolved in the source files, because an unsubstituted token in a
document the app displays for acceptance (FR-11) is a defect, not a template.
**The build id is read before it (beta.18).** The substitution edits tracked files, and the native build id is
`git describe --dirty` at CMake's configure (`src/native/FrameLedger.Shm/CMakeLists.txt`): every release until beta.18
shipped `<tag>-dirty` — the owner's Dashboard read *Overlay build v0.1.0-beta.17-dirty*, and that run's log printed
`FL_BUILD_ID = v0.1.0-beta.17-dirty` two lines after `RELEASE_DATE = 2026-10-07 in 3 file(s)`. `release.yml` now reads
describe from the clean checkout first, refuses one that is already dirty or longer than 31 characters, and passes it
as the environment's `FL_BUILD_ID`, which CMake takes as given (checked for the characters a C string literal carries);
after the publish, `tools/buildid-check.ps1` reads it back out of the four native binaries that compile it, by their
bytes — nothing is loaded. A developer's build still runs describe itself (`+` marks a dirty tree when the long form
would not fit).
## Local quality gate (pre-push)
`./build.ps1 check`:
@@ -298,8 +308,10 @@ document the app displays for acceptance (FR-11) is a defect, not a template.
13b. `tools/accuracy-check.ps1 -SelfTest`, then live — the accuracy block is ONE text (`legal/ACCURACY.md`) embedded verbatim in `README.md` and `legal/DISCLAIMER.md` §4; a copy that drifted, a copy with no markers, or an empty source is red. Four self-test cases, both directions (§S23-6, 2026-09-06)
13c. **`tools/notice-check.ps1 -SelfTest`, then live** (beta.12, owner decision D45, 2026-10-03) — every first-party source file (`.cs .cpp .h .inl .ps1 .xaml`, tracked or new, minus `src/native/third_party/`) opens with `SPDX-License-Identifier: GPL-3.0-only` and `Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE` in its own comment syntax, because GPLv3 §7 wants additional terms named "in the relevant source files" (`NOTICE` carries them); the second line may name another holder and year in the same form (a contributor's own file).
Seven self-test cases, both directions; `./tools/notice-check.ps1 -Fix` writes a missing header, and `tools/resx-gen.ps1` generates the accessor with it
13d. **`tools/wiki-build.ps1 -SelfTest`, then `-Check`** (beta.17, owner decisions D53/D54, 2026-10-07) — assembles the GitHub Wiki from `wiki/`, `guide/` and `LIMITATIONS.md` into a temporary folder, as `wiki.yml` does at a release (`13_CI_CD` §wiki.yml), and fails on a link to a file, folder or section that does not exist, two sources for one page, a page that neither Home nor the sidebar leads to, a sidebar that lists the guide in another order than `guide/README.md`, a backticked repository path in a `wiki/` page that names nothing, and a version number written into a `wiki/` page (the footer says which release the wiki shows). Nine self-test cases, both directions
14. `tools/changelog-check.ps1 -SelfTest` — nine cases, five expected RED. The live half needs a pull request's changed-file list and is supplied by `ci.yml`
14b. `tools/release-notes.ps1 -SelfTest` — five cases over a fixture changelog (a dated and an undated section, a missing one, a prefix that must not match, an empty one). The live half needs a tag's version and runs in `release.yml`, where a missing or empty section is a red release (P4 PR-5)
14c. **`tools/buildid-check.ps1 -SelfTest`** (beta.18) — eight cases, both directions: a binary built from a dirty tree (`-dirty`, or the short form's `+`), one with no id, a missing one, and an expected id that is dirty or not an id are red. The live half needs the release's clean-checkout id and runs in `release.yml` over the published tree (§Release-time token substitution)
15. `tools/resx-audit.ps1` — ~~**skipped loudly; it does not exist, and no `.resx` file does either**~~ **built 2026-09-13 (P3 PR-2)**: `-SelfTest` first (11 fixture cases, both directions), then the live pass over every `Strings.resx` family under `src/` — key sets equal across en/vi/ja, `Safety_*` in `ja` marked for review or signed, `Strings.Designer.cs` current with `tools/resx-gen.ps1`. A tree with no family is red (`09_I18N` §Translation workflow)
16. **struct-mirror** — reads this run's `.trx` and fails when `ShmLayoutMirrorTests` did not execute, so deleting the mirror test is red as well as breaking it
16b. **`tools/test-artifacts-check.ps1`** — `-SelfTest` first (seven cases, two RED), then live: an `overlay-*.log` created since this gate started, still in the real `%LOCALAPPDATA%\FrameLedger\logs` after the tests, whose first line names a `hook-harness*` image, fails the gate. It is what makes a test binary without its log sweep red (`17_HOOK_ENGINE` §Native logging, 2026-09-15); a game's log never counts
+40 -1
View File
@@ -52,6 +52,17 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
case. `Kill` now waits for exit (bounded, asserted) and the delete retries. Not §S19(b) either — a test-harness
race, and the third flake shape of the day (the registry-subtree race between `VkLayerRegistrationTests` and the
GOG reader's test, fixed in #188) was the same kind.
- **Two more on 2026-10-07 (beta.18), both re-run green and then fixed the same day.**
`WhenTheTargetExitsTheHostStopsAndSaysWhy` ended **`TargetNotRunning`** (#286, run 37619719203): the host resolves its
target once, as it starts, and a host slower than the harness's 6 s hold found it gone — the shape recorded since
2026-09-21. The hold is 15 s: a margin, not a signal, because the host prints nothing until its session ends.
`LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing` ended **`RefusedByGuard` / `ModuleScanFailed`**
(#288, run 37627351438): the hosted runner has the Vulkan loader and no device, so the harness exits 77 with a
`[SKIP]` line — but the runner is elevated, the host starts the harness through `CreateProcessWithTokenW`
(`UnelevatedProcess`), the child gets no stdout, and the line never reached the host's output; the test then
depended on the session reading `LaunchTargetExited`, and a scan that hit the dying harness failed it instead. The
test now asks the harness directly, before the host runs (exit 77 = skip, with the harness's own line); hiding the
Vulkan ICDs from that probe makes it skip in under a second, and on a machine with a device it runs in full.
- **A re-run ERASES the evidence, which is why the count above had to be kept by hand.**
`gh run rerun --failed` updates the original run's conclusion, so `gh run list` showed **18 success, 1
cancelled, 0 failed** across the twenty runs that contained all three failures above. Anyone measuring
@@ -127,6 +138,10 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
`VERSION` file (`12_BUILD` §Version); and `CHANGELOG.md` must carry a **non-empty** `## [x.y.z]` section for the
full version, extracted by `tools/release-notes.ps1` (self-tested on every `build.ps1 check`). A missing
section is a red release, not an empty note — the ledger's header said the opposite for five weeks.
- **The build id from the clean checkout** (beta.18): `git describe --always --dirty --abbrev=12` before anything edits a
tracked file — a dirty one or one over 31 characters stops the run — into `FL_BUILD_ID` for CMake. Until beta.18 the
substitution below ran first and every release's natives called themselves `<tag>-dirty` (`12_BUILD` §Release-time
token substitution).
- `{{RELEASE_DATE}}` substituted in `legal/*.md` with the run's UTC date **before the build**, because the App
embeds those documents (FR-11); any `{{` token left anywhere after that fails the job.
- **The identical gate** — `./build.ps1 check`, native first, every tool including `versioninfo-check` against
@@ -184,6 +199,29 @@ FrameLedger uses the **`poli0981/.github` ops repo** where its templates fit, an
- **The `anticheat` block gets extra scrutiny:** schema-valid, non-empty, no entry removed without a justification in the PR body. Removing a blocklist entry is a safety change and requires the same review as a security fix. *(Added 2026-10-04: the PR-only removal step fails the job on any removal, a shrunk per-title list or an added trusted signer, whatever the body says — the justification is for the reviewer, and the job stays red.)*
- `permissions: contents: read`.
### `wiki.yml` — after a successful Release run, and by hand · **repo-local, built 2026-10-07 (beta.17, D53/D54)**
- **What:** the GitHub Wiki is a copy of the repository's own pages — `wiki/` (Home, the sidebar, the developer pages)
and `guide/` (the user guide: the End-user part, the same pages the App shows) with `LIMITATIONS.md`.
`tools/wiki-build.ps1` names each page (a guide page after its first heading, `guide/README.md` as *User-guide*,
`LIMITATIONS.md` as *Limitations*), rewrites links between pages to page names and every other repository link to
its address on GitHub **at the release's tag**, drops each page's first heading (the wiki prints the page name), and
writes a footer naming the tag. The same assembly is `build.ps1`'s `wiki-check` gate (`12_BUILD` §Local quality gate,
13d), so a dead link is red on the pull request, never on the published wiki.
- **When:** `workflow_run` on `Release`, completed — the job runs only when that run succeeded and was started by a
pushed `v*` tag, so a `workflow_dispatch` rehearsal of `release.yml` never publishes. It checks out the run's
`head_sha` (a `workflow_run` job runs `main`'s copy of this file) and links at `head_branch`, the tag. By hand:
`gh workflow run wiki.yml -f ref=main -f publish=false` builds, checks and uploads the pages as an artifact; with
`publish=true` it publishes them.
- **Why not a step of `release.yml`:** the release stays as it was, its rehearsal stays a pure rehearsal, and a wiki
that fails to publish is a red run of its own that can be re-run — a step after `gh release create` could never be
re-run, the release already existing. A release created with `GITHUB_TOKEN` fires no `release` event for other
workflows; `workflow_run` fires because the Release run itself was started by a tag push.
- **Publishing:** `gh auth setup-git`, a clone of `<repo>.wiki.git`, everything but `.git` replaced, a commit as
`github-actions[bot]` only when something changed, `git push origin HEAD:master` (the wiki's branch is `master`). A
page edited on the Wiki tab is overwritten at the next release: edit `wiki/` or `guide/`.
- `permissions: contents: write` — the repository's default workflow token is read-only (read from the API,
2026-10-07), and pushing to the wiki repository needs write.
## Dependabot (`.github/dependabot.yml`)
```yaml
@@ -215,7 +253,7 @@ Central package management makes Dependabot PRs single-file diffs.
**In the tree — done:**
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph
- [x] Repo-local `ci.yml`, `codeql.yml`, `release.yml`, `rules-publish.yml` (all four repo-local by decision, §Workflows); ~~caller stubs pointing at `poli0981/.github`~~ — never the design, see the first paragraph *(and `wiki.yml` since beta.17, repo-local too: five)*
- [x] Issue forms `bug_report.yml`, `feature_request.yml`, `safety_gap.yml`; `ISSUE_TEMPLATE/config.yml` pointing a vulnerability at private reporting; PR template referencing CLAUDE.md's definition of done
- [x] `.github/dependabot.yml` (nuget + github-actions, weekly)
- [x] `SECURITY.md` — the private route for a vulnerability, the public route for a safety gap, and the honest response intent (2026-09-16)
@@ -227,4 +265,5 @@ Central package management makes Dependabot PRs single-file diffs.
- [ ] `Rules / validate` as a required check (§S23-2, after its skip-shim)
- [ ] Dependabot alerts + security updates (the manifest is in the tree; the alerts are a setting)
- [x] Private vulnerability reporting enabled (Settings ▸ Security), so `config.yml`'s link resolves *(marked 2026-10-04: GitHub reports it enabled)*
- [ ] Wiki editing restricted to collaborators (Settings ▸ General ▸ Features ▸ Wikis ▸ *Restrict editing to collaborators only*): otherwise anyone with a GitHub account can change a page until the next release overwrites it (§wiki.yml, beta.17)
- [ ] Repo topics: `windows`, `wpf`, `benchmark`, `fps`, `game-performance` (~~`presentmon`~~ — dropped 2026-08-27, §G)
+20
View File
@@ -71,6 +71,26 @@ under the new theme. `PagesLoadTests.Surfaces` builds every page, window and dia
any check that wants all of them. Colours are compared and texts only reported: another test class may change
`Strings.Culture` between the two builds.
**A page is measured in the Frame the App shows it in, and a theme brings its accent (beta.18).** WPF UI's
`NavigationViewContentPresenter` is a `Frame`, which passes no inherited value into the page, the text colour included, so
a page laid out straight in a window measures the window's colour and not the App's: the theme-switch check above did, and
stayed green over every page title drawn black (`08_UI` §Contrast, fifth hole). The rendered checks host a page in the
presenter (`PagesLoadTests.Hosted`), and `PagesLoadTests.EveryTextIsReadableInBothThemes` measures every surface's shown
texts at ≥ 3:1 in both themes. `Visuals.UnderTheme` switches as the App does — the accent resources derived for the theme
from Windows' default accent (`Visuals.DefaultAccent`, the App's derivation rather than the machine's own palette), then
the dictionary — and puts the application's own resources back afterwards. The accent lives in `Application.Resources`,
not in a theme dictionary; until then a check under Light measured the dark theme's link blue on the light window, 1.9:1,
a colour the App never shows. The theme-switch check compares what can be seen: a text only one of the two instances holds
counts where it shows, and a collapsed part is not compared (a switch re-applies the template of a DataGrid's idle scroll
bar, and its glyphs exist in the switched instance only).
**Loaded needs a shown window, and even then it is not raised everywhere (beta.17).** A tree laid out by hand never raises
Loaded, and a shown one raises it only where a subtree listens for it (`16_WPFUI_SYNTAX` §Gotchas) — so a test that calls
`RaiseEvent(Loaded)` proves a handler, never that WPF reaches it. `ScrollBarHidingTests.EverySurfaceShownWithTheOptionOnDrawsNoBar`
shows each surface in a real window, off the screen and never activated, with the option on before anything is built as
at start-up; `WpfRaisesLoadedOnlyWhereASubtreeListensForIt` checks the harness against WPF itself (a scroller holding a
Border is never loaded, one holding a CheckBox is), on CI too.
**A test that sends input must also say which keys are held.** `Keyboard.Modifiers` is the machine's real keyboard, read
from any thread (a fresh background thread's `GetKeyState` reports the machine's NumLock — measured 2026-10-06), so a
wheel test that read it held whatever key a person pressed while the gate ran: `ChartWheelTests`' plain half went red once
+24 -1
View File
@@ -152,6 +152,8 @@ Native `Menu`, `TabControl`, `ComboBox`, `Slider`~~, `ListView`~~ are fine — t
styles (`Styles/FrameLedger.xaml`), or the `Pill` style with a `SystemFillColor*BackgroundBrush` and an explicit text
brush; `ContrastTests` refuses all five (`08_UI` §Contrast).
- Do **not** set `Background` on `FluentWindow` (kills Mica). Page backgrounds transparent by default.
- **Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`** (2026-10-07): the navigation's
Frame passes no text colour into a page, and a text with none is black (§Gotchas).
- Exception to the no-hex rule: the chart palette — defined once per theme in ~~`Styles/ChartPalette.xaml` (two dictionaries)~~ `Styles/ChartPalette.Dark.xaml` and `ChartPalette.Light.xaml` (corrected 2026-10-04), never inline.
## FlowDocument (rendered documents, beta.12)
@@ -254,7 +256,17 @@ On startup and on `ApplicationThemeManager.Changed`: for every live plot set fig
- [ ] **A scroll bar's visibility is bound inside its scroller's template** (`ComputedVerticalScrollBarVisibility`), so a style
on `ScrollBar` or `ui:DynamicScrollBar` cannot hide it. Set the scroller's own `ScrollBarVisibility` to `Hidden` — no
bar, and the wheel, the keyboard and touch still scroll (`ui:PassiveScrollViewer` treats only `Disabled` as "cannot
scroll") — as `Services.ScrollBarHiding` does for `ui.hide_scrollbars` (beta.14).
scroll") — as `Services.ScrollBarHiding` does for `ui.hide_scrollbars` (beta.14), reaching each scroller from a class
handler on `ScrollChanged` since beta.17 rather than from `Loaded` alone (next item).
- [ ] **A class handler on `Loaded` is not a load hook.** WPF raises Loaded only on an element whose subtree listens for it
with a handler of its own — an instance handler, a style's `EventSetter`, a template's trigger
(`BroadcastEventHelper.OnBroadcastCallback` walks only into `SubtreeHasLoadedChangeHandler`;
`FrameworkElement.ThisHasLoadedChangeEventHandler`) — and `EventManager.RegisterClassHandler` counts as none of them.
WPF UI 4.3.0's `ToggleSwitch`, `CheckBox` and `ProgressRing` templates carry a Loaded trigger, so a scroller over those
loads and a scroller over plain cards and text never does: `ScrollBarHiding` hid Settings' bar and not the Dashboard's
(beta.17). To reach every instance, hook an event the element raises itself — a scroller's `ScrollChanged` comes from its
first layout. `ScrollBarHidingTests.WpfRaisesLoadedOnlyWhereASubtreeListensForIt` keeps the behaviour visible, and a test
that raises Loaded with `RaiseEvent` proves the handler, never that it is reached.
- [ ] **No dialog in 4.3.0 closes on Esc.** Neither `ContentDialog.cs` nor `MessageBox.cs` at the 4.3.0 tag handles a
key (read 2026-09-15), and `ContentDialog.CloseButtonText` DEFAULTS to "Close" — an empty string is how a dialog
says it has no Close button. `MessageBox.Close()` is `[Obsolete("Use Close with MessageBoxResult instead")]` while no
@@ -270,3 +282,14 @@ On startup and on `ApplicationThemeManager.Changed`: for every live plot set fig
`DynamicResource`). `ContrastTests.NoTextBlockTakesItsColourFromAppearance` refuses every form in the App's XAML and code,
`PagesLoadTests.EveryTextFollowsAThemeSwitch` renders every surface through a switch both ways, and
`PagesLoadTests.WpfUisAppearanceStillKeepsTheThemeATextWasMadeUnder` turns red the day upstream follows a switch.
- [ ] **A page in the `NavigationView` inherits nothing, its text colour included.** `NavigationViewContentPresenter` is a
`Frame`, and `Frame` sets `InheritanceBehavior.SkipToAppNow`: the window's `Foreground` stops there, and a text that sets
no colour falls to the TextBlock default, which WPF UI 4.3.0's `TextBlockMetadata` makes `Brushes.Black`. Cards, grids
and controls set their own colour in their templates; the bare texts did not — every page's title and section headings
were black on the dark window, 1.3:1 (the owner's screenshots of beta.17; beta.16's show it too). It came and went: a
page on screen during a theme switch did take the window's new colour through the switch, and every navigation makes a
new page that does not. Every `Page` root sets `Foreground="{DynamicResource TextFillColorPrimaryBrush}"`
(`AccessibilityTests.EveryPageSetsItsOwnTextColour`). A check that lays a page out straight in a window measures the
window's colour, not the App's — beta.17's theme-switch check did and was green over the black titles — so the rendered
checks host a page in the presenter, and `PagesLoadTests.EveryTextIsReadableInBothThemes` measures every surface so
hosted at ≥ 3:1 in both themes.
+4 -1
View File
@@ -499,7 +499,10 @@ card is back with the finding under its disabled switch. The finding itself is o
**What clears it.** Nothing, as before: the block outlives *Change executable* and a re-import (§A game already enabled
can become blocked later). The owner asked for hooking to be turned off when anti-cheat is detected, not for a second
switch. *(Still true under D33: an exception is a separate layer over the block, never a clearing of it — §The user-mode
exception.)*
exception.)* *(And under D55, beta.19: the Agent removes an entry whose game is no longer installed and that has no session,
but never one that carries a block, an exception's grant or a failed trial — the delete's own SQL refuses them
(`SqliteGamePrune`), so an uninstall is not how a block, a grant or D38's "never again" disappears. Only the user's
*Remove… ▸ Delete sessions too* deletes such a row, as before.)*
**D21 stands as a fact.** A process an anti-cheat driver protects is `SessionEndReason.TargetUnreadable` (2026-09-21:
every candidate of that name exists and none can be opened; ELDEN RING under Easy Anti-Cheat on the owner's machine).
+212 -3
View File
@@ -1410,9 +1410,11 @@ stops there"~~ — the override itself is gone since 2026-09-22 (D22).
**Found and NOT fixed — each needs its own PR.**
- ~~**A refused session is not recorded, though the notice says it is.**~~ **Fixed 2026-09-22 (D23):** the loop holds a
refused session open until the target exits, so Tier 2 has a producer and the sentence is true for every refusal.
- **A released Overlay logs its build as `v0.1.0-beta.3-dirty`**: the CI checkout is dirty by the time CMake runs
- ~~**A released Overlay logs its build as `v0.1.0-beta.3-dirty`**: the CI checkout is dirty by the time CMake runs
`git describe`. Both sides of the handshake compile the same string, so nothing breaks; it is a release that calls
itself dirty.
itself dirty.~~ **Fixed 2026-10-07 (beta.18 PR-3):** the dirt was `release.yml`'s own date substitution in
`legal/*.md`; the workflow reads describe from the clean checkout before it and hands it to CMake as `FL_BUILD_ID`,
and `tools/buildid-check.ps1` reads it back out of the published binaries (`12_BUILD` §Release-time token substitution).
- ~~**An install over a running Agent half-replaces the folder** (three failed starts, `Microsoft.Data.Sqlite` not
found).~~ **A GUESS, WITHDRAWN the same evening, and it had already been published in beta.4's notes.** Nothing was
installed between the failures (20:59–21:01) and the start that worked (21:02); the PC had been restarted at 20:57
@@ -2011,7 +2013,7 @@ during finalize, PR-4 the scan set's creation times (D51), PR-5 the App's viewer
**Owner-only, added to the list below:** item 12.
## **START HERE** — 2026-10-06, 0.1.0-beta.16: beta.15 verified, and the chip it left
## ~~**START HERE**~~ — 2026-10-06, 0.1.0-beta.16: beta.15 verified, and the chip it left *(struck 2026-10-07: the head is §beta.17 below)*
*Status is `CHANGELOG.md` `[0.1.0-beta.16]`; this is what no other file carries. The owner, after beta.15's release
(2026-10-06): owner-only item 12 passed on real hardware ("đã chạy và ok"), do the chip beta.15 left, release, and close
@@ -2039,6 +2041,180 @@ added.*
- **The desktop app forbids polling CI** (no `gh` loop, Monitor or ScheduleWakeup): it wakes the session on a failure, a
conflict or a review comment, never on green, so a green PR waits for the owner's word or the owner's auto-merge.
## ~~**START HERE**~~ — 2026-10-07, 0.1.0-beta.17: text that follows a theme switch, scroll bars hidden everywhere, a wiki *(struck 2026-10-07: the head is §beta.18 below)*
*Status is `CHANGELOG.md` `[0.1.0-beta.17]`; this is what no other file carries. The owner's report (2026-10-07, three
screenshots of beta.16): Settings' descriptions kept the old theme's colour after a switch; the Dashboard kept its
scroll bar with Hide scroll bars on; "a complete wiki, concise and easy, End-user and Dev". Five stacked PRs — #281 the
theme text, #282 the scroll bars, #283 the guide's four new pages, #284 the wiki and its publishing, then the
release.*
**Decisions (owner, 2026-10-07, asked before the plan — do not re-ask):**
- **D53 — the wiki's source is the repository.** `wiki/` (Home, the sidebar, the developer pages) and `guide/` with
`LIMITATIONS.md` are assembled by `tools/wiki-build.ps1` and published to the Wiki tab by `.github/workflows/wiki.yml`
after a successful Release run (and by hand); a page edited on the tab is overwritten at the next release. English.
- **D54 — the wiki's End-user half is the user guide**, one source: it grows past D44's eight pages (the screens, every
setting, troubleshooting, a glossary — twelve) and stays embedded in the App. Tests hold that every setting the
Settings page shows and every page and menu item of the main window is named in it.
**Traps met on the way:**
- **`ui:TextBlock Appearance` pins a brush.** WPF UI 4.3.0 resolves it once (`TryFindResource`) and coerces Foreground
to it, so a theme switch leaves the text in the old theme; 129 texts used it. Every contrast check before measured a
theme as a surface was *made* under it — a switch needs the surface hosted in a `Window`, because only
`Application.Windows` hear a dictionary change (`16_WPFUI_SYNTAX` §Gotchas, `14_TESTING`).
- **A class handler on `Loaded` is not a load hook.** WPF raises Loaded only where a subtree listens for it with its own
handler, style EventSetter or template trigger — WPF UI's toggle switches carry one, which is why Settings hid its
bar and the Dashboard never did. A test that calls `RaiseEvent(Loaded)` proves the handler, never that WPF reaches it;
`ScrollChanged` reaches every scroller from its first layout.
- **The wiki's git branch is `master`, and the repository's default workflow token is read-only:** `wiki.yml` declares
`contents: write`. A release made with `GITHUB_TOKEN` fires no `release` event for another workflow; `workflow_run`
does, and runs `main`'s copy of the file — so it checks out the run's `head_sha` and links at its tag.
- **A fresh worktree cannot run the full gate** (the native configure, `CONTRIBUTING`): the stack's tip was gated in the
main checkout on a detached HEAD, and each PR's own CI ran on its branch.
- **Found while writing the guide, not fixed** (a task each): two notices can print an internal name — *"The hook
stopped (WriterSelfDisabled)…"*, and a refusal no anti-cheat names reads ~~*"The anti-cheat guard did not hook this
game: reason RefusedKillSwitch."*~~ *"…: reason RefusedByGuard."* *(corrected 2026-10-07 by beta.18's tests, which
build the Agent's own events: the kill switch's refusal carries the gate's label where a family goes, and read "kill
switch was detected in this game (… (FR-2.4) …)"; a re-scan that could not look read "Access is denied. was detected")*; the kill switch's *Applied* strip says "at the next session start" (it applies
within 30 s); *Turn off* failing says "Nothing was enabled."; in the viewer, the exception switch, the Recording numbers and the Channel stay enabled;
`08_UI` lists a "PawnIO missing" banner that does not exist; and a release's Overlay build id reads `-dirty` (§0.1.0-beta.4,
"Found and NOT fixed", still open). *(All but the build id fixed by beta.18 PR-2, 2026-10-07; the build id is PR-3's.)*
**Owner-only, added to the list below:** item 13.
## ~~**START HERE**~~ — 2026-10-07, 0.1.0-beta.18: page titles readable in the dark theme, notices in words, a clean build id *(struck 2026-10-12: the head is §beta.19 below)*
*Status is `CHANGELOG.md` `[0.1.0-beta.18]`; this is what no other file carries. The owner's report (2026-10-07, five
screenshots of beta.17 in the dark theme): every page's title and section headings near-black on the dark window — and
the two chips beta.17 left (§beta.17, "Found while writing the guide"). Three stacked PRs — #286 the page text, #287
the notices and the rest of that list, #288 the release build id — then the release.*
**No new decisions.** The train is the owner's request of 2026-10-07 ("beta18 with the two chip tasks, and the text that
blends into the background in dark mode").
**Traps met on the way:**
- **A page in the `NavigationView` inherits nothing.** `NavigationViewContentPresenter` is a `Frame`, and a Frame sets
`InheritanceBehavior.SkipToAppNow`; WPF UI 4.3.0 makes the TextBlock default black. A page on screen during a theme
switch takes the window's new colour through the switch and a page navigated to afterwards does not, so it came and
went. Every check before hosted pages straight in a window and measured a page the App never draws — host a page in the
presenter (`PagesLoadTests.Hosted`, `16_WPFUI_SYNTAX` §Gotchas).
- **The accent is not in the theme dictionary.** WPF UI writes it into `Application.Resources` at every
`ApplicationThemeManager.Apply(…, updateAccent: true)`; a test that swaps only the dictionary measures the other theme's
accent (`Visuals.UnderTheme` derives it as the App does; `systemAccentColor: true` reads the machine's own palette).
- **The gate's own refusals look like findings on the wire.** `HookedCaptureGate` puts a label ("kill switch", "previously
blocked") where a family goes; whatever reads a family as "an anti-cheat was found" asks the end reason first. A test
of what the user reads builds the event as the Agent does (`NoticesFromTheAgentTests`), never by hand — the
hand-written events were why every notice test was green.
- **`Safety_Consent_*` strings are versioned with the consent disclosure** (`SafetyDisclosure`): a message that is wrong
on one path gets a key of its own rather than a changed meaning.
- **A release's natives were `-dirty` by the release's own hand:** its date substitution edits `legal/*.md` before CMake
reads describe. The id is read first, handed in, and read back out of the binaries (`tools/buildid-check.ps1`).
- **Met again:** `CaptureHostEndToEndTests.WhenTheTargetExitsTheHostStopsAndSaysWhy` (`TargetNotRunning` on a slow
runner) failed #286's first CI run; the job was re-run. **And a new one** failed #288's:
`…LaunchModeOnAVulkanTargetAttachesToTheLayersRingAndInjectsNothing`. A hosted runner has the Vulkan loader and no
device, so the harness exits 77 with a `[SKIP]` line — but the runner is elevated, the launch goes through
`CreateProcessWithTokenW` (`UnelevatedProcess`), the child inherits no stdout, and the line never reaches the host's
output; when the guard's scan hits the exiting harness (`ModuleScanFailed`) the test fails instead of skipping. Re-run;
~~the deterministic fix is a task of its own~~ fixed the same day by beta.18 PR-5 (the test asks the harness itself,
before the host runs), which also gave the `TargetNotRunning` case a 15 s hold (`13_CI_CD` §ci.yml).
**Owner-only, added to the list below:** item 14.
## ~~**START HERE**~~ — 2026-10-12, 0.1.0-beta.19: the import's helper, the folder Change executable opens in, three engines' versions, uninstalled games *(struck 2026-10-12: the head is §beta.20 below)*
*Status is `CHANGELOG.md` `[0.1.0-beta.19]`; this is what no other file carries. The owner's list (2026-10-12, four items):
*Change executable…* opens in the game's root folder; the version of RPG Maker, Unity and Godot games; A Doll's Locket -
Remake imported as `notification_helper.exe`; whether the Agent removes games whose executable is gone, and if not, to
remove them when no session was recorded. Four stacked PRs — #292 the import, #293 the folder, #294 the versions,
#295 the removal — and two from #295's review, #297 one notice per check and #298 the probe's unreadable-folder tests —
then the release.*
**Decisions (owner, 2026-10-12, asked before the plan — do not re-ask):**
- **D55 — a game you uninstalled leaves the library by itself when it has no session** (amends D41's "nothing is
removed"): its executable gone at sweeps ten minutes apart (counted in the Agent's memory), its drive connected and the
folder it was installed in still there, no session stored, recording or waiting to be recovered — behind Settings ▸
Data ▸ *Remove uninstalled games*, on by default (`02_SPEC` FR-1.8). **Never an entry carrying an anti-cheat block, an
exception's grant or a failed trial**: that part follows from rule 2 and D38 and was not asked (`19_SAFETY` §What a
finding does to the game).
- **D56 — an NW.js runtime is the import's game**: an executable beside `nw.dll` + `package.json` ranks as the engine's
own layout, below Unity's and Unreal's and above a name match, so a launcher-fronted RPG Maker MV/MZ install is pointed
at the process that draws. D28 did that by hand for HELLO, HELLO WORLD!; the locator now picks the same file.
- **The owner's existing A Doll's Locket entry is not rewritten** (D25/D27): *Change executable…* re-points it, and the
import no longer offers a twin of the same store title.
- **The train (owner, 2026-10-12, after the PRs were up):** "commit, push và release luôn" — each PR squash-merged by the
session as its CI went green, then the signed tag and the release, without asking again. Then, of the review's two
follow-ups the session had offered as separate tasks: "2 pr riêng, rồi merge, push và release" — #297 and #298, in this
release.
**Traps met on the way:**
- **A store's own pick can be a helper.** itch's butler saves a *filtered* verdict — the shallowest candidates, minus
those whose manifest asks for elevation — and ranks nothing, so A Doll's Locket's whole verdict was
`notification_helper.exe`. Its database lives in the WAL (a 4 KB main file): a read with `immutable=1` sees no tables;
open it `mode=ro` with the itch app closed, or copy the `-wal` beside it as `ItchLibrarySource` does.
- **The locator's helper fragments are substrings** (`node` is inside *Nodebuster*): good enough for a guess, never to
overrule a store — `ExecutableLocator.RuntimeHelperNames` holds whole names for that.
- **Godot's version string sits 57–78 MB into an export**, past the rules' 8 MiB strings scan; the data pack's header
has it in 20 bytes. **Unity's FileVersion string is not the editor version** (`2022.3.39.5118735`); the ProductVersion
is (`2022.3.39f1 (hash)`), except on 2019.4 players, whose data file's header carries it.
- **`File.Exists` and `Directory.Exists` answer false for a path they may not look at**: before removing anything, the
parent's listing is asked whether the child is there (`ExecutablePresenceProbe`).
- **The signing key was locked when the session began**, and ten pinentry prompts went unanswered; the code went on and
the commits waited. Probe first: `echo x | gpg --batch --pinentry-mode error --local-user <key> --clearsign`.
- **Mechanical, again:** the Write tool writes LF (convert after it); a Bash heredoc halves `\\` (patch scripts are
files); a WPF project has no implicit `System.IO` using; MA0051 (60 lines) hit `ItchLibrarySource.ReadDatabaseAsync`,
`DetectionSweep.SweepOnceAsync` and `AgentServices.AddDetection`; CA1716 rejects an interface member named `Of`.
- **A review of the PR that deletes data, after its gates were green and before it merged, found three defects no gate
could:** a cross-reference to a `19_SAFETY` section that does not exist; a presence probe that listed every drive for
every entry and asked a dead share whether it was ready (`VolumeRoots.IsReady` reads the type first); and an entry
the delete refused that was never asked again (`UninstalledEntryPrune.RetryAfter`, an hour). The `vi`/`ja` switch text
also named the pill in English where those languages show their own word. Review such a PR before the merge. The two
it left for later landed in the same release: one check's removals arrive as one event each, and WPF UI 4.3.0's
`SnackbarService` keeps ONE snackbar and shows every message in it at once (`Show(true)`, read from the assembly), so
only the last name stayed on screen (#297: the page waits `GamesViewModel.RemovalSettle` and says them once); and the
probe's two *Unknown* branches had no test (#298: real folders the test user is denied, each test measured red with its
branch broken).
- **Loop a test class you touched before the merge.** `GamesViewModelTests` run 165 times failed once: two overlapping
reads of the library, the older finishing last and shown — a removed game's card came back. #297 shows only the newest
read. The first version of its test hung: which read reached the held check first was itself a race (wait for the
first to be held before starting the second, and bound every wait).
- **A test run reseeds `%LOCALAPPDATA%\FrameLedger\rules`** with rules `2026.10.2`, whose extractor types the installed
beta.18 cannot parse: its detection sweep says "rules unusable" until it restarts or beta.19 is installed (beta.10's
trap, met again; the guard is unaffected). For beta.20 PR-1 (rules `2026.10.3`, which the installed beta.19 cannot
parse) the session copied the owner's `detection-rules.json` and `.seeded` aside before testing and back after,
byte for byte, so the owner's running Agent kept its own.
**Owner-only, added to the list below:** item 15 — **passed 2026-10-12**.
**After the release (owner, 2026-10-12):** "tiếp tục với 1 pr kèm với detect version game dùng ren'py" — beta.20 PR-1 reads
a Ren'Py game's engine version from `renpy/vc_version.py` (rules `2026.10.3`, Privacy Policy 2.9 — the Legal Gate shows it
once at the next update; `05_DETECTION` §Engine version — Ren'Py) and strikes item 15. Merged for the next pre-release;
no release was asked for.
## **START HERE** — 2026-10-12, 0.1.0-beta.20: the engine version of Ren'Py games
*Status is `CHANGELOG.md` `[0.1.0-beta.20]`; this is what no other file carries.* The owner, the same evening as beta.19 and
after confirming it on real hardware: "tiếp tục với 1 pr kèm với detect version game dùng ren'py", then "tung bản beta20
rồi đóng phiên hẳn". One PR — #299, a Ren'Py game's version from the engine's own `renpy/vc_version.py` (rules
`2026.10.3`, Privacy Policy 2.9, item 15 struck) — then the release.
**Decisions:** none new. The Privacy Policy 2.9 wording — one item added to §4's list, "the version file of a Ren'Py
game's engine" — was shown to the owner with #299 and released on their word.
**Traps met on the way:**
- **`keyboxd` can fail with "Input/output error" while the key is unlocked**: `gpgconf --kill keyboxd` alone brings it
back on the next use; killing `gpg-agent` would drop the cached passphrase and wait on a pinentry.
- **A test run still seeds the owner's live rules** (§beta.19's trap): rules `2026.10.3` cannot be parsed by an installed
beta.19, so the owner's `detection-rules.json` and `.seeded` were copied aside before each local gate and back after.
- **Loop a test class you touched before the merge** (§beta.19): `GamesViewModelTests` then ran 340 times green after #297.
**Owner-only, added to the list below:** item 16.
## Owner-only — no PR can close these
1. **§S23-2 — branch protection.** `Rules / validate` is not a required status check on
@@ -2126,6 +2302,39 @@ added.*
(`12_BUILD` §Debugging) and start `FrameLedger.exe --data-dir <copy>`; the banner names the folder, the pill reads
*Viewer — no Agent*, the switches are off, and the installed App runs beside it untouched. (f) The `ja` strings
marked `review`.
13. **beta.17 on real hardware.** (a) **A theme switch:** on Settings, Dark → Light → Dark, and again with a session's
summary window open — every description and caption follows at once. (b) **Hide scroll bars** on: the Dashboard,
Games, a game's page, Logs, About, Help ▸ User guide and a drop-down list draw no bar, and the wheel still scrolls;
off, the bars come back without a restart. (c) **Help ▸ User guide** lists twelve pages and Limitations; a link to a
section opens that section. (d) **The wiki**, once the release is out: the Wiki tab shows Home, the sidebar's two
halves and a footer naming `v0.1.0-beta.17` — then tick *Restrict editing to collaborators only* (Settings ▸ General
▸ Features ▸ Wikis), or anyone can change a page until the next release overwrites it. (e) The `ja` strings marked
`review`.
14. ~~**beta.18 on real hardware.**~~ **Passed 2026-10-08** — the owner ran it on real hardware and reported it OK ("Đã
test và ok"). *(The item as written:)* (a) **The dark theme:** every page's title and section headings — Dashboard, Games, a
game's page, Compare, Settings, Logs — read light on the dark window, after starting in Dark, after Light → Dark, and
after moving between pages. (b) **The overlay build** on the Dashboard's *Capture agent* card reads `v0.1.0-beta.18`,
without `-dirty`. (c) **Disable all hooking:** turning it on says a game being measured stops within 30 seconds; with
it on, a hooked game's notice reads "All hooking is switched off in Settings, so nothing was measured." (d) The `ja`
strings marked `review`, `Safety_Unhooked_Unnamed_Format` among them.
15. ~~**beta.19 on real hardware.**~~ **Passed 2026-10-12** — the owner ran it and reported (a), (c), (d)'s unplugged
drive, (e) and (f) OK ("Các mục đã test: 1, 2. 5, 6, 4, ok"); (b) and (d)'s removal were read from the logs: Refresh
named the existing entry instead of offering a twin, and one check at 18:04:00 removed Deadly Heart Gambit, Vibe Train
Demo and 衔蝶 (the App's restart at 17:47 had started the ten minutes again), the library then reading *Games · 46*.
*(The item as written:)* (a) **A Doll's Locket - Remake:** its page ▸ *Change executable…* opens in `Dolls
Locket\`; pick `css\Game.exe`. Its launcher asks for administrator, so the runtime is measured only with *Run the agent
as administrator* on — otherwise the session says why nothing was measured. (b) **Refresh** offers no second A Doll's
Locket. (c) **Engine versions:** a Unity game's page (*Unity 2022.3.62f2* on Umamusume, *Unity 2019.4.40* on GIRLS'
FRONTLINE 2), Godot's (*Godot 4.4.1* on 衔蝶), RPG Maker's (*RPG Maker MZ 1.10.0*, *RPG Maker MV 1.6.2* on Flower in
Us, *RPG Maker VX Ace (RGSS 3.0.1)*), each with its *Engine version* line. (d) **Uninstall a game that has no session**
(or delete a copy you added): about ten minutes later its entry is gone and the Games page says so — two removed
together are said in one notice that names both; with the USB drive unplugged nothing is removed; *Remove uninstalled
games* off keeps it. (e) The Legal Gate shows the Privacy Policy 2.8
once. (f) The `ja` strings marked `review`.
16. **beta.20 on real hardware.** (a) **Bound Between Desks:** its page reads *Ren'Py 8.5.0*, and its *Engine version*
line says it was read from the engine's version file (`renpy/vc_version.py`); the first sweep after the update reads
every game once more (rules `2026.10.3`). (b) The Legal Gate shows the Privacy Policy 2.9 once. (c) The `ja` string
marked `review` (`GameDetail_EngineVersion_RenPyVcVersion`).
**Answered 2026-08-05, do not re-ask:** remove `gameguard` and keep `guard` (approved
over a red `Rules` gate, with the reasoning recorded in the merge commit); vendor NVAPI
+5 -2
View File
@@ -7,7 +7,8 @@ This folder is for people who build, change or review FrameLedger. **If you only
| You want to… | Read |
|---|---|
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (D1…D46) and the traps that each cost a cycle. It carries no status on purpose |
| Pick up work where it stopped | [`HANDOFF.md`](HANDOFF.md) — sequencing, decisions (~~D1…D46~~ D1 onward — *corrected 2026-10-07: the range grows with every train*) and the traps that each cost a cycle. It carries no status on purpose |
| Find your way around first | The [wiki](https://github.com/poli0981/frameledger/wiki)'s developer pages (source: [`../wiki/`](../wiki/), beta.17) — a short page per part, each linking here |
| Learn the system | [`../CLAUDE.md`](../CLAUDE.md) (the rules and the layout), then the reading order below |
| Build it | [`12_BUILD.md`](12_BUILD.md) — `./build.ps1 check` is the whole gate, the same one CI runs |
| Contribute or fork | [`../CONTRIBUTING.md`](../CONTRIBUTING.md), [`../FORKING.md`](../FORKING.md), [`../NOTICE`](../NOTICE) |
@@ -76,7 +77,9 @@ are safety items, and something listed there as unresolved should not be built t
## Beside this folder
- [`../guide/`](../guide/README.md) — the user guide (players, English).
- [`../guide/`](../guide/README.md) — the user guide (players, English); since beta.17 (D54) also the wiki's End-user part.
- [`../wiki/`](../wiki/Home.md) — the wiki's own pages: Home, the sidebar, the developer pages (D53). `wiki.yml`
publishes them with the guide to the Wiki tab when a release is made; `build.ps1`'s `wiki-check` holds every link.
- [`../legal/`](../legal/) — the documents a user accepts, the accuracy statement, the third-party notices and licence
texts, the trademark note.
- [`../LIMITATIONS.md`](../LIMITATIONS.md) — what the whole software cannot do, in a player's words.
+15
View File
@@ -63,6 +63,21 @@ are kept because they record what each version changed and why (owner decision D
>
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
### What version 2.9 of the Privacy Policy changed (0.1.0-beta.20)
§4's list of the version marks an engine keeps in its own files gains one: the version file of a Ren'Py game's engine
(`renpy/vc_version.py`), read to show a Ren'Py game's engine version (beta.20 PR-1, owner request 2026-10-12) — its first
4 KiB, for the `version` line only. Nothing here leaves your device, as before.
### What version 2.8 of the Privacy Policy changed (0.1.0-beta.19)
§4 names the version marks an engine keeps in its own files, read to show a Unity, Godot or RPG Maker game's engine
version (beta.19 PR-3, owner request 2026-10-12): Unity's player library (its version information) and the header of its
data file, the header of a Godot data pack, an RPG Maker game's core script and `Game.ini` and the library `Game.ini`
names. Two of them were read before and never stated: the version information of `UnityPlayer.dll` (the Unity rule's
extractor since the detection rules began) and an RPG Maker MV/MZ game's title in `data/System.json`, which the App reads
to name a game added by hand (since 2026-09-23). Nothing here leaves your device, as before.
### What version 2.7 of the Privacy Policy changed (0.1.0-beta.14)
§4 says two things the software reads to tell a crash from an ordinary exit: the crash reports Windows keeps in its
+50
View File
@@ -2633,3 +2633,53 @@ from this PR's build):**
refused, and the private working set then reads N/A), AMD and Intel GPUs, a laptop with two adapters (the reader sums
every adapter's instances for the pid), and a real game — the owner's beta.12 check (HANDOFF owner-only item 9) compares
a session's figures with Task Manager's Details tab at the same moment.
## 17 · Unity, Godot and RPG Maker versions in installed games *(2026-10-12, beta.19)*
Measured read-only on the owner's machine (i7-14700KF, RTX 5080, Windows 11 29648) before the readers were written:
every `UnityPlayer.dll`, `*.pck`, `rmmz_core.js`, `rpg_core.js` and `RGSS*.dll` up to five levels under `D:\another`
(GOG, itch and loose installs), `D:\SteamLibrary\steamapps\common`, Steam's own `common` and `G:\` — 23 installs, read in
9.6 s. Then again through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`, rules `2026.10.2`), which read
every install as tabled. Nothing was copied or written; the decision rules are in `05_DETECTION` §Engine version — Unity,
Godot, RPG Maker.
| Engine | Installs | What the files say | Read as (shipped) | Detect time |
|---|---|---|---|---|
| Unity 2020+ | DONT GO, Dialoop, Broken Shell Demo, Deadly Heart Gambit, DreadFields, Kemono Teatime, March Out!, Umamusume, Walto, Yasha, Yu-Gi-Oh! Master Duel, 帰路, Legends of Runeterra | `UnityPlayer.dll` ProductVersion `2022.3.39f1 (4e1b0f82c39a)` … `6000.3.17f1 (cf0352b38e81)`; FileVersion `2022.3.39.5118735` (the build number where the release letter belongs) | the ProductVersion's editor version (`unity_player`) | 26 ms – 4.1 s |
| Unity 2019.4 | A Space for the Unbound - Prologue (GOG) | ProductVersion = FileVersion `2019.4.1.15122501`; `*_Data/globalgamemanagers` byte 20: `2019.4.1f1` | `2019.4.1f1` (`unity_data`) | 102 ms |
| Unity 2019.4 | GIRLS' FRONTLINE 2: EXILIUM | ProductVersion `2019.4.40.16762411`; the data file's header is not readable (encrypted) | `2019.4.40` (`unity_player_file`) | 2.2 s |
| Godot 4 | Plethora of Bullets 2 (itch), 衔蝶 (Steam) | `<exe>.pck` header `GDPC`, format 2, `4.2.2` / `4.4.1`; the exe's `Godot Engine v4.4.1.stable.official` sits 57–78 MB in; 衔蝶's version resource is the studio's (`0.1.0.3`) | `4.2.2`, `4.4.1` (`godot_pck`) | 24–41 ms |
| RPG Maker MZ | A Doll's Locket - Remake (itch) | `js/rmmz_core.js` line 2 `// rmmz_core.js v1.10.0` (also under the runtime's `css\js\`) | MZ `1.10.0` | 41–53 ms |
| RPG Maker MV | Flower in Us (Steam), 996IR, HELLO, HELLO WORLD! (itch) | `www/js/rpg_core.js` `v1.6.2`, `v1.6.2`, `v1.6.1` (HHW's one folder above its runtime) | MV `1.6.x` | 70–275 ms |
| RPG Maker VX Ace | City of Bones, Träumerei Chapter 2 (itch) | `Game.ini`: `Library=System\RGSS301.dll`; the DLL's version `3, 0, 1, 1` | VX Ace, RGSS `3.0.1` | 427–442 ms |
- **Detect time** is the whole detection of one entry — the install's walk, the rules and the second read — on the USB
drive; the second read itself is a version resource and at most a few kilobytes. It runs once per executable and rules
version, like Unreal's.
- **Four of the itch installs front their runtime with a 213 MB .NET launcher** (HELLO, HELLO WORLD!, A Doll's Locket -
Remake — whose launcher asks for administrator —, City of Bones and Träumerei) — the reason the import's choice of
executable changed in the same train (`05_DETECTION` §Library import, D56).
- **Not measured:** RPG Maker 2000/2003 (`RPG_RT.exe`; none installed, and no rule detects it), XP and VX (no install —
their RGSS1/RGSS2 libraries are read by the same rule as VX Ace's, unmeasured), a Unity build older than 2019 (its
player is the executable, with no `UnityPlayer.dll`), a Godot 3 export, and a Godot pack appended to the executable
(both installs ship the pack beside it; the trailer the reader follows is Godot's documented layout, tested on
synthetic files only).
## 18 · The Ren'Py version in an installed game *(2026-10-12, beta.20)*
The owner's one Ren'Py install, read-only: Bound Between Desks (Steam) — `BoundBetweenDesks.exe` (386,048 bytes, no version
resource), `BoundBetweenDesks.py`, `game\`, `lib\py3-windows-x86_64\` (Python 3.12: `libpython3.12.dll`,
`librenpython.dll`, `pythonw.exe`) and `renpy\` with the engine's `.py` sources beside `__pycache__\*.cpython-312.pyc`.
- `renpy\vc_version.py` (109 bytes, LF line ends): `branch = 'master'`, `nightly = False`, `official = True`,
`version = '8.5.0.25111603'`, `version_name = 'In Good Health'`.
- `renpy\__init__.py` imports those names from `vc_version` (else from `renpy.versions.get_version()`) and builds
`version_tuple` from `version.split(".")`; `renpy.version` is `"Ren'Py " + version_only`.
- The game's own `log.txt` (written at its last start, 2026-09-16) begins `Ren'Py 8.5.0.25111603`: the same number.
Then through the shipped pipeline (`StaticGameDetector` over `GameFileProbe`, rules `2026.10.3`): `renpy 8.5.0
renpy_vc_version` in 79 ms; Dialoop (`unity 6000.3.3f1`), Plethora of Bullets 2 (`godot 4.2.2`), A Doll's Locket - Remake
(`rpgmaker_mv 1.10.0`) and City of Bones (`rpgmaker_rgss 3.0.1`) read as in §17.
- **Not measured:** an older Ren'Py (no other install), whose `vc_version.py` may name no `version` — it then reads as
not found; a build that ships the engine compiled only (none seen).
+2 -1
View File
@@ -26,7 +26,8 @@ a game is being recorded. Backing up is up to you — FrameLedger does not do it
## Delete it
- **A game's sessions:** Games ▸ the game ▸ Sessions ▸ **Delete all sessions…**
- **A game:** its page ▸ **Remove…**
- **A game:** its page ▸ **Remove…** A game you uninstalled goes by itself when it has no sessions (Settings ▸ Data ▸
**Remove uninstalled games**, on unless you turn it off); one with sessions stays, with them, until you remove it.
- **Every session of every game:** Settings ▸ Data ▸ **Delete all sessions…**
- **Everything:** uninstall FrameLedger and let it delete the data folder, or delete the folder yourself.
+124
View File
@@ -0,0 +1,124 @@
# The screens
What each part of FrameLedger shows and what each button does. What the numbers mean is in
[Read your results](03-read-your-results.md); every setting is in [Every setting](08-settings.md).
## The main window
**The badge at the top right** says how the capture agent is doing:
| Badge | Meaning |
|---|---|
| Agent connected | Everything works. |
| Connecting to agent… · Starting agent… | FrameLedger is reaching the agent, or starting it. Give it a few seconds. |
| Waiting for administrator permission… | *Run the agent as administrator* is on, and Windows is asking you. |
| Agent offline | The agent is installed but does not answer. FrameLedger keeps trying; **Retry** on the banner tries now. |
| Agent not installed | `FrameLedger.Agent.exe` is missing: install FrameLedger again. |
| Viewer — no Agent | You opened a copy of a data folder to look at ([When something goes wrong](09-troubleshooting.md#looking-at-a-copy-of-your-data)). |
**Banners** under the menus stay until you act on them: *Capture agent offline* with **Retry**; *Update* with **Restart to
update** (it waits while a game is being recorded); and the safety notices — a game's hooking refused, measurement
stopped, hooking turned off — each with one button that only says you have read it.
**The pages** are on the left: **Dashboard**, **Games**, **Compare**, **Logs**, and **Settings** at the bottom.
## The menus
| Menu | Item | What it does |
|---|---|---|
| **File** | **Add game…** | Pick a game's `.exe` file. It is added with hooking off, and its page opens. |
| | **Import library…** | A checklist of the games installed through Steam, GOG Galaxy, Epic and itch.io. |
| | **Export** ▸ **Session CSV** · **Session JSON** · **Chart PNG** | Saves the session you last selected or opened. Read [Your data](05-your-data.md) before you share a file. |
| | **Exit** | Quits FrameLedger, even when *Minimize to tray on close* is on. |
| **Tools** | **Agent status…** | Opens the Dashboard, where the agent's card is. |
| | **Update detection rules** | The agent reads its detection rules again and checks your games again. |
| | **Vulkan layer registration…** | Opens Settings, where the Vulkan layer is. |
| | **Open data folder** | Opens `%LOCALAPPDATA%\FrameLedger` in Explorer. |
| | **Database maintenance…** | **Check**, **Back up…**, **Sweep…** and **Compact** your database ([When something goes wrong](09-troubleshooting.md#the-database)). |
| **Help** | **User guide** | This guide. |
| | **Check for updates** | Asks GitHub now. |
| | **Report a bug…** | Builds a report on your PC ([When something goes wrong](09-troubleshooting.md#report-a-problem)). |
| | **Online documentation** | The project's page on GitHub. |
| | **Limitations** | What FrameLedger cannot do. |
| | **About FrameLedger** | The version, the licences and the notices. |
## Dashboard
- **Live capture** — the game being recorded right now: its name, **T1** (measured) or **T2** (recorded only), and the
time so far. While it is measured: the frame rate, the resolution, the upscaler, frame generation, ray tracing, the GPU
and CPU temperatures and the game's memory. *Attached — waiting for the first frames…* means hooking worked and the
first frames are on their way.
- **Games tracked**, **Total playtime**, **Sessions this week**.
- **Capture agent** — *State*, *Agent version*, *Telemetry source* (which sensor readers work on this PC: `l1` is
Windows itself, `lhm` is LibreHardwareMonitor, `nvapi` is NVIDIA's own and only on NVIDIA cards), *Overlay build* (the
version of the component loaded into games), *Elevated* (whether the agent runs as administrator) and *Running
sessions*. Everything reads N/A until the agent answers.
- **Recent sessions** — the ten newest. Click one to open its summary.
## Games
- **Search games**; sort by **Name**, **Last played** or **Playtime**; **Show as a list** or **Show as a grid**.
- **Refresh** reads your library again: it offers games newly installed through a store, and marks a game whose `.exe`
is gone as *Not installed*. The agent removes such a game by itself after ten minutes when it has no sessions and its
drive is connected — never one where anti-cheat was found (**Settings ▸ Data ▸ Remove uninstalled games** turns this
off).
- **Add game…** — or drop `.exe` files onto the page.
- Each game shows its name, its store and engine, and one state: **Hooking on**, **Hooking off**, **Anti-cheat** (found,
so it is not hooked), **Exception** (a user-mode exception is in force) or **Not recorded**; then its sessions,
playtime and last play. Click it to open its page (in the list: double-click, or Enter).
## A game's page
- **At the top:** the name, publisher, version, store and engine, the `.exe` path, the last session, the last measured
session's frame rate and its ray-tracing chips. **Edit…** changes the name, publisher, version and notes. **Change
executable…** points the entry at another `.exe` and turns hooking back off; its file dialog opens in the game's own
folder. **Remove…** asks whether to keep the game's sessions.
- **Recording** — off, FrameLedger ignores the program completely: for a launcher or a tool that is not a game.
- **Hooking** — on, the game is measured. A warning comes first, and you type `I ACCEPT THE INJECTION RISK` to go on.
Read [Anti-cheat and safety](04-anti-cheat-and-safety.md) before you do.
- **Anti-cheat** — shown in its place when anti-cheat was found: what was found, and where. **User-mode exception**
appears when the game qualifies for the one exception.
- **Supports** and **Details** — what the game's own files contain, as far as FrameLedger can tell.
- **Tabs:** **Sessions** (every session: double-click a row or press **Open**; **Delete all sessions…** at the top),
**Frametime**, **Distribution**, **Trend** (one point per session for a figure you choose, with changes to your
hardware or driver marked), **Sensors**, and **Latency** when the game reported it.
## A session's summary
It opens from a session row, from the Dashboard, and from the notice when a session is saved.
- A warning at the top when the game crashed or measuring stopped early.
- The **Ray Tracing**, **Path Tracing** and **Ray Reconstruction** chips: click one to correct it by hand, for this
session or as the game's default. Your correction is labelled as yours.
- The figures, the charts and **Statistics per series** — [Read your results](03-read-your-results.md) explains each.
- **Tags and notes** with **Save**, and **Export CSV**, **Export JSON**, **Export PNG**.
## Compare
Tick **2 to 5 sessions**, from any of your games, and press **Compare**: one frame-rate curve per measured session, and
a table with the best value of each row in bold. Comparing a measured session with an unmeasured one asks first,
because they measured different things.
## Logs
What FrameLedger and its agent wrote down. Choose **App** or **Agent**, a level, and search; **Pause** stops the view from
following new lines. **Open logs folder**, and **Export bug bundle**, which does the same as Help ▸ Report a bug….
## Settings
Every switch and box is described in [Every setting](08-settings.md).
## The tray icon
The icon by the clock has **Open FrameLedger**, **Pause capture** / **Resume capture**, **Agent status** and **Exit**; a
click on it opens the window. **Pause capture** stops measuring the running sessions until you resume, and the paused
stretch is left out of their figures. While the window is hidden, a notice pops up when a session is saved or an update
is ready.
## Keyboard and mouse
- **Ctrl+1** … **Ctrl+5** open Dashboard, Games, Compare, Logs and Settings.
- **Alt** or **F10** moves to the menus.
- **Esc** closes a dialog the way its Close or Cancel button does.
- Over a chart, **Ctrl** and the mouse wheel zoom, dragging pans, and a double-click resets. The wheel alone scrolls the
page.
+76
View File
@@ -0,0 +1,76 @@
# Every setting
Settings is the last item on the left. Its sections follow, in the order it shows them. Settings marked *agent* are read
by the capture agent; unless the row says otherwise, a change applies from the next session.
## Capture
| Setting | What it does | Default |
|---|---|---|
| **Disable all hooking** | Nothing is loaded into any game, whatever each game's own switch says. A game being measured stops being measured at the next safety check, within 30 seconds. Sessions are still recorded. *Agent.* | Off |
| **Games with hooking on** | Shown while any game has hooking on: one **Turn off** per game. | — |
| **Hide hooking on anti-cheat games** | On, the page of a game where anti-cheat was found shows only what was found; off, it also shows the Hooking switch, greyed out. Such a game is never hooked either way. | On |
| **Allow hooking in games whose only anti-cheat runs in user mode** | Turns on the one narrow exception ([Anti-cheat and safety](04-anti-cheat-and-safety.md#the-one-exception-you-can-make)). The games that qualify are listed under it, each with **Make exception…** (after a warning) or **Withdraw**. *Agent.* | Off |
| **Vulkan layer** | The component that measures Vulkan games — but only a game FrameLedger starts itself, which the App cannot do yet, so a Vulkan game you start is recorded, not measured. The agent registers and removes it by itself; **Register** and **Unregister** repair that, for your Windows user only. | — |
The link under them, *Read what the hook does and does not do*, opens the safety document on GitHub.
## Recording
| Setting | What it does | Default |
|---|---|---|
| **Minimum session length (s)** | A shorter session is not kept. 5 to 600 seconds. *Agent.* | 30 |
| **Sensor interval (ms)** | How often the PC's sensors are read during a session. 500 to 2000 ms. *Agent.* | 1000 |
| **Raw series kept per game** | How many of each game's newest sessions keep their per-frame data; older ones keep their statistics. 0 keeps everything. *Agent.* | 20 |
## Data
| Setting | What it does | Default |
|---|---|---|
| **Remove uninstalled games** | A game whose `.exe` has been gone for ten minutes is removed from your library — only when it has no sessions, its drive is connected and the folder it was installed in is still there (an unplugged drive never counts), and never a game where anti-cheat was found. Off, it stays and reads *Not installed*. *Agent*, within 15 seconds. | On |
| **Delete all sessions** | Deletes every session of every game, with its data and notes, after asking. Your library, your settings and each game's hooking choice stay. It cannot be undone, and it is refused while a game is being recorded. | — |
## Capture agent
| Setting | What it does | Default |
|---|---|---|
| **Run the agent as administrator** | Lets FrameLedger measure games that run as administrator, and read CPU temperature with PawnIO installed. Windows asks every time the agent starts, at logon too. A warning explains the risk first; read [Limitations](../LIMITATIONS.md#running-the-agent-as-administrator). The agent restarts to apply it, or at its next start if a game is being recorded. | Off |
| **Start the agent at logon** | **Register**, **Repair** or **Remove** a task that starts the agent when you log on, for your user only and without administrator rights. Without it, FrameLedger starts the agent when you open it. | Not installed |
## Appearance
| Setting | What it does | Default |
|---|---|---|
| **Theme** | Follow system, Light or Dark. Applies at once. | Follow system |
| **Language** | English, Tiếng Việt or 日本語. The window is rebuilt in the new language at once. | English |
## Window
| Setting | What it does | Default |
|---|---|---|
| **Start FrameLedger with Windows** | Opens FrameLedger when you log on, for your user only. | Off |
| **Minimize to tray on close** | Closing the window keeps FrameLedger running by the clock; quit with **Exit** in the tray's menu or the File menu. | Off |
| **Show FPS with two decimals** | Every frame rate with two decimals (62.40) instead of a whole number (62). Pages show it when they next open. | Off |
| **Hide scroll bars** | No scroll bars are drawn anywhere; the wheel, the keyboard and touch still scroll. Applies at once. | Off |
## Updates
| Setting | What it does | Default |
|---|---|---|
| **Channel** | *Automatic* follows your copy: a test version (a pre-release) looks for test versions, a release for releases. Or choose *Stable*, or *Beta* (releases and pre-releases). | Automatic |
| **Check for updates at startup** | One question to GitHub a few seconds after FrameLedger starts. A new version downloads in the background and installs only when you restart. | On |
## Logging
| Setting | What it does | Default |
|---|---|---|
| **Debug logging** | FrameLedger writes far more detail into its log, for a bug report. The agent keeps its own level. | Off |
## System
This PC as FrameLedger records it with every session: processor, graphics card and driver, memory, Windows build and
the main display. Nothing is sent anywhere. **Copy** puts the lines on the clipboard, for a bug report.
## Legal
**Reopen the legal documents** shows the documents you accepted, and the GPL, again. Nothing is accepted again.
+98
View File
@@ -0,0 +1,98 @@
# When something goes wrong
Find what you see, then what it means and what to do. Questions that are not problems are in
[Questions and answers](06-faq.md).
## The capture agent is not working
| You see | It means | Do this |
|---|---|---|
| **Connecting to agent…** or **Starting agent…** | FrameLedger is reaching its agent, or starting it. | Wait a few seconds. |
| **Agent offline**, and a banner: *The capture agent is not answering* | The agent is installed but does not answer. Your library, sessions and charts still work; only what is live does not. FrameLedger keeps trying. | **Retry** on the banner, or close FrameLedger and open it again. |
| **Agent not installed** | `FrameLedger.Agent.exe` is missing from FrameLedger's folder. | Install FrameLedger again from the [Releases page](https://github.com/poli0981/frameledger/releases). |
| **Waiting for administrator permission…** | *Run the agent as administrator* is on, and Windows is asking. The prompt may be waiting on the taskbar. | Answer it — or switch the option off in Settings ▸ Capture agent. |
| Settings says *the administrator prompt was declined* | The agent runs with your normal rights. | Nothing, unless you need it ([Every setting](08-settings.md#capture-agent)). |
## A game was recorded but not measured
The session is **T2**, its frame figures read N/A, and its summary says why on the **Why:** line — go by that line.
While the game runs, a notice may say *hooking refused*.
| Why | Do this |
|---|---|
| Hooking was off for the game. | Switch **Hooking** on in the game's page, after reading [Anti-cheat and safety](04-anti-cheat-and-safety.md). |
| The game's file changed since hooking was switched on — an update, usually. | Switch hooking on again for it. |
| The game you added is its launcher. | Add the game's own `.exe` too: hooking a launcher does not reach the game it starts. |
| Anti-cheat was found in the game. | Nothing: FrameLedger will not hook it, and hooking stays off. The only exception is narrow ([Anti-cheat and safety](04-anti-cheat-and-safety.md#the-one-exception-you-can-make)). |
| An anti-cheat driver or service was running on the PC. It may belong to another game. | Close the program it belongs to: the next session is measured again. |
| Anti-cheat appeared while the game was running. | Nothing: measuring stopped, and the summary says *Measurement stopped early*. |
| FrameLedger could not check the game's files. | It checks again by itself; Tools ▸ Update detection rules checks now. |
| The game runs as administrator. | Settings ▸ Capture agent ▸ *Run the agent as administrator* — read its risk in [Limitations](../LIMITATIONS.md#running-the-agent-as-administrator) first. A game protected by an anti-cheat driver cannot be measured either way. |
| The game is 32-bit, uses DirectX 9, or uses Vulkan. | Nothing: these are recorded, not measured ([Limitations](../LIMITATIONS.md#games-it-will-not-measure)). |
| **Disable all hooking** is on. | Switch it off in Settings ▸ Capture. |
| The game was already running when FrameLedger was updated. | Close the game and start it again. |
| Hooking was switched off after the game crashed twice soon after it started. | Switch it on again in the game's page if the cause may be gone — after a driver update, for example. |
| The game's file is gone. | If only its drive letter changed, FrameLedger follows it within about 15 seconds; otherwise **Change executable…** on the game's page. |
| The component could not be loaded into the game. | [Report a problem](#report-a-problem). |
## Some numbers read N/A
- **Everything** reads N/A: the session was not measured — see above.
- **1% low** needs 1,000 of the game's own frames, and **0.1% low** 10,000: a shorter session reads N/A for them.
- **VSync** reads N/A for OpenGL games.
- **VRAM (this game)** reads N/A for the game's first second.
- **GPU sensors** on AMD and Intel cards have not been tested, and **GPU held back** is read on NVIDIA cards only.
- **A session's charts are gone**: its per-frame data was removed under *Raw series kept per game*
([Every setting](08-settings.md#recording)); its statistics stay.
- **Presented FPS** instead of the game's own frame rate, **video memory** that differs from an in-game overlay, and
**CPU temperature**: see [Questions and answers](06-faq.md).
## A session says the game crashed
*How it ended*, on the session's summary:
| It says | It means |
|---|---|
| ended normally | The game closed by itself. |
| ended with exit code 1 | What *End task* or `taskkill` leaves behind: not a crash. |
| crashed (0xC0000005 …) | The game ended with an error code. *0xC0000006* often points at a failing drive. |
| crashed (Windows logged an application error) | Windows recorded the game's crash. |
| crashed (the game started its crash reporter, …) | The game's own crash reporter started while it was ending. |
| interrupted | The agent itself stopped during the session; the session was rebuilt when the agent next started. |
More in [Limitations](../LIMITATIONS.md#when-a-game-crashed). If FrameLedger itself stops, it says *FrameLedger stopped
unexpectedly* and offers to report it.
## An update does not install
- *A session is running, so it is applied only after the session ends* — restart FrameLedger once the game has closed.
- *… is still loaded in a game FrameLedger measured* — close that game, then **Restart to update**.
- *Try again in about an hour* — GitHub limits how often it is asked. *Offline* — no connection.
- A download that fails its check twice: [report a problem](#report-a-problem).
- Windows warns about the installer: see [Install and first start](01-install.md#download-and-install).
## The database
Everything is in one file, the ledger. **Tools ▸ Database maintenance…**:
- **Check** reads the whole file. If it finds a problem, **Back up…** first, then [report a problem](#report-a-problem).
- **Back up…** writes a consistent copy wherever you choose, even while a game is recorded.
- **Sweep…** removes old per-frame data, as *Raw series kept per game* does; it needs the agent running.
- **Compact** gives freed space back to the disk; it waits until no game is being recorded.
- *The ledger was busy* — try again in a moment.
## Looking at a copy of your data
`FrameLedger.exe --data-dir <folder>` opens a **copy** of a data folder to look at — one sent with a bug report, for
example. The badge reads **Viewer — no Agent**: nothing is recorded and nothing on this PC is changed. It refuses your own
data folder.
## Report a problem
- **Help ▸ Report a bug…** (or Logs ▸ Export bug bundle) saves a zip on your PC with FrameLedger's logs, a description of
your PC and your settings — and, if you tick them, FrameLedger's last crash dump and the last session without its
frames, notes or tags. Your Windows user name is removed from the paths in the logs; the crash dump is not cleaned.
You see every file, then the issue form opens on GitHub, and you add the zip yourself: FrameLedger sends nothing.
- The logs are in `%LOCALAPPDATA%\FrameLedger\logs` (Logs ▸ Open logs folder).
- If FrameLedger missed a game's anti-cheat, use the **Safety gap** form instead
([Anti-cheat and safety](04-anti-cheat-and-safety.md#if-frameledger-missed-a-games-anti-cheat)).
+60
View File
@@ -0,0 +1,60 @@
# Words FrameLedger uses
What the words on FrameLedger's screens mean, in alphabetical order. How each figure is computed is in the developers'
[metrics document](../docs/03_METRICS.md).
- **0.1% low, 1% low** — the frame rate of the game's slowest 0.1% and 1% of frames. The further they fall below the
average, the less smooth the game felt. They need 10,000 and 1,000 of the game's own frames.
- **Agent** (the capture agent) — the program FrameLedger runs in the background, with your normal rights, that notices
a game starting and records it.
- **Anti-cheat finding** — what FrameLedger's anti-cheat check found for a game: a component loaded into it, a file or
folder of it, or the game itself on a list. A game with a finding is not hooked ([Anti-cheat and
safety](04-anti-cheat-and-safety.md)).
- **Bug bundle** — the zip **Help ▸ Report a bug…** writes on your PC. Nothing is sent by FrameLedger.
- **Compare** — two to five sessions side by side, from any of your games.
- **Disable all hooking** — the switch that stops every game from being hooked at once, whatever each game's own switch
says. Sessions are still recorded.
- **Displayed FPS** — the frames you saw, generated frames included.
- **FG factor** — Displayed FPS divided by Native FPS, shown as `×1.9 FG`.
- **FPS** — frames per second over the time measured.
- **Frame generation** — the technology (DLSS Frame Generation, FSR Frame Generation) that inserts frames the game did
not render itself.
- **Frame time** — how long one frame took, in milliseconds.
- **Frame to frame** — how much one frame's time differs from the next. Lower is smoother.
- **Frames per watt** — the game's own frames per second for each watt the graphics card drew.
- **GPU held back** — how much of the time the card's power limit or its temperature slowed it down. NVIDIA cards only.
- **Hooking** — loading FrameLedger's small component into a game to measure it. Off for every game until you switch
it on for that game.
- **Ledger** — the one database file that holds your library and sessions, `%LOCALAPPDATA%\FrameLedger\ledger.db`.
- **N/A** — not measured. Never 0, and never an estimate.
- **Native FPS** — the frames the game rendered itself.
- **Overlay build** — the version of the component that hooking loads into a game. It draws nothing on your screen.
- **Override** — your own Yes, No or N/A for a ray-tracing chip. The measured value is kept, and yours is marked as
yours.
- **Presented FPS** — every frame the game handed to Windows, shown when frame generation could not be measured, with a
note saying whether generated frames could be among them.
- **RAM (this game)** — the game's own memory, what Task Manager's Details tab shows as its private working set.
- **Ray tracing, Path tracing, Ray reconstruction** — read *Yes*, *No* or *N/A*. Ray tracing is measured on DirectX 12
games; path tracing is never stated as a fact.
- **Render scale** — the share of the screen's resolution the game drew at before upscaling. 100% means no upscaling.
- **Session** — one run of a game, from its start to its end. A session shorter than 30 seconds is not kept.
- **Steady state** — when frame generation changed during a session (menus, loading screens, a settings change), the
figures are for the state that lasted longest, with the share of the session it covers: `×1.9 FG · 75%`.
- **Stutter** — frames that took more than twice as long as the frames around them, counted, with the share of time
they took.
- **T1** — a measured session. **T2** — a session that was only recorded: how long you played, your PC's sensors and
the game's memory, with every frame figure N/A.
- **Tags and notes** — what you write on a session's summary.
- **Telemetry source** — which sensor readers work on this PC: `l1` is Windows itself, `lhm` is LibreHardwareMonitor,
`nvapi` is NVIDIA's own.
- **Time below 60 FPS** — how much of the session ran slower than 60 frames per second (and *below 30*, and *below your
display's refresh rate*), not counting the tiny wobble of a game held at its frame limit.
- **Trend** — one point per measured session over time, on a game's page.
- **Upscaler** — the technology that draws the game at a lower resolution and scales it up (DLSS, FSR).
- **User-mode exception** — the one way to hook a game where anti-cheat was found: only an anti-cheat that runs entirely
inside the game, one game at a time, after a warning. Its first two sessions are a trial.
- **Viewer** — FrameLedger opened over a copy of a data folder: no agent, nothing recorded, nothing changed.
- **VRAM (this game)** — the game's own video memory, what Task Manager shows as its *Dedicated GPU memory*.
- **VSync** — how many frames asked to wait for the display; *tearing allowed*, how many did not mind tearing. It is
what the game asked: your graphics driver can override it.
- **Vulkan layer** — the component that measures Vulkan games, used only when FrameLedger starts a game itself.
+7 -3
View File
@@ -4,7 +4,7 @@ FrameLedger records how your games run on this PC — frame rate, frame times, t
with, temperatures, and how much memory the game uses — and keeps every session so you can compare them later.
Everything stays on your PC.
Each page below takes a minute or two to read.
Each page below takes a minute or two to read. The first six are the guide; the next four are there to look things up.
1. [Install and first start](01-install.md)
2. [Record a game](02-record-a-game.md)
@@ -12,7 +12,11 @@ Each page below takes a minute or two to read.
4. [Anti-cheat and safety](04-anti-cheat-and-safety.md) — read this before you switch hooking on for any game
5. [Your data](05-your-data.md)
6. [Questions and answers](06-faq.md)
7. [The terms, in plain words](terms-in-plain-words.md)
7. [The screens](07-screens.md) — what each page, menu and button does
8. [Every setting](08-settings.md)
9. [When something goes wrong](09-troubleshooting.md)
10. [Words FrameLedger uses](10-glossary.md)
11. [The terms, in plain words](terms-in-plain-words.md)
What FrameLedger cannot do is listed on its own page: [Limitations](../LIMITATIONS.md) (in the app: Help ▸
Limitations).
@@ -21,4 +25,4 @@ Limitations).
report on your PC that you can look at before you decide to share it.
This guide is part of FrameLedger and describes the version it came with. It is also in the project's repository on
GitHub, in the `guide` folder.
GitHub, in the `guide` folder, and on the project's wiki, which shows the newest release.
+6 -3
View File
@@ -12,7 +12,7 @@
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-10-06.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.16`** (2026-10-06), an unsigned installer built from that tag with its
> **pre-release is `0.1.0-beta.20`** (2026-10-12), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -63,8 +63,11 @@
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
> files state.
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
> player library or its data file — without the release letter where only the library's number is readable),
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
> once a second from Windows' own counters, from outside the game, in every session: a game
+6 -3
View File
@@ -114,7 +114,7 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-10-06.** The software is a beta; its latest
> **pre-release is `0.1.0-beta.16`** (2026-10-06), an unsigned installer built from that tag with its
> **pre-release is `0.1.0-beta.20`** (2026-10-12), an unsigned installer built from that tag with its
> checksums published beside it. The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -165,8 +165,11 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> swap chain; for every other session the window alone is read, and a window covering its monitor reads
> *full-screen or borderless*. What Windows does behind the game (fullscreen optimizations) is not visible.
> - **Engine version:** the exact Unreal Engine 4 or 5 version, read from the game's executable on disk and
> labelled with what it rests on; `N/A` where the executable names none. Other engines show what their own
> files state.
> labelled with what it rests on; `N/A` where the executable names none. Since beta.19 also Unity's (from its
> player library or its data file — without the release letter where only the library's number is readable),
> Godot's (from its data pack) and RPG Maker's maker and version (MV and MZ from their core script; XP, VX and VX
> Ace by their runtime library's version, which is not the editor's). RPG Maker 2000/2003 is not detected. Since
> beta.20 also Ren'Py's (from its engine's version file). Other engines show what their own files state.
> - **The game's own memory (since beta.12):** its dedicated and shared GPU memory and its private
> working set — the numbers Task Manager's Details tab shows — with its working set and commit, read
> once a second from Windows' own counters, from outside the game, in every session: a game
+2 -2
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.7 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.9 · **Effective:** {{RELEASE_DATE}}
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
@@ -39,7 +39,7 @@ An exported session (CSV or JSON) and a bug report can contain your games' names
## 4. What the app can technically observe
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), and the store files that name it (Steam's and GOG's, on your disk) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; how busy the processor is and how much memory is in use, from Windows' own counters; the crash reports Windows keeps in its Application log about a tracked game's executable while it ran (to tell a crash from an ordinary exit — the reports are read, never sent anywhere); and the names of the programs a tracked game starts, so that a game's own crash reporter is recognised.
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation); the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; how busy the processor is and how much memory is in use, from Windows' own counters; the crash reports Windows keeps in its Application log about a tracked game's executable while it ran (to tell a crash from an ordinary exit — the reports are read, never sent anywhere); and the names of the programs a tracked game starts, so that a game's own crash reporter is recognised.
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
+6 -6
View File
@@ -42,7 +42,7 @@
"level, which made it a check that could not fire."
],
"schemaVersion": 2,
"rulesVersion": "2026.10.1",
"rulesVersion": "2026.10.3",
"engines": [
{
@@ -52,7 +52,7 @@
{ "type": "sibling_glob", "value": "UnityPlayer.dll" },
{ "type": "dir_exists", "value": "${ExeName}_Data" }
] },
"version": { "type": "pe_file_version", "from": "UnityPlayer.dll" }
"version": { "type": "unity_build" }
},
{
"id": "unreal",
@@ -70,7 +70,7 @@
{ "type": "sibling_glob", "value": "nw.dll" },
{ "type": "sibling_glob", "value": "package.json" }
] },
"version": null
"version": { "type": "rpgmaker_build" }
},
{
"id": "rpgmaker_rgss",
@@ -83,7 +83,7 @@
{ "type": "sibling_glob", "value": "*.rgss2a" },
{ "type": "sibling_glob", "value": "*.rgss3a" }
] },
"version": null
"version": { "type": "rpgmaker_build" }
},
{
"id": "re_engine",
@@ -109,7 +109,7 @@
{ "type": "sibling_glob", "value": "*.pck" },
{ "type": "strings_contains", "value": "Godot Engine v" }
] },
"version": { "type": "strings_regex", "value": "Godot Engine v(\\d+\\.\\d+[\\.\\d]*)" }
"version": { "type": "godot_build" }
},
{
"id": "gamemaker",
@@ -124,7 +124,7 @@
{ "type": "dir_exists", "value": "renpy" },
{ "type": "sibling_glob", "value": "*.rpa" }
] },
"version": null
"version": { "type": "renpy_build" }
},
{
"id": "cryengine",
+2 -2
View File
@@ -198,12 +198,12 @@
}
},
{
"$comment": "beta.10: Unreal Engine's build facts (the shipping executable's numeric file version and the engine's branch name inside it), decided in code (Domain.Detection.UnrealVersion) rather than by a pattern - which is why it takes no parameter.",
"$comment": "beta.10: Unreal Engine's build facts (the shipping executable's numeric file version and the engine's branch name inside it), decided in code (Domain.Detection.UnrealVersion) rather than by a pattern - which is why it takes no parameter. beta.19 adds Unity's (the player library's version resource, the data file's header), Godot's (a data pack's header, the executable's version resource) and RPG Maker's (MV/MZ's core-script header, the RGSS library Game.ini names), decided by UnityVersion, GodotVersion and RpgMakerVersion. beta.20 adds Ren'Py's (the version line of the engine's renpy/vc_version.py), decided by RenPyVersion.",
"type": "object",
"additionalProperties": false,
"required": ["type"],
"properties": {
"type": { "const": "unreal_build" }
"type": { "enum": ["unreal_build", "unity_build", "godot_build", "rpgmaker_build", "renpy_build"] }
}
}
]
@@ -147,6 +147,25 @@ internal static class AgentServices
services.AddSingleton<IDriverProfileSource>(static sp => sp.GetRequiredService<NvapiDriverProfileSource>());
}
/// <summary>
/// An entry whose game is no longer installed and that had no session goes (beta.19, D55): asked by the detection sweep after
/// the relocator, behind the user's switch, never while a session of it is recorded or waits to be recovered — the merge's
/// own busy test — and never for an entry carrying an anti-cheat block or exception (the delete's SQL checks again).
/// </summary>
private static void AddUninstalledEntryPrune(IServiceCollection services)
{
services.AddSingleton<IGamePrune>(static sp => new SqliteGamePrune(sp.GetRequiredService<LedgerDatabase>()));
services.AddSingleton<IExecutablePresence>(static _ => new ExecutablePresenceProbe(VolumeRoots.IsReady));
services.AddSingleton(static sp => new UninstalledEntryPrune(
sp.GetRequiredService<IGamePrune>(),
sp.GetRequiredService<IExecutablePresence>(),
ct => sp.GetRequiredService<RegisteredSettings>().GetBooleanAsync(SettingsRegistry.RetentionRemoveUninstalledGames, ct),
id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)
|| sp.GetRequiredService<IPartialSessionStore>().PendingGameIds().Contains(id),
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<IIpcEventPublisher>()));
}
/// <summary>The static detection sweep (P4 PR-1, <c>05_DETECTION</c> §Caching): hosted under <c>--serve</c> only, composed and inert under <c>--console</c>.</summary>
private static void AddDetection(IServiceCollection services, AgentPaths paths)
{
@@ -168,13 +187,15 @@ internal static class AgentServices
merge: sp.GetRequiredService<IGameMerge>(),
busy: id => sp.GetRequiredService<CaptureOrchestrator>().IsRecording(id)
|| sp.GetRequiredService<IPartialSessionStore>().PendingGameIds().Contains(id)));
AddUninstalledEntryPrune(services);
services.AddSingleton(static sp => new DetectionSweep(
sp.GetRequiredService<IGameRepository>(),
sp.GetRequiredService<IDetectionRulesSource>(),
sp.GetRequiredService<IGameFileProbe>(),
sp.GetRequiredService<IExecutableIdentitySource>(),
static line => Serilog.Log.Information("{Line}", line),
sp.GetRequiredService<ExecutableRelocator>()));
sp.GetRequiredService<ExecutableRelocator>(),
sp.GetRequiredService<UninstalledEntryPrune>()));
// The anti-cheat pre-scan of the library (beta.8, 19_SAFETY §What a finding does to the game): every entry through
// the guard's advisory checks 3 and 4, again whenever the rules or the executable change. It waits while a session
@@ -39,10 +39,10 @@ internal sealed class DetectionHostedService(DetectionSweep sweep, VkLayerReconc
DetectionSweepReport r = await sweep.SweepOnceAsync(stoppingToken).ConfigureAwait(false);
// Said when something happened or changed (2026-09-23): an unreadable entry used to repeat this line every
// 15 s — 5,760 a day — with nothing new in it.
if (r.Scanned > 0 || r.Relocated > 0 || r.RulesUnusable || (r.Unreadable > 0 && r.Unreadable != previous?.Unreadable))
if (r.Scanned > 0 || r.Relocated > 0 || r.Removed > 0 || r.RulesUnusable || (r.Unreadable > 0 && r.Unreadable != previous?.Unreadable))
{
Log.Information("detect: sweep scanned {Scanned}, current {Current}, unreadable {Unreadable}{Rules}",
r.Scanned, r.Current, r.Unreadable, r.RulesUnusable ? ", rules unusable" : string.Empty);
Log.Information("detect: sweep scanned {Scanned}, current {Current}, unreadable {Unreadable}, removed {Removed}{Rules}",
r.Scanned, r.Current, r.Unreadable, r.Removed, r.RulesUnusable ? ", rules unusable" : string.Empty);
}
previous = r;
+2 -1
View File
@@ -77,7 +77,8 @@ public partial class App : System.Windows.Application
HookCrashHandlers();
// 08_UI §Accessibility (P4 PR-8): Esc closes the open ContentDialog or MessageBox, before any window exists.
DialogKeyboard.Register();
// beta.14: ui.hide_scrollbars reaches every scroller as it loads, those in a control's template too.
// beta.14: ui.hide_scrollbars reaches every scroller as it is laid out (beta.17: not only as it loads), those in a
// control's template too.
ScrollBarHiding.Register();
_run = DiagReport.Requested(e.Args) ? DiagAsync() : RunAsync();
}
@@ -9,6 +9,7 @@
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
xmlns:charts="clr-namespace:FrameLedger.App.Charts"
Title="{x:Static res:Strings.Compare_Header}"
Foreground="{DynamicResource TextFillColorPrimaryBrush}"
ScrollViewer.CanContentScroll="False">
<!-- 08_UI §Compare: the picker (2–5, cross-game), the overlaid percentile curves, the stat table; FR-6.2's guard is the view model's. -->
<ScrollViewer VerticalScrollBarVisibility="Auto">
@@ -9,6 +9,7 @@
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
xmlns:controls="clr-namespace:FrameLedger.App.Controls"
Title="{x:Static res:Strings.Dashboard_Header}"
Foreground="{DynamicResource TextFillColorPrimaryBrush}"
ScrollViewer.CanContentScroll="False">
<ScrollViewer VerticalScrollBarVisibility="Auto">
<StackPanel Style="{StaticResource PageRoot}">
@@ -10,6 +10,7 @@
xmlns:controls="clr-namespace:FrameLedger.App.Controls"
xmlns:charts="clr-namespace:FrameLedger.App.Charts"
Title="{x:Static res:Strings.Games_Header}"
Foreground="{DynamicResource TextFillColorPrimaryBrush}"
ScrollViewer.CanContentScroll="False">
<!--
08_UI §Games › Game detail. The two rows — Supports (files on disk) and Last session measured (the
+1
View File
@@ -11,6 +11,7 @@
Title="{x:Static res:Strings.Games_Header}"
AllowDrop="True"
Drop="OnDrop"
Foreground="{DynamicResource TextFillColorPrimaryBrush}"
ScrollViewer.CanContentScroll="False">
<!--
08_UI §Games: search, sort, FR-1.1 add by pick or by dropping an .exe here. Since beta.11 (owner requests 2026-10-03):
+1
View File
@@ -8,6 +8,7 @@
xmlns:res="clr-namespace:FrameLedger.App"
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
Title="{x:Static res:Strings.Logs_Header}"
Foreground="{DynamicResource TextFillColorPrimaryBrush}"
ScrollViewer.CanContentScroll="False">
<Grid Margin="24,16,24,16">
<Grid.RowDefinitions>
+21 -3
View File
@@ -8,6 +8,7 @@
xmlns:res="clr-namespace:FrameLedger.App"
xmlns:vm="clr-namespace:FrameLedger.App.ViewModels"
Title="{x:Static res:Strings.Settings_Header}"
Foreground="{DynamicResource TextFillColorPrimaryBrush}"
ScrollViewer.CanContentScroll="False">
<ScrollViewer VerticalScrollBarVisibility="Auto">
<StackPanel Style="{StaticResource PageRoot}">
@@ -83,7 +84,7 @@
Text="{x:Static res:Strings.Settings_Exceptions_Body}" />
</StackPanel>
<ui:ToggleSwitch Grid.Column="1" Margin="12,0" AutomationProperties.Name="{x:Static res:Strings.Settings_Exceptions_Label}"
IsChecked="{Binding ViewModel.UserModeExceptions, Mode=TwoWay}" />
IsChecked="{Binding ViewModel.UserModeExceptions, Mode=TwoWay}" IsEnabled="{Binding ViewModel.ActsOnThisPc}" />
</Grid>
</ui:CardExpander.Header>
<StackPanel>
@@ -164,7 +165,8 @@
Content="{x:Static res:Strings.Settings_SafetyDocs}"
Icon="{ui:SymbolIcon Open24}" />
<!-- Recording policy: the three numbers and background capture (D16: the Agent reads them at session start). -->
<!-- Recording policy: the three numbers and background capture (D16: the Agent reads them at session start) — off in a
viewer, which has no Agent (beta.18; every setting the Agent reads is, ViewerModeTests). -->
<ui:TextBlock FontTypography="Subtitle" Margin="0,20,0,8" Text="{x:Static res:Strings.Settings_Policy_Header}" />
<ui:CardControl Margin="0,4,0,0" Icon="{ui:SymbolIcon Timer24}">
<ui:CardControl.Header>
@@ -175,6 +177,7 @@
</ui:CardControl.Header>
<ui:NumberBox MinWidth="140"
AutomationProperties.Name="{x:Static res:Strings.Settings_MinSession_Label}"
IsEnabled="{Binding ViewModel.ActsOnThisPc}"
Maximum="{x:Static vm:SettingsViewModel.MinSessionMaximum}"
Minimum="{x:Static vm:SettingsViewModel.MinSessionMinimum}"
SpinButtonPlacementMode="Inline"
@@ -189,6 +192,7 @@
</ui:CardControl.Header>
<ui:NumberBox MinWidth="140"
AutomationProperties.Name="{x:Static res:Strings.Settings_Interval_Label}"
IsEnabled="{Binding ViewModel.ActsOnThisPc}"
Maximum="{x:Static vm:SettingsViewModel.IntervalMaximum}"
Minimum="{x:Static vm:SettingsViewModel.IntervalMinimum}"
SpinButtonPlacementMode="Inline"
@@ -203,6 +207,7 @@
</ui:CardControl.Header>
<ui:NumberBox MinWidth="140"
AutomationProperties.Name="{x:Static res:Strings.Settings_Retention_Label}"
IsEnabled="{Binding ViewModel.ActsOnThisPc}"
Maximum="{x:Static vm:SettingsViewModel.RetentionMaximum}"
Minimum="0"
SpinButtonPlacementMode="Inline"
@@ -214,7 +219,19 @@
<!-- beta.11 (owner request 2026-10-03: no row without a control): Data - Delete all sessions (D40). -->
<ui:TextBlock FontTypography="Subtitle" Margin="0,20,0,8" Text="{x:Static res:Strings.Settings_Data_Header}" />
<ui:CardControl Margin="0,4,0,0" Icon="{ui:SymbolIcon Delete24}">
<!-- beta.19 (owner decision D55): the Agent removes an entry whose game is no longer installed and that has no session. -->
<ui:CardControl Margin="0,4,0,0" Icon="{ui:SymbolIcon BoxDismiss24}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_RemoveUninstalled_Label}" />
<ui:TextBlock MaxWidth="560" HorizontalAlignment="Left" Style="{StaticResource SecondaryText}" Text="{x:Static res:Strings.Settings_RemoveUninstalled_Body}" TextWrapping="Wrap" />
</StackPanel>
</ui:CardControl.Header>
<ui:ToggleSwitch AutomationProperties.Name="{x:Static res:Strings.Settings_RemoveUninstalled_Label}"
IsChecked="{Binding ViewModel.RemoveUninstalledGames, Mode=TwoWay}"
IsEnabled="{Binding ViewModel.ActsOnThisPc}" />
</ui:CardControl>
<ui:CardControl Margin="0,8,0,0" Icon="{ui:SymbolIcon Delete24}">
<ui:CardControl.Header>
<StackPanel>
<ui:TextBlock FontTypography="BodyStrong" Text="{x:Static res:Strings.Settings_DeleteSessions_Label}" />
@@ -341,6 +358,7 @@
<ComboBox MinWidth="140"
AutomationProperties.Name="{x:Static res:Strings.Settings_UpdateChannel_Label}"
DisplayMemberPath="Label"
IsEnabled="{Binding ViewModel.ActsOnThisPc}"
ItemsSource="{Binding ViewModel.UpdateChannels}"
SelectedValue="{Binding ViewModel.UpdateChannel, Mode=TwoWay}"
SelectedValuePath="Value" />
@@ -24,7 +24,8 @@ public sealed record AntiCheatExceptionResult(AntiCheatExceptionOutcome Outcome,
RefusalText() ?? Detail ?? Strings.Common_NotAvailable),
AntiCheatExceptionOutcome.VersionMismatch => Shared.Strings.Safety_Exception_VersionMismatch,
AntiCheatExceptionOutcome.OptionOff => Shared.Strings.Safety_Exception_OptionOff,
AntiCheatExceptionOutcome.AgentUnavailable => Shared.Strings.Safety_Consent_AgentUnavailable,
// A grant and a withdrawal alike (beta.18): "Nothing was enabled." was the hooking consent's words, untrue for a withdrawal.
AntiCheatExceptionOutcome.AgentUnavailable => Strings.Agent_NotConnected_NothingChanged,
AntiCheatExceptionOutcome.Failed => Detail ?? Strings.Common_NotAvailable,
_ => null,
};
@@ -23,6 +23,7 @@ public static class EmbeddedDocuments
/// <summary>
/// The user guide's pages in reading order (beta.12, D44; <c>guide/</c> in the repository). Each page's title is its
/// first heading; <see cref="LimitationsDocument"/> closes the list, so the guide's links to it open in the window.
/// beta.17 (D54): the four reference pages after the FAQ make the guide the wiki's End-user part too.
/// </summary>
public static IReadOnlyList<string> GuidePages { get; } =
[
@@ -33,6 +34,10 @@ public static class EmbeddedDocuments
"guide/04-anti-cheat-and-safety.md",
"guide/05-your-data.md",
"guide/06-faq.md",
"guide/07-screens.md",
"guide/08-settings.md",
"guide/09-troubleshooting.md",
"guide/10-glossary.md",
"guide/terms-in-plain-words.md",
];
+32
View File
@@ -202,6 +202,38 @@ public static class Formats
_ => id,
};
/// <summary>
/// The engine's name as its version's witness names it (beta.19): each RPG Maker rule covers several makers, and the
/// file the version was read from says which — MZ's or MV's core script, an RGSS1, RGSS2 or RGSS3 library (XP, VX,
/// VX Ace). Any other engine, or no witness, is <see cref="Engine(string?)"/>.
/// </summary>
public static string Engine(string? id, string? versionSource) => (id, versionSource) switch
{
("rpgmaker_mv", EngineVersionSource.RpgMakerMzCore) => "RPG Maker MZ",
("rpgmaker_mv", EngineVersionSource.RpgMakerMvCore) => "RPG Maker MV",
("rpgmaker_rgss", EngineVersionSource.Rgss1Library) => "RPG Maker XP",
("rpgmaker_rgss", EngineVersionSource.Rgss2Library) => "RPG Maker VX",
("rpgmaker_rgss", EngineVersionSource.Rgss3Library) => "RPG Maker VX Ace",
_ => Engine(id),
};
/// <summary>
/// The engine and its version as one text (beta.19): "Unreal Engine 5.4.4", "Unity 2022.3.39f1", "Godot 4.4.1", "RPG Maker
/// MZ 1.10.0" — and "RPG Maker VX Ace (RGSS 3.0.1)", whose number is its runtime library's, not the maker's.
/// </summary>
public static string EngineWithVersion(string? id, string? version, string? versionSource)
{
string name = Engine(id, versionSource);
if (id is null || string.IsNullOrWhiteSpace(version))
{
return name;
}
return versionSource is EngineVersionSource.Rgss1Library or EngineVersionSource.Rgss2Library or EngineVersionSource.Rgss3Library
? string.Create(CultureInfo.InvariantCulture, $"{name} (RGSS {version})")
: string.Create(CultureInfo.InvariantCulture, $"{name} {version}");
}
/// <summary>What an executable runs as (<c>games.exe_machine</c>, beta.8), in the user's language.</summary>
public static string Architecture(string? id) => id switch
{
@@ -0,0 +1,76 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.IO;
using FrameLedger.Infrastructure.Detection;
namespace FrameLedger.App.Services;
/// <summary>
/// The folder Change executable… opens in (beta.19, owner request 2026-10-12): the game's own root folder rather than
/// wherever Windows' dialog was last — the pick is almost always another file of the same install.
/// </summary>
/// <remarks>
/// <para>
/// The root is <see cref="InstallRoot.Resolve"/>'s — the folder a store boundary names (<c>steamapps\common\X</c>,
/// <c>GOG Galaxy\Games\X</c>, <c>Epic Games\X</c>, <c>GamesInstalled\X</c>) — and, where no boundary is recognised, out of
/// an Unreal package's <c>&lt;root&gt;\&lt;Project&gt;\Binaries\Win64</c> to <c>&lt;root&gt;</c>, else the executable's own
/// folder. Only the row's path is stored (no install folder), so this is derived, never remembered.
/// </para>
/// <para>
/// An entry whose folder is gone (*Not installed*) opens at the nearest folder above it that is still there; an entry on a
/// drive that is not connected gets null, and the dialog opens where Windows last was. It asks the file system, so its
/// caller runs it off the UI thread: a share that went away can take seconds to answer.
/// </para>
/// </remarks>
public static class GameFolder
{
/// <summary>The folder to open the pick in for an entry at <paramref name="exePath"/>, or null when there is none.</summary>
public static string? StartFolder(string exePath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
string full;
try
{
full = Path.GetFullPath(exePath);
}
catch (Exception ex) when (ex is ArgumentException or NotSupportedException or PathTooLongException)
{
return null;
}
string? drive = Path.GetPathRoot(full);
if (string.IsNullOrEmpty(drive) || !Directory.Exists(drive))
{
return null;
}
string exeDirectory = Path.GetDirectoryName(full) ?? drive;
string root = InstallRoot.Resolve(full);
if (string.Equals(root, exeDirectory, StringComparison.OrdinalIgnoreCase) && UnrealRoot(exeDirectory) is { } unreal)
{
root = unreal;
}
for (string? folder = root; !string.IsNullOrEmpty(folder); folder = Path.GetDirectoryName(folder))
{
if (Directory.Exists(folder))
{
return folder;
}
}
return drive;
}
/// <summary><c>&lt;root&gt;\&lt;Project&gt;\Binaries\Win64</c> (or <c>WinGDK</c>) → <c>&lt;root&gt;</c>; null for any other folder.</summary>
private static string? UnrealRoot(string exeDirectory)
{
string platform = Path.GetFileName(exeDirectory);
string? binaries = Path.GetDirectoryName(exeDirectory);
bool unreal = (string.Equals(platform, "Win64", StringComparison.OrdinalIgnoreCase) || string.Equals(platform, "WinGDK", StringComparison.OrdinalIgnoreCase))
&& binaries is not null && string.Equals(Path.GetFileName(binaries), "Binaries", StringComparison.OrdinalIgnoreCase);
string? project = unreal ? Path.GetDirectoryName(binaries) : null;
return project is null ? null : Path.GetDirectoryName(project);
}
}
+9 -1
View File
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.IO;
using Microsoft.Win32;
namespace FrameLedger.App.Services;
@@ -8,7 +9,7 @@ namespace FrameLedger.App.Services;
/// <summary>The WPF <see cref="OpenFileDialog"/> for FR-1.1.</summary>
public sealed class GamePicker : IGamePicker
{
public string? PickExecutable()
public string? PickExecutable(string? initialDirectory = null)
{
var dialog = new OpenFileDialog
{
@@ -17,6 +18,13 @@ public sealed class GamePicker : IGamePicker
CheckFileExists = true,
Multiselect = false,
};
// InitialDirectory opens the dialog there whatever folder it remembers (DefaultDirectory would only be a fallback).
if (!string.IsNullOrEmpty(initialDirectory) && Directory.Exists(initialDirectory))
{
dialog.InitialDirectory = initialDirectory;
}
return dialog.ShowDialog() == true ? dialog.FileName : null;
}
}
+5 -1
View File
@@ -7,5 +7,9 @@ namespace FrameLedger.App.Services;
public interface IGamePicker
{
/// <summary>The chosen executable's full path, or null when the user cancelled.</summary>
string? PickExecutable();
/// <param name="initialDirectory">
/// The folder the dialog opens in (beta.19: Change executable… opens in the game's own folder, <see cref="GameFolder"/>);
/// null leaves it to Windows, which opens where the last pick was.
/// </param>
string? PickExecutable(string? initialDirectory = null);
}
+40 -27
View File
@@ -55,13 +55,16 @@ public sealed class SafetyNotices : IDisposable
return new SafetyNotice(SafetyNoticeKind.Unhooked, Strings.Notice_Unhooked_Title, TurnedOff(UnhookText(unhooked), unhooked.HookingTurnedOff), now);
// The Agent's pre-scan of the library turned hooking off for a game the user had turned it on for (2026-09-25):
// not a session event, so none of a refusal's "this run is still recorded" — no run is going on.
// Its reason is the guard's own, and it is sent only for a finding about the game, which names its family.
case IpcMessageType.HookingTurnedOff when IpcCodec.Payload<HookingTurnedOffEvent>(envelope) is { } off:
return new SafetyNotice(SafetyNoticeKind.HookingOff,
string.Format(CultureInfo.CurrentCulture, Strings.Notice_HookingOff_Title_Format, off.GameName ?? Strings.Common_NotAvailable),
TurnedOff(RefusalText(off.Reason, off.Reason, off.Family, off.Signal), turnedOff: true), now);
TurnedOff(GuardText(off.Reason, off.Family, off.Signal) ?? Shared.Strings.Safety_Refused_Unnamed, turnedOff: true), now);
// The session's end in words (beta.18): it printed the enum's name — "The hook stopped (WriterSelfDisabled)" —
// and said the session continued without measuring, while a stop ends it (07_IPC: measurement STOPPED).
case IpcMessageType.CaptureDegraded when IpcCodec.Payload<CaptureDegradedEvent>(envelope) is { } degraded:
return new SafetyNotice(SafetyNoticeKind.Degraded, Strings.Notice_Degraded_Title,
string.Format(CultureInfo.CurrentCulture, Strings.Notice_Degraded_Body_Format, degraded.Reason), now);
Formats.EndReasonText(degraded.Reason) ?? string.Format(CultureInfo.CurrentCulture, Strings.Notice_Degraded_Unknown_Format, degraded.Reason), now);
default:
return null;
}
@@ -73,35 +76,45 @@ public sealed class SafetyNotices : IDisposable
/// <summary>
/// A driver or service that started on the PC mid-session is said as that (beta.13, §S23-3) — not "detected while the
/// game was running … until you enable it again", which was untrue twice: such a finding turns no hooking off, and a
/// finding about the game turns it off for good (the turned-off sentence follows).
/// finding about the game turns it off for good (the turned-off sentence follows). A re-scan that could not look while
/// the game still ran is said as that too (beta.18): it named its signal as a finding, "Access is denied was detected".
/// </summary>
private static string UnhookText(SafetyUnhookEvent unhooked) =>
Formats.IsMachineWide(unhooked.GuardReason) && unhooked.Family is { } family
? string.Format(CultureInfo.CurrentCulture, Shared.Strings.Safety_Unhooked_MachineWide_Format, family, unhooked.Signal ?? Strings.Common_NotAvailable)
: string.Format(CultureInfo.CurrentCulture, Shared.Strings.Safety_Unhooked_Format, unhooked.Family ?? unhooked.Signal ?? Strings.Common_NotAvailable);
/// <summary><paramref name="reason"/> is the session's end reason; <paramref name="guardReason"/> the guard's own, when it named a family.</summary>
private static string RefusalText(string reason, string? guardReason, string? family, string? signal)
private static string UnhookText(SafetyUnhookEvent unhooked) => unhooked switch
{
if (string.Equals(reason, "PreScanCouldNotVerify", StringComparison.Ordinal))
{
return Shared.Strings.Safety_Refused_CouldNotVerify;
}
{ Family: { } family } when Formats.IsMachineWide(unhooked.GuardReason) =>
string.Format(CultureInfo.CurrentCulture, Shared.Strings.Safety_Unhooked_MachineWide_Format, family, unhooked.Signal ?? Strings.Common_NotAvailable),
{ Family: null, GuardReason: { Length: > 0 } guardReason } =>
string.Format(CultureInfo.CurrentCulture, Shared.Strings.Safety_Unhooked_Unnamed_Format, Formats.GuardReasonText(guardReason)),
_ => string.Format(CultureInfo.CurrentCulture, Shared.Strings.Safety_Unhooked_Format, unhooked.Family ?? unhooked.Signal ?? Strings.Common_NotAvailable),
};
if (string.Equals(reason, "TargetUnreadable", StringComparison.Ordinal))
{
return Shared.Strings.Safety_Refused_TargetUnreadable;
}
/// <summary>
/// A refusal in words. <paramref name="reason"/> is the session's end; <paramref name="guardReason"/> the guard's own,
/// sent for every refusal it gave since beta.18 (beside a family only, before).
/// </summary>
private static string RefusalText(string reason, string? guardReason, string? family, string? signal) => reason switch
{
"PreScanCouldNotVerify" => Shared.Strings.Safety_Refused_CouldNotVerify,
"TargetUnreadable" => Shared.Strings.Safety_Refused_TargetUnreadable,
// What the guard found, or could not do; from an agent that sent no reason beside no family, the end's own words.
"RefusedByGuard" => GuardText(guardReason, family, signal) ?? Strings.End_RefusedByGuard,
// The gate's own refusals (beta.18) — Disable all hooking, a game blocked before — are the user's switch or the row's,
// never a finding. The gate labels them in the family's place, and the kill switch's notice read "kill switch was
// detected in this game (the global 'disable all hooking' switch is on (FR-2.4); …)".
// A name this build has no words for (a newer agent's) is named as it is, never as something detected.
_ => Formats.EndReasonText(reason) ?? GuardText(guardReason, family, signal)
?? (string.IsNullOrEmpty(reason) ? Shared.Strings.Safety_Refused_Unnamed : Formats.GuardSentence(reason)),
};
// A refusal no anti-cheat family names (beta.8) — the guard could not look, the game is 32-bit — is said as what it
// is. It used to name its SIGNAL as the family, and the notice read "Access is denied was detected in this game".
if (family is null)
{
return string.IsNullOrEmpty(reason) ? Shared.Strings.Safety_Refused_Unnamed : Formats.GuardSentence(reason);
}
return Formats.NamedRefusal(guardReason, family, signal ?? reason);
}
/// <summary>
/// What the guard said, as a sentence: an anti-cheat it named, found in this game or on this PC; a refusal no family names
/// (beta.8) in its own words — never its signal as the family, which read "Access is denied was detected in this game".
/// Null when it said nothing.
/// </summary>
private static string? GuardText(string? guardReason, string? family, string? signal) =>
family is { Length: > 0 }
? Formats.NamedRefusal(guardReason, family, signal ?? Strings.Common_NotAvailable)
: guardReason is { Length: > 0 } ? Formats.GuardSentence(guardReason) : null;
private void OnEvent(object? sender, AgentEventArgs e)
{
@@ -10,13 +10,22 @@ namespace FrameLedger.App.Services;
/// <summary>
/// <c>ui.hide_scrollbars</c> (beta.14, owner request 2026-10-05): the App draws no scroll bars, and every scroller still
/// scrolls — with the wheel, the keyboard and touch. A bar's visibility is bound in its scroller's template, so no style can
/// reach it; this sets the scroller's own <see cref="ScrollBarVisibility"/> instead. One class handler on
/// <see cref="ScrollViewer"/>'s <c>Loaded</c>, registered at start beside <see cref="DialogKeyboard"/>, sees every scroller the
/// App shows, those inside a control's template too (a DataGrid's, a TextBox's, a rendered document's, a dialog's). While
/// on, an axis whose bar is <see cref="ScrollBarVisibility.Auto"/> or <see cref="ScrollBarVisibility.Visible"/> becomes
/// reach it; this sets the scroller's own <see cref="ScrollBarVisibility"/> instead, from two class handlers on
/// <see cref="ScrollViewer"/> registered at start beside <see cref="DialogKeyboard"/>, which reach every scroller the App shows,
/// those inside a control's template too (a DataGrid's, a TextBox's, a rendered document's, a dialog's):
/// <list type="bullet">
/// <item><c>ScrollChanged</c>, which every scroller raises from its first layout, when its extent and viewport stop being
/// zero, and again whenever they change — inside the layout pass, so the bar is gone before the first frame is drawn.</item>
/// <item><c>Loaded</c>, which beta.14 relied on alone, wrongly (beta.17, the owner's screenshot: the Dashboard kept its bar).
/// WPF raises Loaded only on an element whose subtree listens for it with a handler of its own — an instance handler, a
/// style's EventSetter, a template's trigger — and a class handler is none of those; WPF UI's toggle switches carry one,
/// so Settings was hidden and the Dashboard, all cards and text, never was. It stays for a scroller that comes back with
/// nothing to lay out again.</item>
/// </list>
/// While on, an axis whose bar is <see cref="ScrollBarVisibility.Auto"/> or <see cref="ScrollBarVisibility.Visible"/> becomes
/// <see cref="ScrollBarVisibility.Hidden"/> — WPF's "no bar, still scrolls" — and its own value is remembered on it;
/// <see cref="ScrollBarVisibility.Disabled"/> is never touched, because a disabled axis lays its content out at the viewport's
/// size and wraps text. Off puts every remembered value back, on screen at once and on the next load for the rest.
/// size and wraps text. Off puts every remembered value back, on screen at once and at the next layout for the rest.
/// </summary>
public static class ScrollBarHiding
{
@@ -32,11 +41,12 @@ public static class ScrollBarHiding
/// <summary>Whether the bars are hidden right now.</summary>
public static bool Hidden => _hidden;
/// <summary>Registers the class handler, once per process.</summary>
/// <summary>Registers the class handlers, once per process.</summary>
public static void Register()
{
if (Interlocked.Exchange(ref _registered, 1) == 0)
{
EventManager.RegisterClassHandler(typeof(ScrollViewer), ScrollViewer.ScrollChangedEvent, new ScrollChangedEventHandler(OnScrollChanged), handledEventsToo: true);
EventManager.RegisterClassHandler(typeof(ScrollViewer), FrameworkElement.LoadedEvent, new RoutedEventHandler(OnLoaded), handledEventsToo: true);
}
}
@@ -96,6 +106,15 @@ public static class ScrollBarHiding
}
}
// ScrollChanged bubbles: a scroller's ancestors that are scrollers hear it too, and each gets the same idempotent check.
private static void OnScrollChanged(object sender, ScrollChangedEventArgs e)
{
if (sender is ScrollViewer viewer)
{
Set(viewer);
}
}
private static void Set(ScrollViewer viewer)
{
Axis(viewer, ScrollViewer.VerticalScrollBarVisibilityProperty, _ownVerticalProperty);
+60 -3
View File
@@ -62,6 +62,7 @@ public static class Strings
nameof(Agent_Banner_Offline_Body),
nameof(Agent_Banner_Offline_Title),
nameof(Agent_Banner_Retry),
nameof(Agent_NotConnected_NothingChanged),
nameof(Agent_State_Connected),
nameof(Agent_State_Connecting),
nameof(Agent_State_Elevating),
@@ -445,8 +446,18 @@ public static class Strings
nameof(GameDetail_Edit),
nameof(GameDetail_EngineVersion_Branch),
nameof(GameDetail_EngineVersion_BranchAndFile),
nameof(GameDetail_EngineVersion_CoreScript_Format),
nameof(GameDetail_EngineVersion_FileVersion),
nameof(GameDetail_EngineVersion_GodotExe),
nameof(GameDetail_EngineVersion_GodotPack),
nameof(GameDetail_EngineVersion_GodotPackEmbedded),
nameof(GameDetail_EngineVersion_NotFound),
nameof(GameDetail_EngineVersion_NotFoundInFiles),
nameof(GameDetail_EngineVersion_RenPyVcVersion),
nameof(GameDetail_EngineVersion_Rgss),
nameof(GameDetail_EngineVersion_UnityData),
nameof(GameDetail_EngineVersion_UnityPlayer),
nameof(GameDetail_EngineVersion_UnityPlayerFile),
nameof(GameDetail_Exception_Grant),
nameof(GameDetail_Exception_Granted_Format),
nameof(GameDetail_Exception_Header),
@@ -509,6 +520,10 @@ public static class Strings
nameof(Games_NoMatch),
nameof(Games_Refresh),
nameof(Games_Refresh_ToolTip),
nameof(Games_Removed_Format),
nameof(Games_Removed_Many_Format),
nameof(Games_Removed_More_Format),
nameof(Games_Removed_Title),
nameof(Games_Search_Placeholder),
nameof(Games_Sort_Label),
nameof(Games_Sort_LastPlayed),
@@ -645,8 +660,8 @@ public static class Strings
nameof(Nav_Games),
nameof(Nav_Logs),
nameof(Nav_Settings),
nameof(Notice_Degraded_Body_Format),
nameof(Notice_Degraded_Title),
nameof(Notice_Degraded_Unknown_Format),
nameof(Notice_Dismiss),
nameof(Notice_Error_Title),
nameof(Notice_HookingOff_Title_Format),
@@ -810,6 +825,7 @@ public static class Strings
nameof(Settings_Interval_Body),
nameof(Settings_Interval_Label),
nameof(Settings_Invalid_Format),
nameof(Settings_KillSwitch_Applied_On),
nameof(Settings_KillSwitch_Body),
nameof(Settings_KillSwitch_Label),
nameof(Settings_KillSwitch_Off),
@@ -828,6 +844,9 @@ public static class Strings
nameof(Settings_OnlineMetadata_Label),
nameof(Settings_Policy_Header),
nameof(Settings_Privacy_Header),
nameof(Settings_RemoveUninstalled_Applied),
nameof(Settings_RemoveUninstalled_Body),
nameof(Settings_RemoveUninstalled_Label),
nameof(Settings_Retention_Body),
nameof(Settings_Retention_Label),
nameof(Settings_SafetyDocs),
@@ -1124,6 +1143,8 @@ public static class Strings
public static string Agent_Banner_Retry => ResourceManager.GetString(nameof(Agent_Banner_Retry), Culture) ?? nameof(Agent_Banner_Retry);
public static string Agent_NotConnected_NothingChanged => ResourceManager.GetString(nameof(Agent_NotConnected_NothingChanged), Culture) ?? nameof(Agent_NotConnected_NothingChanged);
public static string Agent_State_Connected => ResourceManager.GetString(nameof(Agent_State_Connected), Culture) ?? nameof(Agent_State_Connected);
public static string Agent_State_Connecting => ResourceManager.GetString(nameof(Agent_State_Connecting), Culture) ?? nameof(Agent_State_Connecting);
@@ -1890,10 +1911,30 @@ public static class Strings
public static string GameDetail_EngineVersion_BranchAndFile => ResourceManager.GetString(nameof(GameDetail_EngineVersion_BranchAndFile), Culture) ?? nameof(GameDetail_EngineVersion_BranchAndFile);
public static string GameDetail_EngineVersion_CoreScript_Format => ResourceManager.GetString(nameof(GameDetail_EngineVersion_CoreScript_Format), Culture) ?? nameof(GameDetail_EngineVersion_CoreScript_Format);
public static string GameDetail_EngineVersion_FileVersion => ResourceManager.GetString(nameof(GameDetail_EngineVersion_FileVersion), Culture) ?? nameof(GameDetail_EngineVersion_FileVersion);
public static string GameDetail_EngineVersion_GodotExe => ResourceManager.GetString(nameof(GameDetail_EngineVersion_GodotExe), Culture) ?? nameof(GameDetail_EngineVersion_GodotExe);
public static string GameDetail_EngineVersion_GodotPack => ResourceManager.GetString(nameof(GameDetail_EngineVersion_GodotPack), Culture) ?? nameof(GameDetail_EngineVersion_GodotPack);
public static string GameDetail_EngineVersion_GodotPackEmbedded => ResourceManager.GetString(nameof(GameDetail_EngineVersion_GodotPackEmbedded), Culture) ?? nameof(GameDetail_EngineVersion_GodotPackEmbedded);
public static string GameDetail_EngineVersion_NotFound => ResourceManager.GetString(nameof(GameDetail_EngineVersion_NotFound), Culture) ?? nameof(GameDetail_EngineVersion_NotFound);
public static string GameDetail_EngineVersion_NotFoundInFiles => ResourceManager.GetString(nameof(GameDetail_EngineVersion_NotFoundInFiles), Culture) ?? nameof(GameDetail_EngineVersion_NotFoundInFiles);
public static string GameDetail_EngineVersion_RenPyVcVersion => ResourceManager.GetString(nameof(GameDetail_EngineVersion_RenPyVcVersion), Culture) ?? nameof(GameDetail_EngineVersion_RenPyVcVersion);
public static string GameDetail_EngineVersion_Rgss => ResourceManager.GetString(nameof(GameDetail_EngineVersion_Rgss), Culture) ?? nameof(GameDetail_EngineVersion_Rgss);
public static string GameDetail_EngineVersion_UnityData => ResourceManager.GetString(nameof(GameDetail_EngineVersion_UnityData), Culture) ?? nameof(GameDetail_EngineVersion_UnityData);
public static string GameDetail_EngineVersion_UnityPlayer => ResourceManager.GetString(nameof(GameDetail_EngineVersion_UnityPlayer), Culture) ?? nameof(GameDetail_EngineVersion_UnityPlayer);
public static string GameDetail_EngineVersion_UnityPlayerFile => ResourceManager.GetString(nameof(GameDetail_EngineVersion_UnityPlayerFile), Culture) ?? nameof(GameDetail_EngineVersion_UnityPlayerFile);
public static string GameDetail_Exception_Grant => ResourceManager.GetString(nameof(GameDetail_Exception_Grant), Culture) ?? nameof(GameDetail_Exception_Grant);
public static string GameDetail_Exception_Granted_Format => ResourceManager.GetString(nameof(GameDetail_Exception_Granted_Format), Culture) ?? nameof(GameDetail_Exception_Granted_Format);
@@ -2018,6 +2059,14 @@ public static class Strings
public static string Games_Refresh_ToolTip => ResourceManager.GetString(nameof(Games_Refresh_ToolTip), Culture) ?? nameof(Games_Refresh_ToolTip);
public static string Games_Removed_Format => ResourceManager.GetString(nameof(Games_Removed_Format), Culture) ?? nameof(Games_Removed_Format);
public static string Games_Removed_Many_Format => ResourceManager.GetString(nameof(Games_Removed_Many_Format), Culture) ?? nameof(Games_Removed_Many_Format);
public static string Games_Removed_More_Format => ResourceManager.GetString(nameof(Games_Removed_More_Format), Culture) ?? nameof(Games_Removed_More_Format);
public static string Games_Removed_Title => ResourceManager.GetString(nameof(Games_Removed_Title), Culture) ?? nameof(Games_Removed_Title);
public static string Games_Search_Placeholder => ResourceManager.GetString(nameof(Games_Search_Placeholder), Culture) ?? nameof(Games_Search_Placeholder);
public static string Games_Sort_Label => ResourceManager.GetString(nameof(Games_Sort_Label), Culture) ?? nameof(Games_Sort_Label);
@@ -2290,10 +2339,10 @@ public static class Strings
public static string Nav_Settings => ResourceManager.GetString(nameof(Nav_Settings), Culture) ?? nameof(Nav_Settings);
public static string Notice_Degraded_Body_Format => ResourceManager.GetString(nameof(Notice_Degraded_Body_Format), Culture) ?? nameof(Notice_Degraded_Body_Format);
public static string Notice_Degraded_Title => ResourceManager.GetString(nameof(Notice_Degraded_Title), Culture) ?? nameof(Notice_Degraded_Title);
public static string Notice_Degraded_Unknown_Format => ResourceManager.GetString(nameof(Notice_Degraded_Unknown_Format), Culture) ?? nameof(Notice_Degraded_Unknown_Format);
public static string Notice_Dismiss => ResourceManager.GetString(nameof(Notice_Dismiss), Culture) ?? nameof(Notice_Dismiss);
public static string Notice_Error_Title => ResourceManager.GetString(nameof(Notice_Error_Title), Culture) ?? nameof(Notice_Error_Title);
@@ -2620,6 +2669,8 @@ public static class Strings
public static string Settings_Invalid_Format => ResourceManager.GetString(nameof(Settings_Invalid_Format), Culture) ?? nameof(Settings_Invalid_Format);
public static string Settings_KillSwitch_Applied_On => ResourceManager.GetString(nameof(Settings_KillSwitch_Applied_On), Culture) ?? nameof(Settings_KillSwitch_Applied_On);
public static string Settings_KillSwitch_Body => ResourceManager.GetString(nameof(Settings_KillSwitch_Body), Culture) ?? nameof(Settings_KillSwitch_Body);
public static string Settings_KillSwitch_Label => ResourceManager.GetString(nameof(Settings_KillSwitch_Label), Culture) ?? nameof(Settings_KillSwitch_Label);
@@ -2656,6 +2707,12 @@ public static class Strings
public static string Settings_Privacy_Header => ResourceManager.GetString(nameof(Settings_Privacy_Header), Culture) ?? nameof(Settings_Privacy_Header);
public static string Settings_RemoveUninstalled_Applied => ResourceManager.GetString(nameof(Settings_RemoveUninstalled_Applied), Culture) ?? nameof(Settings_RemoveUninstalled_Applied);
public static string Settings_RemoveUninstalled_Body => ResourceManager.GetString(nameof(Settings_RemoveUninstalled_Body), Culture) ?? nameof(Settings_RemoveUninstalled_Body);
public static string Settings_RemoveUninstalled_Label => ResourceManager.GetString(nameof(Settings_RemoveUninstalled_Label), Culture) ?? nameof(Settings_RemoveUninstalled_Label);
public static string Settings_Retention_Body => ResourceManager.GetString(nameof(Settings_Retention_Body), Culture) ?? nameof(Settings_Retention_Body);
public static string Settings_Retention_Label => ResourceManager.GetString(nameof(Settings_Retention_Label), Culture) ?? nameof(Settings_Retention_Label);
+79 -3
View File
@@ -33,6 +33,10 @@
<value>キャプチャエージェントがオフライン</value>
<comment>review</comment>
</data>
<data name="Agent_NotConnected_NothingChanged" xml:space="preserve">
<value>キャプチャエージェントに接続されていません。何も変更されていません。</value>
<comment>review</comment>
</data>
<data name="Agent_Banner_Retry" xml:space="preserve">
<value>再試行</value>
<comment>review</comment>
@@ -1833,8 +1837,8 @@
<value>アプリ</value>
<comment>review</comment>
</data>
<data name="Notice_Degraded_Body_Format" xml:space="preserve">
<value>フックが停止しました ({0})。セッションは実測なしで続行します。</value>
<data name="Notice_Degraded_Unknown_Format" xml:space="preserve">
<value>計測を停止しました ({0})。</value>
<comment>review</comment>
</data>
<data name="Notice_Degraded_Title" xml:space="preserve">
@@ -1921,6 +1925,10 @@
<value>適用しました。キャプチャエージェントは次回のセッション開始時に読み込みます。</value>
<comment>review</comment>
</data>
<data name="Settings_KillSwitch_Applied_On" xml:space="preserve">
<value>すべてのフックを無効にしました。実測中のゲームは次回の安全スキャン (30 秒以内) で実測を停止します。</value>
<comment>review</comment>
</data>
<data name="Settings_Capture_Header" xml:space="preserve">
<value>キャプチャ</value>
<comment>review</comment>
@@ -2017,6 +2025,34 @@
<value>データ</value>
<comment>review</comment>
</data>
<data name="Settings_RemoveUninstalled_Label" xml:space="preserve">
<value>アンインストールされたゲームを削除</value>
<comment>review</comment>
</data>
<data name="Settings_RemoveUninstalled_Body" xml:space="preserve">
<value>接続されているドライブから実行ファイルが 10 分間なくなっているゲームを、ライブラリから削除します。セッションが 1 つもない場合に限り、アンチチートが見つかったゲームは削除しません。オフにすると、ゲームは「未インストール」のまま残ります。</value>
<comment>review</comment>
</data>
<data name="Settings_RemoveUninstalled_Applied" xml:space="preserve">
<value>適用しました。キャプチャエージェントは 15 秒以内に読み込みます。</value>
<comment>review</comment>
</data>
<data name="Games_Removed_Title" xml:space="preserve">
<value>ライブラリから削除しました</value>
<comment>review</comment>
</data>
<data name="Games_Removed_Format" xml:space="preserve">
<value>{0} はインストールされておらずセッションもないため、キャプチャエージェントが削除しました。「設定 ▸ データ」でオフにできます。</value>
<comment>review</comment>
</data>
<data name="Games_Removed_Many_Format" xml:space="preserve">
<value>{0} 本のゲームはインストールされておらずセッションもないため、キャプチャエージェントが削除しました: {1}。「設定 ▸ データ」でオフにできます。</value>
<comment>review</comment>
</data>
<data name="Games_Removed_More_Format" xml:space="preserve">
<value>{0} ほか {1} 本</value>
<comment>review</comment>
</data>
<data name="Settings_DeleteSessions_Label" xml:space="preserve">
<value>すべてのセッションを削除</value>
<comment>review</comment>
@@ -2262,7 +2298,7 @@
<comment>review</comment>
</data>
<data name="FirstRun_Import_Body" xml:space="preserve">
<value>FrameLedger は Steam、GOG Galaxy、Epic、itch.io のインストール済みゲームを読み取り、チェックリストから追加できます — 入った後、ゲームページの「ファイル ▸ ライブラリを取り込む…」から。取り込んだゲームはどれも、手動で追加したものと同じくフック無効で始まります。</value>
<value>FrameLedger は Steam、GOG Galaxy、Epic、itch.io のインストール済みゲームを読み取り、チェックリストから追加できます — 入った後、「ファイル ▸ ライブラリをインポート…」から。取り込んだゲームはどれも、手動で追加したものと同じくフック無効で始まります。</value>
<comment>review</comment>
</data>
<data name="FirstRun_Import_Header" xml:space="preserve">
@@ -2913,6 +2949,46 @@
<value>ゲームの実行ファイル内に見つかりません。実行ファイルが圧縮・保護されているか、スタジオがエンジンのビルド名を変更している可能性があります。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_UnityPlayer" xml:space="preserve">
<value>ゲームの Unity プレーヤーライブラリ(UnityPlayer.dll)のバージョンから。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_UnityData" xml:space="preserve">
<value>ゲームの Unity データファイル(globalgamemanagers)の先頭から。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_UnityPlayerFile" xml:space="preserve">
<value>Unity プレーヤーライブラリのバージョン番号のみから。リリースを示す文字(f1 など)はそこに記録されていません。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_GodotPack" xml:space="preserve">
<value>ゲームの Godot データパック(.pck)の先頭から。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_GodotPackEmbedded" xml:space="preserve">
<value>ゲームの実行ファイルに含まれる Godot データパックの先頭から。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_GodotExe" xml:space="preserve">
<value>Godot がゲームの実行ファイルに残したバージョン情報から。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_CoreScript_Format" xml:space="preserve">
<value>ゲームの {0} の最初の行から。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_Rgss" xml:space="preserve">
<value>ゲームの Game.ini が指定する RPG Maker のランタイムライブラリ(RGSS)から。この番号はエディターではなくライブラリのものです。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_RenPyVcVersion" xml:space="preserve">
<value>ゲームの Ren'Py エンジンのバージョンファイル(renpy/vc_version.py)から。</value>
<comment>review</comment>
</data>
<data name="GameDetail_EngineVersion_NotFoundInFiles" xml:space="preserve">
<value>ゲームのファイルには見つかりません。</value>
<comment>review</comment>
</data>
<data name="GameDetail_Details_Libraries" xml:space="preserve">
<value>同梱ライブラリ</value>
<comment>review</comment>
+60 -3
View File
@@ -30,6 +30,9 @@
<data name="Agent_Banner_Offline_Title" xml:space="preserve">
<value>Capture agent offline</value>
</data>
<data name="Agent_NotConnected_NothingChanged" xml:space="preserve">
<value>The capture agent is not connected. Nothing was changed.</value>
</data>
<data name="Agent_Banner_Retry" xml:space="preserve">
<value>Retry</value>
</data>
@@ -1380,8 +1383,8 @@
<data name="Logs_Source_Ui" xml:space="preserve">
<value>App</value>
</data>
<data name="Notice_Degraded_Body_Format" xml:space="preserve">
<value>The hook stopped ({0}); the session continues without measuring.</value>
<data name="Notice_Degraded_Unknown_Format" xml:space="preserve">
<value>Measuring stopped ({0}).</value>
</data>
<data name="Notice_Degraded_Title" xml:space="preserve">
<value>Measurement stopped</value>
@@ -1446,6 +1449,9 @@
<data name="Settings_Applied" xml:space="preserve">
<value>Applied. The capture agent reads it at the next session start.</value>
</data>
<data name="Settings_KillSwitch_Applied_On" xml:space="preserve">
<value>All hooking is off. A game being measured stops being measured at its next safety scan, within 30 seconds.</value>
</data>
<data name="Settings_Capture_Header" xml:space="preserve">
<value>Capture</value>
</data>
@@ -1518,6 +1524,27 @@
<data name="Settings_Data_Header" xml:space="preserve">
<value>Data</value>
</data>
<data name="Settings_RemoveUninstalled_Label" xml:space="preserve">
<value>Remove uninstalled games</value>
</data>
<data name="Settings_RemoveUninstalled_Body" xml:space="preserve">
<value>A game whose executable has been gone for ten minutes, from a drive that is connected, is removed from the library — only when it has no sessions, and never one where anti-cheat was found. Off, it stays and reads Not installed.</value>
</data>
<data name="Settings_RemoveUninstalled_Applied" xml:space="preserve">
<value>Applied. The capture agent reads it within 15 seconds.</value>
</data>
<data name="Games_Removed_Title" xml:space="preserve">
<value>Removed from the library</value>
</data>
<data name="Games_Removed_Format" xml:space="preserve">
<value>{0} is no longer installed and had no sessions, so the capture agent removed it. Settings ▸ Data turns this off.</value>
</data>
<data name="Games_Removed_Many_Format" xml:space="preserve">
<value>{0} games are no longer installed and had no sessions, so the capture agent removed them: {1}. Settings ▸ Data turns this off.</value>
</data>
<data name="Games_Removed_More_Format" xml:space="preserve">
<value>{0} and {1} more</value>
</data>
<data name="Settings_DeleteSessions_Label" xml:space="preserve">
<value>Delete all sessions</value>
</data>
@@ -1702,7 +1729,7 @@
<value>Finish</value>
</data>
<data name="FirstRun_Import_Body" xml:space="preserve">
<value>FrameLedger can read what Steam, GOG Galaxy, Epic and itch.io have installed and add them from a checklist — File ▸ Import library… on the Games page, once you are in. Every imported game starts with hooking off, exactly like one you add by hand.</value>
<value>FrameLedger can read what Steam, GOG Galaxy, Epic and itch.io have installed and add them from a checklist — File ▸ Import library…, once you are in. Every imported game starts with hooking off, exactly like one you add by hand.</value>
</data>
<data name="FirstRun_Import_Header" xml:space="preserve">
<value>Your library</value>
@@ -2195,6 +2222,36 @@ The documents below are the full terms; this summary does not replace them.</val
<data name="GameDetail_EngineVersion_NotFound" xml:space="preserve">
<value>Not found in the game's executable. It may be packed or protected, or the studio renamed the engine's build.</value>
</data>
<data name="GameDetail_EngineVersion_UnityPlayer" xml:space="preserve">
<value>From the version of the game's Unity player library (UnityPlayer.dll).</value>
</data>
<data name="GameDetail_EngineVersion_UnityData" xml:space="preserve">
<value>From the header of the game's Unity data file (globalgamemanagers).</value>
</data>
<data name="GameDetail_EngineVersion_UnityPlayerFile" xml:space="preserve">
<value>From the Unity player library's version number only. The release letter (such as f1) is not recorded there.</value>
</data>
<data name="GameDetail_EngineVersion_GodotPack" xml:space="preserve">
<value>From the header of the game's Godot data pack (.pck).</value>
</data>
<data name="GameDetail_EngineVersion_GodotPackEmbedded" xml:space="preserve">
<value>From the header of the Godot data pack inside the game's executable.</value>
</data>
<data name="GameDetail_EngineVersion_GodotExe" xml:space="preserve">
<value>From the version information Godot left in the game's executable.</value>
</data>
<data name="GameDetail_EngineVersion_CoreScript_Format" xml:space="preserve">
<value>From the first lines of the game's {0}.</value>
</data>
<data name="GameDetail_EngineVersion_Rgss" xml:space="preserve">
<value>From the RPG Maker runtime library (RGSS) that the game's Game.ini names. The number is the library's, not the editor's.</value>
</data>
<data name="GameDetail_EngineVersion_RenPyVcVersion" xml:space="preserve">
<value>From the version file of the game's Ren'Py engine (renpy/vc_version.py).</value>
</data>
<data name="GameDetail_EngineVersion_NotFoundInFiles" xml:space="preserve">
<value>Not found in the game's files.</value>
</data>
<data name="GameDetail_Details_Libraries" xml:space="preserve">
<value>Ships with</value>
</data>
+60 -3
View File
@@ -25,6 +25,9 @@
<data name="Agent_Banner_Offline_Title" xml:space="preserve">
<value>Capture agent ngoại tuyến</value>
</data>
<data name="Agent_NotConnected_NothingChanged" xml:space="preserve">
<value>Capture agent chưa kết nối. Không có gì thay đổi.</value>
</data>
<data name="Agent_Banner_Retry" xml:space="preserve">
<value>Thử lại</value>
</data>
@@ -1375,8 +1378,8 @@
<data name="Logs_Source_Ui" xml:space="preserve">
<value>Ứng dụng</value>
</data>
<data name="Notice_Degraded_Body_Format" xml:space="preserve">
<value>Hook đã dừng ({0}); phiên tiếp tục mà không đo.</value>
<data name="Notice_Degraded_Unknown_Format" xml:space="preserve">
<value>Việc đo đã dừng ({0}).</value>
</data>
<data name="Notice_Degraded_Title" xml:space="preserve">
<value>Đã dừng đo</value>
@@ -1441,6 +1444,9 @@
<data name="Settings_Applied" xml:space="preserve">
<value>Đã áp dụng. Capture agent đọc ở lần bắt đầu phiên kế tiếp.</value>
</data>
<data name="Settings_KillSwitch_Applied_On" xml:space="preserve">
<value>Đã tắt toàn bộ hooking. Game đang được đo sẽ dừng đo ở lần quét an toàn kế tiếp, trong vòng 30 giây.</value>
</data>
<data name="Settings_Capture_Header" xml:space="preserve">
<value>Thu thập</value>
</data>
@@ -1513,6 +1519,27 @@
<data name="Settings_Data_Header" xml:space="preserve">
<value>Dữ liệu</value>
</data>
<data name="Settings_RemoveUninstalled_Label" xml:space="preserve">
<value>Xoá game đã gỡ cài đặt</value>
</data>
<data name="Settings_RemoveUninstalled_Body" xml:space="preserve">
<value>Game có file thực thi đã biến mất mười phút, trên ổ đĩa vẫn đang cắm, sẽ được xoá khỏi thư viện — chỉ khi game chưa có phiên nào, và không bao giờ xoá game đã phát hiện anti-cheat. Khi tắt, game vẫn ở lại với nhãn Chưa cài.</value>
</data>
<data name="Settings_RemoveUninstalled_Applied" xml:space="preserve">
<value>Đã áp dụng. Capture agent đọc trong vòng 15 giây.</value>
</data>
<data name="Games_Removed_Title" xml:space="preserve">
<value>Đã xoá khỏi thư viện</value>
</data>
<data name="Games_Removed_Format" xml:space="preserve">
<value>{0} không còn được cài đặt và chưa có phiên nào, nên capture agent đã xoá nó. Tắt việc này trong Cài đặt ▸ Dữ liệu.</value>
</data>
<data name="Games_Removed_Many_Format" xml:space="preserve">
<value>{0} game không còn được cài đặt và chưa có phiên nào, nên capture agent đã xoá chúng: {1}. Tắt việc này trong Cài đặt ▸ Dữ liệu.</value>
</data>
<data name="Games_Removed_More_Format" xml:space="preserve">
<value>{0} và {1} game khác</value>
</data>
<data name="Settings_DeleteSessions_Label" xml:space="preserve">
<value>Xoá mọi phiên</value>
</data>
@@ -1697,7 +1724,7 @@
<value>Hoàn tất</value>
</data>
<data name="FirstRun_Import_Body" xml:space="preserve">
<value>FrameLedger có thể đọc những gì Steam, GOG Galaxy, Epic và itch.io đã cài và thêm chúng từ một danh sách chọn — File ▸ Nhập thư viện… ở trang Game, khi bạn đã vào trong. Mọi game nhập vào đều bắt đầu với hooking tắt, đúng như game bạn thêm thủ công.</value>
<value>FrameLedger có thể đọc những gì Steam, GOG Galaxy, Epic và itch.io đã cài và thêm chúng từ một danh sách chọn — Tệp ▸ Nhập thư viện…, khi bạn đã vào trong. Mọi game nhập vào đều bắt đầu với hooking tắt, đúng như game bạn thêm thủ công.</value>
</data>
<data name="FirstRun_Import_Header" xml:space="preserve">
<value>Thư viện của bạn</value>
@@ -2190,6 +2217,36 @@ Các văn bản bên dưới là điều khoản đầy đủ; bản tóm tắt
<data name="GameDetail_EngineVersion_NotFound" xml:space="preserve">
<value>Không tìm thấy trong file thực thi của game. File có thể đã bị nén hoặc bảo vệ, hoặc studio đã đổi tên bản dựng của engine.</value>
</data>
<data name="GameDetail_EngineVersion_UnityPlayer" xml:space="preserve">
<value>Lấy từ phiên bản thư viện Unity player của game (UnityPlayer.dll).</value>
</data>
<data name="GameDetail_EngineVersion_UnityData" xml:space="preserve">
<value>Lấy từ phần đầu file dữ liệu Unity của game (globalgamemanagers).</value>
</data>
<data name="GameDetail_EngineVersion_UnityPlayerFile" xml:space="preserve">
<value>Chỉ lấy từ số phiên bản của thư viện Unity player. Chữ cái của bản phát hành (như f1) không được ghi ở đó.</value>
</data>
<data name="GameDetail_EngineVersion_GodotPack" xml:space="preserve">
<value>Lấy từ phần đầu gói dữ liệu Godot của game (.pck).</value>
</data>
<data name="GameDetail_EngineVersion_GodotPackEmbedded" xml:space="preserve">
<value>Lấy từ phần đầu gói dữ liệu Godot nằm trong file thực thi của game.</value>
</data>
<data name="GameDetail_EngineVersion_GodotExe" xml:space="preserve">
<value>Lấy từ thông tin phiên bản mà Godot để lại trong file thực thi của game.</value>
</data>
<data name="GameDetail_EngineVersion_CoreScript_Format" xml:space="preserve">
<value>Lấy từ những dòng đầu của {0} trong game.</value>
</data>
<data name="GameDetail_EngineVersion_Rgss" xml:space="preserve">
<value>Lấy từ thư viện runtime RPG Maker (RGSS) mà file Game.ini của game chỉ định. Đây là số phiên bản của thư viện, không phải của trình biên tập.</value>
</data>
<data name="GameDetail_EngineVersion_RenPyVcVersion" xml:space="preserve">
<value>Lấy từ file phiên bản của engine Ren'Py trong game (renpy/vc_version.py).</value>
</data>
<data name="GameDetail_EngineVersion_NotFoundInFiles" xml:space="preserve">
<value>Không tìm thấy trong các file của game.</value>
</data>
<data name="GameDetail_Details_Libraries" xml:space="preserve">
<value>Đi kèm</value>
</data>
@@ -26,7 +26,7 @@ public sealed class GameCardViewModel
Id = card.Row.Id;
Name = card.Row.Name;
PlatformText = Formats.Platform(card.Row.Platform);
EngineText = Formats.Engine(card.Row.Engine);
EngineText = Formats.Engine(card.Row.Engine, card.Row.EngineVersionSource);
Recorded = card.Row.RecordSessions;
HookOn = Recorded && card.Row.HookEnabled;
// An entry the guard found anti-cheat in says so (beta.8): its hooking is off for good, and "Hooking off" read as
@@ -521,6 +521,13 @@ public sealed partial class GameDetailViewModel : ObservableObject
{
Pending = LoadAsync();
}
else if (string.Equals(e.Envelope.Type, IpcMessageType.GameRemoved, StringComparison.Ordinal)
&& IpcCodec.Payload<GameRemovedEvent>(e.Envelope) is { } removed && removed.GameId == _gameId)
{
// D55 (beta.19): this very entry was removed by the Agent — the page reloads into its not-found state and says why.
_strip.Info(Strings.Games_Removed_Title, string.Format(CultureInfo.CurrentCulture, Strings.Games_Removed_Format, removed.GameName ?? removed.ExePath));
Pending = LoadAsync();
}
});
private async Task LoadSelectedAsync(SessionItemViewModel? session)
@@ -755,7 +762,7 @@ public sealed partial class GameDetailViewModel : ObservableObject
try
{
HookingConsentResult result = await _consent.DisableAsync(Game.Id).ConfigureAwait(true);
Notice(result);
Notice(result, turningOff: true);
}
finally
{
@@ -801,7 +808,8 @@ public sealed partial class GameDetailViewModel : ObservableObject
/// <summary>
/// A store import guesses the executable (Steam names none), and everything downstream is keyed on it: a wrong guess
/// is a game that can never be matched. The pick is the user's own; the row comes back hooking-off and unconsented,
/// exactly as a new game would, and consent is revoked over the pipe first, as removal does.
/// exactly as a new game would, and consent is revoked over the pipe first, as removal does. The dialog opens in the
/// game's own folder (beta.19, <see cref="GameFolder"/>), asked off the UI thread.
/// </summary>
private async Task ChangeExecutableCoreAsync()
{
@@ -810,7 +818,9 @@ public sealed partial class GameDetailViewModel : ObservableObject
return;
}
string? path = _picker.PickExecutable();
string current = Game.Fingerprint.ExePath;
string? folder = await Task.Run(() => GameFolder.StartFolder(current)).ConfigureAwait(true);
string? path = _picker.PickExecutable(folder);
if (path is null || string.Equals(ExecutableIdentity.Normalise(path), Game.Fingerprint.ExePath, StringComparison.OrdinalIgnoreCase))
{
return;
@@ -940,14 +950,17 @@ public sealed partial class GameDetailViewModel : ObservableObject
OnPropertyChanged(nameof(NoticeVisible));
}
/// <summary>A refusal, a mismatch or a failure is a persistent notice on the page; a success clears it.</summary>
private void Notice(HookingConsentResult result)
/// <summary>
/// A refusal, a mismatch or a failure is a persistent notice on the page; a success clears it. With no Agent, turning
/// hooking off changed nothing — not "Nothing was enabled.", the enable path's words, which it said until beta.18.
/// </summary>
private void Notice(HookingConsentResult result, bool turningOff = false)
{
(NoticeText, NoticeSeverity) = result.Outcome switch
{
HookingConsentOutcome.Refused => (result.RefusalText(), InfoBarSeverity.Error),
HookingConsentOutcome.VersionMismatch => (Shared.Strings.Safety_Consent_VersionMismatch, InfoBarSeverity.Warning),
HookingConsentOutcome.AgentUnavailable => (Shared.Strings.Safety_Consent_AgentUnavailable, InfoBarSeverity.Warning),
HookingConsentOutcome.AgentUnavailable => (turningOff ? Strings.Agent_NotConnected_NothingChanged : Shared.Strings.Safety_Consent_AgentUnavailable, InfoBarSeverity.Warning),
// The Agent could not read the executable (beta.8): say whether its drive or the file is missing, not the IPC code.
HookingConsentOutcome.Failed when string.Equals(result.Detail, Shared.Ipc.IpcErrorCode.ExecutableUnreadable, StringComparison.Ordinal) && Game is not null
=> (Formats.ExecutableMissingText(Game.Fingerprint.ExePath), InfoBarSeverity.Warning),
@@ -1163,13 +1176,12 @@ public sealed partial class GameDetailViewModel : ObservableObject
SessionsEmpty = Sessions.Count == 0;
}
private static string EngineText(GameRow row) =>
row.Engine is null || row.EngineVersion is null ? Formats.Engine(row.Engine) : Formats.Engine(row.Engine) + " " + row.EngineVersion;
private static string EngineText(GameRow row) => Formats.EngineWithVersion(row.Engine, row.EngineVersion, row.EngineVersionSource);
/// <summary>
/// Which witness an Unreal Engine version rests on (beta.10, schema 0015) — said, because the executable's version
/// number and the engine's build name can each be wrong in their own way (<c>05_DETECTION</c> §Engine version). An
/// Unreal title whose executable names no version says so once the sweep has read it; other engines add no line.
/// Which witness an engine version rests on (beta.10 for Unreal, schema 0015; beta.19 for Unity, Godot and RPG Maker) —
/// said, because each witness can be wrong or short in its own way (<c>05_DETECTION</c> §Engine version). A title of
/// these engines whose files name no version says so once the sweep has read it; other engines add no line.
/// </summary>
internal static string? EngineVersionSourceText(GameRow row)
{
@@ -1179,8 +1191,20 @@ public sealed partial class GameDetailViewModel : ObservableObject
EngineVersionSource.UnrealBranchAndFile => Strings.GameDetail_EngineVersion_BranchAndFile,
EngineVersionSource.UnrealBranch => Strings.GameDetail_EngineVersion_Branch,
EngineVersionSource.UnrealFileVersion => Strings.GameDetail_EngineVersion_FileVersion,
EngineVersionSource.UnityPlayer => Strings.GameDetail_EngineVersion_UnityPlayer,
EngineVersionSource.UnityData => Strings.GameDetail_EngineVersion_UnityData,
EngineVersionSource.UnityPlayerFile => Strings.GameDetail_EngineVersion_UnityPlayerFile,
EngineVersionSource.GodotPack => Strings.GameDetail_EngineVersion_GodotPack,
EngineVersionSource.GodotPackEmbedded => Strings.GameDetail_EngineVersion_GodotPackEmbedded,
EngineVersionSource.GodotExe => Strings.GameDetail_EngineVersion_GodotExe,
EngineVersionSource.RpgMakerMzCore => string.Format(CultureInfo.CurrentCulture, Strings.GameDetail_EngineVersion_CoreScript_Format, "js/rmmz_core.js"),
EngineVersionSource.RpgMakerMvCore => string.Format(CultureInfo.CurrentCulture, Strings.GameDetail_EngineVersion_CoreScript_Format, "rpg_core.js"),
EngineVersionSource.Rgss1Library or EngineVersionSource.Rgss2Library or EngineVersionSource.Rgss3Library => Strings.GameDetail_EngineVersion_Rgss,
EngineVersionSource.RenPyVcVersion => Strings.GameDetail_EngineVersion_RenPyVcVersion,
null when string.Equals(row.Engine, "unreal", StringComparison.Ordinal) && row.EngineVersion is null && row.ExeMachine is not null
=> Strings.GameDetail_EngineVersion_NotFound,
null when row.Engine is "unity" or "godot" or "rpgmaker_mv" or "rpgmaker_rgss" or "renpy" && row.EngineVersion is null && row.ExeMachine is not null
=> Strings.GameDetail_EngineVersion_NotFoundInFiles,
_ => null,
};
}
@@ -25,6 +25,9 @@ public sealed partial class GamesViewModel : ObservableObject
private const string _listValue = "list";
private const string _gridValue = "grid";
/// <summary>How many removed games one notice names; the rest are counted (<c>Games_Removed_More_Format</c>).</summary>
private const int _removedNamed = 5;
private readonly GameLibrary _library;
private readonly GameSelection _selection;
private readonly IPageNavigator _navigator;
@@ -33,8 +36,13 @@ public sealed partial class GamesViewModel : ObservableObject
private readonly RegisteredSettings? _settings;
private readonly IAgentLink? _agent;
private readonly LibraryChanges? _changes;
private readonly IMessageStrip? _strip;
private readonly TimeProvider _clock;
private readonly Func<string, bool> _exists;
private readonly UiThread _ui = new();
private readonly List<string> _removed = [];
private IReadOnlyList<GameCardViewModel> _all = [];
private int _reads;
private bool _viewRead;
private bool _attached;
@@ -58,8 +66,12 @@ public sealed partial class GamesViewModel : ObservableObject
private bool _listView;
public GamesViewModel(GameLibrary library, GameSelection selection, IPageNavigator navigator, AddGameFlow addGame, ImportLibraryFlow? import = null,
RegisteredSettings? settings = null, IAgentLink? agent = null, LibraryChanges? changes = null)
RegisteredSettings? settings = null, IAgentLink? agent = null, LibraryChanges? changes = null, IMessageStrip? strip = null, TimeProvider? clock = null,
Func<string, bool>? executableExists = null)
{
_strip = strip;
_clock = clock ?? TimeProvider.System;
_exists = executableExists ?? GameLibrary.ExecutableExists;
_library = library ?? throw new ArgumentNullException(nameof(library));
_selection = selection ?? throw new ArgumentNullException(nameof(selection));
_navigator = navigator ?? throw new ArgumentNullException(nameof(navigator));
@@ -89,6 +101,12 @@ public sealed partial class GamesViewModel : ObservableObject
public static string ListText => Strings.Games_View_List;
/// <summary>
/// How long the page waits after the Agent says it removed a game (D55) for the rest of the same check before it reloads
/// and says what went (beta.19). One check removes its games a few milliseconds apart, each in its own event.
/// </summary>
public static TimeSpan RemovalSettle { get; } = TimeSpan.FromSeconds(1);
/// <summary>The sort orders, labelled in the language this page opened in (beta.15: a static list kept the first language).</summary>
public IReadOnlyList<Choice<GamesSort>> Sorts { get; } =
[
@@ -102,14 +120,26 @@ public sealed partial class GamesViewModel : ObservableObject
/// <summary>The load in flight, for a test to await.</summary>
public Task Pending { get; private set; }
/// <summary>
/// The library read and listed. Reads overlap — a session that ends, an import, a removal — and the one that started first
/// can finish last, its checks waiting on a drive that is slow to answer: only the newest read is shown (beta.19 — an
/// older one put back the card of a game the Agent had just removed, until the next read).
/// </summary>
public async Task LoadAsync(CancellationToken ct = default)
{
int read = Interlocked.Increment(ref _reads);
await ReadViewAsync(ct).ConfigureAwait(true);
IReadOnlyList<GameCard> cards = await _library.ListCardsAsync(ct).ConfigureAwait(true);
// Whether each executable is on disk is a file-system question per entry — a drive that is gone can take a moment
// to say so — so it is asked off the UI thread, the game page's own way (GameLibrary.ExecutableExists).
bool[] installed = await Task.Run(() => cards.Select(static c => GameLibrary.ExecutableExists(c.Row.Fingerprint.ExePath)).ToArray(), ct)
Func<string, bool> exists = _exists;
bool[] installed = await Task.Run(() => cards.Select(c => exists(c.Row.Fingerprint.ExePath)).ToArray(), ct)
.ConfigureAwait(true);
if (read != Volatile.Read(ref _reads))
{
return;
}
_all = [.. cards.Select((c, i) => new GameCardViewModel(c, installed[i]))];
HeaderText = string.Format(CultureInfo.CurrentCulture, Strings.Games_Header_Count_Format, _all.Count);
Apply();
@@ -245,8 +275,42 @@ public sealed partial class GamesViewModel : ObservableObject
{
Pending = LoadAsync();
}
else if (string.Equals(e.Envelope.Type, IpcMessageType.GameRemoved, StringComparison.Ordinal)
&& IpcCodec.Payload<GameRemovedEvent>(e.Envelope) is { } removed)
{
// D55 (beta.19): the Agent removed an entry whose game is no longer installed; the card goes, and the page says why.
// A check that removes five says it in five events: the first waits for the rest, then one reload and one notice.
_removed.Add(removed.GameName ?? removed.ExePath);
if (_removed.Count == 1)
{
Pending = SayRemovedAsync();
}
}
});
/// <summary>
/// The games the Agent removed since the first of them, after <see cref="RemovalSettle"/>: the library read once, then one
/// notice — the game's name, or how many went and which. A removal heard during the read starts the next notice.
/// </summary>
private async Task SayRemovedAsync()
{
await Task.Delay(RemovalSettle, _clock).ConfigureAwait(true);
string[] names = [.. _removed];
_removed.Clear();
await LoadAsync().ConfigureAwait(true);
if (_strip is null)
{
return;
}
string listed = names.Length <= _removedNamed
? string.Join(", ", names)
: string.Format(CultureInfo.CurrentCulture, Strings.Games_Removed_More_Format, string.Join(", ", names.Take(_removedNamed)), names.Length - _removedNamed);
_strip.Info(Strings.Games_Removed_Title, names.Length == 1
? string.Format(CultureInfo.CurrentCulture, Strings.Games_Removed_Format, names[0])
: string.Format(CultureInfo.CurrentCulture, Strings.Games_Removed_Many_Format, names.Length, listed));
}
private void OnLibraryChanged(object? sender, EventArgs e) => _ui.Post(() => Pending = LoadAsync());
private void Apply()
@@ -71,6 +71,13 @@ public sealed partial class SettingsViewModel : ObservableObject
[NotifyPropertyChangedFor(nameof(KillSwitchState))]
private bool _killSwitch;
/// <summary>
/// D55 (beta.19): the Agent removes an entry whose game is no longer installed and that has no session
/// (<c>retention.remove_uninstalled_games</c>, on by default).
/// </summary>
[ObservableProperty]
private bool _removeUninstalledGames;
[ObservableProperty]
private int _minSessionSeconds;
@@ -384,6 +391,8 @@ public sealed partial class SettingsViewModel : ObservableObject
partial void OnRetentionRawSessionsChanged(int oldValue, int newValue) => PersistNumber(SettingsRegistry.RetentionRawSessionsPerGame, Strings.Settings_Retention_Label, oldValue, newValue, v => RetentionRawSessions = v);
partial void OnRemoveUninstalledGamesChanged(bool value) => Persist(SettingsRegistry.RetentionRemoveUninstalledGames, value);
partial void OnHideAntiCheatHookingChanged(bool value) => Persist(SettingsRegistry.UiHideAntiCheatHooking, value);
/// <summary>D33: the option is one settings row the Agent reads at every session start and command; the list follows it.</summary>
@@ -532,6 +541,7 @@ public sealed partial class SettingsViewModel : ObservableObject
MinSessionSeconds = await _settings.GetIntegerAsync(SettingsRegistry.CaptureMinSessionSeconds).ConfigureAwait(true);
TelemetryIntervalMs = await _settings.GetIntegerAsync(SettingsRegistry.TelemetryIntervalMs).ConfigureAwait(true);
RetentionRawSessions = await _settings.GetIntegerAsync(SettingsRegistry.RetentionRawSessionsPerGame).ConfigureAwait(true);
RemoveUninstalledGames = await _settings.GetBooleanAsync(SettingsRegistry.RetentionRemoveUninstalledGames).ConfigureAwait(true);
MinimizeToTray = await _settings.GetBooleanAsync(SettingsRegistry.UiMinimizeToTray).ConfigureAwait(true);
HideAntiCheatHooking = await _settings.GetBooleanAsync(SettingsRegistry.UiHideAntiCheatHooking).ConfigureAwait(true);
UserModeExceptions = await _settings.GetBooleanAsync(SettingsRegistry.HookingUserModeExceptions).ConfigureAwait(true);
@@ -712,7 +722,8 @@ public sealed partial class SettingsViewModel : ObservableObject
return;
}
string body = result.Outcome == HookingConsentOutcome.AgentUnavailable ? Shared.Strings.Safety_Consent_AgentUnavailable : result.Detail ?? Strings.Common_NotAvailable;
// Turning off with no Agent changed nothing (beta.18): it said the enable path's "Nothing was enabled."
string body = result.Outcome == HookingConsentOutcome.AgentUnavailable ? Strings.Agent_NotConnected_NothingChanged : result.Detail ?? Strings.Common_NotAvailable;
_strip.Warn(game.Name, body);
}
@@ -765,7 +776,13 @@ public sealed partial class SettingsViewModel : ObservableObject
await _settings.SetAsync(definition, value).ConfigureAwait(true);
if (definition.AgentReads)
{
_strip.Info(Strings.Settings_Header, Strings.Settings_Applied);
// Disable all hooking does not wait for a session to start (beta.18): a measured one stops at its next safety scan.
// Nor does the removal of uninstalled games (beta.19, D55): the Agent reads it at every sweep.
bool killSwitchOn = ReferenceEquals(definition, SettingsRegistry.HookingKillSwitch) && string.Equals(value, "1", StringComparison.Ordinal);
string applied = killSwitchOn ? Strings.Settings_KillSwitch_Applied_On
: ReferenceEquals(definition, SettingsRegistry.RetentionRemoveUninstalledGames) ? Strings.Settings_RemoveUninstalled_Applied
: Strings.Settings_Applied;
_strip.Info(Strings.Settings_Header, applied);
}
}
@@ -40,6 +40,7 @@ public sealed class DetectionSweep : IDisposable
private readonly IExecutableIdentitySource _identity;
private readonly Action<string> _log;
private readonly ExecutableRelocator? _relocator;
private readonly UninstalledEntryPrune? _prune;
private readonly SemaphoreSlim _wake = new(0, 1);
// The path each unreadable entry was last reported at (2026-09-23): said once until it changes or reads again. The
@@ -53,8 +54,9 @@ public sealed class DetectionSweep : IDisposable
/// <param name="identity">Reads each row's executable (its fingerprint), or null when it cannot.</param>
/// <param name="log">The Agent's log line.</param>
/// <param name="relocator">Follows an executable to a drive that changed its letter (2026-09-22); null sweeps without looking.</param>
/// <param name="prune">Removes an entry whose game is no longer installed and had no session (beta.19, D55); null removes nothing.</param>
public DetectionSweep(IGameRepository games, IDetectionRulesSource rules, IGameFileProbe probe, IExecutableIdentitySource identity, Action<string> log,
ExecutableRelocator? relocator = null)
ExecutableRelocator? relocator = null, UninstalledEntryPrune? prune = null)
{
_games = games ?? throw new ArgumentNullException(nameof(games));
_rules = rules ?? throw new ArgumentNullException(nameof(rules));
@@ -62,6 +64,7 @@ public sealed class DetectionSweep : IDisposable
_identity = identity ?? throw new ArgumentNullException(nameof(identity));
_log = log ?? throw new ArgumentNullException(nameof(log));
_relocator = relocator;
_prune = prune;
_detector = new StaticGameDetector(rules, probe);
}
@@ -101,6 +104,7 @@ public sealed class DetectionSweep : IDisposable
int current = 0;
int unreadable = 0;
int relocated = 0;
int removed = 0;
foreach (GameRow listed in await _games.ListAsync(ct).ConfigureAwait(false))
{
ct.ThrowIfCancellationRequested();
@@ -119,17 +123,14 @@ public sealed class DetectionSweep : IDisposable
if (read is not { } onDisk)
{
unreadable++;
if (!_unreadableSaid.TryGetValue(game.Id, out string? said) || !string.Equals(said, game.Fingerprint.ExePath, StringComparison.OrdinalIgnoreCase))
{
_unreadableSaid[game.Id] = game.Fingerprint.ExePath;
_log($"detect: {game.Name} — executable unreadable, skipped ({game.Fingerprint.ExePath}); said once until that changes");
}
bool uninstalled = await UnreadableAsync(game, ct).ConfigureAwait(false);
removed += uninstalled ? 1 : 0;
unreadable += uninstalled ? 0 : 1;
continue;
}
_unreadableSaid.Remove(game.Id);
_prune?.Present(game.Id);
if (!IsStale(game, onDisk, rules.RulesVersion))
{
@@ -143,7 +144,28 @@ public sealed class DetectionSweep : IDisposable
}
}
return new DetectionSweepReport { Scanned = scanned, Current = current, Unreadable = unreadable, Relocated = relocated };
return new DetectionSweepReport { Scanned = scanned, Current = current, Unreadable = unreadable, Relocated = relocated, Removed = removed };
}
/// <summary>
/// An entry whose executable did not read, after the relocator looked for it on every other drive: removed when its game
/// is no longer installed and it had no session (beta.19, D55), else skipped and named once. True when it was removed.
/// </summary>
private async ValueTask<bool> UnreadableAsync(GameRow game, CancellationToken ct)
{
if (_prune is not null && await _prune.ConsiderAsync(game, ct).ConfigureAwait(false))
{
_unreadableSaid.Remove(game.Id);
return true;
}
if (!_unreadableSaid.TryGetValue(game.Id, out string? said) || !string.Equals(said, game.Fingerprint.ExePath, StringComparison.OrdinalIgnoreCase))
{
_unreadableSaid[game.Id] = game.Fingerprint.ExePath;
_log($"detect: {game.Name} — executable unreadable, skipped ({game.Fingerprint.ExePath}); said once until that changes");
}
return false;
}
/// <summary>
@@ -18,6 +18,9 @@ public sealed record DetectionSweepReport
/// <summary>Rows whose executable was found under another drive letter and moved there this pass (2026-09-22).</summary>
public int Relocated { get; init; }
/// <summary>Entries removed this pass because their game is no longer installed and had no session (beta.19, D55).</summary>
public int Removed { get; init; }
/// <summary>The rules file could not be loaded; nothing was scanned.</summary>
public bool RulesUnusable { get; init; }
}
@@ -24,4 +24,29 @@ public interface IGameFileProbe
/// file. Null when no shipping executable is in the snapshot's listing or it could not be read: no facts, never a guess.
/// </summary>
ValueTask<UnrealBuildFacts?> ReadUnrealBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default);
/// <summary>
/// Unity's build facts (beta.19) — the player library's version resource and the header of its data file — asked only
/// after the rules matched an engine whose extractor is <see cref="VersionExtractorType.UnityBuild"/>. Null when neither
/// file is there or could be read.
/// </summary>
ValueTask<UnityBuildFacts?> ReadUnityBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default);
/// <summary>
/// Godot's build facts (beta.19) — a data pack's header, beside the executable or appended to it, and the executable's
/// version resource — for <see cref="VersionExtractorType.GodotBuild"/>. Null when nothing could be read.
/// </summary>
ValueTask<GodotBuildFacts?> ReadGodotBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default);
/// <summary>
/// RPG Maker's build facts (beta.19) — MV/MZ's core-script header, or the RGSS library <c>Game.ini</c> names — for
/// <see cref="VersionExtractorType.RpgMakerBuild"/>. Null when neither is found.
/// </summary>
ValueTask<RpgMakerBuildFacts?> ReadRpgMakerBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default);
/// <summary>
/// Ren'Py's build facts (beta.20) — the <c>version</c> line of the engine's <c>renpy/vc_version.py</c> beside the
/// launcher — for <see cref="VersionExtractorType.RenPyBuild"/>. Null when the file names none or could not be read.
/// </summary>
ValueTask<RenPyBuildFacts?> ReadRenPyBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default);
}
@@ -59,8 +59,9 @@ public sealed class StaticGameDetector(IDetectionRulesSource rulesSource, IGameF
}
/// <summary>
/// The matched engine's version and its witness. Every extractor but one answers from the snapshot; Unreal's is the
/// second read (beta.10), made here for the one engine that matched rather than by the probe for every game.
/// The matched engine's version and its witness. The rules' own extractors answer from the snapshot; an engine whose
/// version is decided in code — Unreal since beta.10, Unity, Godot and RPG Maker since beta.19, Ren'Py since beta.20 — gets one second read,
/// made here for the one engine that matched rather than by the probe for every game.
/// </summary>
private async ValueTask<EngineVersionReading> VersionAsync(EngineMatch engine, GameFileSnapshot snapshot, CancellationToken ct)
{
@@ -69,12 +70,20 @@ public sealed class StaticGameDetector(IDetectionRulesSource rulesSource, IGameF
return EngineVersionReading.None;
}
if (extractor.Type != VersionExtractorType.UnrealBuild)
switch (extractor.Type)
{
return engine.Version is null ? EngineVersionReading.None : new EngineVersionReading(engine.Version, EngineVersionSource.Of(extractor.Type));
case VersionExtractorType.UnrealBuild:
return await _probe.ReadUnrealBuildAsync(snapshot, ct).ConfigureAwait(false) is { } unreal ? UnrealVersion.Decide(unreal) : EngineVersionReading.None;
case VersionExtractorType.UnityBuild:
return await _probe.ReadUnityBuildAsync(snapshot, ct).ConfigureAwait(false) is { } unity ? UnityVersion.Decide(unity) : EngineVersionReading.None;
case VersionExtractorType.GodotBuild:
return await _probe.ReadGodotBuildAsync(snapshot, ct).ConfigureAwait(false) is { } godot ? GodotVersion.Decide(godot) : EngineVersionReading.None;
case VersionExtractorType.RpgMakerBuild:
return await _probe.ReadRpgMakerBuildAsync(snapshot, ct).ConfigureAwait(false) is { } maker ? RpgMakerVersion.Decide(maker) : EngineVersionReading.None;
case VersionExtractorType.RenPyBuild:
return await _probe.ReadRenPyBuildAsync(snapshot, ct).ConfigureAwait(false) is { } renpy ? RenPyVersion.Decide(renpy) : EngineVersionReading.None;
default:
return engine.Version is null ? EngineVersionReading.None : new EngineVersionReading(engine.Version, EngineVersionSource.Of(extractor.Type));
}
UnrealBuildFacts? facts = await _probe.ReadUnrealBuildAsync(snapshot, ct).ConfigureAwait(false);
return facts is null ? EngineVersionReading.None : UnrealVersion.Decide(facts);
}
}
@@ -72,6 +72,12 @@ public sealed class LibraryImporter
bool missing = exe is not null && _identity.Read(exe) is null;
bool already = exe is not null && await _games.FindAsync(exe, ct).ConfigureAwait(false) is { InLibrary: true };
string? movedFrom = exe is null || already ? null : StaleTwinOf(exe, library)?.Fingerprint.ExePath;
if (exe is not null && !already && movedFrom is null && SameStoreTitleOf(game, library) is { } entry)
{
already = true;
_log($"import: {game.Name} ({game.Platform} {game.StoreId}) is already in the library as {entry.Fingerprint.ExePath} — not offered again at {exe}");
}
candidates.Add(new ImportCandidate(game, exe, already, guessed, missing, movedFrom));
}
@@ -130,4 +136,23 @@ public sealed class LibraryImporter
/// </summary>
private GameRow? StaleTwinOf(string exe, IReadOnlyList<GameRow> library) =>
library.FirstOrDefault(r => ExecutableRelocator.IsDriveLetterTwin(r.Fingerprint.ExePath, exe) && _identity.Read(r.Fingerprint.ExePath) is null);
/// <summary>
/// The library entry an earlier import made for this very store title, at another executable (beta.19): the store's id,
/// under the same platform or with the entry's executable inside the title's install folder. The import used to compare
/// paths only, so a guess that changed between builds — A Doll's Locket - Remake's helper became its NW.js runtime —
/// would have offered the same game again beside the entry the user already has; that entry is what Change executable…
/// re-points. The folder half is there because the platform is the detection sweep's to refresh: an itch build that
/// ships Steam's API reads as Steam. A title with no store id is never matched.
/// </summary>
private static GameRow? SameStoreTitleOf(StoreGame game, IReadOnlyList<GameRow> library) =>
string.IsNullOrEmpty(game.StoreId)
? null
: library.FirstOrDefault(r => string.Equals(r.StoreId, game.StoreId, StringComparison.Ordinal)
&& (string.Equals(r.Platform, game.Platform, StringComparison.OrdinalIgnoreCase)
|| IsInside(r.Fingerprint.ExePath, game.InstallDirectory)));
private static bool IsInside(string path, string directory) =>
!string.IsNullOrEmpty(directory)
&& path.StartsWith(Path.TrimEndingDirectorySeparator(directory) + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase);
}
@@ -161,8 +161,12 @@ public static class RecordedSessionEvents
private static string? NullIfEmpty(string? value) => string.IsNullOrEmpty(value) ? null : value;
/// <summary>
/// The guard's own reason when it named a family (beta.13, §S23-3): the App says a <c>BlockedService</c> or
/// <c>BlockedDriver</c> was found on the PC, not in the game. Null when the guard named nothing.
/// The guard's own reason whenever it refused: the App says a <c>BlockedService</c> or <c>BlockedDriver</c> was found on
/// the PC, not in the game (beta.13, §S23-3), and a refusal no family names in the guard's words — "the game is 32-bit…",
/// "the game's loaded modules could not be listed" — rather than by the session's end reason, which printed as
/// <c>reason RefusedByGuard</c> (beta.18). Until beta.18 it was sent only beside a family. Null for an allow, and for a
/// verdict nobody produced.
/// </summary>
private static string? GuardReasonOf(AntiCheatVerdict verdict) => string.IsNullOrEmpty(verdict.Family) ? null : verdict.Reason.ToString();
private static string? GuardReasonOf(AntiCheatVerdict verdict) =>
verdict.Reason is AntiCheatRefusalReason.Allow or AntiCheatRefusalReason.AllowedUnderUserModeException ? null : verdict.Reason.ToString();
}
@@ -0,0 +1,18 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Persistence;
/// <summary>
/// Removes a library entry whose game is no longer installed (beta.19, owner decision D55) — the second Agent write that
/// deletes a <c>games</c> row, after the twin merge (<see cref="IGameMerge"/>; <c>06_DATA_MODEL</c> §Writer ownership).
/// </summary>
public interface IGamePrune
{
/// <summary>
/// Deletes the entry when, in the same statement, it is still at <paramref name="exePath"/>, still in the library, has
/// no session stored, and carries no anti-cheat block, exception or failed-trial mark (CLAUDE.md rule 2: nothing clears
/// a block). True when it was deleted; false when any condition no longer held — nothing is written then.
/// </summary>
ValueTask<bool> RemoveUninstalledAsync(long gameId, string exePath, CancellationToken ct = default);
}
@@ -174,6 +174,20 @@ public static class SettingsRegistry
AgentReads = true,
};
/// <summary>
/// Whether the Agent removes a library entry whose game is no longer installed and that has no session (beta.19, owner
/// decision D55, amending D41's "nothing is removed"): its executable gone at sweeps ten minutes apart, on a drive that is
/// connected, from a folder whose parents are still there — never an entry carrying an anti-cheat block or exception.
/// On by default; off, such an entry stays and reads <i>Not installed</i>. The Agent reads it at every sweep (15 s).
/// </summary>
public static readonly SettingDefinition RetentionRemoveUninstalledGames = new()
{
Key = "retention.remove_uninstalled_games",
Kind = SettingKind.Boolean,
Default = "1",
AgentReads = true,
};
/// <summary>
/// <c>11_UPDATER</c>: the release feed's channel — <c>stable</c> is the releases GitHub does not mark pre-release, <c>beta</c>
/// adds the ones it does (P4 PR-5 reads it). <c>auto</c>, the default since beta.14 (owner decision D47), follows the
@@ -217,7 +231,7 @@ public static class SettingsRegistry
[
UiLanguage, UiTheme, UiStartWithWindows, UiMinimizeToTray, UiHideAntiCheatHooking, UiFpsDecimals, UiHideScrollBars, UiLibraryView,
CaptureBackground, HookingKillSwitch, HookingUserModeExceptions, CaptureRunElevated, CaptureMinSessionSeconds, TelemetryIntervalMs, RetentionRawSessionsPerGame,
UpdateChannel, UpdateAutoCheck, PrivacyOnlineMetadata, LogDebug,
RetentionRemoveUninstalledGames, UpdateChannel, UpdateAutoCheck, PrivacyOnlineMetadata, LogDebug,
];
private static readonly Dictionary<string, SettingDefinition> _byKey = All.ToDictionary(static d => d.Key, StringComparer.Ordinal);
@@ -0,0 +1,29 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Watch;
/// <summary>
/// Why an entry's executable did not read (beta.19, D55) — the distinctions <c>ExecutableIdentity.Read</c>'s null does not
/// make, and the only ones that may remove an entry: <see cref="FileGone"/> is the one answer that does.
/// </summary>
public enum ExecutablePresence
{
/// <summary>Nothing could be told (a share, a refused listing, an error) — never a reason to remove anything.</summary>
Unknown,
/// <summary>The file is there.</summary>
Present,
/// <summary>Its drive is not connected (or not ready): the relocator follows it when it is back on another letter.</summary>
DriveAbsent,
/// <summary>
/// The drive is there, and nothing of the path is but its root: a different disk under the same letter as easily as an
/// uninstall, so not one.
/// </summary>
OnlyTheDriveRemains,
/// <summary>The file is gone from a folder that is still there, or its folder is gone from one that is: uninstalled.</summary>
FileGone,
}
@@ -0,0 +1,11 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Watch;
/// <summary>Tells why an entry's executable did not read (beta.19, D55; <see cref="ExecutablePresence"/>).</summary>
public interface IExecutablePresence
{
/// <summary>What the file system says about <paramref name="exePath"/> — read only, never a process.</summary>
ExecutablePresence Probe(string exePath);
}
@@ -0,0 +1,118 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
using FrameLedger.Application.Ipc;
using FrameLedger.Application.Persistence;
using FrameLedger.Shared.Ipc;
namespace FrameLedger.Application.Watch;
/// <summary>
/// Removes a library entry whose game is no longer installed and that has no session (beta.19, owner decision D55, amending
/// D41's "nothing is removed"). Asked by <c>DetectionSweep</c> about every entry whose executable stayed unreadable after the
/// relocator looked for it on the other drives.
/// </summary>
/// <remarks>
/// <para>
/// <b>Every condition, or nothing.</b> The file is <see cref="ExecutablePresence.FileGone"/> — its drive connected, its folder
/// or the file gone from a folder that is still there, not a refused listing; it has been so at sweeps at least
/// <see cref="Grace"/> apart, at the same path (an update that replaces the executable is not an uninstall); the user's switch
/// (<c>retention.remove_uninstalled_games</c>, on by default) is on; no session of it is being recorded or waits in a
/// <c>.partial</c> to be recovered; and it carries no anti-cheat block, exception or failed-trial mark — rule 2's block is
/// never cleared, and a re-added entry would start without it. The delete itself (<see cref="IGamePrune"/>) checks the stored
/// conditions again in one statement, with "no session stored" among them, so a session finalized meanwhile wins.
/// </para>
/// <para>
/// <b>Counted in memory.</b> When the file was first seen gone is this object's, not the ledger's: an Agent restart starts
/// the ten minutes again, which only delays a removal. An entry the delete refused (it has sessions) is asked again at that
/// path only after <see cref="RetryAfter"/> — its sessions may since have been deleted (FR-1.7), and an answer that does not
/// change is not worth a statement every 15 seconds.
/// </para>
/// </remarks>
public sealed class UninstalledEntryPrune
{
/// <summary>How long a file must have been gone — across sweeps — before its entry goes: longer than a store takes to replace an executable.</summary>
public static readonly TimeSpan Grace = TimeSpan.FromMinutes(10);
/// <summary>How long an entry the delete refused waits before it is asked again.</summary>
public static readonly TimeSpan RetryAfter = TimeSpan.FromHours(1);
private readonly IGamePrune _prune;
private readonly IExecutablePresence _presence;
private readonly Func<CancellationToken, ValueTask<bool>> _enabled;
private readonly Func<long, bool> _busy;
private readonly Action<string> _log;
private readonly IIpcEventPublisher? _pipe;
private readonly TimeProvider _clock;
private readonly Dictionary<long, (string Path, DateTimeOffset Since)> _goneSince = [];
private readonly Dictionary<(long Id, string Path), DateTimeOffset> _kept = [];
/// <summary>The prune over its writer, the file system's answer, the user's switch and the recorder's state.</summary>
/// <param name="prune">The one conditional delete.</param>
/// <param name="presence">Why an executable did not read.</param>
/// <param name="enabled">The user's switch, read at every sweep.</param>
/// <param name="busy">True while a session of the entry is recorded or waits to be recovered.</param>
/// <param name="log">The Agent's log line.</param>
/// <param name="pipe">Where the App hears of a removal; null tells nobody.</param>
/// <param name="clock">The time the grace is counted in.</param>
public UninstalledEntryPrune(IGamePrune prune, IExecutablePresence presence, Func<CancellationToken, ValueTask<bool>> enabled, Func<long, bool> busy,
Action<string> log, IIpcEventPublisher? pipe = null, TimeProvider? clock = null)
{
_prune = prune ?? throw new ArgumentNullException(nameof(prune));
_presence = presence ?? throw new ArgumentNullException(nameof(presence));
_enabled = enabled ?? throw new ArgumentNullException(nameof(enabled));
_busy = busy ?? throw new ArgumentNullException(nameof(busy));
_log = log ?? throw new ArgumentNullException(nameof(log));
_pipe = pipe;
_clock = clock ?? TimeProvider.System;
}
/// <summary>The entry's executable read: whatever was counted against it is forgotten.</summary>
public void Present(long gameId) => _goneSince.Remove(gameId);
/// <summary>
/// The entry's executable did not read and was not relocated: is the game uninstalled, and may its entry go? True when the
/// entry was removed.
/// </summary>
public async ValueTask<bool> ConsiderAsync(GameRow game, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(game);
string path = game.Fingerprint.ExePath;
if (_presence.Probe(path) != ExecutablePresence.FileGone)
{
_goneSince.Remove(game.Id);
return false;
}
DateTimeOffset now = _clock.GetUtcNow();
if (!_goneSince.TryGetValue(game.Id, out (string Path, DateTimeOffset Since) seen) || !string.Equals(seen.Path, path, StringComparison.OrdinalIgnoreCase))
{
_goneSince[game.Id] = (path, now);
return false;
}
if (now - seen.Since < Grace || (_kept.TryGetValue((game.Id, path), out DateTimeOffset refused) && now - refused < RetryAfter)
|| CarriesAntiCheatState(game) || _busy(game.Id)
|| !await _enabled(ct).ConfigureAwait(false))
{
return false;
}
if (!await _prune.RemoveUninstalledAsync(game.Id, path, ct).ConfigureAwait(false))
{
_kept[(game.Id, path)] = now;
return false;
}
_goneSince.Remove(game.Id);
_log(string.Create(CultureInfo.InvariantCulture,
$"library: removed '{game.Name}' — {path} has been gone since {seen.Since:u} and the entry had no session (D55; Settings ▸ Data turns this off)"));
_pipe?.Publish(IpcMessageType.GameRemoved, new GameRemovedEvent(game.Id, game.Name, path, GameRemovedEvent.Uninstalled));
return true;
}
/// <summary>A block, an exception or a failed trial: what rule 2 and D38 keep for good, and a removal would drop.</summary>
private static bool CarriesAntiCheatState(GameRow game) =>
game.BlockedByGuard || game.AcException.GrantedAt is not null || game.AcException.TrialFailed;
}
@@ -18,6 +18,42 @@ public static class EngineVersionSource
/// <summary>Unreal: the numeric file version alone, where nothing suggests the studio replaced it.</summary>
public const string UnrealFileVersion = "unreal_file_version";
/// <summary>Unity (beta.19): the player library's <c>ProductVersion</c>, an editor version with its release letter.</summary>
public const string UnityPlayer = "unity_player";
/// <summary>Unity: the editor version the data file's header names.</summary>
public const string UnityData = "unity_data";
/// <summary>Unity: the player library's numeric file version — MAJOR.MINOR.PATCH, no release letter.</summary>
public const string UnityPlayerFile = "unity_player_file";
/// <summary>Godot (beta.19): the header of the data pack beside the executable.</summary>
public const string GodotPack = "godot_pck";
/// <summary>Godot: the header of the data pack appended to the executable.</summary>
public const string GodotPackEmbedded = "godot_pck_embedded";
/// <summary>Godot: the executable's version resource, still the engine's (<c>ProductName</c> is "Godot Engine").</summary>
public const string GodotExe = "godot_exe";
/// <summary>RPG Maker MZ (beta.19): the header of <c>js/rmmz_core.js</c>.</summary>
public const string RpgMakerMzCore = "rpgmaker_mz_core";
/// <summary>RPG Maker MV: the header of <c>rpg_core.js</c>.</summary>
public const string RpgMakerMvCore = "rpgmaker_mv_core";
/// <summary>RPG Maker XP: the RGSS1 library <c>Game.ini</c> names.</summary>
public const string Rgss1Library = "rgss1_library";
/// <summary>RPG Maker VX: the RGSS2 library.</summary>
public const string Rgss2Library = "rgss2_library";
/// <summary>RPG Maker VX Ace: the RGSS3 library.</summary>
public const string Rgss3Library = "rgss3_library";
/// <summary>Ren'Py (beta.20): the <c>version</c> line of the engine's <c>renpy/vc_version.py</c>, MAJOR.MINOR.PATCH.</summary>
public const string RenPyVcVersion = "renpy_vc_version";
/// <summary>The rule's own extractor, named as the rules file names it (<c>pe_file_version</c>, <c>strings_regex</c>, …).</summary>
public static string Of(VersionExtractorType type) => type switch
{
@@ -26,6 +62,10 @@ public static class EngineVersionSource
VersionExtractorType.StringsRegex => "strings_regex",
VersionExtractorType.ManifestField => "manifest_field",
VersionExtractorType.UnrealBuild => "unreal_build",
VersionExtractorType.UnityBuild => "unity_build",
VersionExtractorType.GodotBuild => "godot_build",
VersionExtractorType.RpgMakerBuild => "rpgmaker_build",
VersionExtractorType.RenPyBuild => "renpy_build",
_ => throw new ArgumentOutOfRangeException(nameof(type), type, "not a version extractor"),
};
}
@@ -0,0 +1,29 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Detection;
/// <summary>
/// What a Godot title's own files say about the engine it was exported with (beta.19), read from the files on disk.
/// </summary>
/// <remarks>
/// A Godot export's data pack starts with a header — the magic <c>GDPC</c>, the pack format, then the engine's MAJOR, MINOR
/// and PATCH — whether it sits beside the executable (<c>Game.pck</c>) or is appended to it. Measured 2026-10-12 on the
/// owner's two Godot installs: Plethora of Bullets 2 (format 2, 4.2.2) and 衔蝶 (format 2, 4.4.1). The executable's
/// own <c>Godot Engine v4.4.1.stable.official</c> string sits 57 to 78 MB into it — past the 8 MiB the rules' strings scan
/// reads, which is why the old <c>strings_regex</c> extractor never found it.
/// </remarks>
public sealed record GodotBuildFacts
{
/// <summary>The engine's MAJOR, MINOR and PATCH from a data pack's header, or null when no header was read.</summary>
public IReadOnlyList<int>? PackVersion { get; init; }
/// <summary>True when that header was read from a pack appended to the executable, not from a <c>.pck</c> beside it.</summary>
public bool PackEmbedded { get; init; }
/// <summary>The executable's <c>ProductName</c>, or null.</summary>
public string? ExeProductName { get; init; }
/// <summary>The executable's <c>ProductVersion</c>, or null.</summary>
public string? ExeProductVersion { get; init; }
}
@@ -0,0 +1,59 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
using System.Text.RegularExpressions;
namespace FrameLedger.Domain.Detection;
/// <summary>The Godot version a title was exported with (beta.19), decided from <see cref="GodotBuildFacts"/> — or nothing.</summary>
/// <remarks>
/// <para>
/// <b>The ladder:</b> (1) a data pack's header, beside the executable or appended to it — the engine writes its own
/// version there; (2) the executable's version resource, only while its <c>ProductName</c> is still <c>Godot Engine</c>:
/// an export whose project set no version information keeps the engine's (<c>4.2.2.stable.official</c> on Plethora of
/// Bullets 2), and one that set its own carries the game's (衔蝶: <c>0.1.0.3</c>), which is not the engine's.
/// </para>
/// <para>
/// A zero patch is not written, because Godot does not write it: 4.3, 4.2.2.
/// </para>
/// </remarks>
public static partial class GodotVersion
{
/// <summary>The product name a Godot export keeps when its project set none.</summary>
public const string EngineProductName = "Godot Engine";
/// <summary>The version these facts establish, and the witness it rests on.</summary>
public static EngineVersionReading Decide(GodotBuildFacts facts)
{
ArgumentNullException.ThrowIfNull(facts);
if (facts.PackVersion is { Count: >= 3 } pack && Format(pack[0], pack[1], pack[2]) is { } fromPack)
{
return new EngineVersionReading(fromPack, facts.PackEmbedded ? EngineVersionSource.GodotPackEmbedded : EngineVersionSource.GodotPack);
}
if (string.Equals(facts.ExeProductName?.Trim(), EngineProductName, StringComparison.OrdinalIgnoreCase)
&& facts.ExeProductVersion is { } text && ProductShape().Match(text.Trim()) is { Success: true } m
&& Format(Parse(m.Groups["major"].Value), Parse(m.Groups["minor"].Value), m.Groups["patch"].Success ? Parse(m.Groups["patch"].Value) : 0) is { } fromExe)
{
return new EngineVersionReading(fromExe, EngineVersionSource.GodotExe);
}
return EngineVersionReading.None;
}
/// <summary><c>4.2.2</c>, <c>4.3</c> — or null for numbers no Godot release carries (a pack written by something else).</summary>
private static string? Format(int major, int minor, int patch) =>
major is < 1 or > 9 || minor is < 0 or > 99 || patch is < 0 or > 99
? null
: patch == 0
? string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}")
: string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}.{patch}");
private static int Parse(string digits) =>
int.TryParse(digits, NumberStyles.None, CultureInfo.InvariantCulture, out int value) ? value : -1;
[GeneratedRegex(@"^(?<major>\d{1,2})\.(?<minor>\d{1,2})(?:\.(?<patch>\d{1,2}))?(?:\.[a-z]|$)", RegexOptions.ExplicitCapture | RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex ProductShape();
}
@@ -0,0 +1,20 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Detection;
/// <summary>
/// What a Ren'Py title's own files say about the engine it was built with (beta.20), read from the files on disk.
/// </summary>
/// <remarks>
/// Ren'Py ships its engine as Python beside the game's launcher, and the engine's <c>renpy/vc_version.py</c> names its
/// release: <c>version = '8.5.0.25111603'</c>, with <c>version_name</c>, <c>branch</c>, <c>official</c> and <c>nightly</c>
/// beside it. Measured 2026-10-12 on the owner's one Ren'Py install, Bound Between Desks (Steam): <c>8.5.0.25111603</c>,
/// the same number the game's own <c>log.txt</c> printed at its last start (<c>Ren'Py 8.5.0.25111603</c>). Its launcher
/// executable carries no version resource.
/// </remarks>
public sealed record RenPyBuildFacts
{
/// <summary>The <c>version</c> string of <c>renpy/vc_version.py</c> (<c>8.5.0.25111603</c>), or null when it names none.</summary>
public string? VcVersion { get; init; }
}
@@ -0,0 +1,35 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
using System.Text.RegularExpressions;
namespace FrameLedger.Domain.Detection;
/// <summary>The Ren'Py version a title was built with (beta.20), decided from <see cref="RenPyBuildFacts"/> — or nothing.</summary>
/// <remarks>
/// One witness: the engine's own <c>renpy/vc_version.py</c>. Its <c>version</c> carries a fourth number, the build
/// (<c>8.5.0.25111603</c>); a Ren'Py release is named by the first three (Ren'Py 8.5.0), so those are kept. A title whose
/// engine names no version there reads as none — nothing else is guessed from.
/// </remarks>
public static partial class RenPyVersion
{
/// <summary>The version these facts establish, and the witness it rests on.</summary>
public static EngineVersionReading Decide(RenPyBuildFacts facts)
{
ArgumentNullException.ThrowIfNull(facts);
return facts.VcVersion is { } text && Shape().Match(text.Trim()) is { Success: true } m
&& Parse(m.Groups["major"].Value) is >= 1 and <= 99 and int major
&& Parse(m.Groups["minor"].Value) is >= 0 and int minor
&& Parse(m.Groups["patch"].Value) is >= 0 and int patch
? new EngineVersionReading(string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}.{patch}"), EngineVersionSource.RenPyVcVersion)
: EngineVersionReading.None;
}
private static int Parse(string digits) =>
int.TryParse(digits, NumberStyles.None, CultureInfo.InvariantCulture, out int value) ? value : -1;
[GeneratedRegex(@"^(?<major>\d{1,2})\.(?<minor>\d{1,3})\.(?<patch>\d{1,3})(?:\.\d{1,12})?$", RegexOptions.ExplicitCapture | RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex Shape();
}
@@ -0,0 +1,34 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Detection;
/// <summary>
/// What an RPG Maker title's own files say about the maker that built it (beta.19), read from the files on disk.
/// </summary>
/// <remarks>
/// <para>
/// <b>MV and MZ</b> ship their engine as JavaScript, and its core script opens with its own name and version — line 2 of
/// <c>js/rmmz_core.js</c> reads <c>// rmmz_core.js v1.10.0</c> (A Doll's Locket - Remake), of <c>www/js/rpg_core.js</c>
/// <c>// rpg_core.js v1.6.2</c> (Flower in Us, 996IR) or <c>v1.6.1</c> (HELLO, HELLO WORLD!) — measured 2026-10-12.
/// </para>
/// <para>
/// <b>XP, VX and VX Ace</b> run on the Ruby Game Scripting System, whose library <c>Game.ini</c> names
/// (<c>Library=System\RGSS301.dll</c>): RGSS1 is XP, RGSS2 VX, RGSS3 VX Ace, and the name carries the library's version
/// (<c>RGSS301</c> is 3.0.1; its version resource reads <c>3, 0, 1, 1</c> on City of Bones and Träumerei Chapter 2).
/// </para>
/// </remarks>
public sealed record RpgMakerBuildFacts
{
/// <summary>The core script whose header was read — <c>rmmz_core.js</c> or <c>rpg_core.js</c> — or null.</summary>
public string? CoreScript { get; init; }
/// <summary>The version that script's header names (<c>1.10.0</c>), or null.</summary>
public string? CoreScriptVersion { get; init; }
/// <summary>The RGSS library's file name (<c>RGSS301.dll</c>), as <c>Game.ini</c> names it or as found, or null.</summary>
public string? RgssLibrary { get; init; }
/// <summary>That library's numeric file version (four parts), or null when it carries none or was not read.</summary>
public IReadOnlyList<int>? RgssFileVersion { get; init; }
}
@@ -0,0 +1,77 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
using System.Text.RegularExpressions;
namespace FrameLedger.Domain.Detection;
/// <summary>
/// Which RPG Maker built a title, and at which version (beta.19), decided from <see cref="RpgMakerBuildFacts"/> — or nothing.
/// The witness names the maker: the App shows <c>rpgmaker_mv</c> as "RPG Maker MZ" when the version came from MZ's core
/// script, and <c>rpgmaker_rgss</c> as "RPG Maker VX Ace" when it came from an RGSS3 library.
/// </summary>
public static partial class RpgMakerVersion
{
/// <summary>MZ's core script.</summary>
public const string MzCoreScript = "rmmz_core.js";
/// <summary>MV's core script.</summary>
public const string MvCoreScript = "rpg_core.js";
/// <summary>The version these facts establish, and the witness it rests on.</summary>
public static EngineVersionReading Decide(RpgMakerBuildFacts facts)
{
ArgumentNullException.ThrowIfNull(facts);
if (ScriptVersion(facts.CoreScriptVersion) is { } script)
{
if (string.Equals(facts.CoreScript, MzCoreScript, StringComparison.OrdinalIgnoreCase))
{
return new EngineVersionReading(script, EngineVersionSource.RpgMakerMzCore);
}
if (string.Equals(facts.CoreScript, MvCoreScript, StringComparison.OrdinalIgnoreCase))
{
return new EngineVersionReading(script, EngineVersionSource.RpgMakerMvCore);
}
}
if (facts.RgssLibrary is null || LibraryShape().Match(facts.RgssLibrary.Trim()) is not { Success: true } m)
{
return EngineVersionReading.None;
}
int generation = m.Groups["generation"].Value[0] - '0';
string source = generation switch
{
1 => EngineVersionSource.Rgss1Library,
2 => EngineVersionSource.Rgss2Library,
_ => EngineVersionSource.Rgss3Library,
};
// The library's own numbers when they are its generation's; else the ones its name carries (RGSS301 → 3.0.1).
string version = facts.RgssFileVersion is { Count: >= 3 } parts && parts[0] == generation && parts[1] is >= 0 and <= 9 && parts[2] is >= 0 and <= 9
? string.Create(CultureInfo.InvariantCulture, $"{parts[0]}.{parts[1]}.{parts[2]}")
: string.Create(CultureInfo.InvariantCulture, $"{generation}.{m.Groups["minor"].Value}.{m.Groups["patch"].Value}");
return new EngineVersionReading(version, source);
}
/// <summary>A core script's version as its header writes it (<c>1.10.0</c>), or null when it does not read as one.</summary>
public static string? ScriptVersion(string? text)
{
if (string.IsNullOrWhiteSpace(text))
{
return null;
}
Match m = ScriptShape().Match(text.Trim());
return m.Success ? m.Value : null;
}
[GeneratedRegex(@"^\d{1,2}\.\d{1,3}\.\d{1,3}$", RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex ScriptShape();
[GeneratedRegex(@"^RGSS(?<generation>[123])(?<minor>\d)(?<patch>\d)[A-Z]?\.dll$", RegexOptions.ExplicitCapture | RegexOptions.CultureInvariant | RegexOptions.IgnoreCase, matchTimeoutMilliseconds: 250)]
private static partial Regex LibraryShape();
}
@@ -232,8 +232,10 @@ public sealed class RuleEvaluator
? v
: null,
// Not answerable from the snapshot: StaticGameDetector reads the engine's build facts for the one engine
// that matched (beta.10) — a scan the probe must not make for every game in the library.
VersionExtractorType.UnrealBuild => null,
// that matched (beta.10; Unity, Godot and RPG Maker since beta.19) — reads the probe must not make for every
// game in the library.
VersionExtractorType.UnrealBuild or VersionExtractorType.UnityBuild or VersionExtractorType.GodotBuild
or VersionExtractorType.RpgMakerBuild or VersionExtractorType.RenPyBuild => null,
_ => null,
};
}
@@ -0,0 +1,27 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Domain.Detection;
/// <summary>
/// What a Unity title's own files say about the engine it was built with (beta.19): read from the files on disk, never from
/// the game's process (CLAUDE.md rule 4 is about game memory).
/// </summary>
/// <remarks>
/// Measured read-only on the owner's fifteen Unity installs, 2026-10-12 (<c>05_DETECTION</c> §Engine version — Unity, Godot,
/// RPG Maker): the player library's <c>ProductVersion</c> names the editor version in thirteen
/// (<c>2022.3.39f1 (4e1b0f82c39a)</c>); a 2019.4 player carries only numbers there, and its data file's header names it
/// (<c>2019.4.1f1</c>); GIRLS' FRONTLINE 2's data file is encrypted, and its player's numeric file version
/// (<c>2019.4.40.16762411</c>) is all there is.
/// </remarks>
public sealed record UnityBuildFacts
{
/// <summary><c>UnityPlayer.dll</c>'s <c>ProductVersion</c> string, or null.</summary>
public string? PlayerProductVersion { get; init; }
/// <summary><c>UnityPlayer.dll</c>'s numeric file version (four parts), or null when it carries none or was not read.</summary>
public IReadOnlyList<int>? PlayerFileVersion { get; init; }
/// <summary>The editor version the header of <c>&lt;Game&gt;_Data\globalgamemanagers</c> names, as read, or null.</summary>
public string? DataHeaderVersion { get; init; }
}
@@ -0,0 +1,78 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Globalization;
using System.Text.RegularExpressions;
namespace FrameLedger.Domain.Detection;
/// <summary>
/// The Unity version a title was built with (beta.19, owner request: "detect the version of Unity, Godot and RPG Maker
/// games"), decided from <see cref="UnityBuildFacts"/> — or nothing.
/// </summary>
/// <remarks>
/// <para>
/// <b>The ladder, strongest first</b> (measured on fifteen installs 2026-10-12):
/// </para>
/// <list type="number">
/// <item>The player library's <c>ProductVersion</c> is an editor version — <c>2022.3.39f1</c>, the release letter and its
/// number included (thirteen of fifteen).</item>
/// <item>The data file's header names one (A Space for the Unbound: <c>2019.4.1f1</c>, beside a player that carries only
/// numbers).</item>
/// <item>The player's numeric file version: MAJOR.MINOR.PATCH and no release letter (GIRLS' FRONTLINE 2: <c>2019.4.40</c>,
/// whose data file is encrypted). The player library is Unity's own binary — a studio does not number it — so this rung
/// is the engine's, only shorter.</item>
/// </list>
/// <para>
/// Until beta.19 the rules read the player's <c>FileVersion</c> string as it is (<c>2022.3.39.5118735</c>, the build
/// number where the release letter belongs).
/// </para>
/// </remarks>
public static partial class UnityVersion
{
/// <summary>The version these facts establish, and the rung it stands on.</summary>
public static EngineVersionReading Decide(UnityBuildFacts facts)
{
ArgumentNullException.ThrowIfNull(facts);
if (EditorVersion(facts.PlayerProductVersion) is { } product)
{
return new EngineVersionReading(product, EngineVersionSource.UnityPlayer);
}
if (EditorVersion(facts.DataHeaderVersion) is { } header)
{
return new EngineVersionReading(header, EngineVersionSource.UnityData);
}
return facts.PlayerFileVersion is { Count: >= 3 } parts && IsUnityMajor(parts[0]) && parts[1] is >= 0 and <= 99 && parts[2] is >= 0 and <= 999
? new EngineVersionReading(string.Create(CultureInfo.InvariantCulture, $"{parts[0]}.{parts[1]}.{parts[2]}"), EngineVersionSource.UnityPlayerFile)
: EngineVersionReading.None;
}
/// <summary>
/// The editor version a text starts with — <c>2022.3.39f1</c> of <c>2022.3.39f1 (4e1b0f82c39a)</c>, <c>6000.0.58f2</c> —
/// or null when it is not one: a major Unity never used, or no release letter (<c>2019.4.1.15122501</c>).
/// </summary>
public static string? EditorVersion(string? text)
{
if (string.IsNullOrWhiteSpace(text))
{
return null;
}
Match m = EditorShape().Match(text.Trim());
return m.Success && int.TryParse(m.Groups["major"].Value, NumberStyles.None, CultureInfo.InvariantCulture, out int major) && IsUnityMajor(major)
? m.Groups["version"].Value
: null;
}
/// <summary>
/// The majors Unity has shipped: 3 to 5, the years 2017 to 2023, and Unity 6's <c>6000</c> line (6000.0 is Unity 6,
/// 6000.3 is 6.3).
/// </summary>
private static bool IsUnityMajor(int major) => major is >= 3 and <= 5 or >= 2017 and <= 2023 or >= 6000 and <= 6999;
[GeneratedRegex(@"^(?<version>(?<major>\d{1,4})\.\d{1,2}\.\d{1,3}[abfpx]\d{1,3})(?![\d.])", RegexOptions.ExplicitCapture | RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex EditorShape();
}
@@ -25,4 +25,22 @@ public enum VersionExtractorType
/// matched — so <see cref="RuleEvaluator"/> returns null for it.
/// </summary>
UnrealBuild,
/// <summary>
/// Unity's (beta.19): the player library's version resource and the data file's header, weighed by
/// <see cref="UnityVersion.Decide"/>. A second read, like <see cref="UnrealBuild"/>.
/// </summary>
UnityBuild,
/// <summary>Godot's (beta.19): a data pack's header and the executable's version resource (<see cref="GodotVersion.Decide"/>).</summary>
GodotBuild,
/// <summary>
/// RPG Maker's (beta.19): MV/MZ's core-script header, or the RGSS library <c>Game.ini</c> names
/// (<see cref="RpgMakerVersion.Decide"/>).
/// </summary>
RpgMakerBuild,
/// <summary>Ren'Py's (beta.20): the <c>version</c> line of the engine's <c>renpy/vc_version.py</c> (<see cref="RenPyVersion.Decide"/>).</summary>
RenPyBuild,
}
@@ -225,6 +225,10 @@ public sealed class DetectionRulesFile : IDetectionRulesSource
"strings_regex" => VersionExtractorType.StringsRegex,
"manifest_field" => VersionExtractorType.ManifestField,
"unreal_build" => VersionExtractorType.UnrealBuild,
"unity_build" => VersionExtractorType.UnityBuild,
"godot_build" => VersionExtractorType.GodotBuild,
"rpgmaker_build" => VersionExtractorType.RpgMakerBuild,
"renpy_build" => VersionExtractorType.RenPyBuild,
_ => throw new InvalidOperationException($"'{owner}' has unknown version extractor '{d.Type}'"),
},
Value = d.Value,
@@ -124,6 +124,131 @@ public sealed class GameFileProbe : IGameFileProbe
return ValueTask.FromResult(ShippingExecutable(snapshot) is { } exe ? UnrealBuildReader.Read(exe.FullPath, exe.RelativePath, ct) : null);
}
/// <inheritdoc />
/// <remarks>
/// <c>UnityPlayer.dll</c> beside the row's executable, else the shallowest one the walk listed; the data file is
/// <c>&lt;exe&gt;_Data\globalgamemanagers</c>, else the one in a <c>*_Data</c> folder beside that player.
/// </remarks>
public ValueTask<UnityBuildFacts?> ReadUnityBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(snapshot);
ct.ThrowIfCancellationRequested();
string exe = Native(snapshot.ExePath);
string? exeDirectory = Path.GetDirectoryName(exe);
string? beside = exeDirectory is null ? null : Path.Combine(exeDirectory, "UnityPlayer.dll");
string? player = beside is not null && File.Exists(beside) ? beside : Shallowest(snapshot, static name => string.Equals(name, "UnityPlayer.dll", StringComparison.OrdinalIgnoreCase));
return ValueTask.FromResult(UnityBuildReader.Read(player, UnityDataFile(snapshot, exe, player)));
}
/// <inheritdoc />
/// <remarks>The pack is <c>&lt;exe&gt;.pck</c> beside the executable, else the only <c>.pck</c> there; else the executable's own end.</remarks>
public ValueTask<GodotBuildFacts?> ReadGodotBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(snapshot);
ct.ThrowIfCancellationRequested();
string exe = Native(snapshot.ExePath);
return ValueTask.FromResult(GodotBuildReader.Read(exe, GodotPack(exe)));
}
/// <inheritdoc />
/// <remarks>The core script or <c>Game.ini</c> beside the executable or up to two folders above; else an RGSS library the walk listed.</remarks>
public ValueTask<RpgMakerBuildFacts?> ReadRpgMakerBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(snapshot);
ct.ThrowIfCancellationRequested();
string? library = Shallowest(snapshot, static name => name.StartsWith("RGSS", StringComparison.OrdinalIgnoreCase) && name.EndsWith(".dll", StringComparison.OrdinalIgnoreCase));
return ValueTask.FromResult(RpgMakerBuildReader.Read(Native(snapshot.ExePath), library));
}
/// <inheritdoc />
/// <remarks>The engine's <c>renpy/vc_version.py</c> beside the launcher, where Ren'Py keeps it.</remarks>
public ValueTask<RenPyBuildFacts?> ReadRenPyBuildAsync(GameFileSnapshot snapshot, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(snapshot);
ct.ThrowIfCancellationRequested();
return ValueTask.FromResult(RenPyBuildReader.Read(Native(snapshot.ExePath)));
}
private static string Native(string path) => path.Replace('/', Path.DirectorySeparatorChar);
/// <summary>The full path of the shallowest file the walk listed whose name <paramref name="named"/> accepts, or null.</summary>
private static string? Shallowest(GameFileSnapshot snapshot, Func<string, bool> named)
{
string? best = null;
int bestDepth = int.MaxValue;
foreach (string relative in snapshot.RelativeFiles)
{
int slash = relative.LastIndexOf('/');
if (!named(relative[(slash + 1)..]))
{
continue;
}
int depth = relative.Count(static c => c == '/');
if (depth < bestDepth)
{
(best, bestDepth) = (relative, depth);
}
}
return best is null ? null : Native(snapshot.GameDirectory.TrimEnd('/') + "/" + best);
}
private static string? UnityDataFile(GameFileSnapshot snapshot, string exe, string? player)
{
string? exeDirectory = Path.GetDirectoryName(exe);
if (exeDirectory is not null)
{
string own = Path.Combine(exeDirectory, Path.GetFileNameWithoutExtension(exe) + "_Data", "globalgamemanagers");
if (File.Exists(own))
{
return own;
}
}
string? playerDirectory = player is null ? null : Path.GetDirectoryName(player);
if (playerDirectory is null)
{
return null;
}
try
{
return Directory.EnumerateDirectories(playerDirectory, "*_Data")
.Select(static d => Path.Combine(d, "globalgamemanagers"))
.FirstOrDefault(File.Exists);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return null;
}
}
private static string? GodotPack(string exe)
{
string? directory = Path.GetDirectoryName(exe);
if (directory is null)
{
return null;
}
string own = Path.Combine(directory, Path.GetFileNameWithoutExtension(exe) + ".pck");
if (File.Exists(own))
{
return own;
}
try
{
string[] packs = [.. Directory.EnumerateFiles(directory, "*.pck").Take(2)];
return packs.Length == 1 ? packs[0] : null;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return null;
}
}
/// <summary>
/// The executable an Unreal title's engine version is read from (beta.10): the row's own when it is the shipping build
/// (<c>*-Win64-Shipping.exe</c>, <c>*-WinGDK-Shipping.exe</c> — what <c>ExecutableLocator</c> prefers), else the largest
@@ -303,9 +428,9 @@ public sealed class GameFileProbe : IGameFileProbe
/// name, keyed by the <c>from</c> value.
/// </summary>
/// <remarks>
/// Unity's rule reads <c>UnityPlayer.dll</c>. Answering that from the game
/// executable would report a version that is <em>wrong</em> rather than
/// merely missing, which is the worse of the two failures.
/// CryEngine's rule reads <c>CrySystem.dll</c> (Unity's read <c>UnityPlayer.dll</c> until beta.19, when its version
/// became <see cref="ReadUnityBuildAsync"/>'s). Answering that from the game executable would report a version that is
/// <em>wrong</em> rather than merely missing, which is the worse of the two failures.
/// </remarks>
private static Dictionary<string, string> ReadSiblingVersions(string dir, DetectionRuleSet rules)
{
@@ -0,0 +1,116 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Buffers.Binary;
using System.Diagnostics;
using FrameLedger.Domain.Detection;
namespace FrameLedger.Infrastructure.Detection;
/// <summary>
/// Godot's build facts from the files on disk (beta.19, <c>05_DETECTION</c> §Engine version — Unity, Godot, RPG Maker): the
/// 20-byte header of the data pack — <c>GDPC</c>, the pack format, the engine's MAJOR, MINOR and PATCH, little-endian — from
/// a <c>.pck</c> beside the executable, or from a pack appended to the executable, which ends with the pack's size and the
/// magic again; and the executable's version resource. Nothing else of either file is read.
/// </summary>
public static class GodotBuildReader
{
/// <summary><c>GDPC</c> as the little-endian <c>uint</c> a pack starts (and an appended pack ends) with.</summary>
public const uint PackMagic = 0x43504447;
/// <summary>The header: magic, format, major, minor, patch.</summary>
public const int HeaderBytes = 20;
/// <summary>What an appended pack leaves at the end of the executable: its size (a 64-bit integer), then the magic.</summary>
public const int TrailerBytes = 12;
/// <summary>The facts for <paramref name="exePath"/>, or null when nothing could be read.</summary>
/// <param name="exePath">The game's executable.</param>
/// <param name="packPath">The <c>.pck</c> beside it, or null when there is none.</param>
public static GodotBuildFacts? Read(string exePath, string? packPath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
IReadOnlyList<int>? pack = packPath is null ? null : ReadFile(packPath, static s => ReadHeader(s, 0));
bool embedded = false;
if (pack is null)
{
pack = ReadFile(exePath, ReadAppended);
embedded = pack is not null;
}
string? productName = null;
string? productVersion = null;
try
{
FileVersionInfo info = FileVersionInfo.GetVersionInfo(exePath);
productName = string.IsNullOrWhiteSpace(info.ProductName) ? null : info.ProductName.Trim();
productVersion = string.IsNullOrWhiteSpace(info.ProductVersion) ? null : info.ProductVersion.Trim();
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException)
{
// The pack, if read, is the stronger witness anyway.
}
return pack is null && productName is null && productVersion is null
? null
: new GodotBuildFacts { PackVersion = pack, PackEmbedded = embedded, ExeProductName = productName, ExeProductVersion = productVersion };
}
/// <summary>MAJOR, MINOR, PATCH from a header at <paramref name="offset"/>, or null when there is none. Public for the tests.</summary>
public static IReadOnlyList<int>? ReadHeader(Stream stream, long offset)
{
ArgumentNullException.ThrowIfNull(stream);
if (offset < 0 || offset + HeaderBytes > stream.Length)
{
return null;
}
Span<byte> header = stackalloc byte[HeaderBytes];
stream.Position = offset;
if (stream.ReadAtLeast(header, HeaderBytes, throwOnEndOfStream: false) < HeaderBytes
|| BinaryPrimitives.ReadUInt32LittleEndian(header) != PackMagic)
{
return null;
}
uint major = BinaryPrimitives.ReadUInt32LittleEndian(header[8..]);
uint minor = BinaryPrimitives.ReadUInt32LittleEndian(header[12..]);
uint patch = BinaryPrimitives.ReadUInt32LittleEndian(header[16..]);
return major > 99 || minor > 99 || patch > 99 ? null : [(int)major, (int)minor, (int)patch];
}
/// <summary>The header of a pack appended to an executable, found through the trailer it ends with. Public for the tests.</summary>
public static IReadOnlyList<int>? ReadAppended(Stream stream)
{
ArgumentNullException.ThrowIfNull(stream);
long length = stream.Length;
if (length < TrailerBytes + HeaderBytes)
{
return null;
}
Span<byte> trailer = stackalloc byte[TrailerBytes];
stream.Position = length - TrailerBytes;
if (stream.ReadAtLeast(trailer, TrailerBytes, throwOnEndOfStream: false) < TrailerBytes
|| BinaryPrimitives.ReadUInt32LittleEndian(trailer[8..]) != PackMagic)
{
return null;
}
long size = BinaryPrimitives.ReadInt64LittleEndian(trailer);
return size < HeaderBytes || size > length - TrailerBytes ? null : ReadHeader(stream, length - TrailerBytes - size);
}
private static IReadOnlyList<int>? ReadFile(string path, Func<Stream, IReadOnlyList<int>?> read)
{
try
{
using var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, bufferSize: 1);
return read(file);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return null;
}
}
}
@@ -0,0 +1,49 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Text;
using System.Text.RegularExpressions;
using FrameLedger.Domain.Detection;
namespace FrameLedger.Infrastructure.Detection;
/// <summary>
/// Ren'Py's build facts from the files on disk (beta.20, <c>05_DETECTION</c> §Engine version — Ren'Py): the <c>version</c>
/// line of the engine's <c>renpy/vc_version.py</c>, which Ren'Py keeps beside the game's launcher — read from its first
/// <see cref="VersionFileBytes"/> bytes. Nothing else of the engine's files is read.
/// </summary>
public static partial class RenPyBuildReader
{
/// <summary>How much of <c>vc_version.py</c> is read: the measured file is 109 bytes.</summary>
public const int VersionFileBytes = 4096;
/// <summary>The facts for the launcher <paramref name="exePath"/>, or null when its engine's version file names none.</summary>
public static RenPyBuildFacts? Read(string exePath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
string? folder = Path.GetDirectoryName(exePath);
return folder is null ? null : ReadVersionFile(Path.Combine(folder, "renpy", "vc_version.py"));
}
/// <summary>The <c>version</c> a <c>vc_version.py</c> names, or null. Public for the tests.</summary>
public static RenPyBuildFacts? ReadVersionFile(string path)
{
ArgumentException.ThrowIfNullOrWhiteSpace(path);
try
{
using var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, bufferSize: 1);
byte[] head = new byte[VersionFileBytes];
int read = file.ReadAtLeast(head, head.Length, throwOnEndOfStream: false);
Match m = VersionLine().Match(Encoding.UTF8.GetString(head, 0, read));
return m.Success ? new RenPyBuildFacts { VcVersion = m.Groups["version"].Value } : null;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return null;
}
}
/// <summary><c>version = '8.5.0.25111603'</c> at the start of a line — never <c>version_name</c>, whose name goes on.</summary>
[GeneratedRegex(@"^version\s*=\s*['""](?<version>[^'""\r\n]{1,64})['""]", RegexOptions.ExplicitCapture | RegexOptions.Multiline | RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex VersionLine();
}
@@ -0,0 +1,151 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using System.Text;
using System.Text.RegularExpressions;
using FrameLedger.Domain.Detection;
namespace FrameLedger.Infrastructure.Detection;
/// <summary>
/// RPG Maker's build facts from the files on disk (beta.19, <c>05_DETECTION</c> §Engine version — Unity, Godot, RPG Maker):
/// the first <see cref="ScriptHeaderBytes"/> of MV/MZ's core script (<c>js/rmmz_core.js</c>, <c>www/js/rpg_core.js</c>,
/// <c>js/rpg_core.js</c>), or <c>Game.ini</c>'s <c>Library=</c> line and that RGSS library's version resource — beside the
/// executable or up to two folders above it, as <c>RpgMakerTitle</c> looks (a launcher-fronted game keeps its runtime in a
/// subfolder: HELLO, HELLO WORLD!'s is <c>swiftshader\</c>, A Doll's Locket's <c>css\</c>). Nothing else is read.
/// </summary>
public static partial class RpgMakerBuildReader
{
/// <summary>How much of a core script is read: its opening comment block, with room to spare (the version is on line 2).</summary>
public const int ScriptHeaderBytes = 4096;
/// <summary>A <c>Game.ini</c> larger than this is not RPG Maker's (it holds four short lines).</summary>
public const long MaxIniBytes = 64 * 1024;
/// <summary>How many folders above the executable's own are looked in.</summary>
public const int FoldersUp = 2;
private static readonly (string Relative, string Script)[] _scripts =
[
(Path.Combine("js", RpgMakerVersion.MzCoreScript), RpgMakerVersion.MzCoreScript),
(Path.Combine("www", "js", RpgMakerVersion.MvCoreScript), RpgMakerVersion.MvCoreScript),
(Path.Combine("js", RpgMakerVersion.MvCoreScript), RpgMakerVersion.MvCoreScript),
];
/// <summary>The facts for an entry at <paramref name="exePath"/>, or null when none of the files is there.</summary>
/// <param name="exePath">The entry's executable.</param>
/// <param name="rgssLibrary">An RGSS library the install listing holds, for an install with no readable <c>Game.ini</c>; or null.</param>
public static RpgMakerBuildFacts? Read(string exePath, string? rgssLibrary = null)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
string? folder = Path.GetDirectoryName(exePath);
for (int up = 0; up <= FoldersUp && !string.IsNullOrEmpty(folder); up++, folder = Path.GetDirectoryName(folder))
{
foreach ((string relative, string script) in _scripts)
{
if (ScriptVersion(Path.Combine(folder, relative), script) is { } version)
{
return new RpgMakerBuildFacts { CoreScript = script, CoreScriptVersion = version };
}
}
if (LibraryOf(Path.Combine(folder, "Game.ini")) is { } library)
{
return Rgss(library);
}
}
return rgssLibrary is null ? null : Rgss(rgssLibrary);
}
/// <summary>The version a core script's header names for <paramref name="script"/>, or null. Public for the tests.</summary>
public static string? ScriptVersion(string path, string script)
{
ArgumentException.ThrowIfNullOrWhiteSpace(path);
try
{
using var file = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, bufferSize: 1);
byte[] head = new byte[ScriptHeaderBytes];
int read = file.ReadAtLeast(head, head.Length, throwOnEndOfStream: false);
foreach (Match m in HeaderLine().Matches(Encoding.UTF8.GetString(head, 0, read)))
{
if (string.Equals(m.Groups["script"].Value, script, StringComparison.OrdinalIgnoreCase))
{
return RpgMakerVersion.ScriptVersion(m.Groups["version"].Value);
}
}
return null;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return null;
}
}
/// <summary>
/// The library a <c>Game.ini</c> names (<c>Library=System\RGSS301.dll</c>), as a full path under the ini's folder — or
/// its bare file name when the value points outside that folder, which is then not read. Null without the line.
/// </summary>
public static string? LibraryOf(string iniPath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(iniPath);
try
{
var ini = new FileInfo(iniPath);
if (!ini.Exists || ini.Length > MaxIniBytes || ini.DirectoryName is not { } folder)
{
return null;
}
foreach (string line in File.ReadLines(iniPath, Encoding.Latin1))
{
Match m = LibraryLine().Match(line);
if (!m.Success)
{
continue;
}
string value = m.Groups["value"].Value.Trim();
string full = Path.GetFullPath(Path.Combine(folder, value));
return full.StartsWith(Path.TrimEndingDirectorySeparator(folder) + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase)
? full
: Path.GetFileName(value);
}
return null;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException)
{
return null;
}
}
private static RpgMakerBuildFacts Rgss(string library)
{
IReadOnlyList<int>? version = null;
if (Path.IsPathFullyQualified(library))
{
try
{
FileVersionInfo info = FileVersionInfo.GetVersionInfo(library);
version = info.FileMajorPart == 0 && info.FileMinorPart == 0 && info.FileBuildPart == 0 && info.FilePrivatePart == 0
? null
: [info.FileMajorPart, info.FileMinorPart, info.FileBuildPart, info.FilePrivatePart];
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException)
{
// The name still carries the version (RGSS301 is 3.0.1).
}
}
return new RpgMakerBuildFacts { RgssLibrary = Path.GetFileName(library), RgssFileVersion = version };
}
[GeneratedRegex(@"^//\s*(?<script>rmmz_core\.js|rpg_core\.js)\s+v(?<version>\d{1,2}\.\d{1,3}\.\d{1,3})\b", RegexOptions.ExplicitCapture | RegexOptions.Multiline | RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex HeaderLine();
[GeneratedRegex(@"^\s*Library\s*=\s*(?<value>\S.*)$", RegexOptions.ExplicitCapture | RegexOptions.CultureInvariant | RegexOptions.IgnoreCase, matchTimeoutMilliseconds: 250)]
private static partial Regex LibraryLine();
}
@@ -0,0 +1,71 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Diagnostics;
using System.Text;
using System.Text.RegularExpressions;
using FrameLedger.Domain.Detection;
namespace FrameLedger.Infrastructure.Detection;
/// <summary>
/// Unity's build facts from the files on disk (beta.19, <c>05_DETECTION</c> §Engine version — Unity, Godot, RPG Maker): the
/// player library's version resource and the first <see cref="DataHeaderBytes"/> bytes of the data file
/// <c>globalgamemanagers</c>, whose serialized-file header names the editor version (at byte 20 in a 2019.4 build, 48 in
/// later ones). Nothing else of either file is read; the game's process is never opened.
/// </summary>
public static partial class UnityBuildReader
{
/// <summary>How much of the data file is read: its header, with room to spare (the version sat at 48 at the latest).</summary>
public const int DataHeaderBytes = 256;
/// <summary>The facts in the two files, or null when neither gave any.</summary>
/// <param name="playerPath"><c>UnityPlayer.dll</c>, or null when the install has none.</param>
/// <param name="dataFilePath"><c>&lt;Game&gt;_Data\globalgamemanagers</c>, or null.</param>
public static UnityBuildFacts? Read(string? playerPath, string? dataFilePath)
{
string? product = null;
IReadOnlyList<int>? numeric = null;
if (playerPath is not null)
{
try
{
FileVersionInfo info = FileVersionInfo.GetVersionInfo(playerPath);
product = string.IsNullOrWhiteSpace(info.ProductVersion) ? null : info.ProductVersion.Trim();
numeric = info.FileMajorPart == 0 && info.FileMinorPart == 0 && info.FileBuildPart == 0 && info.FilePrivatePart == 0
? null
: [info.FileMajorPart, info.FileMinorPart, info.FileBuildPart, info.FilePrivatePart];
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException)
{
// No version resource read: the data file may still say it.
}
}
string? header = dataFilePath is null ? null : DataHeaderVersion(dataFilePath);
return product is null && numeric is null && header is null
? null
: new UnityBuildFacts { PlayerProductVersion = product, PlayerFileVersion = numeric, DataHeaderVersion = header };
}
/// <summary>The editor version in the first <see cref="DataHeaderBytes"/> of a data file, or null. Public for the tests.</summary>
public static string? DataHeaderVersion(string dataFilePath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(dataFilePath);
try
{
using var file = new FileStream(dataFilePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite | FileShare.Delete, bufferSize: 1);
byte[] head = new byte[DataHeaderBytes];
int read = file.ReadAtLeast(head, head.Length, throwOnEndOfStream: false);
Match m = HeaderVersion().Match(Encoding.Latin1.GetString(head, 0, read));
return m.Success ? UnityVersion.EditorVersion(m.Value) : null;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
return null;
}
}
[GeneratedRegex(@"\d{1,4}\.\d{1,2}\.\d{1,3}[abfpx]\d{1,3}", RegexOptions.CultureInvariant, matchTimeoutMilliseconds: 250)]
private static partial Regex HeaderVersion();
}
@@ -24,9 +24,14 @@ namespace FrameLedger.Infrastructure.Import;
/// bootstrapper and as <c>Game-Win64-Shipping.exe</c>.
/// </para>
/// <para>
/// The two layout rules are the engines' own conventions, not guesses about names: a Unity player is <c>X.exe</c>
/// beside a directory <c>X_Data</c>, and an Unreal packaged build's game process is <c>*-Win64-Shipping.exe</c> (the
/// root executable of the same name is a bootstrapper that starts it and exits).
/// The layout rules are the engines' own conventions, not guesses about names: a Unity player is <c>X.exe</c> beside a
/// directory <c>X_Data</c>, an Unreal packaged build's game process is <c>*-Win64-Shipping.exe</c> (the root executable
/// of the same name is a bootstrapper that starts it and exits), and — since beta.19 (owner decision D56) — an NW.js
/// runtime is the executable beside its <c>nw.dll</c> and <c>package.json</c>, which is how an RPG Maker MV/MZ game
/// ships. The last one ranks below the first two and above a name: an NW.js folder can be a tool shipped beside a Unity
/// or Unreal game, and a launcher named after the install is exactly what fronts the runtime on A Doll's Locket - Remake
/// (itch), whose 213 MB <c>DollsLocket.exe</c> starts <c>css\Game.exe</c> — the process that draws, the one D28 pointed
/// HELLO, HELLO WORLD!'s entry at by hand.
/// </para>
/// </remarks>
public sealed class ExecutableLocator : IExecutableLocator
@@ -37,7 +42,8 @@ public sealed class ExecutableLocator : IExecutableLocator
/// </summary>
public const int MaxDepth = 4;
private const int _rankEngineLayout = 2;
private const int _rankEngineLayout = 3;
private const int _rankNwjsRuntime = 2;
private const int _rankNamedAfterTheInstall = 1;
private const int _minimumNameLength = 4;
@@ -50,8 +56,30 @@ public sealed class ExecutableLocator : IExecutableLocator
// beta.14: BugSplat's sender (BsSndRpt64.exe, Kingdom Come: Deliverance II) matches none of the above — its name says
// "report" without the letters; KCD2 picked its game by rank alone.
"bssndrpt", "bugsplat",
// beta.19: what an NW.js runtime keeps beside itself — Chromium's toast helper (NW.js 0.48.4 on A Doll's Locket - Remake,
// 0.82.0 on Flower in Us), and the SDK flavour's compiler and driver, which the NW.js rank would otherwise weigh as the game.
"notification_helper", "nwjc", "chromedriver",
];
/// <summary>
/// Whole names (no extension) of helpers a runtime ships beside a game, which no store's choice makes the game (beta.19).
/// itch's butler keeps the shallowest candidates and drops those that ask for elevation, so its verdict for A Doll's
/// Locket - Remake named <c>notification_helper.exe</c> and nothing else. Whole names rather than
/// <see cref="HelperFragments"/>: a store names its own pick, and a fragment such as <c>node</c> is inside a real game's
/// name (<c>Nodebuster</c>) — the locator's guess can afford that, overruling a store's verdict cannot.
/// </summary>
public static readonly IReadOnlySet<string> RuntimeHelperNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{
"notification_helper", "crashpad_handler", "UnityCrashHandler64", "UnityCrashHandler32", "CrashReportClient", "nwjc", "chromedriver",
};
/// <summary>True for a name in <see cref="RuntimeHelperNames"/>.</summary>
public static bool IsRuntimeHelper(string fileNameWithoutExtension)
{
ArgumentNullException.ThrowIfNull(fileNameWithoutExtension);
return RuntimeHelperNames.Contains(fileNameWithoutExtension);
}
/// <summary>
/// Folder-name fragments of what a store install carries beside the game: a folder whose name holds one is not walked.
/// Red Dead Redemption 2's <c>Redistributables\Rockstar-Games-Launcher.exe</c> is 140 MB to <c>RDR2.exe</c>'s 90.
@@ -164,6 +192,11 @@ public sealed class ExecutableLocator : IExecutableLocator
return _rankEngineLayout; // Unreal: the packaged game process, not the root bootstrapper
}
if (dir is not null && File.Exists(Path.Combine(dir, "nw.dll")) && File.Exists(Path.Combine(dir, "package.json")))
{
return _rankNwjsRuntime; // NW.js (RPG Maker MV/MZ): the runtime, not the launcher in front of it (D56)
}
string squashed = Squash(name);
bool named = squashed.Length >= _minimumNameLength && installName.Length >= _minimumNameLength
&& (installName.Contains(squashed, StringComparison.Ordinal) || squashed.Contains(installName, StringComparison.Ordinal));
@@ -99,16 +99,7 @@ public sealed class ItchLibrarySource(string? itchDirectory = null, Action<strin
""", cancellationToken: ct)).ConfigureAwait(false)).Select(static r => new CaveRow(r.GameId, r.LocationPath, r.FolderName, r.CustomFolder, r.Verdict, r.Title))];
}
int added = 0;
foreach (CaveRow cave in caves)
{
if (ToGame(cave) is { } game && byInstall.TryAdd(game.InstallDirectory, game))
{
added++;
}
}
return $"butler.db read: {locations} location(s), {caves.Count} cave(s), {added} title(s)";
return AddCaves(locations, caves, byInstall);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or SqliteException or InvalidOperationException)
{
@@ -126,7 +117,26 @@ public sealed class ItchLibrarySource(string? itchDirectory = null, Action<strin
}
}
private static StoreGame? ToGame(CaveRow cave)
/// <summary>One row per cave the database lists; returns the log fragment — with the titles whose verdict named only a helper.</summary>
private static string AddCaves(int locations, List<CaveRow> caves, Dictionary<string, StoreGame> byInstall)
{
int added = 0;
List<string> helperVerdicts = [];
foreach (CaveRow cave in caves)
{
if (ToGame(cave, helperVerdicts) is { } game && byInstall.TryAdd(game.InstallDirectory, game))
{
added++;
}
}
string note = $"butler.db read: {locations} location(s), {caves.Count} cave(s), {added} title(s)";
return helperVerdicts.Count == 0
? note
: note + $"; butler's verdict named only a helper for {string.Join(", ", helperVerdicts)} — the executable is guessed instead";
}
private static StoreGame? ToGame(CaveRow cave, List<string> helperVerdicts)
{
string? install = !string.IsNullOrWhiteSpace(cave.CustomFolder) ? cave.CustomFolder
: cave.LocationPath is { Length: > 0 } && cave.FolderName is { Length: > 0 } ? Path.Combine(cave.LocationPath, cave.FolderName)
@@ -138,7 +148,13 @@ public sealed class ItchLibrarySource(string? itchDirectory = null, Action<strin
install = Path.GetFullPath(install);
string name = cave.Title is { Length: > 0 } ? cave.Title : ReadReceipt(Path.Combine(install, ".itch", "receipt.json.gz"))?.Title ?? Path.GetFileName(install);
return new StoreGame(_platform, cave.GameId.ToString(System.Globalization.CultureInfo.InvariantCulture), name, install, VerdictExecutable(cave.Verdict, install), Version: null);
string? exe = VerdictExecutable(cave.Verdict, install, out bool onlyHelpers);
if (onlyHelpers)
{
helperVerdicts.Add(name);
}
return new StoreGame(_platform, cave.GameId.ToString(System.Globalization.CultureInfo.InvariantCulture), name, install, exe, Version: null);
}
/// <summary>
@@ -146,8 +162,17 @@ public sealed class ItchLibrarySource(string? itchDirectory = null, Action<strin
/// Windows candidate is the executable butler itself launches; anything else (an HTML5 or Love2D game, a
/// verdict that will not parse) leaves the guess to the locator.
/// </summary>
private static string? VerdictExecutable(string? verdict, string install)
/// <remarks>
/// <b>Not a candidate a runtime ships as a helper (beta.19).</b> butler saves a FILTERED verdict — the shallowest
/// candidates, minus those whose manifest asks for elevation — and does not rank what is left, so on A Doll's Locket -
/// Remake (game 5085165) the one candidate was <c>Dolls Locket/notification_helper.exe</c>: the 213 MB launcher asks for
/// administrator and the NW.js runtime sits a level deeper. The import took it as the game, unmarked as a guess. A
/// candidate <see cref="ExecutableLocator.IsRuntimeHelper"/> names, or one inside a Unity plugin folder, is skipped;
/// when nothing else is left, <paramref name="onlyHelpers"/> is true and the locator guesses — the review says so.
/// </remarks>
private static string? VerdictExecutable(string? verdict, string install, out bool onlyHelpers)
{
onlyHelpers = false;
if (string.IsNullOrWhiteSpace(verdict))
{
return null;
@@ -167,7 +192,15 @@ public sealed class ItchLibrarySource(string? itchDirectory = null, Action<strin
&& string.Equals(flavor.GetString(), "windows", StringComparison.Ordinal);
if (windows && candidate.TryGetProperty("path", out JsonElement path) && path.ValueKind == JsonValueKind.String && path.GetString() is { Length: > 0 } relative)
{
return Path.GetFullPath(Path.Combine(install, relative.Replace('/', Path.DirectorySeparatorChar)));
string full = Path.GetFullPath(Path.Combine(install, relative.Replace('/', Path.DirectorySeparatorChar)));
if (ExecutableLocator.IsRuntimeHelper(Path.GetFileNameWithoutExtension(full)) || ExecutableLocator.IsUnderPluginFolder(install, full))
{
onlyHelpers = true;
continue;
}
onlyHelpers = false;
return full;
}
}
@@ -175,6 +208,7 @@ public sealed class ItchLibrarySource(string? itchDirectory = null, Action<strin
}
catch (JsonException)
{
onlyHelpers = false;
return null;
}
}
@@ -0,0 +1,36 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using Dapper;
using FrameLedger.Application.Persistence;
namespace FrameLedger.Infrastructure.Persistence;
/// <summary>
/// <see cref="IGamePrune"/> over the ledger (beta.19, owner decision D55): one statement that deletes an uninstalled entry
/// only while every stored condition still holds — the same row at the same path, in the library, no session stored
/// (<c>sessions.game_id</c> is the only reference to <c>games</c> and would cascade), and no anti-cheat block, exception or
/// failed-trial mark. Whatever changed between the sweep's read and this write — a session finalized, a block written, the
/// entry re-pointed — leaves the row as it is.
/// </summary>
public sealed class SqliteGamePrune : IGamePrune
{
private const string _delete =
"DELETE FROM games WHERE id = @id AND exe_path = @path AND removed_at IS NULL "
+ "AND hook_blocked_reason IS NULL AND hook_prescan_state <> 'blocked' "
+ "AND ac_exception_at IS NULL AND ac_exception_trial_failed_at IS NULL "
+ "AND NOT EXISTS (SELECT 1 FROM sessions WHERE sessions.game_id = games.id)";
private readonly LedgerDatabase _db;
public SqliteGamePrune(LedgerDatabase db) => _db = db ?? throw new ArgumentNullException(nameof(db));
/// <inheritdoc />
public async ValueTask<bool> RemoveUninstalledAsync(long gameId, string exePath, CancellationToken ct = default)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
int deleted = await _db.WriteAsync((c, tx, token) => c.ExecuteAsync(new CommandDefinition(_delete, new { id = gameId, path = exePath }, tx, cancellationToken: token)), ct)
.ConfigureAwait(false);
return deleted == 1;
}
}
@@ -0,0 +1,86 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
using System.Security;
using FrameLedger.Application.Watch;
namespace FrameLedger.Infrastructure.Watch;
/// <summary>
/// <see cref="IExecutablePresence"/> over the file system (beta.19, D55): tells a game that is no longer installed from a
/// drive that is not connected, a different disk under the same letter, and a folder Windows will not list — the cases
/// <c>ExecutableIdentity.Read</c>'s null runs together.
/// </summary>
/// <remarks>
/// <para>
/// <b>Asked of listings, not of <c>Exists</c>.</b> <c>File.Exists</c> and <c>Directory.Exists</c> answer false for a path
/// they may not look at as for one that is not there, so the file is looked for in its folder's listing, and a folder that
/// reads as missing is looked for in its parent's: listed but unreadable is <see cref="ExecutablePresence.Unknown"/>.
/// </para>
/// <para>
/// <b>The drive and the path above the game.</b> A drive that <see cref="VolumeRoots"/> does not list as ready (fixed or
/// removable — never a share) is <see cref="ExecutablePresence.DriveAbsent"/>. When nothing of the path is left but the
/// drive's root, the letter may well be another disk's now (the owner's USB drive has changed letters, 2026-09-22):
/// <see cref="ExecutablePresence.OnlyTheDriveRemains"/>, never a removal. An uninstall leaves the folder the game was
/// installed in — <c>steamapps\common</c>, the itch location, <c>D:\Games</c>.
/// </para>
/// </remarks>
public sealed class ExecutablePresenceProbe : IExecutablePresence
{
private readonly Func<string, bool> _driveReady;
/// <summary>
/// The probe over <paramref name="driveReady"/>: whether a root is a ready fixed or removable drive — by default
/// <see cref="VolumeRoots.IsReady"/>, which asks that one drive rather than listing them all for every entry.
/// </summary>
public ExecutablePresenceProbe(Func<string, bool>? driveReady = null) => _driveReady = driveReady ?? VolumeRoots.IsReady;
/// <inheritdoc />
public ExecutablePresence Probe(string exePath)
{
ArgumentException.ThrowIfNullOrWhiteSpace(exePath);
try
{
string full = Path.GetFullPath(exePath);
string? root = Path.GetPathRoot(full);
string? folder = Path.GetDirectoryName(full);
if (string.IsNullOrEmpty(root) || folder is null || full.StartsWith(@"\\", StringComparison.Ordinal))
{
return ExecutablePresence.Unknown;
}
if (!_driveReady(root))
{
return ExecutablePresence.DriveAbsent;
}
if (Directory.Exists(folder))
{
return Directory.EnumerateFiles(folder, Path.GetFileName(full)).Any() ? ExecutablePresence.Present : Gone(folder, root);
}
// The folder reads as missing: up to the nearest folder that is there, which must list the one below it as absent.
string missing = folder;
string? parent = Path.GetDirectoryName(missing);
while (parent is not null && !Directory.Exists(parent))
{
missing = parent;
parent = Path.GetDirectoryName(parent);
}
return parent is null || Directory.EnumerateDirectories(parent, Path.GetFileName(missing)).Any()
? ExecutablePresence.Unknown
: Gone(parent, root);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException or NotSupportedException or SecurityException)
{
return ExecutablePresence.Unknown;
}
}
/// <summary>Gone from <paramref name="nearest"/>, the nearest folder still there — unless that is the drive's root.</summary>
private static ExecutablePresence Gone(string nearest, string root) =>
string.Equals(Path.TrimEndingDirectorySeparator(nearest), Path.TrimEndingDirectorySeparator(root), StringComparison.OrdinalIgnoreCase)
? ExecutablePresence.OnlyTheDriveRemains
: ExecutablePresence.FileGone;
}
@@ -30,4 +30,23 @@ public static class VolumeRoots
return roots;
}
/// <summary>
/// Whether the one drive <paramref name="root"/> names is a ready fixed or removable drive (beta.19) — the same test as
/// <see cref="Ready"/>, asked of one drive. The type is read first: a network or optical drive is never asked whether it
/// is ready, which can block for seconds on a share that went away.
/// </summary>
public static bool IsReady(string root)
{
ArgumentException.ThrowIfNullOrWhiteSpace(root);
try
{
var drive = new DriveInfo(root);
return drive.DriveType is DriveType.Fixed or DriveType.Removable && drive.IsReady;
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or ArgumentException)
{
return false;
}
}
}
@@ -32,6 +32,7 @@ namespace FrameLedger.Shared.Ipc;
[JsonSerializable(typeof(CaptureDegradedEvent))]
[JsonSerializable(typeof(SafetyUnhookEvent))]
[JsonSerializable(typeof(HookingTurnedOffEvent))]
[JsonSerializable(typeof(GameRemovedEvent))]
[JsonSerializable(typeof(CaptureErrorEvent))]
[JsonSerializable(typeof(WatchlistEntry))]
[JsonSerializable(typeof(SetWatchlistRequest))]
+16
View File
@@ -84,6 +84,12 @@ public static class IpcMessageType
/// need be running.
/// </summary>
public const string HookingTurnedOff = "HookingTurnedOff";
/// <summary>
/// The Agent removed a library entry by itself (beta.19, owner decision D55): its game is no longer installed and it had
/// no session. Not a session event; the App reloads what shows the library.
/// </summary>
public const string GameRemoved = "GameRemoved";
}
/// <summary>Codes an <see cref="ErrorAck"/> carries.</summary>
@@ -313,6 +319,16 @@ public sealed record CaptureErrorEvent(Guid? SessionGuid, string Code, string Me
/// <summary><see cref="IpcMessageType.HookingTurnedOff"/>: which entry, and what the guard found (its reason, family and signal).</summary>
public sealed record HookingTurnedOffEvent(long GameId, string? GameName, string Reason, string? Family, string? Signal);
/// <summary>
/// <see cref="IpcMessageType.GameRemoved"/> (beta.19, D55): the entry the Agent removed, its executable's path, and why —
/// <see cref="Uninstalled"/>, the one reason there is: gone from its folder for ten minutes, with no session.
/// </summary>
public sealed record GameRemovedEvent(long GameId, string? GameName, string ExePath, string Reason)
{
/// <summary>The executable is no longer installed and the entry had no session.</summary>
public const string Uninstalled = "uninstalled";
}
// ----------------------------------------------------------------------------------------------------------------
// The command half (P3 PR-1b). 07_IPC §The pipe is not a trust boundary: none of these carries a verdict, a
// clearance, a consent record or a rules source — a client asks, the Agent establishes the fact itself.
+3
View File
@@ -76,6 +76,7 @@ public static class Strings
nameof(Safety_Refused_Unnamed),
nameof(Safety_Unhooked_Format),
nameof(Safety_Unhooked_MachineWide_Format),
nameof(Safety_Unhooked_Unnamed_Format),
];
public static string Safety_AdminMode_Accept => ResourceManager.GetString(nameof(Safety_AdminMode_Accept), Culture) ?? nameof(Safety_AdminMode_Accept);
@@ -171,4 +172,6 @@ public static class Strings
public static string Safety_Unhooked_Format => ResourceManager.GetString(nameof(Safety_Unhooked_Format), Culture) ?? nameof(Safety_Unhooked_Format);
public static string Safety_Unhooked_MachineWide_Format => ResourceManager.GetString(nameof(Safety_Unhooked_MachineWide_Format), Culture) ?? nameof(Safety_Unhooked_MachineWide_Format);
public static string Safety_Unhooked_Unnamed_Format => ResourceManager.GetString(nameof(Safety_Unhooked_Unnamed_Format), Culture) ?? nameof(Safety_Unhooked_Unnamed_Format);
}
+1
View File
@@ -33,6 +33,7 @@
<data name="Safety_HookingTurnedOff" xml:space="preserve"><value>Hooking has been turned off for this game; its page says what was found.</value><comment>safety: human review required</comment></data>
<data name="Safety_Unhooked_Format" xml:space="preserve"><value>Capture stopped: {0} was detected while the game was running, and FrameLedger unhooked.</value><comment>safety: human review required</comment></data>
<data name="Safety_Unhooked_MachineWide_Format" xml:space="preserve"><value>Capture stopped: {0} started on this PC while the game was running ({1}) — a driver or service, which may belong to another game or program — and FrameLedger unhooked. The game's next session is measured again once it is no longer running.</value><comment>safety: human review required</comment></data>
<data name="Safety_Unhooked_Unnamed_Format" xml:space="preserve"><value>Capture stopped while the game was running — {0} — and FrameLedger unhooked.</value><comment>safety: human review required</comment></data>
<data name="Safety_Refused_TargetUnreadable" xml:space="preserve"><value>The game is running, but Windows would not let FrameLedger open its process: it is protected by an anti-cheat driver, or it runs as administrator while FrameLedger does not. Nothing was injected and this run was not measured. FrameLedger will not work around another product's protection. If the game itself runs as administrator, the agent's admin mode in Settings lets FrameLedger open it; a protected process stays closed.</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Title_Format" xml:space="preserve"><value>Make a user-mode exception for {0}?</value><comment>safety: human review required</comment></data>
<data name="Safety_Exception_Intro_Format" xml:space="preserve"><value>FrameLedger found {0} in this game ({1}) and turned its hooking off. This dialog asks whether to make an exception for this game only. It recommends neither choice.</value><comment>safety: human review required</comment></data>
+1
View File
@@ -38,6 +38,7 @@
<data name="Safety_HookingTurnedOff" xml:space="preserve"><value>Hooking has been turned off for this game; its page says what was found.</value></data>
<data name="Safety_Unhooked_Format" xml:space="preserve"><value>Capture stopped: {0} was detected while the game was running, and FrameLedger unhooked.</value></data>
<data name="Safety_Unhooked_MachineWide_Format" xml:space="preserve"><value>Capture stopped: {0} started on this PC while the game was running ({1}) — a driver or service, which may belong to another game or program — and FrameLedger unhooked. The game's next session is measured again once it is no longer running.</value></data>
<data name="Safety_Unhooked_Unnamed_Format" xml:space="preserve"><value>Capture stopped while the game was running — {0} — and FrameLedger unhooked.</value></data>
<data name="Safety_Refused_TargetUnreadable" xml:space="preserve"><value>The game is running, but Windows would not let FrameLedger open its process: it is protected by an anti-cheat driver, or it runs as administrator while FrameLedger does not. Nothing was injected and this run was not measured. FrameLedger will not work around another product's protection. If the game itself runs as administrator, the agent's admin mode in Settings lets FrameLedger open it; a protected process stays closed.</value></data>
<data name="Safety_Exception_Title_Format" xml:space="preserve"><value>Make a user-mode exception for {0}?</value></data>
<data name="Safety_Exception_Intro_Format" xml:space="preserve"><value>FrameLedger found {0} in this game ({1}) and turned its hooking off. This dialog asks whether to make an exception for this game only. It recommends neither choice.</value></data>
+1
View File
@@ -32,6 +32,7 @@
<data name="Safety_HookingTurnedOff" xml:space="preserve"><value>Hooking đã được tắt cho game này; trang của game ghi rõ đã phát hiện gì.</value></data>
<data name="Safety_Unhooked_Format" xml:space="preserve"><value>Đã dừng thu thập: phát hiện {0} khi game đang chạy, và FrameLedger đã gỡ hook.</value></data>
<data name="Safety_Unhooked_MachineWide_Format" xml:space="preserve"><value>Đã dừng thu thập: {0} khởi động trên máy này khi game đang chạy ({1}) — một driver hoặc service, có thể thuộc về game hay chương trình khác — và FrameLedger đã gỡ hook. Phiên sau của game sẽ được đo lại khi nó không còn chạy.</value></data>
<data name="Safety_Unhooked_Unnamed_Format" xml:space="preserve"><value>Đã dừng thu thập khi game đang chạy — {0} — và FrameLedger đã gỡ hook.</value></data>
<data name="Safety_Refused_TargetUnreadable" xml:space="preserve"><value>Game đang chạy, nhưng Windows không cho FrameLedger mở tiến trình của nó: tiến trình được driver anti-cheat bảo vệ, hoặc game chạy với quyền quản trị còn FrameLedger thì không. Không có gì được inject và lần chạy này không được đo. FrameLedger sẽ không tìm cách vượt qua cơ chế bảo vệ của sản phẩm khác. Nếu chính game chạy với quyền quản trị, chế độ quản trị của agent trong Cài đặt cho phép FrameLedger mở nó; tiến trình được bảo vệ vẫn đóng.</value></data>
<data name="Safety_Exception_Title_Format" xml:space="preserve"><value>Tạo ngoại lệ user-mode cho {0}?</value></data>
<data name="Safety_Exception_Intro_Format" xml:space="preserve"><value>FrameLedger đã phát hiện {0} trong game này ({1}) và đã tắt hooking cho nó. Hộp thoại này hỏi bạn có muốn tạo ngoại lệ cho riêng game này không. Nó không khuyến nghị lựa chọn nào.</value></data>
+47 -27
View File
@@ -22,40 +22,60 @@ target_compile_features(FrameLedger.Shm INTERFACE cxx_std_20)
#
# KNOWN LIMIT, stated rather than discovered: this runs at CONFIGURE time, so the
# `-dirty` suffix reflects the tree when CMake last ran, not when the DLL was
# last compiled. For a released build that is exact — CI configures and builds
# once from a clean checkout. For a developer editing between configures it is
# approximate, and the field is a version-skew signal rather than a provenance
# guarantee. Making it exact means re-running git on every build, which is a cost
# on every incremental compile for a value only the attach handshake reads.
execute_process(
COMMAND git describe --always --dirty --abbrev=12
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
OUTPUT_VARIABLE FL_BUILD_ID_RAW
OUTPUT_STRIP_TRAILING_WHITESPACE
ERROR_QUIET
)
if(NOT FL_BUILD_ID_RAW)
set(FL_BUILD_ID_RAW "unknown")
endif()
# buildId is char[32] and the guard side compares the whole array, so a value
# that would be truncated must be caught here rather than becoming a permanent
# mismatch nobody can explain.
string(LENGTH "${FL_BUILD_ID_RAW}" FL_BUILD_ID_LEN)
# AFTER THE FIRST TAG the long form stopped fitting on a developer's machine: `v0.1.0-beta.2-2-gd3e74988a7bc-dirty`
# is 35 characters, so every local configure with an uncommitted change failed here and the documented workaround
# was "commit before you build" (measured 2026-09-17, again 2026-09-21). The id is a version-skew signal, not a
# provenance guarantee (above), so the fallback spends fewer characters on the same facts: an 8-digit abbreviation
# and `+` for dirty. A released build is a clean checkout AT a tag and never reaches this branch. Still too long
# after that is still fatal, for the reason the check exists.
if(FL_BUILD_ID_LEN GREATER 31)
# last compiled. This comment said that for a released build it was exact, "CI
# configures and builds once from a clean checkout", and it was not (corrected
# 2026-10-07, beta.18): release.yml writes the release date into the tracked
# legal/*.md before the gate configures, and every release until beta.18 shipped
# "<tag>-dirty" — the owner's Dashboard read "Overlay build v0.1.0-beta.17-dirty",
# and the run's log "FL_BUILD_ID = v0.1.0-beta.17-dirty" two lines after
# "RELEASE_DATE = 2026-10-07 in 3 file(s)". A release now hands the id in (below). For a
# developer editing between configures it is approximate, and the field is a
# version-skew signal rather than a provenance guarantee. Making it exact means
# re-running git on every build, which is a cost on every incremental compile for a
# value only the attach handshake reads.
#
# A RELEASE HANDS THE ID IN: release.yml reads describe from the clean checkout, before
# anything edits a tracked file, and passes it as the environment's FL_BUILD_ID; it is
# taken as given here, and tools/buildid-check.ps1 then reads it back out of the
# published binaries. It goes into a C string literal, so it must be what describe can
# print and nothing a literal would have to escape.
if(DEFINED ENV{FL_BUILD_ID} AND NOT "$ENV{FL_BUILD_ID}" STREQUAL "")
set(FL_BUILD_ID_RAW "$ENV{FL_BUILD_ID}")
if(NOT FL_BUILD_ID_RAW MATCHES "^[0-9A-Za-z._+-]+$")
message(FATAL_ERROR "FL_BUILD_ID '${FL_BUILD_ID_RAW}' from the environment holds a character no build id has (0-9 A-Z a-z . _ + -).")
endif()
string(LENGTH "${FL_BUILD_ID_RAW}" FL_BUILD_ID_LEN)
else()
execute_process(
COMMAND git describe --always --dirty=+ --abbrev=8
COMMAND git describe --always --dirty --abbrev=12
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
OUTPUT_VARIABLE FL_BUILD_ID_RAW
OUTPUT_STRIP_TRAILING_WHITESPACE
ERROR_QUIET
)
if(NOT FL_BUILD_ID_RAW)
set(FL_BUILD_ID_RAW "unknown")
endif()
# buildId is char[32] and the guard side compares the whole array, so a value
# that would be truncated must be caught here rather than becoming a permanent
# mismatch nobody can explain.
string(LENGTH "${FL_BUILD_ID_RAW}" FL_BUILD_ID_LEN)
# AFTER THE FIRST TAG the long form stopped fitting on a developer's machine: `v0.1.0-beta.2-2-gd3e74988a7bc-dirty`
# is 35 characters, so every local configure with an uncommitted change failed here and the documented workaround
# was "commit before you build" (measured 2026-09-17, again 2026-09-21). The id is a version-skew signal, not a
# provenance guarantee (above), so the fallback spends fewer characters on the same facts: an 8-digit abbreviation
# and `+` for dirty. A released build hands its id in (above) and never reaches this branch. Still too long
# after that is still fatal, for the reason the check exists.
if(FL_BUILD_ID_LEN GREATER 31)
execute_process(
COMMAND git describe --always --dirty=+ --abbrev=8
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
OUTPUT_VARIABLE FL_BUILD_ID_RAW
OUTPUT_STRIP_TRAILING_WHITESPACE
ERROR_QUIET
)
string(LENGTH "${FL_BUILD_ID_RAW}" FL_BUILD_ID_LEN)
endif()
endif()
if(FL_BUILD_ID_LEN GREATER 31)
message(FATAL_ERROR
@@ -185,6 +185,24 @@ public sealed class AccessibilityTests
wrapped.Should().BeEmpty("a page without ScrollViewer.CanContentScroll=\"False\" is wrapped in WPF UI's scroller, and its own root swallows the wheel");
}
/// <summary>
/// beta.18 (the owner's screenshots of beta.17 in the dark theme: every page's title near-black on the dark window). A
/// page is shown in WPF UI's <c>NavigationViewContentPresenter</c>, a <c>Frame</c>, and a Frame sets
/// <c>InheritanceBehavior.SkipToAppNow</c>: the window's text colour never reaches the page, and a text with no colour
/// of its own is WPF UI's TextBlock default, black. Every page gives its texts the theme's colour itself.
/// </summary>
[Fact]
public void EveryPageSetsItsOwnTextColour()
{
List<string> pages = [.. AppXaml().Where(static x => string.Equals(x.Xaml.Root!.Name.LocalName, "Page", StringComparison.Ordinal)).Select(static x => x.File)];
List<string> uncoloured = [.. AppXaml().Where(static x => string.Equals(x.Xaml.Root!.Name.LocalName, "Page", StringComparison.Ordinal)
&& !string.Equals(x.Xaml.Root.Attribute("Foreground")?.Value, "{DynamicResource TextFillColorPrimaryBrush}", StringComparison.Ordinal))
.Select(static x => x.File)];
pages.Should().HaveCountGreaterThanOrEqualTo(6);
string.Join(", ", uncoloured).Should().BeEmpty("a Frame passes no text colour into a page: each sets Foreground=\"{DynamicResource TextFillColorPrimaryBrush}\" (16_WPFUI_SYNTAX §Gotchas)");
}
/// <summary>
/// A stock <c>ScrollViewer</c> takes every wheel, even with nothing left to scroll; inside a dialog that scrolls, the wheel
/// then stops at it. WPF UI's <c>PassiveScrollViewer</c> hands the wheel on at its ends (beta.14).
+5 -10
View File
@@ -23,13 +23,6 @@ public sealed class ContrastTests
{
private static readonly string[] _paletteAppearances = ["Info", "Caution", "Danger", "Success"];
/// <summary>
/// Windows' default accent. The accent brushes are not in the theme dictionaries: `ApplicationThemeManager.Apply(…,
/// updateAccent: true)` derives them from the system accent at start-up (`MainWindow`), so the test derives them the
/// same way from a fixed colour and measures WPF UI's own on-accent text against them.
/// </summary>
private static readonly Color _defaultAccent = Color.FromRgb(0x00, 0x78, 0xD4);
[Fact]
public void NoBadgeUsesAPaletteAppearance()
{
@@ -143,10 +136,12 @@ public sealed class ContrastTests
[InlineData(ApplicationTheme.Light)]
public async Task EveryPillPairMeetsAAInBothThemes(ApplicationTheme theme)
{
Dictionary<string, double> ratios = await PagesLoadTests.OnStaAsync(() =>
// The accent brushes are not in the theme dictionaries: the App derives them from the system accent at each theme
// switch, and Visuals.UnderTheme derives them the same way from Windows' default accent. Until 2026-10-07 this
// passed systemAccentColor: true, which reads the machine's own accent palette wherever Windows answers.
Dictionary<string, double> ratios = await PagesLoadTests.OnStaAsync(() => Visuals.UnderTheme(theme, () =>
{
var themed = new ThemesDictionary { Theme = theme };
ApplicationAccentColorManager.Apply(_defaultAccent, theme, systemGlassColor: false, systemAccentColor: true);
Color window = Wcag.Resolve(themed, "ApplicationBackgroundColor");
Color card = Wcag.Over(Wcag.Resolve(themed, "CardBackgroundFillColorDefault"), window);
Color pillOff = Wcag.Over(Wcag.Resolve(themed, "ControlFillColorDefault"), card);
@@ -159,7 +154,7 @@ public sealed class ContrastTests
["qualifier warning: primary text on caution"] = Wcag.Ratio(Wcag.Over(Wcag.Resolve(themed, "TextFillColorPrimary"), caution), caution),
["the Info badge, for the record"] = Wcag.Ratio(Wcag.Over(Wcag.Resolve(themed, "TextFillColorPrimary"), PaletteLightBlue()), PaletteLightBlue()),
};
});
}));
using (new FluentAssertions.Execution.AssertionScope(theme.ToString()))
{
Loaded 100 of 147 files, more files were not shown because too many files have changed in this diff. Show more