Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

docs(skill): second pass, shorter wording and no repeats of core

yzrc04340945c10
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.md
index d2ddaf7..52a3d80 100644
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@ -58,7 +58,7 @@ Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local), git
## Scripts
-All in `SKILL/scripts/`; each prints its usage with `--help`, run with the `uv run --with …` its docstring names (its first lines; without its packages even `--help` stops on the import). Packages: playwright for every script that opens a page, pillow for the ones that write pictures, numpy for strip, export, `music.py gaps`, prep, frames, sfx and eleven, faster-whisper for eleven, pymupdf for outline and split_pages, scikit-image for trace, edge-tts or kokoro for tts; the rest need only Python and ffmpeg.
+All in `SKILL/scripts/`; each prints its usage with `--help` when run with the `uv run --with …` its docstring's first lines name (without its packages even `--help` stops on the import).
| For | Scripts |
|---|---|
diff --git a/.claude/skills/papermorph/references/core/engine.md b/.claude/skills/papermorph/references/core/engine.md
index 46fba69..0134a48 100644
--- a/.claude/skills/papermorph/references/core/engine.md
+++ b/.claude/skills/papermorph/references/core/engine.md
@@ -1,10 +1,10 @@
# The engine (lib/engine.js, lib/engine.css, lib/math.js)
-A chapter page loads the engine and its `audio/<lang>/timings.js`, defines `CHAPTER` (including `language` when different from `en`: the audio folder), drawing helpers, `BEATS` and questions, then calls `boot()`. The engine provides the stage, drawing, timeline, question types, guide and player. Use the code's signatures if they differ from this reference. The interface text (buttons, help, cover, finish card) follows `<html lang>`: English, Russian, Chinese and Japanese are in the engine's `TRANSLATIONS`; another language needs a block there.
+A chapter page loads the engine and its `audio/<lang>/timings.js`, defines `CHAPTER` (with `language` when not `en`: the audio folder), drawing helpers, `BEATS` and questions, then calls `boot()`. The engine provides the stage, drawing, timeline, question types, guide and player; where the code's signatures differ from this reference, the code wins. Interface text (buttons, help, cover, finish card) follows `<html lang>`: English, Russian, Chinese and Japanese are in the engine's `TRANSLATIONS`; another language needs a block there.
-Every book keeps a copy of the shared engine in `lib/` (`engine.*`, `math.js`, `volume.*`, `contents.*`, `units.*`), so the book runs on its own. The engine is not part of this skill: it lives in the `engine/` folder of the Papermorph repository (or a fork). `python3 SKILL/scripts/engine.py site` copies it into every book from the repository's `engine/` when it is at hand, otherwise from GitHub (`--check` lists copies that differ, `--from DIR|OWNER/REPO@REF` picks the source, by default the latest compatible release, `engine-v2.7`; `@main` takes the newest, a tag or commit pins it, and `engine-v1` is the last engine with the maths helpers inside `engine.js`); a book's copy is not edited by hand. This reference describes `engine-v2.7`; a book on an older copy is synced with `engine.py` before it relies on anything here. An engine bug is fixed at the source, then synced. The book's own settings and style overrides live in `lib/book.css`, imported by `engine.css` and never overwritten: `--math-font` for numbers and formulas, `--progress-key` when the cover uses a key other than the default.
+Every book keeps a copy of the shared engine in `lib/` (`engine.*`, `math.js`, `volume.*`, `contents.*`, `units.*`), so the book runs on its own. The engine is not part of this skill but lives in the `engine/` folder of the Papermorph repository (or a fork). `python3 SKILL/scripts/engine.py site` copies it into every book from the repository's `engine/` when it is at hand, otherwise from GitHub (`--check` lists copies that differ, `--from DIR|OWNER/REPO@REF` picks the source, by default the latest compatible release, `engine-v2.7`; `@main` takes the newest, a tag or commit pins it, and `engine-v1` is the last engine with the maths helpers inside `engine.js`); a book's copy is not edited by hand. This reference describes `engine-v2.7`: sync a book on an older copy before relying on anything here. Fix an engine bug at the source, then sync. The book's own settings and style overrides live in `lib/book.css`, imported by `engine.css` and never overwritten: `--math-font` for numbers and formulas, `--progress-key` when the cover uses a key other than the default.
-The maths helpers (number lines, tiles, fraction rows, planes, chance objects, the number-set diagram, `pickPoint`, `sorter`) are in `lib/math.js`. A chapter that uses one loads `<script src="../lib/math.js"></script>` right after `engine.js`: it reads the engine's globals as it loads, so never before it and never `async`. `lint.py` names a chapter that uses one without loading it. Use the helpers that fit; draw the rest in the chapter, and move what several chapters use into the book's element library (`lib/<name>.js`, [assets.md](../lessons/assets.md)) rather than into the engine copy.
+The maths helpers (number lines, tiles, fraction rows, planes, chance objects, the number-set diagram, `pickPoint`, `sorter`) are in `lib/math.js`. A chapter that uses one loads `<script src="../lib/math.js"></script>` right after `engine.js` (it reads the engine's globals as it loads, so never before it and never `async`). `lint.py` names a chapter that uses one without loading it. Use the helpers that fit; draw the rest in the chapter, and move what several chapters use into the book's element library (`lib/<name>.js`, [assets.md](../lessons/assets.md)) rather than into the engine copy.
## Contents
@@ -24,10 +24,10 @@ The question types and their API (`quiz()`, cards, grading) are in [lessons/ques
- The stage is SVG, `viewBox 0 0 1600 900`; animated things live in `#scene`. HTML cards go in `#ui`, in the same coordinates.
- **Upright stage**. `<html data-stage="portrait">` turns the stage to 900 × 1600 for a phone feed ([shorts.md](../films/shorts.md)). `SW` and `SH` hold the stage size (1600 and 900 otherwise), CSS has `--sw` and `--sh`, and the camera, the bottom band card, the captions, the window fit and `export.py` follow them. The side and top-right question cards and `header()` are still placed for the wide stage, so an upright chapter is a film without questions.
- Every animated element carries a state object written to the DOM by `render()`: `x y` (translate), `s` (scale), `r` (rotate, degrees), `o` (opacity), `d` (stroke drawn, 0–1), `a_<attr>` (numeric attribute, e.g. `'a_stroke-width'`), `c_<attr>` (hex colour). Give a key a starting value before tweening it; an `a_`/`c_` key without one starts from the element's attribute.
-- Scale and rotation are about the element's own origin: draw around (0,0) and place with `x/y`.
+- Scale and rotation are about the element's own origin: draw around (0,0), place with `x/y`.
- `S` holds objects shared across beats (`S.panel`, `S.line`, …). `reset()` clears it, so anything a later beat needs must be stored on `S`.
- Palette `COL`: `chalk dim faint task good bad board` plus six hues named `nat whole int rat irr real` (from the algebra book; give them the book's own meanings in `style.json` `look.meaning`, e.g. `const FORCE = COL.…`). Fonts: `UI` (text), `MATH` (serif unless the book's `--math-font` says otherwise).
-- **Board colour**. The board and ink colours are the palette at the top of `engine.css` (`--page --board --panel --edge --chalk --dim --faint --task --quiz --good --bad`, plus `--on-fill` for text on a coloured button (unset there, so dark) and `--vignette` for the stage's edges, and the shades between them: `--rule --track --track-ask --bar-edge --hover --veil`). A book redefines them in its `lib/book.css` under a plain `:root`; the stage, the cards, the player bar and `COL.chalk … COL.board` all follow, so a light board with dark ink is a few lines of settings (the commented example in `book.css`, shades included). `COL` reads its colours back as `#rrggbb` (colour tweens mix them) and keeps the dark board's own for one that is missing. The six hues stay in JS: a light book picks darker ones in its own `lib/<look>.js` (`Object.assign(COL, { … })`), loaded right after `engine.js` and before `math.js`, which copies the hues as it loads. Check a new palette on a frame with a question card and the captions on (`?beat=N&t=S`), not only on the picture. `site/physics-notebook/` is a light book made this way (`lib/book.css` and `lib/notebook.js`).
+- **Board colour**. The board and ink colours are the palette at the top of `engine.css` (`--page --board --panel --edge --chalk --dim --faint --task --quiz --good --bad`, plus `--on-fill` for text on a coloured button (unset there, so dark) and `--vignette` for the stage's edges, and the shades between them: `--rule --track --track-ask --bar-edge --hover --veil`). A book redefines them in its `lib/book.css` under a plain `:root`; the stage, cards, player bar and `COL.chalk … COL.board` all follow, so a light board with dark ink is a few lines of settings (the commented example in `book.css`, shades included). `COL` reads its colours back as `#rrggbb` (colour tweens mix them) and keeps the dark board's own for one that is missing. The six hues stay in JS: a light book picks darker ones in its own `lib/<look>.js` (`Object.assign(COL, { … })`), loaded right after `engine.js` and before `math.js`, which copies the hues as it loads. Check a new palette on a frame with a question card and the captions on (`?beat=N&t=S`), not only on the picture. `site/physics-notebook/` is a light book made this way (`lib/book.css` and `lib/notebook.js`).
## Drawing
@@ -52,7 +52,7 @@ The question types and their API (`quiz()`, cards, grading) are in [lessons/ques
| `panel(t0)` | fade the current scene group and start a new one; call it at the start of a beat that changes the picture |
| `header(p, str, t0, x, y)` | a small dim heading over the picture (default at 1000, 170 on the wide stage) |
-Topic helpers in `math.js`: number lines (`numberLine`, `move`, `landDot`, `brace`, on the engine's `X(v)`, `Y0`, `tick`, `dot`, `AXIS`), signed tiles (`tile`, `tiles`, `cancelPairs`), algebra tiles (`atile`, `tileRow`, `cancel`, `popIn`, sizes in `TS`), fraction rows (`fracRow`, `reduce`), a decimal point that hops (`pointRow`), a balance (`balance`), inequality graphs (`ray`, `segment`), a coordinate plane (`plane`: `PX/PY`, `dot`, `walk`, `line`, `arrow`, `stair`, `region`, `half`, `fn` for y = f(x); set `P.layer = panel(0)` so marks clear with the beat), scaled axes (`axes`), dot plots (`dataLine`), chance objects (`die`, `coin`, `spinner`, `outline`), area grids (`areaGrid` with `.cell`, `.ring`; `arc`), rectangles (`rect`, `bracketH`), vertical scales (`vAxis`, `thermometer`), the number-set diagram (`RINGS`, `buildVenn`, `regionAt`). Read the function in math.js before first use.
+Topic helpers in `math.js`: number lines (`numberLine`, `move`, `landDot`, `brace`, on the engine's `X(v)`, `Y0`, `tick`, `dot`, `AXIS`), signed tiles (`tile`, `tiles`, `cancelPairs`), algebra tiles (`atile`, `tileRow`, `cancel`, `popIn`, sizes in `TS`), fraction rows (`fracRow`, `reduce`), a decimal point that hops (`pointRow`), a balance (`balance`), inequality graphs (`ray`, `segment`), a coordinate plane (`plane`: `PX/PY`, `dot`, `walk`, `line`, `arrow`, `stair`, `region`, `half`, `fn` for y = f(x); set `P.layer = panel(0)` so marks clear with the beat), scaled axes (`axes`), dot plots (`dataLine`), chance objects (`die`, `coin`, `spinner`, `outline`), area grids (`areaGrid` with `.cell`, `.ring`; `arc`), rectangles (`rect`, `bracketH`), vertical scales (`vAxis`, `thermometer`), the number-set diagram (`RINGS`, `buildVenn`, `regionAt`). Read a function in math.js before first use.
## LaTeX
@@ -73,22 +73,22 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accen
}, { ask: done => quiz(BAND, [/* questions */], done) }], // optional: a question beat
```
-- `m('name', offset)` is the start time of the word after `[[name]]`; `D` is the clip's length. Use marks for actions tied to speech; scene entrances and transitions can use fixed offsets.
+- `m('name', offset)` is the start time of the word after `[[name]]`; `D` is the clip's length. Time actions tied to speech by marks; scene entrances and transitions can use fixed offsets.
- Tweens: `tw(e, to, t0, dur, ease)`, `prog(q => …, t0, dur, ease)` for custom motion (arcs, counters, live redraws), `show(e, t0, dur, ease)`, `hide`, `draw` (same arguments), `pop`, `pulse`, `stream`. Eases: `io`, `out`, `back`, `lin`, `soft`. Continuous motion and cameras: see below.
- A lesson beat ends after its narration and its last tween, and holds that picture `HOLD` (0.6 s) before the next starts (tailed `clockRun`s and cameras run to that end and do not set it: hold a picture longer with a plain run, `prog(() => {}, 0, D + 1)`, or `minDur`, below); an `ask` beat waits for `done()`. An `ask` is any `done => …` that calls `done()` once; `quiz()` is the usual one, and a film's own handler can listen on the stage instead ([documentary.md](../films/documentary.md#interactive-moments)). A `done()` kept from an earlier start of the same beat (the reader stepped back and replayed it) no longer counts; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.
-- **Beats lengthen without a word**: any tween that ends after `D` (a push to `D + .6`, a helper's `clockRun(f, 30)`) lengthens the beat by as much. `?lengths` in the URL prints in the console each beat's voice (`pre` + clip), its length on screen and the time past voice + `HOLD`; read it after a change, and recut the music after any change in length. A helper that does not know the beat's `D` runs to the beat's end with `clockRun(f, 0, { tail: true })`, which never lengthens it.
-- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and no element is revealed (faded, scaled or drawn in from nothing) within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s, so the narration never runs over an empty board. It looks only at reveals: a beat that lays out part of its picture visible at once (axes, empty boxes, a set) and reveals the rest on later words still has that first group pulled to 0.4 s. When those words matter, or a camera shows a picture from the first frame, give the beat `{ lead: false }` in its fourth slot; when every opening in the chapter is timed by hand (a documentary), set `CHAPTER.lead = false` instead. To see where a beat's reveals land, put marks on a contact sheet: `strip.py chNN OUT idea:0.4,label,label+0.3,end --sheet storyboard --url http://localhost:8765/<book>/` (a mark plus an offset is the moment the action is timed to).
+- **Beats lengthen without a word**: any tween that ends after `D` (a push to `D + .6`, a helper's `clockRun(f, 30)`) lengthens the beat by as much. `?lengths` in the URL prints each beat's voice (`pre` + clip), its length on screen and the time past voice + `HOLD` to the console; read it after a change, and recut the music after any change in length. A helper that does not know the beat's `D` runs to the beat's end with `clockRun(f, 0, { tail: true })`, which never lengthens it.
+- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and no element is revealed (faded, scaled or drawn in from nothing) within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s, so the narration never runs over an empty board. It looks only at reveals: a beat that shows part of its picture at once (axes, empty boxes, a set) and reveals the rest on later words still has that first group pulled to 0.4 s. When those words matter, or a camera shows a picture from the first frame, give the beat `{ lead: false }` in its fourth slot; when every opening in the chapter is timed by hand (a documentary), set `CHAPTER.lead = false` instead. To see where a beat's reveals land, put marks on a contact sheet: `strip.py chNN OUT idea:0.4,label,label+0.3,end --sheet storyboard --url http://localhost:8765/<book>/` (a mark plus an offset is the moment the action is timed to).
- **`pre`** in the fourth slot (`{ pre: 1.2 }`) runs the picture that many seconds before the narration starts: an action, then the line. Picture books use it on every scene.
- **`minDur`** in the fourth slot (`{ minDur: 9.4 }`) is the least the whole beat lasts, hold included, as `?lengths` reports it: two mirrored beats (two answers treated alike) get the longer one's length.
- **`dur`** in the fourth slot (`{ dur: 2 }`) makes a beat with no narration: no clip and no `TIMINGS` entry (the engine adds `{ dur, marks: {}, cues: [], silent: true }`), the picture runs `dur` seconds on wall time, then holds. A wordless card (a series card, an end card) needs no silence clip. A beat with a `TIMINGS` entry ignores `dur`.
- **`hold`** in the fourth slot of an `ask` beat in a film (`CHAPTER.film`) is read only by `export.py`: the seconds the video holds the waiting picture before it plays on as if the reader had acted (1.5 by default). The page ignores it.
- **The end of a film**: a chapter whose last beat asks nothing (a picture book) is finished when that beat ends: it is marked done and, with `CHAPTER.next`, offers the next chapter (Enter).
-- **Seeking replays**: jumping to beat N rebuilds the scene and runs earlier beats instantly. Make `run` deterministic: create objects and schedule tweens through the timeline, with inputs from chapter data and replayed `S` state. Create interactions inside `ask`; use `fx`/`fxp` for answer effects.
+- **Seeking replays**: jumping to beat N rebuilds the scene and runs earlier beats instantly, so make `run` deterministic: create objects and schedule tweens through the timeline, with inputs from chapter data and replayed `S` state. Create interactions inside `ask`; use `fx`/`fxp` for answer effects.
- Constants used in a `BEATS` literal are evaluated when it is defined, so define them above `BEATS`. Data used only inside an `ask` closure may sit below.
## World clock and camera
-For continuous motion (vehicles, orbits, rolling, scrolling scenery) and camera work. Everything is a pure function of the beat time, so pause, seek and `?beat=N&t=S` show the same frame.
+For continuous motion (vehicles, orbits, rolling, scrolling scenery) and camera work. Everything is a pure function of beat time, so pause, seek and `?beat=N&t=S` show the same frame.
- `clockRun(f, D)` calls `f(t)` on every frame of the beat, `t` in seconds from its start (0..D); the beat's hold after `D` shows `f(D)`. With `clockRun(f, D, { tail: true })` it keeps calling `f` through the hold, `t` up to the beat's end (`P.end`: the later of the narration and the last tween that is not a tail, plus `HOLD`; a tail's own `D` no longer lengthens the beat): use it where motion must never freeze (a film, whose next scene cuts in), and let `f` pose sensibly past `D`. `f` also gets that end, `f(t, end)`, so a move can land on it (a whip out, a dive into the next scene): under music it is where the beat really leaves, up to `HOLD` early, and at the end a tail stays where the clock is rather than jumping. A camera in a beat with a tailed `clockRun` runs on to `P.end` too, so a follow shot keeps up; in a beat without one, a camera's `D` is its length and does not lengthen the beat. Write positions as functions of `t` (`x = x0 + v * t`) and share them between objects and the camera; never accumulate per-frame state.
- `const cam = camera(parent, D, { x, y, z, r, box, bg })` makes a view onto a world group. Draw in `cam.world` in world coordinates. The view `{x, y}` is the world point shown at the centre, `z` the zoom (screen px per world px), `r` the roll in degrees. Defaults: full stage, `(800, 450)`, `z` 1 (identity, so stage coordinates still work). With `box: [x, y, w, h]` the camera draws in a framed, clipped box with background `bg` (split screen, picture-in-picture); its default zoom fits the 1600 × 900 world into the box. `cam.el` is the camera's group (fade, pop or hide it; it scales about the box centre).
@@ -101,7 +101,7 @@ For continuous motion (vehicles, orbits, rolling, scrolling scenery) and camera
## Performance (Firefox)
-Firefox repaints SVG on the main thread and is the slowest common browser for these pages. Measure in Playwright Firefox as well as Chromium: rAF frame times at beat transitions and during camera moves. Headless Chromium hides paint cost.
+Firefox repaints SVG on the main thread and is the slowest common browser for these pages; headless Chromium hides paint cost. Measure rAF frame times in Playwright Firefox as well as Chromium, at beat transitions and during camera moves ([core/review.md](review.md#smoothness)).
- Never put an SVG filter behind animated content (the stage grain is a static CSS texture for this reason). Avoid clip-paths on moving or zooming groups where a box or an image does the job.
- Large shapes under a big camera zoom or roll are expensive: a filled `<circle>` scaled 6× and rotating cost about 200 ms a frame in Firefox, while the same picture as one `<image>` cost about 3 ms. Prefer one image for a big detailed object (a planet, a map), and few elements over many small ones (merge cells into one path per colour, or use an image).
@@ -111,16 +111,13 @@ Firefox repaints SVG on the main thread and is the slowest common browser for th
- Cross-fading two full-screen cameras costs a long frame: fade only the incoming one in over the outgoing one, then hide the old.
- A question card's entrance after a busy scene can hitch; measure it with `perf.py`.
-
## Player
Space play/pause, and once the chapter has ended replay, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions (a question's narration is captioned too, above its band or beside its corner card, until the narration ends); a beat's last caption clears a second after its narration, so it does not sit on a closing title; a line in another language with a `sub` (`tts.py`, `eleven.py`) shows its subtitle even with captions off, `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen: the stage fills the screen, and the controls lie over its foot, showing while the pointer moves or a key is pressed, while paused and while the pointer is on them (a touch screen, with no hover, keeps them under the stage); full screen also turns the screen to the stage's orientation where the browser can lock it (Android, not iOS), and on a phone held across the stage, starting the chapter goes full screen that way, so a landscape lesson is not a strip on an upright phone, ? help (it lists the question keys only in a chapter with questions, and a film with questions can leave them out with `CHAPTER.questionKeys = false` when its moments have their own controls). Clicking a step segment jumps to that point of the beat (`seekInto(i, frac)`); the next beat's clip preloads while one plays. `seek(i, play)` rebuilds and jumps; `start(i, play)` begins a beat from the current picture. While audio plays, the beat clock follows `audio.currentTime`. In a hidden tab (another tab or window in front) a timer keeps the clock going, so the chapter plays on from beat to beat. `?beat=N&t=S` in the URL opens a frozen frame for review, without captions (N is kept within the chapter's steps); on a question step the answer box takes focus only once Space starts the lesson. With `?review` in the URL, N pauses and asks for a note on the current moment and Shift+N copies the chapter's notes, one line each with the `?beat=N&t=S` that reopens it, so a reviewer can collect notes while watching and hand them over at once. After the end, on the finish card or a film's last frame, Enter opens `CHAPTER.next` (replays when there is none) and R replays.
**Sound effects and music**, in films only: in a chapter with a question, `sfx()` and `music()` are silent, unless the chapter sets `CHAPTER.film = true`: a film with interactive moments (a documentary where the reader fires a rifle). There, while a question beat waits for the reader after its narration, the music plays on (it rises to 70 %, as in a lead-in) and is not pulled back for the time it ran on, and a click on its step bar seeks into it like any other beat; the next beat's tracks take over as usual (`fade` 0 is a cut). `sfx(beat, t, name, vol)` plays `audio/sfx/<name>.mp3` when that beat's clock passes `t` in normal playback (a seek past it fires nothing), at half volume (vol 2 is full); effects are fetched and decoded when `sfx()` is called, before the first click; one still loading when it is due plays late, from its start, for up to a second. A long ambience listed in `SFX_BED` with its length (`SFX_BED.birds = 10`) is joined part-way after a seek. `music(file, beats, gain, fade)` is a looping track under the listed beats (all of them by default; called above `BEATS`, it takes them all when `boot()` runs, and a listed id that `BEATS` lacks is named in a console warning). Its place is the length of its earlier beats as they really ran plus the clock; a beat under music gives back from its closing hold the time the clock stood still (a clip getting going), so the film keeps the music's time. It ducks to 30 % for the whole beat, voice or not, and rises to 70 % only in the `pre` lead-in of the beats in `window.MUSIC_UP_IN_PRE` (`true` for all); it crossfades over `fade` s (0.8; 0 is a cut), and `window.MUSIC_OFF = { beat: t => true }` fades it out for a moment. Both go through one Web Audio graph started by the reader's first touch, click or key, so ducks, fades and the volume slider reach them on phones too (on iOS the slider does not reach the narration). A pause holds the music's level and a seek stops the effects. When a clip loading or buffering holds the clock, the music runs on, then eases back (5 % slower or faster), or jumps back once if it is more than a second out. Safari and every iOS browser stall a media element at each speed change, so there the music keeps the film's speed and is put back by a seek once it is a quarter second out, aimed ahead by the lag it showed after the last one. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.
-Progress is saved under `animebook:progress:<book-path>`; the cover and a picture book's series page read the same key. A book can set another key with `--progress-key` in `lib/book.css`; its cover must then read that key. Books served in different folders have separate saved places and completion lists.
-
-Treat saved progress as optional: malformed JSON, `null` or a non-object value starts with empty progress; only an array of positive integer chapter numbers is used for completion.
+Progress is saved under `animebook:progress:<book-path>`, the key the cover and a picture book's series page read; a book can set another with `--progress-key` in `lib/book.css`, and its cover must then read that key. Books served in different folders have separate saved places and completion lists. Saved progress is optional: malformed JSON, `null` or a non-object value starts with empty progress, and only an array of positive integer chapter numbers counts for completion.
Keep `<link rel="expect" href="#bar" blocking="render">` in every chapter's head; without it Chromium may paint before the player exists and cancel the page transition from the contents page.
@@ -133,6 +130,6 @@ Keep `<link rel="expect" href="#bar" blocking="render">` in every chapter's head
- In a JS string, double each TeX backslash (`'\\frac{a}{b}'`) or use `` String.raw`\frac{a}{b}` ``: `'\text'` is a tab followed by "ext".
- Write a formula wholly in TeX, an `eqLine` sign included (`sym: TX('\\le')`): TeX glyphs are smaller and lighter than `M()` text.
- **Global names.** The engine keeps its own state and helpers in a closure: a chapter may use any other name (`clock`, `fit`, `frame`, `last`, `ui`, `segs`, …; an older engine declared those too), and the engine calls its own functions: replacing one from outside (`window.start = …`) no longer reaches the engine; watch `P` instead. The names it puts in global scope are the API: `TRANSLATIONS PORTRAIT SW SH LANGUAGE translate DECIMAL_SIGN isShortcut NS UI BOOK bookSetting COL MATH NAME BAND RIGHT TOPR SCREEN SORT_SCREEN $m mk st put render G path T cite ctx2d textW F R E TX $tex texGraphic texPart OV M chip tokens layRow collapse mathEl io out back lin tw prog show hide draw pop pulse stream mix evalTo soft clockRun camera scene S AXIS X Y0 num reset tick dot arrow panel retire header fx fxp finishFx pulseFx shakeFx floatText TF $ kbd sources uiW SCORE h rich card mascotEl quiz qlayer keyAct choice mcq tap tapEls pickEls grid rat gcd lowest blanks SND P HOLD clearCards seek seekInto start setSpeed setPlaying setCaptions hideCover restart boot ENGINE seeking captions finishCard BOOK_PROGRESS_KEY progress`, plus the window properties `sfx music SFX SFX_BED BGM MathJax`. A chapter that declares one of them again stops with an error; prefix chapter helpers that would (`rect`, `popIn`, `eqLine`, `slot` from math.js too, when the chapter loads it). `lint.py` lists every clash, each name of a `const a = 1, b = 2` included. `finishCard` and `progress` stay assignable for `scorm-bridge.js`, which wraps them.
-- Drag handling: re-parent (append) the element before `setPointerCapture`; moving a node drops its capture.
+- Dragging: re-parent (append) the element before `setPointerCapture`; moving a node drops its capture.
- A card whose content is too long for `BAND` should become several `blanks` rows in a wider side card.
- When a question beat is continued early, the engine finishes the beat's pending tweens first; don't rely on half-finished fades.
diff --git a/.claude/skills/papermorph/references/core/publish.md b/.claude/skills/papermorph/references/core/publish.md
index 3144b29..1f816d9 100644
--- a/.claude/skills/papermorph/references/core/publish.md
+++ b/.claude/skills/papermorph/references/core/publish.md
@@ -1,6 +1,6 @@
# The book folder, preview and export
-The book is static: HTML, JS, CSS, MP3. No build step, backend, database or accounts; reading progress lives in the browser (`localStorage`). The runnable output is `site/<book>/`; source material and production notes stay outside it.
+The book is static: HTML, JS, CSS, MP3, with no build step, backend, database or accounts; reading progress lives in the browser (`localStorage`). The runnable output is `site/<book>/`; source material and production notes stay outside it.
## Start a book folder
@@ -10,29 +10,29 @@ Once per new slug, from the folder that holds `site/`, `books/`, `content/` and
python3 SKILL/scripts/new_book.py lesson|picture|documentary|shorts <book> [--chapter N] [--lang xx] [--maps]
```
-It runs `engine.py` into `site/<book>/lib/` (the engine, plus `lib/book.css` for this book's settings), copies the tier's kit and templates (the chapter page, the cover or series page, the sample narration, a picture book's paper kit and `sets.js`, a film's `film.js` or `shorts.js`, and with `--maps` the map kit), makes the working folders and prints the next commands. It refuses a slug whose `site/<book>/` exists; resume an existing book from its own files. What each tier does next is in its own file.
+It runs `engine.py` into `site/<book>/lib/` (the engine, plus `lib/book.css` for this book's settings), copies the tier's kit and templates (chapter page, cover or series page, sample narration, a picture book's paper kit and `sets.js`, a film's `film.js` or `shorts.js`, and with `--maps` the map kit), makes the working folders and prints the next commands. It refuses a slug whose `site/<book>/` exists; resume an existing book from its own files. Each tier's file says what comes next.
## Every book
-- Use the agreed primary language: the narration source is `narration.<lang>.json`, the chapter loads `audio/<lang>/timings.js`, and `CHAPTER.language` matches (default `en`; it picks the audio folder). Set `<html lang>` in `index.html` and every chapter to the same language: the player and the contents page take their interface text from it (English, Russian, Chinese and Japanese are built into the engine; other languages fall back to English until a block is added to the engine's `TRANSLATIONS`). Take `voice` and `rate` from `style.json`, and translate the template's own visible text (titles, lede, prompts) before the pilot.
-- A chapter's minutes appear on its title screen (`CHAPTER.minutes`), its contents card and a series card; write the same number in each: the length of its audio (the `dur`s in `timings.js`) plus about 15 s for each question, rounded to whole minutes and never below 1.
-- Each book has its own engine copy, kept in step with `engine.py` ([core/engine.md](engine.md)). The engine and the cover or series page derive the same progress key from the book's URL folder (or `--progress-key` in `lib/book.css`), so moving a book to another folder resets its readers' progress unless the key is set.
+- Use the agreed primary language: the narration source is `narration.<lang>.json`, the chapter loads `audio/<lang>/timings.js`, and `CHAPTER.language` matches (default `en`; it picks the audio folder). Set the same `<html lang>` in `index.html` and every chapter: the player and the contents page take their interface text from it (English, Russian, Chinese and Japanese are built in; other languages fall back to English until a block is added to the engine's `TRANSLATIONS`). Take `voice` and `rate` from `style.json`, and translate the template's visible text (titles, lede, prompts) before the pilot.
+- A chapter's minutes appear on its title screen (`CHAPTER.minutes`), its contents card and any series card, the same number in each: the length of its audio (the `dur`s in `timings.js`) plus about 15 s per question, rounded to whole minutes and never below 1.
+- Each book has its own engine copy, kept in step by `engine.py` ([core/engine.md](engine.md)). The engine and the cover or series page take the progress key from the book's URL folder ([core/engine.md](engine.md#player)), so moving a book resets its readers' progress unless `--progress-key` is set in `lib/book.css`.
- A chapter returns to its book's index; the book opens directly at `/<book>/` and needs no parent index page. Every chapter but the last sets `CHAPTER.next` to the next one.
-- The infinity guide comes with the engine (`mascotEl` in `engine.js`, the cover's in `contents.js`), so a book's copy is replaced at every sync. A custom guide needs a hook in the engine itself; agree it with the user and change the engine at its source.
+- The infinity guide comes with the engine (`mascotEl` in `engine.js`, the cover's in `contents.js`), so a book's copy is replaced at every sync. A custom guide needs a hook in the engine itself, agreed with the user and made at the engine's source.
## Local preview and delivery
-Serve the static output over HTTP, which audio playback needs:
+Audio playback needs HTTP:
```sh
python3 SKILL/scripts/serve.py 8765 site # no-store, so edits are never hidden by the browser cache
```
-Open `http://localhost:8765/<book>/`. Confirm the index opens its chapters, chapters return to it, and any reference links open their works. Deliver `site/<book>/` with its HTML, scripts, styles and audio, the preview command and entry URL, the available chapter count and unresolved issues. Source PDFs, extracted pages, narration drafts and development environments are not part of the static book. Putting a book on a bookshelf and hosting it are separate tasks.
+Open `http://localhost:8765/<book>/`. Confirm the index opens its chapters, chapters return to it, and any reference links open their works. Deliver `site/<book>/` (HTML, scripts, styles, audio) with the preview command and entry URL, the available chapter count and unresolved issues; source PDFs, extracted pages, narration drafts and development environments are not part of it. Putting a book on a bookshelf and hosting it are separate tasks.
## Languages
-Narration and on-screen text are written in one language first. A second language comes after the book is done and approved: keep beat ids and question ids stable, add `narration.<lang>.json` and audio per language, and decide with the user how switching behaves mid-chapter before building it.
+Write narration and on-screen text in one language first. A second language comes after the book is done and approved: keep beat and question ids stable, add `narration.<lang>.json` and audio per language, and agree with the user how switching behaves mid-chapter before building it.
## Video export
@@ -40,9 +40,9 @@ Narration and on-screen text are written in one language first. A second languag
uv run --with playwright --with numpy SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <chapter URL>
```
-It renders the beats to `OUT/chNN.mp4` (1080p, or 1080 × 1920 on the upright stage; 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, effects and music), so the video matches the page.
+It renders the beats to `OUT/chNN.mp4` (1080p, or 1080 × 1920 on the upright stage; 30 fps) plus `OUT/chNN.srt` to upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, effects and music), so the video matches the page.
-- A lesson's question beats are left out and its video ends on a card pointing to the interactive lesson. In a film with `CHAPTER.film`, they stay in: each holds its picture for the beat's `hold` s, the music up at 70 % as the page plays it while it waits, then the next beat plays as if the reader had acted ([documentary.md](../films/documentary.md#interactive-moments)).
+- A lesson's question beats are left out and its video ends on a card pointing to the interactive lesson. In a film with `CHAPTER.film` they stay: each holds its picture for the beat's `hold` s with the music up at 70 %, as the page plays it while waiting, then the next beat plays as if the reader had acted ([documentary.md](../films/documentary.md#interactive-moments)).
- A mix that would clip is turned down as a whole, and the run says by how much; odd sizes are cut to even ones (an upright `--height 720` gives 404 × 720). The video is written beside the old one and renamed when done, so a failed run leaves an earlier `chNN.mp4` alone.
- It takes about seven times the film's length at 1080 × 1920 (a 98.5 s short took 11 min 42 s); `--height 720 --fps 10` makes a quick check copy.
-- Video files are large (an episode at 1080p is tens of megabytes, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.
+- Video files are large (tens of megabytes for a 1080p episode, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.
diff --git a/.claude/skills/papermorph/references/core/review.md b/.claude/skills/papermorph/references/core/review.md
index 81066cd..0a6d954 100644
--- a/.claude/skills/papermorph/references/core/review.md
+++ b/.claude/skills/papermorph/references/core/review.md
@@ -1,6 +1,6 @@
# Seeing your own work, and review rounds
-Watch your output in motion and judge it as a viewer would, against the storyboard and the approved chapters; fix what you find, recheck those parts, then deliver for the user's judgement. Serve `site/` with `serve.py` ([core/publish.md](publish.md#local-preview-and-delivery)) and keep the evidence in `books/<book>/review/chNN/`. Each tier adds its own checks and what to look for: [lessons](../lessons/checks.md), [picture books](../picture-books/stories.md#review-rounds), [films](../films/films.md#review-rounds).
+Watch your output in motion and judge it as a viewer would, against the storyboard and the approved chapters; fix what you find, recheck those parts, then deliver for the user's judgement. Serve `site/` with `serve.py` ([core/publish.md](publish.md#local-preview-and-delivery)) and keep the evidence in `books/<book>/review/chNN/`. Each tier adds its own checks: [lessons](../lessons/checks.md), [picture books](../picture-books/stories.md#review-rounds), [films](../films/films.md#review-rounds).
## Contents
@@ -13,7 +13,7 @@ Watch your output in motion and judge it as a viewer would, against the storyboa
## Static checks first
-`python3 SKILL/scripts/lint.py site/<book> chNN` takes a second and needs no browser: a global name that clashes with the engine or a library (which stops the page script), beats without timings or MP3, marks the code waits for that the narration lacks, narration edited since `tts.py` ran, and a malformed `style.json`. Run it after every edit. `uv run --with playwright SKILL/scripts/check.py chNN --url …` then opens every beat in Chromium and Firefox and reports page errors, console warnings and each beat's length against its voice (a tween running past the voice lengthens a beat silently).
+`python3 SKILL/scripts/lint.py site/<book> chNN` takes a second and needs no browser. It finds a global name that clashes with the engine or a library (which stops the page script), beats without timings or MP3, marks the code waits for that the narration lacks, narration edited since `tts.py` ran, and a malformed `style.json`. Run it after every edit. `uv run --with playwright SKILL/scripts/check.py chNN --url …` then opens every beat in Chromium and Firefox and reports page errors, console warnings and each beat's length against its voice (a tween running past the voice lengthens a beat silently).
## Watch it in motion
@@ -22,11 +22,11 @@ uv run --with playwright --with pillow --with numpy SKILL/scripts/strip.py chNN
uv run --with playwright --with pillow SKILL/scripts/playlog.py chNN --out OUT --url http://localhost:8765/<book>/
```
-- A strip shows one beat at small steps, and a sheet of strips is the contact sheet every review works from. `@w` adds a motion WebP; `@o` adds an onion skin, the same frames laid over each other, later ones stronger, so spacing reads at a glance: even gaps are even speed, bunched ghosts are easing, a ghost that jumps is a pop. An onion skin reads only within one shot, so give it that shot's range (`roll:2..4`, ends may be marks); `@c` draws a picture book's frames in the set's own framing, so under a pan a planted foot stays one sharp ghost and a sliding one smears.
-- Look at each action as a viewer would: does the picture do what the narration says while it is said, does the thing named appear on screen, do props stay in hands, does the camera move with purpose, do labels and numbers agree with the motion? The worst defects in the first films were pictures that contradicted the narration, and they show on a contact sheet at once.
+- A strip shows one beat at small steps; a sheet of strips is the contact sheet every review works from. `@w` adds a motion WebP; `@o` adds an onion skin, the frames laid over each other with later ones stronger, so spacing reads at a glance: even gaps are even speed, bunched ghosts are easing, a ghost that jumps is a pop. An onion skin reads only within one shot, so give it that shot's range (`roll:2..4`, ends may be marks); `@c` draws a picture book's frames in the set's own framing, so under a pan a planted foot stays one sharp ghost and a sliding one smears.
+- Look at each action as a viewer would: does the picture do what the narration says while it is said, does the thing named appear, do props stay in hands, does the camera move with purpose, do labels and numbers agree with the motion? The worst defects in the first films were pictures that contradicted the narration, and they show on a contact sheet at once.
- Watch every beat to its end; problems hide in the beats nobody looked at.
-- A strip is a row of still pictures, so it cannot tell you that nothing is moving: a wave drawn once at a fixed phase looks right in every frame and is dead on screen. `uv run --with playwright --with pillow SKILL/scripts/still.py chNN --url …` lists the stretches of each beat where the stage does not change (in a picture book it switches off the kit's hand jitter and flicker first, so a puppet that only breathes and blinks measures about 1–1.5 and acting 2 and up; its default threshold is 1.5). Some holds are right (a moment to read a result); something that stands for motion should be moving whenever it is on screen.
-- Then watch a few beats live in Firefox with sound, which is how the user watches. An agent that cannot listen runs `playlog.py`: it logs when each sound and caption starts in real playback and shows the stage rebuilt at that moment, so a clack can be checked against the piece landing and a line against the mouth that says it. `--from`/`--to` play only some beats; a lesson stops at its first question.
+- A strip cannot show that nothing moves: a wave drawn once at a fixed phase looks right in every frame and is dead on screen. `uv run --with playwright --with pillow SKILL/scripts/still.py chNN --url …` lists the stretches of each beat where the stage does not change (in a picture book it first switches off the kit's hand jitter and flicker, so a puppet that only breathes and blinks measures about 1–1.5 and acting 2 and up; the default threshold is 1.5). Some holds are right (a moment to read a result); something that stands for motion should move whenever it is on screen.
+- Then watch a few beats live in Firefox with sound, as the user does. An agent that cannot listen runs `playlog.py`: it logs when each sound and caption starts in real playback and shows the stage rebuilt at that moment, so a clack can be checked against the piece landing and a line against the mouth that says it. `--from`/`--to` play only some beats; a lesson stops at its first question.
## Frames
@@ -34,23 +34,23 @@ uv run --with playwright --with pillow SKILL/scripts/playlog.py chNN --out OUT -
uv run --with playwright --with pillow SKILL/scripts/shot.py chNN --url http://localhost:8765/<book>/ --out OUT [--cuts] [--clean]
```
-`shot.py` captures the open and end frames of every beat as 4-up sheets and reports console errors; full-size `chNN_bII_T.png` files show thin geometry the sheet hides. Look for an empty or unrelated opening, text over drawings or clipped at the edge, a card covering what it asks about, leftovers half faded, text too small at half size or too much at once, and the same idea in different colours. `--cuts` puts each beat's last frame beside the next one's first, one cut a row: look there for jumps in place, pose, light and screen direction. `--clean` gives the stage alone, without the player.
+`shot.py` captures the open and end frames of every beat as 4-up sheets and reports console errors; full-size `chNN_bII_T.png` files show thin geometry the sheet hides. Look for an empty or unrelated opening, text over drawings or clipped at the edge, a card covering what it asks about, half-faded leftovers, text too small at half size or too much at once, and the same idea in different colours. `--cuts` puts each beat's last frame beside the next one's first, one cut a row: look there for jumps in place, pose, light and screen direction. `--clean` gives the stage alone, without the player.
## Smoothness
-`uv run --with playwright SKILL/scripts/perf.py chNN --url …` measures frame times in Firefox, which repaints SVG on the main thread and is the slowest common browser for these pages; headless Chromium hides paint cost. Look at the worst beats and transitions; the remedies are in [core/engine.md](engine.md#performance-firefox). Under load the machine is measured, not the page: with six workers exporting, a 16.7 ms beat read 48 to 109 ms. `perf.py` prints the load average and warns above the core count, and `--ref CH:BEAT[@T]` times a known moment in the same run to read a number against. The frame time that decides is taken on a quiet machine.
+`uv run --with playwright SKILL/scripts/perf.py chNN --url …` measures frame times in Firefox, the slowest common browser for these pages (headless Chromium hides paint cost). Look at the worst beats and transitions; the reasons and remedies are in [core/engine.md](engine.md#performance-firefox). Under load the machine is measured, not the page: with six workers exporting, a 16.7 ms beat read 48 to 109 ms. `perf.py` prints the load average and warns above the core count, and `--ref CH:BEAT[@T]` times a known moment in the same run to read a number against. The frame time that decides is taken on a quiet machine.
## Review rounds
-After the first cut, before the user watches, an independent director pass: a fresh agent on a strong model, report-only, given contact sheets of every beat and the approved chapters or reference film, with no knowledge of how the beats were built.
+After the first cut, before the user watches, an independent director pass: a fresh agent on a strong model, report-only, given contact sheets of every beat and the approved chapters or reference film, knowing nothing of how the beats were built.
- **Reports** are ranked: chapter or scene, beat-clock time, what is wrong as a viewer sees it, a concrete fix. Earlier good reports serve as examples. About half of what a director finds is usually the picture saying something other than the voice.
-- **A second round on the exported video** (`export.py`, then the director watches the MP4's frames) finds what the sheets hide; on the shorts it was the round that found most.
-- **Check what a director measured** before sending it back as work, and after the fixes take a quick look yourself at the new frames: one such look still found a wrong date and a dead frame.
+- **A second round on the exported video** (`export.py`, then the director watches the MP4's frames) finds what the sheets hide; on the shorts it found the most.
+- **Check what a director measured** before sending it back as work, and after the fixes look at the new frames yourself: one such look still found a wrong date and a dead frame.
- **Merging**: the coordinator turns the reports into one rework list, taking the director's side where reviewers disagree, and sends the parts back to the workers who made them.
- **Closing**: the next round starts by checking which findings were fixed; a last read-only pass counts them as fixed, partly fixed, not fixed or worse. Two or three rounds made the best episodes. Show the user each fix on a contact sheet as it is made, so a round is quick to check.
-A chapter the Skill made is a first cut: the rounds come before the user watches, and what the user says then still decides.
+The rounds come before the user watches; what the user says then still decides.
## The user's notes
diff --git a/.claude/skills/papermorph/references/core/sound.md b/.claude/skills/papermorph/references/core/sound.md
index e3e0ba9..b0436f5 100644
--- a/.claude/skills/papermorph/references/core/sound.md
+++ b/.claude/skills/papermorph/references/core/sound.md
@@ -1,6 +1,6 @@
# Narration, voices, effects and music
-Voices carry every book; everything else sits under them. In early cuts the music and effects were loud enough that the lines got lost, and that was the first thing viewers noticed. How each tier uses sound is in its own file (a picture book's mouths and scene clips in [stories.md](../picture-books/stories.md#sound), a film's tracks in [films.md](../films/films.md#voice-and-music)); this file is the shared part.
+Voices carry every book and everything else sits under them: in early cuts music and effects buried the lines, and viewers noticed that first. Each tier's own use of sound is in its file (a picture book's mouths and scene clips in [stories.md](../picture-books/stories.md#sound), a film's tracks in [films.md](../films/films.md#voice-and-music)); this file is the shared part.
## Contents
@@ -20,23 +20,23 @@ Voices carry every book; everything else sits under them. In early cuts the musi
"beats": { "intro": "Chapter five. [[sub]]Subtraction undoes addition.", "...": "..." } }
```
-- `[[name]]` goes right before the word an action waits for; `m('name', offset)` in the page returns when that word starts. Names are unique within a beat; a misspelt mark makes the page throw, and a mark that matches no spoken word makes the voice script stop.
-- Write for the ear: short sentences, one idea each. Say symbols, units and numbers in words ("negative seven halves", "meters per second squared"); the picture shows the symbols. Match the audience: plain, warm, never childish.
-- A wordless beat (a series card, an end card) needs no clip, no `timings.js` entry and no narration line: `{ dur: 2 }` in its fourth slot ([core/engine.md](engine.md#timing)); `lint.py`, `export.py`, `music.py` and `check.py` take it as silence. A time only the page needs goes in the page, not in `timings.js`, which the next voice run rewrites.
+- `[[name]]` goes right before the word an action waits for; `m('name', offset)` in the page returns when that word starts. Names are unique within a beat; a misspelt mark makes the page throw, and a mark that matches no spoken word stops the voice script.
+- Write for the ear: short sentences, one idea each. Say symbols, units and numbers in words ("negative seven halves", "meters per second squared"); the picture shows the symbols. Plain and warm, never childish.
+- A wordless beat (a series card, an end card) needs no clip, `timings.js` entry or narration line: `{ dur: 2 }` in its fourth slot ([core/engine.md](engine.md#timing)); `lint.py`, `export.py`, `music.py` and `check.py` take it as silence. A time only the page needs goes in the page, not in `timings.js`, which the next voice run rewrites.
## Voices
-- **`tts.py`** (free): `uv run --with edge-tts SKILL/scripts/tts.py <narration.json> site/<book>/chNN/audio/<lang>` writes `<beat>.mp3` and `timings.js` (duration, marks, captions) and caches each finished beat beside the narration file: moving `[[marks]]` reuses the cache, and after a failure the same command resumes. It takes a few seconds a beat, so a long chapter can outlast a tool's foreground time limit: run it in the background and wait for it before `lint.py`.
+- **`tts.py`** (free): `uv run --with edge-tts SKILL/scripts/tts.py <narration.json> site/<book>/chNN/audio/<lang>` writes `<beat>.mp3` and `timings.js` (duration, marks, captions) and caches each finished beat beside the narration file: moving `[[marks]]` reuses the cache, and after a failure the same command resumes. At a few seconds a beat, a long chapter can outlast a tool's foreground time limit: run it in the background and wait for it before `lint.py`.
- `"engine": "edge"` (default, online) or `"kokoro"` (local, Apache 2.0, English word timings; voices such as `am_michael`, `af_heart`, `bm_george`; `uv run --python 3.12 --with kokoro …`), set at the top of the narration file with `voice` and `rate`. Keep one engine and voice per book (per character in a picture book).
- Edge's `...MultilingualNeural` voices guess the language sentence by sentence and read a short line such as "No zero, no fractions, no negatives." with a Spanish or Portuguese accent; a book in one language uses a one-language voice of that language.
-- **`eleven.py`** (ElevenLabs v4 through OpenRouter, paid, an OpenRouter key): the voice the user chose for the films. It writes the same clips and `timings.js`; the page cannot tell them apart.
- - It takes the voice and model from `--voice` and `--model`, else from the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`; the kits' files name an Edge voice).
- - It prints the cost before paying (`--dry` stops there; about $0.07 a minute, quote it), keeps paid clips cached (a rerun costs nothing), and `--only beat,beat` makes a fresh, paid take of those beats alone.
- - A voice sped up (`--tempo 1.1`, or `"tempo"` in the narration file) is sped before levelling and alignment, and stays sped on a rerun. `--max-pause 0.3` shortens its sentence pauses (0.4 to 1.0 s) before the marks are placed.
+- **`eleven.py`** (ElevenLabs v4 through OpenRouter, paid, an OpenRouter key): the voice the user chose for films. It writes the same clips and `timings.js`; the page cannot tell them apart.
+ - Voice and model come from `--voice` and `--model`, else from the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`; the kits' files name an Edge voice).
+ - It prints the cost before paying (`--dry` stops there; about $0.07 a minute, quote it) and caches paid clips (a rerun costs nothing); `--only beat,beat` makes a fresh, paid take of those beats alone.
+ - A sped-up voice (`--tempo 1.1`, or `"tempo"` in the narration file) is sped before levelling and alignment, and stays sped on a rerun. `--max-pause 0.3` shortens its sentence pauses (0.4 to 1.0 s) before the marks are placed.
- v4 audio tags such as `[cackles]` are acted, not read, and left out of the captions and of `lint.py`'s comparison of narration and page.
- - Its word alignment (local faster-whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now. The transcript writes spoken numbers as digits; `eleven.py` matches them back and prints the marks a rerun moved, but check marks on numbers, since a missed one lands late (up to 0.75 s).
+ - Its word alignment (local faster-whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now. The transcript writes spoken numbers as digits; `eleven.py` matches them back and prints the marks a rerun moved, but check marks on numbers: a missed one lands late (up to 0.75 s).
- **Several voices.** List them under `voices` in the narration file and write each line as `{"speaker": name, "text": …}`; a line without a speaker takes the file's own `voice`, and a speaker missing from `voices` stops the run, naming it. Both scripts do this. Voices need pitches apart (a dog at 113 Hz under a 110 Hz narrator read as the same person).
-- Let the user pick a voice by ear: play a few short samples in the book's own words.
+- Let the user pick a voice by ear from a few short samples in the book's own words.
## Levels
@@ -44,20 +44,20 @@ Voices carry every book; everything else sits under them. In early cuts the musi
## Sound effects
-`sfx.py` synthesizes effects as small MP3s, free and consistent (knock, door, creak, bell, chop, crash, coin, rain, wind, room tone, surf, gulls, crickets, footsteps, a dog, whoosh, bang, tick, thud and more; `--list` names them all). A sound the list lacks goes in the book's own `books/<book>/sfx_recipes.py`, passed with `--recipes`: each top-level function without required arguments is a recipe named after it, returning samples at `sfx.SR`, built from sfx's own helpers (the script's header has the details). Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain.
+`sfx.py` synthesizes effects as small MP3s, free and consistent (knock, door, creak, bell, chop, crash, coin, rain, wind, room tone, surf, gulls, crickets, footsteps, a dog, whoosh, bang, tick, thud and more; `--list` names them all). A sound it lacks goes in the book's own `books/<book>/sfx_recipes.py`, passed with `--recipes`: each top-level function without required arguments is a recipe named after it, returning samples at `sfx.SR`, built from sfx's own helpers (details in the script's header). Keep them soft and natural: the first rain, a high hiss, read as scary; pink noise with patter and taps on umbrellas read as rain.
-- Place an effect on a beat's clock with the engine's `sfx(beat, t, name, volume)` (in a picture book each scene is a beat); it plays at half volume under the voices (vol 2 is full), a pause holds it and the next beat stops it. Cut an effect to its shot: a six-second rain under a one-second shot spills into the next.
-- A long bed (wind, room tone, the 10 s `birds` of a park) is listed in `SFX_BED` with its length (`SFX_BED.birds = 10`), so a seek into the middle joins it part-way; a bed that loops overlaps its seams by about half a second; room tone runs under the silences too, where its absence is heard first.
+- Place an effect on a beat's clock with the engine's `sfx(beat, t, name, volume)` (in a picture book each scene is a beat); it plays at half volume under the voices (vol 2 is full), a pause holds it and the next beat stops it. Cut an effect to its shot: six seconds of rain under a one-second shot spills into the next.
+- A long bed (wind, room tone, a park's 10 s `birds`) goes in `SFX_BED` with its length (`SFX_BED.birds = 10`) so a seek joins it part-way; a looping bed overlaps its seams by about half a second; room tone runs under the silences too, where its absence is heard first.
## Music
-`music(file, beats, gain, fade)` in the chapter page, one call per track ([core/engine.md](engine.md#player) has the mechanics): it ducks to 30 % for the whole of every beat, voice or not, rises to 70 % in the `pre` lead-in of the beats in `window.MUSIC_UP_IN_PRE`, crossfades over `fade` seconds (0.8; 0 is a cut), and `window.MUSIC_OFF = { beat: t => … }` fades it out for a moment. Music does not stop dead mid-scene: carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place.
+`music(file, beats, gain, fade)` in the chapter page, one call per track: it ducks to 30 % under every beat, rises in chosen `pre` lead-ins, crossfades and can fade out for a moment ([core/engine.md](engine.md#player) has the mechanics and settings). Music does not stop dead mid-scene: carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place.
-- **Where it comes from.** Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them. `commons.py --audio` finds public-domain recordings. A composition can be centuries old while its recording is still protected: Commons marks some 1950s–60s recordings public domain under EU rules that the US does not follow (protected there until 2067), and `commons.py`'s licence check cannot see this. Prefer recordings their performers released (PDM-owner, CC0), Musopen, or US military bands. Generated music (Lyria) is made outside the Skill for now.
-- **Cut to the film.** `music.py cut SRC site/<book>/chNN/audio/bgm/NAME.mp3 chNN --url …/<book>/` cuts a recording so its last note lands on the film's end (the last moment it is within 10 LU of its body, so a long decay rings past the end; `--end` sets it by hand) and levels it to −16 LUFS. `--rests` splices out its rests and `--even` evens out its quiet phrase ends (a generated track usually needs it too: its quiet passages fall into the voice's gaps just as a recording's do), `--lift T` raises a hole neither fixes. The cut is made for one length: after any change to a beat's length, cut again (`gaps` says "recut").
-- **Level by ear, check by measure.** Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the ducking to 30 %, a track at −16 LUFS sits about 20 LU under a −14 LUFS voice, the level the user chose for the first short. The gain is relative to the track's own loudness, so give both. `music.py gaps chNN --url …` lists the bed's loudness in each voice-free gap and after the last word and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.
+- **Where it comes from.** Use tracks the book may redistribute (generated for it, or openly licensed) and credit them. `commons.py --audio` finds public-domain recordings. A composition can be centuries old while its recording is still protected: Commons marks some 1950s–60s recordings public domain under EU rules the US does not follow (protected there until 2067), and `commons.py`'s licence check cannot see this. Prefer recordings their performers released (PDM-owner, CC0), Musopen, or US military bands. Generated music (Lyria) is made outside the Skill for now.
+- **Cut to the film.** `music.py cut SRC site/<book>/chNN/audio/bgm/NAME.mp3 chNN --url …/<book>/` cuts a recording so its last note lands on the film's end (the last moment it is within 10 LU of its body, so a long decay rings past the end; `--end` sets it by hand) and levels it to −16 LUFS. `--rests` splices out its rests and `--even` evens out its quiet phrase ends (a generated track usually needs it too: its quiet passages fall into the voice's gaps just as a recording's do); `--lift T` raises a hole neither fixes. The cut fits one length: after any change to a beat's length, cut again (`gaps` says "recut").
+- **Level by ear, check by measure.** Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the ducking to 30 %, a −16 LUFS track then sits about 20 LU under a −14 LUFS voice, the level the user chose for the first short. The gain is relative to the track's own loudness, so give both. `music.py gaps chNN --url …` lists the bed's loudness in each voice-free gap and after the last word and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.
## Captions and other languages
-- Captions come from the narration and appear when their words are heard. A beat's last caption clears a second after its narration.
-- **Lines in other languages** are spoken in their own language by a native voice (Edge has Japanese, Chinese, Korean and more) and subtitled in the book's language: write the beat's `"sub"`, the original and the translation in brackets. The voice script marks such a line (its voice's locale differs from the narration file's language), so the page shows its subtitle even with captions off, the way films subtitle foreign dialogue.
+- Captions come from the narration and appear as their words are heard; a beat's last caption clears a second after its narration.
+- **Lines in other languages** are spoken by a native voice of their language (Edge has Japanese, Chinese, Korean and more) and subtitled in the book's language: write the beat's `"sub"`, the original and the translation in brackets. The voice script marks such a line (its voice's locale differs from the narration file's language), so the page shows its subtitle even with captions off, the way films subtitle foreign dialogue.
diff --git a/.claude/skills/papermorph/references/core/style.md b/.claude/skills/papermorph/references/core/style.md
index c2c5a82..bb845f2 100644
--- a/.claude/skills/papermorph/references/core/style.md
+++ b/.claude/skills/papermorph/references/core/style.md
@@ -1,22 +1,22 @@
# The conversation and style.json
-A cold agent has no idea what the user wants, and its guesses diverge from run to run. Every book therefore starts with a short conversation whose outcome is `books/<book>/style.json`, the anchor every chapter is made against. It fixes *what* the book looks and sounds like; *how* each moment is animated stays free. Each tier's intake says what to ask ([lessons](../lessons/intake.md), [picture books](../picture-books/stories.md#intake-for-a-story), [films](../films/films.md#intake)); this file is how to ask, the models step and the file itself.
+Left to guess what the user wants, an agent's guesses diverge from run to run. So every book starts with a short conversation that ends in `books/<book>/style.json`, the anchor every chapter is made against. It fixes *what* the book looks and sounds like; *how* each moment is animated stays free. Each tier's intake says what to ask ([lessons](../lessons/intake.md), [picture books](../picture-books/stories.md#intake-for-a-story), [films](../films/films.md#intake)); this file covers how to ask, the models step and the file itself.
## Asking
-- Many users want to click, not type. Every point where you need the user, from finding the source to approving the finished chapter, is a choice: two to four concrete options drawn from this book, the recommended one first and labelled so, so that accepting every recommendation still makes a good book. Use the structured question tool when there is one (at most four questions a round); otherwise number the options so a single digit answers. Their own words are always welcome, never required.
-- Questions come from this book and this chapter, not from a form. Skip what the material or earlier answers already settle.
-- After each round, say the answers back as decisions in one or two lines, then move on.
-- Keep what the user says about the look **verbatim** in `words`; later chapters need their taste, not a summary of it. When they only pick options, record the chosen options' wording.
-- The conversation should feel light: the user tries one chapter (or episode) first and decides about the rest after seeing it.
+- Many users want to click, not type. Every point where you need the user, from finding the source to approving the finished chapter, is a choice: two to four concrete options drawn from this book, the recommended one first and labelled so, so that accepting every recommendation still makes a good book. Use the structured question tool when there is one (at most four questions a round); otherwise number the options so one digit answers. Their own words are welcome, never required.
+- Ask from this book and this chapter, not from a form; skip what the material or earlier answers already settle.
+- After each round, say the answers back as decisions in a line or two, then move on.
+- Keep what the user says about the look **verbatim** in `words`: later chapters need their taste, not a summary of it. When they only pick options, record the chosen options' wording.
+- Keep it light: the user tries one chapter (or episode) first and decides about the rest after seeing it.
## Models
-Which model does which step is the user's choice. Users run the Skill with different models and providers, and a book can mix them. Show the defaults for the book's tier as one table, one row per step of that tier's team ([core/team.md](team.md)), and ask: keep it (recommended), or change some rows. Any model the user names is fine.
+Which model does which step is the user's choice; users run the Skill with different models and providers, and a book can mix them. Show the tier's defaults as one table, one row per step of its team ([core/team.md](team.md)), and ask: keep it (recommended), or change some rows. Any model the user names is fine.
| Step | Lesson, tier 1 | Lesson, tier 2 | Picture book | Documentary | Short |
|---|---|---|---|---|---|
-| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) | strong (research, script and storyboard with the user; then voice and music) | strong (the script and storyboard with the user; then voice and music) |
+| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) | strong (research, script and storyboard with the user; then voice and music) | strong (script and storyboard with the user; then voice and music) |
| Narration and beats | middle | middle | strong (voices, the episode kit) | middle (pictures found and treated) | middle (pictures generated or found) |
| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene | middle, one worker per part of the film | middle (the beats) |
| Checks | small | small | small (sound effects too) | small | small |
@@ -24,7 +24,7 @@ Which model does which step is the user's choice. Users run the Skill with diffe
| Rework | strong | strong | middle, per scene | middle, per part | middle |
| Register | small | small | small | small | small |
-**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual model names into `models`, keyed by step as in the [lesson](../../assets/templates/style.json) or [picture-book](../../assets/templates/picture-book/style.json) template (a picture book's keys name its roles: `script`, `kit`, `scenes`, `sound`, `director`, `reviewers`; a [documentary](../../assets/templates/documentary/style.json)'s and a [short](../../assets/templates/shorts/style.json)'s: `script`, `pictures`, `beats`, `checks`, `director`). Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
+**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual names into `models`, keyed by step as in the [lesson](../../assets/templates/style.json) or [picture-book](../../assets/templates/picture-book/style.json) template (a picture book's keys name its roles: `script`, `kit`, `scenes`, `sound`, `director`, `reviewers`; a [documentary](../../assets/templates/documentary/style.json)'s and a [short](../../assets/templates/shorts/style.json)'s: `script`, `pictures`, `beats`, `checks`, `director`). Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
## style.json
@@ -49,6 +49,6 @@ Start from the tier's template: [lessons](../../assets/templates/style.json), or
| `courses` | the course options chosen ([courses.md](../lessons/courses.md)) | when chosen |
| `approved` | chapters the user approved and what each shows well | filled as chapters are approved |
-Leave out blocks the tier does not use. A reader that meets a block it does not know reads it as plain intent. Increase `schema` only when an existing field changes meaning. Keep the file current and short: chapter status, errata and historical feedback stay in `chapters.md` and `chapters/chNN.md`.
+Leave out blocks the tier does not use; a reader that meets an unknown block reads it as plain intent. Increase `schema` only when an existing field changes meaning. Keep the file current and short: chapter status, errata and historical feedback go in `chapters.md` and `chapters/chNN.md`.
Deliver the pilot with a choice: approve and make the rest (recommended when it is good), approve and stop here, or one of two or three concrete changes you would make yourself. Fold the answer and any feedback into `words` and the affected block, and add an approved chapter to `approved`. Approved chapters are the strongest anchor: later chapters watch and read them as worked examples.
diff --git a/.claude/skills/papermorph/references/core/team.md b/.claude/skills/papermorph/references/core/team.md
index cea10bb..f4eaa71 100644
--- a/.claude/skills/papermorph/references/core/team.md
+++ b/.claude/skills/papermorph/references/core/team.md
@@ -1,8 +1,8 @@
# Making a chapter with a team of models
-A chapter can be made by a coordinator handing each step to a fresh subagent on the model that suits it. How a tier splits the work is in its own file: lessons by step of the chapter loop ([lessons.md](../lessons/lessons.md#team)), picture books by scene ([stories.md](../picture-books/stories.md#team)), films by part of the film or by episode ([films.md](../films/films.md#team)). Without subagents, run the same steps in the current agent with file-based state.
+A coordinator can hand each step of a chapter to a fresh subagent on the model that suits it. Each tier's file says how it splits the work: lessons by step of the chapter loop ([lessons.md](../lessons/lessons.md#team)), picture books by scene ([stories.md](../picture-books/stories.md#team)), films by part of the film or by episode ([films.md](../films/films.md#team)). Without subagents, run the same steps in the current agent with file-based state.
-Why this shape: one agent doing a whole chapter carries an ever larger context through every call, and long idle waits make that context expire and get written again; that, more than the model's price, makes a chapter expensive. Small workers that start from the files they need and finish quickly cost far less, and each step can use the cheapest model that does it well. On a physics book this cost about half as much per minute of narration as one strong agent doing everything, at the same quality.
+Why: one agent doing a whole chapter carries an ever larger context through every call, and long idle waits let that context expire and be written again; that, more than the model's price, makes a chapter expensive. Small workers that start from the files they need and finish quickly cost far less, and each step can use the cheapest model that does it well. On a physics book this cost about half as much per minute of narration as one strong agent doing everything, at the same quality.
Each step runs on the model the user chose for it (`models` in `style.json`, [core/style.md](style.md#models)). The defaults are named by strength: **small** (fast and cheap), **middle**, **strong** (the most capable); where `models` is silent, use them and say which model you picked.
@@ -11,12 +11,12 @@ Each step runs on the model the user chose for it (`models` in `style.json`, [co
You read SKILL.md, your tier's file and this one, look at the sheets and the workers' replies, and pass work on. You don't write the chapter, read the page code or read workers' transcripts; keeping your own context small is most of the saving.
- For the pilot the coordinator is the main conversation, since the user sees its sheets and choices. The narration and first frames made at intake are where the steps start, not something to redo.
-- After the pilot a fresh session is the best coordinator, starting from SKILL.md, the tier's file and `style.json`: a long conversation rereads its whole history at every step, and contact sheets make that history large fast.
-- A worker needs little besides this Skill and `style.json`: the user's words, the look, the approved chapters to watch and read, the element library. Its brief adds the chapter, its pages, the step's inputs and outputs, what not to touch, any current user request, the preview URL (start one server for everyone) and a reply of a few lines. Start workers in the background and pass work on as soon as a step returns. Workers don't commit; the coordinator registers the chapter.
-- Wherever a step names the previous or approved chapter as its model, a new book's first chapter (or a series' first episode) has none yet: use what the user agreed at intake (the pilot frames or sheet, the storyboard, `style.json`), the Skill's templates and the books on the shelf. The first chapter the user approves becomes the model from then on.
+- After the pilot a fresh session coordinates best, starting from SKILL.md, the tier's file and `style.json`: a long conversation rereads its whole history at every step, and contact sheets make that history large fast.
+- A worker needs little besides this Skill and `style.json` (the user's words, the look, the approved chapters to watch and read, the element library). Its brief adds the chapter, its pages, the step's inputs and outputs, what not to touch, any current user request, the preview URL (one server for everyone) and a reply of a few lines. Start workers in the background and pass work on as soon as a step returns. Workers don't commit; the coordinator registers the chapter.
+- Where a step names the previous or approved chapter as its model, a new book's first chapter (or a series' first episode) has none yet: use what the user agreed at intake (the pilot frames or sheet, the storyboard, `style.json`), the Skill's templates and the books on the shelf. The first chapter the user approves becomes the model from then on.
- A brief that only asks a worker to look gets skipped; name the commands to run and ask the reply to say what each showed.
- A shared kit (the episode's helpers, the film's pieces) is read-only for the workers: one that needs more asks the coordinator, so every part gets the fix.
-- The chapter must reach the same bar as the book's approved chapters, in the same look, so it sits on the shelf beside them as one book.
+- The chapter must reach the bar of the book's approved chapters, in the same look, so it sits beside them on the shelf as one book.
## Before delivering
@@ -28,6 +28,6 @@ Several episodes or parts made at once each get their own git worktree, branch a
- `books/` and `content/` are git-ignored, so a worktree has neither. `lint.py` finds them in the main checkout by itself; for everything else, give the brief's paths into them absolute, and no worker creates them in its worktree.
- A shared file every worker appends to (one `img/SOURCES.md` for six episodes) conflicts at every merge. Give each worker its own (sources per episode, sizes per episode with `prep.py --art chNN-art.js`), joined once after the merge, and keep the shared files read-only for the workers.
-- The brief is the only rule book: say each file name and each shared file's rule once, the same in the common brief and in each worker's go. One run named the pictures two different ways in two places, and both forbade and invited edits to the sources file.
+- The brief is the only rule book: state each file name and each shared file's rule once, the same in the common brief and in each worker's go. One run named the pictures two ways in two places, and both forbade and invited edits to the sources file.
- Workers that share one paid balance make their pictures before their voice: `paint.py` stops while an OpenRouter balance is under $1.00, and whoever voices first can lock the others out of pictures.
-- Under load the machine is measured, not the page ([core/review.md](review.md#smoothness)): a loudness or timing that one worker reports under load is worth one more measurement before anyone acts on it.
+- Under load the machine is measured, not the page ([core/review.md](review.md#smoothness)): a loudness or timing one worker reports under load is worth one more measurement before anyone acts on it.
diff --git a/.claude/skills/papermorph/references/films/documentary.md b/.claude/skills/papermorph/references/films/documentary.md
index e0b2868..956fbe7 100644
--- a/.claude/skills/papermorph/references/films/documentary.md
+++ b/.claude/skills/papermorph/references/films/documentary.md
@@ -1,18 +1,16 @@
# Documentaries: from a book or an idea to a film
-A documentary is a narrated film about a book, an idea or a stretch of history on the wide stage: two minutes for one idea, ten or fifteen for a book's argument. Its pictures are mostly found: public-domain engravings, paintings and photographs, a few line drawings that draw themselves on, words set large, a map or two, all on one coloured ground and moved in step with a narrator. Usually the reader just watches; a film can also hand them the action at a few moments ([Interactive moments](#interactive-moments)). *Madness and Civilization* (`site/madness/`) is the approved reference: when in doubt, open it and match its level. *Shooting an Elephant* (`site/shooting-an-elephant/`) is the interactive one: the reader fires the rifle.
-
-Intake, the folder, pictures, maps, voice, team and review are shared with shorts in [films.md](films.md). The kit is `assets/templates/documentary/` (`chapter.html`, `narration.en.json`, `style.json`, `lib/film.js`, `lib/book.css`, `lib/fonts.css` and the fonts).
+A documentary is a narrated film on the wide stage about a book, an idea or a stretch of history. Its pictures are mostly found: public-domain engravings, paintings and photographs, a few line drawings that draw themselves on, words set large, a map or two, all on one coloured ground and moved in step with a narrator. Usually the reader just watches; a film can also hand them the action at a few moments ([Interactive moments](#interactive-moments)). The references are in [films.md](films.md), which also holds intake, the folder, pictures, maps, voice, team and review. The kit is `assets/templates/documentary/` (`chapter.html`, `narration.en.json`, `style.json`, `lib/film.js`, `lib/book.css`, `lib/fonts.css` and the fonts).
## The order of work
-1. **Research and the script.** Read the source, and trace every number and quote to where it was first said: a figure found on Wikipedia goes back to the speech or report Wikipedia cites, and that is the source to tag (Wikipedia's "low and middle-income" was the WHO's "low-income"). Read what each date counts, too: the day a virus arrived somewhere is not the day of its first confirmed case. Then write the narration (`content/<book>/chNN/narration.en.json`, [core/sound.md](../core/sound.md#the-narration-file), one beat per paragraph, `[[mark]]` before each word a picture lands on) and a storyboard table (`books/<book>/storyboard.md`: beat, what is said, what we see, which picture). Show both to the user before anything is built. The hard part of a documentary is the argument and the storyboard, not the animation.
+1. **Research and the script.** The hard part of a documentary is the argument and the storyboard, not the animation. Trace every number and quote to where it was first said: a figure found on Wikipedia goes back to the speech or report it cites, and that is the source to tag (Wikipedia's "low and middle-income" was the WHO's "low-income"). Read what each date counts: the day a virus arrived somewhere is not the day of its first confirmed case. Then write the narration (`content/<book>/chNN/narration.en.json`, [core/sound.md](../core/sound.md#the-narration-file), one beat per paragraph) and a storyboard table (`books/<book>/storyboard.md`: beat, what is said, what we see, which picture), and show both to the user before anything is built.
2. **The folder** ([films.md](films.md#the-folder)).
-3. **Pictures**: find them, record them, treat them ([films.md](films.md#pictures)).
-4. **Voice**: `tts.py` or `eleven.py`, one clip per beat and `timings.js` with the marks ([core/sound.md](../core/sound.md#voices)).
-5. **Music.** One recording per part of the film, changing at the turns, never abruptly, at a level that never covers the narrator; open with something short and rhythmic so the start is not slow. Find recordings (`commons.py --audio`), bring them to one loudness (`level.py`), and give each part its track with `music(file, beats, gain, fade)` ([core/sound.md](../core/sound.md#music)).
+3. **Pictures**: find, record, treat ([films.md](films.md#pictures)).
+4. **Voice**: `tts.py` or `eleven.py` ([core/sound.md](../core/sound.md#voices)).
+5. **Music.** One recording per part of the film, changing at the turns, never abruptly; open with something short and rhythmic so the start is not slow. Find recordings (`commons.py --audio`), bring them to one loudness (`level.py`), and give each part its track with `music(file, beats, gain, fade)` ([core/sound.md](../core/sound.md#music)).
6. **The beats**, built from the kit's helpers and timed to the marks (below).
-7. **Review rounds** ([films.md](films.md#review-rounds)), then the user's viewing, then `export.py` for a video if the user wants one ([core/publish.md](../core/publish.md#video-export)). Putting the film on a bookshelf is a separate task.
+7. **Review rounds** ([films.md](films.md#review-rounds)), the user's viewing, then `export.py` if the user wants a video ([core/publish.md](../core/publish.md#video-export)).
## Building the beats
@@ -25,9 +23,9 @@ Intake, the folder, pictures, maps, voice, team and review are shared with short
Add the film's own recurring pieces at the end of the book's `film.js` (Foucault's guide peeking up from the bottom edge, the Europe map). The kit's chapter sets `lead: false`: every opening is timed by hand.
-A film can stretch the kit where its story asks. *Shooting an Elephant* added a red overprint to `say()` (`mark`), a band to `closeups()`, a `clip()` that plays a `<video>` (`img/moulmein-live.mp4`) on the beat clock, and silhouette puppets in the manner of Lotte Reiniger (`lib/puppets.js`). A live `<video>` is the quicker way to a moving shot, at a cost: the export seeks frame by frame without waiting for the video to decode, so an exported clip can lag a frame, where a `frames.py` sheet agrees exactly; check the export, and turn the clip into frames if it shows (the comment on `clip()` in that book's `lib/film.js` says so).
+A film can stretch the kit where its story asks. *Shooting an Elephant* added a red overprint to `say()` (`mark`), a band to `closeups()`, a `clip()` that plays a `<video>` (`img/moulmein-live.mp4`) on the beat clock, and silhouette puppets after Lotte Reiniger (`lib/puppets.js`). A live `<video>` is the quicker way to a moving shot, but the export seeks frame by frame without waiting for it to decode, so an exported clip can lag a frame where a `frames.py` sheet agrees exactly; check the export and turn the clip into frames if it shows (the comment on `clip()` in that book's `lib/film.js` says so).
-Look at your own frames while you build, not only at the end: after each few beats, `shot.py` or `?beat=N&t=S` at the moments a picture lands, and a `strip.py` contact sheet of the beat against its storyboard row ([core/review.md](../core/review.md#watch-it-in-motion)). Ask what a viewer sees while each word is said: is the thing named on screen, does a word or label sit on a face, is the screen sparse.
+Look at your frames every few beats while you build, not only at the end: `shot.py` or `?beat=N&t=S` where a picture lands, a `strip.py` sheet against the beat's storyboard row ([core/review.md](../core/review.md#watch-it-in-motion)). Ask what a viewer sees while each word is said: is the thing named on screen, does a word or label sit on a face, is the screen sparse.
What made the Foucault film work:
@@ -35,16 +33,16 @@ What made the Foucault film work:
- **Close-ups on what is named.** When the narration names "the greedy" and "the vain" aboard the ship of fools, the camera goes to each in the woodcut, with the words as a label.
- **A host, used sparingly.** The author as a cut-out guide works at the key points; fifteen appearances were too many and were cut back.
- **Characters get voices** for a line or a laugh, short: the jester's laugh at the end of a section, not over it.
-- **The ending gathers the film.** Foucault ends with every era's Fool appearing in turn, and the opening epigraph returns.
+- **The ending gathers the film.** Every era's Fool appears in turn, and the opening epigraph returns.
- **Words on screen are few**: a key word, a quote being read, a year. Everything else is said.
## Interactive moments
-A documentary can give the reader a few moments to act, where the story turns on a choice or a deed: in *Shooting an Elephant* the reader looks through the rifle's sight and fires, as Orwell did, and the film goes on from the shot. Open `site/shooting-an-elephant/ch01/index.html` and read `fireAsk` before writing one.
+A documentary can give the reader a few moments to act where the story turns on a choice or a deed: in *Shooting an Elephant* the reader looks through the rifle's sight and fires, as Orwell did, and the film goes on from the shot. Open `site/shooting-an-elephant/ch01/index.html` and read `fireAsk` before writing one.
-- `CHAPTER.film = true` keeps the chapter a film although some beats ask something: its sound effects and music play, the cover offers Play and the film's length instead of a lesson; the help lists the question keys unless the chapter also sets `CHAPTER.questionKeys = false`, for moments with their own controls (the rifle) ([core/engine.md](../core/engine.md#player)).
+- `CHAPTER.film = true` keeps the chapter a film although some beats ask something: its effects and music play, and the cover offers Play and the film's length instead of a lesson; the help lists the question keys unless the chapter also sets `CHAPTER.questionKeys = false`, for moments with their own controls (the rifle) ([core/engine.md](../core/engine.md#player)).
- The moment is a beat whose `ask` is the chapter's own `done => { … }` rather than a `quiz()`. The engine calls it as the beat starts; once the narration and the beat's tweens are over, `P.waiting` turns true and the page waits. The handler listens on the stage (a click, a key), acts only while `P.waiting`, answers at once (a flash, a bang) and calls `done()` once, after which the next beat plays.
-- A reader can step back or replay the beat while the handler is still listening. Note `P.gen` when the handler starts and compare it in every listener and timer: when it has changed, that start of the beat is over, so remove the listeners and do nothing (the engine already ignores a stale `done()`, but not the handler's own flash or sound).
-- While the page waits, the music plays on and rises to 70 %, so choose a track that can carry an open-ended pause.
+- A reader can step back or replay the beat while the handler still listens. Note `P.gen` when the handler starts and compare it in every listener and timer: once it has changed, that start of the beat is over, so remove the listeners and do nothing (the engine ignores a stale `done()`, but not the handler's own flash or sound).
+- While the page waits, the music plays on at 70 %, so choose a track that can carry an open-ended pause.
- `export.py` cannot click: it holds the beat's last picture for its `hold` seconds (`{ ask: fireAsk(1, 'p5b'), hold: 1.5 }` in the fourth slot, 1.5 by default; the engine ignores it), then plays the next beat as if the reader had acted. Whatever the act does on the page (the shot's bang), the next beat also does on its own clock for the video; *Shooting an Elephant* silences that copy when the reader fired.
-- Check it as a reader: `?beat=N` stops on the moment; see that the prompt appears only once the narration ends, that a click acts at once and the film goes on, that stepping back and replaying mid-wait leaves no second flash or extra shot, and that the exported video holds and goes on without a gap.
+- Check it as a reader: `?beat=N` stops on the moment; the prompt appears only once the narration ends, a click acts at once and the film goes on, stepping back and replaying mid-wait leaves no second flash or extra shot, and the exported video holds and goes on without a gap.
diff --git a/.claude/skills/papermorph/references/films/films.md b/.claude/skills/papermorph/references/films/films.md
index e9aa58e..660292b 100644
--- a/.claude/skills/papermorph/references/films/films.md
+++ b/.claude/skills/papermorph/references/films/films.md
@@ -1,8 +1,8 @@
# Films: documentaries and shorts
-A film is a narrated argument told in pictures moved in step with a voice. It comes in two shapes that share almost everything: a **documentary** on the wide stage, two minutes for one idea or ten to fifteen for a book's argument ([documentary.md](documentary.md)), and a **short** on the upright 900 × 1600 stage for a phone feed, one point in one to three minutes ([shorts.md](shorts.md)). Read this file first for either, then the one for its shape.
+A film is a narrated argument told in pictures moved in step with a voice. It comes in two shapes that share almost everything: a **documentary** on the wide stage, two minutes for one idea or ten to fifteen for a book's argument ([documentary.md](documentary.md)), and a **short** on the upright 900 × 1600 stage for a phone feed, one point in one to three minutes ([shorts.md](shorts.md)). Read this file first, then the one for the shape.
-The approved references: *Madness and Civilization* (after Foucault, ten minutes, `site/madness/`) for documentaries, *Shooting an Elephant* (`site/shooting-an-elephant/`) for a documentary the reader acts in, and *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/ch01/`), for shorts. Open them and match their level; they are levels to reach, not formats to copy.
+The approved references, levels to reach rather than formats to copy: *Madness and Civilization* (after Foucault, ten minutes, `site/madness/`) for documentaries, *Shooting an Elephant* (`site/shooting-an-elephant/`) for one the reader acts in, and *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/ch01/`), for shorts.
## Contents
@@ -16,72 +16,71 @@ The approved references: *Madness and Civilization* (after Foucault, ten minutes
## Intake
-A short conversation in the spirit of [core/style.md](../core/style.md#asking): choices to click, the user's words kept verbatim, skipping what the request already settles. The film is the user's argument; the Skill's work is to make it land.
+Ask as in [core/style.md](../core/style.md#asking). The film is the user's argument; the Skill's work is to make it land.
-1. **The point and the angle.** What the film is about, and the one thing a viewer should leave with (Foucault: madness was not always locked up; each age decided what to do with it). Ask what must be in it: a scene, a quote, a person, an ending. What the user stresses is a theme to carry, not a thing to repeat: the first film's two epigraphs, shown four times, were overdone; they belong at the start and the end, with light echoes between.
-2. **The outline.** Ask for the user's outline before writing anything: the hook, the steps, the ending. If there is none, build it together; the argument is the user's, not invented. A series: its name, how many episodes, where the material divides (propose a split, each episode with its one point, as options to click), and how each episode hands on to the next.
-3. **Length, audience, platform.** Ten minutes holds one argument with five or six turns; a two-minute film holds one turn; a short holds one point. Who watches (an overseas feed, a home audience), and for a short, which platform.
-4. **The look.** One ground colour for the whole film (burgundy `#5a0e16` for Foucault, chosen from four tested with the actual pictures on them), two fonts (a condensed sans for key words, a serif for quotes and captions), and how pictures are treated ([below](#pictures)). Offer a ground test: three or four grounds with real pictures on them, side by side, before anything is built. The colours live in the book's `lib/book.css`, which the kit reads; pictures are baked to match with `prep.py --ink/--paper`.
-5. **People.** How real people appear: period pictures for the dead, cut-out figures or drawings for the living, never photographs of living people's faces.
-6. **Sources.** Which numbers and quotes need a source, and how strict to be about anonymous reports ("according to the Wall Street Journal…"). Look at the argument too: where the field disputes a claim the hook states as fact, say so and offer ways to put it (historians doubt Foucault's ships of fools; "Foucault went looking for real ones" kept the line and the truth).
-7. **Voice, music, pictures and budget** ([below](#voice-and-music)): the narrator picked by ear from short samples in the film's own words, the music, found or generated pictures, and what each costs.
+1. **The point and the angle.** What the film is about, the one thing a viewer should leave with (Foucault: madness was not always locked up; each age decided what to do with it), and what must be in it: a scene, a quote, a person, an ending. What the user stresses is a theme to carry, not a thing to repeat: the first film's two epigraphs, shown four times, were overdone; they belong at the start and the end, with light echoes between.
+2. **The outline.** Ask for the user's outline (hook, steps, ending) before writing anything; without one, build it together, since the argument is theirs. A series: its name, how many episodes, a proposed split with each episode's one point as options to click, and how each episode hands on to the next.
+3. **Length, audience, platform.** Ten minutes holds one argument with five or six turns, two minutes one turn, a short one point. Who watches (an overseas feed, a home audience) and, for a short, which platform.
+4. **The look.** One ground colour for the whole film (burgundy `#5a0e16` for Foucault, chosen from four tested with the actual pictures on them), two fonts (a condensed sans for key words, a serif for quotes and captions), and how pictures are treated ([below](#pictures)). Offer a ground test, three or four grounds with real pictures on them side by side, before anything is built. The colours live in the book's `lib/book.css`, which the kit reads; pictures are baked to match with `prep.py --ink/--paper`.
+5. **People.** Period pictures for the dead, cut-out figures or drawings for the living, never photographs of living people's faces.
+6. **Sources.** Which numbers and quotes need a source, and how strict to be about anonymous reports ("according to the Wall Street Journal…"). Where the field disputes a claim the hook states as fact, say so and offer ways to put it (historians doubt Foucault's ships of fools; "Foucault went looking for real ones" kept the line and the truth).
+7. **Voice, music, pictures and budget** ([below](#voice-and-music)).
-Then agree the models ([core/style.md](../core/style.md#models)) and write `books/<book>/style.json` from the kit's `style.json`: `tier: "documentary"` or `"shorts"`, the user's words, the angle, the look, the voice, the music and the models; a short adds the platform, the source of its argument and the series with each episode's point.
+Then agree the models ([core/style.md](../core/style.md#models)) and write `books/<book>/style.json` from the kit's: `tier: "documentary"` or `"shorts"`, the user's words, the angle, the look, the voice, the music and the models; a short adds the platform, the source of its argument and the series with each episode's point.
## The folder
-`python3 SKILL/scripts/new_book.py documentary <book>` or `… shorts <book>`, with `--maps` when the film has a map ([core/publish.md](../core/publish.md#start-a-book-folder)). It lays the kit's `lib/` over the engine's, its `book.css` (with the film's colours) replacing the default; a short gets the documentary kit's fonts too.
+`python3 SKILL/scripts/new_book.py documentary <book>` or `… shorts <book>`, with `--maps` for a map ([core/publish.md](../core/publish.md#start-a-book-folder)). The kit's `lib/` lies over the engine's, its `book.css` (the film's colours) replacing the default; a short gets the documentary kit's fonts too.
-- `books/<book>/` holds the storyboard (`storyboard.md`, or a short's `chNN-script.md`: the outline, the beats with what we see, the sources), `art/` (`found/` with the downloaded pictures and `SOURCES.tsv`, generated pictures and clips, the `prep.py` list, the cost ledger) and `music/`.
-- `site/<book>/img/` holds the treated pictures with `art.js` (`prep.py` fills it), clip sheets with `frames.js` (`frames.py`) and, when the film uses them, `lib/lines.js` (`trace.py`). Each film `chNN/` has `audio/<lang>/`, `audio/bgm/` and, for a short, `audio/sfx/`.
-- The kit's sample beat shows a picture named `first-picture` (a short's: `img/hook-picture.webp`) once there is one. Until a short's picture exists the browser draws a broken image behind its words and the console shows one 404, so `shot.py`, which stops on any page error, takes no screenshots. Voice the sample with `tts.py` and open `ch01/` to check the folder works, then replace the narration with the film's script.
+- `books/<book>/` holds the storyboard (`storyboard.md`, or a short's `chNN-script.md`: outline, beats with what we see, sources), `art/` (`found/` with the downloads and `SOURCES.tsv`, generated pictures and clips, the `prep.py` list, the cost ledger) and `music/`.
+- `site/<book>/img/` holds the treated pictures with `art.js` (from `prep.py`), clip sheets with `frames.js` (`frames.py`) and, when used, `lib/lines.js` (`trace.py`). Each `chNN/` has `audio/<lang>/`, `audio/bgm/` and, for a short, `audio/sfx/`.
+- The kit's sample beat shows a picture named `first-picture` (a short's: `img/hook-picture.webp`) once it exists. Until a short's picture exists the browser draws a broken image and the console shows one 404, so `shot.py`, which stops on any page error, takes no screenshots. Voice the sample with `tts.py` and open `ch01/` to check the folder works, then replace the narration with the film's script.
- The music line in `chapter.html` is commented out until the film has its track, and so are the map kit's lines.
-- A documentary's `index.html` is the picture-book series page, given the film's colours and fonts and a credits section listing every picture and recording from `SOURCES.tsv`; a single film is a series of one. A series of shorts gets a series page later, as any book does; until then the player's home button leads nowhere. Shorts can also live on their long film's series page: *Madness and Civilization* lists its shorts at `/madness/#shorts`, and the host's `_redirects` sends `/madness-shorts/` there.
-- The film's own recurring pieces go in the book's lib: at the end of a documentary's `film.js`, or a short's second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`).
+- A documentary's `index.html` is the picture-book series page in the film's colours and fonts, with a credits section listing every picture and recording from `SOURCES.tsv`; a single film is a series of one. A series of shorts gets a series page later, as any book does; until then the player's home button leads nowhere. Shorts can also live on their long film's page: *Madness and Civilization* lists its shorts at `/madness/#shorts`, and the host's `_redirects` sends `/madness-shorts/` there.
+- The film's own recurring pieces go in the book's lib: at the end of a documentary's `film.js`, or in a short's second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`).
## Pictures
-- **Find, then record.** `commons.py` searches Wikimedia Commons and downloads only public-domain and CC0 files, logging each in `SOURCES.tsv` beside the downloads: name, Commons title, licence, author, source URL, any use restriction such as a trademark (which it warns about), the credit line, the licence URL and the work's date. The book page's credits come from it. One subagent with it found all twenty storyboard pictures for Foucault in thirteen minutes. Other good sources: the Library of Congress, Old Book Illustrations, the Internet Archive; record those by hand the same way.
+- **Find, then record.** `commons.py` searches Wikimedia Commons, downloads only public-domain and CC0 files, and logs each in `SOURCES.tsv`: name, Commons title, licence, author, source URL, any use restriction such as a trademark (it warns), credit line, licence URL and the work's date. The book's credits come from it; one subagent with it found all twenty of Foucault's storyboard pictures in thirteen minutes. The Library of Congress, Old Book Illustrations and the Internet Archive are good too; record those by hand the same way.
- **Treatments**, made by `prep.py`, which also writes `img/art.js` with each picture's size:
- *print*: the picture keeps its paper, with a border and a soft shadow, like a photograph laid on the ground. Paintings, photographs, title pages.
- - *line*: an engraving's dark lines turn into the ground's ink colour and the paper drops out, so the figure stands on the ground itself. Woodcuts and engravings with clean lines.
+ - *line*: an engraving's dark lines take the ground's ink colour and the paper drops out, so the figure stands on the ground itself. Woodcuts and engravings with clean lines.
- *full*: sized for a full-bleed shot on the upright stage.
- - Films made at the same time each keep their own sizes file (`prep.py … --art ch03-art.js`, loaded after `img/art.js`), so no two of them edit the same line.
-- **Generated pictures.** An image model fills what no archive has; note each picture's prompt and cost in the ledger, quote the batch before paying, and show the user the pictures as they come. Low quality is usually enough (94 pictures cost $0.84 for a three-episode series); a picture made from a reference picture, to keep a figure or a style, costs about four times as much, since the reference counts as input ($0.016 against $0.004).
-- **One figure per role**, so that a figure coming back means something (a callback), not that the cast ran out.
-- **Line drawings that draw themselves.** `trace.py` turns a line drawing into ordered strokes; `traced()` draws it on over a few seconds. It is striking once or twice; on every picture it becomes a tic.
-- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (about $0.42; Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. A job takes minutes; `video.py --resume JOBID` picks up one that was interrupted. It worked best when rare.
+ - Films made at the same time each keep their own sizes file (`prep.py … --art ch03-art.js`, loaded after `img/art.js`), so no two edit the same line.
+- **Generated pictures** fill what no archive has: note each prompt and cost in the ledger, quote the batch before paying, and show the user the pictures as they come. Low quality is usually enough (94 pictures cost $0.84 for a three-episode series); one made from a reference picture, to keep a figure or a style, costs about four times as much ($0.016 against $0.004), since the reference counts as input.
+- **One figure per role**, so a figure coming back means something (a callback), not that the cast ran out.
+- **Line drawings that draw themselves.** `trace.py` turns a line drawing into ordered strokes; `traced()` draws it on over a few seconds. Striking once or twice; on every picture, a tic.
+- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (about $0.42; Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. A job takes minutes; `video.py --resume JOBID` picks up an interrupted one. It worked best when rare.
## Maps
-A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe, a virus leaving one city). The map kit `assets/templates/maps/` serves both shapes on either stage: `lib/map.js` draws a paper map (`paperMap()`) and `lib/globe.js` a night globe (`globeShot()`, three.js), both from one view `{ lon, lat, H }`, so a shot hands over from the globe to the map without a jump.
+A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe, a virus leaving one city). The map kit `assets/templates/maps/` serves both stages: `lib/map.js` draws a paper map (`paperMap()`) and `lib/globe.js` a night globe (`globeShot()`, three.js), both from one view `{ lon, lat, H }`, so a shot hands over from globe to map without a jump.
- Its data come from `geo.py`: `img/geo-lite.js` with the world's countries, capitals and big cities, plus only what the film shows, since each adds weight: `--regions CHN,ITA:region` (China's provinces, Italy's regions), `--detail Wuhan=114.27,30.58,1.5` (rivers, lakes and built-up areas around a city), `--cities`, and `--globe site/<book>/lib` for the globe (three.js and NASA's Black Marble as `img/night.webp`): `uv run --with pillow python3 SKILL/scripts/geo.py site/<book>/img --globe site/<book>/lib` (without `--globe`, plain `python3`). Credit "Natural Earth, public domain" and "Black Marble 2016, NASA Earth Observatory, public domain" in the film's sources.
- The API is the comment at the top of `map.js`; `sample.html` plays every piece (`?wide` on the landscape stage).
-- Colour says what kind of thing is on the map: `lit` and `region` fill in the subject's colour (`--map-hot`, the book's red), `hatch` and `areas` draw in ink what is not the subject (an order, a lockdown), so the red keeps one meaning. The colours come from `lib/book.css` (`--map-land`, `--map-sea`, `--map-ink`, …) when it sets them.
+- Colour says what kind of thing is on the map: `lit` and `region` fill in the subject's colour (`--map-hot`, the book's red), `hatch` and `areas` draw in ink what is not the subject (an order, a lockdown), so red keeps one meaning. The colours come from `lib/book.css` (`--map-land`, `--map-sea`, `--map-ink`, …) when it sets them.
- Move a map through its `view(t)` (`mapKeys()` for a camera through keys), not by scaling a group above it: Gecko re-rasters a canvas under a scaled parent. A map or globe draws only inside its `on` window (in a shorts `shot()`, the shot's), since Firefox pays for every drawn canvas, even a covered one.
-- Without the kit, a coastline from Natural Earth as one SVG path in the film's box, with a route drawn on by `along()`, is enough for one still map (Foucault's Europe).
+- Without the kit, a Natural Earth coastline as one SVG path in the film's box, with a route drawn on by `along()`, is enough for one still map (Foucault's Europe).
## Voice and music
-The mechanics (the narration file, `tts.py` and `eleven.py`, levels, `music.py`, recording licences) are in [core/sound.md](../core/sound.md). For films:
+The mechanics are in [core/sound.md](../core/sound.md). For films:
-- **The narrator carries the film**, so the user picks it by ear. Offer both kinds: free voices (Edge, or Kokoro, local) and ElevenLabs v4 through OpenRouter (`eleven.py`, paid). ElevenLabs was the accepted voice on the films so far. Edge and Kokoro cost nothing; ElevenLabs about $0.07 a minute (`eleven.py --dry` prints the estimate; quote it). Characters can have their own voices for a line or a laugh (the Fool's giggle, a king's edict).
-- **Every clip at one level**, −14 LUFS ([core/sound.md](../core/sound.md#levels)); a series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) sets `"tempo"` in each narration file.
-- **Music**: classical recordings suit found pictures; generated music (Lyria) is made outside the Skill for now. How a documentary and a short each use it differs ([documentary.md](documentary.md#the-order-of-work), [shorts.md](shorts.md#the-order-of-work)). Leave `?bgm=` on the page so the user can set the level by ear ([core/sound.md](../core/sound.md#music)).
+- **The narrator carries the film**, so offer both kinds by ear: free voices (Edge, or Kokoro, local) and ElevenLabs v4 (`eleven.py`, paid, about $0.07 a minute), the accepted voice on the films so far. Characters can have their own voices for a line or a laugh (the Fool's giggle, a king's edict).
+- **Every clip at −14 LUFS** ([core/sound.md](../core/sound.md#levels)); a series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) sets `"tempo"` in each narration file.
+- **Music**: classical recordings suit found pictures. A documentary and a short use it differently ([documentary.md](documentary.md#the-order-of-work), [shorts.md](shorts.md#the-order-of-work)).
## Team
-The general shape is in [core/team.md](../core/team.md).
+The general shape is in [core/team.md](../core/team.md); the director passes are as in [core/review.md](../core/review.md#review-rounds).
-- **Documentary**: split by part of the film (a turn of the argument, often one music track). The **strong** coordinator researches and writes the script and storyboard with the user, then builds what every part shares: the voice and `timings.js`, the music, and the film's own recurring pieces. A **middle** worker finds and treats the pictures from the storyboard (`commons.py`, `prep.py`, and `trace.py` or `frames.py` where the storyboard asks), recording each source. One **middle** worker per part then builds its beats, given the storyboard rows, the marks to land on, the kit's API (to read, not to edit), the first and last frame of the parts beside it, and how to look at its own frames; it replies with contact sheets of its beats and what they showed.
-- **Short**: an episode is short enough that the **strong** coordinator writes the script and the shot-by-shot storyboard with the user and builds what the beats share: the voice and `timings.js` at one level, the music, and the series' own pieces. A **middle** worker makes or finds the pictures from the storyboard and records each prompt or source and its cost. One **middle** worker builds the beats (two, splitting the episode at a turn, when it is long), given the script, the marks, the kit's API to read and not edit, the safe area, and how to look at its frames: `strip.py` sheets of every beat and the first frame upright with `shot.py --clean`.
-- The director passes are **strong** and report-only; the coordinator merges their findings and sends parts back to their workers.
+- **Documentary**: split by part of the film (a turn of the argument, often one music track). The **strong** coordinator researches and writes the script and storyboard with the user, then builds what every part shares: the voice and `timings.js`, the music, the film's recurring pieces. A **middle** worker finds and treats the pictures from the storyboard (`commons.py`, `prep.py`, and `trace.py` or `frames.py` where asked), recording each source. One **middle** worker per part builds its beats, given the storyboard rows, the marks to land on, the kit's API (to read, not edit), the first and last frame of the neighbouring parts, and how to look at its own frames; it replies with contact sheets of its beats and what they showed.
+- **Short**: the **strong** coordinator writes the script and shot-by-shot storyboard with the user and builds what the beats share: the voice and `timings.js` at one level, the music, the series' own pieces. A **middle** worker makes or finds the pictures and records each prompt or source and its cost. One **middle** worker builds the beats (two, split at a turn, when the episode is long), given the script, the marks, the kit's API to read and not edit, the safe area, and how to look at its frames: `strip.py` sheets of every beat and the first frame upright with `shot.py --clean`.
## Review rounds
The loop is in [core/review.md](../core/review.md#review-rounds). For a film:
-- **Round 1, on the sheets**: a fresh director on a strong model, given contact sheets of every beat and the reference film (or an approved episode), with no knowledge of how the beats were built. On Foucault it found ten must-fix defects, about half of them the wrong figure on screen while another was named.
-- **Round 2, on the exported MP4**, by another fresh director who watches it as a viewer would: frames every half second on contact sheets, the first frame alone at full size, the audio transcribed with word times and its loudness measured, each against the script and its sources and against the approved films' exports. This round is the lever: on *The Pandemic*'s six shorts every first cut had passed its worker's own checks and still had one to three must-fix faults, most of them the picture saying something other than the voice ("even the vaccinated" drawn as protection).
-- **Check a director's measurement** before it goes back as work: one reported loudness no other measurement matched, and a cut "a second late" was only Whisper starting a word at the pause before it (check a lag against the clip's own silences, not the transcript alone). After the fixes, a quick look of your own at the new MP4's frames; then the user watches the whole film.
+- **Round 1, on the sheets**, against the reference film or an approved episode. On Foucault it found ten must-fix defects, about half the wrong figure on screen while another was named.
+- **Round 2, on the exported MP4**, by another fresh director who watches as a viewer: frames every half second on contact sheets, the first frame alone at full size, the audio transcribed with word times and its loudness measured, each against the script, its sources and the approved films' exports. This round is the lever: each of *The Pandemic*'s six shorts had passed its worker's checks and still had one to three must-fix faults, most the picture saying something other than the voice ("even the vaccinated" drawn as protection).
+- **Check a director's measurement** before it goes back as work: one reported loudness no other measurement matched, and a cut "a second late" was Whisper starting a word at the pause before it; check a lag against the clip's own silences, not the transcript alone.
diff --git a/.claude/skills/papermorph/references/films/shorts.md b/.claude/skills/papermorph/references/films/shorts.md
index f14b41f..2462043 100644
--- a/.claude/skills/papermorph/references/films/shorts.md
+++ b/.claude/skills/papermorph/references/films/shorts.md
@@ -1,6 +1,6 @@
# Shorts: one point, under three minutes, upright, for a phone feed
-A short is a narrated film on the upright 900 × 1600 stage (`<html data-stage="portrait">`, [core/engine.md](../core/engine.md#stage-and-state)), made for YouTube Shorts, TikTok, Reels or X. It makes one point in one to three minutes, with a new picture every one to three seconds: full-bleed photographs or generated pictures, big words, cut-out figures, a number counting up, a chart, a map. What differs from a documentary is the pace, the grammar of the picture and where it ends up; intake, the folder, pictures, maps, voice, team and review are shared in [films.md](films.md). An upright chapter is a film without questions. The worked example is *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/ch01/`), the ten-minute documentary recut as a series: watch it before making one, as a level to match, not a format to copy.
+A short is a narrated film on the upright 900 × 1600 stage (`<html data-stage="portrait">`, [core/engine.md](../core/engine.md#stage-and-state)) for YouTube Shorts, TikTok, Reels or X: one point in one to three minutes, a new picture every one to three seconds (full-bleed photographs or generated pictures, big words, cut-out figures, a number counting up, a chart, a map), and no questions. It differs from a documentary in pace, picture grammar and where it ends up; the rest is in [films.md](films.md). Watch the worked example, *The Ship* (`site/madness-shorts/ch01/`, the ten-minute documentary recut as a series), before making one.
The kit is `assets/templates/shorts/` (`chapter.html`, `narration.en.json`, `style.json`; `lib/shorts.js`, `book.css`, `icons.js`; fonts from the documentary kit).
@@ -14,30 +14,30 @@ The kit is `assets/templates/shorts/` (`chapter.html`, `narration.en.json`, `sty
## What the viewer is doing
-They are scrolling. They decide in the first second whether to stay, and on the platforms' numbers that second is most of the outcome: one of our episodes opened on a generated city picture already moving, under its first line, and 57.8 % stayed past the first chance to swipe; another opened on a still card of text and 12.8 % stayed. A text card reads as a text post, and a line in a script the viewer cannot read is a wall. So the first frame is a picture in motion with the hook spoken over it, and the hook is the point itself, not a preamble ("there's a line that went viral…" spends the second that matters).
+They are scrolling, and decide in the first second whether to stay; on the platforms' numbers that second is most of the outcome. One episode opened on a generated city picture already moving, under its first line, and 57.8 % stayed past the first chance to swipe; another opened on a still card of text and 12.8 % stayed. A text card reads as a text post, and a line in a script the viewer cannot read is a wall. So the first frame is a picture in motion with the hook spoken over it, and the hook is the point itself, not a preamble ("there's a line that went viral…" spends the second that matters).
-After that they stay as long as each moment gives them something new and the argument keeps moving. Background facts are where a short gets slow: compress them hardest and keep the steps of the argument.
+After that they stay while each moment gives them something new and the argument keeps moving. Background facts are where a short gets slow: compress them hardest and keep the steps of the argument.
## Questions for the user
-The questions are the films' intake ([films.md](films.md#intake)): the point and who watches on which platform, the user's outline (a series: its episodes and each one's point), people, sources and disputed claims, voice and music, pictures and budget. Writing the script with the user is strong-model work, building beats middle, checks small.
+The films' intake ([films.md](films.md#intake)): the point, who watches on which platform, the user's outline (a series: its episodes and each one's point), people, sources and disputed claims, voice and music, pictures and budget.
## From a long film
-When the user wants a film that already exists recut as shorts (*Madness and Civilization* became four), the argument is there: its script is the outline, and its checked quotes, found pictures, voice and music carry over. The first questions change: how many episodes, where the film's turns divide them, and what each episode's one point is. Propose the split and episode 1's outline together, then go on as below. Read the film's `style.json`, its narration and its `SOURCES.tsv` before asking anything they already answer. Where a short's habits and the film's differ, ask the user: the documentary's one Fool through the centuries is a recurring figure, which the short's one figure per role would break.
+When the user wants an existing film recut as shorts (*Madness and Civilization* became four), its script is the outline, and its checked quotes, found pictures, voice and music carry over. Read its `style.json`, narration and `SOURCES.tsv` before asking anything they answer. The first questions become how many episodes, where the film's turns divide them, and each episode's one point; propose the split and episode 1's outline together, then go on as below. Where a short's habits and the film's differ, ask the user: the documentary's one Fool through the centuries is a recurring figure, which the short's one figure per role would break.
## The order of work
-1. **The script, beat by beat, with the user.** Keep it in `books/<book>/chNN-script.md`: the agreed outline, a table of beats (the narration, one line of what we see, and its rough length), and each number's and quote's source under it. Show it to the user a few beats at a time and rewrite as they answer.
- - Length: words ÷ the voice's pace (about 2.6 words a second for an ElevenLabs narrator), plus about 1.4 s a beat for the engine's hold after the words (0.6 s) and the camera's tail (0.8 s in the worked example); a twelve-beat script ran 17 s longer than its words. A background beat over about eight seconds is where the short will feel slow; shorten it before the voice is paid for. Once voiced, the length hides in the voice's sentence pauses: `eleven.py --max-pause 0.3` took one episode from 112 s to 107 s.
- - The beats' narration, with `[[mark]]` before each word a picture lands on, goes into `content/<book>/chNN/narration.en.json`; keep the two in step.
-2. **The storyboard, then the cast and the pictures.** One line per shot, a shot every one to three seconds, under each beat of the script: that is the list of pictures to make or find, and a beat-by-beat plan is too coarse for it (one director pass asked for three pictures the plan had missed). Then make or find them ([films.md](films.md#pictures)).
+1. **The script, beat by beat, with the user**, in `books/<book>/chNN-script.md`: the agreed outline, a table of beats (narration, one line of what we see, rough length), and each number's and quote's source under it. Show it a few beats at a time and rewrite as they answer.
+ - Length: words ÷ the voice's pace (about 2.6 words a second for an ElevenLabs narrator), plus about 1.4 s a beat for the engine's hold after the words (0.6 s) and the camera's tail (0.8 s in the worked example); a twelve-beat script ran 17 s longer than its words. A background beat over about eight seconds will feel slow; shorten it before the voice is paid for. Once voiced, length hides in the sentence pauses: `eleven.py --max-pause 0.3` took one episode from 112 s to 107 s.
+ - The narration, with its `[[mark]]`s, goes into `content/<book>/chNN/narration.en.json`; keep the two in step.
+2. **The storyboard, then the cast and the pictures.** One line per shot, a shot every one to three seconds, under each beat of the script: that is the list of pictures to make or find; a beat-by-beat plan is too coarse (one director pass asked for three pictures it had missed). Then make or find them ([films.md](films.md#pictures)).
3. **The folder** ([films.md](films.md#the-folder)). The series' own pieces (its cast's sizes in `MEME`, a series card) go in a second file loaded after `shorts.js`. Every episode but a series' last sets `CHAPTER.next`: the end card names the next episode, and the player offers it only when `next` is set.
-4. **Voice**: `eleven.py` or `tts.py` at −14 LUFS ([core/sound.md](../core/sound.md#voices)). Wordless beats (a series card, an end card) take `{ dur: 2 }` and no line, and the music stays ducked under them. Check the marks on spoken numbers: a number the matcher missed lands late (seven marks in one episode, up to 0.75 s).
-5. **Music.** One track for the whole episode under every beat, `music(file, undefined, gain, .05)`. It changes by easing, at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses, which `music.py cut --rests --even` takes out ([core/sound.md](../core/sound.md#music)). A looping track is fine for a first cut. Start `?bgm=` around 0.4, the level the user chose for episode 1.
-6. **The beats**, built from the kit and timed to the marks; sound effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps. A beat ends at its last tween plus the hold, so the kit's habit of pushing a picture past the voice (`photo(s, …, 0, D + .6)`) lengthens the beat by as much: two beats with the same voice can differ by what their tweens overrun. `?lengths` on the page prints each beat's voice against its length on screen. Two mirrored beats (two answers treated alike) get the same seconds with `{ minDur }` set to the longer one's length.
-7. **Watch it yourself, then the director rounds** ([core/review.md](../core/review.md), [films.md](films.md#review-rounds)). Look at the first frame on its own, upright as the feed shows it: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage; look at it with the platform's title, caption and buttons in mind. Measure what a script can: a shot held still too long (`still.py chNN --min 2`), a number that lands after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode; `strip.py` and `shot.py` take `--query tags` too, to see the tags the export will show). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and on a contact sheet alike: on a shot that long, push at least about 15 %, or cut.
-8. **The user watches**, you fix, and `export.py` writes a 1080 × 1920 MP4 and an `.srt` ([core/publish.md](../core/publish.md#video-export)). On an upright film it shows the source and AI-illustration tags, since the video leaves the page that credits them (`--no-tags` leaves them out). The user uploads it and ticks the platform's AI or synthetic-content box. A video over 25 MiB does not fit Cloudflare Pages; the web page itself is the light version. A series card's still is upright too: `shot.py … --webp 600` writes a 600 × 1067 WebP of the stage.
+4. **Voice**: `eleven.py` or `tts.py` at −14 LUFS; wordless beats (a series card, an end card) take `{ dur: 2 }`; check the marks on spoken numbers, which come late when missed (seven in one episode) ([core/sound.md](../core/sound.md#voices)).
+5. **Music.** One track under the whole episode, `music(file, undefined, gain, .05)`, changing by easing at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses, which `music.py cut --rests --even` takes out ([core/sound.md](../core/sound.md#music)). A looping track is fine for a first cut. Start `?bgm=` around 0.4.
+6. **The beats**, built from the kit and timed to the marks; effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps. A beat ends at its last tween plus the hold, so the kit's habit of pushing a picture past the voice (`photo(s, …, 0, D + .6)`) lengthens the beat by as much, and two beats with the same voice can differ by what their tweens overrun; `?lengths` prints each beat's voice against its length on screen. Two mirrored beats (two answers treated alike) get the same seconds with `{ minDur }` set to the longer one's length.
+7. **Watch it yourself, then the director rounds** ([core/review.md](../core/review.md), [films.md](films.md#review-rounds)). Look at the first frame alone, upright, with the platform's title, caption and buttons in mind: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage. Measure what a script can: a shot held still too long (`still.py chNN --min 2`), a number landing after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode; `strip.py` and `shot.py` take `--query tags` too, to show the tags the export will). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and a contact sheet alike: on a shot that long, push at least about 15 %, or cut.
+8. **The user watches**, you fix, and `export.py` writes the upright MP4 and an `.srt` ([core/publish.md](../core/publish.md#video-export)). On an upright film it shows the source and AI-illustration tags, since the video leaves the page that credits them (`--no-tags` leaves them out). The user uploads it and ticks the platform's AI or synthetic-content box. A video over 25 MiB does not fit Cloudflare Pages; the web page itself is the light version. A series card's still is upright too: `shot.py … --webp 600` writes a 600 × 1067 WebP of the stage.
## The picture
@@ -46,15 +46,15 @@ When the user wants a film that already exists recut as shorts (*Madness and Civ
- `shot()` a full-frame shot with a hard cut, `whip` (a sideways slide with motion blur) or `swipe` (the next clip rising as in a feed); `photo()` a full-bleed picture with a slow push, centred; `found()` the same for a found photograph, tagged with its source; `wide()` a camera across a landscape picture whose subject is off-centre, never showing an edge; `plate()` a picture placed whole on the ground (sizes from `img/art.js`). A picture whose point is its text (a sign, a headline) goes in whole with `plate()`: an upright crop of a shop sign left "Y. WE / RARY CLOS";
- `word()` big condensed capitals (a word wider than its `maxW`, 660, is set smaller, so it and its stroke stay in the safe area), `label()` and `band()` caps on solid blocks, `marker()` a highlighter sweep, `vlog()` white outlined overlay text, `srcTag()` a source or "AI illustration";
- `meme()` a cut-out figure rising in, `swarm()` one crossing then a crowd of them, `stamp()` a rubber stamp slammed on, `counter()` a number counting up, `priceTag()`, `phoneCard()`, `ico()` and `icons()` (Phosphor, MIT), `bar()`, `clipImg()`;
-- its palette (`DARK`, `RED`, `LIGHT`, `MUTED`, …, set in `lib/book.css` as `--dark`, `--red`, …), fonts (`SANS`, `SERIF`) and small tools (`inkW()` text width, `ramp01()`, `seeded()`) are named apart from the documentary kit's `film.js`, so a short can load `film.js` too when it wants a documentary helper (`pic()`, `say()`, `traced()`): load it before `shorts.js`;
+- its palette (`DARK`, `RED`, `LIGHT`, `MUTED`, …, set in `lib/book.css` as `--dark`, `--red`, …), fonts (`SANS`, `SERIF`) and small tools (`inkW()` text width, `ramp01()`, `seeded()`) are named apart from the documentary kit's `film.js`, so a short can load `film.js` before `shorts.js` when it wants a documentary helper (`pic()`, `say()`, `traced()`);
- `shortsBeat` turns a beat tuple into the engine's beat with every cue `LEAD` (0.22 s) early: a cut that lands on the word itself reads as late.
What made the first shorts work:
- **One idea per shot, one to three seconds a shot**, full bleed; words inside x 50–810, y 130–1290, since the platform draws its title, caption and buttons over the rest.
- **Say it literally.** When the narration describes a mechanism, draw each link as the voice names it. The "everyone is cheap" loop read as a vague circle until it became three people, each handing the next their product and its price, A to B, B to C, C back to A.
-- **Numbers move.** A count, a bar growing, a price tag swapped: a number on screen arrives the moment it is said. A big denominator can be drawn literally: "2 in 100,000" as a field of 100,000 dots in one SVG `<pattern>` fill with the two real circles over it played at 17 ms a frame in both browsers.
-- **A series says where it is.** A few seconds after the hook: the series card with this episode lit ("1 · The Ship"), then the argument.
+- **Numbers move.** A count, a bar growing, a price tag swapped: a number arrives the moment it is said. A big denominator can be drawn literally: "2 in 100,000" as a field of 100,000 dots in one SVG `<pattern>` fill with the two real circles over it, played at 17 ms a frame in both browsers.
+- **A series says where it is.** A few seconds after the hook, the series card with this episode lit ("1 · The Ship"), then the argument.
- **The ending points on.** The last beat answers the hook and names the next episode.
Scripts to come: cuts on the music's own beat, and generating music with Lyria.
diff --git a/.claude/skills/papermorph/references/lessons/assets.md b/.claude/skills/papermorph/references/lessons/assets.md
index b947953..8846443 100644
--- a/.claude/skills/papermorph/references/lessons/assets.md
+++ b/.claude/skills/papermorph/references/lessons/assets.md
@@ -1,20 +1,20 @@
# Assets: shared components and chapter needs
-What a book's pictures are made of comes from its content and the look the user chose, never from a default set. Two levels keep that consistent without making every book look alike.
+A book's pictures are made of what its content and the user's chosen look call for, not a default set. Two levels keep that consistent without making every book look alike.
## Book level: the element library
-During intake ([intake.md](intake.md)) the shared components are proposed to the user with how each is made, and their look is agreed. Build each once into the book's library, `site/<book>/lib/<name>.js` (loaded after `engine.js`), drawn around its own origin and placed with `put`, with a short API (`f.set(x, y, len, angle, label)`, `actor.stride('walk', dist)`, `actor.hand()`). List it under `components` in `style.json`: name, file, one line on what it does. A fix to a shared element lifts every chapter at once, so after changing one, compare frames of approved chapters before and after. Keep chapter-specific drawing in the chapter; promote it when a second chapter needs it.
+The shared components and how each is made are agreed at intake ([intake.md](intake.md)). Build each once into `site/<book>/lib/<name>.js` (loaded after `engine.js`), drawn around its own origin and placed with `put`, with a short API (`f.set(x, y, len, angle, label)`, `actor.stride('walk', dist)`, `actor.hand()`), and list it under `components` in `style.json`: name, file, one line on what it does. A fix to a shared element lifts every chapter at once, so after changing one, compare frames of approved chapters before and after. Chapter-specific drawing stays in the chapter until a second chapter needs it.
## Chapter level: needs noticed while storyboarding
-Laying out a chapter's moments shows what the library lacks: a new prop, a place, a real photograph or map. Draw it in the chapter when code can; otherwise add it to `books/<book>/images/image-requests.md` (what, where it appears, size and view, style, licence needed) for the user or a sourcing pass. Anything that turns out to recur moves into the library.
+Laying out a chapter shows what the library lacks: a new prop, a place, a real photograph or map. Draw it in the chapter when code can; otherwise add it to `books/<book>/images/image-requests.md` (what, where it appears, size and view, style, licence needed) for the user or a sourcing pass. Anything that recurs moves into the library.
## Mechanics, whatever the style
-- Incoming files go to `books/<book>/images/inbox/` with `SOURCES.md` (origin URL, author, licence). Prefer public-domain or CC0/CC-BY; record attribution for anything that requires it.
-- A processing script in `books/<book>/images/` turns them into `site/<book>/img/` (crop, recolour, scale, compress), so every output can be rebuilt; `SKILL/scripts/sprites.py` has the common steps: integer nearest-neighbour scaling, colour mapping, pixel art from text rows, and assembling frames into one sheet with a JSON layout. Credits for the published images go in `site/<book>/img/CREDITS.md`.
+- Incoming files go to `books/<book>/images/inbox/` with `SOURCES.md` (origin URL, author, licence). Prefer public domain or CC0/CC-BY; record attribution where required.
+- A processing script in `books/<book>/images/` turns them into `site/<book>/img/` (crop, recolour, scale, compress), so every output can be rebuilt; `SKILL/scripts/sprites.py` has the common steps: integer nearest-neighbour scaling, colour mapping, pixel art from text rows, and assembling frames into one sheet with a JSON layout. Credits for published images go in `site/<book>/img/CREDITS.md`.
- Sprite animation: put a character's frames in one sheet and switch frames by changing a nested `<svg>`'s viewBox; changing an `<image href>` per frame can refetch. Pixel art is drawn at an integer scale with `image-rendering: pixelated` and pre-scaled files.
-- One large detailed object (a planet, a map) is cheaper as a single image than as many shapes; see the Firefox notes in [engine.md](../core/engine.md#performance-firefox).
+- One large detailed object (a planet, a map) is cheaper as a single image than as many shapes ([engine.md](../core/engine.md#performance-firefox)).
-Pictures from an image model (sets and props for picture books, and any other book that agrees a budget) go through `paint.py` and `painted.py`; see [painting.md](../picture-books/painting.md).
+Pictures from an image model (when a book agrees a budget) go through `paint.py` and `painted.py` ([painting.md](../picture-books/painting.md)).
diff --git a/.claude/skills/papermorph/references/lessons/authoring.md b/.claude/skills/papermorph/references/lessons/authoring.md
index d04fda2..0d7cc39 100644
--- a/.claude/skills/papermorph/references/lessons/authoring.md
+++ b/.claude/skills/papermorph/references/lessons/authoring.md
@@ -2,7 +2,7 @@
## Shape
-Chapters have run 5–18 minutes with 5–40 second beats; a long chapter can hold several parts (each a short title beat, lessons, a quick check and a wrap). Let the content determine length and the number of checks/practice sets.
+Chapters have run 5–18 minutes with 5–40 second beats; a long chapter can hold several parts (each a short title beat, lessons, a quick check and a wrap). Let the content set the length and the number of checks and practice sets.
| Beat | Purpose |
| --- | --- |
@@ -17,7 +17,7 @@ Beat ids are shared by the page (`BEATS`) and the narration file; a beat with `a
## Beats
-Before writing code, list the beats. For each lesson beat decide what the eye should watch and what changes; why that change is true (the animation is the argument); which words trigger which actions (these become `[[marks]]`); what text appears, beside the thing it names; and what carries over from the previous beat. Then lay out the key moments as pictures (storyboard): [diagrams.md](diagrams.md) and [scenes.md](scenes.md).
+List the beats before writing code. For each lesson beat decide what the eye watches and what changes; why that change is true (the animation is the argument); which words trigger which actions (the `[[marks]]`); what text appears, beside the thing it names; and what carries over from the previous beat. Then storyboard the key moments ([diagrams.md](diagrams.md), [scenes.md](scenes.md)).
- **Open on the subject.** When a beat clears the picture, the new topic appears right away; labels and steps follow the words. Short pauses for thought are fine.
- **One new thing at a time**, and **the same colour means the same thing** across the chapter and, where it fits, the book.
@@ -27,11 +27,11 @@ Before writing code, list the beats. For each lesson beat decide what the eye sh
The file format, `[[marks]]`, writing for the ear and the voice scripts are in [core/sound.md](../core/sound.md#the-narration-file). A lesson adds:
-- Match the audience: plain, warm, never childish. Explain why, not only how.
+- Explain why, not only how.
- Question beats get one short line ("Quick check. Find the mean."); the card holds the question ([questions.md](questions.md)).
## Content rules
-- Follow the agreed chapter scope and order. Verify facts, calculations and answers actually used in the finished lesson; correct or replace source errors and note them in `books/<book>/chapters/chNN.md` for the user.
+- Follow the agreed chapter scope and order. Verify the facts, calculations and answers the finished lesson uses; correct or replace source errors and note them in `books/<book>/chapters/chNN.md` for the user.
- Check worked examples as the subject, not only as arithmetic (a push on someone standing on the ground is not the net force).
-- Use the notation and rounding in `style.json` (`look.notation`). Record new shared decisions there. Group thousands with a no-break space (U+00A0) or the book's comma: a thin space all but vanishes in bold system fonts (150 000 000 read as 150000000).
+- Use the notation and rounding in `look.notation` of `style.json`, and record new shared decisions there. Group thousands with a no-break space (U+00A0) or the book's comma: a thin space all but vanishes in bold system fonts (150 000 000 read as 150000000).
diff --git a/.claude/skills/papermorph/references/lessons/checks.md b/.claude/skills/papermorph/references/lessons/checks.md
index d98cd3c..a647dab 100644
--- a/.claude/skills/papermorph/references/lessons/checks.md
+++ b/.claude/skills/papermorph/references/lessons/checks.md
@@ -1,6 +1,6 @@
# Lesson checks
-The shared pass (lint, `check.py`, strips, `still.py`, `shot.py`, `perf.py`, review rounds) is in [core/review.md](../core/review.md). A lesson adds the checks below; watch every beat to its end, question cards included.
+The shared pass (lint, `check.py`, strips, `still.py`, `shot.py`, `perf.py`, review rounds) is in [core/review.md](../core/review.md); a lesson watches its question cards to the end too, and adds the checks below.
## Frames and openings
@@ -9,13 +9,13 @@ uv run --with playwright SKILL/scripts/check_blank.py site/<book> chNN --url htt
uv run --with playwright SKILL/scripts/overlap.py chNN --url http://localhost:8765/<book>/
```
-`check_blank.py` reports openings empty for more than a second after speech starts. `overlap.py` samples every beat and lists where an arrow runs through text or two texts collide, with times, so you can look at exactly those frames. Both skip a picture book, whose set is always there and whose words are captions.
+`check_blank.py` reports openings empty for more than a second after speech starts. `overlap.py` samples every beat and lists, with times, where an arrow runs through text or two texts collide, so you can look at exactly those frames. Both skip a picture book, whose set is always there and whose words are captions.
-On the `shot.py` sheets, a lesson also looks for geometry contradicting its values, shapes inside circles or curves crossing the outline; check thin geometry on the full-size `chNN_bII_T.png`, not only the sheet.
+On the `shot.py` sheets a lesson also looks for geometry contradicting its values, shapes inside circles and curves crossing the outline.
## Interaction tests
-Adapt `assets/templates/e2e.py` into `tools/<book>/e2e_chNN.py`: it checks playback, that every beat replays the same frame when seeked, that quiz cards stay readable and on stage at two viewport sizes, and walks the answers, practice and finish card. `ANSWERS` maps each question beat to one step per question: a digit picks a choice, `=a,b` fills the boxes, `#2;1+3` answers a grid (rows split by `;`, each row's columns counted from 1, `+` for several, `#2;;1` a row left empty). Run it in Chromium and with `BROWSER=firefox`. Run existing tests of approved chapters after changing the book's engine or library.
+Adapt `assets/templates/e2e.py` into `tools/<book>/e2e_chNN.py`: it checks playback, that every beat replays the same frame when seeked, that quiz cards stay readable and on stage at two viewport sizes, and walks the answers, practice and finish card. `ANSWERS` maps each question beat to one step per question: a digit picks a choice, `=a,b` fills the boxes, `#2;1+3` answers a grid (rows split by `;`, each row's columns counted from 1, `+` for several, `#2;;1` a row left empty). Run it in Chromium and with `BROWSER=firefox`. After changing the book's engine or library, rerun the approved chapters' tests.
After scoring changes, check a wrong first try stays recorded after revisiting and a restart clears it; after progress changes, check book isolation and missing or malformed stored data. Fix engine bugs at the engine source and copy them to the books with `scripts/engine.py`; book-specific settings stay in each book's `lib/book.css`.
diff --git a/.claude/skills/papermorph/references/lessons/courses.md b/.claude/skills/papermorph/references/lessons/courses.md
index 7d6e3ff..3494ec6 100644
--- a/.claude/skills/papermorph/references/lessons/courses.md
+++ b/.claude/skills/papermorph/references/lessons/courses.md
@@ -1,22 +1,22 @@
# Course options
-Three options for books used in a course, usually at a college: verified citation links, a reviewed bank of choice questions, and a SCORM package for an LMS. None is on by default; offer one at intake only when the book calls for it (it cites other works, its questions must be reviewed before release, or it goes into an LMS), and record the choice in `style.json`.
+Three options for course books, usually at a college: verified citation links, a reviewed bank of choice questions, and a SCORM package for an LMS. None is on by default; offer one at intake only when the book calls for it (it cites other works, its questions must be reviewed before release, or it goes into an LMS), and record the choice in `style.json`.
## Citations
-Each work named on screen (an author–year, a quoted study, a book title) can be a live link to it. Links come from a verified list, never from memory.
+Each work named on screen (an author–year, a quoted study, a book title) can link to it, from a verified list, never from memory.
1. **List.** Add each cited work to `books/<book>/refs.json`, taking authors, year and full title from the source book's own reference list (`pages/*/text.md`). The key is `surname-surname-year` (`scheper-hughes-lock-1987`); `cite` is the on-screen label (`python3 SKILL/scripts/refs.py --help` lists the entry fields; a group author such as the World Health Organization is `{"org": "World Health Organization"}`).
-2. **Find.** `python3 SKILL/scripts/refs.py lookup books/<book>/refs.json --write`. It accepts a Crossref DOI only when the year, first author and title all match. For books without a DOI it takes the ISBN of the edition from the cited year (Open Library), which links to its WorldCat record. Decide each `NO CONFIDENT MATCH` by hand: pick the right candidate or a trusted academic page (`url`, e.g. PubMed, JSTOR, ERIC, a university repository). If none exists, keep the citation as plain text and note it in the chapter file.
+2. **Find.** `python3 SKILL/scripts/refs.py lookup books/<book>/refs.json --write`. It accepts a Crossref DOI only when the year, first author and title all match. For books without a DOI it takes the ISBN of the edition from the cited year (Open Library), which links to its WorldCat record. Decide each `NO CONFIDENT MATCH` by hand: the right candidate or a trusted academic page (`url`, e.g. PubMed, JSTOR, ERIC, a university repository); failing both, keep the citation as plain text and note it in the chapter file.
3. **Verify.** `python3 SKILL/scripts/refs.py verify books/<book>/refs.json --write` resolves every DOI or ISBN, checks it against the entry, fills in missing metadata and stamps `verified`. Fix every `FAIL`.
4. **Build.** `python3 SKILL/scripts/refs.py build books/<book>/refs.json site/<book>/refs.js`, and uncomment the `refs.js` line in `index.html` and each chapter: the contents ends with a link to a separate References view that lists every work, and each chapter's finish card lists the sources that chapter cites.
5. **Draw.** `cite(p, key, { x, y, size, fill, anchor, weight, o: 0 })` draws the label as an underlined link and returns it, ready for `show()`/`tw()` like `T`; `str` overrides the label (e.g. `'(1987)'` after a name drawn separately). Text drawn with `T` or written in a card that matches a work's `cite` label (or one of its `match` strings) becomes a link by itself. Clicking a citation opens the source in a new tab and pauses the lesson; faded-out links take no clicks or Tab focus. A work discussed but not drawn goes in `CHAPTER.refs` so the finish card still lists it.
-Draw a citation next to the text it supports rather than inside a long sentence, so the link is a separate target of at least 24 px text height.
+Draw a citation beside the text it supports rather than inside a long sentence, so the link is a separate target at least 24 px high.
## Choice questions from an item bank
-A chapter's choice questions can live in a reviewed item bank, `books/<book>/items/chNN.items.json`, instead of inline in the page, so they can be linted, reviewed by a person in a sheet, and approved before release. The bank follows the JSON schema of the [mcq-item-writer](https://github.com/titulartarantula/mcq-item-writer) skill, which writes and lints items against evidence-based item-writing rules (stem with the problem, one best answer, plausible distractors, feedback on every option). Inline `choice` stays fine for a quick check written on the spot.
+A chapter's choice questions can live in an item bank, `books/<book>/items/chNN.items.json`, instead of inline in the page, so they can be linted, reviewed by a person in a sheet and approved before release. The bank follows the JSON schema of the [mcq-item-writer](https://github.com/titulartarantula/mcq-item-writer) skill, which writes and lints items against evidence-based item-writing rules (stem with the problem, one best answer, plausible distractors, feedback on every option). Inline `choice` is still fine for a quick check written on the spot.
For a bank used by a page:
@@ -25,7 +25,7 @@ For a bank used by a page:
- **Feedback** on every option, two or three sentences. The engine adds "Correct." / "Not quite.", so don't start with a verdict; `items.py` drops one if present.
- **Order.** Options show as authored (no shuffle): spread the right answer's position across the chapter.
-Build the page's copy after every bank change, and never edit `items.js` by hand:
+Rebuild the page's copy after every bank change rather than editing `items.js` by hand:
```sh
python3 SKILL/scripts/items.py books/<book>/items/chNN.items.json site/<book>/chNN/items.js
@@ -43,7 +43,7 @@ python3 SKILL/scripts/scorm.py site/<book> --version 1.2 # older LMSs
python3 SKILL/scripts/scorm.py site/<book> --mastery 80 # also passed/failed at 80 %, once the whole book is finished
```
-`site/<book>/` is not changed; rebuild the zip after changing the book. The LMS launches `launch.html`, which opens one SCORM session and runs the book in a frame, so moving between chapters keeps the session. The build adds `scorm-bridge.js` to the contents page and after `engine.js` in every chapter; it wraps the engine's `progress()` and `finishCard()`, seeds the book's progress from the LMS on each launch (the LMS is the source of truth) and points folder links (`ch02/`) at `index.html`, which many LMS file servers need.
+`site/<book>/` is left unchanged; rebuild the zip after changing the book. The LMS launches `launch.html`, which opens one SCORM session and runs the book in a frame, so moving between chapters keeps the session. The build adds `scorm-bridge.js` to the contents page and after `engine.js` in every chapter; it wraps the engine's `progress()` and `finishCard()`, seeds the book's progress from the LMS on each launch (the LMS is the source of truth) and points folder links (`ch02/`) at `index.html`, which many LMS file servers need.
| | SCORM 1.2 | SCORM 2004 |
|---|---|---|
@@ -55,10 +55,10 @@ python3 SKILL/scripts/scorm.py site/<book> --mastery 80 # also passed/fail
A chapter counts as finished when its finish card appears, as in the book; a learner can skip there on the step bar, so use `--mastery` when the grade should depend on the answers. Cards that link to another book's folder (`href` in `units`) leave the package and don't work inside an LMS.
-Check a package before handing it over: `uv run --with playwright SKILL/assets/scorm/test/check_scorm.py dist/<book>-scorm2004.zip` opens it in `assets/scorm/test/mock-lms.html` (a stand-in LMS that shows every CMI value), opens a chapter through a folder link, reaches its finish card and checks resume. To click through by hand, unzip the package as `pkg/` next to a copy of `mock-lms.html`, run `python3 SKILL/assets/scorm/test/serve.py <folder> 8781` (no folder URLs, like an LMS) and open `http://localhost:8781/mock-lms.html?pkg=pkg&v=2004&reset`; reload without `&reset` to test resume. Before learners use it, upload it to SCORM Cloud (a free account), the usual test of a real LMS. Audio makes up most of a package: check the LMS's upload limit. Canvas grades only the overall result; it doesn't show the per-chapter objectives.
+Check a package before handing it over: `uv run --with playwright SKILL/assets/scorm/test/check_scorm.py dist/<book>-scorm2004.zip` opens it in `assets/scorm/test/mock-lms.html` (a stand-in LMS that shows every CMI value), opens a chapter through a folder link, reaches its finish card and checks resume. To click through by hand, unzip the package as `pkg/` next to a copy of `mock-lms.html`, run `python3 SKILL/assets/scorm/test/serve.py <folder> 8781` (no folder URLs, like an LMS) and open `http://localhost:8781/mock-lms.html?pkg=pkg&v=2004&reset`; reload without `&reset` to test resume. Before learners use it, try it on SCORM Cloud (a free account), the usual stand-in for a real LMS. Audio makes up most of a package: check the LMS's upload limit. Canvas grades only the overall result; it doesn't show the per-chapter objectives.
## Checking them
-For a chapter with an item bank, lint it with the item writer (`python3 MCQ/scripts/lint_items.py books/<book>/items/chNN.items.json`, where `MCQ` is the mcq-item-writer skill's folder) and fix every error; rebuild `items.js` after any change, then answer one bank question per card position, wrong then right, to see the answered card fit with Continue visible.
+Lint a chapter's item bank with the item writer (`python3 MCQ/scripts/lint_items.py books/<book>/items/chNN.items.json`, where `MCQ` is the mcq-item-writer skill's folder) and fix every error; rebuild `items.js` after any change, then answer one bank question per card position, wrong then right, to see the answered card fit with Continue visible.
-For a chapter that cites works, run `python3 SKILL/scripts/refs.py verify books/<book>/refs.json` and rebuild `refs.js` after any `refs.json` change. Every author–year or work title on screen should be a link whose key is verified; look for links that are missing, unreadable or overlapping other targets, and open one per chapter to confirm it lands on the work.
+For a chapter that cites works, run `python3 SKILL/scripts/refs.py verify books/<book>/refs.json`, and rebuild `refs.js` after any `refs.json` change. Every author–year or work title on screen should be a link whose key is verified; look for links that are missing, unreadable or overlapping other targets, and open one per chapter to confirm it lands on the work.
diff --git a/.claude/skills/papermorph/references/lessons/cover.md b/.claude/skills/papermorph/references/lessons/cover.md
index deae345..73dfce4 100644
--- a/.claude/skills/papermorph/references/lessons/cover.md
+++ b/.claude/skills/papermorph/references/lessons/cover.md
@@ -4,10 +4,10 @@ A textbook's `index.html` is its cover and contents; a picture book or a film us
## Cover and contents (`index.html`)
-One page: no hash or `#book` shows the cover, `#references` the reference list, `#contents` or `#chNN` the contents; a lesson's home button returns to `#chNN`, and the card grows into the lesson frame through a view transition. Preserve cover → contents → chapter navigation and the return from contents to cover.
+One page: no hash or `#book` shows the cover, `#references` the reference list, `#contents` or `#chNN` the contents; a lesson's home button returns to `#chNN`, and the card grows into the lesson frame through a view transition. Keep cover → contents → chapter navigation and the return from contents to cover working.
-- Edit the title, kicker, lede, the faint chalk phrases on the cover (a few formulas or lines from the book), and the `<title>`.
-- The page's script calls `Contents.book({ start, units, hues })` (from the engine's `lib/contents.js`; the shared styles are `lib/contents.css`):
+- Edit the title, kicker, lede, the faint chalk phrases on the cover (a few formulas or lines from the book) and the `<title>`.
+- The page's script calls `Contents.book({ start, units, hues })` (the engine's `lib/contents.js`; shared styles in `lib/contents.css`):
- `units`: `[unit title, [[chapter title, minutes], …]]`; chapters are numbered in order from `start` (`{ unit: 1, chapter: 1 }`; a book whose scope starts mid-way, e.g. at unit 3, chapter 9, keeps the original numbers).
- Add a chapter when its lesson is ready, and set the previous chapter's `CHAPTER.next = '../chNN/'`.
- A unit's optional third entry `{ unit, chapter, sample: true }` renumbers it and marks it as a sample, left out of the chapter count.
@@ -15,8 +15,8 @@ One page: no hash or `#book` shows the cover, `#references` the reference list,
- A chapter's own third entry `{ chapter }` changes only the number on its card; `{ href, chapter }` links a card to another book's chapter, outside this book's count and progress (`href` on a unit's entry does it for the whole unit).
- `hues`: one colour per unit, cycling.
- A book that cites works gets a `#references` view ([courses.md](courses.md#citations)).
-- A book with its own look overrides the tokens of `lib/contents.css` (`--board`, `--chalk`, `--top-bg`, …) in a `<style>` after it, as the template's comment shows; don't copy the stylesheet into the page.
+- A book with its own look overrides the tokens of `lib/contents.css` (`--board`, `--chalk`, `--top-bg`, …) in a `<style>` after it, as the template's comment shows, rather than copying the stylesheet into the page.
## Unit sketches (`unit-art.js`)
-Give each unit a small sketch of its own ideas, drawn in the unit colour, with one gentle topic-related loop. Use the agreed asset approach. Keep the left third light for the title on phones; check the finished contents at 1440 px and 390 px once. Classes and loop examples are in `unit-art.js`; the shared header styles, off-screen pausing and reduced motion live in the engine's `lib/units.css` and `lib/units.js` (`Units.header`, `Units.watch`).
+Give each unit a small sketch of its own ideas in the unit colour, with one gentle topic-related loop, using the agreed asset approach. Keep the left third light for the title on phones; check the finished contents once at 1440 px and 390 px. Classes and loop examples are in `unit-art.js`; the shared header styles, off-screen pausing and reduced motion live in the engine's `lib/units.css` and `lib/units.js` (`Units.header`, `Units.watch`).
diff --git a/.claude/skills/papermorph/references/lessons/diagrams.md b/.claude/skills/papermorph/references/lessons/diagrams.md
index 873fc93..88ad87c 100644
--- a/.claude/skills/papermorph/references/lessons/diagrams.md
+++ b/.claude/skills/papermorph/references/lessons/diagrams.md
@@ -1,11 +1,11 @@
# Symbols and diagrams that change
-For abstract and procedural ideas (the maths books on the showcase site, `site/elementary-algebra/` and `site/math-notebook/`). The picture explains through change: things are rearranged, split, balanced, counted and compared while the narration says why. The change is the argument, so each move must be one the idea allows.
+For abstract and procedural ideas (the maths books, `site/elementary-algebra/` and `site/math-notebook/`). The picture explains through change: things are rearranged, split, balanced, counted and compared while the narration says why. The change is the argument, so each move must be one the idea allows.
-- **One reading line.** A derivation or a procedure reads in one direction, each step under or beside the last, aligned on what stays the same (the `=` sign, the place values). The eye never searches for the next step.
+- **One reading line.** A derivation or a procedure reads in one direction, each step under or beside the last, aligned on what stays the same (the `=` sign, the place values), so the eye never searches for the next step.
- **Change the thing, don't replace it.** Tokens that combine move together and collapse into the result (`tokens`, `collapse`); a tile pair cancels where it stands; a dot hops along the number line. A fresh line of text is a weaker picture than the old one transforming.
-- **Exact where it matters.** Number lines, grids, areas and graphs are to scale; illustrative pictures only need to be clear. Approximations are written as approximations (≈ 4.47…, never = 4.47).
+- **Exact where it matters.** Number lines, grids, areas and graphs are to scale; illustrative pictures only need to be clear. Approximations are written as approximations (≈ 4.47…, not = 4.47).
- **Show the common mistake** where one exists (squaring the coefficient too), visibly crossed out, then the right way.
-- **Vary the composition with the content.** A chapter that is one centred formula after another feels monotonous; a number line, a table, a picture of the quantity and a worked line each have their own layout.
+- **Vary the composition with the content.** One centred formula after another feels monotonous; a number line, a table, a picture of the quantity and a worked line each have their own layout.
-Storyboard these beats like any other: place the key moments in the real page and capture them with `strip.py` before timing the moves ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). The engine's maths helpers (number lines, tiles, fraction rows, planes, data plots) are in `lib/math.js`, listed in [engine.md](../core/engine.md#drawing).
+Storyboard these beats like any other ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). The maths helpers (number lines, tiles, fraction rows, planes, data plots) are in `lib/math.js`, listed in [engine.md](../core/engine.md#drawing).
diff --git a/.claude/skills/papermorph/references/lessons/intake.md b/.claude/skills/papermorph/references/lessons/intake.md
index 688df37..51e9e56 100644
--- a/.claude/skills/papermorph/references/lessons/intake.md
+++ b/.claude/skills/papermorph/references/lessons/intake.md
@@ -1,38 +1,36 @@
# Intake: from a PDF to one agreed chapter
-A short conversation that ends with one chapter the user agreed to try, a tier, the look and `style.json`. How to ask (choices to click, the user's words kept verbatim), the models step and the file itself are in [core/style.md](../core/style.md); this file is what a textbook needs settled.
-
-When the user brings a story, a joke or a fairy tale instead (or a story book's PDF), it becomes a picture book ([stories.md](../picture-books/stories.md#intake-for-a-story)); a book, an idea or a stretch of history to explain as a film, or one point for a phone feed, goes to [films.md](../films/films.md#intake).
+A short conversation that ends with one chapter the user agreed to try, a tier, the look and `style.json`. How to ask, the models step and the file itself are in [core/style.md](../core/style.md); this file is what a textbook needs settled.
## 1. Welcome and the PDF
-Greet briefly as Papermorph. Look for PDFs in the working folder and its subfolders (then the user's Downloads and Desktop if none are found) and ask "Is it this one?", listing up to four candidates. If none are found, offer to search another folder or to take a path. Choose a short slug and place the file at `books/<book>/book.pdf`, a copy or a link.
+Greet briefly as Papermorph. Look for PDFs in the working folder and its subfolders (then the user's Downloads and Desktop) and ask "Is it this one?", listing up to four candidates; if none turn up, offer to search another folder or take a path. Choose a short slug and place the file at `books/<book>/book.pdf`, a copy or a link.
## 2. What this book is
-Run the split ([lessons.md](lessons.md#pipeline)) and read the contents, the preface and the `text.md` of two or three chapter openings across the book. Say in two or three sentences what the book is: subject, readers, how it teaches. Then offer a chapter to try: name two or three candidates with one line each on what they would show, recommending one that is representative rather than the gentlest opening (a light introduction can pass while hiding the hard problems). A section of a long chapter is fine.
+Run the split ([lessons.md](lessons.md#pipeline)) and read the contents, the preface and the `text.md` of two or three chapter openings across the book. Say in two or three sentences what the book is: subject, readers, how it teaches. Then offer two or three chapters to try, one line each on what they would show, recommending a representative one rather than the gentlest opening (a light introduction can pass while hiding the hard problems). A section of a long chapter is fine.
-If the book is for a course, notice it here: when it cites other works (author–year citations, named studies), offer links from the works named on screen to their sources; when its questions must be reviewed before release, offer an item bank; when it goes into an LMS, mention the SCORM package. None is on by default ([courses.md](courses.md)).
+If the book is for a course, notice it here: a book that cites other works can get links from the works named on screen to their sources; questions that must be reviewed before release, an item bank; a book going into an LMS, the SCORM package. None is on by default ([courses.md](courses.md)).
## 3. Tier
-Offer the animation tiers as reference points; the books at https://papermorph.diamonddoge.org/ show each of them; link them.
+Offer the animation tiers as reference points, linking the books at https://papermorph.diamonddoge.org/ that show each:
1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books, `site/elementary-algebra/` and `site/math-notebook/`). The lightest; a smaller model can do most steps.
2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book, `site/science/`). Several times the work of tier 1 per chapter, and the picture step wants a strong model.
3. **Custom**: the user describes what they want; you judge which abilities it needs and say so.
-Recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)); physical and narrative ones fit tier 2 ([scenes.md](scenes.md)). Mixing per beat is allowed under any tier.
+Recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)), physical and narrative ones tier 2 ([scenes.md](scenes.md)). Any tier may mix per beat.
-Then start the book folder (`new_book.py lesson <book>`, [core/publish.md](../core/publish.md#start-a-book-folder)): the look is settled on real frames, so the engine, the chapter page and the voice need to be in place first.
+Then start the book folder (`new_book.py lesson <book>`, [core/publish.md](../core/publish.md#start-a-book-folder)): the look is settled on real frames, so the engine, the chapter page and the voice must be in place first.
## 4. The look, by tier
-**Tier 1** needs few decisions. Propose palette, fonts and the language and voice from the book itself. Then make the chapter's narration and its first one or two beats, laid out at real size ([lessons.md](lessons.md#chapter-loop), steps 2–3), and capture a few key frames with `strip.py`. Show the sheet and ask: go ahead as it is (recommended), or one of two or three concrete changes (calmer, more colour, larger type …). Once agreed, settle the models ([core/style.md](../core/style.md#models)), then write `style.json` and make the chapter.
+**Tier 1** needs few decisions. Propose palette, fonts, language and voice from the book itself. Make the chapter's narration and its first one or two beats at real size ([lessons.md](lessons.md#chapter-loop), steps 2–3) and capture a few key frames with `strip.py`. Show the sheet and ask: go ahead as it is (recommended), or one of two or three concrete changes (calmer, more colour, larger type …). Once agreed, settle the models ([core/style.md](../core/style.md#models)), write `style.json` and make the chapter.
**Tier 2** has more to settle; ask in rounds:
-1. Art and sources: drawn in code, pixel scenes, illustrated, real images; whether web images (with credits) are acceptable. The recurring characters: propose two or three casts that suit the book, each in one line.
-2. Shared components: list the things this chapter, and the chapters around it, will draw again and again (in the science book: force arrows, crates, the actors), each with what it must do and how it would be made. Offer them as one multiple-choice question, recommending the ones that recur most, for which to build once for the whole book ([assets.md](assets.md)).
+1. Art and sources: drawn in code, pixel scenes, illustrated, real images; whether web images (with credits) are acceptable. For the recurring characters, propose two or three casts that suit the book, one line each.
+2. Shared components: list what this chapter and its neighbours will draw again and again (in the science book: force arrows, crates, the actors), each with what it must do and how it would be made. Offer them as one multiple-choice question of which to build once for the whole book, recommending the ones that recur most ([assets.md](assets.md)).
3. The storyboard: lay out the key moments without motion and show the sheet ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). Ask: add motion now (recommended), or a few concrete changes to named frames. Motion comes after the user agrees.
**Custom**: ask what the description leaves open, using the closest tier's rounds and options.
diff --git a/.claude/skills/papermorph/references/lessons/lessons.md b/.claude/skills/papermorph/references/lessons/lessons.md
index a2098ae..eabf459 100644
--- a/.claude/skills/papermorph/references/lessons/lessons.md
+++ b/.claude/skills/papermorph/references/lessons/lessons.md
@@ -1,8 +1,6 @@
# Lessons: from a textbook PDF to animated chapters
-Each chapter is a short animated lesson film where the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture. The maths books (`site/elementary-algebra/`, `site/math-notebook/`) show tier 1, the science book (`site/science/`) tier 2.
-
-Start with [intake.md](intake.md) whenever `books/<book>/style.json` does not exist yet; reuse answers and approvals already given. Re-create explanations, examples and drawings; source PDFs, page images and extracted text stay outside `site/` and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`).
+Each chapter is a short animated lesson film where the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture. The maths books (`site/elementary-algebra/`, `site/math-notebook/`) show tier 1, the science book (`site/science/`) tier 2. A new book starts with [intake.md](intake.md).
## Contents
@@ -14,6 +12,8 @@ Start with [intake.md](intake.md) whenever `books/<book>/style.json` does not ex
## Project layout
+What a lesson book adds to the layout in SKILL.md:
+
```
books/<book>/
book.pdf, sections.json source and page map (private)
@@ -23,9 +23,7 @@ books/<book>/
chapters/chNN.md storyboard, errata, feedback
images/ inbox, SOURCES.md, image-requests.md, processing scripts
review/chNN/ storyboard sheets, strips, check output
-content/<book>/chNN/ narration.<lang>.json and TTS cache
-tools/<book>/ tests and evidence scripts
-site/<book>/ the static book (only this is delivered)
+site/<book>/
index.html, unit-art.js cover + contents, unit sketches (cover.md)
lib/engine.*, math.js, volume.*, contents.*, units.* the engine, copied in by engine.py
lib/book.css this book's engine settings and style overrides
@@ -35,26 +33,26 @@ site/<book>/ the static book (only this is delivered)
## Pipeline
-1. **Intake** ([intake.md](intake.md)), a short conversation: find the PDF with the user, split it, say what the book is, agree on one chapter to try and a tier, start the book folder, settle the look the way that tier needs, agree the models and write `style.json` ([core/style.md](../core/style.md)).
- - Split: `uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf`; use `--level N -o books/<book>/sections.json` at chapter depth. A chapter bookmark that points outside its neighbours is moved to the page holding its title or dropped, with a warning: look at those chapters' pages. For a PDF without usable chapter bookmarks, inspect `split_pages.py … --pages 1-12 --out books/<book>/pages`, then write the map from its contents (schema: `outline.py --help`). Extract chapter text with `split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only`.
+1. **Intake** ([intake.md](intake.md)): find the PDF with the user, split it, say what the book is, agree on one chapter to try and a tier, start the book folder, settle the look the way that tier needs, agree the models and write `style.json` ([core/style.md](../core/style.md)).
+ - Split: `uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf`; use `--level N -o books/<book>/sections.json` at chapter depth. A chapter bookmark that points outside its neighbours is moved to the page holding its title or dropped, with a warning: look at those chapters' pages. Without usable chapter bookmarks, inspect `split_pages.py … --pages 1-12 --out books/<book>/pages` and write the map from its contents (schema: `outline.py --help`). Extract chapter text with `split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only`.
- Start the book folder with `new_book.py lesson <book>` ([core/publish.md](../core/publish.md#start-a-book-folder)) before showing the user any frames; build agreed shared components once into the book's library ([assets.md](assets.md)) and list them in `style.json`.
2. **Pilot.** Make the chosen chapter through the chapter loop and deliver it for the user's judgement. Fold their feedback into `style.json` and record the chapter under `approved`.
-3. **Remaining chapters and finish**, when the user wants the whole book: write `chapters.md`, produce chapters one after another ([Team](#team)), complete cover text, contents and unit sketches ([cover.md](cover.md)). Deliver the static book folder, its entry URL for local preview and any unresolved issues.
+3. **Remaining chapters and finish**, when the user wants the whole book: write `chapters.md`, produce chapters one after another ([Team](#team)), complete cover text, contents and unit sketches ([cover.md](cover.md)). Deliver the static book folder, its local preview URL and any unresolved issues.
-A course book may also want verified citation links, a reviewed question bank or a SCORM package for an LMS; offer them only when the book calls for them ([courses.md](courses.md)).
+A course book may also want verified citation links, a reviewed question bank or a SCORM package; offer them only when the book calls for them ([courses.md](courses.md)).
## Chapter loop
1. **Read** this chapter's `pages/chNN/text.md`; render pages with `split_pages.py … --only chNN` when diagrams or missing text need images. Choose the ideas, examples and sections to teach.
2. **Beats and narration**: list beats in `chapters/chNN.md` with what each says and which word triggers which action ([authoring.md](authoring.md)). Write `content/<book>/chNN/narration.<lang>.json` and voice it with `tts.py` ([core/sound.md](../core/sound.md#voices)).
-3. **Storyboard, layout first**: in the real page, place everything for one to three key moments per beat, real elements at their real sizes, no motion yet. Capture them into one sheet with `strip.py` and give each frame one line: what it says and where the eye goes. That sheet is the storyboard ([diagrams.md](diagrams.md), [scenes.md](scenes.md#storyboard-layout-first-then-motion)). Note what the chapter needs beyond the library: draw it, or add it to the image requests.
+3. **Storyboard, layout first**: one to three key moments per beat, placed in the real page without motion and captured into one sheet ([scenes.md](scenes.md#storyboard-layout-first-then-motion), [diagrams.md](diagrams.md)). Whatever the chapter needs beyond the library is drawn or added to the image requests ([assets.md](assets.md#chapter-level-needs-noticed-while-storyboarding)).
4. **Motion**: add the motion, the camera and the questions ([questions.md](questions.md)); API and replay invariants are in [core/engine.md](../core/engine.md).
-5. **Delivery pass**: watch your output in motion and judge it as a viewer would, against the storyboard ([core/review.md](../core/review.md)); then run the lesson checks ([checks.md](checks.md)). Correct what you find, recheck, deliver; report unresolved problems.
-6. **Register**: add the chapter to the contents (`units` in `Contents.book` in `index.html`, [cover.md](cover.md)), set the previous chapter's `CHAPTER.next`, update `chapters.md` and `chapters/chNN.md`. Promote new shared decisions and recurring elements to `style.json` and the library. The coordinator owns this step when using subagents.
+5. **Delivery pass**: watch it against the storyboard ([core/review.md](../core/review.md)), run the lesson checks ([checks.md](checks.md)), correct, recheck, deliver; report unresolved problems.
+6. **Register**: add the chapter to the contents (`units` in `Contents.book` in `index.html`, [cover.md](cover.md)), set the previous chapter's `CHAPTER.next`, update `chapters.md` and `chapters/chNN.md`. Promote new shared decisions and recurring elements to `style.json` and the library. With subagents the coordinator owns this step.
## LaTeX
-If the book's formulas need LaTeX ([core/engine.md](../core/engine.md#latex)), add MathJax (with its licence) to `lib/` and load `../lib/mathjax.js` right after `engine.js` in every chapter:
+For formulas that need LaTeX ([core/engine.md](../core/engine.md#latex)), add MathJax (with its licence) to `lib/` and load `../lib/mathjax.js` right after `engine.js` in every chapter:
```sh
python3 SKILL/scripts/engine.py site/<book> --latex # lib/mathjax.js; later syncs keep it in step
@@ -64,11 +62,11 @@ python3 SKILL/scripts/engine.py site/<book> --latex # lib/mathjax.js; later sy
The general shape and the coordinator's job are in [core/team.md](../core/team.md); a lesson splits by step of the chapter loop, chapters one after another.
-In the pilot the picture worker stops when the storyboard sheet is ready and replies with it; the coordinator shows the sheet to the user, then continues the same worker with the user's changes to add motion.
+In the pilot the picture worker stops when the storyboard sheet is ready and replies with it; the coordinator shows it to the user, then continues the same worker with the user's changes to add motion.
-1. **Extract — small.** From `pages/chNN/text.md` and the page images it needs, write the source material into `chapters/chNN.md` in the shape of the previous chapter's: concepts in book order with the book's wording and examples, vocabulary, each figure (labels, arrows, purpose), every end-of-chapter question with its answer, and a list of possible problems in the source (flagged, not decided).
-2. **Narration — middle.** From chNN.md, [authoring.md](authoring.md), `style.json` and the previous approved chapter (its beat table and narration as the worked example): decide each flagged problem (`## Errata`), choose what to teach for the book's pacing (and say what was dropped), write the beat table (what the picture shows and does, each `[[mark]]` naming the word that triggers which action, where the eye goes, new visual elements needed), all questions, the narration file, then run `tts.py` and confirm every mark is in timings.js. The plan has to be concrete enough for a different model to build from.
-3. **Picture — strong.** From the plan, `style.json`, the previous approved chapter's page and the book's library: storyboard layout first, then motion, camera and questions, new shared elements in the library, a quick self-view of the busiest beats and lint. The plan is a plan, not a cage. Storyboard and motion stay in one step: split, the next worker would have to read the whole page again. Look at the storyboard sheet yourself when it comes back; problems visible there are cheapest to name now.
+1. **Extract — small.** From `pages/chNN/text.md` and the page images it needs, write the source material into `chapters/chNN.md` in the shape of the previous chapter's: concepts in book order with the book's wording and examples, vocabulary, each figure (labels, arrows, purpose), every end-of-chapter question with its answer, and possible problems in the source (flagged, not decided).
+2. **Narration — middle.** From chNN.md, [authoring.md](authoring.md), `style.json` and the previous approved chapter (its beat table and narration as the worked example): decide each flagged problem (`## Errata`), choose what to teach for the book's pacing (and say what was dropped), write the beat table (what the picture shows and does, each `[[mark]]` and the action it triggers, where the eye goes, new visual elements needed), all questions and the narration file, then run `tts.py` and confirm every mark is in timings.js. The plan must be concrete enough for a different model to build from.
+3. **Picture — strong.** From the plan, `style.json`, the previous approved chapter's page and the library: storyboard layout first, then motion, camera and questions, new shared elements in the library, a quick self-view of the busiest beats and lint. The plan is a plan, not a cage. Storyboard and motion stay in one step, or the next worker would have to read the whole page again. Look at the storyboard sheet yourself when it comes back; problems visible there are cheapest to name now.
4. **Checks — small, report-only**, in parallel with 5: lint, `check.py`, `check_blank.py`, `overlap.py`, `still.py`, `perf.py` in Firefox, and an e2e test adapted from the previous chapter's (the first from `assets/templates/e2e.py`, [checks.md](checks.md#interaction-tests)), in Chromium and Firefox. It reports problems with beat and time and changes only its own test.
5. **Review — middle**, in parallel with 4: watch every beat ([core/review.md](../core/review.md#watch-it-in-motion)) against the storyboard and the approved chapters. It fixes small local problems itself and lists larger ones with beat, time and a suggested fix. Its reply opens with the beats it watched; if some are missing, send it back to finish (continuing a worker is cheaper than starting one).
6. **Rework — strong, only for real problems** left by 4 and 5: a brief listing exactly those, re-checked with strips, `still.py`, lint and e2e in both browsers.
diff --git a/.claude/skills/papermorph/references/lessons/questions.md b/.claude/skills/papermorph/references/lessons/questions.md
index f65c4ab..f2c8a9c 100644
--- a/.claude/skills/papermorph/references/lessons/questions.md
+++ b/.claude/skills/papermorph/references/lessons/questions.md
@@ -1,6 +1,6 @@
# Questions
-Pick the type that lets the student act on the picture itself whenever possible (click the point, the cell, the step) rather than choosing text.
+Prefer a type that lets the student act on the picture itself (click the point, the cell, the step) over choosing text.
| Type | Use for |
| --- | --- |
@@ -19,8 +19,8 @@ New types are welcome when the content calls for one; each needs keyboard play.
- The prompt is rich text ([core/engine.md](../core/engine.md#traps)).
- Feedback: right → `why` (and an animation via `fx`/`onRight`); wrong → a hint aimed at that mistake; after a wrong try, Show answer.
- Grade meaning: equal values match (6/8 = 3/4) unless the lowest form is asked for; sets and pairs in any order; no denominators of zero; never judge irrationality from finitely many digits.
-- The built-in numeric parser uses safe integer numerators and denominators and exact integer products for equality. For answers outside that range, use a subject-specific input and grader rather than allowing rounded values to pass.
-- Compose the question beat for its card: the picture the question is about stays visible (for example in the top 60 % with a `BAND` card below, or beside a `{x, y, w, cls: 'side'}` card); `SCREEN` for practice.
+- The built-in numeric parser compares exact integer products of safe-integer numerators and denominators; for answers outside that range, use a subject-specific input and grader rather than letting rounded values pass.
+- Compose the question beat around its card so the picture it asks about stays visible (in the top 60 % above a `BAND` card, or beside a `{x, y, w, cls: 'side'}` card); `SCREEN` for practice.
- Units in typed answers: write the unit as a word after the box (`{ box: '60' }, ' kilograms'`) so it is not set as a math variable.
## API
@@ -35,6 +35,6 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'
- `blanks(rows)` — rows `{parts: [..., {box: '21'}, ...], why, hint?, fx?, test?}`; accepts −5, 3/4, 2 1/4, 0.75 as exact values, also with a currency sign ($60, 5 €) and thousands grouped by spaces of any kind (1 250, as [authoring.md](authoring.md#content-rules) shows numbers) or, where the decimal sign is a point, by commas (1,250); `{box, lowest: true}` demands lowest terms; `test(values)` judges the whole row (e.g. two factors in either order). `hint` is one message for any wrong value in its row; when different mistakes need their own answers, split the step into rows or ask it as a `choice` with `wrongWhys`. Tab moves between boxes, Enter checks, Esc leaves a box.
- `grid(rows, cols, {multi, text})` — rows `{parts, ans: [keys], why, fx?}`, cols `[[key, label, colour?, hotkey?]]`; with `text: true` parts are rich text (math via `$m`). ↑/↓ change rows.
- `tap(values, right, why, v => wrongWhy, onRight?)` points on the number line; `tapEls(row, idx, right, …)` tokens of a `tokens` row; `pickEls([{el, box: [x,y,w,h], label}], right, …)` any drawn objects; `pickPoint(P, [x,y], why, (x,y) => wrongWhy, onRight?, test?)` grid points (arrows + Enter or click); `sorter(items, trayXY)` drag into the set diagram (keys 1–6). `pickPoint` and `sorter` are in math.js.
-- Answer animations run on their own clock: `fx`, `fxp`, `pulseFx`, `shakeFx`, `floatText`, `qlayer()` (a layer cleared with the question). They are finished automatically when the beat is left.
+- Answer animations run on their own clock: `fx`, `fxp`, `pulseFx`, `shakeFx`, `floatText`, `qlayer()` (a layer cleared with the question). They finish automatically when the beat is left.
- A new type: `build(body, api)` returns `{ reveal, check?, lock?, key?(e), hint? }` and calls `api.grade(ok, message, {right, total})`. `key` handles its shortcuts (return true when used); `hint` lists the keys under the prompt. Every action needs a key; the help overlay (`?`) lists the global ones.
- Scores: `SCORE[id]` keeps the first try across revisits and step jumps; restarting the chapter clears it. A multi-row question scores one per row. A correct retry changes the feedback, not the first-attempt score.
diff --git a/.claude/skills/papermorph/references/lessons/scenes.md b/.claude/skills/papermorph/references/lessons/scenes.md
index b34e849..191a8b9 100644
--- a/.claude/skills/papermorph/references/lessons/scenes.md
+++ b/.claude/skills/papermorph/references/lessons/scenes.md
@@ -1,38 +1,38 @@
# Illustrated scenes
-For physical, spatial and narrative ideas: people and things act out the idea, the camera shows what matters, and the words live inside the picture (the science book on the showcase site, `site/science/`).
+For physical, spatial and narrative ideas: people and things act out the idea, the camera shows what matters, and the words live inside the picture (the science book, `site/science/`).
## Each moment is one picture
-The subject comes first, large and placed where the eye lands; text is part of the picture and appears beside what it names, as it is said. A layout with a title row, a picture somewhere else and notes in a column feels fragmented even when every piece is correct.
+The subject comes first, large and where the eye lands; text is part of the picture and appears beside what it names, as it is said. A title row, a picture somewhere else and notes in a column feel fragmented even when every piece is correct.
Worked example, the push in the science book's chapter 10:
- *Before*: a small pusher and cart at the bottom left, the sentence at the top centre, the word "push" floating far from both, and an arrow above the cart rather than on it. Every piece was right; nothing read as one picture.
-- *After*: the actor three times larger with the cart against her hands; the force arrow starts at the hands and runs through the cart, its label "push · 6 N" on the arrow; the sentence sits just above the actor. The eye goes actor, arrow, words.
+- *After*: the actor three times larger with the cart against her hands; the force arrow starts at the hands and runs through the cart, labelled "push · 6 N" on the arrow; the sentence just above the actor. The eye goes actor, arrow, words.
-Vary the composition with the content (a close-up, a wide shot, a split screen, a view from above) rather than repeating one template; a chapter made of the same frame over and over felt monotonous. Some atmosphere is welcome when it stays light: favour objects and moves that carry the idea, and trim a bystander, dense scenery or a flourish that competes with it.
+Vary the composition with the content (a close-up, a wide shot, a split screen, a view from above); a chapter of the same frame over and over felt monotonous. Light atmosphere is welcome: favour objects and moves that carry the idea, and trim a bystander, dense scenery or a flourish that competes with it.
## Storyboard: layout first, then motion
1. With narration and beats written, place everything for one to three key moments per beat in the real page: real elements at their real sizes, positions written as the moment's values, no tweens yet.
2. Capture those moments into one sheet (`strip.py chNN OUT force:push,dir net:add … --sheet storyboard --url http://localhost:8765/<book>/`; times may be marks). Write one line per frame in `chapters/chNN.md`: what it says and where the eye goes. That sheet is the storyboard; composition is cheapest to change now.
-3. In the pilot the user reviews the sheet before motion is added. In later chapters it is your own check and stays as evidence in `books/<book>/review/chNN/`.
-4. Add motion and camera so that the picture passes through those compositions, then compare finished frames with the sheet.
+3. In the pilot the user reviews the sheet before motion is added; in later chapters it is your own check, kept as evidence in `books/<book>/review/chNN/`.
+4. Add motion and camera so the picture passes through those compositions, then compare finished frames with the sheet.
## Actors and actions
-When the narration says someone pushes, throws or jumps, they perform it with weight and timing, and what they handle moves with them. A figure sliding across the ground like a statue reads as a still picture, not an action, and viewers notice it at once.
+When the narration says someone pushes, throws or jumps, they perform it with weight and timing, and what they handle moves with them. A figure sliding across the ground like a statue reads as a still picture, and viewers notice at once.
- Drive gait frames from the distance travelled, so the feet keep pace with the ground.
-- Keep contact as a shared position: the prop follows the hand position of the current frame; a ball is caught, held and released through it.
+- Keep contact as a shared position: the prop follows the current frame's hand position; a ball is caught, held and released through it.
- Time poses to narration marks (wind-up before "kick", contact on it), and derive motion constants from the marks when an action must land on a word.
- When a sprite set has too few poses, draw frames from a simple skeleton rather than going without the action ([assets.md](assets.md)).
## The camera tells the story
-Establish the scene, push in at the moment of contact, pull back for the result, follow a moving subject, switch views (side to top, split screen) to reveal structure. One purposeful move per beat is usually enough. Labels that must stay readable live in screen space and track their object (`cam.track`). See [engine.md](../core/engine.md#world-clock-and-camera).
+Establish the scene, push in at the moment of contact, pull back for the result, follow a moving subject, switch views (side to top, split screen) to reveal structure. One purposeful move per beat is usually enough. Labels that must stay readable live in screen space and track their object (`cam.track`, [engine.md](../core/engine.md#world-clock-and-camera)).
## True at every moment
-Motion, arrows, labels and numbers state the same thing at the same moment. A force is drawn while it acts and disappears when contact ends; an accelerating object keeps accelerating while its label says so, so size the demonstration to the narration rather than clamping it at the frame edge; readouts come from the same function of time as the motion. Check worked numbers as the subject, not just as arithmetic. Scale realism is not needed; clarity for the reader is.
+Motion, arrows, labels and numbers state the same thing at the same moment. A force is drawn while it acts and disappears when contact ends; an accelerating object keeps accelerating while its label says so, so size the demonstration to the narration rather than clamping it at the frame edge; readouts come from the same function of time as the motion. Scale realism is not needed; clarity is.
-Still frames hide frozen actors and drifting timing; watch each action in motion before calling it done ([review.md](../core/review.md#watch-it-in-motion)).
+Still frames hide frozen actors and drifting timing, so watch each action in motion ([review.md](../core/review.md#watch-it-in-motion)).
diff --git a/.claude/skills/papermorph/references/picture-books/painting.md b/.claude/skills/papermorph/references/picture-books/painting.md
index fca09f9..801d95a 100644
--- a/.claude/skills/papermorph/references/picture-books/painting.md
+++ b/.claude/skills/papermorph/references/picture-books/painting.md
@@ -1,31 +1,31 @@
# Painted sets: an image model for everything that stays still
-In the painted look, one question splits the work: **does it move?** Streets, rooms, walls, shelves, furniture, signs, and props that only move as a whole (a bun, a bottle, an umbrella, a cart, a desk) are painted by an image model. Anything with joints, a face or a change of shape (people, animals, rain and snow, thought bubbles, clock hands) stays a paper puppet in code ([puppets.md](puppets.md)). A painting never has to act and a puppet never has to look like a painting, so neither does the other's job badly. *Joke Collection* paints its episodes this way for well under a dollar each.
+In the painted look one question splits the work: **does it move?** Streets, rooms, walls, shelves, furniture, signs, and props that only move as a whole (a bun, a bottle, an umbrella, a cart, a desk) are painted by an image model. Anything with joints, a face or a change of shape (people, animals, rain and snow, thought bubbles, clock hands) stays a paper puppet in code ([puppets.md](puppets.md)). A painting never has to act and a puppet never has to look like a painting, so neither does the other's job badly. *Joke Collection* paints its episodes this way for well under a dollar each.
## Choosing the look
-Paint one set two or three ways at the cheapest quality, stand the puppets in each (composite a frame), and let the user choose. In *Joke Collection* the candidates were flat paper like the puppets, warm gouache, and a richer torn-paper collage with light; the collage was chosen: let the image model carry as much as it can, while everything that can move still moves. Keep the chosen picture as the style reference for every later set and prop, and record the style words in `style.json`.
+Paint one set two or three ways at the cheapest quality, stand the puppets in each (composite a frame), and let the user choose. In *Joke Collection* the candidates were flat paper like the puppets, warm gouache, and a richer torn-paper collage with light; the collage won: let the image model carry as much as it can, while everything that can move still moves. Keep the chosen picture as the style reference for every later set and prop, and record the style words in `style.json`.
## Getting the composition you need
-Puppets stand at fixed places, counters must hide the right legs, and cuts must match. The reliable way is to draw the set first as a rough SVG sketch in `books/<book>/art/sets.js` (`bake_sets.py books/<book>/art/sets.js site/<book> <set> … --ref books/<book>/art` renders each named set as one frame, `ref-<set>.png`; name the sets, since a set already baked is otherwise skipped; the picture holds every layer of the set, so a layer painted on its own needs its own reference, cropped or sketched as a set of its own), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. The exact geometry does not, so the places puppets and props stand at come from the painted set, not the sketch ([stories.md](stories.md#team) says how to measure them). Once a set is painted, `bake_sets.py` leaves it alone unless you name it. Then:
+Puppets stand at fixed places, counters must hide the right legs, and cuts must match. So draw the set first as a rough SVG sketch in `books/<book>/art/sets.js` and have the model repaint *that picture* in the style of the reference: the layout survives, the look changes. `bake_sets.py books/<book>/art/sets.js site/<book> <set> … --ref books/<book>/art` renders each named set as one frame, `ref-<set>.png` (name the sets, since a set already baked is otherwise skipped; the frame holds every layer of the set, so a layer painted on its own needs its own reference, cropped or sketched as a set of its own). The exact geometry does not survive, so the places puppets and props stand at come from the painted set, not the sketch ([stories.md](stories.md#team) says how to measure them). Once a set is painted, `bake_sets.py` leaves it alone unless you name it. Then:
- **Cut-outs for whatever people stand behind.** A counter, a cart, rows of desks, a lectern: paint each as its own picture on a transparent background and place it as a layer (`painted.py`, `cut`).
- **Variants by editing, not redrawing.** Rain and snow versions of a street, a door open and shut, a bun with a bite: edit the one picture, so a cut between versions changes only that.
-- **Leave signs blank.** Image models garble text, Chinese and Japanese worst. Paint the banner, the shop sign, the blackboard empty and let `painted.py` write the words on in a real font.
-- **Paint wider than the frame.** Camera shakes and zooms see past the edge; `painted.py` pads full frames by mirroring their edges (`pad`, 60 px at the sides and 34 at top and bottom), enough for a shake but not a pan: a camera that travels further zooms in enough to keep its view inside the picture (a follow shot needed about 1.4×), and when something near an edge (a post box) shows twice in a close-up, `"edge": "stretch"` on that layer pads it with its own outermost pixels instead.
+- **Leave signs blank.** Image models garble text, Chinese and Japanese worst. Paint the banner, the shop sign, the blackboard empty and let `painted.py` write the words in a real font.
+- **Paint wider than the frame.** Shakes and zooms see past the edge; `painted.py` pads full frames by mirroring their edges (`pad`, 60 px at the sides and 34 at top and bottom), enough for a shake but not a pan: a camera that travels further zooms in enough to keep its view inside the picture (a follow shot needed about 1.4×), and when something near an edge (a post box) shows twice in a close-up, `"edge": "stretch"` on that layer pads it with its own outermost pixels instead.
-Everything that comes out goes through `painted.py` (manifest `books/<book>/art/painted.json`): sets resized to the 1600×900 frame, blurred copies for close-ups, cut-outs placed, words written, props written to `img/props/`. Stand the puppets in a frame and look before going on.
+Everything goes through `painted.py` (manifest `books/<book>/art/painted.json`): sets resized to the 1600×900 frame, blurred copies for close-ups, cut-outs placed, words written, props written to `img/props/`. Stand the puppets in a frame and look before going on.
## Cost
-Money is the user's, so the user sets a ceiling and sees every cent:
+The money is the user's, so the user sets a ceiling and sees every cent:
- `paint.py --q` is `low` or `medium` (the default; high is refused). Try `--q low` first: in these books low was often good enough for the final set (about $0.016 a picture with one reference, about $0.026 with the style picture as a second; medium about $0.02–0.03; high cost five times as much and, once used in a film, looked the same).
-- `paint.py` reads the OpenRouter key from `~/.config/openrouter/key` or `$OPENROUTER_API_KEY`. Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`; `paint.py --total books/<book>/art/costs.tsv` sums it); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider (OpenRouter's credits page, or `GET https://openrouter.ai/api/v1/credits` with the key), not an estimate; it can lag a batch by some minutes, so read it again before reporting. OpenRouter refuses any image request when the balance is under one dollar. `paint.py` will not write over a picture that already exists (it may be an approved, paid one); `--force` replaces it.
-- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `$OPENAI_API_KEY`, `--env FILE` or `~/.config/papermorph/.env`). OpenAI does not return a price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.
+- `paint.py` reads the OpenRouter key from `~/.config/openrouter/key` or `$OPENROUTER_API_KEY`. Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`; `paint.py --total books/<book>/art/costs.tsv` sums it). Before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider (OpenRouter's credits page, or `GET https://openrouter.ai/api/v1/credits` with the key), not an estimate; it can lag a batch by some minutes, so read it again before reporting. OpenRouter refuses any image request while the balance is under one dollar. `paint.py` will not write over an existing picture (it may be an approved, paid one); `--force` replaces it.
+- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `$OPENAI_API_KEY`, `--env FILE` or `~/.config/papermorph/.env`). OpenAI returns no price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.
- After every batch, put the pictures on one contact sheet and open it for the user (Finder, the browser), even when working on your own, so the user sees each stage.
## Credits and licences
-Pictures you generate belong in the book; say which model painted them in the series page's footer. Stock or web images are a different matter: a public site redistributes the files, so only licences that allow redistribution (CC0 and the like) will do, and the look rarely matches the puppets. Painting your own is usually simpler.
+Generated pictures belong in the book; name the model that painted them in the series page's footer. Stock or web images are different: a public site redistributes the files, so only licences that allow redistribution (CC0 and the like) will do, and the look rarely matches the puppets. Painting your own is usually simpler.
diff --git a/.claude/skills/papermorph/references/picture-books/puppets.md b/.claude/skills/papermorph/references/picture-books/puppets.md
index 2b1efd3..168b0ea 100644
--- a/.claude/skills/papermorph/references/picture-books/puppets.md
+++ b/.claude/skills/papermorph/references/picture-books/puppets.md
@@ -1,8 +1,8 @@
# Paper puppets and the stop-motion look
-The actors of a picture book are paper puppets drawn in code: pieces of coloured paper pinned at the joints, moved a little each frame, like a cut-out film shot by hand. Because a pose is only a set of numbers, any action the story needs (ducking, swinging an axe, diving through a window, shoving a thought bubble) costs a few lines, never a new drawing, and a puppet looks the same in every shot. The kit is in `assets/templates/picture-book/` (`paper.js`, `cast.js`, `shared.js`, `chapter.html`); `new_book.py picture` copies it into `site/<book>/lib/` and the first episode folder.
+The actors are paper puppets drawn in code: pieces of coloured paper pinned at the joints, moved a little each frame, like a cut-out film shot by hand. A pose is only a set of numbers, so any action the story needs (ducking, swinging an axe, diving through a window, shoving a thought bubble) costs a few lines, never a new drawing, and a puppet looks the same in every shot. The kit is in `assets/templates/picture-book/` (`paper.js`, `cast.js`, `shared.js`, `chapter.html`); `new_book.py picture` copies it into `site/<book>/lib/` and the first episode folder.
-Two cast styles are on the shelf, both on the same `paper.js`: round-headed figures that face us, in the spirit of South Park (*Joke Collection*), which the kit's `cast.js` builds (add a character by copying an entry of its `SHAPES`), and jointed storybook figures seen mostly in profile (*Little Red Riding Hood*: the wolf, Grandma, the woodcutter), which a book draws itself, a side set and a front set per figure (start from that book's `lib/paper.js` and `lib/cast.js`, under `site/little-red-riding-hood/` in the Papermorph repository). Pick with the user; the first is quicker to build and to act with.
+Two cast styles are on the shelf, both on `paper.js`: round-headed figures that face us, in the spirit of South Park (*Joke Collection*), built by the kit's `cast.js` (add a character by copying an entry of its `SHAPES`); and jointed storybook figures seen mostly in profile (*Little Red Riding Hood*: the wolf, Grandma, the woodcutter), which a book draws itself, a side and a front set per figure (start from that book's `lib/paper.js` and `lib/cast.js`, under `site/little-red-riding-hood/` in the Papermorph repository). Pick with the user; the first is quicker to build and to act with.
## Contents
@@ -14,35 +14,35 @@ Two cast styles are on the shelf, both on the same `paper.js`: round-headed figu
## What makes it read as stop motion
-- **Twelve frames a second, on twos.** `stopClock` samples every movement into steps; the slight jerk is the style, not a defect. Big moves still ease in and out across those steps. It draws through the beat's 0.6 s hold after the clip too (`clockRun`'s tail: [core/engine.md](../core/engine.md#world-clock-and-camera)), so a scene's pose functions run to about `D + 0.6` and the frame the next scene cuts from is still alive.
-- **The animator's hand.** Each frame nudges every puppet by a tiny random amount (`jit(frame, k)`, the same nudge for the same frame, so pause, seek and `?beat=N&t=S` show exactly what playback shows), and the picture flickers faintly. Keep it small: at full strength it reads as shaking; a third of a pixel-ish wobble, held for two frames, felt hand-made.
+- **Twelve frames a second, on twos.** `stopClock` samples every movement into steps; the slight jerk is the style, not a defect. Big moves still ease in and out across the steps. It draws through the beat's 0.6 s hold after the clip too (`clockRun`'s tail: [core/engine.md](../core/engine.md#world-clock-and-camera)), so a scene's pose functions run to about `D + 0.6` and the frame the next scene cuts from is still alive.
+- **The animator's hand.** Each frame nudges every puppet by a tiny random amount (`jit(frame, k)`, the same nudge for the same frame, so pause, seek and `?beat=N&t=S` show exactly what playback shows), and the picture flickers faintly. At full strength it reads as shaking; about a third of a pixel, held for two frames, felt hand-made.
- **Paper you can feel.** Grain, torn edges and a soft drop shadow on every piece (the `#paper` filter), brass pins at the joints, and a soft contact shadow under the feet so a puppet stands on the ground, leaning the way the set's light falls.
-- **Replacement, not morphing.** Mouths are swapped shapes timed to the words; a blink is two closed frames; a door opens through a few boards of different widths; a bun bitten is a different picture.
+- **Replacement, not morphing.** Mouths are swapped shapes timed to the words; a blink is two closed frames; a door opens through a few boards of different widths; a bitten bun is a different picture.
## Acting
- **Nobody freezes.** Whoever speaks lip-syncs; everyone blinks at their own moments, never in unison; listeners' eyes follow the speaker; reactions get a small head turn or a lid drop. A crowd glances about on its own and turns as one only when something happens (a staggered snap, a frame or two apart).
- **Turning round.** A round-headed puppet turns by sliding its face across the head (`look`), as South Park does. A profile puppet turns as a whole-body swap: the side view squashes, the whole front figure shows for the narrowest frames, and it comes out mirrored. A front head on a side body looked wrong every time.
-- **Feet don't slide.** A walk keeps the planted foot still while the hip rides over it, and the puppet's x comes from the distance the walk returns (`d`, in the puppet's units, times its scale), never from a separate tween. A profile figure uses the compass step `walk()` (`paper.js`): `d` grows as it goes forward, so one built facing right goes `x0 + d·s` and a mirrored one `x0 − d·s`; its `near`/`far` angles go to the near and far leg as they are. A figure that faces us while it crosses the frame side-steps with `spStep()` (`cast.js`): step out, close, both legs leaning outward, `x0 ± d·s` by the direction, a step every 2/3 s by default (keep the period a whole number of 1/3 s, so a drawn frame lands on the widest stance and only one foot moves at a time; the template's `scene1.js` walks the kid in this way); `walk()`'s angles on a front figure cross the ankles every other step. `spWalk()` is the show's quick shuffle on the spot, for short moves where nobody watches the feet. Runs are on twos with a bigger bob. Check a walk on a strip at 1/12 s: the planted shoe should not move between frames.
-- **Hands touch what they hold.** A held prop belongs to the hand's piece (`hold` is the screen-right hand, on `armR`; `holdL` the screen-left one, on `armL`); when something is handed over, both hands meet it. To put a hand on a point, ask the puppet: `aim(pose, 'R', [x, y])` gives the `armR`/`reachR` values for that pose (its result spreads straight into the pose, or tween `arm` and `reach` from rest for a gesture), and `point(pose, 'mouth' | 'chin' | 'capL' | 'capR')` says where that place of the face is for the same pose, so a cup, a scratch or a chin on a hand lands where it should through a lean, a head tilt or a seat. A held thing hangs from the mitten's centre, so aim at the point less the thing's own offset (a cup's rim above the hand). A hand raised above the chin and in towards the face (a cup at the lips, a hand on the chin, a reach across the head) is drawn in front of the head; an arm raised out to the side (a wave, a cheer) stays behind it, and so does a hand at its own side of the head, so a scratch there wants `armFrontR: true` (or `armFrontL`; `false` keeps a hand behind). `far` above 1.25 means the point is out of reach: lean in, step closer or move the point. Look at a full-size still of the moment the hand arrives.
+- **Feet don't slide.** A walk keeps the planted foot still while the hip rides over it, and the puppet's x comes from the distance the walk returns (`d`, in the puppet's units, times its scale), never from a separate tween. A profile figure uses the compass step `walk()` (`paper.js`): `d` grows as it goes forward, so one built facing right goes `x0 + d·s` and a mirrored one `x0 − d·s`; its `near`/`far` angles go to the near and far leg as they are. A figure that faces us while crossing the frame side-steps with `spStep()` (`cast.js`): step out, close, both legs leaning outward, `x0 ± d·s` by direction, a step every 2/3 s by default (keep the period a whole number of 1/3 s, so a drawn frame lands on the widest stance and only one foot moves at a time; the template's `scene1.js` walks the kid this way); `walk()`'s angles on a front figure cross the ankles every other step. `spWalk()` is the show's quick shuffle on the spot, for short moves where nobody watches the feet. Runs are on twos with a bigger bob. Check a walk on a strip at 1/12 s: the planted shoe should not move between frames.
+- **Hands touch what they hold.** A held prop belongs to the hand's piece (`hold` is the screen-right hand, on `armR`; `holdL` the screen-left one, on `armL`); when something is handed over, both hands meet it. To put a hand on a point, ask the puppet: `aim(pose, 'R', [x, y])` gives the `armR`/`reachR` values for that pose (spread straight into the pose, or tween `arm` and `reach` from rest for a gesture), and `point(pose, 'mouth' | 'chin' | 'capL' | 'capR')` says where that place of the face is in the same pose, so a cup, a scratch or a chin on a hand lands right through a lean, a head tilt or a seat. A held thing hangs from the mitten's centre, so aim at the point less the thing's own offset (a cup's rim above the hand). A hand raised above the chin and in towards the face (a cup at the lips, a hand on the chin, a reach across the head) is drawn in front of the head; an arm raised out to the side (a wave, a cheer) stays behind it, and so does a hand at its own side of the head, so a scratch there wants `armFrontR: true` (or `armFrontL`; `false` keeps a hand behind). `far` above 1.25 means the point is out of reach: lean in, step closer or move the point. Look at a full-size still of the moment the hand arrives.
- **Sitting reads from the knees.** A figure that faces us looks seated only when its thighs come towards us: `sit: H` sits on a seat H units above the feet (up to the shape's `legH − 12`, 34 on the kid; a higher seat counts as that), the lap and knees towards us and the shins down to the ground at the pose's `y`. `sit: true` only hides the legs and the shadow, for a seat whose front comes up to the coat (a desk row). A still beside the standing pose should read sitting without the set.
-- **Whatever says where something is follows what is drawn.** A helper a scene asks for a position (`point()`, `aim()`, a board's square or the top of a piece the kit adds) works from the same state the drawing uses this frame, a piece being lifted or carried included, and draw order comes from the pose alone, so a seek to any frame shows what playback showed (compare a frame from playback with the same `?beat=N&t=S`).
+- **Whatever says where something is follows what is drawn.** A helper a scene asks for a position (`point()`, `aim()`, a board's square, the top of a piece the kit adds) works from the same state the drawing uses this frame, a piece being lifted or carried included, and draw order comes from the pose alone, so a seek to any frame shows what playback showed (compare a playback frame with the same `?beat=N&t=S`).
- **Things behind things.** A counter, a cart, a desk row or a lectern sits on its own layer between puppets, so the person behind shows from the chest up (`paperCam(…, { after, stages })` puts puppet layers between set layers).
## Cameras
-`paperCam(parent, set, view)` is one camera on one set: layers slide with parallax, `to`/`cut` move it on the scene's clock, `soft` swaps in the blurred copy of the set for close-ups, `shake(t0, dur, amp = 10)` jolts it (note the order: the engine's `cam.shake` takes the amplitude first), `show(layer, on)` swaps a layer (rain and snow versions of the same street). Several cameras can live in one scene; cut between places by showing one `cam.root` and hiding the others. Close-ups zoom the same set and blur it, so the speaker stays sharp.
+`paperCam(parent, set, view)` is one camera on one set: layers slide with parallax, `to`/`cut` move it on the scene's clock, `soft` swaps in the blurred copy of the set for close-ups, `shake(t0, dur, amp = 10)` jolts it (the engine's `cam.shake` takes the amplitude first), `show(layer, on)` swaps a layer (rain and snow versions of the same street). A scene can hold several cameras; cut between places by showing one `cam.root` and hiding the others. Close-ups zoom the same set and blur it, so the speaker stays sharp.
## Performance
-Paper filters are expensive live, so every finished piece is baked to a bitmap; the parts that change every frame (eyes, mouths, brows, fingers) stay live.
+Paper filters are expensive live, so every finished piece is baked to a bitmap; only what changes every frame (eyes, mouths, brows, fingers) stays live.
- Sets: `bake_sets.py` (SVG sketches) or `painted.py` (painted pictures).
-- Puppet and prop pieces: `bake_puppets.py` seeks every episode to its end, in Chromium and in Firefox, so each piece is asked for once, and writes `img/puppets/<hash>.webp` with `baked.js`.
-- In a series every episode's pieces share one folder. `bake_puppets.py` encodes only pieces it has not baked before and keeps the others; `--clean` (after changing the paper filter itself) re-encodes them all and removes only what no episode asks for any more. Leave the folder to it: a hand-written prune once deleted a published episode's pieces.
-- Rebake after changing any piece or adding an episode. A piece missing from `baked.js` is baked in the browser and costs a stall; `shot.py` says how many pieces a chapter still bakes live.
+- Puppet and prop pieces: `bake_puppets.py` seeks every episode to its end, in Chromium and Firefox, so each piece is asked for once, and writes `img/puppets/<hash>.webp` with `baked.js`.
+- A series shares one folder for every episode's pieces. `bake_puppets.py` encodes only pieces it has not baked before; `--clean` (after changing the paper filter itself) re-encodes them all and removes only what no episode asks for any more. Leave the folder to it: a hand-written prune once deleted a published episode's pieces.
+- Rebake after changing any piece or adding an episode. A piece missing from `baked.js` is baked in the browser and stalls; `shot.py` says how many pieces a chapter still bakes live.
- Full-frame effects that change every frame (the flicker) live outside the SVG, so the picture isn't redrawn each frame.
## Seeing your own work
-The preview server must not cache (`serve.py`). Look at contact sheets that advance the clock the way playback does (`strip.py chNN OUT scene1/0.5 --url http://localhost:8765/<book>/`; times are on the beat clock, so a scene's speech starts at its `pre`, and marks of a joined scene are named `clip.mark`; `scene1:2..5/0.1@o@c` is an onion skin of one shot with the camera held still, for feet and hands), at full-size frames at the key moments (`shot.py`, beats counted from 0 or named), at the last frame of each scene beside the first of the next (`shot.py --cuts`), at the sounds against the picture (`playlog.py`), and play the whole episode through once at speed ([core/review.md](../core/review.md#watch-it-in-motion) has the commands). Some faults appear only in continuous playback (a camera layer shown once and never hidden again), so don't rely on jumps with `?t=` alone.
+Use [core/review.md](../core/review.md#watch-it-in-motion)'s tools on an uncached preview (`serve.py`); here, strip times are on the beat clock, so a scene's speech starts at its `pre`, and a joined scene's marks are named `clip.mark` (`strip.py chNN OUT scene1/0.5 --url http://localhost:8765/<book>/`); `scene1:2..5/0.1@o@c` onion-skins one shot with the camera held still, for feet and hands. Look at full-size frames of the key moments (`shot.py`, beats counted from 0 or named), at each scene's last frame beside the next one's first (`shot.py --cuts`), at the sounds against the picture (`playlog.py`), and play the whole episode through once at speed: some faults appear only in continuous playback (a camera layer shown once and never hidden again), not in `?t=` jumps.
diff --git a/.claude/skills/papermorph/references/picture-books/stories.md b/.claude/skills/papermorph/references/picture-books/stories.md
index d20a9a3..975d362 100644
--- a/.claude/skills/papermorph/references/picture-books/stories.md
+++ b/.claude/skills/papermorph/references/picture-books/stories.md
@@ -1,8 +1,8 @@
# Picture books: from a story to an episode
-A picture book is a short animated film, two to four minutes, told by paper puppets in front of sets. It starts from a story rather than a textbook: a fairy tale, a joke, something that happened to the user, or a story book's PDF. The published examples are on the shelf at https://papermorph.diamonddoge.org/: *Little Red Riding Hood* (everything drawn in code) and *Joke Collection* (painted sets, puppets in code; a series of episodes).
+A picture book is a two-to-four-minute animated film of paper puppets in front of sets, made from a story: a fairy tale, a joke, something that happened to the user, or a story book's PDF. On the shelf at https://papermorph.diamonddoge.org/: *Little Red Riding Hood* (everything drawn in code) and *Joke Collection* (painted sets, puppets in code; a series of episodes).
-The craft is in three references: this one (the story, the shots, the sound and the team), [puppets.md](puppets.md) (the paper puppets and the stop-motion look) and [painting.md](painting.md) (sets and props painted by an image model). The engine, the player, previews, checks, voices and music are shared with every book ([core/sound.md](../core/sound.md), [core/review.md](../core/review.md), [core/engine.md](../core/engine.md)).
+This file covers the story, the shots, the sound and the team; [puppets.md](puppets.md) the paper puppets and the stop-motion look; [painting.md](painting.md) sets and props painted by an image model. The engine, player, checks, voices and music are shared with every book ([core/sound.md](../core/sound.md), [core/review.md](../core/review.md), [core/engine.md](../core/engine.md)).
## Contents
@@ -18,31 +18,31 @@ The craft is in three references: this one (the story, the shots, the sound and
## Intake for a story
-Ask the way [core/style.md](../core/style.md#asking) says: a light conversation, choices to click, the user's words kept verbatim. What to settle, skipping whatever the telling already settles:
+Ask as [core/style.md](../core/style.md#asking) says, skipping whatever the telling already settles:
-1. **The story itself.** Let the user tell it in their own words and keep that telling in `books/<book>/story.md` untouched. Ask what is true and must stay (a real joke has one real punchline), who the people are, where it happens, what language each person speaks.
-2. **The look** is the user's to choose; there is no house style. Paper puppets moved in code ([puppets.md](puppets.md)) are what has worked best so far, so offer them first, in two ways, and welcome any other idea the user has:
+1. **The story itself.** Let the user tell it in their own words and keep that telling untouched in `books/<book>/story.md`. Ask what is true and must stay (a real joke has one real punchline), who the people are, where it happens, what language each person speaks.
+2. **The look** is the user's choice; there is no house style. Paper puppets moved in code ([puppets.md](puppets.md)) have worked best so far, so offer them first, in two ways, and welcome any other idea:
- *Painted world, paper actors* (recommended when an image budget is fine): an image model paints the sets and everything that stays still; the puppets and anything that moves stay in code (Joke Collection, under a dollar of pictures per episode). Ask for a budget ceiling and keep to it ([painting.md](painting.md)).
- *Paper, all in code*: sets and props drawn as SVG paper too. No image cost, plainer, very consistent (Little Red Riding Hood).
3. **Language and voices**: the narration language, one voice per character ([core/sound.md](../core/sound.md#voices)).
4. **A series or one film.** A series shares cast, sets and the series page; each episode is a chapter (`chNN`).
-Then agree on the models ([core/style.md](../core/style.md#models)) and write `style.json` from [the picture-book example](../../assets/templates/picture-book/style.json): `tier: "picture"`, the user's words, the look they chose, a voice for each character, an `illustration` block (the sets, the budget, the cast with a line each), the models, and later the approved episodes. It holds this book's own choices so that its episodes match each other; another book can look entirely different. Then go on to the script.
+Then agree on the models ([core/style.md](../core/style.md#models)) and write `style.json` from [the picture-book example](../../assets/templates/picture-book/style.json): `tier: "picture"`, the user's words, the look, a voice per character, an `illustration` block (the sets, the budget, the cast with a line each), the models, and later the approved episodes. It holds this book's choices so its episodes match each other; another book can look entirely different.
## The order of work
-1. Intake (above), then the script and the storyboard, shown to the user (below).
-2. Start the folder (below).
+1. Intake, then the script and storyboard, shown to the user.
+2. Start the folder.
3. Sound: voices, mouth shapes, one joined clip per scene with its word times, sound effects ([Sound](#sound)).
-4. Sets: sketch them in `sets.js`, bake them, and if the look is painted, paint them from the baked sketches ([painting.md](painting.md)).
+4. Sets: sketch them in `sets.js`, bake them, and for a painted look paint them from the baked sketches ([painting.md](painting.md)).
5. The cast and the scenes, one script per scene ([puppets.md](puppets.md)); bake the puppet pieces.
-6. Review rounds (below), then the user's viewing, then registering the episode.
+6. Review rounds, then the user's viewing, then registering the episode.
## The book folder
`books/<book>/` holds `story.md` (the user's telling, verbatim), `storyboard.md` and `art/` (`sets.js` with the set sketches, generated pictures, `painted.json`, `costs.tsv`). `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`) beside the engine, and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`. The book's `index.html` is the series page.
-`python3 SKILL/scripts/new_book.py picture <book>` makes it ([core/publish.md](../core/publish.md#start-a-book-folder)): the series page, the kit, `ch01/` with the sample `scene1.js`, `sets.js` and `painted.json` in `books/<book>/art/` (the second is only used by a painted look), and an empty `img/puppets/baked.js` that stands in until `bake_puppets.py` has run. Then the sound and the pictures, in this order, with the preview server running on 8765:
+`python3 SKILL/scripts/new_book.py picture <book>` makes it ([core/publish.md](../core/publish.md#start-a-book-folder)): the series page, the kit, `ch01/` with the sample `scene1.js`, `sets.js` and `painted.json` in `books/<book>/art/` (the second only for a painted look), and an empty `img/puppets/baked.js` that stands in until `bake_puppets.py` has run. Then the sound and the pictures, in this order, with the preview server on 8765:
```sh
BOOK=jokes; A="site/$BOOK/ch01/audio/en"; N="content/$BOOK/ch01/narration.en.json"
@@ -53,9 +53,9 @@ python3 "$SKILL/scripts/join.py" "$A" scene1=s01,s02,s02b,s03 --words "$N"
uv run --with numpy python "$SKILL/scripts/sfx.py" "site/$BOOK/ch01/audio/sfx" knock
```
-Keep these commands in `tools/<book>/audio.sh` and rerun it after any change to the narration ([Sound](#sound)). As copied, they voice the kit's own sample episode, a check that the folder works; the episode's script then replaces the narration file, and its scenes replace the `join.py` list.
+Keep these commands in `tools/<book>/audio.sh` and rerun it after any narration change ([Sound](#sound)). As copied they voice the kit's sample episode, a check that the folder works; the episode's script then replaces the narration file, and its scenes the `join.py` list.
-The sets are baked before the scenes are written, the puppets after, since `bake_puppets.py` bakes the poses the chapters ask for; rerun either after a set or a puppet part changes. A painted look paints its sets between `bake_sets.py --ref` and the scenes ([painting.md](painting.md)).
+Sets are baked before the scenes are written, puppets after, since `bake_puppets.py` bakes the poses the chapters ask for; rerun either after a set or puppet part changes. A painted look paints its sets between `bake_sets.py --ref` and the scenes ([painting.md](painting.md)).
```sh
uv run --with playwright --with pillow python "$SKILL/scripts/bake_sets.py" "books/$BOOK/art/sets.js" "site/$BOOK"
@@ -64,68 +64,68 @@ uv run --with playwright --with pillow python "$SKILL/scripts/bake_puppets.py" "
## The script comes first
-Write the script and a storyboard table (`books/<book>/storyboard.md`: scene, shot, what we see, who says what) and show them to the user before building anything. Changing a story on paper is cheap; once every shot is animated it is expensive, and almost every real failure in these books was a story failure that no amount of animation fixed.
+Write the script and a storyboard table (`books/<book>/storyboard.md`: scene, shot, what we see, who says what) and show them to the user before building anything. A story is cheap to change on paper and expensive once animated, and almost every real failure in these books was a story failure no animation fixed.
-What made the difference, from the books:
+What made the difference:
-- **Set up everything the punchline needs.** The first cut of *Breakfast in the Bathroom* had Bo ask "Wanna go eat breakfast… in the bathroom?" out of nowhere; viewers took it literally. It became a joke once the film first showed his two everyday questions, "Breakfast?" every morning at the stall and "Bathroom?" after every class, and then the morning he overslept and came in starving.
+- **Set up everything the punchline needs.** In the first cut of *Breakfast in the Bathroom*, Bo's "Wanna go eat breakfast… in the bathroom?" came out of nowhere and viewers took it literally. It became a joke once the film first showed his two everyday questions, "Breakfast?" every morning at the stall and "Bathroom?" after every class, then the morning he overslept and came in starving.
- **Show the motive before the line.** Bo's stomach growls; a bun appears in a thought bubble; he glances at the door and a toilet appears beside it; the two bubbles shove each other and merge. Only then does he speak. The audience is ahead of him, which is where comedy happens.
-- **Every event needs a cause the audience has seen.** In *Little Red Riding Hood* the first rescue had a woodcutter from nowhere, Grandma suddenly out of the wardrobe and the wolf flying out of the window as if Grandma had superpowers. The fix was a chain: the woodcutter chopping wood near the cottage earlier, a cut to Grandma's eye in the wardrobe crack during the questions, the cry for help, Grandma's umbrella on the wolf's head, the woodcutter blocking the door, the window the only way out, and outside, the window still broken.
+- **Every event needs a cause the audience has seen.** The first rescue in *Little Red Riding Hood* had a woodcutter from nowhere, Grandma suddenly out of the wardrobe and the wolf flying out of the window as if Grandma had superpowers. The fix was a chain: the woodcutter chopping wood near the cottage earlier, a cut to Grandma's eye in the wardrobe crack during the questions, the cry for help, Grandma's umbrella on the wolf's head, the woodcutter blocking the door, the window the only way out, and outside, the window still broken.
- **The audience understands what the characters don't.** In *Do You Need a Bag?* the clerk speaks only Japanese and the customer only English: each line is spoken in its own language with subtitles, and a thought bubble shows the mishearing ("…REJI…?" turning into "VEGGIE?"), so the joke works for viewers who speak neither.
-- **Keep the user's story.** Tighten the wording, add the small connecting moments a film needs, and list every addition for the user; don't swap their joke for a different one.
+- **Keep the user's story.** Tighten the wording, add the small connecting moments a film needs, and list every addition for the user; don't swap their joke for another.
## Scenes, shots, cuts
-One scene is one beat, with one joined audio clip ([Sound](#sound)); cuts inside a scene are timed to its clock. Plan shots the way a film does, because a fixed wide frame for a whole scene plays like a slideshow:
+One scene is one beat with one joined audio clip ([Sound](#sound)); cuts inside a scene are timed to its clock. Plan shots as a film does, because a fixed wide frame for a whole scene plays like a slideshow:
- a wide shot to say where we are, two-shots for conversations, a close-up for whoever speaks, closer and closer as tension rises (the three questions to "Grandma");
- reverse angles: whoever is in close-up has behind them what the other person sees (a separate camera on a matching set, not a zoom of the same one);
- an insert to make a detail readable (a coin on the counter, the clock, a face in a door crack);
- held silences: the beat where nobody speaks is often the joke. Blinks, eyes and a tiny head turn carry it.
-Reviewers of the later episodes kept finding the same few things, all about what the viewer can read. Give every object the joke hangs on an insert of its own; the best episodes ran ten to fourteen shots a half minute. Keep whoever is being spoken to in the shot, since the listener's face is half of the line. Someone following stays far enough behind that the delay itself reads; people pass in front of or behind each other, never through. A face half cut by the frame edge, or a blink on the frame that carries the joke, reads as a mistake.
+Reviewers of the later episodes kept finding the same few things, all about what the viewer can read. Give every object the joke hangs on its own insert; the best episodes ran ten to fourteen shots a half minute. Keep whoever is spoken to in the shot: the listener's face is half the line. Someone following stays far enough behind that the delay itself reads; people pass in front of or behind each other, never through. A face half cut by the frame edge, or a blink on the frame that carries the joke, reads as a mistake.
-Everybody in the shot stays alive and stays there: extras blink and glance about in close-ups too (in an early cut the whole class vanished whenever someone spoke). Between places, cut or use a paper-theatre wipe; at the end, a title card.
+Everybody in the shot stays alive and stays there: extras blink and glance about in close-ups too (an early cut lost the whole class whenever someone spoke). Between places, cut or use a paper-theatre wipe; at the end, a title card.
## Sound
-Voices, levels, effects and music work as in [core/sound.md](../core/sound.md); what a picture book adds is a cast that speaks on screen and one clip per scene.
+Voices, levels, effects and music work as in [core/sound.md](../core/sound.md); a picture book adds a cast that speaks on screen and one clip per scene.
-- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes (a Chinese or Japanese line opens and shuts once per character), and `lips(q, scene, pre, line…)` picks the shape for the frame. Edge's word times run about a tenth of a second ahead of the sound; `mouths.py` and `join.py` move mouths and captions that much later and shut the mouth where the clip's sound stops, so a lip flap that leads or trails the voice is worth reporting.
-- **One clip per scene.** `join.py` joins a scene's lines into one audio clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line, after a word's sound has ended rather than where the next word begins) or after the last line (`name:S`, a stare or a tag). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. `--words` writes every word's time in the scene clip beside the narration; scene authors time actions against it (the beat clock adds the scene's `pre`).
-- **One script for the whole sound**, `tools/<book>/audio.sh`, rerun after any change: lines replaced by hand, `mouths.py`, level fixes, `join.py` with its holes, any caption edits. Join arguments typed only in a terminal have had to be read back out of `shots.js`.
-- **Levels.** `level.py` goes in the script right after `tts.py` and before `join.py`, at its default −18 LUFS ([core/sound.md](../core/sound.md#levels)). The line the joke hangs on must not be the quietest; a line that must sit above the rest (a quiet old man's punchline) gets its own target (`level.py o1.mp3 --lufs -15`) and stays out of the others' list.
-- **Sounds a voice makes.** Animal voices that speak (a dog's "Woof!") came out best from an Edge voice shouting the word, trimmed and normalized; synthesized barks lost to them. A whispered "Shh." is shaped pink noise, not Edge's voiced "shh-uh". Write such a clip over the line's MP3 and set its `dur` in `timings.js` before joining.
-- **Effects and music** are placed on the scene clock (`sfx(scene, t, …)`, `music(…, [scene ids], …)`); a bed that loops overlaps its seams by about half a second. Give a scene silence when silence is the joke: `window.MUSIC_OFF = { scene: t => … }` fades the music out for a stare.
-- **Captions** are on at a reader's first visit (`chapter.html` does this); the reader's own choice is remembered after that. A caption ends at the first real pause after its words; a hole inside a sentence keeps it up. When that gives away words before they are said (a punchline after a pause), split the caption at the hole in `shots.js`, and hold a punchline's caption into the silence after it; do this in the audio script after `join.py`, so a rerun keeps it.
+- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes (a Chinese or Japanese line opens and shuts once per character), and `lips(q, scene, pre, line…)` picks the frame's shape. Edge's word times run about a tenth of a second ahead of the sound; `mouths.py` and `join.py` move mouths and captions that much later and shut the mouth where the clip's sound stops, so a lip flap that leads or trails the voice is worth reporting.
+- **One clip per scene.** `join.py` joins a scene's lines into one clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line, after a word's sound has ended rather than where the next word begins) or after the last line (`name:S`, a stare or a tag). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. `--words` writes every word's time in the scene clip beside the narration, for scene authors to time actions against (the beat clock adds the scene's `pre`).
+- **One script for the whole sound**, `tools/<book>/audio.sh`, rerun after any change: lines replaced by hand, `mouths.py`, level fixes, `join.py` with its holes, caption edits. Join arguments typed only in a terminal have had to be read back out of `shots.js`.
+- **Levels.** `level.py` runs right after `tts.py` and before `join.py`, at its default −18 LUFS ([core/sound.md](../core/sound.md#levels)). The line the joke hangs on must not be the quietest; one that must sit above the rest (a quiet old man's punchline) gets its own target (`level.py o1.mp3 --lufs -15`) and stays out of the others' list.
+- **Sounds a voice makes.** A speaking animal (a dog's "Woof!") came out best as an Edge voice shouting the word, trimmed and normalized; synthesized barks lost to it. A whispered "Shh." is shaped pink noise, not Edge's voiced "shh-uh". Write such a clip over the line's MP3 and set its `dur` in `timings.js` before joining.
+- **Effects and music** go on the scene clock (`sfx(scene, t, …)`, `music(…, [scene ids], …)`). When silence is the joke, `window.MUSIC_OFF = { scene: t => … }` fades the music out for the stare.
+- **Captions** are on at a reader's first visit (`chapter.html` does this); after that the reader's own choice is remembered. A caption ends at the first real pause after its words; a hole inside a sentence keeps it up. When that gives words away before they are said (a punchline after a pause), split the caption at the hole in `shots.js` and hold a punchline's caption into the silence after it; do it in the audio script after `join.py`, so a rerun keeps it.
## Team
-The shape of [core/team.md](../core/team.md), split by scene instead of by step. The **strong** coordinator writes the script with the user and builds what every scene shares: cast, sets and their painting, the episode's helpers, the voices and the joined audio with its word times (`join.py --words`). Then it writes one brief for all scene workers:
+[core/team.md](../core/team.md)'s shape, split by scene instead of by step. The **strong** coordinator writes the script with the user and builds what every scene shares: cast, sets and their painting, the episode's helpers, the voices and the joined audio with its word times (`join.py --words`). Then it writes one brief for all scene workers:
- the story in a paragraph, and the user's words that set the bar;
- the episode kit's API, to read and not edit;
- each scene's `pre`, its holes and the word times to cut on;
- continuity: who stands where, facing whom, in the first and last frame of every scene, so the cuts match;
-- where things are: each set's places for puppets and props, its camera ranges, what comes into view on each pan. A painted set lands some way off its sketch (a bench seat about 30 px), so measure the places on frames of the painted set (`shot.py … --clean` gives the stage alone) and check the table on frames of every set before sending the brief out (a puppet at each place, the camera at each end of its range): a table written from the sketches once put an ear off frame and feet below the ground, and five workers built on it;
+- where things are: each set's places for puppets and props, its camera ranges, what each pan brings into view. A painted set lands some way off its sketch (a bench seat about 30 px), so measure the places on frames of the painted set (`shot.py … --clean` gives the stage alone) and check the table on frames of every set before sending the brief (a puppet at each place, the camera at each end of its range): a table written from the sketches once put an ear off frame and feet below the ground, and five workers built on it;
- the style, the effects available, how to look at one's own work, and the reply (the shots with their times, the first and last frame, what each check showed).
-One **middle** worker per scene, in parallel, writes only its own `sceneN.js`; a **small** worker synthesizes the sound effects from recipes. Before replying, a scene worker runs and reports on these, each with the book's `--url` (the screenshot scripts run with reduced motion, so the workers' browsers can run at once): a strip of its scene, with time ranges and `@o@c` for walks and hands ([core/review.md](../core/review.md#watch-it-in-motion)); full-size `shot.py` frames of its close-ups and of each moment a hand arrives; `shot.py --cuts sceneN` for its cuts in and out; `playlog.py --from sceneN --to sceneN`, since it cannot listen: is each effect on the frame it belongs to, each line on a moving mouth; and `still.py chNN sceneN`, saying which still stretches are meant.
+One **middle** worker per scene, in parallel, writes only its own `sceneN.js`; a **small** worker synthesizes the sound effects from recipes. Before replying, a scene worker runs and reports on these, each with the book's `--url` (the screenshot scripts run with reduced motion, so the workers' browsers can run at once): a strip of its scene, with time ranges and `@o@c` for walks and hands ([core/review.md](../core/review.md#watch-it-in-motion)); full-size `shot.py` frames of its close-ups and of each moment a hand arrives; `shot.py --cuts sceneN` for its cuts in and out; `playlog.py --from sceneN --to sceneN`, since it cannot listen: is each effect on its frame, each line on a moving mouth; and `still.py chNN sceneN`, saying which still stretches are meant.
-Reviewers, in the rounds below: four report-only, a director (**strong**) for story, comedy, staging and shots; two picture reviewers (**middle**) splitting the scenes; one (**middle**) for sound and runtime. The coordinator merges their reports ([core/review.md](../core/review.md#review-rounds)), fixes the kit itself and sends scenes back to their workers. A fresh session as coordinator matters even more here: contact sheets are large, and an episode made in one long conversation spent most of its 22 million tokens rereading them.
+Four reviewers, report-only, in the rounds below: a **strong** director for story, comedy, staging and shots; two **middle** picture reviewers splitting the scenes; one **middle** for sound and runtime. The coordinator merges their reports ([core/review.md](../core/review.md#review-rounds)), fixes the kit itself and sends scenes back to their workers. A fresh coordinator session matters even more here: contact sheets are large, and an episode made in one long conversation spent most of its 22 million tokens rereading them.
## Review rounds
-A first cut made in one pass looks like a first cut. What lifts an episode is watching it the way a director would, against the episodes the user already approved, and sending scenes back ([core/review.md](../core/review.md#review-rounds) has how rounds run).
+A first cut made in one pass looks like one. What lifts an episode is watching it as a director would, against the episodes the user already approved, and sending scenes back ([core/review.md](../core/review.md#review-rounds) has how rounds run).
-- **Director's view**: contact sheets of the whole episode and its cut sheet (`shot.py --cuts`) beside an approved one (a series' first episode: beside its storyboard). Look for story-level causes, not glitches: is every object the joke hangs on given its own shot, is the cause shown before the payoff, are the reactions framed so they read, is the shot density close to the approved episodes', does a silence stay silent? Write a restaging for each scene that needs one: which shots, from where, on which word.
+- **Director's view**: contact sheets of the whole episode and its cut sheet (`shot.py --cuts`) beside an approved one (a series' first episode: beside its storyboard). Look for story-level causes, not glitches: does every object the joke hangs on get its own shot, is the cause shown before the payoff, are the reactions framed so they read, is the shot density close to the approved episodes', does a silence stay silent? Write a restaging for each scene that needs one: which shots, from where, on which word.
- **Picture and sound**: frame by frame for faces cut by the edge, popping poses, puppets passing through each other; sound for lines cut short, effects out of step, music over a silence.
- Restage the scenes from those notes, then look again; two rounds usually settle it.
-Alone, do the same rounds yourself, one viewpoint at a time, writing each review down before changing anything.
+Alone, run the same rounds yourself, one viewpoint at a time, writing each review down before changing anything.
## Delivering
The episode is a first cut for the user's viewing, not a finished film. Deliver its URL with what was made, the final script, the decisions the user should review (every line or moment you added), known problems, and the real cost of pictures. Once the user approves it, add it to `approved` in `style.json` and to the series page, and set the previous episode's `CHAPTER.next`: when an episode's last scene ends, the player marks it watched and offers the next one.
-The series page is the book's `index.html`, made from [series.html](../../assets/templates/picture-book/series.html): one card per episode with a still, its title and a line, and a mark on episodes already watched. A still is one frame of the episode saved as a 1400×788 WebP: `shot.py chNN --out books/<book>/review/stills sceneN:S --webp 1400 --name still-chNN --url http://localhost:8765/<book>/` writes it without the player's controls (beside a full-size PNG); copy the WebP to `site/<book>/img/`. The page's header shows `img/cover.webp`, a still too: the first episode's, or a frame the user picks, until the series has a picture of its own.
+The series page is the book's `index.html`, made from [series.html](../../assets/templates/picture-book/series.html): one card per episode with a still, its title and a line, and a mark on episodes already watched. A still is one frame saved as a 1400×788 WebP: `shot.py chNN --out books/<book>/review/stills sceneN:S --webp 1400 --name still-chNN --url http://localhost:8765/<book>/` writes it without the player's controls (beside a full-size PNG); copy the WebP to `site/<book>/img/`. The page's header shows `img/cover.webp`, a still too: the first episode's, or a frame the user picks, until the series has a picture of its own.