@abide/abide 0.49.0 → 0.50.1

package/src/lib/shared/decodeRefJson.ts

@@ -6,7 +6,7 @@ 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.ts'
+import { REF_JSON_NUMBER_TOKENS, REF_JSON_TAGS } from './REF_JSON_TAGS.ts'
 import { setOwnProperty } from './setOwnProperty.ts'
 
 export function decodeRefJson(text: string): unknown {
@@ -99,13 +99,13 @@ function fillShell(slot: unknown, shell: unknown, shells: unknown[]): void {
 
 // Reverse of encodeRefJson's numberToken.
 function decodeNumberToken(token: string): number {
-    if (token === 'NaN') {
+    if (token === REF_JSON_NUMBER_TOKENS.NAN) {
         return Number.NaN
     }
-    if (token === 'Infinity') {
+    if (token === REF_JSON_NUMBER_TOKENS.INFINITY) {
         return Number.POSITIVE_INFINITY
     }
-    if (token === '-Infinity') {
+    if (token === REF_JSON_NUMBER_TOKENS.NEG_INFINITY) {
         return Number.NEGATIVE_INFINITY
     }
     return -0

package/src/lib/shared/decodeResponse.ts

@@ -18,7 +18,7 @@ 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.
-A streaming rpc's bare call already returns a Subscribable (the type makes
+A streaming rpc's bare call already returns a NamedAsyncIterable (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
@@ -39,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}) — 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()`,
+            `[abide] response at ${response.url} is a stream (${contentType}) — a streaming rpc's bare call already returns a NamedAsyncIterable: 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/decodeWireBody.ts

@@ -0,0 +1,35 @@
+/*
+The single decode point for the "is this ref-json?" policy: abide's own client speaks
+ref-json (encodeRefJson — restores the cycles/shared refs/structured types plain JSON
+can't carry); a foreign client (curl, an OpenAPI SDK, a raw ws client) speaks ordinary
+JSON. Both the rpc body face and the socket-frame face funnel through here so the
+codec fork lives in exactly one place instead of being re-derived per face.
+
+The discriminator is a genuine per-face input difference, kept thin at the call site:
+
+  - `isRefJson === true`  — the rpc client stamped REF_JSON_HEADER, so decode as ref-json.
+  - `isRefJson === false` — no header (a non-abide rpc body), so plain JSON.parse.
+  - `isRefJson === undefined` — no header is available at all (a ws frame carries none),
+    so sniff: try ref-json, fall back to plain JSON. The ref-json `[rootValue, slots]`
+    envelope is ambiguous with a legitimate 2-element array, but a frame is always an
+    object, so a foreign plain-JSON frame makes decodeRefJson throw and we fall back.
+
+Throws on a malformed payload (JSON.parse's own SyntaxError) — the caller decides
+whether that's a 400 (rpc) or a dropped frame (ws).
+*/
+import { decodeRefJson } from './decodeRefJson.ts'
+
+export function decodeWireBody(text: string, isRefJson: boolean | undefined): unknown {
+    if (isRefJson === true) {
+        return decodeRefJson(text)
+    }
+    if (isRefJson === false) {
+        return JSON.parse(text)
+    }
+    // No discriminator (a ws frame has no header): try ref-json, fall back to plain JSON.
+    try {
+        return decodeRefJson(text)
+    } catch {
+        return JSON.parse(text)
+    }
+}

package/src/lib/shared/detectRpcMethod.ts

@@ -1,3 +1,4 @@
+import { HTTP_METHODS } from './HTTP_METHODS.ts'
 import type { HttpMethod } from './types/HttpMethod.ts'
 
 /*
@@ -9,8 +10,14 @@ undefined when no rpc export matches — the caller skips the file rather
 than guessing. Used by the rpc.d.ts codegen to type url() against
 query-carrying rpcs; matching the same convention the bundler rewrites
 keeps the two from drifting.
+
+The FAIL-OPEN fallback for writeRpcDts's method resolution (ADR-0025 D2/D3): when a
+warm server program is present the method is read off the export's helper SYMBOL
+(alias/re-export-aware), and this regex — keyed on the literal helper name — is used
+only when no program built or the query didn't resolve. Byte-identical to the pre-ADR
+path when no program is present.
 */
-const RPC_EXPORT = /export\s+const\s+\w+\s*=\s*(GET|POST|PUT|PATCH|DELETE|HEAD)\s*[<(]/
+const RPC_EXPORT = new RegExp(`export\\s+const\\s+\\w+\\s*=\\s*(${HTTP_METHODS.join('|')})\\s*[<(]`)
 
 export function detectRpcMethod(source: string): HttpMethod | undefined {
     return (source.match(RPC_EXPORT)?.[1] as HttpMethod | undefined) ?? undefined

package/src/lib/shared/done.ts

@@ -1,5 +1,5 @@
 import { tailProbeSlot } from './tailProbeSlot.ts'
-import type { Subscribable } from './types/Subscribable.ts'
+import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
 
 /*
 Reactive terminal-state reader for a stream: true once the source has closed (its
@@ -9,6 +9,12 @@ tail entry status === 'done'). Stream-only — a cache entry's "done" is just
 registered (server render, or tail never imported) reads as not-done.
 */
 // @documentation probes
-export function done(subscribable: Subscribable<unknown>): boolean {
+export function done(subscribable: NamedAsyncIterable<unknown>): boolean {
+    /* Null-tolerant: a promise/iterable subexpression peek-lifts to `undefined` while
+       pending (ADR-0032), so `done(getFeed())` in a template hands us `undefined` on the
+       first pass — treat a missing source as not-done rather than throwing. */
+    if (subscribable == null) {
+        return false
+    }
     return tailProbeSlot.probe?.(subscribable.name)?.done ?? false
 }

package/src/lib/shared/encodeRefJson.ts

@@ -11,7 +11,7 @@ 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.ts'
+import { REF_JSON_NUMBER_TOKENS, REF_JSON_TAGS } from './REF_JSON_TAGS.ts'
 import { setOwnProperty } from './setOwnProperty.ts'
 
 export function encodeRefJson(value: unknown): string {
@@ -99,10 +99,10 @@ export function encodeRefJson(value: unknown): string {
 // Stable token for the numbers JSON can't carry.
 function numberToken(value: number): string {
     if (Object.is(value, -0)) {
-        return '-0'
+        return REF_JSON_NUMBER_TOKENS.NEG_ZERO
     }
     if (Number.isNaN(value)) {
-        return 'NaN'
+        return REF_JSON_NUMBER_TOKENS.NAN
     }
-    return value > 0 ? 'Infinity' : '-Infinity'
+    return value > 0 ? REF_JSON_NUMBER_TOKENS.INFINITY : REF_JSON_NUMBER_TOKENS.NEG_INFINITY
 }

package/src/lib/shared/encodeWireBody.ts

@@ -0,0 +1,18 @@
+/*
+The single honest-JSON ENCODE point for the REST response faces (`json()` and the
+per-frame `sse()` body). JSON.stringify driven by wireJsonReplacer so a structured
+runtime value crosses as honest JSON — a `Set` → array, a `Map` → `[K,V]` entries, a
+`bigint` → digit string — instead of the silent `{}` a bare Set stringifies to or the
+throw a bare bigint triggers. Value-directed (not type-directed), so every consumer
+reads the same honest JSON the projected schema (jsonSchemaForType) describes: abide's
+own client and a foreign EventSource/curl alike.
+
+This is the REST counterpart to the ws path's encodeRefJson: it preserves the
+structured values losslessly the way ref-json does, but without the `[rootValue, slots]`
+envelope a foreign REST consumer (a naive EventSource + JSON.parse) can't read.
+*/
+import { wireJsonReplacer } from './wireJsonReplacer.ts'
+
+export function encodeWireBody(value: unknown): string {
+    return JSON.stringify(value, wireJsonReplacer)
+}

package/src/lib/{server/rpc → shared}/fieldErrorsFromIssues.ts

@@ -1,4 +1,4 @@
-import type { StandardSchemaV1 } from '../../shared/types/StandardSchemaV1.ts'
+import type { StandardSchemaV1 } from './types/StandardSchemaV1.ts'
 
 /*
 Flattens Standard Schema issues into a top-level-field → first-message map, the
@@ -7,6 +7,10 @@ bare `PropertyKey` or a `{ key }` wrapper (the spec allows both), so normalize
 before reading. First message wins per field (a form shows one per input); the
 raw `issues` keep every message and the full path. Issues with no string field
 (root-level refinements) are omitted — they live only in `issues`.
+
+Isomorphic (only the type-only StandardSchemaV1 import): the server 422 path
+(validationError.ts) and the client pre-flight (validationHttpError.ts, ADR-0026)
+both build the identical `fields` map from the same issue list.
 */
 export function fieldErrorsFromIssues(
     issues: readonly StandardSchemaV1.Issue[],

package/src/lib/shared/generateDeclarations.ts

@@ -0,0 +1,72 @@
+import { existsSync } from 'node:fs'
+import { Glob } from 'bun'
+import { abideImportName } from './abideImportName.ts'
+import { abideLog } from './abideLog.ts'
+import { rpcServerForRoot } from './rpcServerForRoot.ts'
+import { scanPages } from './scanPages.ts'
+import { writeHealthDts } from './writeHealthDts.ts'
+import { writePublicAssetsDts } from './writePublicAssetsDts.ts'
+import { writeRoutesDts } from './writeRoutesDts.ts'
+import { writeRpcDts } from './writeRpcDts.ts'
+import { writeTestRpcDts } from './writeTestRpcDts.ts'
+import { writeTestSocketsDts } from './writeTestSocketsDts.ts'
+
+/* Globs a project subtree once, returning [] when the dir is absent so an app
+   missing a folder still generates the same (mirrors the plugin's scanDir /
+   scanPublicOnce). */
+async function scanDir(dir: string, pattern: string, onlyFiles: boolean): Promise<string[]> {
+    if (!existsSync(dir)) {
+        return []
+    }
+    return await Array.fromAsync(new Glob(pattern).scan({ cwd: dir, onlyFiles }))
+}
+
+/*
+The single producer of the dev-editor `.d.ts` artifacts under src/.abide
+(routes/rpc/testRpc/testSockets/health/publicAssets). Owned by build() and run
+CONCURRENTLY with Bun.build so its one rpc `ts.Program` build (ADR-0025 D2's
+alias-aware method detection) hides under the bundle. The runtime server (dev
+worker / `abide start`) no longer generates any `.d.ts` at boot — that removed
+the per-boot program build. Every `.d.ts` here is a non-critical editor
+convenience (CI typechecks via shadow programs, not these files), so the whole
+body is guarded: a codegen hiccup LOGS and resolves rather than failing the
+build.
+*/
+export async function generateDeclarations({ cwd }: { cwd: string }): Promise<void> {
+    try {
+        const rpcDir = `${cwd}/src/server/rpc`
+        const socketsDir = `${cwd}/src/server/sockets`
+        const pagesDir = `${cwd}/src/ui/pages`
+        const publicDir = `${cwd}/src/ui/public`
+        const [importName, pagesScan, rpcFiles, socketFiles, publicFiles] = await Promise.all([
+            abideImportName(cwd),
+            scanPages(pagesDir),
+            scanDir(rpcDir, '**/*.ts', false),
+            scanDir(socketsDir, '**/*.ts', false),
+            scanDir(publicDir, '**/*', true),
+        ])
+        /* One program per build (ADR-0025 D2): resolve each rpc's method off its export helper
+           SYMBOL so an aliased/re-exported helper resolves where writeRpcDts's regex misses it.
+           Fails open to undefined, in which case writeRpcDts falls back to its own regex. */
+        const rpcServerProgram = rpcServerForRoot(new Map(), cwd, rpcDir)
+        const hasAppModule = existsSync(`${cwd}/src/app.ts`)
+        await Promise.all([
+            writeRoutesDts({ cwd, pageFiles: pagesScan.pageFiles, importName }),
+            writeRpcDts({
+                cwd,
+                rpcDir,
+                rpcFiles,
+                importName,
+                methodForModule: rpcServerProgram
+                    ? (modulePath) => rpcServerProgram.methodForModule(modulePath)
+                    : undefined,
+            }),
+            writeTestRpcDts({ cwd, rpcFiles, importName }),
+            writeTestSocketsDts({ cwd, socketFiles, importName }),
+            writeHealthDts({ cwd, hasAppModule, importName }),
+            writePublicAssetsDts({ cwd, publicFiles, importName }),
+        ])
+    } catch (error) {
+        abideLog.error(error)
+    }
+}

package/src/lib/shared/hasSeedableRequest.ts

@@ -0,0 +1,25 @@
+import type { CacheEntry } from './types/CacheEntry.ts'
+
+/*
+Whether a cache entry carries a wire request that can be SEEDED into the SSR warm
+snapshot — any method, so an inline (bare smart read) call hydrates warm on the
+client instead of re-firing after render, regardless of verb. A value called
+inline during render is being used as a read; the seed carries the SSR-computed
+body so the client reads it warm rather than issuing a second call. Producer
+entries (no request) and stream cells (a `NamedAsyncIterable` cell holds no wire
+request) fail it — neither can round-trip a url/method/body through the snapshot.
+
+This gates SEEDING, not re-firing. Re-firing unprompted (invalidate-policy
+refetch, snapshot replay) stays GET-only (REPLAYABLE_METHODS / isReplayableMethod
+in cache.ts) so a genuine write coalesces-only and stays re-submittable — a
+seeded POST is read warm once, never auto-replayed.
+
+The request half of snapshot shippability, factored out so the two gates that
+need it cannot drift: `snapshotShippable` composes it with `settled` for the
+store-filter sites, and `snapshotEntryFromCache` calls it alone — its
+streaming-drain caller hands it still-pending entries it then awaits, so it can't
+require `settled` up front.
+*/
+export function hasSeedableRequest(entry: CacheEntry): boolean {
+    return entry.request !== undefined
+}

package/src/lib/shared/hydrationWindow.ts

@@ -0,0 +1,53 @@
+import { cacheStores } from './cacheStores.ts'
+
+/*
+The one owner of the hydration pass lifecycle — the timing window during which the
+client adopts the server-rendered DOM (the router's hydrate branch and `hydrate`).
+
+Why it exists: 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 (assertClaimedText desync), so `peek` withholds it while `active` is true and
+`wake()` re-runs the withheld scopes once the pass ends.
+
+`active` is a plain boolean — false on the server (no hydration) and after boot —
+readable by the withhold check. `enter`/`exit` bracket a pass with save/restore
+nesting (a `depth` counter) so a child hydrate can't clear an outer pass early;
+`active` stays true until the OUTERMOST `exit`, which then fires `wake`.
+
+`wake` marks every live cache entry's key: a peek scope taps the exact call key's
+lifecycle channel (peek's trackLifecycle), so marking every live entry's key wakes
+the scopes that withheld — cheap, one-time, and harmless for non-peek lifecycle
+readers (they recompute the same value). Marks by key, not the bare store-wide
+channel, because a peek(fn, args) scope taps the per-key prefix channel, which a
+keyless mark misses.
+*/
+export const hydrationWindow = {
+    active: false,
+    depth: 0,
+    /* Open a pass. Nested enters raise the depth without re-firing anything. */
+    enter(): void {
+        hydrationWindow.depth += 1
+        hydrationWindow.active = true
+    },
+    /* Close a pass. Only the OUTERMOST unwind (depth back to zero) clears `active`
+       and wakes the scopes the pass withheld — a nested child exit must not. */
+    exit(): void {
+        hydrationWindow.depth -= 1
+        if (hydrationWindow.depth === 0) {
+            hydrationWindow.active = false
+            hydrationWindow.wake()
+        }
+    },
+    /* Re-run the peeks the pass withheld, now that the retained value is congruent
+       to show. Mark every live entry's key across both cache stores. */
+    wake(): void {
+        const stores = cacheStores()
+        for (const store of stores) {
+            for (const key of store.entries.keys()) {
+                store.markLifecycle(key)
+            }
+        }
+    },
+}

package/src/lib/shared/isAsyncCell.ts

@@ -0,0 +1,11 @@
+import { ASYNC_CELL } from './ASYNC_CELL.ts'
+import type { AsyncComputed } from './types/AsyncComputed.ts'
+
+/*
+True for an async cell's facet — the brand the probe family tests to route a cell
+(`AsyncComputed`/`AsyncState`) to its own `peek`/`pending`/`refreshing`/`refresh`
+methods instead of the cache/stream registries.
+*/
+export function isAsyncCell(value: unknown): value is AsyncComputed<unknown> {
+    return typeof value === 'object' && value !== null && ASYNC_CELL in value
+}

package/src/lib/shared/isAsyncIterable.ts

@@ -0,0 +1,8 @@
+/*
+Any async iterable — a stream cell auto-tracks by consuming `Symbol.asyncIterator` alone, so
+it needs no `name` (unlike `isSubscribable`, which the probe registry keys on the name). A
+plain `async function*` generator qualifies here where the named check would reject it.
+*/
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+    return value != null && typeof (value as any)[Symbol.asyncIterator] === 'function'
+}

package/src/lib/shared/isSubscribable.ts

@@ -1,11 +1,11 @@
-import type { Subscribable } from './types/Subscribable.ts'
+import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
 
 /*
-A Subscribable is a named AsyncIterable — distinguishes a stream argument from
+A NamedAsyncIterable is an AsyncIterable carrying a `name` — distinguishes a stream argument from
 the other probe selector shapes (callables and `{ tags }` objects, neither of
 which carries Symbol.asyncIterator).
 */
-export function isSubscribable(value: unknown): value is Subscribable<unknown> {
+export function isSubscribable(value: unknown): value is NamedAsyncIterable<unknown> {
     return (
         typeof value === 'object' &&
         value !== null &&

package/src/lib/shared/isThenable.ts

@@ -0,0 +1,9 @@
+/* True for a Promise-like value — anything carrying a callable `then`. Used to tell an
+   async cell's unwrap path (a promise to await) from a synchronously-produced value. */
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+    return (
+        value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof (value as { then?: unknown }).then === 'function'
+    )
+}

package/src/lib/shared/jsonSchemaForType.ts

@@ -0,0 +1,258 @@
+import ts from 'typescript'
+
+const STRINGISH_FLAGS =
+    ts.TypeFlags.String | ts.TypeFlags.TemplateLiteral | ts.TypeFlags.StringMapping
+const NUMERIC_FLAGS = ts.TypeFlags.Number | ts.TypeFlags.NumberLiteral
+const NULLISH_FLAGS = ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void
+const OPTIONALITY_FLAGS = ts.TypeFlags.Undefined | ts.TypeFlags.Void
+
+/*
+Projects a `ts.Type` to a JSON Schema (ADR-0030 D2) — the complement of jsonSchemaForSchema, which
+projects a runtime VALIDATOR. This projects a bare typed handler return so an rpc's OpenAPI 200 / MCP
+outputSchema is generated from the handler's return type when no `schemas.output` validator is
+declared. Covers the subset abide's `json()`/`jsonl()` actually emit (primitives, literals, objects,
+arrays, tuples, unions, Date, records). Returns the same `Record<string, unknown>` shape
+jsonSchemaForSchema does, so the projected schema is drop-in for every surface.
+
+Fails OPEN: an unsupported / unresolvable type projects to `{}` (permissive "any JSON") and, at the
+top level, a bare `{}` collapses to undefined so the surface omits the schema — exactly today's
+behavior with no `schemas.output`. Never throws, so a projection gap can't break a build. The `seen`
+set guards a recursive type (a tree node referencing itself) from infinite-looping — a revisit
+emits `{}` to break the cycle.
+*/
+export function jsonSchemaForType(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+): Record<string, unknown> | undefined {
+    const schema = project(checker, type, new Set())
+    // A bare permissive object carries no shape hint — omit it so the surface behaves as if unschema'd.
+    return Object.keys(schema).length === 0 ? undefined : schema
+}
+
+/* The recursive core. Always returns a schema object (never undefined) — `{}` is the permissive
+   fail-open value for anything unsupported, so every branch can compose the result inline. */
+function project(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    // any/unknown carry no shape — permissive.
+    if ((type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0) {
+        return {}
+    }
+    if (type.isUnion()) {
+        return projectUnion(checker, type, seen)
+    }
+    // An intersection rarely projects cleanly to a single JSON Schema — punt permissive (ADR-0030 scope).
+    if (type.isIntersection()) {
+        return {}
+    }
+    // `boolean` is a `true | false` union caught above; a lone literal / intrinsic lands here.
+    if ((type.flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)) !== 0) {
+        return { type: 'boolean' }
+    }
+    if ((type.flags & ts.TypeFlags.StringLiteral) !== 0) {
+        return { type: 'string', const: (type as ts.StringLiteralType).value }
+    }
+    // A template-literal / mapped string projects to a plain string (its pattern isn't modeled).
+    if ((type.flags & STRINGISH_FLAGS) !== 0) {
+        return { type: 'string' }
+    }
+    if ((type.flags & NUMERIC_FLAGS) !== 0) {
+        return { type: 'number' }
+    }
+    // JSON Schema has no bigint; matches the ADR-0029 wire representation (a bigint rides as a string).
+    if ((type.flags & (ts.TypeFlags.BigInt | ts.TypeFlags.BigIntLiteral)) !== 0) {
+        return { type: 'string' }
+    }
+    if ((type.flags & ts.TypeFlags.Null) !== 0) {
+        return { type: 'null' }
+    }
+    if ((type.flags & OPTIONALITY_FLAGS) !== 0) {
+        return {}
+    }
+    // A function/callable body isn't JSON — punt permissive.
+    if (type.getCallSignatures().length > 0) {
+        return {}
+    }
+    const symbolName = type.getSymbol()?.name
+    if (symbolName === 'Date') {
+        return { type: 'string', format: 'date-time' }
+    }
+    if (symbolName === 'Array' || symbolName === 'ReadonlyArray') {
+        return projectArray(checker, type, seen)
+    }
+    // A `Set`/`Map` rides the wire as a JSON array (ADR-0029 output encode), so the projected schema
+    // MUST agree with those bytes — a `Set<T>` is `T[]`, a `Map<K,V>` is `[K,V][]` entries.
+    if (symbolName === 'Set' || symbolName === 'ReadonlySet') {
+        return projectSet(checker, type, seen)
+    }
+    if (symbolName === 'Map' || symbolName === 'ReadonlyMap') {
+        return projectMap(checker, type, seen)
+    }
+    if (isTupleType(type)) {
+        return projectTuple(checker, type, seen)
+    }
+    if ((type.flags & ts.TypeFlags.Object) !== 0) {
+        return projectObject(checker, type, seen)
+    }
+    return {}
+}
+
+/*
+A union projects by first stripping the `undefined`/`null`/`void` members that only encode
+optionality (they make a property non-required, not a real branch). What survives: all-boolean →
+`boolean`; all string-literal → `const` (one) or `enum` (many); one survivor → that member's schema;
+otherwise `anyOf` of each. An all-nullish union (a bare `undefined`) has nothing to say → `{}`.
+*/
+function projectUnion(
+    checker: ts.TypeChecker,
+    type: ts.UnionType,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    const members = type.types.filter((member) => (member.flags & NULLISH_FLAGS) === 0)
+    if (members.length === 0) {
+        return {}
+    }
+    if (members.every((member) => (member.flags & ts.TypeFlags.BooleanLiteral) !== 0)) {
+        return { type: 'boolean' }
+    }
+    if (members.every((member) => (member.flags & ts.TypeFlags.StringLiteral) !== 0)) {
+        const values = members.map((member) => (member as ts.StringLiteralType).value)
+        return values.length === 1 ? { type: 'string', const: values[0] } : { enum: values }
+    }
+    const [onlyMember] = members
+    if (members.length === 1 && onlyMember !== undefined) {
+        return project(checker, onlyMember, seen)
+    }
+    seen.add(type)
+    const anyOf = members.map((member) => project(checker, member, seen))
+    seen.delete(type)
+    return { anyOf }
+}
+
+/* `T[]`/`readonly T[]` → `{ type: 'array', items: project(T) }`. */
+function projectArray(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    const element = checker.getTypeArguments(type as ts.TypeReference)[0]
+    seen.add(type)
+    const items = element === undefined ? {} : project(checker, element, seen)
+    seen.delete(type)
+    return { type: 'array', items }
+}
+
+/* `Set<T>`/`readonly Set<T>` → `{ type: 'array', items: project(T) }` — congruent with the
+   `wireJsonReplacer` encode (`[...set]`). */
+function projectSet(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    const element = checker.getTypeArguments(type as ts.TypeReference)[0]
+    seen.add(type)
+    const items = element === undefined ? {} : project(checker, element, seen)
+    seen.delete(type)
+    return { type: 'array', items }
+}
+
+/* `Map<K,V>`/`readonly Map<K,V>` → an array of `[K,V]` entry tuples — congruent with the
+   `wireJsonReplacer` encode (`[...map]`). Each entry is a fixed 2-tuple, so the item schema is
+   positional `prefixItems` with `items: false` to forbid extras (matching projectTuple). */
+function projectMap(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    const args = checker.getTypeArguments(type as ts.TypeReference)
+    seen.add(type)
+    const keySchema = args[0] === undefined ? {} : project(checker, args[0], seen)
+    const valueSchema = args[1] === undefined ? {} : project(checker, args[1], seen)
+    seen.delete(type)
+    return {
+        type: 'array',
+        items: { type: 'array', prefixItems: [keySchema, valueSchema], items: false },
+    }
+}
+
+/* A fixed-length tuple → positional `prefixItems`, `items: false` to forbid extras (JSON Schema
+   2020-12 / OpenAPI 3.1 tuple encoding). */
+function projectTuple(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    seen.add(type)
+    const prefixItems = checker
+        .getTypeArguments(type as ts.TypeReference)
+        .map((element) => project(checker, element, seen))
+    seen.delete(type)
+    return { type: 'array', prefixItems, items: false }
+}
+
+/*
+An object type → `{ type: 'object', properties, required }`. A property is required unless it is `?`
+optional or its type bears `undefined`. A string index signature (`Record<string, V>` / `{ [k]: V }`)
+becomes `additionalProperties: project(V)`. The `seen` guard short-circuits a self-referential type
+(a recursive tree node) to `{}` so it can't infinite-loop.
+*/
+function projectObject(
+    checker: ts.TypeChecker,
+    type: ts.Type,
+    seen: Set<ts.Type>,
+): Record<string, unknown> {
+    if (seen.has(type)) {
+        return {}
+    }
+    seen.add(type)
+    const properties: Record<string, unknown> = {}
+    const required: string[] = []
+    for (const symbol of checker.getPropertiesOfType(type)) {
+        const propertyType = typeOfProperty(checker, symbol)
+        const name = symbol.getName()
+        properties[name] = project(checker, propertyType, seen)
+        const optional =
+            (symbol.flags & ts.SymbolFlags.Optional) !== 0 || bearsUndefined(propertyType)
+        if (!optional) {
+            required.push(name)
+        }
+    }
+    const indexType = checker.getIndexTypeOfType(type, ts.IndexKind.String)
+    seen.delete(type)
+    const schema: Record<string, unknown> = { type: 'object' }
+    if (Object.keys(properties).length > 0) {
+        schema.properties = properties
+    }
+    if (required.length > 0) {
+        schema.required = required
+    }
+    if (indexType !== undefined) {
+        schema.additionalProperties = project(checker, indexType, seen)
+    }
+    return schema
+}
+
+/* A property symbol's type — from its declaration when it has one (the common case), else the
+   checker's symbol-level type (a synthesized/index property). */
+function typeOfProperty(checker: ts.TypeChecker, symbol: ts.Symbol): ts.Type {
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0]
+    return declaration === undefined
+        ? checker.getTypeOfSymbol(symbol)
+        : checker.getTypeOfSymbolAtLocation(symbol, declaration)
+}
+
+/* True when a property's type includes `undefined`/`void` — an implicit optional even without `?`. */
+function bearsUndefined(type: ts.Type): boolean {
+    if (type.isUnion()) {
+        return type.types.some((member) => (member.flags & OPTIONALITY_FLAGS) !== 0)
+    }
+    return (type.flags & OPTIONALITY_FLAGS) !== 0
+}
+
+/* A tuple is a TypeReference whose target (an ObjectType) carries the Tuple object flag. */
+function isTupleType(type: ts.Type): boolean {
+    const target = (type as ts.TypeReference).target as ts.ObjectType | undefined
+    return target !== undefined && (target.objectFlags & ts.ObjectFlags.Tuple) !== 0
+}

package/src/lib/shared/lenientDecode.ts

@@ -0,0 +1,15 @@
+/*
+Percent-decodes a URL-derived value, keeping the raw text on a malformed escape
+(`/%E0%A4%A`, `/%`) rather than throwing. Shared by matchRoute's param capture
+and createServer's internal-route names (socket names) so
+a bad escape in a navigation or request can't crash matching/dispatch — the
+downstream lookup just misses naturally on the raw text. Callers that must
+fail closed on a bad escape (the asset servers 404 instead) don't use this.
+*/
+export function lenientDecode(value: string): string {
+    try {
+        return decodeURIComponent(value)
+    } catch {
+        return value
+    }
+}