fablecut 1.13.0 → 1.15.0

package/edit-ops.js

@@ -20,10 +20,11 @@
    lockedTracks and untargetedTracks) for headless callers. */
 (function (root, factory) {
   const node = typeof module === "object" && module.exports;
-  const api = factory(node ? require("./mask") : root.FableCutMask, node ? require("./tracker") : root.FableCutTracker);
+  const api = factory(node ? require("./mask") : root.FableCutMask, node ? require("./tracker") : root.FableCutTracker,
+    node ? require("./motion") : root.FableCutMotion);
   if (node) module.exports = api;
   else root.FableCutEdit = api;
-})(typeof self !== "undefined" ? self : this, function (MaskLib, TrackLib) {
+})(typeof self !== "undefined" ? self : this, function (MaskLib, TrackLib, MotionLib) {
   "use strict";
 
   const MIN_DUR = 0.05;
@@ -41,8 +42,10 @@
   /* ── Pure clip helpers ── */
   const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
   const clipEnd = (c) => c.start + c.duration;
-  const clipSpeed = (c) => clamp(+(c.props?.speed) || 1, 0.1, 8);
+  const clipSpeed = (c) => (c.kind === "comp" ? 1 : clamp(+(c.props?.speed) || 1, 0.1, 8));
   const isMediaClip = (c) => c.kind === "video" || c.kind === "audio";
+  /** Clips with a source window (`in` into something with a length): media, and comp clips (into their comp). */
+  const hasSourceTime = (c) => isMediaClip(c) || c.kind === "comp";
   const EASE = {
     linear: (u) => u,
     "ease-in": (u) => u * u,
@@ -65,7 +68,7 @@
     return fallback;
   }
   function hasSpeedRamp(c) {
-    return Array.isArray(c.keyframes?.speed) && c.keyframes.speed.length > 0;
+    return c.kind !== "comp" && Array.isArray(c.keyframes?.speed) && c.keyframes.speed.length > 0;   // comps run at 1×
   }
   /** Source time at timeline time t: in + ∫speed (trapezoid, 1/120 s steps). */
   function mediaTimeAt(c, t) {
@@ -93,10 +96,11 @@
     }
     return Object.keys(out).length ? out : undefined;
   }
-  /** A clip's head moved by `offset` s: its mask keys and track samples follow, like shiftKF does for keyframes. */
+  /** A clip's head moved by `offset` s: its mask keys, shape keys and track samples follow, like shiftKF does for keyframes. */
   function shiftMasks(c, offset) {
     if (!offset || !c.props) return;
-    const ms = c.props.masks, ts = c.props.tracks;
+    const ms = c.props.masks, ts = c.props.tracks, ss = c.props.shapes;
+    if (MotionLib && Array.isArray(ss)) c.props = { ...c.props, shapes: MotionLib.shiftKeys(ss, offset) };
     if (MaskLib && Array.isArray(ms)) {
       const next = MaskLib.shiftKeys(ms, offset);
       if (next !== ms) c.props = { ...c.props, masks: next };
@@ -107,6 +111,27 @@
       if (next.length) c.props.tracks = next; else delete c.props.tracks;
     }
   }
+  /** Clips are leaving the document: their children stay where they are. Each child is
+   *  re-parented to the nearest ancestor that stays (or to nothing), with its static
+   *  position / rotation / scale rewritten to hold its place at its own start. Keyed
+   *  channels keep their keys. Call it before the clips are removed. */
+  function detachChildren(project, goneIds) {
+    if (!MotionLib || !goneIds || !goneIds.size) return 0;
+    const byId = (id) => project.clips.find((x) => x.id === id) || null;
+    let n = 0;
+    for (const k of project.clips) {
+      if (!k.parent || goneIds.has(k.id) || !goneIds.has(k.parent)) continue;
+      let up = byId(k.parent), guard = 0;
+      while (up && goneIds.has(up.id) && guard++ < 64) up = up.parent ? byId(up.parent) : null;
+      const next = up && !goneIds.has(up.id) ? up.id : null;
+      const v = MotionLib.reparentValues(k, next, byId, k.start || 0);
+      k.props = { ...(k.props || {}) };
+      for (const [p, val] of Object.entries(v)) if (!(k.keyframes && Array.isArray(k.keyframes[p]) && k.keyframes[p].length)) k.props[p] = val;
+      if (next) k.parent = next; else delete k.parent;
+      n++;
+    }
+    return n;
+  }
   /** Default stereo pan for an isolated linked stem (L −1, R +1, else center). */
   function defaultPanForChannel(ch) {
     if (ch === 0) return -1;
@@ -120,9 +145,16 @@
     const timeAt = env.mediaTimeAt || mediaTimeAt;
     const removed = (c) => { if (env.onRemove) env.onRemove(c); };
     const getMedia = (id) => P().media.find((m) => m.id === id);
+    /** Length of what c's `in` points into (media or comp), 0 when unknown. */
+    const sourceLen = (c) => {
+      if (c.kind === "comp") { const k = (P().comps || []).find((x) => x.id === c.compId); return k ? +k.duration || 0 : 0; }
+      const m = getMedia(c.mediaId);
+      return m ? +m.duration || 0 : 0;
+    };
     const getClip = (id) => P().clips.find((c) => c.id === id) || null;
     const dropClips = (pred) => {
       const project = P();
+      detachChildren(project, new Set(project.clips.filter(pred).map((x) => x.id)));
       const keep = [];
       for (const x of project.clips) { if (pred(x)) removed(x); else keep.push(x); }
       project.clips = keep;
@@ -286,7 +318,7 @@
         const dIn = t0 - start;
         if (dIn > 1e-6) {
           c.start = t0;
-          if (isMediaClip(c)) c.in += dIn * clipSpeed(c);
+          if (hasSourceTime(c)) c.in += dIn * clipSpeed(c);
           else c.in = 0;
           c.duration -= dIn;
           c.keyframes = shiftKF(c.keyframes, dIn, c.duration);
@@ -676,10 +708,10 @@
 
     /** Longest this clip may run before it runs out of source media. */
     function maxClipDur(c) {
-      if (!isMediaClip(c)) return Infinity;
-      const m = getMedia(c.mediaId);
-      if (!m || !(m.duration > 0)) return Infinity;
-      return Math.max(MIN_DUR, (m.duration - c.in) / clipSpeed(c));
+      if (!hasSourceTime(c)) return Infinity;
+      const len = sourceLen(c);
+      if (!(len > 0)) return Infinity;
+      return Math.max(MIN_DUR, (len - c.in) / clipSpeed(c));
     }
     /* A linked group shares its timing, but a partner may run at a different
        speed (links are inferred from timing alone), so every source limit is the
@@ -690,7 +722,7 @@
     }
     /** How far c's group can pull its head back before any member reaches source 0. */
     function groupHeadRoom(c) {
-      return Math.min(...withLinked([c]).map((x) => (isMediaClip(x) ? x.in / clipSpeed(x) : Infinity)));
+      return Math.min(...withLinked([c]).map((x) => (hasSourceTime(x) ? x.in / clipSpeed(x) : Infinity)));
     }
     /** The clip butting against c's head ("in") or tail ("out") on its track. */
     function adjacentClip(c, side) {
@@ -726,7 +758,7 @@
     function trimGroupHead(c, d, moveStart) {
       for (const x of withLinked([c])) {
         if (moveStart) x.start = +(x.start + d).toFixed(4);
-        if (isMediaClip(x)) x.in = +(x.in + d * clipSpeed(x)).toFixed(4);
+        if (hasSourceTime(x)) x.in = +(x.in + d * clipSpeed(x)).toFixed(4);
         x.duration = +(x.duration - d).toFixed(4);
         x.keyframes = shiftKF(x.keyframes, d, x.duration);
         shiftMasks(x, d);
@@ -796,7 +828,7 @@
      *  delta > 0 drags the picture right, i.e. earlier source. Position and
      *  length stay; clip-local keyframes stay put on the timeline. */
     function slipClip(c, delta) {
-      if (!isMediaClip(c)) return "Slip needs a video or audio clip — stills and titles have no source time";
+      if (!hasSourceTime(c)) return "Slip needs a video or audio clip, or a comp clip — stills and titles have no source time";
       if (isGroupLocked(c)) return TRIM_LOCKED;
       const sp = clipSpeed(c);
       const group = withLinked([c]);
@@ -804,9 +836,9 @@
       // consumes its own span of source (speed can differ across the group).
       let maxIn = Infinity;
       for (const x of group) {
-        if (!isMediaClip(x)) continue;
-        const m = getMedia(x.mediaId);
-        if (m && m.duration > 0) maxIn = Math.min(maxIn, Math.max(0, m.duration - (timeAt(x, clipEnd(x)) - x.in)));
+        if (!hasSourceTime(x)) continue;
+        const len = sourceLen(x);
+        if (len > 0) maxIn = Math.min(maxIn, Math.max(0, len - (timeAt(x, clipEnd(x)) - x.in)));
       }
       const newIn = clampD(c.in - delta * sp, 0, maxIn);
       const d = (c.in - newIn) / sp;
@@ -977,7 +1009,7 @@
 
   return {
     MIN_DUR, MIN_TRANS_DUR, CROSSFADE_DUR, GAP_EPS, TRIM_LOCKED, DEFAULT_TRACKS,
-    clipEnd, clipSpeed, kfChannel, hasSpeedRamp, mediaTimeAt, shiftKF, shiftMasks, defaultPanForChannel,
+    clipEnd, clipSpeed, isMediaClip, hasSourceTime, kfChannel, hasSpeedRamp, mediaTimeAt, shiftKF, shiftMasks, detachChildren, defaultPanForChannel,
     create, forDoc,
   };
 });

package/export-jobs.js

@@ -49,7 +49,7 @@ function createExportJobs(opts) {
   let timer = null;
   const isEnded = (j) => j.status === "done" || j.status === "failed" || j.status === "cancelled";
   const view = (j) => ({
-    id: j.id, kind: j.kind, status: j.status, via: j.via, range: j.range, profile: j.profile || null,
+    id: j.id, kind: j.kind, status: j.status, via: j.via, range: j.range, profile: j.profile || null, preset: j.delivery ? j.delivery.preset || "custom" : null,
     time: j.time ?? null, progress: j.progress, src: j.src || null, result: j.result || null, error: j.error || null,
     created: j.created, updated: j.updated,
   });
@@ -104,8 +104,10 @@ function createExportJobs(opts) {
   return {
     /** Queue an export. where: auto (open tab, else headless) · tab · headless.
      *  kind "scopes" measures one still at `time` instead (fablecut_scopes);
-     *  kind "track" follows a region of a clip and saves it (fablecut_track). */
-    request({ kind = "export", range, profile, time, revision, where = "auto", matte = null, mask = null, track = null }) {
+     *  kind "track" follows a region of a clip and saves it (fablecut_track).
+     *  A scopes job's `image` flag also returns that still as a JPEG data URL,
+     *  which is how fablecut_frame shows an agent the composed program picture. */
+    request({ kind = "export", range, profile, delivery = null, deliveries = null, time, revision, where = "auto", matte = null, mask = null, track = null, image = false }) {
       if (!["auto", "tab", "headless"].includes(where)) throw Object.assign(new Error("where must be auto, tab or headless"), { code: 400 });
       if (!["export", "scopes", "track"].includes(kind)) throw Object.assign(new Error("kind must be export, scopes or track"), { code: 400 });
       if (time != null && !(Number.isFinite(time) && time >= 0)) throw Object.assign(new Error("time must be seconds ≥ 0"), { code: 400 });
@@ -117,10 +119,12 @@ function createExportJobs(opts) {
       const now = Date.now();
       const j = {
         id: "x_" + Math.random().toString(36).slice(2, 10), kind, status: "pending", progress: 0,
-        range: range || null, profile: profile || null, time: time ?? null, revision: Number.isFinite(revision) ? revision : null,
+        range: range || null, profile: profile || null, delivery: kind === "export" && delivery ? delivery : null,
+        deliveries: kind === "export" && Array.isArray(deliveries) && deliveries.length ? deliveries : null, time: time ?? null, revision: Number.isFinite(revision) ? revision : null,
         matte: kind === "scopes" && matte ? { clip: String(matte.clip), layer: matte.layer } : null,
         mask: kind === "scopes" && mask ? { clip: String(mask.clip) } : null,
         track: kind === "track" && track ? track : null,
+        image: kind === "scopes" && !!image,
         via: where === "headless" || (where === "auto" && !tabs) ? "headless" : "tab",
         created: now, updated: now,
       };
@@ -132,7 +136,7 @@ function createExportJobs(opts) {
     },
     get(id) { const j = jobs.get(id); return j ? view(j) : null; },
     /** What a tab needs to run the job (headless pages fetch it by id). */
-    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, time: j.time, revision: j.revision, matte: j.matte || null, mask: j.mask || null, track: j.track || null, status: j.status } : null; },
+    ticket(id) { const j = jobs.get(id); return j ? { id: j.id, kind: j.kind, range: j.range, profile: j.profile, delivery: j.delivery || null, deliveries: j.deliveries || null, time: j.time, revision: j.revision, matte: j.matte || null, mask: j.mask || null, track: j.track || null, image: !!j.image, status: j.status } : null; },
     /** First tab to claim a pending job runs it. */
     claim(id) {
       const j = jobs.get(id);

package/frame-cache.js

@@ -0,0 +1,49 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   The /api/frame render cache (analysis/frames/) — bounded, oldest-first.
+
+   Every distinct combination of source + arguments renders its own JPEG, so an
+   unbounded cache is a disk-fill primitive: varying w, q or t mints a new file
+   each time, and a hostile page could do exactly that through the endpoint.
+   (The header gate on ?path= keeps strangers out; this keeps friends honest.)
+   Each entry is a .jpg plus its .json sidecar; pruning removes both, oldest
+   mtime first, until the directory is back under both limits.
+
+   Pure filesystem logic, no ffmpeg — unit-tested directly in frame-cache.test.js.
+   ═══════════════════════════════════════════════════════════════════════════ */
+"use strict";
+const fs = require("fs");
+const path = require("path");
+
+/* Generous enough that a real editing session never notices: a few hundred
+   grabs at ~100 KB each is tens of megabytes. */
+const DEFAULT_MAX_FILES = 500;
+const DEFAULT_MAX_BYTES = 128 * 1024 * 1024;
+
+/** Delete oldest entries until dir holds ≤ maxFiles JPEGs and ≤ maxBytes.
+ *  Returns {files, bytes, pruned}. Never throws — a prune failure must not
+ *  fail the request that triggered it. */
+function pruneCache(dir, { maxFiles = DEFAULT_MAX_FILES, maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  let names;
+  try { names = fs.readdirSync(dir); } catch { return { files: 0, bytes: 0, pruned: 0 }; }
+  const entries = [];
+  for (const name of names) {
+    if (!name.endsWith(".jpg")) continue;
+    try {
+      const st = fs.statSync(path.join(dir, name));
+      if (st.isFile()) entries.push({ name, size: st.size, mtime: st.mtimeMs });
+    } catch { /* vanished mid-sweep — someone else pruned it */ }
+  }
+  entries.sort((a, b) => a.mtime - b.mtime); // oldest first
+  let bytes = entries.reduce((s, e) => s + e.size, 0);
+  let pruned = 0;
+  while ((entries.length > maxFiles || bytes > maxBytes) && entries.length) {
+    const victim = entries.shift();
+    bytes -= victim.size;
+    pruned++;
+    try { fs.rmSync(path.join(dir, victim.name)); } catch {}
+    try { fs.rmSync(path.join(dir, victim.name.replace(/\.jpg$/, ".json"))); } catch {}
+  }
+  return { files: entries.length, bytes, pruned };
+}
+
+module.exports = { pruneCache, DEFAULT_MAX_FILES, DEFAULT_MAX_BYTES };

package/frame-stats.js

@@ -0,0 +1,267 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   Frame statistics — describe a frame in words, for anyone who can't see it.
+
+   `fablecut_frame` hands a multimodal model an actual image, which is the point.
+   But not every MCP client, and not every model behind it, can read one: a
+   text-only agent gets the coordinates of the picture and nothing else, so it
+   learns nothing about the footage it was asked to judge.
+
+   This closes that gap with measurements instead of pixels — brightness, the
+   dominant colours, and how much a moment differs from the one before it — the
+   same numbers `fablecut_scopes` reports for the composed picture, applied to a
+   source frame. Deliberately NOT a caption: no zero-dependency way to describe
+   what is in the picture honestly. What it gives instead is enough to rank and
+   route footage ("bright outdoor, high motion, dominant green") without a
+   picture at all.
+
+   Pure functions over a raw RGB buffer. No ffmpeg, no canvas, no dependencies,
+   so the whole thing is testable on its own. ═══════════════════════════════════ */
+"use strict";
+
+/* Rec. 709 luma weights — the same coefficients the browser uses, so a number
+   here means the same thing as a number from fablecut_scopes. */
+/* Every luma field below is 0–1, rounded to 3 decimals — the same convention
+   as color.js scopeStats, so the two readings can sit side by side without a
+   conversion nobody remembers to do. */
+const WR = 0.2126, WG = 0.7152, WB = 0.0722;
+const r3 = (v) => Math.round(v * 1000) / 1000;
+
+/* Perceptual buckets. A 4-bit-per-channel histogram is 4096 entries: fine
+   enough to separate a lime from a green, coarse enough that JPEG noise in a
+   gradient lands in one bucket instead of smearing across a hundred. */
+const BITS = 4, SHIFT = 8 - BITS, BUCKETS = 1 << (BITS * 3);
+
+/** Rec. 709 luma of one pixel, 0–255. */
+function luma(r, g, b) { return WR * r + WG * g + WB * b; }
+
+/* Named colours a model can reason about, matched against the histogram's top
+   buckets. These are the useful coarse categories — "sky", "foliage", "skin",
+   "night" — rather than 4096 hex codes nobody can picture. Nearest match by
+   weighted RGB distance, so a slightly-off bucket still lands sensibly. */
+const NAMED = [
+  { name: "black", rgb: [10, 10, 12] },
+  { name: "deep blue", rgb: [16, 26, 74] },
+  { name: "blue", rgb: [40, 84, 190] },
+  { name: "sky blue", rgb: [128, 186, 235] },
+  { name: "cyan", rgb: [56, 190, 200] },
+  { name: "green", rgb: [56, 142, 62] },
+  { name: "lime", rgb: [140, 205, 60] },
+  { name: "olive", rgb: [120, 118, 52] },
+  { name: "yellow", rgb: [226, 200, 62] },
+  { name: "orange", rgb: [222, 122, 44] },
+  { name: "red", rgb: [196, 52, 44] },
+  { name: "dark red", rgb: [104, 26, 26] },
+  { name: "magenta", rgb: [176, 58, 168] },
+  { name: "skin", rgb: [214, 168, 132] },
+  { name: "grey", rgb: [128, 128, 130] },
+  { name: "light grey", rgb: [206, 206, 208] },
+  { name: "white", rgb: [242, 242, 244] },
+];
+function nameColor(r, g, b) {
+  let best = NAMED[0], bestD = Infinity;
+  for (const c of NAMED) {
+    /* Plain Euclidean RGB distance. Luma weighting looks principled and is
+       wrong here: Rec.709 gives blue a weight of 0.07, so a bucket that differs
+       from "blue" mostly in blue reads as "deep blue" instead. For naming a
+       colour, hue is the thing being asked about. */
+    const d = (r - c.rgb[0]) ** 2 + (g - c.rgb[1]) ** 2 + (b - c.rgb[2]) ** 2;
+    if (d < bestD) { bestD = d; best = c; }
+  }
+  return best.name;
+}
+
+/** Bucket a pixel into the 4-bit-per-channel histogram. */
+const bucketOf = (r, g, b) => ((r >> SHIFT) << (BITS * 2)) | ((g >> SHIFT) << BITS) | (b >> SHIFT);
+function bucketRgb(i) {
+  return [((i >> (BITS * 2)) & 0xf) << SHIFT, ((i >> BITS) & 0xf) << SHIFT, (i & 0xf) << SHIFT];
+}
+
+/**
+ * Describe one frame.
+ *
+ * @param rgb  raw RGB24 bytes (w*h*3)
+ * @param w,h  its dimensions
+ * @param opts {stride} — bytes per row, when rgb is a window into a bigger
+ *          buffer (the contact sheet slices cells out of one grid image)
+ * @returns {{luma:object, brightness:string, colours:Array, saturation:number,
+ *            meanRgb:number[], texture:number, samples:number}}
+ */
+function describe(rgb, w, h, { stride = w * 3, offset = 0 } = {}) {
+  const n = w * h;
+  const hist = new Uint32Array(BUCKETS);
+  const lums = new Float64Array(n);
+  let sr = 0, sg = 0, sb = 0, k = 0;
+  for (let y = 0; y < h; y++) {
+    let i = offset + y * stride;
+    for (let x = 0; x < w; x++, i += 3, k++) {
+      const r = rgb[i], g = rgb[i + 1], b = rgb[i + 2];
+      sr += r; sg += g; sb += b;
+      lums[k] = luma(r, g, b);
+      hist[bucketOf(r, g, b)]++;
+    }
+  }
+  // Percentiles need a sort; a frame is at most a few hundred thousand samples,
+  // and this runs once per call, not per frame of a render.
+  const sorted = Float64Array.prototype.slice.call(lums).sort();
+  const q = (p) => sorted[Math.min(n - 1, Math.max(0, Math.round(p * (n - 1))))];
+  let sum = 0;
+  for (let i = 0; i < n; i++) sum += lums[i];
+  const mean = sum / n / 255;
+  const meanRgb = [sr / n, sg / n, sb / n];
+
+  // Saturation 0–1, from mean chroma against mean luma (the cheap version —
+  // no per-pixel HSV pass).
+  const chroma = (Math.max(...meanRgb) - Math.min(...meanRgb)) / 255;
+  const lum01 = mean;
+  const saturation = lum01 < 0.005 ? 0 : Math.min(1, chroma / (lum01 * 2));
+
+  /* "Texture": the mean absolute luma step between horizontally adjacent
+     samples, as a percentage of full range. Smooth sky or a locked-off tripod
+     shot scores near 0; foliage, crowds or a busy frame score clearly higher.
+     Reported on the same 0–100 scale as the analyzer's per-shot `energy`, so
+     the two can be compared directly. It measures detail *within* the frame,
+     not change over time — motionScore() is the change-over-time one. */
+  let diff = 0, dN = 0;
+  for (let y = 0; y < h; y++) {
+    // Start one pixel in: the step reads the pixel before the cursor, and on
+    // the first row that would be rgb[-3] — undefined, and silently NaN.
+    let i = offset + y * stride + 3;
+    for (let x = 1; x < w; x++, i += 3) {
+      diff += Math.abs(luma(rgb[i], rgb[i + 1], rgb[i + 2]) - luma(rgb[i - 3], rgb[i - 2], rgb[i - 1]));
+      dN++;
+    }
+  }
+  // A single-pixel-wide sample has no horizontal neighbours; report no texture
+  // rather than NaN.
+  const detail = dN ? Math.round(diff / dN / 255 * 1000) / 10 : 0;
+
+  // Top colour buckets, merged when they are neighbours so a sky reads as one
+  // entry rather than four.
+  const top = [];
+  for (let i = 0; i < BUCKETS; i++) {
+    if (hist[i]) top.push([i, hist[i]]);
+  }
+  top.sort((a, b) => b[1] - a[1]);
+  const colours = [];
+  for (const [idx, count] of top) {
+    const [r, g, b] = bucketRgb(idx);
+    const near = colours.find((c) =>
+      (c.rgb[0] - r) ** 2 + (c.rgb[1] - g) ** 2 + (c.rgb[2] - b) ** 2 < 900);
+    if (near) {
+      // Weighted mean, so the merged entry points at the colour actually seen.
+      const tot = near.count + count;
+      near.rgb = near.rgb.map((v, j) => Math.round((v * near.count + [r, g, b][j] * count) / tot));
+      near.count = tot;
+      near.pct = tot;
+    } else {
+      colours.push({ rgb: [r, g, b], count, pct: count });
+    }
+  }
+  colours.sort((a, b) => b.count - a.count);
+  const shown = colours.slice(0, 3);
+  for (const c of shown) {
+    c.pct = Math.round(c.pct / n * 100);
+    c.hex = "#" + c.rgb.map((v) => v.toString(16).padStart(2, "0")).join("");
+    c.name = nameColor(c.rgb[0], c.rgb[1], c.rgb[2]);
+  }
+
+  const l = mean;
+  return {
+    luma: {
+      min: r3(q(0) / 255), p1: r3(q(0.01) / 255), median: r3(q(0.5) / 255),
+      mean: r3(l), p99: r3(q(0.99) / 255), max: r3(q(1) / 255),
+    },
+    brightness: l < 0.12 ? "very dark" : l < 0.35 ? "dark" : l < 0.65 ? "mid" : l < 0.85 ? "bright" : "very bright",
+    colours: shown,
+    meanRgb: meanRgb.map((v) => Math.round(v)),
+    saturation: Math.round(saturation * 100) / 100,
+    texture: detail,
+    samples: n,
+  };
+}
+
+/**
+ * Mean absolute per-channel difference between two equally sized regions,
+ * 0–1. High means the picture changed a lot between them — a cut, or fast
+ * motion. This is the "is this a different shot" signal a contact sheet's cells
+ * can be ranked by.
+ */
+function motionScore(rgbA, rgbB, w, h) {
+  const n = w * h * 3;
+  if (!n || !rgbA || !rgbB || rgbA.length < n || rgbB.length < n) return 0;
+  let d = 0;
+  for (let i = 0; i < n; i++) d += Math.abs(rgbA[i] - rgbB[i]);
+  return Math.round(d / n / 255 * 1000) / 1000;
+}
+
+/**
+ * Describe a tiled contact sheet cell by cell. `rgb` is the whole grid image;
+ * cells are read left→right then top→bottom, so cell i is the frame at times[i].
+ *
+ * Each cell reports its own brightness/colours, plus motion against the previous
+ * populated cell — which is what lets a text-only agent find the cut points and
+ * pick the high-motion moments without seeing anything.
+ *
+ * @param rgb  raw RGB24 of the whole grid
+ * @param w,h  grid dimensions
+ * @param cols,rows  the tile layout
+ * @param times  one timestamp per cell, in cell order
+ */
+function describeGrid(rgb, w, h, cols, rows, times = []) {
+  // tile lays cells out edge to edge, so the cell size is the grid divided by
+  // the layout. Guard the rounding: a width that doesn't divide evenly would
+  // drift a pixel per row and smear the last column.
+  const cw = Math.floor(w / cols), ch = Math.floor(h / rows);
+  const cells = [];
+  let prev = null, prevIdx = -1;
+  for (let r = 0; r < rows; r++) {
+    for (let c = 0; c < cols; c++) {
+      const index = r * cols + c;
+      const time = times[index];
+      // Fewer timestamps than cells means tile padded the last row with black —
+      // say so rather than describing a padding cell as a black frame.
+      if (time == null) { cells.push({ index, padded: true }); continue; }
+      const ox = c * cw, oy = r * ch;
+      const view = new Uint8Array(cw * ch * 3);
+      for (let y = 0; y < ch; y++) {
+        const from = ((oy + y) * w + ox) * 3;
+        view.set(rgb.subarray(from, from + cw * 3), y * cw * 3);
+      }
+      const stats = describe(view, cw, ch);
+      const cell = { index, time, ...stats };
+      // Compare against the previous *real* cell, skipping padding, so the last
+      // filled cell of a short row is still measured against its neighbour.
+      cell.motion = prev ? motionScore(view, prev, cw, ch) : 0;
+      cells.push(cell);
+      prev = view; prevIdx = index;
+    }
+  }
+  return { cols, rows, cellWidth: cw, cellHeight: ch, cells };
+}
+
+/** One line per thing worth saying, for a single frame. These lines are the whole
+ *  point of the text fallback: read by a model that never sees the pixels.
+ *  Keep them short — this is what an agent gets instead of the image. */
+function frameLines(label, stats) {
+  const L = stats.luma;
+  const cols = stats.colours.map((c) => `${c.name} ${c.hex} ${c.pct}%`).join(", ");
+  return [
+    `${label}: ${stats.brightness} (luma mean ${L.mean}, median ${L.median}, range ${L.min}–${L.max})`,
+    `  dominant: ${cols || "flat"}`,
+    `  texture ${stats.texture}/100 · saturation ${stats.saturation} · mean rgb [${stats.meanRgb.join(", ")}]`,
+  ];
+}
+
+/** One line per cell, for a contact sheet. `motion` is the change since the
+ *  previous cell, so it spikes at a cut *and* during fast movement — it ranks
+ *  the most active moments, it does not prove there was a cut. */
+function gridLines(grid) {
+  const lines = grid.cells.map((c) => {
+    if (c.padded) return `  cell ${c.index + 1}: (padding — not a frame in this clip)`;
+    return `  cell ${c.index + 1} @ ${c.time}s: ${c.brightness}, ${c.colours.map((x) => `${x.name} ${x.pct}%`).join(" / ") || "flat"}`
+      + ` · texture ${c.texture}/100 · change ${c.motion}`;
+  });
+  return [`Contact sheet ${grid.cols}x${grid.rows}, ${grid.cells.filter((c) => !c.padded).length} frames:`, ...lines];
+}
+
+module.exports = { describe, describeGrid, motionScore, luma, nameColor, frameLines, gridLines };