@cfp-studio/iframe 18.0.1 → 18.3.0

package/preview/__previewjs_internal__/runtime-bridge.ts

@@ -0,0 +1,559 @@
+/**
+ * Runtime bridge for the hidden component preview.
+ *
+ * It runs inside the preview iframe, reads React's dev source metadata from
+ * the fiber attached to each host DOM node, and posts a compact snapshot to the
+ * webview parent. It never changes the rendered tree.
+ */
+
+import {
+	type FiberLike,
+	genFiberRenderChain,
+	genFiberSourceChain,
+	getCodeInfoFromDebugSource,
+	getCodeInfoFromProps,
+	getDisplayNameForFiber,
+	getElementFiberUpward,
+	getFiberSourceLocation,
+	resolveFiberTagKind,
+	type RuntimeComponentFrame,
+	type RuntimeNode,
+	type RuntimeNodeDetail,
+	type RuntimeSnapshot,
+	summarizeComputedStyle,
+	type RuntimeSourceLocation,
+} from "@cfp-studio/fiber-reader";
+
+import {
+	clearPageOverlay,
+	isOverlayChrome,
+	setPageInteractionShield,
+	setPageOverlay,
+	type PageOverlayPayload,
+} from "./overlay";
+
+export type {
+	RuntimeBounds,
+	RuntimeComponentFrame,
+	RuntimeDomSummary,
+	RuntimeNode,
+	RuntimeNodeDetail,
+	RuntimeSnapshot,
+	RuntimeSourceLocation,
+	RuntimeViewport,
+} from "@cfp-studio/fiber-reader";
+
+declare global {
+	interface Window {
+		__cfpBridge?: (payload: string) => void;
+	}
+}
+
+const MAX_NODES = 2000;
+
+/**
+ * 盾牌只能改命中目标，不能拦住默认行为：wheel 会在盾牌上继续冒泡成滚动，
+ * 拖拽/选区/上下文菜单也各有自己的默认动作。inspect 期间逐类拦掉。
+ */
+const BLOCKED_INPUT_EVENTS = [
+	"pointerdown",
+	"pointerup",
+	"pointercancel",
+	"mousedown",
+	"mouseup",
+	"dblclick",
+	"contextmenu",
+	"dragstart",
+	"selectstart",
+] as const;
+
+/** 键盘滚动/翻页：焦点已经 blur 掉，但这些键仍然会滚页面。 */
+const SCROLL_KEYS = new Set([
+	" ",
+	"PageUp",
+	"PageDown",
+	"Home",
+	"End",
+	"ArrowUp",
+	"ArrowDown",
+	"ArrowLeft",
+	"ArrowRight",
+]);
+
+let initialized = false;
+let inspectEnabled = false;
+const nodeElements = new Map<string, Element>();
+
+export function setupRuntimeBridge(): void {
+	if (initialized || typeof window === "undefined") {
+		return;
+	}
+	initialized = true;
+	window.addEventListener("message", (event) => {
+		if (event.data?.kind === "cfp:runtime-request") {
+			publishRuntimeSnapshot();
+		} else if (event.data?.kind === "cfp:set-inspect") {
+			setInspectEnabled(Boolean(event.data.enabled));
+		} else if (event.data?.kind === "cfp:overlay") {
+			const layer = typeof event.data.layer === "string" ? event.data.layer : "default";
+			setPageOverlay(layer, event.data.overlay as PageOverlayPayload | undefined);
+		} else if (event.data?.kind === "cfp:runtime-detail") {
+			const requestId = String(event.data.requestId ?? "");
+			const runtimeNodeId = String(event.data.runtimeNodeId ?? "");
+			const detail = collectRuntimeNodeDetail(runtimeNodeId);
+			publishToHost({ kind: "cfp-runtime-detail", requestId, detail });
+		} else if (event.data?.kind === "cfp:computed-style") {
+			// Computed Styles 视图的订阅：只在该视图可见且选中节点时建立，
+			// 之后由 MutationObserver + resize 触发增量推送（见 subscribeComputedStyle）。
+			const runtimeNodeId = String(event.data.runtimeNodeId ?? "");
+			if (event.data.subscribe === true && runtimeNodeId) {
+				subscribeComputedStyle(runtimeNodeId);
+			} else {
+				unsubscribeComputedStyle();
+			}
+		}
+	});
+	document.addEventListener("click", handleInspectClick, true);
+	document.addEventListener("mousemove", handleInspectMove, true);
+	document.addEventListener("wheel", blockInspectedInteraction, { capture: true, passive: false });
+	document.addEventListener("keydown", handleInspectKeyDown, true);
+	for (const type of BLOCKED_INPUT_EVENTS) {
+		document.addEventListener(type, blockInspectedInteraction, true);
+	}
+	// Fallback for paths where the renderer's snapshot hook is not reached.
+	setTimeout(publishRuntimeSnapshot, 1000);
+}
+
+function blockInspectedInteraction(event: Event): void {
+	if (!inspectEnabled) {
+		return;
+	}
+	event.preventDefault();
+	event.stopPropagation();
+}
+
+function handleInspectKeyDown(event: KeyboardEvent): void {
+	if (!inspectEnabled || !SCROLL_KEYS.has(event.key)) {
+		return;
+	}
+	event.preventDefault();
+	event.stopPropagation();
+}
+
+function setInspectEnabled(enabled: boolean): void {
+	inspectEnabled = enabled;
+	// 两种渲染面共用这套 bridge：inspect 期间页面本身不可交互，输入只能留在覆盖层上。
+	setPageInteractionShield(enabled);
+	if (!enabled) {
+		clearPageOverlay("inspect");
+		return;
+	}
+	// 键盘焦点可能还留在应用里（tab 聚焦的输入框）：inspect 时不应该继续往里输入。
+	const active = document.activeElement;
+	if (active instanceof HTMLElement && active !== document.body && !isOverlayChrome(active)) {
+		active.blur();
+	}
+}
+
+function handleInspectClick(event: MouseEvent): void {
+	if (!inspectEnabled) {
+		return;
+	}
+	const element = elementUnderPointer(event.clientX, event.clientY);
+	const source = element ? getElementSource(element) : undefined;
+	event.preventDefault();
+	event.stopPropagation();
+	publishToHost({ kind: "cfp-runtime-select", source });
+}
+
+function handleInspectMove(event: MouseEvent): void {
+	if (!inspectEnabled) {
+		return;
+	}
+	// 盾牌只是改了命中目标，事件依旧会从 document 冒泡给应用，先截住。
+	event.stopPropagation();
+	const element = elementUnderPointer(event.clientX, event.clientY);
+	if (!element) {
+		clearPageOverlay("inspect");
+		return;
+	}
+	const rect = element.getBoundingClientRect();
+	const fiber = getElementFiberUpward(element);
+	const tag = element.tagName.toLowerCase();
+	const componentName = getComponentName(fiber);
+	const label = componentName ? `${componentName} <${tag}>` : `<${tag}>`;
+	setPageOverlay("inspect", {
+		visible: true,
+		items: [
+			{
+				x: rect.left,
+				y: rect.top,
+				width: rect.width,
+				height: rect.height,
+				label,
+			},
+		],
+	});
+}
+
+function getElementSource(element: Element): RuntimeSourceLocation | undefined {
+	return getSourceLocation(getElementFiberUpward(element));
+}
+
+/**
+ * inspect 的盾牌接管了命中测试，`elementFromPoint` 会返回覆盖层自己；
+ * 用 `elementsFromPoint` 的栈跳过覆盖层元素，才能拿到真正的应用节点。
+ */
+function elementUnderPointer(clientX: number, clientY: number): Element | undefined {
+	const stack = document.elementsFromPoint?.(clientX, clientY) ?? [];
+	const target = stack.find((element) => !isOverlayChrome(element));
+	if (target) {
+		return target;
+	}
+	const fallback = document.elementFromPoint(clientX, clientY);
+	return fallback && !isOverlayChrome(fallback) ? fallback : undefined;
+}
+
+export function publishRuntimeSnapshot(): void {
+	if (typeof window === "undefined") {
+		return;
+	}
+	const snapshot = collectRuntimeSnapshot();
+	publishToHost({ kind: "cfp-runtime-snapshot", snapshot });
+	// 重新渲染会重建 nodeElements：订阅中的节点要么拿到新值，要么显式告知已消失。
+	if (computedStyleSubscription) {
+		scheduleComputedStylePublish();
+	}
+}
+
+/**
+ * Browser mode uses a CDP Runtime binding (`window.__cfpBridge`) because the
+ * preview page is a top-level page with no parent frame. Embedded mode keeps
+ * the ancestor postMessage path.
+ */
+function publishToHost(message: unknown): void {
+	if (typeof window.__cfpBridge === "function") {
+		try {
+			window.__cfpBridge(JSON.stringify(message));
+			return;
+		} catch {
+			// Fall through to postMessage if the binding context is gone.
+		}
+	}
+	if (!window.parent || window.parent === window) {
+		return;
+	}
+	postToAncestors(message);
+}
+
+function postToAncestors(message: unknown): number {
+	const seen = new Set<Window>();
+	let posted = 0;
+	let target: any = window;
+	for (let depth = 0; depth < 5; depth += 1) {
+		try {
+			const parent = target.parent;
+			if (!parent || parent === target || seen.has(parent)) {
+				break;
+			}
+			seen.add(parent);
+			try {
+				parent.postMessage(message, "*");
+			} catch {
+				// Some embedders only preserve string messages; try the JSON fallback.
+			}
+			try {
+				parent.postMessage(JSON.stringify(message), "*");
+			} catch {
+				// Ignore secondary transport failure.
+			}
+			posted += 1;
+			target = parent;
+		} catch {
+			break;
+		}
+	}
+	return posted;
+}
+
+function collectRuntimeSnapshot(): RuntimeSnapshot {
+	const nodes: RuntimeNode[] = [];
+	nodeElements.clear();
+	const root = document.getElementById("root") ?? document.body;
+	const truncated = walk(root, undefined, "root", nodes);
+	return {
+		provider: "preview",
+		url: window.location.href,
+		capturedAt: Date.now(),
+		nodes,
+		diagnostics: truncated ? [`Node limit reached (${MAX_NODES})`] : undefined,
+	};
+}
+
+function walk(element: Element | null, parentId: string | undefined, path: string, nodes: RuntimeNode[]): boolean {
+	if (!element || nodes.length >= MAX_NODES) {
+		return nodes.length >= MAX_NODES;
+	}
+
+	const fiber = getElementFiberUpward(element);
+	const source = getSourceLocation(fiber);
+	// Path-based ID: stable across snapshots as long as the DOM structure is
+	// unchanged. The previous `dom:<index>` changed whenever a sibling appeared.
+	const id = `dom:${path}`;
+	const tag = element.tagName.toLowerCase();
+	const node: RuntimeNode = {
+		id,
+		parentId,
+		kind: "host",
+		name: tag,
+		componentName: getComponentName(fiber),
+		tag,
+		source,
+		children: [],
+	};
+	nodes.push(node);
+	nodeElements.set(id, element);
+
+	let truncated = false;
+	const children = Array.from(element.children);
+	for (let index = 0; index < children.length; index += 1) {
+		if (truncated) {
+			break;
+		}
+		const childPath = `${path}/${index}`;
+		const childId = nodes.length < MAX_NODES ? `dom:${childPath}` : undefined;
+		if (!childId) {
+			truncated = true;
+			break;
+		}
+		node.children.push(childId);
+		truncated = walk(children[index]!, id, childPath, nodes) || truncated;
+	}
+	return truncated;
+}
+
+function collectRuntimeNodeDetail(runtimeNodeId: string): RuntimeNodeDetail | undefined {
+	const element = nodeElements.get(runtimeNodeId);
+	if (!element) {
+		return undefined;
+	}
+	const rect = element.getBoundingClientRect();
+	const fiber = getElementFiberUpward(element);
+	const attributes: Record<string, string> = {};
+	for (const attribute of Array.from(element.attributes)) {
+		attributes[attribute.name] = attribute.value.slice(0, 500);
+	}
+	const text = (element.textContent ?? "").replace(/\s+/g, " ").trim();
+	const outerHTML = element.outerHTML;
+	return {
+		runtimeNodeId,
+		bounds: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+		viewport: {
+			width: window.innerWidth,
+			height: window.innerHeight,
+			scrollX: window.scrollX,
+			scrollY: window.scrollY,
+			devicePixelRatio: window.devicePixelRatio,
+		},
+		computedStyle: summarizeComputedStyle(window.getComputedStyle(element)),
+		dom: {
+			tag: element.tagName.toLowerCase(),
+			id: element.id || undefined,
+			className: element.getAttribute("class") ?? undefined,
+			attributes,
+			text: text ? text.slice(0, 500) : undefined,
+			childElementCount: element.childElementCount,
+			outerHTML: outerHTML.length > 2000 ? outerHTML.slice(0, 2000) : outerHTML,
+			outerHTMLTruncated: outerHTML.length > 2000,
+		},
+		// Render chain (who parented it) and owner chain (who authored the JSX) are
+		// different walks over the same fiber; see @cfp-studio/fiber-reader.
+		componentStack: collectFiberChain(genFiberRenderChain(fiber)),
+		ownerChain: collectFiberChain(genFiberSourceChain(fiber)),
+		capturedAt: Date.now(),
+	};
+}
+
+/**
+ * Computed Styles 视图的订阅态。
+ *
+ * 为什么不是"每次请求返回一次"：视图要跟着 DOM / 样式变化刷新（Codux 的
+ * computed-styles 也是订阅式）。这里用 MutationObserver + resize，节流成
+ * "120ms 静默后推一次、最长 600ms 必推"，并且只在摘要真的变了才发（避免噪声）。
+ */
+interface ComputedStyleSubscription {
+	runtimeNodeId: string;
+	/** 上次推送的摘要（JSON），用于去重。 */
+	lastPayload: string;
+	timer: number | undefined;
+	firstScheduledAt: number | undefined;
+}
+
+const COMPUTED_STYLE_DEBOUNCE_MS = 120;
+const COMPUTED_STYLE_MAX_DELAY_MS = 600;
+
+let computedStyleSubscription: ComputedStyleSubscription | undefined;
+let computedStyleObserver: MutationObserver | undefined;
+let computedStyleResizeListener = false;
+
+function publishComputedStyle(subscription: ComputedStyleSubscription): void {
+	const element = nodeElements.get(subscription.runtimeNodeId);
+	const computedStyle = element ? summarizeComputedStyle(window.getComputedStyle(element)) : null;
+	const payload = JSON.stringify(computedStyle);
+	if (payload === subscription.lastPayload) {
+		return;
+	}
+	subscription.lastPayload = payload;
+	publishToHost({
+		kind: "cfp-computed-style",
+		runtimeNodeId: subscription.runtimeNodeId,
+		computedStyle,
+		capturedAt: Date.now(),
+	});
+}
+
+function scheduleComputedStylePublish(): void {
+	const subscription = computedStyleSubscription;
+	if (!subscription) {
+		return;
+	}
+	const now = Date.now();
+	subscription.firstScheduledAt ??= now;
+	if (subscription.timer !== undefined) {
+		window.clearTimeout(subscription.timer);
+	}
+	const remaining = COMPUTED_STYLE_MAX_DELAY_MS - (now - subscription.firstScheduledAt);
+	const delay = Math.max(0, Math.min(COMPUTED_STYLE_DEBOUNCE_MS, remaining));
+	subscription.timer = window.setTimeout(() => {
+		if (computedStyleSubscription !== subscription) {
+			return;
+		}
+		subscription.timer = undefined;
+		subscription.firstScheduledAt = undefined;
+		publishComputedStyle(subscription);
+	}, delay);
+}
+
+function isOverlayMutation(record: MutationRecord): boolean {
+	const target = record.target;
+	if (target instanceof Element) {
+		return isOverlayChrome(target);
+	}
+	const parent = target.parentElement;
+	return Boolean(parent && isOverlayChrome(parent));
+}
+
+function subscribeComputedStyle(runtimeNodeId: string): void {
+	if (computedStyleSubscription?.runtimeNodeId === runtimeNodeId) {
+		return;
+	}
+	unsubscribeComputedStyle();
+	const subscription: ComputedStyleSubscription = {
+		runtimeNodeId,
+		lastPayload: "",
+		timer: undefined,
+		firstScheduledAt: undefined,
+	};
+	computedStyleSubscription = subscription;
+	if (!computedStyleObserver && typeof MutationObserver !== "undefined") {
+		computedStyleObserver = new MutationObserver((records) => {
+			// inspect 悬停会让 overlay 自己变形；shadow root 内的变更本来就不上报，
+			// 但 host 节点的属性变更会——这类变更不影响被选节点的 computed style。
+			if (records.every(isOverlayMutation)) {
+				return;
+			}
+			scheduleComputedStylePublish();
+		});
+		// 观察整棵树（父/兄弟节点变化也会改 computed style）；overlay 自身的变更
+		// 由 isOverlayChrome 过滤，避免 inspect 悬停时无谓重算。
+		computedStyleObserver.observe(document.documentElement, {
+			subtree: true,
+			childList: true,
+			attributes: true,
+			characterData: true,
+		});
+	}
+	if (!computedStyleResizeListener) {
+		window.addEventListener("resize", scheduleComputedStylePublish);
+		computedStyleResizeListener = true;
+	}
+	publishComputedStyle(subscription);
+}
+
+function unsubscribeComputedStyle(): void {
+	const subscription = computedStyleSubscription;
+	if (subscription?.timer !== undefined) {
+		window.clearTimeout(subscription.timer);
+	}
+	computedStyleSubscription = undefined;
+	computedStyleObserver?.disconnect();
+	computedStyleObserver = undefined;
+	if (computedStyleResizeListener) {
+		window.removeEventListener("resize", scheduleComputedStylePublish);
+		computedStyleResizeListener = false;
+	}
+}
+
+/**
+ * Turn a fiber chain into packet frames, root → node.
+ *
+ * Host / text / fragment / portal frames are dropped: the DOM ancestor chain is
+ * `domPath`'s job, and mixing the two is exactly what schema v2 separated.
+ * Layers that have no name of their own (`memo`, `Suspense`, `Provider`, …) keep
+ * their place via `kind` instead of silently vanishing.
+ */
+function collectFiberChain(fibers: Iterable<FiberLike>): RuntimeComponentFrame[] {
+	const frames: RuntimeComponentFrame[] = [];
+	for (const fiber of fibers) {
+		const kind = resolveFiberTagKind(fiber);
+		if (!kind || kind === "host" || kind === "text" || kind === "fragment" || kind === "portal") {
+			continue;
+		}
+		const name = getDisplayNameForFiber(fiber);
+		if (!name) {
+			continue;
+		}
+		const previous = frames[frames.length - 1];
+		// Consecutive duplicates carry no information (same component, same source).
+		if (previous && previous.name === name && previous.kind === kind) {
+			continue;
+		}
+		const source = getSourceLocation(fiber);
+		frames.push(source ? { name, kind, source } : { name, kind });
+	}
+	return frames.reverse();
+}
+
+/** Source position plus which tier it came from. */
+function getSourceLocation(fiber: FiberLike | undefined): RuntimeSourceLocation | undefined {
+	const location = getFiberSourceLocation(fiber);
+	if (!location) {
+		return undefined;
+	}
+	return {
+		...location,
+		evidence: getCodeInfoFromDebugSource(fiber)
+			? "_debugSource"
+			: getCodeInfoFromProps(fiber)
+				? "data-inspector"
+				: "owner",
+	};
+}
+
+function getComponentName(fiber: FiberLike | undefined): string | undefined {
+	let current = fiber;
+	// `getDisplayNameForFiber` resolves memo/forwardRef/provider layers; fall back
+	// to the nearest frame that actually has a name.
+	while (current) {
+		const name = getDisplayNameForFiber(current);
+		if (name && !isNativeTag(current)) {
+			return name;
+		}
+		current = current.return ?? undefined;
+	}
+	return undefined;
+}
+
+function isNativeTag(fiber: FiberLike): boolean {
+	return typeof fiber.type === "string";
+}

