@abide/abide 0.39.0 → 0.40.1

package/src/lib/ui/navigate.ts

@@ -1,6 +1,13 @@
 import { historyEntries } from './runtime/historyEntries.ts'
 import { runtimePath } from './runtime/runtimePath.ts'
 
+/* Options for `navigate`. `replace` swaps the current history entry instead of pushing.
+   `keepScroll` carries the live scroll offset onto the destination so it isn't reset. */
+export type NavigateOptions = {
+    replace?: boolean
+    keepScroll?: boolean
+}
+
 /* Navigates to `path`: writes a history entry (when available) and updates the
    reactive route, which re-mounts the matching page via `router`. `replace` swaps
    the current entry instead of pushing — used when honouring a server redirect, so
@@ -9,16 +16,34 @@ import { runtimePath } from './runtime/runtimePath.ts'
    teardown the rebuild does. A push leaves the current entry behind — its scroll is
    bucketed so back restores it — and mints a fresh id. A replace destroys the current
    entry and lands fresh content (a redirect), so its saved scroll no longer applies:
-   the bucket is discarded and the id kept, so the new page restores to top/anchor. */
+   the bucket is discarded and the id kept, so the new page restores to top/anchor.
+   `keepScroll` opts the destination out of that reset — for an in-page URL swap (e.g.
+   selecting another episode on the same detail page) where a top jump is jarring: the
+   live offset is bucketed under the destination entry id, so the post-rebuild `restore`
+   reapplies it instead of scrolling to top. */
 // @documentation navigate
-export function navigate(path: string, replace = false): void {
+export function navigate(
+    path: string,
+    { replace = false, keepScroll = false }: NavigateOptions = {},
+): void {
     if (typeof history !== 'undefined') {
         if (replace) {
-            historyEntries.discard()
+            /* keepScroll buckets the live offset under the (unchanged) entry id so
+               restore reapplies it; otherwise the superseded content drops its bucket. */
+            if (keepScroll) {
+                historyEntries.save()
+            } else {
+                historyEntries.discard()
+            }
             history.replaceState({ abideEntry: historyEntries.current }, '', path)
         } else {
             historyEntries.save()
             history.pushState({ abideEntry: historyEntries.next() }, '', path)
+            /* Re-bucket the same offset under the freshly minted id so the pushed entry
+               restores to it rather than to top. */
+            if (keepScroll) {
+                historyEntries.save()
+            }
         }
     }
     runtimePath.value = path

package/src/lib/ui/renderToStream.ts

@@ -1,6 +1,7 @@
 import { resumeSeedScript } from './resumeSeedScript.ts'
 import type { ResumeEntry } from './runtime/RESUME.ts'
 import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
+import { tryEncodeResume } from './tryEncodeResume.ts'
 
 /*
 Out-of-order SSR streaming. Yields the shell first (so the browser paints
@@ -69,10 +70,15 @@ export async function* renderToStream(
         const resolved = await Promise.race(inflight.values())
         inflight.delete(resolved.id)
         enqueueNew()
-        const encoded = encodeResume(resolved.resume)
+        /* An unserializable value (e.g. a cyclic media tree) streams its rendered HTML
+           with NO seed script: both swap consumers (SSR_SWAP_SCRIPT, applyResolved) skip
+           registration when the leading child isn't a parseable script, so hydration
+           re-runs this one branch's promise — degrading to a refetch instead of aborting
+           the whole stream. */
+        const encoded = encodeStreamResume(resolved.resume, resolved.id)
         yield resumeSeedScript(resumeDelta()) +
             `<abide-resolve data-id="${resolved.id}">` +
-            `<script type="application/json">${encoded}</script>` +
+            (encoded === undefined ? '' : `<script type="application/json">${encoded}</script>`) +
             `${resolved.html}</abide-resolve>`
     }
 }
@@ -105,11 +111,13 @@ function settle(block: SsrAwait): Promise<Settled> {
     )
 }
 
