@crievo/omni 0.0.0-stage → 0.1.0

package/tools/reference.mjs

@@ -0,0 +1,1408 @@
+#!/usr/bin/env node
+/* ============================================================================
+   Biblioteca de estilos visuais (antes "referências"): vídeos e fotos que dirigem o visual de um vídeo novo.
+
+     node tools/reference.mjs list
+     node tools/reference.mjs measure <video|url> <nome> [--out <pasta>]
+     node tools/reference.mjs excerpt <nome> <t0> <t1> [--fps 15]
+     node tools/reference.mjs frame   <nome> <t> [<t> …]
+     node tools/reference.mjs color   <nome> <t> <x>,<y> [<x>,<y> …]
+     node tools/reference.mjs curve   <nome> <t0> <t1> --box <x>,<y>,<w>,<h> [--color #hex] [--background #hex]
+     node tools/reference.mjs compare <nome> <proof.html> <tRef>[:<tProva>] … [--out <png>]
+
+   Cada estilo visual é uma pasta em `references.dir` (config) com o vídeo, um
+   GUIDE.md escrito a partir das medições e as folhas que embasam o guia.
+
+   `measure` faz o que dá para medir sem olhar: cortes, duração dos planos,
+   quanto da tela muda a cada instante (onde a peça corre e onde segura),
+   paleta com área de cada cor, superfície (indício de desenho chapado ou de
+   imagem filmada) e, se houver som, volume e pulso. Grava
+   measurements.json, sheets/contacts.png e sheets/cuts.png, e um GUIDE.md a
+   partir de templates/reference.md se a pasta ainda não tem guia.
+
+   O resto (tipografia, layout, curvas) sai de ler as folhas com Read:
+   `excerpt` monta uma folha quadro a quadro de um intervalo, `frame` extrai
+   quadros em resolução cheia para medir corpo de fonte, e `color` lê o hex de
+   pontos de um quadro (coordenadas do quadro em resolução cheia).
+
+   Curva e duração também se medem: `curve` acompanha o que está numa caixa
+   do quadro e devolve, por canal (posição, tamanho, presença), início,
+   duração, o cubic-bezier ajustado, as curvas nomeadas mais perto (CSS e
+   GSAP), overshoot e steps(). `compare` renderiza uma cena de prova
+   (proof/proof.html, a partir de templates/scene.html) nos tempos pedidos e
+   monta referência | prova | diferença, com SSIM e ΔE: é o teste de que o
+   guia reproduz a peça, e não só a descreve.
+
+   Ritmo não se sente em quadro parado, mas se mede: é o que este script dá.
+   Requer ffmpeg/ffprobe; yt-dlp para baixar de link.
+   ============================================================================ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  copyFileSync,
+  statSync,
+  rmSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve, dirname, basename, extname, relative } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { CODE_ROOT, DATA_ROOT as ROOT } from "./lib/paths.mjs";
+
+const CFG = JSON.parse(readFileSync(join(ROOT, "omnivideo.config.json"), "utf8"));
+const LIBRARY = resolve(ROOT, CFG.references.dir.replace(/^~(?=\/|$)/, homedir()));
+const VIDEO_EXT = /\.(mp4|mov|webm|mkv|m4v)$/i;
+
+function fail(msg) {
+  console.error(`erro: ${msg}`);
+  process.exit(1);
+}
+function run(bin, args, { binary = false } = {}) {
+  const r = spawnSync(bin, args, { maxBuffer: 1 << 29, encoding: binary ? "buffer" : "utf8" });
+  if (r.error) fail(`${bin}: ${r.error.message}`);
+  if (r.status !== 0) fail(`${bin} saiu com ${r.status}: ${String(r.stderr).slice(-600)}`);
+  return r.stdout;
+}
+
+/* --- video ------------------------------------------------------------------- */
+function probe(file) {
+  const j = JSON.parse(run("ffprobe", ["-v", "error", "-print_format", "json", "-show_streams", "-show_format", file]));
+  const v = j.streams.find(s => s.codec_type === "video");
+  if (!v) fail(`${file} não tem vídeo`);
+  const [n, d] = (v.avg_frame_rate !== "0/0" ? v.avg_frame_rate : v.r_frame_rate).split("/").map(Number);
+  return {
+    duration: +(+j.format.duration).toFixed(3),
+    w: v.width,
+    h: v.height,
+    fps: +(n / (d || 1)).toFixed(3),
+    audio: j.streams.some(s => s.codec_type === "audio"),
+  };
+}
+
+/* dir and video of a reference by name. A path (with "/") also works: a
+   loose dir, or the video itself (reels/, one video among several), and
+   then the sheets go to its dir. */
+function openRef(name) {
+  if (!name.includes("/")) {
+    const dir = join(LIBRARY, name);
+    return { dir, file: videoInDir(dir) };
+  }
+  const p = resolve(name);
+  if (!existsSync(p)) fail(`${p} não existe`);
+  return statSync(p).isFile() ? { dir: dirname(p), file: p } : { dir: p, file: videoInDir(p) };
+}
+
+function videoInDir(dir) {
+  const m = existsSync(join(dir, "measurements.json"))
+    ? JSON.parse(readFileSync(join(dir, "measurements.json"), "utf8"))
+    : null;
+  if (m?.video && existsSync(join(dir, m.video))) return join(dir, m.video);
+  const v = readdirSync(dir)
+    .filter(f => VIDEO_EXT.test(f))
+    .sort()[0];
+  if (!v) fail(`${dir} não tem vídeo na raiz`);
+  return join(dir, v);
+}
+
+/* --- measurements ---------------------------------------------------------------- */
+
+/* cuts: scene difference of each frame vs the previous one. A cut is the
+   strong jump (≥ 0.3) or the local peak: ≥ 0.06 and 5× the median of ±0.5 s
+   around it. The fixed threshold alone missed cuts between near-black frames
+   (the hero changes, but the whole image barely does): on dark-vibrant-elements
+   it found 0 of 10 cuts, the local peak finds 7; on pure-dark, 3 of 3. */
+function cuts(file, duration) {
+  const out = run("ffmpeg", [
+    "-hide_banner",
+    "-nostats",
+    "-i",
+    file,
+    "-an",
+    "-vf",
+    "scale=320:-2,select='gte(scene,0)',metadata=print:file=-",
+    "-f",
+    "null",
+    "-",
+  ]);
+  const pts = [];
+  let t = null;
+  for (const line of out.split("\n")) {
+    const mt = /pts_time:([\d.]+)/.exec(line);
+    if (mt) t = +mt[1];
+    const ms = /lavfi\.scene_score=([\d.]+)/.exec(line);
+    if (ms && t != null) pts.push([t, +ms[1]]);
+  }
+  const win = Math.max(3, Math.round((pts.length / (duration || 1)) * 0.5));
+  const res = [];
+  pts.forEach(([t, s], i) => {
+    /* the first frames have no "previous shot", and a 0.1 s shot at the end is not a shot */
+    if (t < 0.2 || t > duration - 0.1 || s < 0.06) return;
+    const near = [...pts.slice(Math.max(0, i - win), Math.max(0, i - 1)), ...pts.slice(i + 2, i + win + 1)].map(
+      p => p[1],
+    );
+    if (s >= 0.3 || s >= 5 * Math.max(pct(near, 0.5), 0.004)) res.push({ t: +t.toFixed(3), strength: +s.toFixed(2) });
+  });
+  /* two "cuts" less than 0.1 s apart are a single few-frame transition
+     (flash, motion blur, smear): not a 0.03 s shot */
+  const merged = [];
+  for (const c of res) {
+    const prev = merged.at(-1);
+    if (prev && c.t - prev.t < 0.1) {
+      prev.transition = true;
+      prev.strength = Math.max(prev.strength, c.strength);
+    } else merged.push({ ...c });
+  }
+  return merged;
+}
+
+/* motion: mean luminance of the difference between neighbouring frames,
+   normalized to 30 fps (at 60 fps each difference covers half the time) */
+function motion(file, fps) {
+  const out = run("ffmpeg", [
+    "-hide_banner",
+    "-nostats",
+    "-i",
+    file,
+    "-an",
+    "-vf",
+    "scale=180:-2,tblend=all_mode=difference,signalstats,metadata=print:key=lavfi.signalstats.YAVG:file=-",
+    "-f",
+    "null",
+    "-",
+  ]);
+  const pts = [];
+  let t = null;
+  for (const line of out.split("\n")) {
+    const mt = /pts_time:([\d.]+)/.exec(line);
+    if (mt) t = +mt[1];
+    const my = /YAVG=([\d.]+)/.exec(line);
+    if (my && t != null) pts.push([t, (+my[1] * fps) / 30]);
+  }
+  return pts;
+}
+
+const BLOCKS = "▁▂▃▄▅▆▇█";
+const strip = (vals, max) => vals.map(v => BLOCKS[Math.min(7, Math.floor((v / (max || 1)) * 7.999))]).join("");
+const pct = (arr, p) => {
+  const s = [...arr].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.floor(p * s.length))] ?? 0;
+};
+
+function rhythm(pts, duration) {
+  const step = Math.max(0.25, Math.ceil((duration / 60) * 4) / 4);
+  const n = Math.ceil(duration / step);
+  const sum = Array(n).fill(0),
+    count = Array(n).fill(0);
+  for (const [t, e] of pts) {
+    const i = Math.min(n - 1, Math.floor(t / step));
+    sum[i] += e;
+    count[i]++;
+  }
+  const energy = sum.map((s, i) => (count[i] ? s / count[i] : 0));
+  const max = Math.max(...energy);
+  const t = i => +Math.min(duration, i * step).toFixed(2);
+
+  /* Holding is not standing still: particles and slow camera keep alive in
+     the hold. What defines a hold is motion staying STABLE (nothing new
+     arrives on screen) for at least 1 s. */
+  const stable = energy.map((e, i) => i > 0 && Math.abs(e - energy[i - 1]) <= 0.12 * Math.max(e, 0.5));
+  const holds = [];
+  let start = null;
+  for (let i = 0; i <= n; i++) {
+    if (i < n && stable[i]) {
+      if (start == null) start = i;
+      continue;
+    }
+    if (start != null && (i - start) * step >= 1) holds.push([t(start), t(i)]);
+    start = null;
+  }
+
+  /* Change: a sharp rise over the previous half second. Opening already in
+     strong motion counts too. */
+  const median = pct(energy, 0.5);
+  const changes = [];
+  energy.forEach((e, i) => {
+    const before = i === 0 ? null : Math.min(energy[i - 1], energy[i - 2] ?? energy[i - 1]);
+    const rises = before == null ? e > 1.5 * median : e - before > 0.25 + 0.3 * before;
+    if (rises && !(changes.length && t(i) - changes.at(-1) < 0.5)) changes.push(t(i));
+  });
+
+  /* Truly frozen: almost nothing moves (below 12 % of p90). */
+  const threshold = Math.max(0.15, 0.12 * pct(energy, 0.9));
+  const frozen = energy.filter(e => e < threshold).length * step;
+  const holdTime = holds.reduce((s, [a, b]) => s + (b - a), 0);
+  return {
+    step,
+    strip: strip(energy, max),
+    energy: energy.map(e => +e.toFixed(2)),
+    changes,
+    holds,
+    hold_pct: Math.round((100 * holdTime) / duration),
+    frozen_pct: Math.round((100 * frozen) / duration),
+  };
+}
+
+/* palette: thumbnail frames at 2 fps, color quantized and grouped in OKLab */
+const lin = c => {
+  c /= 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+function oklab(r, g, b) {
+  const [R, G, B] = [lin(r), lin(g), lin(b)];
+  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+  const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B);
+  const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+const hex = (r, g, b) =>
+  "#" +
+  [r, g, b]
+    .map(v => Math.round(v).toString(16).padStart(2, "0"))
+    .join("")
+    .toUpperCase();
+
+function palette(file) {
+  const buf = run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      file,
+      "-an",
+      "-vf",
+      "fps=2,scale=48:-2:flags=area",
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "-",
+    ],
+    { binary: true },
+  );
+  const bins = new Map();
+  for (let i = 0; i + 2 < buf.length; i += 3) {
+    const k = ((buf[i] >> 4) << 8) | ((buf[i + 1] >> 4) << 4) | (buf[i + 2] >> 4);
+    const c = bins.get(k) ?? { n: 0, r: 0, g: 0, b: 0 };
+    c.n++;
+    c.r += buf[i];
+    c.g += buf[i + 1];
+    c.b += buf[i + 2];
+    bins.set(k, c);
+  }
+  const total = buf.length / 3;
+  const groups = [];
+  for (const c of [...bins.values()].sort((a, b) => b.n - a.n)) {
+    const lab = oklab(c.r / c.n, c.g / c.n, c.b / c.n);
+    const g = groups.find(g => Math.hypot(g.lab[0] - lab[0], g.lab[1] - lab[1], g.lab[2] - lab[2]) < 0.04);
+    if (g) {
+      g.n += c.n;
+      g.r += c.r;
+      g.g += c.g;
+      g.b += c.b;
+    } else groups.push({ ...c, lab });
+  }
+  return groups
+    .filter(g => g.n / total >= 0.002)
+    .slice(0, 8)
+    .map(g => colorOf(g, total));
+}
+
+function colorOf(g, total) {
+  const [L, a, b] = oklab(g.r / g.n, g.g / g.n, g.b / g.n);
+  return {
+    hex: hex(g.r / g.n, g.g / g.n, g.b / g.n),
+    oklch: `${L.toFixed(3)} ${Math.hypot(a, b).toFixed(3)} ${Math.round(((Math.atan2(b, a) * 180) / Math.PI + 360) % 360)}`,
+    area_pct: +((100 * g.n) / total).toFixed(2),
+  };
+}
+
+/* Accent and text take little area and vanish in the thumbnail average. Here
+   the sample is per point (no averaging) and only counts what has chroma
+   ≥ 0.08 or is far from the dominant background: where accent, text and
+   highlights live. */
+function highlights(file, bgHex) {
+  const buf = run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      file,
+      "-an",
+      "-vf",
+      "fps=2,scale=135:-2:flags=neighbor",
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "-",
+    ],
+    { binary: true },
+  );
+  const f = oklab(...[1, 3, 5].map(i => parseInt(bgHex.slice(i, i + 2), 16)));
+  const bins = new Map();
+  for (let i = 0; i + 2 < buf.length; i += 3) {
+    const lab = oklab(buf[i], buf[i + 1], buf[i + 2]);
+    const chroma = Math.hypot(lab[1], lab[2]);
+    if (chroma < 0.08 && Math.hypot(lab[0] - f[0], lab[1] - f[1], lab[2] - f[2]) < 0.5) continue;
+    const k = ((buf[i] >> 4) << 8) | ((buf[i + 1] >> 4) << 4) | (buf[i + 2] >> 4);
+    const c = bins.get(k) ?? { n: 0, r: 0, g: 0, b: 0 };
+    c.n++;
+    c.r += buf[i];
+    c.g += buf[i + 1];
+    c.b += buf[i + 2];
+    bins.set(k, c);
+  }
+  const total = buf.length / 3;
+  const groups = [];
+  for (const c of [...bins.values()].sort((a, b) => b.n - a.n)) {
+    const lab = oklab(c.r / c.n, c.g / c.n, c.b / c.n);
+    const g = groups.find(g => Math.hypot(g.lab[0] - lab[0], g.lab[1] - lab[1], g.lab[2] - lab[2]) < 0.06);
+    if (g) {
+      g.n += c.n;
+      g.r += c.r;
+      g.g += c.g;
+      g.b += c.b;
+    } else groups.push({ ...c, lab });
+  }
+  return groups
+    .filter(g => g.n / total >= 0.0001)
+    .slice(0, 6)
+    .map(g => colorOf(g, total));
+}
+
+/* surface: hint that the piece is flat drawing (shape, type, UI) or filmed
+   image (photo, b-roll, grain). How many 4-bit colors cover 90 % of the
+   screen, and how many neighbours are equal (flat area), almost equal
+   (gradient, grain, photo) or edge. The library's shape references give 1 to
+   23 colors and 83 to 95 % flat. A hint for reading the sheets, not a
+   verdict: a dark photo also has few colors. */
+function surface(file) {
+  const buf = run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      file,
+      "-an",
+      "-vf",
+      "fps=2,scale=96:-2:flags=area",
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "-",
+    ],
+    { binary: true },
+  );
+  const n = buf.length / 3;
+  const bins = new Map();
+  let equal = 0,
+    smooth = 0;
+  for (let i = 0; i + 2 < buf.length; i += 3) {
+    const k = ((buf[i] >> 4) << 8) | ((buf[i + 1] >> 4) << 4) | (buf[i + 2] >> 4);
+    bins.set(k, (bins.get(k) ?? 0) + 1);
+    if (i < 3) continue;
+    const d = Math.abs(buf[i] - buf[i - 3]) + Math.abs(buf[i + 1] - buf[i - 2]) + Math.abs(buf[i + 2] - buf[i - 1]);
+    if (d <= 6) equal++;
+    else if (d <= 40) smooth++;
+  }
+  let sum = 0,
+    colors_90 = 0;
+  for (const v of [...bins.values()].sort((a, b) => b - a)) {
+    sum += v;
+    colors_90++;
+    if (sum >= 0.9 * n) break;
+  }
+  return { colors_90, flat_pct: Math.round((100 * equal) / n), smooth_pct: Math.round((100 * smooth) / n) };
+}
+
+/* sound: volume every 0.5 s and pulse by autocorrelation of the onsets */
+function sound(file, duration) {
+  const raw = run(
+    "ffmpeg",
+    ["-hide_banner", "-loglevel", "error", "-i", file, "-vn", "-ac", "1", "-ar", "8000", "-f", "f32le", "-"],
+    { binary: true },
+  );
+  const x = new Float32Array(raw.buffer, raw.byteOffset, Math.floor(raw.length / 4));
+  const HOP = 80; /* 10 ms */
+  const e = [];
+  for (let i = 0; i + HOP <= x.length; i += HOP) {
+    let s = 0;
+    for (let j = i; j < i + HOP; j++) s += x[j] * x[j];
+    e.push(s / HOP);
+  }
+  const db = v => 10 * Math.log10(v + 1e-10);
+  const vol = [];
+  for (let i = 0; i < e.length; i += 50) {
+    const slice = e.slice(i, i + 50);
+    vol.push(db(slice.reduce((a, b) => a + b, 0) / slice.length));
+  }
+  const floor = Math.min(...vol);
+  const onsets = e.map((v, i) => Math.max(0, db(v) - db(e[i - 1] ?? v)));
+  const mean = onsets.reduce((a, b) => a + b, 0) / onsets.length;
+  const o = onsets.map(v => v - mean);
+  const auto = L => {
+    let s = 0;
+    for (let i = L; i < o.length; i++) s += o[i] * o[i - L];
+    return s;
+  };
+  const r0 = auto(0) || 1;
+  let best = { L: 0, r: -Infinity };
+  for (let L = 33; L <= 100; L++) {
+    const r = auto(L);
+    if (r > best.r) best = { L, r };
+  }
+  const strength = best.r / r0;
+  return {
+    volume_db: vol.map(v => +v.toFixed(1)),
+    strip: strip(
+      vol.map(v => v - floor),
+      Math.max(...vol) - floor,
+    ),
+    start_db: +vol
+      .slice(0, 4)
+      .reduce((a, b, _, s) => a + b / s.length, 0)
+      .toFixed(1),
+    end_db: +vol
+      .slice(-4)
+      .reduce((a, b, _, s) => a + b / s.length, 0)
+      .toFixed(1),
+    pulse:
+      strength >= 0.1
+        ? { bpm: Math.round(6000 / best.L), every_s: best.L / 100, strength: +strength.toFixed(2) }
+        : null,
+  };
+}
+
+/* --- sheets -------------------------------------------------------------------- */
+function frameWidth(info) {
+  return info.h > info.w ? 180 : 320;
+}
+function columns(info) {
+  return info.h > info.w ? 6 : 4;
+}
+
+function contactSheet(file, info, out) {
+  const step = info.duration <= 20 ? 0.5 : info.duration <= 45 ? 1 : Math.ceil(info.duration / 45);
+  const n = Math.floor(info.duration / step) + 1;
+  const cols = columns(info),
+    rows = Math.ceil(n / cols);
+  run("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-i",
+    file,
+    "-an",
+    "-vf",
+    `fps=1/${step}:round=near,scale=${frameWidth(info)}:-2,tile=${cols}x${rows}:padding=4:margin=4:color=white`,
+    "-frames:v",
+    "1",
+    out,
+  ]);
+  return { step, n, cols };
+}
+
+function cutsSheet(file, info, list, out) {
+  const used = list.slice(0, 12);
+  if (!used.length) return 0;
+  const frames = used.flatMap(c => {
+    const n = Math.round(c.t * info.fps);
+    return [Math.max(0, n - 1), n];
+  });
+  const sel = frames.map(n => `eq(n,${n})`).join("+");
+  run("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-i",
+    file,
+    "-an",
+    "-vf",
+    `select='${sel}',scale=${frameWidth(info)}:-2,tile=2x${used.length}:padding=4:margin=4:color=white`,
+    "-fps_mode",
+    "vfr",
+    "-frames:v",
+    "1",
+    out,
+  ]);
+  return used.length;
+}
+
+/* --- commands ------------------------------------------------------------------ */
+function measure(source, name, outOpt) {
+  if (!source || !name) fail("uso: reference.mjs measure <video|url> <nome> [--out <pasta>]");
+  const dir = resolve(outOpt ?? join(LIBRARY, name));
+  mkdirSync(join(dir, "sheets"), { recursive: true });
+
+  let file;
+  if (/^https?:\/\//.test(source)) {
+    file = join(dir, "video.mp4");
+    if (!existsSync(file)) {
+      console.log("baixando com yt-dlp…");
+      run("yt-dlp", [
+        "-q",
+        "--no-playlist",
+        "-f",
+        "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b",
+        "--merge-output-format",
+        "mp4",
+        "-o",
+        file,
+        source,
+      ]);
+    }
+  } else {
+    const origin = resolve(source);
+    if (!existsSync(origin)) fail(`${origin} não existe`);
+    file = dirname(origin) === dir ? origin : join(dir, `video${extname(origin).toLowerCase()}`);
+    if (file !== origin) copyFileSync(origin, file);
+  }
+
+  const info = probe(file);
+  console.log(
+    `${name} · ${info.duration}s · ${info.w}×${info.h} · ${info.fps} fps${info.audio ? " · com som" : " · sem som"}`,
+  );
+
+  const cutList = cuts(file, info.duration);
+  const shots = [0, ...cutList.map(c => c.t), info.duration]
+    .map((t, i, a) => (i ? +(t - a[i - 1]).toFixed(2) : null))
+    .slice(1);
+  const rhy = rhythm(motion(file, info.fps), info.duration);
+  const colors = palette(file);
+  const accents = highlights(file, colors[0].hex);
+  const surf = surface(file);
+  const audio = info.audio ? sound(file, info.duration) : null;
+  const contacts = contactSheet(file, info, join(dir, "sheets", "contacts.png"));
+  const nCuts = cutsSheet(file, info, cutList, join(dir, "sheets", "cuts.png"));
+
+  const measurements = {
+    name,
+    source,
+    video: basename(file),
+    measured_at: new Date().toISOString().slice(0, 10),
+    ...info,
+    cuts: cutList,
+    shots: {
+      count: shots.length,
+      mean_s: +(info.duration / shots.length).toFixed(2),
+      min_s: Math.min(...shots),
+      max_s: Math.max(...shots),
+      list_s: shots,
+    },
+    rhythm: rhy,
+    palette: colors,
+    highlights: accents,
+    surface: surf,
+    sound: audio,
+    sheets: { contacts: { file: "sheets/contacts.png", ...contacts }, cuts: nCuts ? "sheets/cuts.png" : null },
+  };
+  writeFileSync(join(dir, "measurements.json"), JSON.stringify(measurements, null, 1) + "\n");
+
+  console.log(
+    `planos: ${shots.length}${shots.length === 1 ? " (um plano só, sem corte)" : ` · média ${measurements.shots.mean_s}s · de ${measurements.shots.min_s} a ${measurements.shots.max_s}s`}`,
+  );
+  if (cutList.length)
+    console.log(
+      `cortes em: ${cutList.map(c => `${c.t}s${c.transition ? " (transição de poucos quadros)" : ""}`).join(", ")}`,
+    );
+  console.log(`movimento (cada caractere = ${rhy.step}s): ${rhy.strip}`);
+  console.log(`mudanças em: ${rhy.changes.join(", ")}s`);
+  console.log(
+    `segura ${rhy.hold_pct}% do tempo: ${rhy.holds.map(([a, b]) => `${a}–${b}s`).join(", ") || "nunca por 1 s"}` +
+      (rhy.frozen_pct ? ` · congelado de verdade ${rhy.frozen_pct}% (somando trechos curtos)` : " · nunca congela"),
+  );
+  console.log("paleta por área:");
+  for (const c of colors) console.log(`   ${c.hex}  oklch ${c.oklch.padEnd(16)} ${String(c.area_pct).padStart(6)}%`);
+  console.log("destaques (acento, texto, brilho):");
+  for (const c of accents) console.log(`   ${c.hex}  oklch ${c.oklch.padEnd(16)} ${String(c.area_pct).padStart(6)}%`);
+  const filmed = surf.colors_90 > 60 || surf.flat_pct < 60;
+  console.log(
+    `superfície: ${surf.colors_90} cores cobrem 90% · ${surf.flat_pct}% chapado · ${surf.smooth_pct}% gradiente/grão → ` +
+      (filmed
+        ? "indício de imagem filmada (foto, b-roll, textura): confira nas folhas e diga no Tipo do guia o que o código não reproduz"
+        : "indício de desenho chapado (shape, tipo, UI): reproduzível em código"),
+  );
+  if (audio) {
+    console.log(`som (cada caractere = 0.5s): ${audio.strip}  de ${audio.start_db} a ${audio.end_db} dB`);
+    console.log(
+      audio.pulse
+        ? `pulso: ≈ ${audio.pulse.bpm} BPM, um a cada ${audio.pulse.every_s}s (força ${audio.pulse.strength})`
+        : "pulso: nenhum claro",
+    );
+  }
+  console.log(
+    `folhas: ${join(dir, "sheets", "contacts.png")} (um quadro a cada ${contacts.step}s, ${contacts.cols} por linha)` +
+      (nCuts ? ` · ${join(dir, "sheets", "cuts.png")} (antes | depois de cada corte)` : ""),
+  );
+
+  const guides = readdirSync(dir).filter(f => /\.md$/i.test(f));
+  if (!guides.length) {
+    const summary = `${info.duration} s · ${info.w}×${info.h} · ${info.fps} fps · ${shots.length === 1 ? "um plano só" : `${shots.length} planos`} · ${info.audio ? "com som" : "sem som"}`;
+    const tpl = readFileSync(join(CODE_ROOT, "templates", "reference.md"), "utf8")
+      .replace("<name>", () => name)
+      .replace("<source>", () => source)
+      .replace("<summary>", () => summary);
+    writeFileSync(join(dir, "GUIDE.md"), tpl);
+    console.log(`GUIDE.md criado a partir do modelo: leia as folhas e preencha → ${join(dir, "GUIDE.md")}`);
+  }
+}
+
+function list() {
+  if (!existsSync(LIBRARY)) fail(`${LIBRARY} não existe`);
+  const all = readdirSync(LIBRARY)
+    .filter(d => statSync(join(LIBRARY, d)).isDirectory())
+    .sort();
+  /* disabled in the studio (a `.disabled` in the dir): out of the choice */
+  const disabled = all.filter(d => existsSync(join(LIBRARY, d, ".disabled")));
+  const dirs = all.filter(d => !disabled.includes(d));
+  for (const d of dirs) {
+    const dir = join(LIBRARY, d);
+    const md = readdirSync(dir)
+      .filter(f => /\.md$/i.test(f))
+      .sort((a, b) => (b === "GUIDE.md") - (a === "GUIDE.md"))[0];
+    const text = md ? readFileSync(join(dir, md), "utf8") : "";
+    const title = /^#\s+(.+)$/m.exec(text)?.[1] ?? "(sem guia)";
+    /* GUIDE.md headings stay PT (parsed content) */
+    const essence = /##\s+Ess[êe]ncia\s*\n+([\s\S]*?)(?:\n\n|\n#)/.exec(text)?.[1]?.replace(/\s+/g, " ").trim();
+    const m = existsSync(join(dir, "measurements.json"))
+      ? JSON.parse(readFileSync(join(dir, "measurements.json"), "utf8"))
+      : null;
+    const videos = readdirSync(dir).filter(f => VIDEO_EXT.test(f));
+    console.log(`${d}  ·  ${title}`);
+    if (essence) console.log(`   ${essence.length > 220 ? essence.slice(0, 217) + "…" : essence}`);
+    const type = /##\s+Tipo\s*\n+([^\n]+)/.exec(text)?.[1]?.replace(/\*\*/g, "").trim();
+    console.log(
+      `   tipo: ${type ?? "não classificado (guia sem a seção Tipo: releia com a skill av-reference)"}` +
+        (existsSync(join(dir, "proof", "proof.html")) ? " · com prova em código" : " · sem prova"),
+    );
+    if (m)
+      console.log(
+        `   ${m.duration}s ${m.w}×${m.h} · ${m.shots.count} plano(s) · segura ${m.rhythm.hold_pct}% · ${m.sound?.pulse ? `${m.sound.pulse.bpm} BPM` : "sem pulso"} · movimento ${m.rhythm.strip.slice(0, 60)}`,
+      );
+    console.log(
+      `   guia: ${md ? join(dir, md) : "falta"}${m ? "" : " · sem measurements.json"}${videos.length ? "" : " · vídeo fora da raiz"}`,
+    );
+  }
+  if (disabled.length) console.log(`\ndesligadas (não use): ${disabled.join(", ")}`);
+}
+
+function excerpt(name, t0, t1, fps) {
+  if (!name || t0 == null || t1 == null) fail("uso: reference.mjs excerpt <nome> <t0> <t1> [--fps 15]");
+  const { dir, file } = openRef(name);
+  const info = probe(file);
+  const n = Math.ceil((t1 - t0) * fps);
+  const cols = columns(info);
+  const out = join(dir, "sheets", `excerpt-${t0}-${t1}.png`);
+  mkdirSync(dirname(out), { recursive: true });
+  run("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-ss",
+    String(t0),
+    "-to",
+    String(t1),
+    "-i",
+    file,
+    "-an",
+    "-vf",
+    `fps=${fps},scale=${frameWidth(info)}:-2,tile=${cols}x${Math.ceil(n / cols)}:padding=4:margin=4:color=white`,
+    "-frames:v",
+    "1",
+    out,
+  ]);
+  console.log(`${n} quadros de ${t0}s a ${t1}s (um a cada ${(1 / fps).toFixed(3)}s, ${cols} por linha) → ${out}`);
+}
+
+function frame(name, times) {
+  if (!name || !times.length) fail("uso: reference.mjs frame <nome> <t> [<t> …]");
+  const { dir, file } = openRef(name);
+  mkdirSync(join(dir, "sheets"), { recursive: true });
+  for (const t of times) {
+    const out = join(dir, "sheets", `frame-${t}.png`);
+    run("ffmpeg", ["-y", "-hide_banner", "-loglevel", "error", "-ss", String(t), "-i", file, "-frames:v", "1", out]);
+    console.log(`t = ${t}s → ${out}`);
+  }
+}
+
+/* color: the point's pixel and the 5×5 mean around it. The mean removes
+   compression noise on flat areas; on thin strokes (letters, edges) the pixel counts. */
+function colorAt(name, t, points) {
+  if (!name || !Number.isFinite(t) || !points.length) fail("uso: reference.mjs color <nome> <t> <x>,<y> [<x>,<y> …]");
+  const { file } = openRef(name);
+  const { w, h } = probe(file);
+  const buf = run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-ss",
+      String(t),
+      "-i",
+      file,
+      "-frames:v",
+      "1",
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "-",
+    ],
+    { binary: true },
+  );
+  if (buf.length < w * h * 3) fail(`quadro em ${t}s veio com ${buf.length} bytes, esperava ${w * h * 3}`);
+  const px = (x, y) => {
+    const i = (Math.min(h - 1, Math.max(0, y)) * w + Math.min(w - 1, Math.max(0, x))) * 3;
+    return [buf[i], buf[i + 1], buf[i + 2]];
+  };
+  for (const p of points) {
+    const [x, y] = p.split(",").map(Number);
+    if (!Number.isInteger(x) || !Number.isInteger(y)) fail(`ponto "${p}" não é <x>,<y>`);
+    const mean = { n: 0, r: 0, g: 0, b: 0 };
+    for (let dy = -2; dy <= 2; dy++)
+      for (let dx = -2; dx <= 2; dx++) {
+        const [r, g, b] = px(x + dx, y + dy);
+        mean.n++;
+        mean.r += r;
+        mean.g += g;
+        mean.b += b;
+      }
+    const [r, g, b] = px(x, y);
+    const point = colorOf({ n: 1, r, g, b }, 1),
+      area = colorOf(mean, mean.n);
+    console.log(
+      `(${x}, ${y})  pixel ${point.hex}  oklch ${point.oklch.padEnd(16)}  média 5×5 ${area.hex}  oklch ${area.oklch}`,
+    );
+  }
+}
+
+/* --- curve: measured duration and easing ---------------------------------------- */
+
+/* CSS cubic-bezier: progress at `s` (fraction of time). x(u) is monotonic
+   for x1 and x2 in [0,1], so bisection finds u. */
+function bezier([x1, y1, x2, y2], s) {
+  let lo = 0,
+    hi = 1,
+    u = s;
+  for (let i = 0; i < 22; i++) {
+    const x = 3 * (1 - u) * (1 - u) * u * x1 + 3 * (1 - u) * u * u * x2 + u * u * u;
+    if (x < s) lo = u;
+    else hi = u;
+    u = (lo + hi) / 2;
+  }
+  return 3 * (1 - u) * (1 - u) * u * y1 + 3 * (1 - u) * u * u * y2 + u * u * u;
+}
+
+/* CSS and GSAP names (power1 = quad … power4 = quint), as cubic-bezier */
+const CURVES = {
+  linear: [0, 0, 1, 1],
+  ease: [0.25, 0.1, 0.25, 1],
+  "ease-out": [0, 0, 0.58, 1],
+  "ease-in": [0.42, 0, 1, 1],
+  "ease-in-out": [0.42, 0, 0.58, 1],
+  "sine.out": [0.61, 1, 0.88, 1],
+  "quad.out · power1.out": [0.5, 1, 0.89, 1],
+  "cubic.out · power2.out": [0.33, 1, 0.68, 1],
+  "quart.out · power3.out": [0.25, 1, 0.5, 1],
+  "quint.out · power4.out": [0.22, 1, 0.36, 1],
+  "expo.out": [0.16, 1, 0.3, 1],
+  "circ.out": [0, 0.55, 0.45, 1],
+  "back.out": [0.34, 1.56, 0.64, 1],
+  "sine.in": [0.12, 0, 0.39, 0],
+  "quad.in · power1.in": [0.11, 0, 0.5, 0],
+  "cubic.in · power2.in": [0.32, 0, 0.67, 0],
+  "quart.in · power3.in": [0.5, 0, 0.75, 0],
+  "quint.in · power4.in": [0.64, 0, 0.78, 0],
+  "expo.in": [0.7, 0, 0.84, 0],
+  "back.in": [0.36, 0, 0.66, -0.56],
+  "sine.inOut": [0.37, 0, 0.63, 1],
+  "quad.inOut · power1.inOut": [0.45, 0, 0.55, 1],
+  "cubic.inOut · power2.inOut": [0.65, 0, 0.35, 1],
+  "quart.inOut · power3.inOut": [0.76, 0, 0.24, 1],
+  "quint.inOut · power4.inOut": [0.83, 0, 0.17, 1],
+  "expo.inOut": [0.87, 0, 0.13, 1],
+  "back.inOut": [0.68, -0.6, 0.32, 1.6],
+};
+
+/* RMS error of a whole animation against the frames: still at 0 until
+   `start`, the curve until `end`, still at 1 after. Start, end and curve are
+   fitted together: the "visible" end of an ease-out arrives long before the
+   real end (a 700 ms power4.out seems to end at 400), and trimming before
+   fitting changes the curve and shortens the duration. */
+function animError(c, start, end, pts) {
+  let s = 0;
+  for (const [t, p] of pts) {
+    const q = t <= start ? 0 : t >= end ? 1 : bezier(c, (t - start) / (end - start));
+    s += (q - p) ** 2;
+  }
+  return Math.sqrt(s / pts.length);
+}
+
+/* each named curve with the best start and end on a half-frame grid; then
+   the best three seed a coordinate descent over the four bezier points,
+   the start and the end */
+function fitAnim(pts, startDet, endDet, fps) {
+  const half = 1 / (2 * fps);
+  const starts = [],
+    ends = [];
+  for (let t = startDet - 0.4; t <= startDet + half; t += half) starts.push(t);
+  for (let t = endDet - half; t <= endDet + 0.8; t += half) ends.push(t);
+  const named = Object.entries(CURVES)
+    .map(([name, c]) => {
+      let m = { name, c, e: Infinity };
+      for (const start of starts)
+        for (const end of ends) {
+          if (end - start < 2 * half) continue;
+          const e = animError(c, start, end, pts);
+          if (e < m.e) m = { name, c, start, end, e };
+        }
+      return m;
+    })
+    .sort((a, b) => a.e - b.e);
+
+  let best = null;
+  for (const seed of named.slice(0, 3)) {
+    let m = { c: [...seed.c], start: seed.start, end: seed.end, e: seed.e };
+    for (const step of [0.05, 0.02, 0.01]) {
+      let changed = true;
+      while (changed) {
+        changed = false;
+        for (let k = 0; k < 6; k++)
+          for (const sign of [-1, 1]) {
+            const c = [...m.c];
+            let { start, end } = m;
+            if (k < 4) {
+              c[k] = +(c[k] + sign * step).toFixed(2);
+              if ((k === 0 || k === 2) && (c[k] < 0 || c[k] > 1)) continue;
+            } else if (k === 4) start += sign * half * step * 20;
+            else end += sign * half * step * 20;
+            if (end - start < 2 * half) continue;
+            const e = animError(c, start, end, pts);
+            if (e < m.e - 1e-6) {
+              m = { c, start, end, e };
+              changed = true;
+            }
+          }
+      }
+    }
+    if (!best || m.e < best.e) best = m;
+  }
+  return { free: best, named: named.slice(0, 3) };
+}
+
+/* Tracks what is inside a box of the frame (full-resolution coordinates)
+   and measures, frame by frame, position, size and presence (area × opacity).
+   The channel that changes most becomes progress 0→1, and from it come start,
+   duration, curve and overshoot. The box must hold only the element, start to end. */
+function curve(name, t0, t1, boxTxt, colorTxt, bgTxt) {
+  if (!name || !Number.isFinite(t0) || !Number.isFinite(t1) || t1 <= t0 || !boxTxt) {
+    fail("uso: reference.mjs curve <nome> <t0> <t1> --box <x>,<y>,<w>,<h> [--color #hex] [--background #hex]");
+  }
+  const { dir, file } = openRef(name);
+  const info = probe(file);
+  const [bx, by, bw, bh] = boxTxt.split(",").map(Number);
+  if (![bx, by, bw, bh].every(Number.isInteger) || bw < 4 || bh < 4 || bx + bw > info.w || by + bh > info.h) {
+    fail(`caixa "${boxTxt}" fora do quadro ${info.w}×${info.h} (x,y,w,h em px inteiros)`);
+  }
+  const sw = Math.min(160, bw) & ~1,
+    sh = Math.max(2, Math.round((bh * sw) / bw) & ~1);
+  const scale = bw / sw;
+  const buf = run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-ss",
+      String(t0),
+      "-to",
+      String(t1),
+      "-i",
+      file,
+      "-an",
+      "-vf",
+      `crop=${bw}:${bh}:${bx}:${by},scale=${sw}:${sh}:flags=area`,
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "-",
+    ],
+    { binary: true },
+  );
+  const size = sw * sh * 3,
+    nf = Math.floor(buf.length / size);
+  if (nf < 4) fail(`só ${nf} quadros entre ${t0}s e ${t1}s`);
+  const labOf = h => oklab(...[1, 3, 5].map(i => parseInt(h.slice(i, i + 2), 16)));
+
+  /* background: the requested one, or the most common color on the box border over the range */
+  let bg;
+  if (bgTxt) bg = labOf(bgTxt);
+  else {
+    const cx = new Map();
+    for (let q = 0; q < nf; q++)
+      for (let y = 0; y < sh; y++)
+        for (let x = 0; x < sw; x++) {
+          if (x > 0 && x < sw - 1 && y > 0 && y < sh - 1) continue;
+          const i = q * size + (y * sw + x) * 3;
+          const k = ((buf[i] >> 4) << 8) | ((buf[i + 1] >> 4) << 4) | (buf[i + 2] >> 4);
+          const c = cx.get(k) ?? { n: 0, r: 0, g: 0, b: 0 };
+          c.n++;
+          c.r += buf[i];
+          c.g += buf[i + 1];
+          c.b += buf[i + 2];
+          cx.set(k, c);
+        }
+    const c = [...cx.values()].sort((a, b) => b.n - a.n)[0];
+    bg = oklab(c.r / c.n, c.g / c.n, c.b / c.n);
+    bgTxt = hex(c.r / c.n, c.g / c.n, c.b / c.n);
+  }
+  const target = colorTxt ? labOf(colorTxt) : null;
+  const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+  /* weight of each pixel: with --color, closeness to it; without, distance
+     from the background, scaled to what the element reaches in the range (so a fade shows) */
+  const d = new Float32Array(nf * sw * sh);
+  for (let p = 0; p < d.length; p++) {
+    const lab = oklab(buf[p * 3], buf[p * 3 + 1], buf[p * 3 + 2]);
+    d[p] = target ? Math.max(0, 1 - Math.max(0, dist(lab, target) - 0.06) / 0.1) : dist(lab, bg);
+  }
+  let ref = 1;
+  if (!target) {
+    const strong = [...d].filter(v => v > 0.05);
+    if (!strong.length) fail(`nada se distingue do fundo ${bgTxt} na caixa: aumente a caixa ou passe --color`);
+    ref = Math.max(0.08, pct(strong, 0.9));
+  }
+  const series = [];
+  for (let q = 0; q < nf; q++) {
+    let P = 0,
+      X = 0,
+      Y = 0,
+      XX = 0,
+      YY = 0;
+    for (let y = 0; y < sh; y++)
+      for (let x = 0; x < sw; x++) {
+        const v = d[q * sw * sh + y * sw + x];
+        const w = target ? v : Math.min(1, Math.max(0, (v - 0.03) / (ref - 0.03)));
+        if (!w) continue;
+        P += w;
+        X += w * x;
+        Y += w * y;
+        XX += w * x * x;
+        YY += w * y * y;
+      }
+    const empty = P < 0.002 * sw * sh;
+    const mx = X / P,
+      my = Y / P;
+    series.push({
+      t: +(t0 + q / info.fps).toFixed(3),
+      presence: P / (sw * sh),
+      x: empty ? null : bx + (mx + 0.5) * scale,
+      y: empty ? null : by + (my + 0.5) * scale,
+      size: empty ? null : Math.sqrt(Math.max(0, XX / P - mx * mx) + Math.max(0, YY / P - my * my)) * scale,
+    });
+  }
+
+  /* each channel: where it started, where it went, how far it moved (relative) */
+  const channels = ["x", "y", "size", "presence"]
+    .map(k => {
+      const vals = series.map(s => s[k]);
+      const ok = vals.map((v, i) => [i, v]).filter(([, v]) => v != null);
+      if (ok.length < 4) return null;
+      const v0 = ok[0][1],
+        v1 = ok.at(-1)[1];
+      const span = k === "x" ? bw : k === "y" ? bh : Math.max(...ok.map(([, v]) => v)) || 1;
+      return { k, vals, v0, v1, rel: Math.abs(v1 - v0) / span };
+      /* presence goes last: whatever enters from nothing goes 0 to 100 % even when
+     what matters is the path (position) or the growth (size) */
+    })
+    .filter(c => c && c.rel >= 0.05)
+    .sort((a, b) => (a.k === "presence") - (b.k === "presence") || b.rel - a.rel);
+  if (!channels.length) fail("nada muda na caixa entre t0 e t1 (menos de 5 % em posição, tamanho e presença)");
+
+  const result = channels.map(c => {
+    const { k, vals, v0, v1 } = c;
+    const prog = vals.map(v => (v == null ? (k === "presence" ? 0 : null) : (v - v0) / (v1 - v0)));
+    const valid = prog.map((p, i) => [i, p]).filter(([, p]) => p != null);
+    const first = valid.find(([, p]) => Math.abs(p) > 0.03)?.[0] ?? 0;
+    const last = [...valid].reverse().find(([, p]) => Math.abs(p - 1) > 0.03)?.[0] ?? nf - 1;
+    const a = Math.max(0, first - 1),
+      b = Math.min(nf - 1, last + 1);
+    const tq = i => t0 + i / info.fps;
+    const span = valid.filter(([i]) => i >= a && i <= b);
+    const max = Math.max(...span.map(([, p]) => p)),
+      min = Math.min(...span.map(([, p]) => p));
+    const ms = s => Math.round(s * 1000);
+    const unit = k === "presence" ? "" : "px";
+    const fmt = v => (k === "presence" ? `${(v * 100).toFixed(1)}% da caixa` : `${Math.round(v)}${unit}`);
+    const base = {
+      channel: k,
+      from: fmt(v0),
+      to: fmt(v1),
+      overshoot: max > 1.03 ? +(max - 1).toFixed(2) : 0,
+      anticipation: min < -0.03 ? +(-min).toFixed(2) : 0,
+      strip: strip(
+        span.map(([, p]) => Math.max(0, p - Math.min(0, min))),
+        Math.max(1, max) - Math.min(0, min),
+      ),
+    };
+
+    /* steps: most intervals still and a few big jumps. In CSS, steps(n)
+       (jump-end) holds the whole first step: the real start is one spacing
+       before the first jump, and the duration is n spacings. */
+    const deltas = span.slice(1).map(([i, p], j) => [i, p - span[j][1]]);
+    const jumps = deltas.filter(([, x]) => Math.abs(x) >= 0.04);
+    const still = deltas.filter(([, x]) => Math.abs(x) < 0.01).length;
+    if (
+      deltas.length >= 4 &&
+      still / deltas.length >= 0.5 &&
+      jumps.length >= 2 &&
+      jumps.length <= 12 &&
+      jumps.every(([, x]) => Math.abs(x) >= 0.5 / jumps.length)
+    ) {
+      const n = jumps.length;
+      const spacing = (tq(jumps.at(-1)[0]) - tq(jumps[0][0])) / (n - 1);
+      return {
+        ...base,
+        steps: n,
+        start_s: +(tq(jumps[0][0]) - spacing).toFixed(3),
+        dur_ms: ms(spacing * n),
+        spacing_ms: ms(spacing),
+      };
+    }
+
+    const pts = valid.map(([i, p]) => [tq(i), p]);
+    const { free, named } = fitAnim(pts, tq(a), tq(b), info.fps);
+    return {
+      ...base,
+      steps: null,
+      start_s: +free.start.toFixed(3),
+      dur_ms: ms(free.end - free.start),
+      bezier: free.c.map(v => +v.toFixed(2)),
+      error: +free.e.toFixed(3),
+      named: named.map(x => ({
+        name: x.name,
+        bezier: x.c,
+        start_s: +x.start.toFixed(3),
+        dur_ms: ms(x.end - x.start),
+        error: +x.e.toFixed(3),
+      })),
+    };
+  });
+
+  const frameMs = 1000 / info.fps;
+  console.log(
+    `${name} · ${t0}–${t1}s · caixa ${boxTxt} · ${nf} quadros a ${info.fps} fps (±${Math.round(frameMs)} ms nas pontas) · ${target ? `cor ${colorTxt}` : `fundo ${bgTxt}`}`,
+  );
+  for (const r of result) {
+    console.log(`\n${r.channel}: ${r.from} → ${r.to}`);
+    console.log(`   progresso ${r.strip}`);
+    if (r.steps) {
+      console.log(
+        `   anda em degraus: steps(${r.steps}), um salto a cada ${r.spacing_ms} ms · começa em ${r.start_s}s · ${r.dur_ms} ms (CSS steps, jump-end)`,
+      );
+      continue;
+    }
+    console.log(
+      `   ajuste:   cubic-bezier(${r.bezier.join(", ")})  começa em ${r.start_s}s · ${r.dur_ms} ms · erro ${r.error}`,
+    );
+    for (const n of r.named)
+      console.log(
+        `   perto de: ${n.name.padEnd(28)} cubic-bezier(${n.bezier.join(", ")})  começa em ${n.start_s}s · ${n.dur_ms} ms · erro ${n.error}`,
+      );
+    if (r.overshoot) console.log(`   overshoot: passa ${Math.round(r.overshoot * 100)}% do destino e volta`);
+    if (r.anticipation) console.log(`   antecipação: recua ${Math.round(r.anticipation * 100)}% antes de ir`);
+  }
+  console.log(
+    `\nerro < 0,03: é essa curva, com essa duração (curvas parecidas com durações diferentes dão o mesmo movimento; prefira a nomeada se o erro dela for quase o mesmo). De 0,03 a 0,06, aproximação. Acima, a caixa pegou mais de um elemento ou o movimento tem fases: meça cada uma.`,
+  );
+
+  const mf = join(dir, "measurements.json");
+  if (existsSync(mf)) {
+    const m = JSON.parse(readFileSync(mf, "utf8"));
+    const key = `${t0}-${t1}@${boxTxt}${colorTxt ? `:${colorTxt}` : ""}`;
+    m.curves = [
+      ...(m.curves ?? []).filter(c => c.key !== key),
+      { key, t0, t1, box: boxTxt, color: colorTxt ?? null, channels: result },
+    ];
+    writeFileSync(mf, JSON.stringify(m, null, 1) + "\n");
+    console.log(`gravado em measurements.json → curves["${key}"]`);
+  }
+}
+
+/* --- compare: the proof scene next to the reference ------------------------------- */
+
+/* frame → rgb24 pixels at a fixed size */
+function pixels(png, w, h) {
+  return run(
+    "ffmpeg",
+    [
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-i",
+      png,
+      "-vf",
+      `scale=${w}:${h}:flags=area`,
+      "-frames:v",
+      "1",
+      "-f",
+      "rawvideo",
+      "-pix_fmt",
+      "rgb24",
+      "-",
+    ],
+    { binary: true },
+  );
+}
+
+/* palette of one frame: colors grouped in OKLab, with area fraction */
+function paletteOf(buf) {
+  const groups = [];
+  for (let i = 0; i + 2 < buf.length; i += 3) {
+    const lab = oklab(buf[i], buf[i + 1], buf[i + 2]);
+    const g = groups.find(g => Math.hypot(g.lab[0] - lab[0], g.lab[1] - lab[1], g.lab[2] - lab[2]) < 0.06);
+    if (g) {
+      g.n++;
+      g.r += buf[i];
+      g.g += buf[i + 1];
+      g.b += buf[i + 2];
+    } else groups.push({ lab, n: 1, r: buf[i], g: buf[i + 1], b: buf[i + 2] });
+  }
+  const total = buf.length / 3;
+  return groups
+    .filter(g => g.n / total >= 0.002)
+    .map(g => ({ lab: g.lab, f: g.n / total, hex: hex(g.r / g.n, g.g / g.n, g.b / g.n) }));
+}
+
+/* Palette regardless of layout: each color on one side goes to the nearest
+   on the other, both ways (× 100, like ΔE). Weight is the square root of the
+   area, otherwise the accent (1 % of the screen) vanishes behind the
+   background. A reference color with no match in the proof (ΔE > 8) is
+   "missing"; a proof color with no match in the reference is "extra". */
+function paletteDistance(a, b) {
+  const nearest = (c, q) =>
+    Math.min(...q.map(d => Math.hypot(c.lab[0] - d.lab[0], c.lab[1] - d.lab[1], c.lab[2] - d.lab[2])));
+  const side = (p, q) =>
+    p.reduce((s, c) => s + Math.sqrt(c.f) * nearest(c, q), 0) / p.reduce((s, c) => s + Math.sqrt(c.f), 0);
+  const unmatched = (p, q) => p.filter(c => nearest(c, q) > 0.08).map(c => `${c.hex} ${(100 * c.f).toFixed(1)}%`);
+  return { de: +(50 * (side(a, b) + side(b, a))).toFixed(1), missing: unmatched(a, b), extra: unmatched(b, a) };
+}
+
+/* The proof is a seek-safe scene (templates/scene.html) that recreates an
+   excerpt of the reference at its size. `compare` renders the proof at the
+   requested times, grabs the reference frames and builds one sheet row per
+   pair: reference | proof | difference. Three numbers per pair: structure
+   SSIM (1 = equal), per-point color ΔE (layout and color) and palette ΔE
+   (colors only, wherever they are). The numbers track the proof improving
+   from one round to the next; reading the sheet decides if it looks alike. */
+async function compare(name, scene, pairs, outOpt) {
+  if (!name || !scene || !pairs.length)
+    fail(
+      "uso: reference.mjs compare <nome> <cena.html> <tRef>[:<tCena>] [<tRef>[:<tCena>] …] [--out sheets/comparison.png]",
+    );
+  const { dir, file } = openRef(name);
+  const info = probe(file);
+  const html = resolve(scene);
+  if (!existsSync(html)) fail(`${html} não existe`);
+  const list = pairs.map(p => {
+    const [r, c] = p.split(":").map(Number);
+    return { ref: r, scene: Number.isFinite(c) ? c : r };
+  });
+  if (list.some(p => !Number.isFinite(p.ref))) fail(`pares: <tRef>[:<tCena>], em segundos (recebi ${pairs.join(" ")})`);
+
+  const tmp = join(dir, "sheets", `.compare-${process.pid}`);
+  mkdirSync(tmp, { recursive: true });
+  const r = spawnSync(
+    process.execPath,
+    [
+      join(CODE_ROOT, "tools", "render.mjs"),
+      html,
+      "--frames",
+      join(tmp, "proof"),
+      "--at",
+      list.map(p => p.scene).join(","),
+      "--w",
+      String(info.w),
+      "--h",
+      String(info.h),
+    ],
+    { encoding: "utf8" },
+  );
+  if (r.status !== 0) fail(`render.mjs saiu com ${r.status}: ${(r.stderr || r.stdout).slice(-600)}`);
+
+  const lw = 300,
+    lh = Math.round((info.h * lw) / info.w / 2) * 2;
+  const mw = 36,
+    mh = Math.max(2, Math.round((info.h * mw) / info.w));
+  const rows = [];
+  for (const [i, p] of list.entries()) {
+    const refPng = join(tmp, `ref${i}.png`),
+      proofPng = join(tmp, "proof", `q${String(i).padStart(3, "0")}.png`);
+    run("ffmpeg", [
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-ss",
+      String(p.ref),
+      "-i",
+      file,
+      "-frames:v",
+      "1",
+      refPng,
+    ]);
+    if (!existsSync(proofPng)) fail(`o render não gerou ${proofPng}`);
+    const ssimOut = spawnSync(
+      "ffmpeg",
+      [
+        "-hide_banner",
+        "-nostats",
+        "-i",
+        refPng,
+        "-i",
+        proofPng,
+        "-lavfi",
+        `[0]scale=${lw}:${lh},format=gray[a];[1]scale=${lw}:${lh},format=gray[b];[a][b]ssim`,
+        "-f",
+        "null",
+        "-",
+      ],
+      { encoding: "utf8" },
+    ).stderr;
+    const ssim = +(/All:([\d.]+)/.exec(ssimOut)?.[1] ?? NaN);
+    const a = pixels(refPng, mw, mh),
+      b = pixels(proofPng, mw, mh);
+    let de = 0;
+    for (let k = 0; k + 2 < a.length; k += 3) {
+      const la = oklab(a[k], a[k + 1], a[k + 2]),
+        lb = oklab(b[k], b[k + 1], b[k + 2]);
+      de += Math.hypot(la[0] - lb[0], la[1] - lb[1], la[2] - lb[2]);
+    }
+    const pa = paletteOf(pixels(refPng, 96, Math.round((info.h * 96) / info.w))),
+      pb = paletteOf(pixels(proofPng, 96, Math.round((info.h * 96) / info.w)));
+    const pal = paletteDistance(pa, pb);
+    rows.push({
+      ref: p.ref,
+      scene: p.scene,
+      ssim: +ssim.toFixed(3),
+      delta_e: +((100 * de) / (a.length / 3)).toFixed(1),
+      palette_de: pal.de,
+      missing: pal.missing,
+      extra: pal.extra,
+      refPng,
+      proofPng,
+    });
+  }
+
+  const out = resolve(dir, outOpt ?? join("sheets", "comparison.png"));
+  mkdirSync(dirname(out), { recursive: true });
+  const inputs = rows.flatMap(l => ["-i", l.refPng, "-i", l.proofPng]);
+  const filter =
+    rows
+      .map(
+        (_, i) =>
+          `[${2 * i}]scale=${lw}:${lh},format=rgb24,split[r${i}][rd${i}];[${2 * i + 1}]scale=${lw}:${lh},format=rgb24,split[p${i}][pd${i}];` +
+          `[rd${i}][pd${i}]blend=all_mode=difference,lutrgb=r='min(255,val*3)':g='min(255,val*3)':b='min(255,val*3)'[d${i}];` +
+          `[r${i}]pad=iw+4:ih:0:0:white[rr${i}];[p${i}]pad=iw+4:ih:0:0:white[pp${i}];[rr${i}][pp${i}][d${i}]hstack=3,pad=iw+8:ih+8:4:4:white[l${i}]`,
+      )
+      .join(";") +
+    (rows.length > 1 ? `;${rows.map((_, i) => `[l${i}]`).join("")}vstack=${rows.length}[out]` : ";[l0]null[out]");
+  run("ffmpeg", [
+    "-y",
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    ...inputs,
+    "-filter_complex",
+    filter,
+    "-map",
+    "[out]",
+    "-frames:v",
+    "1",
+    out,
+  ]);
+  rmSync(tmp, { recursive: true, force: true });
+
+  console.log(`${name} × ${basename(html)} · ${info.w}×${info.h}`);
+  console.log("t ref → t prova      SSIM   ΔE cor   ΔE paleta");
+  for (const l of rows) {
+    console.log(
+      `${String(l.ref).padStart(6)}s → ${String(l.scene).padEnd(7)}s  ${l.ssim.toFixed(3)}  ${String(l.delta_e).padStart(6)}  ${String(l.palette_de).padStart(9)}`,
+    );
+    if (l.missing.length) console.log(`         falta na prova: ${l.missing.join(" · ")}`);
+    if (l.extra.length) console.log(`         sobra na prova: ${l.extra.join(" · ")}`);
+  }
+  const mean = k => +(rows.reduce((s, l) => s + l[k], 0) / rows.length).toFixed(k === "ssim" ? 3 : 1);
+  console.log(
+    `média                 ${mean("ssim").toFixed(3)}  ${String(mean("delta_e")).padStart(6)}  ${String(mean("palette_de")).padStart(9)}`,
+  );
+  console.log(`folha: ${out} (cada linha: estilo visual | prova | diferença ×3). Leia com Read.`);
+  console.log(
+    "ΔE paleta perto de 1: as mesmas cores; o que diz o que corrigir é a lista do que falta e do que sobra. SSIM e ΔE cor caem com layout diferente, mesmo no estilo certo: compare de uma volta para outra.",
+  );
+
+  const mf = join(dir, "measurements.json");
+  if (existsSync(mf)) {
+    const m = JSON.parse(readFileSync(mf, "utf8"));
+    const round = {
+      at: new Date().toISOString().slice(0, 16),
+      scene: relative(dir, html),
+      sheet: relative(dir, out),
+      pairs: rows.map(({ refPng, proofPng, ...l }) => l),
+      mean: { ssim: mean("ssim"), delta_e: mean("delta_e"), palette_de: mean("palette_de") },
+    };
+    m.proofs = [...(m.proofs ?? []), round].slice(-10);
+    writeFileSync(mf, JSON.stringify(m, null, 1) + "\n");
+    console.log(`gravado em measurements.json → proofs (volta ${m.proofs.length})`);
+  }
+}
+
+/* --- cli ------------------------------------------------------------------------ */
+const [cmd, ...rest] = process.argv.slice(2);
+const opt = (n, d) => {
+  const i = rest.indexOf(`--${n}`);
+  return i < 0 ? d : rest.splice(i, 2)[1];
+};
+if (cmd === "list") list();
+else if (cmd === "measure") {
+  const out = opt("out");
+  measure(rest[0], rest[1], out);
+} else if (cmd === "excerpt") {
+  const fps = +opt("fps", 15);
+  excerpt(rest[0], +rest[1], +rest[2], fps);
+} else if (cmd === "frame") frame(rest[0], rest.slice(1).map(Number));
+else if (cmd === "color") colorAt(rest[0], +rest[1], rest.slice(2));
+else if (cmd === "curve") {
+  const box = opt("box"),
+    color = opt("color"),
+    bg = opt("background");
+  curve(rest[0], +rest[1], +rest[2], box, color, bg);
+} else if (cmd === "compare") {
+  const out = opt("out");
+  await compare(rest[0], rest[1], rest.slice(2), out);
+} else {
+  /* usage = the header banner */
+  const lines = readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n");
+  console.log(lines.slice(1, lines.findIndex(l => l.includes("=== */")) + 1).join("\n"));
+  process.exit(2);
+}