From 0debf00bf809cd5c9d2fae6851e34d1e4bb239e9 Mon Sep 17 00:00:00 2001
From: Roman Volosatovs <rvolosatovs@riseup.net>
Date: Mon, 22 Jun 2026 19:56:00 +0200
Subject: [PATCH 1/2] feat(js): add wRPC codec package and use it in the web
 example

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. The example keeps its
own WebTransport stream handling.

Assisted-by: claude:claude-opus-4-8
---
 examples/web/rust/src/main.rs |   6 +
 examples/web/ui/index.html    | 380 +++++++---------------------------
 js/.gitignore                 |   3 +
 js/README.md                  | 118 +++++++++++
 js/package.json               |  45 ++++
 js/src/frame.js               |  85 ++++++++
 js/src/index.d.ts             | 104 ++++++++++
 js/src/index.js               |  15 ++
 js/src/io.js                  | 151 ++++++++++++++
 js/src/types.js               |  94 +++++++++
 js/src/value.js               | 297 ++++++++++++++++++++++++++
 js/src/wit.js                 | 251 ++++++++++++++++++++++
 js/test/frame.test.js         |  52 +++++
 js/test/value.test.js         | 114 ++++++++++
 js/test/wit.test.js           |  62 ++++++
 js/tsconfig.json              |  14 ++
 16 files changed, 1491 insertions(+), 300 deletions(-)
 create mode 100644 js/.gitignore
 create mode 100644 js/README.md
 create mode 100644 js/package.json
 create mode 100644 js/src/frame.js
 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/types.js
 create mode 100644 js/src/value.js
 create mode 100644 js/src/wit.js
 create mode 100644 js/test/frame.test.js
 create mode 100644 js/test/value.test.js
 create mode 100644 js/test/wit.test.js
 create mode 100644 js/tsconfig.json

diff --git a/examples/web/rust/src/main.rs b/examples/web/rust/src/main.rs
index b02d422a7..37e0b58bf 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 _;
@@ -691,6 +692,11 @@ export const PORT = "{port}"
                     ),
                 )),
             )
+            // Serve the `@bytecodealliance/wrpc` codec 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 8cf5f7d09..67d568432 100644
--- a/examples/web/ui/index.html
+++ b/examples/web/ui/index.html
@@ -32,12 +32,65 @@
         }
     </style>
     <script type="module">
+        // The wRPC wire encoding and framing are provided by the
+        // `@bytecodealliance/wrpc` codec, served by the backend under `/wrpc`.
+        // This example owns the WebTransport stream handling (see `invoke`).
+        import { t, encodeInvocation, decodeResults, concatBytes } 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 codec builds the request bytes, the stream carries them,
+        // and the codec decodes the reply. The framed transport maps one stream
+        // to one invocation, so the write side is closed once the request is
+        // sent and the response is read until the stream ends.
+        async function invoke(instance, func, paramTypes, resultTypes, args) {
+            if (!conn) throw 'WebTransport not connected';
+            const payload = encodeInvocation(instance, func, paramTypes, args);
+
+            const stream = await conn.createBidirectionalStream();
+            const writer = stream.writable.getWriter();
+            await writer.write(payload);
+            await writer.close();
+
+            const reader = stream.readable.getReader();
+            const chunks = [];
+            for (; ;) {
+                const { done, value } = await reader.read();
+                if (value) chunks.push(value);
+                if (done) break;
+            }
+            return decodeResults(concatBytes(chunks), resultTypes);
+        }
+
+        // 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 +108,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';
 
