@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/useDocWrite.ts

@@ -8,54 +8,92 @@
 // Both halves are load-bearing and neither is optional:
 //
 //   Reading BASE would tell the author 0 while the layer sat at 150, because
-//     what is on screen is `base ⊕ blocks(frame)`. That is the exact defect the
-//     2D lane's read-effective rule was written to close, and it is worse here
-//     because a shot's blocks are the normal case rather than the exception.
+//     what is on screen is the tracks resolved at the frame. That is the exact
+//     defect the 2D lane's read-effective rule was written to close, and it is
+//     worse here because a shot's keyframed fields are the normal case rather
+//     than the exception.
 //
 //   Writing the typed value into the BASE would make the field disagree with
 //     itself: type 100, watch it read back 250. So a write goes through
 //     `setEffectiveField`, which is the same arithmetic a canvas drag uses —
 //     the inspector and a drag are one operation with different input devices.
 //
+// ── AND THE THIRD HALF: A DRAG ─────────────────────────────────────────
+//
+// A widget that is DRAGGED (the colour picker's three bars, a slider) never
+// calls `commit` while the pointer is down. It calls `scrub.move` per pointer
+// event and lets the release commit. So a section that wires only the commit
+// half has a control that moves its thumb and writes nothing. `useScrub` and
+// `useSelectionScrub` below are that half, over the store's scrub trio.
+//
 // ── WHAT IS GONE FROM THE 2D LANE'S VERSION ────────────────────────────
 //
-// `useNodeTrackField` and everything around it. There are no keyframe tracks in
-// this lane, so there are no diamonds, no per-property sequenced/static fork,
-// and — the real simplification — no `selectionRefusal`: the 2D lane's one row
-// was "this prop is sequenced, select it alone to key it", which cannot arise
-// here. `planSelection` collapses to dedupe plus document order.
-import { useCallback, useEffect, useState } from "react";
-import { animateFieldEdit, effectiveTransform, setEffectiveField } from "@dailies-studio/shot/doc";
-import type { Doc3D, Layer3D, TransformField, Transform3D } from "@dailies-studio/shot/doc";
+// `useNodeTrackField` and everything around it. This lane HAS keyframe tracks
+// (schema v12) and does have diamonds — `KeyframeDot` — but not a per-property
+// sequenced/static fork and not a `selectionRefusal`. Both were consequences of
+// the 2D lane's per-field write path; here every section keeps building a plain
+// `layer -> layer` and `routeLayerEdit` at `writeSelection` below turns the diff
+// into a keyframe on any path the layer animates. So `planSelection` collapses
+// to dedupe plus document order, and no section knows tracks exist.
+import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
+import type { ShotEditorStore } from "../../state/store.js";
+import {
+  containerFrame,
+  effectiveTransform,
+  homeOf,
+  keyframeMinter,
+  lockRefusal,
+  lockedLayerEdited,
+  resolveSceneTracksAt,
+  resolveTracksAt,
+  routeSceneEdit,
+  sceneAsShown,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D, Scene3D, TransformField, Transform3D } from "@dailies-studio/shot/doc";
+import type { ScrubHandlers } from "@dailies-studio/ui";
 import { useShotEditor, useStore } from "../../state/context.js";
+import { authoringFrame } from "../../state/viewMode.js";
+import { commitTransformField, writeSelection } from "../../state/fieldWrite.js";
 
