From 15ddf44ef7c54e7e587ef99d202c1f6c3e96ba32 Mon Sep 17 00:00:00 2001
From: Roman Volosatovs <rvolosatovs@riseup.net>
Date: Mon, 22 Jun 2026 19:56:00 +0200
Subject: [PATCH] feat(js): add wRPC codec package

Add `js/` (`@bytecodealliance/wrpc`), a dependency-free, transport-agnostic
JavaScript codec for the wRPC wire format, mirroring `wrpc-transport`'s
`value.rs` and default framing:

- `t`/`types` build the structural WIT type tree;
- `value` encodes/decodes component-model values (a jco-compatible mapping);
- `wit` parses inlined WIT text back into the type tree;
- `frame` builds an invocation's request bytes and decodes its results.

The ESM source runs directly in the browser and is publishable to npm; it
ships a hand-written `.d.ts`, JSDoc, `node --test` round-trip tests and a
`tsc` typecheck.

Use the codec in the `wasi:keyvalue` web example: the UI imports it from
`/wrpc` (served via `ServeDir`) and drops the hand-rolled byte encoding,
removing the 127-byte request/response size limits.

Assisted-by: claude:claude-opus-4-8
---
 .github/workflows/wrpc.yml    |  18 ++
 examples/web/rust/src/main.rs |   6 +
 examples/web/ui/index.html    | 369 ++++++-------------------------
 js/.gitignore                 |   2 +
 js/README.md                  | 145 +++++++++++++
 js/package-lock.json          |  33 +++
 js/package.json               |  45 ++++
 js/src/index.d.ts             | 188 ++++++++++++++++
 js/src/index.js               |  15 ++
 js/src/io.js                  | 315 +++++++++++++++++++++++++++
 js/src/mux.js                 | 200 +++++++++++++++++
 js/src/session.js             | 323 +++++++++++++++++++++++++++
 js/src/types.js               | 110 ++++++++++
 js/src/value.js               | 395 ++++++++++++++++++++++++++++++++++
 js/test/session.test.js       | 201 +++++++++++++++++
 js/test/value.test.js         | 151 +++++++++++++
 js/tsconfig.json              |  14 ++
 17 files changed, 2230 insertions(+), 300 deletions(-)
 create mode 100644 js/.gitignore
 create mode 100644 js/README.md
 create mode 100644 js/package-lock.json
 create mode 100644 js/package.json
 create mode 100644 js/src/index.d.ts
 create mode 100644 js/src/index.js
 create mode 100644 js/src/io.js
 create mode 100644 js/src/mux.js
 create mode 100644 js/src/session.js
 create mode 100644 js/src/types.js
 create mode 100644 js/src/value.js
 create mode 100644 js/test/session.test.js
 create mode 100644 js/test/value.test.js
 create mode 100644 js/tsconfig.json

diff --git a/.github/workflows/wrpc.yml b/.github/workflows/wrpc.yml
index 7a7b7305c..82a88ee36 100644
--- a/.github/workflows/wrpc.yml
+++ b/.github/workflows/wrpc.yml
@@ -200,6 +200,24 @@ jobs:
         if: ${{ matrix.check == 'nextest' }}
       - run: nix build -L .#checks.x86_64-linux.${{ matrix.check }}
 
+  js:
+    if: ${{ !startsWith(github.ref, 'refs/tags/go/') }}
+    name: js
+    runs-on: ubuntu-24.04
+    defaults:
+      run:
+        working-directory: ./js
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: js/package-lock.json
+      - run: npm ci
+      - run: npm run check
+      - run: npm test
+
   crates:
     if: ${{ !startsWith(github.ref, 'refs/tags/go/') }}
     strategy:
diff --git a/examples/web/rust/src/main.rs b/examples/web/rust/src/main.rs
index 0fe03d401..97d93748f 100644
--- a/examples/web/rust/src/main.rs
+++ b/examples/web/rust/src/main.rs
@@ -23,6 +23,7 @@ use rustls::{DigitallySignedStruct, SignatureScheme};
 use tokio::sync::{Notify, RwLock};
 use tokio::task::JoinSet;
 use tokio::{select, signal};
+use tower_http::services::ServeDir;
 use tower_http::trace::TraceLayer;
 use tracing::{debug, error, info, instrument, trace, warn};
 use tracing_subscriber::layer::SubscriberExt as _;
@@ -616,6 +617,11 @@ export const PORT = "{port}"
                     ),
                 )),
             )
+            // Serve the `@bytecodealliance/wrpc` client the UI imports.
+            .nest_service(
+                "/wrpc",
+                ServeDir::new(concat!(env!("CARGO_MANIFEST_DIR"), "/../../../js/src")),
+            )
             .fallback(index)
             .layer(TraceLayer::new_for_http()),
     );
diff --git a/examples/web/ui/index.html b/examples/web/ui/index.html
index db3c43de2..b24a4e9b4 100644
--- a/examples/web/ui/index.html
+++ b/examples/web/ui/index.html
@@ -32,12 +32,54 @@
         }
     </style>
     <script type="module">
+        // The wRPC wire encoding, framing and invocation are provided by the
+        // `@bytecodealliance/wrpc` client, served by the backend under `/wrpc`.
+        import { t, invoke as wrpcInvoke, fromWebStreams } from '/wrpc/index.js';
+
+        // `wasi:keyvalue/store`, as served by the backend. The types mirror the
+        // WIT in `crates/wasi-keyvalue/wit/deps/keyvalue/store.wit`; the codec
+        // walks them to encode arguments and decode results.
+        const STORE = 'wasi:keyvalue/store@0.2.0-draft2';
+        const error = t.variant({ 'no-such-store': null, 'access-denied': null, other: t.string });
+
+        // open: func(identifier: string) -> result<bucket, error>
+        const OPEN = { params: [t.string], results: [t.result(t.own('bucket'), error)] };
+        // bucket.get: func(key: string) -> result<option<list<u8>>, error>
+        const GET = {
+            params: [t.borrow('bucket'), t.string],
+            results: [t.result(t.option(t.list(t.u8)), error)],
+        };
+        // bucket.set: func(key: string, value: list<u8>) -> result<_, error>
+        const SET = {
+            params: [t.borrow('bucket'), t.string, t.list(t.u8)],
+            results: [t.result(null, error)],
+        };
+
         let conn;
         let buckets = new Map();
 
-        function toHex(v) {
-            if (!v) return '';
-            return v.reduce((s, x) => s + x.toString(16).padStart(2, '0'), '')
+        // Invoke `func` on `instance` over a fresh WebTransport bidirectional
+        // stream. The framed transport maps one stream to one invocation; the
+        // client writes the request, streams any async parameters, and decodes
+        // the reply (and any async results) until all I/O is done.
+        async function invoke(instance, func, paramTypes, resultTypes, args) {
+            if (!conn) throw 'WebTransport not connected';
+            const stream = await conn.createBidirectionalStream();
+            const { results, done } = await wrpcInvoke(
+                fromWebStreams(stream), instance, func, paramTypes, args, resultTypes,
+            );
+            await done;
+            return results;
+        }
+
+        // Render a decoded `error` variant value (`{ tag, val? }`) as a string.
+        function formatError(err) {
+            switch (err.tag) {
+                case 'no-such-store': return 'no such store';
+                case 'access-denied': return 'access denied';
+                case 'other': return err.val;
+                default: return `unknown error \`${err.tag}\``;
+            }
         }
 
         function uuidString(v) {
@@ -55,235 +97,6 @@
             }, '')
         }
 
-        async function wasiKeyvalueStoreOpen(tx, rx, identifier) {
-            const text = new TextEncoder();
-
-            const idBuf = text.encode(identifier);
-            if (idBuf.length > 127) throw 'this example currently does not support identifiers longer than 127 bytes - open a PR!';
-
-            const payloadBytes = 1 + idBuf.length;
-            if (payloadBytes > 127) throw 'this example currently does not support requests payload longer than 127 bytes - open a PR!';
-
-            let buf = new Uint8Array([
-                0,
-                'wasi:keyvalue/store@0.2.0-draft2'.length,
-                ...text.encode('wasi:keyvalue/store@0.2.0-draft2'),
-                'open'.length,
-                ...text.encode('open'),
-                0,
-                payloadBytes,
-                idBuf.length,
-                ...idBuf
-            ]);
-            dbg.debug('writing `open("' + identifier + '")` invocation: ' + toHex(buf));
-            await tx.write(buf);
-
-            dbg.debug('awaiting write to complete');
-            await tx.ready;
-            tx.close();
-
-            dbg.debug('reading `open` response...');
-            buf = null;
-            return await rx.read().then(function handleChunk({done, value}) {
-                if (!buf) {
-                    buf = value;
-                } else if (value) {
-                    const b = new Uint8Array(buf.length + value.length);
-                    b.set(buf);
-                    b.set(value, buf.length);
-                    buf = b;
-                }
-                if (done) {
-                    if (!buf || buf.length < 4) throw 'unexpected EOF';
-                    dbg.debug('received `open` response: ' + toHex(buf));
-                    if (buf[0] != 0) throw 'unexpected path'
-                    if (buf[1] > 127) throw 'only decoding responses of up to 127 bytes is currently supported - open a PR!'
-                    switch (buf[2]) {
-                        case 0:
-                            // ok
-                            return buf.subarray(4);
-                        case 1:
-                            // error
-                            switch (buf[3]) {
-                                case 0:
-                                    throw "no such store";
-                                case 1:
-                                    throw "access denied";
-                                case 2:
-                                    const err = new TextDecoder().decode(buf.subarray(5));
-                                    throw err;
-                            }
-                        default:
-                            throw "invalid result status byte"
-                    }
-                }
-                return rx.read().then(handleChunk);
-            }, err => {
-                throw 'failed to read `open` response: ' + err;
-            })
-        }
-
-        async function wasiKeyvalueStoreBucketGet(tx, rx, bucket, key) {
-            const text = new TextEncoder();
-
-            if (bucket.length > 127) throw 'this example currently does not support buckets longer than 127 bytes - open a PR!';
-
-            const keyBuf = text.encode(key);
-            if (keyBuf.length > 127) throw 'this example currently does not support keys longer than 127 bytes - open a PR!';
-
-            const payloadBytes = 2 + bucket.length + keyBuf.length;
-            if (payloadBytes > 127) throw 'this example currently does not support request payloads longer than 127 bytes - open a PR!';
-
-            let buf = new Uint8Array([
-                0,
-                'wasi:keyvalue/store@0.2.0-draft2'.length,
-                ...text.encode('wasi:keyvalue/store@0.2.0-draft2'),
-                'bucket.get'.length,
-                ...text.encode('bucket.get'),
-                0,
-                payloadBytes,
-                bucket.length,
-                ...bucket,
-                keyBuf.length,
-                ...keyBuf
-            ]);
-
-            dbg.debug('writing `bucket.get("' + bucket + '", "' + key + '")` invocation: ' + toHex(buf));
-            await tx.write(buf);
-
-            dbg.debug('awaiting write to complete');
-            await tx.ready;
-            tx.close();
-
-            dbg.debug('reading `bucket.get` response...');
-            buf = null;
-            return await rx.read().then(function handleChunk({done, value}) {
-                if (!buf) {
-                    buf = value;
-                } else if (value) {
-                    const b = new Uint8Array(buf.length + value.length);
-                    b.set(buf);
-                    b.set(value, buf.length);
-                    buf = b;
-                }
-                if (done) {
-                    if (!buf || buf.length < 4) throw 'unexpected EOF';
-                    dbg.debug('received `bucket.get` response: ' + toHex(buf));
-                    if (buf[0] != 0) throw 'unexpected path'
-                    if (buf[1] > 127) throw 'only decoding responses of up to 127 bytes is currently supported - open a PR!'
-                    switch (buf[2]) {
-                        case 0:
-                            // ok
-                            switch (buf[3]) {
-                                case 0:
-                                    // none
-                                    return null
-                                case 1:
-                                    // some
-                                    if (buf.length < 5) throw 'unexpected EOF'
-                                    return buf.subarray(5)
-                                default:
-                                    throw "invalid option status byte"
-                            }
-                        case 1:
-                            // error
-                            switch (buf[3]) {
-                                case 0:
-                                    throw "no such store";
-                                case 1:
-                                    throw "access denied";
-                                case 2:
-                                    const err = new TextDecoder().decode(buf.subarray(5));
-                                    throw err;
-                            }
-                        default:
-                            throw "invalid result status byte"
-                    }
-                }
-                return rx.read().then(handleChunk);
-            }, err => {
-                throw 'failed to read `bucket.get` response: ' + err;
-            })
-        }
-
-        async function wasiKeyvalueStoreBucketSet(tx, rx, bucket, key, value) {
-            const text = new TextEncoder();
-
-            if (bucket.length > 127) throw 'this example currently does not support buckets longer than 127 bytes - open a PR!';
-            if (value.length > 127) throw 'this example currently does not support values longer than 127 bytes - open a PR!';
-
-            const keyBuf = text.encode(key);
-            if (keyBuf.length > 127) throw 'this example currently does not support keys longer than 127 bytes - open a PR!';
-
-            const payloadBytes = 3 + bucket.length + keyBuf.length + value.length;
-            if (payloadBytes > 127) throw 'this example currently does not support request payloads longer than 127 bytes - open a PR!';
-
-            let buf = new Uint8Array([
-                0,
-                'wasi:keyvalue/store@0.2.0-draft2'.length,
-                ...text.encode('wasi:keyvalue/store@0.2.0-draft2'),
-                'bucket.set'.length,
-                ...text.encode('bucket.set'),
-                0,
-                payloadBytes,
-                bucket.length,
-                ...bucket,
-                keyBuf.length,
-                ...keyBuf,
-                value.length,
-                ...value
-            ]);
-
-            dbg.debug('writing `bucket.set("' + bucket + '", "' + key + '", "' + value + '") invocation: ' + toHex(buf));
-            await tx.write(buf);
-
-            dbg.debug('awaiting write to complete');
-            await tx.ready;
-            tx.close();
-
-            dbg.debug('reading `bucket.set` response...');
-            buf = null;
-            await rx.read().then(function handleChunk({done, value}) {
-                if (!buf) {
-                    buf = value;
-                } else if (value) {
-                    const b = new Uint8Array(buf.length + value.length);
-                    b.set(buf);
-                    b.set(value, buf.length);
-                    buf = b;
-                }
-                if (done) {
-                    if (!buf || buf.length < 3) throw 'unexpected EOF';
-                    dbg.debug('received `bucket.set` response: ' + toHex(buf));
-                    if (buf[0] != 0) throw 'unexpected path'
-                    if (buf[1] > 127) throw 'only decoding responses of up to 127 bytes is currently supported - open a PR!'
-                    switch (buf[2]) {
-                        case 0:
-                            // ok
-                            if (buf.length != 3) throw "unparsed bytes left on stream";
-                            return
-                        case 1:
-                            if (buf.length < 4) throw 'unexpected EOF';
-                            // error
-                            switch (buf[3]) {
-                                case 0:
-                                    throw "no such store";
-                                case 1:
-                                    throw "access denied";
-                                case 2:
-                                    const err = new TextDecoder().decode(buf.subarray(5));
-                                    throw err;
-                            }
-                        default:
-                            throw "invalid result status byte"
-                    }
-                }
-                rx.read().then(handleChunk);
-            }, err => {
-                throw 'failed to read `bucket.set` response: ' + err;
-            })
-        }
-
         async function getBucket() {
             if (!conn) throw 'WebTransport not connected';
 
@@ -328,25 +141,16 @@
                 throw 'selected wRPC transport not supported yet';
             }
 
