diff --git a/docs/packages/studio.mdx b/docs/packages/studio.mdx
index 3a93ae113f..77ba6b2ac2 100644
--- a/docs/packages/studio.mdx
+++ b/docs/packages/studio.mdx
@@ -87,6 +87,11 @@ Peer dependencies are React 19, React DOM 19, and Zustand 4 or 5.
The package also exports `CompositionLevel`, `TimelineElement`, `PickedElement`,
and `PatchOperation`.
+`useElementPicker` remembers the current selection while inspection is active.
+Press Escape in either Studio or the preview to cancel and restore that selection. The
+hovered target is identified beside the preview as `tag#id`, `tag.class`, or the
+tag name alone.
+
## How Studio stays connected to a project
1. Studio loads the composition in an iframe with the HyperFrames runtime.
diff --git a/packages/core/src/inline-scripts/pickerApi.ts b/packages/core/src/inline-scripts/pickerApi.ts
index fbe0dc72bf..083bbe1f10 100644
--- a/packages/core/src/inline-scripts/pickerApi.ts
+++ b/packages/core/src/inline-scripts/pickerApi.ts
@@ -7,6 +7,7 @@ export type HyperframePickerBoundingBox = {
export type HyperframePickerElementInfo = {
id: string | null;
+ className?: string | null;
tagName: string;
selector: string;
label: string;
diff --git a/packages/core/src/runtime/picker.test.ts b/packages/core/src/runtime/picker.test.ts
index b354508b3a..cf27cbecb0 100644
--- a/packages/core/src/runtime/picker.test.ts
+++ b/packages/core/src/runtime/picker.test.ts
@@ -155,6 +155,16 @@ describe("createPickerModule", () => {
expect(candidatesUnder(() => [long], "label")).toEqual([`${"x".repeat(54)}😀…`]);
});
+ it("includes the element classes needed by host hover identifiers", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ const card = document.createElement("div");
+ card.className = "title featured";
+ document.body.appendChild(card);
+
+ expect(candidatesUnder(() => [card], "className")).toEqual(["title featured"]);
+ });
+
it("getCandidatesAtPoint returns empty for invalid coords", () => {
const picker = createPickerModule({ postMessage: createMockPostMessage() });
picker.installPickerApi();
@@ -466,6 +476,34 @@ describe("createPickerModule", () => {
restore();
}
});
+
+ it("refreshes hovered geometry while the preview scrolls and stops after disable", () => {
+ const postMessage = createMockPostMessage();
+ const picker = createPickerModule({ postMessage });
+ document.body.innerHTML = `
Hi
`;
+ let top = 10;
+ at("title").getBoundingClientRect = () => new DOMRect(20, top, 100, 40);
+ const restore = emulateHitTest(() => [at("title")]);
+ try {
+ picker.enablePickMode();
+ move();
+ top = 30;
+ document.dispatchEvent(new Event("scroll"));
+ const hovered = () =>
+ postMessage.mock.calls
+ .map(([message]) => message)
+ .filter((message) => message.type === "element-hovered");
+ expect(hovered().at(-1)?.elementInfo.boundingBox.y).toBe(30);
+
+ picker.disablePickMode();
+ const countAfterDisable = hovered().length;
+ document.dispatchEvent(new Event("scroll"));
+ expect(hovered()).toHaveLength(countAfterDisable);
+ } finally {
+ picker.disablePickMode();
+ restore();
+ }
+ });
});
describe("picks what is drawn under the pointer", () => {
diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts
index 2d2d942e87..584eb421b5 100644
--- a/packages/core/src/runtime/picker.ts
+++ b/packages/core/src/runtime/picker.ts
@@ -303,6 +303,7 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
const htmlEl = el as HTMLElement;
return {
id: htmlEl.id || null,
+ className: el.getAttribute("class") || null,
tagName: el.tagName.toLowerCase(),
selector: buildElementSelector(el),
label: buildElementLabel(el),
@@ -343,6 +344,13 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
deps.postMessage({ source: "hf-preview", type: "element-hovered", elementInfo: info });
}
+ function onPickViewportChange(): void {
+ if (!pickModeActive || !pickModeHighlightEl?.isConnected) return;
+ const info = extractElementInfo(pickModeHighlightEl);
+ setLastHoveredInfo(info);
+ deps.postMessage({ source: "hf-preview", type: "element-hovered", elementInfo: info });
+ }
+
function onPickClick(event: MouseEvent): void {
if (!pickModeActive) return;
event.preventDefault();
@@ -379,6 +387,8 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
document.addEventListener("mousemove", onPickMouseMove, true);
document.addEventListener("click", onPickClick, true);
document.addEventListener("keydown", onPickKeyDown, true);
+ document.addEventListener("scroll", onPickViewportChange, true);
+ window.addEventListener("resize", onPickViewportChange);
emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: true, timestamp: Date.now() });
}
@@ -397,6 +407,8 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
document.removeEventListener("mousemove", onPickMouseMove, true);
document.removeEventListener("click", onPickClick, true);
document.removeEventListener("keydown", onPickKeyDown, true);
+ document.removeEventListener("scroll", onPickViewportChange, true);
+ window.removeEventListener("resize", onPickViewportChange);
emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: false, timestamp: Date.now() });
}
diff --git a/packages/studio/src/hooks/elementPickerHoverLabel.browser.test.ts b/packages/studio/src/hooks/elementPickerHoverLabel.browser.test.ts
new file mode 100644
index 0000000000..0516480510
--- /dev/null
+++ b/packages/studio/src/hooks/elementPickerHoverLabel.browser.test.ts
@@ -0,0 +1,85 @@
+// @vitest-environment happy-dom
+import { build } from "esbuild";
+import { join } from "node:path";
+import { afterEach, expect, it, vi } from "vitest";
+import { closeTestChrome, launchTestChrome } from "../../tests/chromeTestUtils";
+
+vi.setConfig({ testTimeout: 60_000 });
+
+let browser: Awaited> | undefined;
+
+afterEach(async () => {
+ await closeTestChrome(browser);
+ browser = undefined;
+});
+
+it("keeps the hover label readable inside a transformed preview without taking pointer input", async () => {
+ const bundle = await build({
+ entryPoints: [join(import.meta.dirname, "elementPickerHoverLabel.ts")],
+ bundle: true,
+ format: "iife",
+ globalName: "PickerHoverLabel",
+ platform: "browser",
+ write: false,
+ });
+ browser = await launchTestChrome();
+ const page = await browser.newPage();
+ await page.setViewport({ width: 900, height: 600 });
+ await page.setContent(``);
+ await page.addScriptTag({ content: bundle.outputFiles[0]?.text });
+
+ const result = await page.evaluate(() => {
+ const preview = document.querySelector("#preview");
+ if (!preview) throw new Error("preview iframe missing");
+ const api = (
+ window as typeof window & {
+ PickerHoverLabel: {
+ createElementPickerHoverLabel(): {
+ show(
+ info: {
+ id: string;
+ tagName: string;
+ boundingBox: { x: number; y: number; width: number; height: number };
+ },
+ iframe: HTMLIFrameElement,
+ ): void;
+ };
+ };
+ }
+ ).PickerHoverLabel.createElementPickerHoverLabel();
+ api.show(
+ {
+ id: "hero-title",
+ tagName: "h1",
+ boundingBox: { x: 270, y: 24, width: 40, height: 30 },
+ },
+ preview,
+ );
+ const label = document.querySelector("[data-hf-picker-hover-label]");
+ if (!label) throw new Error("hover label missing");
+ const labelRect = label.getBoundingClientRect();
+ const previewRect = preview.getBoundingClientRect();
+ return {
+ text: label.textContent,
+ pointerEvents: getComputedStyle(label).pointerEvents,
+ insidePreview: labelRect.left >= previewRect.left && labelRect.right <= previewRect.right,
+ insideViewport: labelRect.left >= 0 && labelRect.right <= innerWidth,
+ };
+ });
+
+ expect(result).toEqual({
+ text: "h1#hero-title",
+ pointerEvents: "none",
+ insidePreview: true,
+ insideViewport: true,
+ });
+});
diff --git a/packages/studio/src/hooks/elementPickerHoverLabel.test.ts b/packages/studio/src/hooks/elementPickerHoverLabel.test.ts
new file mode 100644
index 0000000000..aa3a2d93a3
--- /dev/null
+++ b/packages/studio/src/hooks/elementPickerHoverLabel.test.ts
@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ createElementPickerHoverLabel,
+ elementPickerLabelPosition,
+ formatElementPickerIdentifier,
+} from "./elementPickerHoverLabel";
+
+afterEach(() => {
+ document.body.innerHTML = "";
+});
+
+describe("formatElementPickerIdentifier", () => {
+ const box = { x: 0, y: 0, width: 10, height: 10 };
+
+ it.each([
+ [{ tagName: "H1", id: "hero-title", className: "headline", boundingBox: box }, "h1#hero-title"],
+ [{ tagName: "DIV", id: null, className: "title featured", boundingBox: box }, "div.title"],
+ [{ tagName: "SPAN", id: null, className: null, boundingBox: box }, "span"],
+ [
+ {
+ tagName: "P",
+ id: null,
+ className: "__hf-pick-highlight caption",
+ boundingBox: box,
+ },
+ "p.caption",
+ ],
+ ])("formats %j as %s", (info, expected) => {
+ expect(formatElementPickerIdentifier(info)).toBe(expected);
+ });
+
+ it("bounds long and unusual identifiers without interpreting markup", () => {
+ const identifier = formatElementPickerIdentifier({
+ tagName: "DIV",
+ id: `
${"x".repeat(100)}`,
+ className: null,
+ boundingBox: box,
+ });
+ expect(Array.from(identifier)).toHaveLength(72);
+ expect(identifier).toMatch(/^div#
/);
+ expect(identifier.endsWith("…")).toBe(true);
+ });
+});
+
+describe("elementPickerLabelPosition", () => {
+ it("maps iframe coordinates through zoom and flips inside the visible frame", () => {
+ expect(
+ elementPickerLabelPosition({
+ iframeRect: { left: 100, top: 50, right: 500, bottom: 250, width: 400, height: 200 },
+ iframeWidth: 200,
+ iframeHeight: 100,
+ elementBox: { x: 180, y: 90, width: 20, height: 10 },
+ labelWidth: 80,
+ labelHeight: 20,
+ viewportWidth: 800,
+ viewportHeight: 600,
+ }),
+ ).toEqual({ left: 374, top: 230 });
+ });
+
+ it("clamps a partly offscreen preview to the usable viewport", () => {
+ expect(
+ elementPickerLabelPosition({
+ iframeRect: { left: -50, top: -20, right: 150, bottom: 80, width: 200, height: 100 },
+ iframeWidth: 200,
+ iframeHeight: 100,
+ elementBox: { x: 0, y: 0, width: 5, height: 5 },
+ labelWidth: 80,
+ labelHeight: 20,
+ viewportWidth: 100,
+ viewportHeight: 60,
+ }),
+ ).toEqual({ left: 0, top: 0 });
+ });
+});
+
+describe("createElementPickerHoverLabel", () => {
+ it("renders plain text without intercepting pointer input and removes itself", () => {
+ const iframe = document.body.appendChild(document.createElement("iframe"));
+ Object.defineProperties(iframe, {
+ clientWidth: { configurable: true, value: 200 },
+ clientHeight: { configurable: true, value: 100 },
+ });
+ iframe.getBoundingClientRect = () => new DOMRect(20, 30, 400, 200);
+ const hoverLabel = createElementPickerHoverLabel();
+ hoverLabel.show(
+ {
+ tagName: "div",
+ id: "not markup",
+ className: null,
+ boundingBox: { x: 10, y: 20, width: 30, height: 40 },
+ },
+ iframe,
+ );
+
+ const label = document.querySelector("[data-hf-picker-hover-label]");
+ expect(label?.textContent).toBe("div#not markup");
+ expect(label?.querySelector("b")).toBeNull();
+ expect(label?.style.pointerEvents).toBe("none");
+ expect(label?.style.position).toBe("fixed");
+
+ hoverLabel.dispose();
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
+ });
+});
diff --git a/packages/studio/src/hooks/elementPickerHoverLabel.ts b/packages/studio/src/hooks/elementPickerHoverLabel.ts
new file mode 100644
index 0000000000..a755478c79
--- /dev/null
+++ b/packages/studio/src/hooks/elementPickerHoverLabel.ts
@@ -0,0 +1,173 @@
+import type { HyperframePickerBoundingBox } from "@hyperframes/core";
+
+const LABEL_GAP_PX = 6;
+const LABEL_MAX_CHARS = 72;
+
+export interface ElementPickerHoverInfo {
+ id: string | null;
+ className?: string | null;
+ tagName: string;
+ boundingBox: HyperframePickerBoundingBox;
+}
+
+export function formatElementPickerIdentifier(info: ElementPickerHoverInfo): string {
+ const tag = info.tagName.trim().toLowerCase() || "element";
+ const id = info.id?.trim();
+ const firstClass = info.className
+ ?.split(/\s+/)
+ .find((name) => name.length > 0 && !name.startsWith("__hf-"));
+ const identifier = id ? `${tag}#${id}` : firstClass ? `${tag}.${firstClass}` : tag;
+ const characters = Array.from(identifier);
+ return characters.length > LABEL_MAX_CHARS
+ ? `${characters.slice(0, LABEL_MAX_CHARS - 1).join("")}…`
+ : identifier;
+}
+
+interface LabelPositionInput {
+ iframeRect: Pick;
+ iframeWidth: number;
+ iframeHeight: number;
+ elementBox: HyperframePickerBoundingBox;
+ labelWidth: number;
+ labelHeight: number;
+ viewportWidth: number;
+ viewportHeight: number;
+}
+
+export function elementPickerLabelPosition(input: LabelPositionInput): {
+ left: number;
+ top: number;
+} {
+ const scaleX = input.iframeWidth > 0 ? input.iframeRect.width / input.iframeWidth : 1;
+ const scaleY = input.iframeHeight > 0 ? input.iframeRect.height / input.iframeHeight : 1;
+ const elementLeft = input.iframeRect.left + input.elementBox.x * scaleX;
+ const elementRight = elementLeft + input.elementBox.width * scaleX;
+ const elementTop = input.iframeRect.top + input.elementBox.y * scaleY;
+ const minLeft = Math.max(0, input.iframeRect.left);
+ const maxRight = Math.min(input.viewportWidth, input.iframeRect.right);
+ const minTop = Math.max(0, input.iframeRect.top);
+ const maxBottom = Math.min(input.viewportHeight, input.iframeRect.bottom);
+ const maxLeft = Math.max(minLeft, maxRight - input.labelWidth);
+ const maxTop = Math.max(minTop, maxBottom - input.labelHeight);
+ const besideRight = elementRight + LABEL_GAP_PX;
+ const besideLeft = elementLeft - input.labelWidth - LABEL_GAP_PX;
+ const preferredLeft = besideRight + input.labelWidth <= maxRight ? besideRight : besideLeft;
+
+ return {
+ left: Math.min(maxLeft, Math.max(minLeft, preferredLeft)),
+ top: Math.min(maxTop, Math.max(minTop, elementTop)),
+ };
+}
+
+export interface ElementPickerHoverLabel {
+ show: (info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => void;
+ clear: () => void;
+ dispose: () => void;
+}
+
+function firstPositive(values: number[]): number {
+ return values.find((value) => value > 0) ?? 0;
+}
+
+function iframeLayoutSize(
+ iframe: HTMLIFrameElement,
+ rect: DOMRect,
+): {
+ width: number;
+ height: number;
+} {
+ return {
+ width: firstPositive([iframe.clientWidth, iframe.offsetWidth, rect.width]),
+ height: firstPositive([iframe.clientHeight, iframe.offsetHeight, rect.height]),
+ };
+}
+
+function viewportSize(doc: Document): { width: number; height: number } {
+ const view = doc.defaultView;
+ return view
+ ? { width: view.innerWidth, height: view.innerHeight }
+ : { width: doc.documentElement.clientWidth, height: doc.documentElement.clientHeight };
+}
+
+export function createElementPickerHoverLabel(doc: Document = document): ElementPickerHoverLabel {
+ const label = doc.createElement("div");
+ label.dataset.hfPickerHoverLabel = "";
+ label.ariaHidden = "true";
+ Object.assign(label.style, {
+ position: "fixed",
+ zIndex: "100",
+ pointerEvents: "none",
+ maxWidth: "220px",
+ overflow: "hidden",
+ textOverflow: "ellipsis",
+ whiteSpace: "nowrap",
+ border: "1px solid color-mix(in oklab, var(--color-studio-accent) 55%, transparent)",
+ borderRadius: "4px",
+ background: "var(--color-studio-bg)",
+ color: "var(--color-studio-text)",
+ boxShadow: "var(--shadow-popover)",
+ padding: "2px 6px",
+ fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
+ fontSize: "10px",
+ lineHeight: "16px",
+ });
+
+ let current: { info: ElementPickerHoverInfo; iframe: HTMLIFrameElement } | null = null;
+ let animationFrame: number | null = null;
+
+ const draw = () => {
+ if (!current || !current.iframe.isConnected) {
+ clear();
+ return;
+ }
+ if (!label.isConnected) doc.body.appendChild(label);
+ label.textContent = formatElementPickerIdentifier(current.info);
+ const iframeRect = current.iframe.getBoundingClientRect();
+ const labelRect = label.getBoundingClientRect();
+ const iframeSize = iframeLayoutSize(current.iframe, iframeRect);
+ const viewport = viewportSize(doc);
+ const position = elementPickerLabelPosition({
+ iframeRect,
+ iframeWidth: iframeSize.width,
+ iframeHeight: iframeSize.height,
+ elementBox: current.info.boundingBox,
+ labelWidth: labelRect.width,
+ labelHeight: labelRect.height,
+ viewportWidth: viewport.width,
+ viewportHeight: viewport.height,
+ });
+ label.style.left = `${position.left}px`;
+ label.style.top = `${position.top}px`;
+ };
+
+ const tick = () => {
+ animationFrame = null;
+ draw();
+ if (current && doc.defaultView) animationFrame = doc.defaultView.requestAnimationFrame(tick);
+ };
+
+ const startTracking = () => {
+ if (animationFrame === null && doc.defaultView) {
+ animationFrame = doc.defaultView.requestAnimationFrame(tick);
+ }
+ };
+
+ function clear(): void {
+ current = null;
+ if (animationFrame !== null && doc.defaultView) {
+ doc.defaultView.cancelAnimationFrame(animationFrame);
+ animationFrame = null;
+ }
+ label.remove();
+ }
+
+ return {
+ show(info, iframe) {
+ current = { info, iframe };
+ draw();
+ startTracking();
+ },
+ clear,
+ dispose: clear,
+ };
+}
diff --git a/packages/studio/src/hooks/useElementPicker.test.ts b/packages/studio/src/hooks/useElementPicker.test.ts
index 98ae87dda7..8ccc2a4da5 100644
--- a/packages/studio/src/hooks/useElementPicker.test.ts
+++ b/packages/studio/src/hooks/useElementPicker.test.ts
@@ -3,7 +3,7 @@ import React, { act, useState } from "react";
import { createRoot, type Root } from "react-dom/client";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
import { useElementPicker } from "./useElementPicker";
// As the host leaves it on disk: hf-ids pinned, no element ids.
@@ -17,6 +17,7 @@ afterEach(() => {
act(() => root?.unmount());
root = null;
document.body.innerHTML = "";
+ vi.restoreAllMocks();
});
// The runtime's element-picked message, posted by `from`.
@@ -35,6 +36,33 @@ const picked = (from: Window | null, selector: string) =>
);
});
+const pickerMessage = (from: Window | null, data: Record) =>
+ act(() => {
+ window.dispatchEvent(
+ new MessageEvent("message", {
+ source: from,
+ data: {
+ source: "hf-preview",
+ ...data,
+ ...runtimeProtocolMetadata(30),
+ },
+ }),
+ );
+ });
+
+const hoverInfo = (overrides: Record = {}) => ({
+ id: null,
+ className: "title",
+ tagName: "div",
+ selector: "div.title",
+ label: "Title",
+ boundingBox: { x: 20, y: 30, width: 100, height: 40 },
+ textContent: "Title",
+ src: null,
+ dataAttributes: {},
+ ...overrides,
+});
+
// The preview page: the saved markup plus what the runtime adds to it.
function mountPreview(mounted = ""): HTMLIFrameElement {
const iframe = document.createElement("iframe");
@@ -80,12 +108,150 @@ function mountPicker(
picked(iframe.contentWindow, selector);
const picker = () => api as ReturnType;
return {
+ iframe,
picker,
synced,
setHostFiles: (next: Record) => act(() => setHostFiles(next)),
};
}
+describe("pick mode cancellation and hover feedback", () => {
+ it("cancels pick mode when Escape is pressed with Studio focus", () => {
+ const { picker } = mountPicker({ "index.html": SAVED });
+ act(() => picker().enablePick());
+
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
+
+ expect(picker().isPickMode).toBe(false);
+ });
+
+ it("shows the hovered element identifier beside the preview", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ act(() => picker().enablePick());
+
+ pickerMessage(iframe.contentWindow, {
+ type: "element-hovered",
+ elementInfo: hoverInfo(),
+ });
+
+ expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe("div.title");
+ });
+
+ it("restores the element selected before pick mode began when cancelled", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ expect(picker().pickedElement?.selector).toBe("h1");
+ act(() => picker().enablePick());
+ pickerMessage(iframe.contentWindow, {
+ type: "element-pick-candidates",
+ candidates: [{ selector: "div.candidate", tagName: "div" }],
+ selectedIndex: 0,
+ point: { x: 1, y: 1 },
+ });
+ expect(picker().pickedElement?.selector).toBe("div.candidate");
+
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
+
+ expect(picker().pickedElement?.selector).toBe("h1");
+ });
+
+ it("restores the previous selection when Escape comes from the preview runtime", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ act(() => picker().enablePick());
+ pickerMessage(iframe.contentWindow, {
+ type: "element-pick-candidates",
+ candidates: [{ selector: "div.candidate", tagName: "div" }],
+ selectedIndex: 0,
+ point: { x: 1, y: 1 },
+ });
+
+ pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
+
+ expect(picker().isPickMode).toBe(false);
+ expect(picker().pickedElement?.selector).toBe("h1");
+ });
+
+ it("ignores Escape while inactive and where an editor owns it", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ const frameWindow = iframe.contentWindow;
+ if (!frameWindow) throw new Error("preview iframe has no content window");
+ const postMessage = vi.spyOn(frameWindow, "postMessage");
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
+ expect(postMessage).not.toHaveBeenCalled();
+
+ const editor = document.body.appendChild(document.createElement("textarea"));
+ act(() => picker().enablePick());
+ act(() => editor.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true })));
+
+ expect(picker().isPickMode).toBe(true);
+ });
+
+ it("survives repeated enable and cancellation cycles", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ for (let cycle = 0; cycle < 3; cycle += 1) {
+ act(() => picker().enablePick());
+ expect(picker().isPickMode).toBe(true);
+ pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
+ expect(picker().isPickMode).toBe(false);
+ expect(picker().pickedElement?.selector).toBe("h1");
+ }
+ });
+
+ it("removes its Studio key listener and disables the runtime on unmount", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ const frameWindow = iframe.contentWindow;
+ if (!frameWindow) throw new Error("preview iframe has no content window");
+ const removeEventListener = vi.spyOn(window, "removeEventListener");
+ const postMessage = vi.spyOn(frameWindow, "postMessage");
+ act(() => picker().enablePick());
+
+ act(() => root?.unmount());
+ root = null;
+
+ expect(removeEventListener.mock.calls.some(([type]) => type === "keydown")).toBe(true);
+ expect(
+ postMessage.mock.calls.some(
+ ([message]) =>
+ typeof message === "object" &&
+ message !== null &&
+ "action" in message &&
+ message.action === "disable-pick-mode",
+ ),
+ ).toBe(true);
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
+ });
+
+ it("commits a normal pick and clears hover state", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ act(() => picker().enablePick());
+ pickerMessage(iframe.contentWindow, {
+ type: "element-hovered",
+ elementInfo: hoverInfo(),
+ });
+
+ picked(iframe.contentWindow, "div.final");
+
+ expect(picker().isPickMode).toBe(false);
+ expect(picker().pickedElement?.selector).toBe("div.final");
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
+ });
+
+ it("clears the label after cancellation", () => {
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
+ act(() => picker().enablePick());
+ pickerMessage(iframe.contentWindow, {
+ type: "element-hovered",
+ elementInfo: hoverInfo({ id: "hero-title", tagName: "h1" }),
+ });
+ expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe(
+ "h1#hero-title",
+ );
+
+ pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
+
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
+ });
+});
+
describe("an edit to a picked element without an id", () => {
it("writes only that edit into the saved file", () => {
const { picker, synced } = mountPicker({ "index.html": SAVED });
@@ -185,8 +351,9 @@ describe("a pick across a reload that swaps the preview frame", () => {
return null;
}
root = createRoot(document.createElement("div"));
- act(() => root?.render(React.createElement(Harness)));
- return { live, ref, picker: () => api as ReturnType };
+ const rerender = () => act(() => root?.render(React.createElement(Harness)));
+ rerender();
+ return { live, ref, rerender, picker: () => api as ReturnType };
}
it("keeps a pick posted by the frame it was made in after a new frame took its place", () => {
@@ -212,6 +379,90 @@ describe("a pick across a reload that swaps the preview frame", () => {
expect(picker().pickedElement?.selector).toBe("h1");
});
+ it("drops hover messages from a primary iframe after it is replaced", () => {
+ const { live, ref, rerender, picker } = mountSwapping();
+ const liveWindow = live.contentWindow;
+ if (!liveWindow) throw new Error("preview iframe has no content window");
+ const oldPostMessage = vi.spyOn(liveWindow, "postMessage");
+ act(() => picker().enablePick());
+ pickerMessage(liveWindow, {
+ type: "element-hovered",
+ elementInfo: hoverInfo(),
+ });
+ expect(document.querySelector("[data-hf-picker-hover-label]")).not.toBeNull();
+
+ const replacement = mountPreview();
+ const replacementWindow = replacement.contentWindow;
+ if (!replacementWindow) throw new Error("replacement iframe has no content window");
+ const replacementPostMessage = vi.spyOn(replacementWindow, "postMessage");
+ ref.current = replacement;
+ rerender();
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
+ expect(
+ oldPostMessage.mock.calls.some(
+ ([message]) =>
+ typeof message === "object" &&
+ message !== null &&
+ "action" in message &&
+ message.action === "disable-pick-mode",
+ ),
+ ).toBe(true);
+ expect(
+ replacementPostMessage.mock.calls.some(
+ ([message]) =>
+ typeof message === "object" &&
+ message !== null &&
+ "action" in message &&
+ message.action === "enable-pick-mode",
+ ),
+ ).toBe(true);
+ pickerMessage(liveWindow, {
+ type: "element-hovered",
+ elementInfo: hoverInfo({ id: "stale" }),
+ });
+
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
+ });
+
+ it("moves active pick mode to a zoomed iframe without losing the original selection", () => {
+ const { live, picker } = mountSwapping();
+ picked(live.contentWindow, "h1");
+ const zoom = mountPreview();
+ const zoomWindow = zoom.contentWindow;
+ if (!zoomWindow) throw new Error("zoom iframe has no content window");
+ const zoomPostMessage = vi.spyOn(zoomWindow, "postMessage");
+ act(() => picker().enablePick());
+
+ act(() => picker().setActiveIframe(zoom));
+ pickerMessage(zoomWindow, {
+ type: "element-hovered",
+ elementInfo: hoverInfo({ id: "zoomed" }),
+ });
+ pickerMessage(zoomWindow, {
+ type: "element-pick-candidates",
+ candidates: [{ selector: "div.zoomed", tagName: "div" }],
+ selectedIndex: 0,
+ point: { x: 1, y: 1 },
+ });
+
+ expect(picker().activeIframeRef.current).toBe(zoom);
+ expect(
+ zoomPostMessage.mock.calls.some(
+ ([message]) =>
+ typeof message === "object" &&
+ message !== null &&
+ "action" in message &&
+ message.action === "enable-pick-mode",
+ ),
+ ).toBe(true);
+ expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe("div#zoomed");
+
+ act(() => picker().setActiveIframe(null));
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
+ expect(picker().pickedElement?.selector).toBe("h1");
+ expect(picker().activeIframeRef.current).toBe(live);
+ });
+
it("still ignores a frame it never showed", () => {
const { picker } = mountSwapping();
const stranger = mountPreview();
diff --git a/packages/studio/src/hooks/useElementPicker.ts b/packages/studio/src/hooks/useElementPicker.ts
index f4ccfaa557..ef55823dee 100644
--- a/packages/studio/src/hooks/useElementPicker.ts
+++ b/packages/studio/src/hooks/useElementPicker.ts
@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef } from "react";
+import { useState, useCallback, useEffect, useRef } from "react";
import { useMountEffect } from "./useMountEffect";
import {
resolveSourceFile,
@@ -13,6 +13,11 @@ import {
} from "../player/lib/runtimeProtocol";
import { compositionPathOfPreviewUrl } from "../player/components/CompositionThumbnail";
import { getSourceFileForElement } from "../components/editor/domEditingDom";
+import {
+ createElementPickerHoverLabel,
+ type ElementPickerHoverInfo,
+ type ElementPickerHoverLabel,
+} from "./elementPickerHoverLabel";
export interface PickedElement {
id: string | null;
@@ -51,54 +56,142 @@ interface PickerOptions {
onSyncFiles?: (files: Record) => void;
}
-/**
- * Hook for element picking via the HyperFrame runtime's picker API.
- * Communicates with the iframe via postMessage.
- */
-export function useElementPicker(
+interface UseElementPickerSessionReturn extends Omit<
+ UseElementPickerReturn,
+ "setStyle" | "setDataAttr" | "setTextContent"
+> {
+ setPickedElement: React.Dispatch>;
+ getActiveIframe: () => HTMLIFrameElement | null;
+}
+
+function usePickerHoverLabel(): {
+ clearHover: () => void;
+ disposeHover: () => void;
+ showHover: (info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => void;
+} {
+ const hoverLabelRef = useRef(null);
+ const clearHover = useCallback(() => hoverLabelRef.current?.clear(), []);
+ const disposeHover = useCallback(() => hoverLabelRef.current?.dispose(), []);
+ const showHover = useCallback((info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => {
+ hoverLabelRef.current ??= createElementPickerHoverLabel();
+ hoverLabelRef.current.show(info, iframe);
+ }, []);
+ return { clearHover, disposeHover, showHover };
+}
+
+function useActivePickerIframe(
iframeRef: React.RefObject,
- options?: PickerOptions,
-): UseElementPickerReturn {
+ isPickModeRef: React.RefObject,
+ clearHover: () => void,
+): {
+ activeIframeRef: React.RefObject;
+ getActiveIframe: () => HTMLIFrameElement | null;
+ setActiveIframe: (el: HTMLIFrameElement | null) => void;
+} {
+ const activeOverrideRef = useRef(null);
+ const activeIframeRef = useRef(null);
+ const lastRenderedActiveIframeRef = useRef(null);
+ const getActiveIframe = useCallback(
+ () => activeOverrideRef.current ?? iframeRef.current,
+ [iframeRef],
+ );
+ const setActiveIframe = useCallback(
+ (el: HTMLIFrameElement | null) => {
+ const previous = activeOverrideRef.current ?? iframeRef.current;
+ const next = el ?? iframeRef.current;
+ if (previous === next) return;
+ clearHover();
+ if (isPickModeRef.current) postPickerControl(previous, "disable-pick-mode");
+ activeOverrideRef.current = el;
+ activeIframeRef.current = next;
+ lastRenderedActiveIframeRef.current = next;
+ if (isPickModeRef.current) postPickerControl(next, "enable-pick-mode");
+ },
+ [clearHover, iframeRef, isPickModeRef],
+ );
+ const renderedActiveIframe = getActiveIframe();
+ useEffect(() => {
+ const previous = lastRenderedActiveIframeRef.current;
+ if (previous !== renderedActiveIframe) {
+ clearHover();
+ if (isPickModeRef.current) {
+ postPickerControl(previous, "disable-pick-mode");
+ postPickerControl(renderedActiveIframe, "enable-pick-mode");
+ }
+ }
+ lastRenderedActiveIframeRef.current = renderedActiveIframe;
+ }, [clearHover, isPickModeRef, renderedActiveIframe]);
+ activeIframeRef.current = getActiveIframe();
+ return { activeIframeRef, getActiveIframe, setActiveIframe };
+}
+
+function useElementPickerSession(
+ iframeRef: React.RefObject,
+): UseElementPickerSessionReturn {
const [isPickMode, setIsPickMode] = useState(false);
const [pickedElement, setPickedElement] = useState(null);
-
- // Secondary/override iframe ref — set when a zoomed frame is active.
- // When set, all postMessage sends and DOM reads go to this ref instead.
- const activeOverrideRef = useRef(null);
-
- const getActiveIframe = useCallback((): HTMLIFrameElement | null => {
- return activeOverrideRef.current ?? iframeRef.current;
- }, [iframeRef]);
-
- // Exposed so the host page can wire the focused view's iframe into the picker
- const setActiveIframe = useCallback((el: HTMLIFrameElement | null) => {
- activeOverrideRef.current = el;
- }, []);
+ const isPickModeRef = useRef(false);
+ const pickedElementRef = useRef(null);
+ pickedElementRef.current = pickedElement;
+ const pickStartSelectionRef = useRef(undefined);
+ const { clearHover, disposeHover, showHover } = usePickerHoverLabel();
+ const { activeIframeRef, getActiveIframe, setActiveIframe } = useActivePickerIframe(
+ iframeRef,
+ isPickModeRef,
+ clearHover,
+ );
const enablePick = useCallback(() => {
- try {
- postRuntimeControlMessage(getActiveIframe()?.contentWindow, "enable-pick-mode");
- setIsPickMode(true);
- } catch {
- /* cross-origin */
- }
+ if (isPickModeRef.current || !postPickerControl(getActiveIframe(), "enable-pick-mode")) return;
+ pickStartSelectionRef.current = pickedElementRef.current;
+ isPickModeRef.current = true;
+ setIsPickMode(true);
}, [getActiveIframe]);
- const disablePick = useCallback(() => {
- try {
- postRuntimeControlMessage(getActiveIframe()?.contentWindow, "disable-pick-mode");
- } catch {
- /* cross-origin */
- }
- setIsPickMode(false);
- }, [getActiveIframe]);
+ const cancelPick = useCallback(
+ (notifyRuntime: boolean) => {
+ if (notifyRuntime) {
+ postPickerControl(getActiveIframe(), "disable-pick-mode");
+ }
+ const selection = pickStartSelectionRef.current;
+ pickStartSelectionRef.current = undefined;
+ if (selection !== undefined) {
+ pickedElementRef.current = selection;
+ setPickedElement(selection);
+ }
+ isPickModeRef.current = false;
+ clearHover();
+ setIsPickMode(false);
+ },
+ [clearHover, getActiveIframe],
+ );
+
+ const disablePick = useCallback(() => cancelPick(true), [cancelPick]);
const clearPick = useCallback(() => {
+ pickedElementRef.current = null;
setPickedElement(null);
}, []);
const windowsThatWerePrimary = useRef(new WeakSet());
+ useEffect(() => {
+ if (!isPickMode) return;
+ const handleKeyDown = (event: KeyboardEvent) => {
+ if (
+ event.key !== "Escape" ||
+ event.defaultPrevented ||
+ event.isComposing ||
+ elementOwnsEscape(event.target)
+ )
+ return;
+ event.preventDefault();
+ disablePick();
+ };
+ window.addEventListener("keydown", handleKeyDown);
+ return () => window.removeEventListener("keydown", handleKeyDown);
+ }, [disablePick, isPickMode]);
+
// Listen for picker messages from the iframe
useMountEffect(() => {
// One guard per message field, then one branch per message type.
@@ -119,31 +212,81 @@ export function useElementPicker(
)
return;
+ if (data.type === "element-hovered") {
+ if (e.source !== activeIframe.contentWindow || !isPickModeRef.current) return;
+ const info = toHoverInfo(data.elementInfo);
+ if (info) showHover(info, activeIframe);
+ return;
+ }
+
if (data.type === "element-picked" && data.elementInfo) {
- setPickedElement(toPickedElement(data.elementInfo, activeIframe));
+ const next = toPickedElement(data.elementInfo, activeIframe);
+ pickedElementRef.current = next;
+ setPickedElement(next);
+ pickStartSelectionRef.current = undefined;
+ isPickModeRef.current = false;
+ clearHover();
setIsPickMode(false);
} else if (data.type === "element-pick-candidates") {
// Multiple candidates at click point — pick the first one
const el = data.candidates?.[data.selectedIndex ?? 0];
- if (el) setPickedElement(toPickedElement(el, activeIframe));
+ if (el) {
+ const next = toPickedElement(el, activeIframe);
+ pickedElementRef.current = next;
+ setPickedElement(next);
+ }
}
if (data.type === "pick-mode-cancelled") {
- setIsPickMode(false);
+ cancelPick(false);
}
};
window.addEventListener("message", handleMessage);
- return () => window.removeEventListener("message", handleMessage);
+ return () => {
+ window.removeEventListener("message", handleMessage);
+ if (isPickModeRef.current) {
+ postPickerControl(getActiveIframe(), "disable-pick-mode");
+ }
+ disposeHover();
+ };
});
- // Ref for options to avoid stale closures in debounced callback
+ return {
+ isPickMode,
+ pickedElement,
+ setPickedElement,
+ getActiveIframe,
+ enablePick,
+ disablePick,
+ clearPick,
+ setActiveIframe,
+ activeIframeRef,
+ };
+}
+
+/** Element picking through the HyperFrame runtime's postMessage API. */
+export function useElementPicker(
+ iframeRef: React.RefObject,
+ options?: PickerOptions,
+): UseElementPickerReturn {
+ const {
+ isPickMode,
+ pickedElement,
+ setPickedElement,
+ getActiveIframe,
+ enablePick,
+ disablePick,
+ clearPick,
+ setActiveIframe,
+ activeIframeRef,
+ } = useElementPickerSession(iframeRef);
+
const optionsRef = useRef(options);
optionsRef.current = options;
const pendingWritesRef = useRef(new Map());
settlePendingWrites(pendingWritesRef.current, options?.workspaceFiles);
- // Sync immediately (not debounced) — save on every change for reliability
const syncToSource = useCallback(
(picked: PickedElement, live: HTMLElement, iframe: HTMLIFrameElement, op: PatchOperation) => {
const opts = optionsRef.current;
@@ -191,7 +334,7 @@ export function useElementPicker(
/* cross-origin */
}
},
- [pickedElement, getActiveIframe, syncToSource],
+ [pickedElement, getActiveIframe, setPickedElement, syncToSource],
);
const setDataAttr = useCallback(
@@ -221,7 +364,7 @@ export function useElementPicker(
/* cross-origin */
}
},
- [pickedElement, getActiveIframe, syncToSource],
+ [pickedElement, getActiveIframe, setPickedElement, syncToSource],
);
const setTextContent = useCallback(
@@ -244,13 +387,9 @@ export function useElementPicker(
/* cross-origin */
}
},
- [pickedElement, getActiveIframe, syncToSource],
+ [pickedElement, getActiveIframe, setPickedElement, syncToSource],
);
- // Ref-like object that always points to the active iframe (override or primary)
- const activeIframeRef = useRef(null);
- activeIframeRef.current = getActiveIframe();
-
return {
isPickMode,
pickedElement,
@@ -266,6 +405,56 @@ export function useElementPicker(
};
}
+function elementOwnsEscape(target: EventTarget | null): boolean {
+ if (!(target instanceof Element)) return false;
+ return Boolean(
+ target.closest(
+ 'dialog,[role="dialog"],[aria-modal="true"],input,textarea,select,[contenteditable="true"],[contenteditable=""],[data-studio-escape-owner]',
+ ),
+ );
+}
+
+function postPickerControl(
+ iframe: HTMLIFrameElement | null | undefined,
+ action: "enable-pick-mode" | "disable-pick-mode",
+): boolean {
+ try {
+ postRuntimeControlMessage(iframe?.contentWindow, action);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function isUnknownRecord(value: unknown): value is Record {
+ return typeof value === "object" && value !== null;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+ return typeof value === "number" && Number.isFinite(value);
+}
+
+function isOptionalString(value: unknown): value is string | null | undefined {
+ return value === null || value === undefined || typeof value === "string";
+}
+
+function toHoverInfo(value: unknown): ElementPickerHoverInfo | null {
+ if (!isUnknownRecord(value)) return null;
+ const info = value;
+ const box = info.boundingBox;
+ if (typeof info.tagName !== "string" || !isUnknownRecord(box)) return null;
+ const coordinates = [box.x, box.y, box.width, box.height];
+ if (!coordinates.every(isFiniteNumber)) return null;
+ const [x, y, width, height] = coordinates as [number, number, number, number];
+ if (!isOptionalString(info.id) || !isOptionalString(info.className)) return null;
+ return {
+ id: typeof info.id === "string" ? info.id : null,
+ className: typeof info.className === "string" ? info.className : null,
+ tagName: info.tagName,
+ boundingBox: { x, y, width, height },
+ };
+}
+
type PickedElementInfo = Partial>;
// workspaceFiles lags this hook's own writes until the host rerenders.