@dp-bohrium/widget-sdk 0.8.0 → 0.10.0

package/assets/toolchain.json

@@ -1,15 +1,15 @@
 {
   "formatVersion": 3,
   "packageName": "@dp-bohrium/widget-sdk",
-  "cli": "0.8.0",
+  "cli": "0.10.0",
   "profile": {
-    "id": "widget-sdk-0.8.0",
-    "sdk": "0.8.0"
+    "id": "widget-sdk-0.10.0",
+    "sdk": "0.10.0"
   },
   "protocol": {
     "schemaVersion": 1,
     "hostApiVersion": 1,
-    "digest": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb"
+    "digest": "sha256:00ae6aba78a5103a2e5318ecafd769a03d02048168cd73e4bea3d87e0f80366d"
   },
   "hostAcceptance": "unknown",
   "documentation": {
@@ -20,9 +20,9 @@
     "llms": "https://dev.dp.tech/bohrium-widget-sdk/llms.txt"
   },
   "digests": {
-    "compiler": "sha256:92822832e958aa5448312194de3d1d4e8515721be2862d978abaefe2143c9c71",
-    "validators": "sha256:47f6793e099e0b4c56da28f42e6ea0c79aecd9cc8915e1746fbd24f999bf05d9",
-    "schemas": "sha256:ee3023e337559bbf83c096365fe1eb49ce6809a880a5e5d65e2a2f6fd53a7ddb",
-    "templates": "sha256:87cf4085fb2769b1b874e9f331258c024f5826c31d0937a6e046b5511b5567c9"
+    "compiler": "sha256:b8ca913544930c6431fcccd04180fd7cf413366f719a89fdf973eb00bfe1495a",
+    "validators": "sha256:3229f4c649cd0ef27e0886a8037dc9f9ebf4e4e391c9c010738a915bf2704cec",
+    "schemas": "sha256:00ae6aba78a5103a2e5318ecafd769a03d02048168cd73e4bea3d87e0f80366d",
+    "templates": "sha256:85be81d7ede0a1631c08a464ce7857ffcce71691bb8d75717d97513c6496a8e5"
   }
 }

package/conformance/development-diagnostics.json

@@ -0,0 +1,128 @@
+[
+  {
+    "name": "valid-render-diagnostic",
+    "contract": "WidgetDevelopmentDiagnostic",
+    "valid": true,
+    "value": {
+      "schemaVersion": 1,
+      "source": "sdk",
+      "code": "RENDER_FAILED",
+      "phase": "render",
+      "operation": "render",
+      "severity": "request-error",
+      "message": "Widget render handler failed",
+      "retryable": false,
+      "correlationId": "render-fixture",
+      "diagnostics": [
+        {
+          "file": "src/widget.ts",
+          "line": 8,
+          "column": 3
+        }
+      ]
+    }
+  },
+  {
+    "name": "invalid-guest-command",
+    "contract": "WidgetDevelopmentDiagnostic",
+    "valid": false,
+    "value": {
+      "schemaVersion": 1,
+      "source": "sdk",
+      "code": "RENDER_FAILED",
+      "phase": "render",
+      "operation": "render",
+      "severity": "request-error",
+      "message": "Widget render handler failed",
+      "retryable": false,
+      "correlationId": "render-fixture",
+      "diagnostics": [
+        {
+          "file": "src/widget.ts",
+          "line": 8,
+          "column": 3
+        }
+      ],
+      "command": "unsafe"
+    }
+  },
+  {
+    "name": "invalid-absolute-source",
+    "contract": "WidgetDevelopmentDiagnostic",
+    "valid": false,
+    "value": {
+      "schemaVersion": 1,
+      "source": "sdk",
+      "code": "RENDER_FAILED",
+      "phase": "render",
+      "operation": "render",
+      "severity": "request-error",
+      "message": "Widget render handler failed",
+      "retryable": false,
+      "correlationId": "render-fixture",
+      "diagnostics": [
+        {
+          "file": "/private/source.ts",
+          "line": 1,
+          "column": 1
+        }
+      ]
+    }
+  },
+  {
+    "name": "valid-offer",
+    "contract": "WidgetDevelopmentOffer",
+    "valid": true,
+    "value": {
+      "type": "widget-bootstrap-offer",
+      "protocolVersion": 1,
+      "extensions": [
+        "development-diagnostics-v1"
+      ]
+    }
+  },
+  {
+    "name": "invalid-duplicate-extension",
+    "contract": "WidgetDevelopmentOffer",
+    "valid": false,
+    "value": {
+      "type": "widget-bootstrap-offer",
+      "protocolVersion": 1,
+      "extensions": [
+        "development-diagnostics-v1",
+        "development-diagnostics-v1"
+      ]
+    }
+  },
+  {
+    "name": "valid-handled-result",
+    "contract": "WidgetRenderResult",
+    "valid": true,
+    "value": {
+      "requestId": "render-fixture",
+      "revision": 1,
+      "outcome": "handled"
+    }
+  },
+  {
+    "name": "invalid-failure-without-diagnostic",
+    "contract": "WidgetRenderResult",
+    "valid": false,
+    "value": {
+      "requestId": "render-fixture",
+      "revision": 1,
+      "outcome": "failed"
+    }
+  },
+  {
+    "name": "invalid-visual-claim",
+    "contract": "WidgetRenderResult",
+    "valid": false,
+    "value": {
+      "requestId": "render-fixture",
+      "revision": 1,
+      "outcome": "handled",
+      "visualVerified": true
+    }
+  }
+]

