@litfamily/lithermes 1.0.8 → 1.0.9

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/stills.mjs

@@ -0,0 +1,71 @@
+// The stills set every render writes, on both paths: each beat's midpoint, a
+// transition strip per cut (6 frames before, the cut, 6 after), a 12-frame
+// contact sheet and the poster frame, listed with their SHA-256 in
+// stills/stills.json. `look` accepts only frames from the latest set.
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { areaResize, contactSheet, pngEncode } from './encode.mjs';
+import { writeJson } from './director.mjs';
+
+const sha = (data) => createHash('sha256').update(data).digest('hex');
+const pad = (n) => String(n).padStart(2, '0');
+
+// beats: [{ index, first, last, mid }] in frames.
+export function stillsPlan({ totalFrames, beats }) {
+  const clamp = (f) => Math.max(0, Math.min(totalFrames - 1, f));
+  const mids = beats.map((b) => ({ index: b.index, frame: clamp(b.mid) }));
+  const cuts = beats.slice(1).map((b, i) => ({ index: i + 1, frame: clamp(b.first), frames: [clamp(b.first - 6), clamp(b.first), clamp(b.first + 6)] }));
+  const contact = Array.from({ length: 12 }, (_, i) => Math.round((i * (totalFrames - 1)) / 11));
+  const poster = clamp(beats[Math.floor(beats.length / 2)].mid);
+  const reduced = clamp(beats[beats.length - 1].mid);
+  const frames = [...new Set([...mids.map((m) => m.frame), ...cuts.flatMap((c) => c.frames), ...contact, poster, reduced])].sort((a, b) => a - b);
+  return { mids, cuts, contact, poster, reduced, frames };
+}
+
+function strip(PNG, images, width, height) {
+  const portrait = height > width;
+  const cellW = portrait ? 360 : 640;
+  const tiles = images.map((rgba) => areaResize(rgba, width, height, cellW));
+  const cellH = tiles[0].height, gap = 6;
+  const W = tiles.length * cellW + (tiles.length + 1) * gap, H = cellH + 2 * gap;
+  const buf = Buffer.alloc(W * H * 4);
+  for (let i = 0; i < buf.length; i += 4) { buf[i] = 30; buf[i + 1] = 32; buf[i + 2] = 36; buf[i + 3] = 255; }
+  tiles.forEach((tile, k) => {
+    const left = gap + k * (cellW + gap);
+    for (let y = 0; y < cellH; y++) tile.data.copy(buf, ((gap + y) * W + left) * 4, y * cellW * 4, (y + 1) * cellW * 4);
+  });
+  return pngEncode(PNG, buf, W, H);
+}
+
+// pngs: Map frame -> PNG bytes of the full-size capture (or a function frame -> PNG bytes).
+export function writeStillsSet({ out, PNG, pngs, plan, size, round, mode, posterPng = null }) {
+  const [W, H] = size;
+  const get = (f) => (typeof pngs === 'function' ? pngs(f) : pngs.get(f));
+  const decoded = new Map();
+  const rgba = (f) => { if (!decoded.has(f)) decoded.set(f, PNG.sync.read(get(f)).data); return decoded.get(f); };
+  rmSync(join(out, 'stills'), { recursive: true, force: true });
+  mkdirSync(join(out, 'stills'), { recursive: true });
+  mkdirSync(join(out, 'sheet'), { recursive: true });
+  const files = [];
+  const put = (rel, bytes, entry) => { writeFileSync(join(out, rel), bytes); files.push({ file: rel, sha256: sha(bytes), ...entry }); };
+  for (const m of plan.mids) put(`stills/beat-${pad(m.index + 1)}-f${m.frame}.png`, get(m.frame), { kind: 'beat-mid', beat: m.index, frame: m.frame });
+  for (const c of plan.cuts) put(`stills/strip-${pad(c.index)}-f${c.frame}.png`, strip(PNG, c.frames.map(rgba), W, H), { kind: 'strip', cut: c.index, frames: c.frames });
+  if (posterPng) put('stills/poster.png', posterPng, { kind: 'poster', frame: plan.poster });
+  else put(`stills/poster-f${plan.poster}.png`, get(plan.poster), { kind: 'poster', frame: plan.poster });
+  const sheetFile = join(out, 'sheet', 'contact.png');
+  contactSheet(PNG, plan.contact.map((f) => ({ data: rgba(f), width: W, height: H, frame: f })), sheetFile);
+  const sheetBytes = readFileSync(sheetFile);
+  files.push({ file: 'sheet/contact.png', sha256: sha(sheetBytes), kind: 'contact', frames: plan.contact });
+  const set = { schema: 'lithermes.stills/v1', round, mode, size, files, required: files.map((f) => f.file), manifestSha256: null };
+  writeJson(join(out, 'stills', 'stills.json'), set);
+  return { file: 'stills/stills.json', files, set };
+}
+
+// Once manifest.json exists, the stills set records its hash; `look` checks it.
+export function stampStills(out) {
+  const file = join(out, 'stills', 'stills.json');
+  const set = JSON.parse(readFileSync(file, 'utf8'));
+  set.manifestSha256 = sha(readFileSync(join(out, 'manifest.json')));
+  writeJson(file, set);
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/stroke.mjs

@@ -0,0 +1,231 @@
+// Single-stroke plotter type from the five OFL EMS SVG fonts (MO-FT-08), laid
+// out as polylines so a pen can write text progressively. Adapted from
+// mexicat/pdoom-video app/src/engine/stroke.ts (MIT, see NOTICE): the optical
+// pair-kerning and writtenLength() method are kept; SVG parsing runs in Node
+// with a small attribute reader instead of the browser DOMParser.
+import { polylineLengths } from './util.mjs';
+
+export const STROKE_FONTS = Object.freeze({
+  readable: 'EMSReadability.svg',
+  script: 'EMSAllure.svg',
+  tech: 'EMSTech.svg',
+  osmotron: 'EMSOsmotron.svg',
+  felix: 'EMSFelix.svg',
+});
+const CONNECTED = new Set(['script']);
+
+const attr = (tag, name) => {
+  const match = tag.match(new RegExp(`\\s${name}="([^"]*)"`));
+  return match ? match[1] : null;
+};
+const decodeEntity = (value) => value
+  .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+  .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number(dec)))
+  .replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+
+function parsePath(d) {
+  const out = [];
+  const tokens = String(d || '').match(/[MLml]|-?\d*\.?\d+(?:e-?\d+)?/g) || [];
+  let current = null, command = 'M';
+  for (let i = 0; i < tokens.length;) {
+    const token = tokens[i];
+    if (/[MLml]/.test(token)) { command = token.toUpperCase(); i++; continue; }
+    const x = parseFloat(tokens[i]), y = parseFloat(tokens[i + 1]);
+    i += 2;
+    if (command === 'M') { current = [{ x, y }]; out.push(current); command = 'L'; }
+    else current?.push({ x, y });
+  }
+  return out;
+}
+
+const inkBox = (strokes) => {
+  let x0 = Infinity, x1 = -Infinity, y0 = Infinity, y1 = -Infinity;
+  for (const s of strokes) for (const p of s) { x0 = Math.min(x0, p.x); x1 = Math.max(x1, p.x); y0 = Math.min(y0, p.y); y1 = Math.max(y1, p.y); }
+  return { x0, x1, y0, y1 };
+};
+
+const ROWS = 90, SHADE = 0.4, CLEAR = 0.1, STRENGTH = 0.6;
+const OPEN_R = new Set("AFLPTVWYKXfrvwyk7'\"’”".split(''));
+const OPEN_L = new Set("AJTVWYXvwyj.,'\"’”…".split(''));
+
+export function parseStrokeFont(svgText, name = 'readable') {
+  const fontFace = svgText.match(/<font-face\b[^>]*>/)?.[0] || '';
+  const fontTag = svgText.match(/<font\b[^>]*>/)?.[0] || '';
+  const defaultAdvance = parseFloat(attr(fontTag, 'horiz-adv-x') || '500');
+  const glyphs = new Map();
+  for (const tag of svgText.match(/<glyph\b[^>]*>/g) || []) {
+    const unicode = attr(tag, 'unicode');
+    if (unicode == null) continue;
+    glyphs.set(decodeEntity(unicode), {
+      adv: parseFloat(attr(tag, 'horiz-adv-x') || String(defaultAdvance)),
+      strokes: parsePath(attr(tag, 'd')),
+    });
+  }
+  let yLo = Infinity, yHi = -Infinity;
+  for (const g of glyphs.values()) for (const s of g.strokes) for (const p of s) { yLo = Math.min(yLo, p.y); yHi = Math.max(yHi, p.y + 1); }
+  const H = inkBox(glyphs.get('H')?.strokes ?? [[{ x: 0, y: 0 }, { x: 0, y: 700 }]]);
+  const X = inkBox(glyphs.get('x')?.strokes ?? [[{ x: 0, y: 0 }, { x: 0, y: 450 }]]);
+  return {
+    name,
+    upm: parseFloat(attr(fontFace, 'units-per-em') || '1000'),
+    glyphs, missingAdv: defaultAdvance,
+    base: H.y0, xTop: X.y1, capTop: H.y1,
+    yLo, dy: (yHi - yLo) / ROWS,
+    profiles: new Map(), kerns: new Map(), target: null,
+  };
+}
+
+function profile(font, ch) {
+  if (font.profiles.has(ch)) return font.profiles.get(ch);
+  const g = font.glyphs.get(ch);
+  let result = null;
+  if (g && g.strokes.length) {
+    const l = new Float64Array(ROWS).fill(NaN), r = new Float64Array(ROWS).fill(NaN);
+    const put = (x, y) => {
+      const i = Math.floor((y - font.yLo) / font.dy);
+      if (i < 0 || i >= ROWS) return;
+      if (!(l[i] <= x)) l[i] = x;
+      if (!(r[i] >= x)) r[i] = x;
+    };
+    for (const s of g.strokes) {
+      if (s.length === 1) put(s[0].x, s[0].y);
+      for (let k = 1; k < s.length; k++) {
+        const a = s[k - 1], b = s[k];
+        const n = Math.max(1, Math.ceil(Math.hypot(b.x - a.x, b.y - a.y) / (font.dy * 0.35)));
+        for (let j = 0; j <= n; j++) put(a.x + ((b.x - a.x) * j) / n, a.y + ((b.y - a.y) * j) / n);
+      }
+    }
+    const widen = (k) => {
+      const lw = new Float64Array(ROWS).fill(NaN), rw = new Float64Array(ROWS).fill(NaN);
+      for (let i = 0; i < ROWS; i++) for (let j = 0; j < ROWS; j++) {
+        const d = Math.abs(i - j) * font.dy * k;
+        if (!Number.isNaN(l[j]) && !(lw[i] <= l[j] + d)) lw[i] = l[j] + d;
+        if (!Number.isNaN(r[j]) && !(rw[i] >= r[j] - d)) rw[i] = r[j] - d;
+      }
+      return [lw, rw];
+    };
+    const [lw, rw] = widen(SHADE), [l45, r45] = widen(1);
+    result = { l: lw, r: rw, l45, r45 };
+  }
+  font.profiles.set(ch, result);
+  return result;
+}
+
+const isLower = (ch) => ch !== ch.toUpperCase() && ch === ch.toLowerCase();
+const isLetter = (ch) => /[\p{L}\p{N}]/u.test(ch);
+
+function approach(font, a, b) {
+  const pa = profile(font, a), pb = profile(font, b);
+  if (!pa || !pb) return null;
+  const adv = font.glyphs.get(a).adv;
+  const lower = isLower(a) || isLower(b) || !isLetter(a) || !isLetter(b);
+  const top = lower ? font.xTop : font.capTop;
+  const i0 = Math.max(0, Math.floor((font.base - font.yLo) / font.dy));
+  const i1 = Math.min(ROWS - 1, Math.floor((top - font.yLo) / font.dy));
+  let m = Infinity;
+  for (let i = i0; i <= i1; i++) {
+    const ra = pa.r[i], lb = pb.l[i];
+    if (!Number.isNaN(ra) && !Number.isNaN(lb)) m = Math.min(m, adv + lb - ra);
+  }
+  return m === Infinity ? null : m;
+}
+
+function pairKern(font, a, b) {
+  if (a === ' ' || b === ' ' || !(OPEN_R.has(a) || OPEN_L.has(b))) return 0;
+  if (!isLetter(a) && !isLetter(b)) return 0;
+  const key = a + b;
+  if (font.kerns.has(key)) return font.kerns.get(key);
+  if (!font.target) {
+    const mean = (pairs) => pairs.map((p) => approach(font, p[0], p[1]) ?? 0).reduce((x, y) => x + y, 0) / pairs.length;
+    font.target = { lc: mean(['nn', 'oo', 'no', 'on']), uc: mean(['HH', 'OO', 'HO', 'OH']) };
+  }
+  const m = approach(font, a, b);
+  let k = 0;
+  if (m !== null) {
+    const lower = isLower(a) || isLower(b) || !isLetter(a) || !isLetter(b);
+    k = Math.max(-0.15 * font.upm, Math.min(0, STRENGTH * ((lower ? font.target.lc : font.target.uc) - m)));
+    const pa = profile(font, a), pb = profile(font, b), adv = font.glyphs.get(a).adv;
+    let near = Infinity;
+    for (let i = 0; i < ROWS; i++) {
+      const ra = pa.r45[i], lb = pb.l45[i];
+      if (!Number.isNaN(ra) && !Number.isNaN(lb)) near = Math.min(near, adv + lb - ra);
+    }
+    k = Math.max(k, Math.min(0, CLEAR * font.upm - near));
+  }
+  font.kerns.set(key, k);
+  return k;
+}
+
+// Polylines in px (origin left baseline, y down) with cumulative lengths for writing.
+export function strokeText(font, text, size, tracking = 0) {
+  const s = size / font.upm;
+  const kern = !CONNECTED.has(font.name);
+  const strokes = [], charOf = [];
+  let x = 0;
+  const chars = Array.from(text);
+  chars.forEach((ch, ci) => {
+    const g = font.glyphs.get(ch);
+    for (const st of g?.strokes ?? []) {
+      strokes.push(st.map((p) => ({ x: x + p.x * s, y: -p.y * s })));
+      charOf.push(ci);
+    }
+    x += (g?.adv ?? font.missingAdv) * s + tracking;
+    if (kern && ci + 1 < chars.length) x += pairKern(font, ch, chars[ci + 1]) * s;
+  });
+  const lens = strokes.map((p) => polylineLengths(p));
+  const startLen = [];
+  let acc = 0;
+  for (const L of lens) { startLen.push(acc); acc += L[L.length - 1] ?? 0; }
+  const charRange = chars.map(() => [Infinity, -Infinity]);
+  strokes.forEach((_, i) => {
+    const r = charRange[charOf[i]];
+    r[0] = Math.min(r[0], startLen[i]);
+    r[1] = Math.max(r[1], startLen[i] + (lens[i][lens[i].length - 1] ?? 0));
+  });
+  let last = 0;
+  for (const r of charRange) {
+    if (r[0] === Infinity) { r[0] = last; r[1] = last; }
+    last = r[1];
+  }
+  return { strokes, startLen, lens, total: acc, width: x - tracking, charRange, size, missing: chars.filter((ch) => ch.trim() && !font.glyphs.has(ch)) };
+}
+
+// Pen distance at time t from each character's own [start, end] window, so the
+// pen follows the timeline's word timing instead of a fixed px/s constant.
+export function writtenLength(layout, charTimes, t) {
+  let len = 0;
+  for (let i = 0; i < layout.charRange.length; i++) {
+    const [a, b] = layout.charRange[i];
+    const [t0, t1] = charTimes[i] ?? [Infinity, Infinity];
+    if (t >= t1) len = b;
+    else if (t > t0) { len = a + (b - a) * ((t - t0) / Math.max(1e-3, t1 - t0)); break; }
+    else break;
+  }
+  return len;
+}
+
+// The written prefix of each polyline as flat coordinate arrays for the page.
+export function writtenStrokes(layout, len) {
+  const out = [];
+  for (let i = 0; i < layout.strokes.length; i++) {
+    const s0 = layout.startLen[i];
+    if (s0 >= len) break;
+    const pts = layout.strokes[i], L = layout.lens[i], remain = len - s0;
+    const flat = [pts[0].x, pts[0].y];
+    let j = 1;
+    for (; j < pts.length && L[j] <= remain; j++) flat.push(pts[j].x, pts[j].y);
+    if (j < pts.length) {
+      const a = pts[j - 1], b = pts[j];
+      const u = (remain - L[j - 1]) / Math.max(1e-6, L[j] - L[j - 1]);
+      flat.push(a.x + (b.x - a.x) * u, a.y + (b.y - a.y) * u);
+    }
+    out.push(flat);
+  }
+  return out;
+}
+
+export function strokeBounds(layout) {
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const s of layout.strokes) for (const p of s) { x0 = Math.min(x0, p.x); x1 = Math.max(x1, p.x); y0 = Math.min(y0, p.y); y1 = Math.max(y1, p.y); }
+  return Number.isFinite(x0) ? [x0, y0, x1, y1] : null;
+}

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/timeline.mjs

