An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
feat(engine): v2.4, the upright stage, music kept in time, frameStep
yzrf6c3199b39e8
diff --git a/.claude/skills/papermorph/assets/templates/documentary/style.json b/.claude/skills/papermorph/assets/templates/documentary/style.jsonindex 35f2a45..786a09d 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.1" },+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4" },"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 7df55dc..77a02bd 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.1" },+ "engine": { "source": "DozenTwelve/Papermorph", "ref": "engine-v2.4" },"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 72fb791..3790002 100644--- a/.claude/skills/papermorph/references/engine.md+++ b/.claude/skills/papermorph/references/engine.md@@ -2,14 +2,14 @@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.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.+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.4`; `@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.4`; what an older copy lacks is marked *(v2.1)*, *(v2.2)*, *(v2.3)* or *(v2.4)*, 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.## Stage and state- 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** *(portrait)*. `<html data-stage="portrait">` turns the stage to 900 × 1600 for a phone feed ([shorts.md](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.+- **Upright stage** *(v2.4)*. `<html data-stage="portrait">` turns the stage to 900 × 1600 for a phone feed ([shorts.md](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`.- `S` holds objects shared across beats (`S.panel`, `S.line`, …). `reset()` clears it, so anything a later beat needs must be stored on `S`.diff --git a/.claude/skills/papermorph/scripts/engine.py b/.claude/skills/papermorph/scripts/engine.pyindex 9b7937b..0060c3c 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 75cb290..25812cc 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.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.+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.4`. 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 export