An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
refactor(skill): organize references by tier, one shared core
yzr8550f10979ff
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.mdindex f241898..d2ddaf7 100644--- a/.claude/skills/papermorph/SKILL.md+++ b/.claude/skills/papermorph/SKILL.md@@ -5,112 +5,72 @@ description: Make or edit animated, narrated, interactive web books from referen# Papermorph-Papermorph makes four kinds of book on one machine:+Papermorph makes three tiers of book on one engine:- **Lessons**, from a textbook PDF: each chapter is a short animated lesson film where the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture.- **Picture books**, from a story, a joke or a fairy tale: short films of paper puppets in front of sets, drawn in code or painted by an image model, with voices, effects and music.-- **Documentaries**, from a book or an idea: narrated films of found public-domain pictures, words and maps moved in step with the voice, with music.-- **Shorts**, from an argument the user outlines: upright films for a phone feed that make one point in under three minutes.+- **Films**, from a book, an idea or the user's argument: narrated **documentaries** of found public-domain pictures, words and maps moved in step with the voice, and upright **shorts** for a phone feed that make one point in under three minutes.All are an SVG stage (1600×900, or 900×1600 for a short) plus a player; **beats** pair narration clips with timed actions. 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).-What the picture should be depends on the book and on the user, so the work starts with a conversation that ends in `style.json`: the user's words, the look they chose, the voices, which model does which step, and later the approved chapters. Every chapter is made against it; how each beat is laid out and choreographed is yours to judge against it and the approved chapters. 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 local preview instructions.+What the picture should be depends on the book and on the user, so the work starts with a conversation that ends in `style.json`: the user's words, the look they chose, the voices, which model does which step, and later the approved chapters. Every chapter is made against it; how each beat is laid out and choreographed is yours to judge against it and the approved chapters. 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/`). A chapter the Skill made is a first cut: review rounds and the user's viewing come before it is published.-## Which path+## Which tier-| The user brings | Path | Read |-|---|---|---|-| A textbook PDF | [Lessons](#lessons) | [intake.md](references/intake.md), then [diagrams.md](references/diagrams.md) (tier 1) or [scenes.md](references/scenes.md) (tier 2), [authoring.md](references/authoring.md), [assets.md](references/assets.md), [review.md](references/review.md) |-| A story, a joke, a fairy tale, or a story book's PDF | [Picture books](#picture-books) | [stories.md](references/stories.md), [puppets.md](references/puppets.md), [sound.md](references/sound.md), [painting.md](references/painting.md) for a painted look |-| A book, an idea or a stretch of history to explain as a narrated film | [Documentaries](#documentaries) | [documentary.md](references/documentary.md), [sound.md](references/sound.md) for music |-| One point to make in under three minutes, upright, for a phone feed (YouTube Shorts, TikTok, Reels) | [Shorts](#shorts) | [shorts.md](references/shorts.md), [documentary.md](references/documentary.md) for voice, pictures and review |-| A course book (cites works, reviewed questions, an LMS) | Lessons plus options | [courses.md](references/courses.md), only when the book calls for them |+Read the tier's first file, then only what the current step needs. Every file below is linked from here; none needs another to be found.-Every path shares [site.md](references/site.md) (the book folder, cover or series page, preview, video export), [engine.md](references/engine.md) (the player and drawing API), [team.md](references/team.md) (making chapters with subagents) and the models step of [intake.md](references/intake.md#5-models). Read only the reference the current step needs.+| The user brings | Tier | Start with | Then, as the step needs |+|---|---|---|---|+| A textbook PDF (a course book too) | Lessons | [lessons.md](references/lessons/lessons.md) | [intake.md](references/lessons/intake.md) · [authoring.md](references/lessons/authoring.md) · [diagrams.md](references/lessons/diagrams.md) (tier 1) · [scenes.md](references/lessons/scenes.md) (tier 2) · [assets.md](references/lessons/assets.md) · [questions.md](references/lessons/questions.md) · [checks.md](references/lessons/checks.md) · [cover.md](references/lessons/cover.md) · [courses.md](references/lessons/courses.md) (citations, item bank, SCORM: only when the book calls for them) |+| A story, a joke, a fairy tale, or a story book's PDF | Picture books | [stories.md](references/picture-books/stories.md) | [puppets.md](references/picture-books/puppets.md) · [painting.md](references/picture-books/painting.md) (a painted look) |+| A book, an idea or a stretch of history to explain as a narrated film | Films: documentary | [films.md](references/films/films.md) | [documentary.md](references/films/documentary.md) |+| One point to make in under three minutes, upright, for a phone feed (YouTube Shorts, TikTok, Reels), or a long film to recut | Films: shorts | [films.md](references/films/films.md) | [shorts.md](references/films/shorts.md) |++Every tier shares the core:++| File | What it holds |+|---|---|+| [core/style.md](references/core/style.md) | how to ask the user, the models step, `style.json` |+| [core/publish.md](references/core/publish.md) | `new_book.py`, language, minutes, preview and delivery, video export |+| [core/sound.md](references/core/sound.md) | the narration file, voices, levels, effects, music, captions |+| [core/review.md](references/core/review.md) | seeing your own work in motion, frames, smoothness, director rounds |+| [core/team.md](references/core/team.md) | making chapters with subagents, the coordinator, workers in parallel |+| [core/engine.md](references/core/engine.md) | the player and drawing API, timing, camera, performance, traps |++Start with the tier's intake whenever `books/<book>/style.json` does not exist yet; reuse answers and approvals already given. The reference books on https://papermorph.diamonddoge.org/ are the bar: the maths and science books for lessons, *Joke Collection* and *Little Red Riding Hood* for picture books, *Madness and Civilization*, *Shooting an Elephant* (interactive) and *The Pandemic* for documentaries, the *Madness and Civilization* shorts for shorts.## Project layout```-books/<book>/- book.pdf, sections.json source and page map (private)- pages/chNN/text.md, *.png extracted reference material (private)- style.json the agreed style every chapter anchors to (assets/templates/style.json)- chapters.md chapter map and status- chapters/chNN.md storyboard, errata, feedback- images/ inbox, SOURCES.md (where each image came from), image-requests.md, processing scripts- review/chNN/ storyboard sheets, strips, check output-content/<book>/chNN/ narration.<lang>.json and TTS cache-tools/<book>/ tests and evidence scripts+books/<book>/ private: source, style.json, storyboards, art, review/ (tier files list their own)+content/<book>/chNN/ narration.<lang>.json and the voice cache+tools/<book>/ tests, audio scripts, evidencesite/<book>/ the static book (only this is delivered)- index.html, unit-art.js cover + contents, unit sketches- lib/engine.*, math.js, the engine (player, maths helpers, cover/contents, unit headers), copied into- volume.*, contents.*, the book by scripts/engine.py- units.*- lib/book.css this book's engine settings and style overrides- lib/*.js, img/ the book's element library and images- chNN/index.html, audio/<lang>/ a lesson, its beat MP3s + timings.js+ index.html cover and contents, or a series page+ lib/ the engine (synced by engine.py), lib/book.css (this book's settings), the tier's kit, the book's own pieces+ img/ the book's pictures+ chNN/index.html, audio/<lang>/ a chapter or episode, its beat MP3s and timings.js (films and picture books: audio/sfx/, audio/bgm/)```-A picture book adds `books/<book>/story.md` (the user's telling, verbatim), `storyboard.md` and `art/` (`sets.js` with the set sketches, generated pictures, `painted.json`, `costs.tsv`); its `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`, which needs engine-v2.2 or later: `sfx()` and `music()` are in the engine) and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`.--A documentary adds `books/<book>/storyboard.md`, `art/` (`found/` with the downloaded pictures, the `prep.py` list, generated clips, `costs.tsv`) and `music/`, where `commons.py` keeps a `SOURCES.tsv` beside its downloads; its `site/<book>/lib/` holds `film.js`, `fonts.css` and `fonts/` from `assets/templates/documentary/` (its `book.css` too, with the film's colours) and, when the film uses them, `lines.js` (`trace.py`); `img/` holds the treated pictures with `art.js` (`prep.py`) and clip sheets with `frames.js` (`frames.py`); `index.html` is the series page with the credits; each film `chNN/` has `audio/<lang>/` and `audio/bgm/`.--A series of shorts adds `books/<book>/chNN-script.md` (the outline, the beats with what we see, the sources), `art/` (generated and found pictures, `costs.tsv`) and `music/`; its `site/<book>/lib/` holds `shorts.js`, `book.css` and `icons.js` from `assets/templates/shorts/` with the documentary kit's fonts, and a second file of the series' own pieces loaded after `shorts.js`; `img/` holds the pictures with `art.js` (`prep.py`); a film with a map, in either tier, adds `map.js` and `globe.js` from `assets/templates/maps/lib/` and `img/geo-lite.js` (`geo.py`); each episode `chNN/` has `audio/<lang>/`, `audio/sfx/` and `audio/bgm/`.--`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`), github.com for `engine.py` when the repository's `engine/` folder is not at hand, an OpenRouter key only for the paid steps the user chooses (`paint.py`, `eleven.py`, `video.py`; `paint_openai.py` takes an OpenAI key), and Playwright browsers (`uv run --with playwright playwright install chromium firefox`; where Playwright's Chromium does not run, set `CHROME` to an installed Chrome, Chromium, Brave or Edge). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).--## Lessons--### Pipeline--Start with intake whenever `books/<book>/style.json` does not exist yet; reuse answers and approvals already given.--1. **Intake** ([intake.md](references/intake.md)), a short conversation: find the PDF with the user (a story goes to [stories.md](references/stories.md)), split it, say what the book is, agree on one chapter to try and a tier, start the book folder, settle the look the way that tier needs, agree which model does which step, and write `style.json`.- - Split: `uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf`; use `--level N -o books/<book>/sections.json` at chapter depth. A chapter bookmark that points outside its neighbours is moved to the page holding its title or dropped, with a warning: look at those chapters' pages. For a PDF without usable chapter bookmarks, inspect `split_pages.py … --pages 1-12 --out books/<book>/pages`, then write the map from its contents (schema: `outline.py --help`). Extract chapter text with `split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only`.- - Start the book folder with [site.md](references/site.md#start-a-book-folder) before showing the user any frames; build agreed shared components once into the book's library ([assets.md](references/assets.md)) and list them in `style.json`.-2. **Pilot.** Make the chosen chapter through the chapter loop and deliver it for the user's judgement. Fold their feedback into `style.json` and record the chapter under `approved`.-3. **Remaining chapters and finish**, when the user wants the whole book: write `chapters.md`, produce chapters sequentially (see *Context*), complete cover text, contents and unit sketches using [site.md](references/site.md). Deliver the static book folder, its entry URL for local preview and any unresolved issues.--A course book may also want verified citation links, a reviewed question bank or a SCORM package for an LMS; offer them only when the book calls for them ([courses.md](references/courses.md)).--### Chapter loop--1. **Read** this chapter's `pages/chNN/text.md`; render pages with `split_pages.py … --only chNN` when diagrams or missing text need images. Choose the ideas, examples and sections to teach.-2. **Beats and narration**: list beats in `chapters/chNN.md` with what each says and which word triggers which action ([authoring.md](references/authoring.md)). Write `content/<book>/chNN/narration.<lang>.json`, then `uv run --with edge-tts SKILL/scripts/tts.py content/<book>/chNN/narration.<lang>.json site/<book>/chNN/audio/<lang>` (for `"engine": "kokoro"`: `uv run --python 3.12 --with kokoro …`).-3. **Storyboard, layout first**: in the real page, place everything for one to three key moments per beat, real elements at their real sizes, no motion yet. Capture them into one sheet with `strip.py` and give each frame one line: what it says and where the eye goes. That sheet is the storyboard. Note what the chapter needs beyond the library: draw it, or add it to the image requests.-4. **Motion**: add the motion, the camera and the questions; API and replay invariants are in [engine.md](references/engine.md).-5. **Delivery pass**: watch your output in motion and judge it as a viewer would, against the storyboard; then run the checks in [review.md](references/review.md). Correct what you find, recheck, deliver; report unresolved problems.-6. **Register**: add the chapter to the contents (`units` in `Contents.book` in `index.html`), set the previous chapter's `CHAPTER.next`, update `chapters.md` and `chapters/chNN.md`. Promote new shared decisions and recurring elements to `style.json` and the library. The coordinator owns this step when using subagents.--## Picture books--Start with the story intake in [stories.md](references/stories.md#intake-for-a-story) whenever `books/<book>/style.json` does not exist yet; agree the models ([intake.md](references/intake.md#5-models)) and write `style.json`. Then follow [the order of work](references/stories.md#the-order-of-work): the script and storyboard shown to the user before anything is built, the book folder ([site.md](references/site.md#a-picture-book)), sound, sets, scenes, [review rounds](references/stories.md#review-rounds), and the user's viewing of the first cut. Each episode is a chapter (`chNN`); a series shares its cast, sets and series page.--## Documentaries--Start with the intake in [documentary.md](references/documentary.md#intake) whenever `books/<book>/style.json` does not exist yet. Then follow [the order of work](references/documentary.md#the-order-of-work): research, the script and storyboard shown to the user, the folder from `assets/templates/documentary/` ([site.md](references/site.md#a-documentary)), pictures found and treated, voice, music, the beats, [review rounds](references/documentary.md#review-rounds) and the user's viewing. *Madness and Civilization* on the shelf is the approved reference; *Shooting an Elephant* (`site/shooting-an-elephant/`) is the interactive one, where the reader fires the rifle ([interactive moments](references/documentary.md#interactive-moments)).--## Shorts+`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. `new_book.py` starts a book of any tier ([core/publish.md](references/core/publish.md#start-a-book-folder)).-Start with the questions in [shorts.md](references/shorts.md#questions-for-the-user) whenever `books/<book>/style.json` does not exist yet; the user's outline comes before any script (a long film being recut as shorts is the outline: [from a long film](references/shorts.md#from-a-long-film)). Then follow [the order of work](references/shorts.md#the-order-of-work): the script written beat by beat with the user, the storyboard and the pictures, the folder from `assets/templates/shorts/` on the upright stage, voice and music levels, the beats, a director pass and the user's viewing, then `export.py` for a 1080 × 1920 video. *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/`), is the worked example.+Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local), github.com for `engine.py` when the repository's `engine/` folder is not at hand, an OpenRouter key only for the paid steps the user chooses (`paint.py`, `eleven.py`, `video.py`; `paint_openai.py` takes an OpenAI key), and Playwright browsers (`uv run --with playwright playwright install chromium firefox`; where Playwright's Chromium does not run, set `CHROME` to an installed Chrome, Chromium, Brave or Edge). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).## Scripts-All in `SKILL/scripts/`; each prints its usage with `--help`, run with the `uv run --with …` its docstring names (its first lines; without its packages even `--help` stops on the import). Packages: playwright for every script that opens a page (shot, strip, still, check, perf, safe, export, music, playlog, overlap, check_blank, bake_sets, bake_puppets), pillow for the ones that write pictures (shot, strip, still, playlog, bake_*, prep, frames, painted, sprites, trace, `geo.py --globe`), numpy for strip, export, `music.py gaps`, prep, frames, sfx and eleven, faster-whisper for eleven, pymupdf for outline and split_pages, scikit-image for trace, edge-tts or kokoro for tts; the rest need only Python and ffmpeg.+All in `SKILL/scripts/`; each prints its usage with `--help`, run with the `uv run --with …` its docstring names (its first lines; without its packages even `--help` stops on the import). Packages: playwright for every script that opens a page, pillow for the ones that write pictures, numpy for strip, export, `music.py gaps`, prep, frames, sfx and eleven, faster-whisper for eleven, pymupdf for outline and split_pages, scikit-image for trace, edge-tts or kokoro for tts; the rest need only Python and ffmpeg.| For | Scripts ||---|---|-| Every book | `serve.py` preview without caching · `engine.py` sync the engine into books · `tts.py` narration and word times · `lint.py` static checks · `check.py` page errors, console warnings and beat lengths in Chromium and Firefox · `shot.py` beat screenshots · `strip.py` storyboard sheets and motion strips · `still.py` stretches where nothing moves · `perf.py` Firefox frame times, with the machine's load and a reference moment · `export.py` MP4 and `.srt` · `level.py` even loudness |-| Lessons | `outline.py` and `split_pages.py` page map and chapter text · `check_blank.py` empty openings · `overlap.py` arrows through text · `sprites.py` image processing steps |-| Picture books | `mouths.py` mouth shapes · `join.py` one clip per scene · `sfx.py` synthesized effects · `playlog.py` sounds and captions against the picture · `bake_sets.py` set layers · `bake_puppets.py` puppet bitmaps · `paint.py` / `paint_openai.py` image-model pictures · `painted.py` place them in the book |-| Documentaries | `commons.py` public-domain pictures and recordings with their licences · `prep.py` print and line treatments · `trace.py` drawings that draw themselves on · `video.py` a clip from a still · `frames.py` a clip as treated frames · `eleven.py` ElevenLabs narration with word times and `--tempo` · `music.py` a music track cut to the film, and the bed in the voice's gaps and at the end · `safe.py` words outside an upright film's safe area · `geo.py` the map kit's countries, regions, cities and globe from Natural Earth |-| Course options | `refs.py` verified citations · `items.py` question bank · `scorm.py` LMS package |+| Every book | `new_book.py` start a book folder · `serve.py` preview without caching · `engine.py` sync the engine into books · `tts.py` narration and word times · `level.py` even loudness · `lint.py` static checks · `check.py` page errors, console warnings and beat lengths in Chromium and Firefox · `shot.py` beat screenshots · `strip.py` storyboard sheets and motion strips · `still.py` stretches where nothing moves · `playlog.py` sounds and captions against the picture · `perf.py` Firefox frame times · `export.py` MP4 and `.srt` · `sfx.py` synthesized effects |+| Lessons | `outline.py` and `split_pages.py` page map and chapter text · `check_blank.py` empty openings · `overlap.py` arrows through text · `sprites.py` image processing steps · `refs.py` verified citations · `items.py` question bank · `scorm.py` LMS package |+| Picture books | `mouths.py` mouth shapes · `join.py` one clip per scene · `bake_sets.py` set layers · `bake_puppets.py` puppet bitmaps · `paint.py` / `paint_openai.py` image-model pictures · `painted.py` place them in the book |+| Films | `commons.py` public-domain pictures and recordings with their licences · `prep.py` print, line and full-bleed treatments · `trace.py` drawings that draw themselves on · `video.py` a clip from a still · `frames.py` a clip as treated frames · `geo.py` the map kit's data from Natural Earth · `eleven.py` ElevenLabs narration with word times · `music.py` a track cut to the film, and the bed in the voice's gaps · `safe.py` words outside an upright film's safe area |`silence.py`, `ledger.py` (the one cost ledger: date, chapter, file, model, what, cost) and `browsers.py` are helpers the others import.## Context-- Talk with the user from the main conversation: intake, and every sheet and choice of the pilot. When subagents are available, chapters are made as a team: a fresh worker per step of the chapter loop, each on the model the user chose for that step (`models` in `style.json`), chapters one after another; a picture book splits by scene instead, a documentary by part of the film. The main conversation coordinates the pilot, since the user sees its sheets; later chapters are best coordinated from a fresh session ([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.-- 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`.+- Talk with the user from the main conversation: intake, and every sheet and choice of the pilot. When subagents are available, later chapters are made as a team, each step on the model the user chose ([core/team.md](references/core/team.md)); without them, run the same steps in the current agent with file-based state.+- Use the engine API and inspect individual functions when needed; copy kit files 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/authoring.md b/.claude/skills/papermorph/references/authoring.mddeleted file mode 100644index c7fccd7..0000000--- a/.claude/skills/papermorph/references/authoring.md+++ /dev/null@@ -1,69 +0,0 @@-# Authoring a chapter--## Shape--Chapters have run 5–18 minutes with 5–40 second beats; a long chapter can hold several parts (each a short title beat, lessons, a quick check and a wrap). Let the content determine length and the number of checks/practice sets.--| Beat | Purpose |-| --- | --- |-| `intro` | Title card (unit and chapter number, title, one line of purpose). |-| lesson beats | One idea each, built up in the picture while the narration explains it. |-| `q1`, `q2`, … | A check of already taught content, separated from the next check by a lesson beat. |-| `wrap` | Three or four numbered takeaways. |-| `final1` … | Full-screen practice covering the whole chapter. With several sets, label them like `'Chapter practice · set 1 of 2'` (the engine appends "· question k of n"). |-| `finish` | Score card (`finishCard`): first-try results for quick checks and practice. |--Beat ids are shared by the page (`BEATS`) and the narration file; a beat with `ask` waits for the answers before moving on.--## Beats--Before writing code, list the beats. For each lesson beat decide what the eye should watch and what changes; why that change is true (the animation is the argument); which words trigger which actions (these become `[[marks]]`); what text appears, beside the thing it names; and what carries over from the previous beat. Then lay out the key moments as pictures (storyboard): [diagrams.md](diagrams.md) and [scenes.md](scenes.md).--- **Open on the subject.** When a beat clears the picture, the new topic appears right away; labels and steps follow the words. Short pauses for thought are fine.-- **One new thing at a time**, and **the same colour means the same thing** across the chapter and, where it fits, the book.-- **Teach the chapter's scope**, choosing sections by idea; note any reordering in `chapters/chNN.md`.--## Narration--`content/<book>/chNN/narration.<lang>.json` (English example):--```json-{ "voice": "en-US-AndrewNeural", "rate": "-4%",- "beats": { "intro": "Chapter five. [[sub]]Subtraction undoes addition.", "...": "..." } }-```--- `[[name]]` goes right before the word an action waits for; `m('name', offset)` in the page returns when that word starts. Names are unique within a beat; a misspelt mark makes the page throw, and a mark that matches no spoken word makes `tts.py` stop.-- Write for the ear: short sentences, one idea each. Say symbols and units in words ("negative seven halves", "meters per second squared"); the picture shows the symbols.-- Match the audience: plain, warm, never childish. Explain why, not only how.-- Question beats get one short line ("Quick check. Find the mean."); the card holds the question.-- `tts.py` writes `<beat>.mp3` and `timings.js` (duration, marks, captions) and caches each finished beat beside the narration JSON: moving `[[marks]]` reuses the cache, and after a failure the same command resumes rather than starting over. It takes a few seconds a beat, so a long chapter can outlast a tool's foreground time limit: run it in the background and wait for it before `lint.py`.-- Engine: `"engine": "edge"` (default, online) or `"kokoro"` (local, Apache 2.0; English word timings; voices such as `am_michael`, `af_heart`, `bm_george`), set at the top of the narration file with `voice` and `rate`. Keep one engine and voice per book. Edge's `...MultilingualNeural` voices guess the language sentence by sentence and read a short line such as "No zero, no fractions, no negatives." with a Spanish or Portuguese accent; a book in one language uses a one-language voice of that language.--## Questions--Pick the type that lets the student act on the picture itself whenever possible (click the point, the cell, the step) rather than choosing text.--| Type | Use for |-| --- | --- |-| `choice` | One answer from a few options, each wrong option with its own explanation (from a reviewed item bank: `mcq`, [courses.md](courses.md)) |-| `blanks` | Typed numbers inside an expression; fractions and mixed numbers accepted; `test` judges a whole row (answers in any order) |-| `grid` | Several items, each classified (yes/no, which category, true/false) |-| `tap` / `tapEls` / `pickEls` | Click a point on the number line / a token in an expression / any drawn object |-| `pickPoint` | Choose a grid point on a coordinate plane (math.js) |-| `sorter` | Drag items into regions (the number-set diagram; math.js) |--New types are welcome when the content calls for one; each needs keyboard play (see engine.md).--- Ids: `c-…` for quick checks, `p-…` for practice; the score card adds them up.-- The prompt is rich text ([engine.md](engine.md#traps)).-- Feedback: right → `why` (and an animation via `fx`/`onRight`); wrong → a hint aimed at that mistake; after a wrong try, Show answer.-- Grade meaning: equal values match (6/8 = 3/4) unless the lowest form is asked for; sets and pairs in any order; no denominators of zero; never judge irrationality from finitely many digits.-- The built-in numeric parser uses safe integer numerators and denominators and exact integer products for equality. For answers outside that range, use a subject-specific input and grader rather than allowing rounded values to pass.-- Compose the question beat for its card: the picture the question is about stays visible (for example in the top 60 % with a `BAND` card below, or beside a `{x, y, w, cls: 'side'}` card); `SCREEN` for practice.-- Units in typed answers: write the unit as a word after the box (`{ box: '60' }, ' kilograms'`) so it is not set as a math variable.--## Content rules--- Follow the agreed chapter scope and order. Verify facts, calculations and answers actually used in the finished lesson; correct or replace source errors and note them in `books/<book>/chapters/chNN.md` for the user.-- Check worked examples as the subject, not only as arithmetic (a push on someone standing on the ground is not the net force).-- Use the notation and rounding in `style.json` (`look.notation`). Record new shared decisions there. Group thousands with a no-break space (U+00A0) or the book's comma: a thin space all but vanishes in bold system fonts (150 000 000 read as 150000000).diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/core/engine.mdsimilarity index 54%rename from .claude/skills/papermorph/references/engine.mdrename to .claude/skills/papermorph/references/core/engine.mdindex 59e62cb..46fba69 100644--- a/.claude/skills/papermorph/references/engine.md+++ b/.claude/skills/papermorph/references/core/engine.md@@ -2,19 +2,32 @@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.7`; `@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.7`; what an older copy lacks is marked *(v2.1)*, *(v2.2)*, *(v2.3)*, *(v2.4)*, *(v2.4.1)*, *(v2.4.2)*, *(v2.5)*, *(v2.6)* or *(v2.7)*, 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.7`; `@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.7`; a book on an older copy is synced with `engine.py` before it relies on anything here. 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.+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](../lessons/assets.md)) rather than into the engine copy.++## Contents++- Stage and state: the stage, the upright stage, element state, palette and board colours+- Drawing+- LaTeX+- Timing: beats, marks, holds, lengths+- World clock and camera+- Performance (Firefox)+- Player: keys, captions, effects and music, progress+- Traps++The question types and their API (`quiz()`, cards, grading) are in [lessons/questions.md](../lessons/questions.md); a film's interactive moment uses its own `ask` ([documentary.md](../films/documentary.md#interactive-moments)).## 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** *(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.+- **Upright stage**. `<html data-stage="portrait">` turns the stage to 900 × 1600 for a phone feed ([shorts.md](../films/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`.- Palette `COL`: `chalk dim faint task good bad board` plus six hues named `nat whole int rat irr real` (from the algebra book; give them the book's own meanings in `style.json` `look.meaning`, e.g. `const FORCE = COL.…`). Fonts: `UI` (text), `MATH` (serif unless the book's `--math-font` says otherwise).-- **Board colour** *(v2.1)*. The board and ink colours are the palette at the top of `engine.css` (`--page --board --panel --edge --chalk --dim --faint --task --quiz --good --bad`, plus `--on-fill` for text on a coloured button (unset there, so dark) and `--vignette` for the stage's edges, and the shades between them: `--rule --track --track-ask --bar-edge --hover --veil`). A book redefines them in its `lib/book.css` under a plain `:root`; the stage, the cards, the player bar and `COL.chalk … COL.board` all follow, so a light board with dark ink is a few lines of settings (the commented example in `book.css`, shades included). `COL` reads its colours back as `#rrggbb` (colour tweens mix them) and keeps the dark board's own for one that is missing. The six hues stay in JS: a light book picks darker ones in its own `lib/<look>.js` (`Object.assign(COL, { … })`), loaded right after `engine.js` and before `math.js`, which copies the hues as it loads. Check a new palette on a frame with a question card and the captions on (`?beat=N&t=S`), not only on the picture. `site/physics-notebook/` is a light book made this way (`lib/book.css` and `lib/notebook.js`).+- **Board colour**. The board and ink colours are the palette at the top of `engine.css` (`--page --board --panel --edge --chalk --dim --faint --task --quiz --good --bad`, plus `--on-fill` for text on a coloured button (unset there, so dark) and `--vignette` for the stage's edges, and the shades between them: `--rule --track --track-ask --bar-edge --hover --veil`). A book redefines them in its `lib/book.css` under a plain `:root`; the stage, the cards, the player bar and `COL.chalk … COL.board` all follow, so a light board with dark ink is a few lines of settings (the commented example in `book.css`, shades included). `COL` reads its colours back as `#rrggbb` (colour tweens mix them) and keeps the dark board's own for one that is missing. The six hues stay in JS: a light book picks darker ones in its own `lib/<look>.js` (`Object.assign(COL, { … })`), loaded right after `engine.js` and before `math.js`, which copies the hues as it loads. Check a new palette on a frame with a question card and the captions on (`?beat=N&t=S`), not only on the picture. `site/physics-notebook/` is a light book made this way (`lib/book.css` and `lib/notebook.js`).## Drawing@@ -25,7 +38,7 @@ The maths helpers (number lines, tiles, fraction rows, planes, chance objects, t| `put(e, {x,y,s,r,o,…})` | set an element's state at once, without a tween (to place a piece drawn around its own origin) || `path(parent, d, attrs, {d:0})` | path; `{d: 0}` makes it ready to be drawn on with `draw()`. A `transform` in `attrs` holds until the state moves the element (`x y s r`), which then owns the transform: to place a shape that also moves, put it in a `G()` || `T(parent, str, {x,y,size,fill,font,weight,anchor,o})` | text |-| `cite(parent, key, {str,x,y,size,fill,weight,anchor,o})` | a citation from `REFS` (`../refs.js`, a course option: [courses.md](courses.md)), drawn as an underlined link that opens the source in a new tab and listed on the finish card ([courses.md](courses.md#citations)) |+| `cite(parent, key, {str,x,y,size,fill,weight,anchor,o})` | a citation from `REFS` (`../refs.js`, a course option: [courses.md](../lessons/courses.md)), drawn as an underlined link that opens the source in a new tab and listed on the finish card ([courses.md](../lessons/courses.md#citations)) || `M(parent, parts, {x,y,size,fill,anchor,o,s})` | math with its baseline at y; parts are strings, `F(n,d)` fractions, `R(x, i)` roots (x may be `F(...)`, i the index), `E(exp)` exponents, `TX(tex)` LaTeX (see [LaTeX](#latex)); returns a group with `_w` (width) || `mathW(parts, size)` | width of math without drawing it (math.js) || `frac(p, top, bot, x, y, t0, opts)` | built-up fraction whose top and bottom are math parts (math.js) |@@ -43,7 +56,7 @@ Topic helpers in `math.js`: number lines (`numberLine`, `move`, `landDot`, `brac## LaTeX-A book whose formulas need more than `M()` parts (indices, sums, matrices, accents) uses the engine's vendored MathJax: add it with `engine.py <book> --latex` ([site.md](site.md#start-a-book-folder)) and load `<script src="../lib/mathjax.js"></script>` right after `engine.js` (after `math.js` when the chapter loads it) in every chapter.+A book whose formulas need more than `M()` parts (indices, sums, matrices, accents) uses the engine's vendored MathJax: add it with `engine.py <book> --latex` ([lessons.md](../lessons/lessons.md)) and load `<script src="../lib/mathjax.js"></script>` right after `engine.js` (after `math.js` when the chapter loads it) in every chapter.- `TX('\\frac{a}{b}')` is a part like `F()`: it works in `M`, `tokens`, `chip`, `eqLine` (also as `sym`), `mathEl`, `blanks` and `grid`; `$tex(tex)` puts one in HTML text. 1 em is `size`; the baseline is at `y`.- Formulas are set in text style, like `$…$`; write `\displaystyle` for large sums and fractions. Words go in `\text{…}` and use the book's math font.@@ -62,12 +75,12 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accen- `m('name', offset)` is the start time of the word after `[[name]]`; `D` is the clip's length. Use marks for actions tied to speech; scene entrances and transitions can use fixed offsets.- Tweens: `tw(e, to, t0, dur, ease)`, `prog(q => …, t0, dur, ease)` for custom motion (arcs, counters, live redraws), `show(e, t0, dur, ease)`, `hide`, `draw` (same arguments), `pop`, `pulse`, `stream`. Eases: `io`, `out`, `back`, `lin`, `soft`. Continuous motion and cameras: see below.-- A lesson beat ends after its narration and its last tween, and holds that picture `HOLD` (0.6 s) before the next starts (tailed `clockRun`s and cameras run to that end and do not set it *(v2.6)*: hold a picture longer with a plain run, `prog(() => {}, 0, D + 1)`, or `minDur`, below); an `ask` beat waits for `done()`. An `ask` is any `done => …` that calls `done()` once; `quiz()` is the usual one, and a film's own handler can listen on the stage instead ([documentary.md](documentary.md#interactive-moments)). A `done()` kept from an earlier start of the same beat (the reader stepped back and replayed it) no longer counts *(v2.4.1)*; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.-- **Beats lengthen without a word**: any tween that ends after `D` (a push to `D + .6`, a helper's `clockRun(f, 30)`) lengthens the beat by as much. `?lengths` in the URL *(v2.7)* prints in the console each beat's voice (`pre` + clip), its length on screen and the time past voice + `HOLD`; read it after a change, and recut the music after any change in length. A helper that does not know the beat's `D` runs to the beat's end with `clockRun(f, 0, { tail: true })`, which never lengthens it.-- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and no element is revealed (faded, scaled or drawn in from nothing) within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s, so the narration never runs over an empty board. It looks only at reveals: a beat that lays out part of its picture visible at once (axes, empty boxes, a set) and reveals the rest on later words still has that first group pulled to 0.4 s. When those words matter, or a camera shows a picture from the first frame, give the beat `{ lead: false }` in its fourth slot; when every opening in the chapter is timed by hand (a documentary), set `CHAPTER.lead = false` *(v2.2)* instead. To see where a beat's reveals land, put marks on a contact sheet: `strip.py chNN OUT idea:0.4,label,label+0.3,end --sheet storyboard --url http://localhost:8765/<book>/` (a mark plus an offset is the moment the action is timed to).+- A lesson beat ends after its narration and its last tween, and holds that picture `HOLD` (0.6 s) before the next starts (tailed `clockRun`s and cameras run to that end and do not set it: hold a picture longer with a plain run, `prog(() => {}, 0, D + 1)`, or `minDur`, below); an `ask` beat waits for `done()`. An `ask` is any `done => …` that calls `done()` once; `quiz()` is the usual one, and a film's own handler can listen on the stage instead ([documentary.md](../films/documentary.md#interactive-moments)). A `done()` kept from an earlier start of the same beat (the reader stepped back and replayed it) no longer counts; a chapter's own handler that acts later can compare `P.gen`, which every start of a beat changes.+- **Beats lengthen without a word**: any tween that ends after `D` (a push to `D + .6`, a helper's `clockRun(f, 30)`) lengthens the beat by as much. `?lengths` in the URL prints in the console each beat's voice (`pre` + clip), its length on screen and the time past voice + `HOLD`; read it after a change, and recut the music after any change in length. A helper that does not know the beat's `D` runs to the beat's end with `clockRun(f, 0, { tail: true })`, which never lengthens it.+- **Opening lead-in**: if a beat calls `panel()` (before 0.5 s) and no element is revealed (faded, scaled or drawn in from nothing) within 0.8 s, `runBeat` moves the opening group (every tween starting within 1.2 s of the first reveal) to start at 0.4 s, so the narration never runs over an empty board. It looks only at reveals: a beat that lays out part of its picture visible at once (axes, empty boxes, a set) and reveals the rest on later words still has that first group pulled to 0.4 s. When those words matter, or a camera shows a picture from the first frame, give the beat `{ lead: false }` in its fourth slot; when every opening in the chapter is timed by hand (a documentary), set `CHAPTER.lead = false` instead. To see where a beat's reveals land, put marks on a contact sheet: `strip.py chNN OUT idea:0.4,label,label+0.3,end --sheet storyboard --url http://localhost:8765/<book>/` (a mark plus an offset is the moment the action is timed to).- **`pre`** in the fourth slot (`{ pre: 1.2 }`) runs the picture that many seconds before the narration starts: an action, then the line. Picture books use it on every scene.-- **`minDur`** in the fourth slot (`{ minDur: 9.4 }`) *(v2.7)* is the least the whole beat lasts, hold included, as `?lengths` reports it: two mirrored beats (two answers treated alike) get the longer one's length.-- **`dur`** in the fourth slot (`{ dur: 2 }`) *(v2.7)* makes a beat with no narration: no clip and no `TIMINGS` entry (the engine adds `{ dur, marks: {}, cues: [], silent: true }`), the picture runs `dur` seconds on wall time, then holds. A wordless card (a series card, an end card) needs no silence clip. A beat with a `TIMINGS` entry ignores `dur`.+- **`minDur`** in the fourth slot (`{ minDur: 9.4 }`) is the least the whole beat lasts, hold included, as `?lengths` reports it: two mirrored beats (two answers treated alike) get the longer one's length.+- **`dur`** in the fourth slot (`{ dur: 2 }`) makes a beat with no narration: no clip and no `TIMINGS` entry (the engine adds `{ dur, marks: {}, cues: [], silent: true }`), the picture runs `dur` seconds on wall time, then holds. A wordless card (a series card, an end card) needs no silence clip. A beat with a `TIMINGS` entry ignores `dur`.- **`hold`** in the fourth slot of an `ask` beat in a film (`CHAPTER.film`) is read only by `export.py`: the seconds the video holds the waiting picture before it plays on as if the reader had acted (1.5 by default). The page ignores it.- **The end of a film**: a chapter whose last beat asks nothing (a picture book) is finished when that beat ends: it is marked done and, with `CHAPTER.next`, offers the next chapter (Enter).- **Seeking replays**: jumping to beat N rebuilds the scene and runs earlier beats instantly. Make `run` deterministic: create objects and schedule tweens through the timeline, with inputs from chapter data and replayed `S` state. Create interactions inside `ask`; use `fx`/`fxp` for answer effects.@@ -77,7 +90,7 @@ A book whose formulas need more than `M()` parts (indices, sums, matrices, accenFor continuous motion (vehicles, orbits, rolling, scrolling scenery) and camera work. Everything is a pure function of the beat time, so pause, seek and `?beat=N&t=S` show the same frame.-- `clockRun(f, D)` calls `f(t)` on every frame of the beat, `t` in seconds from its start (0..D); the beat's hold after `D` shows `f(D)`. With `clockRun(f, D, { tail: true })` *(v2.1; an older engine ignores `tail`, so the hold stands still)* it keeps calling `f` through the hold, `t` up to the beat's end (`P.end`: the later of the narration and the last tween that is not a tail, plus `HOLD`; a tail's own `D` no longer lengthens the beat *(v2.6)*): use it where motion must never freeze (a film, whose next scene cuts in), and let `f` pose sensibly past `D`. `f` also gets that end, `f(t, end)` *(v2.6)*, so a move can land on it (a whip out, a dive into the next scene): under music it is where the beat really leaves, up to `HOLD` early, and at the end a tail stays where the clock is rather than jumping. A camera in a beat with a tailed `clockRun` runs on to `P.end` too, so a follow shot keeps up; in a beat without one, a camera's `D` is its length and does not lengthen the beat. Write positions as functions of `t` (`x = x0 + v * t`) and share them between objects and the camera; never accumulate per-frame state.+- `clockRun(f, D)` calls `f(t)` on every frame of the beat, `t` in seconds from its start (0..D); the beat's hold after `D` shows `f(D)`. With `clockRun(f, D, { tail: true })` it keeps calling `f` through the hold, `t` up to the beat's end (`P.end`: the later of the narration and the last tween that is not a tail, plus `HOLD`; a tail's own `D` no longer lengthens the beat): use it where motion must never freeze (a film, whose next scene cuts in), and let `f` pose sensibly past `D`. `f` also gets that end, `f(t, end)`, so a move can land on it (a whip out, a dive into the next scene): under music it is where the beat really leaves, up to `HOLD` early, and at the end a tail stays where the clock is rather than jumping. A camera in a beat with a tailed `clockRun` runs on to `P.end` too, so a follow shot keeps up; in a beat without one, a camera's `D` is its length and does not lengthen the beat. Write positions as functions of `t` (`x = x0 + v * t`) and share them between objects and the camera; never accumulate per-frame state.- `const cam = camera(parent, D, { x, y, z, r, box, bg })` makes a view onto a world group. Draw in `cam.world` in world coordinates. The view `{x, y}` is the world point shown at the centre, `z` the zoom (screen px per world px), `r` the roll in degrees. Defaults: full stage, `(800, 450)`, `z` 1 (identity, so stage coordinates still work). With `box: [x, y, w, h]` the camera draws in a framed, clipped box with background `bg` (split screen, picture-in-picture); its default zoom fits the 1600 × 900 world into the box. `cam.el` is the camera's group (fade, pop or hide it; it scales about the box centre).- Moves, all on the beat clock: `cam.to({x, y, z, r}, t0, dur = 1, ease = soft)` blends only the keys given, from wherever the camera is at `t0`; `cam.cut(view, t0)` is a hard cut (`dur` 0); `cam.shake(amp, t0, dur, hz = 7)` is a subtle, repeatable shake (fades in and out over 0.3 s). Any key may be a function of `t`: that is a follow shot (`cam.to({ x: t => carX(t) }, 2, 1.5)` locks on over 1.5 s; `r: t => spin(t)` rolls with a rotating object). Zoom changes evenly (log scale) and keeps one world point fixed when start and end allow it.- Parallax: `cam.layer(k, wrap)` returns a group inside the world that moves at `k` × the camera's pan (`k` < 1 far, > 1 near; zoom and roll are not scaled per layer). With `wrap = W` the layer's content repeats every `W` world px: draw one period plus the widest view, and the camera can pan any distance. Keep repeating details (dashes, tiles, trees) on a period that divides `W`, and move followed objects by multiples of `W` when they loop, so the loop is invisible.@@ -92,33 +105,18 @@ Firefox repaints SVG on the main thread and is the slowest common browser for th- Never put an SVG filter behind animated content (the stage grain is a static CSS texture for this reason). Avoid clip-paths on moving or zooming groups where a box or an image does the job.- Large shapes under a big camera zoom or roll are expensive: a filled `<circle>` scaled 6× and rotating cost about 200 ms a frame in Firefox, while the same picture as one `<image>` cost about 3 ms. Prefer one image for a big detailed object (a planet, a map), and few elements over many small ones (merge cells into one path per colour, or use an image).-- Write per-frame attributes and text only when they change (`render()` already skips unchanged transform and opacity). A panel replaced at the start of a beat leaves the page after its fade, and at once while seeking *(v2.6)*; one replaced later in a beat is set to `display: none`. A removed node measures as nothing (`getBBox`, `getComputedTextLength` give 0, `getSubStringLength` throws) and its ids no longer resolve (`url(#…)`, `<use href>`): keep what a later beat measures or refers to outside a panel.+- Write per-frame attributes and text only when they change (`render()` already skips unchanged transform and opacity). A panel replaced at the start of a beat leaves the page after its fade, and at once while seeking; one replaced later in a beat is set to `display: none`. A removed node measures as nothing (`getBBox`, `getComputedTextLength` give 0, `getSubStringLength` throws) and its ids no longer resolve (`url(#…)`, `<use href>`): keep what a later beat measures or refers to outside a panel.- Pixel-art sprites: draw `<image>` with `style="image-rendering: pixelated"` at an integer scale, and pre-scale the file (nearest neighbour) so it stays crisp where the style is ignored.- A `<canvas>` in a `foreignObject` is re-rastered on every frame in Gecko when a parent group scales or moves it: a canvas map pushed by a scaled wrapper got slower, not faster. Move a canvas through its own view (redraw it from `t`), or hold it still and move what lies over it; never scale its parent.- Cross-fading two full-screen cameras costs a long frame: fade only the incoming one in over the outgoing one, then hide the old.- A question card's entrance after a busy scene can hitch; measure it with `perf.py`.-## Questions--```js-quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'], build: blanks([...]) }, …], done, 'Quick check')-```--- Positions: `BAND` (bottom band, y 686–886; long content can push it past the stage, so check it), `TOPR` (top right, ≤ 470 high), `RIGHT`, `SCREEN` (full-screen practice; the label names the set in the book's language, such as `'Chapter practice · set 1 of 2'`, and the engine appends "· question k of n" when a quiz has several questions), `SORT_SCREEN`, or any `{x, y, w, cls: 'side'}`.-- `choice(options, right, why, wrongWhys[], onRight?)` — number keys.-- `mcq(id, onRight?)` — (course option, [courses.md](courses.md)) a whole quiz entry (`{id, prompt, build: choice(...)}`) from the chapter's item bank: `quiz(TOPR, [mcq('c-attrib'), mcq('c-cause')], done)`. Needs `items.js` (built by `scripts/items.py`) loaded after `engine.js`; an unknown id throws.-- `blanks(rows)` — rows `{parts: [..., {box: '21'}, ...], why, hint?, fx?, test?}`; accepts −5, 3/4, 2 1/4, 0.75 as exact values and, *(v2.1)*, with a currency sign ($60, 5 €) and thousands grouped by spaces of any kind (1 250, as [authoring.md](authoring.md) shows numbers) or, where the decimal sign is a point, by commas (1,250); `{box, lowest: true}` demands lowest terms; `test(values)` judges the whole row (e.g. two factors in either order). `hint` is one message for any wrong value in its row; when different mistakes need their own answers, split the step into rows or ask it as a `choice` with `wrongWhys`. Tab moves between boxes, Enter checks, Esc leaves a box.-- `grid(rows, cols, {multi, text})` — rows `{parts, ans: [keys], why, fx?}`, cols `[[key, label, colour?, hotkey?]]`; with `text: true` parts are rich text (math via `$m`). ↑/↓ change rows.-- `tap(values, right, why, v => wrongWhy, onRight?)` points on the number line; `tapEls(row, idx, right, …)` tokens of a `tokens` row; `pickEls([{el, box: [x,y,w,h], label}], right, …)` any drawn objects; `pickPoint(P, [x,y], why, (x,y) => wrongWhy, onRight?, test?)` grid points (arrows + Enter or click); `sorter(items, trayXY)` drag into the set diagram (keys 1–6). `pickPoint` and `sorter` are in math.js.-- Answer animations run on their own clock: `fx`, `fxp`, `pulseFx`, `shakeFx`, `floatText`, `qlayer()` (a layer cleared with the question). They are finished automatically when the beat is left.-- A new type: `build(body, api)` returns `{ reveal, check?, lock?, key?(e), hint? }` and calls `api.grade(ok, message, {right, total})`. `key` handles its shortcuts (return true when used); `hint` lists the keys under the prompt. Every action needs a key; the help overlay (`?`) lists the global ones.-- Scores: `SCORE[id]` keeps the first try across revisits and step jumps; restarting the chapter clears it. A multi-row question scores one per row. A correct retry changes the feedback, not the first-attempt score.## 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); a beat's last caption clears a second after its narration, so it does not sit on a closing title *(v2.4.2)*; a line in another language with a `sub` (`tts.py`, `eleven.py`) shows its subtitle even with captions off *(v2.4.1)*, `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen *(v2.5)*: the stage fills the screen, and the controls lie over its foot, showing while the pointer moves or a key is pressed, while paused and while the pointer is on them (a touch screen, with no hover, keeps them under the stage); full screen also turns the screen to the stage's orientation where the browser can lock it (Android, not iOS), and on a phone held across the stage, starting the chapter goes full screen that way, so a landscape lesson is not a strip on an upright phone, ? help (it lists the question keys only in a chapter with questions, and a film with questions can leave them out with `CHAPTER.questionKeys = false` when its moments have their own controls *(v2.6)*). 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.+Space play/pause, and once the chapter has ended replay, ←/→ 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); a beat's last caption clears a second after its narration, so it does not sit on a closing title; a line in another language with a `sub` (`tts.py`, `eleven.py`) shows its subtitle even with captions off, `<`/`>` speed (0.75–1.5×, remembered), volume (remembered, except muted), F full screen: the stage fills the screen, and the controls lie over its foot, showing while the pointer moves or a key is pressed, while paused and while the pointer is on them (a touch screen, with no hover, keeps them under the stage); full screen also turns the screen to the stage's orientation where the browser can lock it (Android, not iOS), and on a phone held across the stage, starting the chapter goes full screen that way, so a landscape lesson is not a strip on an upright phone, ? help (it lists the question keys only in a chapter with questions, and a film with questions can leave them out with `CHAPTER.questionKeys = false` when its moments have their own controls). 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. `?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); effects are fetched and decoded when `sfx()` is called, before the first click *(v2.6)*; one still loading when it is due plays late, from its start, 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; called above `BEATS`, it takes them all when `boot()` runs *(v2.7)*, and a listed id that `BEATS` lacks is named in a console warning). Its place is the length of its earlier beats as they really ran plus the clock; a beat under music gives back from its closing hold the time the clock stood still (a clip getting going), so the film keeps the music's time *(v2.4)*. 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. Safari and every iOS browser stall a media element at each speed change, so there the music keeps the film's speed and is put back by a seek once it is a quarter second out, aimed ahead by the lag it showed after the last one *(v2.4.1)*. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.+**Sound effects and music**, in films only: in a chapter with a question, `sfx()` and `music()` are silent, unless the chapter sets `CHAPTER.film = true`: 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); effects are fetched and decoded when `sfx()` is called, before the first click; one still loading when it is due plays late, from its start, 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; called above `BEATS`, it takes them all when `boot()` runs, and a listed id that `BEATS` lacks is named in a console warning). Its place is the length of its earlier beats as they really ran plus the clock; a beat under music gives back from its closing hold the time the clock stood still (a clip getting going), so the film keeps the music's time. 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. Safari and every iOS browser stall a media element at each speed change, so there the music keeps the film's speed and is put back by a seek once it is a quarter second out, aimed ahead by the lag it showed after the last one. `export.py` reads `SFX`, `BGM` and these settings and mixes the film by the same rules.Progress is saved under `animebook:progress:<book-path>`; the cover and a picture book's series page read 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.@@ -134,7 +132,7 @@ Keep `<link rel="expect" href="#bar" blocking="render">` in every chapter's head- A `prog` or `clockRun` that redraws only when a key changes (a 12 fps frame number, a step index) must draw from the key's own value (`f / FPS`), not the exact `t` that crossed it: playing, seeking and `?beat=N&t=S` reach the same key at different `t`, and must show the same picture.- In a JS string, double each TeX backslash (`'\\frac{a}{b}'`) or use `` String.raw`\frac{a}{b}` ``: `'\text'` is a tab followed by "ext".- Write a formula wholly in TeX, an `eqLine` sign included (`sym: TX('\\le')`): TeX glyphs are smaller and lighter than `M()` text.-- **Global names.** The engine keeps its own state and helpers in a closure *(v2.7)*: a chapter may use any other name (`clock`, `fit`, `frame`, `last`, `ui`, `segs`, …; an older engine declared those too), and the engine calls its own functions: replacing one from outside (`window.start = …`) no longer reaches the engine; watch `P` instead. The names it puts in global scope are the API: `TRANSLATIONS PORTRAIT SW SH LANGUAGE translate DECIMAL_SIGN isShortcut NS UI BOOK bookSetting COL MATH NAME BAND RIGHT TOPR SCREEN SORT_SCREEN $m mk st put render G path T cite ctx2d textW F R E TX $tex texGraphic texPart OV M chip tokens layRow collapse mathEl io out back lin tw prog show hide draw pop pulse stream mix evalTo soft clockRun camera scene S AXIS X Y0 num reset tick dot arrow panel retire header fx fxp finishFx pulseFx shakeFx floatText TF $ kbd sources uiW SCORE h rich card mascotEl quiz qlayer keyAct choice mcq tap tapEls pickEls grid rat gcd lowest blanks SND P HOLD clearCards seek seekInto start setSpeed setPlaying setCaptions hideCover restart boot ENGINE seeking captions finishCard BOOK_PROGRESS_KEY progress`, plus the window properties `sfx music SFX SFX_BED BGM MathJax`. A chapter that declares one of them again stops with an error; prefix chapter helpers that would (`rect`, `popIn`, `eqLine`, `slot` from math.js too, when the chapter loads it). `lint.py` lists every clash, each name of a `const a = 1, b = 2` included. `finishCard` and `progress` stay assignable for `scorm-bridge.js`, which wraps them.+- **Global names.** The engine keeps its own state and helpers in a closure: a chapter may use any other name (`clock`, `fit`, `frame`, `last`, `ui`, `segs`, …; an older engine declared those too), and the engine calls its own functions: replacing one from outside (`window.start = …`) no longer reaches the engine; watch `P` instead. The names it puts in global scope are the API: `TRANSLATIONS PORTRAIT SW SH LANGUAGE translate DECIMAL_SIGN isShortcut NS UI BOOK bookSetting COL MATH NAME BAND RIGHT TOPR SCREEN SORT_SCREEN $m mk st put render G path T cite ctx2d textW F R E TX $tex texGraphic texPart OV M chip tokens layRow collapse mathEl io out back lin tw prog show hide draw pop pulse stream mix evalTo soft clockRun camera scene S AXIS X Y0 num reset tick dot arrow panel retire header fx fxp finishFx pulseFx shakeFx floatText TF $ kbd sources uiW SCORE h rich card mascotEl quiz qlayer keyAct choice mcq tap tapEls pickEls grid rat gcd lowest blanks SND P HOLD clearCards seek seekInto start setSpeed setPlaying setCaptions hideCover restart boot ENGINE seeking captions finishCard BOOK_PROGRESS_KEY progress`, plus the window properties `sfx music SFX SFX_BED BGM MathJax`. A chapter that declares one of them again stops with an error; prefix chapter helpers that would (`rect`, `popIn`, `eqLine`, `slot` from math.js too, when the chapter loads it). `lint.py` lists every clash, each name of a `const a = 1, b = 2` included. `finishCard` and `progress` stay assignable for `scorm-bridge.js`, which wraps them.- Drag handling: re-parent (append) the element before `setPointerCapture`; moving a node drops its capture.- A card whose content is too long for `BAND` should become several `blanks` rows in a wider side card.- When a question beat is continued early, the engine finishes the beat's pending tweens first; don't rely on half-finished fades.diff --git a/.claude/skills/papermorph/references/core/publish.md b/.claude/skills/papermorph/references/core/publish.mdnew file mode 100644index 0000000..3144b29--- /dev/null+++ b/.claude/skills/papermorph/references/core/publish.md@@ -0,0 +1,48 @@+# The book folder, preview and export++The book is static: HTML, JS, CSS, MP3. No build step, backend, database or accounts; reading progress lives in the browser (`localStorage`). The runnable output is `site/<book>/`; source material and production notes stay outside it.++## Start a book folder++Once per new slug, from the folder that holds `site/`, `books/`, `content/` and `tools/`:++```sh+python3 SKILL/scripts/new_book.py lesson|picture|documentary|shorts <book> [--chapter N] [--lang xx] [--maps]+```++It runs `engine.py` into `site/<book>/lib/` (the engine, plus `lib/book.css` for this book's settings), copies the tier's kit and templates (the chapter page, the cover or series page, the sample narration, a picture book's paper kit and `sets.js`, a film's `film.js` or `shorts.js`, and with `--maps` the map kit), makes the working folders and prints the next commands. It refuses a slug whose `site/<book>/` exists; resume an existing book from its own files. What each tier does next is in its own file.++## Every book++- Use the agreed primary language: the narration source is `narration.<lang>.json`, the chapter loads `audio/<lang>/timings.js`, and `CHAPTER.language` matches (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` from `style.json`, and translate the template's own visible text (titles, lede, prompts) before the pilot.+- A chapter's minutes appear on its title screen (`CHAPTER.minutes`), its contents card and a series card; write the same number in each: the length of its audio (the `dur`s in `timings.js`) plus about 15 s for each question, rounded to whole minutes and never below 1.+- Each book has its own engine copy, kept in step with `engine.py` ([core/engine.md](engine.md)). The engine and the cover or series page derive the same progress key from the book's URL folder (or `--progress-key` in `lib/book.css`), so moving a book to another folder resets its readers' progress unless the key is set.+- A chapter returns to its book's index; the book opens directly at `/<book>/` and needs no parent index page. Every chapter but the last sets `CHAPTER.next` to the next one.+- The infinity guide comes with the engine (`mascotEl` in `engine.js`, the cover's in `contents.js`), so a book's copy is replaced at every sync. A custom guide needs a hook in the engine itself; agree it with the user and change the engine at its source.++## Local preview and delivery++Serve the static output over HTTP, which audio playback needs:++```sh+python3 SKILL/scripts/serve.py 8765 site # no-store, so edits are never hidden by the browser cache+```++Open `http://localhost:8765/<book>/`. Confirm the index opens its chapters, chapters return to it, and any reference links open their works. Deliver `site/<book>/` with its HTML, scripts, styles and audio, the preview command and entry URL, the available chapter count and unresolved issues. Source PDFs, extracted pages, narration drafts and development environments are not part of the static book. Putting a book on a bookshelf and hosting it are separate tasks.++## Languages++Narration and on-screen text are written in one language first. A second language comes after the book is done and approved: keep beat ids and question ids stable, add `narration.<lang>.json` and audio per language, and decide with the user how switching behaves mid-chapter before building it.++## Video export++```sh+uv run --with playwright --with numpy SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <chapter URL>+```++It renders the beats to `OUT/chNN.mp4` (1080p, or 1080 × 1920 on the upright stage; 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, effects and music), so the video matches the page.++- A lesson's question beats are left out and its video ends on a card pointing to the interactive lesson. In a film with `CHAPTER.film`, they stay in: each holds its picture for the beat's `hold` s, the music up at 70 % as the page plays it while it waits, then the next beat plays as if the reader had acted ([documentary.md](../films/documentary.md#interactive-moments)).+- A mix that would clip is turned down as a whole, and the run says by how much; odd sizes are cut to even ones (an upright `--height 720` gives 404 × 720). The video is written beside the old one and renamed when done, so a failed run leaves an earlier `chNN.mp4` alone.+- It takes about seven times the film's length at 1080 × 1920 (a 98.5 s short took 11 min 42 s); `--height 720 --fps 10` makes a quick check copy.+- Video files are large (an episode at 1080p is tens of megabytes, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.diff --git a/.claude/skills/papermorph/references/core/review.md b/.claude/skills/papermorph/references/core/review.mdnew file mode 100644index 0000000..81066cd--- /dev/null+++ b/.claude/skills/papermorph/references/core/review.md@@ -0,0 +1,57 @@+# Seeing your own work, and review rounds++Watch your output in motion and judge it as a viewer would, against the storyboard and the approved chapters; fix what you find, recheck those parts, then deliver for the user's judgement. Serve `site/` with `serve.py` ([core/publish.md](publish.md#local-preview-and-delivery)) and keep the evidence in `books/<book>/review/chNN/`. Each tier adds its own checks and what to look for: [lessons](../lessons/checks.md), [picture books](../picture-books/stories.md#review-rounds), [films](../films/films.md#review-rounds).++## Contents++- Static checks first+- Watch it in motion+- Frames+- Smoothness+- Review rounds+- The user's notes++## 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. `uv run --with playwright SKILL/scripts/check.py chNN --url …` then opens every beat in Chromium and Firefox and reports page errors, console warnings and each beat's length against its voice (a tween running past the voice lengthens a beat silently).++## Watch it in motion++```sh+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:2..4/0.2@o walk:1..5/0.1@o@c+uv run --with playwright --with pillow SKILL/scripts/playlog.py chNN --out OUT --url http://localhost:8765/<book>/+```++- A strip shows one beat at small steps, and a sheet of strips is the contact sheet every review works from. `@w` adds a motion WebP; `@o` adds an onion skin, the same frames laid over each other, later ones stronger, so spacing reads at a glance: even gaps are even speed, bunched ghosts are easing, a ghost that jumps is a pop. An onion skin reads only within one shot, so give it that shot's range (`roll:2..4`, ends may be marks); `@c` draws a picture book's frames in the set's own framing, so under a pan a planted foot stays one sharp ghost and a sliding one smears.+- Look at each action as a viewer would: does the picture do what the narration says while it is said, does the thing named appear on screen, do props stay in hands, does the camera move with purpose, do labels and numbers agree with the motion? The worst defects in the first films were pictures that contradicted the narration, and they show on a contact sheet at once.+- Watch every beat to its end; 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 (in a picture book it switches off the kit's hand jitter and flicker first, so a puppet that only breathes and blinks measures about 1–1.5 and acting 2 and up; its default threshold is 1.5). Some holds are right (a moment to read a result); something that stands for motion should be moving whenever it is on screen.+- Then watch a few beats live in Firefox with sound, which is how the user watches. An agent that cannot listen runs `playlog.py`: it logs when each sound and caption starts in real playback and shows the stage rebuilt at that moment, so a clack can be checked against the piece landing and a line against the mouth that says it. `--from`/`--to` play only some beats; a lesson stops at its first question.++## Frames++```sh+uv run --with playwright --with pillow SKILL/scripts/shot.py chNN --url http://localhost:8765/<book>/ --out OUT [--cuts] [--clean]+```++`shot.py` captures the open and end frames of every beat as 4-up sheets and reports console errors; full-size `chNN_bII_T.png` files show thin geometry the sheet hides. Look for an empty or unrelated opening, text over drawings or clipped at the edge, a card covering what it asks about, leftovers half faded, text too small at half size or too much at once, and the same idea in different colours. `--cuts` puts each beat's last frame beside the next one's first, one cut a row: look there for jumps in place, pose, light and screen direction. `--clean` gives the stage alone, without the player.++## Smoothness++`uv run --with playwright SKILL/scripts/perf.py chNN --url …` measures frame times in Firefox, which repaints SVG on the main thread and is the slowest common browser for these pages; headless Chromium hides paint cost. Look at the worst beats and transitions; the remedies are in [core/engine.md](engine.md#performance-firefox). Under load the machine is measured, not the page: with six workers exporting, a 16.7 ms beat read 48 to 109 ms. `perf.py` prints the load average and warns above the core count, and `--ref CH:BEAT[@T]` times a known moment in the same run to read a number against. The frame time that decides is taken on a quiet machine.++## Review rounds++After the first cut, before the user watches, an independent director pass: a fresh agent on a strong model, report-only, given contact sheets of every beat and the approved chapters or reference film, with no knowledge of how the beats were built.++- **Reports** are ranked: chapter or scene, beat-clock time, what is wrong as a viewer sees it, a concrete fix. Earlier good reports serve as examples. About half of what a director finds is usually the picture saying something other than the voice.+- **A second round on the exported video** (`export.py`, then the director watches the MP4's frames) finds what the sheets hide; on the shorts it was the round that found most.+- **Check what a director measured** before sending it back as work, and after the fixes take a quick look yourself at the new frames: one such look still found a wrong date and a dead frame.+- **Merging**: the coordinator turns the reports into one rework list, taking the director's side where reviewers disagree, and sends the parts back to the workers who made them.+- **Closing**: the next round starts by checking which findings were fixed; a last read-only pass counts them as fixed, partly fixed, not fixed or worse. Two or three rounds made the best episodes. Show the user each fix on a contact sheet as it is made, so a round is quick to check.++A chapter the Skill made is a first cut: the rounds come before the user watches, and what the user says then still decides.++## The user's notes++Deliver 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.diff --git a/.claude/skills/papermorph/references/core/sound.md b/.claude/skills/papermorph/references/core/sound.mdnew file mode 100644index 0000000..e3e0ba9--- /dev/null+++ b/.claude/skills/papermorph/references/core/sound.md@@ -0,0 +1,63 @@+# Narration, voices, effects and music++Voices carry every book; everything else sits under them. In early cuts the music and effects were loud enough that the lines got lost, and that was the first thing viewers noticed. How each tier uses sound is in its own file (a picture book's mouths and scene clips in [stories.md](../picture-books/stories.md#sound), a film's tracks in [films.md](../films/films.md#voice-and-music)); this file is the shared part.++## Contents++- The narration file+- Voices+- Levels+- Sound effects+- Music+- Captions and other languages++## The narration file++`content/<book>/chNN/narration.<lang>.json`, one entry per beat (each kit has a sample):++```json+{ "voice": "en-US-AndrewNeural", "rate": "-4%",+ "beats": { "intro": "Chapter five. [[sub]]Subtraction undoes addition.", "...": "..." } }+```++- `[[name]]` goes right before the word an action waits for; `m('name', offset)` in the page returns when that word starts. Names are unique within a beat; a misspelt mark makes the page throw, and a mark that matches no spoken word makes the voice script stop.+- Write for the ear: short sentences, one idea each. Say symbols, units and numbers in words ("negative seven halves", "meters per second squared"); the picture shows the symbols. Match the audience: plain, warm, never childish.+- A wordless beat (a series card, an end card) needs no clip, no `timings.js` entry and no narration line: `{ dur: 2 }` in its fourth slot ([core/engine.md](engine.md#timing)); `lint.py`, `export.py`, `music.py` and `check.py` take it as silence. A time only the page needs goes in the page, not in `timings.js`, which the next voice run rewrites.++## Voices++- **`tts.py`** (free): `uv run --with edge-tts SKILL/scripts/tts.py <narration.json> site/<book>/chNN/audio/<lang>` writes `<beat>.mp3` and `timings.js` (duration, marks, captions) and caches each finished beat beside the narration file: moving `[[marks]]` reuses the cache, and after a failure the same command resumes. It takes a few seconds a beat, so a long chapter can outlast a tool's foreground time limit: run it in the background and wait for it before `lint.py`.+ - `"engine": "edge"` (default, online) or `"kokoro"` (local, Apache 2.0, English word timings; voices such as `am_michael`, `af_heart`, `bm_george`; `uv run --python 3.12 --with kokoro …`), set at the top of the narration file with `voice` and `rate`. Keep one engine and voice per book (per character in a picture book).+ - Edge's `...MultilingualNeural` voices guess the language sentence by sentence and read a short line such as "No zero, no fractions, no negatives." with a Spanish or Portuguese accent; a book in one language uses a one-language voice of that language.+- **`eleven.py`** (ElevenLabs v4 through OpenRouter, paid, an OpenRouter key): the voice the user chose for the films. It writes the same clips and `timings.js`; the page cannot tell them apart.+ - It takes the voice and model from `--voice` and `--model`, else from the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`; the kits' files name an Edge voice).+ - It prints the cost before paying (`--dry` stops there; about $0.07 a minute, quote it), keeps paid clips cached (a rerun costs nothing), and `--only beat,beat` makes a fresh, paid take of those beats alone.+ - A voice sped up (`--tempo 1.1`, or `"tempo"` in the narration file) is sped before levelling and alignment, and stays sped on a rerun. `--max-pause 0.3` shortens its sentence pauses (0.4 to 1.0 s) before the marks are placed.+ - v4 audio tags such as `[cackles]` are acted, not read, and left out of the captions and of `lint.py`'s comparison of narration and page.+ - Its word alignment (local faster-whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now. The transcript writes spoken numbers as digits; `eleven.py` matches them back and prints the marks a rerun moved, but check marks on numbers, since a missed one lands late (up to 0.75 s).+- **Several voices.** List them under `voices` in the narration file and write each line as `{"speaker": name, "text": …}`; a line without a speaker takes the file's own `voice`, and a speaker missing from `voices` stops the run, naming it. Both scripts do this. Voices need pitches apart (a dog at 113 Hz under a 110 Hz narrator read as the same person).+- Let the user pick a voice by ear: play a few short samples in the book's own words.++## Levels++`level.py <clips>` brings clips to one loudness under a limiter without moving a word, and leaves an already level clip, or one under 0.4 s, as it is, so it can be rerun. A film's voice goes out at −14 LUFS with its peak under −1.5 dBTP: `eleven.py` levels its clips and prints what it delivered (the service alone gives about −23 LUFS, which sank one episode under its music; `--lufs` for another level, `--no-level` to keep the service's); after `tts.py`, run `level.py --lufs -14 --peak -1.5`. A picture book's scene clips sit at `level.py`'s default −18 LUFS ([stories.md](../picture-books/stories.md#sound)). A line that must sit above the rest gets its own target and stays out of the others' list, so a rerun leaves it alone; `--gain` adds again on every run, so it suits a one-off fix.++## Sound effects++`sfx.py` synthesizes effects as small MP3s, free and consistent (knock, door, creak, bell, chop, crash, coin, rain, wind, room tone, surf, gulls, crickets, footsteps, a dog, whoosh, bang, tick, thud and more; `--list` names them all). A sound the list lacks goes in the book's own `books/<book>/sfx_recipes.py`, passed with `--recipes`: each top-level function without required arguments is a recipe named after it, returning samples at `sfx.SR`, built from sfx's own helpers (the script's header has the details). Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain.++- Place an effect on a beat's clock with the engine's `sfx(beat, t, name, volume)` (in a picture book each scene is a beat); it plays at half volume under the voices (vol 2 is full), a pause holds it and the next beat stops it. Cut an effect to its shot: a six-second rain under a one-second shot spills into the next.+- A long bed (wind, room tone, the 10 s `birds` of a park) is listed in `SFX_BED` with its length (`SFX_BED.birds = 10`), so a seek into the middle joins it part-way; a bed that loops overlaps its seams by about half a second; room tone runs under the silences too, where its absence is heard first.++## Music++`music(file, beats, gain, fade)` in the chapter page, one call per track ([core/engine.md](engine.md#player) has the mechanics): it ducks to 30 % for the whole of every beat, voice or not, rises to 70 % in the `pre` lead-in of the beats in `window.MUSIC_UP_IN_PRE`, crossfades over `fade` seconds (0.8; 0 is a cut), and `window.MUSIC_OFF = { beat: t => … }` fades it out for a moment. Music does not stop dead mid-scene: carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place.++- **Where it comes from.** Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them. `commons.py --audio` finds public-domain recordings. A composition can be centuries old while its recording is still protected: Commons marks some 1950s–60s recordings public domain under EU rules that the US does not follow (protected there until 2067), and `commons.py`'s licence check cannot see this. Prefer recordings their performers released (PDM-owner, CC0), Musopen, or US military bands. Generated music (Lyria) is made outside the Skill for now.+- **Cut to the film.** `music.py cut SRC site/<book>/chNN/audio/bgm/NAME.mp3 chNN --url …/<book>/` cuts a recording so its last note lands on the film's end (the last moment it is within 10 LU of its body, so a long decay rings past the end; `--end` sets it by hand) and levels it to −16 LUFS. `--rests` splices out its rests and `--even` evens out its quiet phrase ends (a generated track usually needs it too: its quiet passages fall into the voice's gaps just as a recording's do), `--lift T` raises a hole neither fixes. The cut is made for one length: after any change to a beat's length, cut again (`gaps` says "recut").+- **Level by ear, check by measure.** Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the ducking to 30 %, a track at −16 LUFS sits about 20 LU under a −14 LUFS voice, the level the user chose for the first short. The gain is relative to the track's own loudness, so give both. `music.py gaps chNN --url …` lists the bed's loudness in each voice-free gap and after the last word and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.++## Captions and other languages++- Captions come from the narration and appear when their words are heard. A beat's last caption clears a second after its narration.+- **Lines in other languages** are spoken in their own language by a native voice (Edge has Japanese, Chinese, Korean and more) and subtitled in the book's language: write the beat's `"sub"`, the original and the translation in brackets. The voice script marks such a line (its voice's locale differs from the narration file's language), so the page shows its subtitle even with captions off, the way films subtitle foreign dialogue.diff --git a/.claude/skills/papermorph/references/core/style.md b/.claude/skills/papermorph/references/core/style.mdnew file mode 100644index 0000000..c2c5a82--- /dev/null+++ b/.claude/skills/papermorph/references/core/style.md@@ -0,0 +1,54 @@+# The conversation and style.json++A cold agent has no idea what the user wants, and its guesses diverge from run to run. Every book therefore starts with a short conversation whose outcome is `books/<book>/style.json`, the anchor every chapter is made against. It fixes *what* the book looks and sounds like; *how* each moment is animated stays free. Each tier's intake says what to ask ([lessons](../lessons/intake.md), [picture books](../picture-books/stories.md#intake-for-a-story), [films](../films/films.md#intake)); this file is how to ask, the models step and the file itself.++## Asking++- Many users want to click, not type. Every point where you need the user, from finding the source to approving the finished chapter, is a choice: two to four concrete options drawn from this book, the recommended one first and labelled so, so that accepting every recommendation still makes a good book. Use the structured question tool when there is one (at most four questions a round); otherwise number the options so a single digit answers. Their own words are always welcome, never required.+- Questions come from this book and this chapter, not from a form. Skip what the material or earlier answers already settle.+- After each round, say the answers back as decisions in one or two lines, then move on.+- Keep what the user says about the look **verbatim** in `words`; later chapters need their taste, not a summary of it. When they only pick options, record the chosen options' wording.+- The conversation should feel light: the user tries one chapter (or episode) first and decides about the rest after seeing it.++## 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 book's tier as one table, one row per step of that tier's team ([core/team.md](team.md)), and ask: keep it (recommended), or change some rows. Any model the user names is fine.++| Step | Lesson, tier 1 | Lesson, tier 2 | Picture book | Documentary | Short |+|---|---|---|---|---|---|+| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) | strong (research, script and storyboard with the user; then voice and music) | strong (the script and storyboard with the user; then voice and music) |+| Narration and beats | middle | middle | strong (voices, the episode kit) | middle (pictures found and treated) | middle (pictures generated or found) |+| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene | middle, one worker per part of the film | middle (the beats) |+| Checks | small | small | small (sound effects too) | small | small |+| Review | middle | middle | strong director, middle picture and sound reviewers | strong director | strong director |+| Rework | strong | strong | middle, per scene | middle, per part | middle |+| Register | small | small | 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`, keyed by step as in the [lesson](../../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`; a [documentary](../../assets/templates/documentary/style.json)'s and a [short](../../assets/templates/shorts/style.json)'s: `script`, `pictures`, `beats`, `checks`, `director`). 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.++## style.json++Start from the tier's template: [lessons](../../assets/templates/style.json), or the kit's own `style.json` for a picture book, a documentary or a short. Blocks are grouped by ability, not by tier; a tier is just which blocks are present:++| Block | What it holds | Present in |+|---|---|---|+| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"`, `"picture"`, `"documentary"` or `"shorts"`; title, slug, language, readers, pilot chapter | all |+| `words` | the user's own words about the look, verbatim, with later feedback that changed the bar | all |+| `look` | palette, what each colour means, text and maths fonts, notation and rounding | all |+| `voice` | TTS engine (`edge`; `kokoro` when Edge is unavailable or local audio is wanted; `eleven`, paid, for a film: [core/sound.md](sound.md#voices)), voice, rate | all |+| `pacing` | minutes per chapter, where checks and practice go | all |+| `engine` | engine source and version used to build the book | all |+| `scenes` | art style, cast, how storyboards are reviewed | lessons, tier 2 |+| `components` | shared elements: name, file, what each does | lessons, tier 2 (tier 1 when the book has some) |+| `images` | where images may come from, credit rules | lessons, tier 2 |+| `models` | the model for each step, as agreed above | all |+| `illustration` | a picture book's look, budget, cast and sets ([stories.md](../picture-books/stories.md#intake-for-a-story)) | picture books |+| `angle` | the one thing a viewer leaves with, and what must be in the film | documentaries |+| `music` | the music and where it came from | documentaries, shorts |+| `platform`, `source`, `series`, `sources` | the feed and export size; where the argument comes from (the user's outline or a long film); the series' name and each episode's point; how strict to be about sources ([shorts.md](../films/shorts.md#questions-for-the-user)) | shorts |+| `courses` | the course options chosen ([courses.md](../lessons/courses.md)) | when chosen |+| `approved` | chapters the user approved and what each shows well | filled as chapters are approved |++Leave out blocks the tier does not use. A reader that meets a block it does not know reads it as plain intent. Increase `schema` only when an existing field changes meaning. Keep the file current and short: chapter status, errata and historical feedback stay in `chapters.md` and `chapters/chNN.md`.++Deliver the pilot with a choice: approve and make the rest (recommended when it is good), approve and stop here, or one of two or three concrete changes you would make yourself. Fold the answer and any feedback into `words` and the affected block, and add an approved chapter to `approved`. Approved chapters are the strongest anchor: later chapters watch and read them as worked examples.diff --git a/.claude/skills/papermorph/references/core/team.md b/.claude/skills/papermorph/references/core/team.mdnew file mode 100644index 0000000..cea10bb--- /dev/null+++ b/.claude/skills/papermorph/references/core/team.md@@ -0,0 +1,33 @@+# Making a chapter with a team of models++A chapter can be made by a coordinator handing each step to a fresh subagent on the model that suits it. How a tier splits the work is in its own file: lessons by step of the chapter loop ([lessons.md](../lessons/lessons.md#team)), picture books by scene ([stories.md](../picture-books/stories.md#team)), films by part of the film or by episode ([films.md](../films/films.md#team)). Without subagents, run the same steps in the current agent with file-based state.++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.++Each step runs on the model the user chose for it (`models` in `style.json`, [core/style.md](style.md#models)). The defaults are named by strength: **small** (fast and cheap), **middle**, **strong** (the most capable); where `models` is silent, use them and say which model you picked.++## The coordinator++You read SKILL.md, your tier's file and this one, look at the sheets 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.++- For the pilot the coordinator is the main conversation, since the user sees its sheets and choices. The narration and first frames made at intake are where the steps start, not something to redo.+- After the pilot a fresh session is the best coordinator, starting from SKILL.md, the tier's file and `style.json`: a long conversation rereads its whole history at every step, and contact sheets make that history large fast.+- 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. Its brief adds the chapter, its pages, the step's inputs and outputs, what not to touch, any current user request, the preview URL (start one server for everyone) and a reply of a few lines. Start workers in the background and pass work on as soon as a step returns. Workers don't commit; the coordinator registers the chapter.+- Wherever a step names the previous or approved chapter as its model, a new book's first chapter (or a series' first episode) has none yet: use what the user agreed at intake (the pilot frames or sheet, the storyboard, `style.json`), the Skill's templates and the books on the shelf. The first chapter the user approves becomes the model from then on.+- A brief that only asks a worker to look gets skipped; name the commands to run and ask the reply to say what each showed.+- A shared kit (the episode's helpers, the film's pieces) is read-only for the workers: one that needs more asks the coordinator, so every part gets the fix.+- The chapter must reach the same bar as the book's approved chapters, in the same look, so it sits on the shelf beside them as one book.++## Before delivering++Check the reports against each other (an odd claim is worth one look at the file), confirm lint and the tests 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.++## Workers in parallel++Several episodes or parts made at once each get their own git worktree, branch and preview port (one server per worker, serving its own worktree's `site/`, and that port in every `--url`). What trips them:++- `books/` and `content/` are git-ignored, so a worktree has neither. `lint.py` finds them in the main checkout by itself; for everything else, give the brief's paths into them absolute, and no worker creates them in its worktree.+- A shared file every worker appends to (one `img/SOURCES.md` for six episodes) conflicts at every merge. Give each worker its own (sources per episode, sizes per episode with `prep.py --art chNN-art.js`), joined once after the merge, and keep the shared files read-only for the workers.+- The brief is the only rule book: say each file name and each shared file's rule once, the same in the common brief and in each worker's go. One run named the pictures two different ways in two places, and both forbade and invited edits to the sources file.+- Workers that share one paid balance make their pictures before their voice: `paint.py` stops while an OpenRouter balance is under $1.00, and whoever voices first can lock the others out of pictures.+- Under load the machine is measured, not the page ([core/review.md](review.md#smoothness)): a loudness or timing that one worker reports under load is worth one more measurement before anyone acts on it.diff --git a/.claude/skills/papermorph/references/documentary.md b/.claude/skills/papermorph/references/documentary.mddeleted file mode 100644index 940e6fe..0000000--- a/.claude/skills/papermorph/references/documentary.md+++ /dev/null@@ -1,91 +0,0 @@-# Documentaries: from a book or an idea to a film--A documentary is a narrated film about a book, an idea or a stretch of history: two minutes for one idea, ten or fifteen for a book's argument. Its pictures are mostly found: public-domain engravings, paintings and photographs, a few line drawings that draw themselves on, words set large, a map or two, all on one coloured ground and moved in step with a narrator. Usually the reader just watches; a film can also hand them the action at a few moments ([Interactive moments](#interactive-moments)). The published example is *Madness and Civilization* (after Foucault, ten minutes) on the shelf at https://papermorph.diamonddoge.org/. It is the approved reference for this kind of film: when in doubt, open it and match its level. *Shooting an Elephant* (after Orwell, nine minutes, https://papermorph.diamonddoge.org/shooting-an-elephant/) is the interactive one: the reader fires the rifle.--It shares the engine, the player, captions, previews, `export.py` and the team with every other book. What is its own: the kit `assets/templates/documentary/` (`chapter.html`, `narration.en.json`, `style.json`, `lib/film.js`, `lib/book.css`, `lib/fonts.css` and the fonts), the picture scripts (`commons.py`, `prep.py`, `trace.py`, `frames.py`, `video.py`), the voice script `eleven.py`, and the order of work below.--## Intake--The same spirit as [intake.md](intake.md): a short conversation, choices to click, the user's words kept. Settle, skipping what the request already settles:--1. **The subject and the angle.** What the film is about, and the one thing a viewer should leave with (Foucault: madness was not always locked up; each age decided what to do with it). Ask what must be in it: a scene, a quote, a person, an ending. What the user stresses is a theme to carry, not a thing to repeat: in the first film's first cut the two epigraphs appeared four times, which was overdone; they belong at the start and the end, with light echoes between.-2. **Length and audience.** Ten minutes holds one argument with five or six turns; a two-minute film holds one turn.-3. **The look.** One ground colour for the whole film (burgundy `#5a0e16` for Foucault, chosen from four tested with the actual pictures on them), two fonts (a condensed sans for key words, a serif for quotes and captions), and how found pictures are treated (below). Offer a ground test: three or four grounds with real pictures on them, side by side, before anything is built. The colours live in the book's `lib/book.css`, which `film.js` reads; pictures are baked to match with `prep.py --ink/--paper`.-4. **The voice.** The narrator carries the film, so the user picks it by ear. Offer both kinds: free voices (Edge TTS through `tts.py`, online, or Kokoro, local) and ElevenLabs (`elevenlabs/eleven-v4` through OpenRouter, with `eleven.py`: paid, an OpenRouter key). Play a few short samples of each in the film's own words. On the first film ElevenLabs was chosen over Edge. Characters can have their own voices (the Fool's giggle, a king's edict); ElevenLabs' v4 audio tags such as `[cackles]` are acted, not read, and left out of the captions and of `lint.py`'s comparison of narration and page.-5. **Music.** Classical music suits found pictures: one recording per part of the film, changing at the turns, never abruptly, at a level that never covers the narrator. Open with something short and rhythmic so the start is not slow. A composition can be centuries old while its recording is still protected: Commons marks some 1950s–60s recordings public domain under EU rules that the US does not follow (protected there until 2067). Prefer recordings their performers released (PDM-owner, CC0), Musopen, or US military bands (`commons.py --help`); `commons.py`'s licence check cannot see this.-6. **Budget.** Edge and Kokoro voices cost nothing; ElevenLabs about $0.65 for ten minutes (`eleven.py --dry` prints the characters and the estimate before anything is paid; quote it). A five-second clip from a still costs about $0.42. Pictures from Wikimedia Commons cost nothing.--Then agree the models ([intake.md](intake.md#5-models)) and write `books/<book>/style.json` from the kit's `style.json`: `tier: "documentary"`, the user's words, the angle, the look, the voice and the models.--## The order of work--1. **Research and the script.** Read the source, and trace every number and quote to where it was first said: a figure found on Wikipedia goes back to the speech or report Wikipedia cites, and that is the source to tag (Wikipedia's "low and middle-income" was the WHO's "low-income"). Read what each date counts, too: the day a virus arrived somewhere is not the day of its first confirmed case. Then write the narration (`content/<book>/chNN/narration.en.json` in the format of [authoring.md](authoring.md#narration), one beat per paragraph, `[[mark]]` before each word a picture lands on) and a storyboard table (`books/<book>/storyboard.md`: beat, what is said, what we see, which picture). Show both to the user before anything is built. The hard part of a documentary is the argument and the storyboard, not the animation.-2. **The folder.** `engine.py` makes `site/<book>/lib/` first, then the kit's `lib/` is copied over it (its `book.css`, with the film's colours, replaces the default); `chNN/index.html` starts from the kit's `chapter.html`, and the book's `index.html` from the picture-book series page. The commands are in [site.md](site.md#a-documentary).-3. **Pictures.** Find them, record them, treat them (below).-4. **Voice.** `tts.py` (Edge or Kokoro) or `eleven.py` (ElevenLabs) writes one clip per beat and `timings.js` with the marks; the page cannot tell them apart. `eleven.py` takes the voice and model from `--voice` and `--model`, else from the narration file's `voice` and `model` (an ElevenLabs voice name such as `george`: the kit's file names an Edge voice), and a line with a `speaker` from that speaker's voice under `voices`. It levels every clip to −14 LUFS with its peak under −1.5 dBTP and prints the loudness it delivered (`--lufs` for another level, `--no-level` to leave the clips as the service sent them, about −23 LUFS), keeps paid clips cached (a rerun costs nothing, and a clip levelled in place by `level.py` stays levelled), prints the cost before paying (`--dry` stops there), and `--only beat,beat` makes a fresh, paid take of those beats and leaves the others alone. A voice sped up (`--tempo 1.1`, or `"tempo"` in the narration file) is sped before levelling and alignment, and stays sped on a rerun. A line in another language takes a `sub`, as in `tts.py` ([sound.md](sound.md#voices)). Its word alignment (local faster-whisper) assumes words split by spaces, so a Chinese or Japanese film needs `tts.py` for now; `--help` has the rest.-5. **Music.** Find recordings (`commons.py --audio`), bring them to one loudness (`level.py`), and give each part of the film its track with `music(file, beats, gain, fade)` ([engine.md](engine.md#player)).-6. **The beats**, built from the kit's helpers and timed to the marks.-7. **Review rounds** (below), then the user's viewing, then `export.py` for a video if the user wants one ([site.md](site.md#video-export-optional)). Putting the film on a bookshelf is a separate task.--## Pictures--- **Find, then record.** `commons.py` searches Wikimedia Commons and downloads only public-domain and CC0 files, logging each in `SOURCES.tsv` beside the downloads (`books/<book>/art/found/` in its examples), under a header row: name, Commons title, licence, author, source URL, any use restriction such as a trademark (which it warns about), the credit line (often the holding collection), the licence URL and the work's date. The book page's credits come from it. One subagent with it found all twenty storyboard pictures for Foucault in thirteen minutes. Other good sources: the Library of Congress, Old Book Illustrations, the Internet Archive; record those by hand the same way.-- **Two treatments**, made by `prep.py`, which also writes `img/art.js` with each picture's size:- - *print*: the picture keeps its paper, with a border and a soft shadow, like a photograph laid on the ground. Paintings, photographs, title pages.- - *line*: an engraving's dark lines turn into the ground's ink colour and the paper drops out, so the figure stands on the ground itself. Woodcuts and engravings with clean lines.-- **Line drawings that draw themselves.** `trace.py` turns a line drawing into ordered strokes; `traced()` draws it on over a few seconds. It is striking once or twice; on every picture it becomes a tic.-- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. A job takes minutes; `video.py --resume JOBID` picks up one that was interrupted. On the first film it worked best when rare.-- **Maps** have their own kit ([below](#maps)).--## Building the beats--`film.js` holds the helpers, all pure functions of the beat clock:--- `pic()` places a picture with an entrance; `leave()`, `push()` (a slow Ken Burns move), which work on what `pic()`, `traced()` and `doc()` return (they remember where they were put), and `dissolve()` (one picture turning into another in place);-- `key()` big words in the condensed font, `strike()` a line through one, `say()` a quote typed word by word as it is spoken (Chinese and Japanese character by character; the kit's fonts are Latin only, so such a film adds a CJK font to `fonts.css`), `tag()` a small caption, `dateChip()` the year and place at the top left;-- `closeups()` pushes into a print onto each thing as it is named, with a label, and back out to the whole picture when given its `home` (`{ x, y }`); without it the camera stays on the last close-up;-- `epigraph()`, `doc()` (an old document), `balloon()`, `dots()`, `water()` and `bob()`, `anim()`, `along()`.--Add the film's own recurring pieces at the end of the book's `film.js` (Foucault's guide peeking up from the bottom edge, the Europe map). The kit's chapter sets `lead: false`: every opening is timed by hand.--A film can stretch the kit where its story asks. *Shooting an Elephant* added a red overprint to `say()` (`mark`), a band to `closeups()`, a `clip()` that plays a `<video>` (`img/moulmein-live.mp4`) on the beat clock, and silhouette puppets in the manner of Lotte Reiniger (`lib/puppets.js`). A live `<video>` is the quicker way to a moving shot, at a cost: the export seeks frame by frame without waiting for the video to decode, so an exported clip can lag a frame, where a `frames.py` sheet agrees exactly; check the export, and turn the clip into frames if it shows (the comment on `clip()` in that book's `lib/film.js` says so).--Look at your own frames while you build, not only at the end: after each few beats, `shot.py` or `?beat=N&t=S` at the moments a picture lands, and a `strip.py` contact sheet of the beat against its storyboard row ([review.md](review.md)). Ask what a viewer sees while each word is said: is the thing named on screen, does a word or label sit on a face, is the screen sparse. The first film's worst defects were pictures that contradicted the narration, and they show on a contact sheet at once.--What made the Foucault film work:--- **One idea or element every two to four seconds**, in step with the voice, on a sparse screen: one to three things on the ground.-- **Close-ups on what is named.** When the narration names "the greedy" and "the vain" aboard the ship of fools, the camera goes to each in the woodcut, with the words as a label.-- **A host, used sparingly.** The author as a cut-out guide works at the key points; fifteen appearances were too many and were cut back.-- **Characters get voices** for a line or a laugh, short: the jester's laugh at the end of a section, not over it.-- **The ending gathers the film.** Foucault ends with every era's Fool appearing in turn, and the opening epigraph returns.-- **Words on screen are few**: a key word, a quote being read, a year. Everything else is said.--## Maps--A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe, a virus leaving one city). The map kit `assets/templates/maps/` serves a documentary and a short alike, on either stage: `lib/map.js` draws a paper map (`paperMap()`) and `lib/globe.js` a night globe (`globeShot()`, three.js), both from one view `{ lon, lat, H }`, so a shot hands over from the globe to the map without a jump. Its data come from `geo.py`: `img/geo-lite.js` with the world's countries, capitals and big cities, plus only what the film shows, since each adds weight: `--regions CHN,ITA:region` (China's provinces, Italy's regions), `--detail Wuhan=114.27,30.58,1.5` (rivers, lakes and built-up areas around a city), `--cities`, and `--globe site/<book>/lib` for the globe (three.js and NASA's Black Marble as `img/night.webp`). Credit "Natural Earth, public domain" and "Black Marble 2016, NASA Earth Observatory, public domain" in the film's sources. The API is the comment at the top of `map.js`; `sample.html` plays every piece (`?wide` on the landscape stage).--Colour says what kind of thing is on the map: `lit` and `region` fill in the subject's colour (`--map-hot`, the book's red), `hatch` and `areas` draw in ink what is not the subject (an order, a lockdown), so the red keeps one meaning. Move a map through its `view(t)` (`mapKeys()` for a camera through keys), never by scaling a group above it: Gecko re-rasters a canvas under a scaled parent. A map or globe draws only inside its `on` window (in a shorts `shot()`, the shot's), since Firefox pays for every drawn canvas, even a covered one. The colours come from `lib/book.css` (`--map-land`, `--map-sea`, `--map-ink`, …) when it sets them.--Without the kit, a coastline from Natural Earth as one SVG path in the film's box, with a route drawn on by `along()`, is enough for one still map (Foucault's Europe).--## Interactive moments--A documentary can give the reader a few moments to act, where the story turns on a choice or a deed: in *Shooting an Elephant* the reader looks through the rifle's sight and fires, as Orwell did, and the film goes on from the shot. Open `site/shooting-an-elephant/ch01/index.html` and read `fireAsk` before writing one.--- `CHAPTER.film = true` keeps the chapter a film although some beats ask something: its sound effects and music play, the cover offers Play and the film's length instead of a lesson; the help lists the question keys unless the chapter also sets `CHAPTER.questionKeys = false`, for moments with their own controls (the rifle in *Shooting an Elephant*) *(v2.6)* ([engine.md](engine.md#player)).-- The moment is a beat whose `ask` is the chapter's own `done => { … }` rather than a `quiz()`. The engine calls it as the beat starts; once the narration and the beat's tweens are over, `P.waiting` turns true and the page waits. The handler listens on the stage (a click, a key), acts only while `P.waiting`, answers at once (a flash, a bang) and calls `done()` once, after which the next beat plays.-- A reader can step back or replay the beat while the handler is still listening. Note `P.gen` when the handler starts and compare it in every listener and timer: when it has changed, that start of the beat is over, so remove the listeners and do nothing (the engine already ignores a stale `done()` *(v2.4.1)*, but not the handler's own flash or sound).-- While the page waits, the music plays on and rises to 70 %, so choose a track that can carry an open-ended pause.-- `export.py` cannot click: it holds the beat's last picture for its `hold` seconds (`{ ask: fireAsk(1, 'p5b'), hold: 1.5 }` in the fourth slot, 1.5 by default; the engine ignores it), then plays the next beat as if the reader had acted. Whatever the act does on the page (the shot's bang), the next beat also does on its own clock for the video; *Shooting an Elephant* silences that copy when the reader fired.-- Check it as a reader: `?beat=N` stops on the moment; see that the prompt appears only once the narration ends, that a click acts at once and the film goes on, that stepping back and replaying mid-wait leaves no second flash or extra shot, and that the exported video holds and goes on without a gap.--## Review rounds--After the first cut, an independent director pass: a fresh agent on a strong model, given contact sheets of every beat (`strip.py`) and the reference film, with no knowledge of how the beats were built. On Foucault it found ten must-fix defects, about half of them places where the picture contradicted the narration (the wrong figure on screen while another was named). Fix, and show the user each fix on a contact sheet as it is made: a round is then quick to check.--Then a second round on the exported MP4, by another fresh director who watches it as a viewer would: frames every half second on contact sheets, the first frame alone at full size, the audio transcribed with word times and its loudness measured, each against the script and its sources and against the approved films' exports. This round is the lever: on *The Pandemic*'s six shorts every first cut had passed its worker's own checks and still had one to three must-fix faults, most of them the picture saying something other than the voice ("even the vaccinated" drawn as protection). A director's measurement is checked before it is sent back as work: in that run a loudness reading that no other measurement matched, and a cut "a second late" that was only Whisper starting a word at the pause before it (check a lag against the clip's own silences, not the transcript alone). After the fixes, a quick look of your own at the new MP4's frames still found a wrong date and a dead frame; keep it. Then the user watches the whole film.--## Later--Upright shorts for a phone feed (a 9:16 stage, faster cuts, one music track for the whole film) have their own path: [shorts.md](shorts.md).diff --git a/.claude/skills/papermorph/references/films/documentary.md b/.claude/skills/papermorph/references/films/documentary.mdnew file mode 100644index 0000000..e0b2868--- /dev/null+++ b/.claude/skills/papermorph/references/films/documentary.md@@ -0,0 +1,50 @@+# Documentaries: from a book or an idea to a film++A documentary is a narrated film about a book, an idea or a stretch of history on the wide stage: two minutes for one idea, ten or fifteen for a book's argument. Its pictures are mostly found: public-domain engravings, paintings and photographs, a few line drawings that draw themselves on, words set large, a map or two, all on one coloured ground and moved in step with a narrator. Usually the reader just watches; a film can also hand them the action at a few moments ([Interactive moments](#interactive-moments)). *Madness and Civilization* (`site/madness/`) is the approved reference: when in doubt, open it and match its level. *Shooting an Elephant* (`site/shooting-an-elephant/`) is the interactive one: the reader fires the rifle.++Intake, the folder, pictures, maps, voice, team and review are shared with shorts in [films.md](films.md). The kit is `assets/templates/documentary/` (`chapter.html`, `narration.en.json`, `style.json`, `lib/film.js`, `lib/book.css`, `lib/fonts.css` and the fonts).++## The order of work++1. **Research and the script.** Read the source, and trace every number and quote to where it was first said: a figure found on Wikipedia goes back to the speech or report Wikipedia cites, and that is the source to tag (Wikipedia's "low and middle-income" was the WHO's "low-income"). Read what each date counts, too: the day a virus arrived somewhere is not the day of its first confirmed case. Then write the narration (`content/<book>/chNN/narration.en.json`, [core/sound.md](../core/sound.md#the-narration-file), one beat per paragraph, `[[mark]]` before each word a picture lands on) and a storyboard table (`books/<book>/storyboard.md`: beat, what is said, what we see, which picture). Show both to the user before anything is built. The hard part of a documentary is the argument and the storyboard, not the animation.+2. **The folder** ([films.md](films.md#the-folder)).+3. **Pictures**: find them, record them, treat them ([films.md](films.md#pictures)).+4. **Voice**: `tts.py` or `eleven.py`, one clip per beat and `timings.js` with the marks ([core/sound.md](../core/sound.md#voices)).+5. **Music.** One recording per part of the film, changing at the turns, never abruptly, at a level that never covers the narrator; open with something short and rhythmic so the start is not slow. Find recordings (`commons.py --audio`), bring them to one loudness (`level.py`), and give each part its track with `music(file, beats, gain, fade)` ([core/sound.md](../core/sound.md#music)).+6. **The beats**, built from the kit's helpers and timed to the marks (below).+7. **Review rounds** ([films.md](films.md#review-rounds)), then the user's viewing, then `export.py` for a video if the user wants one ([core/publish.md](../core/publish.md#video-export)). Putting the film on a bookshelf is a separate task.++## Building the beats++`film.js` holds the helpers, all pure functions of the beat clock:++- `pic()` places a picture with an entrance; `leave()`, `push()` (a slow Ken Burns move), which work on what `pic()`, `traced()` and `doc()` return (they remember where they were put), and `dissolve()` (one picture turning into another in place);+- `key()` big words in the condensed font, `strike()` a line through one, `say()` a quote typed word by word as it is spoken (Chinese and Japanese character by character; the kit's fonts are Latin only, so such a film adds a CJK font to `fonts.css`), `tag()` a small caption, `dateChip()` the year and place at the top left;+- `closeups()` pushes into a print onto each thing as it is named, with a label, and back out to the whole picture when given its `home` (`{ x, y }`); without it the camera stays on the last close-up;+- `epigraph()`, `doc()` (an old document), `balloon()`, `dots()`, `water()` and `bob()`, `anim()`, `along()`.++Add the film's own recurring pieces at the end of the book's `film.js` (Foucault's guide peeking up from the bottom edge, the Europe map). The kit's chapter sets `lead: false`: every opening is timed by hand.++A film can stretch the kit where its story asks. *Shooting an Elephant* added a red overprint to `say()` (`mark`), a band to `closeups()`, a `clip()` that plays a `<video>` (`img/moulmein-live.mp4`) on the beat clock, and silhouette puppets in the manner of Lotte Reiniger (`lib/puppets.js`). A live `<video>` is the quicker way to a moving shot, at a cost: the export seeks frame by frame without waiting for the video to decode, so an exported clip can lag a frame, where a `frames.py` sheet agrees exactly; check the export, and turn the clip into frames if it shows (the comment on `clip()` in that book's `lib/film.js` says so).++Look at your own frames while you build, not only at the end: after each few beats, `shot.py` or `?beat=N&t=S` at the moments a picture lands, and a `strip.py` contact sheet of the beat against its storyboard row ([core/review.md](../core/review.md#watch-it-in-motion)). Ask what a viewer sees while each word is said: is the thing named on screen, does a word or label sit on a face, is the screen sparse.++What made the Foucault film work:++- **One idea or element every two to four seconds**, in step with the voice, on a sparse screen: one to three things on the ground.+- **Close-ups on what is named.** When the narration names "the greedy" and "the vain" aboard the ship of fools, the camera goes to each in the woodcut, with the words as a label.+- **A host, used sparingly.** The author as a cut-out guide works at the key points; fifteen appearances were too many and were cut back.+- **Characters get voices** for a line or a laugh, short: the jester's laugh at the end of a section, not over it.+- **The ending gathers the film.** Foucault ends with every era's Fool appearing in turn, and the opening epigraph returns.+- **Words on screen are few**: a key word, a quote being read, a year. Everything else is said.++## Interactive moments++A documentary can give the reader a few moments to act, where the story turns on a choice or a deed: in *Shooting an Elephant* the reader looks through the rifle's sight and fires, as Orwell did, and the film goes on from the shot. Open `site/shooting-an-elephant/ch01/index.html` and read `fireAsk` before writing one.++- `CHAPTER.film = true` keeps the chapter a film although some beats ask something: its sound effects and music play, the cover offers Play and the film's length instead of a lesson; the help lists the question keys unless the chapter also sets `CHAPTER.questionKeys = false`, for moments with their own controls (the rifle) ([core/engine.md](../core/engine.md#player)).+- The moment is a beat whose `ask` is the chapter's own `done => { … }` rather than a `quiz()`. The engine calls it as the beat starts; once the narration and the beat's tweens are over, `P.waiting` turns true and the page waits. The handler listens on the stage (a click, a key), acts only while `P.waiting`, answers at once (a flash, a bang) and calls `done()` once, after which the next beat plays.+- A reader can step back or replay the beat while the handler is still listening. Note `P.gen` when the handler starts and compare it in every listener and timer: when it has changed, that start of the beat is over, so remove the listeners and do nothing (the engine already ignores a stale `done()`, but not the handler's own flash or sound).+- While the page waits, the music plays on and rises to 70 %, so choose a track that can carry an open-ended pause.+- `export.py` cannot click: it holds the beat's last picture for its `hold` seconds (`{ ask: fireAsk(1, 'p5b'), hold: 1.5 }` in the fourth slot, 1.5 by default; the engine ignores it), then plays the next beat as if the reader had acted. Whatever the act does on the page (the shot's bang), the next beat also does on its own clock for the video; *Shooting an Elephant* silences that copy when the reader fired.+- Check it as a reader: `?beat=N` stops on the moment; see that the prompt appears only once the narration ends, that a click acts at once and the film goes on, that stepping back and replaying mid-wait leaves no second flash or extra shot, and that the exported video holds and goes on without a gap.diff --git a/.claude/skills/papermorph/references/films/films.md b/.claude/skills/papermorph/references/films/films.mdnew file mode 100644index 0000000..e9aa58e--- /dev/null+++ b/.claude/skills/papermorph/references/films/films.md@@ -0,0 +1,87 @@+# Films: documentaries and shorts++A film is a narrated argument told in pictures moved in step with a voice. It comes in two shapes that share almost everything: a **documentary** on the wide stage, two minutes for one idea or ten to fifteen for a book's argument ([documentary.md](documentary.md)), and a **short** on the upright 900 × 1600 stage for a phone feed, one point in one to three minutes ([shorts.md](shorts.md)). Read this file first for either, then the one for its shape.++The approved references: *Madness and Civilization* (after Foucault, ten minutes, `site/madness/`) for documentaries, *Shooting an Elephant* (`site/shooting-an-elephant/`) for a documentary the reader acts in, and *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/ch01/`), for shorts. Open them and match their level; they are levels to reach, not formats to copy.++## Contents++- Intake+- The folder+- Pictures+- Maps+- Voice and music+- Team+- Review rounds++## Intake++A short conversation in the spirit of [core/style.md](../core/style.md#asking): choices to click, the user's words kept verbatim, skipping what the request already settles. The film is the user's argument; the Skill's work is to make it land.++1. **The point and the angle.** What the film is about, and the one thing a viewer should leave with (Foucault: madness was not always locked up; each age decided what to do with it). Ask what must be in it: a scene, a quote, a person, an ending. What the user stresses is a theme to carry, not a thing to repeat: the first film's two epigraphs, shown four times, were overdone; they belong at the start and the end, with light echoes between.+2. **The outline.** Ask for the user's outline before writing anything: the hook, the steps, the ending. If there is none, build it together; the argument is the user's, not invented. A series: its name, how many episodes, where the material divides (propose a split, each episode with its one point, as options to click), and how each episode hands on to the next.+3. **Length, audience, platform.** Ten minutes holds one argument with five or six turns; a two-minute film holds one turn; a short holds one point. Who watches (an overseas feed, a home audience), and for a short, which platform.+4. **The look.** One ground colour for the whole film (burgundy `#5a0e16` for Foucault, chosen from four tested with the actual pictures on them), two fonts (a condensed sans for key words, a serif for quotes and captions), and how pictures are treated ([below](#pictures)). Offer a ground test: three or four grounds with real pictures on them, side by side, before anything is built. The colours live in the book's `lib/book.css`, which the kit reads; pictures are baked to match with `prep.py --ink/--paper`.+5. **People.** How real people appear: period pictures for the dead, cut-out figures or drawings for the living, never photographs of living people's faces.+6. **Sources.** Which numbers and quotes need a source, and how strict to be about anonymous reports ("according to the Wall Street Journal…"). Look at the argument too: where the field disputes a claim the hook states as fact, say so and offer ways to put it (historians doubt Foucault's ships of fools; "Foucault went looking for real ones" kept the line and the truth).+7. **Voice, music, pictures and budget** ([below](#voice-and-music)): the narrator picked by ear from short samples in the film's own words, the music, found or generated pictures, and what each costs.++Then agree the models ([core/style.md](../core/style.md#models)) and write `books/<book>/style.json` from the kit's `style.json`: `tier: "documentary"` or `"shorts"`, the user's words, the angle, the look, the voice, the music and the models; a short adds the platform, the source of its argument and the series with each episode's point.++## The folder++`python3 SKILL/scripts/new_book.py documentary <book>` or `… shorts <book>`, with `--maps` when the film has a map ([core/publish.md](../core/publish.md#start-a-book-folder)). It lays the kit's `lib/` over the engine's, its `book.css` (with the film's colours) replacing the default; a short gets the documentary kit's fonts too.++- `books/<book>/` holds the storyboard (`storyboard.md`, or a short's `chNN-script.md`: the outline, the beats with what we see, the sources), `art/` (`found/` with the downloaded pictures and `SOURCES.tsv`, generated pictures and clips, the `prep.py` list, the cost ledger) and `music/`.+- `site/<book>/img/` holds the treated pictures with `art.js` (`prep.py` fills it), clip sheets with `frames.js` (`frames.py`) and, when the film uses them, `lib/lines.js` (`trace.py`). Each film `chNN/` has `audio/<lang>/`, `audio/bgm/` and, for a short, `audio/sfx/`.+- The kit's sample beat shows a picture named `first-picture` (a short's: `img/hook-picture.webp`) once there is one. Until a short's picture exists the browser draws a broken image behind its words and the console shows one 404, so `shot.py`, which stops on any page error, takes no screenshots. Voice the sample with `tts.py` and open `ch01/` to check the folder works, then replace the narration with the film's script.+- The music line in `chapter.html` is commented out until the film has its track, and so are the map kit's lines.+- A documentary's `index.html` is the picture-book series page, given the film's colours and fonts and a credits section listing every picture and recording from `SOURCES.tsv`; a single film is a series of one. A series of shorts gets a series page later, as any book does; until then the player's home button leads nowhere. Shorts can also live on their long film's series page: *Madness and Civilization* lists its shorts at `/madness/#shorts`, and the host's `_redirects` sends `/madness-shorts/` there.+- The film's own recurring pieces go in the book's lib: at the end of a documentary's `film.js`, or a short's second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`).++## Pictures++- **Find, then record.** `commons.py` searches Wikimedia Commons and downloads only public-domain and CC0 files, logging each in `SOURCES.tsv` beside the downloads: name, Commons title, licence, author, source URL, any use restriction such as a trademark (which it warns about), the credit line, the licence URL and the work's date. The book page's credits come from it. One subagent with it found all twenty storyboard pictures for Foucault in thirteen minutes. Other good sources: the Library of Congress, Old Book Illustrations, the Internet Archive; record those by hand the same way.+- **Treatments**, made by `prep.py`, which also writes `img/art.js` with each picture's size:+ - *print*: the picture keeps its paper, with a border and a soft shadow, like a photograph laid on the ground. Paintings, photographs, title pages.+ - *line*: an engraving's dark lines turn into the ground's ink colour and the paper drops out, so the figure stands on the ground itself. Woodcuts and engravings with clean lines.+ - *full*: sized for a full-bleed shot on the upright stage.+ - Films made at the same time each keep their own sizes file (`prep.py … --art ch03-art.js`, loaded after `img/art.js`), so no two of them edit the same line.+- **Generated pictures.** An image model fills what no archive has; note each picture's prompt and cost in the ledger, quote the batch before paying, and show the user the pictures as they come. Low quality is usually enough (94 pictures cost $0.84 for a three-episode series); a picture made from a reference picture, to keep a figure or a style, costs about four times as much, since the reference counts as input ($0.016 against $0.004).+- **One figure per role**, so that a figure coming back means something (a callback), not that the cast ran out.+- **Line drawings that draw themselves.** `trace.py` turns a line drawing into ordered strokes; `traced()` draws it on over a few seconds. It is striking once or twice; on every picture it becomes a tic.+- **A still that moves.** For one or two moments, `video.py` makes a five-second clip from a still (about $0.42; Kling kept the engraving style), and `frames.py` gives every frame the same treatment on one sprite sheet, played by `anim()` on the beat clock so pause, seek and the export agree. A job takes minutes; `video.py --resume JOBID` picks up one that was interrupted. It worked best when rare.++## Maps++A map earns its place when the narration talks about where (the Rhine, the leper houses across Europe, a virus leaving one city). The map kit `assets/templates/maps/` serves both shapes on either stage: `lib/map.js` draws a paper map (`paperMap()`) and `lib/globe.js` a night globe (`globeShot()`, three.js), both from one view `{ lon, lat, H }`, so a shot hands over from the globe to the map without a jump.++- Its data come from `geo.py`: `img/geo-lite.js` with the world's countries, capitals and big cities, plus only what the film shows, since each adds weight: `--regions CHN,ITA:region` (China's provinces, Italy's regions), `--detail Wuhan=114.27,30.58,1.5` (rivers, lakes and built-up areas around a city), `--cities`, and `--globe site/<book>/lib` for the globe (three.js and NASA's Black Marble as `img/night.webp`): `uv run --with pillow python3 SKILL/scripts/geo.py site/<book>/img --globe site/<book>/lib` (without `--globe`, plain `python3`). Credit "Natural Earth, public domain" and "Black Marble 2016, NASA Earth Observatory, public domain" in the film's sources.+- The API is the comment at the top of `map.js`; `sample.html` plays every piece (`?wide` on the landscape stage).+- Colour says what kind of thing is on the map: `lit` and `region` fill in the subject's colour (`--map-hot`, the book's red), `hatch` and `areas` draw in ink what is not the subject (an order, a lockdown), so the red keeps one meaning. The colours come from `lib/book.css` (`--map-land`, `--map-sea`, `--map-ink`, …) when it sets them.+- Move a map through its `view(t)` (`mapKeys()` for a camera through keys), not by scaling a group above it: Gecko re-rasters a canvas under a scaled parent. A map or globe draws only inside its `on` window (in a shorts `shot()`, the shot's), since Firefox pays for every drawn canvas, even a covered one.+- Without the kit, a coastline from Natural Earth as one SVG path in the film's box, with a route drawn on by `along()`, is enough for one still map (Foucault's Europe).++## Voice and music++The mechanics (the narration file, `tts.py` and `eleven.py`, levels, `music.py`, recording licences) are in [core/sound.md](../core/sound.md). For films:++- **The narrator carries the film**, so the user picks it by ear. Offer both kinds: free voices (Edge, or Kokoro, local) and ElevenLabs v4 through OpenRouter (`eleven.py`, paid). ElevenLabs was the accepted voice on the films so far. Edge and Kokoro cost nothing; ElevenLabs about $0.07 a minute (`eleven.py --dry` prints the estimate; quote it). Characters can have their own voices for a line or a laugh (the Fool's giggle, a king's edict).+- **Every clip at one level**, −14 LUFS ([core/sound.md](../core/sound.md#levels)); a series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) sets `"tempo"` in each narration file.+- **Music**: classical recordings suit found pictures; generated music (Lyria) is made outside the Skill for now. How a documentary and a short each use it differs ([documentary.md](documentary.md#the-order-of-work), [shorts.md](shorts.md#the-order-of-work)). Leave `?bgm=` on the page so the user can set the level by ear ([core/sound.md](../core/sound.md#music)).++## Team++The general shape is in [core/team.md](../core/team.md).++- **Documentary**: split by part of the film (a turn of the argument, often one music track). The **strong** coordinator researches and writes the script and storyboard with the user, then builds what every part shares: the voice and `timings.js`, the music, and the film's own recurring pieces. A **middle** worker finds and treats the pictures from the storyboard (`commons.py`, `prep.py`, and `trace.py` or `frames.py` where the storyboard asks), recording each source. One **middle** worker per part then builds its beats, given the storyboard rows, the marks to land on, the kit's API (to read, not to edit), the first and last frame of the parts beside it, and how to look at its own frames; it replies with contact sheets of its beats and what they showed.+- **Short**: an episode is short enough that the **strong** coordinator writes the script and the shot-by-shot storyboard with the user and builds what the beats share: the voice and `timings.js` at one level, the music, and the series' own pieces. A **middle** worker makes or finds the pictures from the storyboard and records each prompt or source and its cost. One **middle** worker builds the beats (two, splitting the episode at a turn, when it is long), given the script, the marks, the kit's API to read and not edit, the safe area, and how to look at its frames: `strip.py` sheets of every beat and the first frame upright with `shot.py --clean`.+- The director passes are **strong** and report-only; the coordinator merges their findings and sends parts back to their workers.++## Review rounds++The loop is in [core/review.md](../core/review.md#review-rounds). For a film:++- **Round 1, on the sheets**: a fresh director on a strong model, given contact sheets of every beat and the reference film (or an approved episode), with no knowledge of how the beats were built. On Foucault it found ten must-fix defects, about half of them the wrong figure on screen while another was named.+- **Round 2, on the exported MP4**, by another fresh director who watches it as a viewer would: frames every half second on contact sheets, the first frame alone at full size, the audio transcribed with word times and its loudness measured, each against the script and its sources and against the approved films' exports. This round is the lever: on *The Pandemic*'s six shorts every first cut had passed its worker's own checks and still had one to three must-fix faults, most of them the picture saying something other than the voice ("even the vaccinated" drawn as protection).+- **Check a director's measurement** before it goes back as work: one reported loudness no other measurement matched, and a cut "a second late" was only Whisper starting a word at the pause before it (check a lag against the clip's own silences, not the transcript alone). After the fixes, a quick look of your own at the new MP4's frames; then the user watches the whole film.diff --git a/.claude/skills/papermorph/references/films/shorts.md b/.claude/skills/papermorph/references/films/shorts.mdnew file mode 100644index 0000000..f14b41f--- /dev/null+++ b/.claude/skills/papermorph/references/films/shorts.md@@ -0,0 +1,60 @@+# Shorts: one point, under three minutes, upright, for a phone feed++A short is a narrated film on the upright 900 × 1600 stage (`<html data-stage="portrait">`, [core/engine.md](../core/engine.md#stage-and-state)), made for YouTube Shorts, TikTok, Reels or X. It makes one point in one to three minutes, with a new picture every one to three seconds: full-bleed photographs or generated pictures, big words, cut-out figures, a number counting up, a chart, a map. What differs from a documentary is the pace, the grammar of the picture and where it ends up; intake, the folder, pictures, maps, voice, team and review are shared in [films.md](films.md). An upright chapter is a film without questions. The worked example is *Madness and Civilization* episode 1, *The Ship* (`site/madness-shorts/ch01/`), the ten-minute documentary recut as a series: watch it before making one, as a level to match, not a format to copy.++The kit is `assets/templates/shorts/` (`chapter.html`, `narration.en.json`, `style.json`; `lib/shorts.js`, `book.css`, `icons.js`; fonts from the documentary kit).++## Contents++- What the viewer is doing+- Questions for the user+- From a long film+- The order of work+- The picture++## What the viewer is doing++They are scrolling. They decide in the first second whether to stay, and on the platforms' numbers that second is most of the outcome: one of our episodes opened on a generated city picture already moving, under its first line, and 57.8 % stayed past the first chance to swipe; another opened on a still card of text and 12.8 % stayed. A text card reads as a text post, and a line in a script the viewer cannot read is a wall. So the first frame is a picture in motion with the hook spoken over it, and the hook is the point itself, not a preamble ("there's a line that went viral…" spends the second that matters).++After that they stay as long as each moment gives them something new and the argument keeps moving. Background facts are where a short gets slow: compress them hardest and keep the steps of the argument.++## Questions for the user++The questions are the films' intake ([films.md](films.md#intake)): the point and who watches on which platform, the user's outline (a series: its episodes and each one's point), people, sources and disputed claims, voice and music, pictures and budget. Writing the script with the user is strong-model work, building beats middle, checks small.++## From a long film++When the user wants a film that already exists recut as shorts (*Madness and Civilization* became four), the argument is there: its script is the outline, and its checked quotes, found pictures, voice and music carry over. The first questions change: how many episodes, where the film's turns divide them, and what each episode's one point is. Propose the split and episode 1's outline together, then go on as below. Read the film's `style.json`, its narration and its `SOURCES.tsv` before asking anything they already answer. Where a short's habits and the film's differ, ask the user: the documentary's one Fool through the centuries is a recurring figure, which the short's one figure per role would break.++## The order of work++1. **The script, beat by beat, with the user.** Keep it in `books/<book>/chNN-script.md`: the agreed outline, a table of beats (the narration, one line of what we see, and its rough length), and each number's and quote's source under it. Show it to the user a few beats at a time and rewrite as they answer.+ - Length: words ÷ the voice's pace (about 2.6 words a second for an ElevenLabs narrator), plus about 1.4 s a beat for the engine's hold after the words (0.6 s) and the camera's tail (0.8 s in the worked example); a twelve-beat script ran 17 s longer than its words. A background beat over about eight seconds is where the short will feel slow; shorten it before the voice is paid for. Once voiced, the length hides in the voice's sentence pauses: `eleven.py --max-pause 0.3` took one episode from 112 s to 107 s.+ - The beats' narration, with `[[mark]]` before each word a picture lands on, goes into `content/<book>/chNN/narration.en.json`; keep the two in step.+2. **The storyboard, then the cast and the pictures.** One line per shot, a shot every one to three seconds, under each beat of the script: that is the list of pictures to make or find, and a beat-by-beat plan is too coarse for it (one director pass asked for three pictures the plan had missed). Then make or find them ([films.md](films.md#pictures)).+3. **The folder** ([films.md](films.md#the-folder)). The series' own pieces (its cast's sizes in `MEME`, a series card) go in a second file loaded after `shorts.js`. Every episode but a series' last sets `CHAPTER.next`: the end card names the next episode, and the player offers it only when `next` is set.+4. **Voice**: `eleven.py` or `tts.py` at −14 LUFS ([core/sound.md](../core/sound.md#voices)). Wordless beats (a series card, an end card) take `{ dur: 2 }` and no line, and the music stays ducked under them. Check the marks on spoken numbers: a number the matcher missed lands late (seven marks in one episode, up to 0.75 s).+5. **Music.** One track for the whole episode under every beat, `music(file, undefined, gain, .05)`. It changes by easing, at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses, which `music.py cut --rests --even` takes out ([core/sound.md](../core/sound.md#music)). A looping track is fine for a first cut. Start `?bgm=` around 0.4, the level the user chose for episode 1.+6. **The beats**, built from the kit and timed to the marks; sound effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps. A beat ends at its last tween plus the hold, so the kit's habit of pushing a picture past the voice (`photo(s, …, 0, D + .6)`) lengthens the beat by as much: two beats with the same voice can differ by what their tweens overrun. `?lengths` on the page prints each beat's voice against its length on screen. Two mirrored beats (two answers treated alike) get the same seconds with `{ minDur }` set to the longer one's length.+7. **Watch it yourself, then the director rounds** ([core/review.md](../core/review.md), [films.md](films.md#review-rounds)). Look at the first frame on its own, upright as the feed shows it: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage; look at it with the platform's title, caption and buttons in mind. Measure what a script can: a shot held still too long (`still.py chNN --min 2`), a number that lands after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode; `strip.py` and `shot.py` take `--query tags` too, to see the tags the export will show). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and on a contact sheet alike: on a shot that long, push at least about 15 %, or cut.+8. **The user watches**, you fix, and `export.py` writes a 1080 × 1920 MP4 and an `.srt` ([core/publish.md](../core/publish.md#video-export)). On an upright film it shows the source and AI-illustration tags, since the video leaves the page that credits them (`--no-tags` leaves them out). The user uploads it and ticks the platform's AI or synthetic-content box. A video over 25 MiB does not fit Cloudflare Pages; the web page itself is the light version. A series card's still is upright too: `shot.py … --webp 600` writes a 600 × 1067 WebP of the stage.++## The picture++`shorts.js` holds the grammar, every helper a pure function of the beat clock:++- `shot()` a full-frame shot with a hard cut, `whip` (a sideways slide with motion blur) or `swipe` (the next clip rising as in a feed); `photo()` a full-bleed picture with a slow push, centred; `found()` the same for a found photograph, tagged with its source; `wide()` a camera across a landscape picture whose subject is off-centre, never showing an edge; `plate()` a picture placed whole on the ground (sizes from `img/art.js`). A picture whose point is its text (a sign, a headline) goes in whole with `plate()`: an upright crop of a shop sign left "Y. WE / RARY CLOS";+- `word()` big condensed capitals (a word wider than its `maxW`, 660, is set smaller, so it and its stroke stay in the safe area), `label()` and `band()` caps on solid blocks, `marker()` a highlighter sweep, `vlog()` white outlined overlay text, `srcTag()` a source or "AI illustration";+- `meme()` a cut-out figure rising in, `swarm()` one crossing then a crowd of them, `stamp()` a rubber stamp slammed on, `counter()` a number counting up, `priceTag()`, `phoneCard()`, `ico()` and `icons()` (Phosphor, MIT), `bar()`, `clipImg()`;+- its palette (`DARK`, `RED`, `LIGHT`, `MUTED`, …, set in `lib/book.css` as `--dark`, `--red`, …), fonts (`SANS`, `SERIF`) and small tools (`inkW()` text width, `ramp01()`, `seeded()`) are named apart from the documentary kit's `film.js`, so a short can load `film.js` too when it wants a documentary helper (`pic()`, `say()`, `traced()`): load it before `shorts.js`;+- `shortsBeat` turns a beat tuple into the engine's beat with every cue `LEAD` (0.22 s) early: a cut that lands on the word itself reads as late.++What made the first shorts work:++- **One idea per shot, one to three seconds a shot**, full bleed; words inside x 50–810, y 130–1290, since the platform draws its title, caption and buttons over the rest.+- **Say it literally.** When the narration describes a mechanism, draw each link as the voice names it. The "everyone is cheap" loop read as a vague circle until it became three people, each handing the next their product and its price, A to B, B to C, C back to A.+- **Numbers move.** A count, a bar growing, a price tag swapped: a number on screen arrives the moment it is said. A big denominator can be drawn literally: "2 in 100,000" as a field of 100,000 dots in one SVG `<pattern>` fill with the two real circles over it played at 17 ms a frame in both browsers.+- **A series says where it is.** A few seconds after the hook: the series card with this episode lit ("1 · The Ship"), then the argument.+- **The ending points on.** The last beat answers the hook and names the next episode.++Scripts to come: cuts on the music's own beat, and generating music with Lyria.diff --git a/.claude/skills/papermorph/references/intake.md b/.claude/skills/papermorph/references/intake.mddeleted file mode 100644index ed76a2e..0000000--- a/.claude/skills/papermorph/references/intake.md+++ /dev/null@@ -1,92 +0,0 @@-# Intake: from a PDF to one agreed chapter--A cold agent with only a PDF has no idea what the user wants, and its guesses diverge from run to run. Intake closes that gap through a short conversation and writes the outcome to `books/<book>/style.json`, the anchor every chapter is made against. The schema fixes *what* the book looks and sounds like; *how* each moment is animated stays free.--The conversation should feel light: the user tries one chapter first and decides about the rest of the book after seeing it.--## Asking--- Many users want to click, not type. Every point where you need the user, from finding the PDF to approving the finished chapter, is a choice: two to four concrete options drawn from this book, the recommended one first and labelled so, so that accepting every recommendation still makes a good book. Use the structured question tool when there is one (at most four questions a round); otherwise number the options so a single digit answers. Their own words are always welcome, never required.-- Questions come from this book and this chapter, not from a form. Skip what the material or earlier answers already settle.-- After each round, say the answers back as decisions in one or two lines, then move on.-- Keep what the user says about the look **verbatim** in `words`; later chapters need their taste, not a summary of it. When they only pick options, record the chosen options' wording.--## 1. Welcome and the PDF--Greet briefly as Papermorph. Look for PDFs in the working folder and its subfolders (then the user's Downloads and Desktop if none are found) and ask "Is it this one?", listing up to four candidates. If none are found, offer to search another folder or to take a path. Choose a short slug and place the file at `books/<book>/book.pdf`, a copy or a link.--When the user brings a story, a joke or a fairy tale instead (or a story book's PDF), it becomes a picture book: go to [stories.md](stories.md), which has its own short intake, and come back here for the models (§5) and `style.json` (§6). A documentary ([documentary.md](documentary.md#intake)) and a short ([shorts.md](shorts.md#questions-for-the-user)) have their own questions too, and come back the same way.--## 2. What this book is--Run the split ([SKILL.md](../SKILL.md#pipeline)) and read the contents, the preface and the `text.md` of two or three chapter openings across the book. Say in two or three sentences what the book is: subject, readers, how it teaches. Then offer a chapter to try: name two or three candidates with one line each on what they would show, recommending one that is representative rather than the gentlest opening (a light introduction can pass while hiding the hard problems). A section of a long chapter is fine.--If the book is for a course, notice it here: when it cites other works (author–year citations, named studies), offer links from the works named on screen to their sources; when its questions must be reviewed before release, offer an item bank; when it goes into an LMS, mention the SCORM package. None is on by default ([courses.md](courses.md)).--## 3. Tier--Offer the animation tiers as reference points; the books at https://papermorph.diamonddoge.org/ show each of them (and the picture books); link them.--1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books, `site/elementary-algebra/` and `site/math-notebook/`). The lightest; a smaller model can do most steps.-2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book, `site/science/`). Several times the work of tier 1 per chapter, and the picture step wants a strong model.-3. **Custom**: the user describes what they want; you judge which abilities it needs and say so.--Recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)); physical and narrative ones fit tier 2 ([scenes.md](scenes.md)). Mixing per beat is allowed under any tier.--Then start the book folder ([site.md](site.md#start-a-book-folder)): the look is settled on real frames, so the engine, the chapter page and the voice need to be in place first.--## 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, 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.-2. Shared components: list the things this chapter, and the chapters around it, will draw again and again (in the science book: force arrows, crates, the actors), each with what it must do and how it would be made. Offer them as one multiple-choice question, recommending the ones that recur most, for which to build once for the whole book ([assets.md](assets.md)).-3. The storyboard: lay out the key moments without motion and show the sheet ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). Ask: add motion now (recommended), or a few concrete changes to named frames. Motion comes after the user agrees.--**Custom**: ask what the description leaves open, using the closest tier's rounds and options.--## 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 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 | Documentary | Shorts |-|---|---|---|---|---|---|-| Extract the chapter (or the story) | small | small | strong (script and storyboard with the user) | strong (research, script and storyboard with the user; then voice and music) | strong (the script and storyboard with the user; then voice and music) |-| Narration and beats | middle | middle | strong (voices, the episode kit) | middle (pictures found and treated) | middle (pictures generated or found) |-| Picture: storyboard, motion, questions | middle | strong | middle, one worker per scene | middle, one worker per part of the film | middle (the beats) |-| Checks | small | small | small (sound effects too) | small | small |-| Review | middle | middle | strong director, middle picture and sound reviewers | strong director | strong director |-| Rework | strong | strong | middle, per scene | middle, per part | middle |-| Register | small | small | 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`, 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`; a [documentary](../assets/templates/documentary/style.json)'s and a [short](../assets/templates/shorts/style.json)'s: `script`, `pictures`, `beats`, `checks`, `director`). 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--Start from [the template](../assets/templates/style.json), or for a picture book, a documentary or a short from its kit's own `style.json`. Blocks are grouped by ability, not by tier; a tier is just which blocks are present:--| Block | What it holds | Present in |-|---|---|---|-| `schema`, `tier`, `book` | schema version; `1`, `2`, `"custom"`, `"picture"`, `"documentary"` or `"shorts"`; title, slug, language, readers, pilot chapter | all |-| `words` | the user's own words about the look, verbatim, with later feedback that changed the bar | all |-| `look` | palette, what each colour means, text and maths fonts, notation and rounding | all |-| `voice` | TTS engine (`edge`, or `kokoro` when Edge is unavailable or local audio is wanted; a documentary may choose `eleven`, paid: [documentary.md](documentary.md#intake)), voice, rate | all |-| `pacing` | minutes per chapter, where checks and practice go | all |-| `engine` | engine source and version used to build the book | all |-| `scenes` | art style, cast, how storyboards are reviewed | tier 2 |-| `components` | shared elements: name, file, what each does | tier 2, tier 1 when the book has some |-| `images` | where images may come from, credit rules | tier 2 |-| `models` | the model for each step, as agreed in §5 | all |-| `illustration` | a picture book's look, budget, cast and sets ([stories.md](stories.md#intake-for-a-story)) | picture books |-| `angle` | the one thing a viewer leaves with, and what must be in the film | documentaries |-| `music` | the music and where it came from | documentaries, shorts |-| `platform`, `source`, `series`, `sources` | the feed and export size; where the argument comes from (the user's outline or a long film); the series' name and each episode's point; how strict to be about sources ([shorts.md](shorts.md#questions-for-the-user)) | shorts |-| `courses` | the course options chosen ([courses.md](courses.md)) | when chosen |-| `approved` | chapters the user approved and what each shows well | filled as chapters are approved |--Leave out blocks the tier does not use. New kinds of book add their own blocks beside these; a reader that meets a block it does not know reads it as plain intent. Increase `schema` only when an existing field changes meaning.--Deliver the pilot with a choice: approve and make the rest of the book (recommended when it is good), approve and stop here, or one of two or three concrete changes you would make yourself. Fold the answer and any feedback into `words` and the affected block, and add an approved chapter to `approved`. Approved chapters are the strongest anchor: later chapters watch and read them as worked examples.--When continuing, write `chapters.md` (a table `| # | Title | Pages | Minutes | Status |`, status planned, ready or user-approved) and go on with the remaining chapters.diff --git a/.claude/skills/papermorph/references/assets.md b/.claude/skills/papermorph/references/lessons/assets.mdsimilarity index 95%rename from .claude/skills/papermorph/references/assets.mdrename to .claude/skills/papermorph/references/lessons/assets.mdindex f1d45be..b947953 100644--- a/.claude/skills/papermorph/references/assets.md+++ b/.claude/skills/papermorph/references/lessons/assets.md@@ -15,6 +15,6 @@ Laying out a chapter's moments shows what the library lacks: a new prop, a place- Incoming files go to `books/<book>/images/inbox/` with `SOURCES.md` (origin URL, author, licence). Prefer public-domain or CC0/CC-BY; record attribution for anything that requires it.- A processing script in `books/<book>/images/` turns them into `site/<book>/img/` (crop, recolour, scale, compress), so every output can be rebuilt; `SKILL/scripts/sprites.py` has the common steps: integer nearest-neighbour scaling, colour mapping, pixel art from text rows, and assembling frames into one sheet with a JSON layout. Credits for the published images go in `site/<book>/img/CREDITS.md`.- Sprite animation: put a character's frames in one sheet and switch frames by changing a nested `<svg>`'s viewBox; changing an `<image href>` per frame can refetch. Pixel art is drawn at an integer scale with `image-rendering: pixelated` and pre-scaled files.-- One large detailed object (a planet, a map) is cheaper as a single image than as many shapes; see the Firefox notes in [engine.md](engine.md#performance-firefox).+- One large detailed object (a planet, a map) is cheaper as a single image than as many shapes; see the Firefox notes in [engine.md](../core/engine.md#performance-firefox).-Pictures from an image model (sets and props for picture books, and any other book that agrees a budget) go through `paint.py` and `painted.py`; see [painting.md](painting.md).+Pictures from an image model (sets and props for picture books, and any other book that agrees a budget) go through `paint.py` and `painted.py`; see [painting.md](../picture-books/painting.md).diff --git a/.claude/skills/papermorph/references/lessons/authoring.md b/.claude/skills/papermorph/references/lessons/authoring.mdnew file mode 100644index 0000000..d04fda2--- /dev/null+++ b/.claude/skills/papermorph/references/lessons/authoring.md@@ -0,0 +1,37 @@+# Authoring a chapter++## Shape++Chapters have run 5–18 minutes with 5–40 second beats; a long chapter can hold several parts (each a short title beat, lessons, a quick check and a wrap). Let the content determine length and the number of checks/practice sets.++| Beat | Purpose |+| --- | --- |+| `intro` | Title card (unit and chapter number, title, one line of purpose). |+| lesson beats | One idea each, built up in the picture while the narration explains it. |+| `q1`, `q2`, … | A check of already taught content, separated from the next check by a lesson beat. |+| `wrap` | Three or four numbered takeaways. |+| `final1` … | Full-screen practice covering the whole chapter. With several sets, label them like `'Chapter practice · set 1 of 2'` (the engine appends "· question k of n"). |+| `finish` | Score card (`finishCard`): first-try results for quick checks and practice. |++Beat ids are shared by the page (`BEATS`) and the narration file; a beat with `ask` waits for the answers before moving on ([questions.md](questions.md)).++## Beats++Before writing code, list the beats. For each lesson beat decide what the eye should watch and what changes; why that change is true (the animation is the argument); which words trigger which actions (these become `[[marks]]`); what text appears, beside the thing it names; and what carries over from the previous beat. Then lay out the key moments as pictures (storyboard): [diagrams.md](diagrams.md) and [scenes.md](scenes.md).++- **Open on the subject.** When a beat clears the picture, the new topic appears right away; labels and steps follow the words. Short pauses for thought are fine.+- **One new thing at a time**, and **the same colour means the same thing** across the chapter and, where it fits, the book.+- **Teach the chapter's scope**, choosing sections by idea; note any reordering in `chapters/chNN.md`.++## Narration++The file format, `[[marks]]`, writing for the ear and the voice scripts are in [core/sound.md](../core/sound.md#the-narration-file). A lesson adds:++- Match the audience: plain, warm, never childish. Explain why, not only how.+- Question beats get one short line ("Quick check. Find the mean."); the card holds the question ([questions.md](questions.md)).++## Content rules++- Follow the agreed chapter scope and order. Verify facts, calculations and answers actually used in the finished lesson; correct or replace source errors and note them in `books/<book>/chapters/chNN.md` for the user.+- Check worked examples as the subject, not only as arithmetic (a push on someone standing on the ground is not the net force).+- Use the notation and rounding in `style.json` (`look.notation`). Record new shared decisions there. Group thousands with a no-break space (U+00A0) or the book's comma: a thin space all but vanishes in bold system fonts (150 000 000 read as 150000000).diff --git a/.claude/skills/papermorph/references/lessons/checks.md b/.claude/skills/papermorph/references/lessons/checks.mdnew file mode 100644index 0000000..d98cd3c--- /dev/null+++ b/.claude/skills/papermorph/references/lessons/checks.md@@ -0,0 +1,22 @@+# Lesson checks++The shared pass (lint, `check.py`, strips, `still.py`, `shot.py`, `perf.py`, review rounds) is in [core/review.md](../core/review.md). A lesson adds the checks below; watch every beat to its end, question cards included.++## Frames and openings++```sh+uv run --with playwright SKILL/scripts/check_blank.py site/<book> chNN --url http://localhost:8765/<book>/+uv run --with playwright SKILL/scripts/overlap.py chNN --url http://localhost:8765/<book>/+```++`check_blank.py` reports openings empty for more than a second after speech starts. `overlap.py` samples every beat and lists where an arrow runs through text or two texts collide, with times, so you can look at exactly those frames. Both skip a picture book, whose set is always there and whose words are captions.++On the `shot.py` sheets, a lesson also looks for geometry contradicting its values, shapes inside circles or curves crossing the outline; check thin geometry on the full-size `chNN_bII_T.png`, not only the sheet.++## Interaction tests++Adapt `assets/templates/e2e.py` into `tools/<book>/e2e_chNN.py`: it checks playback, that every beat replays the same frame when seeked, that quiz cards stay readable and on stage at two viewport sizes, and walks the answers, practice and finish card. `ANSWERS` maps each question beat to one step per question: a digit picks a choice, `=a,b` fills the boxes, `#2;1+3` answers a grid (rows split by `;`, each row's columns counted from 1, `+` for several, `#2;;1` a row left empty). Run it in Chromium and with `BROWSER=firefox`. Run existing tests of approved chapters after changing the book's engine or library.++After scoring changes, check a wrong first try stays recorded after revisiting and a restart clears it; after progress changes, check book isolation and missing or malformed stored data. Fix engine bugs at the engine source and copy them to the books with `scripts/engine.py`; book-specific settings stay in each book's `lib/book.css`.++Test details: keyboard first (Enter checks, Esc leaves a box, press Esc before S, R replays on the finish card); a page opened with `?beat=` is not started, so start it before pressing keys; `seek(i, false)` stops before the old panel's fade, so seek playing or evaluate past it; compare text in lower case (CSS uppercases kickers); avoid assertions on totals that grow with the book.diff --git a/.claude/skills/papermorph/references/courses.md b/.claude/skills/papermorph/references/lessons/courses.mdsimilarity index 97%rename from .claude/skills/papermorph/references/courses.mdrename to .claude/skills/papermorph/references/lessons/courses.mdindex c5e47ec..7d6e3ff 100644--- a/.claude/skills/papermorph/references/courses.md+++ b/.claude/skills/papermorph/references/lessons/courses.md@@ -31,7 +31,7 @@ Build the page's copy after every bank change, and never edit `items.js` by handpython3 SKILL/scripts/items.py books/<book>/items/chNN.items.json site/<book>/chNN/items.js```-The chapter loads `<script src="items.js"></script>` right after `engine.js` and asks with `quiz(TOPR, [mcq('c-attrib')], done)` (engine.md). `items.py` refuses what a card cannot show (multiple-response items, tables, media, no single key) and warns about items not yet marked `approved`.+The chapter loads `<script src="items.js"></script>` right after `engine.js` and asks with `quiz(TOPR, [mcq('c-attrib')], done)` ([questions.md](questions.md)). `items.py` refuses what a card cannot show (multiple-response items, tables, media, no single key) and warns about items not yet marked `approved`.## SCORM packagediff --git a/.claude/skills/papermorph/references/lessons/cover.md b/.claude/skills/papermorph/references/lessons/cover.mdnew file mode 100644index 0000000..deae345--- /dev/null+++ b/.claude/skills/papermorph/references/lessons/cover.md@@ -0,0 +1,22 @@+# Cover, contents and unit sketches++A textbook's `index.html` is its cover and contents; a picture book or a film uses the series page instead.++## Cover and contents (`index.html`)++One page: no hash or `#book` shows the cover, `#references` the reference list, `#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. Preserve cover → contents → chapter navigation and the return from contents to cover.++- 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, and set the previous chapter's `CHAPTER.next = '../chNN/'`.+ - A unit's optional third entry `{ unit, chapter, sample: true }` renumbers it 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 that cites works gets a `#references` view ([courses.md](courses.md#citations)).+- 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.++## Unit sketches (`unit-art.js`)++Give each unit a small sketch of its own ideas, drawn in the unit colour, with one gentle topic-related loop. Use the agreed asset approach. Keep the left third light for the title on phones; check the finished contents at 1440 px and 390 px once. Classes and loop examples are in `unit-art.js`; the shared header styles, off-screen pausing and reduced motion live in the engine's `lib/units.css` and `lib/units.js` (`Units.header`, `Units.watch`).diff --git a/.claude/skills/papermorph/references/diagrams.md b/.claude/skills/papermorph/references/lessons/diagrams.mdsimilarity index 98%rename from .claude/skills/papermorph/references/diagrams.mdrename to .claude/skills/papermorph/references/lessons/diagrams.mdindex 3a15363..873fc93 100644--- a/.claude/skills/papermorph/references/diagrams.md+++ b/.claude/skills/papermorph/references/lessons/diagrams.md@@ -8,4 +8,4 @@ For abstract and procedural ideas (the maths books on the showcase site, `site/e- **Show the common mistake** where one exists (squaring the coefficient too), visibly crossed out, then the right way.- **Vary the composition with the content.** A chapter that is one centred formula after another feels monotonous; a number line, a table, a picture of the quantity and a worked line each have their own layout.-Storyboard these beats like any other: place the key moments in the real page and capture them with `strip.py` before timing the moves ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). The engine's maths helpers (number lines, tiles, fraction rows, planes, data plots) are in `lib/math.js`, listed in [engine.md](engine.md#drawing).+Storyboard these beats like any other: place the key moments in the real page and capture them with `strip.py` before timing the moves ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). The engine's maths helpers (number lines, tiles, fraction rows, planes, data plots) are in `lib/math.js`, listed in [engine.md](../core/engine.md#drawing).diff --git a/.claude/skills/papermorph/references/lessons/intake.md b/.claude/skills/papermorph/references/lessons/intake.mdnew file mode 100644index 0000000..688df37--- /dev/null+++ b/.claude/skills/papermorph/references/lessons/intake.md@@ -0,0 +1,42 @@+# Intake: from a PDF to one agreed chapter++A short conversation that ends with one chapter the user agreed to try, a tier, the look and `style.json`. How to ask (choices to click, the user's words kept verbatim), the models step and the file itself are in [core/style.md](../core/style.md); this file is what a textbook needs settled.++When the user brings a story, a joke or a fairy tale instead (or a story book's PDF), it becomes a picture book ([stories.md](../picture-books/stories.md#intake-for-a-story)); a book, an idea or a stretch of history to explain as a film, or one point for a phone feed, goes to [films.md](../films/films.md#intake).++## 1. Welcome and the PDF++Greet briefly as Papermorph. Look for PDFs in the working folder and its subfolders (then the user's Downloads and Desktop if none are found) and ask "Is it this one?", listing up to four candidates. If none are found, offer to search another folder or to take a path. Choose a short slug and place the file at `books/<book>/book.pdf`, a copy or a link.++## 2. What this book is++Run the split ([lessons.md](lessons.md#pipeline)) and read the contents, the preface and the `text.md` of two or three chapter openings across the book. Say in two or three sentences what the book is: subject, readers, how it teaches. Then offer a chapter to try: name two or three candidates with one line each on what they would show, recommending one that is representative rather than the gentlest opening (a light introduction can pass while hiding the hard problems). A section of a long chapter is fine.++If the book is for a course, notice it here: when it cites other works (author–year citations, named studies), offer links from the works named on screen to their sources; when its questions must be reviewed before release, offer an item bank; when it goes into an LMS, mention the SCORM package. None is on by default ([courses.md](courses.md)).++## 3. Tier++Offer the animation tiers as reference points; the books at https://papermorph.diamonddoge.org/ show each of them; link them.++1. **Diagrams that change**: symbols, number lines, graphs and shapes built in code, rearranged as the narration explains (the maths books, `site/elementary-algebra/` and `site/math-notebook/`). The lightest; a smaller model can do most steps.+2. **Illustrated scenes**: characters act out the idea, the camera moves, external images and a storyboard before motion (the science book, `site/science/`). Several times the work of tier 1 per chapter, and the picture step wants a strong model.+3. **Custom**: the user describes what they want; you judge which abilities it needs and say so.++Recommend one from the chapter's content: abstract and procedural ideas fit tier 1 ([diagrams.md](diagrams.md)); physical and narrative ones fit tier 2 ([scenes.md](scenes.md)). Mixing per beat is allowed under any tier.++Then start the book folder (`new_book.py lesson <book>`, [core/publish.md](../core/publish.md#start-a-book-folder)): the look is settled on real frames, so the engine, the chapter page and the voice need to be in place first.++## 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 ([lessons.md](lessons.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 ([core/style.md](../core/style.md#models)), 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.+2. Shared components: list the things this chapter, and the chapters around it, will draw again and again (in the science book: force arrows, crates, the actors), each with what it must do and how it would be made. Offer them as one multiple-choice question, recommending the ones that recur most, for which to build once for the whole book ([assets.md](assets.md)).+3. The storyboard: lay out the key moments without motion and show the sheet ([scenes.md](scenes.md#storyboard-layout-first-then-motion)). Ask: add motion now (recommended), or a few concrete changes to named frames. Motion comes after the user agrees.++**Custom**: ask what the description leaves open, using the closest tier's rounds and options.++## After the pilot++Deliver the pilot with the choice in [core/style.md](../core/style.md#stylejson). When continuing, write `chapters.md` (a table `| # | Title | Pages | Minutes | Status |`, status planned, ready or user-approved) and go on with the remaining chapters.diff --git a/.claude/skills/papermorph/references/lessons/lessons.md b/.claude/skills/papermorph/references/lessons/lessons.mdnew file mode 100644index 0000000..a2098ae--- /dev/null+++ b/.claude/skills/papermorph/references/lessons/lessons.md@@ -0,0 +1,75 @@+# Lessons: from a textbook PDF to animated chapters++Each chapter is a short animated lesson film where the picture carries the explanation, the narration says it, and quick checks and practice happen inside the picture. The maths books (`site/elementary-algebra/`, `site/math-notebook/`) show tier 1, the science book (`site/science/`) tier 2.++Start with [intake.md](intake.md) whenever `books/<book>/style.json` does not exist yet; reuse answers and approvals already given. Re-create explanations, examples and drawings; source PDFs, page images and extracted text stay outside `site/` and out of version control (`.gitignore`: `*.pdf`, `books/*/pages/`).++## Contents++- Project layout+- Pipeline+- Chapter loop+- LaTeX+- Team++## Project layout++```+books/<book>/+ book.pdf, sections.json source and page map (private)+ pages/chNN/text.md, *.png extracted reference material (private)+ style.json the agreed style every chapter anchors to+ chapters.md chapter map and status+ chapters/chNN.md storyboard, errata, feedback+ images/ inbox, SOURCES.md, image-requests.md, processing scripts+ review/chNN/ storyboard sheets, strips, check output+content/<book>/chNN/ narration.<lang>.json and TTS cache+tools/<book>/ tests and evidence scripts+site/<book>/ the static book (only this is delivered)+ index.html, unit-art.js cover + contents, unit sketches (cover.md)+ lib/engine.*, math.js, volume.*, contents.*, units.* the engine, copied in by engine.py+ lib/book.css this book's engine settings and style overrides+ lib/*.js, img/ the book's element library and images (assets.md)+ chNN/index.html, audio/<lang>/ a lesson, its beat MP3s + timings.js+```++## Pipeline++1. **Intake** ([intake.md](intake.md)), a short conversation: find the PDF with the user, split it, say what the book is, agree on one chapter to try and a tier, start the book folder, settle the look the way that tier needs, agree the models and write `style.json` ([core/style.md](../core/style.md)).+ - Split: `uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf`; use `--level N -o books/<book>/sections.json` at chapter depth. A chapter bookmark that points outside its neighbours is moved to the page holding its title or dropped, with a warning: look at those chapters' pages. For a PDF without usable chapter bookmarks, inspect `split_pages.py … --pages 1-12 --out books/<book>/pages`, then write the map from its contents (schema: `outline.py --help`). Extract chapter text with `split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only`.+ - Start the book folder with `new_book.py lesson <book>` ([core/publish.md](../core/publish.md#start-a-book-folder)) before showing the user any frames; build agreed shared components once into the book's library ([assets.md](assets.md)) and list them in `style.json`.+2. **Pilot.** Make the chosen chapter through the chapter loop and deliver it for the user's judgement. Fold their feedback into `style.json` and record the chapter under `approved`.+3. **Remaining chapters and finish**, when the user wants the whole book: write `chapters.md`, produce chapters one after another ([Team](#team)), complete cover text, contents and unit sketches ([cover.md](cover.md)). Deliver the static book folder, its entry URL for local preview and any unresolved issues.++A course book may also want verified citation links, a reviewed question bank or a SCORM package for an LMS; offer them only when the book calls for them ([courses.md](courses.md)).++## Chapter loop++1. **Read** this chapter's `pages/chNN/text.md`; render pages with `split_pages.py … --only chNN` when diagrams or missing text need images. Choose the ideas, examples and sections to teach.+2. **Beats and narration**: list beats in `chapters/chNN.md` with what each says and which word triggers which action ([authoring.md](authoring.md)). Write `content/<book>/chNN/narration.<lang>.json` and voice it with `tts.py` ([core/sound.md](../core/sound.md#voices)).+3. **Storyboard, layout first**: in the real page, place everything for one to three key moments per beat, real elements at their real sizes, no motion yet. Capture them into one sheet with `strip.py` and give each frame one line: what it says and where the eye goes. That sheet is the storyboard ([diagrams.md](diagrams.md), [scenes.md](scenes.md#storyboard-layout-first-then-motion)). Note what the chapter needs beyond the library: draw it, or add it to the image requests.+4. **Motion**: add the motion, the camera and the questions ([questions.md](questions.md)); API and replay invariants are in [core/engine.md](../core/engine.md).+5. **Delivery pass**: watch your output in motion and judge it as a viewer would, against the storyboard ([core/review.md](../core/review.md)); then run the lesson checks ([checks.md](checks.md)). Correct what you find, recheck, deliver; report unresolved problems.+6. **Register**: add the chapter to the contents (`units` in `Contents.book` in `index.html`, [cover.md](cover.md)), set the previous chapter's `CHAPTER.next`, update `chapters.md` and `chapters/chNN.md`. Promote new shared decisions and recurring elements to `style.json` and the library. The coordinator owns this step when using subagents.++## LaTeX++If the book's formulas need LaTeX ([core/engine.md](../core/engine.md#latex)), add MathJax (with its licence) to `lib/` and load `../lib/mathjax.js` right after `engine.js` in every chapter:++```sh+python3 SKILL/scripts/engine.py site/<book> --latex # lib/mathjax.js; later syncs keep it in step+```++## Team++The general shape and the coordinator's job are in [core/team.md](../core/team.md); a lesson splits by step of the chapter loop, chapters one after another.++In the pilot the picture worker stops when the storyboard sheet is ready and replies with it; the coordinator shows the sheet to the user, then continues the same worker with the user's changes to add motion.++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.py`, `check_blank.py`, `overlap.py`, `still.py`, `perf.py` in Firefox, and an e2e test adapted from the previous chapter's (the first from `assets/templates/e2e.py`, [checks.md](checks.md#interaction-tests)), 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 ([core/review.md](../core/review.md#watch-it-in-motion)) 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`, chapter counts on the cover, `chapters.md` and the status line in chNN.md. Then lint and e2e.diff --git a/.claude/skills/papermorph/references/lessons/questions.md b/.claude/skills/papermorph/references/lessons/questions.mdnew file mode 100644index 0000000..f65c4ab--- /dev/null+++ b/.claude/skills/papermorph/references/lessons/questions.md@@ -0,0 +1,40 @@+# Questions++Pick the type that lets the student act on the picture itself whenever possible (click the point, the cell, the step) rather than choosing text.++| Type | Use for |+| --- | --- |+| `choice` | One answer from a few options, each wrong option with its own explanation (from a reviewed item bank: `mcq`, [courses.md](courses.md)) |+| `blanks` | Typed numbers inside an expression; fractions and mixed numbers accepted; `test` judges a whole row (answers in any order) |+| `grid` | Several items, each classified (yes/no, which category, true/false) |+| `tap` / `tapEls` / `pickEls` | Click a point on the number line / a token in an expression / any drawn object |+| `pickPoint` | Choose a grid point on a coordinate plane (math.js) |+| `sorter` | Drag items into regions (the number-set diagram; math.js) |++New types are welcome when the content calls for one; each needs keyboard play.++## Writing them++- Ids: `c-…` for quick checks, `p-…` for practice; the score card adds them up.+- The prompt is rich text ([core/engine.md](../core/engine.md#traps)).+- Feedback: right → `why` (and an animation via `fx`/`onRight`); wrong → a hint aimed at that mistake; after a wrong try, Show answer.+- Grade meaning: equal values match (6/8 = 3/4) unless the lowest form is asked for; sets and pairs in any order; no denominators of zero; never judge irrationality from finitely many digits.+- The built-in numeric parser uses safe integer numerators and denominators and exact integer products for equality. For answers outside that range, use a subject-specific input and grader rather than allowing rounded values to pass.+- Compose the question beat for its card: the picture the question is about stays visible (for example in the top 60 % with a `BAND` card below, or beside a `{x, y, w, cls: 'side'}` card); `SCREEN` for practice.+- Units in typed answers: write the unit as a word after the box (`{ box: '60' }, ' kilograms'`) so it is not set as a math variable.++## API++```js+quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'], build: blanks([...]) }, …], done, 'Quick check')+```++- Positions: `BAND` (bottom band, y 686–886; long content can push it past the stage, so check it), `TOPR` (top right, ≤ 470 high), `RIGHT`, `SCREEN` (full-screen practice; the label names the set in the book's language, such as `'Chapter practice · set 1 of 2'`, and the engine appends "· question k of n" when a quiz has several questions), `SORT_SCREEN`, or any `{x, y, w, cls: 'side'}`.+- `choice(options, right, why, wrongWhys[], onRight?)` — number keys.+- `mcq(id, onRight?)` — (course option, [courses.md](courses.md)) a whole quiz entry (`{id, prompt, build: choice(...)}`) from the chapter's item bank: `quiz(TOPR, [mcq('c-attrib'), mcq('c-cause')], done)`. Needs `items.js` (built by `scripts/items.py`) loaded after `engine.js`; an unknown id throws.+- `blanks(rows)` — rows `{parts: [..., {box: '21'}, ...], why, hint?, fx?, test?}`; accepts −5, 3/4, 2 1/4, 0.75 as exact values, also with a currency sign ($60, 5 €) and thousands grouped by spaces of any kind (1 250, as [authoring.md](authoring.md#content-rules) shows numbers) or, where the decimal sign is a point, by commas (1,250); `{box, lowest: true}` demands lowest terms; `test(values)` judges the whole row (e.g. two factors in either order). `hint` is one message for any wrong value in its row; when different mistakes need their own answers, split the step into rows or ask it as a `choice` with `wrongWhys`. Tab moves between boxes, Enter checks, Esc leaves a box.+- `grid(rows, cols, {multi, text})` — rows `{parts, ans: [keys], why, fx?}`, cols `[[key, label, colour?, hotkey?]]`; with `text: true` parts are rich text (math via `$m`). ↑/↓ change rows.+- `tap(values, right, why, v => wrongWhy, onRight?)` points on the number line; `tapEls(row, idx, right, …)` tokens of a `tokens` row; `pickEls([{el, box: [x,y,w,h], label}], right, …)` any drawn objects; `pickPoint(P, [x,y], why, (x,y) => wrongWhy, onRight?, test?)` grid points (arrows + Enter or click); `sorter(items, trayXY)` drag into the set diagram (keys 1–6). `pickPoint` and `sorter` are in math.js.+- Answer animations run on their own clock: `fx`, `fxp`, `pulseFx`, `shakeFx`, `floatText`, `qlayer()` (a layer cleared with the question). They are finished automatically when the beat is left.+- A new type: `build(body, api)` returns `{ reveal, check?, lock?, key?(e), hint? }` and calls `api.grade(ok, message, {right, total})`. `key` handles its shortcuts (return true when used); `hint` lists the keys under the prompt. Every action needs a key; the help overlay (`?`) lists the global ones.+- Scores: `SCORE[id]` keeps the first try across revisits and step jumps; restarting the chapter clears it. A multi-row question scores one per row. A correct retry changes the feedback, not the first-attempt score.diff --git a/.claude/skills/papermorph/references/scenes.md b/.claude/skills/papermorph/references/lessons/scenes.mdsimilarity index 96%rename from .claude/skills/papermorph/references/scenes.mdrename to .claude/skills/papermorph/references/lessons/scenes.mdindex 8f26689..b34e849 100644--- a/.claude/skills/papermorph/references/scenes.md+++ b/.claude/skills/papermorph/references/lessons/scenes.md@@ -29,10 +29,10 @@ When the narration says someone pushes, throws or jumps, they perform it with we## The camera tells the story-Establish the scene, push in at the moment of contact, pull back for the result, follow a moving subject, switch views (side to top, split screen) to reveal structure. One purposeful move per beat is usually enough. Labels that must stay readable live in screen space and track their object (`cam.track`). See [engine.md](engine.md#world-clock-and-camera).+Establish the scene, push in at the moment of contact, pull back for the result, follow a moving subject, switch views (side to top, split screen) to reveal structure. One purposeful move per beat is usually enough. Labels that must stay readable live in screen space and track their object (`cam.track`). See [engine.md](../core/engine.md#world-clock-and-camera).## True at every momentMotion, arrows, labels and numbers state the same thing at the same moment. A force is drawn while it acts and disappears when contact ends; an accelerating object keeps accelerating while its label says so, so size the demonstration to the narration rather than clamping it at the frame edge; readouts come from the same function of time as the motion. Check worked numbers as the subject, not just as arithmetic. Scale realism is not needed; clarity for the reader is.-Still frames hide frozen actors and drifting timing; watch each action in motion before calling it done ([review.md](review.md#watch-it-in-motion)).+Still frames hide frozen actors and drifting timing; watch each action in motion before calling it done ([review.md](../core/review.md#watch-it-in-motion)).diff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/picture-books/painting.mdsimilarity index 96%rename from .claude/skills/papermorph/references/painting.mdrename to .claude/skills/papermorph/references/picture-books/painting.mdindex 51b7bf3..fca09f9 100644--- a/.claude/skills/papermorph/references/painting.md+++ b/.claude/skills/papermorph/references/picture-books/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 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; the picture holds every layer of the set, so a layer painted on its own needs its own reference, cropped or sketched as a set of its own), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. The exact geometry does not, so the places puppets and props stand at come from the painted set, not the sketch ([team.md](team.md#picture-books) says how to measure them). 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; the picture holds every layer of the set, so a layer painted on its own needs its own reference, cropped or sketched as a set of its own), then ask the model to repaint *that picture* in the style of the reference: the layout survives, the look changes. The exact geometry does not, so the places puppets and props stand at come from the painted set, not the sketch ([stories.md](stories.md#team) says how to measure them). 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/picture-books/puppets.mdsimilarity index 92%rename from .claude/skills/papermorph/references/puppets.mdrename to .claude/skills/papermorph/references/picture-books/puppets.mdindex 4431a68..2b1efd3 100644--- a/.claude/skills/papermorph/references/puppets.md+++ b/.claude/skills/papermorph/references/picture-books/puppets.md@@ -1,12 +1,20 @@# Paper puppets and the stop-motion look-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.+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`); `new_book.py picture` copies it into `site/<book>/lib/` and the first 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 (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.+## Contents++- What makes it read as stop motion+- Acting+- Cameras+- Performance+- Seeing your own work+## What makes it read as stop motion-- **Twelve frames a second, on twos.** `stopClock` samples every movement into steps; the slight jerk is the style, not a defect. Big moves still ease in and out across those steps. It draws through the beat's 0.6 s hold after the clip too (`clockRun`'s tail, engine-v2.1 on: [engine.md](engine.md#world-clock-and-camera)), so a scene's pose functions run to about `D + 0.6` and the frame the next scene cuts from is still alive.+- **Twelve frames a second, on twos.** `stopClock` samples every movement into steps; the slight jerk is the style, not a defect. Big moves still ease in and out across those steps. It draws through the beat's 0.6 s hold after the clip too (`clockRun`'s tail: [core/engine.md](../core/engine.md#world-clock-and-camera)), so a scene's pose functions run to about `D + 0.6` and the frame the next scene cuts from is still alive.- **The animator's hand.** Each frame nudges every puppet by a tiny random amount (`jit(frame, k)`, the same nudge for the same frame, so pause, seek and `?beat=N&t=S` show exactly what playback shows), and the picture flickers faintly. Keep it small: at full strength it reads as shaking; a third of a pixel-ish wobble, held for two frames, felt hand-made.- **Paper you can feel.** Grain, torn edges and a soft drop shadow on every piece (the `#paper` filter), brass pins at the joints, and a soft contact shadow under the feet so a puppet stands on the ground, leaning the way the set's light falls.- **Replacement, not morphing.** Mouths are swapped shapes timed to the words; a blink is two closed frames; a door opens through a few boards of different widths; a bun bitten is a different picture.@@ -37,4 +45,4 @@ Paper filters are expensive live, so every finished piece is baked to a bitmap;## Seeing your own work-The preview server must not cache (`serve.py`). Look at contact sheets that advance the clock the way playback does (`strip.py chNN OUT scene1/0.5 --url http://localhost:8765/<book>/`; times are on the beat clock, so a scene's speech starts at its `pre`, and marks of a joined scene are named `clip.mark`; `scene1:2..5/0.1@o@c` is an onion skin of one shot with the camera held still, for feet and hands), at full-size frames at the key moments (`shot.py`, beats counted from 0 or named), at the last frame of each scene beside the first of the next (`shot.py --cuts`), at the sounds against the picture (`playlog.py`), and play the whole episode through once at speed ([review.md](review.md) has the commands). Some faults appear only in continuous playback (a camera layer shown once and never hidden again), so don't rely on jumps with `?t=` alone.+The preview server must not cache (`serve.py`). Look at contact sheets that advance the clock the way playback does (`strip.py chNN OUT scene1/0.5 --url http://localhost:8765/<book>/`; times are on the beat clock, so a scene's speech starts at its `pre`, and marks of a joined scene are named `clip.mark`; `scene1:2..5/0.1@o@c` is an onion skin of one shot with the camera held still, for feet and hands), at full-size frames at the key moments (`shot.py`, beats counted from 0 or named), at the last frame of each scene beside the first of the next (`shot.py --cuts`), at the sounds against the picture (`playlog.py`), and play the whole episode through once at speed ([core/review.md](../core/review.md#watch-it-in-motion) has the commands). Some faults appear only in continuous playback (a camera layer shown once and never hidden again), so don't rely on jumps with `?t=` alone.diff --git a/.claude/skills/papermorph/references/picture-books/stories.md b/.claude/skills/papermorph/references/picture-books/stories.mdnew file mode 100644index 0000000..d20a9a3--- /dev/null+++ b/.claude/skills/papermorph/references/picture-books/stories.md@@ -0,0 +1,131 @@+# Picture books: from a story to an episode++A picture book is a short animated film, two to four minutes, told by paper puppets in front of sets. It starts from a story rather than a textbook: a fairy tale, a joke, something that happened to the user, or a story book's PDF. The published examples are on the shelf at https://papermorph.diamonddoge.org/: *Little Red Riding Hood* (everything drawn in code) and *Joke Collection* (painted sets, puppets in code; a series of episodes).++The craft is in three references: this one (the story, the shots, the sound and the team), [puppets.md](puppets.md) (the paper puppets and the stop-motion look) and [painting.md](painting.md) (sets and props painted by an image model). The engine, the player, previews, checks, voices and music are shared with every book ([core/sound.md](../core/sound.md), [core/review.md](../core/review.md), [core/engine.md](../core/engine.md)).++## Contents++- Intake for a story+- The order of work+- The book folder+- The script comes first+- Scenes, shots, cuts+- Sound+- Team+- Review rounds+- Delivering++## Intake for a story++Ask the way [core/style.md](../core/style.md#asking) says: a light conversation, choices to click, the user's words kept verbatim. What to settle, skipping whatever the telling already settles:++1. **The story itself.** Let the user tell it in their own words and keep that telling in `books/<book>/story.md` untouched. Ask what is true and must stay (a real joke has one real punchline), who the people are, where it happens, what language each person speaks.+2. **The look** is the user's to choose; there is no house style. Paper puppets moved in code ([puppets.md](puppets.md)) are what has worked best so far, so offer them first, in two ways, and welcome any other idea the user has:+ - *Painted world, paper actors* (recommended when an image budget is fine): an image model paints the sets and everything that stays still; the puppets and anything that moves stay in code (Joke Collection, under a dollar of pictures per episode). Ask for a budget ceiling and keep to it ([painting.md](painting.md)).+ - *Paper, all in code*: sets and props drawn as SVG paper too. No image cost, plainer, very consistent (Little Red Riding Hood).+3. **Language and voices**: the narration language, one voice per character ([core/sound.md](../core/sound.md#voices)).+4. **A series or one film.** A series shares cast, sets and the series page; each episode is a chapter (`chNN`).++Then agree on the models ([core/style.md](../core/style.md#models)) and write `style.json` from [the picture-book example](../../assets/templates/picture-book/style.json): `tier: "picture"`, the user's words, the look they chose, a voice for each character, an `illustration` block (the sets, the budget, the cast with a line each), the models, and later the approved episodes. It holds this book's own choices so that its episodes match each other; another book can look entirely different. Then go on to the script.++## The order of work++1. Intake (above), then the script and the storyboard, shown to the user (below).+2. Start the folder (below).+3. Sound: voices, mouth shapes, one joined clip per scene with its word times, sound effects ([Sound](#sound)).+4. Sets: sketch them in `sets.js`, bake them, and if the look is painted, paint them from the baked sketches ([painting.md](painting.md)).+5. The cast and the scenes, one script per scene ([puppets.md](puppets.md)); bake the puppet pieces.+6. Review rounds (below), then the user's viewing, then registering the episode.++## The book folder++`books/<book>/` holds `story.md` (the user's telling, verbatim), `storyboard.md` and `art/` (`sets.js` with the set sketches, generated pictures, `painted.json`, `costs.tsv`). `site/<book>/lib/` holds the paper kit (`paper.js`, `cast.js`, `shared.js` from `assets/templates/picture-book/`) beside the engine, and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`. The book's `index.html` is the series page.++`python3 SKILL/scripts/new_book.py picture <book>` makes it ([core/publish.md](../core/publish.md#start-a-book-folder)): the series page, the kit, `ch01/` with the sample `scene1.js`, `sets.js` and `painted.json` in `books/<book>/art/` (the second is only used by a painted look), and an empty `img/puppets/baked.js` that stands in until `bake_puppets.py` has run. Then the sound and the pictures, in this order, with the preview server running on 8765:++```sh+BOOK=jokes; A="site/$BOOK/ch01/audio/en"; N="content/$BOOK/ch01/narration.en.json"+uv run --with edge-tts python "$SKILL/scripts/tts.py" "$N" "$A"+python3 "$SKILL/scripts/level.py" "$A"/*.mp3+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" "site/$BOOK/ch01/audio/sfx" knock+```++Keep these commands in `tools/<book>/audio.sh` and rerun it after any change to the narration ([Sound](#sound)). 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" "books/$BOOK/art/sets.js" "site/$BOOK"+uv run --with playwright --with pillow python "$SKILL/scripts/bake_puppets.py" "site/$BOOK" --url "http://localhost:8765/$BOOK/"+```++## The script comes first++Write the script and a storyboard table (`books/<book>/storyboard.md`: scene, shot, what we see, who says what) and show them to the user before building anything. Changing a story on paper is cheap; once every shot is animated it is expensive, and almost every real failure in these books was a story failure that no amount of animation fixed.++What made the difference, from the books:++- **Set up everything the punchline needs.** The first cut of *Breakfast in the Bathroom* had Bo ask "Wanna go eat breakfast… in the bathroom?" out of nowhere; viewers took it literally. It became a joke once the film first showed his two everyday questions, "Breakfast?" every morning at the stall and "Bathroom?" after every class, and then the morning he overslept and came in starving.+- **Show the motive before the line.** Bo's stomach growls; a bun appears in a thought bubble; he glances at the door and a toilet appears beside it; the two bubbles shove each other and merge. Only then does he speak. The audience is ahead of him, which is where comedy happens.+- **Every event needs a cause the audience has seen.** In *Little Red Riding Hood* the first rescue had a woodcutter from nowhere, Grandma suddenly out of the wardrobe and the wolf flying out of the window as if Grandma had superpowers. The fix was a chain: the woodcutter chopping wood near the cottage earlier, a cut to Grandma's eye in the wardrobe crack during the questions, the cry for help, Grandma's umbrella on the wolf's head, the woodcutter blocking the door, the window the only way out, and outside, the window still broken.+- **The audience understands what the characters don't.** In *Do You Need a Bag?* the clerk speaks only Japanese and the customer only English: each line is spoken in its own language with subtitles, and a thought bubble shows the mishearing ("…REJI…?" turning into "VEGGIE?"), so the joke works for viewers who speak neither.+- **Keep the user's story.** Tighten the wording, add the small connecting moments a film needs, and list every addition for the user; don't swap their joke for a different one.++## Scenes, shots, cuts++One scene is one beat, with one joined audio clip ([Sound](#sound)); cuts inside a scene are timed to its clock. Plan shots the way a film does, because a fixed wide frame for a whole scene plays like a slideshow:++- a wide shot to say where we are, two-shots for conversations, a close-up for whoever speaks, closer and closer as tension rises (the three questions to "Grandma");+- reverse angles: whoever is in close-up has behind them what the other person sees (a separate camera on a matching set, not a zoom of the same one);+- an insert to make a detail readable (a coin on the counter, the clock, a face in a door crack);+- held silences: the beat where nobody speaks is often the joke. Blinks, eyes and a tiny head turn carry it.++Reviewers of the later episodes kept finding the same few things, all about what the viewer can read. Give every object the joke hangs on an insert of its own; the best episodes ran ten to fourteen shots a half minute. Keep whoever is being spoken to in the shot, since the listener's face is half of the line. Someone following stays far enough behind that the delay itself reads; people pass in front of or behind each other, never through. A face half cut by the frame edge, or a blink on the frame that carries the joke, reads as a mistake.++Everybody in the shot stays alive and stays there: extras blink and glance about in close-ups too (in an early cut the whole class vanished whenever someone spoke). Between places, cut or use a paper-theatre wipe; at the end, a title card.++## Sound++Voices, levels, effects and music work as in [core/sound.md](../core/sound.md); what a picture book adds is a cast that speaks on screen and one clip per scene.++- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes (a Chinese or Japanese line opens and shuts once per character), and `lips(q, scene, pre, line…)` picks the shape for the frame. Edge's word times run about a tenth of a second ahead of the sound; `mouths.py` and `join.py` move mouths and captions that much later and shut the mouth where the clip's sound stops, so a lip flap that leads or trails the voice is worth reporting.+- **One clip per scene.** `join.py` joins a scene's lines into one audio clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line, after a word's sound has ended rather than where the next word begins) or after the last line (`name:S`, a stare or a tag). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. `--words` writes every word's time in the scene clip beside the narration; scene authors time actions against it (the beat clock adds the scene's `pre`).+- **One script for the whole sound**, `tools/<book>/audio.sh`, rerun after any change: lines replaced by hand, `mouths.py`, level fixes, `join.py` with its holes, any caption edits. Join arguments typed only in a terminal have had to be read back out of `shots.js`.+- **Levels.** `level.py` goes in the script right after `tts.py` and before `join.py`, at its default −18 LUFS ([core/sound.md](../core/sound.md#levels)). The line the joke hangs on must not be the quietest; a line that must sit above the rest (a quiet old man's punchline) gets its own target (`level.py o1.mp3 --lufs -15`) and stays out of the others' list.+- **Sounds a voice makes.** Animal voices that speak (a dog's "Woof!") came out best from an Edge voice shouting the word, trimmed and normalized; synthesized barks lost to them. A whispered "Shh." is shaped pink noise, not Edge's voiced "shh-uh". Write such a clip over the line's MP3 and set its `dur` in `timings.js` before joining.+- **Effects and music** are placed on the scene clock (`sfx(scene, t, …)`, `music(…, [scene ids], …)`); a bed that loops overlaps its seams by about half a second. Give a scene silence when silence is the joke: `window.MUSIC_OFF = { scene: t => … }` fades the music out for a stare.+- **Captions** are on at a reader's first visit (`chapter.html` does this); the reader's own choice is remembered after that. A caption ends at the first real pause after its words; a hole inside a sentence keeps it up. When that gives away words before they are said (a punchline after a pause), split the caption at the hole in `shots.js`, and hold a punchline's caption into the silence after it; do this in the audio script after `join.py`, so a rerun keeps it.++## Team++The shape of [core/team.md](../core/team.md), split by scene instead of by step. The **strong** coordinator writes the script with the user and builds what every scene shares: cast, sets and their painting, the episode's helpers, the voices and the joined audio with its word times (`join.py --words`). Then it writes one brief for all scene workers:++- the story in a paragraph, and the user's words that set the bar;+- the episode kit's API, to read and not edit;+- each scene's `pre`, its holes and the word times to cut on;+- continuity: who stands where, facing whom, in the first and last frame of every scene, so the cuts match;+- where things are: each set's places for puppets and props, its camera ranges, what comes into view on each pan. A painted set lands some way off its sketch (a bench seat about 30 px), so measure the places on frames of the painted set (`shot.py … --clean` gives the stage alone) and check the table on frames of every set before sending the brief out (a puppet at each place, the camera at each end of its range): a table written from the sketches once put an ear off frame and feet below the ground, and five workers built on it;+- the style, the effects available, how to look at one's own work, and the reply (the shots with their times, the first and last frame, what each check showed).++One **middle** worker per scene, in parallel, writes only its own `sceneN.js`; a **small** worker synthesizes the sound effects from recipes. Before replying, a scene worker runs and reports on these, each with the book's `--url` (the screenshot scripts run with reduced motion, so the workers' browsers can run at once): a strip of its scene, with time ranges and `@o@c` for walks and hands ([core/review.md](../core/review.md#watch-it-in-motion)); full-size `shot.py` frames of its close-ups and of each moment a hand arrives; `shot.py --cuts sceneN` for its cuts in and out; `playlog.py --from sceneN --to sceneN`, since it cannot listen: is each effect on the frame it belongs to, each line on a moving mouth; and `still.py chNN sceneN`, saying which still stretches are meant.++Reviewers, in the rounds below: four report-only, a director (**strong**) for story, comedy, staging and shots; two picture reviewers (**middle**) splitting the scenes; one (**middle**) for sound and runtime. The coordinator merges their reports ([core/review.md](../core/review.md#review-rounds)), fixes the kit itself and sends scenes back to their workers. A fresh session as coordinator matters even more here: contact sheets are large, and an episode made in one long conversation spent most of its 22 million tokens rereading them.++## Review rounds++A first cut made in one pass looks like a first cut. What lifts an episode is watching it the way a director would, against the episodes the user already approved, and sending scenes back ([core/review.md](../core/review.md#review-rounds) has how rounds run).++- **Director's view**: contact sheets of the whole episode and its cut sheet (`shot.py --cuts`) beside an approved one (a series' first episode: beside its storyboard). Look for story-level causes, not glitches: is every object the joke hangs on given its own shot, is the cause shown before the payoff, are the reactions framed so they read, is the shot density close to the approved episodes', does a silence stay silent? Write a restaging for each scene that needs one: which shots, from where, on which word.+- **Picture and sound**: frame by frame for faces cut by the edge, popping poses, puppets passing through each other; sound for lines cut short, effects out of step, music over a silence.+- Restage the scenes from those notes, then look again; two rounds usually settle it.++Alone, do the same rounds yourself, one viewpoint at a time, writing each review down before changing anything.++## Delivering++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. A still is one frame of the episode saved as a 1400×788 WebP: `shot.py chNN --out books/<book>/review/stills sceneN:S --webp 1400 --name still-chNN --url http://localhost:8765/<book>/` writes it without the player's controls (beside a full-size PNG); copy the WebP to `site/<book>/img/`. The page's header shows `img/cover.webp`, a still too: the first episode's, or a frame the user picks, until the series has a picture of its own.diff --git a/.claude/skills/papermorph/references/review.md b/.claude/skills/papermorph/references/review.mddeleted file mode 100644index ba5d6c6..0000000--- a/.claude/skills/papermorph/references/review.md+++ /dev/null@@ -1,41 +0,0 @@-# 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. 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 --with numpy SKILL/scripts/strip.py chNN OUT --url http://localhost:8765/<book>/ push/0.25 law3/0.5@w roll:2..4/0.2@o walk:1..5/0.1@o@c-uv run --with playwright --with pillow SKILL/scripts/playlog.py chNN --out OUT --url http://localhost:8765/<book>/ # picture books: sounds against picture-```--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. An onion skin reads only within one shot, so give it that shot's range (`roll:2..4`, ends may be marks); `@c` draws a picture book's frames in the set's own framing, so under a pan a planted foot stays one sharp ghost and a sliding one smears. 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. An agent that cannot listen plays the chapter with `playlog.py` instead: it logs when each sound and caption starts in real playback and shows the stage rebuilt by seeking to that beat time, so a clack can be checked against the piece landing and a line against the mouth that says it (a fault that only continuous playback shows will not be in those frames). `--from`/`--to` play only some beats; a lesson stops at its first question.--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. In a picture book it switches off the kit's hand jitter and flicker first (a scene's own `jit`, falling snow or a tremble, still counts as motion), so a puppet that only breathes and blinks measures about 1–1.5 and acting 2 and up (its default threshold is 1.5). 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.--## Frames and openings--```sh-uv run --with playwright --with pillow SKILL/scripts/shot.py chNN --url http://localhost:8765/<book>/ --out OUT-uv run --with playwright --with pillow SKILL/scripts/shot.py chNN --url http://localhost:8765/<book>/ --out OUT --cuts # picture books-uv run --with playwright SKILL/scripts/check_blank.py site/<book> chNN --url http://localhost:8765/<book>/-uv run --with playwright SKILL/scripts/overlap.py chNN --url http://localhost:8765/<book>/-```--`shot.py` captures open/end frames of every beat as 4-up sheets and reports console errors. Look for an empty or unrelated opening, text over drawings or clipped at the edge, a card covering what it asks about, leftovers half faded, geometry contradicting its values, shapes inside circles or curves crossing the outline (check thin geometry on the full-size `chNN_bII_T.png`, not only the sheet), text too small at half size or too much at once, and the same idea in different colours. `--cuts` puts each beat's last frame beside the next one's first, one cut a row: in a picture book, look there for jumps in place, pose, light and screen direction. `check_blank.py` reports openings empty for more than a second after speech starts. `overlap.py` samples every beat and lists where an arrow runs through text or two texts collide, with times, so you can look at exactly those frames. Both are lesson checks and skip a picture book, whose set is always there and whose words are captions.--## Smoothness--`uv run --with playwright SKILL/scripts/perf.py chNN --url …` measures frame times in Firefox, which repaints SVG on the main thread and is the slowest common browser for these pages; headless Chromium hides paint cost. Look at the worst beats and transitions; the remedies are in [engine.md](engine.md#performance-firefox).--## Interaction tests--Adapt `assets/templates/e2e.py` into `tools/<book>/e2e_chNN.py`: it checks playback, that every beat replays the same frame when seeked, that quiz cards stay readable and on stage at two viewport sizes, and walks the answers, practice and finish card. `ANSWERS` maps each question beat to one step per question: a digit picks a choice, `=a,b` fills the boxes, `#2;1+3` answers a grid (rows split by `;`, each row's columns counted from 1, `+` for several, `#2;;1` a row left empty). Run it in Chromium and with `BROWSER=firefox`. Run existing tests of approved chapters after changing the book's engine or library.--After scoring changes, check a wrong first try stays recorded after revisiting and a restart clears it; after progress changes, check book isolation and missing or malformed stored data. Fix engine bugs at the engine source and copy them to the books with `scripts/engine.py`; book-specific settings stay in each book's `lib/book.css`.--Test details: keyboard first (Enter checks, Esc leaves a box, press Esc before S, R replays on the finish card); a page opened with `?beat=` is not started, so start it before pressing keys; `seek(i, false)` stops before the old panel's fade, so seek playing or evaluate past it; compare text in lower case (CSS uppercases kickers); avoid assertions on totals that grow with the book.diff --git a/.claude/skills/papermorph/references/shorts.md b/.claude/skills/papermorph/references/shorts.mddeleted file mode 100644index 5e9e79c..0000000--- a/.claude/skills/papermorph/references/shorts.md+++ /dev/null@@ -1,61 +0,0 @@-# Shorts: one point, under three minutes, upright, for a phone feed--A short is a narrated film on an upright 900 × 1600 stage (`<html data-stage="portrait">`), made for YouTube Shorts, TikTok, Reels or X. It makes one point in one to three minutes, with a new picture every one to three seconds: full-bleed photographs or generated pictures, big words, cut-out figures, a number counting up, a chart, a map. It is a cousin of the [documentary](documentary.md) and shares its voice, pictures, export and review; what differs is the pace, the grammar of the picture and where it ends up. The worked example is episode 1 of *Madness and Civilization* (`site/madness-shorts/ch01/`, *The Ship*), the ten-minute [documentary](documentary.md) on the shelf (`site/madness/`) recut as a series of shorts: watch it before making one, and treat it as a level to match, not a format to copy.--What is its own: the kit `assets/templates/shorts/` (`chapter.html`, `narration.en.json`, `style.json`; `lib/shorts.js`, `book.css`, `icons.js`; fonts from the documentary kit) and the order of work below. A map or a globe comes from the map kit it shares with the documentary ([documentary.md](documentary.md#maps)). It needs an engine with the upright stage ([engine.md](engine.md#stage-and-state)); an upright chapter is a film without questions.--## What the viewer is doing--They are scrolling. They decide in the first second whether to stay, and on the platforms' numbers that second is most of the outcome: one of our episodes opened on a generated city picture already moving, under its first line, and 57.8 % stayed past the first chance to swipe; another opened on a still card of text and 12.8 % stayed. A text card reads as a text post, and a line in a script the viewer cannot read is a wall. So the first frame is a picture in motion with the hook spoken over it, and the hook is the point itself, not a preamble ("there's a line that went viral…" spends the second that matters).--After that they stay as long as each moment gives them something new and the argument keeps moving. Background facts are where a short gets slow: compress them hardest and keep the steps of the argument.--## Questions for the user--The short is the user's argument; the Skill's work is to make it land. Ask, offering choices to click and skipping what the request already settles:--1. **The point.** What should a viewer believe or wonder about at the end? Who is the viewer (an overseas feed, a home audience), and which platform?-2. **The outline.** Ask for the user's outline before writing anything: the hook, the steps, the ending. If there is none, build the outline together; do not invent the argument. A series: its name, how many episodes and where the material divides (propose a split, each episode with its one point, as options to click), and how each episode hands on to the next. When the argument comes from a long film, see *From a long film* below.-3. **People.** How real people appear: period pictures for the dead, cut-out figures or drawings for the living, never photographs of living people's faces.-4. **Sources.** Which numbers and quotes need a source, and how strict to be about anonymous reports ("according to the Wall Street Journal…"). Look at the argument itself too: where the field disputes a claim the hook states as fact, say so and offer ways to put it (Foucault's ships of fools are doubted by historians; "Foucault went looking for real ones" kept the line and the truth).-5. **Voice and music.** The narrator (ElevenLabs v4 through OpenRouter was the accepted voice; Edge TTS is the free option): play short samples and let the user pick. Music: a public-domain recording ([documentary.md](documentary.md#intake) has the licence traps), or generated (Lyria, made outside the Skill for now).-6. **Pictures and budget.** Generated pictures, found ones, or both; what each costs per episode (voice about $0.07 a minute; 94 generated pictures at low quality cost $0.84 for one three-episode series; a picture made from a reference picture, to keep a figure or a style, costs about four times as much, since the reference counts as input: $0.016 against $0.004 at low).--Then agree the models ([intake.md](intake.md#5-models): writing the script with the user is strong-model work, building beats middle, checks small) and write `books/<book>/style.json` from the kit's [style.json](../assets/templates/shorts/style.json): `tier: "shorts"`, the platform, the user's words, the series with each episode's point, the look, the voice, the music and the models.--## From a long film--When the user wants a film that already exists recut as shorts (*Madness and Civilization* became four), the argument is there: its script is the outline, and its checked quotes, found pictures, voice and music carry over. The first questions change: how many episodes, where the film's turns divide them, and what each episode's one point is. Propose the split and episode 1's outline together, then go on as below. Read the film's `style.json`, its narration and its `SOURCES.tsv` before asking anything they already answer. Where a short's habits and the film's differ, ask the user: the documentary's one Fool through the centuries is a recurring figure, which the short's rule of one figure per role would break.--## The order of work--1. **The script, beat by beat, with the user.** Keep it in `books/<book>/chNN-script.md`: the agreed outline, a table of beats (the narration, one line of what we see, and its rough length: words ÷ the voice's pace, about 2.6 words a second for an ElevenLabs narrator, plus about 1.4 s a beat for the engine's hold after the words, 0.6 s, and the camera's tail, 0.8 s in the worked example; a twelve-beat script ran 17 s longer than its words), and each number's and quote's source under it. Show it to the user a few beats at a time and rewrite as they answer. A background beat that comes out over about eight seconds is where the short will feel slow; shorten it before the voice is paid for. Once it is voiced, the length hides in the voice's own sentence pauses (0.4 to 1.0 s from ElevenLabs): `eleven.py --max-pause 0.3` shortens them before the marks are placed (one episode went from 112 s to 107 s). The beats' narration, with `[[mark]]` before each word a picture lands on, goes into `content/<book>/chNN/narration.en.json` (the kit's sample shows the format); keep the two in step.-2. **The storyboard, then the cast and the pictures.** One line per shot, a shot every one to three seconds, under each beat of the script: that is the list of pictures to make or find, and a beat-by-beat plan is too coarse for it (one director pass asked for three new pictures the plan had missed). Who appears where: one figure per role, so that a figure coming back means something (a callback), not that the cast ran out. Note each picture's prompt or source and cost, quote the batch before paying, and show the user the pictures as they come. `prep.py`'s `full` treatment sizes full-bleed pictures for the stage. Episodes made at the same time each keep their own sizes file (`prep.py … --art ch03-art.js`, loaded by the episode after `img/art.js`), so no two of them edit the same line.-3. **The folder.** `engine.py site/<book>` first (it starts `lib/` with the engine and a default `book.css`), then the kit's `lib/` over it, with the documentary kit's `fonts.css` and `fonts/`; `chNN/index.html` starts from the kit's `chapter.html` (the commands are in [site.md](site.md#a-short)). The film's own pieces (its cast's sizes in `MEME`, a series card) go in a second file loaded after `shorts.js` (*Madness and Civilization*: `lib/madness.js`); a map or the globe is the map kit's, whose lines `chapter.html` carries commented out. Every episode but a series' last sets `CHAPTER.next` to the next one: the end card names the next episode, and the player offers it only when `next` is set.-4. **Voice.** `eleven.py` or `tts.py`, one clip per beat plus `timings.js`. A series that speaks faster than the voice's own pace (*The Pandemic*'s narrator at ×1.1) puts `"tempo": 1.1` in each narration file, or passes `eleven.py --tempo 1.1`: the clips are sped before they are levelled and aligned, and a rerun keeps it. A wordless beat (a series card, an end card) needs no clip, no `timings.js` entry and no narration line: `{ dur: 2 }` in its fourth slot ([engine.md](engine.md#timing)); `lint.py`, `export.py`, `music.py` and `check.py` take it as silence, and the music stays ducked under it. Every clip goes out at one level, −14 LUFS with its peak under −1.5 dBTP: `eleven.py` levels its clips and prints what it delivered (the voice service gives about −23 LUFS, which sank one episode under its music); after `tts.py`, run `level.py --lufs -14 --peak -1.5`. Check the marks on spoken numbers: the transcript writes "a hundred and twenty" as "120"; `eleven.py` matches the digits to the spoken words and prints the marks a rerun moved, but a number the matcher missed still lands late (seven marks in one episode, up to 0.75 s). A time only the page needs (an end card's) goes in the page, not in `timings.js`, which the next voice run rewrites.-5. **Music.** One track for the whole episode under every beat, `music(file, undefined, gain, .05)`. It changes by easing, at a turn of the argument, never by stopping: a dead stop on a rhetorical question felt staged to the user, and so did a classical recording's rests and quiet phrase ends falling into the voice's pauses. `music.py cut SRC site/<book>/chNN/audio/bgm/epN.mp3 chNN --url …/<book>/` cuts a recording so its last note lands on the film's end (the last moment it is within 10 LU of its body, so a long decay rings past the end instead of leaving the end card silent; `--end` sets it by hand) and levels the file to −16 LUFS; `--rests` splices out its rests, `--even` evens out its quiet phrase ends, and a generated (Lyria) track usually needs `--even` too, since its quiet passages fall into the voice's gaps just as a recording's do. `--lift T` raises a hole that neither fixes (a phrase end with no rest). The cut is made for one length: after any change to a beat's length, cut again (`gaps` says "recut"). A looping track is fine for a first cut. Leave `?bgm=` on the page so the user can set the level by ear; start around 0.4: with the engine's ducking to 30 %, a track at −16 LUFS sits at about −34 LUFS, 20 LU under a −14 LUFS voice, the level the user chose for episode 1 (its track −16.3 LUFS). The gain is relative to the track's own loudness, so give both. `music.py gaps chNN --url …/<book>/` lists the bed's loudness in each voice-free gap and after the last word, and marks the holes; `--mp4` measures the export the same way. A measurement catches gross errors; the ear decides.-6. **The beats**, built from the kit and timed to the marks; sound effects (`sfx.py whoosh bang tick thud`) under the cuts and the stamps. A beat ends at its last tween plus the hold, so the kit's habit of pushing a picture past the voice (`photo(s, …, 0, D + .6)`) lengthens the beat by as much: two beats with the same voice can differ by what their tweens overrun. `?lengths` on the page prints each beat's voice against its length on screen. Two mirrored beats (two answers treated alike) get the same seconds with `{ minDur }` set to the longer one's length.-7. **Watch it yourself, then a director pass.** Contact sheets of every beat (`strip.py`), and the first frame on its own, upright as the feed shows it: `shot.py chNN --out books/<book>/review/first 0:0.3 --clean --url http://localhost:8765/<book>/` writes the bare 900 × 1600 stage. Look at it with the platform's title, caption and buttons in mind (the safe area below). Measure what a script can: page errors, console warnings and beat lengths in both browsers (`check.py chNN --url …`), a shot held still too long (`still.py chNN --min 2`), a number that lands after it is said, words outside the safe area (`safe.py chNN --query tags`, sampled across every beat; the contact sheets hid nine such words in one episode; `strip.py` and `shot.py` take `--query tags` too, to see the tags the export will show). A push too gentle to see (1.0 to 1.08 over six seconds) reads as a dead frame on a phone and on a contact sheet alike: on a shot that long, push at least about 15 %, or cut. A fresh agent on a strong model reviews the sheets against an approved episode without knowing how the beats were built ([documentary.md](documentary.md#review-rounds)); half of what it finds is usually the picture saying something other than the voice. Then a second round on the exported MP4 ([documentary.md](documentary.md#review-rounds)).-8. **The user watches**, you fix, and `export.py chNN --url …/<book>/ --out books/<book>/export` writes a 1080 × 1920 MP4 and an `.srt` (on an upright film it shows the source and AI-illustration tags, since the video leaves the page that credits them; `--no-tags` leaves them out; a minute and a half took about twelve minutes). The user uploads it and ticks the platform's AI or synthetic-content box. A video over 25 MiB does not fit Cloudflare Pages; the web page itself is the light version. A series card's still is upright too: `shot.py … --webp 600` writes a 600 × 1067 WebP of the stage.--## The picture--`shorts.js` holds the grammar, every helper a pure function of the beat clock:--- `shot()` a full-frame shot with a hard cut, `whip` (a sideways slide with motion blur) or `swipe` (the next clip rising as in a feed); `photo()` a full-bleed picture with a slow push, centred; `found()` the same for a found photograph, tagged with its source; `wide()` a camera across a landscape picture whose subject is off-centre, never showing an edge; `plate()` a picture placed whole on the ground (sizes from `img/art.js`). A picture whose point is its text (a sign, a headline) goes in whole with `plate()`: an upright crop of a shop sign left "Y. WE / RARY CLOS";-- `word()` big condensed capitals (a word wider than its `maxW`, 660, is set smaller, so it and its stroke stay in the safe area), `label()` and `band()` caps on solid blocks, `marker()` a highlighter sweep, `vlog()` white outlined overlay text, `srcTag()` a source or "AI illustration";-- `meme()` a cut-out figure rising in, `swarm()` one crossing then a crowd of them, `stamp()` a rubber stamp slammed on, `counter()` a number counting up, `priceTag()`, `phoneCard()`, `ico()` and `icons()` (Phosphor, MIT), `bar()`, `clipImg()`;-- its palette (`DARK`, `RED`, `LIGHT`, `MUTED`, …, set in `lib/book.css` as `--dark`, `--red`, …), fonts (`SANS`, `SERIF`) and small tools (`inkW()` text width, `ramp01()`, `seeded()`) are named apart from the documentary kit's `film.js`, so a short can load `film.js` too when it wants a documentary helper (`pic()`, `say()`, `traced()`): load it before `shorts.js`;-- `shortsBeat` turns a beat tuple into the engine's beat with every cue `LEAD` (0.22 s) early: a cut that lands on the word itself reads as late.--What made the first shorts work:--- **One idea per shot, one to three seconds a shot**, full bleed; words inside x 50–810, y 130–1290, since the platform draws its title, caption and buttons over the rest.-- **Say it literally.** When the narration describes a mechanism, draw each link as the voice names it. The "everyone is cheap" loop read as a vague circle until it became three people, each handing the next their product and its price, A to B, B to C, C back to A.-- **Numbers move.** A count, a bar growing, a price tag swapped: a number on screen arrives the moment it is said. A big denominator can be drawn literally: "2 in 100,000" as a field of 100,000 dots in one SVG `<pattern>` fill with the two real circles over it played at 17 ms a frame in both browsers.-- **A series says where it is.** A few seconds after the hook: the series card with this episode lit ("1 · The Ship"), then the argument.-- **The ending points on.** The last beat answers the hook and names the next episode.--## Later--Scripts to come: cuts on the music's own beat, and generating music with Lyria.diff --git a/.claude/skills/papermorph/references/site.md b/.claude/skills/papermorph/references/site.mddeleted file mode 100644index d6ebea2..0000000--- a/.claude/skills/papermorph/references/site.md+++ /dev/null@@ -1,164 +0,0 @@-# The book: static folder, cover and contents--The book is static: HTML, JS, CSS, MP3. No build step, backend, database or accounts; reading progress lives in the browser (`localStorage`). The runnable output is `site/<book>/`; source material and production notes stay outside it.--## Start a book folder--Set `SKILL` to the installed skill folder. Run once for a new slug; use an existing book's actual files when resuming:--```sh-BOOK_ID=history-BOOK_SITE="site/$BOOK_ID"-BOOK_WORK="books/$BOOK_ID"-mkdir -p "$BOOK_SITE/lib" "$BOOK_SITE/img" "$BOOK_SITE/ch01" "$BOOK_WORK/chapters" "$BOOK_WORK/images/inbox" "content/$BOOK_ID/ch01" "tools/$BOOK_ID"-python3 "$SKILL/scripts/engine.py" "$BOOK_SITE" # the engine into lib/, plus lib/book.css for this book's settings-cp "$SKILL/assets/templates/book.html" "$BOOK_SITE/index.html"-cp "$SKILL/assets/templates/unit-art.js" "$BOOK_SITE/unit-art.js"-cp "$SKILL/assets/templates/chapter.html" "$BOOK_SITE/ch01/index.html"-cp "$SKILL/assets/templates/narration.en.json" "content/$BOOK_ID/ch01/narration.en.json"-```--### A picture book--Instead of the block above (not after it). The book's `index.html` is the series page; each episode comes from the picture-book kit, and the empty `baked.js` stands in until `bake_puppets.py` has run:--```sh-BOOK_ID=jokes-BOOK_SITE="site/$BOOK_ID"-BOOK_WORK="books/$BOOK_ID"-PB="$SKILL/assets/templates/picture-book"-mkdir -p "$BOOK_SITE/lib" "$BOOK_SITE/img/puppets" "$BOOK_SITE/ch01" "$BOOK_WORK/art" "content/$BOOK_ID/ch01" "tools/$BOOK_ID"-python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"-cp "$PB/series.html" "$BOOK_SITE/index.html"-cp "$PB"/lib/*.js "$BOOK_SITE/lib/"-cp "$PB/chapter.html" "$BOOK_SITE/ch01/index.html"; cp "$PB/scene1.js" "$BOOK_SITE/ch01/"-cp "$PB/sets.js" "$BOOK_WORK/art/"-cp "$PB/narration.en.json" "content/$BOOK_ID/ch01/"-echo 'window.BAKED = {};' > "$BOOK_SITE/img/puppets/baked.js"-```--For a painted look, also `cp "$PB/painted.json" "$BOOK_WORK/art/"` ([painting.md](painting.md)). Then the sound and the pictures, in this order ([sound.md](sound.md), [puppets.md](puppets.md)), with the preview server running on 8765:--```sh-A="$BOOK_SITE/ch01/audio/en"; N="content/$BOOK_ID/ch01/narration.en.json"-uv run --with edge-tts python "$SKILL/scripts/tts.py" "$N" "$A"-python3 "$SKILL/scripts/level.py" "$A"/*.mp3-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/"-```--### A documentary--Instead of the first block, like a picture book's. `engine.py` runs first, on the new folder: it refuses a `lib/` that already holds files but no engine. The kit's `lib/` then goes over it, its `book.css` replacing the default one. The book's `index.html` is the picture-book series page, given the film's colours and fonts and a credits section listing every picture and recording from `SOURCES.tsv` (as *Madness and Civilization* does); a single film is a series of one.--```sh-BOOK_ID=film-BOOK_SITE="site/$BOOK_ID"-BOOK_WORK="books/$BOOK_ID"-DK="$SKILL/assets/templates/documentary"-mkdir -p "$BOOK_SITE/lib" "$BOOK_SITE/img" "$BOOK_SITE/ch01" "$BOOK_WORK/art/found" "content/$BOOK_ID/ch01" "tools/$BOOK_ID"-python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"-cp -R "$DK"/lib/. "$BOOK_SITE/lib/"-cp "$DK/chapter.html" "$BOOK_SITE/ch01/index.html"-cp "$SKILL/assets/templates/picture-book/series.html" "$BOOK_SITE/index.html"-cp "$DK/narration.en.json" "content/$BOOK_ID/ch01/"-echo 'window.ART = {};' > "$BOOK_SITE/img/art.js"-```--`prep.py` fills `img/art.js` as pictures are treated. The kit's sample beat shows a picture named `first-picture` once there is one; until then it shows the title alone. Voice the sample with `uv run --with edge-tts python "$SKILL/scripts/tts.py" "content/$BOOK_ID/ch01/narration.en.json" "$BOOK_SITE/ch01/audio/en"` and open `ch01/` to check the folder works, then replace the narration with the film's script ([documentary.md](documentary.md#the-order-of-work)).--### A short--Like a documentary: `engine.py` first, then the shorts kit's `lib/` over it, with the documentary kit's fonts. Each episode is a chapter; its sound effects come from `sfx.py`. The commands for an empty book (a series page and shelf registration come later, as for any book):--```sh-BOOK_ID=short-BOOK_SITE="site/$BOOK_ID"-SK="$SKILL/assets/templates/shorts"-DK="$SKILL/assets/templates/documentary"-mkdir -p "$BOOK_SITE/lib" "$BOOK_SITE/img" "$BOOK_SITE/ch01/audio/sfx" "content/$BOOK_ID/ch01" "books/$BOOK_ID/art"-python3 "$SKILL/scripts/engine.py" "$BOOK_SITE"-cp -R "$SK"/lib/. "$BOOK_SITE/lib/"-cp -R "$DK/lib/fonts.css" "$DK/lib/fonts" "$BOOK_SITE/lib/"-cp "$SK/chapter.html" "$BOOK_SITE/ch01/index.html"-cp "$SK/narration.en.json" "content/$BOOK_ID/ch01/"-echo 'window.ART = {};' > "$BOOK_SITE/img/art.js"-uv run --with edge-tts python "$SKILL/scripts/tts.py" "content/$BOOK_ID/ch01/narration.en.json" "$BOOK_SITE/ch01/audio/en"-uv run --with numpy python "$SKILL/scripts/sfx.py" "$BOOK_SITE/ch01/audio/sfx" whoosh bang tick thud-```--Open `ch01/` to check the folder works: the kit's sample beat plays its line over `img/hook-picture.webp`, so until that picture exists the browser draws a broken image behind its words and the console shows one 404 (and `shot.py`, which stops on any page error, takes no screenshots). The music line in `chapter.html` is commented out until the episode has its track (`audio/bgm/ep1.mp3`), and so are the map kit's lines. Then the script replaces the sample narration ([shorts.md](shorts.md#the-order-of-work)). Until the series has a page, the player's home button leads nowhere; a series of shorts can also live on its long film's series page (*Madness and Civilization* lists its shorts at `/madness/#shorts`, and the host's `_redirects` sends `/madness-shorts/` there).--A series with a map adds the kit and its data (the regions, places and detail its films show: [documentary.md](documentary.md#maps)); a documentary does the same:--```sh-cp "$SKILL"/assets/templates/maps/lib/*.js "$BOOK_SITE/lib/"-uv run --with pillow python3 "$SKILL/scripts/geo.py" "$BOOK_SITE/img" --globe "$BOOK_SITE/lib" # the globe too; without --globe, plain python3-```--### 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` (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). A chapter's minutes appear on its title screen (`CHAPTER.minutes`), its contents card and a series card; write the same number in each: the length of its audio (the `dur`s in `timings.js`) plus about 15 s for each question, rounded to whole minutes and never below 1. 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:--```sh-python3 "$SKILL/scripts/engine.py" "$BOOK_SITE" --latex # lib/mathjax.js; later syncs keep it in step-```--Each book has its own engine copy (kept in step with `engine.py`, see [engine.md](engine.md)), source materials, narration and optional tests. The engine and cover derive the same progress key from the book's URL folder (or `--progress-key` in `lib/book.css`), so moving a book to another folder resets its readers' progress unless the key is set.--A chapter returns to its book's index. Preserve cover → contents → chapter navigation and the return from contents to cover. The book opens directly at `/<book>/`; it needs no parent index page.--## Cover and contents (`index.html`)--A textbook's cover and contents; a picture book, a documentary or a series of shorts uses the series page instead ([stories.md](stories.md#delivering), [above](#a-documentary)).--One page: no hash or `#book` shows the cover, `#references` the reference list, `#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, and set the previous chapter's `CHAPTER.next = '../chNN/'`.- - A unit's optional third entry `{ unit, chapter, sample: true }` renumbers it 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 that cites works gets a `#references` view ([courses.md](courses.md#citations)).-- 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.--## Unit sketches (`unit-art.js`)--Give each unit a small sketch of its own ideas, drawn in the unit colour, with one gentle topic-related loop. Use the agreed asset approach. Keep the left third light for the title on phones; check the finished contents at 1440 px and 390 px once. Classes and loop examples are in `unit-art.js`; the shared header styles, off-screen pausing and reduced motion live in the engine's `lib/units.css` and `lib/units.js` (`Units.header`, `Units.watch`).--## Guide character--The infinity guide comes with the engine (`mascotEl` in `engine.js`, the cover's in `contents.js`), so a book's copy is replaced at every sync. A custom guide needs a hook in the engine itself; agree it with the user and change the engine at its source.--## Local preview and delivery--Serve the static output over HTTP for audio playback:--```sh-python3 SKILL/scripts/serve.py 8765 site # no-store, so edits are never hidden by the browser cache-```--Open `http://localhost:8765/<book>/`. Confirm the cover opens the contents, ready chapter links load their lessons, lessons return to the book's contents, and any reference links open their works. Deliver `site/<book>/` with its HTML, scripts, styles and audio, the preview command and entry URL, available chapter count and unresolved issues. Source PDFs, extracted pages, narration drafts and development environments are not part of the static book.--## Languages--Narration and on-screen text are written in one language first. A second language comes after the book is done and approved: keep beat ids and question ids stable, add `narration.<lang>.json` and audio per language, and decide with the user how switching behaves mid-lesson before building it.--## Video export (optional)--`uv run --with playwright --with numpy SKILL/scripts/export.py chNN --url http://localhost:8765/<book>/ --out OUT --link <lesson URL>` renders the beats to `OUT/chNN.mp4` (1080p, or 1080 × 1920 on the upright stage; 30 fps) plus `OUT/chNN.srt` for upload with it. Frames come from seeking the beat clock and the sound is mixed by the page's own rules (each beat's `pre`, and in a picture book its effects and music), so the video matches the page; question beats are left out and a lesson's video ends on a card pointing to the interactive lesson (in a film with `CHAPTER.film`, they stay in: each holds its picture for the beat's `hold` s, with the music up at 70 % as the page plays it while it waits, then the next beat plays as if the reader had acted; [documentary.md](documentary.md#interactive-moments)). A mix that would clip is turned down as a whole, and the run says by how much; odd sizes are cut to even ones (an upright `--height 720` gives 404 × 720). The video is written beside the old one and renamed when done, so a failed run leaves an earlier `chNN.mp4` alone. How long it takes depends on the frame size and the machine: a 98.5 s upright short at 1080 × 1920 took 11 min 42 s (about 7× its length); `--height 720 --fps 10` makes a quick check copy. Video files are large (an episode at 1080p is tens of megabytes, more than a static host such as Cloudflare Pages takes per file): upload them to the video site, not into `site/`.diff --git a/.claude/skills/papermorph/references/sound.md b/.claude/skills/papermorph/references/sound.mddeleted file mode 100644index 225b23b..0000000--- a/.claude/skills/papermorph/references/sound.md+++ /dev/null@@ -1,29 +0,0 @@-# Sound for picture books--Voices carry the story; everything else sits under them. In early cuts the music and effects were loud enough that the lines got lost, and that was the first thing viewers noticed.--## Voices--- **One voice per character.** List them under `voices` in `narration.<lang>.json` and write each line as `{"speaker": name, "text": …}` (a line without a speaker takes the file's own `voice`; a speaker missing from `voices` stops the run, naming it); `tts.py` synthesizes every line (Edge voices, with rate and pitch: children were adult voices sped up and pitched up). The narrator is a voice too.-- **Lines in other languages** are spoken in their own language by a native voice (Edge has Japanese, Chinese, Korean and more) and subtitled in the book's language. The caption shows both: the original and the translation in brackets. Write it as the beat's `"sub"`; `tts.py` marks such a line (its voice's locale differs from the narration file's language) so the page shows its subtitle even with captions off, the way films subtitle foreign dialogue (engine v2.4.1; an older engine shows it only for a picture book joined by `join.py`).-- **Mouths** follow the words: `mouths.py` turns each line's word timings into mouth shapes (a Chinese or Japanese line opens and shuts once per character), and `lips(q, scene, pre, line…)` picks the shape for the frame. Edge's word times run about a tenth of a second ahead of the sound; `mouths.py` and `join.py` move mouths and captions that much later and shut the mouth where the clip's sound stops, so a lip flap that leads or trails the voice is worth reporting.-- **One clip per scene.** `join.py` joins a scene's lines into one audio clip with short pauses, and inserts silence where the action needs room (`line@T+S`: S seconds of silence T seconds into the line, after a word's sound has ended rather than where the next word begins) or after the last line (`name:S`, a stare or a tag). Gaps for a held stare, a fly landing, a class turning round belong here, not in rushed animation. `--words` writes every word's time in the scene clip beside the narration; scene authors time actions against it (the beat clock adds the scene's `pre`).-- **One script for the whole sound.** Keep the episode's audio steps in one script beside the book's notes (`tools/<book>/audio.sh`) and rerun it after any change: lines replaced by hand, `mouths.py`, level fixes, `join.py` with its holes, any caption edits. One episode's join arguments lived only in a terminal and had to be read back out of `shots.js`.-- **Levels.** The line the joke hangs on must not be the quietest, voices need pitches apart (a dog at 113 Hz under a 110 Hz narrator read as the same person), and peaks stay under -1 dB. `python3 SKILL/scripts/level.py <clips>` brings clips to one loudness (`--lufs`, default -18) under a limiter (`--peak`, default -1 dB) without moving a word, and leaves an already level clip, or one under 0.4 s (a tick, a clack), as it is, so the script can be rerun; it goes in the audio script right after `tts.py` and before `join.py`. A line that must sit above the rest (a quiet old man's punchline) gets its own target and stays out of the others' list (`level.py o1.mp3 --lufs -15`), so a rerun leaves it alone too; `--gain` adds again on every run, so it suits a one-off fix, not the script.-- **Sounds a voice makes.** Animal voices that speak (a dog's "Woof!") came out best from an Edge voice shouting the word, trimmed and normalized; synthesized barks lost to them. A whispered "Shh." is shaped pink noise, not Edge's voiced "shh-uh". Write such a clip over the line's MP3 and set its `dur` in `timings.js` before joining.--## Sound effects--`sfx.py` synthesizes effects as small MP3s, free and consistent (knock, door, creak, bell, chop, crash, coin, rain, wind, room tone, surf, gulls, crickets, footsteps (`patter`, `step1`), a dog and more; `--list` names them all). A sound the list lacks goes in the book's own `books/<book>/sfx_recipes.py`, passed with `--recipes`: each top-level function without required arguments is a recipe named after it, returning samples at `sfx.SR`, built from sfx's own helpers, its docstring's first line shown by `--list` (the script's header has the details). Keep them soft and natural: the first rain was a high hiss and read as scary; pink noise with patter and taps on umbrellas read as rain.--- Place an effect on the scene clock with the engine's `sfx(scene, t, name, volume)`; it plays at half volume under the voices, a pause holds it and the next scene stops it.-- Cut an effect to its shot: a six-second rain under a one-second shot spills into the next.-- A long bed (wind, room tone, the 10 s `birds` of a park) is listed in `SFX_BED` with its length (`SFX_BED.birds = 10`), so a seek into the middle joins it part-way; a bed that loops overlaps its seams by about half a second, and room tone runs under the silences too, where its absence is heard first.--## Music--Music is optional and goes under everything: `music('audio/bgm/theme.mp3', [scene ids], gain, fade)` in the chapter page, one call per track. It sits at 30 % of its own level for the whole of every scene, with voices or without (its silent opening and tail too, so it does not swell between lines); `window.MUSIC_UP_IN_PRE = ['scene']` lifts it to 70 % in that scene's `pre`, its music-only opening. Tracks crossfade over `fade` seconds (0.8 by default; 0 is a cut). Give a scene silence when silence is the joke: `window.MUSIC_OFF = { scene: t => … }` fades it out for a stare. Don't let music stop dead in the middle of a scene; carry it to the end or fade it, and bring an earlier theme back when the story returns to an earlier place. Use tracks the book may redistribute (generated for the book, or openly licensed) and credit them.--## Captions--Picture books turn captions on at a reader's first visit (`chapter.html` does this); the reader's own choice is remembered after that. A caption appears when its words are heard and ends at the first real pause after them; a hole inside a sentence keeps its caption up. When that gives away words before they are said (a punchline after a pause), split the caption at the hole in `shots.js`, and hold a punchline's caption into the silence after it; do this in the audio script after `join.py`, so a rerun keeps it.diff --git a/.claude/skills/papermorph/references/stories.md b/.claude/skills/papermorph/references/stories.mddeleted file mode 100644index ed9892d..0000000--- a/.claude/skills/papermorph/references/stories.md+++ /dev/null@@ -1,68 +0,0 @@-# Picture books: from a story to an episode--A picture book is a short animated film, two to four minutes, told by paper puppets in front of sets. It starts from a story rather than a textbook: a fairy tale, a joke, something that happened to the user, or a story book's PDF. The published examples are on the shelf at https://papermorph.diamonddoge.org/: *Little Red Riding Hood* (everything drawn in code) and *Joke Collection* (painted sets, puppets in code; a series of episodes).--The craft is in four references: this one (the story and the shots), [puppets.md](puppets.md) (the paper puppets and the stop-motion look), [painting.md](painting.md) (sets and props painted by an image model) and [sound.md](sound.md) (voices, sound effects, music). The engine, the player, previews, checks and the team are the same as for every other book.--## Intake for a story--The same spirit as [intake.md](intake.md): a light conversation, choices to click, the user's words kept verbatim. What to settle, skipping whatever the telling already settles:--1. **The story itself.** Let the user tell it in their own words and keep that telling in `books/<book>/story.md` untouched. Ask what is true and must stay (a real joke has one real punchline), who the people are, where it happens, what language each person speaks.-2. **The look** is the user's to choose; there is no house style. Paper puppets moved in code ([puppets.md](puppets.md)) are what has worked best so far, so offer them first, in two ways, and welcome any other idea the user has:- - *Painted world, paper actors* (recommended when an image budget is fine): an image model paints the sets and everything that stays still; the puppets and anything that moves stay in code (Joke Collection, under a dollar of pictures per episode). Ask for a budget ceiling and keep to it ([painting.md](painting.md)).- - *Paper, all in code*: sets and props drawn as SVG paper too. No image cost, plainer, very consistent (Little Red Riding Hood).-3. **Language and voices**: the narration language, one voice per character ([sound.md](sound.md)).-4. **A series or one film.** A series shares cast, sets and the series page; each episode is a chapter (`chNN`).--Then agree on the models ([intake.md](intake.md#5-models)) and write `style.json` from [the picture-book example](../assets/templates/picture-book/style.json): `tier: "picture"`, the user's words, the look they chose, a voice for each character, an `illustration` block (the sets, the budget, the cast with a line each), the models, and later the approved episodes. It holds this book's own choices so that its episodes match each other; another book can look entirely different. Then go on to the script.--## The order of work--1. Intake (above), then the script and the storyboard, shown to the user (below).-2. Start the folder ([site.md](site.md#a-picture-book)).-3. Sound: voices, mouth shapes, one joined clip per scene with its word times, sound effects ([sound.md](sound.md)).-4. Sets: sketch them in `sets.js`, bake them, and if the look is painted, paint them from the baked sketches ([painting.md](painting.md)).-5. The cast and the scenes, one script per scene ([puppets.md](puppets.md)); bake the puppet pieces.-6. Review rounds (below), then the user's viewing, then registering the episode.--## The script comes first--Write the script and a storyboard table (`books/<book>/storyboard.md`: scene, shot, what we see, who says what) and show them to the user before building anything. Changing a story on paper is cheap; once every shot is animated it is expensive, and almost every real failure in these books was a story failure that no amount of animation fixed.--What made the difference, from the books:--- **Set up everything the punchline needs.** The first cut of *Breakfast in the Bathroom* had Bo ask "Wanna go eat breakfast… in the bathroom?" out of nowhere; viewers took it literally. It became a joke once the film first showed his two everyday questions, "Breakfast?" every morning at the stall and "Bathroom?" after every class, and then the morning he overslept and came in starving.-- **Show the motive before the line.** Bo's stomach growls; a bun appears in a thought bubble; he glances at the door and a toilet appears beside it; the two bubbles shove each other and merge. Only then does he speak. The audience is ahead of him, which is where comedy happens.-- **Every event needs a cause the audience has seen.** In *Little Red Riding Hood* the first rescue had a woodcutter from nowhere, Grandma suddenly out of the wardrobe and the wolf flying out of the window as if Grandma had superpowers. The fix was a chain: the woodcutter chopping wood near the cottage earlier, a cut to Grandma's eye in the wardrobe crack during the questions, the cry for help, Grandma's umbrella on the wolf's head, the woodcutter blocking the door, the window the only way out, and outside, the window still broken.-- **The audience understands what the characters don't.** In *Do You Need a Bag?* the clerk speaks only Japanese and the customer only English: each line is spoken in its own language with subtitles, and a thought bubble shows the mishearing ("…REJI…?" turning into "VEGGIE?"), so the joke works for viewers who speak neither.-- **Keep the user's story.** Tighten the wording, add the small connecting moments a film needs, and list every addition for the user; don't swap their joke for a different one.--## Scenes, shots, cuts--One scene is one beat, with one joined audio clip ([sound.md](sound.md)); cuts inside a scene are timed to its clock. Plan shots the way a film does, because a fixed wide frame for a whole scene plays like a slideshow:--- a wide shot to say where we are, two-shots for conversations, a close-up for whoever speaks, closer and closer as tension rises (the three questions to "Grandma");-- reverse angles: whoever is in close-up has behind them what the other person sees (a separate camera on a matching set, not a zoom of the same one);-- an insert to make a detail readable (a coin on the counter, the clock, a face in a door crack);-- held silences: the beat where nobody speaks is often the joke. Blinks, eyes and a tiny head turn carry it.--Reviewers of the later episodes kept finding the same few things, all about what the viewer can read. Give every object the joke hangs on an insert of its own; the best episodes ran ten to fourteen shots a half minute. Keep whoever is being spoken to in the shot, since the listener's face is half of the line. Someone following stays far enough behind that the delay itself reads; people pass in front of or behind each other, never through. A face half cut by the frame edge, or a blink on the frame that carries the joke, reads as a mistake.--Everybody in the shot stays alive and stays there: extras blink and glance about in close-ups too (in an early cut the whole class vanished whenever someone spoke). Between places, cut or use a paper-theatre wipe; at the end, a title card.--## Review rounds--A first cut made in one pass looks like a first cut. What lifts an episode is watching it the way a director would, against the episodes the user already approved, and sending scenes back.--- **Director's view**: contact sheets of the whole episode and its cut sheet (`shot.py --cuts`) beside an approved one (a series' first episode: beside its storyboard). Look for story-level causes, not glitches: is every object the joke hangs on given its own shot, is the cause shown before the payoff, are the reactions framed so they read, is the shot density close to the approved episodes', does a silence stay silent? Write a restaging for each scene that needs one: which shots, from where, on which word.-- **Picture and sound**: frame by frame for faces cut by the edge, popping poses, puppets passing through each other; sound for lines cut short, effects out of step, music over a silence.-- Restage the scenes from those notes, then look again; two rounds usually settle it.--With subagents the reviewers run in parallel ([team.md](team.md#picture-books)); alone, do the same rounds yourself, one viewpoint at a time, writing each review down before changing anything.--## Delivering--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. A still is one frame of the episode saved as a 1400×788 WebP: `shot.py chNN --out books/<book>/review/stills sceneN:S --webp 1400 --name still-chNN --url http://localhost:8765/<book>/` writes it without the player's controls (beside a full-size PNG); copy the WebP to `site/<book>/img/`. The page's header shows `img/cover.webp`, a still too: the first episode's, or a frame the user picks, until the series has a picture of its own.diff --git a/.claude/skills/papermorph/references/team.md b/.claude/skills/papermorph/references/team.mddeleted file mode 100644index 6416f73..0000000--- a/.claude/skills/papermorph/references/team.md+++ /dev/null@@ -1,74 +0,0 @@-# Making a chapter with a team of models--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; for the pilot the coordinator is the main conversation, which shows the user each sheet and choice.--In the pilot, the narration and first beats made at intake (by the main conversation itself, before the models are agreed) are where steps 2 and 3 start, not something to redo. The picture worker stops when the storyboard sheet is ready and replies with it; the coordinator shows the sheet to the user, then continues the same worker with the user's changes to add motion. 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.--Wherever a step below names the previous or approved chapter as its model, a new book's first chapter (or a series' first episode) has none yet: use what the user agreed at intake (the pilot frames or sheet, the storyboard, `style.json`), the Skill's templates and the books on the shelf. The first chapter the user approves becomes the model from then on.--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.--Each step runs on the model the user chose for it (`models` in `style.json`, agreed at intake: [intake.md](intake.md#5-models)). The defaults below are named by strength: **small** (fast and cheap), **middle**, **strong** (the most capable); where `models` is silent, use them and say which model you picked.--## 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. After the pilot a fresh session is the best coordinator, starting from SKILL.md, this file and `style.json`: 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 (the first from `assets/templates/e2e.py`), 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`, chapter counts on the cover, `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 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--The same shape, split by scene instead of by step. The **strong** coordinator writes the script with the user and builds what every scene shares: cast, sets and their painting, the episode's helpers, the voices and the joined audio with its word times (`join.py --words`). Then it writes one brief for all scene workers:--- the story in a paragraph, and the user's words that set the bar;-- the episode kit's API, to read and not edit: a scene that needs more from the kit asks the coordinator, so every scene gets the fix;-- each scene's `pre`, its holes and the word times to cut on;-- continuity: who stands where, facing whom, in the first and last frame of every scene, so the cuts match;-- where things are: each set's places for puppets and props, its camera ranges, what comes into view on each pan. A painted set lands some way off its sketch (a bench seat about 30 px), so measure the places on frames of the painted set (`shot.py … --clean` gives the stage alone) and check the table on frames of every set before sending the brief out (a puppet at each place, the camera at each end of its range): in one episode a table written from the sketches put an ear off frame, feet below the ground and a tree trunk hiding the wrong side, and five workers built on it;-- the style, the effects available, how to look at one's own work, and the reply (the shots with their times, the first and last frame, what each check showed).--One **middle** worker per scene, in parallel, writes only its own `sceneN.js`; a **small** worker synthesizes the sound effects from recipes. Before replying, a scene worker runs and reports on these, each with the book's `--url` (the screenshot scripts run with reduced motion, so the workers' browsers can run at once): a strip of its scene, with time ranges and `@o@c` for walks and hands ([review.md](review.md#watch-it-in-motion)); full-size `shot.py` frames of its close-ups and of each moment a hand arrives; `shot.py --cuts sceneN` for its cuts in and out; `playlog.py --from sceneN --to sceneN`, since it cannot listen: is each effect on the frame it belongs to, each line on a moving mouth; and `still.py chNN sceneN`, saying which still stretches are meant. A brief that only asked them to look was skipped by all five workers of one episode; named commands and a reply that reports what they showed get run.--Review comes in rounds ([stories.md](stories.md#review-rounds) says what to look for):--- **Who**: four report-only reviewers watch the episode against the approved ones (a series' first: its storyboard and brief): a director (**strong**) for story, comedy, staging and shots; two picture reviewers (**middle**) splitting the scenes; one (**middle**) for sound and runtime.-- **Reports**: each ranked: scene, beat-clock time, what is wrong as a viewer sees it, a concrete fix. Earlier good reports serve as examples.-- **Merging**: the coordinator turns the reports into one rework list, taking the director's side where reviewers disagree, fixes the kit itself and sends scenes back to their workers.-- **Closing**: the next round starts by checking which findings were fixed; a last read-only pass counts them as fixed, partly fixed, not fixed or worse. Two or three rounds made the best episodes. The rounds come before the user watches, and what the user says then still decides.--A fresh session as coordinator matters even more here: contact sheets are large, and a long conversation rereads them at every step. An episode made in one night from a bedtime telling, before the review rounds existed, took about 22 million tokens, most of them the coordinator rereading its own context.--## Documentaries--The same shape as a picture book, split by part of the film (a turn of the argument, often one music track) instead of by scene. The **strong** coordinator researches and writes the script and storyboard with the user, then builds what every part shares: the voice and `timings.js`, the music, and the film's own recurring pieces at the end of `film.js`. A **middle** worker finds and treats the pictures from the storyboard (`commons.py`, `prep.py`, and `trace.py` or `frames.py` where the storyboard asks), recording each source.--One **middle** worker per part then builds its beats, given the storyboard rows, the marks to land on, the kit's API (to read, not to edit), the first and last frame of the parts beside it, and how to look at its own frames ([documentary.md](documentary.md#building-the-beats)); it replies with contact sheets of its beats and what they showed. The director pass ([documentary.md](documentary.md#review-rounds)) is **strong** and report-only; the coordinator merges its findings and sends parts back to their workers.--## Shorts--An episode is short enough that the **strong** coordinator writes the script and the shot-by-shot storyboard with the user and builds what the beats share: the voice and `timings.js` at one level, the music, and the series' own pieces in the second lib file. A **middle** worker makes or finds the pictures from the storyboard and records each prompt or source and its cost. One **middle** worker builds the beats (two, splitting the episode at a turn, when it is long), given the script, the marks, the kit's API to read and not edit, the safe area, and how to look at its frames: `strip.py` sheets of every beat and the first frame upright with `shot.py --clean` ([shorts.md](shorts.md#the-order-of-work)). The director pass is **strong** and report-only, against an approved episode: a first round on the sheets, then one on the exported MP4, the round that finds most ([documentary.md](documentary.md#review-rounds)). Check what a director measured before sending it back as work, and after the round-2 fixes take a quick look yourself at the new MP4's frames: in *The Pandemic*'s shorts that look still found a wrong date and a dead frame.--## Workers in parallel--Several episodes or parts made at once each get their own git worktree, branch and preview port (one server per worker, serving its own worktree's `site/`, and that port in every `--url`). What trips them:--- `books/` and `content/` are git-ignored, so a worktree has neither. `lint.py` finds them in the main checkout by itself; for everything else, give the brief's paths into them absolute, and no worker creates them in its worktree.-- A shared file every worker appends to (one `img/SOURCES.md` for six episodes) conflicts at every merge. Give each worker its own (sources per episode, sizes per episode with `prep.py --art chNN-art.js`), joined once after the merge, and keep the shared files read-only for the workers.-- The brief is the only rule book: one sentence each for the file names and the shared files, the same in the common brief and in each worker's go. One run said `img/chNN-*` in one place and `img/epN-*` in another, "do not edit SOURCES.md" and "add your block at the end".-- Workers that share one paid balance make their pictures before their voice: `paint.py` stops while an OpenRouter balance is under $1.00, and whoever voices first can lock the others out of pictures.-- Under load the machine is measured, not the page: with six workers exporting, a 16.7 ms beat read 48 to 109 ms in Firefox. `perf.py` prints the load average and warns above the core count, and `--ref CH:BEAT[@T]` times a known moment in the same run to read a number against; a loudness or timing that one worker or director reports under load is worth one more measurement before anyone acts on it. The frame time that decides goes on a quiet machine.diff --git a/.claude/skills/papermorph/scripts/new_book.py b/.claude/skills/papermorph/scripts/new_book.pynew file mode 100644index 0000000..9a64555--- /dev/null+++ b/.claude/skills/papermorph/scripts/new_book.py@@ -0,0 +1,104 @@+#!/usr/bin/env python3+"""Start a book folder: the engine, the kit's files and the working folders, for one kind of book.++ python3 new_book.py lesson history # a textbook: cover and contents, ch01 from the lesson template+ python3 new_book.py picture jokes # a picture book: series page, paper kit, scene1, sets.js+ python3 new_book.py documentary film # a documentary: film.js kit, series page for the credits+ python3 new_book.py shorts short --maps # upright shorts, here with the map kit (documentaries take --maps too)+ python3 new_book.py lesson stats --chapter 9 --lang ja --root ~/work++Run it from the folder that holds site/, books/, content/ and tools/ (or pass --root). It refuses a book that+already has a site/<book>/ folder, so it never overwrites work; resume an existing book from its own files.+The engine comes from engine.py (the repository's engine/ when at hand, else the latest compatible release).+It copies and creates files only; the voice, effects and baking steps it prints come next.+"""+import argparse, shutil, subprocess, sys+from pathlib import Path++HERE = Path(__file__).resolve().parent+T = HERE.parent / 'assets' / 'templates'+PB, DK, SK, MK = T / 'picture-book', T / 'documentary', T / 'shorts', T / 'maps'+++def copy(src: Path, dst: Path):+ dst.parent.mkdir(parents=True, exist_ok=True)+ if src.is_dir():+ shutil.copytree(src, dst, dirs_exist_ok=True)+ else:+ shutil.copy2(src, dst)+++def main():+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument('kind', choices=['lesson', 'picture', 'documentary', 'shorts'])+ ap.add_argument('book', help='the book slug, e.g. history')+ ap.add_argument('--chapter', type=int, default=1, help='the pilot chapter number (default 1)')+ ap.add_argument('--lang', default='en', help="the narration language code (default en); the template's text stays English until translated")+ ap.add_argument('--maps', action='store_true', help='add the map kit (documentaries and shorts)')+ ap.add_argument('--root', default='.', help='folder holding site/, books/, content/, tools/ (default .)')+ a = ap.parse_args()++ root = Path(a.root).expanduser().resolve()+ ch = f'ch{a.chapter:02d}'+ site, work, content = root / 'site' / a.book, root / 'books' / a.book, root / 'content' / a.book / ch+ if site.exists():+ sys.exit(f'{site} exists: resume from its own files, or choose another slug')+ if a.maps and a.kind not in ('documentary', 'shorts'):+ sys.exit('--maps is for documentaries and shorts')++ for d in (site / 'lib', site / 'img', site / ch, content, root / 'tools' / a.book):+ d.mkdir(parents=True, exist_ok=True)+ # engine.py first: it refuses a lib/ that already holds files but no engine+ subprocess.run([sys.executable, str(HERE / 'engine.py'), str(site)], check=True)+ narration = content / f'narration.{a.lang}.json'++ if a.kind == 'lesson':+ for d in ('chapters', 'images/inbox'):+ (work / d).mkdir(parents=True, exist_ok=True)+ copy(T / 'book.html', site / 'index.html')+ copy(T / 'unit-art.js', site / 'unit-art.js')+ copy(T / 'chapter.html', site / ch / 'index.html')+ copy(T / 'narration.en.json', narration)+ elif a.kind == 'picture':+ (site / 'img' / 'puppets').mkdir(parents=True, exist_ok=True)+ (work / 'art').mkdir(parents=True, exist_ok=True)+ copy(PB / 'series.html', site / 'index.html')+ for f in (PB / 'lib').glob('*.js'):+ copy(f, site / 'lib' / f.name)+ copy(PB / 'chapter.html', site / ch / 'index.html')+ copy(PB / 'scene1.js', site / ch / 'scene1.js')+ copy(PB / 'sets.js', work / 'art' / 'sets.js')+ copy(PB / 'painted.json', work / 'art' / 'painted.json')+ copy(PB / 'narration.en.json', narration)+ (site / 'img' / 'puppets' / 'baked.js').write_text('window.BAKED = {};\n') # until bake_puppets.py runs+ else:+ (work / 'art' / ('found' if a.kind == 'documentary' else '')).mkdir(parents=True, exist_ok=True)+ kit = DK if a.kind == 'documentary' else SK+ copy(kit / 'lib', site / 'lib') # over engine.py's lib/, its book.css replacing the default+ if a.kind == 'shorts':+ copy(DK / 'lib' / 'fonts.css', site / 'lib' / 'fonts.css')+ copy(DK / 'lib' / 'fonts', site / 'lib' / 'fonts')+ (site / ch / 'audio' / 'sfx').mkdir(parents=True, exist_ok=True)+ else:+ copy(PB / 'series.html', site / 'index.html') # a single film is a series of one+ copy(kit / 'chapter.html', site / ch / 'index.html')+ copy(kit / 'narration.en.json', narration)+ (site / 'img' / 'art.js').write_text('window.ART = {};\n') # prep.py fills it+ if a.maps:+ for f in (MK / 'lib').glob('*.js'):+ copy(f, site / 'lib' / f.name)++ S, A = HERE, site / ch / 'audio' / a.lang+ print(f'\n{a.kind} book started: {site.relative_to(root)}/ (pilot {ch}); next:')+ print(f' uv run --with edge-tts python3 {S}/tts.py {narration.relative_to(root)} {A.relative_to(root)}')+ if a.kind == 'picture':+ print(f' then level.py, mouths.py, join.py and sfx.py in tools/{a.book}/audio.sh; bake_sets.py, scenes, bake_puppets.py')+ if a.kind == 'shorts':+ print(f' uv run --with numpy python3 {S}/sfx.py {(site / ch / "audio" / "sfx").relative_to(root)} whoosh bang tick thud')+ if a.maps:+ print(f' uv run --with pillow python3 {S}/geo.py {(site / "img").relative_to(root)} --globe {(site / "lib").relative_to(root)}')+ print(f' python3 {S}/serve.py 8765 site # then open http://localhost:8765/{a.book}/{ch}/')+++if __name__ == '__main__':+ main()diff --git a/README.md b/README.mdindex ca71de3..8d1822a 100644--- a/README.md+++ b/README.md@@ -64,7 +64,7 @@ You need [uv](https://docs.astral.sh/uv/), ffmpeg, and Playwright's browsers (`u**Documentaries:** the source becomes an argument, a script and a storyboard → public-domain pictures are found, their licences recorded, and treated to one look → the narration is voiced and music laid under it → the beats are built in step with the words → a director pass checks every beat against the narration.-Large chapters can be made by a team of subagents, each step on the model that suits it ([team.md](.claude/skills/papermorph/references/team.md)).+Large chapters can be made by a team of subagents, each step on the model that suits it ([core/team.md](.claude/skills/papermorph/references/core/team.md)).## The player@@ -90,7 +90,7 @@ uv run --with playwright --with numpy .claude/skills/papermorph/scripts/export.pFrames are rendered from the lesson clock, so the video matches the page exactly; quizzes stay in the interactive version, and the video ends by pointing there.-For courses, a book can also be packaged for an LMS as SCORM 1.2 or 2004 (`scripts/scorm.py`), and a book can opt in to verified citation links and reviewed question banks ([authoring.md](.claude/skills/papermorph/references/authoring.md)). None of this is on by default.+For courses, a book can also be packaged for an LMS as SCORM 1.2 or 2004 (`scripts/scorm.py`), and a book can opt in to verified citation links and reviewed question banks ([courses.md](.claude/skills/papermorph/references/lessons/courses.md)). None of this is on by default.## Models and cost