@abide/abide 0.43.1 → 0.44.1

package/src/lib/server/runtime/gzipResponse.ts

@@ -1,17 +1,9 @@
-import { contentTypeOf } from '../../shared/contentTypeOf.ts'
-import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
+import type { ResponseBodyKind } from '../../shared/responseBodyKind.ts'
+import { responseBodyKind } from '../../shared/responseBodyKind.ts'
 import { acceptsGzip } from './acceptsGzip.ts'
 import { flushingGzipStream } from './flushingGzipStream.ts'
 import { STREAMED_HTML_HEADER } from './STREAMED_HTML_HEADER.ts'
 
-/*
-Compressible Content-Types — text and structured-text payloads. Binary or
-already-compressed bodies (images, fonts, archives, zstd/gzip blobs) gain
-nothing from a second pass and only burn CPU.
-*/
-const COMPRESSIBLE_TYPE =
-    /^(?:text\/|application\/(?:json|javascript|xml|[\w.-]+\+(?:json|xml))|image\/svg)/
-
 /*
 Gzips a dynamic response (SSR HTML, rpc/json replies, the plain 404) when the
 client accepts it. Static assets never reach here — they already carry a
@@ -23,6 +15,12 @@ expose a string body's length before send, and measuring would mean buffering th
 body — the framing overhead on the rare tiny body is negligible against
 compressing every page and rpc payload.
 
+`kind` is the body class the dispatch pipeline already computed (S2: classify
+once, thread it in) — only `compressible` bodies gzip; `streaming` and `opaque`
+pass through. Standalone callers (the health probe) omit it and it's derived
+here. The streamed-HTML marker is handled independent of `kind` since it's
+stripped even on a skip path.
+
 Buffered bodies take the web CompressionStream (best ratio, one flush at close).
 The streamed SSR document self-marks (STREAMED_HTML_HEADER) and takes a
 per-chunk-flushing gzip instead: the plain CompressionStream buffers the head
@@ -30,7 +28,7 @@ until its deflate window fills, which defeats streaming (the browser can't
 preload-scan the head or paint the pending shell until the stream nearly closes).
 The marker is stripped so it never reaches the client.
 */
