Files
hyperframes/packages/core/src/runtime/picker.ts
T
Xuanru Li c694785df5 fix(core): faint SVG grain is not a click target, and a page reset is not an element's CSS (#5628)
* fix(core): a faint SVG grain is not the click target, and a page reset is not an element's CSS

A filter rect under an svg at opacity 0.07 was still picked. The veil check
required that element's own opacity and a background-image. A `*` rule matched
every element, so a rect was given the page reset as its CSS.

fails without the fix: clicking the grain selects the rect, and inspection attaches `*`.

* fix(core): keep picker comments within the source ratchet

* fix(core): preserve selector literals and SVG veil boundaries
2026-10-15 04:04:13 +00:00

458 lines
18 KiB
TypeScript

import type { RuntimeJson, RuntimeOutboundMessage, RuntimePickerElementInfo } from "./types";
import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "../colorGrading";
import { swallow } from "./diagnostics";
import { isElementNode } from "./domRealm";
import { createDrawnProbe } from "./pickerDrawn";
type PickerModuleDeps = {
postMessage: (payload: RuntimeOutboundMessage) => void;
};
const PICKER_IGNORE_SELECTOR = [
"[data-hyperframes-ignore]",
"[data-hyperframes-picker-ignore]",
"[data-hf-ignore]",
"[data-no-inspect]",
"[data-no-pick]",
"[data-hyper-shader-loading]",
].join(",");
const PICKER_BLOCK_SELECTOR = [
"[data-hyperframes-picker-block]",
"[data-hyper-shader-loading]",
].join(",");
// A composition root's pointer-events:none (rescoped onto its inner root at mount) is about playback, not
// editing, yet it inherits into the whole section. Inner roots and the page's outermost composition root
// take pointer events while the picker looks. A host keeps its own none: that is the parent author making
// an overlay click-through.
const PICKABLE_ROOTS = "[data-hf-inner-root],[data-composition-id]:not([data-composition-id] *)";
const PICKABLE_ROOTS_RULE = `${PICKABLE_ROOTS}{pointer-events:auto!important}`;
// A layered !important outranks every normal rule and every unlayered !important, whatever its specificity
// (a mounted section's rescoped `#root { pointer-events: none !important }`). Ceiling: an author !important
// inside the author's own layer, or inline, still wins; an adopted sheet's layer always orders last.
const PICKABLE_ROOTS_LAYERED = `@layer hf-picker{${PICKABLE_ROOTS_RULE}}`;
export type PickerModule = {
enablePickMode: () => void;
disablePickMode: () => void;
installPickerApi: () => void;
};
export function createPickerModule(deps: PickerModuleDeps): PickerModule {
let pickModeActive = false;
let pickModeHighlightEl: Element | null = null;
let pickModeStyleEl: HTMLStyleElement | null = null;
let pickLastHoveredInfo: RuntimePickerElementInfo | null = null;
let pickLastSelectedInfo: RuntimePickerElementInfo | null = null;
let pickableRootsSheetCache: CSSStyleSheet | null | undefined;
// Roots that were pointer-events:none before the override: their content is pickable, never they.
let passThroughRoots: ReadonlySet<Element> = new Set();
function emitPickerRuntimeEvent(eventName: string, detail: RuntimeJson): void {
try {
window.dispatchEvent(new CustomEvent(eventName, { detail }));
} catch (err) {
// no-op in unsupported contexts
swallow("runtime.picker.site1", err);
}
}
function setLastHoveredInfo(info: RuntimePickerElementInfo | null): void {
pickLastHoveredInfo = info;
emitPickerRuntimeEvent("hyperframe:picker:hovered", {
elementInfo: pickLastHoveredInfo,
isPickMode: pickModeActive,
timestamp: Date.now(),
});
}
function setLastSelectedInfo(info: RuntimePickerElementInfo | null): void {
pickLastSelectedInfo = info;
emitPickerRuntimeEvent("hyperframe:picker:selected", {
elementInfo: pickLastSelectedInfo,
isPickMode: pickModeActive,
timestamp: Date.now(),
});
}
// An adopted sheet is not a DOM node: no MutationObserver hears it (the runtime's timing observer would
// wake a paused transport on every hover) and a saved documentElement.outerHTML never contains it.
function withPickableCompositionRoots<T>(run: () => T): T {
passThroughRoots = new Set(
Array.from(document.querySelectorAll(PICKABLE_ROOTS)).filter(
(root) => getComputedStyle(root).pointerEvents === "none",
),
);
// Nothing to override, so no restyle: adopting the sheet restyles the whole document twice per hover.
if (passThroughRoots.size === 0) return run();
const sheet = pickableRootsSheet();
const release = sheet ? adoptSheet(sheet) : appendPickableRootsStyle();
try {
return run();
} finally {
release();
passThroughRoots = new Set();
}
}
function pickableRootsSheet(): CSSStyleSheet | null {
if (pickableRootsSheetCache !== undefined) return pickableRootsSheetCache;
pickableRootsSheetCache = null;
if (!Array.isArray(document.adoptedStyleSheets) || typeof CSSStyleSheet === "undefined")
return null;
try {
const sheet = new CSSStyleSheet();
sheet.replaceSync(PICKABLE_ROOTS_LAYERED);
pickableRootsSheetCache = sheet;
} catch (err) {
swallow("runtime.picker.site2", err);
}
return pickableRootsSheetCache;
}
function adoptSheet(sheet: CSSStyleSheet): () => void {
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
return () => {
document.adoptedStyleSheets = document.adoptedStyleSheets.filter((s) => s !== sheet);
};
}
// No adoptedStyleSheets (older engines, and jsdom, whose layered !important order is reversed, so this
// rule stays unlayered): a style element for the hit test only. Adding it is a DOM mutation, so there a
// hover can wake the runtime's timing observer.
function appendPickableRootsStyle(): () => void {
const style = document.createElement("style");
style.textContent = PICKABLE_ROOTS_RULE;
(document.head ?? document.documentElement).appendChild(style);
return () => style.remove();
}
function isDecorativeVeil(el: HTMLElement, win: Window): boolean {
const style = win.getComputedStyle(el);
const opacity = Number.parseFloat(style.opacity || "1");
const faint = Number.isFinite(opacity) && opacity < 0.2;
if (faint && !(el.textContent ?? "").trim()) {
const image = style.backgroundImage;
if (image && image !== "none") return true;
}
return faintFilterPaint(el, win);
}
function isFilterDefinition(el: Element): boolean {
if (el.namespaceURI !== "http://www.w3.org/2000/svg") return false;
const tag = el.tagName.toLowerCase();
return tag === "filter" || tag === "defs" || tag.startsWith("fe");
}
function isFilterRect(el: Element): boolean {
if (el.namespaceURI !== "http://www.w3.org/2000/svg") return false;
if (el.tagName.toLowerCase() !== "rect") return false;
const attr = (el.getAttribute("filter") ?? "").trim();
if (attr && attr !== "none") return true;
const painted = el.ownerDocument.defaultView?.getComputedStyle(el).filter ?? "none";
return painted.startsWith("url(");
}
function isOnlyFilterPaint(el: Element): boolean {
if ((el.textContent ?? "").trim()) return false;
if (isFilterDefinition(el) || isFilterRect(el)) return true;
const children = [...el.children];
return children.length > 0 && children.every((child) => isOnlyFilterPaint(child));
}
function isFaint(el: Element, win: Window): boolean {
const opacity = Number.parseFloat(win.getComputedStyle(el).opacity || "1");
return Number.isFinite(opacity) && opacity < 0.2;
}
function faintFilterPaint(el: Element, win: Window): boolean {
if (!isOnlyFilterPaint(el)) return false;
for (
let current: Element | null = el;
current && current !== document.body && current !== document.documentElement;
current = current.parentElement
) {
if (isFaint(current, win) && isOnlyFilterPaint(current)) return true;
}
return false;
}
function isEffectivelyHidden(el: HTMLElement): boolean {
const win = el.ownerDocument.defaultView;
if (!win) return false;
let current: HTMLElement | null = el;
if (win.getComputedStyle(el).visibility === "hidden") return true;
if (isDecorativeVeil(el, win)) return true;
while (current && current !== document.body && current !== document.documentElement) {
const computed = win.getComputedStyle(current);
if (computed.display === "none") return true;
if (computed.pointerEvents === "none") return true;
const opacity = Number.parseFloat(computed.opacity);
if (
Number.isFinite(opacity) &&
opacity <= 0.01 &&
!current.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)
)
return true;
current = current.parentElement;
}
return false;
}
function isPickableElement(el: Element | null): el is Element {
if (!el || el === document.body || el === document.documentElement) return false;
const tag = el.tagName.toLowerCase();
if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") return false;
if (passThroughRoots.has(el)) return false;
if (el.closest(PICKER_IGNORE_SELECTOR)) return false;
if (isEffectivelyHidden(el as HTMLElement)) return false;
return true;
}
function blocksPickerAtPoint(el: Element | null): boolean {
return Boolean(el?.closest(PICKER_BLOCK_SELECTOR));
}
// The mount strips an inner root's id and composition id, so its own tag would match any div.
function innerRootSelector(el: Element): string | null {
const hostId = el.parentElement?.getAttribute("data-composition-id");
if (!el.hasAttribute("data-hf-inner-root") || !hostId) return null;
return `[data-composition-id="${CSS.escape(hostId)}"] > [data-hf-inner-root]`;
}
function buildElementSelector(el: Element): string {
const innerRoot = innerRootSelector(el);
if (innerRoot) return innerRoot;
const htmlEl = el as HTMLElement;
// Escape the ID so digit-leading or otherwise CSS-illegal ids (e.g. `#0`,
// `#1`) produce valid selectors — `document.querySelector("#0")` throws
// SyntaxError per the CSS spec. Sibling branches below already escape.
if (htmlEl.id) return `#${CSS.escape(htmlEl.id)}`;
const compositionId = el.getAttribute("data-composition-id");
if (compositionId) return `[data-composition-id="${CSS.escape(compositionId)}"]`;
const compositionSrc = el.getAttribute("data-composition-src");
if (compositionSrc) return `[data-composition-src="${CSS.escape(compositionSrc)}"]`;
const track = el.getAttribute("data-track-index");
if (track) return `[data-track-index="${CSS.escape(track)}"]`;
const tag = el.tagName.toLowerCase();
const parent = el.parentElement;
if (!parent) return tag;
const siblings = parent.querySelectorAll(`:scope > ${tag}`);
if (siblings.length === 1) return tag;
for (let i = 0; i < siblings.length; i += 1) {
if (siblings[i] === el) return `${tag}:nth-of-type(${i + 1})`;
}
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[] = [];
if (document.elementsFromPoint) {
raw = document.elementsFromPoint(clientX, clientY);
} else if (document.elementFromPoint) {
const single = document.elementFromPoint(clientX, clientY);
raw = single ? [single] : [];
}
if (blocksPickerAtPoint(raw[0] ?? null)) return [];
const dedupe: Record<string, true> = {};
const candidates: Element[] = [];
const drawn: Element[] = [];
const drawsHere = createDrawnProbe(document, clientX, clientY);
for (const [i, node] of raw.entries()) {
if (!isPickableElement(node)) continue;
const key = `${node.tagName}::${(node as HTMLElement).id || ""}::${i}`;
if (dedupe[key]) continue;
dedupe[key] = true;
candidates.push(node);
if (drawn.some((inner) => node.contains(inner)) || drawsHere(node)) {
drawn.push(node);
if (drawn.length >= maxCandidates) break;
}
}
return drawn.length > 0 ? drawn : candidates.slice(0, maxCandidates);
}
function extractElementInfo(el: Element): RuntimePickerElementInfo {
const rect = el.getBoundingClientRect();
const dataAttributes: Record<string, string> = {};
for (const attr of Array.from(el.attributes)) {
if (attr.name.startsWith("data-")) {
dataAttributes[attr.name] = attr.value;
}
}
const htmlEl = el as HTMLElement;
return {
id: htmlEl.id || null,
tagName: el.tagName.toLowerCase(),
selector: buildElementSelector(el),
label: buildElementLabel(el),
boundingBox: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
textContent: el.textContent ? el.textContent.trim().slice(0, 200) : null,
src: el.getAttribute("src") || el.getAttribute("data-composition-src") || null,
dataAttributes,
};
}
function getPickInfosFromPoint(
clientX: number,
clientY: number,
limit?: number,
): RuntimePickerElementInfo[] {
return withPickableCompositionRoots(() =>
getPickCandidatesFromPoint(clientX, clientY, limit),
).map(extractElementInfo);
}
function onPickMouseMove(event: MouseEvent): void {
if (!pickModeActive) return;
const target = withPickableCompositionRoots(() => {
const hit =
getPickCandidatesFromPoint(event.clientX, event.clientY, 1)[0] ??
(isElementNode(event.target) ? event.target : null);
return isPickableElement(hit) ? hit : null;
});
if (!target) return;
if (pickModeHighlightEl === target) return;
if (pickModeHighlightEl) {
pickModeHighlightEl.classList.remove("__hf-pick-highlight");
}
pickModeHighlightEl = target;
target.classList.add("__hf-pick-highlight");
const info = extractElementInfo(target);
setLastHoveredInfo(info);
deps.postMessage({ source: "hf-preview", type: "element-hovered", elementInfo: info });
}
function onPickClick(event: MouseEvent): void {
if (!pickModeActive) return;
event.preventDefault();
event.stopPropagation();
event.stopImmediatePropagation();
const infos = getPickInfosFromPoint(event.clientX, event.clientY, 8);
if (infos.length === 0) return;
setLastHoveredInfo(infos[0] ?? null);
deps.postMessage({
source: "hf-preview",
type: "element-pick-candidates",
candidates: infos,
selectedIndex: 0,
point: { x: event.clientX, y: event.clientY },
});
}
function onPickKeyDown(event: KeyboardEvent): void {
if (event.key !== "Escape") return;
disablePickMode();
deps.postMessage({ source: "hf-preview", type: "pick-mode-cancelled" });
}
function enablePickMode(): void {
if (pickModeActive) return;
pickModeActive = true;
pickModeStyleEl = document.createElement("style");
pickModeStyleEl.textContent = [
".__hf-pick-highlight { outline: 2px solid #4f8cf7 !important; outline-offset: 2px; cursor: crosshair !important; }",
".__hf-pick-active * { cursor: crosshair !important; }",
].join("\n");
document.head.appendChild(pickModeStyleEl);
document.body.classList.add("__hf-pick-active");
document.addEventListener("mousemove", onPickMouseMove, true);
document.addEventListener("click", onPickClick, true);
document.addEventListener("keydown", onPickKeyDown, true);
emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: true, timestamp: Date.now() });
}
function disablePickMode(): void {
if (!pickModeActive) return;
pickModeActive = false;
if (pickModeHighlightEl) {
pickModeHighlightEl.classList.remove("__hf-pick-highlight");
pickModeHighlightEl = null;
}
if (pickModeStyleEl) {
pickModeStyleEl.remove();
pickModeStyleEl = null;
}
document.body.classList.remove("__hf-pick-active");
document.removeEventListener("mousemove", onPickMouseMove, true);
document.removeEventListener("click", onPickClick, true);
document.removeEventListener("keydown", onPickKeyDown, true);
emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: false, timestamp: Date.now() });
}
function installPickerApi(): void {
window.__HF_PICKER_API = {
enable: enablePickMode,
disable: disablePickMode,
isActive: () => pickModeActive,
getHovered: () => pickLastHoveredInfo,
getSelected: () => pickLastSelectedInfo,
getCandidatesAtPoint: (clientX, clientY, limit) =>
Number.isFinite(clientX) && Number.isFinite(clientY)
? getPickInfosFromPoint(clientX, clientY, limit)
: [],
pickAtPoint: (clientX, clientY, index) => {
if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return null;
const infos = getPickInfosFromPoint(clientX, clientY, 8);
if (!infos.length) return null;
const safeIndex = Math.max(0, Math.min(infos.length - 1, Number(index ?? 0)));
const selected = infos[safeIndex] ?? null;
if (!selected) return null;
setLastSelectedInfo(selected);
deps.postMessage({ source: "hf-preview", type: "element-picked", elementInfo: selected });
disablePickMode();
return selected;
},
describe: (element) => (isElementNode(element) ? extractElementInfo(element) : null),
pickManyAtPoint: (clientX, clientY, indexes) => {
if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return [];
const infos = getPickInfosFromPoint(clientX, clientY, 8);
if (!infos.length) return [];
const selected: RuntimePickerElementInfo[] = [];
const rawIndexes = Array.isArray(indexes) ? indexes : [0];
for (const rawIndex of rawIndexes) {
const idx = Math.max(0, Math.min(infos.length - 1, Math.floor(Number(rawIndex))));
const info = infos[idx];
if (!info) continue;
const duplicate = selected.some(
(item) => item.selector === info.selector && item.tagName === info.tagName,
);
if (!duplicate) selected.push(info);
}
if (!selected.length) return [];
setLastSelectedInfo(selected[0] ?? null);
deps.postMessage({
source: "hf-preview",
type: "element-picked-many",
elementInfos: selected,
});
disablePickMode();
return selected;
},
};
emitPickerRuntimeEvent("hyperframe:picker:api-ready", { hasApi: true, timestamp: Date.now() });
}
return { enablePickMode, disablePickMode, installPickerApi };
}