@foldspace_npm/harness 0.1.31 → 0.1.32

package/src/video/timeline.mjs

@@ -0,0 +1,726 @@
+// The video's timeline, as pure functions: which moment of a recording shows
+// at each instant of the video, when a caption fades, where the clips
+// dissolve, where the logo goes. No I/O and no Node imports: the composer page
+// loads this same file in the browser, and the tests run it in Node.
+//
+// Times are in seconds. A scene's source times are seconds since its recording
+// started; its output times are seconds since its clip started in the video.
+
+export const FPS = 30;
+
+// The look settled on after five versions of a customer demo video: the
+// agent's thinking kept but never a long wait, the caption only once the
+// answer is on screen. 4-5 scenes run about 40 s.
+export const TIMING = Object.freeze({
+  leadS: 0.4, // the still panel before the first key
+  typingMaxS: 1.8, // typing, sped up to at most this
+  typingMinS: 1.0,
+  headS: 0.8, // just after Enter: the question bubble and "Thinking..." at real speed
+  waitMaxS: 0.8, // the rest of the thinking, sped up to at most this
+  waitMinS: 0.4,
+  answerMaxS: 1.6, // the card loading and the answer streaming in
+  answerMinS: 1.0,
+  idleGapS: 0.7, // no new picture for longer than this is an idle wait...
+  idleKeepS: 0.35, // ...shown for this long
+  captionDelayS: 0.25, // after the answer settles
+  captionFadeS: 0.35,
+  captionHoldMaxS: 2.6,
+  captionHoldMinS: 2.0,
+  tailS: 0.15, // after the caption has gone
+  openingS: 3.0, // the opening card: two lines and "Built with", nothing more to read
+  endS: 3.2,
+  dissolveS: 0.5,
+  fadeOutS: 0.5, // the last moment of the video fades out
+  // 4-5 scenes after the opening card: about 40 s.
+  maxTotalS: 45,
+});
+
+// ------------------------------------------------------------ time maps
+
+/**
+ * Split [start, end] into pieces at real speed, except that a stretch with no
+ * new picture for longer than `gapS` is shown for `keepS`: nothing on screen
+ * changes during it, so less of it is the same picture.
+ * `frameTimes` are the source times of the recorded pictures, ascending.
+ * Returns [{ srcStart, srcEnd, outS }].
+ */
+export function compressIdleGaps(frameTimes, start, end, { gapS = TIMING.idleGapS, keepS = TIMING.idleKeepS } = {}) {
+  if (!(end > start)) return [];
+  const inside = frameTimes.filter((t) => t > start && t < end);
+  const marks = [start, ...inside, end];
+  const pieces = [];
+  let runStart = start;
+  for (let i = 0; i < marks.length - 1; i++) {
+    const a = marks[i];
+    const b = marks[i + 1];
+    if (b - a > gapS) {
+      if (a > runStart) pieces.push({ srcStart: runStart, srcEnd: a, outS: a - runStart });
+      pieces.push({ srcStart: a, srcEnd: b, outS: keepS });
+      runStart = b;
+    }
+  }
+  if (end > runStart) pieces.push({ srcStart: runStart, srcEnd: end, outS: end - runStart });
+  return pieces;
+}
+
+const total = (pieces) => pieces.reduce((sum, piece) => sum + piece.outS, 0);
+
+/** Speed pieces up evenly so they last at most `maxS`; never slowed down. */
+export function speedTo(pieces, maxS) {
+  const length = total(pieces);
+  if (!(length > maxS) || !(maxS > 0)) return pieces;
+  const factor = maxS / length;
+  return pieces.map((piece) => ({ ...piece, outS: piece.outS * factor }));
+}
+
+/** Pieces laid end to end from `outStart`: [{ outStart, outEnd, srcStart, srcEnd }]. */
+function lay(pieces, outStart) {
+  const segments = [];
+  let at = outStart;
+  for (const piece of pieces) {
+    if (!(piece.outS > 0)) continue;
+    segments.push({ outStart: at, outEnd: at + piece.outS, srcStart: piece.srcStart, srcEnd: piece.srcEnd });
+    at += piece.outS;
+  }
+  return { segments, end: at };
+}
+
+/**
+ * The time budgets for a tightness `k` (0 = roomy, 1 = tightest): typing,
+ * thinking, answer and caption hold shrink together, from max toward min.
+ */
+export function budgets(k = 0, timing = TIMING) {
+  const between = (max, min) => max - (max - min) * Math.min(1, Math.max(0, k));
+  return {
+    typingS: between(timing.typingMaxS, timing.typingMinS),
+    waitS: between(timing.waitMaxS, timing.waitMinS),
+    answerS: between(timing.answerMaxS, timing.answerMinS),
+    holdS: between(timing.captionHoldMaxS, timing.captionHoldMinS),
+  };
+}
+
+/**
+ * The time map of one scene. `events` are source times in seconds:
+ * typingStart, sent, firstReply (may be null), settled. Returns the segments
+ * (output time -> source time), the clip's length, and when the caption shows.
+ *
+ *   lead     still panel                      real speed
+ *   typing   the question typed               sped up to at most typingS
+ *   head     bubble + "Thinking..."           real speed
+ *   wait     the rest of the thinking         sped up to at most waitS
+ *   answer   card loading, answer streaming   sped up to at most answerS
+ *   settled  the answer, then the caption     real speed (the last picture holds)
+ */
+export function sceneTimeMap(events, frameTimes, { k = 0, timing = TIMING } = {}) {
+  const budget = budgets(k, timing);
+  const idle = { gapS: timing.idleGapS, keepS: timing.idleKeepS };
+  const typingStart = Math.max(0, events.typingStart);
+  const sent = Math.max(typingStart, events.sent);
+  const settled = Math.max(sent, events.settled);
+  const headEnd = Math.min(settled, sent + timing.headS);
+  // The poll that saw the first reply ran up to half a poll after it; start
+  // the answer a little before, so the first words are not skipped.
+  const firstReply = events.firstReply == null ? settled : events.firstReply;
+  const answerStart = Math.min(settled, Math.max(headEnd, firstReply - 0.4));
+  const leadStart = Math.max(0, typingStart - timing.leadS);
+
+  const phases = [
+    [{ srcStart: leadStart, srcEnd: typingStart, outS: typingStart - leadStart }],
+    speedTo(compressIdleGaps(frameTimes, typingStart, sent, idle), budget.typingS),
+    compressIdleGaps(frameTimes, sent, headEnd, idle),
+    speedTo(compressIdleGaps(frameTimes, headEnd, answerStart, idle), budget.waitS),
+    speedTo(compressIdleGaps(frameTimes, answerStart, settled, idle), budget.answerS),
+  ];
+  const segments = [];
+  let at = 0;
+  const marks = {};
+  const names = ["lead", "typing", "head", "wait", "answer"];
+  phases.forEach((pieces, index) => {
+    marks[names[index]] = at;
+    const laid = lay(pieces, at);
+    segments.push(...laid.segments);
+    at = laid.end;
+  });
+  marks.settled = at;
+  const caption = captionWindow(at, { ...timing, holdS: budget.holdS });
+  const clipS = caption.outEnd + timing.tailS;
+  // After the answer settles, the recording plays on at real speed; past its
+  // last picture, that picture holds.
+  segments.push({ outStart: at, outEnd: clipS, srcStart: settled, srcEnd: settled + (clipS - at) });
+  return { segments, durationS: clipS, marks, caption };
+}
+
+/** When a caption fades in, holds and fades out, from the moment the answer settles. */
+export function captionWindow(settledAt, timing = TIMING) {
+  const holdS = timing.holdS ?? timing.captionHoldMaxS;
+  const inStart = settledAt + timing.captionDelayS;
+  const inEnd = inStart + timing.captionFadeS;
+  const outStart = inEnd + holdS;
+  const outEnd = outStart + timing.captionFadeS;
+  return { inStart, inEnd, outStart, outEnd };
+}
+
+/** The caption's opacity at clip time `t`: 0 while typing and working, 1 while it holds. */
+export function captionAlpha(caption, t) {
+  if (t <= caption.inStart || t >= caption.outEnd) return 0;
+  if (t < caption.inEnd) return (t - caption.inStart) / (caption.inEnd - caption.inStart);
+  if (t <= caption.outStart) return 1;
+  return (caption.outEnd - t) / (caption.outEnd - caption.outStart);
+}
+
+/** The source time shown at clip time `t`. */
+export function sourceTime(segments, t) {
+  if (!segments.length) return t;
+  let lo = 0;
+  let hi = segments.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (segments[mid].outStart <= t) lo = mid;
+    else hi = mid - 1;
+  }
+  const segment = segments[lo];
+  if (t <= segment.outStart) return segment.srcStart;
+  const span = segment.outEnd - segment.outStart;
+  const share = span > 0 ? Math.min(1, (t - segment.outStart) / span) : 1;
+  return segment.srcStart + (segment.srcEnd - segment.srcStart) * share;
+}
+
+/** The last picture recorded at or before `srcT` (the first one before any). */
+export function frameIndexAt(frameTimes, srcT) {
+  if (!frameTimes.length) return -1;
+  let lo = 0;
+  let hi = frameTimes.length - 1;
+  if (srcT < frameTimes[0]) return 0;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (frameTimes[mid] <= srcT) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+
+// ------------------------------------------------------------ whole video
+
+/**
+ * Clips one after another, each dissolving into the next over `dissolveS`.
+ * Returns each clip's start and the video's length.
+ */
+export function layoutClips(durations, dissolveS = TIMING.dissolveS) {
+  const starts = [];
+  let at = 0;
+  durations.forEach((duration, index) => {
+    starts.push(at);
+    at += duration - (index < durations.length - 1 ? dissolveS : 0);
+  });
+  return { starts, durations: [...durations], totalS: Math.max(0, at), dissolveS };
+}
+
+/**
+ * The clips showing at video time `t`: one, or two while one dissolves into
+ * the next. `alpha` is how strongly each is drawn over what is below it.
+ */
+export function activeClips(layout, t) {
+  const showing = [];
+  layout.starts.forEach((start, index) => {
+    const end = start + layout.durations[index];
+    if (t >= start && t < end) showing.push(index);
+  });
+  if (!showing.length) {
+    const last = layout.starts.length - 1;
+    return last < 0 ? [] : [{ index: last, localT: layout.durations[last], alpha: 1 }];
+  }
+  return showing.map((index, order) => {
+    const localT = t - layout.starts[index];
+    const alpha = order === 0 ? 1 : Math.min(1, localT / layout.dissolveS);
+    return { index, localT, alpha };
+  });
+}
+
+/** The fade to black at the very end of the video, over `fadeOutS`. */
+export function fadeOutAlpha(totalS, t, fadeOutS = TIMING.fadeOutS) {
+  if (t <= totalS - fadeOutS) return 1;
+  return Math.max(0, (totalS - t) / fadeOutS);
+}
+
+/** The video's length for a tightness `k`. */
+export function videoLength(scenes, { k = 0, titleCard = true, endCard = true, timing = TIMING } = {}) {
+  const durations = [
+    ...(titleCard ? [timing.openingS] : []),
+    ...scenes.map((scene) => sceneTimeMap(scene.events, scene.frameTimes, { k, timing }).durationS),
+    ...(endCard ? [timing.endS] : []),
+  ];
+  return layoutClips(durations, timing.dissolveS).totalS;
+}
+
+/**
+ * The roomiest tightness that keeps the video within `maxTotalS`: typing,
+ * thinking, answer and caption hold shrink together toward their minimums.
+ * When even the tightest is too long, says by how much (too many scenes).
+ */
+export function fitToLength(scenes, { titleCard = true, endCard = true, timing = TIMING } = {}) {
+  const length = (k) => videoLength(scenes, { k, titleCard, endCard, timing });
+  if (length(0) <= timing.maxTotalS) return { k: 0, totalS: length(0), overS: 0 };
+  if (length(1) > timing.maxTotalS) {
+    return { k: 1, totalS: length(1), overS: length(1) - timing.maxTotalS };
+  }
+  let lo = 0;
+  let hi = 1;
+  for (let step = 0; step < 24; step++) {
+    const mid = (lo + hi) / 2;
+    if (length(mid) <= timing.maxTotalS) hi = mid;
+    else lo = mid;
+  }
+  return { k: hi, totalS: length(hi), overS: 0 };
+}
+
+// ------------------------------------------------------------ layout
+
+/** `src` scaled to fit inside `dst`, centred: never cropped, never zoomed past fit. */
+export function containRect(srcW, srcH, dstW, dstH) {
+  const scale = Math.min(dstW / srcW, dstH / srcH);
+  const w = srcW * scale;
+  const h = srcH * scale;
+  return { x: (dstW - w) / 2, y: (dstH - h) / 2, w, h, scale };
+}
+
+/** A box in the recorded viewport (CSS px) placed in the video frame. */
+export function placeBox(box, viewport, content) {
+  const sx = content.w / viewport.width;
+  const sy = content.h / viewport.height;
+  return { x: content.x + box.x * sx, y: content.y + box.y * sy, w: box.width * sx, h: box.height * sy };
+}
+
+const overlap = (a, b) =>
+  Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x)) *
+  Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+
+/** The smallest box around `boxes` ({x, y, w, h}), or null. */
+export function unionBox(boxes) {
+  const list = boxes.filter(Boolean);
+  if (!list.length) return null;
+  const x = Math.min(...list.map((box) => box.x));
+  const y = Math.min(...list.map((box) => box.y));
+  return {
+    x,
+    y,
+    w: Math.max(...list.map((box) => box.x + box.w)) - x,
+    h: Math.max(...list.map((box) => box.y + box.h)) - y,
+  };
+}
+
+// Where the small Foldspace logo may go, in this order when several are
+// equally calm: the frame's corners, and the corners of the app's free area
+// beside the agent panel. Top-left comes late: it is where an app puts its own
+// logo and name. Bottom-left is the caption's.
+export const LOGO_SPOTS = ["top-right", "bottom-right", "beside-panel-bottom", "beside-panel-top", "top-left", "bottom-left"];
+
+/**
+ * The places the logo could go: { spot, order, x, y, w, h }. `panel` is the
+ * agent panel's box in the video frame (every scene's, as one box); beside it
+ * means the corner of the app area next to it, at the top and at the bottom.
+ */
+export function logoCandidates({ width, height, logo, margin = 28, gap = 20, content = null, panel = null }) {
+  const spots = [];
+  const add = (spot, x, y) => spots.push({ spot, order: LOGO_SPOTS.indexOf(spot), x, y, w: logo.w, h: logo.h });
+  for (const corner of ["top-right", "bottom-right", "top-left", "bottom-left"]) {
+    add(
+      corner,
+      corner.endsWith("left") ? margin : width - margin - logo.w,
+      corner.startsWith("top") ? margin : height - margin - logo.h,
+    );
+  }
+  if (panel && content) {
+    const onRight = panel.x + panel.w / 2 > content.x + content.w / 2;
+    const x = onRight ? panel.x - gap - logo.w : panel.x + panel.w + gap;
+    const fits = x >= content.x + margin && x + logo.w <= content.x + content.w - margin;
+    if (fits) {
+      add("beside-panel-top", x, Math.max(content.y, 0) + margin);
+      add("beside-panel-bottom", x, Math.min(content.y + content.h, height) - margin - logo.h);
+    }
+  }
+  return spots.sort((a, b) => a.order - b.order);
+}
+
+/**
+ * The spot for the logo: one that touches none of `avoid` (the agent panel in
+ * every scene, the caption cards), with `pad` to spare. Among the clear ones a
+ * spot wholly in the letterbox, off the product, wins; then the calmest -
+ * `busy[spot]` is how much the app's pictures change across that patch (its
+ * logo, a menu, text), so the Foldspace logo never sits on the app's own
+ * logo or controls. Spots within `calmWithin` of the calmest count as calm,
+ * and the order of LOGO_SPOTS decides. If every spot touches something, the
+ * one that covers least.
+ */
+export function chooseLogoSpot({ candidates, avoid = [], content = null, busy = {}, pad = 12, calmWithin = 0.01 }) {
+  const padded = (box) => ({ x: box.x - pad, y: box.y - pad, w: box.w + pad * 2, h: box.h + pad * 2 });
+  const scored = candidates.map((candidate) => ({
+    ...candidate,
+    covered: avoid.reduce((sum, other) => sum + overlap(padded(candidate), other), 0),
+    offProduct: content ? overlap(candidate, content) === 0 : false,
+    busy: Number.isFinite(busy[candidate.spot]) ? busy[candidate.spot] : 0,
+  }));
+  const clear = scored.filter((candidate) => candidate.covered === 0);
+  let pool;
+  if (clear.length) {
+    const off = clear.filter((candidate) => candidate.offProduct);
+    pool = off.length ? off : clear;
+    const calmest = Math.min(...pool.map((candidate) => candidate.busy));
+    pool = pool.filter((candidate) => candidate.busy <= calmest + calmWithin).sort((a, b) => a.order - b.order);
+  } else {
+    pool = [...scored].sort((a, b) => a.covered - b.covered || a.order - b.order);
+  }
+  const best = pool[0];
+  return { spot: best.spot, x: best.x, y: best.y, w: best.w, h: best.h, clear: best.covered === 0 };
+}
+
+/**
+ * How busy a patch of pixels is, 0 (flat) to 1: the mean step in brightness
+ * between neighbouring pixels. Text, icons and logos score high, a plain
+ * header or empty background near 0. `rgba` is ImageData's data. Also returns
+ * the patch's mean brightness, to pick a logo ink that reads on it.
+ */
+export function patchStats(rgba, width, height) {
+  if (!(width > 1 && height > 1)) return { busy: 0, brightness: 0 };
+  const lum = new Float32Array(width * height);
+  let sum = 0;
+  for (let i = 0; i < width * height; i++) {
+    const value = (0.2126 * rgba[i * 4] + 0.7152 * rgba[i * 4 + 1] + 0.0722 * rgba[i * 4 + 2]) / 255;
+    lum[i] = value;
+    sum += value;
+  }
+  let steps = 0;
+  let count = 0;
+  for (let y = 0; y < height - 1; y++) {
+    for (let x = 0; x < width - 1; x++) {
+      const at = y * width + x;
+      steps += Math.abs(lum[at + 1] - lum[at]) + Math.abs(lum[at + width] - lum[at]);
+      count += 2;
+    }
+  }
+  return { busy: steps / count, brightness: sum / (width * height) };
+}
+
+// ------------------------------------------------------------ caption
+
+// Poppins' own line metrics, as fractions of the size. A line `lineHeight`
+// high puts its baseline where a browser would, so the cards come out as
+// their approved HTML mockups.
+export const ASCENT = 1.05;
+export const DESCENT = 0.35;
+/** Where the baseline of `size` text sits in a line `lineHeight` high, from its top. */
+export const baselineIn = (lineHeight, size) => (lineHeight - (ASCENT + DESCENT) * size) / 2 + ASCENT * size;
+/** A browser's "normal" line height for Poppins. */
+export const normalLine = (size) => (ASCENT + DESCENT) * size;
+
+// The caption card on a 1080-high frame, as the approved mockup (option A,
+// after the product video's storyboard): at most 1040 px wide, bottom-left.
+// Sizes in px; the spacings and the highlight's padding in em.
+export const CAPTION = Object.freeze({
+  margin: 48,
+  maxW: 1040,
+  border: 2,
+  radius: 22,
+  padX: 36,
+  padTop: 30,
+  padBottom: 34,
+  pill: 21, // the capability pills: white on blue, as the storyboard's
+  pillLine: 1.5,
+  pillPadX: 15,
+  gap: 10, // between the pills and "2 OF 4"
+  place: 19, // "2 OF 4"
+  placeGap: 8, // beyond the gap, after the last pill
+  placeSpacing: 0.1,
+  question: 24, // the question, small and muted
+  questionTop: 22,
+  line: 46, // the scene's line, large and white
+  lineMin: 30, // smaller only when it would not fit two lines
+  lineStep: 1.2,
+  lineSpacing: -0.02,
+  lineTop: 10,
+  maxLines: 2,
+  markPad: 0.12, // the blue block behind *highlighted* words
+  markRadius: 0.06,
+});
+export const OPEN_QUOTE = "“";
+export const CLOSE_QUOTE = "”";
+
+/**
+ * A scene's line, as written in scenes.json: a "\n" breaks it, and words
+ * between asterisks go on the blue highlight. Returns { paragraphs, marks,
+ * problem }: each paragraph (one per forced line) a list of words, each word
+ * a list of pieces { text, span } - `span` is the highlight it is in, or -1.
+ * `problem` is null, "unbalanced" (an asterisk without its pair), "across"
+ * (a highlight running over the line break) or "empty" (nothing between two
+ * asterisks).
+ */
+export function parseMarked(text) {
+  const source = String(text ?? "");
+  if ((source.match(/\*/g) || []).length % 2) return { paragraphs: [], marks: 0, problem: "unbalanced" };
+  let marks = 0;
+  let problem = null;
+  const paragraphs = source.split("\n").map((paragraph) => {
+    const parts = paragraph.split("*");
+    // An odd number of asterisks in one line: its pair is on the other line.
+    if (parts.length % 2 === 0) problem = problem || "across";
+    const words = [];
+    let word = [];
+    const endWord = () => {
+      if (word.length) words.push(word);
+      word = [];
+    };
+    parts.forEach((part, index) => {
+      const marked = index % 2 === 1;
+      if (marked && !part.trim()) problem = problem || "empty";
+      const span = marked ? marks++ : -1;
+      // Spaces end a word; a highlight that starts or ends mid-word shares it.
+      part.split(/(\s+)/).forEach((chunk) => {
+        if (!chunk) return;
+        if (/^\s+$/.test(chunk)) endWord();
+        else word.push({ text: chunk, span });
+      });
+    });
+    endWord();
+    return words;
+  });
+  return { paragraphs, marks, problem };
+}
+
+/** The visible characters of a line: no asterisks, no break, single spaces. */
+export function visibleText(text) {
+  return String(text ?? "")
+    .replace(/\*/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Words on one line, as runs to draw: { text, span } where neighbours in the
+ * same highlight join up with the space between them, as a browser draws an
+ * inline span.
+ */
+function runsOf(words) {
+  const runs = [];
+  words.forEach((word, index) => {
+    const before = index > 0 ? words[index - 1].at(-1).span : -1;
+    if (index > 0) {
+      // The space is in the highlight only when it is inside one span.
+      const span = before >= 0 && before === word[0].span ? before : -1;
+      const last = runs.at(-1);
+      if (last.span === span) last.text += " ";
+      else runs.push({ text: " ", span });
+    }
+    for (const piece of word) {
+      const last = runs.at(-1);
+      if (last && last.span === piece.span) last.text += piece.text;
+      else runs.push({ ...piece });
+    }
+  });
+  return runs;
+}
+
+/** One drawn line: its runs with their widths, a highlight's padding on each side of its block. */
+function lineOf(words, measure, pad) {
+  let x = 0;
+  const runs = runsOf(words).map((run) => {
+    const marked = run.span >= 0;
+    const w = measure(run.text) + (marked ? pad * 2 : 0);
+    const placed = { text: run.text, mark: marked, x, w, textX: x + (marked ? pad : 0) };
+    x += w;
+    return placed;
+  });
+  return { runs, w: x };
+}
+
+/**
+ * One paragraph in one line, or two as even as they come; null when neither
+ * fits `maxWidth`.
+ */
+function balance(words, maxWidth, measure, pad) {
+  const whole = lineOf(words, measure, pad);
+  if (whole.w <= maxWidth) return [whole];
+  let best = null;
+  for (let cut = 1; cut < words.length; cut++) {
+    const first = lineOf(words.slice(0, cut), measure, pad);
+    const second = lineOf(words.slice(cut), measure, pad);
+    if (first.w > maxWidth || second.w > maxWidth) continue;
+    const widest = Math.max(first.w, second.w);
+    if (!best || widest < best.widest) best = { widest, lines: [first, second] };
+  }
+  return best ? best.lines : null;
+}
+
+/** Words wrapped to `maxWidth`, one after another, however many lines it takes. */
+function greedy(words, maxWidth, measure, pad) {
+  const lines = [];
+  let current = [];
+  for (const word of words) {
+    if (current.length && lineOf([...current, word], measure, pad).w > maxWidth) {
+      lines.push(lineOf(current, measure, pad));
+      current = [];
+    }
+    current.push(word);
+  }
+  if (current.length) lines.push(lineOf(current, measure, pad));
+  return lines;
+}
+
+/**
+ * The scene's line laid out: at its full size in at most two lines - a "\n"
+ * breaks it there, otherwise it wraps as evenly as it can - and a little
+ * smaller only when it will not fit. `measure(text, size)` is the width of
+ * text at that size. Returns { size, lines: [{ runs, w }] }.
+ */
+export function layoutLine(text, maxWidth, measure, c = CAPTION) {
+  const { paragraphs } = parseMarked(text);
+  for (let size = c.line; size >= c.lineMin; size -= 2) {
+    const at = (value) => measure(value, size);
+    const pad = c.markPad * size;
+    const laid = paragraphs.map((words) => balance(words, maxWidth, at, pad));
+    if (laid.some((lines) => !lines)) continue;
+    const lines = laid.flat();
+    if (lines.length <= c.maxLines) return { size, lines };
+  }
+  // Too long even at the smallest size (the file check warns): wrap it all.
+  const at = (value) => measure(value, c.lineMin);
+  return { size: c.lineMin, lines: paragraphs.flatMap((words) => greedy(words, maxWidth, at, c.markPad * c.lineMin)) };
+}
+
+/** Plain words wrapped to `maxWidth`, keeping any line breaks already there. */
+export function wrapWords(text, maxWidth, measure) {
+  const lines = [];
+  for (const paragraph of String(text || "").split("\n")) {
+    let line = "";
+    for (const word of paragraph.split(/\s+/).filter(Boolean)) {
+      const next = line ? `${line} ${word}` : word;
+      if (line && measure(next) > maxWidth) {
+        lines.push(line);
+        line = word;
+      } else {
+        line = next;
+      }
+    }
+    lines.push(line);
+  }
+  return lines;
+}
+
+/**
+ * The caption card, laid out bottom-left of the frame: its box, and where
+ * each part goes inside it. Row 1: the capability pills and "2 OF 4"; row 2:
+ * the question, small; row 3: the scene's line, large, with its highlights.
+ * `measure(text, { weight, size, spacing })` is the width of Poppins text
+ * (spacing in em). As a browser sizes the mockup: as wide as its widest row,
+ * at most 1040 px (less on a narrow frame).
+ */
+export function captionLayout(caption, { height, width, measure, content = null }, c = CAPTION) {
+  const outer = Math.min(c.maxW, width - c.margin * 2);
+  const inner = outer - (c.border + c.padX) * 2;
+  const left = c.border + c.padX;
+  let y = c.border + c.padTop;
+
+  // Row 1, its items centred on one line.
+  const pillH = c.pill * c.pillLine;
+  const pills = caption.capabilities.map((name) => ({
+    name,
+    w: measure(name, { weight: 600, size: c.pill }) + c.pillPadX * 2,
+  }));
+  const placeText = String(caption.place).toUpperCase();
+  const placeLine = normalLine(c.place);
+  const rowH = pills.length ? Math.max(pillH, placeLine) : placeLine;
+  let x = left;
+  for (const pill of pills) {
+    Object.assign(pill, { x, y: y + (rowH - pillH) / 2, h: pillH, textX: x + c.pillPadX });
+    pill.baseline = pill.y + baselineIn(pillH, c.pill);
+    x += pill.w + c.gap;
+  }
+  if (pills.length) x += c.placeGap;
+  const placeW = measure(placeText, { weight: 600, size: c.place, spacing: c.placeSpacing });
+  const place = { text: placeText, x, baseline: y + (rowH - placeLine) / 2 + baselineIn(placeLine, c.place) };
+  const rowW = x + placeW - left;
+  y += rowH + c.questionTop;
+
+  // Row 2: the question between curly quotes.
+  const questionMeasure = (value) => measure(value, { weight: 400, size: c.question });
+  const questionStep = normalLine(c.question);
+  const questionLines = wrapWords(`${OPEN_QUOTE}${caption.question}${CLOSE_QUOTE}`, inner, questionMeasure).map(
+    (text, index) => ({ text, x: left, baseline: y + index * questionStep + baselineIn(questionStep, c.question) }),
+  );
+  const questionW = Math.max(...questionLines.map((line) => questionMeasure(line.text)));
+  y += questionLines.length * questionStep + c.lineTop;
+
+  // Row 3: the line.
+  const laid = layoutLine(caption.line, inner, (value, size) => measure(value, { weight: 600, size, spacing: c.lineSpacing }), c);
+  const lineStep = laid.size * c.lineStep;
+  const lines = laid.lines.map((line, index) => {
+    const top = y + index * lineStep;
+    const baseline = top + baselineIn(lineStep, laid.size);
+    return {
+      baseline,
+      w: line.w,
+      runs: line.runs.map((run) => ({ ...run, x: left + run.x, textX: left + run.textX })),
+    };
+  });
+  // The highlight block covers the font's whole height, as a browser paints an inline background.
+  const mark = { top: -ASCENT * laid.size, h: (ASCENT + DESCENT) * laid.size, radius: c.markRadius * laid.size };
+  y += lines.length * lineStep + c.padBottom + c.border;
+
+  const textW = Math.min(inner, Math.max(rowW, questionW, ...lines.map((line) => line.w)));
+  const w = Math.round(textW + left * 2);
+  const h = Math.round(y);
+  // On a letterboxed frame (the square preset) the card sits on the picture,
+  // never across the black band below it: a see-through card would show a
+  // seam there. If the picture is too short for it, the frame's foot it is.
+  const pictureFoot = content ? Math.min(height, content.y + content.h) : height;
+  const onPicture = pictureFoot - h - c.margin;
+  const top = content && onPicture >= content.y + c.margin ? onPicture : height - h - c.margin;
+  return {
+    x: c.margin,
+    y: Math.round(top),
+    w,
+    h,
+    radius: c.radius,
+    border: c.border,
+    pills,
+    place,
+    questionLines,
+    line: { size: laid.size, lines, mark },
+  };
+}
+
+// ------------------------------------------------------------ colour
+
+/** [r, g, b] 0-255 of #RRGGBB; null for anything else. */
+export function parseHex(hex) {
+  const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(String(hex || ""));
+  return m ? [m[1], m[2], m[3]].map((part) => parseInt(part, 16)) : null;
+}
+
+const toHex = (channels) =>
+  `#${channels
+    .map((value) => Math.round(Math.min(255, Math.max(0, value))).toString(16).padStart(2, "0"))
+    .join("")
+    .toUpperCase()}`;
+
+/** WCAG relative luminance of #RRGGBB, 0..1 (sRGB linearised); null for anything else. */
+export function relativeLuminance(hex) {
+  const channels = parseHex(hex);
+  if (!channels) return null;
+  const [r, g, b] = channels.map((value) => {
+    const c = value / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio of two #RRGGBB colours, 1..21. */
+export function contrastRatio(a, b) {
+  const [light, dark] = [relativeLuminance(a), relativeLuminance(b)].sort((x, y) => y - x);
+  return (light + 0.05) / (dark + 0.05);
+}
+
+/** `top` at `alpha` over `bottom`, as #RRGGBB. */
+export function blendHex(top, alpha, bottom) {
+  const a = parseHex(top);
+  const b = parseHex(bottom);
+  return toHex(a.map((value, index) => value * alpha + b[index] * (1 - alpha)));
+}