-export function gzipResponse(req: Request, response: Response): Response {
+export function gzipResponse(req: Request, response: Response, kind?: ResponseBodyKind): Response {
     const streamedHtml = response.headers.has(STREAMED_HTML_HEADER)
     if (streamedHtml) {
         response.headers.delete(STREAMED_HTML_HEADER)
@@ -38,11 +36,11 @@ export function gzipResponse(req: Request, response: Response): Response {
     if (!response.body || response.headers.has('Content-Encoding')) {
         return response
     }
-    if (!acceptsGzip(req) || isStreamingResponse(response)) {
-        return response
-    }
-    const contentType = contentTypeOf(response.headers)
-    if (!COMPRESSIBLE_TYPE.test(contentType)) {
+    /* A streamed-HTML document classifies as `compressible` (text/html) but the
+       marker was already stripped above, so re-derive after the strip when the
+       pipeline didn't hand a kind in. */
+    const bodyKind = kind ?? responseBodyKind(response)
+    if (!acceptsGzip(req) || bodyKind !== 'compressible') {
         return response
     }
     const headers = new Headers(response.headers)

package/src/lib/server/runtime/logExposedSurfaces.ts

@@ -83,7 +83,7 @@ exposed on, so abide's routing and multimodal-by-default exposure are auditable
 rather than implicit. Three aligned tables — scan a column to spot a missing
 surface, a row to see one declaration's reach:
 
-  - pages: each route with the nearest layout and error boundary wrapping it.
+  - pages: each route key.
   - sockets: name + client surfaces (schema/browser/mcp/cli) and whether clients
     may publish.
   - rpcs: method+path (headed `http` since http/openapi are unconditional) +
@@ -95,9 +95,8 @@ then the surface columns, so the glyphs line up vertically across the tables.
 rpc folds its method into a left-aligned prefix of the identifier cell, so paths
 still start at a shared column. For sockets and rpcs the `schema`
 column leads: it's what unlocks the non-browser surfaces, so a missing schema
-reddens to flag the gated declaration. Loads the full registry, so it runs once
-at boot and only under `abide` debug logging (DEBUG=abide) to avoid forcing
-eager imports in production. Best-effort: enumeration failures are swallowed,
+reddens to flag the gated declaration. Loads the full registry. Runs once at boot; suppressed only via DEBUG=-abide
+(the always-on logging opt-out). Best-effort: enumeration failures are swallowed,
 this is diagnostic only.
 */
 export async function logExposedSurfaces(routing: { pages: Pages }): Promise<void> {

package/src/lib/server/runtime/runWithRequestScope.ts

@@ -120,7 +120,10 @@ export function runWithRequestScope(
                 })
             })
         }
-        if (response.body && isStreamingResponse(response)) {
+        /* Reuse the dispatch pipeline's single S2 classification when it stashed
+           one; callers that don't (mcp, the fetch fallback, tests) classify here. */
+        const streaming = store.responseStreaming ?? isStreamingResponse(response)
+        if (response.body && streaming) {
             /*
             A hand-pumped wrap rather than a TransformStream: streams typically
             end by client disconnect (an SSE tab closing), which cancels the

package/src/lib/server/runtime/serializeCacheSnapshot.ts

@@ -1,11 +1,11 @@
-import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
+import { snapshotShippable } from '../../shared/snapshotShippable.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
 import type { CacheStore } from '../../shared/types/CacheStore.ts'
 import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
 
 /*
 Snapshots the request-scoped cache for SSR at a single instant: every replayable
-(GET/DELETE) entry settled by now, serialized to a wire-safe CacheSnapshotEntry the
+(GET-only) entry settled by now, serialized to a wire-safe CacheSnapshotEntry the
 client seeds its store from. Unsettled and non-replayable entries are skipped; a body
 that can't ship (binary / streaming / rejected) drops out via snapshotEntryFromCache.
 
@@ -21,12 +21,7 @@ over the wire — see its post-stream `__abideResolve` pass. So for a streaming
 render-return snapshot is typically empty; the warm cache arrives over the stream.
 */
 export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshotEntry[]> {
-    const settled = Array.from(store.entries.values()).filter(
-        (entry) =>
-            entry.settled === true &&
-            entry.request !== undefined &&
-            isReplayableMethod(entry.request.method.toUpperCase()),
-    )
+    const settled = Array.from(store.entries.values()).filter(snapshotShippable)
     const snapshots = await Promise.all(
         settled.map((entry) => snapshotEntryFromCache(store, entry)),
     )

package/src/lib/server/runtime/snapshotEntryFromCache.ts

@@ -1,9 +1,10 @@
 import { contentTypeOf } from '../../shared/contentTypeOf.ts'
-import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
+import { hasReplayableRequest } from '../../shared/hasReplayableRequest.ts'
 import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
 import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
 import type { CacheStore } from '../../shared/types/CacheStore.ts'
+import type { ReplayableMethod } from '../../shared/types/ReplayableMethod.ts'
 
 /*
 Awaits one cache entry and turns it into a wire-safe snapshot, or undefined
@@ -25,14 +26,16 @@ export async function snapshotEntryFromCache(
     store: CacheStore,
     entry: CacheEntry,
 ): Promise<CacheSnapshotEntry | undefined> {
-    /* Producer entries have no wire request to replay — they never snapshot. */
-    if (!entry.request) {
-        return undefined
-    }
-    const method = entry.request.method.toUpperCase()
-    if (!isReplayableMethod(method)) {
+    /* The request half of the shared shippability gate: a replayable wire request.
+       Producer entries (no request) and non-replayable methods never snapshot — the
+       streaming-drain caller hands still-pending entries here, so `settled` is NOT gated
+       (the caller's snapshotShippable filter already required it for the entries it picks). */
+    if (!hasReplayableRequest(entry) || !entry.request) {
         return undefined
     }
+    /* `hasReplayableRequest` already verified the uppercased method is replayable; assert it
+       for the snapshot's typed `method` field rather than re-running the same Set check. */
+    const method = entry.request.method.toUpperCase() as ReplayableMethod
     const response = await readSettled(entry.promise as Promise<Response>)
     if (!response) {
         return undefined

package/src/lib/server/runtime/streamFromIterator.ts

@@ -4,7 +4,7 @@ import { messageFromError } from '../../shared/messageFromError.ts'
 Shared body builder for the streaming respond helpers (`jsonl`, `sse`).
 Both flow the same shape — pull from an AsyncIterator, encode each frame
 to bytes, emit a sentinel `error` frame on a generator throw, and route
-ReadableStream's `cancel` into `iter.return()` so the handler's
+ReadableStream's `cancel` into `iterator.return()` so the handler's
 `for await` exits via its normal control path. Only the per-frame
 encoding and the optional keepalive payload differ between the two.
 
@@ -85,7 +85,7 @@ export function streamFromIterator<T>(
             rejection from its cleanup: a `finally` that throws on `.return()`
             would otherwise surface as an unhandled rejection (process-fatal
             under Bun's default) on a client disconnect — a path every
-            sse/jsonl/resolve stream hits routinely.
+            sse/jsonl stream hits routinely.
             */
             return iterator.return?.(reason)?.then(
                 () => undefined,

package/src/lib/server/runtime/types/InspectorRpc.ts

@@ -1,6 +1,6 @@
 /*
-One RPC rpc projected for the inspector: the registry entry reduced to the
-serializable facts the UI renders — where it mounts, its method, which
+One declared RPC projected for the inspector: the registry entry reduced to
+the serializable facts the UI renders — where it mounts, its method, which
 non-browser surfaces advertise it, and its argument/result shapes as JSON
 Schema. Schemas project through jsonSchemaForSchema (same as MCP/OpenAPI), so
 a rpc whose library can't render a schema still lists with an opaque shape.

package/src/lib/server/runtime/types/RequestStore.ts

@@ -52,4 +52,20 @@ export type RequestStore = {
     carried no file parts.
     */
     files?: Record<string, File[]>
+    /*
+    The allowlisted headers forwarded onto in-process rpc Requests during this
+    request's SSR pass — derived once from the inbound headers (which don't change
+    within the scope) and reused by every defineRpc call. Each call clones it,
+    since buildRpcRequest mutates the Headers (content-type/ref-json) before
+    constructing the Request. Undefined until the first in-process rpc.
+    */
+    forwardedHeaders?: Headers
+    /*
+    The body class of the response the dispatch pipeline produced, stashed so
+    runWithRequestScope's closing-record stream monitor reuses the single S2
+    classification instead of re-deriving from the Content-Type. Undefined for
+    callers that don't classify (mcp, the fetch fallback, tests) — those fall
+    back to classifying the response themselves.
+    */
+    responseStreaming?: boolean
 }

package/src/lib/server/runtime/withResponseDefaults.ts

@@ -17,8 +17,13 @@ export function withResponseDefaults(
     status?: number,
 ): ResponseInit {
     const headers = new Headers(defaultHeaders)
-    new Headers(init?.headers).forEach((value, key) => {
-        headers.set(key, value)
-    })
+    /* The dominant case carries no overrides — skip the second Headers
+       allocation + per-key copy and ship the defaults alone. Only merge when
+       the caller actually supplied headers. */
+    if (init?.headers !== undefined) {
+        new Headers(init.headers).forEach((value, key) => {
+            headers.set(key, value)
+        })
+    }
     return { ...init, headers, ...(status !== undefined && { status }) }
 }

package/src/lib/server/socket.ts

@@ -6,7 +6,6 @@ import type { SocketOptions } from './sockets/types/SocketOptions.ts'
 Declares a Socket inside a file under `src/server/sockets/`. Each file contains
 exactly one export, named after the file (e.g. `chat.ts` →
 `export const chat = socket<ChatMessage>(...)`). The bundler reads the
-// @documentation sockets
 export name from the filename and the socket name from the file path
 under `src/server/sockets/`, then rewrites this call to bind the name into the
 runtime implementation (defineSocket on the server, socketProxy on the
@@ -21,6 +20,7 @@ to browser-only when schemaless, all surfaces when a schema is present.
 This function exists only for the type signature; calling it directly
 means the bundler plugin didn't process the file, which throws.
 */
+// @documentation sockets
 export function socket<Schema extends StandardSchemaV1>(
     opts: SocketOptions<Schema> & { schema: Schema },
 ): Socket<StandardSchemaV1.InferOutput<Schema>>

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -220,7 +220,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         }
         /*
         publish() runs the topic's optional Standard Schema synchronously
-        and throws on failure (see defineSocket.validateSync). The
+        and throws on failure (see validateSync in defineSocket.ts). The
         dispatcher invokes us via `void handlePub(...)`, so an unhandled
         throw would surface as an unhandled promise rejection on every
         malformed client frame. Catch + log so a buggy client can't take
@@ -317,7 +317,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             try {
                 /* ref-json from abide's own client; a non-abide client sends a plain-JSON
                    frame, which decodeRefJson rejects (a frame is always an object, never the
-                   `[root, slots]` envelope) — fall back to JSON.parse so raw WS clients work. */
+                   `[rootValue, slots]` envelope) — fall back to JSON.parse so raw WS clients work. */
                 try {
                     frame = decodeRefJson(text) as SocketClientFrame
                 } catch {

package/src/lib/server/sockets/defineSocket.ts

@@ -119,7 +119,11 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
             cachedServer = getActiveServer()
         }
         const server = cachedServer
-        if (server) {
+        /* Remote fan-out is the only consumer of the encoded frame: in-process iterators
+           already received the live object via notify() above. Skip the full message-graph
+           walk (encodeRefJson) + native publish when zero ws clients are subscribed to the
+           topic — subscriberCount is a cheap C-side check, encodeRefJson is not. */
+        if (server && server.subscriberCount(topic) > 0) {
             /* Typed against the shared wire contract so a `SocketServerFrame` change can't
                silently drift from this construction site (the dispatcher's `send` is already
                typed; this was the last `msg` frame built through an unchecked JSON.stringify). */

package/src/lib/server/sockets/socketRegistry.ts

@@ -3,7 +3,7 @@ import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
 /*
 Process-wide registry of every Socket declared in the app. defineSocket
 inserts on first construction; the dispatcher reads on every `sub` /
-`pub` frame so it can find the right Socket by name and check the
-opted-in `allowClientPublish` policy.
+`pub` frame and every REST request so it can find the right Socket by
+name and check the opted-in `allowClientPublish` policy.
 */
 export const socketRegistry = new Map<string, SocketRegistryEntry>()

package/src/lib/server/sockets/types/SocketClientFrame.ts

@@ -9,9 +9,9 @@ the dispatcher checks the topic's `clientPublish` flag before fanning
 out.
 
 `sub` is the per-subscription id minted client-side; the server treats
-it as opaque and routes inbound `msg|err|end` frames back to the same
-id so one ws can multiplex many subscriptions to the same or different
-sockets.
+it as opaque and routes inbound `replay|err|end` frames back to the same
+id — `msg` frames are broadcast keyed by socket name; the client
+demuxes them against every local sub for that socket.
 */
 export type SocketClientFrame =
     | { type: 'sub'; sub: string; socket: string; replay?: number }

package/src/lib/shared/CACHE_WRAPPED.ts

@@ -2,7 +2,8 @@
 Brand on the invoker cache() returns; its property value is the wrapped fn,
 so inspection shows what a wrapper wraps. Detection is certain (set by us,
 never heuristic), which is why misuse throws instead of warning: a wrapper
-used as a selector matches nothing (no url/method, no producer id), and a
-re-wrapped wrapper silently downgrades a remote to an anonymous producer.
+used as a selector matches nothing (no url/method, no producer id), and
+without detection a re-wrapped wrapper would silently downgrade a remote to
+an anonymous producer (no url/method, no shared key, no SSR snapshot).
 */
 export const CACHE_WRAPPED: unique symbol = Symbol('abide.cacheWrapped')

package/src/lib/shared/REMOTE_FUNCTION.ts

@@ -3,6 +3,6 @@ Brand set by createRemoteFunction on both the decoded callable and its raw
 sibling — the exact answer to "is this a abide remote?" where structural
 checks ('url' in fn) would misclassify any user function that happens to
 carry a url property. Read by cache()'s remote/producer discriminator,
-selectorMatcher's identity branch, and the route dispatcher's export scan.
+selectorPrefix's identity branch, and the route dispatcher's export scan.
 */
 export const REMOTE_FUNCTION: unique symbol = Symbol('abide.remoteFunction')

package/src/lib/shared/RPC_ARGS_TYPE.ts

@@ -0,0 +1,7 @@
+/*
+The `RpcArgs<Fn>` type alias both rpc d.ts writers emit verbatim: it lifts the
+args type out of a RemoteFunction, dropping the FormData upload variant so a
+url()/test-client call types against the rpc's plain args.
+*/
+export const RPC_ARGS_TYPE =
+    'type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never'

package/src/lib/shared/STREAMING_CONTENT_TYPES.ts

@@ -1,8 +1,9 @@
 /*
 Content-Type prefixes abide treats as streaming bodies — SSE for the
 `sse()` helper, JSONL / NDJSON for the `jsonl()` helper. Used by
-decodeResponse to refuse a buffered decode and by streamResponse to
-choose the frame parser.
+contentBodyKind (called by decodeResponse and the one-shot path in
+streamResponse) to classify content, and by streamResponse to select the
+JSONL frame parser.
 */
 export const STREAMING_CONTENT_TYPES = [
     'text/event-stream',

package/src/lib/shared/activeCacheStore.ts

@@ -1,20 +1,11 @@
-import { cacheStoreSlot } from './cacheStoreSlot.ts'
-import { createCacheStore } from './createCacheStore.ts'
+import { cacheStoreResolver } from './cacheStoreResolver.ts'
 import type { CacheStore } from './types/CacheStore.ts'
 
 /*
-Resolves the active CacheStore. The runtime is registered via
-`setCacheStoreResolver` from the server entry (request-scoped via ALS)
-or the client entry (module-level singleton). If no resolver is registered,
-a single fallback store is created lazily so isolated tests still work.
+Resolves the active CacheStore: the registered resolver's store, or a single
+lazily-created fallback when none is registered (so isolated tests work). The
+fallback creator guarantees a value, hence the non-null assertion.
 */
 export function activeCacheStore(): CacheStore {
-    const fromResolver = cacheStoreSlot.resolver?.()
-    if (fromResolver) {
-        return fromResolver
-    }
-    if (!cacheStoreSlot.fallback) {
-        cacheStoreSlot.fallback = createCacheStore()
-    }
-    return cacheStoreSlot.fallback
+    return cacheStoreResolver.get()!
 }

package/src/lib/shared/activePage.ts

@@ -1,25 +1,11 @@
-import { pageSlot } from './pageSlot.ts'
+import { pageResolver } from './pageResolver.ts'
 import type { PageSnapshot } from './types/PageSnapshot.ts'
 
 /*
-Resolves the active page snapshot. The runtime is registered via
-`setPageResolver` from the server entry (request-scoped via ALS) or the
-client entry (module-level singleton). If no resolver is registered, a single
-fallback snapshot is created lazily so isolated tests still work. Mirrors
-activeCacheStore.
+Resolves the active page snapshot: the registered resolver's snapshot, or a
+single lazily-created empty snapshot when none is registered (so isolated tests
+work). The fallback creator guarantees a value, hence the non-null assertion.
 */
 export function activePage(): PageSnapshot {
-    const fromResolver = pageSlot.resolver?.()
-    if (fromResolver) {
-        return fromResolver
-    }
-    if (!pageSlot.fallback) {
-        pageSlot.fallback = {
-            route: '',
-            params: {},
-            url: new URL('http://localhost/'),
-            navigating: false,
-        }
-    }
-    return pageSlot.fallback
+    return pageResolver.get()!
 }

package/src/lib/shared/augmentModule.ts

@@ -0,0 +1,18 @@
+/*
+Emits one `declare module '<module>' { interface <iface> { … } }` block, the
+module-augmentation shape every codegen writer (routes, rpc, publicAssets,
+testRpc, testSockets) shares. `entries` is `[key, type]` pairs already in final
+order; each becomes an 8-space-indented `"key": type` member, the indentation
+the consumer src tsconfig include expects. Returns the block body only — the
+writeDts envelope adds banner + footer.
+*/
+export function augmentModule(module: string, iface: string, entries: [string, string][]): string {
+    const members = entries
+        .map(([key, type]) => `        ${JSON.stringify(key)}: ${type}`)
+        .join('\n')
+    return `declare module '${module}' {
+    interface ${iface} {
+${members}
+    }
+}`
+}

package/src/lib/shared/basePath.ts

@@ -1,10 +1,11 @@
-import { baseSlot } from './baseSlot.ts'
+import { baseResolver } from './baseResolver.ts'
 
 /*
-The current mount base path ('' at root). Resolved per side: the server
-installs an APP_URL-derived resolver at boot, the client one reading
-window.__SSR__.base. url() reads this to prefix rooted internal paths.
+The current mount base path ('' at root). Resolved per side: the server installs
+an APP_URL-derived resolver at boot, the client one reading window.__SSR__.base.
+url() reads this to prefix rooted internal paths. Defaults to '' when no resolver
+or fallback is set.
 */
 export function basePath(): string {
-    return baseSlot.resolver?.() ?? baseSlot.fallback ?? ''
+    return baseResolver.get() ?? ''
 }

package/src/lib/shared/baseResolver.ts

@@ -0,0 +1,10 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+
+/*
+The mount-base slot/resolver/reader bundle. The server entry installs an
+APP_URL-derived resolver at boot; the client entry one reading
+window.__SSR__.base. No lazy fallback creator — `fallback` is a plain string set
+directly by isolated tests, and basePath() supplies the '' default. baseSlot /
+basePath re-export the slot and reader; setBaseResolver the setter.
+*/
+export const baseResolver = createResolverSlot<string>()

package/src/lib/shared/baseSlot.ts

@@ -1,14 +1,8 @@
+import { baseResolver } from './baseResolver.ts'
+
 /*
-Internal slot the runtime entries register their mount-base resolver into.
-The server entry installs an APP_URL-derived resolver at boot; the client
-entry installs one reading window.__SSR__.base. `fallback` is a single value
-used only when no resolver is registered — lets isolated tests set a base
-without spinning up the runtime. Mirrors pageSlot / cacheStoreSlot.
+Internal slot the runtime entries register their mount-base resolver into (see
+baseResolver). Exposed so test helpers snapshot/poke `.resolver` and `.fallback`
+directly.
 */
-export const baseSlot: {
-    resolver: (() => string) | undefined
-    fallback: string | undefined
-} = {
-    resolver: undefined,
-    fallback: undefined,
-}
+export const baseSlot = baseResolver.slot

package/src/lib/shared/bodyValueForKind.ts

@@ -0,0 +1,35 @@
+import type { ContentBodyKind } from './contentBodyKind.ts'
+
+/*
+The single body-kind → value mapping shared by the live read (decodeResponse) and
+the synchronous warm read (warmValueFromSnapshot), so neither can disagree about
+which kind yields what — the divergence behind the streaming-guard-in-one-but-not-
+the-other bug.
+
+Generic over the extraction (`Value`) so both async and sync callers reuse it:
+the live read passes Promise-returning accessors (response.json()/text()) and
+handles the deferred kinds (streaming → throw, binary → blob); the warm read
+passes sync accessors (JSON.parse(body)/body) and treats every deferred kind as
+no-warm-value, leaving the live async path to throw/blob exactly as a fresh call
+would. The json/text branches — the only kinds that produce a directly-usable
+value on both sides — are decided here, once.
+
+Returns the DEFER sentinel for `streaming` and `binary`: kinds whose handling is
+side-specific (the live read throws on streaming and blobs on binary; the warm
+read has no synchronous equivalent for either), so the caller branches on it.
+*/
+export const DEFER: unique symbol = Symbol('defer')
+
+export function bodyValueForKind<Value>(
+    kind: ContentBodyKind,
+    json: () => Value,
+    text: () => Value,
+): Value | typeof DEFER {
+    if (kind === 'json') {
+        return json()
+    }
+    if (kind === 'text') {
+        return text()
+    }
+    return DEFER
+}

package/src/lib/shared/cache.ts

@@ -92,7 +92,7 @@ request-scoped on the server, which keeps per-user data from leaking across
 requests; on the client there is one tab store either way, so it is a no-op.
 
 Reactivity is implicit: the invoker calls `store.subscribe(key)`, which
-registers the surrounding $derived / $effect scope. Invalidating the key
+registers the surrounding scope().computed() / scope().effect() scope. Invalidating the key
 then re-runs that scope, which calls cache() again and gets a fresh entry.
 Outside a tracking scope subscribe() is a no-op, so cache() works the same
 in server code and plain client code.
@@ -199,7 +199,7 @@ export function cache<Args, Return>(
         fetch hands each reader a fresh object; cloning keeps warm reads the same.
         */
         if (!isRaw && existing?.value !== undefined) {
-            return Promise.resolve(structuredClone(existing.value)) as Promise<Return>
+            return Promise.resolve(cloneWarmValue(existing.value)) as Promise<Return>
         }
         const responsePromise = invokeRemote(
             store,
@@ -216,6 +216,26 @@ export function cache<Args, Return>(
     return read
 }
 
+/*
+Deep-copies a warm value so each reader gets its own mutable object — the
+no-shared-mutation invariant the warm path turns on (a live fetch hands every
+reader a fresh object; a warm read must match). A warm value only ever comes
+from the json or text body kinds (bodyValueForKind): json yields JSON.parse
+output and text yields a string, so the whole population is JSON-round-trippable
+by construction — no Date/Map/Blob/cycle a structuredClone would be needed for.
+A primitive (string/number/boolean from a text or scalar-json body) is immutable,
+so it is returned as-is with no copy. An object/array goes through a JSON
+round-trip, ~2x faster than structuredClone for this exact shape (measured:
+773µs→516µs on a 149KB list, 3.4ms→1.7ms on 474KB) while producing the same
+fresh, mutable, isomorphic-with-a-cold-read copy.
+*/
+function cloneWarmValue(value: unknown): unknown {
+    if (typeof value !== 'object' || value === null) {
+        return value
+    }
+    return JSON.parse(JSON.stringify(value))
+}
+
 /*
 Normalises the `swr` option to its window, or undefined when off. `true` (or
 `{}`) is stale-while-revalidate with no window — refetch immediately on every

package/src/lib/shared/cacheEntryFromSnapshot.ts

@@ -1,3 +1,4 @@
+import { bodyValueForKind, DEFER } from './bodyValueForKind.ts'
 import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
@@ -32,31 +33,35 @@ export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
 
 /*
 Synchronously decodes a snapshot body so the warm entry reads without a
-microtask hop on first render. A strict subset of `decodeResponse`: it warms
-only the `json`/`text` kinds (the same `contentBodyKind` the live read switches
-on, so the two cannot disagree about a body), returning a value identical to
-what awaiting the Response would yield. Every other kind — non-2xx, 204,
-streaming, binary — yields no warm value and defers to the async path, which
-throws HttpError / returns the streaming error / blobs exactly as a live call
-would.
+microtask hop on first render. The json/text branches go through the shared
+`bodyValueForKind` — the same mapping the live read (`decodeResponse`) uses — so
+the two cannot disagree about how a body becomes a value, returning a value
+identical to what awaiting the Response would yield. Every non-warmable case —
+non-2xx, 204 (the status gate below), streaming, binary (the DEFER sentinel) —
+yields no warm value and defers to the async path, which throws HttpError /
+returns the streaming error / blobs exactly as a live call would.
 */
 function warmValueFromSnapshot(status: number, headers: Headers, body: string): unknown {
+    /* Status gate is side-specific: an error/204 has no warm value here, but the live
+       read throws HttpError / returns undefined for the same status — so it stays out of
+       the shared kind mapping. */
     if (status === 204 || status < 200 || status >= 300) {
         return undefined
     }
     const kind = contentBodyKind(contentTypeOf(headers))
-    if (kind === 'json') {
+    const value = bodyValueForKind(
+        kind,
         /* The body may still be malformed JSON; fall back to the async path rather than
            throwing a SyntaxError synchronously during hydration. */
-        try {
-            return JSON.parse(body)
-        } catch {
-            return undefined
-        }
-    }
-    if (kind === 'text') {
-        return body
-    }
+        () => {
+            try {
+                return JSON.parse(body)
+            } catch {
+                return undefined
+            }
+        },
+        () => body,
+    )
     /* streaming and binary defer to the async path (the live decode throws / blobs). */
-    return undefined
+    return value === DEFER ? undefined : value
 }