docs: correct the two places the user-facing docs are wrong (#206, #207) - #238
Merged
Conversation
#206 -- WRONG, NOT MERELY STALE docs/USER_GUIDE.md described the screensaver as "a bouncing logo". There are 30. README.md's feature list carried the same line. The guide's shortcut table also omitted V, + and - entirely, so an operator reading it could not discover the screensaver controls at all -- which is how the omission was noticed: the owner had to ask for those keys rather than read them. - README feature line rewritten: 30 GPU-rendered savers, random pick on activation, 10-minute rotation, weather and Art-Net off by default. - User guide's Screensaver section rewritten, including that each saver also looks different every activation because its choices are clock-seeded. - V, + and - added to the shortcut table. - All 30 listed in rotation order, which is the order + and - step through. - The split-flap board's status explained: it is the no-signal display, appears immediately rather than after five minutes, and cannot be reached by stepping. That distinction was documented nowhere a user would look. - Weather and Art-Net covered at an operator's level, both flagged off by default, with the detail left in README rather than duplicated. The list came from registry.js, not from the issue -- the issue says explicitly to check against code because the issue will itself age. Cross-checked against structure-baselines.js, the other generated list, as an independent count. #207 -- TWO WORKFLOWS DOCUMENTED NOWHERE .claude/CLAUDE.md's command block omitted npm run bench and npm run baselines, so the only way to find them was to read package.json. - Both added, with the baselines caveat stated where someone will hit it: it rewrites all 30 entries, so a single-saver redesign should edit one line by hand. - The SwiftShader-versus-real-GPU contrast between shadercheck and bench spelled out, including that getting it backwards is what led several PRs to claim frame cost could not be measured headlessly when it could. - Preview harness keys documented in prose rather than only in the HUD legend. Verified against the key handler rather than copied from the issue, which turned up four the issue omitted -- R, the arrow keys, H and F -- and one genuine collision worth a warning: + and - step savers in the shipped app but adjust bloom in the harness. THE DOCUMENTED SELECTOR EXAMPLE DID NOT WORK CLAUDE.md's one worked example of the preview flag was white-particles, and the matcher stripped whitespace but not hyphens, so it silently fell through to the first saver. Fixed in the matcher rather than in the prose, because white-particles is what a reader will type -- it matches the file on disk. Verified end to end: #white-particles now logs "Started: White Particles" with no fallback warning. A TEST, BECAUSE THE LIST HAS ALREADY GONE STALE TWICE #206 suggests generating the list from registry.js. test/docs-screensaver-list.test.js is the cheaper half: it resolves the registry order from source, compares it to the marked block in the guide, and also checks the stated count, the absence of "bouncing logo" in both files, the presence of the V/+/- rows, and that the split-flap board is not in the rotation. Fault-injected both ways -- dropping a saver from the list and reintroducing the bouncing-logo line each fail it.
This was referenced Aug 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #206 and #207.
#206 — wrong, not merely stale
docs/USER_GUIDE.mddescribed the screensaver as "a bouncing logo". There are 30.README.md's feature list carried the same line. The guide's shortcut table also omittedV,+and-entirely, so an operator reading it could not discover the screensavercontrols at all — which is exactly how the omission surfaced: the owner had to ask for
those keys rather than read them.
every activation because its choices are clock-seeded.
V,+and-added to the shortcut table.+and-step through.immediately rather than after five minutes, and cannot be reached by stepping. That
distinction was documented nowhere a user would look.
left in README rather than duplicated.
The list came from
registry.js, not from the issue — the issue says explicitly tocheck against code because the issue will itself age. Cross-checked against
structure-baselines.js, the other generated list, as an independent count.#207 — two workflows documented nowhere
.claude/CLAUDE.md's command block omittednpm run benchandnpm run baselines, so theonly way to find them was to read
package.json.30 entries, so a single-saver redesign should edit one line by hand.
shadercheckandbenchspelled out —including that getting it backwards is what led several PRs to claim frame cost could not be
measured headlessly when it could.
copied from the issue, which turned up four the issue omitted —
R, the arrow keys,Hand
F— and one genuine collision worth a warning:+/-step savers in the shipped appbut adjust bloom in the harness.
The documented selector example did not work
CLAUDE.md's one worked example of the preview flag waswhite-particles, and the matcherstripped whitespace but not hyphens, so it silently fell through to the first saver. The
worst kind of doc error — it teaches the reader the feature is broken.
Fixed in the matcher, not the prose, because
white-particlesis what a reader will typeand it matches the file on disk. All four forms now resolve:
white-particles,whiteparticles,White Particles,white_particles.Verified end to end rather than from the regex: navigating to
#white-particleslogs[Screensaver] Started: White Particleswith no fallback warning.A test, because the list has already gone stale twice
#206 suggests generating the list from
registry.js.test/docs-screensaver-list.test.jsisthe cheaper half — it needs nobody to remember to run a script, and it fails in CI the moment
prose and code disagree. It resolves the registry order from source and checks:
guide claims it is the
+/-order);Vand+/-rows are present;Fault-injected both ways — dropping a saver from the list, and reintroducing the
bouncing-logo line — and each fails it.
Verification
main(3201dbd).npm run lintclean.npm test— 412 passed (407 + 5 new).Not verified / left open
this PR, and its last part — chore: TODO.md is stale and superseded by issues — delete it or mark it historical #208,
TODO.mdbeing stale — is untouched.which is what the issue asked for; one-line descriptions of each would be a larger writing
job and nobody has asked for them.
self-checking, which addresses the staleness risk without adding a build step, but it does
mean the list is still updated by hand.