diff --git a/packages/studio/src/hooks/useDomSelectionTypes.ts b/packages/studio/src/hooks/useDomSelectionTypes.ts index a9c82d61e0..02bcbc5ad7 100644 --- a/packages/studio/src/hooks/useDomSelectionTypes.ts +++ b/packages/studio/src/hooks/useDomSelectionTypes.ts @@ -1,5 +1,6 @@ import type { Dispatch, MutableRefObject, SetStateAction } from "react"; import type { DomEditSelection } from "../components/editor/domEditing"; +import type { PreviewElement } from "../player/lib/previewElements"; import type { SelectElementOptions, TimelineElement } from "../player"; import type { RightPanelTab } from "../utils/studioHelpers"; import type { MarqueeSelectionMode } from "../utils/marqueeGeometry"; @@ -73,7 +74,7 @@ export interface UseDomSelectionReturn { ) => void; clearDomSelection: () => void; buildDomSelectionFromTarget: ( - target: HTMLElement, + target: HTMLElement | PreviewElement, options?: ResolveDomSelectionOptions, ) => Promise; resolveDomSelectionFromPreviewPoint: ( diff --git a/packages/studio/src/hooks/useStudioUrlState.hydration.test.ts b/packages/studio/src/hooks/useStudioUrlState.hydration.test.ts index 711a471c76..0e578fc7c8 100644 --- a/packages/studio/src/hooks/useStudioUrlState.hydration.test.ts +++ b/packages/studio/src/hooks/useStudioUrlState.hydration.test.ts @@ -24,11 +24,9 @@ describe("restoring a selection from the URL", () => { ); await resolveUrlSelections({ - doc, - primaryElement: doc.getElementById("a") as HTMLElement, + find: async (target) => (target.id ? doc.getElementById(target.id) : doc.getElementById("a")), selection: { sourceFile: "index.html" } as never, group: ids.slice(1).map((id) => ({ id, sourceFile: "index.html" })) as never, - activeCompPath: "index.html", isCurrent: () => true, buildDomSelection, }); @@ -36,4 +34,57 @@ describe("restoring a selection from the URL", () => { expect(probed[0]).toBeUndefined(); expect(probed.slice(1)).toEqual([true, true, true]); }); + + it("restores a sealed preview's selection from the frame's description of it", async () => { + const described = { handle: "0123456789abcdef:1", id: "a" } as never; + const buildDomSelection = vi.fn(async (target: unknown) => ({ target }) as never); + const members = await resolveUrlSelections({ + find: async () => described, + selection: { id: "a", sourceFile: "index.html" } as never, + group: [], + isCurrent: () => true, + buildDomSelection, + }); + expect(buildDomSelection).toHaveBeenCalledWith(described, { preferClipAncestor: false }); + expect(members).toEqual([{ target: described }]); + }); + + it("answers undefined while the frame cannot answer, so the caller retries", async () => { + const buildDomSelection = vi.fn(); + const members = await resolveUrlSelections({ + find: async () => undefined, + selection: { id: "a", sourceFile: "index.html" } as never, + group: [], + isCurrent: () => true, + buildDomSelection, + }); + expect(members).toBeUndefined(); + expect(buildDomSelection).not.toHaveBeenCalled(); + }); + + it("waits for a group member the frame cannot answer for yet, rather than dropping it", async () => { + const a = document.createElement("div"); + const built = { id: "a" } as never; + const members = await resolveUrlSelections({ + find: async (target) => (target.id === "a" ? a : undefined), + selection: { id: "a", sourceFile: "index.html" } as never, + group: [{ id: "b" }], + isCurrent: () => true, + buildDomSelection: async () => built, + }); + expect(members).toBeUndefined(); + }); + + it("omits a group member the frame confirms is gone", async () => { + const a = document.createElement("div"); + const built = { id: "a" } as never; + const members = await resolveUrlSelections({ + find: async (target) => (target.id === "a" ? a : null), + selection: { id: "a", sourceFile: "index.html" } as never, + group: [{ id: "b" }], + isCurrent: () => true, + buildDomSelection: async () => built, + }); + expect(members).toEqual([built]); + }); }); diff --git a/packages/studio/src/hooks/useStudioUrlState.retry.test.tsx b/packages/studio/src/hooks/useStudioUrlState.retry.test.tsx new file mode 100644 index 0000000000..b33c8d351b --- /dev/null +++ b/packages/studio/src/hooks/useStudioUrlState.retry.test.tsx @@ -0,0 +1,141 @@ +// @vitest-environment happy-dom + +import React, { act } from "react"; +import type { Root } from "react-dom/client"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { DomEditSelection } from "../components/editor/domEditing"; +import { findSelectionElement } from "../components/editor/previewSelection"; +import { mountReactHarness } from "./domSelectionTestHarness"; +import { useStudioUrlState } from "./useStudioUrlState"; +import type { StudioUrlSelectionState } from "../utils/studioUrlState"; + +vi.mock("../components/editor/previewSelection", () => ({ findSelectionElement: vi.fn() })); + +(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true; + +const find = vi.mocked(findSelectionElement); +const applyDomSelection = vi.fn(); +const applyMarqueeSelection = vi.fn(); +const element = document.createElement("div"); +const built = { element, id: "s0", sourceFile: "index.html" } as unknown as DomEditSelection; +let root: Root | null = null; + +function Harness({ + selection = { sourceFile: "index.html", id: "s0" }, +}: { + selection?: StudioUrlSelectionState; +}) { + useStudioUrlState({ + projectId: "proj", + activeCompPath: null, + duration: 10, + isPlaying: false, + compositionLoading: false, + refreshKey: 0, + previewIframeRef: { current: document.createElement("iframe") }, + rightPanelTab: "design", + rightCollapsed: false, + activeCompPathHydrated: true, + domEditSelection: null, + domEditGroupSelections: [], + applyMarqueeSelection, + buildDomSelectionFromTarget: async () => built, + applyDomSelection, + setRightPanelTab: vi.fn(), + // A link with a selection and no time: the playhead stays at 0. + initialState: { + activeCompPath: null, + currentTime: null, + rightPanelTab: null, + rightCollapsed: null, + timelineVisible: null, + selection, + }, + }); + return null; +} + +async function flush() { + await act(async () => { + await vi.advanceTimersByTimeAsync(300); + }); +} + +// happy-dom fires hashchange on replaceState, which browsers never do; only this file's own events pass. +const dropHashChange = (event: Event) => { + if (!(event as Event & { fromTest?: boolean }).fromTest) event.stopImmediatePropagation(); +}; + +beforeEach(() => { + vi.useFakeTimers(); + window.addEventListener("hashchange", dropHashChange, { capture: true }); +}); + +afterEach(() => { + window.history.replaceState(null, "", "#"); + window.removeEventListener("hashchange", dropHashChange, { capture: true }); + act(() => root?.unmount()); + root = null; + vi.useRealTimers(); + vi.clearAllMocks(); +}); + +describe("useStudioUrlState selection retry", () => { + it("restores a link's selection at playhead 0 when the frame answers on its second try", async () => { + find.mockResolvedValueOnce(undefined).mockResolvedValue(element); + root = mountReactHarness(); + await act(async () => { + await vi.advanceTimersByTimeAsync(0); + }); + // While the lookup retries, the URL still carries the selection, so a reload keeps it. + expect(window.location.hash).toContain("selId=s0"); + await flush(); + expect(find).toHaveBeenCalledTimes(2); + expect(applyDomSelection).toHaveBeenCalledWith(built, { revealPanel: false }); + }); + + it("asks a frame that never answers on a timer, not as fast as it replies", async () => { + find.mockResolvedValue(undefined); + root = mountReactHarness(); + await act(async () => { + await vi.advanceTimersByTimeAsync(1000); + }); + expect(find.mock.calls.length).toBeLessThanOrEqual(5); + expect(applyDomSelection).not.toHaveBeenCalledWith(built, expect.anything()); + }); + + it("finishes hydration when a newer link replaces a lookup that is still waiting", async () => { + find.mockResolvedValue(undefined); + root = mountReactHarness(); + await act(async () => { + await vi.advanceTimersByTimeAsync(0); + }); + expect(window.location.hash).toContain("selId=s0"); + find.mockResolvedValue(element); + await act(async () => { + window.history.replaceState(null, "", window.location.hash.replace("selId=s0", "selId=s1")); + window.dispatchEvent(Object.assign(new Event("hashchange"), { fromTest: true })); + await vi.advanceTimersByTimeAsync(0); + }); + await flush(); + expect(applyDomSelection).toHaveBeenCalledWith(built, { revealPanel: false }); + expect(window.location.hash).not.toContain("selId=s0"); + }); + + it("keeps a linked group member the frame answers for only on a later try", async () => { + const member = document.createElement("div"); + let memberTries = 0; + find.mockImplementation(async (_iframe, target) => { + if (target.id !== "s1") return element; + memberTries += 1; + return memberTries > 1 ? member : undefined; + }); + root = mountReactHarness( + , + ); + await flush(); + await flush(); + expect(memberTries).toBe(2); + expect(applyMarqueeSelection).toHaveBeenCalledWith([built, built], "replace"); + }); +}); diff --git a/packages/studio/src/hooks/useStudioUrlState.ts b/packages/studio/src/hooks/useStudioUrlState.ts index 50dfe1a4fb..2eb003f756 100644 --- a/packages/studio/src/hooks/useStudioUrlState.ts +++ b/packages/studio/src/hooks/useStudioUrlState.ts @@ -1,6 +1,9 @@ import { useCallback, useEffect, useRef, useState } from "react"; import { usePlayerStore } from "../player"; -import { findElementForSelection, type DomEditSelection } from "../components/editor/domEditing"; +import type { DomEditSelection } from "../components/editor/domEditing"; +import type { SelectionLookupTarget } from "../components/editor/domEditSelectionRules"; +import { findSelectionElement } from "../components/editor/previewSelection"; +import type { PreviewElement } from "../player/lib/previewElements"; import type { MarqueeSelectionMode } from "../utils/marqueeGeometry"; import { clampNumber, type RightPanelTab } from "../utils/studioHelpers"; import { parseProjectIdFromHash } from "../utils/projectRouting"; @@ -27,7 +30,7 @@ interface UseStudioUrlStateParams { domEditGroupSelections: DomEditSelection[]; applyMarqueeSelection: (selections: DomEditSelection[], mode: MarqueeSelectionMode) => void; buildDomSelectionFromTarget: ( - target: HTMLElement, + target: HTMLElement | PreviewElement, options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean }, ) => Promise; applyDomSelection: ( @@ -86,42 +89,40 @@ function toPersistedSelection( }; } +// A frame still loading cannot answer a lookup yet: it is asked again this often, this many times (about 10 s). +const URL_SELECTION_RETRY_MS = 250; +const URL_SELECTION_TRIES = 40; + function replaceHash(nextHash: string) { if (typeof window === "undefined") return; if (window.location.hash === nextHash) return; window.history.replaceState(null, "", nextHash); } +type UrlSelectionFound = HTMLElement | PreviewElement | null | undefined; + interface ResolveUrlSelectionsParams { - doc: Document; - primaryElement: HTMLElement; + find: (target: SelectionLookupTarget) => Promise; selection: StudioUrlSelectionState; group: StudioUrlSelectionTarget[]; - activeCompPath: string | null; isCurrent: () => boolean; buildDomSelection: UseStudioUrlStateParams["buildDomSelectionFromTarget"]; } -function findUrlSelectionElement( - doc: Document, +function urlLookupTarget( target: StudioUrlSelectionTarget, fallbackSourceFile: string, - activeCompPath: string | null, -): HTMLElement | null { - return findElementForSelection( - doc, - { - sourceFile: target.sourceFile ?? fallbackSourceFile, - id: target.id, - selector: target.selector, - selectorIndex: target.selectorIndex, - }, - activeCompPath, - ); +): SelectionLookupTarget { + return { + sourceFile: target.sourceFile ?? fallbackSourceFile, + id: target.id, + selector: target.selector, + selectorIndex: target.selectorIndex, + }; } async function buildOptionalDomSelection( - element: HTMLElement | null, + element: HTMLElement | PreviewElement | null | undefined, buildDomSelection: UseStudioUrlStateParams["buildDomSelectionFromTarget"], ): Promise { if (!element) return null; @@ -135,25 +136,24 @@ async function buildOptionalDomSelection( } export async function resolveUrlSelections({ - doc, - primaryElement, + find, selection, group, - activeCompPath, isCurrent, buildDomSelection, -}: ResolveUrlSelectionsParams): Promise { - const primary = await buildDomSelection(primaryElement, { preferClipAncestor: false }); +}: ResolveUrlSelectionsParams): Promise { + const found = await find(urlLookupTarget(selection, "")); + if (!isCurrent()) return null; + if (found === undefined) return undefined; + const primary = found && (await buildDomSelection(found, { preferClipAncestor: false })); if (!isCurrent()) return null; if (!primary) return []; const members = [primary]; for (const member of group) { - const element = findUrlSelectionElement( - doc, - member, - selection.sourceFile ?? "", - activeCompPath, - ); + const element = await find(urlLookupTarget(member, selection.sourceFile ?? "")); + if (!isCurrent()) return null; + // A member the frame cannot answer for yet is not missing: the whole lookup waits for it. + if (element === undefined) return undefined; const resolved = await buildOptionalDomSelection(element, buildDomSelection); if (!isCurrent()) return null; if (resolved) members.push(resolved); @@ -161,6 +161,123 @@ export async function resolveUrlSelections({ return members; } +interface UrlSelectionLookup extends ResolveUrlSelectionsParams { + apply: (members: DomEditSelection[]) => void; + settle: () => void; + retry: (next: () => void) => void; +} + +function lookUpUrlSelection(lookup: UrlSelectionLookup, triesLeft = URL_SELECTION_TRIES): void { + void resolveUrlSelections(lookup).then((members) => { + if (members === undefined && triesLeft > 1) { + lookup.retry(() => lookUpUrlSelection(lookup, triesLeft - 1)); + return; + } + if (members) lookup.apply(members); + lookup.settle(); + }); +} + +function applyUrlMembers( + members: DomEditSelection[], + grouped: boolean, + applyDomSelection: ( + selection: DomEditSelection | null, + options: { revealPanel: boolean }, + ) => void, + applyMarqueeSelection: (selections: DomEditSelection[], mode: MarqueeSelectionMode) => void, +): void { + const primary = members[0]; + if (!primary) return applyDomSelection(null, { revealPanel: false }); + if (!grouped) return applyDomSelection(primary, { revealPanel: false }); + // Missing group members are dropped without failing the rest. + applyMarqueeSelection(members, "replace"); +} + +// One URL-selection lookup at a time: a newer one replaces the older, which ends then. +interface UrlLookupState { + applySeq: number; + retryTimer: ReturnType | undefined; + pendingSettle: (() => void) | undefined; + hydrating: boolean; +} + +function useUrlLookupState(): UrlLookupState { + const state = useRef({ + applySeq: 0, + retryTimer: undefined, + pendingSettle: undefined, + hydrating: false, + }).current; + useEffect(() => () => clearTimeout(state.retryTimer), [state]); + return state; +} + +function endOnce(state: UrlLookupState, onSettled?: () => void): () => void { + let ended = false; + const settle = () => { + if (ended) return; + ended = true; + if (state.pendingSettle === settle) state.pendingSettle = undefined; + onSettled?.(); + }; + return settle; +} + +interface UrlSelectionHost { + iframe: HTMLIFrameElement | null; + activeCompPath: string | null; + lookup: UrlLookupState; + buildDomSelection: ResolveUrlSelectionsParams["buildDomSelection"]; + applyDomSelection: ( + selection: DomEditSelection | null, + options: { revealPanel: boolean }, + ) => void; + applyMarqueeSelection: (selections: DomEditSelection[], mode: MarqueeSelectionMode) => void; +} + +// Resolve a URL selection in the preview, sealed or not, and apply it. False when there is no preview yet; a frame +// that cannot answer yet is asked again on a timer. onSettled runs once the lookup ends, however it ends. +function startUrlSelection( + host: UrlSelectionHost, + selection: StudioUrlSelectionState | null, + onSettled?: () => void, +): boolean { + const { iframe } = host; + if (selection && !iframe) return false; + const { lookup } = host; + clearTimeout(lookup.retryTimer); + const applySeq = ++lookup.applySeq; + lookup.pendingSettle?.(); + const settle = endOnce(lookup, onSettled); + lookup.pendingSettle = settle; + if (!selection || !iframe) { + host.applyDomSelection(null, { revealPanel: false }); + settle(); + return true; + } + const group = selection.group ?? []; + lookUpUrlSelection({ + find: (target) => findSelectionElement(iframe, target, host.activeCompPath), + selection, + group, + isCurrent: () => applySeq === lookup.applySeq, + buildDomSelection: host.buildDomSelection, + apply: (members) => + applyUrlMembers( + members, + group.length > 0, + host.applyDomSelection, + host.applyMarqueeSelection, + ), + settle, + retry: (next) => { + lookup.retryTimer = setTimeout(next, URL_SELECTION_RETRY_MS); + }, + }); + return true; +} + export function useStudioUrlState({ projectId, activeCompPath, @@ -190,7 +307,7 @@ export function useStudioUrlState({ const [selectionHydrated, setSelectionHydrated] = useState(initialState.selection == null); const pendingSelectionRef = useRef(initialState.selection); const stableTimeRef = useRef(initialState.currentTime); - const selectionApplySeqRef = useRef(0); + const urlLookup = useUrlLookupState(); const buildUrlState = useCallback( (): StudioUrlState => ({ @@ -206,63 +323,28 @@ export function useStudioUrlState({ [activeCompPath, domEditGroupSelections, domEditSelection, rightCollapsed, rightPanelTab], ); - // Resolve a URL selection to a live element and apply it. Shared by the initial - // hydration effect and the external-navigation (hashchange) handler. Returns - // false ONLY when the iframe document isn't ready yet (caller should retry); - // a missing element or null selection clears the selection and returns true. + // Shared by the initial hydration effect and the hashchange handler. const applyUrlSelection = useCallback( - (selection: StudioUrlSelectionState | null): boolean => { - const applySeq = ++selectionApplySeqRef.current; - if (!selection) { - applyDomSelection(null, { revealPanel: false }); - return true; - } - let doc: Document | null = null; - try { - doc = previewIframeRef.current?.contentDocument ?? null; - } catch { - return false; - } - if (!doc) return false; - const element = findElementForSelection( - doc, + (selection: StudioUrlSelectionState | null, onSettled?: () => void): boolean => + startUrlSelection( { - sourceFile: selection.sourceFile ?? "", - id: selection.id, - selector: selection.selector, - selectorIndex: selection.selectorIndex, + iframe: previewIframeRef.current, + activeCompPath, + lookup: urlLookup, + buildDomSelection: buildDomSelectionFromTarget, + applyDomSelection, + applyMarqueeSelection, }, - activeCompPath, - ); - if (!element) { - applyDomSelection(null, { revealPanel: false }); - return true; - } - const group = selection.group ?? []; - void resolveUrlSelections({ - doc, - primaryElement: element, selection, - group, - activeCompPath, - isCurrent: () => applySeq === selectionApplySeqRef.current, - buildDomSelection: buildDomSelectionFromTarget, - }).then((members) => { - if (!members) return; - const primary = members[0]; - if (!primary) return applyDomSelection(null, { revealPanel: false }); - if (group.length === 0) return applyDomSelection(primary, { revealPanel: false }); - // Missing group members are dropped without failing the rest. - applyMarqueeSelection(members, "replace"); - }); - return true; - }, + onSettled, + ), [ activeCompPath, applyDomSelection, applyMarqueeSelection, buildDomSelectionFromTarget, previewIframeRef, + urlLookup, ], ); @@ -288,7 +370,7 @@ export function useStudioUrlState({ const selectionHydrationTime = selectionHydrated ? 0 : currentTime; useEffect(() => { if (!projectId || hydratedSelectionRef.current || compositionLoading) return; - if (!hydratedSeekRef.current) return; + if (!hydratedSeekRef.current || urlLookup.hydrating) return; const targetTime = initialState.currentTime; if (targetTime != null && Math.abs(selectionHydrationTime - stableTimeRef.current!) > 0.05) { return; @@ -303,10 +385,13 @@ export function useStudioUrlState({ markHydrated(); return; } - // Doc not ready yet → leave hydration pending so a later tick retries. - if (!applyUrlSelection(pendingSelection)) return; - markHydrated(); - pendingSelectionRef.current = null; + // Hydration ends with the lookup, so the URL keeps the selection; no preview yet: a later tick retries. + const settled = () => { + urlLookup.hydrating = false; + markHydrated(); + pendingSelectionRef.current = null; + }; + urlLookup.hydrating = applyUrlSelection(pendingSelection, settled); }, [ applyUrlSelection, compositionLoading, @@ -314,6 +399,7 @@ export function useStudioUrlState({ initialState.currentTime, projectId, refreshKey, + urlLookup, ]); useEffect(() => { diff --git a/packages/studio/src/utils/studioPreviewHelpers.test.ts b/packages/studio/src/utils/studioPreviewHelpers.test.ts index 450e6da973..3410e22ebd 100644 --- a/packages/studio/src/utils/studioPreviewHelpers.test.ts +++ b/packages/studio/src/utils/studioPreviewHelpers.test.ts @@ -90,6 +90,29 @@ describe("pauseStudioPreviewPlayback", () => { expect(siblingPause).not.toHaveBeenCalled(); }); + it("pauses a sealed preview by message, since its window refuses every other read", () => { + const postMessage = vi.fn(); + // A cross-origin window: postMessage is allowed, any other property read throws. + const sealedWindow = new Proxy( + { postMessage }, + { + get(target, key) { + if (key === "postMessage") return target.postMessage; + throw new DOMException( + "Blocked a frame from accessing a cross-origin frame.", + "SecurityError", + ); + }, + }, + ); + const iframe = { contentWindow: sealedWindow } as unknown as HTMLIFrameElement; + + pauseStudioPreviewPlayback(iframe); + + expect(postMessage).toHaveBeenCalledTimes(1); + expect(postMessage.mock.calls[0]?.[0]).toMatchObject({ action: "pause" }); + }); + it("falls back to pausing timelines directly when __player is unavailable", () => { const timelinePause = vi.fn(); const siblingPause = vi.fn(); diff --git a/packages/studio/src/utils/studioPreviewHelpers.ts b/packages/studio/src/utils/studioPreviewHelpers.ts index 839c7c3810..1814c894b6 100644 --- a/packages/studio/src/utils/studioPreviewHelpers.ts +++ b/packages/studio/src/utils/studioPreviewHelpers.ts @@ -4,6 +4,8 @@ import { pointerTarget, pointerTargets, } from "@hyperframes/core/runtime/editing-port"; +import { bridgePlaybackAdapter } from "../player/lib/bridgePlayback"; +import { previewFrameOpaque } from "../player/lib/previewChannel"; // One canvas hit-test for Studio and the runtime that answers it for a frame Studio cannot script. export { coversComposition }; @@ -73,6 +75,11 @@ function readPlaybackTime(target: object | null, key: string): number | null { } export function pauseStudioPreviewPlayback(iframe: HTMLIFrameElement | null): number | null { + if (iframe && previewFrameOpaque(iframe)) { + const bridge = bridgePlaybackAdapter(iframe); + bridge?.pause(); + return bridge?.getTime() ?? null; + } const win = iframe?.contentWindow; if (!win) return null;