package/dist/cli.mjs

@@ -1,13 +1,123 @@
 #!/usr/bin/env node
-import { a as normalizeArchivePath, c as compileAuthorManifest, i as prepareWidgetPackage, n as scaffoldDshWidget, o as checkWidgetProject, s as resolveWidgetProjects, t as auditDshPlugin } from "./dsh-BlpXm2Bv.mjs";
+import { a as normalizeArchivePath, c as loadContractValidators, i as prepareWidgetPackage, l as compileAuthorManifest, n as scaffoldDshWidget, o as checkWidgetProject, s as resolveWidgetProjects, t as auditDshPlugin } from "./dsh-BJWUB8Nq.mjs";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
-import { constants, existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
+import { constants, existsSync, fstatSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
 import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import { createServer } from "node:http";
 import { isDeepStrictEqual } from "node:util";
+//#region ../../scripts/widget/widget-development-observations.mjs
+const JOURNAL_CAPACITY = 32;
+const ATTEMPT_CAPACITY = 32;
+const ID_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/u;
+const exact = (value, keys) => value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+/** 每个 SDK 开发会话独占；只有受保护的 Host control 能写入。 */
+async function createDevelopmentObservations() {
+	const { validateWidgetDevelopmentDiagnostic, createWidgetRecoveryPlan, isWidgetRenderResult } = await loadContractValidators();
+	let cursor = 0;
+	let current = {
+		state: "unknown",
+		cursor
+	};
+	const attempts = /* @__PURE__ */ new Map();
+	const entries = [];
+	let previousFailure;
+	return {
+		snapshot(includeEntries = true) {
+			return structuredClone({
+				...current,
+				cursor,
+				oldestCursor: entries[0]?.cursor ?? cursor,
+				...includeEntries ? { entries } : {}
+			});
+		},
+		reset(generation) {
+			attempts.clear();
+			current = {
+				state: "unknown",
+				generation,
+				cursor
+			};
+		},
+		accept(input, generation) {
+			if (!exact(input, [
+				"generation",
+				"attemptId",
+				"instanceId",
+				"sequence",
+				"event"
+			]) || input.generation !== generation || typeof input.attemptId !== "string" || !ID_PATTERN.test(input.attemptId) || !(typeof input.instanceId === "string" && /^[a-zA-Z0-9_.:%-]{1,1024}$/u.test(input.instanceId)) || !Number.isSafeInteger(input.sequence) || input.sequence < 1) throw new Error("invalid observation identity");
+			const event = input.event;
+			const connected = exact(event, ["type", "supported"]) && event.type === "connected" && typeof event.supported === "boolean";
+			const diagnostic = exact(event, ["type", "diagnostic"]) && event.type === "diagnostic" && validateWidgetDevelopmentDiagnostic(event.diagnostic).ok;
+			const result = exact(event, ["type", "result"]) && event.type === "render-result" && isWidgetRenderResult(event.result);
+			if (!connected && !diagnostic && !result) throw new Error("invalid observation contract");
+			const known = attempts.get(input.attemptId);
+			if (known && (known.instanceId !== input.instanceId || input.sequence <= known.sequence)) throw new Error("stale observation");
+			if (!connected && (current.attemptId !== input.attemptId || !known)) throw new Error("inactive observation attempt");
+			if (!connected && !known.supported && (result || event.diagnostic.source === "sdk")) throw new Error("development extension was not negotiated");
+			if (connected && (known || attempts.size >= ATTEMPT_CAPACITY)) throw new Error("reused or excessive observation attempt");
+			attempts.set(input.attemptId, {
+				instanceId: input.instanceId,
+				sequence: input.sequence,
+				supported: connected ? event.supported : known.supported
+			});
+			if (connected) current = {
+				state: event.supported ? "connected" : "unsupported",
+				generation,
+				attemptId: input.attemptId,
+				instanceId: input.instanceId
+			};
+			const failure = diagnostic ? event.diagnostic : result && event.result.outcome === "failed" ? event.result.diagnostic : void 0;
+			if (failure) {
+				const fingerprint = JSON.stringify([
+					failure.source,
+					failure.code,
+					failure.phase,
+					failure.operation,
+					failure.diagnostics
+				]);
+				const repeated = previousFailure?.fingerprint === fingerprint && previousFailure.generation === generation;
+				const recovery = createWidgetRecoveryPlan(failure, {
+					executionState: "finished",
+					mayHaveExecuted: true,
+					progress: {
+						repeated,
+						hasNewEvidence: !repeated
+					}
+				});
+				previousFailure = {
+					fingerprint,
+					generation
+				};
+				current = {
+					...current,
+					state: "failed",
+					diagnostic: failure,
+					recovery,
+					renderResult: result ? event.result : void 0
+				};
+			} else if (result && event.result.outcome === "handled") {
+				const { diagnostic: _diagnostic, recovery: _recovery, ...identity } = current;
+				current = {
+					...identity,
+					state: "handled",
+					renderResult: event.result
+				};
+			}
+			const entry = {
+				cursor: ++cursor,
+				...input
+			};
+			entries.push(entry);
+			if (entries.length > JOURNAL_CAPACITY) entries.shift();
+			return this.snapshot(false);
+		}
+	};
+}
+//#endregion
 //#region ../../scripts/widget/widget-dev.mjs
 const repoRoot = resolve(fileURLToPath(new URL("../..", import.meta.url)));
 const DEFAULT_PORT = 4300;
@@ -105,6 +215,7 @@ function usage$1() {
   --watch             监听 src、manifest.json 和 package.json，变化后重新 build
   --no-build          使用现有的 manifest.widgetConfig.entry，不执行 build
   --port <port>       固定 Profile 服务端口（默认 ${DEFAULT_PORT}）
+  --listen-fd <fd>    接管宿主已监听的 IPv4 loopback TCP socket；仅与 --no-build 一起使用
   --help              显示帮助
 
 开发流程：
@@ -116,6 +227,7 @@ function usage$1() {
 }
 function parseArgs(argv) {
 	const positional = [];
+	let portSpecified = false;
 	const options = {
 		open: false,
 		watch: false,
@@ -160,10 +272,17 @@ function parseArgs(argv) {
 			const value = Number(argv[++index]);
 			if (!Number.isInteger(value) || value < 1024 || value > 65535) throw new Error("--port 必须是 1024 到 65535 之间的整数");
 			options.port = value;
+			portSpecified = true;
+		} else if (argument === "--listen-fd") {
+			const value = argv[++index];
+			const fd = Number(value);
+			if (!/^\d+$/u.test(value) || fd < 3 || fd > 2 ** 31 - 1) throw new Error("--listen-fd 需要宿主传入的文件描述符（fd ≥ 3）");
+			options.listenFd = fd;
 		} else if (argument.startsWith("-")) throw new Error(`未知选项：${argument}`);
 		else positional.push(argument);
 	}
 	if (positional.length !== 1) throw new Error("需要一个 Widget 工程目录或 manifest.json");
+	if (options.listenFd !== void 0 && (portSpecified || options.build || options.watch)) throw new Error("--listen-fd 必须与 --no-build 一起使用，不能与 --port 或 --watch 同用");
 	return {
 		help: false,
 		project: positional[0],
@@ -721,6 +840,28 @@ function runBuild(projectRoot, { capture = false } = {}) {
 		});
 	});
 }
+async function listenForDevelopment(server, { port, listenFd }) {
+	if (listenFd !== void 0 && !fstatSync(listenFd).isSocket()) throw new Error("--listen-fd 需要宿主传入已监听的 127.0.0.1 TCP socket");
+	await new Promise((resolveListen, rejectListen) => {
+		server.once("error", rejectListen);
+		const onListen = () => {
+			server.off("error", rejectListen);
+			resolveListen();
+		};
+		if (listenFd === void 0) server.listen(port, "127.0.0.1", onListen);
+		else server.listen({
+			fd: listenFd,
+			exclusive: true
+		}, onListen);
+	});
+	const address = server.address();
+	if (address?.family !== "IPv4" || address.address !== "127.0.0.1" || !address.port) {
+		server.close();
+		server.closeAllConnections();
+		throw new Error("--listen-fd 需要宿主传入已监听的 127.0.0.1 TCP socket");
+	}
+	return `http://${address.address}:${address.port}`;
+}
 async function startWidgetDevelopment(projectRoot, options) {
 	const buildProject = options.buildProject ?? runBuild;
 	const emit = options.emit ?? ((line, error = false) => error ? console.error(line) : console.log(line));
@@ -761,6 +902,8 @@ async function startWidgetDevelopment(projectRoot, options) {
 		},
 		lastBuildError: null
 	};
+	const observations = await createDevelopmentObservations();
+	observations.reset(state.generation);
 	const eventClients = /* @__PURE__ */ new Map();
 	let eventId = 0;
 	let session;
@@ -783,7 +926,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		}
 	});
 	const developmentSnapshot = () => {
-		const origin = `http://127.0.0.1:${server.address().port}`;
+		const { origin } = session.descriptor;
 		const development = panelDevelopmentDescriptor(successfulGeneration, `${origin}${V1_PROFILE_PATH}`, `${origin}${V1_STATUS_PATH}`);
 		return {
 			protocolVersion: 1,
@@ -798,7 +941,8 @@ async function startWidgetDevelopment(projectRoot, options) {
 			assets: successfulGeneration.assets,
 			watch: state.watch,
 			lastBuild: state.lastBuild,
-			lastBuildError: state.lastBuildError
+			lastBuildError: state.lastBuildError,
+			runtime: observations.snapshot()
 		};
 	};
 	const generationReadyData = () => {
@@ -813,6 +957,10 @@ async function startWidgetDevelopment(projectRoot, options) {
 		};
 	};
 	const server = createServer((request, response) => {
+		if (!session) {
+			response.destroy();
+			return;
+		}
 		const url = new URL(request.url ?? "/", "http://127.0.0.1");
 		if (request.method === "OPTIONS") {
 			response.writeHead(405, secureHeaders("text/plain; charset=utf-8")).end();
@@ -877,8 +1025,30 @@ async function startWidgetDevelopment(projectRoot, options) {
 			request.on("end", () => {
 				try {
 					const control = JSON.parse(body || "{}");
-					if (control.protocolVersion !== 1 || !["reload", "disconnect"].includes(control.action)) throw new Error("invalid control action");
-					if (control.action === "disconnect") {
+					if (control.protocolVersion !== 1 || ![
+						"reload",
+						"disconnect",
+						"report-runtime",
+						"refresh-built-output"
+					].includes(control.action)) throw new Error("invalid control action");
+					if (control.action === "report-runtime") {
+						json$1(response, 200, {
+							ok: true,
+							protocolVersion: 1,
+							runtime: observations.accept(control.observation, state.generation)
+						});
+						return;
+					}
+					if (control.action === "refresh-built-output") {
+						const candidate = createDevelopmentGeneration(projectRoot, successfulGeneration.number + 1, GENERATION_LIMITS, options.manifestOptions);
+						successfulGeneration = candidate;
+						retainedGenerations.set(candidate.guestCapability, candidate);
+						while (retainedGenerations.size > RETAINED_GENERATIONS) retainedGenerations.delete(retainedGenerations.keys().next().value);
+						state.generation = candidate.number;
+						observations.reset(candidate.number);
+						state.lastBuildError = null;
+						sendEvent("generation-ready", generationReadyData());
+					} else if (control.action === "disconnect") {
 						sendEvent("disconnected", { reason: "host-request" });
 						session.disconnect();
 					} else sendEvent("reload-requested", { generation: state.generation });
@@ -915,7 +1085,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 				});
 				return;
 			}
-			const origin = `http://127.0.0.1:${server.address().port}`;
+			const { origin } = session.descriptor;
 			const launchUrl = `${origin}${guestGenerationRoot(successfulGeneration)}/launch.html`;
 			json$1(response, 200, createDevelopmentConfig({
 				manifest: successfulGeneration.manifest,
@@ -928,7 +1098,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		}
 		if (url.pathname === PROFILE_PATH) {
 			const runId = url.searchParams.get("runId") || "widget-dev-run";
-			const origin = `http://127.0.0.1:${server.address().port}`;
+			const { origin } = session.descriptor;
 			json$1(response, 200, createDevelopmentConfig({
 				manifest: successfulGeneration.manifest,
 				runId,
@@ -987,11 +1157,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 		}
 		serveGenerationAsset(successfulGeneration, assetPath, response);
 	});
-	await new Promise((resolveListen, rejectListen) => {
-		server.once("error", rejectListen);
-		server.listen(options.port, "127.0.0.1", resolveListen);
-	});
-	const origin = `http://127.0.0.1:${server.address().port}`;
+	const origin = await listenForDevelopment(server, options);
 	session = createWidgetDevelopmentSession({ origin });
 	const profileUrl = `${origin}${PROFILE_PATH}`;
 	const descriptorUrl = `${origin}${DESCRIPTOR_PATH}`;
@@ -1054,6 +1220,7 @@ async function startWidgetDevelopment(projectRoot, options) {
 			retainedGenerations.set(candidate.guestCapability, candidate);
 			while (retainedGenerations.size > RETAINED_GENERATIONS) retainedGenerations.delete(retainedGenerations.keys().next().value);
 			state.generation = candidate.number;
+			observations.reset(candidate.number);
 			state.lastBuild = {
 				ok: true,
 				digest: candidate.digest,
@@ -1315,6 +1482,7 @@ function commandTopics(context) {
 				"--open                      连接或唤起 Widget 开发宿主（默认关闭）",
 				"--no-build                  跳过首次构建，使用现有入口（默认先构建）",
 				"--port <端口>               本地服务端口，1024–65535（默认 4300）",
+				"--listen-fd <fd>            接管宿主的 IPv4 回环监听；须与 --no-build 同用，排除 --port 和 --watch",
 				"--scheme <scheme>           宿主 deep link scheme（默认 widget-host）",
 				"--bridge <url>              指定 loopback HTTP(S) bridge；默认探测标准端口",
 				HOST_OPTION,
@@ -1475,7 +1643,8 @@ function documentationLines(documentation, topic = {}) {
 		...topic.agentDocs ? [
 			`文档站：${documentation.url}`,
 			`Agent 索引：${documentation.llms}`,
-			`完整文档：${documentation.llmsFull}`
+			`完整文档：${documentation.llmsFull}`,
+			"工程内的作者指引见 node_modules/@dp-bohrium/widget-sdk/llms.txt。"
 		] : []
 	];
 }
@@ -2459,6 +2628,7 @@ Widget ZIP 使用 \`pnpm run widget:pack\` 或 \`npm run widget:pack\`；\`pnpm
 
 - Widget 界面与业务逻辑在 ${sourceFile} 中；本工程的 ${hostFile} 调用 SDK 的 runWidgetHost 启动 Widget。
 - 高度链、布局与滚动策略直接写在 ${sourceFile} 中，样式随 activate 安装并在释放时清理；JSON 展示元素单独处理换行。
+- 在 [SDK 本地索引](./node_modules/@dp-bohrium/widget-sdk/llms.txt) 查看「Widget 尺寸与滚动」。
 - manifest.json 是作者清单，打包时由 CLI 编译为宿主清单。
 - 提交 widget-toolchain.json 与依赖 lockfile；dist/widget.js 与生成的 ZIP 不提交。
 - check 只验证结构、声明和样例，不执行 JavaScript；pack 成功不代表首帧渲染、真实授权或业务验收成功。

package/dist/compatibility/testing.js

@@ -1,4 +1,4 @@
-import { n as MemoryTransport, t as ProtocolEndpoint } from "../protocol-endpoint-CDz-YDGT.js";
+import { n as MemoryTransport, t as ProtocolEndpoint } from "../protocol-endpoint-DbT0OJNu.js";
 //#region src/runtime/mock-host.ts
 const widgetMessageTypes = /* @__PURE__ */ new Set([
 	"ready",

package/dist/contracts.js

@@ -1,2 +1,3 @@
-import { i as isWidgetActivationEvent, n as isWidgetEventName, r as WIDGET_ACTIVATION_EVENTS, t as WIDGET_EVENT_NAMES } from "./widget-events-gsKJbjqg.js";
-export { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, isWidgetActivationEvent, isWidgetEventName };
+import { a as projectWidgetRuntimeDiagnostic, c as WIDGET_EVENT_NAMES, d as isWidgetActivationEvent, i as projectWidgetCapabilityDiagnostic, l as isWidgetEventName, n as createWidgetRecoveryPlan, o as projectWidgetToolchainDiagnostic, r as findWidgetRecoveryRule, s as selectWidgetDevelopmentExtensions, t as WIDGET_RECOVERY_RULES, u as WIDGET_ACTIVATION_EVENTS } from "./widget-recovery-BF_sSUZX.js";
+import { n as isWidgetGuestDiagnostic, r as isWidgetRenderResult, t as isWidgetDevelopmentOffer } from "./development-guards-COvBR0G1.js";
+export { WIDGET_ACTIVATION_EVENTS, WIDGET_EVENT_NAMES, WIDGET_RECOVERY_RULES, createWidgetRecoveryPlan, findWidgetRecoveryRule, isWidgetActivationEvent, isWidgetDevelopmentOffer, isWidgetEventName, isWidgetGuestDiagnostic, isWidgetRenderResult, projectWidgetCapabilityDiagnostic, projectWidgetRuntimeDiagnostic, projectWidgetToolchainDiagnostic, selectWidgetDevelopmentExtensions };

package/dist/development-guards-COvBR0G1.js

@@ -0,0 +1,136 @@
+//#region src/protocol/generated-development-policy.ts
+/** GENERATED FILE. Do not edit directly. */
+const widgetDevelopmentPolicy = {
+	"required": [
+		"schemaVersion",
+		"source",
+		"code",
+		"phase",
+		"operation",
+		"severity",
+		"message"
+	],
+	"keys": [
+		"schemaVersion",
+		"source",
+		"code",
+		"sourceCode",
+		"phase",
+		"sourcePhase",
+		"operation",
+		"severity",
+		"message",
+		"retryable",
+		"correlationId",
+		"diagnostics",
+		"io"
+	],
+	"textMax": {
+		"code": 96,
+		"sourceCode": 96,
+		"sourcePhase": 96,
+		"operation": 96,
+		"message": 1024,
+		"field": 128,
+		"expected": 256,
+		"observed": 256,
+		"file": 256,
+		"excerpt": 1024
+	},
+	"maxDetails": 8,
+	"phases": [
+		"discovery",
+		"build",
+		"config",
+		"load",
+		"handshake",
+		"render",
+		"update",
+		"capability",
+		"dispose"
+	],
+	"severities": [
+		"warning",
+		"request-error",
+		"instance-failure"
+	],
+	"identifierPattern": "^[A-Za-z][A-Za-z0-9_.-]*$",
+	"filePattern": "^(?!/)(?!.*\\\\)(?!.*:)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^\\u0000-\\u001f]+$"
+};
+//#endregion
+//#region src/protocol/development-guards.ts
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function keys(value, required, allowed = required) {
+	return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => allowed.includes(key));
+}
+const identifier = new RegExp(widgetDevelopmentPolicy.identifierPattern, "u");
+const sourceFile = new RegExp(widgetDevelopmentPolicy.filePattern, "u");
+function text(value, max, empty = false) {
+	return typeof value === "string" && (empty || value.length > 0) && [...value].length <= max;
+}
+function correlation(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function id(value) {
+	return text(value, widgetDevelopmentPolicy.textMax.code) && identifier.test(value);
+}
+function detail(value) {
+	if (!record(value)) return false;
+	if ("file" in value) return keys(value, [
+		"file",
+		"line",
+		"column"
+	], [
+		"file",
+		"line",
+		"column",
+		"excerpt"
+	]) && text(value["file"], widgetDevelopmentPolicy.textMax.file) && sourceFile.test(value["file"]) && Number.isSafeInteger(value["line"]) && Number(value["line"]) > 0 && Number.isSafeInteger(value["column"]) && Number(value["column"]) > 0 && (value["excerpt"] === void 0 || text(value["excerpt"], widgetDevelopmentPolicy.textMax.excerpt));
+	return keys(value, ["field"], [
+		"field",
+		"expected",
+		"observed"
+	]) && text(value["field"], widgetDevelopmentPolicy.textMax.field) && (value["expected"] === void 0 || text(value["expected"], widgetDevelopmentPolicy.textMax.expected, true)) && (value["observed"] === void 0 || text(value["observed"], widgetDevelopmentPolicy.textMax.observed, true));
+}
+function io(value) {
+	if (!record(value) || !keys(value, ["kind"], [
+		"kind",
+		"status",
+		"sourceCode"
+	]) || value["sourceCode"] !== void 0 && !id(value["sourceCode"])) return false;
+	if (value["kind"] === "http") return Number.isInteger(value["status"]) && Number(value["status"]) >= 100 && Number(value["status"]) <= 599 && !(Number(value["status"]) >= 200 && Number(value["status"]) < 300);
+	return (value["kind"] === "transport" || value["kind"] === "invalid-response") && value["status"] === void 0;
+}
+/** 与源头 Schema 同源限额的轻量边界判定，不加载 AJV 或 Runtime。 */
+function isWidgetGuestDiagnostic(value) {
+	if (!record(value) || !keys(value, widgetDevelopmentPolicy.required, widgetDevelopmentPolicy.keys) || value["schemaVersion"] !== 1 || value["source"] !== "sdk" || !id(value["code"]) || !id(value["operation"]) || !widgetDevelopmentPolicy.phases.some((phase) => phase === value["phase"]) || !widgetDevelopmentPolicy.severities.some((severity) => severity === value["severity"]) || !text(value["message"], widgetDevelopmentPolicy.textMax.message)) return false;
+	if (value["retryable"] !== void 0 && typeof value["retryable"] !== "boolean" || value["correlationId"] !== void 0 && !correlation(value["correlationId"]) || value["sourceCode"] !== void 0 && !id(value["sourceCode"]) || value["sourcePhase"] !== void 0 && !id(value["sourcePhase"])) return false;
+	return (value["diagnostics"] === void 0 || Array.isArray(value["diagnostics"]) && value["diagnostics"].length <= widgetDevelopmentPolicy.maxDetails && value["diagnostics"].every(detail)) && (value["io"] === void 0 || io(value["io"]));
+}
+/** offer 只声明解析能力；实际 iframe 来源与 attempt 由 Host 校验。 */
+function isWidgetDevelopmentOffer(value) {
+	return record(value) && keys(value, [
+		"type",
+		"protocolVersion",
+		"extensions"
+	]) && value["type"] === "widget-bootstrap-offer" && value["protocolVersion"] === 1 && Array.isArray(value["extensions"]) && value["extensions"].length === 1 && value["extensions"][0] === "development-diagnostics-v1";
+}
+/** 失败回执仍需 Host 再匹配实际已发送的 request/revision。 */
+function isWidgetRenderResult(value) {
+	if (!record(value) || !correlation(value["requestId"]) || !Number.isSafeInteger(value["revision"]) || Number(value["revision"]) < 1) return false;
+	if (value["outcome"] === "handled" || value["outcome"] === "superseded") return keys(value, [
+		"requestId",
+		"revision",
+		"outcome"
+	]);
+	return value["outcome"] === "failed" && keys(value, [
+		"requestId",
+		"revision",
+		"outcome",
+		"diagnostic"
+	]) && isWidgetGuestDiagnostic(value["diagnostic"]) && value["diagnostic"].correlationId === value["requestId"] && (value["diagnostic"].phase === "render" || value["diagnostic"].phase === "update");
+}
+//#endregion
+export { isWidgetGuestDiagnostic as n, isWidgetRenderResult as r, isWidgetDevelopmentOffer as t };