From ba33e4e5bb46fbabeb5bd1109a37b57e1ddd25f6 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:38:02 +0700
Subject: [PATCH 035/110] Keep ending outside scene progress
---
src/lib/reader/track.js | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/src/lib/reader/track.js b/src/lib/reader/track.js
index 00ad470..41c27e7 100644
--- a/src/lib/reader/track.js
+++ b/src/lib/reader/track.js
@@ -149,6 +149,11 @@ export function segmentsOf(track, book) {
const out = [];
const index = new Map();
for (const stop of track) {
+ /* The ending is its own experience. It belongs after the final scene,
+ but it is not another line inside that scene and must not make the
+ progress display say, for example, “12 of 13” on the last line. */
+ if (stop.kind === 'end') continue;
+
if (!index.has(stop.unit)) {
const unit = unitLike(book, stop.unit);
const seg = {
@@ -173,7 +178,7 @@ export function segmentsOf(track, book) {
} else if (stop.kind === 'say') {
seg.said += 1;
if (!seg.plate && stop.plate) seg.plate = stop.plate;
- } else if (stop.kind !== 'end') {
+ } else {
seg.asks += 1;
if (!seg.plate && stop.plate) seg.plate = stop.plate;
}
From 770b19fff8554c45502c4fd805b1b548f11d8eaf Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:38:09 +0700
Subject: [PATCH 036/110] Add CI for solo reader redesign
---
.github/workflows/solo-reader-ci.yml | 36 ++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
create mode 100644 .github/workflows/solo-reader-ci.yml
diff --git a/.github/workflows/solo-reader-ci.yml b/.github/workflows/solo-reader-ci.yml
new file mode 100644
index 0000000..6b314dc
--- /dev/null
+++ b/.github/workflows/solo-reader-ci.yml
@@ -0,0 +1,36 @@
+name: Solo reader CI
+
+on:
+ push:
+ branches:
+ - solo-reader-redesign
+ pull_request:
+ branches:
+ - main
+
+jobs:
+ verify:
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@v4
+
+ - name: Use Node 22
+ uses: actions/setup-node@v4
+ with:
+ node-version: 22
+ cache: npm
+
+ - name: Install dependencies
+ run: npm ci --ignore-scripts
+
+ - name: Typecheck
+ run: npm run typecheck
+
+ - name: Unit tests
+ run: npm test
+
+ - name: Production build
+ run: npm run build
From 4d523235b213915705145c802eda16b82a55b7da Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:40:19 +0700
Subject: [PATCH 037/110] Add exact Grok storyboard for Gift scene 2
---
docs/storyboards/GIFT-OF-THE-MAGI-S2.md | 282 ++++++++++++++++++++++++
1 file changed, 282 insertions(+)
create mode 100644 docs/storyboards/GIFT-OF-THE-MAGI-S2.md
diff --git a/docs/storyboards/GIFT-OF-THE-MAGI-S2.md b/docs/storyboards/GIFT-OF-THE-MAGI-S2.md
new file mode 100644
index 0000000..60f9e1e
--- /dev/null
+++ b/docs/storyboards/GIFT-OF-THE-MAGI-S2.md
@@ -0,0 +1,282 @@
+# The Gift of the Magi — Scene 2 production storyboard
+
+## Scene
+
+**Unit:** `s2`
+**Title:** The Eight-Dollar Flat
+**Location:** Della and Jim's apartment and the vestibule below
+**Narration clips:** `n_s2_0.mp3` through `n_s2_17.mp3`
+
+Scene 2 is not a reset. It continues directly from the approved apartment anchor and Della established in Scene 1. The visual purpose is to let the reader inspect the life that produced the $1.87 without turning poverty into a museum display.
+
+## Continuity rules
+
+Reuse the canonical Della, apartment geometry, furniture, winter daylight, painterly rendering, 16:9 framing, and subtitle-safe lower band from Scene 1.
+
+Add one new continuity family:
+
+- **Vestibule anchor:** narrow shared entrance below the apartment; period-appropriate worn walls; stubborn letter-box; old electric bell button; modest name card for James Dillingham Young. It should feel cheaply maintained, not abandoned.
+- **Jim:** young adult man, about twenty-two, lean, serious face softened around Della; period working man's clothes; overcoat visibly worn but respectable; no gloves. Once approved, this becomes the canonical Jim reference for later scenes.
+
+As before: no generated captions, no modern objects, no lip sync, no invented dialogue, no dramatic cuts inside a single line. Motion starts immediately.
+
+---
+
+## Line-by-line production backlog
+
+### S2-00 — `n_s2_0` — 4.184 s
+
+**Text:** “While the mistress of the home is gradually subsiding from the first stage to the second,”
+
+**Start keyframe:** Continue from Scene 1's couch continuity. Della sits up slowly on the shabby couch, wiping the last tears from her face. Her posture is tired rather than theatrical.
+
+**End keyframe:** Same shot; Della has steadied herself, hands resting in her lap, breathing calmer.
+
+**Shot:** medium three-quarter view.
+**Camera:** slow pull back that begins immediately.
+**Action:** recover from crying.
+**Emotion:** sadness settling into ordinary endurance.
+
+### S2-01 — `n_s2_1` — 1.294 s
+
+**Text:** “take a look at the home.”
+
+**Start keyframe:** The camera has pulled wide enough that Della is now only one element inside the room: couch, table, narrow window, worn rug, sparse furniture.
+
+**End keyframe:** Not required.
+
+**Shot:** wide establishing interior.
+**Camera:** continue the gentle pull back from S2-00.
+**Action:** none.
+**Purpose:** hand visual attention from Della to the apartment itself.
+
+### S2-02 — `n_s2_2` — 2.218 s
+
+**Text:** “A furnished flat at $8 per week.”
+
+**Start keyframe:** Wide apartment view emphasizing that the room is furnished but cheaply: small table, worn couch, basic chairs, narrow window, few possessions. Do not show a written $8 sign.
+
+**End keyframe:** Optional slightly tighter composition on the furniture wear and cramped scale.
+
+**Shot:** wide interior.
+**Camera:** slow lateral drift.
+**Action:** none.
+**Emotion:** matter-of-fact scarcity.
+
+### S2-03 — `n_s2_3` — 2.140 s
+
+**Text:** “It did not exactly beggar description,”
+
+**Start keyframe:** Detail family from the apartment: patched couch fabric, worn red carpet, simple table edge, perhaps a repaired chair. Keep everything clean enough to show care despite lack of money.
+
+**End keyframe:** Not required.
+
+**Shot:** environmental detail.
+**Camera:** restrained pan across two or three worn surfaces.
+**Tone:** the narrator is joking; the image should stay sincere.
+
+### S2-04 — `n_s2_4` — 3.403 s
+
+**Text:** “but it certainly had that word on the lookout for the mendicancy squad.”
+
+**Start keyframe:** Same humble room, wider again, with Della small in frame. Nothing should suggest literal beggars arriving; “mendicancy squad” is comic verbal exaggeration.
+
+**End keyframe:** Della rises from the couch and crosses toward the table/window, returning to ordinary life.
+
+**Shot:** wide interior.
+**Camera:** locked or very slow push.
+**Action:** Della gets back up.
+**Emotion:** dignity inside hardship.
+**Do not:** visualize a “mendicancy squad,” police, or beggars.
+
+### S2-05 — `n_s2_5` — 3.664 s
+
+**Text:** “In the vestibule below was a letter-box into which no letter would go,”
+
+**Start keyframe:** Establish the vestibule anchor. Close-medium view of an old wall-mounted letter-box with a warped or jammed slot. Staircase rises toward the apartment in background.
+
+**End keyframe:** A period envelope approaches the slot but cannot fit because the mechanism/slot is plainly broken; use a hand only if needed, not a new named character.
+
+**Shot:** environmental close-up.
+**Camera:** tiny push toward letter-box.
+**Action:** simple failed attempt at the slot.
+**Emotion:** shabby inconvenience with dry humor.
+
+### S2-06 — `n_s2_6` — 3.742 s
+
+**Text:** “and an electric button from which no mortal finger could coax a ring.”
+
+**Start keyframe:** Same vestibule wall. Period electric bell button beside the entrance, visibly old and loose.
+
+**End keyframe:** A finger presses it; nothing changes. Avoid sparks or comic malfunction.
+
+**Shot:** close-up.
+**Camera:** locked.
+**Action:** one press.
+**Emotion:** resigned absurdity.
+
+### S2-07 — `n_s2_7` — 3.195 s
+
+**Text:** “Also appertaining thereunto was a card bearing the name”
+
+**Start keyframe:** The camera moves from bell button toward a small worn name-card holder. The card is present but do not depend on AI-generated legible lettering.
+
+**End keyframe:** Tighter frame on the card holder; leave the card area visually simple so the app can later overlay or composite exact text if desired.
+
+**Shot:** close environmental detail.
+**Camera:** gentle slide.
+**Action:** none.
+**Important:** do not trust generated typography.
+
+### S2-08 — `n_s2_8` — 1.737 s
+
+**Text:** “Mr. James Dillingham Young.”
+
+**Start keyframe:** Reuse S2-07 end frame. If the production pipeline supports post-composited text, this is where the exact name can appear as a clean overlay asset. Otherwise keep the physical card suggestive but unreadable and let the subtitle carry the words.
+
+**End keyframe:** None.
+
+**Shot:** card close-up.
+**Camera:** locked.
+**Purpose:** let the grandness of the name sit against the shabby vestibule.
+
+### S2-09 — `n_s2_9` — 1.984 s
+
+**Text:** “The ‘Dillingham’ had been flung to the breeze”
+
+**Start keyframe:** Same name-card holder, but visually imply the middle name is fading or the card is being modestly altered — for example a small paper strip or worn lettering area. Do not animate literal letters flying away.
+
+**End keyframe:** Optional close detail of the simplified card.
+
+**Shot:** detail.
+**Camera:** slight pull back.
+**Tone:** narrator joke about shrinking status.
+
+### S2-10 — `n_s2_10` — 2.158 s
+
+**Text:** “during a former period of prosperity”
+
+**Start keyframe:** Brief warm-toned memory insert of Jim in the same flat earlier, better dressed and carrying himself with a little more financial ease; furniture should be recognizably the same so this is not mistaken for a different household.
+
+**End keyframe:** Jim hangs or straightens the proud long name card near the vestibule/door.
+
+**Shot:** medium memory image.
+**Camera:** gentle push.
+**Action:** straighten the name card.
+**Emotion:** modest pride, not wealth.
+
+### S2-11 — `n_s2_11` — 3.013 s
+
+**Text:** “when its possessor was being paid $30 per week.”
+
+**Start keyframe:** Memory family. Jim at a small desk/work counter receiving a pay envelope or counting a modest week's wages. Do not show a huge cash pile or readable $30 text.
+
+**End keyframe:** He slips the envelope into his coat with quiet satisfaction.
+
+**Shot:** medium detail.
+**Camera:** locked.
+**Action:** receive/store pay envelope.
+**Emotion:** relative security, not prosperity in the modern sense.
+
+### S2-12 — `n_s2_12` — 3.312 s
+
+**Text:** “Now, when the income was shrunk to $20, though,”
+
+**Start keyframe:** Return to present-day cool winter light. Canonical Jim at the apartment table with a thinner pay envelope and a few bills/coins, face serious.
+
+**End keyframe:** Jim looks from the small amount toward household expenses on the table; no readable budget text is necessary.
+
+**Shot:** medium.
+**Camera:** slight push toward his hands.
+**Action:** compare money with expenses.
+**Emotion:** quiet pressure.
+
+### S2-13 — `n_s2_13` — 4.028 s
+
+**Text:** “they were thinking seriously of contracting to a modest and unassuming D.”
+
+**Start keyframe:** Back in vestibule at the name card. Jim and Della stand together looking at it with faint, private amusement despite the problem.
+
+**End keyframe:** One of them lightly touches/adjusts the card as if considering shortening the grand middle name.
+
+**Shot:** medium two-shot with card visible.
+**Camera:** gentle push.
+**Action:** shared glance and small card gesture.
+**Emotion:** humor shared inside financial strain.
+**Do not:** make this a broad joke or have them physically tear letters off.
+
+### S2-14 — `n_s2_14` — 4.132 s
+
+**Text:** “But whenever Mr. James Dillingham Young came home and reached his flat above”
+
+**Start keyframe:** Establish canonical Jim arriving home in present day. He climbs the final apartment stairs in his worn overcoat, tired but composed. No gloves.
+
+**End keyframe:** Jim reaches the apartment door; his hand begins to open it.
+
+**Shot:** medium tracking/three-quarter stair view.
+**Camera:** gentle rise/follow.
+**Action:** climb final steps and reach door.
+**Emotion:** end-of-workday fatigue, anticipation of home.
+
+### S2-15 — `n_s2_15` — 3.872 s
+
+**Text:** “he was called ‘Jim’ and greatly hugged by Mrs. James Dillingham Young,”
+
+**Start keyframe:** Jim has just entered. Della moves toward him immediately, face brighter than in Scene 1.
+
+**End keyframe:** Warm, simple embrace near the doorway. Keep it affectionate and natural; no romance-poster posing.
+
+**Shot:** medium two-shot.
+**Camera:** slow push toward the embrace.
+**Action:** Della crosses one step and hugs Jim.
+**Emotion:** uncomplicated affection and relief.
+**Continuity:** This is the canonical normal-state Jim/Della relationship image for later emotional contrast.
+
+### S2-16 — `n_s2_16` — 2.010 s
+
+**Text:** “already introduced to you as Della.”
+
+**Start keyframe:** Reuse the embrace end frame, then let Della pull back just enough that her familiar face is visible.
+
+**End keyframe:** Della smiles up at Jim; Jim's expression softens.
+
+**Shot:** medium close two-shot.
+**Camera:** locked.
+**Action:** tiny separation after hug.
+**Emotion:** recognition and warmth.
+
+### S2-17 — `n_s2_17` — 1.437 s
+
+**Text:** “Which is all very good.”
+
+**Start keyframe:** Same doorway family. Della and Jim turn together into the small apartment, still close to each other.
+
+**End keyframe:** Optional wider frame of both moving into the shabby room, making the contrast explicit: the home is poor; their welcome is rich.
+
+**Shot:** medium-wide.
+**Camera:** gentle pull back.
+**Action:** enter the room together.
+**Emotion:** narrator's warm approval.
+
+---
+
+## Generation order
+
+1. Reuse Scene 1 apartment anchor; do not regenerate it.
+2. Make the vestibule anchor: letter-box, bell, name-card position, stairs.
+3. Approve canonical Jim in present-day clothes before S2-14 through S2-17.
+4. Generate S2-14 to S2-17 as one continuous arrival/hug family.
+5. Generate S2-05 to S2-09 as one vestibule-detail family.
+6. Generate S2-12 and S2-13 as present-day money/name-card family.
+7. Generate S2-10 and S2-11 as a warmer memory family, preserving Jim and apartment identity.
+8. Generate S2-00 to S2-04 last because they mostly reuse Scene 1 Della/apartment continuity.
+9. Only animate after still continuity passes inspection.
+
+## Acceptance tests specific to Scene 2
+
+- Jim is the same person in memory and present-day shots; only styling/lighting/economic context changes.
+- The vestibule geometry is stable across letter-box, bell, card and arrival shots.
+- No AI-generated lettering is relied on for meaning.
+- Poverty is conveyed through repair, scale, wear and missing conveniences, not dirt or caricature.
+- Della/Jim affection feels ordinary and established; it is not staged like a romantic climax.
+- The last four lines form one continuous arrival sequence with no camera-axis jumps.
From 5fc245103e7d216840848df386647835ac6c012d Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:41:39 +0700
Subject: [PATCH 038/110] Preserve CI typecheck diagnostics
---
.github/workflows/solo-reader-ci.yml | 20 +++++++++++++++++++-
1 file changed, 19 insertions(+), 1 deletion(-)
diff --git a/.github/workflows/solo-reader-ci.yml b/.github/workflows/solo-reader-ci.yml
index 6b314dc..5456674 100644
--- a/.github/workflows/solo-reader-ci.yml
+++ b/.github/workflows/solo-reader-ci.yml
@@ -27,7 +27,25 @@ jobs:
run: npm ci --ignore-scripts
- name: Typecheck
- run: npm run typecheck
+ id: typecheck
+ continue-on-error: true
+ shell: bash
+ run: |
+ set -o pipefail
+ npm run typecheck 2>&1 | tee ci-typecheck.log
+
+ - name: Preserve typecheck diagnostics
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: typecheck-diagnostics
+ path: ci-typecheck.log
+ if-no-files-found: error
+ retention-days: 7
+
+ - name: Stop after a failed typecheck
+ if: steps.typecheck.outcome == 'failure'
+ run: exit 1
- name: Unit tests
run: npm test
From 24cfe46dcb3c8c3f3136382ff254e00ebfb52478 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:42:23 +0700
Subject: [PATCH 039/110] Type the solo book and storyboard contract
---
src/lib/types.js | 171 +++++++++++++++++++++++++++++------------------
1 file changed, 105 insertions(+), 66 deletions(-)
diff --git a/src/lib/types.js b/src/lib/types.js
index 42edb17..f961d9d 100644
--- a/src/lib/types.js
+++ b/src/lib/types.js
@@ -2,9 +2,7 @@
* The shapes everything else agrees on.
*
* Written as JSDoc rather than TypeScript so the runtime stays plain
- * JavaScript, while `checkJs` still refuses a renamed field or a
- * changed argument. When a book format changes, the failure should be a
- * type error at build time, not a blank card in front of a class.
+ * JavaScript while `checkJs` still catches drift in the pack contract.
*
* @module types
*/
@@ -12,41 +10,39 @@
/**
* One glossed word, as the trainer carries it.
* @typedef {object} Word
- * @property {string} w the word as it appears in the text
- * @property {string} d its meaning, in the book's own words
- * @property {string} [unit] id of the scene it was met in
- * @property {number} [hits] consecutive right answers; 2 retires it
- * @property {number} [asked] how many times it has been put to the student
- * @property {boolean} [mine] true when the student looked it up themselves
+ * @property {string} w
+ * @property {string} d
+ * @property {string} [unit]
+ * @property {number} [hits]
+ * @property {number} [asked]
+ * @property {boolean} [mine]
*/
/**
- * One option on a question card.
+ * One option on a vocabulary question card.
* @typedef {object} Choice
- * @property {string} t the text shown
- * @property {boolean} ok whether choosing it is correct
+ * @property {string} t
+ * @property {boolean} ok
*/
/**
- * A question, ready to render. Exactly one of `options` or `answer` is
- * meaningful: spelling questions are typed, everything else is chosen.
* @typedef {object} Question
* @property {string} kind
* @property {Word} [item]
- * @property {Word[]} [items] matching rounds carry several
+ * @property {Word[]} [items]
* @property {string} [prompt]
* @property {string} [sub]
* @property {Choice[]} options
- * @property {string} [answer] spelling only
- * @property {string} [hint] spelling only
- * @property {string} [firstLetter] spelling only
- * @property {string[]} [words] matching only
- * @property {{t:string,w:string}[]} [meanings] matching only
- * @property {object} [set] odd-one-out only
+ * @property {string} [answer]
+ * @property {string} [hint]
+ * @property {string} [firstLetter]
+ * @property {string[]} [words]
+ * @property {{t:string,w:string}[]} [meanings]
+ * @property {object} [set]
*/
/**
- * Everything the engine needs to build a question.
+ * Everything the vocabulary engine needs to build a question.
* @typedef {object} Ctx
* @property {Book} book
* @property {Record
} swaps
@@ -57,50 +53,96 @@
* @typedef {object} Unit
* @property {string} id
* @property {string} title
- * @property {string} [act] the division of the story this belongs to
- * @property {string} [scene] key into the plate map; defaults to id
- * @property {string} [caption] one line about the picture — used as alt text
+ * @property {string} [act]
+ * @property {string} [scene]
+ * @property {string} [caption]
* @property {number} [num]
- * @property {string} [para] a plain-language summary of the scene
+ * @property {string} [para]
* @property {string[]} [stanzas]
- * @property {string[][]} [gloss] [word, meaning] pairs — the pairing is
- * enforced by validateBook at load time,
- * not by the type, because a JSON import
- * cannot be narrowed to a tuple
+ * @property {string[][]} [gloss]
* @property {{q:string,opts:string[],correct:number}[]} [mc]
*/
/**
- * A book package.
+ * One guide turn before or after a book.
*
- * `plates` maps a scene to its picture file. The art is content-addressed
- * — filenames are hashes — so without this map there is no way from a
- * scene to its image, and a missing entry must read as "no picture"
- * rather than as a guessed path that 404s.
+ * `clip: null` is meaningful: the text has been rewritten but its new
+ * recording has not been produced yet, so the UI must not play an older
+ * recording whose words no longer match.
*
- * The rest is what a book teaches with and what its characters say. It
- * is listed here rather than left off because a package that quietly
- * lacks `dialogue` should be a type error where it is read, not a
- * reading where nobody speaks and no one can say why.
+ * @typedef {object} FramingTurn
+ * @property {string} [who]
+ * @property {string} text
+ * @property {string} [state]
+ * @property {string|null} [clip]
+ */
+
+/**
+ * The production packet for one narrated line.
+ *
+ * The descriptive fields are intentionally part of runtime data. The
+ * same object drives the reader and serves as the exact brief for the
+ * image/video generation pipeline.
+ *
+ * @typedef {object} VisualPlan
+ * @property {string|null} [start] approved first key image
+ * @property {string|null} [end] optional controlled second key image
+ * @property {string|null} [clip] optional finished silent visual clip
+ * @property {string|null} [poster]
+ * @property {string} [alt]
+ * @property {string} [shot]
+ * @property {string} [camera]
+ * @property {string} [action]
+ * @property {string} [mood]
+ * @property {number} [duration] narration window in seconds
+ * @property {string} [status] production state such as todo/approved
+ */
+
+/** @typedef {Record>} Storyboard */
+
+/**
+ * One optional literary lens in Ambrose's Explore notes.
+ * @typedef {object} ExploreLens
+ * @property {string} title
+ * @property {string} text
+ * @property {string} [kicker]
+ * @property {string} [lookFor]
+ */
+
+/**
+ * @typedef {object} ExploreNotes
+ * @property {{title?:string,text:string}} [intro]
+ * @property {ExploreLens[]} [lenses]
+ * @property {Record} [units]
+ */
+
+/**
+ * A book package consumed by the solo reader.
+ *
+ * The active product contract is story text, media, vocabulary, optional
+ * framing, optional Explore notes, and optional storyboard production
+ * data. Legacy teaching/dialogue fields remain typed temporarily while
+ * old extracted packs are migrated, but the solo story track does not
+ * consult them.
*
* @typedef {object} Book
- * @property {{title:string,id?:string,source?:string}} meta
+ * @property {{title:string,id?:string,source?:string,author?:string,by?:string,kind?:string}} meta
* @property {Unit[]} units
* @property {Record} [swaps]
* @property {Record} [plates]
- * @property {{audio?:string, cues?:string}} [media] where this book's
- * recordings and cue file sit once built. Part of the pack rather
- * than of the extracted data: it depends on how the assets are laid
- * out, not on anything the author wrote. Relative, always — itch
- * serves from a nested path and a leading slash 404s everything.
- * @property {Record} [teaching] questions and prompts, by unit
- * @property {Record} [info] material that is not read aloud
+ * @property {Storyboard} [storyboard]
+ * @property {{audio?:string, cues?:string}} [media]
+ * @property {{source?:string,fetchedAt?:number}} [plugin]
+ * @property {ExploreNotes} [explore]
+ * @property {Record} [teaching] legacy extraction data
+ * @property {Record} [info]
* @property {Record} [recaps]
* @property {{members:Record}} [cast]
* @property {{name?:string, hello?:string, passIntro?:Record}} [guideVoice]
- * @property {any[]} [preshow]
+ * @property {FramingTurn[]} [preshow]
+ * @property {FramingTurn[]} [afterword]
* @property {Record} [wrenReactions]
- * @property {Record} [dialogue]
+ * @property {Record} [dialogue]
* @property {Record} [lineTranslations]
* @property {Record} [wordTranslations]
* @property {Record} [uiTranslations]
@@ -108,9 +150,7 @@
*/
/**
- * Somebody who speaks. A book pack can ship a different cast — or one
- * voice, or five — without the engine changing.
- *
+ * Somebody who speaks.
* @typedef {object} CastMember
* @property {string} id
* @property {string} name
@@ -118,25 +158,23 @@
* @property {string} [voice]
* @property {string} [side]
* @property {string} [blurb]
- * @property {string} [art] relative path, for the same reason the
- * plate paths are relative
+ * @property {string} [art]
*/
/**
- * One beat: a picture, a line, and the recording that speaks it.
+ * One narrated line: visual, literary text, recording and clickable words.
* @typedef {object} Beat
* @property {number} i
* @property {string} unit
* @property {string} line
* @property {string|null} clip
* @property {{id:string,src:string|null,alt:string}} plate
- * @property {Record} [gloss] the words this unit explains,
- * carried so a line knows its
- * own hard words
+ * @property {Record} [gloss]
+ * @property {VisualPlan|null} [visual]
*/
/**
- * A practice session. Every field is replaced, never edited.
+ * A vocabulary practice session.
* @typedef {object} Session
* @property {Word[]} queue
* @property {string|null} lastKind
@@ -149,12 +187,14 @@
*/
/**
- * One row of the gradebook.
+ * Legacy gradebook row. This type disappears with the classroom removal
+ * pass; keeping it until then prevents dormant old modules from silently
+ * breaking the integration branch before they are deleted together.
* @typedef {object} Row
- * @property {string} [file] the filename it arrived as, if any
- * @property {number} [pass] which reading (2 = quiz, 3 = written)
- * @property {number} [autoRight] automatically-marked items correct
- * @property {number} [autoTotal] automatically-marked items asked
+ * @property {string} [file]
+ * @property {number} [pass]
+ * @property {number} [autoRight]
+ * @property {number} [autoTotal]
* @property {string} cls
* @property {string} no
* @property {string} name
@@ -164,8 +204,7 @@
* @property {number|''} percentNum
* @property {number} minutes
* @property {string} when
- * @property {number|string} retried count, or '' when none — the CSV
- * wants an empty cell, not a zero
+ * @property {number|string} retried
* @property {number} [attempts]
* @property {number|''} [priorScore]
* @property {number|''} [priorPercent]
From 7e1cda75aebbcebe95f3a8089d00a633e6edc4a3 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:43:20 +0700
Subject: [PATCH 040/110] Type storyboard beat options explicitly
---
src/lib/reader/beats.js | 34 ++++++++++++++++++----------------
1 file changed, 18 insertions(+), 16 deletions(-)
diff --git a/src/lib/reader/beats.js b/src/lib/reader/beats.js
index 09de6bd..9775927 100644
--- a/src/lib/reader/beats.js
+++ b/src/lib/reader/beats.js
@@ -1,5 +1,14 @@
import { plainStanza, inlineGlosses } from '../book/validate.js';
+/**
+ * @typedef {object} BeatOptions
+ * @property {(id:string)=>boolean} [hasClip]
+ * @property {Record} [plates]
+ * @property {Record} [storyboard]
+ * @property {string} [base]
+ */
+
+/** @param {Partial|null|undefined} unit */
export function linesOf(unit) {
return (unit?.stanzas || [])
.flatMap((sz) => plainStanza(String(sz)).split('\n'))
@@ -7,6 +16,7 @@ export function linesOf(unit) {
.filter(Boolean);
}
+/** @param {Partial|null|undefined} unit */
export function glossOf(unit) {
/** @type {Record} */
const out = {};
@@ -39,23 +49,11 @@ function visualFor(storyboard, unit, sceneId, i) {
*
* A book may supply only a plate, a line-specific plate, or a full visual
* storyboard entry. Storyboard entries are intentionally descriptive as
- * well as playable so the same JSON can be handed to an art/video model:
+ * well as playable so the same JSON can be handed to an art/video model.
*
- * {
- * start: 'art/s1-0-a.webp',
- * end: 'art/s1-0-b.webp',
- * clip: 'video/s1-0.mp4',
- * shot: 'medium close-up',
- * camera: 'slow push toward Della',
- * action: 'she counts the last pennies twice',
- * mood: 'private worry, not melodrama',
- * duration: 6
- * }
- *
- * `start` is the canonical key image. `end` is optional but strongly
- * preferred when a generated clip needs controlled motion. `clip` is the
- * finished visual animation; when it is absent the reader displays the
- * key image instead.
+ * @param {Partial|null|undefined} unit
+ * @param {BeatOptions} [opts]
+ * @returns {import('../types.js').Beat[]}
*/
export function beatsOf(
unit,
@@ -97,6 +95,10 @@ export function beatsOf(
});
}
+/**
+ * @param {import('../types.js').Book|null|undefined} book
+ * @param {BeatOptions} [opts]
+ */
export function beatsOfBook(book, opts = {}) {
const merged = {
plates: book?.plates || {},
From eee4ecba9e546f5bdc73fe6c3654f46ea592c59a Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:43:38 +0700
Subject: [PATCH 041/110] Refocus book-context tests on solo reader
---
src/ui/useBook.test.jsx | 133 +++++-----------------------------------
1 file changed, 15 insertions(+), 118 deletions(-)
diff --git a/src/ui/useBook.test.jsx b/src/ui/useBook.test.jsx
index d6ec771..f185425 100644
--- a/src/ui/useBook.test.jsx
+++ b/src/ui/useBook.test.jsx
@@ -9,33 +9,22 @@ import { BookProvider, useBook } from './useBook.jsx';
import { linesOf } from '../lib/reader/beats.js';
import { resetCues } from './useCueTrack.js';
import Reader from './Reader.jsx';
-import Class from './Class.jsx';
/**
- * The seam where the book gets in.
+ * The seam where the book gets into the solo reader.
*
- * The book used to be an `import` at the top of `main.jsx`, and
- * everything that fell out of it — the id a student's work is filed
- * under, the folder the recordings are in, the line counts a translation
- * is checked against — was worked out once, when the file loaded. With
- * one book that is invisible. With two it is a data-loss bug: the second
- * book's answers get written under the first book's name, and nothing
- * anywhere says so.
- *
- * So these are the tests that could not have passed before. Every one of
- * them renders a book that is NOT the one the app ships with, and two of
- * them change the book while the screen is mounted — which is the case a
- * value captured at load can never survive.
+ * These tests deliberately use packs other than the bundled title. The
+ * provider must re-derive identity, media and line counts whenever the
+ * selected book changes; otherwise a Git-loaded book would inherit the
+ * previous title's audio paths or translation alignment.
*/
-/** A second title, so "follows the book" can mean something. */
const other = {
...book,
meta: { ...book.meta, id: 'other-book', title: 'Another Reading' },
media: { audio: 'other-audio/', cues: 'cues/other.vtt' },
};
-/** A third, shorter, so the derived counts have to be different. */
const shorter = {
...book,
meta: { ...book.meta, id: 'shorter-book' },
@@ -44,47 +33,36 @@ const shorter = {
beforeEach(() => {
localStorage.clear();
- /* The cue file is fetched once and cached at module scope, so a book
- read in one test would hand its timings to the next one. */
resetCues();
});
-/** The reading, mounted on whichever book it is handed. */
function reading(pack) {
return (
-
);
}
-/** Mounted, with the cue fetch allowed to settle before anything is asked. */
async function read(pack) {
- const r = render(reading(pack));
+ const result = render(reading(pack));
await act(async () => {});
- return r;
+ return result;
}
describe('the book is something the app is given', () => {
- it('is not the book the app ships with, so these tests mean something', () => {
- /* If the fixture were ever registered as a title, every assertion
- below would still pass and prove nothing. */
+ it('uses a fixture that is not the bundled title', () => {
expect(book.meta.id).not.toBe(defaultBook.meta.id);
expect(other.media.audio).not.toBe(defaultBook.media.audio);
});
- it('refuses to render a screen that has no book above it', () => {
- /* The router is built at module scope, so the provider has to wrap
- it rather than live inside it. Get that wrong and every screen
- reads a book nobody chose — which is worth an error the first
- time it is rendered, not a quiet default. */
+ it('refuses to render a consumer with no book above it', () => {
expect(() => render(
@@ -108,11 +86,7 @@ describe('what falls out of the book falls out of THIS book', () => {
expect(JSON.parse(screen.getByTestId('counts').textContent)).toEqual(want);
});
- it('counts them again when the book changes, rather than keeping the first answer', () => {
- /* The line counts are what refuse a translation that does not line
- up. Left over from a previous book they would refuse a good
- translation and wave a mismatched one through — silently, against
- the wrong sentences. */
+ it('recomputes those counts when the book changes', () => {
const { rerender } = render(
-
- );
-
- it('reads the outbox of the book on screen', () => {
- teacher();
- parked(book.meta.id, 2);
- parked(other.meta.id, 0);
-
- panel(book);
- expect(screen.getByText(/pieces of work handed in/i).textContent).toMatch(/\b2\b/);
- });
-
- it('reads a different book’s outbox from a different key', () => {
- teacher();
- parked(book.meta.id, 2);
- parked(other.meta.id, 0);
-
- panel(other);
- expect(screen.getByText(/Nothing is waiting/i)).toBeInTheDocument();
- });
-
- it('changes which key it reads when the book changes under it', () => {
- /* The whole point. A book id captured when the module loaded cannot
- do this, and the failure is silent: one book's work written under
- another book's name, discovered by a teacher who cannot find it. */
- teacher();
- parked(book.meta.id, 2);
- parked(other.meta.id, 0);
-
- const { rerender } = panel(other);
- expect(screen.getByText(/Nothing is waiting/i)).toBeInTheDocument();
-
- rerender(
-
-
- );
- expect(screen.queryByText(/Nothing is waiting/i)).toBeNull();
- expect(screen.getByText(/pieces of work handed in/i).textContent).toMatch(/\b2\b/);
- });
-});
From 9e6eb4840a4f84824668c8622850968a70f80da7 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:44:05 +0700
Subject: [PATCH 042/110] Type legacy track options during migration
---
src/lib/reader/track.js | 8 +++++---
1 file changed, 5 insertions(+), 3 deletions(-)
diff --git a/src/lib/reader/track.js b/src/lib/reader/track.js
index 41c27e7..b21bc7c 100644
--- a/src/lib/reader/track.js
+++ b/src/lib/reader/track.js
@@ -60,6 +60,11 @@ export function storyTrack(book, opts = {}) {
/**
* Legacy three-pass track retained while the classroom code is being
* removed from the repository. New product code should use `storyTrack`.
+ *
+ * @param {import('../types.js').Book|null|undefined} book
+ * @param {number} [pass]
+ * @param {Parameters[1]} [opts]
+ * @returns {Stop[]}
*/
export function trackFor(book, pass = 1, opts = {}) {
const merged = { plates: book?.plates || {}, storyboard: book?.storyboard || {}, ...opts };
@@ -149,9 +154,6 @@ export function segmentsOf(track, book) {
const out = [];
const index = new Map();
for (const stop of track) {
- /* The ending is its own experience. It belongs after the final scene,
- but it is not another line inside that scene and must not make the
- progress display say, for example, “12 of 13” on the last line. */
if (stop.kind === 'end') continue;
if (!index.has(stop.unit)) {
From 10314fb5dff2f568d55819e4e5ee30c6775bde30 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:45:35 +0700
Subject: [PATCH 043/110] Make solo reader integration hooks optional
---
src/ui/Reader.jsx | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/src/ui/Reader.jsx b/src/ui/Reader.jsx
index aa03750..64d9b49 100644
--- a/src/ui/Reader.jsx
+++ b/src/ui/Reader.jsx
@@ -29,10 +29,10 @@ function openPopover() {
*/
export default function Reader({
index = 0,
- onMove,
- translationFor,
- wordIn,
- onTap,
+ onMove = undefined,
+ translationFor = undefined,
+ wordIn = undefined,
+ onTap = undefined,
lang = '',
muted = false,
motion = true,
From bbad438dc5551f8d6127704f3293b07fc8cd96cf Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:47:00 +0700
Subject: [PATCH 044/110] Preserve test and build CI diagnostics
---
.github/workflows/solo-reader-ci.yml | 40 ++++++++++++++++++++++++++--
1 file changed, 38 insertions(+), 2 deletions(-)
diff --git a/.github/workflows/solo-reader-ci.yml b/.github/workflows/solo-reader-ci.yml
index 5456674..054e150 100644
--- a/.github/workflows/solo-reader-ci.yml
+++ b/.github/workflows/solo-reader-ci.yml
@@ -48,7 +48,43 @@ jobs:
run: exit 1
- name: Unit tests
- run: npm test
+ id: tests
+ continue-on-error: true
+ shell: bash
+ run: |
+ set -o pipefail
+ npm test 2>&1 | tee ci-tests.log
+
+ - name: Preserve test diagnostics
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: test-diagnostics
+ path: ci-tests.log
+ if-no-files-found: error
+ retention-days: 7
+
+ - name: Stop after failed unit tests
+ if: steps.tests.outcome == 'failure'
+ run: exit 1
- name: Production build
- run: npm run build
+ id: build
+ continue-on-error: true
+ shell: bash
+ run: |
+ set -o pipefail
+ npm run build 2>&1 | tee ci-build.log
+
+ - name: Preserve build diagnostics
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: build-diagnostics
+ path: ci-build.log
+ if-no-files-found: error
+ retention-days: 7
+
+ - name: Stop after failed build
+ if: steps.build.outcome == 'failure'
+ run: exit 1
From d6adb68c9367d9b044d1bd0575a63dbaab050c9d Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:51:50 +0700
Subject: [PATCH 045/110] Run all solo reader CI checks before failing
---
.github/workflows/solo-reader-ci.yml | 50 ++++++++++++----------------
1 file changed, 21 insertions(+), 29 deletions(-)
diff --git a/.github/workflows/solo-reader-ci.yml b/.github/workflows/solo-reader-ci.yml
index 054e150..8fd6cab 100644
--- a/.github/workflows/solo-reader-ci.yml
+++ b/.github/workflows/solo-reader-ci.yml
@@ -34,19 +34,6 @@ jobs:
set -o pipefail
npm run typecheck 2>&1 | tee ci-typecheck.log
- - name: Preserve typecheck diagnostics
- if: always()
- uses: actions/upload-artifact@v4
- with:
- name: typecheck-diagnostics
- path: ci-typecheck.log
- if-no-files-found: error
- retention-days: 7
-
- - name: Stop after a failed typecheck
- if: steps.typecheck.outcome == 'failure'
- run: exit 1
-
- name: Unit tests
id: tests
continue-on-error: true
@@ -55,19 +42,6 @@ jobs:
set -o pipefail
npm test 2>&1 | tee ci-tests.log
- - name: Preserve test diagnostics
- if: always()
- uses: actions/upload-artifact@v4
- with:
- name: test-diagnostics
- path: ci-tests.log
- if-no-files-found: error
- retention-days: 7
-
- - name: Stop after failed unit tests
- if: steps.tests.outcome == 'failure'
- run: exit 1
-
- name: Production build
id: build
continue-on-error: true
@@ -76,15 +50,33 @@ jobs:
set -o pipefail
npm run build 2>&1 | tee ci-build.log
+ - name: Preserve typecheck diagnostics
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: typecheck-diagnostics
+ path: ci-typecheck.log
+ if-no-files-found: ignore
+ retention-days: 7
+
+ - name: Preserve test diagnostics
+ if: always()
+ uses: actions/upload-artifact@v4
+ with:
+ name: test-diagnostics
+ path: ci-tests.log
+ if-no-files-found: ignore
+ retention-days: 7
+
- name: Preserve build diagnostics
if: always()
uses: actions/upload-artifact@v4
with:
name: build-diagnostics
path: ci-build.log
- if-no-files-found: error
+ if-no-files-found: ignore
retention-days: 7
- - name: Stop after failed build
- if: steps.build.outcome == 'failure'
+ - name: Fail if a verification stage failed
+ if: steps.typecheck.outcome == 'failure' || steps.tests.outcome == 'failure' || steps.build.outcome == 'failure'
run: exit 1
From d57a28b2841dbddc94d746a5b828b911e061436d Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:52:16 +0700
Subject: [PATCH 046/110] Test the new catalog boundary instead of the old
bundled-book registry
---
src/engine.test.js | 259 ++++++++++++---------------------------------
1 file changed, 70 insertions(+), 189 deletions(-)
diff --git a/src/engine.test.js b/src/engine.test.js
index 2cdf1ef..6c082ed 100644
--- a/src/engine.test.js
+++ b/src/engine.test.js
@@ -1,94 +1,32 @@
import { describe, it, expect } from 'vitest';
import { readFileSync, readdirSync, statSync } from 'node:fs';
import { join } from 'node:path';
-import { BOOKS, defaultBook, bookById, mediaOf } from './books/index.js';
+import { CATALOG, catalogBook } from './lib/library/catalog.js';
/**
- * One engine, many books.
+ * One reader, many books.
*
- * This is a goal, not a description: a second title should be a new
- * folder under `src/books/` and no change anywhere else — new content,
- * no new code. That only stays true if something checks, because the
- * cheapest way to write any feature is to reach for the book you have in
- * front of you, and it is invisible until the day somebody tries to ship
- * a second one.
- *
- * So: the engine may not know the name of a book. Not its id, not its
- * folder, not its audio directory, not its cue file. It asks the pack.
+ * The redesign has one deliberate content boundary: `library/catalog.js`.
+ * That file is allowed to know which titles are on the shelf and where a
+ * remote pack lives. The reader, vocabulary trainer, media code and UI
+ * below the bookshelf are not. Keeping the exception explicit is stronger
+ * than the old rule that pretended the application could have a bookshelf
+ * without any code ever naming a book.
*/
const ROOT = 'src';
-
-/** Ids alone, for the question "can two packs collide". */
-const BOOK_IDS = BOOKS.map((b) => b.meta.id);
-
-/**
- * Everything a leak could look like.
- *
- * This was ids only, and an id is the least likely form to leak. What
- * actually leaked was an author: `VocabCard.jsx` told every student
- * "though not the word O. Henry chose", so a child reading The Raven was
- * told Poe's word was O. Henry's. The guard searched for `magi` and
- * waved the name straight past.
- *
- * Titles come from the packs. Authors do not exist in a pack, so they
- * are listed by hand, and that is a weaker check worth naming as one: it
- * catches the two authors whose books exist, not the next name somebody
- * types.
- */
-const AUTHORS = ['O. Henry', 'Edgar Allan Poe'];
-const BOOK_NAMES = [...BOOK_IDS, ...BOOKS.map((b) => b.meta.title).filter(Boolean), ...AUTHORS];
-
-/**
- * The engine is named after one of its own books, and this test cannot
- * see the difference.
- *
- * `magi` is a book id. "Magi Reader" is the product. A plain search for
- * the id matches both, so `const APP = 'Magi Reader'` would be reported
- * as the engine naming a book — which is the opposite of true, and the
- * failure message would send whoever hit it looking for a layering bug
- * that is not there.
- *
- * It has already happened once: the backend file was briefly
- * `magi-backend.gs`, named after the product, and this test failed. The
- * file was renamed to `backend.gs`, which was the right move for its own
- * reasons, but it left the collision unfixed and waiting for the first
- * page title or about box.
- *
- * So the product's own name is removed before the search, and only that.
- * A bare `magi` anywhere still fails, which the test below proves.
- */
+const CATALOG_FILE = join(ROOT, 'lib', 'library', 'catalog.js');
const PRODUCT = /\bmagi[ -]reader\b/gi;
+const BOOK_NAMES = CATALOG.flatMap((entry) => [entry.id, entry.title, entry.author]).filter(Boolean);
-/** One line with its comments and the product's name taken out. */
-function codeOf(line) {
- return line.replace(/\/\*.*?\*\/|\/\/.*$|^\s*\*.*$/g, '').replace(PRODUCT, '');
-}
-
-/** A name in a regex is a name, not a pattern. "O. Henry" has a dot in
- * it, and an unescaped dot matches "OXHenry". */
const escape = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-/** Does an already-stripped line of code name a book? */
-function namesABookIn(code) {
- return BOOK_NAMES.some((n) => new RegExp(`\\b${escape(n)}\\b`, 'i').test(code));
-}
-
-/** The same question about a raw line, for the self-test below. */
-function namesABook(line) {
- return namesABookIn(codeOf(line));
+function codeOf(line) {
+ return String(line)
+ .replace(/\/\*.*?\*\/|\/\/.*$|^\s*\*.*$/g, '')
+ .replace(PRODUCT, '');
}
-/**
- * The lines of a file that are actually code.
- *
- * Comments are stripped from the WHOLE FILE first, not line by line, and
- * that is the difference that matters. A comment may quote the reading
- * it describes, and `codeOf` cannot see a block comment that spans
- * lines, so prose about a book read as code naming one. Blanking the
- * comment while keeping its newlines means a real finding still reports
- * the line it is on.
- */
function codeLinesOf(text) {
return String(text)
.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
@@ -96,108 +34,67 @@ function codeLinesOf(text) {
.split('\n');
}
-/** Every source file in the engine — everything except the packs. */
+function namesABook(line) {
+ const code = codeOf(line);
+ return BOOK_NAMES.some((name) => new RegExp(`\\b${escape(name)}\\b`, 'i').test(code));
+}
+
+/** Every shipped source file that should remain title-agnostic. */
function engineFiles(dir = ROOT, out = []) {
for (const name of readdirSync(dir)) {
const path = join(dir, name);
if (statSync(path).isDirectory()) {
- /* the packs are allowed to know what they are called */
if (path === join(ROOT, 'books')) continue;
engineFiles(path, out);
continue;
}
if (!/\.(js|jsx|css)$/.test(name)) continue;
- /* tests load a real book on purpose; they are not shipped */
if (/\.test\.jsx?$/.test(name)) continue;
if (name === 'engine.test.js') continue;
+ if (path === CATALOG_FILE) continue;
out.push(path);
}
return out;
}
-describe('the engine does not know which book it is reading', () => {
+describe('the catalog is the content boundary', () => {
const files = engineFiles();
- it('has source files to check, so this test cannot pass by finding none', () => {
+ it('checks a real body of runtime code', () => {
expect(files.length).toBeGreaterThan(15);
});
- it('tells the product from the book it is named after', () => {
- /* The exception above, kept honest. If this test ever passes by
- matching nothing, the one above is worthless. */
+ it('recognises a real book name but not the product name', () => {
expect(namesABook("const APP_NAME = 'Magi Reader';")).toBe(false);
- expect(namesABook('const zip = `magi-reader-${version}.zip`;')).toBe(false);
-
- expect(namesABook("import book from './books/magi/book.json';")).toBe(true);
- expect(namesABook("if (id === 'magi') return DEFAULT;")).toBe(true);
- /* the exception removes the product's name, not the whole line */
- expect(namesABook("const t = 'Magi Reader'; const b = 'magi';")).toBe(true);
+ expect(namesABook("const id = 'magi';")).toBe(true);
+ expect(namesABook("const title = 'The Gift of the Magi';")).toBe(true);
+ expect(namesABook('O. Henry wrote it')).toBe(true);
});
- it('catches a title or an author, not only an id', () => {
- /* The leak this was widened for: VocabCard told every student
- "though not the word O. Henry chose", so a child reading The Raven
- was told Poe's word was O. Henry's. Searching ids alone waved it
- through, because no id appears in that sentence. */
- expect(namesABook('though not the word O. Henry chose')).toBe(true);
- expect(namesABook('a line about Edgar Allan Poe')).toBe(true);
- expect(namesABook("const t = 'The Gift of the Magi';")).toBe(true);
-
- /* and the dot in "O. Henry" is a dot, not any character */
- expect(namesABook('OXHenry wrote it')).toBe(false);
- expect(namesABook('the author chose it')).toBe(false);
- });
-
- it('does not read prose in a block comment as code', () => {
- /* validate.js explains a rule using Poe, and Scene.jsx explains a
- defect using O. Henry. Both are comments about books, which is
- allowed and useful. A per-line strip could not see a block comment
- spanning lines and reported all four as leaks. */
- const file = [
+ it('does not mistake prose in block comments for title-specific code', () => {
+ const text = [
'/**',
- ' * A poem by Edgar Allan Poe, quoted to explain the rule.',
- ' * The Gift of the Magi lost its commas here.',
- ' */',
- "const x = 'fine';",
- '/* O. Henry, on one line */',
- "const y = 'also fine';",
- ].join('\n');
- expect(codeLinesOf(file).filter(namesABookIn)).toEqual([]);
- });
-
- it('still finds a leak on the line after a block comment', () => {
- /* Blanking a comment must not blank the code under it, and the line
- numbers have to survive so a finding points somewhere real. */
- const file = [
- '/*',
- ' * Poe wrote it.',
+ ' * O. Henry and Edgar Allan Poe are useful examples here.',
' */',
- "import b from './books/magi/book.json';",
+ "const value = 'generic';",
].join('\n');
- const lines = codeLinesOf(file);
- expect(lines).toHaveLength(4);
- expect(lines.findIndex(namesABookIn)).toBe(3);
+ expect(codeLinesOf(text).filter(namesABook)).toEqual([]);
});
- it('never names a book', () => {
- /* `src/books/index.js` is the one place a title is named, and it is
- a pack directory, not the engine. Everything else asks it. */
+ it('keeps book names out of the generic runtime', () => {
const guilty = [];
for (const file of files) {
- /* a comment may quote the reading it is describing, so comments
- come out of the whole file before anything is searched */
- codeLinesOf(readFileSync(file, 'utf8')).forEach((code, i) => {
- if (namesABookIn(code)) guilty.push(`${file}:${i + 1}: ${code.trim()}`);
+ codeLinesOf(readFileSync(file, 'utf8')).forEach((line, i) => {
+ if (namesABook(line)) guilty.push(`${file}:${i + 1}: ${line.trim()}`);
});
}
expect(guilty).toEqual([]);
});
- it('never hard-codes where a book keeps its media', () => {
+ it('keeps title-specific media paths out of the generic runtime', () => {
const guilty = [];
for (const file of files) {
- const text = readFileSync(file, 'utf8');
- text.split('\n').forEach((line, i) => {
+ codeLinesOf(readFileSync(file, 'utf8')).forEach((line, i) => {
if (/['"][\w-]*(audio|cues)\/[\w-]*\.?\w*['"]/.test(codeOf(line))) {
guilty.push(`${file}:${i + 1}: ${line.trim()}`);
}
@@ -207,65 +104,49 @@ describe('the engine does not know which book it is reading', () => {
});
});
-describe('a book pack says what it is and where its media lives', () => {
- it('names itself', () => {
- for (const b of BOOKS) {
- expect(b.meta.id, 'a pack with no id cannot be told from another').toBeTruthy();
- expect(b.meta.title).toBeTruthy();
- }
+describe('the bookshelf catalog', () => {
+ it('contains real entries and unique ids', () => {
+ expect(CATALOG.length).toBeGreaterThan(1);
+ expect(new Set(CATALOG.map((entry) => entry.id)).size).toBe(CATALOG.length);
});
- it('has a unique id, so two packs cannot share a gradebook', () => {
- /* Ids, not BOOK_NAMES: that list also carries titles and authors now,
- and counting it here would compare a book count against a name
- count and fail for a reason that has nothing to do with packs. */
- expect(new Set(BOOK_IDS).size).toBe(BOOKS.length);
+ it('gives every entry enough identity to render a useful shelf card', () => {
+ for (const entry of CATALOG) {
+ expect(entry.id).toBeTruthy();
+ expect(entry.title).toBeTruthy();
+ expect(entry.author).toBeTruthy();
+ expect(entry.kind).toBeTruthy();
+ expect(entry.note).toBeTruthy();
+ }
});
- it('says where its recordings and cues are, relatively', () => {
- for (const b of BOOKS) {
- const m = mediaOf(b);
- expect(m.audio, `${b.meta.id} has no audio path`).toBeTruthy();
- expect(m.cues, `${b.meta.id} has no cue file`).toBeTruthy();
- /* itch serves from a nested path: a leading slash 404s everything */
- for (const p of [m.audio, m.cues]) {
- expect(p.startsWith('/'), `"${p}" is absolute and would 404 on itch`).toBe(false);
- expect(p.startsWith('http')).toBe(false);
- }
+ it('has exactly one loading source for every ready title', () => {
+ for (const entry of CATALOG.filter((item) => !item.comingSoon)) {
+ expect(Boolean(entry.local) !== Boolean(entry.remote), entry.id).toBe(true);
}
});
- it('carries the whole book, not a stub', () => {
- for (const b of BOOKS) {
- expect(b.units.length).toBeGreaterThan(0);
- for (const part of ['teaching', 'plates', 'cast', 'dialogue']) {
- expect(
- Object.keys(b[part] || {}).length,
- `${b.meta.id} has no ${part}`
- ).toBeGreaterThan(0);
+ it('keeps deployment-relative media paths relative', () => {
+ for (const entry of CATALOG.filter((item) => item.remote)) {
+ const spec = entry.remote;
+ const relative = [
+ spec.plate,
+ spec.beatPlate,
+ spec.audio,
+ spec.cues,
+ ...Object.values(spec.cast || {}),
+ ].filter(Boolean);
+ for (const path of relative) {
+ expect(path.startsWith('/'), `${entry.id}: ${path}`).toBe(false);
+ expect(path.startsWith('http'), `${entry.id}: ${path}`).toBe(false);
}
+ expect(spec.book.startsWith('https://')).toBe(true);
+ expect(spec.base.startsWith('https://')).toBe(true);
}
});
-});
-
-describe('choosing a book', () => {
- it('opens with the first one', () => {
- expect(defaultBook).toBe(BOOKS[0]);
- });
-
- it('finds one by name', () => {
- expect(bookById(BOOKS[0].meta.id)).toBe(BOOKS[0]);
- });
-
- it('falls back rather than handing back nothing', () => {
- /* a stale link to a book this build does not carry should open the
- reader, not a blank page */
- expect(bookById('a-book-that-is-not-here')).toBe(defaultBook);
- expect(bookById('')).toBe(defaultBook);
- });
- it('gives empty paths for a pack with no media, rather than throwing', () => {
- expect(mediaOf({})).toEqual({ audio: '', cues: '' });
- expect(mediaOf(null)).toEqual({ audio: '', cues: '' });
+ it('finds a known book and refuses an unknown one', () => {
+ expect(catalogBook(CATALOG[0].id)).toBe(CATALOG[0]);
+ expect(catalogBook('not-on-this-shelf')).toBeNull();
});
});
From 8faa253d0c3dd003a314eafd7e78662d8dffd63c Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:52:33 +0700
Subject: [PATCH 047/110] Validate the bundled Magi pack without external audio
staging
---
src/books/magi/pack.test.js | 146 ++++++++++++------------------------
1 file changed, 46 insertions(+), 100 deletions(-)
diff --git a/src/books/magi/pack.test.js b/src/books/magi/pack.test.js
index b46e9f1..633f7ae 100644
--- a/src/books/magi/pack.test.js
+++ b/src/books/magi/pack.test.js
@@ -1,15 +1,8 @@
import { describe, it, expect } from 'vitest';
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
import book from './index.js';
import { beatsOfBook } from '../../lib/reader/beats.js';
import { wordsByClip } from '../../lib/media/vtt.js';
-import {
- preshowRun,
- helloRun,
- passIntroRun,
- talkFor,
- reactionsFor,
-} from '../../lib/speech/script.js';
import { wordsOf } from '../../lib/vocab/words.js';
import { validateBook } from '../../lib/book/validate.js';
import {
@@ -20,103 +13,59 @@ import {
} from '../../lib/vocab/kinds.js';
/**
- * What is true of THIS pack, and of no other.
- *
- * The engine's own tests moved to `books/fixture` so that the engine
- * could be tested without a title. What could not move is anything that
- * asks a question about this pack's own contents: whether its 519
- * recordings are on disk, whether its cue file names every clip, whether
- * its real word list can be quizzed without producing a question with
- * two right answers.
- *
- * Those are pack facts, so they live with the pack. When
- * `src/books/magi/` becomes its own repository this file goes with it,
- * and the engine repository loses nothing it was relying on.
+ * Facts about the bundled Gift of the Magi pack.
*
- * The sweeps below deliberately repeat rules the fixture also checks.
- * That is not duplication for its own sake: the fixture proves the rule
- * is implemented, and this proves this book obeys it. A generated pack
- * can break the second without touching the first.
+ * Narration MP3s are deployment assets copied into `public/magi-audio`
+ * by the packaging pipeline; they are intentionally not committed to the
+ * source repository. CI therefore checks the committed contract it can
+ * actually prove: every story line has a cue, the pack points at relative
+ * media locations, every named picture exists, and its real vocabulary
+ * can produce valid practice questions.
*/
-/* Deterministic, so a failure names a seed somebody can reproduce. */
const seeded = (seed) => () => {
seed = (seed * 1664525 + 1013904223) % 4294967296;
return seed / 4294967296;
};
-describe('every recording this pack names is on disk', () => {
- /* A line whose clip is missing is silent, and silence is the one
- failure nobody reports — a student assumes the sound is off. */
-
- const clips = new Set(
- readdirSync('public/magi-audio')
- .filter((f) => f.endsWith('.mp3'))
- .map((f) => f.replace(/\.mp3$/, ''))
- );
-
- /* All cues live in one WebVTT file — 519 separate ones put the build
- over itch's 1000-file limit and the upload was rejected. */
+describe('the narration contract', () => {
const cues = wordsByClip(readFileSync('public/cues/magi.vtt', 'utf8'));
+ const beats = beatsOfBook(book);
- /** Every line the two of them speak, outside the narration. */
- const spoken = () => {
- const out = [...preshowRun(book), ...helloRun(book)];
- for (const p of [1, 2, 3]) out.push(...passIntroRun(book, p));
- for (const id of [...book.units.map((u) => u.id), ...Object.keys(book.info)]) {
- out.push(...talkFor(book, id));
- out.push(...reactionsFor(book, id).values());
- }
- return out;
- };
-
- it('has an mp3 and a cue for every beat of the story', () => {
- /* The clips were produced against the old reader's line numbering.
- If that drifts, a student gets a silent page and nothing says why. */
- const missingAudio = [];
- const missingCues = [];
- for (const b of beatsOfBook(book)) {
- if (!existsSync(`public/magi-audio/${b.clip}.mp3`)) missingAudio.push(b.clip);
- if (!cues[b.clip]?.length) missingCues.push(b.clip);
- }
- expect({ missingAudio, missingCues }).toEqual({ missingAudio: [], missingCues: [] });
+ it('has a cue for every narrated story line', () => {
+ const missing = beats.filter((beat) => !cues[beat.clip]?.length).map((beat) => beat.clip);
+ expect(missing).toEqual([]);
});
- it('has an mp3 and a cue for every line the guides speak', () => {
- const missingAudio = spoken()
- .filter((t) => !clips.has(t.clip))
- .map((t) => t.clip);
- const missingCues = spoken()
- .filter((t) => !cues[t.clip]?.length)
- .map((t) => t.clip);
- expect({ missingAudio, missingCues }).toEqual({ missingAudio: [], missingCues: [] });
+ it('checks a real amount of narration rather than passing vacuously', () => {
+ expect(beats.length).toBeGreaterThan(100);
+ expect(Object.keys(cues).length).toBeGreaterThan(beats.length);
});
- it('covers a real number of clips, so the checks above are not vacuous', () => {
- expect(beatsOfBook(book).length).toBeGreaterThan(100);
- expect(spoken().length).toBeGreaterThan(50);
+ it('keeps its deployment media paths relative', () => {
+ expect(book.media.audio).toBeTruthy();
+ expect(book.media.cues).toBeTruthy();
+ for (const path of [book.media.audio, book.media.cues]) {
+ expect(path.startsWith('/'), path).toBe(false);
+ expect(path.startsWith('http'), path).toBe(false);
+ }
});
});
describe('every picture this pack names is on disk', () => {
it('finds the plate for every scene', () => {
- const named = [...new Set(beatsOfBook(book).map((b) => b.plate.src))];
- /* A book with no plates passes the check below without examining
- anything, and reads exactly like a book whose plates are all
- present. Say how many were looked at. */
- expect(named.length, 'no plates were checked, so the check below proves nothing').toBeGreaterThan(
- 5
- );
+ const named = [...new Set(beatsOfBook(book).map((beat) => beat.plate.src))];
+ expect(
+ named.length,
+ 'no plates were checked, so the check below proves nothing'
+ ).toBeGreaterThan(5);
const missing = named.filter((src) => !src || !existsSync(`public/${src}`));
expect(missing).toEqual([]);
});
});
-describe('this pack’s own word list can be quizzed', () => {
- /* The fixture proves the rules hold. This proves the sixty-odd real
- words obey them — which is where "craved and coveted are each
- other's substitutes" was found, and no toy fixture would have. */
- const items = wordsOf(book).map((i) => ({ ...i, asked: 1 }));
+describe('this pack’s own word list can be practised', () => {
+ const items = wordsOf(book).map((item) => ({ ...item, asked: 1 }));
const ctx = { book, swaps: book.swaps, all: items };
it('agrees with the contract about how many words the trainer gets', () => {
@@ -126,23 +75,23 @@ describe('this pack’s own word list can be quizzed', () => {
it('produces an answerable question for every word and every kind', () => {
const problems = [];
for (const item of items) {
- for (const kind of kindsFor(ctx, item, items).filter((k) => k !== 'match')) {
- for (let s = 1; s < 6; s++) {
- const q = buildQuestion(ctx, kind, item, items, seeded(s));
- const label = `${kind}/${item.w}/seed${s}`;
+ for (const kind of kindsFor(ctx, item, items).filter((value) => value !== 'match')) {
+ for (let seed = 1; seed < 6; seed++) {
+ const question = buildQuestion(ctx, kind, item, items, seeded(seed));
+ const label = `${kind}/${item.w}/seed${seed}`;
- if (!q.prompt) problems.push(`${label}: empty prompt`);
+ if (!question.prompt) problems.push(`${label}: empty prompt`);
if (kind === 'spell') {
- if (!q.answer) problems.push(`${label}: no answer`);
+ if (!question.answer) problems.push(`${label}: no answer`);
} else {
- const correct = q.options.filter((o) => o.ok);
- if (correct.length !== 1)
- problems.push(`${label}: ${correct.length} correct options`);
- const texts = q.options.map((o) => String(o.t).toLowerCase());
- if (new Set(texts).size !== texts.length)
+ const correct = question.options.filter((option) => option.ok);
+ if (correct.length !== 1) problems.push(`${label}: ${correct.length} correct options`);
+ const texts = question.options.map((option) => String(option.t).toLowerCase());
+ if (new Set(texts).size !== texts.length) {
problems.push(`${label}: duplicate options [${texts}]`);
+ }
}
- if (selfBetraying(q)) problems.push(`${label}: prompt contains the answer`);
+ if (selfBetraying(question)) problems.push(`${label}: prompt contains the answer`);
}
}
}
@@ -150,14 +99,11 @@ describe('this pack’s own word list can be quizzed', () => {
});
it('specifically keeps craved and coveted apart', () => {
- /* The two words substitute for each other, so neither may be a wrong
- answer for the other: the question would have two right answers
- and would punish the student who knew both. */
- const craved = items.find((i) => i.w.toLowerCase() === 'craved');
+ const craved = items.find((item) => item.w.toLowerCase() === 'craved');
expect(craved, 'the pack no longer glosses craved').toBeTruthy();
- for (let s = 1; s < 40; s++) {
- const words = distractorsFor(ctx, craved, 'swap', 3, seeded(s)).map((g) =>
- g.w.toLowerCase()
+ for (let seed = 1; seed < 40; seed++) {
+ const words = distractorsFor(ctx, craved, 'swap', 3, seeded(seed)).map((item) =>
+ item.w.toLowerCase()
);
expect(words).not.toContain('coveted');
}
From 966b239528130270d9b6d244af2a8f69f46996b9 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:52:54 +0700
Subject: [PATCH 048/110] Make track tests describe the solo reading contract
---
src/lib/reader/track.test.js | 267 ++++++++++-------------------------
1 file changed, 75 insertions(+), 192 deletions(-)
diff --git a/src/lib/reader/track.test.js b/src/lib/reader/track.test.js
index 555d962..b428c38 100644
--- a/src/lib/reader/track.test.js
+++ b/src/lib/reader/track.test.js
@@ -1,234 +1,117 @@
import { describe, it, expect, beforeAll } from 'vitest';
import book from '../../books/fixture/index.js';
-import { trackFor, stepTrack, segmentsOf, whereIn, jumpSegment, aimAt } from './track.js';
-import { questionsOf, promptsOf } from './assessment.js';
+import { storyTrack, stepTrack, segmentsOf, whereIn, jumpSegment } from './track.js';
import { beatsOfBook } from './beats.js';
-/* The engine's own fixture book. A track is the same three readings
- whatever pack it is built from, and testing it against a title only
- proves it works for that title. */
-
-describe('every reading', () => {
- for (const pass of [1, 2, 3]) {
- it(`reading ${pass} ends with an ending, rather than running out`, () => {
- const t = trackFor(book, pass);
- expect(t[t.length - 1].kind).toBe('end');
- /* exactly one, and only at the end */
- expect(t.filter((s) => s.kind === 'end')).toHaveLength(1);
- });
- }
-
- it('gives a question about unread material a picture to ask it about', () => {
- /* A question about a part that WAS read aloud follows that part's
- lines, and the picture from the last of them is still on screen.
- The background pages have no lines, so their questions have to
- carry a picture of their own — and until they did, the author page
- and the note on the afterlife showed a black rectangle. */
- const read = new Set(book.units.map((u) => u.id));
- const missing = [];
- let asked = 0;
- for (const pass of [1, 2, 3]) {
- for (const stop of trackFor(book, pass)) {
- if (stop.kind !== 'question' && stop.kind !== 'prompt') continue;
- if (read.has(stop.unit)) continue;
- asked++;
- if (!stop.plate?.src) missing.push(`${pass}:${stop.unit}`);
- }
- }
- expect(missing).toEqual([]);
- expect(asked, 'a book with no background pages would pass too').toBeGreaterThan(0);
- });
-
- it('has nothing at all to show for a book with nothing in it', () => {
- expect(trackFor({ meta: { title: '' }, units: [] }, 1)).toEqual([]);
- });
-});
-
-describe('reading 1', () => {
- it('is the story, and the two of them talking about it', () => {
- const t = trackFor(book, 1);
- expect(t.filter((s) => s.kind === 'line')).toHaveLength(beatsOfBook(book).length);
- expect(t.filter((s) => s.kind === 'say').length).toBeGreaterThan(0);
- expect(t.some((s) => s.kind === 'question' || s.kind === 'prompt')).toBe(false);
- });
-});
-
-describe('reading 2', () => {
- it('is the story with every question in it', () => {
- const t = trackFor(book, 2);
- const asked = t.filter((s) => s.kind === 'question');
- expect(asked).toHaveLength(questionsOf(book).length);
- expect(t.filter((s) => s.kind === 'prompt')).toHaveLength(0);
+describe('the solo story track', () => {
+ it('contains every story line once and then one ending', () => {
+ const track = storyTrack(book);
+ const lines = track.filter((stop) => stop.kind === 'line');
+ expect(lines).toHaveLength(beatsOfBook(book).length);
+ expect(track[track.length - 1].kind).toBe('end');
+ expect(track.filter((stop) => stop.kind === 'end')).toHaveLength(1);
+ expect(track.map((stop) => stop.at)).toEqual(track.map((_, index) => index));
});
- it('asks about a segment only after it has been read', () => {
- const t = trackFor(book, 2);
- for (const stop of t) {
- if (stop.kind !== 'question') continue;
- const lines = t.filter((s) => s.kind === 'line' && s.unit === stop.unit);
- if (!lines.length) continue; // background notes, which are not read
- expect(lines[lines.length - 1].at).toBeLessThan(stop.at);
- }
+ it('contains no classroom or mid-story interruption stops', () => {
+ const kinds = new Set(storyTrack(book).map((stop) => stop.kind));
+ expect([...kinds].sort()).toEqual(['end', 'line']);
});
- it('loses no question, even one about material that is not read aloud', () => {
- const ids = new Set(
- trackFor(book, 2)
- .filter((s) => s.kind === 'question')
- .map((s) => s.question.id)
- );
- for (const q of questionsOf(book)) expect(ids.has(q.id)).toBe(true);
+ it('ignores legacy teaching data even when the pack still carries it', () => {
+ const noisy = {
+ ...book,
+ teaching: { injected: { watch: 'interrupt me' } },
+ dialogue: { injected: [{ who: 'wren', text: 'interrupt me' }] },
+ wrenReactions: { injected: [{ at: 0, line: 'interrupt me' }] },
+ };
+ expect(storyTrack(noisy)).toEqual(storyTrack(book));
});
-});
-describe('reading 3', () => {
- it('is the story with every written prompt in it', () => {
- const t = trackFor(book, 3);
- expect(t.filter((s) => s.kind === 'prompt')).toHaveLength(promptsOf(book).length);
- expect(t.filter((s) => s.kind === 'question')).toHaveLength(0);
+ it('has nothing to show for an empty book', () => {
+ expect(storyTrack({ meta: { title: '' }, units: [] })).toEqual([]);
});
});
describe('the position', () => {
- it('numbers every stop, once, in order', () => {
- const t = trackFor(book, 2);
- expect(t.map((s) => s.at)).toEqual(t.map((_, i) => i));
- });
-
- it('refuses to produce a position that is not on the track', () => {
- const t = trackFor(book, 1);
- expect(stepTrack(t, -50, 0)).toBe(0);
- expect(stepTrack(t, 99999, 0)).toBe(t.length - 1);
- expect(stepTrack(t, NaN, 1)).toBe(0);
+ it('clamps bad positions onto the actual track', () => {
+ const track = storyTrack(book);
+ expect(stepTrack(track, -50, 0)).toBe(0);
+ expect(stepTrack(track, 99999, 0)).toBe(track.length - 1);
+ expect(stepTrack(track, NaN, 1)).toBe(0);
expect(stepTrack([], 4, 1)).toBe(0);
});
});
describe('the storyboard', () => {
- it('has one entry per segment, covering the whole track with no gap', () => {
- const t = trackFor(book, 2);
- const segs = segmentsOf(t, book);
-
- expect(segs.length).toBe(new Set(t.map((s) => s.unit)).size);
- expect(segs[0].from).toBe(0);
- expect(segs[segs.length - 1].to).toBe(t.length - 1);
- for (let i = 1; i < segs.length; i++) {
- expect(segs[i].from, 'segments run end to end').toBe(segs[i - 1].to + 1);
+ it('has one entry per story unit and stops before the ending', () => {
+ const track = storyTrack(book);
+ const segments = segmentsOf(track, book);
+ const storyStops = track.filter((stop) => stop.kind !== 'end');
+
+ expect(segments.length).toBe(new Set(storyStops.map((stop) => stop.unit)).size);
+ expect(segments[0].from).toBe(0);
+ expect(segments[segments.length - 1].to).toBe(storyStops[storyStops.length - 1].at);
+ for (let index = 1; index < segments.length; index++) {
+ expect(segments[index].from, 'segments run end to end').toBe(segments[index - 1].to + 1);
}
});
- it('carries a picture and a title, because that is what is navigable', () => {
- const segs = segmentsOf(trackFor(book, 1), book);
- expect(segs.every((s) => s.title)).toBe(true);
- expect(segs.filter((s) => s.plate?.src).length).toBeGreaterThan(segs.length * 0.8);
- });
-
- it('counts what is in each segment', () => {
- const segs = segmentsOf(trackFor(book, 2), book);
- const asks = segs.reduce((n, s) => n + s.asks, 0);
- expect(asks).toBe(questionsOf(book).length);
- });
-
- it('says where a position is', () => {
- const t = trackFor(book, 1);
- const segs = segmentsOf(t, book);
- expect(whereIn(segs, 0)).toMatchObject({ index: 0, through: 1 });
-
- const second = segs[1];
- expect(whereIn(segs, second.from).segment.id).toBe(second.id);
- expect(whereIn(segs, second.to)).toMatchObject({ through: second.to - second.from + 1 });
- expect(whereIn(segs, t.length - 1).index).toBe(segs.length - 1);
+ it('carries a picture and title because that is what a reader navigates by', () => {
+ const segments = segmentsOf(storyTrack(book), book);
+ expect(segments.every((segment) => segment.title)).toBe(true);
+ expect(segments.filter((segment) => segment.plate?.src).length).toBeGreaterThan(
+ segments.length * 0.8
+ );
});
-});
-describe('jumping by segment', () => {
- let t, segs;
- beforeAll(() => {
- t = trackFor(book, 1);
- segs = segmentsOf(t, book);
+ it('counts only literary lines inside a story segment', () => {
+ const track = storyTrack(book);
+ const segments = segmentsOf(track, book);
+ expect(segments.reduce((count, segment) => count + segment.lines, 0)).toBe(
+ beatsOfBook(book).length
+ );
+ expect(segments.every((segment) => segment.said === 0 && segment.asks === 0)).toBe(true);
});
- it('goes to the top of the next one', () => {
- expect(jumpSegment(segs, segs[0].from, 1)).toBe(segs[1].from);
- });
+ it('locates story positions and deliberately leaves the ending outside the storyboard', () => {
+ const track = storyTrack(book);
+ const segments = segmentsOf(track, book);
+ expect(whereIn(segments, 0)).toMatchObject({ index: 0, through: 1 });
- it('back from partway through restarts this segment, not the last one', () => {
- /* what the back button on a music player does */
- const mid = segs[2].from + 1;
- expect(jumpSegment(segs, mid, -1)).toBe(segs[2].from);
- });
+ const second = segments[1];
+ expect(whereIn(segments, second.from).segment.id).toBe(second.id);
+ expect(whereIn(segments, second.to)).toMatchObject({ through: second.to - second.from + 1 });
- it('back from the very top of a segment goes to the previous one', () => {
- expect(jumpSegment(segs, segs[2].from, -1)).toBe(segs[1].from);
- });
-
- it('does not run off either end', () => {
- expect(jumpSegment(segs, 0, -1)).toBe(0);
- const last = segs[segs.length - 1];
- expect(jumpSegment(segs, last.from, 1)).toBe(last.from);
+ const lastStory = track.length - 2;
+ expect(whereIn(segments, lastStory).index).toBe(segments.length - 1);
+ expect(whereIn(segments, track.length - 1)).toMatchObject({ index: -1, segment: null });
});
});
-describe('the one thing to look for', () => {
- /* Every part carries a `watch` line for reading one and a `focus` line
- for reading two. Both were authored, translated into every language
- the picker offers, and described in the printed guide as "before
- each part you are told one thing to look for". Neither had ever been
- rendered anywhere except the guide. */
- it('gives the watch line at the start of a part in reading one', () => {
- const track = trackFor(book, 1);
- const text = aimAt(book, 1, track, 0);
- expect(text).toBeTruthy();
- expect(text).toBe(book.teaching[track[0].unit].watch);
- });
-
- it('gives the focus line in reading two, not the watch line', () => {
- const track = trackFor(book, 2);
- const first = track.findIndex((s) => s.unit);
- const text = aimAt(book, 2, track, first);
- expect(text).toBe(book.teaching[track[first].unit].focus);
- expect(text).not.toBe(book.teaching[track[first].unit].watch);
- });
+describe('jumping by story segment', () => {
+ let segments;
- it('says it once per part, not under every line', () => {
- /* Repeating a prompt under every line turns it into wallpaper, and
- the point of aiming attention is that it is aimed once. */
- const track = trackFor(book, 1);
- const shown = track.map((_, i) => aimAt(book, 1, track, i)).filter(Boolean);
- const parts = new Set(track.map((s) => s.unit).filter(Boolean));
- expect(shown).toHaveLength(parts.size);
- expect(new Set(shown).size).toBe(shown.length);
+ beforeAll(() => {
+ segments = segmentsOf(storyTrack(book), book);
});
- it('lands on the first stop of each part, wherever that falls', () => {
- const track = trackFor(book, 1);
- for (let i = 0; i < track.length; i++) {
- if (!aimAt(book, 1, track, i)) continue;
- const before = i > 0 ? track[i - 1].unit : null;
- expect(before, `part ${track[i].unit} announced mid-part`).not.toBe(track[i].unit);
- }
+ it('goes to the top of the next segment', () => {
+ expect(jumpSegment(segments, segments[0].from, 1)).toBe(segments[1].from);
});
- it('says nothing in reading three, which is writing rather than looking', () => {
- const track = trackFor(book, 3);
- expect(track.map((_, i) => aimAt(book, 3, track, i)).filter(Boolean)).toEqual([]);
+ it('back from partway through restarts the current segment', () => {
+ const mid = segments[2].from + 1;
+ expect(jumpSegment(segments, mid, -1)).toBe(segments[2].from);
});
- it('says nothing for a part that carries no prompt, rather than an empty one', () => {
- const bare = { ...book, teaching: { ...book.teaching } };
- const track = trackFor(book, 1);
- const unit = track[0].unit;
- bare.teaching[unit] = { ...bare.teaching[unit], watch: ' ' };
- expect(aimAt(bare, 1, track, 0)).toBeNull();
+ it('back from the top goes to the previous segment', () => {
+ expect(jumpSegment(segments, segments[2].from, -1)).toBe(segments[1].from);
});
- it('never throws on a book or a position that is not there', () => {
- for (const bad of [null, undefined, {}, { teaching: null }]) {
- expect(() => aimAt(bad, 1, [], 0)).not.toThrow();
- expect(aimAt(bad, 1, [], 0)).toBeNull();
- }
- const track = trackFor(book, 1);
- expect(aimAt(book, 1, track, 9999)).toBeNull();
- expect(aimAt(book, 1, null, 0)).toBeNull();
+ it('does not run off either end', () => {
+ expect(jumpSegment(segments, 0, -1)).toBe(0);
+ const last = segments[segments.length - 1];
+ expect(jumpSegment(segments, last.from, 1)).toBe(last.from);
});
});
From 284f9f565947ff1b91affbbf8980cac806dc4d1e Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:56:22 +0700
Subject: [PATCH 049/110] Remove the legacy three-pass reading track
---
src/lib/reader/track.js | 163 +++++++++-------------------------------
1 file changed, 36 insertions(+), 127 deletions(-)
diff --git a/src/lib/reader/track.js b/src/lib/reader/track.js
index b21bc7c..12f4ea4 100644
--- a/src/lib/reader/track.js
+++ b/src/lib/reader/track.js
@@ -1,37 +1,31 @@
import { beatsOf } from './beats.js';
-import { questionsOf, promptsOf } from './assessment.js';
-import { reactionsFor, talkFor } from '../speech/script.js';
/**
- * One stop on a reading track.
+ * One stop in the literary work.
*
- * The legacy classroom track can still contain dialogue, questions and
- * prompts because old tests and old packs know that shape. The solo reader
- * uses `storyTrack`, which deliberately contains only story lines and an
- * ending. Keeping those two contracts separate makes it impossible for an
- * old teaching field to accidentally interrupt a recreational reading.
+ * The solo reader has only two states: a narrated line and the ending.
+ * Questions, prompts, teacher instructions and mid-story guide dialogue
+ * are not valid track data anymore; framing lives before and after the
+ * work and commentary lives in Explore.
*
* @typedef {object} Stop
- * @property {'line'|'say'|'question'|'prompt'|'end'} kind
+ * @property {'line'|'end'} kind
* @property {number} at
* @property {string} unit
* @property {number} [i]
* @property {string} [line]
* @property {string|null} [clip]
- * @property {{id:string, src:string|null, alt:string}} [plate]
+ * @property {{id:string,src:string|null,alt:string}} [plate]
* @property {Record} [gloss]
- * @property {object} [visual]
- * @property {import('../speech/script.js').Turn} [turn]
- * @property {any} [question]
- * @property {any} [prompt]
+ * @property {import('../types.js').Visual} [visual]
*/
/**
- * The product track: the literary work, uninterrupted.
+ * Build the uninterrupted literary work.
*
- * Wren and Ambrose belong before and after the work, and the deeper
- * explanation belongs in Explore. Nothing from `teaching`, `dialogue`,
- * `questions`, `writing`, or reaction data is consulted here.
+ * Nothing from legacy teaching, assessment or dialogue fields is read
+ * here. Old packs may still carry those fields while they are migrated;
+ * they cannot alter what a person sees while reading.
*
* @param {import('../types.js').Book|null|undefined} book
* @param {Parameters[1]} [opts]
@@ -52,96 +46,12 @@ export function storyTrack(book, opts = {}) {
}
}
- const lastUnit = out.length ? out[out.length - 1].unit : book?.units?.[0]?.id || '';
- if (out.length) out.push({ kind: 'end', unit: lastUnit });
+ if (out.length) out.push({ kind: 'end', unit: out[out.length - 1].unit });
return out.map((stop, at) => ({ ...stop, at }));
}
-/**
- * Legacy three-pass track retained while the classroom code is being
- * removed from the repository. New product code should use `storyTrack`.
- *
- * @param {import('../types.js').Book|null|undefined} book
- * @param {number} [pass]
- * @param {Parameters[1]} [opts]
- * @returns {Stop[]}
- */
-export function trackFor(book, pass = 1, opts = {}) {
- const merged = { plates: book?.plates || {}, storyboard: book?.storyboard || {}, ...opts };
- const units = book?.units || [];
-
- const questions = pass === 2 ? questionsOf(book) : [];
- const prompts = pass === 3 ? promptsOf(book) : [];
- const byUnit = (list) => {
- const m = new Map();
- for (const x of list) {
- if (!m.has(x.unit)) m.set(x.unit, []);
- m.get(x.unit).push(x);
- }
- return m;
- };
- const q = byUnit(questions);
- const p = byUnit(prompts);
-
- /** @type {Omit[]} */
- const out = [];
- for (const u of units) {
- const reacts = pass === 1 ? reactionsFor(book, u.id) : new Map();
-
- for (const beat of beatsOf(u, merged)) {
- out.push({ kind: 'line', unit: u.id, ...beat });
- const r = reacts.get(beat.i);
- if (r) out.push({ kind: 'say', unit: u.id, turn: r, plate: beat.plate });
- }
-
- if (pass === 1) {
- for (const turn of talkFor(book, u.id)) out.push({ kind: 'say', unit: u.id, turn });
- }
- for (const x of q.get(u.id) || []) out.push({ kind: 'question', unit: u.id, question: x });
- for (const x of p.get(u.id) || []) out.push({ kind: 'prompt', unit: u.id, prompt: x });
- }
-
- const placed = new Set(units.map((u) => u.id));
- const extras = Object.keys(book?.info || {}).filter((id) => !placed.has(id));
- const infoPlate = (id) => {
- const info = book?.info?.[id];
- const file = merged.plates[info?.scene || id];
- if (!file) return undefined;
- return {
- id: info?.scene || id,
- src: `${merged.base ?? ''}${file}`,
- alt: info?.caption || info?.title || '',
- };
- };
-
- if (pass === 1) {
- for (const id of extras) {
- const plate = infoPlate(id);
- for (const turn of talkFor(book, id)) out.push({ kind: 'say', unit: id, turn, plate });
- }
- }
- for (const x of questions)
- if (!placed.has(x.unit)) out.push({ kind: 'question', unit: x.unit, question: x, plate: infoPlate(x.unit) });
- for (const x of prompts)
- if (!placed.has(x.unit)) out.push({ kind: 'prompt', unit: x.unit, prompt: x, plate: infoPlate(x.unit) });
-
- const lastUnit = out.length ? out[out.length - 1].unit : units[0]?.id || '';
- if (out.length) out.push({ kind: 'end', unit: lastUnit });
- return out.map((stop, i) => ({ ...stop, at: i }));
-}
-
-export function aimAt(book, pass, track, at) {
- if (pass !== 1 && pass !== 2) return null;
- const stop = track?.[at];
- if (!stop?.unit) return null;
- if (at > 0 && track[at - 1]?.unit === stop.unit) return null;
- const teaching = book?.teaching?.[stop.unit];
- const text = pass === 1 ? teaching?.watch : teaching?.focus;
- return typeof text === 'string' && text.trim() ? text : null;
-}
-
export function unitLike(book, id) {
- return (book?.units || []).find((u) => u.id === id) || book?.info?.[id] || null;
+ return (book?.units || []).find((unit) => unit.id === id) || null;
}
export function stepTrack(track, index, delta) {
@@ -150,15 +60,22 @@ export function stepTrack(track, index, delta) {
return Math.max(0, Math.min(track.length - 1, want));
}
+/**
+ * Turn line stops into visual story segments.
+ *
+ * The ending is outside this map by design: finishing the book is a new
+ * experience, not an extra line inside the final scene.
+ */
export function segmentsOf(track, book) {
const out = [];
const index = new Map();
+
for (const stop of track) {
if (stop.kind === 'end') continue;
if (!index.has(stop.unit)) {
const unit = unitLike(book, stop.unit);
- const seg = {
+ const segment = {
id: stop.unit,
act: unit?.act || '',
title: unit?.title || stop.unit,
@@ -166,37 +83,29 @@ export function segmentsOf(track, book) {
from: stop.at,
to: stop.at,
lines: 0,
- said: 0,
- asks: 0,
};
- index.set(stop.unit, seg);
- out.push(seg);
- }
- const seg = index.get(stop.unit);
- seg.to = stop.at;
- if (stop.kind === 'line') {
- seg.lines += 1;
- if (!seg.plate && stop.plate) seg.plate = stop.plate;
- } else if (stop.kind === 'say') {
- seg.said += 1;
- if (!seg.plate && stop.plate) seg.plate = stop.plate;
- } else {
- seg.asks += 1;
- if (!seg.plate && stop.plate) seg.plate = stop.plate;
+ index.set(stop.unit, segment);
+ out.push(segment);
}
+
+ const segment = index.get(stop.unit);
+ segment.to = stop.at;
+ segment.lines += 1;
+ if (!segment.plate && stop.plate) segment.plate = stop.plate;
}
+
return out;
}
export function whereIn(segments, at) {
- const i = segments.findIndex((s) => at >= s.from && at <= s.to);
- const seg = segments[i] ?? null;
+ const index = segments.findIndex((segment) => at >= segment.from && at <= segment.to);
+ const segment = segments[index] ?? null;
return {
- index: i,
- segment: seg,
+ index,
+ segment,
of: segments.length,
- through: seg ? at - seg.from + 1 : 0,
- span: seg ? seg.to - seg.from + 1 : 0,
+ through: segment ? at - segment.from + 1 : 0,
+ span: segment ? segment.to - segment.from + 1 : 0,
};
}
From 1606a707772d7c142556f65d4c98056cc03099cf Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:56:34 +0700
Subject: [PATCH 050/110] Keep speech only for book framing
---
src/lib/speech/script.js | 91 ++++++++++++++--------------------------
1 file changed, 31 insertions(+), 60 deletions(-)
diff --git a/src/lib/speech/script.js b/src/lib/speech/script.js
index f87c3e4..e4f4490 100644
--- a/src/lib/speech/script.js
+++ b/src/lib/speech/script.js
@@ -1,20 +1,24 @@
-/** @typedef {{who:string, text:string, state?:string, clip?:string|null}} Turn */
+/** @typedef {{who:string,text:string,state?:string,clip?:string|null}} Turn */
export function castOf(book) {
const members = book?.cast?.members;
- const base = members && Object.keys(members).length
- ? members
- : {
- wren: { id: 'wren', name: 'Wren', role: 'guide' },
- prof: { id: 'prof', name: 'Grandpa Ambrose', role: 'expert' },
- };
+ const base =
+ members && Object.keys(members).length
+ ? members
+ : {
+ wren: { id: 'wren', name: 'Wren', role: 'guide' },
+ prof: { id: 'prof', name: 'Grandpa Ambrose', role: 'expert' },
+ };
const out = { ...base };
if (out.prof) {
const old = String(out.prof.name || '').trim().toLowerCase();
out.prof = {
...out.prof,
- name: !old || old === 'professor' || old === 'the professor' ? 'Grandpa Ambrose' : out.prof.name,
+ name:
+ !old || old === 'professor' || old === 'the professor'
+ ? 'Grandpa Ambrose'
+ : out.prof.name,
role: 'expert',
};
}
@@ -27,66 +31,33 @@ export function speaker(book, who) {
return members[id] || { id: String(id || 'wren'), name: '' };
}
-export function reactionsFor(book, unitId) {
- /** @type {Map} */
- const at = new Map();
- for (const r of book?.wrenReactions?.[unitId] || []) {
- if (!r?.line) continue;
- at.set(Number(r.at), {
- who: 'wren',
- text: r.line,
- state: r.state || '',
- clip: `wh_${unitId}_${r.at}`,
- });
- }
- return at;
-}
-
-export function talkFor(book, unitId) {
- return (book?.dialogue?.[unitId] || []).map((t, i) => ({
- who: speaker(book, t.who).id,
- text: t.text,
- state: t.state || '',
- clip: `d_${unitId}_${i}`,
- }));
-}
-
function clipOr(entry, fallback) {
return Object.hasOwn(entry || {}, 'clip') ? entry.clip : fallback;
}
-/** Before the work. New framing may deliberately set `clip: null` while
- * its rewritten audio is still being produced; Speaker then presents the
- * words without pretending an older recording matches them. */
+/**
+ * Short conversation before the literary work.
+ *
+ * Authored entries may set `clip: null` while replacement voice audio is
+ * being produced. The UI then shows the exact text instead of playing an
+ * older recording that says something different.
+ */
export function preshowRun(book) {
- return (book?.preshow || []).map((p, i) => ({
- who: speaker(book, p.who || 'wren').id,
- text: p.text,
- state: p.state || '',
- clip: clipOr(p, `g_pre${i}`),
+ return (book?.preshow || []).map((entry, index) => ({
+ who: speaker(book, entry.who || 'wren').id,
+ text: entry.text,
+ state: entry.state || '',
+ clip: clipOr(entry, `g_pre${index}`),
}));
}
+/** The matching conversation after the final line. */
export function afterwordRun(book) {
- const source = Array.isArray(book?.afterword) && book.afterword.length
- ? book.afterword
- : book?.dialogue?.impact || [];
-
- const authored = Array.isArray(book?.afterword) && book.afterword.length;
- return source.map((p, i) => ({
- who: speaker(book, p.who || (i % 2 ? 'prof' : 'wren')).id,
- text: p.text,
- state: p.state || '',
- clip: clipOr(p, authored ? `g_after${i}` : `d_impact_${i}`),
+ const source = Array.isArray(book?.afterword) ? book.afterword : [];
+ return source.map((entry, index) => ({
+ who: speaker(book, entry.who || (index % 2 ? 'prof' : 'wren')).id,
+ text: entry.text,
+ state: entry.state || '',
+ clip: clipOr(entry, `g_after${index}`),
}));
}
-
-export function helloRun(book) {
- const text = book?.guideVoice?.hello;
- return text ? [{ who: 'wren', text, state: 'happy', clip: 'g_hello' }] : [];
-}
-
-export function passIntroRun(book, pass) {
- const text = book?.guideVoice?.passIntro?.[String(pass)];
- return text ? [{ who: 'wren', text, state: 'talk', clip: `g_pass${pass}` }] : [];
-}
From ef13c0a7330050ee9d64e35eb625993ee4232214 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:56:56 +0700
Subject: [PATCH 051/110] Test Wren and Ambrose only as framing voices
---
src/lib/speech/speech.test.js | 347 ++++++++++++----------------------
1 file changed, 118 insertions(+), 229 deletions(-)
diff --git a/src/lib/speech/speech.test.js b/src/lib/speech/speech.test.js
index 2416af6..8778167 100644
--- a/src/lib/speech/speech.test.js
+++ b/src/lib/speech/speech.test.js
@@ -1,14 +1,5 @@
import { describe, it, expect } from 'vitest';
-import book from '../../books/fixture/index.js';
-import {
- castOf,
- speaker,
- reactionsFor,
- talkFor,
- preshowRun,
- helloRun,
- passIntroRun,
-} from './script.js';
+import { castOf, speaker, preshowRun, afterwordRun } from './script.js';
import {
createSpeech,
speak,
@@ -22,293 +13,191 @@ import {
progressOf,
} from './queue.js';
import { loadHeard, saveHeard, clearHeard } from './heard.js';
-import { trackFor } from '../reader/track.js';
-import { beatsOfBook } from '../reader/beats.js';
-
-/**
- * Who speaks, when, and one at a time — against the engine's own
- * fixture book.
- *
- * Whether a pack's spoken lines all have recordings behind them is a
- * fact about that pack; it is checked in `books/magi/pack.test.js`.
- */
-/** Every reaction the book gives a line to, across the whole book. */
-const spokenReactions = () =>
- Object.values(book.wrenReactions)
- .flat()
- .filter((r) => r.line).length;
+const book = {
+ cast: {
+ members: {
+ wren: { id: 'wren', name: 'Wren', role: 'guide', art: 'art/wren.webp' },
+ prof: { id: 'prof', name: 'Professor', role: 'expert', art: 'art/ambrose.webp' },
+ },
+ },
+ preshow: [
+ { who: 'wren', text: 'I brought the book.', state: 'happy', clip: null },
+ { who: 'prof', text: 'Then let the book speak.', state: 'warm', clip: null },
+ ],
+ afterword: [
+ { who: 'wren', text: 'That ending landed.', state: 'thinking', clip: null },
+ { who: 'ambrose', text: 'Now we may look at how it was built.', state: 'warm', clip: null },
+ ],
+};
-/** Every turn of conversation in the book. */
-const dialogueTurns = () => Object.values(book.dialogue).flat().length;
+const pre = () => preshowRun(book);
+const after = () => afterwordRun(book);
-describe('the cast', () => {
- it('is the people the pack names, with names and faces', () => {
+describe('the framing cast', () => {
+ it('uses the pack’s people while normalising the old Professor name', () => {
const members = castOf(book);
- expect(Object.keys(members)).toEqual(Object.keys(book.cast.members));
- expect(Object.keys(members).length).toBeGreaterThan(1);
- for (const m of Object.values(members)) {
- expect(m.name).toBeTruthy();
- expect(m.art, `${m.name} has no picture`).toMatch(/^art\/.+\.(webp|png|jpe?g)$/);
- }
+ expect(members.wren.name).toBe('Wren');
+ expect(members.prof.name).toBe('Grandpa Ambrose');
+ expect(members.prof.role).toBe('expert');
});
- it('answers to the short names the conversations are written in', () => {
- /* The book writes 'w' and 'p' in its conversations and full ids
- everywhere else. The names come from the pack — this pack calls
- them Pip and Marlow — so a second title renames them for free. */
+ it('keeps the old short aliases so migrated packs do not need rewriting', () => {
expect(speaker(book, 'w').id).toBe('wren');
expect(speaker(book, 'p').id).toBe('prof');
- expect(speaker(book, 'wren').name).toBe(book.cast.members.wren.name);
- expect(speaker(book, 'p').name).toBe(book.cast.members.prof.name);
+ expect(speaker(book, 'ambrose').id).toBe('prof');
});
- it('still speaks for a book that ships no cast', () => {
- expect(Object.keys(castOf({})).length).toBeGreaterThan(0);
- expect(speaker({}, 'w').id).toBe('wren');
+ it('has safe defaults for a pack with no cast', () => {
+ expect(speaker({}, 'w').name).toBe('Wren');
+ expect(speaker({}, 'p').name).toBe('Grandpa Ambrose');
});
});
-describe('what they say', () => {
- it('gives the guide a reaction only where the book gave her a line', () => {
- let faces = 0;
- let lines = 0;
- for (const [unitId, list] of Object.entries(book.wrenReactions)) {
- faces += list.length;
- lines += reactionsFor(book, unitId).size;
- }
- expect(lines).toBe(spokenReactions());
- expect(lines, 'a reaction with no line is a face, not an interruption').toBeLessThan(faces);
+describe('before and after the work', () => {
+ it('maps the preshow exactly and respects explicit text-only turns', () => {
+ expect(pre()).toHaveLength(2);
+ expect(pre().map((turn) => turn.who)).toEqual(['wren', 'prof']);
+ expect(pre().every((turn) => turn.clip === null)).toBe(true);
});
- it('has a conversation for every part of the story', () => {
- for (const u of book.units) expect(talkFor(book, u.id).length, u.id).toBeGreaterThan(0);
+ it('maps the afterword exactly and resolves Ambrose aliases', () => {
+ expect(after()).toHaveLength(2);
+ expect(after().map((turn) => turn.who)).toEqual(['wren', 'prof']);
+ expect(after().every((turn) => turn.clip === null)).toBe(true);
});
- it('names both people in a conversation, never a raw w or p', () => {
- const who = new Set(book.units.flatMap((u) => talkFor(book, u.id).map((t) => t.who)));
- expect([...who].sort()).toEqual(['prof', 'wren']);
- });
-
- it('has a preshow, a greeting and an introduction to each reading', () => {
- expect(preshowRun(book)).toHaveLength(book.preshow.length);
- expect(book.preshow.length).toBeGreaterThan(1);
- expect(helloRun(book)).toHaveLength(1);
- for (const pass of [1, 2, 3]) expect(passIntroRun(book, pass)).toHaveLength(1);
+ it('returns no framing for a book that authored none', () => {
+ expect(preshowRun({})).toEqual([]);
+ expect(afterwordRun({})).toEqual([]);
});
- it('gives nothing back for a book that has none of it', () => {
- expect(preshowRun({})).toEqual([]);
- expect(helloRun({})).toEqual([]);
- expect(passIntroRun({}, 1)).toEqual([]);
- expect(talkFor({}, 'p1')).toEqual([]);
- expect(reactionsFor({}, 'p1').size).toBe(0);
+ it('assigns predictable clip ids when a pack does not specify them', () => {
+ const spoken = {
+ preshow: [{ who: 'wren', text: 'Before' }],
+ afterword: [{ who: 'prof', text: 'After' }],
+ };
+ expect(preshowRun(spoken)[0].clip).toBe('g_pre0');
+ expect(afterwordRun(spoken)[0].clip).toBe('g_after0');
});
});
-const hello = () => helloRun(book);
-const pre = () => preshowRun(book);
-
-describe('one queue, one owner', () => {
- it('says nothing until somebody claims it', () => {
+describe('one framing queue, one owner', () => {
+ it('says nothing until something claims the queue', () => {
expect(speaking(createSpeech())).toBeNull();
});
- it('lets at most one person speak — there is no state for two', () => {
- let s = speak(createSpeech(), 'hello', hello());
- expect(speaking(s)).not.toBeNull();
+ it('never has two simultaneous speakers', () => {
+ let state = speak(createSpeech(), 'before', pre());
+ expect(speaking(state)).not.toBeNull();
- /* the shape of the old bug: a second caller arriving mid-speech */
- s = speak(s, 'preshow', pre());
- const talking = speaking(s);
- expect(talking).not.toBeNull();
- expect(Array.isArray(talking)).toBe(false);
- expect(s.key, 'the newer claim owns the queue').toBe('preshow');
- expect(s.turns).toEqual(pre());
+ state = speak(state, 'after', after());
+ expect(Array.isArray(speaking(state))).toBe(false);
+ expect(state.key).toBe('after');
+ expect(state.turns).toEqual(after());
});
- it('walks its turns in order and then closes', () => {
+ it('walks turns in order and closes at the end', () => {
const turns = pre();
- let s = speak(createSpeech(), 'preshow', turns);
- for (let n = 0; n < turns.length; n++) {
- expect(speaking(s).text).toBe(turns[n].text);
- expect(progressOf(s)).toEqual({ at: n + 1, of: turns.length });
- expect(isLast(s)).toBe(n === turns.length - 1);
- s = next(s);
+ let state = speak(createSpeech(), 'before', turns);
+ for (let index = 0; index < turns.length; index++) {
+ expect(speaking(state).text).toBe(turns[index].text);
+ expect(progressOf(state)).toEqual({ at: index + 1, of: turns.length });
+ expect(isLast(state)).toBe(index === turns.length - 1);
+ state = next(state);
}
- expect(s.open).toBe(false);
- expect(speaking(s)).toBeNull();
+ expect(state.open).toBe(false);
+ expect(speaking(state)).toBeNull();
});
- it('goes back a turn, but not off the front', () => {
- const turns = pre();
- let s = speak(createSpeech(), 'preshow', turns);
- s = next(s);
- expect(speaking(back(s)).text).toBe(turns[0].text);
- expect(back(back(s)).at).toBe(0);
+ it('goes back without running off the front', () => {
+ let state = next(speak(createSpeech(), 'before', pre()));
+ expect(speaking(back(state)).text).toBe(pre()[0].text);
+ expect(back(back(state)).at).toBe(0);
});
- it('ignores an empty claim rather than opening on nothing', () => {
- const s = createSpeech();
- expect(speak(s, 'nope', [])).toBe(s);
- expect(speak(s, '', hello())).toBe(s);
+ it('ignores empty claims', () => {
+ const state = createSpeech();
+ expect(speak(state, 'empty', [])).toBe(state);
+ expect(speak(state, '', pre())).toBe(state);
});
});
-describe('dismissed stays dismissed', () => {
- it('does not say hello twice', () => {
- let s = speak(createSpeech(), 'hello', hello());
- s = close(s);
- expect(wasHeard(s, 'hello')).toBe(true);
-
- const again = speak(s, 'hello', hello());
- expect(again.open, 'the greeting came back').toBe(false);
- expect(speaking(again)).toBeNull();
- });
-
- it('counts sitting through it as having heard it', () => {
- let s = speak(createSpeech(), 'hello', hello());
- s = next(s); // one turn, so this reaches the end
- expect(wasHeard(s, 'hello')).toBe(true);
- expect(speak(s, 'hello', hello()).open).toBe(false);
+describe('dismissed framing stays dismissed', () => {
+ it('does not immediately reopen something the reader closed', () => {
+ let state = close(speak(createSpeech(), 'before', pre()));
+ expect(wasHeard(state, 'before')).toBe(true);
+ expect(speak(state, 'before', pre()).open).toBe(false);
});
- it('does not restart what is already open', () => {
- let s = speak(createSpeech(), 'preshow', pre());
- s = next(s);
- s = next(s);
- expect(speak(s, 'preshow', pre()).at, 'jumped back to the start').toBe(2);
+ it('counts reaching the end as heard', () => {
+ let state = speak(createSpeech(), 'before', pre());
+ while (state.open) state = next(state);
+ expect(wasHeard(state, 'before')).toBe(true);
});
- it('plays it again when asked outright', () => {
- let s = close(speak(createSpeech(), 'hello', hello()));
- s = speak(s, 'hello', hello(), { again: true });
- expect(s.open).toBe(true);
+ it('does not restart an already-open conversation', () => {
+ let state = next(speak(createSpeech(), 'before', pre()));
+ expect(speak(state, 'before', pre()).at).toBe(1);
});
- it('can forget everything, for the next person to use the device', () => {
- const s = forget(close(speak(createSpeech(), 'hello', hello())));
- expect(s.heard).toEqual([]);
- expect(speak(s, 'hello', hello()).open).toBe(true);
+ it('can replay when explicitly asked', () => {
+ let state = close(speak(createSpeech(), 'before', pre()));
+ state = speak(state, 'before', pre(), { again: true });
+ expect(state.open).toBe(true);
});
- it('starts from what was heard on the last visit', () => {
- expect(speak(createSpeech(['hello']), 'hello', hello()).open).toBe(false);
+ it('can forget framing history', () => {
+ const state = forget(close(speak(createSpeech(), 'before', pre())));
+ expect(state.heard).toEqual([]);
+ expect(speak(state, 'before', pre()).open).toBe(true);
});
});
-describe('remembering it between visits', () => {
+describe('remembering framing between visits', () => {
function fakeStore(behaviour = 'ok') {
const map = new Map();
return {
get length() {
return map.size;
},
- key: (i) => [...map.keys()][i] ?? null,
+ key: (index) => [...map.keys()][index] ?? null,
clear: () => map.clear(),
- getItem: (k) => (map.has(k) ? map.get(k) : null),
- setItem: (k, v) => {
+ getItem: (key) => (map.has(key) ? map.get(key) : null),
+ setItem: (key, value) => {
if (behaviour !== 'ok') throw new Error('QuotaExceededError');
- map.set(k, v);
- },
- removeItem: (k) => {
- map.delete(k);
+ map.set(key, value);
},
+ removeItem: (key) => map.delete(key),
_map: map,
};
}
- it('survives a round trip', () => {
- const s = fakeStore();
- expect(saveHeard('fixture', ['hello', 'preshow'], s)).toBe(true);
- expect(loadHeard('fixture', s)).toEqual(['hello', 'preshow']);
- clearHeard('fixture', s);
- expect(loadHeard('fixture', s)).toEqual([]);
+ it('survives a round trip and can be cleared', () => {
+ const store = fakeStore();
+ expect(saveHeard('fixture', ['before', 'after'], store)).toBe(true);
+ expect(loadHeard('fixture', store)).toEqual(['before', 'after']);
+ clearHeard('fixture', store);
+ expect(loadHeard('fixture', store)).toEqual([]);
});
- it('says so when the device will not save, rather than pretending', () => {
- expect(saveHeard('fixture', ['hello'], fakeStore('full'))).toBe(false);
+ it('reports when the device refuses storage', () => {
+ expect(saveHeard('fixture', ['before'], fakeStore('full'))).toBe(false);
});
- it('treats what is in the store as input, not truth', () => {
- const s = fakeStore();
+ it('treats stored data as untrusted input', () => {
+ const store = fakeStore();
for (const junk of ['not json', '{"a":1}', '"hello"', 'null']) {
- s._map.set('reader.heard.v1.fixture', junk);
- expect(loadHeard('fixture', s)).toEqual([]);
- }
- s._map.set('reader.heard.v1.fixture', JSON.stringify(['hello', 7, null, 'preshow']));
- expect(loadHeard('fixture', s)).toEqual(['hello', 'preshow']);
- });
-
- it('greets a reader properly when they open a different book', () => {
- const s = fakeStore();
- saveHeard('fixture', ['hello'], s);
- expect(loadHeard('other', s)).toEqual([]);
- });
-});
-
-describe('speech in the reading', () => {
- it('puts the two of them in the first reading and nowhere else', () => {
- /* Counted back off the raw book rather than written down: the
- failure to catch is the track dropping turns, and a number copied
- from the track would move with the bug. */
- const said = (pass) => trackFor(book, pass).filter((s) => s.kind === 'say');
- expect(said(1)).toHaveLength(spokenReactions() + dialogueTurns());
- /* readings 2 and 3 have their own task: a question is hard enough to
- answer without someone talking over the passage it is about */
- expect(said(2)).toHaveLength(0);
- expect(said(3)).toHaveLength(0);
- });
-
- it('never puts two speakers on one stop', () => {
- for (const stop of trackFor(book, 1)) {
- if (stop.kind !== 'say') continue;
- expect(typeof stop.turn.who).toBe('string');
- expect(stop.turn.text).toBeTruthy();
- }
- });
-
- it('has the guide react to the line she is reacting to, right after it', () => {
- const t = trackFor(book, 1);
- for (let i = 0; i < t.length; i++) {
- if (t[i].kind !== 'say' || !/^wh_/.test(t[i].turn.clip || '')) continue;
- const before = t[i - 1];
- expect(before.kind).toBe('line');
- expect(t[i].turn.clip).toBe(`wh_${before.unit}_${before.i}`);
- }
- });
-
- it('keeps the conversations about the material that is never read aloud', () => {
- /* Turns that hang off units which are not read segments. The first
- draft dropped them on the floor, which is exactly the sort of loss
- nobody notices — the reading still works, and a slice of what they
- say is simply gone. */
- const t = trackFor(book, 1);
- for (const id of Object.keys(book.info)) {
- const turns = t.filter((s) => s.kind === 'say' && s.unit === id);
- expect(turns.length, id).toBe(book.dialogue[id].length);
- }
- });
-
- it('holds the conversation after the part, not during it', () => {
- const t = trackFor(book, 1);
- for (const stop of t) {
- if (stop.kind !== 'say' || !/^d_/.test(stop.turn.clip || '')) continue;
- const lines = t.filter((s) => s.kind === 'line' && s.unit === stop.unit);
- /* the background pages are talked about but never read aloud;
- those conversations come after the whole story rather than
- after a part of it */
- if (!lines.length) continue;
- expect(lines[lines.length - 1].at).toBeLessThan(stop.at);
+ store._map.set('reader.heard.v1.fixture', junk);
+ expect(loadHeard('fixture', store)).toEqual([]);
}
+ store._map.set('reader.heard.v1.fixture', JSON.stringify(['before', 7, null, 'after']));
+ expect(loadHeard('fixture', store)).toEqual(['before', 'after']);
});
- it('leaves reading 1 as one line at a time, plus the talking', () => {
- const t = trackFor(book, 1);
- const lines = beatsOfBook(book).length;
- expect(t.filter((s) => s.kind === 'line')).toHaveLength(lines);
- /* and one more stop at the end, which is the ending itself */
- expect(t).toHaveLength(lines + spokenReactions() + dialogueTurns() + 1);
- expect(t[t.length - 1].kind).toBe('end');
+ it('keeps each book’s framing history separate', () => {
+ const store = fakeStore();
+ saveHeard('fixture', ['before'], store);
+ expect(loadHeard('other', store)).toEqual([]);
});
});
From f1b94baa1f512b455ae3ac62228ed5542a2e6d70 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:57:17 +0700
Subject: [PATCH 052/110] Match storyboard tests to line-only segments
---
src/lib/reader/track.test.js | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/lib/reader/track.test.js b/src/lib/reader/track.test.js
index b428c38..4d532ca 100644
--- a/src/lib/reader/track.test.js
+++ b/src/lib/reader/track.test.js
@@ -71,7 +71,7 @@ describe('the storyboard', () => {
expect(segments.reduce((count, segment) => count + segment.lines, 0)).toBe(
beatsOfBook(book).length
);
- expect(segments.every((segment) => segment.said === 0 && segment.asks === 0)).toBe(true);
+ expect(segments.every((segment) => !('said' in segment) && !('asks' in segment))).toBe(true);
});
it('locates story positions and deliberately leaves the ending outside the storyboard', () => {
From 9f6ee5c5e8f251cb2e68268344b556478d9474f6 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:57:32 +0700
Subject: [PATCH 053/110] Remove classroom UI
---
src/ui/Class.jsx | 431 -----------------------------------------------
1 file changed, 431 deletions(-)
delete mode 100644 src/ui/Class.jsx
diff --git a/src/ui/Class.jsx b/src/ui/Class.jsx
deleted file mode 100644
index 279314a..0000000
--- a/src/ui/Class.jsx
+++ /dev/null
@@ -1,431 +0,0 @@
-import { useEffect, useId, useMemo, useState } from 'react';
-import { T } from './useUi.jsx';
-import { useBook } from './useBook.jsx';
-import {
- mintOwner,
- classKey,
- readClassKey,
- joinCode,
- safeApi,
- loadOwner,
- saveOwner,
- loadApi,
- saveApi,
- OWNER_KEY,
- API_KEY,
-} from '../lib/class/key.js';
-import { loadOutbox, saveOutbox, waiting, flush } from '../lib/class/outbox.js';
-import { senderFor } from '../lib/class/send.js';
-import { KEY as STUDENT_KEY } from '../lib/class/student.js';
-import { qrPath } from '../lib/qr/svg.js';
-import SheetSetup from './SheetSetup.jsx';
-import Gradebook from './Gradebook.jsx';
-import Overlay from './Overlay.jsx';
-
-/**
- * The teacher's side.
- *
- * Everything here rests on one idea: the teacher is whoever set the
- * class up, because nobody else was there. So there is nothing to log
- * in to. Setting a class up mints a key on this device, and that key —
- * written down once — is what makes any other device the teacher's too.
- *
- * Two things are said out loud on this screen rather than left for
- * someone to discover:
- *
- * the class key is the way back, and the reset button is not
- * the link the class gets is not the key, and cannot be used as one
- */
-
-/** Where the reader is being served from, minus any query or hash. */
-function hereUrl() {
- try {
- const u = new URL(globalThis.location.href);
- u.hash = '';
- u.search = '';
- return u.toString().replace(/[?#]$/, '');
- } catch {
- return '';
- }
-}
-
-/**
- * The class link as a code to point a camera at.
- *
- * A link is a fine thing to have and a poor thing to give thirty people
- * at once. Read aloud it is a hundred and fifty characters of base32;
- * written on a board it is a typo per student; sent to their phones it
- * needs a channel a teacher may not have. Held up, it takes a second and
- * needs nothing.
- *
- * What is encoded is the JOIN LINK and never the class key. They are one
- * character apart on this screen and the difference is the whole security
- * model: the join link points a device at a Sheet, and the class key is
- * what makes a device the teacher's. A code carrying the key would hand
- * every student in the room the gradebook, silently, and it would look
- * exactly like this one.
- *
- * @param {{value:string, alt:string, className?:string}} props
- */
-function QrCode({ value, alt, className = '' }) {
- /* Encoding is a few milliseconds of Reed-Solomon and eight masks
- scored, which is nothing once but not nothing on every keystroke in
- the class-name field above. */
- const code = useMemo(() => {
- try {
- return qrPath(value);
- } catch {
- /* Too long to encode. The link is on screen as text and the copy
- button works, so this is a missing convenience, not a dead end —
- and saying so beats drawing something unscannable. */
- return null;
- }
- }, [value]);
-
- if (!code) return This link is too long to put in a code.
;
-
- return (
-
-
- );
-}
-
-export default function Class() {
- /* Whose class this is depends on which book is being read: the outbox
- and the gradebook are both filed per book, and a teacher looking at
- one book's marks must not be shown another's. Asked for on every
- render rather than read once, because "which book" is now a thing
- that can change. */
- const { id: bookId, title: bookTitle } = useBook();
- const id = useId();
- const [owner, setOwner] = useState(() => loadOwner());
- const [api, setApi] = useState(() => loadApi());
- const [outbox, setOutbox] = useState(() => loadOutbox(bookId));
-
- const [cls, setCls] = useState(() => loadOwner()?.cls || '');
- const [sheet, setSheet] = useState('');
- const [paste, setPaste] = useState('');
- const [said, setSaid] = useState('');
- const [confirmReset, setConfirmReset] = useState('');
- const [showing, setShowing] = useState(false);
-
- /* Said once and then gone, so a teacher is not reading last week's
- confirmation as if it were this one. */
- useEffect(() => {
- if (!said) return undefined;
- const t = setTimeout(() => setSaid(''), 6000);
- return () => clearTimeout(t);
- }, [said]);
-
- const key = owner ? classKey(owner, api) : '';
- const join = api ? joinCode(api, owner?.cls || cls) : '';
- const link = join ? `${hereUrl()}#/?join=${join}` : '';
- const queue = waiting(outbox);
-
- const copy = async (text, what) => {
- try {
- await navigator.clipboard.writeText(text);
- setSaid(`${what} copied.`);
- } catch {
- /* A locked clipboard is not a failure worth a dialog — the text
- is on screen and selectable, which is what a teacher will do
- anyway. */
- setSaid(`Select the ${what.toLowerCase()} and copy it.`);
- }
- };
-
- /* ---------------------------------------------------------------- */
-
- if (!owner) {
- return (
-
-
- Class
-
-
- Setting a class up on this device is what makes you its teacher. There is nothing to
- log in to and no password to lose.
-
-
-
-
-
-
- {said ? (
-
- {said}
-
- ) : null}
-
- );
- }
-
- return (
-
-
- Class
- {owner.cls ? {owner.cls} : null}
-
-
-
- Your class key
-
- Write this down once. It is the way back if this device dies, if you teach from
- another machine, or if someone covers your lesson. The reset button is not.
-
- {key}
-
- copy(key, 'Class key')}>
- Copy the class key
-
-
-
-
-
-
-
- The link for your class
-
- This points a student’s device at your Sheet. It is not your class key
- and cannot be used as one — a student who keeps it cannot open your gradebook.
-
-
-
-
-
- Students point a camera at this and the reader opens already joined. Nothing to
- type, and nothing to read out.
-
-
{link}
-
-
- setShowing(true)}>
- Show it big
-
- copy(link, 'Class link')}>
- Copy the link
-
-
-
- ) : null}
-
- {/* Full screen, because the code has to be read from the back of
- the room. A rather than a new route: it is the same
- screen made big for thirty seconds, and Escape should put it
- back — which the platform already does. */}
- setShowing(false)}
- title={owner.cls ? `Join ${owner.cls}` : 'Join this class'}
- className="qr-big"
- >
- Point a camera at this.
-
-
-
- Waiting to be sent
- {queue.count === 0 ? (
- Nothing is waiting. Everything handed in has gone.
- ) : (
- <>
-
- {queue.count} {queue.count === 1 ? 'piece' : 'pieces'} of work handed in on
- this device {queue.count === 1 ? 'has' : 'have'} not reached the Sheet yet.
- {queue.stuck
- ? ` ${queue.stuck} of them has been tried several times — check the link above.`
- : ''}
-
- {
- const { items, sent } = await flush(outbox, senderFor(api));
- saveOutbox(bookId, items);
- setOutbox(items);
- setSaid(sent ? `${sent} sent.` : 'Still nothing getting through.');
- }}
- >
- Try again now
-
-
- )}
-
-
-
-
- {said ? (
-
- {said}
-
- ) : null}
-
- );
-}
From b68fe9c6148f1b69cb8bad6bb39be73ac0613280 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:57:38 +0700
Subject: [PATCH 054/110] Remove classroom UI tests
---
src/ui/Class.test.jsx | 126 ------------------------------------------
1 file changed, 126 deletions(-)
delete mode 100644 src/ui/Class.test.jsx
diff --git a/src/ui/Class.test.jsx b/src/ui/Class.test.jsx
deleted file mode 100644
index 2110cc2..0000000
--- a/src/ui/Class.test.jsx
+++ /dev/null
@@ -1,126 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import Class from './Class.jsx';
-import book from '../books/fixture/index.js';
-import { BookProvider } from './useBook.jsx';
-import { encode } from '../lib/qr/encode.js';
-import { qrPath } from '../lib/qr/svg.js';
-import { classKey, joinCode, mintOwner, readJoin, readClassKey } from '../lib/class/key.js';
-
-/**
- * What the code on the wall actually contains.
- *
- * This is the one thing about the QR feature that is worth more than a
- * screenshot. The class panel shows two long strings a few centimetres
- * apart — the class key, which makes a device the teacher's, and the
- * join link, which does not — and a QR code renders both of them as the
- * same anonymous field of squares. Encoding the wrong one hands the
- * gradebook to every student who scans it, and there is no way to see
- * that by looking.
- *
- * So the code is decoded back here, and asserted to be the join link.
- * The rest of the teacher panel is covered end to end in
- * `e2e/teacher.spec.js`; this is the assertion that has to hold in the
- * same commit as the feature.
- */
-
-const API =
- 'https://script.google.com/macros/s/AKfycbwABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abc/exec';
-
-/**
- * Read the drawn code back out of the DOM.
- *
- * The path is the only place the encoded text survives in the rendered
- * output, so the way to find out what was encoded is to find the input
- * whose path matches it. Which is enough: the join link and the class
- * key produce entirely different symbols, and a match on the whole path
- * is a match on every module.
- */
-function drawnMatches(svg, text) {
- const drawn = svg.querySelector('path')?.getAttribute('d');
- return !!drawn && drawn === qrPath(text).d;
-}
-
-beforeEach(() => {
- localStorage.clear();
-});
-
-/**
- * The teacher's panel, on the book the app is showing.
- *
- * Which book that is arrives through the provider, not as a prop: the
- * outbox and the gradebook are filed per book, and the panel has to read
- * that off the reading rather than off anything decided when this file
- * loaded.
- */
-function open() {
- return render(
-
-
- );
-}
-
-/** Set this device up as a teacher with a Sheet connected. */
-function asTeacher(cls = '1-A') {
- const owner = mintOwner(cls);
- localStorage.setItem('reader.teacher.owner.v1', JSON.stringify(owner));
- localStorage.setItem('reader.api.v1', API);
- return owner;
-}
-
-describe('the code the class scans', () => {
- it('carries the join link, and not the class key', () => {
- /* The prototype handed students the class key. Anyone who kept the
- link could open the gradebook, and a QR code is the easiest way
- yet invented to hand a whole room something by mistake. */
- const owner = asTeacher();
- open();
-
- const svg = screen.getAllByRole('img', { name: /code holding the link/i })[0];
- expect(svg).toBeInTheDocument();
-
- const join = joinCode(API, '1-A');
- const link = `${globalThis.location.origin}${globalThis.location.pathname}#/?join=${join}`;
- expect(drawnMatches(svg, link), 'the code is not the join link').toBe(true);
- expect(
- drawnMatches(svg, classKey(owner, API)),
- 'the class key was encoded into the code'
- ).toBe(false);
- });
-
- it('encodes something a student device can act on and a teacher cannot be made from', () => {
- /* Belt and braces on the payload itself rather than on the drawing:
- what a scan produces has to read as a join code and must not read
- as a class key. */
- const join = joinCode(API, '1-A');
- expect(readJoin(join)).toEqual({ api: API, cls: '1-A' });
- expect(readClassKey(join)).toBeNull();
-
- const link = `https://example.test/reader/#/?join=${join}`;
- /* and it has to fit in a symbol at all, at a realistic length */
- expect(() => encode(link)).not.toThrow();
- expect(encode(link).version).toBeLessThanOrEqual(10);
- });
-
- it('is not shown at all until there is a Sheet to point a device at', () => {
- /* Without an endpoint there is no join code, so a code here would
- encode a link that joins nothing. */
- localStorage.setItem('reader.teacher.owner.v1', JSON.stringify(mintOwner('1-A')));
- open();
- expect(screen.queryByRole('img', { name: /code holding the link/i })).toBeNull();
- });
-
- it('has a way to make it big enough to read from the back of the room', () => {
- asTeacher();
- open();
- expect(screen.getByRole('button', { name: /Show it big/i })).toBeInTheDocument();
- });
-
- it('describes itself to a screen reader instead of being an unnamed picture', () => {
- asTeacher();
- open();
- const svg = screen.getAllByRole('img', { name: /code holding the link/i })[0];
- expect(svg.getAttribute('aria-label')).toMatch(/link for your class/i);
- });
-});
From 382bd8c6f0ae4de16c9369a959600f80aea9bbbc Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:57:45 +0700
Subject: [PATCH 055/110] Remove gradebook UI
---
src/ui/Gradebook.jsx | 216 -------------------------------------------
1 file changed, 216 deletions(-)
delete mode 100644 src/ui/Gradebook.jsx
diff --git a/src/ui/Gradebook.jsx b/src/ui/Gradebook.jsx
deleted file mode 100644
index dd05374..0000000
--- a/src/ui/Gradebook.jsx
+++ /dev/null
@@ -1,216 +0,0 @@
-import { useRef, useState } from 'react';
-import { buildCsv } from '../lib/gradebook/csv.js';
-import { markingWorkbook } from '../lib/gradebook/workbook.js';
-import { MIME as XLSX_MIME } from '../lib/gradebook/xlsx.js';
-import {
- loadCollected,
- saveCollected,
- clearCollected,
- collect,
- summarise,
- fileName,
-} from '../lib/gradebook/collected.js';
-
-/**
- * The work gathered on this device, and the workbook that marks it.
- *
- * For a room with no Google in it. Where a Sheet is connected the work
- * goes there and this stays empty — they are two answers to the same
- * question and a school will want one of them.
- *
- * The table is deliberately short on columns. Everything is in the
- * workbook; this is here so a teacher can see that the pile they dropped
- * in arrived, and whose is missing.
- */
-
-function download(data, name, type) {
- const url = URL.createObjectURL(new Blob([data], { type }));
- const a = document.createElement('a');
- a.href = url;
- a.download = name;
- document.body.appendChild(a);
- a.click();
- a.remove();
- /* revoked on the next turn, not immediately: Safari has not started
- the download by the time click() returns */
- setTimeout(() => URL.revokeObjectURL(url), 30_000);
-}
-
-/**
- * @param {object} props
- * @param {string} props.bookId
- * @param {string} props.bookTitle
- */
-export default function Gradebook({ bookId, bookTitle }) {
- const [rows, setRows] = useState(() => loadCollected(bookId));
- const [said, setSaid] = useState('');
- const [wipe, setWipe] = useState(false);
- const picker = useRef(/** @type {HTMLInputElement|null} */ (null));
-
- const take = async (fileList) => {
- const files = await Promise.all(
- [...fileList].map(async (f) => ({ name: f.name, text: await f.text() }))
- );
- const result = collect(rows, files);
- setRows(result.rows);
- saveCollected(bookId, result.rows);
- setSaid(summarise(result));
- };
-
- const marks = (r) =>
- typeof r.percentNum === 'number'
- ? `${r.percentNum}%`
- : r.scoreNum === ''
- ? '—'
- : r.scoreNum;
-
- return (
-
- Work collected on this device
-
- {rows.length === 0 ? (
-
- Nothing yet. If your class hands in to files rather than to a Sheet, drop them here —
- the marking workbook is built from whatever is in this list.
-
- ) : (
-
- {rows.length} {rows.length === 1 ? 'piece' : 'pieces'} of work, from{' '}
- {new Set(rows.map((r) => `${r.cls}|${r.name}`)).size} students.
-
- )}
-
-
- {/* The button below is the control; this is the machinery it
- drives. Out of the accessibility tree entirely rather than
- merely out of sight — an unlabelled file input announced to
- a screen reader is a second, worse way to do the same thing,
- and axe was right to say so. */}
- picker.current?.click()}>
- Add handed-in files
-
-
- {
- const bytes = markingWorkbook(rows);
- if (bytes) {
- download(bytes, fileName(bookTitle, rows, 'xlsx'), XLSX_MIME);
- setSaid('Workbook saved. Mark on the Answers sheet; the Grades sheet follows.');
- }
- }}
- >
- Marking workbook
-
-
- {
- download(
- buildCsv(rows),
- fileName(bookTitle, rows, 'csv'),
- 'text/csv;charset=utf-8'
- );
- setSaid('CSV saved.');
- }}
- >
- CSV
-
-
-
- {rows.length > 0 ? (
- <>
- {/* The table scrolls inside itself once a class is thirty
- long, and a scrollable box has to be reachable from the
- keyboard or it cannot be read without a mouse. Caught on
- the phone profile, where the box is short enough to
- overflow with two rows in it. */}
- {/* eslint-disable jsx-a11y/no-noninteractive-tabindex */}
-
-
- Work collected on this device
-
-
- Class
- No.
- Name
- Assignment
- Marks
- Handed in
-
-
-
- {rows.map((r) => (
-
- {r.cls}
- {r.no}
- {r.name}
- {r.assignment}
- {marks(r)}
- {String(r.when || '').slice(0, 10)}
-
- ))}
-
-
-
- {
- clearCollected(bookId);
- setRows([]);
- setWipe(false);
- setSaid('Cleared. Save the workbook first next time.');
- }}
- >
- Yes, remove all {rows.length}
-
- setWipe(false)}>
- Keep it
-
-
- ) : (
- setWipe(true)}>
- Remove the collected work
-
- )}
-
- ) : null}
-
- {said ? (
-
- {said}
-
- ) : null}
-
- );
-}
From ea30be04322f4a827b1d3489a799f5fe184762c0 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:57:53 +0700
Subject: [PATCH 056/110] Remove classroom learning guide
---
src/ui/Guide.jsx | 340 -----------------------------------------------
1 file changed, 340 deletions(-)
delete mode 100644 src/ui/Guide.jsx
diff --git a/src/ui/Guide.jsx b/src/ui/Guide.jsx
deleted file mode 100644
index 461c705..0000000
--- a/src/ui/Guide.jsx
+++ /dev/null
@@ -1,340 +0,0 @@
-import { useEffect, useMemo } from 'react';
-import { Link, useLocation, useOutletContext } from 'react-router-dom';
-import { guideOutline, contentsOf, anchorFor, TOP } from '../lib/guide/outline.js';
-import { T } from './useUi.jsx';
-import { useBook } from './useBook.jsx';
-
-/**
- * The learning guide, which is also the teacher's guide.
- *
- * It owns no content. Every heading, every count and every word in it
- * comes out of `lib/guide/outline.js`, which comes out of the book pack —
- * so this file is the arrangement, the anchors and the printing, and a
- * second title needs none of it changed.
- *
- * Two things it deliberately does not build:
- *
- * an accordion — the parts of the plan are ``, so they open
- * with a click, with a keyboard, with find-in-page, and on paper.
- *
- * a print dialog — the button calls the one the browser already has.
- * "Exportable for compliance" is print-to-PDF, which every device a
- * school owns can already do, and which produces a file a department
- * can open in ten years.
- */
-
-/**
- * Jump to a section.
- *
- * The router is a hash router, because itch serves this from a static
- * path with no server to rewrite URLs. That has one consequence right
- * here: the fragment belongs to the router, so a bare `href="#words"`
- * would not scroll — it would navigate to a route called `words`, miss,
- * and bounce the reader to the front page.
- *
- * So the links are real links to a real location — `#/guide#guide-words`
- * survives a reload, a bookmark and a Back press, which is the whole
- * reason this build has a router at all — and the scroll the browser
- * would have done is done here instead.
- *
- * `key` is in the dependencies as well as `hash`: clicking the same
- * contents entry twice is two navigations to the same place, and a
- * reader who has scrolled away in between expects the second one to
- * take them back.
- */
-function useJumpToHash() {
- const { hash, key } = useLocation();
-
- useEffect(() => {
- const id = hash.replace(/^#/, '');
- if (!id) return;
- const el = document.getElementById(id);
- if (!el) return;
-
- /* Smooth per jump rather than `scroll-behavior: smooth` in the
- stylesheet, so that turning motion off turns this off with it —
- and so a jump in a browser that ignores the option still lands. */
- const still =
- document.documentElement.classList.contains('stillness') ||
- (typeof matchMedia === 'function' &&
- matchMedia('(prefers-reduced-motion: reduce)').matches);
- el.scrollIntoView?.({ behavior: still ? 'auto' : 'smooth', block: 'start' });
- }, [hash, key]);
-}
-
-/** A line, with the same line in the reader's language underneath it. */
-function Line({ said, lang }) {
- if (!said) return null;
- return (
- <>
- {said.text}
- {said.other && (
-
- {said.other}
-
- )}
-
- );
-}
-
-/** One part of the book: what it points at, what it asks, what it explains. */
-function Entry({ entry, lang }) {
- const asked = entry.asks.length;
- return (
- /* Open, and not by oversight. A closed is not in the
- printed page in any browser, and this document exists to be
- printed — so what is on screen is what comes out of the printer,
- and collapsing a part is the reader's choice rather than a state
- the guide arrives in and prints from. */
-
-
- {entry.act}
- {entry.title}
-
- {entry.read ? `${entry.lines} lines` : 'not read aloud'}
- {asked ? ` · ${asked} to answer` : ''}
- {entry.writes ? ' · 1 to write' : ''}
-
-
-
- {entry.caption && {entry.caption}
}
-
-
- {entry.watch && (
- <>
- Before it
-
-
-
- )}
- {entry.focus && (
- <>
- What to notice
-
-
-
- )}
- {asked > 0 && (
- <>
- It asks
-
-
- {entry.asks.map((q) => (
- {q}
- ))}
-
-
-
- )}
- {entry.writes && (
- <>
- To write
-
- {entry.writes.q}
- {entry.writes.intro && {entry.writes.intro}
}
-
- {entry.writes.hint}
- {entry.writes.minWords ? ` At least ${entry.writes.minWords} words.` : ''}
-
-
-
- )}
- {entry.words.length > 0 && (
- <>
- Words explained here
- {entry.words.join(', ')}
-
- )}
-
-
- );
-}
-
-/** A table that may be wider than the page it is on. */
-function Table({ columns, rows }) {
- return (
-
-
-
-
- {columns.map((c) => (
-
- {c}
-
- ))}
-
-
-
- {rows.map((row) => (
-
- {row.map((cell, i) => (
-
- {cell}
-
- ))}
-
- ))}
-
-
-
{block.text}
;
- case 'para':
- return {block.text}
;
- case 'note':
- return {block.text}
;
- case 'subhead':
- return (
-
- {block.text}
-
- );
- case 'list':
- return (
-
- {block.items.map((item) => (
-
- {item.lead && {item.lead} }
- {item.text}
-
- ))}
-
- );
- case 'table':
- return ;
- case 'plan':
- return (
-
- {block.entries.map((e) => (
-
- );
- case 'glossary':
- return (
- w.other)
- ? ['Word', 'What it means', 'In your language', 'Met in']
- : ['Word', 'What it means', 'Met in']
- }
- rows={block.words.map((w) =>
- block.words.some((x) => x.other)
- ? [w.word, w.meaning, w.other || '', w.where]
- : [w.word, w.meaning, w.where]
- )}
- />
- );
- default:
- return null;
- }
-}
-
-/**
- * @param {object} props
- * @param {string} [props.lang] overrides the reader's setting, for tests
- */
-export default function Guide({ lang }) {
- /* The book comes from the app, not from an import: this document is
- entirely built out of whichever pack is being read, so a guide made
- from a book the reader has moved on from would be a plausible-looking
- document about the wrong story. */
- const { book } = useBook();
- /* The reader's language comes from the shell, the same way the reading
- gets it. Read defensively rather than destructured: this component is
- also rendered on its own in a test, where there is no outlet above
- it and the context is null. */
- const ctx = /** @type {{settings?: {language?: string}}|null} */ (useOutletContext());
- const language = lang ?? ctx?.settings?.language ?? '';
- const { pathname } = useLocation();
- useJumpToHash();
-
- const outline = useMemo(() => guideOutline(book, { lang: language }), [book, language]);
- const contents = useMemo(() => contentsOf(outline), [outline]);
-
- /* Every section ends with the way back to the contents, so a reader
- who has jumped into the middle of a long document is never left
- scrolling to find the list again. */
- const backToTop = (
-
-
-
-
-
- Contents
- {contents.map((part) => (
-
-
{part.title}
-
{part.note}
-
- {part.items.map((item) => (
-
- {item.n}
- {item.heading}
-
-
- ))}
-
-
window.print()}
- >
- Print or save as PDF
-
-
-
-
- {outline.parts.map((part) => (
-
-
-
{part.title}
-
{part.note}
-
- {part.sections.map((section) => (
-
-
- {section.n}
- {section.heading}
-
- {section.blocks.map((block, i) => (
-
- ))}
-
- ))}
-
-
- );
-}
From f0c055fba75e71eb4be9400769096c3c1b9c591b Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:57:59 +0700
Subject: [PATCH 057/110] Remove classroom learning guide tests
---
src/ui/Guide.test.jsx | 142 ------------------------------------------
1 file changed, 142 deletions(-)
delete mode 100644 src/ui/Guide.test.jsx
diff --git a/src/ui/Guide.test.jsx b/src/ui/Guide.test.jsx
deleted file mode 100644
index e9aeae5..0000000
--- a/src/ui/Guide.test.jsx
+++ /dev/null
@@ -1,142 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import book from '../books/fixture/index.js';
-import { render, screen, within } from '@testing-library/react';
-import { createMemoryRouter, RouterProvider } from 'react-router-dom';
-import Guide from './Guide.jsx';
-import { BookProvider } from './useBook.jsx';
-import { guideOutline, sectionsOf, anchorFor, planOf } from '../lib/guide/outline.js';
-
-/**
- * "Done when it prints cleanly and its table of contents jumps."
- *
- * The printing is CSS, and jsdom has no printer. What can be asserted
- * here is the half that actually breaks: that every contents entry has
- * something in the document to jump to, and that it is still a link — a
- * real href, so it works before the JavaScript settles, survives a
- * reload, and can be shared.
- *
- * Rendered from the engine's own fixture book. This component owns no
- * content — every heading and count in it comes out of the pack — so a
- * title would only prove it works for that title.
- */
-
-/**
- * Rendered at /guide, the way the app mounts it.
- *
- * The book arrives through the provider rather than as a prop, which is
- * how the app supplies it: the router is built before any book is chosen,
- * so nothing on a route can be handed one.
- */
-function open(props = {}) {
- const router = createMemoryRouter(
- [
- {
- path: '/guide',
- element: (
-
-
- ),
- },
- ],
- { initialEntries: ['/guide'] }
- );
- return render( does not print', () => {
- open();
- const parts = /** @type {NodeListOf} */ (
- document.querySelectorAll('.guide-entry')
- );
- /* One per part the book teaches — the count comes from the book so
- that a part silently missing from the plan fails here too. */
- expect(parts).toHaveLength(planOf(book).length);
- expect(parts.length).toBeGreaterThan(1);
- for (const p of parts) expect(p.open).toBe(true);
- });
-
- it('names the book it was built from', () => {
- open();
- expect(screen.getByRole('heading', { level: 1 }).textContent).toContain('Learning guide');
- expect(document.body.textContent).toContain(book.meta.title);
- });
-
- it("shows the reader's language under the lines that have one", () => {
- /* The setting reaches this screen. It did not reach the reading for
- two phases, which is the defect this is written against. */
- const lang = book.languages[0].code;
- open({ lang });
- const translated = document.querySelectorAll(`.guide-entry .ui-tr[lang="${lang}"]`);
- /* Two lines per part are quoted from the guides — what to watch for
- and what to notice — and the pack translates both. */
- expect(translated).toHaveLength(planOf(book, lang).length * 2);
- expect(translated.length).toBeGreaterThan(1);
- });
-
- it('is English only when no language has been chosen', () => {
- open({ lang: '' });
- expect(document.querySelectorAll('.guide-entry .ui-tr')).toHaveLength(0);
- });
-});
From 69f73056ed989e5ae2f28509c08e15d316c24075 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:58:05 +0700
Subject: [PATCH 058/110] Remove hand-in UI
---
src/ui/HandIn.jsx | 165 ----------------------------------------------
1 file changed, 165 deletions(-)
delete mode 100644 src/ui/HandIn.jsx
diff --git a/src/ui/HandIn.jsx b/src/ui/HandIn.jsx
deleted file mode 100644
index da90f3c..0000000
--- a/src/ui/HandIn.jsx
+++ /dev/null
@@ -1,165 +0,0 @@
-import { useEffect, useRef, useState } from 'react';
-import SignIn from './SignIn.jsx';
-import { T } from './useUi.jsx';
-import { label as studentLabel } from '../lib/class/student.js';
-
-/**
- * Handing the work in.
- *
- * Three rules here came out of a classroom rather than out of the code.
- *
- * A student sees it being sent. Not a spinner in a corner — a bar, and
- * the word "Sending", because that is the thing they will understand and
- * the thing they will wait for. The bar moves on real steps (written
- * down, sent, confirmed) rather than on a timer, so it is not lying.
- *
- * A student is never told it failed. They cannot do anything about it,
- * they will not understand it, and the likely response is to hand in
- * again and again. The work is written down before anything is sent, and
- * the retry is ours, quietly. From their side it is done, because it is.
- *
- * A student is never told their work went somewhere it did not. If there
- * is no class set up on this device, it says so plainly — the work is
- * saved here — rather than showing a Hand in button that does nothing.
- *
- * @param {object} props
- * @param {number} props.pass
- * @param {import('../lib/class/student.js').Student|null} props.student
- * @param {boolean} props.hasClass is there anywhere for it to go
- * @param {(s:any)=>void} props.onSignIn
- * @param {()=>void} props.onSignOut
- * @param {(step:(n:number)=>void)=>Promise} props.onHandIn
- * @param {()=>void} [props.onSaveFile] the offline path: a file the
- * teacher can collect, for a room with no Sheet in it
- * @param {boolean} [props.alreadyIn]
- */
-export default function HandIn({
- pass,
- student,
- hasClass,
- onSignIn,
- onSignOut,
- onHandIn,
- onSaveFile,
- alreadyIn = false,
-}) {
- const [state, setState] = useState(
- /** @type {'idle'|'signing'|'sending'|'done'} */ (alreadyIn ? 'done' : 'idle')
- );
- const [step, setStep] = useState(0);
- /* Nothing is set on a component that has gone: a student who presses
- Hand in and immediately taps Back should not produce a warning in
- a teacher's console. */
- const alive = useRef(true);
- useEffect(() => {
- alive.current = true;
- return () => {
- alive.current = false;
- };
- }, []);
-
- /* Asked for first, whichever way the work is going out: a file with
- no name on it is no use to a teacher collecting thirty of them, and
- the offline path used to produce exactly that. */
- const askWho = (
-
- {
- onSignIn(s);
- setState('idle');
- }}
- onCancel={student ? () => setState('idle') : undefined}
- />
-
- );
-
- if (state === 'signing') return askWho;
-
- if (!hasClass) {
- /* No Sheet to send to. The work is not lost and it is not stranded
- either: it saves to a file the teacher can collect, which is the
- whole offline path. Saying only "your work stays here" left a
- student holding something they could not hand over. */
- return (
-
-
- No class is set up on this device, so your work stays here.
-
- {onSaveFile ? (
-
(student ? onSaveFile() : setState('signing'))}
- >
- Save my work to a file
-
- ) : null}
-
-
- Handed in.
- {' '}
- Your teacher has it.
-
- );
- }
-
- if (state === 'sending') {
- const of = 3;
- return (
-
-
- Sending your work…
-
- {/* A real progress element, moved by real steps. */}
-
- {step} of {of}
-
-
-
- Handing in reading {pass} as {studentLabel(student)}
- setState('signing')}>
- Not you?
-
-
-
-
{
- setState('sending');
- setStep(1);
- try {
- await onHandIn(setStep);
- } finally {
- /* Done either way. It is written down; if it has not gone
- yet it will, and that is not the student's problem. */
- if (alive.current) {
- setStep(3);
- setState('done');
- }
- }
- }}
- >
- Hand in your work
-
-
-
- Sign out of this device
-
-
-
-
- Question {progress.at} of {progress.of}
-
- {progress.right} right
-
-
-
- {question.q}
-
-
- {retrying && !done && (
-
- Not quite. {' '}
- {question.hint || 'Look back at the part you just read, then try again.'}
-
- )}
-
-
- {(question.opts || []).map((text, i) => {
- const state = !done
- ? ''
- : i === question.correct
- ? ' correct'
- : picked === i
- ? ' wrong'
- : '';
- return (
-
- {
- setChosen(i);
- onAnswer(i);
- }}
- >
- {text}
-
-
- );
- })}
-
-
- {done && (
-
- {answered.correct ? 'Right.' : 'Not this time.'} {' '}
- {question.fb || question.explain || ''}
-
- )}
-
- {onSkip && !done && (
-
- Skip this one
-
- )}
-
- );
-}
From 1fbc1625048dbeccafec342c0d31e2ac90ba7f8a Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:58:24 +0700
Subject: [PATCH 060/110] Remove classroom sheet setup
---
src/ui/SheetSetup.jsx | 125 ------------------------------------------
1 file changed, 125 deletions(-)
delete mode 100644 src/ui/SheetSetup.jsx
diff --git a/src/ui/SheetSetup.jsx b/src/ui/SheetSetup.jsx
deleted file mode 100644
index 7db2def..0000000
--- a/src/ui/SheetSetup.jsx
+++ /dev/null
@@ -1,125 +0,0 @@
-import { useState } from 'react';
-import backend from '../backend/backend.gs?raw';
-
-/**
- * How a teacher gets a Sheet to point the reader at.
- *
- * Until this existed, the Class panel asked for an Apps Script
- * deployment link and gave no way to make one — the script lived only
- * inside the prototype's HTML, as a block to be copied by hand out of
- * view-source. A panel that asks for something it does not tell you how
- * to produce is not a feature.
- *
- * Six steps and a copy button. The steps are numbered because this is
- * genuinely a sequence and the order matters — deploying before saving
- * gives you a link to nothing.
- *
- * The "unverified app" warning gets a paragraph of its own, because it
- * is the point where a teacher stops. It is Google saying "a human
- * wrote this and we have not reviewed it", about a script that teacher
- * has just pasted into their own Sheet, and it is expected.
- */
-
-const STEPS = [
- ['In your Google Sheet, open', 'Extensions → Apps Script'],
- ['Delete whatever is in the editor, paste the code below, and press', 'Save'],
- ['Then', 'Deploy → New deployment → Web app'],
- ['Set', 'Execute as: Me'],
- ['Set', 'Who has access: Anyone'],
- ['Copy the link it gives you — it ends in /exec — and paste it above', ''],
-];
-
-export default function SheetSetup() {
- const [open, setOpen] = useState(false);
- const [said, setSaid] = useState('');
-
- return (
-
- Making a Sheet to send it to
-
- Any Google Sheet you own. This adds a short script to it that receives the work and
- keeps the marks up to date. Nothing is stored on a student’s tablet.
-
-
- setOpen((v) => !v)}
- >
- {open ? 'Hide the steps' : 'Show me how'}
-
-
- {open ? (
- <>
-
- {/* Keyed on the whole step, not on the words it opens with:
- two of them begin "Set", which React reported as two
- children with the same key. */}
- {STEPS.map(([before, what]) => (
-
- {before} {what ? {what} : null}
-
- ))}
-
-
-
- Google will call it an unverified app . That is expected: it is saying a
- person wrote this and Google has not reviewed it, about a script you have just
- pasted into your own Sheet. Choose Advanced , then Go to (project name)
- .
-
-
-
- You sign in once, here, and no student ever does. Execute as: Me means the
- script runs with your account’s permission on your Sheet — which is also the
- real proof of who the teacher is, better than any passcode this app could invent. No
- route in it ever hands a student’s work back, so the link is a way in, not a
- way to read the class.
-
-
-
- {
- try {
- await navigator.clipboard.writeText(backend);
- setSaid('Code copied. Paste it into Apps Script.');
- } catch {
- setSaid('Select all of the code below and copy it.');
- }
- }}
- >
- Copy the code
-
- {Math.round(backend.length / 1024)} KB
-
-
- {said ? (
-
- {said}
-
- ) : null}
-
- {/* A scrollable box has to be reachable from the keyboard, or
- somebody who cannot use a mouse cannot read the script
- they are being asked to trust — WCAG 2.1.1, and the reason
- browsers are adding this automatically. `region` plus a
- label is the accessible form of it; the rule below does not
- know that case and would have this be unreachable. */}
- {/* eslint-disable jsx-a11y/no-noninteractive-tabindex */}
-
- {backend}
-
- {/* eslint-enable jsx-a11y/no-noninteractive-tabindex */}
-
- ) : null}
-
- );
-}
From 9eef6f3d60471472362cb5ef695ae4d0eb9cdbe7 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:58:33 +0700
Subject: [PATCH 061/110] Remove classroom sign-in UI
---
src/ui/SignIn.jsx | 244 ----------------------------------------------
1 file changed, 244 deletions(-)
delete mode 100644 src/ui/SignIn.jsx
diff --git a/src/ui/SignIn.jsx b/src/ui/SignIn.jsx
deleted file mode 100644
index 4e2c1f0..0000000
--- a/src/ui/SignIn.jsx
+++ /dev/null
@@ -1,244 +0,0 @@
-import { useEffect, useId, useMemo, useRef, useState } from 'react';
-import { normaliseStudent, problemsWith, canSignIn } from '../lib/class/student.js';
-import { lookupStudent, hasMatch } from '../lib/class/roster.js';
-import { loadApi } from '../lib/class/key.js';
-import { T } from './useUi.jsx';
-
-/**
- * Who is at this device.
- *
- * Four fields and nothing else. It is asked once, and only when there is
- * somewhere for the work to go — a student reading on their own at home
- * should never be made to type their class number to see a story.
- *
- * Every problem is reported against the field it belongs to rather than
- * as one message at the top: "please check your details" makes a
- * thirteen-year-old guess which of four boxes is wrong.
- *
- * WHERE THE CLASS LIST COMES IN. If the teacher keeps one, the number
- * they typed is looked up and the name on the list is offered back for
- * them to accept or refuse. A class of thirty produces three students
- * called Kevin, one who types "aaaa", one who taps a friend's name for
- * a laugh, and one who joins twenty minutes late; the number solves most
- * of that and the confirmation solves the rest.
- *
- * And it is a convenience, never a gate. Unconfigured, offline, slow,
- * unreadable, or simply not on the list — every one of those signs them
- * in with what they typed, silently, because none of it is a thing a
- * student can do anything about and all of it ends with work that has
- * to reach a teacher. Nothing here can stop anybody handing work in.
- *
- * @param {object} props
- * @param {import('../lib/class/student.js').Student|null} [props.student]
- * @param {(s: import('../lib/class/student.js').Student) => void} props.onSignIn
- * @param {() => void} [props.onCancel]
- * @param {string} [props.api] where the class list lives; read from the
- * class set up on this device when not given
- * @param {typeof lookupStudent} [props.lookup] testing seam
- */
-export default function SignIn({
- student = null,
- onSignIn,
- onCancel,
- api,
- lookup = lookupStudent,
-}) {
- const id = useId();
- const [form, setForm] = useState(() => student || { cls: '', no: '', name: '', nick: '' });
- /* Nothing is marked wrong before it has been filled in once. An empty
- form covered in red is the app telling a student off for arriving. */
- const [touched, setTouched] = useState(/** @type {Record} */ ({}));
- const [tried, setTried] = useState(false);
-
- /* 'asking' is the form; 'checking' is the class list being asked;
- 'confirm' is a name being offered back. The prototype called these
- number, list and manual — the same three moments. */
- const [phase, setPhase] = useState(/** @type {'asking'|'checking'|'confirm'} */ ('asking'));
- const [candidate, setCandidate] = useState(
- /** @type {import('../lib/class/roster.js').RosterMatch|null} */ (null)
- );
-
- const endpoint = useMemo(() => (api !== undefined ? api : loadApi()), [api]);
-
- /* Nothing is set on a component that has gone: a student who presses
- the button and immediately taps Back should not produce a warning
- in a teacher's console. */
- const alive = useRef(true);
- useEffect(() => {
- alive.current = true;
- return () => {
- alive.current = false;
- };
- }, []);
-
- /* Asked once per number. A student who said "no, that is not me" is
- not asked the same question again on the next press, and neither is
- one whose lookup found nothing — the second press signs them in. */
- const asked = useRef(/** @type {Set} */ (new Set()));
-
- const confirmRef = useRef(/** @type {HTMLButtonElement|null} */ (null));
- useEffect(() => {
- /* A real focus change, so a screen reader says what just happened
- rather than leaving it on a form that has visibly changed. The
- button's own label carries the name being offered. */
- if (phase === 'confirm') confirmRef.current?.focus();
- }, [phase]);
-
- const problems = problemsWith(form);
- const show = (k) => (touched[k] || tried) && problems[k];
-
- const set = (k) => (e) => setForm((f) => ({ ...f, [k]: e.target.value }));
- const blur = (k) => () => setTouched((t) => ({ ...t, [k]: true }));
-
- const fields = [
- ['cls', 'Class', 'e.g. 1-A', 'organization'],
- ['no', 'Number', 'e.g. 07', 'off'],
- ['name', 'Your name', '', 'name'],
- ['nick', 'What you like to be called', 'optional', 'nickname'],
- ];
-
- async function submit(e) {
- e.preventDefault();
- if (phase === 'checking') return;
- setTried(true);
- if (!canSignIn(form)) return;
-
- const typed = normaliseStudent(form);
- const key = `${typed.cls}|${typed.no}`;
- if (!endpoint || asked.current.has(key)) {
- onSignIn(typed);
- return;
- }
-
- setPhase('checking');
- /* The lookup answers rather than throwing, and the catch is here
- anyway: a thrown error would leave the button saying "Checking
- the class list" for the rest of the lesson, which is the one
- failure that would actually stop somebody handing work in. */
- const answer = await lookup(endpoint, typed).catch(() => null);
- if (!alive.current) return;
- asked.current.add(key);
-
- /* Only worth interrupting them for a name that is not the one they
- just typed. Agreeing with the register is not news. */
- const match = hasMatch(answer) ? answer.match : null;
- if (match && match.name.toLowerCase() !== typed.name.toLowerCase()) {
- setCandidate(match);
- setPhase('confirm');
- return;
- }
- setPhase('asking');
- onSignIn(typed);
- }
-
- if (phase === 'confirm' && candidate) {
- return (
-
-
- Is this you?
-
-
- {candidate.name}
- {candidate.nick && candidate.nick !== candidate.name ? (
- {candidate.nick}
- ) : null}
-
- Number {candidate.no} on your teacher’s class list
-
-
-
- {
- /* Refusing goes back to the form, not out of the door.
- Somebody has to be able to be the new student whose
- number was somebody else's last term. */
- setCandidate(null);
- setPhase('asking');
- }}
- >
- No, use what I typed
-
-
- onSignIn(
- normaliseStudent({
- ...form,
- no: candidate.no,
- name: candidate.name,
- nick: candidate.nick,
- })
- )
- }
- >
- Yes, that’s me
-
-
-
- );
- }
-
- const checking = phase === 'checking';
-
- return (
-
- );
-}
From 3df1d4c7698592f4dbf6e716c1efac4a98070469 Mon Sep 17 00:00:00 2001
From: Dan Cockrell <173971169+dancockrell@users.noreply.github.com>
Date: Tue, 1 Sep 2026 12:58:43 +0700
Subject: [PATCH 062/110] Remove classroom sign-in tests
---
src/ui/SignIn.test.jsx | 214 -----------------------------------------
1 file changed, 214 deletions(-)
delete mode 100644 src/ui/SignIn.test.jsx
diff --git a/src/ui/SignIn.test.jsx b/src/ui/SignIn.test.jsx
deleted file mode 100644
index 24d8a31..0000000
--- a/src/ui/SignIn.test.jsx
+++ /dev/null
@@ -1,214 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import SignIn from './SignIn.jsx';
-
-/**
- * The door.
- *
- * Every test here that breaks the class list ends by asserting that
- * somebody got signed in anyway. That is the whole design: the roster
- * catches typos and duplicate names, and it is never the thing that
- * decides whether a student may hand work in.
- */
-
-const API =
- 'https://script.google.com/macros/s/AKfycbwABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abc/exec';
-
-const TYPED = { cls: '1-A', no: '07', name: 'Kevin', nick: '' };
-
-/* The hint sits inside the label ("Class", then "e.g. 1-A"), so the
- accessible name is the pair of them. Anchored at the front, which is
- what a person reading the form sees first. */
-const box = (label) => screen.getByLabelText(new RegExp(`^${label}`));
-
-/** Fill the form in the way a student does, then press the button. */
-async function signIn(user, who = TYPED) {
- await user.type(box('Class'), who.cls);
- await user.type(box('Number'), who.no);
- await user.type(box('Your name'), who.name);
- await user.click(screen.getByRole('button', { name: /That’s me/ }));
-}
-
-/** @param {import('../lib/class/roster.js').RosterAnswer} answer */
-const answers = (answer) => vi.fn(async () => answer);
-
-const found = (over = {}) => ({
- outcome: /** @type {const} */ ('found'),
- match: { no: '07', name: 'Kevin Park', nick: 'Kev', ...over },
-});
-
-describe('when there is no class list to check against', () => {
- it('signs them in without asking anybody anything', async () => {
- const onSignIn = vi.fn();
- const lookup = vi.fn();
- const user = userEvent.setup();
- /* No endpoint on this device. Not a failed lookup — no lookup. */
- render(
-
-
- Question {progress.at} of {progress.of}
-
- Write in your own words
-
-
- {prompt.q}
- {prompt.hint && {prompt.hint}
}
-
-
- Your answer
-
-