@abide/abide 0.44.0 → 0.44.1

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

@@ -0,0 +1,79 @@
+import { effect } from '../effect.ts'
+import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { scope } from '../runtime/scope.ts'
+import { scopeGroup } from '../runtime/scopeGroup.ts'
+import { fillBefore } from './fillBefore.ts'
+import { openMarker } from './openMarker.ts'
+import { replaceRange } from './replaceRange.ts'
+
+/*
+The shared lifecycle of every single-slot control-flow block (`when`, `switchBlock`):
+a marker-bounded RANGE that holds at most one piece of content at a time, swapped as a
+unit when a `key` changes. The block supplies a `key()` thunk (the identity of the
+chosen branch — `'then'|'else'` for `when`, the case index for `switchBlock`) and a
+`contentFor(key)` resolver returning that branch's builder, or `undefined` for an
+empty branch. This module owns the marker setup, the hydrate-vs-create fork, and the
+swap effect with its reentrancy/teardown dance — the structure both blocks copy-pasted.
+
+The chosen branch builds through `scope` (directly on hydrate, via `fillBefore` on a
+swap), which builds untracked — so a raw reactive read in the branch content doesn't
+subscribe the swap effect; only `key()` (which reads the block's source) drives the
+toggle. The branch's own interpolations still track, each through its own effect.
+
+On hydrate it adopts the server-rendered range: claim the start marker, run the chosen
+branch in place (its content claims the existing nodes), then claim the end marker. The
+effect's first run sees the same key and is a no-op; later changes clear the range and
+build fresh into a fragment.
+
+`before` (a static node located by the skeleton) places the range among siblings on
+create, so the block sits before a static suffix rather than at the parent's end.
+Hydrate ignores it — the claim cursor (positioned past the prefix) drives placement.
+*/
+export function mountSwappableRange<Key>(
+    parent: Node,
+    key: () => Key,
+    contentFor: (key: Key) => ((parent: Node) => void) | undefined,
+    before: Node | null = null,
+): void {
+    const hydration = RENDER.hydration
+    /* The live branch's scope, registered with the owner so it disposes on owner
+       teardown — not only on a branch swap via replaceRange. */
+    const group = scopeGroup()
+    let dispose: (() => void) | undefined
+    let activeKey: Key
+    let end: Comment
+
+    const start = openMarker(parent, RANGE_OPEN, before)
+    if (hydration !== undefined) {
+        activeKey = key()
+        const chosen = contentFor(activeKey)
+        if (chosen !== undefined) {
+            dispose = group.track(scope(() => chosen(parent))) // content claims the SSR nodes in place
+        }
+        end = openMarker(parent, RANGE_CLOSE)
+    } else {
+        end = openMarker(parent, RANGE_CLOSE, before)
+        activeKey = key()
+        const chosen = contentFor(activeKey)
+        if (chosen !== undefined) {
+            dispose = group.track(fillBefore(end, chosen))
+        }
+    }
+
+    effect(() => {
+        const next = key()
+        if (next === activeKey) {
+            return
+        }
+        activeKey = next
+        const chosen = contentFor(next)
+        /* Null `dispose` before `replaceRange` builds the new branch: a reentrant swap
+           during that build (an effect in the new content writing the source) would
+           otherwise re-enter with the already-disposed disposer and clear it twice. */
+        const prior = dispose
+        dispose = undefined
+        const built = replaceRange(start, end, prior, chosen)
+        dispose = built !== undefined ? group.track(built) : undefined
+    })
+}

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