-/* JSON for a `<script type="application/json">` data block: script content is raw
-   text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
-   literal `</script>` from closing the block early — quotes stay raw. Far cheaper
-   than attribute escaping (no full-string `"`/`&` passes) and JSON.parse decodes it
-   back. `applyResolved`/the inline swap script read it via `.textContent`. */
-function encodeResume(resume: ResumeEntry): string {
-    return JSON.stringify(resume).replace(/</g, '\\u003c')
+/* ref-json for a `<script type="application/json">` data block: script content is
+   raw text, so only `<` needs neutralizing (emitted as a unicode escape) to keep a
+   literal `</script>` from closing the block early — quotes stay raw, and the escape
+   survives `decodeRefJson`'s inner JSON.parse since `<` only ever appears inside JSON
+   strings. `tryEncodeResume` handles the serialize-or-refetch policy (undefined → no
+   script → the swap consumers skip registration → hydration re-runs that one promise).
+   `applyResolved`/the inline swap script store it via `.textContent`; `awaitBlock` decodes it. */
+function encodeStreamResume(resume: ResumeEntry, id: number): string | undefined {
+    return tryEncodeResume(resume, id)?.replace(/</g, '\\u003c')
 }

package/src/lib/ui/resumeSeedScript.ts

@@ -1,17 +1,27 @@
 import { safeJsonForScript } from '../shared/safeJsonForScript.ts'
 import type { ResumeEntry } from './runtime/RESUME.ts'
+import { tryEncodeResume } from './tryEncodeResume.ts'
 
 /* A self-contained `<script>` seeding the await-resume manifest with the blocking
    values rendered inline on the server, so client hydration adopts each resolved
    branch instead of re-running its promise. Empty when nothing blocking resolved.
-   The payload runs as JS (`Object.assign`), so it's encoded via `safeJsonForScript`
-   — escaping `<`, `-->`, and U+2028/U+2029 so a serialized body value can't close
-   the script early or parse as a line terminator. Shared by the buffered
-   (`createUiPageRenderer`) and streaming (`renderToStream`) paths. */
+   Each entry is ref-json-encoded to a string (decoded at read in `awaitBlock`); the
+   id→string map runs as JS (`Object.assign`), so it's wrapped in `safeJsonForScript`
+   — escaping `<`, `-->`, and U+2028/U+2029 so an encoded value can't close the script
+   early or parse as a line terminator. Shared by the buffered (`createUiPageRenderer`)
+   and streaming (`renderToStream`) paths. */
 // @documentation plumbing
 export function resumeSeedScript(resume: Record<number, ResumeEntry>): string {
-    if (Object.keys(resume).length === 0) {
+    /* ref-json (not JSON) so a value carrying cycles or shared back-references — a
+       media tree with parent↔child links — seeds instead of being dropped. `tryEncodeResume`
+       drops just an unserializable entry (the client re-runs that one branch's promise),
+       keeping every other branch seeded rather than blanking the whole page. */
+    const encoded = Object.entries(resume).flatMap(([id, entry]) => {
+        const text = tryEncodeResume(entry, id)
+        return text === undefined ? [] : [[id, text] as const]
+    })
+    if (encoded.length === 0) {
         return ''
     }
-    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${safeJsonForScript(resume)})</script>`
+    return `<script>Object.assign(window.__abideResume=window.__abideResume||{},${safeJsonForScript(Object.fromEntries(encoded))})</script>`
 }

package/src/lib/ui/router.ts

@@ -36,6 +36,47 @@ const resolveUrl = (path: string): URL =>
         ? new URL(`http://localhost${path}`)
         : new URL(path, location.origin)
 
+/* A full browser load is the recovery for an import/probe failure — offline, a hashed
+   chunk name rotated by a deploy, a transient 5xx. But a DETERMINISTIC failure (a chunk
+   that throws every load) would reload forever. Bound it per destination: after
+   MAX_RECOVERY_RELOADS consecutive reloads of the same URL, stop and leave the error
+   visible instead of thrashing. `sessionStorage` so the count survives the reload it
+   triggers (and clears with the tab); absent it (SSR / privacy mode), fall back to a
+   single reload. `clearRecoveryReloads` resets the count once that URL mounts cleanly,
+   so a later genuine blip gets its reload again. */
+const MAX_RECOVERY_RELOADS = 2
+const reloadCountKey = (url: string): string => `abide:reload:${url}`
+
+function boundedReload(url: string): void {
+    if (typeof location === 'undefined') {
+        return
+    }
+    let count = 0
+    try {
+        count = Number(sessionStorage.getItem(reloadCountKey(url)) ?? '0')
+        sessionStorage.setItem(reloadCountKey(url), String(count + 1))
+    } catch {
+        /* sessionStorage blocked — proceed with an unbounded single reload. */
+    }
+    if (count >= MAX_RECOVERY_RELOADS) {
+        console.error(
+            `[abide] gave up reloading ${url} after ${count} attempts — the page keeps failing to load. See the error above.`,
+        )
+        return
+    }
+    location.href = url
+}
+
+/* A URL mounted cleanly — forget its reload history so a future transient failure there
+   is allowed to recover by reloading again. */
+function clearRecoveryReloads(url: string): void {
+    try {
+        sessionStorage.removeItem(reloadCountKey(url))
+    } catch {
+        /* nothing persisted — nothing to clear. */
+    }
+}
+
 /*
 A minimal client router on the History API. `router` matches the current path
 against the route patterns (literal / `[name]` / `[...rest]`, via matchRoute),
@@ -73,6 +114,11 @@ export function router(
     /* The mounted layout chain (outermost first) + the page disposer. */
     const mountedLayouts: MountedLayout[] = []
     let disposePage: (() => void) | undefined
+    /* The route key of the currently mounted leaf page — its identity for the
+       same-page in-place diff: when a navigation resolves to this same key with an
+       unchanged layout chain, only params/url differ, so the page stays mounted and
+       updates through the reactive `page` proxy (no teardown). */
+    let mountedPageKey: string | undefined
     /* The root outlet boundary in `host` (`#app`) the outermost layer fills — established
        once on the first mount (claimed from the SSR DOM when hydrating, created otherwise)
        and reused across navigations, since `#app` itself never re-mounts. */
@@ -167,6 +213,7 @@ export function router(
                 boundary = slot
             }
             if (pageView === undefined) {
+                mountedPageKey = undefined
                 return
             }
             disposePage = fillBoundary(
@@ -177,6 +224,7 @@ export function router(
                 /* The page's route key names its scope in the inspector (see above). */
                 pageKey,
             ).dispose
+            mountedPageKey = pageKey
         }
         if (hydrating) {
             const previous = RENDER.hydration
@@ -351,15 +399,13 @@ export function router(
                     /* 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)
+                        navigate(decision.path, { replace: 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
-                        }
+                        boundedReload(decision.url)
                         return
                     }
                     const layoutViews = resolvedLayouts.filter(
@@ -377,6 +423,36 @@ export function router(
                     }
                     const hydrating = first && pageView?.hydratable === true
                     first = false
+                    /* Same page, same layout chain — only params/url differ (e.g. stepping
+                       between episodes on one detail page). The whole structure survives, so
+                       publish the new snapshot on the reactive `page` proxy and let the mounted
+                       page + layouts re-derive in place — no teardown, no rebuild, so local
+                       state, scroll, and DOM are kept (the persistence layouts already get,
+                       now extended to the leaf). A reader keyed on an *unchanged* param (a page
+                       whose data is `cache(...)({ id: page.params.id })`) doesn't re-fire at
+                       all — value-memoised computeds stop the equal id from waking it — so the
+                       page's blocking await never re-suspends. No view transition: nothing
+                       structurally swaps. */
+                    const targetUrl = resolveUrl(path)
+                    const samePageInPlace =
+                        pageView !== undefined &&
+                        key === mountedPageKey &&
+                        divergence === mountedLayouts.length &&
+                        divergence === chainKeys.length &&
+                        /* A differing query is page data — it still rebuilds, matching the
+                           hash-only fast path's guard. Only path-param changes within the same
+                           route key (e.g. the episode segment) take the in-place route. */
+                        clientPage.value.url.search === targetUrl.search
+                    if (samePageInPlace) {
+                        clientPage.value = {
+                            route: chainRoute,
+                            params,
+                            url: targetUrl,
+                            navigating: false,
+                        }
+                        historyEntries.restore(targetUrl.hash)
+                        return
+                    }
                     /* The DOM mutation a navigation makes: tear the divergent chain down
                    (clearing its content from its boundary) and rebuild into the same
                    boundary (hydration adopts in place). */
@@ -413,6 +489,23 @@ export function router(
                        (a fresh load with no persisted offset falls through to hash/top). */
                         historyEntries.restore(url.hash)
                     }
+                    /* Build / hydrate is the deterministic surface — a codegen defect or a
+                       throw in user render code fails the SAME way every load, so reloading
+                       would loop forever. Catch it HERE (not in the outer `.catch`, which a
+                       hydrating swap's synchronous throw would otherwise reach): surface the
+                       error and stop, never reload. A clean mount clears any prior recovery
+                       reloads for this URL so a later transient failure can recover again. */
+                    const commit = (): void => {
+                        try {
+                            swap()
+                            clearRecoveryReloads(resolveUrl(path).href)
+                        } catch (error) {
+                            console.error(
+                                `[abide] page at ${path} threw while mounting — not reloading (a reload would re-run the same failure):`,
+                                error,
+                            )
+                        }
+                    }
                     /* Wrap the swap in a View Transition where the browser supports it, so
                    the page change cross-fades (and shared `view-transition-name` elements
                    morph) — the synchronous swap is exactly the mutation the API snapshots
@@ -423,23 +516,23 @@ export function router(
                         typeof document !== 'undefined' &&
                         'startViewTransition' in document
                     ) {
-                        document.startViewTransition(swap)
+                        document.startViewTransition(commit)
                     } else {
-                        swap()
+                        commit()
                     }
                 })
-                .catch(() => {
-                    /* A page/layout chunk import (or the probe) rejected — offline, a hashed
-                   chunk filename rotated by a deploy, or a transient asset 5xx. Without
-                   this the navigating:true latched above never clears (a bound spinner
-                   spins forever) and the rejection surfaces as an unhandledrejection.
-                   Fall back to a full browser load so the server serves the target. */
+                .catch((error) => {
+                    /* A page/layout chunk IMPORT (or the probe) rejected — offline, a hashed
+                   chunk filename rotated by a deploy, or a transient asset 5xx: recoverable,
+                   so a full browser load is the right fallback (and clears the latched
+                   navigating:true, so a bound spinner doesn't spin forever). Bounded, so a
+                   chunk that fails to import every time can't reload-loop. Deterministic
+                   render throws don't land here — `commit` swallows them above. */
                     if (token !== sequence || disposed) {
                         return
                     }
-                    if (typeof location !== 'undefined') {
-                        location.href = resolveUrl(path).href
-                    }
+                    console.error(`[abide] failed to load page at ${path} — reloading:`, error)
+                    boundedReload(resolveUrl(path).href)
                 })
         })
     })

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

