@dp-bohrium/widget-sdk 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,5 +1,6 @@
-import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-D2xmZVSb.js";
-import { i as isWidgetActivationEvent, n as isWidgetEventName, r as WIDGET_ACTIVATION_EVENTS, t as WIDGET_EVENT_NAMES } from "./widget-events-gsKJbjqg.js";
+import { i as createWidgetClient, l as WIDGET_SDK_VERSION } from "./runtime-9g5MfsgK.js";
+import { a as projectWidgetRuntimeDiagnostic, c as WIDGET_EVENT_NAMES, d as isWidgetActivationEvent, l as isWidgetEventName, u as WIDGET_ACTIVATION_EVENTS } from "./widget-recovery-BF_sSUZX.js";
+import { n as isWidgetGuestDiagnostic } from "./development-guards-COvBR0G1.js";
 //#region src/manifest.ts
 function compiledContribution(contribution) {
 	switch (contribution.type) {
@@ -368,6 +369,7 @@ function createContext(client, payload, renderHandlers, lifetime) {
 function createWidgetRuntime(module, options = {}) {
 	let client;
 	const renderHandlers = /* @__PURE__ */ new Set();
+	let latestRenderRevision = 0;
 	const reportCleanupError = (error) => options.onCleanupError?.(toStartupError(error));
 	const lifetime = createWidgetLifetime(reportCleanupError);
 	let activation;
@@ -393,6 +395,16 @@ function createWidgetRuntime(module, options = {}) {
 			retryable: false,
 			correlationId: request.requestId
 		};
+		let location = null;
+		try {
+			location = error instanceof Error ? /(?:\/__widget\/guest\/[^/]+\/|\/assets\/)([a-zA-Z0-9_./-]+):(\d+):(\d+)/u.exec(error.stack ?? "") : null;
+		} catch {}
+		const projected = projectWidgetRuntimeDiagnostic(failure, update ? "update" : "render", location?.[1] ? [{
+			file: location[1],
+			line: Number(location[2]),
+			column: Number(location[3])
+		}] : void 0);
+		const diagnostic = isWidgetGuestDiagnostic(projected) ? projected : projectWidgetRuntimeDiagnostic(failure, update ? "update" : "render");
 		writeLocalDiagnostic("[Widget 渲染失败]", failure, error);
 		for (const observer of [options.events?.onError, options.onError]) try {
 			Promise.resolve(observer?.(failure)).catch((observerError) => {
@@ -401,6 +413,7 @@ function createWidgetRuntime(module, options = {}) {
 		} catch (observerError) {
 			writeLocalDiagnostic("[Widget 诊断回调失败]", observerError);
 		}
+		return diagnostic;
 	}
 	function runDeactivation() {
 		if (deactivation) return deactivation;
@@ -438,18 +451,51 @@ function createWidgetRuntime(module, options = {}) {
 				return activation;
 			},
 			onRender(request, update) {
+				latestRenderRevision = request.revision;
 				const renderContext = {
 					phase: update ? "update" : "initial",
 					signal: lifetime.signal
 				};
-				for (const handler of [...renderHandlers]) {
-					if (lifetime.signal.aborted) break;
+				const handlers = [...renderHandlers];
+				let reported = false;
+				const reportResult = (diagnostic) => {
+					if (lifetime.signal.aborted || !handlers.length || reported) return;
+					reported = true;
 					try {
-						Promise.resolve(handler(request, renderContext)).catch((error) => reportRenderFailure(error, request, update));
+						if (request.revision !== latestRenderRevision) client.reportRenderResult({
+							requestId: request.requestId,
+							revision: request.revision,
+							outcome: "superseded"
+						});
+						else if (diagnostic) client.reportRenderResult({
+							requestId: request.requestId,
+							revision: request.revision,
+							outcome: "failed",
+							diagnostic: {
+								...diagnostic,
+								correlationId: request.requestId,
+								phase: update ? "update" : "render"
+							}
+						});
+						else client.reportRenderResult({
+							requestId: request.requestId,
+							revision: request.revision,
+							outcome: "handled"
+						});
+					} catch (reason) {
+						writeLocalDiagnostic("[Widget 诊断发送失败]", reason);
+					}
+				};
+				Promise.all(handlers.map(async (handler) => {
+					if (lifetime.signal.aborted) return;
+					try {
+						await handler(request, renderContext);
 					} catch (error) {
-						reportRenderFailure(error, request, update);
+						reportResult(reportRenderFailure(error, request, update));
 					}
-				}
+				})).then(() => reportResult()).catch((reason) => {
+					writeLocalDiagnostic("[Widget 诊断发送失败]", reason);
+				});
 			},
 			onDispose: dispose
 		}

package/dist/protocol/development-guards.d.ts

@@ -0,0 +1,9 @@
+import type { WidgetDevelopmentDiagnostic, WidgetDevelopmentOffer, WidgetRenderResult } from "./generated-runtime-contracts.js";
+/** 与源头 Schema 同源限额的轻量边界判定，不加载 AJV 或 Runtime。 */
+export declare function isWidgetGuestDiagnostic(value: unknown): value is WidgetDevelopmentDiagnostic & {
+    source: "sdk";
+};
+/** offer 只声明解析能力；实际 iframe 来源与 attempt 由 Host 校验。 */
+export declare function isWidgetDevelopmentOffer(value: unknown): value is WidgetDevelopmentOffer;
+/** 失败回执仍需 Host 再匹配实际已发送的 request/revision。 */
+export declare function isWidgetRenderResult(value: unknown): value is WidgetRenderResult;

package/dist/protocol/generated-development-policy.d.ts

@@ -0,0 +1,22 @@
+/** GENERATED FILE. Do not edit directly. */
+export declare const widgetDevelopmentPolicy: {
+    readonly required: readonly ["schemaVersion", "source", "code", "phase", "operation", "severity", "message"];
+    readonly keys: readonly ["schemaVersion", "source", "code", "sourceCode", "phase", "sourcePhase", "operation", "severity", "message", "retryable", "correlationId", "diagnostics", "io"];
+    readonly textMax: {
+        readonly code: 96;
+        readonly sourceCode: 96;
+        readonly sourcePhase: 96;
+        readonly operation: 96;
+        readonly message: 1024;
+        readonly field: 128;
+        readonly expected: 256;
+        readonly observed: 256;
+        readonly file: 256;
+        readonly excerpt: 1024;
+    };
+    readonly maxDetails: 8;
+    readonly phases: readonly ["discovery", "build", "config", "load", "handshake", "render", "update", "capability", "dispose"];
+    readonly severities: readonly ["warning", "request-error", "instance-failure"];
+    readonly identifierPattern: "^[A-Za-z][A-Za-z0-9_.-]*$";
+    readonly filePattern: "^(?!/)(?!.*\\\\)(?!.*:)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^\\u0000-\\u001f]+$";
+};

package/dist/protocol/generated-runtime-contracts.d.ts

@@ -545,6 +545,124 @@ export type HostUserServiceRequest = ({
     action: "email.read";
     payload: HostUserEmailReadInput;
 });
+/**
+ * 受控字段诊断或工程相对源码位置；不携带原始对象。
+ */
+export type WidgetDiagnosticDetail = ({
+    field: string;
+    expected?: string;
+    observed?: string;
+} | {
+    file: string;
+    line: number;
+    column: number;
+    excerpt?: string;
+});
+/**
+ * 保留 transport、HTTP 与非法响应事实；不包含 URL 或原始响应。
+ */
+export type WidgetDiagnosticIO = ({
+    kind: ("transport" | "invalid-response");
+    sourceCode?: string;
+} | {
+    kind: "http";
+    status: number;
+    sourceCode?: string;
+});
+/**
+ * 恢复动作的语义及类型化参数；可信宿主绑定已有工具，不包含任意命令。
+ */
+export type WidgetRecoveryAction = ({
+    id: "inspect";
+    params: {
+        area: ("toolchain" | "host-bridge" | "configuration" | "bundle" | "handshake" | "render" | "capability" | "lease" | "operation-outcome" | "runtime");
+    };
+} | {
+    id: "wait";
+    params: {
+        milestone: ("budget-reset" | "connection-restored");
+        retryAfterMs?: number;
+    };
+} | {
+    id: "edit-project";
+    params: {
+        evidence: "diagnostics";
+    };
+} | {
+    id: "build-project";
+    params: {
+        target: "current-project";
+    };
+} | {
+    id: "refresh-preview";
+    params: {
+        target: "current-project";
+    };
+} | {
+    id: "verify-scenario";
+    params: {
+        target: ("current-attempt" | "next-built-generation");
+        scenarioId?: string;
+    };
+} | {
+    id: "request-external-action";
+    params: {
+        reason: ("authorization" | "host-support" | "host-start" | "credentials");
+    };
+} | {
+    id: "stop-preview";
+    params: {
+        target: "current-preview";
+    };
+});
+/**
+ * 经 offer/connect 显式选择的开发扩展；不授予 capability。
+ */
+export type WidgetDevelopmentExtension = "development-diagnostics-v1";
+/**
+ * 仅表示受管渲染处理器的处理结果，不代表视觉或业务验收。
+ */
+export type WidgetRenderResult = ({
+    requestId: string;
+    revision: number;
+    outcome: ("handled" | "superseded");
+} | {
+    requestId: string;
+    revision: number;
+    outcome: "failed";
+    diagnostic: WidgetRenderFailureDiagnostic;
+});
+/**
+ * 失败处理回执的 SDK 请求诊断；接收方还须匹配当前 requestId。
+ */
+export type WidgetRenderFailureDiagnostic = (WidgetGuestDiagnostic & {
+    correlationId: string;
+    phase?: ("render" | "update");
+});
+/**
+ * Guest 仅声明 SDK 诊断事实，不得冒充 Host 或工具链。
+ */
+export type WidgetGuestDiagnostic = (WidgetDevelopmentDiagnostic & {
+    source: "sdk";
+});
+/**
+ * 扩展 profile 下的 Widget → Host 消息；原 WidgetToHostMessage 不扩展。
+ */
+export type WidgetDevelopmentMessage = (WidgetToHostMessage | WidgetDiagnosticMessage | WidgetRenderResultMessage);
+/**
+ * 经协商的开发扩展 Bridge 消息；仍受现有通道与消息预算约束。
+ */
+export type WidgetDiagnosticMessage = (BridgeEnvelopeBase & {
+    type: "diagnostic";
+    payload: WidgetGuestDiagnostic;
+});
+/**
+ * 经协商的开发扩展 Bridge 消息；仍受现有通道与消息预算约束。
+ */
+export type WidgetRenderResultMessage = (BridgeEnvelopeBase & {
+    type: "render-result";
+    payload: WidgetRenderResult;
+});
 /**
  * Runtime 契约的汇总根容器；仅用于代码生成与符合性校验，不直接对外签发。
  */
@@ -585,6 +703,14 @@ export interface WidgetRuntimeContracts {
     hostUserEmailReadInput?: HostUserEmailReadInput;
     hostUserEmailReadOutput?: HostUserEmailReadOutput;
     hostUserServiceRequest?: HostUserServiceRequest;
+    widgetDevelopmentDiagnostic?: WidgetDevelopmentDiagnostic;
+    widgetRecoveryContext?: WidgetRecoveryContext;
+    widgetRecoveryPlan?: WidgetRecoveryPlan;
+    widgetRecoveryRule?: WidgetRecoveryRule;
+    widgetDevelopmentOffer?: WidgetDevelopmentOffer;
+    widgetDevelopmentConnect?: WidgetDevelopmentConnect;
+    widgetRenderResult?: WidgetRenderResult;
+    widgetDevelopmentMessage?: WidgetDevelopmentMessage;
 }
 /**
  * 渲染请求公共字段：schemaVersion、requestId、instanceId、revision、state、context。
@@ -1222,3 +1348,118 @@ export interface HostUserProfileReadOutput {
 export interface HostUserEmailReadOutput {
     email: (string | null);
 }
+/**
+ * 可信出口的标准诊断；恢复指令和 scope 由宿主另行生成。
+ */
+export interface WidgetDevelopmentDiagnostic {
+    schemaVersion: 1;
+    source: ("sdk" | "host" | "toolchain");
+    code: string;
+    sourceCode?: string;
+    phase: ("discovery" | "build" | "config" | "load" | "handshake" | "render" | "update" | "capability" | "dispose");
+    sourcePhase?: string;
+    operation: string;
+    severity: ("warning" | "request-error" | "instance-failure");
+    message: string;
+    retryable?: boolean;
+    correlationId?: string;
+    /**
+     * @maxItems 8
+     */
+    diagnostics?: [] | [WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail] | [WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail, WidgetDiagnosticDetail];
+    io?: WidgetDiagnosticIO;
+}
+/**
+ * 复用工具执行结果语义的可信恢复上下文；缺失字段表示未知，不能授权重放。
+ */
+export interface WidgetRecoveryContext {
+    progress?: WidgetRecoveryProgress;
+    executionState?: ("not_started" | "finished" | "partial" | "unknown");
+    mayHaveExecuted?: boolean;
+}
+/**
+ * 可信宿主观察到的恢复进展；重复故障无新证据时不能重复同一修复。
+ */
+export interface WidgetRecoveryProgress {
+    repeated: boolean;
+    hasNewEvidence: boolean;
+}
+/**
+ * 可信宿主选择的恢复计划；不能由 Guest 的诊断 payload 指定。
+ */
+export interface WidgetRecoveryPlan {
+    progress?: WidgetRecoveryProgress;
+    schemaVersion: 1;
+    ruleId: string;
+    ruleVersion: number;
+    disposition: ("retry" | "repair" | "inspect" | "external-action" | "stop");
+    nextAction: WidgetRecoveryAction;
+    verification: WidgetRecoveryVerification;
+    guidance: string;
+    /**
+     * 首项动作完成后的有限恢复步骤；宿主逐步验证前置条件，不原样盲目重放。
+     *
+     * @maxItems 8
+     */
+    followUpActions: [] | [WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction];
+}
+/**
+ * 恢复复验目标；下一成功构建须在取得回执后绑定实际产物。
+ */
+export interface WidgetRecoveryVerification {
+    target: ("current-attempt" | "next-built-generation" | "original-operation");
+    milestone: ("diagnostics-updated" | "render-handled" | "scenario-passed" | "operation-confirmed");
+    scenarioId?: string;
+}
+/**
+ * 公共恢复规则目录条目；空 codes 仅用于显式 unknown 回退。
+ */
+export interface WidgetRecoveryRule {
+    id: string;
+    version: number;
+    /**
+     * @minItems 1
+     * @maxItems 3
+     */
+    sources: [("sdk" | "host" | "toolchain")] | [("sdk" | "host" | "toolchain"), ("sdk" | "host" | "toolchain")] | [("sdk" | "host" | "toolchain"), ("sdk" | "host" | "toolchain"), ("sdk" | "host" | "toolchain")];
+    /**
+     * @maxItems 64
+     */
+    codes: string[];
+    disposition: ("retry" | "repair" | "inspect" | "external-action" | "stop");
+    nextAction: WidgetRecoveryAction;
+    verification: WidgetRecoveryVerification;
+    guidance: string;
+    /**
+     * 首项动作完成后的有限恢复步骤；宿主逐步验证前置条件，不原样盲目重放。
+     *
+     * @maxItems 8
+     */
+    followUpActions: [] | [WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction] | [WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction, WidgetRecoveryAction];
+}
+/**
+ * 独立于旧 bootstrap-ready 的支持声明，接收方仍须校验 frame 来源和挂载尝试。
+ */
+export interface WidgetDevelopmentOffer {
+    type: "widget-bootstrap-offer";
+    protocolVersion: 1;
+    /**
+     * @minItems 1
+     * @maxItems 1
+     */
+    extensions: [WidgetDevelopmentExtension];
+}
+/**
+ * 仅在收到当前 iframe 合法 offer 后使用的扩展 connect；旧形状保持不变。
+ */
+export interface WidgetDevelopmentConnect {
+    type: "widget-host-connect";
+    protocolVersion: 1;
+    channelId: string;
+    initPayload: InitPayload;
+    /**
+     * @minItems 1
+     * @maxItems 1
+     */
+    extensions: [WidgetDevelopmentExtension];
+}

package/dist/protocol/index.d.ts

@@ -41,3 +41,8 @@ export type BridgeEnvelope<TType extends string = string, TPayload = unknown> =
 };
 /** 可加载绑定与降级绑定的联合，即 Host Runtime Config 中一条 binding 的两种结果。 */
 export type ResolvedWidgetBinding = LoadableBinding | FallbackBinding;
+export { isWidgetDevelopmentOffer, isWidgetGuestDiagnostic, isWidgetRenderResult, } from "./development-guards.js";
+export type { WidgetDevelopmentConnect, WidgetDevelopmentDiagnostic, WidgetDevelopmentExtension, WidgetDevelopmentMessage, WidgetDevelopmentOffer, WidgetDiagnosticDetail, WidgetDiagnosticIO, WidgetDiagnosticMessage, WidgetGuestDiagnostic, WidgetRecoveryAction, WidgetRecoveryContext, WidgetRecoveryPlan, WidgetRecoveryProgress, WidgetRecoveryRule, WidgetRecoveryVerification, WidgetRenderResult, WidgetRenderResultMessage, } from "./generated-runtime-contracts.js";
+export { createWidgetRecoveryPlan, findWidgetRecoveryRule, projectWidgetCapabilityDiagnostic, projectWidgetRuntimeDiagnostic, projectWidgetToolchainDiagnostic, selectWidgetDevelopmentExtensions, WIDGET_RECOVERY_RULES, } from "./widget-recovery.js";
+/** SDK 运行层使用的已协商消息；旧 WidgetProtocolMessage 联合保持不变。 */
+export type WidgetRuntimeProtocolMessage = WidgetProtocolMessage | import("./generated-runtime-contracts.js").WidgetDevelopmentMessage;

package/dist/protocol/widget-recovery.d.ts

@@ -0,0 +1,19 @@
+import type { CapabilityResult, WidgetDevelopmentDiagnostic, WidgetDevelopmentExtension, WidgetDevelopmentOffer, WidgetError, WidgetGuestDiagnostic, WidgetRecoveryContext, WidgetRecoveryPlan, WidgetRecoveryRule } from "./generated-runtime-contracts.js";
+/** 包含 unknown 与操作核对规则，Agent 可按 plan.ruleId 定位每个实际计划。 */
+export declare const WIDGET_RECOVERY_RULES: readonly WidgetRecoveryRule[];
+/** 根据稳定码选择通用规则；未知码明确走排查，不匹配自由文本。 */
+export declare function findWidgetRecoveryRule(diagnostic: Pick<WidgetDevelopmentDiagnostic, "source" | "code">): WidgetRecoveryRule;
+/** 纯规则选择，不运行工具；宿主仍须校验实际能力、权限、scope 与恢复预算。 */
+export declare function createWidgetRecoveryPlan(diagnostic: WidgetDevelopmentDiagnostic, context?: WidgetRecoveryContext): WidgetRecoveryPlan;
+/** 只投影已校验的稳定字段；Guest message、context 和恢复文字不进入可信诊断。 */
+export declare function projectWidgetRuntimeDiagnostic(error: WidgetError, operation: string, diagnostics?: WidgetDevelopmentDiagnostic["diagnostics"]): WidgetGuestDiagnostic;
+/** 能力拒绝只影响当前请求；不把它投影为实例终态。 */
+export declare function projectWidgetCapabilityDiagnostic(failure: Extract<CapabilityResult, {
+    ok: false;
+}>, operation: string): WidgetDevelopmentDiagnostic;
+/** 工程错误仅提取稳定 code；原始 stdout/stderr 由可信工具单独脱敏投影。 */
+export declare function projectWidgetToolchainDiagnostic(error: {
+    code: string;
+}, operation: string, phase: "discovery" | "build" | "config"): WidgetDevelopmentDiagnostic;
+/** 仅选择双方声明的扩展；实际 frame 来源和当前 attempt 仍由 Host 校验。 */
+export declare function selectWidgetDevelopmentExtensions(offer: WidgetDevelopmentOffer | undefined, supported: readonly WidgetDevelopmentExtension[]): readonly WidgetDevelopmentExtension[];

package/dist/{protocol-endpoint-CDz-YDGT.js → protocol-endpoint-DbT0OJNu.js}

@@ -1,5 +1,8 @@
+import { n as isWidgetGuestDiagnostic, r as isWidgetRenderResult } from "./development-guards-COvBR0G1.js";
 //#region src/runtime/transport.ts
 const protocolMessageTypes = /* @__PURE__ */ new Set([
+	"diagnostic",
+	"render-result",
 	"init",
 	"render",
 	"update",
@@ -25,6 +28,8 @@ function isFiniteNonNegative(value) {
 }
 function isProtocolPayload(type, payload) {
 	switch (type) {
+		case "diagnostic": return isWidgetGuestDiagnostic(payload);
+		case "render-result": return isWidgetRenderResult(payload);
 		case "init": return hasRequiredKeys(payload, [
 			"instanceId",
 			"locale",

package/dist/runtime/bootstrap.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RegionCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "../protocol/index.js";
+import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RegionCapabilityResult, RenderRequest, WidgetError, WidgetGuestDiagnostic, WidgetLiveEvent, WidgetRenderResult } from "../protocol/index.js";
 import { type PresentationFocusDirection, type PresentationSurface, type RegionName, type WidgetCapabilityRequestOptions, type WidgetClientEvents, type WidgetClientState } from "./client.js";
 import { type SubscribeWidgetEventsOptions, type WidgetEventSubscription, type WidgetToolHooks } from "./events.js";
 import type { WidgetNetworkClient } from "./network.js";
@@ -109,6 +109,8 @@ export declare class WidgetRuntimeClient {
     private stopPresentationKeyboard;
     dispose(): void;
     private receiveConnection;
+    reportDevelopmentDiagnostic(diagnostic: WidgetGuestDiagnostic): void;
+    reportRenderResult(result: WidgetRenderResult): void;
     private requireClient;
     private removeConnectionListener;
     private failConnection;

package/dist/runtime/client.d.ts

@@ -1,4 +1,4 @@
-import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RegionCapabilityRequest, RegionCapabilityResult, RenderRequest, WidgetError, WidgetLiveEvent } from "../protocol/index.js";
+import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RegionCapabilityRequest, RegionCapabilityResult, RenderRequest, WidgetError, WidgetGuestDiagnostic, WidgetLiveEvent, WidgetRenderResult } from "../protocol/index.js";
 import { type WidgetNetworkClient } from "./network.js";
 import type { WidgetTransport } from "./transport.js";
 export type WidgetClientState = "created" | "waiting-ready" | "ready" | "disposed";
@@ -8,6 +8,7 @@ export interface WidgetClientOptions {
     widgetSdkVersion: string;
     hostApiVersion?: 1;
     initialPayload?: InitPayload;
+    developmentDiagnostics?: boolean;
     handshakeTimeoutMs?: number;
     capabilityTimeoutMs?: number;
     createMessageId?: () => string;
@@ -48,6 +49,7 @@ export declare class WidgetClient {
     private readonly endpoint;
     private readonly widgetSdkVersion;
     private readonly channelId;
+    private readonly developmentDiagnostics;
     private readonly handshakeTimeoutMs;
     private readonly capabilityTimeoutMs;
     private readonly createMessageId;
@@ -81,6 +83,8 @@ export declare class WidgetClient {
     private receive;
     private initialize;
     private initializeAsync;
+    reportDevelopmentDiagnostic(diagnostic: WidgetGuestDiagnostic): void;
+    reportRenderResult(result: WidgetRenderResult): void;
     private send;
     private assertUsable;
     private acceptsRender;

package/dist/runtime/index.js

@@ -1,3 +1,3 @@
-import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-D2xmZVSb.js";
-import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-CDz-YDGT.js";
+import { a as isWidgetHostConnectMessage, c as WidgetClient, i as createWidgetClient, l as WIDGET_SDK_VERSION, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as REGION_CONFIRMATION_TIMEOUT_MS, t as WIDGET_BOOTSTRAP_READY } from "../runtime-9g5MfsgK.js";
+import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-DbT0OJNu.js";
 export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, REGION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WIDGET_SDK_VERSION, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/runtime/protocol-endpoint.d.ts

@@ -1,17 +1,17 @@
-import type { WidgetProtocolMessage } from "../protocol/index.js";
+import type { WidgetRuntimeProtocolMessage } from "../protocol/index.js";
 import { type WidgetTransport } from "./transport.js";
 declare const envelopeFields: readonly ["protocolVersion", "channelId", "messageId", "sequence"];
 type EnvelopeField = (typeof envelopeFields)[number];
-export type ProtocolMessageBody<TMessage extends WidgetProtocolMessage> = TMessage extends WidgetProtocolMessage ? Omit<TMessage, EnvelopeField> : never;
-interface ProtocolEndpointOptions<TInbound extends WidgetProtocolMessage> {
+export type ProtocolMessageBody<TMessage extends WidgetRuntimeProtocolMessage> = TMessage extends WidgetRuntimeProtocolMessage ? Omit<TMessage, EnvelopeField> : never;
+interface ProtocolEndpointOptions<TInbound extends WidgetRuntimeProtocolMessage> {
     transport: WidgetTransport;
     channelId: string;
     createMessageId: () => string;
-    acceptsInbound: (message: WidgetProtocolMessage) => message is TInbound;
+    acceptsInbound: (message: WidgetRuntimeProtocolMessage) => message is TInbound;
     onMessage: (message: TInbound) => void;
     onError?: (error: Error) => void;
 }
-export declare class ProtocolEndpoint<TInbound extends WidgetProtocolMessage, TOutbound extends WidgetProtocolMessage> {
+export declare class ProtocolEndpoint<TInbound extends WidgetRuntimeProtocolMessage, TOutbound extends WidgetRuntimeProtocolMessage> {
     private readonly transport;
     private readonly channelId;
     private readonly createMessageId;

package/dist/runtime/transport.d.ts

@@ -1,7 +1,7 @@
-import type { WidgetProtocolMessage } from "../protocol/index.js";
+import type { WidgetRuntimeProtocolMessage } from "../protocol/index.js";
 export interface WidgetTransport {
-    send(message: WidgetProtocolMessage): void;
-    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    send(message: WidgetRuntimeProtocolMessage): void;
+    onMessage(listener: (message: WidgetRuntimeProtocolMessage) => void): () => void;
     onError?(listener: (error: Error) => void): () => void;
     close(): void;
 }
@@ -9,7 +9,7 @@ export interface WidgetTransport {
 export interface WidgetMessagePort {
     onmessage: ((event: MessageEvent<unknown>) => void) | null;
     onmessageerror?: ((event: MessageEvent<unknown>) => void) | null;
-    postMessage(message: WidgetProtocolMessage): void;
+    postMessage(message: WidgetRuntimeProtocolMessage): void;
     start?: () => void;
     close(): void;
 }
@@ -17,14 +17,14 @@ export interface WidgetMessagePort {
  * Performs the inexpensive checks that are possible at the transport edge.
  * Payload-specific validation stays with the contract/conformance layer.
  */
-export declare function isWidgetProtocolMessage(value: unknown): value is WidgetProtocolMessage;
+export declare function isWidgetProtocolMessage(value: unknown): value is WidgetRuntimeProtocolMessage;
 export declare class MemoryTransport implements WidgetTransport {
     private peer?;
     private readonly listeners;
     private closed;
     static pair(): readonly [MemoryTransport, MemoryTransport];
-    send(message: WidgetProtocolMessage): void;
-    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    send(message: WidgetRuntimeProtocolMessage): void;
+    onMessage(listener: (message: WidgetRuntimeProtocolMessage) => void): () => void;
     onError(): () => void;
     close(): void;
 }
@@ -35,8 +35,8 @@ export declare class MessagePortTransport implements WidgetTransport {
     private readonly errorListeners;
     private closed;
     constructor(port: WidgetMessagePort);
-    send(message: WidgetProtocolMessage): void;
-    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    send(message: WidgetRuntimeProtocolMessage): void;
+    onMessage(listener: (message: WidgetRuntimeProtocolMessage) => void): () => void;
     onError(listener: (error: Error) => void): () => void;
     private reportError;
     close(): void;