@abide/abide 0.34.1 → 0.35.0

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

@@ -130,7 +130,7 @@ export function parseTemplate(source: string, baseOffset = 0): { nodes: Template
                 cursor += 1
             }
             if (source.charAt(cursor) !== '=') {
-                attrs.push({ kind: 'static', name, value: '' }) // boolean attribute
+                attrs.push({ kind: 'static', name, value: '', bare: true }) // boolean attribute
                 continue
             }
             cursor += 1 // past '='
@@ -284,13 +284,16 @@ function rejectStrayBranches(
 /* Turns a component's attributes into props. A component has no directives —
    every attribute is a prop under its written name, so `on*`/`bind:`/`attach`
    round-trip to their original names (the kinds the tag-blind attribute parser
-   assigned) instead of being dropped. A static value becomes a string literal;
-   every other kind keeps its `code`, letting a prop hold any value, functions
-   included (e.g. an `onclick` callback). */
+   assigned) instead of being dropped. A static value becomes a string literal —
+   a bare attribute coerces to `true` instead; every other kind keeps its `code`,
+   letting a prop hold any value, functions included (e.g. an `onclick` callback). */
 function toProps(attrs: TemplateAttr[]): { name: string; code: string; loc?: number }[] {
     return attrs.map((attr) => {
         if (attr.kind === 'static') {
-            return { name: attr.name, code: JSON.stringify(attr.value) }
+            /* A bare attribute (`<Toggle on />`) is a boolean flag: coerce it to
+               `true` so the prop reads as a boolean, not the empty string a native
+               element would serialise. An explicit `on=""` stays the empty string. */
+            return { name: attr.name, code: attr.bare ? 'true' : JSON.stringify(attr.value) }
         }
         /* Every non-static kind keeps its `code`/`loc`; only the prop name differs —
            a directive (`event`/`bind`/`attach`) round-trips to its written name. */

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

@@ -3,7 +3,7 @@ import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
 
 /*
 The signal binding names a `<script>` nested in a control-flow branch declares
-(`state`/`linked`/`computed`/`prop`). The back-end adds them to the deref scope so both the
+(`state`/`linked`/`computed`). The back-end adds them to the deref scope so both the
 script body and the branch's markup rewrite `{a}` → `a.value` — these stay PLAIN
 signals (local to the branch's render, owned by its scope, re-seeded from the
 in-scope data each mount), unlike the top-level component script which desugars to
@@ -30,7 +30,7 @@ export function nestedBindingNames(code: string): Set<string> {
     return names
 }
 
-/* The callee name of a `NAME = state(...)` / `computed(...)` / `prop(...)` declaration —
+/* The callee name of a `NAME = state(...)` / `computed(...)` / `linked(...)` declaration —
    bare or the explicit scope form (`scope().state(...)` / `c.state(...)`), receiver-agnostic. */
 function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
     const initializer = declaration.initializer

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

@@ -9,6 +9,13 @@ touched — declaration names, parameter names, and property names are collected
 into a skip set first, and object shorthand (`{ count }`) is expanded to
 `{ count: model.count }`. This is the bridge from the signal surface the author
 writes to the patch substrate underneath.
+
+The rewrite is lexically scope-aware: a reference whose name is re-bound by an
+enclosing scope (a function/arrow parameter or a nested local declaration) refers
+to that inner binding, not the component signal, so it is left untouched. Without
+this, a callback like `list.map(option => option.toUpperCase())` in a component
+that also has an `option` prop (`const { option } = props()`) would have its loop
+variable rewritten to `option()` and blow up at runtime (`option is not a function`).
 */
 export function renameSignalRefs(
     code: string,
@@ -18,6 +25,10 @@ export function renameSignalRefs(
 ): string {
     const source = ts.createSourceFile('component.ts', code, ts.ScriptTarget.Latest, true)
 
+    /* The signal names that a nested binding can shadow — only these matter for
+       scope tracking, so we ignore every other local binding. */
+    const signalNames = new Set<string>([...stateNames, ...derivedNames, ...computedNames])
+
     /* Identifier nodes that are names, not value reads — never rewritten. */
     const skip = new Set<ts.Node>()
     const collect = (node: ts.Node): void => {
@@ -45,33 +56,47 @@ export function renameSignalRefs(
 
     const result = ts.transform(source, [
         (context) => (root) => {
-            const visit = (node: ts.Node): ts.Node => {
-                /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`. */
-                if (ts.isShorthandPropertyAssignment(node)) {
-                    const replacement = referenceFor(
-                        node.name.text,
-                        stateNames,
-                        derivedNames,
-                        computedNames,
-                    )
-                    if (replacement !== undefined) {
-                        return ts.factory.createPropertyAssignment(node.name.text, replacement)
+            /* Each visitor carries the set of signal names shadowed by the scopes it sits
+               inside; entering a scope that re-binds a signal name produces a fresh visitor
+               with that name added, so shadowing is per-branch (a sibling scope is unaffected). */
+            const makeVisitor = (shadowed: ReadonlySet<string>): ts.Visitor => {
+                const visit = (node: ts.Node): ts.Node => {
+                    /* Shorthand `{ count }` → `{ count: model.count }` / `{ total: total.value }`,
+                       unless a nearer scope shadows the name. */
+                    if (ts.isShorthandPropertyAssignment(node) && !shadowed.has(node.name.text)) {
+                        const replacement = referenceFor(
+                            node.name.text,
+                            stateNames,
+                            derivedNames,
+                            computedNames,
+                        )
+                        if (replacement !== undefined) {
+                            return ts.factory.createPropertyAssignment(node.name.text, replacement)
+                        }
                     }
-                }
-                if (ts.isIdentifier(node) && !skip.has(node)) {
-                    const replacement = referenceFor(
-                        node.text,
-                        stateNames,
-                        derivedNames,
-                        computedNames,
-                    )
-                    if (replacement !== undefined) {
-                        return replacement
+                    if (ts.isIdentifier(node) && !skip.has(node) && !shadowed.has(node.text)) {
+                        const replacement = referenceFor(
+                            node.text,
+                            stateNames,
+                            derivedNames,
+                            computedNames,
+                        )
+                        if (replacement !== undefined) {
+                            return replacement
+                        }
                     }
+                    /* Recurse with the scope this node introduces folded in (same visitor when
+                       it adds no shadowing name, so unscoped subtrees allocate nothing extra). */
+                    const inner = extendShadowed(node, shadowed, signalNames)
+                    return ts.visitEachChild(
+                        node,
+                        inner === shadowed ? visit : makeVisitor(inner),
+                        context,
+                    )
                 }
-                return ts.visitEachChild(node, visit, context)
+                return visit
             }
-            return ts.visitNode(root, visit) as ts.SourceFile
+            return ts.visitNode(root, makeVisitor(new Set())) as ts.SourceFile
         },
     ])
     const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
@@ -80,6 +105,111 @@ export function renameSignalRefs(
     return output
 }
 
+/* The shadowed-name set for `node`'s children: the parent set plus any signal name
+   that `node` re-binds as a new scope. Returns the parent set unchanged (same
+   reference) when `node` introduces no colliding binding, so the caller can skip
+   allocating a new visitor. */
+function extendShadowed(
+    node: ts.Node,
+    shadowed: ReadonlySet<string>,
+    signalNames: ReadonlySet<string>,
+): ReadonlySet<string> {
+    const introduced = new Set<string>()
+    collectScopeBindings(node, introduced)
+    const added = [...introduced].filter((name) => signalNames.has(name) && !shadowed.has(name))
+    if (added.length === 0) {
+        return shadowed
+    }
+    return new Set<string>([...shadowed, ...added])
+}
+
+/* The names `node` binds when it opens a lexical scope — function/arrow parameters
+   (and the function's own name), block-level `let`/`const`/`function`/`class`,
+   `for`-header declarations, and the `catch` binding. Only names bound directly at
+   this scope; deeper scopes are folded in as the walk descends into them. */
+function collectScopeBindings(node: ts.Node, into: Set<string>): void {
+    const parameters = functionParameters(node)
+    if (parameters !== undefined) {
+        for (const parameter of parameters) {
+            collectBindingNames(parameter.name, into)
+        }
+        if (
+            (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node)) &&
+            node.name !== undefined
+        ) {
+            into.add(node.name.text)
+        }
+        return
+    }
+    if (ts.isBlock(node) || ts.isModuleBlock(node) || ts.isCaseBlock(node)) {
+        const statements = ts.isCaseBlock(node)
+            ? node.clauses.flatMap((clause) => [...clause.statements])
+            : node.statements
+        for (const statement of statements) {
+            collectStatementBindings(statement, into)
+        }
+        return
+    }
+    if (ts.isCatchClause(node) && node.variableDeclaration !== undefined) {
+        collectBindingNames(node.variableDeclaration.name, into)
+        return
+    }
+    if (ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) {
+        const initializer = node.initializer
+        if (initializer !== undefined && ts.isVariableDeclarationList(initializer)) {
+            for (const declaration of initializer.declarations) {
+                collectBindingNames(declaration.name, into)
+            }
+        }
+    }
+}
+
+/* The names a single block-level statement binds: `var`/`let`/`const`, and named
+   `function`/`class` declarations. */
+function collectStatementBindings(statement: ts.Statement, into: Set<string>): void {
+    if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+            collectBindingNames(declaration.name, into)
+        }
+    }
+    if (
+        (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
+        statement.name !== undefined
+    ) {
+        into.add(statement.name.text)
+    }
+}
+
+/* Every identifier bound by a binding name — a plain identifier or the leaves of a
+   destructuring pattern (object/array, including rest elements). */
+function collectBindingNames(name: ts.BindingName, into: Set<string>): void {
+    if (ts.isIdentifier(name)) {
+        into.add(name.text)
+        return
+    }
+    for (const element of name.elements) {
+        if (ts.isBindingElement(element)) {
+            collectBindingNames(element.name, into)
+        }
+    }
+}
+
+/* The parameter list of a function-like node, or undefined if `node` is not one. */
+function functionParameters(node: ts.Node): ts.NodeArray<ts.ParameterDeclaration> | undefined {
+    if (
+        ts.isArrowFunction(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node)
+    ) {
+        return node.parameters
+    }
+    return undefined
+}
+
 /* `model.<name>` for a state binding, `<name>()` for a computed doc-slot (the
    string-free reader `scope().derive` returns), `<name>.value` for a runtime cell
    (linked / lens / transform-state), else undefined. */

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/compile/types/TemplateAttr.ts

@@ -1,5 +1,7 @@
 /*
-An element attribute. `static` is a literal; `expression` is `name={code}` bound
+An element attribute. `static` is a literal — `bare` marks a valueless attribute
+(`disabled`, not `disabled=""`), letting a component coerce it to `true` while a
+native element still serialises it as `name=""`; `expression` is `name={code}` bound
 reactively; `event` is `on<event>={code}` where `code` evaluates to the handler;
 `bind` is `bind:<property>={lvalue}`, a two-way binding whose `code` is the
 writable doc path read into the property and written back on input; `attach` is
@@ -9,7 +11,7 @@ absolute offset of `code` in the original `.abide` source (see TextPart) —
 optional, set only when the parser tracks positions for the type-checking shadow.
 */
 export type TemplateAttr =
-    | { kind: 'static'; name: string; value: string }
+    | { kind: 'static'; name: string; value: string; bare?: true }
     | { kind: 'expression'; name: string; code: string; loc?: number }
     | { kind: 'event'; event: string; code: string; loc?: number }
     | { kind: 'bind'; property: string; code: string; loc?: number }

package/src/lib/ui/dom/applyResolved.ts

@@ -1,13 +1,23 @@
 import { RESUME } from '../runtime/RESUME.ts'
+import { seedStreamedResolution } from '../seedStreamedResolution.ts'
 
 /*
-Client consumer of an SSR stream fragment. Parses a streamed
-`<abide-resolve data-id="ID"><script type="application/json">…</script>…</abide-resolve>`
-frame, registers its serialized value in the resume manifest (for later hydration), finds the
-matching `<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary in `root`, removes
-the pending nodes between the markers, and inserts the resolved content in their
-place. The pending shell painted instantly; this swaps in each value as it
-arrives — completing the out-of-order streaming loop on the client.
+Bundle-side consumer of an SSR stream chunk, the counterpart of the doc stream's inline
+vanilla scripts (SSR_SWAP_SCRIPT's `__abideSwap` + `__abideResolve`) for a stream the
+running bundle consumes itself — streaming SPA navigation, socket-delivered SSR. It routes
+the two chunk kinds the stream interleaves:
+
+  - `<abide-cache>{StreamedResolution}</abide-cache>` → seed the streamed cache partition.
+    A script set via innerHTML never runs, so the cache channel rides a data frame here
+    (not the doc stream's `<script>__abideResolve(…)</script>`); seeding it keeps the
+    pending {#await} read warm instead of cold-missing to the network.
+  - `<abide-resolve data-id="ID"><script type="application/json">…</script>…</abide-resolve>`
+    → register the value in the resume manifest (for hydration), find the matching
+    `<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary in `root`, remove the pending
+    nodes between the markers, and insert the resolved content in their place.
+
+The pending shell painted instantly; this swaps in each value as it arrives — completing
+the out-of-order streaming loop on the client.
 */
 // @documentation plumbing
 export function applyResolved(root: Element, frame: string): void {
@@ -17,6 +27,16 @@ export function applyResolved(root: Element, frame: string): void {
     if (resolved === null || resolved.getAttribute === undefined) {
         return
     }
+    /* A cache-seed frame warms the streamed cache partition — paired with the DOM swap so a
+       bundle-consumed stream can't adopt a resolved branch while dropping its cache key. */
+    if (resolved.nodeName === 'ABIDE-CACHE') {
+        try {
+            seedStreamedResolution(JSON.parse(resolved.textContent ?? 'null'))
+        } catch {
+            /* malformed payload — leave unseeded; the read falls back to a live fetch */
+        }
+        return
+    }
     const id = resolved.getAttribute('data-id')
     if (id === null) {
         return

package/src/lib/ui/installHotBridge.ts

@@ -24,6 +24,7 @@ import { effect } from './effect.ts'
 import { enterScope } from './enterScope.ts'
 import { exitScope } from './exitScope.ts'
 import { enterRenderPass } from './runtime/enterRenderPass.ts'
+import { escapeKey } from './runtime/escapeKey.ts'
 import { exitRenderPass } from './runtime/exitRenderPass.ts'
 import { hotReloadEnabled } from './runtime/hotReloadEnabled.ts'
 import { hotReplace } from './runtime/hotReplace.ts'
@@ -68,6 +69,7 @@ export function installHotBridge(): void {
         mountSlot,
         mountChild,
         hydrate,
+        escapeKey,
         nextBlockId,
         enterRenderPass,
         exitRenderPass,

package/src/lib/ui/runtime/escapeKey.ts

@@ -4,10 +4,16 @@ Escapes one object key into a JSON Pointer reference token (RFC 6901): `~`→`~0
 survives a `/`-joined path instead of being mis-split into segments. `~` is
 escaped first so a `/`→`~1` substitution isn't re-escaped. The common key (a
 plain identifier) contains neither char, so the scan returns it untouched.
+
+Coerces first: lowerDocAccess wraps every dynamic path segment in this call, and a
+segment is often a number (an array index `lines[i]`) — String() mirrors the `+`
+join that built the path before, leaving numerics as their decimal text.
 */
-export function escapeKey(key: string): string {
-    if (!key.includes('~') && !key.includes('/')) {
-        return key
+// @documentation plumbing
+export function escapeKey(key: string | number): string {
+    const segment = String(key)
+    if (!segment.includes('~') && !segment.includes('/')) {
+        return segment
     }
-    return key.replace(/~/g, '~0').replace(/\//g, '~1')
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1')
 }

package/src/lib/ui/seedStreamedResolution.ts

@@ -0,0 +1,22 @@
+import { activeCacheStore } from '../shared/activeCacheStore.ts'
+import { cacheEntryFromSnapshot } from '../shared/cacheEntryFromSnapshot.ts'
+import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
+
+/*
+Seeds one streamed cache resolution into the active store — the single sink for the
+streamed (pending {#await}) cache partition. A full CacheSnapshotEntry warms the entry
+so a `cache()` read resolves synchronously (no wire round-trip) and `<template await>`
+adopts without a refetch; a `{ key, miss }` marker — a body the server couldn't snapshot
+(binary / rejected / evicted) — is a no-op, so that read falls back to a live fetch.
+
+Shared by startClient's boot drain, the live `window.__abideResolve`, and applyResolved,
+so no resolved-frame consumer can swap DOM while silently dropping the cache channel —
+the asymmetry that made streamed reads cold-miss to the network.
+*/
+// @documentation plumbing
+export function seedStreamedResolution(resolution: StreamedResolution): void {
+    if ('miss' in resolution) {
+        return
+    }
+    activeCacheStore().entries.set(resolution.key, cacheEntryFromSnapshot(resolution))
+}

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
 }