@hyperframes/studio 0.8.46 → 0.8.48

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/hooks/useTimelinePlayer.ts

@@ -45,6 +45,7 @@ import { shouldResumeForwardPlaybackAfterSeek, shouldStopAfterSeek } from "../li
 import { applyPreviewVariablesToUrl } from "../../hooks/previewVariablesStore";
 import { createPreviewMessageHandler } from "./previewMessageRouter";
 import { timelineElementsChanged } from "./timelinePlayerSync";
+import { safeContentDocument } from "./timelineSyncHydration";
 
 export function useTimelinePlayer() {
   const iframeRef = useRef<HTMLIFrameElement | null>(null);
@@ -60,7 +61,7 @@ export function useTimelinePlayer() {
   const staticSeekAdapterRef = useRef<StaticSeekCacheEntry | null>(null);
   const staticSeekWarnedRef = useRef(false);
 
-  const { setIsPlaying, setCurrentTime, setDuration, setTimelineReady, setElements } =
+  const { setIsPlaying, setCurrentTime, setDuration, requestTimelineReady, setElements } =
     usePlayerStore.getState();
 
   // The fixture lease belongs at this shared synchronization boundary so every
@@ -101,7 +102,11 @@ export function useTimelinePlayer() {
         setDuration(nextDuration ?? 0);
       }
       if (!state.timelineReady) {
-        setTimelineReady(true);
+        // Same gate as initializeAdapter's own readiness wait: this is the
+        // message-based fallback for compositions that report their duration
+        // via clip manifest rather than the direct adapter, and it must not
+        // enable Play any earlier than that path does.
+        requestTimelineReady(safeContentDocument(iframeRef.current));
       }
 
       // Asynchronously enrich media elements still missing sourceDuration
@@ -120,7 +125,7 @@ export function useTimelinePlayer() {
         },
       );
     },
-    [setElements, setTimelineReady, setDuration],
+    [setElements, requestTimelineReady, setDuration],
   );
 
   // Pre-existing dispatcher complexity — surfaced by this PR's line shifts, not new logic.
