@abide/abide 0.46.0 → 0.47.0

package/src/lib/shared/cacheEntryFromSnapshot.ts

@@ -1,6 +1,7 @@
-import { bodyValueForKind, DEFER } from './bodyValueForKind.ts'
+import { bodyValueForKind } from './bodyValueForKind.ts'
 import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
+import { DEFER } from './DEFER.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 import type { CacheSnapshotEntry } from './types/CacheSnapshotEntry.ts'
 
@@ -19,38 +20,18 @@ export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
         statusText: entry.statusText,
         headers,
     })
-    /* Deferred seed: decode nothing now — hand back a memoized materializer the first read
-       invokes, so hydration pays no payload decode. Eager seed: decode up front as before. */
-    const warm = entry.lazy
-        ? memoizeWarm(() => warmValueFromSnapshot(entry.status, headers, entry.body))
-        : undefined
     return {
         key: entry.key,
         promise: Promise.resolve(response),
         request: new Request(entry.url, { method: entry.method }),
         ttl: undefined,
         expiresAt: undefined,
-        value: entry.lazy ? undefined : warmValueFromSnapshot(entry.status, headers, entry.body),
-        warm,
+        value: warmValueFromSnapshot(entry.status, headers, entry.body),
         settled: true,
         hydrated: true,
     }
 }
 
-/* Wraps a warm decode so it runs at most once — the materialized value (including a
-   legitimate undefined for a non-warmable status) is cached after the first call. */
-function memoizeWarm(decode: () => unknown): () => unknown {
-    let materialized = false
-    let value: unknown
-    return () => {
-        if (!materialized) {
-            value = decode()
-            materialized = true
-        }
-        return value
-    }
-}
-
 /*
 Synchronously decodes a snapshot body so the warm entry reads without a
 microtask hop on first render. The json/text branches go through the shared

package/src/lib/shared/cacheStoreSlot.ts

@@ -1,8 +1,12 @@
-import { cacheStoreResolver } from './cacheStoreResolver.ts'
+import { createCacheStore } from './createCacheStore.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
 
 /*
-Internal slot the runtime entries register their resolver into (see
-cacheStoreResolver). Exposed so test helpers snapshot/poke `.resolver` and
-`.fallback` directly.
+The active-CacheStore slot. The server entry installs an ALS-backed resolver
+(request-scoped); the client entry a module-singleton one. With no resolver
+registered, a single fallback store is created lazily so isolated tests work
+without booting the runtime; test helpers snapshot/poke `.resolver` and
+`.fallback` directly. activeCacheStore is the public read.
 */
-export const cacheStoreSlot = cacheStoreResolver.slot
+export const cacheStoreSlot = createResolverSlot<CacheStore>(createCacheStore)

package/src/lib/{server/runtime → shared}/createReachable.ts