package/preview/__previewjs_internal__/vscode-control.ts

@@ -1,58 +1,83 @@
 export function setupVSCodeControlListener() {
-    console.log('setupVSCodeControlListener');
-    window.addEventListener('message', (event) => {
-        parseMessageFromChannel(event.data, (eventName, args) => {
-            console.log(`收到vscode:${eventName}消息: ${args}`);
-            if (eventName === 'ready') {
-                const { message } = JSON.parse(args) as { message: string };
-                console.log(`处理消息体: ${message}`);
-                const payload = JSON.parse(message);
-                window.__PREVIEWJS_IFRAME__.reportEvent({
-                    kind: "toggle-inspect",
-                    enabled: payload.data.isInspectorOpen,
-                });
-                return true;
-            }
-            return false
-        })
-    })
+	window.addEventListener("message", (event) => {
+		if (typeof event.data !== "string") {
+			return;
+		}
+		parseMessageFromChannel(event.data, (eventName, args) => {
+			console.debug(`收到vscode:${eventName}消息: ${args}`);
+			if (eventName === "ready") {
+				const { message } = JSON.parse(args) as { message: string };
+				const payload = JSON.parse(message);
+				window.__PREVIEWJS_IFRAME__.reportEvent({
+					kind: "toggle-inspect",
+					enabled: payload.data.isInspectorOpen,
+				});
+				return true;
+			}
+			return false;
+		});
+	});
 }
 
 export function parseMessageFromChannel(
-    message: string,
-    emit: (eventName: WebviewEvent, args: string) => boolean): boolean {
-    for (const e of webviewEventNames) {
-        if (message.substr(0, e.length) === e && message[e.length] === ':') {
-            emit(e, message.substr(e.length + 1));
-            return true;
-        }
-    }
+	message: string,
+	emit: (eventName: WebviewEvent, args: string) => boolean,
+): boolean {
+	// 预览页会收到两类消息：vscode 频道字符串，以及 cfp-* 对象（runtime-bridge / inspect）。
+	// 这里必须自己挡一次——只要调用方漏判，非字符串就会走到 substr 上炸掉整个监听器。
+	if (typeof message !== "string") {
+		return false;
+	}
+	for (const e of webviewEventNames) {
+		if (message.substr(0, e.length) === e && message[e.length] === ":") {
+			emit(e, message.substr(e.length + 1));
+			return true;
+		}
+	}
 
-    return false;
+	return false;
 }
 
