@cfp-studio/iframe 18.3.0 → 18.4.1

package/preview/__previewjs_internal__/runtime-bridge.ts

@@ -20,6 +20,7 @@ import {
 	type RuntimeNode,
 	type RuntimeNodeDetail,
 	type RuntimeSnapshot,
+	defaultStyleKeys,
 	summarizeComputedStyle,
 	type RuntimeSourceLocation,
 } from "@cfp-studio/fiber-reader";
@@ -27,6 +28,9 @@ import {
 import {
 	clearPageOverlay,
 	isOverlayChrome,
+	overlayActionAt,
+	runOverlayAction,
+	setOverlayActionHandler,
 	setPageInteractionShield,
 	setPageOverlay,
 	type PageOverlayPayload,
@@ -82,6 +86,13 @@ const SCROLL_KEYS = new Set([
 
 let initialized = false;
 let inspectEnabled = false;
+/**
+ * 当前渲染面能否「截取单个元素」。
+ *
+ * 由宿主在 `cfp:set-inspect` 里带下来：browser 模式有 CDP 可裁切，embedded
+ * 是 iframe、跨域拿不到像素，所以不该显示那个按钮（点了只会失败）。
+ */
+let inspectScreenshotAvailable = false;
 const nodeElements = new Map<string, Element>();
 
 export function setupRuntimeBridge(): void {
@@ -89,10 +100,23 @@ export function setupRuntimeBridge(): void {
 		return;
 	}
 	initialized = true;
+	// 选中框上的快捷按钮：把「对哪个 runtime 节点做什么」发给宿主执行。
+	setOverlayActionHandler((actionId) => {
+		const runtimeNodeId = selectedRuntimeNodeId();
+		if (!runtimeNodeId) {
+			return;
+		}
+		publishToHost({ kind: "cfp-selection-action", action: actionId, runtimeNodeId });
+	});
 	window.addEventListener("message", (event) => {
 		if (event.data?.kind === "cfp:runtime-request") {
 			publishRuntimeSnapshot();
+		} else if (event.data?.kind === "cfp:select-runtime-node") {
+			// 宿主（Runtime Tree 点选）要求把某个节点标成「已选中」：
+			// 面板里选中与预览里的选中框要双向同步。
+			selectRuntimeNodeById(typeof event.data.runtimeNodeId === "string" ? event.data.runtimeNodeId : undefined);
 		} else if (event.data?.kind === "cfp:set-inspect") {
+			inspectScreenshotAvailable = event.data.screenshot === true;
 			setInspectEnabled(Boolean(event.data.enabled));
 		} else if (event.data?.kind === "cfp:overlay") {
 			const layer = typeof event.data.layer === "string" ? event.data.layer : "default";
@@ -146,6 +170,8 @@ function setInspectEnabled(enabled: boolean): void {
 	setPageInteractionShield(enabled);
 	if (!enabled) {
 		clearPageOverlay("inspect");
+		clearPageOverlay("inspect-selected");
+		selectedElement = undefined;
 		return;
 	}
 	// 键盘焦点可能还留在应用里（tab 聚焦的输入框）：inspect 时不应该继续往里输入。
@@ -155,17 +181,132 @@ function setInspectEnabled(enabled: boolean): void {
 	}
 }
 
+/**
+ * inspect 的选中态：点选后保留一个实线框，与 hover 的虚线框区分。
+ *
+ * 两层 overlay 各自独立（`inspect` / `inspect-selected`），所以 hover 移动时
+ * 不会把选中框冲掉。
+ */
+let selectedElement: Element | undefined;
+
 function handleInspectClick(event: MouseEvent): void {
 	if (!inspectEnabled) {
 		return;
 	}
+	// 先判按钮：本监听挂在 document 的**捕获阶段**，比按钮自己的 click 先跑，
+	// 而 `document.elementsFromPoint` 看不到 shadow 内部 —— 不先查这一下，
+	// 点按钮会被当成点页面（选中父元素），按钮永远点不响。
+	const actionId = overlayActionAt(event.clientX, event.clientY);
+	if (actionId) {
+		event.preventDefault();
+		event.stopPropagation();
+		// **直接调处理函数，不要 `button.click()`**：
+		// 合成事件的 clientX/Y 是 0，会被本监听器再次命中
+		// （`overlayActionAt(0, 0)` 找不到按钮 → 当成点了页面 → 选中左上角元素），
+		// 而且 `stopPropagation` 会让按钮自己的监听器永远收不到 click。
+		runOverlayAction(actionId);
+		return;
+	}
 	const element = elementUnderPointer(event.clientX, event.clientY);
 	const source = element ? getElementSource(element) : undefined;
 	event.preventDefault();
 	event.stopPropagation();
+	selectedElement = element ?? undefined;
+	renderSelectedOverlay();
 	publishToHost({ kind: "cfp-runtime-select", source });
 }
 
+/** 当前选中元素对应的 runtimeNodeId（宿主执行动作时要用它定位节点）。 */
+function selectedRuntimeNodeId(): string | undefined {
+	if (!selectedElement) {
+		return undefined;
+	}
+	for (const [id, element] of nodeElements) {
+		if (element === selectedElement) {
+			return id;
+		}
+	}
+	return undefined;
+}
+
+/** 选中框：实线 + 更淡的填充，与 hover 的虚线区分开。 */
+function renderSelectedOverlay(): void {
+	// **不依赖 inspect 模式**：Runtime Tree 点选时通常没开 inspect，
+	// 而「树 → 预览页」的选中框正是那时要显示的。
+	// （早期这里是 `!inspectEnabled` 就清空，导致反向同步永远看不到效果。）
+	if (!selectedElement || !selectedElement.isConnected) {
+		clearPageOverlay("inspect-selected");
+		return;
+	}
+	const rect = selectedElement.getBoundingClientRect();
+	const fiber = getElementFiberUpward(selectedElement);
+	const componentName = getComponentName(fiber);
+	const tag = selectedElement.tagName.toLowerCase();
+	const label = componentName ? `${componentName} <${tag}>` : `<${tag}>`;
+	setPageOverlay("inspect-selected", {
+		visible: true,
+		items: [
+			{
+				x: rect.left,
+				y: rect.top,
+				width: rect.width,
+				height: rect.height,
+				color: "#f5a623",
+				// 1px 足够：2px 在 iframe 内会显得笨重（实测反馈）。
+				borderWidth: 1,
+				borderStyle: "solid",
+				backgroundAlpha: 0.06,
+				label,
+				// 两个快捷动作挂在标签右侧：截图当前元素 / 复制 Selection Context Packet。
+				// 截图只在能截的渲染面显示：embedded（iframe）跨域拿不到像素，
+				// 给了按钮也只会失败，所以直接不渲染。
+				actions: [
+					...(inspectScreenshotAvailable
+						? [
+								{
+									id: "screenshot",
+									title: "Screenshot this element",
+									// 相机：机身 + 顶部凸起 + 镜头圆（描边版，12px 下轮廓清晰）。
+									iconMarkup: '<path d="M1.5 5.5h2.8l1-1.5h5.4l1 1.5h2.8v8h-13z"/><circle cx="8" cy="9" r="2.4"/>',
+								},
+							]
+						: []),
+					{
+						id: "copy-context",
+						title: "Copy selection context",
+						// 剪贴板：板身 + 顶部夹子（夹子用填充，否则 12px 下会糊成一片）。
+						iconMarkup:
+							'<rect x="3" y="3" width="10" height="11.5" rx="1"/><rect x="5.8" y="1.5" width="4.4" height="2.6" rx="0.8" fill="currentColor"/>',
+					},
+				],
+			},
+		],
+	});
+}
+
+/**
+ * 宿主侧让某个节点成为「选中态」（Runtime Tree 点选时用）。
+ *
+ * 通过 `cfp:runtime-detail` 之外的消息传不进来，所以用 `Runtime.evaluate`
+ * 直接调这个全局钩子（浏览器模式）/ postMessage（embedded 模式）。
+ */
+function selectRuntimeNodeById(runtimeNodeId: string | undefined): void {
+	if (!runtimeNodeId) {
+		selectedElement = undefined;
+		clearPageOverlay("inspect-selected");
+		return;
+	}
+	const element = nodeElements.get(runtimeNodeId);
+	if (!element) {
+		// 树里的节点可能不在当前 DOM（未渲染的分支）——静默，不清掉已有选中。
+		return;
+	}
+	selectedElement = element;
+	// 元素可能不在视口内：先滚动到可见位置，再按最终位置画框。
+	element.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+	renderSelectedOverlay();
+}
+
 function handleInspectMove(event: MouseEvent): void {
 	if (!inspectEnabled) {
 		return;
@@ -191,6 +332,8 @@ function handleInspectMove(event: MouseEvent): void {
 				width: rect.width,
 				height: rect.height,
 				label,
+				// hover 用虚线：与点选后的实线区分，避免「哪个是当前选中」看不出来。
+				borderStyle: "dashed",
 			},
 		],
 	});
@@ -332,6 +475,41 @@ function walk(element: Element | null, parentId: string | undefined, path: strin
 	return truncated;
 }
 
+/**
+ * 初始值基线缓存：tag → 参考元素的 computed style 摘要。
+ *
+ * 参考元素放在 shadow root 里（作者样式匹配不到影子树内部），并显式 `all: initial`，
+ * 因此拿到的是**纯 CSS 初始值**：不继承页面、也不被任何作者规则命中。
+ */
+const baselineCache = new Map<string, Record<string, string>>();
+let baselineHost: HTMLElement | undefined;
+
+function measureBaseline(tagName: string): Record<string, string> {
+	const tag = tagName.toLowerCase();
+	const cached = baselineCache.get(tag);
+	if (cached) {
+		return cached;
+	}
+	if (!baselineHost) {
+		baselineHost = document.createElement("div");
+		baselineHost.setAttribute("aria-hidden", "true");
+		baselineHost.style.cssText =
+			"position:absolute;left:-9999px;top:0;width:0;height:0;overflow:hidden;visibility:hidden;pointer-events:none;";
+		document.body.appendChild(baselineHost);
+	}
+	const root = baselineHost.shadowRoot ?? baselineHost.attachShadow({ mode: "open" });
+	root.replaceChildren();
+	const reference = document.createElement(tag);
+	// `all: initial` 让参考元素回到 **CSS 初始值**（不继承宿主、也不被作者规则命中）：
+	// 否则作者写 `div { letter-spacing: 2px }` 时，参考元素会通过继承拿到同一个值，
+	// 把用户真正设置的属性误判成默认值。
+	reference.style.all = "initial";
+	root.appendChild(reference);
+	const summary = summarizeComputedStyle(window.getComputedStyle(reference));
+	baselineCache.set(tag, summary);
+	return summary;
+}
+
 function collectRuntimeNodeDetail(runtimeNodeId: string): RuntimeNodeDetail | undefined {
 	const element = nodeElements.get(runtimeNodeId);
 	if (!element) {
@@ -345,6 +523,7 @@ function collectRuntimeNodeDetail(runtimeNodeId: string): RuntimeNodeDetail | un
 	}
 	const text = (element.textContent ?? "").replace(/\s+/g, " ").trim();
 	const outerHTML = element.outerHTML;
+	const computedStyle = summarizeComputedStyle(window.getComputedStyle(element));
 	return {
 		runtimeNodeId,
 		bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
@@ -355,7 +534,8 @@ function collectRuntimeNodeDetail(runtimeNodeId: string): RuntimeNodeDetail | un
 			scrollY: window.scrollY,
 			devicePixelRatio: window.devicePixelRatio,
 		},
-		computedStyle: summarizeComputedStyle(window.getComputedStyle(element)),
+		computedStyle,
+		computedStyleDefaults: defaultStyleKeys(computedStyle, measureBaseline(element.tagName)),
 		dom: {
 			tag: element.tagName.toLowerCase(),
 			id: element.id || undefined,
@@ -408,6 +588,8 @@ function publishComputedStyle(subscription: ComputedStyleSubscription): void {
 		kind: "cfp-computed-style",
 		runtimeNodeId: subscription.runtimeNodeId,
 		computedStyle,
+		computedStyleDefaults:
+			element && computedStyle ? defaultStyleKeys(computedStyle, measureBaseline(element.tagName)) : [],
 		capturedAt: Date.now(),
 	});
 }

package/preview/__previewjs_internal__/state.ts

@@ -3,9 +3,9 @@ import type { RenderOptions } from "../../src";
 let state: RenderOptions | null = null;
 
 export function getState() {
-  return state;
+	return state;
 }
 
 export function setState(newState: RenderOptions) {
-  state = newState;
+	state = newState;
 }

package/preview/__previewjs_internal__/vite-hmr-listener.ts

@@ -1,74 +1,75 @@
 /// <reference types="vite/client" />
 import type { ErrorPayload, UpdatePayload } from "vite/types/hmrPayload";
+
 import { generateMessageFromError } from "./error-message";
 
 const IGNORED_UPDATE_PATH = "/__previewjs_internal__/preview.js?";
 
 export function setupViteHmrListener() {
-  const hmr = import.meta.hot;
-  if (!hmr) {
-    return;
-  }
-  let error: ErrorPayload | null = null;
-  let isFirstUpdate = true;
-  hmr.on("vite:beforeFullReload", () => {
-    window.__PREVIEWJS_IFRAME__.reportEvent({
-      kind: "vite-before-reload",
-    });
-  });
-  hmr.on("vite:error", (payload: ErrorPayload) => {
-    error = payload;
-    if (typeof payload.err?.message !== "string") {
-      // This error doesn't match the expected payload.
-      // For example, this can happen with invalid CSS with the
-      // vite-plugin-vue2 plugin.
-      // Block this to prevent crashes down the track.
-      return;
-    }
-    window.__PREVIEWJS_IFRAME__.reportEvent({
-      kind: "error",
-      source: "vite",
-      message: generateMessageFromError(payload.err.message, payload.err.stack),
-    });
-  });
-  hmr.on("vite:beforeUpdate", (payload: UpdatePayload) => {
-    if (payload.updates.every((u) => u.path.startsWith(IGNORED_UPDATE_PATH))) {
-      // Ignore.
-      return;
-    }
-    // This is a copy of Vite logic that is disabled when the error overlay is off:
-    // https://github.com/vitejs/vite/blob/f3d15f106f378c3850b62fbebd69fc8f7c7f944b/packages/vite/src/client/client.ts#L61
-    if (error && isFirstUpdate) {
-      window.location.reload();
-    } else {
-      error = null;
-      isFirstUpdate = false;
-    }
-    if (window.__PREVIEWJS_IFRAME__.lastRenderFailed) {
-      window.location.reload();
-    } else {
-      window.__PREVIEWJS_IFRAME__.reportEvent({
-        kind: "vite-before-update",
-        payload,
-      });
-    }
-  });
-  hmr.on("vite:afterUpdate", (payload: UpdatePayload) => {
-    if (payload.updates.every((u) => u.path.startsWith(IGNORED_UPDATE_PATH))) {
-      // Ignore.
-      return;
-    }
-    window.__PREVIEWJS_IFRAME__.reportEvent({
-      kind: "vite-after-update",
-      payload,
-    });
-  });
-  hmr.on("vite:invalidate", () => {
-    window.__PREVIEWJS_IFRAME__.reportEvent({
-      kind: "vite-invalidate",
-    });
-    window.__PREVIEWJS_IFRAME__.refresh({
-      refetchPreviewableModule: true,
-    });
-  });
+	const hmr = import.meta.hot;
+	if (!hmr) {
+		return;
+	}
+	let error: ErrorPayload | null = null;
+	let isFirstUpdate = true;
+	hmr.on("vite:beforeFullReload", () => {
+		window.__PREVIEWJS_IFRAME__.reportEvent({
+			kind: "vite-before-reload",
+		});
+	});
+	hmr.on("vite:error", (payload: ErrorPayload) => {
+		error = payload;
+		if (typeof payload.err?.message !== "string") {
+			// This error doesn't match the expected payload.
+			// For example, this can happen with invalid CSS with the
+			// vite-plugin-vue2 plugin.
+			// Block this to prevent crashes down the track.
+			return;
+		}
+		window.__PREVIEWJS_IFRAME__.reportEvent({
+			kind: "error",
+			source: "vite",
+			message: generateMessageFromError(payload.err.message, payload.err.stack),
+		});
+	});
+	hmr.on("vite:beforeUpdate", (payload: UpdatePayload) => {
+		if (payload.updates.every((u) => u.path.startsWith(IGNORED_UPDATE_PATH))) {
+			// Ignore.
+			return;
+		}
+		// This is a copy of Vite logic that is disabled when the error overlay is off:
+		// https://github.com/vitejs/vite/blob/f3d15f106f378c3850b62fbebd69fc8f7c7f944b/packages/vite/src/client/client.ts#L61
+		if (error && isFirstUpdate) {
+			window.location.reload();
+		} else {
+			error = null;
+			isFirstUpdate = false;
+		}
+		if (window.__PREVIEWJS_IFRAME__.lastRenderFailed) {
+			window.location.reload();
+		} else {
+			window.__PREVIEWJS_IFRAME__.reportEvent({
+				kind: "vite-before-update",
+				payload,
+			});
+		}
+	});
+	hmr.on("vite:afterUpdate", (payload: UpdatePayload) => {
+		if (payload.updates.every((u) => u.path.startsWith(IGNORED_UPDATE_PATH))) {
+			// Ignore.
+			return;
+		}
+		window.__PREVIEWJS_IFRAME__.reportEvent({
+			kind: "vite-after-update",
+			payload,
+		});
+	});
+	hmr.on("vite:invalidate", () => {
+		window.__PREVIEWJS_IFRAME__.reportEvent({
+			kind: "vite-invalidate",
+		});
+		window.__PREVIEWJS_IFRAME__.refresh({
+			refetchPreviewableModule: true,
+		});
+	});
 }

package/preview/index.html

@@ -1,83 +1,82 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-  <head>
-    <link rel="icon" href="/logo.png" />
-    <script>
-      // 将全局对象 globalThis 赋值给 window.global，确保在不同环境下全局对象的一致性
-      window.global = globalThis;
-      // 将 window.module 设置为 undefined，避免模块冲突
-      window.module = undefined;
+	<head>
+		<link rel="icon" href="/logo.png" />
+		<script>
+			// 将全局对象 globalThis 赋值给 window.global，确保在不同环境下全局对象的一致性
+			window.global = globalThis;
+			// 将 window.module 设置为 undefined，避免模块冲突
+			window.module = undefined;
 
-      // 定义一个全局对象 __PREVIEWJS_IFRAME__，用于管理预览框架的状态和事件
-      window.__PREVIEWJS_IFRAME__ = {
-        // 初始化 lastRenderFailed 为 false，表示初始渲染未失败
-        lastRenderFailed: false,
-        toggleInspect:false,
-        /**
-         * 报告预览事件
-         * @param {Object} event - 事件对象
-         * @param {string} event.kind - 事件类型，如 "rendered" 或 "error"
-         * @param {string} [event.source] - 事件源，如 "renderer"
-         */
-        reportEvent: (event) => {
-          // 如果事件类型为 "rendered"，则将 lastRenderFailed 设为 false
-          if (event.kind === "rendered" ) {
-            window.__PREVIEWJS_IFRAME__.lastRenderFailed = false;
-          } 
-          // 如果事件类型为 "error" 且事件源为 "renderer"，则将 lastRenderFailed 设为 true
-          else if (event.kind === "error" && event.source === "renderer") {
-            window.__PREVIEWJS_IFRAME__.lastRenderFailed = true;
-          }
-          // 调用控制器的 onPreviewEvent 方法处理事件.
-          // 跨域 iframe 无法直接读取 parent 的属性，此时走 postMessage.
-          let delivered = false;
-          try {
-            const controller =
-              // 注意: 与 core/src/html-error.ts 中的代码保持同步.
-              window.__PREVIEWJS_CONTROLLER__ || window.parent.__PREVIEWJS_CONTROLLER__;
-            if (controller) {
-              controller.onPreviewEvent(event);
-              delivered = true;
-            }
-          } catch {
-            // cross-origin parent; fall through to postMessage
-          }
-          if (!delivered && window.parent !== window) {
-            window.parent.postMessage({ kind: "preview-event", event }, "*");
-          }
-        },
-        /**
-         * 刷新预览
-         * 目前为空函数，可根据需求实现具体逻辑
-         */
-        refresh: () => {}
-      };
-      // 报告启动事件，表明预览框架正在初始化
-      window.__PREVIEWJS_IFRAME__.reportEvent({
-        kind: "bootstrapping",
-      });
-    </script>
-    <!-- %OPTIONAL_HEAD_CONTENT% -->
-    <style>
-      body {
-        padding: 1rem;
-        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto",
-          "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans",
-          "Helvetica Neue", sans-serif;
-        -webkit-font-smoothing: antialiased;
-        -moz-osx-font-smoothing: grayscale;
-      }
+			// 定义一个全局对象 __PREVIEWJS_IFRAME__，用于管理预览框架的状态和事件
+			window.__PREVIEWJS_IFRAME__ = {
+				// 初始化 lastRenderFailed 为 false，表示初始渲染未失败
+				lastRenderFailed: false,
+				toggleInspect: false,
+				/**
+				 * 报告预览事件
+				 * @param {Object} event - 事件对象
+				 * @param {string} event.kind - 事件类型，如 "rendered" 或 "error"
+				 * @param {string} [event.source] - 事件源，如 "renderer"
+				 */
+				reportEvent: (event) => {
+					// 如果事件类型为 "rendered"，则将 lastRenderFailed 设为 false
+					if (event.kind === "rendered") {
+						window.__PREVIEWJS_IFRAME__.lastRenderFailed = false;
+					}
+					// 如果事件类型为 "error" 且事件源为 "renderer"，则将 lastRenderFailed 设为 true
+					else if (event.kind === "error" && event.source === "renderer") {
+						window.__PREVIEWJS_IFRAME__.lastRenderFailed = true;
+					}
+					// 调用控制器的 onPreviewEvent 方法处理事件.
+					// 跨域 iframe 无法直接读取 parent 的属性，此时走 postMessage.
+					let delivered = false;
+					try {
+						const controller =
+							// 注意: 与 core/src/html-error.ts 中的代码保持同步.
+							window.__PREVIEWJS_CONTROLLER__ || window.parent.__PREVIEWJS_CONTROLLER__;
+						if (controller) {
+							controller.onPreviewEvent(event);
+							delivered = true;
+						}
+					} catch {
+						// cross-origin parent; fall through to postMessage
+					}
+					if (!delivered && window.parent !== window) {
+						window.parent.postMessage({ kind: "preview-event", event }, "*");
+					}
+				},
+				/**
+				 * 刷新预览
+				 * 目前为空函数，可根据需求实现具体逻辑
+				 */
+				refresh: () => {},
+			};
+			// 报告启动事件，表明预览框架正在初始化
+			window.__PREVIEWJS_IFRAME__.reportEvent({
+				kind: "bootstrapping",
+			});
+		</script>
+		<!-- %OPTIONAL_HEAD_CONTENT% -->
+		<style>
+			body {
+				padding: 1rem;
+				font-family:
+					-apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans",
+					"Droid Sans", "Helvetica Neue", sans-serif;
+				-webkit-font-smoothing: antialiased;
+				-moz-osx-font-smoothing: grayscale;
+			}
 
-      code,
-      .code {
-        font-family: source-code-pro, Menlo, Monaco, Consolas, "Courier New",
-          monospace;
-      }
-    </style>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
+			code,
+			.code {
+				font-family: source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;
+			}
+		</style>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+	</head>
+	<body>
+		<div id="root"></div>
+	</body>
 </html>