@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/timeline/model.ts

@@ -6,8 +6,8 @@
 // `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
+// A lifespan, a clip and a camera move are INTERVALS, and their 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.
@@ -18,22 +18,61 @@
 // 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.
+// ponytail: BlockRow and ShotRow are local. Promote them into
+// @dailies-studio/timeline when a SECOND chrome needs an interval lane — the
+// motion editor already has overlapping `Transition`s, so it plausibly will.
 import {
-  deltaFor,
+  defDurationFrames,
   docDurationFrames,
-  isSpringBlock,
+  audioHomeOf,
+  firstKeyframeFrame,
+  homeOf,
+  isDefId,
+  isOpenEndedOut,
   layerChildren,
-  motionPresets,
-  resolveLayerAt,
+  masterAudioClips,
+  framingsChain,
+  isZoomRigBreak,
+  patchHome,
+  sceneStart,
   sceneWindows,
+  sceneTrackablePath,
+  layerLifespan,
+  layerTrackablePath,
+  updateAudioClip,
+  // ── the clip ops, which are what a VIDEO row's gestures write through ──
+  //
+  // Every one of them refuses by returning the document it was handed, which
+  // is the property `writeLifespan` below is built on: a gesture that cannot
+  // land writes nothing and the scrub's base survives untouched.
+  rollLayers,
+  rollSeam,
+  shiftLayer,
+  shiftTracks,
+  slipLayer,
+  tracksPatch,
+  trimLayer,
+  videoClipOf,
+  videoSoundClip,
+} from "@dailies-studio/shot/doc";
+import type {
+  AudioClipRef,
+  ComponentDef3D,
+  Doc3D,
+  LayerHome,
+  Layer3D,
+  PathShot,
+  Scene3D,
+  Shot,
+  ShotAsset,
+  ShotTrack,
+  VideoClipInfo,
+  VideoLayer3D,
 } 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";
