@cfp-studio/iframe 18.0.1 → 18.2.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@cfp-studio/iframe",
-  "version": "18.0.1",
+  "version": "18.2.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.mts",
   "files": [
     "dist",
     "preview"
@@ -12,12 +12,17 @@
   "devDependencies": {
     "assert-never": "1.4.0",
     "immer": "10.1.1",
-    "typescript": "5.7.3",
-    "unbuild": "2.0.0",
-    "vite": "6.2.0"
+    "typescript": "5.9.3",
+    "vite": "6.4.5"
+  },
+  "dependencies": {
+    "@cfp-studio/fiber-reader": "0.1.0"
   },
   "scripts": {
-    "build": "tsc && unbuild",
-    "release": "tsc && unbuild --minify"
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "release": "tsdown --minify",
+    "lint": "oxlint",
+    "format": "oxfmt --write ."
   }
 }

package/preview/__previewjs_internal__/index.ts

@@ -4,6 +4,7 @@ import { setUpLogInterception } from "./logs";
 import { loadRenderer } from "./renderer";
 import { runRenderer } from "./run-renderer";
 import { setState } from "./state";
+import { setupRuntimeBridge } from "./runtime-bridge";
 import { setupViteHmrListener } from "./vite-hmr-listener";
 import { setupVSCodeControlListener } from "./vscode-control";
 
