@statewalker/webrun-msgpack 0.1.1 → 0.2.2

package/README.md

@@ -1,8 +1,31 @@
 # @statewalker/webrun-msgpack
 
-Length-prefixed MessagePack frame codec for async iterables. Streams-safe `encode`/`decode` for arbitrary values, plus zero-copy specialisations for `Float32Array`.
+MessagePack on the wire, in **two distinct shapes**:
 
-## Why it exists
+- a **stream codec** — `encodeMsgpack` / `decodeMsgpack`, length-prefixed, for a transport with no
+  message boundaries (plus zero-copy specialisations for `Float32Array`);
+- a **message codec** — `msgpackCodec`, a `PortCodec` for `@statewalker/webrun-rpc`'s
+  `multiplexPort`, with no length prefix, for a transport that already frames.
+
+They are not interchangeable, and reaching for the wrong one is easy. The table below is the whole
+decision.
+
+## Which codec
+
+| | `encodeMsgpack` / `decodeMsgpack` | `msgpackCodec` |
+| --- | --- | --- |
+| Kind | stream codec | message codec (`PortCodec`) |
+| Shape | `AsyncIterable<T>` ⇄ `AsyncIterable<Uint8Array>` | one `PortEnvelope` ⇄ one `postMessage` |
+| Framing | **4-byte big-endian length prefix**, added by this package | **none** — the transport's own message boundaries are the framing |
+| Use it when | the transport is a byte *stream*: a TCP-like socket, a `ReadableStream`, a file, anything where chunk boundaries are arbitrary | the transport preserves *message* boundaries: a WebSocket, an `RTCDataChannel`, a LiveKit data packet |
+| Malformed input | a truncated trailing frame is never emitted; the consumer ends without yielding a partial value | dropped, never thrown — a bad frame from a peer cannot take the multiplexer down |
+| Depends on | `@ygoe/msgpack` only | `@ygoe/msgpack`, plus **type-only** `@statewalker/webrun-rpc` |
+
+Adding a length prefix on a transport that already frames is redundant framing; relying on message
+boundaries where there are none is the truncation bug the stream codec exists to prevent. Pick by
+the transport, not by taste.
+
+## Why the stream codec exists
 
 Consumers that pipe values across transports (scanners writing chunks to a store, chat pipelines streaming embeddings, etc.) need a way to serialise a stream of objects into a byte stream and reassemble it on the other side without truncation surprises.
 
@@ -10,13 +33,34 @@ A raw MessagePack stream has no frame boundaries: a decoder can only succeed if
 
 Previously the codec lived inside `@repo/streams` (private, unpublished). It's been extracted here so (a) consumers that only need framing don't pull in the broader `webrun-streams` surface, and (b) the `@ygoe/msgpack` dependency lives in exactly one place.
 
-## How to use
+## Why the port codec exists
+
+`@statewalker/webrun-rpc`'s `multiplexPort` runs many virtual ports over one transport, and it needs
+a codec to put its envelopes on the wire. `structuredCodec` (in `webrun-rpc`) passes them through
+unencoded, which works only where messages are *structured values* — a `MessagePort`, a worker, an
+iframe. `msgpackCodec` is the byte-transport sibling: one envelope becomes one msgpack frame and one
+`postMessage`.
+
+## Install
 
 ```sh
 npm install @statewalker/webrun-msgpack
 ```
 
