@dp-bohrium/widget-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DP Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @dp-bohrium/widget-sdk
+
+Widget developer SDK. Use `createWidgetClient` inside a production Widget
+Bundle. It announces the bundle to the Host, accepts the transferred
+`MessagePort`, and exposes the shared lifecycle and capability protocol
+without requiring Widget code to handle `window.postMessage` directly.
+
+Install the exact prerelease from the internal registry:
+
+```bash
+pnpm add @dp-bohrium/widget-sdk@0.0.1 \
+  --registry=https://registry.npmjs.org
+```
+
+Host Runtime and Shrimp should keep consuming `@dp-bohrium/widget-contracts`.
+They must not install this package.
+
+```ts
+import { createWidgetClient } from "@dp-bohrium/widget-sdk";
+
+const widget = createWidgetClient({
+  widgetSdkVersion: "0.0.1",
+  async onInit(payload) {
+    // Initialize using the Host-provided locale, theme and capabilities.
+    console.log(payload.locale);
+    await Promise.resolve(); // Load application state here.
+  },
+  onRender(request) {
+    // Render the complete snapshot for the selected slot.
+    console.log(request.slot);
+  },
+  onDispose({ reason, deadlineMs }) {
+    // Release local timers, subscriptions and workers.
+    console.log(reason, deadlineMs);
+  },
+});
+
+await widget.ready();
+widget.resize({ width: 600, height: 400 });
+```
+
+## Host-managed network access
+
+Declare `requestedCapabilities.network.fetch` in the Widget Manifest, then use the typed facade after
+`ready()` resolves. The Widget never receives Host credentials and does not call browser `fetch` directly:
+
+```ts
+const controller = new AbortController();
+const result = await widget.network.fetch(
+  {
+    url: "https://api.example.org/papers",
+    auth: "optional",
+    method: "GET",
+    headers: { accept: "application/json" },
+  },
+  { signal: controller.signal, timeoutMs: 15_000 },
+);
+
+if (result.ok) {
+  consume(result.data.status, result.data.headers, result.data.body);
+} else {
+  showNetworkFailure(result.reason, result.retryable);
+}
+```
+
+The Host decides whether to prompt, remember an exact Origin grant, select an opaque credential binding,
+follow a redirect, or deny the request. Calls before readiness, after disposal, or without a current
+`network.fetch` grant reject locally. Abort and timeout reuse the existing MessageChannel capability lifecycle.
+`requestCapability` remains available for protocol-level integrations, but `widget.network.fetch` is the
+supported network API for Widget application code.
+
+## Host-governed panel presentation
+
+Panel Widgets can ask the Host to present their current panel in a workspace,
+floating, or overlay surface. The same methods are available on the ordinary
+`createWidgetClient()` result and the low-level `WidgetClient`:
+
+```ts
+import { PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "@dp-bohrium/widget-sdk";
+
+const presentationAbort = new AbortController();
+const result = await widget.present("floating", {
+  timeoutMs: PRESENTATION_CONFIRMATION_TIMEOUT_MS,
+  signal: presentationAbort.signal,
+});
+
+if (!result.ok) {
+  showPresentationDenial(result.reason, result.message);
+} else if ("surface" in result.data) {
+  // The Host can report a different actual surface, such as a compact-mode
+  // downgrade from floating to overlay or workspace.
+  showCurrentSurface(result.data.surface);
+}
+
+await widget.changePresentationSurface("overlay");
+await widget.focusPresentationBoundary("forward");
+await widget.closePresentation();
+```
+
+When the Host grants `ui.presentation` with the `overlay` surface, the ordinary
+client also installs keyboard cooperation for cross-origin Panel overlays. An
+unhandled, trusted, non-composing Escape requests `closePresentation()`. A Tab
+that is followed by focus leaving the iframe requests
+`focusPresentationBoundary("forward" | "backward")`; internal focus movement
+does not send anything. Frameworks with a custom focus manager can call the
+typed helper directly.
+
+The default confirmation timeout is 60 seconds. `timeoutMs` overrides it and
+`signal` cancels local waiting. A Host policy or user denial resolves normally
+as `{ ok: false, reason, message, retryable }`; client timeout, abort, dispose,
+or a malformed successful response rejects the Promise. Browser resize,
+visibility, focus, and pointer events are never treated as confirmation.
+
+These methods only request a presentation. The Host remains the final authority
+for grants, supported surfaces, confirmation, compact-mode downgrade, and the
+actual panel state. `isTrusted` and `defaultPrevented` are Widget-realm noise
+filters, not authorization: the MessageChannel identifies the current iframe
+instance but cannot prove a physical key or human activation. The Widget cannot
+name a target Panel, Host selector, identity, runtime generation, coordinate, or
+layer. The Host must recheck the current instance, top Overlay, focus epoch, and
+higher security layers before accepting either request.
+
+`ready()` is not sent to the Host until `onInit` returns or its Promise
+settles. If initialization fails, the SDK reports a structured `onError`
+event and then invokes `onDispose` so local resources can be released.
+`handshakeTimeoutMs` also bounds this initialization step after the Host
+connection has been established.
+
+When only `onUpdate` is supplied, the first complete `render` snapshot is also
+delivered to `onUpdate`.
+
+`WidgetClient` provides the framework-neutral, low-level runtime interface.
+Capability requests accept `{ timeoutMs, signal }`, so application lifecycle
+hooks can cancel pending reads without receiving late results. It is available
+from `@dp-bohrium/widget-sdk/runtime` for advanced integrations and protocol-level
+tests.
+
+The main entry exposes the production `createWidgetClient` factory. Low-level
+protocol classes and bootstrap constants are available from
+`@dp-bohrium/widget-sdk/runtime`; `MessagePortTransport` and the bootstrap
+messages are not part of the ordinary Widget API.
+
+`@dp-bohrium/widget-sdk/testing` provides `MemoryTransport` and
+`MockWidgetHost`. The Mock Host owns init/ready sequencing, first-render versus
+update selection, resize events, capability adapter responses, and terminal
+dispose behavior. It uses the same public contracts as production Hosts but
+does not claim production iframe, CSP, authorization, or resource-isolation
+guarantees. Contract validators stay in the unpublished
+`@dp-bohrium/widget-contract-testing` workspace package.
+
+Set `capabilityResult` for one deterministic default allow or denial. A supplied
+`handleCapability` remains the authoritative advanced handler when both are
+present. `host.capabilityRequests` returns an ordered defensive-copy snapshot,
+so tests can inspect requests without mutating Mock Host state.
+
+or fallback UI. If the Host iframe uses `sandbox="allow-scripts"` without
+`allow-same-origin`, load the bundled Widget as a classic script or IIFE
+unless the isolated origin serves CORS headers for `type="module"`.
+
+If the Host sends a malformed Bridge envelope or payload, the transport reports
+a structured `MESSAGE_INVALID` error and closes the connection. The Widget is
+not left waiting on a connection that the Host still considers active.
+
+
+## 受授权的事件订阅与工具 Hook（本地候选）
+
+新增 `subscribeEvents`、`onTool` 和 `invokeAction`。Manifest 声明与 Host 实际 grant 必须同时包含 topic/action，旧 Host 不会自动获得这些能力；发布时需一起升级 contracts 和消费者。订阅类型从包根与 `/runtime` 导出。
+
+```ts
+const events = client.subscribeEvents({
+  topic: "jobs.progress",
+  onBatch(batch, { signal }) {
+    if (signal.aborted) return;
+    // 只应用本批真实事件；batch.reset 时替换旧状态。
+    renderProgress(batch.events);
+  },
+  onError: showSubscriptionError,
+});
+const hooks = client.onTool({
+  onToolCall: showStarted,
+  onToolResult: showCompleted,
+  onToolError: showFailed,
+  onToolCancelled: showCancelled,
+}, { onError: showSubscriptionError });
+const result = await client.invokeAction({
+  action: "tools.inspect",
+  idempotencyKey: crypto.randomUUID(),
+  arguments: { toolCallId },
+});
+const resumeCursor = events.cursor;
+events.unsubscribe();
+hooks.unsubscribe();
+```
+
+Hook 观察已经发生的服务端工具事实，不是执行前拦截器；不允许通过 iframe 回调改写参数、审批或控制 durable 执行。`tools.inspect` 是当前 Shrimp 的只读动作 provider，返回工具身份和最新可读取状态；其他 action 由 Host/provider 显式实现并授权。SDK 不自动重试动作，也不把回调完成解释为工具执行完成。
+
+所有订阅共享实例的 events 请求预算，并各自遵守 topic 最小间隔。游标仅在 `onBatch` 成功后提交；消费者异常、权限撤销和不可恢复的历史错误会关闭订阅并调用 `onError`。`unsubscribe` 和 Host dispose 释放订阅、排队请求和本地在途等待，忽略迟到结果；异步回调需检查传入 signal 后再更新自己的状态。`closed` 表示订阅已关闭，并不等待用户未完成的回调结束。重新订阅时显式传入已保存 cursor。
+
+维护者可复验包在仓库 `examples/forge/tool-observer`，不包含在开发者 npm 包中。
+
+每次 events.read 是有界、非阻塞读取；当前 V1 没有单请求取消 wire 消息，unsubscribe 会停止后续轮询并取消本地等待，已经发出的服务端读取可能完成但其结果被忽略。Host 实例卸载另通过既有 lease/AbortSignal 释放在途宿主请求。

