@hyperframes/studio 0.8.47 → 0.8.49

package/src/hooks/useTimelineDeleteOps.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { TimelineElement } from "../player";
+import { applyRippleShifts, useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+
+installReactActEnvironment();
+
+function el(id: string, start: number, duration: number, track = 0): TimelineElement {
+  return { id, tag: "video", start, duration, track, domId: id };
+}
+
+describe("applyRippleShifts", () => {
+  it("returns survivors unchanged when there are no changes", () => {
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    expect(applyRippleShifts(survivors, null)).toBe(survivors);
+  });
+
+  it("rewrites only the starts named by the changes", () => {
+    const survivors = [el("a", 0, 2), el("c", 8, 1)];
+    const result = applyRippleShifts(survivors, [{ element: survivors[1], start: 2 }]);
+    expect(result).toEqual([el("a", 0, 2), el("c", 2, 1)]);
+    expect(result[0]).toBe(survivors[0]);
+  });
+});
+
+describe("useTimelineDeleteOps: ripple undo label", () => {
+  const html = `<!DOCTYPE html><html data-composition-variables='[]'><body>
+<div data-hf-id="hf-stage" data-hf-root 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>`;
+
+  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: html }), { status: 200 });
+        }
+        return new Response(JSON.stringify({ content: html }), { status: 200 });
+      }),
+    );
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+  });
+
+  type DeleteOpsOptions = Parameters<typeof useTimelineDeleteOps>[0];
+
+  function mountDeleteHarness(overrides: {
+    handleTimelineGroupMove: DeleteOpsOptions["handleTimelineGroupMove"];
+    showToast?: DeleteOpsOptions["showToast"];
+  }) {
+    const elements = [el("hf-a", 0, 2), el("hf-b", 2, 2), el("hf-c", 4, 2)];
+    let hook: ReturnType<typeof useTimelineDeleteOps> | null = null;
+    function Harness() {
+      hook = useTimelineDeleteOps({
+        projectIdRef: { current: "test-project" },
+        activeCompPath: "index.html",
+        timelineElements: elements,
+        showToast: overrides.showToast ?? vi.fn(),
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+        recordEdit: vi.fn().mockResolvedValue(undefined),
+        reloadPreview: vi.fn(),
+        previewIframeRef: { current: null },
+        handleTimelineGroupMove: overrides.handleTimelineGroupMove,
+      });
+      return null;
+    }
+    mountReactHarness(<Harness />);
+    return { b: elements[1], getHook: () => hook! };
+  }
+
+  // editHistory.ts's coalescing keeps the LAST recordEdit call's label, so the
+  // folded ripple move must carry the delete's label, not its own.
+  it("passes the delete's own label to the folded ripple move, not 'Move timeline clips'", async () => {
+    const handleTimelineGroupMove = vi.fn().mockResolvedValue(undefined);
+    const { b, getHook } = mountDeleteHarness({ handleTimelineGroupMove });
+
+    await act(async () => {
+      await getHook().handleTimelineElementDelete(b);
+    });
+
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ label: "Delete timeline clip" }),
+    );
+  });
+
+  it("shows exactly one toast when a ripple fails to persist after a committed delete", async () => {
+    const handleTimelineGroupMove = vi.fn().mockRejectedValue(new Error("persist failed"));
+    const showToast = vi.fn();
+    const { b, getHook } = mountDeleteHarness({ handleTimelineGroupMove, showToast });
+
+    await act(async () => {
+      await getHook().handleTimelineElementDelete(b);
+    });
+
+    // The user did one thing (delete); the generic move-failure toast is
+    // suppressed on this call so only the specific message reaches them.
+    expect(showToast).toHaveBeenCalledTimes(1);
+    expect(showToast).toHaveBeenCalledWith(
+      "Clip deleted, but the gap could not be closed.",
+      "error",
+    );
+    expect(handleTimelineGroupMove).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({ suppressFailureToast: true }),
+    );
+  });
+});

package/src/hooks/useTimelineDeleteOps.ts

