@cfp-studio/iframe 18.3.0 → 18.4.1

package/preview/__previewjs_internal__/overlay.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "vitest";
+
+import { pickActionId, runOverlayAction, setOverlayActionHandler } from "./overlay";
+
+/**
+ * 覆盖层按钮的命中判定（纯逻辑）。
+ *
+ * 这段出过两个只能手测发现的静默 bug，所以至少把「元素栈 → 动作 id」抽出来断言：
+ * - 用 `button.click()` 伪造点击时坐标是 0，会被再次命中 → 选中左上角元素；
+ * - 整个覆盖层设成可交互后，inspect 关闭时变成挡住应用的透明蒙版。
+ */
+
+/** 造一个最小可用的伪元素：只实现 `closest` 与 `dataset`。 */
+function fakeButton(actionId?: string): Element {
+	const self: { dataset: Record<string, string>; closest: (selector: string) => Element | null } = {
+		dataset: actionId ? { cfpActionId: actionId } : {},
+		closest: (selector: string) =>
+			selector.includes("data-cfp-action-id") && actionId ? (self as unknown as Element) : null,
+	};
+	return self as unknown as Element;
+}
+
+/** 按钮内部的图标元素：自身没有 dataset，`closest` 能回溯到按钮。 */
+function fakeIcon(button: Element): Element {
+	return {
+		closest: (selector: string) => (selector.includes("data-cfp-action-id") ? button : null),
+	} as unknown as Element;
+}
+
+/** 普通应用元素：`closest` 找不到按钮。 */
+function fakePageElement(): Element {
+	return { closest: () => null } as unknown as Element;
+}
+
+describe("pickActionId", () => {
+	test("栈里有按钮时返回它的动作 id", () => {
+		expect(pickActionId([fakeButton("screenshot")])).toBe("screenshot");
+	});
+
+	test("点在按钮内的 svg 上也能命中（图标是按钮的子元素）", () => {
+		// 真实场景：栈顶是 <path>/<svg>，按钮在下一层。
+		const button = fakeButton("copy-context");
+		expect(pickActionId([fakeIcon(button), button])).toBe("copy-context");
+	});
+
+	test("按钮有 data 但值为空时算未命中", () => {
+		// 防止空字符串被当成合法动作 id 发出去。
+		expect(pickActionId([fakeButton(""), fakePageElement()])).toBeUndefined();
+	});
+
+	test("纯页面元素（点到应用本身）→ undefined", () => {
+		expect(pickActionId([fakePageElement(), fakePageElement()])).toBeUndefined();
+	});
+
+	test("空栈 → undefined", () => {
+		expect(pickActionId([])).toBeUndefined();
+	});
+
+	test("栈里同时有页面元素和按钮时，优先返回按钮", () => {
+		// 这是「点按钮不该选中底层元素」的核心断言。
+		expect(pickActionId([fakePageElement(), fakeButton("screenshot")])).toBe("screenshot");
+	});
+
+	test("元素没有 closest 方法时不崩", () => {
+		// `elementsFromPoint` 在某些环境会返回非 Element 的对象。
+		expect(pickActionId([{} as Element])).toBeUndefined();
+	});
+});
+
+describe("按钮的触发路径唯一（避免一次点击执行两次）", () => {
+	// 回归：按钮曾自带 click 监听器，而 inspect 的 handleInspectClick 挂在 document
+	// 捕获阶段、先于它执行 —— 同一个动作跑两遍（实测点一次 📋 生成两个 packet，
+	// selectionId 只差最后一位）。现在只有 `runOverlayAction` 一处触发。
+	test("runOverlayAction 只回调一次", async () => {
+		const calls: string[] = [];
+		setOverlayActionHandler((id) => calls.push(id));
+		runOverlayAction("copy-context");
+		expect(calls).toEqual(["copy-context"]);
+		setOverlayActionHandler(undefined);
+	});
+
+	test("没有注册处理函数时不抛错", () => {
+		setOverlayActionHandler(undefined);
+		expect(() => runOverlayAction("screenshot")).not.toThrow();
+	});
+});

package/preview/__previewjs_internal__/overlay.ts

