@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/inspector/KeyframeDot.tsx

@@ -0,0 +1,373 @@
+// THE KEYFRAME DIAMOND: the inspector's one way to start animating a property,
+// and the only place a track is created.
+//
+// ── ONE WIDGET, THIRTY PATHS ────────────────────────────────────────────
+//
+// It takes a dotted PATH and nothing else, because the path table
+// (`TRACKABLE_PATHS`) already knows the kind, the label, the layer kinds it
+// exists on and the container it needs — so a section adds animation to a row
+// by naming the path it edits, and cannot get the rules for that path wrong in
+// a way the gate would then reject.
+//
+// ── THREE STATES, AND THEY ARE NOT DECORATION ───────────────────────────
+//
+// All three are one 16px button (`.insp-key`, ui/widgets.css) INSIDE the box
+// that shows the value it keys: render it as that field's `trailing`, its
+// accessory lane (a NumberField's, a ColorField's, a labelled InspectorRow's
+// pill), never in a column after the box, so a field that cannot be keyed is
+// exactly as wide as one that can.
+//
+//   keyed    a key sits AT the playhead: a filled `--kf` diamond. Pressing
+//            removes it.
+//   tracked  a track exists, and this frame is between keys: a hollow `--kf`
+//            diamond. Pressing keys the value the layer is holding right now.
+//   rest     no track: a hollow diamond in the third ink. Pressing mints one
+//            from the authored value, which does not move the picture: a
+//            one-key track holds that value at every frame, exactly as the
+//            constant did.
+//
+// The state is `aria-pressed` (keyed is pressed) under ONE constant name,
+// "Keyframe <property>", the way a toggle button speaks. A name that flipped
+// between "Add" and "Remove" said the state twice ("Remove Position keyframe,
+// pressed"); the verb lives in the tooltip.
+//
+// ── A VECTOR'S BOXES EACH CARRY ITS DIAMOND ─────────────────────────────
+//
+// A track is per VECTOR: `transform.position` carries x, y and z in one vec3,
+// so keying any of them keys all three (validate refuses `transform.position`
+// beside `transform.position.z`). So every box that shows a part of one
+// vector carries that vector's diamond, and they light together: Position X,
+// Y and Z each show the position track's state, and a press on any keys the
+// vector. `parts` names the parts in the tooltip ("X, Y and Z key together"),
+// so a diamond in the Y box never reads as Y's own.
+//
+// ── DISABLED WHILE IT CANNOT TELL THE TRUTH ─────────────────────────────
+//
+// Under `LockedControls` (a viewer's panel) it writes nothing. While the
+// transport PLAYS, its state is read off the HELD inspector frame
+// (`useInspectorFrame` holds the readouts during playback) while a press keys
+// the LIVE one, so it is disabled with a tooltip that says why, rather than a
+// button that keys a frame it is not showing. Both keep full strength
+// (widgets.css): a disabled diamond still says whether the property moves.
+//
+// ── AND THE FOURTH: ABSENT ──────────────────────────────────────────────
+//
+// A path this layer cannot carry gets NO button, rather than a dead one. The
+// refusal is the gate's own predicate (`layerTrackRefusal`) plus the device
+// screen rule, so what the chrome offers and what the document accepts are the
+// same set by construction — this lane's autosave-400 rule.
+//
+// ── AND ITS TWIN RIDES ALONG ────────────────────────────────────────────
+//
+// `ExposeDot` sits in the same lane, from the same `path`, so every box that
+// carries a diamond can also publish that property while a definition is open
+// — two edits rather than twenty-six call sites. It asks its OWN refusals (see
+// its header): the two sets overlap and neither contains the other, which is
+// why it is rendered beside the diamond rather than under its eligibility.
+// NOT for a diamond over SEVERAL paths: a pin publishes one target, and the
+// Corner row published only its top-left corner under the name "Radius", so
+// an instance's override moved one corner while the row writes four.
+//
+// ONE PIN PER TRACK, where the diamond is one per box. A pin publishes the
+// whole track, so Position's three boxes each carrying one drew three
+// identical "Publish Position" buttons, and the second accessory squeezed the
+// units out of the Tilt pair at the panel's floor. The vector's FIRST box keeps
+// the pin, and every other box that shows a part of the same track (Y, Z, H,
+// Tilt Y, a fill's Opacity, a stroke's Alpha) passes `pin={false}`. A
+// ControlSpec row's vector (an instance prop, a material parameter) keeps its
+// one pin out of the boxes altogether, in the row's label column (PropRow's
+// `actions`, drawn with `diamond={false}`): its boxes are thirds of the row,
+// and the first one's lane could not hold a diamond and a pin, so the pin was
+// half clipped at the panel's floor. Each box passes `pin={false}`, and
+// `parts` from the axis words its boxes show.
+import { IconDiamond, useLocked } from "@dailies-studio/ui";
+import {
+  deviceScreenDerivesPath,
+  deviceScreenOwnerOf,
+  exposedPropWriting,
+  homeOf,
+  instancePropKeyOf,
+  layerSnapshotContract,
+  layerTrackRefusal,
+  layerTrackablePath,
+  sceneTrackRefusal,
+  sceneTrackablePath,
+  trackablePath,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, Layer3D } from "@dailies-studio/shot/doc";
+import type { Contract, ControlSpec } from "@dailies-studio/contract";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { ExposeDot } from "./ExposeDot.js";
+import { useInspectorFrame, useSelectedLayers } from "./useDocWrite.js";
+
+/** Why a diamond is disabled while the transport runs, as its tooltip. */
+const PLAYING_TITLE = "Pause playback to add or remove a keyframe";
+
+/** The registry's contract for an instance layer, or undefined. Read from the
+ *  store so every `KeyframeDot` call site stays "give me a path" — the
+ *  `instance.props.<key>` family needs a contract to be typed at all, and a
+ *  prop-name argument at forty call sites is how one of them ends up passing the
+ *  wrong one. `InstanceSection` is what puts it in the store (`loadContract`);
+ *  absent, `layerTrackRefusal` falls back to the layer's own snapshot. */
+function contractOf(contracts: Record<string, Contract>, layer: Layer3D): Contract | undefined {
+  return layer.kind === "instance" ? contracts[layer.instance.component] : undefined;
+}
+
+/** The contract's own spec for an `instance.props.<key>` path on this layer,
+ *  or undefined: the live registry's, else the layer's snapshot, the order
+ *  `layerTrackablePath` reads them in. */
+function instanceSpecOf(layer: Layer3D, path: string, live: Contract | undefined): ControlSpec | undefined {
+  const key = instancePropKeyOf(path);
+  if (key === null || layer.kind !== "instance") return undefined;
+  return (live ?? layerSnapshotContract(layer))?.keys[key];
+}
+
+/** "X and Y", "X, Y and Z": a vector's parts as one phrase. */
+function listWords(words: readonly string[]): string {
+  return words.length <= 1 ? (words[0] ?? "") : `${words.slice(0, -1).join(", ")} and ${words[words.length - 1]}`;
+}
+
+/** The tooltip's "X, Y and Z key together.", for a diamond over two or more
+ *  parts; undefined for one, which keys only itself. */
+function togetherOf(parts: readonly string[] | undefined): string | undefined {
+  return parts === undefined || parts.length < 2 ? undefined : `${listWords(parts)} key together.`;
+}
+
+/**
+ * The diamond for one property: render it as the `trailing` of the box that
+ * shows the value (a NumberField's, a ColorField's, a labelled row's).
+ *
+ * `label` overrides what the tooltip calls the property, and defaults to the
+ * table's own. The override exists because a row's wording is sometimes the
+ * SECTION's — the table says "Corner TL" and the row says "TL" — and a tooltip
+ * that disagreed with the control beside it would be worse than a generic one.
+ *
+ * `parts` names what keys together when the diamond sits in a box that shows
+ * one part of a vector (Position's "X", "Y" and "Z"), or over a control that
+ * writes several paths at once (the four corners). The tooltip says so.
+ *
+ * `pin={false}` leaves the expose pin out of this box, for every box of a
+ * vector after the one that carries it (see the header: one pin per track).
+ * `diamond={false}` draws the pin alone, named and typed as it would be beside
+ * the diamond, for a row that carries its track's pin outside the boxes.
+ */
+export function KeyframeDot({
+  path,
+  label,
+  parts,
+  pin = true,
+  diamond = true,
+}: {
+  path: string | readonly string[];
+  label?: string;
+  parts?: readonly string[];
+  pin?: boolean;
+  diamond?: boolean;
+}) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const contracts = useShotEditor((s) => s.contracts);
+  const layers = useSelectedLayers();
+  const { sceneId, sceneFrame } = useInspectorFrame();
+  // ── ONE CONTROL MAY OWN SEVERAL PATHS ─────────────────────────────────────
+  //
+  // Not a convenience: a control that edits four fields at once (the uniform
+  // corner radius writes `tl`/`tr`/`br`/`bl`) has one diamond because it has
+  // one value, and four diamonds would offer an independence the control does
+  // not have. The four are keyed together, in one transaction.
+  const paths = typeof path === "string" ? [path] : path;
+  const first = paths[0];
+  // The table's ENTRY, or — for a contract-driven path, which no table knows —
+  // the FIRST selected layer's spec. Callers that pass `label` skip both for the
+  // wording.
+  const tabled = first === undefined ? undefined : (trackablePath(first) ?? undefined);
+  const live = layers[0] === undefined ? undefined : contractOf(contracts, layers[0]);
+  const fromContract =
+    first === undefined || layers[0] === undefined
+      ? undefined
+      : (layerTrackablePath(layers[0], first, live, doc?.materials) ?? undefined);
+  const name = label ?? tabled?.label ?? fromContract?.label ?? first ?? "";
+  // THE KIND THE PIN STORES is the contract vocabulary, so a published prop is
+  // drawn by the control it was published from. For `instance.props.<key>`
+  // that is the CONTRACT's kind (an enum, an asset, a curve), never the kind
+  // its track keys as: `contractTrackablePath` types an asset or a curve as a
+  // "string" track, and a prop minted with it was a text box over an asset id
+  // or a curve's JSON. A material parameter's entry already speaks it.
+  const exposedKind =
+    (first === undefined || layers[0] === undefined ? undefined : instanceSpecOf(layers[0], first, live)?.kind) ??
+    tabled?.kind ??
+    fromContract?.kind;
+  const together = togetherOf(parts);
+
+  if (doc === null || sceneId === null || layers.length === 0 || first === undefined) return null;
+  // EVERY selected layer has to be able to carry it. A diamond that keyed three
+  // of four would be a control whose effect depends on a selection the author
+  // is not looking at.
+  const eligible = layers.every((layer) =>
+    paths.every((p) => keyframeRefusal(doc, sceneId, layer, p, contractOf(contracts, layer)) === null),
+  );
+
+  const tracked = layers.some((layer) => paths.some((p) => layer.tracks?.[p] !== undefined));
+  const keyed =
+    tracked &&
+    layers.every((layer) =>
+      paths.every((p) => layer.tracks?.[p]?.keyframes.some((k) => k.frame === sceneFrame) === true),
+    );
+
+  // ── THE TWO VERBS SHARE THE LANE, AND NOT THE ELIGIBILITY ─────────────────
+  //
+  // The pin is rendered BESIDE the diamond rather than after an early return,
+  // and that is not tidiness: the two refusals are genuinely different sets.
+  // `keyframeRefusal` rejects any path the trackable table does not hold and
+  // any layer kind it does not list, while `exposeProp` asks only for a
+  // resolvable default and no colliding track — so a path with no table row
+  // (a section may name a plain authored field) is publishable while being
+  // unkeyable. Gating the pin behind the diamond would have hidden exactly
+  // those.
+  //
+  // `ExposeDot` returns null on its own outside a definition, so in the shot
+  // context this renders nothing, and the box's lane hides itself empty.
+  //
+  // A diamond over several paths is named by ALL of them: under the first
+  // alone, Media's Zoom (the four crop edges) took Crop X's test id, so a
+  // lookup by that id found the button that keys all four.
+  return (
+    <>
+      {eligible && diamond ? (
+        <Diamond
+          id={paths.join("+")}
+          name={name}
+          tracked={tracked}
+          keyed={keyed}
+          {...(together === undefined ? {} : { together })}
+          onToggle={() => store.toggleKeyframe(paths)}
+        />
+      ) : null}
+      {pin && paths.length === 1 ? <ExposeDot path={first} label={name} kind={exposedKind} /> : null}
+    </>
+  );
+}
+
+/**
+ * The same diamond with the SHOT as its subject: its background colour and its
+ * post stack (P5).
+ *
+ * A second component rather than a flag, because nothing about the subject is
+ * shared — a different path table, a different refusal, a different store verb,
+ * and no fan-out at all (a shot is one subject however many layers are
+ * selected). What IS shared is every pixel of the control, which is `Diamond`.
+ *
+ * ── ABSENT, NOT DEAD, ON AN EFFECT THAT IS OFF ──────────────────────────
+ *
+ * `sceneTrackRefusal` refuses `effects.bloom.strength` while `bloom` is
+ * undefined, and the row it would sit in is not rendered then either (the
+ * toggle hides its params). Asked anyway, because the toggle and the table are
+ * two different lists and this is the one the save gate reads.
+ *
+ * `parts` is `KeyframeDot`'s: the parts of a vector its one track keys (a
+ * grade's R, G and B, a ray centre's X and Y), which the tooltip says key
+ * together.
+ */
+export function SceneKeyframeDot({ path, label, parts }: { path: string; label?: string; parts?: readonly string[] }) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const editingDef = useShotEditor((s) => s.editingDef);
+  const sceneId = useShotEditor((s) => s.sceneId);
+  const { sceneFrame } = useInspectorFrame();
+  const name = label ?? (sceneTrackablePath(path)?.label ?? path);
+  const scene = doc === null || sceneId === null ? undefined : doc.scenesById[sceneId];
+  // A DEFINITION HAS NEITHER. `useInspectorFrame` reports the def-local clock
+  // while one is open, so a diamond drawn here would key the shot under the
+  // playhead at a frame from a different timeline.
+  if (scene === undefined || editingDef !== null) return null;
+  if (sceneTrackRefusal(scene, path) !== null) return null;
+
+  const track = scene.tracks?.[path];
+  const keyed = track?.keyframes.some((k) => k.frame === sceneFrame) === true;
+  const together = togetherOf(parts);
+  return (
+    <Diamond
+      id={path}
+      name={name}
+      tracked={track !== undefined}
+      keyed={keyed}
+      {...(together === undefined ? {} : { together })}
+      onToggle={() => store.toggleSceneKeyframe([path])}
+    />
+  );
+}
+
+/** The control itself. One look, one wording, one set of states — so a shot
+ *  property and a layer property cannot end up reading differently. */
+function Diamond({
+  id,
+  name,
+  tracked,
+  keyed,
+  together,
+  onToggle,
+}: {
+  /** What its test id names: the path it keys, or every path, `+`-joined. */
+  id: string;
+  name: string;
+  tracked: boolean;
+  keyed: boolean;
+  /** "X, Y and Z key together.", for a diamond over the parts of one vector:
+   *  a box that shows one of them, or one box that shows them all. */
+  together?: string;
+  onToggle: () => void;
+}) {
+  const locked = useLocked();
+  const playing = useShotEditor((s) => s.playing);
+  const verb = keyed
+    ? `Remove the ${name} keyframe at this frame`
+    : tracked
+      ? `Keyframe ${name} here: it is animated, and this frame is between keys`
+      : `Animate ${name}: the first keyframe takes the value it already has, so nothing moves`;
+  return (
+    <button
+      type="button"
+      className={`insp-key${keyed ? " is-keyed" : tracked ? " is-tracked" : ""}`}
+      data-testid={`keyframe-dot-${id}`}
+      aria-label={`Keyframe ${name}`}
+      aria-pressed={keyed}
+      title={playing ? PLAYING_TITLE : together === undefined ? verb : `${verb}. ${together}`}
+      disabled={locked || playing}
+      onClick={onToggle}
+    >
+      <IconDiamond filled={keyed} />
+    </button>
+  );
+}
+
+/**
+ * Why this layer cannot carry a track on this path, or null.
+ *
+ * The GATE'S OWN predicate, plus the one rule that is not a property of the
+ * document: `applyDeviceScreen` derives a screen child's position, size and
+ * corners at render time and strips their tracks, so a keyframe there would
+ * save, validate, sample, and move nothing.
+ *
+ * Kept in step with `trackOps`' copy by both reading `layerTrackRefusal` and
+ * `deviceScreenDerivesPath` — the affordance and the op ask the same two
+ * questions, in the same order, of the same functions.
+ */
+function keyframeRefusal(
+  doc: Doc3D,
+  containerId: string,
+  layer: Layer3D,
+  path: string,
+  live?: Contract | undefined,
+): string | null {
+  const own = layerTrackRefusal(layer, path, live, doc.materials);
+  if (own !== null) return own;
+  // An exposed prop drives its target through the same `writeAtPath` a track
+  // substitutes with, so validate refuses both owning one path. Asked here too,
+  // or the diamond offers a keyframe the save rejects.
+  const exposed = exposedPropWriting(doc, containerId, layer.id, path);
+  if (exposed !== null) return `driven by the "${exposed.label}" property`;
+  if (!deviceScreenDerivesPath(path)) return null;
+  const home = homeOf(doc, containerId);
+  const owner = home === null ? null : deviceScreenOwnerOf(home, layer.id);
+  return owner === null ? null : `derived from "${owner.label}"`;
+}

