@abide/abide 0.34.1 → 0.34.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # abide
 
+## 0.34.2
+
+### Patch Changes
+
+- [`91b03c5`](https://github.com/briancray/abide/commit/91b03c540e7139205f1518a6e2429411df43b859) - enforce the msg frame against the shared wire type ([`77fedf1`](https://github.com/briancray/abide/commit/77fedf17787b8bd8fbcdc56c722016ec4e905836))
+
+- [`91b03c5`](https://github.com/briancray/abide/commit/91b03c540e7139205f1518a6e2429411df43b859) - extract the shared sub registry + frame routing ([`b81dcce`](https://github.com/briancray/abide/commit/b81dcceb63ccd92dd04f9108173510e8c132a02c))
+
+- [`91b03c5`](https://github.com/briancray/abide/commit/91b03c540e7139205f1518a6e2429411df43b859) - classify response body kind once for live and warm decode ([`bd4fb4c`](https://github.com/briancray/abide/commit/bd4fb4cec2813f3d58ee6b277d2428ba75e521ae))
+
+- [`c1242f3`](https://github.com/briancray/abide/commit/c1242f3bd4343c760362950d7953a172b2d112f5) - fix(cache): honor the streaming guard in the SSR cache-snapshot round-trip. The snapshot path's content-type classifiers were hand-mirrored against `decodeResponse` but omitted its `isStreamingResponse` refusal, so a `cache()`d GET to a streaming endpoint (SSE / NDJSON / JSONL) would (a) hang SSR — `snapshotEntryFromCache` called `response.text()` on a never-ending body — and (b) break isomorphism — `warmValueFromSnapshot` warm-decoded the body to a value while a live read throws the "use tail()/stream()" error. The server now skips streaming responses (shared `isStreamingResponse`) and the warm decoder defers them to the async path, keeping it a strict subset of `decodeResponse`.
+
+- [`f710ba8`](https://github.com/briancray/abide/commit/f710ba8a6266f67c7ff03d9117e1484a7c63f59a) - fix(ui): single shared `skeletonContext` pass drives `<!--a-->` anchor placement for both back-ends, so the SSR string and client build can't disagree about skeleton markers. Previously the server tracked skeleton position as mutable traversal state reset at each fresh-context boundary; a forgotten reset (component slot content, snippet bodies) leaked an anchor the client never emitted, desyncing hydration. Boundaries are now enumerated once, declaratively. Adds a generative, reference-checked congruence harness (`uiRenderCongruenceFuzz`) that combinatorially nests every fresh-context boundary inside skeletonable parents and checks marker congruence + content against a by-construction reference + a hydration round-trip — catching this whole drift class without hand-enumerating shapes.
+
 ## 0.34.1
 
 ### Patch Changes

package/package.json

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

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

@@ -1,4 +1,5 @@
 import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
+import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
 import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
 import type { CacheStore } from '../../shared/types/CacheStore.ts'
@@ -38,6 +39,14 @@ export async function snapshotEntryFromCache(
     if (store.entries.get(entry.key) !== entry) {
         return undefined
     }
+    /* A streaming body (SSE / JSONL / NDJSON) can't ship: `response.text()` below would
+       hang buffering a never-ending stream, and `decodeResponse` refuses it on the client
+       anyway — so a snapshot value would diverge from a live read. Skip it (the same guard
+       `decodeResponse` applies), letting the client live-fetch and get the proper streaming
+       error. */
+    if (isStreamingResponse(response)) {
+        return undefined
+    }
     const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
     if (!isTextual(contentType)) {
         return undefined

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

@@ -6,6 +6,7 @@ import { getActiveServer } from '../runtime/getActiveServer.ts'
 import { registerSocket } from './registerSocket.ts'
 import type { Socket } from './types/Socket.ts'
 import type { SocketOptions } from './types/SocketOptions.ts'
+import type { SocketServerFrame } from './types/SocketServerFrame.ts'
 
 /*
 Server-side construction of a Socket. The bundler rewrites every
@@ -118,7 +119,11 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
         }
         const server = cachedServer
         if (server) {
-            server.publish(topic, JSON.stringify({ type: 'msg', socket: name, message: validated }))
+            /* Typed against the shared wire contract so a `SocketServerFrame` change can't
+               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))
         }
     }
 

package/src/lib/shared/cacheEntryFromSnapshot.ts

@@ -1,3 +1,4 @@
+import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 import type { CacheSnapshotEntry } from './types/CacheSnapshotEntry.ts'
@@ -31,30 +32,31 @@ export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
 
 /*
 Synchronously decodes a snapshot body so the warm entry reads without a
-microtask hop on first render. Mirrors decodeResponse for the textual cases the
-snapshot ships; non-2xx and 204 yield no warm value and fall back to the async
-path, which throws HttpError / returns undefined exactly as a live call would.
-Binary/xml bodies also skip the warm path and decode asynchronously.
+microtask hop on first render. A strict subset of `decodeResponse`: it warms
+only the `json`/`text` kinds (the same `contentBodyKind` the live read switches
+on, so the two cannot disagree about a body), returning a value identical to
+what awaiting the Response would yield. Every other kind — non-2xx, 204,
+streaming, binary — yields no warm value and defers to the async path, which
+throws HttpError / returns the streaming error / blobs exactly as a live call
+would.
 */
 function warmValueFromSnapshot(status: number, headers: Headers, body: string): unknown {
     if (status === 204 || status < 200 || status >= 300) {
         return undefined
     }
-    const contentType = contentTypeOf(headers)
-    if (contentType.includes('json')) {
-        /*
-        `.includes('json')` also matches streaming/non-JSON types like
-        application/x-ndjson; fall back to the async path (return undefined)
-        rather than throwing a SyntaxError synchronously during hydration.
-        */
+    const kind = contentBodyKind(contentTypeOf(headers))
+    if (kind === 'json') {
+        /* The body may still be malformed JSON; fall back to the async path rather than
+           throwing a SyntaxError synchronously during hydration. */
         try {
             return JSON.parse(body)
         } catch {
             return undefined
         }
     }
-    if (contentType.startsWith('text/')) {
+    if (kind === 'text') {
         return body
     }
+    /* streaming and binary defer to the async path (the live decode throws / blobs). */
     return undefined
 }

package/src/lib/shared/contentBodyKind.ts

@@ -0,0 +1,27 @@
+import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
+
+/*
+The single classification of a Content-Type into the body kind that decides how
+its bytes become a value. One ordering, read by every decoder, so the live read
+(`decodeResponse`) and the synchronous warm read (`warmValueFromSnapshot`) cannot
+classify the same body differently — the divergence that shipped a warm value a
+live read rejected (the streaming-guard-in-one-but-not-the-other bug).
+
+`streaming` is tested FIRST and the order is load-bearing: `application/jsonl`
+and `application/x-ndjson` both contain `json`, so a json-first scan would
+mis-bucket a stream as parseable JSON.
+*/
+export type ContentBodyKind = 'streaming' | 'json' | 'text' | 'binary'
+
+export function contentBodyKind(contentType: string): ContentBodyKind {
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        return 'streaming'
+    }
+    if (contentType.includes('json')) {
+        return 'json'
+    }
+    if (contentType.startsWith('text/')) {
+        return 'text'
+    }
+    return 'binary'
+}

package/src/lib/shared/createSocketSubRegistry.ts

@@ -0,0 +1,112 @@
+import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
+import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
+import type { SocketChannel } from './types/SocketChannel.ts'
+import type { SocketSubCallbacks } from './types/SocketSubCallbacks.ts'
+
+/*
+The multiplex bookkeeping every SocketChannel shares: the local subscription
+registry plus the inbound `SocketServerFrame` routing. A channel supplies only
+its transport (`send`, and when to call `drainSubs` on a drop); everything that
+encodes the wire contract — how a `msg` fans out to a socket's subs, how
+`replay`/`end`/`err` address one sub — lives here once, so the browser multiplex
+and the test harness cannot drift on the protocol (ADR-0005).
+
+`send` carries an outbound client frame however the channel can (the browser
+queues until open and reconnects; the test harness queues until open). Routing
+and the registry never touch the transport, so they stay identical across both.
+*/
+export function createSocketSubRegistry(send: (frame: SocketClientFrame) => void): {
+    channel: SocketChannel
+    routeFrame: (frame: SocketServerFrame) => void
+    drainSubs: () => SocketSubCallbacks[]
+} {
+    const subs = new Map<string, { socket: string; callbacks: SocketSubCallbacks }>()
+    /* Reverse index for `msg` fan-out: one server publish addresses a socket, not a sub. */
+    const subsBySocket = new Map<string, Set<string>>()
+
+    function dropSub(id: string): void {
+        const entry = subs.get(id)
+        if (!entry) {
+            return
+        }
+        subs.delete(id)
+        const set = subsBySocket.get(entry.socket)
+        if (set) {
+            set.delete(id)
+            if (set.size === 0) {
+                subsBySocket.delete(entry.socket)
+            }
+        }
+    }
+
+    /*
+    Routes one inbound frame to its sub(s):
+      `msg`    → every local sub of that socket (addressed by socket name)
+      `replay` → the one sub that requested the seed (its batched tail)
+      `end`/`err` → the one sub, dropped first so its iterator can't take another frame
+    A frame for an unknown sub/socket is ignored — a sub torn down between request
+    and delivery.
+    */
+    function routeFrame(frame: SocketServerFrame): void {
+        if (frame.type === 'msg') {
+            const targets = subsBySocket.get(frame.socket)
+            if (!targets) {
+                return
+            }
+            for (const subId of targets) {
+                subs.get(subId)?.callbacks.onMessage(frame.message)
+            }
+            return
+        }
+        if (frame.type === 'replay') {
+            subs.get(frame.sub)?.callbacks.onReplay(frame.messages)
+            return
+        }
+        const sub = subs.get(frame.sub)
+        if (!sub) {
+            return
+        }
+        dropSub(frame.sub)
+        if (frame.type === 'end') {
+            sub.callbacks.onEnd()
+        } else {
+            sub.callbacks.onError(frame.message)
+        }
+    }
+
+    /* Tear down every sub on a transport drop and hand the caller their callbacks.
+       Clears the registry BEFORE the caller runs `onDisconnect`, so a consumer that
+       re-subscribes in reaction (in a later microtask) registers onto fresh state. */
+    function drainSubs(): SocketSubCallbacks[] {
+        const active = [...subs.values()].map((entry) => entry.callbacks)
+        subs.clear()
+        subsBySocket.clear()
+        return active
+    }
+
+    const channel: SocketChannel = {
+        subscribe(id, socket, replay, callbacks) {
+            subs.set(id, { socket, callbacks })
+            /* Not getOrInsertComputed: browser-side code, and Safari/Chrome only shipped it within the last browser cycle (26.2 / 145). */
+            let set = subsBySocket.get(socket)
+            if (!set) {
+                set = new Set()
+                subsBySocket.set(socket, set)
+            }
+            set.add(id)
+            send({ type: 'sub', sub: id, socket, replay })
+        },
+        unsubscribe(id) {
+            if (!subs.has(id)) {
+                return
+            }
+            dropSub(id)
+            send({ type: 'unsub', sub: id })
+        },
+        publish(socket, message) {
+            send({ type: 'pub', socket, message })
+        },
+    }
+
+    return { channel, routeFrame, drainSubs }
+}

package/src/lib/shared/decodeResponse.ts

@@ -1,6 +1,6 @@
+import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
 import { HttpError } from './HttpError.ts'
-import { isStreamingResponse } from './isStreamingResponse.ts'
 
 /*
 Decodes a Response into the natural body value based on Content-Type:
@@ -33,15 +33,16 @@ export async function decodeResponse(response: Response): Promise<unknown> {
         return undefined
     }
     const contentType = contentTypeOf(response.headers)
-    if (isStreamingResponse(response)) {
+    const kind = contentBodyKind(contentType)
+    if (kind === 'streaming') {
         throw new Error(
             `[abide] response at ${response.url} is a stream (${contentType}) — use tail(fn.stream(args)) for a reactive view, or fn.stream(args) for per-call iteration, instead of awaiting the bare call or cache()`,
         )
     }
-    if (contentType.includes('json')) {
+    if (kind === 'json') {
         return response.json()
     }
-    if (contentType.startsWith('text/')) {
+    if (kind === 'text') {
         return response.text()
     }
     return response.blob()

package/src/lib/shared/isStreamingResponse.ts

@@ -1,12 +1,12 @@
+import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
-import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
 
 /*
 Whether a Response carries a streaming body (SSE / JSONL / NDJSON) by its
-Content-Type, so callers drain it frame-by-frame instead of buffering.
-Shared by the CLI print path and the MCP tool dispatcher.
+Content-Type, so callers drain it frame-by-frame instead of buffering. The
+streaming bucket of the shared `contentBodyKind` classification. Shared by the
+CLI print path and the MCP tool dispatcher.
 */
 export function isStreamingResponse(response: Response): boolean {
-    const contentType = contentTypeOf(response.headers)
-    return STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))
+    return contentBodyKind(contentTypeOf(response.headers)) === 'streaming'
 }

package/src/lib/test/createTestSocketChannel.ts

@@ -2,8 +2,7 @@ import type { Socket } from '../server/sockets/types/Socket.ts'
 import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
 import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
 import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
-import type { SocketChannel } from '../shared/types/SocketChannel.ts'
-import type { SocketSubCallbacks } from '../shared/types/SocketSubCallbacks.ts'
+import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
 
 /*
 Test-side substitute for the browser socketChannel: one ws to the booted
@@ -23,8 +22,6 @@ export function createTestSocketChannel(wsUrl: string): {
     /* `using channel = createTestSocketChannel(url)` — disposal closes the ws. */
     [Symbol.dispose]: () => void
 } {
-    const subs = new Map<string, { socket: string; callbacks: SocketSubCallbacks }>()
-    const subsBySocket = new Map<string, Set<string>>()
     let pendingSends: string[] = []
 
     const ws = new WebSocket(wsUrl)
@@ -48,20 +45,9 @@ export function createTestSocketChannel(wsUrl: string): {
         pendingSends.push(message)
     }
 
-    function dropSub(id: string): void {
-        const entry = subs.get(id)
-        if (!entry) {
-            return
-        }
-        subs.delete(id)
-        const set = subsBySocket.get(entry.socket)
-        if (set) {
-            set.delete(id)
-            if (set.size === 0) {
-                subsBySocket.delete(entry.socket)
-            }
-        }
-    }
+    /* Same sub registry + frame routing the browser channel uses; this harness owns
+       only the bare ws (no reconnect — a test drives the lifecycle through close()). */
+    const registry = createSocketSubRegistry(send)
 
     ws.addEventListener('open', flushPending)
     ws.addEventListener('message', (event) => {
@@ -71,70 +57,23 @@ export function createTestSocketChannel(wsUrl: string): {
         } catch {
             return
         }
-        if (frame.type === 'msg') {
-            const targets = subsBySocket.get(frame.socket)
-            if (!targets) {
-                return
-            }
-            for (const subId of targets) {
-                subs.get(subId)?.callbacks.onMessage(frame.message)
-            }
-            return
-        }
-        if (frame.type === 'replay') {
-            subs.get(frame.sub)?.callbacks.onReplay(frame.messages)
-            return
-        }
-        const sub = subs.get(frame.sub)
-        if (!sub) {
-            return
-        }
-        dropSub(frame.sub)
-        if (frame.type === 'end') {
-            sub.callbacks.onEnd()
-        } else {
-            sub.callbacks.onError(frame.message)
-        }
+        registry.routeFrame(frame)
     })
     /* A drop after subs are live is unexpected; surface it so iterators unblock
        instead of awaiting a frame that never comes. Idempotent — the first of
-       error/close clears subs, the second finds none. error covers a failed
+       error/close drains the subs, the second finds none. error covers a failed
        handshake (no open, no clean close) that close alone would miss. */
     function disconnectAll(): void {
-        const active = [...subs.values()]
-        subs.clear()
-        subsBySocket.clear()
-        for (const sub of active) {
-            sub.callbacks.onDisconnect()
+        for (const callbacks of registry.drainSubs()) {
+            callbacks.onDisconnect()
         }
     }
     ws.addEventListener('close', disconnectAll)
     ws.addEventListener('error', disconnectAll)
 
-    const channel: SocketChannel = {
-        subscribe(id, socket, replay, callbacks) {
-            subs.set(id, { socket, callbacks })
-            let set = subsBySocket.get(socket)
-            if (!set) {
-                set = new Set()
-                subsBySocket.set(socket, set)
-            }
-            set.add(id)
-            send({ type: 'sub', sub: id, socket, replay })
-        },
-        unsubscribe(id) {
-            if (!subs.has(id)) {
-                return
-            }
-            dropSub(id)
-            send({ type: 'unsub', sub: id })
-        },
-        publish: (socket, message) => send({ type: 'pub', socket, message }),
-    }
-
     /* Same Socket<T> builder the browser proxy uses, over this test channel. */
     function socket<T>(name: string): Socket<T> {
-        return buildSocketOverChannel<T>(name, () => channel)
+        return buildSocketOverChannel<T>(name, () => registry.channel)
     }
 
     const close = () => ws.close()

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

@@ -2,10 +2,9 @@ import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
 import { componentWrapperTag } from './componentWrapperTag.ts'
 import { groupBindParts } from './groupBindParts.ts'
 import { isControlFlow } from './isControlFlow.ts'
-import { isTextLeaf } from './isTextLeaf.ts'
 import { lowerContext } from './lowerContext.ts'
 import { scopeAttr } from './scopeAttr.ts'
-import { skeletonable } from './skeletonable.ts'
+import { skeletonContext } from './skeletonContext.ts'
 import { staticAttr } from './staticAttr.ts'
 import { staticTextPart } from './staticTextPart.ts'
 import { stripEffects } from './stripEffects.ts'
@@ -65,41 +64,33 @@ export function generateSSR(
         return children.map((child) => generate(child, target)).join('')
     }
 
+    /* Per-node skeleton position, computed once. Both back-ends read this single source of
+       truth so their `<!--a-->` anchor placement cannot drift — the fresh-context boundaries
+       (control-flow branches, component/slot/snippet content) are enumerated there, not
+       re-tracked here as mutable state that a forgotten reset could leak past. */
+    const { inSkeleton, markText } = skeletonContext(nodes)
+
     /* A control-flow branch's content, generated exactly like a normal child list so
        a branch holds ANY content (components, text, nested blocks). `generate` emits
        nested `<script>`s in document order; `withNestedScripts` puts their bindings in
        scope — matching the client build, so hydration stays aligned. The caller wraps
        it in the `[ … ]` range markers the runtime tracks (unconditionally per block,
-       so an empty/false branch still emits the boundary the client claims). */
+       so an empty/false branch still emits the boundary the client claims). The branch's
+       fresh build context is already recorded by `skeletonContext`, so its children read
+       their own (reset) position — no flag juggling here. */
     function branchContent(children: TemplateNode[], target: string): string {
-        /* A control-flow branch is a fresh build context — the block runtime mounts it, not
-           the parent skeleton — so reset the skeleton/anchor tracking; the branch's own
-           skeletonable elements re-enter it. */
-        const previousSkeleton = inSkeleton
-        const previousMark = markText
-        inSkeleton = false
-        markText = false
-        const out = withNestedScripts(children, () => generateInto(children, target))
-        inSkeleton = previousSkeleton
-        markText = previousMark
-        return out
+        return withNestedScripts(children, () => generateInto(children, target))
     }
     const openRange = (target: string): string => push(target, RANGE_OPEN)
     const closeRange = (target: string): string => push(target, RANGE_CLOSE)
 
-    /* True inside a skeletonable subtree; `markText` true when, additionally, the current
-       element is NOT a text-leaf — so its reactive text is interleaved and the client uses
-       an `<!--a-->` anchor. The marker is kept both sides (like control-flow ranges), so
-       SSR markup stays identical to the client DOM. */
-    let inSkeleton = false
-    let markText = false
-
     /* In a skeleton, a control-flow block or slot is positioned by an `<!--a-->` anchor
        (cloned into the located parent), so it can sit anywhere among static siblings.
        Emitted both sides in document order — the client's anchor scan lines up with it.
        Outside a skeleton (top-level / inside a branch) blocks mount on the host directly,
        so no anchor. */
-    const anchorMark = (target: string): string => (inSkeleton ? push(target, '<!--a-->') : '')
+    const anchorMark = (node: TemplateNode, target: string): string =>
+        inSkeleton.get(node) ? push(target, '<!--a-->') : ''
 
     function generate(node: TemplateNode, target: string): string {
         /* A control-flow block is positioned by an `<!--a-->` anchor when in a skeleton
@@ -107,7 +98,7 @@ export function generateSSR(
            mirroring the client's single `skeletonMarkup` control-flow branch — rather than
            prefixing each block kind's own `anchorMark` call (six sites that had to stay in
            lock-step). `anchorMark` no-ops outside a skeleton, so non-block nodes ignore it. */
-        const anchor = isControlFlow(node) ? anchorMark(target) : ''
+        const anchor = isControlFlow(node) ? anchorMark(node, target) : ''
         if (node.kind === 'text') {
             return node.parts
                 .map((part) => {
@@ -116,7 +107,7 @@ export function generateSSR(
                         return markup === '' ? '' : push(target, markup)
                     }
                     const value = `$text(${lowerExpression(part.code)})`
-                    return markText
+                    return markText.get(node)
                         ? `${target}.push('<!--a-->' + ${value});\n`
                         : `${target}.push(${value});\n`
                 })
@@ -197,6 +188,11 @@ export function generateSSR(
             const parts = node.props.map(
                 (prop) => `${JSON.stringify(prop.name)}: () => (${lowerExpression(prop.code)})`,
             )
+            /* Slot content is a fresh build context — the child's `<slot>` mounts it via
+               `mountSlot`, not the parent skeleton clone, and the client builds it through
+               `componentParts`/`generateChildren` (never the skeleton path). `skeletonContext`
+               records it reset, so its children emit no enclosing-skeleton anchors the client
+               slot builder would lack. */
             const slotCode = generateInto(node.children, '$slot')
             if (slotCode.trim() !== '') {
                 parts.push(
@@ -256,21 +252,11 @@ export function generateSSR(
         }
         code += push(target, '>')
         if (!VOID_TAGS.has(node.tag)) {
-            /* Track skeleton context: reactive text gets an `<!--a-->` anchor only when
-               interleaved (this element has non-text children) inside a skeletonable
-               subtree — matching the client's anchor vs marker-free text-leaf choice. */
-            const entering = !inSkeleton && skeletonable(node)
-            if (entering) {
-                inSkeleton = true
-            }
-            const previousMark = markText
-            markText = inSkeleton && !isTextLeaf(node)
-            /* A `<script>` child scopes its bindings to this element's subtree. */
+            /* Each child's skeleton position (whether its reactive text interleaves into an
+               anchor, whether a nested block anchors) is already recorded by `skeletonContext`
+               — read per node, not tracked here. A `<script>` child scopes its bindings to
+               this element's subtree. */
             code += withNestedScripts(node.children, () => generateInto(node.children, target))
-            markText = previousMark
-            if (entering) {
-                inSkeleton = false
-            }
             code += push(target, `</${node.tag}>`)
         }
         return code
@@ -281,19 +267,14 @@ export function generateSSR(
        by an `<!--a-->` anchor and its content bounded by a `[ … ]` range (matching the
        client's `mountSlot`), so it can sit among static siblings. The fallback is a fresh,
        non-skeleton build context — the client builds it via `mountSlot`/`fillBefore`, not the
-       skeleton clone — so its reactive text takes no anchor (reset like `branchContent`). */
+       skeleton clone — so its reactive text takes no anchor (`skeletonContext` records the
+       fallback children reset). */
     function generateSlot(
         node: Extract<TemplateNode, { kind: 'element' }>,
         target: string,
     ): string {
-        const wrap = inSkeleton
-        const previousSkeleton = inSkeleton
-        const previousMark = markText
-        inSkeleton = false
-        markText = false
+        const wrap = inSkeleton.get(node)
         const fallback = generateInto(node.children, target)
-        inSkeleton = previousSkeleton
-        markText = previousMark
         const body =
             fallback.trim() === ''
                 ? `if ($props && $props.$children) { ${target}.push($props.$children()); }\n`
@@ -301,7 +282,7 @@ export function generateSSR(
         if (!wrap) {
             return body
         }
-        return `${anchorMark(target)}${openRange(target)}${body}${closeRange(target)}`
+        return `${anchorMark(node, target)}${openRange(target)}${body}${closeRange(target)}`
     }
 
     /* Boundary markers + a `$awaits` registration carrying the promise and

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

@@ -0,0 +1,83 @@
+import { isControlFlow } from './isControlFlow.ts'
+import { isTextLeaf } from './isTextLeaf.ts'
+import { skeletonable } from './skeletonable.ts'
+import type { SkeletonContext } from './types/SkeletonContext.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/*
+The single source of truth for where skeleton markers go. One top-down walk records,
+per node, whether it sits inside a parser-backed skeleton clone (`inSkeleton`) and
+whether its reactive text is interleaved (`markText`) — the two facts that decide
+`<!--a-->` anchor placement. Both back-ends read this instead of re-deriving the
+position (the client structurally, the server as mutable traversal state), which is
+what let them drift: a fresh-context boundary the server forgot to reset leaked an
+anchor the client never emitted, desyncing hydration.
+
+A fresh-context boundary resets to NOT-in-skeleton, because the content there is
+built by its own runtime (a control-flow block's branch, a component's slot content,
+a `<slot>`'s fallback, a snippet's body) — never cloned by the enclosing skeleton —
+so an enclosing skeletonable subtree must not stamp markers onto it. Enumerating
+every such boundary HERE, once, makes "forgetting to reset one" impossible.
+*/
+export function skeletonContext(nodes: TemplateNode[]): SkeletonContext {
+    const inSkeleton = new WeakMap<TemplateNode, boolean>()
+    const markText = new WeakMap<TemplateNode, boolean>()
+
+    /* Walk `node` carrying the context that applies AT it; recurse into children with the
+       context that applies to THEM. */
+    function visit(node: TemplateNode, nodeInSkeleton: boolean, nodeMarkText: boolean): void {
+        inSkeleton.set(node, nodeInSkeleton)
+        markText.set(node, nodeMarkText)
+
+        /* Control-flow branches, component slot content, and snippet bodies are fresh build
+           contexts — their children re-enter the skeleton only via their own skeletonable
+           elements, so reset both flags. (A standalone branch/case is reached as a child of
+           its control-flow node and likewise resets.) */
+        if (isControlFlow(node) || node.kind === 'component' || node.kind === 'snippet') {
+            for (const child of childrenOf(node)) {
+                visit(child, false, false)
+            }
+            return
+        }
+        /* A `branch`/`case` is a transparent grouping inside its control-flow block (its
+           children are generated directly, the wrapper never emits markup) — pass the
+           already-reset context through so a skeletonable element inside it re-enters. */
+        if (node.kind === 'branch' || node.kind === 'case') {
+            for (const child of node.children) {
+                visit(child, nodeInSkeleton, nodeMarkText)
+            }
+            return
+        }
+        if (node.kind !== 'element') {
+            return // text / script / style carry no skeleton children
+        }
+        if (node.tag === 'slot') {
+            /* The slot's own children are its fallback — a fresh context built by `mountSlot`,
+               not the enclosing clone. */
+            for (const child of node.children) {
+                visit(child, false, false)
+            }
+            return
+        }
+        /* A skeletonable element not already in a skeleton opens one; its descendants are in
+           skeleton. Reactive text interleaves (takes an anchor) unless this element is a
+           text-leaf (only text/style children), which binds its text marker-free. */
+        const childInSkeleton = nodeInSkeleton || skeletonable(node)
+        const childMarkText = childInSkeleton && !isTextLeaf(node)
+        for (const child of node.children) {
+            visit(child, childInSkeleton, childMarkText)
+        }
+    }
+
+    for (const node of nodes) {
+        visit(node, false, false)
+    }
+    return { inSkeleton, markText }
+}
+
+/* The child list of any node that has one (control-flow, component, snippet, element);
+   `[]` for the leaf kinds (text/script/style). `isControlFlow` is not a type guard, so the
+   `in` check is what narrows the union for the fresh-context branch. */
+function childrenOf(node: TemplateNode): TemplateNode[] {
+    return 'children' in node ? node.children : []
+}

package/src/lib/ui/compile/types/SkeletonContext.ts

@@ -0,0 +1,15 @@
+import type { TemplateNode } from './TemplateNode.ts'
+
+/*
+The per-node skeleton position both back-ends consult so their marker placement
+cannot drift. `inSkeleton` is true when a node sits inside a parser-backed skeleton
+clone (so control-flow blocks and `<slot>`s take an `<!--a-->` anchor at their
+position); `markText` is true when, additionally, the node's reactive text is
+interleaved with element siblings (so it takes an `<!--a-->` anchor rather than
+binding marker-free on a text-leaf element). Keyed by node identity — both maps are
+filled by one shared `skeletonContext` pass over the parsed tree.
+*/
+export type SkeletonContext = {
+    inSkeleton: WeakMap<TemplateNode, boolean>
+    markText: WeakMap<TemplateNode, boolean>
+}

package/src/lib/ui/socketChannel.ts

@@ -1,24 +1,17 @@
 import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
 import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
+import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
 import type { SocketChannel } from '../shared/types/SocketChannel.ts'
-import type { SocketSubCallbacks } from '../shared/types/SocketSubCallbacks.ts'
 import { withBase } from '../shared/withBase.ts'
 
 let singleton: SocketChannel | undefined
 
 /*
-Lazily opens the single multiplexed ws used by every socket proxy on
-the page. Routes inbound frames:
-  `msg`    → all local subs of that socket
-  `replay` → the matching sub (its batched seed)
-  `end`    → the matching sub
-  `err`    → the matching sub
-
-`msg` frames carry no sub id: one publish from the server fans out to
-every connected ws via Bun's native publish, and each ws delivers the
-message to every local sub of that socket. `replay`/`end`/`err` are
-per-sub — a seed batch belongs to the sub that requested it.
+Lazily opens the single multiplexed ws used by every socket proxy on the page.
+The sub registry + inbound `msg`/`replay`/`end`/`err` routing lives in
+`createSocketSubRegistry` (shared with the test harness); this channel owns the
+transport that wraps it — connect, reconnect/backoff, and visibility.
 
 Outbound frames sent before `ws.onopen` fires are queued and flushed
 on open. The channel reconnects on close with bounded backoff;
@@ -46,8 +39,6 @@ export function getSocketChannel(): SocketChannel {
     if (singleton) {
         return singleton
     }
-    const subs = new Map<string, { socket: string; callbacks: SocketSubCallbacks }>()
-    const subsBySocket = new Map<string, Set<string>>()
     let ws: WebSocket | undefined
     let pendingSends: string[] = []
     let backoffMs = 250
@@ -73,6 +64,10 @@ export function getSocketChannel(): SocketChannel {
         connect()
     }
 
+    /* The local sub registry + inbound frame routing; this channel owns only the
+       transport (connect/reconnect/backoff/visibility) around it. */
+    const registry = createSocketSubRegistry(send)
+
     function connect(): void {
         /* Backoff window owns reconnection; queued frames flush when its attempt opens. */
         if (reconnectTimer !== undefined) {
@@ -99,64 +94,26 @@ export function getSocketChannel(): SocketChannel {
             } catch {
                 return
             }
-            if (frame.type === 'msg') {
-                /*
-                One Bun-published frame fans out to every local sub of
-                that socket on this ws — addressed by socket name, not
-                per-sub id.
-                */
-                const targets = subsBySocket.get(frame.socket)
-                if (!targets) {
-                    return
-                }
-                for (const subId of targets) {
-                    subs.get(subId)?.callbacks.onMessage(frame.message)
-                }
-                return
-            }
-            if (frame.type === 'replay') {
-                subs.get(frame.sub)?.callbacks.onReplay(frame.messages)
-                return
-            }
-            if (frame.type === 'end') {
-                const sub = subs.get(frame.sub)
-                if (!sub) {
-                    return
-                }
-                dropSub(frame.sub)
-                sub.callbacks.onEnd()
-                return
-            }
-            if (frame.type === 'err') {
-                const sub = subs.get(frame.sub)
-                if (!sub) {
-                    return
-                }
-                dropSub(frame.sub)
-                sub.callbacks.onError(frame.message)
-                return
-            }
+            registry.routeFrame(frame)
         })
         ws.addEventListener('close', () => {
-            const active = [...subs.values()]
-            subs.clear()
-            subsBySocket.clear()
+            const active = registry.drainSubs()
             /*
             Drop any queued frames too. We've just torn down every local
             sub, so replaying their `sub`/`unsub`/`pub` frames on
             reconnect would open ghost subscriptions on the server that
             no client object tracks (and never gets an `unsub`). This
             keeps the "channel never re-subscribes" contract above
-            honest — consumers re-open fresh subs. Cleared before the
-            callbacks run so a consumer reacting to the disconnect (its
-            catch resolves in a microtask, after this handler) queues
-            onto a fresh list.
+            honest — consumers re-open fresh subs. `drainSubs` cleared the
+            registry before these callbacks run so a consumer reacting to
+            the disconnect (its catch resolves in a microtask, after this
+            handler) registers onto a fresh list.
             */
             const hadPending = pendingSends.length > 0
             pendingSends = []
             ws = undefined
-            for (const sub of active) {
-                sub.callbacks.onDisconnect()
+            for (const callbacks of active) {
+                callbacks.onDisconnect()
             }
             if (active.length === 0 && !hadPending) {
                 return
@@ -169,21 +126,6 @@ export function getSocketChannel(): SocketChannel {
         })
     }
 
-    function dropSub(id: string): void {
-        const entry = subs.get(id)
-        if (!entry) {
-            return
-        }
-        subs.delete(id)
-        const set = subsBySocket.get(entry.socket)
-        if (set) {
-            set.delete(id)
-            if (set.size === 0) {
-                subsBySocket.delete(entry.socket)
-            }
-        }
-    }
-
     /*
     Release the ws when the tab hides rather than hold an idle connection the
     browser throttles. Closing rides the normal drop path (close handler →
@@ -200,28 +142,6 @@ export function getSocketChannel(): SocketChannel {
         }
     })
 
-    singleton = {
-        subscribe(id, socket, replay, callbacks) {
-            subs.set(id, { socket, callbacks })
-            /* Not getOrInsertComputed: browser-side code, and Safari/Chrome only shipped it within the last browser cycle (26.2 / 145). */
-            let set = subsBySocket.get(socket)
-            if (!set) {
-                set = new Set()
-                subsBySocket.set(socket, set)
-            }
-            set.add(id)
-            send({ type: 'sub', sub: id, socket, replay })
-        },
-        unsubscribe(id) {
-            if (!subs.has(id)) {
-                return
-            }
-            dropSub(id)
-            send({ type: 'unsub', sub: id })
-        },
-        publish(socket, message) {
-            send({ type: 'pub', socket, message })
-        },
-    }
+    singleton = registry.channel
     return singleton
 }