Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

docs(skill): fixes from a fresh walk through both paths

yzr1c97dc586bd1
diff --git a/.claude/skills/papermorph/assets/templates/picture-book/lib/paper.js b/.claude/skills/papermorph/assets/templates/picture-book/lib/paper.js
index ccd2369..84a6bf7 100644
--- a/.claude/skills/papermorph/assets/templates/picture-book/lib/paper.js
+++ b/.claude/skills/papermorph/assets/templates/picture-book/lib/paper.js
@@ -57,7 +57,7 @@ function paperCam(p, setName, v0 = {}, { after = null, stages = [] } = {}) {
const blur = L.soft ? mk('image', { href: `../img/sets/${setName}/${L.name}-soft.webp`, ...img, visibility: 'hidden' }, g) : null;
layers.push({ g, k: L.k, sharp, blur, name: L.name });
if (stages.includes(L.name)) layers.push({ g: stageAt[L.name] = mk('g', {}, world), k: L.k });
- if (L.name === (after || 'house') || (!after && L.k === 1 && !stage)) layers.push({ g: stage = mk('g', {}, world), k: 1 });
+ if (L.name === after || (!after && L.k === 1 && !stage)) layers.push({ g: stage = mk('g', {}, world), k: 1 });
}
mk('rect', { width: 1600, height: 900, fill: 'url(#vignette)' }, root);
// Parallax is measured from the set's own framing (base), wherever the beat's first view is.
@@ -219,9 +219,9 @@ function trunkWipe(p, t0, dur, mode = 'in') {
const [a, b] = mode === 'in' ? [1650, -200] : [-200, -2150];
return q => { const u = Math.min(1, Math.max(0, (q - t0) / dur)); vis(g, mode === 'in' ? u > 0 : u < 1); tf(g, `translate(${(a + (b - a) * ease(u)).toFixed(0)},0)`); };
}
-// The title card at the end: a paper label that drops in on its pin.
-function endCard(p, t0) {
+// The title card at the end: a paper label that drops in on its pin. Give the words in the book's language.
+function endCard(p, t0, words = 'The End') {
const g = prop(p, `<g filter="url(#paper)"><rect x="560" y="330" width="480" height="240" rx="14" fill="#f3e9d2"/><rect x="580" y="350" width="440" height="200" rx="8" fill="none" stroke="#c8322f" stroke-width="5"/></g>
- <text x="800" y="478" text-anchor="middle" font-family="Georgia, serif" font-size="78" font-style="italic" fill="#5a2a1e">The End</text>${pinAt(800, 342)}`);
+ <text x="800" y="478" text-anchor="middle" font-family="Georgia, serif" font-size="78" font-style="italic" fill="#5a2a1e">${words}</text>${pinAt(800, 342)}`);
return q => { const u = (q - t0) * FPS; vis(g, u >= 0); const d = [-60, -20, 8, -3, 0][Math.min(4, Math.max(0, Math.floor(u / 2)))]; tf(g, `translate(0,${d})`); };
}
diff --git a/.claude/skills/papermorph/references/intake.md b/.claude/skills/papermorph/references/intake.md
index feca30b..6657804 100644
--- a/.claude/skills/papermorph/references/intake.md
+++ b/.claude/skills/papermorph/references/intake.md
@@ -37,7 +37,7 @@ Then start the book folder ([site.md](site.md#start-a-book-folder)): the look is
## 4. The look, by tier
-**Tier 1** needs few decisions. Propose palette, fonts and the language and voice from the book itself. Then make the chapter's narration and its first one or two beats, laid out at real size ([SKILL.md](../SKILL.md#chapter-loop), steps 2–3), and capture a few key frames with `strip.py`. Show the sheet and ask: go ahead as it is (recommended), or one of two or three concrete changes (calmer, more colour, larger type …). Once agreed, write `style.json` and make the chapter.
+**Tier 1** needs few decisions. Propose palette, fonts and the language and voice from the book itself. Then make the chapter's narration and its first one or two beats, laid out at real size ([SKILL.md](../SKILL.md#chapter-loop), steps 2–3), and capture a few key frames with `strip.py`. Show the sheet and ask: go ahead as it is (recommended), or one of two or three concrete changes (calmer, more colour, larger type …). Once agreed, settle the models (§5), then write `style.json` and make the chapter.
**Tier 2** has more to settle; ask in rounds:
1. Art and sources: drawn in code, pixel scenes, illustrated, real images; whether web images (with credits) are acceptable. The recurring characters: propose two or three casts that suit the book, each in one line.
@@ -48,7 +48,7 @@ Then start the book folder ([site.md](site.md#start-a-book-folder)): the look is
## 5. Models
-Which model does which step is the user's choice. Users run the Skill with different models and providers, and a book can mix them. Show the defaults for the chosen tier as one table, one row per step of the chapter loop ([team.md](team.md#steps)), and ask: keep it (recommended), or change some rows. Any model the user names is fine.
+Which model does which step is the user's choice. Users run the Skill with different models and providers, and a book can mix them. Show the defaults for the chosen tier as one table, one row per step in [team.md](team.md#steps), and ask: keep it (recommended), or change some rows. Any model the user names is fine.
| Step | Tier 1 | Tier 2 | Picture book |
|---|---|---|---|
@@ -60,7 +60,7 @@ Which model does which step is the user's choice. Users run the Skill with diffe
| Rework | strong | strong | middle, per scene |
| Register | small | small | small |
-**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual model names into `models`. Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
+**small**, **middle** and **strong** stand for the user's current fast, balanced and most capable models; write the actual model names into `models`, keyed by step as in the [course](../assets/templates/style.json) or [picture-book](../assets/templates/picture-book/style.json) template (a picture book's keys name its roles: `script`, `kit`, `scenes`, `sound`, `director`, `reviewers`). Without subagents one agent does every step on its own model, and the table only records that. The user can change a row at any time; later chapters follow the table as it stands.
## 6. style.json
diff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/painting.md
index 23d34b2..c49248c 100644
--- a/.claude/skills/papermorph/references/painting.md
+++ b/.claude/skills/papermorph/references/painting.md
@@ -8,7 +8,7 @@ Paint one set two or three ways at the cheapest quality, stand the puppets in ea
## Getting the composition you need
-Puppets stand at fixed places, counters must hide the right legs, and cuts must match. The reliable way is to draw the set first as a rough SVG sketch in `books/<book>/art/sets.js` (`bake_sets.py … --ref books/<book>/art` renders each set as one frame, `ref-<set>.png`), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. Once a set is painted, `bake_sets.py` leaves it alone unless you name it. Then:
+Puppets stand at fixed places, counters must hide the right legs, and cuts must match. The reliable way is to draw the set first as a rough SVG sketch in `books/<book>/art/sets.js` (`bake_sets.py books/<book>/art/sets.js site/<book> <set> … --ref books/<book>/art` renders each named set as one frame, `ref-<set>.png`; name the sets, since a set already baked is otherwise skipped), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. Once a set is painted, `bake_sets.py` leaves it alone unless you name it. Then:
- **Cut-outs for whatever people stand behind.** A counter, a cart, rows of desks, a lectern: paint each as its own picture on a transparent background and place it as a layer (`painted.py`, `cut`).
- **Variants by editing, not redrawing.** Rain and snow versions of a street, a door open and shut, a bun with a bite: edit the one picture, so a cut between versions changes only that.
diff --git a/.claude/skills/papermorph/references/puppets.md b/.claude/skills/papermorph/references/puppets.md
index 762690f..30245c9 100644
--- a/.claude/skills/papermorph/references/puppets.md
+++ b/.claude/skills/papermorph/references/puppets.md
@@ -2,7 +2,7 @@
The actors of a picture book are paper puppets drawn in code: pieces of coloured paper pinned at the joints, moved a little each frame, like a cut-out film shot by hand. Because a pose is only a set of numbers, any action the story needs (ducking, swinging an axe, diving through a window, shoving a thought bubble) costs a few lines, never a new drawing, and a puppet looks the same in every shot. The kit is in `assets/templates/picture-book/` (`paper.js`, `cast.js`, `shared.js`, `chapter.html`); copy it into `site/<book>/lib/` and the episode folder.
-Two cast styles are on the shelf, both on the same `paper.js`: round-headed figures that face us, in the spirit of South Park (*Joke Collection*), which the kit's `cast.js` builds (add a character by copying an entry of its `SHAPES`), and jointed storybook figures seen mostly in profile (*Little Red Riding Hood*: the wolf, Grandma, the woodcutter), which a book draws itself, a side set and a front set per figure. Pick with the user; the first is quicker to build and to act with.
+Two cast styles are on the shelf, both on the same `paper.js`: round-headed figures that face us, in the spirit of South Park (*Joke Collection*), which the kit's `cast.js` builds (add a character by copying an entry of its `SHAPES`), and jointed storybook figures seen mostly in profile (*Little Red Riding Hood*: the wolf, Grandma, the woodcutter), which a book draws itself, a side set and a front set per figure (start from that book's `lib/paper.js` and `lib/cast.js`, under `site/little-red-riding-hood/` in the Papermorph repository). Pick with the user; the first is quicker to build and to act with.
## What makes it read as stop motion
diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.md
index f14f26c..310c242 100644
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@ -45,15 +45,20 @@ uv run --with edge-tts python "$SKILL/scripts/tts.py" "$N" "$A"
python3 "$SKILL/scripts/mouths.py" "$N" "$A"
python3 "$SKILL/scripts/join.py" "$A" scene1=s01,s02,s02b,s03 --words "$N"
uv run --with numpy python "$SKILL/scripts/sfx.py" "$BOOK_SITE/ch01/audio/sfx" knock
+```
+
+Keep these commands in a script beside the book's notes (`tools/$BOOK_ID/audio.sh`) and rerun it after any change to the narration. As copied, they voice the kit's own sample episode, a check that the folder works; the episode's script then replaces the narration file, and its scenes replace the `join.py` list.
+
+The sets are baked before the scenes are written, the puppets after, since `bake_puppets.py` bakes the poses the chapters ask for; rerun either after a set or a puppet part changes. A painted look paints its sets between `bake_sets.py --ref` and the scenes ([painting.md](painting.md)).
+
+```sh
uv run --with playwright --with pillow python "$SKILL/scripts/bake_sets.py" "$BOOK_WORK/art/sets.js" "$BOOK_SITE"
uv run --with playwright --with pillow python "$SKILL/scripts/bake_puppets.py" "$BOOK_SITE" --url "http://localhost:8765/$BOOK_ID/"
```
-Keep these commands in a script beside the book's notes (`tools/$BOOK_ID/audio.sh`) and rerun it after any change to the narration. A painted look paints its sets between `bake_sets.py --ref` and the scenes ([painting.md](painting.md)).
-
### Every book
-Use the pilot chapter's number in place of `ch01` when the pilot is not the first chapter. Use the agreed primary language: rename the narration source, load `audio/<lang>/timings.js`, and set `CHAPTER.language` to match (default `en`, it picks the audio folder). Set `<html lang>` in `index.html` and every chapter to the same language: the player and the contents page take their interface text from it (English, Russian, Chinese and Japanese are built into the engine; other languages fall back to English until a block is added to the engine's `TRANSLATIONS`). Take `voice` and `rate` for each narration file from `style.json`, and translate the template's own visible text (titles, lede, prompts) before the pilot.
+Use the pilot chapter's number in place of `ch01` when the pilot is not the first chapter. Use the agreed primary language: rename the narration source, load `audio/<lang>/timings.js` (a picture-book chapter also loads `mouths.js` and `shots.js` from that folder), and set `CHAPTER.language` to match (default `en`, it picks the audio folder). Set `<html lang>` in `index.html` and every chapter to the same language: the player and the contents page take their interface text from it (English, Russian, Chinese and Japanese are built into the engine; other languages fall back to English until a block is added to the engine's `TRANSLATIONS`). Take `voice` and `rate` for each narration file from `style.json`, and translate the template's own visible text (titles, lede, prompts) before the pilot.
If the book's formulas need LaTeX ([engine.md](engine.md#latex)), add MathJax (with its license) to `lib/`, and load `../lib/mathjax.js` right after `engine.js` in every chapter:
diff --git a/.claude/skills/papermorph/references/stories.md b/.claude/skills/papermorph/references/stories.md
index 43303a3..a153594 100644
--- a/.claude/skills/papermorph/references/stories.md
+++ b/.claude/skills/papermorph/references/stories.md
@@ -65,4 +65,4 @@ With subagents the reviewers run in parallel ([team.md](team.md#picture-books));
The episode is a first cut for the user's viewing, not a finished film. Deliver its URL with what was made, the final script, the decisions the user should review (every line or moment you added), known problems, and the real cost of pictures. Once the user approves it, add it to `approved` in `style.json` and to the series page, and set the previous episode's `CHAPTER.next`: when an episode's last scene ends, the player marks it watched and offers the next one.
-The series page is the book's `index.html`, made from [series.html](../assets/templates/picture-book/series.html): one card per episode with a still, its title and a line, and a mark on episodes already watched.
+The series page is the book's `index.html`, made from [series.html](../assets/templates/picture-book/series.html): one card per episode with a still, its title and a line, and a mark on episodes already watched. A still is one frame of the episode (`shot.py`, or the page at `?beat=N&t=S`) saved as a 1400×788 WebP, like the cover image.
diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.md
index 34e800d..368b91a 100644
--- a/.claude/skills/papermorph/references/team.md
+++ b/.claude/skills/papermorph/references/team.md
@@ -25,7 +25,7 @@ Start each worker in the background with a short brief: the chapter and its page
## 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.
+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 and runs Claude Code, 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.
## Picture books
diff --git a/.claude/skills/papermorph/scripts/bake_puppets.py b/.claude/skills/papermorph/scripts/bake_puppets.py
index 49f5488..85e7f04 100644
--- a/.claude/skills/papermorph/scripts/bake_puppets.py
+++ b/.claude/skills/papermorph/scripts/bake_puppets.py
@@ -1,8 +1,8 @@
#!/usr/bin/env python3
"""Bake every paper piece a picture book uses (puppets and props, every scene of every chapter) to bitmaps.
- python3 SKILL/scripts/serve.py 8790 site &
- uv run --with playwright --with pillow python bake_puppets.py site/<book> [--url http://localhost:8790/<book>/] [--clean]
+ python3 SKILL/scripts/serve.py 8765 site &
+ uv run --with playwright --with pillow python bake_puppets.py site/<book> [--url http://localhost:8765/<book>/] [--clean]
The page would otherwise run the paper filter on each piece at startup. This opens every chNN of the book with ?bake
(which ignores existing bitmaps), seeks it to its last beat (which builds every scene before it, so every piece is asked
@@ -11,7 +11,7 @@ Run it after changing a puppet or prop drawing, or after adding a chapter. A pie
bounding box, and the box of text or of a rotated piece differs between browsers, so the pages are opened in Chromium
and in Firefox and both sets are kept. Pieces already baked are not encoded again, and files this run did not produce
are kept (a piece another chapter or an earlier run made); --clean (after changing the paper filter itself) re-encodes
-every piece and then removes the files no chapter asked for. --url defaults to the book under http://localhost:8790/.
+every piece and then removes the files no chapter asked for. --url defaults to the book under http://localhost:8765/.
"""
import argparse, base64, io, json, pathlib
from PIL import Image
@@ -31,7 +31,7 @@ def main():
ap.add_argument('site'); ap.add_argument('--url'); ap.add_argument('--clean', action='store_true')
a = ap.parse_args()
site = pathlib.Path(a.site); out = site / 'img/puppets'
- url = (a.url or f'http://localhost:8790/{site.resolve().name}/').rstrip('/') + '/'
+ url = (a.url or f'http://localhost:8765/{site.resolve().name}/').rstrip('/') + '/'
got = {}
with sync_playwright() as p:
for kind in (p.chromium, p.firefox):