@peers-app/peers-sdk 0.26.6 → 0.27.0

package/dist/contracts/frozen-contracts.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FROZEN_CONTRACTS_FILE = void 0;
+exports.checkFrozenContracts = checkFrozenContracts;
+exports.freezeContracts = freezeContracts;
+exports.describeFrozenContractChanges = describeFrozenContractChanges;
+const validate_1 = require("./validate");
+// A stable package release freezes every contract version it provides: its shape can't change
+// again, only its descriptions and tool policy. A package records what its stable releases froze
+// in `frozen-contracts.json`, checked in at its root, so its build and tests can refuse a change
+// before a release ships one. `peers-package contract freeze` writes it.
+/** The file, at a package's root, that records the contract versions its stable releases froze. */
+exports.FROZEN_CONTRACTS_FILE = "frozen-contracts.json";
+const ABOUT = "Contract versions this package's stable releases froze. A frozen version's shape can't change (descriptions and tool policy can); declare a new version instead. Written by `peers-package contract freeze`.";
+const key = (contract) => `${contract.contractId}@${contract.version}`;
+/**
+ * Check the contracts a package provides against the versions its stable releases froze.
+ *
+ * @param frozen - The package's `frozen-contracts.json`.
+ * @param provided - The contracts the package provides now. A `devTag` is ignored.
+ * @returns The frozen versions it changed, and those it no longer provides.
+ * @throws When the package provides the same contract identity more than once.
+ */
+function checkFrozenContracts(frozen, provided) {
+    const current = new Map();
+    for (const contract of provided) {
+        const identity = key(contract);
+        if (current.has(identity))
+            throw new Error(`Duplicate provided contract ${identity}`);
+        current.set(identity, contract);
+    }
+    const check = { changed: [], notProvided: [] };
+    for (const contract of frozen.contracts) {
+        const now = current.get(key(contract));
+        if (!now) {
+            check.notProvided.push(contract);
+            continue;
+        }
+        const changes = (0, validate_1.contractShapeChanges)(contract, toJson(now));
+        if (changes.length > 0)
+            check.changed.push({ contract, changes });
+    }
+    return check;
+}
+/**
+ * Record every contract version a release provides as frozen by that release, keeping the
+ * versions already frozen. Refuses (records nothing) when the release changed a frozen version.
+ *
+ * @param frozen - The package's `frozen-contracts.json`, or undefined when it has none yet.
+ * @param provided - The contracts the release provides.
+ * @param packageVersion - The release's package version.
+ * @returns The file's new content, the versions it added, and the check that decided.
+ * @throws When the package version is blank or provided contract identities repeat.
+ */
+function freezeContracts(frozen, provided, packageVersion) {
+    if (typeof packageVersion !== "string" || !packageVersion.trim()) {
+        throw new Error("The package has no version to freeze its contracts as");
+    }
+    const existing = frozen ?? { contracts: [] };
+    const check = checkFrozenContracts(existing, provided);
+    if (check.changed.length > 0)
+        return { frozen: existing, added: [], check };
+    const known = new Set(existing.contracts.map(key));
+    const added = provided
+        .filter((contract) => !known.has(key(contract)))
+        .map((contract) => frozenContract(contract, packageVersion));
+    const contracts = [...existing.contracts, ...added].sort((a, b) => key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0);
+    return { frozen: { about: ABOUT, contracts }, added, check };
+}
+/**
+ * Describe a check's failures, one line per changed contract version, for a build or test error.
+ *
+ * @param check - What {@link checkFrozenContracts} found.
+ */
+function describeFrozenContractChanges(check) {
+    return check.changed.map(({ contract, changes }) => `${contract.name} (${key(contract)}), frozen by ${contract.frozenBy}: ${changes.join("; ")}. Declare a new version instead.`);
+}
+/** A provided contract as a frozen entry: JSON data, without its dev tag. */
+function frozenContract(contract, packageVersion) {
+    const { devTag: _dev, ...shape } = toJson(contract);
+    return { ...shape, frozenBy: packageVersion };
+}
+/** A definition as JSON data; legacy default factories are omitted without executing them. */
+function toJson(contract) {
+    return JSON.parse(JSON.stringify(contract));
+}