@@ -21,6 +22,7 @@ export function initListeners() {
   setUpLinkInterception();
   overrideCopyCutPaste();
   setupVSCodeControlListener();
+  setupRuntimeBridge();
 }
 
 export function initPreview({
@@ -29,10 +31,8 @@ export function initPreview({
   wrapperModule,
   wrapperName,
 }: {
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   previewableModule: any;
   previewableName: string;
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   wrapperModule: any;
   wrapperName: string;
 }): typeof window.__PREVIEWJS_IFRAME__.refresh {
@@ -67,7 +67,6 @@ export function initPreview({
         shouldAbortRender: () => renderId !== thisRenderId,
         loadRenderer,
       });
-      // biome-ignore lint/suspicious/noExplicitAny: <explanation>
     } catch (error: any) {
       if (root.innerHTML !== rootHtml) {
         // 重新调用前一次渲染，以确保预览不会白屏。

package/preview/__previewjs_internal__/links.ts

@@ -8,7 +8,6 @@ export function setUpLinkInterception() {
           break;
         }
         if (node.nodeName === "A") {
-          // biome-ignore lint/suspicious/noExplicitAny: <explanation>
           const url = (node as any).href;
           // Handle click here by posting data back to VS Code
           // for your extension to handle

package/preview/__previewjs_internal__/logs.ts

@@ -14,7 +14,6 @@ const HMR_FAILED_UPDATE_REGEX =
 export function setUpLogInterception() {
   const makeLogger =
     (level: LogLevel, defaultFn: typeof console.log) =>
-      // biome-ignore lint/suspicious/noExplicitAny: <explanation>
       (...args: any[]) => {
         // Prevent an infinite call stack size if anything here logs.
         const self = console[level];
@@ -74,7 +73,6 @@ export function setUpLogInterception() {
  * @returns 
  */
 
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
 function formatError(error?: any, message?: any): string {
   // 如果 error 对象存在且包含 stack 和 message 属性
   if (error?.stack && error.message) {
@@ -95,7 +93,6 @@ function formatError(error?: any, message?: any): string {
  * @param args 
  * @returns 
  */
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
 function formatLogMessage(...args: any[]) {
   if (args.length === 0) {
     return "";
@@ -110,7 +107,6 @@ function formatLogMessage(...args: any[]) {
  * @param value 
  * @returns 
  */
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
 function formatValue(value: any) {
   if (typeof value === "string") {
     return value;

package/preview/__previewjs_internal__/overlay.ts

@@ -0,0 +1,187 @@
+/**
+ * Page-internal overlay channel.
+ *
+ * Overlays live inside the preview page so they remain aligned with the
+ * rendered pixels in external browser mode. A Shadow DOM host isolates styles
+ * from the inspected application. Each feature owns a named layer so clearing
+ * one overlay cannot clear another feature's overlay.
+ */
+
+export interface PageOverlayItem {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	label?: string;
+	color?: string;
+	borderWidth?: number;
+}
+
+export interface PageOverlayPayload {
+	visible: boolean;
+	items: PageOverlayItem[];
+}
+
+let host: HTMLDivElement | undefined;
+let shadowRoot: ShadowRoot | undefined;
+const layers = new Map<string, HTMLDivElement>();
+
+export function setPageOverlay(layerId: string, payload: PageOverlayPayload | undefined): void {
+	if (!payload?.visible || payload.items.length === 0) {
+		clearPageOverlay(layerId);
+		return;
+	}
+	ensureHost();
+	const layer = ensureLayer(layerId);
+	layer.replaceChildren();
+	for (const item of payload.items) {
+		const element = document.createElement("div");
+		element.className = "cfp-overlay-item";
+		element.style.left = `${item.x}px`;
+		element.style.top = `${item.y}px`;
+		element.style.width = `${item.width}px`;
+		element.style.height = `${item.height}px`;
+		element.style.borderColor = item.color ?? "#3794ff";
+		element.style.borderWidth = `${item.borderWidth ?? 1}px`;
+		if (item.label) {
+			const label = document.createElement("span");
+			label.className = "cfp-overlay-label";
+			label.textContent = item.label;
+			element.appendChild(label);
+		}
+		layer.appendChild(element);
+	}
+}
+
+export function clearPageOverlay(layerId?: string): void {
+	if (!layerId) {
+		host?.remove();
+		host = undefined;
+		shadowRoot = undefined;
+		layers.clear();
+		return;
+	}
+	layers.get(layerId)?.remove();
+	layers.delete(layerId);
+	if (layers.size === 0) {
+		host?.remove();
+		host = undefined;
+		shadowRoot = undefined;
+	}
+}
+
+let shieldHost: HTMLDivElement | undefined;
+
+/**
+ * inspect 期间拦掉页面自身的指针交互：用户只能和覆盖层打交道。
+ *
+ * 用一个真实元素接管命中测试，而不是靠 `pointer-events: none` + preventDefault：
+ * 这样 CSS `:hover`、光标、文本选择、拖拽、滚动、表单聚焦都不会落到应用上。
+ * 代价是 `elementFromPoint` 会返回盾牌本身，所以命中测试要换成
+ * `elementsFromPoint` 并跳过覆盖层元素（见 `isOverlayChrome`）。
+ */
+export function setPageInteractionShield(enabled: boolean): void {
+	if (typeof document === "undefined") {
+		return;
+	}
+	if (!enabled) {
+		shieldHost?.remove();
+		shieldHost = undefined;
+		return;
+	}
+	if (shieldHost?.isConnected) {
+		return;
+	}
+	const element = document.createElement("div");
+	element.dataset.cfpShield = "true";
+	element.setAttribute("aria-hidden", "true");
+	// 与应用样式隔离：`* { cursor: ... }` / `touch-action` 之类的规则不应影响盾牌。
+	const root = element.attachShadow({ mode: "closed" });
+	const style = document.createElement("style");
+	style.textContent = `
+		:host {
+			all: initial;
+			position: fixed;
+			inset: 0;
+			z-index: 2147483646;
+			cursor: crosshair;
+			touch-action: none;
+			overscroll-behavior: contain;
+		}
+		div {
+			position: fixed;
+			inset: 0;
+			background: transparent;
+		}
+	`;
+	root.append(style, document.createElement("div"));
+	document.documentElement.appendChild(element);
+	shieldHost = element;
+}
+
+/** 覆盖层自身的 DOM（overlay host / 盾牌）；命中测试必须跳过它们。 */
+export function isOverlayChrome(element: Element): boolean {
+	return Boolean(element.closest("[data-cfp-overlay], [data-cfp-shield]"));
+}
+
+function ensureLayer(layerId: string): HTMLDivElement {
+	const existing = layers.get(layerId);
+	if (existing?.isConnected) {
+		return existing;
+	}
+	if (!shadowRoot) {
+		throw new Error("Overlay shadow root is not available");
+	}
+	const layer = document.createElement("div");
+	layer.className = "cfp-overlay-layer";
+	layer.dataset.cfpOverlayLayer = layerId;
+	shadowRoot.appendChild(layer);
+	layers.set(layerId, layer);
+	return layer;
+}
+
+function ensureHost(): void {
+	if (host?.isConnected && shadowRoot) {
+		return;
+	}
+	host = document.createElement("div");
+	host.dataset.cfpOverlay = "true";
+	host.setAttribute("aria-hidden", "true");
+	shadowRoot = host.attachShadow({ mode: "closed" });
+	const style = document.createElement("style");
+	style.textContent = `
+		:host {
+			all: initial;
+			position: fixed;
+			inset: 0;
+			z-index: 2147483647;
+			pointer-events: none;
+			contain: layout style;
+		}
+		.cfp-overlay-layer {
+			position: fixed;
+			inset: 0;
+			pointer-events: none;
+		}
+		.cfp-overlay-item {
+			position: fixed;
+			box-sizing: border-box;
+			pointer-events: none;
+			border-style: solid;
+			background: rgba(55, 148, 255, 0.12);
+		}
+		.cfp-overlay-label {
+			position: absolute;
+			left: 0;
+			top: -20px;
+			padding: 2px 5px;
+			border-radius: 3px;
+			background: #3794ff;
+			color: white;
+			font: 11px/1.4 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+			white-space: nowrap;
+		}
+	`;
+	shadowRoot.appendChild(style);
+	document.documentElement.appendChild(host);
+}

package/preview/__previewjs_internal__/run-renderer.ts

@@ -1,4 +1,5 @@
 import type { RendererLoader } from "../../src";
+import { publishRuntimeSnapshot } from "./runtime-bridge";
 import { getState } from "./state";
 
 export async function runRenderer({
@@ -10,10 +11,8 @@ export async function runRenderer({
   shouldAbortRender,
   loadRenderer,
 }: {
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   wrapperModule: any;
   wrapperName: string;
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
   previewableModule: any;
   previewableName: string;
   renderId: number;
@@ -65,6 +64,9 @@ export async function runRenderer({
   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",
   });
@@ -75,7 +77,6 @@ export async function runRenderer({
  * and shown to the user.
  */
 
-// biome-ignore lint/suspicious/noExplicitAny: <explanation>
 function transformFunctions(value: any, path: string[]): any {
   if (value && typeof value === "object") {
     if (Array.isArray(value)) {