-/** A colour swatch takes no drag, so it has no scrub — but `ColorPicker`'s
- *  contract requires the trio, because the same widget IS scrubbed when it sits
- *  on a keyframable property elsewhere. Three no-ops, in one place. */
-export const NO_SCRUB = { start: () => {}, move: () => {}, end: () => {} };
+// A `NO_SCRUB` triple of no-ops used to live here, passed by every section that
+// believed "a colour swatch takes no drag". The claim was false: `ColorPicker`
+// routes its SV square, its hue bar and its alpha bar ENTIRELY through
+// `scrub.move`, and `PropControl`'s sliders take the same path, so every
+// section that passed it had a colour reachable only through the hex and R/G/B
+// boxes. `useScrub` and `useSelectionScrub` below are what replaced it, and it
+// is deleted rather than deprecated so a new section cannot reintroduce the bug
+// by reaching for the convenient-looking constant.
 
 /** THE one document-edit seam. Every inspector commit is a transaction, so it
- *  is one undo entry however many layers it touched. */
+ *  is one undo entry however many layers it touched. A write that edits a
+ *  locked layer lands nothing and names that layer, the same rule
+ *  `writeSelection` applies per layer. */
 export function useDocWrite(): (write: (doc: Doc3D) => Doc3D) => void {
   const store = useStore();
-  return useCallback((write) => store.edit(write), [store]);
+  return useCallback(
+    (write) => {
+      let refusal: string | null = null;
+      const ran = store.edit((base) => {
+        const next = write(base);
+        const locked = lockedLayerEdited(base, next);
+        if (locked === null) return next;
+        refusal = lockRefusal(locked);
+        return base;
+      });
+      if (ran && refusal !== null) store.reportError(refusal);
+    },
+    [store],
+  );
 }
 
