feat(studio): layers panel and marquee read an opaque preview over its channel (#7639)

* feat(studio): layers panel and marquee read an opaque preview over its channel

The runtime answers a new layers request with the Layers walk: each layer's
handle, depth, child count, z-index and kind, by the rules Studio walks a
scriptable frame with, which move to core. On an opaque frame the Layers
panel lists, selects and drills in from it, and the marquee measures its
candidates over the channel and selects from their descriptions. An opaque
selection maps to a timeline clip known only by its clip id, so a marquee's
picks survive the timeline sync.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio): opaque preview hover, layers drill-in, marquee paging and delete path

Review follow-ups for the opaque-preview Layers panel and marquee:

- Delete on an opaque selection runs the DOM delete again. The clip-id match
  that lets a selection find a row known only by its clip id is now opt-in
  (`clipIdScope`), passed only by selection sync and the Layers seek, never by
  delete or group commits, which need a patch target that row lacks. A row
  with no file reads as in the open composition, as the forward lookup does.
- The runtime's `layers` reports a drill-in group it no longer has
  (`missingGroup`) and lists nothing, so the panel leaves the drill-in after a
  reload as the same-origin branch does, rather than list the whole page.
- `layers` takes an `offset`, and the marquee pages through every layer, so
  elements past one reply's 2,048 cap still band-select.
- A Layers refresh that lands while an opaque read is in flight runs once more
  when it settles, instead of being dropped.
- A hover resolved for a pointer move that a leave or newer move superseded is
  dropped.
- `pointer-targets` reads the hit stack once per request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(core): keep the layers paging test inside the Windows runner's timeout

