@dailies-studio/shot-editor 0.1.0

package/src/panels/inspector/scene/EffectsSection.tsx

@@ -0,0 +1,123 @@
+// The cinematic post stack, one toggle per effect.
+//
+// ABSENT MEANS OFF — there is no `enabled` flag anywhere in `SceneEffects`,
+// because two ways to say "off" is one way to disagree. So a toggle here
+// DELETES the key rather than setting a boolean, and the shader chain rebuilds
+// from `postSignature`, which is derived from exactly which keys exist.
+import type { ReactNode } from "react";
+import { InspectorRow, InspectorSection, NumberField, Toggle } from "@dailies-studio/ui";
+import type { SceneEffects } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../../state/context.js";
+
+/** What each effect looks like when first switched on. Values that read as the
+ *  effect rather than as nothing — a bloom at strength 0 is a toggle that
+ *  appears not to work, and the author blames the renderer. */
+const DEFAULTS = {
+  dof: { fStop: 2.8, bokehScale: 2, quality: "mip" },
+  bloom: { strength: 0.6, radius: 0.5, threshold: 0.7 },
+  vignette: { amount: 0.5, radius: 0.55, softness: 0.4 },
+  grain: { amount: 0.08, size: 1.5 },
+  colorSplit: { strength: 1.5, scale: 1.05 },
+  ghost: { amount: 0.25, offset: [0.004, 0.002], count: 3 },
+  grade: { slope: [1, 1, 1], offset: [0, 0, 0], power: [1, 1, 1], saturation: 1 },
+  edgeFade: { size: 0.12, softness: 0.08 },
+  motionBlur: { shutterDeg: 180, samples: 8 },
+} as const satisfies Record<keyof SceneEffects, unknown>;
+
+type EffectKey = keyof typeof DEFAULTS;
+
+export function EffectsSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  if (doc === null || sceneId === null) return null;
+  const effects = doc.scenesById[sceneId]?.effects;
+  if (effects === undefined) return null;
+
+  // Block body: `edit` now answers whether it ran, and this caller has no use
+  // for the answer — see SceneSection.
+  const patch = (next: SceneEffects): void => {
+    store.edit((d) => ({
+      ...d,
+      scenesById: { ...d.scenesById, [sceneId]: { ...d.scenesById[sceneId]!, effects: next } },
+    }));
+  };
+
+  const toggle = (key: EffectKey, on: boolean): void => {
+    const next: Record<string, unknown> = { ...effects };
+    if (on) next[key] = DEFAULTS[key];
+    else delete next[key];
+    patch(next as SceneEffects);
+  };
+
+  const set = (key: EffectKey, field: string, value: number): void => {
+    const current = (effects as Record<string, Record<string, unknown>>)[key] ?? DEFAULTS[key];
+    patch({ ...effects, [key]: { ...current, [field]: value } } as SceneEffects);
+  };
+
+  return (
+    <InspectorSection title="Effects" persistKey="shot:effects">
+      <Row label="Depth of field" on={effects.dof !== undefined} onToggle={(v) => toggle("dof", v)}>
+        <NumberField value={effects.dof?.fStop ?? 2.8} label="f/" ariaLabel="Aperture" min={0.7} max={32} step={0.1} onCommit={(v) => set("dof", "fStop", v)} />
+        <NumberField value={effects.dof?.bokehScale ?? 2} label="Amount" ariaLabel="Bokeh scale" min={0} max={20} step={0.5} onCommit={(v) => set("dof", "bokehScale", v)} />
+      </Row>
+      <Row label="Bloom" on={effects.bloom !== undefined} onToggle={(v) => toggle("bloom", v)}>
+        <NumberField value={effects.bloom?.strength ?? 0.6} label="Amount" ariaLabel="Bloom strength" min={0} max={5} step={0.05} onCommit={(v) => set("bloom", "strength", v)} />
+        <NumberField value={effects.bloom?.threshold ?? 0.7} label="Cut" ariaLabel="Bloom threshold" min={0} max={2} step={0.05} onCommit={(v) => set("bloom", "threshold", v)} />
+      </Row>
+      <Row label="Vignette" on={effects.vignette !== undefined} onToggle={(v) => toggle("vignette", v)}>
+        <NumberField value={effects.vignette?.amount ?? 0.5} label="Amount" ariaLabel="Vignette amount" min={0} max={1} step={0.05} onCommit={(v) => set("vignette", "amount", v)} />
+        <NumberField value={effects.vignette?.radius ?? 0.55} label="Size" ariaLabel="Vignette radius" min={0} max={1.5} step={0.05} onCommit={(v) => set("vignette", "radius", v)} />
+      </Row>
+      <Row label="Grain" on={effects.grain !== undefined} onToggle={(v) => toggle("grain", v)}>
+        <NumberField value={effects.grain?.amount ?? 0.08} label="Amount" ariaLabel="Grain amount" min={0} max={1} step={0.01} onCommit={(v) => set("grain", "amount", v)} />
+        <NumberField value={effects.grain?.size ?? 1.5} label="Size" ariaLabel="Grain size" min={1} max={16} step={0.5} onCommit={(v) => set("grain", "size", v)} />
+      </Row>
+      <Row label="Color split" on={effects.colorSplit !== undefined} onToggle={(v) => toggle("colorSplit", v)}>
+        <NumberField value={effects.colorSplit?.strength ?? 1.5} label="Amount" ariaLabel="Colour split strength" min={0} max={20} step={0.1} onCommit={(v) => set("colorSplit", "strength", v)} />
+      </Row>
+      <Row label="Ghost" on={effects.ghost !== undefined} onToggle={(v) => toggle("ghost", v)}>
+        <NumberField value={effects.ghost?.amount ?? 0.25} label="Amount" ariaLabel="Ghost amount" min={0} max={1} step={0.05} onCommit={(v) => set("ghost", "amount", v)} />
+        {/* A LOOP BOUND, not a uniform — changing it recompiles the chain, which
+            is exactly why `postSignature` carries it and the other params do
+            not. */}
+        <NumberField value={effects.ghost?.count ?? 3} label="Copies" ariaLabel="Ghost count" min={1} max={8} step={1} onCommit={(v) => set("ghost", "count", v)} />
+      </Row>
+      <Row label="Edge fade" on={effects.edgeFade !== undefined} onToggle={(v) => toggle("edgeFade", v)}>
+        <NumberField value={effects.edgeFade?.size ?? 0.12} label="Size" ariaLabel="Edge fade size" min={0} max={0.5} step={0.01} onCommit={(v) => set("edgeFade", "size", v)} />
+      </Row>
+      <Row label="Grade" on={effects.grade !== undefined} onToggle={(v) => toggle("grade", v)}>
+        <NumberField value={effects.grade?.saturation ?? 1} label="Sat" ariaLabel="Saturation" min={0} max={3} step={0.05} onCommit={(v) => set("grade", "saturation", v)} />
+      </Row>
+      <Row label="Motion blur" on={effects.motionBlur !== undefined} onToggle={(v) => toggle("motionBlur", v)}>
+        {/* NOT A SHADER PASS. This feeds the export layer's sub-frame
+            accumulation, which is the only formulation compatible with
+            out-of-order rendering — see SceneEffects in types.ts. It therefore
+            shows in an EXPORT and not in the preview. */}
+        <NumberField value={effects.motionBlur?.shutterDeg ?? 180} label="Shutter" ariaLabel="Shutter angle" unit="deg" min={0} max={360} step={10} onCommit={(v) => set("motionBlur", "shutterDeg", v)} />
+        <NumberField value={effects.motionBlur?.samples ?? 8} label="Samples" ariaLabel="Motion blur samples" min={2} max={32} step={1} onCommit={(v) => set("motionBlur", "samples", v)} />
+      </Row>
+    </InspectorSection>
+  );
+}
+
+function Row({
+  label,
+  on,
+  onToggle,
+  children,
+}: {
+  label: string;
+  on: boolean;
+  onToggle(on: boolean): void;
+  children: ReactNode;
+}) {
+  return (
+    <div className="effect-row" data-effect={label}>
+      <InspectorRow label={label}>
+        <Toggle checked={on} ariaLabel={label} onChange={onToggle} />
+      </InspectorRow>
+      {on ? <div className="effect-params">{children}</div> : null}
+    </div>
+  );
+}

