@hyperframes/studio 0.8.47 → 0.8.49

package/src/player/components/useTimelineGeometry.ts

@@ -93,9 +93,14 @@ export function useTimelineGeometry({
   useEffect(() => {
     if (zoomMode !== "manual" || isDragging.current) return;
     const el = scrollRef.current;
-    const target = lastScrollLeftRef.current;
-    if (!el || target <= 0) return;
+    if (!el) return;
+    // Read the ref inside the frame, not here: a sibling effect in the same
+    // commit (a fresh reveal) can still update lastScrollLeftRef before this
+    // frame runs, and a value captured now would fight that reveal with a
+    // stale target.
     const raf = requestAnimationFrame(() => {
+      const target = lastScrollLeftRef.current;
+      if (target <= 0) return;
       const max = Math.max(0, el.scrollWidth - el.clientWidth);
       const next = Math.min(target, max);
       if (Math.abs(el.scrollLeft - next) > 0.5) el.scrollLeft = next;

package/src/player/components/useTimelineGeometryFocusOrder.test.tsx

@@ -0,0 +1,184 @@
+// @vitest-environment happy-dom
+
+import React, { act, useMemo, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { timelineClipFocusId, timelineTrackRowId } from "./timelineNavigationIdentity";
+import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
+import { useTimelineGeometry } from "./useTimelineGeometry";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const nextFrame = () => new Promise<number>((resolve) => requestAnimationFrame(resolve));
+
+const oldElement = { id: "old", tag: "div", start: 0, duration: 1, track: 1 };
+const heroElement = { id: "hero", tag: "div", start: 20, duration: 2, track: 1 };
+const clipId = timelineClipFocusId("hero");
+const rowId = timelineTrackRowId(1);
+const beforeRows: readonly TimelineLogicalRow[] = [
+  {
+    id: rowId,
+    kind: "row",
+    physicalTrackKey: 1,
+    logicalIndex: 0,
+    level: 1,
+    parentId: null,
+    elementId: null,
+    expandable: false,
+    expanded: false,
+    items: [],
+  },
+];
+const afterRows: readonly TimelineLogicalRow[] = [
+  {
+    id: rowId,
+    kind: "row",
+    physicalTrackKey: 1,
+    logicalIndex: 0,
+    level: 1,
+    parentId: null,
+    elementId: null,
+    expandable: false,
+    expanded: false,
+    items: [{ id: clipId, kind: "clip", rowId, elementId: "hero", time: 21 }],
+  },
+];
+
+// Renders the two real production hooks side by side, in a caller-chosen call
+// order, to test whether their interaction actually depends on that order —
+// as opposed to simulating one hook's effect by hand.
+function OrderHarness({
+  order,
+  expandedElements,
+  logicalRows,
+  lastScrollLeftRef,
+}: {
+  order: "geometry-first" | "coordinator-first";
+  expandedElements: (typeof oldElement)[];
+  logicalRows: readonly TimelineLogicalRow[];
+  lastScrollLeftRef: React.RefObject<number>;
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const isDragging = useRef(false);
+  const ppsRef = useRef(0);
+  const fitPpsRef = useRef(0);
+  const rowGeometry = useMemo(() => createTimelineRowGeometry([1], [48]), []);
+
+  const runGeometry = () =>
+    useTimelineGeometry({
+      viewportWidth: 300,
+      effectiveDuration: 60,
+      zoomMode: "manual",
+      manualZoomPercent: 100,
+      ppsRef,
+      fitPpsRef,
+      draggedClip: null,
+      resizingClip: null,
+      expandedElements,
+      isDragging,
+      scrollRef,
+      lastScrollLeftRef,
+      contentOrigin: 32,
+    });
+  const runFocus = () =>
+    useTimelineFocusCoordinator({
+      scrollRef,
+      logicalRows,
+      elements: expandedElements,
+      rowGeometry,
+      pixelsPerSecond: 100,
+      contentOrigin: 32,
+      allowHorizontal: true,
+      viewportVersion: logicalRows.length,
+      projectId: "project-a",
+      sessionEpoch: 1,
+      syncScrollViewport: () => {},
+      lastScrollLeftRef,
+    });
+
+  // `order` is fixed for the lifetime of one mounted harness, so this call
+  // order is stable across that instance's renders.
+  if (order === "geometry-first") {
+    runGeometry();
+    runFocus();
+  } else {
+    runFocus();
+    runGeometry();
+  }
+
+  return (
+    <div
+      ref={(node) => {
+        scrollRef.current = node;
+        if (node) {
+          Object.defineProperty(node, "clientWidth", { configurable: true, value: 300 });
+          Object.defineProperty(node, "clientHeight", { configurable: true, value: 100 });
+          Object.defineProperty(node, "scrollWidth", { configurable: true, value: 20_000 });
+        }
+      }}
+    />
+  );
+}
+
+let host: HTMLDivElement;
+let root: Root;
+beforeEach(() => {
+  usePlayerStore.setState({ timelineProjectId: "project-a", timelineSessionEpoch: 1 });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+describe.each(["geometry-first", "coordinator-first"] as const)(
+  "useTimelineGeometry + useTimelineFocusCoordinator, %s",
+  (order) => {
+    it("a same-commit reveal survives the geometry restore effect regardless of hook registration order", async () => {
+      const lastScrollLeftRef = { current: 132 };
+      await act(async () => {
+        root.render(
+          <OrderHarness
+            order={order}
+            expandedElements={[oldElement]}
+            logicalRows={beforeRows}
+            lastScrollLeftRef={lastScrollLeftRef}
+          />,
+        );
+      });
+      const scroll = host.firstElementChild as HTMLDivElement;
+      scroll.scrollLeft = 132;
+      await act(async () => {
+        await nextFrame();
+      });
+      expect(scroll.scrollLeft).toBe(132);
+
+      // One commit: the drop both adds the element (expandedElements changes,
+      // arming the geometry restore effect) and resolves the focus request
+      // (arming the coordinator's reveal), exactly as Timeline.tsx renders them.
+      usePlayerStore.getState().requestTimelineFocus(clipId);
+      await act(async () => {
+        root.render(
+          <OrderHarness
+            order={order}
+            expandedElements={[oldElement, heroElement]}
+            logicalRows={afterRows}
+            lastScrollLeftRef={lastScrollLeftRef}
+          />,
+        );
+      });
+      await act(async () => {
+        await nextFrame();
+      });
+
+      expect(scroll.scrollLeft).toBe(1_944);
+      expect(lastScrollLeftRef.current).toBe(1_944);
+    });
+  },
+);

package/src/player/components/useTimelineLogicalFocus.ts

@@ -63,6 +63,7 @@ export function useTimelineLogicalFocus(input: TimelineLogicalFocusInput) {
     projectId,
     sessionEpoch: input.sessionEpoch,
     syncScrollViewport: input.syncScrollViewport,
+    lastScrollLeftRef: input.lastScrollLeftRef,
   });
   const rows = useTimelineRowVirtualization({
     scrollRef: input.scrollRef,

package/src/player/components/useTimelineTrackLayout.ts

@@ -1,7 +1,7 @@
 import { useMemo, useRef } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { animationLaneGroups } from "./TimelinePropertyLanes";
-import { isAudioTimelineElement } from "../../utils/timelineInspector";
+import { isAudioOrVideoTimelineElement } from "../../utils/timelineInspector";
 import { elementAutomationLanes, groupAutomationLanes } from "./automationLaneData";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { DraggedClipState } from "./timelineClipDragTypes";
@@ -44,14 +44,15 @@ export function trackShowsBeatStrip(
 }
 
 /**
- * Automation lanes on one clip, or 0 for anything that is not audio.
+ * Automation lanes on one clip.
  *
- * An audio clip can be worth expanding without carrying a single tween, so this
- * counts toward whether a track has anything to disclose. A function rather than
- * a map so every caller reads the same cached parse and none can drift.
+ * A clip can be worth expanding without carrying a single tween, so this counts
+ * toward whether a track has anything to disclose. Gated on
+ * `isAudioOrVideoTimelineElement`, matching `groupAutomationLanes`. A function
+ * rather than a map so every caller reads the same cached parse and none can drift.
  */
 function automationLaneCountOf(element: TimelineElement): number {
-  return isAudioTimelineElement(element) ? elementAutomationLanes(element).length : 0;
+  return isAudioOrVideoTimelineElement(element) ? elementAutomationLanes(element).length : 0;
 }
 
 /**

package/src/player/hooks/usePlaybackKeyboard.test.ts

@@ -1,4 +1,5 @@
 // @vitest-environment happy-dom
+// fallow-ignore-file code-duplication
 
 import React, { act, useEffect } from "react";
 import { createRoot } from "react-dom/client";
@@ -171,6 +172,39 @@ describe("usePlaybackKeyboard — keyboard layout independence (#834)", () => {
 
     expect(spies.play).toHaveBeenCalledTimes(1);
   });
+
+  it("'A' does not seek to the in-point while the razor tool is armed, so it's free for the razor's own return-to-select binding", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5, activeTool: "razor" });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a" }));
+    });
+
+    expect(spies.seek).not.toHaveBeenCalled();
+  });
+
+  it("'A' still seeks to the in-point when the razor tool isn't armed", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5, activeTool: "select" });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a" }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
+  });
+
+  it("Shift+A still seeks to the in-point while the razor is armed, since only plain A exits the razor", () => {
+    const { dispatch, spies } = setupHook();
+    usePlayerStore.setState({ inPoint: 1.5, activeTool: "razor" });
+
+    act(() => {
+      dispatch(keydown({ code: "KeyA", key: "a", shiftKey: true }));
+    });
+
+    expect(spies.seek).toHaveBeenCalledWith(1.5, { keepPlaying: true });
+  });
 });
 
 describe("usePlaybackKeyboard — mute & loop shortcuts (#905)", () => {

package/src/player/hooks/usePlaybackKeyboard.ts

@@ -26,6 +26,14 @@ interface UsePlaybackKeyboardParams {
   seek: (time: number, options?: { keepPlaying?: boolean }) => void;
 }
 
+// The razor tool owns plain "a" (return to select) while it's armed; this
+// can't rely on defaultPrevented since both listeners register on window and
+// fire in an order this hook doesn't control. Shift+A and Alt+A are left for
+// the in-point seek below, since only plain A means "exit the razor".
+function shouldRazorClaimPlainA(e: KeyboardEvent): boolean {
+  return !e.shiftKey && !e.altKey && usePlayerStore.getState().activeTool === "razor";
+}
+
 export function usePlaybackKeyboard({
   iframeRef,
   shuttleDirectionRef,
@@ -79,6 +87,10 @@ export function usePlaybackKeyboard({
     }
   }, [play, pause]);
 
+  // Pre-existing dispatcher, already over the complexity gate before this
+  // branch's one-line "a" fix touched it. A real fix is a dispatch-table
+  // rewrite, out of scope here; the branch this PR changed is its own function.
+  // fallow-ignore-next-line complexity
   const handlePlaybackKeyDown = useCallback(
     (e: KeyboardEvent) => {
       if (e.defaultPrevented) return;
@@ -161,6 +173,7 @@ export function usePlaybackKeyboard({
         return;
       }
       if (key === "a") {
+        if (shouldRazorClaimPlainA(e)) return;
         e.preventDefault();
         seek(usePlayerStore.getState().inPoint ?? 0, { keepPlaying: true });
         return;

package/src/player/lib/timelineElementHelpers.ts

@@ -392,6 +392,14 @@ export function deriveTimelineStoreKey(params: {
   return buildTimelineElementKey({ id: "", fallbackIndex: 0, ...params });
 }
 
+/**
+ * {@link deriveTimelineStoreKey} for a caller that already has a DOM id in
+ * hand (e.g. one it just minted), so the undefined branch never applies.
+ */
+export function deriveTimelineStoreKeyForDomId(domId: string, sourceFile?: string): string {
+  return deriveTimelineStoreKey({ domId, sourceFile })!;
+}
+
 // ---------------------------------------------------------------------------
 // DOM node querying
 // ---------------------------------------------------------------------------

package/src/player/lib/timelineIframeHelpers.test.ts

@@ -1,4 +1,5 @@
 // @vitest-environment jsdom
+// fallow-ignore-file code-duplication
 import { describe, expect, it, vi } from "vitest";
 import {
   applyPreviewAudioFlags,
@@ -54,6 +55,27 @@ describe("buildMissingCompositionElements — hfId (R7)", () => {
     expect(entry).toBeDefined();
     expect(entry?.hfId).toBeUndefined();
   });
+
+  it("carries the resolved track onto authoredTrack, so splitting a recovered composition host can't drift to a new row", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <div
+          data-composition-id="scene-c"
+          data-composition-src="scenes/c.html"
+          data-track-index="2"
+          data-start="0"
+          data-duration="5"
+        ></div>
+      </div>
+    `);
+
+    const { missing } = buildMissingCompositionElements(doc, window as IframeWindow, [], 10);
+    const entry = missing[0];
+
+    expect(entry).toBeDefined();
+    expect(entry?.track).toBe(2);
+    expect(entry?.authoredTrack).toBe(2);
+  });
 });
 
 describe("setPreviewMediaVolume", () => {

package/src/player/lib/timelineIframeHelpers.ts

@@ -452,6 +452,7 @@ function buildMissingCompositionEntry(params: {
     start: window.start,
     duration: window.duration,
     track: timing.trackIndex,
+    authoredTrack: timing.trackIndex,
     domId: optionalNonEmpty(element.id),
     hfId: optionalNonEmpty(element.getAttribute("data-hf-id")),
     selector,

package/src/player/store/playerStore.ts

@@ -108,14 +108,14 @@ interface PlayerState extends PlayerStoreSlices {
   /** Timeline magnet toggle — when false, clip drags/trims/drops never snap. */
   timelineSnapEnabled: boolean;
   setTimelineSnapEnabled: (enabled: boolean) => void;
+  /** Keeps the main track gapless on delete; distinct from the magnet above. */
+  rippleEditEnabled: boolean;
+  setRippleEditEnabled: (enabled: boolean) => void;
   /** Transport + ruler readout: timecode ("time") or frame number ("frame"). */
   timeDisplayMode: TimelineTimeDisplayMode;
   setTimeDisplayMode: (mode: TimelineTimeDisplayMode) => void;
-  /**
-   * Pin the timeline zoom to its current visual scale before a duration-changing
-   * edit, so a subsequent duration change (which recomputes fit-pps) stops
-   * rescaling every clip. No-op once already pinned (mode is "manual").
-   */
+  /** Pin the timeline zoom to its current scale before a duration change, so
+   *  it stops rescaling every clip. No-op once already pinned. */
   pinTimelineZoom: (currentPixelsPerSecond: number, fitPixelsPerSecond: number) => void;
   /** The timeline's live pixels-per-second + fit basis, published by <Timeline>. */
   timelinePps: number;
@@ -149,26 +149,16 @@ interface PlayerState extends PlayerStoreSlices {
   /** Clears project data without creating a new hard-project session. */
   reset: () => void;
 
-  /**
-   * Request a seek from outside the player loop (e.g. Layers panel).
-   * useTimelinePlayer subscribes and calls adapter.seek() + liveTime.notify().
-   */
+  /** Request a seek from outside the player loop (e.g. Layers panel);
+   *  useTimelinePlayer subscribes and calls adapter.seek() + liveTime.notify(). */
   requestedSeekTime: number | null;
   requestSeek: (time: number) => void;
   clearSeekRequest: () => void;
 
-  /**
-   * Request the transport start or stop from outside the player loop.
-   *
-   * The FX rack auditions a preset by writing it to the running graph, which is
-   * silent while the transport is paused — so hovering one has to start
-   * playback, and leaving has to put the playhead back where it was. Hovering is
-   * not an edit and must not cost the author their place.
-   *
-   * A nonce rather than a bare boolean: two hovers in a row both want play, and
-   * without it the second request is indistinguishable from the first having
-   * already been served.
-   */
+  /** Request the transport start or stop from outside the player loop: the FX
+   *  rack starts playback to audition a preset (silent while paused) and
+   *  restores the playhead on leave, without costing the author their place.
+   *  A nonce, not a bare boolean, so two hovers in a row both register. */
   playbackRequest: { playing: boolean; returnTo: number | null; nonce: number } | null;
   requestPlayback: (playing: boolean, returnTo?: number | null) => void;
   clearPlaybackRequest: () => void;
@@ -475,6 +465,11 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
     writeStudioUiPreferences({ timelineSnapEnabled: enabled });
     set({ timelineSnapEnabled: enabled });
   },
+  rippleEditEnabled: readStudioUiPreferences().rippleEditEnabled ?? true, // default on
+  setRippleEditEnabled: (enabled) => {
+    writeStudioUiPreferences({ rippleEditEnabled: enabled });
+    set({ rippleEditEnabled: enabled });
+  },
   timeDisplayMode: readStudioUiPreferences().timeDisplayMode ?? "time",
   setTimeDisplayMode: (mode) => {
     writeStudioUiPreferences({ timeDisplayMode: mode });

package/src/player/store/readinessSlice.ts

@@ -1,7 +1,8 @@
 /** Gates `timelineReady` on the composition's declared readiness inputs
- * (media, for now) instead of just a known duration. The generation counter
- * is module-scope, not store state: it guards an in-flight settlement, not
- * something a component reads, so bumping it shouldn't trigger a render. */
+ * (media, compute, and the paint-and-idle default) instead of just a known
+ * duration. The generation counter is module-scope, not store state: it
+ * guards an in-flight settlement, not something a component reads, so
+ * bumping it shouldn't trigger a render. */
 import type { StoreApi } from "zustand";
 import { settleCompositionReadiness } from "@hyperframes/core/composition-readiness";
 

package/src/utils/blockInstaller.test.ts

@@ -63,5 +63,9 @@ describe("addBlockToProject", () => {
     expect(source).toContain('data-start="2.5"');
     expect(source).toContain('data-duration="4.25"');
     expect(source).toContain('data-track-index="3"');
+    // hostKey addresses the new element the same way the timeline selects
+    // clips (sourceFile#domId), so the caller can select and reveal it.
+    expect(result?.hostKey).toBe("compositions/scene.html#camcorder-hud");
+    expect(source).toContain('id="camcorder-hud"');
   });
 });

package/src/utils/blockInstaller.ts

@@ -11,6 +11,7 @@ import { formatTimelineAttributeNumber } from "../player/components/timelineEdit
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
 import type { EditHistoryKind } from "./editHistory";
 import { extendRootDurationInSource } from "./rootDuration";
+import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
 function getMaxZIndexFromIframe(iframe: HTMLIFrameElement | null): number {
   try {
@@ -174,7 +175,7 @@ function buildSubCompositionHtml({
 
 export async function addBlockToProject(
   opts: AddBlockOptions,
-): Promise<{ block: RegistryItem; compositionPath: string } | null> {
+): Promise<{ block: RegistryItem; compositionPath: string; hostKey: string } | null> {
   const {
     projectId,
     blockName,
@@ -213,8 +214,9 @@ export async function addBlockToProject(
       currentTime: opts.currentTime ?? 0,
     });
     const { width, height } = resolveTimelineAssetCompositionSize(originalContent);
+    const hostId = buildUniqueCompositionId(block.name, collectHtmlIds(originalContent));
     const subComposition = buildSubCompositionHtml({
-      id: buildUniqueCompositionId(block.name, collectHtmlIds(originalContent)),
+      id: hostId,
       compositionFile,
       start,
       duration,
@@ -242,7 +244,11 @@ export async function addBlockToProject(
     await refreshFileTree();
     reloadPreview();
 
-    return { block, compositionPath: compositionFile };
+    return {
+      block,
+      compositionPath: compositionFile,
+      hostKey: deriveTimelineStoreKeyForDomId(hostId, targetPath),
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : "Failed to add block";
     showToast(message);

package/src/utils/razorSplitTransaction.test.ts

@@ -37,6 +37,16 @@ describe("buildAtomicCutIntents", () => {
     expect(intents[0].targets.map((target) => target.originalId)).toEqual(["host-a", "host-b"]);
   });
 
+  it("carries the element's authored track onto the cut target, so both split halves stay pinned to it server-side", () => {
+    const intents = buildAtomicCutIntents([element({ authoredTrack: 2 })], 2, "index.html");
+    expect(intents[0].targets[0].track).toBe(2);
+  });
+
+  it("falls back to the resolved track when the element has no authoredTrack", () => {
+    const intents = buildAtomicCutIntents([element({ track: 3 })], 2, "index.html");
+    expect(intents[0].targets[0].track).toBe(3);
+  });
+
   it("rebases each nested target into its own source-file coordinates", () => {
     const intents = buildAtomicCutIntents(
       [element({ start: 8, duration: 4, expandedParentStart: 6, sourceFile: "scene.html" })],

package/src/utils/razorSplitTransaction.ts

@@ -4,6 +4,7 @@ import { buildPatchTarget } from "./timelineElementSplit";
 import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
 import { buildProjectApiPath } from "./projectRouting";
 import { markStudioWriteToken } from "./studioFileVersion";
+import { resolveElementTrack } from "./studioHelpers";
 
 type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
 
@@ -16,6 +17,7 @@ interface CutTarget {
   playbackStart?: number;
   playbackRate?: number;
   isComposition?: boolean;
+  track?: number;
 }
 
 interface CutFileIntent {
@@ -69,6 +71,9 @@ function buildCutTarget(
     ...(element.playbackStart != null ? { playbackStart: element.playbackStart } : {}),
     ...(element.playbackRate != null ? { playbackRate: element.playbackRate } : {}),
     ...(element.kind === "composition" ? { isComposition: true } : {}),
+    // Pin both halves to the current track: unstamped, the runtime's positional
+    // fallback (parseAuthoredTrack) renumbers the new sibling onto a new row.
+    track: resolveElementTrack(element),
   };
 }
 

package/src/utils/retryBudget.ts

@@ -0,0 +1,20 @@
+import type { MutableRefObject } from "react";
+
+export interface RetryBudgetState<K> {
+  id: K;
+  count: number;
+}
+
+// A target still resolving (a just-dropped/pasted/duplicated element, or a
+// preview still reloading) heals within a few retries; one that never will
+// would otherwise retry forever. A new id resets the count.
+export function recordRetryAttempt<K>(
+  ref: MutableRefObject<RetryBudgetState<K>>,
+  id: K,
+  maxRetries: number,
+): boolean {
+  const previous = ref.current;
+  const count = previous.id === id ? previous.count + 1 : 1;
+  ref.current = { id, count };
+  return count <= maxRetries;
+}

package/src/utils/sdkCutover.familyGate.test.ts

@@ -41,6 +41,10 @@ describe("SDK family gate mapping", () => {
         {} as never,
         deps,
       ),
-    ).resolves.toMatchObject({ status: "declined", reason: "ineligible_operation" });
+      // The dom family is off, so the gate declines on the FLAG, not on the op
+      // batch (which is a perfectly eligible inline-style edit). Before the
+      // reason split this reported `ineligible_operation`, which read as "the
+      // SDK cannot express this edit" when the truth was "this family is off".
+    ).resolves.toMatchObject({ status: "declined", reason: "feature_disabled" });
   });
 });

package/src/utils/sdkCutover.test.ts

@@ -649,6 +649,57 @@ window.__timelines = { main: tl };</script></div>
     for (const candidate of published) candidate.dispose();
   });
 
+  it("does not resurrect an element a prior REST write already deleted, even with a stale live session", async () => {
+    // A delete persists via the server REST path, then a same-gesture ripple
+    // move reaches an SDK-eligible batch persist while `live` was never
+    // reloaded. Prove the candidate rebases on the post-delete disk bytes.
+    const twoElementHtml = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-hf-root>
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="5" data-duration="2"></div>
+</div>
+</body></html>`;
+    const live = await openComposition(twoElementHtml, { history: false });
+
+    // Disk already reflects hf-b's deletion — a separate write that completed
+    // before this persist started, exactly like the delete's own REST call
+    // that `handleTimelineElementsDelete` awaits before the ripple begins.
+    const postDelete = await openComposition(twoElementHtml, { history: false });
+    postDelete.removeElement("hf-b");
+    let disk = postDelete.serialize();
+    postDelete.dispose();
+    expect(disk).not.toContain("hf-b");
+
+    const writeProjectFile = vi.fn(async (_path: string, content: string) => {
+      disk = content;
+    });
+    const deps = {
+      editHistory: { recordEdit: vi.fn().mockResolvedValue(undefined) },
+      writeProjectFile,
+      readProjectFile: vi.fn(async () => disk),
+      reloadPreview: vi.fn(),
+      publishSession: vi.fn().mockReturnValue("published"),
+    };
+
+    // The ripple: only survivors move, mirroring resolveShiftedElements — this
+    // never touches hf-b, which `live` (unlike disk) still believes exists.
+    const result = await persistSdkCandidateMutation(
+      live,
+      "/comp.html",
+      twoElementHtml,
+      deps,
+      (candidate) => candidate.setTiming("hf-a", { start: 3 }),
+    );
+
+    expect(result.status).toBe("committed");
+    expect(disk).not.toContain("hf-b");
+    const written = await openComposition(disk, { history: false });
+    expect(written.getElement("hf-a")?.start).toBe(3);
+    expect(written.getElement("hf-b")).toBeNull();
+    written.dispose();
+    live.dispose();
+  });
+
   it("fails instead of cloning stale bytes when the authoritative queued read rejects", async () => {
     const live = await openComposition(html, { history: false });
     let disk = html;