@abide/abide 0.39.0 → 0.40.1

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # abide
 
+## 0.40.1
+
+### Patch Changes
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - share a single TS printer across compile passes ([`0626e68`](https://github.com/briancray/abide/commit/0626e68500b6cc8e7e2c770184ec4aa0fd06106d))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - bind-check generated modules and collect identifiers via AST ([`1e9d350`](https://github.com/briancray/abide/commit/1e9d3506873121ffd978039653f920edbed6c9ce))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - value-memoised push-pull reactivity (CLEAN/CHECK/DIRTY) ([`2ae8f14`](https://github.com/briancray/abide/commit/2ae8f141da5873bea0eb31a9a59d81182ca5a12a))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - syntax fuzz corpus for the identifier-rewrite passes ([`2e7d604`](https://github.com/briancray/abide/commit/2e7d6043aeeb9ca894bdb45f3f27893fbc5bf2f8))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - build control-flow subtrees untracked ([`33c0d8e`](https://github.com/briancray/abide/commit/33c0d8e834e5145a84d872ff496df122bbb0da95))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - lower the component script in a single parse ([`53098f8`](https://github.com/briancray/abide/commit/53098f8c2fe36e46e61b41d8a617aba6ac75e96f))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - regenerate README and AGENTS surface map ([`6bb6a39`](https://github.com/briancray/abide/commit/6bb6a3906d5aba522a4fe33bffae0911adf0b0fe))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - spread reactive page.params before postMessage in inspector bridge ([`7c99395`](https://github.com/briancray/abide/commit/7c993959e9dfc0c7f7038f694f95b59093a10dfc))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - make signal-rewrite parent-independent ([`868717a`](https://github.com/briancray/abide/commit/868717a6f7ff824b24ef8a96e5e5f59add5ceed1))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - pick runtime imports by tokenizing the output, not substring grep ([`a102986`](https://github.com/briancray/abide/commit/a102986bef90609297246ea001528a32e111be53))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - re-apply saved scroll offset until async content grows the page ([`a813b47`](https://github.com/briancray/abide/commit/a813b47387289c0049e63997a72a6805e461b18c))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - aliased import mangled when its name collides with a signal ([`abfe25d`](https://github.com/briancray/abide/commit/abfe25dcf7c00e61156b5d36fe82f290fc6c4cfb))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - granular reactive page snapshot + in-place same-route navigation ([`b561eb5`](https://github.com/briancray/abide/commit/b561eb52439577d3a75a7872befee4b9f0e98267))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - lower the component script in a literal single parse ([`b72b238`](https://github.com/briancray/abide/commit/b72b238377ff6545de549589d36b49ad4ecebb2d))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - chain per-expression lowering over a single parse ([`d808317`](https://github.com/briancray/abide/commit/d808317d817ae8a414695b7bfb037b8aff7017c3))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - classify signal-rewrite positions at visit time ([`d99577e`](https://github.com/briancray/abide/commit/d99577e2ac77d8742088608fba554ff5c2e799a4))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - make template-node generators exhaustive ([`e0f246d`](https://github.com/briancray/abide/commit/e0f246dfbbf4ea4f2dc481fc543a6e9f0a6fa43b))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - lower ++/-- on a doc path; guard the whole generated module ([`f49c122`](https://github.com/briancray/abide/commit/f49c122354fc4ef65f4c44db820d703078dd57f4))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - fold SSR effect-stripping into the single-parse chain ([`fa4515d`](https://github.com/briancray/abide/commit/fa4515d07164765ea0ee609cf1847535a41f95ed))
+
+## 0.40.0
+
+### Minor Changes
+
+- [`05ea7e2`](https://github.com/briancray/abide/commit/05ea7e235b1e7c035d3b4313e12fc83733fa814b) - <template elseif> conditional chains ([`c3237cc`](https://github.com/briancray/abide/commit/c3237ccc0d222c36e8b00ce68595eb92609ef856))
+
+- [`15c0ad3`](https://github.com/briancray/abide/commit/15c0ad334f698dfb49a9dcd0e0361925afc4f6c8) - `navigate` takes an options object — `navigate(path, { replace?, keepScroll? })` — replacing the old `navigate(path, replace?)` boolean. **Breaking:** a caller passing a boolean (`navigate(path, true)`) must migrate to `navigate(path, { replace: true })`; a bare `navigate(path)` is unchanged. The new `keepScroll` flag carries the live scroll offset onto the destination entry so an in-page URL swap — e.g. selecting another episode on the same detail page — restores to the current position instead of jumping to top. A push re-buckets the offset under the freshly minted entry id; a `replace` keeps the entry's bucket instead of discarding it.
+
+- [`ba56bb2`](https://github.com/briancray/abide/commit/ba56bb28be06fa0a11ab57fb10fa2d6b75ab8656) - Add `share`/`shared` context to `scope()`. The reactive doc does not inherit down the scope tree (each scope owns a separate document), so passing a value from an ancestor to a descendant previously meant threading it through every layer as props. `scope().share(key, value)` now puts a named value on a scope's own side-map, and `scope().shared(key)` reads the closest ancestor (self included) that has the key — an existence-checked, non-tracking upward walk, returning `undefined` when no scope provides it. The value is held by reference and the lookup never subscribes, so reactive context is expressed by sharing a `cell` (or a scope) rather than a plain object — reactivity rides what you share, not the share itself. A shared `undefined` shadows an ancestor (the walk stops on `has`, not truthiness). The shared map is released on `dispose`.
+
+### Patch Changes
+
+- [`a5a37f9`](https://github.com/briancray/abide/commit/a5a37f94258a56c4f24eb2b5539a280ce877bdfc) - extract resolveBranches for branch lookup ([`19a28a1`](https://github.com/briancray/abide/commit/19a28a1236e38a78c53a2adff0a981c8ad20b698))
+
+- [`a5a37f9`](https://github.com/briancray/abide/commit/a5a37f94258a56c4f24eb2b5539a280ce877bdfc) - sync AGENTS.md surface map for scope share/shared and navigate options ([`3e41255`](https://github.com/briancray/abide/commit/3e4125516164c94cfe9c9e6baa35f9ff9ec9c3e0))
+
+- [`a5a37f9`](https://github.com/briancray/abide/commit/a5a37f94258a56c4f24eb2b5539a280ce877bdfc) - use Promise.withResolvers in runWithVerbTimeout ([`504bdca`](https://github.com/briancray/abide/commit/504bdcac285cfd3762c8390fd1b6d640e62029bc))
+
+- [`a5a37f9`](https://github.com/briancray/abide/commit/a5a37f94258a56c4f24eb2b5539a280ce877bdfc) - extract VerbBaseOpts for shared verb options ([`d7414ca`](https://github.com/briancray/abide/commit/d7414cab7a557b54395321026d818b9fba82ba34))
+
+- [`ccc7f87`](https://github.com/briancray/abide/commit/ccc7f879d0506af084335785026200aeb38fdde4) - `on()` no longer attaches a non-function event handler. A component that omits an optional `on*` prop forwards it as `undefined`, yet the compiler still emits the `on()` call — so the listener fired `undefined(event)` and threw "handler is not a function" on every matching event (a keystroke or input on a search box, a click, …). `on()` now skips attaching when the handler is not a function, so an omitted optional handler is a no-op rather than a per-event crash.
+
+- [`c29dcd2`](https://github.com/briancray/abide/commit/c29dcd2796b5caa3ee41857aa612322b1e4220fa) - Parse `html`-branded raw markup in the parent's namespace. The client-side raw-HTML
+  binding parsed markup by setting `innerHTML` on a throwaway `<div>`, so the fragment
+  parser always used the HTML namespace — markup bound inside an `<svg>` produced
+  HTML-namespaced `<path>`/`<circle>` elements that exist in the DOM but never render.
+  This only surfaced on client-created or re-rendered nodes; the initial SSR/hydration
+  path adopts the server markup verbatim and kept the correct namespace, so an icon
+  component (`{html(svgInnerMarkup)}` inside `<svg>`) rendered on first paint but
+  vanished the moment its subtree was rebuilt on the client (e.g. a live cache delta).
+  A new `parseRawNodes` helper picks an SVG holder when the parent is SVG-namespaced,
+  shared by both `appendText` and `appendTextAt`.
+
+- [`9a74da6`](https://github.com/briancray/abide/commit/9a74da67c1f65cdb37e7a47af2e7b104cfe7620f) - Stop the signal-ref rewrite from descending into type space. `renameSignalRefs` rewrote every value-position identifier matching a signal name, but never skipped TypeScript type aliases, interfaces, or type annotations — so a component that destructures a prop (`const { option, ...rest } = props<Props>()`) and names that prop in its own type (`type Props = { option?: (value: T) => unknown; … }`) had the type member rewritten into a call (`option(): …`). This only surfaced once a `...rest` binding forced the named prop type to be emitted into the build (a no-rest `props<{…}>()` strips its type argument); with simple property types the mangle landed as accidentally-valid method-signature syntax, but optional/function/union members (`option?: (v) => unknown`, `value?: T | T[] | string`) became invalid TS and failed the page build. The visitor now leaves type aliases, interfaces, and any type node untouched — type space never holds a runtime read, and types erase at build regardless.
+
+- [`92597f0`](https://github.com/briancray/abide/commit/92597f0cbabc1e44449c0f0f812048481c38c579) - RPC bodies and socket frames now ship as ref-json (cycles, shared references, and
+  the types JSON drops/coerces — `undefined`, `bigint`, `Date`, `Map`, `Set`, `NaN`,
+  `±Infinity`, `-0` — survive the wire), and the server still accepts ordinary JSON from
+  non-abide clients. abide's own client flags a ref-json body with the `abide-ref-json`
+  header so the server decodes it with the matching codec; a request without the header
+  (curl, an OpenAPI-generated SDK, a webhook) is read with plain `JSON.parse`, so the
+  documented HTTP/OpenAPI body contract keeps working. The header is the discriminator
+  rather than the payload shape because ref-json's `[root, slots]` envelope is ambiguous
+  with a legitimate plain-JSON two-element array body. Socket frames need no header — a
+  frame is always an object, never the envelope array, so a plain-JSON frame falls back
+  to `JSON.parse` unambiguously.
+
 ## 0.39.0
 
 ### Minor Changes

package/README.md

@@ -1,159 +1,157 @@
 # abide
 
-**One typed RPC declaration fans out to an HTTP route, a typed browser proxy, a CLI subcommand, an MCP tool, and an OpenAPI operation — built for humans and machines.**
+**One typed declaration fans out to HTTP, a CLI, an MCP tool, and an OpenAPI
+spec — and the bundler swaps the runtime per side.**
 
-abide is an isomorphic framework on Bun: the same callable has the same name and behaviour on both sides, and the bundler swaps the runtime per side — a server handler in `src/server`, a `fetch` proxy in the browser. Server-render and hydrate the same `.abide` components, broadcast over multiplexed sockets, and expose every read to an agent — all in a single Bun runtime.
+abide is an isomorphic framework on Bun and web standards: you declare a verb,
+a socket, or a component once, and the same callable runs server-side, in the
+browser, from the terminal, and from an agent — the bundler decides which
+runtime each side gets. Built for humans *and* machines.
 
-- One dependency (`typescript`, for the type-checking shadow); `tailwindcss` + `bun-plugin-tailwind` are optional peers.
-- Runs on Bun `>= 1.3.0`. No bundler config, no server framework, no client router to wire up.
+- One direct dependency — the TypeScript compiler, used by `abide check`.
+  Tailwind is an optional peer. Everything runs on a single Bun runtime
+  (≥ 1.3.0); no second toolchain.
 
 ## Quick start
 
 ```sh
-bunx abide scaffold my-app   # scaffolds, installs deps, and (in a TTY) starts dev
+bunx abide scaffold my-app   # copies the template, installs, starts dev
 ```
 
-Or read the exhaustive demo:
+Or clone the kitchen-sink and run it:
 
 ```sh
 git clone https://github.com/briancray/abide
-cd abide && bun install
-cd examples/kitchen-sink && bun dev
+cd abide/examples/kitchen-sink
+bun install
+bun run dev
 ```
 
-The whole public surface — every export, CLI command, route, env var, and the `.abide` grammar — is mapped in [`AGENTS.md`](./AGENTS.md).
-
 ## RPCs
 
-An RPC is one export per file under `src/server/rpc/`. The file path is the URL (`getMessages.ts` → `/rpc/getMessages`), and a [Standard Schema](https://standardschema.dev) (zod / valibot / arktype, unadapted) validates the args and projects every other surface.
+An RPC is one export per file under `src/server/rpc/`. **The file path is the
+URL.** The schema validates arguments and projects the MCP tool, the CLI flags,
+and the OpenAPI operation. The contract is Standard Schema — zod, valibot, or
+arktype, unadapted.
 
 ```ts
-// src/server/rpc/getMessages.ts
+// src/server/rpc/getMessages.ts — file path is the route: GET /getMessages
 import { GET } from '@abide/abide/server/GET'
 import { json } from '@abide/abide/server/json'
 import { z } from 'zod'
-import { history } from '../../store.ts'
 
 const inputSchema = z.object({ room: z.string() })
 
-export const getMessages = GET(({ room }) => json({ messages: history(room) }), { inputSchema })
+export const getMessages = GET(({ room }) => json(board(room)), { inputSchema })
 ```
 
-That one declaration fans out:
+One declaration, five surfaces:
 
 ```text
-                  getMessages   (one declaration)
-                        │
-   ┌──────────┬─────────┼─────────┬──────────────┐
-   ▼          ▼         ▼         ▼              ▼
- SSR call   browser   MCP tool   CLI sub-     OpenAPI
-cache(fn)()  fetch   (read-only) command      operation
+              getMessages = GET(fn, { inputSchema })
+                              │
+   ┌───────────┬─────────────┼────────────┬──────────────┐
+ SSR call   browser fetch   MCP tool    CLI command    OpenAPI op
+cache(fn)() typed proxy()  (read-only)  abide ... cli  /openapi.json
 ```
 
-The `inputSchema` unlocks the CLI and — because a `GET`/`HEAD` is read-only — an MCP tool. A mutating verb (`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to an agent; opt in with `clients: { mcp: true }`. Consume the verb four ways, all typed against the declaration: `cache(getMessages)({ room })` for an SSR-memoized in-process read, the bundler-swapped `getMessages({ room })` `fetch` proxy in the browser, `.raw(args)` for the untouched `Response`, and `.stream(args)` for a frame-by-frame `jsonl`/`sse` body.
+A schema unlocks the CLI everywhere and MCP for read-only verbs; a mutating
+verb never auto-exposes to MCP — it needs explicit `clients: { mcp: true }`.
+Consume the verb four ways: `cache(getMessages)({ room })` resolves in-process
+during SSR, the same call hits a swapped `fetch` in the browser,
+`getMessages.raw(args)` returns the undecoded `Response`, and
+`getMessages.stream(args)` is an iterable view of the body.
 
-> Query args travel as strings — use `z.coerce.*` for numbers and booleans. The per-verb `timeout` option fires a `504` on every surface and is distinct from the client-wide `ABIDE_CLIENT_TIMEOUT`.
+> Query args travel as strings — validate with `z.coerce.*`. The per-verb
+> `timeout` (504 on every surface) is distinct from `ABIDE_CLIENT_TIMEOUT`.
 
 ## Sockets
 
-A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — `for await` it on the server, or read it reactively with `tail()` in a component — and every socket multiplexes onto one WebSocket at `/__abide/sockets`.
+A socket is one broadcast topic per file under `src/server/sockets/`. A
+`Socket<T>` is an isomorphic `AsyncIterable<T>`, and every socket multiplexes
+onto one websocket at `/__abide/sockets`.
 
 ```ts
-// src/server/sockets/messages.ts
+// src/server/sockets/messages.ts — topic name = file name: `messages`
 import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
-const schema = z.object({
-    id: z.string(),
-    room: z.string(),
-    from: z.string(),
-    text: z.string(),
-    at: z.number(),
-})
+const schema = z.object({ id: z.string(), room: z.string(), from: z.string(), text: z.string() })
 
-// retain the last 100 frames; lazily evict any older than an hour
-export const messages = socket({ schema, tail: 100, ttl: 3_600_000 })
+// retain the last 50 frames; evict any older than an hour
+export const messages = socket({ schema, tail: 50, ttl: 3_600_000 })
 export type Message = z.infer<typeof schema>
 ```
 
-The schema validates every publish and flips on the read surfaces (a `messages-tail` MCP tool / CLI command). For clients that can't speak the ws multiplex, each socket has an HTTP face at `/__abide/sockets/messages`: `GET` returns the retained tail, `POST` publishes — gated by `clientPublish` (default `false`, so browsers publish through a validating verb instead).
+The socket also has an HTTP face at `/__abide/sockets/messages`, for clients
+that can't speak the ws multiplex: `GET` returns the retained tail, `POST`
+publishes — gated by `clientPublish` (off by default, so the POST 403s).
 
 ## Components
 
-A component is an `.abide` file: valid HTML with a `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. `scope()` is the sole reactive surface; `props`, `effect`, and `html` are in scope without import. This one imports the verb and socket above:
+A `.abide` component is the payoff: it imports the verb and the socket above
+and ties them together with the native `<template>` grammar. Reactive state is
+reached only through `scope()` — `scope().state()` is writable,
+`scope().computed()` is read-only. `props()` and `effect()` are in-scope, no
+import.
 
 ```html
 <script>
 import { cache } from '@abide/abide/shared/cache'
 import { tail } from '@abide/abide/ui/tail'
 import { getMessages } from '$server/rpc/getMessages.ts'
-import { sendMessage } from '$server/rpc/sendMessage.ts'
+import { postMessage } from '$server/rpc/postMessage.ts'
 import { messages } from '$server/sockets/messages.ts'
 import Avatar from '$ui/Avatar.abide'
 
-const { room } = props<{ room: string }>()
+const { room = 'lobby' } = props<{ room?: string }>()
+
+// SSR-warm history; live frames then stream over the ws
+const seed = cache(getMessages)({ room })
+const live = scope().computed(() => tail(messages, { last: 50 }))
 
-let from = scope().state('alice')               // a writable cell — read/assign as a plain var
-let draft = scope().state('')
+let from = scope().state('alice')
+let text = scope().state('')
 let pinned = scope().state(false)
-let filter = scope().state('all')
-const live = scope().computed(() => tail(messages))   // re-renders on every new frame
-
-async function send(event: SubmitEvent) {
-    event.preventDefault()
-    if (draft.trim() === '') return
-    await sendMessage({ room, from, text: draft })     // a mutating verb
-    draft = ''
+let sort = scope().state('newest')
+
+async function send() {
+    await postMessage({ room, from, text })
+    text = ''
 }
 </script>
 
-<!-- a named snippet: a reusable builder, rendered like a function -->
 <template name="bubble" args={msg}>
-    <li><Avatar name={msg.from} /> <b>{msg.from}</b>: {msg.text}</li>
+    <li class="flex gap-2"><Avatar name={msg.from} /> <b>{msg.from}</b> {msg.text}</li>
 </template>
 
-<h1>#{room}</h1>
-
-<form onsubmit={send}>
-    <input bind:value={from} />
-    <input bind:value={draft} placeholder="message" />
+<form onsubmit={send} class="flex gap-2">
+    <input bind:value={from} class="border px-2" />
+    <input bind:value={text} placeholder="message" class="flex-1 border px-2" />
     <label><input type="checkbox" bind:checked={pinned} /> pin</label>
-    <label><input type="radio" bind:group={filter} value="all" /> all</label>
-    <label><input type="radio" bind:group={filter} value="mine" /> mine</label>
-    <button type="submit" disabled={draft.trim() === ''}>send</button>
+    <label><input type="radio" bind:group={sort} value="newest" /> newest</label>
+    <button disabled={!text} class="border px-3">send</button>
 </form>
 
-<template if={live}>
-    <p class="live">latest: {live.text}</p>
-    <template else>
-        <p>no messages yet</p>
-    </template>
-</template>
-
-<template switch={filter}>
-    <template case={'all'}><p>showing everyone</p></template>
-    <template case={'mine'}><p>showing {from}</p></template>
-    <template default><p>—</p></template>
+<template switch={sort}>
+    <template case={'newest'}><p class="text-xs">newest first</p></template>
+    <template default><p class="text-xs">oldest first</p></template>
 </template>
 
-<template await={cache(getMessages)({ room })}>
-    <p>loading…</p>
+<template await={seed}>
+    <p class="text-xs text-slate-500">loading…</p>
     <template then="history">
-        <ul>
-            <template each={history.messages} as="msg" key="msg.id">
+        <ul class="mt-3 space-y-1">
+            <template each={live ?? history} as="msg" key="msg.id">
                 {bubble(msg)}
             </template>
         </ul>
     </template>
-    <template catch="error">
-        <p>failed: {error.message}</p>
-    </template>
+    <template catch="err"><p class="text-rose-700">{err.message}</p></template>
 </template>
 
 <style>
-    .live {
-        font-weight: 600;
-    }
+    li { font-size: 0.875rem; }
 </style>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.39.0",
+    "version": "0.40.1",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

package/src/lib/server/rpc/parseArgs.ts

@@ -1,6 +1,8 @@
 import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
 import { contentTypeOf } from '../../shared/contentTypeOf.ts'
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { HttpError } from '../../shared/HttpError.ts'
+import { REF_JSON_HEADER } from '../../shared/REF_JSON_HEADER.ts'
 import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
 import { error } from '../error.ts'
 import { requestContext } from '../runtime/requestContext.ts'
@@ -92,7 +94,14 @@ export async function parseArgs(
             if (contentType.includes('application/json')) {
                 const text = await bounded.text()
                 if (text !== '') {
-                    body = JSON.parse(text)
+                    /* abide's own client flags ref-json with REF_JSON_HEADER (restores
+                       cycles/shared refs JSON can't carry); a non-abide client (curl, an
+                       OpenAPI SDK) omits it and sends ordinary JSON — read with plain
+                       JSON.parse, since the ref-json envelope is ambiguous with a 2-element
+                       array body. */
+                    body = bounded.headers.has(REF_JSON_HEADER)
+                        ? decodeRefJson(text)
+                        : JSON.parse(text)
                 }
             } else if (
                 contentType.includes('application/x-www-form-urlencoded') ||

package/src/lib/server/rpc/runWithVerbTimeout.ts

@@ -19,18 +19,16 @@ export function runWithVerbTimeout(
     ms: number,
     onTimeout: () => void,
 ): Promise<Response> {
-    let timer: ReturnType<typeof setTimeout> | undefined
     let timedOut = false
-    const deadline = new Promise<Response>((resolve) => {
-        timer = setTimeout(() => {
-            timedOut = true
-            onTimeout()
-            resolve(error(504, 'handler timeout'))
-        }, ms)
-    })
+    const deadline = Promise.withResolvers<Response>()
+    const timer = setTimeout(() => {
+        timedOut = true
+        onTimeout()
+        deadline.resolve(error(504, 'handler timeout'))
+    }, ms)
     return (async () => {
         try {
-            return await Promise.race([work, deadline])
+            return await Promise.race([work, deadline.promise])
         } finally {
             clearTimeout(timer)
             if (timedOut) {

package/src/lib/server/rpc/types/VerbHelper.ts

@@ -3,6 +3,21 @@ import type { RemoteFunction } from '../../../shared/types/RemoteFunction.ts'
 import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
 import type { RemoteHandler } from './RemoteHandler.ts'
 
+/*
+Options every verb overload accepts: the OpenAPI 200 `outputSchema`, the
+`clients` surface flags, the same-origin CSRF exemption (`crossOrigin`), the
+pre-parse body-byte ceiling (`maxBodySize`), and the per-surface handler
+`timeout` (ms). The schema-bearing overloads intersect this with their own
+`inputSchema`/`filesSchema` members.
+*/
+type VerbBaseOpts = {
+    outputSchema?: StandardSchemaV1
+    clients?: Partial<ClientFlags>
+    crossOrigin?: boolean
+    maxBodySize?: number
+    timeout?: number
+}
+
 /*
 Shared signature for every verb helper (GET / POST / …). Three overloads:
 
@@ -50,36 +65,18 @@ export type VerbHelper = {
             StandardSchemaV1.InferOutput<InputSchema> & StandardSchemaV1.InferOutput<FilesSchema>,
             Return
         >,
-        opts: {
+        opts: VerbBaseOpts & {
             inputSchema: InputSchema
             filesSchema: FilesSchema
-            outputSchema?: StandardSchemaV1
-            clients?: Partial<ClientFlags>
-            crossOrigin?: boolean
-            maxBodySize?: number
-            timeout?: number
         },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, Return>
     <Return = unknown, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
         fn: RemoteHandler<StandardSchemaV1.InferOutput<InputSchema>, Return>,
-        opts: {
-            inputSchema: InputSchema
-            outputSchema?: StandardSchemaV1
-            clients?: Partial<ClientFlags>
-            crossOrigin?: boolean
-            maxBodySize?: number
-            timeout?: number
-        },
+        opts: VerbBaseOpts & { inputSchema: InputSchema },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, Return>
     <Args = undefined, Return = unknown>(
         fn: RemoteHandler<Args, Return>,
-        opts: {
-            outputSchema?: StandardSchemaV1
-            clients?: Partial<ClientFlags>
-            crossOrigin?: boolean
-            maxBodySize?: number
-            timeout?: number
-        },
+        opts: VerbBaseOpts,
     ): RemoteFunction<Args, Return>
     <Args = undefined, Return = unknown>(
         fn: RemoteHandler<Args, Return>,

package/src/lib/server/runtime/SSR_SWAP_SCRIPT.ts

@@ -1,17 +1,18 @@
 /*
 The tiny inline script the abide-ui SSR stream ships in <head>. For each streamed
 `<abide-resolve data-id>` frame it reads the leading `<script type=application/json>`,
-registers the resolved value into
-`window.__abideResume` (the resume manifest hydration reads) and swaps the resolved
-markup into the matching `<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary —
-so the pending shell paints instantly and each value lands as it arrives, before
-the client bundle even loads. Vanilla and self-contained (no framework runtime),
-minified to one line so it inlines cheaply ahead of the document body.
+stores its raw ref-json text into `window.__abideResume` (the resume manifest hydration
+reads, decoding each entry at read time) and swaps the resolved markup into the matching
+`<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary — so the pending shell paints
+instantly and each value lands as it arrives, before the client bundle even loads. It
+stores the text undecoded precisely because it's vanilla and self-contained — no framework
+runtime, hence no ref-json decoder; the bundle decodes on read. Minified to one line so it
+inlines cheaply ahead of the document body.
 */
 export const SSR_SWAP_SCRIPT =
     "function __abideSwap(){var f=document.querySelector('abide-resolve');while(f){" +
     "var id=f.getAttribute('data-id'),p=f.firstChild,w=document.createTreeWalker(document.body,NodeFilter.SHOW_COMMENT),o=null,c;" +
-    "if(p&&p.nodeName==='SCRIPT'){try{(window.__abideResume=window.__abideResume||{})[id]=JSON.parse(p.textContent||'null');}catch(e){}p.remove();}" +
+    "if(p&&p.nodeName==='SCRIPT'){(window.__abideResume=window.__abideResume||{})[id]=p.textContent||'';p.remove();}" +
     "while((c=w.nextNode())){if(c.data==='abide:await:'+id){o=c;break;}}" +
     "if(o){var n=o.nextSibling;while(n&&!(n.nodeType===8&&n.data==='/abide:await:'+id)){var x=n.nextSibling;n.remove();n=x;}" +
     "while(f.firstChild){o.parentNode.insertBefore(f.firstChild,n);}}f.remove();f=document.querySelector('abide-resolve');}}"

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,5 +1,7 @@
 import type { ServerWebSocket } from 'bun'
 import { abideLog } from '../../shared/abideLog.ts'
+import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
 import { error } from '../error.ts'
@@ -104,7 +106,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         if (ws.readyState !== WebSocket.OPEN) {
             return
         }
-        ws.send(JSON.stringify(frame))
+        ws.send(encodeRefJson(frame))
     }
 
     function addSub(state: ConnectionState, name: string, sub: string): boolean {
@@ -312,11 +314,18 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             const text = typeof data === 'string' ? data : textDecoder.decode(data)
             let frame: SocketClientFrame
             try {
-                frame = JSON.parse(text) as SocketClientFrame
+                /* ref-json from abide's own client; a non-abide client sends a plain-JSON
+                   frame, which decodeRefJson rejects (a frame is always an object, never the
+                   `[root, slots]` envelope) — fall back to JSON.parse so raw WS clients work. */
+                try {
+                    frame = decodeRefJson(text) as SocketClientFrame
+                } catch {
+                    frame = JSON.parse(text) as SocketClientFrame
+                }
             } catch {
                 return
             }
-            // JSON.parse succeeds on `null`/`42`/`true`; ignore anything that isn't a frame object.
+            // both codecs yield a value for `null`/`42`/`true` too; ignore anything that isn't a frame object.
             if (typeof frame !== 'object' || frame === null) {
                 return
             }

package/src/lib/server/sockets/defineSocket.ts

@@ -1,4 +1,5 @@
 import { createPushIterator } from '../../shared/createPushIterator.ts'
+import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
 import { socketTapSlot } from '../../shared/socketTapSlot.ts'
 import type { TailHooks } from '../../shared/types/TailHooks.ts'
@@ -123,7 +124,8 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
                silently drift from this construction site (the dispatcher's `send` is already
                typed; this was the last `msg` frame built through an unchecked JSON.stringify). */
             const frame: SocketServerFrame = { type: 'msg', socket: name, message: validated }
-            server.publish(topic, JSON.stringify(frame))
+            // ref-json (matching the dispatcher + client) so a message graph with cycles/shared refs fans out intact.
+            server.publish(topic, encodeRefJson(frame))
         }
     }
 

package/src/lib/shared/REF_JSON_HEADER.ts

@@ -0,0 +1,9 @@
+/*
+Request header the RPC client stamps (value '1') when an `application/json` body is
+ref-json-encoded (encodeRefJson), so the server decodes with the matching codec.
+Its presence is the unambiguous discriminator: ref-json's `[rootValue, slots]`
+envelope collides with a legitimate plain-JSON 2-element array body, so the shape
+alone can't be trusted. Absence means an ordinary JSON body from a non-abide client
+(curl, an OpenAPI-generated SDK, a webhook) — parseArgs reads it with plain JSON.parse.
+*/
+export const REF_JSON_HEADER = 'abide-ref-json'

package/src/lib/shared/REF_JSON_TAGS.ts

@@ -0,0 +1,31 @@
+/*
+Value tags for the ref-json codec (encodeRefJson / decodeRefJson). The output is
+a `[rootValue, slots]` pair: `slots` holds only the hoisted CONTAINERS (objects,
+arrays, Maps, Sets) addressed by index; every other value is encoded INLINE at its
+position — a bare JSON primitive, or one of these tagged arrays. Primitives never
+get their own slot, so a primitive-heavy payload stays close to plain-JSON size and
+speed. A tag is always the first element of a JSON array at a value position; bare
+JSON values are literal primitives, and plain objects only ever appear AS slots
+(hoisted), so user data — even an object keyed `~r` or an array shaped like a tag —
+can't collide with these. Shared between encoder and decoder so the tokens can't drift.
+*/
+export const REF_JSON_TAGS = {
+    // ['~r', slotIndex] — reference to a hoisted container; breaks cycles, preserves shared identity.
+    REF: '~r',
+    // ['~a', ...values]
+    ARRAY: '~a',
+    // ['~m', [[keyValue, valValue], …]]
+    MAP: '~m',
+    // ['~s', [value, …]]
+    SET: '~s',
+    // ['~d', epochMs]
+    DATE: '~d',
+    // ['~x', source, flags]
+    REGEXP: '~x',
+    // ['~g', decimalString] — BigInt can't go through JSON natively.
+    BIGINT: '~g',
+    // ['~u'] — undefined (and functions/symbols, folded to it).
+    UNDEFINED: '~u',
+    // ['~n', token] — the numbers JSON flattens to null: 'NaN' | 'Infinity' | '-Infinity' | '-0'.
+    NUMBER: '~n',
+} as const

package/src/lib/shared/assertExhaustive.ts

@@ -0,0 +1,14 @@
+/*
+Exhaustiveness guard for a discriminated-union dispatch. When every variant is
+handled, the fall-through value narrows to `never`, so passing it here type-checks;
+adding a new variant without a branch makes this a COMPILE error AND, if it slips
+past types, throws at runtime naming the variant — converting a silent mis-dispatch
+(a new template-node kind routed to the wrong branch) into a loud failure. The
+enumeration's completeness becomes the type checker's job instead of inspection's.
+*/
+export function assertExhaustive(value: never, context = 'variant'): never {
+    const kind = (value as { kind?: unknown })?.kind
+    throw new Error(
+        `[abide] non-exhaustive ${context}${kind === undefined ? '' : `: ${String(kind)}`}`,
+    )
+}

package/src/lib/shared/buildRpcRequest.ts

@@ -1,5 +1,7 @@
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { encodeRefJson } from './encodeRefJson.ts'
 import { queryStringFromArgs } from './queryStringFromArgs.ts'
+import { REF_JSON_HEADER } from './REF_JSON_HEADER.ts'
 import type { HttpVerb } from './types/HttpVerb.ts'
 
 /*
@@ -49,11 +51,16 @@ export function buildRpcRequest({
             body: args,
         })
     }
+    /* ref-json (still valid JSON, so the content-type holds) so an arg graph with
+       cycles or shared back-references reaches the handler instead of throwing here.
+       The REF_JSON_HEADER flags the encoding so parseArgs decodes it with the same
+       codec; a non-abide client omits it and parseArgs reads plain JSON.parse. */
     requestHeaders.set('content-type', 'application/json')
+    requestHeaders.set(REF_JSON_HEADER, '1')
     return new Request(new URL(url, baseUrl).href, {
         method,
         headers: requestHeaders,
-        body: JSON.stringify(args),
+        body: encodeRefJson(args),
     })
 }