@@ -1,7 +1,7 @@
-import { createLivenessWatch } from '../../shared/createLivenessWatch.ts'
+import { createLivenessWatch } from './createLivenessWatch.ts'
 
 /*
-The reachability registry behind `abide/server/reachable`. A probe transport
+The reachability registry behind `abide/shared/reachable`. A probe transport
 and the timings are injected so the public name wires them from env + a real
 HEAD while tests drive scripted outcomes on tiny intervals.
 

package/src/lib/shared/createRemoteFunction.ts

@@ -1,9 +1,12 @@
-import { decodeResponse } from './decodeResponse.ts'
+import { attachRpcSelectorMethods } from './attachRpcSelectorMethods.ts'
+import { cache } from './cache.ts'
 import { HttpError } from './HttpError.ts'
 import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import { recordRemoteMeta } from './recordRemoteMeta.ts'
+import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
 import { subscribableFromResponse } from './subscribableFromResponse.ts'
+import type { CacheOptions } from './types/CacheOptions.ts'
 import type { ClientFlags } from './types/ClientFlags.ts'
 import type { HttpMethod } from './types/HttpMethod.ts'
 import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
@@ -47,8 +50,21 @@ export function createRemoteFunction<Args, Return>(opts: {
         opts?: RpcOptions,
     ) => Promise<Response>
     parseArgsForFetch?: (request: Request) => Promise<Args | undefined>
+    /* A streaming rpc (handler returns jsonl()/sse()): the bare call returns the Subscribable
+       directly (the iterable IS the value) rather than decoding one Response body. Emitted by
+       the bundler's syntactic scan; false/undefined keeps the decode-a-Response path. */
+    streaming?: boolean
 }): RemoteFunction<Args, Return> {
-    const { method, url, clients, crossOrigin, buildRequest, invoke, parseArgsForFetch } = opts
+    const {
+        method,
+        url,
+        clients,
+        crossOrigin,
+        buildRequest,
+        invoke,
+        parseArgsForFetch,
+        streaming,
+    } = opts
 
     /*
     Dispatch is the one-stop entry for both the plain call (no prebuilt
@@ -90,19 +106,51 @@ export function createRemoteFunction<Args, Return>(opts: {
     Object.defineProperty(rawCall, REMOTE_FUNCTION, { value: true })
     const raw = rawCall as RawRemoteFunction<Args>
 
-    function callable(args: Args | FormData, opts?: RpcOptions): Promise<Return> {
-        return raw(args, opts).then(decodeResponse) as Promise<Return>
+    function callable(
+        args: Args | FormData,
+        opts?: RpcOptions,
+    ): Promise<Return> | Subscribable<Return> {
+        /* A streaming rpc (jsonl/sse) returns the Subscribable directly — the iterable IS the
+           value (for await / state(fn(args))). Deferred fetch, keyForRemoteCall-keyed so tail()
+           dedupes readers; no decode, so the error-capture path below doesn't apply. */
+        if (streaming) {
+            return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
+                raw(args as Args, opts),
+            )
+        }
+        /* The bare call IS the smart read: route through the cache store's smart-read
+           path so a replayable read is coalesced, retained (SWR unconditional), and
+           reactive, while a write is coalesce-only — the raw fetch moves to `.raw`.
+           `cache.read(callable, …)` brand-reads `callable.raw` for the undecoded variant
+           and decodes on the way out, so pass the callable (which carries `.raw`), not
+           `raw`. `opts` supplies cache options (ttl/tags/throttle/debounce); per-call
+           transport options live on `.raw` now. */
+        const key = keyForRemoteCall(method, url, args)
+        return cache
+            .read(callable as RemoteFunction<Args, Return>, args as Args, opts as CacheOptions)
+            .then(
+                /* Capture the rejection into the rpc error registry (design Part 4) keyed by call
+               identity, and clear it on success — the reactive `fn.error()` probe reads it. */
+                (value) => {
+                    rpcErrorRegistry.clear(key)
+                    return value as Return
+                },
+                (error: unknown) => {
+                    /* A parked durable write throws a `kind: 'queued'` sentinel — it's pending
+                   retry, not a failure. Don't record it, so fn.error() stays undefined for a
+                   merely-parked write (pending() already reflects it via the outbox). */
+                    if (!(error instanceof HttpError && error.kind === 'queued')) {
+                        rpcErrorRegistry.record(key, error)
+                    }
+                    throw error
+                },
+            )
     }
     callable.method = method
     callable.url = url
     callable.clients = clients
     callable.crossOrigin = crossOrigin
     callable.raw = raw
-    callable.stream = (args?: Args | FormData): Subscribable<Return> => {
-        return subscribableFromResponse(keyForRemoteCall(method, url, args), () =>
-            raw(args as Args),
-        )
-    }
     /* Uniform runtime guard for every rpc — the per-rpc data typing lives entirely in the
        RpcErrorGuard<Errors> signature RemoteFunction projects onto it (Errors flows from the
        rpc helper's declared type, not from here). */