package/src/panels/inspector/KeyframeSection.tsx

@@ -0,0 +1,257 @@
+// THE FOCUSED KEYFRAME'S EASING — this lane's adapter over the shared
+// `@dailies-studio/timeline` `KeyframeEditor` (a single key's Frame and Value
+// fields, preset palette, bezier pad, spring stiffness/damping/mass, live
+// engine-sampled preview).
+//
+// ── WHY THIS FILE EXISTS AT ALL ────────────────────────────────────────────
+//
+// The component was finished, tested and mounted in the legacy editor, and this
+// lane never mounted it. The cost was not cosmetic: the dock's diamond menu can
+// pick the SPRING preset but nothing anywhere could edit a spring's parameters,
+// so every keyframe spring in every shot document was `SPRING_DEFAULT`
+// (170/26/1) forever — while a BLOCK, one panel away, got the full editor. Two
+// ease models with two levels of access is exactly the drift `EASE_PRESETS`
+// being one shared table exists to prevent.
+//
+// ── WRITTEN FOR A SET, AND NOW HOLDING ONE ─────────────────────────────────
+//
+// `addresses` is the store's whole selection and every derivation below folds
+// over it (`every` for the two kind facts, `map` for the eases and refs), which
+// is what the shared component's contract has always been (`refs:
+// KeyframeAddr[]`, `setEase(refs, …)`). It was written this way while the store
+// still held one, so widening that field cost this file a single line.
+//
+// The one thing that stays single-subject is the PREVIEW: a settle curve is a
+// picture of one segment, and drawing four over each other says nothing.
+//
+// ── THE KIND RULES ARE THE ENGINE'S, NEVER A HAND-COPY ─────────────────────
+//
+// `springable` and `allDiscrete` come from `SPRINGABLE_KINDS` / `DISCRETE_KINDS`
+// so the palette cannot offer what `evaluateTrack` refuses — a spring on a
+// `quaternion` track (reachable through `instance.props.<key>`) THROWS in the
+// sampler, and the ops layer refuses that write. An affordance that disagrees
+// with the gate is the defect this rule removes.
+import { useRef } from "react";
+import { DEFAULT_SHOT_FPS, homeOf, sampleTrackAt, trackablePath } from "@dailies-studio/shot/doc";
+import type { ShotTrack } from "@dailies-studio/shot/doc";
+import { DISCRETE_KINDS, SPRINGABLE_KINDS } from "@dailies-studio/engine";
+import type { Ease, Keyframe, Rational, Value } from "@dailies-studio/engine";
+import { KeyframeEditor, keyframeAddrKey } from "@dailies-studio/timeline";
+import type { KeyframeAddr, KeyframeFieldsView, KeyframeSelectionView } from "@dailies-studio/timeline";
+import { InspectorSection } from "@dailies-studio/ui";
+import { useShotEditor, useStore } from "../../state/context.js";
+import type { CurveKeyRef, CurveOp } from "../../state/types.js";
+import { unitOf } from "../timeline/curveModel.js";
+import { timecode } from "../timeline/model.js";
+
+/** How many points the preview polyline samples over one segment. The shared
+ *  component draws whatever it is handed. */
+const PREVIEW_SAMPLES = 96;
+
+/** One resolved address: where it points, and what it points AT. */
+interface Entry {
+  /** The address as the store holds it — position-keyed, which is what every
+   *  keyframe verb in this lane already takes. */
+  at: { containerId: string; layerId: string | null; path: string; frame: number };
+  track: ShotTrack;
+  kf: Keyframe;
+}
+
+/**
+ * The row id the shared component addresses a key by. It never leaves this
+ * file — `mapAt` turns it straight back into a store address — so it only has
+ * to be unique within the selection, and (container, layer, path) is exactly
+ * the track's identity.
+ */
+function rowIdOf(at: Entry["at"]): string {
+  return `${at.containerId}|${at.layerId ?? ""}|${at.path}`;
+}
+
+export function KeyframeSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const addresses = useShotEditor((s) => s.selectedKeyframes);
+  // A STATE SLICE OR NULL, never a fresh fallback object:
+  // a selector minting `{num,den}` per call is never Object.is-stable and spins
+  // useSyncExternalStore. The fallback is `DEFAULT_SHOT_FPS`, the timebase a
+  // fresh document is created at, rather than a third copy of those two numbers.
+  const fps = useShotEditor((s) => s.doc?.fps ?? null) ?? DEFAULT_SHOT_FPS;
+  // Whether the open block-drag scrub is OURS. A ref, not a local: the adapter
+  // below is rebuilt every render and a Frame scrub re-renders on each capture.
+  const ownsDrag = useRef(false);
+
+  if (doc === null) return null;
+
+  const entries: Entry[] = [];
+  for (const at of addresses) {
+    // TWO SUBJECTS, TWO HOMES. A layer's tracks come through `homeOf`, so a
+    // keyframe inside an open component DEFINITION resolves exactly as one in
+    // a shot does. A `layerId: null` address is the SHOT ITSELF, whose tracks
+    // hang off the scene — a definition has no scene-level tracks at all,
+    // which is why this arm reads `scenesById` and not the home.
+    const track: ShotTrack | undefined =
+      at.layerId === null
+        ? doc.scenesById[at.containerId]?.tracks?.[at.path]
+        : homeOf(doc, at.containerId)?.layersById[at.layerId]?.tracks?.[at.path];
+    const kf = track?.keyframes.find((k) => k.frame === at.frame);
+    if (track !== undefined && kf !== undefined) entries.push({ at, track, kf });
+  }
+  // AN UNRESOLVABLE ADDRESS RENDERS NOTHING rather than an empty frame: the key
+  // can be deleted, undone away or have its layer deselected while this is
+  // mounted, and a heading over no controls would outlive its subject.
+  if (entries.length === 0) return null;
+
+  const refs: KeyframeAddr[] = entries.map((e) => ({ rowId: rowIdOf(e.at), keyframeId: e.kf.id }));
+  const byKey = new Map<string, Entry>(entries.map((e) => [keyframeAddrKey({ rowId: rowIdOf(e.at), keyframeId: e.kf.id }), e]));
+  const mapAt = (addrs: readonly KeyframeAddr[]): Entry["at"][] =>
+    addrs.flatMap((a) => {
+      const e = byKey.get(keyframeAddrKey(a));
+      return e === undefined ? [] : [e.at];
+    });
+  /** The same address as the store's curve ops take it: by keyframe ID, which
+   *  is what lets a frame edit move the key without losing track of it. */
+  const keyOf = (a: KeyframeAddr): CurveKeyRef | null => {
+    const e = byKey.get(keyframeAddrKey(a));
+    return e === undefined
+      ? null
+      : { containerId: e.at.containerId, layerId: e.at.layerId, path: e.at.path, keyframeId: e.kf.id };
+  };
+
+  const selection: KeyframeSelectionView = {
+    eases: entries.map((e) => e.kf.easeOut),
+    allDiscrete: entries.every((e) => DISCRETE_KINDS.has(e.track.kind)),
+    springable: entries.every((e) => SPRINGABLE_KINDS.has(e.track.kind)),
+    refs,
+    preview: previewFor(entries.length === 1 ? entries[0]! : null, fps),
+  };
+  const fields = fieldsFor(entries.length === 1 ? entries[0]! : null);
+
+  /** One ease write on every target, as ONE undo step. The store verb is the
+   *  same one the dock's diamond menu calls, so the panel and the menu cannot
+   *  disagree about what setting an ease does. */
+  const writeEase = (targets: readonly Entry["at"][], ease: Ease) => store.setKeyframesEase(targets, ease);
+
+  return (
+    <InspectorSection className="insp-object" title={headingFor(entries, fps)} persistKey="shot:keyframe">
+      <KeyframeEditor
+        selection={selection}
+        fields={fields}
+        setEase={(r, ease) => writeEase(mapAt(r), ease)}
+        gesture={{
+          // ── THE GRAPH'S GESTURE, NOT THE INSPECTOR SCRUB ──────────────────
+          //
+          // The pads emit `setEase`, and the Frame and Value fields emit `move`
+          // and `setValue`: the same three ops a graph drag does, so they take
+          // the same store lane (`captureCurveOps`). That lane matters for the
+          // Frame field. The selection is position-keyed, and the inspector
+          // scrub does not carry it along a move, so the first step of a Frame
+          // drag left the selection on an empty frame and unmounted this
+          // section under the pointer. `captureCurveOps` relocates the
+          // selection with the key, and its cancel restores it.
+          //
+          // Every capture still re-derives from the scrub's BASE, which is what
+          // makes the whole drag one undo entry and Escape exact.
+          //
+          // OWNERSHIP IS CHECKED, because this lane has no inspector guard. A
+          // typed commit lands on blur, and a press on a dock bar opens that
+          // bar's drag BEFORE the field blurs. Without the check the typed op
+          // was captured into the bar's scrub and `end(true)` committed and
+          // closed it under the bar's pointer. A refused begin now makes the
+          // capture and the end no-ops, so the typed value is dropped instead.
+          begin: () => {
+            ownsDrag.current = store.beginBlockDrag();
+          },
+          capture: (ops) => {
+            if (!ownsDrag.current) return;
+            const mapped: CurveOp[] = [];
+            for (const op of ops) {
+              if (op.kind === "setValue") {
+                const key = keyOf(op.ref);
+                if (key !== null) mapped.push({ kind: "setValue", key, value: op.value });
+                continue;
+              }
+              const keys = op.refs.map(keyOf).filter((k): k is CurveKeyRef => k !== null);
+              if (keys.length === 0) continue;
+              mapped.push(
+                op.kind === "move"
+                  ? { kind: "move", keys, deltaFrames: op.deltaFrames, ...(op.snap === undefined ? {} : { snap: op.snap }) }
+                  : { kind: "setEase", keys, ease: op.ease },
+              );
+            }
+            store.captureCurveOps(mapped);
+          },
+          end: (commit) => {
+            if (!ownsDrag.current) return;
+            ownsDrag.current = false;
+            store.endBlockDrag(commit);
+          },
+        }}
+      />
+    </InspectorSection>
+  );
+}
+
+/**
+ * The single-selection Frame and Value fields, or null for a set.
+ *
+ * Value is for a plain `number` track only. A vector's components and a
+ * colour's channels have no one number to show, and the ops layer's
+ * `setValue` writes a vector only through a named component, which this
+ * address does not carry. The Frame field still applies to every kind.
+ */
+function fieldsFor(single: Entry | null): KeyframeFieldsView | null {
+  if (single === null) return null;
+  const { at, track, kf } = single;
+  const v = kf.value;
+  return {
+    ref: { rowId: rowIdOf(at), keyframeId: kf.id },
+    frame: kf.frame,
+    value: track.kind === "number" && typeof v === "number" ? v : null,
+    // THE CURVE PANE'S OWN RULE, so the field and the graph's axis cannot
+    // name two different units for one property.
+    ...unitOf(at.path),
+  };
+}
+
+/** "Opacity at 0:00.12" for one key, "3 keyframes" for a set. The path's own
+ *  label through `trackablePath`, so the heading names the property the way the
+ *  inspector row and the dock row both already name it; the position is
+ *  timecode, like every other position. */
+function headingFor(entries: readonly Entry[], fps: Rational): string {
+  if (entries.length !== 1) return `${entries.length} keyframes`;
+  const e = entries[0]!;
+  const label = trackablePath(e.at.path)?.label ?? e.at.path;
+  return `${label} at ${timecode(e.kf.frame, fps)}`;
+}
+
+/**
+ * The single-selection segment preview, or null.
+ *
+ * Number tracks only, and only with a NEXT key — an ease governs the segment
+ * LEAVING its keyframe, so the last key has no curve to draw (and writing its
+ * ease changes nothing, which the dock's menu says out loud). Sampled through
+ * `sampleTrackAt`, the engine's own sampler, so a spring's overshoot in this
+ * preview is the overshoot the export renders.
+ */
+function previewFor(single: Entry | null, fps: Rational): KeyframeSelectionView["preview"] {
+  if (single === null || single.track.kind !== "number") return null;
+  const { track, kf } = single;
+  const i = track.keyframes.findIndex((k) => k.id === kf.id);
+  const next = i < 0 ? undefined : track.keyframes[i + 1];
+  if (next === undefined) return null;
+  return {
+    fromFrame: kf.frame,
+    toFrame: next.frame,
+    isSpring: kf.easeOut.type === "spring",
+    sample: (from, to, n) => {
+      const out: { frame: number; value: number }[] = [];
+      const steps = Math.max(1, Math.min(n, PREVIEW_SAMPLES));
+      for (let s = 0; s <= steps; s += 1) {
+        const frame = from + ((to - from) * s) / steps;
+        const v: Value | undefined = sampleTrackAt(track, frame, fps);
+        out.push({ frame, value: typeof v === "number" ? v : 0 });
+      }
+      return out;
+    },
+  };
+}