package/src/panels/inspector/scene/SceneSection.tsx

@@ -0,0 +1,71 @@
+// The scene's own properties, shown when nothing is selected. The subject
+// switch is the SELECTION, not a tab: a layer inspector and a scene inspector
+// are the same panel looking at whatever the author last clicked.
+import { ColorPicker, InspectorRow, InspectorSection, NumberField, TextField } from "@dailies-studio/ui";
+import type { Scene3D } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { NO_SCRUB } from "../useDocWrite.js";
+
+export function SceneSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  if (doc === null || sceneId === null) return null;
+  const scene = doc.scenesById[sceneId];
+  if (scene === undefined) return null;
+
+  // A block body, not a concise one: `edit` reports whether it RAN (a drag
+  // holds the history open and refuses), and this caller has nothing to do with
+  // that answer — returning it out of a `void` handler is the type error that
+  // says so.
+  const patch = (next: Partial<Scene3D>): void => {
+    store.edit((d) => ({
+      ...d,
+      scenesById: { ...d.scenesById, [sceneId]: { ...d.scenesById[sceneId]!, ...next } },
+    }));
+  };
+
+  return (
+    <InspectorSection title="Shot" persistKey="shot:scene" collapsible={false}>
+      <InspectorRow label="Name">
+        <TextField value={scene.name} ariaLabel="Shot name" onCommit={(name) => patch({ name })} />
+      </InspectorRow>
+      <InspectorRow>
+        <NumberField
+          value={scene.durationFrames}
+          label="Frames"
+          ariaLabel="Shot duration"
+          min={1}
+          step={1}
+          onCommit={(durationFrames) => store.trimScene(sceneId, durationFrames)}
+        />
+      </InspectorRow>
+      <InspectorRow>
+        {/* THE ONLY CONTROL ON PARALLAX STRENGTH. A wide fov puts the camera
+            close, so a depth offset changes scale a lot; a long lens puts it far
+            and the same offset barely registers (resolve.ts's planeDistance). */}
+        <NumberField
+          value={scene.fovDeg}
+          label="Lens"
+          ariaLabel="Field of view"
+          unit="deg"
+          min={5}
+          max={120}
+          step={1}
+          onCommit={(fovDeg) => patch({ fovDeg })}
+        />
+      </InspectorRow>
+      <InspectorRow label="Background">
+        {/* A scene is OPAQUE by contract (types.ts), so there is no alpha here
+            and none is offered — the renderer clears with alpha 1, and a
+            transparent background would be a promise the export cannot keep. */}
+        <ColorPicker
+          value={scene.background.type === "solid" ? scene.background.color : "#0b0b0d"}
+          ariaLabel="Background colour"
+          scrub={NO_SCRUB}
+          commit={(color) => patch({ background: { type: "solid", color } })}
+        />
+      </InspectorRow>
+    </InspectorSection>
+  );
+}

