@abide/abide 0.43.0 → 0.44.0

package/src/lib/server/prompts/promptRegistry.ts

@@ -3,7 +3,7 @@ import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
 /*
 Process-wide registry of every prompt declared in the app. definePrompt
 inserts on first construction (eagerly when the registry loader walks the
-prompts manifest at MCP boot). The MCP server reads this to build its
+prompts manifest on first enumeration request). The MCP server reads this to build its
 `prompts/list` + `prompts/get` responses.
 */
 export const promptRegistry = new Map<string, PromptRegistryEntry>()

package/src/lib/server/prompts/types/Prompt.ts

@@ -2,7 +2,8 @@
 An MCP prompt declared by a markdown file under `src/mcp/prompts/`. The
 resolver plugin parses the file's frontmatter + body and generates a call
 to definePrompt, stamping in the `name` from the file path; `render(args)`
-interpolates the body's `{{name}}` placeholders into the single user
+interpolates the body's `{{name}}` placeholders and returns the rendered
+string; `renderPrompt` in mcpSurface.ts then wraps it as the single user
 message returned by `prompts/get`. Prompts are MCP-only — there is no
 client-side counterpart, so the shape carries no ClientFlags.
 */

package/src/lib/server/rpc/dispatchRpcInProcess.ts

@@ -7,8 +7,8 @@ import { runWithRequestScope } from '../runtime/runWithRequestScope.ts'
 Runs a rpc in-process: synthesizes the rpc Request from the remote's own
 method + url and pipes it through remote.fetch — the same handler/validation/
 error path the HTTP router uses, no network hop. The single in-process
-dispatch every consumer surface (the CLI client, the MCP tool dispatcher, and
-the test client) routes through, so they can't drift on how a rpc is invoked.
+dispatch every consumer surface (the CLI client and the MCP tool dispatcher)
+routes through, so they can't drift on how a rpc is invoked.
 Takes the RemoteFunction directly — invocation never reads the registry
 entry's schemas/clients (validation is closed over inside the remote), so the
 entry is not a dependency here. `baseUrl` gives the synthetic Request its

package/src/lib/server/rpc/types/RpcHelper.ts