+import { formatValue } from "@dailies-studio/ui";
+import { clipProgress01 } from "@dailies-studio/engine";
+import type { Ease, Rational, TrackKind, Value } from "@dailies-studio/engine";
+import { TRANSFORM_CHANNELS } from "../../channels.js";
 
 /** One scene's bar on the SCENE STRIP. */
 export interface SceneBar {
@@ -44,12 +83,12 @@ export interface SceneBar {
   end: number;
 }
 
-/** One block's bar on a MICRO track. */
+/** One camera move's bar on the camera row. */
 export interface BlockBar {
+  /** The move's own id (`shot.id`). */
   id: string;
-  layerId: string;
-  slot: AnimBlock["slot"];
-  preset: string;
+  /** The move's kind (`dolly`, `orbit`), the bar's name. */
+  label: string;
   /** SCENE-LOCAL frames, half-open. */
   frame: number;
   durationFrames: number;
@@ -63,11 +102,6 @@ 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[] {
@@ -84,24 +118,42 @@ export function masterDuration(doc: Doc3D): number {
 }
 
 /**
- * One scene's rows, in OUTLINE order and nested.
+ * A sibling list in DISPLAY order: front first, each id with its index in the
+ * STORED list.
  *
- * 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.
+ * Every layer list is stored back to front (index 0 paints first, schema v35,
+ * Figma's `children`), and Figma's layers panel shows it reversed, the front
+ * layer as the top row. A walker that emits a parent before it recurses then
+ * puts the parent row above its children, which is the other half of that
+ * reading. The outline and the dock both walk through this one function, so
+ * they never disagree about which row is on top, and a row keeps its ARRAY
+ * index, which is what a drop and `aria-posinset` are computed from.
  */
-export function trackRows(scene: Scene3D, isolation: string | null = null): TrackRowModel[] {
+export function frontFirst(ids: readonly string[]): { id: string; index: number }[] {
+  const out: { id: string; index: number }[] = [];
+  for (let index = ids.length - 1; index >= 0; index -= 1) out.push({ id: ids[index]!, index });
+  return out;
+}
+
+/**
+ * One scene's rows, nested, FRONT FIRST (`frontFirst`), exactly as the layers
+ * panel lists them: the dock sits under that panel, and two lists of the same
+ * layers in different orders is a UI nobody can follow. Upper rows cover lower
+ * ones, which is also an NLE's track order.
+ */
+export function trackRows(
+  scene: LayerHome,
+  isolation: string | null = null,
+): TrackRowModel[] {
   const out: TrackRowModel[] = [];
   const walk = (ids: readonly string[], depth: number): void => {
-    for (const id of ids) {
+    for (const { id } of frontFirst(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);
     }
@@ -110,11 +162,11 @@ export function trackRows(scene: Scene3D, isolation: string | null = null): Trac
   //
   // 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
+  // in the scene, so the one panel an author uses to retime a layer 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
+  // keys 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);
@@ -122,114 +174,126 @@ export function trackRows(scene: Scene3D, isolation: string | null = null): Trac
   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;
+/** One keyframe on a track. SCENE-LOCAL frames, like every bar in this file. */
+export interface TrackKey {
+  /** The keyframe's own id. Carried for React's key and for nothing else — the
+   *  ops address a keyframe by (track, frame), see `selectedKeyframe`. */
+  id: string;
   frame: number;
-  durationFrames: number;
-  spring: boolean;
-  /** The channel's resolved value at the span's two edges, formatted. */
-  from: string;
-  to: string;
+  /** The ease LEAVING this key — `easeOut`, which is why the menu that sets it
+   *  hangs off the key rather than off the segment between two. The whole object
+   *  rather than its `type`, so the row can name the PRESET ("Ease Out") through
+   *  the shared `matchPreset` instead of the shape ("Bezier"). */
+  ease: Ease;
+  /** The value, formatted for the title. */
+  value: string;
+  /** The OWNING TRACK's kind. Carried so the menu that sets `ease` can offer
+   *  only what the engine will sample: a spring on a non-springable kind
+   *  throws inside `evaluateTrack`, and the discrete kinds hold structurally
+   *  so every tween on them is a no-op dressed as a choice. */
+  kind: TrackKind;
+  /** True for the track's final keyframe, whose `easeOut` governs no segment.
+   *  The menu disables its ease entries rather than writing a value that is
+   *  never read — this lane refuses rather than going silently inert. */
+  last: boolean;
+  /** The track curves its path (`spatialInterp`): no spring ease, the
+   *  engine's rule, so the menu leaves the spring presets out. */
+  curved: boolean;
 }
 
 export interface ChannelRowModel {
-  key: Channel;
+  /** The tracked path this row's diamonds edit, and the row's identity. */
+  path: string;
   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;
+  keys: TrackKey[];
 }
 
 /**
- * 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);
-    }
+ * `channelRows`, replayed per layer object.
+ *
+ * Layers are immutable on edit, so identity is value here. The dock computed
+ * the rows of every visible expanded layer on every document change just to
+ * read their `.length` for a row height, while `ChannelRows` computed the same
+ * rows again to draw them. One entry per layer.
+ */
+const CHANNEL_ROWS = new WeakMap<Layer3D, ChannelRowModel[]>();
+export function channelRowsCached(layer: Layer3D): ChannelRowModel[] {
+  const cached = CHANNEL_ROWS.get(layer);
+  if (cached !== undefined) return cached;
+  const rows = channelRows(layer);
+  CHANNEL_ROWS.set(layer, rows);
+  return rows;
+}
+
+/**
+ * One row per tracked path on this layer. A path nothing animates gets no row:
+ * Lottie lists animated properties, not every property, and a property lane
+ * appears when it carries animation and not before.
+ *
+ * The transform paths lead, in `TRANSFORM_CHANNELS`' order (which is
+ * resolve.ts's), then every other tracked path sorted, so two layers with the
+ * same tracks list them the same way; a `Record`'s own order is not one.
+ */
+export function channelRows(layer: Layer3D): ChannelRowModel[] {
+  const tracks = layer.tracks ?? {};
+  const out: ChannelRowModel[] = [];
+  for (const [path, spec] of TRANSFORM_CHANNELS) {
+    const track = tracks[path];
+    if (track !== undefined) out.push({ path, label: spec.label, keys: trackKeys(track) });
   }
-  return CHANNELS.flatMap((c) => {
-    const spans = spansByKey.get(c.key);
-    return spans === undefined ? [] : [{ key: c.key, label: c.label, spans }];
-  });
+  for (const path of Object.keys(tracks).sort()) {
+    if (TRANSFORM_CHANNELS.has(path)) continue;
+    out.push({
+      path,
+      // The LAYER'S lookup, so a tracked `instance.props.<key>` row reads the
+      // contract's label ("Time") instead of its path. Falls back to the path
+      // when the layer carries no snapshot and the registry is not in reach
+      // here — a dock row is a readout, and this module takes no store.
+      label: layerTrackablePath(layer, path)?.label ?? path,
+      keys: trackKeys(tracks[path]!),
+    });
+  }
+  return out;
+}
+
+/**
+ * The SHOT's own tracked properties as channel rows (P5): its background colour
+ * and its post stack.
+ *
+ * Sorted by path for `channelRows`' reason: a `Record`'s key order is not one.
+ */
+export function sceneChannelRows(scene: Scene3D): ChannelRowModel[] {
+  const tracks = scene.tracks ?? {};
+  return Object.keys(tracks)
+    .sort()
+    .map((path) => ({
+      path,
+      label: sceneTrackablePath(path)?.label ?? path,
+      keys: trackKeys(tracks[path]!),
+    }));
+}
+
+function trackKeys(track: ShotTrack): TrackKey[] {
+  const lastIndex = track.keyframes.length - 1;
+  return track.keyframes.map((k, i) => ({
+    id: k.id,
+    frame: k.frame,
+    ease: k.easeOut,
+    value: formatTrackValue(k.value),
+    kind: track.kind,
+    last: i === lastIndex,
+    curved: track.spatialInterp !== undefined,
+  }));
+}
+
+/** A keyframe's value as one short string, for the diamond's title. Not a
+ *  channel formatter: a track's value is the AUTHORED type at its path, which is
+ *  a number, a vector or a hex colour, and `TRANSFORM_CHANNELS`' readers all
+ *  take a resolved `LayerState`. */
+function formatTrackValue(value: Value): string {
+  if (typeof value === "number") return formatValue(value, 0.01);
+  if (Array.isArray(value)) return value.map((v) => formatValue(v, 0.1)).join(", ");
+  return String(value);
 }
 
 /** The camera's own track: one bar per shot. It is a row like any other so the
@@ -238,15 +302,160 @@ export function channelRows(layer: Layer3D, fps: Rational): ChannelRowModel[] {
 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,
+    label: shot.kind,
     frame: shot.frame,
     durationFrames: Math.max(1, Math.trunc(shot.durationFrames)),
     spring: shot.ease?.type === "spring",
   }));
 }
 
+// ── CAMERA KEYFRAMES: PRESENTATION, ZERO SCHEMA (P4) ────────────────────────
+//
+// The camera move system already IS a keyframe track — `cameraAt` walks
+// non-overlapping windows with hold-forever semantics, which is
+// last-writer-by-time. What it lacked was a picture of its own poses.
+//
+// ── AND WHERE THE PICTURE STOPS ─────────────────────────────────────────
+//
+// A camera endpoint is NOT a property-lane keyframe, so it does not get that
+// diamond. A move carries ONE ease for its whole window and the gap after it is
+// a HOLD rather than an interpolation, so drawing them alike would teach an
+// author that every diamond behaves the same — and the first time they
+// right-clicked a camera mark expecting an ease menu they would be right to be
+// annoyed. Camera marks are HOLLOW and read-only; ease stays per-move in the
+// inspector, where a move's ease belongs.
+
+export type CameraMarkKind = "pose" | "chained" | "break" | "waypoint";
+
+/** One camera pose on the camera row. SCENE-LOCAL frames, like every bar. */
+export interface CameraMark {
+  /** Stable across renders: the move it belongs to plus which end. */
+  id: string;
+  frame: number;
+  kind: CameraMarkKind;
+  title: string;
+}
+
+/**
+ * Every camera pose in a scene, in frame order.
+ *
+ * Three rules, and each is a claim the drawing then makes:
+ *
+ *   CHAINED — a move that opens on exactly the pose the previous one closed on
+ *     is ONE keyframe, not two stacked on a pixel. Compared through
+ *     `framingsChain`, which walks `shotWaypoints` because a `PathShot` has no
+ *     `from`/`to` at all. A GAP between the two is still a chain: the camera
+ *     holds that pose across it, so it really is continuous.
+ *   BREAK — the end of a zoom move that changes the zoom. `cameraRigAt` pins
+ *     the distance only INSIDE that window, so the rig jumps one frame later
+ *     and every layer at a non-zero depth pops. Drawn as a split mark rather
+ *     than as an unbroken diamond, because an unbroken diamond would promise a
+ *     continuity that is not there.
+ *   WAYPOINT — a path move's interior poses, READ-ONLY. The chrome refuses to
+ *     half-edit a path today (`setShotFraming` no-ops on one and the inspector
+ *     says so), and the only waypoint writer in the repo replaces the whole
+ *     array, so a draggable mark here would be a control with no op behind it.
+ */
+export function cameraMarks(scene: Scene3D, fps: Rational): CameraMark[] {
+  const out: CameraMark[] = [];
+  const shots = [...scene.shots].sort((a, b) => a.frame - b.frame);
+
+  for (const [index, shot] of shots.entries()) {
+    const duration = Math.max(1, Math.trunc(shot.durationFrames));
+    const end = shot.frame + duration;
+    const previous = shots[index - 1];
+    const chained = previous !== undefined && framingsChain(previous, shot);
+
+    // The OPENING pose. Suppressed when it chains, because the previous move's
+    // closing mark already stands for it — two marks for one pose is the thing
+    // the chain predicate exists to prevent.
+    if (!chained) {
+      out.push({
+        id: `${shot.id}:in`,
+        frame: shot.frame,
+        kind: "pose",
+        title: `${shot.label} starts here`,
+      });
+    }
+
+    // A path's interior poses, read-only. Endpoints are excluded: index 0 is
+    // the opening mark above and the last is the closing mark below.
+    if (shot.kind === "path") {
+      for (const [at, frame] of waypointFrames(shot, fps).entries()) {
+        if (at === 0 || at === shot.waypoints.length - 1) continue;
+        out.push({
+          id: `${shot.id}:wp${at}`,
+          frame,
+          kind: "waypoint",
+          // READ-ONLY IN TIME, editable in POSE. A mark sits at the frame the
+          // eased progress reaches this waypoint, which is derived — there is
+          // nothing under it for a drag to write to. The pose itself is edited
+          // in the inspector's waypoint rows.
+          title:
+            `${shot.label} waypoint ${at + 1} of ${shot.waypoints.length}: its time is derived ` +
+            `from the move's ease; edit its pose in the inspector`,
+        });
+      }
+    }
+
+    // The CLOSING pose, which on a LEGACY scene is also where a zoom's rig pin
+    // ends. v18 removed the pin, so a modern scene draws a plain pose here and
+    // the split mark survives only for documents still on the old rig.
+    const broken = scene.legacyZoomRig === true && isZoomRigBreak(shot);
+    out.push({
+      id: `${shot.id}:out`,
+      frame: end,
+      kind: broken ? "break" : chainsForward(shots, index) ? "chained" : "pose",
+      title: broken
+        ? `${shot.label} ends here, and the camera RIG jumps: on this scene's old rig a zoom move ` +
+          `pins the distance only inside its own window, so every layer at a non-zero depth pops ` +
+          `one frame later. Upgrade the camera in the inspector to remove the step.`
+        : `${shot.label} ends here`,
+    });
+  }
+  return out.sort((a, b) => a.frame - b.frame);
+}
+
+/** Whether the NEXT move opens on this one's closing pose. */
+function chainsForward(shots: readonly Shot[], index: number): boolean {
+  const here = shots[index];
+  const next = shots[index + 1];
+  return here !== undefined && next !== undefined && framingsChain(here, next);
+}
+
+/**
+ * The frame each waypoint of a path move is first REACHED at, on the integer
+ * grid the whole document is built on.
+ *
+ * ── SCANNED, NOT SOLVED ─────────────────────────────────────────────────
+ *
+ * A waypoint sits at `i / (n - 1)` in the spline's own parameter, and the ease
+ * maps time onto that parameter — so placing a mark needs the ease INVERTED. A
+ * bezier ease has no closed-form inverse in the direction wanted, and a hold
+ * ease has no inverse at all (its progress is a step).
+ *
+ * So this walks the move's frames and takes the first one whose eased progress
+ * has reached the waypoint. That is exact ON THE GRID, which is the only
+ * resolution the dock can draw at anyway, and it is total for every ease
+ * including hold. The cost is one `clipProgress01` per frame of one move, once
+ * per render of the camera row.
+ */
+function waypointFrames(shot: PathShot, fps: Rational): number[] {
+  const duration = Math.max(1, Math.trunc(shot.durationFrames));
+  const count = shot.waypoints.length;
+  if (count < 2) return shot.waypoints.map(() => shot.frame);
+  const out: number[] = [];
+  let at = 0;
+  for (let i = 0; i < count; i += 1) {
+    const target = i / (count - 1);
+    while (at < duration && clipProgress01({ ...shot, durationFrames: duration }, shot.frame + at, fps) < target) {
+      at += 1;
+    }
+    out.push(shot.frame + at);
+  }
+  return out;
+}
+
 /**
  * A DELTA in px as a delta in frames.
  *
@@ -256,33 +465,493 @@ export function cameraBars(scene: Scene3D): BlockBar[] {
  * 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.
  */
+// ── AND THE SAME RULE FOR THE POSES ───────────────────────────────────────
+//
+// A camera mark is an 8px square turned 45 degrees, so it occupies about 11.3px
+// of the lane whatever the zoom, while the distance between two of them is the
+// distance between two moves. On a row of one-frame moves that distance is one
+// frame, and at the zoom where a 71-frame shot fills the dock that is 9.9px:
+// the marks overlapped each other by more than a pixel and eight pairs of them
+// fused into a chain of lozenges. A mark that cannot be told from its neighbour
+// has stopped being a mark and become a texture.
+//
+// So the ones that will not fit are not drawn, EXCEPT a break. That exception
+// is the same one the drawing itself makes: a pose, a chain and a waypoint each
+// restate something the bars beside them already say, which is why they are
+// hidden from assistive technology, while a break is a rig discontinuity that
+// exists nowhere else on the row. Dropping the redundant ones costs a reader
+// nothing; dropping a break would remove the only place that fact appears. Two
+// breaks close enough to touch will therefore still touch, and that is the
+// right trade: rare, and information over tidiness.
+//
+// 13 and not 12, because a break is drawn a pixel larger than the rest (a 9px
+// square, so 12.73px across its diagonal) and 12 left it fusing with the pose
+// beside it. The gap has to clear the WIDEST mark, not the common one.
+export const CAMERA_MARK_MIN_GAP_PX = 13;
+
+/**
+ * The marks that can be drawn without fusing into their neighbours, in frame
+ * order. `ppf` is the lane's current zoom, so this thins as the author zooms
+ * out and restores every mark as they zoom back in.
+ */
+/**
+ * Whether a mark carries something no other part of the row does.
+ *
+ * ONE definition, because two things read it and they must agree: this file
+ * decides whether a crowded mark may be dropped, and BlockRow decides whether
+ * it is announced to assistive technology. Those were the same condition
+ * written out twice, so a second load-bearing kind would have been exposed in
+ * the markup and silently thinned away out of the picture.
+ */
+export function isLoadBearingMark(mark: CameraMark): boolean {
+  return mark.kind === "break";
+}
+
+export function thinCameraMarks(marks: readonly CameraMark[], ppf: number): CameraMark[] {
+  const kept: CameraMark[] = [];
+  let lastFrame: number | null = null;
+  for (const mark of marks) {
+    const room = lastFrame === null || (mark.frame - lastFrame) * ppf >= CAMERA_MARK_MIN_GAP_PX;
+    if (!room && !isLoadBearingMark(mark)) continue;
+    kept.push(mark);
+    lastFrame = mark.frame;
+  }
+  return kept;
+}
+
 export function frameDelta(px: number, ppf: number): number {
   return Math.round(px / Math.max(1e-6, ppf));
 }
 
+// ── THE ZOOM, AS A SLIDER POSITION ────────────────────────────────────────
+//
+// `dockPpf` runs 0.2 to 60, which is a 300x range, and a linear slider over it
+// is unusable: every zoom an author actually works at lives in the first 3% of
+// the track, and the remaining 97% is the difference between "very close" and
+// "closer". Half a track of nothing is not a control.
+//
+// LOGARITHMIC, so equal travel is equal RATIO. A slider that doubles the zoom
+// for every fifth of the track behaves the way the wheel already does
+// (`useAnchoredZoom` multiplies by `exp(-deltaY * 0.002)`, which is the same
+// geometric family), so the two gestures agree about what "a bit more" means
+// and the thumb tracks a wheel zoom at a constant rate.
+//
+// The pair is exact in both directions (`sliderToPpf(ppfToSlider(x)) === x`
+// within float error), which is what lets the slider be a readout of the wheel
+// and the wheel keep working while the slider is on screen.
+
+/** Where `ppf` sits on a 0..1 track. Clamped, so a value the store has not seen
+ *  yet (or a NaN out of a broken caller) still paints somewhere real. */
+export function ppfToSlider(ppf: number, min: number, max: number): number {
+  if (!Number.isFinite(ppf)) return 0;
+  const clamped = Math.min(max, Math.max(min, ppf));
+  return Math.log(clamped / min) / Math.log(max / min);
+}
+
+/** The zoom a 0..1 track position means. */
+export function sliderToPpf(t: number, min: number, max: number): number {
+  if (!Number.isFinite(t)) return min;
+  const clamped = Math.min(1, Math.max(0, t));
+  return min * Math.pow(max / min, clamped);
+}
+
+// ── WHETHER A BAR CAN CARRY ITS OWN NAME ──────────────────────────────────
+//
+// A bar is as wide as its window is long, so on a dense row most bars are
+// narrower than the word inside them. They were drawn anyway: the label kept
+// its `text-overflow: ellipsis` and the browser gave it whatever was left after
+// the inset, which on a one-frame move was between zero and three pixels. A row
+// of twenty-two camera moves therefore read as "d d d dolly d d dolly", where
+// every "d" is a name that has been compressed past the point of being one.
+//
+// The rule is the inspector's, one lane over: a label that cannot be read in
+// full is worse than no label, because the reader cannot tell a truncation from
+// a short word. So the name is drawn only when the whole name fits, and the
+// bar's `title` carries the name and the frame range for every bar either
+// way, so nothing becomes unreachable.
+//
+// ── WHY AN ESTIMATE AND NOT A MEASUREMENT ─────────────────────────────────
+//
+// The honest measurement is the text's own advance width, which needs a layout
+// pass or a canvas `measureText` PER BAR, on a row that re-renders on every
+// frame of a zoom drag. This is one multiply against a per-character average,
+// and the average is measured rather than guessed: against the face the label
+// actually resolves to (`500 12px "Inter Variable"`), "in" runs 5.12px per
+// character, "orbit" 5.32, "dolly" 5.54 and "crossfade" 6.35. 6.4 sits just
+// above the widest of them, so every real move name is biased toward hiding:
+// erring that way costs a name that would have just fitted, while erring the
+// other way puts back the sliver this exists to remove.
+//
+// A label of all-wide glyphs would beat it (a lone "w" is 9.95px), which is
+// why `.block-label` keeps `text-overflow: ellipsis` underneath as a backstop
+// rather than relying on this being exact.
+export const BLOCK_LABEL_INSET_PX = 18;
+
+/**
+ * About how many pixels `label` needs at the dock's own face.
+ *
+ * Three buckets, because a name is NOT always a lowercase English keyword.
+ * The camera row's is (`dolly`, `orbit`), but a clip's (`clipNamePlace`) is a
+ * file or layer name, so this sees whatever the author typed. Measured against `500 12px "Inter Variable"`, the face the label
+ * actually inherits: lowercase runs 5.1 to 6.4 per character across `in`,
+ * `orbit`, `dolly` and `crossfade`, capitals about 8, and a full-width glyph
+ * takes the whole 12px em. One flat average tuned on lowercase would pass an
+ * all-caps or CJK name and then ellipsise it, which is the exact sliver this
+ * exists to remove.
+ *
+ * Iterated with `for...of` so a surrogate pair counts once: `label.length` is
+ * UTF-16 code units and would score an emoji as two narrow characters.
+ */
+export function estimateLabelPx(label: string): number {
+  let px = 0;
+  for (const ch of label) {
+    const code = ch.codePointAt(0) ?? 0;
+    // Everything from CJK radicals up is full-width in practice, as are the
+    // fullwidth forms and emoji above the BMP.
+    if (code >= 0x2e80) px += 12;
+    // A cheap test for "this glyph is a capital": a character that changes
+    // under toLowerCase. It catches Latin, Greek and Cyrillic capitals without
+    // a table, and scores digits and punctuation as lowercase, which is right.
+    else if (ch !== ch.toLowerCase()) px += 8;
+    else px += 6.4;
+  }
+  return px;
+}
+
+/**
+ * Does `label` fit inside a bar `widthPx` wide, inset and all?
+ *
+ * `widthPx` is the bar's BORDER-box width, which is what BlockBarView computes
+ * and what CSS consumes, so the inset above is the label's 16px of padding plus
+ * the bar's own 1px border on each side. Getting that wrong by two pixels would
+ * bias the answer toward showing a label that then clips, which is the one
+ * direction this must not err in.
+ */
+export function fitsBlockLabel(widthPx: number, label: string): boolean {
+  return widthPx >= BLOCK_LABEL_INSET_PX + estimateLabelPx(label);
+}
+
+/** The gap between a clip and a name drawn beside it, the boards' 6px. */
+export const CLIP_NAME_GAP_PX = 6;
+
+/**
+ * WHERE A CLIP'S NAME GOES. A name is never cut short: inside the clip when the
+ * whole of it fits, else just AFTER the clip, else (at the track's end, where
+ * after would run off the lane) just BEFORE it, right-aligned. `laneW` is the
+ * lane's drawable width in px, measured from the lane's own 0 like `leftPx`.
+ */
+export function clipNamePlace(
+  leftPx: number,
+  widthPx: number,
+  label: string,
+  laneW: number,
+): "inside" | "after" | "before" {
+  const text = estimateLabelPx(label);
+  if (fitsBlockLabel(widthPx, label)) return "inside";
+  return leftPx + widthPx + CLIP_NAME_GAP_PX + text <= laneW || leftPx - CLIP_NAME_GAP_PX - text < 0
+    ? "after"
+    : "before";
+}
+
 /** 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 PLAYHEAD IN LANE COORDINATES, AND THE LANE THAT FOLLOWS IT ─────────
+
+/**
+ * WHERE THE PLAYHEAD IS, in the frames this lane is drawn in. ONE function,
+ * because two things read it and they must never disagree: the line that draws
+ * it, and the scroller that follows it.
+ *
+ * The fork is unify P2's one-time-base rule. A DEFINITION runs on `defFrame`, a
+ * clock of its own with no master position at all. Everything else runs on
+ * master time, re-zeroed by `origin` — which is DRAW-ONLY (see this file's
+ * master-strip header): the shot context subtracts the shot's start here and
+ * `seek` adds it straight back, so what reaches the store is the master frame
+ * it has always been.
+ *
+ * Split out of `DockPlayhead` when the lane learned to follow. Left inline it
+ * would have been copied into the follow effect, and a lane that scrolled to a
+ * different frame than it drew is the exact shape of bug this codebase has paid
+ * for before — two spellings of one mapping, agreeing on every input anyone
+ * happened to try.
+ */
+export function laneFrame(
+  state: { frame: number; defFrame: number; editingDef: string | null },
+  origin: number,
+): number {
+  return state.editingDef === null ? state.frame - origin : state.defFrame;
+}
+
+/**
+ * How much of the visible lane the playhead may cross before it drags the view
+ * along. Outside this band the scroll moves; inside it nothing happens.
+ *
+ * A DEADZONE and not a centred playhead. Centring writes a scroll on every
+ * frame, so the whole lane slides under the pointer at all times and there is
+ * never a still moment in which to click a bar. With a band, a scrub inside the
+ * visible window costs nothing at all, and only playback that runs off the edge
+ * pays.
+ *
+ * The forward number is the interesting one. Once playback pushes past it, each
+ * later frame scrolls by exactly one frame's width, so the playhead stays PINNED
+ * at 0.75 and the content slides under it — which is the "shots passing by" read
+ * this was asked for, and it falls out of the clamp rather than needing its own
+ * mode. 0.75 rather than the far edge leaves a quarter of a lane of lookahead:
+ * an author watching a cut approach can see the next shot's bars before they
+ * arrive.
+ */
+export const FOLLOW_BAND = { back: 0.25, forward: 0.75 } as const;
+
+/**
+ * The `scrollLeft` that brings the playhead back inside the band, or NULL when
+ * it is already inside and nothing should move.
+ *
+ * Null rather than "the current value" on purpose: the caller writes
+ * `el.scrollLeft` only when this answers, so the common case (a playhead in
+ * view) touches no DOM at all — and a write of the same number would still
+ * fire a scroll event and still fight a momentum scroll mid-flight.
+ *
+ * Pure, and that is not tidiness either: jsdom reports every `clientWidth` as 0,
+ * so a lane's geometry can only be exercised from a test by stubbing it. The
+ * arithmetic is the part worth pinning, and it is testable here with no layout
+ * at all.
+ */
+export function followScrollLeft(view: {
+  /** The playhead's x in CONTENT pixels — label column included, because the
+   *  label cell is part of the scrolled content and `left:` is measured from
+   *  the same origin. */
+  playheadPx: number;
+  scrollLeft: number;
+  /** The scroll container's `clientWidth`. */
+  laneW: number;
+  /** `scrollWidth`, so the answer is clamped to what the browser would clamp it
+   *  to anyway. Without this the caller writes a number, the browser stores a
+   *  different one, and every later comparison is against a value that was
+   *  never there. */
+  contentW: number;
+}): number | null {
+  const { playheadPx, scrollLeft, laneW, contentW } = view;
+  if (!(laneW > 0) || !Number.isFinite(playheadPx)) return null;
+  const max = Math.max(0, contentW - laneW);
+  const back = scrollLeft + laneW * FOLLOW_BAND.back;
+  const forward = scrollLeft + laneW * FOLLOW_BAND.forward;
+  let next = scrollLeft;
+  if (playheadPx > forward) next = playheadPx - laneW * FOLLOW_BAND.forward;
+  else if (playheadPx < back) next = playheadPx - laneW * FOLLOW_BAND.back;
+  else return null;
+  next = Math.max(0, Math.min(max, next));
+  // The clamp can land back on where we already are — a playhead past the end
+  // of a document already scrolled to its limit is the ordinary case, and it
+  // must not write a scroll on every frame of the tail.
+  return next === scrollLeft ? null : next;
+}
+
+/** `.dock-ruler`'s height, and the sticky strip the rows scroll under. Paired
+ *  with the CSS rule of the same name: the ruler is the one piece of the
+ *  scroller that does not move vertically, so it is also the top of the usable
+ *  viewport for anything being revealed below it. 28 in every context, the
+ *  boards' ruler: the playhead's 18px pill hangs 5px down with the ticks
+ *  standing up off the floor beside it. */
+export const DOCK_RULER_H = 28;
+
+/** Breathing room around a revealed row, so it lands just inside the edge
+ *  rather than flush against it (or half under the sticky ruler). */
+export const FOLLOW_MARGIN = 8;
+
+/**
+ * The `scrollTop` that brings a shot's row into view, or NULL when it already
+ * is and nothing should move.
+ *
+ * NEAREST, not a band, and that is the difference from `followScrollLeft`
+ * above. The horizontal follow tracks a playhead that moves every frame, so it
+ * pins the head at 0.75 of the lane and lets the content slide under it. This
+ * one is driven by `sceneId`, which moves about once per SHOT — roughly seven
+ * times in a minute of film. Recentring the lane on each of those would be the
+ * panel jumping under an author who is reading it, for no lookahead worth
+ * having. So it moves the minimum distance, and only when the row is actually
+ * outside: it is `scrollIntoView({ block: "nearest" })` written as arithmetic.
+ *
+ * Arithmetic and not the DOM call for two reasons. Past 40 shots the dock
+ * virtualizes and the row may not be MOUNTED, so there is nothing to call the
+ * method on, while the prefix sum over `groupHeights` that positions the
+ * spacers still knows exactly where it would be. And jsdom lays nothing out,
+ * so a DOM-measured follow could not be tested at all.
+ */
+export function followScrollTop(view: {
+  /** The row's y in CONTENT pixels, ruler included: it is inside the scroller
+   *  and above every group, so it is part of the same origin. */
+  rowTop: number;
+  rowH: number;
+  scrollTop: number;
+  /** The scroll container's `clientHeight`. */
+  viewH: number;
+  /** `scrollHeight`, so the answer is clamped where the browser would clamp
+   *  it, for `followScrollLeft`'s reason. */
+  contentH: number;
+  /** The sticky ruler's height: content under it is covered, not visible. */
+  stickyH: number;
+}): number | null {
+  const { rowTop, rowH, scrollTop, viewH, contentH, stickyH } = view;
+  if (!(viewH > 0) || !Number.isFinite(rowTop)) return null;
+  const max = Math.max(0, contentH - viewH);
+  // The visible band, in content pixels: under the ruler, above the bottom.
+  const top = scrollTop + stickyH + FOLLOW_MARGIN;
+  const bottom = scrollTop + viewH - FOLLOW_MARGIN;
+  let next = scrollTop;
+  if (rowTop < top) next = rowTop - stickyH - FOLLOW_MARGIN;
+  else if (rowTop + rowH > bottom) next = rowTop + rowH - viewH + FOLLOW_MARGIN;
+  else return null;
+  next = Math.max(0, Math.min(max, next));
+  return next === scrollTop ? null : next;
+}
+
+/**
+ * Where a layer's row sits in the dock's scrolled content, ruler included (the
+ * origin `followScrollTop` takes), or NULL when no shown group lists it.
+ *
+ * From the same heights the virtual windows place their spacers by, not from
+ * the DOM, for `followScrollTop`'s reason: past the window thresholds the row
+ * being revealed is exactly the one that may not be mounted.
+ *
+ * `leads[i]` is the height of group i above its first layer row: the separator,
+ * the shot row, and the camera rows of a shown shot. `height` is the row with
+ * its open lanes, the entry the layer window holds for it.
+ *
+ * A layer id names a row of one container, but the scene context lists every
+ * shot, so `prefer` (the shot the stage shows) wins a tie before document order.
+ */
+export function rowOffsetOf(
+  groups: readonly { id: string; rows: readonly { layerId: string }[] }[],
+  groupHeights: readonly number[],
+  leads: readonly number[],
+  layerHeights: ReadonlyMap<string, readonly number[]>,
+  layerId: string,
+  prefer: string | null = null,
+): { groupId: string; top: number; height: number } | null {
+  const holds = (index: number): number => {
+    const heights = layerHeights.get(groups[index]!.id) ?? [];
+    const row = groups[index]!.rows.findIndex((r) => r.layerId === layerId);
+    // A closed group lists no heights: its rows are not drawn.
+    return row < heights.length ? row : -1;
+  };
+  let index = groups.findIndex((g) => g.id === prefer);
+  if (index < 0 || holds(index) < 0) index = groups.findIndex((_, i) => holds(i) >= 0);
+  if (index < 0) return null;
+  const heights = layerHeights.get(groups[index]!.id)!;
+  const row = holds(index);
+  let top = DOCK_RULER_H + (leads[index] ?? 0);
+  for (let i = 0; i < index; i += 1) top += groupHeights[i] ?? 0;
+  for (let i = 0; i < row; i += 1) top += heights[i] ?? 0;
+  return { groupId: groups[index]!.id, top, height: heights[row] ?? 0 };
+}
+
+/**
+ * A layer row as the in-container follow reads it: its span in LANE frames,
+ * where it sits in the dock's content (ruler included, `rowOffsetOf`'s
+ * origin) with its open lanes, its depth in the pre-order walk, and whether
+ * its eye is off.
+ */
+export interface FollowRow {
+  in: number;
+  out: number;
+  top: number;
+  height: number;
+  depth: number;
+  hidden: boolean;
+}
+
+/**
+ * Which rows are ON SCREEN at a lane frame, by the runtime's rule and not the
+ * bar's (`useLive` lights a bar by its span alone). `layerAliveAt` drops a
+ * hidden layer, and the render walk stops at a layer that is not alive, so a
+ * child inside its own span is still not drawn while its parent is not. A
+ * row's parent is the nearest row above it one level up: `trackRows` walks
+ * pre-order and `masterRows`' time order keeps children under their parent.
+ */
+export function rowsOnScreenAt(rows: readonly FollowRow[], frame: number): boolean[] {
+  const out: boolean[] = [];
+  // The latest row seen at each depth: the open ancestor of the next one.
+  const chain: boolean[] = [];
+  for (const row of rows) {
+    // An isolated subtree can start below depth 0: its root has no parent row.
+    const parentOn = row.depth === 0 ? true : (chain[row.depth - 1] ?? true);
+    const on = parentOn && !row.hidden && row.in <= frame && frame < row.out;
+    chain[row.depth] = on;
+    chain.length = row.depth + 1;
+    out.push(on);
+  }
+  return out;
+}
+
+/**
+ * THE ROWS THAT CAME ON SCREEN as the playhead moved from `from` to `to`, as
+ * one band from the topmost to the lowest of them, or NULL when none did.
+ *
+ * A difference of two sets, not a crossing of edges, so one answer covers a
+ * playback tick that skipped frames, the reverse shuttle (a row comes on as
+ * the playhead backs into its end), a scrub, and a loop's wrap to the start
+ * (the rows the shot opens with come on again). A row on screen for the whole
+ * run never appears, so a full-length background never pins the view.
+ *
+ * What the band is for is `followScrollTop`: the shot reveal's "nearest", one
+ * scroll per appearance and only when it is out of view, never a scroll per
+ * frame. Rows run in time order, so playback walks the dock down the list the
+ * way the Project's reveal walks it down the shots.
+ */
+export function appearedBand(
+  rows: readonly FollowRow[],
+  from: number,
+  to: number,
+): { top: number; height: number } | null {
+  if (from === to || rows.length === 0) return null;
+  const before = rowsOnScreenAt(rows, from);
+  const after = rowsOnScreenAt(rows, to);
+  let top = Infinity;
+  let bottom = -Infinity;
+  for (let i = 0; i < rows.length; i += 1) {
+    if (!after[i] || before[i]) continue;
+    const row = rows[i]!;
+    top = Math.min(top, row.top);
+    bottom = Math.max(bottom, row.top + row.height);
+  }
+  return top === Infinity ? null : { top, height: bottom - top };
+}
+
+// ── THE MASTER STRIP, AND THE TWO CONTEXTS OVER IT ──────────────────────────
+//
+// The dock was two levels once, keyed on `state.sceneId` — which follows the
+// PLAYHEAD, so the lower half changed under the author every time they scrubbed
+// across a cut. That is the thing that was deleted, and it stays deleted.
 //
-// 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.
+// What replaced it is a real context bit, `state.enteredScene`, written only by
+// the enter/leave verbs:
 //
-// 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.
+//   SCENE context — every shot's rows at their MASTER positions, in master
+//     order, one continuous strip: the sequence read, which is what answers
+//     "what happens between the logo landing and the price appearing" when
+//     those two things are in different shots. The per-element rows are opt-in
+//     here (the summary toggle) because the subject is the arrangement.
+//   SHOT context — one group, re-zeroed on the shot the author OPENED, plus
+//     the master-timed marker and audio lanes clipped to its window. Not the
+//     old scene-follows-playhead mode: nothing but the enter verb can change
+//     what is on screen, so a scrub cannot move the author.
 //
 // 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
+// one missed conversion moves a bar 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.
+//
+// The shot context's re-zero rides that same split, and this is the sharp edge
+// in it: `offsetFrames` STAYS the scene's true master start, because SNAPPING
+// converts through it (`beginSnap` freezes MASTER targets) and `ChannelRow`
+// round-trips the master playhead through it. The re-zero is a second,
+// DRAW-ONLY number — `originFrames` — subtracted in the `left` expressions and
+// nowhere else. Folding the two into one is how a snap in the shot context
+// would land on a frame the same drag reaches in the scene context.
 
 /** A layer's half-open SCENE-LOCAL lifespan, with the default filled in. */
 export interface Lifespan {
@@ -291,7 +960,8 @@ export interface Lifespan {
 }
 
 /**
- * The layer's bar, with an ABSENT `lifetime` resolved to the whole scene.
+ * The layer's bar, with an ABSENT `lifetime` resolved to the whole scene, and
+ * an OPEN `out` resolved to the container's end.
  *
  * 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,
@@ -299,19 +969,323 @@ export interface Lifespan {
  * 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.
+ * An open end (`isOpenEndedOut`: a component placed by an agent with only a
+ * start frame) is the same default at one end: "until the container ends". It
+ * resolves here for the same reason, and every reader downstream gets it for
+ * free. Read raw it was a bar nine quadrillion frames long: the content extent
+ * followed it, and the ruler pushed a tick every few frames of that until V8
+ * refused the array and the dock died with the tab frozen.
+ *
+ * A stored lifespan is otherwise 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. The open
+ * end is not that clamp: the marker has no position to show or pull back, and
+ * nothing is written by resolving it either. A drag that moves the out edge
+ * starts from the resolved end and writes a finite one, as it does for an
+ * absent lifetime; one that moves only the in edge keeps the marker
+ * (`writeLifespan`).
+ *
+ * NEVER BEFORE `in + MIN_LIFESPAN_FRAMES`. A Shot shortened under a placement
+ * (a later `update_scene`, a razor cut before its entrance) leaves `in` at or
+ * past the end, and the end alone is an inverted bar: a negative duration in
+ * the inspector, an extent that stops short of the bar, and an in edge that
+ * jumps back to `out - 1` on the first nudge. A finite window there keeps its
+ * real `out` and the extent follows it; the open one is drawn as its shortest
+ * bar, at its start, and the extent follows that.
+ */
+export function lifespanOf(layer: Layer3D, containerDurationFrames: number): Lifespan {
+  // The rule itself lives in shot (`layerLifespan`), shared with the clip ops
+  // and the motion presets, so the dock cannot draw a window they disagree on.
+  return layerLifespan(layer, containerDurationFrames);
+}
+
+// ── HOW TALL A LIFESPAN ROW IS, AND WHY THE NUMBER LIVES HERE ───────────────
+//
+// `TimelineDock`'s virtual window builds PREFIX SUMS out of `expandedLayerHeight`
+// and positions spacers with them, so a row whose CSS height disagrees with the
+// number the sum used scrolls to the wrong place and the mismatch grows one row
+// at a time. The heights are therefore constants both sides read, not a literal
+// in the sheet and a literal in the sum.
+//
+// A VIDEO row is a CLIP row: a filmstrip over the recording's own waveform. It
+// is 56 tall against an ordinary row's 28, and that budget is spent exactly:
+//
+//   32  picture
+//    1  EDGE between the two, and an edge is what reads. In the light theme
+//       `--panel-raised` IS `--panel`, so a "surface step up" between the strip
+//       and the wave would be invisible; a line is not.
+//   22  waveform
+//   ──
+//   55  the bar, inside the row's own 1px bottom border (`box-sizing` is
+//       border-box globally, so 55 + 1 = `VIDEO_ROW_H`).
+
+/** An ordinary lifespan row, paired with `.lifespan-row`'s CSS height, and the
+ *  left column's outline row (`.layer-row`, var(--row-h)): one row height. */
+export const LAYER_ROW_H = 28;
+/** One `ShotRow`, paired with `.shot-row`'s CSS height. The vertical follow
+ *  reveals exactly this much: a shot's own row, not its expanded contents,
+ *  which can be taller than the dock. 28, the row ruling: the 20px clip sits
+ *  4px under the row's top inside the 1px bottom border. */
+export const SHOT_ROW_H = 28;
+/** A video row: the two strips plus their edge, plus the row's own border. */
+export const VIDEO_ROW_H = 56;
+export const VIDEO_PICTURE_H = 32;
+export const VIDEO_EDGE_H = 1;
+export const VIDEO_WAVE_H = 22;
+/** One `.channel-row`: an animated property, the "No animation" hint, or the
+ *  "+ property" row that ends every expansion. Paired with the CSS height, and
+ *  the unit `expandedLayerHeight` and `groupHeights` count channel rows in.
+ *  28, the row ruling: a channel row is a row like any other, not a sub-row. */
+export const CHANNEL_ROW_H = 28;
+/** One `.block-row`: the shot's camera. Paired with the CSS height, and
+ *  counted by the same two sums. */
+export const BLOCK_ROW_H = 28;
+
+/**
+ * How wide a bar's trim handles are, in px, measured INSIDE its two edges.
+ *
+ * A fixed 8px reads fine on a two-second bar and is absurd on a six-frame one:
+ * at 16px wide the two handles ARE the bar, and the body gesture — the one an
+ * author reaches for first — has nowhere left to be pressed. So: a third of the
+ * bar, never below 3px (smaller is not a pointer target), never above half the
+ * bar (the body has to survive), and never above 10px.
  */
-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 function trimHandlePx(widthPx: number): number {
+  const w = Number.isFinite(widthPx) ? Math.max(0, widthPx) : 0;
+  return Math.min(Math.max(w / 3, 3), w / 2, 10);
+}
+
+/** A stretch of SCENE-LOCAL frames, half-open, where the picture is frozen. */
+export interface HeldSpan {
+  from: number;
+  to: number;
+}
+
+/**
+ * The clip facts a VIDEO row draws with, derived ONCE per document beside the
+ * row rather than per render inside it.
+ *
+ * `masterRows` is memoised on the document's identity and the dock re-renders
+ * for every zoom tick, so a row that re-derived its own clip arithmetic would
+ * re-run `videoClipOf` and re-resolve two assets sixty times a second during a
+ * zoom drag. It also keeps `LifespanRow` free of `doc`: the row reads its own
+ * model and the selection, which is the rule the rest of this lane follows.
+ */
+export interface VideoRow {
+  /** The PICTURE's asset row, which is what `Filmstrip` keys its sheet on (its
+   *  content-addressed `path`). Undefined when the document carries no row for
+   *  `video.asset`, which draws a bar with no strip rather than refusing. */
+  pictureAsset: ShotAsset | undefined;
+  /** The inline soundtrack's asset, handed to the waveform as it is. The OBJECT
+   *  and not its path, because `AudioWaveform` fetches on the identity of this
+   *  prop and a fresh `{ path }` per render would refetch forever. */
+  soundAsset: ShotAsset | undefined;
+  /**
+   * The inline sound's slice of its source, or null when this recording
+   * contributes none to the mix (`videoSoundClip`'s three gates: hidden,
+   * retimed or looping, or a window that never opens).
+   *
+   * Only the two fields the waveform cuts on, with `offsetFrames`' absent-is-0
+   * already resolved: the bar's placement is the LAYER's window, which the row
+   * is drawing anyway, so carrying a whole `AudioClipRef` here would be a second
+   * copy of the frames the lifespan already holds.
+   */
+  sound: { offsetFrames: number; durationFrames: number } | null;
+  /** `video.sound.muted`. Read off the LAYER, not off `sound`, because the
+   *  button must still say what it would toggle when the clip above is null. */
+  muted: boolean;
+  /**
+   * `video.offsetFrames`, absent resolved to 0: the SCENE frame the source's
+   * t=0 lands on, and the thing a SLIP moves.
+   *
+   * Carried because it is a slip's snap anchor. A slip leaves the window where
+   * it is, so snapping the window's `in` would snap a number that is not
+   * moving: the delta would land the FOOTAGE wherever the constant gap between
+   * `in` and the offset happened to put it. `clip.leadFrom` is the same
+   * crossing but is null whenever the window does not sit on the frozen side of
+   * it, which is most of the time and exactly when a slip is being dragged.
+   */
+  offsetFrames: number;
+  /** Present only when the layer declares a soundtrack at all. Nothing to mute
+   *  is not a muted thing, and a dead button is worse than no button. */
+  hasSound: boolean;
+  clip: VideoClipInfo;
+  /** Where the FIRST picture is frozen because the footage has not started,
+   *  clipped to the window. Null when no frame of the window is. */
+  lead: HeldSpan | null;
+  /** Where the LAST picture is frozen because the footage ran out. */
+  hold: HeldSpan | null;
+  /** The layer whose window BEGINS where this one's ends, so the pair has a
+   *  seam a roll can move. `rollSeam` is the authority on whether it does. */
+  rollPartner: string | null;
 }
 
 export interface MasterRow extends TrackRowModel {
   lifespan: Lifespan;
+  /** Set for a `kind: "video"` layer in a SCENE. Absent inside a component
+   *  definition, where a video has no sound and no seam to roll: its frames are
+   *  def-local and the placing instance decides where they land. */
+  video?: VideoRow;
+}
+
+/**
+ * The two frozen stretches of a clip's window, on the scene clock.
+ *
+ * `videoClipOf` reports the two CROSSINGS and leaves the rounding here. What
+ * this function wants out of a crossing is ONE number either way: the boundary
+ * frame between the live stretch and the frozen one, which both halves of a
+ * half-open span are then written from. That number falls out of the clamp in
+ * `sourceTimeAt`, not out of a rounding preference.
+ *
+ * ── THE ROUNDING IS THE RATE'S SIGN, NOT THE SIDE ────────────────────────
+ *
+ * Source time at a scene frame is `(f - offsetFrames) * timeScale`, read at the
+ * frame's LEFT EDGE, which is `VideoClipInfo`'s stated convention. Work out
+ * which frames the clamp is holding, on each end and each sign:
+ *
+ *   FORWARD the lead clamps below t=0, so a frame is frozen while `f < cross`,
+ *   and the run-out clamps above the duration, so a frame is frozen once
+ *   `f >= cross`. Both boundaries are the smallest integer at or past the
+ *   crossing, which is `ceil(cross)`.
+ *
+ *   BACKWARD source time runs DOWN as the scene runs on, so both inequalities
+ *   flip: the lead freezes while `f > cross` and the run-out while `f <= cross`.
+ *   Both boundaries are now the smallest integer STRICTLY past the crossing,
+ *   which is `floor(cross) + 1`.
+ *
+ * The two agree on a fractional crossing and differ by exactly one on a whole
+ * one, which is the case that actually ships: `leadFrom` IS `offsetFrames`, a
+ * whole frame in every document that validates. Ceiling both signs therefore
+ * shaded the last LIVE frame of every reversed clip as frozen, on every one of
+ * them, and the fractional rows that would have caught it agree by luck.
+ *
+ * WHICH END IS WHICH is the sign too, and `VideoClipInfo`'s header states it:
+ * the frozen first picture is the window's HEAD forward and its TAIL backward,
+ * and the run-out is whichever one is left. Derived here beside the rounding
+ * rather than at the call site, so the one branch the sign owns is one branch.
+ */
+function heldSpan(
+  win: Lifespan,
+  cross: number | null,
+  end: "lead" | "hold",
+  forward: boolean,
+): HeldSpan | null {
+  if (cross === null || !Number.isFinite(cross)) return null;
+  const at = forward ? Math.ceil(cross) : Math.floor(cross) + 1;
+  const head = end === "lead" ? forward : !forward;
+  if (head) {
+    const to = Math.min(at, win.out);
+    return to > win.in ? { from: win.in, to } : null;
+  }
+  const from = Math.max(at, win.in);
+  return from < win.out ? { from, to: win.out } : null;
+}
+
+/**
+ * One video layer's row model.
+ *
+ * `byIn` maps a scene-local `in` frame to the CLIP that starts there, built
+ * once per scene so finding an abutting neighbour is a lookup rather than a
+ * scan per row; `null` there is a frame two clips contest, which names no
+ * partner at all (see `clipsByIn`). A named one is still only a CANDIDATE:
+ * `rollSeam` decides whether the pair actually has a seam, because that verdict
+ * has exactly one home (a collapsed `legalRollRange` reads the same as a
+ * genuine one-frame range, which is the confusion `rollSeam` exists to end).
+ */
+function videoRowOf(
+  doc: Doc3D,
+  scene: Scene3D,
+  layer: VideoLayer3D,
+  byIn: ReadonlyMap<number, string | null>,
+): VideoRow {
+  const clip = videoClipOf(layer, scene.durationFrames, doc.fps, doc.assets[layer.video.asset]);
+  const sound = videoSoundClip(layer, scene.durationFrames);
+  const forward = (layer.video.timeScale ?? 1) > 0;
+  const win: Lifespan = { in: clip.in, out: clip.out };
+  const candidate = byIn.get(clip.out);
+  return {
+    pictureAsset: doc.assets[layer.video.asset],
+    soundAsset: sound === null ? undefined : doc.assets[sound.asset],
+    sound: sound === null ? null : { offsetFrames: sound.offsetFrames ?? 0, durationFrames: sound.durationFrames },
+    muted: layer.video.sound?.muted === true,
+    hasSound: layer.video.sound !== undefined,
+    offsetFrames: layer.video.offsetFrames ?? 0,
+    clip,
+    lead: heldSpan(win, clip.leadFrom, "lead", forward),
+    hold: heldSpan(win, clip.holdFrom, "hold", forward),
+    // `typeof` rather than a nullish test, because the map has THREE answers
+    // and two of them mean "no partner": absent (nothing starts there) and null
+    // (two clips do, so which one is not the index's to pick).
+    rollPartner:
+      typeof candidate !== "string" || rollSeam(doc, scene.id, layer.id, candidate) === null ? null : candidate,
+  };
+}
+
+/**
+ * IS THIS A CLIP ROW? The answer is the row's clip facts, or nothing.
+ *
+ * ONE PREDICATE, AND IT HAS TWO READERS, because those two are a pair:
+ * `LifespanRow` draws a clip bar from it, and `expandedLayerHeight` in
+ * TimelineDock sizes the row from it. The dock's virtual window builds PREFIX
+ * SUMS out of that height and positions every spacer beneath this row with
+ * them, so the two answers are one fact or the list shears.
+ *
+ * THEY DISAGREED INSIDE A COMPONENT DEFINITION, which is the case that needs
+ * both halves and not just the layer's kind. `defGroup` carries no `video` on
+ * its rows on purpose: a definition's frames are def-local, so its video has no
+ * sound and no seam, and the placing instance decides where they land. The
+ * height keyed on `layer.kind === "video"` alone, so the dock reserved 56px,
+ * the row drew 28, and every row below it sat 28px out.
+ *
+ * It also answers the stale-row case the render has always needed: a row whose
+ * layer has just been deleted under a render still carries `row.video`, and a
+ * 56px bar drawn where the prefix sum said 28 shears the same list the same
+ * way.
+ *
+ * It lives HERE, beside `videoRowOf` which mints the thing it reads, and not in
+ * the component that draws it: a predicate two panels answer with is a model
+ * fact, and importing one leaf component from another to get at it is the
+ * shape that made the two disagree in the first place.
+ */
+export function clipRowOf(
+  layer: Layer3D | undefined,
+  row: { video?: VideoRow | undefined },
+): VideoRow | undefined {
+  return layer?.kind === "video" ? row.video : undefined;
+}
+
+/**
+ * Scene-local `in` frame -> the CLIP that starts there, or null when more than
+ * one does.
+ *
+ * ── A ROLL IS A CLIP GESTURE, AND THIS INDEX IS WHERE THAT IS TRUE ──────
+ *
+ * The header's own sentence for a roll is "this clip's tail and the next clip's
+ * head trade frames", the handle renders on clip rows alone, and the range the
+ * seam is bounded by (`legalRollRange`) is built out of both partners' FOOTAGE
+ * bounds. Indexing every layer kind made a liar of all three: a rect that
+ * happened to abut a clip became its partner, and the drag then moved a seam
+ * between a recording and a rectangle. So only `kind: "video"` layers are
+ * candidates, and a rect abutting a clip simply is not one.
+ *
+ * ── AND NULL IS A REFUSAL, NOT A MISS ───────────────────────────────────
+ *
+ * This used to be first-writer-wins in `layersById` order, which is an order no
+ * author can see and no document promises: two clips starting on the same frame
+ * meant the partner you rolled against depended on key order, and the same
+ * gesture on the same picture could write to either one. Refusal over
+ * corruption: a contested frame has no unambiguous "next clip", so it names
+ * none, the handle does not render, and the author trims an edge instead.
+ */
+function clipsByIn(scene: Scene3D): Map<number, string | null> {
+  const out = new Map<number, string | null>();
+  for (const layer of Object.values(scene.layersById)) {
+    if (layer.kind !== "video") continue;
+    const at = lifespanOf(layer, scene.durationFrames).in;
+    out.set(at, out.has(at) ? null : layer.id);
+  }
+  return out;
 }
 
 /** One scene's whole block of rows, placed on the master timeline. */
@@ -323,15 +1297,54 @@ export interface MasterSceneGroup {
   end: number;
   /** The camera's shots. SCENE-LOCAL, like every other bar here. */
   camera: BlockBar[];
+  /** The camera's POSES (P4), derived once with the group rather than per
+   *  render of the row: `cameraMarks` scans a path move's frames to invert its
+   *  ease, and the dock re-renders on every ppf change — so a zoom drag would
+   *  otherwise re-run that scan sixty times a second. */
+  cameraKeys: CameraMark[];
   rows: MasterRow[];
 }
 
+/**
+ * THE DOCK READS IN TIME ORDER: siblings sorted by where their lifespan starts,
+ * earliest on top. `rows` is a pre-order walk (`trackRows`), front first, so a
+ * tie keeps the stacking order. Children stay under their parent and are sorted
+ * among themselves the same way. The Layers panel keeps the stacking order;
+ * this is the dock's reading only, since a timeline is read left to right and
+ * top to bottom.
+ */
+export function timeOrder<R extends { depth: number; lifespan: Lifespan }>(rows: readonly R[]): R[] {
+  type Node = { row: R; kids: Node[] };
+  const roots: Node[] = [];
+  const path: Node[] = [];
+  for (const row of rows) {
+    const node: Node = { row, kids: [] };
+    path.length = Math.min(path.length, row.depth);
+    (path[path.length - 1]?.kids ?? roots).push(node);
+    path.push(node);
+  }
+  const out: R[] = [];
+  const emit = (nodes: Node[]): void => {
+    // `sort` is stable, so equal starts keep the walk's front-first order.
+    for (const n of [...nodes].sort((a, b) => a.row.lifespan.in - b.row.lifespan.in)) {
+      out.push(n.row);
+      emit(n.kids);
+    }
+  };
+  emit(roots);
+  return out;
+}
+
 /** 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 [];
+    // Built from the WHOLE scene and not from the rows: an isolation narrows
+    // what is drawn, and a clip still abuts the neighbour it abuts whether or
+    // not that neighbour has a row on screen.
+    const byIn = clipsByIn(scene);
     return [
       {
         id: w.id,
@@ -339,13 +1352,22 @@ export function masterRows(doc: Doc3D, isolation: string | null = null): MasterS
         start: w.start,
         end: w.end,
         camera: cameraBars(scene),
+        cameraKeys: cameraMarks(scene, doc.fps),
         // 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),
-        })),
+        rows: timeOrder(
+          trackRows(scene, scene.layersById[isolation ?? ""] === undefined ? null : isolation).map((row) => {
+            const layer = scene.layersById[row.layerId]!;
+            const lifespan = lifespanOf(layer, scene.durationFrames);
+            // Spread-or-omit rather than `video: undefined`, because
+            // `exactOptionalPropertyTypes` is on and an explicitly undefined
+            // optional is not the same thing as an absent one.
+            return layer.kind === "video"
+              ? { ...row, lifespan, video: videoRowOf(doc, scene, layer, byIn) }
+              : { ...row, lifespan };
+          }),
+        ),
       },
     ];
   });
@@ -354,7 +1376,7 @@ export function masterRows(doc: Doc3D, isolation: string | null = null): MasterS
 /**
  * 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
+ * Not `docDurationFrames`: a lifespan or a camera move 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.
  */
@@ -363,13 +1385,97 @@ export function masterContentFrames(doc: Doc3D, groups: readonly MasterSceneGrou
   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);
   }
+  // The two MASTER-timed lanes, on the same argument the rows make: a clip
+  // dragged past the last shot has to stay scrollable-to, or it cannot be
+  // dragged back. They were left out while the lanes drew unclipped and it did
+  // not show; the shot context clips them to its window, so an extent that
+  // stopped short would now hide the tail of a bed rather than let it overhang.
+  for (const { clip } of masterAudioClips(doc)) {
+    end = Math.max(end, Math.trunc(clip.frame) + Math.max(1, Math.trunc(clip.durationFrames)));
+  }
+  for (const marker of doc.markers ?? []) end = Math.max(end, Math.trunc(marker.frame) + 1);
   return end;
 }
 
+/**
+ * ONE SHOT's content extent, in SHOT-LOCAL frames — `masterContentFrames`' twin
+ * for the shot context, the way `defContentFrames` is for the component one.
+ *
+ * Never `masterContentFrames` with one group: that floors at the whole
+ * document's duration, so an eight-frame shot inside a fifty-second video would
+ * open with a ruler fifty seconds wide and its own bars in the first pixel.
+ */
+export function shotContentFrames(group: MasterSceneGroup): number {
+  let end = group.end - group.start;
+  for (const row of group.rows) {
+    end = Math.max(end, row.lifespan.out);
+  }
+  for (const bar of group.camera) end = Math.max(end, bar.frame + bar.durationFrames);
+  return end;
+}
+
+/**
+ * THE ISOLATED SUBTREE'S LIFESPAN UNION, in SCENE-LOCAL frames: the earliest
+ * `in` and the latest `out` over the root and every layer under it, the same
+ * rows `trackRows` lists for that isolation. Null when the scene does not hold
+ * the id, or the union is empty.
+ *
+ * What the dock fits on entering isolation, and the span its follow holds to,
+ * so an object that lives for one second of a ten-second shot is not drawn as
+ * a sliver nor scrolled away from while the rest of the shot plays.
+ */
+export function isolationSpan(scene: Scene3D, isolation: string): Lifespan | null {
+  if (scene.layersById[isolation] === undefined) return null;
+  let from = Infinity;
+  let to = -Infinity;
+  for (const row of trackRows(scene, isolation)) {
+    const layer = scene.layersById[row.layerId];
+    if (layer === undefined) continue;
+    const life = lifespanOf(layer, scene.durationFrames);
+    from = Math.min(from, life.in);
+    to = Math.max(to, life.out);
+  }
+  return Number.isFinite(from) && to > from ? { in: from, out: to } : null;
+}
+
+/** One audio row, the master bed's lane and a shot's own Sound row alike.
+ *  Paired with `.audio-lane` and `.scene-audio-row`'s CSS height. */
+export const AUDIO_ROW_H = 32;
+/** `.marker-lane`'s CSS height, its 1px top border included. */
+export const MARKER_LANE_H = 20;
+/** `.dock-scroll`'s padding-bottom (`--space-3`). */
+const DOCK_SCROLL_PAD_H = 6;
+
+/**
+ * THE DOCK BODY'S HEIGHT WITH EVERY SHOT FOLDED, in px: the ruler plus the rows
+ * a first look shows. `fitShell` sizes an untouched dock to this, so the stage
+ * gets every pixel the timeline does not draw.
+ *
+ * Inside a shot: Shot, Camera and Sound, plus the master bed when one overlaps
+ * the shot (`AudioLane`'s own early return). Over the Project: one row per shot
+ * and the separators between them, plus the master bed, which is always drawn
+ * there. The marker lane in both, once the document has a marker.
+ */
+export function foldedDockContentH(doc: Doc3D, enteredScene: string | null): number {
+  const windows = sceneWindows(doc);
+  const shot = enteredScene === null ? undefined : windows.find((w) => w.id === enteredScene);
+  let rows: number;
+  if (shot !== undefined) {
+    const bed = Object.values(doc.audio).some((clip) => {
+      const start = Math.trunc(clip.frame);
+      return start + Math.max(1, Math.trunc(clip.durationFrames)) > shot.start && start < shot.end;
+    });
+    rows = SHOT_ROW_H + BLOCK_ROW_H + AUDIO_ROW_H + (bed ? AUDIO_ROW_H : 0);
+  } else {
+    rows = windows.length * SHOT_ROW_H + Math.max(0, windows.length - 1) + AUDIO_ROW_H;
+  }
+  const markers = (doc.markers ?? []).length > 0 ? MARKER_LANE_H : 0;
+  return DOCK_RULER_H + rows + markers + DOCK_SCROLL_PAD_H;
+}
+
 /**
  * The dock's one time string.
  *
@@ -395,11 +1501,202 @@ export function timecode(frame: number, fps: Rational): string {
   return minutes === 0 ? fixed : `${minutes}:${fixed.padStart(5, "0")}`;
 }
 
-// ── THE LIFESPAN'S THREE GESTURES ───────────────────────────────────────────
+/**
+ * THE CHROME'S ONE DURATION STRING: seconds, two decimals, no space ("18.00s",
+ * "2.50s", "125.50s"). Paper's format, and the founder's ruling: a LENGTH
+ * reads this way everywhere it is printed (a shot's row, the Tool footer, the
+ * inspector head, the storyboard, a sound's trailing value), so one shot is
+ * one string wherever the eye meets it. POSITIONS keep the clock (`timecode`,
+ * `clock`, the rulers) and frame counts keep "60f": a clock says
+ * where, this says how long, and the two never share a form.
+ *
+ * Never a minute prefix: a length is compared against other lengths, and
+ * "1:05" beside "58.00s" would make the eye convert. A length is never
+ * negative and never NaN, so either reads as nothing at all.
+ */
+export function formatDuration(seconds: number): string {
+  return `${(Number.isFinite(seconds) && seconds > 0 ? seconds : 0).toFixed(2)}s`;
+}
+
+const pad2 = (n: number): string => String(n).padStart(2, "0");
+
+/**
+ * THE TRANSPORT CHIP'S CLOCK: always "MM:SS.hh" ("00:02.20").
+ *
+ * Padded, unlike `timecode`, because the chip is a fixed slot in the head: a
+ * readout whose width changes at every whole second shoves the suffix beside
+ * it sideways. Rounded to the hundredth in INTEGER hundredths, so 59.996s
+ * carries into "01:00.00" rather than printing "00:60.00". Minutes keep
+ * counting past an hour ("75:00.00").
+ */
+export function clock(frame: number, fps: Rational): string {
+  const h = Math.round((frame * fps.den * 100) / fps.num);
+  const abs = Math.abs(h);
+  return `${h < 0 ? "-" : ""}${pad2(Math.floor(abs / 6000))}:${pad2(Math.floor(abs / 100) % 60)}.${pad2(abs % 100)}`;
+}
+
+/**
+ * THE PLAYHEAD PILL'S READING: decimal seconds, always two places ("2.20",
+ * "8.00"), and a minute prefix only past a minute ("1:07.50"). Unlike
+ * `timecode` a whole second keeps its decimals, so the pill holds one width
+ * while it moves. Rounded in integer hundredths, like `clock`.
+ */
+export function playheadLabel(frame: number, fps: Rational): string {
+  const h = Math.round((frame * fps.den * 100) / fps.num);
+  const abs = Math.abs(h);
+  const minutes = Math.floor(abs / 6000);
+  const rest = `${Math.floor(abs / 100) % 60}.${pad2(abs % 100)}`;
+  return `${h < 0 ? "-" : ""}${minutes === 0 ? rest : `${minutes}:${rest.padStart(5, "0")}`}`;
+}
+
+// ── THE DOCK RULER'S TICKS: THREE TIERS ON A SECONDS LADDER ────────────────
 //
-//   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.
+// The package `Ruler` steps one tier of labelled ticks over a FRAME ladder,
+// which is what a keyframe lane wants. The dock spans a whole video, so it
+// counts SECONDS, and three tiers (labelled majors, mids, minors) say where in
+// a second the playhead is without a label on every tick.
+//
+// Each row is [major, mid, minor] in seconds. Every ratio inside a row is an
+// integer, so all three tiers are read off ONE index over the finest step and
+// a tick is never drawn twice.
+
+/** [major, mid, minor] seconds; `null` is no minor tier at this zoom. */
+const RULER_LADDER: readonly (readonly [number, number, number | null])[] = [
+  [0.1, 0.05, null],
+  [0.2, 0.1, null],
+  [0.5, 0.25, 0.05],
+  [1, 0.5, 0.25],
+  [2, 1, 0.25],
+  [5, 1, 0.5],
+  [10, 5, 1],
+  [30, 10, 5],
+  [60, 30, 10],
+  [120, 60, 10],
+  [300, 60, 30],
+  [600, 300, 60],
+  [1800, 600, 300],
+  [3600, 1800, 600],
+];
+
+/** The narrowest spacing a labelled major may have: room for "1:30" and air. */
+export const RULER_LABEL_PX = 64;
+/** A tier closer than this is noise, not a scale, and is not drawn. */
+const RULER_TIER_MIN_PX = 6;
+/** The same ceiling `rulerTicks` holds, for the same reason: a stored extent
+ *  far past its Shot must not become millions of spans. */
+const RULER_MAX_TICKS = 20000;
+
+export interface DockRulerTick {
+  /** Lane frame (fractional: a quarter second at 30 fps is 7.5 frames). */
+  frame: number;
+  /** Exact seconds, for the label. */
+  seconds: number;
+  /** 0 major (labelled), 1 mid, 2 minor. */
+  tier: 0 | 1 | 2;
+}
+
+/**
+ * The ticks from 0 to `extentF` lane frames at `ppf` pixels per frame: the
+ * first ladder row whose major spacing clears `RULER_LABEL_PX`, less any tier
+ * under `RULER_TIER_MIN_PX`, and the row coarsened until the count is bounded.
+ */
+export function dockRulerTicks(extentF: number, ppf: number, fps: Rational): DockRulerTick[] {
+  const pxPerSecond = (ppf * fps.num) / fps.den;
+  const endS = Number.isFinite(extentF) ? Math.max(0, (extentF * fps.den) / fps.num) : 0;
+  if (!(pxPerSecond > 0)) return [{ frame: 0, seconds: 0, tier: 0 }];
+  let row = RULER_LADDER.findIndex(([major]) => major * pxPerSecond >= RULER_LABEL_PX);
+  if (row === -1) row = RULER_LADDER.length - 1;
+  for (;;) {
+    const [major, mid, minor] = RULER_LADDER[row]!;
+    const steps = [major, mid, minor].filter(
+      (s): s is number => s !== null && s * pxPerSecond >= RULER_TIER_MIN_PX,
+    );
+    const finest = steps[steps.length - 1]!;
+    if (endS / finest <= RULER_MAX_TICKS || row === RULER_LADDER.length - 1) {
+      const majorEvery = Math.round(major / finest);
+      const midEvery = Math.round(mid / finest);
+      const count = Math.min(Math.floor(endS / finest + 1e-9), RULER_MAX_TICKS);
+      const ticks: DockRulerTick[] = [];
+      for (let i = 0; i <= count; i++) {
+        // Rounded to the millisecond so 0.05 * 3 labels "0.15", not 0.15000000000000002.
+        const seconds = Math.round(i * finest * 1000) / 1000;
+        ticks.push({
+          frame: (seconds * fps.num) / fps.den,
+          seconds,
+          tier: i % majorEvery === 0 ? 0 : i % midEvery === 0 ? 1 : 2,
+        });
+      }
+      return ticks;
+    }
+    row++;
+  }
+}
+
+/** A ruler label's width per character at `.dock-tick-label`'s 12px numeric
+ *  face. An estimate on purpose: reading layout for it would force a reflow per
+ *  label on every zoom step, and the face's digits are tabular, so a count of
+ *  characters is close to the drawn width. Slightly generous, so an estimate
+ *  that is off errs toward hiding a label rather than overlapping two. */
+const RULER_LABEL_CHAR_PX = 7.4;
+/** `.dock-tick-label`'s inset from its tick, on either side (var(--space-2)). */
+const RULER_LABEL_INSET_PX = 4;
+/** The least air between two labels' boxes. */
+const RULER_LABEL_GAP_PX = 4;
+
+export type RulerLabelPlace = "start" | "end" | "hidden";
+
+/**
+ * WHERE EACH MAJOR'S LABEL GOES: right of its tick ("start"), left of it
+ * ("end", `.is-end`) when a start label would run off the lane, or nowhere.
+ *
+ * The end label reads back INTO the lane, which puts it on top of the previous
+ * major's label whenever the two ticks are closer than both labels' widths:
+ * `dockRulerTicks` only promises `RULER_LABEL_PX` between majors, and "1:30"
+ * beside "1:40" needs more than that once one of them is flipped. So, walking
+ * from the end, a label whose box would reach the next shown one is dropped.
+ * The END label wins, because it is the one that says how long the lane is.
+ */
+export function rulerLabelPlaces(
+  majors: readonly { x: number; text: string }[],
+  timeW: number,
+): RulerLabelPlace[] {
+  const width = (text: string): number => text.length * RULER_LABEL_CHAR_PX;
+  const places = majors.map(({ x, text }): RulerLabelPlace =>
+    x > 0 && x + RULER_LABEL_INSET_PX + width(text) > timeW ? "end" : "start",
+  );
+  let limit = Infinity; // the left edge of the next label that is shown
+  for (let i = majors.length - 1; i >= 0; i--) {
+    const { x, text } = majors[i]!;
+    const left = places[i] === "end" ? x - RULER_LABEL_INSET_PX - width(text) : x + RULER_LABEL_INSET_PX;
+    if (left + width(text) + RULER_LABEL_GAP_PX > limit) {
+      places[i] = "hidden";
+      continue;
+    }
+    limit = left;
+  }
+  return places;
+}
+
+/** Seconds rounded to the hundredth, as a number, so `${s}` prints "0.5". */
+const centi = (s: number): number => Math.round(s * 100) / 100;
+
+/** THE RULER'S LABEL, in every context: a clock, "0:00", "0:02", "1:15", and
+ *  "0:00.5" between seconds. The same position form as `timecode`, so the
+ *  ruler, the playhead chip and the marker tooltips read one time. */
+export function rulerLabel(seconds: number): string {
+  const s = centi(seconds);
+  const m = Math.floor(s / 60);
+  const rest = centi(s - m * 60);
+  const whole = Math.floor(rest);
+  const frac = String(centi(rest - whole)).slice(1); // "" or ".5" / ".25"
+  return `${m}:${pad2(whole)}${frac}`;
+}
+
+// ── THE LIFESPAN'S GESTURES: THREE ON ANY BAR ───────────────────────────────
+//
+//   BODY moves the bar AND every keyframe on the layer by the same delta.
+//   SLIP  moves every keyframe and leaves the bar where it is.
+//   IN / OUT move one end and touch no keyframe 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,
@@ -407,13 +1704,38 @@ export function timecode(frame: number, fps: Rational): string {
 // 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
+// EVERY MODE CLAMPS ON THE LEFT ONLY. A keyframe's 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";
+// ── AND THE TWO A VIDEO CLIP ADDS ───────────────────────────────────────────
+//
+// A word names a gesture on ONE bar, which is all four above ever needed. Two
+// of the clip gestures need an ID the word cannot hold — which OTHER bars a
+// body drag is carrying, and which neighbour a roll is rolling against — so
+// those two are objects.
+//
+// THEY ARE OBJECTS RATHER THAN EXTRA ARGUMENTS on purpose: `dragLifespan` on
+// the store takes `(sceneId, layerId, mode, delta)` and hands `mode` straight
+// to this function, so a gesture that carries its own payload in the mode needs
+// no change to the store's signature and cannot be called with the payload
+// missing.
+
+/** A body drag carrying every bar in the list, not just the pressed one. */
+export interface LifespanMove {
+  move: readonly string[];
+}
+/** A roll of the seam this bar's `out` shares with `roll`'s `in`. */
+export interface LifespanRoll {
+  roll: string;
+}
+/** A body drag that FANS the bars out: rank i of `staggerOrder` moves i steps. */
+export interface LifespanStagger {
+  stagger: readonly string[];
+}
+export type LifespanDrag = "body" | "in" | "out" | "slip" | "shift" | LifespanMove | LifespanRoll | LifespanStagger;
 
 /** The shortest lifespan an edge drag may leave behind. `validate.ts` demands
  *  `out > in`; this is that rule with the integer grid applied. */
@@ -431,34 +1753,91 @@ export function writeLifespan(
   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);
+  // Any CONTAINER (unify P2): the def-local dock drags an interior layer's
+  // lifespan with the definition's id in the sceneId slot.
+  const home = homeOf(doc, sceneId);
+  const layer = home?.layersById[layerId];
+  if (home === null || layer === undefined) return doc;
+  const containerDuration = isDefId(sceneId)
+    ? defDurationFrames(doc.components![sceneId]!)
+    : Math.trunc(doc.scenesById[sceneId]!.durationFrames);
+  const life = lifespanOf(layer, containerDuration);
   const d = Math.round(delta);
+  if (!Number.isFinite(d)) return doc;
+
+  // ── THE TWO GESTURES THAT NAME A SECOND LAYER ─────────────────────────
+  //
+  // Both are pair or group edits, so neither can be expressed as a patch of the
+  // pressed layer the way the four word gestures below are, and both go
+  // straight to the op that owns the arithmetic. A roll asks `rollSeam` first
+  // because that is the ONE place a pair's touching is decided: `rollLayers`
+  // would refuse a pair with no seam anyway, and asking here is what turns the
+  // delta into the absolute frame the op wants.
+  if (typeof mode !== "string") {
+    if ("roll" in mode) {
+      const seam = rollSeam(doc, sceneId, layerId, mode.roll);
+      return seam === null ? doc : rollLayers(doc, sceneId, layerId, mode.roll, seam + d);
+    }
+    if ("stagger" in mode) return staggerLayers(doc, sceneId, staggerOrder(home, mode.stagger, containerDuration), d);
+    return moveLayers(doc, sceneId, mode.move, d);
+  }
+
+  // The one-bar slide. `shiftLayer` carries the window, the tracks
+  // and the content clock together, so the picture at the new `in` is the
+  // picture that was at the old one — and it REFUSES rather than clamps, which
+  // is why it is not folded into the clamped `body` case below.
+  if (mode === "shift") return shiftLayer(doc, sceneId, layerId, d);
+
+  // ── THE VIDEO FORK ────────────────────────────────────────────────────
+  //
+  // A clip's edges are bounded by its FOOTAGE as well as by its scene, and its
+  // body carries the recording under it. Writing `lifetime` here would produce
+  // a window over frames the recording does not have (an edge) or slide the
+  // footage under a bar that only moved (a body) — the two states the clip ops
+  // were written to refuse. So a video layer in a SCENE writes through them.
+  //
+  // NOT INSIDE A DEFINITION. The clip ops resolve their layer through
+  // `doc.scenesById`, and a `cmp_` container is not there: they would refuse
+  // every gesture silently. A definition's video has no sound and no seam
+  // either (its frames are def-local; the placing instance decides where they
+  // land), so the ordinary body below is the honest behaviour there.
+  if (layer.kind === "video" && !isDefId(sceneId)) {
+    switch (mode) {
+      case "in":
+        return trimLayer(doc, sceneId, layerId, "in", life.in + d);
+      case "out":
+        return trimLayer(doc, sceneId, layerId, "out", life.out + d);
+      case "slip":
+        return slipLayer(doc, sceneId, layerId, d);
+      case "body":
+        return moveLayers(doc, sceneId, [layerId], d);
+    }
+  }
+
   let next: Layer3D;
 
   switch (mode) {
     case "body": {
-      // ONE clamped delta for the bar and the blocks together. Clamping them
+      // ONE clamped delta for the bar and the keys 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)));
+      // zero while its keys kept sliding, and the author would have retimed
+      // the animation by dragging the layer. `firstKeyframeFrame` is Infinity
+      // with no keys, so the `Math.min` against it is a no-op.
+      const moved = Math.max(d, -Math.min(life.in, firstKeyframeFrame(layer.tracks)));
       if (moved === 0) return doc;
       next = {
         ...layer,
         lifetime: { in: life.in + moved, out: life.out + moved },
-        blocks: shiftBlocks(layer.blocks, moved),
-      };
+        ...shiftedKeys(layer, moved),
+      } as Layer3D;
       break;
     }
     case "slip": {
-      const earliest = earliestBlock(layer);
+      const earliest = firstKeyframeFrame(layer.tracks);
       if (!Number.isFinite(earliest)) return doc;
       const moved = Math.max(d, -earliest);
       if (moved === 0) return doc;
-      next = { ...layer, blocks: shiftBlocks(layer.blocks, moved) };
+      next = { ...layer, ...shiftedKeys(layer, moved) } as Layer3D;
       break;
     }
     // An edge that lands where it already was returns the document BY
@@ -468,7 +1847,11 @@ export function writeLifespan(
     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 } };
+      // An OPEN end stays open: this gesture moved the head, not the tail, and
+      // closing it would end the placement short of a Shot lengthened later.
+      // `splitLayer` and `trimLayer` keep it for the same reason.
+      const out = layer.lifetime !== undefined && isOpenEndedOut(layer.lifetime.out) ? layer.lifetime.out : life.out;
+      next = { ...layer, lifetime: { in: at, out } };
       break;
     }
     case "out": {
@@ -479,19 +1862,156 @@ export function writeLifespan(
     }
   }
 
+  return patchHome(doc, sceneId, {
+    layers: home.layers,
+    layersById: { ...home.layersById, [layerId]: next },
+  });
+}
+
+/**
+ * Slide these layers whole, ALL OR NOTHING.
+ *
+ * ── WHY THE WHOLE SELECTION AND NOT THE PRESSED BAR ─────────────────────
+ *
+ * Selecting three clips and dragging one of them moves all three in every NLE,
+ * and the dock already selects the pressed bar before the drag starts. Moving
+ * only the one the pointer is on would silently break the arrangement the
+ * author selected in order to preserve.
+ *
+ * ── WHY IT REFUSES INSTEAD OF MOVING WHAT IT CAN ────────────────────────
+ *
+ * `shiftLayer` refuses — by returning the document it was handed — when a
+ * window would leave the scene or a keyframe would pass zero. Applying the rest
+ * anyway would move part of a selection and leave the rest, which is a
+ * rearrangement the author did not ask for, cannot see the shape of, and undoes
+ * as one entry. So the first refusal refuses the gesture: nothing moves, the
+ * bars stay where they were, and the next pixel of travel is tried against the
+ * same base.
+ *
+ * IDS THAT ARE NOT IN THIS CONTAINER refuse for the same reason, because
+ * `shiftLayer` answers an unknown layer with the same unchanged document. A
+ * selection that spans two scenes therefore does not move, which is honest: a
+ * signed delta means the same thing in both clocks, but the two windows are
+ * bounded by different scenes and half of them landing is the state above.
+ */
+export function moveLayers(
+  doc: Doc3D,
+  sceneId: string,
+  layerIds: readonly string[],
+  byFrames: number,
+): Doc3D {
+  const by = Math.round(byFrames);
+  if (by === 0 || !Number.isFinite(by) || layerIds.length === 0) return doc;
+  let next = doc;
+  for (const id of layerIds) {
+    const moved = shiftLayer(next, sceneId, id, by);
+    if (moved === next) return doc;
+    next = moved;
+  }
+  return next;
+}
+
+/**
+ * The order a stagger fans `ids` out in: by each bar's `in`, earliest first,
+ * and a tie by OUTLINE order (the dock's rows, top to bottom), so two bars that
+ * start together fan out the way the author reads them. Ids not in `home` are
+ * kept at the end, so `staggerLayers` can refuse them rather than drop them.
+ */
+export function staggerOrder(
+  home: LayerHome,
+  ids: readonly string[],
+  containerDurationFrames: number,
+): string[] {
+  const outline = new Map(trackRows(home).map((r, i) => [r.layerId, i] as const));
+  const start = (id: string): number => {
+    const layer = home.layersById[id];
+    return layer === undefined ? Infinity : lifespanOf(layer, containerDurationFrames).in;
+  };
+  const rank = (id: string): number => outline.get(id) ?? Infinity;
+  return [...ids].sort((a, b) => start(a) - start(b) || rank(a) - rank(b));
+}
+
+/**
+ * Move `ordered[i]` by `i * step`: the first bar stays, each next one a step
+ * further. ALL OR NOTHING, `moveLayers`' rule and for its reason: a fan with one
+ * bar refused is a rearrangement nobody asked for.
+ */
+export function staggerLayers(doc: Doc3D, sceneId: string, ordered: readonly string[], step: number): Doc3D {
+  const by = Math.round(step);
+  if (by === 0 || !Number.isFinite(by) || ordered.length < 2) return doc;
+  let next = doc;
+  for (const [i, id] of ordered.entries()) {
+    if (i === 0) {
+      // Rank 0 does not move, but an id outside this container still refuses.
+      if (homeOf(doc, sceneId)?.layersById[id] === undefined) return doc;
+      continue;
+    }
+    const moved = shiftLayer(next, sceneId, id, i * by);
+    if (moved === next) return doc;
+    next = moved;
+  }
+  return next;
+}
+
+/** Every keyframe on `layer` moved by `delta`, as a patch. No per-key clamp,
+ *  deliberately: the caller has already clamped the DELTA against the earliest
+ *  key, so none can go negative, and a floor here would break the one thing a
+ *  body drag and a slip promise, that every key moved by the same amount.
+ *  `shiftTracks` subtracts, so a move LATER passes a negative. */
+function shiftedKeys(layer: Layer3D, delta: number): ReturnType<typeof tracksPatch> {
+  return tracksPatch(shiftTracks(layer.tracks, -delta));
+}
+
+// ── THE DEF-LOCAL STRIP (the component context's dock, unify P2) ────────────
+//
+// A definition's timeline is ONE group shaped exactly like a scene's — same
+// MasterRow, same gestures — with no camera row (a definition
+// has no camera), no scene strip and no master offsets (start = 0). Reusing
+// MasterSceneGroup rather than minting a sibling type is what lets the dock
+// render both through one path.
+
+/** The open definition's rows as one master-shaped group at offset 0. */
+export function defGroup(def: ComponentDef3D): MasterSceneGroup {
+  const duration = defDurationFrames(def);
+  const home: Scene3D = defAsScene(def, duration);
+  return {
+    id: def.id,
+    name: def.name,
+    start: 0,
+    end: duration,
+    // A DEFINITION HAS NO CAMERA, so it has no poses either. The dock skips the
+    // camera row entirely inside one; this keeps the shape total anyway.
+    camera: [],
+    cameraKeys: [],
+    rows: trackRows(home, null).map((row) => ({
+      ...row,
+      lifespan: lifespanOf(home.layersById[row.layerId]!, duration),
+    })),
+  };
+}
+
+/** A definition wearing a Scene3D's shape, for the row derivations that take
+ *  one. Only `layers`/`layersById`/`durationFrames` are ever read by them. */
+function defAsScene(def: ComponentDef3D, duration: number): Scene3D {
   return {
-    ...doc,
-    scenesById: {
-      ...doc.scenesById,
-      [sceneId]: { ...scene, layersById: { ...scene.layersById, [layerId]: next } },
-    },
+    id: def.id,
+    name: def.name,
+    durationFrames: duration,
+    background: { type: "solid", color: "#000000" },
+    fovDeg: 35,
+    camera: { x: 0, y: 0, zoom: 1, rollDeg: 0, focusZ: 0 },
+    shots: [],
+    layers: def.roots,
+    layersById: def.layersById,
+    effects: {},
   };
 }
 
-/** `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 def strip's content extent, `masterContentFrames`' twin. */
+export function defContentFrames(group: MasterSceneGroup): number {
+  let end = group.end;
+  for (const row of group.rows) end = Math.max(end, row.lifespan.out);
+  return end;
 }
 
 // ── THE AUDIO CLIP'S GESTURES ───────────────────────────────────────────────
@@ -555,10 +2075,26 @@ export function audioClipView(clip: AudioClipRef): AudioClipView {
  * 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.
+ *
+ * ── THE GESTURE IS BASE-AGNOSTIC, THE MARKERS ARE NOT ──────────────────
+ *
+ * Every clamp below works on the clip's OWN frames, which since schema v13 are
+ * master frames for the bed and scene-local ones for a clip its shot owns. That
+ * needs no branch: a delta is a delta in either base, and "not before zero" is
+ * "not before the video" for one and "not before this shot" for the other,
+ * which is exactly what each schema requires.
+ *
+ * The MARKER sweep is the one thing that cannot be base-agnostic, because
+ * markers are master-timed whatever the clip is. `home` supplies the shift, and
+ * getting it wrong would drag a beat mark off a bed in a document where the
+ * clip and the marks are numbered in two different bases.
  */
 export function writeAudioDrag(doc: Doc3D, clipId: string, mode: AudioDrag, delta: number): Doc3D {
-  const clip = doc.audio[clipId];
+  const home = audioHomeOf(doc, clipId);
+  if (home === null) return doc;
+  const clip = home.sceneId === null ? doc.audio[clipId] : doc.scenesById[home.sceneId]?.audio?.[clipId];
   if (clip === undefined) return doc;
+  const base = home.sceneId === null ? 0 : (sceneStart(doc, home.sceneId) ?? 0);
   const c = audioClipView(clip);
   const d = Math.round(delta);
   /** The shortest a trim may leave the clip: one frame, and never shorter than
@@ -620,22 +2156,147 @@ export function writeAudioDrag(doc: Doc3D, clipId: string, mode: AudioDrag, delt
     }
   }
 
-  const next: Doc3D = { ...doc, audio: { ...doc.audio, [clipId]: { ...clip, ...patch } } };
+  const next = updateAudioClip(doc, clipId, patch);
   if (markerDelta === 0) return next;
-  const end = c.frame + c.durationFrames;
+  // MASTER frames, so the clip's own window is shifted into that base first.
+  const from = base + c.frame;
+  const end = from + c.durationFrames;
   const markers = (doc.markers ?? []).map((m) =>
-    m.frame >= c.frame && m.frame < end ? { ...m, frame: Math.max(0, m.frame + markerDelta) } : m,
+    m.frame >= from && 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 }));
+// ── THE FILMSTRIP'S COLUMNS ───────────────────────────────────────────────
+//
+// Where a video row's thumbnails go, and it is the only part of the strip that
+// is arithmetic rather than pixels, which is why it lives here beside the rest
+// of the dock's geometry and not in `Filmstrip.tsx`.
+//
+// TILES ARE PLACED IN SOURCE TIME. That is the whole design, and everything
+// below is a consequence of it. A column is not "the nth slot of this bar", it
+// is "the picture at source frame s", and s is derived from the same three
+// fields the decode clock reads (`lifetime.in`, `video.offsetFrames`,
+// `video.timeScale`) through the same arithmetic `videoClipOf` states:
+//
+//   sourceFrame(sceneFrame) = (sceneFrame - offsetFrames) * timeScale
+//
+// ── WHY THAT MATTERS: A TRIM MUST NOT RE-CUT THE STRIP ────────────────────
+//
+// `trimLayer` writes `lifetime` and NOTHING ELSE (`video.offsetFrames` is
+// untouched), so a head trim of d frames adds d to `lifetime.in`, and the
+// derived `sourceInFrames` moves by d * timeScale on its own. The bar's left
+// edge therefore moves right by d * ppf while `x0` (below) moves left by
+// exactly the same d * ppf, and every column's ABSOLUTE position on the lane
+// is unchanged. The footage slides under the window instead of being re-cut,
+// which is what a trim looks like in every NLE and what an author is checking
+// when they drag the edge: the frame they were aiming at must not move.
+//
+// A strip laid out from the BAR's left edge would do the opposite. Each trim
+// step would re-phase every thumbnail, the row would shimmer through the whole
+// gesture, and the one thing the author is reading off the strip, which
+// moment of the take this edge lands on, would be the thing that moves.
+//
+// ── THE COLUMN PITCH IS EXACTLY `tileWidth`, AND THAT IS NOT A ROUNDING ───
+//
+// Column i sits at `x0 + (i * intervalFrames / rate) * ppf`, and
+// `intervalFrames / rate` is `tileWidth / ppf` by construction, so the whole
+// expression collapses to `x0 + i * tileWidth`. Screen pitch is constant at
+// every rate and every zoom; the rate only changes how much SOURCE each column
+// covers, and the sign of the rate only changes which direction the source
+// runs as the columns march right. `intervalFrames` is therefore signed and
+// never rounded: rounding it would put a drift of up to half a tile into every
+// column index, growing along the bar.
+
+/** How wide one thumbnail is drawn, in CSS pixels. Wide enough that a column
+ *  is a picture rather than a smear, narrow enough that an ordinary clip bar
+ *  carries several. */
+export const FILMSTRIP_TILE_PX = 48;
+
+/**
+ * A hard ceiling on columns per plan, so a degenerate input cannot turn a
+ * decoration into a hang.
+ *
+ * Not a budget the caller is expected to hit: `Filmstrip.tsx` asks only for the
+ * visible slice plus the viewport's margin, which is a few thousand pixels and
+ * so a few dozen columns. This catches the case where a caller asks for a whole
+ * bar at a deep zoom.
+ */
+export const FILMSTRIP_MAX_COLUMNS = 512;
+
+/** One thumbnail's placement. */
+export interface FilmstripColumn {
+  /** The column's LEFT edge in BAR-LOCAL pixels. May be negative, or run past
+   *  the bar's right edge: a column that straddles an edge is still drawn, and
+   *  the bar's own `overflow: hidden` is what cuts it. */
+  x: number;
+  /**
+   * The source frame this column shows, at the DOCUMENT's rate.
+   *
+   * Fractional and signed on purpose. Negative means the window opens before
+   * the recording's t=0, which is the lead `videoClipOf.leadFrom` names, and
+   * the loader clamps it to the first tile, so the frozen first picture draws
+   * itself with no branch here. The run-out end clamps the same way.
+   */
+  sourceFrame: number;
+}
+
+export interface FilmstripPlan {
+  /** Source frames one column covers. SIGNED (a negative `timeScale` runs the
+   *  source down as the scene runs on) and never rounded. */
+  intervalFrames: number;
+  /** Bar-local pixels where source frame 0 sits. */
+  x0: number;
+  columns: FilmstripColumn[];
+}
+
+/**
+ * The columns covering `[fromPx, toPx)` of a video clip's bar.
+ *
+ * PURE, and the whole reason the maths is here rather than inside the canvas
+ * effect: the invariant above is a property of these numbers, so a test can pin
+ * it without a DOM, a sheet, or a device pixel ratio.
+ *
+ * `fromPx`/`toPx` are BAR-LOCAL and are a clip, not a clamp: they decide which
+ * columns are worth producing, never where a column lands.
+ */
+export function filmstripLayout(input: {
+  /** `lifetime.in`, scene-local. */
+  lifetimeIn: number;
+  /** `video.offsetFrames`. */
+  offsetFrames: number;
+  /** `video.timeScale`. A zero or non-finite rate reads as 1, matching
+   *  `videoClipOf`'s own defaulting, so the strip and the decode clock cannot
+   *  disagree about what a broken field meant. */
+  timeScale: number;
+  ppf: number;
+  tileWidth: number;
+  fromPx: number;
+  toPx: number;
+}): FilmstripPlan {
+  const { lifetimeIn, offsetFrames, timeScale, ppf, tileWidth, fromPx, toPx } = input;
+  const rate = Number.isFinite(timeScale) && timeScale !== 0 ? timeScale : 1;
+  const empty: FilmstripPlan = { intervalFrames: 0, x0: 0, columns: [] };
+  if (!(ppf > 0) || !(tileWidth > 0)) return empty;
+  if (!Number.isFinite(lifetimeIn) || !Number.isFinite(offsetFrames)) return empty;
+  if (!Number.isFinite(fromPx) || !Number.isFinite(toPx) || toPx <= fromPx) return empty;
+
+  const intervalFrames = (tileWidth / ppf) * rate;
+  const x0 = (offsetFrames - lifetimeIn) * ppf;
+
+  // The pitch identity, spelled as `i * tileWidth` because that is what it is.
+  // Indices may be negative, and must be: a bar whose window opens before the
+  // source's t=0 has its first visible column at a negative source frame.
+  const first = Math.floor((fromPx - x0) / tileWidth);
+  const last = Math.ceil((toPx - x0) / tileWidth);
+  if (!Number.isFinite(first) || !Number.isFinite(last)) return empty;
+
+  const columns: FilmstripColumn[] = [];
+  const stop = Math.min(last, first + FILMSTRIP_MAX_COLUMNS);
+  for (let i = first; i < stop; i++) {
+    columns.push({ x: x0 + i * tileWidth, sourceFrame: i * intervalFrames });
+  }
+  return { intervalFrames, x0, columns };
 }