@abide/abide 0.39.0 → 0.40.0

package/AGENTS.md

@@ -142,7 +142,7 @@ Test suites compile `.abide` and rewrite verbs under `bun test` via `preload = [
 
 ### Reactive state — @documentation reactive-state
 
-- `abide/ui/scope` — `scope()`: the sole reactive surface. `.state(initial?, transform?)` (writable cell), `.computed(fn)` (read-only), `.linked(seed, transform?)` (local draft reseeded from upstream). Bare `state`/`computed`/`linked` are a compile error; a writable computed is expressed at the binding (`bind:value={{ get, set }}`). Also carries doc/persistence/undo/broadcast methods.
+- `abide/ui/scope` — `scope()`: the sole reactive surface. `.state(initial?, transform?)` (writable cell), `.computed(fn)` (read-only), `.linked(seed, transform?)` (local draft reseeded from upstream). Bare `state`/`computed`/`linked` are a compile error; a writable computed is expressed at the binding (`bind:value={{ get, set }}`). `.share(key, value)`/`.shared(key)` pass context down the tree (closest-ancestor lookup; the reactive doc itself doesn't inherit, so share a `cell` for reactive context). Also carries doc/persistence/undo/broadcast methods.
 
 ### Effect — @documentation effect
 
@@ -151,7 +151,7 @@ Test suites compile `.abide` and rewrite verbs under `bun test` via `preload = [
 ### Tail & navigate — @documentation tail · navigate
 
 - `abide/ui/tail` — `tail(subscribable)`: latest frame of a `Socket`/stream (reactive); window form `tail(s, { last })` → array; `tail.error`/`tail.status` probes.
-- `abide/ui/navigate` — `navigate(path, replace?)`: client navigation through the router.
+- `abide/ui/navigate` — `navigate(path, options?)`: client navigation through the router. `options` is `{ replace?, keepScroll? }` — `replace` swaps the current history entry, `keepScroll` preserves the live scroll offset across an in-page URL swap.
 
 ### Outbox — @documentation ui
 

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # abide
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.39.0",
+    "version": "0.40.0",
     "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/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),
     })
 }
 

package/src/lib/shared/decodeRefJson.ts

@@ -0,0 +1,110 @@
+/*
+Inverse of encodeRefJson — rebuild a value graph (cycles, shared references, and the
+JSON-hostile types) from a `[rootValue, slots]` ref-json string. Two passes are
+required: pass one allocates every hoisted container as an empty shell, pass two fills
+them. The shell must exist before its contents are filled so a back-reference to an
+ancestor resolves to the already-allocated object — which is what reconnects a cycle.
+Inline primitives need no shell; they decode directly where they sit.
+*/
+import { REF_JSON_TAGS } from './REF_JSON_TAGS'
+
+export function decodeRefJson(text: string): unknown {
+    const parsed = JSON.parse(text)
+    if (!Array.isArray(parsed) || parsed.length !== 2 || !Array.isArray(parsed[1])) {
+        // encodeRefJson always emits a `[rootValue, slots]` pair; anything else isn't our format.
+        throw new TypeError('decodeRefJson: not a ref-json payload')
+    }
+    const [rootValue, slots] = parsed as [unknown, unknown[]]
+    // Pass 1: an empty container shell per slot. Pass 2 fills them so a ref to an ancestor finds its shell.
+    const shells = slots.map(buildShell)
+    slots.forEach((slot, index) => {
+        fillShell(slot, shells[index], shells)
+    })
+    return resolveValue(rootValue, shells)
+}
+
+// Empty container matching a slot's kind. Every slot is a container (only containers are hoisted).
+function buildShell(slot: unknown): unknown {
+    if (Array.isArray(slot)) {
+        if (slot[0] === REF_JSON_TAGS.ARRAY) {
+            return []
+        }
+        if (slot[0] === REF_JSON_TAGS.MAP) {
+            return new Map()
+        }
+        if (slot[0] === REF_JSON_TAGS.SET) {
+            return new Set()
+        }
+    }
+    return {}
+}
+
+// Decode an inline value: bare primitive (itself), a leaf-special, or a reference to a built shell.
+function resolveValue(value: unknown, shells: unknown[]): unknown {
+    if (!Array.isArray(value)) {
+        return value
+    }
+    switch (value[0]) {
+        case REF_JSON_TAGS.REF:
+            return shells[value[1] as number]
+        case REF_JSON_TAGS.UNDEFINED:
+            return undefined
+        case REF_JSON_TAGS.DATE:
+            return new Date(value[1] as number)
+        case REF_JSON_TAGS.REGEXP:
+            return new RegExp(value[1] as string, value[2] as string)
+        case REF_JSON_TAGS.BIGINT:
+            return BigInt(value[1] as string)
+        case REF_JSON_TAGS.NUMBER:
+            return decodeNumberToken(value[1] as string)
+        default:
+            throw new TypeError(`decodeRefJson: unknown value tag ${String(value[0])}`)
+    }
+}
+
+// Fill a container shell from its slot, resolving each inline child.
+function fillShell(slot: unknown, shell: unknown, shells: unknown[]): void {
+    if (!Array.isArray(slot)) {
+        const target = shell as Record<string, unknown>
+        const record = slot as Record<string, unknown>
+        for (const key of Object.keys(record)) {
+            target[key] = resolveValue(record[key], shells)
+        }
+        return
+    }
+    if (slot[0] === REF_JSON_TAGS.ARRAY) {
+        const target = shell as unknown[]
+        // Loop (not push(...spread)) so a huge array can't blow the call-stack arg limit.
+        for (let index = 1; index < slot.length; index++) {
+            target.push(resolveValue(slot[index], shells))
+        }
+        return
+    }
+    if (slot[0] === REF_JSON_TAGS.MAP) {
+        const target = shell as Map<unknown, unknown>
+        for (const [key, val] of slot[1] as [unknown, unknown][]) {
+            target.set(resolveValue(key, shells), resolveValue(val, shells))
+        }
+        return
+    }
+    if (slot[0] === REF_JSON_TAGS.SET) {
+        const target = shell as Set<unknown>
+        for (const member of slot[1] as unknown[]) {
+            target.add(resolveValue(member, shells))
+        }
+    }
+}
+
+// Reverse of encodeRefJson's numberToken.
+function decodeNumberToken(token: string): number {
+    if (token === 'NaN') {
+        return Number.NaN
+    }
+    if (token === 'Infinity') {
+        return Number.POSITIVE_INFINITY
+    }
+    if (token === '-Infinity') {
+        return Number.NEGATIVE_INFINITY
+    }
+    return -0
+}

