@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -1,5 +1,6 @@
-// The scene's camera, as five fields. Shown under the scene, when nothing is
-// selected.
+// The scene's camera: where it looks, its lens, its zoom and its orbit. Shown
+// in both contexts when nothing is selected, after the context's own section
+// (see `CONTAINER_LAYOUT`).
 //
 // ── THE SAME TWO TRUTHS THE LAYER INSPECTOR FOLLOWS ─────────────────────
 //
@@ -12,48 +13,257 @@
 // onwards `cameraAt` is painting a shot's framing, so writing `scene.camera`
 // there would dirty the document and move nothing. That refusal is not written
 // here. It is `writeFraming`'s, reached through the store's `writeCamera`, the
-// same seam the frustum drag, the align and the fit all go through. This panel
-// is a keyboard frustum and deliberately has no opinion of its own.
-//
-// The two halves are coherent by construction rather than by care:
-// `shotOwningCamera` is null exactly when `cameraAt` returns `scene.camera`, so
-// whenever a base write is allowed the effective value IS the base.
-import { InspectorSection } from "@dailies-studio/ui";
-import { cameraAt, shotOwningCamera } from "@dailies-studio/shot/doc";
+// same seam the gizmo drag, the align and the fit all go through. This panel
+// is a keyboard gizmo and deliberately has no opinion of its own.
+//
+// ── AND IT SAYS WHAT A CHANGE WILL DO, BEFORE ONE IS MADE ───────────────
+//
+// `cameraWriteGate` is the fork's own answer, asked up front: held by which
+// move, or edits which move, or adds one. The same sentence the error strip
+// speaks after a refused drag, said here while the author is still reading.
+//
+// ── A DRAG HERE IS A STAGE DRAG ─────────────────────────────────────────
+//
+// The fields and the zoom slider scrub LIVE, through the stage's own
+// framing lane (`onFramingGestureStart`/`End`): one gesture, one undo entry,
+// and the same "a lane already open wins" refusal the gizmo gets. They used
+// to commit only on release, so the stage did not move while the number did.
+//
+// ── ITS KEYS ARE ITS POSES ──────────────────────────────────────────────
+//
+// The camera has no property track: it animates through moves, and a move's
+// two ends are the camera's keyframes (`cameraMarks`, the same marks the
+// camera row draws). So each field's diamond reads those poses: KEYED when a
+// pose sits at the playhead (a pose holds the whole framing, so every field
+// lights together), ANIMATED when the field's value differs between poses,
+// STATIC otherwise. A click on a keyed diamond removes the move that pose
+// belongs to; a click anywhere else adds a move ending at the playhead
+// (`addShotAtPlayhead`, the camera row's "+ shot"). A path's interior
+// waypoint is read-only here, as it is on the row. While the transport plays
+// the diamonds are disabled: their state is read off the held inspector frame
+// while a press would add or remove a move at the live one.
+//
+// Each diamond sits INSIDE its field, the house in-field key, and it is the
+// ACCENT, not `--kf`: `--kf` is a property keyframe on a track, and a camera
+// pose is not one (model.ts says the same of its marks). The lens has no
+// diamond at all: it is not part of a pose.
+import { useEffect, useMemo, useRef } from "react";
+import { InspectorSection, NumberField } from "@dailies-studio/ui";
+import { cameraAt, cameraWriteGate, removeShot } from "@dailies-studio/shot/doc";
+import type { Doc3D, Framing, Scene3D } from "@dailies-studio/shot/doc";
+import type { ShotEditorStore } from "../../../state/store.js";
 import { useShotEditor, useStore } from "../../../state/context.js";
