@statewalker/webrun-rpc 0.4.0

package/dist/io-handle.d.ts

@@ -0,0 +1,17 @@
+import type { ListenPortOptions } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+/**
+ * Server half of a full-duplex exchange over any `MessageTarget`.
+ *
+ * For each inbound stream, invokes `handler` with the stream, sends the
+ * handler's output back, and yields a counter. The generator never ends
+ * on its own — consumers break when they want to stop. Pairs with
+ * {@link ioSend}.
+ *
+ * If the peer (the consumer of our outbound send) posts a `cancel-channel`
+ * message on the same sub-channel, we abort `send` immediately. This makes
+ * `ioSend`'s `iter.return()` propagate cleanly without waiting for
+ * `callPort` timeouts.
+ */
+export declare function ioHandle<T, U = T>(port: MessageTarget, handler: (input: AsyncIterable<T>) => AsyncIterable<U> | Promise<AsyncIterable<U>>, options?: ListenPortOptions): AsyncGenerator<number>;
+//# sourceMappingURL=io-handle.d.ts.map

package/dist/io-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-handle.d.ts","sourceRoot":"","sources":["../src/io-handle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;;;;;;;;;GAYG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAClF,OAAO,GAAE,iBAAsB,GAC9B,cAAc,CAAC,MAAM,CAAC,CAgBxB"}

package/dist/io-send.d.ts

@@ -0,0 +1,26 @@
+import type { ListenPortOptions } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+export interface IoSendOptions extends ListenPortOptions {
+    /**
+     * Optional cancel signal threaded into `recieve` so the consumer can force
+     * an in-flight `input.next()` to resolve immediately (otherwise an
+     * AsyncGenerator's `.return()` queues behind the pending `.next()` and
+     * never preempts a hanging await). Used by `callBidi` to abort the inner
+     * stream when the outer call rejects.
+     */
+    cancelSignal?: AbortSignal;
+}
+/**
+ * Client half of a full-duplex exchange over any `MessageTarget`.
+ *
+ * Concurrently reads one inbound stream from the peer and writes `output`
+ * to it. Yields each value received from the peer. Completes once both
+ * directions finish. Pairs with {@link ioHandle}.
+ *
+ * If the consumer breaks out of the `for await` (via `iter.return()` or
+ * loop `break`), `ioSend` posts a `cancel-channel` message on the same
+ * sub-channel so the peer can abort its `send` immediately rather than
+ * waiting for `callPort` timeouts to fire.
+ */
+export declare function ioSend<T, U = T>(port: MessageTarget, output: AsyncIterable<U> | Iterable<U>, options?: IoSendOptions): AsyncGenerator<T>;
+//# sourceMappingURL=io-send.d.ts.map

package/dist/io-send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-send.d.ts","sourceRoot":"","sources":["../src/io-send.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAuB,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EACpC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACtC,OAAO,GAAE,aAAkB,GAC1B,cAAc,CAAC,CAAC,CAAC,CAoCnB"}

package/dist/listen-bidi.d.ts

@@ -0,0 +1,11 @@
+import type { MessageTarget } from "./message-target.js";
+export type BidiHandler<TIn, TOut> = (input: AsyncIterable<TIn>, params: Record<string, unknown>) => AsyncIterable<TOut> | Promise<AsyncIterable<TOut>>;
+/**
+ * Server half of {@link callBidi}: listens for stream-call requests on `port`
+ * and dispatches each accepted one to `action`.
+ *
+ * The optional `accept` predicate can inspect the incoming params and reject
+ * unwanted calls. Returns a cleanup function that removes the listener.
+ */
+export declare function listenBidi<TIn, TOut>(port: MessageTarget, action: BidiHandler<TIn, TOut>, accept?: (params: Record<string, unknown>) => boolean): () => void;
+//# sourceMappingURL=listen-bidi.d.ts.map

package/dist/listen-bidi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-bidi.d.ts","sourceRoot":"","sources":["../src/listen-bidi.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,WAAW,CAAC,GAAG,EAAE,IAAI,IAAI,CACnC,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,EACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,aAAa,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,IAAI,EAClC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,EAC9B,MAAM,GAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAoB,GAChE,MAAM,IAAI,CAUZ"}

package/dist/listen-port.d.ts

