@cfp-studio/iframe 18.4.2 → 18.4.4

package/dist/index.d.mts

@@ -33,6 +33,14 @@ declare global {
        */
       lastRenderFailed: boolean;
       toggleInspect: boolean;
+      /**
+       * 编译期错误兜底开关（`index.html` 的内联脚本用）。
+       *
+       * `true` 时由 `index.html` 上报那些「模块还没加载就崩」的错误
+       * （Vite 解析 `.less` 失败、`react-dom` 缺失等）；`logs.ts` 接管后置 `false`。
+       * 见 `docs/todo/39`。
+       */
+      startupErrorGuard: boolean;
       /**
        * 处理 HMR 更新
        * @param payload - HMR 更新的负载

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfp-studio/iframe",
-  "version": "18.4.2",
+  "version": "18.4.4",
   "license": "MIT",
   "files": [
     "dist",

package/preview/__previewjs_internal__/logs.ts

@@ -45,6 +45,10 @@ export function setUpLogInterception() {
 	console.info = makeLogger("info", console.info);
 	console.warn = makeLogger("warn", console.warn);
 	console.error = makeLogger("error", console.error);
+	// 接管 `index.html` 的编译期兜底（见 `docs/todo/39`）：
+	// 本模块靠模块加载才能执行，所以更早的失败只能由 `index.html` 的内联脚本接住。
+	// 现在轮到我们了，关掉那个兜底，避免同一个错误上报两次。
+	window.__PREVIEWJS_IFRAME__.startupErrorGuard = false;
 	window.onerror = (message, source, lineno, colno, error) => {
 		window.__PREVIEWJS_IFRAME__.reportEvent({
 			kind: "error",

package/preview/__previewjs_internal__/overlay.ts

@@ -18,8 +18,9 @@ export interface PageOverlayItem {
 	/**
 	 * 边框线型。
 	 *
-	 * inspect 用线型区分状态：`dashed` = 鼠标悬停（跟着指针走），
-	 * `solid` = 已点选（停留不动）。只靠颜色区分对色弱用户不够。
+	 * 现有语义：
+	 * - `dashed` = inspect 的鼠标悬停（跟着指针走）
+	 * - `solid` = 已点选的选中态（不论来自预览点选还是树点选 —— 框不编码来源）
 	 */
 	borderStyle?: "solid" | "dashed";
 	/** 背景透明度倍数；选中态更淡，避免遮住内容。 */
@@ -310,6 +311,10 @@ function ensureHost(): void {
 		.cfp-overlay-item {
 			position: fixed;
 			box-sizing: border-box;
+			/*
+			 * 边框本身可命中：这样鼠标移到框线上时能触发 hover，
+			 * 内部区域仍然穿透 —— 不能整块 auto，否则会挡住页面交互。
+			 */
 			pointer-events: none;
 			border-style: solid;
 			background: rgba(55, 148, 255, 0.12);
@@ -334,9 +339,8 @@ function ensureHost(): void {
 			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）。 */
+		.cfp-overlay-label-text {
+			/* 文字块：实心底色由 --cfp-label-bg 决定（跟随 item.color）。 */
 			display: inline-flex;
 			align-items: center;
 			padding: 2px 6px;
@@ -344,13 +348,62 @@ function ensureHost(): void {
 			background: var(--cfp-label-bg, #3794ff);
 		}
 		.cfp-overlay-actions {
-			/* 按钮块自身的内边距小一些，图标周围不显得松。 */
-			padding: 2px 3px;
+			/*
+			 * 按钮块：**透明背景**，与文字块靠 gap 分隔 ——
+			 * 不再叠一层同色实心块，视觉上少一个方块、也少占一点宽度。
+			 * 内边距保留 2px，让图标与文字块的间距不至于挤在一起。
+			 */
+			display: inline-flex;
+			align-items: center;
+			/* 上下 padding 归零：否则 height:0 的盒子仍会被撑到 4px 高。 */
+			padding: 0 3px;
 			gap: 3px;
+			background: transparent;
+			/*
+			 * **关键：不参与所在 flex 行的尺寸计算。**
+			 *
+			 * 这一行是 align-items: center 的 flex，行高由最高子项决定：
+			 * 文字块 ≈ 19.4px（line-height 15.4 + padding 4），
+			 * 而按钮是固定 16px + padding 4 = 20px —— 比文字块高 0.6px。
+			 * 于是按钮「参与布局」与「不参与布局」两种状态下，行高在
+			 * 19px / 20px 之间取整跳动，表现为鼠标进出标签时整条标签上下呼吸。
+			 *
+			 * align-self: center + height: 0 让这个盒子高度为零：
+			 * 它内部的按钮溢出显示，但**不再撑高这一行**，行高恒等于文字块。
+			 */
+			height: 0;
+			align-self: center;
+			/*
+			 * 默认隐藏，鼠标移到标签上才出现。
+			 *
+			 * 为什么用 opacity 而不是 display:none：
+			 * 按钮靠 overlayActionAt() 做命中测试，而
+			 * elementsFromPoint() **不会返回 display:none 的元素** ——
+			 * 用 display 隐藏会让按钮永久点不到。
+			 *
+			 * 这里只切 opacity、**不切 visibility**：visibility 是离散属性，
+			 * 会让浏览器在布局阶段重新判断元素是否参与计算；只改 opacity
+			 * 走的是合成层，不影响任何几何。
+			 */
+			opacity: 0;
+			transition: opacity 0.12s ease;
+		}
+		/*
+		 * 鼠标移到**标签**上时才显示按钮。
+		 *
+		 * 没有做「hover 到框」：框是 pointer-events:none（必须如此，否则它会把
+		 * 页面交互全挡住）。要让框线可命中
+		 * 就得包一层可交互元素，那又回到「透明蒙版挡页面」的老问题。
+		 * 标签就在框的左上角，hover 过去只多一个短距离，性价比更高。
+		 */
+		.cfp-overlay-label:hover .cfp-overlay-actions {
+			opacity: 1;
 		}
 		.cfp-overlay-action {
 			/* 父级是 pointer-events:none（不挡页面命中测试），按钮要单独开启。 */
 			pointer-events: auto;
+			/* 容器高度为 0，按钮靠自身尺寸溢出显示；不收缩。 */
+			flex: 0 0 auto;
 			display: inline-flex;
 			align-items: center;
 			justify-content: center;
@@ -359,7 +412,8 @@ function ensureHost(): void {
 			padding: 0;
 			border: 0;
 			border-radius: 2px;
-			background: rgba(255, 255, 255, 0.22);
+			/* 透明：底色直接取标签块的颜色，少一层白雾、更干净。 */
+			background: transparent;
 			color: inherit;
 			font-size: 10px;
 			line-height: 1;
@@ -370,7 +424,8 @@ function ensureHost(): void {
 			pointer-events: none;
 		}
 		.cfp-overlay-action:hover {
-			background: rgba(255, 255, 255, 0.4);
+			/* 悬停时才给一层浅底，明确「点得到」。 */
+			background: rgba(255, 255, 255, 0.28);
 		}
 	`;
 	shadowRoot.appendChild(style);

package/preview/__previewjs_internal__/reflowTracker.spec.ts

@@ -0,0 +1,254 @@
+import { describe, expect, it } from "vitest";
+
+import { type ReflowObserver, type ReflowTarget, trackReflow } from "./reflowTracker";
+
+/**
+ * `trackReflow` 的契约测试（`docs/todo/33` 问题 2）。
+ *
+ * 这个模块的存在理由：覆盖层用 `position: fixed` + 视口坐标，滚动/缩放后必须重算。
+ * 而这类 bug 的典型失手方式是**监听器没解绑**（选中切换频繁 → 累积泄漏）
+ * 或**没节流**（滚动时每事件重绘 → 掉帧）。所以测试重点放在这两条上，
+ * 而不是「能不能收到事件」。
+ */
+
+interface FakeTarget extends ReflowTarget {
+	emit(type: string): void;
+	listenerCount(type: string): number;
+	lastOptions(type: string): AddEventListenerOptions | undefined;
+}
+
+function fakeTarget(): FakeTarget {
+	const listeners = new Map<string, Set<() => void>>();
+	const options = new Map<string, AddEventListenerOptions | undefined>();
+	return {
+		addEventListener(type, listener, opts) {
+			if (!listeners.has(type)) {
+				listeners.set(type, new Set());
+			}
+			listeners.get(type)!.add(listener);
+			options.set(type, opts);
+		},
+		removeEventListener(type, listener) {
+			listeners.get(type)?.delete(listener);
+		},
+		emit(type) {
+			for (const listener of [...(listeners.get(type) ?? [])]) {
+				listener();
+			}
+		},
+		listenerCount(type) {
+			return listeners.get(type)?.size ?? 0;
+		},
+		lastOptions(type) {
+			return options.get(type);
+		},
+	};
+}
+
+/** 手动步进的调度器：记录排队的回调，由测试决定何时「进入下一帧」。 */
+function manualScheduler() {
+	const queue: Array<() => void> = [];
+	return {
+		schedule: (callback: () => void) => {
+			queue.push(callback);
+		},
+		/** 执行当前排队的全部回调（模拟一帧）。 */
+		frame() {
+			for (const callback of queue.splice(0)) {
+				callback();
+			}
+		},
+		pending: () => queue.length,
+	};
+}
+
+function fakeObserver(): ReflowObserver & { observed: Element[]; readonly disconnected: number } {
+	const state = { observed: [] as Element[], disconnected: 0 };
+	return {
+		get observed() {
+			return state.observed;
+		},
+		get disconnected() {
+			return state.disconnected;
+		},
+		observe(target) {
+			state.observed.push(target);
+		},
+		disconnect() {
+			state.disconnected++;
+		},
+	} as unknown as ReflowObserver & { observed: Element[]; readonly disconnected: number };
+}
+
+/** 占位元素：`trackReflow` 只把它转交给 observer，不读任何属性。 */
+const fakeElement = {} as Element;
+
+describe("trackReflow", () => {
+	it("scroll 与 resize 都会触发重算", () => {
+		const target = fakeTarget();
+		const scheduler = manualScheduler();
+		let count = 0;
+		trackReflow({ onReflow: () => count++, target, schedule: scheduler.schedule });
+
+		target.emit("scroll");
+		scheduler.frame();
+		expect(count).toBe(1);
+
+		target.emit("resize");
+		scheduler.frame();
+		expect(count).toBe(2);
+	});
+
+	it("同一帧内多个事件只重算一次（节流）", () => {
+		const target = fakeTarget();
+		const scheduler = manualScheduler();
+		let count = 0;
+		trackReflow({ onReflow: () => count++, target, schedule: scheduler.schedule });
+
+		for (let i = 0; i < 20; i++) {
+			target.emit("scroll");
+		}
+		expect(scheduler.pending()).toBe(1);
+		scheduler.frame();
+		expect(count).toBe(1);
+
+		// 下一帧可以再次触发（节流不是「只跑一次」）。
+		target.emit("scroll");
+		scheduler.frame();
+		expect(count).toBe(2);
+	});
+
+	it("scroll 用捕获阶段监听（内部滚动容器不冒泡到 window）", () => {
+		const target = fakeTarget();
+		trackReflow({ onReflow: () => {}, target, schedule: manualScheduler().schedule });
+
+		const options = target.lastOptions("scroll");
+		expect(options?.capture).toBe(true);
+		expect(options?.passive).toBe(true);
+		expect(target.lastOptions("resize")?.passive).toBe(true);
+	});
+
+	it("stop() 解绑全部监听并断开 observer", () => {
+		const target = fakeTarget();
+		const observer = fakeObserver();
+		const tracker = trackReflow({
+			onReflow: () => {},
+			target,
+			schedule: manualScheduler().schedule,
+			resizeObserverFactory: () => observer,
+			observe: fakeElement,
+		});
+
+		expect(target.listenerCount("scroll")).toBe(1);
+		expect(target.listenerCount("resize")).toBe(1);
+		expect(observer.observed).toEqual([fakeElement]);
+
+		tracker.stop();
+
+		expect(target.listenerCount("scroll")).toBe(0);
+		expect(target.listenerCount("resize")).toBe(0);
+		expect(observer.disconnected).toBe(1);
+	});
+
+	it("stop() 幂等：重复调用只断开一次、且不再重算", () => {
+		const target = fakeTarget();
+		const scheduler = manualScheduler();
+		const observer = fakeObserver();
+		let count = 0;
+		const tracker = trackReflow({
+			onReflow: () => count++,
+			target,
+			schedule: scheduler.schedule,
+			resizeObserverFactory: () => observer,
+			observe: fakeElement,
+		});
+
+		// 先排一个回调，再 stop —— 已排队的回调不应再执行重算。
+		target.emit("scroll");
+		tracker.stop();
+		tracker.stop();
+		scheduler.frame();
+
+		expect(count).toBe(0);
+		expect(observer.disconnected).toBe(1);
+
+		// 解绑后事件不再排队。
+		target.emit("scroll");
+		expect(scheduler.pending()).toBe(0);
+	});
+
+	it("stop() 之后 flush() 不再重算", () => {
+		const target = fakeTarget();
+		let count = 0;
+		const tracker = trackReflow({ onReflow: () => count++, target, schedule: manualScheduler().schedule });
+
+		tracker.flush();
+		expect(count).toBe(1);
+
+		tracker.stop();
+		tracker.flush();
+		expect(count).toBe(1);
+	});
+
+	it("ResizeObserver 回调走同一条节流路径", () => {
+		const scheduler = manualScheduler();
+		let onResize: (() => void) | undefined;
+		let count = 0;
+		trackReflow({
+			onReflow: () => count++,
+			target: fakeTarget(),
+			schedule: scheduler.schedule,
+			resizeObserverFactory: (callback) => {
+				onResize = callback;
+				return fakeObserver();
+			},
+			observe: fakeElement,
+		});
+
+		onResize?.();
+		onResize?.();
+		expect(scheduler.pending()).toBe(1);
+		scheduler.frame();
+		expect(count).toBe(1);
+	});
+
+	it("没有 ResizeObserver 时仍能工作（只靠 scroll / resize）", () => {
+		const target = fakeTarget();
+		const scheduler = manualScheduler();
+		let count = 0;
+		expect(() =>
+			trackReflow({
+				onReflow: () => count++,
+				target,
+				schedule: scheduler.schedule,
+				resizeObserverFactory: undefined,
+				observe: fakeElement,
+			}),
+		).not.toThrow();
+
+		target.emit("scroll");
+		scheduler.frame();
+		expect(count).toBe(1);
+	});
+
+	it("observer 构造抛错时降级，不影响滚动重算", () => {
+		const target = fakeTarget();
+		const scheduler = manualScheduler();
+		let count = 0;
+		expect(() =>
+			trackReflow({
+				onReflow: () => count++,
+				target,
+				schedule: scheduler.schedule,
+				resizeObserverFactory: () => {
+					throw new Error("unsupported");
+				},
+				observe: fakeElement,
+			}),
+		).not.toThrow();
+
+		target.emit("scroll");
+		scheduler.frame();
+		expect(count).toBe(1);
+	});
+});

package/preview/__previewjs_internal__/reflowTracker.ts

@@ -0,0 +1,147 @@
+/**
+ * 让某块「位置依赖」的覆盖层跟随布局变化重算（`docs/todo/33` 问题 2）。
+ *
+ * ## 为什么需要这个模块
+ *
+ * 覆盖层用的是 `position: fixed` + **视口坐标**（`getBoundingClientRect()` 的结果）。
+ * 视口坐标只在「计算那一刻」有效 —— 页面一旦滚动或窗口一旦缩放，元素在视口中的位置
+ * 就变了，而覆盖层不会自己动。所以必须在选中态存续期间**持续重算**。
+ *
+ * ## 要监听哪些「变化源」
+ *
+ * | 变化源 | 监听方式 | 为什么 |
+ * | --- | --- | --- |
+ * | 窗口/文档滚动 | `scroll` + `capture` | 内部滚动容器（`overflow:auto`）**不会**冒泡到 window，只有捕获阶段能收到 |
+ * | 视口缩放 | `resize` | 元素尺寸/位置都可能变 |
+ * | 元素自身尺寸 | `ResizeObserver` | 内容变多导致高度变化时，`resize` 未必触发 |
+ *
+ * 已知局限：`ResizeObserver` 只在**被观察元素尺寸**变化时回调，元素因兄弟节点变化
+ * 而位移时不触发。这类位移主要发生在滚动（已覆盖）与页面重排（通常伴随尺寸变化）时，
+ * 实际观测到的场景已能覆盖，故**不做逐帧轮询** —— 轮询的是开销与抖动，不值得。
+ *
+ * ## 节流
+ *
+ * 滚动事件高频（一次滚动可产生几十个事件）。用 `requestAnimationFrame` 合并：
+ * 一帧内的多次请求只重算一次，且重算发生在绘制前，不会出现拖影。
+ *
+ * ## 清理
+ *
+ * `stop()` 必须解绑全部监听并断开两个 observer。调用方的契约：
+ * - 选中态建立 → `start()`
+ * - 选中态结束（取消选中 / 元素失联 / 重入 setup）→ `stop()`
+ *
+ * 重复 `start()` 会先 `stop()`，因此调用方不需要自己记账。
+ */
+
+/** 只依赖所需的最小 DOM 能力，方便单测传入假件。 */
+export interface ReflowTarget {
+	addEventListener(type: string, listener: () => void, options?: AddEventListenerOptions): void;
+	removeEventListener(type: string, listener: () => void, options?: EventListenerOptions): void;
+}
+
+export interface ReflowObserver {
+	observe(target: Element): void;
+	disconnect(): void;
+}
+
+export interface TrackOptions {
+	/** 执行重算（已节流）。 */
+	onReflow: () => void;
+	/** 滚动/缩放事件的宿主，默认 `window`。 */
+	target?: ReflowTarget;
+	/** 一帧调度器，默认 `requestAnimationFrame`；单测可注入同步实现。 */
+	schedule?: (callback: () => void) => void;
+	/** `ResizeObserver` 构造器，默认全局同名对象；不可用时跳过该观察源。 */
+	resizeObserverFactory?: (callback: () => void) => ReflowObserver;
+	/** 被观察尺寸/位置的目标（通常是选中元素）。**不传则不建 ResizeObserver**，只靠 scroll / resize。 */
+	observe?: Element;
+}
+
+export interface ReflowTracker {
+	/** 立刻重算一次（不等待下一帧），用于选中态刚建立时。 */
+	flush(): void;
+	/** 解绑全部监听并断开 observer；可重复调用。 */
+	stop(): void;
+}
+
+/**
+ * 让 `onReflow` 在滚动 / 缩放 / 元素尺寸变化时被节流调用。
+ *
+ * 返回的 tracker 在 `stop()` 前一直有效；`stop()` 幂等。
+ */
+export function trackReflow(options: TrackOptions): ReflowTracker {
+	const target = options.target ?? (typeof window === "undefined" ? undefined : (window as unknown as ReflowTarget));
+	const schedule =
+		options.schedule ??
+		((callback: () => void) => {
+			if (typeof requestAnimationFrame === "function") {
+				requestAnimationFrame(callback);
+				return;
+			}
+			// 没有 rAF 的环境（极端降级）直接同步执行，宁可掉帧也不要漏重算。
+			callback();
+		});
+
+	let pending = false;
+	let stopped = false;
+
+	// 节流核心：一帧内只跑一次。`pending` 置位后到回调执行前不再重复排队，
+	// 避免快速滚动时把一帧内的 N 个事件排成 N 个回调。
+	const requestReflow = (): void => {
+		if (stopped || pending) {
+			return;
+		}
+		pending = true;
+		schedule(() => {
+			pending = false;
+			if (!stopped) {
+				options.onReflow();
+			}
+		});
+	};
+
+	// 内部滚动容器不冒泡到 window，必须用捕获阶段才能收到。
+	// passive: true —— 我们从不 preventDefault，声明 passive 让浏览器不必等待监听器返回。
+	// 同一个对象同时用于 add / remove：解绑时 `capture` 必须一致，否则解不掉。
+	const scrollListenOptions: AddEventListenerOptions = { capture: true, passive: true };
+	const resizeListenOptions: AddEventListenerOptions = { passive: true };
+	target?.addEventListener("scroll", requestReflow, scrollListenOptions);
+	target?.addEventListener("resize", requestReflow, resizeListenOptions);
+
+	// 元素自身尺寸变化（内容变多/图片加载完成/字体回流）。
+	let resizeObserver: ReflowObserver | undefined;
+	const factory =
+		options.resizeObserverFactory ??
+		(typeof ResizeObserver === "function" ? (callback: () => void) => new ResizeObserver(callback) : undefined);
+	if (factory && options.observe) {
+		try {
+			resizeObserver = factory(requestReflow);
+			resizeObserver.observe(options.observe);
+		} catch {
+			// 观察失败不影响滚动/缩放这两条主路径，静默降级。
+			resizeObserver = undefined;
+		}
+	}
+
+	return {
+		flush(): void {
+			if (!stopped) {
+				options.onReflow();
+			}
+		},
+		stop(): void {
+			if (stopped) {
+				return;
+			}
+			stopped = true;
+			target?.removeEventListener("scroll", requestReflow, scrollListenOptions);
+			target?.removeEventListener("resize", requestReflow, resizeListenOptions);
+			try {
+				resizeObserver?.disconnect();
+			} catch {
+				// 断开失败只可能发生在环境已销毁时，忽略。
+			}
+			resizeObserver = undefined;
+		},
+	};
+}

package/preview/__previewjs_internal__/run-renderer.ts

@@ -1,5 +1,5 @@
 import type { RendererLoader } from "../../src";
-import { publishRuntimeSnapshot } from "./runtime-bridge";
+import { publishRendered, publishRuntimeSnapshot } from "./runtime-bridge";
 import { getState } from "./state";
 
 export async function runRenderer({
@@ -66,9 +66,23 @@ export async function runRenderer({
 	// Publish before reportEvent: custom preview webviews may not install a
 	// __PREVIEWJS_CONTROLLER__, while the runtime bridge is independent.
 	setTimeout(publishRuntimeSnapshot, 0);
+	// **两条通路都要发，它们服务不同的消费者**（勿合并）：
+	//
+	// ① `reportEvent({kind:"rendered"})` → `PreviewController`
+	//    （`engine/iframe/src/index.ts`）用它 `clearExpectRenderTimeout()` 并更新
+	//    `state.rendered`。**不发给它，controller 会在 5 秒后判定「渲染没发生」
+	//    并 `resetIframe()`，造成每 5 秒无限重载 —— 表现为持续白闪 + 反复 rebuild。**
+	//    这条通路依赖父窗口，只在 embedded 有效，但对 embedded 是**必需**的。
+	//
+	// ② `publishRendered()` → runtime-bridge（`cfp-rendered`）→ shell → host
+	//    宿主侧的 `preview/rendered`。这条跨两种渲染面都通用，
+	//    browser 模式只有它能到达宿主。
+	//
+	// 详见 `docs/analysis/preview-event-channels.md`。
 	window.__PREVIEWJS_IFRAME__.reportEvent({
 		kind: "rendered",
 	});
+	publishRendered();
 }
 
 /**

package/preview/__previewjs_internal__/runtime-bridge.ts

@@ -35,6 +35,8 @@ import {
 	setPageOverlay,
 	type PageOverlayPayload,
 } from "./overlay";
+import { type ReflowTracker, trackReflow } from "./reflowTracker";
+import { mergeSelection, pruneDetached, type SelectionSubject, toggleSelection } from "./selectionModel";
 
 export type {
 	RuntimeBounds,
@@ -102,6 +104,13 @@ export function setupRuntimeBridge(): void {
 	initialized = true;
 	// 选中框上的快捷按钮：把「对哪个 runtime 节点做什么」发给宿主执行。
 	setOverlayActionHandler((actionId) => {
+		// 清除选中在**本进程内**就完成，不必绕宿主：
+		// 它没有 runtimeNodeId 可发（宿主那条路会先 reveal 节点，对清除是错的），
+		// 而且清完框立刻消失才是对的反馈。
+		if (actionId === CLEAR_SELECTION_ACTION) {
+			clearSelectedElements();
+			return;
+		}
 		const runtimeNodeId = selectedRuntimeNodeId();
 		if (!runtimeNodeId) {
 			return;
@@ -114,7 +123,10 @@ export function setupRuntimeBridge(): void {
 		} else if (event.data?.kind === "cfp:select-runtime-node") {
 			// 宿主（Runtime Tree 点选）要求把某个节点标成「已选中」：
 			// 面板里选中与预览里的选中框要双向同步。
-			selectRuntimeNodeById(typeof event.data.runtimeNodeId === "string" ? event.data.runtimeNodeId : undefined);
+			selectRuntimeNodeById(
+				typeof event.data.runtimeNodeId === "string" ? event.data.runtimeNodeId : undefined,
+				event.data.additive === true,
+			);
 		} else if (event.data?.kind === "cfp:set-inspect") {
 			inspectScreenshotAvailable = event.data.screenshot === true;
 			setInspectEnabled(Boolean(event.data.enabled));
@@ -139,6 +151,16 @@ export function setupRuntimeBridge(): void {
 	});
 	document.addEventListener("click", handleInspectClick, true);
 	document.addEventListener("mousemove", handleInspectMove, true);
+	// hover 框同理也是视口坐标（见 `reflowTracker.ts` 的说明）。它没有「选中态」
+	// 可以依附，鼠标下一次移动会自然重建，所以滚动时**清掉**即可 ——
+	// 保留它会停在滚动前的位置，比不显示更误导。
+	window.addEventListener(
+		"scroll",
+		() => {
+			clearPageOverlay("inspect");
+		},
+		{ capture: true, passive: true },
+	);
 	document.addEventListener("wheel", blockInspectedInteraction, { capture: true, passive: false });
 	document.addEventListener("keydown", handleInspectKeyDown, true);
 	for (const type of BLOCKED_INPUT_EVENTS) {
@@ -157,6 +179,18 @@ function blockInspectedInteraction(event: Event): void {
 }
 
 function handleInspectKeyDown(event: KeyboardEvent): void {
+	// Esc 清选中**不受 inspect 开关限制**：树点选的框在 inspect 之外也存在，
+	// 用户按 Esc 的意图就是「我不想看这个框了」。放在最前面，且不阻止默认行为 ——
+	// 应用自身可能也用 Esc 关弹窗，我们只清自己的框。
+	if (event.key === "Escape") {
+		if (selectedSubjects.length > 0) {
+			clearSelectedElements();
+			// 控件上的 Esc 可能与「关闭弹窗」等应用行为重叠；不清掉默认行为，
+			// 但要阻止事件继续冒泡到应用的快捷键盘处理器。
+			event.stopPropagation();
+		}
+		return;
+	}
 	if (!inspectEnabled || !SCROLL_KEYS.has(event.key)) {
 		return;
 	}
@@ -170,10 +204,22 @@ function setInspectEnabled(enabled: boolean): void {
 	setPageInteractionShield(enabled);
 	if (!enabled) {
 		clearPageOverlay("inspect");
+		// 只**隐藏**框，不丢弃选中态：
+		// 用户可能刚在树里选了一个节点、还没进 inspect；此时清掉选中，
+		// 进 inspect 后就得重新选一次。选中态归 `selectedSubjects` 管，
+		// 是否显示归 `inspectEnabled` 管 —— 两者正交。
+		//
+		// 同时停掉跟随重算：不显示时每帧算 `getBoundingClientRect` 是白跑。
+		stopSelectedReflow();
 		clearPageOverlay("inspect-selected");
-		selectedElement = undefined;
 		return;
 	}
+	// 进入 inspect：把已有的选中重新画出来（可能是在非 inspect 时从树里选的），
+	// 并恢复跟随重算。
+	if (selectedSubjects.length > 0) {
+		startSelectedReflow();
+		renderSelectedOverlay();
+	}
 	// 键盘焦点可能还留在应用里（tab 聚焦的输入框）：inspect 时不应该继续往里输入。
 	const active = document.activeElement;
 	if (active instanceof HTMLElement && active !== document.body && !isOverlayChrome(active)) {
@@ -182,12 +228,77 @@ function setInspectEnabled(enabled: boolean): void {
 }
 
 /**
- * inspect 的选中态：点选后保留一个实线框，与 hover 的虚线框区分。
+ * 选中态是一个**集合**（支持多选）。
  *
  * 两层 overlay 各自独立（`inspect` / `inspect-selected`），所以 hover 移动时
  * 不会把选中框冲掉。
+ *
+ * ## 为什么是集合而不是单值
+ *
+ * 单值时「多选」需要把状态机整个换掉（`selectedElement` → `selectedElements`），
+ * 是破坏性重构。改成集合后，单选的语义就是「长度 1 的集合」，
+ * 放开多选不需要再动状态容器 —— 渲染层也已经吃 `items[]`（见 `overlay.ts`）。
+ */
+let selectedSubjects: SelectionSubject<Element>[] = [];
+
+/** 边框上「清除选中」按钮的 action id（iframe 内就地处理，不发给宿主）。 */
+const CLEAR_SELECTION_ACTION = "clear-selection";
+
+/**
+ * 选中框的「跟随重算」订阅（`docs/todo/33` 问题 2）。
+ *
+ * 选框用 `position: fixed` + 视口坐标，所以只要选中态还在，就必须跟随
+ * 滚动/缩放/元素尺寸变化重绘 —— 否则框会停在选中那一刻的位置。
+ *
+ * 多选时只 observe 第一个元素作为代表：`ResizeObserver` 的主要作用是补
+ * 「页面重排导致整体位移」这种 `scroll` / `resize` 收不到的情况，
+ * 而这类重排通常由容器引起，观察任何一个成员都能感知到。
+ * 逐个 observe 会让「N 个元素各触发一次」放大成 O(N²) 次重绘。
  */
-let selectedElement: Element | undefined;
+let selectedReflow: ReflowTracker | undefined;
+
+/** 开/关跟随重算；`stopSelectedReflow` 在选中态结束时必须调，否则监听器泄漏。 */
+function startSelectedReflow(): void {
+	stopSelectedReflow();
+	const first = selectedSubjects[0];
+	if (!first) {
+		return;
+	}
+	selectedReflow = trackReflow({
+		onReflow: renderSelectedOverlay,
+		observe: first.element,
+	});
+}
+
+function stopSelectedReflow(): void {
+	selectedReflow?.stop();
+	selectedReflow = undefined;
+}
+
+/**
+ * 选中态的**唯一**写入口。
+ *
+ * `additive` 为 true 时把元素**追加**到现有选中（已存在则不动），
+ * 否则**替换**整个选中集。
+ *
+ * 同时负责重订「跟随重算」—— 集合变化后观察目标也可能变。
+ */
+function setSelectedElements(subjects: SelectionSubject<Element>[], additive = false): void {
+	// 元素可能在选中之后被卸载：顺手剔除，`renderSelectedOverlay` 就不必逐个判 `isConnected`。
+	selectedSubjects = pruneDetached(mergeSelection(selectedSubjects, subjects, additive));
+	if (selectedSubjects.length > 0) {
+		startSelectedReflow();
+	} else {
+		stopSelectedReflow();
+	}
+}
+
+/** 清空选中（连订阅一起停）。 */
+function clearSelectedElements(): void {
+	selectedSubjects = [];
+	stopSelectedReflow();
+	clearPageOverlay("inspect-selected");
+}
 
 function handleInspectClick(event: MouseEvent): void {
 	if (!inspectEnabled) {
@@ -211,77 +322,146 @@ function handleInspectClick(event: MouseEvent): void {
 	const source = element ? getElementSource(element) : undefined;
 	event.preventDefault();
 	event.stopPropagation();
-	selectedElement = element ?? undefined;
+	if (!element) {
+		// 点到页面外/什么都没有：清空（与「点空白取消」的通用直觉一致）。
+		clearSelectedElements();
+		publishToHost({ kind: "cfp-runtime-select", source });
+		return;
+	}
+	// Ctrl/Cmd 点选 = 追加到现有选中（多选）；否则替换。
+	// `metaKey` 覆盖 macOS 的 Cmd，`ctrlKey` 覆盖 Windows/Linux 的 Ctrl。
+	const additive = event.ctrlKey || event.metaKey;
+	if (additive) {
+		// Ctrl/Cmd + 点选：已在集合里则**移除**（开关语义），否则加入。
+		selectedSubjects = pruneDetached(toggleSelection(selectedSubjects, element));
+		if (selectedSubjects.length > 0) {
+			startSelectedReflow();
+		} else {
+			stopSelectedReflow();
+		}
+	} else {
+		setSelectedElements([{ element }]);
+	}
 	renderSelectedOverlay();
 	publishToHost({ kind: "cfp-runtime-select", source });
 }
 
-/** 当前选中元素对应的 runtimeNodeId（宿主执行动作时要用它定位节点）。 */
+/**
+ * 当前选中元素对应的 runtimeNodeId（宿主执行动作时要用它定位节点）。
+ *
+ * 多选时取**第一个**：快捷动作（截图 / 复制 packet）目前都是单元素语义，
+ * 多选下的动作语义（全部截图？并集截图？）尚未定义，先取第一个，
+ * 与 `renderSelectedOverlay` 的 label 一致。
+ */
 function selectedRuntimeNodeId(): string | undefined {
-	if (!selectedElement) {
+	const first = selectedSubjects[0];
+	if (!first) {
 		return undefined;
 	}
 	for (const [id, element] of nodeElements) {
-		if (element === selectedElement) {
+		if (element === first.element) {
 			return id;
 		}
 	}
 	return undefined;
 }
 
-/** 选中框：实线 + 更淡的填充，与 hover 的虚线区分开。 */
+/**
+ * 选中框：多层 `items` 一次画完（多选时一层多个框）。
+ *
+ * 视觉：与 hover **同色（蓝）**，靠**线型**区分 ——
+ * - hover：`dashed`（见 `handleInspectMove`）
+ * - 选中：`solid`
+ *
+ * 为什么不再用橙色：橙色与 hover 蓝并列时信息量重复（两者都在表达「这个元素」），
+ * 而颜色差异对色弱用户无效；线型是更稳的第二通道。
+ * （曾用颜色区分 inspect 点选与树点选，已回退 —— 理由见 `selectionModel.ts` 顶部。）
+ *
+ * 动作按钮只挂在**第一个**框上：动作目前是单元素语义，挂在每个框上
+ * 会让人以为「点哪个按钮就作用于哪个元素」，而实际实现只取第一个。
+ */
 function renderSelectedOverlay(): void {
-	// **不依赖 inspect 模式**：Runtime Tree 点选时通常没开 inspect，
-	// 而「树 → 预览页」的选中框正是那时要显示的。
-	// （早期这里是 `!inspectEnabled` 就清空，导致反向同步永远看不到效果。）
-	if (!selectedElement || !selectedElement.isConnected) {
+	// **只有 inspect 激活时**才在预览里画框（产品决策，2026-11-02）：
+	//
+	// 1. 不激活时，选代码/选树只是「定位到哪段代码」的动作，预览里再画个框会持续干扰，
+	//    尤其用户本来就在读页面的时候。
+	// 2. 框上的按钮（截图 / 复制 / 清除）都依赖 inspect 上下文
+	//    （`inspectScreenshotAvailable` 只在 inspect 时下发），不激活时给了也点不动。
+	//
+	// 选中态本身仍然保留在 `selectedSubjects` 里，进 inspect 就会画出来。
+	if (!inspectEnabled) {
+		stopSelectedReflow();
 		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"/>',
-					},
-				],
-			},
-		],
+	const visible = selectedSubjects.filter((subject) => subject.element.isConnected);
+	if (visible.length === 0) {
+		// 元素全部失联（被卸载/替换）：连订阅一起停掉，
+		// 否则会在后续每帧滚动里白跑一次 `getBoundingClientRect`。
+		if (selectedSubjects.length > 0) {
+			selectedSubjects = [];
+		}
+		stopSelectedReflow();
+		clearPageOverlay("inspect-selected");
+		return;
+	}
+
+	const items = visible.map((subject, index) => {
+		const rect = subject.element.getBoundingClientRect();
+		const fiber = getElementFiberUpward(subject.element);
+		const componentName = getComponentName(fiber);
+		const tag = subject.element.tagName.toLowerCase();
+		const label = componentName ? `${componentName} <${tag}>` : `<${tag}>`;
+		return {
+			x: rect.left,
+			y: rect.top,
+			width: rect.width,
+			height: rect.height,
+			// 与 hover 同色（蓝）：颜色不再承载含义，**线型**区分状态。
+			// 1px 足够：2px 在 iframe 内会显得笨重（实测反馈）。
+			color: "#3794ff",
+			borderWidth: 1,
+			borderStyle: "solid" as const,
+			backgroundAlpha: 0.06,
+			// 多选时给每个框标序号，便于对照「第几个」。
+			label: visible.length > 1 ? `${index + 1}. ${label}` : label,
+			// 两个快捷动作挂在标签右侧：截图当前元素 / 复制 Selection Context Packet。
+			// 截图只在能截的渲染面显示：embedded（iframe）跨域拿不到像素，
+			// 给了按钮也只会失败，所以直接不渲染。
+			actions:
+				index !== 0
+					? []
+					: [
+							...(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"/>',
+							},
+							// 「清除」按钮：树面板没有清除动作，不在这里给入口，
+							// 用户就只能靠点空白或再点别的元素来清掉。
+							{
+								id: CLEAR_SELECTION_ACTION,
+								title: "Clear selection",
+								// 叉号：两条对角线，描边 1.4 在 12px 下仍清晰。
+								iconMarkup: '<path d="M4 4l8 8M12 4l-8 8"/>',
+							},
+						],
+		};
 	});
+
+	setPageOverlay("inspect-selected", { visible: true, items });
 }
 
 /**
@@ -290,10 +470,9 @@ function renderSelectedOverlay(): void {
  * 通过 `cfp:runtime-detail` 之外的消息传不进来，所以用 `Runtime.evaluate`
  * 直接调这个全局钩子（浏览器模式）/ postMessage（embedded 模式）。
  */
-function selectRuntimeNodeById(runtimeNodeId: string | undefined): void {
+function selectRuntimeNodeById(runtimeNodeId: string | undefined, additive = false): void {
 	if (!runtimeNodeId) {
-		selectedElement = undefined;
-		clearPageOverlay("inspect-selected");
+		clearSelectedElements();
 		return;
 	}
 	const element = nodeElements.get(runtimeNodeId);
@@ -301,9 +480,16 @@ function selectRuntimeNodeById(runtimeNodeId: string | undefined): void {
 		// 树里的节点可能不在当前 DOM（未渲染的分支）——静默，不清掉已有选中。
 		return;
 	}
-	selectedElement = element;
+	setSelectedElements([{ element }], additive);
 	// 元素可能不在视口内：先滚动到可见位置，再按最终位置画框。
-	element.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+	//
+	// 两个闸门：
+	// - 追加模式下不滚动 —— 用户正按着 ctrl 连续点选，页面跳动会让人点偏。
+	// - 非 inspect 时不滚动 —— 那条路只同步代码/树，不该把预览页拽走
+	//   （框本来也不显示，滚过去毫无意义）。
+	if (!additive && inspectEnabled) {
+		element.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+	}
 	renderSelectedOverlay();
 }
 
@@ -332,7 +518,7 @@ function handleInspectMove(event: MouseEvent): void {
 				width: rect.width,
 				height: rect.height,
 				label,
-				// hover 用虚线：与点选后的实线区分，避免「哪个是当前选中」看不出来。
+				// hover 用虚线、选中用实线：两者同色（蓝），靠线型区分状态。
 				borderStyle: "dashed",
 			},
 		],
@@ -357,6 +543,31 @@ function elementUnderPointer(clientX: number, clientY: number): Element | undefi
 	return fallback && !isOverlayChrome(fallback) ? fallback : undefined;
 }
 
+/**
+ * 上报「组件渲染完成」（`docs/analysis/preview-event-channels.md` §7）。
+ *
+ * ## 为什么走 runtime-bridge 而不是 `__PREVIEWJS_IFRAME__.reportEvent`
+ *
+ * `reportEvent` 那条通路（`__PREVIEWJS_CONTROLLER__` / `parent.postMessage`）
+ * **只在 embedded 可用** —— 它依赖父窗口，而 browser 模式的预览页是顶层窗口
+ * （`window.parent === window`），两条子路都断。
+ *
+ * runtime-bridge 是**唯一跨两种模式都存在的桥**：
+ * - browser：走 `__cfpBridge`（CDP `Runtime.addBinding` 注入的反向通道）
+ * - embedded：走 `parent.postMessage`
+ *
+ * ## 语义边界
+ *
+ * 只表示「组件已挂载且没抛错」，**不保证布局稳定**（异步数据 / 图片 / 字体可能未就绪）。
+ * 需要布局稳定的场合由消费方自己等，不要在这一层加 settled 猜测。
+ */
+export function publishRendered(): void {
+	if (typeof window === "undefined") {
+		return;
+	}
+	publishToHost({ kind: "cfp-rendered" });
+}
+
 export function publishRuntimeSnapshot(): void {
 	if (typeof window === "undefined") {
 		return;
@@ -431,11 +642,30 @@ function collectRuntimeSnapshot(): RuntimeSnapshot {
 	};
 }
 
+/**
+ * 渲染错误面板的标记属性（`docs/todo/39`）。
+ *
+ * 与 `@cfp-studio/analyzer-api` 的 `ERROR_PANEL_ATTRIBUTE` 保持一致。
+ * 面板是**预览工具自己画的内容**，不是被预览组件的一部分 ——
+ * 不排除的话它会作为普通 DOM 出现在 Runtime Tree 里，还会参与点击选框命中。
+ */
+const ERROR_PANEL_ATTRIBUTE = "data-preview-error-panel";
+
+/** 该元素是否是预览工具自己的错误面板。 */
+function isErrorPanel(element: Element): boolean {
+	return element.hasAttribute?.(ERROR_PANEL_ATTRIBUTE) ?? false;
+}
+
 function walk(element: Element | null, parentId: string | undefined, path: string, nodes: RuntimeNode[]): boolean {
 	if (!element || nodes.length >= MAX_NODES) {
 		return nodes.length >= MAX_NODES;
 	}
 
+	if (isErrorPanel(element)) {
+		// 跳过面板自身与它的子树，但不计为截断。
+		return false;
+	}
+
 	const fiber = getElementFiberUpward(element);
 	const source = getSourceLocation(fiber);
 	// Path-based ID: stable across snapshots as long as the DOM structure is

package/preview/__previewjs_internal__/selectionModel.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { mergeSelection, pruneDetached, type SelectionSubject, toggleSelection } from "./selectionModel";
+
+/**
+ * 多选选中态的纯逻辑测试。
+ *
+ * 风险集中在三处，所以用例也围绕它们：
+ * 1. `additive` 的追加/替换语义（Ctrl 点选靠它）
+ * 2. 开关语义（重复 Ctrl 点同一元素应移除）
+ * 3. 失联元素的剔除（否则框会画到看不见的位置，重绘也白跑）
+ *
+ * 注：曾在此测试「来源 → 视觉编码」（两色方案），已随该方案回退删除。
+ * 见 `selectionModel.ts` 顶部关于为何不编码来源的说明。
+ */
+
+function element(name: string, connected = true) {
+	return { name, isConnected: connected };
+}
+
+function subject(name: string): SelectionSubject<ReturnType<typeof element>> {
+	return { element: element(name) };
+}
+
+describe("mergeSelection", () => {
+	it("additive = false 时替换整个集合", () => {
+		const next = mergeSelection([subject("a")], [subject("b")], false);
+		expect(next.map((s) => s.element.name)).toEqual(["b"]);
+	});
+
+	it("additive = true 时追加", () => {
+		const next = mergeSelection([subject("a")], [subject("b")], true);
+		expect(next.map((s) => s.element.name)).toEqual(["a", "b"]);
+	});
+
+	it("additive = true 时不重复加入同一元素", () => {
+		const a = subject("a");
+		expect(mergeSelection([a], [a], true)).toHaveLength(1);
+	});
+
+	it("不修改入参数组（纯函数）", () => {
+		const current = [subject("a")];
+		mergeSelection(current, [subject("b")], true);
+		expect(current).toHaveLength(1);
+	});
+});
+
+describe("toggleSelection", () => {
+	it("未选中时加入", () => {
+		const el = element("a");
+		const next = toggleSelection([], el);
+		expect(next).toHaveLength(1);
+		expect(next[0]!.element).toBe(el);
+	});
+
+	it("已选中时移除（重复 Ctrl 点选 = 取消）", () => {
+		const el = element("a");
+		expect(toggleSelection([{ element: el }], el)).toHaveLength(0);
+	});
+
+	it("不误伤其它元素", () => {
+		const a = element("a");
+		const b = element("b");
+		const next = toggleSelection([{ element: a }, { element: b }], a);
+		expect(next.map((s) => s.element.name)).toEqual(["b"]);
+	});
+});
+
+describe("pruneDetached", () => {
+	it("剔除脱离文档的元素", () => {
+		const alive = { element: element("a", true) };
+		const dead = { element: element("b", false) };
+		expect(pruneDetached([alive, dead])).toEqual([alive]);
+	});
+
+	it("全都在时内容不变", () => {
+		expect(pruneDetached([{ element: element("a", true) }])).toHaveLength(1);
+	});
+});

package/preview/__previewjs_internal__/selectionModel.ts

@@ -0,0 +1,84 @@
+/**
+ * 预览选中态的**纯逻辑**（多选集合运算）。
+ *
+ * ## 为什么抽出来
+ *
+ * `runtime-bridge.ts` 顶层就依赖 `window` / `document`，无法在单测环境加载。
+ * 而「多选」的核心风险全在集合运算上：`additive` 语义、重复点击的开关行为、
+ * 元素卸载后的剔除。这些都是纯函数，抽出来就能测，不必搭 DOM。
+ *
+ * `runtime-bridge` 只负责「收集元素 → 调这里 → 画图」。
+ *
+ * ## 为什么没有「来源」概念
+ *
+ * 曾经用 `origin`（inspect / runtime-tree）区分框的颜色，**已回退**。理由：
+ *
+ * 1. 颜色编码的是系统内部的来源分类，不是用户需要区分的任务 ——
+ *    用户只知道「我点了这个元素」，不知道也不需要知道它从哪条链路进来。
+ * 2. 它引入了环形回授问题：inspect 点选 → 宿主 revealRuntimeNode → 树回发
+ *    `select-runtime-node` → 框被重新绘制成另一种颜色。每个同步点都要判断
+ *    「这次该不该覆盖」，复杂度远超收益。
+ * 3. 退出 inspect 时需要按来源分流（清橙留蓝），让一个简单动作有了条件分支。
+ *
+ * 如果将来确实需要表达「这个框是怎么来的」，用**标签前缀**（文字）比颜色便宜得多，
+ * 且不受环形回授影响、对色弱用户友好。详见 `docs/todo/33`。
+ */
+
+/** 选中集合的一个成员。 */
+export interface SelectionSubject<E> {
+	element: E;
+}
+
+/**
+ * 合并选中集合。
+ *
+ * @param current 现有集合（不会被修改，返回新数组）
+ * @param incoming 新加入的成员
+ * @param additive `true` = 追加（已在集合里的元素不重复加）；`false` = 替换整个集合
+ */
+export function mergeSelection<E>(
+	current: ReadonlyArray<SelectionSubject<E>>,
+	incoming: ReadonlyArray<SelectionSubject<E>>,
+	additive: boolean,
+): Array<SelectionSubject<E>> {
+	// 替换模式：直接以传入的为准。
+	if (!additive) {
+		return [...incoming];
+	}
+	const merged = [...current];
+	for (const subject of incoming) {
+		if (!merged.some((existing) => existing.element === subject.element)) {
+			merged.push(subject);
+		}
+	}
+	return merged;
+}
+
+/**
+ * `additive` 语义下的**开关**：元素已在集合中则移除，否则加入。
+ *
+ * 这是 Ctrl/Cmd + 点选的行为：反复点同一个元素应当来回切换，
+ * 而不是（像单纯 `additive` 追加那样）无论点多少次都只有「加」。
+ */
+export function toggleSelection<E>(
+	current: ReadonlyArray<SelectionSubject<E>>,
+	element: E,
+): Array<SelectionSubject<E>> {
+	const exists = current.some((subject) => subject.element === element);
+	if (exists) {
+		return current.filter((subject) => subject.element !== element);
+	}
+	return [...current, { element }];
+}
+
+/**
+ * 剔除已脱离文档的元素（被卸载/替换）。
+ *
+ * 不剔的话会有两个问题：框会画到看不见的位置；`ResizeObserver` 一直挂着一个
+ * 已不在 DOM 的节点，重算就是白跑。
+ */
+export function pruneDetached<E extends { isConnected: boolean }>(
+	subjects: ReadonlyArray<SelectionSubject<E>>,
+): Array<SelectionSubject<E>> {
+	return subjects.filter((subject) => subject.element.isConnected);
+}

package/preview/index.html

@@ -13,6 +13,8 @@
 				// 初始化 lastRenderFailed 为 false，表示初始渲染未失败
 				lastRenderFailed: false,
 				toggleInspect: false,
+				/** 编译期兜底上报开关：`logs.ts` 接管后置 false（见 `docs/todo/39`）。 */
+				startupErrorGuard: true,
 				/**
 				 * 报告预览事件
 				 * @param {Object} event - 事件对象
@@ -56,6 +58,47 @@
 			window.__PREVIEWJS_IFRAME__.reportEvent({
 				kind: "bootstrapping",
 			});
+
+			/**
+			 * 编译期错误的兜底上报（`docs/todo/39`）。
+			 *
+			 * **为什么必须放在这里**：Vite 的模块图加载失败（例如 `.less` 缺 `less` 包、
+			 * `react-dom` 未安装）发生在**任何业务 JS 执行之前** —— `__previewjs_internal__/logs.ts`
+			 * 里那套 `window.onerror` 自己也靠模块加载才能注册，救不了更早的失败。
+			 * 结果就是「白屏 + 零报错」，用户无从下手。
+			 *
+			 * 这里是内联脚本，一定先于模块执行，所以能接住那些“还没进入应用就崩”的错误。
+			 * 模块加载成功后，`logs.ts` 会把这两个钩子**覆盖**成更完整的版本（带格式化与
+			 * `vite:error` 分流），这属于预期叠加：本处只要求“不静默”。
+			 */
+			const reportStartupError = (raw) => {
+				// `logs.ts` 加载成功后会把这个开关关掉（它有更完整的格式化与 vite:error 分流），
+				// 避免同一个错误被上报两次。
+				if (!window.__PREVIEWJS_IFRAME__.startupErrorGuard) {
+					return;
+				}
+				const text = raw instanceof Error ? raw.stack || raw.message : String(raw);
+				window.__PREVIEWJS_IFRAME__.reportEvent({
+					kind: "error",
+					source: "vite",
+					message: text,
+				});
+			};
+
+			window.addEventListener("error", (event) => {
+				// 只接模块脚本 / 资源加载失败，其它错误交给 logs.ts 的版本。
+				if (event.target && event.target !== window && event.target.tagName) {
+					reportStartupError(`Failed to load ${event.target.tagName.toLowerCase()}: ${event.target.src || event.target.href || ""}`);
+					return;
+				}
+				if (event.error || event.message) {
+					reportStartupError(event.error || event.message);
+				}
+			}, true);
+
+			window.addEventListener("unhandledrejection", (event) => {
+				reportStartupError(event.reason);
+			});
 		</script>
 		<!-- %OPTIONAL_HEAD_CONTENT% -->
 		<style>