An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
feat(skill): CHROME browser choice, OpenAI painting, key redaction (#15)
Yuya Shimboria595b4b3066d
diff --git a/.claude/skills/papermorph/SKILL.md b/.claude/skills/papermorph/SKILL.mdindex 3687595..b1c022f 100644--- a/.claude/skills/papermorph/SKILL.md+++ b/.claude/skills/papermorph/SKILL.md@@ -37,7 +37,7 @@ site/<book>/ the static book (only this is delivered)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`). 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`) 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).## Pipelinediff --git a/.claude/skills/papermorph/references/painting.md b/.claude/skills/papermorph/references/painting.mdindex 994e7af..e8e668b 100644--- a/.claude/skills/papermorph/references/painting.md+++ b/.claude/skills/papermorph/references/painting.md@@ -23,6 +23,7 @@ Money is the user's, so the user sets a ceiling and sees every cent:- `paint.py` takes quality `low` or `medium` only. Try low first: in these books low was often good enough for the final set (about $0.02 a picture; medium about $0.02–0.03; high cost five times as much and, once used in a film, looked the same).- Every picture is logged with its cost (`--ledger books/<book>/art/costs.tsv`); before a batch, say how many pictures and what they will cost; after it, report the real balance from the provider, not an estimate. OpenRouter refuses any image request when the balance is under one dollar.+- Without an OpenRouter account, `paint_openai.py` calls OpenAI's image API directly with the same arguments and ledger (key in `OPENAI_API_KEY`). OpenAI does not return a price, so its ledger lines are estimates: read the real spend from OpenAI's usage page.- After every batch, put the pictures on one contact sheet and open it for the user (Finder, the browser), even when working on your own: they like to see each stage.## Credits and licencesdiff --git a/.claude/skills/papermorph/scripts/bake_puppets.py b/.claude/skills/papermorph/scripts/bake_puppets.pyindex 20a64c6..49f5488 100644--- a/.claude/skills/papermorph/scripts/bake_puppets.py+++ b/.claude/skills/papermorph/scripts/bake_puppets.py@@ -16,6 +16,7 @@ every piece and then removes the files no chapter asked for. --url defaults to timport argparse, base64, io, json, pathlibfrom PIL import Imagefrom playwright.sync_api import sync_playwright+from browsers import exeREADY = """async () => {let n = -1; while (bakedJobs.size !== n) { n = bakedJobs.size; await Promise.all([...bakedJobs.values()]); await new Promise(r => setTimeout(r, 300)); }@@ -34,7 +35,12 @@ def main():got = {}with sync_playwright() as p:for kind in (p.chromium, p.firefox):- b = kind.launch(); pg = b.new_page(viewport={'width': 1600, 'height': 900})+ try:+ b = kind.launch(**exe()) if kind is p.chromium else kind.launch()+ except Exception as e: # Playwright's Firefox may not run on this system: the Chromium pieces still stand+ if kind is p.chromium: raise+ print(f'{kind.name} did not start, so Firefox bakes its own few pieces in the page:', str(e).splitlines()[0]); continue+ pg = b.new_page(viewport={'width': 1600, 'height': 900})for ch in sorted(d.name for d in site.glob('ch[0-9][0-9]')):pg.goto(f'{url}{ch}/?bake', timeout=600000)last = pg.evaluate('BEATS.length - 1')diff --git a/.claude/skills/papermorph/scripts/bake_sets.py b/.claude/skills/papermorph/scripts/bake_sets.pyindex 63b78bc..f493494 100644--- a/.claude/skills/papermorph/scripts/bake_sets.py+++ b/.claude/skills/papermorph/scripts/bake_sets.py@@ -17,6 +17,7 @@ The sketches are a finished look on their own (free) and the composition referenimport asyncio, base64, io, json, pathlib, sysfrom PIL import Imagefrom playwright.async_api import async_playwright+from browsers import exeJS = """async ([name, i, soft]) => {const L = SETS[name]()[i], [x, y, w, h] = L.box, s = L.scale || 1;@@ -33,7 +34,7 @@ async def main(sets_js, site, only, ref):out = pathlib.Path(site) / 'img/sets'; old = out / 'sets.js'man = json.loads(old.read_text().split('=', 1)[1].rstrip().rstrip(';')) if old.exists() else {}async with async_playwright() as p:- b = await p.chromium.launch(); pg = await b.new_page()+ b = await p.chromium.launch(**exe()); pg = await b.new_page()await pg.add_script_tag(path=str(pathlib.Path(sets_js).resolve()))known = await pg.evaluate('Object.keys(SETS)')if set(only) - set(known): sys.exit(f'not in {sets_js}: {sorted(set(only) - set(known))}')diff --git a/.claude/skills/papermorph/scripts/browsers.py b/.claude/skills/papermorph/scripts/browsers.pynew file mode 100644index 0000000..3eac141--- /dev/null+++ b/.claude/skills/papermorph/scripts/browsers.py@@ -0,0 +1,19 @@+"""Which Chromium the scripts launch: Playwright's own, or the one $CHROME names.++ from browsers import exe+ b = await p.chromium.launch(**exe()) # or sync_api++Set CHROME to an installed Chrome, Chromium, Brave or Edge where Playwright's own build does not run (some Linux+distributions), e.g. CHROME=/snap/bin/brave. Such a browser also gets the flags a headless page needs there: no+sandbox (containers), a shared-memory fallback, and sound without a click (the books play audio). Unset, nothing+changes, so a review on one machine matches another's.+"""+import os++ARGS = ["--no-sandbox", "--disable-dev-shm-usage", "--autoplay-policy=no-user-gesture-required"]+++def exe():+ """kwargs for p.chromium.launch(...): $CHROME with its flags, or {} for Playwright's bundled browser."""+ path = os.environ.get("CHROME")+ return {"executable_path": path, "args": ARGS} if path else {}diff --git a/.claude/skills/papermorph/scripts/check_blank.py b/.claude/skills/papermorph/scripts/check_blank.pyindex 06d3929..27cb429 100644--- a/.claude/skills/papermorph/scripts/check_blank.py+++ b/.claude/skills/papermorph/scripts/check_blank.py@@ -14,6 +14,7 @@ Otherwise it prints one line saying none were found. Exit status 1 when somethinimport argparse, asyncio, os, sysfrom pathlib import Pathfrom playwright.async_api import async_playwright+from browsers import exeLIMIT = float(os.environ.get("LIMIT", "1.0"))PROBE = r"""@@ -41,7 +42,7 @@ PROBE = r"""async def main(book: Path, chapters, url):found = []async with async_playwright() as p:- browser = await p.chromium.launch()+ browser = await p.chromium.launch(**exe())pg = await browser.new_page(viewport={"width": 1600, "height": 960})for ch in chapters:await pg.goto(f"{url}{ch}/index.html?beat=0&t=0"); await pg.wait_for_timeout(300)diff --git a/.claude/skills/papermorph/scripts/export.py b/.claude/skills/papermorph/scripts/export.pyindex fe8d1cc..b4fb88b 100644--- a/.claude/skills/papermorph/scripts/export.py+++ b/.claude/skills/papermorph/scripts/export.py@@ -16,6 +16,7 @@ import argparse, asyncio, functools, json, subprocess, sys, tempfile, waveimport numpy as npfrom pathlib import Pathfrom playwright.async_api import async_playwright+from browsers import exeEND_SECONDS = 4FLAT = '#frame { border-radius: 0 !important; box-shadow: none !important; }' # square corners in the video@@ -66,7 +67,7 @@ async def main(a):out = Path(a.out); out.mkdir(parents=True, exist_ok=True)scale = a.height / 900async with async_playwright() as p:- b = await p.chromium.launch()+ b = await p.chromium.launch(**exe())# The page fits a 1640 x 1000 frame at scale 1: the 1600 x 900 stage, rendered at the requested height.pg = await b.new_page(viewport={'width': 1640, 'height': 1000}, device_scale_factor=scale)errs = []diff --git a/.claude/skills/papermorph/scripts/ledger.py b/.claude/skills/papermorph/scripts/ledger.pynew file mode 100644index 0000000..cf3d371--- /dev/null+++ b/.claude/skills/papermorph/scripts/ledger.py@@ -0,0 +1,20 @@+"""Sums for the paint scripts' 5-column TSV ledgers (date, file, model, quality, cost)."""+import pathlib+++def rows(path):+ """Parsed non-empty ledger rows: [date, file, model, quality, cost]."""+ text = pathlib.Path(path).read_text(encoding="utf-8")+ return [l.rstrip("\n").split("\t") for l in text.splitlines() if l.strip()]+++def print_total(path, note=""):+ """Per-model and overall USD sums; note appends e.g. ', estimated'."""+ rs = rows(path)+ by = {}+ for r in rs:+ by[r[2]] = by.get(r[2], 0) + float(r[4])+ tail = f" ({len(rs)} pictures{', ' + note if note else ''})"+ for m, c in sorted(by.items()):+ print(f"{m:40s} {c:8.4f} USD")+ print(f"{'total':40s} {sum(by.values()):8.4f} USD{tail}")diff --git a/.claude/skills/papermorph/scripts/paint.py b/.claude/skills/papermorph/scripts/paint.pyindex ea85673..bf5541b 100644--- a/.claude/skills/papermorph/scripts/paint.py+++ b/.claude/skills/papermorph/scripts/paint.py@@ -17,16 +17,9 @@ after a batch, so the spend is known."""import argparse, base64, datetime, json, mimetypes, os, pathlib, sys, urllib.request, urllib.error+from ledger import print_total-def total(path):- rows = [l.rstrip("\n").split("\t") for l in pathlib.Path(path).read_text(encoding="utf-8").splitlines() if l.strip()]- by = {}- for r in rows:- by[r[2]] = by.get(r[2], 0) + float(r[4])- for m, c in sorted(by.items()):- print(f"{m:40s} {c:8.4f} USD")- print(f"{'total':40s} {sum(by.values()):8.4f} USD ({len(rows)} pictures)")-+total = print_totaldef key():f = pathlib.Path("~/.config/openrouter/key").expanduser()@@ -55,12 +48,14 @@ def main():body["resolution"] = "2K"if a.refs:body["input_references"] = [{"type": "image_url", "image_url": {"url": f"data:{mimetypes.guess_type(r)[0] or 'image/png'};base64," + base64.b64encode(pathlib.Path(r).read_bytes()).decode()}} for r in a.refs]+ k = key()req = urllib.request.Request("https://openrouter.ai/api/v1/images", json.dumps(body).encode(),- {"Authorization": f"Bearer {key()}", "Content-Type": "application/json"})+ {"Authorization": f"Bearer {k}", "Content-Type": "application/json"})try:r = json.load(urllib.request.urlopen(req, timeout=600))except urllib.error.HTTPError as e:- raise SystemExit(f"{e.code} {e.read().decode()[:500]}")+ err = e.read().decode(errors="replace").replace(k, "***")[:500] # redact the whole body, then trim+ raise SystemExit(f"{e.code} {err}")out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)out.write_bytes(base64.b64decode(r["data"][0]["b64_json"]))usage = r.get("usage") or {}diff --git a/.claude/skills/papermorph/scripts/paint_openai.py b/.claude/skills/papermorph/scripts/paint_openai.pynew file mode 100644index 0000000..79c35ba--- /dev/null+++ b/.claude/skills/papermorph/scripts/paint_openai.py@@ -0,0 +1,108 @@+#!/usr/bin/env python3+"""One picture from OpenAI's image API directly (no OpenRouter). Same CLI, ledger and spirit as paint.py.++ python3 paint_openai.py OUT.png "prompt" [ref.png ...] [--ar 16:9] [--q low|medium] [--bg transparent]+ [--model gpt-image-2.5-flare] [--env /path/to/.env] --ledger books/<book>/art/costs.tsv+ python3 paint_openai.py --total books/<book>/art/costs.tsv # sum a ledger, per model and overall++Aspect ratios map to OpenAI's sizes: 16:9 -> 1536x1024, 9:16 -> 1024x1536, otherwise 1024x1024.+Reference pictures go through /v1/images/edits (multipart), no refs through /v1/images/generations (JSON).+Quality is low or medium only: high costs several times as much and has never been needed; the script refuses it.+The key is read from $OPENAI_API_KEY, else from --env FILE, else ~/.config/papermorph/.env.++OpenAI's response reports usage tokens but not a USD cost, so the ledger records an estimate+(about 0.02 USD per low picture, 0.05 per medium at 1536x1024) — check the invoice for exact numbers.+Each call prints the usage and appends one line to the ledger (date, file, model, quality, cost).+"""+import argparse, base64, datetime, json, os, pathlib, sys, urllib.request, urllib.error++API = "https://api.openai.com/v1"+SIZES = {"16:9": "1536x1024", "9:16": "1024x1536", "1:1": "1024x1024"}+EST = {"low": 0.02, "medium": 0.05, "high": 0.20}+++from ledger import print_total++def total(path):+ print_total(path, 'estimated')+++def env_value(v):+ """An .env value: surrounding whitespace, then matching outer quotes, removed."""+ v = v.strip()+ if len(v) >= 2 and v[0] == v[-1] and v[0] in ('"', "'"):+ v = v[1:-1]+ return v+++def key(env):+ if os.environ.get("OPENAI_API_KEY"):+ return os.environ["OPENAI_API_KEY"]+ for f in ([pathlib.Path(env)] if env else []) + [pathlib.Path("~/.config/papermorph/.env").expanduser()]:+ if f.exists():+ for line in f.read_text().splitlines():+ if line.startswith("OPENAI_API_KEY="):+ k = env_value(line.split("=", 1)[1])+ if k: # skip empty lines, keep looking+ return k+ raise SystemExit("no key: set OPENAI_API_KEY or pass --env FILE with OPENAI_API_KEY=...")+++def post(url, key, data, headers):+ req = urllib.request.Request(url, data, {"Authorization": f"Bearer {key}", **headers})+ try:+ return json.load(urllib.request.urlopen(req, timeout=600))+ except urllib.error.HTTPError as e:+ body = e.read().decode(errors="replace").replace(key, "***")[:500] # redact the whole body, then trim+ raise SystemExit(f"{e.code} {body}")+++def multipart(fields, files):+ b = "----papermorph" + os.urandom(8).hex()+ def part(h, v): return f"--{b}\r\n{h}\r\n\r\n".encode() + (v if isinstance(v, bytes) else v.encode()) + b"\r\n"+ body = b"".join(part(f'Content-Disposition: form-data; name="{k}"', v) for k, v in fields.items())+ for name, fname, data in files:+ body += part(f'Content-Disposition: form-data; name="{name}"; filename="{fname}"\r\nContent-Type: image/png', data)+ return body + f"--{b}--\r\n".encode(), f"multipart/form-data; boundary={b}"+++def main():+ if len(sys.argv) == 3 and sys.argv[1] == "--total":+ return total(sys.argv[2])+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)+ ap.add_argument("out"); ap.add_argument("prompt"); ap.add_argument("refs", nargs="*")+ ap.add_argument("--ar", default="16:9"); ap.add_argument("--q", default="medium", choices=["low", "medium", "high"])+ ap.add_argument("--bg", default="auto", choices=["auto", "transparent", "opaque"])+ ap.add_argument("--model", default="gpt-image-2.5-flare")+ ap.add_argument("--env", default="", help="path to a .env file containing OPENAI_API_KEY=...")+ ap.add_argument("--ledger", required=True, help="tab-separated cost log, e.g. books/<book>/art/costs.tsv")+ a = ap.parse_args()+ if a.q == "high":+ raise SystemExit("quality high is refused: use low or medium")+ k = key(a.env)+ size = SIZES.get(a.ar, "1024x1024")+ out = pathlib.Path(a.out); out.parent.mkdir(parents=True, exist_ok=True)++ if a.refs:+ fields = {"model": a.model, "prompt": a.prompt, "quality": a.q, "size": size}+ if a.bg != "auto":+ fields["background"] = a.bg+ body, ctype = multipart(fields, [("image[]", pathlib.Path(r).name, pathlib.Path(r).read_bytes()) for r in a.refs])+ r = post(f"{API}/images/edits", k, body, {"Content-Type": ctype})+ else:+ body = {"model": a.model, "prompt": a.prompt, "quality": a.q, "size": size, "output_format": "png"}+ if a.bg != "auto":+ body["background"] = a.bg+ r = post(f"{API}/images/generations", k, json.dumps(body).encode(), {"Content-Type": "application/json"})++ out.write_bytes(base64.b64decode(r["data"][0]["b64_json"]))+ usage = r.get("usage") or {}+ cost = (usage.get("cost") if isinstance(usage, dict) else None) or EST[a.q]+ print(a.out, f"cost {cost} USD (est)", json.dumps(usage))+ led = pathlib.Path(a.ledger); led.parent.mkdir(parents=True, exist_ok=True)+ with led.open("a", encoding="utf-8") as f:+ f.write(f"{datetime.date.today()}\t{a.out}\t{a.model}\t{a.q}\t{cost:.4f}\n")+++if __name__ == "__main__":+ main()diff --git a/.claude/skills/papermorph/scripts/shot.py b/.claude/skills/papermorph/scripts/shot.pyindex 1496418..2e8f464 100644--- a/.claude/skills/papermorph/scripts/shot.py+++ b/.claude/skills/papermorph/scripts/shot.py@@ -14,17 +14,19 @@ import argparse, asyncioimport sysfrom pathlib import Pathfrom playwright.async_api import async_playwright+from browsers import exefrom PIL import Imageasync def main(a):a.out.mkdir(parents=True, exist_ok=True)async with async_playwright() as p:- b = await p.chromium.launch()+ b = await p.chromium.launch(**exe())pg = await b.new_page(viewport={"width": 1600, "height": 960})errs = []pg.on("pageerror", lambda e: errs.append(str(e)))- pg.on("console", lambda m: m.type == "error" and errs.append(m.text))+ # a desktop browser ($CHROME) also asks the server for /favicon.ico, which is not the book's+ pg.on("console", lambda m: m.type == "error" and not m.location.get("url", "").endswith("/favicon.ico") and errs.append(m.text))base = f"{a.url}{a.chapter}/index.html"await pg.goto(base + "?beat=0&t=0"); await pg.wait_for_timeout(500)if errs:diff --git a/.claude/skills/papermorph/scripts/strip.py b/.claude/skills/papermorph/scripts/strip.pyindex 0955e45..91734d5 100644--- a/.claude/skills/papermorph/scripts/strip.py+++ b/.claude/skills/papermorph/scripts/strip.py@@ -17,6 +17,7 @@ a row. Firefox by default: it is the slowest common browser and the one to judgeimport argparse, asyncio, re, sys, tempfilefrom pathlib import Pathfrom playwright.async_api import async_playwright+from browsers import exefrom PIL import Image, ImageDrawdef sheet(ims, path, cols=4):@@ -40,7 +41,7 @@ async def main(a):out = Path(a.out); out.mkdir(parents=True, exist_ok=True)tmp = Path(tempfile.mkdtemp()) / "f.png"async with async_playwright() as p:- b = await (p.firefox.launch(firefox_user_prefs={"media.autoplay.default": 0}) if a.browser == "firefox" else p.chromium.launch())+ b = await (p.firefox.launch(firefox_user_prefs={"media.autoplay.default": 0}) if a.browser == "firefox" else p.chromium.launch(**exe()))pg = await b.new_page(viewport={"width": 1600, "height": 960})errs = []; pg.on("pageerror", lambda e: errs.append(str(e)))await pg.goto(f"{a.url}{a.chapter}/?beat=0&t=0"); await pg.wait_for_timeout(800)