@net-mesh/browser 0.37.0

package/dist/async-queue.js

@@ -0,0 +1,62 @@
+/**
+ * The one-consumer async queue behind every async iterable in this
+ * package (`node.events()`, `stream`).
+ *
+ * Items that arrive while the consumer is not awaiting are buffered in
+ * arrival order; buffering stops the moment the loop is left (`break`,
+ * `return`, or an exception), which is what calls the `detach` hook, so
+ * a page that stops consuming stops paying. A page that starts a loop
+ * and then never awaits it will grow the buffer — leave the loop
+ * instead of abandoning it.
+ */
+export class AsyncQueue {
+    detach;
+    buffered = [];
+    waiting = null;
+    ended = false;
+    /** @param detach called once when the consumer stops iterating. */
+    constructor(detach = () => { }) {
+        this.detach = detach;
+    }
+    /** Hand an item to the consumer, or buffer it. */
+    push(item) {
+        if (this.ended)
+            return;
+        const waiting = this.waiting;
+        if (waiting) {
+            this.waiting = null;
+            waiting({ value: item, done: false });
+            return;
+        }
+        this.buffered.push(item);
+    }
+    /** End the iteration once the buffer drains. */
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        const waiting = this.waiting;
+        if (waiting) {
+            this.waiting = null;
+            waiting({ value: undefined, done: true });
+        }
+    }
+    next() {
+        const buffered = this.buffered.shift();
+        if (buffered !== undefined)
+            return Promise.resolve({ value: buffered, done: false });
+        if (this.ended)
+            return Promise.resolve({ value: undefined, done: true });
+        const { promise, resolve } = Promise.withResolvers();
+        this.waiting = resolve;
+        return promise;
+    }
+    return() {
+        this.detach();
+        this.end();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}

package/dist/credential.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `requestCredential` — ask a game anchor for an anonymous visitor
+ * credential, so a page connects with no hand-minted secret.
+ *
+ * ```ts
+ * import { openSession, requestCredential } from '@net-mesh/browser';
+ *
+ * const { credentialB64, bootstrapUrl } = await requestCredential({
+ *   anchorUrl: 'https://anchor.example.com',
+ *   game: 'my-game',
+ * });
+ * const session = await openSession({ credentialB64, bootstrapUrl });
+ * ```
+ *
+ * The anchor must admit the game (`net-mesh anchor serve --game my-game`).
+ * Each call is a new visitor seat: the credential binds to the first
+ * browser identity that enrolls with it, and that identity may reconnect
+ * with it for the credential's lifetime (a promoted leader tab does).
+ *
+ * **Who the player is.** A game connects with `connect()` (stores, lobbies
+ * and the lossy channel need it) and keeps its player with
+ * `rememberedIdentity()`, which stores the identity in this origin's
+ * `localStorage`: one player per **browser profile**. Clearing site data
+ * makes a new player, and the same person on two devices is two players.
+ * A bare `connect()` without it makes a new identity every page load.
+ */
+/** {@link requestCredential}'s argument. */
+export interface RequestCredentialOptions {
+    /**
+     * The anchor's bootstrap URL — what the operator passed as
+     * `anchor serve --url`, e.g. `https://anchor.example.com`.
+     */
+    readonly anchorUrl: string;
+    /** The game id the anchor admits (`--game`). */
+    readonly game: string;
+    /** Cancels the request. */
+    readonly signal?: AbortSignal;
+    /** A `fetch` to use instead of the global one (tests, workers). */
+    readonly fetch?: typeof fetch;
+}
+/** What {@link requestCredential} returns — exactly what `connect()` / `openSession()` take. */
+export interface AnchorCredential {
+    readonly credentialB64: string;
+    readonly bootstrapUrl: string;
+    readonly game: string;
+}
+/** Why {@link requestCredential} failed. */
+export type CredentialRequestErrorKind = 
+/** The anchor does not admit that game. */
+'unknown-game'
+/** Too many requests from this address, or for this game; retry shortly. */
+ | 'rate-limited'
+/** The anchor did not understand the request. */
+ | 'malformed-request'
+/** The anchor could not be reached, or it issues no credentials. */
+ | 'unreachable'
+/** The anchor answered something this package does not recognise. */
+ | 'unexpected';
+/** A typed {@link requestCredential} failure. */
+export declare class CredentialRequestError extends Error {
+    readonly kind: CredentialRequestErrorKind;
+    /** The HTTP status, when the anchor answered. */
+    readonly status: number | null;
+    readonly name = "CredentialRequestError";
+    constructor(kind: CredentialRequestErrorKind, message: string, 
+    /** The HTTP status, when the anchor answered. */
+    status?: number | null);
+}
+/** Ask `anchorUrl` for a fresh anonymous credential for `game`. */
+export declare function requestCredential(options: RequestCredentialOptions): Promise<AnchorCredential>;