package/src/lib/shared/encodeRefJson.ts

@@ -0,0 +1,106 @@
+/*
+Serialise an arbitrary value graph to a JSON string that survives cycles and shared
+references — the gap JSON.stringify can't cross. Only mutable CONTAINERS (objects,
+arrays, Maps, Sets) are hoisted into a flat `slots` array and referenced by index, so
+a cycle becomes a back-reference instead of infinite recursion, and two paths to the
+same container decode back to the same object. Primitives are encoded INLINE at their
+position (not hoisted), so a primitive-heavy payload stays near plain-JSON size and
+speed. Beyond plain objects/arrays it round-trips the types JSON drops or coerces:
+undefined, bigint, NaN, ±Infinity, -0, Date, RegExp, Map and Set. Functions and
+symbols can't be serialised and encode as undefined, matching JSON.stringify. Output
+shape is `[rootValue, slots]`. Decode with decodeRefJson. Not streaming — the whole
+graph is walked up front.
+*/
+import { REF_JSON_TAGS } from './REF_JSON_TAGS'
+
+export function encodeRefJson(value: unknown): string {
+    // Hoisted containers only; slots[i] is addressed by ['~r', i]. Primitives stay inline.
+    const slots: unknown[] = []
+    // Container identity → slot index: a revisited container emits a back-reference instead of recursing.
+    const ids = new Map<object, number>()
+
+    // Hoist a container to a slot (once) and return its index. Reserve the index BEFORE encoding
+    // children so a cyclic child resolves back to this slot.
+    function intern(container: object): number {
+        const seen = ids.get(container)
+        if (seen !== undefined) {
+            return seen
+        }
+        const index = slots.length
+        slots.push(0)
+        ids.set(container, index)
+        slots[index] = encodeContainer(container)
+        return index
+    }
+
+    // Inline encoding of a value at its position: bare primitive, leaf-special tag, or a container reference.
+    function encodeValue(input: unknown): unknown {
+        if (input === null) {
+            return null
+        }
+        const type = typeof input
+        if (type === 'string' || type === 'boolean') {
+            return input
+        }
+        if (type === 'number') {
+            const numeric = input as number
+            // -0, NaN, ±Infinity can't round-trip as bare JSON; tag them.
+            if (!Number.isFinite(numeric) || Object.is(numeric, -0)) {
+                return [REF_JSON_TAGS.NUMBER, numberToken(numeric)]
+            }
+            return numeric
+        }
+        if (type === 'bigint') {
+            return [REF_JSON_TAGS.BIGINT, (input as bigint).toString()]
+        }
+        // undefined | function | symbol — not representable; fold to undefined as JSON drops them.
+        if (type !== 'object') {
+            return [REF_JSON_TAGS.UNDEFINED]
+        }
+        if (input instanceof Date) {
+            return [REF_JSON_TAGS.DATE, input.getTime()]
+        }
+        if (input instanceof RegExp) {
+            return [REF_JSON_TAGS.REGEXP, input.source, input.flags]
+        }
+        // Mutable container: hoist for identity and reference it — primitives above never reach here.
+        return [REF_JSON_TAGS.REF, intern(input as object)]
+    }
+
+    // A hoisted container's slot: a tagged array (or plain object) whose nested values are encoded inline.
+    function encodeContainer(container: object): unknown {
+        if (Array.isArray(container)) {
+            return [REF_JSON_TAGS.ARRAY, ...container.map(encodeValue)]
+        }
+        if (container instanceof Map) {
+            return [
+                REF_JSON_TAGS.MAP,
+                Array.from(container, ([key, val]) => [encodeValue(key), encodeValue(val)]),
+            ]
+        }
+        if (container instanceof Set) {
+            return [REF_JSON_TAGS.SET, Array.from(container, encodeValue)]
+        }
+        const record = container as Record<string, unknown>
+        // Own enumerable keys, built in one loop — ~2× cheaper than Object.fromEntries(keys.map(...))
+        // (no intermediate pairs array / closures) on this per-object always-hot path.
+        const encoded: Record<string, unknown> = {}
+        for (const key of Object.keys(record)) {
+            encoded[key] = encodeValue(record[key])
+        }
+        return encoded
+    }
+
+    return JSON.stringify([encodeValue(value), slots])
+}
+
+// Stable token for the numbers JSON can't carry.
+function numberToken(value: number): string {
+    if (Object.is(value, -0)) {
+        return '-0'
+    }
+    if (Number.isNaN(value)) {
+        return 'NaN'
+    }
+    return value > 0 ? 'Infinity' : '-Infinity'
+}