package/dist/compatibility/testing.d.ts

@@ -0,0 +1,3 @@
+export type { MockWidgetHostEvents, MockWidgetHostOptions, MockWidgetHostState, } from "../runtime/mock-host.js";
+export { MockWidgetHost } from "../runtime/mock-host.js";
+export { MemoryTransport } from "../runtime/transport.js";

package/dist/compatibility/testing.js

@@ -0,0 +1,129 @@
+import { n as MemoryTransport, t as ProtocolEndpoint } from "../protocol-endpoint-CHWoXvKN.js";
+//#region src/runtime/mock-host.ts
+const widgetMessageTypes = /* @__PURE__ */ new Set([
+	"ready",
+	"resize",
+	"capability-request",
+	"error"
+]);
+function isWidgetToHostMessage(message) {
+	return widgetMessageTypes.has(message.type);
+}
+var MockWidgetHost = class {
+	endpoint;
+	init;
+	events;
+	handleCapability;
+	capabilityResult;
+	receivedCapabilityRequests = [];
+	state = "created";
+	rendered = false;
+	readyPromise;
+	resolveReady;
+	rejectReady;
+	constructor(options, events = {}) {
+		this.init = options.init;
+		this.events = events;
+		this.handleCapability = options.handleCapability;
+		this.capabilityResult = options.capabilityResult ?? {
+			ok: false,
+			reason: "unsupported",
+			message: "mock host capability is not configured",
+			retryable: false
+		};
+		this.endpoint = new ProtocolEndpoint({
+			transport: options.transport,
+			channelId: options.channelId,
+			createMessageId: options.createMessageId ?? (() => crypto.randomUUID()),
+			acceptsInbound: isWidgetToHostMessage,
+			onMessage: (message) => this.receive(message)
+		});
+		this.readyPromise = new Promise((resolve, reject) => {
+			this.resolveReady = resolve;
+			this.rejectReady = reject;
+		});
+		this.readyPromise.catch(() => void 0);
+	}
+	get currentState() {
+		return this.state;
+	}
+	get capabilityRequests() {
+		return structuredClone(this.receivedCapabilityRequests);
+	}
+	ready() {
+		return this.readyPromise;
+	}
+	start() {
+		if (this.state !== "created") return;
+		this.state = "waiting-ready";
+		this.endpoint.send({
+			type: "init",
+			payload: this.init
+		});
+	}
+	render(request) {
+		this.assertReady();
+		this.endpoint.send({
+			type: this.rendered ? "update" : "render",
+			payload: request
+		});
+		this.rendered = true;
+	}
+	dispose(reason = "mock-host-disposed") {
+		if (this.state === "disposed") return;
+		const disposedBeforeReady = this.state !== "ready";
+		this.endpoint.send({
+			type: "dispose",
+			payload: {
+				reason,
+				deadlineMs: this.init.resourceBudget.timeouts.disposeGraceMs
+			}
+		});
+		this.state = "disposed";
+		if (disposedBeforeReady) this.rejectReady(/* @__PURE__ */ new Error(`mock host disposed before ready: ${reason}`));
+		this.endpoint.close();
+	}
+	receive(message) {
+		if (this.state === "disposed") return;
+		if (message.type === "ready") {
+			if (this.state !== "waiting-ready") return;
+			this.state = "ready";
+			this.resolveReady();
+			this.events.onReady?.(message.payload);
+		} else if (message.type === "resize") {
+			if (this.state !== "ready") return;
+			this.events.onResize?.(message.payload);
+		} else if (message.type === "capability-request") {
+			if (this.state !== "ready") return;
+			this.resolveCapability(message.payload.requestId, message.payload.request);
+		} else if (message.type === "error") this.events.onError?.(message.payload);
+	}
+	async resolveCapability(requestId, request) {
+		this.receivedCapabilityRequests.push(structuredClone(request));
+		let result;
+		try {
+			result = this.handleCapability ? await this.handleCapability(request) : structuredClone(this.capabilityResult);
+		} catch {
+			result = {
+				ok: false,
+				reason: "internal-error",
+				message: "mock capability handler failed",
+				retryable: false
+			};
+		}
+		if (this.state !== "ready") return;
+		this.endpoint.send({
+			type: "capability-result",
+			payload: {
+				requestId,
+				result
+			}
+		});
+	}
+	assertReady() {
+		if (this.state === "disposed") throw new Error("mock host is disposed");
+		if (this.state !== "ready") throw new Error("mock host is not ready");
+	}
+};
+//#endregion
+export { MemoryTransport, MockWidgetHost };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export type { CreateWidgetClientOptions, PresentationFocusDirection, PresentationSurface, SubscribeWidgetEventsOptions, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientFactoryOptions, WidgetClientOptions, WidgetClientState, WidgetDisposeEvent, WidgetEventBatchContext, WidgetEventSubscription, WidgetHostConnectMessage, WidgetMessagePort, WidgetNetworkClient, WidgetNetworkFetchResult, WidgetRuntimeWindow, WidgetSize, WidgetToolHooks, WidgetTransport, } from "./runtime/index.js";
+export { createWidgetClient, PRESENTATION_CONFIRMATION_TIMEOUT_MS, } from "./runtime/index.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+import { i as createWidgetClient, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS } from "./runtime-D-xKLIEj.js";
+export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, createWidgetClient };