package/dist/contracts/host-contract-client.d.ts

@@ -0,0 +1,134 @@
+import type { IDataChangedEvent } from "../data/orm/subscribable.data-source";
+import { type AnyContractTools, type ContractEventPayloadsOf, type ContractIdOf, type ContractObservableValuesOf, type ContractObservableWritabilityOf, type ContractTableInputsOf, type ContractTableRowsOf, type ContractToolsOf, type ContractVersionOf, type IContractRef } from "../define/contract-ref";
+import type { IPackageTableHandle } from "../define/table";
+import { type Observable, type ReadonlyObservable } from "../observable";
+import { type IContractSubscription } from "./contract-proxy";
+/** Options for a subscription made through a {@link hostContract} client. */
+export interface IHostSubscribeOptions {
+    /**
+     * Called each time the subscription is live again after the host connection was replaced
+     * (a reconnect), including when its first attachment failed (`ready` resolved `false`).
+     * Anything sent while it was down was missed, so read again.
+     */
+    onReconnect?: () => void;
+}
+/**
+ * A table on a {@link hostContract} client: the same methods as a package's own table handle,
+ * plus `dataChanged`. Every call goes through the providing package's table (its class, if it
+ * has one), so `save` takes the schema's input and the provider's defaults and transforms apply.
+ */
+export interface IHostContractTable<T extends Record<string, any>, TInput = T> extends IPackageTableHandle<T, TInput> {
+    /** Changes to the table's rows, pushed by the provider. */
+    readonly dataChanged: {
+        subscribe(handler: (event: IDataChangedEvent<T>) => void, options?: IHostSubscribeOptions): IContractSubscription;
+    };
+}
+/** An event on a {@link hostContract} client. */
+export interface IHostContractEvent<P> {
+    /** Receive each payload the provider emits from now on. */
+    subscribe(handler: (payload: P) => void, options?: IHostSubscribeOptions): IContractSubscription;
+}
+type HostTable<R, I> = R extends Record<string, any> ? IHostContractTable<R, I> : never;
+/**
+ * A UI's client for one contract on the local host, typed from its reference. Every member is
+ * made on first use. Calls wait for the host connection, and fail if it is lost or replaced
+ * before they reply; subscriptions and observables follow it across reconnects.
+ */
+export interface IHostContractClient<T> {
+    /** The contract's id. */
+    readonly contractId: string;
+    /** The contract's version. */
+    readonly version: number;
+    /** Tools: `await news.tools.refresh()`. */
+    readonly tools: ContractToolsOf<T>;
+    /** Tables the contract exposes: `await news.tables.Feeds.list()`. */
+    readonly tables: {
+        readonly [K in keyof ContractTableRowsOf<T>]: HostTable<ContractTableRowsOf<T>[K], K extends keyof ContractTableInputsOf<T> ? ContractTableInputsOf<T>[K] : never>;
+    };
+    /** Events: `weather.events.alert.subscribe((payload) => …)`. */
+    readonly events: {
+        readonly [K in keyof ContractEventPayloadsOf<T>]: IHostContractEvent<ContractEventPayloadsOf<T>[K]>;
+    };
+    /**
+     * Observables, as live local copies: read with `weather.observables.location()` (or
+     * `useObservable`), write with `weather.observables.location(value)`. Each subscribes on first
+     * access and reads `undefined` until the provider's value arrives. A write the provider refuses
+     * (the observable is read-only, or the value doesn't fit) is logged, and the copy reads the
+     * provider's value again. A write still awaiting its reply when the connection is replaced is
+     * logged as failed too, along with writes queued on that connection. Writes made while
+     * disconnected or after reconnecting can use the new connection, and the copy follows its
+     * value. Read-only declarations expose only the read and subscription methods. Await an
+     * observable's `loadingPromise` before relying on its initial value; it resolves after the
+     * first snapshot attempt or disposal, including if that read failed (and was logged).
+     */
+    readonly observables: {
+        readonly [K in keyof ContractObservableValuesOf<T>]: (true extends (K extends keyof ContractObservableWritabilityOf<T> ? ContractObservableWritabilityOf<T>[K] : boolean) ? Observable<ContractObservableValuesOf<T>[K] | undefined> : ReadonlyObservable<ContractObservableValuesOf<T>[K] | undefined>) & {
+            /** Settles after the first snapshot attempt, or when the client is disposed. */
+            readonly loadingPromise: Promise<void>;
+        };
+    };
+    /** Cancel connection waits, end subscriptions, and refuse new calls and writes. Idempotent. */
+    dispose(): void;
+}
+/** Options for {@link hostContract}. */
+export interface IHostContractOptions {
+    /**
+     * The data context every call is scoped to, read when the client connects (and again after a
+     * reconnect). Defaults to the active group, or the personal context when none is active.
+     */
+    dataContextId?: () => Promise<string | undefined>;
+    /** How long a call waits for the host connection before it fails. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /**
+     * Reach this provider of the contract rather than the group's default: to show a widget for
+     * every installed provider, say.
+     */
+    providerPackageId?: string;
+}
+/**
+ * Replace the default data context for clients made without one, or restore it with
+ * `undefined`. Test hosts use it, where there is no signed-in user. Not exported from the SDK.
+ *
+ * @internal
+ * @param resolver - Resolves the data context each time a client connects.
+ */
+export declare function setDefaultHostDataContextId(resolver: (() => Promise<string | undefined>) | undefined): void;
+/**
+ * A UI's client for a contract on the local host: tools, tables (with `dataChanged`), events,
+ * and observables, typed from the reference.
+ *
+ * ```ts
+ * import type { News } from "../package"; // types only: no handler code in the UI bundle
+ * export const news = hostContract<typeof News>(contractId, contractVersion);
+ *
+ * const headlines = await news.tables.Headlines.list({}, { pageSize: 100 });
+ * await news.tools.refresh();
+ * ```
+ *
+ * The client needs no contract definition: members are made on first use. Calls wait for the
+ * host connection (up to `timeoutMs`). A tool or table call still waiting for its reply when
+ * the connection is lost or replaced fails, though the provider may have run it. Subscriptions
+ * and observables wait as long as it takes, and re-attach after a reconnect. Subscription `ready` acknowledges the first attachment;
+ * `onReconnect` runs once each replacement subscription is live. Dispose independent clients
+ * made with options when their owner ends; shared clients normally live for the window.
+ *
+ * Calls are scoped to the active group, read when the client connects; switching groups
+ * reloads the window. Without options, every call for the same contract id and version
+ * returns the same client, even from a new reference.
+ *
+ * Calls act as the signed-in user, like every UI call today. Without a contract type, the
+ * client is untyped, as with an untyped `contractRef`.
+ *
+ * @param contractId - The contract's id; with a contract type, it must be that contract's.
+ * @param version - The contract's version; with a contract type, it must be that contract's.
+ * @param options - Data context, provider, and connection wait.
+ */
+export declare function hostContract<T = AnyContractTools>(contractId: ContractIdOf<T>, version: ContractVersionOf<T>, options?: IHostContractOptions): IHostContractClient<T>;
+/**
+ * A UI's client for a contract on the local host, from `contractRef` or `declareContract`.
+ *
+ * @param ref - From `contractRef` or `declareContract`, typed with the contract.
+ * @param options - Data context, provider, and connection wait.
+ */
+export declare function hostContract<T>(ref: IContractRef<T>, options?: IHostContractOptions): IHostContractClient<T>;
+export {};

