@cfp-studio/iframe 18.4.3 → 18.4.5

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-//#region ../../../../node_modules/.pnpm/vite@6.4.5_@types+node@24.19.2_jiti@2.7.0_less@4.2.2_lightningcss@1.30.2_sass@1.85.1_terser@5.40.0_tsx@4.19.3_yaml@2.7.0/node_modules/vite/types/hmrPayload.d.ts
+//#region ../../../../node_modules/.pnpm/vite@6.4.5_@types+node@24.1_13c54df9746541450cb8a36e10ae9cdd/node_modules/vite/types/hmrPayload.d.ts
 interface UpdatePayload {
   type: 'update';
   updates: Update[];
@@ -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.3",
+  "version": "18.4.5",
   "license": "MIT",
   "files": [
     "dist",
@@ -10,6 +10,7 @@
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "dependencies": {
+    "@cfp-studio/analyzer-api": "0.1.15",
     "@cfp-studio/fiber-reader": "0.3.0"
   },
   "devDependencies": {

package/preview/__previewjs_internal__/index.ts

@@ -1,3 +1,5 @@
+import { clearErrorPanel } from "@cfp-studio/analyzer-api";
+
 import { overrideCopyCutPaste } from "./copy-cut-paste";
 import { setUpLinkInterception } from "./links";
 import { setUpLogInterception } from "./logs";
@@ -67,11 +69,20 @@ export function initPreview({
 				shouldAbortRender: () => renderId !== thisRenderId,
 				loadRenderer,
 			});
+			// 渲染成功：上一次的错误覆盖层该撤了。
+			//
+			// 面板现在挂在 `document.body` 的独立覆盖层上（不占 `#root`），所以不会被
+			// `root.innerHTML` 覆写带走 —— 必须显式清 —— 否则改好代码后面板会永久赖着。
+			clearErrorPanel();
 		} catch (error: any) {
-			if (root.innerHTML !== rootHtml) {
-				// 重新调用前一次渲染，以确保预览不会白屏。
-				root.innerHTML = rootHtml;
-			}
+			// **不再 `root.innerHTML = rootHtml` 回填快照**。
+			//
+			// 旧行为（为了「不白屏」而回滚）实测症状：「错误面板闪现一下，然后被正常页面
+			// 覆盖」，用户看不到真正原因。现在改成：保留错误覆盖层（半透明遮罩盖住旧画面），
+			// 同时继续 `reportEvent` 给宿主侧。
+			//
+			// `rootHtml` 仍用于判定：没变化说明连上一次的 DOM 都没建立，无需特别处理。
+			void rootHtml;
 			window.__PREVIEWJS_IFRAME__.reportEvent({
 				kind: "error",
 				source: "renderer",

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__/runtime-bridge.ts

@@ -642,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__/vite-hmr-listener.ts

@@ -46,7 +46,15 @@ export function setupViteHmrListener() {
 			isFirstUpdate = false;
 		}
 		if (window.__PREVIEWJS_IFRAME__.lastRenderFailed) {
-			window.location.reload();
+			// **不要 `location.reload()`**。
+			//
+			// 旧行为：上一次渲染失败时整页重载。实测症状（真实反馈）：
+			// 「保存后闪现错误页面，然后被白屏覆盖」—— 错误面板刚画出来就被重载抹了，
+			// 重载后 `runNewRender` 又在 `loadRenderer` 阶段抛错，用户什么都看不到。
+			//
+			// 现在：面板是独立覆盖层（见 `analyzer-api` 的 `renderErrorPanel`），
+			// 只要重新渲染就行 —— 成功时 `runNewRender` 会自己 `clearErrorPanel()`。
+			window.__PREVIEWJS_IFRAME__.refresh({ refetchPreviewableModule: true });
 		} else {
 			window.__PREVIEWJS_IFRAME__.reportEvent({
 				kind: "vite-before-update",

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>