package/src/panels/inspector/scene/TransitionSection.tsx

@@ -0,0 +1,136 @@
+// How this shot hands over to the next one.
+//
+// A transition is stored on the OUTGOING shot — the one selected here — and
+// plays over the opening frames of the one after it. That is why the section is
+// titled "Into next shot" and why the last shot's controls are inert: there is
+// nothing after it to blend into. It stays EDITABLE there rather than hidden,
+// because reordering can make any shot last and then not last again, and a
+// setting that vanishes when you drag a bar looks like data loss.
+//
+// The preset list comes from the ROOT of @dailies-studio/transitions, never from
+// its ./gl entry: that entry's first import is `three/tsl`, and the chrome
+// bundle must not carry a shader graph layer to draw a dropdown. The root's
+// `glPresetSpecs` is the same data gl.ts builds against, asserted in lockstep
+// at import.
+import {
+  InspectorRow,
+  InspectorSection,
+  NumberField,
+} from "@dailies-studio/ui";
+import { glPresetSpecs, resolveGlPresetSpec } from "@dailies-studio/transitions";
+import { MIN_TRANSITION_FRAMES } from "@dailies-studio/shot/doc";
+import type { Value } from "@dailies-studio/engine";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { ParamRow } from "../ParamRow.js";
+
+/** "no transition", as a select value. Not a preset id, and cannot be one. */
+const CUT = "";
+
+/** What a transition looks like when first chosen: a third of a second at 30fps,
+ *  which reads as a transition rather than as a glitch. */
+const DEFAULT_FRAMES = 10;
+
+export function TransitionSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  if (doc === null || sceneId === null) return null;
+  const scene = doc.scenesById[sceneId];
+  if (scene === undefined) return null;
+
+  const transition = scene.transition;
+  const spec = transition === undefined ? undefined : resolveGlPresetSpec(transition.kind);
+  const isLast = doc.scenes[doc.scenes.length - 1] === sceneId;
+  const next = isLast ? null : (doc.scenesById[doc.scenes[doc.scenes.indexOf(sceneId) + 1]!] ?? null);
+
+  const setKind = (kind: string): void => {
+    if (kind === CUT) {
+      store.setSceneTransition(sceneId, null);
+      return;
+    }
+    // Params are PRESET-SCOPED, so switching preset starts from that preset's
+    // own defaults rather than carrying the previous one's names across — the
+    // same reasoning as setBlockPreset.
+    store.setSceneTransition(sceneId, {
+      kind,
+      durationFrames: transition?.durationFrames ?? DEFAULT_FRAMES,
+    });
+  };
+
+  const setParam = (name: string, value: Value): void => {
+    if (transition === undefined) return;
+    store.setSceneTransition(sceneId, {
+      ...transition,
+      params: { ...transition.params, [name]: value },
+    });
+  };
+
+  return (
+    <InspectorSection title="Into next shot" persistKey="shot:transition">
+      <InspectorRow label="Transition">
+        <select
+          className="select"
+          aria-label="Transition preset"
+          value={transition?.kind ?? CUT}
+          onChange={(e) => setKind(e.target.value)}
+        >
+          <option value={CUT}>Cut</option>
+          {Object.values(glPresetSpecs).map((p) => (
+            <option key={p.id} value={p.id}>
+              {p.label}
+            </option>
+          ))}
+          {/* A document may name a preset this build does not have — it renders
+              as a cut, and the picker says so instead of silently showing
+              "Cut" and rewriting it on the next edit. */}
+          {transition !== undefined && spec === undefined ? (
+            <option value={transition.kind}>{transition.kind} (unknown)</option>
+          ) : null}
+        </select>
+      </InspectorRow>
+
+      {transition !== undefined ? (
+        <>
+          <InspectorRow label="Frames">
+            <NumberField
+              value={transition.durationFrames}
+              ariaLabel="Transition frames"
+              min={MIN_TRANSITION_FRAMES}
+              step={1}
+              onCommit={(v) =>
+                store.setSceneTransition(sceneId, {
+                  ...transition,
+                  durationFrames: Math.max(MIN_TRANSITION_FRAMES, Math.round(v)),
+                })
+              }
+            />
+          </InspectorRow>
+          {/* The stored number is the AUTHOR's, and the resolver clamps it to
+              whatever the next shot can hold — so trimming that shot short and
+              back again does not quietly rewrite what was typed. Said here
+              because the discrepancy is otherwise invisible. */}
+          {next !== null && transition.durationFrames > next.durationFrames ? (
+            <p className="inspector-note">
+              Longer than {next.name} ({next.durationFrames}f) — it plays over
+              that whole shot.
+            </p>
+          ) : null}
+          {isLast ? (
+            <p className="inspector-note">
+              This is the last shot, so nothing plays. Kept for when one follows
+              it.
+            </p>
+          ) : null}
+          {spec?.params.map((p) => (
+            <ParamRow
+              key={p.name}
+              spec={p}
+              value={transition.params?.[p.name] ?? p.default}
+              onCommit={(v) => setParam(p.name, v)}
+            />
+          ))}
+        </>
+      ) : null}
+    </InspectorSection>
+  );
+}

