@nice-code/action 0.14.0 → 0.16.0

package/README.md

@@ -1,582 +1,582 @@
-# @nice-code/action
-
-Typed, transport-agnostic action system for calling functions across client/server boundaries with full TypeScript inference.
-
-## Install
-
-```bash
-bun add @nice-code/action
-```
-
-Peer deps: `valibot` (or any [Standard Schema](https://github.com/standard-schema/standard-schema) library), `@tanstack/react-query` (for `@nice-code/action/react-query`).
-
-## Core concepts
-
-- **ActionDomain** — a named group of typed actions (like an API surface)
-- **ActionSchema** — input/output schema + declared error types for one action
-- **ActionRuntime** — one per client; processes incoming requests and dispatches them to handlers. Wire each backend it talks to with `runtime.connectTo(...)`
-- **ActionLocalHandler** — executes actions in the current process
-- **ActionExternalClientHandler** — forwards/receives actions over HTTP or WebSocket to another client
-- **ActionServerHandler** — server-side handler for backends accepting many client connections over one open channel; ferries results back and can push/broadcast server-initiated actions to clients
-- **RuntimeCoordinate** — identifies an environment (frontend, backend, worker…) and is how actions are routed
-
-> **One runtime per client.** A client (a frontend, a backend, a worker) has a *single* `ActionRuntime` identifying it across every peer it talks to — not one per feature or per backend. Register your local handlers on it, then call `runtime.connectTo(peerCoordinate, { transports, domains })` once per peer to wire the outbound channels. This keeps one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
-
----
-
-## Defining actions
-
-### 1. Create a root domain (shared between client and server)
-
-```ts
-import { createActionRootDomain, actionSchema } from "@nice-code/action";
-import * as v from "valibot";
-
-// Root domain — no actions, just a namespace anchor
-export const appRoot = createActionRootDomain({ domain: "app_root" });
-
-// Child domain with actions
-export const userDomain = appRoot.createChildDomain({
-  domain: "user",
-  actions: {
-    getUser: actionSchema()
-      .input({ schema: v.object({ userId: v.string() }) })
-      .output({ schema: v.object({ id: v.string(), name: v.string() }) })
-      .throws(err_user, ["not_found"]),  // from @nice-code/error
-
-    updateName: actionSchema()
-      .input({ schema: v.object({ userId: v.string(), name: v.string() }) })
-      .output({ schema: v.object({ success: v.boolean() }) }),
-  },
-});
-```
-
-### 2. Serialization for non-JSON-native types
-
-```ts
-createAt: actionSchema()
-  .output(
-    { schema: v.object({ createdAt: v.date() }) },
-    ({ createdAt }) => ({ createdAt: createdAt.toISOString() }),  // serialize
-    ({ createdAt }) => ({ createdAt: new Date(createdAt) }),       // deserialize
-  ),
-```
-
-### 3. Declare thrown errors
-
-```ts
-import { defineNiceError, err } from "@nice-code/error";
-
-const err_user = defineNiceError({
-  domain: "err_user",
-  schema: {
-    not_found: err<{ userId: string }>({
-      message: ({ userId }) => `User not found: ${userId}`,
-      httpStatusCode: 404,
-      context: { required: true },
-    }),
-  },
-} as const);
-
-// Attach to an action schema
-actionSchema()
-  .throws(err_user)                        // any id from err_user
-  .throws(err_user, ["not_found"])          // only specific ids
-```
-
----
-
-## Setting up runtimes
-
-### Server (local handler)
-
-```ts
-import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
-
-// Identify this environment
-export const serverCoord = RuntimeCoordinate.env("backend");
-
-// Implement the actions
-const userHandler = createLocalHandler()
-  .forDomain(userDomain, async (request) => {
-    if (request.id === "getUser") {
-      const user = await db.users.find(request.input.userId);
-      if (!user) throw err_user.fromId("not_found", { userId: request.input.userId });
-      return user;
-    }
-  });
-
-// Or use the map syntax (preferred)
-const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
-  getUser: async (req) => {
-    const user = await db.users.find(req.input.userId);
-    if (!user) throw err_user.fromId("not_found", { userId: req.input.userId });
-    return user;
-  },
-  updateName: async (req) => {
-    await db.users.update(req.input.userId, { name: req.input.name });
-    return { success: true };
-  },
-});
-
-// Or wrap an object directly
-const userHandler = userDomain.wrapAsLocalHandler({
-  getUser: async ({ userId }) => { /* ... */ },
-  updateName: async ({ userId, name }) => { /* ... */ },
-});
-
-// Wire up the runtime
-export const serverRuntime = new ActionRuntime(serverCoord)
-  .addHandlers([userHandler])
-  .apply();
-```
-
-### Handling incoming requests (HTTP endpoint)
-
-```ts
-// Hono example
-app.post("/resolve_action", async (c) => {
-  const wire = await c.req.json();
-  const runningAction = await serverRuntime.handleActionPayloadWire(wire);
-  const result = await runningAction.waitForResultPayload();
-  return c.json(result.toJsonObject());
-});
-```
-
-Or fold the whole endpoint (CORS + preflight, the `/action` POST, an optional WebSocket upgrade, and a
-404 fallback) into one web-standard `fetch` handler with `createActionFetchHandler`:
-
-```ts
-import { createActionFetchHandler } from "@nice-code/action";
-
-// Works anywhere Request/Response exist (Workers, Durable Objects, Bun, …).
-const fetchHandler = createActionFetchHandler(serverRuntime, {
-  // Omit for an HTTP-only endpoint. For a Durable Object:
-  onWebSocketUpgrade: () => {
-    const pair = new WebSocketPair();
-    ctx.acceptWebSocket(pair[1]);
-    return new Response(null, { status: 101, webSocket: pair[0] });
-  },
-});
-
-// async fetch(request) { return fetchHandler(request); }
-```
-
-By default a `POST` whose path ends in `/action` carries an action wire, and an `Upgrade: websocket`
-request whose path ends in `/ws` is upgraded; override with `isActionPath` / `isWebSocketPath`.
-
-### Client (connecting to a backend)
-
-A client has one runtime. Call `connectTo` once per backend it talks to: it builds the
-`ActionExternalClientHandler`, routes the listed `domains`/`actions` to it, registers it, and applies —
-all in one call.
-
-```ts
-import { ActionRuntime, RuntimeCoordinate, HttpTransport } from "@nice-code/action";
-
-export const clientCoord = RuntimeCoordinate.env("frontend");
-export const serverCoord = RuntimeCoordinate.env("backend");
-
-// The single runtime that identifies this client everywhere.
-export const clientRuntime = new ActionRuntime(clientCoord);
-
-// Transport definitions are plain, reusable objects you construct once.
-const serverHttp = HttpTransport.create({
-  createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
-});
-
-// Wire the backend — route the userDomain's actions over this transport.
-clientRuntime.connectTo(serverCoord, {
-  transports: [serverHttp],
-  domains: [userDomain],
-});
-
-// Connect to more backends on the same runtime as needed:
-// clientRuntime.connectTo(authCoord, { transports: [authWs], domains: [authDomain] });
-```
-
-`connectTo(peerCoordinate, options)` accepts:
-
-- `transports` — one or more transports, tried in declared order (first = preferred, e.g. a WebSocket; later = fallback, e.g. HTTP)
-- `domains` / `actions` — which domains (or individual actions) route to this peer
-- `localHandlers` — handlers that run *locally* on this same channel, e.g. to answer **server→client pushes** (see [Bi-directional communication](#bi-directional-communication-server--client))
-- `defaultTimeout` — default per-action timeout
-
-It returns the `ActionExternalClientHandler` so you can later `handler.clearTransportCache()` (which also
-closes any live sockets) on teardown.
-
-<details>
-<summary>What <code>connectTo</code> desugars to</summary>
-
-```ts
-const serverHandler = new ActionExternalClientHandler({
-  runtimeCoordinate: serverCoord,
-  transports: [serverHttp],
-}).forDomain(userDomain);
-
-clientRuntime.addHandlers([serverHandler]).apply();
-```
-</details>
-
----
-
-## Calling actions
-
-```ts
-// Create a request payload
-const request = userDomain.action.getUser.request({ userId: "u_123" });
-
-// Run it — returns a RunningAction
-const runningAction = await userDomain.runAction(request);
-
-// Wait for the result
-const result = await runningAction.waitForResultPayload();
-console.log(result.output); // { id: "u_123", name: "Alice" }
-
-// Or run and get the output directly (throws on error)
-const output = await userDomain.action.getUser
-  .request({ userId: "u_123" })
-  .runToOutput();
-```
-
----
-
-## Bi-directional communication (server ⇆ client)
-
-Actions flow both ways. The frontend calls the backend the way shown above; the **backend can call the
-frontend** over the *same* open connection — no second channel, no polling. This needs a duplex transport
-(a WebSocket), so both ends share one channel.
-
-The shape:
-
-- **Define the client-facing actions in their own domain**, shared by both ends (same as any other domain).
-- **On the client**, register a *local handler* for those actions and route them as `localHandlers` on the
-  `connectTo` channel — so when the server pushes a request, the client executes it locally and the result
-  is sent straight back over the same socket.
-- **On the server**, use an `ActionServerHandler` (one per connection-accepting channel). It ferries
-  results back to the originating socket automatically, and gives you `pushToClient` / `broadcast` to
-  initiate actions toward connected clients.
-
-### Shared domains
-
-```ts
-// Client implements these — the server pushes them.
-export const clientPushDomain = appRoot.createChildDomain({
-  domain: "client_push",
-  actions: {
-    notify: actionSchema()
-      .input({ schema: v.object({ text: v.string() }) })
-      .output({ schema: v.object({ seen: v.boolean() }) }),
-  },
-});
-
-// Server implements these — the client calls them (normal direction).
-export const gameDomain = appRoot.createChildDomain({
-  domain: "game",
-  actions: {
-    join: actionSchema()
-      .input({ schema: v.object({ roomId: v.string() }) })
-      .output({ schema: v.object({ ok: v.boolean() }) }),
-  },
-});
-```
-
-### Server side
-
-```ts
-import {
-  ActionRuntime,
-  RuntimeCoordinate,
-  createServerHandler,
-} from "@nice-code/action";
-
-const backendCoord = RuntimeCoordinate.env("backend");
-const clientEnv = RuntimeCoordinate.env("frontend"); // the env of connecting clients
-
-const serverRuntime = new ActionRuntime(backendCoord);
-
-// Handles inbound client→server actions locally.
-const gameHandler = gameDomain.wrapAsLocalHandler({
-  join: async ({ roomId }) => ({ ok: true }),
-});
-
-// Accepts many client connections over one channel; you tell it how to send a frame.
-const serverHandler = createServerHandler<WebSocket>({
-  clientEnv,
-  formatMessage: adapter, // e.g. createBinaryWsAdapter([gameDomain, clientPushDomain])
-  send: (ws, frame) => ws.send(frame),
-  runtime: serverRuntime, // lets broadcast() find the runtime without threading it through
-});
-
-serverRuntime.addHandlers([gameHandler, serverHandler]).apply();
-
-// Per inbound socket message (e.g. a Durable Object's webSocketMessage):
-//   serverHandler.receive(ws, message);
-// On close/error:
-//   serverHandler.dropConnection(ws);
-```
-
-Push a server-initiated action to a specific client (await its reply just like any action), or fan one
-out to everyone:
-
-```ts
-// One client — pass the connection token or the client's RuntimeCoordinate.
-const running = serverHandler.pushToClient(
-  serverRuntime,
-  ws,
-  clientPushDomain.action.notify.request({ text: "hi" }),
-);
-const result = await running.waitForResultPayload();
-console.log(result.output); // { seen: true }
-
-// Everyone currently connected (fire-and-forget); skip the origin, or filter with `where`.
-serverHandler.broadcast(() => clientPushDomain.action.notify.request({ text: "room update" }), {
-  except: originWs,
-  where: (ws) => ws.deserializeAttachment()?.role === "player",
-});
-```
-
-When an inbound client action needs the originating socket (to reply on it, register it in a room, etc.),
-use `forConnectionDomainCases` — each case receives the request *and* that client's live connection,
-saving the manual `getConnectionForClient(action.context.originClient)` lookup:
-
-```ts
-const gameCases = serverHandler.forConnectionDomainCases(gameDomain, {
-  join: ({ input }, conn) => {
-    if (conn != null) rooms.add(input.roomId, conn);
-    return { ok: conn != null };
-  },
-});
-
-serverRuntime.addHandlers([gameCases, serverHandler]).apply();
-```
-
-### Client side
-
-The client registers a local handler for the pushed actions and hands it to `connectTo` as a
-`localHandler` on the WebSocket channel. Results route back over the same socket automatically.
-
-```ts
-const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
-
-// Execute server→client pushes locally.
-const pushHandler = clientPushDomain.wrapAsLocalHandler({
-  notify: async ({ text }) => {
-    showToast(text);
-    return { seen: true };
-  },
-});
-
-clientRuntime.connectTo(backendCoord, {
-  transports: [gameWs], // a WebSocketTransport (duplex)
-  domains: [gameDomain], // client→server actions routed out over this socket
-  localHandlers: [pushHandler], // server→client pushes handled locally on the same socket
-});
-```
-
-### Durable Objects / hibernation
-
-For transports whose sockets outlive process eviction (e.g. a Durable Object's hibernatable
-WebSockets), pair the server handler with `createHibernatableWsServerAdapter`. It owns persistence:
-it stores each connection's binding on bind and replays them on construction, so results and pushes
-still route to the right socket after the object wakes.
-
-```ts
-import { createHibernatableWsServerAdapter } from "@nice-code/action";
-
-const wsServer = createHibernatableWsServerAdapter({
-  handler: serverHandler,
-  getWebSockets: () => ctx.getWebSockets(),
-  getAttachment: (ws) => ws.deserializeAttachment(),
-  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
-});
-
-// webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
-// webSocketClose/Error(ws) => wsServer.drop(ws);
-```
-
----
-
-## React Query integration
-
-```ts
-import { useActionQuery, useActionMutation } from "@nice-code/action/react-query";
-
-// Query
-function UserProfile({ userId }: { userId: string }) {
-  const { data } = useActionQuery(
-    userDomain.action.getUser,
-    { userId },
-    { queryKey: ["user", userId] },
-  );
-  return <div>{data?.name}</div>;
-}
-
-// Mutation
-function RenameUser() {
-  const { mutate } = useActionMutation(userDomain.action.updateName);
-  return <button onClick={() => mutate({ userId: "u_1", name: "Bob" })}>Rename</button>;
-}
-```
-
----
-
-## Devtools
-
-### Browser panel — `@nice-code/action/devtools/browser`
-
-A dockable in-app panel showing every action run: status, timing, input/output, routing, errors, and call stacks. Renders only when `NODE_ENV === "development"` (or with `forceEnable`).
-
-```tsx
-import { ActionDevtoolsCore, NiceActionDevtools } from "@nice-code/action/devtools/browser";
-
-const devtoolsCore = new ActionDevtoolsCore();
-devtoolsCore.attachToDomain(appRoot);
-
-function App() {
-  return (
-    <>
-      <MyApp />
-      <NiceActionDevtools core={devtoolsCore} position="dock-bottom" />
-    </>
-  );
-}
-```
-
-### Server logger — `@nice-code/action/devtools/server`
-
-Logs action lifecycle (started / progress / success / error) with timings — pretty lines or newline-delimited JSON.
-
-```ts
-import { ActionServerDevtools } from "@nice-code/action/devtools/server";
-
-const devtools = new ActionServerDevtools({ format: "json", logPayloads: false });
-devtools.attachToDomain(appRoot);
-```
-
----
-
-## WebSocket transport
-
-```ts
-import { ActionRuntime, WebSocketTransport, HttpTransport } from "@nice-code/action";
-
-const serverWs = WebSocketTransport.create({
-  createWebSocket: () => new WebSocket("wss://api.example.com/resolve_action/ws"),
-  getTransportCacheKey: () => ["wss://api.example.com/resolve_action/ws"],
-});
-
-// One channel, WebSocket preferred with HTTP as fallback.
-clientRuntime.connectTo(serverCoord, {
-  transports: [serverWs, serverHttp],
-  domains: [userDomain],
-});
-```
-
-The socket is opened lazily and reused across actions sharing a `getTransportCacheKey`. Multiple
-transports can be registered; the runtime picks the best available one (WebSocket preferred for lower
-latency, HTTP as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
-
-Each transport takes a single creation function so you decide how simple or complex it should be —
-derive the request per action straight from the params (e.g.
-`HttpTransport.create({ createRequest: (input) => ({ url: \`/api/${input.action.id}\` }) })`). For full
-control over readiness (support detection, async init), `WebSocketTransport` / `CustomTransport` also
-offer `.createAdvanced({ getTransport })`.
-
-A WebSocket is duplex, so it's also the channel the server pushes back over — see
-[Bi-directional communication](#bi-directional-communication-server--client).
-
-### Secure WebSocket channel
-
-For an authenticated (and optionally end-to-end encrypted) socket, define the channel once in shared
-code and hand it to both ends — the binary codec and wire-dictionary version can never drift apart. The
-client identifies itself with its runtime coordinate + a persisted crypto identity; the server pins
-client keys trust-on-first-use.
-
-```ts
-// shared.ts — both ends import this
-import { defineSecureWsChannel } from "@nice-code/action";
-
-// Domains in a stable order (the binary wire dictionary is positional — add new ones to the end).
-export const channel = defineSecureWsChannel({ domains: [userDomain, clientPushDomain] });
-```
-
-```ts
-// client.ts
-import { createSecureWebSocketTransport, ESecurityLevel } from "@nice-code/action";
-
-const secureWs = createSecureWebSocketTransport({
-  channel,
-  runtime: clientRuntime, // its coordinate is the authenticated identity in the handshake
-  storageAdapter, // persists this client's verify key across reloads (@nice-code/util)
-  securityLevel: ESecurityLevel.encrypted, // none | authenticated | encrypted
-  url: "wss://api.example.com/meta/ws",
-});
-
-clientRuntime.connectTo(serverCoord, {
-  transports: [secureWs, serverHttp], // secure WS preferred, HTTP fallback
-  domains: [userDomain],
-  localHandlers: [pushHandler], // server pushes ride the same secure socket
-});
-```
-
-```ts
-// server.ts (e.g. inside a Durable Object)
-import {
-  createSecureActionServerHandler,
-  createHibernatableWsServerAdapter,
-} from "@nice-code/action";
-
-const serverHandler = createSecureActionServerHandler<WebSocket>({
-  channel, // same shared channel
-  clientEnv, // env of the connecting clients
-  runtime: serverRuntime, // its coordinate is the server identity in the handshake
-  storageAdapter, // backs BOTH the server's identity and its TOFU key pins — use persistent storage
-  send: (ws, frame) => ws.send(frame),
-  // securityLevel defaults to negotiating any of none / authenticated / encrypted per connection
-});
-
-const wsServer = createHibernatableWsServerAdapter({
-  handler: serverHandler,
-  getWebSockets: () => ctx.getWebSockets(),
-  getAttachment: (ws) => ws.deserializeAttachment(),
-  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
-});
-```
-
-Security levels: `none` (self-asserted identity, fine for dev/trusted networks), `authenticated`
-(handshake-verified identity), `encrypted` (authenticated + per-connection AES-GCM payload encryption).
-A server can accept a negotiable set so a single endpoint serves all three. Persisting the channel's
-binding (via the hibernatable adapter) lets an `authenticated`/`encrypted` connection resume after the
-server is evicted without re-handshaking.
-
----
-
-## RuntimeCoordinate
-
-Identifies a runtime environment and is used to route actions to the right handler.
-
-```ts
-RuntimeCoordinate.env("backend")                   // named env
-RuntimeCoordinate.env("backend").specify({ perId: "worker-1" }) // env + instance
-RuntimeCoordinate.unknown                           // unspecified
-```
-
----
-
-## Error handling in actions
-
-Actions declared with `.throws(domain, ids?)` surface typed errors at the call site:
-
-```ts
-import { castNiceError } from "@nice-code/error";
-
-try {
-  const output = await userDomain.action.getUser.request({ userId }).runToOutput();
-} catch (e) {
-  const error = castNiceError(e);
-  if (err_user.isExact(error) && error.hasId("not_found")) {
-    console.log("User not found:", error.getContext("not_found").userId);
-  }
-}
-```
+# @nice-code/action
+
+Typed, transport-agnostic action system for calling functions across client/server boundaries with full TypeScript inference.
+
+## Install
+
+```bash
+bun add @nice-code/action
+```
+
+Peer deps: `valibot` (or any [Standard Schema](https://github.com/standard-schema/standard-schema) library), `@tanstack/react-query` (for `@nice-code/action/react-query`).
+
+## Core concepts
+
+- **ActionDomain** — a named group of typed actions (like an API surface)
+- **ActionSchema** — input/output schema + declared error types for one action
+- **ActionRuntime** — one per client; processes incoming requests and dispatches them to handlers. Wire each backend it talks to with `runtime.connectTo(...)`
+- **ActionLocalHandler** — executes actions in the current process
+- **ActionExternalClientHandler** — forwards/receives actions over HTTP or WebSocket to another client
+- **ActionServerHandler** — server-side handler for backends accepting many client connections over one open channel; ferries results back and can push/broadcast server-initiated actions to clients
+- **RuntimeCoordinate** — identifies an environment (frontend, backend, worker…) and is how actions are routed
+
+> **One runtime per client.** A client (a frontend, a backend, a worker) has a *single* `ActionRuntime` identifying it across every peer it talks to — not one per feature or per backend. Register your local handlers on it, then call `runtime.connectTo(peerCoordinate, { transports, domains })` once per peer to wire the outbound channels. This keeps one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
+
+---
+
+## Defining actions
+
+### 1. Create a root domain (shared between client and server)
+
+```ts
+import { createActionRootDomain, actionSchema } from "@nice-code/action";
+import * as v from "valibot";
+
+// Root domain — no actions, just a namespace anchor
+export const appRoot = createActionRootDomain({ domain: "app_root" });
+
+// Child domain with actions
+export const userDomain = appRoot.createChildDomain({
+  domain: "user",
+  actions: {
+    getUser: actionSchema()
+      .input({ schema: v.object({ userId: v.string() }) })
+      .output({ schema: v.object({ id: v.string(), name: v.string() }) })
+      .throws(err_user, ["not_found"]),  // from @nice-code/error
+
+    updateName: actionSchema()
+      .input({ schema: v.object({ userId: v.string(), name: v.string() }) })
+      .output({ schema: v.object({ success: v.boolean() }) }),
+  },
+});
+```
+
+### 2. Serialization for non-JSON-native types
+
+```ts
+createAt: actionSchema()
+  .output(
+    { schema: v.object({ createdAt: v.date() }) },
+    ({ createdAt }) => ({ createdAt: createdAt.toISOString() }),  // serialize
+    ({ createdAt }) => ({ createdAt: new Date(createdAt) }),       // deserialize
+  ),
+```
+
+### 3. Declare thrown errors
+
+```ts
+import { defineNiceError, err } from "@nice-code/error";
+
+const err_user = defineNiceError({
+  domain: "err_user",
+  schema: {
+    not_found: err<{ userId: string }>({
+      message: ({ userId }) => `User not found: ${userId}`,
+      httpStatusCode: 404,
+      context: { required: true },
+    }),
+  },
+} as const);
+
+// Attach to an action schema
+actionSchema()
+  .throws(err_user)                        // any id from err_user
+  .throws(err_user, ["not_found"])          // only specific ids
+```
+
+---
+
+## Setting up runtimes
+
+### Server (local handler)
+
+```ts
+import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
+
+// Identify this environment
+export const serverCoord = RuntimeCoordinate.env("backend");
+
+// Implement the actions
+const userHandler = createLocalHandler()
+  .forDomain(userDomain, async (request) => {
+    if (request.id === "getUser") {
+      const user = await db.users.find(request.input.userId);
+      if (!user) throw err_user.fromId("not_found", { userId: request.input.userId });
+      return user;
+    }
+  });
+
+// Or use the map syntax (preferred)
+const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
+  getUser: async (req) => {
+    const user = await db.users.find(req.input.userId);
+    if (!user) throw err_user.fromId("not_found", { userId: req.input.userId });
+    return user;
+  },
+  updateName: async (req) => {
+    await db.users.update(req.input.userId, { name: req.input.name });
+    return { success: true };
+  },
+});
+
+// Or wrap an object directly
+const userHandler = userDomain.wrapAsLocalHandler({
+  getUser: async ({ userId }) => { /* ... */ },
+  updateName: async ({ userId, name }) => { /* ... */ },
+});
+
+// Wire up the runtime
+export const serverRuntime = new ActionRuntime(serverCoord)
+  .addHandlers([userHandler])
+  .apply();
+```
+
+### Handling incoming requests (HTTP endpoint)
+
+```ts
+// Hono example
+app.post("/resolve_action", async (c) => {
+  const wire = await c.req.json();
+  const runningAction = await serverRuntime.handleActionPayloadWire(wire);
+  const result = await runningAction.waitForResultPayload();
+  return c.json(result.toJsonObject());
+});
+```
+
+Or fold the whole endpoint (CORS + preflight, the `/action` POST, an optional WebSocket upgrade, and a
+404 fallback) into one web-standard `fetch` handler with `createActionFetchHandler`:
+
+```ts
+import { createActionFetchHandler } from "@nice-code/action";
+
+// Works anywhere Request/Response exist (Workers, Durable Objects, Bun, …).
+const fetchHandler = createActionFetchHandler(serverRuntime, {
+  // Omit for an HTTP-only endpoint. For a Durable Object:
+  onWebSocketUpgrade: () => {
+    const pair = new WebSocketPair();
+    ctx.acceptWebSocket(pair[1]);
+    return new Response(null, { status: 101, webSocket: pair[0] });
+  },
+});
+
+// async fetch(request) { return fetchHandler(request); }
+```
+
+By default a `POST` whose path ends in `/action` carries an action wire, and an `Upgrade: websocket`
+request whose path ends in `/ws` is upgraded; override with `isActionPath` / `isWebSocketPath`.
+
+### Client (connecting to a backend)
+
+A client has one runtime. Call `connectTo` once per backend it talks to: it builds the
+`ActionExternalClientHandler`, routes the listed `domains`/`actions` to it, registers it, and applies —
+all in one call.
+
+```ts
+import { ActionRuntime, RuntimeCoordinate, HttpTransport } from "@nice-code/action";
+
+export const clientCoord = RuntimeCoordinate.env("frontend");
+export const serverCoord = RuntimeCoordinate.env("backend");
+
+// The single runtime that identifies this client everywhere.
+export const clientRuntime = new ActionRuntime(clientCoord);
+
+// Transport definitions are plain, reusable objects you construct once.
+const serverHttp = HttpTransport.create({
+  createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
+});
+
+// Wire the backend — route the userDomain's actions over this transport.
+clientRuntime.connectTo(serverCoord, {
+  transports: [serverHttp],
+  domains: [userDomain],
+});
+
+// Connect to more backends on the same runtime as needed:
+// clientRuntime.connectTo(authCoord, { transports: [authWs], domains: [authDomain] });
+```
+
+`connectTo(peerCoordinate, options)` accepts:
+
+- `transports` — one or more transports, tried in declared order (first = preferred, e.g. a WebSocket; later = fallback, e.g. HTTP)
+- `domains` / `actions` — which domains (or individual actions) route to this peer
+- `localHandlers` — handlers that run *locally* on this same channel, e.g. to answer **server→client pushes** (see [Bi-directional communication](#bi-directional-communication-server--client))
+- `defaultTimeout` — default per-action timeout
+
+It returns the `ActionExternalClientHandler` so you can later `handler.clearTransportCache()` (which also
+closes any live sockets) on teardown.
+
+<details>
+<summary>What <code>connectTo</code> desugars to</summary>
+
+```ts
+const serverHandler = new ActionExternalClientHandler({
+  runtimeCoordinate: serverCoord,
+  transports: [serverHttp],
+}).forDomain(userDomain);
+
+clientRuntime.addHandlers([serverHandler]).apply();
+```
+</details>
+
+---
+
+## Calling actions
+
+```ts
+// Create a request payload
+const request = userDomain.action.getUser.request({ userId: "u_123" });
+
+// Run it — returns a RunningAction
+const runningAction = await userDomain.runAction(request);
+
+// Wait for the result
+const result = await runningAction.waitForResultPayload();
+console.log(result.output); // { id: "u_123", name: "Alice" }
+
+// Or run and get the output directly (throws on error)
+const output = await userDomain.action.getUser
+  .request({ userId: "u_123" })
+  .runToOutput();
+```
+
+---
+
+## Bi-directional communication (server ⇆ client)
+
+Actions flow both ways. The frontend calls the backend the way shown above; the **backend can call the
+frontend** over the *same* open connection — no second channel, no polling. This needs a duplex transport
+(a WebSocket), so both ends share one channel.
+
+The shape:
+
+- **Define the client-facing actions in their own domain**, shared by both ends (same as any other domain).
+- **On the client**, register a *local handler* for those actions and route them as `localHandlers` on the
+  `connectTo` channel — so when the server pushes a request, the client executes it locally and the result
+  is sent straight back over the same socket.
+- **On the server**, use an `ActionServerHandler` (one per connection-accepting channel). It ferries
+  results back to the originating socket automatically, and gives you `pushToClient` / `broadcast` to
+  initiate actions toward connected clients.
+
+### Shared domains
+
+```ts
+// Client implements these — the server pushes them.
+export const clientPushDomain = appRoot.createChildDomain({
+  domain: "client_push",
+  actions: {
+    notify: actionSchema()
+      .input({ schema: v.object({ text: v.string() }) })
+      .output({ schema: v.object({ seen: v.boolean() }) }),
+  },
+});
+
+// Server implements these — the client calls them (normal direction).
+export const gameDomain = appRoot.createChildDomain({
+  domain: "game",
+  actions: {
+    join: actionSchema()
+      .input({ schema: v.object({ roomId: v.string() }) })
+      .output({ schema: v.object({ ok: v.boolean() }) }),
+  },
+});
+```
+
+### Server side
+
+```ts
+import {
+  ActionRuntime,
+  RuntimeCoordinate,
+  createServerHandler,
+} from "@nice-code/action";
+
+const backendCoord = RuntimeCoordinate.env("backend");
+const clientEnv = RuntimeCoordinate.env("frontend"); // the env of connecting clients
+
+const serverRuntime = new ActionRuntime(backendCoord);
+
+// Handles inbound client→server actions locally.
+const gameHandler = gameDomain.wrapAsLocalHandler({
+  join: async ({ roomId }) => ({ ok: true }),
+});
+
+// Accepts many client connections over one channel; you tell it how to send a frame.
+const serverHandler = createServerHandler<WebSocket>({
+  clientEnv,
+  formatMessage: adapter, // e.g. createBinaryWireAdapter([gameDomain, clientPushDomain])
+  send: (ws, frame) => ws.send(frame),
+  runtime: serverRuntime, // lets broadcast() find the runtime without threading it through
+});
+
+serverRuntime.addHandlers([gameHandler, serverHandler]).apply();
+
+// Per inbound socket message (e.g. a Durable Object's webSocketMessage):
+//   serverHandler.receive(ws, message);
+// On close/error:
+//   serverHandler.dropConnection(ws);
+```
+
+Push a server-initiated action to a specific client (await its reply just like any action), or fan one
+out to everyone:
+
+```ts
+// One client — pass the connection token or the client's RuntimeCoordinate.
+const running = serverHandler.pushToClient(
+  serverRuntime,
+  ws,
+  clientPushDomain.action.notify.request({ text: "hi" }),
+);
+const result = await running.waitForResultPayload();
+console.log(result.output); // { seen: true }
+
+// Everyone currently connected (fire-and-forget); skip the origin, or filter with `where`.
+serverHandler.broadcast(() => clientPushDomain.action.notify.request({ text: "room update" }), {
+  except: originWs,
+  where: (ws) => ws.deserializeAttachment()?.role === "player",
+});
+```
+
+When an inbound client action needs the originating socket (to reply on it, register it in a room, etc.),
+use `forConnectionDomainCases` — each case receives the request *and* that client's live connection,
+saving the manual `getConnectionForClient(action.context.originClient)` lookup:
+
+```ts
+const gameCases = serverHandler.forConnectionDomainCases(gameDomain, {
+  join: ({ input }, conn) => {
+    if (conn != null) rooms.add(input.roomId, conn);
+    return { ok: conn != null };
+  },
+});
+
+serverRuntime.addHandlers([gameCases, serverHandler]).apply();
+```
+
+### Client side
+
+The client registers a local handler for the pushed actions and hands it to `connectTo` as a
+`localHandler` on the WebSocket channel. Results route back over the same socket automatically.
+
+```ts
+const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
+
+// Execute server→client pushes locally.
+const pushHandler = clientPushDomain.wrapAsLocalHandler({
+  notify: async ({ text }) => {
+    showToast(text);
+    return { seen: true };
+  },
+});
+
+clientRuntime.connectTo(backendCoord, {
+  transports: [gameWs], // a WebSocketTransport (duplex)
+  domains: [gameDomain], // client→server actions routed out over this socket
+  localHandlers: [pushHandler], // server→client pushes handled locally on the same socket
+});
+```
+
+### Durable Objects / hibernation
+
+For transports whose sockets outlive process eviction (e.g. a Durable Object's hibernatable
+WebSockets), pair the server handler with `createHibernatableWsServerAdapter`. It owns persistence:
+it stores each connection's binding on bind and replays them on construction, so results and pushes
+still route to the right socket after the object wakes.
+
+```ts
+import { createHibernatableWsServerAdapter } from "@nice-code/action";
+
+const wsServer = createHibernatableWsServerAdapter({
+  handler: serverHandler,
+  getWebSockets: () => ctx.getWebSockets(),
+  getAttachment: (ws) => ws.deserializeAttachment(),
+  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
+});
+
+// webSocketMessage(ws, msg) => wsServer.receive(ws, msg);
+// webSocketClose/Error(ws) => wsServer.drop(ws);
+```
+
+---
+
+## React Query integration
+
+```ts
+import { useActionQuery, useActionMutation } from "@nice-code/action/react-query";
+
+// Query
+function UserProfile({ userId }: { userId: string }) {
+  const { data } = useActionQuery(
+    userDomain.action.getUser,
+    { userId },
+    { queryKey: ["user", userId] },
+  );
+  return <div>{data?.name}</div>;
+}
+
+// Mutation
+function RenameUser() {
+  const { mutate } = useActionMutation(userDomain.action.updateName);
+  return <button onClick={() => mutate({ userId: "u_1", name: "Bob" })}>Rename</button>;
+}
+```
+
+---
+
+## Devtools
+
+### Browser panel — `@nice-code/action/devtools/browser`
+
+A dockable in-app panel showing every action run: status, timing, input/output, routing, errors, and call stacks. Renders only when `NODE_ENV === "development"` (or with `forceEnable`).
+
+```tsx
+import { ActionDevtoolsCore, NiceActionDevtools } from "@nice-code/action/devtools/browser";
+
+const devtoolsCore = new ActionDevtoolsCore();
+devtoolsCore.attachToDomain(appRoot);
+
+function App() {
+  return (
+    <>
+      <MyApp />
+      <NiceActionDevtools core={devtoolsCore} position="dock-bottom" />
+    </>
+  );
+}
+```
+
+### Server logger — `@nice-code/action/devtools/server`
+
+Logs action lifecycle (started / progress / success / error) with timings — pretty lines or newline-delimited JSON.
+
+```ts
+import { ActionServerDevtools } from "@nice-code/action/devtools/server";
+
+const devtools = new ActionServerDevtools({ format: "json", logPayloads: false });
+devtools.attachToDomain(appRoot);
+```
+
+---
+
+## WebSocket transport
+
+```ts
+import { ActionRuntime, WebSocketTransport, HttpTransport } from "@nice-code/action";
+
+const serverWs = WebSocketTransport.create({
+  createWebSocket: () => new WebSocket("wss://api.example.com/resolve_action/ws"),
+  getTransportCacheKey: () => ["wss://api.example.com/resolve_action/ws"],
+});
+
+// One channel, WebSocket preferred with HTTP as fallback.
+clientRuntime.connectTo(serverCoord, {
+  transports: [serverWs, serverHttp],
+  domains: [userDomain],
+});
+```
+
+The socket is opened lazily and reused across actions sharing a `getTransportCacheKey`. Multiple
+transports can be registered; the runtime picks the best available one (WebSocket preferred for lower
+latency, HTTP as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
+
+Each transport takes a single creation function so you decide how simple or complex it should be —
+derive the request per action straight from the params (e.g.
+`HttpTransport.create({ createRequest: (input) => ({ url: \`/api/${input.action.id}\` }) })`). For full
+control over readiness (support detection, async init), `WebSocketTransport` / `CustomTransport` also
+offer `.createAdvanced({ getTransport })`.
+
+A WebSocket is duplex, so it's also the channel the server pushes back over — see
+[Bi-directional communication](#bi-directional-communication-server--client).
+
+### Secure WebSocket channel
+
+For an authenticated (and optionally end-to-end encrypted) socket, define the channel once in shared
+code and hand it to both ends — the binary codec and wire-dictionary version can never drift apart. The
+client identifies itself with its runtime coordinate + a persisted crypto identity; the server pins
+client keys trust-on-first-use.
+
+```ts
+// shared.ts — both ends import this
+import { defineSecureWsChannel } from "@nice-code/action";
+
+// Domains in a stable order (the binary wire dictionary is positional — add new ones to the end).
+export const channel = defineSecureWsChannel({ domains: [userDomain, clientPushDomain] });
+```
+
+```ts
+// client.ts
+import { createSecureWebSocketTransport, ESecurityLevel } from "@nice-code/action";
+
+const secureWs = createSecureWebSocketTransport({
+  channel,
+  runtime: clientRuntime, // its coordinate is the authenticated identity in the handshake
+  storageAdapter, // persists this client's verify key across reloads (@nice-code/util)
+  securityLevel: ESecurityLevel.encrypted, // none | authenticated | encrypted
+  url: "wss://api.example.com/meta/ws",
+});
+
+clientRuntime.connectTo(serverCoord, {
+  transports: [secureWs, serverHttp], // secure WS preferred, HTTP fallback
+  domains: [userDomain],
+  localHandlers: [pushHandler], // server pushes ride the same secure socket
+});
+```
+
+```ts
+// server.ts (e.g. inside a Durable Object)
+import {
+  createSecureActionServerHandler,
+  createHibernatableWsServerAdapter,
+} from "@nice-code/action";
+
+const serverHandler = createSecureActionServerHandler<WebSocket>({
+  channel, // same shared channel
+  clientEnv, // env of the connecting clients
+  runtime: serverRuntime, // its coordinate is the server identity in the handshake
+  storageAdapter, // backs BOTH the server's identity and its TOFU key pins — use persistent storage
+  send: (ws, frame) => ws.send(frame),
+  // securityLevel defaults to negotiating any of none / authenticated / encrypted per connection
+});
+
+const wsServer = createHibernatableWsServerAdapter({
+  handler: serverHandler,
+  getWebSockets: () => ctx.getWebSockets(),
+  getAttachment: (ws) => ws.deserializeAttachment(),
+  setAttachment: (ws, binding) => ws.serializeAttachment(binding),
+});
+```
+
+Security levels: `none` (self-asserted identity, fine for dev/trusted networks), `authenticated`
+(handshake-verified identity), `encrypted` (authenticated + per-connection AES-GCM payload encryption).
+A server can accept a negotiable set so a single endpoint serves all three. Persisting the channel's
+binding (via the hibernatable adapter) lets an `authenticated`/`encrypted` connection resume after the
+server is evicted without re-handshaking.
+
+---
+
+## RuntimeCoordinate
+
+Identifies a runtime environment and is used to route actions to the right handler.
+
+```ts
+RuntimeCoordinate.env("backend")                   // named env
+RuntimeCoordinate.env("backend").specify({ perId: "worker-1" }) // env + instance
+RuntimeCoordinate.unknown                           // unspecified
+```
+
+---
+
+## Error handling in actions
+
+Actions declared with `.throws(domain, ids?)` surface typed errors at the call site:
+
+```ts
+import { castNiceError } from "@nice-code/error";
+
+try {
+  const output = await userDomain.action.getUser.request({ userId }).runToOutput();
+} catch (e) {
+  const error = castNiceError(e);
+  if (err_user.isExact(error) && error.hasId("not_found")) {
+    console.log("User not found:", error.getContext("not_found").userId);
+  }
+}
+```