From 51ae92510502dae5255f997058e9a5dfa399ad77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 16 Nov 2026 16:10:26 +0000 Subject: [PATCH] feat(core): describe replies carry the picker's element label, and studio exports standInHandle (#7936) * feat(core): describe replies carry the picker's element label, and studio exports standInHandle * fix(core): label an element by its rendered text, and read a describe reply without a label * style(core): format the rendered-text walk --- packages/core/src/runtime/editingElement.ts | 1 + .../core/src/runtime/editingHandles.test.ts | 7 +++ packages/core/src/runtime/editingHandles.ts | 23 ++------- packages/core/src/runtime/elementLabel.ts | 47 +++++++++++++++++++ packages/core/src/runtime/picker.ts | 20 +------- packages/studio/src/index.ts | 1 + .../src/player/lib/previewElements.test.ts | 4 ++ .../studio/src/player/lib/previewElements.ts | 1 + .../studio/src/sealedPreviewExports.test.ts | 1 + 9 files changed, 66 insertions(+), 39 deletions(-) create mode 100644 packages/core/src/runtime/elementLabel.ts diff --git a/packages/core/src/runtime/editingElement.ts b/packages/core/src/runtime/editingElement.ts index d04257cff3..bd6520d318 100644 --- a/packages/core/src/runtime/editingElement.ts +++ b/packages/core/src/runtime/editingElement.ts @@ -32,6 +32,7 @@ export interface EditingElementHit { * `truncated` says something was cut, so the description is not safe to write back to source. */ export interface EditingElementDescription extends EditingElementHit { + label?: string; parent: EditingElementHandle | null; id: string | null; selector: string | null; diff --git a/packages/core/src/runtime/editingHandles.test.ts b/packages/core/src/runtime/editingHandles.test.ts index 905b53c6f0..69212972bf 100644 --- a/packages/core/src/runtime/editingHandles.test.ts +++ b/packages/core/src/runtime/editingHandles.test.ts @@ -77,6 +77,7 @@ describe("element handles over the editing port", () => { handle: top!.handle, parent: below!.handle, tag: "p", + label: "Hi there", id: null, selector: ".title", matchesBefore: [], @@ -98,6 +99,12 @@ describe("element handles over the editing port", () => { expect(JSON.parse(JSON.stringify(described))).toEqual(described); }); + it("names an element by its rendered text, never its script or style source", async () => { + document.body.innerHTML = `
Card title
`; + const described = await describeOne(document.querySelector("div")!); + expect(described).toMatchObject({ label: "Card title", text: "Card title" }); + }); + it("keeps an element's handle for the page load, answering null only while it is detached", async () => { document.body.innerHTML = `

A

B

`; const [a, b] = Array.from(document.querySelectorAll("p")); diff --git a/packages/core/src/runtime/editingHandles.ts b/packages/core/src/runtime/editingHandles.ts index 5c99d2cc78..8a0ec976a3 100644 --- a/packages/core/src/runtime/editingHandles.ts +++ b/packages/core/src/runtime/editingHandles.ts @@ -19,6 +19,7 @@ import { type EditingElementMatch, type EditingElementSource, } from "./editingElement"; +import { buildElementLabel, NO_TEXT, renderedTextOf } from "./elementLabel"; // Drawn on first use, not at load: a render seeds getRandomValues, and a draw here would shift the // composition's own random values. @@ -83,8 +84,6 @@ function matchesBefore(element: Element, selector: string | undefined) { return null; } -const NO_TEXT = new Set(["script", "style"]); - type Cut = { truncated: boolean }; /** A value over `limit` is cut: a `dataUrl` one starting `data:` to its header, any other by length. */ @@ -96,24 +95,7 @@ function cut(value: string, limit: number, state: Cut, dataUrl = false): string } 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); + return cut(renderedTextOf(element, MAX_ELEMENT_TEXT), MAX_ELEMENT_TEXT, state); } function inlineStyles(element: Element, state: Cut): Record { @@ -165,6 +147,7 @@ function describeElement(element: Element): EditingElementDescription { const state: Cut = { truncated: false }; return { ...elementHit(element), + label: buildElementLabel(element), parent: element.parentElement ? handleFor(element.parentElement) : null, id: element.id || null, selector: selector ?? null, diff --git a/packages/core/src/runtime/elementLabel.ts b/packages/core/src/runtime/elementLabel.ts new file mode 100644 index 0000000000..a7ddf75c87 --- /dev/null +++ b/packages/core/src/runtime/elementLabel.ts @@ -0,0 +1,47 @@ +/** Elements whose text is code, not content: left out of every text an editor reads. */ +export const NO_TEXT = new Set(["script", "style"]); + +/** The element's rendered text, script and style left out, read until it passes `limit` chars. */ +export function renderedTextOf(element: Element, limit: number): 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 > limit) break; + } + return text; +} + +// Enough source text for a 56-character label once whitespace runs collapse. +const LABEL_SOURCE_CHARS = 1000; + +/** The short name an editor shows for an element: its text for text tags, otherwise its role. */ +export function buildElementLabel(el: Element): string { + const tag = el.tagName.toLowerCase(); + const text = renderedTextOf(el, LABEL_SOURCE_CHARS).trim().replace(/\s+/g, " "); + const trimLabel = (value: string, maxChars: number) => { + const chars = Array.from(value); + return chars.length > maxChars ? `${chars.slice(0, maxChars - 1).join("")}…` : value; + }; + const heading = /^h[1-6]$/.test(tag); + if (heading || tag === "p" || tag === "span" || tag === "div") + return text.length > 0 ? trimLabel(text, 56) : heading ? "Heading" : "Text"; + if (tag === "img") return "Image"; + if (tag === "video") return "Video"; + if (tag === "audio") return "Audio"; + if (tag === "svg") return "Shape"; + if (el.getAttribute("data-composition-src")) return "Composition"; + if (tag === "section") return "Section"; + return `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`; +} diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts index b05564d578..7e3812a0c0 100644 --- a/packages/core/src/runtime/picker.ts +++ b/packages/core/src/runtime/picker.ts @@ -5,6 +5,7 @@ import { swallow } from "./diagnostics"; import { isElementNode } from "./domRealm"; import { unproxiedSrc } from "./proxySrc"; import { createDrawnProbe } from "./pickerDrawn"; +import { buildElementLabel } from "./elementLabel"; type PickerModuleDeps = { postMessage: (payload: RuntimeOutboundMessage) => void; @@ -248,25 +249,6 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule { return tag; } - function buildElementLabel(el: Element): string { - const tag = el.tagName.toLowerCase(); - const text = (el.textContent ?? "").trim().replace(/\s+/g, " "); - const trimLabel = (value: string, maxChars: number) => { - const chars = Array.from(value); - return chars.length > maxChars ? `${chars.slice(0, maxChars - 1).join("")}…` : value; - }; - const heading = /^h[1-6]$/.test(tag); - if (heading || tag === "p" || tag === "span" || tag === "div") - return text.length > 0 ? trimLabel(text, 56) : heading ? "Heading" : "Text"; - if (tag === "img") return "Image"; - if (tag === "video") return "Video"; - if (tag === "audio") return "Audio"; - if (tag === "svg") return "Shape"; - if (el.getAttribute("data-composition-src")) return "Composition"; - if (tag === "section") return "Section"; - return `${tag.charAt(0).toUpperCase()}${tag.slice(1)}`; - } - function getPickCandidatesFromPoint(clientX: number, clientY: number, limit?: number): Element[] { const maxCandidates = typeof limit === "number" && limit > 0 ? limit : 8; let raw: Element[] = []; diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts index 715cc01b87..2662f64dc5 100644 --- a/packages/studio/src/index.ts +++ b/packages/studio/src/index.ts @@ -62,6 +62,7 @@ export { findPreviewElementForTimelineElement, readable, standInFor, + standInHandle, } from "./components/editor/previewSelection"; export { PREVIEW_QUALITY_LEVELS, type PreviewQuality } from "@hyperframes/core/preview-quality"; export type { diff --git a/packages/studio/src/player/lib/previewElements.test.ts b/packages/studio/src/player/lib/previewElements.test.ts index 8e4456c0d9..634223e13f 100644 --- a/packages/studio/src/player/lib/previewElements.test.ts +++ b/packages/studio/src/player/lib/previewElements.test.ts @@ -50,6 +50,7 @@ function described(n: number, extra: Partial = {}) { handle: h(n), parent: null, tag: "div", + label: "Text", id: null, selector: null, matchesBefore: null, @@ -68,6 +69,8 @@ function described(n: number, extra: Partial = {}) { describe("readPreviewElement", () => { it("takes a description with the wire shape and refuses anything off it", () => { expect(readPreviewElement(described(1))).toEqual(described(1)); + const { label: _label, ...fromAnOlderRuntime } = described(1); + expect(readPreviewElement(fromAnOlderRuntime)).toEqual(fromAnOlderRuntime); for (const bad of [ null, [], @@ -77,6 +80,7 @@ describe("readPreviewElement", () => { described(1, { handle: `${LOAD.toUpperCase()}:1` }), described(1, { parent: "x" }), described(1, { tag: 1 as never }), + described(1, { label: 1 as never }), described(1, { source: { file: 1 } as never }), described(1, { locked: "yes" as never }), described(1, { attributes: [["a"]] as never }), diff --git a/packages/studio/src/player/lib/previewElements.ts b/packages/studio/src/player/lib/previewElements.ts index c40ce7b32c..db624e410c 100644 --- a/packages/studio/src/player/lib/previewElements.ts +++ b/packages/studio/src/player/lib/previewElements.ts @@ -70,6 +70,7 @@ function readHit(value: unknown): PreviewElementHit | null { export function readPreviewElement(value: unknown): PreviewElement | null { if (!readHit(value) || !isFields(value)) return null; if (value.parent !== null && !isHandle(value.parent)) return null; + if (value.label !== undefined && !isText(value.label)) 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; diff --git a/packages/studio/src/sealedPreviewExports.test.ts b/packages/studio/src/sealedPreviewExports.test.ts index 8ad761f0e6..8ac52ba07a 100644 --- a/packages/studio/src/sealedPreviewExports.test.ts +++ b/packages/studio/src/sealedPreviewExports.test.ts @@ -17,4 +17,5 @@ it("exports a sealed preview's checked element reads and stand-ins as the ones S ); expect(studio.readable).toBe(selection.readable); expect(studio.standInFor).toBe(selection.standInFor); + expect(studio.standInHandle).toBe(selection.standInHandle); });