@dp-bohrium/widget-sdk 0.0.1

package/dist/runtime/client.d.ts

@@ -0,0 +1,82 @@
+import type { CapabilityRequest, CapabilityResult, GrantedCapability, InitPayload, PresentationCapabilityRequest, PresentationCapabilityResult, RenderRequest, WidgetError } from "@dp-bohrium/widget-contracts";
+import { type WidgetNetworkClient } from "./network.js";
+import type { WidgetTransport } from "./transport.js";
+export type WidgetClientState = "created" | "waiting-ready" | "ready" | "disposed";
+export interface WidgetClientOptions {
+    transport: WidgetTransport;
+    channelId: string;
+    widgetSdkVersion: string;
+    hostApiVersion?: 1;
+    initialPayload?: InitPayload;
+    handshakeTimeoutMs?: number;
+    capabilityTimeoutMs?: number;
+    createMessageId?: () => string;
+}
+export interface WidgetClientEvents {
+    onInit?: (payload: InitPayload) => void | PromiseLike<void>;
+    onRender?: (request: RenderRequest, update: boolean) => void;
+    onUpdate?: (request: RenderRequest) => void;
+    onError?: (error: WidgetError) => void;
+    onDispose?: (reason: string, deadlineMs?: number) => void;
+}
+export interface WidgetCapabilityRequestOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export declare const PRESENTATION_CONFIRMATION_TIMEOUT_MS = 60000;
+type SurfacePresentationInput = Extract<PresentationCapabilityRequest["input"], {
+    surface: unknown;
+}>;
+type FocusBoundaryPresentationInput = Extract<PresentationCapabilityRequest["input"], {
+    action: "focus-boundary";
+}>;
+export type PresentationSurface = SurfacePresentationInput["surface"];
+export type PresentationFocusDirection = FocusBoundaryPresentationInput["direction"];
+type PresentationRequest = (request: CapabilityRequest, options: WidgetCapabilityRequestOptions) => Promise<CapabilityResult>;
+export declare function hasOverlayPresentationGrant(capabilities: readonly GrantedCapability[]): boolean;
+export declare function requestPresentationCapability(request: PresentationRequest, capabilityRequest: PresentationCapabilityRequest, options?: WidgetCapabilityRequestOptions): Promise<PresentationCapabilityResult>;
+export declare class WidgetClient {
+    readonly network: WidgetNetworkClient;
+    private readonly endpoint;
+    private readonly widgetSdkVersion;
+    private readonly channelId;
+    private readonly handshakeTimeoutMs;
+    private readonly capabilityTimeoutMs;
+    private readonly createMessageId;
+    private readonly events;
+    private state;
+    private readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private handshakeTimer?;
+    private instanceId?;
+    private renderRevision?;
+    private overlayPresentationGranted;
+    private networkFetchGranted;
+    private readonly pending;
+    private readonly hostApiVersion;
+    private readySettled;
+    constructor(options: WidgetClientOptions, events?: WidgetClientEvents);
+    get currentState(): WidgetClientState;
+    ready(): Promise<void>;
+    resize(width: number, height: number): void;
+    requestCapability(request: CapabilityRequest, options?: 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>;
+    dispose(): void;
+    private finishDispose;
+    private rejectPendingCapabilities;
+    private receive;
+    private initialize;
+    private initializeAsync;
+    private send;
+    private assertUsable;
+    private acceptsRender;
+    private assertReady;
+    private handleTransportError;
+    private failHandshake;
+    private failWithError;
+}
+export {};

package/dist/runtime/event-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ToolLifecycleEvent, WidgetEventBatch } from "@dp-bohrium/widget-contracts";
+export declare function parseWidgetEventBatch(value: unknown): WidgetEventBatch;
+export declare function parseToolLifecycleEvent(value: unknown): ToolLifecycleEvent;

package/dist/runtime/events.d.ts

