@dailies-studio/shot-editor 0.1.0

package/src/panels/inspector/animate/BlockTiming.tsx

@@ -0,0 +1,341 @@
+// The focused block's params, timing and easing.
+//
+// ── WHY THIS IS NOT `KeyframeEditor` ───────────────────────────────────
+//
+// `@dailies-studio/timeline`'s ease editor is a fine component and its INPUTS
+// are keyframe-shaped: `refs: KeyframeAddr[]` and a `TimelineGesture` whose
+// capture emits `{kind:"setEase", refs}`. There are no keyframes in this lane,
+// so every one of those would be a fabricated address. What DOES transfer is
+// everything pure: `EASE_PRESETS`, `matchPreset`, `SPRING_DEFAULT`, and the pad
+// geometry `padToPx`/`pxToPad`. Those are imported, not re-derived, so the two
+// chromes cannot disagree about what "Ease Out" means.
+//
+// ── THE SPRING WART, AND THE TAIL THAT ADMITS IT ───────────────────────
+//
+// A spring has an INTRINSIC duration in seconds. So dragging a spring block's
+// right edge changes where its window CLIPS, not how fast it settles — which is
+// correct physics and matches springs everywhere else in the engine, but is
+// invisible unless the UI says so. It says so twice: the duration field is
+// disabled with the reason attached, and the preview draws the part of the
+// settle that falls OUTSIDE the block window as a dashed tail. If the tail is
+// long, the block is cutting the spring off mid-flight, and the author can see
+// exactly that.
+import { useRef } from "react";
+import {
+  blockProgressAt,
+  motionPresets,
+  presetsForSlot,
+  MIN_ANIMATE_FRAMES,
+} from "@dailies-studio/shot/doc";
+import type { AnimBlock } from "@dailies-studio/shot/doc";
+import { EASE_PRESETS, SPRING_DEFAULT, easeSelection, padToPx, pxToPad } from "@dailies-studio/timeline";
+import type { PadGeom } from "@dailies-studio/timeline";
+import { InspectorRow, InspectorSection, NumberField, polylinePoints } from "@dailies-studio/ui";
+import type { Ease, SpringEase, Value } from "@dailies-studio/engine";
+import type { PointerEvent as ReactPointerEvent } from "react";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { ParamRow } from "../ParamRow.js";
+import { useFocusedBlock } from "./useBlocks.js";
+
+const PAD_GEOM: PadGeom = { width: 216, height: 132, padY: 30 };
+const PREVIEW_W = 216;
+const PREVIEW_H = 72;
+const PREVIEW_PAD = 8;
+const PREVIEW_SAMPLES = 96;
+/** How far past the block's own window the settle tail is drawn, as a multiple
+ *  of the window. Two windows is enough to show a spring that has not settled
+ *  and short enough that a settled one draws a flat stub. */
+const TAIL_FACTOR = 2;
+
+export function BlockTiming() {
+  const store = useStore();
+  // A STATE SLICE OR NULL, never a fresh fallback object: a selector that
+  // mints `{num: 30, den: 1}` per call gives useSyncExternalStore a snapshot
+  // that is never Object.is-stable, which is an infinite re-render the moment
+  // this mounts with no document. Unreachable today only because the
+  // inspector early-returns on a null doc — this keeps it unreachable.
+  const fps = useShotEditor((s) => s.doc?.fps ?? null) ?? { num: 30, den: 1 };
+  const ref = useFocusedBlock();
+  if (ref === null) return null;
+  const { layer, block } = ref;
+  const preset = motionPresets[block.preset];
+  const duration = Math.max(1, Math.trunc(block.durationFrames));
+  const spring = block.ease?.type === "spring";
+
+  return (
+    <InspectorSection title="Timing" persistKey="shot:animate:timing">
+      <InspectorRow>
+        <NumberField
+          value={block.frame}
+          label="Start"
+          ariaLabel="Block start"
+          min={0}
+          step={1}
+          onCommit={(next) => store.setBlockTiming(layer.id, block.id, Math.max(0, next), duration)}
+        />
+        <NumberField
+          value={duration}
+          label="Frames"
+          ariaLabel="Block frames"
+          min={MIN_ANIMATE_FRAMES}
+          step={1}
+          // A spring's duration is set by its physics. The field still SHOWS the
+          // window (it is real: it is where the block stops contributing), it
+          // just refuses to pretend that changing it retimes the motion.
+          disabled={spring}
+          {...(spring ? { title: "A spring settles in its own time — edit stiffness and damping." } : {})}
+          onCommit={(next) =>
+            store.setBlockTiming(layer.id, block.id, block.frame, Math.max(MIN_ANIMATE_FRAMES, next))
+          }
+        />
+      </InspectorRow>
+
+      {preset !== undefined &&
+        preset.params.map((spec) => (
+          <ParamRow
+            key={spec.name}
+            spec={spec}
+            value={paramValue(block, spec.name, spec.default)}
+            onCommit={(next) => store.setBlockParams(layer.id, block.id, { [spec.name]: next })}
+          />
+        ))}
+
+      <EaseControl
+        {...(block.ease === undefined ? {} : { ease: block.ease })}
+        onEase={(ease) => store.setBlockEase(layer.id, block.id, ease)}
+        onScrub={(ease) => store.setBlockEase(layer.id, block.id, ease)}
+      />
+      <SettlePreview block={block} fps={fps} />
+
+      {/* The preset itself is swappable in place, so "make that a slide instead"
+          keeps the block's timing and easing rather than deleting and redoing. */}
+      <InspectorRow label="Preset">
+        <select
+          className="select"
+          aria-label="Block preset"
+          value={block.preset}
+          onChange={(e) => store.setBlockPreset(layer.id, block.id, e.target.value)}
+        >
+          {presetsForSlot(block.slot).map((p) => (
+            <option key={p.id} value={p.id}>
+              {p.label}
+            </option>
+          ))}
+        </select>
+      </InspectorRow>
+    </InspectorSection>
+  );
+}
+
+function paramValue(block: AnimBlock, name: string, fallback: Value): Value {
+  const v = block.params[name];
+  return v === undefined ? fallback : v;
+}
+
+// ---- easing ------------------------------------------------------------------
+
+/**
+ * The ease row, plus whichever editor the chosen ease needs.
+ *
+ * Takes an `Ease` and not a block, because the CAMERA's shots carry one too and
+ * `clipProgress01` reads it from both the same way. Two ease editors would be
+ * two places for "Ease Out" to mean something slightly different, which is the
+ * whole reason `EASE_PRESETS` is imported rather than re-declared.
+ */
+export function EaseControl(props: {
+  ease?: Ease;
+  /** What the select is called. The subject differs between the two callers and
+   *  the accessible name has to say which one the author is looking at. */
+  ariaLabel?: string;
+  onEase(ease: Ease): void;
+  onScrub(ease: Ease): void;
+}) {
+  const ease = props.ease;
+  // `easeSelection` takes a LIST because the shared editor is multi-select. One
+  // block is a list of one, and reusing it keeps "Custom" meaning exactly what
+  // it means in the other two chromes.
+  const sel = easeSelection(ease === undefined ? [] : [ease]);
+
+  return (
+    <>
+      <InspectorRow label="Ease">
+        <select
+          className="select"
+          aria-label={props.ariaLabel ?? "Block ease"}
+          value={sel.selectValue}
+          onChange={(e) => {
+            const preset = EASE_PRESETS.find((p) => p.id === e.target.value);
+            if (preset !== undefined) props.onEase(preset.ease);
+          }}
+        >
+          {EASE_PRESETS.map((p) => (
+            <option key={p.id} value={p.id}>
+              {p.label}
+            </option>
+          ))}
+          {sel.selectValue === "custom" && (
+            <option value="custom" disabled>
+              Custom
+            </option>
+          )}
+          {sel.selectValue === "mixed" && (
+            <option value="mixed" disabled>
+              —
+            </option>
+          )}
+        </select>
+      </InspectorRow>
+      {sel.ease?.type === "bezier" && <BezierPad handles={sel.ease.handles} onEase={props.onScrub} />}
+      {sel.ease?.type === "spring" && <SpringFields spring={sel.ease} onEase={props.onEase} />}
+    </>
+  );
+}
+
+function BezierPad(props: {
+  handles: readonly [number, number, number, number];
+  onEase(ease: Ease): void;
+}) {
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  const drag = useRef<{ index: 0 | 1; base: [number, number, number, number] } | null>(null);
+
+  const down =
+    (index: 0 | 1) =>
+    (e: ReactPointerEvent<SVGCircleElement>): void => {
+      if (e.button !== 0) return;
+      e.currentTarget.setPointerCapture(e.pointerId);
+      const h = props.handles;
+      drag.current = { index, base: [h[0], h[1], h[2], h[3]] };
+    };
+
+  const move = (e: ReactPointerEvent<SVGCircleElement>): void => {
+    const d = drag.current;
+    const svg = svgRef.current;
+    if (d === null || svg === null) return;
+    const rect = svg.getBoundingClientRect();
+    const [x, y] = pxToPad(PAD_GEOM, e.clientX - rect.left, e.clientY - rect.top);
+    // Rebuilt from the DRAG-START handles, so the untouched one cannot creep as
+    // the live value it is being compared against changes underneath.
+    const handles: [number, number, number, number] =
+      d.index === 0 ? [x, y, d.base[2], d.base[3]] : [d.base[0], d.base[1], x, y];
+    props.onEase({ type: "bezier", handles });
+  };
+
+  const up = (e: ReactPointerEvent<SVGCircleElement>): void => {
+    if (drag.current === null) return;
+    drag.current = null;
+    e.currentTarget.releasePointerCapture(e.pointerId);
+  };
+
+  const h = props.handles;
+  const [ax, ay] = padToPx(PAD_GEOM, 0, 0);
+  const [bx, by] = padToPx(PAD_GEOM, 1, 1);
+  const [x1, y1] = padToPx(PAD_GEOM, h[0], h[1]);
+  const [x2, y2] = padToPx(PAD_GEOM, h[2], h[3]);
+  const handle = (index: 0 | 1) => ({
+    className: "insp-pad-handle",
+    r: 4.5,
+    onPointerDown: down(index),
+    onPointerMove: move,
+    onPointerUp: up,
+    onPointerCancel: () => {
+      drag.current = null;
+    },
+  });
+
+  return (
+    <svg ref={svgRef} className="insp-pad" width={PAD_GEOM.width} height={PAD_GEOM.height}>
+      <rect
+        className="insp-pad-box"
+        x={0.5}
+        y={PAD_GEOM.padY + 0.5}
+        width={PAD_GEOM.width - 1}
+        height={PAD_GEOM.height - 2 * PAD_GEOM.padY - 1}
+        rx={3}
+      />
+      <path className="insp-pad-curve" d={`M ${ax} ${ay} C ${x1} ${y1} ${x2} ${y2} ${bx} ${by}`} />
+      <line className="insp-pad-arm" x1={ax} y1={ay} x2={x1} y2={y1} />
+      <line className="insp-pad-arm" x1={bx} y1={by} x2={x2} y2={y2} />
+      <circle {...handle(0)} cx={x1} cy={y1} />
+      <circle {...handle(1)} cx={x2} cy={y2} />
+    </svg>
+  );
+}
+
+const SPRING_FIELDS = [
+  { key: "stiffness", label: "Stiffness", min: 1, max: 1000, step: 1 },
+  { key: "damping", label: "Damping", min: 0, max: 200, step: 0.5 },
+  { key: "mass", label: "Mass", min: 0.05, max: 20, step: 0.05 },
+] as const;
+
+function SpringFields(props: { spring: SpringEase; onEase(ease: Ease): void }) {
+  return (
+    <InspectorRow>
+      {SPRING_FIELDS.map((f) => (
+        <NumberField
+          key={f.key}
+          value={props.spring[f.key]}
+          label={f.label}
+          ariaLabel={`Spring ${f.label.toLowerCase()}`}
+          min={f.min}
+          max={f.max}
+          step={f.step}
+          onCommit={(v) => props.onEase({ ...SPRING_DEFAULT, ...props.spring, [f.key]: v })}
+        />
+      ))}
+    </InspectorRow>
+  );
+}
+
+// ---- the preview, and the tail --------------------------------------------------
+
+function SettlePreview(props: { block: AnimBlock; fps: { num: number; den: number } }) {
+  const { block, fps } = props;
+  const duration = Math.max(1, Math.trunc(block.durationFrames));
+  const spring = block.ease?.type === "spring";
+  // Sampled through `blockProgressAt` — the SAME function the renderer folds
+  // with. A preview drawn from a local re-implementation of the ease would
+  // eventually disagree with the pixels, which is the one thing a preview must
+  // never do.
+  const to = block.frame + (spring ? duration * (1 + TAIL_FACTOR) : duration);
+  const samples: Array<{ frame: number; value: number }> = [];
+  for (let i = 0; i < PREVIEW_SAMPLES; i += 1) {
+    const frame = block.frame + ((to - block.frame) * i) / (PREVIEW_SAMPLES - 1);
+    samples.push({ frame, value: blockProgressAt(block, frame, fps) ?? 0 });
+  }
+  const line = polylinePoints(samples, PREVIEW_W, PREVIEW_H, PREVIEW_PAD);
+  if (line === null) return null;
+  // The window's right edge in preview px, so the tail is drawn from exactly
+  // where the block stops contributing.
+  const edgeX = spring ? (duration / (to - block.frame)) * PREVIEW_W : PREVIEW_W;
+
+  return (
+    <div className="insp-preview animate-preview" data-testid="block-preview">
+      <svg width={PREVIEW_W} height={PREVIEW_H}>
+        {/* One polyline, clipped twice: solid inside the window, dashed after.
+            Two <polyline>s over the same points with opposite clips beats
+            splitting the sample array, because the split point then cannot land
+            between two samples and jitter as the duration changes. */}
+        <defs>
+          <clipPath id="blk-in">
+            <rect x={0} y={0} width={edgeX} height={PREVIEW_H} />
+          </clipPath>
+          <clipPath id="blk-out">
+            <rect x={edgeX} y={0} width={PREVIEW_W - edgeX} height={PREVIEW_H} />
+          </clipPath>
+        </defs>
+        <polyline className={spring ? "is-spring" : ""} points={line.points} clipPath="url(#blk-in)" />
+        {spring && (
+          <>
+            <polyline className="is-tail" points={line.points} clipPath="url(#blk-out)" />
+            <line className="animate-preview-edge" x1={edgeX} y1={0} x2={edgeX} y2={PREVIEW_H} />
+          </>
+        )}
+      </svg>
+      {spring && (
+        <span className="insp-dim animate-preview-note">
+          dashed = after the block ends; the spring holds at its clipped value
+        </span>
+      )}
+    </div>
+  );
+}

