@abide/abide 0.33.1 → 0.34.0

package/AGENTS.md

@@ -25,13 +25,13 @@
 
 One declared verb fans out to every surface, with no extra work:
 
-```
+```text
        export const getMessages = GET(fn, { inputSchema })
                                  │
    ┌───────────────┬────────────┼──────────────┬────────────────┐
  SSR call      browser fetch    MCP tool      CLI subcommand   OpenAPI op
-cache(fn)()   fetch /rpc/...   (read-only +    app get-messages  /openapi.json
-(in-process)  (typed proxy)     schema → tool)  (schema → flags)  (described)
+cache(fn)()   fetch /rpc/...   getMessages   app get-messages  /openapi.json
+(in-process)  (typed proxy)  (read-only+schema) (schema→flags)   (described)
 ```
 
 A Standard Schema (zod / valibot / arktype, unadapted) is the contract: it
@@ -76,7 +76,7 @@ For `bun test`, add `preload = ["@abide/abide/preload"]` under `[test]` in `bunf
 
 ## Server surface — `abide/server/*` (and authored helpers)
 
-### RPC verbs — `@readme rpc`
+### RPC verbs — `@documentation rpc`
 Each is `Verb(fn, opts?)` with three overloads (see `src/lib/server/rpc/types/VerbHelper.ts`):
 `Verb(fn, { inputSchema, outputSchema?, filesSchema?, clients?, timeout?, maxBodySize?, crossOrigin? })`,
 `Verb(fn, { clients })`, and bare `Verb(fn)`. Return type usually infers from the
@@ -94,7 +94,7 @@ plain call decodes the body + throws `HttpError` on non-2xx; `.raw` resolves to
 `Response` undecoded; `.stream(args)` returns a `Subscribable` (SSE/JSONL frames, or
 the decoded body once) for `tail()`; `.fetch(req)` is framework-internal dispatch.
 
-### Responses — `@readme response`
+### Responses — `@documentation response`
 - `abide/server/json(data, init?)` — JSON with `Cache-Control: no-store`; `json(undefined)` → 204 that round-trips to `undefined`.
 - `abide/server/error(status, message?, init?)` — text/plain error; message defaults to the status reason phrase.
 - `abide/server/redirect(url, status=302, init?)` — accepts relative URLs (platform `Response.redirect` doesn't); 301/302/303/307/308.
@@ -102,29 +102,29 @@ the decoded body once) for `tail()`; `.fetch(req)` is framework-internal dispatc
 - `abide/server/sse(iterable, init?)` — wrap an `AsyncIterable` as Server-Sent Events; 15s keepalive; errors → `event: error`.
 - `abide/shared/HttpError` — thrown by remote calls on non-2xx; carries `status`, `statusText`, raw `response`.
 
-### Sockets — `@readme sockets`
+### Sockets — `@documentation sockets`
 - `abide/server/socket(opts?)` — declare a `Socket<T>` (an isomorphic `AsyncIterable<T>`) inside `src/server/sockets/<name>.ts`. Opts: `{ schema?, tail?, ttl?, clientPublish?, clients? }`. `tail: n` retains last n frames; `ttl` evicts older. HTTP face at `/__abide/sockets/<name>`: GET = retained tail, POST = publish (gated by `clientPublish`).
 
-### Agents — `@readme agent`
+### Agents — `@documentation agent`
 - `abide/server/agent(engine, messages)` — run a model engine against the app's own (already-gated) MCP surface; returns the engine's `AgentFrame` stream. Wrap in `jsonl()`/`sse()` to pick the transport. Types exported: `NeutralMessage`, `AgentFrame` (`text`/`tool_use`/`tool_result`/`done`), `AgentSurface`, `AgentEngine`. Engines live in `@abide/<provider>` packages, never in core.
 
-### Request scope — `@readme request-scope`
+### Request scope — `@documentation request-scope`
 Resolve only during an in-flight SSR render or RPC handler (throw outside one):
 - `abide/server/request()` → the inbound `Request`.
 - `abide/server/cookies()` → Bun `CookieMap`; writes flush as `Set-Cookie` on return.
 - `abide/server/server()` → active `Bun.serve` (or a no-op in-process server under CLI/MCP/test).
 
