@hyperframes/studio 0.8.131 → 0.8.133

package/src/player/components/timelineStackingSync.ts

@@ -1,10 +1,10 @@
 /**
  * timelineStackingSync — lane ↔ stacking unification (pure).
  *
- * The approved design: **lane order implies stacking**. A clip on a higher lane
- * (rendered ABOVE another in the timeline) should render ON TOP of any clip it
- * OVERLAPS IN TIME. But authored z-indexes are sacred: z only changes on a user
- * edit, and ONLY for the clip(s) the user actually edited.
+ * A row move restacks the moved clip only: moved up, it rises above every clip
+ * it overlaps in time on the rows now below it; moved down, it sinks below every
+ * such clip on the rows now above it. Neighbours never change, so a clip nobody
+ * moved never goes behind anything (a full-frame scene on the top row stays put).
  *
  * Lane → screen mapping (see Timeline.tsx trackOrder / TimelineCanvas rows):
  * tracks are sorted ASCENDING and rendered top → bottom, so a LOWER `track`
@@ -38,7 +38,7 @@ export interface StackingElement {
    * (e.g. an unmounted / nested sub-comp element, or one outside the active file).
    * A non-finite-z clip is EXCLUDED from the computation — it is neither a stacking
    * neighbour nor resolvable as an edit — so an unresolved node never fabricates a
-   * z=0 neighbour that poisons the boundary math (item 13). The reader signals a
+   * z=0 neighbour. The reader signals a
    * miss with NaN rather than null so the value stays assignable to the existing
    * `(el) => number` reader contract the drag hook / commit deps declare.
    */
@@ -57,10 +57,9 @@ export interface StackingElement {
   /**
    * Discovery / DOM document position (optional). Two clips with EQUAL z paint by
    * DOM order — the one LATER in the DOM paints ON TOP. When supplied, "is A above
-   * B" uses (zIndex, domIndex); without it equal-z is ambiguous and the sync can
-   * under-patch (the reported bug: a clip dragged to the bottom lane over an
-   * equal-z neighbour changed nothing on canvas). Callers pass the index of the
-   * element in the discovery order array.
+   * B" uses (zIndex, domIndex); without it equal z counts as "not above", so the
+   * move writes a z. Callers pass the index of the element in the discovery order
+   * array.
    */
   domIndex?: number;
 }