-            if (identifier.length > 127) throw 'this example currently does not support identifiers longer than 127 bytes - open a PR!';
-
-            const bucket = buckets.get(identifier);
-            if (bucket) return bucket;
+            const existing = buckets.get(identifier);
+            if (existing) return existing;
 
-            dbg.debug('creating `open` stream...');
-            const stream = await conn.createBidirectionalStream();
-            return await wasiKeyvalueStoreOpen(
-                stream.writable.getWriter(),
-                stream.readable.getReader(),
-                identifier,
-            ).then(bucket => {
-                const bucketName = uuidString(bucket);
-                dbg.log(`opened bucket ${bucketName}`);
-                buckets.set(identifier, bucket);
-                return bucket;
-            }, err => {
-                throw 'failed to open bucket: ' + err;
-            });
+            dbg.debug(`opening bucket for \`${identifier}\`...`);
+            const [res] = await invoke(STORE, 'open', OPEN.params, OPEN.results, [identifier]);
+            if (res.tag === 'err') throw 'failed to open bucket: ' + formatError(res.val);
+            const bucket = res.val;
+            buckets.set(identifier, bucket);
+            dbg.log(`opened bucket ${uuidString(bucket)}`);
+            return bucket;
         }
 
         async function handleGet() {
@@ -354,73 +158,38 @@
             const getValue = document.querySelector('#get input[name="get-value"]');
             if (getValue) getValue.value = null;
 
-            if (!conn) throw 'WebTransport not connected';
-
             const bucket = await getBucket();
-            if (!bucket) throw 'failed to get bucket';
 
             const obj = getFormValues('#get');
-
             const key = obj['get-key'];
             if (!key) throw 'key must be set';
-            if (key.length > 127) throw 'this example currently does not support keys longer than 127 bytes - open a PR!';
 
-            dbg.debug('creating `get` stream...');
-            const stream = await conn.createBidirectionalStream();
-            await wasiKeyvalueStoreBucketGet(
-                stream.writable.getWriter(),
-                stream.readable.getReader(),
-                bucket,
-                key,
-            ).then(value => {
-                if (!value) {
-                    dbg.info('key missing')
-                    return;
-                }
-                const s = new TextDecoder().decode(value);
-                const bucketName = uuidString(bucket);
-                dbg.info(`got value from bucket ${bucketName}:`, JSON.stringify(s, null, 2));
-                if (getValue) getValue.value = s;
-            }, err => {
-                throw 'failed to get value: ' + err;
-            });
+            dbg.debug(`getting \`${key}\`...`);
+            const [res] = await invoke(STORE, 'bucket.get', GET.params, GET.results, [bucket, key]);
+            if (res.tag === 'err') throw 'failed to get value: ' + formatError(res.val);
+            if (res.val === undefined) {
+                dbg.info('key missing');
+                return;
+            }
+            const s = new TextDecoder().decode(res.val);
+            dbg.info(`got value from bucket ${uuidString(bucket)}:`, JSON.stringify(s, null, 2));
+            if (getValue) getValue.value = s;
         }
 
         async function handleSet() {
-            if (!conn) throw 'WebTransport not connected';
-
             const bucket = await getBucket();
-            if (!bucket) throw 'failed to get bucket';
 
             const obj = getFormValues('#set');
-
             const key = obj['set-key'];
             if (!key) throw 'key must be set';
-            if (key.length > 127) throw 'this example currently does not support keys longer than 127 bytes - open a PR!';
 
             const value = obj['set-value'];
-            let valueBuf;
-            if (value) {
-                valueBuf = new TextEncoder().encode(value);
-            } else {
-                valueBuf = new Uint8Array();
-            }
-            if (valueBuf.length > 127) throw 'this example currently does not support values longer than 127 bytes - open a PR!';
+            const valueBuf = value ? new TextEncoder().encode(value) : new Uint8Array();
 
-            dbg.debug('creating `set` stream...');
-            const stream = await conn.createBidirectionalStream();
-            await wasiKeyvalueStoreBucketSet(
-                stream.writable.getWriter(),
-                stream.readable.getReader(),
-                bucket,
-                key,
-                valueBuf,
-            ).then(() => {
-                const bucketName = uuidString(bucket);
-                dbg.info(`set value in bucket ${bucketName}`);
-            }, err => {
-                throw 'failed to set value: ' + err
-            });
+            dbg.debug(`setting \`${key}\`...`);
+            const [res] = await invoke(STORE, 'bucket.set', SET.params, SET.results, [bucket, key, valueBuf]);
+            if (res.tag === 'err') throw 'failed to set value: ' + formatError(res.val);
+            dbg.info(`set value in bucket ${uuidString(bucket)}`);
         }
 
         const dbg = (() => {
diff --git a/js/.gitignore b/js/.gitignore
new file mode 100644
index 000000000..2d98f97ce
--- /dev/null
+++ b/js/.gitignore
@@ -0,0 +1,2 @@
+node_modules/
+*.tgz
diff --git a/js/README.md b/js/README.md
new file mode 100644
index 000000000..85a808a02
--- /dev/null
+++ b/js/README.md
@@ -0,0 +1,145 @@
+# `@bytecodealliance/wrpc`
+
+A [wRPC](https://github.com/bytecodealliance/wrpc) client for JavaScript: a
+transport-agnostic, component-native implementation of the wRPC wire format and
+its mandatory framing. It encodes and decodes [component model] values against a
+WIT type tree and invokes (or serves) functions over a single bidirectional
+byte stream, multiplexing each invocation's synchronous and **asynchronous**
+(`stream` / `future`) parameters and results — leaving the byte transport
+(WebTransport, WebSocket, a `MessagePort`, …) up to you.
+
+It is dependency-free and ships as standard ES modules, so it runs directly in
+the browser (`<script type="module">`) as well as through a bundler or Node.
+
+[component model]: https://component-model.bytecodealliance.org
+
+## Install
+
+```sh
+npm install @bytecodealliance/wrpc
+```
+
+## Quick start
+
+Describe the function's parameter and result types with the `t` (types)
+builders, then `invoke` it over a transport. A transport is any duplex of byte
+chunks; `fromWebStreams` adapts a WHATWG `{ readable, writable }` pair, such as
+a WebTransport bidirectional stream:
+
+```js
+import { t, invoke, fromWebStreams } from "@bytecodealliance/wrpc";
+
+const store = "wasi:keyvalue/store@0.2.0-draft2";
+const error = t.variant({ "no-such-store": null, "access-denied": null, other: t.string });
+
+// open: func(identifier: string) -> result<bucket, error>
+const transport = fromWebStreams(await conn.createBidirectionalStream());
+const { results, done } = await invoke(
+  transport,
+  store,
+  "open",
+  [t.string],
+  [""],
+  [t.result(t.own("bucket"), error)],
+);
+
+const [opened] = results;
+if (opened.tag === "err") throw opened.val;
+const bucket = opened.val; // a Uint8Array handle
+await done; // all asynchronous I/O has completed
+```
+
+`invoke` runs the framing (a single connection per invocation, the protocol
+byte and instance/function names, then the root parameter and result frames)
+and resolves with the decoded `results` as soon as the synchronous reply
+arrives. `stream` results are async iterables of chunks and `future` results
+are promises — both fed as their data arrives over the multiplexed
+sub-streams — and `done` resolves once every asynchronous parameter and result
+has been transmitted.
+
+### Streams and futures
+
+`t.stream(elem)` and `t.future(some)` describe asynchronous values. A `stream`
+parameter is given as an (async-)iterable of chunks (a `Uint8Array` for
+`stream<u8>`, an array of elements otherwise); a `future` as a value, a promise,
+or a thunk. Decoded `stream` results are async iterables of chunks and `future`
+results are promises:
+
+```js
+import { t, invoke, fromWebStreams } from "@bytecodealliance/wrpc";
+
+// echo: func(r: req) -> tuple<stream<u64>, stream<u8>>
+const req = t.record({ numbers: t.stream(t.u64), bytes: t.stream(t.u8) });
+const { results, done } = await invoke(
+  fromWebStreams(stream),
+  "wrpc-examples:streams/handler",
+  "echo",
+  [req],
+  [{ numbers: [[1n, 2n, 3n]], bytes: new Uint8Array([1, 2, 3]) }],
+  [t.tuple(t.stream(t.u64), t.stream(t.u8))],
+);
+
+const [numbers, bytes] = results[0];
+for await (const chunk of numbers) console.log(chunk); // [1n, 2n, 3n]
+for await (const chunk of bytes) console.log(chunk); // Uint8Array([1, 2, 3])
+await done;
+```
+
+### Serving
+
+`accept` is the server-side counterpart: read an invocation's header off a
+transport, decode its parameters, and send the results.
+
+```js
+import { t, accept } from "@bytecodealliance/wrpc";
+
+const inv = await accept(transport); // { instance, func, ... }
+const { params, done: rx } = await inv.receiveParams([t.string]);
+await Promise.all([rx, inv.sendResults([t.result(t.own("bucket"), error)], [{ tag: "ok", val: handle }])]);
+```
+
+## Value mapping
+
+Component-model values map to JavaScript following the same conventions as
+[`jco`](https://github.com/bytecodealliance/jco):
+
+| WIT                       | JavaScript                                   |
+| ------------------------- | -------------------------------------------- |
+| `bool`                    | `boolean`                                    |
+| `s8`–`s32`, `u8`–`u32`    | `number`                                     |
+| `s64`, `u64`              | `bigint`                                     |
+| `f32`, `f64`              | `number`                                     |
+| `char`, `string`          | `string`                                     |
+| `list<u8>`                | `Uint8Array`                                 |
+| `list<T>`                 | `Array`                                      |
+| `tuple<...>`              | `Array`                                      |
+| `record`                  | object keyed by field name                   |
+| `option<T>`               | `T \| undefined`                             |
+| `result<O, E>`            | `{ tag: "ok", val } \| { tag: "err", val }`  |
+| `variant`                 | `{ tag: caseName, val? }`                    |
+| `enum`                    | `string` (the case name)                     |
+| `flags`                   | `{ [name]: boolean }`                        |
+| `future<T>`               | `Promise<T>` (or, when sending, a thunk)     |
+| `stream<T>`               | async iterable of chunks (`Uint8Array` for `stream<u8>`) |
+| `own<R>` / `borrow<R>`    | `Uint8Array` (the opaque handle bytes)       |
+
+## API
+
+- `t` / `types` — type-tree builders (`bool`, `list`, `record`, `result`, `stream`, `future`, …).
+- `invoke(transport, instance, func, paramTypes, args, resultTypes?)` — invoke a function; resolves to `{ results, done }`.
+- `accept(transport)` — accept an invocation; resolves to `{ instance, func, receiveParams, sendResults, mux }`.
+- `fromWebStreams({ readable, writable })` — adapt a WHATWG stream duplex to a transport.
+- `encodeValue(writer, ty, value, sink?, path?)` / `decodeValue(reader, ty, sink?, path?)` — the low-level value codec.
+- `Mux` / `Outgoing` — the framing multiplexer, for custom session control.
+- `Writer` / `Reader` / `AsyncReader` / `Chan` — byte and async primitives.
+
+## Development
+
+```sh
+npm test       # codec / framing / session tests (node --test)
+npm run check  # type-check the sources and declarations (tsc)
+```
+
+## License
+
+Apache-2.0 WITH LLVM-exception
diff --git a/js/package-lock.json b/js/package-lock.json
new file mode 100644
index 000000000..5f47ea923
--- /dev/null
+++ b/js/package-lock.json
@@ -0,0 +1,33 @@
+{
+  "name": "@bytecodealliance/wrpc",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@bytecodealliance/wrpc",
+      "version": "0.1.0",
+      "license": "Apache-2.0 WITH LLVM-exception",
+      "devDependencies": {
+        "typescript": "^5.6.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    }
+  }
+}
diff --git a/js/package.json b/js/package.json
new file mode 100644
index 000000000..c0d7393a8
--- /dev/null
+++ b/js/package.json
@@ -0,0 +1,45 @@
+{
+  "name": "@bytecodealliance/wrpc",
+  "version": "0.1.0",
+  "description": "Transport-agnostic, component-native wRPC client for JavaScript",
+  "type": "module",
+  "license": "Apache-2.0 WITH LLVM-exception",
+  "homepage": "https://wrpc.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bytecodealliance/wrpc.git",
+    "directory": "js"
+  },
+  "keywords": [
+    "wrpc",
+    "wit",
+    "rpc",
+    "component-model",
+    "webassembly",
+    "wasm"
+  ],
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test",
+    "check": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
diff --git a/js/src/index.d.ts b/js/src/index.d.ts
new file mode 100644
index 000000000..44a69154f
--- /dev/null
+++ b/js/src/index.d.ts
@@ -0,0 +1,188 @@
+// Type definitions for the `wrpc` package.
+
+/** A structural wRPC/WIT type. */
+export type Type =
+  | { kind: "bool" | "s8" | "u8" | "s16" | "u16" | "s32" | "u32" | "s64" | "u64" | "f32" | "f64" | "char" | "string" }
+  | { kind: "list"; elem: Type }
+  | { kind: "option"; some: Type }
+  | { kind: "result"; ok: Type | null; err: Type | null }
+  | { kind: "tuple"; elems: Type[] }
+  | { kind: "record"; fields: { name: string; ty: Type }[] }
+  | { kind: "variant"; cases: { name: string; ty: Type | null }[] }
+  | { kind: "enum"; names: string[] }
+  | { kind: "flags"; names: string[] }
+  | { kind: "future"; some: Type }
+  | { kind: "stream"; elem: Type }
+  | { kind: "own" | "borrow"; name: string };
+
+/** The JavaScript representation of a decoded component-model value. */
+export type Value =
+  | boolean
+  | number
+  | bigint
+  | string
+  | Uint8Array
+  | Value[]
+  | { [field: string]: Value }
+  | { tag: string; val?: Value }
+  | Promise<Value>
+  | AsyncIterable<Value[] | Uint8Array>
+  | undefined;
+
+/**
+ * A descriptor recorded by {@link decodeValue} for a pending `stream`/`future`
+ * value, naming the relative sub-stream `path` and the placeholder to feed.
+ */
+export type DecodeDeferred =
+  | { path: number[]; kind: "future"; ty: Type; resolve: (value: Value) => void }
+  | { path: number[]; kind: "stream"; ty: Type; queue: Chan<Value[] | Uint8Array> };
+
+// ----- types.js -------------------------------------------------------------
+
+export namespace types {
+  export const bool: Type;
+  export const s8: Type;
+  export const u8: Type;
+  export const s16: Type;
+  export const u16: Type;
+  export const s32: Type;
+  export const u32: Type;
+  export const s64: Type;
+  export const u64: Type;
+  export const f32: Type;
+  export const f64: Type;
+  export const char: Type;
+  export const string: Type;
+  export function list(elem: Type): Type;
+  export function option(some: Type): Type;
+  export function future(some: Type): Type;
+  export function stream(elem: Type): Type;
+  export function result(ok?: Type | null, err?: Type | null): Type;
+  export function tuple(...elems: Type[]): Type;
+  export function record(fields: Record<string, Type> | { name: string; ty: Type }[]): Type;
+  export function variant(cases: Record<string, Type | null> | { name: string; ty: Type | null }[]): Type;
+  function enumType(names: string[]): Type;
+  export { enumType as enum };
+  export function flags(names: string[]): Type;
+  export function own(name: string): Type;
+  export function borrow(name: string): Type;
+}
+
+export { types as t };
+
+// ----- io.js ----------------------------------------------------------------
+
+export class Writer {
+  constructor();
+  u8(b: number): void;
+  bytes(bytes: Uint8Array | number[]): void;
+  varU(value: number | bigint): void;
+  varS(value: number | bigint): void;
+  name(str: string): void;
+  finish(): Uint8Array;
+}
+
+export class Reader {
+  constructor(bytes: Uint8Array);
+  readonly done: boolean;
+  bytes: Uint8Array;
+  pos: number;
+  u8(): number;
+  peek(): number;
+  take(n: number): Uint8Array;
+  varU(): bigint;
+  varS(): bigint;
+  name(): string;
+}
+
+/** An unbounded async FIFO queue. */
+export class Chan<T> implements AsyncIterable<T> {
+  constructor();
+  push(value: T): void;
+  close(err?: unknown): void;
+  next(): Promise<{ value: T | undefined; done: boolean }>;
+  [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+
+/** A pull-based async byte reader that buffers across chunk boundaries. */
+export class AsyncReader {
+  constructor(pull: () => Promise<Uint8Array | null | undefined>);
+  remaining(): Uint8Array;
+  consume(n: number): void;
+  more(): Promise<boolean>;
+  u8(): Promise<number>;
+  take(n: number): Promise<Uint8Array>;
+  varU(): Promise<bigint>;
+  name(): Promise<string>;
+}
+
+// ----- value.js -------------------------------------------------------------
+//
+// The low-level value codec. `stream`/`future` values require the session's
+// `sink` (collected by `invoke`/`accept`); without it they throw.
+
+export function encodeValue(
+  w: Writer,
+  ty: Type,
+  v: Value,
+  sink?: { path: number[]; kind: "stream" | "future"; ty: Type; value: Value }[],
+  path?: number[],
+): void;
+export function decodeValue(r: Reader, ty: Type, sink?: DecodeDeferred[], path?: number[]): Value;
+
+// ----- mux.js ---------------------------------------------------------------
+
+/** The wRPC framing protocol version byte. */
+export const PROTOCOL: number;
+
+/** A byte-stream transport: a duplex of `Uint8Array` chunks. */
+export interface Transport {
+  read(): Promise<Uint8Array | null | undefined>;
+  write(bytes: Uint8Array): Promise<void> | void;
+  closeWrite?(): Promise<void> | void;
+}
+
+export function fromWebStreams(duplex: {
+  readable: ReadableStream<Uint8Array>;
+  writable: WritableStream<Uint8Array>;
+}): Transport;
+
+/** A handle to one (sub-)stream of the connection's write side. */
+export class Outgoing {
+  constructor(mux: Mux, path: number[]);
+  path: number[];
+  write(data: Uint8Array): Promise<void>;
+  index(rel: number[]): Outgoing;
+}
+
+/** The framing multiplexer over a {@link Transport}. */
+export class Mux {
+  constructor(transport: Transport);
+  master: AsyncReader;
+  writeHeader(instance: string, func: string): Promise<void>;
+  start(): void;
+  incoming(path: number[]): AsyncReader;
+  outgoing(path: number[]): Outgoing;
+  closeWrite(): Promise<void>;
+}
+
+// ----- session.js -----------------------------------------------------------
+
+export function invoke(
+  transport: Transport,
+  instance: string,
+  func: string,
+  paramTypes: Type[],
+  args: Value[],
+  resultTypes?: Type[],
+): Promise<{ results: Value[]; done: Promise<void> }>;
+
+export interface Invocation {
+  instance: string;
+  func: string;
+  mux: Mux;
+  receiveParams(paramTypes: Type[]): Promise<{ params: Value[]; done: Promise<void> }>;
+  sendResults(resultTypes: Type[], values: Value[]): Promise<void>;
+}
+
+export function accept(transport: Transport): Promise<Invocation>;
diff --git a/js/src/index.js b/js/src/index.js
new file mode 100644
index 000000000..9ab1e7a27
--- /dev/null
+++ b/js/src/index.js
@@ -0,0 +1,15 @@
+// The wRPC client for JavaScript: a transport-agnostic, component-native RPC
+// implementation of the wRPC wire format and its mandatory framing.
+//
+// `types` (re-exported as `t`) builds the structural type tree; `value`
+// encodes/decodes component-model values; `mux` implements the framing over a
+// transport; and `session` invokes and serves functions with full
+// `stream`/`future` support. `invoke` and `accept` are the entry points.
+
+export * as t from "./types.js";
+export * as types from "./types.js";
+
+export { Reader, Writer, AsyncReader, Chan } from "./io.js";
+export { encodeValue, decodeValue } from "./value.js";
+export { Mux, Outgoing, PROTOCOL, fromWebStreams } from "./mux.js";
+export { invoke, accept } from "./session.js";
diff --git a/js/src/io.js b/js/src/io.js
new file mode 100644
index 000000000..22dc123bc
--- /dev/null
+++ b/js/src/io.js
@@ -0,0 +1,315 @@
+// Byte-stream reader and writer with the integer and string codecs the wRPC
+// wire format is built from: LEB128 integers and `core:name` length-prefixed
+// UTF-8 strings. See the wRPC `SPEC.md` and the component model value
+// definition encoding.
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/** A growable little-endian byte writer. */
+export class Writer {
+  constructor() {
+    this.buf = new Uint8Array(64);
+    this.len = 0;
+  }
+
+  /** @param {number} extra number of additional bytes that must fit */
+  #reserve(extra) {
+    const need = this.len + extra;
+    if (need <= this.buf.length) return;
+    let cap = this.buf.length * 2;
+    while (cap < need) cap *= 2;
+    const grown = new Uint8Array(cap);
+    grown.set(this.buf.subarray(0, this.len));
+    this.buf = grown;
+  }
+
+  /** Write a single byte. @param {number} b */
+  u8(b) {
+    this.#reserve(1);
+    this.buf[this.len++] = b & 0xff;
+  }
+
+  /** Write raw bytes. @param {Uint8Array | number[]} bytes */
+  bytes(bytes) {
+    this.#reserve(bytes.length);
+    this.buf.set(bytes, this.len);
+    this.len += bytes.length;
+  }
+
+  /**
+   * Write an unsigned LEB128 integer.
+   * @param {number | bigint} value non-negative integer
+   */
+  varU(value) {
+    let v = BigInt(value);
+    if (v < 0n) throw new RangeError(`expected a non-negative integer, got ${v}`);
+    do {
+      let byte = Number(v & 0x7fn);
+      v >>= 7n;
+      if (v !== 0n) byte |= 0x80;
+      this.u8(byte);
+    } while (v !== 0n);
+  }
+
+  /**
+   * Write a signed LEB128 integer.
+   * @param {number | bigint} value
+   */
+  varS(value) {
+    let v = BigInt(value);
+    for (;;) {
+      const byte = Number(v & 0x7fn);
+      v >>= 7n; // BigInt `>>` is an arithmetic (sign-extending) shift
+      const signBit = byte & 0x40;
+      if ((v === 0n && !signBit) || (v === -1n && signBit)) {
+        this.u8(byte);
+        return;
+      }
+      this.u8(byte | 0x80);
+    }
+  }
+
+  /**
+   * Write a `core:name`: an unsigned LEB128 length prefix followed by the
+   * UTF-8 bytes.
+   * @param {string} str
+   */
+  name(str) {
+    const utf8 = textEncoder.encode(str);
+    this.varU(utf8.length);
+    this.bytes(utf8);
+  }
+
+  /** @returns {Uint8Array} a copy of the written bytes */
+  finish() {
+    return this.buf.slice(0, this.len);
+  }
+}
+
+/** A cursor over a byte buffer with the matching decoders. */
+export class Reader {
+  /** @param {Uint8Array} bytes */
+  constructor(bytes) {
+    this.bytes = bytes;
+    this.pos = 0;
+  }
+
+  /** @returns {boolean} whether the cursor is at the end of the buffer */
+  get done() {
+    return this.pos >= this.bytes.length;
+  }
+
+  /** Read a single byte. @returns {number} */
+  u8() {
+    if (this.pos >= this.bytes.length) throw new RangeError("unexpected end of input");
+    return this.bytes[this.pos++];
+  }
+
+  /** Read the next byte without consuming it. @returns {number} */
+  peek() {
+    if (this.pos >= this.bytes.length) throw new RangeError("unexpected end of input");
+    return this.bytes[this.pos];
+  }
+
+  /** Read `n` raw bytes. @param {number} n @returns {Uint8Array} */
+  take(n) {
+    if (this.pos + n > this.bytes.length) throw new RangeError("unexpected end of input");
+    const slice = this.bytes.subarray(this.pos, this.pos + n);
+    this.pos += n;
+    return slice;
+  }
+
+  /** Read an unsigned LEB128 integer. @returns {bigint} */
+  varU() {
+    let result = 0n;
+    let shift = 0n;
+    let byte;
+    do {
+      byte = this.u8();
+      result |= BigInt(byte & 0x7f) << shift;
+      shift += 7n;
+    } while (byte & 0x80);
+    return result;
+  }
+
+  /** Read a signed LEB128 integer. @returns {bigint} */
+  varS() {
+    let result = 0n;
+    let shift = 0n;
+    let byte;
+    do {
+      byte = this.u8();
+      result |= BigInt(byte & 0x7f) << shift;
+      shift += 7n;
+    } while (byte & 0x80);
+    if (byte & 0x40) result |= -1n << shift; // sign-extend
+    return result;
+  }
+
+  /** Read a `core:name`. @returns {string} */
+  name() {
+    const len = Number(this.varU());
+    return textDecoder.decode(this.take(len));
+  }
+}
+
+/** The message thrown by readers when the input is exhausted mid-value. */
+export const UNEXPECTED_EOF = "unexpected end of input";
+
+/** @param {unknown} err @returns {boolean} whether `err` is an end-of-input underflow */
+export function isUnexpectedEof(err) {
+  return err instanceof RangeError && err.message.startsWith(UNEXPECTED_EOF);
+}
+
+/**
+ * An unbounded async FIFO queue. Producers `push` values (or `close` the
+ * queue); consumers `await next()` or iterate it with `for await`. Once
+ * closed, pending and subsequent `next()` calls resolve to `{ done: true }`,
+ * or reject with the error passed to `close` if the channel was failed.
+ *
+ * @template T
+ */
+export class Chan {
+  constructor() {
+    /** @type {T[]} */
+    this.queue = [];
+    /** @type {{ resolve: (r: { value: T | undefined, done: boolean }) => void, reject: (e: unknown) => void }[]} */
+    this.waiters = [];
+    this.closed = false;
+    /** @type {unknown} */
+    this.error = undefined;
+  }
+
+  /** Push a value. Ignored once the channel is closed. @param {T} value */
+  push(value) {
+    if (this.closed) return;
+    const w = this.waiters.shift();
+    if (w) w.resolve({ value, done: false });
+    else this.queue.push(value);
+  }
+
+  /**
+   * Close the channel, releasing every pending and future `next()`. When `err`
+   * is given the channel is failed: once buffered values are drained, `next()`
+   * rejects with `err` instead of signalling a clean end.
+   * @param {unknown} [err]
+   */
+  close(err) {
+    if (this.closed) return;
+    this.closed = true;
+    this.error = err;
+    let w;
+    while ((w = this.waiters.shift())) {
+      if (err !== undefined) w.reject(err);
+      else w.resolve({ value: undefined, done: true });
+    }
+  }
+
+  /** @returns {Promise<{ value: T | undefined, done: boolean }>} */
+  next() {
+    if (this.queue.length) return Promise.resolve({ value: this.queue.shift(), done: false });
+    if (this.closed) {
+      return this.error !== undefined
+        ? Promise.reject(this.error)
+        : Promise.resolve({ value: undefined, done: true });
+    }
+    return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+  }
+
+  [Symbol.asyncIterator]() {
+    return { next: () => this.next() };
+  }
+}
+
+/**
+ * A pull-based async byte reader with the same integer/`core:name` decoders as
+ * {@link Reader}, but able to await more input across chunk boundaries. It is
+ * driven by a `pull` function returning the next chunk (or `null`/`undefined`
+ * at end of input), and buffers any leftover bytes between reads.
+ */
+export class AsyncReader {
+  /** @param {() => Promise<Uint8Array | null | undefined>} pull */
+  constructor(pull) {
+    this.pull = pull;
+    /** @type {Uint8Array} */
+    this.buf = new Uint8Array(0);
+    this.pos = 0;
+    this.eof = false;
+  }
+
+  /** The bytes buffered but not yet consumed. @returns {Uint8Array} */
+  remaining() {
+    return this.buf.subarray(this.pos);
+  }
+
+  /** Mark `n` buffered bytes as consumed. @param {number} n */
+  consume(n) {
+    this.pos += n;
+  }
+
+  /**
+   * Pull one more chunk into the buffer.
+   * @returns {Promise<boolean>} `false` once the input is exhausted
+   */
+  async more() {
+    if (this.eof) return false;
+    const chunk = await this.pull();
+    if (chunk === null || chunk === undefined) {
+      this.eof = true;
+      return false;
+    }
+    if (chunk.length === 0) return this.more();
+    const rem = this.remaining();
+    if (rem.length === 0) {
+      this.buf = chunk;
+      this.pos = 0;
+    } else {
+      const merged = new Uint8Array(rem.length + chunk.length);
+      merged.set(rem, 0);
+      merged.set(chunk, rem.length);
+      this.buf = merged;
+      this.pos = 0;
+    }
+    return true;
+  }
+
+  /** Read a single byte, awaiting input if needed. @returns {Promise<number>} */
+  async u8() {
+    while (this.pos >= this.buf.length) {
+      if (!(await this.more())) throw new RangeError(UNEXPECTED_EOF);
+    }
+    return this.buf[this.pos++];
+  }
+
+  /** Read `n` bytes, awaiting input if needed. @param {number} n @returns {Promise<Uint8Array>} */
+  async take(n) {
+    while (this.buf.length - this.pos < n) {
+      if (!(await this.more())) throw new RangeError(UNEXPECTED_EOF);
+    }
+    const slice = this.buf.slice(this.pos, this.pos + n);
+    this.pos += n;
+    return slice;
+  }
+
+  /** Read an unsigned LEB128 integer. @returns {Promise<bigint>} */
+  async varU() {
+    let result = 0n;
+    let shift = 0n;
+    let byte;
+    do {
+      byte = await this.u8();
+      result |= BigInt(byte & 0x7f) << shift;
+      shift += 7n;
+    } while (byte & 0x80);
+    return result;
+  }
+
+  /** Read a `core:name`. @returns {Promise<string>} */
+  async name() {
+    const len = Number(await this.varU());
+    return textDecoder.decode(await this.take(len));
+  }
+}
+
+export { textEncoder, textDecoder };
diff --git a/js/src/mux.js b/js/src/mux.js
new file mode 100644
index 000000000..1815e16ef
--- /dev/null
+++ b/js/src/mux.js
@@ -0,0 +1,200 @@
+// The framing multiplexer: the layer that turns a transport's single
+// bidirectional byte stream into the indexed sub-streams an invocation needs.
+//
+// Every wRPC transport (TCP, Unix, QUIC, WebTransport, WebSocket, …) provides
+// one bidirectional byte stream per invocation; this module implements the
+// mandatory wRPC framing on top of it (see `SPEC.md`, "Framed stream
+// specification"). Outgoing data is written as frames `[path][data]`, where
+// `path` is a `list<u32>` index identifying the (sub-)stream; incoming frames
+// are demultiplexed back to the reader registered for their path.
+
+import { AsyncReader, Chan, Writer } from "./io.js";
+
+/** The wRPC framing protocol version byte. */
+export const PROTOCOL = 0x00;
+
+/** @param {number[]} path */
+const key = (path) => path.join(",");
+
+/**
+ * A byte-stream transport: a duplex of `Uint8Array` chunks.
+ * @typedef {object} Transport
+ * @property {() => Promise<Uint8Array | null | undefined>} read next inbound chunk, `null` at EOF
+ * @property {(bytes: Uint8Array) => Promise<void> | void} write send an outbound chunk
+ * @property {() => Promise<void> | void} [closeWrite] half-close the write side
+ */
+
+/**
+ * Adapt a WHATWG stream duplex (as provided by a WebTransport bidirectional
+ * stream, or built over a WebSocket / `MessagePort`) to a {@link Transport}.
+ * @param {{ readable: ReadableStream<Uint8Array>, writable: WritableStream<Uint8Array> }} duplex
+ * @returns {Transport}
+ */
+export function fromWebStreams({ readable, writable }) {
+  const reader = readable.getReader();
+  const writer = writable.getWriter();
+  return {
+    read: async () => {
+      const { value, done } = await reader.read();
+      return done ? null : value;
+    },
+    write: (bytes) => writer.write(bytes),
+    closeWrite: () => writer.close(),
+  };
+}
+
+/**
+ * A handle to one (sub-)stream of the multiplexed connection's write side.
+ * `write` emits one frame; `index` descends to a nested sub-stream.
+ */
+export class Outgoing {
+  /** @param {Mux} mux @param {number[]} path */
+  constructor(mux, path) {
+    this.mux = mux;
+    this.path = path;
+  }
+
+  /** @param {Uint8Array} data @returns {Promise<void>} */
+  write(data) {
+    return this.mux._writeFrame(this.path, data);
+  }
+
+  /** @param {number[]} rel @returns {Outgoing} */
+  index(rel) {
+    return new Outgoing(this.mux, [...this.path, ...rel]);
+  }
+}
+
+/**
+ * The framing multiplexer over a {@link Transport}. Construct one per
+ * invocation, optionally read the header off `master`, then call `start()` to
+ * begin demultiplexing inbound frames.
+ */
+export class Mux {
+  /** @param {Transport} transport */
+  constructor(transport) {
+    this.transport = transport;
+    /** Reader over the raw inbound byte stream (header, then frames). */
+    this.master = new AsyncReader(() => transport.read());
+    /** @type {Map<string, Chan<Uint8Array>>} */
+    this.channels = new Map();
+    /** @type {Map<string, Uint8Array[]>} buffered frames awaiting a reader */
+    this.buffered = new Map();
+    /** Serializes outbound writes so each frame is emitted atomically. */
+    this.writeChain = Promise.resolve();
+    this.inboundClosed = false;
+    /** @type {Promise<void> | undefined} */
+    this.ingress = undefined;
+  }
+
+  /** Write the invocation header: the protocol byte and instance/function names.
+   * @param {string} instance @param {string} func @returns {Promise<void>} */
+  writeHeader(instance, func) {
+    const w = new Writer();
+    w.u8(PROTOCOL);
+    w.name(instance);
+    w.name(func);
+    return this._write(w.finish());
+  }
+
+  /** Begin reading and routing inbound frames off `master`. */
+  start() {
+    if (this.ingress) return;
+    this.ingress = this._ingress().catch((err) => {
+      this._closeInbound(err);
+    });
+  }
+
+  async _ingress() {
+    const m = this.master;
+    for (;;) {
+      // Stop cleanly at a frame boundary once the peer closes the stream.
+      if (m.remaining().length === 0 && !(await m.more())) break;
+      const depth = Number(await m.varU());
+      const path = new Array(depth);
+      for (let i = 0; i < depth; i++) path[i] = Number(await m.varU());
+      const len = Number(await m.varU());
+      const data = await m.take(len);
+      this._route(path, data);
+    }
+    this._closeInbound();
+  }
+
+  /** @param {number[]} path @param {Uint8Array} data */
+  _route(path, data) {
+    const k = key(path);
+    const chan = this.channels.get(k);
+    if (chan) {
+      chan.push(data);
+      return;
+    }
+    const pending = this.buffered.get(k);
+    if (pending) pending.push(data);
+    else this.buffered.set(k, [data]);
+  }
+
+  /** @param {Error} [err] */
+  _closeInbound(err) {
+    this.inboundClosed = true;
+    this.inboundError = err;
+    for (const chan of this.channels.values()) chan.close(err);
+  }
+
+  /**
+   * The reader for the sub-stream addressed by `path` (the root channel is
+   * `[]`). Any frames that arrived before the call are replayed in order.
+   * @param {number[]} path
+   * @returns {AsyncReader}
+   */
+  incoming(path) {
+    const k = key(path);
+    let chan = this.channels.get(k);
+    if (!chan) {
+      chan = new Chan();
+      const pending = this.buffered.get(k);
+      if (pending) {
+        for (const data of pending) chan.push(data);
+        this.buffered.delete(k);
+      }
+      if (this.inboundClosed) chan.close(this.inboundError);
+      this.channels.set(k, chan);
+    }
+    const reader = new AsyncReader(async () => {
+      const { value, done } = await chan.next();
+      return done ? null : value;
+    });
+    // Allow the value codec to descend into nested sub-streams.
+    /** @param {number[]} rel */
+    const index = (rel) => this.incoming([...path, ...rel]);
+    /** @type {any} */ (reader).index = index;
+    return reader;
+  }
+
+  /** The writer for the sub-stream addressed by `path` (root is `[]`).
+   * @param {number[]} path @returns {Outgoing} */
+  outgoing(path) {
+    return new Outgoing(this, path);
+  }
+
+  /** @param {number[]} path @param {Uint8Array} data */
+  _writeFrame(path, data) {
+    const w = new Writer();
+    w.varU(path.length);
+    for (const p of path) w.varU(p);
+    w.varU(data.length);
+    w.bytes(data);
+    return this._write(w.finish());
+  }
+
+  /** @param {Uint8Array} bytes */
+  _write(bytes) {
+    this.writeChain = this.writeChain.then(() => this.transport.write(bytes));
+    return this.writeChain;
+  }
+
+  /** Flush pending writes and half-close the write side. @returns {Promise<void>} */
+  async closeWrite() {
+    await this.writeChain;
+    if (this.transport.closeWrite) await this.transport.closeWrite();
+  }
+}
diff --git a/js/src/session.js b/js/src/session.js
new file mode 100644
index 000000000..283dc489b
--- /dev/null
+++ b/js/src/session.js
@@ -0,0 +1,323 @@
+// The asynchronous session layer: invoking a function and serving one over a
+// framed transport, with full support for `stream` and `future` parameters and
+// results.
+//
+// An invocation's synchronous values travel in the root frame (path `[]`);
+// each pending `stream`/`future` is transmitted concurrently over the framed
+// sub-stream addressed by its structural index path (see `SPEC.md`). The value
+// codec (`value.js`) writes a pending marker and records a descriptor for every
+// such value; the helpers below walk those descriptors, spawning a reader or
+// writer task per sub-stream.
+
+import { Reader, Writer, isUnexpectedEof } from "./io.js";
+import { Mux, PROTOCOL } from "./mux.js";
+import { decodeValue, encodeValue } from "./value.js";
+
+/** @typedef {import("./index.d.ts").Type} Type */
+/** @typedef {import("./mux.js").Transport} Transport */
+/** @typedef {import("./mux.js").Outgoing} Outgoing */
+
+// ----- encoding side --------------------------------------------------------
+
+/** Resolve a `future` value: a plain value, a thunk, or a promise.
+ * @param {any} v */
+async function resolveFuture(v) {
+  if (typeof v === "function") v = v();
+  return await v;
+}
+
+/**
+ * Yield the chunks of a `stream` source. A `stream<u8>` may be given as a
+ * single `Uint8Array`; otherwise the source is any (async-)iterable of chunks
+ * (arrays of elements, or `Uint8Array`s for `stream<u8>`).
+ * @param {any} src
+ * @param {Type} elem
+ */
+async function* streamChunks(src, elem) {
+  if (src === null || src === undefined) return;
+  if (elem.kind === "u8" && src instanceof Uint8Array) {
+    if (src.length) yield src;
+    return;
+  }
+  if (typeof src[Symbol.asyncIterator] === "function") {
+    for await (const chunk of src) yield chunk;
+    return;
+  }
+  if (typeof src[Symbol.iterator] === "function") {
+    for (const chunk of src) yield chunk;
+    return;
+  }
+  throw new TypeError("expected a `stream` source: an iterable or async-iterable of chunks");
+}
+
+/** @param {any} chunk @param {Type} elem @returns {any[]} */
+function chunkItems(chunk, elem) {
+  if (elem.kind === "u8") return Array.from(chunk);
+  if (!Array.isArray(chunk)) throw new TypeError("expected an array for a `stream` chunk");
+  return chunk;
+}
+
+/**
+ * Transmit one deferred value descriptor over `out`.
+ * @param {Outgoing} out
+ * @param {{ kind: "stream" | "future", ty: Type, value: any }} entry
+ */
+function writeDeferred(out, entry) {
+  return entry.kind === "future"
+    ? writeFuture(out, entry.ty, entry.value)
+    : writeStream(out, entry.ty, entry.value);
+}
+
+/** @param {Outgoing} out @param {Type} ty @param {any} value */
+async function writeFuture(out, ty, value) {
+  const v = await resolveFuture(value);
+  const w = new Writer();
+  /** @type {any[]} */
+  const sink = [];
+  encodeValue(w, ty, v, sink, []);
+  await out.write(w.finish());
+  await Promise.all(sink.map((e) => writeDeferred(out.index(e.path), e)));
+}
+
+/** @param {Outgoing} out @param {Type} elem @param {any} src */
+async function writeStream(out, elem, src) {
+  let base = 0;
+  /** @type {Promise<void>[]} */
+  const tasks = [];
+  for await (const chunk of streamChunks(src, elem)) {
+    const w = new Writer();
+    if (elem.kind === "u8") {
+      const bytes = chunk instanceof Uint8Array ? chunk : Uint8Array.from(chunk);
+      // An empty chunk is indistinguishable from the stream terminator.
+      if (bytes.length === 0) continue;
+      w.varU(bytes.length);
+      w.bytes(bytes);
+      base += bytes.length;
+    } else {
+      const items = chunkItems(chunk, elem);
+      if (items.length === 0) continue;
+      w.varU(items.length);
+      items.forEach((item, k) => {
+        /** @type {any[]} */
+        const sink = [];
+        encodeValue(w, elem, item, sink, []);
+        for (const e of sink) tasks.push(writeDeferred(out.index([base + k, ...e.path]), e));
+      });
+      base += items.length;
+    }
+    await out.write(w.finish());
+  }
+  const end = new Writer();
+  end.varU(0); // a stream is terminated by an empty chunk
+  await out.write(end.finish());
+  await Promise.all(tasks);
+}
+
+// ----- decoding side --------------------------------------------------------
+
+/**
+ * Decode one value of type `ty` from the async reader `ar`, pulling more input
+ * until a whole value is available. Returns the value and the descriptors of
+ * any pending `stream`/`future` values nested within it (with paths relative to
+ * the value).
+ * @param {import("./io.js").AsyncReader} ar
+ * @param {Type} ty
+ */
+async function decodeOne(ar, ty) {
+  for (;;) {
+    const r = new Reader(ar.remaining());
+    /** @type {any[]} */
+    const sink = [];
+    try {
+      const value = decodeValue(r, ty, sink, []);
+      ar.consume(r.pos);
+      return { value, sink };
+    } catch (err) {
+      if (isUnexpectedEof(err) && (await ar.more())) continue;
+      if (isUnexpectedEof(err)) {
+        throw new RangeError("unexpected end of input while decoding a value");
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Decode a tuple of `types` from the root channel reader, returning the decoded
+ * values and the absolute-path descriptors of pending sub-streams.
+ * @param {import("./io.js").AsyncReader} root
+ * @param {Type[]} types
+ */
+async function decodeTuple(root, types) {
+  const values = [];
+  /** @type {any[]} */
+  const sink = [];
+  for (let i = 0; i < types.length; i++) {
+    const { value, sink: nested } = await decodeOne(root, types[i]);
+    values.push(value);
+    for (const e of nested) sink.push({ ...e, path: [i, ...e.path] });
+  }
+  return { values, sink };
+}
+
+/**
+ * Receive one deferred value over `ar` and feed its placeholder.
+ * @param {any} ar
+ * @param {import("./index.d.ts").DecodeDeferred} entry
+ */
+async function readDeferred(ar, entry) {
+  if (entry.kind === "future") {
+    const { value, sink } = await decodeOne(ar, entry.ty);
+    entry.resolve(value);
+    await Promise.all(sink.map((e) => readDeferred(e.path.length ? ar.index(e.path) : ar, e)));
+    return;
+  }
+  await readStream(ar, entry.ty, entry.queue);
+}
+
+/** @param {any} ar @param {Type} elem @param {any} queue */
+async function readStream(ar, elem, queue) {
+  let base = 0;
+  /** @type {Promise<void>[]} */
+  const tasks = [];
+  try {
+    for (;;) {
+      let len;
+      try {
+        len = Number(await ar.varU());
+      } catch (err) {
+        // The peer closed the connection without an explicit empty terminator.
+        if (isUnexpectedEof(err)) break;
+        throw err;
+      }
+      if (len === 0) break;
+      if (elem.kind === "u8") {
+        queue.push(await ar.take(len));
+      } else {
+        const chunk = new Array(len);
+        for (let k = 0; k < len; k++) {
+          const { value, sink } = await decodeOne(ar, elem);
+          chunk[k] = value;
+          for (const e of sink) tasks.push(readDeferred(ar.index([base + k, ...e.path]), e));
+        }
+        queue.push(chunk);
+      }
+      base += len;
+    }
+  } catch (err) {
+    // Surface a transport/decode failure to whoever is consuming the stream,
+    // rather than leaving the consumer hanging on a queue that never closes.
+    queue.close(err);
+    throw err;
+  }
+  queue.close();
+  await Promise.all(tasks);
+}
+
+/**
+ * Run every pending sub-stream reader for a decoded tuple. Each descriptor's
+ * path is absolute (rooted at the root channel).
+ * @param {any} root
+ * @param {any[]} sink
+ */
+function runReadSink(root, sink) {
+  return Promise.all(sink.map((e) => readDeferred(root.index(e.path), e)));
+}
+
+// ----- public API -----------------------------------------------------------
+
+/**
+ * Invoke `func` on `instance` over `transport`, sending `args` (encoded against
+ * `paramTypes`) and decoding the reply against `resultTypes`.
+ *
+ * Returns the decoded `results` immediately once the synchronous reply frame
+ * arrives — `stream` results are async iterables of chunks and `future`
+ * results are promises, both fed as their data arrives — together with a
+ * `done` promise that resolves once all asynchronous I/O (parameters and
+ * results) has completed.
+ *
+ * @param {Transport} transport
+ * @param {string} instance
+ * @param {string} func
+ * @param {Type[]} paramTypes
+ * @param {any[]} args
+ * @param {Type[]} [resultTypes]
+ * @returns {Promise<{ results: any[], done: Promise<void> }>}
+ */
+export async function invoke(transport, instance, func, paramTypes, args, resultTypes = []) {
+  if (args.length !== paramTypes.length) {
+    throw new RangeError(`expected ${paramTypes.length} argument(s), got ${args.length}`);
+  }
+  const mux = new Mux(transport);
+  await mux.writeHeader(instance, func);
+  mux.start();
+
+  const w = new Writer();
+  /** @type {any[]} */
+  const psink = [];
+  paramTypes.forEach((ty, i) => encodeValue(w, ty, args[i], psink, [i]));
+  await mux.outgoing([]).write(w.finish());
+  const tx = Promise.all(psink.map((e) => writeDeferred(mux.outgoing(e.path), e))).then(() =>
+    mux.closeWrite(),
+  );
+
+  const root = mux.incoming([]);
+  const { values, sink } = await decodeTuple(root, resultTypes);
+  const rx = runReadSink(root, sink);
+
+  const done = Promise.all([tx, rx]).then(() => undefined);
+  // Avoid an unhandled rejection if the caller uses `results` without `done`.
+  done.catch(() => {});
+  return { results: values, done };
+}
+
+/**
+ * Accept a single invocation on `transport`: read its header and return a
+ * handle exposing the invoked `instance`/`func`, methods to receive the
+ * parameters and send the results, and the underlying multiplexer.
+ *
+ * @param {Transport} transport
+ */
+export async function accept(transport) {
+  const mux = new Mux(transport);
+  const version = await mux.master.u8();
+  if (version !== PROTOCOL) {
+    throw new Error(`unsupported wRPC framing version byte 0x${version.toString(16)}`);
+  }
+  const instance = await mux.master.name();
+  const func = await mux.master.name();
+  mux.start();
+  const root = mux.incoming([]);
+
+  return {
+    instance,
+    func,
+    mux,
+
+    /**
+     * Decode the invocation parameters against `paramTypes`. Returns the
+     * decoded `params` and a `done` promise for the parameters' async I/O.
+     * @param {Type[]} paramTypes
+     */
+    async receiveParams(paramTypes) {
+      const { values, sink } = await decodeTuple(root, paramTypes);
+      return { params: values, done: runReadSink(root, sink) };
+    },
+
+    /**
+     * Encode and send the invocation results, then half-close the write side.
+     * Resolves once all asynchronous result I/O has completed.
+     * @param {Type[]} resultTypes
+     * @param {any[]} values
+     */
+    async sendResults(resultTypes, values) {
+      const w = new Writer();
+      /** @type {any[]} */
+      const sink = [];
+      resultTypes.forEach((ty, i) => encodeValue(w, ty, values[i], sink, [i]));
+      await mux.outgoing([]).write(w.finish());
+      await Promise.all(sink.map((e) => writeDeferred(mux.outgoing(e.path), e)));
+      await mux.closeWrite();
+    },
+  };
+}
diff --git a/js/src/types.js b/js/src/types.js
new file mode 100644
index 000000000..61ee461ec
--- /dev/null
+++ b/js/src/types.js
@@ -0,0 +1,110 @@
+// Constructors for the type tree the value codec walks. A `Type` mirrors a WIT
+// type structurally:
+//
+//   { kind: "bool" | "s8" | "u8" | "s16" | "u16" | "s32" | "u32" | "s64"
+//          | "u64" | "f32" | "f64" | "char" | "string" }
+//   | { kind: "list", elem: Type }
+//   | { kind: "option", some: Type }
+//   | { kind: "result", ok: Type | null, err: Type | null }
+//   | { kind: "tuple", elems: Type[] }
+//   | { kind: "record", fields: { name: string, ty: Type }[] }
+//   | { kind: "variant", cases: { name: string, ty: Type | null }[] }
+//   | { kind: "enum", names: string[] }
+//   | { kind: "flags", names: string[] }
+//   | { kind: "own" | "borrow", name: string }
+//
+// This is the structural type tree the value codec and session walk.
+
+export const bool = { kind: "bool" };
+export const s8 = { kind: "s8" };
+export const u8 = { kind: "u8" };
+export const s16 = { kind: "s16" };
+export const u16 = { kind: "u16" };
+export const s32 = { kind: "s32" };
+export const u32 = { kind: "u32" };
+export const s64 = { kind: "s64" };
+export const u64 = { kind: "u64" };
+export const f32 = { kind: "f32" };
+export const f64 = { kind: "f64" };
+export const char = { kind: "char" };
+export const string = { kind: "string" };
+
+/** @typedef {import("./index.d.ts").Type} Type */
+
+/** `list<elem>` @param {Type} elem */
+export const list = (elem) => ({ kind: "list", elem });
+
+/** `option<some>` @param {Type} some */
+export const option = (some) => ({ kind: "option", some });
+
+/**
+ * `future<some>`. Carries a single asynchronous value, multiplexed over the
+ * invocation's framed stream. Requires the async session API (`invoke` /
+ * `accept`); the synchronous `encode`/`decode` cannot transmit it.
+ * @param {Type} some
+ */
+export const future = (some) => ({ kind: "future", some });
+
+/**
+ * `stream<elem>`. Carries an asynchronous sequence of `elem` chunks,
+ * multiplexed over the invocation's framed stream. Requires the async session
+ * API (`invoke` / `accept`).
+ * @param {Type} elem
+ */
+export const stream = (elem) => ({ kind: "stream", elem });
+
+/**
+ * `result<ok, err>`. Pass `null` for an absent payload, e.g. `result(null, e)`
+ * is `result<_, e>` and `result()` is bare `result`.
+ * @param {Type | null} [ok]
+ * @param {Type | null} [err]
+ */
+export const result = (ok = null, err = null) => ({ kind: "result", ok, err });
+
+/** `tuple<...elems>` @param {...Type} elems */
+export const tuple = (...elems) => ({ kind: "tuple", elems });
+
+/**
+ * A record. Accepts an ordered field map `{ name: Type }` or an array of
+ * `{ name, ty }`. Field order is the wire order and must match the WIT.
+ * @param {Record<string, Type> | { name: string, ty: Type }[]} fields
+ */
+export const record = (fields) => ({ kind: "record", fields: normalizeFields(fields) });
+
+/**
+ * A variant. Accepts a case map `{ name: Type | null }` (use `null` for a
+ * payload-less case) or an array of `{ name, ty }`.
+ * @param {Record<string, Type | null> | { name: string, ty: Type | null }[]} cases
+ */
+export const variant = (cases) => ({
+  kind: "variant",
+  cases: normalizeCases(cases),
+});
+
+/** An enum. @param {string[]} names */
+export const enumType = (names) => ({ kind: "enum", names: [...names] });
+
+/** Flags. @param {string[]} names */
+export const flags = (names) => ({ kind: "flags", names: [...names] });
+
+/** An owned resource handle `own<name>`. @param {string} name */
+export const own = (name) => ({ kind: "own", name });
+
+/** A borrowed resource handle `borrow<name>`. @param {string} name */
+export const borrow = (name) => ({ kind: "borrow", name });
+
+/** @param {Record<string, Type> | { name: string, ty: Type }[]} fields */
+function normalizeFields(fields) {
+  if (Array.isArray(fields)) return fields.map(({ name, ty }) => ({ name, ty }));
+  return Object.entries(fields).map(([name, ty]) => ({ name, ty }));
+}
+
+/** @param {Record<string, Type | null> | { name: string, ty: Type | null }[]} cases */
+function normalizeCases(cases) {
+  if (Array.isArray(cases)) return cases.map(({ name, ty }) => ({ name, ty: ty ?? null }));
+  return Object.entries(cases).map(([name, ty]) => ({ name, ty: ty ?? null }));
+}
+
+// `enum` is a reserved word, so the constructor is exported as `enumType`; this
+// alias lets callers write `t.enum([...])` via the namespace import.
+export { enumType as enum };
diff --git a/js/src/value.js b/js/src/value.js
new file mode 100644
index 000000000..10103961f
--- /dev/null
+++ b/js/src/value.js
@@ -0,0 +1,395 @@
+// The component-model value codec, in the wRPC wire format. A value is encoded
+// or decoded against a `Type` from `types.js`. This mirrors the canonical Rust
+// codec in `wrpc-transport`'s `value.rs`.
+//
+// JavaScript representation of values (aligned with the component-model JS
+// conventions used by `jco`):
+//
+//   bool                -> boolean
+//   s8/u8/.../s32/u32   -> number
+//   s64/u64             -> bigint
+//   f32/f64             -> number
+//   char                -> string (a single Unicode scalar)
+//   string              -> string
+//   list<u8>            -> Uint8Array
+//   list<T>             -> Array
+//   tuple               -> Array
+//   record              -> object keyed by field name
+//   option<T>           -> T | undefined (none is `undefined`/`null`)
+//   result<O, E>        -> { tag: "ok", val } | { tag: "err", val }
+//   variant             -> { tag: caseName, val? }
+//   enum                -> string (the case name)
+//   flags               -> { [name]: boolean }
+//   own<R> / borrow<R>  -> Uint8Array (the opaque handle bytes)
+
+import { Chan, Reader, Writer, textEncoder, textDecoder } from "./io.js";
+
+/** @typedef {import("./index.d.ts").Type} Type */
+/** @typedef {import("./index.d.ts").Value} Value */
+
+/** @param {Type} ty */
+const isBytes = (ty) => ty.kind === "list" && ty.elem.kind === "u8";
+
+/**
+ * Extend a relative index `path` by structural index `i`, but only while a
+ * `sink` is being collected (otherwise paths are irrelevant and left
+ * `undefined`). `option`/`result`/`variant` keep the parent's path; `list`,
+ * `tuple` and `record` push the element/field index, matching the wRPC
+ * indexing rules.
+ * @param {unknown} sink
+ * @param {number[] | undefined} path
+ * @param {number} i
+ */
+const childPath = (sink, path, i) => (sink ? [...(path ?? []), i] : undefined);
+
+/** @param {string} kind @param {string} [op] */
+const asyncRequired = (kind, op = "decode") =>
+  `\`${kind}\` values require the async session API (\`invoke\`/\`accept\`), ` +
+  `not the synchronous \`${op}\``;
+
+/**
+ * Coerce `v` to an integer `bigint` and assert it is within `[min, max]`,
+ * rejecting fractional, non-numeric, or out-of-range inputs instead of
+ * silently wrapping them on the wire.
+ * @param {any} v @param {string} kind @param {bigint} min @param {bigint} max
+ * @returns {bigint}
+ */
+function checkInt(v, kind, min, max) {
+  let b;
+  if (typeof v === "bigint") {
+    b = v;
+  } else {
+    const n = Number(v);
+    if (!Number.isInteger(n)) throw new TypeError(`expected an integer for \`${kind}\`, got ${v}`);
+    b = BigInt(n);
+  }
+  if (b < min || b > max) {
+    throw new RangeError(`\`${kind}\` value ${b} out of range [${min}, ${max}]`);
+  }
+  return b;
+}
+
+/**
+ * Decode a single stream/list chunk of `n` elements of type `elem` from `r`.
+ * `stream<u8>` chunks are returned as a `Uint8Array`; all others as an array.
+ * @param {Reader} r
+ * @param {Type} elem
+ * @param {number} n
+ * @param {import("./index.d.ts").DecodeDeferred[]} [sink]
+ * @param {number[]} [path]
+ */
+function readChunk(r, elem, n, sink, path) {
+  if (elem.kind === "u8") return r.take(n).slice();
+  const out = new Array(n);
+  for (let i = 0; i < n; i++) out[i] = decodeValue(r, elem, sink, childPath(sink, path, i));
+  return out;
+}
+
+/**
+ * Encode a value against a type into `w`.
+ *
+ * `stream` and `future` values cannot be written synchronously: their data is
+ * multiplexed over the invocation's framed stream after the synchronous header.
+ * When `sink` is supplied (by the async session machinery) the pending marker
+ * is written and a descriptor `{ path, kind, ty, value }` is appended to it,
+ * recording the relative `path` at which the deferred data must be transmitted.
+ * Without a `sink`, encountering one throws.
+ *
+ * @param {Writer} w
+ * @param {Type} ty
+ * @param {any} v
+ * @param {{ path: number[], kind: "stream" | "future", ty: Type, value: any }[]} [sink]
+ * @param {number[]} [path] relative index path to `v` (only tracked with `sink`)
+ */
+export function encodeValue(w, ty, v, sink, path) {
+  switch (ty.kind) {
+    case "bool":
+      w.u8(v ? 1 : 0);
+      return;
+    case "u8":
+      w.u8(Number(checkInt(v, "u8", 0n, 0xffn)));
+      return;
+    case "s8":
+      w.u8(Number(checkInt(v, "s8", -0x80n, 0x7fn)) & 0xff);
+      return;
+    case "u16":
+      w.varU(checkInt(v, "u16", 0n, 0xffffn));
+      return;
+    case "u32":
+      w.varU(checkInt(v, "u32", 0n, 0xffffffffn));
+      return;
+    case "u64":
+      w.varU(checkInt(v, "u64", 0n, (1n << 64n) - 1n));
+      return;
+    case "s16":
+      w.varS(checkInt(v, "s16", -0x8000n, 0x7fffn));
+      return;
+    case "s32":
+      w.varS(checkInt(v, "s32", -0x80000000n, 0x7fffffffn));
+      return;
+    case "s64":
+      w.varS(checkInt(v, "s64", -(1n << 63n), (1n << 63n) - 1n));
+      return;
+    case "f32": {
+      const buf = new ArrayBuffer(4);
+      new DataView(buf).setFloat32(0, Number(v), true);
+      w.bytes(new Uint8Array(buf));
+      return;
+    }
+    case "f64": {
+      const buf = new ArrayBuffer(8);
+      new DataView(buf).setFloat64(0, Number(v), true);
+      w.bytes(new Uint8Array(buf));
+      return;
+    }
+    case "char":
+      w.bytes(textEncoder.encode(String(v)));
+      return;
+    case "string":
+      w.name(String(v));
+      return;
+    case "list": {
+      if (isBytes(ty)) {
+        const bytes = toBytes(v);
+        w.varU(bytes.length);
+        w.bytes(bytes);
+        return;
+      }
+      if (!Array.isArray(v)) throw new TypeError("expected an array for a `list`");
+      w.varU(v.length);
+      v.forEach((x, i) => encodeValue(w, ty.elem, x, sink, childPath(sink, path, i)));
+      return;
+    }
+    case "tuple": {
+      if (!Array.isArray(v) || v.length !== ty.elems.length) {
+        throw new TypeError(`expected a ${ty.elems.length}-element tuple`);
+      }
+      ty.elems.forEach((et, i) => encodeValue(w, et, v[i], sink, childPath(sink, path, i)));
+      return;
+    }
+    case "record": {
+      if (typeof v !== "object" || v === null) throw new TypeError("expected an object for a `record`");
+      ty.fields.forEach(({ name, ty: fty }, i) => {
+        if (!(name in v)) throw new TypeError(`missing record field \`${name}\``);
+        encodeValue(w, fty, v[name], sink, childPath(sink, path, i));
+      });
+      return;
+    }
+    case "option":
+      if (v === null || v === undefined) {
+        w.u8(0);
+      } else {
+        w.u8(1);
+        encodeValue(w, ty.some, v, sink, path);
+      }
+      return;
+    case "result": {
+      const { tag, val } = asResult(v);
+      if (tag === "ok") {
+        w.u8(0);
+        if (ty.ok) encodeValue(w, ty.ok, val, sink, path);
+      } else {
+        w.u8(1);
+        if (ty.err) encodeValue(w, ty.err, val, sink, path);
+      }
+      return;
+    }
+    case "enum": {
+      const i = ty.names.indexOf(String(v));
+      if (i < 0) throw new RangeError(`unknown enum case \`${v}\``);
+      w.varU(i);
+      return;
+    }
+    case "variant": {
+      const { tag, val } = asVariant(v);
+      const i = ty.cases.findIndex((c) => c.name === tag);
+      if (i < 0) throw new RangeError(`unknown variant case \`${tag}\``);
+      w.varU(i);
+      if (ty.cases[i].ty) encodeValue(w, ty.cases[i].ty, val, sink, path);
+      return;
+    }
+    case "future":
+    case "stream": {
+      // Mark the value pending; its data flows over the framed sub-stream.
+      w.u8(0x00);
+      if (!sink) throw new Error(asyncRequired(ty.kind, "encode"));
+      const elem = ty.kind === "future" ? ty.some : ty.elem;
+      sink.push({ path: path ?? [], kind: ty.kind, ty: elem, value: v });
+      return;
+    }
+    case "flags": {
+      const set = toFlagSet(v);
+      const bytes = new Uint8Array(Math.ceil(Math.max(ty.names.length, 1) / 8));
+      ty.names.forEach((name, i) => {
+        if (set.has(name)) bytes[i >> 3] |= 1 << (i & 7);
+      });
+      w.bytes(bytes);
+      return;
+    }
+    case "own":
+    case "borrow": {
+      const bytes = toBytes(v);
+      w.varU(bytes.length);
+      w.bytes(bytes);
+      return;
+    }
+    default:
+      throw new Error(`encoding \`${/** @type {any} */ (ty).kind}\` is not supported`);
+  }
+}
+
+/**
+ * Decode a value of type `ty` from `r`.
+ *
+ * `stream` and `future` values carry their data asynchronously over the
+ * framed sub-streams. When `sink` is supplied (by the async session
+ * machinery), a placeholder is returned — a `Promise` for a `future`, an async
+ * iterable of chunks for a `stream` — and a descriptor recording the relative
+ * `path` and the placeholder's resolver/queue is appended to `sink`. Without a
+ * `sink`, encountering one throws.
+ *
+ * @param {Reader} r
+ * @param {Type} ty
+ * @param {import("./index.d.ts").DecodeDeferred[]} [sink]
+ * @param {number[]} [path] relative index path to this value (only with `sink`)
+ * @returns {any}
+ */
+export function decodeValue(r, ty, sink, path) {
+  switch (ty.kind) {
+    case "bool":
+      return r.u8() !== 0;
+    case "u8":
+      return r.u8();
+    case "s8": {
+      const b = r.u8();
+      return b >= 0x80 ? b - 0x100 : b;
+    }
+    case "u16":
+    case "u32":
+      return Number(r.varU());
+    case "s16":
+    case "s32":
+      return Number(r.varS());
+    case "u64":
+      return r.varU();
+    case "s64":
+      return r.varS();
+    case "f32":
+      return new DataView(r.take(4).slice().buffer).getFloat32(0, true);
+    case "f64":
+      return new DataView(r.take(8).slice().buffer).getFloat64(0, true);
+    case "char": {
+      // Read one UTF-8 scalar value: the lead byte determines the length.
+      const lead = r.peek();
+      const len = lead < 0x80 ? 1 : lead < 0xe0 ? 2 : lead < 0xf0 ? 3 : 4;
+      return textDecoder.decode(r.take(len));
+    }
+    case "string":
+      return r.name();
+    case "list":
+      return readChunk(r, ty.elem, Number(r.varU()), sink, path);
+    case "tuple":
+      return ty.elems.map((et, i) => decodeValue(r, et, sink, childPath(sink, path, i)));
+    case "record": {
+      /** @type {Record<string, any>} */
+      const out = {};
+      ty.fields.forEach(({ name, ty: fty }, i) => {
+        out[name] = decodeValue(r, fty, sink, childPath(sink, path, i));
+      });
+      return out;
+    }
+    case "option":
+      return r.u8() !== 0 ? decodeValue(r, ty.some, sink, path) : undefined;
+    case "result":
+      return r.u8() !== 0
+        ? { tag: "err", val: ty.err ? decodeValue(r, ty.err, sink, path) : undefined }
+        : { tag: "ok", val: ty.ok ? decodeValue(r, ty.ok, sink, path) : undefined };
+    case "enum": {
+      const i = Number(r.varU());
+      const name = ty.names[i];
+      if (name === undefined) throw new RangeError(`unknown enum discriminant ${i}`);
+      return name;
+    }
+    case "variant": {
+      const i = Number(r.varU());
+      const c = ty.cases[i];
+      if (!c) throw new RangeError(`unknown variant discriminant ${i}`);
+      return c.ty ? { tag: c.name, val: decodeValue(r, c.ty, sink, path) } : { tag: c.name };
+    }
+    case "future": {
+      const ready = r.u8() !== 0;
+      if (ready) return Promise.resolve(decodeValue(r, ty.some, sink, path));
+      if (!sink) throw new Error(asyncRequired(ty.kind));
+      /** @type {(value: any) => void} */
+      let resolve = () => {};
+      const promise = new Promise((res) => {
+        resolve = res;
+      });
+      sink.push({ path: path ?? [], kind: "future", ty: ty.some, resolve });
+      return promise;
+    }
+    case "stream": {
+      const n = Number(r.varU());
+      if (n > 0) {
+        // A stream sent inline as a single ready chunk.
+        const chunk = readChunk(r, ty.elem, n, sink, path);
+        const q = new Chan();
+        q.push(chunk);
+        q.close();
+        return q;
+      }
+      if (!sink) throw new Error(asyncRequired(ty.kind));
+      const queue = new Chan();
+      sink.push({ path: path ?? [], kind: "stream", ty: ty.elem, queue });
+      return queue;
+    }
+    case "flags": {
+      const bytes = r.take(Math.ceil(Math.max(ty.names.length, 1) / 8));
+      /** @type {Record<string, boolean>} */
+      const out = {};
+      ty.names.forEach((name, i) => {
+        out[name] = (bytes[i >> 3] & (1 << (i & 7))) !== 0;
+      });
+      return out;
+    }
+    case "own":
+    case "borrow":
+      return r.take(Number(r.varU())).slice();
+    default:
+      throw new Error(`decoding \`${/** @type {any} */ (ty).kind}\` is not supported`);
+  }
+}
+
+/** @param {any} v */
+function toBytes(v) {
+  if (v instanceof Uint8Array) return v;
+  if (v instanceof ArrayBuffer) return new Uint8Array(v);
+  if (ArrayBuffer.isView(v)) return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+  if (Array.isArray(v)) return Uint8Array.from(v);
+  throw new TypeError("expected `Uint8Array`, `ArrayBuffer`, or `number[]` for a byte list");
+}
+
+/** @param {any} v */
+function asResult(v) {
+  if (v && typeof v === "object" && (v.tag === "ok" || v.tag === "err")) {
+    return { tag: v.tag, val: v.val };
+  }
+  throw new TypeError('expected `{ tag: "ok" | "err", val }` for a `result`');
+}
+
+/** @param {any} v */
+function asVariant(v) {
+  if (typeof v === "string") return { tag: v, val: undefined };
+  if (v && typeof v === "object" && typeof v.tag === "string") return { tag: v.tag, val: v.val };
+  throw new TypeError("expected a string or `{ tag, val }` for a `variant`");
+}
+
+/** @param {any} v */
+function toFlagSet(v) {
+  if (v instanceof Set) return v;
+  if (Array.isArray(v)) return new Set(v);
+  if (v && typeof v === "object") {
+    return new Set(Object.keys(v).filter((k) => v[k]));
+  }
+  throw new TypeError("expected an object, array, or `Set` for `flags`");
+}
diff --git a/js/test/session.test.js b/js/test/session.test.js
new file mode 100644
index 000000000..ff574bf8a
--- /dev/null
+++ b/js/test/session.test.js
@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import * as t from "../src/types.js";
+import { Chan } from "../src/io.js";
+import { Mux } from "../src/mux.js";
+import { invoke, accept } from "../src/session.js";
+
+/**
+ * A pair of in-memory transports wired back to back, modelling a single
+ * bidirectional byte stream per invocation.
+ */
+function duplexPair() {
+  const a = new Chan();
+  const b = new Chan();
+  const end = (chan) => ({
+    read: async () => {
+      const { value, done } = await chan.read.next();
+      return done ? null : value;
+    },
+    write: (bytes) => {
+      chan.write.push(bytes);
+    },
+    closeWrite: () => {
+      chan.write.close();
+    },
+  });
+  return [end({ read: a, write: b }), end({ read: b, write: a })];
+}
+
+/** Drain an async iterable of chunks into a flat array. */
+async function collect(stream) {
+  const out = [];
+  for await (const chunk of stream) out.push(...chunk);
+  return out;
+}
+
+const STREAMS = "wrpc-examples:streams/handler";
+const req = t.record({ numbers: t.stream(t.u64), bytes: t.stream(t.u8) });
+const echoResult = t.tuple(t.stream(t.u64), t.stream(t.u8));
+
+test("stream parameters and results echo end to end", async () => {
+  const [client, server] = duplexPair();
+
+  // A server that echoes the request's two streams straight back.
+  const serving = (async () => {
+    const inv = await accept(server);
+    assert.equal(inv.instance, STREAMS);
+    assert.equal(inv.func, "echo");
+    const { params, done: rx } = await inv.receiveParams([req]);
+    const { numbers, bytes } = params[0];
+    await Promise.all([rx, inv.sendResults([echoResult], [[numbers, bytes]])]);
+  })();
+
+  const { results, done } = await invoke(
+    client,
+    STREAMS,
+    "echo",
+    [req],
+    [{ numbers: [[1n, 2n, 3n], [4n, 5n]], bytes: new Uint8Array([10, 20, 30, 40]) }],
+    [echoResult],
+  );
+
+  const [numbers, bytes] = results[0];
+  assert.deepEqual(await collect(numbers), [1n, 2n, 3n, 4n, 5n]);
+  assert.deepEqual(await collect(bytes), [10, 20, 30, 40]);
+
+  await Promise.all([done, serving]);
+});
+
+test("empty interior stream chunks do not truncate the stream", async () => {
+  const ty = t.tuple(t.stream(t.u64));
+  const [client, server] = duplexPair();
+  const serving = (async () => {
+    const inv = await accept(server);
+    const { params, done: rx } = await inv.receiveParams([ty]);
+    await Promise.all([rx, inv.sendResults([ty], [params[0]])]);
+  })();
+
+  // The empty middle chunk must not be read as the stream terminator.
+  const { results, done } = await invoke(
+    client,
+    STREAMS,
+    "echo",
+    [ty],
+    [[[[1n, 2n], [], [3n, 4n]]]],
+    [ty],
+  );
+  assert.deepEqual(await collect(results[0][0]), [1n, 2n, 3n, 4n]);
+  await Promise.all([done, serving]);
+});
+
+test("an inbound transport failure surfaces to a sub-stream reader", async () => {
+  /** @type {(e: Error) => void} */
+  let fail = () => {};
+  const transport = {
+    read: () => new Promise((_, reject) => (fail = reject)),
+    write: () => {},
+  };
+  const mux = new Mux(transport);
+  mux.start();
+  const reader = mux.incoming([0]);
+  const pending = reader.u8(); // waiting on inbound bytes that never arrive
+  fail(new Error("connection reset"));
+  await assert.rejects(pending, /connection reset/);
+});
+
+const futures = "wrpc-test:async/futures";
+const fut = t.future(t.string);
+
+test("future parameters and results resolve end to end", async () => {
+  const [client, server] = duplexPair();
+
+  const serving = (async () => {
+    const inv = await accept(server);
+    const { params, done: rx } = await inv.receiveParams([fut]);
+    const greeting = await params[0]; // the future the client sent
+    await Promise.all([rx, inv.sendResults([fut], [Promise.resolve(`${greeting}, world`)])]);
+  })();
+
+  const { results, done } = await invoke(
+    client,
+    futures,
+    "greet",
+    [fut],
+    // a future parameter may be a value, a promise, or a thunk returning one
+    [Promise.resolve("hello")],
+    [fut],
+  );
+
+  assert.equal(await results[0], "hello, world");
+  await Promise.all([done, serving]);
+});
+
+test("a result-less, async-less invocation completes", async () => {
+  const [client, server] = duplexPair();
+
+  const serving = (async () => {
+    const inv = await accept(server);
+    const { params } = await inv.receiveParams([t.string]);
+    assert.equal(params[0], "key");
+    await inv.sendResults([], []);
+  })();
+
+  const { results, done } = await invoke(client, "wasi:keyvalue/store", "delete", [t.string], ["key"], []);
+  assert.deepEqual(results, []);
+  await Promise.all([done, serving]);
+});
+
+// ----- nested async (stream/future within stream/future) --------------------
+
+/**
+ * Invoke an `echo` of a single-parameter, single-result function whose
+ * parameter and result share the type `ty`; the server reflects the decoded
+ * value straight back, exercising both the decode and re-encode of `ty`.
+ */
+async function echo(ty, arg) {
+  const [client, server] = duplexPair();
+  const serving = (async () => {
+    const inv = await accept(server);
+    const { params, done: rx } = await inv.receiveParams([ty]);
+    await Promise.all([rx, inv.sendResults([ty], [params[0]])]);
+  })();
+  const { results, done } = await invoke(client, "test:nested/echo", "echo", [ty], [arg], [ty]);
+  return { result: results[0], done, serving };
+}
+
+test("future<future<T>> resolves through both layers", async () => {
+  const ty = t.future(t.future(t.string));
+  const { result, done, serving } = await echo(ty, "deep");
+  assert.equal(await (await result), "deep");
+  await Promise.all([done, serving]);
+});
+
+test("future<stream<u8>> resolves to a byte stream", async () => {
+  const ty = t.future(t.stream(t.u8));
+  const { result, done, serving } = await echo(ty, new Uint8Array([1, 2, 3]));
+  assert.deepEqual(await collect(await result), [1, 2, 3]);
+  await Promise.all([done, serving]);
+});
+
+test("stream<future<T>> yields chunks of promises", async () => {
+  const ty = t.stream(t.future(t.string));
+  const { result, done, serving } = await echo(ty, [["a", "b"], ["c"]]);
+  const out = [];
+  for await (const chunk of result) out.push(...(await Promise.all(chunk)));
+  assert.deepEqual(out, ["a", "b", "c"]);
+  await Promise.all([done, serving]);
+});
+
+test("stream<stream<u8>> yields chunks of byte streams", async () => {
+  const ty = t.stream(t.stream(t.u8));
+  // one outer chunk carrying two inner byte streams
+  const { result, done, serving } = await echo(ty, [[new Uint8Array([1, 2]), new Uint8Array([3, 4])]]);
+  const out = [];
+  for await (const chunk of result) {
+    for (const inner of chunk) out.push(await collect(inner));
+  }
+  assert.deepEqual(out, [[1, 2], [3, 4]]);
+  await Promise.all([done, serving]);
+});
diff --git a/js/test/value.test.js b/js/test/value.test.js
new file mode 100644
index 000000000..75863a3c3
--- /dev/null
+++ b/js/test/value.test.js
@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import * as t from "../src/types.js";
+import { Reader, Writer } from "../src/io.js";
+import { encodeValue, decodeValue } from "../src/value.js";
+
+/** Encode a single value against `ty` to bytes. */
+function encode(ty, v) {
+  const w = new Writer();
+  encodeValue(w, ty, v);
+  return w.finish();
+}
+
+/** Decode a single value of type `ty` from `bytes`. */
+function decode(ty, bytes) {
+  return decodeValue(new Reader(bytes), ty);
+}
+
+/** Assert that `v` survives an encode/decode round-trip against `ty`. */
+function roundtrip(ty, v) {
+  const out = decode(ty, encode(ty, v));
+  assert.deepEqual(out, v);
+  return out;
+}
+
+test("booleans", () => {
+  roundtrip(t.bool, true);
+  roundtrip(t.bool, false);
+});
+
+test("small integers", () => {
+  for (const v of [0, 1, 127, 255]) roundtrip(t.u8, v);
+  for (const v of [-128, -1, 0, 127]) roundtrip(t.s8, v);
+  for (const v of [0, 300, 65535]) roundtrip(t.u16, v);
+  for (const v of [-32768, -1, 32767]) roundtrip(t.s16, v);
+  for (const v of [0, 1, 4294967295]) roundtrip(t.u32, v);
+  for (const v of [-2147483648, -1, 2147483647]) roundtrip(t.s32, v);
+});
+
+test("integer encoding rejects out-of-range and non-integer values", () => {
+  assert.throws(() => encode(t.u8, 256), /out of range/);
+  assert.throws(() => encode(t.u8, -1), /out of range/);
+  assert.throws(() => encode(t.s8, 128), /out of range/);
+  assert.throws(() => encode(t.s8, -129), /out of range/);
+  assert.throws(() => encode(t.u16, 65536), /out of range/);
+  assert.throws(() => encode(t.u32, 4294967296), /out of range/);
+  assert.throws(() => encode(t.u64, -1n), /out of range/);
+  assert.throws(() => encode(t.u64, 1n << 64n), /out of range/);
+  assert.throws(() => encode(t.u8, 1.5), /expected an integer/);
+  // bounds are inclusive
+  roundtrip(t.u8, 255);
+  roundtrip(t.s8, -128);
+});
+
+test("64-bit integers are bigint", () => {
+  roundtrip(t.u64, 0n);
+  roundtrip(t.u64, 18446744073709551615n);
+  roundtrip(t.s64, -9223372036854775808n);
+  roundtrip(t.s64, 9223372036854775807n);
+});
+
+test("floats", () => {
+  for (const v of [0, 1.5, -2.25, 3.141592653589793]) roundtrip(t.f64, v);
+  roundtrip(t.f32, 1.5);
+});
+
+test("char and string", () => {
+  roundtrip(t.char, "a");
+  roundtrip(t.char, "€");
+  roundtrip(t.char, "😀");
+  roundtrip(t.string, "");
+  roundtrip(t.string, "hello, wRPC 👋");
+});
+
+test("byte lists round-trip as Uint8Array", () => {
+  const out = roundtrip(t.list(t.u8), new Uint8Array([1, 2, 3, 255]));
+  assert.ok(out instanceof Uint8Array);
+  // encoding also accepts a plain array
+  assert.deepEqual(decode(t.list(t.u8), encode(t.list(t.u8), [1, 2, 3])), new Uint8Array([1, 2, 3]));
+});
+
+test("lists, tuples, records", () => {
+  roundtrip(t.list(t.string), ["a", "b", "c"]);
+  roundtrip(t.tuple(t.u8, t.string, t.bool), [7, "x", true]);
+  const rec = t.record({ keys: t.list(t.string), cursor: t.option(t.string) });
+  roundtrip(rec, { keys: ["a", "b"], cursor: "next" });
+  roundtrip(rec, { keys: [], cursor: undefined });
+});
+
+test("options", () => {
+  const ty = t.option(t.u32);
+  roundtrip(ty, 42);
+  assert.equal(decode(ty, encode(ty, undefined)), undefined);
+  assert.equal(decode(ty, encode(ty, null)), undefined);
+});
+
+test("results", () => {
+  const ty = t.result(t.string, t.u32);
+  roundtrip(ty, { tag: "ok", val: "fine" });
+  roundtrip(ty, { tag: "err", val: 7 });
+  // `result<_, e>`: ok carries no payload
+  const unit = t.result(null, t.string);
+  assert.deepEqual(decode(unit, encode(unit, { tag: "ok" })), { tag: "ok", val: undefined });
+});
+
+test("enums and variants", () => {
+  const color = t.enum(["red", "green", "blue"]);
+  roundtrip(color, "green");
+  const err = t.variant({ "no-such-store": null, "access-denied": null, other: t.string });
+  roundtrip(err, { tag: "no-such-store" });
+  roundtrip(err, { tag: "other", val: "boom" });
+  // a payload-less variant case may be written as a bare string
+  assert.deepEqual(decode(err, encode(err, "access-denied")), { tag: "access-denied" });
+});
+
+test("flags", () => {
+  const ty = t.flags(["read", "write", "exec"]);
+  roundtrip(ty, { read: true, write: false, exec: true });
+  // arrays and sets are also accepted on encode
+  assert.deepEqual(decode(ty, encode(ty, ["read", "exec"])), { read: true, write: false, exec: true });
+});
+
+test("resource handles round-trip as bytes", () => {
+  const handle = new Uint8Array(16).map((_, i) => i);
+  const out = roundtrip(t.own("bucket"), handle);
+  assert.ok(out instanceof Uint8Array);
+  roundtrip(t.borrow("bucket"), handle);
+});
+
+test("stream and future cannot be encoded or decoded synchronously", () => {
+  // They require the async session API; `encode`/`decode` must refuse them.
+  assert.throws(() => encode(t.stream(t.u8), new Uint8Array([1])), /async session API/);
+  assert.throws(() => encode(t.future(t.string), "x"), /async session API/);
+  // a pending marker (`0x00`) decoded on its own is likewise rejected
+  assert.throws(() => decode(t.stream(t.u8), new Uint8Array([0])), /async session API/);
+  assert.throws(() => decode(t.future(t.string), new Uint8Array([0])), /async session API/);
+});
+
+test("the wasi:keyvalue store types", () => {
+  const error = t.variant({ "no-such-store": null, "access-denied": null, other: t.string });
+  const open = t.result(t.own("bucket"), error);
+  const get = t.result(t.option(t.list(t.u8)), error);
+  const set = t.result(null, error);
+
+  roundtrip(open, { tag: "ok", val: new Uint8Array([0xde, 0xad, 0xbe, 0xef]) });
+  roundtrip(get, { tag: "ok", val: new TextEncoder().encode("value") });
+  roundtrip(get, { tag: "ok", val: undefined });
+  roundtrip(get, { tag: "err", val: { tag: "no-such-store" } });
+  assert.deepEqual(decode(set, encode(set, { tag: "ok" })), { tag: "ok", val: undefined });
+});
diff --git a/js/tsconfig.json b/js/tsconfig.json
new file mode 100644
index 000000000..1066512f4
--- /dev/null
+++ b/js/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}