@@ -0,0 +1,16 @@
+import type { MessageTarget } from "./message-target.js";
+export interface ListenPortOptions {
+    /** Channel name filter — ignore messages whose `channelName` doesn't match. */
+    channelName?: string;
+    /** Logging function; defaults to a no-op. */
+    log?: (...args: unknown[]) => void;
+}
+export type PortHandler<TParams = unknown, TResult = unknown> = (params: TParams) => TResult | Promise<TResult>;
+/**
+ * Installs `handler` as the server side of a `callPort` / `listenPort`
+ * request/response pair on `port`.
+ *
+ * Returns a cleanup function that removes the listener.
+ */
+export declare function listenPort<TParams = unknown, TResult = unknown>(port: MessageTarget, handler: PortHandler<TParams, TResult>, { channelName, log }?: ListenPortOptions): () => void;
+//# sourceMappingURL=listen-port.d.ts.map

package/dist/listen-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen-port.d.ts","sourceRoot":"","sources":["../src/listen-port.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,MAAM,WAAW,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAC9D,MAAM,EAAE,OAAO,KACZ,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAC7D,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,EAAE,WAAgB,EAAE,GAAc,EAAE,GAAE,iBAAsB,GAC3D,MAAM,IAAI,CAsBZ"}

package/dist/message-target.d.ts

@@ -0,0 +1,16 @@
+export type MessageListener = (event: MessageEvent) => void | Promise<void>;
+/** An object we can listen for `"message"` events on. */
+export interface MessageSource {
+    addEventListener(type: "message", listener: MessageListener): void;
+    removeEventListener(type: "message", listener: MessageListener): void;
+    start?(): void | Promise<void>;
+}
+/** An object we can post messages to (with optional transferable list). */
+export interface MessageSink {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+}
+/** Full-duplex message target: both sends and receives. */
+export interface MessageTarget extends MessageSource, MessageSink {
+    close?(): void | Promise<void>;
+}
+//# sourceMappingURL=message-target.d.ts.map

package/dist/message-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-target.d.ts","sourceRoot":"","sources":["../src/message-target.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5E,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACnE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACtE,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;CAChE;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAc,SAAQ,aAAa,EAAE,WAAW;IAC/D,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/multiplex-port.d.ts

@@ -0,0 +1,12 @@
+import type { MessageTarget } from "./message-target.js";
+import type { PortMux, PortMuxOptions } from "./port-types.js";
+/** Ceiling on concurrently open virtual ports. Bounds the id table only. */
+export declare const DEFAULT_MAX_PORTS = 1024;
+/**
+ * The default `PortMux`: emulates multiplexing over a single port.
+ *
+ * A transport that already multiplexes natively supplies its own `PortMux`
+ * instead — this implementation is for transports that offer one pipe.
+ */
+export declare function multiplexPort(port: MessageTarget, options: PortMuxOptions): PortMux;
+//# sourceMappingURL=multiplex-port.d.ts.map

package/dist/multiplex-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiplex-port.d.ts","sourceRoot":"","sources":["../src/multiplex-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG7E,4EAA4E;AAC5E,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAwHnF"}

package/dist/port-types.d.ts