-### Config / data — `@readme configuration` / `reference`
+### Config / data — `@documentation configuration` / `reference`
 - `abide/server/env(schema, opts?)` — validate `Bun.env` against a Standard Schema at module top level; fails boot loudly. Registered so the bundle launcher derives its setup form.
 - `abide/server/appDataDir()` → the running bundle's per-user data dir (cwd-independent, pure).
 
-### Observability — `@readme observability`
+### Observability — `@documentation observability`
 - `abide/server/reachable(host)` — server-only outbound reachability; first call probes (HEAD), then warm-polls every TTL. Tuned by `ABIDE_REACHABLE_TTL` / `ABIDE_REACHABLE_TIMEOUT`.
 - `abide/shared/health()` → `HealthState` (framework + app `health()` hook payload, typed via generated `health.d.ts`); also at `/__abide/health`.
 - `abide/shared/log` — unified logger carrying request-scope context; `log()/warn/error/trace` on the app channel, `log.channel(name)` on a `DEBUG`-gated channel. `ABIDE_LOG_FORMAT=json` for JSON lines.
 - `abide/shared/trace()` → current W3C `traceparent` (isomorphic; client reads the SSR-stamped trace).
 
-### App / inspector types — `@readme plumbing`
+### App / inspector types — `@documentation plumbing`
 - `abide/server/AppModule` — shape of `src/app.ts` (error handler, health hook, lifecycle).
 - `abide/server/InspectorContext` — inspector wiring type.
 - `abide/server/rpc/defineVerb`, `abide/server/sockets/defineSocket`, `abide/server/prompts/definePrompt`, `abide/server/prompts/renderPromptTemplate` — bundler-emitted runtime bindings; you don't call these by hand (the `GET`/`socket`/`.md` files compile down to them).
@@ -133,24 +133,24 @@ Resolve only during an in-flight SSR render or RPC handler (throw outside one):
 
 ## Isomorphic surface — `abide/shared/*`
 
-### Cache — `@readme cache`
-- `abide/shared/cache(fnOrProducer)` → a memoised callable. Key auto-derives (method+url+args for a remote fn; producer-reference+args for a producer). Options `{ ttl?, scope?, global?, swr? }`: `ttl` ms-past-resolve (omit = forever, `0` = dedupe-only / the **mutation idiom**); `scope` tags for group invalidation; `global` = process-level store (server); `swr` = stale-while-revalidate — on invalidate, keep the stale value (reader sees `refreshing()`, not `pending()`) and refetch in the background. `swr: true` refetches immediately; `swr: { throttle | debounce }` adds a coalescing window. GET-only, throws on a write.
-- `cache.invalidate(selector?, args?)` — end retention early (by fn, fn+args, `{ scope }`, or all).
+### Cache — `@documentation cache`
+- `abide/shared/cache(fnOrProducer)` → a memoised callable. Key auto-derives (method+url+args for a remote fn; producer-reference+args for a producer). Options `{ ttl?, tags?, global?, swr? }`: `ttl` ms-past-resolve (omit = forever, `0` = dedupe-only / the **mutation idiom**); `tags` for group invalidation; `global` = process-level store (server); `swr` = stale-while-revalidate — on invalidate, keep the stale value (reader sees `refreshing()`, not `pending()`) and refetch in the background. `swr: true` refetches immediately; `swr: { throttle | debounce }` adds a coalescing window. GET-only, throws on a write.
+- `cache.invalidate(selector?, args?)` — end retention early (by fn, fn+args, `{ tags }`, or all).
 - `cache.patch(selector, updater, args?)` — optimistic local fold over matching entries.
 - `cache.on(subscribable, (frame, ctx) => …)` — event-driven cache maintenance: run a handler per socket/stream frame; `ctx.invalidate` / `ctx.patch` are coverage-tracked and resync on reconnect. Client-only (no-op on server).
 
