@hyperframes/studio 0.8.51 → 0.8.53-desktop.0

package/src/hooks/useRightPanelIntents.ts

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useRef } from "react";
+import { useDockLayoutStore, visiblePanelInZone } from "../components/dock/dockLayoutStore";
+
+/** Opens the Slideshow panel when the file becomes a slideshow and closes it when it stops being one; a user's own close, and a restored layout's placement, stick. */
+export function useSlideshowDockPanel(isSlideshowComposition: boolean) {
+  const controller = useDockLayoutStore((state) => state.controller);
+  const wasSlideshow = useRef(false);
+  useEffect(() => {
+    if (!controller) return;
+    const inDock = useDockLayoutStore.getState().openPanels.has("slideshow");
+    if (isSlideshowComposition && !inDock) controller.open("slideshow");
+    if (!isSlideshowComposition && wasSlideshow.current && inDock) controller.close("slideshow");
+    wasSlideshow.current = isSlideshowComposition;
+  }, [isSlideshowComposition, controller]);
+}
+
+/** Block params replace the Design body until Design stops showing; picking another tab dismisses them elsewhere. */
+export function useBlockParamsDismissal({
+  hasBlockParams,
+  onDismiss,
+}: {
+  hasBlockParams: boolean;
+  onDismiss: () => void;
+}) {
+  const designVisible = useDockLayoutStore((state) => state.visiblePanels.has("design"));
+  useEffect(() => {
+    if (hasBlockParams && !designVisible) onDismiss();
+  }, [hasBlockParams, designVisible, onDismiss]);
+}
+
+/** Wraps a tab setter so any tab other than block-params first dismisses the block-params view. */
+export function useDismissingTabSetter<Tab extends string>(
+  setTab: (tab: Tab) => void,
+  dismissBlockParams: () => void,
+) {
+  return useCallback(
+    (tab: Tab) => {
+      if (tab !== "block-params") dismissBlockParams();
+      setTab(tab);
+    },
+    [setTab, dismissBlockParams],
+  );
+}
+
+/** Caption edit mode owns the Design panel: whenever the right column shows something else, bring Design back. */
+export function useCaptionDesignFocus(captionEditMode: boolean) {
+  const designVisible = useDockLayoutStore((state) => state.visiblePanels.has("design"));
+  const rightShown = useDockLayoutStore(
+    (state) => visiblePanelInZone("right", state.lastActive, state.visiblePanels) !== null,
+  );
+  useEffect(() => {
+    if (captionEditMode && rightShown && !designVisible) {
+      useDockLayoutStore.getState().activatePanel("design");
+    }
+  }, [captionEditMode, rightShown, designVisible]);
+}
+
+/** The right-column panel the user last focused, whether or not the column is currently showing. */
+export function useRightPanelIntent() {
+  return useDockLayoutStore((state) =>
+    visiblePanelInZone("right", state.lastActive, state.openPanels),
+  );
+}

package/src/hooks/useServerConnection.hashProject.test.tsx

