@abide/abide 0.28.0

package/src/lib/ui/router.ts

@@ -0,0 +1,286 @@
+import { layoutChainForRoute } from '../shared/layoutChainForRoute.ts'
+import { effect } from './effect.ts'
+import { matchRoute } from './matchRoute.ts'
+import { navigate } from './navigate.ts'
+import { clientPage } from './runtime/clientPage.ts'
+import { enterRenderPass } from './runtime/enterRenderPass.ts'
+import { exitRenderPass } from './runtime/exitRenderPass.ts'
+import { firstOutlet } from './runtime/firstOutlet.ts'
+import { runtimePath } from './runtime/runtimePath.ts'
+import type { NavVerdict } from './runtime/types/NavVerdict.ts'
+import type { Route } from './runtime/types/Route.ts'
+import type { RouteLoader } from './runtime/types/RouteLoader.ts'
+import { untrack } from './runtime/untrack.ts'
+
+/* A layout mounted in the active chain: its route key (the directory URL — its
+   identity for the diff), the disposer that stops its reactivity, and the outlet
+   element the next layer mounts into. */
+type MountedLayout = { key: string; dispose: () => void; outlet: Element }
+
+/* A layout mount that returns no disposer still needs one for the chain teardown. */
+const noop = (): void => {}
+
+/*
+A minimal client router on the History API. `router` matches the current path
+against the route patterns (literal / `[name]` / `[...rest]`, via matchRoute),
+imports the matching page's chunk — plus every `layout.abide` chunk that wraps it
+(`layoutChainForRoute`) — on demand, and mounts them as a chain: each layout into
+the previous layout's `<slot/>` outlet, the page into the innermost outlet.
+
+Navigation re-resolves the chain and DIFFS it against the mounted one: layouts whose
+route key still matches at the same depth stay mounted (their state, effects, scroll,
+and DOM survive); from the first divergent layout down — the leaf layers — everything
+is disposed and rebuilt, and the page (always the leaf) re-mounts every time. The
+reactive `page` proxy means a persisted layout reading route/params updates in place
+without a remount. Each chunk loads only on first visit, cached after.
+
+`probe` (when given) runs each post-boot navigation's destination through the
+server's app.handle first, so auth/redirect gating applies to client navigation
+just as it does to a fresh load; its verdict either clears the mount, soft-redirects
+where handle() pointed, or hands off to a full browser load. The first render
+adopts a document handle() already ran on, so it isn't probed. There is no server
+router — the server picks the page by request URL directly; this is the client
+half. `*` is the fallback route.
+*/
+// @readme plumbing
+export function router(
+    host: Element,
+    loaders: Record<string, RouteLoader>,
+    layoutLoaders: Record<string, RouteLoader> = {},
+    probe?: (path: string) => Promise<NavVerdict>,
+): () => void {
+    /* The mounted layout chain (outermost first) + the page disposer. */
+    const mountedLayouts: MountedLayout[] = []
+    let disposePage: (() => void) | undefined
+    const patterns = Object.keys(loaders).filter((key) => key !== '*')
+    const layoutKeys = Object.keys(layoutLoaders)
+
+    /* A code-split resolver over one loader map: resolved chunks keyed by route
+       pattern, so a revisit re-mounts without a second import. */
+    const resolver = (
+        map: Record<string, RouteLoader>,
+    ): ((key: string) => Promise<Route | undefined>) => {
+        const resolved = new Map<string, Route | undefined>()
+        return async (key) => {
+            if (resolved.has(key)) {
+                return resolved.get(key)
+            }
+            const loader = map[key]
+            const view = loader === undefined ? undefined : (await loader()).default
+            resolved.set(key, view)
+            return view
+        }
+    }
+    const resolvePage = resolver(loaders)
+    const resolveLayout = resolver(layoutLoaders)
+
+    /* Tear down the page and every layout from `index` inward (innermost first), then
+       return the container the rebuild mounts into — the surviving layout's outlet, or
+       `host` when the whole chain goes. */
+    const disposeFrom = (index: number): Element => {
+        disposePage?.()
+        disposePage = undefined
+        for (let depth = mountedLayouts.length - 1; depth >= index; depth -= 1) {
+            mountedLayouts[depth]?.dispose()
+        }
+        const base = index === 0 ? host : (mountedLayouts[index - 1] as MountedLayout).outlet
+        mountedLayouts.length = index
+        return base
+    }
+
+    /* Mount (or hydrate) the chain tail — layouts `[index..]` then the page — into
+       `base`, threading each layer into the previous one's outlet. Hydration brackets
+       ONE render pass across all layers so await/try block ids stay unique and aligned
+       with the SSR stream; a fresh mount needs no shared pass. */
+    const buildFrom = (
+        base: Element,
+        index: number,
+        chainKeys: string[],
+        layoutViews: Route[],
+        pageView: Route | undefined,
+        params: Record<string, string>,
+        hydrating: boolean,
+    ): void => {
+        const run = (): void => {
+            let container = base
+            for (let depth = index; depth < layoutViews.length; depth += 1) {
+                const view = layoutViews[depth] as Route
+                const dispose = hydrating
+                    ? (view.hydrate as NonNullable<Route['hydrate']>)(container, params)
+                    : (view(container, params) ?? noop)
+                const outlet = firstOutlet(container)
+                if (outlet === undefined) {
+                    throw new Error('[abide] a layout.abide must contain a <slot/> outlet')
+                }
+                mountedLayouts.push({ key: chainKeys[depth] as string, dispose, outlet })
+                container = outlet
+            }
+            if (pageView === undefined) {
+                return
+            }
+            disposePage = hydrating
+                ? (pageView.hydrate as NonNullable<Route['hydrate']>)(container, params)
+                : (pageView(container, params) ?? undefined)
+        }
+        if (hydrating) {
+            enterRenderPass()
+            try {
+                run()
+            } finally {
+                exitRenderPass()
+            }
+            return
+        }
+        run()
+    }
+
+    const onPopState = (): void => {
+        runtimePath.value = location.pathname + location.search + location.hash
+    }
+    const onClick = (event: MouseEvent): void => {
+        /* Let the browser own anything that isn't a plain primary-button click:
+           modified clicks (open in a new tab/window), middle/right buttons, and
+           already-handled events. */
+        if (
+            event.defaultPrevented ||
+            event.button !== 0 ||
+            event.metaKey ||
+            event.ctrlKey ||
+            event.shiftKey ||
+            event.altKey
+        ) {
+            return
+        }
+        const target = event.target as Element
+        const link = target.closest?.('a[href]') as HTMLAnchorElement | null
+        if (link === null) {
+            return
+        }
+        /* Defer to the browser for links it should own: a new-tab target, a
+           download, or an explicitly external rel. */
+        if (
+            (link.target !== '' && link.target !== '_self') ||
+            link.hasAttribute('download') ||
+            link.getAttribute('rel') === 'external'
+        ) {
+            return
+        }
+        const destination = new URL(link.href)
+        if (destination.origin !== location.origin) {
+            return
+        }
+        event.preventDefault()
+        /* Carry the query and hash, not just the pathname, so the destination page's
+           page.url sees them and an SPA navigation matches a fresh server load. */
+        navigate(destination.pathname + destination.search + destination.hash)
+    }
+    if (typeof window !== 'undefined') {
+        window.addEventListener('popstate', onPopState)
+        document.addEventListener('click', onClick as EventListener)
+    }
+
+    /* First render adopts the server-rendered DOM (when the matching page is
+       hydratable); navigation after that re-mounts fresh. */
+    let first = true
+    /* Monotonic token: a newer navigation that resolves first wins, so a slow
+       chunk landing late never overwrites the page the user has since moved to. */
+    let sequence = 0
+    /* Latched on teardown so a navigation whose imports/probe were in flight at
+       dispose can't run its `.then` and rebuild a chain we just tore down — the
+       `token` guard only catches a *newer* navigation, not disposal. */
+    let disposed = false
+    const stop = effect(() => {
+        /* The route is the only dependency the router should re-run on. Everything
+           else runs untracked so the page's build-time reads (each interpolation
+           reads its value once before wrapping it in its own effect) bind to the
+           page's own effects, not this one — otherwise any in-page state change
+           would re-run the router and re-mount the page, dropping local state. */
+        const path = runtimePath.value
+        untrack(() => {
+            /* The route matches on the pathname only; the query/hash ride along for
+               the probe (so server gating sees them) and for clientPage.url. */
+            const pathname = path.split(/[?#]/)[0] ?? path
+            const matched = matchRoute(patterns, pathname)
+            const key = matched?.route ?? '*'
+            const params = matched?.params ?? {}
+            /* The layout chain resolves off the literal route key (so a layout at a
+               `[id]` directory matches the `[name]` pattern, not the concrete path). */
+            const chainRoute = matched?.route ?? pathname
+            const chainKeys = layoutChainForRoute(chainRoute, layoutKeys)
+            sequence += 1
+            const token = sequence
+            /* First paint adopts a document the server already ran handle() on;
+               only later navigations re-run it through the probe. */
+            const verdict: Promise<NavVerdict> =
+                first || probe === undefined ? Promise.resolve({ kind: 'mount' }) : probe(path)
+            /* Resolve the page chunk, its layout chunks, and the gate in parallel,
+               keeping the current chain mounted until all land — no blank frame while
+               imports are in flight or the probe is in the air. */
+            void Promise.all([
+                resolvePage(key),
+                Promise.all(chainKeys.map((layoutKey) => resolveLayout(layoutKey))),
+                verdict,
+            ]).then(([pageView, resolvedLayouts, decision]) => {
+                if (token !== sequence || disposed) {
+                    return
+                }
+                /* handle() redirected: go where it pointed, replacing the blocked
+                   URL so back doesn't trap on it. The router re-probes the target. */
+                if (decision.kind === 'redirect') {
+                    navigate(decision.path, true)
+                    return
+                }
+                /* handle() blocked it / redirected off-origin / the probe failed:
+                   let the browser load the server's real response. */
+                if (decision.kind === 'reload') {
+                    if (typeof location !== 'undefined') {
+                        location.href = decision.url
+                    }
+                    return
+                }
+                /* Publish the active page so the `page` proxy resolves route/params/url. */
+                clientPage.value = {
+                    route: matched?.route ?? pathname,
+                    params,
+                    url:
+                        typeof location === 'undefined'
+                            ? new URL(`http://localhost${path}`)
+                            : new URL(location.href),
+                    navigating: false,
+                }
+                const layoutViews = resolvedLayouts.filter(
+                    (view): view is Route => view !== undefined,
+                )
+                /* The shared prefix of layouts (same route key at the same depth) stays
+                   mounted; the first divergence and everything inward is rebuilt. */
+                let divergence = 0
+                while (
+                    divergence < mountedLayouts.length &&
+                    divergence < chainKeys.length &&
+                    mountedLayouts[divergence]?.key === chainKeys[divergence]
+                ) {
+                    divergence += 1
+                }
+                const hydrating =
+                    first && pageView?.hydratable === true && pageView.hydrate !== undefined
+                first = false
+                const base = disposeFrom(divergence)
+                /* A fresh mount clears the torn-down DOM; hydration adopts it in place. */
+                if (!hydrating) {
+                    base.textContent = ''
+                }
+                buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
+            })
+        })
+    })
+
+    return () => {
+        disposed = true
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('popstate', onPopState)
+            document.removeEventListener('click', onClick as EventListener)
+        }
+        stop()
+        disposeFrom(0)
+    }
+}

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

@@ -0,0 +1,8 @@
+/* The element a layout's `<slot/>` lowers to: an empty structural container the
+   router fills with the next layer of the route's layout chain (the nested layout
+   or the page). SSR emits it empty so the renderer can fold the child's html into
+   it; on the client the router mounts/hydrates the child into it and finds it by
+   tag. Shared by both compiler back-ends, the SSR chain composer, and the router so
+   they all agree on the marker. */
+// @readme plumbing
+export const OUTLET_TAG = 'abide-outlet'

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

@@ -0,0 +1,8 @@
+/*
+The ownership scope currently collecting teardown callbacks. While a component
+(or a list row) builds, `scope()` points this at an array; every effect and event
+listener created during the build pushes its disposer here, so the whole instance
+tears down together. undefined outside any build — effects in plain code own
+their own lifecycle via the disposer they return.
+*/
+export const OWNER: { current: Array<() => void> | undefined } = { current: undefined }

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

@@ -0,0 +1,14 @@
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Mutable singletons shared by every reactive primitive: the observer currently
+running (so a read can register itself as that observer's dependency), the set
+of effects dirtied since the last flush, and the batch depth (writes inside a
+batch queue effects and flush once on exit). Held on one object so signal,
+computed, and effect all reference the same graph state without a barrel.
+*/
+export const REACTIVE_CONTEXT: {
+    observer: ReactiveNode | undefined
+    pendingEffects: Set<ReactiveNode>
+    batchDepth: number
+} = { observer: undefined, pendingEffects: new Set(), batchDepth: 0 }

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

@@ -0,0 +1,23 @@
+/*
+Render mode shared by the dom helpers. In the default (create) mode `hydration`
+is undefined and helpers build fresh nodes. During `hydrate` it holds, per parent,
+the next server-rendered child node to claim — a node pointer (not an index) so it
+survives nodes a block inserts (anchors) mid-hydration. Helpers claim in build
+order, which matches the SSR order, advancing the pointer to the next sibling.
+
+`blockId`/`depth` drive the render-pass block-id counter: every `await`/`try` block
+draws an id from `blockId` in document order, shared across a component and the
+child components it inlines, so ids are globally unique within one render pass (the
+SSR stream and client hydration agree on them — `RESUME` is keyed by id). `depth`
+tracks nesting so the OUTERMOST render/mount resets the counter and a child render/
+mount continues it. See `enterRenderPass`/`nextBlockId`.
+*/
+export const RENDER: {
+    hydration: { next: Map<Node, Node | null> } | undefined
+    blockId: number
+    depth: number
+} = {
+    hydration: undefined,
+    blockId: 0,
+    depth: 0,
+}

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

@@ -0,0 +1,16 @@
+/* The await-resume manifest: the resolved value (or error) of each streamed
+   `await` block, keyed by its boundary id. The SSR stream serializes each value
+   alongside its fragment; the client registers it (via `applyResolved` or the
+   inline swap script), and hydration reads it so an `await` block adopts the
+   resolved branch with the real value instead of re-running the promise.
+
+   Backed by `globalThis.__abideResume` so the inline stream-swap script (vanilla,
+   running during the stream before the bundle loads) and the framework share one
+   store: whoever runs first creates it, the other adopts the same reference. */
+export type ResumeEntry = { ok: true; value: unknown } | { ok: false; error: unknown }
+
+const globalScope = globalThis as { __abideResume?: Record<number, ResumeEntry> }
+globalScope.__abideResume ??= {}
+
+// @readme plumbing
+export const RESUME: Record<number, ResumeEntry> = globalScope.__abideResume

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

@@ -0,0 +1,41 @@
+import type { Patch } from './types/Patch.ts'
+
+/*
+Applies `patch` to `tree` by mutating in place and returns the root (a fresh
+value only when the root itself is replaced). In-place is the deliberate choice:
+the patch path already names exactly what changed, so we never need copy-on-write
+to *detect* a change — and cloning the spine made every leaf write O(width) of
+the widest ancestor (a 5k-item list copied 50k times in the bench). Mutating is
+O(depth). History/undo is served by journalling patches (the change is a value),
+not by retaining old roots — which is cheaper anyway. The wake step in createDoc
+force-notifies ancestor readers from the path, since their container keeps its
+identity now.
+
+`segments` is the patch path pre-split by the caller (createDoc also needs it),
+threaded in so the path is split once per patch rather than here and there.
+*/
+export function applyPatchToTree(tree: unknown, patch: Patch, segments: string[]): unknown {
+    /* Replacing the root can't mutate in place — hand back the new value. */
+    if (segments.length === 0) {
+        return patch.op === 'remove' ? undefined : patch.value
+    }
+    let parent = tree as Record<string, unknown>
+    for (const segment of segments.slice(0, -1)) {
+        parent = parent[segment] as Record<string, unknown>
+    }
+    const key = segments[segments.length - 1] as string
+    if (patch.op === 'replace') {
+        parent[key] = patch.value
+    } else if (patch.op === 'add') {
+        if (Array.isArray(parent)) {
+            parent.splice(key === '-' ? parent.length : Number(key), 0, patch.value)
+        } else {
+            parent[key] = patch.value
+        }
+    } else if (Array.isArray(parent)) {
+        parent.splice(Number(key), 1)
+    } else {
+        delete parent[key]
+    }
+    return tree
+}

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

@@ -0,0 +1,10 @@
+import type { RENDER } from './RENDER.ts'
+
+/* The next server-rendered node to claim under `parent` during hydration,
+   defaulting to its first child when the pointer hasn't been set yet. */
+export function claimChild(
+    hydration: NonNullable<(typeof RENDER)['hydration']>,
+    parent: Node,
+): Node | null {
+    return hydration.next.has(parent) ? (hydration.next.get(parent) ?? null) : parent.firstChild
+}

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

@@ -0,0 +1,16 @@
+import type { PageSnapshot } from '../../shared/types/PageSnapshot.ts'
+import { state } from '../state.ts'
+
+/*
+The client-side page snapshot the `page` proxy reads (startClient registers
+`() => clientPage.value` as the page resolver). It's a abide-ui signal, so a
+component reading page.url/params/route inside an effect re-runs when the router
+updates it on navigation. Server renders never touch this — there the resolver
+reads the per-request store instead.
+*/
+export const clientPage = state<PageSnapshot>({
+    route: '',
+    params: {},
+    url: typeof location === 'undefined' ? new URL('http://localhost/') : new URL(location.href),
+    navigating: false,
+})

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

@@ -0,0 +1,16 @@
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/* Creates a lazy derived node. Born dirty so its first read computes; thereafter
+   it recomputes only when a dependency triggers it. */
+export function createComputedNode(compute: () => unknown): ReactiveNode {
+    return {
+        value: undefined,
+        compute,
+        depsHead: undefined,
+        depsTail: undefined,
+        subsHead: undefined,
+        subsTail: undefined,
+        dirty: true,
+        isEffect: false,
+    }
+}

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

@@ -0,0 +1,177 @@
+import { applyPatchToTree } from './applyPatchToTree.ts'
+import { createSignalNode } from './createSignalNode.ts'
+import { flushEffects } from './flushEffects.ts'
+import { pathExists } from './pathExists.ts'
+import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
+import { readNode } from './readNode.ts'
+import { trigger } from './trigger.ts'
+import type { Cell } from './types/Cell.ts'
+import type { Doc } from './types/Doc.ts'
+import type { Patch } from './types/Patch.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+import { valueAtPath } from './valueAtPath.ts'
+import { writeNode } from './writeNode.ts'
+
+/*
+Builds a reactive document over `initial`. Each path read for the first time
+mints a signal node; the node is the notification token, the (mutable) tree is
+the source of truth. A patch mutates the tree in place — O(depth), not O(width) —
+then wakes from the patch's **change root** with shape-only reactivity:
+
+  - a value change at a path (an object key replaced with a new value) wakes only
+    that path and, if it became a container, its descendants — NOT its ancestors.
+    Reading a container subscribes to its own shape, so a deep field change never
+    re-runs a reader of the array/object above it (the reason a single list-item
+    edit doesn't reconcile the whole `each`).
+  - a structural change (add/remove anywhere, or replacing an array element by
+    index) changes the *parent container's* shape, so the parent is the change
+    root: it is force-notified (its identity is unchanged after in-place mutation)
+    and its descendants are re-read to pick up index shifts.
+
+Reads of exactly the changed path are gated by `Object.is`, so an equal write
+wakes nobody. Change is addressed, not diffed, and the address is as shallow as
+the change.
+*/
+export function createDoc(initial: unknown): Doc {
+    let tree = initial
+    const nodes = new Map<string, ReactiveNode>()
+
+    function nodeFor(path: string): ReactiveNode {
+        let node = nodes.get(path)
+        if (node === undefined) {
+            node = createSignalNode(valueAtPath(tree, path))
+            nodes.set(path, node)
+        }
+        return node
+    }
+
+    function read<T>(path: string): T {
+        return readNode(nodeFor(path)) as T
+    }
+
+    /*
+    Wakes readers from `rootPath`. `force` notifies the root unconditionally (a
+    structural change keeps the container's identity, so there is no new value to
+    compare); otherwise the root is written through the `Object.is` gate. When
+    `descend`, a container root also re-reads its existing descendant nodes (gated)
+    to catch nested and index-shifted values. `descend` is skipped for a change
+    that leaves every existing descendant path addressing the same value (an
+    end-append or an object-key add), so those updates stay O(depth) instead of
+    paying a scan over every minted node.
+    */
+    function wakeSubtree(rootPath: string, force: boolean, descend: boolean): void {
+        const rootValue = valueAtPath(tree, rootPath)
+        const rootNode = nodes.get(rootPath)
+        if (rootNode !== undefined) {
+            if (force) {
+                trigger(rootNode)
+            } else {
+                writeNode(rootNode, rootValue)
+            }
+        }
+        if (!descend || rootValue === null || typeof rootValue !== 'object') {
+            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. */
+                if (pathExists(tree, candidate)) {
+                    writeNode(node, valueAtPath(tree, candidate))
+                } else {
+                    writeNode(node, undefined)
+                    nodes.delete(candidate)
+                }
+            }
+        }
+    }
+
+    function apply(patch: Patch): void {
+        const segments = patch.path === '' ? [] : patch.path.split('/')
+        tree = applyPatchToTree(tree, patch, segments)
+        const parentPath = segments.slice(0, -1).join('/')
+        const parentValue = valueAtPath(tree, parentPath)
+        const leafKey = segments[segments.length - 1] as string | undefined
+        /* A structural change (add/remove, or an array element replaced by index)
+           reshapes the parent; a plain value replace reshapes only its own path. */
+        const parentIsArray = Array.isArray(parentValue)
+        const structural = patch.op !== 'replace' || parentIsArray
+        const arrayLength = parentIsArray ? (parentValue as unknown[]).length : 0
+        /* An add that introduces a new path without shifting any existing sibling —
+           an object-key add or an array append at the end — changes only the added
+           slot's subtree plus (for an array) its `length` node, never the existing
+           element nodes. Waking exactly those two avoids re-reading every descendant
+           of a large container. Every other structural change (any remove, a
+           mid-array insert, an array element replace) shifts indices or replaces a
+           subtree, so all descendants must be re-read. */
+        const nonShiftingAdd =
+            patch.op === 'add' &&
+            (!parentIsArray || leafKey === '-' || Number(leafKey) === arrayLength - 1)
+        REACTIVE_CONTEXT.batchDepth += 1
+        try {
+            if (segments.length === 0) {
+                wakeSubtree('', true, true)
+            } else if (!structural) {
+                wakeSubtree(patch.path, false, true)
+            } else if (nonShiftingAdd) {
+                wakeSubtree(parentPath, true, false)
+                /* The appended slot resolves to its real index when keyed by `-`. */
+                const addedPath =
+                    parentIsArray && leafKey === '-'
+                        ? `${parentPath}/${arrayLength - 1}`
+                        : patch.path
+                wakeSubtree(addedPath, false, true)
+                const lengthNode = parentIsArray ? nodes.get(`${parentPath}/length`) : undefined
+                if (lengthNode !== undefined) {
+                    writeNode(lengthNode, arrayLength)
+                }
+            } else {
+                wakeSubtree(parentPath, true, true)
+            }
+        } finally {
+            REACTIVE_CONTEXT.batchDepth -= 1
+        }
+        flushEffects()
+    }
+
+    /*
+    A stable accessor bound to one scalar leaf — what the compiler emits so a hot
+    loop has zero string work: the node, the parent container, and the leaf key
+    are resolved once. `set` mutates the parent directly and writes the node
+    through the gate; no ancestor walk, because a scalar leaf change is shape-only
+    (it never reshapes its container). Valid while ancestors keep their identity
+    (the scalar-field case); a wholesale ancestor replace re-binds the cell.
+    */
+    function cell<T>(path: string): Cell<T> {
+        const node = nodeFor(path)
+        const segments = path.split('/')
+        const leafKey = segments[segments.length - 1] as string
+        let parent = tree as Record<string, unknown>
+        for (const segment of segments.slice(0, -1)) {
+            parent = parent[segment] as Record<string, unknown>
+        }
+        return {
+            get: () => readNode(node) as T,
+            set: (value: T) => {
+                parent[leafKey] = value
+                writeNode(node, value)
+            },
+        }
+    }
+
+    return {
+        read,
+        cell,
+        apply,
+        replace: (path, value) => apply({ op: 'replace', path, value }),
+        add: (path, value) => apply({ op: 'add', path, value }),
+        remove: (path) => apply({ op: 'remove', path }),
+        snapshot: () => tree,
+    }
+}