diff --git a/packages/core/src/runtime/editingAgent.test.ts b/packages/core/src/runtime/editingAgent.test.ts index a637aee3d9..ceb1291171 100644 --- a/packages/core/src/runtime/editingAgent.test.ts +++ b/packages/core/src/runtime/editingAgent.test.ts @@ -143,6 +143,8 @@ describe("installEditingAgent", () => { "computed-styles", "elements-at-point", "describe", + "ancestors", + "query", ], }, }); @@ -260,6 +262,38 @@ describe("installEditingAgent", () => { 40 + index, "invalid-params", ]), + ...[ + { handle: "0123456789abcdef:1" }, + { handle: "1", properties: ["color"] }, + { handle: 1, properties: ["color"] }, + { handle: "0123456789abcdef:1", selector: "p", properties: ["color"] }, + { handle: "0123456789abcdef:1", properties: ["color;"] }, + ].map((params, index) => [ + { v: 1, id: 70 + index, kind: "computed-styles", params }, + 70 + index, + "invalid-params", + ]), + ...[ + {}, + { handles: [] }, + { handles: ["1"] }, + { handles: Array(257).fill("0123456789abcdef:1") }, + ].map((params, index) => [ + { v: 1, id: 80 + index, kind: "ancestors", params }, + 80 + index, + "invalid-params", + ]), + ...[ + {}, + { selector: "" }, + { selector: 1 }, + { selector: "p".repeat(2001) }, + { selector: "p", x: 1 }, + ].map((params, index) => [ + { v: 1, id: 90 + index, kind: "query", params }, + 90 + 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 } }, diff --git a/packages/core/src/runtime/editingAgent.ts b/packages/core/src/runtime/editingAgent.ts index a362a428a1..e72673c3b2 100644 --- a/packages/core/src/runtime/editingAgent.ts +++ b/packages/core/src/runtime/editingAgent.ts @@ -20,7 +20,13 @@ import { type EditingResult, } from "./editingPort"; import type { ClipNode } from "./clipTree"; -import { describeHandles, elementsAtPoint } from "./editingHandles"; +import { + ancestorHandles, + describeHandles, + elementForHandle, + elementsAtPoint, + queryElements, +} from "./editingHandles"; import { getLogicalOpacity } from "../studioPreviewMark"; type Handlers = { @@ -57,8 +63,12 @@ const HANDLERS: Handlers = { setLoopStart(seconds); return { applied: true }; }, - "computed-styles": ({ selector, properties }) => { - const element = document.querySelector(selector); + "computed-styles": (params) => { + const { properties } = params; + const element = + "handle" in params + ? elementForHandle(params.handle) + : document.querySelector(params.selector); if (!element) return { styles: null }; const computed = window.getComputedStyle(element); const styles: Record = {}; @@ -71,6 +81,8 @@ const HANDLERS: Handlers = { }, "elements-at-point": ({ x, y }) => ({ elements: elementsAtPoint(x, y) }), describe: ({ handles }) => ({ elements: describeHandles(handles) }), + ancestors: ({ handles }) => ({ ancestors: ancestorHandles(handles) }), + query: ({ selector }) => queryElements(selector), }; function serve(port: MessagePort): void { diff --git a/packages/core/src/runtime/editingElement.ts b/packages/core/src/runtime/editingElement.ts index a3360ca565..3fffbf8094 100644 --- a/packages/core/src/runtime/editingElement.ts +++ b/packages/core/src/runtime/editingElement.ts @@ -52,12 +52,18 @@ export interface EditingElementDescription extends EditingElementHit { truncated: boolean; } +export interface EditingElementMatch { + handle: EditingElementHandle; + source: EditingElementSource; +} + 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; +export const MAX_QUERY_MATCHES = 2_048; // fallow-ignore-next-line complexity function escapeCssIdentifier(value: string): string { diff --git a/packages/core/src/runtime/editingHandles.test.ts b/packages/core/src/runtime/editingHandles.test.ts index f72752ba09..467a07f1e8 100644 --- a/packages/core/src/runtime/editingHandles.test.ts +++ b/packages/core/src/runtime/editingHandles.test.ts @@ -3,8 +3,10 @@ import { installEditingAgent } from "./editingAgent"; import { trackedHandleCount } from "./editingHandles"; import { EDITING_ELEMENT_HANDLE, + MAX_DESCRIBE_HANDLES, MAX_ELEMENT_TEXT, MAX_ELEMENT_VALUE, + MAX_QUERY_MATCHES, type EditingElementDescription, type EditingElementHit, } from "./editingPort"; @@ -201,4 +203,63 @@ describe("element handles over the editing port", () => { }, ]); }); + + it("names a handle's ancestors parent first, up to the document element, and null once removed", async () => { + document.body.innerHTML = `

A

`; + const p = document.querySelector("p")!; + const { handle } = await describeOne(p); + const reply = await ask("ancestors", { handles: [handle, handle] }); + const [chain, again] = (reply.result as unknown as { ancestors: string[][] }).ancestors; + expect(again).toEqual(chain); + const tags = (await describeHandles(chain!)).map((entry) => entry?.tag); + expect(tags).toEqual(["div", "section", "body", "html"]); + + p.remove(); + const gone = await ask("ancestors", { handles: [handle] }); + expect(gone.result).toEqual({ ancestors: [null] }); + }); + + it("stops an ancestor chain at what one describe takes", async () => { + document.body.innerHTML = "
".repeat(MAX_DESCRIBE_HANDLES + 5) + "

deep

"; + const { handle } = await describeOne(document.querySelector("p")!); + const reply = await ask("ancestors", { handles: [handle] }); + const [chain] = (reply.result as unknown as { ancestors: string[][] }).ancestors; + expect(chain).toHaveLength(MAX_DESCRIBE_HANDLES); + const [top] = await describeHandles([chain!.at(-1)!]); + expect(top!.parent).not.toBeNull(); + }); + + it("answers a query with each match's handle and source, in document order", async () => { + document.body.innerHTML = `

+

`; + const reply = await ask("query", { selector: ".t" }); + const { matches, truncated } = reply.result as unknown as { + matches: Array<{ handle: string; source: { file: string | null } }>; + truncated: boolean; + }; + expect(truncated).toBe(false); + expect(matches.map((match) => match.source.file)).toEqual([null, "cards.html"]); + const described = await describeHandles(matches.map((match) => match.handle)); + expect(described.map((entry) => entry?.id)).toEqual(["a", "b"]); + expect((await ask("query", { selector: "p[" })).error).toMatchObject({ code: "failed" }); + }); + + it("caps a query's matches and says so", async () => { + document.body.innerHTML = "".repeat(MAX_QUERY_MATCHES + 1); + const { result } = await ask("query", { selector: "i" }); + const { matches, truncated } = result as unknown as { matches: unknown[]; truncated: boolean }; + expect(matches).toHaveLength(MAX_QUERY_MATCHES); + expect(truncated).toBe(true); + }); + + it("reads computed styles for the element a handle names, and null once it is removed", async () => { + document.body.innerHTML = `

`; + const second = document.querySelectorAll("p")[1]!; + const { handle } = await describeOne(second); + const styles = (properties: string[]) => + ask("computed-styles", { handle, properties }).then((reply) => reply.result); + expect(await styles(["color"])).toEqual({ styles: { color: "rgb(4, 5, 6)" } }); + second.remove(); + expect(await styles(["color"])).toEqual({ styles: null }); + }); }); diff --git a/packages/core/src/runtime/editingHandles.ts b/packages/core/src/runtime/editingHandles.ts index 9f8ea2c573..ff0295655b 100644 --- a/packages/core/src/runtime/editingHandles.ts +++ b/packages/core/src/runtime/editingHandles.ts @@ -5,15 +5,18 @@ */ import { buildStableSelector, + MAX_DESCRIBE_HANDLES, MAX_ELEMENT_ENTRIES, MAX_ELEMENT_TEXT, MAX_ELEMENT_VALUE, MAX_POINT_STACK, + MAX_QUERY_MATCHES, MAX_SOURCE_GROUPS, readElementSource, type EditingElementDescription, type EditingElementHandle, type EditingElementHit, + type EditingElementMatch, type EditingElementSource, } from "./editingElement"; @@ -43,7 +46,7 @@ function handleFor(element: Element): EditingElementHandle { } /** The live element in this document behind `handle`, else null. */ -function elementForHandle(handle: EditingElementHandle): Element | null { +export function elementForHandle(handle: EditingElementHandle): Element | null { const [handleLoad, count] = handle.split(":"); if (handleLoad !== loadId()) return null; const n = Number(count); @@ -188,3 +191,30 @@ export function describeHandles( return element ? describeElement(element) : null; }); } + +export function ancestorHandles( + requested: readonly EditingElementHandle[], +): Array { + return requested.map((handle) => { + const element = elementForHandle(handle); + if (!element) return null; + const chain: EditingElementHandle[] = []; + let node = element.parentElement; + for (; node && chain.length < MAX_DESCRIBE_HANDLES; node = node.parentElement) { + chain.push(handleFor(node)); + } + return chain; + }); +} + +export function queryElements(selector: string): { + matches: EditingElementMatch[]; + truncated: boolean; +} { + const matches: EditingElementMatch[] = []; + for (const element of document.querySelectorAll(selector)) { + if (matches.length === MAX_QUERY_MATCHES) return { matches, truncated: true }; + matches.push({ handle: handleFor(element), source: readElementSource(element) }); + } + return { matches, truncated: false }; +} diff --git a/packages/core/src/runtime/editingPort.test.ts b/packages/core/src/runtime/editingPort.test.ts index 630091b7bd..d618870fde 100644 --- a/packages/core/src/runtime/editingPort.test.ts +++ b/packages/core/src/runtime/editingPort.test.ts @@ -68,6 +68,8 @@ describe("createEditingPortClient", () => { "computed-styles", "elements-at-point", "describe", + "ancestors", + "query", ], }); } finally { diff --git a/packages/core/src/runtime/editingPort.ts b/packages/core/src/runtime/editingPort.ts index ff36414aed..9f764e6186 100644 --- a/packages/core/src/runtime/editingPort.ts +++ b/packages/core/src/runtime/editingPort.ts @@ -15,6 +15,7 @@ import { type EditingElementDescription, type EditingElementHandle, type EditingElementHit, + type EditingElementMatch, } from "./editingElement"; import type { RuntimeTimelineMessage } from "./types"; import { wallClearTimeout, wallSetTimeout } from "./wallClock"; @@ -30,10 +31,12 @@ export { MAX_ELEMENT_TEXT, MAX_ELEMENT_VALUE, MAX_POINT_STACK, + MAX_QUERY_MATCHES, MAX_SOURCE_GROUPS, type EditingElementDescription, type EditingElementHandle, type EditingElementHit, + type EditingElementMatch, type EditingElementSource, type EditingRect, } from "./editingElement"; @@ -52,6 +55,8 @@ export const EDITING_REQUEST_KINDS = [ "computed-styles", "elements-at-point", "describe", + "ancestors", + "query", ] as const; export type EditingRequestKind = (typeof EDITING_REQUEST_KINDS)[number]; @@ -77,9 +82,9 @@ export interface EditingRequests { "wait-for-seek": { params: NoParams; result: { waited: boolean } }; /** Where a looping playback wraps to; null stops looping from a custom start. */ "set-loop-start": { params: { seconds: number | null }; result: { applied: boolean } }; - /** `styles` is null when no element matches `selector`; empty values are left out. */ + /** The element `selector` first matches, or `handle` names. `styles` is null for none; empty values are left out. */ "computed-styles": { - params: { selector: string; properties: string[] }; + params: ({ selector: string } | { handle: EditingElementHandle }) & { properties: string[] }; result: { styles: Record | null }; }; /** The stack under a viewport point, topmost first, up to MAX_POINT_STACK. Describe one to keep. */ @@ -92,6 +97,16 @@ export interface EditingRequests { params: { handles: EditingElementHandle[] }; result: { elements: Array }; }; + /** Each handle's ancestors, parent first, up to MAX_DESCRIBE_HANDLES; null as in `describe`. */ + ancestors: { + params: { handles: EditingElementHandle[] }; + result: { ancestors: Array }; + }; + /** The matches of `selector` in document order, up to MAX_QUERY_MATCHES; an invalid one fails. */ + query: { + params: { selector: string }; + result: { matches: EditingElementMatch[]; truncated: boolean }; + }; } export type EditingParams = EditingRequests[K]["params"]; export type EditingResult = EditingRequests[K]["result"]; @@ -133,6 +148,36 @@ const hasKeys = (params: unknown, keys: string): params is Record params === undefined || (isPlainRecord(params) && Object.keys(params).length === 0) ? {} : null; +const isSelector = (value: unknown): value is string => + typeof value === "string" && value.length > 0 && value.length <= MAX_SELECTOR_LENGTH; +const isHandle = (value: unknown): value is EditingElementHandle => + typeof value === "string" && EDITING_ELEMENT_HANDLE.test(value); + +function styleTarget(params: Record) { + const keys = Object.keys(params).sort().join(); + const { selector, handle } = params; + if (keys === "properties,selector" && isSelector(selector)) return { selector }; + return keys === "handle,properties" && isHandle(handle) ? { handle } : null; +} + +function styleProperties(properties: unknown): string[] | null { + if (!Array.isArray(properties) || properties.length > MAX_STYLE_PROPERTIES) return null; + const names = properties.filter( + (name): name is string => + typeof name === "string" && + name.length <= MAX_STYLE_PROPERTY_LENGTH && + STYLE_PROPERTY.test(name), + ); + return names.length === properties.length ? names : null; +} + +function handleList(params: unknown): { handles: EditingElementHandle[] } | null { + 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(isHandle) ? { handles } : null; +} + const PARAM_PARSERS: { [K in EditingRequestKind]: (params: unknown) => EditingParams | null; } = { @@ -148,37 +193,22 @@ const PARAM_PARSERS: { : null; }, "computed-styles": (params) => { - if (!isPlainRecord(params) || Object.keys(params).sort().join() !== "properties,selector") { - return null; - } - const { selector, properties } = params; - if (typeof selector !== "string" || !selector || selector.length > MAX_SELECTOR_LENGTH) { - return null; - } - if (!Array.isArray(properties) || properties.length > MAX_STYLE_PROPERTIES) return null; - const names = properties.filter( - (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; + if (!isPlainRecord(params)) return null; + const target = styleTarget(params); + const properties = styleProperties(params.properties); + return target && properties ? { ...target, properties } : 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; - }, + describe: handleList, + ancestors: handleList, + query: (params) => + hasKeys(params, "selector") && isSelector(params.selector) + ? { selector: params.selector } + : null, }; /** Validates one request off the wire. Never throws: anything unusable becomes a typed error. */ diff --git a/packages/studio/src/components/editor/domEditSelectionRules.ts b/packages/studio/src/components/editor/domEditSelectionRules.ts new file mode 100644 index 0000000000..fe18192228 --- /dev/null +++ b/packages/studio/src/components/editor/domEditSelectionRules.ts @@ -0,0 +1,138 @@ +/** Selection rules over an ancestor chain: one answer for live elements and for descriptions. */ +import type { TimelineElementDomTarget, TimelineElementDomTargetOptions } from "./domEditingTypes"; +import { escapeCssString, normalizeTimelineCompositionSource } from "./domEditingDom"; + +/** Reads one element of a chain: the target first, then each parent up to the document element. */ +export interface SelectionChainReader { + attr(node: N, name: string): string | null; + selector(node: N): string | undefined; + /** The document's `body` or root element, where the walk to an addressable element stops. */ + isDocumentRoot(node: N): boolean; +} + +const OUT_OF_SCOPE = -1; +const hasClass = (value: string | null, name: string) => + (value ?? "").split(/[\t\n\f\r ]+/).includes(name); + +/** + * A `data-hf-group` wrapper is one unit until the user drills into it; inside the drilled-into + * group, clicks reach its children, or the next group nested in it. Returns the unit's index, null + * to resolve the target itself, or OUT_OF_SCOPE when the target is outside the drilled-into group. + */ +function groupUnitIndex( + chain: readonly N[], + read: SelectionChainReader, + activeGroupIndex: number | null, +): number | null { + const groups = chain.flatMap((node, index) => + read.attr(node, "data-hf-group") === null ? [] : [index], + ); + if (activeGroupIndex === null) return groups.at(-1) ?? null; + const at = groups.indexOf(activeGroupIndex); + if (at === -1) return OUT_OF_SCOPE; + return at > 0 ? groups[at - 1]! : null; +} + +/** The nearest `.clip`; a composition host counts only as the target itself. */ +function clipAncestorIndex(chain: readonly N[], read: SelectionChainReader): number | null { + for (let index = 0; index < chain.length; index += 1) { + const node = chain[index]!; + if (!hasClass(read.attr(node, "class"), "clip")) continue; + const isHost = + read.attr(node, "data-composition-src") !== null || + read.attr(node, "data-composition-file") !== null; + if (!isHost || index === 0) return index; + } + return null; +} + +/** Where a selection of `chain[0]` lands; `activeGroupIndex` is -1 for a drilled group not in `chain`. */ +export function selectionTargetIndex( + chain: readonly N[], + read: SelectionChainReader, + options: { exactTarget?: boolean; preferClipAncestor?: boolean; activeGroupIndex: number | null }, +): number | null { + let start = options.exactTarget ? 0 : groupUnitIndex(chain, read, options.activeGroupIndex); + if (start === OUT_OF_SCOPE) start = groupUnitIndex(chain, read, null); + start ??= options.preferClipAncestor ? (clipAncestorIndex(chain, read) ?? 0) : 0; + for (let index = start; index < chain.length; index += 1) { + const node = chain[index]!; + if (read.isDocumentRoot(node)) return null; + if (read.selector(node) || read.attr(node, "data-hf-id")?.trim()) return index; + } + return null; +} + +export function chainLocked( + chain: readonly N[], + read: SelectionChainReader, + index: number, +): boolean { + return chain.slice(index).some((node) => read.attr(node, "data-timeline-locked") !== null); +} + +export interface SelectionLookupTarget { + id?: string | null; + hfId?: string; + selector?: string; + selectorIndex?: number; + sourceFile?: string; +} + +/** The selectors tried in order, each with the index of its match among those from `sourceFile`. */ +export function selectionLookups( + selection: SelectionLookupTarget, +): Array<{ selector: string; index: number }> { + const lookups: Array<{ selector: string; index: number }> = []; + if (selection.hfId) { + lookups.push({ selector: `[data-hf-id="${escapeCssString(selection.hfId)}"]`, index: 0 }); + } + // Flattened sub-compositions can repeat authored ids, so an id is matched by attribute, per source. + if (selection.id) lookups.push({ selector: `[id="${escapeCssString(selection.id)}"]`, index: 0 }); + if (selection.selector) { + lookups.push({ selector: selection.selector, index: selection.selectorIndex ?? 0 }); + } + return lookups; +} + +/** + * Where a timeline element is in the preview: `target` to look up, else, when `rootFallback`, the + * first composition root if it comes from `sourceFile`. + */ +export function timelineElementLookup( + element: TimelineElementDomTarget, + options: TimelineElementDomTargetOptions, +): { target: SelectionLookupTarget | null; sourceFile: string; rootFallback: boolean } { + const elementId = typeof element.id === "string" ? element.id : ""; + const compositionSource = + normalizeTimelineCompositionSource(element.compositionSrc) ?? + options.compIdToSrc?.get(elementId); + const sourceFile = + compositionSource ?? + normalizeTimelineCompositionSource(element.sourceFile) ?? + options.activeCompositionPath ?? + "index.html"; + const escapedElementId = escapeCssString(elementId); + const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null; + const selector = + element.selector ?? + (compositionSource + ? `[data-composition-src="${escapedCompositionSource}"],[data-composition-file="${escapedCompositionSource}"],[data-composition-id="${escapedElementId}"]` + : escapedElementId + ? `[data-composition-id="${escapedElementId}"]` + : undefined); + + const target = + selector || element.domId + ? { + id: element.domId ?? undefined, + selector, + selectorIndex: element.selectorIndex, + sourceFile, + } + : null; + const hasExplicitDomTarget = Boolean(element.domId || element.selector || compositionSource); + const rootFallback = + !options.isMasterView && !hasExplicitDomTarget && Boolean(options.activeCompositionPath); + return { target, sourceFile, rootFallback }; +} diff --git a/packages/studio/src/components/editor/domEditingElement.ts b/packages/studio/src/components/editor/domEditingElement.ts index 045d20e85a..004610c723 100644 --- a/packages/studio/src/components/editor/domEditingElement.ts +++ b/packages/studio/src/components/editor/domEditingElement.ts @@ -11,14 +11,13 @@ import type { } from "./domEditingTypes"; import { buildStableSelector, - escapeCssString, getSelectorIndex, getSourceFileForElement, isHtmlElement, isElementVisibleThroughAncestors, - normalizeTimelineCompositionSource, querySelectorAllSafely, } from "./domEditingDom"; +import { selectionLookups, timelineElementLookup } from "./domEditSelectionRules"; // ─── Visibility ────────────────────────────────────────────────────────────── @@ -171,36 +170,6 @@ export function isDomLayerElement(el: HTMLElement): boolean { return isInspectableLayerElement(el) && resolveLayerSelector(el) !== undefined; } -// ─── Clip ancestor / selection candidate ───────────────────────────────────── - -function getPreferredClipAncestor(startEl: HTMLElement): HTMLElement | null { - let current: HTMLElement | null = startEl; - while (current) { - if (current.classList.contains("clip")) { - const isCompositionHost = - current.hasAttribute("data-composition-src") || - current.hasAttribute("data-composition-file"); - if (!isCompositionHost || current === startEl) return current; - } - current = current.parentElement; - } - return null; -} - -export function getSelectionCandidate( - startEl: HTMLElement, - options: DomEditContextOptions, -): HTMLElement { - if (options.preferClipAncestor) { - const clipAncestor = getPreferredClipAncestor(startEl); - if (clipAncestor) { - return clipAncestor; - } - } - - return startEl; -} - // ─── Visual target resolution ───────────────────────────────────────────────── export function resolveVisualDomEditSelectionTarget( @@ -295,23 +264,11 @@ export function findElementForSelection( (!selection.sourceFile || getSourceFileForElement(candidate, activeCompositionPath).sourceFile === selection.sourceFile); - const findAll = (selector: string): HTMLElement[] => - querySelectorAllSafely(doc, selector).filter(sourceMatches); - - if (selection.hfId) { - const byHfId = findAll(`[data-hf-id="${escapeCssString(selection.hfId)}"]`)[0]; - if (byHfId) return byHfId; + for (const { selector, index } of selectionLookups(selection)) { + const found = querySelectorAllSafely(doc, selector).filter(sourceMatches)[index]; + if (found) return found; } - - if (selection.id) { - // Flattened sub-compositions can repeat authored ids. getElementById returns - // only the first document match, so filter every id match by source first. - const byId = findAll(`[id="${escapeCssString(selection.id)}"]`)[0]; - if (byId) return byId; - } - - if (!selection.selector) return null; - return findAll(selection.selector)[selection.selectorIndex ?? 0] ?? null; + return null; } // The selected node while mounted, else its copy in the selection's own file (ids repeat across files), else any copy. @@ -327,49 +284,15 @@ export function findPreviewNode( ); } -// fallow-ignore-next-line complexity export function findElementForTimelineElement( doc: Document, element: TimelineElementDomTarget, options: TimelineElementDomTargetOptions, ): HTMLElement | null { - const elementId = typeof element.id === "string" ? element.id : ""; - const compositionSource = - normalizeTimelineCompositionSource(element.compositionSrc) ?? - options.compIdToSrc?.get(elementId); - const sourceFile = - compositionSource ?? - normalizeTimelineCompositionSource(element.sourceFile) ?? - options.activeCompositionPath ?? - "index.html"; - const escapedElementId = escapeCssString(elementId); - const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null; - const selector = - element.selector ?? - (compositionSource - ? `[data-composition-src="${escapedCompositionSource}"],[data-composition-file="${escapedCompositionSource}"],[data-composition-id="${escapedElementId}"]` - : escapedElementId - ? `[data-composition-id="${escapedElementId}"]` - : undefined); - - if (selector || element.domId) { - const targetElement = findElementForSelection( - doc, - { - id: element.domId ?? undefined, - selector, - selectorIndex: element.selectorIndex, - sourceFile, - }, - options.activeCompositionPath, - ); - if (targetElement) return targetElement; - } - - const hasExplicitDomTarget = Boolean(element.domId || element.selector || compositionSource); - if (options.isMasterView || hasExplicitDomTarget || !options.activeCompositionPath) { - return null; - } + const { target, sourceFile, rootFallback } = timelineElementLookup(element, options); + const found = target && findElementForSelection(doc, target, options.activeCompositionPath); + if (found) return found; + if (!rootFallback) return null; const root = doc.querySelector("[data-composition-id]"); if (!isHtmlElement(root)) return null; diff --git a/packages/studio/src/components/editor/domEditingGroups.ts b/packages/studio/src/components/editor/domEditingGroups.ts index 8b90f84c42..a725754de9 100644 --- a/packages/studio/src/components/editor/domEditingGroups.ts +++ b/packages/studio/src/components/editor/domEditingGroups.ts @@ -1,15 +1,5 @@ import { isHtmlElement } from "./domEditingDom"; -// `data-hf-group` selection semantics: a group wrapper is selected as one unit -// until the user drills into it; once drilled in, clicks resolve to its children -// (or to the next nested group inside it). One level of drill-in at a time keeps -// nested groups navigable. - -export type GroupCapture = - | { kind: "unit"; element: HTMLElement } // select this group wrapper as one unit - | { kind: "child" } // resolve the clicked element normally - | { kind: "out-of-scope" }; // clicked outside the drilled-into group → select nothing - // Layer-tree roots: the drilled-into group's element children, else the doc root. export function groupScopedLayerRoots( root: HTMLElement, @@ -18,24 +8,3 @@ export function groupScopedLayerRoots( const els = activeGroupElement?.isConnected ? Array.from(activeGroupElement.children) : [root]; return els.filter(isHtmlElement); } - -export function resolveGroupCapture( - startEl: HTMLElement, - activeGroupElement: HTMLElement | null, -): GroupCapture { - const groups: HTMLElement[] = []; - for (let n: HTMLElement | null = startEl; n; n = n.parentElement) { - if (n.hasAttribute("data-hf-group")) groups.push(n); - } - const result = ((): GroupCapture => { - if (!activeGroupElement) { - const outermost = groups[groups.length - 1]; - return outermost ? { kind: "unit", element: outermost } : { kind: "child" }; - } - const idx = groups.indexOf(activeGroupElement); - if (idx === -1) return { kind: "out-of-scope" }; - const nestedInside = groups[idx - 1]; - return nestedInside ? { kind: "unit", element: nestedInside } : { kind: "child" }; - })(); - return result; -} diff --git a/packages/studio/src/components/editor/domEditingLayers.ts b/packages/studio/src/components/editor/domEditingLayers.ts index bcb802b467..8aec1da6b8 100644 --- a/packages/studio/src/components/editor/domEditingLayers.ts +++ b/packages/studio/src/components/editor/domEditingLayers.ts @@ -1,5 +1,5 @@ import { isClipHiddenByRuntime, PREVIEW_ONLY_ATTRS } from "@hyperframes/core/studio-preview-mark"; -import { knownSourceAnswer, probeSourceElement, type ProbeTarget } from "./probeSourceElement"; +import { existsInSourceFile } from "./probeSourceElement"; import { isAudibleVideoNode } from "../../player/lib/timelineElementHelpers"; import type { PatchOperation } from "../../utils/sourcePatcher"; import { @@ -7,7 +7,12 @@ import { resolveEditingSections, type EditableElementFacts, } from "@hyperframes/core/editing"; -import { groupScopedLayerRoots, resolveGroupCapture } from "./domEditingGroups"; +import { groupScopedLayerRoots } from "./domEditingGroups"; +import { + chainLocked, + selectionTargetIndex, + type SelectionChainReader, +} from "./domEditSelectionRules"; import type { DomEditCapabilities, DomEditContextOptions, @@ -18,7 +23,6 @@ import type { import { buildElementLabel, buildStableSelector, - findClosestByAttribute, getCuratedComputedStyles, getDataAttributes, getInlineStyles, @@ -27,11 +31,7 @@ import { isEditableTextLeaf, isHtmlElement, } from "./domEditingDom"; -import { - findElementForSelection, - getSelectionCandidate, - isDomLayerElement, -} from "./domEditingElement"; +import { findElementForSelection, isDomLayerElement } from "./domEditingElement"; import { isCompositionRootLayer } from "./domEditingRootLayer"; import { withSelectorIndexPass } from "../../utils/sourceScopedSelectorIndex"; import { type DomEditLayerWalkCache, readDomEditLayerWalkEntry } from "./domEditLayerWalkCache"; @@ -206,7 +206,7 @@ export function buildTextFieldChildLocator( }; } -function capabilityFacts(geometry: { +export function capabilityFacts(geometry: { hasStableTarget: boolean; tag: string; inlineStyles: Record; @@ -296,99 +296,94 @@ export async function resolveDomEditSelection( ): Promise { if (!startEl) return null; const doc = startEl.ownerDocument; - - let capture = options.exactTarget - ? ({ kind: "unit", element: startEl } as const) - : resolveGroupCapture(startEl, options.activeGroupElement ?? null); - if (capture.kind === "out-of-scope") { - // Drill-in is non-sticky: clicking/hovering OUTSIDE the drilled-into group - // exits it and resolves the target normally, rather than selecting nothing - // (which felt like "can't select anything" once you'd drilled in). - capture = resolveGroupCapture(startEl, null); - } - let current: HTMLElement | null = - capture.kind === "unit" ? capture.element : getSelectionCandidate(startEl, options); - while (current && current !== doc.body && current !== doc.documentElement) { - const selector = buildStableSelector(current); - const hfId = readHfId(current); - if (!selector && !hfId) { - current = current.parentElement; - continue; - } - - const { sourceFile, compositionPath } = getSourceFileForElement( - current, - options.activeCompositionPath, - ); - const selectorIndex = selector - ? getSelectorIndex(doc, current, selector, sourceFile, options.activeCompositionPath) - : undefined; - const compositionSrc = - current.getAttribute("data-composition-src") ?? - current.getAttribute("data-composition-file") ?? - undefined; - const inlineStyles = getInlineStyles(current); - const computedStyles = getCuratedComputedStyles(current); - const isCompositionRoot = - (current.hasAttribute("data-composition-id") && !compositionSrc) || - isCompositionRootLayer(current, doc, computedStyles); - const textFields = collectDomEditTextFields(current); - const isInsideLocked = Boolean(findClosestByAttribute(current, ["data-timeline-locked"])); - const probeTarget: ProbeTarget = {}; - if (current.id) probeTarget.id = current.id; - if (hfId) probeTarget.hfId = hfId; - if (selector) probeTarget.selector = selector; - if (selectorIndex != null) probeTarget.selectorIndex = selectorIndex; - let existsInSource = knownSourceAnswer(options.previous, current, sourceFile, probeTarget); - const probe = existsInSource === undefined && !options.skipSourceProbe; - if (probe && options.projectId && (current.id || selector || hfId)) { - existsInSource = await probeSourceElement(options.projectId, sourceFile, probeTarget); - } - const capabilities = resolveEditingAffordances( - capabilityFacts({ - hasStableTarget: Boolean(selector || hfId), - tag: current.tagName.toLowerCase(), - inlineStyles, - computedStyles, - isCompositionHost: Boolean(compositionSrc), - isCompositionRoot, - isInsideLockedComposition: isInsideLocked, - isMasterView: options.isMasterView, - existsInSource: existsInSource ?? true, - }), - ).capabilities; - const rect = current.getBoundingClientRect(); - - return { - element: current, - id: current.id || undefined, - hfId, - selector, - selectorIndex, - sourceFile, - compositionPath, - compositionSrc, - isCompositionHost: Boolean(compositionSrc), - isInsideLockedComposition: isInsideLocked, - label: buildElementLabel(current), - tagName: current.tagName.toLowerCase(), - boundingBox: { - x: rect.left, - y: rect.top, - width: rect.width, - height: rect.height, - }, - textContent: current.textContent?.trim() || null, - dataAttributes: getDataAttributes(current), + const chain: HTMLElement[] = []; + for (let node: HTMLElement | null = startEl; node; node = node.parentElement) chain.push(node); + const read = liveChainReader(doc); + const active = options.activeGroupElement ?? null; + const index = selectionTargetIndex(chain, read, { + exactTarget: options.exactTarget, + preferClipAncestor: options.preferClipAncestor, + activeGroupIndex: active ? chain.indexOf(active) : null, + }); + if (index === null) return null; + const current = chain[index]!; + const selector = buildStableSelector(current); + const hfId = readHfId(current); + const { sourceFile, compositionPath } = getSourceFileForElement( + current, + options.activeCompositionPath, + ); + const selectorIndex = selector + ? getSelectorIndex(doc, current, selector, sourceFile, options.activeCompositionPath) + : undefined; + const compositionSrc = + current.getAttribute("data-composition-src") ?? + current.getAttribute("data-composition-file") ?? + undefined; + const inlineStyles = getInlineStyles(current); + const computedStyles = getCuratedComputedStyles(current); + const isCompositionRoot = + (current.hasAttribute("data-composition-id") && !compositionSrc) || + isCompositionRootLayer(current, doc, computedStyles); + const textFields = collectDomEditTextFields(current); + const isInsideLocked = chainLocked(chain, read, index); + const existsInSource = await existsInSourceFile( + options.previous, + current, + sourceFile, + { id: current.id, hfId, selector, selectorIndex }, + options, + ); + const capabilities = resolveEditingAffordances( + capabilityFacts({ + hasStableTarget: Boolean(selector || hfId), + tag: current.tagName.toLowerCase(), inlineStyles, computedStyles, - textFields, - capabilities, - existsInSource, - }; - } + isCompositionHost: Boolean(compositionSrc), + isCompositionRoot, + isInsideLockedComposition: isInsideLocked, + isMasterView: options.isMasterView, + existsInSource: existsInSource ?? true, + }), + ).capabilities; + const rect = current.getBoundingClientRect(); - return null; + return { + element: current, + id: current.id || undefined, + hfId, + selector, + selectorIndex, + sourceFile, + compositionPath, + compositionSrc, + isCompositionHost: Boolean(compositionSrc), + isInsideLockedComposition: isInsideLocked, + label: buildElementLabel(current), + tagName: current.tagName.toLowerCase(), + boundingBox: { + x: rect.left, + y: rect.top, + width: rect.width, + height: rect.height, + }, + textContent: current.textContent?.trim() || null, + dataAttributes: getDataAttributes(current), + inlineStyles, + computedStyles, + textFields, + capabilities, + existsInSource, + }; +} + +function liveChainReader(doc: Document): SelectionChainReader { + return { + attr: (el, name) => el.getAttribute(name), + selector: buildStableSelector, + isDocumentRoot: (el) => el === doc.body || el === doc.documentElement, + }; } export async function refreshDomEditSelection( diff --git a/packages/studio/src/components/editor/domEditingRootLayer.ts b/packages/studio/src/components/editor/domEditingRootLayer.ts index 2dff58f962..d2522137f7 100644 --- a/packages/studio/src/components/editor/domEditingRootLayer.ts +++ b/packages/studio/src/components/editor/domEditingRootLayer.ts @@ -12,32 +12,36 @@ function approximatelyEqual(a: number, b: number) { return Math.abs(a - b) <= COMPOSITION_ROOT_LAYER_EPSILON_PX; } -function getCompositionRootBounds(doc: Document) { - const root = - doc.querySelector("[data-composition-id]") ?? doc.documentElement ?? null; - const rootWidth = readPositiveDimension(root?.getAttribute("data-width") ?? null); - const rootHeight = readPositiveDimension(root?.getAttribute("data-height") ?? null); - if (!root || !rootWidth || !rootHeight) return null; - return { rect: root.getBoundingClientRect(), width: rootWidth, height: rootHeight }; +interface Box { + left: number; + top: number; + width: number; + height: number; } -function getRenderedLayerSize(element: HTMLElement, computedStyles: Record) { - const rect = element.getBoundingClientRect(); - const width = rect.width || parsePx(computedStyles.width); - const height = rect.height || parsePx(computedStyles.height); - return width && height ? { width, height } : null; +export interface CompositionRootFacts { + rect: Box; + width: string | null; + height: string | null; } -function matchesCompositionRootBounds( - elementRect: DOMRect, - elementSize: { width: number; height: number }, - rootBounds: { rect: DOMRect; width: number; height: number }, -) { - return ( - approximatelyEqual(elementRect.left, rootBounds.rect.left) && - approximatelyEqual(elementRect.top, rootBounds.rect.top) && - approximatelyEqual(elementSize.width, rootBounds.width) && - approximatelyEqual(elementSize.height, rootBounds.height) +export function coversCompositionRoot( + layer: { rect: Box; computedStyles: Record }, + root: CompositionRootFacts | null, +): boolean { + if (isExplicitFullBleedLayer(layer.computedStyles)) return false; + const rootWidth = readPositiveDimension(root?.width ?? null); + const rootHeight = readPositiveDimension(root?.height ?? null); + if (!root || !rootWidth || !rootHeight) return false; + const width = layer.rect.width || parsePx(layer.computedStyles.width); + const height = layer.rect.height || parsePx(layer.computedStyles.height); + return Boolean( + width && + height && + approximatelyEqual(layer.rect.left, root.rect.left) && + approximatelyEqual(layer.rect.top, root.rect.top) && + approximatelyEqual(width, rootWidth) && + approximatelyEqual(height, rootHeight), ); } @@ -52,13 +56,14 @@ export function isCompositionRootLayer( ) { if (element.parentElement !== doc.body) return false; if (element.hasAttribute("data-hf-allow-root-edit")) return false; - if (isExplicitFullBleedLayer(computedStyles)) return false; - - const rootBounds = getCompositionRootBounds(doc); - const elementSize = getRenderedLayerSize(element, computedStyles); - return Boolean( - rootBounds && - elementSize && - matchesCompositionRootBounds(element.getBoundingClientRect(), elementSize, rootBounds), + const root = + doc.querySelector("[data-composition-id]") ?? doc.documentElement ?? null; + return coversCompositionRoot( + { rect: element.getBoundingClientRect(), computedStyles }, + root && { + rect: root.getBoundingClientRect(), + width: root.getAttribute("data-width"), + height: root.getAttribute("data-height"), + }, ); } diff --git a/packages/studio/src/components/editor/domEditingTypes.ts b/packages/studio/src/components/editor/domEditingTypes.ts index 1839b56e04..249050cb78 100644 --- a/packages/studio/src/components/editor/domEditingTypes.ts +++ b/packages/studio/src/components/editor/domEditingTypes.ts @@ -1,5 +1,6 @@ import type { PatchTarget } from "../../utils/sourcePatcher"; import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser"; +import type { EditingElementHandle } from "@hyperframes/core/runtime/editing-port"; export const CURATED_STYLE_PROPERTIES = [ "position", @@ -78,6 +79,7 @@ export interface DomEditTextField { export interface DomEditSelection extends PatchTarget { element: HTMLElement; + handle?: EditingElementHandle; label: string; tagName: string; sourceFile: string; diff --git a/packages/studio/src/components/editor/previewSelection.test.ts b/packages/studio/src/components/editor/previewSelection.test.ts new file mode 100644 index 0000000000..6e48e18bb1 --- /dev/null +++ b/packages/studio/src/components/editor/previewSelection.test.ts @@ -0,0 +1,376 @@ +// @vitest-environment happy-dom + +import React, { act } from "react"; +import { createRoot } from "react-dom/client"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { EDITING_ELEMENT_HANDLE } from "@hyperframes/core/runtime/editing-port"; +// The frame's real runtime agent, serving the opaque frame from this document. +import { installEditingAgent } from "../../../../core/src/runtime/editingAgent"; +import { + findElementForSelection, + findElementForTimelineElement, + resolveDomEditSelection, + type DomEditSelection, +} from "./domEditing"; +import { setCompositionSourceMap } from "./domEditingDom"; +import { + findPreviewElementForSelection, + findPreviewElementForTimelineElement, + resolvePreviewSelection, + type PreviewSelectionOptions, +} from "./previewSelection"; +import { + describePreviewElements, + previewElementsAtPoint, + type PreviewElement, +} from "../../player/lib/previewElements"; +import { detachedFakeIframe } from "../../player/hooks/timelinePlayerTestHarness"; +import { installReactActEnvironment } from "../../hooks/domSelectionTestHarness"; +import { useDomSelection } from "../../hooks/useDomSelection"; +import type { TimelineElement } from "../../player"; + +installReactActEnvironment(); + +const closers: Array<() => void> = []; +afterEach(() => { + closers.splice(0).forEach((close) => close()); + setCompositionSourceMap(new Map()); + document.body.innerHTML = ""; + delete (document as { elementsFromPoint?: unknown }).elementsFromPoint; +}); + +/** A frame Studio scripts directly; its document is this one. */ +function liveFrame(): HTMLIFrameElement { + const iframe = detachedFakeIframe({}); + Object.defineProperty(iframe, "contentDocument", { value: document }); + return iframe; +} + +/** A frame Studio cannot read, whose runtime is the real editing agent over this document. */ +function opaqueFrame(): HTMLIFrameElement { + const frame: Record = {}; + const iframe = detachedFakeIframe(frame); + Object.defineProperty(iframe, "contentDocument", { value: null }); + Object.defineProperty(frame, "document", { + get: () => { + throw new DOMException("blocked", "SecurityError"); + }, + }); + const parent = { + postMessage: (data: unknown, _origin: string, ports: MessagePort[]) => + window.dispatchEvent( + new MessageEvent("message", { source: frame as unknown as Window, data, ports }), + ), + } as unknown as Window; + const agent = installEditingAgent(parent); + frame.postMessage = (data: unknown) => + window.dispatchEvent(new MessageEvent("message", { source: parent, data })); + closers.push(() => agent.dispose()); + return iframe; +} + +const CONTEXT: PreviewSelectionOptions = { + activeCompositionPath: "index.html", + isMasterView: false, +}; + +/** The selection both paths agree on: everything but the element itself and its text fields. */ +function shared(selection: DomEditSelection | null) { + if (!selection) return null; + const { element: _element, handle: _handle, textFields: _fields, ...rest } = selection; + return rest; +} + +/** The opaque frame's description of `element`, as a hit-test would hand it over. */ +async function describedOnOpaque(iframe: HTMLIFrameElement, element: Element) { + Object.defineProperty(document, "elementsFromPoint", { + configurable: true, + value: () => [element], + }); + const [hit] = (await previewElementsAtPoint(iframe, 0, 0)) ?? []; + const [described] = (await describePreviewElements(iframe, [hit!.handle])) ?? []; + return described!; +} + +async function bothPaths(element: HTMLElement, options: PreviewSelectionOptions = CONTEXT) { + const opaque = opaqueFrame(); + const live = await resolveDomEditSelection(element, options); + const remote = await resolvePreviewSelection( + opaque, + await describedOnOpaque(opaque, element), + options, + ); + return { live, remote, opaque }; +} + +const NAMES = ["id", "data-hf-id", "data-pick", "data-composition-id"]; +const nameOf = (element: Element) => + NAMES.map((name) => element.getAttribute(name)).find(Boolean) ?? null; +const named = (element: PreviewElement) => + NAMES.map((name) => element.attributes.find(([key]) => key === name)?.[1]).find(Boolean) ?? null; + +const FIXTURE = ` +
+
+

Member

+
+
bold
+
in
+

Locked

+ +
+

no selector here

+
+
`; + +describe("opaque frame selections match same-origin ones", () => { + it.each([ + ["a group member at the top level selects the outermost group", "[data-hf-id=m1]", {}], + ["a clip's child, preferring the clip ancestor, selects the clip", "b", { clip: true }], + ["a host clip is not taken for its child", "#in-host", { clip: true }], + ["an element with no selector walks up to its addressable parent", "#plain b", {}], + ["a timeline-locked element is selected as locked", "#locked", {}], + ["a class match counts its index within its own file", "[data-pick=t2]", {}], + ["a body child sitting on the root counts as the composition root", "#bg", {}], + ])("%s", async (_name, selector, flags: { clip?: boolean }) => { + document.body.innerHTML = FIXTURE; + const { live, remote } = await bothPaths(document.querySelector(selector)!, { + ...CONTEXT, + preferClipAncestor: flags.clip, + }); + expect(live).not.toBeNull(); + expect(shared(remote)).toEqual(shared(live)); + expect(remote!.handle).toMatch(EDITING_ELEMENT_HANDLE); + expect(remote!.tagName).toBe(live!.element.tagName.toLowerCase()); + }); + + it("covers the cases each rule decides", async () => { + document.body.innerHTML = FIXTURE; + const pick = async (selector: string, clip = false) => + (await bothPaths(document.querySelector(selector)!, { + ...CONTEXT, + preferClipAncestor: clip, + }))!.remote!; + expect((await pick("[data-hf-id=m1]")).selector).toBe("#outer-wrap"); + expect((await pick("b", true)).id).toBe("scene"); + expect((await pick("#in-host", true)).id).toBe("in-host"); + expect((await pick("#plain b")).id).toBe("plain"); + expect(await pick("#locked")).toMatchObject({ + isInsideLockedComposition: true, + inlineStyles: { "border-radius": "8px" }, + dataAttributes: { start: "2" }, + label: "Locked", + }); + expect(await pick("[data-pick=t2]")).toMatchObject({ + sourceFile: "compositions/cards.html", + selectorIndex: 1, + }); + expect((await pick("#bg")).capabilities).toMatchObject({ + canCrop: false, + canApplyManualOffset: false, + }); + expect((await pick("#plain")).capabilities.canApplyManualOffset).toBe(true); + }); + + it("follows a drilled-into group: its nested group, then its children, else the top level", async () => { + document.body.innerHTML = FIXTURE; + const member = document.querySelector("[data-hf-id=m1]")!; + const opaque = opaqueFrame(); + const described = await describedOnOpaque(opaque, member); + const outerLive = document.querySelector('[data-hf-group="outer"]')!; + const innerLive = document.querySelector('[data-hf-group="inner"]')!; + // On an opaque frame the drilled-into group is the stand-in of an earlier selection. + const outerRemote = (await resolvePreviewSelection(opaque, described, CONTEXT))!.element; + const innerRemote = (await resolvePreviewSelection(opaque, described, { + ...CONTEXT, + activeGroupElement: outerRemote, + }))!.element; + const cases: Array<[HTMLElement | null, HTMLElement | null, string]> = [ + [outerLive, outerRemote, '[data-hf-group="inner"]'], + [innerLive, innerRemote, ".member"], + [document.querySelector("#scene"), null, "#outer-wrap"], + ]; + for (const [activeLive, activeRemote, selector] of cases) { + const live = await resolveDomEditSelection(member, { + ...CONTEXT, + activeGroupElement: activeLive, + }); + const remote = await resolvePreviewSelection(opaque, described, { + ...CONTEXT, + activeGroupElement: activeRemote ?? document.createElement("div"), + }); + expect(live!.selector).toBe(selector); + expect(shared(remote)).toEqual(shared(live)); + } + }); + + it.each([ + [ + "by selector and index in its own file", + { selector: ".tile", selectorIndex: 1, sourceFile: "compositions/cards.html" }, + ], + ["by id", { id: "t-index", sourceFile: "index.html" }], + ["by hf id", { hfId: "m1" }], + ["nothing for a selector with no match", { selector: ".missing" }], + ["nothing for an invalid selector", { selector: "p[" }], + ])("finds an element for a selection %s", async (_name, selection) => { + document.body.innerHTML = FIXTURE; + const live = findElementForSelection(document, selection, "index.html"); + const found = await findPreviewElementForSelection(opaqueFrame(), selection, "index.html"); + expect(live === null ? null : nameOf(live)).toBe(found === null ? null : found && named(found)); + if (selection.selector !== ".missing" && selection.selector !== "p[") + expect(live).not.toBeNull(); + }); + + it.each([ + [ + "a clip by selector", + { id: "x", selector: ".tile", selectorIndex: 1, sourceFile: "compositions/cards.html" }, + false, + "t2", + ], + ["the root, from the active composition, outside the master view", { id: "x" }, false, "main"], + ["nothing in the master view without a DOM target", { id: "x" }, true, null], + ])("finds a timeline element: %s", async (_name, element, isMasterView, expected) => { + document.body.innerHTML = FIXTURE; + const options = { activeCompositionPath: "index.html", isMasterView }; + const live = findElementForTimelineElement(document, element, options); + const found = await findPreviewElementForTimelineElement(opaqueFrame(), element, options); + expect(live && nameOf(live)).toBe(expected); + expect(found && named(found)).toBe(expected); + }); +}); + +describe("opaque frame selection handles", () => { + it("gives a selection an inert, tag-only stand-in, the same one for a handle", async () => { + document.body.innerHTML = FIXTURE; + const { remote, opaque } = await bothPaths(document.querySelector("#locked")!); + const again = await resolvePreviewSelection( + opaque, + await describedOnOpaque(opaque, document.querySelector("#locked")!), + { ...CONTEXT, previous: remote }, + ); + expect(again!.element).toBe(remote!.element); + expect(remote!.element.tagName).toBe("P"); + expect(remote!.element.attributes).toHaveLength(0); + expect(remote!.element.textContent).toBe(""); + expect(remote!.element.ownerDocument.defaultView).toBeNull(); + expect(remote!.element.ownerDocument).not.toBe(document); + }); + + it("builds nothing for a removed element, and finds nothing the runtime cannot name", async () => { + document.body.innerHTML = FIXTURE; + const opaque = opaqueFrame(); + const locked = document.querySelector("#locked")!; + const described = await describedOnOpaque(opaque, locked); + // A description whose parent is not the element its runtime names as the parent. + const unlinked = { ...described, parent: described.handle }; + expect(await resolvePreviewSelection(opaque, unlinked, CONTEXT)).toBeNull(); + expect(await resolvePreviewSelection(opaque, described, CONTEXT)).not.toBeNull(); + locked.remove(); + expect(await resolvePreviewSelection(opaque, described, CONTEXT)).toBeNull(); + const stale = { + ...described, + handle: described.handle.replace(/^[0-9a-f]{16}/, "f".repeat(16)), + }; + expect(await resolvePreviewSelection(opaque, stale, CONTEXT)).toBeNull(); + }); + + it("says it cannot tell when the frame has no editing agent", async () => { + vi.useFakeTimers(); + try { + const frame: Record = { postMessage: () => {} }; + const iframe = detachedFakeIframe(frame); + const pending = findPreviewElementForSelection(iframe, { id: "plain" }, "index.html"); + await vi.advanceTimersByTimeAsync(2_000); + expect(await pending).toBeUndefined(); + } finally { + vi.useRealTimers(); + } + }); + + it("says it cannot tell when a capped query does not reach the index", async () => { + document.body.innerHTML = "".repeat(2_049); + const found = await findPreviewElementForSelection( + opaqueFrame(), + { selector: ".n", selectorIndex: 2_048 }, + "index.html", + ); + expect(found).toBeUndefined(); + }); +}); + +describe("useDomSelection on an opaque frame", () => { + function renderSelection(iframe: HTMLIFrameElement) { + let hook: ReturnType | null = null; + function Harness() { + hook = useDomSelection({ + projectId: null, + activeCompPath: "index.html", + isMasterView: false, + compIdToSrc: new Map(), + captionEditMode: false, + previewIframeRef: { current: iframe }, + timelineElements: [], + getTimelineSelectionSet: () => new Set(), + setSelectedTimelineElementId: vi.fn(), + setTimelineSelectionSet: vi.fn(), + setRightCollapsed: vi.fn(), + setRightPanelTab: vi.fn(), + previewIframe: iframe, + refreshKey: 0, + rightPanelTab: "design", + }); + return null; + } + const host = document.createElement("div"); + const root = createRoot(host); + act(() => root.render(React.createElement(Harness))); + closers.push(() => act(() => root.unmount())); + return () => hook!; + } + + const clip = (selector: string) => + ({ + id: "c", + selector, + selectorIndex: 0, + sourceFile: "index.html", + }) as unknown as TimelineElement; + + it("selects a timeline clip, refreshes it, and drops it once the frame no longer has it", async () => { + document.body.innerHTML = FIXTURE; + const liveHook = renderSelection(liveFrame()); + const hook = renderSelection(opaqueFrame()); + await act(() => liveHook().handleTimelineElementSelect(clip("#locked"))); + await act(() => hook().handleTimelineElementSelect(clip("#locked"))); + const selected = hook().domEditSelection!; + expect(selected.handle).toMatch(EDITING_ELEMENT_HANDLE); + expect(shared(selected)).toEqual(shared(liveHook().domEditSelection)); + + document.querySelector("#locked")!.style.left = "12px"; + await act(() => hook().refreshDomEditSelectionFromPreview(selected)); + expect(hook().domEditSelection!.inlineStyles.left).toBe("12px"); + expect(hook().domEditSelection!.element).toBe(selected.element); + + document.querySelector("#locked")!.remove(); + await act(() => hook().refreshDomEditSelectionFromPreview(hook().domEditSelection!)); + expect(hook().domEditSelection).toBeNull(); + }); + + it("re-finds every group member on refresh", async () => { + document.body.innerHTML = FIXTURE; + const hook = renderSelection(opaqueFrame()); + await act(() => hook().handleTimelineElementSelect(clip("#locked"))); + const first = hook().domEditSelection!; + await act(() => hook().handleTimelineElementSelect(clip("#plain"))); + const second = hook().domEditSelection!; + act(() => hook().applyDomSelection(first, { additive: true })); + expect(hook().domEditGroupSelections).toHaveLength(2); + + document.querySelector("#locked")!.remove(); + await act(() => hook().refreshDomEditSelectionFromPreview(first)); + expect(hook().domEditGroupSelections.map((s) => s.id)).toEqual(["plain"]); + expect(hook().domEditSelection!.handle).toBe(second.handle); + }); +}); diff --git a/packages/studio/src/components/editor/previewSelection.ts b/packages/studio/src/components/editor/previewSelection.ts new file mode 100644 index 0000000000..5f3db0e4d9 --- /dev/null +++ b/packages/studio/src/components/editor/previewSelection.ts @@ -0,0 +1,361 @@ +/** + * Selections in a preview frame Studio cannot script, built from its runtime's element + * descriptions. Which element a selection lands on comes from `domEditSelectionRules.ts`, the + * rules a scriptable frame's selections use, so both kinds of frame select the same element. + * + * Such a selection's `element` is a stand-in: an element with only the target's tag, in a + * document with no window, the same one for a handle for the whole frame load. Nothing in it + * loads, runs or renders, and nothing from the frame is copied into it. The frame's element is + * the selection's `handle`. + */ +import { resolveEditingAffordances } from "@hyperframes/core/editing"; +import type { EditingPortClient } from "@hyperframes/core/runtime/editing-port"; +import { + previewComputedStyles, + previewEditingClient, + previewFrameOpaque, +} from "../../player/lib/previewChannel"; +import { + describePreviewElements, + previewAncestors, + previewElementSelectorIndex, + previewElementSourceFile, + queryPreviewElements, + type PreviewElement, +} from "../../player/lib/previewElements"; +import { coversCompositionRoot } from "./domEditingRootLayer"; +import { + buildElementLabel, + getDataAttributes, + getInlineStyles, + isHtmlElement, + resolveElementSourceFile, +} from "./domEditingDom"; +import { findElementForSelection } from "./domEditingElement"; +import { capabilityFacts, resolveDomEditSelection } from "./domEditingLayers"; +import { + chainLocked, + selectionLookups, + selectionTargetIndex, + timelineElementLookup, + type SelectionChainReader, + type SelectionLookupTarget, +} from "./domEditSelectionRules"; +import { + CURATED_STYLE_PROPERTIES, + type DomEditContextOptions, + type DomEditSelection, + type TimelineElementDomTarget, + type TimelineElementDomTargetOptions, +} from "./domEditingTypes"; +import { existsInSourceFile } from "./probeSourceElement"; + +let inertDocument: Document | undefined; +const inert = () => (inertDocument ??= document.implementation.createHTMLDocument("")); + +function inertElement(tag: string): HTMLElement { + try { + return inert().createElement(tag); + } catch { + return inert().createElement("div"); + } +} + +const standIns = new WeakMap>(); +const standInHandles = new WeakMap(); + +function standInFor(iframe: HTMLIFrameElement, element: PreviewElement): HTMLElement { + const client = previewEditingClient(iframe); + const byHandle = standIns.get(client) ?? new Map(); + standIns.set(client, byHandle); + let standIn = byHandle.get(element.handle); + if (!standIn) { + standIn = inertElement(element.tag); + byHandle.set(element.handle, standIn); + standInHandles.set(standIn, element.handle); + } + return standIn; +} + +/** + * The description as an element of the inert document, discarded after the read, so the label, + * data-attribute and inline-style helpers read it as they read a live element. + */ +function readable(element: PreviewElement): HTMLElement { + const probe = inertElement(element.tag); + for (const [name, value] of element.attributes) { + if (name !== "id" && name !== "class" && !name.startsWith("data-")) continue; + try { + probe.setAttribute(name, value); + } catch { + // A name the parser took but setAttribute refuses; no helper reads such a name. + } + } + for (const [name, value] of Object.entries(element.inlineStyles)) { + probe.style.setProperty(name, value); + } + probe.textContent = element.text; + return probe; +} + +const attr = (element: PreviewElement, name: string) => + element.attributes.find(([key]) => key === name)?.[1] ?? null; + +/** Undefined when the frame cannot answer; null when nothing matches. */ +type Found = PreviewElement | null | undefined; + +const validSelector = (selector: string) => { + try { + inert().querySelector(selector); + return true; + } catch { + return false; + } +}; + +/** `findElementForSelection` over the frame's runtime. */ +export async function findPreviewElementForSelection( + iframe: HTMLIFrameElement, + selection: SelectionLookupTarget, + activeCompositionPath: string | null, +): Promise { + for (const { selector, index } of selectionLookups(selection)) { + if (!validSelector(selector)) continue; + const reply = await queryPreviewElements(iframe, selector); + if (!reply) return undefined; + const fromFile = reply.matches.filter( + ({ source }) => + !selection.sourceFile || + resolveElementSourceFile(source, activeCompositionPath) === selection.sourceFile, + ); + const match = fromFile[index]; + if (!match) { + if (reply.truncated) return undefined; + continue; + } + const [element] = (await describePreviewElements(iframe, [match.handle])) ?? []; + return element ?? undefined; + } + return null; +} + +/** `findElementForTimelineElement` over the frame's runtime. */ +export async function findPreviewElementForTimelineElement( + iframe: HTMLIFrameElement, + element: TimelineElementDomTarget, + options: TimelineElementDomTargetOptions, +): Promise { + const { target, sourceFile, rootFallback } = timelineElementLookup(element, options); + const path = options.activeCompositionPath; + const found = target && (await findPreviewElementForSelection(iframe, target, path)); + if (found !== null) return found; + if (!rootFallback) return null; + const reply = await queryPreviewElements(iframe, "[data-composition-id]"); + if (!reply) return undefined; + const root = reply.matches[0]; + if (!root || resolveElementSourceFile(root.source, path) !== sourceFile) return null; + const [described] = (await describePreviewElements(iframe, [root.handle])) ?? []; + return described ?? undefined; +} + +/** The target and every ancestor up to the document element, or null when any is missing. */ +async function previewChain( + iframe: HTMLIFrameElement, + target: PreviewElement, +): Promise { + const [lineage] = (await previewAncestors(iframe, [target.handle])) ?? []; + if (!lineage) return null; + const ancestors = lineage.length ? await describePreviewElements(iframe, lineage) : []; + if (!ancestors || ancestors.some((entry) => entry === null)) return null; + const chain = [target, ...(ancestors as PreviewElement[])]; + const linked = chain.every((node, i) => node.parent === (chain[i + 1]?.handle ?? null)); + return linked ? chain : null; +} + +function chainReader(chain: readonly PreviewElement[]): SelectionChainReader { + const root = chain.at(-1); + const body = chain.at(-2); + return { + attr, + selector: (node) => node.selector ?? undefined, + isDocumentRoot: (node) => node === root || (node === body && node.tag === "body"), + }; +} + +async function compositionRoot(iframe: HTMLIFrameElement, documentElement: PreviewElement) { + const reply = await queryPreviewElements(iframe, "[data-composition-id]"); + const first = reply?.matches[0]; + const [root] = first ? ((await describePreviewElements(iframe, [first.handle])) ?? []) : []; + const element = root ?? documentElement; + const { x, y, width, height } = element.rect; + return { + rect: { left: x, top: y, width, height }, + width: attr(element, "data-width"), + height: attr(element, "data-height"), + }; +} + +export type PreviewSelectionOptions = DomEditContextOptions & { + projectId?: string | null; + skipSourceProbe?: boolean; + exactTarget?: boolean; + previous?: DomEditSelection | null; +}; + +function chainIndex( + chain: readonly PreviewElement[], + read: SelectionChainReader, + options: PreviewSelectionOptions, +): number | null { + const active = options.activeGroupElement; + const activeHandle = active ? standInHandles.get(active) : undefined; + return selectionTargetIndex(chain, read, { + exactTarget: options.exactTarget, + preferClipAncestor: options.preferClipAncestor, + activeGroupIndex: active ? chain.findIndex((node) => node.handle === activeHandle) : null, + }); +} + +function previewIdentity(current: PreviewElement, path: string | null) { + const selector = current.selector ?? undefined; + return { + id: current.id || undefined, + hfId: attr(current, "data-hf-id")?.trim() || undefined, + selector, + selectorIndex: selector ? previewElementSelectorIndex(current, path) : undefined, + sourceFile: previewElementSourceFile(current, path), + }; +} + +async function isPreviewCompositionRoot( + iframe: HTMLIFrameElement, + chain: readonly PreviewElement[], + index: number, + computedStyles: Record, +): Promise { + const current = chain[index]!; + if (attr(current, "data-composition-id") !== null && !compositionSourceOf(current)) return true; + const parent = chain[index + 1]; + const underBody = parent?.tag === "body" && chainReader(chain).isDocumentRoot(parent); + if (!underBody || attr(current, "data-hf-allow-root-edit") !== null) return false; + const { x, y, width, height } = current.rect; + const rect = { left: x, top: y, width, height }; + return coversCompositionRoot( + { rect, computedStyles }, + await compositionRoot(iframe, chain.at(-1)!), + ); +} + +const compositionSourceOf = (element: PreviewElement) => + attr(element, "data-composition-src") ?? attr(element, "data-composition-file") ?? undefined; + +/** + * `resolveDomEditSelection` for a frame element Studio has a description of. Text fields are left + * empty: they are read for text edits, which write through the frame's document. + */ +export async function resolvePreviewSelection( + iframe: HTMLIFrameElement, + target: PreviewElement, + options: PreviewSelectionOptions, +): Promise { + const chain = await previewChain(iframe, target); + const index = chain && chainIndex(chain, chainReader(chain), options); + if (!chain || index === null) return null; + const current = chain[index]!; + const element = standInFor(iframe, current); + const identity = previewIdentity(current, options.activeCompositionPath); + const compositionSrc = compositionSourceOf(current); + const probe = readable(current); + const inlineStyles = getInlineStyles(probe); + const computedStyles = + (await previewComputedStyles(iframe, current, [...CURATED_STYLE_PROPERTIES])) ?? {}; + const isCompositionRoot = await isPreviewCompositionRoot(iframe, chain, index, computedStyles); + const isInsideLocked = chainLocked(chain, chainReader(chain), index); + const { sourceFile } = identity; + const existsInSource = await existsInSourceFile( + options.previous, + element, + sourceFile, + identity, + options, + ); + const capabilities = resolveEditingAffordances( + capabilityFacts({ + hasStableTarget: Boolean(identity.selector || identity.hfId), + tag: current.tag, + inlineStyles, + computedStyles, + isCompositionHost: Boolean(compositionSrc), + isCompositionRoot, + isInsideLockedComposition: isInsideLocked, + isMasterView: options.isMasterView, + existsInSource: existsInSource ?? true, + }), + ).capabilities; + const { x, y, width, height } = current.rect; + + return { + element, + handle: current.handle, + ...identity, + compositionPath: sourceFile, + compositionSrc, + isCompositionHost: Boolean(compositionSrc), + isInsideLockedComposition: isInsideLocked, + label: buildElementLabel(probe), + tagName: current.tag, + boundingBox: { x, y, width, height }, + textContent: current.text.trim() || null, + dataAttributes: getDataAttributes(probe), + inlineStyles, + computedStyles, + textFields: [], + capabilities, + existsInSource, + }; +} + +function liveElementForSelection( + iframe: HTMLIFrameElement | null, + selection: SelectionLookupTarget, + activeCompositionPath: string | null, +): HTMLElement | null | undefined { + let doc: Document | null = null; + try { + doc = iframe?.contentDocument ?? null; + } catch { + return undefined; + } + return doc ? findElementForSelection(doc, selection, activeCompositionPath) : undefined; +} + +/** `selection`'s element in the frame now, or its description; undefined when the frame cannot answer. */ +export async function findSelectionElement( + iframe: HTMLIFrameElement | null, + selection: SelectionLookupTarget, + activeCompositionPath: string | null, +): Promise { + return iframe && previewFrameOpaque(iframe) + ? findPreviewElementForSelection(iframe, selection, activeCompositionPath) + : liveElementForSelection(iframe, selection, activeCompositionPath); +} + +/** `resolveDomEditSelection` for an element, or for a description from `iframe`. */ +export async function resolveFoundSelection( + iframe: HTMLIFrameElement | null, + found: HTMLElement | PreviewElement, + options: PreviewSelectionOptions, +): Promise { + if (isHtmlElement(found)) return resolveDomEditSelection(found, options); + return iframe ? resolvePreviewSelection(iframe, found, options) : null; +} + +/** A timeline element's description in a frame Studio cannot script; null for any other frame. */ +export async function findOpaqueTimelineElement( + iframe: HTMLIFrameElement | null, + element: TimelineElementDomTarget, + lookup: TimelineElementDomTargetOptions, +): Promise { + if (!iframe || !previewFrameOpaque(iframe)) return null; + return (await findPreviewElementForTimelineElement(iframe, element, lookup)) ?? null; +} diff --git a/packages/studio/src/components/editor/probeSourceElement.ts b/packages/studio/src/components/editor/probeSourceElement.ts index a1e6c551ad..da75cbe322 100644 --- a/packages/studio/src/components/editor/probeSourceElement.ts +++ b/packages/studio/src/components/editor/probeSourceElement.ts @@ -4,7 +4,7 @@ import type { DomEditSelection } from "./domEditingTypes"; export type ProbeTarget = { id?: string; hfId?: string; selector?: string; selectorIndex?: number }; -export function knownSourceAnswer( +function knownSourceAnswer( previous: DomEditSelection | null | undefined, element: HTMLElement, sourceFile: string, @@ -68,3 +68,21 @@ export function probeSourceElement( probes.push({ target, resolve }); }); } + +export async function existsInSourceFile( + previous: DomEditSelection | null | undefined, + element: HTMLElement, + sourceFile: string, + target: ProbeTarget, + options: { projectId?: string | null; skipSourceProbe?: boolean }, +): Promise { + const probeTarget: ProbeTarget = {}; + if (target.id) probeTarget.id = target.id; + if (target.hfId) probeTarget.hfId = target.hfId; + if (target.selector) probeTarget.selector = target.selector; + if (target.selectorIndex != null) probeTarget.selectorIndex = target.selectorIndex; + const known = knownSourceAnswer(previous, element, sourceFile, probeTarget); + if (known !== undefined || options.skipSourceProbe || !options.projectId) return known; + if (!target.id && !target.selector && !target.hfId) return known; + return probeSourceElement(options.projectId, sourceFile, probeTarget); +} diff --git a/packages/studio/src/hooks/useDomSelection.ts b/packages/studio/src/hooks/useDomSelection.ts index 1360d309fb..e651332cbb 100644 --- a/packages/studio/src/hooks/useDomSelection.ts +++ b/packages/studio/src/hooks/useDomSelection.ts @@ -13,11 +13,15 @@ import { seedDomEditGroupWithSelection, } from "../utils/domEditHelpers"; import { - findElementForSelection, findElementForTimelineElement, - resolveDomEditSelection, type DomEditSelection, } from "../components/editor/domEditing"; +import { + findOpaqueTimelineElement, + findSelectionElement, + resolveFoundSelection, +} from "../components/editor/previewSelection"; +import type { PreviewElement } from "../player/lib/previewElements"; import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits"; import { holdScenesOf } from "../utils/sceneHold"; import { useStudioTestHooks } from "./useStudioTestHooks"; @@ -216,8 +220,12 @@ export function useDomSelection({ ); const buildDomSelectionFromTarget = useCallback( - (target: HTMLElement, options?: ResolveDomSelectionOptions) => { - return resolveDomEditSelection(target, { + ( + target: HTMLElement | PreviewElement, + options?: ResolveDomSelectionOptions, + iframe = previewIframeRef.current, + ) => { + return resolveFoundSelection(iframe, target, { activeCompositionPath: activeCompPath, isMasterView, preferClipAncestor: options?.preferClipAncestor, @@ -231,7 +239,7 @@ export function useDomSelection({ projectId, }); }, - [activeCompPath, isMasterView, projectId], + [activeCompPath, isMasterView, previewIframeRef, projectId], ); const resolveDomSelectionFromPreviewPoint = useCallback( @@ -302,23 +310,25 @@ export function useDomSelection({ // fallow-ignore-next-line complexity async (element: TimelineElement): Promise => { const iframe = previewIframeRef.current; + const lookup = { activeCompositionPath: activeCompPath, compIdToSrc, isMasterView }; let doc: Document | null = null; try { doc = iframe?.contentDocument ?? null; } catch { return null; } - if (!doc) return null; + if (!doc) { + const found = await findOpaqueTimelineElement(iframe, element, lookup); + return found + ? buildDomSelectionFromTarget(found, { preferClipAncestor: false }, iframe) + : null; + } const held = holdScenesOf(iframe, element); if (held) await held; reapplyPositionEditsAfterSeek(doc); - const targetElement = findElementForTimelineElement(doc, element, { - activeCompositionPath: activeCompPath, - compIdToSrc, - isMasterView, - }); + const targetElement = findElementForTimelineElement(doc, element, lookup); return targetElement ? buildDomSelectionFromTarget(targetElement, { preferClipAncestor: false, @@ -365,15 +375,8 @@ export function useDomSelection({ const stillSelected = () => domEditSelectionsTargetSame(domEditSelectionRef.current, selection); if (!stillSelected()) return; - let doc: Document | null = null; - try { - doc = iframe?.contentDocument ?? null; - } catch { - return; - } - if (!doc) return; - - const element = findElementForSelection(doc, selection, activeCompPath); + const element = await findSelectionElement(iframe, selection, activeCompPath); + if (element === undefined || !stillSelected()) return; if (!element) { // Losing the primary is not losing the selection. When a group is live, // re-resolve it and keep whoever still exists rather than wiping the lot. @@ -390,7 +393,11 @@ export function useDomSelection({ return; } - const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection }); + const nextSelection = await buildDomSelectionFromTarget( + element, + { previous: selection }, + iframe, + ); if (nextSelection && stillSelected()) { applyDomSelection(nextSelection, { revealPanel: false, @@ -405,17 +412,10 @@ export function useDomSelection({ // fallow-ignore-next-line complexity async (selections: DomEditSelection[]) => { const iframe = previewIframeRef.current; - let doc: Document | null = null; - try { - doc = iframe?.contentDocument ?? null; - } catch { - return; - } - if (!doc) return; - const nextGroup: DomEditSelection[] = []; for (const selection of selections) { - const element = findElementForSelection(doc, selection, activeCompPath); + const element = await findSelectionElement(iframe, selection, activeCompPath); + if (element === undefined) return; if (!element) continue; const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection }); if (nextSelection) nextGroup.push(nextSelection); diff --git a/packages/studio/src/hooks/usePreviewInteraction.ts b/packages/studio/src/hooks/usePreviewInteraction.ts index 9b5395307e..7cfb3bba04 100644 --- a/packages/studio/src/hooks/usePreviewInteraction.ts +++ b/packages/studio/src/hooks/usePreviewInteraction.ts @@ -190,7 +190,7 @@ export function usePreviewInteraction({ preferClipAncestor: options?.preferClipAncestor ?? false, }); // A null result while drilled into a group means the click landed OUTSIDE that - // group (resolveGroupCapture → out-of-scope). Drill-in isn't sticky: exit it and + // group (selectionTargetIndex: out of scope). Drill-in isn't sticky: exit it and // re-resolve at the top level so this click selects whatever's there (or the // group as a unit). Without this, a stale drill-in keeps selecting children and // the "first click selects the group" expectation breaks. diff --git a/packages/studio/src/player/lib/previewChannel.ts b/packages/studio/src/player/lib/previewChannel.ts index 41e3727e41..e63e0ec570 100644 --- a/packages/studio/src/player/lib/previewChannel.ts +++ b/packages/studio/src/player/lib/previewChannel.ts @@ -97,13 +97,14 @@ export async function previewClipManifest(iframe: HTMLIFrameElement): Promise | null> { - const reply = await previewRequest(iframe, "computed-styles", { selector, properties }); + const element = typeof target === "string" ? { selector: target } : { handle: target.handle }; + const reply = await previewRequest(iframe, "computed-styles", { ...element, 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.ts b/packages/studio/src/player/lib/previewElements.ts index 7b345ae8eb..8914b5c240 100644 --- a/packages/studio/src/player/lib/previewElements.ts +++ b/packages/studio/src/player/lib/previewElements.ts @@ -7,6 +7,7 @@ import { MAX_DESCRIBE_HANDLES, type EditingElementDescription, type EditingElementHit, + type EditingElementMatch, type EditingElementSource, } from "@hyperframes/core/runtime/editing-port"; import { resolveElementSourceFile } from "../../components/editor/domEditingDom"; @@ -96,6 +97,32 @@ export async function describePreviewElements( }); } +/** Each handle's ancestors, parent first; null for an element the frame no longer has. */ +export async function previewAncestors( + iframe: HTMLIFrameElement, + handles: readonly string[], +): Promise | null> { + if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null; + const reply = await previewRequest(iframe, "ancestors", { handles: [...handles] }); + const chains: unknown = reply?.ancestors; + if (!Array.isArray(chains) || chains.length !== handles.length) return null; + return chains.map((chain) => + Array.isArray(chain) && chain.every(isHandle) ? (chain as string[]) : null, + ); +} + +/** The frame's matches for `selector` in document order; null when the runtime cannot answer. */ +export async function queryPreviewElements( + iframe: HTMLIFrameElement, + selector: string, +): Promise<{ matches: EditingElementMatch[]; truncated: boolean } | null> { + const reply = await previewRequest(iframe, "query", { selector }); + const matches: unknown = reply?.matches; + if (!Array.isArray(matches) || typeof reply?.truncated !== "boolean") return null; + const ok = matches.every((m) => isFields(m) && isHandle(m.handle) && isSource(m.source)); + return ok ? { matches: matches as EditingElementMatch[], truncated: reply.truncated } : null; +} + /** `getSourceFileForElement` for the frame's own element. */ export function previewElementSourceFile( element: PreviewElement,