@abide/abide 0.34.2 → 0.36.0

package/src/lib/ui/router.ts

@@ -209,6 +209,17 @@ export function router(
             const chainKeys = layoutChainForRoute(chainRoute, layoutKeys)
             sequence += 1
             const token = sequence
+            /* Flag the outgoing page as navigating for the resolve window — chunk
+               import + probe + the view transition all run before the swap commits.
+               Published on the CURRENT snapshot (route/params unchanged) so a spinner
+               bound to `page.navigating` shows over the page being left; `swap`
+               republishes with the destination and `navigating: false` on commit.
+               Skipped on first paint — there is no page to leave. An instant SPA hop
+               (chunk cached, no probe) flips it back within the same microtask, so the
+               browser never paints the intermediate state — no flash. */
+            if (!first && !clientPage.value.navigating) {
+                clientPage.value = { ...clientPage.value, navigating: true }
+            }
             /* First paint adopts a document the server already ran handle() on;
                only later navigations re-run it through the probe. */
             const verdict: Promise<NavVerdict> =
@@ -238,16 +249,6 @@ export function router(
                     }
                     return
                 }
-                /* Publish the active page so the `page` proxy resolves route/params/url. */
-                clientPage.value = {
-                    route: chainRoute,
-                    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,
                 )
@@ -267,7 +268,22 @@ export function router(
                 /* The DOM mutation a navigation makes: tear the divergent chain down,
                    clear its DOM (a fresh mount; hydration adopts in place), rebuild. */
                 const swap = (): void => {
+                    /* Tear the outgoing page + divergent layouts down BEFORE publishing the
+                       new snapshot. Publishing first would re-run the doomed leaf page's
+                       computeds against the new route's params (a missing `[id]` reads back
+                       `undefined`, e.g. `Number(page.params.id)` → NaN → a bogus request)
+                       while it's still mounted. Disposing first kills that scope; surviving
+                       prefix layouts then update in place on publish. */
                     const base = disposeFrom(divergence)
+                    clientPage.value = {
+                        route: chainRoute,
+                        params,
+                        url:
+                            typeof location === 'undefined'
+                                ? new URL(`http://localhost${path}`)
+                                : new URL(location.href),
+                        navigating: false,
+                    }
                     if (!hydrating) {
                         base.textContent = ''
                     }

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

@@ -0,0 +1,8 @@
+/*
+The abort reason used to cancel an RPC bound to a reactive computation when that
+computation re-runs (its result is superseded) or its scope disposes. A unique
+symbol so remoteProxy can distinguish OUR cancellation — which it swallows into a
+never-settling promise, never a rejection — from a genuine network fault or a
+caller's own abort.
+*/
+export const REQUEST_SUPERSEDED: unique symbol = Symbol('abide.request.superseded')

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

@@ -0,0 +1,22 @@
+import { REQUEST_SUPERSEDED } from './REQUEST_SUPERSEDED.ts'
+import { reactiveAbortState } from './reactiveAbortState.ts'
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Aborts the RPC(s) a reactive computation left in flight — called when the node
+re-runs (the prior run's result is superseded) and when its scope disposes (the
+result would land in a torn-down tree). The `armed` gate keeps this a single
+boolean check until some reactive RPC has actually bound a controller. The abort
+reason is REQUEST_SUPERSEDED so remoteProxy can tell our cancellation from a real
+fault and swallow it rather than surface a rejection.
+*/
+export function abortNode(node: ReactiveNode): void {
+    if (!reactiveAbortState.armed) {
+        return
+    }
+    const controller = reactiveAbortState.controllers.get(node)
+    if (controller !== undefined) {
+        reactiveAbortState.controllers.delete(node)
+        controller.abort(REQUEST_SUPERSEDED)
+    }
+}

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

@@ -0,0 +1,26 @@
+import { cacheManagedSlot } from '../../shared/cacheManagedSlot.ts'
+import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
+import { reactiveAbortState } from './reactiveAbortState.ts'
+
+/*
+The AbortSignal bound to the currently-running reactive computation (effect or
+computed), its controller created lazily on first use. An RPC invoked inside a
+reactive read passes this to fetch, so the request aborts when that computation
+re-runs (superseded) or its scope disposes (navigated away). Returns undefined —
+leaving the fetch unbound by scope — in two cases: there is no reactive owner to
+bind to (an event-handler call), or the call is cache-managed (the cache owns the
+shared flight's lifetime; binding it to one reader would abort it for the others).
+*/
+export function currentAbortSignal(): AbortSignal | undefined {
+    const node = REACTIVE_CONTEXT.observer
+    if (node === undefined || cacheManagedSlot.active) {
+        return undefined
+    }
+    let controller = reactiveAbortState.controllers.get(node)
+    if (controller === undefined) {
+        controller = new AbortController()
+        reactiveAbortState.controllers.set(node, controller)
+        reactiveAbortState.armed = true
+    }
+    return controller.signal
+}

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

@@ -4,10 +4,16 @@ Escapes one object key into a JSON Pointer reference token (RFC 6901): `~`→`~0
 survives a `/`-joined path instead of being mis-split into segments. `~` is
 escaped first so a `/`→`~1` substitution isn't re-escaped. The common key (a
 plain identifier) contains neither char, so the scan returns it untouched.
+
+Coerces first: lowerDocAccess wraps every dynamic path segment in this call, and a
+segment is often a number (an array index `lines[i]`) — String() mirrors the `+`
+join that built the path before, leaving numerics as their decimal text.
 */
-export function escapeKey(key: string): string {
-    if (!key.includes('~') && !key.includes('/')) {
-        return key
+// @documentation plumbing
+export function escapeKey(key: string | number): string {
+    const segment = String(key)
+    if (!segment.includes('~') && !segment.includes('/')) {
+        return segment
     }
-    return key.replace(/~/g, '~0').replace(/\//g, '~1')
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1')
 }

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

@@ -0,0 +1,15 @@
+import type { ReactiveNode } from './types/ReactiveNode.ts'
+
+/*
+Shared state for scope-bound RPC abort. `controllers` maps a reactive computation
+(effect/computed) to the AbortController of the RPC(s) it fired, kept OFF
+ReactiveNode — like an effect's cleanup closure — so signals and the read/write hot
+path pay nothing. `armed` flips true the first time an RPC binds a controller and
+gates the runNode/unlinkDeps lookups, so an app that never fires a reactive RPC pays
+only one boolean check per compute run. Mirrors REACTIVE_CONTEXT's single-object
+pattern (shared mutable singletons on one object, reached without a barrel).
+*/
+export const reactiveAbortState: {
+    controllers: WeakMap<ReactiveNode, AbortController>
+    armed: boolean
+} = { controllers: new WeakMap(), armed: false }

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

@@ -1,5 +1,7 @@
+import { abortNode } from './abortNode.ts'
 import { endTracking } from './endTracking.ts'
 import { REACTIVE_CONTEXT } from './REACTIVE_CONTEXT.ts'
+import { reactiveAbortState } from './reactiveAbortState.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
 /*
@@ -12,6 +14,13 @@ taken this run leaves its edges past the cursor, so they are dropped here. Retur
 the fresh value (used by lazy computed reads).
 */
 export function runNode(node: ReactiveNode): unknown {
+    /* This run supersedes the prior one — abort any RPC it left in flight before
+       re-tracking, so a stale request never lands after a newer one started. The
+       `armed` gate inlines here so an app that never fires a reactive RPC pays one
+       property read on this hot path, not a call. */
+    if (reactiveAbortState.armed) {
+        abortNode(node)
+    }
     /* Rewind: track() walks forward from here, reusing matching edges in order. */
     node.depsTail = undefined
     const previous = REACTIVE_CONTEXT.observer

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

@@ -0,0 +1,40 @@
+import { OWNER } from './OWNER.ts'
+
+/*
+A set of child-scope disposers that composes with the enclosing owner. `scope()`
+returns a disposer but does NOT self-register, so a control-flow block's live
+children — a branch, a list row — would outlive an owner teardown (a navigation):
+the leak every block otherwise hand-wires against, several incorrectly. A block
+creates one group, then `track`s each child it builds:
+
+  `track(dispose)` adopts a child's disposer and returns a wrapper that disposes it
+  AND drops it from the group — call the wrapper on a flip/prune (it's idempotent, so
+  a second call is a no-op). Whatever stays tracked is disposed once, when the
+  enclosing owner tears down. A swapped-out child is already dropped, so owner
+  teardown only ever runs the children still live.
+
+This is the single mechanism `when`/`switch`/`await`/`try`/`each`/`eachAsync` share
+in place of each re-deriving owner composition (where the divergence bred the leaks).
+*/
+export function scopeGroup(): { track: (dispose: () => void) => () => void } {
+    const live = new Set<() => void>()
+    const track = (dispose: () => void): (() => void) => {
+        live.add(dispose)
+        return () => {
+            if (live.delete(dispose)) {
+                dispose()
+            }
+        }
+    }
+    /* One teardown for the whole group; disposes whatever children are still live when
+       the owner goes. Outside any scope (a standalone block) the group owns nothing. */
+    if (OWNER.current !== undefined) {
+        OWNER.current.push(() => {
+            for (const dispose of live) {
+                dispose()
+            }
+            live.clear()
+        })
+    }
+    return { track }
+}

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

@@ -1,4 +1,6 @@
+import { abortNode } from './abortNode.ts'
 import { detachLink } from './detachLink.ts'
+import { reactiveAbortState } from './reactiveAbortState.ts'
 import type { ReactiveNode } from './types/ReactiveNode.ts'
 
 /*
@@ -9,6 +11,12 @@ dead observer, then empties the node's own list. The `Set`-era equivalent was
 `for (dep of node.deps) dep.observers.delete(node); node.deps.clear()`.
 */
 export function unlinkDeps(node: ReactiveNode): void {
+    /* Disposing tears this computation out of the graph — abort any RPC it left in
+       flight, its result would land in a scope that no longer exists. Gated inline so
+       the common disarmed dispose pays one property read, not a call. */
+    if (reactiveAbortState.armed) {
+        abortNode(node)
+    }
     let link = node.depsHead
     while (link !== undefined) {
         const next = link.nextDep

package/src/lib/ui/seedStreamedResolution.ts

@@ -0,0 +1,22 @@
+import { activeCacheStore } from '../shared/activeCacheStore.ts'
+import { cacheEntryFromSnapshot } from '../shared/cacheEntryFromSnapshot.ts'
+import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
+
+/*
+Seeds one streamed cache resolution into the active store — the single sink for the
+streamed (pending {#await}) cache partition. A full CacheSnapshotEntry warms the entry
+so a `cache()` read resolves synchronously (no wire round-trip) and `<template await>`
+adopts without a refetch; a `{ key, miss }` marker — a body the server couldn't snapshot
+(binary / rejected / evicted) — is a no-op, so that read falls back to a live fetch.
+
+Shared by startClient's boot drain, the live `window.__abideResolve`, and applyResolved,
+so no resolved-frame consumer can swap DOM while silently dropping the cache channel —
+the asymmetry that made streamed reads cold-miss to the network.
+*/
+// @documentation plumbing
+export function seedStreamedResolution(resolution: StreamedResolution): void {
+    if ('miss' in resolution) {
+        return
+    }
+    activeCacheStore().entries.set(resolution.key, cacheEntryFromSnapshot(resolution))
+}

package/src/lib/ui/startClient.ts

@@ -1,15 +1,16 @@
-import { cacheEntryFromSnapshot } from '../shared/cacheEntryFromSnapshot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { setBaseResolver } from '../shared/setBaseResolver.ts'
 import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
 import { setGlobalCacheStoreResolver } from '../shared/setGlobalCacheStoreResolver.ts'
 import { setPageResolver } from '../shared/setPageResolver.ts'
 import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
+import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
 import { installHotBridge } from './installHotBridge.ts'
 import { probeNavigation } from './probeNavigation.ts'
 import { router } from './router.ts'
 import { clientPage } from './runtime/clientPage.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
+import { seedStreamedResolution } from './seedStreamedResolution.ts'
 
 /* The server's __SSR__ payload this entry consumes. */
 type SsrPayload = { cache?: CacheSnapshotEntry[]; base?: string }
@@ -50,9 +51,22 @@ export function startClient(
     setCacheStoreResolver(() => store)
     /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
     setGlobalCacheStoreResolver(() => store)
-    for (const entry of ssr.cache ?? []) {
-        store.entries.set(entry.key, cacheEntryFromSnapshot(entry))
+    /* Seed both SSR cache partitions through the one streamed-resolution sink: `ssr.cache`
+       (inline — reads settled at render-return, in __SSR__) and `__abideResumeCache` (pending
+       {#await} reads whose `__abideResolve(...)` chunks the stream pushed during parse, before
+       this deferred bundle ran). A warm entry lets a `cache()` read resolve synchronously so
+       `<template await>` adopts without a refetch; a miss marker re-fetches live. */
+    const streamed =
+        (globalThis as { __abideResumeCache?: StreamedResolution[] }).__abideResumeCache ?? []
+    for (const resolution of [...(ssr.cache ?? []), ...streamed]) {
+        seedStreamedResolution(resolution)
     }
+    /* Keep the cache channel live past boot: replace the head's buffering collector with
+       the store-connected sink so a post-load resolution — streaming SPA navigation or a
+       socket-delivered SSR frame, both routed through applyResolved — seeds the store
+       directly instead of pushing to a buffer nothing drains again. */
+    ;(globalThis as { __abideResolve?: (resolution: StreamedResolution) => void }).__abideResolve =
+        seedStreamedResolution
 
     return router(target, routes, layoutRoutes, probeNavigation)
 }

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

@@ -1,16 +0,0 @@
-import type { CacheEntry } from './CacheEntry.ts'
-import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
-
-/*
-The SSR partition of a request's cache, read after `render()` returns.
-`inline` are entries settled by then (consumed via `await`, so render blocked
-on them) — they ship in the first chunk's `__SSR__` blob. `pending` are
-GET/DELETE entries still in flight (consumed via `{#await}`, which render emits
-as a pending branch without blocking) — the streamer awaits each and pushes a
-`__abideResolve` chunk as it lands. Non-GET/DELETE pending entries are dropped:
-they can't be snapshotted, so the client re-fetches them live on cache miss.
-*/
-export type CacheSnapshot = {
-    inline: CacheSnapshotEntry[]
-    pending: CacheEntry[]
-}