package/src/panels/inspector/animate/DuringBlocks.tsx

@@ -0,0 +1,85 @@
+// The During list: the blocks the Animate gesture writes, plus a palette to add
+// one without a gesture.
+//
+// Each row FOCUSES rather than expanding inline. `state.selectedBlock` is the
+// same bit the dock's bars write, so clicking a row here highlights the bar
+// there and puts its timing in one editor below — instead of N accordion
+// editors that each claim to be "the" timing controls.
+import { motionPresets, presetsForSlot } from "@dailies-studio/shot/doc";
+import { InspectorSection } from "@dailies-studio/ui";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { useSelectedLayers } from "../useDocWrite.js";
+import { useBlocksInSlot } from "./useBlocks.js";
+
+const DEFAULT_FRAMES = 24;
+
+export function DuringBlocks() {
+  const store = useStore();
+  const layers = useSelectedLayers();
+  const blocks = useBlocksInSlot("during");
+  const focused = useShotEditor((s) => s.selectedBlock);
+  // The inspector's subject scene. Its layers are the selection's, so this is
+  // the scene every row here belongs to by construction.
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const multi = layers.length > 1;
+  if (layers.length === 0 || sceneId === null) return null;
+
+  return (
+    <InspectorSection title="During" persistKey="shot:animate:during">
+      {blocks.length === 0 ? (
+        <p className="inspector-empty">
+          Press ⇧A, then drag on the canvas. The edit becomes a block ending at the playhead.
+        </p>
+      ) : (
+        <ul className="animate-blocks" aria-label="During blocks">
+          {blocks.map(({ layer, block }) => {
+            const on = focused?.layerId === layer.id && focused.blockId === block.id;
+            const label = motionPresets[block.preset]?.label ?? block.preset;
+            return (
+              <li key={`${layer.id}:${block.id}`}>
+                <button
+                  type="button"
+                  className="animate-block-row"
+                  aria-pressed={on}
+                  aria-label={`Block ${label} on ${layer.label}`}
+                  onClick={() => store.selectBlock({ sceneId, layerId: layer.id, blockId: block.id })}
+                >
+                  <span className="animate-block-name">
+                    {label}
+                    {/* Which layer, but only when there IS more than one — on a
+                        single selection the suffix would be noise on every row. */}
+                    {multi && <em className="animate-block-owner"> · {layer.label}</em>}
+                  </span>
+                  <span className="animate-block-span">
+                    f{block.frame}–{block.frame + Math.max(1, Math.trunc(block.durationFrames))}
+                  </span>
+                </button>
+                <button
+                  type="button"
+                  className="animate-block-remove"
+                  aria-label={`Remove ${label} on ${layer.label}`}
+                  onClick={() => store.removeBlock(layer.id, block.id)}
+                >
+                  ✕
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+      <div className="animate-palette" role="group" aria-label="During presets">
+        {presetsForSlot("during").map((preset) => (
+          <button
+            key={preset.id}
+            type="button"
+            className="animate-preset"
+            aria-label={`Add ${preset.label}`}
+            onClick={() => store.addBlock("during", preset.id, DEFAULT_FRAMES)}
+          >
+            + {preset.label}
+          </button>
+        ))}
+      </div>
+    </InspectorSection>
+  );
+}

package/src/panels/inspector/animate/InOutPresets.tsx

@@ -0,0 +1,57 @@
+// The In and Out palettes: click a preset, every selected layer gets that block.
+//
+// ── WHY THEY STACK RATHER THAN REPLACE ─────────────────────────────────
+//
+// Clicking Fade then Slide gives a layer that fades AND slides, because the
+// channel combinators commute — the fold has no ordering rule to get wrong. So
+// the palette is a set of buttons, not a radio group, and a preset already on
+// the layer shows as active and REMOVES on a second click. A replace-only
+// palette would make "fade and slide in" unauthorable, which is the single most
+// common entrance in the entire category.
+import { presetsForSlot } from "@dailies-studio/shot/doc";
+import type { BlockSlot } from "@dailies-studio/shot/doc";
+import { InspectorSection } from "@dailies-studio/ui";
+import { useStore } from "../../../state/context.js";
+import { useSelectedLayers } from "../useDocWrite.js";
+import { useBlocksInSlot } from "./useBlocks.js";
+
+/** The default window for a palette-added entrance or exit. */
+const DEFAULT_FRAMES = 12;
+
+export function InOutPresets(props: { slot: BlockSlot; title: string }) {
+  const store = useStore();
+  const layers = useSelectedLayers();
+  const present = useBlocksInSlot(props.slot);
+  if (layers.length === 0) return null;
+
+  // A preset counts as "on" when EVERY selected layer carries it. Partial
+  // coverage reads as off, so one more click completes the set rather than
+  // clearing the layers that already had it.
+  const coverage = new Map<string, number>();
+  for (const { block } of present) coverage.set(block.preset, (coverage.get(block.preset) ?? 0) + 1);
+
+  return (
+    <InspectorSection title={props.title} persistKey={`shot:animate:${props.slot}`}>
+      <div className="animate-palette" role="group" aria-label={`${props.title} presets`}>
+        {presetsForSlot(props.slot).map((preset) => {
+          const on = (coverage.get(preset.id) ?? 0) >= layers.length;
+          return (
+            <button
+              key={preset.id}
+              type="button"
+              className="animate-preset"
+              aria-label={`${props.title} ${preset.label}`}
+              aria-pressed={on}
+              onClick={() => {
+                if (on) store.removeBlocksByPreset(props.slot, preset.id);
+                else store.addBlock(props.slot, preset.id, DEFAULT_FRAMES);
+              }}
+            >
+              {preset.label}
+            </button>
+          );
+        })}
+      </div>
+    </InspectorSection>
+  );
+}

package/src/panels/inspector/animate/ResolvedChannels.tsx

@@ -0,0 +1,150 @@
+// What the block stack ADDS UP TO on this layer, at this frame.
+//
+// ── WHY A READOUT AND NOT SEVEN MORE FIELDS ─────────────────────────────
+//
+// Blocks are DELTA writers and they compose (resolve.ts). So "what is this
+// layer's opacity right now" has no single author: it is the base times every
+// active block's contribution, and there is nothing for a field to write into
+// that would not have to pick one of the contributors and hide the rest. The
+// Design tab already solves the writable half — `setEffectiveField` compensates
+// a typed value back through the fold — and this is the other half: a stacked
+// delta model where the author can see the sum is legible, and one where they
+// cannot is a pile of numbers that do not match the screen.
+//
+// ── IT CANNOT DISAGREE WITH THE STAGE, BY CONSTRUCTION ─────────────────
+//
+// Every number here comes out of `resolveLayerAt`, which is the same function
+// the runtime writes onto the mesh and the same one the renderer samples. There
+// is no second fold in this file and there must never be one: a readout that
+// re-derived the composition would be a second answer to a question that has
+// exactly one, and it would drift the first time a channel gained a combinator.
+//
+// ── "WRITING" MEANS DECLARED, NOT DIFFERENT ────────────────────────────
+//
+// A channel is marked when a live block's delta CONTAINS it, not when the
+// folded value happens to differ from identity. The two come apart constantly:
+// an out-fade at its first frame writes opacity 1, and an in-fade that finished
+// forty frames ago still writes opacity 1 and still owns the channel. Marking
+// on "differs from identity" would say "nothing is animating this" one frame
+// before a fade visibly starts, and would need a second copy of resolve.ts's
+// identity table to say it. Declared is both cheaper and truer: the mark means
+// "a block governs this channel", which is exactly what an author about to type
+// in the Design tab needs to know.
+import { InspectorSection, formatValue } from "@dailies-studio/ui";
+import {
+  blockProgressAt,
+  deltaFor,
+  layerDeltaAt,
+  motionPresets,
+  resolveLayerAt,
+} from "@dailies-studio/shot/doc";
+import type { Layer3D, LayerDelta } from "@dailies-studio/shot/doc";
+import type { Rational } from "@dailies-studio/engine";
+import { CHANNELS } from "../../../channels.js";
+import type { Channel } from "../../../channels.js";
+import { useShotEditor } from "../../../state/context.js";
+import { useInspectorFrame, useSelectedLayers } from "../useDocWrite.js";
+
+export function ResolvedChannels() {
+  const layers = useSelectedLayers();
+  const { sceneFrame } = useInspectorFrame();
+  const fps = useShotEditor((s) => s.doc?.fps ?? null);
+  // THE FIRST selected layer. A fan-out would have to answer "what is the
+  // resolved opacity of four layers", which is either four readouts or a
+  // "Mixed" that tells the author nothing about the composition they came here
+  // to understand. One subject, named in the header when there is a choice.
+  const layer = layers[0];
+  if (layer === undefined || fps === null) return null;
+
+  const state = resolveLayerAt(layer, sceneFrame, fps);
+  const delta = layerDeltaAt(layer, sceneFrame, fps);
+  const writers = writersAt(layer, sceneFrame, fps);
+
+  return (
+    <InspectorSection
+      title="Resolved"
+      persistKey="shot:animate:resolved"
+      action={
+        <span className="insp-dim">
+          {layers.length > 1 ? `${layer.label} · ` : ""}f{sceneFrame}
+        </span>
+      }
+    >
+      <dl className="resolved-list" aria-label="Resolved channels">
+        {CHANNELS.map((channel) => {
+          const by = writers.get(channel.key);
+          return (
+            <div
+              key={channel.key}
+              className="resolved-row"
+              data-channel={channel.key}
+              data-live={by !== undefined}
+            >
+              <dt className="resolved-label">{channel.label}</dt>
+              <dd className="resolved-value">{channel.read(state)}</dd>
+              <dd
+                className="resolved-by"
+                title={by === undefined ? undefined : `${by.join(", ")} → ${deltaText(channel.key, delta)}`}
+              >
+                {by?.join(", ") ?? ""}
+              </dd>
+            </div>
+          );
+        })}
+      </dl>
+    </InspectorSection>
+  );
+}
+
+/**
+ * Which live blocks declare each channel, by preset label.
+ *
+ * `blockProgressAt` + `deltaFor` is the same pair `layerDeltaAt` folds with, so
+ * a block counted here is exactly a block that contributed to the numbers
+ * beside it — including the outside-the-window holds, which are the cases a
+ * naive "is the playhead inside the bar" test gets wrong in both directions.
+ */
+function writersAt(layer: Layer3D, sceneFrame: number, fps: Rational): Map<Channel, string[]> {
+  const out = new Map<Channel, string[]>();
+  for (const block of layer.blocks) {
+    const p = blockProgressAt(block, sceneFrame, fps);
+    if (p === null) continue;
+    const label = motionPresets[block.preset]?.label ?? block.preset;
+    for (const key of Object.keys(deltaFor(block.preset, block.slot, block.params, p)) as Channel[]) {
+      const at = out.get(key);
+      if (at === undefined) out.set(key, [label]);
+      // Two Fades on one channel are one name: the row says WHAT governs the
+      // channel, and the count is the dock's job.
+      else if (!at.includes(label)) at.push(label);
+    }
+  }
+  return out;
+}
+
+/** The fold's own contribution to one channel, in that channel's combinator's
+ *  terms — a multiply reads "×", an add reads signed. It is the answer to "how
+ *  much of this number is the blocks", which the resolved value alone hides. */
+function deltaText(key: Channel, d: Required<LayerDelta>): string {
+  switch (key) {
+    case "opacity":
+      return `×${formatValue(d.opacity, 0.01)}`;
+    case "offset":
+      return d.offset.map(signed).join(", ");
+    case "scale":
+      return d.scale.map((v) => `×${formatValue(v, 0.01)}`).join(", ");
+    case "tilt":
+      return d.tilt.map((v) => `${signed(v)}°`).join(", ");
+    case "roll":
+      return `${signed(d.roll)}°`;
+    case "blurPx":
+      return `${formatValue(d.blurPx, 0.1)} px`;
+    case "reveal":
+      return `${formatValue(d.reveal * 100, 1)}%`;
+    case "textPhase":
+      return `${formatValue(d.textPhase * 100, 1)}%`;
+  }
+}
+
+function signed(v: number): string {
+  return `${v >= 0 ? "+" : ""}${formatValue(v, 0.1)}`;
+}