Skip to content

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

feat(skill): lint.py, fast static checks of a book's chapters

yzr4b7d120e1803
diff --git a/.claude/skills/papermorph/references/engine.md b/.claude/skills/papermorph/references/engine.md
index 8ecc0b9..44e9fc2 100644
--- a/.claude/skills/papermorph/references/engine.md
+++ b/.claude/skills/papermorph/references/engine.md
@@ -91,7 +91,7 @@ quiz(position, [{ id: 'c-mean', prompt: ['Find the mean of ', $m('7, 3, 9'), '.'
## Player
-Space play/pause, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions, F full screen, ? help. `seek(i, play)` rebuilds and jumps; `start(i, play)` begins a beat from the current picture. While audio plays, the beat clock follows `audio.currentTime`. `?beat=N&t=S` in the URL opens a frozen frame for review. The finish card's Enter opens `CHAPTER.next`, R replays.
+Space play/pause, ←/→ previous/next beat (Shift+←/→ during a question), Home restart, C captions, `<`/`>` speed (0.75–1.5×, remembered), F full screen, ? help. Clicking a step segment jumps to that point of the beat (`seekInto(i, frac)`); the next beat's clip preloads while one plays. `seek(i, play)` rebuilds and jumps; `start(i, play)` begins a beat from the current picture. While audio plays, the beat clock follows `audio.currentTime`. `?beat=N&t=S` in the URL opens a frozen frame for review. The finish card's Enter opens `CHAPTER.next`, R replays.
Progress uses the stable legacy key `animebook:progress:<book-path>` (keep it when renaming the project so existing readers retain their progress); the cover template reads the same key. A book can set another key with `--progress-key` in `lib/book.css`; its cover must then read that key. Books served in different folders have separate saved places and completion lists.
@@ -103,7 +103,7 @@ Keep `<link rel="expect" href="#bar" blocking="render">` in every chapter's head
- `M()` italicises 1–2 letter lowercase runs (variables) and runs of capitals, but keeps common short English words upright (by, my, an, if, in, is, of, or, …; capitalised: By, If, In, …). In maths write `b​y`, `m​y`, `a​n`, `B​y` to keep them italic. Units inside `M()` turn italic too: write them as words in `T()` text ("meters"). Never put an English sentence in `M()`.
- Prompts, `grid` text rows and `choice` options are HTML: plain strings render as text, so wrap math in `$m(...)`.
-- Prefix chapter-specific helpers when their names might collide with engine globals (`rect`, `popIn`, `eqLine`, `fit`, `slot`, `Y0`, `OV`, `camera`, `soft`, `clockRun`, `retire`, `seeking`, `BOOK`, `bookSetting`, …); a redeclaration stops the page script.
+- Prefix chapter-specific helpers when their names might collide with engine globals (`rect`, `popIn`, `eqLine`, `fit`, `slot`, `Y0`, `OV`, `camera`, `soft`, `clockRun`, `retire`, `seeking`, `BOOK`, `bookSetting`, …); a redeclaration stops the page script. `lint.py` lists every clash.
- Drag handling: re-parent (append) the element before `setPointerCapture`; moving a node drops its capture.
- A card whose content is too long for `BAND` should become several `blanks` rows in a wider side card.
- When a question beat is continued early, the engine finishes the beat's pending tweens first; don't rely on half-finished fades.
diff --git a/.claude/skills/papermorph/references/review.md b/.claude/skills/papermorph/references/review.md
index 36a47b1..de1841e 100644
--- a/.claude/skills/papermorph/references/review.md
+++ b/.claude/skills/papermorph/references/review.md
@@ -10,6 +10,10 @@ uv run --with playwright --with pillow SKILL/scripts/strip.py chNN OUT --url htt
A strip shows one beat at small steps; `@w` adds a motion WebP. Look at each action as a viewer would: do actors perform what the narration says, do props stay on the hands, does the camera move with purpose, does each frame still match the storyboard, do arrows, labels and readouts agree with the motion? Then watch a few beats live in Firefox with sound, which is how the user watches.
+## Static checks first
+
+`python3 SKILL/scripts/lint.py site/<book> chNN` takes a second and needs no browser: a global name that clashes with the engine or a library (which stops the page script), beats without timings or MP3, marks the code waits for that the narration lacks, narration edited since `tts.py` ran, and a malformed `style.json`. Run it after every edit, before the passes below.
+
## Frames and openings
```sh
diff --git a/.claude/skills/papermorph/scripts/lint.py b/.claude/skills/papermorph/scripts/lint.py
new file mode 100644
index 0000000..681df85
--- /dev/null
+++ b/.claude/skills/papermorph/scripts/lint.py
@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Fast static checks of a book's chapters, no browser: run before the delivery pass and after any edit.
+
+ python3 lint.py site/<book> # every chapter
+ python3 lint.py site/<book> ch12 ch13 # some chapters
+ python3 lint.py site/<book> --content content/<book> --brief books/<book>
+
+Errors (exit status 1):
+ global a top-level name in the chapter or a lib file it loads is also declared by the engine or another of
+ its scripts; a second const/let/class stops the page script, a second function silently replaces one
+ beat a beat id has no entry in audio/<lang>/timings.js or no MP3
+ mark m('name') is not a mark of any beat
+ stale the narration's text or [[marks]] differ from timings.js: run tts.py again
+ style style.json is not valid JSON or lacks schema, tier, book, words, look or voice
+Warnings: a beat's m('name') not among that beat's own marks (beats built by shared helpers can mislead this);
+ no beats recognised in a chapter.
+--content defaults to content/<book> (content/ for the first book's legacy layout), --brief to books/<book>.
+"""
+import argparse, json, re, sys
+from pathlib import Path
+
+DECL = re.compile(r'(?<![\w$.])(?:async\s+)?(function\*?|const|let|var|class)\s+([A-Za-z_$][\w$]*)')
+SRC = re.compile(r'<script\s+src="([^"]+)"')
+INLINE = re.compile(r'<script>(.*?)</script>', re.S)
+BEAT = re.compile(r"\[\s*'(\w+)'\s*,\s*(['\"`])(?:\\.|(?!\2).)*\2\s*,\s*(?:\(\s*(?:m\b|\))|m\s*=>)") # ['id', 'title', (m, D) =>
+MCALL = re.compile(r"(?<![\w$.])m\(\s*'(\w+)'\s*[,)]")
+MARK = re.compile(r'\[\[(\w+)\]\]')
+
+
+def depth0(text):
+ """The code with strings, templates, comments and regex literals blanked, and a mask of brace depth 0."""
+ out, top, depth, i, n = list(text), [False] * len(text), 0, 0, len(text)
+ stack = [] # open template literals: brace depth at each ${
+ prev = '' # last significant character, to tell a regex from a division
+ def blank(a, b):
+ for k in range(a, b):
+ if out[k] != '\n':
+ out[k] = ' '
+ while i < n:
+ c = text[i]
+ if c in '\'"':
+ j = i + 1
+ while j < n and text[j] != c and text[j] != '\n':
+ j += 2 if text[j] == '\\' else 1
+ blank(i + 1, j); i = j + 1; prev = 'a'; continue
+ if c == '`' or (c == '}' and stack and stack[-1] == depth):
+ if c == '}':
+ stack.pop()
+ j = i + 1
+ while j < n and text[j] != '`' and not (text[j] == '$' and text[j + 1:j + 2] == '{'):
+ j += 2 if text[j] == '\\' else 1
+ blank(i + 1, j)
+ if j < n and text[j] == '$':
+ stack.append(depth); i = j + 2; prev = '('; continue
+ i = j + 1; prev = 'a'; continue
+ if c == '/' and text[i + 1:i + 2] == '/':
+ j = text.find('\n', i); j = n if j < 0 else j
+ blank(i, j); i = j; continue
+ if c == '/' and text[i + 1:i + 2] == '*':
+ j = text.find('*/', i + 2); j = n if j < 0 else j + 2
+ blank(i, j); i = j; continue
+ if c == '/' and (prev in '(,=:[!&|?{};+-*%<>~^' or prev == ''):
+ j, cls = i + 1, False
+ while j < n and text[j] != '\n' and (text[j] != '/' or cls):
+ if text[j] == '\\': j += 1
+ elif text[j] == '[': cls = True
+ elif text[j] == ']': cls = False
+ j += 1
+ blank(i + 1, j); i = j + 1; prev = 'a'; continue
+ if c in '{([':
+ depth += 1
+ elif c in '})]':
+ depth -= 1
+ top[i] = depth == 0
+ if not c.isspace():
+ prev = 'a' if (c.isalnum() or c in '_$') else c
+ if c.isalpha(): # keywords after which a slash starts a regex
+ w = re.match(r'[A-Za-z]+', text[i:]).group(0)
+ if w in ('return', 'typeof', 'case', 'in', 'of', 'new', 'delete', 'void', 'throw', 'else', 'do'):
+ prev = '('
+ top[i:i + len(w)] = [depth == 0] * len(w)
+ i += len(w); continue
+ i += 1
+ return ''.join(out), top
+
+
+def decls(text):
+ """Top-level declarations of a script: name, kind and line."""
+ code, top = depth0(text)
+ return [(m.group(2), m.group(1), code.count('\n', 0, m.start()) + 1)
+ for m in DECL.finditer(code) if top[m.start()]]
+
+
+def timings(path):
+ t = path.read_text(encoding='utf-8')
+ return json.loads(t[t.index('{'):t.rindex('}') + 1])
+
+
+def words(s):
+ return re.sub(r'[^\w]+', ' ', MARK.sub('', s)).lower().split()
+
+
+def lint_chapter(ch, content, out):
+ err = lambda kind, msg: out.append(('E', kind, f'{ch.name}: {msg}'))
+ warn = lambda kind, msg: out.append(('W', kind, f'{ch.name}: {msg}'))
+ html = (ch / 'index.html').read_text(encoding='utf-8')
+ inline = '\n'.join(INLINE.findall(html))
+ # globals: every script the page loads, in order
+ seen = {}
+ for src in SRC.findall(html) + ['(chapter)']:
+ if src == '(chapter)':
+ text, name = inline, 'chapter'
+ else:
+ f = (ch / src).resolve()
+ if f.suffix != '.js' or not f.exists() or f.name == 'timings.js':
+ continue
+ text, name = f.read_text(encoding='utf-8'), f.name
+ for ident, kind, line in decls(text):
+ if ident in seen:
+ first, k0 = seen[ident]
+ what = 'replaces' if kind.startswith('function') and k0.startswith('function') else 'redeclares'
+ err('global', f'{name}:{line} {what} {ident} from {first}')
+ else:
+ seen[ident] = (name, kind)
+ # beats, audio, marks
+ lang = (re.search(r"language:\s*'(\w+)'", inline) or [None, 'en'])[1]
+ tpath = ch / 'audio' / lang / 'timings.js'
+ if not tpath.exists():
+ return err('beat', f'no audio/{lang}/timings.js')
+ T = timings(tpath)
+ starts = [(m.start(), m.group(1)) for m in BEAT.finditer(inline)]
+ ids = [b for _, b in starts]
+ if not ids:
+ warn('beat', "no beats recognised (expected ['id', 'title', (m, D) => …]); marks were not checked")
+ for b in ids:
+ if b not in T:
+ err('beat', f'beat {b} has no timings')
+ elif not (ch / 'audio' / lang / f'{b}.mp3').exists():
+ err('beat', f'beat {b} has no MP3')
+ every = {k for v in T.values() for k in v.get('marks', {})}
+ for i, (pos, b) in enumerate(starts):
+ body = inline[pos:starts[i + 1][0] if i + 1 < len(starts) else len(inline)]
+ for k in sorted(set(MCALL.findall(body))):
+ if k not in every:
+ err('mark', f"m('{k}') in beat {b} is not a mark of any beat")
+ elif b in T and k not in T[b].get('marks', {}):
+ warn('mark', f"m('{k}') in beat {b} is not one of its marks")
+ # narration against the generated audio
+ nar = content / ch.name / f'narration.{lang}.json'
+ if nar.exists():
+ N = json.loads(nar.read_text(encoding='utf-8-sig')).get('beats', {})
+ for b, text in N.items():
+ if b not in T:
+ err('stale', f'narration beat {b} has no timings')
+ continue
+ if set(MARK.findall(text)) != set(T[b].get('marks', {})):
+ err('stale', f'beat {b}: narration marks differ from timings.js')
+ cues = ' '.join(c[1] for c in T[b].get('cues', []))
+ if cues and words(text) != words(cues):
+ err('stale', f'beat {b}: narration text differs from the generated audio')
+
+
+def lint_style(brief, out):
+ p = brief / 'style.json'
+ if not p.exists():
+ return
+ try:
+ s = json.loads(p.read_text(encoding='utf-8'))
+ except ValueError as e:
+ return out.append(('E', 'style', f'style.json: {e}'))
+ missing = [k for k in ('schema', 'tier', 'book', 'words', 'look', 'voice') if k not in s]
+ if missing:
+ out.append(('E', 'style', f'style.json lacks {", ".join(missing)}'))
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument('book', type=Path, help='the book folder in site/')
+ ap.add_argument('chapters', nargs='*', help='chNN (default: all)')
+ ap.add_argument('--content', type=Path)
+ ap.add_argument('--brief', type=Path)
+ a = ap.parse_args()
+ root, slug = a.book.resolve().parent.parent, a.book.resolve().name
+ content = a.content or next((c for c in (root / 'content' / slug, root / 'content') if c.is_dir()), root / 'content' / slug)
+ chs = [a.book / c for c in a.chapters] if a.chapters else sorted(a.book.glob('ch[0-9]*'))
+ out = []
+ for ch in chs:
+ if (ch / 'index.html').exists():
+ lint_chapter(ch, content, out)
+ lint_style(a.brief or root / 'books' / slug, out)
+ for level, kind, msg in out:
+ print(f'{"error" if level == "E" else "warn "} {kind:6} {msg}')
+ n = sum(level == 'E' for level, _, _ in out)
+ print(f'{len(chs)} chapters: {n} errors, {len(out) - n} warnings')
+ sys.exit(1 if n else 0)
+
+
+if __name__ == '__main__':
+ main()