@@ -15,6 +15,35 @@ export interface PageOverlayItem {
 	label?: string;
 	color?: string;
 	borderWidth?: number;
+	/**
+	 * 边框线型。
+	 *
+	 * inspect 用线型区分状态：`dashed` = 鼠标悬停（跟着指针走），
+	 * `solid` = 已点选（停留不动）。只靠颜色区分对色弱用户不够。
+	 */
+	borderStyle?: "solid" | "dashed";
+	/** 背景透明度倍数；选中态更淡，避免遮住内容。 */
+	backgroundAlpha?: number;
+	/**
+	 * label 右侧的 inline 按钮（inspect 选中态用：截图 / 复制上下文）。
+	 *
+	 * `id` 由调用方定义，点击时通过 `onOverlayAction` 回调回传。
+	 */
+	actions?: Array<{
+		id: string;
+		title: string;
+		/**
+		 * 内联 SVG 元素的完整标记（不含 `<svg>` 外层）。
+		 *
+		 * 为什么不用 emoji / 字体图标：overlay 在 iframe 内的 Shadow DOM 里，
+		 * 拿不到 VS Code 的 codicon 字体；emoji 在不同平台字形与基线不一致。
+		 *
+		 * 为什么用**描边**而不是填充：实测填充版（含 `evenodd`）缩到 12px 后
+		 * 相机与剪贴板都变成实心色块，镜头/分隔线完全看不清。描边版在
+		 * 同一尺寸下轮廓清晰。
+		 */
+		iconMarkup: string;
+	}>;
 }
 
 export interface PageOverlayPayload {
@@ -22,6 +51,32 @@ export interface PageOverlayPayload {
 	items: PageOverlayItem[];
 }
 
+/**
+ * 把图标标记包进 `<svg>`。
+ *
+ * 用描边（`stroke: currentColor`）而非填充 —— 12px 下轮廓比实心块更易辨认。
+ * `vector-effect: non-scaling-stroke` 保证缩放到按钮尺寸后线宽不被压细。
+ */
+function renderIconSvg(markup: string): string {
+	return (
+		`<svg viewBox="0 0 16 16" width="12" height="12" fill="none" stroke="currentColor" ` +
+		`stroke-width="1.4" stroke-linejoin="round" stroke-linecap="round" ` +
+		`style="vector-effect:non-scaling-stroke" aria-hidden="true">${markup}</svg>`
+	);
+}
+
+/**
+ * 覆盖层按钮的点击回调。由 bridge 注册（拿到 runtimeNodeId 后发消息给宿主）。
+ *
+ * 用回调而不是在 overlay 里直接 postMessage：overlay 只管画，
+ * 不知道「当前选中哪个节点」这类业务状态。
+ */
+let onOverlayAction: ((actionId: string) => void) | undefined;
+
+export function setOverlayActionHandler(handler: ((actionId: string) => void) | undefined): void {
+	onOverlayAction = handler;
+}
+
 let host: HTMLDivElement | undefined;
 let shadowRoot: ShadowRoot | undefined;
 const layers = new Map<string, HTMLDivElement>();
@@ -43,10 +98,46 @@ export function setPageOverlay(layerId: string, payload: PageOverlayPayload | un
 		element.style.height = `${item.height}px`;
 		element.style.borderColor = item.color ?? "#3794ff";
 		element.style.borderWidth = `${item.borderWidth ?? 1}px`;
+		if (item.borderStyle) {
+			element.style.borderStyle = item.borderStyle;
+		}
+		if (item.backgroundAlpha !== undefined) {
+			// 颜色里的 alpha 写死在 CSS 里不方便逐项调，这里直接覆盖背景。
+			element.style.background = `rgba(55, 148, 255, ${item.backgroundAlpha})`;
+		}
 		if (item.label) {
 			const label = document.createElement("span");
 			label.className = "cfp-overlay-label";
-			label.textContent = item.label;
+			// 标签底色跟随该 item 的边框色：hover 是蓝、选中是橙。
+			// 之前写死在 CSS 里，导致 hover 的标签也显示成选中的橙色（实测反馈）。
+			label.style.setProperty("--cfp-label-bg", item.color ?? "#3794ff");
+			// 文字与按钮是**两个独立的圆角块**（不是同一块里加分隔线）：
+			// 外层 `label` 只做定位与排布，背景落在两个子块上。
+			const text = document.createElement("span");
+			text.className = "cfp-overlay-label-text";
+			text.textContent = item.label;
+			label.appendChild(text);
+			if (item.actions?.length) {
+				const group = document.createElement("span");
+				group.className = "cfp-overlay-actions";
+				for (const action of item.actions) {
+					const button = document.createElement("button");
+					button.className = "cfp-overlay-action";
+					button.type = "button";
+					// 供 `overlayActionAt` 命中测试用。
+					button.dataset.cfpActionId = action.id;
+					button.title = action.title;
+					button.setAttribute("aria-label", action.title);
+					button.innerHTML = renderIconSvg(action.iconMarkup);
+					// **不要给按钮加 click 监听器**：inspect 的 `handleInspectClick` 挂在
+					// document 的**捕获阶段**，它先跑（命中按钮 → `runOverlayAction`），
+					// 之后事件继续传播到按钮自己的监听器 —— 同一个动作会执行两次
+					// （实测：点一次 📋 生成两个 packet，selectionId 只差最后一位）。
+					// 捕获阶段那处已经 stopPropagation，按钮这里不需要（也无法）再挡。
+					group.appendChild(button);
+				}
+				label.appendChild(group);
+			}
 			element.appendChild(label);
 		}
 		layer.appendChild(element);
@@ -124,6 +215,52 @@ export function isOverlayChrome(element: Element): boolean {
 	return Boolean(element.closest("[data-cfp-overlay], [data-cfp-shield]"));
 }
 
+/**
+ * 某个页面坐标是否落在覆盖层的**按钮**上。
+ *
+ * 为什么需要它：inspect 的点击监听挂在 `document` 的**捕获阶段**
+ * （`addEventListener("click", handler, true)`），比按钮自己的 click 先跑；
+ * 而 `document.elementsFromPoint()` 不穿透 shadow DOM，只能看到 host。
+ * 于是「点按钮」会被当成「点页面」，选中了父元素 —— 按钮形同虚设。
+ *
+ * 这里用 `shadowRoot.elementsFromPoint` 直接问覆盖层内部，是唯一可靠的判定。
+ * 找到按钮就返回它的 `id`，调用方据此执行动作并跳过选中逻辑。
+ */
+export function overlayActionAt(clientX: number, clientY: number): string | undefined {
+	const root = shadowRoot;
+	if (!root || !host?.isConnected) {
+		return undefined;
+	}
+	return pickActionId(root.elementsFromPoint?.(clientX, clientY) ?? []);
+}
+
+/**
+ * 从 `elementsFromPoint` 的栈里挑出按钮的动作 id（纯函数，便于单测）。
+ *
+ * 抽出来的原因：这段逻辑出过两个静默 bug ——
+ * 1. 用 `button.click()` 伪造点击时 clientX/Y 是 0，会被再次命中并选中左上角元素；
+ * 2. 整个覆盖层设成可交互后，inspect 关闭时它变成一张挡住应用的透明蒙版。
+ * 两者都不容易用手测复现，至少让「栈 → 动作」这一步可以被断言。
+ *
+ * 判定用 `closest` 而不是 `instanceof HTMLButtonElement`：图标是按钮内的 `<svg>`，
+ * 点在图标的 path 上时栈顶不是 button 本身。
+ */
+export function pickActionId(stack: readonly Element[]): string | undefined {
+	for (const element of stack) {
+		const button = element.closest?.("button[data-cfp-action-id]") as HTMLElement | null;
+		const id = button?.dataset?.cfpActionId;
+		if (id) {
+			return id;
+		}
+	}
+	return undefined;
+}
+
+/** 执行某个覆盖层按钮的动作（由 `overlayActionAt` 的结果驱动）。 */
+export function runOverlayAction(actionId: string): void {
+	onOverlayAction?.(actionId);
+}
+
 function ensureLayer(layerId: string): HTMLDivElement {
 	const existing = layers.get(layerId);
 	if (existing?.isConnected) {
@@ -147,7 +284,14 @@ function ensureHost(): void {
 	host = document.createElement("div");
 	host.dataset.cfpOverlay = "true";
 	host.setAttribute("aria-hidden", "true");
-	shadowRoot = host.attachShadow({ mode: "closed" });
+	// `mode: "open"` 是必需的，不能改回 closed。
+	//
+	// `document.elementsFromPoint()` **不穿透 shadow DOM**：closed 模式下它只返回
+	// 外层 host 元素，`event.target` 也被 retarget 成 host ——
+	// 于是 inspect 的点击检测永远拿不到按钮，表现为「点按钮却选中了父元素」。
+	// open 模式下 elementsFromPoint 会返回 shadow 内部的按钮，
+	// `isOverlayChrome`（用 closest 判断）也才能把它们识别为覆盖层内容。
+	shadowRoot = host.attachShadow({ mode: "open" });
 	const style = document.createElement("style");
 	style.textContent = `
 		:host {
@@ -171,16 +315,63 @@ function ensureHost(): void {
 			background: rgba(55, 148, 255, 0.12);
 		}
 		.cfp-overlay-label {
+			/*
+			 * 只有标签自己可交互，**整层保持 pointer-events: none**。
+			 *
+			 * 早期把整层设为 auto，结果：inspect 关闭时也会渲染选中框（树→预览同步），
+			 * 于是那块透明的全屏层盖住了应用，页面从此点不动，直到重开 inspect 或刷新
+			 * （实测反馈）。现在标签外的区域仍然穿透。
+			 */
+			pointer-events: auto;
+			/* 只做定位与排布：背景在两个字块上，中间留 gap 形成视觉间隔。 */
 			position: absolute;
 			left: 0;
-			top: -20px;
-			padding: 2px 5px;
-			border-radius: 3px;
-			background: #3794ff;
+			top: -22px;
+			display: flex;
+			align-items: center;
+			gap: 4px;
 			color: white;
 			font: 11px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 			white-space: nowrap;
 		}
+		.cfp-overlay-label-text,
+		.cfp-overlay-actions {
+			/* 两个独立的圆角块；底色由 --cfp-label-bg 决定（跟随 item.color）。 */
+			display: inline-flex;
+			align-items: center;
+			padding: 2px 6px;
+			border-radius: 3px;
+			background: var(--cfp-label-bg, #3794ff);
+		}
+		.cfp-overlay-actions {
+			/* 按钮块自身的内边距小一些，图标周围不显得松。 */
+			padding: 2px 3px;
+			gap: 3px;
+		}
+		.cfp-overlay-action {
+			/* 父级是 pointer-events:none（不挡页面命中测试），按钮要单独开启。 */
+			pointer-events: auto;
+			display: inline-flex;
+			align-items: center;
+			justify-content: center;
+			width: 16px;
+			height: 16px;
+			padding: 0;
+			border: 0;
+			border-radius: 2px;
+			background: rgba(255, 255, 255, 0.22);
+			color: inherit;
+			font-size: 10px;
+			line-height: 1;
+			cursor: pointer;
+		}
+		.cfp-overlay-action svg {
+			display: block;
+			pointer-events: none;
+		}
+		.cfp-overlay-action:hover {
+			background: rgba(255, 255, 255, 0.4);
+		}
 	`;
 	shadowRoot.appendChild(style);
 	document.documentElement.appendChild(host);

package/preview/__previewjs_internal__/renderer/index.tsx

@@ -7,6 +7,6 @@ import type { RendererLoader } from "../../../src";
  * @throws {Error} 当该占位函数被调用时，会抛出“Dummy loader was invoked!”错误。
  */
 export const loadRenderer: RendererLoader = () => {
-  // 这是一个占位函数，在运行时会被特定框架的实现所替换。
-  throw new Error("调用到占位 loader 函数");
+	// 这是一个占位函数，在运行时会被特定框架的实现所替换。
+	throw new Error("调用到占位 loader 函数");
 };

package/preview/__previewjs_internal__/run-renderer.ts

@@ -3,73 +3,72 @@ import { publishRuntimeSnapshot } from "./runtime-bridge";
 import { getState } from "./state";
 
 export async function runRenderer({
-  wrapperModule,
-  wrapperName,
-  previewableModule,
-  previewableName,
-  renderId,
-  shouldAbortRender,
-  loadRenderer,
+	wrapperModule,
+	wrapperName,
+	previewableModule,
+	previewableName,
+	renderId,
+	shouldAbortRender,
+	loadRenderer,
 }: {
-  wrapperModule: any;
-  wrapperName: string;
-  previewableModule: any;
-  previewableName: string;
-  renderId: number;
-  shouldAbortRender: () => boolean;
-  loadRenderer: RendererLoader;
+	wrapperModule: any;
+	wrapperName: string;
+	previewableModule: any;
+	previewableName: string;
+	renderId: number;
+	shouldAbortRender: () => boolean;
+	loadRenderer: RendererLoader;
 }) {
-  const currentState = getState();
-  if (!currentState || shouldAbortRender()) {
-    return;
-  }
-  window.__PREVIEWJS_IFRAME__.reportEvent({
-    kind: "before-render",
-  });
-  const { render, jsxFactory } = await loadRenderer({
-    wrapperModule,
-    wrapperName,
-    previewableModule,
-    previewableName,
-    renderId,
-    shouldAbortRender,
-  });
-  if (shouldAbortRender()) {
-    return;
-  }
-  const { autogenCallbackProps, properties } =
-    await previewableModule.PreviewJsEval(
-      `
+	const currentState = getState();
+	if (!currentState || shouldAbortRender()) {
+		return;
+	}
+	window.__PREVIEWJS_IFRAME__.reportEvent({
+		kind: "before-render",
+	});
+	const { render, jsxFactory } = await loadRenderer({
+		wrapperModule,
+		wrapperName,
+		previewableModule,
+		previewableName,
+		renderId,
+		shouldAbortRender,
+	});
+	if (shouldAbortRender()) {
+		return;
+	}
+	const { autogenCallbackProps, properties } = await previewableModule.PreviewJsEval(
+		`
       let ${currentState.autogenCallbackPropsSource};
       let ${currentState.propsAssignmentSource};
       return { autogenCallbackProps, properties };
       `,
-      {
-        __jsxFactory__: jsxFactory,
-      }
-    );
-  if (shouldAbortRender()) {
-    return;
-  }
-  // Fix: break transformFunctions(properties || presetProps, []) into 2 parts
-  // 1. transformFunctions(properties, [])
-  // 2. transformFunctions(presetProps, [])
-  await render(({ presetProps, presetGlobalProps }) => ({
-    ...transformFunctions(autogenCallbackProps, []),
-    ...transformFunctions(presetGlobalProps, []),
-    ...transformFunctions(properties, []),
-    ...transformFunctions(presetProps, []),
-  }));
+		{
+			__jsxFactory__: jsxFactory,
+		},
+	);
+	if (shouldAbortRender()) {
+		return;
+	}
+	// Fix: break transformFunctions(properties || presetProps, []) into 2 parts
+	// 1. transformFunctions(properties, [])
+	// 2. transformFunctions(presetProps, [])
+	await render(({ presetProps, presetGlobalProps }) => ({
+		...transformFunctions(autogenCallbackProps, []),
+		...transformFunctions(presetGlobalProps, []),
+		...transformFunctions(properties, []),
+		...transformFunctions(presetProps, []),
+	}));
 
-  if (shouldAbortRender()) {
-    return;
-  }
-  // Publish before reportEvent: custom preview webviews may not install a
-  // __PREVIEWJS_CONTROLLER__, while the runtime bridge is independent.
-  setTimeout(publishRuntimeSnapshot, 0);
-  window.__PREVIEWJS_IFRAME__.reportEvent({
-    kind: "rendered",
-  });
+	if (shouldAbortRender()) {
+		return;
+	}
+	// Publish before reportEvent: custom preview webviews may not install a
+	// __PREVIEWJS_CONTROLLER__, while the runtime bridge is independent.
+	setTimeout(publishRuntimeSnapshot, 0);
+	window.__PREVIEWJS_IFRAME__.reportEvent({
+		kind: "rendered",
+	});
 }
 
 /**
@@ -78,41 +77,39 @@ export async function runRenderer({
  */
 
 function transformFunctions(value: any, path: string[]): any {
-  if (value && typeof value === "object") {
-    if (Array.isArray(value)) {
-      // Array.
-      return value.map((v, i) =>
-        transformFunctions(v, [...path, i.toString(10)])
-      );
-    }
-    if (value.constructor === Object) {
-      // Plain object (i.e. not Set or Map or any class instance).
-      if (value.$$typeof) {
-        // This is likely a React component, e.g. instantiated in a JSX expression.
-        // We don't want to show an action invoked when the JSX function is invoked,
-        // so skip it.
-        return value;
-      }
-      if (value.__v_isVNode) {
-        // This is likely a Vue component (at least Vue 3).
-        return value;
-      }
-      return Object.fromEntries(
-        Object.entries(value).map(([k, v]) => [
-          k,
-          typeof v === "function"
-            ? (...args: unknown[]) => {
-              window.__PREVIEWJS_IFRAME__.reportEvent({
-                kind: "action",
-                type: "fn",
-                path: [...path, k].join("."),
-              });
-              return v(...args);
-            }
-            : transformFunctions(v, [...path, k]),
-        ])
-      );
-    }
-  }
-  return value;
+	if (value && typeof value === "object") {
+		if (Array.isArray(value)) {
+			// Array.
+			return value.map((v, i) => transformFunctions(v, [...path, i.toString(10)]));
+		}
+		if (value.constructor === Object) {
+			// Plain object (i.e. not Set or Map or any class instance).
+			if (value.$$typeof) {
+				// This is likely a React component, e.g. instantiated in a JSX expression.
+				// We don't want to show an action invoked when the JSX function is invoked,
+				// so skip it.
+				return value;
+			}
+			if (value.__v_isVNode) {
+				// This is likely a Vue component (at least Vue 3).
+				return value;
+			}
+			return Object.fromEntries(
+				Object.entries(value).map(([k, v]) => [
+					k,
+					typeof v === "function"
+						? (...args: unknown[]) => {
+								window.__PREVIEWJS_IFRAME__.reportEvent({
+									kind: "action",
+									type: "fn",
+									path: [...path, k].join("."),
+								});
+								return v(...args);
+							}
+						: transformFunctions(v, [...path, k]),
+				]),
+			);
+		}
+	}
+	return value;
 }