@@ -0,0 +1,94 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useServerConnection } from "./useServerConnection";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const captured: { projectId: string | null } = { projectId: null };
+
+function Probe() {
+  captured.projectId = useServerConnection().projectId;
+  return null;
+}
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+/**
+ * The hash project id outlives the project it names — a renamed folder, or a
+ * bookmark from a project that is gone. It used to be trusted unconditionally,
+ * so every later /api/projects/<id>/... request 404'd for the life of the tab,
+ * including the composition read that opens the SDK session. Telemetry after
+ * the read-reason split: 120 http_error/404 reads across 5 users in 24h.
+ */
+function stubFetch(projectRoute: { status: number } | "reject") {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      if (url === "/api/projects") {
+        return { ok: true, json: async () => ({ projects: [{ id: "real-project" }] }) } as Response;
+      }
+      if (projectRoute === "reject") throw new TypeError("Failed to fetch");
+      return { ok: projectRoute.status === 200, status: projectRoute.status } as Response;
+    }),
+  );
+}
+
+async function renderWithHash(hash: string) {
+  window.location.hash = hash;
+  const root = createRoot(document.createElement("div"));
+  await act(async () => root.render(<Probe />));
+  await flush();
+  return root;
+}
+
+describe("useServerConnection hash project id", () => {
+  beforeEach(() => {
+    captured.projectId = null;
+    window.location.hash = "";
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps a hash id the server can resolve", async () => {
+    stubFetch({ status: 200 });
+    const root = await renderWithHash("#project/stale-or-not");
+
+    expect(captured.projectId).toBe("stale-or-not");
+    await act(async () => root.unmount());
+  });
+
+  it("falls back to the first project when the hash id is gone", async () => {
+    stubFetch({ status: 404 });
+    const root = await renderWithHash("#project/deleted-project");
+
+    expect(captured.projectId).toBe("real-project");
+    expect(window.location.hash).toContain("real-project");
+    await act(async () => root.unmount());
+  });
+
+  // The important one: a blip must not rewrite the user's hash out from under a
+  // project that is actually fine. Only a definite 404 is "missing".
+  it("keeps the hash id when the check itself fails", async () => {
+    stubFetch("reject");
+    const root = await renderWithHash("#project/unreachable-check");
+
+    expect(captured.projectId).toBe("unreachable-check");
+    await act(async () => root.unmount());
+  });
+
+  it("keeps the hash id on a non-404 error status", async () => {
+    stubFetch({ status: 500 });
+    const root = await renderWithHash("#project/server-erroring");
+
+    expect(captured.projectId).toBe("server-erroring");
+    await act(async () => root.unmount());
+  });
+});

package/src/hooks/useServerConnection.ts

