@hyperframes/studio 0.7.57 → 0.7.59

package/src/player/components/timelineClipDragCommit.ts

@@ -1,5 +1,8 @@
 import type { TimelineElement } from "../store/playerStore";
 import type { DraggedClipState } from "./useTimelineClipDrag";
+// Type-only: erased at runtime, so the timelineZMirror → timelineClipDragCommit
+// value-import edge stays acyclic.
+import type { ZMirrorLaneMove } from "./timelineZMirror";
 import { classifyZone, normalizeToZones } from "./timelineZones";
 import { computeStackingPatches, type StackingPatch } from "./timelineStackingSync";
 import { getTimelineEditCapabilities } from "./timelineEditing";
@@ -8,6 +11,7 @@ import {
   beginTimelineOptimisticGesture,
   isLatestTimelineOptimisticGesture,
 } from "./timelineOptimisticRevision";
+import { runLaneZGesture } from "../../components/nle/zLaneGesture";
 
 type StartTrack = Pick<TimelineElement, "start" | "track">;
 export interface TimelineMoveEdit {
@@ -31,11 +35,14 @@ export interface DragCommitDeps {
   /** Atomic multi-clip persist (single undo) for lane changes + track inserts.
    *  `coalesceKey`, when supplied, tags the resulting "Move timeline clips"
    *  history entry so it merges with the lane change's z-reorder entry (see the
-   *  lane-change branch below). */
+   *  lane-change branch below). `coalesceMs` widens that entry's fold window
+   *  (per-gesture-unique keys make an unbounded window safe) — required when a
+   *  server round-trip sits between the gesture's two records. */
   onMoveElements?: (
     edits: TimelineMoveEdit[],
     coalesceKey?: string,
     operation?: TimelineMoveOperation,
+    coalesceMs?: number,
   ) => Promise<void> | void;
   /**
    * The current multi-selection (store.selectedElementIds). When the dragged
@@ -60,18 +67,13 @@ export interface DragCommitDeps {
    * the canvas z-order commit uses (handleDomZIndexReorderCommit). Documented in
    * research/STAGE3-NEEDED-WIRING.md.
    */
-  onStackingPatches?: (patches: StackingPatch[], coalesceKey?: string) => void;
+  onStackingPatches?: (patches: StackingPatch[], coalesceKey?: string) => Promise<unknown> | void;
 }
 
 const keyOf = (e: TimelineElement) => e.key ?? e.id;
 const round3 = (v: number) => Math.round(v * 1000) / 1000;
 
-// One coalesce key per lane-change gesture, shared by the move-persist history
-// entry ("Move timeline clips") and the follow-up z-reorder entry ("Reorder
-// layers") so editHistory (pushEditHistoryEntry) folds the two consecutive
-// records into a single undo step. A monotonic counter — NOT Date.now() /
-// Math.random(), which the determinism rules forbid — suffices: the key only has
-// to be unique per gesture and identical across the gesture's two records.
+// One deterministic coalesce key shared by both records in a lane-change gesture.
 let laneChangeGestureSeq = 0;
 
 /** Whether Studio may write timing to this clip (false for locked/implicit rows). */