@@ -0,0 +1,177 @@
+// Brief -> canonical timeline (§A4, §A10). Tier 1 paces each unit at 1.25x its
+// reading floor and snaps every cut FORWARD to the beat grid, never shortening a
+// hold (MO-A-06/09/10/14/15/16). Tier 2 swaps the fixed-BPM grid for the beats a
+// pre-warmed librosa venv detected in the user's own audio. The anchor-and-snap
+// idea is the only thing taken from pdoom's timeline method; nothing of its
+// content is used.
+import { FRAME, OUTPUT, READING, TIMING } from './constants.mjs';
+import { eojeols, readingCounts, readingFloor, scriptOf, smart, plain } from './type.mjs';
+
+export const SCENES = Object.freeze(['title-slam', 'karaoke-line', 'kinetic-list', 'number-counter', 'stroke-signature', 'end-card']);
+const LIST_SPLIT = /\s*(?:·|•|\||;|,|\/)\s*/u;
+
+export function listItems(text) {
+  return String(text).split(LIST_SPLIT).map((item) => item.trim()).filter(Boolean);
+}
+
+export function defaultScene(text, index, count) {
+  if (index === 0) return 'title-slam';
+  if (count >= 2 && index === count - 1) return 'end-card';
+  if (/\d/.test(text)) return 'number-counter';
+  if (listItems(text).length >= 3) return 'kinetic-list';
+  return 'karaoke-line';
+}
+
+// Grid of beat times starting at 0 (the film start is always an anchor).
+export function makeGrid({ bpm, beats }) {
+  if (beats?.length) {
+    const sorted = [...new Set(beats.filter((b) => Number.isFinite(b) && b > 0))].sort((a, b) => a - b);
+    const gaps = sorted.slice(1).map((b, i) => b - sorted[i]).sort((a, b) => a - b);
+    const step = gaps.length ? gaps[Math.floor(gaps.length / 2)] : 60 / bpm;
+    return { beat: step, at: (target) => {
+      const hit = sorted.find((b) => b >= target - 1e-9);
+      if (target <= 1e-9) return 0;
+      if (hit !== undefined) return hit;
+      const last = sorted.at(-1) ?? 0;
+      return last + Math.ceil((target - last - 1e-9) / step) * step;
+    } };
+  }
+  const beat = 60 / bpm;
+  return { beat, at: (target) => Math.ceil((target - 1e-9) / beat) * beat };
+}
+
+const frameRound = (t, fps) => Math.round(t * fps) / fps;
+const fix = (x) => Math.round(x * 1e6) / 1e6;
+
+function revealSteps(parts, lineFloor, quarter) {
+  const weights = parts.map((p) => {
+    const { H, W } = readingCounts(p);
+    return Math.max(0.05, READING.hangulSecPerSyllable * H + W / READING.englishWordsPerSec);
+  });
+  const total = weights.reduce((a, b) => a + b, 0);
+  return parts.map((_, j) => {
+    const share = TIMING.paceMargin * lineFloor * (weights[j] / total);
+    return Math.ceil(Math.max(READING.revealFloor, share) / quarter - 1e-9) * quarter;
+  });
+}
+
+export function normalizeBrief(raw) {
+  if (!raw || typeof raw !== 'object') throw Object.assign(new Error('brief must be a JSON object'), { userError: true });
+  const text = Array.isArray(raw.text) ? raw.text : typeof raw.text === 'string' ? [raw.text] : null;
+  if (!text || !text.length || !text.every((line) => typeof line === 'string' && line.trim())) {
+    throw Object.assign(new Error('brief.text must be a non-empty list of display lines'), { userError: true });
+  }
+  if (raw.scenes && (!Array.isArray(raw.scenes) || raw.scenes.some((s) => s != null && !SCENES.includes(s)))) {
+    throw Object.assign(new Error(`brief.scenes entries must be one of ${SCENES.join(', ')}`), { userError: true });
+  }
+  const bpm = raw.bpm == null ? TIMING.defaultBpm : Number(raw.bpm);
+  if (!Number.isFinite(bpm) || bpm < TIMING.minBpm || bpm > TIMING.maxBpm) {
+    throw Object.assign(new Error(`brief.bpm must be ${TIMING.minBpm}..${TIMING.maxBpm}`), { userError: true });
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (typeof item === 'string' && /<[^<>\n]{1,80}>/u.test(item)) throw Object.assign(new Error(`brief.${key} still holds an example placeholder (${item}); write this film's own value`), { userError: true });
+    }
+  }
+  if (raw.durationSec != null && !(Number(raw.durationSec) >= 4 && Number(raw.durationSec) <= 90)) {
+    throw Object.assign(new Error('brief.durationSec must be 4..90'), { userError: true });
+  }
+  return { ...raw, text: text.map((line) => line.trim()), bpm, seed: Number.isInteger(raw.seed) ? raw.seed >>> 0 : 20260926 };
+}
+
+export function buildTimeline(brief, { presetId, fps = FRAME.fps, audioGrid = null } = {}) {
+  const grid = makeGrid(audioGrid ? { bpm: audioGrid.bpm, beats: audioGrid.beats } : { bpm: brief.bpm });
+  const beat = grid.beat, quarter = beat / 4;
+  const typed = presetId === 'terminalcore';
+  const warnings = [];
+  const lines = brief.text.map((line) => (typed ? plain(line) : smart(line)));
+  const plan = lines.map((text, index) => {
+    let sceneId = brief.scenes?.[index] || defaultScene(text, index, lines.length);
+    if (sceneId === 'stroke-signature' && /[가-힣ᄀ-ᇿ㄰-㆏]/u.test(text)) {
+      warnings.push(`line ${index + 1}: the stroke fonts have no Hangul, so it uses title-slam instead of stroke-signature`);
+      sceneId = 'title-slam';
+    }
+    if (sceneId === 'number-counter' && !/\d/.test(text)) sceneId = 'karaoke-line';
+    if (sceneId === 'kinetic-list' && listItems(text).length < 2) sceneId = 'karaoke-line';
+    return { text, sceneId };
+  });
+  const lay = (scale) => {
+    const uses = new Map();
+    const units = [];
+    let cursor = 0, gridBeat = 0;
+    plan.forEach(({ text, sceneId }) => {
+      const shotIndex = uses.get(sceneId) ?? 0;
+      uses.set(sceneId, shotIndex + 1);
+      const id = shotIndex === 0 ? sceneId : `${sceneId}-${shotIndex + 1}`;
+      const floor = readingFloor(text, 'line');
+      const { C } = readingCounts(text);
+      let need = Math.max(TIMING.paceMargin * floor, C / READING.englishCps + 1 / fps, TIMING.minSceneBeats * beat);
+      let parts = [], steps = [];
+      if (sceneId === 'karaoke-line') parts = eojeols(text);
+      if (sceneId === 'kinetic-list') parts = listItems(text);
+      if (parts.length > 1) {
+        steps = revealSteps(parts, floor, quarter);
+        need = Math.max(need, steps.reduce((a, b) => a + b, 0) + beat);
+      }
+      if (sceneId === 'number-counter') need = Math.max(need, 1.2 + beat);
+      if (sceneId === 'stroke-signature') need = Math.max(need, 0.11 * Array.from(text).length + beat);
+      if (sceneId === 'end-card') need = Math.max(need, TIMING.paceMargin * floor + beat);
+      need *= scale;
+      const start = cursor;
+      const endBeat = grid.at(gridBeat + need);
+      const end = frameRound(endBeat, fps);
+      units.push({ id, sceneId, shotIndex, start: fix(start), end: fix(end), holdSec: fix(end - start), kind: 'line', text, script: scriptOf(text), beatSec: fix(gridBeat) });
+      let t = gridBeat;
+      parts.forEach((part, j) => {
+        if (parts.length < 2) return;
+        const rs = frameRound(t, fps), re = frameRound(t + steps[j], fps);
+        units.push({ id: `${id}/r${j}`, sceneId, shotIndex, start: fix(rs), end: fix(re), holdSec: fix(re - rs), kind: 'reveal', text: part, script: scriptOf(part), beatSec: fix(t) });
+        t += steps[j];
+      });
+      cursor = end;
+      gridBeat = endBeat;
+    });
+    return units;
+  };
+  // A treatment length scales every hold up (reveal steps stay on their floors)
+  // until the film reaches it; the floors are never cut to meet a shorter one.
+  let units = lay(1);
+  const target = Number(brief.durationSec);
+  if (Number.isFinite(target) && target > 0) {
+    const endOf = (list) => list.filter((u) => u.kind === 'line').at(-1).end;
+    const natural = endOf(units);
+    if (natural < target - 1e-9) {
+      let lo = 1, hi = 2 * target / natural;
+      for (let i = 0; i < 40; i++) {
+        const mid = (lo + hi) / 2;
+        if (endOf(lay(mid)) >= target - 1e-9) hi = mid; else lo = mid;
+      }
+      units = lay(hi);
+    } else if (natural > target + beat) {
+      warnings.push(`the reading floors force a ${natural} s film, longer than the requested ${target} s`);
+    }
+  }
+  const shots = units.filter((u) => u.kind === 'line');
+  const last = shots.at(-1);
+  if (last.end < OUTPUT.minDurationSec) {
+    const endBeat = grid.at(OUTPUT.minDurationSec);
+    last.end = fix(frameRound(endBeat, fps));
+    last.holdSec = fix(last.end - last.start);
+    warnings.push(`film extended to ${last.end} s to reach the 3 s duration floor`);
+  }
+  if (last.end > OUTPUT.warnDurationSec) warnings.push(`film runs ${last.end} s, past the 90 s advisory length`);
+  return { timeline: units, durationSec: last.end, beat, warnings };
+}
+
+export function shotsOf(timeline) {
+  return timeline.filter((u) => u.kind === 'line' || u.kind === 'scene');
+}
+
+export function shotAt(timeline, t) {
+  const shots = shotsOf(timeline);
+  return shots.find((s) => t >= s.start - 1e-6 && t < s.end - 1e-6) || shots.at(-1);
+}
+
+export function revealsOf(timeline, shot) {
+  return timeline.filter((u) => u.kind === 'reveal' && u.sceneId === shot.sceneId && u.shotIndex === shot.shotIndex);
+}