@@ -338,25 +162,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() {
@@ -364,73 +179,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..2ab8404dd
--- /dev/null
+++ b/js/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+*.tgz
+package-lock.json
diff --git a/js/README.md b/js/README.md
new file mode 100644
index 000000000..cd4e1bc95
--- /dev/null
+++ b/js/README.md
@@ -0,0 +1,118 @@
+# `@bytecodealliance/wrpc`
+
+The [wRPC](https://github.com/bytecodealliance/wrpc) codec for JavaScript: a
+transport-agnostic encoder/decoder for the wRPC wire format. It encodes and
+decodes [component model] values against a WIT type tree and frames an
+invocation's 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 a value's type with the `t` (types) builders, then encode and decode:
+
+```js
+import { t, encode, decode } from "@bytecodealliance/wrpc";
+
+const error = t.variant({
+  "no-such-store": null,
+  "access-denied": null,
+  other: t.string,
+});
+const ty = t.result(t.option(t.list(t.u8)), error);
+
+const bytes = encode(ty, { tag: "ok", val: new TextEncoder().encode("hi") });
+const value = decode(ty, bytes); // { tag: "ok", val: Uint8Array }
+```
+
+To invoke a function, build the request bytes with `encodeInvocation`, write
+them on a transport stream, and decode the reply with `decodeResults`:
+
+```js
+import { t, encodeInvocation, decodeResults, concatBytes } from "@bytecodealliance/wrpc";
+
+const store = "wasi:keyvalue/store@0.2.0-draft2";
+
+// open: func(identifier: string) -> result<bucket, error>
+const payload = encodeInvocation(store, "open", [t.string], [""]);
+
+// ... write `payload` on a bidirectional byte stream and read the reply ...
+const reply = concatBytes(chunks);
+
+const [opened] = decodeResults(reply, [t.result(t.own("bucket"), error)]);
+if (opened.tag === "err") throw opened.val;
+const bucket = opened.val; // a Uint8Array handle
+```
+
+The framing matches the default `wrpc-transport` framing (TCP, Unix,
+WebTransport, WebSocket): a single connection per invocation, with the protocol
+byte, the instance and function names, and a root parameter frame on the way
+out, and a root result frame on the way back.
+
+## 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 }`                        |
+| `own<R>` / `borrow<R>`    | `Uint8Array` (the opaque handle bytes)       |
+
+## Working without static types
+
+If a server renders its interface as inlined WIT (as the `wrpc-wasmtime` CLI
+does), `parseWit` / `parseType` turn that text into the same type tree the
+`t` builders produce, so you can drive the codec without generated bindings:
+
+```js
+import { parseType, encode, decode } from "@bytecodealliance/wrpc";
+
+const ty = parseType("result<option<list<u8>>, variant { not-found, other(string) }>");
+const value = decode(ty, encode(ty, { tag: "ok", val: new Uint8Array([1, 2, 3]) }));
+```
+
+## API
+
+- `t` / `types` — type-tree builders (`bool`, `list`, `record`, `result`, …).
+- `encode(ty, value)` / `decode(ty, bytes)` — single-value codec.
+- `encodeValue(writer, ty, value)` / `decodeValue(reader, ty)` — streaming codec.
+- `Writer` / `Reader` — LEB128 and `core:name` byte primitives.
+- `parseType(text)` / `parseWit(text)` — WIT text → type tree.
+- `encodeInvocation(instance, func, paramTypes, args)` — the request bytes.
+- `decodeResults(bytes, resultTypes)` — the decoded results.
+- `concatBytes(chunks)` — join the byte chunks a transport yields.
+
+## Development
+
+```sh
+npm test       # codec / framing / WIT round-trip 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.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/frame.js b/js/src/frame.js
new file mode 100644
index 000000000..37dcd949f
--- /dev/null
+++ b/js/src/frame.js
@@ -0,0 +1,85 @@
+// The default wRPC framing for non-multiplexed byte-stream transports (the same
+// framing `wrpc-transport`'s `frame` module implements, used by TCP, Unix,
+// WebSocket and WebTransport).
+//
+// A client writes, on the connection's root stream:
+//   - the framing protocol byte `0x00`,
+//   - the `core:name`-encoded instance and function names,
+//   - the root frame `[path-len=0][data-len][params]`, whose data is the
+//     concatenated encoding of the parameters.
+//
+// The server replies with the concatenated encoding of the results in its own
+// root frame `[path-len=0][data-len][results]`.
+//
+// This module covers the synchronous root channel only — the indexed
+// sub-streams used for async params/results (`stream`, `future`) are not
+// handled here.
+
+import { Reader, Writer } from "./io.js";
+import { encodeValue, decodeValue } from "./value.js";
+
+/** @typedef {import("./index.d.ts").Type} Type */
+
+/** The wRPC framing protocol version byte. */
+export const PROTOCOL = 0x00;
+
+/**
+ * Build the bytes a client writes to invoke `func` on `instance`: the protocol
+ * byte, the instance and function names, and the root parameter frame.
+ * @param {string} instance
+ * @param {string} func
+ * @param {Type[]} paramTypes
+ * @param {any[]} args
+ * @returns {Uint8Array}
+ */
+export function encodeInvocation(instance, func, paramTypes, args) {
+  if (args.length !== paramTypes.length) {
+    throw new RangeError(`expected ${paramTypes.length} argument(s), got ${args.length}`);
+  }
+  const params = new Writer();
+  paramTypes.forEach((ty, i) => encodeValue(params, ty, args[i]));
+  const paramBytes = params.finish();
+
+  const w = new Writer();
+  w.u8(PROTOCOL);
+  w.name(instance);
+  w.name(func);
+  w.u8(0); // root frame path length
+  w.varU(paramBytes.length); // root frame data length
+  w.bytes(paramBytes);
+  return w.finish();
+}
+
+/**
+ * Decode the server's root result frame `[path-len=0][data-len][data]` into the
+ * result values. An empty input means no result frame was written (i.e. a
+ * function with no results).
+ * @param {Uint8Array} bytes
+ * @param {Type[]} resultTypes
+ * @returns {any[]}
+ */
+export function decodeResults(bytes, resultTypes) {
+  if (resultTypes.length === 0 || bytes.length === 0) return [];
+  const frame = new Reader(bytes);
+  const pathLen = Number(frame.varU());
+  if (pathLen !== 0) throw new Error(`unexpected result frame path length ${pathLen}`);
+  const dataLen = Number(frame.varU());
+  const data = new Reader(frame.take(dataLen));
+  return resultTypes.map((ty) => decodeValue(data, ty));
+}
+
+/**
+ * Concatenate a list of byte chunks into a single `Uint8Array`.
+ * @param {Uint8Array[]} chunks
+ */
+export function concatBytes(chunks) {
+  let total = 0;
+  for (const c of chunks) total += c.length;
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.length;
+  }
+  return out;
+}
diff --git a/js/src/index.d.ts b/js/src/index.d.ts
new file mode 100644
index 000000000..c877b6379
--- /dev/null
+++ b/js/src/index.d.ts
@@ -0,0 +1,104 @@
+// 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: "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 }
+  | undefined;
+
+// ----- types.js -------------------------------------------------------------
+
+export namespace types {
+  const bool: Type;
+  const s8: Type;
+  const u8: Type;
+  const s16: Type;
+  const u16: Type;
+  const s32: Type;
+  const u32: Type;
+  const s64: Type;
+  const u64: Type;
+  const f32: Type;
+  const f64: Type;
+  const char: Type;
+  const string: Type;
+  function list(elem: Type): Type;
+  function option(some: Type): Type;
+  function result(ok?: Type | null, err?: Type | null): Type;
+  function tuple(...elems: Type[]): Type;
+  function record(fields: Record<string, Type> | { name: string; ty: Type }[]): Type;
+  function variant(cases: Record<string, Type | null> | { name: string; ty: Type | null }[]): Type;
+  function enumType(names: string[]): Type;
+  export { enumType as enum };
+  function flags(names: string[]): Type;
+  function own(name: string): Type;
+  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;
+  take(n: number): Uint8Array;
+  varU(): bigint;
+  varS(): bigint;
+  name(): string;
+}
+
+// ----- value.js -------------------------------------------------------------
+
+export function encode(ty: Type, v: Value): Uint8Array;
+export function decode(ty: Type, bytes: Uint8Array): Value;
+export function encodeValue(w: Writer, ty: Type, v: Value): void;
+export function decodeValue(r: Reader, ty: Type): Value;
+
+// ----- wit.js ---------------------------------------------------------------
+
+export function parseType(text: string): Type;
+export function parseWit(text: string): {
+  package: string | null;
+  interface: string;
+  funcs: { name: string; params: { name: string; ty: Type }[]; results: Type[] }[];
+};
+
+// ----- frame.js -------------------------------------------------------------
+
+export const PROTOCOL: number;
+export function encodeInvocation(instance: string, func: string, paramTypes: Type[], args: Value[]): Uint8Array;
+export function decodeResults(bytes: Uint8Array, resultTypes: Type[]): Value[];
+export function concatBytes(chunks: Uint8Array[]): Uint8Array;
diff --git a/js/src/index.js b/js/src/index.js
new file mode 100644
index 000000000..d3cc8e9f1
--- /dev/null
+++ b/js/src/index.js
@@ -0,0 +1,15 @@
+// The wRPC codec for JavaScript: a transport-agnostic encoder/decoder for the
+// wRPC wire format.
+//
+// `types` (re-exported as `t`) builds the structural type tree; `value`
+// encodes/decodes component-model values against it; `wit` parses a served
+// interface description back into types; and `frame` is the default
+// byte-stream framing used to invoke a function and read its results.
+
+export * as t from "./types.js";
+export * as types from "./types.js";
+
+export { Reader, Writer } from "./io.js";
+export { encode, decode, encodeValue, decodeValue } from "./value.js";
+export { parseType, parseWit } from "./wit.js";
+export { PROTOCOL, encodeInvocation, decodeResults, concatBytes } from "./frame.js";
diff --git a/js/src/io.js b/js/src/io.js
new file mode 100644
index 000000000..67e515bd3
--- /dev/null
+++ b/js/src/io.js
@@ -0,0 +1,151 @@
+// 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 `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));
+  }
+}
+
+export { textEncoder, textDecoder };
diff --git a/js/src/types.js b/js/src/types.js
new file mode 100644
index 000000000..3321ba86a
--- /dev/null
+++ b/js/src/types.js
@@ -0,0 +1,94 @@
+// 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 }
+//
+// The same tree is produced by the WIT parser in `wit.js`.
+
+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 });
+
+/**
+ * `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..81648fb8a
--- /dev/null
+++ b/js/src/value.js
@@ -0,0 +1,297 @@
+// The component-model value codec, in the wRPC wire format. A value is encoded
+// or decoded against a `Type` from `types.js` (or the WIT parser). 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 { 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";
+
+/**
+ * Encode a value against a type into `w`.
+ * @param {Writer} w
+ * @param {Type} ty
+ * @param {any} v
+ */
+export function encodeValue(w, ty, v) {
+  switch (ty.kind) {
+    case "bool":
+      w.u8(v ? 1 : 0);
+      return;
+    case "u8":
+    case "s8":
+      w.u8(Number(v) & 0xff);
+      return;
+    case "u16":
+    case "u32":
+    case "u64":
+      w.varU(typeof v === "bigint" ? v : Math.trunc(Number(v)));
+      return;
+    case "s16":
+    case "s32":
+    case "s64":
+      w.varS(typeof v === "bigint" ? v : Math.trunc(Number(v)));
+      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);
+      for (const x of v) encodeValue(w, ty.elem, x);
+      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]));
+      return;
+    }
+    case "record": {
+      if (typeof v !== "object" || v === null) throw new TypeError("expected an object for a `record`");
+      for (const { name, ty: fty } of ty.fields) {
+        if (!(name in v)) throw new TypeError(`missing record field \`${name}\``);
+        encodeValue(w, fty, v[name]);
+      }
+      return;
+    }
+    case "option":
+      if (v === null || v === undefined) {
+        w.u8(0);
+      } else {
+        w.u8(1);
+        encodeValue(w, ty.some, v);
+      }
+      return;
+    case "result": {
+      const { tag, val } = asResult(v);
+      if (tag === "ok") {
+        w.u8(0);
+        if (ty.ok) encodeValue(w, ty.ok, val);
+      } else {
+        w.u8(1);
+        if (ty.err) encodeValue(w, ty.err, val);
+      }
+      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);
+      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`.
+ * @param {Reader} r
+ * @param {Type} ty
+ * @returns {any}
+ */
+export function decodeValue(r, ty) {
+  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.bytes[r.pos];
+      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": {
+      const n = Number(r.varU());
+      if (isBytes(ty)) return r.take(n).slice();
+      const out = new Array(n);
+      for (let i = 0; i < n; i++) out[i] = decodeValue(r, ty.elem);
+      return out;
+    }
+    case "tuple":
+      return ty.elems.map((et) => decodeValue(r, et));
+    case "record": {
+      /** @type {Record<string, any>} */
+      const out = {};
+      for (const { name, ty: fty } of ty.fields) out[name] = decodeValue(r, fty);
+      return out;
+    }
+    case "option":
+      return r.u8() !== 0 ? decodeValue(r, ty.some) : undefined;
+    case "result":
+      return r.u8() !== 0
+        ? { tag: "err", val: ty.err ? decodeValue(r, ty.err) : undefined }
+        : { tag: "ok", val: ty.ok ? decodeValue(r, ty.ok) : 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) } : { tag: c.name };
+    }
+    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`);
+  }
+}
+
+/**
+ * Encode a single value to a fresh `Uint8Array`.
+ * @param {Type} ty
+ * @param {any} v
+ */
+export function encode(ty, v) {
+  const w = new Writer();
+  encodeValue(w, ty, v);
+  return w.finish();
+}
+
+/**
+ * Decode a single value from `bytes`.
+ * @param {Type} ty
+ * @param {Uint8Array} bytes
+ */
+export function decode(ty, bytes) {
+  return decodeValue(new Reader(bytes), ty);
+}
+
+/** @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/src/wit.js b/js/src/wit.js
new file mode 100644
index 000000000..b53bb74f6
--- /dev/null
+++ b/js/src/wit.js
@@ -0,0 +1,251 @@
+// A parser for the structural, inlined subset of WIT that wRPC servers render
+// with `wasm-wave`'s `DisplayType` (records as `record { a: u8 }`, variants as
+// `variant { off, on(u8) }`, …). It turns that text back into the `Type` tree
+// the value codec walks, so a client can fetch a served interface description
+// and invoke it without statically generated bindings.
+//
+// This handles inlined, self-contained type expressions and a flat
+// `interface { name: func(...) -> ...; }` document. It does not resolve named
+// type aliases or `use` statements; build those types with `types.js` instead.
+
+// Identifiers, the `->` arrow, version/number runs (e.g. `0.2.0-draft2` in a
+// package declaration), and single-character punctuation.
+const TYPE_TOKEN = /\s*(->|[A-Za-z][A-Za-z0-9-]*|[0-9][A-Za-z0-9.+-]*|[{}()<>,:;_/.@])/y;
+
+/** @param {string} src @returns {string[]} */
+function tokenize(src) {
+  const tokens = [];
+  let pos = 0;
+  while (pos < src.length) {
+    TYPE_TOKEN.lastIndex = pos;
+    const m = TYPE_TOKEN.exec(src);
+    if (!m) {
+      if (/\s/.test(src[pos])) {
+        pos += 1;
+        continue;
+      }
+      throw new SyntaxError(`unexpected character \`${src[pos]}\` in WIT`);
+    }
+    tokens.push(m[1]);
+    pos = TYPE_TOKEN.lastIndex;
+  }
+  return tokens;
+}
+
+const PRIMITIVES = new Set([
+  "bool", "s8", "u8", "s16", "u16", "s32", "u32", "s64", "u64",
+  "f32", "f64", "char", "string",
+]);
+
+/** A token cursor shared by the type and document parsers. */
+class TokenStream {
+  /** @param {string[]} tokens */
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.pos = 0;
+  }
+  peek() {
+    return this.tokens[this.pos];
+  }
+  next() {
+    if (this.pos >= this.tokens.length) throw new SyntaxError("unexpected end of WIT");
+    return this.tokens[this.pos++];
+  }
+  /** @param {string} tok */
+  expect(tok) {
+    const got = this.next();
+    if (got !== tok) throw new SyntaxError(`expected \`${tok}\`, got \`${got}\``);
+    return got;
+  }
+  eof() {
+    return this.pos >= this.tokens.length;
+  }
+}
+
+/**
+ * Parse a single type expression from `ts` into a `Type`.
+ * @param {TokenStream} ts
+ * @returns {object}
+ */
+function parseTypeFrom(ts) {
+  const tok = ts.next();
+  if (PRIMITIVES.has(tok)) return { kind: tok };
+  switch (tok) {
+    case "list": {
+      ts.expect("<");
+      const elem = parseTypeFrom(ts);
+      ts.expect(">");
+      return { kind: "list", elem };
+    }
+    case "option": {
+      ts.expect("<");
+      const some = parseTypeFrom(ts);
+      ts.expect(">");
+      return { kind: "option", some };
+    }
+    case "result": {
+      if (ts.peek() !== "<") return { kind: "result", ok: null, err: null };
+      ts.expect("<");
+      const ok = ts.peek() === "_" ? (ts.next(), null) : parseTypeFrom(ts);
+      let err = null;
+      if (ts.peek() === ",") {
+        ts.next();
+        err = parseTypeFrom(ts);
+      }
+      ts.expect(">");
+      return { kind: "result", ok, err };
+    }
+    case "tuple": {
+      ts.expect("<");
+      const elems = [];
+      if (ts.peek() !== ">") {
+        elems.push(parseTypeFrom(ts));
+        while (ts.peek() === ",") {
+          ts.next();
+          elems.push(parseTypeFrom(ts));
+        }
+      }
+      ts.expect(">");
+      return { kind: "tuple", elems };
+    }
+    case "record": {
+      ts.expect("{");
+      const fields = [];
+      if (ts.peek() !== "}") {
+        do {
+          const name = ts.next();
+          ts.expect(":");
+          fields.push({ name, ty: parseTypeFrom(ts) });
+        } while (ts.peek() === "," && ts.next());
+      }
+      ts.expect("}");
+      return { kind: "record", fields };
+    }
+    case "variant": {
+      ts.expect("{");
+      const cases = [];
+      if (ts.peek() !== "}") {
+        do {
+          const name = ts.next();
+          let ty = null;
+          if (ts.peek() === "(") {
+            ts.next();
+            ty = parseTypeFrom(ts);
+            ts.expect(")");
+          }
+          cases.push({ name, ty });
+        } while (ts.peek() === "," && ts.next());
+      }
+      ts.expect("}");
+      return { kind: "variant", cases };
+    }
+    case "enum": {
+      ts.expect("{");
+      const names = [];
+      if (ts.peek() !== "}") {
+        do {
+          names.push(ts.next());
+        } while (ts.peek() === "," && ts.next());
+      }
+      ts.expect("}");
+      return { kind: "enum", names };
+    }
+    case "flags": {
+      ts.expect("{");
+      const names = [];
+      if (ts.peek() !== "}") {
+        do {
+          names.push(ts.next());
+        } while (ts.peek() === "," && ts.next());
+      }
+      ts.expect("}");
+      return { kind: "flags", names };
+    }
+    case "borrow": {
+      ts.expect("<");
+      const name = ts.next();
+      ts.expect(">");
+      return { kind: "borrow", name };
+    }
+    case "own": {
+      ts.expect("<");
+      const name = ts.next();
+      ts.expect(">");
+      return { kind: "own", name };
+    }
+    default:
+      // A bare identifier is an owned resource handle (`own<utxo>` is rendered
+      // as just `utxo`).
+      return { kind: "own", name: tok };
+  }
+}
+
+/**
+ * Parse a single inlined WIT type expression.
+ * @param {string} text
+ * @returns {object}
+ */
+export function parseType(text) {
+  return parseTypeFrom(new TokenStream(tokenize(text)));
+}
+
+/**
+ * Parse a flat WIT document: an optional `package` declaration and one
+ * `interface` whose body is a list of `name: func(params) -> results;`.
+ * @param {string} text
+ * @returns {{ package: string | null, interface: string, funcs: { name: string, params: { name: string, ty: object }[], results: object[] }[] }}
+ */
+export function parseWit(text) {
+  const ts = new TokenStream(tokenize(text));
+
+  let pkg = null;
+  if (ts.peek() === "package") {
+    ts.next();
+    const parts = [];
+    while (ts.peek() !== ";" && !ts.eof()) parts.push(ts.next());
+    ts.expect(";");
+    pkg = parts.join("");
+  }
+
+  ts.expect("interface");
+  const iface = ts.next();
+  ts.expect("{");
+
+  const funcs = [];
+  while (ts.peek() !== "}" && !ts.eof()) {
+    const name = ts.next();
+    ts.expect(":");
+    ts.expect("func");
+    ts.expect("(");
+    const params = [];
+    if (ts.peek() !== ")") {
+      do {
+        const pname = ts.next();
+        ts.expect(":");
+        params.push({ name: pname, ty: parseTypeFrom(ts) });
+      } while (ts.peek() === "," && ts.next());
+    }
+    ts.expect(")");
+
+    const results = [];
+    if (ts.peek() === "->") {
+      ts.next();
+      if (ts.peek() === "(") {
+        ts.next();
+        if (ts.peek() !== ")") {
+          do {
+            results.push(parseTypeFrom(ts));
+          } while (ts.peek() === "," && ts.next());
+        }
+        ts.expect(")");
+      } else {
+        results.push(parseTypeFrom(ts));
+      }
+    }
+    ts.expect(";");
+    funcs.push({ name, params, results });
+  }
+  ts.expect("}");
+
+  return { package: pkg, interface: iface, funcs };
+}
diff --git a/js/test/frame.test.js b/js/test/frame.test.js
new file mode 100644
index 000000000..48a7bd75a
--- /dev/null
+++ b/js/test/frame.test.js
@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import * as t from "../src/types.js";
+import { encode } from "../src/value.js";
+import { encodeInvocation, decodeResults, PROTOCOL } from "../src/frame.js";
+import { Writer } from "../src/io.js";
+
+const INSTANCE = "wasi:keyvalue/store@0.2.0-draft2";
+
+test("encodeInvocation matches the framed wire layout", () => {
+  // `open("")`: protocol byte, the two names, then the root frame
+  // `[path-len=0][data-len][params]` where params is the encoded `""`.
+  const bytes = encodeInvocation(INSTANCE, "open", [t.string], [""]);
+
+  const enc = new TextEncoder();
+  const name = enc.encode(INSTANCE);
+  const expected = Uint8Array.from([
+    PROTOCOL,
+    name.length, ...name,
+    4, ...enc.encode("open"),
+    0, // root frame path length
+    1, // root frame data length
+    0, // the encoded empty string (length 0)
+  ]);
+  assert.deepEqual(bytes, expected);
+});
+
+test("encodeInvocation rejects an argument-count mismatch", () => {
+  assert.throws(() => encodeInvocation(INSTANCE, "open", [t.string], []), RangeError);
+});
+
+test("decodeResults reads a root result frame", () => {
+  const error = t.variant({ "no-such-store": null, "access-denied": null, other: t.string });
+  const result = t.result(t.option(t.list(t.u8)), error);
+
+  // Build the server's reply: a root frame wrapping the encoded result value.
+  const value = { tag: "ok", val: new TextEncoder().encode("hello") };
+  const data = encode(result, value);
+  const frame = new Writer();
+  frame.u8(0); // path length
+  frame.varU(data.length); // data length
+  frame.bytes(data);
+
+  const [decoded] = decodeResults(frame.finish(), [result]);
+  assert.deepEqual(decoded, value);
+});
+
+test("decodeResults returns [] for an empty body or no result types", () => {
+  assert.deepEqual(decodeResults(new Uint8Array(), [t.string]), []);
+  assert.deepEqual(decodeResults(Uint8Array.from([0, 0]), []), []);
+});
diff --git a/js/test/value.test.js b/js/test/value.test.js
new file mode 100644
index 000000000..bc33779f5
--- /dev/null
+++ b/js/test/value.test.js
@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import * as t from "../src/types.js";
+import { encode, decode } from "../src/value.js";
+
+/** 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("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("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/test/wit.test.js b/js/test/wit.test.js
new file mode 100644
index 000000000..727af339a
--- /dev/null
+++ b/js/test/wit.test.js
@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseType, parseWit } from "../src/wit.js";
+import { encode, decode } from "../src/value.js";
+
+test("parses inlined primitive and compound types", () => {
+  assert.deepEqual(parseType("u64"), { kind: "u64" });
+  assert.deepEqual(parseType("list<string>"), { kind: "list", elem: { kind: "string" } });
+  assert.deepEqual(parseType("option<u8>"), { kind: "option", some: { kind: "u8" } });
+  assert.deepEqual(parseType("result<_, string>"), {
+    kind: "result",
+    ok: null,
+    err: { kind: "string" },
+  });
+  assert.deepEqual(parseType("tuple<u8, string>"), {
+    kind: "tuple",
+    elems: [{ kind: "u8" }, { kind: "string" }],
+  });
+});
+
+test("parses records, variants, enums and flags", () => {
+  assert.deepEqual(parseType("record { a: u8, b: string }"), {
+    kind: "record",
+    fields: [
+      { name: "a", ty: { kind: "u8" } },
+      { name: "b", ty: { kind: "string" } },
+    ],
+  });
+  assert.deepEqual(parseType("variant { off, on(u8) }"), {
+    kind: "variant",
+    cases: [
+      { name: "off", ty: null },
+      { name: "on", ty: { kind: "u8" } },
+    ],
+  });
+  assert.deepEqual(parseType("enum { red, green, blue }").names, ["red", "green", "blue"]);
+  assert.deepEqual(parseType("flags { read, write }").names, ["read", "write"]);
+});
+
+test("a parsed type drives the value codec", () => {
+  const ty = parseType("result<option<list<u8>>, variant { not-found, other(string) }>");
+  const value = { tag: "ok", val: new Uint8Array([1, 2, 3]) };
+  assert.deepEqual(decode(ty, encode(ty, value)), value);
+});
+
+test("parses a flat interface document", () => {
+  const doc = parseWit(`
+    package wasi:keyvalue@0.2.0-draft2;
+    interface store {
+      open: func(identifier: string) -> result<u32, string>;
+      drop: func(handle: u32);
+    }
+  `);
+  assert.equal(doc.package, "wasi:keyvalue@0.2.0-draft2");
+  assert.equal(doc.interface, "store");
+  assert.equal(doc.funcs.length, 2);
+  assert.equal(doc.funcs[0].name, "open");
+  assert.deepEqual(doc.funcs[0].params, [{ name: "identifier", ty: { kind: "string" } }]);
+  assert.equal(doc.funcs[0].results.length, 1);
+  assert.deepEqual(doc.funcs[1].results, []);
+});
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"]
+}

From dc363b043bcb245f6164553de3cf29748c3698dd Mon Sep 17 00:00:00 2001
From: Roman Volosatovs <rvolosatovs@riseup.net>
Date: Mon, 22 Jun 2026 20:47:22 +0200
Subject: [PATCH 2/2] fix(js): error clearly when a result frame is missing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`decodeResults` treated an empty response identically whether or not
results were expected, returning `[]` in both cases. When a peer closes
the wRPC stream without writing a result frame — e.g. the web example's
proxy backend is unreachable and the invocation fails server-side — the
caller's `const [res] = ...` destructure yielded `undefined`, surfacing
as a cryptic "can't access property tag, res is undefined" in the UI.

Throw a descriptive error in that case instead, while still returning
`[]` for functions that legitimately have no results.

Assisted-by: claude:claude-opus-4-8
---
 js/src/frame.js       | 14 +++++++++++---
 js/test/frame.test.js |  8 ++++++--
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/js/src/frame.js b/js/src/frame.js
index 37dcd949f..f0d915f2f 100644
--- a/js/src/frame.js
+++ b/js/src/frame.js
@@ -52,14 +52,22 @@ export function encodeInvocation(instance, func, paramTypes, args) {
 
 /**
  * Decode the server's root result frame `[path-len=0][data-len][data]` into the
- * result values. An empty input means no result frame was written (i.e. a
- * function with no results).
+ * result values. A function with no results writes no frame, so an empty input
+ * is expected (and returns `[]`) only when no results are expected. If results
+ * are expected but the input is empty, the peer closed the stream without
+ * responding (e.g. the invocation failed server-side) and an error is thrown.
  * @param {Uint8Array} bytes
  * @param {Type[]} resultTypes
  * @returns {any[]}
  */
 export function decodeResults(bytes, resultTypes) {
-  if (resultTypes.length === 0 || bytes.length === 0) return [];
+  if (resultTypes.length === 0) return [];
+  if (bytes.length === 0) {
+    throw new Error(
+      "peer closed the stream without sending a result frame " +
+        "(the invocation likely failed on the other end)",
+    );
+  }
   const frame = new Reader(bytes);
   const pathLen = Number(frame.varU());
   if (pathLen !== 0) throw new Error(`unexpected result frame path length ${pathLen}`);
diff --git a/js/test/frame.test.js b/js/test/frame.test.js
index 48a7bd75a..d255ec449 100644
--- a/js/test/frame.test.js
+++ b/js/test/frame.test.js
@@ -46,7 +46,11 @@ test("decodeResults reads a root result frame", () => {
   assert.deepEqual(decoded, value);
 });
 
-test("decodeResults returns [] for an empty body or no result types", () => {
-  assert.deepEqual(decodeResults(new Uint8Array(), [t.string]), []);
+test("decodeResults returns [] when no results are expected", () => {
+  assert.deepEqual(decodeResults(new Uint8Array(), []), []);
   assert.deepEqual(decodeResults(Uint8Array.from([0, 0]), []), []);
 });
+
+test("decodeResults throws when results are expected but the body is empty", () => {
+  assert.throws(() => decodeResults(new Uint8Array(), [t.string]), /without sending a result/);
+});