Skip to content

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

Merge PR #11: verified citation links and item-bank choice questions

yzrc27249fa27a0
diff --cc .claude/skills/papermorph/SKILL.md
index d10b663,b1c022f..5b90da4
--- a/.claude/skills/papermorph/SKILL.md
+++ b/.claude/skills/papermorph/SKILL.md
@@@ -17,8 -19,6 +19,8 @@@ Follow the pipeline forward, entering a
books/<book>/
book.pdf, sections.json source and page map (private)
pages/chNN/text.md, *.png extracted reference material (private)
- refs.json cited works with verified DOI/ISBN/URL (scripts/refs.py)
- items/chNN.items.json optional choice-question bank per chapter (scripts/items.py)
++ refs.json optional: cited works with verified DOI/ISBN/URL (scripts/refs.py)
++ items/chNN.items.json optional: a reviewed choice-question bank per chapter (scripts/items.py)
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
@@@ -28,16 -28,16 +30,18 @@@ content/<book>/chNN/ narratio
tools/<book>/ tests and evidence scripts
site/<book>/ the static book (only this is delivered)
index.html, unit-art.js cover + contents, unit sketches
- refs.js the cited works, built by scripts/refs.py
++ refs.js optional: the cited works, built by scripts/refs.py
lib/engine.*, volume.*, the engine (player, cover/contents, unit headers), copied into the book by
contents.*, units.* scripts/engine.py
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
+ chNN/items.js built choice questions (scripts/items.py), when the chapter has a bank
```
- `SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Existing books keep their paths. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`) network access to api.crossref.org and openlibrary.org for references, and Playwright browsers (`uv run --with playwright playwright install chromium firefox`). Preview: `python3 SKILL/scripts/serve.py 8765 site` (no browser caching).
+ 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/`) and `img/` the baked sets, props and puppet pieces; each episode `chNN/` has one script per scene and `audio/<lang>/`, `audio/sfx/`, `audio/bgm/`.
+
-`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Existing books keep their paths. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`) 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).
++`SKILL` means this skill's absolute folder; `<book>` is the book slug, `<lang>` its primary language code. Existing books keep their paths. Needs: `uv`, `ffmpeg`/`ffprobe`, Edge TTS network access (or Kokoro, local: `uv run --python 3.12 --with kokoro`), api.crossref.org and openlibrary.org for a book with citations, 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).
## Pipeline
@@@ -51,10 -51,10 +55,10 @@@ Start with intake whenever `books/<book
## 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. When the chapter names other works (an author–year, a study, a book), add them to `refs.json` and run `refs.py lookup`, `verify` and `build` ([authoring.md](references/authoring.md#citations)).
-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.
++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. In a book that cites its sources (an option for academic books, chosen at intake), add the works the chapter names to `refs.json` and run `refs.py lookup`, `verify` and `build` ([authoring.md](references/authoring.md#citations)).
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).
+4. **Motion**: add the motion, the camera and the questions (choice questions may come from an item bank via `mcq()`, [authoring.md](references/authoring.md#choice-questions-from-an-item-bank)); 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.
diff --cc .claude/skills/papermorph/assets/templates/book.html
index e59a7b5,82a6e0d..a3be85b
--- a/.claude/skills/papermorph/assets/templates/book.html
+++ b/.claude/skills/papermorph/assets/templates/book.html
@@@ -11,7 -11,6 +11,7 @@@
<script src="lib/units.js"></script>
<script src="lib/contents.js"></script>
<script src="unit-art.js"></script>
- <script src="refs.js"></script><!-- the book's cited works, built by the skill's scripts/refs.py -->
++<!-- <script src="refs.js"></script> a book that cites works: its reference list, built by the skill's scripts/refs.py -->
<link rel="expect" href="#ch01" blocking="render">
<!-- The book's own look, if it differs from the chalkboard: override the tokens of lib/contents.css here, e.g.
<style>
diff --cc .claude/skills/papermorph/assets/templates/chapter.html
index 0524bb2,2c859b6..7778b11
--- a/.claude/skills/papermorph/assets/templates/chapter.html
+++ b/.claude/skills/papermorph/assets/templates/chapter.html
@@@ -9,8 -9,6 +9,8 @@@
</head>
<body>
<script src="../lib/engine.js"></script>
- <script src="../refs.js"></script><!-- the book's sources for cite(); built by scripts/refs.py -->
++<!-- <script src="../refs.js"></script> a book that cites works: the sources for cite(); built by scripts/refs.py -->
+<!-- <script src="items.js"></script> choice questions for mcq(id); built by scripts/items.py from books/<book>/items/chNN.items.json -->
<script src="audio/en/timings.js"></script>
<script>
'use strict';
diff --cc .claude/skills/papermorph/references/authoring.md
index 9014482,da1abdb..ab21f61
--- a/.claude/skills/papermorph/references/authoring.md
+++ b/.claude/skills/papermorph/references/authoring.md
@@@ -86,15 -67,3 +86,15 @@@ The chapter loads `<script src="items.j
- 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.
+
+## Citations
+
- Every work named on screen (an author–year, a quoted study, a book title) can be a live link to that work. Links come from a verified list, never from memory.
++An option for books that name other works (an author–year, a quoted study, a book title), usually academic ones; offer it at intake, not by default. Each such work on screen can be a live link to it. Links come from a verified list, never from memory.
+
+1. **List.** Add each cited work to `books/<book>/refs.json`, taking authors, year and full title from the source book's own reference list (`pages/*/text.md`). The key is `surname-surname-year` (`scheper-hughes-lock-1987`); `cite` is the on-screen label (`python3 SKILL/scripts/refs.py --help` lists the entry fields).
+2. **Find.** `python3 SKILL/scripts/refs.py lookup books/<book>/refs.json --write`. It accepts a Crossref DOI only when the year, first author and title all match. For books without a DOI it takes the ISBN of the edition from the cited year (Open Library), which links to its WorldCat record. Decide each `NO CONFIDENT MATCH` by hand: pick the right candidate or a trusted academic page (`url`, e.g. PubMed, JSTOR, ERIC, a university repository). If none exists, keep the citation as plain text and note it in the chapter file.
+3. **Verify.** `python3 SKILL/scripts/refs.py verify books/<book>/refs.json --write` resolves every DOI or ISBN, checks it against the entry, fills in missing metadata and stamps `verified`. Fix every `FAIL`.
- 4. **Build.** `python3 SKILL/scripts/refs.py build books/<book>/refs.json site/<book>/refs.js`. Chapters and the contents page load it: the contents ends with a link to a separate References view that lists every work, and each chapter's finish card lists the sources that chapter cites.
++4. **Build.** `python3 SKILL/scripts/refs.py build books/<book>/refs.json site/<book>/refs.js`, and uncomment the `refs.js` line in `index.html` and each chapter: the contents ends with a link to a separate References view that lists every work, and each chapter's finish card lists the sources that chapter cites.
+5. **Draw.** `cite(p, key, { x, y, size, fill, anchor, weight, o: 0 })` draws the label as an underlined link and returns it, ready for `show()`/`tw()` like `T`; `str` overrides the label (e.g. `'(1987)'` after a name drawn separately). Text drawn with `T` or written in a card that matches a work's `cite` label (or one of its `match` strings) becomes a link by itself. Clicking a citation opens the source in a new tab and pauses the lesson; faded-out links take no clicks or Tab focus. A work discussed but not drawn goes in `CHAPTER.refs` so the finish card still lists it.
+
+Draw a citation next to the text it supports rather than inside a long sentence, so the link is a separate target of at least 24 px text height.
diff --cc .claude/skills/papermorph/references/intake.md
index a75c3f0,4a38f6c..4eb3fe7
--- a/.claude/skills/papermorph/references/intake.md
+++ b/.claude/skills/papermorph/references/intake.md
@@@ -42,6 -42,6 +42,8 @@@ When the user brings a story rather tha
**Custom**: ask what the description leaves open, using the closest tier's rounds and options.
++When the book cites other works (author–year citations, named studies), ask whether the works named on screen should link to their sources ([authoring.md](authoring.md#citations)); when its questions must be reviewed before release (a course book), offer an item bank ([authoring.md](authoring.md#choice-questions-from-an-item-bank)). Neither is on by default.
++
## 5. style.json
Start from [the template](../assets/templates/style.json). Blocks are grouped by ability, not by tier; a tier is just which blocks are present:
diff --cc .claude/skills/papermorph/references/site.md
index a19c584,38c0c5c..6e9bbd5
--- a/.claude/skills/papermorph/references/site.md
+++ b/.claude/skills/papermorph/references/site.md
@@@ -39,7 -57,6 +57,7 @@@ One page: no hash or `#book` shows the
- Edit the title, kicker, lede, the faint chalk phrases on the cover (a few formulas or lines from the book), and the `<title>`.
- The page's script calls `Contents.book({ start, units, hues })` (from the engine's `lib/contents.js`; the shared styles are `lib/contents.css`). `units`: `[unit title, [[chapter title, minutes], …]]`; chapters are numbered in order from `start` (`{ unit: 1, chapter: 1 }`; a book whose scope starts mid-way, e.g. at unit 3, chapter 9, keeps the original numbers). Add a chapter when its lesson is ready; also set the previous chapter's `CHAPTER.next = '../chNN/'`. An optional third entry `{ unit, chapter, sample: true }` renumbers a unit and marks it as a sample, left out of the chapter count. 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.
- - References: the page loads `refs.js`, and the contents ends with one link to the separate `#references` view, which lists every cited work linked to its DOI or catalogue record; a book without citations shows no link. Rebuild `refs.js` whenever `refs.json` changes ([authoring.md](authoring.md#citations)).
++- References (only a book that cites works): uncomment the `refs.js` line in `index.html` and in each chapter; the contents then ends with one link to the separate `#references` view, which lists every cited work linked to its DOI or catalogue record; a book without citations shows no link. Rebuild `refs.js` whenever `refs.json` changes ([authoring.md](authoring.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`)
@@@ -58,7 -75,7 +76,7 @@@ Serve the static output over HTTP for a
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 reference links open their works. Deliver `site/<book>/` with its HTML, scripts (including `refs.js`), 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.
-Open `http://localhost:8765/<book>/`. Confirm the cover opens the contents, ready chapter links load their lessons, and lessons return to the book's contents. 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.
++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