mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
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:
co-authored by
Claude Opus 5.5
parent
cc47f7ea74
commit
e1ddb2e162
@@ -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 {
|
||||
|
||||
@@ -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,
|
||||
},
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
Reference in New Issue
Block a user