docs: regenerate WALKTHROUGH.md and drop a stale Setup comment - #77
Merged
Merged
Conversation
WALKTHROUGH.md had drifted badly since #67-#74. It documented a `loadScenarios()` that fetched `public/scenarios/*.json` (now typed constants in `src/scenarios.ts`), a `src/screens/letterhead.ts` (now `fragments.ts`), and had no mention of `src/paragraph.ts` at all. Its snippets were pinned with `sed -n 'N,Mp'` line ranges into a `play.ts` that has since been rewritten, so `showboat verify` kept passing while the prose described code that no longer existed. Rebuilt from scratch in first-run execution order: page load, boot and hydration, the store, the domain types, the content constants, Setup, the paragraph machine, dice and rules, the Play screen, then scoring and export. Every snippet is now anchored to content rather than line numbers, so a command keeps pointing at the code it quotes. Six blocks execute the game layer instead of quoting it -- the paragraph machine driven through all seven phases, its wrong-phase guards, the character-gated dice bonus on The Archduke, the full scoring matrix, the tier boundaries, and a complete five-paragraph session through `toMarkdown`. Also removes an orphaned JSDoc block above `cardId`: a pre-#74 copy of `renderChoiceStep`'s comment asserting "the `aria-label` below is the name", contradicted by both the live comment eight lines below it and by the code, which uses `aria-labelledby`. Filed while tracing: #75 (a new `PhaseName` variant type-checks clean and renders nothing in either play-screen switch) and #76 (the mount error boundary covers only the first render). Co-Authored-By: Claude
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.
What
WALKTHROUGH.mdhad drifted badly since #67–#74 and is rebuilt from scratch. The old document described:loadScenarios()fetchingpublic/scenarios/*.json— those files are gone; scenarios are typed constants insrc/scenarios.tssrc/screens/letterhead.ts— nowsrc/screens/fragments.tssrc/paragraph.tsat all — the paragraph machine was extracted in refactor: extract the paragraph machine and test it #67and pinned its snippets with
sed -n 'N,Mp'line ranges into aplay.tsthat has since been rewritten. This is the failure mode the document exists to prevent:showboat verifyre-runs the code blocks but never reads the surrounding prose, so it kept passing while the narrative described code that no longer existed.How it is built now
First-run execution order: page load → boot and hydration → the store → the domain types → the content constants → Setup → the paragraph machine → dice and rules → the Play screen → scoring and export.
Every snippet is anchored to content (
sed -n '/^export function advance/,/^}$/p') rather than to line numbers, so a command keeps pointing at the code it quotes when unrelated edits move it.Six blocks execute the game layer rather than quoting it — the paragraph machine driven through all seven phases, its wrong-phase guards returning the identical object,
planRollshowing a Courtier collecting The Archduke's gated Heart die where a Monk does not, the complete scoring matrix, the tier boundaries, and a full five-paragraph session throughtoMarkdown. That last one makes the whole ruleset visible in one output, including that a flourish which holds on an inferior word scores −1 — worse than not attempting one — which is whyadvanceforces the flourish decision before the Language roll.Code change
Removes a seven-line orphaned JSDoc block above
cardIdinsrc/screens/setup.ts. It was a pre-#74 copy ofrenderChoiceStep's comment asserting "thearia-labelbelow is the name", contradicted by both the live comment eight lines below it and by the code, which usesaria-labelledby.Findings filed
PhaseNamevariant type-checks clean;STEP_INDEXis the only compile-time gate and both phase switches inplay.tsfall through to an empty container. Verified by compiling both ways.try/catchis commented as covering "any unrecoverable state" but wraps only the first render.Both are on the Workbench board (Backlog / P1 / S / 2 and Backlog / P2 / XS / 1).
Checks
bun run check:cigreen — Biome clean,tsc --noEmitclean, 82 tests pass.uvx showboat verify WALKTHROUGH.mdexits 0, re-confirmed aftercheck:cito make sure Biome does not touch the captured output blocks.