@abide/abide 0.43.1 → 0.44.1

package/src/lib/bundle/probeAbideServer.ts

@@ -10,7 +10,7 @@ Confirms a URL points at a abide server before the launcher navigates the app
 window there, by fetching its unauthenticated health endpoint. Returns the
 server's identity on success, or undefined when nothing abide answers — a network
 error, the wrong port, or a non-abide page (a bare 403/404, a different app, a
-captive portal's 200 — hence the `abide: true` body check, never response.ok
+captive portal's 200 — hence the `abide: true` (or version string) body check, never response.ok
 alone). The endpoint bypasses the app's own middleware, so an auth-guarded abide
 app still verifies here even though its pages would later redirect to a login.
 Probes HEALTH_PATH first, falling back to the IDENTITY_PATH alias so a newer

package/src/lib/cli/parseArgvForRpc.ts

@@ -1,3 +1,5 @@
+import { tokenizeArgvFlags } from './tokenizeArgvFlags.ts'
+
 /*
 Parses an argv tail into the JSON args bag for an RPC. The JSON Schema
 on the manifest entry (when present) drives flag typing:
@@ -9,8 +11,10 @@ on the manifest entry (when present) drives flag typing:
 
 For complex shapes (nested objects, unions, anyOf) the CLI exposes
 `--json <stringified-args>` as an escape hatch that supplies the whole
-args bag verbatim. Stdin: if a JSON object arrives piped in, it's used
-as the full args bag (flags layer on top).
+args bag verbatim. Stdin: if a JSON object arrives piped in with no argv flags, it is used
+as the full args bag. Stdin and flags are mutually exclusive — stdin is
+skipped when argv is non-empty to avoid hanging on a pipe that never
+sends EOF.
 
 Unrecognised flags throw — early loud feedback is more useful than
 silent drops.
@@ -45,44 +49,39 @@ export async function parseArgvForRpc(
         }
     }
 
-    for (let index = 0; index < argv.length; index++) {
-        const token = argv[index] as string
-        if (token === '--json') {
-            const next = argv[++index]
-            if (!next) {
+    /* The shared tokenizer owns the flag-consumption grammar (boolean / inline /
+       `--json` / `--no-` negation). This loop layers RPC value semantics on each
+       yielded token: JSON-blob merge, Number coercion, array accumulation. */
+    for (const token of tokenizeArgvFlags(argv, jsonSchema)) {
+        if (token.positional !== undefined) {
+            throw new Error(`unexpected positional argument: ${token.positional}`)
+        }
+        if (token.isJson) {
+            if (token.missingValue || token.value === undefined) {
                 throw new Error('--json requires a value')
             }
-            const parsed = JSON.parse(next)
+            const parsed = JSON.parse(token.value)
             if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
                 throw new Error('--json value must be a JSON object')
             }
             Object.assign(args, parsed)
             continue
         }