-import { FramingRows } from "../FramingRows.js";
-import { useInspectorFrame } from "../useDocWrite.js";
+import { SECTION_ICONS } from "../../../icons.js";
+import { FRAMING_KEYS, FramingRows } from "../FramingRows.js";
+import type { CameraKeys, FramingScrub } from "../FramingRows.js";
+import { cameraMarks } from "../../timeline/model.js";
+import { useInspectorFrame, useScrub } from "../useDocWrite.js";
+import { patchScene } from "./SceneSection.js";
+
+/**
+ * The camera's gesture bracket over the store's framing lane.
+ *
+ * THE LANE IS OPENED ON THE FIRST MOVE, not on the press: a press that never
+ * moves (a click to focus, a slider tap on the thumb) then opens nothing. If
+ * the lane refuses (another drag holds the history), the gesture writes
+ * nothing live and its last value is committed as one plain edit at the end,
+ * so the author's number still lands rather than vanishing.
+ *
+ * Stable for the store's lifetime, and the gesture is a ref, so the widgets
+ * reading these at pointer time always see the one gesture in flight.
+ */
+function useCameraScrub(store: ShotEditorStore): FramingScrub {
+  const gesture = useRef<{ open: boolean | null; last: Partial<Framing> | null } | null>(null);
+  // A section unmounted mid-drag (the subject changed under the pointer)
+  // must not leave the lane open: the next stage drag would be refused.
+  useEffect(
+    () => () => {
+      if (gesture.current?.open === true) store.stageHandlers.onFramingGestureEnd(false);
+      gesture.current = null;
+    },
+    [store],
+  );
+  return useMemo(() => {
+    const move = (patch: Partial<Framing>): void => {
+      const g = gesture.current;
+      if (g === null) return;
+      g.last = { ...g.last, ...patch };
+      if (g.open === null) g.open = store.stageHandlers.onFramingGestureStart();
+      if (g.open) store.setSceneCamera(patch);
+    };
+    const end = (commit: boolean): void => {
+      const g = gesture.current;
+      gesture.current = null;
+      if (g === null) return;
+      if (g.open === true) store.stageHandlers.onFramingGestureEnd(commit);
+      else if (commit && g.last !== null) store.setSceneCamera(g.last);
+    };
+    return {
+      start: () => {
+        gesture.current = { open: null, last: null };
+      },
+      move,
+      end,
+      commit: (patch) => {
+        if (gesture.current === null) {
+          store.setSceneCamera(patch);
+          return;
+        }
+        move(patch);
+        end(true);
+      },
+    };
+  }, [store]);
+}
+
+/** Why the diamonds are disabled while the transport runs, as their tooltip. */
+const PLAYING_ACTION = "Pause playback to add or remove a camera move.";
+
+/**
+ * The diamonds' data for the scene at a scene-local frame. Pure, so the rule
+ * is testable without a store: `remove` is handed the id of the move to drop
+ * and `add` adds one at the playhead.
+ */
+export function cameraKeys(
+  doc: Doc3D,
+  scene: Scene3D,
+  sceneFrame: number,
+  actions: { add(): void; remove(shotId: string): void },
+): { keys: CameraKeys; count: number } {
+  const marks = cameraMarks(scene, doc.fps);
+  const poses = marks.map((mark) => cameraAt(scene, mark.frame, doc.fps, doc.size));
+  const animated = new Set(
+    FRAMING_KEYS.filter((key) => poses.some((pose) => (pose[key] ?? 0) !== (poses[0]![key] ?? 0))),
+  );
+  const here = marks.find((mark) => mark.frame === sceneFrame);
+  const shot = here === undefined ? undefined : scene.shots.find((s) => here.id.startsWith(`${s.id}:`));
+  let action: string;
+  let toggle: (() => void) | null;
+  if (here === undefined) {
+    action = "Click to add a camera move ending at the playhead.";
+    toggle = actions.add;
+  } else if (here.kind === "waypoint" || shot === undefined) {
+    action = "A path waypoint is read-only here: edit its pose in the move's waypoint rows.";
+    toggle = null;
+  } else {
+    action = `Click to remove the camera move “${shot.label}”.`;
+    toggle = () => actions.remove(shot.id);
+  }
+  return {
+    count: marks.length,
+    keys: {
+      stateOf: (key) => (here !== undefined ? "keyed" : animated.has(key) ? "animated" : "static"),
+      animatedOf: (key) => animated.has(key),
+      action,
+      toggle,
+    },
+  };
+}
 
 export function CameraSection() {
   const store = useStore();
   const doc = useShotEditor((s) => s.doc);
   const animate = useShotEditor((s) => s.animateMode);
+  const driver = useShotEditor((s) => s.cameraDriver);
+  const playing = useShotEditor((s) => s.playing);
   const { sceneId, sceneFrame } = useInspectorFrame();
+  const scrub = useCameraScrub(store);
+  // The lens writes the SCENE, so it rides the scene's scrub and its one
+  // patch op rather than the framing lane. The scene is read live per capture,
+  // for `SceneSection`'s reason.
+  const dragLens = useScrub((d, raw) => {
+    const id = store.getState().sceneId;
+    return id === null ? d : patchScene(d, id, raw as Partial<Scene3D>, store.getState().frame);
+  });
   if (doc === null || sceneId === null) return null;
   const scene = doc.scenesById[sceneId];
   if (scene === undefined) return null;
 
-  // Only worth saying with animate OFF: with it on the same write authors a
-  // move instead of being refused, so naming the owner would be a warning about
-  // something that is not going to happen.
-  const owner = animate ? null : shotOwningCamera(scene, sceneFrame);
+  const gate = cameraWriteGate(scene, sceneFrame, animate);
+  const { keys, count } = cameraKeys(doc, scene, sceneFrame, {
+    add: () => store.addShotAtPlayhead(sceneId),
+    remove: (shotId) => store.edit((d) => removeShot(d, sceneId, shotId)),
+  });
 
   return (
-    <InspectorSection title="Camera" persistKey="shot:camera">
+    // No section scope: the camera's rows keep the rhythm and the fields every
+    // other section keeps because both are the house's (widgets.css).
+    <InspectorSection
+      title="Camera"
+      icon={SECTION_ICONS.camera}
+      note={count > 0 ? <span className="camera-field-key-count">· {count} keyed</span> : undefined}
+      persistKey="shot:camera"
+    >
+      {driver !== null && (
+        <span className="insp-notice" data-testid="camera-driven-by">
+          Camera driven by {driver}. The framing below has no effect while it is.
+        </span>
+      )}
       <FramingRows
-        framing={cameraAt(scene, sceneFrame, doc.fps)}
+        framing={cameraAt(scene, sceneFrame, doc.fps, doc.size)}
         name="Camera"
-        onCommit={(patch) => store.setSceneCamera(patch)}
+        scrub={scrub}
+        zoomSlider
+        keys={playing ? { ...keys, toggle: null, action: PLAYING_ACTION } : keys}
+        fov={
+          // 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). Moved here from the Shot section: it is the
+          // camera's lens, whatever object stores it.
+          //
+          // Its name starts with the word in its box, so a speech command and
+          // a screen reader use the word the author reads. No diamond: the
+          // lens is the scene's, not a pose's, and a dead diamond would only
+          // claim it keys.
+          <NumberField
+            value={scene.fovDeg}
+            label="FOV"
+            ariaLabel="FOV, field of view"
+            unit="°"
+            min={5}
+            max={120}
+            step={1}
+            title="The lens. A wide field of view puts the camera close, so depth changes scale a lot; a long lens puts it far, and the same depth barely registers"
+            onScrubStart={dragLens.start}
+            onScrub={(fovDeg) => dragLens.move({ fovDeg } satisfies Partial<Scene3D>)}
+            onScrubEnd={dragLens.end}
+            onCommit={(fovDeg) => {
+              store.edit((d) => patchScene(d, sceneId, { fovDeg }, store.getState().frame));
+            }}
+          />
+        }
       />
-      {owner !== null && (
+      {gate.kind === "held" && gate.shot !== undefined && (
         // The fields stay LIVE. Typing into one produces the refusal by name in
         // the error strip, which is how the author learns the rule; a disabled
         // field would only teach them that the panel is broken.
-        <span className="insp-dim" data-testid="camera-held-by">
-          Held by the camera move “{owner.label}” from frame {owner.frame}. Turn on Animate (⇧A) to author the
+        // `insp-notice` and NOT `insp-dim`: the dim face is the MONO NUMERAL
+        // one and it sets `white-space: nowrap`, so this two-sentence
+        // explanation was laid out as a single line and clipped at the rail's
+        // edge, so the author saw "Held by the camera move" and none of the two
+        // ways out of it. `insp-dim` is for a value or a unit; a sentence
+        // wraps.
+        <span className="insp-notice" data-testid="camera-held-by">
+          Held by the camera move “{gate.shot.label}” from frame {gate.shot.frame}. Turn on Animate (⇧A) to author the
           move, or put the playhead before it.
         </span>
       )}
+      {gate.kind === "free" && gate.writes === "editsMove" && gate.shot !== undefined && (
+        <span className="insp-notice" data-testid="camera-edits-move">
+          Animate is on: a change here edits the end of the camera move “{gate.shot.label}”.
+        </span>
+      )}
+      {gate.kind === "free" && gate.writes === "newMove" && (
+        <span className="insp-notice" data-testid="camera-new-move">
+          Animate is on: a change here adds a camera move ending at the playhead.
+        </span>
+      )}
+      {(gate.kind === "derived" || gate.kind === "shaped" || gate.kind === "tooEarly") && (
+        <span className="insp-notice" data-testid="camera-gate">
+          {gate.refusal}
+        </span>
+      )}
     </InspectorSection>
   );
 }