package/dist/protocol-endpoint-CHWoXvKN.js

@@ -0,0 +1,214 @@
+//#region src/runtime/transport.ts
+const protocolMessageTypes = /* @__PURE__ */ new Set([
+	"init",
+	"render",
+	"update",
+	"capability-result",
+	"error",
+	"dispose",
+	"ready",
+	"resize",
+	"capability-request"
+]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function property(value, key) {
+	return value[key];
+}
+function hasRequiredKeys(value, keys) {
+	return keys.every((key) => Object.hasOwn(value, key));
+}
+function isFiniteNonNegative(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isProtocolPayload(type, payload) {
+	switch (type) {
+		case "init": return hasRequiredKeys(payload, [
+			"instanceId",
+			"locale",
+			"theme",
+			"capabilities",
+			"resourceBudget"
+		]) && typeof property(payload, "instanceId") === "string" && typeof property(payload, "locale") === "string" && isRecord(property(payload, "theme")) && Array.isArray(property(payload, "capabilities")) && isRecord(property(payload, "resourceBudget"));
+		case "render":
+		case "update": {
+			const revision = property(payload, "revision");
+			const context = property(payload, "context");
+			const content = property(payload, "content");
+			return property(payload, "schemaVersion") === 1 && typeof property(payload, "requestId") === "string" && typeof property(payload, "instanceId") === "string" && typeof revision === "number" && Number.isSafeInteger(revision) && revision >= 1 && typeof property(payload, "slot") === "string" && typeof property(payload, "state") === "string" && isRecord(context) && isRecord(content);
+		}
+		case "capability-result": return typeof property(payload, "requestId") === "string" && isRecord(property(payload, "result"));
+		case "error": return typeof property(payload, "code") === "string" && typeof property(payload, "phase") === "string" && typeof property(payload, "message") === "string" && typeof property(payload, "retryable") === "boolean" && typeof property(payload, "correlationId") === "string";
+		case "dispose": return typeof property(payload, "reason") === "string" && isFiniteNonNegative(property(payload, "deadlineMs"));
+		case "ready": return typeof property(payload, "widgetSdkVersion") === "string" && property(payload, "hostApiVersion") === 1;
+		case "resize": return isFiniteNonNegative(property(payload, "width")) && isFiniteNonNegative(property(payload, "height"));
+		case "capability-request": return typeof property(payload, "requestId") === "string" && isRecord(property(payload, "request"));
+		default: return false;
+	}
+}
+/**
+* Performs the inexpensive checks that are possible at the transport edge.
+* Payload-specific validation stays with the contract/conformance layer.
+*/
+function isWidgetProtocolMessage(value) {
+	if (!isRecord(value)) return false;
+	const keys = Object.keys(value);
+	const expectedKeys = [
+		"protocolVersion",
+		"channelId",
+		"messageId",
+		"sequence",
+		"type",
+		"payload"
+	];
+	if (keys.length !== expectedKeys.length || expectedKeys.some((key) => !keys.includes(key))) return false;
+	const protocolVersion = property(value, "protocolVersion");
+	const channelId = property(value, "channelId");
+	const messageId = property(value, "messageId");
+	const sequence = property(value, "sequence");
+	const type = property(value, "type");
+	const payload = property(value, "payload");
+	return protocolVersion === 1 && typeof channelId === "string" && channelId.length >= 16 && typeof messageId === "string" && messageId.length > 0 && typeof sequence === "number" && Number.isSafeInteger(sequence) && sequence > 0 && typeof type === "string" && protocolMessageTypes.has(type) && isRecord(payload) && isProtocolPayload(type, payload);
+}
+var MemoryTransport = class MemoryTransport {
+	peer;
+	listeners = /* @__PURE__ */ new Set();
+	closed = false;
+	static pair() {
+		const first = new MemoryTransport();
+		const second = new MemoryTransport();
+		first.peer = second;
+		second.peer = first;
+		return [first, second];
+	}
+	send(message) {
+		if (this.closed) throw new Error("transport is closed");
+		if (this.peer?.closed) return;
+		for (const listener of this.peer?.listeners ?? []) listener(message);
+	}
+	onMessage(listener) {
+		if (this.closed) return () => void 0;
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	onError() {
+		return () => void 0;
+	}
+	close() {
+		this.closed = true;
+		this.listeners.clear();
+	}
+};
+/** Adapts a browser MessagePort to the SDK's contract-message transport. */
+var MessagePortTransport = class {
+	port;
+	listeners = /* @__PURE__ */ new Set();
+	errorListeners = /* @__PURE__ */ new Set();
+	closed = false;
+	constructor(port) {
+		this.port = port;
+		this.port.onmessage = (event) => {
+			if (this.closed) return;
+			const message = event.data;
+			if (!isWidgetProtocolMessage(message)) {
+				this.reportError(/* @__PURE__ */ new Error("invalid widget protocol message"));
+				return;
+			}
+			for (const listener of this.listeners) listener(message);
+		};
+		this.port.onmessageerror = () => {
+			this.reportError(/* @__PURE__ */ new Error("MessagePort reported a message error"));
+		};
+		this.port.start?.();
+	}
+	send(message) {
+		if (this.closed) throw new Error("transport is closed");
+		this.port.postMessage(message);
+	}
+	onMessage(listener) {
+		if (this.closed) return () => void 0;
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	onError(listener) {
+		if (this.closed) return () => void 0;
+		this.errorListeners.add(listener);
+		return () => this.errorListeners.delete(listener);
+	}
+	reportError(error) {
+		if (this.closed) return;
+		for (const listener of [...this.errorListeners]) try {
+			listener(error);
+		} catch {}
+		this.close();
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.listeners.clear();
+		this.errorListeners.clear();
+		this.port.onmessage = null;
+		if (this.port.onmessageerror !== void 0) this.port.onmessageerror = null;
+		this.port.close();
+	}
+};
+//#endregion
+//#region src/runtime/protocol-endpoint.ts
+const inboundMessageWindowSize = 256;
+var ProtocolEndpoint = class {
+	transport;
+	channelId;
+	createMessageId;
+	acceptsInbound;
+	unsubscribe;
+	unsubscribeError;
+	sequence = 0;
+	inboundSequence = 0;
+	inboundMessageIds = /* @__PURE__ */ new Set();
+	closed = false;
+	constructor(options) {
+		this.transport = options.transport;
+		this.channelId = options.channelId;
+		this.createMessageId = options.createMessageId;
+		this.acceptsInbound = options.acceptsInbound;
+		this.unsubscribe = this.transport.onMessage((message) => {
+			if (!isWidgetProtocolMessage(message)) {
+				options.onError?.(/* @__PURE__ */ new Error("invalid widget protocol message"));
+				return;
+			}
+			if (!this.accepts(message)) return;
+			options.onMessage(message);
+		});
+		this.unsubscribeError = this.transport.onError?.((error) => options.onError?.(error)) ?? (() => void 0);
+	}
+	send(message) {
+		if (this.closed) throw new Error("protocol endpoint is closed");
+		this.transport.send({
+			...message,
+			protocolVersion: 1,
+			channelId: this.channelId,
+			messageId: this.createMessageId(),
+			sequence: ++this.sequence
+		});
+	}
+	close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.unsubscribe();
+		this.unsubscribeError();
+		this.transport.close();
+	}
+	accepts(message) {
+		if (this.closed || message.protocolVersion !== 1 || message.channelId !== this.channelId || !this.acceptsInbound(message) || this.inboundMessageIds.has(message.messageId) || message.sequence <= this.inboundSequence) return false;
+		this.inboundSequence = message.sequence;
+		this.inboundMessageIds.add(message.messageId);
+		if (this.inboundMessageIds.size > inboundMessageWindowSize) {
+			const oldestMessageId = this.inboundMessageIds.values().next().value;
+			if (oldestMessageId) this.inboundMessageIds.delete(oldestMessageId);
+		}
+		return true;
+	}
+};
+//#endregion
+export { isWidgetProtocolMessage as i, MemoryTransport as n, MessagePortTransport as r, ProtocolEndpoint as t };

package/dist/runtime/bootstrap.d.ts

@@ -0,0 +1,95 @@
+import type { CapabilityRequest, CapabilityResult, InitPayload, PresentationCapabilityResult, RenderRequest, WidgetError } from "@dp-bohrium/widget-contracts";
+import { type PresentationFocusDirection, type PresentationSurface, 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";
+export declare const WIDGET_BOOTSTRAP_READY: "widget-bootstrap-ready";
+export declare const WIDGET_HOST_CONNECT: "widget-host-connect";
+export interface WidgetHostConnectMessage {
+    type: typeof WIDGET_HOST_CONNECT;
+    protocolVersion: 1;
+    channelId: string;
+    initPayload: InitPayload;
+}
+export interface WidgetRuntimeWindow {
+    readonly parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    };
+    addEventListener(type: "message", listener: (event: MessageEvent<unknown>) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEvent<unknown>) => void): void;
+}
+export interface WidgetDisposeEvent {
+    reason: string;
+    deadlineMs?: number;
+}
+export interface CreateWidgetClientOptions {
+    widgetSdkVersion: string;
+    hostApiVersion?: 1;
+    handshakeTimeoutMs?: number;
+    capabilityTimeoutMs?: number;
+    connectionTimeoutMs?: number;
+    createMessageId?: () => string;
+    expectedHostOrigin?: string;
+    window?: WidgetRuntimeWindow;
+    events?: WidgetClientEvents;
+    onInit?: (payload: InitPayload) => void | PromiseLike<void>;
+    onRender?: (request: RenderRequest) => void;
+    onUpdate?: (request: RenderRequest) => void;
+    onError?: (error: WidgetError) => void;
+    onDispose?: (event: WidgetDisposeEvent) => void;
+}
+export type WidgetClientFactoryOptions = CreateWidgetClientOptions;
+export interface WidgetSize {
+    width: number;
+    height: number;
+}
+export declare function isWidgetHostConnectMessage(value: unknown): value is WidgetHostConnectMessage;
+/**
+ * High-level Widget-side runtime. It hides bootstrap postMessage and the
+ * transferred MessagePort from Widget application code.
+ */
+export declare class WidgetRuntimeClient {
+    readonly network: WidgetNetworkClient;
+    private readonly runtimeWindow;
+    private readonly options;
+    private readonly events;
+    private readonly messageListener;
+    private readonly readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private readySettled;
+    private connectionTimer?;
+    private client?;
+    private state;
+    private disposed;
+    private capabilities;
+    private overlayPresentationGranted;
+    private readonly subscriptions;
+    private readonly eventReads;
+    private readonly eventReadsLifetime;
+    private presentationKeyboard;
+    constructor(options: CreateWidgetClientOptions);
+    get currentState(): WidgetClientState;
+    ready(): Promise<void>;
+    resize(width: number, height: number): void;
+    resize(size: WidgetSize): void;
+    requestCapability(request: CapabilityRequest, timeoutMs?: number | WidgetCapabilityRequestOptions): Promise<CapabilityResult>;
+    present(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+    closePresentation(options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+    changePresentationSurface(surface: PresentationSurface, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+    focusPresentationBoundary(direction: PresentationFocusDirection, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+    subscribeEvents(options: SubscribeWidgetEventsOptions): WidgetEventSubscription;
+    onTool(hooks: WidgetToolHooks, options: Pick<SubscribeWidgetEventsOptions, "cursor" | "onError">): WidgetEventSubscription;
+    invokeAction(input: Extract<CapabilityRequest, {
+        operation: "actions.invoke";
+    }>["input"], options?: WidgetCapabilityRequestOptions): Promise<CapabilityResult>;
+    private stopSubscriptions;
+    private startPresentationKeyboard;
+    private stopPresentationKeyboard;
+    dispose(): void;
+    private receiveConnection;
+    private requireClient;
+    private removeConnectionListener;
+    private failConnection;
+    private rejectBeforeReady;
+}
+export declare function createWidgetClient(options: CreateWidgetClientOptions): WidgetRuntimeClient;