-        if (!token.startsWith('--')) {
-            throw new Error(`unexpected positional argument: ${token}`)
+        // The tokenizer treats `--help` / `-h` as a help token; in RPC parsing
+        // they are an unrecognised flag, surfaced loudly like any other.
+        if (token.isHelp || token.name === undefined) {
+            throw new Error('unexpected --help flag')
         }
-        const stripped = token.slice('--'.length)
-        const [literalName, eqValue] = stripped.includes('=')
-            ? [stripped.slice(0, stripped.indexOf('=')), stripped.slice(stripped.indexOf('=') + 1)]
-            : [stripped, undefined]
-        /* `--no-x` negates only a known boolean property x; otherwise the literal
-           name wins, so a property legitimately named `no-…` stays reachable. */
-        const negatedName = literalName.startsWith('no-')
-            ? literalName.slice('no-'.length)
-            : undefined
-        const isNegated = negatedName !== undefined && properties[negatedName]?.type === 'boolean'
-        const name = isNegated ? (negatedName as string) : literalName
-        const prop = properties[name]
-        const propType = prop?.type
+        const name = token.name
+        const propType = properties[name]?.type
         if (propType === 'boolean') {
-            args[name] = !isNegated
+            args[name] = !token.negated
             continue
         }
-        const value = eqValue ?? argv[++index]
-        if (value === undefined) {
+        if (token.missingValue || token.value === undefined) {
             throw new Error(`--${name} requires a value`)
         }
+        const value = token.value
         if (propType === 'number' || propType === 'integer') {
             // Reject a blank value explicitly — `Number('')` / `Number('  ')` is 0,
             // not NaN, so the NaN guard alone would silently coerce it to zero.

package/src/lib/cli/runCli.ts

@@ -9,6 +9,7 @@ import { printTrimmed } from './printTrimmed.ts'
 import { resolveCliTarget } from './resolveCliTarget.ts'
 import { runSession } from './runSession.ts'
 import { startLocalInstance } from './startLocalInstance.ts'
+import { tokenizeArgvFlags } from './tokenizeArgvFlags.ts'
 import type { CliManifest } from './types/CliManifest.ts'
 import type { CliTarget } from './types/CliTarget.ts'
 
@@ -16,37 +17,21 @@ const isHelpFlag = (arg: string): boolean => arg === '--help' || arg === '-h'
 
 /*
 Whether a command's argv tail genuinely requests help, i.e. a help flag appears
-at a flag position rather than as the value of a value-expecting flag. Mirrors
-parseArgvForRpc's flag rule: boolean props (and `--name=…`) consume no following
-token, everything else consumes the next token as its value — so `--title --help`
-passes `--help` as the title value, not a help request.
+at a flag position rather than as the value of a value-expecting flag. Shares
+tokenizeArgvFlags' grammar with parseArgvForRpc so the two can't drift: the
+tokenizer applies the flag-consumption rule (boolean / `--name=…` / `--json`
+consume their value), so a `--help` that was a flag's value is already swallowed
+and never surfaces as a help token — `--title --help` passes `--help` as the
+title value, not a help request.
 */
 function commandArgvRequestsHelp(
     argvTail: string[],
     jsonSchema: Record<string, unknown> | undefined,
 ): boolean {
-    const properties =
-        (jsonSchema?.properties as Record<string, { type?: string }> | undefined) ?? {}
-    for (let index = 0; index < argvTail.length; index += 1) {
-        const token = argvTail[index] as string
-        if (isHelpFlag(token)) {
+    for (const token of tokenizeArgvFlags(argvTail, jsonSchema)) {
+        if (token.isHelp) {
             return true
         }
-        if (!token.startsWith('--')) {
-            continue
-        }
-        if (token === '--json') {
-            index += 1 // consumes its value
-            continue
-        }
-        const rawName = token.slice('--'.length)
-        if (rawName.includes('=')) {
-            continue // inline value, consumes no following token
-        }
-        const name = rawName.startsWith('no-') ? rawName.slice('no-'.length) : rawName
-        if (properties[name]?.type !== 'boolean') {
-            index += 1 // a value-expecting flag consumes the next token
-        }
     }
     return false
 }

package/src/lib/cli/tokenizeArgvFlags.ts

@@ -0,0 +1,84 @@
+/*
+The single argv-tail flag grammar shared by help-detection (runCli) and RPC arg
+parsing (parseArgvForRpc) so the two can never drift. Walks the tail and yields
+one token per flag occurrence, honouring the schema-driven consumption rule:
+
+  - `--help` / `-h`               → { isHelp: true }, consumes no following token
+  - `--json <blob>`               → { isJson: true, value }, consumes the next token
+                                     (the value is the verbatim JSON args bag)
+  - boolean props (and `--no-x`)  → { name, value: undefined }, consumes no token
+  - `--name=value`                → { name, value }, inline, consumes no token
+  - everything else               → { name, value }, consumes the next token
+
+`--no-x` negates only a known boolean property x; otherwise the literal `no-…`
+name is kept so a property legitimately named `no-…` stays reachable. Reports
+`negated` and `missingValue` so the parser can apply boolean/coercion semantics
+and throw precise errors. A bare positional (no leading `--`) yields
+{ positional: token } so each consumer rejects or ignores it as it sees fit.
+
+Pure; reads the schema's `properties` only to classify boolean props.
+*/
+export function* tokenizeArgvFlags(
+    argvTail: string[],
+    jsonSchema: Record<string, unknown> | undefined,
+): Generator<{
+    isHelp?: boolean
+    isJson?: boolean
+    positional?: string
+    name?: string
+    value?: string
+    negated?: boolean
+    missingValue?: boolean
+}> {
+    const properties =
+        (jsonSchema?.properties as Record<string, { type?: string }> | undefined) ?? {}
+    for (let index = 0; index < argvTail.length; index += 1) {
+        const token = argvTail[index] as string
+        if (token === '--help' || token === '-h') {
+            yield { isHelp: true }
+            continue
+        }
+        if (!token.startsWith('--')) {
+            yield { positional: token }
+            continue
+        }
+        // `--json <blob>`: the next token is the verbatim JSON args bag.
+        if (token === '--json') {
+            const value = argvTail[index + 1]
+            if (value === undefined) {
+                yield { isJson: true, missingValue: true }
+            } else {
+                index += 1
+                yield { isJson: true, value }
+            }
+            continue
+        }
+        const stripped = token.slice('--'.length)
+        const [literalName, inlineValue] = stripped.includes('=')
+            ? [stripped.slice(0, stripped.indexOf('=')), stripped.slice(stripped.indexOf('=') + 1)]
+            : [stripped, undefined]
+        /* `--no-x` negates only a known boolean property x; otherwise the literal
+           name wins, so a property legitimately named `no-…` stays reachable. */
+        const negatedName = literalName.startsWith('no-')
+            ? literalName.slice('no-'.length)
+            : undefined
+        const negated = negatedName !== undefined && properties[negatedName]?.type === 'boolean'
+        const name = negated ? (negatedName as string) : literalName
+        // Boolean props and inline `--name=value` consume no following token.
+        if (properties[name]?.type === 'boolean') {
+            yield { name, negated }
+            continue
+        }
+        if (inlineValue !== undefined) {
+            yield { name, value: inlineValue }
+            continue
+        }
+        const value = argvTail[index + 1]
+        if (value === undefined) {
+            yield { name, missingValue: true }
+        } else {
+            index += 1
+            yield { name, value }
+        }
+    }
+}

package/src/lib/cli/types/CliManifest.ts

@@ -1,9 +1,11 @@
 import type { CliManifestEntry } from './CliManifestEntry.ts'
 
 /*
-Map from rpc export-name (e.g. "getReport") to its manifest entry. Built
-by the bundler from the same rpcRegistry MCP consumes; entries are
-emitted only for rpcs with `clients.cli: true`. The CLI binary and any
-programmatic createClient caller read this to dispatch calls.
+Map from command name (URL-derived via commandNameForUrl, e.g. "getReport"
+or "users-list") to its manifest entry. Built by the bundler from
+rpcRegistry and socketRegistry; entries are emitted for rpcs and sockets
+with `clients.cli: true`. Sockets produce `<base>-tail` (and `-publish`
+when `allowClientPublish` is set). The CLI binary and any programmatic
+createClient caller read this to dispatch calls.
 */
 export type CliManifest = Record<string, CliManifestEntry>

package/src/lib/mcp/annotationsForMethod.ts

@@ -2,7 +2,7 @@ import type { HttpMethod } from '../shared/types/HttpMethod.ts'
 
 /*
 Maps an HTTP method to MCP tool annotations so a model can tell a read from
-a write before calling. Abide derives these from the rpc the RPC was
+a write before calling. Abide derives these from the HTTP method the RPC was
 declared with rather than asking the author to repeat the intent:
   - GET / HEAD  → read-only, non-destructive
   - POST        → creates; not idempotent, not (necessarily) destructive

package/src/lib/mcp/toolResultFromResponse.ts

@@ -15,7 +15,7 @@ function asText(value: unknown): string {
 }
 
 /*
-Turns an rpc/socket Response into an MCP `tools/call` result. Always
+Turns an RPC Response into an MCP `tools/call` result. Always
 carries a `text` content block for backward compatibility; adds
 `structuredContent` (an object, per the MCP spec) so models that
 understand structured output get the typed value instead of a stringified

package/src/lib/mcp/types/JsonRpcRequest.ts

@@ -1,8 +1,8 @@
 /*
 JSON-RPC 2.0 request frame as MCP delivers it over Streamable HTTP. The
-`id` is absent for notifications (which we don't currently receive from
-clients but accept silently). `method` is a string like "tools/list" or
-"resources/read".
+`id` is absent for notifications; they are dispatched for their side effect
+and acknowledged with a 202 (JSON-RPC forbids replying with an envelope).
+`method` is a string like "tools/list" or "resources/read".
 */
 export type JsonRpcRequest = {
     jsonrpc: '2.0'

package/src/lib/server/AppModule.ts

@@ -10,7 +10,7 @@ WebSockets are not exposed here — abide's only native WebSocket
 surface is the sockets hub (see `abide/server/socket`), multiplexed onto a
 single framework-owned connection per client at `/__abide/sockets`.
 Inside request scopes, the live Bun.Server is reachable via the
-exported `server()` function from `abide/server`; `init` receives it
+exported `server()` function from `abide/server/server`; `init` receives it
 explicitly because it runs outside a request.
 */
 // @documentation plumbing

package/src/lib/server/cli/handleCliDownload.ts

@@ -92,12 +92,14 @@ async function computeBinary(
 }
 
 /*
-Handles GET /__abide/cli/<platform> — streams a gzipped tarball
-containing the platform-specific thin binary + a `.env` carrying
-ABIDE_APP_URL (and ABIDE_APP_TOKEN if the inbound request was authenticated).
+Handles GET /__abide/cli/<platform> — streams a gzipped tarball containing
+the platform-specific thin binary, the sibling server binary, and a `.env`
+carrying ABIDE_APP_URL (and ABIDE_APP_TOKEN if the inbound request was
+authenticated).
 
-Thin binaries live at `dist/cli-thin/<platform>/<programName>`
-(produced by `abide cli` with ABIDE_APP_URL set). Missing platforms produce
+Thin binaries live at `dist/cli-thin/<platform>/<programName>` (produced
+lazily by `buildCli` on first request). The `.env` baking `ABIDE_APP_URL`
+is generated at download time, not build time. Missing platforms produce
 404 — the install script reports it, doesn't try to fall back.
 */
 export async function handleCliDownload(

package/src/lib/server/cli/installScript.ts

@@ -7,9 +7,9 @@ platform-specific tarball and extracts it into `$ABIDE_INSTALL_DIR`
 (default `~/.local/bin`). The tarball already contains the `.env` next
 to the binary — no separate config write step in the script.
 
-The script is rendered server-side so `<ABIDE_APP_URL>` is the request's own
-origin and the embedded curl URL needs no escaping or quoting beyond
-basic shell hygiene.
+The script is rendered server-side so the request origin is baked into the
+`URL` variable at generation time and the embedded curl URL needs no escaping
+or quoting beyond basic shell hygiene.
 */
 export function installScript(appUrl: string, programName: string): string {
     return `#!/usr/bin/env sh

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

@@ -100,7 +100,15 @@ export function defineRpc<Args, Return>(
     function buildRequest(args: Args | undefined): Request {
         const store = requestContext.getStore()
         const baseUrl = store ? store.url.href : 'http://localhost/'
-        const headers = store ? forwardHeaders(store.req.headers) : new Headers()
+        /* The forwarded allowlist is request-invariant — derive it once per scope
+           and clone per call (buildRpcRequest mutates the Headers). */
+        let headers: Headers
+        if (store) {
+            store.forwardedHeaders ??= forwardHeaders(store.req.headers)
+            headers = new Headers(store.forwardedHeaders)
+        } else {
+            headers = new Headers()
+        }
         return buildRpcRequest({ method, url, args, baseUrl, headers })
     }
 

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

@@ -17,6 +17,7 @@ import { isDebugNegated } from '../../shared/isDebugNegated.ts'
 import { logClosingRecord } from '../../shared/logClosingRecord.ts'
 import { OFFLINE_HEADER } from '../../shared/OFFLINE_HEADER.ts'
 import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+import { responseBodyKind } from '../../shared/responseBodyKind.ts'
 import { SOCKETS_PATH } from '../../shared/SOCKETS_PATH.ts'
 import { setAppName } from '../../shared/setAppName.ts'
 import { setBaseResolver } from '../../shared/setBaseResolver.ts'
@@ -242,8 +243,11 @@ export async function createServer({
     isn't installed. Resolved at boot so the fetch route below can branch on it.
     */
     const inspectorHandler = await maybeMountInspector({ name: appName, version: appVersion })
-    /* Built on first request, then reused — the rpc registry is frozen after load. */
-    let openApiSpec: ReturnType<typeof buildOpenApiSpec> | undefined
+    /* Built on first request, then reused — the rpc registry is frozen after load.
+       Memoised as a promise so two concurrent cold requests share one build instead
+       of both building (the second otherwise clobbering the first). A rejected build
+       clears the memo so the next request retries rather than caching the failure. */
+    let openApiSpec: Promise<ReturnType<typeof buildOpenApiSpec>> | undefined
     const cliCwd = process.cwd()
 
     /* Request closing records are on by default — DEBUG=-abide is the off switch (negation, like the abide channel itself). */
@@ -362,12 +366,19 @@ export async function createServer({
             const response = app?.handle
                 ? await app.handle(req, (next) => handler(next, pathParams, store))
                 : await handler(req, pathParams, store)
+            /* Classify the body once (S2) and thread it into both downstream
+               steps — gzip + the closing-record stream monitor — instead of
+               each re-deriving from the Content-Type. */
+            const kind = responseBodyKind(response)
+            store.responseStreaming = kind === 'streaming'
+            // Streaming bodies (sse/jsonl, socket tail) opt out of the idle timeout.
+            if (kind === 'streaming') {
+                server.timeout(req, 0)
+            }
             /* Gzip compressible dynamic bodies (SSR HTML, rpc/json, 404) when the
                client accepts it; streaming frame protocols and static assets are
                passed through untouched (see gzipResponse). */
-            const encoded = gzipResponse(req, response)
-            // Streaming bodies (sse/jsonl, socket tail) opt out of the idle timeout.
-            return disableIdleTimeoutForStream(server, req, encoded)
+            return gzipResponse(req, response, kind)
         })
     }
 
@@ -481,6 +492,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)),
                     )
@@ -562,14 +594,20 @@ export async function createServer({
                         req,
                         {},
                         async () => {
-                            if (!openApiSpec) {
-                                await ensureRegistriesLoaded()
-                                openApiSpec = buildOpenApiSpec({
-                                    title: appName,
-                                    version: appVersion,
+                            openApiSpec ??= ensureRegistriesLoaded()
+                                .then(() =>
+                                    buildOpenApiSpec({
+                                        title: appName,
+                                        version: appVersion,
+                                    }),
+                                )
+                                .catch((error) => {
+                                    // Don't cache a failed build — clear the memo so a
+                                    // later request retries instead of 500-ing forever.
+                                    openApiSpec = undefined
+                                    throw error
                                 })
-                            }
-                            return Response.json(openApiSpec, {
+                            return Response.json(await openApiSpec, {
                                 headers: { 'Cache-Control': NO_STORE },
                             })
                         },

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()
@@ -26,7 +26,7 @@ export async function devHotModuleResponse(moduleId: string): Promise<Response>
     if (source === undefined) {
         return new Response('not found', { status: 404 })
     }
-    const code = compileModule(source, {
+    const { code } = compileModule(source, {
         isLayout: moduleId.endsWith('layout.abide'),
         moduleId,
         hot: true,

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>,