@exponential_app/eui 0.0.0-stage → 0.2.0

package/dist/types/src/host/record-store.d.ts

@@ -0,0 +1,103 @@
+import type { AppPackage } from "./package.js";
+import type { ParsedSource, SourceResolver } from "./sources.js";
+/** The binding scheme: `records:<kind>[?query]`. */
+export declare const RECORDS_SCHEME = "records";
+/** The write functions (no consent card: the app's own rows). */
+export declare const RECORDS_FUNCTIONS: readonly string[];
+/** The neutral query's defaults (catalog/host.json `package.records.query`). */
+export declare const RECORDS_QUERY: {
+    readonly sortDefault: "createdAt";
+    readonly orderDefault: "desc";
+    readonly limitDefault: 100;
+    readonly limitMax: 500;
+};
+/** Query keys a host may give a meaning (Exponential does); never a field filter. */
+export declare const RECORDS_RESERVED_PARAMS: readonly string[];
+export interface RecordRow {
+    id: string;
+    kind: string;
+    data: Record<string, unknown>;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export type RecordsFilterOp = `eq` | `gt` | `gte` | `lt` | `lte`;
+export interface RecordsQuery {
+    kind: string;
+    mine: boolean;
+    sort: string;
+    order: `asc` | `desc`;
+    limit: number;
+    /** By field, then operator. */
+    filters: {
+        field: string;
+        op: RecordsFilterOp;
+        value: string;
+    }[];
+}
+export interface RecordsValue {
+    rows: Record<string, unknown>[];
+    count: number;
+}
+/** `records:<kind>?…` (as `parseSource` gives it) → the query; null = not
+ *  a records source. */
+export declare function parseRecordsSource(source: Pick<ParsedSource, `scheme` | `name` | `params`>): RecordsQuery | null;
+/** The value a `records:` binding emits over `rows` (any kind): the kind's
+ *  matching rows sorted (ties by id) then cut at the limit, `count` before
+ *  the limit. `names` = user id → the display name (`author`). */
+export declare function recordsValue(rows: readonly RecordRow[], query: RecordsQuery, ctx: {
+    me: string | null;
+    names?: Record<string, string>;
+}): RecordsValue;
+/** What a host provides: one package's records, any transport. */
+export interface RecordStore {
+    /** Every row of the package (any kind) now, then on every change; returns the cancel. */
+    subscribe(emit: (rows: readonly RecordRow[]) => void): () => void;
+    /** Create (no id) or shallow-patch `data` (id); resolves the row's id. The
+     *  caller has validated the result against the kind's schema. */
+    upsert(input: {
+        kind: string;
+        data: Record<string, unknown>;
+        id?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(id: string): Promise<void>;
+    /** One row by id (the patch base). */
+    get(id: string): RecordRow | undefined;
+}
+/** The reference store: in memory, `now` + `newId` injectable. */
+export declare class MemoryRecordStore implements RecordStore {
+    private readonly options;
+    private rows;
+    private listeners;
+    private seq;
+    constructor(options?: {
+        me?: string | null;
+        now?: () => string;
+        newId?: () => string;
+        rows?: readonly RecordRow[];
+    });
+    subscribe(emit: (rows: readonly RecordRow[]) => void): () => void;
+    get(id: string): RecordRow | undefined;
+    upsert(input: {
+        kind: string;
+        data: Record<string, unknown>;
+        id?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(id: string): Promise<void>;
+    private changed;
+}
+/** A package's records on a host: the `records` source resolver and the
+ *  two write functions (pass them to `ExponentialHost` as `sources` /
+ *  `functions`). A write is validated against the kind's schema (a patch:
+ *  the merged data) before the store sees it; a refusal throws. */
+export declare function recordsHost(pkg: Pick<AppPackage, `records`>, store: RecordStore, ctx?: {
+    me: string | null;
+    names?: Record<string, string>;
+}): {
+    sources: Record<string, SourceResolver>;
+    functions: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
+};

package/dist/types/src/host/records.d.ts

@@ -0,0 +1,45 @@
+import type { PackageIssue } from "./package.js";
+/** `^[a-z][a-z0-9_]{0,31}$`: a kind's name (catalog/host.json `package.records`). */
+export declare const RECORD_KIND_PATTERN: RegExp;
+/** The keys every record row carries; a schema may not declare them. */
+export declare const RECORD_RESERVED_KEYS: readonly string[];
+export declare const RECORD_FIELD_TYPES: readonly string[];
+export declare const RECORD_ITEM_TYPES: readonly string[];
+export declare const RECORD_FORMATS: readonly string[];
+export interface RecordItems {
+    type: `string` | `number` | `integer` | `boolean`;
+    enum?: string[];
+}
+export interface RecordField {
+    type: `string` | `number` | `integer` | `boolean` | `array`;
+    /** Strings only: the allowed values. */
+    enum?: string[];
+    /** Arrays only: what an item is. */
+    items?: RecordItems;
+    /** Strings: characters; arrays: items. */
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    /** Strings only: `date` (YYYY-MM-DD), `date-time` (ISO 8601), `time` (HH:MM[:SS]). */
+    format?: `date` | `date-time` | `time`;
+    description?: string;
+}
+export interface RecordSchema {
+    type: `object`;
+    properties: Record<string, RecordField>;
+    required?: string[];
+    /** Default false: a key outside `properties` is refused. */
+    additionalProperties?: boolean;
+}
+export interface RecordKind {
+    schema: RecordSchema;
+    title?: string;
+    description?: string;
+}
+/** Every problem with a kind's schema, each with a JSON pointer under `at`. */
+export declare function validateRecordSchema(schema: unknown, at: string): PackageIssue[];
+/** Every problem with `data` against `schema` (a valid one): `/field`
+ *  pointers. A null or missing optional field passes; a required one does
+ *  not; a key the schema does not declare is refused unless
+ *  `additionalProperties` is true. */
+export declare function validateRecord(schema: RecordSchema, data: unknown): PackageIssue[];

package/dist/types/src/host/router.d.ts

@@ -0,0 +1,38 @@
+import type { HostOp } from "./contract.js";
+import type { AvailableExtension, PackageIssue, AppPackage } from "./package.js";
+export interface HostRouterOptions {
+    /** Extension catalog ids the host registered (negotiation). */
+    extensionIds?: readonly string[];
+    /** VAPP-161: their versions and components (a package's `extensions`
+     *  are checked against them; unset = only that the id is registered). */
+    extensions?: readonly AvailableExtension[];
+}
+export interface SurfaceInfo {
+    surfaceId: string;
+    catalogId: string;
+    /** The package whose template created it (its function policy). */
+    packageId?: string;
+}
+export declare class HostRouter {
+    private extensionIds;
+    private surfaces;
+    private packages;
+    private extensions;
+    constructor(options?: HostRouterOptions);
+    get supportedCatalogIds(): string[];
+    registerExtension(id: string, available?: AvailableExtension): void;
+    /** Install a declarative package: its templates become `applyTemplate`
+     *  targets. Returns the validation issues (installed only when none). */
+    installPackage(pkg: AppPackage): PackageIssue[];
+    package(id: string): AppPackage | undefined;
+    surface(id: string): SurfaceInfo | undefined;
+    surfaceIds(): string[];
+    /** One server message → the ops to perform, in order. Never throws. */
+    route(message: unknown): HostOp[];
+    private findPackage;
+    private invalid;
+    private missing;
+}
+/** A2UI: an omitted path or `/` is the whole data model (`""` in JSON
+ *  pointer terms, which every surface's setPointer takes). */
+export declare function normalizePath(path: string | undefined): string;

package/dist/types/src/host/runtime.d.ts

@@ -0,0 +1,213 @@
+import type { ResolvedTheme } from "../theme-types.js";
+import type { ExtensionDef, FlatComponent, ReduceIssue, UiNode } from "../types.js";
+import type { ClientMessage, HostOp } from "./contract.js";
+import type { PackageIssue, AppPackage } from "./package.js";
+import type { FunctionDecision, FunctionPolicy, MediaOptions, MediaRequest, UrlPolicy } from "./policy.js";
+import { HostRouter } from "./router.js";
+import type { SourceResolvers } from "./sources.js";
+export type TransportStatus = `connecting` | `open` | `closed` | `error`;
+/** Messages in, client messages out. Adapters: `transports.ts`. */
+export interface Transport {
+    /** Start delivering messages; report the connection state. */
+    start(receive: (message: unknown) => void, status: (status: TransportStatus, detail?: string) => void): void;
+    send(message: ClientMessage): void | Promise<void>;
+    close(): void;
+}
+export interface FunctionCallInfo {
+    surfaceId: string;
+    componentId: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export type HostFunction = (args: Record<string, unknown>, call: FunctionCallInfo) => unknown | Promise<unknown>;
+export interface HostPolicy {
+    /** The declarative gate; `ask` decisions go to onFunctionCall. */
+    functions?: FunctionPolicy;
+    /** The consent hook: true runs the call. Unset = `ask` is denied. */
+    onFunctionCall?: (call: FunctionCallInfo) => boolean | Promise<boolean>;
+    urls?: UrlPolicy;
+    /** Opens an allowed url (default: `window.open(url, "_blank")`). */
+    openUrl?: (url: string) => void;
+    media?: MediaOptions;
+}
+export interface HostOptions {
+    transport?: Transport;
+    functions?: Record<string, HostFunction>;
+    sources?: SourceResolvers;
+    extensions?: readonly ExtensionDef[];
+    packages?: readonly AppPackage[];
+    policy?: HostPolicy;
+    /** Every client message that leaves (after the transport got it). */
+    onSend?: (message: ClientMessage) => void;
+    /** Ops the host performs (tests, logging). */
+    onOp?: (op: HostOp) => void;
+    /** Every problem the host meets (a package that failed validation, an
+     *  error it answered a message with, an invalid surface theme). A
+     *  transport-less host has no server to tell: this is where they land. */
+    onIssue?: (issue: HostIssue) => void;
+}
+/** One problem the host met; `host.issues` keeps the latest ones. */
+export interface HostIssue {
+    /** A host error code (`TEMPLATE_NOT_FOUND`…) or `PACKAGE_INVALID`. */
+    code: string;
+    message: string;
+    surfaceId?: string;
+    /** A JSON pointer (into the package or the message). */
+    path?: string;
+    packageId?: string;
+}
+/** A package passed in `HostOptions.packages` that failed validation. */
+export declare class PackageError extends Error {
+    readonly packageId: string;
+    readonly issues: PackageIssue[];
+    constructor(packageId: string, issues: PackageIssue[]);
+}
+/** A `createSurface.theme` (a built-in id or a theme JSON) → the resolved
+ *  theme, or why it is unusable. */
+export declare function resolveSurfaceTheme(input: unknown): {
+    theme: ResolvedTheme | null;
+    issues: string[];
+};
+export interface FunctionOutcome {
+    decision: FunctionDecision;
+    result?: unknown;
+    error?: string;
+}
+type Listener = () => void;
+/** One surface's state: the flat components, the data model, the reduced
+ *  tree. Mutations notify subscribers; `root` is reduced lazily. */
+export declare class SurfaceStore {
+    private extensions;
+    readonly surfaceId: string;
+    catalogId: string;
+    packageId?: string;
+    sendDataModel: boolean;
+    /** The flat components, mutated in place while nothing holds them. */
+    private list;
+    /** `list` was handed out (`components`): the next update copies first. */
+    private shared;
+    private positions;
+    data: Record<string, unknown>;
+    /** The server's `createSurface.theme`, resolved (undefined = the
+     *  renderer's own theme). */
+    theme?: ResolvedTheme;
+    private reduced;
+    private listeners;
+    version: number;
+    constructor(surfaceId: string, catalogId: string, extensions: () => readonly ExtensionDef[]);
+    /** The flat components as a SNAPSHOT: an array handed out here is never
+     *  mutated afterwards (the next update copies first), so a renderer that
+     *  keeps it sees a stable value; a stream nobody reads stays linear. */
+    get components(): readonly FlatComponent[];
+    /** The flat component with this id (undefined = none). */
+    component(id: string): FlatComponent | undefined;
+    get root(): UiNode | null;
+    get issues(): ReduceIssue[];
+    /** Round 2 §4: the reducer's lifted data templates (absent without any). */
+    get templates(): Record<string, UiNode> | undefined;
+    private reduce;
+    /** A2UI: a later update replaces components BY ID and keeps the rest
+     *  (an id → position map: a streamed surface costs linear, VAPP-103). */
+    setComponents(components: readonly FlatComponent[]): void;
+    /** Re-reduce on the next read (the extension set changed). */
+    invalidate(): void;
+    /** Write the data model at `pointer` (`undefined` removes); a refused
+     *  write (writePointer) changes nothing and returns the reason. */
+    setData(pointer: string, value: unknown): string | undefined;
+    subscribe(listener: Listener): () => void;
+    notify(): void;
+}
+export declare class ExponentialHost {
+    private options;
+    readonly router: HostRouter;
+    private stores;
+    /** Per surface, one entry per bound path (VAPP-122: a re-bind of a path
+     *  cancels the earlier subscription at that path). */
+    private subscriptions;
+    /** Per surface: the FLAT component owning a failed node → that
+     *  component as it was when it failed + the node ids already reported. */
+    private paintErrors;
+    private listeners;
+    private functions;
+    private sources;
+    private extensions;
+    status: TransportStatus;
+    statusDetail?: string;
+    /** The last UNSUPPORTED_CATALOG id seen (the catalog-update banner). */
+    unsupportedCatalog?: string;
+    /** The latest problems (newest last, capped); a new array per change. */
+    issues: readonly HostIssue[];
+    constructor(options?: HostOptions);
+    /** False for a local-only host (packages, in-memory feeds): no
+     *  `host_offline` state to show. */
+    get hasTransport(): boolean;
+    get supportedCatalogIds(): string[];
+    clientCapabilities(): {
+        "v0.9": {
+            supportedCatalogIds: string[];
+        };
+    };
+    get extensionDefs(): readonly ExtensionDef[];
+    registerExtension(ext: ExtensionDef): void;
+    registerFunction(name: string, fn: HostFunction): void;
+    registerSource(scheme: string, resolver: SourceResolvers[string]): void;
+    /** Install a package; its validation issues are returned AND reported
+     *  (`issues`, `onIssue`). A package with issues is not installed. */
+    installPackage(pkg: AppPackage): PackageIssue[];
+    private report;
+    surface(id: string): SurfaceStore | undefined;
+    surfaceIds(): string[];
+    subscribe(listener: Listener): () => void;
+    private notify;
+    connect(): void;
+    close(): void;
+    /** One server message (a transport calls this; tests and in-memory hosts
+     *  may call it directly). */
+    receive(message: unknown): HostOp[];
+    send(message: ClientMessage): void;
+    private perform;
+    private unbind;
+    /** A component's server event: the A2UI client action message. */
+    action(event: {
+        surfaceId: string;
+        componentId: string;
+        name: string;
+        context?: Record<string, unknown>;
+        payload?: Record<string, unknown>;
+        timestamp?: string;
+    }): ClientMessage;
+    /** The policy decision for a call, before any consent hook. */
+    decide(surfaceId: string, name: string): FunctionDecision;
+    /** An action `functionCall` to a host function: gate, consent, run. A
+     *  built-in other than openUrl and bind has no effect as an action. */
+    callFunction(call: FunctionCallInfo): Promise<FunctionOutcome>;
+    /** VAPP-122: the `bind` action: re-follow `path` from `source` with
+     *  `params` appended (`sourceWithParams`), through the router like a
+     *  server's bindDataModel (the surface's package allowlist applies; a
+     *  refusal is the usual SOURCE_DENIED / VALIDATION_FAILED error). True
+     *  when the bind op ran. */
+    bind(surfaceId: string, args: Record<string, unknown>): boolean;
+    /** The URL policy every href passes (relative urls against the urls' or
+     *  the media `baseUrl`). */
+    urlPolicy(): UrlPolicy;
+    /** openUrl / Link through the URL policy. True when it opened. */
+    openUrl(url: string): boolean;
+    /** A renderer's painter for `componentId` failed. Reported ONCE per
+     *  surface + component id (whatever the message) as an A2UI
+     *  `RENDER_FAILED` error (and so a host issue), and not again until that
+     *  component's props change (an `updateComponents` naming it, or the
+     *  surface re-created). A part or template-instance id counts under the
+     *  flat component it belongs to (`card.body` → `card`), so the record is
+     *  bounded by the surface's components. */
+    paintError(error: {
+        surfaceId: string;
+        componentId: string;
+        message: string;
+    }): void;
+    private forgetPaintErrors;
+    /** The media policy every src passes (`policy.media`). */
+    mediaOptions(): MediaOptions | undefined;
+    /** The image loader's request (absolute url + auth headers). */
+    mediaRequest(url: string): MediaRequest | null;
+}
+export {};

package/dist/types/src/host/signature.d.ts

@@ -0,0 +1,52 @@
+import type { PackageIssue } from "./package.js";
+/** The context the signed bytes start with. */
+export declare const PACKAGE_FILE_SIGNATURE_CONTEXT = "exponential-ui/package-file/v1\n";
+export declare const PACKAGE_FILE_SIGNATURE_ALG = "ed25519";
+export declare const AUTHOR_KEY_PREFIX = "ed25519:";
+export declare const AUTHOR_NAME_MAX = 80;
+export interface PackageFileAuthor {
+    name: string;
+    /** `ed25519:` + the 32-byte public key, unpadded base64url. */
+    key: string;
+}
+export interface PackageFileSignature {
+    alg: `ed25519`;
+    /** The 64-byte signature, unpadded base64url. */
+    value: string;
+}
+export type PackageFileVerification = {
+    status: `unsigned`;
+} | {
+    status: `valid`;
+    author: PackageFileAuthor;
+} | {
+    status: `invalid`;
+    issues: PackageIssue[];
+};
+/** RFC 8785 (JCS): no whitespace, keys sorted by UTF-16 code units, strings
+ *  and numbers as ECMAScript's JSON.stringify writes them (`1`, `1e+21`, `-0`
+ *  = `0`); an undefined member is skipped. Throws on a non-finite number or a
+ *  value JSON has no form for. */
+export declare function canonicalJson(value: unknown): string;
+/** What the signature covers: the context line + the canonical JSON of the
+ *  file without `signature`, as UTF-8. */
+export declare function packageFileSignedBytes(file: Record<string, unknown>): Uint8Array<ArrayBuffer>;
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+/** Strict: the url-safe alphabet, no padding; null otherwise. */
+export declare function base64UrlDecode(text: string): Uint8Array<ArrayBuffer> | null;
+/** The 32-byte public key of `author.key`; null when malformed. */
+export declare function authorPublicKey(key: unknown): Uint8Array<ArrayBuffer> | null;
+/** The file signed by the holder of the 32-byte Ed25519 `seed`, as
+ *  `author` `name`: every key but `signature` kept, then `author` and
+ *  `signature` (replaced when present). */
+export declare function signPackageFile<T extends Record<string, unknown>>(file: T, signer: {
+    name: string;
+    seed: Uint8Array;
+}): Promise<Omit<T, `author` | `signature`> & {
+    author: PackageFileAuthor;
+    signature: PackageFileSignature;
+}>;
+/** Is the file signed, and by whom: `unsigned` without `signature` (an
+ *  `author` alone is an unverified claim), `valid` with the author, or
+ *  `invalid` with every problem as a JSON pointer. */
+export declare function verifyPackageFile(file: unknown): Promise<PackageFileVerification>;

package/dist/types/src/host/sources.d.ts

@@ -0,0 +1,22 @@
+export interface ParsedSource {
+    /** The source as written. */
+    uri: string;
+    scheme: string;
+    name: string;
+    params: Record<string, string>;
+}
+/** `exp:issues?board=b1&limit=20` → `{scheme: "exp", name: "issues",
+ *  params: {board: "b1", limit: "20"}}`; null when it does not parse. */
+export declare function parseSource(uri: string): ParsedSource | null;
+/** What a resolver emits into: the value lands at the bound path. */
+export type SourceEmit = (value: unknown) => void;
+/** A scheme's resolver: start following `source`, return the cancel. */
+export type SourceResolver = (source: ParsedSource, emit: SourceEmit) => (() => void) | void;
+export type SourceResolvers = Record<string, SourceResolver>;
+/** VAPP-122: `source` with `params` appended as its query, for the `bind`
+ *  action (`{functionCall: {call: "bind", args: {path, source, params}}}`):
+ *  keys sorted, key and value percent-encoded (everything but
+ *  `A-Z a-z 0-9 - _ . ! ~ * ' ( )`), a null or undefined value skipped, an
+ *  object or array as JSON, after `?` or `&`. A repeated key parses with
+ *  the last value, so a param overrides the source's own. */
+export declare function sourceWithParams(source: string, params?: Record<string, unknown> | null): string;

package/dist/types/src/host/tools.d.ts

@@ -0,0 +1,42 @@
+import type { PackageIssue } from "./package.js";
+/** `^[a-z][a-z0-9_-]{0,31}$`: a tool's id. */
+export declare const TOOL_ID_PATTERN: RegExp;
+export declare const TOOL_KINDS: readonly string[];
+export interface PackageTool {
+    kind: `mcp` | `script`;
+    title: string;
+    description?: string;
+    /** A remote MCP server (Streamable HTTP). */
+    url?: string;
+    /** A local MCP server (stdio) or the script's process. */
+    command?: string;
+    args?: string[];
+    /** Variable NAMES the host passes through, never values. */
+    env?: string[];
+}
+/** One row of the consent card. */
+export interface ToolConsentRow {
+    id: string;
+    kind: `mcp` | `script`;
+    transport: `http` | `stdio` | `script`;
+    title: string;
+    description: string | null;
+    /** The url, or the command line exactly as it runs. */
+    target: string;
+    env: string[];
+}
+/** Every problem with a package's `tools`, ids in sorted order. */
+export declare function validateTools(tools: unknown): PackageIssue[];
+/** The consent card's rows for a (valid) package's tools, by id. */
+export declare function toolConsent(pkg: {
+    tools?: Record<string, PackageTool>;
+}): ToolConsentRow[];
+/** The key a remembered grant is stored under: ANY change to the tool's
+ *  definition is a new key (the card asks again). */
+export declare function toolConsentKey(packageId: string, toolId: string, tool: PackageTool): string;
+/** The tool a host function name calls: `tools.<id>` (a script) or
+ *  `tools.<id>.<name>` (an MCP server's tool); null = not a tool call. */
+export declare function toolCall(name: string): {
+    toolId: string;
+    tool: string | null;
+} | null;

package/dist/types/src/host/transports.d.ts

@@ -0,0 +1,109 @@
+import type { ClientMessage } from "./contract.js";
+import { JsonlDecoder, SseDecoder } from "./decoders.js";
+import type { Decoded } from "./decoders.js";
+import type { Transport, TransportStatus } from "./runtime.js";
+type Receive = (message: unknown) => void;
+type Status = (status: TransportStatus, detail?: string) => void;
+/** In-memory: `feed` messages in, read what the host sent from `sent`. */
+export declare class MemoryTransport implements Transport {
+    readonly sent: ClientMessage[];
+    private receiveFn?;
+    private pending;
+    onSend?: (message: ClientMessage) => void;
+    start(receive: Receive, status: Status): void;
+    feed(...messages: unknown[]): void;
+    /** JSONL text, as a stream server would send it. */
+    feedJsonl(text: string): void;
+    send(message: ClientMessage): void;
+    close(): void;
+}
+export interface HttpTransportOptions {
+    /** The stream to read (GET). */
+    url: string;
+    /** Where client messages go (POST, JSON body); default `url`. */
+    postUrl?: string;
+    headers?: Record<string, string>;
+    /** Reconnect after a drop (an error or an aborted stream), ms (0 =
+     *  never). Default 2000. */
+    reconnectMs?: number;
+    /** Reconnect after a CLEAN end of the stream too (the server resumes it).
+     *  Default false: a stream that ends is done (status `closed`). An SSE
+     *  stream that sent a `retry:` field signals this itself. */
+    resumable?: boolean;
+    fetch?: typeof fetch;
+}
+declare abstract class StreamTransport implements Transport {
+    protected options: HttpTransportOptions;
+    private controller?;
+    /** Bumped by every start/close: a loop whose generation is stale exits
+     *  (an old loop asleep in its reconnect wait never runs beside a new
+     *  one). */
+    private generation;
+    constructor(options: HttpTransportOptions);
+    protected abstract decoder(): {
+        push(chunk: string): Decoded;
+        end(): Decoded;
+        retryMs?: number;
+    };
+    protected abstract accept(): string;
+    start(receive: Receive, status: Status): void;
+    private run;
+    send(message: ClientMessage): Promise<void>;
+    close(): void;
+}
+/** A2UI JSONL over a streamed HTTP response (`application/jsonl`). */
+export declare class JsonlStreamTransport extends StreamTransport {
+    protected decoder(): JsonlDecoder;
+    protected accept(): string;
+}
+/** Server-Sent Events read through fetch (headers allowed, unlike
+ *  EventSource). */
+export declare class SseTransport extends StreamTransport {
+    protected decoder(): SseDecoder;
+    protected accept(): string;
+}
+/** One A2UI message (or JSONL) per frame; client messages go back as
+ *  frames. */
+export declare class WebSocketTransport implements Transport {
+    private options;
+    private socket?;
+    /** Bumped by every start/close: a stale socket's reconnect timer is a
+     *  no-op. */
+    private generation;
+    constructor(options: {
+        url: string;
+        protocols?: string | string[];
+        reconnectMs?: number;
+        WebSocket?: typeof WebSocket;
+    });
+    start(receive: Receive, status: Status): void;
+    send(message: ClientMessage): void;
+    close(): void;
+}
+export interface McpTransportOptions {
+    /** The MCP server's streamable-HTTP endpoint. */
+    url: string;
+    /** The tool whose result carries the surface (called once at start). */
+    tool: string;
+    arguments?: Record<string, unknown>;
+    /** The tool client messages go to; default `a2ui_event`. */
+    actionTool?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}
+/** A2UI over MCP: calls `tool`, delivers the A2UI resources in its result,
+ *  and sends every client message as a tools/call to `actionTool` (its
+ *  result may carry more messages). JSON-RPC over plain POST; an SSE
+ *  response body is read through the SSE decoder. */
+export declare class McpTransport implements Transport {
+    private options;
+    private id;
+    private receiveFn?;
+    private session?;
+    constructor(options: McpTransportOptions);
+    start(receive: Receive, status: Status): void;
+    send(message: ClientMessage): Promise<void>;
+    close(): void;
+    private rpc;
+}
+export {};