An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
docs(skill): engine v2.6 in engine.md and documentary.md
yzraa8d35181ad7
diff --git a/.claude/skills/papermorph/references/documentary.md b/.claude/skills/papermorph/references/documentary.mdindex d003713..0fd29bd 100644--- a/.claude/skills/papermorph/references/documentary.md+++ b/.claude/skills/papermorph/references/documentary.md@@ -65,7 +65,7 @@ What made the Foucault film work: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, and the help leaves out the question keys ([engine.md](engine.md#player)).+- `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 in *Shooting an Elephant*) *(v2.6)* ([engine.md](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()` *(v2.4.1)*, 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.diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.mdindex ad70534..91fed79 100644--- a/.claude/skills/papermorph/references/engine.md+++ b/.claude/skills/papermorph/references/engine.md@@ -62,7 +62,7 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accen- `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.- 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; 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](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 *(v2.4.1)*; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.+- 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 *(v2.6)*: hold a picture longer with a plain run, `prog(() => {}, 0, D + 1)`); 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](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 *(v2.4.1)*; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.- **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` *(v2.2)* 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.- **`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.@@ -74,7 +74,7 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accenFor 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.-- `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 })` *(v2.1; an older engine ignores `tail`, so the hold stands still)* 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, plus `HOLD`): use it where motion must never freeze (a film, whose next scene cuts in), and let `f` pose sensibly past `D`. A camera in a beat with a tailed `clockRun` runs on to `P.end` too, so a follow shot keeps up. Write positions as functions of `t` (`x = x0 + v * t`) and share them between objects and the camera; never accumulate per-frame state.+- `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 })` *(v2.1; an older engine ignores `tail`, so the hold stands still)* 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 *(v2.6)*): 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)` *(v2.6)*, 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).- Moves, all on the beat clock: `cam.to({x, y, z, r}, t0, dur = 1, ease = soft)` blends only the keys given, from wherever the camera is at `t0`; `cam.cut(view, t0)` is a hard cut (`dur` 0); `cam.shake(amp, t0, dur, hz = 7)` is a subtle, repeatable shake (fades in and out over 0.3 s). Any key may be a function of `t`: that is a follow shot (`cam.to({ x: t => carX(t) }, 2, 1.5)` locks on over 1.5 s; `r: t => spin(t)` rolls with a rotating object). Zoom changes evenly (log scale) and keeps one world point fixed when start and end allow it.- Parallax: `cam.layer(k, wrap)` returns a group inside the world that moves at `k` × the camera's pan (`k` < 1 far, > 1 near; zoom and roll are not scaled per layer). With `wrap = W` the layer's content repeats every `W` world px: draw one period plus the widest view, and the camera can pan any distance. Keep repeating details (dashes, tiles, trees) on a period that divides `W`, and move followed objects by multiples of `W` when they loop, so the loop is invisible.@@ -89,7 +89,7 @@ Firefox repaints SVG on the main thread and is the slowest common browser for th- 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).-- Write per-frame attributes and text only when they change (`render()` already skips unchanged transform and opacity). Old panels are set to `display: none` after their fade.+- Write per-frame attributes and text only when they change (`render()` already skips unchanged transform and opacity). A panel replaced at the start of a beat leaves the page after its fade, and at once while seeking *(v2.6)*; one replaced later in a beat is set to `display: none`. A removed node measures as nothing (`getBBox`, `getComputedTextLength` give 0, `getSubStringLength` throws) and its ids no longer resolve (`url(#…)`, `<use href>`): keep what a later beat measures or refers to outside a panel.- Pixel-art sprites: draw `<image>` with `style="image-rendering: pixelated"` at an integer scale, and pre-scale the file (nearest neighbour) so it stays crisp where the style is ignored.- 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`.@@ -112,9 +112,9 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'## Player-Space play/pause, and once the chapter has ended replay *(v2.1)*, ←/→ 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 *(v2.4.2)*; a line in another language with a `sub` (`tts.py`, `eleven.py`) shows its subtitle even with captions off *(v2.4.1)*, `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen *(v2.5)*: 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. 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 *(v2.3.1; an older engine stops at the end of the beat until the tab is shown again)*. `?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.+Space play/pause, and once the chapter has ended replay *(v2.1)*, ←/→ 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 *(v2.4.2)*; a line in another language with a `sub` (`tts.py`, `eleven.py`) shows its subtitle even with captions off *(v2.4.1)*, `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen *(v2.5)*: 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 *(v2.6)*). 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 *(v2.3.1; an older engine stops at the end of the beat until the tab is shown again)*. `?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** *(v2.2)*, in films only: in a chapter with a question, `sfx()` and `music()` are silent, unless the chapter sets `CHAPTER.film = true` *(v2.3)*: 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); 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). 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 *(v2.4)*. 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 *(v2.4.1)*. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.+**Sound effects and music** *(v2.2)*, in films only: in a chapter with a question, `sfx()` and `music()` are silent, unless the chapter sets `CHAPTER.film = true` *(v2.3)*: 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 *(v2.6)*; 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). 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 *(v2.4)*. 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 *(v2.4.1)*. `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.