fix(studio): a sealed preview pauses on press and reopens a link's selection (#8135)

* fix(studio): a sealed preview pauses on press and reopens a link's selection

* fix(studio): a linked selection retries on a timer, whatever the playhead

* refactor(studio): one lookup-state hook keeps the URL-state hook's size where main had it

* fix(studio): a linked group member keeps the lookup waiting until the preview can answer for it
This commit is contained in:
Miguel Ángel
2026-11-18 16:46:11 +00:00
committed by GitHub
parent 559499453b
commit e5566b3dc9
6 changed files with 397 additions and 88 deletions
@@ -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<DomEditSelection | null>;
resolveDomSelectionFromPreviewPoint: (
@@ -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]);
});
});
@@ -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(<Harness />);
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(<Harness />);
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(<Harness />);
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(
<Harness selection={{ sourceFile: "index.html", id: "s0", group: [{ id: "s1" }] }} />,
);
await flush();
await flush();
expect(memberTries).toBe(2);
expect(applyMarqueeSelection).toHaveBeenCalledWith([built, built], "replace");
});
});
+170 -84
View File
@@ -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<DomEditSelection | null>;
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<UrlSelectionFound>;
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<DomEditSelection | null> {
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<DomEditSelection[] | null> {
const primary = await buildDomSelection(primaryElement, { preferClipAncestor: false });
}: ResolveUrlSelectionsParams): Promise<DomEditSelection[] | null | undefined> {
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<typeof setTimeout> | undefined;
pendingSettle: (() => void) | undefined;
hydrating: boolean;
}
function useUrlLookupState(): UrlLookupState {
const state = useRef<UrlLookupState>({
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<number | null>(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(() => {
@@ -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();
@@ -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;