@abide/abide 0.44.0 → 0.45.0

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/lib/ui/runtime/createEffectNode.ts

@@ -1,3 +1,5 @@
+import { CURRENT_SCOPE } from './CURRENT_SCOPE.ts'
+import { inScope } from './inScope.ts'
 import { NODE_STATE } from './NODE_STATE.ts'
 import { OWNER } from './OWNER.ts'
 import { runNode } from './runNode.ts'
@@ -23,13 +25,17 @@ export function createEffectNode(fn: () => EffectResult): () => void {
        ReactiveNode so signals and computeds — which share the node shape and the
        read/write hot path — pay nothing for a feature only effects use. */
     let cleanup: Teardown | undefined
+    /* The teardown fires deferred (before a re-run, on dispose) when the ambient scope
+       has moved on; pin the one current at creation so an ambient `scope()` inside it
+       resolves the owning component, matching how `attach` pins its teardown. */
+    const captured = CURRENT_SCOPE.current
     /* Runs the previous run's teardown before re-running and on dispose, exactly
        once each. */
     const runCleanup = (): void => {
         if (cleanup !== undefined) {
             const teardown = cleanup
             cleanup = undefined
-            teardown()
+            inScope(captured, teardown)
         }
     }
     const node: ReactiveNode = {

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

@@ -11,6 +11,12 @@ drains the captured one — so an effect that dirties further effects re-queues
 for the next pass rather than mutating the array mid-iteration; loops until the
 graph settles. The swap reuses the drained array as the next spare, so a steady
 flush allocates nothing.
+
+Raises `batchDepth` for the whole drain so a write inside an effect body queues
+rather than re-entering the flush: `trigger` gates its flush on `batchDepth === 0`,
+and re-entry would run a just-dirtied effect nested — ahead of effects already in
+this pass and on a JS stack that grows with the write chain. Suppressed, the
+newly-dirtied effect falls to the `do…while` and runs in queue (creation) order.
 */
 export function flushEffects(): void {
     /* Empty-queue fast path allocates nothing — only the length check, matching the
@@ -20,6 +26,18 @@ export function flushEffects(): void {
     if (REACTIVE_CONTEXT.pendingEffects.length === 0) {
         return
     }
+    /* Always entered at depth 0 (trigger/batch-exit gate on it); the bump makes the
+       drain non-reentrant, restored in `finally` so a throwing effect body can't strand
+       the graph batched. */
+    REACTIVE_CONTEXT.batchDepth += 1
+    try {
+        drain()
+    } finally {
+        REACTIVE_CONTEXT.batchDepth -= 1
+    }
+}
+
+function drain(): void {
     let spare: ReactiveNode[] = []
     do {
         const batch = REACTIVE_CONTEXT.pendingEffects

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

@@ -0,0 +1,40 @@
+import { OWNER } from './OWNER.ts'
+
+/*
+A monotonic generation an async block checks before a late continuation touches the DOM. It
+answers one question — "is the work I started still the current work?" — and is bumped on the
+two events that both invalidate in-flight work: a reactive `renew()` (a re-run supersedes the
+prior promise/drain) and the enclosing OWNER's teardown (a settle after disposal must be
+DROPPED, not run `place`/`insertBefore` on a now-detached anchor → NotFoundError). `onTeardown`
+releases extra resources at teardown (e.g. an async iterator's `return()`).
+
+Extracted from the byte-identical guard hand-rolled in `awaitBlock` and `eachAsync`. The
+teardown half is the load-bearing one: a re-run bump alone leaves a promise/drain that settles
+AFTER disposal to still pass the liveness check and crash on the dead anchor — the bug both
+sites independently had to grow.
+*/
+export function generationGuard(onTeardown?: () => void): {
+    renew: () => number
+    token: () => number
+    live: (captured: number) => boolean
+} {
+    let generation = 0
+    /* The teardown bump is load-bearing: without it a promise/drain settling after the owner
+       disposes still passes `live(captured)` and touches a detached anchor. */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => {
+            generation += 1
+            onTeardown?.()
+        })
+    }
+    return {
+        /* Supersede any in-flight generation; call at the start of each (re-)run. Returns the
+           new token so a runner can capture it in the same statement. */
+        renew: () => (generation += 1),
+        /* The live generation to capture before an await and compare after — for when the
+           renew and the capture happen in different functions (as in awaitBlock's render). */
+        token: () => generation,
+        /* Whether `captured` is still the live generation — safe to touch the DOM. */
+        live: (captured: number) => captured === generation,
+    }
+}

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

@@ -34,7 +34,15 @@ export function runNode(node: ReactiveNode): unknown {
            on read without re-running, never waking downstream. An effect has no value
            worth comparing and no subscribers, so this is a no-op for it (its body ran
            inside compute above). The subscriber list isn't re-linked here — only its
-           members' `status` is bumped — so walking it live is safe. */
+           members' `status` is bumped — so walking it live is safe.
+
+           This bumps status directly, bypassing `mark` — it neither enqueues effects nor
+           propagates CHECK onward, yet nothing is missed: this recompute only happens
+           while settling a subscriber that was itself reached from the originating
+           write's `mark` propagation, which already CHECK-marked (and so enqueued) every
+           effect in this cone on their CLEAN→CHECK edge. So every subscriber here is
+           already CHECK/queued; the direct write only UPGRADES it CHECK→DIRTY so its own
+           settle recomputes instead of memoising back to CLEAN. */
         if (!Object.is(node.value, next)) {
             node.value = next
             let link = node.subsHead

package/src/lib/ui/runtime/types/SsrRender.ts

@@ -1,4 +1,4 @@
-import type { ResumeEntry } from '../RESUME.ts'
+import type { DeferMarker, ResumeEntry } from '../RESUME.ts'
 
 /* One STREAMING await block captured during SSR (no `then` on the `await` tag): its
    boundary id, the promise to await, and the async string-renderers for the resolved
@@ -18,10 +18,11 @@ export type SsrAwait = {
 /* The result of a component's server `render()`: the pending-shell HTML, the
    serializable document snapshot for client resume, the STREAMING await blocks to
    flush out of order, and `resume` — the inline-rendered BLOCKING await values keyed
-   by boundary id, seeded into the manifest so hydration adopts them without a refetch. */
+   by boundary id, seeded into the manifest so hydration adopts them without a refetch. A
+   deferred (cache-backed) blocking value is a `DeferMarker` in place of the value. */
 export type SsrRender = {
     html: string
     state: unknown
     awaits: SsrAwait[]
-    resume: Record<number, ResumeEntry>
+    resume: Record<number, ResumeEntry | DeferMarker>
 }

package/src/lib/ui/scope.ts

@@ -3,17 +3,15 @@ import { CURRENT_SCOPE } from './runtime/CURRENT_SCOPE.ts'
 import type { Scope } from './types/Scope.ts'
 
 /*
-Resolves a lexical scope. `scope()` returns the current one — established per
-lexical level by the compiler, so it reads "where you are" with no handle. Outside
-any scope (boot, a script) it mints a detached root once and reuses it. `scope('/')`
-returns the root of the current tree (the app-global scope). The returned value is
-passable: hand it to a child or a helper and it can read/extend/undo that scope.
+Resolves the current lexical scope — established per lexical level by the compiler,
+so it reads "where you are" with no handle. Outside any scope (boot, a script) it
+mints a detached root once and reuses it. The returned value is passable: hand it to
+a child or a helper and it can read/extend/undo that scope (walk up via `.root()`).
 */
 // @documentation reactive-state
-export function scope(address?: string): Scope {
+export function scope(): Scope {
     if (!CURRENT_SCOPE.current) {
         CURRENT_SCOPE.current = createScope()
     }
-    const current = CURRENT_SCOPE.current
-    return address === '/' ? current.root() : current
+    return CURRENT_SCOPE.current
 }

package/src/lib/ui/tryEncodeResume.ts

@@ -1,5 +1,5 @@
 import { encodeRefJson } from '../shared/encodeRefJson.ts'
-import type { ResumeEntry } from './runtime/RESUME.ts'
+import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
 
 /* ref-json-encode an await-resume entry, or `undefined` if it can't be serialized.
    encodeRefJson is total (cycles become back-references, functions fold to undefined),
@@ -7,7 +7,10 @@ import type { ResumeEntry } from './runtime/RESUME.ts'
    entry and warn, so the client re-runs that one branch's promise while every other
    branch stays seeded. Shared by the streaming (`renderToStream`) and buffered/seed
    (`resumeSeedScript`) paths so the serialize-or-refetch policy lives in one place. */
-export function tryEncodeResume(entry: ResumeEntry, id: number | string): string | undefined {
+export function tryEncodeResume(
+    entry: ResumeEntry | DeferMarker,
+    id: number | string,
+): string | undefined {
     try {
         return encodeRefJson(entry)
     } catch (cause) {

package/src/lib/ui/types/Scope.ts

@@ -1,7 +1,6 @@
 import type { computed } from '../computed.ts'
 import type { effect } from '../effect.ts'
 import type { linked } from '../linked.ts'
-import type { Cell } from '../runtime/types/Cell.ts'
 import type { Patch } from '../runtime/types/Patch.ts'
 import type { state } from '../state.ts'
 import type { SyncTransport } from './SyncTransport.ts'
@@ -9,7 +8,7 @@ import type { SyncTransport } from './SyncTransport.ts'
 /*
 A lexical scope: the unit that owns a region's reactive data, its lifetime, and
 the capabilities applied to it. Its data surface MIRRORS `Doc` (read/replace/add/
-remove/cell/derive/apply/snapshot) so the compiler can target a scope as a
+remove/derive/apply/snapshot) so the compiler can target a scope as a
 component's data binding directly. It nests (`child`/`root`), passes values
 down the tree as context (`share`/`shared`), and carries the capability surface as
 methods so a scope is a passable value: `<Child parentScope={scope} />`.
@@ -33,7 +32,6 @@ export type Scope = {
     add: (path: string, value: unknown) => void
     remove: (path: string) => void
     apply: (patch: Patch) => void
-    cell: <T>(path: string) => Cell<T>
     derive: <T>(path: string, compute: () => T) => () => T
     snapshot: () => unknown
     /* The reactive primitives — namespaced under the scope, but AMBIENT-bound, not
@@ -64,7 +62,8 @@ export type Scope = {
     /* context — values shared DOWN the tree (not in the reactive doc, which doesn't
        inherit): `share` puts a named value on this scope; `shared` reads the closest
        ancestor (self included) that has the key, undefined if none. The value is held
-       by reference, so reactive context = share a `cell`/scope, not a plain object. */
+       by reference, so reactive context = share a scope (its doc is reactive), not a
+       plain object snapshot. */
     share: (key: string, value: unknown) => void
     shared: <T>(key: string) => T | undefined
     /* capabilities — enable where the scope's changes go */

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/server/rpc/buildErrorConstructors.ts

@@ -1,19 +0,0 @@
-import type { ErrorConstructors } from '../../shared/types/ErrorConstructors.ts'
-import type { ErrorSpec } from '../../shared/types/ErrorSpec.ts'
-
-/*
-Turns a rpc's declared `ErrorSpec` into the constructor object handed to the
-handler (`(args, { errors })`). Each constructor stamps its name + status onto an
-`ErrorDescriptor` carrying the call's `data`, which `error()` serializes as the
-`{ $abideError, data }` body. Receiver-agnostic on data: a nullary error ignores
-the (absent) argument.
-*/
-export function buildErrorConstructors<Spec extends ErrorSpec>(
-    spec: Spec,
-): ErrorConstructors<Spec> {
-    const entries = Object.entries(spec).map(([name, { status }]) => [
-        name,
-        (data: unknown) => ({ $abideError: name, status, data }),
-    ])
-    return Object.fromEntries(entries) as ErrorConstructors<Spec>
-}

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
-}

package/src/lib/shared/types/ErrorConstructors.ts

@@ -1,17 +0,0 @@
-import type { ErrorDescriptor } from './ErrorDescriptor.ts'
-import type { ErrorSpec } from './ErrorSpec.ts'
-import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
-
-/*
-The constructors handed to the handler via its second arg (`(args, { errors })`),
-derived from the rpc's `ErrorSpec`. An entry with a `data` schema makes its
-constructor require that schema's inferred input; an entry without one is nullary.
-Each returns a typed `ErrorDescriptor` to pass to `error()`.
-*/
-export type ErrorConstructors<Spec extends ErrorSpec> = {
-    [Name in keyof Spec & string]: Spec[Name]['data'] extends StandardSchemaV1
-        ? (
-              data: StandardSchemaV1.InferInput<Spec[Name]['data']>,
-          ) => ErrorDescriptor<Name, StandardSchemaV1.InferInput<Spec[Name]['data']>>
-        : () => ErrorDescriptor<Name, undefined>
-}

package/src/lib/shared/types/ErrorDescriptor.ts

@@ -1,10 +0,0 @@
-/*
-What a rpc error constructor returns: a plain descriptor (NOT a Response), so it
-flows through the single `error()` funnel — `return error(errors.invalidCoupon({…}))`.
-`error()` reads `status` off it and serializes `{ $abideError: name, data }` as the body.
-*/
-export type ErrorDescriptor<Name extends string = string, Data = unknown> = {
-    readonly $abideError: Name
-    readonly status: number
-    readonly data: Data
-}