Skip to content

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

refactor(engine): move the engine out of the Skill into engine/

yzr78ec99e8c91c
diff --git a/.claude/skills/papermorph/scripts/engine.py b/.claude/skills/papermorph/scripts/engine.py
new file mode 100644
index 0000000..f3658fa
--- /dev/null
+++ b/.claude/skills/papermorph/scripts/engine.py
@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Copy the Papermorph engine into books, or check that their copies match.
+
+ python3 engine.py site/history # one book
+ python3 engine.py site # every book in site/ (each folder with lib/engine.js)
+ python3 engine.py site --check # report copies that differ; exit status 1 if any
+ python3 engine.py site --from ../my-engine # a local engine folder (a fork, or one being fixed)
+ python3 engine.py site --from you/fork@v2 # engine/ of a GitHub repo at a tag, branch or commit
+
+The engine is not part of this skill: it is the engine/ folder of a repository, versioned by tags, and anyone may
+fork it. Without --from, ./engine is used when it exists (a checkout of that repository), otherwise DEFAULT.
+Each book keeps a full copy in lib/, so it runs on its own; fix the engine at its source and sync, never edit the
+copies. lib/book.css holds the book's own settings and overrides; it is created from the default and never
+overwritten.
+"""
+import argparse, filecmp, io, shutil, sys, tarfile, tempfile, urllib.request
+from pathlib import Path
+
+DEFAULT = 'DozenTwelve/Papermorph@main'
+OWN = 'book.css'
+
+
+def fetch(spec: str) -> Path:
+ repo, _, ref = spec.partition('@')
+ url = f'https://codeload.github.com/{repo}/tar.gz/{ref or "main"}'
+ try:
+ data = urllib.request.urlopen(url, timeout=60).read()
+ except OSError as e:
+ sys.exit(f'cannot download {url}: {e}')
+ out = Path(tempfile.mkdtemp(prefix='papermorph-engine-'))
+ with tarfile.open(fileobj=io.BytesIO(data)) as tar:
+ for m in tar.getmembers():
+ parts = m.name.split('/')
+ if m.isfile() and len(parts) == 3 and parts[1] == 'engine': # <repo>-<ref>/engine/<file>
+ (out / parts[2]).write_bytes(tar.extractfile(m).read())
+ if not (out / 'engine.js').exists():
+ sys.exit(f'{spec} has no engine/engine.js')
+ return out
+
+
+def source(spec):
+ if spec is None:
+ spec = 'engine' if Path('engine/engine.js').exists() else DEFAULT
+ path = Path(spec)
+ if path.is_dir():
+ if not (path / 'engine.js').exists():
+ sys.exit(f'{path} has no engine.js')
+ return path
+ return fetch(spec)
+
+
+def books(target: Path):
+ if (target / 'lib' / 'engine.js').exists():
+ return [target]
+ found = sorted(p.parent.parent for p in target.glob('*/lib/engine.js'))
+ if not found and (target / 'lib').is_dir(): # e.g. site/ with the bookshelf's lib/, before any book exists
+ sys.exit(f'{target}/lib has no engine.js and no book folder below it has one: pass the book folder itself')
+ return found or [target] # or a new book
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument('target', type=Path, help='a book folder, or a folder of books')
+ ap.add_argument('--from', dest='src', metavar='DIR|OWNER/REPO@REF', help=f'engine source (default ./engine, else {DEFAULT})')
+ ap.add_argument('--check', action='store_true', help='only report differing copies')
+ a = ap.parse_args()
+ engine = source(a.src)
+ shared = sorted(p for p in engine.iterdir() if p.suffix in ('.js', '.css') and p.name != OWN)
+ stale = []
+ for book in books(a.target):
+ lib = book / 'lib'
+ for src in shared:
+ dst = lib / src.name
+ if dst.exists() and filecmp.cmp(src, dst, shallow=False):
+ continue
+ stale.append(dst)
+ if not a.check:
+ lib.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(src, dst)
+ if not (lib / OWN).exists():
+ stale.append(lib / OWN)
+ if not a.check:
+ shutil.copyfile(engine / OWN, lib / OWN)
+ verb = 'differs' if a.check else 'updated'
+ for p in stale:
+ print(f'{verb}: {p}')
+ if not stale:
+ print('all engine copies match' if a.check else 'nothing to update')
+ sys.exit(1 if a.check and stale else 0)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/.claude/skills/papermorph/scripts/sync_engine.py b/.claude/skills/papermorph/scripts/sync_engine.py
deleted file mode 100644
index c50e036..0000000
--- a/.claude/skills/papermorph/scripts/sync_engine.py
+++ /dev/null
@@ -1,58 +0,0 @@
-#!/usr/bin/env python3
-"""Copy the skill's engine into books, or check that their copies match.
-
- python3 sync_engine.py site/history # one book
- python3 sync_engine.py site # every book in site/ (each folder with lib/engine.js)
- python3 sync_engine.py site --check # report copies that differ; exit status 1 if any
-
-Each book keeps a full copy of the engine in lib/, so it runs on its own. The copies are not edited by hand:
-change assets/engine/ and sync. lib/book.css holds the book's own settings and overrides; it is created from
-the default when missing and never overwritten.
-"""
-import argparse, filecmp, shutil, sys
-from pathlib import Path
-
-ENGINE = Path(__file__).resolve().parent.parent / 'assets' / 'engine'
-OWN = 'book.css'
-
-
-def books(target: Path):
- if (target / 'lib' / 'engine.js').exists():
- return [target]
- found = sorted(p.parent.parent for p in target.glob('*/lib/engine.js'))
- if not found and (target / 'lib').is_dir(): # e.g. site/ with the bookshelf's lib/, before any book exists
- sys.exit(f'{target}/lib has no engine.js and no book folder below it has one: pass the book folder itself')
- return found or [target] # or a new book
-
-
-def main():
- ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
- ap.add_argument('target', type=Path, help='a book folder, or a folder of books')
- ap.add_argument('--check', action='store_true', help='only report differing copies')
- a = ap.parse_args()
- shared = sorted(p for p in ENGINE.iterdir() if p.is_file() and p.name != OWN and not p.name.startswith('.'))
- stale = []
- for book in books(a.target):
- lib = book / 'lib'
- for src in shared:
- dst = lib / src.name
- if dst.exists() and filecmp.cmp(src, dst, shallow=False):
- continue
- stale.append(dst)
- if not a.check:
- lib.mkdir(parents=True, exist_ok=True)
- shutil.copyfile(src, dst)
- if not (lib / OWN).exists():
- stale.append(lib / OWN)
- if not a.check:
- shutil.copyfile(ENGINE / OWN, lib / OWN)
- verb = 'differs' if a.check else 'updated'
- for p in stale:
- print(f'{verb}: {p}')
- if not stale:
- print('all engine copies match' if a.check else 'nothing to update')
- sys.exit(1 if a.check and stale else 0)
-
-
-if __name__ == '__main__':
- main()
diff --git a/.claude/skills/papermorph/assets/engine/book.css b/engine/book.css
similarity index 100%
rename from .claude/skills/papermorph/assets/engine/book.css
rename to engine/book.css
diff --git a/.claude/skills/papermorph/scripts/check_volume.py b/engine/check_volume.py
similarity index 96%
rename from .claude/skills/papermorph/scripts/check_volume.py
rename to engine/check_volume.py
index b4cf5a2..d8992bd 100644
--- a/.claude/skills/papermorph/scripts/check_volume.py
+++ b/engine/check_volume.py
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""Real-audio volume regression for both books and the Skill chapter template.
-Serve site on 8767, then: uv run --with playwright .claude/skills/papermorph/scripts/check_volume.py
+Serve site on 8767, then: uv run --with playwright engine/check_volume.py
BASE_URL overrides http://127.0.0.1:8767. No files are generated.
"""
import asyncio
@@ -12,8 +12,9 @@ from urllib.parse import urlparse
from playwright.async_api import async_playwright
-SKILL = Path(__file__).resolve().parents[1]
-SITE = SKILL.parents[2] / "site"
+ENGINE = Path(__file__).resolve().parent
+SKILL = ENGINE.parent / ".claude/skills/papermorph"
+SITE = ENGINE.parent / "site"
BASE = os.environ.get("BASE_URL", "http://127.0.0.1:8767").rstrip("/")
@@ -22,7 +23,7 @@ async def template(route):
if name == "ch01/":
await route.fulfill(path=SKILL / "assets/templates/chapter.html")
elif name.startswith("lib/"):
- await route.fulfill(path=SKILL / "assets/engine" / Path(name).name)
+ await route.fulfill(path=ENGINE / Path(name).name)
elif name.endswith("timings.js"):
timing = {"dur": 30, "marks": {"sub": 1, "note": 2, "w1": 3, "w2": 4}, "cues": []}
await route.fulfill(content_type="text/javascript", body="const TIMINGS = " + json.dumps(
diff --git a/.claude/skills/papermorph/assets/engine/engine.css b/engine/engine.css
similarity index 100%
rename from .claude/skills/papermorph/assets/engine/engine.css
rename to engine/engine.css
diff --git a/.claude/skills/papermorph/assets/engine/engine.js b/engine/engine.js
similarity index 100%
rename from .claude/skills/papermorph/assets/engine/engine.js
rename to engine/engine.js
diff --git a/.claude/skills/papermorph/assets/engine/volume.css b/engine/volume.css
similarity index 100%
rename from .claude/skills/papermorph/assets/engine/volume.css
rename to engine/volume.css
diff --git a/.claude/skills/papermorph/assets/engine/volume.js b/engine/volume.js
similarity index 100%
rename from .claude/skills/papermorph/assets/engine/volume.js
rename to engine/volume.js