Skip to content

docs: regenerate WALKTHROUGH.md and drop a stale Setup comment - #77

Merged
philoserf merged 1 commit into
mainfrom
docs/regenerate-walkthrough
Sep 16, 2026
Merged

philoserf merged 1 commit into
mainfrom
docs/regenerate-walkthrough

Conversation

@philoserf

Copy link
Copy Markdown
Owner

What

WALKTHROUGH.md had drifted badly since #67–#74 and is rebuilt from scratch. The old document described:

  • loadScenarios() fetching public/scenarios/*.json — those files are gone; scenarios are typed constants in src/scenarios.ts
  • src/screens/letterhead.ts — now src/screens/fragments.ts
  • no src/paragraph.ts at all — the paragraph machine was extracted in refactor: extract the paragraph machine and test it #67

and pinned its snippets with sed -n 'N,Mp' line ranges into a play.ts that has since been rewritten. This is the failure mode the document exists to prevent: showboat verify re-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, planRoll showing 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 through toMarkdown. 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 why advance forces the flourish decision before the Language roll.

Code change

Removes a seven-line orphaned JSDoc block above cardId in src/screens/setup.ts. It was 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.

Findings filed

Both are on the Workbench board (Backlog / P1 / S / 2 and Backlog / P2 / XS / 1).

Checks

bun run check:ci green — Biome clean, tsc --noEmit clean, 82 tests pass. uvx showboat verify WALKTHROUGH.md exits 0, re-confirmed after check:ci to make sure Biome does not touch the captured output blocks.

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
@philoserf
philoserf merged commit e7386b0 into main Sep 16, 2026
3 checks passed
@philoserf
philoserf deleted the docs/regenerate-walkthrough branch September 16, 2026 12:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant