An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
feat(skill): onion skins, review notes, atoms fixed and composition free
yzr4b718b5c02fa
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.mdindex 0667f94..8cbb163 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. 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).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.diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.mdindex 8fc80cc..99e00c9 100644--- a/.claude/skills/papermorph/references/engine.md+++ b/.claude/skills/papermorph/references/engine.md@@ -101,7 +101,7 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'## Player-Space play/pause, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions, `<`/`>` speed (0.75–1.5×, remembered), 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. The finish card's Enter opens `CHAPTER.next`, R replays.+Space play/pause, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions, `<`/`>` speed (0.75–1.5×, remembered), 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. 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. The finish card's Enter opens `CHAPTER.next`, R replays.Progress uses the stable legacy key `animebook:progress:<book-path>` (keep it when renaming the project so existing readers retain their progress); the cover template reads 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.diff --git a/.claude/skills/papermorph/references/review.md b/.claude/skills/papermorph/references/review.mdindex de1841e..ffd8be2 100644--- a/.claude/skills/papermorph/references/review.md+++ b/.claude/skills/papermorph/references/review.md@@ -1,14 +1,14 @@# Delivery pass-Serve `site/` with `python3 SKILL/scripts/serve.py 8765 site` (no browser caching, so an engine edit is never hidden by a stale file). Use this pass once per chapter: watch, fix what you find, recheck those parts, then deliver for the user's judgement of aesthetics, pacing and teaching. Keep the evidence in `books/<book>/review/chNN/`.+Serve `site/` with `python3 SKILL/scripts/serve.py 8765 site` (no browser caching, so an engine edit is never hidden by a stale file). Use this pass once per chapter: watch, fix what you find, recheck those parts, then deliver for the user's judgement of aesthetics, pacing and teaching. Offer the chapter URL with `?review` added: the user can press N at any moment to leave a note and Shift+N to copy them all for you, each with the `?beat=N&t=S` that opens that frame. Keep the evidence in `books/<book>/review/chNN/`.## Watch it in motion```sh-uv run --with playwright --with pillow SKILL/scripts/strip.py chNN OUT --url http://localhost:8765/<book>/ push/0.25 law3/0.5@w+uv run --with playwright --with pillow --with numpy SKILL/scripts/strip.py chNN OUT --url http://localhost:8765/<book>/ push/0.25 law3/0.5@w roll/0.2@o```-A strip shows one beat at small steps; `@w` adds a motion WebP. 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.+A 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.## Static checks firstdiff --git a/.claude/skills/papermorph/scripts/strip.py b/.claude/skills/papermorph/scripts/strip.pyindex 2e1b25d..adff11c 100644--- a/.claude/skills/papermorph/scripts/strip.py+++ b/.claude/skills/papermorph/scripts/strip.py@@ -1,14 +1,16 @@#!/usr/bin/env python3"""Frames of a chapter's beats on contact sheets, rendered from the beat clock: storyboard sheets and motion strips.- uv run --with playwright --with pillow strip.py ch12 OUT [specs ...] [--sheet NAME] [--url URL] [--browser chromium]+ uv run --with playwright --with pillow --with numpy strip.py ch12 OUT [specs ...] [--sheet NAME] [--url URL] [--browser chromium]push:2.3,dir,end chosen moments of beat 'push': seconds, a narration mark (dir, dir+0.5), mid or endpush/0.25 a motion strip: every 0.25 s across the beat (push alone: every 1 s)push/0.25@w also a motion WebP of the beat (0.25 s steps)+ push/0.2@o also an onion skin: the strip's frames laid over each other in one picture, later ones+ stronger; even gaps between ghosts mean even speed, bunched ghosts slow-in or slow-out--sheet storyboard put every frame into one sheet OUT/storyboard.jpg (layout-first storyboard)-Without --sheet each beat gets OUT/strip_<beat>.jpg. Frames are labelled "beat t" and shown at 1/3 size, four+Without --sheet each beat gets OUT/strip_<beat>.jpg (onion skins OUT/onion_<beat>.jpg). Frames are labelled "beat t" and shown at 1/3 size, foura row. Firefox by default: it is the slowest common browser and the one to judge by. --url is where the book is served."""import argparse, asyncio, re, sys, tempfile@@ -22,6 +24,17 @@ def sheet(ims, path, cols=4):for k, im in enumerate(ims): S.paste(im, ((k % cols) * W, (k // cols) * H))S.save(path, quality=84)+def onion_skin(ims):+ """Frames over a common background: what stays still is the per-pixel median; what moved is painted from+ each frame, earliest faintest."""+ import numpy as np+ F = np.stack([np.asarray(im, dtype=np.float32) for im in ims]); bg = np.median(F, axis=0); out = bg.copy()+ for k, f in enumerate(F):+ moved = np.abs(f - bg).max(axis=2) > 24+ a = .25 + .75 * k / max(len(F) - 1, 1)+ out[moved] = out[moved] * (1 - a) + f[moved] * a+ return Image.fromarray(out.astype(np.uint8))+async def main(a):out = Path(a.out); out.mkdir(parents=True, exist_ok=True)tmp = Path(tempfile.mkdtemp()) / "f.png"@@ -38,7 +51,8 @@ async def main(a):return im.resize((im.width // scale, im.height // scale))allims = []for spec in a.specs:- webp = spec.endswith("@w"); spec = spec.removesuffix("@w")+ m = re.fullmatch(r"(.+?)((?:@[wo])*)", spec); spec, flags = m[1], m[2]+ webp, onion = "@w" in flags, "@o" in flagsm = re.fullmatch(r"([^:/]+)(?::(.+)|/([\d.]+))?", spec)if not m: sys.exit(f"bad spec {spec!r}")bid, moments, step = m.groups()@@ -53,9 +67,14 @@ async def main(a):await pg.evaluate(f"seek({i}, false)"); await pg.wait_for_timeout(300)st = float(step or 1)ts = [when(x) for x in moments.split(",")] if moments else [k * st for k in range(int(dur / st) + 1)]- ims = []+ ims, raw = [], []for t in ts:- im = await shot(t, 3); ImageDraw.Draw(im).text((6, 4), f"{bid} t={t:.2f}", fill=(255, 230, 120)); ims.append(im)+ im = await shot(t, 3); raw.append(im.copy())+ ImageDraw.Draw(im).text((6, 4), f"{bid} t={t:.2f}", fill=(255, 230, 120)); ims.append(im)+ if onion:+ skin = onion_skin([await shot(t, 2) for t in ts] if len(ts) > 1 else raw)+ ImageDraw.Draw(skin).text((8, 6), f"{bid} onion t={ts[0]:.2f}..{ts[-1]:.2f}, {len(ts)} frames", fill=(255, 230, 120))+ skin.save(out / f"onion_{bid}.jpg", quality=86)if a.sheet: allims += imselse: sheet(ims, out / f"strip_{bid}.jpg")if webp: