@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -0,0 +1,180 @@
+// MAKE IT YOURS: the open Project's template fields (schema v50), one row each,
+// for the person who started from a template and now swaps in their own
+// screenshot, headline and logo.
+//
+// A container section: it shows with nothing selected in Studio, above the
+// Shots and inside one alike, and only while `swapFieldsOf` lists a field (a
+// data gate, layout.ts). The rows keep that list's order, the order a viewer
+// meets the fields: the Shots in playing order, then the definitions.
+//
+// ── EVERY WRITE IS AN EXISTING ONE, AIMED AT THE ROW'S OWN LAYER ────────
+//
+// A media row's Replace is the Media section's `replaceLayerMedia`, and a text
+// row writes `text.content` through `writeSelection`, the Text section's path,
+// each told the field's container: a field can sit in a Shot the playhead is
+// not in, or in a definition. So a viewer's refusal, the lock rule and the one
+// undo step are theirs. A locked layer keeps its row, its control locked, and
+// the lock's own sentence on it. The row's name only navigates (into its Shot,
+// or its component, with the layer selected), so it stays live for a viewer.
+import { useMemo, useRef, useState } from "react";
+import { InspectorSection, TextField, useLocked } from "@dailies-studio/ui";
+import { containerFrame, homeOf, lockRefusal, swapFieldsOf } from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D, SwapField } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import type { ShotEditorStore } from "../../../state/store.js";
+import { writeSelection } from "../../../state/fieldWrite.js";
+import { authoringFrame } from "../../../state/viewMode.js";
+import { IMAGE_ACCEPT, VIDEO_ACCEPT } from "../../toolbar/useAddRows.js";
+import { MediaPoster, assetUrl } from "../../storyboard/ReferencePreview.js";
+
+export function MakeItYoursSection() {
+  const doc = useShotEditor((s) => s.doc);
+  const fields = useMemo(() => (doc === null ? [] : swapFieldsOf(doc)), [doc]);
+  if (doc === null || fields.length === 0) return null;
+  return (
+    <InspectorSection
+      title="Make it yours"
+      persistKey="shot:make-it-yours"
+      summary={`${fields.length} ${fields.length === 1 ? "field" : "fields"}`}
+    >
+      <ul className="make-it-yours" data-testid="make-it-yours">
+        {fields.map((field) => (
+          <FieldRow key={`${field.containerId}/${field.layerId}`} doc={doc} field={field} />
+        ))}
+      </ul>
+    </InspectorSection>
+  );
+}
+
+function FieldRow({ doc, field }: { doc: Doc3D; field: SwapField }) {
+  const store = useStore();
+  const layer = homeOf(doc, field.containerId)?.layersById[field.layerId];
+  if (layer === undefined) return null;
+  const lock = layer.locked === true ? lockRefusal(layer) : null;
+  const where = [
+    field.containerName,
+    ...(field.container === "component" ? ["changes every use"] : []),
+    ...(lock === null ? [] : ["Locked"]),
+  ].join(" · ");
+  return (
+    <li className="make-it-yours-row" data-field={field.layerId}>
+      <div className="make-it-yours-head">
+        {layer.kind === "image" || layer.kind === "video" ? <MediaThumb doc={doc} layer={layer} /> : null}
+        <button
+          type="button"
+          className="make-it-yours-name"
+          title={field.container === "component" ? `Open ${field.containerName} and select this layer` : `Go to ${field.containerName} and select this layer`}
+          onClick={() => goToField(store, field)}
+        >
+          <span className="make-it-yours-label">{field.label}</span>
+          <span className="make-it-yours-where">{where}</span>
+        </button>
+        {layer.kind === "image" || layer.kind === "video" ? <ReplaceButton field={field} kind={layer.kind} lock={lock} /> : null}
+      </div>
+      {layer.kind === "text" ? (
+        <TextField
+          value={layer.text.content}
+          ariaLabel={`${field.label}, text`}
+          // A one-line field commits on Enter; content that already breaks a
+          // line keeps the textarea, so an edit never folds its lines.
+          multiline={layer.text.content.includes("\n")}
+          {...(lock === null ? {} : { readOnly: true, title: lock })}
+          onCommit={(content) => writeText(store, field, content)}
+        />
+      ) : null}
+    </li>
+  );
+}
+
+/** The field's picture as it stands: the stored file, small. */
+function MediaThumb({ doc, layer }: { doc: Doc3D; layer: Extract<Layer3D, { kind: "image" | "video" }> }) {
+  const asset = doc.assets[layer.kind === "image" ? layer.image.asset : layer.video.asset];
+  return (
+    <span className="make-it-yours-thumb" aria-hidden="true" {...(asset === undefined ? { title: "File missing" } : {})}>
+      {asset === undefined ? null : layer.kind === "image" ? (
+        <img className="make-it-yours-media" src={assetUrl(asset.path)} alt="" draggable={false} loading="lazy" />
+      ) : (
+        <MediaPoster className="make-it-yours-media" src={assetUrl(asset.path)} atSeconds={null} />
+      )}
+    </span>
+  );
+}
+
+/** Replace…, the Media section's verb, for the row's layer. A locked layer's
+ *  press says why instead of opening the picker. */
+function ReplaceButton({ field, kind, lock }: { field: SwapField; kind: "image" | "video"; lock: string | null }) {
+  const store = useStore();
+  const locked = useLocked();
+  const fileRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+  const pick = (file: File): void => {
+    setBusy(true);
+    void store
+      .replaceLayerMedia(field.layerId, file, field.containerId)
+      .catch((e: unknown) => store.reportError(e instanceof Error ? e.message : String(e)))
+      .finally(() => setBusy(false));
+  };
+  return (
+    <>
+      <button
+        type="button"
+        className="btn"
+        aria-label={`Replace, ${field.label}`}
+        title={lock ?? `Swap ${field.label} for a file of your own`}
+        disabled={locked || busy}
+        aria-disabled={lock !== null || undefined}
+        onClick={() => {
+          if (lock === null) fileRef.current?.click();
+          else store.reportError(lock);
+        }}
+      >
+        Replace…
+      </button>
+      <input
+        ref={fileRef}
+        type="file"
+        hidden
+        aria-label={`${field.label}, ${kind} file`}
+        accept={kind === "video" ? VIDEO_ACCEPT : IMAGE_ACCEPT}
+        onChange={(event) => {
+          const file = event.currentTarget.files?.[0];
+          event.currentTarget.value = "";
+          if (file !== undefined) pick(file);
+        }}
+      />
+    </>
+  );
+}
+
+/** The Text section's write, `writeSelection` over the one layer, in the
+ *  field's own container: one undo step, a locked layer named. */
+function writeText(store: ShotEditorStore, field: SwapField, content: string): void {
+  const s = store.getState();
+  if (s.doc === null) return;
+  const at = containerFrame(s.doc, field.containerId, authoringFrame(s));
+  let refusal: string | null = null;
+  const ran = store.edit((doc) => {
+    const out = writeSelection(
+      doc,
+      field.containerId,
+      [field.layerId],
+      (layer) => (layer.kind === "text" ? ({ ...layer, text: { ...layer.text, content } } as Layer3D) : layer),
+      at,
+    );
+    refusal = out.refusal;
+    return out.doc;
+  });
+  if (ran && refusal !== null) store.reportError(refusal);
+}
+
+/** Into the field's Shot, or its component's definition, with the layer
+ *  selected: the verbs Every use's Go to takes (`goToComponentUse`). */
+function goToField(store: ShotEditorStore, field: SwapField): void {
+  if (field.container === "component") {
+    store.editComponent(field.containerId);
+    if (store.getState().editingDef === field.containerId) store.select([field.layerId]);
+    return;
+  }
+  store.enterScene(field.containerId);
+  if (store.getState().enteredScene === field.containerId) store.select([field.layerId]);
+}

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

@@ -0,0 +1,191 @@
+// THE PROJECT ITSELF: the document's own four fields, shown in both contexts
+// when nothing is selected.
+//
+// ── COLLAPSIBLE IN BOTH, OPEN BY DEFAULT ONLY WHERE IT IS THE SUBJECT ─────
+//
+// It was pinned open and mounted in the project context alone. Inside a shot
+// the size and rate are still the frame the author is composing into, so the
+// rail now carries the section there too, collapsed to one mono line
+// ("1920×1080 · 30fps") that answers the question without the four rows. In
+// the project context the rows ARE the work, so it opens by default there.
+// The two contexts keep separate collapse bits for that reason: one shared bit
+// would make collapsing it inside a shot hide the project's own panel.
+//
+// ── WHY THIS DID NOT EXIST ──────────────────────────────────────────────
+//
+// The rail's empty-selection branch mounted the SHOT sections in both contexts,
+// so the scene context described whichever shot the playhead was over and
+// changed under every scrub across a cut. The document's own fields had no
+// writer anywhere in the chrome: `doc.fps` and `doc.size` were read by the
+// export dialog and by nothing else, and `doc.name` by nothing at all. A tool
+// that can open a video, arrange it and render it, but cannot say what rate or
+// what size it is, is missing a panel rather than a feature.
+//
+// ── THE RATE IS A PICKER AND NOT A NUMBER ────────────────────────────────
+//
+// `doc.fps` is a RATIONAL, and the rates that matter are not all integers, so
+// the control offers exact pairs from `FPS_OPTIONS` (the one table both editors
+// read) rather than a decimal field. A document naming a rate that list does not
+// have keeps it, labelled, exactly as the transition picker keeps an unknown
+// preset rather than silently rewriting it.
+import { Combobox, InspectorRow, InspectorSection, NumberField, TextField } from "@dailies-studio/ui";
+import type { ComboboxOption } from "@dailies-studio/ui";
+import { FPS_OPTIONS } from "@dailies-studio/timeline";
+import { docDurationFrames } from "@dailies-studio/shot/doc";
+import { framesToSeconds } from "@dailies-studio/engine";
+import type { Rational } from "@dailies-studio/engine";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { SECTION_ICONS } from "../../../icons.js";
+import { formatDuration } from "../../timeline/model.js";
+
+/** "<num>/<den>" — the picker's value, so an exact rational round-trips through
+ *  a string-valued control without a lookup table on the way back. */
+const rateKey = (fps: Rational): string => `${fps.num}/${fps.den}`;
+
+/** Said on the label and on the field, because either one may be what the
+ *  pointer lands on and a field that moves a source file should warn from
+ *  both. */
+const COMPONENT_TITLE =
+  "The generated component's name. Changing it moves src/shots/<Name>.tsx on the next save.";
+
+export function SceneDocSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const inShot = useShotEditor((s) => s.enteredScene !== null);
+  if (doc === null) return null;
+
+  const total = docDurationFrames(doc);
+  const key = rateKey(doc.fps);
+  const known = FPS_OPTIONS.some((r) => rateKey(r.fps) === key);
+  const options: ComboboxOption[] = [
+    // FPS_OPTIONS is fastest-first, as the motion editor has always shown it;
+    // this picker reads slowest-first, so the copy is what gets reversed.
+    ...FPS_OPTIONS.map((r) => ({ value: rateKey(r.fps), label: r.label })).reverse(),
+    // A rate this build's list does not carry is KEPT and named. Dropping to
+    // the nearest one would retime the whole video on the first unrelated edit.
+    ...(known ? [] : [{ value: key, label: `${(doc.fps.num / doc.fps.den).toFixed(3)} (${key})` }]),
+  ];
+
+  // The rate as a plain number: 30, 29.97, 23.976. Three places at most and
+  // trailing zeros dropped, so an integer rate does not read "30.000".
+  const fps = Number((doc.fps.num / doc.fps.den).toFixed(3));
+
+  // A DRAG on W or H resizes the frame under the pointer, as every other
+  // dragged field writes: the panel scrub around `setDocSize`, which captures
+  // into it while it is open (store.ts), so the whole drag is one undo entry.
+  // Each move names the one side it moves and keeps the other as drawn.
+  const dragSize = (side: "width" | "height") => ({
+    onScrubStart: () => store.beginScrub(),
+    onScrub: (value: number) => store.setDocSize({ ...doc.size, [side]: value }),
+    onScrubEnd: (commit: boolean) => store.endScrub(commit),
+  });
+
+  return (
+    <InspectorSection
+      title="Project"
+      icon={SECTION_ICONS.project}
+      summary={`${doc.size.width}×${doc.size.height} · ${fps}fps`}
+      numericSummary
+      // `shot:document` is the project context's existing bit, kept so nobody's
+      // stored collapse state is thrown away.
+      persistKey={inShot ? "shot:document:in-shot" : "shot:document"}
+      defaultCollapsed={inShot}
+      // No section scope: the rhythm, the fields and the readout face its two
+      // derived rows wear are the house's (widgets.css), for every panel alike.
+    >
+      {/* "Component" and not "Generated component": `.insp-label` is capped at
+          60% of a 288px pill, so the longer wording ellipsised ITSELF and then
+          truncated the value beside it, which is the one thing on the row an
+          author needs to read. The full story stays on the label's title and in
+          the aria name, where length costs nothing. */}
+      <InspectorRow label="Component" labelTitle={COMPONENT_TITLE}>
+        {/* `doc.name`, not `state.name`. The latter is the stable Project slug
+            used by the URL and server; this is the name the
+            generated component takes, so committing it moves
+            `src/shots/<Name>.tsx` on the next save. The title says so, because
+            a field that silently moves a source file is worse than one that
+            warns. */}
+        <TextField
+          value={doc.name}
+          ariaLabel="Generated component name"
+          title={COMPONENT_TITLE}
+          onCommit={(name) => store.setDocName(name)}
+        />
+      </InspectorRow>
+      {/* THE FRAME'S SIZE, A PAIR LIKE TRANSFORM'S W | H: two boxes, each
+          its own field with its prefix inside, and no "Size" pill around them
+          (a labelled box holding two more boxes drew the name twice and
+          squeezed both values). Whole pixels from one up, the store's clamp
+          stated where the author types. */}
+      <InspectorRow>
+        <div className="insp-vec">
+          <NumberField
+            value={doc.size.width}
+            label="W"
+            ariaLabel="Project width"
+            unit="px"
+            min={1}
+            step={1}
+            {...dragSize("width")}
+            onCommit={(width) => store.setDocSize({ ...doc.size, width })}
+          />
+          <NumberField
+            value={doc.size.height}
+            label="H"
+            ariaLabel="Project height"
+            unit="px"
+            min={1}
+            step={1}
+            {...dragSize("height")}
+            onCommit={(height) => store.setDocSize({ ...doc.size, height })}
+          />
+        </div>
+      </InspectorRow>
+      <InspectorRow label="Rate">
+        <Combobox
+          ariaLabel="Frame rate"
+          options={options}
+          value={key}
+          onChange={(next) => {
+            const [num, den] = next.split("/").map(Number);
+            if (num === undefined || den === undefined) return;
+            store.setDocFps({ num, den });
+          }}
+        />
+      </InspectorRow>
+      {/* DERIVED, so both are text and not fields: the length of a scene is the
+          sum of its shots' durations, and the one place to change it is the
+          Duration row in the Shot section below. A writable total would need a
+          rule for which shot absorbed the difference, and there is no honest
+          answer to that.
+
+          SO THE WORD APPEARS TWICE IN THIS RAIL, once read-only here and once
+          editable there, and the section heading above each — Project, Shot —
+          is what separates them. That is the deliberate trade: the two rows
+          hold the same quantity in the same unit, and spelling one of them
+          differently would invent a distinction an author would go looking for
+          and not find.
+
+          TWO ROWS AND NOT ONE. "1:04 · 1920f · 7 shots" read as one cryptic
+          string because it answered two different questions at once: how long
+          the film runs, and how many pieces it is in. A labelled row each says
+          which number is which without a legend.
+
+          IN THE HOUSE READOUT (`insp-readout`, widgets.css), the Time
+          section's: the field's box with nothing to type into and no hover, the
+          number in the numeral face in the second ink. They were the 10px sans
+          `.insp-dim` alone, which set a total in a smaller face than every
+          value around it. */}
+      <InspectorRow label="Duration" className="insp-readout">
+        <span className="insp-dim" data-testid="scene-length">
+          {formatDuration(framesToSeconds(total, doc.fps))} · {total}f
+        </span>
+      </InspectorRow>
+      <InspectorRow label="Shots" className="insp-readout">
+        <span className="insp-dim" data-testid="scene-shots">
+          {doc.scenes.length}
+        </span>
+      </InspectorRow>
+    </InspectorSection>
+  );
+}

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

@@ -1,71 +1,246 @@
-// 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
+// The shot's own properties, shown when nothing is selected. The subject
+// switch is the SELECTION, not a tab: a layer inspector and a shot 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";
+//
+// ── THE ROWS ARE SHARED, THE SECTION IS NOT ──────────────────────────────
+//
+// `ShotRows` is the body and two sections wear it. Inside a shot it is
+// `SceneSection`, "Shot". In the project context it is the top half of
+// "Shot & transition" (TransitionSection.tsx), because there the shot and the
+// seam after it are read together. One body, so a row added here lands in
+// both and the two can never disagree about what a shot is.
+//
+// Name and Duration are the shot's IDENTITY and its place on the master
+// timeline, so they show in both contexts (the Name row with one exception,
+// see its own note). Background is what the shot LOOKS like, a judgement made
+// against the framed picture, so it stays inside the shot.
+//
+// THE LENS MOVED TO CAMERA as its FOV row. `fovDeg` is stored on the scene,
+// but it is a camera property to the author: it sets how far the camera
+// stands, which is what parallax strength is. `patchScene` is exported for
+// that row so the lens keeps this file's one write path.
+import { InspectorRow, InspectorSection, NumberField, TextField } from "@dailies-studio/ui";
+import { containerFrame, trimScene } from "@dailies-studio/shot/doc";
+import type { Doc3D, Scene3D } from "@dailies-studio/shot/doc";
+import { SceneKeyframeDot } from "../KeyframeDot.js";
+import { SECTION_ICONS, SPARKLES_ICON } from "../../../icons.js";
+import { PaintRows } from "../design/PaintRows.js";
 import { useShotEditor, useStore } from "../../../state/context.js";
