playrig 0.0.0-stage → 0.1.0

package/editions/ae/skills/create-ae-recipe/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: create-ae-recipe
+description: Add a new recipe (reusable, parameterised After Effects effect, element, camera move, transition or scene) to the motion library in <library>/. Works from a text description, iterating with visual previews until the user approves, or from a reference video that is analysed frame by frame and converted into a recipe. Use when the user wants to create, add, capture, recreate or "turn into a recipe" an animation or effect.
+---
+
+# create-ae-recipe
+
+You add one recipe at a time to `<library>/` (one Markdown file per recipe, see `<library>/README.md`). Recipes run in the user's **open** After Effects project through the Playrig for After Effects, so the work is: build it, **look at it**, show the user, iterate, then save it cleanly.
+
+Two entry points, same finish:
+
+- **A. From a description** → draft, preview, iterate with the user.
+- **B. From a reference video** → break it down frame by frame, measure it, rebuild it, compare against the reference.
+- **C. Finalise** (both) → generalise params, document tweaks, lint, save previews, index, clean up.
+
+## 0. Setup and safety (always)
+
+```bash
+.claude/skills/create-ae-recipe/scripts/setup.sh      # once: ffmpeg + Pillow venv (idempotent)
+playrig ae scratch start       # remember what's in the project before you add anything
+```
+
+- After Effects must be open with the Playrig for After Effects panel started (status `Idle`). If a job times out, tell the user to start the panel.
+- You are working inside the user's real project. **All experiments go in comps named `SCRATCH-<id>-v<n>`.** Never modify their existing layers/comps. Never save the project. Never run `scratch clean --yes` before reading its list and confirming every item is yours.
+- Each Playrig job is one Undo step; the user can Edit > Undo.
+- Fonts: check the requested font is installed (`textInfo.font` via inspect, or a visible substitution in the preview). Default is Inter.
+
+Media tools (video/image): `.claude/skills/create-ae-recipe/scripts/media` (alias `M` below). `M --help` lists them.
+
+## 1. Check the library first
+
+Read **only** `<library>/INDEX.md`. If an existing recipe already covers (most of) the request, say so and offer: use it as is / extend it with new params / make a variant. Look at `composes_with` — many "new" looks are a chain of existing recipes. Decide the recipe boundary: **one effect per recipe**; a whole scene is a chain, not a recipe.
+
+## A. From a description
+
+1. **Clarify minimally.** Ask at most 3 questions, only those that change the build (light or dark background? what text/labels? duration/size?). Otherwise pick defaults and say what you assumed.
+2. **Plan out loud in 5 lines:** recipe id (`lowercase-kebab`), category, what it builds, the 5-10 parameters you will expose, what it needs (fonts, comp order).
+3. **Draft:** `playrig ae lib new <category>/<id>` (creates an `experimental` recipe). Write the `jsx` block using `references/ae-patterns.md` (matchNames, expression templates, ES3 rules, easing).
+4. **Preview:** `playrig ae lib run <id> --param comp=SCRATCH-<id>-v1` renders the frames listed in `preview_times`. For motion, pick times that show the *sequence* (start, early, mid, settle) and combine them: `M sheet <png paths…> --cols 2 --out /tmp/<id>-v1.png`. **Read the image yourself first** and fix obvious defects (wrong order, clipped, invisible text, off-screen) before showing the user.
+5. **Show the user** the sheet (give the file path; describe what they should be seeing), and ask for *concrete* feedback: timing, size, colour, amount of motion, anything missing. Offer 2-3 quick variants when taste is the question ("tighter vs floatier"): render them side by side.
+6. **Iterate:** edit the recipe or pass different `--param`s, `playrig ae scratch clean --yes` (after checking its list), re-run as `-v2`, `-v3`. Keep a one-line changelog of what changed and why; it becomes "Gotchas"/"Tweaks".
+7. When the user says it's right → **C. Finalise**.
+
+## B. From a reference video
+
+Goal: understand *what is built and how it moves*, then rebuild it parametrically, **not** to clone pixels.
+
+1. **Probe:** `M info <video>` (fps, size, duration). `M cuts <video>` (hard cuts only: dissolves/overlaps are not detected). Note fps: express timings in frames at that fps.
+2. **Overview:** `M frames <video> --fps 4 --out /tmp/ref` then `M sheet /tmp/ref --cols 3` (labelled contact sheets). Read **every** sheet. Write a shot list: time range, what's on screen, background, transition into the shot.
+3. **Scope with the user:** list the distinct, reusable pieces you see (e.g. "per-word text fly-in", "chip pops", "CMY split exit") and recommend which to capture. Ask which one(s). Capture one recipe per piece; remember the rest as `planned` stubs if the user wants them tracked.
+4. **Measure the chosen piece** (see `references/video-analysis.md` for the full checklist):
+   - Frame-accurate view: `M frames <video> --start S --end E --every-frame --out /tmp/win` → `M sheet /tmp/win --cols 4 --cell 480`.
+   - Timing and easing: `M activity <video> --start S --end E [--region x,y,w,h]`. Burst starts/ends = animation start/duration; decay shape = easing; gaps between bursts = stagger spacing.
+   - Colours: `M palette <frame>`, `M color <frame> x,y --box 5` (coordinates are in the frame's pixels; scale to 1920×1080 if the video is smaller).
+   - Detail: `M crop <frame> x y w h --scale 3` to read type weight, stroke width, corner radius, handles.
+5. **Hypothesise the build** in After Effects terms (layers, text animators, expressions, parenting, camera) and state it. If something is ambiguous (random vs designed, 2D vs 3D) test the cheapest hypothesis first.
+6. **Rebuild** as an `experimental` recipe (`lib new`), run it in `SCRATCH-<id>-vN`, rendering at the **same timestamps** as the reference frames you studied: `playrig ae lib run <id> --param comp=… --snap "SCRATCH-<id>-v1@t1,t2,t3"` (or set `preview_times`).
+7. **Compare:** `M compare <ref frame> <our frame> --diff --out /tmp/cmp-t.png` for 3-4 key times. Read them. Fix the largest differences first (timing → position → size → colour → polish). Stop when it reads the same at normal speed; exact pixels are not the goal.
+8. **Show the user** comparisons (reference | ours) and ask what to adjust. Iterate as in A.6.
+9. → **C. Finalise.** Credit the source in `origin:` (e.g. "reference video: <name>, 3.2-4.1 s").
+
+## C. Finalise
+
+1. **Generalise.** Turn every magic number into a parameter named for what it does visually (`staggerFrames`, `popFrom`), with units in `desc` and sensible `min`/`max`. Defaults = the approved look. Keep to 5-15 params; fold the rest into constants. Include `comp` (always) and `width/height/duration/fps` only if the recipe can create the comp.
+2. **Prove the tweaks.** For the 3-5 most important params, render a low and a high value and look. Write "Tweaks that matter" from what you saw, not from guesses.
+3. **Document** the file: `summary` (≤150 chars, one sentence), `use_when`, `tags`, `aliases` (names people will actually say, incl. industry terms), `composes_with` (existing ids), `origin`, and the sections *What it looks like / How it works / Tweaks that matter / Gotchas / Combine with*. Gotchas = ordering rules, requirements (fonts, light backgrounds), limits, and anything you hit while iterating.
+4. **Check replaceability.** Run the recipe twice on a scratch comp, the second time with `--replace` (and different params): the comp must end with one clean set of layers in the same stacking position. If the recipe changes *existing* layers (parents, 3D flags, deletes or replaces them), set `idempotent: false` and write a `replace_note` that says how to change it instead.
+5. **Check:** `playrig ae lib check` must show 0 errors (fix warnings you can).
+6. **Previews + status:** `playrig ae lib run <id> --param comp=SCRATCH-<id>-final --save-preview` (stores images next to the recipe and embeds them), then set `status: ready` in the frontmatter.
+7. **Index:** `playrig ae lib index`. Confirm the new line reads well in `<library>/INDEX.md`.
+8. **Clean up:** `playrig ae scratch clean` → read the list → `scratch clean --yes`. Confirm the item count is back to baseline.
+9. **Report:** id, what it does, params, what you could not capture or assumed, and how to run it. Don't commit unless asked.
+
+## Quality bar
+
+- It was **run in After Effects and looked at**, at least at start/mid/end of the motion. "Status ok" is not evidence the picture is right.
+- Matchnames only; ES3 only; no reliance on any specific project; self-contained expressions.
+- Order-dependent behaviour is in Gotchas.
+- A stranger could pick it from the index line, tune it from the Tweaks table, and run it without opening the script.
+
+## References (load on demand)
+
+- `references/ae-patterns.md`: matchNames, expression templates (stagger, easing, seeded random), keyframe/ease API, 3D/parenting pitfalls, ES3 rules, helper functions.
+- `references/video-analysis.md`: the frame-by-frame breakdown checklist, effect fingerprints, how to read easing/stagger from motion data, what can't be inferred.
+- `<library>/README.md`: the recipe file format and conventions. `<library>/_common.jsx`: helpers appended to every recipe (`libText`, `libTextAnimator`, `libKey`, …).

package/editions/ae/skills/create-ae-recipe/references/ae-patterns.md

@@ -0,0 +1,88 @@
+# After Effects patterns for recipes
+
+Everything here was verified in After Effects 26.5 through the Playrig for After Effects while building the library. Scripts are **ExtendScript (ES3)**.
+
+## ES3 rules (the linter `playrig ae lib check` enforces most)
+
+No `let`/`const`, arrow functions, template literals, `JSON`, `Array.indexOf/forEach/map/filter`, `Math.sign`, `String.trim`. Use `for` loops, `var`, string concatenation. Helper for membership: loop and compare. Function declarations are hoisted, which is how `_common.jsx` helpers are available from line 1.
+
+Parameters arrive as `P.<name>` (defaults merged by the CLI). Don't redefine `P`.
+
+## matchNames (never display names: they break in non-English AE)
+
+| Thing | matchName |
+|---|---|
+| Transform group | `ADBE Transform Group` → `ADBE Anchor Point`, `ADBE Position` (`ADBE Position_0/1/2` if separated), `ADBE Scale`, `ADBE Rotate Z` (2D) / `ADBE Rotate X/Y/Z`, `ADBE Orientation`, `ADBE Opacity` |
+| Camera | `ADBE Camera Options Group` → `ADBE Camera Zoom`; transform `ADBE Point of Interest` **absent on one-node cameras: null-check it** |
+| Effects | `ADBE Effect Parade` → add with `ADBE Ramp` (Gradient Ramp), `ADBE Grid`, `ADBE Tint`, ... |
+| Gradient Ramp props | `ADBE Ramp-0001` start, `-0002` start colour, `-0003` end, `-0004` end colour, `-0005` shape (1 linear, 2 radial), `-0006` scatter, `-0007` blend |
+| Grid props | `ADBE Grid-0001` anchor, `-0002` size from (3 = width & height sliders), `-0004` width, `-0005` height, `-0006` border, `-0012` colour |
+| Tint props | `ADBE Tint-0001` map black, `-0002` map white, `-0003` amount |
+| Text | `ADBE Text Properties` → `ADBE Text Document` (source text), `ADBE Text Animators` |
+| Text animator | `ADBE Text Animator` → `ADBE Text Selectors`, `ADBE Text Animator Properties` |
+| Selectors | `ADBE Text Selector` (range), `ADBE Text Expressible Selector` (`ADBE Text Range Type2` based-on: 1 chars, 2 chars excl. spaces, 3 words, 4 lines; `ADBE Text Expressible Amount`), `ADBE Text Wiggly Selector` |
+| Animator props | `ADBE Text Position 3D`, `ADBE Text Scale 3D`, `ADBE Text Rotation` (Z), `ADBE Text Rotation X/Y`, `ADBE Text Opacity`, `ADBE Text Fill Color`, `ADBE Text Skew`, `ADBE Text Blur`, `ADBE Text Tracking Amount` |
+| Shapes | `ADBE Root Vectors Group` → `ADBE Vector Group` → `ADBE Vectors Group`; `ADBE Vector Shape - Rect` (`ADBE Vector Rect Size`, `ADBE Vector Rect Roundness`), `ADBE Vector Shape - Ellipse`, `ADBE Vector Graphic - Fill` (`ADBE Vector Fill Color`), `ADBE Vector Graphic - Stroke` (`ADBE Vector Stroke Color`, `ADBE Vector Stroke Width`) |
+
+To discover an unknown matchName: build it by hand in a scratch comp, then walk `layer.property(...)` with `numProperties` / `.matchName` in a bridge job (see how it was done for text animators), or `PLAYRIG.inspect`.
+
+## Text
+
+- Create: `comp.layers.addText(str)`; style through `TextDocument` (`font` = **PostScript name** e.g. `Inter-ExtraBold`, `fontSize`, `fillColor` 0..1 RGB, `tracking`, `justification`), then `prop.setValue(doc)`. Call `doc.resetCharStyle()` first.
+- Per-range styling: `var r = doc.characterRange(i, j); r.font = "Inter-Bold"; prop.setValue(doc);` (set `doc`, not `r`; `r` is a live view).
+- A scripted animator starts with **no** default Range Selector (`sels.numProperties` is 0): don't call `property(1).remove()` blindly (use a while loop on numProperties).
+- Selector amount expressions **must return an array** `[v, v, v]` (0..100), not a scalar.
+- `layer.sourceRectAtTime(0, false).width` measures text for sizing chips/boxes.
+
+## Expression templates (JavaScript engine)
+
+```js
+// frame-based stagger with ease-out (textIndex is 1-based; use unit = word/char via Based On)
+var f = timeToFrames(time - thisLayer.inPoint);
+var s = 1 + (textIndex - 1) * STAGGER;
+var p = clamp((f - s) / MOVE_FRAMES, 0, 1);
+var e = 1 - Math.pow(1 - p, 4);        // easeOutQuart  (cubic: 3; expo: 1 - Math.pow(2, -10*p))
+var v = (1 - e) * 100;                  // 100 = fully "away", 0 = settled
+[v, v, v]
+```
+```js
+// arc: path bows mid-flight
+var v = Math.sin(e * Math.PI) * 100;   [v, v, v]
+// stable per-letter random (scatter): seed by textIndex so renders are repeatable
+seedRandom(textIndex * 7 + 1, true); var r = random(-1, 1);
+// parent opacity follows another layer
+parent.transform.opacity
+```
+Embed parameters into expressions by building the string in the recipe (`"... * " + P.staggerFrames`). Keep expressions self-contained (no project layer names).
+
+## Keyframes and easing
+
+- `prop.setValueAtTime(t, value)`; then ease with `prop.setTemporalEaseAtKey(k, [new KeyframeEase(0, inf)], [new KeyframeEase(0, outInf)])`. One ease object per dimension (`libEaseKey` handles this). Influence: 16.7 ≈ linear feel, 33 = classic Easy Ease, 60-85 = strong ease (fast start, long soft landing).
+- Keys set by script are linear by default. Hold = `setInterpolationTypeAtKey(k, KeyframeInterpolationType.HOLD)`.
+- Times are seconds in the comp. Convert frames with `n / comp.frameRate`. Land timings on whole frames.
+- Don't keyframe layers whose `startTime ≠ 0` from scripts: keys come out offset. Put the animation inside the precomp or set `startTime` last and verify `keyTime()`.
+
+## Layers, 3D, parenting
+
+- New layers are added **on top**. If B must sit above A, add A first, then B, or `B.moveBefore(A)` (chip label above chip).
+- Shape groups: **first group draws on top**. Inside a group: path, then stroke, then fill (stroke drawn above fill).
+- `layer.parent = other` can jump the child's position. Make the parent's anchor = position = comp centre (identity transform) so there's no jump, and set children's local positions **after** parenting.
+- A 3D layer's children must also be 3D to follow it in perspective (a rig recipe has to convert them).
+- 3D layers are skipped by 2D push-in rigs by design; use the camera or the layer's own drift.
+- Property references go stale after `addProperty()`: re-fetch by matchName.
+- Camera: one-node camera by default; position `[cx, cy, -zoom]`, zoom param = px; Z=0 layers stay 1:1.
+- Adjustment layer: add a solid then `layer.adjustmentLayer = true`; effects only affect layers **below**.
+- Blend modes: `layer.blendingMode = BlendingMode.MULTIPLY`. CMY copies on Multiply make black on white backgrounds.
+- Motion blur: `layer.motionBlur = true` per layer and `comp.motionBlur = true`; shutter angle 180 is normal.
+
+## Bridge facts that affect recipes
+
+- `alert()` is redirected to the log; `confirm()` returns false. No dialogs.
+- Snapshots are taken after the job finishes; first render of a new comp can be slow (the client waits up to 30 s for late files).
+- Fonts that aren't installed are substituted silently: verify `textInfo.font` in `PLAYRIG.inspect`.
+- Each job = one undo step; partial work stays if a job errors halfway (remove with `scratch clean`).
+- Job ids must be unique per run; `lib run` generates them.
+
+## Helpers available in every recipe (`<library>/_common.jsx`)
+
+`libHex`, `libComp`, `libTargetComp`, `libLayer`, `libRequireLayer`, `libSolid`, `libEaseKey`, `libKey`, `libFrames`, `libList`, `libText`, `libTextAnimator`, `libStyleWord`. Add a helper there (not in a recipe) when two recipes need the same thing, and keep it ES3.

package/editions/ae/skills/create-ae-recipe/references/video-analysis.md

@@ -0,0 +1,72 @@
+# Reading a reference video frame by frame
+
+Goal: recover **what is built and how it moves**, in After Effects terms, well enough to rebuild it parametrically. Not pixel cloning.
+
+## Normalise first
+
+- Note the video's fps and size (`media info`). Express times in **frames at that fps**; motion design lands on small whole numbers of frames (1-4 frame staggers, 6-24 frame moves).
+- Scale measurements to a 1920×1080 comp: `x_comp = x_video * 1920 / video_width`.
+- Social/UI videos are often 30 or 60 fps; recipes default to 24. Convert durations in seconds, then round to frames of the comp you build in.
+
+## Pass 1: shot list (contact sheets at ~4 fps)
+
+For every shot write: time range, background (light/dark/gradient/grid), what's in frame, type (text, size class, weight), any camera feel (flat, perspective, push-in), and **how it ends** (hard cut / dissolve / overlap / scatter-out). Hard cuts show on `media cuts`; dissolves don't: look for frames that blend two scenes.
+
+## Pass 2: per-effect measurement (frame-accurate)
+
+Pick the window of one effect: `media frames --start S --end E --every-frame`, then a sheet at 4 columns.
+
+| Question | How to answer it |
+|---|---|
+| When does it start/stop? | `media activity --start S --end E` (optionally `--region`): first/last frame above threshold. |
+| Easing? | Shape of the motion score: starts high then decays = ease-out; rises then falls = ease in-out; flat = linear; abrupt jump = hold/cut. Strong ease-out (long tail) = 60-85% influence or ease-out quart/expo. |
+| Stagger? | Repeated bursts; spacing between burst starts, in frames = stagger. Or compare when each item first appears on the frame sheet. |
+| What moves, what doesn't? | Use `--region` on one item vs the background. |
+| Position/size | Read pixel coordinates from frames; `media crop` to zoom. Measure at rest (end of the move) and at start. |
+| Colours | `media palette` for the scene, `media color x,y --box 5` for specific fills/strokes (average a small box to avoid anti-aliasing). |
+| Type | Weight (regular/medium/bold/extrabold), tracking (tight/loose), case, size (cap height in px ≈ 0.7 × font size). Ask the user for the font if you can't tell; default Inter. |
+| Depth/3D? | Foreshortening (shapes getting narrower in one axis), perspective convergence, parallax between layers moving at different speeds → 3D layers + camera. |
+| Motion blur? | Streaks along the motion direction on fast moves → motion blur on (180° shutter). |
+
+## Worked example (validated against known ground truth)
+
+A recipe with 6 words, 2-frame stagger, 9-frame ease-out was rendered to video and analysed blind:
+
+```
+M activity video.mp4                          # whole frame: one bell-shaped burst, frames 2-19  -> sum of overlapping moves
+M activity video.mp4 --region 150,225,120,90  # FIRST word only: active frames 2-9, peak early, decaying tail -> ease-out, ~8-9 frame move
+M activity video.mp4 --region 690,225,120,90  # LAST word only:  active frames 12-19
+```
+stagger = (start_last - start_first) / (n - 1) = (12 - 2) / 5 = **2 frames**; move length ~ 8-9 frames. These matched the recipe's real values (stagger 2, move 9). Use the same trick for any repeated element: isolate the first and last with `--region`.
+Whole-frame activity alone blurs overlapping moves together, so always go to regions once you know where the items are.
+
+## Effect fingerprints
+
+| You see | Likely build |
+|---|---|
+| Words/letters arriving one after another with rotation/offset | Text animator + Expression Selector (Words/Characters), staggered by frames |
+| Text that is black but splits into cyan/magenta/yellow fringes | Three Multiply copies (Y/M/C) on a light background |
+| Letters flying apart randomly, spinning, growing | Scatter animators with seeded random per letter |
+| Soft bright centre fading to darker edges | Gradient Ramp (radial) |
+| Faint square grid on dark | Grid effect on a solid at low opacity |
+| Whole frame creeping larger over a hold | Controller null scale 100 → ~105% |
+| Panels tilted in perspective, shifting against each other | 3D layers parented to a rotated null + camera |
+| Everything draining to grey then returning | Adjustment layer + Tint amount keyed |
+| Outline boxes with corner handles around letters | Shape layers per glyph, timed with the reveal |
+| Chips/labels popping with a tiny overshoot | Scale keys 70 → 104 → 100, strong ease |
+
+## Pass 3: hypothesise, build, compare
+
+State the build in layers/animators/expressions. Build the cheapest version, render **at the reference's timestamps**, and `media compare ref ours --diff`. Fix in order: timing → position → size → colour → polish. Compare at *start, early, mid, settle* of the motion, not just the end pose.
+
+## What you cannot recover (say so in the recipe)
+
+- Randomness: you can see it looks random, not the seed. Match the *character* (range, speed), expose a `seed` param.
+- Expressions/rig wiring: you see the result, not the controls. Rebuild with the simplest equivalent.
+- Fonts, exact easing curves, and subtle colour management: approximate and expose as params.
+- Audio and sync: ignored unless the user asks.
+- Source resolution/compression artefacts: don't reproduce them.
+
+## Presenting findings to the user
+
+Short and visual: a shot list, one contact sheet of the piece you propose to capture, your build hypothesis in 3-5 lines, the measured numbers (frames, px, colours) you'll use as defaults, and what you're unsure about. Ask only about decisions that change the result.

package/editions/ae/skills/create-ae-recipe/scripts/media

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Wrapper: runs media.py with the skill's venv (falls back to system python3 if Pillow is importable).
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PY="$HERE/.venv/bin/python"; [ -x "$PY" ] || PY="$(command -v python3)"
+exec "$PY" "$HERE/scripts/media.py" "$@"

package/editions/ae/skills/create-ae-recipe/scripts/media.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""media.py: video/image helpers for the create-ae-recipe skill.
+
+Needs ffmpeg + ffprobe on PATH and Pillow (installed by scripts/setup.sh). Run through scripts/media (wrapper).
+
+  media check
+  media info <video>
+  media cuts <video> [--threshold 18]
+  media frames <video> [--start S] [--end S] [--fps N | --every-frame | --times t1,t2,..] [--width 960] [--out DIR]
+  media sheet <dir-or-files...> [--cols 3] [--cell 640] [--out FILE] [--labels]
+  media activity <video> [--start S] [--end S] [--region x,y,w,h] [--threshold T]
+  media compare <reference.png> <ours.png> [--out FILE] [--diff]
+  media color <image> x,y [x,y ...] [--box W]
+  media palette <image> [--n 6]
+  media crop <image> x y w h [--scale 2] [--out FILE]
+"""
+import argparse, glob, json, os, re, shutil, subprocess, sys, tempfile
+
+def die(msg, code=2):
+    print(msg, file=sys.stderr); sys.exit(code)
+
+def need(tool):
+    if not shutil.which(tool): die(f"{tool} not found. Run scripts/setup.sh")
+
+def run(cmd, **kw):
+    return subprocess.run(cmd, capture_output=True, text=True, **kw)
+
+def pil():
+    try:
+        from PIL import Image, ImageChops, ImageDraw, ImageFont, ImageStat
+        return Image, ImageChops, ImageDraw, ImageFont, ImageStat
+    except ImportError:
+        die("Pillow missing. Run scripts/setup.sh")
+
+def font(size):
+    _, _, _, ImageFont, _ = pil()
+    for p in ("/System/Library/Fonts/Menlo.ttc", "/System/Library/Fonts/Monaco.ttf", "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf", "C:/Windows/Fonts/consola.ttf"):
+        if os.path.exists(p):
+            try: return ImageFont.truetype(p, size)
+            except OSError: pass
+    return ImageFont.load_default()
+
+def probe(video):
+    need("ffprobe")
+    r = run(["ffprobe", "-v", "error", "-print_format", "json", "-show_streams", "-show_format", video])
+    if r.returncode: die(r.stderr.strip() or "ffprobe failed")
+    j = json.loads(r.stdout)
+    v = next((s for s in j["streams"] if s["codec_type"] == "video"), None)
+    if not v: die("no video stream")
+    num, den = (v.get("avg_frame_rate") or v["r_frame_rate"]).split("/")
+    fps = float(num) / float(den) if float(den) else float(v["r_frame_rate"].split("/")[0])
+    dur = float(v.get("duration") or j["format"].get("duration") or 0)
+    return {"width": v["width"], "height": v["height"], "fps": round(fps, 3), "duration": round(dur, 3),
+            "frames": int(v.get("nb_frames") or round(dur * fps)), "codec": v["codec_name"],
+            "audio": any(s["codec_type"] == "audio" for s in j["streams"])}
+
+# ---------------------------------------------------------------- commands
+def cmd_check(a):
+    ok = True
+    for t in ("ffmpeg", "ffprobe"):
+        p = shutil.which(t); print(f"{t}: {p or 'MISSING'}"); ok &= bool(p)
+    try: import PIL; print(f"Pillow: {PIL.__version__}")
+    except ImportError: print("Pillow: MISSING"); ok = False
+    sys.exit(0 if ok else 1)
+
+def cmd_info(a):
+    i = probe(a.video)
+    print(json.dumps(i, indent=2))
+    print(f"\n{i['width']}x{i['height']} @ {i['fps']} fps, {i['duration']} s ({i['frames']} frames), {i['codec']}, audio: {i['audio']}")
+
+def diff_scores(video, start=None, end=None, region=None, gray=True, width=320):
+    """Per-frame mean absolute difference vs the previous frame (0..255), at the video's own fps."""
+    Image, ImageChops, _, _, ImageStat = pil()
+    need("ffmpeg")
+    fps = probe(video)["fps"]
+    fmt = "format=gray" if gray else "format=rgb24"
+    vf = f"{'crop=' + ':'.join(region.split(',')[2:] + region.split(',')[:2]) + ',' if region else ''}scale={width}:-2,{fmt}"
+    tmp = tempfile.mkdtemp()
+    try:
+        cmd = ["ffmpeg", "-y", "-v", "error"] + (["-ss", f"{start:.4f}"] if start else []) + ["-i", video] + (["-t", f"{end - (start or 0):.4f}"] if end else []) + ["-vf", f"fps={fps},{vf}", os.path.join(tmp, "g%05d.png")]
+        r = run(cmd)
+        if r.returncode: die(r.stderr)
+        scores = []; prev = None
+        for fp in sorted(glob.glob(os.path.join(tmp, "g*.png"))):
+            im = Image.open(fp).convert("L" if gray else "RGB")
+            scores.append(0.0 if prev is None else sum(ImageStat.Stat(ImageChops.difference(im, prev)).mean) / len(ImageStat.Stat(im).mean))
+            prev = im
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    return scores, fps
+
+def cmd_cuts(a):
+    # Colour-aware frame differencing (ffmpeg's luma scene score misses cuts between similar-brightness colours).
+    scores, fps = diff_scores(a.video, gray=False, width=160)
+    d = len(scores) / fps
+    cuts = []
+    for i in range(1, len(scores)):
+        nb = [scores[j] for j in (i - 2, i - 1, i + 1, i + 2) if 0 <= j < len(scores)]
+        if scores[i] >= a.threshold and scores[i] > 2.5 * (max(nb) if nb else 0):
+            cuts.append(i / fps)
+    bounds = [0.0] + cuts + [d]
+    print(f"{len(cuts)} hard cuts (frame-to-frame change >= {a.threshold}, a single-frame spike): {', '.join(f'{t:.3f}s (frame {round(t * fps)})' for t in cuts) or 'none'}")
+    print("\nsegments:")
+    for i in range(len(bounds) - 1):
+        print(f"  {i + 1}: {bounds[i]:.2f}s - {bounds[i + 1]:.2f}s ({bounds[i + 1] - bounds[i]:.2f}s)")
+    print("\nOnly HARD cuts are detected. Dissolves, overlaps and fast whips are not: confirm on a contact sheet, and use `media activity` to see when things move.")
+
+def cmd_frames(a):
+    need("ffmpeg")
+    info = probe(a.video)
+    out = a.out or os.path.join(tempfile.gettempdir(), "ae-recipe-frames", re.sub(r"\W+", "_", os.path.basename(a.video)))
+    os.makedirs(out, exist_ok=True)
+    for f in glob.glob(os.path.join(out, "t*.png")): os.remove(f)
+    vf = f"scale={a.width}:-2"
+    if a.times:
+        for t in [float(x) for x in a.times.split(",")]:
+            r = run(["ffmpeg", "-y", "-v", "error", "-ss", f"{t:.4f}", "-i", a.video, "-frames:v", "1", "-vf", vf, os.path.join(out, f"t{t:08.3f}.png")])
+            if r.returncode: die(r.stderr)
+    else:
+        start = a.start or 0.0
+        fps = info["fps"] if a.every_frame else (a.fps or 4.0)
+        cmd = ["ffmpeg", "-y", "-v", "error"]
+        if a.start: cmd += ["-ss", f"{a.start:.4f}"]
+        cmd += ["-i", a.video]
+        if a.end: cmd += ["-t", f"{a.end - start:.4f}"]
+        cmd += ["-vf", f"fps={fps},{vf}", "-start_number", "0", os.path.join(out, "f%05d.png")]
+        r = run(cmd)
+        if r.returncode: die(r.stderr)
+        for f in sorted(glob.glob(os.path.join(out, "f*.png"))):
+            n = int(re.search(r"f(\d+)", f).group(1))
+            os.rename(f, os.path.join(out, f"t{start + n / fps:08.3f}.png"))
+    files = sorted(glob.glob(os.path.join(out, "t*.png")))
+    print(f"{len(files)} frames in {out}")
+    print(f"first {os.path.basename(files[0])}, last {os.path.basename(files[-1])}" if files else "no frames")
+    print(f"video: {info['width']}x{info['height']} @ {info['fps']} fps. Next: media sheet {out}")
+
+def frame_time(path):
+    m = re.findall(r"(\d+\.\d+|\d+)(?=\.png$)", os.path.basename(path))
+    return float(m[-1]) if m else None
+
+def collect(paths):
+    files = []
+    for p in paths:
+        files += sorted(glob.glob(os.path.join(p, "*.png"))) if os.path.isdir(p) else [p]
+    return sorted(files, key=lambda f: (frame_time(f) if frame_time(f) is not None else 1e9, f))
+
+def cmd_sheet(a):
+    Image, _, ImageDraw, _, _ = pil()
+    files = collect(a.paths)
+    if not files: die("no images")
+    cols = a.cols; cell = a.cell
+    first = Image.open(files[0]); ch = round(cell * first.height / first.width)
+    per = cols * cols  # square-ish sheets: cols x cols per page
+    pages = [files[i:i + per] for i in range(0, len(files), per)]
+    base = a.out or os.path.join(os.path.dirname(files[0]) if os.path.isdir(a.paths[0]) is False else a.paths[0], "sheet.png")
+    stem, ext = os.path.splitext(base)
+    outs = []
+    f = font(max(14, cell // 24))
+    for pi, page in enumerate(pages):
+        rows = (len(page) + cols - 1) // cols
+        sh = Image.new("RGB", (cols * cell, rows * ch), (36, 36, 36))
+        for i, fp in enumerate(page):
+            im = Image.open(fp).convert("RGB").resize((cell - 4, ch - 4), Image.LANCZOS)
+            t = frame_time(fp)
+            label = f"{t:.3f}s" if t is not None else os.path.basename(fp)
+            d = ImageDraw.Draw(im); w = int(d.textlength(label, font=f)) + 12
+            d.rectangle([0, 0, w, f.size + 8], fill=(255, 0, 200)); d.text((6, 3), label, fill=(255, 255, 255), font=f)
+            sh.paste(im, ((i % cols) * cell + 2, (i // cols) * ch + 2))
+        out = base if len(pages) == 1 else f"{stem}-{pi + 1}{ext}"
+        sh.save(out); outs.append(out)
+    print("\n".join(outs))
+
+def cmd_activity(a):
+    start = a.start or 0.0
+    scores, fps = diff_scores(a.video, a.start, a.end, a.region, gray=True, width=320)
+    if not scores: die("no frames")
+    peak = max(scores) or 1.0
+    thr = a.threshold if a.threshold is not None else max(0.15, peak * 0.04)
+    print(f"{len(scores)} frames @ {fps} fps from {start:.2f}s. Motion score = mean pixel change vs previous frame. Threshold {thr:.2f}.\n")
+    print("frame   time    score")
+    for i, sc in enumerate(scores):
+        bar = "#" * int(40 * sc / peak)
+        print(f"{i:5d} {start + i / fps:7.3f}  {sc:6.2f} {bar}")
+    print("\nActive windows (motion above threshold):")
+    i = 0
+    while i < len(scores):
+        if scores[i] > thr:
+            j = i
+            while j + 1 < len(scores) and scores[j + 1] > thr: j += 1
+            print(f"  {start + i / fps:.3f}s - {start + (j + 1) / fps:.3f}s  ({j - i + 1} frames, peak {max(scores[i:j + 1]):.2f} at frame {i + scores[i:j + 1].index(max(scores[i:j + 1]))})")
+            i = j + 1
+        else: i += 1
+    print("\nReading it: a burst that starts high and decays = ease-out; low-high-low = ease in-out; flat plateau = linear. Gaps between bursts = stagger spacing.")
+
+def cmd_compare(a):
+    Image, ImageChops, ImageDraw, _, _ = pil()
+    ref = Image.open(a.reference).convert("RGB"); ours = Image.open(a.ours).convert("RGB")
+    if ours.size != ref.size: ours = ours.resize(ref.size, Image.LANCZOS)
+    W = 960; H = round(W * ref.height / ref.width)
+    panels = [("REFERENCE", ref), ("OURS", ours)]
+    if a.diff: panels.append(("DIFFERENCE (x4)", ImageChops.difference(ref, ours).point(lambda v: min(255, v * 4))))
+    sh = Image.new("RGB", (W * len(panels), H), (36, 36, 36)); f = font(26)
+    for i, (name, im) in enumerate(panels):
+        im = im.resize((W - 4, H - 4), Image.LANCZOS); d = ImageDraw.Draw(im)
+        d.rectangle([0, 0, int(d.textlength(name, font=f)) + 16, 40], fill=(255, 0, 200)); d.text((8, 5), name, fill=(255, 255, 255), font=f)
+        sh.paste(im, (i * W + 2, 2))
+    out = a.out or os.path.join(tempfile.gettempdir(), "ae-recipe-compare.png"); sh.save(out); print(out)
+
+def hexc(rgb): return "#%02X%02X%02X" % tuple(int(round(c)) for c in rgb[:3])
+
+def cmd_color(a):
+    Image, _, _, _, ImageStat = pil()
+    im = Image.open(a.image).convert("RGB")
+    for pt in a.points:
+        x, y = [int(v) for v in pt.split(",")]
+        if a.box > 1:
+            h = a.box // 2; reg = im.crop((max(0, x - h), max(0, y - h), x + h + 1, y + h + 1))
+            c = ImageStat.Stat(reg).mean; print(f"({x},{y}) avg of {a.box}x{a.box}: {hexc(c)}  rgb({c[0]:.0f},{c[1]:.0f},{c[2]:.0f})")
+        else:
+            c = im.getpixel((x, y)); print(f"({x},{y}): {hexc(c)}  rgb{c}")
+
+def cmd_palette(a):
+    Image, _, _, _, _ = pil()
+    im = Image.open(a.image).convert("RGB"); im.thumbnail((200, 200))
+    q = im.quantize(colors=a.n, method=Image.Quantize.MEDIANCUT); pal = q.getpalette()
+    counts = sorted(q.getcolors(), reverse=True); total = sum(c for c, _ in counts)
+    print("dominant colours (share of pixels):")
+    for c, idx in counts: print(f"  {hexc(pal[idx * 3:idx * 3 + 3])}  {100 * c / total:5.1f}%")
+
+def cmd_crop(a):
+    Image, _, _, _, _ = pil()
+    im = Image.open(a.image).convert("RGB").crop((a.x, a.y, a.x + a.w, a.y + a.h))
+    if a.scale != 1: im = im.resize((int(a.w * a.scale), int(a.h * a.scale)), Image.LANCZOS)
+    out = a.out or os.path.join(tempfile.gettempdir(), "ae-recipe-crop.png"); im.save(out); print(out)
+
+def main():
+    p = argparse.ArgumentParser(prog="media", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    s = p.add_subparsers(dest="cmd", required=True)
+    s.add_parser("check").set_defaults(f=cmd_check)
+    x = s.add_parser("info"); x.add_argument("video"); x.set_defaults(f=cmd_info)
+    x = s.add_parser("cuts"); x.add_argument("video"); x.add_argument("--threshold", type=float, default=18.0); x.set_defaults(f=cmd_cuts)
+    x = s.add_parser("frames"); x.add_argument("video"); x.add_argument("--start", type=float); x.add_argument("--end", type=float)
+    x.add_argument("--fps", type=float); x.add_argument("--every-frame", action="store_true"); x.add_argument("--times"); x.add_argument("--width", type=int, default=960); x.add_argument("--out"); x.set_defaults(f=cmd_frames)
+    x = s.add_parser("sheet"); x.add_argument("paths", nargs="+"); x.add_argument("--cols", type=int, default=3); x.add_argument("--cell", type=int, default=640); x.add_argument("--out"); x.set_defaults(f=cmd_sheet)
+    x = s.add_parser("activity"); x.add_argument("video"); x.add_argument("--start", type=float); x.add_argument("--end", type=float); x.add_argument("--region"); x.add_argument("--threshold", type=float); x.set_defaults(f=cmd_activity)
+    x = s.add_parser("compare"); x.add_argument("reference"); x.add_argument("ours"); x.add_argument("--out"); x.add_argument("--diff", action="store_true"); x.set_defaults(f=cmd_compare)
+    x = s.add_parser("color"); x.add_argument("image"); x.add_argument("points", nargs="+"); x.add_argument("--box", type=int, default=1); x.set_defaults(f=cmd_color)
+    x = s.add_parser("palette"); x.add_argument("image"); x.add_argument("--n", type=int, default=6); x.set_defaults(f=cmd_palette)
+    x = s.add_parser("crop"); x.add_argument("image"); [x.add_argument(k, type=int) for k in ("x", "y", "w", "h")]; x.add_argument("--scale", type=float, default=2); x.add_argument("--out"); x.set_defaults(f=cmd_crop)
+    a = p.parse_args(); a.f(a)
+
+if __name__ == "__main__":
+    main()

package/editions/ae/skills/create-ae-recipe/scripts/setup.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Sets up the create-ae-recipe skill's tools: ffmpeg/ffprobe (Homebrew on macOS) and a local venv with Pillow.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+if ! command -v ffmpeg >/dev/null 2>&1 || ! command -v ffprobe >/dev/null 2>&1; then
+  if command -v brew >/dev/null 2>&1; then echo "Installing ffmpeg with Homebrew..."; brew install ffmpeg
+  elif command -v apt-get >/dev/null 2>&1; then echo "Installing ffmpeg with apt..."; sudo apt-get install -y ffmpeg
+  else echo "Install ffmpeg manually (https://ffmpeg.org) and re-run." >&2; exit 1; fi
+fi
+
+if [ ! -x "$HERE/.venv/bin/python" ]; then
+  echo "Creating Python venv at $HERE/.venv"
+  python3 -m venv "$HERE/.venv"
+fi
+"$HERE/.venv/bin/pip" install -q --upgrade pillow
+"$HERE/scripts/media" check

package/editions/ae/skills/create-ae-video/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: create-ae-video
+description: Master guide for making a video in After Effects with Claude ("Create AE Video"). Use at the START of any conversation about making, animating, recreating or editing a video, promo, explainer, title sequence or motion piece in After Effects. Runs a readiness check, does a short discovery, chooses the path (library recipes, new recipes from a description or a reference video, or changing something already in the project), then guides storyboard, build, review and handover by delegating to the use-ae-recipes and create-ae-recipe skills.
+---
+
+# Create AE Video
+
+You are the conductor. You get the user from "I want a video" to finished comps in their After Effects project, with a clear plan, visible progress and approval gates. You stay thin: the heavy lifting is delegated.
+
+| Skill | Use it for |
+|---|---|
+| **`use-ae-recipes`** | Building scenes from the library, tuning, assembling a master comp, reviewing |
+| **`create-ae-recipe`** | Adding a missing look to the library, from a description (iterate with previews) or from a reference video (frame-by-frame breakdown) |
+| this skill | Preflight, discovery, deciding the path, storyboard, status board, gates, handover |
+
+Invoke the others with the Skill tool when you reach their phase; give them the brief and the relevant storyboard row so they don't re-ask. Don't re-run their preflights.
+
+Ground rules (always): you work in the user's **open** project. Create new comps only, never touch existing ones unless asked, **never save** the project, never render the final output (the user does that). Every run is one Undo step. Show images by file path and say what to look for.
+
+## Phase 0: Preflight (first thing, before asking anything)
+
+```bash
+node .claude/skills/create-ae-video/scripts/preflight.js
+```
+
+It checks Node, the Playrig CLI, the library lint, ffmpeg/Pillow, sibling skills, and (live) After Effects + the Playrig panel, the open project, and the Inter fonts.
+
+- Tell the user the result in **3 lines** (ready? what's open? any note).
+- **Blocked?** Give the printed fix, wait, re-run. Typical: After Effects not open, panel not started (Window > Playrig, then Start), media tools missing (`.claude/skills/create-ae-recipe/scripts/setup.sh`), font missing.
+- **Resuming?** If the project is saved and has an `EDIT_LOGS/` folder beside it (older projects: `AE-BRIDGE/`), read its `JOURNAL.md` and `assets.ae.md` to see what earlier sessions did. If comps already exist, ask whether this continues them.
+
+## Phase 1: Discovery (short)
+
+First, one choice question (use AskUserQuestion if available):
+
+1. **New video from my idea/brief**
+2. **Recreate or take inspiration from a reference video**
+3. **Add a new effect/look to my library** → go straight to `create-ae-recipe`, then offer to continue to a video
+4. **Continue or modify something already in the project**
+
+Then collect the brief (template in `references/templates.md`). Ask **at most 5 questions**, only what changes the result: purpose and audience, length and format (default 1920×1080, 24 fps), the words/content, tone and look (light & clean vs dark & technical, brand colours, font), references. Assume the rest and **state the assumptions**. End with a 6-line **brief block** the user can correct.
+
+For a reference video: ask for the file path, then run `create-ae-recipe`'s overview steps (`media info`, `cuts`, contact sheets) to understand it before planning.
+
+## Phase 2: Library fit
+
+Read **only** `<library>/INDEX.md`. Build the **coverage map** (template): each thing the brief needs → matching recipe(s) → `ready` / `planned` / `missing`. Don't open recipe files yet.
+
+For each gap offer: **substitute** with something that exists, **create** it (via `create-ae-recipe`), or **drop** it. Say honestly what's weak. Recommend one option per gap; the user decides.
+
+## Phase 3: Storyboard and gate
+
+Produce the **storyboard** (template): scene, time range, background, content, recipe chain, transition out, plus a **status board**. Keep to one idea per scene, 1.5-4 s each. Total time should match the brief.
+
+**Gate: do not build until the user approves the storyboard** (a quick "go" is enough; trivial single-effect requests skip the table).
+
+## Phase 4: Fill the gaps (only if any)
+
+For each approved gap, run `create-ae-recipe` (one at a time). Each ends with a tested, previewed, indexed recipe. Update the status board after each. If a gap turns out to be expensive, say so and re-offer substitute/drop.
+
+## Phase 5: Build scene by scene
+
+Run `use-ae-recipes` for one scene at a time. After each scene show its preview sheet and get a reaction before the next. Tuning = changing recipe parameters. Update the status board (`planned → built → approved`).
+
+## Phase 6: Assemble and polish
+
+Assemble the master comp (with a structure recipe or a job script) and review the whole timeline on a contact sheet (every 0.25 s). Run a **polish pass** with a checklist: pacing, legibility, consistent palette/type, transition feel, anything clipped or off-screen, first and last frame. Max **2 polish rounds** unless the user wants more.
+
+## Phase 7: Handover
+
+Use the handover template: comps created, per-scene command chains (re-runnable), the parameters most worth tweaking, assumptions, new recipes added to the library, what's still planned, and the reminders: the project is **unsaved** and **not rendered**. Offer next steps (another scene, variations, a vertical version, new recipes for the planned items).
+
+## How to run the conversation
+
+- **Status board.** Keep a compact board (template) and reprint it at each milestone: brief, scenes with status, recipes to create. It is how the user stays oriented.
+- **One decision at a time.** Short messages, concrete options, a recommendation. Never ask what you can sensibly assume.
+- **Show early.** The first visible result should arrive quickly: build the hook scene first.
+- **Change requests are edits, not rebuilds.** New words: `edit-text.jsx`. Different look from a recipe: `playrig ae lib run <id> --replace` with the new params (replaces only that recipe's layers, in place). Rebuilding a whole scene is a last resort and discards the user's manual changes in it.
+- **Direction change** mid-way: update the brief and board, say what it invalidates, continue.
+- **Failures:** read the printed error, fix parameters or ordering; don't retry blindly. If Playrig stops answering, re-run preflight.
+- **Token economy:** index first, then one recipe file at a time; never read recipe scripts to use them; don't re-read what's already in context.
+- **Honesty:** say which recipes are planned, what you approximated, and what you could not verify.
+- **Quality bar:** nothing is "done" until frames were looked at (start, mid, end of motion) and the user reacted to them.
+
+## References
+
+- `references/templates.md`: brief block, question bank with defaults, coverage map, storyboard, status board, handover.
+- Sibling skills: `.claude/skills/use-ae-recipes/`, `.claude/skills/create-ae-recipe/`. Library: `<library>/INDEX.md`, `<library>/README.md`.