@@ -101,12 +103,17 @@ function canMoveElement(element: TimelineElement): boolean {
  * `false` so the caller also skips the z-sync (no orphaned z patch).
  *
  * The DOM is updated synchronously up front; the returned promise never rejects.
+ *
+ * Exported for reuse by non-drag batch time-moves (track gap closing — see
+ * timelineGapCommit.ts) so they share the same optimistic-apply, rollback, and
+ * atomic single-undo persist semantics as a drag commit.
  */
-function persistMoveEdits(
+export function persistMoveEdits(
   edits: TimelineMoveEdit[],
   deps: DragCommitDeps,
   coalesceKey?: string,
   operation: TimelineMoveOperation = "timing",
+  coalesceMs?: number,
 ): Promise<boolean> {
   if (edits.length === 0) return Promise.resolve(true);
   const { updateElement, onMoveElement, onMoveElements } = deps;
@@ -148,7 +155,7 @@ function persistMoveEdits(
       : { element: e.element, updates: { ...e.updates, track: e.persistTrack } },
   );
   const persisted = onMoveElements
-    ? onMoveElements(persistEdits, coalesceKey, operation)
+    ? onMoveElements(persistEdits, coalesceKey, operation, coalesceMs)
     : Promise.all(persistEdits.map((e) => Promise.resolve(onMoveElement?.(e.element, e.updates))));
   return Promise.resolve(persisted).then(
     () => true,
@@ -173,7 +180,7 @@ function persistMoveEdits(
 /** Same-source-file predicate: authored track numbers only compare within ONE
  *  file's coordinate space (an expanded sub-comp child's authoredTrack is in ITS
  *  file, not the host timeline's). `undefined` means the active composition. */
-const sameSourceFile = (a: TimelineElement, b: TimelineElement): boolean =>
+export const sameSourceFile = (a: TimelineElement, b: TimelineElement): boolean =>
   (a.sourceFile ?? null) === (b.sourceFile ?? null);
 
 /**
@@ -203,7 +210,7 @@ const sameSourceFile = (a: TimelineElement, b: TimelineElement): boolean =>
  * Edge-created lanes (min-1 / max+1 inserts) route through the insert path,
  * never here.
  */
-function authoredTrackForLane(
+export function authoredTrackForLane(
   lane: number,
   elements: TimelineElement[],
   dragged: TimelineElement,
@@ -217,7 +224,10 @@ function authoredTrackForLane(
     if (!nearest || Math.abs(p.track - lane) < Math.abs(nearest.track - lane)) nearest = p;
   }
   if (!nearest) return lane;
-  return (nearest.authoredTrack ?? nearest.track) + (lane - nearest.track);
+  // Rounded: expanded children live on FRACTIONAL synthetic display rows (see
+  // buildChildElements), so a lane distance measured against one can carry a
+  // fraction — an authored data-track-index must stay an integer.
+  return Math.round((nearest.authoredTrack ?? nearest.track) + (lane - nearest.track));
 }
 
 function insertTrackValue(trackOrder: number[], insertRow: number): number {
@@ -351,8 +361,13 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
     return e;
   });
   const multiKeys = multi ? multi.keys : null;
-  void persistMoveEdits(edits, deps, coalesceKey, "lane-reorder").then((moved) => {
-    if (moved && isVertical) {
+  if (!isVertical || !deps.readZIndex || !deps.onStackingPatches) {
+    void persistMoveEdits(edits, deps, coalesceKey, "lane-reorder");
+    return;
+  }
+  void runLaneZGesture({
+    commitLane: () => persistMoveEdits(edits, deps, coalesceKey, "lane-reorder"),
+    commitZ: () =>
       syncStackingForEdit(
         candidate,
         dragKey,
@@ -361,81 +376,123 @@ export function commitDraggedClipMove(drag: DraggedClipState, deps: DragCommitDe
         multiKeys,
         deps,
         coalesceKey,
-      );
-    }
-  });
+      ),
+  }).catch(() => undefined);
 }
 
-/**
- * Insert a new track at the drop's gap boundary. The dragged clip lands on the
- * fractional insert lane; normalizeToZones then compacts every lane to a contiguous
- * integer, which shifts the clips at/below the insert down by one. That +1
- * renumber is the ONLY sanctioned multi-clip write; it is index-only (never z).
- * The whole affected set is persisted atomically (single undo), and the deliberate
- * vertical move syncs the dragged clip's stacking afterwards.
- */
+/** Build the one sanctioned multi-clip write: atomically insert and compact a
+ * source-file zone, then let the caller sync the deliberate vertical stacking. */
 // fallow-ignore-next-line complexity
-function commitTrackInsert(
-  drag: DraggedClipState,
-  deps: DragCommitDeps,
+function buildTrackInsertEdits(
+  element: TimelineElement,
+  previewStart: number,
+  insertRow: number,
   multi: {
     keys: ReadonlySet<string>;
     movedStart: (e: TimelineElement) => number;
   } | null,
-): void {
+  deps: DragCommitDeps,
+): { candidate: TimelineElement[]; edits: TimelineMoveEdit[] } | null {
   const { elements, trackOrder } = deps;
-  const dragKey = keyOf(drag.element);
-  const targetTrack = insertTrackValue(trackOrder, drag.insertRow!);
-  // Drop-intent set: dragged clip at the fractional insert lane (so it sorts
-  // between its neighbours), selection members time-shifted, others as-is.
+  const editKey = keyOf(element);
+  // Expanded-child rows are synthetic host lanes, not source-file topology.
+  if (element.expandedParentStart != null) return null;
+  const targetTrack = insertTrackValue(trackOrder, insertRow);
   const candidate = elements.map((e) => {
-    if (keyOf(e) === dragKey) return { ...e, start: drag.previewStart, track: targetTrack };
+    if (keyOf(e) === editKey) return { ...e, start: previewStart, track: targetTrack };
     if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
     return e;
   });
-  // normalizeToZones compacts the fractional lane to a contiguous integer, which
-  // shifts the at/below clips down by one — the sanctioned +1 index renumber.
-  const normalized = normalizeToZones(candidate);
+  // Foreign display rows and the opposite zone must not affect this topology.
+  const writableZone = classifyZone(element);
+  const writable = (src: TimelineElement): boolean =>
+    sameSourceFile(src, element) &&
+    classifyZone(src) === writableZone &&
+    src.expandedParentStart == null;
+  const topologyOrder = [...new Set(elements.filter(writable).map((e) => e.track))].sort(
+    (a, b) => a - b,
+  );
+  const topologyInsertRow = topologyOrder.filter((track) => track < targetTrack).length;
+  const topologyTargetTrack = insertTrackValue(topologyOrder, topologyInsertRow);
+  const normalized = normalizeToZones(
+    elements.filter(writable).map((e) => {
+      if (keyOf(e) === editKey) {
+        return { ...e, start: previewStart, track: topologyTargetTrack };
+      }
+      if (multi?.keys.has(keyOf(e))) return { ...e, start: multi.movedStart(e) };
+      return e;
+    }),
+  );
   const bySrc = new Map(elements.map((e) => [keyOf(e), e]));
-  // The renumber is only correct as a WHOLE-SET write: skipping an unwritable
-  // clip whose lane shifts leaves its track colliding with a renumbered
-  // neighbour, and the next normalize merges the two lanes. If any shifted clip
-  // can't be written, refuse the insert instead of persisting a broken layout.
+  // A partial zone renumber creates collisions; refuse a shifted locked row.
   for (const norm of normalized) {
     const src = bySrc.get(keyOf(norm));
-    if (src && !canMoveElement(src) && norm.track !== src.track) {
+    if (
+      src &&
+      writable(src) &&
+      !canMoveElement(src) &&
+      norm.track !== (src.authoredTrack ?? src.track)
+    ) {
       console.warn(
         `[Timeline] Track insert refused: locked clip ${keyOf(src)} would need renumbering`,
       );
-      return;
+      return null;
     }
   }
   const edits: TimelineMoveEdit[] = [];
+  if (multi) {
+    for (const src of elements) {
+      const srcKey = keyOf(src);
+      if (srcKey !== editKey && multi.keys.has(srcKey) && !writable(src) && canMoveElement(src)) {
+        edits.push({
+          element: src,
+          updates: { start: multi.movedStart(src), track: src.track },
+          persistTrack: src.authoredTrack,
+        });
+      }
+    }
+  }
   for (const norm of normalized) {
     const src = bySrc.get(keyOf(norm));
-    if (!src) continue;
-    // Capabilities gate (unchanged-lane clips only reach here now): never write
-    // a locked/implicit clip.
-    if (!canMoveElement(src)) continue;
+    if (!src || !canMoveElement(src)) continue;
     const start =
-      keyOf(norm) === dragKey || multi?.keys.has(keyOf(norm))
-        ? (multi?.movedStart(src) ?? drag.previewStart)
+      keyOf(norm) === editKey || multi?.keys.has(keyOf(norm))
+        ? (multi?.movedStart(src) ?? previewStart)
         : src.start;
     edits.push({ element: src, updates: { start, track: norm.track } });
   }
+  return { candidate, edits };
+}
+
+function commitTrackInsert(
+  drag: DraggedClipState,
+  deps: DragCommitDeps,
+  multi: {
+    keys: ReadonlySet<string>;
+    movedStart: (e: TimelineElement) => number;
+  } | null,
+): void {
+  const dragKey = keyOf(drag.element);
+  const built = buildTrackInsertEdits(
+    drag.element,
+    drag.previewStart,
+    drag.insertRow!,
+    multi,
+    deps,
+  );
+  if (!built) return;
+  const { candidate, edits } = built;
+  if (edits.length === 0) return;
 
   const coalesceKey = `clip-lane-move:${laneChangeGestureSeq++}`;
-  void persistMoveEdits(edits, deps, coalesceKey, "track-insert").then((moved) => {
-    // Skip the z-sync when the insert produced NO move edits (e.g. every clip in
-    // the set is locked/implicit and gets filtered out). persistMoveEdits resolves
-    // `true` for an empty batch so the caller's serialization proceeds, but firing
-    // the z-sync here would record an orphaned z-only history entry for a move that
-    // never persisted.
-    if (moved && edits.length > 0) {
-      // Reason the z-sync on the drop-intent `candidate` (dragged clip at its
-      // fractional insert lane) — NOT the re-normalized lanes — so the sync sees
-      // the user's move. The guard lane is the aimed insert row (a boundary in
-      // display-lane space, comparable to the clip's contiguous current lane).
+  if (!deps.readZIndex || !deps.onStackingPatches) {
+    void persistMoveEdits(edits, deps, coalesceKey, "track-insert");
+    return;
+  }
+  void runLaneZGesture({
+    commitLane: () => persistMoveEdits(edits, deps, coalesceKey, "track-insert"),
+    commitZ: () =>
+      // Sync from the fractional drop intent, not the normalized persisted lanes.
       syncStackingForEdit(
         candidate,
         dragKey,
@@ -444,9 +501,54 @@ function commitTrackInsert(
         multi ? multi.keys : null,
         deps,
         coalesceKey,
-      );
-    }
-  });
+      ),
+  }).catch(() => undefined);
+}
+
+/**
+ * Commit the timeline lane move that MIRRORS a canvas z-order menu action
+ * (resolveZMirrorLaneMove's non-null result). Same machinery as a lane drag:
+ *
+ * - kind "move": persistMoveEdits with `{start: element.start, track: displayTrack}`
+ *   + `persistTrack` — identical shape to commitDraggedClipMove's lane-change
+ *   branch (optimistic store update, authoredTrack mirror, rollback on failure).
+ * - kind "insert": buildTrackInsertEdits — the SAME renumber core commitTrackInsert
+ *   uses — then the same atomic persist.
+ *
+ * Deliberately NO syncStackingForEdit here: the z values were just set by the
+ * user's menu action, and the lane→z sync would recompute (and fight) them. The
+ * mirror caller also omits `readZIndex`/`onStackingPatches` from `deps`, so even
+ * a future call into the sync would no-op (double protection; see
+ * useCanvasZOrderTimelineMirror).
+ *
+ * `coalesceKey` MUST be the z persist's key (`z-reorder:<action>:<ids>:g<seq>`)
+ * so editHistory folds the z write and this track write into ONE undo entry, and
+ * `coalesceMs` MUST widen this record's fold window: the mirror only runs after
+ * the z persist's server round-trip resolved, so under real network latency the
+ * gap between the two records exceeds the reducer's 300ms default and the fold
+ * would never happen live. The key is unique per gesture, so an unbounded
+ * window can never merge distinct gestures.
+ *
+ * Resolves `true` once the move persisted, `false` on rollback / refused insert.
+ */
+export function commitZMirrorLaneMove(
+  element: TimelineElement,
+  move: NonNullable<ZMirrorLaneMove>,
+  deps: DragCommitDeps,
+  coalesceKey: string,
+  coalesceMs?: number,
+): Promise<boolean> {
+  if (move.kind === "move") {
+    const edit: TimelineMoveEdit = {
+      element,
+      updates: { start: element.start, track: move.displayTrack },
+      persistTrack: move.persistTrack,
+    };
+    return persistMoveEdits([edit], deps, coalesceKey, "lane-reorder", coalesceMs);
+  }
+  const built = buildTrackInsertEdits(element, element.start, move.insertRow, null, deps);
+  if (!built || built.edits.length === 0) return Promise.resolve(false);
+  return persistMoveEdits(built.edits, deps, coalesceKey, "track-insert", coalesceMs);
 }
 
 /**
@@ -467,18 +569,16 @@ function syncStackingForEdit(
   multiKeys: ReadonlySet<string> | null,
   deps: DragCommitDeps,
   coalesceKey?: string,
-): void {
+): Promise<void> {
   const { readZIndex, onStackingPatches } = deps;
-  if (!readZIndex || !onStackingPatches) return;
+  if (!readZIndex || !onStackingPatches) return Promise.resolve();
 
   // Aiming at the clip's OWN current display lane is not a relocation — never
   // touch z (guards the pure-time-move invariant even if a spurious topology call
   // slips through). Every real lane-realization drop aims at a DIFFERENT lane.
-  if (aimedLane === currentLane) return;
+  if (aimedLane === currentLane) return Promise.resolve();
 
-  // `candidate` is in discovery order, so its array index IS the DOM document
-  // position. Equal-z clips paint by DOM order, so the sync needs it to decide
-  // "is A above B" (see StackingElement.domIndex).
+  // Discovery order is DOM order, which breaks equal-z ties.
   const stackingEls = candidate.map((el, domIndex) => ({
     key: keyOf(el),
     start: el.start,
@@ -486,6 +586,7 @@ function syncStackingForEdit(
     track: el.track,
     zIndex: readZIndex(el),
     isAudio: classifyZone(el) === "audio",
+    sourceFile: el.sourceFile,
     domIndex,
     stackingContextId: el.stackingContextId ?? null,
   }));
@@ -494,5 +595,6 @@ function syncStackingForEdit(
   if (multiKeys) for (const k of multiKeys) if (k !== dragKey) editedKeys.push(k);
 
   const patches = computeStackingPatches(stackingEls, editedKeys);
-  if (patches.length > 0) onStackingPatches(patches, coalesceKey);
+  if (patches.length === 0) return Promise.resolve();
+  return Promise.resolve(onStackingPatches(patches, coalesceKey)).then(() => undefined);
 }

package/src/player/components/timelineGapCommit.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../store/playerStore";
+import type { DragCommitDeps } from "./timelineClipDragCommit";
+import {
+  canShiftTrackGapClips,
+  commitCloseAllTrackGaps,
+  commitCloseTrackGap,
+} from "./timelineGapCommit";
+import { resolveAllTrackGaps } from "./timelineGaps";
+
+function el(id: string, start: number, duration: number, track = 0): TimelineElement {
+  // domId + video tag → getTimelineEditCapabilities(...).canMove === true
+  return { id, tag: "video", start, duration, track, domId: id };
+}
+
+function lockedEl(id: string, start: number, duration: number): TimelineElement {
+  return { ...el(id, start, duration), timelineLocked: true };
+}
+
+function makeDeps(laneElements: TimelineElement[]) {
+  const onMoveElements = vi.fn(() => Promise.resolve());
+  const updateElement = vi.fn();
+  const deps: DragCommitDeps = {
+    elements: laneElements,
+    trackOrder: [0],
+    updateElement,
+    onMoveElements,
+  };
+  return { deps, onMoveElements, updateElement };
+}
+
+/** Assert exactly ONE atomic persist batch; return its flattened edits + coalesce key. */
+function singleBatch(onMoveElements: ReturnType<typeof vi.fn>) {
+  expect(onMoveElements).toHaveBeenCalledTimes(1);
+  const [edits, coalesceKey] = onMoveElements.mock.calls[0] as unknown as [
+    Array<{ element: TimelineElement; updates: { start: number; track: number } }>,
+    string,
+  ];
+  return { coalesceKey, edits: edits.map((e) => ({ id: e.element.id, ...e.updates })) };
+}
+
+describe("commitCloseTrackGap", () => {
+  it("persists ONE atomic batch shifting the next clip and every clip after it", () => {
+    const lane = [el("a", 0, 2), el("b", 5, 3), el("c", 10, 1)];
+    const { deps, onMoveElements } = makeDeps(lane);
+
+    expect(commitCloseTrackGap(lane, 3, deps)).toBe(true);
+
+    const { edits, coalesceKey } = singleBatch(onMoveElements);
+    // Gap is [2, 5) → width 3; b and c shift left by 3, tracks unchanged.
+    expect(edits).toEqual([
+      { id: "b", start: 2, track: 0 },
+      { id: "c", start: 7, track: 0 },
+    ]);
+    expect(typeof coalesceKey).toBe("string");
+    expect(coalesceKey).toMatch(/^track-gap-close:\d+$/);
+  });
+
+  it("optimistically applies the same starts to the store", () => {
+    const lane = [el("a", 0, 2), el("b", 5, 3)];
+    const { deps, updateElement } = makeDeps(lane);
+    commitCloseTrackGap(lane, 3, deps);
+    expect(updateElement).toHaveBeenCalledWith("b", { start: 2, track: 0 });
+  });
+
+  it("closes the leading gap (first clip lands at 0)", () => {
+    const lane = [el("a", 2, 3), el("b", 6, 1)];
+    const { deps, onMoveElements } = makeDeps(lane);
+
+    expect(commitCloseTrackGap(lane, 1, deps)).toBe(true);
+    const [edits] = onMoveElements.mock.calls[0] as unknown as [
+      Array<{ element: TimelineElement; updates: { start: number; track: number } }>,
+    ];
+    expect(edits.map((e) => ({ id: e.element.id, start: e.updates.start }))).toEqual([
+      { id: "a", start: 0 },
+      { id: "b", start: 4 },
+    ]);
+  });
+
+  it("uses a fresh coalesce key per gesture", () => {
+    const lane = [el("a", 0, 2), el("b", 5, 3)];
+    const first = makeDeps(lane);
+    const second = makeDeps(lane);
+    commitCloseTrackGap(lane, 3, first.deps);
+    commitCloseTrackGap(lane, 3, second.deps);
+    const keyA = first.onMoveElements.mock.calls[0][1 as never];
+    const keyB = second.onMoveElements.mock.calls[0][1 as never];
+    expect(keyA).not.toEqual(keyB);
+  });
+
+  it("refuses (no write) when there is no clip right of the point", () => {
+    const lane = [el("a", 0, 2)];
+    const { deps, onMoveElements, updateElement } = makeDeps(lane);
+    expect(commitCloseTrackGap(lane, 5, deps)).toBe(false);
+    expect(onMoveElements).not.toHaveBeenCalled();
+    expect(updateElement).not.toHaveBeenCalled();
+  });
+
+  it("refuses (no partial compaction) when ANY shifting clip is unmovable", () => {
+    const lane = [el("a", 0, 2), el("b", 5, 3), lockedEl("c", 10, 1)];
+    const { deps, onMoveElements, updateElement } = makeDeps(lane);
+    expect(commitCloseTrackGap(lane, 3, deps)).toBe(false);
+    expect(onMoveElements).not.toHaveBeenCalled();
+    expect(updateElement).not.toHaveBeenCalled();
+  });
+});
+
+describe("commitCloseAllTrackGaps", () => {
+  it("compacts the whole lane in ONE atomic batch (leading gap included)", () => {
+    const lane = [el("a", 1, 2), el("b", 5, 3), el("c", 10, 1)];
+    const { deps, onMoveElements } = makeDeps(lane);
+
+    expect(commitCloseAllTrackGaps(lane, deps)).toBe(true);
+
+    const { edits, coalesceKey } = singleBatch(onMoveElements);
+    expect(edits).toEqual([
+      { id: "a", start: 0, track: 0 },
+      { id: "b", start: 2, track: 0 },
+      { id: "c", start: 5, track: 0 },
+    ]);
+    expect(coalesceKey).toMatch(/^track-gap-close:\d+$/);
+  });
+
+  it("refuses when the track is already contiguous (no gaps)", () => {
+    const lane = [el("a", 0, 2), el("b", 2, 3)];
+    const { deps, onMoveElements } = makeDeps(lane);
+    expect(commitCloseAllTrackGaps(lane, deps)).toBe(false);
+    expect(onMoveElements).not.toHaveBeenCalled();
+  });
+
+  it("refuses when any shifting clip is unmovable, even if others could move", () => {
+    const lane = [lockedEl("a", 1, 2), el("b", 5, 3)];
+    const { deps, onMoveElements, updateElement } = makeDeps(lane);
+    expect(commitCloseAllTrackGaps(lane, deps)).toBe(false);
+    expect(onMoveElements).not.toHaveBeenCalled();
+    expect(updateElement).not.toHaveBeenCalled();
+  });
+
+  it("proceeds when an unmovable clip does NOT need to shift", () => {
+    // Locked clip already sits flush at 0 — only movable clips shift.
+    const lane = [lockedEl("a", 0, 2), el("b", 4, 1)];
+    const { deps, onMoveElements } = makeDeps(lane);
+    expect(commitCloseAllTrackGaps(lane, deps)).toBe(true);
+    const [edits] = onMoveElements.mock.calls[0] as unknown as [
+      Array<{ element: TimelineElement; updates: { start: number } }>,
+    ];
+    expect(edits.map((e) => ({ id: e.element.id, start: e.updates.start }))).toEqual([
+      { id: "b", start: 2 },
+    ]);
+  });
+});
+
+describe("canShiftTrackGapClips", () => {
+  it("is true only when every named clip is movable", () => {
+    const lane = [el("a", 1, 2), lockedEl("b", 5, 3)];
+    expect(canShiftTrackGapClips(lane, [{ key: "a", newStart: 0 }])).toBe(true);
+    expect(canShiftTrackGapClips(lane, resolveAllTrackGaps(lane))).toBe(false);
+  });
+
+  it("is false for unknown keys", () => {
+    expect(canShiftTrackGapClips([el("a", 0, 1)], [{ key: "ghost", newStart: 0 }])).toBe(false);
+  });
+});

package/src/player/components/timelineGapCommit.ts

@@ -0,0 +1,103 @@
+import type { TimelineElement } from "../store/playerStore";
+import { getTimelineEditCapabilities } from "./timelineEditing";
+import {
+  persistMoveEdits,
+  type DragCommitDeps,
+  type TimelineMoveEdit,
+} from "./timelineClipDragCommit";
+import {
+  laneGapFloor,
+  resolveAllTrackGaps,
+  resolveCloseGapShifts,
+  resolveTrackGapAt,
+  type TrackGapShift,
+} from "./timelineGaps";
+
+/**
+ * Commit layer for the track-gap context menu ("Close gap" / "Close all gaps").
+ *
+ * Each action is ONE atomic {@link persistMoveEdits} batch — pure time moves
+ * (`updates.track === element.track`, no authored-track rewrite) tagged with a
+ * per-gesture-unique coalesce key, so an action is exactly one undo entry and
+ * flows through the existing move pipeline (optimistic store apply + rollback,
+ * SDK fast path, patchIframeDomTiming preview).
+ *
+ * Refusal rule: if ANY clip that must shift is unmovable
+ * ({@link getTimelineEditCapabilities}.canMove === false), the whole action is
+ * refused — never a partial compaction. The menu disables the item via
+ * {@link canShiftTrackGapClips}; the commit re-checks as defense in depth.
+ */
+
+const keyOf = (e: TimelineElement) => e.key ?? e.id;
+
+// Per-gesture-unique coalesce key. A monotonic counter — NOT Date.now() /
+// Math.random() (determinism rules) — mirrors laneChangeGestureSeq in
+// timelineClipDragCommit.ts.
+let gapCloseGestureSeq = 0;
+
+/** True when every clip named in `shifts` may be time-moved. */
+export function canShiftTrackGapClips(
+  laneElements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+): boolean {
+  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
+  return shifts.every((s) => {
+    const element = byKey.get(s.key);
+    return element != null && getTimelineEditCapabilities(element).canMove;
+  });
+}
+
+function buildShiftEdits(
+  laneElements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+): TimelineMoveEdit[] | null {
+  if (shifts.length === 0 || !canShiftTrackGapClips(laneElements, shifts)) return null;
+  const byKey = new Map(laneElements.map((e) => [keyOf(e), e]));
+  return shifts.map((s) => {
+    const element = byKey.get(s.key)!;
+    return { element, updates: { start: s.newStart, track: element.track } };
+  });
+}
+
+function commitShifts(
+  laneElements: readonly TimelineElement[],
+  shifts: readonly TrackGapShift[],
+  deps: DragCommitDeps,
+): boolean {
+  const edits = buildShiftEdits(laneElements, shifts);
+  if (!edits) return false;
+  void persistMoveEdits(edits, deps, `track-gap-close:${gapCloseGestureSeq++}`);
+  return true;
+}
+
+/**
+ * Close the ONE gap under `time` on the lane: the next clip and every clip
+ * after it on that lane shift left by the gap's width. Returns false (and
+ * writes nothing) when there is no gap at the point or a shifting clip is
+ * unmovable.
+ */
+export function commitCloseTrackGap(
+  laneElements: readonly TimelineElement[],
+  time: number,
+  deps: DragCommitDeps,
+): boolean {
+  const gap = resolveTrackGapAt(laneElements, time, undefined, laneGapFloor(laneElements));
+  if (!gap) return false;
+  return commitShifts(laneElements, resolveCloseGapShifts(laneElements, gap), deps);
+}
+
+/**
+ * Compact the whole lane (leading gap included): clips become contiguous from
+ * 0, order and durations preserved. Returns false (and writes nothing) when
+ * the lane has no gaps or a shifting clip is unmovable.
+ */
+export function commitCloseAllTrackGaps(
+  laneElements: readonly TimelineElement[],
+  deps: DragCommitDeps,
+): boolean {
+  return commitShifts(
+    laneElements,
+    resolveAllTrackGaps(laneElements, undefined, laneGapFloor(laneElements)),
+    deps,
+  );
+}