package/dist/credential.js

@@ -0,0 +1,95 @@
+/**
+ * `requestCredential` — ask a game anchor for an anonymous visitor
+ * credential, so a page connects with no hand-minted secret.
+ *
+ * ```ts
+ * import { openSession, requestCredential } from '@net-mesh/browser';
+ *
+ * const { credentialB64, bootstrapUrl } = await requestCredential({
+ *   anchorUrl: 'https://anchor.example.com',
+ *   game: 'my-game',
+ * });
+ * const session = await openSession({ credentialB64, bootstrapUrl });
+ * ```
+ *
+ * The anchor must admit the game (`net-mesh anchor serve --game my-game`).
+ * Each call is a new visitor seat: the credential binds to the first
+ * browser identity that enrolls with it, and that identity may reconnect
+ * with it for the credential's lifetime (a promoted leader tab does).
+ *
+ * **Who the player is.** A game connects with `connect()` (stores, lobbies
+ * and the lossy channel need it) and keeps its player with
+ * `rememberedIdentity()`, which stores the identity in this origin's
+ * `localStorage`: one player per **browser profile**. Clearing site data
+ * makes a new player, and the same person on two devices is two players.
+ * A bare `connect()` without it makes a new identity every page load.
+ */
+/** A typed {@link requestCredential} failure. */
+export class CredentialRequestError extends Error {
+    kind;
+    status;
+    name = 'CredentialRequestError';
+    constructor(kind, message, 
+    /** The HTTP status, when the anchor answered. */
+    status = null) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+    }
+}
+const REFUSALS = {
+    unknown_game: 'unknown-game',
+    rate_limited: 'rate-limited',
+    malformed_request: 'malformed-request',
+};
+/** Ask `anchorUrl` for a fresh anonymous credential for `game`. */
+export async function requestCredential(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (typeof doFetch !== 'function') {
+        throw new CredentialRequestError('unreachable', 'requestCredential needs fetch');
+    }
+    const endpoint = `${options.anchorUrl.replace(/\/+$/, '')}/credential`;
+    let response;
+    try {
+        response = await doFetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ game: options.game }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        });
+    }
+    catch (error) {
+        if (options.signal?.aborted)
+            throw error;
+        throw new CredentialRequestError('unreachable', `could not reach ${endpoint}: ${String(error)}`);
+    }
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Not JSON: an anchor without `--game` answers its router's bare 404.
+    }
+    if (!response.ok) {
+        const refusal = body?.refusal;
+        const message = body?.message;
+        const kind = typeof refusal === 'string' && refusal in REFUSALS
+            ? REFUSALS[refusal]
+            : response.status === 404
+                ? 'unreachable'
+                : 'unexpected';
+        const detail = kind === 'unreachable'
+            ? `${endpoint} issues no credentials (is the anchor started with --game?)`
+            : typeof message === 'string'
+                ? message
+                : `the anchor answered ${response.status}`;
+        throw new CredentialRequestError(kind, detail, response.status);
+    }
+    const reply = body;
+    if (typeof reply?.credentialB64 !== 'string' ||
+        typeof reply.bootstrapUrl !== 'string' ||
+        typeof reply.game !== 'string') {
+        throw new CredentialRequestError('unexpected', 'the anchor answered without a credential', response.status);
+    }
+    return { credentialB64: reply.credentialB64, bootstrapUrl: reply.bootstrapUrl, game: reply.game };
+}

