@abide/abide 0.45.0 → 0.47.0

package/AGENTS.md

@@ -1,420 +1,465 @@
 # AGENTS.md — abide complete surface map
 
-> The exhaustive index of abide's public surface: every `exports` key appears
-> once, grouped by namespace, with its import specifier and a one-line spec.
-> This is the whole-API read; the README is the curated 3-primitive intro.
-> CONTEXT.md is the glossary, `docs/adr/` the rationale.
-
-**No barrels.** Every public name has its own module path
-(`abide/server/GET`, `abide/shared/cache`, `abide/ui/scope`) — there is no
-umbrella `index.ts`, so importing one name never drags side-effecting siblings
-into the bundle. The namespace marks the side a name runs on: `abide/server/*`
-is server-only, `abide/ui/*` is client-only, `abide/shared/*` is isomorphic
-(same callable, same behaviour on both sides; the bundler swaps the runtime).
-
-Package: `@abide/abide`, one runtime (Bun `>=1.3.0`), one direct dependency
-(TypeScript). The bullets below name each export by its import specifier in the
-`abide/…` shorthand — the published package is `@abide/abide`, so
-`abide/server/GET` imports from `@abide/abide/server/GET`. These are import
-specifiers, not source file paths.
+> This file is the exhaustive public-surface map of `@abide/abide`: every
+> `exports` key, grouped by namespace, with its import specifier and a one-line
+> spec. The README is the curated three-primitive intro; `CONTEXT.md` is the
+> domain glossary; `docs/adr/` holds the rationale behind decisions. Ground
+> rules: there are **no barrels** — every public name has its own module path,
+> and the namespace marks the side it runs on (`abide/server/*` server-only,
+> `abide/ui/*` client-only, `abide/shared/*` isomorphic — same callable, same
+> behavior on both sides). Package `@abide/abide`, runtime Bun ≥ 1.3, one
+> direct dependency (TypeScript). Import specifiers below are `exports`-map
+> keys (`@abide/abide/server/GET`), not source file paths.
 
 ## The premise
 
-One typed RPC declaration fans out to every surface:
+One typed declaration fans out to every surface:
 
 ```text
-                  export const getMessages = GET(fn, { inputSchema })
-                                     │
-       ┌───────────────┬─────────────┼─────────────┬───────────────┐
-       ▼               ▼             ▼             ▼               ▼
-   SSR call       browser fetch   MCP tool     CLI command     OpenAPI op
- cache(fn)()     typed proxy    (read-only)   getMessages …  /openapi.json
- (in-process)    (swapped fn())
+src/server/rpc/getMessages.ts
+      │
+      ├─ SSR / server   await getMessages({ room })  in-process, no HTTP
+      ├─ browser        await getMessages({ room })  typed fetch proxy
+      ├─ HTTP           GET /rpc/getMessages?room=…
+      ├─ CLI            my-app get-messages --room …
+      ├─ MCP            tool: get-messages
+      └─ OpenAPI        operation in /openapi.json
 ```
 
