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