@@ -425,7 +430,7 @@ export function useTimelinePlayer() {
       syncTimelineElements,
       setDuration,
       setCurrentTime,
-      setTimelineReady,
+      requestTimelineReady,
       setIsPlaying,
       attachIframeShortcutListeners,
       applyPreviewAudioState,

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -42,7 +42,7 @@ interface UseTimelineSyncCallbacksParams {
   syncTimelineElements: (elements: TimelineElement[], nextDuration?: number) => void;
   setDuration: (v: number) => void;
   setCurrentTime: (v: number) => void;
-  setTimelineReady: (v: boolean) => void;
+  requestTimelineReady: (doc: Document | null) => void;
   setIsPlaying: (v: boolean) => void;
   attachIframeShortcutListeners: () => void;
   applyPreviewAudioState: () => void;
@@ -106,7 +106,7 @@ export function useTimelineSyncCallbacks({
   syncTimelineElements,
   setDuration,
   setCurrentTime,
-  setTimelineReady,
+  requestTimelineReady,
   setIsPlaying,
   attachIframeShortcutListeners,
   applyPreviewAudioState,
@@ -204,7 +204,10 @@ export function useTimelineSyncCallbacks({
     syncAdapterDuration(adapter, setDuration);
     setCurrentTime(startTime);
     if (!isRefreshingRef.current) {
-      setTimelineReady(true);
+      // Enables Play from actual play-readiness, not just a known duration —
+      // a click before this resolves used to start the timeline with media,
+      // images or fonts still loading and never recover.
+      requestTimelineReady(safeContentDocument(iframeRef.current));
     }
     isRefreshingRef.current = false;
     setIsPlaying(false);
@@ -223,7 +226,7 @@ export function useTimelineSyncCallbacks({
     getAdapter,
     setDuration,
     setCurrentTime,
-    setTimelineReady,
+    requestTimelineReady,
     setIsPlaying,
     processTimelineMessage,
     enrichMissingCompositions,

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.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment happy-dom
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { usePlayerStore, liveTime, type TimelineElement } from "./playerStore";
 
@@ -322,6 +323,47 @@ describe("usePlayerStore", () => {
     });
   });
 
+  describe("requestTimelineReady", () => {
+    function stalledVideoDoc(): { doc: Document; video: HTMLVideoElement } {
+      const doc = document.implementation.createHTMLDocument("composition");
+      const video = doc.createElement("video");
+      Object.defineProperty(video, "readyState", { value: 0, configurable: true });
+      doc.body.appendChild(video);
+      return { doc, video };
+    }
+
+    it("resolves timelineReady once the doc's media settles", async () => {
+      const { doc, video } = stalledVideoDoc();
+      usePlayerStore.getState().requestTimelineReady(doc);
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+      video.dispatchEvent(new Event("canplay"));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(usePlayerStore.getState().timelineReady).toBe(true);
+    });
+
+    it("a stale wait from a project switched away from never marks the new project ready", async () => {
+      // beginTimelineSession no-ops when projectId is unchanged, so pin a
+      // known starting project first rather than relying on reset()'s
+      // leftover timelineProjectId from whatever test ran before this one.
+      usePlayerStore.getState().beginTimelineSession("readiness-test-project-a");
+      const { doc: docA, video: videoA } = stalledVideoDoc();
+      usePlayerStore.getState().requestTimelineReady(docA);
+
+      // Switches projects mid-wait — beginTimelineSession resets timelineReady
+      // to false for project B, whose own media has not been checked at all.
+      usePlayerStore.getState().beginTimelineSession("readiness-test-project-b");
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+      // A's wait settles late; it must not resolve into B's readiness.
+      videoA.dispatchEvent(new Event("canplay"));
+      await new Promise((resolve) => setTimeout(resolve, 0));
+
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+    });
+  });
+
   describe("setElements", () => {
     it("sets the elements array", () => {
       const elements: TimelineElement[] = [

package/src/player/store/playerStore.ts

@@ -19,6 +19,7 @@ import {
 import { createEditingModeSlice, type EditingModeSlice } from "./editingModeSlice";
 import { createTimelineFocusRequest, type TimelineFocusRequest } from "./timelineFocusState";
 import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
+import { createPlaybackReadinessSlice, resetPlaybackReadinessState } from "./readinessSlice";
 
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
@@ -54,12 +55,15 @@ function resolveElementSelection(
   };
 }
 
-interface PlayerState
-  extends KeyframeSlice, AutomationSelectionSlice, ThumbnailSlice, EditingModeSlice {
+type PlayerStoreSlices = KeyframeSlice &
+  AutomationSelectionSlice &
+  ThumbnailSlice &
+  EditingModeSlice &
+  ReturnType<typeof createPlaybackReadinessSlice>;
+interface PlayerState extends PlayerStoreSlices {
   isPlaying: boolean;
   currentTime: number;
   duration: number;
-  timelineReady: boolean;
   /** Increments exactly once when the Studio switches to a different project. */
   timelineSessionEpoch: number;
   /** Project owning the current timeline session; null outside a project-scoped reset. */
@@ -104,14 +108,14 @@ interface PlayerState
   /** 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;
@@ -129,7 +133,6 @@ interface PlayerState
   setAudioMuted: (muted: boolean) => void;
   setAudioVolume: (volume: number) => void;
   setLoopEnabled: (enabled: boolean) => void;
-  setTimelineReady: (ready: boolean) => void;
   setBeatDragging: (dragging: boolean) => void;
   setElements: (elements: TimelineElement[]) => void;
   setSelectedElementId: (id: string | null, options?: SelectElementOptions) => void;
@@ -146,26 +149,16 @@ interface PlayerState
   /** 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;
@@ -260,7 +253,7 @@ export function createTimelineResetState() {
     isPlaying: false,
     currentTime: 0,
     duration: 0,
-    timelineReady: false,
+    ...resetPlaybackReadinessState(),
     beatDragging: false,
     elements: [],
     selectedElementId: null,
@@ -304,7 +297,6 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   isPlaying: false,
   currentTime: 0,
   duration: 0,
-  timelineReady: false,
   timelineSessionEpoch: 0,
   timelineProjectId: null,
   beatDragging: false,
@@ -333,6 +325,7 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 
   ...createAutomationSelectionSlice(set),
   ...createEditingModeSlice(set),
+  ...createPlaybackReadinessSlice(set),
 
   activeKeyframePct: null,
   setActiveKeyframePct: (pct) => set({ activeKeyframePct: pct }),
@@ -472,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 });
@@ -521,7 +519,6 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   bumpZEditVersion: () => set((state) => ({ zEditVersion: state.zEditVersion + 1 })),
   setCurrentTime: (time) => set({ currentTime: Number.isFinite(time) ? time : 0 }),
   setDuration: (duration) => set({ duration: Number.isFinite(duration) ? duration : 0 }),
-  setTimelineReady: (ready) => set({ timelineReady: ready }),
   setBeatDragging: (dragging) => set({ beatDragging: dragging }),
   setElements: (elements) => set({ elements }),
   // A genuine single selection: always collapse the set to just this element. User

package/src/player/store/readinessSlice.ts

@@ -0,0 +1,42 @@
+/** 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. */
+import type { StoreApi } from "zustand";
+import { settleCompositionReadiness } from "@hyperframes/core/composition-readiness";
+
+export interface PlaybackReadinessSlice {
+  timelineReady: boolean;
+  setTimelineReady: (ready: 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. */
+  requestTimelineReady: (doc: Document | null) => void;
+}
+
+let timelineReadyGeneration = 0;
+
+/** For a full timeline reset: bumps the generation so any requestTimelineReady
+ * wait in flight can never resolve into what replaced it. */
+export function resetPlaybackReadinessState(): Pick<PlaybackReadinessSlice, "timelineReady"> {
+  timelineReadyGeneration++;
+  return { timelineReady: false };
+}
+
+export function createPlaybackReadinessSlice(
+  set: StoreApi<PlaybackReadinessSlice>["setState"],
+): PlaybackReadinessSlice {
+  return {
+    timelineReady: false,
+    setTimelineReady: (ready) => {
+      timelineReadyGeneration++;
+      set({ timelineReady: ready });
+    },
+    requestTimelineReady: (doc) => {
+      const generation = ++timelineReadyGeneration;
+      if (!doc) return set({ timelineReady: true });
+      settleCompositionReadiness(doc, () => {
+        if (generation === timelineReadyGeneration) set({ timelineReady: true });
+      });
+    },
+  };
+}

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/sdkCutover.gate.test.ts

@@ -1,11 +1,12 @@
 import { describe, expect, it, vi } from "vitest";
 
-// Dark-launch contract: with STUDIO_SDK_CUTOVER_ENABLED=false, EVERY cutover
+// Kill-switch contract: with VITE_STUDIO_SDK_CUTOVER_ENABLED=false, EVERY cutover
 // persist chokepoint must explicitly decline so the caller takes the legacy server
 // path — even when a valid SDK session exists (one always does, for
-// shadow/selection). This is the contract the prod flag-flip rests on; a future
-// refactor of the gate guards that silently re-enables cutover on flag-off
-// turns these red. (sdkCutover.test.ts mocks the flag TRUE; this is its sibling.)
+// shadow/selection). Default is ON (manualEditingAvailability.test.ts pins that);
+// this file pins that the env override still turns it fully off. A future
+// refactor of the gate guards that ignores the flag turns these red.
+// (sdkCutover.test.ts mocks the flag TRUE; this is its sibling.)
 vi.mock("../components/editor/manualEditingAvailability", () => ({
   STUDIO_SDK_CUTOVER_ENABLED: false,
   STUDIO_SDK_RESOLVER_SHADOW_ENABLED: false,

package/src/utils/sdkCutover.test.ts

@@ -23,6 +23,8 @@ vi.mock("./studioTelemetry", () => ({
   trackStudioEvent: vi.fn(),
 }));
 
+import { trackStudioEvent } from "./studioTelemetry";
+
 const styleOp = (property: string, value: string): PatchOperation => ({
   type: "inline-style",
   property,
@@ -202,6 +204,46 @@ describe("sdkCutoverPersist", () => {
     expect(result.status).toBe("declined");
   });
 
+  it("tags target_not_found with resolverDisagreement when dispatch could have resolved it", async () => {
+    // getElement is canonical-only for a bare id; resolveSnapshot mirrors what
+    // dispatch resolves (bare ids anywhere). An element present under a scoped
+    // id is dispatchable, so getElement refusing it is a resolver disagreement
+    // — and one the shadow event stays silent about.
+    const deps = makeDeps();
+    const session = makeSession(false);
+    (session as unknown as { getElements: () => unknown[] }).getElements = () => [
+      { id: "hf-abc", scopedId: "host/hf-abc" },
+    ];
+    const sel = { hfId: "hf-abc" } as never;
+
+    await sdkCutoverPersist(sel, [styleOp("color", "red")], "before", "/path.html", session, deps);
+
+    expect(trackStudioEvent).toHaveBeenCalledWith(
+      "sdk_cutover_declined",
+      expect.objectContaining({ reason: "target_not_found", resolverDisagreement: true }),
+    );
+  });
+
+  it("does not tag resolverDisagreement when the element is genuinely absent", async () => {
+    const deps = makeDeps();
+    const session = makeSession(false);
+    (session as unknown as { getElements: () => unknown[] }).getElements = () => [
+      { id: "hf-other", scopedId: "hf-other" },
+    ];
+    const sel = { hfId: "hf-abc" } as never;
+    vi.mocked(trackStudioEvent).mockClear();
+
+    await sdkCutoverPersist(sel, [styleOp("color", "red")], "before", "/path.html", session, deps);
+
+    expect(trackStudioEvent).toHaveBeenLastCalledWith(
+      "sdk_cutover_declined",
+      expect.objectContaining({ reason: "target_not_found" }),
+    );
+    expect(vi.mocked(trackStudioEvent).mock.lastCall?.[1]).not.toHaveProperty(
+      "resolverDisagreement",
+    );
+  });
+
   it("dispatches setStyle for inline-style ops", async () => {
     const deps = makeDeps();
     const session = makeSession(true);
@@ -607,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;