@abide/abide 0.40.0 → 0.40.1

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

@@ -1,16 +1,121 @@
 import type { PageSnapshot } from '../../shared/types/PageSnapshot.ts'
 import { state } from '../state.ts'
+import { flushEffects } from './flushEffects.ts'
+import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
+import type { State } from './types/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.
+`() => clientPage.value` as the page resolver). Server renders never touch this —
+there the resolver reads the per-request store instead.
+
+GRANULAR by field: rather than one signal holding the whole snapshot (which woke
+every `page.*` reader on any navigation), each field is its own cell and each param
+key its own lazily-created cell. So a reader of `page.params.id` subscribes to the id
+cell alone and is NOT woken when `page.params.rest` changes (stepping between episodes
+on one detail page) — no manual `computed` memo needed at the call site.
+
+The `.value` get/set API is unchanged, so the router and tests still read
+`clientPage.value.url` and write `clientPage.value = {…}`: the getter returns a STABLE
+snapshot whose field accessors do the granular reads (returning a stable object is what
+stops `clientPage.value` itself from subscribing to everything — a subscription happens
+only when a field is read), and the setter reconciles each field cell (an Object.is-equal
+write is a no-op, so an unchanged id never fires).
 */
-export const clientPage = state<PageSnapshot>({
-    route: '',
-    params: {},
-    url: typeof location === 'undefined' ? new URL('http://localhost/') : new URL(location.href),
-    navigating: false,
+
+const routeCell = state<string>('')
+const navigatingCell = state<boolean>(false)
+const urlCell = state<URL>(
+    typeof location === 'undefined' ? new URL('http://localhost/') : new URL(location.href),
+)
+
+/* Per-param-key cells, created on first read/write of a key. A page that reads
+   `page.params.id` mints the id cell and subscribes to it alone. Keys persist across
+   navigations (the Map is bounded by the app's param vocabulary); a route that drops a
+   key sets its cell to undefined so its readers wake to the absence. */
+const paramCells = new Map<string, State<string | undefined>>()
+function paramCell(key: string): State<string | undefined> {
+    let cell = paramCells.get(key)
+    if (cell === undefined) {
+        cell = state<string>()
+        paramCells.set(key, cell)
+    }
+    return cell
+}
+
+/* The surface `page.params` exposes: each key access is a granular cell read, so it
+   tracks per-key like the underlying object would, but reactively. */
+const paramsProxy = new Proxy({} as Record<string, string>, {
+    get: (_target, key) => (typeof key === 'string' ? paramCell(key).value : undefined),
+    has: (_target, key) => typeof key === 'string' && paramCell(key).value !== undefined,
+    ownKeys: () =>
+        [...paramCells].filter(([, cell]) => cell.value !== undefined).map(([key]) => key),
+    getOwnPropertyDescriptor: (_target, key) => {
+        if (typeof key !== 'string') {
+            return undefined
+        }
+        const value = paramCell(key).value
+        if (value === undefined) {
+            return undefined
+        }
+        return { enumerable: true, configurable: true, value }
+    },
 })
+
+/* The stable snapshot `clientPage.value` returns — reading a field does the granular
+   cell read, so a reader subscribes to that field alone. */
+const snapshot: PageSnapshot = {
+    get route(): string {
+        return routeCell.value
+    },
+    get params(): Record<string, string> {
+        return paramsProxy
+    },
+    get url(): URL {
+        return urlCell.value
+    },
+    get navigating(): boolean {
+        return navigatingCell.value
+    },
+}
+
+/* Reconcile the param cells to `next`: write each key (Object.is in the cell skips a
+   no-op, so an unchanged id stays asleep), clear any key the new route dropped. The
+   spread-and-rewrite paths (`{ ...clientPage.value, navigating }`) hand our own proxy
+   straight back — a no-op, recognised by identity. */
+function reconcileParams(next: Record<string, string>): void {
+    if (next === paramsProxy) {
+        return
+    }
+    for (const key of Object.keys(next)) {
+        paramCell(key).value = next[key]
+    }
+    for (const [key, cell] of paramCells) {
+        if (!(key in next)) {
+            cell.value = undefined
+        }
+    }
+}
+
+export const clientPage: { value: PageSnapshot } = {
+    get value(): PageSnapshot {
+        return snapshot
+    },
+    set value(next: PageSnapshot) {
+        /* Batch the field writes so a navigation publishes the whole snapshot atomically:
+           without it each cell write flushes effects separately, so a reader of two fields
+           (e.g. `page.url` + `page.params.id`) re-runs once per field and transiently
+           observes a half-updated snapshot (new url, stale id). Same batch idiom as
+           `createDoc` — flush once, after every cell is reconciled. */
+        REACTIVE_CONTEXT.batchDepth += 1
+        try {
+            routeCell.value = next.route
+            urlCell.value = next.url
+            navigatingCell.value = next.navigating
+            reconcileParams(next.params)
+        } finally {
+            REACTIVE_CONTEXT.batchDepth -= 1
+        }
+        flushEffects()
+    },
+}

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

@@ -1,7 +1,9 @@
+import { NODE_STATE } from './NODE_STATE.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
-/* Creates a lazy computed node. Born dirty so its first read computes; thereafter
-   it recomputes only when a dependency triggers it. */
+/* Creates a lazy computed node. Born DIRTY so its first read computes; thereafter a
+   read settles it — recomputing only when the check walk finds a dependency whose
+   value actually changed. */
 export function createComputedNode(compute: () => unknown): ReactiveNode {
     return {
         value: undefined,
@@ -10,7 +12,7 @@ export function createComputedNode(compute: () => unknown): ReactiveNode {
         depsTail: undefined,
         subsHead: undefined,
         subsTail: undefined,
-        dirty: true,
+        status: NODE_STATE.DIRTY,
         isEffect: false,
     }
 }

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

@@ -1,3 +1,4 @@
+import { NODE_STATE } from './NODE_STATE.ts'
 import { OWNER } from './OWNER.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
 import { runNode } from './runNode.ts'
@@ -42,7 +43,8 @@ export function createEffectNode(fn: () => EffectResult): () => void {
         depsTail: undefined,
         subsHead: undefined,
         subsTail: undefined,
-        dirty: false,
+        /* Born DIRTY; the immediate `runNode` below captures deps and settles it CLEAN. */
+        status: NODE_STATE.DIRTY,
         isEffect: true,
     }
     runNode(node)

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

@@ -1,7 +1,9 @@
+import { NODE_STATE } from './NODE_STATE.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
 /* Creates a writable leaf node holding `value` with no compute — the source a
-   document path or a `state()` cell is backed by. */
+   document path or a `state()` cell is backed by. Always CLEAN: a signal has no
+   dependencies to settle; its value is whatever was last written. */
 export function createSignalNode(value: unknown): ReactiveNode {
     return {
         value,
@@ -10,7 +12,7 @@ export function createSignalNode(value: unknown): ReactiveNode {
         depsTail: undefined,
         subsHead: undefined,
         subsTail: undefined,
-        dirty: false,
+        status: NODE_STATE.CLEAN,
         isEffect: false,
     }
 }

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

@@ -1,17 +1,20 @@
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
-import { runNode } from './runNode.ts'
+import { updateIfNecessary } from './updateIfNecessary.ts'
 
 /*
-Drains queued effects synchronously. Snapshots and clears the queue each pass so
-an effect that dirties further effects re-queues them for the next pass rather
-than mutating the set mid-iteration; loops until the graph settles.
+Drains queued effects synchronously. Each is queued when it first leaves CLEAN, but
+runs only if `updateIfNecessary` finds a dependency that truly changed — a CHECK
+effect whose deps all memoised back to equal values settles to CLEAN without
+running its body. Snapshots and clears the queue each pass so an effect that dirties
+further effects re-queues them for the next pass rather than mutating the set
+mid-iteration; loops until the graph settles.
 */
 export function flushEffects(): void {
     while (REACTIVE_CONTEXT.pendingEffects.size > 0) {
         const batch = [...REACTIVE_CONTEXT.pendingEffects]
         REACTIVE_CONTEXT.pendingEffects.clear()
         for (const node of batch) {
-            runNode(node)
+            updateIfNecessary(node)
         }
     }
 }

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

@@ -51,6 +51,39 @@ const offsets = new Map<number, [number, number]>()
 let current = 0
 let seq = 0
 
+/* Generation token for an in-flight `restore` retry chain (below); a newer restore
+   bumps it so a stale chain — from a superseded navigation — stops re-applying. */
+let restoreToken = 0
+/* Frame budget for re-applying a saved offset while the page is still filling in.
+   ~half a second at 60fps — long enough for an async page's content to settle, short
+   enough not to fight a user who starts scrolling. */
+const MAX_RESTORE_FRAMES = 30
+
+/* Re-apply a saved offset until it sticks. A restore can land before the page's async
+   content has materialised — `disposeFrom` empties the document, `buildFrom` mounts a
+   page whose blocking `<template await>` is still pending, so the document is momentarily
+   short and the browser clamps the requested offset to its tiny max (an in-page episode
+   swap reset to the top this way). Each frame re-applies; once `scrollTo` is no longer
+   clamped (the content has grown tall enough to honour the offset) the chain stops, so
+   the common case — a page already tall — applies exactly once and schedules no frame. */
+function reapplyOffset(offset: [number, number], token: number): void {
+    const apply = (framesLeft: number): void => {
+        // A newer restore superseded this chain, or the scroll surface vanished.
+        if (token !== restoreToken || typeof view.scrollTo !== 'function') {
+            return
+        }
+        view.scrollTo(offset[0], offset[1])
+        // The browser clamps to the current max; an honoured offset means the page is
+        // tall enough now — stop. Otherwise retry next frame as the content fills in.
+        const reached = (view.scrollY ?? 0) >= offset[1] && (view.scrollX ?? 0) >= offset[0]
+        if (reached || framesLeft <= 0 || typeof view.requestAnimationFrame !== 'function') {
+            return
+        }
+        view.requestAnimationFrame(() => apply(framesLeft - 1))
+    }
+    apply(MAX_RESTORE_FRAMES)
+}
+
 export const historyEntries = {
     /* The active history entry's id — stamped into history.state by `navigate`. */
     get current(): number {
@@ -98,9 +131,14 @@ export const historyEntries = {
         if (typeof view.scrollTo !== 'function') {
             return
         }
+        /* Any restore supersedes a pending retry chain — including this top/anchor path,
+           so a later navigation to a fresh page can't have an earlier keepScroll swap's
+           re-apply fire its stale offset over it. */
+        restoreToken += 1
+        const token = restoreToken
         const offset = offsets.get(current) ?? persistedOffset()
         if (offset !== undefined) {
-            view.scrollTo(offset[0], offset[1])
+            reapplyOffset(offset, token)
             return
         }
         const anchor = anchorFor(hash)

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

@@ -1,16 +1,17 @@
-import { runNode } from './runNode.ts'
 import { track } from './track.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
+import { updateIfNecessary } from './updateIfNecessary.ts'
 
 /*
-Reads a node's current value and subscribes the running observer to it. A dirty
-computed recomputes first (lazy pull); a signal returns its stored value
-directly. Tracking happens after recompute so the reader links to the computed
-itself, not its transitive deps.
+Reads a node's current value and subscribes the running observer to it. A computed
+settles first (the lazy pull — `updateIfNecessary` refreshes only the deps that
+changed, recomputing if any did); a signal has no compute and returns its stored
+value directly. Tracking happens after the settle so the reader links to the
+computed itself, not its transitive deps.
 */
 export function readNode(node: ReactiveNode): unknown {
-    if (node.compute !== undefined && node.dirty) {
-        runNode(node)
+    if (node.compute !== undefined) {
+        updateIfNecessary(node)
     }
     track(node)
     return node.value

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

@@ -1,5 +1,6 @@
 import { abortNode } from './abortNode.ts'
 import { endTracking } from './endTracking.ts'
+import { NODE_STATE } from './NODE_STATE.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
 import { reactiveAbortState } from './reactiveAbortState.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
@@ -26,8 +27,23 @@ export function runNode(node: ReactiveNode): unknown {
     const previous = REACTIVE_CONTEXT.observer
     REACTIVE_CONTEXT.observer = node
     try {
-        node.value = node.compute?.()
-        node.dirty = false
+        const next = node.compute?.()
+        /* Value memoisation: only a computed whose result actually changed marks its
+           subscribers DIRTY, so the in-progress check walk recomputes them. An
+           Object.is-equal recompute leaves them at CHECK — they settle back to CLEAN
+           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. */
+        if (!Object.is(node.value, next)) {
+            node.value = next
+            let link = node.subsHead
+            while (link !== undefined) {
+                link.sub.status = NODE_STATE.DIRTY
+                link = link.nextSub
+            }
+        }
+        node.status = NODE_STATE.CLEAN
         return node.value
     } finally {
         REACTIVE_CONTEXT.observer = previous

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

@@ -1,17 +1,28 @@
 import { OWNER } from './OWNER.ts'
+import { untrack } from './untrack.ts'
 
 /*
 Runs `build` under a fresh ownership scope so every effect and listener created
 inside is collected, and returns a disposer that tears them all down in reverse
 order (children before parents). Save/restore of the previous owner makes scopes
 nest — a list row's scope sits inside its component's scope.
+
+The build runs UNTRACKED. A detached subtree is built synchronously, and when that
+build happens inside a swap effect (a control-flow block re-running `each`/`when`/
+`switch`/`await`) its top-level reads would otherwise subscribe THAT effect, so any
+in-content state change would re-run the block and rebuild the whole subtree. The
+content's own interpolations still track normally — each wraps its read in its own
+effect, which re-installs itself as the observer. Untracking here is the framework's
+invariant (a build never subscribes its builder) stated once, so no control-flow
+block has to remember it; it's a harmless no-op for top-level builds (mount/hydrate),
+where there is no surrounding observer to leak into.
 */
 export function scope(build: () => void): () => void {
     const previous = OWNER.current
     const disposers: Array<() => void> = []
     OWNER.current = disposers
     try {
-        build()
+        untrack(build)
     } finally {
         OWNER.current = previous
     }

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

@@ -1,43 +1,59 @@
 import { flushEffects } from './flushEffects.ts'
+import { NODE_STATE } from './NODE_STATE.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
 /*
-Invalidates the observer cone of a just-written node: effect observers are
-queued, computed observers are marked dirty and recursed into (their value may
-now differ, so their own observers must learn of it). Recompute is lazy — a
-computed recomputes on next read — so this pass only invalidates and collects.
-
-The subscriber list is walked live: invalidate runs no compute and no effect, so
-nothing re-subscribes (the only mutators of a subscriber list, `track` and
-`runNode`, run inside compute execution, which only `flushEffects` reaches — after
-this pass). The re-subscribe hazard belongs to the flush, where `flushEffects`
-defends with its own snapshot. `nextSub` is read before recursing, so the walk
-holds no reference a downstream pass could invalidate.
+Raises `node` to at least `status` and propagates the news up its subscriber cone.
+An effect crossing out of CLEAN is queued (whether it became CHECK or DIRTY — the
+flush decides whether it really runs). A computed crossing out of CLEAN propagates
+CHECK to *its* subscribers, so the whole cone learns a dependency *might* have
+changed; it does so exactly once (a later CHECK→DIRTY upgrade re-notifies nobody —
+its subscribers are already CHECK). No compute runs here, so no subscriber list is
+re-linked mid-walk (`track`/`runNode` run inside compute, which only the flush
+reaches). `nextSub` is read before recursing so the walk holds no edge a deeper
+pass could detach.
 */
-function invalidate(node: ReactiveNode): void {
+function mark(node: ReactiveNode, status: number): void {
+    if (node.status >= status) {
+        return
+    }
+    const wasClean = node.status === NODE_STATE.CLEAN
+    node.status = status
+    if (node.isEffect) {
+        if (wasClean) {
+            REACTIVE_CONTEXT.pendingEffects.add(node)
+        }
+        return
+    }
+    /* A computed propagates CHECK to its subscribers only on its first move out of
+       CLEAN — they are already CHECK on any later upgrade, so re-walking is wasted. */
+    if (!wasClean) {
+        return
+    }
     let link = node.subsHead
     while (link !== undefined) {
-        const observer = link.sub
         const next = link.nextSub
-        if (observer.isEffect) {
-            REACTIVE_CONTEXT.pendingEffects.add(observer)
-        } else if (!observer.dirty) {
-            observer.dirty = true
-            invalidate(observer)
-        }
+        mark(link.sub, NODE_STATE.CHECK)
         link = next
     }
 }
 
 /*
-Propagates a change forward from a just-written node. Invalidation collects the
-whole cone first; the queued effects flush once, at the outermost trigger (or,
-inside a batch, when the batch owner exits) — never mid-propagation, so an effect
-never runs against a half-invalidated graph.
+Propagates a change forward from a just-written signal: its direct subscribers read
+a value that actually changed, so they are DIRTY; the rest of their cone is CHECK
+(a transitive dependency *may* have changed — `updateIfNecessary` will verify on
+read). Recompute is lazy. The queued effects flush once, at the outermost trigger
+(or, inside a batch, when the batch owner flushes) — never mid-propagation, so an
+effect never runs against a half-marked graph.
 */
 export function trigger(node: ReactiveNode): void {
-    invalidate(node)
+    let link = node.subsHead
+    while (link !== undefined) {
+        const next = link.nextSub
+        mark(link.sub, NODE_STATE.DIRTY)
+        link = next
+    }
     if (REACTIVE_CONTEXT.batchDepth === 0) {
         flushEffects()
     }

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

@@ -20,6 +20,9 @@ export type ReactiveNode = {
     depsTail: ReactiveLink | undefined
     subsHead: ReactiveLink | undefined
     subsTail: ReactiveLink | undefined
-    dirty: boolean
+    /* The node's settle-state for push-pull propagation: CLEAN / CHECK / DIRTY (see
+       NODE_STATE). A signal is always CLEAN (no compute); a computed is born DIRTY and
+       cycles CLEAN→CHECK/DIRTY→CLEAN as deps change and reads settle it. */
+    status: number
     isEffect: boolean
 }

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

@@ -0,0 +1,40 @@
+import { NODE_STATE } from './NODE_STATE.ts'
+import { runNode } from './runNode.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Settles a node so its value is current before it is read (or, for an effect, before
+it runs at flush). CLEAN: nothing to do. CHECK: a transitive dependency *might* have
+changed — refresh each direct dependency in turn; refreshing one that truly changed
+marks this node DIRTY (`runNode` does the marking), so stop the moment that happens.
+DIRTY (set directly by a write, or by the check walk): recompute.
+
+A CHECK node whose dependencies all recompute to equal values ends CLEAN without
+recomputing — the value memoisation that stops an unchanged computed from waking its
+readers. Refreshing deps top-down *before* a recompute reads them is what keeps the
+pull glitch-free: a reader never observes a stale intermediate, because by the time
+it recomputes, every dependency it reads has already settled this pass.
+*/
+export function updateIfNecessary(node: ReactiveNode): void {
+    if (node.status === NODE_STATE.CLEAN) {
+        return
+    }
+    if (node.status === NODE_STATE.CHECK) {
+        let link = node.depsHead
+        while (link !== undefined) {
+            updateIfNecessary(link.dep)
+            /* A dep recomputed to a changed value and marked us DIRTY — no need to
+               check the rest, we already know we must recompute. */
+            if (node.status === NODE_STATE.DIRTY) {
+                break
+            }
+            link = link.nextDep
+        }
+    }
+    if (node.status === NODE_STATE.DIRTY) {
+        runNode(node)
+    } else {
+        /* CHECK with no changed dependency — the cached value still holds. */
+        node.status = NODE_STATE.CLEAN
+    }
+}