@@ -129,10 +129,19 @@ export function skeleton(parent: Node, html: string): SkeletonHoles {
         hydration.next.set(parent, node)
     } else {
         const children = source.childNodes
+        /* Stage clones in a fragment ONLY for a live (connected) parent, where one
+           append reflows once instead of per clone. A detached parent triggers no
+           reflow on append, so the fragment is pure overhead there — skip it and
+           append direct. `topLevel` collects each clone either way for anchor/
+           element-hole resolution. */
+        const target: Node = parent.isConnected ? document.createDocumentFragment() : parent
         for (let index = 0; index < children.length; index += 1) {
             const clone = (children[index] as Node).cloneNode(true)
             topLevel.push(clone)
-            parent.appendChild(clone)
+            target.appendChild(clone)
+        }
+        if (target !== parent) {
+            parent.appendChild(target)
         }
     }
     /* Anchor holes via the ONE shared ordering rule (`walkAnchorOrder`) — the same traversal

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

@@ -1,26 +1,16 @@
-import { effect } from '../effect.ts'
-import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
-import { RENDER } from '../runtime/RENDER.ts'
-import { scope } from '../runtime/scope.ts'
-import { scopeGroup } from '../runtime/scopeGroup.ts'
-import { fillBefore } from './fillBefore.ts'
-import { openMarker } from './openMarker.ts'
-import { replaceRange } from './replaceRange.ts'
+import { mountSwappableRange } from './mountSwappableRange.ts'
 import type { SwitchCase } from './types/SwitchCase.ts'
 
 /*
 Multi-branch binding — the runtime for `{#switch}` blocks and for `{#if}` chains that
 include `{:elseif}` branches (compiled as a switch over `true` with Boolean-coerced
-match thunks so the first truthy branch wins). An effect evaluates the
+match thunks so the first truthy branch wins). A swappable range evaluates the
 subject, picks the first case whose `match` equals it (strict `===`), falling back
 to the default (`match` undefined); the chosen case's content lives in a RANGE
 bounded by two comment markers, so a case holds any content. Staying on the same
 case across a subject change leaves it mounted; switching clears the range and
-builds the new case fresh.
-
-On hydrate it adopts the case the server rendered: claim the start marker, run the
-matching case in place, claim the end marker. The effect's first run picks the same
-case and is a no-op; later changes swap the range.
+builds the new case fresh. See `mountSwappableRange` for the shared
+hydrate/swap/teardown semantics — the case index is the swap key.
 */
 // @documentation plumbing
 export function switchBlock(
@@ -29,59 +19,21 @@ export function switchBlock(
     cases: SwitchCase[],
     before: Node | null = null,
 ): void {
-    const hydration = RENDER.hydration
-    /* The live case's scope, registered with the owner so it disposes on owner
-       teardown — not only when the subject switches cases via replaceRange. */
-    const group = scopeGroup()
-    let dispose: (() => void) | undefined
-    let activeIndex: number
-    let end: Comment
-
+    /* Pick the first case matching the subject (`===`), else the default (`match`
+       undefined), else -1 for no match. */
     const select = (value: unknown): number => {
         const matched = cases.findIndex(
             (entry) => entry.match !== undefined && entry.match() === value,
         )
         return matched === -1 ? cases.findIndex((entry) => entry.match === undefined) : matched
     }
-    const caseAt = (index: number): SwitchCase | undefined =>
-        index === -1 ? undefined : cases[index]
-    /* The chosen case builds through `scope` (directly on hydrate, via `fillBefore` on a
-       swap), which builds untracked — so a raw reactive read in the case content doesn't
-       subscribe the swap effect below; only `subject()` (and each case's `match()`) drives
-       the swap. The case's own interpolations still track, each through its own effect. */
-
-    /* `before` places the range among static siblings on create (block before a suffix);
-       hydrate ignores it and uses the parked claim cursor. */
-    const start = openMarker(parent, RANGE_OPEN, before)
-    if (hydration !== undefined) {
-        activeIndex = select(subject())
-        const chosen = caseAt(activeIndex)
-        if (chosen !== undefined) {
-            dispose = group.track(scope(() => chosen.render(parent))) // claim the SSR nodes in place
-        }
-        end = openMarker(parent, RANGE_CLOSE)
-    } else {
-        end = openMarker(parent, RANGE_CLOSE, before)
-        activeIndex = select(subject())
-        const chosen = caseAt(activeIndex)
-        if (chosen !== undefined) {
-            dispose = group.track(fillBefore(end, (p) => chosen.render(p)))
-        }
-    }
-
-    effect(() => {
-        const index = select(subject())
-        if (index === activeIndex) {
-            return
-        }
-        activeIndex = index
-        const chosen = caseAt(index)
-        /* Null `dispose` before `replaceRange` builds the new case: a reentrant switch
-           during that build (an effect in the new content writing the subject) would
-           otherwise re-enter with the already-disposed disposer and clear it twice. */
-        const prior = dispose
-        dispose = undefined
-        const next = replaceRange(start, end, prior, chosen && ((p) => chosen.render(p)))
-        dispose = next !== undefined ? group.track(next) : undefined
-    })
+    mountSwappableRange(
+        parent,
+        () => select(subject()),
+        (index) => {
+            const chosen = index === -1 ? undefined : cases[index]
+            return chosen && ((p) => chosen.render(p))
+        },
+        before,
+    )
 }

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

@@ -1,24 +1,13 @@
-import { effect } from '../effect.ts'
-import { RANGE_CLOSE, RANGE_OPEN } from '../runtime/RANGE_MARKER.ts'
-import { RENDER } from '../runtime/RENDER.ts'
-import { scope } from '../runtime/scope.ts'
-import { scopeGroup } from '../runtime/scopeGroup.ts'
-import { fillBefore } from './fillBefore.ts'
-import { openMarker } from './openMarker.ts'
-import { replaceRange } from './replaceRange.ts'
+import { mountSwappableRange } from './mountSwappableRange.ts'
 
 /*
 Conditional binding — the runtime for `<template if>` (with optional `else`). The
 branch's content lives in a RANGE bounded by two comment markers, so a branch may
 hold anything — elements, components, text, nested control-flow, snippets — not
-just element roots. An effect tracks `condition()` and swaps the range's content
-on a truthy↔falsy flip (`render` truthy, `renderElse` falsy); an unchanged
-condition is a no-op.
-
-On hydrate it adopts the server-rendered range: claim the start marker, run the
-matching render in place (its content claims the existing nodes), then claim the
-end marker. The effect's first run sees the same branch and is a no-op; later
-toggles clear the range and build fresh into a fragment.
+just element roots. A 2-case swappable range tracks `condition()` and swaps the
+range's content on a truthy↔falsy flip (`render` truthy, `renderElse` falsy); an
+unchanged condition is a no-op. See `mountSwappableRange` for the shared
+hydrate/swap/teardown semantics.
 */
 // @documentation plumbing
 export function when(
@@ -28,52 +17,10 @@ export function when(
     renderElse?: (parent: Node) => void,
     before: Node | null = null,
 ): void {
-    const hydration = RENDER.hydration
-    /* The chosen branch builds through `scope` (directly on hydrate, via `fillBefore`
-       on a swap), which builds untracked — so a raw reactive read in the branch content
-       doesn't subscribe the swap effect below; only `condition()` drives the toggle. The
-       branch's own interpolations still track, each through its own effect. */
-    const chosenFor = (branch: 'then' | 'else') => (branch === 'then' ? render : renderElse)
-    /* The live branch's scope, registered with the owner so it disposes on owner
-       teardown — not only on a branch flip via replaceRange. */
-    const group = scopeGroup()
-    let dispose: (() => void) | undefined
-    let activeBranch: 'then' | 'else'
-    let end: Comment
-
-    /* `before` (a static node located by the skeleton) places the range among siblings on
-       create, so the block sits before a static suffix rather than at the parent's end.
-       Hydrate ignores it — the claim cursor (positioned past the prefix) drives placement. */
-    const start = openMarker(parent, RANGE_OPEN, before)
-    if (hydration !== undefined) {
-        activeBranch = condition() ? 'then' : 'else'
-        const chosen = chosenFor(activeBranch)
-        if (chosen !== undefined) {
-            dispose = group.track(scope(() => chosen(parent))) // content claims the SSR nodes in place
-        }
-        end = openMarker(parent, RANGE_CLOSE)
-    } else {
-        end = openMarker(parent, RANGE_CLOSE, before)
-        activeBranch = condition() ? 'then' : 'else'
-        const chosen = chosenFor(activeBranch)
-        if (chosen !== undefined) {
-            dispose = group.track(fillBefore(end, chosen))
-        }
-    }
-
-    effect(() => {
-        const branch = condition() ? 'then' : 'else'
-        if (branch === activeBranch) {
-            return
-        }
-        activeBranch = branch
-        const chosen = chosenFor(branch)
-        /* Null `dispose` before `replaceRange` builds the new branch: a reentrant flip
-           during that build (an effect in the new content writing the condition) would
-           otherwise re-enter with the already-disposed disposer and clear it twice. */
-        const prior = dispose
-        dispose = undefined
-        const next = replaceRange(start, end, prior, chosen)
-        dispose = next !== undefined ? group.track(next) : undefined
-    })
+    mountSwappableRange(
+        parent,
+        () => (condition() ? 'then' : 'else'),
+        (branch) => (branch === 'then' ? render : renderElse),
+        before,
+    )
 }

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

@@ -43,6 +43,18 @@ the change.
 export function createDoc(initial: unknown): Doc {
     let tree = initial
     const nodes = new Map<string, ReactiveNode>()
+    /* Prefix index: every path → the set of its DIRECT children that lie on a route
+       to some minted node (a trie over the minted paths' ancestor chains). A
+       structural descend walks this from the change root through actual descendants
+       only, replacing the old O(all live cells) `startsWith` scan over the whole
+       `nodes` map. The links span INTERMEDIATE paths that have no node of their own
+       (e.g. `byId` and `byId/<key>` exist as links even when only `byId/<key>/n` was
+       read), so a descend from any ancestor reaches the leaf. Maintained in lockstep
+       with `nodes`: a node's whole ancestor chain is linked when `nodeFor` mints it,
+       unlinked from the leaf up when `wakeSubtree` evicts it. Membership of a path in
+       `nodes` (does it carry a signal?) is independent of its membership here (is it
+       on a route to one?). */
+    const childKeys = new Map<string, Set<string>>()
     /* Computed slots: a path whose value is a function of other paths, not stored
        truth. Held apart from `nodes` so the structural wake/eviction never touches
        them; their dirtiness is driven entirely by the deps they read (the signal
@@ -54,15 +66,65 @@ export function createDoc(initial: unknown): Doc {
        name the document it came from (reference identity, the undo/persistence key). */
     let self: Doc
 
+    /* Links `path` into the trie under its parent and continues up the ancestor chain.
+       Stops at the first ancestor whose parent set already lists it — that link, and
+       everything above it, is already present (some sibling minted the upper chain). */
+    function linkPath(path: string): void {
+        let child = path
+        for (;;) {
+            const parentPath = parentPathOf(child)
+            const siblings = childKeys.get(parentPath)
+            if (siblings === undefined) {
+                childKeys.set(parentPath, new Set([child]))
+            } else if (siblings.has(child)) {
+                return
+            } else {
+                siblings.add(child)
+            }
+            if (parentPath === '') {
+                return
+            }
+            child = parentPath
+        }
+    }
+
     function nodeFor(path: string): ReactiveNode {
         let node = nodes.get(path)
         if (node === undefined) {
             node = createSignalNode(walkPath(tree, path).value)
             nodes.set(path, node)
+            linkPath(path)
         }
         return node
     }
 
+    /* Drops a node and unlinks it from the trie, pruning each emptied ancestor link up
+       the chain — the eviction half of the lockstep with `nodeFor`. A link is removed
+       only once its child set empties, so an intermediate path with other live
+       descendants keeps its place. */
+    function evict(path: string): void {
+        nodes.delete(path)
+        let child = path
+        for (;;) {
+            const parentPath = parentPathOf(child)
+            const siblings = childKeys.get(parentPath)
+            if (siblings === undefined) {
+                return
+            }
+            siblings.delete(child)
+            /* A parent still listing other children, or still carrying its own node,
+               stays — only a fully empty, node-less link is pruned and walked past. */
+            if (siblings.size > 0) {
+                return
+            }
+            childKeys.delete(parentPath)
+            if (parentPath === '' || nodes.has(parentPath)) {
+                return
+            }
+            child = parentPath
+        }
+    }
+
     function read<T>(path: string): T {
         /* Size-gated so a doc with no computed slots pays nothing on the stored hot
            path — only one `.size` check, not a `.get` per read. */
@@ -109,25 +171,53 @@ export function createDoc(initial: unknown): Doc {
             return
         }
         const prefix = rootPath === '' ? '' : `${rootPath}/`
-        for (const [candidate, node] of nodes) {
-            if (candidate !== rootPath && candidate.startsWith(prefix)) {
-                /* A descendant whose path the mutation removed — a deleted key, an
-                   out-of-range index after a shrink — is woken to undefined, then
-                   dropped from the registry. Without eviction `nodes` grows for the
-                   life of the session over churning keys (items/<uuid>, message ids),
-                   and this very descend scan degrades linearly with it. The woken
-                   reader re-mints a fresh node on its flush if the path ever returns.
-                   Deleting the current entry mid-iteration is safe on a Map. */
+        /* Walk the prefix index from `rootPath` over its real descendants only — a
+           BFS over the parent→children adjacency map — instead of scanning every live
+           node. `pending` holds parent-paths whose direct children are yet to visit;
+           each visited child that is itself a container is enqueued. The total work is
+           the size of the changed subtree, not the whole doc. */
+        const pending: string[] = [rootPath]
+        while (pending.length > 0) {
+            const parentPath = pending.pop() as string
+            const siblings = childKeys.get(parentPath)
+            if (siblings === undefined) {
+                continue
+            }
+            /* Snapshot the set before iterating: eviction below mutates it, and a
+               deleted child must not skip its successor (Set iteration is order-
+               sensitive to in-place deletes). */
+            for (const candidate of [...siblings]) {
                 /* Walk from the already-resolved container (`rootValue`) using only the
                    path SUFFIX past the shared prefix, instead of re-walking every
                    candidate's full path from the tree root — the prefix is walked once
                    per wake, not once per descendant. */
                 const walk = walkPath(rootValue, candidate.slice(prefix.length))
+                /* An INTERMEDIATE link (a path on a route to a node but carrying none of
+                   its own — e.g. `byId/<key>` when only `byId/<key>/n` was read) has no
+                   signal to wake; it exists only to be descended through. So the
+                   wake/evict touches a node only when one is present, while the descend
+                   decision below is independent of node existence. */
+                const node = nodes.get(candidate)
                 if (walk.exists) {
-                    writeNode(node, walk.value)
+                    if (node !== undefined) {
+                        writeNode(node, walk.value)
+                    }
+                    /* Descend into a container child to reach its own descendants. */
+                    if (walk.value !== null && typeof walk.value === 'object') {
+                        pending.push(candidate)
+                    }
                 } else {
-                    writeNode(node, undefined)
-                    nodes.delete(candidate)
+                    /* A descendant whose path the mutation removed — a deleted key, an
+                       out-of-range index after a shrink — is woken to undefined, then
+                       dropped from the registry. The woken reader re-mints a fresh node
+                       on its flush if the path ever returns. A removed container's own
+                       descendants are still enqueued (whether or not THIS path held a
+                       node) so they too are woken/evicted. */
+                    if (node !== undefined) {
+                        writeNode(node, undefined)
+                        evict(candidate)
+                    }
+                    pending.push(candidate)
                 }
             }
         }

package/src/zodCjsPlugin.ts

@@ -20,6 +20,14 @@ the bug while keeping zod v4. Server-only: the client bundle strips zod from rpc
 modules (they become remote proxies), and dev never bundles.
 */
 export function zodCjsPlugin(cwd: string): BunPlugin {
+    /*
+    The (specifier, importer-dir) → cjs path mapping is deterministic per build —
+    zod's location doesn't move mid-build, and the filter fires for every zod
+    import in every module. Memoise on a `${path}\0${from}` key (mirrors the
+    resolver's resolveExtension cache) so the fs round-trips (resolveSync +
+    existsSync) run once per unique pair instead of once per import.
+    */
+    const cjsPathCache = new Map<string, string>()
     return {
         name: 'abide-zod-cjs',
         setup(build) {
@@ -27,9 +35,16 @@ export function zodCjsPlugin(cwd: string): BunPlugin {
                 /* Resolve from the importer (or cwd for the entry) to zod's ESM
                    target, then swap to its `.cjs` sibling when one exists. */
                 const from = args.importer ? dirname(args.importer) : cwd
+                const key = `${args.path}\0${from}`
+                const cached = cjsPathCache.get(key)
+                if (cached !== undefined) {
+                    return { path: cached }
+                }
                 const resolved = Bun.resolveSync(args.path, from)
                 const cjs = resolved.replace(/\.js$/, '.cjs')
-                return { path: existsSync(cjs) ? cjs : resolved }
+                const path = existsSync(cjs) ? cjs : resolved
+                cjsPathCache.set(key, path)
+                return { path }
             })
         },
     }

package/src/lib/shared/matchesDebugPattern.ts

@@ -1,16 +0,0 @@
-/*
-One DEBUG pattern against one channel name, npm-debug conventions:
-`*` matches everything, `abide:*` matches 'abide' and every 'abide:…'
-sub-channel, anything else matches exactly. Negation (`-` prefix) is the
-caller's concern — patterns arrive here already stripped.
-*/
-export function matchesDebugPattern(name: string, pattern: string): boolean {
-    if (pattern === '*') {
-        return true
-    }
-    if (pattern.endsWith(':*')) {
-        const prefix = pattern.slice(0, -2)
-        return name === prefix || name.startsWith(`${prefix}:`)
-    }
-    return pattern === name
-}

package/src/lib/shared/parseDebugPatterns.ts

@@ -1,21 +0,0 @@
-/*
-DEBUG's comma list, parsed once per distinct string — the gate runs on every
-log emission, and the env never changes server-side. A single-slot memo
-suffices: the browser's abide-debug localStorage toggle produces a new string
-that misses the memo and reparses.
-*/
-let lastEnv: string | undefined
-let lastPatterns: string[] = []
-
-export function parseDebugPatterns(env: string | undefined): string[] {
-    if (env !== lastEnv) {
-        lastEnv = env
-        lastPatterns = env
-            ? env
-                  .split(',')
-                  .map((raw) => raw.trim())
-                  .filter((pattern) => pattern !== '')
-            : []
-    }
-    return lastPatterns
-}