fablecut 1.13.0 → 1.15.0

package/CLAUDE.md

@@ -26,12 +26,22 @@ Every Claude Code session then has these tools:
   into `./media/` and register it. The stored `src` is always `/media/…`.
 - `fablecut_analyze_reference` — turn a reference video into an edit blueprint
   (shots, beats, BPM, energy, drop) + extract its music. See "Remake a reference video".
-- `fablecut_encode_profiles` — list export presets from `encoding-profiles.json` (each is a
-  raw ffmpeg args list). Set `project.encodeProfile` via patch to pin a project default.
+- `fablecut_frame` — **look at** a moment and get back an actual image.
+  `{path, t}` returns one frame of a source clip; `{path, frames}` returns a
+  contact sheet across it; with no `path`, `{time}` renders the composed
+  timeline. See "Look at the footage" below.
+- `fablecut_encode_profiles` — list the **delivery presets** (YouTube, Shorts, Reels, TikTok,
+  X, LinkedIn, Master, Broadcast, Web, Archive, saved ones) and the raw ffmpeg **encoding
+  profiles** from `encoding-profiles.json`. `{preset:"youtube"}` returns one preset's spec.
+  See "Export" below.
 - `fablecut_normalize_audio` — measure clips (BS.1770 LUFS or sample peak, via ffmpeg) and
   set their clip gain to a loudness target. See "Audio mix" below.
 - `fablecut_auto_duck` — find where the voice tracks speak and write `duck` keyframes that
   dip the music under it. See "Audio mix" below.
