feat(studio): timeline select and selection refresh read an opaque preview over its channel (#7613)

* feat(studio): timeline select and selection refresh read an opaque preview over its channel

On a preview frame Studio cannot script, timeline select, a selection
refresh and a group refresh build the selection from the runtime's element
descriptions. The rules that pick the element (group capture and drill-in,
the clip ancestor, the walk to an addressable element, timeline-locked, the
lookups and the master-view root fallback) move to a pure module over an
ancestor chain, used by both paths, so both select the same element.
Same-origin frames keep their direct reads.

The editing port gains `ancestors` (each handle's chain, parent first) and
`query` (a selector's matches with their source facts), and
`computed-styles` also names its element by handle. An opaque selection
carries the element's handle; its `element` is a tag-only stand-in in a
document with no window.

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

* chore(studio): keep the selection rules' comment share at the package's

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-12 22:39:47 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent f5476851dd
commit aed4c18feb
20 changed files with 1302 additions and 312 deletions
@@ -143,6 +143,8 @@ describe("installEditingAgent", () => {
"computed-styles",
"elements-at-point",
"describe",
"ancestors",
"query",
],
},
});
@@ -260,6 +262,38 @@ describe("installEditingAgent", () => {
40 + index,
"invalid-params",
]),
...[
{ handle: "0123456789abcdef:1" },
{ handle: "1", properties: ["color"] },
{ handle: 1, properties: ["color"] },
{ handle: "0123456789abcdef:1", selector: "p", properties: ["color"] },
{ handle: "0123456789abcdef:1", properties: ["color;"] },
].map((params, index) => [
{ v: 1, id: 70 + index, kind: "computed-styles", params },
70 + index,
"invalid-params",
]),
...[
{},
{ handles: [] },
{ handles: ["1"] },
{ handles: Array(257).fill("0123456789abcdef:1") },
].map((params, index) => [
{ v: 1, id: 80 + index, kind: "ancestors", params },
80 + index,
"invalid-params",
]),
...[
{},
{ selector: "" },
{ selector: 1 },
{ selector: "p".repeat(2001) },
{ selector: "p", x: 1 },
].map((params, index) => [
{ v: 1, id: 90 + index, kind: "query", params },
90 + 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 } },
+15 -3
View File
@@ -20,7 +20,13 @@ import {
type EditingResult,
} from "./editingPort";
import type { ClipNode } from "./clipTree";
import { describeHandles, elementsAtPoint } from "./editingHandles";
import {
ancestorHandles,
describeHandles,
elementForHandle,
elementsAtPoint,
queryElements,
} from "./editingHandles";
import { getLogicalOpacity } from "../studioPreviewMark";
type Handlers = {
@@ -57,8 +63,12 @@ const HANDLERS: Handlers = {
setLoopStart(seconds);
return { applied: true };
},
"computed-styles": ({ selector, properties }) => {
const element = document.querySelector(selector);
"computed-styles": (params) => {
const { properties } = params;
const element =
"handle" in params
? elementForHandle(params.handle)
: document.querySelector(params.selector);
if (!element) return { styles: null };
const computed = window.getComputedStyle(element);
const styles: Record<string, string> = {};
@@ -71,6 +81,8 @@ const HANDLERS: Handlers = {
},
"elements-at-point": ({ x, y }) => ({ elements: elementsAtPoint(x, y) }),
describe: ({ handles }) => ({ elements: describeHandles(handles) }),
ancestors: ({ handles }) => ({ ancestors: ancestorHandles(handles) }),
query: ({ selector }) => queryElements(selector),
};
function serve(port: MessagePort): void {
@@ -52,12 +52,18 @@ export interface EditingElementDescription extends EditingElementHit {
truncated: boolean;
}
export interface EditingElementMatch {
handle: EditingElementHandle;
source: EditingElementSource;
}
export const MAX_ELEMENT_ENTRIES = 256;
export const MAX_ELEMENT_TEXT = 10_000;
export const MAX_ELEMENT_VALUE = 2_000;
export const MAX_SOURCE_GROUPS = 64;
export const MAX_DESCRIBE_HANDLES = 256;
export const MAX_POINT_STACK = 64;
export const MAX_QUERY_MATCHES = 2_048;
// fallow-ignore-next-line complexity
function escapeCssIdentifier(value: string): string {
@@ -3,8 +3,10 @@ import { installEditingAgent } from "./editingAgent";
import { trackedHandleCount } from "./editingHandles";
import {
EDITING_ELEMENT_HANDLE,
MAX_DESCRIBE_HANDLES,
MAX_ELEMENT_TEXT,
MAX_ELEMENT_VALUE,
MAX_QUERY_MATCHES,
type EditingElementDescription,
type EditingElementHit,
} from "./editingPort";
@@ -201,4 +203,63 @@ describe("element handles over the editing port", () => {
},
]);
});
it("names a handle's ancestors parent first, up to the document element, and null once removed", async () => {
document.body.innerHTML = `<section id="s"><div class="g"><p id="p">A</p></div></section>`;
const p = document.querySelector("p")!;
const { handle } = await describeOne(p);
const reply = await ask<never>("ancestors", { handles: [handle, handle] });
const [chain, again] = (reply.result as unknown as { ancestors: string[][] }).ancestors;
expect(again).toEqual(chain);
const tags = (await describeHandles(chain!)).map((entry) => entry?.tag);
expect(tags).toEqual(["div", "section", "body", "html"]);
p.remove();
const gone = await ask<never>("ancestors", { handles: [handle] });
expect(gone.result).toEqual({ ancestors: [null] });
});
it("stops an ancestor chain at what one describe takes", async () => {
document.body.innerHTML = "<div>".repeat(MAX_DESCRIBE_HANDLES + 5) + "<p>deep</p>";
const { handle } = await describeOne(document.querySelector("p")!);
const reply = await ask<never>("ancestors", { handles: [handle] });
const [chain] = (reply.result as unknown as { ancestors: string[][] }).ancestors;
expect(chain).toHaveLength(MAX_DESCRIBE_HANDLES);
const [top] = await describeHandles([chain!.at(-1)!]);
expect(top!.parent).not.toBeNull();
});
it("answers a query with each match's handle and source, in document order", async () => {
document.body.innerHTML = `<p class="t" id="a"></p>
<div data-composition-file="cards.html"><p class="t" id="b"></p></div>`;
const reply = await ask<never>("query", { selector: ".t" });
const { matches, truncated } = reply.result as unknown as {
matches: Array<{ handle: string; source: { file: string | null } }>;
truncated: boolean;
};
expect(truncated).toBe(false);
expect(matches.map((match) => match.source.file)).toEqual([null, "cards.html"]);
const described = await describeHandles(matches.map((match) => match.handle));
expect(described.map((entry) => entry?.id)).toEqual(["a", "b"]);
expect((await ask<never>("query", { selector: "p[" })).error).toMatchObject({ code: "failed" });
});
it("caps a query's matches and says so", async () => {
document.body.innerHTML = "<i></i>".repeat(MAX_QUERY_MATCHES + 1);
const { result } = await ask<never>("query", { selector: "i" });
const { matches, truncated } = result as unknown as { matches: unknown[]; truncated: boolean };
expect(matches).toHaveLength(MAX_QUERY_MATCHES);
expect(truncated).toBe(true);
});
it("reads computed styles for the element a handle names, and null once it is removed", async () => {
document.body.innerHTML = `<p class="t" style="color: rgb(1, 2, 3)"></p><p class="t" style="color: rgb(4, 5, 6)"></p>`;
const second = document.querySelectorAll("p")[1]!;
const { handle } = await describeOne(second);
const styles = (properties: string[]) =>
ask<never>("computed-styles", { handle, properties }).then((reply) => reply.result);
expect(await styles(["color"])).toEqual({ styles: { color: "rgb(4, 5, 6)" } });
second.remove();
expect(await styles(["color"])).toEqual({ styles: null });
});
});
+31 -1
View File
@@ -5,15 +5,18 @@
*/
import {
buildStableSelector,
MAX_DESCRIBE_HANDLES,
MAX_ELEMENT_ENTRIES,
MAX_ELEMENT_TEXT,
MAX_ELEMENT_VALUE,
MAX_POINT_STACK,
MAX_QUERY_MATCHES,
MAX_SOURCE_GROUPS,
readElementSource,
type EditingElementDescription,
type EditingElementHandle,
type EditingElementHit,
type EditingElementMatch,
type EditingElementSource,
} from "./editingElement";
@@ -43,7 +46,7 @@ function handleFor(element: Element): EditingElementHandle {
}
/** The live element in this document behind `handle`, else null. */
function elementForHandle(handle: EditingElementHandle): Element | null {
export function elementForHandle(handle: EditingElementHandle): Element | null {
const [handleLoad, count] = handle.split(":");
if (handleLoad !== loadId()) return null;
const n = Number(count);
@@ -188,3 +191,30 @@ export function describeHandles(
return element ? describeElement(element) : null;
});
}
export function ancestorHandles(
requested: readonly EditingElementHandle[],
): Array<EditingElementHandle[] | null> {
return requested.map((handle) => {
const element = elementForHandle(handle);
if (!element) return null;
const chain: EditingElementHandle[] = [];
let node = element.parentElement;
for (; node && chain.length < MAX_DESCRIBE_HANDLES; node = node.parentElement) {
chain.push(handleFor(node));
}
return chain;
});
}
export function queryElements(selector: string): {
matches: EditingElementMatch[];
truncated: boolean;
} {
const matches: EditingElementMatch[] = [];
for (const element of document.querySelectorAll(selector)) {
if (matches.length === MAX_QUERY_MATCHES) return { matches, truncated: true };
matches.push({ handle: handleFor(element), source: readElementSource(element) });
}
return { matches, truncated: false };
}
@@ -68,6 +68,8 @@ describe("createEditingPortClient", () => {
"computed-styles",
"elements-at-point",
"describe",
"ancestors",
"query",
],
});
} finally {
+57 -27
View File
@@ -15,6 +15,7 @@ import {
type EditingElementDescription,
type EditingElementHandle,
type EditingElementHit,
type EditingElementMatch,
} from "./editingElement";
import type { RuntimeTimelineMessage } from "./types";
import { wallClearTimeout, wallSetTimeout } from "./wallClock";
@@ -30,10 +31,12 @@ export {
MAX_ELEMENT_TEXT,
MAX_ELEMENT_VALUE,
MAX_POINT_STACK,
MAX_QUERY_MATCHES,
MAX_SOURCE_GROUPS,
type EditingElementDescription,
type EditingElementHandle,
type EditingElementHit,
type EditingElementMatch,
type EditingElementSource,
type EditingRect,
} from "./editingElement";
@@ -52,6 +55,8 @@ export const EDITING_REQUEST_KINDS = [
"computed-styles",
"elements-at-point",
"describe",
"ancestors",
"query",
] as const;
export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number];
@@ -77,9 +82,9 @@ export interface EditingRequests {
"wait-for-seek": { params: NoParams; result: { waited: boolean } };
/** Where a looping playback wraps to; null stops looping from a custom start. */
"set-loop-start": { params: { seconds: number | null }; result: { applied: boolean } };
/** `styles` is null when no element matches `selector`; empty values are left out. */
/** The element `selector` first matches, or `handle` names. `styles` is null for none; empty values are left out. */
"computed-styles": {
params: { selector: string; properties: string[] };
params: ({ selector: string } | { handle: EditingElementHandle }) & { properties: string[] };
result: { styles: Record<string, string> | null };
};
/** The stack under a viewport point, topmost first, up to MAX_POINT_STACK. Describe one to keep. */
@@ -92,6 +97,16 @@ export interface EditingRequests {
params: { handles: EditingElementHandle[] };
result: { elements: Array<EditingElementDescription | null> };
};
/** Each handle's ancestors, parent first, up to MAX_DESCRIBE_HANDLES; null as in `describe`. */
ancestors: {
params: { handles: EditingElementHandle[] };
result: { ancestors: Array<EditingElementHandle[] | null> };
};
/** The matches of `selector` in document order, up to MAX_QUERY_MATCHES; an invalid one fails. */
query: {
params: { selector: string };
result: { matches: EditingElementMatch[]; truncated: boolean };
};
}
export type EditingParams<K extends EditingRequestKind> = EditingRequests[K]["params"];
export type EditingResult<K extends EditingRequestKind> = EditingRequests[K]["result"];
@@ -133,6 +148,36 @@ const hasKeys = (params: unknown, keys: string): params is Record<string, unknow
const noParams = (params: unknown): NoParams | null =>
params === undefined || (isPlainRecord(params) && Object.keys(params).length === 0) ? {} : null;
const isSelector = (value: unknown): value is string =>
typeof value === "string" && value.length > 0 && value.length <= MAX_SELECTOR_LENGTH;
const isHandle = (value: unknown): value is EditingElementHandle =>
typeof value === "string" && EDITING_ELEMENT_HANDLE.test(value);
function styleTarget(params: Record<string, unknown>) {
const keys = Object.keys(params).sort().join();
const { selector, handle } = params;
if (keys === "properties,selector" && isSelector(selector)) return { selector };
return keys === "handle,properties" && isHandle(handle) ? { handle } : null;
}
function styleProperties(properties: unknown): string[] | null {
if (!Array.isArray(properties) || properties.length > MAX_STYLE_PROPERTIES) return null;
const names = properties.filter(
(name): name is string =>
typeof name === "string" &&
name.length <= MAX_STYLE_PROPERTY_LENGTH &&
STYLE_PROPERTY.test(name),
);
return names.length === properties.length ? names : null;
}
function handleList(params: unknown): { handles: EditingElementHandle[] } | null {
if (!hasKeys(params, "handles") || !Array.isArray(params.handles)) return null;
const { handles } = params;
if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
return handles.every(isHandle) ? { handles } : null;
}
const PARAM_PARSERS: {
[K in EditingRequestKind]: (params: unknown) => EditingParams<K> | null;
} = {
@@ -148,37 +193,22 @@ const PARAM_PARSERS: {
: null;
},
"computed-styles": (params) => {
if (!isPlainRecord(params) || Object.keys(params).sort().join() !== "properties,selector") {
return null;
}
const { selector, properties } = params;
if (typeof selector !== "string" || !selector || selector.length > MAX_SELECTOR_LENGTH) {
return null;
}
if (!Array.isArray(properties) || properties.length > MAX_STYLE_PROPERTIES) return null;
const names = properties.filter(
(name): name is string =>
typeof name === "string" &&
name.length <= MAX_STYLE_PROPERTY_LENGTH &&
STYLE_PROPERTY.test(name),
);
return names.length === properties.length ? { selector, properties: names } : null;
if (!isPlainRecord(params)) return null;
const target = styleTarget(params);
const properties = styleProperties(params.properties);
return target && properties ? { ...target, properties } : null;
},
"elements-at-point": (params) => {
if (!hasKeys(params, "x,y")) return null;
const { x, y } = params;
return Number.isFinite(x) && Number.isFinite(y) ? { x: x as number, y: y as number } : null;
},
describe: (params) => {
if (!hasKeys(params, "handles") || !Array.isArray(params.handles)) return null;
const { handles } = params;
if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
return handles.every(
(handle) => typeof handle === "string" && EDITING_ELEMENT_HANDLE.test(handle),
)
? { handles: handles as string[] }
: null;
},
describe: handleList,
ancestors: handleList,
query: (params) =>
hasKeys(params, "selector") && isSelector(params.selector)
? { selector: params.selector }
: null,
};
/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */
@@ -0,0 +1,138 @@
/** Selection rules over an ancestor chain: one answer for live elements and for descriptions. */
import type { TimelineElementDomTarget, TimelineElementDomTargetOptions } from "./domEditingTypes";
import { escapeCssString, normalizeTimelineCompositionSource } from "./domEditingDom";
/** Reads one element of a chain: the target first, then each parent up to the document element. */
export interface SelectionChainReader<N> {
attr(node: N, name: string): string | null;
selector(node: N): string | undefined;
/** The document's `body` or root element, where the walk to an addressable element stops. */
isDocumentRoot(node: N): boolean;
}
const OUT_OF_SCOPE = -1;
const hasClass = (value: string | null, name: string) =>
(value ?? "").split(/[\t\n\f\r ]+/).includes(name);
/**
* A `data-hf-group` wrapper is one unit until the user drills into it; inside the drilled-into
* group, clicks reach its children, or the next group nested in it. Returns the unit's index, null
* to resolve the target itself, or OUT_OF_SCOPE when the target is outside the drilled-into group.
*/
function groupUnitIndex<N>(
chain: readonly N[],
read: SelectionChainReader<N>,
activeGroupIndex: number | null,
): number | null {
const groups = chain.flatMap((node, index) =>
read.attr(node, "data-hf-group") === null ? [] : [index],
);
if (activeGroupIndex === null) return groups.at(-1) ?? null;
const at = groups.indexOf(activeGroupIndex);
if (at === -1) return OUT_OF_SCOPE;
return at > 0 ? groups[at - 1]! : null;
}
/** The nearest `.clip`; a composition host counts only as the target itself. */
function clipAncestorIndex<N>(chain: readonly N[], read: SelectionChainReader<N>): number | null {
for (let index = 0; index < chain.length; index += 1) {
const node = chain[index]!;
if (!hasClass(read.attr(node, "class"), "clip")) continue;
const isHost =
read.attr(node, "data-composition-src") !== null ||
read.attr(node, "data-composition-file") !== null;
if (!isHost || index === 0) return index;
}
return null;
}
/** Where a selection of `chain[0]` lands; `activeGroupIndex` is -1 for a drilled group not in `chain`. */
export function selectionTargetIndex<N>(
chain: readonly N[],
read: SelectionChainReader<N>,
options: { exactTarget?: boolean; preferClipAncestor?: boolean; activeGroupIndex: number | null },
): number | null {
let start = options.exactTarget ? 0 : groupUnitIndex(chain, read, options.activeGroupIndex);
if (start === OUT_OF_SCOPE) start = groupUnitIndex(chain, read, null);
start ??= options.preferClipAncestor ? (clipAncestorIndex(chain, read) ?? 0) : 0;
for (let index = start; index < chain.length; index += 1) {
const node = chain[index]!;
if (read.isDocumentRoot(node)) return null;
if (read.selector(node) || read.attr(node, "data-hf-id")?.trim()) return index;
}
return null;
}
export function chainLocked<N>(
chain: readonly N[],
read: SelectionChainReader<N>,
index: number,
): boolean {
return chain.slice(index).some((node) => read.attr(node, "data-timeline-locked") !== null);
}
export interface SelectionLookupTarget {
id?: string | null;
hfId?: string;
selector?: string;
selectorIndex?: number;
sourceFile?: string;
}
/** The selectors tried in order, each with the index of its match among those from `sourceFile`. */
export function selectionLookups(
selection: SelectionLookupTarget,
): Array<{ selector: string; index: number }> {
const lookups: Array<{ selector: string; index: number }> = [];
if (selection.hfId) {
lookups.push({ selector: `[data-hf-id="${escapeCssString(selection.hfId)}"]`, index: 0 });
}
// Flattened sub-compositions can repeat authored ids, so an id is matched by attribute, per source.
if (selection.id) lookups.push({ selector: `[id="${escapeCssString(selection.id)}"]`, index: 0 });
if (selection.selector) {
lookups.push({ selector: selection.selector, index: selection.selectorIndex ?? 0 });
}
return lookups;
}
/**
* Where a timeline element is in the preview: `target` to look up, else, when `rootFallback`, the
* first composition root if it comes from `sourceFile`.
*/
export function timelineElementLookup(
element: TimelineElementDomTarget,
options: TimelineElementDomTargetOptions,
): { target: SelectionLookupTarget | null; sourceFile: string; rootFallback: boolean } {
const elementId = typeof element.id === "string" ? element.id : "";
const compositionSource =
normalizeTimelineCompositionSource(element.compositionSrc) ??
options.compIdToSrc?.get(elementId);
const sourceFile =
compositionSource ??
normalizeTimelineCompositionSource(element.sourceFile) ??
options.activeCompositionPath ??
"index.html";
const escapedElementId = escapeCssString(elementId);
const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null;
const selector =
element.selector ??
(compositionSource
? `[data-composition-src="${escapedCompositionSource}"],[data-composition-file="${escapedCompositionSource}"],[data-composition-id="${escapedElementId}"]`
: escapedElementId
? `[data-composition-id="${escapedElementId}"]`
: undefined);
const target =
selector || element.domId
? {
id: element.domId ?? undefined,
selector,
selectorIndex: element.selectorIndex,
sourceFile,
}
: null;
const hasExplicitDomTarget = Boolean(element.domId || element.selector || compositionSource);
const rootFallback =
!options.isMasterView && !hasExplicitDomTarget && Boolean(options.activeCompositionPath);
return { target, sourceFile, rootFallback };
}
@@ -11,14 +11,13 @@ import type {
} from "./domEditingTypes";
import {
buildStableSelector,
escapeCssString,
getSelectorIndex,
getSourceFileForElement,
isHtmlElement,
isElementVisibleThroughAncestors,
normalizeTimelineCompositionSource,
querySelectorAllSafely,
} from "./domEditingDom";
import { selectionLookups, timelineElementLookup } from "./domEditSelectionRules";
// ─── Visibility ──────────────────────────────────────────────────────────────
@@ -171,36 +170,6 @@ export function isDomLayerElement(el: HTMLElement): boolean {
return isInspectableLayerElement(el) && resolveLayerSelector(el) !== undefined;
}
// ─── Clip ancestor / selection candidate ─────────────────────────────────────
function getPreferredClipAncestor(startEl: HTMLElement): HTMLElement | null {
let current: HTMLElement | null = startEl;
while (current) {
if (current.classList.contains("clip")) {
const isCompositionHost =
current.hasAttribute("data-composition-src") ||
current.hasAttribute("data-composition-file");
if (!isCompositionHost || current === startEl) return current;
}
current = current.parentElement;
}
return null;
}
export function getSelectionCandidate(
startEl: HTMLElement,
options: DomEditContextOptions,
): HTMLElement {
if (options.preferClipAncestor) {
const clipAncestor = getPreferredClipAncestor(startEl);
if (clipAncestor) {
return clipAncestor;
}
}
return startEl;
}
// ─── Visual target resolution ─────────────────────────────────────────────────
export function resolveVisualDomEditSelectionTarget(
@@ -295,23 +264,11 @@ export function findElementForSelection(
(!selection.sourceFile ||
getSourceFileForElement(candidate, activeCompositionPath).sourceFile ===
selection.sourceFile);
const findAll = (selector: string): HTMLElement[] =>
querySelectorAllSafely(doc, selector).filter(sourceMatches);
if (selection.hfId) {
const byHfId = findAll(`[data-hf-id="${escapeCssString(selection.hfId)}"]`)[0];
if (byHfId) return byHfId;
for (const { selector, index } of selectionLookups(selection)) {
const found = querySelectorAllSafely(doc, selector).filter(sourceMatches)[index];
if (found) return found;
}
if (selection.id) {
// Flattened sub-compositions can repeat authored ids. getElementById returns
// only the first document match, so filter every id match by source first.
const byId = findAll(`[id="${escapeCssString(selection.id)}"]`)[0];
if (byId) return byId;
}
if (!selection.selector) return null;
return findAll(selection.selector)[selection.selectorIndex ?? 0] ?? null;
return null;
}
// The selected node while mounted, else its copy in the selection's own file (ids repeat across files), else any copy.
@@ -327,49 +284,15 @@ export function findPreviewNode(
);
}
// fallow-ignore-next-line complexity
export function findElementForTimelineElement(
doc: Document,
element: TimelineElementDomTarget,
options: TimelineElementDomTargetOptions,
): HTMLElement | null {
const elementId = typeof element.id === "string" ? element.id : "";
const compositionSource =
normalizeTimelineCompositionSource(element.compositionSrc) ??
options.compIdToSrc?.get(elementId);
const sourceFile =
compositionSource ??
normalizeTimelineCompositionSource(element.sourceFile) ??
options.activeCompositionPath ??
"index.html";
const escapedElementId = escapeCssString(elementId);
const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null;
const selector =
element.selector ??
(compositionSource
? `[data-composition-src="${escapedCompositionSource}"],[data-composition-file="${escapedCompositionSource}"],[data-composition-id="${escapedElementId}"]`
: escapedElementId
? `[data-composition-id="${escapedElementId}"]`
: undefined);
if (selector || element.domId) {
const targetElement = findElementForSelection(
doc,
{
id: element.domId ?? undefined,
selector,
selectorIndex: element.selectorIndex,
sourceFile,
},
options.activeCompositionPath,
);
if (targetElement) return targetElement;
}
const hasExplicitDomTarget = Boolean(element.domId || element.selector || compositionSource);
if (options.isMasterView || hasExplicitDomTarget || !options.activeCompositionPath) {
return null;
}
const { target, sourceFile, rootFallback } = timelineElementLookup(element, options);
const found = target && findElementForSelection(doc, target, options.activeCompositionPath);
if (found) return found;
if (!rootFallback) return null;
const root = doc.querySelector("[data-composition-id]");
if (!isHtmlElement(root)) return null;
@@ -1,15 +1,5 @@
import { isHtmlElement } from "./domEditingDom";
// `data-hf-group` selection semantics: a group wrapper is selected as one unit
// until the user drills into it; once drilled in, clicks resolve to its children
// (or to the next nested group inside it). One level of drill-in at a time keeps
// nested groups navigable.
export type GroupCapture =
| { kind: "unit"; element: HTMLElement } // select this group wrapper as one unit
| { kind: "child" } // resolve the clicked element normally
| { kind: "out-of-scope" }; // clicked outside the drilled-into group → select nothing
// Layer-tree roots: the drilled-into group's element children, else the doc root.
export function groupScopedLayerRoots(
root: HTMLElement,
@@ -18,24 +8,3 @@ export function groupScopedLayerRoots(
const els = activeGroupElement?.isConnected ? Array.from(activeGroupElement.children) : [root];
return els.filter(isHtmlElement);
}
export function resolveGroupCapture(
startEl: HTMLElement,
activeGroupElement: HTMLElement | null,
): GroupCapture {
const groups: HTMLElement[] = [];
for (let n: HTMLElement | null = startEl; n; n = n.parentElement) {
if (n.hasAttribute("data-hf-group")) groups.push(n);
}
const result = ((): GroupCapture => {
if (!activeGroupElement) {
const outermost = groups[groups.length - 1];
return outermost ? { kind: "unit", element: outermost } : { kind: "child" };
}
const idx = groups.indexOf(activeGroupElement);
if (idx === -1) return { kind: "out-of-scope" };
const nestedInside = groups[idx - 1];
return nestedInside ? { kind: "unit", element: nestedInside } : { kind: "child" };
})();
return result;
}
@@ -1,5 +1,5 @@
import { isClipHiddenByRuntime, PREVIEW_ONLY_ATTRS } from "@hyperframes/core/studio-preview-mark";
import { knownSourceAnswer, probeSourceElement, type ProbeTarget } from "./probeSourceElement";
import { existsInSourceFile } from "./probeSourceElement";
import { isAudibleVideoNode } from "../../player/lib/timelineElementHelpers";
import type { PatchOperation } from "../../utils/sourcePatcher";
import {
@@ -7,7 +7,12 @@ import {
resolveEditingSections,
type EditableElementFacts,
} from "@hyperframes/core/editing";
import { groupScopedLayerRoots, resolveGroupCapture } from "./domEditingGroups";
import { groupScopedLayerRoots } from "./domEditingGroups";
import {
chainLocked,
selectionTargetIndex,
type SelectionChainReader,
} from "./domEditSelectionRules";
import type {
DomEditCapabilities,
DomEditContextOptions,
@@ -18,7 +23,6 @@ import type {
import {
buildElementLabel,
buildStableSelector,
findClosestByAttribute,
getCuratedComputedStyles,
getDataAttributes,
getInlineStyles,
@@ -27,11 +31,7 @@ import {
isEditableTextLeaf,
isHtmlElement,
} from "./domEditingDom";
import {
findElementForSelection,
getSelectionCandidate,
isDomLayerElement,
} from "./domEditingElement";
import { findElementForSelection, isDomLayerElement } from "./domEditingElement";
import { isCompositionRootLayer } from "./domEditingRootLayer";
import { withSelectorIndexPass } from "../../utils/sourceScopedSelectorIndex";
import { type DomEditLayerWalkCache, readDomEditLayerWalkEntry } from "./domEditLayerWalkCache";
@@ -206,7 +206,7 @@ export function buildTextFieldChildLocator(
};
}
function capabilityFacts(geometry: {
export function capabilityFacts(geometry: {
hasStableTarget: boolean;
tag: string;
inlineStyles: Record<string, string>;
@@ -296,99 +296,94 @@ export async function resolveDomEditSelection(
): Promise<DomEditSelection | null> {
if (!startEl) return null;
const doc = startEl.ownerDocument;
let capture = options.exactTarget
? ({ kind: "unit", element: startEl } as const)
: resolveGroupCapture(startEl, options.activeGroupElement ?? null);
if (capture.kind === "out-of-scope") {
// Drill-in is non-sticky: clicking/hovering OUTSIDE the drilled-into group
// exits it and resolves the target normally, rather than selecting nothing
// (which felt like "can't select anything" once you'd drilled in).
capture = resolveGroupCapture(startEl, null);
}
let current: HTMLElement | null =
capture.kind === "unit" ? capture.element : getSelectionCandidate(startEl, options);
while (current && current !== doc.body && current !== doc.documentElement) {
const selector = buildStableSelector(current);
const hfId = readHfId(current);
if (!selector && !hfId) {
current = current.parentElement;
continue;
}
const { sourceFile, compositionPath } = getSourceFileForElement(
current,
options.activeCompositionPath,
);
const selectorIndex = selector
? getSelectorIndex(doc, current, selector, sourceFile, options.activeCompositionPath)
: undefined;
const compositionSrc =
current.getAttribute("data-composition-src") ??
current.getAttribute("data-composition-file") ??
undefined;
const inlineStyles = getInlineStyles(current);
const computedStyles = getCuratedComputedStyles(current);
const isCompositionRoot =
(current.hasAttribute("data-composition-id") && !compositionSrc) ||
isCompositionRootLayer(current, doc, computedStyles);
const textFields = collectDomEditTextFields(current);
const isInsideLocked = Boolean(findClosestByAttribute(current, ["data-timeline-locked"]));
const probeTarget: ProbeTarget = {};
if (current.id) probeTarget.id = current.id;
if (hfId) probeTarget.hfId = hfId;
if (selector) probeTarget.selector = selector;
if (selectorIndex != null) probeTarget.selectorIndex = selectorIndex;
let existsInSource = knownSourceAnswer(options.previous, current, sourceFile, probeTarget);
const probe = existsInSource === undefined && !options.skipSourceProbe;
if (probe && options.projectId && (current.id || selector || hfId)) {
existsInSource = await probeSourceElement(options.projectId, sourceFile, probeTarget);
}
const capabilities = resolveEditingAffordances(
capabilityFacts({
hasStableTarget: Boolean(selector || hfId),
tag: current.tagName.toLowerCase(),
inlineStyles,
computedStyles,
isCompositionHost: Boolean(compositionSrc),
isCompositionRoot,
isInsideLockedComposition: isInsideLocked,
isMasterView: options.isMasterView,
existsInSource: existsInSource ?? true,
}),
).capabilities;
const rect = current.getBoundingClientRect();
return {
element: current,
id: current.id || undefined,
hfId,
selector,
selectorIndex,
sourceFile,
compositionPath,
compositionSrc,
isCompositionHost: Boolean(compositionSrc),
isInsideLockedComposition: isInsideLocked,
label: buildElementLabel(current),
tagName: current.tagName.toLowerCase(),
boundingBox: {
x: rect.left,
y: rect.top,
width: rect.width,
height: rect.height,
},
textContent: current.textContent?.trim() || null,
dataAttributes: getDataAttributes(current),
const chain: HTMLElement[] = [];
for (let node: HTMLElement | null = startEl; node; node = node.parentElement) chain.push(node);
const read = liveChainReader(doc);
const active = options.activeGroupElement ?? null;
const index = selectionTargetIndex(chain, read, {
exactTarget: options.exactTarget,
preferClipAncestor: options.preferClipAncestor,
activeGroupIndex: active ? chain.indexOf(active) : null,
});
if (index === null) return null;
const current = chain[index]!;
const selector = buildStableSelector(current);
const hfId = readHfId(current);
const { sourceFile, compositionPath } = getSourceFileForElement(
current,
options.activeCompositionPath,
);
const selectorIndex = selector
? getSelectorIndex(doc, current, selector, sourceFile, options.activeCompositionPath)
: undefined;
const compositionSrc =
current.getAttribute("data-composition-src") ??
current.getAttribute("data-composition-file") ??
undefined;
const inlineStyles = getInlineStyles(current);
const computedStyles = getCuratedComputedStyles(current);
const isCompositionRoot =
(current.hasAttribute("data-composition-id") && !compositionSrc) ||
isCompositionRootLayer(current, doc, computedStyles);
const textFields = collectDomEditTextFields(current);
const isInsideLocked = chainLocked(chain, read, index);
const existsInSource = await existsInSourceFile(
options.previous,
current,
sourceFile,
{ id: current.id, hfId, selector, selectorIndex },
options,
);
const capabilities = resolveEditingAffordances(
capabilityFacts({
hasStableTarget: Boolean(selector || hfId),
tag: current.tagName.toLowerCase(),
inlineStyles,
computedStyles,
textFields,
capabilities,
existsInSource,
};
}
isCompositionHost: Boolean(compositionSrc),
isCompositionRoot,
isInsideLockedComposition: isInsideLocked,
isMasterView: options.isMasterView,
existsInSource: existsInSource ?? true,
}),
).capabilities;
const rect = current.getBoundingClientRect();
return null;
return {
element: current,
id: current.id || undefined,
hfId,
selector,
selectorIndex,
sourceFile,
compositionPath,
compositionSrc,
isCompositionHost: Boolean(compositionSrc),
isInsideLockedComposition: isInsideLocked,
label: buildElementLabel(current),
tagName: current.tagName.toLowerCase(),
boundingBox: {
x: rect.left,
y: rect.top,
width: rect.width,
height: rect.height,
},
textContent: current.textContent?.trim() || null,
dataAttributes: getDataAttributes(current),
inlineStyles,
computedStyles,
textFields,
capabilities,
existsInSource,
};
}
function liveChainReader(doc: Document): SelectionChainReader<HTMLElement> {
return {
attr: (el, name) => el.getAttribute(name),
selector: buildStableSelector,
isDocumentRoot: (el) => el === doc.body || el === doc.documentElement,
};
}
export async function refreshDomEditSelection(
@@ -12,32 +12,36 @@ function approximatelyEqual(a: number, b: number) {
return Math.abs(a - b) <= COMPOSITION_ROOT_LAYER_EPSILON_PX;
}
function getCompositionRootBounds(doc: Document) {
const root =
doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement ?? null;
const rootWidth = readPositiveDimension(root?.getAttribute("data-width") ?? null);
const rootHeight = readPositiveDimension(root?.getAttribute("data-height") ?? null);
if (!root || !rootWidth || !rootHeight) return null;
return { rect: root.getBoundingClientRect(), width: rootWidth, height: rootHeight };
interface Box {
left: number;
top: number;
width: number;
height: number;
}
function getRenderedLayerSize(element: HTMLElement, computedStyles: Record<string, string>) {
const rect = element.getBoundingClientRect();
const width = rect.width || parsePx(computedStyles.width);
const height = rect.height || parsePx(computedStyles.height);
return width && height ? { width, height } : null;
export interface CompositionRootFacts {
rect: Box;
width: string | null;
height: string | null;
}
function matchesCompositionRootBounds(
elementRect: DOMRect,
elementSize: { width: number; height: number },
rootBounds: { rect: DOMRect; width: number; height: number },
) {
return (
approximatelyEqual(elementRect.left, rootBounds.rect.left) &&
approximatelyEqual(elementRect.top, rootBounds.rect.top) &&
approximatelyEqual(elementSize.width, rootBounds.width) &&
approximatelyEqual(elementSize.height, rootBounds.height)
export function coversCompositionRoot(
layer: { rect: Box; computedStyles: Record<string, string> },
root: CompositionRootFacts | null,
): boolean {
if (isExplicitFullBleedLayer(layer.computedStyles)) return false;
const rootWidth = readPositiveDimension(root?.width ?? null);
const rootHeight = readPositiveDimension(root?.height ?? null);
if (!root || !rootWidth || !rootHeight) return false;
const width = layer.rect.width || parsePx(layer.computedStyles.width);
const height = layer.rect.height || parsePx(layer.computedStyles.height);
return Boolean(
width &&
height &&
approximatelyEqual(layer.rect.left, root.rect.left) &&
approximatelyEqual(layer.rect.top, root.rect.top) &&
approximatelyEqual(width, rootWidth) &&
approximatelyEqual(height, rootHeight),
);
}
@@ -52,13 +56,14 @@ export function isCompositionRootLayer(
) {
if (element.parentElement !== doc.body) return false;
if (element.hasAttribute("data-hf-allow-root-edit")) return false;
if (isExplicitFullBleedLayer(computedStyles)) return false;
const rootBounds = getCompositionRootBounds(doc);
const elementSize = getRenderedLayerSize(element, computedStyles);
return Boolean(
rootBounds &&
elementSize &&
matchesCompositionRootBounds(element.getBoundingClientRect(), elementSize, rootBounds),
const root =
doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement ?? null;
return coversCompositionRoot(
{ rect: element.getBoundingClientRect(), computedStyles },
root && {
rect: root.getBoundingClientRect(),
width: root.getAttribute("data-width"),
height: root.getAttribute("data-height"),
},
);
}
@@ -1,5 +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";
export const CURATED_STYLE_PROPERTIES = [
"position",
@@ -78,6 +79,7 @@ export interface DomEditTextField {
export interface DomEditSelection extends PatchTarget {
element: HTMLElement;
handle?: EditingElementHandle;
label: string;
tagName: string;
sourceFile: string;
@@ -0,0 +1,376 @@
// @vitest-environment happy-dom
import React, { act } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import { EDITING_ELEMENT_HANDLE } from "@hyperframes/core/runtime/editing-port";
// The frame's real runtime agent, serving the opaque frame from this document.
import { installEditingAgent } from "../../../../core/src/runtime/editingAgent";
import {
findElementForSelection,
findElementForTimelineElement,
resolveDomEditSelection,
type DomEditSelection,
} from "./domEditing";
import { setCompositionSourceMap } from "./domEditingDom";
import {
findPreviewElementForSelection,
findPreviewElementForTimelineElement,
resolvePreviewSelection,
type PreviewSelectionOptions,
} from "./previewSelection";
import {
describePreviewElements,
previewElementsAtPoint,
type PreviewElement,
} from "../../player/lib/previewElements";
import { detachedFakeIframe } from "../../player/hooks/timelinePlayerTestHarness";
import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness";
import { useDomSelection } from "../../hooks/useDomSelection";
import type { TimelineElement } from "../../player";
installReactActEnvironment();
const closers: Array<() => void> = [];
afterEach(() => {
closers.splice(0).forEach((close) => close());
setCompositionSourceMap(new Map());
document.body.innerHTML = "";
delete (document as { elementsFromPoint?: unknown }).elementsFromPoint;
});
/** A frame Studio scripts directly; its document is this one. */
function liveFrame(): HTMLIFrameElement {
const iframe = detachedFakeIframe({});
Object.defineProperty(iframe, "contentDocument", { value: document });
return iframe;
}
/** A frame Studio cannot read, whose runtime is the real editing agent over this document. */
function opaqueFrame(): HTMLIFrameElement {
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;
}
const CONTEXT: PreviewSelectionOptions = {
activeCompositionPath: "index.html",
isMasterView: false,
};
/** The selection both paths agree on: everything but the element itself and its text fields. */
function shared(selection: DomEditSelection | null) {
if (!selection) return null;
const { element: _element, handle: _handle, textFields: _fields, ...rest } = selection;
return rest;
}
/** The opaque frame's description of `element`, as a hit-test would hand it over. */
async function describedOnOpaque(iframe: HTMLIFrameElement, element: Element) {
Object.defineProperty(document, "elementsFromPoint", {
configurable: true,
value: () => [element],
});
const [hit] = (await previewElementsAtPoint(iframe, 0, 0)) ?? [];
const [described] = (await describePreviewElements(iframe, [hit!.handle])) ?? [];
return described!;
}
async function bothPaths(element: HTMLElement, options: PreviewSelectionOptions = CONTEXT) {
const opaque = opaqueFrame();
const live = await resolveDomEditSelection(element, options);
const remote = await resolvePreviewSelection(
opaque,
await describedOnOpaque(opaque, element),
options,
);
return { live, remote, opaque };
}
const NAMES = ["id", "data-hf-id", "data-pick", "data-composition-id"];
const nameOf = (element: Element) =>
NAMES.map((name) => element.getAttribute(name)).find(Boolean) ?? null;
const named = (element: PreviewElement) =>
NAMES.map((name) => element.attributes.find(([key]) => key === name)?.[1]).find(Boolean) ?? null;
const FIXTURE = `
<div data-composition-id="main" data-width="1920" data-height="1080">
<div data-hf-group="outer" id="outer-wrap">
<div data-hf-group="inner"><p class="member" data-hf-id="m1" style="left: 4px; border-radius: 8px">Member</p></div>
</div>
<div class="clip scene" id="scene"><span class="inner"><b>bold</b></span></div>
<div class="clip" data-composition-src="compositions/a.html" id="host"><span id="in-host">in</span></div>
<div data-timeline-locked><p id="locked" data-start="2" style="border-radius: 8px">Locked</p></div>
<i class="tile" id="t-index"></i>
<div data-composition-file="compositions/cards.html"><i class="tile"></i><i class="tile" data-pick="t2"></i></div>
<p id="plain"><b>no selector here</b></p>
</div>
<div id="bg" style="width: 1920px; height: 1080px"></div>`;
describe("opaque frame selections match same-origin ones", () => {
it.each([
["a group member at the top level selects the outermost group", "[data-hf-id=m1]", {}],
["a clip's child, preferring the clip ancestor, selects the clip", "b", { clip: true }],
["a host clip is not taken for its child", "#in-host", { clip: true }],
["an element with no selector walks up to its addressable parent", "#plain b", {}],
["a timeline-locked element is selected as locked", "#locked", {}],
["a class match counts its index within its own file", "[data-pick=t2]", {}],
["a body child sitting on the root counts as the composition root", "#bg", {}],
])("%s", async (_name, selector, flags: { clip?: boolean }) => {
document.body.innerHTML = FIXTURE;
const { live, remote } = await bothPaths(document.querySelector<HTMLElement>(selector)!, {
...CONTEXT,
preferClipAncestor: flags.clip,
});
expect(live).not.toBeNull();
expect(shared(remote)).toEqual(shared(live));
expect(remote!.handle).toMatch(EDITING_ELEMENT_HANDLE);
expect(remote!.tagName).toBe(live!.element.tagName.toLowerCase());
});
it("covers the cases each rule decides", async () => {
document.body.innerHTML = FIXTURE;
const pick = async (selector: string, clip = false) =>
(await bothPaths(document.querySelector<HTMLElement>(selector)!, {
...CONTEXT,
preferClipAncestor: clip,
}))!.remote!;
expect((await pick("[data-hf-id=m1]")).selector).toBe("#outer-wrap");
expect((await pick("b", true)).id).toBe("scene");
expect((await pick("#in-host", true)).id).toBe("in-host");
expect((await pick("#plain b")).id).toBe("plain");
expect(await pick("#locked")).toMatchObject({
isInsideLockedComposition: true,
inlineStyles: { "border-radius": "8px" },
dataAttributes: { start: "2" },
label: "Locked",
});
expect(await pick("[data-pick=t2]")).toMatchObject({
sourceFile: "compositions/cards.html",
selectorIndex: 1,
});
expect((await pick("#bg")).capabilities).toMatchObject({
canCrop: false,
canApplyManualOffset: false,
});
expect((await pick("#plain")).capabilities.canApplyManualOffset).toBe(true);
});
it("follows a drilled-into group: its nested group, then its children, else the top level", async () => {
document.body.innerHTML = FIXTURE;
const member = document.querySelector<HTMLElement>("[data-hf-id=m1]")!;
const opaque = opaqueFrame();
const described = await describedOnOpaque(opaque, member);
const outerLive = document.querySelector<HTMLElement>('[data-hf-group="outer"]')!;
const innerLive = document.querySelector<HTMLElement>('[data-hf-group="inner"]')!;
// On an opaque frame the drilled-into group is the stand-in of an earlier selection.
const outerRemote = (await resolvePreviewSelection(opaque, described, CONTEXT))!.element;
const innerRemote = (await resolvePreviewSelection(opaque, described, {
...CONTEXT,
activeGroupElement: outerRemote,
}))!.element;
const cases: Array<[HTMLElement | null, HTMLElement | null, string]> = [
[outerLive, outerRemote, '[data-hf-group="inner"]'],
[innerLive, innerRemote, ".member"],
[document.querySelector<HTMLElement>("#scene"), null, "#outer-wrap"],
];
for (const [activeLive, activeRemote, selector] of cases) {
const live = await resolveDomEditSelection(member, {
...CONTEXT,
activeGroupElement: activeLive,
});
const remote = await resolvePreviewSelection(opaque, described, {
...CONTEXT,
activeGroupElement: activeRemote ?? document.createElement("div"),
});
expect(live!.selector).toBe(selector);
expect(shared(remote)).toEqual(shared(live));
}
});
it.each([
[
"by selector and index in its own file",
{ selector: ".tile", selectorIndex: 1, sourceFile: "compositions/cards.html" },
],
["by id", { id: "t-index", sourceFile: "index.html" }],
["by hf id", { hfId: "m1" }],
["nothing for a selector with no match", { selector: ".missing" }],
["nothing for an invalid selector", { selector: "p[" }],
])("finds an element for a selection %s", async (_name, selection) => {
document.body.innerHTML = FIXTURE;
const live = findElementForSelection(document, selection, "index.html");
const found = await findPreviewElementForSelection(opaqueFrame(), selection, "index.html");
expect(live === null ? null : nameOf(live)).toBe(found === null ? null : found && named(found));
if (selection.selector !== ".missing" && selection.selector !== "p[")
expect(live).not.toBeNull();
});
it.each([
[
"a clip by selector",
{ id: "x", selector: ".tile", selectorIndex: 1, sourceFile: "compositions/cards.html" },
false,
"t2",
],
["the root, from the active composition, outside the master view", { id: "x" }, false, "main"],
["nothing in the master view without a DOM target", { id: "x" }, true, null],
])("finds a timeline element: %s", async (_name, element, isMasterView, expected) => {
document.body.innerHTML = FIXTURE;
const options = { activeCompositionPath: "index.html", isMasterView };
const live = findElementForTimelineElement(document, element, options);
const found = await findPreviewElementForTimelineElement(opaqueFrame(), element, options);
expect(live && nameOf(live)).toBe(expected);
expect(found && named(found)).toBe(expected);
});
});
describe("opaque frame selection handles", () => {
it("gives a selection an inert, tag-only stand-in, the same one for a handle", async () => {
document.body.innerHTML = FIXTURE;
const { remote, opaque } = await bothPaths(document.querySelector<HTMLElement>("#locked")!);
const again = await resolvePreviewSelection(
opaque,
await describedOnOpaque(opaque, document.querySelector("#locked")!),
{ ...CONTEXT, previous: remote },
);
expect(again!.element).toBe(remote!.element);
expect(remote!.element.tagName).toBe("P");
expect(remote!.element.attributes).toHaveLength(0);
expect(remote!.element.textContent).toBe("");
expect(remote!.element.ownerDocument.defaultView).toBeNull();
expect(remote!.element.ownerDocument).not.toBe(document);
});
it("builds nothing for a removed element, and finds nothing the runtime cannot name", async () => {
document.body.innerHTML = FIXTURE;
const opaque = opaqueFrame();
const locked = document.querySelector("#locked")!;
const described = await describedOnOpaque(opaque, locked);
// A description whose parent is not the element its runtime names as the parent.
const unlinked = { ...described, parent: described.handle };
expect(await resolvePreviewSelection(opaque, unlinked, CONTEXT)).toBeNull();
expect(await resolvePreviewSelection(opaque, described, CONTEXT)).not.toBeNull();
locked.remove();
expect(await resolvePreviewSelection(opaque, described, CONTEXT)).toBeNull();
const stale = {
...described,
handle: described.handle.replace(/^[0-9a-f]{16}/, "f".repeat(16)),
};
expect(await resolvePreviewSelection(opaque, stale, CONTEXT)).toBeNull();
});
it("says it cannot tell when the frame has no editing agent", async () => {
vi.useFakeTimers();
try {
const frame: Record<string, unknown> = { postMessage: () => {} };
const iframe = detachedFakeIframe(frame);
const pending = findPreviewElementForSelection(iframe, { id: "plain" }, "index.html");
await vi.advanceTimersByTimeAsync(2_000);
expect(await pending).toBeUndefined();
} finally {
vi.useRealTimers();
}
});
it("says it cannot tell when a capped query does not reach the index", async () => {
document.body.innerHTML = "<i class='n'></i>".repeat(2_049);
const found = await findPreviewElementForSelection(
opaqueFrame(),
{ selector: ".n", selectorIndex: 2_048 },
"index.html",
);
expect(found).toBeUndefined();
});
});
describe("useDomSelection on an opaque frame", () => {
function renderSelection(iframe: HTMLIFrameElement) {
let hook: ReturnType<typeof useDomSelection> | null = null;
function Harness() {
hook = useDomSelection({
projectId: null,
activeCompPath: "index.html",
isMasterView: false,
compIdToSrc: new Map(),
captionEditMode: false,
previewIframeRef: { current: iframe },
timelineElements: [],
getTimelineSelectionSet: () => new Set(),
setSelectedTimelineElementId: vi.fn(),
setTimelineSelectionSet: vi.fn(),
setRightCollapsed: vi.fn(),
setRightPanelTab: vi.fn(),
previewIframe: iframe,
refreshKey: 0,
rightPanelTab: "design",
});
return null;
}
const host = document.createElement("div");
const root = createRoot(host);
act(() => root.render(React.createElement(Harness)));
closers.push(() => act(() => root.unmount()));
return () => hook!;
}
const clip = (selector: string) =>
({
id: "c",
selector,
selectorIndex: 0,
sourceFile: "index.html",
}) as unknown as TimelineElement;
it("selects a timeline clip, refreshes it, and drops it once the frame no longer has it", async () => {
document.body.innerHTML = FIXTURE;
const liveHook = renderSelection(liveFrame());
const hook = renderSelection(opaqueFrame());
await act(() => liveHook().handleTimelineElementSelect(clip("#locked")));
await act(() => hook().handleTimelineElementSelect(clip("#locked")));
const selected = hook().domEditSelection!;
expect(selected.handle).toMatch(EDITING_ELEMENT_HANDLE);
expect(shared(selected)).toEqual(shared(liveHook().domEditSelection));
document.querySelector<HTMLElement>("#locked")!.style.left = "12px";
await act(() => hook().refreshDomEditSelectionFromPreview(selected));
expect(hook().domEditSelection!.inlineStyles.left).toBe("12px");
expect(hook().domEditSelection!.element).toBe(selected.element);
document.querySelector("#locked")!.remove();
await act(() => hook().refreshDomEditSelectionFromPreview(hook().domEditSelection!));
expect(hook().domEditSelection).toBeNull();
});
it("re-finds every group member on refresh", async () => {
document.body.innerHTML = FIXTURE;
const hook = renderSelection(opaqueFrame());
await act(() => hook().handleTimelineElementSelect(clip("#locked")));
const first = hook().domEditSelection!;
await act(() => hook().handleTimelineElementSelect(clip("#plain")));
const second = hook().domEditSelection!;
act(() => hook().applyDomSelection(first, { additive: true }));
expect(hook().domEditGroupSelections).toHaveLength(2);
document.querySelector("#locked")!.remove();
await act(() => hook().refreshDomEditSelectionFromPreview(first));
expect(hook().domEditGroupSelections.map((s) => s.id)).toEqual(["plain"]);
expect(hook().domEditSelection!.handle).toBe(second.handle);
});
});
@@ -0,0 +1,361 @@
/**
* Selections in a preview frame Studio cannot script, built from its runtime's element
* descriptions. Which element a selection lands on comes from `domEditSelectionRules.ts`, the
* rules a scriptable frame's selections use, so both kinds of frame select the same element.
*
* Such a selection's `element` is a stand-in: an element with only the target's tag, in a
* document with no window, the same one for a handle for the whole frame load. Nothing in it
* loads, runs or renders, and nothing from the frame is copied into it. The frame's element is
* the selection's `handle`.
*/
import { resolveEditingAffordances } from "@hyperframes/core/editing";
import type { EditingPortClient } from "@hyperframes/core/runtime/editing-port";
import {
previewComputedStyles,
previewEditingClient,
previewFrameOpaque,
} from "../../player/lib/previewChannel";
import {
describePreviewElements,
previewAncestors,
previewElementSelectorIndex,
previewElementSourceFile,
queryPreviewElements,
type PreviewElement,
} from "../../player/lib/previewElements";
import { coversCompositionRoot } from "./domEditingRootLayer";
import {
buildElementLabel,
getDataAttributes,
getInlineStyles,
isHtmlElement,
resolveElementSourceFile,
} from "./domEditingDom";
import { findElementForSelection } from "./domEditingElement";
import { capabilityFacts, resolveDomEditSelection } from "./domEditingLayers";
import {
chainLocked,
selectionLookups,
selectionTargetIndex,
timelineElementLookup,
type SelectionChainReader,
type SelectionLookupTarget,
} from "./domEditSelectionRules";
import {
CURATED_STYLE_PROPERTIES,
type DomEditContextOptions,
type DomEditSelection,
type TimelineElementDomTarget,
type TimelineElementDomTargetOptions,
} from "./domEditingTypes";
import { existsInSourceFile } from "./probeSourceElement";
let inertDocument: Document | undefined;
const inert = () => (inertDocument ??= document.implementation.createHTMLDocument(""));
function inertElement(tag: string): HTMLElement {
try {
return inert().createElement(tag);
} catch {
return inert().createElement("div");
}
}
const standIns = new WeakMap<EditingPortClient, Map<string, HTMLElement>>();
const standInHandles = new WeakMap<Element, string>();
function standInFor(iframe: HTMLIFrameElement, element: PreviewElement): HTMLElement {
const client = previewEditingClient(iframe);
const byHandle = standIns.get(client) ?? new Map<string, HTMLElement>();
standIns.set(client, byHandle);
let standIn = byHandle.get(element.handle);
if (!standIn) {
standIn = inertElement(element.tag);
byHandle.set(element.handle, standIn);
standInHandles.set(standIn, element.handle);
}
return standIn;
}
/**
* 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 {
const probe = inertElement(element.tag);
for (const [name, value] of element.attributes) {
if (name !== "id" && name !== "class" && !name.startsWith("data-")) continue;
try {
probe.setAttribute(name, value);
} catch {
// A name the parser took but setAttribute refuses; no helper reads such a name.
}
}
for (const [name, value] of Object.entries(element.inlineStyles)) {
probe.style.setProperty(name, value);
}
probe.textContent = element.text;
return probe;
}
const attr = (element: PreviewElement, name: string) =>
element.attributes.find(([key]) => key === name)?.[1] ?? null;
/** Undefined when the frame cannot answer; null when nothing matches. */
type Found = PreviewElement | null | undefined;
const validSelector = (selector: string) => {
try {
inert().querySelector(selector);
return true;
} catch {
return false;
}
};
/** `findElementForSelection` over the frame's runtime. */
export async function findPreviewElementForSelection(
iframe: HTMLIFrameElement,
selection: SelectionLookupTarget,
activeCompositionPath: string | null,
): Promise<Found> {
for (const { selector, index } of selectionLookups(selection)) {
if (!validSelector(selector)) continue;
const reply = await queryPreviewElements(iframe, selector);
if (!reply) return undefined;
const fromFile = reply.matches.filter(
({ source }) =>
!selection.sourceFile ||
resolveElementSourceFile(source, activeCompositionPath) === selection.sourceFile,
);
const match = fromFile[index];
if (!match) {
if (reply.truncated) return undefined;
continue;
}
const [element] = (await describePreviewElements(iframe, [match.handle])) ?? [];
return element ?? undefined;
}
return null;
}
/** `findElementForTimelineElement` over the frame's runtime. */
export async function findPreviewElementForTimelineElement(
iframe: HTMLIFrameElement,
element: TimelineElementDomTarget,
options: TimelineElementDomTargetOptions,
): Promise<Found> {
const { target, sourceFile, rootFallback } = timelineElementLookup(element, options);
const path = options.activeCompositionPath;
const found = target && (await findPreviewElementForSelection(iframe, target, path));
if (found !== null) return found;
if (!rootFallback) return null;
const reply = await queryPreviewElements(iframe, "[data-composition-id]");
if (!reply) return undefined;
const root = reply.matches[0];
if (!root || resolveElementSourceFile(root.source, path) !== sourceFile) return null;
const [described] = (await describePreviewElements(iframe, [root.handle])) ?? [];
return described ?? undefined;
}
/** The target and every ancestor up to the document element, or null when any is missing. */
async function previewChain(
iframe: HTMLIFrameElement,
target: PreviewElement,
): Promise<PreviewElement[] | null> {
const [lineage] = (await previewAncestors(iframe, [target.handle])) ?? [];
if (!lineage) return null;
const ancestors = lineage.length ? await describePreviewElements(iframe, lineage) : [];
if (!ancestors || ancestors.some((entry) => entry === null)) return null;
const chain = [target, ...(ancestors as PreviewElement[])];
const linked = chain.every((node, i) => node.parent === (chain[i + 1]?.handle ?? null));
return linked ? chain : null;
}
function chainReader(chain: readonly PreviewElement[]): SelectionChainReader<PreviewElement> {
const root = chain.at(-1);
const body = chain.at(-2);
return {
attr,
selector: (node) => node.selector ?? undefined,
isDocumentRoot: (node) => node === root || (node === body && node.tag === "body"),
};
}
async function compositionRoot(iframe: HTMLIFrameElement, documentElement: PreviewElement) {
const reply = await queryPreviewElements(iframe, "[data-composition-id]");
const first = reply?.matches[0];
const [root] = first ? ((await describePreviewElements(iframe, [first.handle])) ?? []) : [];
const element = root ?? documentElement;
const { x, y, width, height } = element.rect;
return {
rect: { left: x, top: y, width, height },
width: attr(element, "data-width"),
height: attr(element, "data-height"),
};
}
export type PreviewSelectionOptions = DomEditContextOptions & {
projectId?: string | null;
skipSourceProbe?: boolean;
exactTarget?: boolean;
previous?: DomEditSelection | null;
};
function chainIndex(
chain: readonly PreviewElement[],
read: SelectionChainReader<PreviewElement>,
options: PreviewSelectionOptions,
): number | null {
const active = options.activeGroupElement;
const activeHandle = active ? standInHandles.get(active) : undefined;
return selectionTargetIndex(chain, read, {
exactTarget: options.exactTarget,
preferClipAncestor: options.preferClipAncestor,
activeGroupIndex: active ? chain.findIndex((node) => node.handle === activeHandle) : null,
});
}
function previewIdentity(current: PreviewElement, path: string | null) {
const selector = current.selector ?? undefined;
return {
id: current.id || undefined,
hfId: attr(current, "data-hf-id")?.trim() || undefined,
selector,
selectorIndex: selector ? previewElementSelectorIndex(current, path) : undefined,
sourceFile: previewElementSourceFile(current, path),
};
}
async function isPreviewCompositionRoot(
iframe: HTMLIFrameElement,
chain: readonly PreviewElement[],
index: number,
computedStyles: Record<string, string>,
): Promise<boolean> {
const current = chain[index]!;
if (attr(current, "data-composition-id") !== null && !compositionSourceOf(current)) return true;
const parent = chain[index + 1];
const underBody = parent?.tag === "body" && chainReader(chain).isDocumentRoot(parent);
if (!underBody || attr(current, "data-hf-allow-root-edit") !== null) return false;
const { x, y, width, height } = current.rect;
const rect = { left: x, top: y, width, height };
return coversCompositionRoot(
{ rect, computedStyles },
await compositionRoot(iframe, chain.at(-1)!),
);
}
const compositionSourceOf = (element: PreviewElement) =>
attr(element, "data-composition-src") ?? attr(element, "data-composition-file") ?? undefined;
/**
* `resolveDomEditSelection` for a frame element Studio has a description of. Text fields are left
* empty: they are read for text edits, which write through the frame's document.
*/
export async function resolvePreviewSelection(
iframe: HTMLIFrameElement,
target: PreviewElement,
options: PreviewSelectionOptions,
): Promise<DomEditSelection | null> {
const chain = await previewChain(iframe, target);
const index = chain && chainIndex(chain, chainReader(chain), options);
if (!chain || index === null) return null;
const current = chain[index]!;
const element = standInFor(iframe, current);
const identity = previewIdentity(current, options.activeCompositionPath);
const compositionSrc = compositionSourceOf(current);
const probe = readable(current);
const inlineStyles = getInlineStyles(probe);
const computedStyles =
(await previewComputedStyles(iframe, current, [...CURATED_STYLE_PROPERTIES])) ?? {};
const isCompositionRoot = await isPreviewCompositionRoot(iframe, chain, index, computedStyles);
const isInsideLocked = chainLocked(chain, chainReader(chain), index);
const { sourceFile } = identity;
const existsInSource = await existsInSourceFile(
options.previous,
element,
sourceFile,
identity,
options,
);
const capabilities = resolveEditingAffordances(
capabilityFacts({
hasStableTarget: Boolean(identity.selector || identity.hfId),
tag: current.tag,
inlineStyles,
computedStyles,
isCompositionHost: Boolean(compositionSrc),
isCompositionRoot,
isInsideLockedComposition: isInsideLocked,
isMasterView: options.isMasterView,
existsInSource: existsInSource ?? true,
}),
).capabilities;
const { x, y, width, height } = current.rect;
return {
element,
handle: current.handle,
...identity,
compositionPath: sourceFile,
compositionSrc,
isCompositionHost: Boolean(compositionSrc),
isInsideLockedComposition: isInsideLocked,
label: buildElementLabel(probe),
tagName: current.tag,
boundingBox: { x, y, width, height },
textContent: current.text.trim() || null,
dataAttributes: getDataAttributes(probe),
inlineStyles,
computedStyles,
textFields: [],
capabilities,
existsInSource,
};
}
function liveElementForSelection(
iframe: HTMLIFrameElement | null,
selection: SelectionLookupTarget,
activeCompositionPath: string | null,
): HTMLElement | null | undefined {
let doc: Document | null = null;
try {
doc = iframe?.contentDocument ?? null;
} catch {
return undefined;
}
return doc ? findElementForSelection(doc, selection, activeCompositionPath) : undefined;
}
/** `selection`'s element in the frame now, or its description; undefined when the frame cannot answer. */
export async function findSelectionElement(
iframe: HTMLIFrameElement | null,
selection: SelectionLookupTarget,
activeCompositionPath: string | null,
): Promise<HTMLElement | Found> {
return iframe && previewFrameOpaque(iframe)
? findPreviewElementForSelection(iframe, selection, activeCompositionPath)
: liveElementForSelection(iframe, selection, activeCompositionPath);
}
/** `resolveDomEditSelection` for an element, or for a description from `iframe`. */
export async function resolveFoundSelection(
iframe: HTMLIFrameElement | null,
found: HTMLElement | PreviewElement,
options: PreviewSelectionOptions,
): Promise<DomEditSelection | null> {
if (isHtmlElement(found)) return resolveDomEditSelection(found, options);
return iframe ? resolvePreviewSelection(iframe, found, options) : null;
}
/** A timeline element's description in a frame Studio cannot script; null for any other frame. */
export async function findOpaqueTimelineElement(
iframe: HTMLIFrameElement | null,
element: TimelineElementDomTarget,
lookup: TimelineElementDomTargetOptions,
): Promise<PreviewElement | null> {
if (!iframe || !previewFrameOpaque(iframe)) return null;
return (await findPreviewElementForTimelineElement(iframe, element, lookup)) ?? null;
}
@@ -4,7 +4,7 @@ import type { DomEditSelection } from "./domEditingTypes";
export type ProbeTarget = { id?: string; hfId?: string; selector?: string; selectorIndex?: number };
export function knownSourceAnswer(
function knownSourceAnswer(
previous: DomEditSelection | null | undefined,
element: HTMLElement,
sourceFile: string,
@@ -68,3 +68,21 @@ export function probeSourceElement(
probes.push({ target, resolve });
});
}
export async function existsInSourceFile(
previous: DomEditSelection | null | undefined,
element: HTMLElement,
sourceFile: string,
target: ProbeTarget,
options: { projectId?: string | null; skipSourceProbe?: boolean },
): Promise<boolean | undefined> {
const probeTarget: ProbeTarget = {};
if (target.id) probeTarget.id = target.id;
if (target.hfId) probeTarget.hfId = target.hfId;
if (target.selector) probeTarget.selector = target.selector;
if (target.selectorIndex != null) probeTarget.selectorIndex = target.selectorIndex;
const known = knownSourceAnswer(previous, element, sourceFile, probeTarget);
if (known !== undefined || options.skipSourceProbe || !options.projectId) return known;
if (!target.id && !target.selector && !target.hfId) return known;
return probeSourceElement(options.projectId, sourceFile, probeTarget);
}
+30 -30
View File
@@ -13,11 +13,15 @@ import {
seedDomEditGroupWithSelection,
} from "../utils/domEditHelpers";
import {
findElementForSelection,
findElementForTimelineElement,
resolveDomEditSelection,
type DomEditSelection,
} from "../components/editor/domEditing";
import {
findOpaqueTimelineElement,
findSelectionElement,
resolveFoundSelection,
} from "../components/editor/previewSelection";
import type { PreviewElement } from "../player/lib/previewElements";
import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits";
import { holdScenesOf } from "../utils/sceneHold";
import { useStudioTestHooks } from "./useStudioTestHooks";
@@ -216,8 +220,12 @@ export function useDomSelection({
);
const buildDomSelectionFromTarget = useCallback(
(target: HTMLElement, options?: ResolveDomSelectionOptions) => {
return resolveDomEditSelection(target, {
(
target: HTMLElement | PreviewElement,
options?: ResolveDomSelectionOptions,
iframe = previewIframeRef.current,
) => {
return resolveFoundSelection(iframe, target, {
activeCompositionPath: activeCompPath,
isMasterView,
preferClipAncestor: options?.preferClipAncestor,
@@ -231,7 +239,7 @@ export function useDomSelection({
projectId,
});
},
[activeCompPath, isMasterView, projectId],
[activeCompPath, isMasterView, previewIframeRef, projectId],
);
const resolveDomSelectionFromPreviewPoint = useCallback(
@@ -302,23 +310,25 @@ export function useDomSelection({
// fallow-ignore-next-line complexity
async (element: TimelineElement): Promise<DomEditSelection | null> => {
const iframe = previewIframeRef.current;
const lookup = { activeCompositionPath: activeCompPath, compIdToSrc, isMasterView };
let doc: Document | null = null;
try {
doc = iframe?.contentDocument ?? null;
} catch {
return null;
}
if (!doc) return null;
if (!doc) {
const found = await findOpaqueTimelineElement(iframe, element, lookup);
return found
? buildDomSelectionFromTarget(found, { preferClipAncestor: false }, iframe)
: null;
}
const held = holdScenesOf(iframe, element);
if (held) await held;
reapplyPositionEditsAfterSeek(doc);
const targetElement = findElementForTimelineElement(doc, element, {
activeCompositionPath: activeCompPath,
compIdToSrc,
isMasterView,
});
const targetElement = findElementForTimelineElement(doc, element, lookup);
return targetElement
? buildDomSelectionFromTarget(targetElement, {
preferClipAncestor: false,
@@ -365,15 +375,8 @@ export function useDomSelection({
const stillSelected = () =>
domEditSelectionsTargetSame(domEditSelectionRef.current, selection);
if (!stillSelected()) return;
let doc: Document | null = null;
try {
doc = iframe?.contentDocument ?? null;
} catch {
return;
}
if (!doc) return;
const element = findElementForSelection(doc, selection, activeCompPath);
const element = await findSelectionElement(iframe, selection, activeCompPath);
if (element === undefined || !stillSelected()) return;
if (!element) {
// Losing the primary is not losing the selection. When a group is live,
// re-resolve it and keep whoever still exists rather than wiping the lot.
@@ -390,7 +393,11 @@ export function useDomSelection({
return;
}
const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection });
const nextSelection = await buildDomSelectionFromTarget(
element,
{ previous: selection },
iframe,
);
if (nextSelection && stillSelected()) {
applyDomSelection(nextSelection, {
revealPanel: false,
@@ -405,17 +412,10 @@ export function useDomSelection({
// fallow-ignore-next-line complexity
async (selections: DomEditSelection[]) => {
const iframe = previewIframeRef.current;
let doc: Document | null = null;
try {
doc = iframe?.contentDocument ?? null;
} catch {
return;
}
if (!doc) return;
const nextGroup: DomEditSelection[] = [];
for (const selection of selections) {
const element = findElementForSelection(doc, selection, activeCompPath);
const element = await findSelectionElement(iframe, selection, activeCompPath);
if (element === undefined) return;
if (!element) continue;
const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection });
if (nextSelection) nextGroup.push(nextSelection);
@@ -190,7 +190,7 @@ export function usePreviewInteraction({
preferClipAncestor: options?.preferClipAncestor ?? false,
});
// A null result while drilled into a group means the click landed OUTSIDE that
// group (resolveGroupCapture → out-of-scope). Drill-in isn't sticky: exit it and
// group (selectionTargetIndex: out of scope). Drill-in isn't sticky: exit it and
// re-resolve at the top level so this click selects whatever's there (or the
// group as a unit). Without this, a stale drill-in keeps selecting children and
// the "first click selects the group" expectation breaks.
@@ -97,13 +97,14 @@ export async function previewClipManifest(iframe: HTMLIFrameElement): Promise<Cl
return manifest as ClipManifest;
}
/** The runtime's computed `properties` for the element `selector` names; null when it has none. */
/** The runtime's computed `properties` for the element `target` names; null when it has none. */
export async function previewComputedStyles(
iframe: HTMLIFrameElement,
selector: string,
target: string | { handle: string },
properties: string[],
): Promise<Record<string, string> | null> {
const reply = await previewRequest(iframe, "computed-styles", { selector, properties });
const element = typeof target === "string" ? { selector: target } : { handle: target.handle };
const reply = await previewRequest(iframe, "computed-styles", { ...element, properties });
const styles: unknown = reply?.styles;
if (typeof styles !== "object" || styles === null) return null;
const read: Record<string, string> = {};
@@ -7,6 +7,7 @@ import {
MAX_DESCRIBE_HANDLES,
type EditingElementDescription,
type EditingElementHit,
type EditingElementMatch,
type EditingElementSource,
} from "@hyperframes/core/runtime/editing-port";
import { resolveElementSourceFile } from "../../components/editor/domEditingDom";
@@ -96,6 +97,32 @@ export async function describePreviewElements(
});
}
/** Each handle's ancestors, parent first; null for an element the frame no longer has. */
export async function previewAncestors(
iframe: HTMLIFrameElement,
handles: readonly string[],
): Promise<Array<string[] | null> | null> {
if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
const reply = await previewRequest(iframe, "ancestors", { handles: [...handles] });
const chains: unknown = reply?.ancestors;
if (!Array.isArray(chains) || chains.length !== handles.length) return null;
return chains.map((chain) =>
Array.isArray(chain) && chain.every(isHandle) ? (chain as string[]) : null,
);
}
/** The frame's matches for `selector` in document order; null when the runtime cannot answer. */
export async function queryPreviewElements(
iframe: HTMLIFrameElement,
selector: string,
): Promise<{ matches: EditingElementMatch[]; truncated: boolean } | null> {
const reply = await previewRequest(iframe, "query", { selector });
const matches: unknown = reply?.matches;
if (!Array.isArray(matches) || typeof reply?.truncated !== "boolean") return null;
const ok = matches.every((m) => isFields(m) && isHandle(m.handle) && isSource(m.source));
return ok ? { matches: matches as EditingElementMatch[], truncated: reply.truncated } : null;
}
/** `getSourceFileForElement` for the frame's own element. */
export function previewElementSourceFile(
element: PreviewElement,