@nice-code/action 0.18.0 → 0.20.0

package/README.md

@@ -1,637 +1,699 @@
-# @nice-code/action
-
-Typed, transport-agnostic action system for calling functions across runtime boundaries (client/server,
-worker/worker, peer/peer) with full TypeScript inference — including **bi-directional** calls where the
-acceptor pushes actions back over the same connection.
-
-## 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`).
-
----
-
-## Mental model
-
-One sentence: **a `runtime` links to a `peer` over a `carrier`, and the routing between them is declared
-once as a `channel`.** Identity, auth, and encryption work the same regardless of carrier — the only
-distinctions that survive every carrier are:
-
-- **role** — who dials (**connector**) vs who accepts and can push back (**acceptor**).
-- **shape** — **duplex** (a WebSocket / WebRTC channel: push-capable, the return path for results and
-  server pushes) vs **exchange** (HTTP: one request, one reply).
-
-The pieces:
-
-| Concept | What it is |
-| --- | --- |
-| **ActionDomain** | A named group of typed actions (your API surface) |
-| **ActionSchema** | Input/output schema + declared error types for one action |
-| **ActionRuntime** | One per runtime; identifies it and dispatches actions to handlers |
-| **Channel** | The transport-agnostic routing contract between two runtimes, declared *by role* (`toAcceptor` / `toConnector`) — `defineChannel` (plain) or `defineSecureChannel` (binary + encryption) |
-| **Carrier** | How bytes actually move: `wsCarrier` / `httpCarrier` / `inMemoryCarrier` / `rtcCarrier` (connector side), `wsAcceptorCarrier` / `httpAcceptorCarrier` (acceptor side) |
-| **Transport** | A carrier wrapped with a security policy: `secureTransport` (handshake + optional encryption) or `plainTransport` |
-| **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 `connectChannel(...)` once per peer (or `serveChannel(...)` to accept). This keeps
-> one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
-
-The high-level entry points — `connectChannel` (dial out) and `serveChannel` (accept) — are what you
-reach for 95% of the time. The lower-level handler/carrier/transport objects they desugar to are
-documented at the end under [Lower-level building blocks](#lower-level-building-blocks).
-
----
-
-## Defining actions
-
-### 1. Create a root domain (shared between both ends)
-
-```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
-```
-
----
-
-## Channels — the routing contract
-
-A **channel** declares what flows in each direction between two runtimes, *by role*, so both ends derive
-their routing from one shared definition instead of restating domain lists:
-
-- **`toAcceptor`** — domains the connector *sends to* the acceptor (the classic "request").
-- **`toConnector`** — domains the acceptor *pushes back to* the connector (the classic "push"). A domain
-  can appear in both lists if it's bidirectional.
-
-Define it once in code shared by both ends:
-
-```ts
-// shared.ts — both ends import this
-import { defineChannel } from "@nice-code/action";
-
-export const appChannel = defineChannel({
-  toAcceptor: [userDomain],   // client → server requests
-  toConnector: [],            // server → client pushes (none here)
-});
-```
-
-For an authenticated/encrypted binary WebSocket, use **`defineSecureChannel`** instead — same role-based
-shape, plus it bakes in the positional binary wire dictionary and a version derived from the domains, so
-the codec and version can never drift between the two ends:
-
-```ts
-import { defineSecureChannel } from "@nice-code/action";
-
-export const appChannel = defineSecureChannel({
-  toAcceptor: [userDomain, lobbyDomain],  // requests
-  toConnector: [lobbyDomain],             // pushes (lobbyDomain is bidirectional)
-});
-```
-
-> The lists are **positional** for the binary wire dictionary — **add new domains to the end** of their
-> list. Reordering shifts the version, and a stale peer is then cleanly rejected by the handshake instead
-> of silently misrouting a frame.
-
-A secure channel is still an ordinary channel, so it works anywhere a channel is expected.
-
----
-
-## Runtimes & handlers
-
-### Local execution (the acceptor's actual work)
-
-A **local handler** runs actions in the current process. Build one and register it on the runtime; this
-is what answers incoming requests.
-
-```ts
-import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
-
-export const serverCoord = RuntimeCoordinate.env("backend");
-
-// Map syntax (preferred)
-const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
-  getUser: async (action) => {
-    const user = await db.users.find(action.input.userId);
-    if (!user) throw err_user.fromId("not_found", { userId: action.input.userId });
-    return user;
-  },
-  updateName: async (action) => {
-    await db.users.update(action.input.userId, { name: action.input.name });
-    return { success: true };
-  },
-});
-
-// Or one action at a time
-const userHandler2 = createLocalHandler()
-  .forAction(userDomain.action.getUser, async ({ input }) => db.users.find(input.userId));
-
-// Or wrap an object directly off the domain
-const userHandler3 = userDomain.wrapAsLocalHandler({
-  getUser: async ({ userId }) => { /* ... */ },
-  updateName: async ({ userId, name }) => { /* ... */ },
-});
-```
-
-`wrapAsPartialLocalHandler` is the same but lets you implement only *some* of a domain's actions (useful
-for local-first clients that resolve a few actions themselves and forward the rest).
-
-### Accepting connections — `serveChannel`
-
-`serveChannel` is the one call that stands up an acceptor: it builds the crypto identity **once**, fans it
-across every carrier, registers your handlers, wires hibernation, and returns a server object whose
-`fetch` / `duplex` / `pushToClient` you forward straight to the host.
-
-```ts
-import {
-  ActionRuntime,
-  RuntimeCoordinate,
-  serveChannel,
-  wsAcceptorCarrier,
-  httpAcceptorCarrier,
-} from "@nice-code/action";
-
-const runtime = new ActionRuntime(serverCoord);
-
-const server = serveChannel(runtime, appChannel, {
-  clientEnv: RuntimeCoordinate.env("frontend"), // env of the connecting clients
-  storage: storageAdapter,                       // backs identity + TOFU key pins (persistent)
-  handlers: [userHandler],                        // your local execution
-  carriers: [
-    wsAcceptorCarrier({ send: (ws, frame) => ws.send(frame), /* upgrade, hibernation */ }),
-    httpAcceptorCarrier(),                         // HTTP fallback (same channel)
-  ],
-});
-
-// Wire the host's events to the server:
-//   fetch(req)                     => server.fetch(req)
-//   webSocketMessage(ws, msg)      => server.duplex?.receive(ws, msg)
-//   webSocketClose/Error(ws)       => server.duplex?.drop(ws)
-```
-
-`serveChannel(runtime, channel, options)` returns `{ handlers, fetch, duplex?, pushToClient }`:
-
-- **`fetch`** — a web-standard handler that does the WS upgrade, the (secure or plain) HTTP action POST,
-  CORS preflight, and a `404` fallback. Forward the host's `fetch` straight to it.
-- **`duplex`** — the `{ receive, drop }` lifecycle for the *sole* duplex carrier (a shortcut for the
-  common single-WebSocket case; `undefined` when there are zero or several — then feed each carrier
-  handle directly).
-- **`pushToClient(target, request, opts?)`** — push a server-initiated action to one connected client
-  (see [Bi-directional](#bi-directional-communication-acceptor--connector)).
-- **`handlers`** — the acceptor handlers it built, one per duplex carrier (reach for these for per-handler
-  `broadcast`).
-
-Key options: `clientEnv` (required), `storage` (required only when a carrier is secure — the default),
-`carriers`, `handlers`, plus `securityLevel` / `link` / `verifyKeyResolver` / `defaultTimeout`.
-
-> On Cloudflare, [`@nice-code/action/platform/cloudflare`](#cloudflare-durable-objects) collapses the
-> Durable Object carrier + storage boilerplate to one-liners.
-
-### Connecting — `connectChannel`
-
-The connector has one runtime and `connectChannel`s to each acceptor it talks to. It routes the channel's
-`toAcceptor` domains out over the transports (first = preferred, rest = fallback) and registers local
-handlers for the `toConnector` pushes from `onPush` — all derived from the channel, no restated lists.
-
-```ts
-import {
-  ActionRuntime,
-  RuntimeCoordinate,
-  ESecurityLevel,
-  connectChannel,
-  secureTransport,
-  plainTransport,
-  wsCarrier,
-  httpCarrier,
-} from "@nice-code/action";
-
-export const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
-
-// A carrier wrapped in a security policy = a transport.
-const wsTransport = secureTransport({
-  channel: appChannel,
-  runtime: clientRuntime,        // its coordinate is the authenticated identity in the handshake
-  storageAdapter,                // persists this client's crypto identity across reloads
-  securityLevel: ESecurityLevel.encrypted,
-  carrier: wsCarrier("wss://api.example.com/resolve_action/ws"),
-});
-const httpTransport = plainTransport({
-  carrier: httpCarrier(() => ({ url: "https://api.example.com/resolve_action" })),
-});
-
-connectChannel(clientRuntime, serverCoord, {
-  channel: appChannel,
-  transports: [wsTransport, httpTransport], // secure WS preferred, HTTP fallback
-  // onPush: { ... }  // handlers for the channel's toConnector pushes (see below)
-});
-```
-
-`connectChannel(runtime, acceptorCoordinate, options)` returns the `ConnectorHandler` so you can later
-`handler.clearTransportCache()` (which also closes any live sockets) on teardown. Options:
-
-- **`channel`** — the shared channel; its `toAcceptor`/`toConnector` drive all routing.
-- **`transports`** — to the acceptor, in preference order; all carry the same `toAcceptor` domains and the
-  manager falls through on failure.
-- **`onPush`** — handlers for the channel's `toConnector` pushes (optional; omit for send-only).
-- **`defaultTimeout`** — default per-action timeout.
-
----
-
-## Calling actions
-
-Once a runtime is wired, calling an action looks the same regardless of where it resolves (locally or
-over a carrier):
-
-```ts
-// Run and get the output directly (throws on a declared/transport error)
-const output = await userDomain.action.getUser
-  .request({ userId: "u_123" })
-  .runToOutput();
-console.log(output); // { id: "u_123", name: "Alice" }
-
-// Or keep the RunningAction handle for progress/abort, then await the full result payload
-const running = await userDomain.runAction(userDomain.action.getUser.request({ userId: "u_123" }));
-const result = await running.waitForResultPayload();
-console.log(result.output);
-```
-
----
-
-## Bi-directional communication (acceptor ⇆ connector)
-
-Over a **duplex** carrier (a WebSocket) the acceptor can call the connector back on the *same* open
-connection — no second channel, no polling. The shape:
-
-1. **Declare the push domain in the channel's `toConnector`** (shared by both ends).
-2. **On the connector**, handle those pushes with `connectChannel`'s `onPush` — keyed by action id,
-   typed from the channel. The reply routes straight back over the same socket.
-3. **On the acceptor**, use `server.pushToClient(...)` (one client) or a handler's `broadcast(...)`
-   (everyone). The originating client is available on any inbound action as
-   `action.context.originClient`.
-
-### Shared channel
-
-```ts
-// Bidirectional: client sends `start_feed`; server pushes `position_update` back.
-export const lobbyDomain = appRoot.createChildDomain({
-  domain: "lobby",
-  actions: {
-    start_feed: actionSchema()
-      .input({ schema: v.object({ count: v.number() }) })
-      .output({ schema: v.object({ delivered: v.number() }) }),
-    position_update: actionSchema()
-      .input({ schema: v.object({ player: v.string(), x: v.number(), y: v.number() }) })
-      .output({ schema: v.object({ acknowledged: v.boolean() }) }),
-  },
-});
-
-export const appChannel = defineSecureChannel({
-  toAcceptor: [userDomain, lobbyDomain],  // start_feed flows here
-  toConnector: [lobbyDomain],             // position_update pushes back here
-});
-```
-
-### Connector side — handle pushes with `onPush`
-
-```ts
-connectChannel(clientRuntime, serverCoord, {
-  channel: appChannel,
-  transports: [wsTransport, httpTransport],
-  onPush: {
-    // Keyed by the toConnector action id; input + output typed from the channel.
-    position_update: async ({ player, x, y }) => {
-      renderPlayer(player, x, y);
-      return { acknowledged: true };
-    },
-  },
-});
-```
-
-### Acceptor side — push back
-
-The local handler reads `action.context.originClient` to know who asked, then pushes to them:
-
-```ts
-const lobbyHandler = createLocalHandler().forDomainActionCases(lobbyDomain, {
-  start_feed: async (action) => {
-    let delivered = 0;
-    for (let seq = 0; seq < action.input.count; seq++) {
-      const running = server.pushToClient(
-        action.context.originClient,                // the requesting client's coordinate
-        lobbyDomain.action.position_update.request({ player: "alice", x: 1, y: 2 }),
-      );
-      await running.waitForResultPayload(); // await the client's ack like any action
-      delivered++;
-    }
-    return { delivered };
-  },
-});
-```
-
-Fan one out to everyone on a carrier with a handler's `broadcast` (fire-and-forget; skip the origin or
-filter by connection):
-
-```ts
-server.handlers[0].broadcast(
-  () => lobbyDomain.action.position_update.request({ player: "system", x: 0, y: 0 }),
-  { except: originWs, where: (ws) => ws.deserializeAttachment()?.role === "player" },
-);
-```
-
-> **When a handler needs the originating connection itself** (to register it in a room, etc.) rather than
-> just the client coordinate, build connection-aware cases with `acceptChannelConnections(handler,
-> channel, { ... })` — each case receives the request *and* that client's live connection. See
-> [Lower-level building blocks](#lower-level-building-blocks).
-
----
-
-## Cloudflare Durable Objects
-
-`@nice-code/action/platform/cloudflare` collapses the DO boilerplate (the `WebSocketPair` upgrade, the
-hibernation attachment wiring, and the DO-storage adapter) into one-liners you hand to `serveChannel`.
-The core library stays platform-agnostic — nothing here is reachable from the main entry.
-
-```ts
-import { DurableObject } from "cloudflare:workers";
-import { ActionRuntime, serveChannel, httpAcceptorCarrier } from "@nice-code/action";
-import {
-  durableObjectWsCarrier,
-  durableObjectStorage,
-  type TDurableObjectChannelServer,
-} from "@nice-code/action/platform/cloudflare";
-
-export class MyDurableObject extends DurableObject {
-  private _server: TDurableObjectChannelServer | null = null;
-
-  private getServer(): TDurableObjectChannelServer {
-    if (this._server != null) return this._server;
-    const runtime = new ActionRuntime(serverCoord);
-
-    // One WS carrier (duplex — pushes + hibernation persistence) + a secure HTTP fallback (exchange),
-    // both sharing one crypto identity built from this DO's storage, surviving eviction.
-    this._server = serveChannel(runtime, appChannel, {
-      clientEnv: RuntimeCoordinate.env("frontend"),
-      storage: durableObjectStorage(this.ctx, { keyPrefix: "ws:" }),
-      handlers: [userHandler],
-      carriers: [durableObjectWsCarrier(this.ctx), httpAcceptorCarrier()],
-    });
-    return this._server;
-  }
-
-  async fetch(request: Request): Promise<Response> {
-    return this.getServer().fetch(request);
-  }
-  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
-    this.getServer().duplex?.receive(ws, msg);
-  }
-  async webSocketClose(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
-  async webSocketError(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
-}
-```
-
-- **`durableObjectWsCarrier(ctx, { secure? })`** — a hibernatable-WebSocket acceptor carrier with `send`,
-  the `WebSocketPair` upgrade, and the hibernation hooks all derived from the DO's `ctx`. Pass
-  `secure: false` for a plain WS endpoint (then no `storage` is needed for it).
-- **`durableObjectStorage(ctx, { keyPrefix? })`** — wraps the DO's storage as a `StorageAdapter` for
-  `serveChannel`'s `storage`.
-
-Because the WS carrier persists each connection's binding on bind and replays it on construction, results
-and pushes still route to the right socket after the object wakes from eviction.
-
----
-
-## Security levels
-
-`ESecurityLevel` (used by `secureTransport` and `serveChannel`):
-
-- **`none`** — identity self-asserted, no handshake. Fastest; fine for dev/trusted networks.
-- **`authenticated`** — the handshake verifies identity (sign/verify + trust-on-first-use key pin);
-  frames are unencrypted.
-- **`encrypted`** — authenticated *plus* every frame AES-GCM encrypted with the handshake-derived key.
-
-The connector picks its level; an acceptor by default **negotiates any of the three per connection**, so
-one endpoint serves all three. The client identifies itself with its runtime coordinate + a persisted
-crypto identity; the server pins client keys trust-on-first-use. Persisting the server's binding (via the
-hibernatable carrier) lets an `authenticated`/`encrypted` connection resume after eviction without
-re-handshaking.
-
-The whole thing rides one channel: the same `secureTransport({ carrier: wsCarrier(...) })` works at any
-level, and `httpCarrier` runs the *same* secure session over HTTP (handshake → token → encrypted frames),
-with the request/reply correlation provided for free by the HTTP transaction. Pair a secure WS with a
-plain HTTP fallback by giving the acceptor a `httpAcceptorCarrier({ secure: false })`.
-
----
-
-## Multiple carriers on one runtime
-
-`serveChannel` accepts **any number of duplex carriers** (e.g. WebSocket + WebRTC) plus at most one
-exchange carrier. They all share one crypto identity and one runtime, and each result/push routes back
-over the carrier its client actually connected on (connection-aware return routing). With several duplex
-carriers, `server.duplex` is `undefined` — feed each carrier handle's own `receive`/`drop` directly.
-
-```ts
-const ws  = wsAcceptorCarrier({ send: wsSend, upgrade, hibernation });
-const rtc = rtcCarrier(/* ... */);
-const server = serveChannel(runtime, appChannel, {
-  clientEnv, storage,
-  carriers: [ws, rtc, httpAcceptorCarrier()],
-  handlers: [appHandler],
-});
-// route each host's events to the matching handle:
-//   onWsMessage(c, m)  => ws.receive(c, m)
-//   onRtcMessage(c, m) => rtc.receive(c, m)
-```
-
-On the connector side, list several transports in `connectChannel`'s `transports` (preference order) to
-get automatic fallback across carriers (e.g. secure WS, then plain HTTP).
-
----
-
-## 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);
-```
-
----
-
-## 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.env("backend").withPersistentId(id.toString()) // env + persistent instance id
-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);
-  }
-}
-```
-
----
-
-## Lower-level building blocks
-
-`connectChannel` and `serveChannel` are sugar; reach for these when you need finer control.
-
-- **`ActionRuntime.connectTo(coordinate, { transports, domains, actions, localHandlers, defaultTimeout })`**
-  — what `connectChannel` desugars to: build a `ConnectorHandler` for a peer, route domains/actions to
-  it, register it (plus any local push handlers), and apply — in one call. Use it directly when your
-  routing isn't expressed as a single channel.
-
-- **Carriers vs transports.** A *carrier* (`wsCarrier`, `httpCarrier`, `inMemoryCarrier`, `rtcCarrier`) is
-  raw byte movement; a *transport* (`secureTransport`, `plainTransport`) wraps one with a security policy.
-  `connectTo` takes transports; `serveChannel` takes acceptor carriers (`wsAcceptorCarrier`,
-  `httpAcceptorCarrier`) and applies the security policy itself.
-
-- **`acceptChannel(runtime, channel, { clientEnv, storageAdapter, send, ... })`** — build the secure
-  `AcceptorHandler` for a channel by hand (the accept-in counterpart to a single transport), when you're
-  not using `serveChannel`. Pair it with **`acceptChannelConnections(handler, channel, cases)`** to
-  register connection-aware execution — each case receives the request *and* the originating connection:
-
-  ```ts
-  const acceptor = acceptChannel(runtime, appChannel, { clientEnv, storageAdapter, send });
-  const cases = acceptChannelConnections(acceptor, appChannel, {
-    join: ({ input }, conn) => { if (conn != null) rooms.add(input.roomId, conn); return { ok: true }; },
-  });
-  runtime.addHandlers([cases, acceptor]).apply();
-  ```
-
-- **`createActionFetchHandler(runtime, options)`** — the web-standard `fetch` handler (CORS, action POST,
-  optional WS upgrade, 404) on its own, when you want the HTTP entry without `serveChannel`.
-
-- **`createHibernatableWsServerAdapter({ handler, getConnections, getAttachment, setAttachment })`** —
-  the hibernation persistence layer `serveChannel` wires automatically; use it directly with a hand-built
-  `AcceptorHandler`.
-
-- **`createBinaryWireAdapter(domains)`** / **`createBinaryWireSessionFactory(domains)`** — the positional
-  binary codecs `defineSecureChannel` builds for you; useful for custom carriers.
-
-- **`createInMemoryChannelPair()` / `inMemoryCarrier`** — wire two runtimes together in-process (tests,
-  same-process peers) with no network.
-
-- **Custom carriers** — for any channel nice-action doesn't model natively, implement an
-  `IDuplexCarrierSource` / `IExchangeCarrierSource` and hand it to `secureTransport` / `plainTransport`
-  (connector) or build an acceptor carrier for `serveChannel`.
+# @nice-code/action
+
+Typed, transport-agnostic action system for calling functions across runtime boundaries (client/server,
+worker/worker, peer/peer) with full TypeScript inference — including **bi-directional** calls where the
+acceptor pushes actions back over the same connection.
+
+## 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`).
+
+---
+
+## Mental model
+
+One sentence: **a `runtime` links to a `peer` over a `carrier`, and the routing between them is declared
+once as a `channel`.** Identity, auth, and encryption work the same regardless of carrier — the only
+distinctions that survive every carrier are:
+
+- **role** — who dials (**connector**) vs who accepts and can push back (**acceptor**).
+- **shape** — **duplex** (a WebSocket / WebRTC channel: push-capable, the return path for results and
+  server pushes) vs **exchange** (HTTP: one request, one reply).
+
+The pieces:
+
+| Concept | What it is |
+| --- | --- |
+| **ActionDomain** | A named group of typed actions (your API surface) |
+| **ActionSchema** | Input/output schema + declared error types for one action |
+| **ActionRuntime** | One per runtime; identifies it and dispatches actions to handlers |
+| **Channel** | The transport-agnostic routing contract between two runtimes, declared *by role* (`toAcceptor` / `toConnector`) — `defineChannel` (plain) or `defineSecureChannel` (binary + encryption) |
+| **Carrier** | How bytes actually move: `wsCarrier` / `httpCarrier` / `inMemoryCarrier` / `rtcCarrier` (connector side), `wsAcceptorCarrier` / `httpAcceptorCarrier` (acceptor side) |
+| **Transport** | A carrier wrapped with a security policy: `secureTransport` (handshake + optional encryption) or `plainTransport` |
+| **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 `connectChannel(...)` once per peer (or `serveChannel(...)` to accept). This keeps
+> one identity (and one crypto identity, for secure channels) per client and avoids routing ambiguity.
+
+The high-level entry points — `connectChannel` (dial out) and `serveChannel` (accept) — are what you
+reach for 95% of the time. The lower-level handler/carrier/transport objects they desugar to are
+documented at the end under [Lower-level building blocks](#lower-level-building-blocks).
+
+---
+
+## Defining actions
+
+### 1. Create a root domain (shared between both ends)
+
+```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
+```
+
+---
+
+## Channels — the routing contract
+
+A **channel** declares what flows in each direction between two runtimes, *by role*, so both ends derive
+their routing from one shared definition instead of restating domain lists:
+
+- **`toAcceptor`** — domains the connector *sends to* the acceptor (the classic "request").
+- **`toConnector`** — domains the acceptor *pushes back to* the connector (the classic "push"). A domain
+  can appear in both lists if it's bidirectional.
+
+Define it once in code shared by both ends:
+
+```ts
+// shared.ts — both ends import this
+import { defineChannel } from "@nice-code/action";
+
+export const appChannel = defineChannel({
+  toAcceptor: [userDomain],   // client → server requests
+  toConnector: [],            // server → client pushes (none here)
+});
+```
+
+For an authenticated/encrypted binary WebSocket, use **`defineSecureChannel`** instead — same role-based
+shape, plus it bakes in the positional binary wire dictionary and a version derived from the domains, so
+the codec and version can never drift between the two ends:
+
+```ts
+import { defineSecureChannel } from "@nice-code/action";
+
+export const appChannel = defineSecureChannel({
+  toAcceptor: [userDomain, lobbyDomain],  // requests
+  toConnector: [lobbyDomain],             // pushes (lobbyDomain is bidirectional)
+});
+```
+
+> The lists are **positional** for the binary wire dictionary — **add new domains to the end** of their
+> list. Reordering shifts the version, and a stale peer is then cleanly rejected by the handshake instead
+> of silently misrouting a frame.
+
+A secure channel is still an ordinary channel, so it works anywhere a channel is expected.
+
+---
+
+## Runtimes & handlers
+
+### Local execution (the acceptor's actual work)
+
+A **local handler** runs actions in the current process. Build one and register it on the runtime; this
+is what answers incoming requests.
+
+```ts
+import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
+
+export const serverCoord = RuntimeCoordinate.env("backend");
+
+// Map syntax (preferred)
+const userHandler = createLocalHandler().forDomainActionCases(userDomain, {
+  getUser: async (action) => {
+    const user = await db.users.find(action.input.userId);
+    if (!user) throw err_user.fromId("not_found", { userId: action.input.userId });
+    return user;
+  },
+  updateName: async (action) => {
+    await db.users.update(action.input.userId, { name: action.input.name });
+    return { success: true };
+  },
+});
+
+// Or one action at a time
+const userHandler2 = createLocalHandler()
+  .forAction(userDomain.action.getUser, async ({ input }) => db.users.find(input.userId));
+
+// Or wrap an object directly off the domain
+const userHandler3 = userDomain.wrapAsLocalHandler({
+  getUser: async ({ userId }) => { /* ... */ },
+  updateName: async ({ userId, name }) => { /* ... */ },
+});
+```
+
+`wrapAsPartialLocalHandler` is the same but lets you implement only *some* of a domain's actions (useful
+for local-first clients that resolve a few actions themselves and forward the rest).
+
+### Accepting connections — `serveChannel`
+
+`serveChannel` is the one call that stands up an acceptor: it builds the crypto identity **once**, fans it
+across every carrier, registers your handlers, wires hibernation, and returns a server object whose
+`fetch` / `duplex` / `pushToClient` you forward straight to the host.
+
+```ts
+import {
+  ActionRuntime,
+  RuntimeCoordinate,
+  serveChannel,
+  wsAcceptorCarrier,
+  httpAcceptorCarrier,
+} from "@nice-code/action";
+
+const runtime = new ActionRuntime(serverCoord);
+
+const server = serveChannel(runtime, appChannel, {
+  clientEnv: RuntimeCoordinate.env("frontend"), // env of the connecting clients
+  storage: storageAdapter,                       // backs identity + TOFU key pins (persistent)
+  handlers: [userHandler],                        // your local execution
+  carriers: [
+    wsAcceptorCarrier({ send: (ws, frame) => ws.send(frame), /* upgrade, attachmentStore */ }),
+    httpAcceptorCarrier(),                         // HTTP fallback (same channel)
+  ],
+});
+
+// Wire the host's events to the server:
+//   fetch(req)                     => server.fetch(req)
+//   webSocketMessage(ws, msg)      => server.duplex?.receive(ws, msg)
+//   webSocketClose/Error(ws)       => server.duplex?.drop(ws)
+```
+
+`serveChannel(runtime, channel, options)` returns `{ handlers, fetch, duplex?, pushToClient }`:
+
+- **`fetch`** — a web-standard handler that does the WS upgrade, the (secure or plain) HTTP action POST,
+  CORS preflight, and a `404` fallback. Forward the host's `fetch` straight to it.
+- **`duplex`** — the `{ receive, drop }` lifecycle for the *sole* duplex carrier (a shortcut for the
+  common single-WebSocket case; `undefined` when there are zero or several — then feed each carrier
+  handle directly).
+- **`pushToClient(target, request, opts?)`** — push a server-initiated action to one connected client
+  (see [Bi-directional](#bi-directional-communication-acceptor--connector)).
+- **`handlers`** — the acceptor handlers it built, one per duplex carrier (reach for these for per-handler
+  `broadcast`).
+
+Key options: `clientEnv` (required), `storage` (required only when a carrier is secure — the default),
+`carriers`, `handlers`, plus `securityLevel` / `link` / `verifyKeyResolver` / `defaultTimeout`.
+
+> On Cloudflare, [`@nice-code/action/platform/cloudflare`](#cloudflare-durable-objects) collapses the
+> Durable Object carrier + storage boilerplate to one-liners.
+
+### Connecting — `connectChannel`
+
+The connector has one runtime and `connectChannel`s to each acceptor it talks to. It routes the channel's
+`toAcceptor` domains out over the transports (first = preferred, rest = fallback) and registers local
+handlers for the `toConnector` pushes from `onPush` — all derived from the channel, no restated lists.
+
+```ts
+import {
+  ActionRuntime,
+  RuntimeCoordinate,
+  ESecurityLevel,
+  connectChannel,
+  secureTransport,
+  plainTransport,
+  wsCarrier,
+  httpCarrier,
+} from "@nice-code/action";
+
+export const clientRuntime = new ActionRuntime(RuntimeCoordinate.env("frontend"));
+
+// A carrier wrapped in a security policy = a transport.
+const wsTransport = secureTransport({
+  channel: appChannel,
+  runtime: clientRuntime,        // its coordinate is the authenticated identity in the handshake
+  storageAdapter,                // persists this client's crypto identity across reloads
+  securityLevel: ESecurityLevel.encrypted,
+  carrier: wsCarrier("wss://api.example.com/resolve_action/ws"),
+});
+const httpTransport = plainTransport({
+  carrier: httpCarrier(() => ({ url: "https://api.example.com/resolve_action" })),
+});
+
+connectChannel(clientRuntime, serverCoord, {
+  channel: appChannel,
+  transports: [wsTransport, httpTransport], // secure WS preferred, HTTP fallback
+  // onPush: { ... }  // handlers for the channel's toConnector pushes (see below)
+});
+```
+
+`connectChannel(runtime, acceptorCoordinate, options)` returns the `ConnectorHandler` so you can later
+`handler.clearTransportCache()` (which also closes any live sockets) on teardown. Options:
+
+- **`channel`** — the shared channel; its `toAcceptor`/`toConnector` drive all routing.
+- **`transports`** — to the acceptor, in preference order; all carry the same `toAcceptor` domains and the
+  manager falls through on failure.
+- **`onPush`** — handlers for the channel's `toConnector` pushes (optional; omit for send-only).
+- **`defaultTimeout`** — default per-action timeout.
+
+---
+
+## Calling actions
+
+Once a runtime is wired, calling an action looks the same regardless of where it resolves (locally or
+over a carrier):
+
+```ts
+// Run and get the output directly (throws on a declared/transport error)
+const output = await userDomain.action.getUser
+  .request({ userId: "u_123" })
+  .runToOutput();
+console.log(output); // { id: "u_123", name: "Alice" }
+
+// Or keep the RunningAction handle for progress/abort, then await the full result payload
+const running = await userDomain.runAction(userDomain.action.getUser.request({ userId: "u_123" }));
+const result = await running.waitForResultPayload();
+console.log(result.output);
+```
+
+---
+
+## Bi-directional communication (acceptor ⇆ connector)
+
+Over a **duplex** carrier (a WebSocket) the acceptor can call the connector back on the *same* open
+connection — no second channel, no polling. The shape:
+
+1. **Declare the push domain in the channel's `toConnector`** (shared by both ends).
+2. **On the connector**, handle those pushes with `connectChannel`'s `onPush` — keyed by action id,
+   typed from the channel. The reply routes straight back over the same socket.
+3. **On the acceptor**, use `server.pushToClient(...)` (one client) or a handler's `broadcast(...)`
+   (everyone). The originating client is available on any inbound action as
+   `action.context.originClient`.
+
+### Shared channel
+
+```ts
+// Bidirectional: client sends `start_feed`; server pushes `position_update` back.
+export const lobbyDomain = appRoot.createChildDomain({
+  domain: "lobby",
+  actions: {
+    start_feed: actionSchema()
+      .input({ schema: v.object({ count: v.number() }) })
+      .output({ schema: v.object({ delivered: v.number() }) }),
+    position_update: actionSchema()
+      .input({ schema: v.object({ player: v.string(), x: v.number(), y: v.number() }) })
+      .output({ schema: v.object({ acknowledged: v.boolean() }) }),
+  },
+});
+
+export const appChannel = defineSecureChannel({
+  toAcceptor: [userDomain, lobbyDomain],  // start_feed flows here
+  toConnector: [lobbyDomain],             // position_update pushes back here
+});
+```
+
+### Connector side — handle pushes with `onPush`
+
+```ts
+connectChannel(clientRuntime, serverCoord, {
+  channel: appChannel,
+  transports: [wsTransport, httpTransport],
+  onPush: {
+    // Keyed by the toConnector action id; input + output typed from the channel.
+    position_update: async ({ player, x, y }) => {
+      renderPlayer(player, x, y);
+      return { acknowledged: true };
+    },
+  },
+});
+```
+
+### Acceptor side — push back
+
+The local handler reads `action.context.originClient` to know who asked, then pushes to them:
+
+```ts
+const lobbyHandler = createLocalHandler().forDomainActionCases(lobbyDomain, {
+  start_feed: async (action) => {
+    let delivered = 0;
+    for (let seq = 0; seq < action.input.count; seq++) {
+      const running = server.pushToClient(
+        action.context.originClient,                // the requesting client's coordinate
+        lobbyDomain.action.position_update.request({ player: "alice", x: 1, y: 2 }),
+      );
+      await running.waitForResultPayload(); // await the client's ack like any action
+      delivered++;
+    }
+    return { delivered };
+  },
+});
+```
+
+Fan one out to everyone on the sole duplex carrier with `server.broadcast` (fire-and-forget; skip the
+origin or filter by connection):
+
+```ts
+server.broadcast(
+  () => lobbyDomain.action.position_update.request({ player: "system", x: 0, y: 0 }),
+  { except: originWs, where: (ws) => server.connections.get(ws)?.role === "player" },
+);
+```
+
+> **When a handler needs the originating connection itself** (to register it in a room, etc.) rather than
+> just the client coordinate, pass `channelCases` to `serveChannel` — each case receives the request *and*
+> that client's live connection. With several duplex carriers (no sole handler), reach for a specific
+> `server.handlers[i].broadcast(...)` and `acceptChannelConnections(handler, channel, { ... })` directly
+> (see [Lower-level building blocks](#lower-level-building-blocks)).
+
+---
+
+## Cloudflare Durable Objects
+
+`@nice-code/action/platform/cloudflare` collapses the DO boilerplate (the `WebSocketPair` upgrade, the
+hibernation attachment wiring, and the DO-storage adapter) into one-liners you hand to `serveChannel`.
+The core library stays platform-agnostic — nothing here is reachable from the main entry.
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+import { ActionRuntime, serveChannel, httpAcceptorCarrier } from "@nice-code/action";
+import {
+  durableObjectWsCarrier,
+  durableObjectStorage,
+  type TDurableObjectChannelServer,
+} from "@nice-code/action/platform/cloudflare";
+
+export class MyDurableObject extends DurableObject {
+  private _server: TDurableObjectChannelServer | null = null;
+
+  private getServer(): TDurableObjectChannelServer {
+    if (this._server != null) return this._server;
+    const runtime = new ActionRuntime(serverCoord);
+
+    // One WS carrier (duplex — pushes + hibernation persistence) + a secure HTTP fallback (exchange),
+    // both sharing one crypto identity built from this DO's storage, surviving eviction.
+    this._server = serveChannel(runtime, appChannel, {
+      clientEnv: RuntimeCoordinate.env("frontend"),
+      storage: durableObjectStorage(this.ctx, { keyPrefix: "ws:" }),
+      handlers: [userHandler],
+      carriers: [durableObjectWsCarrier(this.ctx), httpAcceptorCarrier()],
+    });
+    return this._server;
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    return this.getServer().fetch(request);
+  }
+  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
+    this.getServer().duplex?.receive(ws, msg);
+  }
+  async webSocketClose(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
+  async webSocketError(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
+}
+```
+
+- **`durableObjectWsCarrier(ctx, { secure? })`** — a hibernatable-WebSocket acceptor carrier with `send`,
+  the `WebSocketPair` upgrade, and the socket-attachment access all derived from the DO's `ctx`. Pass
+  `secure: false` for a plain WS endpoint (then no `storage` is needed for it). It exposes the attachment to
+  `serveChannel`, which owns the layout: it persists the routing binding there and (when `connectionState`
+  is requested) co-stores per-connection app state in the *same* slot, so both survive eviction.
+- **`durableObjectStorage(ctx, { keyPrefix? })`** — wraps the DO's storage as a `StorageAdapter` for
+  `serveChannel`'s `storage`.
+
+### Per-connection state + broadcast (stateful DOs)
+
+A presence/room DO that tracks who's on each socket and fans messages out adds two `serveChannel` knobs —
+no `handlers[0]`, no hand-wired attachment store:
+
+```ts
+const server = serveChannel(runtime, lobbyChannel, {
+  clientEnv: RuntimeCoordinate.env("web"),
+  storage: durableObjectStorage(this.ctx, { keyPrefix: "lobby-ws:" }),
+  carriers: [durableObjectWsCarrier(this.ctx), httpAcceptorCarrier({ secure: false })],
+  // Co-store each player's identity with the routing binding in the socket attachment (survives a wake).
+  connectionState: { schema: vs_player },
+  // Connection-aware cases: each gets the request + the originating socket.
+  channelCases: {
+    join: (action, ws) => {
+      if (ws) server.connections.set(ws, action.input); // typed by the schema
+      server.broadcast(() => lobbyPush.action.player_joined.request(action.input), { except: ws });
+      return { players: this.roster() };
+    },
+  },
+});
+
+// Rebuild in-memory state from surviving sockets after a wake (binding replay is automatic):
+for (const [, player] of server.connections.entries()) this.players.set(player.id, player);
+```
+
+`connectionState` narrows the return so `server.connections` is non-optional, and `server.broadcast`
+fans out over the sole duplex carrier. The store's `read`/`write` are pluggable, so a DO that prefers to
+keep state in its SQLite/KV storage rather than the socket attachment can supply its own.
+
+Because the WS carrier persists each connection's binding on bind and replays it on construction, results
+and pushes still route to the right socket after the object wakes from eviction.
+
+---
+
+## Security levels
+
+`ESecurityLevel` (used by `secureTransport` and `serveChannel`):
+
+- **`none`** — identity self-asserted, no handshake. Fastest; fine for dev/trusted networks.
+- **`authenticated`** — the handshake verifies identity (sign/verify + trust-on-first-use key pin);
+  frames are unencrypted.
+- **`encrypted`** — authenticated *plus* every frame AES-GCM encrypted with the handshake-derived key.
+
+The connector picks its level; an acceptor by default **negotiates any of the three per connection**, so
+one endpoint serves all three. The client identifies itself with its runtime coordinate + a persisted
+crypto identity; the server pins client keys trust-on-first-use. Persisting the server's binding (via the
+hibernatable carrier) lets an `authenticated`/`encrypted` connection resume after eviction without
+re-handshaking.
+
+The whole thing rides one channel: the same `secureTransport({ carrier: wsCarrier(...) })` works at any
+level, and `httpCarrier` runs the *same* secure session over HTTP (handshake → token → encrypted frames),
+with the request/reply correlation provided for free by the HTTP transaction. Pair a secure WS with a
+plain HTTP fallback by giving the acceptor a `httpAcceptorCarrier({ secure: false })`.
+
+---
+
+## Multiple carriers on one runtime
+
+`serveChannel` accepts **any number of duplex carriers** (e.g. WebSocket + WebRTC) plus at most one
+exchange carrier. They all share one crypto identity and one runtime, and each result/push routes back
+over the carrier its client actually connected on (connection-aware return routing). With several duplex
+carriers, `server.duplex` is `undefined` — feed each carrier handle's own `receive`/`drop` directly.
+
+```ts
+const ws  = wsAcceptorCarrier({ send: wsSend, upgrade, attachmentStore });
+const rtc = rtcCarrier(/* ... */);
+const server = serveChannel(runtime, appChannel, {
+  clientEnv, storage,
+  carriers: [ws, rtc, httpAcceptorCarrier()],
+  handlers: [appHandler],
+});
+// route each host's events to the matching handle:
+//   onWsMessage(c, m)  => ws.receive(c, m)
+//   onRtcMessage(c, m) => rtc.receive(c, m)
+```
+
+On the connector side, list several transports in `connectChannel`'s `transports` (preference order) to
+get automatic fallback across carriers (e.g. secure WS, then plain HTTP).
+
+### Gating a transport until a precondition holds — `available`
+
+A transport can declare an `available` predicate to opt **out** of selection until a runtime precondition
+is met. While it returns `false`, the manager treats that transport as `unsupported` and falls through to
+the next one in preference order — **without** opening its carrier or even computing its cache key. The
+predicate is re-evaluated per action dispatch, so the transport switches on the moment the precondition
+holds, with no reconnect.
+
+```ts
+// Prefer the secure socket, but only once a session id exists; fall back to HTTP meanwhile.
+const wsTransport = secureTransport({
+  channel, runtime, storageAdapter, securityLevel,
+  available: () => sessionId != null,
+  carrier: wsCarrier(`${url}/ws`, {
+    // Only ever called once `available` passes, so no need for a placeholder cache key.
+    getTransportCacheKey: () => [sessionId],
+  }),
+});
+
+connectChannel(runtime, serverCoord, {
+  transports: [wsTransport, httpTransport], // ws preferred; HTTP serves while ws is gated off
+});
+```
+
+Flipping `available` back to `false` only **skips selection** — it does not tear down a live carrier
+(socket closure stays owned by the carrier's own disconnect handling), and a still-cached connection is
+reused with no reconnect once it becomes available again. Omit `available` for an always-available
+transport (the default).
+
+---
+
+## 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);
+```
+
+---
+
+## 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.env("backend").withPersistentId(id.toString()) // env + persistent instance id
+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);
+  }
+}
+```
+
+---
+
+## Lower-level building blocks
+
+`connectChannel` and `serveChannel` are sugar; reach for these when you need finer control.
+
+- **`ActionRuntime.connectTo(coordinate, { transports, domains, actions, localHandlers, defaultTimeout })`**
+  — what `connectChannel` desugars to: build a `ConnectorHandler` for a peer, route domains/actions to
+  it, register it (plus any local push handlers), and apply — in one call. Use it directly when your
+  routing isn't expressed as a single channel.
+
+- **Carriers vs transports.** A *carrier* (`wsCarrier`, `httpCarrier`, `inMemoryCarrier`, `rtcCarrier`) is
+  raw byte movement; a *transport* (`secureTransport`, `plainTransport`) wraps one with a security policy.
+  `connectTo` takes transports; `serveChannel` takes acceptor carriers (`wsAcceptorCarrier`,
+  `httpAcceptorCarrier`) and applies the security policy itself.
+
+- **`acceptChannel(runtime, channel, { clientEnv, storageAdapter, send, ... })`** — build the secure
+  `AcceptorHandler` for a channel by hand (the accept-in counterpart to a single transport), when you're
+  not using `serveChannel`. Pair it with **`acceptChannelConnections(handler, channel, cases)`** to
+  register connection-aware execution — each case receives the request *and* the originating connection:
+
+  ```ts
+  const acceptor = acceptChannel(runtime, appChannel, { clientEnv, storageAdapter, send });
+  const cases = acceptChannelConnections(acceptor, appChannel, {
+    join: ({ input }, conn) => { if (conn != null) rooms.add(input.roomId, conn); return { ok: true }; },
+  });
+  runtime.addHandlers([cases, acceptor]).apply();
+  ```
+
+- **`createActionFetchHandler(runtime, options)`** — the web-standard `fetch` handler (CORS, action POST,
+  optional WS upgrade, 404) on its own, when you want the HTTP entry without `serveChannel`.
+
+- **`createHibernatableWsServerAdapter({ handler, getConnections, getAttachment, setAttachment })`** —
+  the hibernation persistence layer `serveChannel` wires automatically; use it directly with a hand-built
+  `AcceptorHandler`.
+
+- **`createBinaryWireAdapter(domains)`** / **`createBinaryWireSessionFactory(domains)`** — the positional
+  binary codecs `defineSecureChannel` builds for you; useful for custom carriers.
+
+- **`createInMemoryChannelPair()` / `inMemoryCarrier`** — wire two runtimes together in-process (tests,
+  same-process peers) with no network.
+
+- **Custom carriers** — for any channel nice-action doesn't model natively, implement an
+  `IDuplexCarrierSource` / `IExchangeCarrierSource` and hand it to `secureTransport` / `plainTransport`
+  (connector) or build an acceptor carrier for `serveChannel`.