@@ -18,6 +18,26 @@ interface ServerConnectionState {
  * Polls every 2 s until the server responds, then transitions automatically.
  * Cleans up pending timers on unmount so it is safe under React StrictMode.
  */
+/**
+ * Whether a hash-supplied project id still names something the server can
+ * resolve. Three answers, not two: a failed request must NOT be read as
+ * "missing", or one network blip would discard a perfectly good deep link.
+ *
+ * Resolved through `/api/projects/:id`, which calls the same
+ * `adapter.resolveProject` the file routes use. A match against the
+ * `/api/projects` list would be wrong twice over: that list omits session ids
+ * (which resolve fine) and skips project dirs without an `index.html`.
+ */
+async function resolveHashProject(id: string): Promise<"ok" | "missing" | "unknown"> {
+  try {
+    const res = await fetch(`/api/projects/${encodeURIComponent(id)}`);
+    if (res.ok) return "ok";
+    return res.status === 404 ? "missing" : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 export function useServerConnection(): ServerConnectionState {
   const [projectId, setProjectId] = useState<string | null>(null);
   const [resolving, setResolving] = useState(true);
@@ -39,21 +59,34 @@ export function useServerConnection(): ServerConnectionState {
     function tryConnect() {
       fetch("/api/projects")
         .then((r) => r.json())
-        .then((data) => {
+        .then(async (data) => {
           if (cancelled) return;
+          // A hash project id outlives the project it names — a renamed folder,
+          // or a bookmark from a project that is gone. Trusting it blindly made
+          // every later /api/projects/<id>/... request 404 for the life of the
+          // tab, including the composition read that opens the SDK session, so
+          // every edit fell back to the server path with nothing to show why.
+          // Telemetry after the read-reason split: 120 http_error/404 reads
+          // across 5 users in 24h, ~24 each, never recovering.
           if (hashProjectId) {
-            setProjectId(hashProjectId);
-            setWaitingForServer(false);
-          } else {
-            const first = (data.projects ?? [])[0];
-            if (first) {
-              setProjectId(first.id);
+            const state = await resolveHashProject(hashProjectId);
+            if (cancelled) return;
+            // "unknown" keeps the old behaviour: a transient failure must not
+            // rewrite the user's hash out from under a valid project.
+            if (state !== "missing") {
+              setProjectId(hashProjectId);
               setWaitingForServer(false);
-              window.location.hash = buildProjectHash(first.id);
-            } else {
-              scheduleRetry();
+              return;
             }
           }
+          const first = (data.projects ?? [])[0];
+          if (first) {
+            setProjectId(first.id);
+            setWaitingForServer(false);
+            window.location.hash = buildProjectHash(first.id);
+          } else {
+            scheduleRetry();
+          }
         })
         .catch(() => {
           if (!cancelled) scheduleRetry();

package/src/hooks/useSlideshowTabState.test.ts

@@ -4,7 +4,6 @@ import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it } from "vitest";
 import { useSlideshowTabState } from "./useSlideshowTabState";
-import type { RightPanelTab } from "../utils/studioHelpers";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -15,14 +14,10 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-function renderHook(params: {
-  editingFileContent: string | null | undefined;
-  rightPanelTab: RightPanelTab;
-}) {
+function renderHook(params: { editingFileContent: string | null | undefined }) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
-  const setRightPanelTabCalls: RightPanelTab[] = [];
   let current: ReturnType<typeof useSlideshowTabState> | null = null;
 
   function Harness() {
@@ -30,8 +25,7 @@ function renderHook(params: {
       editingFileContent: params.editingFileContent,
       previewIframeRef: { current: null },
       refreshKey: 0,
-      rightPanelTab: params.rightPanelTab,
-      setRightPanelTab: (tab) => setRightPanelTabCalls.push(tab),
+      slideshowVisible: false,
     });
     return null;
   }
@@ -45,52 +39,36 @@ function renderHook(params: {
       if (!current) throw new Error("useSlideshowTabState did not render");
       return current;
     },
-    setRightPanelTabCalls,
     unmount: () => act(() => root.unmount()),
   };
 }
 
+// Whether "slideshow" stays the active dock tab across a file switch is
+// StudioRightPanels' own effect now (it opens/closes the dock panel), not
+// this hook's job — this only derives the two values that effect reads.
 describe("useSlideshowTabState", () => {
   it("detects a slideshow composition via the JSON island", () => {
-    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML, rightPanelTab: "design" });
+    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML });
     expect(harness.getState().isSlideshowComposition).toBe(true);
     harness.unmount();
   });
 
   it("reports false for a plain (non-slideshow) composition", () => {
-    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "design" });
+    const harness = renderHook({ editingFileContent: PLAIN_HTML });
     expect(harness.getState().isSlideshowComposition).toBe(false);
     harness.unmount();
   });
 
   it("reports false when there is no editing file yet", () => {
-    const harness = renderHook({ editingFileContent: undefined, rightPanelTab: "design" });
+    const harness = renderHook({ editingFileContent: undefined });
     expect(harness.getState().isSlideshowComposition).toBe(false);
     harness.unmount();
   });
 
   it("still detects a malformed island — presence-only, not full manifest validation", () => {
     const malformed = `<html><body><script type="application/hyperframes-slideshow+json">{not valid json</script></body></html>`;
-    const harness = renderHook({ editingFileContent: malformed, rightPanelTab: "design" });
+    const harness = renderHook({ editingFileContent: malformed });
     expect(harness.getState().isSlideshowComposition).toBe(true);
     harness.unmount();
   });
-
-  it("bounces rightPanelTab off 'slideshow' to 'renders' on a non-slideshow composition", () => {
-    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "slideshow" });
-    expect(harness.setRightPanelTabCalls).toEqual(["renders"]);
-    harness.unmount();
-  });
-
-  it("does not bounce when the composition is a slideshow", () => {
-    const harness = renderHook({ editingFileContent: SLIDESHOW_HTML, rightPanelTab: "slideshow" });
-    expect(harness.setRightPanelTabCalls).toEqual([]);
-    harness.unmount();
-  });
-
-  it("does not bounce a tab other than 'slideshow'", () => {
-    const harness = renderHook({ editingFileContent: PLAIN_HTML, rightPanelTab: "renders" });
-    expect(harness.setRightPanelTabCalls).toEqual([]);
-    harness.unmount();
-  });
 });

package/src/hooks/useSlideshowTabState.ts

@@ -1,29 +1,22 @@
-import { useEffect, useMemo, type MutableRefObject } from "react";
+import { useMemo, type MutableRefObject } from "react";
 import { SLIDESHOW_ISLAND_TYPE, slideshowIslandRegex } from "@hyperframes/core/slideshow";
 import type { SceneInfo } from "../components/panels/SlideshowPanel";
 import type { IframeWindow } from "../player/lib/playbackTypes";
-import type { RightPanelTab } from "../utils/studioHelpers";
 
 /**
  * Derives whether the currently-edited composition is a slideshow (carries
  * the slideshow JSON island — the same definitive marker the CLI's `present`
  * command requires; it refuses to run without one) and the live scene list
- * for the Slideshow panel, and bounces `rightPanelTab` off "slideshow" the
- * moment it stops applying (e.g. the user switches to a non-slideshow file
- * while that tab was open) so the panel never shows a dangling active tab
- * whose button is no longer even rendered.
- *
- * Extracted from StudioRightPanel to keep that file under the 600-LOC gate.
+ * for the Slideshow panel. Extracted from StudioRightPanels to keep that file
+ * under the 600-LOC gate.
  */
 export function useSlideshowTabState(params: {
   editingFileContent: string | null | undefined;
   previewIframeRef: MutableRefObject<HTMLIFrameElement | null>;
   refreshKey: number;
-  rightPanelTab: RightPanelTab;
-  setRightPanelTab: (tab: RightPanelTab) => void;
+  slideshowVisible: boolean;
 }): { isSlideshowComposition: boolean; slideshowScenes: SceneInfo[] } {
-  const { editingFileContent, previewIframeRef, refreshKey, rightPanelTab, setRightPanelTab } =
-    params;
+  const { editingFileContent, previewIframeRef, refreshKey, slideshowVisible } = params;
 
   // Presence-only (not full manifest validation): a malformed island should
   // still surface the Slideshow tab so the user can see/fix it, rather than
@@ -49,13 +42,7 @@ export function useSlideshowTabState(params: {
       return [];
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [previewIframeRef, rightPanelTab, refreshKey]);
-
-  useEffect(() => {
-    if (rightPanelTab === "slideshow" && !isSlideshowComposition) {
-      setRightPanelTab("renders");
-    }
-  }, [rightPanelTab, isSlideshowComposition, setRightPanelTab]);
+  }, [previewIframeRef, slideshowVisible, refreshKey]);
 
   return { isSlideshowComposition, slideshowScenes };
 }

package/src/hooks/useStudioContextValue.test.ts

@@ -4,14 +4,12 @@ import React from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import type { RightInspectorPanes } from "../utils/studioHelpers";
+import type { PanelId } from "../components/dock/panelRegistry";
 import { makeSelection } from "./domSelectionTestHarness";
 import { useInspectorState, type InspectorState } from "./useStudioContextValue";
 
 interface HarnessProps {
-  rightPanelTab: string;
-  rightInspectorPanes: RightInspectorPanes;
-  rightCollapsed: boolean;
+  rightPanel: PanelId | null;
   isPlaying: boolean;
   isGestureRecording: boolean;
   domEditSelection: DomEditSelection | null;
@@ -22,9 +20,7 @@ function renderInspectorState(props: HarnessProps): InspectorState {
 
   function Harness() {
     state = useInspectorState(
-      props.rightPanelTab,
-      props.rightInspectorPanes,
-      props.rightCollapsed,
+      props.rightPanel,
       props.isPlaying,
       props.domEditSelection,
       props.isGestureRecording,
@@ -42,9 +38,7 @@ function selectedProps(
 ): HarnessProps & { domEditSelection: DomEditSelection } {
   const element = document.createElement("div");
   return {
-    rightPanelTab: "renders",
-    rightInspectorPanes: { layers: false, design: false },
-    rightCollapsed: true,
+    rightPanel: "renders",
     isPlaying: false,
     isGestureRecording: false,
     domEditSelection: makeSelection("Selected", element),
@@ -78,16 +72,10 @@ describe("useInspectorState", () => {
   it("keeps selected DOM bounds coupled to the inspector or variables panel", () => {
     expect(renderInspectorState(selectedProps()).shouldShowSelectedDomBounds).toBe(false);
     expect(
-      renderInspectorState(
-        selectedProps({
-          rightPanelTab: "design",
-          rightInspectorPanes: { layers: false, design: true },
-        }),
-      ).shouldShowSelectedDomBounds,
+      renderInspectorState(selectedProps({ rightPanel: "design" })).shouldShowSelectedDomBounds,
     ).toBe(true);
     expect(
-      renderInspectorState(selectedProps({ rightPanelTab: "variables" }))
-        .shouldShowSelectedDomBounds,
+      renderInspectorState(selectedProps({ rightPanel: "variables" })).shouldShowSelectedDomBounds,
     ).toBe(true);
   });
 });

package/src/hooks/useStudioContextValue.ts

@@ -1,7 +1,7 @@
 import { useCallback, useMemo, type DragEvent } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import type { StudioContextValue } from "../contexts/StudioContext";
-import type { RightInspectorPanes } from "../utils/studioHelpers";
+import type { PanelId } from "../components/dock/panelRegistry";
 import type { TimelineFileDropHandler } from "./useTimelineEditingTypes";
 import { usePlayerStore } from "../player";
 
@@ -66,33 +66,21 @@ export function buildStudioContextValue(input: StudioContextInput): StudioContex
 }
 
 export interface InspectorState {
-  layersPanelActive: boolean;
-  designPanelActive: boolean;
   inspectorPanelActive: boolean;
-  inspectorButtonActive: boolean;
   shouldShowMotionPath: boolean;
   shouldShowSelectedDomBounds: boolean;
 }
 
 export function useInspectorState(
-  rightPanelTab: string,
-  rightInspectorPanes: RightInspectorPanes,
-  rightCollapsed: boolean,
+  rightPanel: PanelId | null,
   isPlaying: boolean,
   domEditSelection: DomEditSelection | null,
   isGestureRecording?: boolean,
 ): InspectorState {
-  // fallow-ignore-next-line complexity
   return useMemo(() => {
-    const inspectorTabActive = rightPanelTab === "design" || rightPanelTab === "layers";
-    const layersPanelActive = inspectorTabActive && rightInspectorPanes.layers;
-    const designPanelActive = inspectorTabActive && rightInspectorPanes.design;
-    const inspectorPanelActive = layersPanelActive || designPanelActive;
+    const inspectorPanelActive = rightPanel === "layers" || rightPanel === "design";
     return {
-      layersPanelActive,
-      designPanelActive,
       inspectorPanelActive,
-      inspectorButtonActive: !rightCollapsed && inspectorPanelActive,
       // Deliberately wider than shouldShowSelectedDomBounds: the on-canvas path
       // handles ARE the arc-drag affordance, so gating them on an open Inspector
       // would make keyframe path editing reachable only from a side panel.
@@ -102,18 +90,9 @@ export function useInspectorState(
       // The Variables tab also works against the canvas selection (bind card),
       // so the selection outline stays visible there too.
       shouldShowSelectedDomBounds:
-        (inspectorPanelActive || rightPanelTab === "variables") &&
-        !isPlaying &&
-        !isGestureRecording,
+        (inspectorPanelActive || rightPanel === "variables") && !isPlaying && !isGestureRecording,
     };
-  }, [
-    rightPanelTab,
-    rightInspectorPanes,
-    rightCollapsed,
-    isPlaying,
-    isGestureRecording,
-    domEditSelection,
-  ]);
+  }, [rightPanel, isPlaying, isGestureRecording, domEditSelection]);
 }
 
 /** Lets an OS file drop reach `onDrop` anywhere in the shell; the timeline shows its own landing preview. */

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -5,6 +5,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../player";
 import { applyRippleShifts, useTimelineDeleteOps } from "./useTimelineDeleteOps";
 import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
+import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
 
 installReactActEnvironment();
 
@@ -117,3 +119,112 @@ describe("useTimelineDeleteOps: ripple undo label", () => {
     );
   });
 });
+
+// Regression: a delete's write can reach disk before its history entry is
+// recorded, so an Undo fired in that window found nothing to restore.
+// Fails without useTrackPendingTimelineEdit's wrap (see that file).
+describe("useTimelineDeleteOps: undo race", () => {
+  // data-composition-id (readRootCompositionDuration's key) plus a
+  // remove-element mock that actually drops hf-c: needed for a real diff.
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-composition-id="main" data-duration="6">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+<div data-hf-id="hf-c" data-start="4" data-duration="2"></div>
+</div>
+</body></html>`;
+  const htmlAfterDeletingC = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-composition-id="main" data-duration="6">
+<div data-hf-id="hf-a" data-start="0" data-duration="2"></div>
+<div data-hf-id="hf-b" data-start="2" data-duration="2"></div>
+</div>
+</body></html>`;
+
+  beforeEach(() => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.includes("/file-mutations/remove-element/")) {
+          return new Response(JSON.stringify({ changed: true, content: htmlAfterDeletingC }), {
+            status: 200,
+          });
+        }
+        return new Response(JSON.stringify({ content: html }), { status: 200 });
+      }),
+    );
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+  });
+
+  // A manually-resolved gate stands in for the delete's write landing — a
+  // real timer raced the fix's own microtasks unpredictably (verified: it
+  // kept passing even with the fix's tracking call deleted).
+  function deferred<T>() {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>((r) => (resolve = r));
+    return { promise, resolve };
+  }
+
+  function mountRaceHarness() {
+    const elements = [el("hf-a", 0, 2), el("hf-b", 2, 2), el("hf-c", 4, 2)];
+    const gate = deferred<void>();
+    const recordEdit = vi.fn(() => gate.promise);
+    let tracked: ((elements: TimelineElement[]) => Promise<void>) | null = null;
+    function Harness() {
+      const track = useTrackPendingTimelineEdit();
+      const hook = useTimelineDeleteOps({
+        projectIdRef: { current: "test-project" },
+        activeCompPath: "index.html",
+        timelineElements: elements,
+        showToast: vi.fn(),
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        recordEdit,
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: null },
+        handleTimelineGroupMove: vi.fn().mockResolvedValue(undefined),
+      });
+      tracked = track(hook.handleTimelineElementsDelete);
+      return null;
+    }
+    mountReactHarness(<Harness />);
+    // Deletes the LAST clip (not the middle one): only this shrinks the
+    // composition's furthest-clip-end duration, so the write actually
+    // differs from the original content and recordEdit is reached — the
+    // middle clip's delete leaves duration unchanged and is a no-op write.
+    return { gate, recordEdit, deleteSelection: () => tracked!([elements[2]]) };
+  }
+
+  it("the pending-edit flush waits while the delete's history write is still landing", async () => {
+    const { gate, recordEdit, deleteSelection } = mountRaceHarness();
+    const order: string[] = [];
+    const deletePromise = deleteSelection().then(() => order.push("deleted"));
+    // Let the delete run up to (and call) recordEdit, which is now gated —
+    // this is the exact window a fast Undo used to race into.
+    await vi.waitFor(() => expect(recordEdit).toHaveBeenCalled());
+    // No React state changes happen inside the flush itself here (no
+    // pending-edit-flush listeners are registered in this harness), so it
+    // does not need act()'s wrapping — only awaiting the delete's own
+    // resolution below does.
+    const flushPromise = flushStudioPendingEdits().then(() => order.push("flushed"));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(order).toEqual([]);
+    gate.resolve();
+    await deletePromise;
+    await flushPromise;
+    expect(order).toEqual(["deleted", "flushed"]);
+  });
+
+  it("the pending-edit flush resolves immediately once the delete has already finished", async () => {
+    const { gate, deleteSelection } = mountRaceHarness();
+    gate.resolve();
+    await deleteSelection();
+    await act(async () => {
+      await flushStudioPendingEdits();
+    });
+  });
+});