+- `fablecut_frame` — **see** a moment. `{path, t}` → one JPEG frame of a source
+  clip; `{path, frames:12}` → a contact sheet across it; `{time}` → the composed
+  timeline, graded, as export renders it. Returns a real image, not numbers.
+  See "Look at the footage" below.
 - `fablecut_denoise` — reduce background noise on audio clips (renders a cleaned copy of the
   file and switches the clip's stems to it). See "Audio mix" below.
 - `fablecut_export` — render the timeline to a file in `exports/` with the editor's own
@@ -41,6 +51,9 @@ Every Claude Code session then has these tools:
   select. See "Color" and "Masks" below.
 - `fablecut_track` — motion tracking: follow a region of a video clip, store it as
   a track, and make a mask or another clip follow it. See "Tracking" below.
+- `fablecut_proxy` — make, check or delete proxies: light copies of heavy footage
+  the editor plays while editing (export always reads the originals). See
+  "Media management" below.
 
 ### Token-efficient editing (important for agents)
 
@@ -59,8 +72,12 @@ Editing via full get→modify→set costs thousands of tokens per change. Cheape
    Re-check the clips, then retry with that revision.
 3. **Docs**: request `fablecut_docs {section:"schema"}` (or "Recipes", "Remake", …)
    instead of the whole manual; skip it entirely if the schema is already in context.
-4. **Media questions** (duration, fps, size): read them from the registered media
-   entries — don't shell out to ffprobe; the browser probes and writes them back.
+4. **Media questions** (duration, resolution, fps, codec, audio channels, file
+   size, how often it is used): read them from the registered media entries or
+   the compact view's MEDIA lines — don't shell out to ffprobe; the editor
+   probes every file and writes them back (see "Media management").
+   For what the footage *looks like*, use `fablecut_frame` — it is far cheaper
+   than reading a file, and far more reliable than inferring from a number.
 5. Batch related changes into ONE patch call (ops apply in order, one revision bump).
 6. **Cut and trim with the edit ops** (next section) rather than recomputing
    `start` / `in` / `duration` by hand — they keep linked stems in sync.
@@ -133,6 +150,9 @@ reports the real paths.
 Tests (and nothing else) may set **`FABLECUT_NO_FS_WATCH=1`** to skip `fs.watch`.
 On Windows, libuv can abort the process when a file is created under a temp
 data dir. Production leaves watching on so the UI live-reloads.
+Tests may also set **`FABLECUT_NO_AUTOSTART=1`** so `ensureUIServer()` reports
+a missing editor server instead of spawning one — the auto-start is detached,
+so a test that triggers it would leave a `server.js` running after it finishes.
 
 ## Run
 
@@ -177,8 +197,10 @@ Reusable assets, visible in the editor's left-panel tabs and never copied:
 | `library/elements/` | **Elements** | overlay art: alpha PNGs, light leaks, textures, stickers |
 | `library/svg/`      | **SVG**      | animated vector graphics **you author** (convention below) |
 | `library/fonts/`    | font editor  | `.ttf/.otf/.woff/.woff2`, auto-registered, family name = file name; a variable font draws every `weight` |
+| `library/presets/`  | Inspector → Motion → Presets | saved animation presets, one `.json` each (see "Presets and templates") |
+| `library/templates/`| **Templates** | saved templates, one `.json` each, listed after the built-in ones |
 
-- List via `GET /api/library?dir=sfx|elements|svg|fonts` (recursive; subfolders OK).
+- List via `GET /api/library?dir=sfx|elements|svg|fonts|presets|templates` (recursive; subfolders OK).
 - To use one in the timeline, add a media entry whose `src` is its library path,
   e.g. `{ "id":"m_x", "name":"whoosh.mp3", "kind":"audio", "src":"/library/sfx/whoosh.mp3" }`
   — then reference it from clips like any other media.
@@ -252,6 +274,10 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
   "untargetedTracks": [ "V2" ],
   // ^ optional — lanes edits skip (split, insert, ripple, close gap…); default: all targeted
   "encodeProfile": "hq",  // optional — fast-export profile id (see encoding-profiles.json)
+  "delivery": { "preset": "youtube", "width": 1920, "height": 1080, "…": "…" },
+  // ^ optional — the delivery spec exports use by default (see "Delivery presets"); setProject takes a preset id
+  "outputs": [ { "id": "o_1", "on": true, "preset": "master", "…": "…" } ],
+  // ^ optional — batch outputs: files made together, one render per frame rate (see "Batch outputs and the export queue")
   "master": { "gain": -1.5, "fx": [ { "type": "limiter", "ceiling": -1 } ] },
   // ^ optional — master fader, dB (−60 = silence … +12; omit = 0 dB) and master effects (see "Audio mix")
   "tracks": [                          // optional — timeline lanes (default V3…V1 + A1…A4)
@@ -266,11 +292,18 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
     { "id": "A4", "kind": "audio" }
   ],
   "buses": [ { "id": "B1", "name": "Dialogue", "gain": -2, "fx": [ { "type": "compressor" } ] } ],
+  "collections": [ { "id": "col_sel", "name": "Selects", "media": [ "m_abc" ] } ],
+  // ^ optional — Project-bin collections: media grouped across folders; see "Media management"
+  "comps": [ { "id": "lt", "name": "Lower third", "width": 1280, "height": 720, "duration": 5, "clips": [ /* … */ ] } ],
+  // ^ optional — compositions (nested sequences), placed with kind:"comp" clips; see "Compositions (nested sequences)"
   // ^ optional — submix buses B1…B8: name, gain (dB), pan, mute, fx; tracks route in with `out`
   "media": [
     { "id": "m_abc", "name": "intro.mp4", "kind": "video",  // video|audio|image|svg
       "src": "/media/intro.mp4",             // path under ./media or ./library (never a raw https:// URL)
       "duration": 12.4, "width": 1920, "height": 1080,
+      "fps": 29.97, "codec": "h264", "audioCodec": "aac", "audioChannels": 2, "sampleRate": 48000,
+      "size": 45200000, "bitrate": 29300000, // probed from the file (read-only; see "Media management")
+      "favorite": true, "tags": [ "interview", "day 1" ],   // optional: bin organization
       "folderId": null },                    // optional: id of a folders[] entry
     { "id": "m_abd", "name": "intro.denoise-medium.flac", "kind": "audio", "src": "/media/intro.denoise-medium.flac",
       "derivedFrom": "m_abc", "denoise": "medium" }  // a noise-reduced copy of m_abc (see "Audio mix")
@@ -278,8 +311,9 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
   "clips": [
     {
       "id": "c_xyz",             // unique string
-      "mediaId": "m_abc",        // null for kind:"text" and kind:"adjust"
-      "kind": "video",           // video | audio | image | svg | text | adjust
+      "mediaId": "m_abc",        // null for kind:"text", "adjust", "shape", "null" and "comp"
+      "kind": "video",           // video | audio | image | svg | text | adjust | shape | null | comp
+      // kind:"comp" also has "compId" (a comps[] entry) — see "Compositions (nested sequences)"
       "track": "V1",             // Vn…V1 (video) | A1…An (audio); extras via UI +V/+A or tracks[]
       "start": 0,                // timeline position, seconds
       "in": 2.5,                 // offset into source media, seconds (0 for image/svg/text)
@@ -289,10 +323,13 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
       "locked": true,            // OPTIONAL — locked by the user: leave it alone (MCP patch refuses edits)
       "disabled": true,          // OPTIONAL — stays on the timeline, hidden from preview / audio / export
       "unlinked": true,          // OPTIONAL — the user unlinked this clip; never auto-relinked on load
+      "parent": "c_null",        // OPTIONAL — moves, turns and scales with that clip (see "Shapes, nulls and parenting")
       "props": { /* all optional — see the props reference below */ },
       // OPTIONAL — keyframe animation. Times are seconds RELATIVE TO CLIP START.
       // "ease" sits on the DESTINATION keyframe of each segment:
       // linear | ease-in | ease-out | ease-in-out (default ease-in-out).
+      // x and y keys at the same time are a position key; pin / pout on them (px)
+      // are motion-path curve handles (see "Motion paths, motion blur and text on a path").
       "keyframes": {
         "scale":   [ { "t": 0, "v": 1 }, { "t": 5, "v": 1.25, "ease": "linear" } ],
         "opacity": [ { "t": 0, "v": 0 }, { "t": 0.8, "v": 1 } ]
@@ -316,6 +353,9 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
 | `scale` | 1 | |
 | `rotation` | 0 | degrees |
 | `opacity` | 1 | 0–1 |
+| `anchorX`, `anchorY` | 0 | anchor point, px from the picture's centre: the point `x`/`y` place and `rotation`/`scale` turn around |
+| `autoOrient` | false | turn the clip with its direction of travel along its motion path (`rotation` adds on top) |
+| `motionBlur` · `motionBlurSamples` | 0 · 8 | motion blur: shutter angle in degrees (0 = off, 180 = film look, up to 720) · sub-frame samples 2–32 |
 | `blend` | "normal" | how the clip lays over what is under it (see Track mattes and blending) |
 | `matte` · `matteTrack` | — | a track matte (see Track mattes and blending) |
 
@@ -390,6 +430,8 @@ These are quick looks. For real grading use `props.grade` (see "Color" below).
 | `bgColor` `bgOpacity` | "#000", 0 | rounded pill behind each line |
 | `textAnim` | "none" | typewriter · word-pop · word-slide · karaoke · **letter-pop** (per-character entrance; Arabic/Indic auto-fallback to per-word clusters so joined letters shape correctly) · **wave** (looping per-character ride; same shaping fallback) · **bounce** (looping per-word hop) · **shake** (looping jitter) · **clip-reveal** (wipe-mask sweep, per line) · **zoom-in** (scale + opacity settle) · **font-cut** (rhythmically swaps typeface, then settles — see `fontCutSet`) · **rise-mask** (line rises from behind its baseline, lower-third reveal) |
 | `wordRate` | 0.15 | seconds per word (typewriter: /4, letter-pop: /3 per character); also staggers `clip-reveal`/`zoom-in`/`rise-mask` per line |
+| `textPath` | — | set the title along a path: one shape item (`path`, `line`, `ellipse`, `rect`, `polygon`, `star`) whose outline is the baseline; more lines follow on parallel curves below it. See "Motion paths, motion blur and text on a path" |
+| `pathOffset` · `pathAlign` | 0 · "start" | where along the path the text sits (% of its length, keyframable, wraps on closed paths) · which end of the text sits there: start · center · end |
 | `fontCutSet` | (curated) | array of font family names cycled by `font-cut`, e.g. `["Anton","Bebas Neue","Archivo Black","Oswald"]`; each is auto-loaded |
 
 **Title styles (one-tap cohesive looks).** Text clips created in the UI now
@@ -432,7 +474,16 @@ footage. Example: 0.3 s impact shake over everything =
 shows — rect, ellipse, bezier, free-hand; feather, expand, invert, add /
 subtract / intersect, keyframes. See "Masks" below.
 
-**Animatable props** (usable in `keyframes`): x, y, scale, rotation, opacity,
+**Shape layers** (`kind:"shape"`): `props.shapes` (rectangles, ellipses,
+polygons, stars, lines, bezier paths, groups) and `trimStart` / `trimEnd` /
+`trimOffset` (%, a draw-on of every path). **Null objects** (`kind:"null"`)
+never render; other clips are parented to them. See "Shapes, nulls and parenting".
+
+**Comp clips** (`kind:"comp"`, `compId`): a composition placed as one clip — it
+draws like a picture of the comp's size (`fit` defaults to `none`) and its media
+plays and exports. See "Compositions (nested sequences)".
+
+**Animatable props** (usable in `keyframes`): x, y, scale, rotation, opacity, anchorX, anchorY, trimStart, trimEnd, trimOffset, pathOffset,
 volume, pan, duck, speed, brightness, contrast, saturation, hue, blur, grayscale, sepia,
 invert, temperature, tint, vignette, cornerRadius, shake, rgbSplit, grain,
 fontSize, letterSpacing, glow.
@@ -925,6 +976,539 @@ track the screen with Scale and Rotate on and attach the new picture, cropped
 to fit; **a highlight that stays on a UI element** in a screen recording —
 track the button, attach a rect svg.
 
+### Shapes, nulls and parenting
+
+Motion graphics are built from three pieces: **shape layers** (vector shapes
+drawn by the editor, crisp at any size), **null objects** (invisible layers that
+carry a transform) and **parenting** (a clip moves, turns and scales with
+another clip). Every visual clip also has an **anchor point**. All of it runs
+the same in preview and export.
+
+**Shape layers.** A clip with `kind:"shape"` (no `mediaId`) draws
+`props.shapes`, a list drawn bottom-up (first = bottom):
+
+```jsonc
+{ "id": "c_lt", "kind": "shape", "mediaId": null, "track": "V2", "start": 0, "duration": 5,
+  "props": { "x": -300, "y": 220, "shapes": [
+    { "type": "rect", "name": "Bar", "w": 520, "h": 90, "radius": 12, "fill": "#ffd166",
+      "keys": [ { "t": 0, "w": 0 }, { "t": 0.6, "w": 520, "ease": "ease-out" } ] },
+    { "type": "line", "y": 60, "points": [[-260, 0], [260, 0]], "stroke": "#ffffff", "strokeWidth": 6,
+      "keys": [ { "t": 0.3, "trimEnd": 0 }, { "t": 1.1, "trimEnd": 100 } ] },
+    { "type": "group", "x": 300, "items": [
+      { "type": "star", "sides": 5, "inner": 0.45, "w": 80, "h": 80, "fill": "#ff7ac8" },
+      { "type": "ellipse", "w": 120, "h": 120, "fill": "none", "stroke": "#ff7ac8", "strokeWidth": 4 } ],
+      "keys": [ { "t": 0, "rotation": 0 }, { "t": 5, "rotation": 360, "ease": "linear" } ] }
+  ] } }
+```
+
+| key | default | does |
+|---|---|---|
+| `type` | `rect` | `rect` · `ellipse` · `polygon` · `star` · `line` · `path` · `group` |
+| `x` · `y` | 0 | position in layer px, from the layer's origin (the clip's `x`/`y`, y down) |
+| `rotation` · `scale` · `opacity` | 0 · 1 · 1 | about the item's own `x, y` |
+| `w` · `h` | 200 | size, px (rect, ellipse, polygon, star) |
+| `radius` | 0 | rect corner radius, px |
+| `sides` · `inner` | 6 / 5 · 0.5 | polygon / star point count (3–64); a star's inner radius as a fraction of the outer |
+| `points` | — | line: exactly 2 · path: 2–128 points `[x, y]` or `[x, y, inX, inY, outX, outY]` (curve handles relative to the point), px around the item's `x, y` |
+| `closed` | true | path only; `false` leaves it open (lines are always open) |
+| `fill` · `stroke` | `#ffffff` · `none` | `"#rrggbb"`, `"#rrggbbaa"` or `"none"`; lines and open paths default to a white stroke and no fill |
+| `strokeWidth` | 6 (8 open) | px; set with `stroke` |
+| `lineCap` · `lineJoin` | `round` · `round` | `butt` · `round` · `square` / `miter` · `round` · `bevel` |
+| `dash` | — | `[on, off, …]` px, e.g. `[24, 12]` |
+| `trimStart` · `trimEnd` | 0 · 100 | the part of the outline drawn, % — key `trimEnd` 0→100 to draw a path on |
+| `trimOffset` | 0 | % of the outline the drawn part is shifted round by (key it to make a dash run round a loop) |
+| `items` | — | group only: its items. A group moves, turns, scales, fades and trims them together (groups nest 4 deep) |
+| `name` · `on` | — | a label (agents address items by it); `on:false` hides it |
+| `keys` | — | `[{t, ease?, …}]`, `t` in seconds from the clip's start. Keyable: `x y rotation scale opacity w h radius inner strokeWidth trimStart trimEnd trimOffset fill stroke points`. Each value eases between the keys that set it (`ease` on the arriving key); colours blend; `points` keys morph the path and need its point count |
+
+At most 64 items per layer (group children included). The layer itself is a
+normal visual clip: its `x`, `y`, `scale`, `rotation`, `opacity`, `blend`,
+masks, transitions and keyframes all work, as do `blur` and `shake`. Its own
+`trimStart` / `trimEnd` / `trimOffset` (clip props, keyframable) trim every
+path in it at once. A trimmed shape fills the part that is drawn.
+
+**Null objects.** `kind:"null"` (no `mediaId`) is a clip that never renders.
+Give it `x`, `y`, `rotation`, `scale` (and keyframes), and parent clips to it to
+move them as one. The monitor shows it as a red square while it is on screen.
+
+**Parenting.** `"parent": "<clip id>"` (top-level, next to `track`) makes a
+clip move, turn and scale with that clip. Its own `x`/`y` are then measured
+in the parent's space: from the parent's centre, turned and scaled with it.
+Parents chain (a parent can have a parent), and loops are refused. Only the
+transform follows: the parent's opacity, transitions, shake and effects do
+not, and the parent's keyframes are read even outside its time range (held
+at its first or last value). Splitting a parent leaves the children on the
+left half.
+
+**Anchor point.** `anchorX` / `anchorY` (px from the picture's centre, for any
+visual clip) pick the point that `x`/`y` place and that `rotation` and `scale`
+turn around: `anchorY: 200` on a 400 px tall shape spins it about its bottom
+edge. Moving the anchor without moving the picture means changing `x`/`y`
+with it (the editor's anchor tool does that).
+
+In the editor: the bin's **Shapes** tab adds a rectangle, ellipse, polygon,
+star, line or pen-path layer, or a null object, at the playhead. The **Shape layer** section lists the
+items; pick one to edit it — the sliders, Fill / Stroke (colour or **None**),
+ends and joins, trim, **Group** / **Ungroup** / **Out**, ↑ ↓, **Copy**,
+**Delete** — and on the monitor drag it to move, the knob to turn it (Shift:
+15°) and the corners to resize it. On a line or path, drag points and their
+handles (Alt breaks the pair, Alt-drag pulls new handles); on a path,
+Ctrl-click the outline to add a point and double-click one to remove it.
+**Pen** draws a new path: click points (drag to curve), click the first point
+to close it or press Enter to keep it open. Each value has its own **◆**: key
+it at the playhead, and from then on changing it keys it. Every visual clip's
+Transform section has **Anchor** (**✥ Move**: drag on the monitor to move the
+anchor point while the picture stays put, Shift snaps to the centre;
+**Centre** puts it back) and **Parent**. Right-click clips → **Parent to a
+new null** groups them under a fresh null at their centre.
+
+**Agents:**
+
+- Add a layer with `addClip {kind:"shape", track, start, duration, props:{shapes:[…]}}`,
+  a null with `addClip {kind:"null", track, start, duration, props:{x, y}}`.
+- `{op:"setShape", id, set:{type:"rect", w:400, h:80, fill:"#ffd166"}}` adds an
+  item (no `shape`, an index one past the end or a new name adds one; a new
+  item needs `type`). `{op:"setShape", id, shape:"Bar", set:{fill:"#22d3ee"}}`
+  edits one — by index (0 = first), name, or a path into groups like `"2.0"`
+  (item 0 of group 2; `"2.3"` with 3 items adds one there) — merging key by
+  key (`null` resets a key; a new `type` keeps the position and paint).
+  `replace:true` starts it over. `keys` in `set` replaces its keys.
+  `{op:"removeShape", id, shape}` deletes one. `ids:[…]` edits several clips.
+- `{op:"setParent", id | ids, parent:"c_null"}` parents clips and keeps them
+  where they are on screen (at time `at`, default each clip's start; keyed
+  channels are left as they are). `keep:false` keeps the numbers instead.
+  `parent:null` unparents. Removing a parent clip unparents its children
+  where they stand.
+- `props.shapes` and `parent` written through `addClip` / `updateClip` are
+  validated the same way; bad input refuses the whole patch. The compact
+  view lists a layer as `[3 shapes: rect #ffd166 2 keys, line stroke #ffffff/6, group(star(5) #ff7ac8)]`
+  and a child as `parent:c_null`.
+
+Recipes: **draw-on logo** — the logo as `path` items with a stroke and no fill,
+`trimEnd` keyed 0→100 (stagger the items' keys), then `fill` keyed from
+`"#ffffff00"` to `"#ffffff"`; **lower third** — a `rect` bar whose `w` keys
+from 0, a `line` drawn on under it, a title on the track above parented to the
+shape layer so they slide out together; **loading ring** — an ellipse with a
+stroke, `trimEnd: 25`, `trimOffset` keyed 0→100 with `ease:"linear"`;
+**orbit** — a null at the centre with `rotation` keyed 0→360, a shape parented
+to it with `x: 300`; **swing from the top** — `anchorY` at the top edge
+(minus half the height) and `rotation` keyed −10↔10; **burst** — a group of
+lines at different `rotation`s with `scale` keyed 0→1 and `opacity` 1→0.
+
+### Motion paths, motion blur and text on a path
+
+**Motion paths.** When `keyframes.x` and `keyframes.y` both have a key at the
+same time, that is a **position key**. Give position keys curve handles and
+the clip travels along a bezier path between them instead of a straight line.
+The handles are `pin` (arriving) and `pout` (leaving) on the x and y keys,
+in px relative to the key's position, in the clip's `x`/`y` space:
+
+```jsonc
+"keyframes": {
+  "x": [ { "t": 0, "v": -450, "pout": 250 }, { "t": 2, "v": 0, "pin": -250, "pout": 250 }, { "t": 4, "v": 450, "pin": -250 } ],
+  "y": [ { "t": 0, "v": 150, "pout": -300 }, { "t": 2, "v": 0 },                        { "t": 4, "v": 150, "pin": -300 } ]
+}
+```
+
+Between two position keys the clip moves along the curve at the pace of the
+arriving key's `ease`, measured along the curve, so a `linear` key gives an
+even speed around a bend. A segment with an extra x or y key inside it, or
+with no handles, runs the channels as before. `autoOrient: true` turns the
+clip to face its direction of travel, and its `rotation` adds on top. A
+parent on a curved path carries its children along it.
+
+**Motion blur.** `motionBlur` is a shutter angle: the clip is drawn at
+`motionBlurSamples` moments across `motionBlur / 360` of a frame, centred on
+the frame, and the samples are averaged. 180 is the film look; 360 smears a
+whole frame. It blurs whatever changes: position, scale, rotation, a parent's
+motion, keyed shapes and trims. A clip that does not move draws once. During
+playback the preview uses as many samples as fit in the frame time (all of them
+on a fast machine); a paused frame and export always use them all. It works on
+video, image, svg, text and shape clips.
+
+**Text on a path.** `textPath` on a text clip is one shape item (`path`, `line`,
+`ellipse`, `rect`, `polygon` or `star`, with the same geometry keys and
+`keys` as in "Shapes, nulls and parenting", but no paint or trim) whose
+outline is the baseline, in the title's own px. The first line of text runs
+along it, each letter turned with the path; each further line (`\n`) runs on a
+parallel curve one line-height below, so its letters space by that curve's own
+length. `pathOffset` (% of the path's length, keyframable) is where the text
+sits, and `pathAlign` says which end of each line sits there. On a closed path
+the text wraps around; keying `pathOffset` 0 → 100 sends it once around a
+circle. Every text animation plays along the path. Font, size, colour,
+gradient, stroke, glow, shadow, `lineHeight` and `letterSpacing` all apply;
+text boxes and `align` do not (`pathAlign` takes their place).
+
+```jsonc
+{ "kind": "text", "props": { "text": "AROUND AND AROUND • ", "font": "Anton", "fontSize": 40, "letterSpacing": 4,
+  "textPath": { "type": "ellipse", "w": 300, "h": 300 }, "pathAlign": "start" },
+  "keyframes": { "pathOffset": [ { "t": 0, "v": 0 }, { "t": 6, "v": 100, "ease": "linear" } ] } }
+```
+
+In the editor: when the selected clip has two or more position keys, its path
+shows on the monitor: the curve, a dot per frame (their spacing is the speed),
+a square per key and the keys' handles. Drag a key to move it, drag a handle to
+bend the path (Alt breaks the pair), Alt-drag a key to pull new handles, and
+double-click a key to make it a corner again. Moving the clip on the monitor
+or typing X / Y keys both channels together. The Inspector's **Motion**
+section has **Smooth** (handles through every position key), **Straight**,
+**Auto-orient**, **Motion blur** and **Blur samples**. A title's **Text path**
+section sets it on a **Line**, **Arc**, **Circle**, **Wave** or a **Pen** path
+(click points, drag to curve, Enter to finish, click the first point to close
+it). **Edit path** shows the path's points on the monitor, and **Offset** and
+**Align** place the text along it.
+
+**Agents:**
+
+- Write `pin` / `pout` on x / y keys directly, or
+  `{op:"setMotionPath", id | ids, path:"smooth" | "straight", autoOrient?: true}`.
+  `"smooth"` needs the position keys first (x and y keyed together at two or more times).
+- Motion blur: `updateClip` with `props:{motionBlur:180, motionBlurSamples:12}`.
+- `{op:"setTextPath", id | ids, path:"line" | "arc" | "circle" | "wave" | {type:"path", points:[…], closed:false, …} | null, offset?, align?}`
+  sets, replaces or removes (`null`) a title's path; animate `pathOffset` with
+  keyframes.
+- These are validated on `addClip` / `updateClip` too. The compact view shows
+  `path:curved` after a clip's keyframes, and a title's `"textPath":"ellipse 300×300"`.
+
+Recipes: **fly-in on a curve** — two position keys, `setMotionPath` smooth,
+`autoOrient:true`, `motionBlur:180`; **orbiting label** — circle `textPath`,
+`pathOffset` keyed 0 → 100 linear; **stamp along a road** — an open `path`
+textPath that follows the shape in the footage, `pathAlign:"center"`,
+`textAnim:"letter-pop"`; **whip without the transition** — a fast `x` move over
+4–6 frames with `motionBlur:360`.
+
+### Compositions (nested sequences)
+
+A **composition** (comp) is a timeline of its own, with its own size, length,
+tracks and clips, that is placed on the main timeline (or inside another comp)
+as one clip. Build a lower third, a logo sting or a whole scene once, then use
+it as many times as you like: every clip that shows the comp changes when the
+comp is edited. Comps live in `project.comps`:
+
+```jsonc
+"comps": [
+  { "id": "lt", "name": "Lower third", "width": 1280, "height": 720, "duration": 5,
+    "background": "#00000000",   // optional; leave it out for transparent
+    "tracks": [ { "id": "V2", "kind": "video" }, { "id": "V1", "kind": "video" }, { "id": "A1", "kind": "audio" } ],
+    "clips": [
+      { "id": "bar", "kind": "shape", "track": "V1", "start": 0, "duration": 5, "props": { "shapes": [ … ] } },
+      { "id": "name", "kind": "text", "track": "V2", "start": 0.3, "duration": 4.7, "props": { "text": "Ada Lovelace" } },
+      { "id": "whoosh", "kind": "audio", "mediaId": "m_whoosh", "track": "A1", "start": 0, "in": 0, "duration": 0.6 }
+    ] }
+],
+"clips": [
+  { "id": "c_lt1", "kind": "comp", "compId": "lt", "mediaId": null, "track": "V3", "start": 4, "in": 0, "duration": 5,
+    "props": { "fit": "none", "y": 220 } }
+]
+```
+
+| key | default | does |
+|---|---|---|
+| `id` · `name` | — · the id | how clips and agents refer to it · the label shown on its clips and in the bin |
+| `width` · `height` | the project's | the comp's frame, px (16…8192) |
+| `duration` | — | seconds; what the comp shows past its clips is transparent (or its `background`) |
+| `background` | none | a colour behind the comp's clips; leave it out for transparent |
+| `tracks` | V3…V1, A1, A2 | the comp's own lanes, like the project's `tracks` |
+| `clips` | [] | ordinary clips of any kind (comp clips too), with times inside the comp |
+| `template` | — | set on a placed template: `{id, hold, fields}` (see "Presets and templates") |
+
+**A comp clip** (`kind:"comp"`, `compId`, no `mediaId`) shows the comp from its
+`in` (comp seconds) for its `duration`, at speed 1. It draws like a picture of
+the comp's size: `fit` defaults to `none` (the comp's own pixels), and its
+transform, keyframes, opacity, transitions, masks, track matte, blend, grade and
+filters all apply to the comp's frame as a whole. Trims and splits move its
+`in` like a video clip's; the window can't run past the comp's length.
+
+The media inside a comp **plays and exports as if it were on the timeline**:
+its video frames, and its audio, which goes through the main timeline's audio
+track of the same name (its fader, effects and bus). A comp clip that is
+disabled, or sits on a disabled track, silences the comp's audio too. Comps
+nest up to 4 deep, and a comp can never contain itself.
+
+In the editor: the bin's **Project** tab lists the comps; drag one onto the
+timeline to place it, and double-click it (or a comp clip, or **Open** in the
+Inspector's **Composition** section) to open it. An open comp takes over the
+timeline: every tool, shortcut and inspector works on its clips, and the
+breadcrumb above the timeline (or **Esc**, once nothing is selected) goes back
+out. Right-click clips → **Precompose** moves them into a new comp and puts a
+comp clip in their place; right-click the Project tab → **New composition**
+starts an empty one. The Composition section also sets the comp's name, size,
+length and background.
+
+**Agents:**
+
+- `{op:"addComp", comp:{id?, name, duration, width?, height?, background?, tracks?, clips?:[…]}}`
+  adds one (its clips go through the same checks as `addClip`).
+  `{op:"updateComp", id, set:{name?, width?, height?, duration?, background?, tracks?}}`
+  changes it; `{op:"removeComp", id}` is refused while a clip still uses it.
+- Place it with `addClip {kind:"comp", compId, track, start, duration, in?}`.
+- `{op:"inComp", comp, ops:[…]}` runs clip and timeline ops on the comp's own
+  clips: `addClip`, `updateClip`, `removeClip`, `split`, `rippleDelete`, the
+  trims, `setShape`, `setMask`, `setGrade`, `setParent`, `setMotionPath`,
+  `setTextPath`, clip `setFx`, `precompose`, and `inComp` for a comp inside it.
+- `{op:"precompose", ids:[…], name?, id?}` moves those clips (here, or in the
+  comp an `inComp` is running in) into a new comp that starts at the earliest
+  of them; a comp clip of the same length takes their place.
+- The compact view shows a comp clip as `comp(lt in:1.5)` and lists every comp
+  under `COMPS` with its clips.
+
+Recipes: **reusable lower third** — a template (next section) gives every
+speaker their own copy with their own name; a plain comp suits a graphic that
+is the same every time; **logo sting** — a draw-on logo comp at the head and tail of the edit;
+**picture in picture of a whole scene** — precompose the scene's clips, then
+scale the comp clip down and move it into a corner;
+**one grade for a sequence** — precompose it and grade the comp clip once.
+
+### Presets and templates
+
+Two ways to reuse motion: an **animation preset** keys a named animation onto a
+clip, and a **template** is a ready-made comp (lower third, logo animation,
+social layout) whose text, colours and pictures are **fields** you fill in.
+
+**Presets.** A preset keys the clip's own channels, relative to where the clip
+already is: `scale` and `opacity` multiply the clip's value and everything else
+adds to it, so "Slide up" works wherever the clip sits and however big it is.
+Each has an anchor: **in** plays from the clip's start and settles on its
+values, **out** starts from them and ends at the clip's end, **at** is an
+emphasis at a time you pick (the playhead, or `at`), and **loop** spans the
+whole clip. Keys already in the window a preset covers are replaced; the rest
+stay, so an In, an Out and a loop on another channel live side by side.
+
+| group | presets |
+|---|---|
+| In | `fade-in` · `pop-in` · `slide-up-in` · `slide-down-in` · `slide-left-in` (from the right) · `slide-right-in` (from the left) · `drop-in` · `zoom-in` · `spin-in` · `whip-in` (with motion blur) · `rise-blur` · `draw-on` (shape layers) |
+| Out | `fade-out` · `pop-out` · `slide-up-out` · `slide-down-out` · `slide-left-out` · `slide-right-out` · `zoom-out` · `spin-out` · `whip-out` · `sink-blur` · `draw-off` |
+| At (emphasis) | `pulse` · `shake` · `wobble` · `bounce` · `flash` |
+| Loop | `float` · `breathe` · `sway` · `spin` · `wiggle` |
+
+Every In / Out / At preset is 0.35–1 s long; `length` stretches it (a clip
+shorter than the preset squeezes it in). A saved preset is a JSON file in
+`library/presets/`, shared by every project:
+
+```jsonc
+{ "id": "fly-in", "name": "Fly in", "group": "Saved", "anchor": "in", "length": 0.6,
+  "keys": { "x": [ { "t": 0, "v": -500 }, { "t": 0.6, "v": 0, "ease": "ease-out" } ],
+            "opacity": [ { "t": 0, "v": 0 }, { "t": 0.3, "v": 1 } ] },
+  "props": { "motionBlur": 180 } }   // optional: motionBlur, motionBlurSamples
+```
+
+`t` is seconds into the preset (for a loop, 0…1 of the clip). Channels: `x y
+scale rotation opacity blur anchorX anchorY trimStart trimEnd trimOffset
+brightness saturation hue grayscale shake rgbSplit glow fontSize letterSpacing
+pathOffset`.
+
+**Templates.** Placing one adds its own comp (so two lower thirds can show two
+names) and a comp clip showing it with `fit:"contain"`; a template made for
+another shape than the canvas sits inside it, letterboxed. The comp carries
+what makes it a template:
+
+```jsonc
+{ "id": "comp_x1", "name": "Lower third — Bar", "width": 1920, "height": 1080, "duration": 5, "clips": [ … ],
+  "template": { "id": "lower-third-bar", "hold": 4.5, "fields": [
+    { "key": "name", "label": "Name", "type": "text", "targets": [ "name:props.text" ], "value": "Ava Moreno" },
+    { "key": "accent", "label": "Accent", "type": "color", "targets": [ "bar:props.shapes.1.fill" ], "value": "#ffd166" } ] } }
+```
+
+| template | name | size | length | fields |
+|---|---|---|---|---|
+| `lower-third-bar` | Lower third — Bar | 1920×1080 | 5 s | `name` `title` `accent` `panel` |
+| `lower-third-underline` | Lower third — Underline | 1920×1080 | 5 s | `name` `title` `accent` |
+| `lower-third-boxes` | Lower third — Boxes | 1920×1080 | 5 s | `name` `title` `accent` `box` |
+| `logo-ring` | Logo — Ring reveal | 1920×1080 | 4 s | `logo` `brand` `accent` |
+| `logo-slam` | Logo — Slam | 1920×1080 | 3.5 s | `logo` `accent` |
+| `logo-lines` | Logo — Lines | 1920×1080 | 4 s | `logo` `tagline` `lines` |
+| `social-story` | Story — Headline (9:16) | 1080×1920 | 6 s | `headline` `subline` `button` `accent` `background` |
+| `social-quote` | Post — Quote (1:1) | 1080×1080 | 6 s | `quote` `author` `accent` `background` |
+| `social-end-card` | End card — Follow (16:9) | 1920×1080 | 6 s | `heading` `button` `accent` `background` |
+
+Field types: `text` (a string), `color` (`#rgb`, `#rrggbb` or `#rrggbbaa`) and
+`media` (a media id of a picture: image, svg or video; the clip's kind follows
+it). A target is `"<clip id>:<path>"` inside the comp (`props.text`,
+`props.shapes.1.fill`, `mediaId`, …) or `"comp:background"`; one field can set
+several. The logo templates start with a placeholder,
+`/library/elements/logo-placeholder.svg`, until the `logo` field gets a
+picture. **`hold`** is when the exit starts: changing a template's length
+keeps everything after it at the same distance from the end, so a longer lower
+third just holds longer (it can't get shorter than its entrance needs).
+
+A saved template (`library/templates/<id>.json`) is a template object:
+`{id, name, group, width, height, duration, hold, background?, tracks?, clips,
+media?, fields}`; `media` lists the `{id, name, kind, src}` entries its clips
+use (`/library/…` or `/media/…`), matched by `src` when it is placed. A saved
+preset or template whose name a built-in already has is saved as
+"<name> (saved)".
+
+In the editor: the bin's **Templates** tab lists them by group (Lower thirds,
+Logo animations, Social, then Saved); drag one onto the timeline or click ＋.
+The Inspector's **Template** section on its clip edits the fields, its
+**Length**, and offers **Use W×H canvas** when the template was made for
+another shape. Right-click a comp in the Project tab → **Save as template**
+keeps it (every title's text and every picture become fields). The
+**Motion** section's **Presets** menus (In, Out, At playhead, Loop) put a
+preset on the selected clips, and **Save as preset** keeps this clip's
+keyframes (In: from its start to its last key; Out: from its first key to its
+end; Loop: the whole clip).
+
+**Agents:**
+
+- `{op:"applyPreset", id | ids, preset, length?, at?}` — `preset` is a name,
+  a saved one's id, or an inline preset object; `at` is timeline seconds (for
+  an At preset; default the clip's start). Visual clips only.
+- `{op:"addTemplate", template, start?, track?, duration?, fields?:{key: value}, id?, compId?, name?}`
+  places one (default track V2, at 0, its own length).
+- `{op:"setTemplate", id, fields?:{key: value}, duration?}` — `id` is its comp
+  clip or its comp; a new `duration` retimes it, and clips that showed it to
+  its end keep doing so.
+- `{op:"savePreset", id, name, anchor?, from?, to?}` (`from`/`to` in clip
+  seconds) or `{op:"savePreset", preset:{…}}`; `{op:"saveTemplate", comp,
+  name?, fields?, hold?}` or `{op:"saveTemplate", template:{…}}`. Files are
+  written once the patch is saved, and later ops in the same patch can use them.
+- `applyPreset`, `addTemplate` and `setTemplate` also run inside `inComp`.
+- The compact view prints a placed template's fields under its comp:
+  `template lower-third-bar — fields (setTemplate): name="Ava Moreno" …`.
+
+Recipes: **name every speaker** — `addTemplate lower-third-bar` once per
+speaker with `fields:{name, title}`; **branded intro** — `addTemplate logo-ring`
+with `fields:{logo:"<your logo's media id>", brand, accent}` at 0;
+**vertical teaser** — set the canvas to 1080×1920, `addTemplate social-story`;
+**house style** — build a comp the way you like it, `saveTemplate`, then place
+it in every project; **titles that arrive and leave the same way** —
+`applyPreset` an In and an Out on every title in one patch.
+
+### Media management
+
+The Project bin knows each file's details and helps find, group and track
+footage. Everything here is organization: none of it changes what plays or
+exports.
+
+**Metadata.** The editor reads every file in `media/` and `library/` with
+ffprobe (via `GET /api/media-info`) and writes what it finds onto the media
+entry. These fields are read-only — they describe the file:
+
+| key | does |
+|---|---|
+| `fps` | video frame rate (29.97, 25, 59.94 …); absent for stills and audio |
+| `codec` | video codec (`h264`, `hevc`, `prores`, `vp9` …), or the image format (`png`, `mjpeg`) |
+| `audioCodec` · `audioChannels` · `sampleRate` | first audio stream: codec, channel count (`0` = the file has no audio), Hz |
+| `size` · `bitrate` | file size in bytes · overall bitrate, bits per second |
+| `width` · `height` · `duration` | as before; filled in when missing (phone footage shot rotated reports its upright size) |
+
+Without ffprobe on PATH only `size` is filled in; the browser still probes
+`duration`, `width` and `height`.
+
+**Organizing.** `favorite: true` stars a file; `tags` is a list of free-form
+labels (at most 24, each up to 32 characters, matched without regard to case).
+`collections` at the top of the document group media across folders — a file
+can be in any number of them, while it sits in one folder (`folderId`).
+
+**Usage.** A file's *placements* are the clips that show it, on the main
+timeline and inside every composition. A video and the audio stems linked to it
+count as one placement, so a shot used twice reads "used 2×".
+
+In the editor, the Project tab has:
+
+- **Search** — every word must match the name, kind, extension, codec,
+  resolution (`3840x2160`, `2160p`) or a tag; `#word` matches tags only. Esc clears it.
+- **Show** — All media · ★ Favorites · Used in the edit · Unused · a kind · a
+  collection · a tag. While searching or filtering, the bin lists the hits flat
+  (each with its folder), with a count and **Clear**; a collection's view also
+  has **Rename** and **Delete** (its media stay).
+- **Sort** — name (natural: `shot 2` before `shot 10`), kind, duration,
+  resolution, frame rate, codec, audio channels, file size or times used, with
+  ↑ / ↓. Files missing a value sort last either way. Folders keep their tree;
+  the sort applies inside each.
+- **☰ List view** — one row per file with columns: name, duration, resolution,
+  FPS, codec, audio, size and uses; click a column heading to sort by it. On a
+  narrow bin the columns drop out right to left; widen the panel to see them all.
+- On each file: **☆** stars it, the **uses** badge opens its placements.
+  Right-click a file → **Open in Source**, **Find timeline instances** (every
+  placement, main timeline and comps, with track and time — click one to jump
+  there, opening its comp if needed), **Media info…**, favorites, **Tags…**,
+  **Add to / Remove from** a collection, **New collection…**, **Remove from project**.
+- Right-click a clip on the timeline → **Reveal in project** scrolls the bin to
+  its file (or its comp), opening folders and clearing a search that hides it.
+
+**Offline media.** A file is *offline* when its `src` names nothing under
+`media/` or `library/` — it was moved, renamed or deleted. The editor checks
+on load and whenever those folders change. An offline file's clips stay where
+they are: the timeline hatches them red (**⚠ Offline**), the monitor and the
+export draw a **Media offline** slate in the picture's place, and its audio is
+silent. The bin marks the file **OFFLINE**, says how many are missing, and the
+Show filter gains **⚠ Offline**. The Export dialog warns before rendering one.
+Files under `media/` may sit in subfolders (`/media/archive/a.mp4`).
+
+- **Relink** points a media entry at the same footage where it is now; clips
+  keep their In points, edits and everything else. Right-click the file →
+  **Relink…** (or **Relink…** on the offline banner for all of them). The
+  dialog looks through `media/` and `library/` for each file — same name, the
+  same name with another extension, a similar name, the same size — and
+  picks a same-name match for you. **Browse…** picks one file and **Choose
+  folder…** matches a whole folder by name; either copies the chosen files
+  into `media/`. A relinked file whose length differs from the original gets
+  a warning (is it really the same footage?).
+- **Replace file…** (right-click a file) puts a *different* file behind the
+  media entry — a new render, a better take. Every clip using it switches;
+  each keeps its In point and timing, trimmed to fit a shorter file. The name
+  and details follow the new file; favorites, tags and collections stay. To
+  swap the file of one clip only, use the Inspector's **Source** menu instead.
+- Relink and replace are one undo step each.
+
+**Proxies.** Heavy footage — 4K, HEVC, ProRes, long phone clips — can stutter
+while you scrub and play. A *proxy* is a light copy the editor plays instead
+while you edit: H.264 at 540p (or 720p / 1080p, never larger than the
+source), a keyframe every 12 frames so seeking is quick, the source's own
+timestamps (frame for frame — no frames added or dropped) and its first audio
+stream. The edit always refers to the original: the timeline, `project.json`
+and every clip stay the same whether proxies are on or off.
+
+**Export always reads the originals**, and so do `fablecut_frame` (timeline
+mode), `fablecut_scopes`, tracking and every other measurement — the
+players switch to the original files for the render and back afterwards. A
+proxy only changes how smoothly the preview runs, never the result.
+
+- Right-click a video in the bin → **Create proxy (540p)** / **(720p)**;
+  right-click the **Project** tab → **Create proxies for N videos**. ffmpeg
+  makes them on the server one at a time in the background; the bin shows
+  each file's progress (**P 42%**), then a green **P** once it is ready.
+  **Delete proxy** removes one. The bin's list view has a **Proxy** column,
+  Show has **Has a proxy** / **Video without a proxy**, and **Media info**
+  says which file is playing.
+- The monitor's **Proxy** button turns proxy playback on and off (on by
+  default; remembered in this browser). The Source monitor follows it too.
+- Proxies live in `analysis/proxies/`, a disposable cache: each is named
+  after its source file *and that file's size and modification time*, so a
+  re-rendered or replaced original simply has no proxy until you make a new
+  one. Deleting the folder loses nothing but time. Proxies need ffmpeg.
+
+**Agents:**
+
+- `{op:"updateMedia", id | ids, set:{name?, favorite?, tags?, folderId?}, addTags?, removeTags?}`
+  — organize files (`favorite:false` unstars; `tags:[]` clears). Metadata keys
+  are refused: they come from the file.
+- `{op:"setCollection", id?, name?, media?, add?, remove?}` creates a collection
+  (a new `id`, or a `name` no collection has) or changes one: `media` replaces
+  its list, `add` / `remove` edit it. `{op:"removeCollection", id}` deletes it;
+  its media stay. `removeMedia` takes a file out of every collection.
+- The compact view lists each file with its metadata, ★, tags, folder and
+  `uses:N`, and the collections on one line:
+  `m_abc video "intro.mp4" 12.4s 1920×1080 29.97 fps h264 stereo 48 kHz 45 MB ★ #interview uses:2`.
+- `fablecut_import_media` probes the file as it imports it, so the entry it
+  returns already has these fields.
+- `fablecut_status` lists offline media, and the compact view marks each
+  `OFFLINE (file missing — relinkMedia)` and each video with a proxy `proxy:540p`.
+- `fablecut_proxy {}` reports every video's proxy; `{create:true, mediaIds?, height?}`
+  makes them (waits until done unless `wait:false`); `{delete:true, mediaIds?}`
+  removes them. Proxies never change what you measure or export, so an agent
+  only needs them when the user asks for smoother playback.
+- `{op:"relinkMedia", id, src:"/media/…", name?}` — the same footage found
+  elsewhere: put the file in `media/` (copy it, or `fablecut_import_media` and
+  `removeMedia` the extra entry it registers), then relink. The note warns when
+  the new file's length differs.
+- `{op:"replaceMedia", id, src, name?}` — a different file behind the entry;
+  clips keep their timing, trimmed to fit (the note says how many). `src` must
+  be an existing file under `/media/` or `/library/` of the same kind (an
+  audio entry may use a video container).
+
 ### Semantics
 
 - Rendering order: V1 is drawn first, then V2, V3, … on top. SVG/image/text clips
@@ -1020,6 +1604,44 @@ track the button, attach a rect svg.
 - `bgRemove` and `chromaKey` can combine with all filters; heavy pixel work is
   automatic (only runs when those props are set).
 
+## Look at the footage (`fablecut_frame`)
+
+`fablecut_analyze_reference` gives you the **ears** — where the cuts are, how hard
+each shot hits. `fablecut_frame` gives you the **eyes**. It answers with a real
+image (an MCP `image` content block), so you can judge a shot instead of
+inferring it from an `energy` value.
+
+| call | returns |
+|---|---|
+| `{path:"/media/x.mp4", t:3.2}` | that exact frame |
+| `{path:"/media/x.mp4", frames:12}` | a 4×3 contact sheet across the whole clip |
+| `{path:"/media/x.mp4", frames:12, from:30, to:90}` | a contact sheet across part of it |
+| `{time:8.5}` (no `path`) | the **composed timeline** at 8.5 s, graded, all tracks |
+| `{path}` with an absolute path | the file is read in place without copying into `media/` |
+| `{path, text:true}` | text-only statistics (luma, colors, texture, saturation, motion) for non-vision agents |
+
+Each answer leads with a text line naming the source, the timestamp(s) and (in
+timeline mode) the clips on screen, so you always know what you are looking at.
+`width` sets the pixel width (default 768 for one frame, 320 per contact-sheet
+cell); `text:true` returns descriptive statistics instead of an image block, for
+agents without vision capability — luma levels (min, p1, median, mean, p99, max,
+all 0–1 like `fablecut_scopes`), dominant colors, texture, saturation and
+per-cell motion; `where`/`timeout` apply to timeline mode only.
+
+The REST endpoint `/api/frame` accepts `src`, `t`, `frames`, `from`, `to`, `w`,
+`q` (JPEG quality 1–31) and `text=1` (statistics mode) as query parameters.
+
+**When it pays.** Before choosing a clip's `in` point, sample a few candidate
+moments — the blueprint tells you a shot spans 2.1 s–4.9 s and reads
+`energy: 88`, but only a frame tells you whether that is a car jump or a pan
+across a landscape. Contact sheets are the cheap survey: one call shows you
+what a whole 3-minute clip holds, then you grab single frames where it matters.
+Timeline mode answers "what did I actually build?" — the same picture the user
+sees and export renders, grades and transitions included.
+
+Needs ffmpeg on PATH for the source modes. Timeline mode runs in the open editor
+tab, else a headless browser, like `fablecut_export`.
+
 ## Remake a reference video (analyze → blueprint → rebuild)
 
 Given a reference edit (a reel/montage the user likes), FableCut can analyze it
@@ -1059,6 +1681,8 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
    (hard cuts by default — that's what shot detection saw). Pick source footage
    whose motion matches each shot's `energy` (calm ≤40, action ≥70), and choose
    each clip's `in` so something interesting happens inside the window.
+   **Then look**: `fablecut_frame {path, frames:12}` to survey a candidate clip,
+   `{path, t}` at the exact moment you want, before committing to an `in`.
 4. The `drop`: put the hero shot there; classic garnish = a speed ramp landing
    on it, an impact `adjust` layer (shake+rgbSplit), or a whip transition.
 5. Pacing garnish to taste: shots shorter than ~0.6 s read as beat-flashes;
@@ -1074,7 +1698,27 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
   Append `?force=1` to overwrite unconditionally. Writes are atomic (tmp file +
   rename), so a crashed write never corrupts the file.
 - `GET  /api/media`   — list files in ./media (name, src, size)
-- `GET  /api/library?dir=sfx|elements|svg|fonts` — list library assets
+- `GET  /api/media-info?src=/media/x.mp4` → `{src, info}` · `POST /api/media-info {srcs:[…], stat?}` →
+  `{info:{src: info}}` (up to 2000; `stat:true` answers only `{size, mtimeMs}`, no ffprobe —
+  how the editor checks for offline files) — a file's metadata from ffprobe: `size`, `fps`, `codec`,
+  `audioCodec`, `audioChannels`, `sampleRate`, `bitrate`, `duration`, `width`, `height` and
+  `probe` (`"ffprobe"`, or `"stat"` when only the size could be read). `info` is `null` when
+  the src names no file under `/media/` or `/library/`. Cached per file version.
+- `POST /api/proxy {srcs:[…], height?:540|720|1080}` → `{status:{src: status}}` queues proxies
+  (ffmpeg, one at a time); `POST /api/proxy/status {srcs}` → `{status:{src: status | null}}`;
+  `POST /api/proxy/delete {srcs}` → `{deleted:{src: n}}`. A status is
+  `{state:"ready", src:"/proxies/…", width, height, size}`, `{state:"queued"|"running", progress, height}`,
+  `{state:"failed", error}` or `{state:"none"}` (`null` = no such source file). Progress and
+  results are also pushed as SSE event `proxy` (`{src, status}`). `GET /proxies/<name>` serves
+  a proxy file from `analysis/proxies/`. `/api/proxy` answers 503 without ffmpeg.
+- `POST /api/relink/candidates {media:[{id, name, src?, size?, kind?}]}` →
+  `{candidates:{id:[{src, name, size, score, why}]}}` — where a missing file might be now:
+  files under `media/` and `library/` (subfolders included) of the same kind, ranked by
+  name (same name, same name with another extension, similar name) and size, best 5 each.
+- `GET  /api/library?dir=sfx|elements|svg|fonts|presets|templates` — list library assets
+- `GET  /api/presets` · `GET /api/templates` — the saved presets / templates, validated (bad files skipped);
+  `POST /api/presets {preset}` · `POST /api/templates {template}` — validate one and save it as
+  `library/presets/<id>.json` / `library/templates/<id>.json`, returning `{id, name, file}`
 - `POST /api/upload?name=foo.mp4` — raw body saved into ./media, returns `{src}`.
   MP4/MOV/M4V uploads are auto-remuxed with `+faststart` (needs ffmpeg on PATH).
   Files copied straight into ./media by external tools skip this — remux big ones
@@ -1096,9 +1740,27 @@ obvious cuts were missed, raise it if motion is being misread as cuts.
 - `POST /api/analyze` — body `{src:"/media/ref.mp4", threshold?, music?}`: analyze a
   reference video into an edit blueprint (see "Remake a reference video"); extracts
   its music into ./media. `GET /api/analyze?src=…` returns the cached blueprint.
+- `GET  /api/frame?src=/media/x.mp4&t=3.2` — one JPEG still of a source clip, the
+  "eyes" to go with `/api/analyze`'s ears (see "Look at the footage"). Optional
+  `w` (pixel width, default 768) and `q` (ffmpeg `-q:v` 1–31, default 4).
+  `&frames=N[&cols=][&from=][&to=][&w=320]` instead returns one N-up **contact
+  sheet** across the clip (N 2–60; `cols` omitted → the squarest layout, so 6
+  frames give 3×2 rather than 4×2 with two black cells). `src` must name an
+  existing file under `/media/` or `/library/` (404 otherwise). `?path=` reads
+  any file on the machine but only with the `X-FableCut-Client: mcp` request
+  header, which only the local MCP client sends — without it the request is
+  refused (403) before the path is even resolved. Results are cached in
+  `analysis/frames/` keyed by source path, size and mtime; the cache is capped
+  (500 files / 128 MB, oldest first). The response carries
+  `X-FableCut-Frame-Times` (comma-separated sample times, so a sheet's cells can
+  be mapped back to timestamps) and `X-FableCut-Frame-Source`.
+- `POST /api/scopes/request` also takes `{"image":true}`, which makes the editor
+  return the measured still as a JPEG data URL in `result.image` — how
+  `fablecut_frame {time}` shows an agent the composed program picture.
 - `GET  /api/events`  — SSE: named event `change` when project.json, ./media or
   ./library changes; named event `profiles` when `encoding-profiles.json` changes
-  (UI refreshes the export-profile list only — no project reload)
+  (UI refreshes the export-profile list only — no project reload); named event
+  `proxy` as a proxy is queued, makes progress, finishes or is deleted
 - Fast / WebCodecs export (browser compositor → server ffmpeg):
   `GET /api/export/ffmpeg` → `{available}` · `GET /api/export/profiles[?detail=1]` →
   `{default, profiles, issues}` · `POST /api/export/begin`
@@ -1341,12 +2003,135 @@ agent last wrote, so an export right after a patch includes that patch.
 
 - `fablecut_export {}` — waits, then returns the file path under `exports/`.
   Range: `inPoint`→`outPoint` when either is set, else the whole timeline;
-  `range:"entire"|"in-out"` overrides. `profile:"hq"` picks an encoding profile.
+  `range:"entire"|"in-out"` overrides.
+- `preset:"instagram-reels"` picks a delivery preset; `delivery:{…}` changes any of its
+  settings (`{preset:"youtube", delivery:{fps:60, video:{rate:"vbr", bitrate:16000}}}`).
+  `profile:"hq"` picks a raw encoding profile instead. With neither, `project.delivery`
+  is used when set, else `project.encodeProfile`, else the server's default profile.
+- `outputs:true` exports the project's checked batch outputs; `outputs:[{preset:"master"},
+  {preset:"youtube"}, {preset:"instagram-reels"}, …]` exports a list. One render per
+  frame rate; the reply lists every file (or why one failed).
 - `where:"headless"` renders in the background and leaves the user's tab alone;
   `where:"tab"` refuses if no tab is open.
 - Long edits: `wait:false` returns a job id at once; poll with `{job:"x_…"}`
   and stop one with `{cancel:"x_…"}`. One export runs at a time.
 
+### Delivery presets
+
+The Export dialog's **Preset** list. Each preset is a structured spec — no ffmpeg
+arguments to write — that `delivery.js` turns into one ffmpeg pass:
+
+| Preset | Output |
+|---|---|
+| `youtube` | 1920×1080, H.264 CRF 18, keyframe every 0.5 s, AAC 384k 48 kHz |
+| `youtube-shorts` | 1080×1920, as YouTube; warns past 3 min |
+| `instagram-reels` | 1080×1920, H.264 CRF 19 capped at 25 Mb/s, AAC 256k; ≤ 60 fps, warns past 3 min |
+| `tiktok` | 1080×1920, H.264 CRF 19 capped at 20 Mb/s, AAC 256k; warns past 10 min |
+| `x` | 1920×1080, H.264 CRF 20 capped at 25 Mb/s, AAC 192k; warns past 2:20 and 512 MB |
+| `linkedin` | 1920×1080, H.264 CRF 20 capped at 20 Mb/s, AAC 192k; warns past 15 min and 5 GB |
+| `master` (default) | the picture's own size, H.264 CRF 16, AAC 320k |
+| `broadcast` | 1920×1080 ProRes 422 HQ MOV, PCM 24-bit 48 kHz, Rec. 709, normalized to −23 LUFS / −1 dBTP (EBU R128); warns off 25 / 29.97 / 50 / 59.94 fps |
+| `web` | 1280×720 H.264 CRF 23, AAC 128k, fast start |
+| `archive` | the picture's own size, lossless FFV1 4:2:2 10-bit MKV, PCM 24-bit |
+| `custom` | your own settings |
+
+A spec (every key optional — what is left out comes from its `preset`):
+
+```jsonc
+{
+  "preset": "youtube",
+  "width": 1920, "height": 1080,   // null = the picture's own size (the export frame, else the canvas)
+  "fps": null,                     // null = the project's; 23.976 / 29.97 / 59.94 are exact NTSC rates
+  "reframe": "fill",               // another shape: fill crops the middle (or the export frame), fit pads, stretch
+  "container": "mp4",              // mp4 · mov · mkv · webm · mxf
+  "video": {
+    "codec": "h264",               // h264 · hevc · av1 · vp9 · prores · dnxhr · mpeg2 (XDCAM HD422) · ffv1
+    "encoder": "libx264",          // or h264_nvenc / h264_qsv / h264_amf … — listed only when they work here
+    "rate": "crf",                 // crf · vbr · cbr (ProRes, DNxHR, XDCAM, FFV1 are fixed)
+    "crf": 18, "bitrate": 12000, "maxrate": null,   // kb/s; maxrate caps a CRF or VBR encode
+    "keyint": 2,                   // seconds between keyframes, 0 = the encoder's default
+    "speed": "balanced",           // fast · balanced · best
+    "pixFmt": "yuv420p",           // 4:2:0 / 4:2:2 / 4:4:4, 8 or 10 bit, as the codec allows
+    "profile": null                // ProRes: proxy lt standard hq 4444 4444xq · DNxHR: lb sq hq hqx 444
+  },
+  "audio": { "codec": "aac", "bitrate": 320, "sampleRate": 48000, "channels": 2,
+             "loudness": null, "truePeak": -1 },
+                                   // aac · opus · mp3 · pcm16 · pcm24 · flac · none
+                                   // loudness: a LUFS target (−14 streaming, −16 podcast, −23 EBU R128, −24 ATSC) or null
+  "color": "bt709",                // bt709 · bt709-full · bt601-625 (PAL) · bt601-525 (NTSC)
+  "filename": "{project}_{preset}_{res}",
+  // tokens: {project} {preset} {res} (1080p, 1080x1920, 1080sq) {w} {h} {fps} {codec} {date} {time} {range} {n}
+  "metadata": { "title": "", "artist": "", "description": "", "copyright": "", "date": "", "keywords": "" }
+}
+```
+
+- **Impossible combinations are corrected, and the reply says how** — ProRes moves to MOV,
+  WebM takes Opus, Quick Sync gets 4:2:0. The dialog shows the same notes.
+- **Reframing happens in ffmpeg**: the browser sends the whole canvas and ffmpeg crops
+  the export frame (or the middle, for another shape) and scales. The dialog warns
+  when the output is upscaled or cropped, when a platform's length, size or frame-rate
+  limit is passed, and estimates the file size where it can (bitrate and fixed-rate
+  codecs; CRF cannot know).
+- Outputs that keep more than 4:2:0 8-bit (ProRes, DNxHR, FFV1, 10-bit, 4:2:2, 4:4:4)
+  get raw RGBA frames instead of JPEG, so no chroma is lost on the way. Slower to send.
+- The audio is cut to exactly the frames' length.
+- **Loudness** (`audio.loudness`): the mix is measured and turned to the target with
+  ffmpeg's two-pass `loudnorm` — one linear gain, and a true-peak limiter at `truePeak`.
+  When the peaks leave no room for the gain it compresses instead and may land under the
+  target; the check after the export says so. Off (null) leaves the mix as mixed —
+  except Broadcast, which normalizes to −23 LUFS / −1 dBTP. Mixes shorter than 3 s may
+  not reach the target.
+- **Checked after the export.** Every file is read back with ffprobe and measured
+  (BS.1770 integrated loudness and true peak) and compared with what was asked:
+  size, frame rate, frame count, codec, color tags, audio codec / rate / channels,
+  length, loudness against the target (±1 LU) and the true-peak ceiling, and file size
+  against the platform's limit. Without a target the report says where the platform
+  plays it ("YouTube plays it 4.2 dB quieter"). The report shows in the queue, a toast
+  after a single export, and the `fablecut_export` reply.
+- **Saved presets**: "Save preset…" in the dialog writes `library/delivery/<id>.json`,
+  listed under "Saved" in every project (`GET / POST /api/export/presets`,
+  `POST /api/export/presets/delete {id}`).
+- The settings are checked by a 0.1 s ffmpeg dry run before anything renders.
+- The dialog remembers the last settings in this browser. `setProject {delivery:"youtube"}`
+  (or a spec) pins them in the project, for the dialog and for `fablecut_export`.
+- Fast export only — WebCodecs and Realtime export encode their own way.
+
+### Batch outputs and the export queue
+
+**One project → many files.** `project.outputs` is the project's list of files to make
+(up to 16), each a delivery spec plus `{id, on}`. In the Export dialog, **Batch outputs**
+lists them: **+ Add these settings** adds the preset shown above, **+ Typical set** adds
+Master, YouTube 1080p, Reel 1080×1920, Square 1080 and a 720p preview, the checkbox picks
+which go out, **Load** shows one's settings above. **Export checked** queues the checked
+ones and starts.
+
+```jsonc
+// setProject {outputs:[…]} — a preset id or a spec each; stored complete with an id
+{"op":"setProject","set":{"outputs":[
+  "master", "youtube",
+  {"preset":"instagram-reels"},
+  {"preset":"custom","width":1080,"height":1080,"filename":"{project}_square_{res}"},
+  {"preset":"web","filename":"{project}_preview_{res}","on":false}
+]}}
+```
+
+- **Rendered once.** Outputs with the same frame rate and range go out in ONE render:
+  the compositor draws each frame once and every output's ffmpeg encodes it (up to 8 per
+  render). Four 1080p files take about as long as one. Outputs at another frame rate get
+  their own render. When any output needs full chroma (ProRes, 10-bit, lossless) the
+  frames go as RGBA to all of them.
+- **The export frame** is the picture for outputs of its own shape (and for the
+  picture's own size). An output of another shape reframes the whole canvas — a project
+  framed for 9:16 still makes a proper 16:9 file.
+- **The export queue** (Export dialog → **Add to queue**, or **Queue**) runs waiting
+  outputs back to back with a progress bar each, **Stop**, **Retry** for a failed one,
+  **Open** for a finished file and **Clear finished**. It lives in the tab: a reload
+  empties it. One output that fails does not stop the others in its render.
+- REST: `POST /api/export/begin {deliveries:[{delivery, name}, …], canvasW, canvasH,
+  region?, duration, fps, hasAudio}` → `{id, input, jpegQuality, outputs:[{file, spec,
+  summary, notes, size}]}`; frames and audio as for one output; `/api/export/end` →
+  `{src, outputs:[{file, ok, src, report:{ok, checks:[{ok, text}], line}, mixLoudness?} | {file, ok:false, error}]}`.
+
 ### Encoding profiles (`encoding-profiles.json`)
 
 User-editable at the repo root. A profile is a **raw ffmpeg argument list** plus the
@@ -1410,11 +2195,12 @@ ffmpeg -y -f image2pipe -framerate <fps> -i - [-i audio.wav] <jpeg-color> <args
 not `-i source.mp4`. Filters and codec settings apply to that frame stream. To transcode
 an existing file verbatim, run ffmpeg directly — that is outside the compositor path.
 
-**Which profile is used (priority):**
-1. Profile picked in the Export dialog (one-off; saved to browser settings unless overridden)
-2. `project.encodeProfile` — set via UI reload or `{op:"setProject", set:{encodeProfile:"hq"}}`
-3. Browser setting `encodeProfile` in localStorage (set when you change the Export dropdown)
-4. `default` in `encoding-profiles.json`
+Encoding profiles are listed at the bottom of the Export dialog's Preset list.
+
+**What the Export dialog opens on (priority):**
+1. `project.delivery`, then `project.encodeProfile` — set with `setProject`
+2. The last preset or profile used in this browser
+3. The `master` delivery preset
 
 **MCP:** `fablecut_encode_profiles` lists profiles; `{detail:true}` includes each `args`
 array; `{profile:"hq"}` returns one profile. `fablecut_status` shows the effective profile.