-### Probes — `@readme probes` (read-only; reading never triggers work)
+### Probes — `@documentation probes` (read-only; reading never triggers work)
 - `abide/shared/pending(selector?, args?)` — "no value yet" (in-flight call, or stream awaiting first frame).
 - `abide/shared/refreshing(selector?, args?)` — "holding a value while a fresher source is in flight".
 - `abide/shared/online()` — reactive connectivity probe (server: the calling client's reported state via offline header).
 
 Same selector grammar as `cache.invalidate`; also accept a `Subscribable`. See CONTEXT.md → Probe.
 
-### Routing / page — `@readme page` / `url`
+### Routing / page — `@documentation page` / `url`
 - `abide/shared/page` — reactive proxy: `route`, `params`, `url` (browser-space), `navigating`. Isomorphic; re-runs reactive readers on navigation.
 - `abide/shared/url(path, query?)` — type-safe URL builder; augmented by generated `RpcRoutes`/`PageRoutes`/`PublicAssets` for autocomplete. Applies mount base.
 
-### Templating values — `@readme plumbing`
+### Templating values — `@documentation plumbing`
 - `abide/shared/html` — `html\`...\`` tagged template → `RawHtml` (trusted markup); `rawHtmlString(v)`.
 - `abide/shared/snippet(payload)` → `Snippet` — a reusable template builder (the `<template name=…>` form).
 - `abide/shared/createSubscriber(start)` — the subscription primitive behind sockets/streams/probes.
@@ -159,53 +159,58 @@ Same selector grammar as `cache.invalidate`; also accept a `Subscribable`. See C
 
 ## UI surface — `abide/ui/*` (client-only)
 
-### Reactive primitives — `@readme plumbing` (in scope inside `.abide`, no import)
-- `abide/ui/state(initial, transform?)` → writable `State<T>` (`.value` getter/setter). Local truth. `transform(next, prev) => T` is a write-coercion gate: each `.value=` stores what it returns (`return prev` rejects via the `Object.is` no-op); construction `initial` is verbatim. Plain `state(x)` is a serializable doc slot; `state(x, transform)` is a non-serializing `.value` cell.
-- `abide/ui/linked(seed, transform?)` → writable `State<T>` seeded reactively from upstream (Angular's `linkedSignal`): owns a local value, reseeds when the `seed` thunk's deps change, edits stay local. `transform` gates reseeds and writes alike. Thunk seed is required (it is the reactivity); seed captured by reference (clone in the thunk for isolation). Non-serializing — reseeds on resume.
-- `abide/ui/derived(compute)` → lazy read-only computed (`.value`); re-derived on resume, never serialized. `derived(compute, set)` → writable lens: `.value` derives from upstream, assigning runs imperative `set(next)` to write *through* to the sources (no local store).
-- `abide/ui/effect(fn)` → run now, re-run on dependency change; `fn` may return teardown / be async; returns dispose.
-- `abide/ui/doc(initial?)` → reactive document: immutable tree addressed by path, every change a patch (the substrate under all reactivity / resumability / sync).
+### Reactive primitives — `@documentation plumbing` (declared through `scope()` in a `.abide` `<script>`; the runtime forms are NOT public exports)
+Reactive state is owned by a scope and declared explicitly through it: `const count = scope().state(0)` (or a captured handle: `const s = scope(); const count = s.state(0)`). A **bare** `state(...)` / `linked(...)` / `computed(...)` call is a compile error — the surface always shows the scope interaction. The declared binding is then read/written by its bare name (`{count}`, `count = count + 1`); the compiler lowers that to the doc API.
+- `scope().state(initial, transform?)` — local truth. Plain `state(x)` lowers to a serializable `model` (= `scope()`) doc slot. `state(x, transform)` is a write-coercion gate (`.value` cell).
+- `scope().linked(seed, transform?)` — a `.value` cell seeded reactively from upstream (Angular's `linkedSignal`): owns a local value, reseeds when the `seed` thunk's deps change, edits stay local. Non-serializing — reseeds on resume.
+- `scope().computed(compute)` → a read-only computed **doc slot** (`scope().derive("name", compute)`), referenced as `name()` (string-free reader): re-computed on resume, never serialized/journalled. Always read-only (no `set` overload) — a writable computed is expressed at the binding site (`bind:value={{ get, set }}`), where the write actually originates.
+- `prop('name')` → a read-only computed doc slot over the parent thunk (`scope().derive`), referenced as `name()`.
+- `abide/ui/effect(fn)` → run now, re-run on dependency change; `fn` may return teardown / be async; returns dispose. (`effect` IS still a public export.)
+- `abide/ui/scope(address?)` → `Scope` — **the data + capability seam; the only public way to reach reactive state.** The reactive document (immutable path-addressed tree, every change a patch — JSON Pointer keys via `escapeKey`, so a key may contain `/`) is now *internal* (`doc`/`createDoc`): a scope wraps one and mirrors its interface — `read`/`replace`/`add`/`remove`/`cell`/`derive`/`snapshot` (data; `derive(path, compute)` is a computed slot, never stored/serialized/journalled), `child`/`root`/`parent` (tree), `dispose`. Every applied patch is announced on an internal process-global patch bus (`PATCH_BUS`) carrying `{ doc, patch, inverse }` — the single tap undo / persistence / sync consume; computed recomputes never reach it. Capabilities route where the scope's changes go — `record({ limit? })` to an undo journal (then `undo`/`redo`/`canUndo`/`canRedo`), `persist(key?)` to durable storage (key defaults to the scope `id`), `broadcast(transport)` to peers. A passable value (`<Child parentScope={scope}/>`). `scope()` = the ambient current scope — `mount`/`hydrate` (client) and `enterScope`/`exitScope` (SSR, per render) establish one per component; the lowering emits `const model = scope()`, so `scope()`'s data IS the component's `state`; `scope('/')` = the root. Resolves correctly inside event handlers, effects, and attach teardowns (they pin the scope they were registered under).
+
+### Local-first queue — `@documentation ui`
+- `abide/ui/outbox({ key, send, store?, online?, onDrop? })` → `Outbox<T>` — durable FIFO queue for local-first writes; distinct from `scope().broadcast()` (which replicates *state*, not outbound mutations). `enqueue(payload)` records a serializable mutation (persisted via `persist`, so it survives a reload) and drains FIFO while `online()`; success dequeues, offline-mid-send keeps the head and retries on reconnect (auto-drains on the online edge), an online rejection drops the entry and reports via `onDrop` (roll back the optimistic change there). At-least-once → `send` should be idempotent. `pending()` is a reactive read for a sync indicator. Built on `doc` + `persist` + `online` (the queue is itself a persisted doc).
 
 ### Streams
 - `abide/ui/tail(subscribable)` → latest frame (`T | undefined`); `tail(x, { last: n })` → window `T[]`. Reactive latest-wins read of a socket/stream. `tail.status` / `tail.error` expose richer stream state. See CONTEXT.md → Tail.
 
-### Navigation / lifecycle — `@readme plumbing`
+### Navigation / lifecycle — `@documentation plumbing`
 - `abide/ui/navigate(path, replace?)` — client navigation.
 - `abide/ui/router(...)`, `abide/ui/startClient(...)`, `abide/ui/renderToStream(render)` — bootstrap/render runtime (compiler/launcher uses these).
 
-### DOM + render runtime — `@readme plumbing` (compiler-emitted; you don't hand-write these)
+### DOM + render runtime — `@documentation plumbing` (compiler-emitted; you don't hand-write these)
 `abide/ui/dom/{mount,mountChild,hydrate,text,appendText,appendTextAt,appendSnippet,appendStatic,cloneStatic,skeleton,anchorCursor,mountSlot,attr,on,attach,each,eachAsync,when,awaitBlock,tryBlock,switchBlock,applyResolved}` and `abide/ui/runtime/{nextBlockId,enterRenderPass,exitRenderPass}`. These are what `analyzeComponent → generateBuild/generateSSR` lower a `.abide` file into — every bound element builds through the parser-backed `skeleton` (one clone + located holes / `<!--a-->` anchors); there is no imperative element builder. Read them only to understand compiler output.
 - `abide/ui/remoteProxy`, `abide/ui/socketProxy` — the browser-side implementations the bundler swaps in for `GET(...)` / `socket(...)`.
 
 ### `.abide` component format (see `src/lib/ui/README.md`)
 Valid HTML with `<script>` + native `<template>` control flow + scoped `<style>`.
-- **Bindings:** `{expr}` text, `name={expr}` attr, `onclick={fn}`, `bind:value={…}` / `bind:checked` / `bind:group`, `attach={fn}` (node-lifetime attachment — the dual of `on`; the `use:`-action / `{@attach}` equivalent, lowered to `ui/dom/attach`).
+- **Bindings:** `{expr}` text, `name={expr}` attr, `onclick={fn}`, `bind:value={…}` / `bind:checked` / `bind:group`, `attach={fn}` (node-lifetime attachment — the dual of `on`; the `use:`-action / `{@attach}` equivalent, lowered to `ui/dom/attach`). A two-way `bind:` target is an **lvalue** (`count`, `model.lines[i]`) or an **accessor object** `bind:value={{ get, set }}` (reads via `get()`, writes via `set(v)`) — the only way to two-way-bind derived state; binding a read-only `computed` is a compile error.
 - **Control flow (native `<template>`):** `if` with a nested `else` (the `<template else>` is a CHILD of its `<template if>`, not a sibling), `each={list} as="x" key="x.id"`, `await={p}`/`then`/`catch`, `switch`/`case`/`default`.
-- **A branch is a lexical scope:** any control-flow branch may host its own nested `<script>` and `<style>`. The nested `<script>` declares branch-local **plain** signals (`state`/`derived`/`linked`/`prop`) — owned by the branch's render scope, re-seeded each mount (not the serializable top-level `doc`) — with the branch's binding in scope (`then`/`catch`'s `as` value, the `each` `as`/`key` row), so it can derive from the awaited/iterated value; its bindings cover the branch subtree and later siblings auto-deref them. The nested `<style>` is scoped to that branch alone (its own `data-a-<hash>`), not the whole component.
+- **A branch is a lexical scope:** any control-flow branch may host its own nested `<script>` and `<style>`. The nested `<script>` declares branch-local **plain** signals (`state`/`computed`/`linked`/`prop`) — owned by the branch's render scope, re-seeded each mount (not the serializable top-level `doc`) — with the branch's binding in scope (`then`/`catch`'s `as` value, the `each` `as`/`key` row), so it can derive from the awaited/iterated value; its bindings cover the branch subtree and later siblings auto-deref them. The nested `<style>` is scoped to that branch alone (its own `data-a-<hash>`), not the whole component.
 - **Components:** capitalised tags (`<Layout title=…>`); children fill `<slot/>`; props are reactive (passed as thunks). A component has no directives — every attribute is a prop under its written name (so `onclick=`/`bind:open=`/`attach=` pass through as props, e.g. callbacks, not the DOM-element directives those are on a lowercase tag) and is type-checked against the child's declared props. `prop('name')` reads a typed component prop (the parent-supplied thunk, reactive + read-only); route params come from the `page` proxy (`page.params.name`), not `prop()`.
 - **Snippets / named slots:** `<template name="x" args={…}>` declares a reusable named builder (the `snippet()` form), rendered like a function — covers named slots / `{@render}`.
 - **Reactivity:** write plain assignment (`count += 1`, `items.push(x)`); the compiler lowers it to patches. Deep-field edits wake only that field.
-- **SSR:** byte-identical HTML string; `renderToStream` ships the shell then streams `<template await>` fragments out of order; `hydrate` adopts static structure in place (control-flow blocks + child components fall back to `mount`/re-render — known gap).
+- **SSR:** byte-identical HTML string; `renderToStream` ships the shell then streams `<template await>` fragments out of order; `hydrate` adopts the server DOM in place — static structure, `if`/`else`, keyed `each`, `switch`, `try`, and child components/slots all claim existing nodes (no re-render; focus/scroll/input preserved). The one cold-rebuild case left is a genuinely-pending `await` that is neither resumable (`RESUME[id]`) nor cache-warm — it discards the boundary and builds the pending branch fresh; an `await` over a `cache`d read is warm on resume and adopts without a flash.
 
 ---
 
-## Build / tooling — `@readme plumbing`
+## Build / tooling — `@documentation plumbing`
 - `abide/ui-plugin` — Bun loader plugin for `.abide` files.
 - `abide/resolver-plugin` — resolves the `$server`/`$ui`/virtual modules and swaps server↔client runtime per target.
 - `abide/preload` — Bun preload registering both plugins (use in `bunfig.toml` `[test]`).
 - `abide/build`, `abide/compile` — programmatic build / standalone-executable compile.
 - `abide/tsconfig` — base tsconfig for consumer apps.
 
-## Desktop bundle — `@readme bundle`
+## Desktop bundle — `@documentation bundle`
 - `abide/bundle/BundleWindow` — `src/bundle/window.ts` default-export shape (`title`, `width`, `height`, `menu`, `config` schema for the first-run setup form).
 - `abide/bundle/BundleMenu`, `abide/bundle/BundleMenuItem` — custom menu types.
 - `abide/bundle/onMenu(handler)` / `onMenu(name, handler)` — subscribe to native menu clicks (returns unsubscribe; drop into an `effect`). Inert outside the bundle.
 - `abide/bundle/bundled()` — true inside the desktop webview (isomorphic detection).
 
-## MCP — `@readme plumbing`
+## MCP — `@documentation plumbing`
 - `abide/mcp/createMcpServer(opts)` — framework-internal; the `abide:mcp` virtual constructs it. Tools derive from verbs/sockets flagged `clients.mcp: true`; auth inherits from the inbound request; optional `authorize` hook. Served at `/__abide/mcp`.
 
-## Testing — `@readme testing`
+## Testing — `@documentation testing`
 - `abide/test/createTestApp()` → `TestApp` with typed `RpcClient` / `SocketClient` — in-process dispatch, no network.
 - `abide/test/createScriptedSurface(...)` — records tool dispatches for engine tests.
 - `abide/test/assertAgentFrameConformance(...)` — the frame contract every engine must satisfy (exactly one `done`, last; every `tool_use` answered by a same-id/name `tool_result`).
@@ -240,5 +245,5 @@ Valid HTML with `<script>` + native `<template>` control flow + scoped `<style>`
 
 *Maintenance (abide repo only): this file mirrors `package.json` `exports`. After
 adding/renaming an export, run `bun run scripts/readmeSurfaces.ts` from
-`packages/abide/` (it lists every export by `@readme` slug and fails on any untagged
-one) and reflect the change here.*
+`packages/abide/` (it lists every export by `@documentation` slug and fails on any
+untagged one) and reflect the change here.*

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # abide
 
+## 0.34.0
+
+### Minor Changes
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - make scope() the sole reactive surface ([`7484b44`](https://github.com/briancray/abide/commit/7484b44034542a9bdbdaeedd6c8b9bb08c71f2cf))
+
+### Patch Changes
+
+- [`1593504`](https://github.com/briancray/abide/commit/159350461d6b1070bd0981c7a8ae049655eb1c7d) - drop unused Doc import from Scope type ([`383669b`](https://github.com/briancray/abide/commit/383669b957648e4393e4df341dc9e1b01303fab5))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - rename selector "scope" to "tags" ([`38c41c8`](https://github.com/briancray/abide/commit/38c41c838091448c1477f588e6fafc4e566f9830))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - rename @readme export tag to @documentation ([`7045cfb`](https://github.com/briancray/abide/commit/7045cfbe5a9d3f69d165cb91fd01355f76162495))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - preserve template-literal whitespace when indenting module bodies ([`89d975a`](https://github.com/briancray/abide/commit/89d975ae58dc4459c85909f414e0e46431924103))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - resolve scope() in the shadow program and map binding names ([`a06c38a`](https://github.com/briancray/abide/commit/a06c38a08d417bd45509c58d661caa5f45b34ae3))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - migrate to the scope() authoring surface ([`b0691fc`](https://github.com/briancray/abide/commit/b0691fc56746e516b7196eec008c063c0dda5e6d))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - rewrite scope() to avoid assignment-in-expression ([`c6e021b`](https://github.com/briancray/abide/commit/c6e021b68401bb30e55f11cf587a4b1bdf6f41c9))
+
+- [`3697394`](https://github.com/briancray/abide/commit/3697394b693f82266dadd227033d08cacd9df0bf) - regenerate README/AGENTS and refocus the write-readme skill ([`d40a3fe`](https://github.com/briancray/abide/commit/d40a3fec152c339f267327a95348af51c1f62027))
+
 ## 0.33.1
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,11 @@
 # abide
 
-**A type-safe isomorphic framework built on web standards and Bun. Zero runtime dependencies, single runtime.**
+**Write one function. Get a typed HTTP endpoint, a CLI, an MCP tool, and an OpenAPI operation — from the same line of code.**
 
-abide is not just a web framework. Strongly-typed RPCs surface through HTTP, a CLI, and an MCP, with a full OpenAPI spec. Everything is generated for you with zero additional work - but you control surface exposure. Its a framework built for humans *and* machines.
+abide is a type-safe isomorphic framework built on web standards and Bun. You declare a verb once; the bundler swaps the runtime per side and projects that one declaration onto every surface — humans hit it over HTTP or the CLI, machines hit it over MCP, and you control which surfaces each verb exposes. It's a framework built for humans *and* machines.
+
+- Zero runtime dependencies
+- A single runtime (Bun) in every mode — dev, build, and compiled binary
 
 ## Quick start
 
@@ -10,7 +13,7 @@ abide is not just a web framework. Strongly-typed RPCs surface through HTTP, a C
 bunx abide scaffold my-app   # scaffolds, installs, and starts the dev server
 ```
 
-To see a full demo, clone the repo and run the kitchen-sink example — every surface is a runnable, documented page:
+To see every surface live, clone the repo and run the kitchen-sink example — each page is runnable and documented:
 
 ```sh
 git clone https://github.com/briancray/abide
@@ -18,9 +21,7 @@ cd abide && bun install
 cd examples/kitchen-sink && bun run dev
 ```
 
-## Three foundational primitives
-
-### RPCs
+## RPCs
 
 An RPC is a handler wrapped by its HTTP method — one export per file under `src/server/rpc/`. The file path is the URL; the schema validates args and projects the MCP tool, CLI flags, and OpenAPI operation. Standard Schema is the contract: zod, valibot, and arktype work unadapted.
 
@@ -50,13 +51,13 @@ cache(fn)()   fetch /rpc/...   getMessages   app get-messages  /openapi.json
 (in-process)  (typed proxy)  (read-only+schema) (schema→flags)   (described)
 ```
 
-The same callable is consumed differently per side — `cache(getMessages)({ room })` in-process, the swapped `fetch` in the browser, `.raw(args)` for a `Response`, `.stream(args)` for `tail()`. A schema gates the machine surfaces: it unlocks CLI and (for read-only verbs) MCP; a mutating verb never auto-exposes to MCP — it needs an explicit `clients: { mcp: true }`. Per-verb `timeout` (504, on every surface) is distinct from the client-side `ABIDE_CLIENT_TIMEOUT`.
+The same callable is consumed differently per side — `cache(getMessages)({ room })` in-process, the swapped `fetch` in the browser, `.raw(args)` for a `Response`, `.stream(args)` for `tail()`. A schema gates the machine surfaces: it unlocks the CLI and (for read-only verbs) MCP; a mutating verb never auto-exposes to MCP — it needs an explicit `clients: { mcp: true }`. Per-verb `timeout` (504, on every surface) is distinct from the client-side `ABIDE_CLIENT_TIMEOUT`.
 
 > Query args travel as strings — use `z.coerce.*` so numbers and booleans validate.
 
-### Sockets
+## Sockets
 
-One broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — every socket multiplexes onto one ws at `/__abide/sockets`.
+One broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — every socket multiplexes onto one ws at `/__abide/sockets`. A `schema` validates publishes, infers the frame type, and flips on the MCP/CLI read faces.
 
 ```ts
 // src/server/sockets/chat.ts
@@ -70,11 +71,11 @@ export const chat = socket({ schema, tail: 100, ttl: 3_600_000 })
 export type ChatMessage = z.infer<typeof schema>
 ```
 
-For clients that can't speak the ws multiplex, each socket has an HTTP face at `/__abide/sockets/<name>` — `GET` returns the retained tail, `POST` publishes (gated by `clientPublish`).
+For clients that can't speak the ws multiplex, each socket has an HTTP face at `/__abide/sockets/<name>` — `GET` returns the retained tail, `POST` publishes (gated by `clientPublish`, off by default).
 
-### Components
+## Components
 
-Components are `.abide` files — valid HTML with `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. The reactive primitives (`state`, `derived`, `effect`, `prop`) are in scope without import. This page reads the verb above through `cache()`, tails the socket live, and exercises most of the template grammar:
+Components are `.abide` files — valid HTML with `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. Reactive state is reached through `scope()` (`scope().state(v)`, `scope().computed(fn)`); `prop` and `effect` are in scope without import. This page reads the verb above through `cache()`, tails the socket live, and exercises most of the template grammar:
 
 ```html
 <script>
@@ -85,19 +86,19 @@ import { publishChat } from '$server/rpc/publishChat.ts'
 import { chat } from '$server/sockets/chat.ts'
 import Avatar from '$ui/Avatar.abide'
 
-let room = prop('room')                                  // typed via src/.abide/routes.d.ts
-const history = derived(() => cache(getMessages)({ room })) // SSR snapshot + reactive refetch
-const latest = derived(() => tail(chat))                 // re-renders on every new frame
+let room = prop('room')                                            // typed via src/.abide/routes.d.ts
+const history = scope().computed(() => cache(getMessages)({ room })) // SSR snapshot + reactive refetch
+const latest = scope().computed(() => tail(chat))                  // re-renders on every new frame
 
-let from = state('alice')
-let text = state('')
-let filter = state('all')        // all | mine | others
-let onlyUnread = state(false)
+let from = scope().state('alice')
+let text = scope().state('')
+let filter = scope().state('all')        // all | mine | others
+let onlyUnread = scope().state(false)
 
 async function send(event: SubmitEvent) {
     event.preventDefault()
     if (text.trim() === '') return
-    await publishChat({ room, from, text })              // server validates, then broadcasts
+    await publishChat({ from, text })                              // server validates, then broadcasts
     text = ''
 }
 </script>
@@ -150,5 +151,4 @@ async function send(event: SubmitEvent) {
 </style>
 ```
 
-
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.33.1",
+    "version": "0.34.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -72,11 +72,11 @@
         "./shared/trace": "./src/lib/shared/trace.ts",
         "./shared/url": "./src/lib/shared/url.ts",
         "./shared/createSubscriber": "./src/lib/shared/createSubscriber.ts",
-        "./ui/state": "./src/lib/ui/state.ts",
-        "./ui/linked": "./src/lib/ui/linked.ts",
-        "./ui/derived": "./src/lib/ui/derived.ts",
         "./ui/effect": "./src/lib/ui/effect.ts",
-        "./ui/doc": "./src/lib/ui/doc.ts",
+        "./ui/scope": "./src/lib/ui/scope.ts",
+        "./ui/enterScope": "./src/lib/ui/enterScope.ts",
+        "./ui/exitScope": "./src/lib/ui/exitScope.ts",
+        "./ui/outbox": "./src/lib/ui/outbox.ts",
         "./ui/dom/mount": "./src/lib/ui/dom/mount.ts",
         "./ui/dom/mountChild": "./src/lib/ui/dom/mountChild.ts",
         "./ui/dom/hydrate": "./src/lib/ui/dom/hydrate.ts",

package/src/abideResolverPlugin.ts

@@ -99,7 +99,7 @@ Also rewrites modules under src/server/rpc and src/server/sockets:
   defineSocket on the server (with the socket name + opts) or
   socketProxy on the client (name only — opts are server-side).
 */
-// @readme plumbing
+// @documentation plumbing
 export function abideResolverPlugin({
     cwd = process.cwd(),
     embedAssets = false,

package/src/build.ts

@@ -32,7 +32,7 @@ last-good server) survives instead of crashing and orphaning the child. By
 default a failure exits the process (one-shot `abide build` / `compile`);
 the dev orchestrator passes `exitOnFailure: false`.
 */
-// @readme plumbing
+// @documentation building
 export async function build({
     cwd = process.cwd(),
     minify = true,

package/src/compile.ts

@@ -16,7 +16,7 @@ entry. Defaults
 the target to the host platform and appends `.exe` for windows targets.
 Returns the path of the emitted binary; exits the process on build failure.
 */
-// @readme plumbing
+// @documentation building
 export async function compile({
     cwd = process.cwd(),
     target = detectTarget(),

package/src/lib/bundle/BundleMenu.ts

@@ -5,7 +5,7 @@ A top-level bundle menu, inserted into the macOS menu bar between the standard
 Edit and Window menus. `label` titles the menu; `items` are its entries top to
 bottom.
 */
-// @readme bundle
+// @documentation bundle
 export type BundleMenu = {
     label: string
     items: BundleMenuItem[]

package/src/lib/bundle/BundleMenuItem.ts

@@ -18,7 +18,7 @@ calls `webview_navigate` with the given URL (the native side, on the UI thread).
 That's how the built-in Server menu drives the connect screen — `emit` reaches
 the loaded page, `navigate` repoints the window itself.
 */
-// @readme bundle
+// @documentation bundle
 export type BundleMenuItem =
     | { separator: true }
     | { label: string; shortcut?: string; emit: string }

package/src/lib/bundle/BundleWindow.ts

@@ -13,7 +13,7 @@ built-in File menu (Start server / Connect / Disconnect) are always installed.
 `menu` adds custom top-level menus between the Edit and Window menus; their items
 emit `abide:menu` events the app handles. See BundleMenuItem.
 */
-// @readme bundle
+// @documentation bundle
 export type BundleWindow = {
     title?: string
     width?: number

package/src/lib/bundle/bundled.ts

@@ -26,7 +26,7 @@ its *rendering context* (the webview) is inside it.
 Distinct from runningAsStandaloneBinary(), which is also true for a plain compiled
 (install-tarball) server binary — still a web app, not a bundle.
 */
-// @readme bundle
+// @documentation bundle
 export function bundled(): boolean {
     if (typeof window === 'undefined') {
         return Boolean(Bun.env.ABIDE_PARENT_PID)