@abide/abide 0.46.0 → 0.48.0

package/src/lib/shared/parseRouteSegments.ts

@@ -1,21 +1,30 @@
 export type RouteSegment =
     | { kind: 'literal'; value: string }
-    | { kind: 'param'; name: string; catchAll: boolean }
+    | { kind: 'param'; name: string; catchAll: boolean; optional: boolean }
 
 /*
 Splits a abide route URL into typed segments. `[name]` becomes a param,
-`[...rest]` becomes a catch-all param, anything else is a literal. Used
-by toBunRoutePattern (server-side Bun pattern emission) and writeRoutesDts
-(client-side `Routes` type augmentation) so the two consumers can't drift
-on what counts as a param.
+`[[name]]` an optional param, `[...rest]` a catch-all param, anything else a
+literal. Used by matchRoute (both the server's fetch dispatch and the client
+router) and writeRoutesDts (client-side `Routes` type augmentation) so the
+consumers can't drift on what counts as a param.
 */
 export function parseRouteSegments(routeUrl: string): RouteSegment[] {
     return routeUrl.split('/').map((segment) => {
+        if (segment.startsWith('[[') && segment.endsWith(']]')) {
+            const name = segment.slice(2, -2)
+            /* `[[...rest]]` is redundant — a catch-all already matches zero
+               segments — but normalizing beats mis-parsing brackets into the name. */
+            if (name.startsWith('...')) {
+                return { kind: 'param', name: name.slice(3), catchAll: true, optional: false }
+            }
+            return { kind: 'param', name, catchAll: false, optional: true }
+        }
         if (segment.startsWith('[...') && segment.endsWith(']')) {
-            return { kind: 'param', name: segment.slice(4, -1), catchAll: true }
+            return { kind: 'param', name: segment.slice(4, -1), catchAll: true, optional: false }
         }
         if (segment.startsWith('[') && segment.endsWith(']')) {
-            return { kind: 'param', name: segment.slice(1, -1), catchAll: false }
+            return { kind: 'param', name: segment.slice(1, -1), catchAll: false, optional: false }
         }
         return { kind: 'literal', value: segment }
     })

package/src/lib/shared/patch.ts

@@ -0,0 +1,41 @@
+import { cache } from './cache.ts'
+import type { CacheOptions } from './types/CacheOptions.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+
+/*
+Mutate the retained value of the matching cached read(s) in place — reactive
+(readers re-render), no network. The optimistic-update / real-time primitive:
+patch a cached list from a socket frame (`on(chat, m => getList.patch(l => [...l,
+m]))`) or apply an optimistic edit before a write lands. The updater receives the
+current decoded value and returns the next.
+
+  patch(getFoo, args, updater)   → that exact call
+  patch(getFoo, updater)         → every args-variant of that rpc
+  patch({ tags }, updater)       → every entry sharing a tag
+
+Instance sugar `getFoo.patch(args?, updater)` ≡ `patch(getFoo, args, updater)`.
+The updater is always the last argument; a not-yet-read key has nothing to patch.
+*/
+// @documentation cache
+export function patch<Args, Return>(
+    fn: RemoteFunction<Args, Return> | ((args?: Args) => Promise<Return>),
+    args: Args | undefined,
+    updater: (current: Return) => Return,
+): void
+export function patch<Args, Return>(
+    fn: RemoteFunction<Args, Return> | ((args?: Args) => Promise<Return>),
+    updater: (current: Return) => Return,
+): void
+export function patch<Return>(
+    selector: Pick<CacheOptions, 'tags'>,
+    updater: (current: Return) => Return,
+): void
+export function patch(selector: unknown, argsOrUpdater: unknown, maybeUpdater?: unknown): void {
+    /* Updater is always last: 3 args → (selector, args, updater); 2 args → (selector, updater). */
+    const updater = (maybeUpdater !== undefined ? maybeUpdater : argsOrUpdater) as (
+        current: unknown,
+    ) => unknown
+    const args = maybeUpdater !== undefined ? argsOrUpdater : undefined
+    cache.patch(selector as CacheSelector<unknown, unknown>, args, updater)
+}

package/src/lib/shared/peek.ts

@@ -0,0 +1,35 @@
+import { cache } from './cache.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+import type { Socket } from './types/Socket.ts'
+
+/*
+The value member of the probe family: the currently-retained value, synchronously,
+without triggering anything — `T | undefined` (undefined when nothing is retained
+yet). For a cached read it is the retained cache value (reactive in a tracking
+scope — re-runs when a refresh lands or a patch mutates it; a one-shot snapshot
+otherwise). For a subscribable (socket / stream) it is the latest frame, read off
+the source's own `.peek()`. Instance sugar `getFoo.peek(args?)` ≡ `peek(getFoo,
+args?)`, `socket.peek()` ≡ `peek(socket)`.
+
+  peek(getFoo, args?)   → the retained value for that call
+  peek(socket)          → the latest frame
+*/
+// @documentation probes
+export function peek<Args, Return>(
+    fn: RemoteFunction<Args, Return>,
+    args?: Args,
+): Return | undefined
+export function peek<T>(source: Socket<T>): T | undefined
+export function peek(source: unknown, args?: unknown): unknown {
+    /* A subscribable (socket/stream) carries its own latest-frame probe; an rpc does not
+       have Symbol.asyncIterator, so this cleanly splits the two even though both expose a
+       `.peek` method. */
+    if (
+        source !== null &&
+        typeof source === 'object' &&
+        typeof (source as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function'
+    ) {
+        return (source as { peek: () => unknown }).peek()
+    }
+    return cache.peek(source as RemoteFunction<unknown, unknown>, args as never)
+}

package/src/lib/shared/prepareRemoteExport.ts

@@ -0,0 +1,40 @@
+import { type ExportCallSite, findExportCallSite } from './findExportCallSite.ts'
+import { importNamesToStrip } from './importNamesToStrip.ts'
+import { stripImport } from './stripImport.ts'
+
+export type RemoteExport = {
+    /* The source with the user's dead server-helper import removed. */
+    stripped: string
+    /* The one exported `helper(...)` call the surface must rewrite. */
+    site: ExportCallSite
+}
+
+/*
+The scan-once envelope every file-based remote surface ($rpc, $sockets) shares:
+strip the user's server-helper import under both the project's chosen name and
+the canonical package name (so the dead import can't side-effect-load the stub
+into the server bundle), then locate the single exported helper call. Each
+surface passes the subpaths it places under a name (`server/GET`…/`server/socket`)
+and the ident predicate that recognizes its call; the character-by-character
+walk still happens exactly once. Returns undefined when the module declares no
+matching export (a plain `.ts` helper alongside the surface), and throws the
+surface's own single-export error when it declares more than one.
+*/
+export function prepareRemoteExport(
+    source: string,
+    importName: string,
+    subpathsForName: (name: string) => string[],
+    identMatches: (ident: string) => boolean,
+    singleExportError: string,
+): RemoteExport | undefined {
+    const stripped = importNamesToStrip(importName).reduce(
+        (current, name) =>
+            subpathsForName(name).reduce((acc, subpath) => stripImport(acc, subpath), current),
+        source,
+    )
+    const site = findExportCallSite(stripped, identMatches, singleExportError)
+    if (!site) {
+        return undefined
+    }
+    return { stripped, site }
+}

package/src/lib/shared/prepareRpcModule.ts

@@ -1,8 +1,6 @@
-import { findExportCallSite } from './findExportCallSite.ts'
-import { importNamesToStrip } from './importNamesToStrip.ts'
 import { isReadOnlyMethod } from './isReadOnlyMethod.ts'
+import { prepareRemoteExport } from './prepareRemoteExport.ts'
 import { skipNonCode } from './skipNonCode.ts'
-import { stripImport } from './stripImport.ts'
 import type { HttpMethod } from './types/HttpMethod.ts'
 
 const RPC_NAMES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
@@ -15,6 +13,9 @@ export type PreparedRpcModule = {
     method: HttpMethod
     /* `outbox: true` in the opts — the client proxy is emitted durable. */
     durable: boolean
+    /* The handler calls jsonl()/sse() — the client proxy is emitted streaming (bare call
+       returns the Subscribable). Congruent with the RemoteCallable conditional by construction. */
+    streaming: boolean
     exportName: string
     rewriteForServer: (url: string) => string
 }
@@ -52,32 +53,43 @@ export function prepareRpcModule(
 ): PreparedRpcModule | undefined {
     /*
     The "no barrels" surface places each method at its own path
-    (`abide/server/GET`, `abide/server/POST`, …) — strip every one so
-    the user's method import doesn't linger and side-effect-load the
-    stub module into the server bundle. The user may import under the
-    project's chosen name or the canonical package name, so strip both.
+    (`abide/server/GET`, `abide/server/POST`, …), so the strip subpaths are
+    every method under each import name — the user's method import must not
+    linger and side-effect-load the stub module into the server bundle.
     */
-    const stripped = importNamesToStrip(importName).reduce(
-        (current, name) =>
-            RPC_NAMES.reduce(
-                (acc, method) => stripImport(acc, `${name}/server/${method}`),
-                current,
-            ),
+    const prepared = prepareRemoteExport(
         source,
+        importName,
+        (name) => RPC_NAMES.map((method) => `${name}/server/${method}`),
+        (ident) => RPC_SET.has(ident),
+        SINGLE_EXPORT_ERROR,
     )
-    const site = findExportCallSite(stripped, (ident) => RPC_SET.has(ident), SINGLE_EXPORT_ERROR)
-    if (!site) {
+    if (!prepared) {
         return undefined
     }
+    const { stripped, site } = prepared
     const method = site.ident as HttpMethod
     const durable = detectDurable(stripped, site.parenStart, site.parenEnd, method)
+    const streaming = detectStreaming(stripped, site.parenStart, site.parenEnd)
     return {
         method,
         durable,
+        streaming,
         exportName: site.exportName,
         rewriteForServer(url: string): string {
             const binding = `__abideDefineRpc__(${JSON.stringify(method)}, ${JSON.stringify(url)}, `
-            return stripped.slice(0, site.callStart) + binding + stripped.slice(site.parenStart + 1)
+            const head = stripped.slice(0, site.callStart) + binding
+            if (!streaming) {
+                return head + stripped.slice(site.parenStart + 1)
+            }
+            /* Inject the build-time streaming flag into the handler's opts, preserving any author
+               opts by spread. Split the call's top-level args (handler + optional opts) — dropping
+               a trailing-comma empty part — so a trailing comma or absent opts can't produce
+               `...()`. `head` ends after the METHOD( paren; keep everything from `)` onward. */
+            const parts = splitTopLevelArgs(stripped, site.parenStart, site.parenEnd)
+            const [handler, opts] = parts
+            const injected = opts ? `{ streaming: true, ...(${opts}) }` : '{ streaming: true }'
+            return `${head}${handler}, ${injected}${stripped.slice(site.parenEnd)}`
         },
     }
 }
@@ -111,6 +123,76 @@ function detectDurable(
     return durable
 }
 
+const STREAM_HELPERS = new Set(['jsonl', 'sse'])
+const IDENT_START = /[A-Za-z_$]/
+const IDENT_PART = /[A-Za-z0-9_$]/
+
+/* True when the handler returns a streaming body — it calls abide's jsonl()/sse(), the only
+   constructors of a `TypedResponse<AsyncIterable<Frame>>`. Congruent by construction with the
+   RemoteCallable conditional (Return is an AsyncIterable iff the handler calls jsonl/sse). Scans
+   the whole call-arg region depth-blind (the opts never mention jsonl/sse), skipping
+   strings/comments/regex via skipNonCode so a mention in a literal can't misfire. Same
+   literal-only limit as `outbox`: an indirection through a wrapper function isn't seen. */
+function detectStreaming(source: string, parenStart: number, parenEnd: number): boolean {
+    let i = parenStart + 1
+    while (i < parenEnd) {
+        const skipped = skipNonCode(source, i)
+        if (skipped !== undefined) {
+            i = skipped
+            continue
+        }
+        if (IDENT_START.test(source[i] ?? '') && !IDENT_PART.test(source[i - 1] ?? '')) {
+            let j = i + 1
+            while (j < parenEnd && IDENT_PART.test(source[j] ?? '')) {
+                j += 1
+            }
+            if (STREAM_HELPERS.has(source.slice(i, j))) {
+                let k = j
+                while (k < parenEnd && /\s/.test(source[k] ?? '')) {
+                    k += 1
+                }
+                /* `jsonl(` a call, `jsonl<` a generic call — either is the streaming constructor. */
+                if (source[k] === '(' || source[k] === '<') {
+                    return true
+                }
+            }
+            i = j
+            continue
+        }
+        i += 1
+    }
+    return false
+}
+
+/* The call's top-level arguments, trimmed, with empty parts (a trailing comma) dropped —
+   `[handler]` or `[handler, opts]`. Depth-aware and skips strings/comments/regex so commas
+   inside the handler body or opts don't miscount. */
+function splitTopLevelArgs(source: string, parenStart: number, parenEnd: number): string[] {
+    const parts: string[] = []
+    let depth = 0
+    let start = parenStart + 1
+    let i = parenStart + 1
+    while (i < parenEnd) {
+        const skipped = skipNonCode(source, i)
+        if (skipped !== undefined) {
+            i = skipped
+            continue
+        }
+        const c = source[i]
+        if (c === '(' || c === '{' || c === '[') {
+            depth += 1
+        } else if (c === ')' || c === '}' || c === ']') {
+            depth -= 1
+        } else if (c === ',' && depth === 0) {
+            parts.push(source.slice(start, i).trim())
+            start = i + 1
+        }
+        i += 1
+    }
+    parts.push(source.slice(start, parenEnd).trim())
+    return parts.filter((part) => part.length > 0)
+}
+
 /*
 The text of the call's final argument — the opts object for a `METHOD(handler, opts)` call.
 Walks the arg list depth-aware, skipping strings / templates / comments / regex (skipNonCode)

package/src/lib/shared/prepareSocketModule.ts

@@ -1,6 +1,4 @@
-import { findExportCallSite } from './findExportCallSite.ts'
-import { importNamesToStrip } from './importNamesToStrip.ts'
-import { stripImport } from './stripImport.ts'
+import { prepareRemoteExport } from './prepareRemoteExport.ts'
 
 const SINGLE_EXPORT_ERROR =
     '[abide] $sockets module contains more than one `socket(...)` export — each file must declare exactly one socket'
@@ -14,27 +12,25 @@ export type PreparedSocketModule = {
 Scans a `$sockets/**` module once and returns its declared export name
 plus a closure that, given the socket name, emits the server-side
 rewrite (`__abideDefineSocket__("<name>"[, opts])` spliced into the
-original source). The single scan replaces the prior separate
-extract + rewrite passes, so the resolver plugin only walks each source
-character-by-character once.
+original source). The strip + find envelope is the shared prepareRemoteExport
+scan; this module only supplies the socket import subpath and ident, then
+splices its own binding.
 */
 export function prepareSocketModule(
     source: string,
     importName: string,
 ): PreparedSocketModule | undefined {
-    /*
-    Strip the user's `socket` import under the project's chosen name and the
-    canonical package name so the dead import can't side-effect-load the
-    socket helper into the server bundle.
-    */
-    const stripped = importNamesToStrip(importName).reduce(
-        (current, name) => stripImport(current, `${name}/server/socket`),
+    const prepared = prepareRemoteExport(
         source,
+        importName,
+        (name) => [`${name}/server/socket`],
+        (ident) => ident === 'socket',
+        SINGLE_EXPORT_ERROR,
     )
-    const site = findExportCallSite(stripped, (ident) => ident === 'socket', SINGLE_EXPORT_ERROR)
-    if (!site) {
+    if (!prepared) {
         return undefined
     }
+    const { stripped, site } = prepared
     return {
         exportName: site.exportName,
         rewriteForServer(name: string): string {

package/src/lib/shared/queryStringFromArgs.ts

@@ -11,6 +11,10 @@ is stable under arg reordering. Returns the query body without a leading
 walk — no entries / filtered / URLSearchParams intermediates — to keep the
 hot GET-cache path allocation-light. Callers validate that `args` is a
 plain object first; this assumes that.
+
+A non-primitive VALUE throws: String() would flatten every object to
+'[object Object]', so distinct calls would collide onto one request URL and
+one cache key — the first call's data silently served for the second.
 */
 export function queryStringFromArgs(args: Record<string, unknown>, sort: boolean): string {
     const keys = sort ? Object.keys(args).sort() : Object.keys(args)
@@ -20,6 +24,13 @@ export function queryStringFromArgs(args: Record<string, unknown>, sort: boolean
         if (value === undefined) {
             continue
         }
+        const kind = typeof value
+        if (value !== null && (kind === 'object' || kind === 'function' || kind === 'symbol')) {
+            const got = Array.isArray(value) ? 'array' : kind
+            throw new TypeError(
+                `[abide] query arg "${key}" must be a primitive — got ${got} (query-carrying methods can't encode structured values; move the arg to a POST body)`,
+            )
+        }
         query += query ? '&' : ''
         query += `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
     }

package/src/lib/shared/reachable.ts

@@ -0,0 +1,102 @@
+import { createReachable } from './createReachable.ts'
+import { parseBoundedEnvInt } from './parseBoundedEnvInt.ts'
+
+/*
+Isomorphic outbound reachability. `await reachable(host)` HEADs the host's
+origin: the first call awaits a real probe (faithful — a down host costs the
+full timeout, an up host one handshake) and starts a background poll that
+re-probes every TTL, so every later call resolves instantly off the warm
+value, fresh within one TTL. A host going down is caught within ~failureLimit
+polls; recovery flips it back automatically.
+
+  if (!(await reachable('api.example.com'))) return error(503)
+
+No host asks about the app's own backend: constant true on the server (the
+server IS the backend — health()'s rule) and on a loopback origin (`abide
+dev`, a desktop bundle's embedded server — this machine, reachable by
+construction even with the network gone); a deployed origin probes like any
+other host.
+
+A bare host defaults to https; pass an explicit http://… for a non-TLS host.
+Answers "can I connect to this host," NOT "is my endpoint healthy": any
+completed HTTP response (even 4xx/5xx, even a 405 to HEAD) counts as reachable;
+only a connection failure or timeout reads as unreachable.
+
+Same callable both sides. The server has no ambient connectivity signal, so
+this is the honest way to fail a doomed outbound call fast — see online() for
+the inbound/client-reported counterpart. The browser probes no-cors (a
+completed opaque response proves connectivity without the host's CORS
+blessing) and composes navigator.onLine in at read time, so a lost network
+reports false instantly instead of waiting out the warm value — except for
+loopback hosts, which need no network.
+
+ABIDE_REACHABLE_TTL (poll cadence / freshness, ms) and ABIDE_REACHABLE_TIMEOUT
+(per-HEAD bound, ms) tune the server defaults; the browser has no env, so it
+runs the defaults. The timeout is deliberately generous so a healthy-but-
+distant host over a slow link is not mis-read as down.
+*/
+const env = typeof process === 'undefined' ? undefined : process.env
+const TTL_MS = parseBoundedEnvInt(env?.ABIDE_REACHABLE_TTL, 1_000, 600_000) ?? 30_000
+const TIMEOUT_MS = parseBoundedEnvInt(env?.ABIDE_REACHABLE_TIMEOUT, 100, 60_000) ?? 3_000
+/* Stop polling a host nobody has read in a few TTLs; the next read restarts it cold. */
+const IDLE_MS = TTL_MS * 3
+
+/* Status-agnostic HEAD: a completed response proves connectivity; reject/timeout does not.
+   The browser probes no-cors — an opaque response still completes, so a foreign origin
+   without CORS headers can't mis-read an up host as down. */
+async function probeOrigin(origin: string): Promise<boolean> {
+    try {
+        await fetch(origin, {
+            method: 'HEAD',
+            mode: typeof window === 'undefined' ? undefined : 'no-cors',
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        })
+        return true
+    } catch {
+        return false
+    }
+}
+
+const registry = createReachable({
+    probe: probeOrigin,
+    intervalMs: TTL_MS,
+    idleMs: IDLE_MS,
+})
+
+/* Loopback = this machine: no network between, so no probe and no offline gate. */
+function isLoopbackHost(hostname: string): boolean {
+    return (
+        hostname === 'localhost' ||
+        hostname.endsWith('.localhost') ||
+        hostname.startsWith('127.') ||
+        hostname === '[::1]'
+    )
+}
+
+/* Mirrors the registry's normalization: a bare host defaults to https. */
+function hostnameOf(host: string | URL): string {
+    const url = typeof host === 'string' && !/^https?:\/\//i.test(host) ? `https://${host}` : host
+    return new URL(url).hostname
+}
+
+// @documentation observability
+export function reachable(host?: string | URL): Promise<boolean> {
+    if (typeof window === 'undefined') {
+        /* No host = the app's own backend, and the server IS the backend. */
+        return host === undefined ? Promise.resolve(true) : registry.reachable(host)
+    }
+    if (host === undefined) {
+        /* The app's own backend = the page's origin. Loopback served this very page
+           from this machine — reachable by construction, never worth a poll. */
+        if (isLoopbackHost(location.hostname)) {
+            return Promise.resolve(true)
+        }
+        host = location.origin
+    }
+    /* window-gated because Bun defines a partial navigator; `=== false` because only an
+       explicit offline report is reliable. A loopback host is exempt — no network needed. */
+    if (navigator.onLine === false && !isLoopbackHost(hostnameOf(host))) {
+        return Promise.resolve(false)
+    }
+    return registry.reachable(host)
+}

package/src/lib/shared/refresh.ts

@@ -0,0 +1,22 @@
+import { cache } from './cache.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+
+/*
+Refetch every cached read matching the selector, keeping the stale value visible
+until the fresh one swaps in (refreshing() true meanwhile) — the smart-call
+refetch. Because the smart read retains its value on the client (SWR
+unconditional there), a refresh always refetches-and-swaps; it never drops to a
+pending blank. Follows the shared selector grammar:
+
+  refresh(getFoo, args)   → that exact call
+  refresh(getFoo)         → every args-variant of that rpc
+  refresh({ tags })       → every entry sharing a tag
+  refresh()               → every entry
+
+Instance sugar `getFoo.refresh(args?)` ≡ `refresh(getFoo, args?)`. Reports, never
+retains a spinner — pair with `refreshing()` to surface the in-flight reload.
+*/
+// @documentation cache
+export function refresh<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args): void {
+    cache.refresh(arg, args)
+}

package/src/lib/shared/requestScopeSlot.ts

@@ -1,10 +1,13 @@
-import { requestScopeResolver } from './requestScopeResolver.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
 
 /*
-Internal slot the runtime entries register their request-scope resolver into (see
-requestScopeResolver). Exposed so callers read `.resolver?.()` and test helpers
-snapshot/poke `.resolver` directly. Undefined resolver — or one returning
-undefined outside any request — means "no scope": trace() returns undefined and
-log lines print without the context prefix.
+The request-scope slot. The server installs an ALS-backed resolver
+(createServer, reading the RequestStore); the client a module-singleton seeded
+from __SSR__ (startClient). No fallback creator — an unset resolver (or one
+returning undefined outside any request) means "no scope": callers read
+`.resolver?.()` and treat undefined as absent (trace() returns undefined and
+log lines print without the context prefix). Test helpers snapshot/poke
+`.resolver` directly.
 */
-export const requestScopeSlot = requestScopeResolver.slot
+export const requestScopeSlot = createResolverSlot<RequestScopeInfo>()

package/src/lib/shared/routeParamsShape.ts

@@ -3,18 +3,18 @@ import { parseRouteSegments } from './parseRouteSegments.ts'
 /*
 The TypeScript type literal for a route's path params — `{ "id": string }` for
 `/post/[id]`, `Record<string, never>` for a param-less route. Walks the `[name]` /
-`[...rest]` segments; catch-all segments map to `string` under their declared name
-(the server's toBunRoutePattern renames Bun's `*` key back to that name when
-dispatching, so the page sees `params.rest`, not `params['*']`). The single source of
-truth shared by `writeRoutesDts` (page.params typing) and the `.abide` check shadow
-(page `props()` typing).
+`[[name]]` / `[...rest]` segments; a catch-all maps to `string` under its declared
+name (matchRoute captures it there, `''` when it consumed nothing), and an
+`[[optional]]` maps to an optional key (absent from params when unmatched). The
+single source of truth shared by `writeRoutesDts` (page.params typing) and the
+`.abide` check shadow (page `props()` typing).
 */
 export function routeParamsShape(routeUrl: string): string {
-    const keys = parseRouteSegments(routeUrl)
+    const entries = parseRouteSegments(routeUrl)
         .filter((segment) => segment.kind === 'param')
-        .map((segment) => segment.name)
-    if (keys.length === 0) {
+        .map((segment) => `${JSON.stringify(segment.name)}${segment.optional ? '?' : ''}: string`)
+    if (entries.length === 0) {
         return 'Record<string, never>'
     }
-    return `{ ${keys.map((key) => `${JSON.stringify(key)}: string`).join('; ')} }`
+    return `{ ${entries.join('; ')} }`
 }

package/src/lib/shared/rpcErrorRegistry.ts

@@ -0,0 +1,69 @@
+import { createSignalNode } from '../ui/runtime/createSignalNode.ts'
+import { track } from '../ui/runtime/track.ts'
+import { trigger } from '../ui/runtime/trigger.ts'
+
+/*
+The rpc's error memory — the last error per call identity (the keyForRemoteCall
+key), recorded at the rpc call boundary and cleared on a later success or
+invalidate. Orthogonal to the cache entry lifecycle (design Fork 1): the cache
+still evicts on error exactly as before; this remembers the error for reactive
+reads. One shared signal node backs reactivity — readers `track` it, writers
+`trigger` it — the same coarse lifecycle-channel pattern the cache probes use.
+*/
+const node = createSignalNode(undefined)
+const errors = new Map<string, unknown>()
+
+/* Insertion order = recency; a re-record moves the key to the tail so readAny returns latest. */
+function bump(key: string, error: unknown): void {
+    errors.delete(key)
+    errors.set(key, error)
+}
+
+export const rpcErrorRegistry = {
+    record(key: string, error: unknown): void {
+        /* Client-only: on the server the boundary runs per request, and this Map is a single
+           module global — recording would leak errors across requests/users and grow unbounded.
+           SSR errors surface through `{:catch}`; the reactive probe is a client feature, so the
+           server keeps the Map empty (reads return undefined there). */
+        if (typeof window === 'undefined') {
+            return
+        }
+        bump(key, error)
+        trigger(node)
+    },
+    clear(key: string): void {
+        if (errors.delete(key)) {
+            trigger(node)
+        }
+    },
+    /* Clears every error whose key is, or is prefixed by, the selector's `method url` —
+       so `invalidate(fn)` resets a whole rpc's errors, and `invalidate(fn, args)` (an exact
+       key prefix) resets just that call. Covers bare-call errors that never became entries. */
+    clearMatching(prefix: string): void {
+        let changed = false
+        for (const key of errors.keys()) {
+            if (key === prefix || key.startsWith(`${prefix} `)) {
+                errors.delete(key)
+                changed = true
+            }
+        }
+        if (changed) {
+            trigger(node)
+        }
+    },
+    read(key: string): unknown {
+        track(node)
+        return errors.get(key)
+    },
+    /* Most-recent error whose key is, or is prefixed by, the fn selector's `method url`. */
+    readAny(prefix: string): unknown {
+        track(node)
+        let latest: unknown
+        for (const [key, error] of errors) {
+            if (key === prefix || key.startsWith(`${prefix} `)) {
+                latest = error
+            }
+        }
+        return latest
+    },
+}