@@ -74,7 +73,7 @@ export interface StackingPatch {
 /**
  * Canonical paint-scope key: leaf z-indexes are comparable only within the same
  * source document and CSS stacking context. The ONLY place this normalization
- * lives — partitioning, membership checks, and pairwise equality all use it.
+ * lives; samePaintScope compares with it.
  */
 const paintScopeKey = (el: { sourceFile?: string; stackingContextId?: string | null }): string =>
   JSON.stringify([el.sourceFile ?? null, el.stackingContextId ?? null]);
@@ -114,21 +113,13 @@ export function laneIsAbove(
   return a.track < b.track;
 }
 
-/**
- * Working record for the cascade resolver: a live-mutable, RESOLVED (non-null) z
- * the resolver can bump, plus the immutable identity/lane/time/dom fields. Clips
- * whose z could not be resolved (null) are dropped before this stage.
- */
-interface MutZ extends StackingElement {
-  zIndex: number;
-}
+/** Which way the edited clips moved between rows. */
+export type StackingDirection = "up" | "down";
 
 /**
  * Does `a` currently paint ON TOP of `b`? Higher z wins; equal z breaks by DOM
- * order (later in DOM paints on top). When either domIndex is absent, equal z is
- * treated as "not strictly above" (ambiguous) — callers should supply domIndex to
- * disambiguate (see StackingElement.domIndex). Exported (like laneIsAbove) as the
- * ONE paint-order predicate so every consumer agrees on what "paints above" means.
+ * order (later in DOM paints on top). Without both domIndex values equal z is
+ * ambiguous and counts as "not above", so the move still writes a z.
  */
 function paintsAbove(
   a: Pick<StackingElement, "zIndex" | "domIndex">,
@@ -139,233 +130,58 @@ function paintsAbove(
   return false;
 }
 
-/** Reduce a neighbour set's z-indices to a single bound, or null when empty. */
-function boundaryZ(neighbours: MutZ[], reduce: (zs: number[]) => number): number | null {
-  return neighbours.length > 0 ? reduce(neighbours.map((o) => o.zIndex)) : null;
+/** Moved up: one above the highest clip it now sits above, or null when it already paints above them all. */
+function raisedZ(clip: StackingElement, overlapping: StackingElement[]): number | null {
+  const below = overlapping.filter((o) => laneIsAbove(clip, o));
+  if (below.every((o) => paintsAbove(clip, o))) return null;
+  return Math.max(...below.map((o) => o.zIndex)) + 1;
 }
 
-/**
- * Resolve `edited` so that, among the clips it OVERLAPS IN TIME, its paint order
- * matches its lane order (lower lane ⇒ paints on top). Records every z change
- * (edited clip AND any neighbours that must be bumped) into `patchZ`.
- *
- * Fast path (unchanged behaviour): when a single non-negative z for the edited
- * clip alone realises the order — strictly between the neighbours if there is
- * integer room, else just above the lower neighbour, else just below the upper —
- * emit only that. This keeps every existing single-patch test passing.
- *
- * Cascade path: when ties/clamping make the single-clip patch impossible or
- * ineffective (must sit below an overlapping z=0 neighbour, or between adjacent /
- * equal-z neighbours where DOM order alone can't express it), bump the minimum set
- * of overlapping neighbours that must stay ABOVE by +1 (cascading only as far as
- * needed) so the edited clip's intended lane order is realised with all z ≥ 0.
- * "Authored z sacred" stays the default — neighbours are touched only when the
- * user's explicit lane move is otherwise inexpressible (same precedent as the
- * canvas context-menu tie-aware fix).
- *
- * Returns true when any z changed (recorded in `patchZ`), false for a no-op.
- */
-function resolveEditedZ(
-  edited: MutZ,
-  overlapping: MutZ[],
-  overlappersOf: (clip: MutZ) => MutZ[],
-  patchZ: (clip: MutZ, z: number) => void,
-): boolean {
-  const visualOverlap = overlapping.filter((o) => !o.isAudio);
-  if (visualOverlap.length === 0) return false;
-
-  // Neighbours that must end up BELOW edited (lower lane) vs ABOVE (higher lane).
-  const below = visualOverlap.filter((o) => laneIsAbove(edited, o));
-  const above = visualOverlap.filter((o) => laneIsAbove(o, edited));
-
-  // Already correct against every overlapping neighbour → no-op (authored z kept).
-  const correct =
-    below.every((o) => paintsAbove(edited, o)) && above.every((o) => paintsAbove(o, edited));
-  if (correct) return false;
-
-  const maxBelow = boundaryZ(below, (zs) => Math.max(...zs));
-
-  // ── Fast path: try to realise the order by moving only `edited`. ──────────────
-  const single = trySingleZ(edited, below, above);
-  if (single != null) {
-    if (single !== edited.zIndex) patchZ(edited, single);
-    // Even at an unchanged z the DOM-order ties may already be satisfied; if not,
-    // `trySingleZ` returned null and we fall through to the cascade.
-    return single !== edited.zIndex;
-  }
-
-  // ── Cascade path: can't fit `edited` between the neighbours with one z ≥ 0. ───
-  // Sit edited at maxBelow+1 (or 0 when it only has above-neighbours) and lift the
-  // above-neighbours that are now not strictly above, minimally, one step past it.
-  const target = maxBelow != null ? maxBelow + 1 : 0;
-  const clamped = Math.max(0, target);
-  if (clamped !== edited.zIndex) patchZ(edited, clamped);
-  liftAbove(edited, overlappersOf, patchZ);
-  return true;
+/** Moved down: one below the lowest clip it now sits under, but never under z 0 (a negative z can paint behind the
+ * composition's own background) and never under a clip on a lower row it paints over now, so the move cannot hide it.
+ * Null when it already paints under them all or cannot go lower. */
+function loweredZ(clip: StackingElement, overlapping: StackingElement[]): number | null {
+  const above = overlapping.filter((o) => laneIsAbove(o, clip));
+  if (above.every((o) => paintsAbove(o, clip))) return null;
+  const keepOver = overlapping.filter((o) => laneIsAbove(clip, o) && paintsAbove(clip, o));
+  const floor = Math.max(
+    0,
+    ...keepOver.map((o) =>
+      paintsAbove({ ...clip, zIndex: o.zIndex }, o) ? o.zIndex : o.zIndex + 1,
+    ),
+  );
+  const z = Math.max(floor, Math.min(...above.map((o) => o.zIndex)) - 1);
+  return z < clip.zIndex ? z : null;
 }
 
 /**
- * Pick a single non-negative z for `edited` that lands it correctly against its
- * neighbours (paints above every below-neighbour, below every above-neighbour), or
- * null when no such z exists and the caller must cascade.
- *
- * The candidate is verified with the SAME `paintsAbove` predicate the resolver uses
- * (z + DOM tie-break), so an authored z that already paints correctly by DOM order
- * is honoured instead of over-patched: with below=z3 and an above-neighbour at z4
- * that is LATER in the DOM, edited=4 ties the neighbour but the neighbour still
- * paints on top by DOM order — a valid single patch, no neighbour bump (item 12).
- * When the tie would INVERT (the above-neighbour is earlier in DOM) the candidate
- * fails verification and the caller cascades.
- */
-// edited has neighbours on BOTH sides: prefer the integer midpoint of a real gap;
-// with no strict gap a DOM tie-break may still let it sit AT minAbove (item 12),
-// else the caller cascades.
-function zBetweenNeighbours(
-  maxBelow: number,
-  minAbove: number,
-  correctAt: (z: number) => boolean,
-): number | null {
-  if (minAbove - maxBelow >= 2) {
-    const mid = Math.floor((maxBelow + minAbove) / 2);
-    return mid > maxBelow && mid < minAbove ? mid : null;
-  }
-  return correctAt(minAbove) ? minAbove : null;
-}
-
-// edited has only above-neighbours: sit one step below minAbove, or at the z=0
-// floor tie minAbove when a DOM tie-break keeps that neighbour on top.
-function zBelowOnly(minAbove: number, correctAt: (z: number) => boolean): number | null {
-  const candidate = minAbove - 1;
-  if (candidate >= 0) return candidate;
-  return correctAt(minAbove) ? minAbove : null;
-}
-
-function trySingleZ(edited: MutZ, below: MutZ[], above: MutZ[]): number | null {
-  const maxBelow = boundaryZ(below, (zs) => Math.max(...zs));
-  const minAbove = boundaryZ(above, (zs) => Math.min(...zs));
-
-  const correctAt = (z: number): boolean => {
-    const probe: MutZ = { ...edited, zIndex: z };
-    return below.every((b) => paintsAbove(probe, b)) && above.every((a) => paintsAbove(a, probe));
-  };
-
-  if (maxBelow != null && minAbove != null)
-    return zBetweenNeighbours(maxBelow, minAbove, correctAt);
-  if (maxBelow != null) return maxBelow + 1; // only below-neighbours → grow upward
-  if (minAbove != null) return zBelowOnly(minAbove, correctAt);
-  return null;
-}
-
-/**
- * Enforce the module invariant — for every OVERLAPPING pair, the clip on the upper
- * lane paints on top — starting from `edited` and cascading TRANSITIVELY.
- *
- * Seeded with `edited`: each of its upper-lane overlappers must paint strictly
- * above it (the deliberate lane move). Raising a clip can then tie or cross ANOTHER
- * clip it overlaps that sits on an even higher lane — that clip must be lifted too,
- * and so on. Without the cascade a lifted neighbour could tie an untouched clip on
- * a higher lane and, being later in the DOM, paint above it — an untouched pair
- * visibly inverting (#2198). The condition is LANE order (not "was originally
- * above"), so a clip that was already violating lane order — e.g. a bottom-lane
- * clip painting on top — is fixed, never preserved. Only clips whose z actually
- * changes are patched; z climbs by +1 each step so the walk terminates.
- */
-function liftAbove(
-  edited: MutZ,
-  overlappersOf: (clip: MutZ) => MutZ[],
-  patchZ: (clip: MutZ, z: number) => void,
-): void {
-  const queue: MutZ[] = [edited];
-  const raiseAbove = (clip: MutZ, floor: MutZ): void => {
-    if (paintsAbove(clip, floor)) return; // already strictly on top
-    patchZ(clip, floor.zIndex + 1); // patchZ mutates clip.zIndex in place
-    queue.push(clip);
-  };
-  while (queue.length > 0) {
-    const floor = queue.shift()!;
-    for (const other of overlappersOf(floor)) {
-      if (laneIsAbove(other, floor) && !paintsAbove(other, floor)) raiseAbove(other, floor);
-    }
-  }
-}
-
-/**
- * Compute z-index patches so each edited clip's stacking matches its lane order.
- *
- * @param elements  The FULL post-edit element set (edited clips already carry
- *                  their new lane/time). Untouched clips keep their current z.
- * @param editedKeys  Keys of the clip(s) the user just edited.
- * @returns  Minimal z patches. When a single-clip patch realises the order it is
- *           the only patch (authored z of neighbours untouched); when ties or a
- *           z=0 floor make that impossible, the minimum set of overlapping
- *           neighbours is bumped too so the lane move is always realisable with
- *           all z ≥ 0. Non-overlapping / already-correct edits yield nothing.
- *
- * Multi-clip edits: each edited clip is resolved against the CURRENT (already-
- * patched) z of all OTHER clips, lower lane first, so a group dragged onto a busy
- * region stacks consistently.
+ * The z-index patches for a row move: each edited clip, and only it, is raised (`up`) or lowered (`down`) against the
+ * clips it overlaps in time in its own paint scope. Clips whose live z is unresolved (non-finite) and audio clips take
+ * no part. Several edited clips resolve against each other's new z: the bottom one first when moving up, the top one
+ * first when moving down.
  */
 export function computeStackingPatches(
   elements: StackingElement[],
   editedKeys: Iterable<string>,
+  direction: StackingDirection,
 ): StackingPatch[] {
   const editedSet = new Set(editedKeys);
-  if (editedSet.size === 0) return [];
+  const live = elements
+    .filter((e) => Number.isFinite(e.zIndex) && !e.isAudio)
+    .map((e) => ({ ...e }));
+  const edited = live
+    .filter((e) => editedSet.has(e.key))
+    .sort((a, b) => (direction === "up" ? b.track - a.track : a.track - b.track));
 
-  // Drop clips whose live z couldn't be resolved (non-finite / NaN): a fabricated
-  // z=0 would enter the boundary math as a phantom neighbour at the z-floor. An
-  // unresolved clip is neither a neighbour nor resolvable as an edit, so it is
-  // excluded outright (item 13).
-  const allResolved = elements.filter((e) => Number.isFinite(e.zIndex));
-
-  // Leaf z is only meaningful within ONE source document and stacking context:
-  // across either boundary the ancestor composition/context decides paint order.
-  // Restrict the computation to the edited clips' own paint scope(s).
-  const editedScopes = new Set(allResolved.filter((e) => editedSet.has(e.key)).map(paintScopeKey));
-  const resolved = allResolved.filter((e) => editedScopes.has(paintScopeKey(e)));
-
-  // Mutable z snapshot so edits + cascaded bumps see each other's applied z.
-  const byKey = new Map<string, MutZ>(resolved.map((e) => [e.key, { ...e }]));
-  const edited = resolved
-    .filter((e) => editedSet.has(e.key) && !e.isAudio)
-    .map((e) => byKey.get(e.key)!)
-    // Resolve lower-lane (renders below) clips first so their new z is visible
-    // to higher-lane siblings resolved after them.
-    .sort((a, b) => b.track - a.track);
-
-  const changed = new Map<string, number>();
-  const patchZ = (clip: MutZ, z: number): void => {
-    clip.zIndex = z;
-    changed.set(clip.key, z);
-  };
-
-  // The full live set, so the transitive cascade can reach clips that overlap a
-  // LIFTED neighbour without overlapping the edited clip itself (#2198).
-  const all = [...byKey.values()];
-  const overlappersOf = (clip: MutZ): MutZ[] =>
-    all.filter(
-      (o) => o.key !== clip.key && !o.isAudio && samePaintScope(clip, o) && overlapsInTime(clip, o),
-    );
-
-  for (const clip of edited) {
-    resolveEditedZ(clip, overlappersOf(clip), overlappersOf, patchZ);
-  }
-
-  // Emit in a stable order (edited clips first in their resolve order, then any
-  // cascaded neighbours) — deterministic for tests and undo grouping.
-  const emitted = new Set<string>();
   const patches: StackingPatch[] = [];
   for (const clip of edited) {
-    if (changed.has(clip.key) && !emitted.has(clip.key)) {
-      patches.push({ key: clip.key, zIndex: changed.get(clip.key)! });
-      emitted.add(clip.key);
-    }
-  }
-  for (const [key, zIndex] of changed) {
-    if (!emitted.has(key)) {
-      patches.push({ key, zIndex });
-      emitted.add(key);
-    }
+    const overlapping = live.filter(
+      (o) => o.key !== clip.key && overlapsInTime(clip, o) && samePaintScope(clip, o),
+    );
+    const zIndex = direction === "up" ? raisedZ(clip, overlapping) : loweredZ(clip, overlapping);
+    if (zIndex === null) continue;
+    clip.zIndex = zIndex;
+    patches.push({ key: clip.key, zIndex });
   }
   return patches;
 }

package/src/player/components/useTimelineStackingSync.ts

@@ -55,7 +55,7 @@ export function useTimelineStackingSync({
   // NaN (NOT 0) when the element can't be resolved in the preview iframe — a
   // nested / unmounted sub-comp node, or one outside the active file. Fabricating
   // z=0 would enter computeStackingPatches as a real overlapping neighbour at the
-  // z-floor and skew the boundary math; a non-finite value tells it to EXCLUDE this
+  // z-floor; a non-finite value tells it to EXCLUDE this
   // clip instead. NaN (rather than null) keeps the return assignable to the
   // `(el) => number` reader contract the drag hook / commit deps declare.
   const readClipZIndex = useCallback(

package/src/player/hooks/usePlaybackKeyboard.ts

@@ -60,6 +60,7 @@ export function usePlaybackKeyboard({
 
   const shuttle = useCallback(
     (direction: "forward" | "backward") => {
+      if (usePlayerStore.getState().playLocked) return;
       if (shuttleDirectionRef.current === direction) {
         shuttleSpeedIndexRef.current = Math.min(
           shuttleSpeedIndexRef.current + 1,

package/src/player/hooks/useTimelinePlayer.playLock.test.ts

@@ -0,0 +1,137 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, expect, it, vi } from "vitest";
+import {
+  makeAdapterWindow,
+  makeFakeIframe,
+  renderTimelinePlayerHarness,
+  resetPlayerStore,
+} from "./timelinePlayerTestHarness";
+import { usePlayerStore } from "../store/playerStore";
+import { scrubMusicAtSeek } from "../lib/playbackScrub";
+
+vi.mock("../lib/playbackScrub", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/playbackScrub")>()),
+  scrubMusicAtSeek: vi.fn(),
+}));
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  resetPlayerStore();
+  usePlayerStore.setState({ playLocked: false, loopEnabled: false, playbackRate: 1 });
+  vi.mocked(scrubMusicAtSeek).mockClear();
+});
+
+function readyPlayer() {
+  const { api, root } = renderTimelinePlayerHarness();
+  const { adapter, win } = makeAdapterWindow();
+  act(() => {
+    api.iframeRef.current = makeFakeIframe(win);
+    api.onIframeLoad();
+    usePlayerStore.setState({ timelineReady: true });
+  });
+  return { api, root, adapter };
+}
+
+const press = (key: string) =>
+  act(() => {
+    window.dispatchEvent(new KeyboardEvent("keydown", { key, code: `Key${key.toUpperCase()}` }));
+  });
+
+it("starts nothing while the host holds playback: Play, a playback request or play backward", () => {
+  const { api, root, adapter } = readyPlayer();
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  act(() => api.play());
+  act(() => usePlayerStore.getState().requestPlayback(true));
+  press("j");
+  expect(adapter.play).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+  act(() => root.unmount());
+});
+
+it("J and L keep the chosen speed while the host holds playback", () => {
+  const { root } = readyPlayer();
+  act(() => usePlayerStore.getState().setPlaybackRate(0.5));
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  press("l");
+  press("j");
+  expect(usePlayerStore.getState().playbackRate).toBe(0.5);
+  act(() => root.unmount());
+});
+
+it("a looping film reaching its end while held stops instead of starting again", () => {
+  const frames: FrameRequestCallback[] = [];
+  const raf = vi.spyOn(window, "requestAnimationFrame").mockImplementation((tick) => {
+    frames.push(tick);
+    return frames.length;
+  });
+  const { api, root, adapter } = readyPlayer();
+  act(() => usePlayerStore.setState({ loopEnabled: true }));
+  act(() => api.play());
+  // Held with the store already reading stopped, so nothing pauses the frame loop first.
+  act(() => usePlayerStore.setState({ playLocked: true, isPlaying: false }));
+  adapter.seek(30);
+  act(() => frames.at(-1)!(0));
+  expect(adapter.play).toHaveBeenCalledTimes(1);
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+  raf.mockRestore();
+  act(() => root.unmount());
+});
+
+it("turning the hold on before the preview has a player still clears playing", () => {
+  const { root } = renderTimelinePlayerHarness();
+  act(() => usePlayerStore.setState({ isPlaying: true }));
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+  act(() => root.unmount());
+});
+
+it("a seek that would keep playing does not resume while the host holds playback", () => {
+  const { api, root, adapter } = readyPlayer();
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  // The store still reads playing (a host that set the hold before the player caught up): only the hold stops it.
+  act(() => usePlayerStore.setState({ isPlaying: true }));
+  act(() => {
+    api.seek(5, { keepPlaying: true });
+  });
+  expect(adapter.play).not.toHaveBeenCalled();
+  act(() => root.unmount());
+});
+
+it("a seek while the host holds playback moves the picture without scrub audio", () => {
+  const { api, root, adapter } = readyPlayer();
+  act(() => {
+    api.seek(2);
+  });
+  expect(scrubMusicAtSeek).toHaveBeenCalledTimes(1);
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  act(() => {
+    api.seek(4);
+  });
+  expect(adapter.getTime()).toBe(4);
+  expect(scrubMusicAtSeek).toHaveBeenCalledTimes(1);
+  act(() => root.unmount());
+});
+
+it("a timeline reset keeps the hold: the host owns it", () => {
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  act(() => usePlayerStore.getState().reset());
+  expect(usePlayerStore.getState().playLocked).toBe(true);
+});
+
+it("turning the hold on pauses a playing film; turning it off lets Play start again", () => {
+  const { api, root, adapter } = readyPlayer();
+  act(() => api.play());
+  expect(usePlayerStore.getState().isPlaying).toBe(true);
+  act(() => usePlayerStore.getState().setPlayLocked(true));
+  expect(adapter.pause).toHaveBeenCalled();
+  expect(usePlayerStore.getState().isPlaying).toBe(false);
+  act(() => usePlayerStore.getState().setPlayLocked(false));
+  act(() => api.play());
+  expect(adapter.play).toHaveBeenCalledTimes(2);
+  expect(usePlayerStore.getState().isPlaying).toBe(true);
+  act(() => root.unmount());
+});

package/src/player/hooks/useTimelinePlayer.ts

@@ -200,7 +200,8 @@ export function useTimelinePlayer({
     applyPreviewAudioFlags(iframeRef.current, audioMuted, audioVolume);
   }, []);
   const play = useCallback(() => {
-    if (!usePlayerStore.getState().timelineReady) return;
+    const { timelineReady, playLocked } = usePlayerStore.getState();
+    if (!timelineReady || playLocked) return;
     stopRAFLoop();
     stopReverseLoop();
     stopScrubPreviewAudio();
@@ -286,9 +287,8 @@ export function useTimelinePlayer({
   const pause = useCallback(() => {
     stopReverseLoop();
     const adapter = getAdapter();
-    if (!adapter) return;
-    adapter.pause();
-    setCurrentTime(adapter.getTime()); // sync store so Split/Delete have accurate time
+    adapter?.pause();
+    if (adapter) setCurrentTime(adapter.getTime()); // sync store so Split/Delete have accurate time
     setIsPlaying(false);
     shuttleDirectionRef.current = null;
     shuttleSpeedIndexRef.current = 0;
@@ -306,17 +306,19 @@ export function useTimelinePlayer({
       const duration = Math.max(0, adapter.getDuration());
       const nextTime = clampToDuration(time, duration);
       const keepPlaying = options?.keepPlaying === true;
+      const { playLocked, isPlaying: storeWasPlaying } = usePlayerStore.getState();
       const shouldResumeAfterSeek = shouldResumeForwardPlaybackAfterSeek({
         keepPlaying,
         wasReverseShuttle,
-        storeWasPlaying: usePlayerStore.getState().isPlaying,
+        storeWasPlaying,
         duration,
         nextTime,
+        playLocked,
       });
       adapter.seek(nextTime, options);
       publishSeek(nextTime, options); // Direct DOM updates (playhead, timecode, progress) — no re-render
       setCurrentTime(nextTime); // sync store so Split/Delete have accurate time
-      if (!shouldResumeAfterSeek && !keepPlaying) scrubMusicAtSeek(iframeRef.current, nextTime);
+      if (!keepPlaying && !playLocked) scrubMusicAtSeek(iframeRef.current, nextTime);
       if (shouldResumeAfterSeek) {
         stopRAFLoop();
         applyPlaybackRate(usePlayerStore.getState().playbackRate);
@@ -349,6 +351,13 @@ export function useTimelinePlayer({
     ],
   );
 
+  useEffect(
+    () =>
+      usePlayerStore.subscribe((state, prev) => {
+        if (state.playLocked && !prev.playLocked && state.isPlaying) pause();
+      }),
+    [pause],
+  );
   useEffect(() => {
     return usePlayerStore.subscribe((state, prev) => {
       if (state.requestedSeekTime !== null && state.requestedSeekTime !== prev.requestedSeekTime) {

package/src/player/hooks/useTimelinePlayerLoop.ts

@@ -60,7 +60,7 @@ export function useTimelinePlayerLoop({
         const looping = usePlayerStore.getState().loopEnabled && dur > 0;
         setLoopStart(looping ? loopStart : null);
         if (time >= loopEnd) {
-          if (looping) {
+          if (looping && !usePlayerStore.getState().playLocked) {
             // keepPlaying skips the adapter's implicit pause; play() below is then a no-op.
             adapter.seek(loopStart, { keepPlaying: true });
             liveTime.notify(loopStart);

package/src/player/lib/playbackSeek.ts

@@ -4,8 +4,10 @@ export function shouldResumeForwardPlaybackAfterSeek(input: {
   storeWasPlaying: boolean;
   duration: number;
   nextTime: number;
+  playLocked: boolean;
 }): boolean {
   return (
+    !input.playLocked &&
     input.keepPlaying &&
     !input.wasReverseShuttle &&
     input.storeWasPlaying &&

package/src/player/store/readinessSlice.ts

@@ -13,6 +13,8 @@ export interface PlaybackReadinessSlice {
   previewBooted: boolean;
   setTimelineReady: (ready: boolean) => void;
   markPreviewBooted: () => void;
+  playLocked: boolean;
+  setPlayLocked: (locked: boolean) => void;
   /** Sets timelineReady once doc's readiness inputs settle, or immediately
    *  if doc is null. A wait a later call supersedes never wins the race.
    *  Waits for doc's load step first: it pauses and rewinds the preview, so a
@@ -47,6 +49,8 @@ export function createPlaybackReadinessSlice(
     timelineReady: false,
     previewBooted: false,
     markPreviewBooted: () => set({ previewBooted: true }),
+    playLocked: false,
+    setPlayLocked: (locked) => set({ playLocked: locked }),
     setTimelineReady: (ready) => {
       timelineReadyGeneration++;
       set({ timelineReady: ready });

package/src/timelineStackingSyncExport.test.tsx

@@ -24,8 +24,9 @@ it("restacks the host's preview when a lane move puts a clip below another", asy
   const iframe = document.createElement("iframe");
   document.body.appendChild(iframe);
   const doc = iframe.contentDocument!;
-  // No authored z: DOM order paints tag over title, which matches the rows until the move.
-  doc.body.innerHTML = '<div id="title"></div><div id="tag"></div><div id="note"></div>';
+  // Tag (top row) paints over title, matching the rows until the move.
+  doc.body.innerHTML =
+    '<div id="title" style="z-index: 2"></div><div id="tag" style="z-index: 3"></div><div id="note"></div>';
   const clip = (id: string, start: number, duration: number, track: number) =>
     ({ id, key: id, domId: id, tag: "div", start, duration, track }) as const;
   usePlayerStore.setState({