Papermorph

Papermorph

Papermorph makes four kinds of book on one machine:

• 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.

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.

Which path

Every path shares site.md (the book folder, cover or series page, preview, video export), engine.md (the player and drawing API), team.md (making chapters with subagents) and the models step of intake.md. Read only the reference the current step needs.

Project layout

Copy code
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
site/<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

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; 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), a short conversation: find the PDF with the user (a story goes to 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 before showing the user any frames; build agreed shared components once into the book's library (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. 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).

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). 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.
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. 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 whenever books/<book>/style.json does not exist yet; agree the models (intake.md) and write style.json. Then follow the order of work: the script and storyboard shown to the user before anything is built, the book folder (site.md), sound, sets, scenes, 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 whenever books/<book>/style.json does not exist yet. Then follow the order of work: research, the script and storyboard shown to the user, the folder from assets/templates/documentary/ (site.md), pictures found and treated, voice, music, the beats, 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).

Shorts

Start with the questions in shorts.md 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). Then follow 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.

Scripts

All in SKILL/scripts/; each prints its usage with --help (run it with the uv run --with … its docstring names).

silence.py, ledger.py 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). 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.