@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/playbackPreparation.ts

@@ -0,0 +1,562 @@
+// Which frames the stage draws once, before playback starts, so that playback
+// never pays a first-use cost.
+//
+// ── WHY PLAYBACK NEEDS THIS AT ALL ─────────────────────────────────────────
+//
+// The first time a frame is really drawn, the GPU process does work the
+// warm-up cannot do ahead of it: the first submit of a new pipeline, of a
+// transition's render targets, of a caption's rasters. Measured on
+// examples/training-season-reel (1080p, WebGPU, RTX 3060): the first loop
+// stalled 3.0 s in total with gaps up to 530 ms, and every later loop about
+// 1.1 s with none over 110 ms. The warm-up compiles STAND-INS of the next
+// scene while the transport runs; a stand-in builds the program but not the
+// first real draw, and it only gets the frames before the cut to do it in.
+//
+// Drawing these frames once through the ordinary seek path, with the stage in
+// its playing presentation, pays that cost under a frozen picture (bridge
+// v51): in the background while the author sits paused, or for a queued Play.
+// Measured end to end on the landscape cut: the first loop's stalls fell from
+// 3.2 s to about 0.3 s and its worst gap from 284 ms to under 100 ms, for a
+// pass of about 3 s. HyperFrames makes the same trade for its shader
+// transitions: it holds `play()` while it renders every transition frame once.
+//
+// ── WHICH FRAMES, AND IN WHICH ORDER ───────────────────────────────────────
+//
+// The frames where something can appear that the GPU has not drawn yet:
+//
+// - a Shot's first frame, where its scene mounts;
+// - a transition window's first and last frames and the first frame after
+//   it, where the held Shot leaves (the stalls sat on both ends). Under
+//   `hold` the outgoing Shot is one frozen picture for the whole window, so
+//   the frames between buy nothing but the keys inside it of the incoming
+//   Shot's fades, blurs and component props: that Shot plays on into the TO
+//   operand, a target keyed apart from the canvas when the Shot has no post
+//   chain, and the one frame per state the rule below picks can land outside
+//   the window. Under `run` the
+//   outgoing Shot plays on past its own end, and every window frame is a
+//   picture of it drawn nowhere else, so all of them;
+// - a layer's first frame;
+// - the frames inside the Shot where one of its tracks can change what the
+//   renderer builds (`trackEventFrames`): one frame of each blending a fade
+//   draws (blending is part of a pipeline) and of each side of a blur's 0,
+//   both ends of a component prop, a move's last key, each step of a raster
+//   input. A tweened colour, raster input or geometry input builds nothing it
+//   can keep. Every frame of an animation was measured and bought nothing
+//   over its two ends (154 frames against 250, the same stalls).
+//
+// In playing order from the playhead, with the playhead's own Shot LAST: a
+// Play pass then ends inside the Shot it hands over in, so the hand-over's
+// start frame needs no remount. With the loop off, only the frames playback
+// can reach from the playhead in its direction.
+//
+// ── WHAT IS REMEMBERED ────────────────────────────────────────────────────
+//
+// Each frame carries a KEY: what its pixels depend on, as content, because a
+// save replaces the whole document object. The parts, each memoised by the
+// identity of what it reads:
+//
+// - the document-wide inputs every Shot draws with: size, rate, the assets
+//   that are not audio, materials, material lighting, component definitions;
+// - the Shot as it draws: `drawnScene`, less its name, its audio and its
+//   guides, so a still, a resource, a rename, a sound or a guide re-keys
+//   nothing;
+// - the Shot before it, on the incoming transition window's frames only (the
+//   only frames that draw both);
+// - the placed code components' module epoch (`preparationKey().modules`), on
+//   the Shots that place one;
+// - the isolated layer, on the frames of the Shot that holds it;
+// - the Shot-local frame.
+//
+// The store adds what the stage shows (the layout, the shading, the board) in
+// front of every key, and `PreparedFrames` drops everything when the stage's
+// base moves (`preparationKey().base`). A frame is credited only for what the
+// stage reported of it (`credit`), so a timed-out frame is never prepared.
+//
+// ── WHY A FRAME WAS PENDING (the perf flag only) ──────────────────────────
+//
+// Under the chrome's `?perf=1` or `?perf=log`, each frame also carries its key
+// in parts, `PreparedFrames` remembers the parts it last credited for each
+// frame in each view, and every pass names why each of its frames is pending:
+// the first part that moved, a first timeout, the clear that dropped it, or
+// never drawn (`PreparedFrames.explain`, `window.__dailiesPrep`). With the
+// flag off none of it runs.
+import {
+  INSTANCE_PROP_PREFIX,
+  drawnScene,
+  sceneWindows,
+  shotsPlacing,
+  trackEventFrames,
+  transitionAt,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D, Scene3D } from "@dailies-studio/shot/doc";
+import type { ShotPreparedOutcome } from "../bridgeTypes.js";
+
+/** The chrome's perf flag as its URL set it: the two values the stage URL
+ *  forwards (`stageSrc`), or null. */
+export type PreparationPerf = "1" | "log" | null;
+
+/** Read once at load, like the stage's `PERF_HUD_ENABLED`, and written again
+ *  only by the test seam below. */
+let perf: PreparationPerf = chromePerfFlag();
+
+/** The chrome's `?perf`, ALLOWLISTED: the one reading of it, for this file and
+ *  for the stage URL StagePanel builds, which must never carry anything else. */
+export function chromePerfFlag(): PreparationPerf {
+  const value = typeof window === "undefined" ? null : new URLSearchParams(window.location.search).get("perf");
+  return value === "1" || value === "log" ? value : null;
+}
+
+/** Test seam: the perf flag as the URL would set it. A `PreparedFrames` reads
+ *  it when it is made, `playbackPreparation` on every call. Drops the last
+ *  report. */
+export function setPreparationPerf(next: PreparationPerf): void {
+  perf = next;
+  report = null;
+}
+
+export interface PreparationFrame {
+  /** MASTER frame to seek. */
+  frame: number;
+  /** What this frame's pixels depend on, for `PreparedFrames`. */
+  key: string;
+  /** The key in parts, under the perf flag only. */
+  parts?: PreparationKeyParts;
+}
+
+/** A frame's key in parts, which `PreparedFrames.explain` compares. */
+export interface PreparationKeyParts {
+  /** Which frame this is across edits: the Shot's id and the Shot-local frame. */
+  id: string;
+  /** What the stage shows: the prefix the store adds, so empty as
+   *  `playbackPreparation` lists it. */
+  view: string;
+  /** The document-wide inputs. */
+  shared: string;
+  /** The Shot before, on this Shot's incoming transition window (empty
+   *  elsewhere and for the first Shot). */
+  prev: string;
+  /** This Shot. */
+  shot: string;
+  /** The placed modules' epoch, or empty for a Shot that places no code. */
+  modules: string;
+  /** The isolated layer, or empty when it is not in this Shot. */
+  isolation: string;
+  /** The Shot-local frame. */
+  local: number;
+}
+
+/** Where the transport starts, which orders the list. */
+export interface PreparationStart {
+  /** The playhead, a MASTER frame. */
+  frame: number;
+  /** The transport wraps its window (`playbackLoops`). */
+  loop: boolean;
+  /** The sign of the rate it starts at. */
+  direction: 1 | -1;
+}
+
+/** What the stage shows besides the document, per frame. */
+export interface PreparationInputs {
+  /** The layer the stage isolates, or null. */
+  isolation: string | null;
+  /** The placed code components' module epoch (`preparationKey().modules`). */
+  modules: string;
+}
+
+/**
+ * The frames to prepare inside a playback window, in the order to draw them.
+ *
+ * `window` is the transport's loop (`playbackWindow`): only frames playback
+ * will reach are prepared.
+ */
+export function playbackPreparation(
+  doc: Doc3D,
+  window: { start: number; frames: number },
+  start: PreparationStart,
+  inputs: PreparationInputs,
+): PreparationFrame[] {
+  const end = window.start + window.frames;
+  const shared = sharedHashOf(doc);
+  const placing = placingOf(doc);
+  const withParts = perf !== null;
+  const shots: ShotFrames[] = [];
+  let previousHash = "";
+  for (const scene of sceneWindows(doc)) {
+    const body = doc.scenesById[scene.id];
+    const length = scene.end - scene.start;
+    if (body === undefined || length <= 0) continue;
+    const { hash, events, stateKeys } = shotFactsOf(body, doc.fps);
+    const blendsFrom = previousHash;
+    previousHash = hash;
+    if (scene.end <= window.start || scene.start >= end) continue;
+    // The blend into this Shot, and its window's last local frame (the first
+    // after the blend), or -1 when nothing blends into it.
+    const into = transitionAt(doc, scene.start);
+    const blend = into?.incoming === scene.id ? into : null;
+    const blended = blend === null ? -1 : blend.durationFrames;
+    const local = new Set<number>(events);
+    if (blend !== null) {
+      // `run` (`outgoingSceneFrameAt`): every window frame; `hold`, or none
+      // set: the window's first and last frames, the one after it, and this
+      // Shot's state keys between them (see the header).
+      if (doc.scenesById[blend.outgoing]?.transition?.outgoing === "run") {
+        for (let at = 0; at <= blended; at += 1) local.add(at);
+      } else {
+        local.add(0).add(blended - 1).add(blended);
+        // ponytail: listed for a Shot with a post chain too, whose operand
+        // draws its scene through a source keyed as its presenter's, so they
+        // buy nothing there; the chain test (`hasPostChain`) lives with three.
+        // Skip them once a three-free one exists.
+        for (const at of stateKeys) if (at >= 1 && at <= blended - 2) local.add(at);
+      }
+    }
+    const modules = placing.has(scene.id) ? inputs.modules : "";
+    const isolation = inputs.isolation !== null && body.layersById[inputs.isolation] !== undefined ? inputs.isolation : "";
+    const frames: PreparationFrame[] = [];
+    for (const at of [...local].sort((a, b) => a - b)) {
+      if (at < 0 || at >= length) continue;
+      const frame = scene.start + at;
+      if (frame < window.start || frame >= end) continue;
+      const prev = at <= blended ? blendsFrom : "";
+      const key = `${shared}|${prev}>${hash}${modules === "" ? "" : `~${modules}`}@${at}${isolation === "" ? "" : `!${isolation}`}`;
+      frames.push(
+        withParts
+          ? { frame, key, parts: { id: `${scene.id}@${at}`, view: "", shared, prev, shot: hash, modules, isolation, local: at } }
+          : { frame, key },
+      );
+    }
+    shots.push({ start: scene.start, end: scene.end, frames });
+  }
+  return inPlayingOrder(shots, window, start);
+}
+
+/** One Shot's frames inside the window, ascending. */
+interface ShotFrames {
+  start: number;
+  end: number;
+  frames: PreparationFrame[];
+}
+
+/** The Shots in playing order from the playhead's, which comes LAST, each
+ *  ascending; with the loop off, only the frames reachable in `direction`. */
+function inPlayingOrder(
+  shots: readonly ShotFrames[],
+  window: { start: number; frames: number },
+  { frame, loop, direction }: PreparationStart,
+): PreparationFrame[] {
+  const count = shots.length;
+  if (count === 0) return [];
+  // Where the transport's first frame is, by `playbackTargetFrame`'s rule
+  // (Header.tsx): outside the window it starts at the in point, and with the
+  // loop off a start on the far edge plays again from the near one.
+  const last = window.start + window.frames - 1;
+  let from = frame >= window.start && frame <= last ? frame : window.start;
+  if (!loop && from === (direction < 0 ? window.start : last)) from = direction < 0 ? last : window.start;
+  const home = Math.max(
+    0,
+    shots.findIndex((shot) => from >= shot.start && from < shot.end),
+  );
+  const order: number[] = [];
+  for (let step = 1; step < count; step += 1) {
+    const at = home + step * direction;
+    if (at >= 0 && at < count) order.push(at);
+    else if (loop) order.push(((at % count) + count) % count);
+  }
+  order.push(home);
+  const out: PreparationFrame[] = [];
+  for (const at of order) {
+    for (const entry of shots[at]!.frames) {
+      if (!loop && (direction > 0 ? entry.frame < from : entry.frame > from)) continue;
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+/** What a Shot's frames key on, where its events are, and its state keys
+ *  (`stateKeyFrames`): once per Shot object, which an edit elsewhere in the
+ *  document keeps, and per rate, which a spring's frames move with. */
+interface ShotFacts {
+  hash: string;
+  events: readonly number[];
+  stateKeys: readonly number[];
+}
+const shotFacts = new WeakMap<Scene3D, ShotFacts & { fps: Doc3D["fps"] }>();
+
+function shotFactsOf(body: Scene3D, fps: Doc3D["fps"]): ShotFacts {
+  let facts = shotFacts.get(body);
+  if (facts === undefined || facts.fps.num !== fps.num || facts.fps.den !== fps.den) {
+    const { name: _name, audio: _audio, guides: _guides, ...drawn } = drawnScene(body);
+    facts = { hash: contentHash(drawn), events: sceneEventFrames(body, fps), stateKeys: stateKeyFrames(body), fps };
+    shotFacts.set(body, facts);
+  }
+  return facts;
+}
+
+/** The last shared hash and the six fields it was made of, by identity. */
+let sharedMemo: { of: readonly unknown[]; hash: string } | null = null;
+
+function sharedHashOf(doc: Doc3D): string {
+  const of = [doc.size, doc.fps, doc.assets, doc.materials, doc.materialLighting, doc.components];
+  const memo = sharedMemo;
+  if (memo !== null && of.every((value, at) => value === memo.of[at])) return memo.hash;
+  // Audio draws no pixel: an import of a sound re-keys nothing.
+  const assets = Object.fromEntries(Object.entries(doc.assets).filter(([, asset]) => asset.kind !== "audio"));
+  const hash = contentHash({
+    size: doc.size,
+    fps: doc.fps,
+    assets,
+    materials: doc.materials,
+    materialLighting: doc.materialLighting,
+    components: doc.components,
+  });
+  sharedMemo = { of, hash };
+  return hash;
+}
+
+/** The Shots that place a code component (`shotsPlacing`), per document. */
+const placingMemo = new WeakMap<Doc3D, ReadonlySet<string>>();
+
+function placingOf(doc: Doc3D): ReadonlySet<string> {
+  let placing = placingMemo.get(doc);
+  if (placing === undefined) {
+    placing = new Set(shotsPlacing(doc, []));
+    placingMemo.set(doc, placing);
+  }
+  return placing;
+}
+
+/** The Shot-local frames where a layer starts, or one of its tracks can
+ *  change what the renderer builds (`trackEventFrames`). */
+function sceneEventFrames(scene: Scene3D, fps: Doc3D["fps"]): number[] {
+  const length = Math.max(0, Math.trunc(scene.durationFrames));
+  const out = [0];
+  for (const layer of Object.values(scene.layersById)) {
+    if (layer.lifetime !== undefined) out.push(layer.lifetime.in);
+    for (const [path, track] of Object.entries(layer.tracks ?? {})) {
+      out.push(...trackEventFrames(path, track, fps, lifeInShot(layer, length)));
+    }
+  }
+  return out;
+}
+
+/** The frames of every key a fade, a blur or a component prop track has where
+ *  its layer draws: what a held window's interior adds (see the header). */
+function stateKeyFrames(scene: Scene3D): number[] {
+  const length = Math.max(0, Math.trunc(scene.durationFrames));
+  const out: number[] = [];
+  for (const layer of Object.values(scene.layersById)) {
+    const life = lifeInShot(layer, length);
+    for (const [path, track] of Object.entries(layer.tracks ?? {})) {
+      if (path !== "transform.opacity" && path !== "blurPx" && !path.startsWith(INSTANCE_PROP_PREFIX)) continue;
+      for (const key of track.keyframes) if (key.frame >= life.in && key.frame < life.out) out.push(key.frame);
+    }
+  }
+  return out;
+}
+
+/** A layer's lifetime inside its Shot: no lifetime is the whole Shot, so a key
+ *  past the Shot's end is no frame the layer draws, and the state it reaches
+ *  inside is found on the curve instead. */
+function lifeInShot(layer: Layer3D, length: number): { in: number; out: number } {
+  return { in: layer.lifetime?.in ?? 0, out: Math.min(layer.lifetime?.out ?? length, length) };
+}
+
+/**
+ * FNV-1a over a value's JSON. Not a security hash: two inputs colliding costs
+ * one skipped preparation, which is a stall, never a wrong picture.
+ */
+function contentHash(value: unknown): string {
+  const text = JSON.stringify(value) ?? "";
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(36) + text.length.toString(36);
+}
+
+/** Why the prepared set was last cleared: a new renderer (`onReady`), the
+ *  stage's base moved (`preparationKey().base`), another Project opened, or
+ *  the set ran past `PREPARED_LIMIT`. */
+export type PreparedClear = "new stage" | "base" | "Project" | "overflow";
+
+/** Why a frame is pending, in the order `explain` asks: drawn only in another
+ *  view, else the first part of its key that differs from the parts this view
+ *  last credited it with, else one timeout of that very key, else the clear
+ *  that dropped it, else never drawn. */
+const PREPARATION_REASONS = [
+  "view",
+  "shared",
+  "previous Shot",
+  "Shot",
+  "modules",
+  "isolation",
+  "timed out",
+  "cleared: new stage",
+  "cleared: base",
+  "cleared: Project",
+  "cleared: overflow",
+  "never drawn",
+] as const;
+export type PreparationReason = (typeof PREPARATION_REASONS)[number];
+
+/** What `window.__dailiesPrep` holds under the perf flag. */
+export interface PreparationReport {
+  /** The passes begun: for a queued Play, and while paused. */
+  passes: { foreground: number; background: number };
+  /** Why the prepared set was last cleared; null: never. */
+  cleared: PreparedClear | null;
+  /** The last pass begun. */
+  last: PreparationBreakdown | null;
+}
+
+/** One pass: per reason, how many of its frames were pending for it, and the
+ *  first few as `<Shot id>@<local frame>`. */
+export interface PreparationBreakdown {
+  background: boolean;
+  frames: number;
+  reasons: Partial<Record<PreparationReason, { count: number; examples: string[] }>>;
+}
+
+/** Examples kept per reason. */
+const EXAMPLES = 3;
+
+/** The report of the latest `PreparedFrames` made under the perf flag. */
+let report: PreparationReport | null = null;
+
+/** That report, or null with the perf flag off. */
+export function preparationReport(): PreparationReport | null {
+  return report;
+}
+
+/** What a `PreparedFrames` keeps under the perf flag. */
+interface PreparationDiagnostics {
+  /** The parts each frame was last credited with in each view, by
+   *  `drawnKey`. */
+  drawn: Map<string, PreparationKeyParts>;
+  /** Every `PreparationKeyParts.id` credited in any view. */
+  drawnAnywhere: Set<string>;
+  report: PreparationReport;
+  /** `?perf=log`: one console line per pass as well. */
+  log: boolean;
+}
+
+/** ponytail: the record is bounded by a whole clear, like the runtime's raster
+ *  key history. It serves the perf report alone, and what a clear costs is a
+ *  few frames reading "never drawn" until they are drawn again. */
+const DRAWN_LIMIT = 4096;
+
+/** How many keys a `PreparedFrames` holds, credited, timed out once and given
+ *  up together, before it starts over: a long session of edits mints new keys
+ *  and never retires old ones. */
+const PREPARED_LIMIT = 20_000;
+
+const drawnKey = (parts: PreparationKeyParts): string => `${parts.view}#${parts.id}`;
+
+/** A new report, which `preparationReport` and `window.__dailiesPrep` show
+ *  from now on: the page has one store. */
+function startDiagnostics(log: boolean): PreparationDiagnostics {
+  const own: PreparationReport = { passes: { foreground: 0, background: 0 }, cleared: null, last: null };
+  report = own;
+  if (typeof window !== "undefined") (window as unknown as { __dailiesPrep?: PreparationReport }).__dailiesPrep = own;
+  return { drawn: new Map(), drawnAnywhere: new Set(), report: own, log };
+}
+
+function reasonOf(
+  parts: PreparationKeyParts,
+  sameView: PreparationKeyParts | undefined,
+  drawnElsewhere: boolean,
+  timedOut: boolean,
+  cleared: PreparedClear | null,
+): PreparationReason {
+  if (timedOut) return "timed out";
+  // Never drawn in this view: the view is what moved, if any other drew it.
+  if (sameView === undefined) return drawnElsewhere ? "view" : "never drawn";
+  if (parts.shared !== sameView.shared) return "shared";
+  if (parts.prev !== sameView.prev) return "previous Shot";
+  if (parts.shot !== sameView.shot) return "Shot";
+  if (parts.modules !== sameView.modules) return "modules";
+  if (parts.isolation !== sameView.isolation) return "isolation";
+  // The very key it was credited with: only a clear drops a credited key.
+  return cleared === null ? "never drawn" : `cleared: ${cleared}`;
+}
+
+/**
+ * The keys this stage has drawn, the ones it gave up on, and the ones that
+ * timed out once. Owned by the store, which clears it whenever the GPU state
+ * the keys stand for is replaced: a new renderer, a moved base, another
+ * Project.
+ */
+export class PreparedFrames {
+  /** Presented in the playing presentation by their own publication, or
+   *  drawn whole by the transport. */
+  private readonly keys = new Set<string>();
+  /** Timed out twice: not asked for again until the key or the base moves. */
+  private readonly gaveUp = new Set<string>();
+  /** Timed out once, with no external claim pending at the deadline. */
+  private readonly timedOut = new Set<string>();
+  /** Under the perf flag only, read when the store makes this. */
+  private readonly diagnostics: PreparationDiagnostics | null = perf === null ? null : startDiagnostics(perf === "log");
+
+  /** `frames` less what is prepared or given up. */
+  pending(frames: readonly PreparationFrame[]): PreparationFrame[] {
+    return frames.filter((entry) => !this.keys.has(entry.key) && !this.gaveUp.has(entry.key));
+  }
+
+  /** One frame, by how the stage said it ended (bridge v51). `"presented"`
+   *  prepares its key alone; a second `"timeout"` gives the key up; a
+   *  `"timeout-pending"` (a load still out at the deadline) counts nothing, so
+   *  the frame is asked for again. */
+  credit(entry: PreparationFrame, outcome: ShotPreparedOutcome): void {
+    if (outcome === "timeout-pending") return;
+    if (this.keys.size + this.gaveUp.size + this.timedOut.size >= PREPARED_LIMIT) this.clear("overflow");
+    if (outcome === "timeout") {
+      if (this.timedOut.delete(entry.key)) this.gaveUp.add(entry.key);
+      else this.timedOut.add(entry.key);
+      return;
+    }
+    this.timedOut.delete(entry.key);
+    this.keys.add(entry.key);
+    const diagnostics = this.diagnostics;
+    if (diagnostics === null || entry.parts === undefined) return;
+    if (diagnostics.drawn.size >= DRAWN_LIMIT) {
+      diagnostics.drawn.clear();
+      diagnostics.drawnAnywhere.clear();
+    }
+    diagnostics.drawn.set(drawnKey(entry.parts), entry.parts);
+    diagnostics.drawnAnywhere.add(entry.parts.id);
+  }
+
+  clear(reason: PreparedClear): void {
+    this.keys.clear();
+    this.gaveUp.clear();
+    this.timedOut.clear();
+    if (this.diagnostics !== null) this.diagnostics.report.cleared = reason;
+  }
+
+  /** Under the perf flag only: why each frame of a pass that begins is
+   *  pending, kept as the report's `last`, and under `?perf=log` one console
+   *  line. */
+  explain(frames: readonly PreparationFrame[], background: boolean): void {
+    const diagnostics = this.diagnostics;
+    if (diagnostics === null) return;
+    const { drawn, drawnAnywhere, report: own } = diagnostics;
+    const reasons: PreparationBreakdown["reasons"] = {};
+    for (const { key, parts } of frames) {
+      if (parts === undefined) continue;
+      const reason = reasonOf(parts, drawn.get(drawnKey(parts)), drawnAnywhere.has(parts.id), this.timedOut.has(key), own.cleared);
+      const row = (reasons[reason] ??= { count: 0, examples: [] });
+      row.count += 1;
+      if (row.examples.length < EXAMPLES) row.examples.push(parts.id);
+    }
+    own.passes[background ? "background" : "foreground"] += 1;
+    own.last = { background, frames: frames.length, reasons };
+    if (!diagnostics.log) return;
+    const words = PREPARATION_REASONS.flatMap((reason) => {
+      const row = reasons[reason];
+      return row === undefined ? [] : [`${reason} ${row.count} (${row.examples.join(", ")})`];
+    });
+    console.debug(`[prep] ${background ? "background" : "play"} pass, ${frames.length} frames: ${words.join("; ")}`);
+  }
+}