@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/isolationTrail.ts

@@ -0,0 +1,92 @@
+// The isolation trail: which layers sit above the isolated one, whether
+// anything inside it is drawing at the playhead, and whether it can take an
+// insert. The stage header's breadcrumb (IsolationTrail.tsx) reads the first
+// two. One walk, so the header and anything else that names the path cannot
+// disagree about it.
+import {
+  canHoldChildren,
+  layerAliveAt,
+  layerChildren,
+  parentOf,
+  sceneStart,
+  type Layer3D,
+} from "@dailies-studio/shot/doc";
+import { wordFor } from "../layerWords.js";
+import type { ShotEditorState } from "./types.js";
+
+type Lookup = { layersById: Record<string, Layer3D> };
+
+/** The isolated layer and every ancestor above it, outermost first. The path
+ *  the breadcrumb walks, and the reason entering a nested subtree is reversible
+ *  one level at a time. Bounded by the layer count, so a corrupt parent cycle
+ *  ends instead of hanging the chrome. */
+export function crumbsFor(scene: Lookup, id: string): string[] {
+  const out: string[] = [];
+  const limit = Object.keys(scene.layersById).length;
+  let at: string | null = id;
+  for (let i = 0; at !== null && i <= limit; i += 1) {
+    out.push(at);
+    at = parentOf(scene as never, at);
+  }
+  return out.reverse();
+}
+
+/**
+ * True when the isolated subtree draws nothing at the playhead: the layer or
+ * an ancestor is outside its lifespan (or hidden), or every leaf under it is.
+ * The pane is then uniformly dimmed with nothing to click, and the breadcrumb
+ * says why instead of letting the mode read as broken.
+ *
+ * A selector returning a boolean, so a subscriber re-renders only when the
+ * answer flips, not on every playback frame. An empty container counts as on
+ * screen: there is nothing to be missing.
+ */
+export function isolationOffscreen(s: ShotEditorState): boolean {
+  if (s.doc === null || s.isolation === null || s.editingDef !== null || s.sceneId === null) {
+    return false;
+  }
+  const scene = s.doc.scenesById[s.sceneId];
+  if (scene === undefined || scene.layersById[s.isolation] === undefined) return false;
+  const start = sceneStart(s.doc, s.sceneId);
+  if (start === null) return false;
+  const frame = s.frame - start;
+  if (frame < 0 || frame >= scene.durationFrames) return true;
+  const chain = crumbsFor(scene, s.isolation);
+  for (const id of chain.slice(0, -1)) {
+    const layer = scene.layersById[id];
+    if (layer !== undefined && !layerAliveAt(layer, frame)) return true;
+  }
+  const draws = (id: string): boolean => {
+    const layer = scene.layersById[id];
+    if (layer === undefined || !layerAliveAt(layer, frame)) return false;
+    const kids = layerChildren(layer);
+    return kids.length === 0 || kids.some(draws);
+  };
+  return !draws(s.isolation);
+}
+
+/**
+ * Why nothing can be added while `layer` is the isolation subject, or null
+ * when it can take children (or there is no subject).
+ *
+ * Everything outside the isolated subtree is dimmed and unpickable, so an
+ * insert that fell back to the scene root used to land where the author could
+ * neither see nor click it. A leaf subject refuses instead, with the reason.
+ * `insertContext` reports it, and the tool dock and the Use buttons render it
+ * as their disabled reason, so a refused click is never a surprise.
+ */
+export function leafInsertRefusal(layer: Layer3D | undefined): string | null {
+  if (layer === undefined || canHoldChildren(layer)) return null;
+  const word = wordFor(layer);
+  const noun = word === word.toUpperCase() ? word : word.toLowerCase();
+  return `Can't add inside this ${noun}. Only groups, devices and cloners hold layers.`;
+}
+
+/** `leafInsertRefusal` for the isolation the stage is showing. A string or
+ *  null, so a selector over it allocates nothing. */
+export function isolationInsertRefusal(
+  s: Pick<ShotEditorState, "doc" | "sceneId" | "isolation" | "editingDef">,
+): string | null {
+  if (s.doc === null || s.isolation === null || s.editingDef !== null || s.sceneId === null) return null;
+  return leafInsertRefusal(s.doc.scenesById[s.sceneId]?.layersById[s.isolation]);
+}

