An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
ci: check the Skill's docs, the books and the scripts on every pull request
yzr2d20cdcc7c83
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.mdnew file mode 100644index 0000000..dba71e9--- /dev/null+++ b/.claude/CLAUDE.md@@ -0,0 +1 @@+@../AGENTS.mddiff --git a/.github/scripts/check_site.py b/.github/scripts/check_site.pynew file mode 100644index 0000000..884a201--- /dev/null+++ b/.github/scripts/check_site.py@@ -0,0 +1,66 @@+#!/usr/bin/env python3+"""Checks of the published books that need no private folders, network or browser. Run from the repository root:++ python3 .github/scripts/check_site.py++- every book's engine copy matches engine/ (engine.py --check), so no one edited a copy instead of the source;+- lint.py on every book (errors fail; narration is not checked, since content/ is not in the repository);+- node --check on every script: the .js files and each inline <script> of every page, so a syntax error that+ would stop a chapter is caught before it ships.++Needs Python 3 and Node. Exits 1 if any check fails.+"""+import re, subprocess, sys, tempfile+from pathlib import Path++ROOT = Path(__file__).resolve().parents[2]+SCRIPTS = ROOT / '.claude/skills/papermorph/scripts'+failed = []+++def run(label, cmd):+ r = subprocess.run(cmd, cwd=ROOT, capture_output=True, text=True)+ if r.returncode:+ failed.append(label)+ print(f'FAIL {label}\n{(r.stdout + r.stderr).strip()}\n')+ return r+++def node_check(path, label):+ r = subprocess.run(['node', '--check', str(path)], capture_output=True, text=True)+ if r.returncode:+ failed.append(label)+ print(f'FAIL {label}\n{r.stderr.strip()}\n')+++def main():+ run('engine copies', [sys.executable, str(SCRIPTS / 'engine.py'), 'site', '--check'])+ books = sorted(p.parent.parent for p in (ROOT / 'site').glob('*/lib/engine.js'))+ for book in books:+ run(f'lint {book.name}', [sys.executable, str(SCRIPTS / 'lint.py'), str(book.relative_to(ROOT))])++ tracked = subprocess.run(['git', 'ls-files', 'engine', 'site', '.claude/skills/papermorph/assets'],+ cwd=ROOT, capture_output=True, text=True, check=True).stdout.split()+ js = [f for f in tracked if f.endswith('.js') and 'vendor/' not in f and not f.endswith('mathjax.js')]+ pages = [f for f in tracked if f.endswith('.html')]+ for f in js:+ node_check(ROOT / f, f)+ inline = 0+ with tempfile.TemporaryDirectory() as tmp:+ for f in pages:+ html = (ROOT / f).read_text(errors='replace')+ for i, (attrs, body) in enumerate(re.findall(r'<script(\s[^>]*)?>(.*?)</script>', html, flags=re.S)):+ attrs = attrs or ''+ if 'src=' in attrs or not body.strip() or re.search(r'type=["\']?(?!text/javascript|module)', attrs):+ continue+ out = Path(tmp) / f'{len(failed)}-{inline}.{"mjs" if "module" in attrs else "js"}'+ out.write_text(body)+ node_check(out, f'{f} <script> #{i + 1}')+ inline += 1+ print(f'{len(books)} books linted, {len(js)} scripts and {inline} inline scripts checked; '+ f'{len(failed)} failed' + (': ' + ', '.join(failed) if failed else ''))+ sys.exit(1 if failed else 0)+++if __name__ == '__main__':+ main()diff --git a/.github/scripts/check_skill.py b/.github/scripts/check_skill.pynew file mode 100644index 0000000..cd76bec--- /dev/null+++ b/.github/scripts/check_skill.py@@ -0,0 +1,115 @@+#!/usr/bin/env python3+"""Check that the Papermorph Skill's docs agree with its files. Standard library only; run from the repository root:++ python3 .github/scripts/check_skill.py++- every relative link and #anchor in SKILL.md, references/ and the repository's own .md files resolves;+- SKILL.md links every reference file directly, so none is reachable only through another;+- every script in scripts/ is named in SKILL.md, and every script compiles;+- a flag written next to a script (`level.py --lufs -14`) appears in that script's source;+- a `scripts/x.py` or `assets/templates/...` path named in the docs exists.++Prints each problem with its file and exits 1 if there are any.+"""+import re, sys+from pathlib import Path++ROOT = Path(__file__).resolve().parents[2]+SKILL = ROOT / '.claude/skills/papermorph'+DOCS = [SKILL / 'SKILL.md', *sorted((SKILL / 'references').rglob('*.md'))]+REPO_DOCS = [p for p in (ROOT / 'README.md', ROOT / 'AGENTS.md', ROOT / 'engine/vendor/mathjax/README.md') if p.exists()]+problems = []+++def say(path, msg):+ problems.append(f'{path.relative_to(ROOT)}: {msg}')+++def slug(heading):+ h = re.sub(r'[`*_]', '', heading.strip().lower())+ return re.sub(r'[^\w\- ]', '', h).replace(' ', '-')+++def anchors(path):+ out, fence = set(), False+ for line in path.read_text().splitlines():+ if line.startswith('```'):+ fence = not fence+ elif not fence and (m := re.match(r'#{1,6} (.*)', line)):+ out.add(slug(m.group(1)))+ return out+++def without_fences(text):+ return re.sub(r'```.*?```', '', text, flags=re.S)+++def links():+ for doc in DOCS + REPO_DOCS:+ for target in re.findall(r'\]\(([^)\s]+)\)', without_fences(doc.read_text())):+ if re.match(r'[a-z]+:', target):+ continue+ path, _, frag = target.partition('#')+ dest = (doc.parent / path).resolve() if path else doc+ if not dest.exists():+ say(doc, f'link to a missing file: {target}')+ elif frag and dest.suffix == '.md' and frag not in anchors(dest):+ say(doc, f'link to a missing heading: {target}')+++def routing():+ text = (SKILL / 'SKILL.md').read_text()+ linked = {(SKILL / t.split('#')[0]).resolve() for t in re.findall(r'\]\((references/[^)#\s]+)', text)}+ for ref in DOCS[1:]:+ if ref.resolve() not in linked:+ say(ref, 'not linked from SKILL.md')+ for script in sorted((SKILL / 'scripts').glob('*.py')):+ if f'`{script.name}`' not in text:+ say(script, 'not named in SKILL.md')+ try:+ compile(script.read_text(), str(script), 'exec')+ except SyntaxError as e:+ say(script, f'does not compile: line {e.lineno}: {e.msg}')+++def code_spans(text):+ """Inline code spans, plus each line of a fenced block as one span."""+ spans = []+ for block in re.findall(r'```[^\n]*\n(.*?)```', text, flags=re.S):+ spans += block.splitlines()+ return spans + re.findall(r'`([^`\n]+)`', without_fences(text))+++def drift():+ for doc in DOCS:+ for span in code_spans(doc.read_text()):+ for p in re.findall(r'(?:^|[\s"]|SKILL/)(scripts/\w+\.py)', span):+ if not (SKILL / p).exists():+ say(doc, f'names a missing script: {p}')+ for p in re.findall(r'(assets/templates/[\w./*-]+)', span):+ if not list(SKILL.glob(p.rstrip('/.'))):+ say(doc, f'names a missing path: {p}')+ for name in re.findall(r'(\w+\.py)\b', span):+ src = SKILL / 'scripts' / name+ if not src.exists():+ continue+ code = src.read_text()+ # a flag right after this script's name and before the next script or pipe belongs to it+ tail = re.split(r'\b\w+\.py\b|\|', span.split(name, 1)[1])[0]+ for flag in re.findall(r'(?<![\w-])(--[a-z][\w-]*)', tail):+ if flag != '--help' and flag not in code:+ say(doc, f'{name} has no {flag}')+++def selftest():+ assert slug('Performance (Firefox)') == 'performance-firefox'+ assert slug('Cover and contents (`index.html`)') == 'cover-and-contents-indexhtml'+ assert slug('style.json') == 'stylejson'+ assert code_spans('a `x.py --y` b\n```sh\none\ntwo\n```') == ['one', 'two', 'x.py --y']+++if __name__ == '__main__':+ selftest()+ links(); routing(); drift()+ print('\n'.join(problems) or 'ok', f'\n{len(problems)} problems in {len(DOCS) + len(REPO_DOCS)} docs')+ sys.exit(1 if problems else 0)diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.ymlnew file mode 100644index 0000000..73c49c8--- /dev/null+++ b/.github/workflows/checks.yml@@ -0,0 +1,28 @@+name: Checks++on:+ pull_request:+ push:+ branches: [main]++permissions:+ contents: read++jobs:+ skill:+ runs-on: ubuntu-latest+ timeout-minutes: 5+ steps:+ - uses: actions/checkout@v4+ - name: Skill docs agree with its files+ run: python3 .github/scripts/check_skill.py+ - name: Python scripts (pyflakes errors, no unused-import noise)+ run: pipx run ruff check --select F,E9 --ignore F401 --output-format concise .claude/skills/papermorph/scripts .github engine++ site:+ runs-on: ubuntu-latest+ timeout-minutes: 10+ steps:+ - uses: actions/checkout@v4+ - name: Engine copies, lint, script syntax+ run: python3 .github/scripts/check_site.pydiff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 0000000..d641830--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,33 @@+# Working on Papermorph++Papermorph is a Claude Code Skill that turns a textbook PDF, a story or an argument into a narrated, animated web book: lessons, picture books, and films (documentaries and upright shorts). This file is for an agent changing the repository; the Skill's own instructions for making books are in `.claude/skills/papermorph/SKILL.md`.++## What lives where++- `.claude/skills/papermorph/`: the Skill. `SKILL.md` routes by tier and links every reference directly; `references/core/` holds what every tier shares (style, publish, sound, review, team, engine), `references/lessons/`, `references/picture-books/` and `references/films/` what is each tier's own; `scripts/` the tools; `assets/templates/` the kits a new book is copied from (`scripts/new_book.py`).+- `engine/`: the one source of the player and drawing engine. Change it here, then copy it into the books with `python3 .claude/skills/papermorph/scripts/engine.py site`; never edit a book's `lib/engine.*` copy. A book's own settings live in its `lib/book.css`, which the sync leaves alone.+- `site/`: the published books, static files only, with no build step or backend.+- `books/`, `content/` and `tools/` are the maintainers' private working folders and are not in the repository. Don't recreate them in a commit.+- Don't add a copyrighted book, its PDF, or lessons made from one.++## Changing the Skill++The Skill is read by models making books, so what it says has to be true and has to be found. These rules come from what went wrong before:++1. **The docs describe what the kits and scripts actually do.** Change the code and its docs in the same commit, and open a template before describing it. A doc once said a chapter page had map lines commented out that only another kit's page had, and an agent spent a step looking for them.+2. **Reference films and books are built with the kit the Skill ships.** When a reference needed something the kit lacks, move it into the kit, or the reference teaches a path no one else can follow.+3. **Tools say what they could not do.** A label pushed off frame, an unknown region name, a global that clashes with the engine: print it and name it. A silent skip looks like success to the agent running the tool.+4. **Shared files hold only what is shared.** `references/core/` is for every tier, and `references/films/films.md` for both documentaries and shorts. A sentence true of one tier or shape goes in that tier's file.+5. **Each step can get what it needs from the steps before it, and each target comes with the figure to reach it.** A length comes with a words-per-minute figure; a loudness comes with the level to set.++Write Skill guidance as intent, reasons and examples, and give the model ways to see its own output. Avoid lists of bans: they narrow what the model tries, and the owner has turned them down before. Keep each fact in one place and link to it.++## Checks++CI (`.github/workflows/checks.yml`) runs these on every pull request; run them before you push:++- `python3 .github/scripts/check_skill.py` checks links and anchors, that `SKILL.md` links every reference and names every script, that scripts compile, and that flags and paths named in the docs exist.+- `python3 .github/scripts/check_site.py` (needs Node) checks that every book's engine copy matches `engine/`, runs `lint.py` on every book, and runs `node --check` on every script, inline page scripts included.+- `pipx run ruff check --select F,E9 --ignore F401 .claude/skills/papermorph/scripts .github engine` catches undefined names and other pyflakes errors in the Python tools.+- After an engine or page change, serve the site (`python3 .claude/skills/papermorph/scripts/serve.py 8765 site`), play the chapters you touched in a browser, and run `python3 .claude/skills/papermorph/scripts/lint.py site/<book>` and the engine's own checks (`uv run --with playwright engine/check_i18n.py`, `engine/check_latex.py`; `engine/check_volume.py` with the site served on 8767).+- After a large change to the Skill, have a fresh agent make a short film with the Skill alone, and sort what it trips on under the rules above. If a problem fits none of them, a rule is missing.diff --git a/README.md b/README.mdindex 8d1822a..18a82df 100644--- a/README.md+++ b/README.md@@ -117,7 +117,7 @@ Ticked items are in the Skill today. The Skill currently goes as far as document## Contributing-Fixes to the Skill and the player are welcome. Please don't open pull requests that add a copyrighted book, its PDF, or lessons made from one.+Fixes to the Skill and the player are welcome. Please don't open pull requests that add a copyrighted book, its PDF, or lessons made from one. Agents and people changing the repository: start with [AGENTS.md](AGENTS.md).## Try the examples locally