-/** MASTER frame -> the scene-local frame the effective read wants. Derived
- *  rather than stored: the scene's start is a prefix sum, so a trim upstream
- *  moves it and a cached offset would go stale silently. Pure and EXPORTED,
- *  because it has callers with different frames: the display hook below
- *  (coalesced) and every commit path (live at the click or keystroke —
- *  useTransformWrite here, ShotSection's "Set from current framing"). */
-export function sceneLocalFrame(doc: Doc3D, sceneId: string, frame: number): number {
-  let start = 0;
-  for (const id of doc.scenes) {
-    const duration = Math.max(1, Math.trunc(doc.scenesById[id]?.durationFrames ?? 0));
-    if (id === sceneId) break;
-    start += duration;
-  }
-  return Math.max(0, frame - start);
-}
+// `sceneLocalFrame` and a private `containerFrame` used to live here, and the
+// store carried a third open-coding of the same arithmetic. Three prefix sums
+// over one mapping, one of which clamped a scene duration at 1 where the other
+// two clamped at 0 — they agreed only because `validate` refuses a duration
+// below 1, which is a gate holding up an invariant nobody asked it to hold.
+// There is one now: `containerFrame` in @dailies-studio/shot, imported above.
+// Every site here calls it, including the ones that used to open-code its
+// definition-vs-shot fork inline.
 
 /** How stale the inspector's DISPLAYED frame may run while the playhead is
  *  moving fast. ~10Hz keeps a scrub's numbers live enough to read against the
@@ -83,69 +121,233 @@ const INSPECTOR_FRAME_MS = 100;
  *  that subscribed the raw frame would run its resolver fold per tick. */
 export function useCoalescedFrame(): number {
   const store = useStore();
-  const [frame, setFrame] = useState(() => store.getState().frame);
-  useEffect(() => {
-    let timer: ReturnType<typeof setTimeout> | null = null;
-    let lastPush = 0;
-    const push = (f: number): void => {
-      lastPush = performance.now();
-      setFrame(f);
-    };
-    const onChange = (): void => {
-      const s = store.getState();
-      // Held during playback. The pause itself notifies (playing flips), and
-      // that notification falls through to the flush below.
-      if (s.playing) return;
-      if (timer !== null) {
-        clearTimeout(timer);
-        timer = null;
-      }
-      const since = performance.now() - lastPush;
-      if (since >= INSPECTOR_FRAME_MS) {
-        push(s.frame);
-        return;
+  const source = coalescedFrameSource(store, "frame");
+  return useSyncExternalStore(source.subscribe, source.get, source.get);
+}
+
+/** The definition clock (`defFrame`), coalesced by the same policy. A
+ *  readout inside a definition that subscribed the hot channel re-rendered
+ *  per tick of the def-local clock while the transport played. */
+export function useCoalescedDefFrame(): number {
+  const store = useStore();
+  const source = coalescedFrameSource(store, "defFrame");
+  return useSyncExternalStore(source.subscribe, source.get, source.get);
+}
+
+/**
+ * ONE coalescer per store, shared by every `useCoalescedFrame` caller.
+ *
+ * Each caller used to own a raw store subscription, a `useState` and a
+ * trailing timer. `useSelectionValue` instantiates two per field, so the
+ * Typography section alone held eighteen subscriptions and eighteen timers,
+ * every one of which woke on every store notification (sixty a second while
+ * playing) to read the state and return. This is the same policy, held once:
+ * the frame is HELD while the transport plays (the pause itself notifies and
+ * falls through to the flush), trails at ~10 Hz during a scrub, and leads on
+ * a lone seek. Subscribers see one notification per coalesced change through
+ * `useSyncExternalStore`.
+ *
+ * The store subscription exists only while someone listens. A fresh listener
+ * syncs the frame from the store WITHOUT touching `lastPush`: mounting must
+ * not consume the leading edge, or the first seek after mount would coalesce
+ * instead of landing immediately. With nobody listening, `get` reads the
+ * store live rather than a value that went stale in between.
+ */
+interface CoalescedFrameSource {
+  get(): number;
+  subscribe(listener: () => void): () => void;
+}
+type CoalescedClock = "frame" | "defFrame";
+const COALESCED_FRAME_SOURCES = new WeakMap<ShotEditorStore, Partial<Record<CoalescedClock, CoalescedFrameSource>>>();
+function coalescedFrameSource(store: ShotEditorStore, key: CoalescedClock): CoalescedFrameSource {
+  let bucket = COALESCED_FRAME_SOURCES.get(store);
+  if (bucket === undefined) {
+    bucket = {};
+    COALESCED_FRAME_SOURCES.set(store, bucket);
+  }
+  const existing = bucket[key];
+  if (existing !== undefined) return existing;
+  const listeners = new Set<() => void>();
+  let frame = store.getState()[key];
+  let lastPush = 0;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let unsubscribe: (() => void) | null = null;
+  // Only a frame CHANGE spends the leading edge. Every store notification lands
+  // here, so a late non-frame one (an asset-usage fetch after open) would
+  // otherwise make the next lone seek trail.
+  const push = (next: number): void => {
+    if (next === frame) return;
+    lastPush = performance.now();
+    frame = next;
+    for (const listener of [...listeners]) listener();
+  };
+  const onChange = (): void => {
+    const s = store.getState();
+    if (s.playing) return;
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    const since = performance.now() - lastPush;
+    if (since >= INSPECTOR_FRAME_MS) {
+      push(s[key]);
+      return;
+    }
+    // The trailing flush re-reads the store when it fires, so the value that
+    // lands is the newest one, not the one that armed the timer.
+    timer = setTimeout(() => {
+      timer = null;
+      push(store.getState()[key]);
+    }, INSPECTOR_FRAME_MS - since);
+  };
+  const source: CoalescedFrameSource = {
+    get: () => (listeners.size === 0 ? store.getState()[key] : frame),
+    subscribe(listener) {
+      if (listeners.size === 0) {
+        frame = store.getState()[key];
+        unsubscribe = store.subscribe(onChange);
       }
-      // The trailing flush: re-reads the store when it fires, so the value
-      // that lands is the newest one, not the one that armed the timer.
-      timer = setTimeout(() => {
-        timer = null;
-        push(store.getState().frame);
-      }, INSPECTOR_FRAME_MS - since);
-    };
-    // The frame may have moved between render and subscription. A SYNC-UP,
-    // not a rate event: it must not touch `lastPush`, or mounting would
-    // consume the leading edge and the very first seek after mount would
-    // coalesce instead of landing immediately.
-    setFrame(store.getState().frame);
-    const unsubscribe = store.subscribe(onChange);
-    return () => {
-      unsubscribe();
-      if (timer !== null) clearTimeout(timer);
-    };
-  }, [store]);
-  return frame;
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size !== 0) return;
+        unsubscribe?.();
+        unsubscribe = null;
+        if (timer !== null) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      };
+    },
+  };
+  bucket[key] = source;
+  return source;
 }
 
 /** The scene the inspector is looking at, and the SCENE-LOCAL frame — the two
- *  things every effective read needs. The frame is the COALESCED one. */
+ *  things every effective read needs. The frame is the COALESCED one.
+ *
+ *  With a DEFINITION open (unify P2) the container is the definition and the
+ *  frame is the DEF-LOCAL clock: interior keyframes live on def-local frames, so
+ *  an effective read at a master-derived frame would show values from a clock
+ *  the stage is not rendering. */
 export function useInspectorFrame(): { sceneId: string | null; sceneFrame: number } {
   const sceneId = useShotEditor((s) => s.sceneId);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  const defFrame = useCoalescedDefFrame();
   const frame = useCoalescedFrame();
   const doc = useShotEditor((s) => s.doc);
-  if (doc === null || sceneId === null) return { sceneId: null, sceneFrame: 0 };
-  return { sceneId, sceneFrame: sceneLocalFrame(doc, sceneId, frame) };
+  if (doc === null) return { sceneId: null, sceneFrame: 0 };
+  if (editingDef !== null) return { sceneId: editingDef, sceneFrame: defFrame };
+  if (sceneId === null) return { sceneId: null, sceneFrame: 0 };
+  return { sceneId, sceneFrame: containerFrame(doc, sceneId, frame) };
 }
 