package/src/state/keyMoves.ts

@@ -0,0 +1,134 @@
+// MOVING SEVERAL KEYFRAMES AT ONCE, each by its own distance. The keyboard
+// nudge moves a selection rigidly; the ⌥-drag stagger fans it out; the stretch
+// bracket scales it about its far end. Each is one
+// pure write over the document, so the store verb around each is only the
+// bracket (an `edit` for the nudge, a scrub capture for the drag).
+import { homeOf, moveLayerKeyframe, moveSceneKeyframe } from "@dailies-studio/shot/doc";
+import { retimeLandings, retimeMinFactor } from "@dailies-studio/timeline";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import type { KeyframeSel } from "./types.js";
+
+export interface KeyMove {
+  key: KeyframeSel;
+  to: number;
+}
+
+const trackOf = (k: KeyframeSel): string => `${k.containerId}|${k.layerId ?? ""}|${k.path}`;
+
+/**
+ * Move every key in `moves` to its `to`, or refuse the whole set.
+ *
+ * REFUSED WHOLE ON ANY COLLISION: a key landing on a key that is not moving
+ * away, or two keys landing on one frame of one track, would replace a key with
+ * nothing on screen having said so. A frame below 0 refuses too.
+ *
+ * ORDER MATTERS INSIDE THE WRITE: a key may only land once the key that sat on
+ * its target has left, or the earlier one replaces the later. Each pass moves
+ * every key whose target is free, so a rigid nudge goes front to back in its own
+ * direction and a fan goes outward.
+ */
+export function moveKeyRefs(doc: Doc3D, moves: readonly KeyMove[]): { doc: Doc3D; refusal: string | null } {
+  const live = moves.filter((m) => m.to !== m.key.frame);
+  if (live.length === 0) return { doc, refusal: null };
+  const leaving = new Set(live.map((m) => `${trackOf(m.key)}|${m.key.frame}`));
+  const landing = new Set<string>();
+  for (const { key, to } of live) {
+    if (to < 0) return { doc, refusal: "That would put a keyframe before frame 0." };
+    const at = `${trackOf(key)}|${to}`;
+    const tracks =
+      key.layerId === null
+        ? doc.scenesById[key.containerId]?.tracks
+        : homeOf(doc, key.containerId)?.layersById[key.layerId]?.tracks;
+    const occupied = tracks?.[key.path]?.keyframes.some((other) => other.frame === to) === true;
+    if ((occupied && !leaving.has(at)) || landing.has(at))
+      return { doc, refusal: "That would drop a keyframe onto another one. Nothing was moved." };
+    landing.add(at);
+  }
+  let next = doc;
+  let pending = live;
+  while (pending.length > 0) {
+    const sitting = new Set(pending.map((m) => `${trackOf(m.key)}|${m.key.frame}`));
+    const ready = pending.filter((m) => !sitting.has(`${trackOf(m.key)}|${m.to}`));
+    // A cycle (two keys swapping places) cannot be written one move at a time.
+    if (ready.length === 0) return { doc, refusal: "Those keyframes would swap places. Nothing was moved." };
+    for (const { key, to } of ready)
+      next =
+        key.layerId === null
+          ? moveSceneKeyframe(next, key.containerId, key.path, key.frame, to)
+          : moveLayerKeyframe(next, key.containerId, key.layerId, key.path, key.frame, to);
+    pending = pending.filter((m) => !ready.includes(m));
+  }
+  return { doc: next, refusal: null };
+}
+
+/**
+ * Where a stagger of `keys` by `step` sends each one.
+ *
+ * SEVERAL LAYERS: each layer's keys move together, so their spacing stays, and
+ * the layers are ranked by their earliest selected key. ONE LAYER: the keys
+ * keys are ranked by distinct frame, so keys sharing a frame move together.
+ * Rank i moves `i * step`.
+ */
+export function keyStaggerMoves(keys: readonly KeyframeSel[], step: number): KeyMove[] {
+  const groups = new Map<string, KeyframeSel[]>();
+  for (const k of keys) {
+    const id = `${k.containerId}|${k.layerId ?? ""}`;
+    groups.set(id, [...(groups.get(id) ?? []), k]);
+  }
+  if (groups.size > 1) {
+    const earliest = (g: readonly KeyframeSel[]): number => Math.min(...g.map((k) => k.frame));
+    const ranked = [...groups.values()].sort((a, b) => earliest(a) - earliest(b));
+    return ranked.flatMap((g, i) => g.map((key) => ({ key, to: key.frame + i * step })));
+  }
+  // Rank distinct frames, not keys: keys on one frame (a pose across tracks)
+  // stay together.
+  const frames = [...new Set(keys.map((k) => k.frame))].sort((a, b) => a - b);
+  return [...keys]
+    .sort((a, b) => a.frame - b.frame)
+    .map((key) => ({ key, to: key.frame + frames.indexOf(key.frame) * step }));
+}
+
+/** What a stretch of the selection does: every key's move, and the factor it
+ *  landed on (the chip's readout). */
+export interface KeyStretch {
+  moves: KeyMove[];
+  factor: number;
+}
+
+/**
+ * Where a STRETCH of `keys` sends each one: the selection's frames scaled
+ * about its far end, so the edge grabbed moves by `deltaFrames` and the other
+ * stays put. Graph mode's retime bracket, over keys on any tracks and layers.
+ *
+ * In the dock's frames (a Shot's keys plus its start, `offsetOf`), so keys in
+ * two Shots stretch about one anchor. The factor stops where two keys of one
+ * track would round onto one frame (`retimeMinFactor`) and where a key would
+ * cross its container's frame 0; null when even that factor collides, or the
+ * selection spans one frame.
+ */
+export function keyStretchMoves(
+  keys: readonly KeyframeSel[],
+  edge: "left" | "right",
+  deltaFrames: number,
+  offsetOf: (containerId: string) => number,
+): KeyStretch | null {
+  const placed = keys.map((key) => ({ key, at: key.frame + offsetOf(key.containerId) }));
+  if (placed.length < 2) return null;
+  const min = Math.min(...placed.map((p) => p.at));
+  const max = Math.max(...placed.map((p) => p.at));
+  if (min === max) return null;
+  const anchor = edge === "left" ? max : min;
+  const grab = edge === "left" ? min : max;
+  const byTrack = new Map<string, typeof placed>();
+  for (const p of placed) byTrack.set(trackOf(p.key), [...(byTrack.get(trackOf(p.key)) ?? []), p]);
+  const tracks = [...byTrack.values()];
+  let factor = Math.max(retimeMinFactor(tracks.map((t) => t.map((p) => p.at))), (grab + deltaFrames - anchor) / (grab - anchor));
+  // No key before its own container's frame 0: only keys below the anchor can.
+  for (const p of placed) {
+    if (p.at < anchor) factor = Math.min(factor, (anchor - offsetOf(p.key.containerId)) / (anchor - p.at));
+  }
+  const landed = retimeLandings(tracks.map((t) => t.map((p) => p.at)), anchor, factor);
+  if (landed === null) return null;
+  const moves = tracks.flatMap((t, i) => t.map((p, j) => ({ key: p.key, to: landed[i]![j]! - offsetOf(p.key.containerId) })));
+  return { moves, factor };
+}