@@ -0,0 +1,45 @@
+import type { CapabilityRequest, GrantedCapability, ToolLifecycleEvent, WidgetEventBatch } from "@dp-bohrium/widget-contracts";
+export interface WidgetEventSubscription {
+    readonly cursor: string | undefined;
+    readonly closed: Promise<void>;
+    unsubscribe(): void;
+}
+export interface WidgetEventBatchContext {
+    readonly signal: AbortSignal;
+}
+export interface SubscribeWidgetEventsOptions {
+    topic: string;
+    cursor?: string;
+    onBatch(batch: WidgetEventBatch, context: WidgetEventBatchContext): void | Promise<void>;
+    onError(error: Error): void;
+}
+type EventGrant = Extract<GrantedCapability, {
+    name: "events.read";
+}>;
+interface SubscriptionDependencies extends SubscribeWidgetEventsOptions {
+    grant(): Promise<EventGrant | undefined>;
+    request(request: Extract<CapabilityRequest, {
+        operation: "events.read";
+    }>, options: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+}
+/** 游标仅在消费者处理成功后推进；取消和失败都释放本实例的读取与计时器。 */
+export declare function subscribeToWidgetEvents(options: SubscriptionDependencies): WidgetEventSubscription;
+export interface WidgetToolHooks {
+    toolName?: string;
+    toolCallId?: string;
+    onToolCall?(event: ToolLifecycleEvent, context: WidgetEventBatchContext): void | Promise<void>;
+    onToolResult?(event: ToolLifecycleEvent, context: WidgetEventBatchContext): void | Promise<void>;
+    onToolError?(event: ToolLifecycleEvent, context: WidgetEventBatchContext): void | Promise<void>;
+    onToolCancelled?(event: ToolLifecycleEvent, context: WidgetEventBatchContext): void | Promise<void>;
+    onReset?(snapshot: WidgetEventBatch["snapshot"], context: WidgetEventBatchContext): void | Promise<void>;
+}
+/** 工具 Hook 是执行事实的观察者；不得用浏览器回调替代服务端执行门禁。 */
+export declare function toolHookHandlers(hooks: WidgetToolHooks): (batch: WidgetEventBatch, context?: WidgetEventBatchContext) => Promise<void>;
+export interface WidgetEventReadScheduler {
+    schedule<T>(topic: string, grant: EventGrant, signal: AbortSignal, read: () => Promise<T>): Promise<T>;
+}
+/** 实例内所有订阅共用授权额度；FIFO 防止后来的订阅抢占先到的读取。 */
+export declare function createWidgetEventReadScheduler(): WidgetEventReadScheduler;
+export {};

package/dist/runtime/index.d.ts

@@ -0,0 +1,8 @@
+export type { CreateWidgetClientOptions, WidgetClientFactoryOptions, WidgetDisposeEvent, WidgetHostConnectMessage, WidgetRuntimeWindow, WidgetSize, } from "./bootstrap.js";
+export { createWidgetClient, isWidgetHostConnectMessage, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WidgetRuntimeClient, } from "./bootstrap.js";
+export type { PresentationFocusDirection, PresentationSurface, WidgetCapabilityRequestOptions, WidgetClientEvents, WidgetClientOptions, WidgetClientState, } from "./client.js";
+export { PRESENTATION_CONFIRMATION_TIMEOUT_MS, WidgetClient, } from "./client.js";
+export type { SubscribeWidgetEventsOptions, WidgetEventBatchContext, WidgetEventSubscription, WidgetToolHooks, } from "./events.js";
+export type { WidgetNetworkClient, WidgetNetworkFetchResult, } from "./network.js";
+export type { WidgetMessagePort, WidgetTransport } from "./transport.js";
+export { isWidgetProtocolMessage, MessagePortTransport, } from "./transport.js";

package/dist/runtime/index.js

@@ -0,0 +1,3 @@
+import { a as isWidgetHostConnectMessage, i as createWidgetClient, n as WIDGET_HOST_CONNECT, o as PRESENTATION_CONFIRMATION_TIMEOUT_MS, r as WidgetRuntimeClient, s as WidgetClient, t as WIDGET_BOOTSTRAP_READY } from "../runtime-D-xKLIEj.js";
+import { i as isWidgetProtocolMessage, r as MessagePortTransport } from "../protocol-endpoint-CHWoXvKN.js";
+export { MessagePortTransport, PRESENTATION_CONFIRMATION_TIMEOUT_MS, WIDGET_BOOTSTRAP_READY, WIDGET_HOST_CONNECT, WidgetClient, WidgetRuntimeClient, createWidgetClient, isWidgetHostConnectMessage, isWidgetProtocolMessage };

package/dist/runtime/mock-host.d.ts

@@ -0,0 +1,45 @@
+import type { CapabilityRequest, CapabilityResult, InitPayload, RenderRequest, WidgetError } from "@dp-bohrium/widget-contracts";
+import type { WidgetTransport } from "./transport.js";
+export type MockWidgetHostState = "created" | "waiting-ready" | "ready" | "disposed";
+export interface MockWidgetHostOptions {
+    transport: WidgetTransport;
+    channelId: string;
+    init: InitPayload;
+    createMessageId?: () => string;
+    handleCapability?: (request: CapabilityRequest) => CapabilityResult | Promise<CapabilityResult>;
+    capabilityResult?: CapabilityResult;
+}
+export interface MockWidgetHostEvents {
+    onReady?: (payload: {
+        widgetSdkVersion: string;
+        hostApiVersion: 1;
+    }) => void;
+    onResize?: (size: {
+        width: number;
+        height: number;
+    }) => void;
+    onError?: (error: WidgetError) => void;
+}
+export declare class MockWidgetHost {
+    private readonly endpoint;
+    private readonly init;
+    private readonly events;
+    private readonly handleCapability?;
+    private readonly capabilityResult;
+    private readonly receivedCapabilityRequests;
+    private state;
+    private rendered;
+    private readonly readyPromise;
+    private resolveReady;
+    private rejectReady;
+    constructor(options: MockWidgetHostOptions, events?: MockWidgetHostEvents);
+    get currentState(): MockWidgetHostState;
+    get capabilityRequests(): readonly CapabilityRequest[];
+    ready(): Promise<void>;
+    start(): void;
+    render(request: RenderRequest): void;
+    dispose(reason?: string): void;
+    private receive;
+    private resolveCapability;
+    private assertReady;
+}

package/dist/runtime/network.d.ts

@@ -0,0 +1,18 @@
+import type { CapabilityRequest, CapabilityResult, WidgetNetworkFetchInput, WidgetNetworkFetchOutput } from "@dp-bohrium/widget-contracts";
+import type { WidgetCapabilityRequestOptions, WidgetClientState } from "./client.js";
+export type WidgetNetworkFetchResult = Readonly<{
+    ok: true;
+    data: WidgetNetworkFetchOutput;
+}> | Extract<CapabilityResult, {
+    ok: false;
+}>;
+export interface WidgetNetworkClient {
+    fetch(input: WidgetNetworkFetchInput, options?: WidgetCapabilityRequestOptions): Promise<WidgetNetworkFetchResult>;
+}
+interface WidgetNetworkClientDependencies {
+    readonly state: () => WidgetClientState;
+    readonly granted: () => boolean;
+    readonly request: (request: CapabilityRequest, options?: WidgetCapabilityRequestOptions) => Promise<CapabilityResult>;
+}
+export declare function createWidgetNetworkClient(dependencies: WidgetNetworkClientDependencies): WidgetNetworkClient;
+export {};

package/dist/runtime/presentation-keyboard.d.ts

@@ -0,0 +1,29 @@
+import type { PresentationFocusDirection, WidgetCapabilityRequestOptions } from "./client.js";
+interface PresentationKeyboardEvent {
+    readonly key: string;
+    readonly shiftKey: boolean;
+    readonly repeat: boolean;
+    readonly isComposing: boolean;
+    readonly isTrusted: boolean;
+    readonly defaultPrevented: boolean;
+}
+interface PresentationFocusEvent {
+    readonly relatedTarget: EventTarget | null;
+}
+export interface PresentationKeyboardTarget {
+    readonly document: unknown;
+    addEventListener(type: "keydown", listener: (event: PresentationKeyboardEvent) => void): void;
+    addEventListener(type: "focusout", listener: (event: PresentationFocusEvent) => void): void;
+    removeEventListener(type: "keydown", listener: (event: PresentationKeyboardEvent) => void): void;
+    removeEventListener(type: "focusout", listener: (event: PresentationFocusEvent) => void): void;
+}
+interface PresentationKeyboardAdapterOptions {
+    readonly target: PresentationKeyboardTarget;
+    close(options: WidgetCapabilityRequestOptions): Promise<unknown>;
+    focusBoundary(direction: PresentationFocusDirection, options: WidgetCapabilityRequestOptions): Promise<unknown>;
+}
+export interface PresentationKeyboardAdapter {
+    dispose(): void;
+}
+export declare function createPresentationKeyboardAdapter(options: PresentationKeyboardAdapterOptions): PresentationKeyboardAdapter;
+export {};

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

@@ -0,0 +1,30 @@
+import type { WidgetProtocolMessage } from "@dp-bohrium/widget-contracts";
+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> {
+    transport: WidgetTransport;
+    channelId: string;
+    createMessageId: () => string;
+    acceptsInbound: (message: WidgetProtocolMessage) => message is TInbound;
+    onMessage: (message: TInbound) => void;
+    onError?: (error: Error) => void;
+}
+export declare class ProtocolEndpoint<TInbound extends WidgetProtocolMessage, TOutbound extends WidgetProtocolMessage> {
+    private readonly transport;
+    private readonly channelId;
+    private readonly createMessageId;
+    private readonly acceptsInbound;
+    private readonly unsubscribe;
+    private readonly unsubscribeError;
+    private sequence;
+    private inboundSequence;
+    private readonly inboundMessageIds;
+    private closed;
+    constructor(options: ProtocolEndpointOptions<TInbound>);
+    send(message: ProtocolMessageBody<TOutbound>): void;
+    close(): void;
+    private accepts;
+}
+export {};

package/dist/runtime/transport.d.ts

@@ -0,0 +1,43 @@
+import type { WidgetProtocolMessage } from "@dp-bohrium/widget-contracts";
+export interface WidgetTransport {
+    send(message: WidgetProtocolMessage): void;
+    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    onError?(listener: (error: Error) => void): () => void;
+    close(): void;
+}
+/** The part of the browser MessagePort API used by the SDK runtime. */
+export interface WidgetMessagePort {
+    onmessage: ((event: MessageEvent<unknown>) => void) | null;
+    onmessageerror?: ((event: MessageEvent<unknown>) => void) | null;
+    postMessage(message: WidgetProtocolMessage): void;
+    start?: () => void;
+    close(): void;
+}
+/**
+ * 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 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;
+    onError(): () => void;
+    close(): void;
+}
+/** Adapts a browser MessagePort to the SDK's contract-message transport. */
+export declare class MessagePortTransport implements WidgetTransport {
+    private readonly port;
+    private readonly listeners;
+    private readonly errorListeners;
+    private closed;
+    constructor(port: WidgetMessagePort);
+    send(message: WidgetProtocolMessage): void;
+    onMessage(listener: (message: WidgetProtocolMessage) => void): () => void;
+    onError(listener: (error: Error) => void): () => void;
+    private reportError;
+    close(): void;
+}