@@ -0,0 +1,22 @@
+/*
+The three settle-states a reactive node moves through, for value-memoised
+(push-pull) propagation. CLEAN: the value is current. CHECK: a *transitive*
+dependency may have changed — the value can't be trusted until the direct deps are
+refreshed. DIRTY: a *direct* dependency changed — recompute.
+
+A signal write marks its direct subscribers DIRTY and the rest of their cone
+CHECK; a read then settles a node by refreshing only the deps that the check walk
+finds actually changed. A computed that recomputes to an `Object.is`-equal value
+leaves its subscribers untouched, so an unchanged value never wakes downstream —
+the memoisation a single bare boolean `dirty` flag (no CHECK tier, no value
+compare) couldn't express.
+*/
+/* Typed as `number` (not `as const` literals) so a `node.status === CHECK` guard
+   doesn't narrow the field to the literal `1` — the recursive `updateIfNecessary`
+   call mutates `status` out of band, which TS can't see, and a literal narrowing
+   would make the following `=== DIRTY` check a "no overlap" error. */
+export const NODE_STATE: {
+    readonly CLEAN: number
+    readonly CHECK: number
+    readonly DIRTY: number
+} = { CLEAN: 0, CHECK: 1, DIRTY: 2 }

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

@@ -1,16 +1,23 @@
 /* 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
+   `await` block, keyed by its boundary id. The SSR stream serializes each entry
    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. */
+   Each value is the ref-json-encoded ResumeEntry STRING, not the decoded object:
+   the entry is encoded with the ref-json codec (so a resolved value carrying cycles
+   or shared back-references survives, where JSON would drop it) and decoded lazily
+   at the read site in `awaitBlock`. Storing the raw string keeps the inline
+   stream-swap script — vanilla, running before the bundle and the codec load — able
+   to register an entry without the decoder.
+
+   Backed by `globalThis.__abideResume` so the inline stream-swap script 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> }
+const globalScope = globalThis as { __abideResume?: Record<number, string> }
 globalScope.__abideResume ??= {}
 
 // @documentation plumbing
-export const RESUME: Record<number, ResumeEntry> = globalScope.__abideResume
+export const RESUME: Record<number, string> = globalScope.__abideResume

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)