-import { NO_SCRUB } from "../useDocWrite.js";
+import { backgroundLayerOf } from "../../../state/insert.js";
+import { useInspectorScene, useScrub, writeScene } from "../useDocWrite.js";
 
+/**
+ * One scene, patched, over the document it is HANDED.
+ *
+ * Both write paths run it: a typed value through `edit`, and a drag through
+ * `scrubCapture`, which re-derives from the gesture's BASE. Two spellings of
+ * this would be two answers to what a background drag did, and the drag's is
+ * the one nobody would be watching.
+ */
+export function patchScene(doc: Doc3D, sceneId: string, next: Partial<Scene3D>, frame: number): Doc3D {
+  // Through `writeScene`, so a shot that ANIMATES its background takes a
+  // keyframe at the playhead rather than a constant the track is already
+  // overriding (P5). Nothing else it writes is trackable (a name, a duration
+  // and the camera's lens are not per-frame values), so this is one path's
+  // rule riding the seam every field already crosses.
+  return writeScene(doc, sceneId, (scene) => ({ ...scene, ...next }), containerFrame(doc, sceneId, frame));
+}
+
+/**
+ * Inside a shot, the shot alone: the seam after it is off screen there, so the
+ * transition rows are not offered (see `CONTAINER_LAYOUT`).
+ *
+ * COLLAPSIBLE, like every sibling in the rail. It was pinned open because it
+ * was the only thing naming the shot, so collapsing it left the panel
+ * describing something it no longer named. The head carries the name now, so
+ * the section is free to behave like the rest of the stack. The `persistKey`
+ * is unchanged: it is invisible to the author, and renaming it would only
+ * throw away the collapse state people already have.
+ */
 export function SceneSection() {
+  // A boolean, so the selector returns a primitive and never allocates.
+  const has = useShotEditor((s) => s.sceneId !== null && s.doc?.scenesById[s.sceneId] !== undefined);
+  if (!has) return null;
+  // The same rows in the same look as "Shot & transition", which wears the
+  // same body: both are the house rows (widgets.css), with no section scope.
+  return (
+    <InspectorSection title="Shot" icon={SECTION_ICONS.shot} persistKey="shot:scene">
+      <ShotRows />
+    </InspectorSection>
+  );
+}
+
+/** The shot's own rows, the body both shot sections wear. */
+export function ShotRows() {
   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;
+  /** Inside a shot (or a definition, which mounts its own panel): the
+   *  background rows below. The same bit the rest of the chrome branches on. */
+  const inShot = useShotEditor((s) => s.enteredScene !== null);
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const ground = useShotEditor((s) =>
+    s.enteredScene === null ? null : backgroundLayerOf(s.doc?.scenesById[s.enteredScene]),
+  );
+
+  // ── THE DRAG HALF, DECLARED BEFORE THE EARLY RETURNS ──────────────────
+  //
+  // Before, because a hook that sits after a conditional return changes the
+  // hook count between renders. ONE bracket for every patchable field: the
+  // widget sends the PATCH it is pointing at, so every background control
+  // shares one capture rule instead of one hook each.
+  //
+  // The scene is read from the STORE inside the capture, never closed over
+  // from this render. It is the same live read `useSelectionScrub` makes, so a
+  // drag held across a scene switch cannot write into the scene the panel last
+  // rendered against.
+  const dragScene = useScrub((d, raw) => {
+    const id = store.getState().sceneId;
+    // The frame LIVE at the capture and against the document BEING WRITTEN.
+    return id === null ? d : patchScene(d, id, raw as Partial<Scene3D>, store.getState().frame);
+  });
+  // The duration goes through `trimScene` and not through the patch above,
+  // because that op owns the floor clamp and returns the base BY REFERENCE when
+  // the number did not move, so a drag that ends where it started commits
+  // nothing, exactly as the typed path behaves.
+  const dragDuration = useScrub((d, raw) => {
+    const id = store.getState().sceneId;
+    return id === null ? d : trimScene(d, id, Number(raw));
+  });
+  // TYPED at the call sites. `move` takes `unknown`, so without this a
+  // mistyped field name would ride a drag straight into the document and only
+  // show up as a control that does nothing.
+  const moveScene = (next: Partial<Scene3D>): void => dragScene.move(next);
+
+  // THE SHOT AS PAINTED, not the authored constants. `background.color` is
+  // keyframable, and once it carries a track the constant this used to read is
+  // pinned by `routeTrackedEdit` — so the well showed a colour the stage had
+  // long left, and dragging it moved nothing on screen. Display only; every
+  // write below still goes through `patchScene` over the handed document.
+  const scene = useInspectorScene();
+
+  if (doc === null || sceneId === null || scene === null) 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 } },
-    }));
+    store.edit((d) => patchScene(d, sceneId, next, store.getState().frame));
   };
 
   return (
-    <InspectorSection title="Shot" persistKey="shot:scene" collapsible={false}>
-      <InspectorRow label="Name">
-        <TextField value={scene.name} ariaLabel="Shot name" onCommit={(name) => patch({ name })} />
-      </InspectorRow>
+    <>
+      {/* ── THE NAME ROW, IN ONE CONTEXT ONLY ────────────────────────────
+          Inside a shot the head IS this field (`InspectorHead`'s "Shot"
+          subject, renaming through `renameScene`), and a heading plus a Name
+          row two lines below it holding the same string is the panel saying
+          the same thing twice.
+
+          In the SCENE context the head names the PROJECT, because that is what
+          the panel is a view of there, and the shot below it is one of its
+          parts. So the row stays: dropping it in both contexts would leave the
+          scene context with no way to rename a shot at all, and a capability's
+          only affordance has to remain visible at rest. */}
+      {inShot ? null : (
+        <InspectorRow label="Name">
+          <TextField value={scene.name} ariaLabel="Shot name" onCommit={(name) => patch({ name })} />
+        </InspectorRow>
+      )}
       <InspectorRow>
+        {/* DURATION, in frames, carrying its unit in the field's own suffix the
+            way every other frame count in this panel does. `ariaLabel` is
+            unchanged: it is what the tests address this field by and it already
+            said "duration".
+
+            THE WORD IS THE PROJECT'S, AND THE PROJECT'S ROW IS NOT A FIELD.
+            `SceneDocSection`'s Duration is a DERIVED read-only total
+            ("1:04 · 1920f", the sum of every shot), and the Project section
+            sits directly above this one in both contexts. So the rail now shows the word twice
+            there, once read-only and once editable, and the section heading
+            above each — Project, Shot — is what separates them. That is the
+            trade this rename made, and it is the reason `data-testid` and
+            `aria-label` stayed put: they, not the visible word, are how
+            anything addresses either row.
+
+            The transition rows say "Duration" too, because in the project
+            context they share this row's section and Duration, Duration, Frames
+            for three lengths in frames is the panel inventing a distinction
+            that is not there. The row still spelled "Frames",
+            `DefinitionSection`'s, never shares a rail with a Duration row, so
+            nothing reads two words for one quantity anywhere. That is
+            structural and not luck: the definition container renders
+            `DefinitionSection` alone. */}
         <NumberField
           value={scene.durationFrames}
-          label="Frames"
+          label="Duration"
+          unit="f"
           ariaLabel="Shot duration"
           min={1}
           step={1}
+          onScrubStart={dragDuration.start}
+          onScrub={dragDuration.move}
+          onScrubEnd={dragDuration.end}
           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>
+      {inShot ? (
+        <>
+          {/* A scene is OPAQUE by contract (types.ts), so there is no alpha
+              anywhere in these rows and none is offered — the renderer clears
+              with alpha 1, and a transparent background would be a promise the
+              export cannot keep. `opaque` is what keeps that true: without it
+              every picker here showed an alpha bar and took an 8-digit hex.
+
+              The rows write the whole `Paint` union, which is what the renderer
+              has always read: `BackgroundPlane` draws both gradients for real
+              through the ordinary Canvas2D rasterizer. Before this, the row was
+              a solid-only picker whose scrub AND commit each wrote
+              `{type: "solid"}`, so touching the swatch DELETED a gradient an
+              agent or an MCP call had authored.
+
+              The keyframe diamond rides the SOLID row only. `background.color`
+              is a colour track and the track table refuses it over a gradient,
+              which is a paint with no single colour to interpolate. */}
+          <PaintRows
+            value={scene.background}
+            ariaPrefix="Background"
+            // The type row READS "Background" here and plain "Type" in
+            // `FillSection`, whose own heading already says Fill. Under this
+            // heading — "Shot", beside a Duration — "Type" would
+            // name nothing it is the type of.
+            label="Background"
+            opaque
+            solidTrailing={<SceneKeyframeDot path="background.color" />}
+            onScrubStart={dragScene.start}
+            onScrub={(edit) => moveScene({ background: edit(scene.background) })}
+            onScrubEnd={dragScene.end}
+            onCommit={(edit) => patch({ background: edit(scene.background) })}
+          />
+          {/* THE DRAWER'S OTHER DOOR. A shader ground is a locked layer at the
+              back, not a Paint, so these rows cannot hold one. This opens the
+              Insert drawer at Backgrounds, where "Use as background" places it.
+              Once one is placed, the door selects it instead: a locked layer
+              skips stage clicks, so this and its outline row are the ways to
+              its props. Hidden for a viewer, like the drawer it opens. */}
+          {readOnly ? null : (
+            <InspectorRow>
+              <div className="insp-buttons">
+                <button
+                  type="button"
+                  className="btn shot-shader-button"
+                  onClick={() =>
+                    ground === null ? store.openInsertDrawer("Backgrounds") : store.select([ground])
+                  }
+                >
+                  {SPARKLES_ICON}
+                  {ground === null ? "Shader background…" : "Edit background"}
+                </button>
+              </div>
+            </InspectorRow>
+          )}
+        </>
+      ) : null}
+    </>
   );
 }