@@ -0,0 +1,86 @@
+import type { MessageTarget } from "./message-target.js";
+/**
+ * What a multiplexer exchanges over the underlying port.
+ *
+ * Three types and nothing more. There is no DATA/ACK split, no credit and no
+ * error type: `close` carries an opaque `reason` that layer 1 never inspects,
+ * because stream semantics belong above this layer.
+ */
+export type PortEnvelope = {
+    type: "open";
+    id: number;
+    meta?: unknown;
+} | {
+    type: "message";
+    id: number;
+    payload: unknown;
+} | {
+    type: "close";
+    id: number;
+    reason?: unknown;
+};
+/**
+ * How an envelope reaches the wire.
+ *
+ * This is the only place that knows the wire format. A port whose messages are
+ * structured values passes envelopes through untouched; a port whose messages
+ * are bytes encodes them. A transport with different constraints adds a codec,
+ * not a multiplexer.
+ */
+export interface PortCodec {
+    /** Place one envelope on the underlying port. */
+    post(port: MessageTarget, envelope: PortEnvelope, transfer?: Transferable[]): void;
+    /** Recover an envelope from a message event, or `undefined` to ignore it. */
+    read(event: MessageEvent): PortEnvelope | undefined;
+}
+export interface PortMuxOptions {
+    /** How envelopes are placed on the underlying port. */
+    codec: PortCodec;
+    /**
+     * Called when the peer opens a port. Return `false` to reject it: a `close`
+     * goes back and every later message for that id is dropped. Any other return
+     * value — including `undefined` — accepts.
+     *
+     * With no `onPort` at all, inbound ports are rejected. A port nobody holds
+     * has no consumer, and accepting one would mean dropping its traffic
+     * silently rather than telling the peer.
+     */
+    onPort?: (port: MessageTarget, meta?: unknown) => boolean | undefined;
+    /**
+     * Id parity. The initiator allocates even ids, the responder odd, so both
+     * ends may open concurrently with no negotiation. Defaults to `"initiator"`.
+     */
+    side?: "initiator" | "responder";
+    /**
+     * Ceiling on concurrently open virtual ports. Bounds the id table only — it
+     * never inspects, counts or delays a payload.
+     */
+    maxPorts?: number;
+    /**
+     * Largest **payload** a port on this mux can carry, if the transport imposes
+     * a limit. Layer 1 does not enforce it; it reports it so layer 2 can chunk.
+     *
+     * It bounds the payload, **not the frame**. `duplexOverPort` applies
+     * `toChunks(maxMessageSize)` and the envelope framing — the chunk wrapper,
+     * `callPort`'s request, this mux's own envelope, then the codec — is added on
+     * top afterwards. Measured over `msgpackCodec` that framing is 123-128 bytes
+     * (modelled ceiling 134), and it is not constant: the call id's length varies
+     * per chunk, the port id's integer width adds up to 4, and the payload's
+     * length header widens at 64 KiB.
+     *
+     * So set this **at least 256 bytes below** the transport's real limit. Set to
+     * the limit exactly, a full-size chunk overruns it — which on LiveKit
+     * delivered a body as zero bytes with no error on either side.
+     */
+    maxMessageSize?: number;
+}
+/** One port in, many ports out. */
+export interface PortMux {
+    /** Allocate a port, announce it, and return the local end. */
+    openPort(meta?: unknown): Promise<MessageTarget>;
+    /** Close every virtual port, then release the underlying port. */
+    close(): Promise<void>;
+    /** See {@link PortMuxOptions.maxMessageSize}. */
+    readonly maxMessageSize?: number;
+}
+//# sourceMappingURL=port-types.d.ts.map

package/dist/port-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-types.d.ts","sourceRoot":"","sources":["../src/port-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,iDAAiD;IACjD,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IACnF,6EAA6E;IAC7E,IAAI,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,KAAK,EAAE,SAAS,CAAC;IACjB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;IACtE;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,OAAO;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjD,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/recieve.d.ts