The paging test walked the 2,051-layer page three times with every row
mapped, which ran past 5 s on windows-latest. It now maps only the last
page's rows and has its own 20 s timeout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-11-13 07:48:32 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent ff687fed99
commit be67089a80
31 changed files with 1210 additions and 80 deletions
@@ -147,6 +147,7 @@ describe("installEditingAgent", () => {
"ancestors",
"query",
"geometry",
"layers",
],
},
});
@@ -316,6 +317,20 @@ describe("installEditingAgent", () => {
100 + index,
"invalid-params",
]),
...[
{ group: null },
{ group: "0123456789abcdef:0" },
{ group: ["0123456789abcdef:1"] },
{ group: "0123456789abcdef:1", max: 5 },
{ scope: "0123456789abcdef:1" },
{ offset: -1 },
{ offset: 1.5 },
{ offset: "2" },
].map((params, index) => [
{ v: 1, id: 130 + index, kind: "layers", params },
130 + index,
"invalid-params",
]),
...[["--"], ["--a b"], ["--a;b"], ["--a:b"], ["Color"], ["-x"], ["--" + "a".repeat(255)]].map(
(properties, index) => [
{ v: 1, id: 60 + index, kind: "computed-styles", params: { selector: "p", properties } },
@@ -29,6 +29,7 @@ import {
} from "./editingHandles";
import { elementGeometry } from "./editingGeometry";
import { pointerTargetsAt } from "./editingTargets";
import { layersOf } from "./editingLayers";
import { getLogicalOpacity } from "../studioPreviewMark";
type Handlers = {
@@ -87,6 +88,7 @@ const HANDLERS: Handlers = {
ancestors: ({ handles }) => ({ ancestors: ancestorHandles(handles) }),
query: ({ selector }) => queryElements(selector),
geometry: ({ handles, children }) => elementGeometry(handles, children),
layers: ({ group, offset }) => layersOf(group, offset),
};
function serve(port: MessagePort): void {
+1 -1
View File
@@ -34,7 +34,7 @@ const collected = new FinalizationRegistry<number>((n) => {
});
let lastNumber = 0;
function handleFor(element: Element): EditingElementHandle {
export function handleFor(element: Element): EditingElementHandle {
let n = numbers.get(element);
if (n === undefined) {
n = ++lastNumber;
@@ -0,0 +1,78 @@
import { afterEach, describe, expect, it } from "vitest";
import { MAX_QUERY_MATCHES } from "./editingElement";
import { elementForHandle } from "./editingHandles";
import { layersOf } from "./editingLayers";
afterEach(() => {
document.body.innerHTML = "";
});
const named = (handle: string) =>
elementForHandle(handle)?.id || elementForHandle(handle)?.className;
describe("layers", () => {
it("walks layers in document order with their depth, child count, z-index and kind", () => {
document.body.innerHTML = `<main data-composition-id="m">
<div id="card" style="z-index: 3"><p id="title">Hi <b>there</b></p><img id="pic"></div>
<div id="pair" data-hf-group="g"><i id="a"></i></div>
<div id="parked" data-hf-clip-hidden style="visibility: hidden"><p id="inside" style="visibility: visible">x</p></div>
<div><span class="loose"></span></div>
<script id="code"></script></main>`;
const { layers, truncated } = layersOf();
expect(truncated).toBe(false);
expect(layers.map((layer) => [named(layer.handle), layer.depth, layer.childCount])).toEqual([
["card", 0, 2],
["title", 1, 0],
["pic", 1, 0],
["pair", 0, 1],
["a", 1, 0],
["loose", 0, 0],
]);
expect(layers.map((layer) => layer.kind)).toEqual([
"group",
"text",
"image",
"group",
"shape",
"shape",
]);
expect(layers[0]!.zIndex).toBe(3);
});
it("scopes to a drilled-into group, and caps the walk", () => {
const tiles = Array.from({ length: MAX_QUERY_MATCHES + 3 }, (_, i) => `<i id="t${i}"></i>`);
document.body.innerHTML = `<main data-composition-id="m"><div id="pair" data-hf-group="g">
<i id="a"></i><i id="b"></i></div>${tiles.join("")}</main>`;
const all = layersOf();
expect(all).toMatchObject({ truncated: true });
expect(all.layers).toHaveLength(MAX_QUERY_MATCHES);
const pair = all.layers[0]!.handle;
expect(layersOf(pair).layers.map((layer) => [named(layer.handle), layer.depth])).toEqual([
["a", 0],
["b", 0],
]);
expect(layersOf(pair).missingGroup).toBe(false);
});
it("pages past the cap from an offset, so a caller can read every layer", () => {
const tiles = Array.from({ length: MAX_QUERY_MATCHES + 3 }, (_, i) => `<i id="t${i}"></i>`);
document.body.innerHTML = `<main data-composition-id="m">${tiles.join("")}</main>`;
const rest = layersOf(undefined, MAX_QUERY_MATCHES);
expect(rest).toMatchObject({ truncated: false, missingGroup: false });
expect(rest.layers.map((layer) => named(layer.handle))).toEqual([
`t${MAX_QUERY_MATCHES}`,
`t${MAX_QUERY_MATCHES + 1}`,
`t${MAX_QUERY_MATCHES + 2}`,
]);
const last = layersOf(undefined, MAX_QUERY_MATCHES + 2).layers;
expect(last.map((layer) => named(layer.handle))).toEqual([`t${MAX_QUERY_MATCHES + 2}`]);
}, 20_000);
it("lists nothing for a group this page no longer has, and says so", () => {
document.body.innerHTML = `<main data-composition-id="m"><div id="pair" data-hf-group="g"><i id="a"></i></div></main>`;
const pair = layersOf().layers[0]!.handle;
document.getElementById("pair")!.remove();
expect(layersOf(pair)).toEqual({ layers: [], truncated: false, missingGroup: true });
expect(layersOf("0123456789abcdef:1")).toMatchObject({ layers: [], missingGroup: true });
});
});
+115
View File
@@ -0,0 +1,115 @@
/** The Layers walk `layers` answers; Studio walks a frame it scripts by the same rules. */
import { isRichTextFormattingTag } from "../utils/richTextSanitize";
import { isClipHiddenByRuntime } from "../studioPreviewMark";
import { MAX_QUERY_MATCHES, type EditingElementHandle } from "./editingElement";
import { elementForHandle, handleFor } from "./editingHandles";
import { isDomLayerElement } from "./editingTargets";
import { isElementNode } from "./domRealm";
export type LayerKind = "image" | "video" | "audio" | "vector" | "group" | "text" | "shape";
export interface EditingLayer {
handle: EditingElementHandle;
depth: number;
childCount: number;
zIndex: number;
kind: LayerKind;
}
export function isCompositionHost(el: Element): boolean {
return el.hasAttribute("data-composition-src") || el.hasAttribute("data-composition-file");
}
export function hasOnlyFormattingChildren(element: HTMLElement): boolean {
for (const child of Array.from(element.children)) {
if (!isRichTextFormattingTag(child.tagName)) return false;
if (child.namespaceURI !== "http://www.w3.org/1999/xhtml") return false;
// Formatting nests, and a structural child hidden inside a span is still structural.
if (!hasOnlyFormattingChildren(child as HTMLElement)) return false;
}
return true;
}
/** What a Layers row tells a person an element is: its media tag, a group, text, or else a shape. */
export function layerKindOf(el: Element, hasChildren: boolean): LayerKind {
const tag = el.tagName.toLowerCase();
if (tag === "img" || tag === "picture") return "image";
if (tag === "video") return "video";
if (tag === "audio") return "audio";
if (tag === "svg") return "vector";
if (el.hasAttribute("data-hf-group") || isCompositionHost(el)) return "group";
if (hasOnlyFormattingChildren(el as HTMLElement) && el.textContent?.trim()) return "text";
return hasChildren ? "group" : "shape";
}
/** The inline `z-index`, else the computed one; 0 for `auto` or none. */
export function elementZIndex(element: HTMLElement): number {
const inline = element.style?.zIndex;
if (inline && inline !== "auto") {
const parsed = parseInt(inline, 10);
if (Number.isFinite(parsed)) return parsed;
}
const value = element.ownerDocument?.defaultView?.getComputedStyle(element).zIndex;
if (!value || value === "auto") return 0;
const parsed = parseInt(value, 10);
return Number.isFinite(parsed) ? parsed : 0;
}
const layerChildren = (el: Element) =>
Array.from(el.children).filter(
(child) => isElementNode(child) && isDomLayerElement(child as HTMLElement),
).length;
/** Every layer under `roots`, in document order, with its depth among layers. */
function walkLayers(
roots: readonly Element[],
max = Number.POSITIVE_INFINITY,
): {
layers: Array<{ element: HTMLElement; depth: number; childCount: number }>;
truncated: boolean;
} {
const layers: Array<{ element: HTMLElement; depth: number; childCount: number }> = [];
let truncated = false;
const visit = (el: HTMLElement, depth: number) => {
if (truncated || isClipHiddenByRuntime(el)) return;
const layer = isDomLayerElement(el);
if (layer) {
if (layers.length === max) {
truncated = true;
return;
}
layers.push({ element: el, depth, childCount: layerChildren(el) });
}
for (const child of Array.from(el.children)) {
if (isElementNode(child)) visit(child as HTMLElement, layer ? depth + 1 : depth);
}
};
for (const root of roots) if (isElementNode(root)) visit(root as HTMLElement, 0);
return { layers, truncated };
}
/**
* `layers`: the composition's layers, or the drilled-into group's when `group` names one, from the
* `offset`th on. A `group` this page no longer has lists nothing, so Studio can leave the drill-in.
*/
export function layersOf(
group?: EditingElementHandle,
offset = 0,
): { layers: EditingLayer[]; truncated: boolean; missingGroup: boolean } {
const scope = group ? elementForHandle(group) : null;
if (group && !scope) return { layers: [], truncated: false, missingGroup: true };
const root = document.querySelector("[data-composition-id]") ?? document.documentElement;
const roots = scope ? Array.from(scope.children) : root ? [root] : [];
const walk = walkLayers(roots, offset + MAX_QUERY_MATCHES);
return {
truncated: walk.truncated,
missingGroup: false,
layers: walk.layers.slice(offset).map(({ element, depth, childCount }) => ({
handle: handleFor(element),
depth,
childCount,
zIndex: elementZIndex(element),
kind: layerKindOf(element, childCount > 0),
})),
};
}
@@ -72,6 +72,7 @@ describe("createEditingPortClient", () => {
"ancestors",
"query",
"geometry",
"layers",
],
});
} finally {
+32
View File
@@ -18,6 +18,7 @@ import {
type EditingElementMatch,
} from "./editingElement";
import type { EditingElementBox, EditingElementGeometry } from "./editingGeometry";
import type { EditingLayer } from "./editingLayers";
import type { RuntimeTimelineMessage } from "./types";
import { wallClearTimeout, wallSetTimeout } from "./wallClock";
@@ -66,6 +67,14 @@ export {
type EditingLocalPointer,
type EditingViewport,
} from "./editingTargets";
export {
elementZIndex,
hasOnlyFormattingChildren,
isCompositionHost,
layerKindOf,
type EditingLayer,
type LayerKind,
} from "./editingLayers";
export {
composeElementTransform,
individualRotateDegrees,
@@ -90,6 +99,7 @@ export const EDITING_REQUEST_KINDS = [
"ancestors",
"query",
"geometry",
"layers",
] as const;
export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number];
@@ -153,6 +163,12 @@ export interface EditingRequests {
children: EditingElementBox[] | null;
};
};
/** The Layers walk from `offset`, MAX_QUERY_MATCHES at a time, scoped to a drilled-into `group`;
* `missingGroup` says this page has no such group, and lists nothing. */
layers: {
params: { group?: EditingElementHandle; offset?: number };
result: { layers: EditingLayer[]; truncated: boolean; missingGroup: boolean };
};
}
export type EditingParams<K extends EditingRequestKind> = EditingRequests[K]["params"];
export type EditingResult<K extends EditingRequestKind> = EditingRequests[K]["result"];
@@ -230,6 +246,21 @@ function point(params: unknown): { x: number; y: number } | null {
return Number.isFinite(x) && Number.isFinite(y) ? { x: x as number, y: y as number } : null;
}
const isOffset = (value: unknown): value is number =>
Number.isSafeInteger(value) && (value as number) >= 0;
function layerParams(params: unknown): EditingParams<"layers"> | null {
if (!isPlainRecord(params)) return null;
const { group, offset, ...rest } = params;
const valid = [
Object.keys(rest).length === 0,
group === undefined || isHandle(group),
offset === undefined || isOffset(offset),
];
if (valid.includes(false)) return null;
return { ...(isHandle(group) && { group }), ...(isOffset(offset) && { offset }) };
}
const PARAM_PARSERS: {
[K in EditingRequestKind]: (params: unknown) => EditingParams<K> | null;
} = {
@@ -265,6 +296,7 @@ const PARAM_PARSERS: {
if (!list || !("children" in params)) return list;
return isHandle(children) ? { ...list, children } : null;
},
layers: (params) => noParams(params) ?? layerParams(params),
};
/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */
@@ -1,5 +1,6 @@
import { afterEach, describe, expect, it } from "vitest";
import { MAX_POINT_STACK } from "./editingElement";
import { elementForHandle } from "./editingHandles";
import { pointerTargetsAt } from "./editingTargets";
function sized(element: Element, [x, y, width, height]: number[]) {
@@ -36,6 +37,19 @@ describe("pointer-targets", () => {
expect(asked[0]).toEqual([480, 540]);
expect(answer.target).toMatchObject({ tag: "p", rect: { x: 10, y: 20, width: 300 } });
expect(answer.stack.map((hit) => hit.handle)).toEqual([answer.target!.handle]);
expect(asked).toHaveLength(1);
});
it("reads the stack once, and falls back to a group's gap only when it is empty", () => {
document.body.innerHTML = `<main data-composition-id="m"><div id="g" data-hf-group="g"><i id="a"></i><i id="b"></i></div></main>`;
sized(document.querySelector("main")!, [0, 0, 1920, 1080]);
sized(document.getElementById("a")!, [0, 0, 100, 100]);
sized(document.getElementById("b")!, [400, 400, 100, 100]);
stackAt([]);
const answer = pointerTargetsAt(0.1, 0.2);
expect(asked).toHaveLength(1);
expect(answer.stack).toEqual([]);
expect(elementForHandle(answer.target!.handle)).toBe(document.getElementById("g"));
});
it("caps the stack, and answers nothing when the composition has no size", () => {
+10 -3
View File
@@ -269,7 +269,10 @@ export function pointerTarget(doc: Document, point: EditingLocalPointer): HTMLEl
const visualTarget = candidates.find((el) => !isFullBleedTarget(el, point.viewport)) ?? null;
if (visualTarget) return visualTarget;
}
return pointerFallbackTarget(doc, point);
}
function pointerFallbackTarget(doc: Document, point: EditingLocalPointer): HTMLElement | null {
const groupHit = findGroupAtPoint(doc, point.x, point.y);
if (groupHit && !hasAuthorPointerEventsNone(groupHit) && isDomLayerElement(groupHit))
return groupHit;
@@ -316,7 +319,11 @@ export function pointerTargetsAt(
): { target: EditingElementHit | null; stack: EditingElementHit[] } {
const point = compositionPoint(document, x, y);
if (!point) return { target: null, stack: [] };
const target = pointerTarget(document, point);
const stack = pointerTargets(document, point).slice(0, MAX_POINT_STACK);
return { target: target && elementHit(target), stack: stack.map(elementHit) };
const stack = pointerTargets(document, point);
const visual = typeof document.elementsFromPoint === "function" ? stack[0] : undefined;
const target = visual ?? pointerFallbackTarget(document, point);
return {
target: target && elementHit(target),
stack: stack.slice(0, MAX_POINT_STACK).map(elementHit),
};
}
@@ -0,0 +1,176 @@
// @vitest-environment happy-dom
import { act, createElement } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, expect, it, vi } from "vitest";
// The frame's real runtime agent, serving the opaque frame from this document.
import { installEditingAgent } from "../../../../core/src/runtime/editingAgent";
import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
import { detachedFakeIframe } from "../../player/hooks/timelinePlayerTestHarness";
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
import type { DomEditSelection } from "./domEditing";
import { LayersPanel } from "./LayersPanel";
import { announcePreviewDocumentLoaded } from "../../player/sceneSwap";
import { describePreviewElements, queryPreviewElements } from "../../player/lib/previewElements";
import { standInFor } from "./previewSelection";
installReactActEnvironment();
const mocks = vi.hoisted(() => ({
previewIframeRef: { current: null } as { current: unknown },
activeGroupElement: null as HTMLElement | null,
applyDomSelection: vi.fn(),
setActiveGroupElement: vi.fn(),
// While set, a layers read waits on it after the frame answers.
hold: null as Promise<void> | null,
answered: 0,
}));
vi.mock("../../player/lib/previewElements", async (importOriginal) => {
const actual = await importOriginal<typeof import("../../player/lib/previewElements")>();
return {
...actual,
previewLayers: async (...args: Parameters<typeof actual.previewLayers>) => {
const reply = await actual.previewLayers(...args);
mocks.answered += 1;
await mocks.hold;
return reply;
},
};
});
vi.mock("../../contexts/StudioContext", () => ({
useStudioShellContextOptional: () => ({
previewIframeRef: mocks.previewIframeRef,
activeCompPath: "index.html",
showToast: vi.fn(),
}),
useStudioPlaybackContextOptional: () => ({
refreshKey: 0,
compositionLoading: false,
timelineElements: [],
isPlaying: false,
}),
}));
vi.mock("../../contexts/DomEditContext", () => ({
useDomEditContext: () => ({
domEditSelection: null,
activeGroupElement: mocks.activeGroupElement,
applyDomSelection: mocks.applyDomSelection,
updateDomEditHoverSelection: vi.fn(),
handleDomZIndexReorderCommit: vi.fn(),
setActiveGroupElement: mocks.setActiveGroupElement,
}),
}));
vi.mock("../nle/useCanvasZOrderTimelineMirror", () => ({
useLayerReorderTimelineMirror: () => vi.fn(),
}));
const closers: Array<() => void> = [];
afterEach(() => {
closers.splice(0).forEach((close) => close());
mocks.activeGroupElement = null;
mocks.hold = null;
mocks.answered = 0;
vi.clearAllMocks();
usePreviewIframeStore.setState({ iframe: null });
document.body.innerHTML = "";
});
/** A frame Studio cannot read, whose runtime is the real editing agent over this document. */
function opaqueFrame() {
const frame: Record<string, unknown> = {};
const iframe = detachedFakeIframe(frame);
Object.defineProperty(iframe, "contentDocument", { value: null });
Object.defineProperty(frame, "document", {
get: () => {
throw new DOMException("blocked", "SecurityError");
},
});
const parent = {
postMessage: (data: unknown, _origin: string, ports: MessagePort[]) =>
window.dispatchEvent(
new MessageEvent("message", { source: frame as unknown as Window, data, ports }),
),
} as unknown as Window;
const agent = installEditingAgent(parent);
frame.postMessage = (data: unknown) =>
window.dispatchEvent(new MessageEvent("message", { source: parent, data }));
closers.push(() => agent.dispose());
return iframe;
}
it("lists an opaque frame's layers, selects a row, and drills into a group row", async () => {
document.body.innerHTML = `<main data-composition-id="main">
<div id="card"><h1 id="title">Hi</h1></div>
<div id="pair" data-hf-group="pair"><i id="a"></i></div>
<div id="host" data-composition-src="compositions/intro-card.html"></div></main>`;
const iframe = opaqueFrame();
mocks.previewIframeRef.current = iframe;
usePreviewIframeStore.setState({ iframe });
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
act(() => root.render(createElement(LayersPanel)));
closers.push(() => act(() => root.unmount()));
const rows = () => [...host.querySelectorAll<HTMLElement>("[data-layer-index]")];
await vi.waitFor(() => expect(rows()).toHaveLength(5));
const named = (label: string) => rows().find((r) => r.textContent?.includes(label))!;
expect(named("Title").querySelector("[data-layer-kind]")!.getAttribute("data-layer-kind")).toBe(
"text",
);
expect(named("pair").title).toBe("This layer can't be reordered");
const hostIcon = named("Intro").querySelector("[data-layer-kind]")!;
expect(hostIcon.className).toContain("bg-on");
act(() => named("Title").click());
await vi.waitFor(() => expect(mocks.applyDomSelection).toHaveBeenCalled());
const picked = mocks.applyDomSelection.mock.calls[0]![0] as DomEditSelection;
expect(picked).toMatchObject({ id: "title", selector: "#title" });
expect(picked.handle).toBeTruthy();
act(() => void named("pair").dispatchEvent(new MouseEvent("dblclick", { bubbles: true })));
await vi.waitFor(() => expect(mocks.setActiveGroupElement).toHaveBeenCalledOnce());
const group = mocks.setActiveGroupElement.mock.calls[0]![0] as HTMLElement;
expect(group.hasAttribute("data-hf-group")).toBe(false);
});
function renderPanel(iframe: HTMLIFrameElement) {
mocks.previewIframeRef.current = iframe;
usePreviewIframeStore.setState({ iframe });
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
act(() => root.render(createElement(LayersPanel)));
closers.push(() => act(() => root.unmount()));
return () =>
[...host.querySelectorAll<HTMLElement>("[data-layer-index]")].map((r) => r.textContent);
}
it("leaves a drill-in whose group a reload took, rather than list the whole page under it", async () => {
document.body.innerHTML = `<main data-composition-id="main">
<div id="card"></div><div id="pair" data-hf-group="pair"><i id="a"></i></div></main>`;
const iframe = opaqueFrame();
const [pair] = (await queryPreviewElements(iframe, "#pair"))!.matches;
const [described] = (await describePreviewElements(iframe, [pair!.handle]))!;
mocks.activeGroupElement = standInFor(iframe, described!);
document.getElementById("pair")!.remove();
const rows = renderPanel(iframe);
await vi.waitFor(() => expect(mocks.setActiveGroupElement).toHaveBeenCalledWith(null));
expect(rows()).toEqual([]);
});
it("reads the layers once more when a refresh lands while a read is in flight", async () => {
document.body.innerHTML = `<main data-composition-id="main"><div id="card"></div></main>`;
let release!: () => void;
mocks.hold = new Promise<void>((resolve) => (release = resolve));
const iframe = opaqueFrame();
const rows = renderPanel(iframe);
await vi.waitFor(() => expect(mocks.answered).toBe(1));
// Past the panel's settle timer, so only the announced refresh can bring the new layer.
await new Promise((resolve) => setTimeout(resolve, 150));
// The first read has its answer and is waiting; the page changes and announces it.
document.querySelector("main")!.insertAdjacentHTML("beforeend", `<div id="late"></div>`);
act(() => announcePreviewDocumentLoaded(iframe));
act(() => release());
await vi.waitFor(() => expect(rows()).toEqual(["Late", "Card"]));
});
@@ -40,6 +40,10 @@ import { zReorderCoalesceKey } from "../../hooks/useElementLifecycleOps";
import { useLayerReorderTimelineMirror } from "../nle/useCanvasZOrderTimelineMirror";
import { runZLaneGesture } from "../nle/zLaneGesture";
import { useLayerRevealOverride } from "./useLayerRevealOverride";
import { previewFrameOpaque } from "../../player/lib/previewChannel";
import { describePreviewElements } from "../../player/lib/previewElements";
import { collectPreviewLayerItems, layerDataAttribute } from "./previewLayers";
import { resolvePreviewSelection, selectionDataAttribute } from "./previewSelection";
// Rows this panel renders before it stops. A display budget, not a document limit.
const LAYERS_PANEL_MAX_ROWS = 80;
@@ -146,9 +150,26 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
const isMasterView = !activeCompPath || activeCompPath === "index.html";
const livePreviewIframe = useLivePreviewIframe();
// The opaque read in flight; `again` holds a refresh that arrived meanwhile, run once it settles.
const opaqueRead = useRef<{ again: boolean } | null>(null);
const collectLayers = useCallback(() => {
const iframe = previewIframeRef.current;
if (!iframe) return;
if (previewFrameOpaque(iframe)) {
if (opaqueRead.current) return void (opaqueRead.current.again = true);
const read = { again: false };
opaqueRead.current = read;
const scope = { activeCompositionPath: activeCompPath, activeGroupElement };
void collectPreviewLayerItems(iframe, scope, LAYERS_PANEL_MAX_ROWS).then((reply) => {
if (opaqueRead.current !== read) return;
opaqueRead.current = null;
// A reload took the drilled-into group; leave it as same-origin does below.
if (reply?.missingGroup) return setActiveGroupElement(null);
if (reply) setLayers(sortLayersByZIndex(reply.items));
if (read.again) collectLayers();
});
return;
}
let doc: Document | null = null;
try {
doc = iframe.contentDocument;
@@ -175,6 +196,7 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
}, [previewIframeRef, activeCompPath, isMasterView, activeGroupElement, setActiveGroupElement]);
useEffect(() => {
opaqueRead.current = null;
collectLayers();
}, [collectLayers, refreshKey, zEditVersion, livePreviewIframe]);
@@ -210,15 +232,20 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
}, [collectLayers]);
const resolveSelection = useCallback(
(layer: DomEditLayerItem) => {
const doc = previewIframeRef.current?.contentDocument;
const el = liveLayerElement(layer, doc, activeCompPath);
return resolveDomEditSelection(el, {
async (layer: DomEditLayerItem) => {
const iframe = previewIframeRef.current;
const options = {
activeCompositionPath: activeCompPath,
isMasterView,
preferClipAncestor: false,
activeGroupElement,
});
};
if (layer.preview && iframe) {
const [described] = (await describePreviewElements(iframe, [layer.preview.handle])) ?? [];
return described ? resolvePreviewSelection(iframe, described, options) : null;
}
const el = liveLayerElement(layer, iframe?.contentDocument, activeCompPath);
return resolveDomEditSelection(el, options);
},
[activeCompPath, isMasterView, previewIframeRef, activeGroupElement],
);
@@ -228,7 +255,8 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
const selection = await resolveSelection(layer);
if (!selection) return;
let matchedId = findMatchingTimelineElementId(selection, timelineElements);
const scope = activeCompPath || "index.html";
let matchedId = findMatchingTimelineElementId(selection, timelineElements, scope);
if (!matchedId) {
const sourceFile = selection.sourceFile ?? "index.html";
@@ -253,7 +281,7 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
}
}
},
[currentTime, resolveSelection, timelineElements],
[activeCompPath, currentTime, resolveSelection, timelineElements],
);
const handleSelectLayer = useCallback(
@@ -275,7 +303,7 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
const handleLayerDoubleClick = useCallback(
async (layer: DomEditLayerItem) => {
const selection = await resolveSelection(layer);
if (selection?.element.hasAttribute("data-hf-group")) {
if (selection && selectionDataAttribute(selection, "data-hf-group") !== null) {
setActiveGroupElement(selection.element);
} else {
await handleSelectLayer(layer);
@@ -456,8 +484,11 @@ export const LayersPanel = memo(function LayersPanel({ host }: { host?: LayersPa
const draggable = isLayerDraggable(layer);
const isCollapsed = collapsed[layer.key] ?? false;
const hasChildren = layer.childCount > 0;
const isCompHost = isCompositionHost(layer.element);
const kind = layerKindOf(layer.element, hasChildren);
const isCompHost = layer.preview
? layerDataAttribute(layer, "data-composition-src") !== null ||
layerDataAttribute(layer, "data-composition-file") !== null
: isCompositionHost(layer.element);
const kind = layer.preview?.kind ?? layerKindOf(layer.element, hasChildren);
const KindIcon = KIND_ICON[kind];
const kindName = kind[0].toUpperCase() + kind.slice(1);
const hint = draggable
@@ -1,4 +1,4 @@
import { isRichTextFormattingTag } from "@hyperframes/core/rich-text-sanitize";
import { hasOnlyFormattingChildren } from "@hyperframes/core/runtime/editing-port";
import type { DomEditSelection } from "./domEditingTypes";
import { isTextEditableSelection } from "./domEditingLayers";
@@ -53,21 +53,6 @@ export function canEditElementTextInline(element: HTMLElement | null): boolean {
return (element.textContent ?? "").trim().length > 0;
}
export function hasOnlyFormattingChildren(element: HTMLElement): boolean {
for (const child of Array.from(element.children)) {
if (!isRichTextFormattingTag(child.tagName)) return false;
if (!isHtmlFromAnyWindow(child)) return false;
// Formatting nests, and a structural child hidden inside a span is still
// structural.
if (!hasOnlyFormattingChildren(child as HTMLElement)) return false;
}
return true;
}
function isHtmlFromAnyWindow(node: Element): boolean {
return node.namespaceURI === "http://www.w3.org/1999/xhtml";
}
/** Where and when a press landed, for recognising the next one as a pair. */
export interface PressMark {
x: number;
@@ -1,6 +1,6 @@
import type { PatchTarget } from "../../utils/sourcePatcher";
import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
import type { EditingElementHandle } from "@hyperframes/core/runtime/editing-port";
import type { EditingElementHandle, LayerKind } from "@hyperframes/core/runtime/editing-port";
export const CURATED_STYLE_PROPERTIES = [
"position",
@@ -112,6 +112,12 @@ export interface DomEditLayerItem {
selector?: string;
selectorIndex?: number;
sourceFile: string;
preview?: {
handle: string;
zIndex: number;
kind: LayerKind;
dataAttributes: Record<string, string>;
};
}
export interface DomEditContextOptions {
@@ -1,19 +1,2 @@
import { hasOnlyFormattingChildren } from "./domEditInlineText";
export type LayerKind = "image" | "video" | "audio" | "vector" | "group" | "text" | "shape";
export function isCompositionHost(el: Element): boolean {
return el.hasAttribute("data-composition-src") || el.hasAttribute("data-composition-file");
}
/** What a Layers row tells a person an element is: its media tag, a group, text, or else a shape. */
export function layerKindOf(el: Element, hasChildren: boolean): LayerKind {
const tag = el.tagName.toLowerCase();
if (tag === "img" || tag === "picture") return "image";
if (tag === "video") return "video";
if (tag === "audio") return "audio";
if (tag === "svg") return "vector";
if (el.hasAttribute("data-hf-group") || isCompositionHost(el)) return "group";
if (hasOnlyFormattingChildren(el as HTMLElement) && el.textContent?.trim()) return "text";
return hasChildren ? "group" : "shape";
}
// One kind rule for Studio's Layers rows and the runtime that lists an opaque frame's layers.
export { isCompositionHost, layerKindOf } from "@hyperframes/core/runtime/editing-port";
@@ -40,8 +40,8 @@ export function sortLayersByZIndex(layers: DomEditLayerItem[]): DomEditLayerItem
}
chunks.sort((a, b) => {
const zA = getElementZIndex(a.root.element);
const zB = getElementZIndex(b.root.element);
const zA = a.root.preview?.zIndex ?? getElementZIndex(a.root.element);
const zB = b.root.preview?.zIndex ?? getElementZIndex(b.root.element);
if (zA !== zB) return zB - zA;
return b.domIndex - a.domIndex;
});
@@ -16,6 +16,12 @@ import {
} from "../../utils/marqueeGeometry";
import { toVisibleOverlayRect } from "./domEditOverlayGeometry";
import { movesGesture } from "./domEditOverlayGestures";
import { previewFrameOpaque } from "../../player/lib/previewChannel";
import {
collectPreviewMarqueeCandidates,
resolvePreviewMarqueeHits,
type PreviewMarqueeHit,
} from "./previewLayers";
interface MarqueeState {
startX: number;
@@ -42,6 +48,7 @@ const MARQUEE_THRESHOLD_PX = 4;
interface MarqueeHit {
element: HTMLElement;
rect: Rect;
description?: PreviewMarqueeHit["description"];
}
/**
@@ -118,6 +125,25 @@ async function resolveDomEditSelections(
return hits;
}
/** The band's candidates: an opaque frame's are measured over its channel, once per band. */
function bandCandidates(
iframe: HTMLIFrameElement,
overlay: HTMLDivElement,
acp: string,
measured: { cached: MarqueeHit[] | null; measuring: Promise<MarqueeHit[]> | null },
): MarqueeHit[] | Promise<MarqueeHit[]> {
if (!previewFrameOpaque(iframe))
return currentMarqueeCandidates(measured.cached, iframe, overlay, acp);
return measured.measuring ?? collectPreviewMarqueeCandidates(iframe, overlay);
}
/** Studio's edit selections for the hits; an opaque frame's are read from their descriptions. */
function resolveMarqueeHits(iframe: HTMLIFrameElement, hits: MarqueeHit[], acp: string) {
const elements = hits.map((hit) => hit.element);
if (!previewFrameOpaque(iframe)) return resolveDomEditSelections(elements, acp);
return resolvePreviewMarqueeHits(iframe, hits as PreviewMarqueeHit[], acp);
}
export interface MarqueeGesturesDeps<T = DomEditSelection> {
iframeRef: React.RefObject<HTMLIFrameElement | null>;
overlayRef: React.RefObject<HTMLDivElement | null>;
@@ -176,6 +202,8 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
const [candidateRects, setCandidateRects] = useState<Rect[]>([]);
// Measured once when the drag passes the threshold and reused until it ends.
const candidatesRef = useRef<MarqueeHit[] | null>(null);
const opaqueCandidatesRef = useRef<Promise<MarqueeHit[]> | null>(null);
const bandRef = useRef<{ rect: Rect; mode: MarqueeSelectionMode } | null>(null);
const commitMarquee = useCallback(
async (rect: Rect, mode: MarqueeSelectionMode) => {
@@ -183,12 +211,12 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
const overlay = deps.overlayRef.current;
if (!iframe || !overlay || !deps.onMarqueeSelectRef.current) return;
const acp = deps.activeCompositionPathRef.current ?? "index.html";
const candidates = currentMarqueeCandidates(candidatesRef.current, iframe, overlay, acp);
const elements = hitsWithin(rect, candidates).map((hit) => hit.element);
const measured = { cached: candidatesRef.current, measuring: opaqueCandidatesRef.current };
const hits = hitsWithin(rect, await bandCandidates(iframe, overlay, acp, measured));
const resolveHits = deps.resolveHits;
const picks = resolveHits
? await resolveHits(elements)
: ((await resolveDomEditSelections(elements, acp)) as T[]);
? await resolveHits(hits.map((hit) => hit.element))
: ((await resolveMarqueeHits(iframe, hits, acp)) as T[]);
const applySelection = deps.onMarqueeSelectRef.current;
if (!applySelection) return;
const result = applySelection(picks, mode);
@@ -208,6 +236,8 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
setMarqueeRect(null);
setCandidateRects([]);
candidatesRef.current = null;
opaqueCandidatesRef.current = null;
bandRef.current = null;
}, []);
const begin = useCallback(
@@ -261,6 +291,18 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
const overlay = deps.overlayRef.current;
if (!iframe || !overlay) return;
const acp = deps.activeCompositionPathRef.current ?? "index.html";
bandRef.current = { rect, mode };
if (!candidatesRef.current && previewFrameOpaque(iframe)) {
if (opaqueCandidatesRef.current) return;
const measuring = collectPreviewMarqueeCandidates(iframe, overlay);
opaqueCandidatesRef.current = measuring;
void measuring.then((hits) => {
if (opaqueCandidatesRef.current !== measuring || !bandRef.current) return;
candidatesRef.current = hits;
showCandidates(bandRef.current.rect, bandRef.current.mode);
});
return;
}
candidatesRef.current ??= collectMarqueeCandidates(iframe, overlay, acp);
let hits = hitsWithin(rect, candidatesRef.current);
if (mode === "subtract") hits = hits.filter((h) => isSelectedElement(h.element));
@@ -284,6 +326,7 @@ export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGest
if (Math.hypot(dx, dy) < MARQUEE_THRESHOLD_PX) return;
m.pastThreshold = true;
candidatesRef.current = null;
opaqueCandidatesRef.current = null;
}
const rect: Rect = {
left: Math.min(m.startX, m.currentX),
@@ -0,0 +1,308 @@
// @vitest-environment happy-dom
import { act, createElement, useRef } from "react";
import { MAX_QUERY_MATCHES } from "@hyperframes/core/runtime/editing-port";
import { createRoot } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
// The frame's real runtime agent, serving the opaque frame from this document.
import { installEditingAgent } from "../../../../core/src/runtime/editingAgent";
import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
import { watchPreviewFrame } from "../../player/lib/bridgePlayback";
import { getElementZIndex } from "../../player/lib/layerOrdering";
import { detachedFakeIframe } from "../../player/hooks/timelinePlayerTestHarness";
import { previewLayers } from "../../player/lib/previewElements";
import type { TimelineElement } from "../../player";
import { findMatchingTimelineElementId } from "../../utils/studioHelpers";
import { collectDomEditLayerItems, type DomEditSelection } from "./domEditing";
import type { DomEditLayerItem } from "./domEditingTypes";
import { layerKindOf } from "./layerKind";
import { sortLayersByZIndex } from "./layersPanelSort";
import { useMarqueeGestures } from "./marqueeCommit";
import { collectPreviewLayerItems, layerDataAttribute } from "./previewLayers";
import { findPreviewElementForSelection, resolvePreviewSelection } from "./previewSelection";
import { isLayerDraggable } from "./useLayerDrag";
installReactActEnvironment();
HTMLElement.prototype.setPointerCapture ??= () => {};
HTMLElement.prototype.releasePointerCapture ??= () => {};
const FIXTURE = `
<main data-composition-id="main" data-width="1920" data-height="1080">
<div id="card" class="clip" style="z-index: 4"><h1 id="title">Launch <b>day</b></h1><img id="pic"></div>
<div id="pair" data-hf-group="pair"><i id="a"></i><i data-hf-id="b-hf"></i></div>
<div id="parked" data-hf-clip-hidden style="visibility: hidden"><p id="inside" style="visibility: visible">x</p></div>
<div id="cropped" style="clip-path: inset(0 0 0 200px); background: red"></div>
<div id="host" data-composition-src="compositions/a.html"><span id="in-host">in</span></div>
<i class="tile"></i><i class="tile" id="t2"></i>
<div id="backdrop" style="background: #111"></div>
<div id="faded" style="opacity: 0"></div>
</main>`;
const RECTS: Record<string, number[]> = {
card: [100, 100, 400, 300],
title: [110, 110, 300, 60],
pic: [110, 200, 200, 150],
pair: [600, 100, 10, 10],
a: [600, 100, 80, 80],
"b-hf": [700, 140, 80, 80],
host: [900, 500, 300, 200],
"in-host": [910, 510, 100, 20],
t2: [1300, 800, 50, 50],
backdrop: [0, 0, 1920, 1080],
faded: [120, 120, 50, 50],
cropped: [700, 300, 400, 60],
};
const FRAME = [100, 50, 960, 540];
function sized(element: Element, [x, y, width, height]: number[]) {
element.getBoundingClientRect = () =>
({ x, y, width, height, left: x, top: y, right: x + width, bottom: y + height }) as DOMRect;
Object.defineProperty(element, "offsetWidth", { value: width, configurable: true });
Object.defineProperty(element, "offsetHeight", { value: height, configurable: true });
return element;
}
const byName = (name: string) =>
document.getElementById(name) ?? document.querySelector(`[data-hf-id="${name}"]`);
const closers: Array<() => void> = [];
beforeEach(() => {
document.body.innerHTML = FIXTURE;
sized(document.querySelector("main")!, [0, 0, 1920, 1080]);
for (const [name, rect] of Object.entries(RECTS)) sized(byName(name)!, rect);
});
afterEach(() => {
closers.splice(0).forEach((close) => close());
document.body.innerHTML = "";
});
/** A frame Studio scripts directly; its document is this one. */
function liveFrame() {
const iframe = detachedFakeIframe(window as unknown as Record<string, unknown>);
Object.defineProperty(iframe, "contentDocument", { value: document });
return sized(iframe, FRAME) as HTMLIFrameElement;
}
/** A frame Studio cannot read, whose runtime is the real editing agent over this document. */
function opaqueFrame() {
const frame: Record<string, unknown> = {};
const iframe = sized(detachedFakeIframe(frame), FRAME) as HTMLIFrameElement;
Object.defineProperty(iframe, "contentDocument", { value: null });
Object.defineProperty(frame, "document", {
get: () => {
throw new DOMException("blocked", "SecurityError");
},
});
const parent = {
postMessage: (data: unknown, _origin: string, ports: MessagePort[]) =>
window.dispatchEvent(
new MessageEvent("message", { source: frame as unknown as Window, data, ports }),
),
} as unknown as Window;
const agent = installEditingAgent(parent);
frame.postMessage = (data: unknown) =>
window.dispatchEvent(new MessageEvent("message", { source: parent, data }));
closers.push(() => agent.dispose());
watchPreviewFrame(iframe);
window.dispatchEvent(
new MessageEvent("message", {
source: frame as unknown as Window,
origin: window.location.origin,
data: { source: "hf-preview", type: "stage-size", width: 1920, height: 1080 },
}),
);
return iframe;
}
const CONTEXT = { activeCompositionPath: "index.html", isMasterView: true };
const row = ({ element: _e, preview: _p, ...rest }: DomEditLayerItem) => rest;
describe("Layers rows on an opaque frame match same-origin ones", () => {
it("lists the same rows, with the kind and z-index each row shows", async () => {
const live = collectDomEditLayerItems(document.querySelector("main"), CONTEXT);
const remote = (await collectPreviewLayerItems(opaqueFrame(), CONTEXT))!.items;
expect(remote.map(row)).toEqual(live.map(row));
expect(remote.map((item) => item.preview!.kind)).toEqual(
live.map((item) => layerKindOf(item.element, item.childCount > 0)),
);
expect(remote.map((item) => item.preview!.zIndex)).toEqual(
live.map((item) => getElementZIndex(item.element)),
);
expect(remote.map((item) => item.label)).toContain("pair");
expect(sortLayersByZIndex(remote)[0]!.id).toBe("card");
});
it("scopes to a drilled-into group's stand-in, and stops at the row budget", async () => {
const opaque = opaqueFrame();
const found = await findPreviewElementForSelection(opaque, { id: "pair" }, "index.html");
const group = (await resolvePreviewSelection(opaque, found!, {
...CONTEXT,
exactTarget: true,
}))!;
const scoped = { ...CONTEXT, activeGroupElement: group.element };
const live = collectDomEditLayerItems(document.querySelector("main"), {
...CONTEXT,
activeGroupElement: document.getElementById("pair"),
});
const inGroup = (await collectPreviewLayerItems(opaque, scoped))!;
expect(inGroup.items.map(row)).toEqual(live.map(row));
expect(inGroup.missingGroup).toBe(false);
expect((await collectPreviewLayerItems(opaque, CONTEXT, 2))!.items).toHaveLength(2);
// A reload takes the group with it: the frame lists nothing and says so, not the whole page.
document.getElementById("pair")!.remove();
expect(await collectPreviewLayerItems(opaque, scoped)).toEqual({
items: [],
missingGroup: true,
});
});
it("reads a row's attributes off its description, and does not offer it for reordering", async () => {
const remote = (await collectPreviewLayerItems(opaqueFrame(), CONTEXT))!.items;
const pair = remote.find((item) => item.id === "pair")!;
expect(layerDataAttribute(pair, "data-hf-group")).toBe("pair");
expect(pair.element.hasAttribute("data-hf-group")).toBe(false);
const host = remote.find((item) => item.id === "host")!;
expect(layerDataAttribute(host, "data-composition-src")).toBe("compositions/a.html");
expect(isLayerDraggable(pair)).toBe(false);
});
});
describe("a marquee on an opaque frame matches a same-origin one", () => {
function band(iframe: HTMLIFrameElement) {
const picked: { selections: DomEditSelection[] | null; candidates: number } = {
selections: null,
candidates: 0,
};
function Surface() {
const overlayRef = useRef<HTMLDivElement>(null);
const marquee = useMarqueeGestures({
iframeRef: { current: iframe },
overlayRef,
activeCompositionPathRef: { current: "index.html" },
onMarqueeSelectRef: { current: (selections) => void (picked.selections = selections) },
});
picked.candidates = marquee.candidateRects.length;
return createElement("div", {
ref: (el: HTMLDivElement | null) => {
if (el) overlayRef.current = sized(el, [20, 10, 1200, 800]) as HTMLDivElement;
},
"data-band": "",
onPointerDown: marquee.begin,
onPointerMove: marquee.onPointerMove,
onPointerUp: marquee.onPointerUp,
});
}
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
act(() => root.render(createElement(Surface)));
closers.push(() => act(() => root.unmount()));
const surface = host.querySelector("[data-band]")!;
const pointer = (type: string, x: number, y: number) =>
act(() => {
surface.dispatchEvent(
new PointerEvent(type, {
bubbles: true,
buttons: type === "pointerup" ? 0 : 1,
pointerId: 1,
clientX: x,
clientY: y,
}),
);
});
return { picked, pointer };
}
const ids = async (iframe: HTMLIFrameElement) => {
const { picked, pointer } = band(iframe);
pointer("pointerdown", 130, 70);
pointer("pointermove", 500, 200);
pointer("pointermove", 520, 220);
await vi.waitFor(() => expect(picked.candidates).toBeGreaterThan(0));
const candidates = picked.candidates;
pointer("pointerup", 520, 220);
await vi.waitFor(() => expect(picked.selections).not.toBeNull());
return { candidates, ids: picked.selections!.map((s) => s.id ?? s.hfId), picked };
};
it("outlines and selects the same elements: visible, not full-bleed, inside the band", async () => {
const live = await ids(liveFrame());
const remote = await ids(opaqueFrame());
expect(remote.ids).toEqual(live.ids);
expect(remote.candidates).toBe(live.candidates);
// A group's members select as the group, on both kinds of frame.
expect(remote.ids).toEqual(["card", "title", "pic", "pair", "pair"]);
expect(remote.picked.selections!.every((selection) => selection.handle)).toBe(true);
});
it("selects layers past the cap on one layers reply, as same-origin does", async () => {
// Unmeasured fillers first, so every element in the band sits past the first reply.
const fillers = Array.from({ length: MAX_QUERY_MATCHES }, (_, i) => `<i id="f${i}"></i>`);
document.querySelector("main")!.insertAdjacentHTML("afterbegin", fillers.join(""));
expect((await previewLayers(opaqueFrame()))!.truncated).toBe(true);
const remote = await ids(opaqueFrame());
expect(remote.ids).toEqual(["card", "title", "pic", "pair", "pair"]);
}, 20_000);
});
it("maps an opaque selection to a timeline clip the frame knows only by its clip id", () => {
const clip = {
id: "card",
key: "index.html:card:0",
sourceFile: "index.html",
} as TimelineElement;
const selection = {
id: "card",
sourceFile: "index.html",
isCompositionHost: false,
handle: "0123456789abcdef:1",
};
expect(findMatchingTimelineElementId(selection, [clip], "index.html")).toBe("index.html:card:0");
const unhandled = { ...selection, handle: undefined };
expect(findMatchingTimelineElementId(unhandled, [clip], "index.html")).toBeNull();
const hydrated = { ...clip, domId: "other" } as TimelineElement;
expect(findMatchingTimelineElementId(selection, [hydrated], "index.html")).toBeNull();
// Without a scope (delete, group) the row is not this selection: it has no patch target.
expect(findMatchingTimelineElementId(selection, [clip])).toBeNull();
// A row naming no file is in the open composition, as the forward lookup reads it.
const bare = { id: "card", key: "compositions/a.html:card:0" } as TimelineElement;
const inSub = { ...selection, sourceFile: "compositions/a.html" };
expect(findMatchingTimelineElementId(inSub, [bare], "compositions/a.html")).toBe(bare.key);
expect(findMatchingTimelineElementId(inSub, [bare], "index.html")).not.toBe(bare.key);
});
it("refuses a layers reply that names an unknown kind", async () => {
const frame: Record<string, unknown> = {};
const iframe = detachedFakeIframe(frame);
Object.defineProperty(iframe, "contentDocument", { value: null });
Object.defineProperty(frame, "document", {
get: () => {
throw new DOMException("blocked", "SecurityError");
},
});
const { port1, port2 } = new MessageChannel();
closers.push(() => port1.close());
const layer = {
handle: "0123456789abcdef:1",
depth: 0,
childCount: 0,
zIndex: 0,
kind: "plugin",
};
port1.onmessage = ({ data }) =>
port1.postMessage({
v: 1,
id: data.id,
ok: true,
result: { layers: [layer], truncated: false, missingGroup: false },
});
frame.postMessage = () =>
window.dispatchEvent(
new MessageEvent("message", {
source: frame as unknown as Window,
data: { source: "hf-preview", type: "editing-port", v: 1 },
ports: [port2],
}),
);
expect(await previewLayers(iframe)).toBeNull();
});
@@ -0,0 +1,164 @@
/** Layers rows and marquee candidates for a preview frame Studio cannot script, from its runtime. */
import { MAX_DESCRIBE_HANDLES, type EditingLayer } from "@hyperframes/core/runtime/editing-port";
import {
describePreviewElements,
previewLayers,
queryPreviewElements,
type PreviewElement,
} from "../../player/lib/previewElements";
import type { Rect } from "../../utils/marqueeGeometry";
import { coversComposition } from "../../utils/studioPreviewHelpers";
import { buildElementLabel, getDataAttributes } from "./domEditingDom";
import { getDomEditLayerKey } from "./domEditingLayers";
import type { DomEditContextOptions, DomEditLayerItem, DomEditSelection } from "./domEditingTypes";
import { measurePreviewVisibleRects } from "./previewOverlayRects";
import {
previewIdentity,
readable,
resolvePreviewSelection,
standInFor,
standInHandle,
} from "./previewSelection";
async function describeAll(iframe: HTMLIFrameElement, handles: readonly string[]) {
const described: Array<PreviewElement | null> = [];
for (let at = 0; at < handles.length; at += MAX_DESCRIBE_HANDLES) {
const part = await describePreviewElements(
iframe,
handles.slice(at, at + MAX_DESCRIBE_HANDLES),
);
if (!part) return null;
described.push(...part);
}
return described;
}
function layerItem(
iframe: HTMLIFrameElement,
layer: EditingLayer,
element: PreviewElement,
path: string | null,
): DomEditLayerItem {
const probe = readable(element);
const identity = previewIdentity(element, path);
return {
...identity,
key: getDomEditLayerKey(identity),
element: standInFor(iframe, element),
label: buildElementLabel(probe),
tagName: element.tag,
depth: layer.depth,
childCount: layer.childCount,
preview: {
handle: layer.handle,
zIndex: layer.zIndex,
kind: layer.kind,
dataAttributes: getDataAttributes(probe),
},
};
}
/**
* `collectDomEditLayerItems` over the frame's runtime; null when it cannot answer. `missingGroup`
* says the drilled-into group is gone from the frame, as after a reload, and lists nothing.
*/
export async function collectPreviewLayerItems(
iframe: HTMLIFrameElement,
options: Pick<DomEditContextOptions, "activeCompositionPath" | "activeGroupElement">,
maxItems = Number.POSITIVE_INFINITY,
): Promise<{ items: DomEditLayerItem[]; missingGroup: boolean } | null> {
const group = options.activeGroupElement && standInHandle(options.activeGroupElement);
const reply = await previewLayers(iframe, group ?? undefined);
const layers = reply?.layers.slice(0, maxItems) ?? [];
const described =
reply &&
(await describeAll(
iframe,
layers.map((layer) => layer.handle),
));
if (!reply || !described) return null;
const items = layers.flatMap((layer, index) => {
const element = described[index];
return element ? [layerItem(iframe, layer, element, options.activeCompositionPath)] : [];
});
return { items, missingGroup: reply.missingGroup };
}
// A bound on the pages one read follows, so a frame that never stops paging cannot hold it open.
const MAX_LAYER_PAGES = 64;
/** Every layer the frame lists, page by page past its per-reply cap; null when it cannot answer. */
async function allPreviewLayers(iframe: HTMLIFrameElement): Promise<EditingLayer[] | null> {
const layers: EditingLayer[] = [];
for (let page = 0; page < MAX_LAYER_PAGES; page += 1) {
const reply = await previewLayers(iframe, undefined, layers.length);
if (!reply) return null;
layers.push(...reply.layers);
if (!reply.truncated || !reply.layers.length) break;
}
return layers;
}
/** A layer's `data-` attribute; a stand-in's comes from its description. */
export function layerDataAttribute(layer: DomEditLayerItem, name: `data-${string}`) {
if (!layer.preview) return layer.element.getAttribute(name);
return layer.preview.dataAttributes[name.slice("data-".length)] ?? null;
}
async function compositionViewport(iframe: HTMLIFrameElement) {
const roots = await queryPreviewElements(iframe, "[data-composition-id]");
const root = roots?.matches[0] ?? (await queryPreviewElements(iframe, "html"))?.matches[0];
const [described] = (root && (await describePreviewElements(iframe, [root.handle]))) || [];
if (!described) return null;
const declared = (name: string) =>
Number.parseFloat(described.attributes.find(([key]) => key === name)?.[1] ?? "");
const [width, height] = [declared("data-width"), declared("data-height")];
return {
width: width > 0 ? width : described.rect.width || 1,
height: height > 0 ? height : described.rect.height || 1,
};
}
export interface PreviewMarqueeHit {
element: HTMLElement;
rect: Rect;
description: PreviewElement;
}
/** `collectMarqueeCandidates` over the frame's runtime: every visible, not full-bleed layer. */
export async function collectPreviewMarqueeCandidates(
iframe: HTMLIFrameElement,
overlayEl: HTMLDivElement,
): Promise<PreviewMarqueeHit[]> {
// Hit-testing takes the whole document, as same-origin does: a layer past one reply's cap still selects.
const layers = await allPreviewLayers(iframe);
const handles = layers?.map((layer) => layer.handle) ?? [];
const viewport = handles.length ? await compositionViewport(iframe) : null;
const described = viewport && (await describeAll(iframe, handles));
const measured = described && (await measurePreviewVisibleRects(iframe, overlayEl, handles));
if (!described || !measured || !viewport) return [];
return handles.flatMap((_, index) => {
const description = described[index];
const box = measured[index];
if (!description || !box?.visible || coversComposition(box.frame, viewport)) return [];
const { left, top, width, height } = box.rect;
const element = standInFor(iframe, description);
return [{ element, rect: { left, top, width, height }, description }];
});
}
/** Marquee picks as selections, read like the frame's own descriptions. */
export async function resolvePreviewMarqueeHits(
iframe: HTMLIFrameElement,
hits: PreviewMarqueeHit[],
activeCompositionPath: string,
): Promise<DomEditSelection[]> {
const isMasterView = !activeCompositionPath || activeCompositionPath === "index.html";
const options = { activeCompositionPath, isMasterView, skipSourceProbe: true };
const picks: DomEditSelection[] = [];
for (const hit of hits) {
const selection = await resolvePreviewSelection(iframe, hit.description, options);
if (selection) picks.push(selection);
}
return picks;
}
@@ -4,6 +4,7 @@
* `domEditOverlayGeometry`'s, so both kinds of frame draw an element's chrome in the same place.
*/
import {
MAX_DESCRIBE_HANDLES,
ROTATION_GATE_EPSILON_DEG,
type EditingElementBox,
type EditingElementGeometry,
@@ -121,3 +122,29 @@ export async function measurePreviewRects(
if (!reply || !scale) return null;
return reply.elements.map((geometry) => geometry && groupAwareRect(scale, geometry, true));
}
/** `toVisibleOverlayRect` for each handle, with its frame rect and whether it renders. */
export async function measurePreviewVisibleRects(
iframe: HTMLIFrameElement,
overlayEl: HTMLDivElement,
handles: string[],
) {
const measured: Array<{ rect: OverlayRect; frame: EditingRect; visible: boolean } | null> = [];
for (let at = 0; at < handles.length; at += MAX_DESCRIBE_HANDLES) {
const reply = await previewGeometry(iframe, handles.slice(at, at + MAX_DESCRIBE_HANDLES));
const scale = reply && computeOverlayRootScale(overlayEl, iframe, null);
if (!reply || !scale) return null;
for (const box of reply.elements) {
const rect = box && baseRect(scale, box);
measured.push(
box &&
rect && {
rect: { ...rect, ...hugRectForClipPath(rect, box.clipPath) },
frame: box.rect,
visible: box.visible,
},
);
}
}
return measured;
}
@@ -20,6 +20,7 @@ import type { PreviewElement } from "../../player/lib/previewElements";
import { detachedFakeIframe } from "../../player/hooks/timelinePlayerTestHarness";
import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
import { useDomSelection } from "../../hooks/useDomSelection";
import { usePreviewInteraction } from "../../hooks/usePreviewInteraction";
import type { TimelineElement } from "../../player";
installReactActEnvironment();
@@ -172,7 +173,9 @@ describe("canvas hit-tests on an opaque frame match same-origin ones", () => {
});
describe("useDomSelection over an opaque frame's canvas", () => {
function renderSelection(iframe: HTMLIFrameElement) {
type Resolve = ReturnType<typeof useDomSelection>["resolveDomSelectionFromPreviewPoint"];
let interaction: ReturnType<typeof usePreviewInteraction> | null = null;
function renderSelection(iframe: HTMLIFrameElement, wrapResolve = (resolve: Resolve) => resolve) {
let hook: ReturnType<typeof useDomSelection> | null = null;
function Harness() {
hook = useDomSelection({
@@ -192,6 +195,17 @@ describe("useDomSelection over an opaque frame's canvas", () => {
refreshKey: 0,
rightPanelTab: "design",
});
interaction = usePreviewInteraction({
captionEditMode: false,
compositionLoading: false,
previewIframeRef: { current: iframe },
showToast: vi.fn(),
applyDomSelection: hook.applyDomSelection,
resolveDomSelectionFromPreviewPoint: wrapResolve(hook.resolveDomSelectionFromPreviewPoint),
resolveAllDomSelectionsFromPreviewPoint: hook.resolveAllDomSelectionsFromPreviewPoint,
updateDomEditHoverSelection: hook.updateDomEditHoverSelection,
setActiveGroupElement: hook.setActiveGroupElement,
});
return null;
}
const root = createRoot(document.createElement("div"));
@@ -211,6 +225,37 @@ describe("useDomSelection over an opaque frame's canvas", () => {
expect(cycle.map((selection) => selection.id)).toEqual(["title", "mask", "block"]);
});
const move = (x: number, y: number) => {
const [clientX, clientY] = client(x, y);
const event = { clientX, clientY } as React.PointerEvent<HTMLDivElement>;
return interaction!.handlePreviewCanvasPointerMove(event);
};
it.each([
["opaque", opaqueFrame],
["same-origin", liveFrame],
])("drops a hover the pointer left before it resolved (%s)", async (_kind, frame) => {
const hook = renderSelection(frame());
const moved = move(60, 60);
act(() => interaction!.handlePreviewCanvasPointerLeave());
await act(() => moved);
expect(hook().domEditHoverSelection).toBeNull();
});
it("keeps the newest move's hover when an older one resolves after it", async () => {
let calls = 0;
const hook = renderSelection(opaqueFrame(), (resolve) => async (...args) => {
const delay = ++calls === 1 ? 60 : 0;
const picked = await resolve(...args);
await new Promise((done) => setTimeout(done, delay));
return picked;
});
const older = move(60, 60);
const newer = move(1050, 650);
await act(() => Promise.all([older, newer]));
expect(hook().domEditHoverSelection).toMatchObject({ id: "pair" });
});
it("takes a hover of the same element from a reloaded frame, whose handle is new", async () => {
const hook = renderSelection(opaqueFrame());
const picked = (await act(() =>
@@ -76,7 +76,7 @@ const standIns = new WeakMap<EditingPortClient, Map<string, HTMLElement>>();
const standInHandles = new WeakMap<Element, string>();
const standInAncestors = new WeakMap<Element, string[]>();
function standInFor(iframe: HTMLIFrameElement, element: PreviewElement): HTMLElement {
export function standInFor(iframe: HTMLIFrameElement, element: PreviewElement): HTMLElement {
const client = previewEditingClient(iframe);
const byHandle = standIns.get(client) ?? new Map<string, HTMLElement>();
standIns.set(client, byHandle);
@@ -93,7 +93,7 @@ function standInFor(iframe: HTMLIFrameElement, element: PreviewElement): HTMLEle
* The description as an element of the inert document, discarded after the read, so the label,
* data-attribute and inline-style helpers read it as they read a live element.
*/
function readable(element: PreviewElement): HTMLElement {
export function readable(element: PreviewElement): HTMLElement {
const probe = inertElement(element.tag);
for (const [name, value] of element.attributes) {
if (name !== "id" && name !== "class" && !name.startsWith("data-")) continue;
@@ -262,7 +262,7 @@ function chainIndex(
});
}
function previewIdentity(current: PreviewElement, path: string | null) {
export function previewIdentity(current: PreviewElement, path: string | null) {
const selector = current.selector ?? undefined;
return {
id: current.id || undefined,
@@ -414,6 +414,8 @@ export async function findOpaqueTimelineElement(
return (await findPreviewElementForTimelineElement(iframe, element, lookup)) ?? null;
}
export const standInHandle = (element: Element) => standInHandles.get(element);
export function elementWithin(container: HTMLElement, element: HTMLElement): boolean {
const handle = standInHandles.get(container);
if (handle === undefined) return container.contains(element);
@@ -440,7 +442,8 @@ export function pointerMayHitElement(iframe: HTMLIFrameElement, clientX: number,
if (!previewFrameOpaque(iframe))
return Boolean(getPreviewTargetFromPointer(iframe, clientX, clientY));
const answer = pointerAnswers.get(iframe);
return answer?.x === clientX && answer.y === clientY ? answer.found : true;
const near = answer && Math.hypot(answer.x - clientX, answer.y - clientY) <= 2;
return near ? answer.found : true;
}
export async function findPointerTarget(
@@ -36,7 +36,7 @@ export interface UseLayerDragReturn {
}
export function isLayerDraggable(layer: DomEditLayerItem): boolean {
if (!(layer.selector || layer.id)) return false;
if (!(layer.selector || layer.id) || layer.preview) return false;
let el: HTMLElement | null = layer.element;
while (el) {
if (el.hasAttribute("data-timeline-locked")) return false;
@@ -27,4 +27,11 @@ describe("timelineElementsForDelete", () => {
const elements = [clip("a", "clip-a")];
expect(timelineElementsForDelete([sel("nested-text")], elements)).toBeNull();
});
it("leaves an opaque frame's selection on the DOM path, as its clip-id row has no patch target", () => {
// An opaque frame's rows carry only the clip id; the selection carries the frame's handle.
const row = { id: "title", sourceFile: "index.html", start: 0, duration: 1, track: 0 };
const opaque = { ...sel("title"), handle: "0123456789abcdef:1" } as DomEditSelection;
expect(timelineElementsForDelete([opaque], [row as TimelineElement])).toBeNull();
});
});
@@ -6,6 +6,7 @@ import { logSelect } from "../utils/selectDebug";
interface TimelineMirrorDeps {
timelineElements: TimelineElement[];
activeCompPath: string | null;
getTimelineSelectionSet: () => ReadonlySet<string>;
setSelectedTimelineElementId: (id: string | null, options?: SelectElementOptions) => void;
setTimelineSelectionSet: (ids: Set<string>) => void;
@@ -32,6 +33,7 @@ export function announceTimelineSelection(
): void {
const {
timelineElements,
activeCompPath,
getTimelineSelectionSet,
setSelectedTimelineElementId,
setTimelineSelectionSet,
@@ -42,7 +44,7 @@ export function announceTimelineSelection(
return;
}
const timelineIdFor = (selection: DomEditSelection) =>
findMatchingTimelineElementId(selection, timelineElements) ??
findMatchingTimelineElementId(selection, timelineElements, activeCompPath || "index.html") ??
findTimelineIdByAncestor(
selection.element,
timelineElements,
@@ -104,6 +104,7 @@ export function useDomSelection({
announceSelectionToTimeline(
{
timelineElements,
activeCompPath,
getTimelineSelectionSet,
setSelectedTimelineElementId,
setTimelineSelectionSet,
@@ -113,6 +114,7 @@ export function useDomSelection({
replaceSet,
),
[
activeCompPath,
getTimelineSelectionSet,
setSelectedTimelineElementId,
setTimelineSelectionSet,
@@ -74,6 +74,7 @@ export function usePreviewInteraction({
}: UsePreviewInteractionParams) {
const cycleRef = useRef<ClickCycleState | null>(null);
const lastDownRef = useRef<{ t: number; x: number; y: number } | null>(null);
const hoverSeqRef = useRef(0);
const pausePreviewPlayback = useCallback(() => {
const pausedTime = pauseStudioPreviewPlayback(previewIframeRef.current);
@@ -238,6 +239,7 @@ export function usePreviewInteraction({
const handlePreviewCanvasPointerMove = useCallback(
// fallow-ignore-next-line complexity
async (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
const seq = ++hoverSeqRef.current;
if (captionEditMode || compositionLoading) {
updateDomEditHoverSelection(null);
return null;
@@ -247,6 +249,7 @@ export function usePreviewInteraction({
preferClipAncestor: options?.preferClipAncestor ?? false,
skipSourceProbe: true,
});
if (seq !== hoverSeqRef.current) return null;
updateDomEditHoverSelection(nextSelection);
return nextSelection;
},
@@ -259,6 +262,7 @@ export function usePreviewInteraction({
);
const handlePreviewCanvasPointerLeave = useCallback(() => {
hoverSeqRef.current += 1;
updateDomEditHoverSelection(null);
}, [updateDomEditHoverSelection]);
@@ -80,6 +80,36 @@ function makeSyncFixture() {
}
describe("useTimelineSelectionPreviewSync", () => {
it("keeps an opaque frame's selection that matches a clip known only by its id", async () => {
// An opaque frame's rows carry only the clip id; its selections carry the frame's handle.
const timelineElements = [
{ id: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
] as TimelineElement[];
const element = document.createElement("div");
element.id = "clip-1";
const selection = { ...makeSelection("First", element), handle: "0123456789abcdef:1" };
const applyDomSelection = vi.fn();
const applyMarqueeSelection = vi.fn();
const buildDomSelectionForTimelineElement = vi.fn(async () => null);
const harness = renderHarness();
await harness.rerender({
selectedElementId: "clip-1",
selectedElementIds: new Set(["clip-1"]),
timelineElements,
domEditSelection: selection,
domEditGroupSelections: [selection],
buildDomSelectionForTimelineElement,
applyDomSelection,
applyMarqueeSelection,
onSelectionNotFound: vi.fn(),
});
expect(buildDomSelectionForTimelineElement).not.toHaveBeenCalled();
expect(applyDomSelection).not.toHaveBeenCalled();
harness.cleanup();
});
it("syncs a multi-id timeline selection into preview group selections", async () => {
const { firstSelection, secondSelection, timelineElements, selectionById } = makeSyncFixture();
const applyDomSelection = vi.fn();
@@ -139,11 +139,16 @@ export function useTimelineSelectionPreviewSync({
: [];
const currentIds = currentSelections
.map((selection) =>
resolveTimelineIdForSelection(selection, timelineElements, activeCompPath),
resolveTimelineIdForSelection(selection, timelineElements, activeCompPath, true),
)
.filter((id): id is string => Boolean(id));
const currentAnchor = currentDomEditSelection
? resolveTimelineIdForSelection(currentDomEditSelection, timelineElements, activeCompPath)
? resolveTimelineIdForSelection(
currentDomEditSelection,
timelineElements,
activeCompPath,
true,
)
: null;
if (selectedIds.length === 0) {
@@ -1,3 +1,4 @@
import { elementZIndex } from "@hyperframes/core/runtime/editing-port";
import { readLayerRevealPriorZ } from "./timelineElementHelpers";
export interface StackingContextDescriptor {
@@ -16,17 +17,7 @@ export function getElementZIndex(element: HTMLElement): number {
// An active Layers-panel reveal lift reports the element's TRUE z.
const prior = readLayerRevealPriorZ(element);
if (prior != null) return prior;
const inline = element.style?.zIndex;
if (inline && inline !== "auto") {
const parsed = parseInt(inline, 10);
if (Number.isFinite(parsed)) return parsed;
}
const win = element.ownerDocument?.defaultView;
if (!win) return 0;
const value = win.getComputedStyle(element).zIndex;
if (value === "auto" || value === "") return 0;
const parsed = parseInt(value, 10);
return Number.isFinite(parsed) ? parsed : 0;
return elementZIndex(element);
} catch {
return 0;
}
@@ -14,6 +14,7 @@ import {
type EditingElementHit,
type EditingElementMatch,
type EditingElementSource,
type EditingLayer,
} from "@hyperframes/core/runtime/editing-port";
import { resolveElementSourceFile } from "../../components/editor/domEditingDom";
import { previewRequest } from "./previewChannel";
@@ -224,3 +225,33 @@ export async function previewGeometry(
children: children && childrenOk ? (boxes as EditingElementBox[]) : null,
};
}
const LAYER_KINDS = new Set(["image", "video", "audio", "vector", "group", "text", "shape"]);
const isLayer = (value: unknown): value is EditingLayer =>
isFields(value) &&
isHandle(value.handle) &&
isCount(value.depth) &&
isCount(value.childCount) &&
Number.isFinite(value.zIndex) &&
LAYER_KINDS.has(value.kind as string);
export interface PreviewLayers {
layers: EditingLayer[];
truncated: boolean;
missingGroup: boolean;
}
/** One page of the frame's layers in document order from `offset`, scoped to `group` when given; null when the runtime cannot answer. */
export async function previewLayers(
iframe: HTMLIFrameElement,
group?: string,
offset = 0,
): Promise<PreviewLayers | null> {
const params = { ...(group ? { group } : {}), ...(offset ? { offset } : {}) };
const reply = await previewRequest(iframe, "layers", params);
const layers: unknown = reply?.layers;
const { truncated, missingGroup } = reply ?? {};
if (!Array.isArray(layers) || typeof truncated !== "boolean") return null;
if (typeof missingGroup !== "boolean") return null;
return layers.every(isLayer) ? { layers, truncated, missingGroup } : null;
}
+27 -4
View File
@@ -133,14 +133,30 @@ export type ElementMatchSelection = Pick<
| "sourceFile"
| "compositionSrc"
| "isCompositionHost"
>;
> &
Partial<Pick<DomEditSelection, "handle">>;
function matchesByClipId(
selection: ElementMatchSelection,
element: TimelineElement,
file: string,
value: string | undefined,
clipIdScope: string | undefined,
) {
if (!clipIdScope || !selection.handle) return false;
if (element.domId || element.hfId || element.selector) return false;
return element.id === value && (element.sourceFile || clipIdScope) === file;
}
function matchesByDomId(
selection: ElementMatchSelection,
element: TimelineElement,
selectionSourceFile: string,
clipIdScope?: string,
): boolean {
if (!selection.id) return false;
if (matchesByClipId(selection, element, selectionSourceFile, selection.id, clipIdScope))
return true;
return (
element.domId === selection.id && (element.sourceFile || "index.html") === selectionSourceFile
);
@@ -150,8 +166,11 @@ function matchesByHfId(
selection: ElementMatchSelection,
element: TimelineElement,
selectionSourceFile: string,
clipIdScope?: string,
): boolean {
if (!selection.hfId) return false;
if (matchesByClipId(selection, element, selectionSourceFile, selection.hfId, clipIdScope))
return true;
return (
element.hfId === selection.hfId && (element.sourceFile || "index.html") === selectionSourceFile
);
@@ -174,9 +193,11 @@ function matchesBySelector(selection: ElementMatchSelection, element: TimelineEl
);
}
/** `clipIdScope` matches opaque picks to clip-id-only rows, which have no patch target: select/seek only. */
export function findMatchingTimelineElementId(
selection: ElementMatchSelection,
elements: TimelineElement[],
clipIdScope?: string,
): string | null {
const selectionSourceFile = selection.sourceFile || "index.html";
// Priority matters, not just "any of the three": a composition-host
@@ -191,7 +212,7 @@ export function findMatchingTimelineElementId(
// first; only fall back to the coarser compositionSrc-only match when
// none of them identifies a specific element.
const byId = selection.id
? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile))
? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile, clipIdScope))
: undefined;
if (byId) return byId.key ?? byId.id;
@@ -199,7 +220,7 @@ export function findMatchingTimelineElementId(
// whether it has a real DOM id — the only correlator for an element like
// an ungroup child that has neither an authored id nor a selector.
const byHfId = selection.hfId
? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile))
? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile, clipIdScope))
: undefined;
if (byHfId) return byHfId.key ?? byHfId.id;
@@ -267,9 +288,11 @@ export function resolveTimelineIdForSelection(
selection: DomEditSelection,
elements: TimelineElement[],
activeCompPath: string | null,
byClipId = false,
): string | null {
const clipIdScope = byClipId ? activeCompPath || "index.html" : undefined;
return (
findMatchingTimelineElementId(selection, elements) ??
findMatchingTimelineElementId(selection, elements, clipIdScope) ??
findTimelineIdByAncestor(
selection.element,
elements,