@hyperframes/studio 0.6.48 → 0.6.49

package/src/hooks/useDomEditTextCommits.ts

@@ -38,7 +38,7 @@ export interface UseDomEditTextCommitsParams {
   buildDomSelectionFromTarget: (
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
-  ) => DomEditSelection | null;
+  ) => Promise<DomEditSelection | null>;
   persistDomEditOperations: PersistDomEditOperations;
   resolveImportedFontAsset: (fontFamilyValue: string) => ImportedFontAsset | null;
 }
@@ -231,7 +231,7 @@ export function useDomEditTextCommits({
       if (doc) {
         const refreshed = findElementForSelection(doc, domEditSelection, activeCompPath);
         if (refreshed) {
-          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          const nextSelection = await buildDomSelectionFromTarget(refreshed);
           if (nextSelection) {
             applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
           }
@@ -287,7 +287,7 @@ export function useDomEditTextCommits({
       if (doc) {
         const refreshed = findElementForSelection(doc, selection, activeCompPath);
         if (refreshed) {
-          const nextSelection = buildDomSelectionFromTarget(refreshed);
+          const nextSelection = await buildDomSelectionFromTarget(refreshed);
           if (nextSelection) {
             applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
           }

package/src/hooks/useDomSelection.ts

@@ -60,17 +60,19 @@ export interface UseDomSelectionReturn {
   buildDomSelectionFromTarget: (
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
-  ) => DomEditSelection | null;
+  ) => Promise<DomEditSelection | null>;
   resolveDomSelectionFromPreviewPoint: (
     clientX: number,
     clientY: number,
     options?: { preferClipAncestor?: boolean },
-  ) => DomEditSelection | null;
+  ) => Promise<DomEditSelection | null>;
   updateDomEditHoverSelection: (selection: DomEditSelection | null) => void;
-  buildDomSelectionForTimelineElement: (element: TimelineElement) => DomEditSelection | null;
-  handleTimelineElementSelect: (element: TimelineElement | null) => void;
-  refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => void;
-  refreshDomEditGroupSelectionsFromPreview: (selections: DomEditSelection[]) => void;
+  buildDomSelectionForTimelineElement: (
+    element: TimelineElement,
+  ) => Promise<DomEditSelection | null>;
+  handleTimelineElementSelect: (element: TimelineElement | null) => Promise<void>;
+  refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
+  refreshDomEditGroupSelectionsFromPreview: (selections: DomEditSelection[]) => Promise<void>;
 }
 
 // ── Hook ──
@@ -193,24 +195,34 @@ export function useDomSelection({
   }, [applyDomSelection]);
 
   const buildDomSelectionFromTarget = useCallback(
-    (target: HTMLElement, options?: { preferClipAncestor?: boolean }) => {
+    (
+      target: HTMLElement,
+      options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
+    ) => {
       return resolveDomEditSelection(target, {
         activeCompositionPath: activeCompPath,
         isMasterView,
         preferClipAncestor: options?.preferClipAncestor,
+        skipSourceProbe: options?.skipSourceProbe,
+        projectId,
       });
     },
-    [activeCompPath, isMasterView],
+    [activeCompPath, isMasterView, projectId],
   );
 
   const resolveDomSelectionFromPreviewPoint = useCallback(
-    (clientX: number, clientY: number, options?: { preferClipAncestor?: boolean }) => {
+    async (
+      clientX: number,
+      clientY: number,
+      options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
+    ) => {
       const iframe = previewIframeRef.current;
       if (!iframe || captionEditMode) return null;
       const target = getPreviewTargetFromPointer(iframe, clientX, clientY, activeCompPath);
       if (!target) return null;
       return buildDomSelectionFromTarget(target, {
         preferClipAncestor: options?.preferClipAncestor,
+        skipSourceProbe: options?.skipSourceProbe,
       });
     },
     [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
@@ -223,7 +235,7 @@ export function useDomSelection({
   }, []);
 
   const buildDomSelectionForTimelineElement = useCallback(
-    (element: TimelineElement): DomEditSelection | null => {
+    async (element: TimelineElement): Promise<DomEditSelection | null> => {
       const iframe = previewIframeRef.current;
       let doc: Document | null = null;
       try {
@@ -248,21 +260,21 @@ export function useDomSelection({
   );
 
   const handleTimelineElementSelect = useCallback(
-    (element: TimelineElement | null) => {
+    async (element: TimelineElement | null) => {
       if (!STUDIO_INSPECTOR_PANELS_ENABLED) return;
       if (!element) {
         applyDomSelection(null, { revealPanel: false });
         return;
       }
 
-      const selection = buildDomSelectionForTimelineElement(element);
+      const selection = await buildDomSelectionForTimelineElement(element);
       if (selection) applyDomSelection(selection);
     },
     [applyDomSelection, buildDomSelectionForTimelineElement],
   );
 
   const refreshDomEditSelectionFromPreview = useCallback(
-    (selection: DomEditSelection) => {
+    async (selection: DomEditSelection) => {
       const iframe = previewIframeRef.current;
       let doc: Document | null = null;
       try {
@@ -275,7 +287,7 @@ export function useDomSelection({
       const element = findElementForSelection(doc, selection, activeCompPath);
       if (!element) return;
 
-      const nextSelection = buildDomSelectionFromTarget(element);
+      const nextSelection = await buildDomSelectionFromTarget(element);
       if (nextSelection) {
         applyDomSelection(nextSelection, {
           revealPanel: false,
@@ -287,7 +299,7 @@ export function useDomSelection({
   );
 
   const refreshDomEditGroupSelectionsFromPreview = useCallback(
-    (selections: DomEditSelection[]) => {
+    async (selections: DomEditSelection[]) => {
       const iframe = previewIframeRef.current;
       let doc: Document | null = null;
       try {
@@ -301,7 +313,7 @@ export function useDomSelection({
       for (const selection of selections) {
         const element = findElementForSelection(doc, selection, activeCompPath);
         if (!element) continue;
-        const nextSelection = buildDomSelectionFromTarget(element);
+        const nextSelection = await buildDomSelectionFromTarget(element);
         if (nextSelection) nextGroup.push(nextSelection);
       }
       if (nextGroup.length === 0) return;

package/src/hooks/usePreviewInteraction.ts

@@ -20,8 +20,8 @@ export interface UsePreviewInteractionParams {
   resolveDomSelectionFromPreviewPoint: (
     clientX: number,
     clientY: number,
-    options?: { preferClipAncestor?: boolean },
-  ) => DomEditSelection | null;
+    options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
+  ) => Promise<DomEditSelection | null>;
   updateDomEditHoverSelection: (selection: DomEditSelection | null) => void;
 
   onClickToSource?: (selection: DomEditSelection) => void;
@@ -40,9 +40,9 @@ export function usePreviewInteraction({
   onClickToSource,
 }: UsePreviewInteractionParams) {
   const handlePreviewCanvasMouseDown = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
+    async (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
       if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) return;
-      const nextSelection = resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+      const nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
         preferClipAncestor: options?.preferClipAncestor ?? false,
       });
       if (!nextSelection) {
@@ -66,14 +66,15 @@ export function usePreviewInteraction({
   );
 
   const handlePreviewCanvasPointerMove = useCallback(
-    (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
+    async (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
       if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) {
         updateDomEditHoverSelection(null);
         return null;
       }
 
-      const nextSelection = resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+      const nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
         preferClipAncestor: options?.preferClipAncestor ?? false,
+        skipSourceProbe: true,
       });
       updateDomEditHoverSelection(nextSelection);
       return nextSelection;

package/src/hooks/useStudioUrlState.ts

@@ -25,7 +25,7 @@ interface UseStudioUrlStateParams {
   buildDomSelectionFromTarget: (
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
-  ) => DomEditSelection | null;
+  ) => Promise<DomEditSelection | null>;
   applyDomSelection: (
     selection: DomEditSelection | null,
     options?: {
@@ -140,10 +140,11 @@ export function useStudioUrlState({
       return;
     }
 
-    const selection = buildDomSelectionFromTarget(element, { preferClipAncestor: false });
-    applyDomSelection(selection, { revealPanel: false });
     hydratedSelectionRef.current = true;
     pendingSelectionRef.current = null;
+    void buildDomSelectionFromTarget(element, { preferClipAncestor: false }).then((selection) => {
+      applyDomSelection(selection, { revealPanel: false });
+    });
   }, [
     activeCompPath,
     applyDomSelection,

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

@@ -1,6 +1,10 @@
 import { describe, expect, it, vi } from "vitest";
-import { wrapTimeline } from "./playbackAdapter";
-import type { TimelineLike } from "./playbackTypes";
+import { createStaticSeekPlaybackAdapter, wrapTimeline } from "./playbackAdapter";
+import type {
+  RuntimePlaybackAdapter,
+  StaticSeekPlaybackClock,
+  TimelineLike,
+} from "./playbackTypes";
 
 describe("wrapTimeline seek keepPlaying option (#834)", () => {
   function mockTimeline(): TimelineLike & {
@@ -48,3 +52,162 @@ describe("wrapTimeline seek keepPlaying option (#834)", () => {
     expect(tl.seek).toHaveBeenCalledWith(5);
   });
 });
+
+describe("createStaticSeekPlaybackAdapter seek keepPlaying option", () => {
+  type StaticSeekPlayer = Pick<RuntimePlaybackAdapter, "getTime"> &
+    Partial<Pick<RuntimePlaybackAdapter, "renderSeek" | "seek">>;
+
+  function makeFakeClock(): StaticSeekPlaybackClock & {
+    runNextFrame: () => boolean;
+    cancelled: number[];
+    scheduled: number;
+    setNow: (ms: number) => void;
+  } {
+    let now = 0;
+    let nextHandle = 0;
+    const pending = new Map<number, FrameRequestCallback>();
+    const cancelled: number[] = [];
+    let scheduled = 0;
+    return {
+      now: () => now,
+      requestAnimationFrame: (cb) => {
+        nextHandle += 1;
+        pending.set(nextHandle, cb);
+        scheduled += 1;
+        return nextHandle;
+      },
+      cancelAnimationFrame: (handle) => {
+        if (pending.delete(handle)) cancelled.push(handle);
+      },
+      runNextFrame: () => {
+        const next = pending.entries().next();
+        if (next.done) return false;
+        const [handle, cb] = next.value;
+        pending.delete(handle);
+        cb(now);
+        return true;
+      },
+      cancelled,
+      get scheduled() {
+        return scheduled;
+      },
+      setNow: (ms) => {
+        now = ms;
+      },
+    };
+  }
+
+  function makePlayer(): StaticSeekPlayer & {
+    renderSeek: ReturnType<typeof vi.fn>;
+  } {
+    return {
+      getTime: () => 0,
+      renderSeek: vi.fn(),
+    };
+  }
+
+  it("default seek stops the RAF ticker so the adapter reports paused", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    adapter.play();
+    expect(adapter.isPlaying()).toBe(true);
+
+    adapter.seek(5);
+
+    expect(adapter.isPlaying()).toBe(false);
+    expect(adapter.getTime()).toBe(5);
+    expect(player.renderSeek).toHaveBeenLastCalledWith(5);
+    expect(clock.cancelled.length).toBeGreaterThan(0);
+  });
+
+  it("default seek prevents the ticker from advancing further", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    adapter.play();
+    player.renderSeek.mockClear();
+
+    adapter.seek(5);
+
+    // Any frame the RAF callback already had queued before cancel should be a no-op.
+    clock.setNow(1000);
+    clock.runNextFrame();
+    expect(player.renderSeek).toHaveBeenCalledTimes(1); // only the seek itself
+    expect(player.renderSeek).toHaveBeenLastCalledWith(5);
+    expect(adapter.getTime()).toBe(5);
+  });
+
+  it("seek with { keepPlaying: true } preserves playback and rebases the ticker", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    adapter.play();
+    clock.setNow(500);
+    expect(adapter.isPlaying()).toBe(true);
+
+    adapter.seek(3, { keepPlaying: true });
+
+    expect(adapter.isPlaying()).toBe(true);
+    expect(adapter.getTime()).toBe(3);
+
+    // Advance 1s of wall-clock time. With playStartTime rebased to 3 and
+    // playStartNow rebased to 500, the next tick should render around t=4.
+    clock.setNow(1500);
+    clock.runNextFrame();
+    expect(player.renderSeek).toHaveBeenLastCalledWith(4);
+  });
+
+  it("seek with { keepPlaying: false } pauses (matches default)", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    adapter.play();
+    adapter.seek(5, { keepPlaying: false });
+
+    expect(adapter.isPlaying()).toBe(false);
+    expect(player.renderSeek).toHaveBeenLastCalledWith(5);
+  });
+
+  it("seek with { keepPlaying: true } does not force playback when adapter is paused", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    adapter.seek(2, { keepPlaying: true });
+
+    expect(adapter.isPlaying()).toBe(false);
+    expect(adapter.getTime()).toBe(2);
+    expect(player.renderSeek).toHaveBeenLastCalledWith(2);
+  });
+
+  it("seek without options stays back-compatible with the previous signature", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    // Caller written before the options parameter existed.
+    adapter.seek(4);
+
+    expect(player.renderSeek).toHaveBeenLastCalledWith(4);
+    expect(adapter.getTime()).toBe(4);
+    expect(adapter.isPlaying()).toBe(false);
+  });
+
+  it("default seek clamps to duration and still pauses", () => {
+    const clock = makeFakeClock();
+    const player = makePlayer();
+    const adapter = createStaticSeekPlaybackAdapter(player, 10, clock);
+
+    adapter.play();
+    adapter.seek(99);
+
+    expect(adapter.getTime()).toBe(10);
+    expect(player.renderSeek).toHaveBeenLastCalledWith(10);
+    expect(adapter.isPlaying()).toBe(false);
+  });
+});

package/src/player/lib/playbackAdapter.ts

@@ -113,12 +113,20 @@ export function createStaticSeekPlaybackAdapter(
       playing = false;
       stopTicker();
     },
-    seek: (time) => {
+    seek: (time, options) => {
       renderSeek(time);
-      if (playing) {
-        playStartTime = currentTime;
-        playStartNow = clock.now();
+      if (options?.keepPlaying) {
+        if (playing) {
+          playStartTime = currentTime;
+          playStartNow = clock.now();
+        }
+        return;
       }
+      // Default seek aligns with wrapTimeline: stop the RAF ticker so the
+      // adapter's `playing` flag matches the public seek contract instead of
+      // silently driving renderSeek in the background.
+      playing = false;
+      stopTicker();
     },
     getTime: () => currentTime,
     getDuration: () => safeDuration,

package/src/utils/studioUrlState.test.ts

@@ -53,7 +53,7 @@ function renderStudioUrlStateHarness(
     timelineVisible: true,
     activeCompPathHydrated: true,
     domEditSelection: null,
-    buildDomSelectionFromTarget: () => null,
+    buildDomSelectionFromTarget: () => Promise.resolve(null),
     applyDomSelection: () => {},
     initialState: {
       activeCompPath: null,
@@ -162,7 +162,7 @@ describe("studio url state", () => {
     expect(normalizeStudioUrlPanelTab("motion", { motionPanelEnabled: false })).toBe("design");
   });
 
-  it("hydrates seek first, preserves the initial url state, then restores selection", () => {
+  it("hydrates seek first, preserves the initial url state, then restores selection", async () => {
     vi.useFakeTimers();
     window.history.replaceState(null, "", "#project/demo?t=4.2&tab=design&selId=hero");
     const requestSeek = vi.fn();
@@ -209,7 +209,7 @@ describe("studio url state", () => {
       rightPanelTab: "design",
       rightCollapsed: false,
       applyDomSelection,
-      buildDomSelectionFromTarget: () => restoredSelection,
+      buildDomSelectionFromTarget: () => Promise.resolve(restoredSelection),
       initialState: {
         activeCompPath: null,
         currentTime: 4.2,
@@ -232,8 +232,10 @@ describe("studio url state", () => {
     expect(applyDomSelection).not.toHaveBeenCalled();
 
     harness.rerender({ currentTime: 4.2 });
-    act(() => {
+    await act(async () => {
       vi.advanceTimersByTime(250);
+      // Flush microtasks so the async buildDomSelectionFromTarget Promise resolves
+      await Promise.resolve();
     });
     expect(applyDomSelection).toHaveBeenCalledWith(restoredSelection, { revealPanel: false });