package/src/state/keyframeClipboard.ts

@@ -0,0 +1,177 @@
+// The keyframe clipboard: a selection out, the same motion back in somewhere
+// else.
+//
+// ── WHAT A CLIP IS, AND WHY IT IS RELATIVE ────────────────────────────────
+//
+// Copying keys and pasting them at the playhead is the single most common way
+// an author reuses motion — the same punch on a second card, the same settle on
+// a whole row of them. So a clip stores frames RELATIVE to the earliest key in
+// the whole clip, never absolute ones: paste puts that earliest key on the
+// playhead and everything else keeps its spacing, which is what makes a
+// two-track clip (a position and an opacity that were meant to land together)
+// arrive still in sync.
+//
+// The anchor is clip-wide rather than per track for exactly that reason. Per
+// track, every track's first key would land on the playhead and a deliberate
+// offset between two of them would be flattened out.
+//
+// ── IN MEMORY, NOT ON THE SYSTEM CLIPBOARD ────────────────────────────────
+//
+// `graphClipboard` encodes to text because a material graph is worth carrying
+// between browser tabs. Keyframes are not: they are meaningless without the
+// track kinds and paths they came from, and the realistic gesture is "copy this
+// bounce onto that layer" inside one session. A store field is the whole
+// transport. The codec is still split out here so the upgrade path is a
+// `JSON.stringify` and a format tag, exactly as `MATERIAL_CLIP_FORMAT` does.
+import type { Ease, TrackKind, Value, Vec2, Vec3 } from "@dailies-studio/engine";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { homeOf } from "@dailies-studio/shot/doc";
+import type { KeyframeSel } from "./types.js";
+
+/** One track's worth of copied keys, with the path and kind they came from. */
+export interface KeyframeClipTrack {
+  path: string;
+  /** The SOURCE track's kind. Paste refuses a target whose kind differs — see
+   *  `pasteTargets`. */
+  kind: TrackKind;
+  /** The source track was a bezier path, so its keys' handles (offsets from
+   *  the key's value, no rebasing needed) say exactly what the source said:
+   *  an absent side is a cleared side. */
+  bezier?: true;
+  keys: readonly ClipKey[];
+}
+
+/** One copied key. The handles are present only when the source track is a
+ *  bezier path and the key has them. */
+export interface ClipKey {
+  relFrame: number;
+  value: Value;
+  easeOut: Ease;
+  spatialIn?: Vec2 | Vec3;
+  spatialOut?: Vec2 | Vec3;
+}
+
+/** A clip key without its frame: what is held per (track, frame). */
+type HeldKey = Omit<ClipKey, "relFrame">;
+
+export interface KeyframeClip {
+  version: 1;
+  tracks: readonly KeyframeClipTrack[];
+}
+
+/**
+ * Read a selection out of the document into a clip, or null when it holds
+ * nothing copyable.
+ *
+ * Grouped by (container, layer, path) because that is a TRACK, and a clip's
+ * unit is a track: two keys on `transform.position` are one row of the clip,
+ * and the same frame on `transform.opacity` is another.
+ */
+export function copyKeyframes(doc: Doc3D, selection: readonly KeyframeSel[]): KeyframeClip | null {
+  const byTrack = new Map<string, { path: string; kind: TrackKind; bezier: boolean; frames: number[] }>();
+  const valueAt = new Map<string, HeldKey>();
+
+  for (const at of selection) {
+    const tracks =
+      at.layerId === null
+        ? doc.scenesById[at.containerId]?.tracks
+        : homeOf(doc, at.containerId)?.layersById[at.layerId]?.tracks;
+    const track = tracks?.[at.path];
+    const key = track?.keyframes.find((k) => k.frame === at.frame);
+    if (track === undefined || key === undefined) continue;
+    const id = `${at.containerId}|${at.layerId ?? ""}|${at.path}`;
+    const row = byTrack.get(id) ?? {
+      path: at.path,
+      kind: track.kind,
+      bezier: track.spatialInterp?.type === "bezier",
+      frames: [],
+    };
+    row.frames.push(at.frame);
+    byTrack.set(id, row);
+    valueAt.set(`${id}|${at.frame}`, {
+      value: key.value,
+      easeOut: key.easeOut,
+      ...(row.bezier && key.spatialIn !== undefined ? { spatialIn: [...key.spatialIn] as Vec2 | Vec3 } : {}),
+      ...(row.bezier && key.spatialOut !== undefined ? { spatialOut: [...key.spatialOut] as Vec2 | Vec3 } : {}),
+    });
+  }
+  if (byTrack.size === 0) return null;
+
+  // THE ANCHOR IS THE WHOLE CLIP'S EARLIEST FRAME — see the header.
+  let anchor = Number.POSITIVE_INFINITY;
+  for (const row of byTrack.values()) for (const f of row.frames) anchor = Math.min(anchor, f);
+
+  const tracks: KeyframeClipTrack[] = [];
+  for (const [id, row] of byTrack) {
+    const keys = row.frames
+      .slice()
+      .sort((a, b) => a - b)
+      .flatMap((frame) => {
+        const held = valueAt.get(`${id}|${frame}`);
+        return held === undefined ? [] : [{ relFrame: frame - anchor, ...held }];
+      });
+    if (keys.length > 0) tracks.push({ path: row.path, kind: row.kind, ...(row.bezier ? { bezier: true as const } : {}), keys });
+  }
+  return tracks.length === 0 ? null : { version: 1, tracks };
+}
+
+/** One track of a clip, aimed at a subject, with the frames it will write. */
+export interface PasteTarget {
+  path: string;
+  /** Copied off a bezier path: see `KeyframeClipTrack.bezier`. */
+  bezier?: true;
+  keys: readonly ({ frame: number } & HeldKey)[];
+}
+
+/**
+ * Where a clip lands on `subject`, and what it cannot.
+ *
+ * ── KIND EQUALITY, THEN THE EXISTING GATES ───────────────────────────────
+ *
+ * A track's kind must match EXACTLY. Anything looser is a guess about what the
+ * author meant — a `vec3` position pasted onto a `vec2` size is arithmetic
+ * nobody asked for — and the value rules that police the rest (`colour must be
+ * #hex`, an enum's options, a number's range) already live in
+ * `trackValueRefusal`, which every write goes through. So this checks the one
+ * thing those cannot, and hands the rest over.
+ *
+ * A path the subject does not track yet is a target too, so a bounce copied
+ * from one card pastes onto a card that has never been animated. Whether the
+ * subject can hold that path is the trackable-path gate's question
+ * (`keyframeRefusal`, `sceneTrackRefusal`), which the write asks and the paste
+ * reports.
+ */
+export function pasteTargets(
+  doc: Doc3D,
+  clip: KeyframeClip,
+  subject: { containerId: string; layerId: string | null },
+  atFrame: number,
+): { targets: PasteTarget[]; refusals: string[] } {
+  const tracks =
+    subject.layerId === null
+      ? doc.scenesById[subject.containerId]?.tracks
+      : homeOf(doc, subject.containerId)?.layersById[subject.layerId]?.tracks;
+  const targets: PasteTarget[] = [];
+  const refusals: string[] = [];
+
+  for (const row of clip.tracks) {
+    const existing = tracks?.[row.path];
+    if (existing !== undefined && existing.kind !== row.kind) {
+      refusals.push(
+        `"${row.path}" is a ${existing.kind} here and the copied keys are ${row.kind}, so they cannot land on it.`,
+      );
+      continue;
+    }
+    targets.push({
+      path: row.path,
+      ...(row.bezier === true ? { bezier: true as const } : {}),
+      // Integer frames, and never below zero: a clip anchored later than the
+      // playhead would otherwise ask for a negative frame the validator refuses.
+      keys: row.keys.map(({ relFrame, ...held }) => ({
+        frame: Math.max(0, Math.trunc(atFrame + relFrame)),
+        ...held,
+      })),
+    });
+  }
+  return { targets, refusals };
+}