@dailies-studio/shot-editor 0.1.0

package/src/panels/timeline/model.ts

@@ -0,0 +1,641 @@
+// The dock's geometry and its rows, derived from the document.
+//
+// ── WHY `TimelineModel` IS NOT USED HERE ────────────────────────────────
+//
+// @dailies-studio/timeline's `TimelineModel` is KEYFRAME-SHAPED throughout:
+// `rows[].keyframes`, `toggleKeyframe(rowId, frame)`, `setEase(refs:
+// KeyframeAddr[])`, `focusedCurve`. Every member is about INSTANTS.
+//
+// A block lane has INTERVALS, and its verbs are trim-in, trim-out, split,
+// reorder and retime. Forcing one through the other gives either a
+// discriminated union half the shared components must switch on, or a
+// `TimelineModel` whose `keyframes` array is permanently empty — and the second
+// is worse, because it looks like it works.
+//
+// What IS reused, unchanged, is everything geometric and presentational:
+// `Ruler`, `PlayheadLine`, `frameToPx`, `useAnchoredZoom`, `startDrag` and
+// `CurveGraph`. Those are about frames and pixels, which both lanes agree about.
+// The one geometry helper this lane does NOT reuse is `pxToFrame` — see
+// `frameDelta` below for why a signed delta must not go through it.
+//
+// ponytail: BlockRow and SceneStrip are local. Promote them into
+// @dailies-studio/timeline when a SECOND chrome needs a block lane — the motion
+// editor already has overlapping `Transition`s, so it plausibly will.
+import {
+  deltaFor,
+  docDurationFrames,
+  isSpringBlock,
+  layerChildren,
+  motionPresets,
+  resolveLayerAt,
+  sceneWindows,
+} from "@dailies-studio/shot/doc";
+import type { AnimBlock, AudioClipRef, Doc3D, Layer3D, Scene3D } from "@dailies-studio/shot/doc";
+import type { Rational } from "@dailies-studio/engine";
+import { CHANNELS, CHANNEL_BY_KEY } from "../../channels.js";
+import type { Channel } from "../../channels.js";
+
+/** One scene's bar on the SCENE STRIP. */
+export interface SceneBar {
+  id: string;
+  name: string;
+  /** MASTER frames, half-open [start, end). */
+  start: number;
+  end: number;
+}
+
+/** One block's bar on a MICRO track. */
+export interface BlockBar {
+  id: string;
+  layerId: string;
+  slot: AnimBlock["slot"];
+  preset: string;
+  /** SCENE-LOCAL frames, half-open. */
+  frame: number;
+  durationFrames: number;
+  /** The OUT handle means something different for a spring — see timelineOps.
+   *  The dock disables it rather than letting the author discover that. */
+  spring: boolean;
+}
+
+/** One layer's row. */
+export interface TrackRowModel {
+  layerId: string;
+  label: string;
+  depth: number;
+  blocks: BlockBar[];
+  /** A layer with no blocks still gets a row: it is where the Animate tool
+   *  will put the first one, and an empty lane the author cannot see is a
+   *  feature they cannot find. */
+  empty: boolean;
+}
+
+export function sceneBars(doc: Doc3D): SceneBar[] {
+  return sceneWindows(doc).map((w) => ({
+    id: w.id,
+    name: doc.scenesById[w.id]?.name ?? w.id,
+    start: w.start,
+    end: w.end,
+  }));
+}
+
+export function masterDuration(doc: Doc3D): number {
+  return docDurationFrames(doc);
+}
+
+/**
+ * One scene's rows, in OUTLINE order and nested.
+ *
+ * Outline order and not paint order, because the dock sits under a layers panel
+ * that is itself the outline — two lists of the same layers in different orders
+ * is a UI nobody can follow.
+ */
+export function trackRows(scene: Scene3D, isolation: string | null = null): TrackRowModel[] {
+  const out: TrackRowModel[] = [];
+  const walk = (ids: readonly string[], depth: number): void => {
+    for (const id of ids) {
+      const layer = scene.layersById[id];
+      if (layer === undefined) continue;
+      out.push({
+        layerId: id,
+        label: layer.label,
+        depth,
+        blocks: layer.blocks.map((b) => barOf(b, id)),
+        empty: layer.blocks.length === 0,
+      });
+      walk(layerChildren(layer), depth + 1);
+    }
+  };
+  // ── THE DOCK IS SCOPED WHEN THE OUTLINE AND THE STAGE ARE ─────────────
+  //
+  // Going inside a card dims the rest of the scene, makes it unpickable and
+  // narrows the outline to the subtree — and the dock kept listing every layer
+  // in the scene, so the one panel an author uses to find a block still showed
+  // dozens of rows for layers they could not click.
+  //
+  // The subtree's ROOT is included and its ancestors are not, so the card's own
+  // blocks stay reachable: entering a card to retime it and then not finding it
+  // is the reason to enter at all.
+  const root = isolation === null ? null : scene.layersById[isolation];
+  if (root !== undefined && root !== null) walk([root.id], 0);
+  else walk(scene.layers, 0);
+  return out;
+}
+
+function barOf(block: AnimBlock, layerId: string): BlockBar {
+  return {
+    id: block.id,
+    layerId,
+    slot: block.slot,
+    preset: block.preset,
+    frame: block.frame,
+    durationFrames: Math.max(1, Math.trunc(block.durationFrames)),
+    spring: isSpringBlock(block),
+  };
+}
+
+// ── CHANNEL ROWS: THE LOTTIE READ OF A BLOCK LANE ───────────────────────────
+//
+// Lottielab's timeline expands a layer into one row per ANIMATED PROPERTY —
+// Position, Scale, Opacity — with keyframe diamonds on each. This lane
+// animates with blocks, not stored keyframe tracks, and that does not change
+// here: a channel row is a DERIVED VIEW over the blocks. `deltaFor` already
+// says which channels a block writes, so the rows come straight out of the
+// document with nothing new stored in it.
+//
+// The span's endpoint values come from `resolveLayerAt` — the same fold the
+// stage draws and the renderer samples — at the block's two edge frames. A
+// second fold here would be a second answer to a question with exactly one.
+//
+// Dragging anything on a channel row drags the BLOCK. The block is still the
+// atom: "move the opacity keyframes" moves the Fade everywhere it writes,
+// which is what keeps a preset one legible thing instead of six anonymous
+// tracks.
+
+/** One block's footprint on one channel row. Frames are SCENE-LOCAL, like
+ *  every bar in this file. */
+export interface ChannelSpan {
+  blockId: string;
+  slot: AnimBlock["slot"];
+  /** The preset's display label, for the span's tooltip. */
+  preset: string;
+  frame: number;
+  durationFrames: number;
+  spring: boolean;
+  /** The channel's resolved value at the span's two edges, formatted. */
+  from: string;
+  to: string;
+}
+
+export interface ChannelRowModel {
+  key: Channel;
+  label: string;
+  spans: ChannelSpan[];
+}
+
+/** The parts of a bar that fall outside the layer's lifespan, in SCENE frames.
+ *  Both ends, because a lifespan can be trimmed from either side and a short
+ *  enough one clips a block at both. Shared by the camera's block bars and the
+ *  channel spans, so "drawn dead" means one thing. */
+export function deadSpans(
+  bar: { frame: number; durationFrames: number },
+  lifespan: Lifespan | undefined,
+): { from: number; to: number }[] {
+  if (lifespan === undefined) return [];
+  const end = bar.frame + bar.durationFrames;
+  const out: { from: number; to: number }[] = [];
+  if (bar.frame < lifespan.in) out.push({ from: bar.frame, to: Math.min(end, lifespan.in) });
+  if (end > lifespan.out) out.push({ from: Math.max(bar.frame, lifespan.out), to: end });
+  return out;
+}
+
+/**
+ * One row per channel that at least one block on this layer writes, in
+ * CHANNELS order (which is resolve.ts's), each carrying the spans of the
+ * blocks that write it. A channel nothing writes gets no row — Lottie lists
+ * animated properties, not every property.
+ *
+ * Which channels a block writes is DECLARED, not sampled: `deltaFor`'s keys at
+ * any progress. Probed at 0.5 rather than an endpoint only because a fade's
+ * delta at p=0 is still a declaration and the keys do not depend on p.
+ */
+export function channelRows(layer: Layer3D, fps: Rational): ChannelRowModel[] {
+  const spansByKey = new Map<Channel, ChannelSpan[]>();
+  for (const block of layer.blocks) {
+    const keys = Object.keys(deltaFor(block.preset, block.slot, block.params, 0.5)) as Channel[];
+    if (keys.length === 0) continue;
+    const frame = Math.trunc(block.frame);
+    const duration = Math.max(1, Math.trunc(block.durationFrames));
+    const a = resolveLayerAt(layer, frame, fps);
+    const b = resolveLayerAt(layer, frame + duration, fps);
+    for (const key of keys) {
+      const spec = CHANNEL_BY_KEY.get(key);
+      if (spec === undefined) continue;
+      const span: ChannelSpan = {
+        blockId: block.id,
+        slot: block.slot,
+        preset: motionPresets[block.preset]?.label ?? block.preset,
+        frame,
+        durationFrames: duration,
+        spring: isSpringBlock(block),
+        from: spec.read(a),
+        to: spec.read(b),
+      };
+      const at = spansByKey.get(key);
+      if (at === undefined) spansByKey.set(key, [span]);
+      else at.push(span);
+    }
+  }
+  return CHANNELS.flatMap((c) => {
+    const spans = spansByKey.get(c.key);
+    return spans === undefined ? [] : [{ key: c.key, label: c.label, spans }];
+  });
+}
+
+/** The camera's own track: one bar per shot. It is a row like any other so the
+ *  camera can be trimmed and retimed with the same gestures, rather than
+ *  through a panel that would be a second timeline. */
+export function cameraBars(scene: Scene3D): BlockBar[] {
+  return scene.shots.map((shot) => ({
+    id: shot.id,
+    layerId: CAMERA_ROW_ID,
+    slot: "during" as const,
+    preset: shot.kind,
+    frame: shot.frame,
+    durationFrames: Math.max(1, Math.trunc(shot.durationFrames)),
+    spring: shot.ease?.type === "spring",
+  }));
+}
+
+/**
+ * A DELTA in px as a delta in frames.
+ *
+ * NOT `pxToFrame`, and the difference is a real bug rather than a style
+ * preference: that helper clamps at zero, because its job is turning an
+ * absolute x POSITION into a frame and there is no frame before the first one.
+ * A drag delta is signed, so running it through the clamp silently drops every
+ * leftward drag — a left-trim that never moves, which looks like a dead handle.
+ */
+export function frameDelta(px: number, ppf: number): number {
+  return Math.round(px / Math.max(1e-6, ppf));
+}
+
+/** The camera row's stand-in layer id. Not a real layer, and deliberately not a
+ *  valid `l3_` id, so a code path that treated it as one fails loudly. */
+export const CAMERA_ROW_ID = "camera";
+
+// ── THE MASTER STRIP ────────────────────────────────────────────────────────
+//
+// The dock used to be two levels: a scene strip on top and the tracks of
+// WHICHEVER SCENE THE PLAYHEAD WAS IN underneath. One bit, `state.sceneId`,
+// decided what the lower half showed.
+//
+// That bit is gone from the geometry. Every scene's rows are on screen at once,
+// at their MASTER positions, grouped in master order — one continuous strip, the
+// way the reference editor and every NLE draw a sequence. `state.sceneId` is
+// still the inspector's subject and the URL's, but nothing about the timeline's
+// layout reads it any more, which is what makes "drag a layer in scene 3 while
+// the playhead sits in scene 1" a gesture rather than a mode change.
+//
+// BARS STAY SCENE-LOCAL and the GROUP carries the offset. The alternative —
+// baking `start` into every bar's `frame` — turns each bar into a master frame
+// that every gesture has to convert back before it can call a document op, and
+// one missed conversion moves a block a whole scene. A drag DELTA is
+// offset-invariant, so keeping the offset out of the bar makes the conversion a
+// rendering detail and never a document one.
+
+/** A layer's half-open SCENE-LOCAL lifespan, with the default filled in. */
+export interface Lifespan {
+  in: number;
+  out: number;
+}
+
+/**
+ * The layer's bar, with an ABSENT `lifetime` resolved to the whole scene.
+ *
+ * The document's field is optional and absent means "always" (`layerAliveAt`).
+ * A bar needs two ends, so the default is materialised HERE, in one place,
+ * rather than at each of the gestures and readers that would otherwise pick
+ * their own. Nothing is written by reading it: the first edge drag is what puts
+ * a `lifetime` in the document.
+ *
+ * A stored lifespan is returned AS IT IS, even when it runs past the end of the
+ * scene. Clamping it to the scene here would silently rewrite a document the
+ * first time the dock drew it, and the part past the end is exactly the thing
+ * the author needs to see in order to pull it back.
+ */
+export function lifespanOf(layer: Layer3D, scene: Scene3D): Lifespan {
+  const life = layer.lifetime;
+  if (life === undefined) return { in: 0, out: Math.max(1, Math.trunc(scene.durationFrames)) };
+  return { in: Math.trunc(life.in), out: Math.trunc(life.out) };
+}
+
+export interface MasterRow extends TrackRowModel {
+  lifespan: Lifespan;
+}
+
+/** One scene's whole block of rows, placed on the master timeline. */
+export interface MasterSceneGroup {
+  id: string;
+  name: string;
+  /** MASTER frames, half-open — the prefix sum, never a stored offset. */
+  start: number;
+  end: number;
+  /** The camera's shots. SCENE-LOCAL, like every other bar here. */
+  camera: BlockBar[];
+  rows: MasterRow[];
+}
+
+/** Every scene's rows in MASTER order, each group carrying the offset its bars
+ *  are drawn at. */
+export function masterRows(doc: Doc3D, isolation: string | null = null): MasterSceneGroup[] {
+  return sceneWindows(doc).flatMap((w) => {
+    const scene = doc.scenesById[w.id];
+    if (scene === undefined) return [];
+    return [
+      {
+        id: w.id,
+        name: scene.name,
+        start: w.start,
+        end: w.end,
+        camera: cameraBars(scene),
+        // The isolation only narrows the scene it LIVES IN. A master timeline
+        // shows every scene, and the subtree exists in exactly one of them —
+        // scoping the others by an id they do not contain would empty them.
+        rows: trackRows(scene, scene.layersById[isolation ?? ""] === undefined ? null : isolation).map((row) => ({
+          ...row,
+          lifespan: lifespanOf(scene.layersById[row.layerId]!, scene),
+        })),
+      },
+    ];
+  });
+}
+
+/**
+ * How wide the time area has to be, in MASTER frames.
+ *
+ * Not `docDurationFrames`: a lifespan or a block may sit past the end of its
+ * scene (nothing forbids it, and the runtime simply never reaches it), and a
+ * bar the author cannot scroll to is a bar they cannot drag back.
+ */
+export function masterContentFrames(doc: Doc3D, groups: readonly MasterSceneGroup[]): number {
+  let end = docDurationFrames(doc);
+  for (const group of groups) {
+    for (const row of group.rows) {
+      end = Math.max(end, group.start + row.lifespan.out);
+      for (const bar of row.blocks) end = Math.max(end, group.start + bar.frame + bar.durationFrames);
+    }
+    for (const bar of group.camera) end = Math.max(end, group.start + bar.frame + bar.durationFrames);
+  }
+  return end;
+}
+
+/**
+ * The dock's one time string.
+ *
+ * A WHOLE second reads as a clock — "0:00", "1:07" — and anything between two
+ * seconds reads as seconds and hundredths — "12.84". The hundredths appear only
+ * when they carry information: at 30fps the clock form rounds three neighbouring
+ * frames to the same string, and a readout that sits still while the playhead
+ * moves is worse than no readout. Past a minute the clock prefix stays on
+ * ("1:07.50") so the two forms never disagree about which minute it is.
+ *
+ * Whole-second detection is INTEGER arithmetic on the rational fps, not
+ * `Number.isInteger` on a division: 1001/30000 documents have exact second
+ * boundaries that a float compare misses.
+ */
+export function timecode(frame: number, fps: Rational): string {
+  const seconds = (frame * fps.den) / fps.num;
+  const minutes = Math.floor(seconds / 60);
+  const rest = seconds - minutes * 60;
+  if ((frame * fps.den) % fps.num === 0) {
+    return `${minutes}:${String(Math.round(rest)).padStart(2, "0")}`;
+  }
+  const fixed = rest.toFixed(2);
+  return minutes === 0 ? fixed : `${minutes}:${fixed.padStart(5, "0")}`;
+}
+
+// ── THE LIFESPAN'S THREE GESTURES ───────────────────────────────────────────
+//
+//   BODY moves the bar AND every block on the layer by the same delta.
+//   SLIP  moves every block and leaves the bar where it is.
+//   IN / OUT move one end and touch no block at all.
+//
+// Body-versus-edge is After Effects verbatim, and it is not configurable in any
+// tool that ships it: dragging a layer's duration bar carries its keyframes,
+// moving one end does not. SLIP is the third gesture — AE's hollow slip bar,
+// Premiere's slip tool, Cavalry's offset command — and a timeline that ships
+// only the first two gets filed against for it.
+//
+// EVERY MODE CLAMPS ON THE LEFT ONLY. `block.frame` is validated non-negative
+// and a lifespan starting before its scene is meaningless, so zero is a real
+// floor; the right has no floor, because a bar hanging past the end of its scene
+// is a legible state the author can drag back and a clamp there would freeze the
+// default lifespan (which is exactly the whole scene) in place.
+
+export type LifespanDrag = "body" | "in" | "out" | "slip";
+
+/** The shortest lifespan an edge drag may leave behind. `validate.ts` demands
+ *  `out > in`; this is that rule with the integer grid applied. */
+export const MIN_LIFESPAN_FRAMES = 1;
+
+/**
+ * Apply one lifespan gesture. PURE, and the delta is measured from the
+ * document handed in — which is the scrub's BASE, so a coalesced pointermove or
+ * a snap that bites and un-bites cannot make a drag drift.
+ */
+export function writeLifespan(
+  doc: Doc3D,
+  sceneId: string,
+  layerId: string,
+  mode: LifespanDrag,
+  delta: number,
+): Doc3D {
+  const scene = doc.scenesById[sceneId];
+  const layer = scene?.layersById[layerId];
+  if (scene === undefined || layer === undefined) return doc;
+  const life = lifespanOf(layer, scene);
+  const d = Math.round(delta);
+  let next: Layer3D;
+
+  switch (mode) {
+    case "body": {
+      // ONE clamped delta for the bar and the blocks together. Clamping them
+      // apart is the bug this shape exists to prevent: the bar would stop at
+      // zero while its blocks kept sliding, and the author would have retimed
+      // the animation by dragging the layer.
+      const moved = Math.max(d, -Math.min(life.in, earliestBlock(layer)));
+      if (moved === 0) return doc;
+      next = {
+        ...layer,
+        lifetime: { in: life.in + moved, out: life.out + moved },
+        blocks: shiftBlocks(layer.blocks, moved),
+      };
+      break;
+    }
+    case "slip": {
+      const earliest = earliestBlock(layer);
+      if (!Number.isFinite(earliest)) return doc;
+      const moved = Math.max(d, -earliest);
+      if (moved === 0) return doc;
+      next = { ...layer, blocks: shiftBlocks(layer.blocks, moved) };
+      break;
+    }
+    // An edge that lands where it already was returns the document BY
+    // REFERENCE, absent `lifetime` included. So the field is materialised by
+    // the first drag that actually moves an edge and not by the first one that
+    // twitches — a no-op edit still dirties the document and still autosaves.
+    case "in": {
+      const at = Math.max(0, Math.min(life.out - MIN_LIFESPAN_FRAMES, life.in + d));
+      if (at === life.in) return doc;
+      next = { ...layer, lifetime: { in: at, out: life.out } };
+      break;
+    }
+    case "out": {
+      const at = Math.max(life.in + MIN_LIFESPAN_FRAMES, life.out + d);
+      if (at === life.out) return doc;
+      next = { ...layer, lifetime: { in: life.in, out: at } };
+      break;
+    }
+  }
+
+  return {
+    ...doc,
+    scenesById: {
+      ...doc.scenesById,
+      [sceneId]: { ...scene, layersById: { ...scene.layersById, [layerId]: next } },
+    },
+  };
+}
+
+/** `Infinity` for a layer with no blocks, so the caller's `Math.min` against it
+ *  is a no-op rather than a special case. */
+function earliestBlock(layer: Layer3D): number {
+  return layer.blocks.reduce((min, b) => Math.min(min, b.frame), Infinity);
+}
+
+// ── THE AUDIO CLIP'S GESTURES ───────────────────────────────────────────────
+//
+// The same shape as the lifespan's — a PURE writer measured from the scrub's
+// BASE, so a coalesced pointermove or a snap that bites and un-bites cannot
+// make a drag drift — over `AudioClipRef`, whose frames are MASTER frames.
+//
+// ── WHY A BODY DRAG CARRIES THE MARKERS ─────────────────────────────────
+//
+// A beat marker belongs to the music, not to the timecode. This is the single
+// most-filed complaint against Premiere's timeline markers (they are sequence
+// markers, so sliding the track leaves every marked beat pointing at silence)
+// and it is the thing Final Cut made a fiat by giving clips their own markers.
+//
+// We keep `MarkerRef.frame` a MASTER frame and derive the ownership instead: a
+// body drag moves every marker that CURRENTLY SITS INSIDE the clip's window, by
+// the same clamped delta, in the same capture — so it is one undo entry and
+// Escape restores clip and marks together.
+//
+// Derived rather than stored, and that is the load-bearing choice. A
+// `marker.clipId` would need an answer for "the clip was deleted", "the clip
+// was trimmed past the marker", "two clips overlap this frame" and "the marker
+// was dragged out of its clip", and every one of those answers is a rule the
+// author cannot see on screen. Containment at the moment of the gesture is a
+// rule they can see: the marks under the bar move with the bar.
+//
+// TRIM AND SLIP DO NOT MOVE MARKERS. A trim changes what you hear; it does not
+// change when the beat you marked happens. Slip is the same statement about the
+// source. Only moving the clip moves the sound in time, so only moving the clip
+// moves the marks.
+
+export type AudioDrag = "body" | "in" | "out" | "slip" | "fade-in" | "fade-out";
+
+/** Fields with their documented defaults filled in, for a lane that has to
+ *  compute with them. Reading one never writes one. */
+export interface AudioClipView {
+  frame: number;
+  durationFrames: number;
+  offsetFrames: number;
+  gain: number;
+  fadeInFrames: number;
+  fadeOutFrames: number;
+  muted: boolean;
+}
+
+export function audioClipView(clip: AudioClipRef): AudioClipView {
+  return {
+    frame: Math.trunc(clip.frame),
+    durationFrames: Math.max(1, Math.trunc(clip.durationFrames)),
+    offsetFrames: Math.max(0, Math.trunc(clip.offsetFrames ?? 0)),
+    gain: clip.gain ?? 1,
+    fadeInFrames: Math.max(0, Math.trunc(clip.fadeInFrames ?? 0)),
+    fadeOutFrames: Math.max(0, Math.trunc(clip.fadeOutFrames ?? 0)),
+    muted: clip.muted ?? false,
+  };
+}
+
+/**
+ * Apply one audio gesture. Every clamp here restates a `validate.ts` bound, so
+ * a live drag can never build a document the save would refuse: `frame` and
+ * `offsetFrames` stay non-negative integers, `durationFrames` stays positive,
+ * and `fadeIn + fadeOut` never exceeds the duration.
+ */
+export function writeAudioDrag(doc: Doc3D, clipId: string, mode: AudioDrag, delta: number): Doc3D {
+  const clip = doc.audio[clipId];
+  if (clip === undefined) return doc;
+  const c = audioClipView(clip);
+  const d = Math.round(delta);
+  /** The shortest a trim may leave the clip: one frame, and never shorter than
+   *  the fades already on it. */
+  const floor = Math.max(1, c.fadeInFrames + c.fadeOutFrames);
+  let patch: Partial<AudioClipRef>;
+  let markerDelta = 0;
+
+  switch (mode) {
+    case "body": {
+      const moved = Math.max(d, -c.frame);
+      if (moved === 0) return doc;
+      patch = { frame: c.frame + moved };
+      markerDelta = moved;
+      break;
+    }
+    // A head trim moves the clip and the source trim TOGETHER: the audio under
+    // the remaining bar must not slide, which is what a trim means in every NLE
+    // and is why this is not two independent edits.
+    case "in": {
+      const moved = Math.max(-c.frame, Math.max(-c.offsetFrames, Math.min(c.durationFrames - floor, d)));
+      if (moved === 0) return doc;
+      patch = {
+        frame: c.frame + moved,
+        offsetFrames: c.offsetFrames + moved,
+        durationFrames: c.durationFrames - moved,
+      };
+      break;
+    }
+    case "out": {
+      const next = Math.max(floor, c.durationFrames + d);
+      if (next === c.durationFrames) return doc;
+      patch = { durationFrames: next };
+      break;
+    }
+    // SLIP: the source moves under a bar that stays exactly where it is. There
+    // is no right-hand clamp, because nothing here knows the source length —
+    // the mixer emits silence past the end, which is a legible state the author
+    // can drag back out of.
+    case "slip": {
+      const next = Math.max(0, c.offsetFrames + d);
+      if (next === c.offsetFrames) return doc;
+      patch = { offsetFrames: next };
+      break;
+    }
+    case "fade-in": {
+      const next = Math.max(0, Math.min(c.durationFrames - c.fadeOutFrames, c.fadeInFrames + d));
+      if (next === c.fadeInFrames) return doc;
+      patch = { fadeInFrames: next };
+      break;
+    }
+    // The handle sits at `frame + duration - fadeOut`, so dragging it LEFT
+    // (negative delta) lengthens the fade. Hence the minus.
+    case "fade-out": {
+      const next = Math.max(0, Math.min(c.durationFrames - c.fadeInFrames, c.fadeOutFrames - d));
+      if (next === c.fadeOutFrames) return doc;
+      patch = { fadeOutFrames: next };
+      break;
+    }
+  }
+
+  const next: Doc3D = { ...doc, audio: { ...doc.audio, [clipId]: { ...clip, ...patch } } };
+  if (markerDelta === 0) return next;
+  const end = c.frame + c.durationFrames;
+  const markers = (doc.markers ?? []).map((m) =>
+    m.frame >= c.frame && m.frame < end ? { ...m, frame: Math.max(0, m.frame + markerDelta) } : m,
+  );
+  // Re-sorted because a moved subset can cross a marker that did not move, and
+  // `validate.ts` enforces the sort the strip draws in.
+  return { ...next, markers: [...markers].sort((a, b) => a.frame - b.frame) };
+}
+
+function shiftBlocks(blocks: readonly AnimBlock[], delta: number): AnimBlock[] {
+  // No per-block clamp, deliberately: the caller has already clamped the DELTA
+  // against the earliest block, so none of these can go negative. A floor here
+  // would break the one thing a body drag and a slip promise — that every block
+  // moved by the same amount — in exactly the case it was meant to protect.
+  // No re-sort either: a uniform shift preserves whatever order they were in.
+  return blocks.map((b) => ({ ...b, frame: b.frame + delta }));
+}