diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts
index 4d4dcb8058..a637aee3d9 100644
--- a/packages/core/src/runtime/editingAgent.test.ts
+++ b/packages/core/src/runtime/editingAgent.test.ts
@@ -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 = `
Hi
`;
+ 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();
diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts
index 24ae8630ff..a362a428a1 100644
--- a/packages/core/src/runtime/editingAgent.ts
+++ b/packages/core/src/runtime/editingAgent.ts
@@ -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 {
diff --git a/packages/core/src/runtime/editingElement.ts b/packages/core/src/runtime/editingElement.ts
new file mode 100644
index 0000000000..a3360ca565
--- /dev/null
+++ b/packages/core/src/runtime/editingElement.ts
@@ -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;
+}
+
+/** `:`, 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;
+ /** Rendered-tree text: `Shown`;
+ 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 = `data: 42 users, up 3%
`;
+ const dataText = await describeOne(document.querySelector("p")!);
+ expect(dataText).toMatchObject({ text: "data: 42 users, up 3%", truncated: false });
+
+ document.body.innerHTML = `${"y".repeat(MAX_ELEMENT_TEXT + 10)}
`;
+ 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 = `
+
+
+
+ `;
+ 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,
+ },
+ ]);
+ });
+});
diff --git a/packages/core/src/runtime/editingHandles.ts b/packages/core/src/runtime/editingHandles.ts
new file mode 100644
index 0000000000..9f8ea2c573
--- /dev/null
+++ b/packages/core/src/runtime/editingHandles.ts
@@ -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();
+const elements = new Map>();
+const collected = new FinalizationRegistry((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;
+ 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 {
+ const styles: Record = {};
+ const declared = (element as Partial).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 {
+ return requested.map((handle) => {
+ const element = elementForHandle(handle);
+ return element ? describeElement(element) : null;
+ });
+}
diff --git a/packages/core/src/runtime/editingPort.test.ts b/packages/core/src/runtime/editingPort.test.ts
index bd9bb8fcb7..630091b7bd 100644
--- a/packages/core/src/runtime/editingPort.test.ts
+++ b/packages/core/src/runtime/editingPort.test.ts
@@ -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();
diff --git a/packages/core/src/runtime/editingPort.ts b/packages/core/src/runtime/editingPort.ts
index f9e57e3126..ff36414aed 100644
--- a/packages/core/src/runtime/editingPort.ts
+++ b/packages/core/src/runtime/editingPort.ts
@@ -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 | 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 };
+ };
}
export type EditingParams = EditingRequests[K]["params"];
export type EditingResult = EditingRequests[K]["result"];
@@ -86,7 +124,11 @@ export function isPlainRecord(value: unknown): value is Record
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 =>
+ 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. */
diff --git a/packages/studio/src/components/editor/domEditingDom.ts b/packages/studio/src/components/editor/domEditingDom.ts
index d56cef4cb1..860a74dad0 100644
--- a/packages/studio/src/components/editor/domEditingDom.ts
+++ b/packages/studio/src/components/editor/domEditingDom.ts
@@ -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 =
diff --git a/packages/studio/src/player/lib/previewChannel.ts b/packages/studio/src/player/lib/previewChannel.ts
index afc54d2af7..41e3727e41 100644
--- a/packages/studio/src/player/lib/previewChannel.ts
+++ b/packages/studio/src/player/lib/previewChannel.ts
@@ -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 {
let timer: ReturnType | undefined;
const probe = new Promise(
(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(
+ iframe: HTMLIFrameElement,
+ kind: K,
+ params: EditingParams,
+ timeoutMs?: number,
+): Promise | 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 {
- 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;
@@ -86,9 +103,7 @@ export async function previewComputedStyles(
selector: string,
properties: string[],
): Promise | 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 = {};
diff --git a/packages/studio/src/player/lib/previewElements.test.ts b/packages/studio/src/player/lib/previewElements.test.ts
new file mode 100644
index 0000000000..8e4456c0d9
--- /dev/null
+++ b/packages/studio/src/player/lib/previewElements.test.ts
@@ -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 = { 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 = {}) {
+ 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 = `
+
+
+ `;
+ const target = document.querySelectorAll(".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();
+ });
+});
diff --git a/packages/studio/src/player/lib/previewElements.ts b/packages/studio/src/player/lib/previewElements.ts
new file mode 100644
index 0000000000..7b345ae8eb
--- /dev/null
+++ b/packages/studio/src/player/lib/previewElements.ts
@@ -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;
+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 {
+ 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 | 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);
+}