@@ -0,0 +1,35 @@
+import { type ListenPortOptions } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+export interface RecieveOptions extends ListenPortOptions {
+    /**
+     * Optional cancel signal. When fired, the currently-active
+     * `recieveIterator` is force-closed (its producer is signalled `done`
+     * with an `AbortError`) so any pending `.next()` resolves immediately
+     * and the consumer's iteration loop can unwind. Required to make
+     * consumer-side `iter.return()` propagate through `callBidi`/`yield*`
+     * without waiting on `callPort` timeouts.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Async generator over async generators. Each outer yield is one inbound
+ * stream reconstructed from chunk-envelopes delivered by the peer's
+ * {@link send}.
+ *
+ * The outer generator itself never ends: break out of the outer loop when
+ * you've handled the streams you care about.
+ *
+ * When the outer for-await is interrupted (`break`, `return`, throw), the
+ * `finally` here both removes the underlying `listenPort` and closes the
+ * most recently yielded `recieveIterator`. The latter is required because
+ * a `listenPort` handler invocation that's already in flight (awaiting
+ * `deliver(chunk)`) would otherwise hang forever — `iterator.return()`
+ * triggers `drainQueue` which resolves all pending producer Promises.
+ *
+ * If `options.signal` is provided and fires while the consumer is awaiting
+ * a chunk, the active `recieveIterator` is force-delivered an end-of-stream
+ * marker so the consumer wakes up immediately rather than waiting for the
+ * next inbound chunk (or `callPort` timeout).
+ */
+export declare function recieve<T>(port: MessageTarget, options?: RecieveOptions): AsyncGenerator<AsyncGenerator<T>>;
+//# sourceMappingURL=recieve.d.ts.map

package/dist/recieve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recieve.d.ts","sourceRoot":"","sources":["../src/recieve.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,iBAAiB,EAAc,MAAM,kBAAkB,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAuB,OAAO,CAAC,CAAC,EAC9B,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,cAAmB,GAC3B,cAAc,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAiDnC"}

package/dist/send.d.ts

@@ -0,0 +1,23 @@
+import { type CallPortOptions } from "./call-port.js";
+import type { MessageTarget } from "./message-target.js";
+export interface SendOptions extends CallPortOptions {
+    /**
+     * Optional cancellation signal. When fired, `send` aborts cleanly:
+     *   - the current iteration is interrupted (by calling `return()` on the
+     *     underlying iterator, releasing any pending work in the producer);
+     *   - no further `callPort` round-trips are issued;
+     *   - the final `{done: true}` marker is **not** sent (the peer told us
+     *     it's gone — there's no one to receive it).
+     *
+     * `send` resolves normally on abort; the caller can distinguish abort
+     * from normal completion by checking `options.signal.aborted` after.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Send every value produced by `output` to `port`, one `callPort` round-trip
+ * per chunk. Resolves once the peer has acknowledged the final `{ done: true }`
+ * envelope, or once `options.signal` aborts (whichever comes first).
+ */
+export declare function send<T>(port: MessageTarget, output: AsyncIterable<T> | Iterable<T>, options?: SendOptions): Promise<void>;
+//# sourceMappingURL=send.d.ts.map

package/dist/send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../src/send.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAY,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,MAAM,WAAW,WAAY,SAAQ,eAAe;IAClD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,CAAC,EAC1B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACtC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA8Bf"}

package/dist/structured-codec.d.ts

@@ -0,0 +1,12 @@
+import type { PortCodec } from "./port-types.js";
+/**
+ * For ports whose messages are structured values — a real `MessagePort`, a
+ * worker, an iframe.
+ *
+ * Envelopes are posted as-is, so nothing is encoded, `ArrayBuffer`s move
+ * zero-copy through the transfer list, and structured clone does the work the
+ * platform already does well. This is a performance choice only: layer 2 may
+ * not send anything a byte codec could not also carry.
+ */
+export declare const structuredCodec: PortCodec;
+//# sourceMappingURL=structured-codec.d.ts.map

package/dist/structured-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-codec.d.ts","sourceRoot":"","sources":["../src/structured-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAU/D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,SAU7B,CAAC"}

package/dist/through-abort.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wraps an async iterable so that an `AbortSignal` firing causes the wrapper
+ * to return cleanly, forwarding `return()` to the underlying iterator so the
+ * producer (e.g., a user-supplied generator) sees its own `finally` blocks
+ * run immediately rather than waiting for the next yield.
+ */
+export declare function throughAbort<T>(input: AsyncIterable<T> | Iterable<T>, signal: AbortSignal): AsyncGenerator<T>;
+//# sourceMappingURL=through-abort.d.ts.map

package/dist/through-abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"through-abort.d.ts","sourceRoot":"","sources":["../src/through-abort.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAuB,YAAY,CAAC,CAAC,EACnC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACrC,MAAM,EAAE,WAAW,GAClB,cAAc,CAAC,CAAC,CAAC,CAsBnB"}

package/dist/transfer-port-mux.d.ts

@@ -0,0 +1,39 @@
+import type { MessageTarget } from "./message-target.js";
+import type { PortMux } from "./port-types.js";
+/** The `type` of the envelope that carries a transferred port to the peer. */
+export declare const PORT_TRANSFER = "webrun-rpc:port-transfer";
+export interface TransferPortMuxOptions {
+    /**
+     * Called when the peer transfers a port in. Return `false` to reject it: the
+     * port is closed and nothing further arrives on it. Any other return value —
+     * including `undefined` — accepts.
+     *
+     * With no `onPort` at all, inbound ports are rejected, matching
+     * `multiplexPort`: a port nobody holds has no consumer.
+     */
+    onPort?: (port: MessageTarget, meta?: unknown) => boolean | undefined;
+    /** Reported to layer 2, never enforced. A `MessagePort` normally has none. */
+    maxMessageSize?: number;
+}
+/**
+ * A `PortMux` whose ports are real, transferred `MessagePort`s (spec D23).
+ *
+ * `openPort` creates a `MessageChannel`, transfers one end to the peer over
+ * `target`, and returns the other. There is no id table, no `maxPorts` and no
+ * envelope overhead per message, because the platform does the multiplexing.
+ *
+ * **It needs structured clone with transferables**, so it exists in browsers,
+ * workers and iframes and nowhere else that lacks them. A caller selects it
+ * explicitly rather than by capability sniffing (spec D21): use
+ * `multiplexPort` where the transport is one pipe of bytes.
+ *
+ * What it buys over emulation: a transferred port can cross an origin or a
+ * worker boundary and be handed to code that never saw `target`, where an
+ * emulated port id is meaningless outside its own mux.
+ *
+ * `target` must be a full `MessageTarget`. Reaching a send-only `MessageSink`
+ * — a `ServiceWorkerClient`, say — is a real use of port transfer but needs a
+ * different entry point, and is not part of this interface.
+ */
+export declare function transferPortMux(target: MessageTarget, options?: TransferPortMuxOptions): PortMux;
+//# sourceMappingURL=transfer-port-mux.d.ts.map

package/dist/transfer-port-mux.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-port-mux.d.ts","sourceRoot":"","sources":["../src/transfer-port-mux.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,aAAa,6BAA6B,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,GAAG,SAAS,CAAC;IACtE,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CA8DT"}

package/dist/virtual-port.d.ts

@@ -0,0 +1,19 @@
+import type { MessageTarget } from "./message-target.js";
+export interface VirtualPortHandle {
+    /** The consumer-facing end. Indistinguishable from a real `MessagePort`. */
+    port: MessageTarget;
+    /** Multiplexer-only: hand an inbound payload to the consumer's listeners. */
+    deliver(payload: unknown): void;
+    /** Multiplexer-only: the port is finished; drop listeners and go inert. */
+    markClosed(): void;
+    isClosed(): boolean;
+}
+/**
+ * One virtual port.
+ *
+ * `deliver` and `markClosed` are deliberately not on `port`: the consumer holds
+ * only a `MessageTarget`, so it cannot forge inbound traffic or close the port
+ * out from under the multiplexer's bookkeeping.
+ */
+export declare function newVirtualPort(send: (payload: unknown, transfer?: Transferable[]) => void, requestClose: (reason?: unknown) => void): VirtualPortHandle;
+//# sourceMappingURL=virtual-port.d.ts.map

package/dist/virtual-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-port.d.ts","sourceRoot":"","sources":["../src/virtual-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,IAAI,EAAE,aAAa,CAAC;IACpB,6EAA6E;IAC7E,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,2EAA2E;IAC3E,UAAU,IAAI,IAAI,CAAC;IACnB,QAAQ,IAAI,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,KAAK,IAAI,EAC3D,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,GACvC,iBAAiB,CAgDnB"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@statewalker/webrun-rpc",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
+  "description": "Ports and RPC over them: a port multiplexer, and typed request/response and streaming primitives over any MessageTarget.",
+  "homepage": "https://github.com/statewalker/webrun-wire",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:statewalker/webrun-wire.git",
+    "directory": "packages/webrun-rpc"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-streams": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "rimraf": "^6.1.3",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-streams-conformance": "0.2.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
+    "lint": "biome check src tests"
+  }
+}