-/** Every selected layer, in document order. The ONE place a panel gets its
- *  subjects, so no section re-derives the list with a different answer. */
+/** Every selected layer, in document order, AS PAINTED at the playhead. The ONE
+ *  place a panel gets its subjects, so no section re-derives the list with a
+ *  different answer. Resolves through the CONTAINER (`editingDef ?? sceneId`,
+ *  the store's own `layerContainer` rule), so the right rail works inside a
+ *  definition.
+ *
+ * ── `resolveTracksAt` IS THE READOUT HALF OF THE ASYMMETRY ──────────────
+ *
+ * The header above states that readouts come from the layer as painted, and
+ * until this call only the TRANSFORM half was implemented (`effectiveTransform`
+ * -> `trackedBaseTransform`, which substitutes five channels and nothing else).
+ * Every other tracked path was read straight off the authored constant — and
+ * that constant is DEAD once a track exists, because `routeTrackedEdit` mints
+ * the keyframe and writes the old base BACK (trackOps.ts). Base pinned plus a
+ * readout that reads the base is a control that can never move again: the
+ * slider does not follow the pointer, an arrow nudge is always base+step, and
+ * typing the number the field is showing is diffed against itself and writes
+ * nothing at all. That is one bug over ~70 trackable paths, from
+ * `instance.props.<key>` through `paint.fill.color`, `mesh.color`,
+ * `text.style.sizePx` and the crop boxes.
+ *
+ * The two halves compose rather than collide: `resolveTracksAt` SKIPS transform
+ * paths (tracks.ts), leaving them to `effectiveTransform` below, and it returns
+ * its input by reference for an untracked layer, so the common case allocates
+ * nothing. `tracks` stays on the result, which is what keeps `KeyframeDot`'s
+ * diamond states reading true off a resolved layer.
+ *
+ * DISPLAY ONLY. Writes never come through here: `writeSelection` re-reads its
+ * subjects from the document it is handed, and a scrub capture re-derives from
+ * the gesture's base, so a sampled value cannot be baked into a constant.
+ */
 export function useSelectedLayers(): Layer3D[] {
   const doc = useShotEditor((s) => s.doc);
   const sceneId = useShotEditor((s) => s.sceneId);
+  const editingDef = useShotEditor((s) => s.editingDef);
   const selection = useShotEditor((s) => s.selection);
-  if (doc === null || sceneId === null) return [];
+  const { sceneFrame } = useInspectorFrame();
+  // Memoised on its five inputs: the inspector repaints whole on every
+  // document identity change, i.e. once per rAF frame of any drag anywhere,
+  // and this ran its map/filter/resolve chain once per `useSelectionValue`
+  // site in the open sections (nine in Typography alone) per repaint.
+  return useMemo(() => {
+    if (doc === null) return EMPTY_LAYERS;
+    const container = editingDef ?? sceneId;
+    if (container === null) return EMPTY_LAYERS;
+    const home = homeOf(doc, container);
+    if (home === null) return EMPTY_LAYERS;
+    return selection
+      .map((id) => home.layersById[id])
+      .filter((l): l is Layer3D => l !== undefined)
+      .map((l) => resolveTracksAt(l, sceneFrame, doc.fps));
+  }, [doc, sceneId, editingDef, selection, sceneFrame]);
+}
+const EMPTY_LAYERS: Layer3D[] = [];
+
+/**
+ * `effectiveTransform`, replayed per (layer, frame, fps).
+ *
+ * Every `useSelectionValue` site folds it for every selected layer on every
+ * inspector repaint; the layer objects are immutable on edit and the frame is
+ * the shared coalesced one, so the same fold was answered up to nine times per
+ * section per repaint. One entry per layer object, replaced when the frame or
+ * fps moves.
+ */
+const EFFECTIVE_TRANSFORMS = new WeakMap<
+  Layer3D,
+  { sceneFrame: number; fpsNum: number; fpsDen: number; transform: Transform3D }
+>();
+function effectiveTransformCached(layer: Layer3D, sceneFrame: number, fps: Doc3D["fps"]): Transform3D {
+  const cached = EFFECTIVE_TRANSFORMS.get(layer);
+  if (
+    cached !== undefined &&
+    cached.sceneFrame === sceneFrame &&
+    cached.fpsNum === fps.num &&
+    cached.fpsDen === fps.den
+  ) {
+    return cached.transform;
+  }
+  const transform = effectiveTransform(layer, sceneFrame, fps);
+  EFFECTIVE_TRANSFORMS.set(layer, { sceneFrame, fpsNum: fps.num, fpsDen: fps.den, transform });
+  return transform;
+}
+
+/**
+ * The shot the scene sections describe, AS PAINTED at the playhead.
+ *
+ * `useSelectedLayers`'s twin one level up, for the same reason and against the
+ * same failure: `routeSceneEdit` runs the SAME `routeTrackedEdit`, so a scene
+ * constant is pinned the moment a track exists on it, and the two sections that
+ * read `doc.scenesById[sceneId]` directly (the background well and the 27
+ * keyframable post-effect params) would show it forever.
+ *
+ * The frame is `containerFrame`'s and NOT `useInspectorFrame`'s: that hook
+ * substitutes the DEFINITION and its own clock while one is open, and a shot is
+ * not a definition — asking it for a scene would hand back `undefined` and blank
+ * the section. Display only, exactly as above.
+ */
+export function useInspectorScene(): Scene3D | null {
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const frame = useCoalescedFrame();
+  if (doc === null || sceneId === null) return null;
   const scene = doc.scenesById[sceneId];
-  if (scene === undefined) return [];
-  return selection.map((id) => scene.layersById[id]).filter((l): l is Layer3D => l !== undefined);
+  if (scene === undefined) return null;
+  return resolveSceneTracksAt(scene, containerFrame(doc, sceneId, frame), doc.fps);
 }
 
 export interface SelectionValue<T> {
@@ -160,17 +362,54 @@ export interface SelectionValue<T> {
  * Read one property across the selection, from the layer AS PAINTED.
  *
  * `read` is handed the EFFECTIVE transform for transform properties and the
- * layer itself for paint ones, because paint has no block deltas at all in v1 —
- * so paint reads and writes are both base and cannot disagree.
+ * layer itself for paint ones.
+ *
+ * ── `read` MUST RETURN A SCALAR ─────────────────────────────────────────
+ *
+ * A number, a string, a boolean, null or undefined. Members are compared with
+ * `Object.is`, so an OBJECT read is mixed BY IDENTITY: `l => l.paint.shadows[0]`
+ * reports `mixed` for every multi-selection, including one where all the shadows
+ * are identical, and the row shows "Mixed" over values the author can see agree.
+ * Read the scalar the row displays — `l => l.paint.shadows?.[0]?.color`, one
+ * hook per field.
+ *
+ * A deep equal here is NOT the fix, for the reason the 2D lane's twin states:
+ * it would need a key-order-independent equality, which is a second and quieter
+ * definition of "the same value" living in a module with no business owning one.
+ *
+ * The rule cannot be stated in the type system over an arbitrary `T`, so a
+ * violation is REPORTED instead: a permanently wrong "Mixed" that says nothing
+ * is exactly the silent readout this lane keeps removing.
  */
 export function useSelectionValue<T>(read: (layer: Layer3D, effective: Transform3D) => T): SelectionValue<T> {
   const layers = useSelectedLayers();
   const { sceneFrame } = useInspectorFrame();
   const doc = useShotEditor((s) => s.doc);
   if (layers.length === 0 || doc === null) return { value: undefined, mixed: false };
-  const values = layers.map((l) => read(l, effectiveTransform(l, sceneFrame, doc.fps)));
+  const values = layers.map((l) => read(l, effectiveTransformCached(l, sceneFrame, doc.fps)));
   const first = values[0]!;
-  return { value: first, mixed: values.some((v) => !Object.is(v, first)) };
+  const mixed = values.some((v) => !Object.is(v, first));
+  // Only in the mixed branch: a scalar read costs one `typeof` on a value that
+  // already disagreed, and an agreeing selection costs nothing at all.
+  if (mixed) reportObjectRead(first);
+  return { value: first, mixed };
+}
+
+/** Shapes already reported, so a wrong read is loud ONCE rather than sixty
+ *  times a second. This runs inside render, and the inspector re-renders on
+ *  every coalesced frame while the playhead moves. Keyed on the value's own
+ *  keys, so two different broken reads each get their own line. */
+const OBJECT_READS = new Set<string>();
+
+function reportObjectRead(value: unknown): void {
+  if (value === null || typeof value !== "object") return;
+  const shape = Object.keys(value).join(",");
+  if (OBJECT_READS.has(shape)) return;
+  OBJECT_READS.add(shape);
+  console.error(
+    `[shot inspector] useSelectionValue read an OBJECT ({${shape}}), so "Mixed" is decided by ` +
+      `identity and is true for every multi-selection. Read the scalar the row displays instead.`,
+  );
 }
 
 /**
@@ -180,44 +419,129 @@ export function useSelectionValue<T>(read: (layer: Layer3D, effective: Transform
  * that way — so a fan-out cannot depend on the order the author happened to
  * click in, and an id cannot be visited twice.
  */
-export function useSelectionWrite(): (
-  build: (layer: Layer3D) => Layer3D,
-  opts?: { includeLocked?: boolean },
-) => void {
+export function useSelectionWrite(): (build: (layer: Layer3D) => Layer3D) => void {
   const store = useStore();
   return useCallback(
-    (build, opts) => {
+    (build) => {
       // LIVE at the commit, like the frame in useTransformWrite: a
       // render-captured sceneId paired with a live frame would write into
-      // last render's scene when the commit lands right on a crossing.
-      const sceneId = store.getState().sceneId;
-      if (sceneId === null) return;
-      const ids = store.getState().selection;
-      if (ids.length === 0) return;
-      store.edit((doc) => {
-        const scene = doc.scenesById[sceneId];
-        if (scene === undefined) return doc;
-        const layersById = { ...scene.layersById };
-        let changed = false;
-        for (const id of ids) {
-          const layer = layersById[id];
-          // A locked layer is skipped — that is what locked MEANS. The one
-          // exception is the lock toggle itself, or a lock would be one-way.
-          if (layer === undefined || (layer.locked === true && opts?.includeLocked !== true)) continue;
-          const next = build(layer);
-          if (next === layer) continue;
-          layersById[id] = next;
-          changed = true;
-        }
-        return changed
-          ? { ...doc, scenesById: { ...doc.scenesById, [sceneId]: { ...scene, layersById } } }
-          : doc;
+      // last render's scene when the commit lands right on a crossing. The
+      // CONTAINER rule: a definition while one is open.
+      const s = store.getState();
+      const container = s.editingDef ?? s.sceneId;
+      if (container === null || s.selection.length === 0 || s.doc === null) return;
+      const at = containerFrame(s.doc, container, authoringFrame(s));
+      let refusal: string | null = null;
+      const ran = store.edit((doc) => {
+        const out = writeSelection(doc, container, s.selection, build, at);
+        refusal = out.refusal;
+        return out.doc;
       });
+      if (ran && refusal !== null) store.reportError(refusal);
     },
     [store],
   );
 }
 
+/**
+ * `writeSelection`'s twin with the SHOT as the subject: build the next scene,
+ * and let `routeSceneEdit` turn the diff into a keyframe on any path the shot
+ * animates (P5).
+ *
+ * Exported because the two scene sections each own a pure patch function
+ * (`patchScene`, `patchEffect`) that both their typed and their drag path
+ * already run, and this wraps exactly those — so the background well and fifteen
+ * effect fields become keyframe-aware without either section learning what a
+ * track is. Same rule as the layer half, one level up.
+ *
+ * The FRAME is read live by the caller, never captured at render, for the reason
+ * `useSelectionScrub` reads it live: a drag held across a shot boundary would
+ * otherwise write keys at a frame the playhead has left.
+ *
+ * IDENTITY WHEN NOTHING CHANGED, so `edit` records no history entry and a drag
+ * that ends where it started commits nothing.
+ */
+export function writeScene(
+  doc: Doc3D,
+  sceneId: string,
+  build: (scene: Scene3D) => Scene3D,
+  sceneFrame: number,
+): Doc3D {
+  const scene = doc.scenesById[sceneId];
+  if (scene === undefined) return doc;
+  // Built from the shot as shown, for `writeSelection`'s reason.
+  const shown = sceneAsShown(scene, sceneFrame, doc.fps);
+  const next = routeSceneEdit(scene, build(shown), sceneFrame, keyframeMinter(doc), shown);
+  if (next === scene) return doc;
+  return { ...doc, scenesById: { ...doc.scenesById, [sceneId]: next } };
+}
+
+/**
+ * A PANEL DRAG as ONE undo entry: the store's scrub trio wearing the shape the
+ * shared widgets ask for (`ScrubHandlers`, ui/TextField.ts).
+ *
+ * `write` is PURE, `(doc, raw) => doc`, and it MUST RE-READ its subject from
+ * the doc it is HANDED. Every capture re-derives from the gesture's BASE
+ * (store.ts's `scrubCapture`), so a move passes the ABSOLUTE value the author is
+ * pointing at and never a delta from the previous move. A builder that instead
+ * closed over a value read at RENDER time re-applies the whole drag on top of
+ * itself sixty times a second, and the only symptom is a control that runs away
+ * from the cursor.
+ *
+ * NO ERROR IS RETURNED, unlike the 2D lane's `DocWrite`. This chrome has one
+ * error strip and the store owns it: `beginScrub` puts its own refusal there
+ * when another lane holds the history (a stage drag, a wheel dolly under
+ * follow), and the two later verbs no-op on a refused scrub, so a widget may
+ * drive all three blind, which is exactly what `ColorPicker` does.
+ */
+export function useScrub(write: (doc: Doc3D, raw: unknown) => Doc3D): ScrubHandlers {
+  const store = useStore();
+  // Deliberately not memoized. Every call site passes an inline builder, so a
+  // dependency on it would rebuild this object every render anyway, and the
+  // widgets read these handlers off their props at POINTER time, which is what
+  // keeps the newest builder the one a move runs.
+  return {
+    start: () => store.beginScrub(),
+    move: (raw) => store.scrubCapture((doc) => write(doc, raw)),
+    end: (commit) => store.endScrub(commit),
+  };
+}
+
+/**
+ * The same bracket, fanned out over the selection: `useSelectionWrite`'s builder
+ * with the widget's raw value beside it, through the same `writeSelection`.
+ *
+ * The subjects are read LIVE per capture rather than at render, for the reason
+ * the commit path reads them live: a fan-out over the selection a panel last
+ * RENDERED against would write into layers the author has since left.
+ */
+export function useSelectionScrub(build: (layer: Layer3D, raw: unknown) => Layer3D): ScrubHandlers {
+  const store = useStore();
+  // The last capture's lock refusal, named once at the release rather than per
+  // pointer event.
+  const refusal = useRef<string | null>(null);
+  const scrub = useScrub((doc, raw) => {
+    const s = store.getState();
+    const container = s.editingDef ?? s.sceneId;
+    if (container === null) return doc;
+    // The frame LIVE at the capture, and against the document being written
+    // rather than the store's — a scrub re-derives from its base, so the shot
+    // starts here are the base's.
+    const at = containerFrame(doc, container, authoringFrame(s));
+    const out = writeSelection(doc, container, s.selection, (layer) => build(layer, raw), at);
+    refusal.current = out.refusal;
+    return out.doc;
+  });
+  return {
+    ...scrub,
+    end: (commit) => {
+      scrub.end(commit);
+      if (commit && refusal.current !== null) store.reportError(refusal.current);
+      refusal.current = null;
+    },
+  };
+}
+
 /**
  * Type a transform field across the selection.
  *
@@ -227,42 +551,10 @@ export function useSelectionWrite(): (
  */
 export function useTransformWrite(): (field: TransformField, value: number) => void {
   const store = useStore();
-  const write = useSelectionWrite();
   return useCallback(
     (field, value) => {
-      // LIVE state at the keystroke, never the display hook's coalesced frame:
-      // the compensation arithmetic must target the frame actually painted, or
-      // the typed value lands up to 100ms of playhead away from where it reads
-      // back.
-      const s = store.getState();
-      const doc = s.doc;
-      if (doc === null || s.sceneId === null) return;
-      const sceneId = s.sceneId;
-      const sceneFrame = sceneLocalFrame(doc, sceneId, s.frame);
-      let refusal: string | null = null;
-      // ANIMATE ON: the typed value becomes a During block ending at the
-      // playhead — the same fork a stage drag takes (store.ts) and the camera
-      // takes (writeFraming), because the inspector and a drag are one
-      // operation with different input devices. OFF: the base write below.
-      if (s.animateMode) {
-        store.edit((base) => {
-          const out = animateFieldEdit(base, sceneId, s.selection, field, value, sceneFrame, base.fps);
-          refusal = out.refusals[0] ?? null;
-          return out.doc;
-        });
-        store.reportError(refusal);
-        return;
-      }
-      write((layer) => {
-        const out = setEffectiveField(layer, field, value, sceneFrame, doc.fps);
-        if (out.refusal !== null) {
-          refusal ??= out.refusal;
-          return layer;
-        }
-        return out.transform === layer.transform ? layer : { ...layer, transform: out.transform };
-      });
-      store.reportError(refusal);
+      store.reportError(commitTransformField(store, field, value, store.getState().selection));
     },
-    [store, write],
+    [store],
   );
 }