-A schema makes the handler safe to advertise off-browser: it turns the CLI on
-for any method and auto-exposes read-only methods (`GET`/`HEAD`) as MCP tools.
-A mutating method (`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to MCP — it
-needs an explicit `clients: { mcp: true }`. Explicit `clients` always wins.
+An `inputSchema` (any Standard Schema library — zod, valibot, arktype,
+unadapted) is the gate: it unlocks the CLI, and for read-only methods
+(GET/HEAD) the MCP tool. A mutating method (POST/PUT/PATCH/DELETE) never
+auto-exposes to MCP — it requires explicit `clients: { mcp: true }`.
 
 ## File-based conventions
 
-The bundler reads meaning from these paths (the project's own `src/`, not the
-package):
-
 | Path | Meaning |
 | --- | --- |
-| `src/server/rpc/<name>.ts` | One RPC; export name = file stem, URL = `/rpc/<path>` |
-| `src/server/sockets/<name>.ts` | One socket; export name = file stem, name = path |
-| `src/mcp/prompts/<name>.md` | An MCP prompt (front-matter + `{{placeholder}}` body) |
-| `src/server/config.ts` | Eager-imported config module (the `env()` call site) |
-| `src/app.ts` | Optional `AppModule` hooks (`init`/`handle`/`handleError`/`health`) |
-| `src/bundle/window.ts` | Default-exported `BundleWindow` (desktop bundle config) |
-| `src/ui/pages/**/page.abide` | A route; its URL is the folder path (`[name]` dynamic) |
-| `src/ui/pages/**/layout.abide` | A layout; wraps the chain below via its outlet |
-| `src/ui/public/` | Static assets, gzip-embedded and served at root |
-| `src/.abide/*.d.ts` | Generated type augmentations (routes, rpc, sockets, health) |
-| `dist/_app/` | Client build output |
+| `src/server/rpc/<name>.ts` | One RPC per file; the export name must match the file stem; the file path becomes the URL `/rpc/<name>` (subdirectories nest into the path) |
+| `src/server/sockets/<name>.ts` | One broadcast socket per file; export name = file stem = topic name |
+| `src/mcp/prompts/<name>.md` | An MCP prompt template; `{{arg}}` placeholders become the prompt's arguments |
+| `src/mcp/resources/**` | Files served as MCP resources (gzip-embedded into builds) |
+| `src/server/config.ts` | Boot-time `env()` validation; eager-imported so a bad environment fails the boot |
+| `src/app.ts` | Optional `AppModule` hooks: `init`, `handle`, `handleError`, `health`, `forwardHeaders` |
+| `src/bundle/window.ts` | Optional `BundleWindow` default export configuring the desktop bundle's window and menus |
+| `src/ui/pages/**/page.abide` | A routed page; the directory path is the route — a `[id]` folder is a path param, `[[id]]` an optional param, `[...rest]` a catch-all |
+| `src/ui/pages/**/layout.abide` | A layout wrapping the pages below it; its `{children()}` is the router outlet |
+| `src/ui/public/` | Static assets served as-is |
+| `src/.abide/*.d.ts` | Generated typing (rpc args for `url()`, page routes, health fields, test rpc/socket clients, public asset paths) |
+| `dist/` | Build output — `dist/_app` client bundle, `dist/cli-thin/<platform>/` CLI tarballs |
+
+Project import aliases resolve to the five top-level source dirs: `$server`,
+`$ui`, `$shared`, `$mcp`, `$cli` (e.g. `$server/rpc/getMessages`,
+`$ui/pages/...`). `$server/rpc/*` and `$server/sockets/*` are proxied into
+client bundles; any other `$server/*` import from client code is a
+side-crossing error.
 
 ## CLI
 
 | Command | Does |
 | --- | --- |
-| `bunx abide scaffold <name>` | Scaffold a project, install, start dev (`--no-install` / `--no-dev` opt out; non-TTY never auto-starts) |
-| `abide dev` | Build the client + run the server with hot reload (rebuild/restart on `src/` changes) |
-| `abide build` | One client build into `dist/_app/` (no server) |
-| `abide start` | Run the production server against a built `dist/` |
-| `abide check` | Type-check every `.abide` template + props; non-zero exit on errors |
-| `abide run <file> [args]` | Run a script under the abide preload (same runtime as the server) |
-| `abide compile [--target] [--out]` | Build a standalone server executable |
-| `abide cli [--target] [--out] [--platforms]` | Build the thin CLI binary (ships the server beside it) |
-| `abide bundle` | Build a movable, self-contained desktop app bundle (unsigned) |
-| `abide lsp` | Run the `.abide` language server over stdio (editor diagnostics) |
-| `abide init-agent` | Write/refresh a root `CLAUDE.md` pointer to this surface map |
-
-For `bun test`, add `preload = ["@abide/abide/preload"]` under `[test]` in
-`bunfig.toml`.
+| `bunx abide scaffold <name>` | Scaffolds the bundled template, installs it, and (interactive TTY only) starts the dev server; `--no-install` / `--no-dev` opt out |
+| `abide dev` | Dev orchestrator: builds the client, runs the server as a child, watches `src/`, rebuilds + restarts on change, live-reloads the browser |
+| `abide build` | One-shot client build into `dist/_app` (CI / static deploys) |
+| `abide start` | Runs the production server against an already-built `dist/` |
+| `abide run <file> [args...]` | Runs any script under the abide preload — same runtime as the server (`.abide` compilation, `abide/*` + `$` alias resolution) |
+| `abide compile [--target=…] [--out=…]` | Compiles a standalone server executable (client assets embedded) |
+| `abide cli [--target=…] [--out=…] [--platforms=a,b,c]` | Builds the thin CLI binary (rpc manifest baked in) that talks to a remote server or starts a local one; `--platforms` cross-compiles into `dist/cli-thin/<platform>/` |
+| `abide bundle` | Assembles a movable, self-contained desktop app bundle (server binary + launcher + webview) for the host platform; unsigned |
+| `abide check` | Type-checks every `.abide` component's template + props through its shadow; non-zero exit on errors |
+| `abide lsp` | Runs the `.abide` language server over stdio (JSON-RPC) for editor diagnostics |
+| `abide init-agent` | Writes/refreshes the CLAUDE.md pointer to this surface map for non-scaffolded projects |
+
+For tests, add `preload = ["@abide/abide/preload"]` under `[test]` in
+`bunfig.toml` and use `bun test`.
 
 ## Authoring contracts
 
-**RPC** (`src/server/rpc/<name>.ts`) — `export const <name> = METHOD(handler, opts?)`.
-The handler receives `InferOutput<inputSchema>` (or the bare arg type when
-schemaless), reads `request()` / `cookies()` for request scope, and returns a
-`json` / `jsonl` / `sse` / `error` / `redirect` helper Response or a raw
-`Response`. A named, client-branchable error is raised by RETURNING an
-`error.typed(name, status, schema?)` constructor — the RPC infers its typed-error
-surface from whichever constructors the handler returns, so there is no `errors:`
-option. `opts`: `inputSchema`, `outputSchema` (OpenAPI 200 + MCP
-`outputSchema`), `filesSchema` (multipart File parts; send a `FormData`),
-`clients` (`{ browser, mcp, cli }`), `crossOrigin` (exempt a mutating RPC from the
-same-origin CSRF gate), `timeout` (ms handler deadline → 504 every surface),
-`maxBodySize` (received-byte ceiling → 413), and — mutating helpers only —
-`outbox` (durable replay; `GET(fn, { outbox })` is a compile error). Query args
-arrive as strings → use `z.coerce.*`. Consume: `cache(fn)(args)` in-process,
-the swapped browser proxy `fn(args)`, `fn.raw(args)` for the `Response`,
-`fn.stream(args)` for a frame `Subscribable`.
-
-**Socket** (`src/server/sockets/<name>.ts`) — `export const <name> = socket(opts)`.
-`opts`: `schema` (validates publishes, infers `T`, turns mcp/cli on), `tail`
-(retained-frame count for replay), `ttl` (lazy eviction ms), `clientPublish`
-(allow client `POST` publishes), `clients`. A `Socket<T>` is an
-`AsyncIterable<T>` (bare `for await` = live, no replay); `.tail(count?)` opens a
-replay-seeded subscription; `.publish(m)` is isomorphic.
-
-**Page / layout** (`src/ui/pages/**`) — a `page.abide`'s URL is its folder path;
-`[id]` segments arrive as `page.params.id`. A `layout.abide` wraps the layer
-below at its outlet (`{children()}`). Read `page` for route/params/url, call
-`url()` / `navigate()` for base-correct links.
-
-**App** (`src/app.ts`) — optional `AppModule`: `init({ server })` (returns an
-optional teardown), `handle(request, next)` (single middleware), `handleError`,
-`health(request)` (fields merged into `/__abide/health`), `forwardHeaders`.
-**Config** (`src/server/config.ts`) — `export const config = env(schema)` at
-module top level.
-
-**Isomorphism** — wrap an RPC in `cache(fn)(args)` so an SSR `await` bakes the
-value into the initial HTML and the client hydrates warm off the serialized
-snapshot; the same call in the browser dedupes and fetches.
-
-## .abide template grammar
-
-A component file is a leading `<script>` (module imports + reactive setup),
-markup, and an optional root `<style>`. Ambient names the compiler injects (no
-import): `scope`, `props`, `effect`, `snippet`. `html` is imported
-(`abide/ui/html`). A *root* `<style>` is component-scoped; a `<script>` or
-`<style>` nested inside a control-flow branch is scoped to that branch (a nested
-`<script>` declares branch-local `scope().state/linked/computed`, re-seeded per
-mount, and may not carry module imports — those hoist to the leading `<script>`).
-
-**Reactive state** — reached only through `scope()`; the documented default is
-the destructure-once idiom: `const { state, computed, linked, effect } = scope()`
-at the top, then bare calls.
-
-| Form | Meaning |
-| --- | --- |
-| `let x = state(v, transform?)` | Writable state; assign `x = …` to update |
-| `const d = computed(() => …)` | Read-only derived |
-| `const l = linked(fn, transform?)` | Writable, re-seeds when `fn`'s deps change |
-| `effect(() => { … })` | Reaction re-run on dep change; client-only (SSR strips it) |
-| `const { a = d, ...rest } = props()` | Ambient prop reader (defaults + rest) |
-
-Bare `state`/`computed`/`linked`/`effect`/`derived` with no `scope()` destructure
-in scope is a compile error. `computed` is always read-only — express a writable
-computed at the binding (`bind:value={{ get, set }}`).
-
-**Bindings / directives**
-
-| Syntax | Meaning |
+**RPC** — the handler receives the schema-validated args
+(`InferOutput<inputSchema>`); typed generics on the helper are a compile error
+— type the parameter, let the body infer. Inside it, `request()` / `cookies()`
+/ `server()` read the request scope. Return `json(data)` (or `jsonl` / `sse`
+for streams, `error` / `redirect`, or a raw `Response`). Options:
+`inputSchema`, `outputSchema`, `filesSchema` (validates uploaded `File` parts,
+kept out of the JSON-Schema projection), `clients: { browser, mcp, cli }`,
+`crossOrigin` (exempts a mutating rpc from the same-origin CSRF gate),
+`timeout` (handler deadline in ms → 504 on every surface, composed into
+`request().signal`), `maxBodySize` (per-rpc 413 cap), `outbox` (durable
+delivery, mutating methods only). Query args on GET/HEAD/DELETE travel as
+strings — coerce in the schema (`z.coerce.number()`). A body rpc also accepts
+a `FormData` in place of typed args (the upload escape hatch): text fields
+validate as args, `File` parts validate against `filesSchema`.
+
+**Consuming an rpc** — the bare call `fn(args, opts?)` IS the smart read:
+cached, coalesced, reactive, stale-while-revalidate for replayable (GET/HEAD)
+reads; the second arg takes `{ ttl, tags, throttle, debounce, global, n }`
+(retention and the refetch clock — not transport). `global: true` stores the
+entry in the process-level store instead of the request-scoped default
+(server), so later requests reuse the value — for memoising an external
+endpoint, never per-user data; on the client it is a no-op (one tab store).
+During SSR the same call resolves
+in-process and its value is baked into the HTML so hydration starts warm —
+there is no `cache()` wrapper; the bare call carries the caching. Around it:
+`fn.raw(args, init?)` returns the raw `Response` (per-call transport options —
+`signal`, `headers`, `keepalive`, … — live here); `fn.refresh(args?)`
+refetches keeping the stale value visible; `fn.patch(args?, updater)` mutates
+the retained value locally (absent on streaming rpcs); `fn.peek(args?)` reads
+it synchronously; `fn.pending(args?)` / `fn.refreshing(args?)` are reactive
+probes; `fn.error(args?)` is the rpc's last typed error; `fn.watch(args?,
+handler)` pipes each resolved value to a handler (client-only; SSR-inert);
+`fn.isError(e, kind?)` type-guards a caught error against the rpc's declared
+error kinds; `fn.outbox()` exposes a durable rpc's parked-write queue. A
+handler that returns `jsonl()`/`sse()` makes the bare call return a
+`Subscribable` (`for await` it) — detected at build, nothing to declare;
+awaiting a streaming call is a compile error.
+
+**Typed errors** — declare a constructor with
+`error.typed(name, status, schema?)` and `return` it from the handler; the
+client's `HttpError` then carries `kind` (the name) and `data` (the schema's
+payload), narrowed via `rpc.isError`. The framework reserves
+`kind: 'validation'` (422, `data: ValidationErrorData`) and `kind: 'queued'`
+(a durable call parked while unreachable; `data` is the parked `OutboxEntry`).
+
+**Durable outbox** — an `outbox: true` (mutating) rpc still fetches and throws
+normally, but an unreachable server (transport failure or 502/503/504/52x)
+parks the request for replay as a side-effect and throws `kind: 'queued'`;
+once a backlog exists new calls park straight to the tail so writes stay
+ordered. Nothing auto-drains: replay via `rpc.outbox.retry()` or the global
+`outbox.retry()`; cancel via an entry's `controller.abort()`.
+
+**Socket** — `socket<T>(opts)` or `socket({ schema, … })` (with a schema, `T`
+infers and publishes validate). Options: `tail` (retained frames, default 1 —
+`tail: 0` opts out), `ttl` (retained frames expire lazily after N ms),
+`clientPublish` (accept browser/HTTP publishes, off by default), `clients`
+(mcp/cli exposure; a schema flips both on by default). The socket IS the
+`AsyncIterable` — iterating is the live stream, no replay. Members:
+`broadcast(msg)` (isomorphic publish — server fans out in-process + to remote
+subscribers, client sends a validated `pub` frame), `tail(count?)` (a
+subscription seeded with retained frames), `peek()` (latest retained frame),
+`refresh()` (drop local frames and re-pull the server tail; server-side
+no-op), `watch(handler)` ≡ `watch(socket, handler)` (client-only, SSR-inert),
+`pending()` / `refreshing()` / `done()` / `error()` (reactive stream probes),
+plus `name` and `clients`.
+
+**Pages and layouts** — `src/ui/pages/blog/[id]/page.abide` serves
+`/blog/<id>`; the param arrives as a prop (`const { id } = props()`) and on the
+reactive `page.params`. A `[[name]]` folder is an optional segment (the route
+matches with or without it; the param is absent when unmatched), `[...rest]`
+a catch-all capturing the remaining path (last segment only). One matcher
+resolves routes on both sides — at the first position where two matching
+patterns differ, literal beats `[name]` beats `[[name]]` beats `[...rest]`. A `layout.abide` wraps every page below its directory
+and renders the page at its `{children()}` outlet. Links are plain `<a href>`
+(the router intercepts in-app hrefs); build paths with `url()` and navigate
+programmatically with `navigate()`.
+
+**app.ts / config.ts** — `src/app.ts` optionally exports the `AppModule`
+hooks: `init({ server })` (boot; may return a cleanup run on SIGINT/SIGTERM),
+`handle(request, next)` (single middleware), `handleError(error, request)`,
+`health(request)` (fields merged into the `/__abide/health` payload — public
+and unauthenticated, keep it cheap), and `forwardHeaders` (extra inbound
+header names forwarded onto in-process rpc requests beyond the built-in
+auth/identity set). `src/server/config.ts` holds the `env(schema)` call so a
+bad environment fails at boot.
+
+## `.abide` template grammar
+
+A component file is: an optional leading `<script>` (imports + author scope),
+markup, optional `<style>` blocks. The compiler emits a client build and an
+SSR render from the same parse; `abide check` / the LSP type-check the
+template through a generated shadow. HTML comments are dropped; a bare
+`<template>` is an inert element.
+
+Reactive state is reached through **imported primitives**, resolved by import
+binding (alias-safe) and lowered by the compiler — inside a component you read
+and write the declared names as plain variables (`{count}`,
+`onclick={() => (count += 1)}`); there is no `.value` in `.abide` authoring
+and no `$state` sigils. In plain `.ts` modules the same imports are runtime
+cells read/written through `.value`.
+
+| Primitive | Import | Spec |
+| --- | --- | --- |
+| `state(initial, transform?)` | `@abide/abide/ui/state` | Writable cell. Plain `state(v)` lowers to a serializable doc slot (SSR-resumable); with `transform` the gate runs on every write (`(next, previous) => stored`) |
+| `state.computed(fn)` | member of `state` | Read-only derived value, lazy, never serialized |
+| `state.linked(fn, transform?)` | member of `state` | Writable cell re-seeded whenever the thunk's dependencies change |
+| `state.share(key, value)` / `state.shared(key)` | members of `state` | Put a named value on the ambient scope / read the closest ancestor's |
+| `watch(source, handler)` | `@abide/abide/ui/watch` | The single reaction primitive (client-only, stripped from SSR). Sources: a bare thunk `watch(() => …)` (auto-tracked effect), a state cell, a cell array, a socket/stream (`handler(frame)` per frame with reconnect replay), an rpc (`watch(fn, args?, handler)` — runs the smart read, `handler(value)` on each change). Returns a scope-tied disposer |
+| `html(str)` / `` html`…` `` | `@abide/abide/ui/html` | Brands trusted raw HTML so `{expr}` inserts nodes instead of escaped text; plain `{value}` always escapes |
+| `props()` | ambient (no import) | The prop reader: `const { name = fallback, ...rest } = props()`; a page's props are its route params |
+
+Bindings and directives (the attribute kinds `readAttributes` parses):
+
+| Form | Spec |
 | --- | --- |
-| `{expr}` | Escaped text interpolation |
-| `{html(...)}` | `html`-branded raw markup, plain call or tagged template (unescaped) |
-| `name={expr}` / `name="a {b}"` | Attribute value (plain or interpolated) |
-| `on<event>={fn}` | Event listener (`onclick`, `onsubmit`, …) |
-| `bind:value` / `bind:checked` / `bind:group` | Two-way form binds |
-| `bind:value={{ get, set }}` | Derived two-way binding |
-| `class:name={cond}` | Toggle a class |
-| `style:property={value}` | Set one style property |
-| `attach={fn}` | Run `fn(element)` at mount (returns optional teardown) |
-| `{...spread}` | Spread object keys — props on a component, attributes on an element |
-
-**Control flow** — mustache blocks, not `<template>`:
-
-| Block | Form |
+| `{expr}` | Text interpolation, escaped; a snippet or `html`-branded value mounts as nodes |
+| `name={expr}` | Attribute/prop bound to an expression |
+| `name="a {expr} b"` | Interpolated attribute — a literal `{` in a quoted value always interpolates (write `&lbrace;` for a literal brace) |
+| `{...expr}` | Spread — props onto a component, attributes onto a native element (rejected on `<template>`) |
+| `on<event>={fn}` | Event listener (`onclick`, `onsubmit`, …); on a component it is a checked callback prop |
+| `bind:value={cell}` | Two-way input/select/textarea binding. `<input type="number"/"range">` writes back a number; `<select>` re-applies against late-mounting options and `<select multiple>` binds an array of selected values |
+| `bind:value={{ get, set }}` | Writable-computed binding: read via `get()`, write via `set(next)` |
+| `bind:checked={cell}` / `bind:group={cell}` | Checkbox boolean / radio-group value (SSR emits boolean attributes bare — `checked`, `open`, `selected` on the matching option) |
+| `class:name={cond}` | Toggles a class; merges with a reactive `class` base in one effect |
+| `style:property={value}` | Sets one style property; merges with a reactive `style` base |
+| `attach={fn}` | Runs `fn(element)` at build time; an optional returned teardown runs on dispose |
+
+Control flow is mustache blocks (`{#…}` open, `{:…}` branch, `{/…}` close —
+the close must name its block, and a branch outside its block is a parse
+error):
+
+| Block | Spec |
 | --- | --- |
-| If | `{#if c}…{:else if d}…{:else}…{/if}` |
-| For | `{#for item, i of list by key}…{/for}` |
-| For-await | `{#for await item of source}…{/for}` (over an `AsyncIterable`) |
-| Await | `{#await p}…{:then v}…{:catch e}…{:finally}…{/await}` |
-| Switch | `{#switch s}{:case x}…{:default}…{/switch}` |
-| Try | `{#try}…{:catch e}…{:finally}…{/try}` |
-| Snippet | `{#snippet name(args)}…{/snippet}`, called `{name(args)}` |
-
-A capitalised tag is a child component; nested content renders where the child
-calls `{children()}` — the single slot, with `{#if children}…{:else}…{/if}` as
-the fallback form. No named slots.
+| `{#if cond}…{:else if cond}…{:else}…{/if}` | Conditional chain (the branch keyword is `{:else if}`, with a space) |
+| `{#for item, i of list by key}…{:catch e}…{/for}` | Keyed list; `, i` index and `by` key optional; `{#for await item of asyncIterable}` renders rows as they arrive (its `{:catch}` shows the stream error) |
+| `{#await p}…{:then v}…{:catch e}…{:finally}…{/await}` | Async block. The branch form streams: SSR flushes the shell and streams the fragment out of order. The head form `{#await p then v}` is blocking — rendered inline (depth-first, serial) during the SSR pass |
+| `{#switch subject}{:case match}…{:default}…{/switch}` | Multi-branch on a subject; only branches render — stray content is a compile error |
+| `{#try}…{:catch e}…{:finally}…{/try}` | Synchronous error boundary around a build/reactive throw |
+| `{#snippet name(args)}…{/snippet}` | Declares a reusable builder, called as an interpolation: `{name(args)}`; a snippet value passes through props like any other value |
 
-> Removed forms throw a migration error: the `<slot>` element (use
-> `{children()}`), `<template name>` snippets (use `{#snippet}`), and all
-> `<template if>` / `<template each>` / `<template await>` / … control flow (use
-> the `{#…}` blocks). A bare `<template>` is now an inert element.
+Components are capitalised tags (`<Panel prop={x}>…</Panel>`); nested content
+renders where the component calls `{children()}` — the single fill point
+(`{#if children}{children()}{:else}…{/if}` for a fallback; there are no named
+slots and no `<slot>` element). A layout's `{children()}` is the route outlet.
 
-## Server surface — abide/server/*
+`<script>` and `<style>` are **not component-root-only**: either may sit
+inside a control-flow branch, scoped to that branch. A nested `<script>`
+declares branch-local `state` / `state.computed` / `state.linked` the same
+imported way (re-seeded per mount; static `import` statements are illegal
+there — imports live in the leading `<script>`). A **root** `<style>` is
+component-scoped; a nested `<style>` scopes to its sibling subtree only.
 
-### RPC — @documentation rpc
+Removed forms throw migration errors at parse time: the `<slot>` element (use
+`{children()}`), `<template name>` snippets (use `{#snippet}`), and all
+`<template if/each/await/switch/…>` control flow (use `{#…}` blocks).
 
-- `abide/server/GET` — read RPC helper; `GET(fn, opts?)`, bound by the bundler from `src/server/rpc/`.
-- `abide/server/POST` — create/mutate RPC helper; accepts `outbox` for durable replay.
-- `abide/server/PUT` — replace RPC helper (mutating).
-- `abide/server/PATCH` — partial-update RPC helper (mutating).
-- `abide/server/DELETE` — delete RPC helper (mutating).
-- `abide/server/HEAD` — read RPC helper, no body (auto-exposes to MCP like GET).
+## Server surface — `abide/server/*`
 
-### Sockets — @documentation sockets
+### RPC — `@documentation rpc`
 
-- `abide/server/socket` — `socket(opts)` declares a broadcast topic; one export per file under `src/server/sockets/`.
+- `@abide/abide/server/GET` — GET rpc helper: `export const x = GET(handler, opts?)` inside `src/server/rpc/`; the bundler rewrites it to the server dispatcher or the browser proxy — calling it outside an rpc module throws.
+- `@abide/abide/server/POST` — POST rpc helper (mutating: accepts `outbox`, JSON/FormData body).
+- `@abide/abide/server/PUT` — PUT rpc helper (mutating).
+- `@abide/abide/server/PATCH` — PATCH rpc helper (mutating).
+- `@abide/abide/server/DELETE` — DELETE rpc helper (mutating; args travel in the query string).
+- `@abide/abide/server/HEAD` — HEAD rpc helper (read-only).
 
-### Response — @documentation response
+### Responses — `@documentation response`
 
-- `abide/server/json` — JSON `Response` with `Cache-Control: no-store` default; same shape as `Response.json`.
-- `abide/server/jsonl` — wraps an `AsyncIterable<Frame>` as a JSON Lines (`application/jsonl`) streaming Response.
-- `abide/server/sse` — wraps an `AsyncIterable<Frame>` as Server-Sent Events (`text/event-stream`).
-- `abide/server/error` — error Responses. `error(status, message?)` = plain-text (message defaults to the status reason phrase). `error.typed(name, status, schema?)` = a reusable named typed-error constructor; returning it from a handler IS the error (serializes `{ $abideError, data }` at `status`), and the RPC infers `rpc.isError(e, name)` narrowing (`.kind` + typed `.data`) from the returned constructors — no `errors:` option.
-- `abide/server/redirect` — redirect Response; accepts relative URLs, defaults to 302.
+- `@abide/abide/server/json` — `json(data, init?)`: JSON response with `Cache-Control: no-store` default; `json(undefined)` emits 204 and round-trips back to `undefined`; carries the value type so the rpc's `Return` infers.
+- `@abide/abide/server/jsonl` — `jsonl(asyncIterable, init?)`: JSON Lines streaming response; consumer cancel flows into the generator's `return`; a generator throw becomes a final `{"$error": message}` line.
+- `@abide/abide/server/sse` — `sse(asyncIterable, init?)`: Server-Sent Events response with a 15s keepalive comment; errors emit an `event: error` frame carrying only the message.
+- `@abide/abide/server/error` — `error(status, message?, init?)`: plain-text error response (message defaults to the reason phrase); the caller's await throws `HttpError`. Member `error.typed(name, status, schema?)` declares a reusable typed-error constructor the handler returns (see Authoring contracts).
+- `@abide/abide/server/redirect` — `redirect(url, status = 302, init?)`: redirect response accepting relative URLs; 301/302/303/307/308.
 
-### Request scope — @documentation request-scope
+### Request scope — `@documentation request-scope`
 
-- `abide/server/request` — the inbound `Request` for the current SSR/RPC pass (AsyncLocalStorage; throws outside a scope).
-- `abide/server/cookies` — the request's cookie jar (Bun `CookieMap`); writes flush as `Set-Cookie` on return.
-- `abide/server/server` — the active `Bun.serve` instance (a no-op in-process server under CLI/MCP/test dispatch).
+- `@abide/abide/server/request` — `request()`: the inbound `Request` for the in-flight SSR/rpc pass (AsyncLocalStorage); throws outside a request scope.
+- `@abide/abide/server/cookies` — `cookies()`: the request's cookie jar (Bun `CookieMap`) — reads parse the inbound header; `set`/`delete` flush as `Set-Cookie` when the handler returns.
+- `@abide/abide/server/server` — `server()`: the active `Bun.serve` instance; a no-op stand-in during in-process dispatch (CLI/MCP/tests); throws before boot.
 
-### Configuration — @documentation configuration
+### Configuration — `@documentation configuration`
 
-- `abide/server/env` — validate `Bun.env` against a Standard Schema at module top level; returns typed config or fails boot loudly.
+- `@abide/abide/server/env` — `env(schema)`: validates `Bun.env` against a Standard Schema at module top level (synchronous; every issue reported at once) and returns the typed config; the schema also projects the bundle's first-run setup form.
 
-### Observability — @documentation observability
+### Sockets — `@documentation sockets`
 
-- `abide/server/reachable` — `await reachable(host)` outbound reachability probe with warm TTL polling (server-only).
+- `@abide/abide/server/socket` — `socket<T>(opts?)` / `socket({ schema, tail, ttl, clientPublish, clients })`: declares the broadcast topic inside `src/server/sockets/<name>.ts`; see Authoring contracts for the full `Socket<T>` member surface.
 
-### Agent — @documentation agent
+### Agent — `@documentation agent`
 
-- `abide/server/agent` — `agent(engine, messages)` runs a model engine against the app's own MCP surface, returning the engine's `AgentFrame` stream (wrap in `jsonl()`/`sse()`); also exports `NeutralMessage`, `AgentFrame`, `AgentSurface`, `AgentEngine`.
+- `@abide/abide/server/agent` — `agent(engine, messages)`: runs a provider engine (an `@abide/<provider>` package) against the app's own MCP surface inside an rpc's request scope and returns its `AgentFrame` stream; the handler picks the transport (`jsonl(agent(…))` / `sse(agent(…))`). The module also exports the neutral contract types: `NeutralMessage` (user/assistant/tool turns), `AgentFrame` (`text` deltas, `tool_use`, `tool_result`, `done` with a stop reason), `AgentSurface` (the gated tool/prompt/resource surface), and `AgentEngine` (surface + messages + origin in, frames out).
 
-### Server plumbing — @documentation plumbing
+### Server plumbing — `@documentation plumbing`
 
-- `abide/server/AppModule` — type of the optional `src/app.ts` hooks (`init`/`handle`/`handleError`/`health`/`forwardHeaders`).
-- `abide/server/InspectorContext` — type the capabilities core injects into `@abide/inspector` when enabled.
-- `abide/server/rpc/defineRpc` — the runtime the RPC helpers compile to (method + URL + handler → `RemoteFunction`); not called directly.
-- `abide/server/sockets/defineSocket` — the server-side `socket()` implementation the bundler binds the file name into.
-- `abide/server/prompts/definePrompt` — the runtime each `src/mcp/prompts/<file>.md` compiles to (registers an MCP prompt).
-- `abide/server/prompts/renderPromptTemplate` — substitutes `{{name}}` placeholders in a markdown prompt body (missing → empty).
+- `@abide/abide/server/AppModule` — the type of `src/app.ts`'s optional hooks (`init`, `handle`, `handleError`, `health`, `forwardHeaders`).
+- `@abide/abide/server/InspectorContext` — the capability object core injects into `@abide/inspector` (`loadSurface`, `cacheSnapshot`, `inFlightSnapshot`, `onRecord`, app identity); keeps the inspector a pure consumer.
+- `@abide/abide/server/rpc/defineRpc` — `defineRpc(method, url, handler, opts?)`: the server-side construction the bundler rewrites rpc helper calls into — validation, timeout composition, client-flag resolution, registry entry.
+- `@abide/abide/server/sockets/defineSocket` — `defineSocket(name, opts?)`: server-side socket construction (retained-tail buffer with lazy TTL eviction, per-subscriber queues, `server.publish` fan-out).
+- `@abide/abide/server/prompts/definePrompt` — `definePrompt(name, opts)`: registers an MCP prompt; the resolver plugin generates one call per `src/mcp/prompts/<name>.md`.
+- `@abide/abide/server/prompts/renderPromptTemplate` — `renderPromptTemplate(template, args)`: substitutes `{{name}}` placeholders in a prompt body (missing args collapse to empty).
 
-## Isomorphic surface — abide/shared/*
+## Isomorphic surface — `abide/shared/*`
 
-### Cache — @documentation cache
+### Cache mutators — `@documentation cache`
 
-- `abide/shared/cache` — `cache(fn, options?)(args)` request/tab-scoped read with coalescing, `ttl`, `swr`, `tags`, `global`; SSR snapshot for warm hydration. Carries `cache.invalidate(selector?, args?)` and `cache.on(source, handler)` (event-driven invalidation).
+- `@abide/abide/shared/refresh` — `refresh(selector?, args?)`: refetch every cached read matching the selector, keeping the stale value visible until the fresh one swaps in. Selector grammar: `(fn, args)` exact call, `(fn)` every args-variant, `({ tags })` a tagged group, `()` everything. `fn.refresh(args?)` is the pre-bound sugar.
+- `@abide/abide/shared/patch` — `patch(fn, args?, updater)` / `patch({ tags }, updater)`: mutate the retained value(s) in place — reactive, no network; the optimistic-update / socket-frame primitive. `fn.patch(…)` is the sugar.
 
-### Response — @documentation response
+### Probes — `@documentation probes`
 
-- `abide/shared/HttpError` — thrown on a non-2xx remote call; carries the raw `Response` plus `kind`/`data`.
-- `abide/shared/ValidationErrorData` — the `data` payload (`kind: 'validation'`, status 422) of a validation failure: raw `issues` + form-friendly `fields`.
+Probes report, never act — reading one opens no fetch and no stream.
 
-### RPC — @documentation rpc
+- `@abide/abide/shared/pending` — `pending(selector?, args?)`: reactive "no value yet" probe over calls and streams (global, per-rpc, per-call, tagged, per-subscribable; a durable rpc's parked writes count too).
+- `@abide/abide/shared/refreshing` — `refreshing(selector?, args?)`: "holding a value while a fresher one is in flight" — the SWR reload / stream-reconnect badge.
+- `@abide/abide/shared/peek` — `peek(fn, args?)` / `peek(socket)`: the retained value (or latest frame), synchronously, `T | undefined`; reactive inside a tracking scope.
+- `@abide/abide/shared/done` — `done(subscribable)`: true once a stream closed (stream-only; a cache read's "done" is `!pending && !refreshing`).
+- `@abide/abide/shared/online` — `online()`: reactive connectivity probe — browser `online`/`offline` events; server-side it reflects the *calling client's* reported connectivity (always true during SSR and outside a scope).
 
-- `abide/shared/withJsonSchema` — attach a `toJSONSchema()` projection to a Standard Schema whose library lacks one (feeds OpenAPI/MCP/CLI).
+### Errors — `@documentation response`
 
-### Templating — @documentation templating
+- `@abide/abide/shared/HttpError` — thrown by rpc calls on non-2xx; carries `status`, `statusText`, the raw `response`, and — for typed/validation/queued errors — `kind` + `data`.
+- `@abide/abide/shared/ValidationErrorData` — the `data` shape of a `kind: 'validation'` failure: the raw Standard Schema `issues` plus a `fields` (field → first message) map.
 
-- `abide/shared/snippet` — brands a payload so a `{expr}` interpolation mounts it (client builder / SSR string); the runtime behind `{#snippet}`. Also `Snippet<Payload>`, `snippetPayload`.
+### Schema projection — `@documentation rpc`
 
-### Probes — @documentation probes
+- `@abide/abide/shared/withJsonSchema` — `withJsonSchema(schema, toJsonSchema)`: attaches the `toJSONSchema()` projection to a Standard Schema whose library lacks one, feeding OpenAPI, MCP, CLI help, and the bundle setup form.
 
-- `abide/shared/pending` — reactive in-flight probe over cache + tail registries; `pending()`, `pending(fn)`, `pending(fn, args)`, `pending({ tags })`.
-- `abide/shared/refreshing` — reactive revalidation probe (holding a value while a fresher one loads); same selector grammar as `pending`.
-- `abide/shared/online` — reactive network-connectivity probe (`navigator.onLine`, offline-reliable).
+### Observability — `@documentation observability`
 
-### Page — @documentation page
+- `@abide/abide/shared/health` — `health()`: reactive backend health — `{ reachable, abide, name, version, …app health-hook fields }`, polled from `/__abide/health` only while a tracking scope reads it; SSR-seeded so hydration starts warm; constant `{ reachable: true }` on the server. The `AppHealth`/`AppHealthMap` types augment from the generated `health.d.ts`.
+- `@abide/abide/shared/reachable` — `await reachable(host?)`: outbound reachability, same callable both sides. The first call probes (HEAD) and starts a TTL background poll; later calls answer instantly off the warm value. Any completed HTTP response counts as reachable. No host asks about the app's own backend: constant true on the server and on a loopback origin (dev, desktop bundle — works offline); a deployed origin probes like any host. The browser probes no-cors and composes `navigator.onLine` in at read time (loopback exempt). Tuned by `ABIDE_REACHABLE_TTL` / `ABIDE_REACHABLE_TIMEOUT` (server env; the browser runs the defaults).
+- `@abide/abide/shared/log` — the unified logger: `log(...)` / `.warn` / `.error` / `.trace` on the app's always-on channel, every record carrying request-scope context (short trace id, +elapsed, method+path); member `log.channel(name)` returns the same shape on a DEBUG-gated diagnostic channel. Renders tsv (default) or JSON per `ABIDE_LOG_FORMAT`.
+- `@abide/abide/shared/trace` — `trace()`: the current request's W3C `traceparent` (client-side: the trace of the request that rendered the page), or undefined outside any scope.
 
-- `abide/shared/page` — reactive page proxy: `route`, `params`, `url` (browser-space), `navigating`; isomorphic.
+### Page — `@documentation page`
 
-### URL — @documentation url
+- `@abide/abide/shared/page` — the reactive page proxy: `page.route`, `page.params`, `page.url` (browser-space on both sides, mount base included), `page.navigating`; isomorphic, re-runs readers across navigations.
 
-- `abide/shared/url` — `url(path, args?)` resolves a base-correct, typed in-app URL (RPC query / page params / asset); also `RpcRoutes`, `PageRoutes`, `PublicAssets`, `PathParams` (augmentable typing seams).
+### URL — `@documentation url`
 
-### Observability — @documentation observability
+- `@abide/abide/shared/url` — `url(path, params?/args?)`: resolves any in-app URL to its base-correct form — a page route literal interpolates its `[name]` / `[[name]]` / `[...rest]` params (typed via `PathParams`; an absent optional drops its segment), a GET rpc path serializes typed args to the query, anything else is base-prefixed. Also exports the augmentable `RpcRoutes` / `PageRoutes` / `PublicAssets` maps and the `PathParams<P>` type.
 
-- `abide/shared/health` — typed `health()` probe of `/__abide/health` (fields augmented from the app's `health()` hook); also `AppHealthMap`, `AppHealth`, `HealthState`.
-- `abide/shared/log` — unified logger carrying request-scope context; `log`/`.warn`/`.error`/`.trace` on the app channel, `log.channel(name)` for DEBUG-gated channels.
-- `abide/shared/trace` — the current request's W3C `traceparent`, or undefined outside a request scope; isomorphic.
+### Templating — `@documentation templating`
 
-### Isomorphic plumbing — @documentation plumbing
+- `@abide/abide/shared/snippet` — `snippet(payload)`: brands a snippet payload so a `{expr}` interpolation mounts it (client: a DOM builder; server: the rendered string); the compiler wraps `{#snippet}` bodies in this. Also exports the `Snippet<P>` type and `snippetPayload(value)` (the payload, or undefined for plain values).
 
-- `abide/shared/createSubscriber` — abide-native open-on-first-read / close-on-last-reader subscriber over the signal core (cache/tail substrate).
+### Shared plumbing — `@documentation plumbing`
 
-## UI surface — abide/ui/* (client-only)
+- `@abide/abide/shared/createSubscriber` — `createSubscriber(start)`: open-on-first-tracked-read / close-on-last-reader resource lifecycle grounded in the signal core; the substrate under `health()`, `online()`, and the tail probes.
 
-### Reactive state — @documentation reactive-state
+## UI surface — `abide/ui/*` (client-only)
 
-- `abide/ui/scope` — `scope()` resolves the current lexical scope; the sole reactive entry, carrying `state`/`computed`/`linked`/`effect` + data/context/capability methods (walk to the tree root via the handle's `.root()`).
+### Reactive state — `@documentation reactive-state`
 
-### Templating — @documentation templating
+- `@abide/abide/ui/state` — the `state` primitive: `state(initial, transform?)` writable cell, `state.computed(fn)` read-only derived, `state.linked(fn, transform?)` writable-reseeded, `state.share(key, value)` / `state.shared(key)` ambient context. In `.abide` files the compiler lowers reads/writes to plain variable syntax; in `.ts` the cell is read/written through `.value`.
+- `@abide/abide/ui/watch` — `watch(source, handler)`: the single reaction primitive over a thunk, cell, cell array, socket/stream, or rpc (see the grammar table). Client-only; the compiler strips author calls from SSR, and the `socket.watch` / `fn.watch` instance sugar is SSR-inert.
 
-- `abide/ui/html` — `html(string)` / `` html`…` `` marks trusted raw HTML so a `{expr}` inserts nodes instead of escaped text.
+### Templating — `@documentation templating`
 
-### Tail — @documentation tail
+- `@abide/abide/ui/html` — `html(string)` / `` html`…` ``: brands trusted raw HTML for unescaped interpolation; the tag does not escape its interpolations — only feed it values you trust.
 
-- `abide/ui/tail` — reactive streaming consumer of a `Subscribable<T>` (socket / `fn.stream`); bare = latest frame, `{ last: n }` = window; `tail.error`, `tail.status`. No-op on the server.
+### Navigate — `@documentation navigate`
 
-### Navigate — @documentation navigate
+- `@abide/abide/ui/navigate` — `navigate(path, params?, options?)`: typed programmatic navigation off the route map; params interpolate through `url()` (base-correct). Options `{ replace, keepScroll }`. The module also exports `navigatePath(path, options?)` (already-resolved paths — the router's own entry, no re-basing) and the `NavigateOptions` type.
 
-- `abide/ui/navigate` — `navigate(path, params?, options?)` typed in-app navigation through `url()`; `replace`/`keepScroll`. Also `navigatePath` (already-resolved path) and `NavigateOptions`.
+### Outbox — `@documentation ui`
 
-### UI — @documentation ui
+- `@abide/abide/ui/outbox` — the global reactive outbox: `outbox()` lists every durable rpc's undelivered entries (each tagged with its `rpc`), member `outbox.retry()` drains every queue. Empty list server-side. Types `GlobalOutbox`, `GlobalOutboxEntry`.
 
-- `abide/ui/outbox` — global reactive view of every durable RPC's parked writes; callable for the list, `outbox.retry()` to drain. Also `GlobalOutbox`, `GlobalOutboxEntry`.
+### UI plumbing — `@documentation plumbing`
 
-### UI plumbing — @documentation plumbing
+Compiler/runtime machinery — published so generated code, the type shadow, and
+tests can import it, not for app code.
 
-- `abide/ui/effect` — the from-scratch effect primitive `scope().effect` lowers to (and the SSR strip target).
-- `abide/ui/enterScope` — opens an isolated lexical scope for an SSR render; returns the previous one.
-- `abide/ui/exitScope` — restores the scope `enterScope` saved (closes an SSR render's scope).
-- `abide/ui/remoteProxy` — client-side substitute for a server RPC (typed fetch over HTTP); also `DurableOptions`.
-- `abide/ui/socketProxy` — client-side substitute for a server `Socket` (subscribe over the multiplexed ws).
-- `abide/ui/router` — the client router: outlet boundaries, chain mounting, history-driven navigation.
-- `abide/ui/startClient` — boot entry that consumes the server's `__SSR__` payload and hydrates the page.
-- `abide/ui/renderToStream` — out-of-order SSR streaming: shell first, then one resolved fragment per streaming await block.
-- `abide/ui/dom/mount` — mount a top-level page/layout into a host under an ownership scope; returns a disposer.
-- `abide/ui/dom/mountChild` — mount a child component as a marker-bounded range (no wrapper element).
-- `abide/ui/dom/mergeProps` — compose a child's props from ordered explicit/spread/`$children` layers (last wins).
-- `abide/ui/dom/spreadProps` — wrap a `{...source}` prop-spread layer as live value thunks.
-- `abide/ui/dom/restProps` — the unconsumed props of a `const { a, ...rest } = props()` destructure.
-- `abide/ui/dom/spreadAttrs` — spread an object's keys onto a native element (`<div {...rest}>`).
-- `abide/ui/dom/readCall` — guarded method call on a reactive-doc read (legible throw naming the authored path).
-- `abide/ui/dom/hydrate` — adopt server-rendered DOM in place instead of rebuilding; returns a disposer.
-- `abide/ui/dom/text` — a text node tracking a `read()` (plain-text fast path).
-- `abide/ui/dom/appendText` — a reactive `{expr}` interpolation (escaped text / `{snippet}` / `html` raw).
-- `abide/ui/dom/appendTextAt` — `appendText` mounted at a skeleton anchor comment (text interleaved with elements).
-- `abide/ui/dom/appendSnippet` — mount a `{snippet(args)}` builder's nodes in a marker range, reactive in its args.
-- `abide/ui/dom/appendStatic` — a static (non-reactive) text node, claimed on hydrate.
-- `abide/ui/dom/cloneStatic` — append a fully-static subtree, byte-identical to the SSR markup.
-- `abide/ui/dom/skeleton` — clone a bound element's static skeleton with located holes/anchors.
-- `abide/ui/dom/anchorCursor` — position a skeleton-anchored control-flow block or slot.
-- `abide/ui/dom/mountSlot` — mount a component's `{children()}` content (or fallback) as a marker range.
-- `abide/ui/dom/outlet` — a layout's outlet boundary the router fills with the next chain layer.
-- `abide/ui/dom/attr` — bind one element attribute to a `read()` (present/absent boolean semantics).
-- `abide/ui/dom/on` — attach an event listener, owned by the current scope (the `onclick={…}` target).
-- `abide/ui/dom/attach` — run an `attach={fn}` against an element at build, owning its teardown.
-- `abide/ui/dom/each` — keyed list runtime (`{#for … by key}`); each row a marker-bounded range.
-- `abide/ui/dom/eachAsync` — async keyed list runtime (`{#for await … }`) over an `AsyncIterable`.
-- `abide/ui/dom/when` — conditional runtime (`{#if}` + optional `{:else}`).
-- `abide/ui/dom/awaitBlock` — async runtime (`{#await}` → pending / then / catch ranges).
-- `abide/ui/dom/tryBlock` — synchronous error-boundary runtime (`{#try}`).
-- `abide/ui/dom/switchBlock` — multi-branch runtime (`{#switch}`, strict `===`, default fallback).
-- `abide/ui/dom/applyResolved` — bundle-side consumer of an SSR stream chunk (streaming nav / socket SSR).
-- `abide/ui/runtime/escapeKey` — escape one object key into a JSON-Pointer reference token (RFC 6901).
-- `abide/ui/runtime/nextBlockId` — the next block id in the current render pass (await/try, document order).
-- `abide/ui/runtime/enterRenderPass` — mark entry into a render/mount (resets the block-id counter at depth 0).
-- `abide/ui/runtime/exitRenderPass` — mark exit from a render/mount, unwinding the depth.
+- `@abide/abide/ui/effect` — `effect(fn)`: the raw auto-tracked effect the compiler emits for bindings; authors use `watch`. Returns a disposer; SSR strips author calls.
+- `@abide/abide/ui/currentScope` — `scope()`: the ambient lexical scope — the internal lowering host for `state`/`effect` (`derive`/`linked`/`effect`/`share` land here).
+- `@abide/abide/ui/enterRenderScope` — `enterScope()`: opens an isolated scope for an SSR render; returns the previous scope to restore.
+- `@abide/abide/ui/exitRenderScope` — `exitScope(previous)`: restores the scope `enterScope` saved.
+- `@abide/abide/ui/router` — `router(...)`: the client router — fills layout/page chains into comment-marker outlet boundaries, intercepts in-app links, buckets/restores scroll per history entry.
+- `@abide/abide/ui/startClient` — `startClient(...)`: the client entry — reads every `__SSR__` field into its shared slot (cache seed, health seed, client timeout, resume manifest), hydrates the chain, starts the router.
+- `@abide/abide/ui/renderToStream` — `renderToStream(render)`: out-of-order SSR streaming — shell first, then one `<abide-resolve>` fragment per streaming await block in completion order; blocking (`then`-head) awaits render inline.
+- `@abide/abide/ui/remoteProxy` — `remoteProxy(method, url, opts?)`: the browser-side rpc stub the bundler emits (fetch, decode, HttpError, outbox parking, streaming); the `DurableOptions` type rides along.
+- `@abide/abide/ui/socketProxy` — `socketProxy(name)`: the browser-side socket stub — the identical `Socket<T>` shape over the page's lazily-opened multiplexed ws channel.
+- `@abide/abide/ui/runtime/escapeKey` — JSON-Pointer-escapes one reactive-doc path key (`~`→`~0`, `/`→`~1`).
+- `@abide/abide/ui/runtime/nextBlockId` — the next await/try block id in the current render pass (document order, shared across inlined children).
+- `@abide/abide/ui/runtime/enterRenderPass` — marks entry into a render/mount; the outermost resets the block-id counter.
+- `@abide/abide/ui/runtime/exitRenderPass` — unwinds `enterRenderPass`'s depth.
+- `@abide/abide/ui/dom/mount` — mounts a top-level page/layout into a host under an ownership scope; returns the unmount.
+- `@abide/abide/ui/dom/mountChild` — mounts a nested child component as a comment-marker range (dev builds also register it with the hot bridge).
+- `@abide/abide/ui/dom/mountSlot` — mounts a component's passed-children content as a marker-bounded range.
+- `@abide/abide/ui/dom/outlet` — a layout's outlet: an empty `<!--abide:outlet-->…<!--/abide:outlet-->` boundary the router fills.
+- `@abide/abide/ui/dom/hydrate` — adopts server-rendered DOM instead of rebuilding: runs the build with a claim cursor over the existing nodes.
+- `@abide/abide/ui/dom/skeleton` — the parsed-once static-structure clone path every bound element builds through; element holes by path, blocks by anchor comments.
+- `@abide/abide/ui/dom/anchorCursor` — positions a skeleton-anchored block/slot at its `<!--a-->` anchor, in clone and hydrate modes alike.
+- `@abide/abide/ui/dom/cloneStatic` — appends a fully-static subtree (no bindings, control flow, or listeners) by cloning.
+- `@abide/abide/ui/dom/appendStatic` — a static text node: created (create mode) or claimed from server-rendered text (hydrate mode).
+- `@abide/abide/ui/dom/appendText` — a reactive `{expr}` text node under a parent.
+- `@abide/abide/ui/dom/appendTextAt` — a reactive text node mounted at a skeleton anchor (text interleaved with element siblings).
+- `@abide/abide/ui/dom/appendSnippet` — mounts a `{snippet(args)}` interpolation's builder into a marker-bounded range.
+- `@abide/abide/ui/dom/text` — a text node whose content tracks a reactive read.
+- `@abide/abide/ui/dom/attr` — binds an element attribute to a read (boolean true → bare attribute, false/nullish → removed).
+- `@abide/abide/ui/dom/on` — attaches an event listener whose removal is registered with the ownership scope.
+- `@abide/abide/ui/dom/attach` — runs an `attach={fn}` attachment and registers its optional teardown.
+- `@abide/abide/ui/dom/bindSelectValue` — two-way `<select>` binding that re-applies the selection when the option set changes (late-mounting `{#for}`/async options; `multiple` binds an array).
+- `@abide/abide/ui/dom/each` — keyed `{#for}` runtime: marker-bounded rows reconciled by key.
+- `@abide/abide/ui/dom/eachAsync` — `{#for await}` runtime: rows append/reconcile as the AsyncIterable yields.
+- `@abide/abide/ui/dom/when` — `{#if}` runtime (single-branch swap in a marker-bounded range).
+- `@abide/abide/ui/dom/switchBlock` — `{#switch}` runtime (also `{#if}` chains with `{:else if}` branches).
+- `@abide/abide/ui/dom/awaitBlock` — `{#await}` runtime: pending → resolved/error branch swap, teardown-generation guarded.
+- `@abide/abide/ui/dom/tryBlock` — `{#try}` runtime: synchronous error boundary around a subtree build.
+- `@abide/abide/ui/dom/applyResolved` — consumes a streamed SSR `<abide-resolve>` chunk, swapping it into its await boundary (the bundle-side counterpart of the doc stream's inline scripts).
+- `@abide/abide/ui/dom/mergeProps` — composes a child's props from explicit thunk runs, spread layers, and the trailing children layer.
+- `@abide/abide/ui/dom/spreadProps` — wraps a `{...source}` spread layer so every key resolves to a live value thunk.
+- `@abide/abide/ui/dom/restProps` — the live unconsumed-props object behind `const { …, ...rest } = props()`.
+- `@abide/abide/ui/dom/spreadAttrs` — spreads an object's keys onto a native element (`<div {...rest}>`), keys enumerated once.
+- `@abide/abide/ui/dom/readCall` — guarded method call on a reactive-doc read (the `model.draft.trim()` lowering).
 
 ## Build / tooling
 
-### Building — @documentation building
+### Building — `@documentation building`
 
-- `abide/build` — build the client bundle into `dist/_app` (the `.abide` loader, virtual resolver, optional Tailwind, optional gzip).
-- `abide/compile` — produce a standalone Bun server executable (runs `build` first, embeds compressed assets).
+- `@abide/abide/build` — `build({ cwd, … })`: builds the client bundle into `dist/_app` (`.abide` loader, virtual-module resolver, optional Tailwind); production builds also emit `.gz` siblings; staged and atomically swapped so a live dev server never sees a half-built dist.
+- `@abide/abide/compile` — `compile({ cwd, target?, outfile? })`: produces a standalone server executable (runs the client build first and embeds the compressed assets); returns the binary path.
 
-### Build plumbing — @documentation plumbing
+### Tooling plumbing — `@documentation plumbing`
 
-- `abide/preload` — the Bun preload that installs the `.abide` loader + resolver for the server/scripts/tests.
-- `abide/resolver-plugin` — resolves `$`-aliased / extensionless / directory imports Node-style; also the build's virtual-module loaders.
-- `abide/ui-plugin` — the Bun plugin that compiles `.abide` single-file components into ES modules.
-- `abide/tsconfig` — the shippable base `tsconfig.app.json` projects extend.
+- `@abide/abide/preload` — the Bun preload installing the `.abide` loader, the virtual-module resolver, and a `.css` no-op loader — the same runtime for the server, scripts (`abide run`), and `bun test`.
+- `@abide/abide/resolver-plugin` — the resolver plugin itself: `$`-alias + virtual-module (`abide:*`) resolution, rpc/socket module rewriting, side-crossing guards.
+- `@abide/abide/ui-plugin` — the Bun plugin that compiles `.abide` single-file components to ES modules (layouts flagged by filename; scoped styles bundled into the entry stylesheet).
+- `@abide/abide/tsconfig` — the base tsconfig apps extend (`bundler` resolution, strict, `types: ["bun"]`, erasable syntax only).
 
-## Desktop bundle
+## Desktop bundle — `@documentation bundle`
 
-### Bundle — @documentation bundle
+- `@abide/abide/bundle/BundleWindow` — the type of `src/bundle/window.ts`'s default export: window title/size plus custom `menu` entries inserted between the standard Edit and Window menus.
+- `@abide/abide/bundle/BundleMenu` — one top-level custom menu (`label` + `items`).
+- `@abide/abide/bundle/BundleMenuItem` — one menu entry: a divider, an `emit` item dispatching an `abide:menu` CustomEvent into the page (optional Cmd `shortcut`), or a `navigate` item repointing the window itself.
+- `@abide/abide/bundle/onMenu` — `onMenu(handler)` / `onMenu(name, handler)`: subscribes to bundle menu clicks; returns an unsubscribe; inert during SSR and in plain browser tabs.
+- `@abide/abide/bundle/bundled` — `bundled()`: true inside the desktop bundle (client: webview init flag; server: launcher-spawned process), false in a plain browser tab or on a remote server.
+- `@abide/abide/server/appDataDir` — `appDataDir()`: the running bundle's per-user data dir, keyed by the bundler-injected program name; pure path computation, cwd-independent (`ABIDE_DATA_DIR` overrides).
 
-- `abide/server/appDataDir` — the running bundle's per-user data dir (keyed by program name; cwd-independent; server-side).
-- `abide/bundle/BundleWindow` — type of the default-exported `src/bundle/window.ts` window config (title/size/menus).
-- `abide/bundle/BundleMenu` — a top-level macOS menu (`label` + `items`).
-- `abide/bundle/BundleMenuItem` — a single menu entry (divider or a click that dispatches an `abide:menu` event).
-- `abide/bundle/onMenu` — subscribe to bundle menu clicks (catch-all or filtered); returns an unsubscribe.
-- `abide/bundle/bundled` — true when running inside the desktop bundle rather than a plain browser (isomorphic).
+## MCP — `@documentation mcp`
 
-## MCP
-
-### MCP — @documentation mcp
-
-- `abide/mcp/createMcpServer` — construct the MCP server bound to the RPC registry (tools from `clients.mcp` RPCs + prompts + resources); `handle(request)` backs `/__abide/mcp`. Framework-internal.
+- `@abide/abide/mcp/createMcpServer` — `createMcpServer(opts?)`: the MCP server behind `/__abide/mcp` — tools derived from every `clients.mcp` rpc and socket (a `<name>-tail` read tool, plus `<name>-publish` under `clientPublish`), prompts from `src/mcp/prompts/`, auth inherited from the inbound request, optional `authorize` hook. Framework-constructed; there is no user-authored server module.
 
 ## Testing
 
-### Testing — @documentation testing
-
-- `abide/test/createTestApp` — boot an in-process app for tests: typed `app.rpc.<rpc>` / `app.sockets.<name>` off the project's real surface. Also `TestApp`, `RpcClient`, `SocketClient`.
-
-### Testing plumbing — @documentation plumbing
-
-- `abide/test/createScriptedSurface` — a scripted MCP surface for driving an `AgentEngine` in tests.
-- `abide/test/assertAgentFrameConformance` — assert an engine's frame stream satisfies the neutral `AgentFrame` contract.
+- `@abide/abide/test/createTestApp` — `@documentation testing` — boots the app in-process for `bun test`: typed `app.rpc.<name>` / `app.sockets.<name>` clients (typed via the generated `testRpc.d.ts` / `testSockets.d.ts`), request scope included, no network.
+- `@abide/abide/test/createScriptedSurface` — `@documentation plumbing` — a scripted `AgentSurface` for engine tests: declarative tool stubs in, an MCP surface out, every dispatched call recorded for assertions.
+- `@abide/abide/test/assertAgentFrameConformance` — `@documentation plumbing` — collects an engine's frame stream and asserts the neutral `AgentFrame` contract (exactly one terminal `done`, paired `tool_use`/`tool_result`, string deltas); returns the frames for provider-specific assertions.
 
 ## Generated machine surfaces
 
-Runtime routes the framework serves (the internal `/__abide/config|dev|reload|…`
-routes are deliberate plumbing and not listed):
-
 | Route | Serves |
 | --- | --- |
-| `/openapi.json` | OpenAPI 3 document, generated from every schema-bearing RPC |
-| `/__abide/mcp` | MCP endpoint (streamable HTTP): tools, prompts, resources |
-| `/__abide/health` | Health JSON (the app's `health()` hook merged in) |
-| `/__abide/sockets` | Multiplexed WebSocket hub; HTTP face `/__abide/sockets/<name>` (GET tail, POST publish) |
-| `/__abide/cli` | CLI binary download (per-platform thin client + server) |
-| `/__abide/hot` | Dev hot-update stream the browser bridge consumes for HMR |
-| `/__abide/identity` | App identity (name/version) for CLI/bundle connect handshakes |
-| `/__abide/inspector` | Opt-in inspector UI (gated by `ABIDE_ENABLE_INSPECTOR`) |
+| `/openapi.json` | The OpenAPI document projected from every rpc's method, URL, and schemas |
+| `/__abide/mcp` | The MCP endpoint (tools from rpcs/sockets, prompts, resources); auth flows from the inbound request |
+| `/__abide/health` | Liveness + identity JSON: framework version, app name/version, plus the app `health(request)` hook's fields; answered ahead of `app.handle` |
+| `/__abide/identity` | Compatibility alias for the same payload with the legacy `abide: true` marker |
+| `/__abide/sockets` | The single multiplexed WebSocket every client socket rides |
+| `/__abide/sockets/<name>` | A socket's HTTP face: `GET` = retained tail as JSON (SSE stream under `Accept: text/event-stream`; `?tail=N` caps/seeds), `POST` = publish gated by `clientPublish`; 404 unless the socket is exposed to mcp/cli |
+| `/__abide/cli` | `GET` = shell install script; `/__abide/cli/<platform>` streams the thin-CLI tarball (cli + server binaries, `.env` baked with `ABIDE_APP_URL`/`ABIDE_APP_TOKEN`) |
+| `/__abide/inspector` | The `@abide/inspector` UI, mounted only under `ABIDE_ENABLE_INSPECTOR=true` |
+| `/__abide/hot/<moduleId>` | Dev-only component hot-module endpoint backing `.abide` HMR |
 
 ## Environment variables
 
 | Variable | Effect |
 | --- | --- |
-| `PORT` | Server listen port |
-| `APP_URL` | Public origin; its pathname becomes the mount base (e.g. `/v2`) for `url()`/routing |
-| `ABIDE_APP_URL` | Default remote server URL the CLI/bundle connects to |
-| `ABIDE_APP_TOKEN` | Bearer token the CLI/bundle sends to a remote abide server |
-| `ABIDE_CLIENT_TIMEOUT` | ms ceiling on a browser/CLI remote RPC call (1–600000) |
-| `ABIDE_IDLE_TIMEOUT` | Bun per-connection idle timeout, seconds (default 10) |
-| `ABIDE_MAX_REQUEST_BODY_SIZE` | Server-wide max request body bytes |
-| `ABIDE_REACHABLE_TIMEOUT` | ms per `reachable()` probe (default 3000, 100–60000) |
-| `ABIDE_REACHABLE_TTL` | ms `reachable()` freshness / poll cadence (default 30000, 1000–600000) |
-| `ABIDE_DATA_DIR` | Override the per-user app data dir on every platform |
-| `ABIDE_LOG_FORMAT` | `json` emits structured log records instead of human lines |
-| `ABIDE_ENABLE_INSPECTOR` | `true` mounts the inspector (requires `@abide/inspector`) |
-| `ABIDE_INSPECT` | Non-empty enables the desktop webview devtools |
-| `DEBUG` | Enable diagnostic channels (`abide:cache`, `abide:rpc`, …); `-abide` silences all |
+| `PORT` | Binds that exact port (a collision fails loudly); unset, the server finds an open port from the default |
+| `APP_URL` | The app's public origin and optional mount base path (a bare `/v2` is tolerated); drives `url()` base-prefixing |
+| `ABIDE_APP_URL` | The remote server a thin CLI binary talks to (baked into its downloaded `.env`) |
+| `ABIDE_APP_TOKEN` | Bearer token the thin CLI sends; baked into the downloaded `.env` when the download request was authenticated |
+| `ABIDE_CLIENT_TIMEOUT` | Default browser-side rpc timeout in ms — read at server boot, shipped to the client via the SSR payload |
+| `ABIDE_DATA_DIR` | Overrides the per-user data directory on every platform |
+| `ABIDE_ENABLE_INSPECTOR` | `true` mounts `@abide/inspector` at `/__abide/inspector` (the package must be installed) |
+| `ABIDE_IDLE_TIMEOUT` | Bun per-connection idle timeout in seconds (default 10) |
+| `ABIDE_INSPECT` | Enables right-click → Inspect in the desktop bundle's webview |
+| `ABIDE_LOG_FORMAT` | `json` renders one JSON object per log line (default: tab-separated tsv) |
+| `ABIDE_MAX_REQUEST_BODY_SIZE` | Server-wide max request body bytes (a per-rpc `maxBodySize` refines it) |
+| `ABIDE_REACHABLE_TTL` | `reachable()` poll cadence / freshness in ms (default 30000) |
+| `ABIDE_REACHABLE_TIMEOUT` | `reachable()` per-probe bound in ms (default 3000) |
+| `DEBUG` | Channel-gated diagnostics (`DEBUG=abide:rpc`, `abide:sockets`, `abide:build`, …); `DEBUG=-abide` silences the framework's own channel |
 
 ---
 
-Mirrors the `exports` map in `package.json`; run
-`bun run packages/abide/scripts/readmeSurfaces.ts` after adding or renaming an
-export to catch any untagged export and re-derive the slug grouping.
+This file mirrors `package.json`'s `exports`; after adding or renaming an
+export, run `bun run packages/abide/scripts/readmeSurfaces.ts` and regenerate.