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); +}