An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
fix(engine): v2.3.1, a hidden tab plays on from beat to beat
DozenTwelvea0774c97a670
diff --git a/.claude/skills/papermorph/assets/templates/documentary/style.json b/.claude/skills/papermorph/assets/templates/documentary/style.jsonindex c6cc3fc..35f2a45 100644--- a/.claude/skills/papermorph/assets/templates/documentary/style.json+++ b/.claude/skills/papermorph/assets/templates/documentary/style.json@@ -15,7 +15,7 @@"voice": { "engine": "edge", "voice": "en-GB-RyanNeural", "rate": "-4%" },"music": "public-domain classical recordings, one per part of the film, changing at the turns","pacing": { "minutes": 10, "turns": "one argument with five or six turns; one idea or picture every two to four seconds" },- "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.3" },+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.3.1" },"models": { "script": "claude-opus-5-5", "pictures": "claude-sonnet-5-5", "beats": "claude-sonnet-5-5", "checks": "claude-haiku-5-5", "director": "claude-opus-5-5" },"approved": [{ "chapter": "ch01", "why": "close-ups on what is named; few words on screen" }]}diff --git a/.claude/skills/papermorph/assets/templates/style.json b/.claude/skills/papermorph/assets/templates/style.jsonindex c4eb7a0..7df55dc 100644--- a/.claude/skills/papermorph/assets/templates/style.json+++ b/.claude/skills/papermorph/assets/templates/style.json@@ -14,7 +14,7 @@},"voice": { "engine": "edge", "voice": "en-US-AndrewNeural", "rate": "-4%" },"pacing": { "minutes": [6, 10], "checks": "one or two quick checks inside the lesson, practice at the end" },- "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.3" },+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.3.1" },"models": { "extract": "claude-haiku-5-5", "narration": "claude-sonnet-5-5", "picture": "claude-opus-5-5", "checks": "claude-haiku-5-5", "review": "claude-sonnet-5-5", "rework": "claude-opus-5-5", "register": "claude-haiku-5-5" },"scenes": {"art": "pixel scenes on a dark board, characters about a third of the stage tall",diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.mdindex de41248..f536e58 100644--- a/.claude/skills/papermorph/references/engine.md+++ b/.claude/skills/papermorph/references/engine.md@@ -2,7 +2,7 @@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.-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.3`; `@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.3`; what an older copy lacks is marked *(v2.1)*, *(v2.2)* or *(v2.3)*, and syncing the book brings it. 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: 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.3.1`; `@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.3.1`; what an older copy lacks is marked *(v2.1)*, *(v2.2)* or *(v2.3)*, and syncing the book brings it. 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.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](assets.md)) rather than into the engine copy.@@ -107,7 +107,7 @@ 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), `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen, ? 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`. `?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), `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen, ? 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.**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, joined part-way, 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. 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. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.diff --git a/.claude/skills/papermorph/scripts/engine.py b/.claude/skills/papermorph/scripts/engine.pyindex 15c36ba..9b7937b 100644--- a/.claude/skills/papermorph/scripts/engine.py+++ b/.claude/skills/papermorph/scripts/engine.py@@ -20,7 +20,7 @@ with lib/mathjax.js keeps it in step like the rest.import argparse, filecmp, io, shutil, sys, tarfile, tempfile, urllib.requestfrom pathlib import Path-DEFAULT = 'DozenTwelve/[email protected]' # follows the latest compatible release+DEFAULT = 'DozenTwelve/[email protected]' # follows the latest compatible releaseOWN = 'book.css'LATEX = {'vendor/mathjax/tex-svg-full.js': 'mathjax.js', 'vendor/mathjax/LICENSE': 'mathjax-LICENSE.txt'}diff --git a/README.md b/README.mdindex 182bac4..75cb290 100644--- a/README.md+++ b/README.md@@ -77,7 +77,7 @@ python3 .claude/skills/papermorph/scripts/engine.py sitepython3 .claude/skills/papermorph/scripts/engine.py site --from you/your-fork@main```-Engine versions are tags (`engine-v2`, `engine-v2.1`, …); a new major number means a book may need a change, described in its [release notes](https://github.com/DozenTwelve/Papermorph/releases). Outside this repository, `engine.py` syncs from the latest compatible release, now `engine-v2.3`. Since `engine-v2` the maths helpers (number lines, tiles, planes, the number-set diagram) are in `lib/math.js`: a chapter that uses them loads `../lib/math.js` right after `engine.js`, and `lint.py` names the chapters that need it. `--from DozenTwelve/Papermorph@engine-v1` keeps the earlier engine.+Engine versions are tags (`engine-v2`, `engine-v2.1`, …); a new major number means a book may need a change, described in its [release notes](https://github.com/DozenTwelve/Papermorph/releases). Outside this repository, `engine.py` syncs from the latest compatible release, now `engine-v2.3.1`. Since `engine-v2` the maths helpers (number lines, tiles, planes, the number-set diagram) are in `lib/math.js`: a chapter that uses them loads `../lib/math.js` right after `engine.js`, and `lint.py` names the chapters that need it. `--from DozenTwelve/Papermorph@engine-v1` keeps the earlier engine.## Video and LMS exportdiff --git a/engine/engine.js b/engine/engine.jsindex bdd729c..4d3817c 100644--- a/engine/engine.js+++ b/engine/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/elementary-algebra/lib/engine.js b/site/elementary-algebra/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/elementary-algebra/lib/engine.js+++ b/site/elementary-algebra/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/joke-collection/lib/engine.js b/site/joke-collection/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/joke-collection/lib/engine.js+++ b/site/joke-collection/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/little-red-riding-hood/lib/engine.js b/site/little-red-riding-hood/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/little-red-riding-hood/lib/engine.js+++ b/site/little-red-riding-hood/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/madness/lib/engine.js b/site/madness/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/madness/lib/engine.js+++ b/site/madness/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/math-notebook/lib/engine.js b/site/math-notebook/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/math-notebook/lib/engine.js+++ b/site/math-notebook/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/physics-notebook/lib/engine.js b/site/physics-notebook/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/physics-notebook/lib/engine.js+++ b/site/physics-notebook/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/science/lib/engine.js b/site/science/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/science/lib/engine.js+++ b/site/science/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/shooting-an-elephant/lib/engine.js b/site/shooting-an-elephant/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/shooting-an-elephant/lib/engine.js+++ b/site/shooting-an-elephant/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {diff --git a/site/three-little-pigs/lib/engine.js b/site/three-little-pigs/lib/engine.jsindex bdd729c..4d3817c 100644--- a/site/three-little-pigs/lib/engine.js+++ b/site/three-little-pigs/lib/engine.js@@ -1438,7 +1438,14 @@ function filmDone() {}let last = performance.now();function frame(now) {- const dt = Math.min(.1, (now - last) / 1000);+ step(now, .1);+ requestAnimationFrame(frame);+}+// A hidden tab gets no animation frames: a timer keeps the film going, so a beat that ends there still starts the next+// one (a tab playing sound keeps its timers). Its ticks come late, so they may move the clock further at once.+setInterval(() => { if (document.hidden) step(performance.now(), 1.5); }, 250);+function step(now, most) {+ const dt = Math.min(most, Math.max(0, now - last) / 1000);last = now;clock += dt;if (FX.length) { evalTo(clock, FX); FX = FX.filter(w => !w.done); }@@ -1459,7 +1466,6 @@ function frame(now) {soundTick(dt);syncLinks();ui();- requestAnimationFrame(frame);}let segs = [];function buildSegs() {