@cfp-studio/iframe 18.0.1 → 18.3.0

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)) {