@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/TimeSection.tsx

@@ -0,0 +1,866 @@
+// WHEN A LAYER IS ON SCREEN, AND — FOR A RECORDING — WHICH PART OF IT PLAYS.
+//
+// ── WHY THIS SECTION HAD TO EXIST ───────────────────────────────────────
+//
+// A lifetime was reachable only by dragging a bar in the dock. That is the
+// right gesture and it is the only one, so "start this at frame 90" was a drag
+// against a ruler, unrepeatable across two layers and impossible at a zoom
+// where a frame is a third of a pixel. The clip fields were worse: `sourceIn`,
+// `sourceOut` and the natural length of a recording had no field ANYWHERE in
+// the chrome, and the three things that can end a clip were indistinguishable
+// by looking at it.
+//
+// ── ITS ASYMMETRY IS `useDocWrite`'s, AND BOTH HALVES ARE LIVE HERE ─────
+//
+// Read that file's header first. Readouts come from the layer AS PAINTED at the
+// playhead (`useSelectedLayers`, which runs `resolveTracksAt`), and writes are
+// compensated so the rendered value lands on what was typed. This section is
+// where the two halves are visibly different work rather than the same read
+// twice, because it has one field of each kind:
+//
+//   THE GAIN IS TRACKED. `video.sound.gain` is a keyframable path (tracks.ts),
+//     so its base is DEAD the moment a track exists — `routeTrackedEdit` writes
+//     the old base back. A row reading the base would show a number the mixer
+//     stopped using, and typing the number the field displayed would diff
+//     against itself and write nothing at all. So it reads through the resolved
+//     layer and writes through `useSelectionWrite`, which turns the diff into a
+//     keyframe at the playhead.
+//   EVERY TIME FIELD IS NOT. A lifetime has no track, so there is
+//     nothing to compensate — but the value still must not be read at RENDER
+//     and written back later. Each write below re-reads its subject from the
+//     document `useDocWrite` hands it and computes the delta THERE, so a commit
+//     that lands after an undo, a scene crossing or another panel's edit is
+//     measured against the document it is actually writing into.
+//
+// ── AND EVERY TIME EDIT GOES THROUGH AN OP THAT ALREADY EXISTS ──────────
+//
+// `writeLifespan` (panels/timeline/model.ts) is what the dock's bars drag
+// through. It forks a VIDEO layer in a scene onto `trimLayer`/`moveLayers`,
+// which bound an edge by the FOOTAGE as well as by the scene, and leaves a
+// plain layer on the clamped lifetime write. Typing a number and dragging a bar
+// are one operation with different input devices — the rule `useDocWrite`'s
+// header states for the canvas — so this section spends a subtraction to reach
+// the delta API rather than owning a second set of clamps that would disagree
+// with the bars on the first edge case.
+//
+// ── ONE LAYER, DECLARED ─────────────────────────────────────────────────
+//
+// A lifetime is a property of one layer and every clip op takes one `layerId`.
+// A fan-out would need `moveLayers`' all-or-nothing posture for the edges and
+// has no meaning at all for "source in", so this section renders for a single
+// selection and withholds itself otherwise — the rule `component`, `instance`,
+// `triggers` and `material` already follow (layout.ts).
+//
+// CEILING, stated: a NEGATIVE source in is readable here and not typeable. It
+// means the window opens before the recording does, which is what `splitScene`
+// leaves behind for a clip already playing at a cut; `setVideoSource` clamps a
+// requested source frame to the recording, so the row shows the lead and
+// refuses to invent one. Slipping the clip in the dock is what moves it.
+//
+// ── EVERY FIELD DRAGS LIVE ──────────────────────────────────────────────
+//
+// Each number's drag runs the SAME op its typed value does, as a scrub: one
+// undo entry, every capture re-derived from the gesture's base (so an edge's
+// delta is measured against the document the drag started from), and the
+// store's lock rule applied to each capture. A capture an op refuses (a retime
+// the sound forbids, a fade longer than the sound) holds the last value the
+// same gesture landed, and the refusal is said once, at the release.
+import { useRef, useState } from "react";
+import {
+  InspectorRow,
+  InspectorSection,
+  NumberField,
+  PropertyGrid,
+  SegmentedControl,
+  Toggle,
+  useLocked,
+  wordOptions,
+} from "@dailies-studio/ui";
+import type { ScrubHandlers } from "@dailies-studio/ui";
+import {
+  MAX_AUDIO_GAIN,
+  MEDIA_LOOPS,
+  containerDurationOf,
+  defDurationFrames,
+  homeOf,
+  retimeVideo,
+  retimeVideoRefusal,
+  setVideoSound,
+  setVideoSoundRefusal,
+  setVideoSource,
+  videoClipOf,
+} from "@dailies-studio/shot/doc";
+import type {
+  ComponentLayer3D,
+  Doc3D,
+  InstanceLayer3D,
+  Layer3D,
+  MediaLoop,
+  Scene3D,
+  VideoLayer3D,
+  VideoSound,
+} from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { framesToSeconds } from "@dailies-studio/engine";
+import { formatDuration, lifespanOf, timecode, writeLifespan } from "../timeline/model.js";
+import { KeyframeDot } from "./KeyframeDot.js";
+import {
+  MAX_GAIN_DB,
+  MIN_GAIN_DB,
+  closingCaption,
+  closingEdge,
+  dbToGain,
+  gainAsDb,
+  naturalOutFrame,
+} from "./timeModel.js";
+import { useDocWrite, useScrub, useSelectedLayers, useSelectionScrub, useSelectionWrite } from "./useDocWrite.js";
+
+/** The loops, as data, so a word renamed in the schema is a compile error here
+ *  rather than a segment that writes a value the runtime ignores. */
+const LOOP_OPTIONS = wordOptions(MEDIA_LOOPS);
+
+/** A placement's loop (schema v47): the same two words, plus Off, which is the
+ *  field's absence and what every older placement means. */
+const PLACEMENT_LOOP_OFF = "off";
+const PLACEMENT_LOOP_OPTIONS = [{ value: PLACEMENT_LOOP_OFF, label: "Off" }, ...LOOP_OPTIONS];
+
+export function TimeSection() {
+  const store = useStore();
+  const write = useDocWrite();
+  const layers = useSelectedLayers();
+  const doc = useShotEditor((s) => s.doc);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const editingDef = useShotEditor((s) => s.editingDef);
+
+  // ONE layer, by the rule in this file's header. `layers` is already the
+  // selection AS PAINTED and in document order, so the single case is the
+  // whole of it.
+  const layer = layers.length === 1 ? layers[0] : undefined;
+  if (doc === null || layer === undefined) return null;
+  // The CONTAINER, the store's own `layerContainer` rule: a definition while
+  // one is open, and the scene otherwise. `writeLifespan` takes either.
+  const container = editingDef ?? sceneId;
+  if (container === null) return null;
+  // The SCENE, and null inside a definition. Every clip op resolves its layer
+  // through `doc.scenesById`, so a `cmp_` container would have them refuse
+  // silently — the same fork `writeLifespan` takes for exactly this reason.
+  const scene: Scene3D | undefined = editingDef === null && sceneId !== null ? doc.scenesById[sceneId] : undefined;
+  const life = lifespanOf(layer, containerDurationOf(doc, container));
+
+  return (
+    <InspectorSection className="insp-object" title="Time" persistKey="shot:time">
+      {/* A plain pair, two boxes across the row. A lifetime has no track, so
+          neither box carries a diamond, and neither is narrower for it. */}
+      <PropertyGrid>
+        <LifetimeField
+          side="in"
+          container={container}
+          layerId={layer.id}
+          value={life.in}
+          title={`Scene frame this layer appears on: ${timecode(life.in, doc.fps)}`}
+          onWrite={write}
+        />
+        <LifetimeField
+          side="out"
+          container={container}
+          layerId={layer.id}
+          value={life.out}
+          title={`Scene frame this layer leaves on: ${timecode(life.out, doc.fps)}`}
+          onWrite={write}
+        />
+      </PropertyGrid>
+
+      {/* THE TIMECODE, as a readout and not a second pair of fields. Frames are
+          what a lifetime is stored in and what a keyframe is written in, so the
+          fields stay in frames; the clock is what an author reads a cut
+          against, and having both means never converting by hand. Drawn as a
+          read-only BOX in the numeral face, the field's shape with nothing to
+          type into, so it reads as a value of this layer rather than a note:
+          the house readout (`insp-readout`, widgets.css). */}
+      <InspectorRow label="Timecode" className="insp-readout">
+        <span className="insp-dim" data-testid="time-timecode">
+          {timecode(life.in, doc.fps)} → {timecode(life.out, doc.fps)}
+        </span>
+      </InspectorRow>
+
+      {/* READ-ONLY, because it is not a third fact. Duration is `out - in`, and
+          a field for it would be a second absolute writer for one of the two
+          edges: typing into it would have to pick an edge to move, silently. */}
+      <InspectorRow label="Duration" className="insp-readout">
+        <span className="insp-dim" data-testid="time-duration">
+          {formatDuration(framesToSeconds(life.out - life.in, doc.fps))}
+        </span>
+      </InspectorRow>
+
+      {layer.kind === "video" && scene !== undefined && sceneId !== null ? (
+        <ClipRows doc={doc} scene={scene} sceneId={sceneId} layer={layer} />
+      ) : null}
+
+      {layer.kind === "instance" || layer.kind === "component" ? <PlacementLoopRows doc={doc} layer={layer} /> : null}
+
+      {layer.kind === "video" && scene !== undefined && sceneId !== null && layer.video.sound !== undefined ? (
+        <SoundRows
+          doc={doc}
+          sceneId={sceneId}
+          layer={layer}
+          sound={layer.video.sound}
+          onRefusal={(message) => store.reportError(message)}
+        />
+      ) : null}
+    </InspectorSection>
+  );
+}
+
+/**
+ * One lifetime edge, typed or dragged.
+ *
+ * Both halves re-read their subject from the document they are handed and
+ * measure the delta there. See this file's header: the typed value is
+ * absolute, `writeLifespan` is a gesture API, and the subtraction must not be
+ * taken against a render-time reading. A drag's every capture starts from the
+ * gesture's base, so its delta never compounds.
+ */
+function LifetimeField(props: {
+  side: "in" | "out";
+  container: string;
+  layerId: string;
+  value: number;
+  title: string;
+  onWrite: (write: (doc: Doc3D) => Doc3D) => void;
+}) {
+  const { side, container, layerId } = props;
+  const edge = (base: Doc3D, to: number): Doc3D => {
+    const subject = homeOf(base, container)?.layersById[layerId];
+    if (subject === undefined) return base;
+    const now = lifespanOf(subject, containerDurationOf(base, container));
+    const delta = Math.round(to) - now[side];
+    return delta === 0 ? base : writeLifespan(base, container, layerId, side, delta);
+  };
+  const scrub = useScrub((doc, raw) => edge(doc, Number(raw)));
+  return (
+    <InspectorRow>
+      <NumberField
+        value={props.value}
+        label={side === "in" ? "In" : "Out"}
+        ariaLabel={side === "in" ? "Lifetime in" : "Lifetime out"}
+        unit="f"
+        min={0}
+        step={1}
+        title={props.title}
+        onCommit={(next) => props.onWrite((base) => edge(base, next))}
+        onScrubStart={scrub.start}
+        onScrub={scrub.move}
+        onScrubEnd={scrub.end}
+      />
+    </InspectorRow>
+  );
+}
+
+/**
+ * A drag over one of this section's REFUSING ops: `useScrub`'s bracket, with
+ * the op's refusal kept from the last capture and said ONCE, at the release,
+ * the way `useSelectionScrub` says a lock.
+ *
+ * A REFUSED CAPTURE HOLDS THE LAST VALUE THIS GESTURE LANDED. Every capture
+ * re-derives from the gesture's base, so a refused one that wrote the base
+ * threw the whole drag away: a fade dragged to 10 and on past what the sound
+ * allows went back to 0 at the release. It re-runs the op with the last value
+ * it accepted instead (the press value when it accepted none), so the field
+ * stops where the op stopped and the release lands that.
+ *
+ * `refused` hears the refusal and the value it refused, for a row that holds
+ * it on screen; `landed` hears a release whose last capture was accepted, so
+ * that row can let go of a refusal it was still holding.
+ */
+function useOpScrub(
+  write: (doc: Doc3D, value: number) => { doc: Doc3D; refusal: string | null },
+  on: { refused?: (why: string, value: number) => void; landed?: () => void } = {},
+): ScrubHandlers {
+  const store = useStore();
+  const gesture = useRef<{ refusal: string | null; value: number; landed: number | null } | null>(null);
+  const scrub = useScrub((doc, raw) => {
+    const value = Number(raw);
+    const out = write(doc, value);
+    const landed = out.refusal === null ? value : (gesture.current?.landed ?? null);
+    gesture.current = { refusal: out.refusal, value, landed };
+    return out.refusal === null || landed === null ? out.doc : write(doc, landed).doc;
+  });
+  return {
+    start: () => {
+      gesture.current = null;
+      scrub.start();
+    },
+    move: scrub.move,
+    end: (commit) => {
+      scrub.end(commit);
+      const last = gesture.current;
+      gesture.current = null;
+      if (!commit || last === null) return;
+      if (last.refusal === null) {
+        on.landed?.();
+        return;
+      }
+      store.reportError(last.refusal);
+      on.refused?.(last.refusal, last.value);
+    },
+  };
+}
+
+/**
+ * The clip half: which part of the recording this window selects, how fast it
+ * runs, what happens past its end, and which edge actually closes it.
+ *
+ * A child component rather than inline JSX because the video case needs its own
+ * hooks (the speed field keeps a draft while a refusal is on screen) and a hook
+ * cannot live behind the `kind === "video"` test above.
+ */
+function ClipRows(props: { doc: Doc3D; scene: Scene3D; sceneId: string; layer: VideoLayer3D }) {
+  const { doc, scene, sceneId, layer } = props;
+  const store = useStore();
+  const write = useDocWrite();
+  // Natural length is a plain button, so it reads a viewer's lock here.
+  const locked = useLocked();
+  const rate = layer.video.timeScale ?? 1;
+  const clip = videoClipOf(layer, scene.durationFrames, doc.fps, doc.assets[layer.video.asset]);
+  const close = closingEdge(clip, scene.durationFrames, rate);
+  const natural = naturalOutFrame(clip, layer.video.offsetFrames ?? 0, rate);
+
+  /** Both source edges through ONE op. `setVideoSource` is the only thing in
+   *  the repo that converts between the two rulers, and its header says why:
+   *  expressing a source statement through the gesture ops means the caller
+   *  doing the `(f - offsetFrames) * timeScale` arithmetic, which is exactly
+   *  the drift `videoClipOf` refuses. */
+  const source = (base: Doc3D, which: "inFrames" | "outFrames", to: number): Doc3D =>
+    setVideoSource(base, sceneId, layer.id, { [which]: Math.round(to) });
+  // The drag halves: `setVideoSource` clamps to the recording itself, so a
+  // capture past either end lands on it rather than refusing.
+  const inScrub = useScrub((doc, raw) => source(doc, "inFrames", Number(raw)));
+  const outScrub = useScrub((doc, raw) => source(doc, "outFrames", Number(raw)));
+
+  return (
+    <>
+      {/* A plain pair: the source edges in the recording's own frames. */}
+      <PropertyGrid>
+        <InspectorRow>
+          <NumberField
+            value={clip.sourceInFrames}
+            label="Src in"
+            ariaLabel="Source in frame"
+            unit="f"
+            step={1}
+            // NO `min`. A negative value is a real state — the window opens
+            // before the recording does — and `NumberField` clamps on every
+            // commit path, so a floor here would erase it on the first touch.
+            // The WRITE clamps instead, in `setVideoSource`, which is the
+            // ceiling this file's header states.
+            title="Which source frame plays under the window's in. Moves the footage, never the window"
+            onCommit={(next) => write((base) => source(base, "inFrames", next))}
+            onScrubStart={inScrub.start}
+            onScrub={inScrub.move}
+            onScrubEnd={inScrub.end}
+          />
+        </InspectorRow>
+        <InspectorRow>
+          <NumberField
+            value={clip.sourceOutFrames}
+            label="Src out"
+            ariaLabel="Source out frame"
+            unit="f"
+            step={1}
+            title="Which source frame plays under the window's out. Moves the out, never the in"
+            onCommit={(next) => write((base) => source(base, "outFrames", next))}
+            onScrubStart={outScrub.start}
+            onScrub={outScrub.move}
+            onScrubEnd={outScrub.end}
+          />
+        </InspectorRow>
+      </PropertyGrid>
+
+      <SpeedRow
+        doc={doc}
+        sceneId={sceneId}
+        layer={layer}
+        rate={rate}
+        onWrite={(next) => write(next)}
+        onRefusal={(message) => store.reportError(message)}
+      />
+
+      {/* Past the recording's END. `hold` is the default — a screen capture
+          under a longer shot ends on its last frame rather than restarting
+          mid-shot — and every document written before schema v22 carries an
+          explicit `loop` put there by the migration, so an old film keeps the
+          wrap it was authored with. */}
+      <InspectorRow label="Past end">
+        <SegmentedControl
+          ariaLabel="Video loop"
+          value={layer.video.loop ?? "hold"}
+          options={LOOP_OPTIONS}
+          onChange={(next) =>
+            write((base) => patchVideo(base, sceneId, layer.id, (v) => ({ ...v, loop: next as MediaLoop })))
+          }
+        />
+      </InspectorRow>
+
+      {/* THE NATURAL LENGTH. Through `writeLifespan` like every other edge, so
+          the footage clamp and the scene clamp are `trimLayer`'s and not a
+          second pair here. DISABLED, never hidden, when nobody has probed the
+          asset: the affordance for a capability stays visible at rest (the
+          design system's rule), and the tooltip says what is missing. */}
+      <InspectorRow label="Length">
+        <button
+          type="button"
+          className="btn"
+          data-testid="time-natural-length"
+          disabled={locked || natural === null}
+          title={
+            natural === null
+              ? "This recording has not been probed, so its length is unknown"
+              : `Set the out so the whole recording plays once, at frame ${natural}`
+          }
+          onClick={() =>
+            write((base) => {
+              if (natural === null) return base;
+              const now = lifespanOf(base.scenesById[sceneId]?.layersById[layer.id] ?? layer, scene.durationFrames);
+              return natural === now.out ? base : writeLifespan(base, sceneId, layer.id, "out", natural - now.out);
+            })
+          }
+        >
+          Natural length
+        </button>
+      </InspectorRow>
+
+      <InspectorRow>
+        <span className="insp-notice" data-testid="time-closing-edge">
+          {closingCaption(close, doc.fps, rate)}
+        </span>
+      </InspectorRow>
+    </>
+  );
+}
+
+/**
+ * The rate, with KEEP-WINDOW semantics and its refusal on screen.
+ *
+ * `retimeVideo` pins the source frame under the window's `in` across the
+ * change, so the bar does not move and the footage does not scrub sideways
+ * under a cut that is already timed. It REFUSES a rate away from 1 on a layer
+ * whose inline sound is in the mix, because neither mixer can resample — and a
+ * refusal that only returned the document unchanged would read as a field that
+ * snaps back for no reason.
+ *
+ * So the typed value is held in a DRAFT while the refusal is up. Without it the
+ * field re-renders from the document, shows the old rate, and the author's only
+ * evidence that anything happened is one line in the error strip.
+ *
+ * ── AND THE DRAFT IS RE-ASKED EVERY RENDER, NOT LATCHED ─────────────────
+ *
+ * The refusal names its own cure ("mute or remove the sound first"), so the
+ * document that cures it arrives while the draft is still on screen. A latched
+ * draft would then keep showing 2 over a layer that is now free to BE 2 — and
+ * because the field's value already reads 2, retyping it commits nothing at
+ * all: the author performs the cure the message asked for and the control is
+ * dead. So the stored draft is only honoured while the refusal still applies,
+ * and the field falls back to the document's own rate the moment it lifts.
+ */
+function SpeedRow(props: {
+  doc: Doc3D;
+  sceneId: string;
+  layer: VideoLayer3D;
+  rate: number;
+  onWrite: (write: (doc: Doc3D) => Doc3D) => void;
+  onRefusal: (message: string | null) => void;
+}) {
+  const { doc, sceneId, layer, rate } = props;
+  const [refused, setRefused] = useState<{ value: number; why: string } | null>(null);
+  // THE DRAG HALF, through the same op and the same refusal as a typed rate:
+  // a capture the sound forbids lands nothing new, and the release holds the
+  // refused rate on screen exactly as a typed one is held. A drag that lands
+  // lets go of a held one, as a typed rate that lands does: otherwise the field
+  // kept showing the refused 2 and its notice over a document now at 1.
+  const scrub = useOpScrub(
+    (base, raw) => {
+      const to = speedOf(raw);
+      const why = retimeVideoRefusal(base, sceneId, layer.id, to);
+      return why !== null ? { doc: base, refusal: why } : { doc: retimeVideo(base, sceneId, layer.id, to), refusal: null };
+    },
+    {
+      refused: (why, raw) => setRefused({ value: speedOf(raw), why }),
+      landed: () => setRefused(null),
+    },
+  );
+  // Re-asked, never latched — see the header. `retimeVideoRefusal` is a pure
+  // read over the live document, so the draft survives exactly as long as the
+  // reason for it does.
+  const standing =
+    refused !== null && retimeVideoRefusal(doc, sceneId, layer.id, refused.value) !== null ? refused : null;
+  return (
+    <>
+      <InspectorRow>
+        <NumberField
+          value={standing?.value ?? rate}
+          label="Speed"
+          ariaLabel="Video speed"
+          unit="x"
+          step={0.1}
+          // NO `min`, for the reason the source-in row has none: a negative
+          // rate is a legal authored value (backwards playback from a late
+          // start) and `NumberField` clamps on every commit path.
+          title="Playback rate, keeping the window and the frame it opens on. 2 runs the recording twice as fast"
+          onCommit={(next) => {
+            const to = speedOf(next);
+            const why = retimeVideoRefusal(doc, sceneId, layer.id, to);
+            if (why !== null) {
+              setRefused({ value: to, why });
+              props.onRefusal(why);
+              return;
+            }
+            setRefused(null);
+            props.onWrite((base) => retimeVideo(base, sceneId, layer.id, to));
+          }}
+          onScrubStart={scrub.start}
+          onScrub={scrub.move}
+          onScrubEnd={scrub.end}
+        />
+      </InspectorRow>
+      {standing === null ? null : (
+        <InspectorRow>
+          <span className="insp-notice is-warn" data-testid="time-speed-refusal">
+            {standing.why}
+          </span>
+        </InspectorRow>
+      )}
+    </>
+  );
+}
+
+/** A rate as the document may hold it: three decimals, and 0 (or anything
+ *  not a number) snapped to 1. Zero is REFUSED at the save gate rather than
+ *  written, so it is snapped here instead of being handed to the validator as
+ *  an error the author cannot see the cause of. */
+function speedOf(next: number): number {
+  const rounded = Number(next.toFixed(3));
+  return rounded === 0 || !Number.isFinite(rounded) ? 1 : rounded;
+}
+
+/**
+ * THE RECORDING'S OWN SOUND, on the layer that draws its picture.
+ *
+ * Only for a video that HAS one: `video.sound` absent means silent, which is
+ * every video layer written before the field existed, and a level field over
+ * nothing is three controls that write into a record that is not there.
+ * Attaching one is `add_footage`'s and the dock's job, not a level row's.
+ *
+ * ── THE GAIN AND THE REST TAKE DIFFERENT DOORS, ON PURPOSE ──────────────
+ *
+ * GAIN goes through `useSelectionWrite`, because `video.sound.gain` is a
+ * keyframable path: the write has to become a KEYFRAME at the playhead when the
+ * layer animates it, and that is precisely what `routeLayerEdit` does inside
+ * that hook. `setVideoSound` would write the base instead, which a track then
+ * ignores.
+ *
+ * MUTE AND THE FADES go through `setVideoSound`, because they are not tracked
+ * and they ARE gated: a fade pair longer than the frames the recording is
+ * audible over, a gain past the mixer's ceiling, a duck naming a clip that is
+ * gone — six rules that live in `validateShotDoc` and that the predicate asks
+ * rather than restates. Writing those fields raw would produce a document the
+ * save gate refuses, with the author holding the only copy.
+ *
+ * ── LOCK GOVERNS THIS SECTION LIKE EVERY OTHER ─────────────────────────
+ *
+ * `useDocWrite` and `useSelectionWrite` both run `lockRefuses`, and so does the
+ * dock's bar drag, so a locked clip refuses In/Out, the source rows, the sound
+ * rows and Gain alike, and names the layer.
+ *
+ * ── AND THE PATCH IS BUILT FROM THE BASE RECORD, NEVER THE RESOLVED ONE ──
+ *
+ * `setVideoSound` takes a WHOLE `VideoSound` and writes it verbatim, so the
+ * record handed to it is the record the document ends up with — every field,
+ * not only the one the author touched. `props.sound` is the layer AS PAINTED
+ * (`useSelectedLayers` runs `resolveTracksAt`), so when `video.sound.gain` is
+ * KEYFRAMED that record's `gain` is a SAMPLE OF AN ANIMATION at the playhead.
+ * Spreading it meant ticking Mute or nudging a fade froze the whole automation
+ * to whatever the needle happened to read on that frame, silently and with the
+ * author's only copy of the curve gone the moment the save landed.
+ *
+ * This is exactly the asymmetry `useDocWrite`'s header exists to state: READ
+ * resolved, WRITE the base. So `baseSoundOf` re-reads the authored record out
+ * of the document being written into, `next` patches the one field the author
+ * touched, and the gain the track owns passes through untouched — which is
+ * also what keeps `routeTrackedEdit`'s "the base is dead once a track exists"
+ * true rather than something this section quietly overwrites.
+ */
+function SoundRows(props: {
+  doc: Doc3D;
+  sceneId: string;
+  layer: VideoLayer3D;
+  sound: VideoSound;
+  onRefusal: (message: string | null) => void;
+}) {
+  const { doc, sceneId, layer, sound } = props;
+  const write = useDocWrite();
+  const selectionWrite = useSelectionWrite();
+  // THE DRAG HALVES. The gain through the selection seam its typed value takes
+  // (so a drag over an animated gain keys it), the fades through the same gate
+  // their typed values ask, refusing a capture the gate refuses.
+  const gainScrub = useSelectionScrub((subject, raw) => withGain(subject, Number(raw)));
+  const fadeScrub = (key: "fadeInFrames" | "fadeOutFrames") => (base: Doc3D, value: number) => {
+    const from = baseSoundOf(base, sceneId, layer.id);
+    if (from === undefined) return { doc: base, refusal: null };
+    const next = withFade(from, key, value);
+    const why = setVideoSoundRefusal(base, sceneId, layer.id, next);
+    return why !== null ? { doc: base, refusal: why } : { doc: setVideoSound(base, sceneId, layer.id, next), refusal: null };
+  };
+  const fadeInScrub = useOpScrub(fadeScrub("fadeInFrames"));
+  const fadeOutScrub = useOpScrub(fadeScrub("fadeOutFrames"));
+
+  /** One door for the three gated fields, with the refusal reported rather
+   *  than swallowed: a control that silently did nothing is the failure this
+   *  whole lane keeps removing.
+   *
+   *  `next` is applied TWICE and to two different records on purpose. The
+   *  predicate has to judge the document the author is looking at, so it gets
+   *  the base read out of `doc`; the write re-reads and re-patches inside
+   *  `useDocWrite`'s own document, which is this file's rule for every
+   *  untracked field (see the header) and is what makes a commit that lands
+   *  after an undo or another panel's edit measure against the right subject.
+   *  `next` is pure — `withFade` and `without` build a new object and read
+   *  nothing else — so applying it twice cannot compound. */
+  const patchSound = (next: (from: VideoSound) => VideoSound): void => {
+    const base = baseSoundOf(doc, sceneId, layer.id);
+    if (base === undefined) return;
+    const why = setVideoSoundRefusal(doc, sceneId, layer.id, next(base));
+    if (why !== null) {
+      props.onRefusal(why);
+      return;
+    }
+    write((into) => {
+      const from = baseSoundOf(into, sceneId, layer.id);
+      return from === undefined ? into : setVideoSound(into, sceneId, layer.id, next(from));
+    });
+  };
+
+  return (
+    <>
+      {/* A HEADING and not a nested `InspectorSection`: the sound is part of
+          this clip's timing, and a second collapsible inside one would give
+          the author two disclosure states for one subject. */}
+      <div className="insp-heading">Recording sound</div>
+
+      {/* dB, because that is the unit a level decision is made in, over a
+          document that stores the LINEAR multiplier the engine applies. The
+          conversion is `timeModel.ts`'s and its round trip is pinned there.
+          Both ends are the mixer's: silence (`MIN_GAIN_DB`, where the gain
+          reads back as a true 0) and its ceiling, so a drag stops where the
+          commit would. */}
+      <InspectorRow>
+        <NumberField
+          value={gainAsDb(sound.gain ?? 1)}
+          label="Gain"
+          ariaLabel="Recording gain"
+          unit="dB"
+          step={0.1}
+          min={MIN_GAIN_DB}
+          max={MAX_GAIN_DB}
+          title="Level of the recording's own sound. 0 dB is the file as recorded"
+          trailing={<KeyframeDot path="video.sound.gain" label="Gain" />}
+          onCommit={(next) => selectionWrite((subject) => withGain(subject, next))}
+          onScrubStart={gainScrub.start}
+          onScrub={gainScrub.move}
+          onScrubEnd={gainScrub.end}
+        />
+      </InspectorRow>
+
+      <InspectorRow label="Mute">
+        <Toggle
+          checked={sound.muted === true}
+          ariaLabel="Mute the recording's sound"
+          onChange={(checked) =>
+            patchSound((from) => (checked ? { ...from, muted: true } : without(from, "muted")))
+          }
+        />
+      </InspectorRow>
+
+      {/* A plain pair, the two fades. */}
+      <PropertyGrid>
+        <InspectorRow>
+          <NumberField
+            value={sound.fadeInFrames ?? 0}
+            label="Fade in"
+            ariaLabel="Recording fade in"
+            unit="f"
+            min={0}
+            step={1}
+            onCommit={(next) => patchSound((from) => withFade(from, "fadeInFrames", next))}
+            onScrubStart={fadeInScrub.start}
+            onScrub={fadeInScrub.move}
+            onScrubEnd={fadeInScrub.end}
+          />
+        </InspectorRow>
+        <InspectorRow>
+          <NumberField
+            value={sound.fadeOutFrames ?? 0}
+            label="Fade out"
+            ariaLabel="Recording fade out"
+            unit="f"
+            min={0}
+            step={1}
+            onCommit={(next) => patchSound((from) => withFade(from, "fadeOutFrames", next))}
+            onScrubStart={fadeOutScrub.start}
+            onScrub={fadeOutScrub.move}
+            onScrubEnd={fadeOutScrub.end}
+          />
+        </InspectorRow>
+      </PropertyGrid>
+    </>
+  );
+}
+
+/**
+ * A placement's loop (schema v47): what a component's clock does past its
+ * period. A code instance names its period (`loopFrames`), because a code
+ * component has no length of its own; a Studio-made component's period is its
+ * definition's length, shown here and edited on the definition. Both go
+ * through `useSelectionWrite`, which writes into whichever container holds the
+ * layer. Off removes the fields, the absence every older placement has.
+ */
+function PlacementLoopRows(props: { doc: Doc3D; layer: InstanceLayer3D | ComponentLayer3D }) {
+  const { doc, layer } = props;
+  const write = useSelectionWrite();
+  const loop = layer.kind === "instance" ? layer.instance.loop : layer.component.loop;
+  // A loop needs a period the moment it is switched on: one second of frames.
+  const second = Math.max(1, Math.round(doc.fps.num / doc.fps.den));
+  const def = layer.kind === "component" ? doc.components?.[layer.component.def] : undefined;
+  return (
+    <>
+      <InspectorRow label="Loop">
+        <SegmentedControl
+          ariaLabel="Placement loop"
+          value={loop ?? PLACEMENT_LOOP_OFF}
+          options={PLACEMENT_LOOP_OPTIONS}
+          onChange={(next) => write((base) => withPlacementLoop(base, next, second))}
+        />
+      </InspectorRow>
+      {layer.kind === "instance" && loop !== undefined ? (
+        <InspectorRow>
+          <NumberField
+            value={layer.instance.loopFrames ?? second}
+            label="Every"
+            ariaLabel="Loop period"
+            title="The loop's period, in frames"
+            unit="f"
+            min={1}
+            step={1}
+            onCommit={(next) =>
+              write((base) =>
+                base.kind === "instance" && base.instance.loop !== undefined
+                  ? { ...base, instance: { ...base.instance, loopFrames: Math.max(1, Math.round(next)) } }
+                  : base,
+              )
+            }
+          />
+        </InspectorRow>
+      ) : null}
+      {def !== undefined && loop !== undefined ? (
+        <InspectorRow label="Every" className="insp-readout">
+          <span className="insp-dim" data-testid="time-loop-period" title="The definition's length">
+            {`${defDurationFrames(def)}f · ${formatDuration(framesToSeconds(defDurationFrames(def), doc.fps))}`}
+          </span>
+        </InspectorRow>
+      ) : null}
+    </>
+  );
+}
+
+/** One placement's loop set to `next` ("off", "hold" or "loop"). Off deletes
+ *  the keys rather than writing undefined, the `exactOptionalPropertyTypes`
+ *  rule; an instance switched on keeps its period or takes `period`. */
+function withPlacementLoop(layer: Layer3D, next: string, period: number): Layer3D {
+  const on = next === PLACEMENT_LOOP_OFF ? null : (next as MediaLoop);
+  if (layer.kind === "instance") {
+    const { loop: _loop, loopFrames, ...rest } = layer.instance;
+    return { ...layer, instance: on === null ? rest : { ...rest, loop: on, loopFrames: loopFrames ?? period } };
+  }
+  if (layer.kind === "component") {
+    const { loop: _loop, ...rest } = layer.component;
+    return { ...layer, component: on === null ? rest : { ...rest, loop: on } };
+  }
+  return layer;
+}
+
+/**
+ * The recording's sound AS AUTHORED, out of the document it is read from.
+ *
+ * The one record `setVideoSound` may legally be handed. See `SoundRows`'s
+ * header: a resolved layer's `video.sound` carries a SAMPLED `gain` whenever
+ * the path is keyframed, and writing that back is how an animation gets
+ * flattened by a mute toggle.
+ *
+ * SCENE-ADDRESSED and not `homeOf`, matching the clip ops above: every
+ * `setVideoSound` call resolves its layer through `doc.scenesById`, so a
+ * container id that is a definition has to answer undefined here rather than
+ * hand back a record the op would then refuse to write.
+ */
+function baseSoundOf(doc: Doc3D, sceneId: string, layerId: string): VideoSound | undefined {
+  const layer: Layer3D | undefined = doc.scenesById[sceneId]?.layersById[layerId];
+  return layer !== undefined && layer.kind === "video" ? layer.video.sound : undefined;
+}
+
+/** The recording's gain set from dB on one layer, the one builder its typed
+ *  value and its drag both run. Another layer, or a video with no sound, is
+ *  left alone. */
+function withGain(subject: Layer3D, db: number): Layer3D {
+  return subject.kind === "video" && subject.video.sound !== undefined
+    ? {
+        ...subject,
+        video: { ...subject.video, sound: { ...subject.video.sound, gain: roundGain(dbToGain(db)) } },
+      }
+    : subject;
+}
+
+/** Four decimals, `audioLoudness.ts`'s own rule for a stored gain: enough to be
+ *  exact at any audible level, few enough that the number written into the
+ *  document is one a human can read back. Clamped to the mixer's range, so the
+ *  field's dB ceiling and the document's linear one are one limit. */
+function roundGain(gain: number): number {
+  const clamped = Math.max(0, Math.min(MAX_AUDIO_GAIN, Number.isFinite(gain) ? gain : 1));
+  return Math.round(clamped * 1e4) / 1e4;
+}
+
+/** A fade of 0 DELETES the key: absent already means no fade, and an explicit
+ *  0 is a second way to say the same thing that codegen then prints. */
+function withFade(sound: VideoSound, key: "fadeInFrames" | "fadeOutFrames", value: number): VideoSound {
+  const frames = Math.max(0, Math.round(Number.isFinite(value) ? value : 0));
+  return frames === 0 ? without(sound, key) : { ...sound, [key]: frames };
+}
+
+/** Drop one optional key rather than setting it to `undefined`. Under
+ *  `exactOptionalPropertyTypes` those are different values, and codegen prints
+ *  the record by key order — a present-but-undefined key is a key. */
+function without(sound: VideoSound, key: "muted" | "fadeInFrames" | "fadeOutFrames"): VideoSound {
+  const { [key]: _drop, ...rest } = sound;
+  void _drop;
+  return rest;
+}
+
+/** A plain video-block patch, for the ONE field here that is neither a clip op
+ *  nor a gated sound field. `loop` has no arithmetic and no gate: it picks
+ *  which of two branches `sourceTimeAt` takes past the end. */
+function patchVideo(
+  doc: Doc3D,
+  sceneId: string,
+  layerId: string,
+  next: (video: VideoLayer3D["video"]) => VideoLayer3D["video"],
+): Doc3D {
+  const scene = doc.scenesById[sceneId];
+  const layer: Layer3D | undefined = scene?.layersById[layerId];
+  if (scene === undefined || layer === undefined || layer.kind !== "video") return doc;
+  const video = next(layer.video);
+  if (video === layer.video) return doc;
+  return {
+    ...doc,
+    scenesById: {
+      ...doc.scenesById,
+      [sceneId]: { ...scene, layersById: { ...scene.layersById, [layerId]: { ...layer, video } } },
+    },
+  };
+}