package/dist/contracts/host-contract-client.js

@@ -0,0 +1,396 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setDefaultHostDataContextId = setDefaultHostDataContextId;
+exports.hostContract = hostContract;
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const contract_ref_1 = require("../define/contract-ref");
+const lazy_members_1 = require("../define/lazy-members");
+const table_handle_1 = require("../define/table-handle");
+const observable_1 = require("../observable");
+const contract_proxy_1 = require("./contract-proxy");
+const host_contract_transport_1 = require("./host-contract-transport");
+/** Default wait for the host connection before a call fails. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** Shared clients, one per contract id and version, for `hostContract` without options. */
+const sharedClients = new Map();
+async function activeDataContextId() {
+    if (defaultDataContextId) {
+        return defaultDataContextId();
+    }
+    const user = await (0, user_context_singleton_1.getUserContext)();
+    return user.currentlyActiveGroupId() || user.userId;
+}
+let defaultDataContextId;
+/**
+ * Replace the default data context for clients made without one, or restore it with
+ * `undefined`. Test hosts use it, where there is no signed-in user. Not exported from the SDK.
+ *
+ * @internal
+ * @param resolver - Resolves the data context each time a client connects.
+ */
+function setDefaultHostDataContextId(resolver) {
+    defaultDataContextId = resolver;
+}
+/** Implementation of both forms. */
+function hostContract(...args) {
+    let ref;
+    let options;
+    if (typeof args[0] === "string") {
+        ref = (0, contract_ref_1.contractRef)(args[0], args[1]);
+        options = args[2];
+    }
+    else {
+        ref = args[0];
+        options = args[1];
+    }
+    if (typeof ref !== "function" || ref.kind !== "contract-ref") {
+        throw new Error("hostContract takes (contractId, version) or a reference from contractRef(contractId, version)");
+    }
+    if (options === undefined) {
+        const key = `${ref.contractId}@${ref.version}`;
+        const shared = sharedClients.get(key);
+        if (shared) {
+            return shared;
+        }
+        const client = createHostContractClient(ref, {}, () => sharedClients.delete(key));
+        sharedClients.set(key, client);
+        return client;
+    }
+    return createHostContractClient(ref, options, () => { });
+}
+/** Stop waiting for a context lookup or reply when its connection or caller ends. */
+function abortable(promise, signals) {
+    const aborted = signals.find((signal) => signal.aborted);
+    if (aborted)
+        return Promise.reject(aborted.reason);
+    return new Promise((resolve, reject) => {
+        const finish = (action) => {
+            for (const signal of signals)
+                signal.removeEventListener("abort", abort);
+            action();
+        };
+        const abort = () => finish(() => reject(signals.find((signal) => signal.aborted)?.reason));
+        for (const signal of signals)
+            signal.addEventListener("abort", abort, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
+/**
+ * Stop waiting for a reply once its connection is lost or replaced: a dropped socket never
+ * answers. The request may still have reached the provider. A reply already on its way, or a
+ * transport that fails its calls as it closes, gets a turn to land first: the provider's answer
+ * beats the guess that it was lost, so a call that ran isn't reported as failed.
+ */
+function untilReplaced(reply, signal) {
+    reply.catch(() => undefined);
+    return new Promise((resolve, reject) => {
+        let timer;
+        const replaced = () => {
+            timer = setTimeout(() => reject(signal.reason), 0);
+        };
+        const settle = (finish) => {
+            signal.removeEventListener("abort", replaced);
+            clearTimeout(timer);
+            finish();
+        };
+        if (signal.aborted)
+            replaced();
+        else
+            signal.addEventListener("abort", replaced, { once: true });
+        reply.then((value) => settle(() => resolve(value)), (error) => settle(() => reject(error)));
+    });
+}
+function createHostContractClient(ref, options, onDispose) {
+    const { contractId, version } = ref;
+    if (options.providerPackageId !== undefined &&
+        (typeof options.providerPackageId !== "string" || options.providerPackageId.trim() === "")) {
+        throw new Error("hostContract providerPackageId must be a non-empty package id");
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const resolveDataContextId = options.dataContextId ?? activeDataContextId;
+    let disposed = false;
+    let connection;
+    let pending;
+    let unwatch;
+    /** Re-attach callbacks for every live subscription and observable. */
+    const followers = new Map();
+    const lifetime = new AbortController();
+    let contextLifetime = new AbortController();
+    const disposedError = () => new Error(`Host contract ${contractId} v${version} is disposed`);
+    const watchTransport = () => {
+        if (unwatch) {
+            return;
+        }
+        unwatch = (0, host_contract_transport_1.subscribeHostContractTransport)(() => {
+            contextLifetime.abort(new Error(`Host connection for ${contractId} v${version} was lost or replaced`));
+            contextLifetime = new AbortController();
+            pending = undefined;
+            if (connection) {
+                connection.members.dispose();
+                connection = undefined;
+            }
+            for (const follower of [...followers.keys()]) {
+                follower();
+            }
+        }, { emitCurrent: false });
+    };
+    /** The connection for the current transport, made on first use. */
+    const connect = async (wait) => {
+        const signal = wait.signal ?? lifetime.signal;
+        for (;;) {
+            if (disposed) {
+                throw disposedError();
+            }
+            if (signal.aborted)
+                throw signal.reason;
+            watchTransport();
+            const transport = (0, host_contract_transport_1.getHostContractTransport)() ?? (await (0, host_contract_transport_1.waitForHostContractTransport)({ ...wait, signal }));
+            if (disposed) {
+                throw disposedError();
+            }
+            if ((0, host_contract_transport_1.getHostContractTransport)() !== transport) {
+                continue;
+            }
+            if (connection?.transport === transport) {
+                return connection;
+            }
+            if (pending?.transport !== transport) {
+                pending = { transport, dataContextId: resolveDataContextId() };
+            }
+            const request = pending;
+            const contextSignal = contextLifetime.signal;
+            let dataContextId;
+            try {
+                dataContextId = await abortable(request.dataContextId, [contextSignal, signal]);
+            }
+            catch (error) {
+                if (!disposed && !signal.aborted && contextSignal.aborted)
+                    continue;
+                if (pending === request) {
+                    pending = undefined;
+                }
+                throw error;
+            }
+            if (disposed) {
+                throw disposedError();
+            }
+            if (contextSignal.aborted || (0, host_contract_transport_1.getHostContractTransport)() !== transport) {
+                continue;
+            }
+            if (connection?.transport !== transport) {
+                connection = {
+                    transport,
+                    signal: contextSignal,
+                    members: (0, contract_proxy_1.createContractConsumerMembers)(contractId, version, transport, {
+                        ...(dataContextId ? { dataContextId } : {}),
+                        ...(options.providerPackageId ? { providerPackageId: options.providerPackageId } : {}),
+                    }),
+                };
+            }
+            return connection;
+        }
+    };
+    /**
+     * Keep a subscription attached to the current connection: now (once connected), and again
+     * after every reconnect, when `onReconnect` runs.
+     */
+    const follow = (attach, onReconnect) => {
+        if (disposed)
+            throw disposedError();
+        let active = true;
+        let current;
+        let attachedBefore = false;
+        let attempt;
+        let settleReady;
+        const ready = new Promise((resolve) => {
+            settleReady = resolve;
+        });
+        const reattach = async (signal) => {
+            try {
+                const next = await connect({ signal });
+                if (!active || signal.aborted || connection !== next || current?.connection === next)
+                    return;
+                current?.subscription.unsubscribe();
+                const subscription = attach(next.members);
+                const attached = { connection: next, subscription };
+                current = attached;
+                const live = await (subscription.ready ?? Promise.resolve(true));
+                if (!active || signal.aborted || current !== attached)
+                    return;
+                if (!live) {
+                    settleReady(false);
+                    attachedBefore = true;
+                    return;
+                }
+                settleReady(true);
+                if (attachedBefore)
+                    onReconnect?.();
+                attachedBefore = true;
+            }
+            catch (error) {
+                if (active && !disposed && !signal.aborted) {
+                    settleReady(false);
+                    // `ready` already said false, so report a later attachment as a reconnect.
+                    attachedBefore = true;
+                    console.error("Host contract subscription failed", error);
+                }
+            }
+        };
+        const run = () => {
+            attempt?.abort();
+            if (current && current.connection !== connection) {
+                current.subscription.unsubscribe();
+                current = undefined;
+            }
+            attempt = new AbortController();
+            void reattach(attempt.signal);
+        };
+        const unsubscribe = () => {
+            if (!active)
+                return false;
+            active = false;
+            attempt?.abort();
+            followers.delete(run);
+            current?.subscription.unsubscribe();
+            current = undefined;
+            settleReady(false);
+            return true;
+        };
+        followers.set(run, unsubscribe);
+        run();
+        return { ready, unsubscribe };
+    };
+    /** Make a call on the current connection; it fails if that connection is replaced first. */
+    const call = async (send) => {
+        const next = await connect({ timeoutMs });
+        return untilReplaced(Promise.resolve().then(() => send(next.members)), next.signal);
+    };
+    const tools = (0, lazy_members_1.lazyMembers)((toolName) => (...args) => call((members) => members.tool(toolName)(...args)));
+    const tables = (0, lazy_members_1.lazyMembers)((tableName) => ({
+        ...(0, table_handle_1.packageTableMethods)((operation, args) => call((members) => members.table(tableName)[operation](...args))),
+        dataChanged: {
+            subscribe: (handler, subscribeOptions) => follow((members) => members.table(tableName).dataChanged.subscribe(handler), subscribeOptions?.onReconnect),
+        },
+    }));
+    const events = (0, lazy_members_1.lazyMembers)((eventName) => ({
+        subscribe: (handler, subscribeOptions) => follow((members) => members.event(eventName).subscribe(handler), subscribeOptions?.onReconnect),
+    }));
+    const observables = (0, lazy_members_1.lazyMembers)((observableName) => {
+        const local = (0, observable_1.observable)();
+        let finishLoading;
+        const loadingPromise = new Promise((resolve) => {
+            finishLoading = () => {
+                lifetime.signal.removeEventListener("abort", finishLoading);
+                resolve();
+            };
+        });
+        if (disposed)
+            finishLoading();
+        else
+            lifetime.signal.addEventListener("abort", finishLoading, { once: true });
+        let mirror;
+        let applying = false;
+        let localRevision = 0;
+        let remoteRevision = 0;
+        // Each value has its own ordered write queue. Retire writes queued on a replaced connection;
+        // writes made during an outage wait for the next one rather than target a disposed mirror.
+        let writes = Promise.resolve();
+        const apply = (value) => {
+            applying = true;
+            try {
+                local(value);
+            }
+            finally {
+                applying = false;
+            }
+        };
+        // A reply lost with its connection would hold every later write, so writes stop waiting
+        // once the connection is replaced; the next mirror brings its value.
+        local.subscribe((value) => {
+            if (applying)
+                return;
+            const written = ++localRevision;
+            const queuedOn = (0, host_contract_transport_1.getHostContractTransport)() ? contextLifetime.signal : lifetime.signal;
+            writes = writes.then(async () => {
+                try {
+                    const next = await connect({ timeoutMs, signal: queuedOn });
+                    if (next.signal.aborted)
+                        throw next.signal.reason;
+                    const before = remoteRevision;
+                    const result = await untilReplaced(next.members.setObservable(observableName, value), next.signal);
+                    if (!disposed &&
+                        connection === next &&
+                        remoteRevision === before &&
+                        localRevision === written) {
+                        apply(result);
+                    }
+                }
+                catch (error) {
+                    if (!disposed) {
+                        console.error("Contract observable set failed", error);
+                        const current = mirror;
+                        const signal = contextLifetime.signal;
+                        await untilReplaced(current?.refresh() ?? Promise.resolve(), signal).catch(() => undefined);
+                        if (current && mirror === current && !disposed && localRevision === written) {
+                            apply(current.observable());
+                        }
+                    }
+                }
+            });
+        });
+        follow((members) => {
+            // The provider decides writability: no definition is needed in this client.
+            const made = members.observable(observableName, true, () => { });
+            mirror = made;
+            const subscription = made.observable.subscribe((value) => {
+                remoteRevision++;
+                apply(value);
+            });
+            void made.loaded.then(() => {
+                if (mirror === made)
+                    finishLoading();
+            });
+            return {
+                unsubscribe: () => {
+                    subscription.dispose();
+                    if (mirror === made)
+                        mirror = undefined;
+                    return true;
+                },
+            };
+        });
+        const exposed = ((...args) => {
+            if (args.length === 0)
+                return local();
+            if (disposed)
+                throw disposedError();
+            return local(args[0]);
+        });
+        exposed.subscribe = local.subscribe;
+        exposed.notifySubscribers = local.notifySubscribers;
+        exposed.subscriberCount = local.subscriberCount;
+        return Object.assign(exposed, { loadingPromise });
+    });
+    return Object.freeze({
+        contractId,
+        version,
+        tools,
+        tables,
+        events,
+        observables,
+        dispose: () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            lifetime.abort(disposedError());
+            contextLifetime.abort(disposedError());
+            for (const unsubscribe of [...followers.values()])
+                unsubscribe();
+            unwatch?.();
+            connection?.members.dispose();
+            connection = undefined;
+            onDispose();
+        },
+    });
+}

package/dist/contracts/host-contract-transport.d.ts

@@ -31,8 +31,10 @@ export declare function subscribeHostContractTransport(listener: HostContractTra
  * Wait for the next available UI-to-host contract transport.
  *
  * @param opts.timeoutMs Optional deadline; rejects if no transport registers in time.
+ * @param opts.signal Cancels the wait and releases its listener.
  * @returns The current transport immediately, or the next registered transport.
  */
 export declare function waitForHostContractTransport(opts?: {
     timeoutMs?: number;
+    signal?: AbortSignal;
 }): Promise<IContractTransport>;

package/dist/contracts/host-contract-transport.js

@@ -70,9 +70,14 @@ function subscribeHostContractTransport(listener, opts = {}) {
  * Wait for the next available UI-to-host contract transport.
  *
  * @param opts.timeoutMs Optional deadline; rejects if no transport registers in time.
+ * @param opts.signal Cancels the wait and releases its listener.
  * @returns The current transport immediately, or the next registered transport.
  */
 function waitForHostContractTransport(opts = {}) {
+    const { signal } = opts;
+    if (signal?.aborted) {
+        return Promise.reject(signal.reason);
+    }
     const current = getHostContractTransport();
     if (current) {
         return Promise.resolve(current);
@@ -90,6 +95,7 @@ function waitForHostContractTransport(opts = {}) {
                 clearTimeout(timer);
             }
             unsubscribe();
+            signal?.removeEventListener("abort", abort);
             action();
         };
         const unsubscribe = subscribeHostContractTransport((transport) => {
@@ -98,6 +104,8 @@ function waitForHostContractTransport(opts = {}) {
             }
             finish(() => resolve(transport));
         }, { emitCurrent: false });
+        const abort = () => finish(() => reject(signal?.reason));
+        signal?.addEventListener("abort", abort, { once: true });
         if (timeoutMs !== undefined) {
             timer = setTimeout(() => {
                 finish(() => reject(new Error(`Timed out waiting for host contract transport after ${timeoutMs}ms`)));