@@ -34,7 +34,7 @@ type MutatingRpcOpts = RpcBaseOpts & {
 }
 
 /*
-Shared signature for every rpc helper (GET / POST / …). Three overloads:
+Shared signature for every rpc helper (GET / POST / …). Four overloads:
 
   - `Rpc(fn, { inputSchema, outputSchema?, clients? })` — `Args` infers
     from `InferInput<InputSchema>`, the handler receives

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

@@ -18,8 +18,8 @@ sources, picked at construction:
 
 Returns a server fn that resolves to `undefined` when no public file
 matches the request path, so the caller falls through to its own 404 /
-middleware path. The path-traversal guard mirrors serveStaticAsset's
-defence against encoded `..` segments in the raw URL.
+middleware path. The path-traversal guard uses the same `containsTraversal`
+check against encoded `..` segments in the raw URL.
 
 Async because disk mode globs `publicDir` once at construction to build a
 Set of the available paths: every page nav and RPC falls through here, so

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

@@ -36,7 +36,7 @@ function methodNotAllowed(allow: string): Response {
 
 /*
 Owns route dispatch: deciding, per registered URL, whether a request hits an
-rpc rpc, a page render, or nothing — and the method-matching that picks the
+an rpc, a page render, or nothing — and the method-matching that picks the
 status. Page URLs (under src/ui/pages/) serve GET/HEAD by rendering; rpc
 URLs (under src/server/rpc/, `/rpc/...`) dispatch to the single declared rpc,
 405 on method mismatch; an unregistered URL is 404. Page and rpc URLs are

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

@@ -481,6 +481,27 @@ export async function createServer({
                 /* Component hot module — the browser imports one edited `.abide`'s
                    hot build here instead of reloading (dev component HMR). */
                 if (clientFingerprint !== undefined && url.pathname.startsWith(DEV_HOT_PREFIX)) {
+                    /* This endpoint serves `application/javascript` for the browser's
+                       `import()`. A TOP-LEVEL NAVIGATION to it — clicking the module link in a
+                       stack trace, or opening the URL — would DOWNLOAD the file, since browsers
+                       can't render JS as a document. A navigation sends `Accept: text/html`;
+                       `import()` sends a wildcard Accept. Redirect a navigation back to a real
+                       page (the referring page when same-origin, else the mount root) so the
+                       error surfaces in context as a normal render instead of saving a file. */
+                    if ((req.headers.get('accept') ?? '').includes('text/html')) {
+                        const referer = req.headers.get('referer')
+                        const page =
+                            referer !== null &&
+                            URL.canParse(referer) &&
+                            new URL(referer).origin === url.origin &&
+                            !new URL(referer).pathname.startsWith(DEV_HOT_PREFIX)
+                                ? referer
+                                : base || '/'
+                        return new Response(null, {
+                            status: 302,
+                            headers: { Location: page, 'Cache-Control': NO_STORE },
+                        })
+                    }
                     return devHotModuleResponse(
                         decodeURIComponent(url.pathname.slice(DEV_HOT_PREFIX.length)),
                     )

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

@@ -1,10 +1,9 @@
 import { appNameSlot } from '../../shared/appNameSlot.ts'
 import { SSR_CACHE_CONTROL } from '../../shared/CACHE_CONTROL_VALUES.ts'
 import { formatTraceparent } from '../../shared/formatTraceparent.ts'
-import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
 import { layoutChainForRoute } from '../../shared/layoutChainForRoute.ts'
 import { safeJsonForScript } from '../../shared/safeJsonForScript.ts'
-import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import { snapshotShippable } from '../../shared/snapshotShippable.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
 import type { StreamedResolution } from '../../shared/types/StreamedResolution.ts'
 import { renderChain } from '../../ui/renderChain.ts'
@@ -23,6 +22,9 @@ type LoadPage = () => Promise<{ default: UiComponent }>
 
 const SSR_MARKER = /<!--ssr:(head|body|state)-->/g
 const BODY_MARKER = '<!--ssr:body-->'
+/* Compiled once — both fill the shell per page render. */
+const HEAD_STATE_MARKER = /<!--ssr:(head|state)-->/g
+const HEAD_CLOSE_TAG = /<\/head>/i
 
 function wantsJson(request: Request): boolean {
     return (request.headers.get('accept') ?? '').includes('application/json')
@@ -140,7 +142,7 @@ export function createUiPageRenderer({
        build-time injector). A no-op when there are none or the shell carries no </head>. */
     function injectRoutePreloads(html: string, routeUrl: string): string {
         const links = routePreloadLinks(routeUrl)
-        return links === '' ? html : html.replace(/<\/head>/i, `${links}</head>`)
+        return links === '' ? html : html.replace(HEAD_CLOSE_TAG, `${links}</head>`)
     }
 
     async function renderPage(
@@ -212,9 +214,7 @@ export function createUiPageRenderer({
             `<script>${SSR_SWAP_SCRIPT}${CACHE_RESOLVE_SCRIPT}</script>` +
             `${await stateTag(routeUrl, params, store, inline)}`
         const filled = injectRoutePreloads(
-            shell.replace(/<!--ssr:(head|state)-->/g, (_match, key: string) =>
-                key === 'head' ? head : '',
-            ),
+            shell.replace(HEAD_STATE_MARKER, (_match, key: string) => (key === 'head' ? head : '')),
             routeUrl,
         )
         const [before, after] = filled.split(BODY_MARKER)
@@ -245,11 +245,7 @@ export function createUiPageRenderer({
                            bundle, so startClient seeds the store and the block's subscription read
                            is warm. Skip keys already shipped inline in __SSR__. */
                         const streamedEntries = Array.from(store.cache.entries.values()).filter(
-                            (entry: CacheEntry) =>
-                                entry.settled === true &&
-                                entry.request !== undefined &&
-                                isReplayableMethod(entry.request.method.toUpperCase()) &&
-                                !inlinedKeys.has(entry.key),
+                            (entry) => snapshotShippable(entry) && !inlinedKeys.has(entry.key),
                         )
                         for await (const resolution of streamCacheResolutions(
                             store.cache,

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

@@ -3,8 +3,8 @@ import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
 
 /*
 The framework's CSRF refusal, shared by every same-origin gate — the socket
-upgrade, the socket REST publish face, the MCP endpoint, and mutating rpc
-rpcs — so the 403 body can't drift between surfaces. `hint` appends a
+upgrade, the socket REST publish face, the MCP endpoint, and mutating rpcs
+— so the 403 body can't drift between surfaces. `hint` appends a
 surface-specific remedy; rpc names its `crossOrigin: true` opt-out so the
 first developer this 403s can self-serve.
 */

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

@@ -6,7 +6,7 @@ import { isCrossOriginRequest } from './isCrossOriginRequest.ts'
 /*
 The framework's CSRF/CSWSH posture in one place: a cross-origin browser
 request to a mutating framework endpoint is refused. Every endpoint that
-parses bodies ignoring Content-Type (rpc rpcs, socket publish, MCP JSON-RPC)
+parses bodies ignoring Content-Type (rpcs, socket publish, MCP JSON-RPC)
 must gate here — a hostile page's text/plain form trick could otherwise
 smuggle a payload in with the visitor's ambient cookies; non-browser clients
 send no Origin and pass. Returns the 403 to send, or undefined to proceed.

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

@@ -11,8 +11,8 @@ mode — runtime sourced from `window.__abide`, self-invoking `hotReplace` — a
 transpiles the embedded author TypeScript to plain JS the browser can import
 directly (the normal pipeline relies on the bundler's `ts` loader for this). The
 browser imports this in place of a reload; on load it swaps the component's live
-instances. The id is guarded as a project-relative `.abide` under cwd; a bad or
-missing file 404s so the client falls back to a reload.
+instances. The id is guarded as a project-relative `.abide` under cwd; a bad
+module ID returns 400; a missing file 404s so the client falls back to a reload.
 */
 export async function devHotModuleResponse(moduleId: string): Promise<Response> {
     const root = process.cwd()

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

@@ -13,7 +13,7 @@ than `body instanceof ReadableStream`, since every bodied Response exposes one.
 A streamed SSR page (`text/html`) is deliberately not opted out: it inherits the
 configured `idleTimeout` as a bounded cap on how long it can hold the connection,
 and the client re-fetches any placeholder left unresolved by a cut stream (see
-flushUnresolvedPlaceholders). Non-stream responses pass through.
+streamCacheResolutions, which yields { key, miss } markers the client re-fetches). Non-stream responses pass through.
 */
 export function disableIdleTimeoutForStream(
     server: Server<unknown>,

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/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/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/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/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/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.

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
 }

package/src/lib/shared/createPushIterator.ts

@@ -1,5 +1,5 @@
 /*
-Single-slot-mailbox AsyncIterator factory shared by the in-process
+Bounded-queue AsyncIterator factory shared by the in-process
 socket fan-out (defineSocket) and the client-side ws proxy
 (socketProxy). Callers push values, signal end, signal an error, or
 signal a transport disconnect; the iterator drains a queue then awaits

package/src/lib/shared/decodeResponse.ts

@@ -1,3 +1,4 @@
+import { bodyValueForKind, DEFER } from './bodyValueForKind.ts'
 import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
 import { httpErrorFor } from './httpErrorFor.ts'
@@ -6,7 +7,7 @@ import { httpErrorFor } from './httpErrorFor.ts'
 Decodes a Response into the natural body value based on Content-Type:
   application/json (or `*\/+json`) → parsed JSON
   text/*                           → string
-  204 No Content / empty body      → undefined
+  204 No Content                   → undefined
   everything else                  → Blob
 
 Non-2xx responses throw HttpError so the happy path never has to check
@@ -39,11 +40,13 @@ export async function decodeResponse(response: Response): Promise<unknown> {
             `[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()`,
         )
     }
-    if (kind === 'json') {
-        return response.json()
-    }
-    if (kind === 'text') {
-        return response.text()
-    }
-    return response.blob()
+    /* json/text go through the shared mapping warmValueFromSnapshot also uses, so a warm
+       seed reads byte-identically to this live read; binary (the only DEFER kind left,
+       streaming already threw above) blobs. */
+    const value = bodyValueForKind(
+        kind,
+        () => response.json(),
+        () => response.text(),
+    )
+    return value === DEFER ? response.blob() : value
 }

package/src/lib/shared/hasReplayableRequest.ts

@@ -0,0 +1,17 @@
+import { isReplayableMethod } from './isReplayableMethod.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+
+/*
+Whether a cache entry carries a wire request that can be replayed from a warm
+snapshot — a replayable (GET-only) method, so the seed never re-fires a write or
+loses a body. Producer entries (no request) and write methods fail it.
+
+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 hasReplayableRequest(entry: CacheEntry): boolean {
+    return entry.request !== undefined && isReplayableMethod(entry.request.method.toUpperCase())
+}

package/src/lib/shared/html.ts

@@ -1,36 +1,17 @@
-const RAW_HTML = Symbol.for('abide.rawHtml')
+/* The registered brand for trusted raw markup. `Symbol.for` resolves through the
+   global registry, so this binding is the same symbol across module/bundle copies;
+   `html` (`abide/ui/html`) imports it to brand, `rawHtmlString` reads it back. */
+export const RAW_HTML = Symbol.for('abide.rawHtml')
 
 /* A value marked as trusted raw markup — a `{expr}` interpolation inserts it
    verbatim (not escaped) on both sides. The brand is a registered Symbol, so it
-   survives across module/bundle copies. */
+   survives across module/bundle copies. Branded by `html` (`abide/ui/html`); read
+   back by `rawHtmlString` here — the isomorphic reader both runtimes consume. */
 export type RawHtml = { readonly [RAW_HTML]: string }
 
-/*
-Marks a string as trusted raw HTML so a `{expr}` interpolation inserts its nodes
-instead of escaped text — the abide idiom for raw markup (no `{@html}` mustache).
-Works two ways:
-
-  html(trustedString)        // plain call — insert the string verbatim
-  html`<b>${name}</b>`       // tagged — concatenate parts verbatim
-
-Calling `html` is the explicit opt-in to raw insertion; plain `{value}` always
-escapes. The tag does NOT auto-escape interpolations (it's raw by intent), so only
-build markup from values you trust, or escape them yourself.
-*/
-// @documentation templating
-export function html(strings: TemplateStringsArray | string, ...values: unknown[]): RawHtml {
-    if (typeof strings === 'string') {
-        return { [RAW_HTML]: strings }
-    }
-    let markup = strings[0] ?? ''
-    for (let index = 0; index < values.length; index += 1) {
-        markup += String(values[index]) + (strings[index + 1] ?? '')
-    }
-    return { [RAW_HTML]: markup }
-}
-
 /* The raw markup of a `html`-branded value, or undefined for anything else
    (so text bindings can fast-path plain values and only branded ones go raw). */
+// @documentation plumbing
 export function rawHtmlString(value: unknown): string | undefined {
     return value !== null && typeof value === 'object' && RAW_HTML in value
         ? (value as RawHtml)[RAW_HTML]