package/src/panels/inspector/useDocWrite.ts

@@ -0,0 +1,268 @@
+// The inspector's write and read seams.
+//
+// ── THE ASYMMETRY, WHICH IS THE WHOLE FILE ──────────────────────────────
+//
+// READOUTS come from the layer AS PAINTED at the playhead. WRITES derive from
+// the base, compensated so the rendered value lands on what the author typed.
+//
+// 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.
+//
+//   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.
+//
+// ── 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";
+import { useShotEditor, useStore } from "../../state/context.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: () => {} };
+
+/** THE one document-edit seam. Every inspector commit is a transaction, so it
+ *  is one undo entry however many layers it touched. */
+export function useDocWrite(): (write: (doc: Doc3D) => Doc3D) => void {
+  const store = useStore();
+  return useCallback((write) => store.edit(write), [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);
+}
+
+/** 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
+ *  canvas; 30Hz numbers are unreadable AND cost eleven sections a re-render
+ *  and an `effectiveTransform` per selected layer, each. */
+const INSPECTOR_FRAME_MS = 100;
+
+/**
+ * The playhead as the inspector SHOWS it, coalesced.
+ *
+ * Two high-rate sources exist and `playing` only names one of them: scrubbing
+ * drives `seek()` at pointer-event rate with `playing === false` (the ruler,
+ * the transport slider, and any future source — none of which carry drag
+ * brackets). So the gate is on the RATE, not on a flag: held entirely during
+ * playback, throttled to ~10Hz otherwise, and always flushing the final frame
+ * once the stream quiets so the panel never rests on a stale number.
+ *
+ * Display only. Commits read the live frame at the keystroke (see
+ * `useTransformWrite`) — a write compensated against a coalesced frame would
+ * land the typed value at a playhead the render already left.
+ */
+/** Exported for every chrome READOUT that resolves document state at the
+ *  playhead (the inspector fields, the timeline's channel values): held while
+ *  playing, ~10 Hz while scrubbing, leading edge on a lone seek. A readout
+ *  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;
+      }
+      // 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;
+}
+
+/** 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. */
+export function useInspectorFrame(): { sceneId: string | null; sceneFrame: number } {
+  const sceneId = useShotEditor((s) => s.sceneId);
+  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) };
+}
+
+/** 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. */
+export function useSelectedLayers(): Layer3D[] {
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const selection = useShotEditor((s) => s.selection);
+  if (doc === null || sceneId === null) return [];
+  const scene = doc.scenesById[sceneId];
+  if (scene === undefined) return [];
+  return selection.map((id) => scene.layersById[id]).filter((l): l is Layer3D => l !== undefined);
+}
+
+export interface SelectionValue<T> {
+  /** The common value, or the FIRST layer's when they differ. */
+  value: T | undefined;
+  /** True when the selection does not agree. The widgets show "Mixed" and
+   *  apply a typed value to the whole selection. */
+  mixed: boolean;
+}
+
+/**
+ * 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.
+ */
+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 first = values[0]!;
+  return { value: first, mixed: values.some((v) => !Object.is(v, first)) };
+}
+
+/**
+ * Write one property to EVERY selected layer, as ONE transaction.
+ *
+ * In document order and deduped, because `select` already keeps the selection
+ * 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 {
+  const store = useStore();
+  return useCallback(
+    (build, opts) => {
+      // 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;
+      });
+    },
+    [store],
+  );
+}
+
+/**
+ * Type a transform field across the selection.
+ *
+ * The refusal is REPORTED, not swallowed: a field that silently did nothing to
+ * one of four selected layers is the failure the whole two-truths rule exists
+ * to make impossible.
+ */
+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, write],
+  );
+}