package/src/lib/test/createTestSocketChannel.ts

@@ -3,6 +3,8 @@ import type { SocketClientFrame } from '../server/sockets/types/SocketClientFram
 import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
 import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
 import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
+import { decodeRefJson } from '../shared/decodeRefJson.ts'
+import { encodeRefJson } from '../shared/encodeRefJson.ts'
 
 /*
 Test-side substitute for the browser socketChannel: one ws to the booted
@@ -37,7 +39,8 @@ export function createTestSocketChannel(wsUrl: string): {
     }
 
     function send(frame: SocketClientFrame): void {
-        const message = JSON.stringify(frame)
+        // ref-json, matching the browser channel + the server's dispatcher/publish codec.
+        const message = encodeRefJson(frame)
         if (ws.readyState === WebSocket.OPEN) {
             ws.send(message)
             return
@@ -53,7 +56,8 @@ export function createTestSocketChannel(wsUrl: string): {
     ws.addEventListener('message', (event) => {
         let frame: SocketServerFrame
         try {
-            frame = JSON.parse(event.data as string) as SocketServerFrame
+            // The server sends ref-json frames (createSocketDispatcher/defineSocket); decode to match.
+            frame = decodeRefJson(event.data as string) as SocketServerFrame
         } catch {
             return
         }

package/src/lib/ui/compile/compileShadow.ts

@@ -381,19 +381,26 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                narrowing — emitting it inside the `if` block (as a plain child) instead
                gave it the positive narrowing, so a literal-union compare read as a
                "no overlap" and a typeof-narrowed branch saw the wrong member. */
-            const elseChild = node.children.find(
-                (child): child is Extract<TemplateNode, { kind: 'case' }> =>
-                    child.kind === 'case' && child.match === undefined,
+            const branches = node.children.filter(
+                (child): child is Extract<TemplateNode, { kind: 'case' }> => child.kind === 'case',
             )
-            const thenChildren = node.children.filter((child) => child !== elseChild)
+            const thenChildren = node.children.filter((child) => child.kind !== 'case')
             builder.raw('if ')
             builder.expr(node.condition, node.loc)
             builder.raw(' {\n')
             emitNodes(thenChildren, builder)
             builder.raw('}')
-            if (elseChild !== undefined) {
-                builder.raw(' else {\n')
-                emitNodes(elseChild.children, builder)
+            /* `elseif` → a real `else if` so its body inherits the prior conditions' negative
+               narrowing plus its own positive; `else` → the trailing block. */
+            for (const branch of branches) {
+                if (branch.condition !== undefined) {
+                    builder.raw(' else if ')
+                    builder.expr(branch.condition, branch.loc)
+                    builder.raw(' {\n')
+                } else {
+                    builder.raw(' else {\n')
+                }
+                emitNodes(branch.children, builder)
                 builder.raw('}')
             }
             builder.raw('\n')