feat(core): runtime element handles for the editing channel (#7603)

* feat(core): runtime element handles for the editing channel

The runtime gives each element a numeric handle for one page load and
answers two new editing-port requests: `elements-at-point` (the stack under
a viewport point) and `describe` (handles to plain-data descriptions). Each
description carries the element's stable selector, the source facts Studio
resolves to a file, earlier class-selector matches counted per source,
attributes, inline styles, text, child handles and its client rect.

The stable-selector rule and source-attribute read move to core so Studio
and the runtime address elements one way; Studio re-exports them and
resolves a description's source file and selector index with its own map.

Studio adds `PreviewElement` (a checked description) and client helpers.
Every channel read now gives up after the agent probe when the frame's
runtime has no editing agent, as the seek wait already did. `computed-styles`
accepts custom property names with any case or `_`.

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

* fix(core): per-load element handles and a light elements-at-point reply

Handles are now "<load>:<n>" strings, where the load id is random per page
load, so a handle from an earlier load reads as null like a removed
element. `describe` checks the exact format.

`elements-at-point` returns only {handle, tag, rect}; callers describe the
one they keep. Descriptions cap each attribute and inline-style value, keep
only a `data:` value's header, leave <script> and <style> text out, and say
when anything was cut. A handle's entry goes once its element is collected
or found disconnected.

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

* fix(core): draw the element-handle load id on first use

A render seeds crypto.getRandomValues from virtual time, so drawing the
load id when the runtime loads shifted every random value the composition
drew after it, and the random-stagger-workers render no longer matched its
baseline. The id is now drawn the first time a handle is made, which a
render never does.

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

* fix(core): keep a parked element's handle, and cut data: headers only from values

A scene the preview parks and puts back keeps its element handles: an entry
now goes only once its element is garbage-collected. Text that starts with
"data:" is no longer cut to a header; that rule applies to attribute and
inline-style values.

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 14:13:18 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent cc47f7ea74
commit e1ddb2e162
11 changed files with 1008 additions and 101 deletions
+62 -1
View File
@@ -135,7 +135,15 @@ describe("installEditingAgent", () => {
ok: true,
result: {
version: 1,
kinds: ["hello", "runtime-snapshot", "wait-for-seek", "set-loop-start", "computed-styles"],
kinds: [
"hello",
"runtime-snapshot",
"wait-for-seek",
"set-loop-start",
"computed-styles",
"elements-at-point",
"describe",
],
},
});
expect((await ask(port, { v: 1, id: 2, kind: "runtime-snapshot", params: {} })).result).toEqual(
@@ -221,6 +229,44 @@ describe("installEditingAgent", () => {
22,
"invalid-params",
],
...[
{ y: 1 },
{ x: 1, y: Number.NaN },
{ x: "1", y: 1 },
{ x: 1, y: Infinity },
{ x: 1, y: 2, z: 3 },
].map((params, index) => [
{ v: 1, id: 30 + index, kind: "elements-at-point", params },
30 + index,
"invalid-params",
]),
...[
{},
{ handles: [] },
{ handles: [1] },
{ handles: ["1"] },
{ handles: ["0123456789abcdef"] },
{ handles: ["0123456789abcdef:0"] },
{ handles: ["0123456789abcdef:01"] },
{ handles: ["0123456789ABCDEF:1"] },
{ handles: ["0123456789abcde:1"] },
{ handles: ["0123456789abcdef:1 "] },
{ handles: [`0123456789abcdef:${"9".repeat(16)}`] },
{ handles: Array(257).fill("0123456789abcdef:1") },
{ handles: ["0123456789abcdef:1"], extra: 1 },
{ handles: { 0: "0123456789abcdef:1", length: 1 } },
].map((params, index) => [
{ v: 1, id: 40 + index, kind: "describe", params },
40 + 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 } },
60 + index,
"invalid-params",
],
),
])("rejects %j with a typed error", async (request, id, code) => {
const setLoopStart = vi.fn();
window.__hf = { setLoopStart };
@@ -250,6 +296,21 @@ describe("installEditingAgent", () => {
});
});
it("reads custom properties whose names use any case or an underscore", async () => {
document.body.innerHTML = `<p id="title" style="--Brand_Color: red; --x2: 4px">Hi</p>`;
const properties = ["--Brand_Color", "--x2", "--é"];
const reply = await ask(connectedPort(), {
v: 1,
id: 1,
kind: "computed-styles",
params: { selector: "#title", properties },
});
expect(reply).toMatchObject({ ok: true });
expect(Object.keys((reply.result as { styles: object }).styles)).toEqual(
expect.arrayContaining(["--Brand_Color", "--x2"]),
);
});
it("replies failed when a handler rejects or its result cannot be cloned", async () => {
window.__hfWaitForSeekCompletion = () => Promise.reject(new Error("seek lost"));
const port = connectedPort();
@@ -20,6 +20,7 @@ import {
type EditingResult,
} from "./editingPort";
import type { ClipNode } from "./clipTree";
import { describeHandles, elementsAtPoint } from "./editingHandles";
import { getLogicalOpacity } from "../studioPreviewMark";
type Handlers = {
@@ -68,6 +69,8 @@ const HANDLERS: Handlers = {
}
return { styles };
},
"elements-at-point": ({ x, y }) => ({ elements: elementsAtPoint(x, y) }),
describe: ({ handles }) => ({ elements: describeHandles(handles) }),
};
function serve(port: MessagePort): void {
+150
View File
@@ -0,0 +1,150 @@
// How an element is addressed in source: one rule for Studio and the runtime's editing agent.
/** Names an element's source file. The parent resolves it: `file`, else its composition map. */
export interface EditingElementSource {
/** `data-composition-file`, else `data-composition-src`, of the nearest element with either. */
file: string | null;
/** The nearest `data-composition-id`, and that element's `data-hf-original-composition-id`. */
compositionId: string | null;
originalCompositionId: string | null;
}
/** `<load>:<n>`, never reused. One from another page load, or of a removed element, reads as null. */
export type EditingElementHandle = string;
export const EDITING_ELEMENT_HANDLE = /^[0-9a-f]{16}:[1-9][0-9]{0,14}$/;
export interface EditingRect {
x: number;
y: number;
width: number;
height: number;
}
export interface EditingElementHit {
handle: EditingElementHandle;
tag: string;
/** `getBoundingClientRect()`, in the frame's CSS pixels. */
rect: EditingRect;
}
/**
* An element as plain data, cut at the MAX_ELEMENT_* limits; a `data:` value keeps only its header.
* `truncated` says something was cut, so the description is not safe to write back to source.
*/
export interface EditingElementDescription extends EditingElementHit {
parent: EditingElementHandle | null;
id: string | null;
selector: string | null;
/**
* A class selector's earlier matches, counted per source. The element's index in its file is the
* sum of the counts whose source resolves to that file. Null for other selectors, or too many.
*/
matchesBefore: Array<{ source: EditingElementSource; count: number }> | null;
source: EditingElementSource;
/** The element or an ancestor carries `data-timeline-locked`. */
locked: boolean;
/** Every attribute but `style`. */
attributes: Array<[name: string, value: string]>;
inlineStyles: Record<string, string>;
/** Rendered-tree text: `<script>` and `<style>` contents are left out, as from `children`. */
text: string;
children: Array<{ handle: EditingElementHandle } | { text: string }>;
truncated: boolean;
}
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;
// fallow-ignore-next-line complexity
function escapeCssIdentifier(value: string): string {
const css = globalThis.CSS as { escape?: (input: string) => string } | undefined;
if (typeof css?.escape === "function") return css.escape(value);
if (value === "-") return "\\-";
let escaped = "";
for (let index = 0; index < value.length; index += 1) {
const char = value[index] ?? "";
const code = char.charCodeAt(0);
if (code === 0) {
escaped += "�";
continue;
}
const isDigit = code >= 48 && code <= 57;
const isUpperAlpha = code >= 65 && code <= 90;
const isLowerAlpha = code >= 97 && code <= 122;
const isControl = (code >= 1 && code <= 31) || code === 127;
const isLeadingDigit = index === 0 && isDigit;
const isSecondDigitAfterDash = index === 1 && value.startsWith("-") && isDigit;
if (isControl || isLeadingDigit || isSecondDigitAfterDash) {
escaped += `\\${code.toString(16)} `;
continue;
}
if (isUpperAlpha || isLowerAlpha || isDigit || char === "-" || char === "_" || code >= 128) {
escaped += char;
continue;
}
escaped += `\\${char}`;
}
return escaped;
}
export function escapeCssString(value: string): string {
return value
.replace(/\\/g, "\\\\")
.replace(/"/g, '\\"')
.replace(/\n/g, "\\a ")
.replace(/\r/g, "\\d ")
.replace(/\f/g, "\\c ");
}
export function buildStableSelector(el: Element): string | undefined {
if (el.id) return `#${escapeCssIdentifier(el.id)}`;
const compositionId = el.getAttribute("data-composition-id");
if (compositionId) return `[data-composition-id="${escapeCssString(compositionId)}"]`;
// Group wrappers carry no id/class; their data-hf-group value is the unique,
// stable handle the source mutations write — use it so the wrapper is
// selectable, patchable (move/scale), and addressable for ungroup.
const group = el.getAttribute("data-hf-group");
if (group) return `[data-hf-group="${escapeCssString(group)}"]`;
return getPreferredClassSelector(el);
}
export function getPreferredClassSelector(el: Element): string | undefined {
const classes = Array.from(el.classList)
.map((value) => value.trim())
.filter(Boolean);
if (classes.length === 0) return undefined;
const preferred =
classes.find((value) => value !== "clip" && !value.startsWith("__hf-")) ?? classes[0];
return preferred ? `.${escapeCssIdentifier(preferred)}` : undefined;
}
function closestWithAny(el: Element, names: readonly string[]): Element | null {
for (let node: Element | null = el; node; node = node.parentElement) {
const candidate = node;
if (names.some((name) => candidate.hasAttribute(name))) return candidate;
}
return null;
}
export function readElementSource(el: Element): EditingElementSource {
const host = closestWithAny(el, ["data-composition-file", "data-composition-src"]);
const root = closestWithAny(el, ["data-composition-id"]);
return {
file:
host?.getAttribute("data-composition-file") ??
host?.getAttribute("data-composition-src") ??
null,
compositionId: root?.getAttribute("data-composition-id") ?? null,
originalCompositionId: root?.getAttribute("data-hf-original-composition-id") ?? null,
};
}
@@ -0,0 +1,204 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { installEditingAgent } from "./editingAgent";
import { trackedHandleCount } from "./editingHandles";
import {
EDITING_ELEMENT_HANDLE,
MAX_ELEMENT_TEXT,
MAX_ELEMENT_VALUE,
type EditingElementDescription,
type EditingElementHit,
} from "./editingPort";
const CONNECT = { source: "hf-parent", type: "editing-connect", v: 1 };
type Reply<T> = { ok: boolean; result?: { elements: T[] }; error?: { code: string } };
describe("element handles over the editing port", () => {
let port: MessagePort;
let agent: { dispose: () => void };
let lastId = 0;
const ask = <T>(kind: string, params: unknown): Promise<Reply<T>> =>
new Promise((resolve) => {
port.onmessage = (event) => resolve(event.data);
port.postMessage({ v: 1, id: ++lastId, kind, params });
});
const describeHandles = async (handles: string[]) =>
(await ask<EditingElementDescription | null>("describe", { handles })).result!.elements;
const atPoint = async () =>
(await ask<EditingElementHit>("elements-at-point", { x: 5, y: 6 })).result!.elements;
const describeOne = async (element: Element) => {
stackAtPoint(element);
const [hit] = await atPoint();
return (await describeHandles([hit!.handle]))[0]!;
};
const stackAtPoint = (...elements: Element[]) =>
Object.defineProperty(document, "elementsFromPoint", {
configurable: true,
value: vi.fn(() => elements),
});
beforeEach(() => {
const iframe = document.createElement("iframe");
document.body.appendChild(iframe);
const parent = iframe.contentWindow!;
const handoff = vi.fn();
parent.postMessage = handoff as unknown as Window["postMessage"];
agent = installEditingAgent(parent);
window.dispatchEvent(new MessageEvent("message", { source: parent, data: CONNECT }));
port = (handoff.mock.calls[0]![2] as MessagePort[])[0]!;
});
afterEach(() => {
agent.dispose();
document.body.innerHTML = "";
delete (document as { elementsFromPoint?: unknown }).elementsFromPoint;
});
it("answers a point with handle, tag and rect only, and describes a kept handle in plain data", async () => {
document.body.innerHTML = `
<div data-composition-id="card__hf1" data-hf-original-composition-id="card" data-timeline-locked>
<p class="clip title" data-hf-id="hf-1" data-start="2" style="color: red; left: 4px">Hi <b>there</b></p>
</div>`;
const title = document.querySelector("p")!;
stackAtPoint(title, title.parentElement!);
const [top, below] = await atPoint();
expect(document.elementsFromPoint).toHaveBeenCalledWith(5, 6);
expect(top).toEqual({
handle: expect.stringMatching(EDITING_ELEMENT_HANDLE),
tag: "p",
rect: { x: 0, y: 0, width: 0, height: 0 },
});
expect(below).toEqual({ handle: expect.any(String), tag: "div", rect: expect.any(Object) });
const [described, root] = await describeHandles([top!.handle, below!.handle]);
expect(described).toEqual({
handle: top!.handle,
parent: below!.handle,
tag: "p",
id: null,
selector: ".title",
matchesBefore: [],
source: { file: null, compositionId: "card__hf1", originalCompositionId: "card" },
locked: true,
attributes: [
["class", "clip title"],
["data-hf-id", "hf-1"],
["data-start", "2"],
],
inlineStyles: { color: "red", left: "4px" },
text: "Hi there",
children: [{ text: "Hi " }, { handle: expect.stringMatching(EDITING_ELEMENT_HANDLE) }],
rect: { x: 0, y: 0, width: 0, height: 0 },
truncated: false,
});
expect(root).toMatchObject({ tag: "div", selector: '[data-composition-id="card__hf1"]' });
expect(root!.matchesBefore).toBeNull();
expect(JSON.parse(JSON.stringify(described))).toEqual(described);
});
it("keeps an element's handle for the page load, answering null only while it is detached", async () => {
document.body.innerHTML = `<p id="a">A</p><p id="b">B</p>`;
const [a, b] = Array.from(document.querySelectorAll("p"));
stackAtPoint(a!, b!);
const [first, second] = await atPoint();
expect(first!.handle).not.toBe(second!.handle);
const again = await describeHandles([second!.handle, first!.handle]);
expect(again.map((entry) => entry?.id)).toEqual(["b", "a"]);
// The preview parks a scene with replaceWith and later puts the same nodes back.
const placeholder = document.createElement("template");
a!.replaceWith(placeholder);
const tracked = trackedHandleCount();
const unknown = first!.handle.replace(/:\d+$/, ":999999");
expect(await describeHandles([first!.handle, unknown, second!.handle])).toEqual([
null,
null,
expect.objectContaining({ id: "b" }),
]);
expect(trackedHandleCount()).toBe(tracked);
placeholder.replaceWith(a!);
expect(await describeHandles([first!.handle])).toEqual([expect.objectContaining({ id: "a" })]);
});
it("answers null for a handle from an earlier load, even one with the same number", async () => {
document.body.innerHTML = `<p id="a">A</p>`;
const element = document.querySelector("p")!;
stackAtPoint(element);
const [current] = await atPoint();
// A fresh module instance is a fresh page load: a new load id, numbering from 1 again.
vi.resetModules();
const earlierLoad = await import("./editingHandles");
const [earlier] = earlierLoad.elementsAtPoint(0, 0);
expect(earlier!.handle).not.toBe(current!.handle);
expect(await describeHandles([earlier!.handle])).toEqual([null]);
const sameNumber = `${earlier!.handle.split(":")[0]}:${current!.handle.split(":")[1]}`;
expect(await describeHandles([sameNumber, current!.handle])).toEqual([
null,
expect.objectContaining({ id: "a" }),
]);
expect(earlierLoad.describeHandles([current!.handle])).toEqual([null]);
});
it("draws its load id on first use, so loading the runtime leaves a seeded RNG alone", async () => {
vi.resetModules();
const draw = vi.spyOn(crypto, "getRandomValues");
try {
const fresh = await import("./editingHandles");
expect(draw).not.toHaveBeenCalled();
document.body.innerHTML = `<p>A</p>`;
stackAtPoint(document.querySelector("p")!);
fresh.elementsAtPoint(0, 0);
fresh.elementsAtPoint(0, 0);
expect(draw).toHaveBeenCalledOnce();
} finally {
draw.mockRestore();
}
});
it("cuts long values, keeps only a data: header, and leaves script and style text out", async () => {
const long = "x".repeat(MAX_ELEMENT_VALUE + 50);
document.body.innerHTML = `<div class="card" title="${long}" style="--note: ${long}">
<img src="data:image/png;base64,${"A".repeat(5000)}"><style>.a{color:red}</style>
<script>window.secretish = 1</script><span>Shown</span></div><style>.b{}</style>`;
const card = document.querySelector("div")!;
const described = await describeOne(card);
expect(described.truncated).toBe(true);
expect(described.attributes[1]).toEqual(["title", long.slice(0, MAX_ELEMENT_VALUE)]);
expect(described.inlineStyles["--note"]!.length).toBeLessThanOrEqual(MAX_ELEMENT_VALUE);
expect(described.text.replace(/\s+/g, " ").trim()).toBe("Shown");
const img = await describeOne(card.querySelector("img")!);
expect(img.attributes).toEqual([["src", "data:image/png;base64,"]]);
expect(img.truncated).toBe(true);
const style = await describeOne(card.querySelector("style")!);
expect(style).toMatchObject({ text: "", children: [], truncated: false });
document.body.innerHTML = `<p>data: 42 users, up 3%</p>`;
const dataText = await describeOne(document.querySelector("p")!);
expect(dataText).toMatchObject({ text: "data: 42 users, up 3%", truncated: false });
document.body.innerHTML = `<p>${"y".repeat(MAX_ELEMENT_TEXT + 10)}</p>`;
const text = await describeOne(document.querySelector("p")!);
expect(text.text).toHaveLength(MAX_ELEMENT_TEXT);
expect(text.children).toEqual([{ text: "y".repeat(MAX_ELEMENT_TEXT) }]);
expect(text.truncated).toBe(true);
});
it("counts a class selector's earlier matches per source", async () => {
document.body.innerHTML = `
<div class="tile"></div>
<div data-composition-file="cards.html"><div class="tile"></div><div class="tile"></div></div>
<div data-composition-src="cards.html"><div class="tile" id="t"></div></div>
<div data-composition-file="cards.html"><div class="tile"></div></div>`;
const last = await describeOne(document.querySelectorAll(".tile")[4]!);
expect(last.source.file).toBe("cards.html");
expect(last.matchesBefore).toEqual([
{ source: { file: null, compositionId: null, originalCompositionId: null }, count: 1 },
{
source: { file: "cards.html", compositionId: null, originalCompositionId: null },
count: 3,
},
]);
});
});
+190
View File
@@ -0,0 +1,190 @@
/**
* Element handles for the editing channel. The parent never receives an element, only a handle this
* module gives it and the plain data `describeElement` reads from it. Handles live for one page load:
* the maps are module state, and an entry goes once its element is garbage-collected.
*/
import {
buildStableSelector,
MAX_ELEMENT_ENTRIES,
MAX_ELEMENT_TEXT,
MAX_ELEMENT_VALUE,
MAX_POINT_STACK,
MAX_SOURCE_GROUPS,
readElementSource,
type EditingElementDescription,
type EditingElementHandle,
type EditingElementHit,
type EditingElementSource,
} from "./editingElement";
// Drawn on first use, not at load: a render seeds getRandomValues, and a draw here would shift the
// composition's own random values.
let load = "";
const loadId = () =>
(load ||= Array.from(crypto.getRandomValues(new Uint8Array(8)), (byte) =>
byte.toString(16).padStart(2, "0"),
).join(""));
const numbers = new WeakMap<Element, number>();
const elements = new Map<number, WeakRef<Element>>();
const collected = new FinalizationRegistry<number>((n) => {
if (!elements.get(n)?.deref()) elements.delete(n);
});
let lastNumber = 0;
function handleFor(element: Element): EditingElementHandle {
let n = numbers.get(element);
if (n === undefined) {
n = ++lastNumber;
numbers.set(element, n);
collected.register(element, n);
}
if (!elements.has(n)) elements.set(n, new WeakRef(element));
return `${loadId()}:${n}`;
}
/** The live element in this document behind `handle`, else null. */
function elementForHandle(handle: EditingElementHandle): Element | null {
const [handleLoad, count] = handle.split(":");
if (handleLoad !== loadId()) return null;
const n = Number(count);
const element = elements.get(n)?.deref();
if (!element) elements.delete(n);
// A parked scene's nodes come back, so a disconnected element keeps its entry.
return element?.isConnected && element.ownerDocument === document ? element : null;
}
/** How many elements hold a live entry; for tests of the bound. */
export const trackedHandleCount = () => elements.size;
const sameSource = (a: EditingElementSource, b: EditingElementSource) =>
a.file === b.file &&
a.compositionId === b.compositionId &&
a.originalCompositionId === b.originalCompositionId;
function matchesBefore(element: Element, selector: string | undefined) {
if (!selector?.startsWith(".")) return null;
const groups: Array<{ source: EditingElementSource; count: number }> = [];
let matches: NodeListOf<Element>;
try {
matches = document.querySelectorAll(selector);
} catch {
return null;
}
for (const match of matches) {
if (match === element) return groups;
const source = readElementSource(match);
const group = groups.find((entry) => sameSource(entry.source, source));
if (group) group.count += 1;
else if (groups.push({ source, count: 1 }) > MAX_SOURCE_GROUPS) return null;
}
return null;
}
const NO_TEXT = new Set(["script", "style"]);
type Cut = { truncated: boolean };
/** A `dataUrl` value starting `data:` keeps only its header; text is cut by length alone. */
function cut(value: string, limit: number, state: Cut, dataUrl = false): string {
const header = dataUrl && value.startsWith("data:") ? value.slice(0, value.indexOf(",") + 1) : "";
const kept = header || value.slice(0, limit);
if (kept.length < value.length) state.truncated = true;
return kept.slice(0, limit);
}
function renderedText(element: Element, state: Cut): string {
if (NO_TEXT.has(element.localName)) return "";
let text = "";
const walker = document.createTreeWalker(
element,
NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
{
acceptNode: (node) =>
node.nodeType === Node.ELEMENT_NODE && NO_TEXT.has((node as Element).localName)
? NodeFilter.FILTER_REJECT
: NodeFilter.FILTER_ACCEPT,
},
);
for (let node = walker.nextNode(); node; node = walker.nextNode()) {
if (node.nodeType !== Node.TEXT_NODE) continue;
text += node.nodeValue;
if (text.length > MAX_ELEMENT_TEXT) break;
}
return cut(text, MAX_ELEMENT_TEXT, state);
}
function inlineStyles(element: Element, state: Cut): Record<string, string> {
const styles: Record<string, string> = {};
const declared = (element as Partial<ElementCSSInlineStyle>).style;
if (!declared) return styles;
if (declared.length > MAX_ELEMENT_ENTRIES) state.truncated = true;
for (let index = 0; index < Math.min(declared.length, MAX_ELEMENT_ENTRIES); index += 1) {
const name = declared.item(index);
styles[name] = cut(declared.getPropertyValue(name), MAX_ELEMENT_VALUE, state, true);
}
return styles;
}
function attributes(element: Element, state: Cut): EditingElementDescription["attributes"] {
const kept = Array.from(element.attributes).filter((attribute) => attribute.name !== "style");
if (kept.length > MAX_ELEMENT_ENTRIES) state.truncated = true;
return kept
.slice(0, MAX_ELEMENT_ENTRIES)
.map((attribute) => [attribute.name, cut(attribute.value, MAX_ELEMENT_VALUE, state, true)]);
}
function children(element: Element, state: Cut): EditingElementDescription["children"] {
const out: EditingElementDescription["children"] = [];
const textless = NO_TEXT.has(element.localName);
for (const node of element.childNodes) {
if (out.length >= MAX_ELEMENT_ENTRIES) {
state.truncated = true;
break;
}
if (node.nodeType === Node.ELEMENT_NODE) out.push({ handle: handleFor(node as Element) });
else if (node.nodeType === Node.TEXT_NODE && !textless)
out.push({ text: cut(node.nodeValue ?? "", MAX_ELEMENT_TEXT, state) });
}
return out;
}
function hit(element: Element): EditingElementHit {
const rect = element.getBoundingClientRect();
return {
handle: handleFor(element),
tag: element.tagName.toLowerCase(),
rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
};
}
function describeElement(element: Element): EditingElementDescription {
const selector = buildStableSelector(element);
const state: Cut = { truncated: false };
return {
...hit(element),
parent: element.parentElement ? handleFor(element.parentElement) : null,
id: element.id || null,
selector: selector ?? null,
matchesBefore: matchesBefore(element, selector),
source: readElementSource(element),
locked: element.closest("[data-timeline-locked]") !== null,
attributes: attributes(element, state),
inlineStyles: inlineStyles(element, state),
text: renderedText(element, state),
children: children(element, state),
truncated: state.truncated,
};
}
export function elementsAtPoint(x: number, y: number): EditingElementHit[] {
return document.elementsFromPoint(x, y).slice(0, MAX_POINT_STACK).map(hit);
}
export function describeHandles(
requested: readonly EditingElementHandle[],
): Array<EditingElementDescription | null> {
return requested.map((handle) => {
const element = elementForHandle(handle);
return element ? describeElement(element) : null;
});
}
@@ -60,7 +60,15 @@ describe("createEditingPortClient", () => {
await client.ready;
expect(await client.request("hello", {})).toEqual({
version: 1,
kinds: ["hello", "runtime-snapshot", "wait-for-seek", "set-loop-start", "computed-styles"],
kinds: [
"hello",
"runtime-snapshot",
"wait-for-seek",
"set-loop-start",
"computed-styles",
"elements-at-point",
"describe",
],
});
} finally {
agent.dispose();
+62 -2
View File
@@ -9,9 +9,35 @@
* otherwise takes straight off the frame's window, which an opaque-origin
* preview does not allow.
*/
import {
EDITING_ELEMENT_HANDLE,
MAX_DESCRIBE_HANDLES,
type EditingElementDescription,
type EditingElementHandle,
type EditingElementHit,
} from "./editingElement";
import type { RuntimeTimelineMessage } from "./types";
import { wallClearTimeout, wallSetTimeout } from "./wallClock";
export {
buildStableSelector,
escapeCssString,
getPreferredClassSelector,
readElementSource,
EDITING_ELEMENT_HANDLE,
MAX_DESCRIBE_HANDLES,
MAX_ELEMENT_ENTRIES,
MAX_ELEMENT_TEXT,
MAX_ELEMENT_VALUE,
MAX_POINT_STACK,
MAX_SOURCE_GROUPS,
type EditingElementDescription,
type EditingElementHandle,
type EditingElementHit,
type EditingElementSource,
type EditingRect,
} from "./editingElement";
export const EDITING_PROTOCOL_VERSION = 1 as const;
/** Parent to frame, on the window: asks the runtime for the port. */
export const EDITING_CONNECT = "editing-connect";
@@ -24,6 +50,8 @@ export const EDITING_REQUEST_KINDS = [
"wait-for-seek",
"set-loop-start",
"computed-styles",
"elements-at-point",
"describe",
] as const;
export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number];
@@ -54,6 +82,16 @@ export interface EditingRequests {
params: { selector: string; 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. */
"elements-at-point": {
params: { x: number; y: number };
result: { elements: EditingElementHit[] };
};
/** One entry per handle, in order; null for an unknown or removed element. */
describe: {
params: { handles: EditingElementHandle[] };
result: { elements: Array<EditingElementDescription | null> };
};
}
export type EditingParams<K extends EditingRequestKind> = EditingRequests[K]["params"];
export type EditingResult<K extends EditingRequestKind> = EditingRequests[K]["result"];
@@ -86,7 +124,11 @@ export function isPlainRecord(value: unknown): value is Record<string, unknown>
const MAX_SELECTOR_LENGTH = 2_000;
const MAX_STYLE_PROPERTIES = 64;
const STYLE_PROPERTY = /^(--)?[a-z][a-z0-9-]*$/;
const MAX_STYLE_PROPERTY_LENGTH = 256;
const STYLE_PROPERTY = /^(?:[a-z][a-z0-9-]*|--[\w\u0080-\uffff-]+)$/;
const hasKeys = (params: unknown, keys: string): params is Record<string, unknown> =>
isPlainRecord(params) && Object.keys(params).sort().join() === keys;
const noParams = (params: unknown): NoParams | null =>
params === undefined || (isPlainRecord(params) && Object.keys(params).length === 0) ? {} : null;
@@ -115,10 +157,28 @@ const PARAM_PARSERS: {
}
if (!Array.isArray(properties) || properties.length > MAX_STYLE_PROPERTIES) return null;
const names = properties.filter(
(name): name is string => typeof name === "string" && STYLE_PROPERTY.test(name),
(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;
},
"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;
},
};
/** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */
@@ -5,6 +5,13 @@
*/
import { getLogicalOpacity } from "@hyperframes/core/studio-preview-mark";
import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
import {
buildStableSelector,
escapeCssString,
getPreferredClassSelector,
readElementSource,
type EditingElementSource,
} from "@hyperframes/core/runtime/editing-port";
import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
import { CURATED_STYLE_PROPERTIES } from "./domEditingTypes";
@@ -36,6 +43,8 @@ export function isEditableTextLeaf(el: HTMLElement): boolean {
}
export { getLogicalOpacity };
// One addressing rule for Studio and the runtime that describes elements to it.
export { buildStableSelector, escapeCssString };
/** Does this node render AT ALL, ignoring what it inherits? Sole owner of the
* rule; the walk below only decides which nodes to ask it about. */
@@ -171,33 +180,24 @@ export function getCompositionSourceMapRevision(): number {
return compositionSourceMapRevision;
}
function sourceFromCompositionId(ownerRoot: HTMLElement | null): string | undefined {
if (!ownerRoot || compositionSourceMap.size === 0) return undefined;
// The runtime may rename the mounted id to a runtime-unique one, preserving the
// authored id on `data-hf-original-composition-id` — prefer that, then the current id.
const authored = ownerRoot.getAttribute("data-hf-original-composition-id");
const current = ownerRoot.getAttribute("data-composition-id");
return (
(authored ? compositionSourceMap.get(authored) : undefined) ??
(current ? compositionSourceMap.get(current) : undefined)
);
/** The source file `source` names (see `EditingElementSource`), with this project's composition map. */
export function resolveElementSourceFile(
source: EditingElementSource,
activeCompositionPath: string | null,
): string {
const { file, compositionId, originalCompositionId } = source;
const mapped = compositionSourceMap.size
? ((originalCompositionId ? compositionSourceMap.get(originalCompositionId) : undefined) ??
(compositionId ? compositionSourceMap.get(compositionId) : undefined))
: undefined;
return file ?? mapped ?? activeCompositionPath ?? "index.html";
}
export function getSourceFileForElement(
el: HTMLElement,
activeCompositionPath: string | null,
): { sourceFile: string; compositionPath: string } {
const sourceHost = findClosestByAttribute(el, ["data-composition-file", "data-composition-src"]);
const ownerRoot = findClosestByAttribute(el, ["data-composition-id"]);
const sourceFile =
sourceHost?.getAttribute("data-composition-file") ??
sourceHost?.getAttribute("data-composition-src") ??
ownerRoot?.getAttribute("data-composition-file") ??
ownerRoot?.getAttribute("data-composition-src") ??
sourceFromCompositionId(ownerRoot) ??
activeCompositionPath ??
"index.html";
const sourceFile = resolveElementSourceFile(readElementSource(el), activeCompositionPath);
return {
sourceFile,
compositionPath: sourceFile,
@@ -228,49 +228,6 @@ export function normalizeTimelineCompositionSource(value: string | undefined): s
// ─── CSS escaping ─────────────────────────────────────────────────────────────
function escapeCssIdentifier(value: string): string {
const css = globalThis.CSS as { escape?: (input: string) => string } | undefined;
if (typeof css?.escape === "function") return css.escape(value);
if (value === "-") return "\\-";
let escaped = "";
for (let index = 0; index < value.length; index += 1) {
const char = value[index] ?? "";
const code = char.charCodeAt(0);
if (code === 0) {
escaped += "�";
continue;
}
const isDigit = code >= 48 && code <= 57;
const isUpperAlpha = code >= 65 && code <= 90;
const isLowerAlpha = code >= 97 && code <= 122;
const isControl = (code >= 1 && code <= 31) || code === 127;
const isLeadingDigit = index === 0 && isDigit;
const isSecondDigitAfterDash = index === 1 && value.startsWith("-") && isDigit;
if (isControl || isLeadingDigit || isSecondDigitAfterDash) {
escaped += `\\${code.toString(16)} `;
continue;
}
if (isUpperAlpha || isLowerAlpha || isDigit || char === "-" || char === "_" || code >= 128) {
escaped += char;
continue;
}
escaped += `\\${char}`;
}
return escaped;
}
export function escapeCssString(value: string): string {
return value
.replace(/\\/g, "\\\\")
.replace(/"/g, '\\"')
.replace(/\n/g, "\\a ")
.replace(/\r/g, "\\d ")
.replace(/\f/g, "\\c ");
}
export function querySelectorAllSafely(doc: Document, selector: string): Element[] {
try {
return Array.from(doc.querySelectorAll(selector));
@@ -293,31 +250,6 @@ function humanizeIdentifier(value: string): string {
// ─── CSS selector building ────────────────────────────────────────────────────
export function buildStableSelector(el: HTMLElement): string | undefined {
if (el.id) return `#${escapeCssIdentifier(el.id)}`;
const compositionId = el.getAttribute("data-composition-id");
if (compositionId) return `[data-composition-id="${escapeCssString(compositionId)}"]`;
// Group wrappers carry no id/class; their data-hf-group value is the unique,
// stable handle the source mutations write — use it so the wrapper is
// selectable, patchable (move/scale), and addressable for ungroup.
const group = el.getAttribute("data-hf-group");
if (group) return `[data-hf-group="${escapeCssString(group)}"]`;
return getPreferredClassSelector(el);
}
function getPreferredClassSelector(el: HTMLElement): string | undefined {
const classes = Array.from(el.classList)
.map((value) => value.trim())
.filter(Boolean);
if (classes.length === 0) return undefined;
const preferred =
classes.find((value) => value !== "clip" && !value.startsWith("__hf-")) ?? classes[0];
return preferred ? `.${escapeCssIdentifier(preferred)}` : undefined;
}
// fallow-ignore-next-line complexity
export function buildElementLabel(el: HTMLElement): string {
const compositionId =
@@ -1,7 +1,10 @@
// Runtime-state reads over a preview frame's editing port; an opaque frame's window is out of reach.
import {
createEditingPortClient,
type EditingParams,
type EditingPortClient,
type EditingRequestKind,
type EditingResult,
} from "@hyperframes/core/runtime/editing-port";
import type { ClipManifest, IframeWindow } from "./playbackTypes";
@@ -51,9 +54,7 @@ export function setFrameLoopStart(iframe: HTMLIFrameElement, seconds: number | n
export const AGENT_PROBE_MS = 1_000;
/** Gives up after AGENT_PROBE_MS with no port: a runtime without the editing agent never answers. */
export async function previewSeekPainted(iframe: HTMLIFrameElement, timeoutMs?: number) {
const client = previewEditingClient(iframe);
async function agentConnected(client: EditingPortClient): Promise<boolean> {
let timer: ReturnType<typeof setTimeout> | undefined;
const probe = new Promise<boolean>(
(resolve) => (timer = setTimeout(resolve, AGENT_PROBE_MS, false)),
@@ -66,12 +67,28 @@ export async function previewSeekPainted(iframe: HTMLIFrameElement, timeoutMs?:
probe,
]);
clearTimeout(timer);
if (connected) await client.request("wait-for-seek", {}, { timeoutMs }).catch(() => {});
return connected;
}
/** Null when no port comes within AGENT_PROBE_MS (a runtime without the editing agent), or on error. */
export async function previewRequest<K extends EditingRequestKind>(
iframe: HTMLIFrameElement,
kind: K,
params: EditingParams<K>,
timeoutMs?: number,
): Promise<EditingResult<K> | null> {
const client = previewEditingClient(iframe);
if (!(await agentConnected(client))) return null;
return client.request(kind, params, { timeoutMs }).catch(() => null);
}
export async function previewSeekPainted(iframe: HTMLIFrameElement, timeoutMs?: number) {
await previewRequest(iframe, "wait-for-seek", {}, timeoutMs);
}
/** The reply is frame data, so its shape is checked. */
export async function previewClipManifest(iframe: HTMLIFrameElement): Promise<ClipManifest | null> {
const snapshot = await previewEditingClient(iframe).request("runtime-snapshot", {});
const snapshot = await previewRequest(iframe, "runtime-snapshot", {});
const manifest: unknown = snapshot?.clipManifest;
if (typeof manifest !== "object" || manifest === null) return null;
const { clips, durationInFrames } = manifest as Partial<ClipManifest>;
@@ -86,9 +103,7 @@ export async function previewComputedStyles(
selector: string,
properties: string[],
): Promise<Record<string, string> | null> {
const reply = await previewEditingClient(iframe)
.request("computed-styles", { selector, properties })
.catch(() => null);
const reply = await previewRequest(iframe, "computed-styles", { selector, properties });
const styles: unknown = reply?.styles;
if (typeof styles !== "object" || styles === null) return null;
const read: Record<string, string> = {};
@@ -0,0 +1,167 @@
// @vitest-environment happy-dom
import { afterEach, describe, expect, it, vi } from "vitest";
import type { EditingElementDescription } from "@hyperframes/core/runtime/editing-port";
import {
describePreviewElements,
previewElementSelectorIndex,
previewElementSourceFile,
previewElementsAtPoint,
readPreviewElement,
type PreviewElement,
} from "./previewElements";
import { AGENT_PROBE_MS, previewComputedStyles } from "./previewChannel";
import {
getSelectorIndex,
getSourceFileForElement,
setCompositionSourceMap,
} from "../../components/editor/domEditingDom";
import { detachedFakeIframe, serveEditingRequests } from "../hooks/timelinePlayerTestHarness";
const closers: Array<() => void> = [];
afterEach(() => {
closers.splice(0).forEach((close) => close());
setCompositionSourceMap(new Map());
document.body.innerHTML = "";
});
/** A frame Studio cannot read; `answer` is its runtime, or it has none. */
function opaqueFrame(answer?: (kind: string, params: unknown) => unknown) {
const frame: Record<string, unknown> = { postMessage: () => {} };
const iframe = detachedFakeIframe(frame);
Object.defineProperty(iframe, "contentDocument", { value: null });
Object.defineProperty(frame, "document", {
get: () => {
throw new DOMException("blocked", "SecurityError");
},
});
const handed = vi.fn(answer ?? (() => null));
if (answer) closers.push(serveEditingRequests(frame, handed));
return { iframe, handed };
}
const NO_SOURCE = { file: null, compositionId: null, originalCompositionId: null };
const LOAD = "0123456789abcdef";
const h = (n: number) => `${LOAD}:${n}`;
function described(n: number, extra: Partial<EditingElementDescription> = {}) {
return {
handle: h(n),
parent: null,
tag: "div",
id: null,
selector: null,
matchesBefore: null,
source: NO_SOURCE,
locked: false,
attributes: [["data-hf-id", `hf-${n}`]],
inlineStyles: { left: "4px" },
text: "",
children: [{ text: "Hi" }, { handle: h(n + 1) }],
rect: { x: 1, y: 2, width: 3, height: 4 },
truncated: false,
...extra,
} as EditingElementDescription;
}
describe("readPreviewElement", () => {
it("takes a description with the wire shape and refuses anything off it", () => {
expect(readPreviewElement(described(1))).toEqual(described(1));
for (const bad of [
null,
[],
described(1, { handle: 1 as never }),
described(1, { handle: "1" }),
described(1, { handle: `${LOAD}:0` }),
described(1, { handle: `${LOAD.toUpperCase()}:1` }),
described(1, { parent: "x" }),
described(1, { tag: 1 as never }),
described(1, { source: { file: 1 } as never }),
described(1, { locked: "yes" as never }),
described(1, { attributes: [["a"]] as never }),
described(1, { inlineStyles: { left: 4 } as never }),
described(1, { children: [{ node: {} }] as never }),
described(1, { matchesBefore: [{ source: NO_SOURCE, count: -1 }] }),
described(1, { rect: { x: Number.NaN, y: 0, width: 0, height: 0 } }),
described(1, { truncated: undefined as never }),
]) {
expect(readPreviewElement(bad)).toBeNull();
}
});
});
describe("element requests over an opaque frame's port", () => {
it("asks for the stack under a point and keeps only well-formed entries", async () => {
const hit = { handle: h(1), tag: "p", rect: { x: 1, y: 2, width: 3, height: 4 } };
const bad = [
{ ...hit, handle: "x" },
{ ...hit, tag: 1 },
{ ...hit, rect: { x: 1 } },
];
const { iframe, handed } = opaqueFrame(() => ({ elements: [hit, ...bad] }));
expect(await previewElementsAtPoint(iframe, 10, 20)).toEqual([hit]);
expect(handed).toHaveBeenCalledWith("elements-at-point", { x: 10, y: 20 });
});
it("describes handles in order, with null for a gone element or a mismatched entry", async () => {
let reply: unknown = { elements: [described(2), null, described(9)] };
const { iframe, handed } = opaqueFrame(() => reply);
const asked = [h(2), h(3), h(4)];
expect(await describePreviewElements(iframe, asked)).toEqual([described(2), null, null]);
expect(handed).toHaveBeenCalledWith("describe", { handles: asked });
reply = { elements: [described(2)] };
expect(await describePreviewElements(iframe, [h(2), h(3)])).toBeNull();
handed.mockClear();
expect(await describePreviewElements(iframe, [])).toBeNull();
expect(await describePreviewElements(iframe, Array(257).fill(h(1)))).toBeNull();
expect(handed).not.toHaveBeenCalled();
});
it("gives up after the agent probe when the frame's runtime has no editing agent", async () => {
const { iframe } = opaqueFrame();
const started = Date.now();
const answers = await Promise.all([
previewComputedStyles(iframe, "#a", ["color"]),
previewElementsAtPoint(iframe, 1, 1),
describePreviewElements(iframe, [h(1)]),
]);
expect(answers).toEqual([null, null, null]);
expect(Date.now() - started).toBeLessThan(AGENT_PROBE_MS + 500);
});
});
describe("source file and selector index from a description", () => {
it("answers what Studio reads off the frame's own element", () => {
setCompositionSourceMap(new Map([["card", "cards.html"]]));
document.body.innerHTML = `
<div class="tile"></div>
<div data-composition-file="cards.html"><div class="tile"></div></div>
<div data-composition-id="card__hf2" data-hf-original-composition-id="card">
<div class="tile"></div><div class="tile"></div>
</div>`;
const target = document.querySelectorAll<HTMLElement>(".tile")[3]!;
const element = readPreviewElement(
described(7, {
selector: ".tile",
source: { file: null, compositionId: "card__hf2", originalCompositionId: "card" },
// As the runtime counts the matches before it: one per distinct source.
matchesBefore: [
{ source: NO_SOURCE, count: 1 },
{ source: { ...NO_SOURCE, file: "cards.html" }, count: 1 },
{
source: { file: null, compositionId: "card__hf2", originalCompositionId: "card" },
count: 1,
},
],
}),
) as PreviewElement;
const { sourceFile } = getSourceFileForElement(target, "index.html");
expect(previewElementSourceFile(element, "index.html")).toBe(sourceFile);
expect(sourceFile).toBe("cards.html");
const index = getSelectorIndex(document, target, ".tile", sourceFile, "index.html");
expect(previewElementSelectorIndex(element, "index.html")).toBe(index);
expect(index).toBe(2);
expect(previewElementSelectorIndex({ ...element, matchesBefore: null }, null)).toBeUndefined();
});
});
@@ -0,0 +1,117 @@
/**
* Elements of a preview frame Studio cannot script, by the handles its runtime gives them. A handle
* names an element for one load of the frame; after the frame loads again, describe it afresh.
*/
import {
EDITING_ELEMENT_HANDLE,
MAX_DESCRIBE_HANDLES,
type EditingElementDescription,
type EditingElementHit,
type EditingElementSource,
} from "@hyperframes/core/runtime/editing-port";
import { resolveElementSourceFile } from "../../components/editor/domEditingDom";
import { previewRequest } from "./previewChannel";
declare const checked: unique symbol;
/** A description that passed `readPreviewElement`. Only that function makes one. */
export type PreviewElement = EditingElementDescription & { readonly [checked]: true };
export type PreviewElementHit = EditingElementHit & { readonly [checked]: true };
type Fields = Record<string, unknown>;
const isFields = (value: unknown): value is Fields =>
typeof value === "object" && value !== null && !Array.isArray(value);
const isHandle = (value: unknown) =>
typeof value === "string" && EDITING_ELEMENT_HANDLE.test(value);
const isText = (value: unknown) => typeof value === "string";
const isTextOrNull = (value: unknown) => value === null || typeof value === "string";
const isCount = (value: unknown) => Number.isSafeInteger(value) && (value as number) >= 0;
const isSource = (value: unknown): value is EditingElementSource =>
isFields(value) &&
isTextOrNull(value.file) &&
isTextOrNull(value.compositionId) &&
isTextOrNull(value.originalCompositionId);
const isTextRecord = (value: unknown) => isFields(value) && Object.values(value).every(isText);
function hasPlainFields(value: Fields): boolean {
const { matchesBefore, attributes, children } = value;
const groupsOk =
matchesBefore === null ||
(Array.isArray(matchesBefore) &&
matchesBefore.every((g) => isFields(g) && isSource(g.source) && isCount(g.count)));
const attributesOk =
Array.isArray(attributes) &&
attributes.every((a) => Array.isArray(a) && a.length === 2 && a.every(isText));
const childrenOk =
Array.isArray(children) &&
children.every((c) => isFields(c) && (isHandle(c.handle) || isText(c.text)));
return groupsOk && attributesOk && childrenOk && typeof value.truncated === "boolean";
}
function readHit(value: unknown): PreviewElementHit | null {
if (!isFields(value) || !isHandle(value.handle) || !isText(value.tag)) return null;
const { rect } = value;
const rectOk = isFields(rect) && [rect.x, rect.y, rect.width, rect.height].every(Number.isFinite);
return rectOk ? (value as unknown as PreviewElementHit) : null;
}
/** Frame data checked against `EditingElementDescription`; null when any field is off. */
export function readPreviewElement(value: unknown): PreviewElement | null {
if (!readHit(value) || !isFields(value)) return null;
if (value.parent !== null && !isHandle(value.parent)) return null;
if (!isTextOrNull(value.id) || !isTextOrNull(value.selector)) return null;
if (!isSource(value.source) || typeof value.locked !== "boolean") return null;
if (!isTextRecord(value.inlineStyles) || !isText(value.text)) return null;
return hasPlainFields(value) ? (value as unknown as PreviewElement) : null;
}
/** The elements under a frame viewport point, topmost first; null when the runtime cannot answer. */
export async function previewElementsAtPoint(
iframe: HTMLIFrameElement,
x: number,
y: number,
): Promise<PreviewElementHit[] | null> {
const reply = await previewRequest(iframe, "elements-at-point", { x, y });
const elements: unknown = reply?.elements;
if (!Array.isArray(elements)) return null;
return elements.map(readHit).filter((element) => element !== null);
}
/**
* One entry per handle, in order: null for an element the frame no longer has. The whole answer is
* null when the runtime cannot answer, or when there are no handles or more than the runtime takes.
*/
export async function describePreviewElements(
iframe: HTMLIFrameElement,
handles: readonly string[],
): Promise<Array<PreviewElement | null> | null> {
if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
const reply = await previewRequest(iframe, "describe", { handles: [...handles] });
const elements: unknown = reply?.elements;
if (!Array.isArray(elements) || elements.length !== handles.length) return null;
return elements.map((entry, index) => {
const element = readPreviewElement(entry);
return element?.handle === handles[index] ? element : null;
});
}
/** `getSourceFileForElement` for the frame's own element. */
export function previewElementSourceFile(
element: PreviewElement,
activeCompositionPath: string | null,
): string {
return resolveElementSourceFile(element.source, activeCompositionPath);
}
/** `getSelectorIndex` for the frame's own element; undefined when the runtime could not count. */
export function previewElementSelectorIndex(
element: PreviewElement,
activeCompositionPath: string | null,
): number | undefined {
if (!element.selector?.startsWith(".") || !element.matchesBefore) return undefined;
const file = previewElementSourceFile(element, activeCompositionPath);
return element.matchesBefore
.filter((group) => resolveElementSourceFile(group.source, activeCompositionPath) === file)
.reduce((sum, group) => sum + group.count, 0);
}