package/src/byte-channel.ts

@@ -0,0 +1,109 @@
+import type { ByteChannel } from "@statewalker/webrun-streams";
+import type { MessageListener, MessageTarget } from "./message-target.js";
+
+/**
+ * Wrap any `MessageTarget` — a real `MessagePort`, a worker, or a virtual
+ * port over some other transport — as a `ByteChannel`. Outbound bytes are emitted via
+ * `port.postMessage(uint8Array)` (the structured-clone path); inbound bytes
+ * are taken from `message` events whose `data` is a `Uint8Array` (or
+ * coerceable byte-like value).
+ *
+ * The port must already be started (`port.start()` if manually constructed).
+ * This adapter assumes the port carries only byte payloads — non-byte messages
+ * are ignored.
+ */
+export function byteChannelFromMessagePort(port: MessageTarget): ByteChannel {
+  let closedResolve!: () => void;
+  const closed = new Promise<void>((r) => {
+    closedResolve = r;
+  });
+  let isClosed = false;
+
+  const queue: Uint8Array[] = [];
+  let pending: ((value: IteratorResult<Uint8Array>) => void) | null = null;
+
+  const deliver = (bytes: Uint8Array): void => {
+    if (isClosed) return;
+    if (pending) {
+      const r = pending;
+      pending = null;
+      r({ value: bytes, done: false });
+    } else {
+      queue.push(bytes);
+    }
+  };
+
+  const onMessage = (ev: MessageEvent): void => {
+    const data = ev.data as unknown;
+    if (data instanceof Uint8Array) {
+      deliver(new Uint8Array(data));
+      return;
+    }
+    if (data instanceof ArrayBuffer) {
+      deliver(new Uint8Array(data));
+      return;
+    }
+    if (ArrayBuffer.isView(data)) {
+      const view = data as ArrayBufferView;
+      deliver(
+        new Uint8Array(view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength)),
+      );
+    }
+  };
+
+  // MessagePort doesn't fire a "close" event natively; consumers signal close
+  // by calling the channel's close() (which we honour) or by tearing down the
+  // underlying port (which they must observe themselves).
+  port.addEventListener("message", onMessage as unknown as MessageListener);
+  port.start?.();
+
+  const recv: AsyncIterable<Uint8Array> = {
+    [Symbol.asyncIterator]() {
+      return {
+        next(): Promise<IteratorResult<Uint8Array>> {
+          if (queue.length > 0) {
+            return Promise.resolve({ value: queue.shift() as Uint8Array, done: false });
+          }
+          if (isClosed) {
+            return Promise.resolve({
+              value: undefined,
+              done: true,
+            } as IteratorResult<Uint8Array>);
+          }
+          return new Promise<IteratorResult<Uint8Array>>((resolve) => {
+            pending = resolve;
+          });
+        },
+      };
+    },
+  };
+
+  return {
+    send(bytes) {
+      if (isClosed) return;
+      try {
+        port.postMessage(bytes);
+      } catch {
+        /* port closed by peer */
+      }
+    },
+    recv,
+    closed,
+    close() {
+      if (isClosed) return;
+      isClosed = true;
+      port.removeEventListener("message", onMessage as unknown as MessageListener);
+      try {
+        void port.close?.();
+      } catch {
+        /* ignore */
+      }
+      if (pending) {
+        const r = pending;
+        pending = null;
+        r({ value: undefined, done: true } as IteratorResult<Uint8Array>);
+      }
+      closedResolve();
+    },
+  };
+}

