An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
feat(skill): add team workflow, still-frame check and display numbering docs
yzr86e43320e76a
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.mdindex 8cbb163..fecff1e 100644--- a/.claude/skills/papermorph/SKILL.md+++ b/.claude/skills/papermorph/SKILL.md@@ -7,7 +7,7 @@ description: Make or edit animated, narrated, interactive web books from referenEach chapter is a short animated lesson film: the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture. Good means **alive** (things act and change with weight and timing), **composed** (each moment reads as one picture, text beside what it names), **true** (motion, labels and numbers agree at every moment) and **smooth** (it plays without stutter, Firefox included). Technically a chapter is one 1600×900 SVG stage plus a player; **beats** pair narration clips with timed actions.-What the picture should be depends on the book and on the user, so the work starts with a conversation ([intake.md](references/intake.md)) that ends in `style.json`, the book's agreed style. Every chapter is made against it. `style.json` fixes the atoms (palette and meanings, fonts, voice, cast, shared components, approved chapters); composition stays free, so how each beat is laid out and choreographed is yours to judge against it and the approved chapters. Then read the reference for the technique in use: [diagrams.md](references/diagrams.md) (symbols and diagrams that change), [scenes.md](references/scenes.md) (illustrated scenes, actors, camera), [assets.md](references/assets.md) (shared components, images, sprites), [authoring.md](references/authoring.md) (chapter shape, narration, questions), [engine.md](references/engine.md), [review.md](references/review.md), [site.md](references/site.md).+What the picture should be depends on the book and on the user, so the work starts with a conversation ([intake.md](references/intake.md)) that ends in `style.json`, the book's agreed style. Every chapter is made against it. `style.json` fixes the atoms (palette and meanings, fonts, voice, cast, shared components, approved chapters); composition stays free, so how each beat is laid out and choreographed is yours to judge against it and the approved chapters. Then read the reference for the technique in use: [diagrams.md](references/diagrams.md) (symbols and diagrams that change), [scenes.md](references/scenes.md) (illustrated scenes, actors, camera), [assets.md](references/assets.md) (shared components, images, sprites), [authoring.md](references/authoring.md) (chapter shape, narration, questions), [engine.md](references/engine.md), [review.md](references/review.md), [site.md](references/site.md), [team.md](references/team.md) (making chapters with subagents).Follow the pipeline forward, entering at the requested stage for existing work. User requests override defaults. Re-create explanations, examples and drawings; keep source PDFs, page images and extracted text outside the static output folder and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`). Deliver a self-contained book folder with a cover, contents, chapters and local preview instructions.@@ -56,7 +56,7 @@ Start with intake whenever `books/<book>/style.json` does not exist yet; reuse a## Context-- Keep intake and the pilot in the main conversation. Afterwards, use one fresh subagent per chapter sequentially when available; otherwise run the same loop in the current agent with file-based state.-- 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. A brief adds the chapter number, its pages and any current user request. The worker returns files, delivery result, errata and new elements or decisions in a few lines; the coordinator registers it.+- Keep intake and the pilot in the main conversation. Afterwards, when subagents are available, coordinate each chapter as a team: a fresh worker per step of the chapter loop, each on the cheapest model that does that step well, chapters one after another ([team.md](references/team.md)). Without subagents, run the same loop in the current agent with file-based state.+- 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. A brief adds the chapter, its pages, the step's inputs and outputs and any current user request. Workers reply in a few lines; the coordinator registers the chapter.- Read only the reference needed for the current step. Use the engine API and inspect individual functions when needed; copy assets rather than reading their full source as instructions.- Keep `style.json` current and short. Chapter status, errata and historical feedback stay in `chapters.md` and `chapters/chNN.md`.diff --git a/.claude/skills/papermorph/references/review.md b/.claude/skills/papermorph/references/review.mdindex ffd8be2..3380fc7 100644--- a/.claude/skills/papermorph/references/review.md+++ b/.claude/skills/papermorph/references/review.md@@ -10,6 +10,8 @@ uv run --with playwright --with pillow --with numpy SKILL/scripts/strip.py chNNA strip shows one beat at small steps; `@w` adds a motion WebP; `@o` adds an onion skin, the same frames laid over each other in one picture, later ones stronger, so spacing reads at a glance: even gaps are even speed, bunched ghosts are easing in or out, a ghost that jumps is a pop. Look at each action as a viewer would: do actors perform what the narration says, do props stay on the hands, does the camera move with purpose, does each frame still match the storyboard, do arrows, labels and readouts agree with the motion? Then watch a few beats live in Firefox with sound, which is how the user watches.+Watch every beat to its end, question cards included; 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. Some holds are right (a moment to read a result); a wave, a ray of light or an actor that stands for something in motion should be moving whenever it is on screen, because the motion is what it explains.+## 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, before the passes below.diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.mdindex d0df459..fe51d82 100644--- a/.claude/skills/papermorph/references/site.md+++ b/.claude/skills/papermorph/references/site.md@@ -35,7 +35,7 @@ A chapter returns to its book's index. Preserve cover → contents → chapter nOne page: no hash or `#book` shows the cover, `#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.- 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`). `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; also set the previous chapter's `CHAPTER.next = '../chNN/'`. An optional third entry `{ unit, chapter, sample: true }` renumbers a unit and marks it as a sample, left out of the chapter count.+- The page's script calls `Contents.book({ start, units, hues })` (from the engine's `lib/contents.js`; the shared styles are `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; also set the previous chapter's `CHAPTER.next = '../chNN/'`. An optional third entry `{ unit, chapter, sample: true }` renumbers a unit and marks it as a sample, left out of the chapter count. To show different numbers than the folders, add `label` to `start` (`{ unit: 1, chapter: 9, label: 1 }` shows ch09 as 1) and set the same `CHAPTER.label` in each lesson, which its title screen and completion card show. 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 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.diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.mdnew file mode 100644index 0000000..c035cfd--- /dev/null+++ b/.claude/skills/papermorph/references/team.md@@ -0,0 +1,28 @@+# Making a chapter with a team of models++After the pilot, a chapter can be made by a coordinator handing each step of the chapter loop to a fresh subagent on the model that suits it. The chapter must reach the same bar as the book's approved chapters, in the same look (`style.json`), so it sits on the shelf beside them as one book.++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.++Models below are named by tier: **small** (fast and cheap; Haiku today), **middle** (Sonnet today), **strong** (Opus today). Pass the tier's current model to the subagent.++## The coordinator++You read SKILL.md and this file, look at the storyboard sheet 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. A fresh session is the best coordinator: a long conversation rereads its whole history at every step.++Start each worker in the background with a short brief: the chapter and its pages, what to read, what to write, what not to touch, the preview URL (start one server for everyone), and a reply of a few lines. Workers don't commit. Pass work on as soon as a step returns.++## Steps++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.+4. **Checks — small, report-only**, in parallel with 5: lint, `check_blank.py`, `overlap.py`, `still.py`, `perf.py` in Firefox, and an e2e test adapted from the previous chapter's, 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 as [review.md](review.md) describes, 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.+7. **Register — small.** Give it the exact edits: the contents entry, the previous chapter's `CHAPTER.next`, cover or shelf counts, `chapters.md` and the status line in chNN.md. Then lint and e2e.++## Before delivering++Check the reports against each other (an odd claim is worth one look at the file), confirm lint and e2e pass, and deliver the chapter URL with `?review`. If the user wants the cost, it is in the subagent transcripts (`subagents/agent-<id>.jsonl` under the session's folder in `~/.claude/projects/`: usage per assistant message, each message id counted once) plus your own session's usage.diff --git a/.claude/skills/papermorph/scripts/still.py b/.claude/skills/papermorph/scripts/still.pynew file mode 100644index 0000000..7ccf158--- /dev/null+++ b/.claude/skills/papermorph/scripts/still.py@@ -0,0 +1,48 @@+#!/usr/bin/env python3+"""Stretches where a lesson beat's stage does not move: seeks each beat every STEP seconds and compares frames.++ uv run --with playwright --with pillow still.py ch15 --url http://localhost:8765/science/ [beat ...] [--min 3]++Prints, per lesson beat, the stretches of at least --min seconds whose consecutive frames differ by less than+--thr (mean absolute pixel difference, 0-255, on a small grey copy of the stage). Strips and onion skins cannot+show that nothing moves; this can. A stretch is worth a look, not automatically wrong: a held moment can be right.+"""+import argparse, asyncio, io+from playwright.async_api import async_playwright+from PIL import Image, ImageChops, ImageStat++ap = argparse.ArgumentParser()+ap.add_argument("chapter"); ap.add_argument("beats", nargs="*")+ap.add_argument("--url", default="http://localhost:8765/")+ap.add_argument("--step", type=float, default=1); ap.add_argument("--min", type=float, default=3)+ap.add_argument("--thr", type=float, default=.03)+a = ap.parse_args()+URL = a.url.rstrip("/") + f"/{a.chapter}/"++async def main():+ async with async_playwright() as p:+ b = await p.firefox.launch(firefox_user_prefs={"media.autoplay.default": 0})+ pg = await b.new_page(viewport={"width": 1600, "height": 960})+ await pg.goto(URL + "?beat=0&t=0"); await pg.wait_for_timeout(800)+ ids = await pg.evaluate("BEATS.map(b => b.id)"); asks = await pg.evaluate("BEATS.map(b => !!b.ask)")+ r = await pg.evaluate("(() => { const r = document.getElementById('stage').getBoundingClientRect(); return {x: r.x, y: r.y, width: r.width, height: r.height}; })()")+ for i, bid in enumerate(ids):+ if asks[i] or (a.beats and bid not in a.beats): continue+ dur = await pg.evaluate(f"TIMINGS['{bid}'].dur")+ await pg.evaluate(f"seek({i}, false)"); await pg.wait_for_timeout(200)+ prev, diffs, t = None, [], 0.0+ while t <= dur + 1e-6:+ await pg.evaluate(f"P.t = {t}; evalTo({t})"); await pg.wait_for_timeout(40)+ im = Image.open(io.BytesIO(await pg.screenshot(clip=r))).convert("L").resize((400, 240))+ if prev is not None: diffs.append((t, ImageStat.Stat(ImageChops.difference(prev, im)).mean[0]))+ prev = im; t += a.step+ runs, start = [], None+ for t1, d in diffs + [(t, 99)]:+ if d < a.thr and start is None: start = t1 - a.step+ if d >= a.thr and start is not None:+ if min(t1 - a.step, dur) - start >= a.min: runs.append((start, min(t1 - a.step, dur)))+ start = None+ print(f"{bid:11s} dur {dur:5.1f} still: " + (", ".join(f"{s:.0f}-{e:.0f}s" for s, e in runs) or "-"), flush=True)+ await b.close()++asyncio.run(main())