package/dist/errors.d.ts

@@ -0,0 +1,400 @@
+/**
+ * The leaf's error taxonomy, mirrored in TypeScript.
+ *
+ * One class per variant of `net_leaf::error::LeafError`, with the two
+ * nested enums (`RtcError`, `RpcError`) flattened into `kind` so a
+ * caller — or a Playwright assertion — can branch on one stable
+ * string. `message` is verbatim the Rust `Display` text that crossed
+ * the wasm boundary, so nothing is lost in the re-typing;
+ * `errors.test.ts` pins that round-trip.
+ *
+ * **The failure-typing correction lives in this file's types.** There
+ * is no way to build a {@link RtcErrorFailure} of type `udpBlocked`
+ * without a {@link UdpBlockedEvidence}, and `udpBlockedEvidence()` —
+ * the mirror of Rust's `UdpBlockedEvidence::new` — returns `null`
+ * unless both observations hold. An ICE timeout on its own therefore
+ * cannot become `udp-blocked` anywhere in this package.
+ */
+/** Every error kind the leaf can surface, one per Rust variant. */
+export type LeafErrorKind = 'wire' | 'session' | 'control-plane' | 'identity' | 'not-leader' | 'ice-timeout' | 'udp-blocked' | 'channel-closed' | 'rtc-unsupported' | 'rpc-refused' | 'rpc-timeout' | 'session-lost' | 'leader-lost' | 'rpc-indeterminate' | 'rpc-malformed' | 'ice-server-conflict' | 'org-admission-denied' | 'org-revoked' | 'org-timeout' | 'org-cancelled' | 'org-leader-lost' | 'org-session-lost' | 'org-indeterminate' | 'org-refused' | 'org-internal' | 'org-malformed' | 'unknown';
+/**
+ * The two observations that, together, distinguish blocked UDP from
+ * an anchor that simply is not there. Mirrors
+ * `net_leaf::error::UdpBlockedEvidence`.
+ *
+ * The field types are the literal `true`, not `boolean`: a value of
+ * this type is itself the proof, so a caller cannot hand one over
+ * with `bootstrapOk: false`.
+ */
+export interface UdpBlockedEvidence {
+    /** The anchor answered over HTTPS — it is up and addressable. */
+    readonly bootstrapOk: true;
+    /** A STUN binding to the `rtc_addr` that anchor published went unanswered. */
+    readonly stunProbeFailed: true;
+    /** The address the probe was aimed at, so the claim names its subject. */
+    readonly probed: string;
+}
+/**
+ * `UdpBlockedEvidence` only when both observations hold; `null`
+ * otherwise, which is the caller's instruction to stay with
+ * `ice-timeout`. Mirror of `UdpBlockedEvidence::new`.
+ */
+export declare function udpBlockedEvidence(bootstrapOk: boolean, stunProbeFailed: boolean, probed: string): UdpBlockedEvidence | null;
+/** Why an RTC attempt did not produce a DataChannel. */
+export type RtcErrorFailure = {
+    readonly type: 'iceTimeout';
+} | {
+    readonly type: 'udpBlocked';
+    readonly evidence: UdpBlockedEvidence;
+} | {
+    readonly type: 'channelClosed';
+    readonly detail: string;
+} | {
+    readonly type: 'unsupported';
+    readonly detail: string;
+};
+/** How an nRPC call ended when it did not return a reply. */
+export type RpcErrorFailure = {
+    readonly type: 'refused';
+    readonly status: number;
+    readonly message: string;
+} | {
+    readonly type: 'timeout';
+} | {
+    readonly type: 'sessionLost';
+} | {
+    readonly type: 'leaderLost';
+    readonly generation: number;
+} | {
+    readonly type: 'indeterminate';
+    readonly deadlineMs: number;
+} | {
+    readonly type: 'malformed';
+    readonly detail: string;
+};
+/** The base class of everything this package rejects with. */
+export declare abstract class LeafError extends Error {
+    /** The flat, stable discriminant. */
+    abstract readonly kind: LeafErrorKind;
+    protected constructor(message: string);
+}
+/** The wire layer refused a packet: framing, AEAD, replay window. */
+export declare class WireError extends LeafError {
+    readonly detail: string;
+    readonly kind: "wire";
+    constructor(detail: string);
+}
+/** No session for a peer, an incomplete handshake, a replaced session. */
+export declare class SessionError extends LeafError {
+    readonly detail: string;
+    readonly kind: "session";
+    constructor(detail: string);
+}
+/** The control plane could not carry what the leaf asked it to. */
+export declare class ControlPlaneError extends LeafError {
+    readonly detail: string;
+    readonly kind: "control-plane";
+    constructor(detail: string);
+}
+/** Identity storage, generation or custody. */
+export declare class IdentityError extends LeafError {
+    readonly detail: string;
+    readonly kind: "identity";
+    constructor(detail: string);
+}
+/**
+ * A supplied `iceServers` entry named **this connection's own peer**
+ * as its STUN server.
+ *
+ * The mirror of Rust's `LeafError::IceServerConflictsWithPeer`. An
+ * anchor's `rtc_addr` is the ICE peer of a connection with that
+ * anchor, not a STUN server for it: the connection gathers no
+ * server-reflexive candidate and times out. The leaf refuses this
+ * **before any ICE work**, and refuses rather than silently
+ * stripping the entry — stripping would turn an explicit
+ * NAT-traversal configuration into a host-candidate-only attempt
+ * while appearing to have accepted it.
+ *
+ * The fix is to omit `iceServers` and let `connect()` use the
+ * endpoint the anchor announces as `stun_addr` on
+ * `GET /rtc/anchor`, or to name a STUN server that is not this
+ * peer. {@link diagnosticStunUrl} exists for the throwaway UDP
+ * probe and is not a source of `iceServers`.
+ *
+ * **Detection is endpoint equality only**, after default-port
+ * normalisation. A URL naming a DNS alias that resolves to the peer
+ * is not detected: the leaf resolves no names. The announced
+ * endpoint is what makes detection unnecessary for the configuration
+ * Net supplies.
+ */
+export declare class IceServerConflictError extends LeafError {
+    readonly entry: string;
+    readonly peerRtcAddr: string;
+    readonly kind: "ice-server-conflict";
+    constructor(entry: string, peerRtcAddr: string);
+}
+/**
+ * This tab is not the leader for the origin and the operation needs
+ * the node. Carries the generation the caller presented so a stale
+ * follower's failure is legible.
+ */
+export declare class NotLeaderError extends LeafError {
+    readonly presented: number;
+    readonly current: number | null;
+    readonly kind: "not-leader";
+    constructor(presented: number, current?: number | null);
+}
+/** The RTC transport itself. `kind` is the flattened failure. */
+export declare class RtcError extends LeafError {
+    readonly failure: RtcErrorFailure;
+    readonly kind: 'ice-timeout' | 'udp-blocked' | 'channel-closed' | 'rtc-unsupported';
+    constructor(failure: RtcErrorFailure);
+}
+/** An nRPC call failed or was disposed of. `kind` is the flattened failure. */
+export declare class RpcError extends LeafError {
+    readonly failure: RpcErrorFailure;
+    readonly kind: 'rpc-refused' | 'rpc-timeout' | 'session-lost' | 'leader-lost' | 'rpc-indeterminate' | 'rpc-malformed';
+    constructor(failure: RpcErrorFailure);
+}
+/**
+ * Something crossed the boundary that this taxonomy does not
+ * recognise — a browser exception, or a leaf `Display` string this
+ * version of the package predates.
+ *
+ * Deliberately not folded into a neighbouring variant: mis-typing a
+ * failure is the exact mistake the Stage 5 correction exists to
+ * prevent, so an unrecognised message stays unrecognised.
+ */
+export declare class UnknownLeafError extends LeafError {
+    /** The value as it crossed the boundary, for diagnosis. */
+    readonly cause?: unknown | undefined;
+    readonly kind: "unknown";
+    constructor(message: string, 
+    /** The value as it crossed the boundary, for diagnosis. */
+    cause?: unknown | undefined);
+}
+/**
+ * The frozen coarse vocabulary of an admission denial — the whole of
+ * what a remote provider ever says about why. A precise remote reason
+ * would be a credential oracle, so the wire carries one of these three
+ * bytes and the detailed refusal stays provider-side audit only.
+ */
+export type CoarseAdmissionReason = 'denied' | 'not-supported' | 'unavailable';
+/** Every org terminal kind, one per the leaf's frozen terminal vocabulary. */
+export type OrgErrorKind = 'org-admission-denied' | 'org-revoked' | 'org-timeout' | 'org-cancelled' | 'org-leader-lost' | 'org-session-lost' | 'org-indeterminate' | 'org-refused' | 'org-internal' | 'org-malformed';
+/**
+ * The base class of the org terminal vocabulary — what
+ * {@link OrgByteStream}'s terminal error item carries and what the org
+ * verbs reject with. `message` is the boundary's own text, verbatim,
+ * exactly as the rest of this taxonomy keeps it.
+ */
+export declare abstract class OrgStreamError extends LeafError {
+    abstract readonly kind: OrgErrorKind;
+}
+/**
+ * The provider's admission engine refused the call (`RpcStatus 0x0009`).
+ * `coarse` is the frozen three-bucket reason and nothing finer.
+ */
+export declare class OrgAdmissionDeniedError extends OrgStreamError {
+    readonly coarse: CoarseAdmissionReason;
+    readonly kind: OrgErrorKind;
+    constructor(coarse: CoarseAdmissionReason, message?: string);
+}
+/**
+ * Credentials were revoked mid-call. **Is** an admission denial:
+ * `coarse` is fixed to `'denied'` (the frozen Revoked → Denied coarse
+ * map), so `instanceof OrgAdmissionDeniedError` and
+ * `coarse === 'denied'` hold — `instanceof OrgRevokedError` is how a
+ * page that wants the cause gets it.
+ */
+export declare class OrgRevokedError extends OrgAdmissionDeniedError {
+    readonly kind: OrgErrorKind;
+    constructor(message?: string);
+}
+/** The call's deadline elapsed. Nothing is re-issued. */
+export declare class OrgTimeoutError extends OrgStreamError {
+    readonly kind: "org-timeout";
+    constructor(message?: string);
+}
+/** The call was cancelled — by its owner, or by a teardown that owns it. */
+export declare class OrgCancelledError extends OrgStreamError {
+    readonly kind: "org-cancelled";
+    constructor(message?: string);
+}
+/**
+ * The generation holding the call was replaced (the shared-session
+ * surface's typed `LeaderLost`). `generation` is the generation that
+ * owned the call, as an exact decimal string — the u64 never becomes a
+ * JS number here. Never resumed: a successor generation's calls are
+ * fresh calls with fresh correlation and fresh proofs.
+ */
+export declare class OrgLeaderLostError extends OrgStreamError {
+    readonly generation: string;
+    readonly kind: "org-leader-lost";
+    constructor(generation: string, message?: string);
+}
+/** The session carrying the call went away. */
+export declare class OrgSessionLostError extends OrgStreamError {
+    readonly kind: "org-session-lost";
+    constructor(message?: string);
+}
+/**
+ * The caller's own deadline elapsed before an answer arrived; the
+ * remote operation may still have executed and was not retried.
+ */
+export declare class OrgIndeterminateError extends OrgStreamError {
+    readonly deadlineMs: number;
+    readonly kind: "org-indeterminate";
+    constructor(deadlineMs: number, message?: string);
+}
+/**
+ * The application refused the call. `status` is its status code.
+ *
+ * Also the frozen wire kinds `server_error` (a server-answered failure
+ * status — the vocabulary's second name for this same condition) and
+ * `capability_denied` (the capability gate's refusal of the call): a
+ * re-typed wire string carries no recoverable `status` (`0`) and its
+ * `message` keeps the detail verbatim.
+ */
+export declare class OrgRefusedError extends OrgStreamError {
+    readonly status: number;
+    readonly kind: "org-refused";
+    constructor(status: number, message?: string);
+}
+/**
+ * The boundary failed internally. Also what a terminal item whose
+ * `kind` this build does not know becomes: mis-typing a failure is the
+ * exact mistake this taxonomy exists to prevent, so an unknown kind is
+ * named internal rather than guessed into a merits bucket. The frozen
+ * wire kinds `no_route` and `transport` land here for the same reason:
+ * they carry no merits verdict (nobody refused the call).
+ */
+export declare class OrgInternalError extends OrgStreamError {
+    readonly kind: "org-internal";
+    constructor(message?: string);
+}
+/**
+ * The reply or item did not decode. Also the frozen wire kinds
+ * `codec_encode` / `codec_decode` — the one codec class, both
+ * directions: an item that did not survive the codec is malformed
+ * whichever side failed.
+ */
+export declare class OrgMalformedError extends OrgStreamError {
+    readonly kind: "org-malformed";
+    constructor(message?: string);
+}
+/**
+ * Why a call, stream, sink or request stream retired — the exact
+ * string the retirement observables resolve with, kept verbatim.
+ *
+ * `node-closed` and `replaced` are teardown verdicts rather than call
+ * outcomes; both arrive at the terminal vocabulary as `cancelled`
+ * (the frozen retire → terminal map), and the raw string is what tells
+ * them apart.
+ *
+ * `resource-exhausted` is the leaf's byte-budget retirement
+ * (`RetireReason::ResourceExhausted`'s spelling). Its precise
+ * observable is the `admission-denied` / `unavailable` denial — the
+ * same class the byte-budget send refusal on that call re-types as
+ * ({@link ORG_SINK_BUDGET_REFUSAL}) — never a cancel and never a
+ * teardown verdict.
+ */
+export type OrgRetireReason = 'timeout' | 'cancelled' | 'revoked' | 'session-lost' | 'leader-lost' | 'node-closed' | 'replaced' | 'resource-exhausted';
+/**
+ * THE typed closed refusal of a handler-side sink after retirement —
+ * one text whatever the verdict, so the wrapper's belt (its own
+ * short-circuit) and the leaf's hardening (its rejection) are the
+ * same observable. The verdict itself is what `retired` reports.
+ */
+export declare const ORG_SINK_CLOSED_REFUSAL = "org: the response sink is closed: the call was retired";
+/**
+ * The upload sink's spelling of the SAME typed closed refusal —
+ * `sink_error(SinkError::Closed, "the upload sink")` at the leaf —
+ * pinned verbatim like {@link ORG_SINK_CLOSED_REFUSAL}. One text per
+ * sink, one text per verdict: what the leaf's `sink_error` spells is
+ * exactly this family, and anything outside it is not a closed refusal.
+ */
+export declare const ORG_UPLOAD_SINK_CLOSED_REFUSAL = "org: the upload sink is closed: the call was retired";
+/**
+ * The byte-budget closed refusals — `sink_error(SinkError::ResourceExhausted, ..)`
+ * for the response sink and the upload sink. The item overran the
+ * call's byte budget and the call retired as `ResourceExhausted`,
+ * whose precise observable is the `admission-denied` / `unavailable`
+ * denial (the leaf's frozen map; C4, coarse `Unavailable`) — so these
+ * re-type as exactly that, never as a cancel.
+ */
+export declare const ORG_SINK_BUDGET_REFUSAL = "org: the response sink is closed: the call's byte budget refused the item and retired the call";
+export declare const ORG_UPLOAD_SINK_BUDGET_REFUSAL = "org: the upload sink is closed: the call's byte budget refused the item and retired the call";
+/**
+ * Parse one wire token — or the one-byte coarse body a `0x0009`
+ * refusal carries — into the coarse bucket. Anything undecodable is
+ * the least-informative bucket (`denied`), never an error about an
+ * error: the caller still learns it was denied.
+ */
+export declare function coarseAdmissionReason(token: string | undefined): CoarseAdmissionReason;
+/** The terminal error a retirement verdict maps to (the frozen map). */
+export declare function orgRetireError(reason: OrgRetireReason): OrgStreamError;
+/**
+ * Type one terminal item from the boundary — the frozen `kind`
+ * vocabulary plus its fields — as the class §4.3 names.
+ *
+ * `message` is kept verbatim as the error's message.
+ */
+export declare function orgTerminalError(item: {
+    kind: string;
+    message?: string;
+    coarse?: string;
+    generation?: string;
+    status?: number;
+    deadlineMs?: number;
+}): OrgStreamError;
+/**
+ * Type one retirement verdict coming back from the boundary's
+ * `retired()`. A string this build does not know is a boundary
+ * disagreement — named `replaced`-as-cancelled would lie about which
+ * teardown ran, so it becomes the cancelled terminal and the raw
+ * string stays in `OrgRetireReason`'s consumers' hands unchanged.
+ */
+export declare function orgRetireReason(raw: string): OrgRetireReason;
+/**
+ * Parse one `org:` wire string (`org:<domain>:<kind>[:detail]`, the
+ * `OrgSdkError::to_wire` vocabulary) or a `0x0009` admission refusal,
+ * or `null` if the message is not one.
+ *
+ * The domains and kind tokens mirror `classifyOrgError` from the Node
+ * binding where names coincide; the `rpc` domain reuses the frozen
+ * nRPC kind vocabulary rather than minting second names for the same
+ * conditions. Every frozen `org:rpc:` kind classifies (the frozen
+ * wire-kind map at the `rpc` switch) — a binding that returned `null`
+ * there forced the caller into `UnknownLeafError`, which is the
+ * cross-language drift this closes.
+ */
+export declare function parseOrgError(message: string): OrgStreamError | null;
+/**
+ * Re-type whatever the wasm boundary threw.
+ *
+ * `wasm-bindgen` hands us a `JsError` whose `message` is the Rust
+ * `Display` of `LeafError`, so the taxonomy is recovered by parsing
+ * exactly those prefixes. Anything else — a `DOMException` from
+ * `RTCPeerConnection`, a string, a plain object — becomes
+ * {@link UnknownLeafError} with the original value as `cause`.
+ */
+export declare function fromWasmError(thrown: unknown): LeafError;
+/**
+ * Parse one `LeafError` `Display` string, or `null` if it is not one.
+ *
+ * Exported because it is the whole of the wasm→TS error contract and
+ * deserves to be unit-testable without a wasm module.
+ */
+export declare function parseLeafError(message: string): LeafError | null;
+/** Parse the nested `RtcError` `Display`, or `null`. */
+export declare function parseRtcFailure(text: string): RtcErrorFailure | null;
+/** Parse the nested `RpcError` `Display`, or `null`. */
+export declare function parseRpcFailure(text: string): RpcErrorFailure | null;
+/** `true` when this error carries the UDP-blocked evidence. */
+export declare function isUdpBlocked(error: unknown): error is RtcError & {
+    failure: {
+        type: 'udpBlocked';
+        evidence: UdpBlockedEvidence;
+    };
+};