package/src/call-bidi.ts

@@ -0,0 +1,60 @@
+import { type CallPortOptions, callPort } from "./call-port.js";
+import { ioSend } from "./io-send.js";
+import type { MessageTarget } from "./message-target.js";
+
+export interface CallBidiOptions extends CallPortOptions {
+  /** Timeout for the outer stream (default: `Number.MAX_SAFE_INTEGER` / max int). */
+  bidiTimeout?: number;
+}
+
+export interface CallBidiArgs {
+  options?: CallBidiOptions;
+  [key: string]: unknown;
+}
+
+/**
+ * Initiates a full-duplex stream call: ships `input` values to the peer and
+ * yields the values returned by `listenBidi`'s handler.
+ *
+ * Internally allocates a fresh sub-channel name, announces it to the peer
+ * via `callPort`, and then runs {@link ioSend} on that sub-channel.
+ *
+ * If the outer `callPort` rejects (e.g., the peer's handler threw and
+ * `listenPort` surfaced the error as `response:error`), the inner `ioSend`'s
+ * recieveIterator is force-closed via an internal cancel signal so the
+ * consumer doesn't hang waiting for chunks that will never come. The outer
+ * error is then re-thrown to the caller.
+ */
+export async function* callBidi<TIn, TOut>(
+  port: MessageTarget,
+  input: AsyncIterable<TIn> | Iterable<TIn>,
+  { options = {}, ...params }: CallBidiArgs = {},
+): AsyncGenerator<TOut> {
+  const channelName = `${+String(Math.random()).substring(2)}`;
+  const { bidiTimeout = 2147483647 } = options;
+  const promise = callPort(port, { ...params, channelName }, { ...options, timeout: bidiTimeout });
+
+  const cancelInner = new AbortController();
+  const sendIter = ioSend<TOut, TIn>(port, input, {
+    ...options,
+    channelName,
+    cancelSignal: cancelInner.signal,
+  });
+
+  let outerError: unknown;
+  promise.catch((err) => {
+    outerError = err;
+    cancelInner.abort();
+  });
+
+  try {
+    yield* sendIter;
+  } finally {
+    try {
+      await promise;
+    } catch {
+      /* surfaced via outerError */
+    }
+  }
+  if (outerError !== undefined) throw outerError;
+}