-export type WebviewEvent = 'getState' | 'getUrl' | 'openInEditor' | 'cssMirrorContent' | 'ready' | 'setState' | 'telemetry' | 'websocket'
-    | 'getVscodeSettings' | 'copyText' | 'focusEditor' | 'focusEditorGroup' | 'openUrl' | 'toggleScreencast' | 'toggleInspect' | 'replayConsoleMessages'
-    | 'devtoolsConnection' | 'toggleCSSMirrorContent' | 'writeToClipboard' | 'readClipboard';
+export type WebviewEvent =
+	| "getState"
+	| "getUrl"
+	| "openInEditor"
+	| "cssMirrorContent"
+	| "ready"
+	| "setState"
+	| "telemetry"
+	| "websocket"
+	| "getVscodeSettings"
+	| "copyText"
+	| "focusEditor"
+	| "focusEditorGroup"
+	| "openUrl"
+	| "toggleScreencast"
+	| "toggleInspect"
+	| "replayConsoleMessages"
+	| "devtoolsConnection"
+	| "toggleCSSMirrorContent"
+	| "writeToClipboard"
+	| "readClipboard";
 export const webviewEventNames: WebviewEvent[] = [
-    'getState',
-    'getUrl',
-    'openInEditor',
-    'cssMirrorContent',
-    'ready',
-    'setState',
-    'telemetry',
-    'websocket',
-    'getVscodeSettings',
-    'copyText',
-    'focusEditor',
-    'focusEditorGroup',
-    'openUrl',
-    'toggleScreencast',
-    'toggleInspect',
-    'replayConsoleMessages',
-    'devtoolsConnection',
-    'toggleCSSMirrorContent',
-    'writeToClipboard',
-    'readClipboard',
-];
+	"getState",
+	"getUrl",
+	"openInEditor",
+	"cssMirrorContent",
+	"ready",
+	"setState",
+	"telemetry",
+	"websocket",
+	"getVscodeSettings",
+	"copyText",
+	"focusEditor",
+	"focusEditorGroup",
+	"openUrl",
+	"toggleScreencast",
+	"toggleInspect",
+	"replayConsoleMessages",
+	"devtoolsConnection",
+	"toggleCSSMirrorContent",
+	"writeToClipboard",
+	"readClipboard",
+];