@zap-proto/web 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,142 @@
+# @zap-proto/web
+
+Browser-frontend RPC over **ZAP** — a drop-in tRPC replacement for Next.js /
+Remix / SvelteKit. Native ZAP envelopes over WebSocket binary frames, layered
+cleanly on [`@zap-proto/zap`](https://github.com/zap-proto/ts) (the ZAP wire
+runtime). `v0.1.0` — pre-1.0 by policy; no version tags until the full chain
+works end-to-end.
+
+> **Note on naming.** The foundation runtime is `@zap-proto/zap` (the canonical
+> TypeScript ZAP runtime, repo `zap-proto/ts`). This package — the WebSocket
+> frontend layer — is `@zap-proto/web`, repo `zap-proto/web`. It is **not**
+> Cap'n Proto; ZAP is a zero-copy, zero-dependency binary format byte-compatible
+> with the Go runtime `github.com/zap-proto/go` and `github.com/luxfi/zap`.
+
+## What @zap-proto/web IS
+
+- A **drop-in replacement for tRPC** across Hanzo's TS apps (esign, console,
+  platform), using native ZAP RPC over WebSocket instead of JSON-over-HTTP.
+- An **isomorphic transport** — the same `WsTransport` works in Node (post
+  HTTP-upgrade, over the `ws` package) and in the browser (native `WebSocket`).
+- A Node **`serve(httpServer, opts)`** harness that attaches to an existing
+  `http.Server`, so Next.js (`app.getRequestHandler()`) or a Remix Node server
+  share one port — integration is one line.
+- A browser **`connect(url, opts)`** that opens the WS, waits for `open`, and
+  returns the bootstrap call surface typed by your generated bindings.
+- A **`mintCap` boundary hook** at the WS upgrade so apps plug their own
+  bearer→context minting logic.
+
+## What @zap-proto/web is NOT
+
+- ❌ **Not a Zod/procedure DSL** like tRPC. Service shape comes from `.zap`
+  schemas (`struct`s + method ordinals), codegen'd via
+  `zapgen --target=ts` from [`zap-proto/ts`](https://github.com/zap-proto/ts).
+- ❌ **Not a JSON wrapper.** Wire format is ZAP envelopes over WS **binary**
+  messages. Text frames are a protocol violation and close the socket with WS
+  code `1003`.
+- ❌ **Not Cap'n Proto.** ZAP is its own zero-copy format. The bootstrap is the
+  connection's call surface (`bootstrap.call(method, { payload })`), not a
+  Cap'n Proto capability object.
+- ❌ **Not a bearer-JWT framework.** `mintCap` is a **slot** — apps provide a fn
+  `(upgradeReq) => Promise<Ctx | null>`. `v0` ships the slot; the canonical
+  ML-DSA-65 signed `Capability` mint (per
+  [`zap-spec/capabilities.zap`](https://github.com/zap-proto/spec) — the
+  3408-byte signature footer, BLAKE3 identity, attenuable/revocable authority)
+  lands in a later version. Until then, whatever non-null value `mintCap`
+  returns becomes the per-connection `ctx`.
+
+## Install
+
+```sh
+pnpm i @zap-proto/web @zap-proto/zap
+```
+
+> `@zap-proto/zap` is not yet published to npm. The `dependencies` entry already
+> ships plain semver (`^0.1.0`); until it lands on npm, local tests resolve the
+> specifier to the sibling source tree (`../ts`, the `zap-proto/ts` repo) via the
+> `vitest.config.ts` alias and the `tsconfig.json` path. No change needed once
+> `@zap-proto/zap` ships — just drop the alias.
+
+## Quick start — Next.js (≈30 lines)
+
+```ts
+// server.ts
+import http from "node:http";
+import next from "next";
+import { serve } from "@zap-proto/web/server";
+import { newGreeting, HelloArgs } from "./gen/hello_zap.js"; // zapgen --target=ts
+
+const app = next({ dev: process.env.NODE_ENV !== "production" });
+const handle = app.getRequestHandler();
+
+await app.prepare();
+const server = http.createServer((req, res) => handle(req, res));
+
+serve(server, {
+  path: "/zap",
+  // mintCap SLOT: turn a bearer into your app's ctx. Return null → HTTP 401.
+  mintCap: async (req) => {
+    const auth = req.headers.authorization;
+    return auth ? { org: await orgFromBearer(auth) } : null;
+  },
+  // rootCap(ctx): dispatch every decoded ZAP Call for this connection.
+  rootCap: (ctx) => (call) => {
+    const args = HelloArgs.wrap(call.payload);
+    return {
+      status: 200,
+      promiseID: call.promiseID,
+      body: newGreeting({ text: `hi ${args.name} @ ${ctx.org}` }),
+    };
+  },
+});
+
+server.listen(3000);
+```
+
+```ts
+// client.ts (browser)
+import { connect } from "@zap-proto/web/client";
+import { newHelloArgs, Greeting } from "./gen/hello_zap.js";
+
+const { bootstrap, close } = await connect("wss://app.hanzo.ai/zap", {
+  bearer: sessionToken, // forwarded as Authorization on the upgrade (Node ws)
+});
+
+const resp = await bootstrap.call(/* method */ 0, {
+  payload: newHelloArgs({ name: "ada" }),
+});
+console.log(Greeting.wrap(resp.body).text); // "hi ada @ acme"
+close();
+```
+
+> **Browser bearer caveat.** The browser's native `WebSocket` cannot set an
+> `Authorization` header. In the browser, `connect({ bearer })` falls back to a
+> `?authorization=Bearer%20…` query param the server can read; prefer a cookie
+> sent automatically on the upgrade for production. The header path applies to a
+> header-capable `WebSocketImpl` (the `ws` package, used in Node/SSR/tests).
+
+## Schema → code
+
+Service shape is `.zap` schemas compiled with the ZAP compiler from
+[`zap-proto/ts`](https://github.com/zap-proto/ts):
+
+```sh
+zapgen --target=ts -single hello.zap   # → hello_zap.ts (views + builders)
+```
+
+Method ordinals (the interface method `@n`) are the integers you pass to
+`bootstrap.call(method, …)` and match in your `rootCap` dispatch.
+
+## API
+
+| Export | Entry | Purpose |
+| --- | --- | --- |
+| `serve(httpServer, opts)` | `@zap-proto/web/server` | Attach a ZAP RPC endpoint to a Node `http.Server`. |
+| `connect(url, opts?)` | `@zap-proto/web/client` | Open a ZAP RPC WebSocket; returns `{ bootstrap, close }`. |
+| `nodeWsTransport(ws)` / `browserWsTransport(ws)` | `@zap-proto/web/transport` | Wrap a `ws`/native WebSocket as a `WsTransport`. |
+| `MintCap<Ctx>` | `@zap-proto/web/auth` | The bearer→ctx slot. |
+| `WebRpcError` | `@zap-proto/web` | Transport-level RPC failure (rejected upgrade, mid-call close, non-OK status). |
+
+## License
+
+MIT © Lux Industries Inc.

package/dist/auth.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from "node:http";
+/**
+ * MintCap is the boundary where a bearer (cookie, header, session) becomes a
+ * typed Capability that downstream RPC methods are authorized against.
+ *
+ * v0 ships the SLOT — apps supply their own fn. The canonical ML-DSA-65 signed
+ * Capability mint (per zap-spec/capabilities.zap — the 3408-byte signature
+ * footer, BLAKE3 object identity, attenuable/revocable authority) lands in a
+ * later version. Until then you can return any object: whatever non-null value
+ * you return becomes the `ctx` threaded into your `rootCap(ctx)` factory and
+ * carried on every {@link import("@zap-proto/zap").Call} as its capability buffer.
+ *
+ * Return `null` to reject the connection with HTTP 401 before the WebSocket
+ * upgrade completes — no socket is opened for an unauthorized request.
+ *
+ * @typeParam Ctx - the minted authority/context type your handlers consume.
+ * @param req - the raw HTTP upgrade request (read `req.headers.authorization`,
+ *              cookies, etc.).
+ * @returns the minted context, or `null` to reject with 401.
+ */
+export type MintCap<Ctx> = (req: IncomingMessage) => Promise<Ctx | null>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC"}

package/dist/auth.js

@@ -0,0 +1,4 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+export {};
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,4CAA4C"}

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * client.ts — connect(url, opts): open a ZAP-over-WebSocket RPC connection from
+ * the browser (or Node, for tests) and return the bootstrap call surface.
+ *
+ * The transport is isomorphic: in the browser this uses the native WebSocket
+ * global; in Node you inject the `ws` package's WebSocket via
+ * {@link ConnectOptions.WebSocketImpl} (Node 22+ also has a built-in global
+ * WebSocket, but it cannot set request headers — see the bearer note below).
+ *
+ * Bearer note: the browser's native WebSocket constructor CANNOT set an
+ * Authorization header — the WS protocol gives JS no header control. So:
+ *   - Node `ws` (tests, SSR): we pass `{ headers: { Authorization } }`, which
+ *     `ws` forwards on the upgrade request, where serve()'s mintCap reads it.
+ *   - browser: rely on a cookie sent automatically on the upgrade, or encode
+ *     the bearer in a subprotocol; the Authorization-header path only applies
+ *     to a header-capable WebSocketImpl. We feature-detect by arity and fall
+ *     back to a query param (`?authorization=Bearer%20...`) the server can read.
+ */
+import { Conn } from "./conn.js";
+/** Options for {@link connect}. */
+export interface ConnectOptions {
+    /** Bearer token; forwarded as `Authorization: Bearer <bearer>` on upgrade. */
+    bearer?: string;
+    /**
+     * WebSocket constructor to use. Defaults to globalThis.WebSocket (browser /
+     * Node 22+). Inject the `ws` package's WebSocket in Node tests/SSR so the
+     * bearer can ride an Authorization header.
+     */
+    WebSocketImpl?: typeof WebSocket;
+}
+/**
+ * The bootstrap call surface returned by {@link connect}. RootCap is the
+ * generated typed wrapper a consumer layers over the raw {@link Conn} call
+ * surface — `connect<MyRootCap>(...)` then exposes typed methods on `bootstrap`.
+ *
+ * On the real @zap-proto/zap foundation the bootstrap is the connection's call
+ * surface (method ordinal + ZAP payload), not a Cap'n Proto capability object.
+ * The default `RootCap = Conn` gives you raw `bootstrap.call(method, { payload })`;
+ * a zapgen-generated client wraps that into named, typed methods.
+ */
+export interface Connection<RootCap = Conn> {
+    bootstrap: RootCap;
+    close(): void;
+}
+/**
+ * Open a ZAP RPC WebSocket to `url`, wait for the connection to open, and
+ * return the bootstrap call surface. The default RootCap is the raw {@link Conn}.
+ */
+export declare function connect<RootCap = Conn>(url: string, opts?: ConnectOptions): Promise<Connection<RootCap>>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,mCAAmC;AACnC,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,SAAS,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU,CAAC,OAAO,GAAG,IAAI;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAG,IAAI,EAC1C,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAgD9B"}

package/dist/client.js

@@ -0,0 +1,105 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+/**
+ * client.ts — connect(url, opts): open a ZAP-over-WebSocket RPC connection from
+ * the browser (or Node, for tests) and return the bootstrap call surface.
+ *
+ * The transport is isomorphic: in the browser this uses the native WebSocket
+ * global; in Node you inject the `ws` package's WebSocket via
+ * {@link ConnectOptions.WebSocketImpl} (Node 22+ also has a built-in global
+ * WebSocket, but it cannot set request headers — see the bearer note below).
+ *
+ * Bearer note: the browser's native WebSocket constructor CANNOT set an
+ * Authorization header — the WS protocol gives JS no header control. So:
+ *   - Node `ws` (tests, SSR): we pass `{ headers: { Authorization } }`, which
+ *     `ws` forwards on the upgrade request, where serve()'s mintCap reads it.
+ *   - browser: rely on a cookie sent automatically on the upgrade, or encode
+ *     the bearer in a subprotocol; the Authorization-header path only applies
+ *     to a header-capable WebSocketImpl. We feature-detect by arity and fall
+ *     back to a query param (`?authorization=Bearer%20...`) the server can read.
+ */
+import { Conn } from "./conn.js";
+import { browserWsTransport } from "./transport.js";
+import { WebRpcError } from "./errors.js";
+/**
+ * Open a ZAP RPC WebSocket to `url`, wait for the connection to open, and
+ * return the bootstrap call surface. The default RootCap is the raw {@link Conn}.
+ */
+export async function connect(url, opts = {}) {
+    const Impl = opts.WebSocketImpl ?? globalThis.WebSocket;
+    if (!Impl) {
+        throw new WebRpcError("zap-web: no WebSocket implementation (pass opts.WebSocketImpl)");
+    }
+    const ws = openSocket(Impl, url, opts.bearer);
+    await new Promise((resolve, reject) => {
+        const onOpen = () => {
+            cleanup();
+            resolve();
+        };
+        const onErr = () => {
+            cleanup();
+            reject(new WebRpcError(`zap-web: failed to connect to ${url}`));
+        };
+        const onClose = (ev) => {
+            cleanup();
+            const code = ev?.code;
+            reject(new WebRpcError(`zap-web: upgrade rejected by ${url}`, code === 1006 ? 401 : code));
+        };
+        const cleanup = () => {
+            remove(ws, "open", onOpen);
+            remove(ws, "error", onErr);
+            remove(ws, "close", onClose);
+        };
+        add(ws, "open", onOpen);
+        add(ws, "error", onErr);
+        add(ws, "close", onClose);
+    });
+    const transport = browserWsTransport(ws);
+    const conn = new Conn(transport);
+    return {
+        bootstrap: conn,
+        close() {
+            conn.close(1000, "client closed");
+        },
+    };
+}
+/**
+ * Construct a WebSocket, attaching the bearer the best way the impl allows.
+ * Node `ws` accepts a 3rd `options.headers` arg; the browser native WebSocket
+ * does not, so we fall back to a query param the server can read.
+ */
+function openSocket(Impl, url, bearer) {
+    if (!bearer)
+        return new Impl(url);
+    // Node `ws` WebSocket: third constructor arg is options { headers }.
+    // We detect header support by the constructor's declared arity (>= 3).
+    if (Impl.length >= 3) {
+        return new Impl(url, undefined, {
+            headers: { Authorization: `Bearer ${bearer}` },
+        });
+    }
+    // Browser native WebSocket: no header control — encode on the URL instead.
+    const u = new URL(url);
+    u.searchParams.set("authorization", `Bearer ${bearer}`);
+    return new Impl(u.toString());
+}
+// --- isomorphic add/remove listener (browser EventTarget vs `ws` emitter) ---
+function add(ws, type, fn) {
+    const anyWs = ws;
+    if (typeof anyWs.addEventListener === "function") {
+        anyWs.addEventListener(type, fn);
+    }
+    else if (typeof anyWs.on === "function") {
+        anyWs.on(type, fn);
+    }
+}
+function remove(ws, type, fn) {
+    const anyWs = ws;
+    if (typeof anyWs.removeEventListener === "function") {
+        anyWs.removeEventListener(type, fn);
+    }
+    else if (typeof anyWs.off === "function") {
+        anyWs.off(type, fn);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/conn.d.ts

@@ -0,0 +1,60 @@
+/**
+ * conn.ts — a transport-agnostic ZAP RPC connection over a {@link WsTransport}.
+ *
+ * This is the shared core of both serve() and connect(). It mirrors the
+ * correlation logic of @zap-proto/zap's ZapClient (Node TCP), but rides a duplex
+ * WebSocket transport instead of a TCP socket and works in both directions:
+ *
+ *   - client side: call() ships a request envelope and resolves its Response
+ *     when the matching promiseID comes back.
+ *   - server side: an inbound request envelope is decoded into a Call and
+ *     handed to the registered handler, whose Response is shipped back.
+ *
+ * Each WS binary message is exactly one ZAP envelope (see transport.ts), so the
+ * envelope's own header tag (MSG_TYPE_ROUTER_BASE) distinguishes a request from
+ * a response and there is no extra framing. We disambiguate direction by trying
+ * the request decode first; a frame that parses as a request with a known
+ * method is dispatched as a server call, otherwise it is treated as a response
+ * to one of our outstanding promises.
+ */
+import { type Call, type Response } from "@zap-proto/zap";
+import type { WsTransport } from "./transport.js";
+/** A server-side request handler: a decoded Call in, a Response out. */
+export type CallHandler = (call: Call) => Promise<Response> | Response;
+/** Options for an outbound {@link Conn.call}. */
+export interface CallOptions {
+    /** Pipeline this call off an earlier call's promiseID (0 = root). */
+    target?: number;
+    /** Capability buffer to carry on the call (defaults to the conn's cap). */
+    cap?: Uint8Array;
+    /** Method params, ZAP-encoded. */
+    payload?: Uint8Array;
+}
+/**
+ * Conn correlates ZAP request/response envelopes over a single duplex
+ * WebSocket transport. One Conn is FIFO per direction on the wire, matching the
+ * Go node's per-connection dispatch.
+ */
+export declare class Conn {
+    private readonly transport;
+    private readonly pending;
+    private promiseSeq;
+    private closed;
+    private handler;
+    private readonly cap;
+    constructor(transport: WsTransport, opts?: {
+        handler?: CallHandler;
+        cap?: Uint8Array;
+    });
+    /**
+     * Ship one Call and await its correlated Response. The promiseID is assigned
+     * here unless the caller pipelines via {@link CallOptions.target}.
+     */
+    call(method: number, opts?: CallOptions): Promise<Response>;
+    /** Close the connection and fail all in-flight calls. */
+    close(code?: number, reason?: string): void;
+    private onFrame;
+    private dispatch;
+    private fail;
+}
+//# sourceMappingURL=conn.d.ts.map

package/dist/conn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conn.d.ts","sourceRoot":"","sources":["../src/conn.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAOL,KAAK,IAAI,EACT,KAAK,QAAQ,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;AAEvE,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAID;;;;GAIG;AACH,qBAAa,IAAI;IAQb,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;gBAGd,SAAS,EAAE,WAAW,EACvC,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,WAAW,CAAC;QAAC,GAAG,CAAC,EAAE,UAAU,CAAA;KAAO;IAQxD;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAwB/D,yDAAyD;IACzD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAM3C,OAAO,CAAC,OAAO;YAmBD,QAAQ;IA8BtB,OAAO,CAAC,IAAI;CAcb"}

package/dist/conn.js

@@ -0,0 +1,145 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+/**
+ * conn.ts — a transport-agnostic ZAP RPC connection over a {@link WsTransport}.
+ *
+ * This is the shared core of both serve() and connect(). It mirrors the
+ * correlation logic of @zap-proto/zap's ZapClient (Node TCP), but rides a duplex
+ * WebSocket transport instead of a TCP socket and works in both directions:
+ *
+ *   - client side: call() ships a request envelope and resolves its Response
+ *     when the matching promiseID comes back.
+ *   - server side: an inbound request envelope is decoded into a Call and
+ *     handed to the registered handler, whose Response is shipped back.
+ *
+ * Each WS binary message is exactly one ZAP envelope (see transport.ts), so the
+ * envelope's own header tag (MSG_TYPE_ROUTER_BASE) distinguishes a request from
+ * a response and there is no extra framing. We disambiguate direction by trying
+ * the request decode first; a frame that parses as a request with a known
+ * method is dispatched as a server call, otherwise it is treated as a response
+ * to one of our outstanding promises.
+ */
+import { buildRequest, buildResponse, parseRequest, parseResponse, NO_TARGET, Status, } from "@zap-proto/zap";
+import { WebRpcError } from "./errors.js";
+const EMPTY = new Uint8Array(0);
+/**
+ * Conn correlates ZAP request/response envelopes over a single duplex
+ * WebSocket transport. One Conn is FIFO per direction on the wire, matching the
+ * Go node's per-connection dispatch.
+ */
+export class Conn {
+    transport;
+    pending = new Map();
+    promiseSeq = 0;
+    closed = false;
+    handler = null;
+    cap;
+    constructor(transport, opts = {}) {
+        this.transport = transport;
+        this.handler = opts.handler ?? null;
+        this.cap = opts.cap ?? EMPTY;
+        transport.onMessage((bytes) => this.onFrame(bytes));
+        transport.onClose(() => this.fail());
+    }
+    /**
+     * Ship one Call and await its correlated Response. The promiseID is assigned
+     * here unless the caller pipelines via {@link CallOptions.target}.
+     */
+    call(method, opts = {}) {
+        if (this.closed) {
+            return Promise.reject(new WebRpcError("zap-web: connection closed"));
+        }
+        this.promiseSeq = (this.promiseSeq + 1) >>> 0 || 1;
+        const promiseID = this.promiseSeq;
+        const c = {
+            method,
+            promiseID,
+            target: opts.target ?? NO_TARGET,
+            cap: opts.cap ?? this.cap,
+            payload: opts.payload ?? EMPTY,
+        };
+        return new Promise((resolve, reject) => {
+            this.pending.set(promiseID, resolve);
+            try {
+                this.transport.send(buildRequest(c));
+            }
+            catch (err) {
+                this.pending.delete(promiseID);
+                reject(err instanceof Error ? err : new WebRpcError(String(err)));
+            }
+        });
+    }
+    /** Close the connection and fail all in-flight calls. */
+    close(code, reason) {
+        if (this.closed)
+            return;
+        this.transport.close(code, reason);
+        this.fail();
+    }
+    onFrame(bytes) {
+        if (this.handler) {
+            // Server side: every inbound frame is a request to dispatch.
+            this.dispatch(bytes);
+            return;
+        }
+        // Client side: every inbound frame is a response to one of our calls.
+        let resp;
+        try {
+            resp = parseResponse(bytes);
+        }
+        catch {
+            return; // malformed frame from peer — drop it.
+        }
+        const resolve = this.pending.get(resp.promiseID);
+        if (!resolve)
+            return;
+        this.pending.delete(resp.promiseID);
+        resolve(resp);
+    }
+    async dispatch(bytes) {
+        let call;
+        try {
+            call = parseRequest(bytes);
+        }
+        catch {
+            return; // unparseable request — drop it.
+        }
+        const handler = this.handler;
+        if (!handler)
+            return;
+        let resp;
+        try {
+            resp = await handler(call);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : "internal handler error";
+            resp = {
+                status: Status.Internal,
+                promiseID: call.promiseID,
+                body: new TextEncoder().encode(JSON.stringify({ error: msg })),
+            };
+        }
+        if (this.closed)
+            return;
+        try {
+            this.transport.send(buildResponse(resp.status, call.promiseID, resp.body));
+        }
+        catch {
+            // peer went away mid-response — nothing to do.
+        }
+    }
+    fail() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const [, resolve] of this.pending) {
+            resolve({
+                status: 0,
+                promiseID: 0,
+                body: new TextEncoder().encode(JSON.stringify({ error: "connection closed" })),
+            });
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=conn.js.map

package/dist/conn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conn.js","sourceRoot":"","sources":["../src/conn.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * errors.ts — error surface for the web RPC layer.
+ *
+ * Method/wire-level decode failures keep using @zap-proto/zap's ZapParseError (the
+ * runtime throws it on a bad magic/version/size); we re-export it so consumers
+ * have one import site. WebRpcError is new: it covers transport-level failures
+ * that only exist at the WebSocket boundary — a rejected upgrade, a socket that
+ * closes mid-call, or a non-OK RPC status surfaced to the caller.
+ */
+export { ZapParseError } from "@zap-proto/zap";
+/**
+ * WebRpcError is raised for WebSocket-transport-level failures: the upgrade was
+ * rejected (401/other), the socket closed while a call was in flight, or a
+ * call returned a non-OK ZAP status. `status` carries the ZAP/HTTP status when
+ * one is known (e.g. 401 for a rejected mint, or the response envelope status).
+ */
+export declare class WebRpcError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAK7C"}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// Copyright (C) 2025, Lux Industries Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+/**
+ * errors.ts — error surface for the web RPC layer.
+ *
+ * Method/wire-level decode failures keep using @zap-proto/zap's ZapParseError (the
+ * runtime throws it on a bad magic/version/size); we re-export it so consumers
+ * have one import site. WebRpcError is new: it covers transport-level failures
+ * that only exist at the WebSocket boundary — a rejected upgrade, a socket that
+ * closes mid-call, or a non-OK RPC status surfaced to the caller.
+ */
+export { ZapParseError } from "@zap-proto/zap";
+/**
+ * WebRpcError is raised for WebSocket-transport-level failures: the upgrade was
+ * rejected (401/other), the socket closed while a call was in flight, or a
+ * call returned a non-OK ZAP status. `status` carries the ZAP/HTTP status when
+ * one is known (e.g. 401 for a rejected mint, or the response envelope status).
+ */
+export class WebRpcError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "WebRpcError";
+        this.status = status;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,4CAA4C;AAE5C;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAU;IAEzB,YAAY,OAAe,EAAE,MAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}