-Four exports — one encode/decode pair for generic values, one for `Float32Array`:
+One runtime dependency **in the emitted bundle**
+([`@ygoe/msgpack`](https://www.npmjs.com/package/@ygoe/msgpack)), no peer dependencies. ESM only
+(`"type": "module"`). That is not the same as the install cost: `@statewalker/webrun-rpc` is a
+declared `dependency`, so `npm install` also pulls it and, transitively, `@statewalker/webrun-streams`
+into `node_modules` — even for a consumer who uses only the stream codec.
+
+`@statewalker/webrun-rpc` is declared as a dependency but is **type-only**: `msgpackCodec` imports
+the `PortCodec` interface from it and no runtime code, so nothing of `webrun-rpc` is in the built
+bundle (`dist/index.js` imports `@ygoe/msgpack` and nothing else) and `webrun-rpc` gains no msgpack
+dependency in either direction.
+
+## How to use
+
+### Exports
 
 | Export | Direction | Use case |
 | --- | --- | --- |
@@ -24,6 +68,7 @@ Four exports — one encode/decode pair for generic values, one for `Float32Arra
 | `decodeMsgpack<T>(src: AsyncIterable<Uint8Array>)` | bytes → values | inverse of `encodeMsgpack` |
 | `encodeFloat32Arrays(src: AsyncIterable<Float32Array>)` | arrays → bytes | zero-copy float streaming |
 | `decodeFloat32Arrays(src: AsyncIterable<Uint8Array>)` | bytes → arrays | inverse of `encodeFloat32Arrays` |
+| `msgpackCodec: PortCodec` | envelope ⇄ one framed message | `multiplexPort` over a byte transport |
 
 ## Examples
 
@@ -82,6 +127,149 @@ for await (const v of decodeMsgpack<{ a: number; b: string }>(byOne())) {
 }
 ```
 
+### An RPC stream over a byte transport
+
+`msgpackCodec` on both ends of a transport that carries `Uint8Array`s, one virtual port, one
+`duplexOverPort` round trip. The pipe below stands in for the real thing — replace it with a
+WebSocket pair, an `RTCDataChannel`, or a LiveKit packet stream and nothing else changes.
+
+```js
+import { duplexOverPort, multiplexPort, serveDuplexOverPort } from "@statewalker/webrun-rpc";
+import { msgpackCodec } from "@statewalker/webrun-msgpack";
+
+// A byte transport: two ends that carry `Uint8Array`s and nothing else.
+function bytePipePair() {
+  const listeners = [new Set(), new Set()];
+  const make = (self) => ({
+    postMessage(bytes) {
+      const copy = bytes.slice(); // a real transport does not share the sender's buffer
+      setTimeout(() => {
+        for (const listener of [...listeners[1 - self]]) listener({ data: copy });
+      }, 0);
+    },
+    addEventListener: (_type, listener) => listeners[self].add(listener),
+    removeEventListener: (_type, listener) => listeners[self].delete(listener),
+  });
+  return { a: make(0), b: make(1) };
+}
+
+const pipe = bytePipePair();
+
+// The responder: every virtual port the peer opens gets an echo handler.
+const server = multiplexPort(pipe.b, {
+  codec: msgpackCodec,
+  side: "responder",
+  onPort: (port) => {
+    serveDuplexOverPort(port, async function* (input) {
+      for await (const chunk of input) yield chunk;
+    });
+  },
+});
+
+// The initiator: one virtual port, one duplex round trip over it.
+const client = multiplexPort(pipe.a, { codec: msgpackCodec, side: "initiator" });
+const port = await client.openPort({ kind: "stream" });
+const call = duplexOverPort(port, { maxMessageSize: client.maxMessageSize });
+
+async function* body() {
+  yield new TextEncoder().encode("hello ");
+  yield new TextEncoder().encode("bytes");
+}
+
+const decoder = new TextDecoder();
+let echoed = "";
+for await (const chunk of call(body())) echoed += decoder.decode(chunk);
+console.log(echoed); // "hello bytes"
+
+await client.close();
+await server.close();
+```
+
+The same stack passes the unmodified `webrun-streams-conformance` L0–L6 suite over a byte pipe, in
+both framing regimes — unlimited, and with frames capped at 64 KiB
+(`tests/conformance-bytes.test.ts`).
+
+**Read that green narrowly: an in-process pipe is not a transport.** The pipe hands `Uint8Array`s
+straight from one object to another inside one process, so what the suite covers is this codec's own
+contract end to end, including under chunking. It covers *none* of what a real byte transport brings:
+framing, message-size ceilings and what a transport does when you exceed one, backpressure,
+reconnection, close codes and error semantics. A WebSocket, an `RTCDataChannel` and a LiveKit data
+track each need their own run before anything here is claimed of them.
+
+## `maxMessageSize` bounds the payload, not the frame
+
+**Leave a margin of at least 256 bytes below your transport's hard limit.** This is the one thing
+that will bite you when wiring `msgpackCodec` to a capped transport, and the frame sizes below are
+measured rather than cautious:
+
+`duplexOverPort` applies `toChunks(maxMessageSize)` to the *payload*. The envelope framing —
+`WireChunk`, `callPort`'s `{type, channelName, callId, params}`, the mux's `{type, id, payload}`,
+then this codec — is added **on top, afterwards**. Over `msgpackCodec` that overhead is
+`87 + len(callId)` bytes and it is **not constant**: `callId` is
+`` `call-${Date.now()}-${String(Math.random()).substring(2)}` ``, whose length varies **31–40**
+characters *per chunk* because `Math.random()` drops trailing zeros; the port id's integer width
+adds 0–4; the channel name adds 1 for `"out"` over `"in"`; and a chunk at or above 64 KiB adds 2 as
+the payload's `bin` header widens.
+
+Two numbers, and the difference between them matters: adding those terms up gives a **modelled
+ceiling of 134 bytes**, while the overheads *actually observed* span **123–128 bytes**. The 134 is
+arithmetic; the 123–128 is measurement.
+
+The largest, 128, comes from a **64 KiB** cap — a 65,664-byte frame in the capped conformance run
+over a 10 MiB body — which is the regime where the `bin`-header term applies. A separate sweep, eight
+runs at a **16 KiB** cap with a 1 MiB body (several thousand chunks, so several thousand `callId`s),
+never exceeded **126** at that cap; the table below is one run per cap and is not that sweep. A
+256-byte margin covers all of it, which is why the advice is a round number rather than a tight one.
+
+Measured, with a 512 KiB body through the stack above:
+
+| `maxMessageSize` | intent | largest frame actually posted | overhead |
+| --- | --- | --- | --- |
+| `16 * 1024` | an `RTCDataChannel`'s conservative ceiling | **16,508 bytes** | 124 |
+| `12 * 1024` | LiveKit's safe packet size | **12,413 bytes** | 125 |
+| `64 * 1024` | | **65,662 bytes** | 126 |
+
+So setting `maxMessageSize` to the transport's hard limit **overruns it on the first full-size
+chunk** — and a transport that silently drops an oversized message (LiveKit does; the body arrives
+as zero bytes with no error on either side) gives you no signal at all. Set it to
+`limit - 256` and the arithmetic stops mattering.
+
+This is spec D10's correction, recorded in
+`docs/superpowers/specs/2026-09-05-port-multiplexer-design.md`.
+
+## Two things `msgpackCodec` does that `structuredCodec` does not
+
+**The transfer list is ignored.** `PortCodec.post` receives an optional `Transferable[]`;
+`msgpackCodec` drops it. After encoding, the payload is *inside* the bytes — there is no live
+`ArrayBuffer` left on the far side of the call to hand over, and passing the caller's original
+buffers as transferables would detach buffers the caller still owns. `structuredCodec` forwards the
+list, because there the objects themselves cross.
+
+**msgpack drops object keys whose value is explicitly `undefined`**; structured clone keeps them. So
+`{ result: undefined }` arrives as `{}` over this codec and as `{ result: undefined }` over
+`structuredCodec`. Nothing `webrun-rpc`'s layer 2 sends depends on the difference — every wire shape
+it produces is pinned against both codecs in `tests/codec-equivalence.test.ts` — and per **spec
+D16** it must not come to. If you build a payload where `"key" in obj` means something different
+from `obj.key === undefined`, it will not survive this codec.
+
+D16's reach has one open edge, worth knowing before you put arbitrary application errors on a byte
+transport: `serializeError` copies **every own enumerable property** off a thrown `Error` onto the
+wire. Whether the resulting `error` payload is msgpack-expressible therefore depends on what your
+code throws — a `cause` holding a `Map` or a class instance collapses to `{}`, and a circular
+reference makes `serialize` throw.
+
+## A `@ygoe/msgpack` wart, so nobody debugs it twice
+
+On some truncated input `@ygoe/msgpack`'s `deserialize` calls **`console.debug("msgpack array:", …)`
+with the whole offending buffer** before it throws. `msgpackCodec` catches the throw and drops the
+frame, but it cannot suppress the log — the call is inside the library.
+
+Precisely: the log fires when the decode runs off the end of the buffer *where a byte code is
+expected* (`Invalid byte value 'undefined' at index N`). A truncation that lands mid-string throws
+`Cannot read properties of undefined (reading 'toString')` with no log, and `0xc1` garbage or empty
+input throws silently. So the noise is real but intermittent — a peer that half-writes a frame will
+print a buffer dump on your console and nothing will be wrong with your code.
+
 ## Internals
 
 ### Frame layout
@@ -95,6 +283,8 @@ for await (const v of decodeMsgpack<{ a: number; b: string }>(byOne())) {
 
 - Big-endian 32-bit length prefix — same convention as Java `DataOutputStream` and most wire protocols.
 - Max payload per frame: 2³²−1 bytes. No fragmentation within a frame (a single call to `serialize` produces the whole payload up-front); very large values will allocate proportionally.
+- **This layout is the stream codec's only.** `msgpackCodec` writes a bare msgpack document per
+  message and prefixes nothing.
 
 ### Decoder state machine
 
@@ -108,30 +298,63 @@ The decoder keeps a rolling `Uint8Array` buffer. Each incoming chunk is appended
 
 Zero-length chunks are tolerated and simply no-op through the loop. Truncated trailing frames are silently dropped — the buffer retains them but the consuming `for await` ends without yielding a partial value.
 
+### What `msgpackCodec.read` accepts, and what it refuses
+
+It accepts whatever byte shape a transport pump hands over — a `Uint8Array`, a bare `ArrayBuffer`,
+or any `ArrayBufferView` (a `DataView` included, offset and length honoured). Everything else is
+refused by returning `undefined`: a non-byte value, empty bytes, malformed msgpack, and well-formed
+msgpack that decodes to something that is not a `PortEnvelope` (the `id` must be a non-negative
+integer and the `type` one of `open` / `message` / `close`). A shared transport carries traffic that
+is not ours, and layer 1 must not mistake it for an envelope.
+
+Refusal is always a dropped message, never a throw: a throw here would escape inside the raw port's
+own listener, outside any consumer's reach, and would let one hostile frame take the multiplexer
+down.
+
+There are three inputs for which `read` *can* still throw, all inside the byte-shape check that runs
+before the `try`: a detached `ArrayBuffer`, a `DataView` over a detached buffer, and a `Proxy` with
+a throwing `getPrototypeOf`. None is producible by a remote peer sending bytes — each needs
+same-process JavaScript already holding the backing memory — so the guarantee is "cannot throw for
+anything that arrives over a wire", not "cannot throw for any JavaScript value".
+
 ### Float32Array zero-copy
 
 `encodeFloat32Arrays` constructs a `Uint8Array` view over the `Float32Array`'s underlying buffer and serialises it as a msgpack `bin` payload — no float-by-float conversion. `decodeFloat32Arrays` reinterprets the decoded `Uint8Array` as a `Float32Array`. When the decoded buffer's `byteOffset` is not 4-byte aligned (can happen if `@ygoe/msgpack` returns a view into a larger buffer), we copy into a fresh aligned `Uint8Array` before constructing the `Float32Array`; otherwise the operation is view-only.
 
+### A trap when writing a transport pump
+
+`serialize` returns a **view** over an internal buffer that is not trimmed: a 10 MiB envelope
+measures ~10,485,800 bytes over a 16,777,216-byte `ArrayBuffer` (~1.6× slack, `byteOffset` 0). Send
+the view. A pump that reaches for `frame.buffer` instead would put ~6 MiB of trailing zeros on the
+wire per message.
+
 ### Dependencies
 
 - [`@ygoe/msgpack`](https://github.com/ygoe/msgpack.js) — single-file msgpack implementation (≈7 kB gzipped), no transitive deps.
+- [`@statewalker/webrun-rpc`](../webrun-rpc) — **types only** (`PortCodec`, `PortEnvelope`); no runtime import is emitted.
 
-Dev: TypeScript, vitest, tsdown, rimraf (catalog versions from the monorepo root).
+Dev: TypeScript, vitest, rolldown, rimraf (catalog versions from the monorepo root).
+`@statewalker/webrun-streams` and `@statewalker/webrun-streams-conformance` are dev-only, for the
+conformance run.
 
 ### Constraints
 
 - Big-endian length prefix only — no little-endian variant.
 - `decodeMsgpack` allocates one `Uint8Array` per incoming chunk for the `concat`; long streams with many tiny chunks may benefit from a batched source upstream.
 - `Float32Array` codec is strictly `Float32` — no element-size negotiation.
+- `msgpackCodec` carries no length prefix, so it is **unusable** on a transport without message
+  boundaries. Use the stream codec there.
 
 ## Scripts
 
 ```sh
-pnpm test        # vitest run (25 tests)
-pnpm run build   # tsdown
-pnpm lint        # biome check
+pnpm test              # vitest run (84 tests / 4 files)
+pnpm run build         # rolldown + tsc --emitDeclarationOnly
+pnpm lint              # biome check src tests
+pnpm typecheck         # tsc --noEmit (src)
+pnpm typecheck:tests   # tsc -p tsconfig.tests.json — needs the sibling packages built
 ```
 
 ## License
 
-MIT © statewalker
+MIT © statewalker — see [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { decodeFloat32Arrays, decodeMsgpack, encodeFloat32Arrays, encodeMsgpack, } from "./msgpack.js";
+export { msgpackCodec } from "./port-codec.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,133 @@
+import msgpack from "@ygoe/msgpack";
+//#region src/msgpack.ts
+const { serialize: serialize$1, deserialize: deserialize$1 } = msgpack;
+/**
+* Encode each value as a length-prefixed msgpack frame.
+* Frame format: [4-byte big-endian length][msgpack bytes]
+*/
+async function* encodeMsgpack(input) {
+	for await (const item of input) {
+		const payload = serialize$1(item);
+		const frame = new Uint8Array(4 + payload.length);
+		new DataView(frame.buffer).setUint32(0, payload.length, false);
+		frame.set(payload, 4);
+		yield frame;
+	}
+}
+/**
+* Decode length-prefixed msgpack frames, reassembling across chunk boundaries.
+*/
+async function* decodeMsgpack(input) {
+	let buffer = /* @__PURE__ */ new Uint8Array(0);
+	for await (const chunk of input) {
+		buffer = concat(buffer, chunk);
+		while (buffer.length >= 4) {
+			const frameLen = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength).getUint32(0, false);
+			if (buffer.length < 4 + frameLen) break;
+			const payload = buffer.subarray(4, 4 + frameLen);
+			buffer = buffer.subarray(4 + frameLen);
+			yield deserialize$1(Uint8Array.from(payload));
+		}
+	}
+}
+/**
+* Encode each Float32Array as a msgpack frame.
+* The Float32Array is converted to a Uint8Array view (zero-copy) before encoding as msgpack bin.
+*/
+async function* encodeFloat32Arrays(input) {
+	for await (const arr of input) {
+		const bytes = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+		const payload = serialize$1(bytes);
+		const frame = new Uint8Array(4 + payload.length);
+		new DataView(frame.buffer).setUint32(0, payload.length, false);
+		frame.set(payload, 4);
+		yield frame;
+	}
+}
+/**
+* Decode msgpack frames back to Float32Array.
+* Each frame contains a msgpack bin value (Uint8Array), reinterpreted as Float32Array.
+*/
+async function* decodeFloat32Arrays(input) {
+	for await (const item of decodeMsgpack(wrapIterable(input))) {
+		const aligned = alignBuffer(item);
+		yield new Float32Array(aligned.buffer, aligned.byteOffset, aligned.byteLength / 4);
+	}
+}
+function alignBuffer(bytes) {
+	if (bytes.byteOffset % 4 === 0) return bytes;
+	const aligned = new Uint8Array(bytes.length);
+	aligned.set(bytes);
+	return aligned;
+}
+function concat(a, b) {
+	if (a.length === 0) return b;
+	const result = new Uint8Array(a.length + b.length);
+	result.set(a, 0);
+	result.set(b, a.length);
+	return result;
+}
+async function* wrapIterable(input) {
+	yield* input;
+}
+//#endregion
+//#region src/port-codec.ts
+const { serialize, deserialize } = msgpack;
+/**
+* Same shape check as `structuredCodec`'s, applied after decoding. A shared
+* transport carries traffic that is not ours, and layer 1 must not mistake it
+* for an envelope.
+*/
+function isEnvelope(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	if (typeof candidate.id !== "number") return false;
+	if (!Number.isInteger(candidate.id) || candidate.id < 0) return false;
+	return candidate.type === "open" || candidate.type === "message" || candidate.type === "close";
+}
+/** Accept whatever byte shape a transport pump hands over. */
+function toBytes(data) {
+	if (data instanceof Uint8Array) return data;
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	if (ArrayBuffer.isView(data)) {
+		const view = data;
+		return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+	}
+}
+/**
+* For ports whose messages are bytes — a WebSocket, a WebRTC data channel, a
+* LiveKit data packet.
+*
+* One envelope becomes one msgpack frame and one `postMessage`. There is no
+* length prefix, because every transport this codec targets preserves message
+* boundaries; adding one would be redundant framing on a transport that
+* already frames. (`encodeMsgpack`/`decodeMsgpack` in this package *do* carry
+* a length prefix — they are a stream codec for a transport with no
+* boundaries, and are a different thing.)
+*
+* The transfer list is deliberately ignored: after encoding, the payload is
+* inside the bytes, so there is nothing left to hand over.
+*
+* **Not interchangeable with `structuredCodec` in one respect:** msgpack drops
+* object keys whose value is `undefined`, where structured clone preserves
+* them. Nothing layer 2 sends depends on that distinction today, and it must
+* not come to — see spec D16.
+*/
+const msgpackCodec = {
+	post(port, envelope) {
+		port.postMessage(serialize(envelope));
+	},
+	read(event) {
+		const bytes = toBytes(event.data);
+		if (!bytes || bytes.byteLength === 0) return void 0;
+		let decoded;
+		try {
+			decoded = deserialize(bytes);
+		} catch {
+			return;
+		}
+		return isEnvelope(decoded) ? decoded : void 0;
+	}
+};
+//#endregion
+export { decodeFloat32Arrays, decodeMsgpack, encodeFloat32Arrays, encodeMsgpack, msgpackCodec };

package/dist/msgpack.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Encode each value as a length-prefixed msgpack frame.
+ * Frame format: [4-byte big-endian length][msgpack bytes]
+ */
+export declare function encodeMsgpack<T>(input: AsyncIterable<T>): AsyncGenerator<Uint8Array>;
+/**
+ * Decode length-prefixed msgpack frames, reassembling across chunk boundaries.
+ */
+export declare function decodeMsgpack<T>(input: AsyncIterable<Uint8Array>): AsyncGenerator<T>;
+/**
+ * Encode each Float32Array as a msgpack frame.
+ * The Float32Array is converted to a Uint8Array view (zero-copy) before encoding as msgpack bin.
+ */
+export declare function encodeFloat32Arrays(input: AsyncIterable<Float32Array>): AsyncGenerator<Uint8Array>;
+/**
+ * Decode msgpack frames back to Float32Array.
+ * Each frame contains a msgpack bin value (Uint8Array), reinterpreted as Float32Array.
+ */
+export declare function decodeFloat32Arrays(input: AsyncIterable<Uint8Array>): AsyncGenerator<Float32Array>;
+//# sourceMappingURL=msgpack.d.ts.map

package/dist/msgpack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msgpack.d.ts","sourceRoot":"","sources":["../src/msgpack.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,wBAAuB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAS3F;AAED;;GAEG;AACH,wBAAuB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAgB3F;AAED;;;GAGG;AACH,wBAAuB,mBAAmB,CACxC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GACjC,cAAc,CAAC,UAAU,CAAC,CAU5B;AAED;;;GAGG;AACH,wBAAuB,mBAAmB,CACxC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,GAC/B,cAAc,CAAC,YAAY,CAAC,CAK9B"}

package/dist/port-codec.d.ts

@@ -0,0 +1,22 @@
+import type { PortCodec } from "@statewalker/webrun-rpc";
+/**
+ * For ports whose messages are bytes — a WebSocket, a WebRTC data channel, a
+ * LiveKit data packet.
+ *
+ * One envelope becomes one msgpack frame and one `postMessage`. There is no
+ * length prefix, because every transport this codec targets preserves message
+ * boundaries; adding one would be redundant framing on a transport that
+ * already frames. (`encodeMsgpack`/`decodeMsgpack` in this package *do* carry
+ * a length prefix — they are a stream codec for a transport with no
+ * boundaries, and are a different thing.)
+ *
+ * The transfer list is deliberately ignored: after encoding, the payload is
+ * inside the bytes, so there is nothing left to hand over.
+ *
+ * **Not interchangeable with `structuredCodec` in one respect:** msgpack drops
+ * object keys whose value is `undefined`, where structured clone preserves
+ * them. Nothing layer 2 sends depends on that distinction today, and it must
+ * not come to — see spec D16.
+ */
+export declare const msgpackCodec: PortCodec;
+//# sourceMappingURL=port-codec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"port-codec.d.ts","sourceRoot":"","sources":["../src/port-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,yBAAyB,CAAC;AA6BvE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,EAAE,SAmB1B,CAAC"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@statewalker/webrun-msgpack",
-  "version": "0.1.1",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
-  "description": "Length-prefixed MessagePack frame codec for async iterables. Streams-safe encode/decode for values and Float32Arrays.",
+  "description": "MessagePack codecs for the wire: a length-prefixed stream codec for async iterables (values and Float32Arrays), and msgpackCodec, a PortCodec that carries webrun-rpc port envelopes over a byte transport.",
   "homepage": "https://github.com/statewalker/webrun-wire",
   "author": {
     "name": "Mikhail Kotelnikov",
@@ -16,33 +16,41 @@
     "directory": "packages/webrun-msgpack"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@ygoe/msgpack": "^1.0.3"
+    "@ygoe/msgpack": "^1.0.3",
+    "@statewalker/webrun-rpc": "0.4.0"
   },
   "devDependencies": {
     "rimraf": "^6.1.3",
-    "tsdown": "^0.22.14",
+    "rolldown": "^1.2.4",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "@statewalker/webrun-streams": "0.2.0",
+    "@statewalker/webrun-streams-conformance": "0.2.0"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsdown",
+    "build": "rimraf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
     "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
     "clean": "rimraf dist",
-    "lint": "biome check --write .",
+    "lint": "biome check src tests",
     "format": "biome format --write ."
   }
 }

package/src/index.ts

@@ -4,3 +4,4 @@ export {
   encodeFloat32Arrays,
   encodeMsgpack,
 } from "./msgpack.js";
+export { msgpackCodec } from "./port-codec.js";

package/src/port-codec.ts

@@ -0,0 +1,68 @@
+import type { PortCodec, PortEnvelope } from "@statewalker/webrun-rpc";
+import msgpack from "@ygoe/msgpack";
+
+const { serialize, deserialize } = msgpack;
+
+/**
+ * Same shape check as `structuredCodec`'s, applied after decoding. A shared
+ * transport carries traffic that is not ours, and layer 1 must not mistake it
+ * for an envelope.
+ */
+function isEnvelope(value: unknown): value is PortEnvelope {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { type?: unknown; id?: unknown };
+  if (typeof candidate.id !== "number") return false;
+  if (!Number.isInteger(candidate.id) || candidate.id < 0) return false;
+  return candidate.type === "open" || candidate.type === "message" || candidate.type === "close";
+}
+
+/** Accept whatever byte shape a transport pump hands over. */
+function toBytes(data: unknown): Uint8Array | undefined {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (ArrayBuffer.isView(data)) {
+    const view = data as ArrayBufferView;
+    return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+  }
+  return undefined;
+}
+
+/**
+ * For ports whose messages are bytes — a WebSocket, a WebRTC data channel, a
+ * LiveKit data packet.
+ *
+ * One envelope becomes one msgpack frame and one `postMessage`. There is no
+ * length prefix, because every transport this codec targets preserves message
+ * boundaries; adding one would be redundant framing on a transport that
+ * already frames. (`encodeMsgpack`/`decodeMsgpack` in this package *do* carry
+ * a length prefix — they are a stream codec for a transport with no
+ * boundaries, and are a different thing.)
+ *
+ * The transfer list is deliberately ignored: after encoding, the payload is
+ * inside the bytes, so there is nothing left to hand over.
+ *
+ * **Not interchangeable with `structuredCodec` in one respect:** msgpack drops
+ * object keys whose value is `undefined`, where structured clone preserves
+ * them. Nothing layer 2 sends depends on that distinction today, and it must
+ * not come to — see spec D16.
+ */
+export const msgpackCodec: PortCodec = {
+  post(port, envelope) {
+    port.postMessage(serialize(envelope));
+  },
+
+  read(event) {
+    const bytes = toBytes(event.data);
+    if (!bytes || bytes.byteLength === 0) return undefined;
+    let decoded: unknown;
+    try {
+      decoded = deserialize(bytes);
+    } catch {
+      // A malformed frame is a peer bug or hostile traffic. Dropping it keeps
+      // layer 1's drop-never-queue posture; throwing here would escape into
+      // the raw port's own listener, outside any consumer's reach.
+      return undefined;
+    }
+    return isEnvelope(decoded) ? decoded : undefined;
+  },
+};

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022-2026 statewalker
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/index.d.mts

@@ -1,23 +0,0 @@
-//#region src/msgpack.d.ts
-/**
- * Encode each value as a length-prefixed msgpack frame.
- * Frame format: [4-byte big-endian length][msgpack bytes]
- */
-declare function encodeMsgpack<T>(input: AsyncIterable<T>): AsyncGenerator<Uint8Array>;
-/**
- * Decode length-prefixed msgpack frames, reassembling across chunk boundaries.
- */
-declare function decodeMsgpack<T>(input: AsyncIterable<Uint8Array>): AsyncGenerator<T>;
-/**
- * Encode each Float32Array as a msgpack frame.
- * The Float32Array is converted to a Uint8Array view (zero-copy) before encoding as msgpack bin.
- */
-declare function encodeFloat32Arrays(input: AsyncIterable<Float32Array>): AsyncGenerator<Uint8Array>;
-/**
- * Decode msgpack frames back to Float32Array.
- * Each frame contains a msgpack bin value (Uint8Array), reinterpreted as Float32Array.
- */
-declare function decodeFloat32Arrays(input: AsyncIterable<Uint8Array>): AsyncGenerator<Float32Array>;
-//#endregion
-export { decodeFloat32Arrays, decodeMsgpack, encodeFloat32Arrays, encodeMsgpack };
-//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/msgpack.ts"],"mappings":";;;;;iBAQuB,cAAc,GAAG,OAAO,cAAc,KAAK,eAAe;;;;iBAc1D,cAAc,GAAG,OAAO,cAAc,cAAc,eAAe;;;;;iBAsBnE,oBACrB,OAAO,cAAc,gBACpB,eAAe;;;;;iBAgBK,oBACrB,OAAO,cAAc,cACpB,eAAe"}

package/dist/index.mjs

@@ -1,76 +0,0 @@
-import msgpack from "@ygoe/msgpack";
-//#region src/msgpack.ts
-const { serialize, deserialize } = msgpack;
-/**
-* Encode each value as a length-prefixed msgpack frame.
-* Frame format: [4-byte big-endian length][msgpack bytes]
-*/
-async function* encodeMsgpack(input) {
-	for await (const item of input) {
-		const payload = serialize(item);
-		const frame = new Uint8Array(4 + payload.length);
-		new DataView(frame.buffer).setUint32(0, payload.length, false);
-		frame.set(payload, 4);
-		yield frame;
-	}
-}
-/**
-* Decode length-prefixed msgpack frames, reassembling across chunk boundaries.
-*/
-async function* decodeMsgpack(input) {
-	let buffer = /* @__PURE__ */ new Uint8Array(0);
-	for await (const chunk of input) {
-		buffer = concat(buffer, chunk);
-		while (buffer.length >= 4) {
-			const frameLen = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength).getUint32(0, false);
-			if (buffer.length < 4 + frameLen) break;
-			const payload = buffer.subarray(4, 4 + frameLen);
-			buffer = buffer.subarray(4 + frameLen);
-			yield deserialize(Uint8Array.from(payload));
-		}
-	}
-}
-/**
-* Encode each Float32Array as a msgpack frame.
-* The Float32Array is converted to a Uint8Array view (zero-copy) before encoding as msgpack bin.
-*/
-async function* encodeFloat32Arrays(input) {
-	for await (const arr of input) {
-		const bytes = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
-		const payload = serialize(bytes);
-		const frame = new Uint8Array(4 + payload.length);
-		new DataView(frame.buffer).setUint32(0, payload.length, false);
-		frame.set(payload, 4);
-		yield frame;
-	}
-}
-/**
-* Decode msgpack frames back to Float32Array.
-* Each frame contains a msgpack bin value (Uint8Array), reinterpreted as Float32Array.
-*/
-async function* decodeFloat32Arrays(input) {
-	for await (const item of decodeMsgpack(wrapIterable(input))) {
-		const aligned = alignBuffer(item);
-		yield new Float32Array(aligned.buffer, aligned.byteOffset, aligned.byteLength / 4);
-	}
-}
-function alignBuffer(bytes) {
-	if (bytes.byteOffset % 4 === 0) return bytes;
-	const aligned = new Uint8Array(bytes.length);
-	aligned.set(bytes);
-	return aligned;
-}
-function concat(a, b) {
-	if (a.length === 0) return b;
-	const result = new Uint8Array(a.length + b.length);
-	result.set(a, 0);
-	result.set(b, a.length);
-	return result;
-}
-async function* wrapIterable(input) {
-	yield* input;
-}
-//#endregion
-export { decodeFloat32Arrays, decodeMsgpack, encodeFloat32Arrays, encodeMsgpack };
-
-//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/msgpack.ts"],"sourcesContent":["import msgpack from \"@ygoe/msgpack\";\n\nconst { serialize, deserialize } = msgpack;\n\n/**\n * Encode each value as a length-prefixed msgpack frame.\n * Frame format: [4-byte big-endian length][msgpack bytes]\n */\nexport async function* encodeMsgpack<T>(input: AsyncIterable<T>): AsyncGenerator<Uint8Array> {\n  for await (const item of input) {\n    const payload = serialize(item);\n    const frame = new Uint8Array(4 + payload.length);\n    const view = new DataView(frame.buffer);\n    view.setUint32(0, payload.length, false);\n    frame.set(payload, 4);\n    yield frame;\n  }\n}\n\n/**\n * Decode length-prefixed msgpack frames, reassembling across chunk boundaries.\n */\nexport async function* decodeMsgpack<T>(input: AsyncIterable<Uint8Array>): AsyncGenerator<T> {\n  let buffer: Uint8Array = new Uint8Array(0);\n\n  for await (const chunk of input) {\n    buffer = concat(buffer, chunk);\n\n    while (buffer.length >= 4) {\n      const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);\n      const frameLen = view.getUint32(0, false);\n      if (buffer.length < 4 + frameLen) break;\n\n      const payload = buffer.subarray(4, 4 + frameLen);\n      buffer = buffer.subarray(4 + frameLen);\n      yield deserialize(Uint8Array.from(payload)) as T;\n    }\n  }\n}\n\n/**\n * Encode each Float32Array as a msgpack frame.\n * The Float32Array is converted to a Uint8Array view (zero-copy) before encoding as msgpack bin.\n */\nexport async function* encodeFloat32Arrays(\n  input: AsyncIterable<Float32Array>,\n): AsyncGenerator<Uint8Array> {\n  for await (const arr of input) {\n    const bytes = new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);\n    const payload = serialize(bytes);\n    const frame = new Uint8Array(4 + payload.length);\n    const view = new DataView(frame.buffer);\n    view.setUint32(0, payload.length, false);\n    frame.set(payload, 4);\n    yield frame;\n  }\n}\n\n/**\n * Decode msgpack frames back to Float32Array.\n * Each frame contains a msgpack bin value (Uint8Array), reinterpreted as Float32Array.\n */\nexport async function* decodeFloat32Arrays(\n  input: AsyncIterable<Uint8Array>,\n): AsyncGenerator<Float32Array> {\n  for await (const item of decodeMsgpack<Uint8Array>(wrapIterable(input))) {\n    const aligned = alignBuffer(item);\n    yield new Float32Array(aligned.buffer, aligned.byteOffset, aligned.byteLength / 4);\n  }\n}\n\nfunction alignBuffer(bytes: Uint8Array): Uint8Array {\n  if (bytes.byteOffset % 4 === 0) return bytes;\n  const aligned = new Uint8Array(bytes.length);\n  aligned.set(bytes);\n  return aligned;\n}\n\nfunction concat(a: Uint8Array, b: Uint8Array): Uint8Array {\n  if (a.length === 0) return b;\n  const result = new Uint8Array(a.length + b.length);\n  result.set(a, 0);\n  result.set(b, a.length);\n  return result;\n}\n\nasync function* wrapIterable<T>(input: AsyncIterable<T>): AsyncGenerator<T> {\n  yield* input;\n}\n"],"mappings":";;AAEA,MAAM,EAAE,WAAW,gBAAgB;;;;;AAMnC,gBAAuB,cAAiB,OAAqD;CAC3F,WAAW,MAAM,QAAQ,OAAO;EAC9B,MAAM,UAAU,UAAU,IAAI;EAC9B,MAAM,QAAQ,IAAI,WAAW,IAAI,QAAQ,MAAM;EAE/C,IADiB,SAAS,MAAM,MAC7B,CAAC,CAAC,UAAU,GAAG,QAAQ,QAAQ,KAAK;EACvC,MAAM,IAAI,SAAS,CAAC;EACpB,MAAM;CACR;AACF;;;;AAKA,gBAAuB,cAAiB,OAAqD;CAC3F,IAAI,yBAAqB,IAAI,WAAW,CAAC;CAEzC,WAAW,MAAM,SAAS,OAAO;EAC/B,SAAS,OAAO,QAAQ,KAAK;EAE7B,OAAO,OAAO,UAAU,GAAG;GAEzB,MAAM,WAAW,IADA,SAAS,OAAO,QAAQ,OAAO,YAAY,OAAO,UAC/C,CAAC,CAAC,UAAU,GAAG,KAAK;GACxC,IAAI,OAAO,SAAS,IAAI,UAAU;GAElC,MAAM,UAAU,OAAO,SAAS,GAAG,IAAI,QAAQ;GAC/C,SAAS,OAAO,SAAS,IAAI,QAAQ;GACrC,MAAM,YAAY,WAAW,KAAK,OAAO,CAAC;EAC5C;CACF;AACF;;;;;AAMA,gBAAuB,oBACrB,OAC4B;CAC5B,WAAW,MAAM,OAAO,OAAO;EAC7B,MAAM,QAAQ,IAAI,WAAW,IAAI,QAAQ,IAAI,YAAY,IAAI,UAAU;EACvE,MAAM,UAAU,UAAU,KAAK;EAC/B,MAAM,QAAQ,IAAI,WAAW,IAAI,QAAQ,MAAM;EAE/C,IADiB,SAAS,MAAM,MAC7B,CAAC,CAAC,UAAU,GAAG,QAAQ,QAAQ,KAAK;EACvC,MAAM,IAAI,SAAS,CAAC;EACpB,MAAM;CACR;AACF;;;;;AAMA,gBAAuB,oBACrB,OAC8B;CAC9B,WAAW,MAAM,QAAQ,cAA0B,aAAa,KAAK,CAAC,GAAG;EACvE,MAAM,UAAU,YAAY,IAAI;EAChC,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,YAAY,QAAQ,aAAa,CAAC;CACnF;AACF;AAEA,SAAS,YAAY,OAA+B;CAClD,IAAI,MAAM,aAAa,MAAM,GAAG,OAAO;CACvC,MAAM,UAAU,IAAI,WAAW,MAAM,MAAM;CAC3C,QAAQ,IAAI,KAAK;CACjB,OAAO;AACT;AAEA,SAAS,OAAO,GAAe,GAA2B;CACxD,IAAI,EAAE,WAAW,GAAG,OAAO;CAC3B,MAAM,SAAS,IAAI,WAAW,EAAE,SAAS,EAAE,MAAM;CACjD,OAAO,IAAI,GAAG,CAAC;CACf,OAAO,IAAI,GAAG,EAAE,MAAM;CACtB,OAAO;AACT;AAEA,gBAAgB,aAAgB,OAA4C;CAC1E,OAAO;AACT"}