@@ -2,7 +2,7 @@ import { buildProjectApiPath } from "../utils/projectRouting";
 // Timeline clip deletion: the marquee/multi path and the single-clip wrapper
 // the context menu uses. Extracted verbatim from useTimelineEditing.ts to keep
 // it under the studio 600-line cap, following useTimelineAssetDropOps.
-import { useCallback, type MutableRefObject, type RefObject } from "react";
+import { useCallback, useRef, type MutableRefObject, type RefObject } from "react";
 import type { TimelineElement } from "../player";
 import { usePlayerStore } from "../player";
 import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
@@ -12,6 +12,28 @@ import { buildPatchTarget } from "./timelineEditingHelpers";
 import { captureDurationRollback, readFileContent } from "./timelineTimingSync";
 import { setCompositionDurationToContent } from "../utils/timelineAssetDrop";
 import { furthestClipEndFromSource } from "../player/lib/timelineElementHelpers";
+import {
+  resolveMainTrackDeleteRippleShifts,
+  resolveShiftedElements,
+} from "../player/components/timelineGapCommit";
+import type {
+  TimelineGroupCommitOptions,
+  TimelineGroupMoveChange,
+} from "./useTimelineGroupEditing";
+
+/** Apply already-resolved ripple changes to the surviving elements for the
+ *  optimistic store update after a delete. Pure — no IO. */
+export function applyRippleShifts(
+  survivors: TimelineElement[],
+  changes: readonly TimelineGroupMoveChange[] | null,
+): TimelineElement[] {
+  if (!changes) return survivors;
+  const newStartByElement = new Map(changes.map((c) => [c.element, c.start]));
+  return survivors.map((te) => {
+    const newStart = newStartByElement.get(te);
+    return newStart != null ? { ...te, start: newStart } : te;
+  });
+}
 
 interface UseTimelineDeleteOpsOptions {
   projectIdRef: MutableRefObject<string | null>;
@@ -24,8 +46,20 @@ interface UseTimelineDeleteOpsOptions {
   isRecordingRef?: MutableRefObject<boolean>;
   forceReloadSdkSession?: () => void;
   previewIframeRef: RefObject<HTMLIFrameElement | null>;
+  /** The same atomic multi-clip move commit the track-gap menu uses, reused
+   *  to ripple the main track after a delete, folded into the delete's own
+   *  undo entry via a shared coalesceKey. */
+  handleTimelineGroupMove: (
+    changes: TimelineGroupMoveChange[],
+    options?: TimelineGroupCommitOptions,
+  ) => Promise<void>;
 }
 
+// Per-gesture-unique coalesce key — a monotonic counter, not Date.now() /
+// Math.random() (determinism rules), mirroring gapCloseGestureSeq in
+// timelineGapCommit.ts.
+let deleteGestureSeq = 0;
+
 export function useTimelineDeleteOps({
   projectIdRef,
   activeCompPath,
@@ -37,7 +71,12 @@ export function useTimelineDeleteOps({
   isRecordingRef,
   forceReloadSdkSession,
   previewIframeRef,
+  handleTimelineGroupMove,
 }: UseTimelineDeleteOpsOptions) {
+  // First-use-per-session notice for the ripple. Plain info toast: Studio's
+  // toast system has no action buttons, so Undo and the toggle location are
+  // named in words instead.
+  const rippleNoticeShownRef = useRef(false);
   // fallow-ignore-next-line complexity
   const handleTimelineElementsDelete = useCallback(
     // fallow-ignore-next-line complexity
@@ -109,11 +148,17 @@ export function useTimelineDeleteOps({
           usePlayerStore.getState().setDuration(deleteContentEnd);
         }
 
+        // Shared with the ripple move below so a folded ripple is one undo
+        // step with the delete, not two (editHistory.ts coalesces by key +
+        // window across separate recordEdit calls, not by label).
+        const coalesceKey = `main-track-ripple-delete:${deleteGestureSeq++}`;
+        const deleteHistoryLabel = "Delete timeline clip";
         try {
           await saveProjectFilesWithHistory({
             projectId: pid,
-            label: "Delete timeline clip",
+            label: deleteHistoryLabel,
             kind: "timeline",
+            coalesceKey,
             files: { [targetPath]: patchedContent },
             readFile: async () => originalContent,
             // remove-element already wrote the removal, so disk holds THAT — not the
@@ -128,17 +173,65 @@ export function useTimelineDeleteOps({
         }
 
         const deletedKeys = new Set(sameFile.map((te) => te.key ?? te.id));
-        usePlayerStore
-          .getState()
-          .setElements(timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id)));
+        const survivors = timelineElements.filter((te) => !deletedKeys.has(te.key ?? te.id));
+
+        // Ripple: close the gap the delete left on the main track. Pure decision
+        // first (resolveMainTrackDeleteRippleShifts — off, no main-track clip
+        // deleted, already gapless, or a locked survivor all resolve to null),
+        // then the one write, folded into the delete's undo entry above.
+        const rippleShifts = resolveMainTrackDeleteRippleShifts(
+          survivors,
+          sameFile,
+          usePlayerStore.getState().rippleEditEnabled,
+        );
+        let rippleApplied: TimelineGroupMoveChange[] | null = null;
+        let rippleFailed = false;
+        if (rippleShifts) {
+          const rippleChanges = resolveShiftedElements(survivors, rippleShifts);
+          try {
+            await handleTimelineGroupMove(rippleChanges, {
+              coalesceKey,
+              coalesceMs: Number.POSITIVE_INFINITY,
+              // Coalescing keeps the LAST entry's label; without this the undo
+              // toast reads "Undid Move timeline clips" after a delete, naming
+              // the ripple's mechanics instead of what the user actually did.
+              label: deleteHistoryLabel,
+              // This call gets its own, more specific failure toast below —
+              // the generic one would tell the user about one action twice.
+              suppressFailureToast: true,
+            });
+            rippleApplied = rippleChanges;
+          } catch (error) {
+            // The delete already committed; a failed ripple leaves the gap the
+            // toggle-off behaviour would have left anyway — not worth undoing
+            // an otherwise-successful delete over.
+            rippleFailed = true;
+            console.error("[Timeline] ripple-edit failed to persist after delete", error);
+            showToast("Clip deleted, but the gap could not be closed.", "error");
+          }
+        }
+
+        usePlayerStore.getState().setElements(applyRippleShifts(survivors, rippleApplied));
         usePlayerStore.getState().setSelectedElementId(null);
         usePlayerStore.getState().setSelectedElementIds(new Set());
         forceReloadSdkSession?.();
         reloadPreview();
-        showToast(
-          `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
-          "info",
-        );
+        // A failed ripple already showed its own toast above; the user did one
+        // thing (delete), so they get one message, not this generic follow-up too.
+        if (!rippleFailed) {
+          showToast(
+            `Deleted ${label}. Use Undo to restore ${sameFile.length === 1 ? "it" : "them"}.`,
+            "info",
+          );
+        }
+        if (rippleApplied && !rippleNoticeShownRef.current) {
+          rippleNoticeShownRef.current = true;
+          showToast(
+            "Ripple closed the gap on the main track. Undo (⌘Z) restores it, or turn off " +
+              "Ripple in the timeline toolbar.",
+            "info",
+          );
+        }
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to delete timeline clip";
         showToast(message);
@@ -155,6 +248,7 @@ export function useTimelineDeleteOps({
       isRecordingRef,
       forceReloadSdkSession,
       previewIframeRef,
+      handleTimelineGroupMove,
     ],
   );
 

package/src/hooks/useTimelineEditing.ts

@@ -413,6 +413,7 @@ export function useTimelineEditing({
     isRecordingRef,
     forceReloadSdkSession,
     previewIframeRef,
+    handleTimelineGroupMove: groupEditing.handleTimelineGroupMove,
   });
 
   const { handleTimelineAssetDrop, handleTimelineFileDrop, handleTimelineCompositionDrop } =

package/src/hooks/useTimelineGroupEditing.test.tsx

@@ -0,0 +1,74 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Root } from "react-dom/client";
+import type { TimelineElement } from "../player";
+import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
+import { installReactActEnvironment, mountReactHarness } from "./domSelectionTestHarness";
+
+installReactActEnvironment();
+
+function el(id: string, start: number, duration: number, track = 0): TimelineElement {
+  return { id, tag: "video", start, duration, track, domId: id };
+}
+
+describe("useTimelineGroupEditing: handleTimelineGroupMove suppressFailureToast", () => {
+  let root: Root | null = null;
+
+  afterEach(() => {
+    if (root) act(() => root!.unmount());
+    root = null;
+    document.body.innerHTML = "";
+  });
+
+  type GroupEditingOptions = Parameters<typeof useTimelineGroupEditing>[0];
+
+  // No project id makes enqueueGroupOperation reject before any persist runs,
+  // exercising the move's real catch block without faking the SDK/server path.
+  function mountFailingHarness(showToast: GroupEditingOptions["showToast"]) {
+    let hook: ReturnType<typeof useTimelineGroupEditing> | null = null;
+    function Harness() {
+      hook = useTimelineGroupEditing({
+        activeCompPath: "index.html",
+        editQueueRef: { current: Promise.resolve() },
+        pendingTimelineEditPathRef: { current: new Set() },
+        previewIframeRef: { current: null },
+        projectIdRef: { current: null },
+        recordEdit: vi.fn().mockResolvedValue(undefined),
+        reloadPreview: vi.fn(),
+        showToast,
+        writeProjectFile: vi.fn().mockResolvedValue(undefined),
+      });
+      return null;
+    }
+    root = mountReactHarness(<Harness />);
+    return () => hook!;
+  }
+
+  const change = { element: el("a", 0, 2), start: 2 };
+
+  it("shows no toast when suppressFailureToast is set on a failed move", async () => {
+    const showToast = vi.fn();
+    const getHook = mountFailingHarness(showToast);
+
+    await act(async () => {
+      await expect(
+        getHook().handleTimelineGroupMove([change], { suppressFailureToast: true }),
+      ).rejects.toThrow();
+    });
+
+    expect(showToast).not.toHaveBeenCalled();
+  });
+
+  it("shows one toast when suppressFailureToast is not set on a failed move", async () => {
+    const showToast = vi.fn();
+    const getHook = mountFailingHarness(showToast);
+
+    await act(async () => {
+      await expect(getHook().handleTimelineGroupMove([change])).rejects.toThrow();
+    });
+
+    expect(showToast).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useTimelineGroupEditing.ts

@@ -47,6 +47,15 @@ export interface TimelineGroupCommitOptions {
   coalesceKey?: string;
   /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
   coalesceMs?: number;
+  /** Overrides the default "Move timeline clips" undo-history label. Coalescing
+   *  keeps the LAST entry's label (editHistory.ts), so a mechanical follow-up
+   *  move folded into another gesture's coalesceKey (e.g. the ripple after a
+   *  delete) should carry that gesture's own label, not its own. */
+  label?: string;
+  /** Skips this call's own generic failure toast (the error is still logged
+   *  to the console) — for a caller that shows its own more specific message
+   *  on the same failure, so the user isn't told about one action twice. */
+  suppressFailureToast?: boolean;
 }
 
 interface UseTimelineGroupEditingOptions {
@@ -272,21 +281,22 @@ export function useTimelineGroupEditing({
       syncPreviewContentDuration(previewIframeRef.current);
       const coalesceKey = options?.coalesceKey ?? moveCoalesceKey(changes);
       const coalesceMs = options?.coalesceMs;
-      return enqueueGroupOperation("Move timeline clips", async (projectId) => {
+      const label = options?.label ?? "Move timeline clips";
+      return enqueueGroupOperation(label, async (projectId) => {
         await options?.beforeTiming;
         const handledBySdk = await trySdkBatchPersist({
           changes,
           sdkChanges: toSdkTimingChanges(changes, (change) => ({ start: change.start })),
           eligible: changes.every((change) => change.track == null),
           needsExtension,
-          label: "Move timeline clips",
+          label,
           coalesceKey,
           coalesceMs,
         });
         if (!handledBySdk) {
           await persistServerBatch(
             projectId,
-            "Move timeline clips",
+            label,
             changes.map((change) => ({
               element: change.element,
               buildPatches: (original, target) =>
@@ -315,7 +325,7 @@ export function useTimelineGroupEditing({
             projectId,
             iframe: previewIframeRef.current,
             reloadPreview,
-            label: "Move timeline clips",
+            label,
             errorLabel: "Failed to shift GSAP positions",
             coalesceKey,
             recordEdit,
@@ -336,7 +346,11 @@ export function useTimelineGroupEditing({
         // Failed persist: revert the optimistic duration readout + live root
         // alongside the gesture owner's store rollback.
         rollbackDuration();
-        showToast(getStudioSaveErrorMessage(error), "error");
+        if (options?.suppressFailureToast) {
+          console.error("[Timeline] group move failed to persist", error);
+        } else {
+          showToast(getStudioSaveErrorMessage(error), "error");
+        }
         throw error;
       });
     },

package/src/hooks/useTimelineSelectionPreviewSync.test.tsx

@@ -175,7 +175,70 @@ describe("useTimelineSelectionPreviewSync", () => {
     harness.cleanup();
   });
 
-  it("warns once while retrying a timeline selection after preview refreshes", async () => {
+  it("does not clear the selection when the selected clip is not in timelineElements yet", async () => {
+    // A freshly-dropped clip is selected before the reload that adds it to
+    // timelineElements has completed. Bailing quietly here (like the
+    // DOM-node-not-ready case above) lets the later effect run, once the
+    // element exists, apply the selection instead of wiping it.
+    const { timelineElements } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async () => null);
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: "clip-3",
+      selectedElementIds: new Set(["clip-3"]),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound,
+    });
+
+    // Still within the retry grace window: quiet, not yet a warning.
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
+    expect(applyDomSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("does not shrink a pasted or duplicated group's selection when only some members have appeared yet", async () => {
+    // Paste/duplicate of a group selects every new id up front; one member
+    // (clip-1) is already in timelineElements, the other (a fresh paste/dup
+    // target, "clip-3") is not yet. Applying only the resolved member would
+    // silently drop the rest of the group from the store.
+    const { firstSelection, timelineElements, selectionById } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) => {
+      return selectionById.get(element.id) ?? firstSelection;
+    });
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: "clip-1",
+      selectedElementIds: new Set(["clip-1", "clip-3"]),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound,
+    });
+
+    // Still within the retry grace window: quiet, not yet a warning.
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
+    expect(applyDomSelection).not.toHaveBeenCalled();
+    expect(applyMarqueeSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("stays quiet through retries and resolves once the preview refreshes", async () => {
     const { secondSelection, timelineElements } = makeSyncFixture();
     const applyDomSelection = vi.fn();
     const applyMarqueeSelection = vi.fn();
@@ -199,7 +262,7 @@ describe("useTimelineSelectionPreviewSync", () => {
       onSelectionNotFound,
     });
 
-    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
     expect(applyDomSelection).not.toHaveBeenCalled();
 
     await harness.rerender({
@@ -214,7 +277,7 @@ describe("useTimelineSelectionPreviewSync", () => {
       onSelectionNotFound,
     });
 
-    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
 
     previewReady = true;
     await harness.rerender({
@@ -230,6 +293,155 @@ describe("useTimelineSelectionPreviewSync", () => {
     });
 
     expect(applyDomSelection).toHaveBeenCalledWith(secondSelection);
+    expect(onSelectionNotFound).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("degrades to the resolvable subset once a group member never resolves", async () => {
+    // clip-2 is a permanent hold-out (deleted out of band, a stale id, or
+    // anything else that will never build a selection). Retrying forever
+    // would leave the whole group's selection stuck; after a few attempts,
+    // apply the members that did resolve instead.
+    const { firstSelection, timelineElements } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) =>
+      element.id === "clip-1" ? firstSelection : null,
+    );
+    const selectedElementIds = new Set(["clip-1", "clip-2"]);
+    const harness = renderHarness();
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      await harness.rerender({
+        selectedElementId: "clip-1",
+        selectedElementIds,
+        timelineElements: [...timelineElements],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+        buildDomSelectionForTimelineElement,
+        applyDomSelection,
+        applyMarqueeSelection,
+        onSelectionNotFound,
+      });
+    }
+
+    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+    expect(applyDomSelection).toHaveBeenCalledWith(firstSelection);
+    expect(applyMarqueeSelection).not.toHaveBeenCalled();
+    harness.cleanup();
+  });
+
+  it("gives a fresh retry budget after deselecting a permanently-unresolvable selection", async () => {
+    // Same permanent hold-out as the test above, but the user deselects and
+    // reselects the exact same group afterward. Without resetting the retry
+    // budget on deselect, reselecting the same key resumes an already-
+    // exhausted count and degrades on the very first attempt with no warning.
+    const { firstSelection, timelineElements } = makeSyncFixture();
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const onSelectionNotFound = vi.fn();
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) =>
+      element.id === "clip-1" ? firstSelection : null,
+    );
+    const selectedElementIds = new Set(["clip-1", "clip-2"]);
+    const harness = renderHarness();
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      await harness.rerender({
+        selectedElementId: "clip-1",
+        selectedElementIds,
+        timelineElements: [...timelineElements],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+        buildDomSelectionForTimelineElement,
+        applyDomSelection,
+        applyMarqueeSelection,
+        onSelectionNotFound,
+      });
+    }
+    expect(onSelectionNotFound).toHaveBeenCalledOnce();
+
+    await harness.rerender({
+      selectedElementId: null,
+      selectedElementIds: new Set(),
+      timelineElements: [...timelineElements],
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound,
+    });
+
+    for (let attempt = 0; attempt < 4; attempt++) {
+      await harness.rerender({
+        selectedElementId: "clip-1",
+        selectedElementIds,
+        timelineElements: [...timelineElements],
+        domEditSelection: null,
+        domEditGroupSelections: [],
+        buildDomSelectionForTimelineElement,
+        applyDomSelection,
+        applyMarqueeSelection,
+        onSelectionNotFound,
+      });
+    }
+
+    expect(onSelectionNotFound).toHaveBeenCalledTimes(2);
+    harness.cleanup();
+  });
+
+  it("resolves every member of a large selection concurrently, not one network round trip at a time", async () => {
+    const elementCount = 30;
+    const timelineElements: TimelineElement[] = Array.from({ length: elementCount }, (_, i) => ({
+      id: `clip-${i}`,
+      domId: `clip-${i}`,
+      tag: "div",
+      start: i,
+      duration: 1,
+      track: i % 4,
+    }));
+    const selectionById = new Map(
+      timelineElements.map((el) => {
+        const domEl = document.createElement("div");
+        domEl.id = el.id;
+        return [el.id, makeSelection(el.id, domEl)];
+      }),
+    );
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const buildDomSelectionForTimelineElement = vi.fn(async (element: TimelineElement) => {
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      // Stands in for the network round trip: yields once so every member's
+      // call has a chance to start before any of them finish.
+      await Promise.resolve();
+      inFlight -= 1;
+      return selectionById.get(element.id) ?? null;
+    });
+    const applyDomSelection = vi.fn();
+    const applyMarqueeSelection = vi.fn();
+    const harness = renderHarness();
+
+    await harness.rerender({
+      selectedElementId: timelineElements[0].id,
+      selectedElementIds: new Set(timelineElements.map((el) => el.id)),
+      timelineElements,
+      domEditSelection: null,
+      domEditGroupSelections: [],
+      buildDomSelectionForTimelineElement,
+      applyDomSelection,
+      applyMarqueeSelection,
+      onSelectionNotFound: vi.fn(),
+    });
+
+    expect(buildDomSelectionForTimelineElement).toHaveBeenCalledTimes(elementCount);
+    // A sequential loop never has more than one call in flight at once; this
+    // asserts every member's probe started before any of them resolved.
+    expect(maxInFlight).toBe(elementCount);
+    expect(applyMarqueeSelection).toHaveBeenCalledOnce();
+    expect(applyMarqueeSelection.mock.calls[0]?.[0]).toHaveLength(elementCount);
     harness.cleanup();
   });
 });