@@ -132,5 +180,6 @@ export function createRemoteFunction<Args, Return>(opts: {
         : (request: Request): Promise<Response> => {
               return dispatch(undefined, undefined, request)
           }
+    attachRpcSelectorMethods(callable as RemoteFunction<Args, Return>)
     return callable as RemoteFunction<Args, Return>
 }

package/src/lib/shared/createResolverSlot.ts

@@ -1,37 +1,30 @@
 import type { ResolverSlot } from './types/ResolverSlot.ts'
 
 /*
-The slot/resolver/reader triple the runtime entries share for cache store,
-page, and mount-base state. A runtime entry registers a side-specific resolver
-via `set` (ALS-backed on the server, a module singleton on the client); `get`
-returns the resolved value, falling back to a single lazily-created fallback
-when no resolver is registered so isolated tests work without booting the
-runtime. `slot` stays exposed so test helpers can snapshot/poke `.resolver` and
-`.fallback` directly. Pass `createFallback` for a lazily-built, cached fallback
-(cache store, page); omit it for a slot whose fallback is a plain value set
-directly (mount base) — `get` then returns `T | undefined`.
+The resolver-slot seam the runtime entries share for cache store, page,
+request-scope, and mount-base state. A runtime entry registers a side-specific
+resolver by assigning `.resolver` (ALS-backed on the server, a module
+singleton on the client); `get()` returns the resolved value, falling back to
+a single lazily-created fallback when no resolver is registered so isolated
+tests work without booting the runtime. Pass `createFallback` for a
+lazily-built, cached fallback (cache store, page); omit it for a slot whose
+fallback is a plain value set directly (mount base) — `get()` then returns
+`T | undefined`.
 */
-export function createResolverSlot<T>(createFallback?: () => T): {
-    slot: ResolverSlot<T>
-    set: (fn: () => T | undefined) => void
-    get: () => T | undefined
-} {
-    const slot: ResolverSlot<T> = { resolver: undefined, fallback: undefined }
-
-    function set(fn: () => T | undefined): void {
-        slot.resolver = fn
-    }
-
-    function get(): T | undefined {
-        const fromResolver = slot.resolver?.()
-        if (fromResolver !== undefined) {
-            return fromResolver
-        }
-        if (createFallback && slot.fallback === undefined) {
-            slot.fallback = createFallback()
-        }
-        return slot.fallback
+export function createResolverSlot<T>(createFallback?: () => T): ResolverSlot<T> {
+    const slot: ResolverSlot<T> = {
+        resolver: undefined,
+        fallback: undefined,
+        get(): T | undefined {
+            const fromResolver = slot.resolver?.()
+            if (fromResolver !== undefined) {
+                return fromResolver
+            }
+            if (createFallback && slot.fallback === undefined) {
+                slot.fallback = createFallback()
+            }
+            return slot.fallback
+        },
     }
-
-    return { slot, set, get }
+    return slot
 }

package/src/lib/shared/createSocketSubRegistry.ts

@@ -1,6 +1,6 @@
-import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
-import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
 import type { SocketChannel } from './types/SocketChannel.ts'
+import type { SocketClientFrame } from './types/SocketClientFrame.ts'
+import type { SocketServerFrame } from './types/SocketServerFrame.ts'
 import type { SocketSubCallbacks } from './types/SocketSubCallbacks.ts'
 
 /*

package/src/lib/shared/decodeRefJson.ts

@@ -6,7 +6,8 @@ them. The shell must exist before its contents are filled so a back-reference to
 ancestor resolves to the already-allocated object — which is what reconnects a cycle.
 Inline primitives need no shell; they decode directly where they sit.
 */
-import { REF_JSON_TAGS } from './REF_JSON_TAGS'
+import { REF_JSON_TAGS } from './REF_JSON_TAGS.ts'
+import { setOwnProperty } from './setOwnProperty.ts'
 
 export function decodeRefJson(text: string): unknown {
     const parsed = JSON.parse(text)
@@ -68,7 +69,8 @@ function fillShell(slot: unknown, shell: unknown, shells: unknown[]): void {
         const target = shell as Record<string, unknown>
         const record = slot as Record<string, unknown>
         for (const key of Object.keys(record)) {
-            target[key] = resolveValue(record[key], shells)
+            // setOwnProperty: a wire `__proto__` key must not hijack the shell's prototype.
+            setOwnProperty(target, key, resolveValue(record[key], shells))
         }
         return
     }

package/src/lib/shared/decodeResponse.ts

@@ -1,6 +1,7 @@
-import { bodyValueForKind, DEFER } from './bodyValueForKind.ts'
+import { bodyValueForKind } from './bodyValueForKind.ts'
 import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
+import { DEFER } from './DEFER.ts'
 import { httpErrorFor } from './httpErrorFor.ts'
 
 /*
@@ -17,10 +18,11 @@ propagation), and the success path types as Promise<Return> cleanly.
 Streaming Content-Types (SSE / JSONL / NDJSON) throw a clear error
 rather than silently doing the wrong thing: response.text() would hang
 forever on a never-ending body and response.json() would fail mid-parse.
-The error points callers at the right tools — `tail(fn.stream(args))`
-for a shared reactive view, or `fn.stream(args)` directly for a fresh
-per-call AsyncIterable — both of which know how to consume the body
-frame-by-frame.
+A streaming rpc's bare call already returns a Subscribable (the type makes
+`await fn(args)` a compile error), so this is a backstop for the paths that
+still decode a raw Response — `cache()` and the one-shot stream reader. The
+error points callers at the right tools: `state(fn(args))` for a reactive
+view, or `for await (… of fn(args))` for direct iteration.
 
 Callers that need headers, streaming, or per-status branching should use
 the `.raw(args)` escape hatch on the remote function instead — that
@@ -37,7 +39,7 @@ export async function decodeResponse(response: Response): Promise<unknown> {
     const kind = contentBodyKind(contentType)
     if (kind === 'streaming') {
         throw new Error(
-            `[abide] response at ${response.url} is a stream (${contentType}) — use tail(fn.stream(args)) for a reactive view, or fn.stream(args) for per-call iteration, instead of awaiting the bare call or cache()`,
+            `[abide] response at ${response.url} is a stream (${contentType}) — a streaming rpc's bare call already returns a Subscribable: use state(fn(args)) for a reactive view or \`for await (… of fn(args))\` for iteration, not await/cache()`,
         )
     }
     /* json/text go through the shared mapping warmValueFromSnapshot also uses, so a warm

package/src/lib/shared/done.ts

@@ -0,0 +1,14 @@
+import { tailProbeSlot } from './tailProbeSlot.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Reactive terminal-state reader for a stream: true once the source has closed (its
+tail entry status === 'done'). Stream-only — a cache entry's "done" is just
+`!pending && !refreshing`, so there is no cache-selector form. The residual bit the
+`pending` / `refreshing` / `error` probes don't cover (see design Part 4). No prober
+registered (server render, or tail never imported) reads as not-done.
+*/
+// @documentation probes
+export function done(subscribable: Subscribable<unknown>): boolean {
+    return tailProbeSlot.probe?.(subscribable.name)?.done ?? false
+}

package/src/lib/shared/encodeRefJson.ts

@@ -11,7 +11,8 @@ symbols can't be serialised and encode as undefined, matching JSON.stringify. Ou
 shape is `[rootValue, slots]`. Decode with decodeRefJson. Not streaming — the whole
 graph is walked up front.
 */
-import { REF_JSON_TAGS } from './REF_JSON_TAGS'
+import { REF_JSON_TAGS } from './REF_JSON_TAGS.ts'
+import { setOwnProperty } from './setOwnProperty.ts'
 
 export function encodeRefJson(value: unknown): string {
     // Hoisted containers only; slots[i] is addressed by ['~r', i]. Primitives stay inline.
@@ -86,7 +87,8 @@ export function encodeRefJson(value: unknown): string {
         // (no intermediate pairs array / closures) on this per-object always-hot path.
         const encoded: Record<string, unknown> = {}
         for (const key of Object.keys(record)) {
-            encoded[key] = encodeValue(record[key])
+            // setOwnProperty: an own `__proto__` key must reach the wire, not the accessor.
+            setOwnProperty(encoded, key, encodeValue(record[key]))
         }
         return encoded
     }

package/src/lib/shared/globalCacheStoreSlot.ts

@@ -1,9 +1,12 @@
-import { globalCacheStoreResolver } from './globalCacheStoreResolver.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
 
 /*
-Slot for the process-level cache store resolver (see globalCacheStoreResolver).
-Exposed so test helpers snapshot/poke `.resolver` directly. Unset means no global
-store is registered, in which case globalCacheStore() falls back to the active
-(request/tab) store.
+Slot for the process-level cache store used by cache() entries opting into
+`global: true`. The server entry registers a module-singleton store outliving
+any one request; the client entry points it at its single tab store so
+`global` is a no-op there. No fallback creator — unset means no global store
+is registered, in which case globalCacheStore() falls back to the active
+(request/tab) store. Test helpers snapshot/poke `.resolver` directly.
 */
-export const globalCacheStoreSlot = globalCacheStoreResolver.slot
+export const globalCacheStoreSlot = createResolverSlot<CacheStore>()

package/src/lib/shared/hydratingSlot.ts

@@ -0,0 +1,12 @@
+/*
+Set true only while the client adopts the server-rendered DOM (the hydration
+render pass — see the router's hydrate branch and `hydrate`). Read by `peek`: the
+server materializes no cache value (materializeRetained/cacheEntryFromSnapshot are
+client-only), so server-side peek is uniformly undefined and the SSR render always
+shows the fallback. A snapshot-seeded warm value surfacing DURING hydration would
+diverge from that server text and corrupt the claimed text node, so peek withholds
+it until the pass ends — `wakeHydrationPeeks` then re-runs the scope on the now-
+congruent value. A plain boolean, save/restore-nested so a child hydrate can't clear
+an outer pass early; false on the server (no hydration) and after boot.
+*/
+export const hydratingSlot: { active: boolean } = { active: false }

package/src/lib/shared/isLayoutFile.ts

@@ -0,0 +1,12 @@
+import { fileName } from './fileName.ts'
+
+/*
+Whether a module path is a router `layout.abide` — an EXACT leaf-filename match, the
+one predicate every site shares. `endsWith('layout.abide')` is wrong: it also matches
+`cardlayout.abide`, which the bundler's loader (exact match) compiles as a plain
+component, so an `endsWith` site would hot-compile / fingerprint it as a layout and
+diverge from the shipped bundle. Mirrors the loader so classification can't drift.
+*/
+export function isLayoutFile(path: string): boolean {
+    return fileName(path) === 'layout.abide'
+}

package/src/lib/shared/keyForRemoteCall.ts

@@ -1,5 +1,6 @@
 import { canonicalJson } from './canonicalJson.ts'
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
+import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
 import { queryStringFromArgs } from './queryStringFromArgs.ts'
 import type { HttpMethod } from './types/HttpMethod.ts'
 
@@ -12,7 +13,7 @@ synthesized Request can't disagree); POST/PUT/PATCH join args after a space as
 canonical JSON. The rpc split mirrors buildRpcRequest exactly.
 */
 export function keyForRemoteCall(method: HttpMethod, url: string, args: unknown): string {
-    const prefix = `${method} ${url}`
+    const prefix = keyPrefixForRemote(method, url)
     if (!carriesBodyArgs(method)) {
         if (args && typeof args === 'object' && !Array.isArray(args)) {
             const search = queryStringFromArgs(args as Record<string, unknown>, true)

package/src/lib/shared/keyPrefixForRemote.ts

@@ -0,0 +1,12 @@
+import type { HttpMethod } from './types/HttpMethod.ts'
+
+/*
+The cache/error-registry key prefix a remote function's entries share: `${method} ${url}`
+(method + route template). The single definition of the prefix grammar — keyForRemoteCall
+appends `?query`/` body` onto it, and keyMatchesPrefix extends it — so every consumer that
+prefix-matches (`fn.error()`, the cache selector prefix, the MCP tool labels) composes the
+SAME prefix and can't silently mismatch if the format ever changes.
+*/
+export function keyPrefixForRemote(method: HttpMethod, url: string): string {
+    return `${method} ${url}`
+}

package/src/lib/shared/matchRoute.ts

@@ -0,0 +1,175 @@
+import { normalizePathname } from './normalizePathname.ts'
+import type { RouteSegment } from './parseRouteSegments.ts'
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+Per-route parse cache. The route set is stable across a session, so parsing a
+pattern into segments is done once per route rather than on every match. Keyed
+by the pattern string; entries never need eviction since routes don't churn.
+*/
+const PARSED_ROUTES = new Map<string, RouteSegment[]>()
+
+function parsedRoute(route: string): RouteSegment[] {
+    let segments = PARSED_ROUTES.get(route)
+    if (segments === undefined) {
+        segments = parseRouteSegments(route)
+        PARSED_ROUTES.set(route, segments)
+    }
+    return segments
+}
+
+/* One pattern segment's specificity rank — lower is more specific. */
+function segmentRank(segment: RouteSegment): number {
+    if (segment.kind === 'literal') {
+        return 0
+    }
+    if (segment.catchAll) {
+        return 3
+    }
+    return segment.optional ? 2 : 1
+}
+
+/* Positional specificity between two routes that both match a path: walk both
+   patterns left to right, and at the first position where the segment kinds
+   differ the more specific kind wins — literal > `[name]` > `[[name]]` >
+   `[...rest]`. So `/a/[b]` beats `/[a]/b`, and a literal head beats a param
+   head even against a catch-all tail (matching how Bun's own router ranked).
+   Prefix-equal patterns: the shorter one is the exact match. A full tie keeps
+   the earlier-registered route — deterministic, unlike count-based scoring,
+   because kind sequences that differ anywhere are ordered at that position. */
+function moreSpecific(candidate: RouteSegment[], best: RouteSegment[]): boolean {
+    const shared = Math.min(candidate.length, best.length)
+    for (let index = 0; index < shared; index += 1) {
+        const candidateRank = segmentRank(candidate[index] as RouteSegment)
+        const bestRank = segmentRank(best[index] as RouteSegment)
+        if (candidateRank !== bestRank) {
+            return candidateRank < bestRank
+        }
+    }
+    return candidate.length < best.length
+}
+
+/*
+The route matcher — the single grammar of record on both sides: the server's
+fetch dispatch and the client router resolve a pathname through this same
+function, so params decode and precedence agree by construction. Given the
+registered route patterns and a pathname, returns the matching route + decoded
+params, or undefined. Segments are literal / `[name]` / `[[name]]` (optional) /
+`[...rest]` (catch-all), via the shared `parseRouteSegments`. The most specific
+match wins (see moreSpecific).
+*/
+export function matchRoute(
+    routes: string[],
+    pathname: string,
+): { route: string; params: Record<string, string> } | undefined {
+    /* Match the canonical slash form — `//users` and `/users/` both match
+       `/users` — otherwise the extra empty segment rejects the path or lets
+       `/users/[id]` capture an empty id. The server redirects a request whose
+       raw pathname differs from this form before dispatching (see createServer),
+       so its auth middleware guards the same string this matcher routes. */
+    const normalized = normalizePathname(pathname)
+    const pathSegments = normalized.split('/')
+    let best: { route: string; params: Record<string, string>; parsed: RouteSegment[] } | undefined
+    for (const route of routes) {
+        const parsed = parsedRoute(route)
+        const params = matchSegments(parsed, pathSegments)
+        if (params === undefined) {
+            continue
+        }
+        if (best === undefined || moreSpecific(parsed, best.parsed)) {
+            best = { route, params, parsed }
+        }
+    }
+    return best === undefined ? undefined : { route: best.route, params: best.params }
+}
+
+/* Percent-decodes a captured value. Lenient — a malformed sequence (`/%E0%A4%A`)
+   keeps the raw text rather than throwing, so a bad escape in a navigation or
+   request can't crash matching; the downstream lookup just misses naturally. */
+function decodeParam(value: string): string {
+    try {
+        return decodeURIComponent(value)
+    } catch {
+        return value
+    }
+}
+
+/* Matches one parsed pattern against the path's segments, capturing decoded
+   params; undefined on mismatch. */
+function matchSegments(
+    segments: RouteSegment[],
+    pathSegments: string[],
+): Record<string, string> | undefined {
+    const params: Record<string, string> = {}
+    return matchFrom(segments, pathSegments, 0, 0, params) ? params : undefined
+}
+
+/*
+Depth-first walk over the pattern. An optional segment first tries to consume a
+path segment (greedy — `/[[a]]/[[b]]` on `/x` captures `a`), and on a deeper
+mismatch backtracks to try absence, un-capturing its param so a failed branch
+can't leak into the succeeding one. Recursion depth is bounded by the pattern's
+segment count, not the request path. A catch-all consumes every remaining
+segment (possibly none), decoding each sub-segment while keeping `/` separators
+— so an encoded `%2F` stays inside one sub-segment.
+*/
+function matchFrom(
+    segments: RouteSegment[],
+    pathSegments: string[],
+    segmentIndex: number,
+    pathIndex: number,
+    params: Record<string, string>,
+): boolean {
+    if (segmentIndex === segments.length) {
+        /* Pattern exhausted — the path must be too (no extra segments). */
+        return pathIndex === pathSegments.length
+    }
+    const segment = segments[segmentIndex]
+    if (segment === undefined) {
+        return false
+    }
+    if (segment.kind === 'param' && segment.catchAll) {
+        params[segment.name] = pathSegments.slice(pathIndex).map(decodeParam).join('/')
+        return true
+    }
+    const value = pathSegments[pathIndex]
+    if (segment.kind === 'literal') {
+        if (value !== segment.value) {
+            return false
+        }
+        return matchFrom(segments, pathSegments, segmentIndex + 1, pathIndex + 1, params)
+    }
+    if (segment.optional) {
+        /* Consume first; on failure restore the prior capture (a same-named
+           earlier `[name]` must survive the backtrack) and retry as absent. An
+           optional never captures an empty segment. */
+        if (value !== undefined && value !== '') {
+            const previous = params[segment.name]
+            params[segment.name] = decodeParam(value)
+            if (matchFrom(segments, pathSegments, segmentIndex + 1, pathIndex + 1, params)) {
+                return true
+            }
+            if (previous === undefined) {
+                delete params[segment.name]
+            } else {
+                params[segment.name] = previous
+            }
+        }
+        if (matchFrom(segments, pathSegments, segmentIndex + 1, pathIndex, params)) {
+            return true
+        }
+        /* Absent at the bare root: `/` splits into ['', ''] and slash collapsing
+           can't remove that dangling empty segment, so an absent optional also
+           swallows it — `/[[lang]]` must match `/` (the path url() generates). */
+        if (value === '') {
+            return matchFrom(segments, pathSegments, segmentIndex + 1, pathIndex + 1, params)
+        }
+        return false
+    }
+    /* A required `[name]` param never captures an empty segment (e.g. `/users//5`). */
+    if (value === undefined || value === '') {
+        return false
+    }
+    params[segment.name] = decodeParam(value)
+    return matchFrom(segments, pathSegments, segmentIndex + 1, pathIndex + 1, params)
+}

package/src/lib/shared/normalizePathname.ts

@@ -0,0 +1,11 @@
+/*
+The canonical slash form of a pathname: duplicate slashes collapsed, one
+trailing slash stripped (except root) — so `//users/` canonicalizes to
+`/users`. matchRoute matches this form on both sides, and the server 308s a
+page request whose raw pathname differs (see createServer), so the app.handle
+auth seam always guards exactly the string the matcher routes.
+*/
+export function normalizePathname(pathname: string): string {
+    const collapsed = pathname.includes('//') ? pathname.replace(/\/{2,}/g, '/') : pathname
+    return collapsed.length > 1 && collapsed.endsWith('/') ? collapsed.slice(0, -1) : collapsed
+}

package/src/lib/shared/pageSlot.ts

@@ -1,8 +1,17 @@
-import { pageResolver } from './pageResolver.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { PageSnapshot } from './types/PageSnapshot.ts'
 
 /*
-Internal slot the runtime entries register their page resolver into (see
-pageResolver). Exposed so test helpers snapshot/poke `.resolver` and
-`.fallback` directly.
+The active-page slot. The server entry installs an ALS-backed resolver
+(request-scoped, so concurrent and streaming renders never share state); the
+client entry a module-singleton one. With no resolver registered, a single
+empty snapshot is created lazily so isolated tests work; test helpers
+snapshot/poke `.resolver` and `.fallback` directly. activePage is the public
+read.
 */
-export const pageSlot = pageResolver.slot
+export const pageSlot = createResolverSlot<PageSnapshot>(() => ({
+    route: '',
+    params: {},
+    url: new URL('http://localhost/'),
+    navigating: false,
+}))