@belte/belte 0.19.0

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

@@ -0,0 +1,35 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+
+// Keepalive comment cadence — keeps the idle SSE connection from being dropped.
+const KEEPALIVE_INTERVAL_MS = 15000
+
+/*
+The dev live-reload channel (`/__belte/dev`, dev only). An SSE stream that
+carries no events of its own — the browser-side client (DEV_RELOAD_CLIENT_SCRIPT)
+reloads when this connection drops and reconnects, which only happens when the
+dev orchestrator restarts the server after a rebuild. The opening `retry: 250`
+shortens EventSource's reconnect backoff; a periodic comment keeps the idle
+connection alive. The interval is cleared when the consumer disconnects.
+*/
+export function devReloadResponse(): Response {
+    let keepalive: ReturnType<typeof setInterval>
+    const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+            controller.enqueue(new TextEncoder().encode('retry: 250\n\n'))
+            keepalive = setInterval(() => {
+                controller.enqueue(new TextEncoder().encode(': keepalive\n\n'))
+            }, KEEPALIVE_INTERVAL_MS)
+        },
+        cancel() {
+            clearInterval(keepalive)
+        },
+    })
+    return new Response(body, {
+        headers: {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': NO_STORE,
+            'X-Content-Type-Options': 'nosniff',
+            Connection: 'keep-alive',
+        },
+    })
+}

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

@@ -0,0 +1,27 @@
+import type { Server } from 'bun'
+import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
+
+/*
+Opts a long-lived streaming response (SSE / JSONL) out of Bun's per-connection
+idle timeout. Such a stream can stay quiet for longer than the 10s default
+between frames, which Bun would otherwise read as an idle connection and close
+mid-stream. `server.timeout(req, 0)` clears the timeout for just this in-flight
+request, leaving the global default in place for ordinary traffic. Streaming is
+detected by Content-Type (the shared signal the CLI/MCP drain paths use) rather
+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.
+*/
+export function disableIdleTimeoutForStream(
+    server: Server<unknown>,
+    req: Request,
+    response: Response,
+): Response {
+    if (isStreamingResponse(response)) {
+        server.timeout(req, 0)
+    }
+    return response
+}

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

@@ -0,0 +1,15 @@
+import type { StandardSchemaV1 } from '../../shared/types/StandardSchemaV1.ts'
+
+/*
+Holds the schema handed to env() so the bundle launcher can project the
+first-run setup form from it (jsonSchemaForSchema) without re-running boot
+validation. `skipValidation` lets the launcher import src/server/config.ts
+purely to register the schema: env() records it and returns early instead of
+validating Bun.env — which the launcher has no business doing, that's the
+embedded server's job at its own boot. In-process module state, so the server
+child the launcher spawns gets a fresh store and validates normally.
+*/
+export const envSchemaStore: {
+    schema: StandardSchemaV1 | undefined
+    skipValidation: boolean
+} = { schema: undefined, skipValidation: false }

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

@@ -0,0 +1,35 @@
+// Ports probed upward from `start` before giving up and letting the kernel assign one.
+const SCAN_RANGE = 100
+
+/*
+Returns the first bindable TCP port at or above `start`, probing upward.
+Used when no PORT is configured so the server lands on a predictable
+3000+ port (3000, then 3001, …) instead of a random kernel-assigned one —
+running a second app just steps to the next free port. Each probe binds a
+throwaway server and stops it; like any release-then-rebind there's a tiny
+race before the real listener takes the port, negligible for a local boot.
+After SCAN_RANGE occupied ports it gives up scanning and lets the kernel
+assign any free port (bind to 0).
+*/
+export function findOpenPort(start: number): number {
+    for (let port = start; port < start + SCAN_RANGE; port++) {
+        try {
+            return bindAndRelease(port)
+        } catch {
+            // port in use — try the next one up
+        }
+    }
+    // every candidate was taken; bind to 0 so the kernel picks a free port
+    return bindAndRelease(0)
+}
+
+/*
+Binds a throwaway server to `port` (0 = let the kernel assign one), reads the
+actual bound port, and releases it. Throws if the port is already in use.
+*/
+function bindAndRelease(port: number): number {
+    const probe = Bun.serve({ port, fetch: () => new Response() })
+    const bound = probe.port as number
+    probe.stop(true)
+    return bound
+}

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

@@ -0,0 +1,6 @@
+import type { Server } from 'bun'
+import { serverSlot } from './serverSlot.ts'
+
+export function getActiveServer(): Server<unknown> | undefined {
+    return serverSlot.active
+}

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

@@ -0,0 +1,29 @@
+import { Glob } from 'bun'
+
+/*
+Scans `cwd` for files matching `pattern` and returns their request paths as
+a Set, mapping each relative file path to a root-relative URL via `keyFor`.
+Used to snapshot the on-disk asset trees (the `public/` files, the `_app`
+precompressed `.zst` siblings) once at boot so the request path is a Set
+lookup instead of a filesystem stat.
+
+A missing directory makes scan throw ENOENT — swallowed to an empty Set so
+the caller just falls through. This scan-and-catch is also the reliable
+directory existence test: `Bun.file(dir).exists()` returns false for a
+directory, so guarding the scan with it silently yields an empty Set.
+*/
+export async function globToPathSet(
+    cwd: string,
+    pattern: string,
+    keyFor: (file: string) => string,
+    options?: { dot?: boolean },
+): Promise<Set<string>> {
+    try {
+        const files = await Array.fromAsync(
+            new Glob(pattern).scan({ cwd, dot: options?.dot ?? false }),
+        )
+        return new Set(files.map(keyFor))
+    } catch {
+        return new Set()
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { Server } from 'bun'
+
+/*
+The Server `server()` hands back under in-process dispatch (CLI / MCP / test
+client), where no Bun.serve has booted so there is no live connection to act on.
+Each member is the honest no-op for a request that never rode a socket: timeout
+and upgrade do nothing, publish reaches no subscribers (0 bytes sent),
+subscriberCount is 0, requestIP has no peer (null). Handlers using these idioms
+run unchanged in-process instead of throwing; createServer's live Server takes
+precedence whenever one is booted. Connection-scoped only — config-shaped
+members (port, url, hostname …) are intentionally absent: there is no server to
+describe, and a stubbed value would mislead more than their plain absence.
+*/
+export const inProcessServer = {
+    timeout() {},
+    upgrade: () => false,
+    publish: () => 0,
+    subscriberCount: () => 0,
+    requestIP: () => null,
+} as unknown as Server<unknown>

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

@@ -0,0 +1,25 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { isDebugEnabled } from '../../shared/isDebugEnabled.ts'
+
+/*
+The framework's default 500 response. Shared by the per-request scope's catch
+(runWithRequestScope) and Bun.serve's global error() fallback so the two can't
+drift. Only reached when the app supplies no `handleError` hook.
+
+Secure by default: a bare `Internal Server Error` so paths, library versions,
+and message contents never leak to clients in production. The full stack is
+shown only under `DEBUG=belte` (the same dev signal that turns on request
+logging); the cause is logged server-side regardless of the flag.
+*/
+export function internalErrorResponse(error: unknown): Response {
+    const body = isDebugEnabled('belte')
+        ? `<pre>${String((error as Error)?.stack ?? error)}</pre>`
+        : 'Internal Server Error'
+    return new Response(body, {
+        status: 500,
+        headers: {
+            'Content-Type': 'text/html; charset=utf-8',
+            'Cache-Control': NO_STORE,
+        },
+    })
+}

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

@@ -0,0 +1,19 @@
+/*
+True when a WebSocket upgrade carries a browser Origin that doesn't match the
+request's own host — the cross-site WebSocket hijacking (CSWSH) shape. A
+mismatched Origin means another site is trying to open the socket in a visitor's
+authenticated browser. Native clients (CLI, MCP) send no Origin, so an absent
+header is allowed; only a present-and-mismatched (or unparseable) Origin is
+rejected. An unparseable Origin is treated as cross-origin (fail closed).
+*/
+export function isCrossOriginUpgrade(request: Request, requestUrl: URL): boolean {
+    const origin = request.headers.get('origin')
+    if (!origin) {
+        return false
+    }
+    try {
+        return new URL(origin).host !== requestUrl.host
+    } catch {
+        return true
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { Server } from 'bun'
+
+// Ports tried upward from `start` before giving up and letting the kernel assign one.
+const SCAN_RANGE = 100
+
+/*
+Binds the real server, scanning upward from `start` for the first free port.
+The listener that wins a port is the one that keeps it: unlike probing a
+throwaway server and releasing it before the real bind, this leaves no window
+for the chosen port to be stolen in between — the gap that crashed boot on
+EADDRINUSE instead of stepping to the next port. `bindAt` does the actual
+Bun.serve; only an in-use port is retried, any other failure propagates. After
+SCAN_RANGE occupied ports it binds port 0 so the kernel assigns any free port.
+*/
+export function listenOnOpenPort(
+    bindAt: (port: number) => Server<unknown>,
+    start: number,
+): Server<unknown> {
+    for (let port = start; port < start + SCAN_RANGE; port++) {
+        try {
+            return bindAt(port)
+        } catch (error) {
+            if (!isAddressInUse(error)) {
+                throw error
+            }
+            // port in use — try the next one up
+        }
+    }
+    // every candidate was taken; bind to 0 so the kernel picks a free port
+    return bindAt(0)
+}
+
+// Bun reports a taken port as an Error carrying code 'EADDRINUSE'.
+function isAddressInUse(error: unknown): boolean {
+    return error instanceof Error && (error as { code?: string }).code === 'EADDRINUSE'
+}

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

@@ -0,0 +1,162 @@
+import type { Pages } from '../../browser/types/Pages.ts'
+import { log } from '../../shared/log.ts'
+import type { NormalizedLayoutPrefix } from '../../shared/nearestLayoutPrefix.ts'
+import { nearestLayoutPrefix } from '../../shared/nearestLayoutPrefix.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { socketRegistry } from '../sockets/socketRegistry.ts'
+import { ensureRegistriesLoaded } from './registryManifests.ts'
+
+// Cell glyphs: PRESENT, ABSENT.
+const PRESENT = '✓'
+const ABSENT = '·'
+const COLUMN_GAP = 2
+
+const hasColor = typeof Bun !== 'undefined' && Bun.enableANSIColors
+// Red foreground then `\x1b[39m` (default-foreground, not full reset) so the enclosing dim survives.
+const redden = (text: string): string =>
+    hasColor ? `${Bun.color('red', 'ansi-256')}${text}\x1b[39m` : text
+
+/*
+A declared inputSchema is what makes mcp/cli safe to advertise (see defineVerb /
+defineSocket), so a missing schema gets a red `·` to flag the declaration whose
+machine surfaces are gated behind it.
+*/
+const schemaCell = (hasSchema: boolean): string => (hasSchema ? PRESENT : redden(ABSENT))
+const flag = (on: boolean): string => (on ? PRESENT : ABSENT)
+
+// Display width ignoring ANSI color escapes, so colored glyphs don't inflate alignment.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the ESC (\x1b) is the intended match — stripping the color escape to measure visible width
+const displayWidth = (cell: string): number => cell.replace(/\x1b\[[0-9;]*m/g, '').length
+
+// A titled table: its header row plus data rows, all sharing the column layout below.
+type SurfaceTable = { title: string; header: string[]; rows: string[][] }
+
+// Per-column width: the widest cell's display width across every row given.
+function columnWidths(rows: string[][]): number[] {
+    const columnCount = Math.max(...rows.map((row) => row.length))
+    return Array.from({ length: columnCount }, (_, column) =>
+        Math.max(...rows.map((row) => displayWidth(row[column] ?? ''))),
+    )
+}
+
+/*
+Left-aligns one row's cells into the given fixed column widths plus a gap.
+Padding is explicit spaces measured by displayWidth so embedded color escapes
+don't inflate the width and break alignment. Two-space indented.
+*/
+function renderRow(row: string[], widths: number[]): string {
+    return (
+        '  ' +
+        row
+            .map(
+                (cell, column) =>
+                    cell + ' '.repeat(widths[column] - displayWidth(cell) + COLUMN_GAP),
+            )
+            .join('')
+            .trimEnd()
+    )
+}
+
+/*
+Prints every non-empty table under one shared set of column widths, so the
+identifier and glyph columns line up vertically across the page/socket/rpc
+tables rather than each table aligning only within itself. Each table keeps its
+own dim header row.
+*/
+function logTables(tables: SurfaceTable[]): void {
+    const present = tables.filter((table) => table.rows.length > 0)
+    if (present.length === 0) {
+        return
+    }
+    const widths = columnWidths(present.flatMap((table) => [table.header, ...table.rows]))
+    present.forEach((table) => {
+        log.info(`${table.title}:`)
+        log.detail([table.header, ...table.rows].map((row) => renderRow(row, widths)).join('\n'))
+    })
+}
+
+/*
+Boot-time surface map: every page, socket, and rpc with the surfaces it is
+exposed on, so belte'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.
+  - sockets: name + client surfaces (schema/browser/mcp/cli) and whether clients
+    may publish.
+  - rpcs: method+path (headed `http` since http/openapi are unconditional) +
+    per-declaration client surfaces.
+
+All three render under one shared column grid (see logTables): the identifier
+leads flush-left in every table — page route, socket name, or rpc method+path —
+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 `belte` debug logging (DEBUG=belte) to avoid forcing
+eager imports in production. Best-effort: enumeration failures are swallowed,
+this is diagnostic only.
+*/
+export async function logExposedSurfaces(routing: {
+    pages: Pages
+    layoutPrefixes: NormalizedLayoutPrefix[]
+    errorPrefixes: NormalizedLayoutPrefix[]
+}): Promise<void> {
+    try {
+        await ensureRegistriesLoaded()
+    } catch {
+        return
+    }
+
+    const pageRows = Object.keys(routing.pages)
+        .map((route) => [
+            route,
+            nearestLayoutPrefix(route, routing.layoutPrefixes) ?? ABSENT,
+            nearestLayoutPrefix(route, routing.errorPrefixes) ?? ABSENT,
+        ])
+        .sort()
+
+    const socketRows = Array.from(socketRegistry.values(), (entry) => [
+        entry.socket.name,
+        schemaCell(Boolean(entry.schema)),
+        flag(entry.clients.browser),
+        flag(entry.clients.mcp),
+        flag(entry.clients.cli),
+        flag(entry.allowClientPublish),
+    ]).sort()
+
+    /*
+    rpc identifier = method left-aligned to a shared width then the path, so the
+    methods line up and every path starts at the same column — while the cell as
+    a whole still leads flush-left like the page route and socket name.
+    */
+    const methodWidth = Math.max(
+        'http'.length,
+        ...Array.from(verbRegistry.values(), (entry) => entry.remote.method.length),
+    )
+    const withMethod = (method: string, identifier: string): string =>
+        method.padEnd(methodWidth + COLUMN_GAP) + identifier
+
+    const rpcRows = Array.from(verbRegistry.values(), (entry) => [
+        withMethod(entry.remote.method, entry.remote.url),
+        schemaCell(Boolean(entry.inputSchema)),
+        flag(entry.clients.browser),
+        flag(entry.clients.mcp),
+        flag(entry.clients.cli),
+    ]).sort()
+
+    logTables([
+        { title: 'pages', header: ['page', 'layout', 'error'], rows: pageRows },
+        {
+            title: 'sockets',
+            header: ['socket', 'schema', 'browser', 'mcp', 'cli', 'publish'],
+            rows: socketRows,
+        },
+        {
+            title: 'rpcs',
+            header: [withMethod('http', ''), 'schema', 'browser', 'mcp', 'cli'],
+            rows: rpcRows,
+        },
+    ])
+}

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

@@ -0,0 +1,20 @@
+/*
+Derives the MIME type from a URL pathname using Bun.file().type, which
+operates on the file extension synchronously without touching the disk. The
+Bun.file ref here is never read from — it exists only to reuse Bun's
+extension-to-MIME table. Cache by extension so repeat hits for the same
+chunk type (.js / .css / .map / .svg / …) skip the BunFile allocation.
+*/
+const mimeByExtension = new Map<string, string>()
+
+export function mimeForExtension(pathname: string): string {
+    const dot = pathname.lastIndexOf('.')
+    const extension = dot === -1 ? '' : pathname.slice(dot)
+    const cached = mimeByExtension.get(extension)
+    if (cached !== undefined) {
+        return cached
+    }
+    const type = Bun.file(pathname).type
+    mimeByExtension.set(extension, type)
+    return type
+}

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

@@ -0,0 +1,10 @@
+import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+
+/*
+Parses BELTE_IDLE_TIMEOUT into Bun's per-connection idle timeout in seconds.
+Bun accepts 0–255 (0 disables the timeout); returns undefined for missing,
+empty, or out-of-range/non-integer input so the caller keeps its default.
+*/
+export function parseIdleTimeout(value: string | undefined): number | undefined {
+    return parseBoundedEnvInt(value, 0, 255)
+}

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

@@ -0,0 +1,11 @@
+import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+
+/*
+Parses a PORT env value into a usable TCP port (0–65535), returning undefined
+for missing, empty, or out-of-range/non-integer input so the caller can fall
+back to a default. A bare Number() would turn '' into 0 (a random
+kernel-assigned port) and 'abc' into NaN, both silently wrong.
+*/
+export function parsePort(value: string | undefined): number | undefined {
+    return parseBoundedEnvInt(value, 0, 65535)
+}

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

@@ -0,0 +1,66 @@
+import type { PromptRoutes } from '../prompts/types/PromptRoutes.ts'
+import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
+import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
+
+/*
+Process-wide slot for the rpc + sockets + prompts manifests. createServer
+assigns once at boot (right after the route table is built); the MCP
+server, the OpenAPI emitter, and prompt enumeration read it on first
+request so they can lazy-import every module and walk the
+verb/socket/prompt registries.
+
+The slot pattern (mirrors getActiveServer) lets the framework-generated
+McpServer bind to the manifests at module scope while the loaders stay
+lazy until the first enumeration request.
+*/
+type RegistryManifests = {
+    rpc: RemoteRoutes
+    sockets: SocketRoutes
+    prompts: PromptRoutes
+}
+
+let manifests: RegistryManifests | undefined
+let loading: Promise<void> | undefined
+
+export function setRegistryManifests(value: RegistryManifests): void {
+    manifests = value
+    loading = undefined
+}
+
+/*
+On first call, eagerly imports every rpc + socket + prompt module so
+defineVerb / defineSocket / definePrompt fire and populate the
+registries. Idempotent — repeat calls reuse the same in-flight promise,
+so concurrent first requests (e.g. /openapi.json + an MCP tools/list)
+trigger exactly one load instead of racing to fire the full import set
+each. Eager loading is acceptable here because enumeration (MCP
+tool/resource/prompt lists, the OpenAPI document) fundamentally requires
+the full surface; the alternative of per-call lazy loading produces flaky
+first-call latency.
+*/
+export function ensureRegistriesLoaded(): Promise<void> {
+    if (!manifests) {
+        return Promise.resolve()
+    }
+    if (!loading) {
+        const { rpc, sockets, prompts } = manifests
+        loading = Promise.all([
+            ...Object.values(rpc).map((loader) => loader()),
+            ...Object.values(sockets).map((loader) => loader()),
+            ...Object.values(prompts).map((loader) => loader()),
+        ])
+            .then(() => undefined)
+            /*
+            Clear the memo on failure so a transient import error (a
+            module that throws at load, fixed by the next HMR pass)
+            doesn't poison every later enumeration request for the
+            process lifetime. The rejection still propagates to this
+            caller; the reset only affects subsequent calls.
+            */
+            .catch((error) => {
+                loading = undefined
+                throw error
+            })
+    }
+    return loading
+}

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

@@ -0,0 +1,5 @@
+// AsyncLocalStorage is canonical via node:async_hooks — Bun has no separate API
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { RequestStore } from './types/RequestStore.ts'
+
+export const requestContext = new AsyncLocalStorage<RequestStore>()

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

@@ -0,0 +1,29 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { streamCacheResolutions } from './streamCacheResolutions.ts'
+import { streamFromIterator } from './streamFromIterator.ts'
+import { takePendingStream } from './streamStash.ts'
+
+/*
+The out-of-band resolution stream. The browser opens this once per streamed page
+(token from `__SSR__.streamToken`) and reads newline-delimited StreamedResolution
+objects as each pending {#await} fetch lands — draining the SAME in-flight
+promises stashed during SSR, so handlers run once. A missing/expired token
+(404) tells the client to re-fetch its placeholders live.
+
+Returned directly (not via dispatchRequest), so it inherits the configured
+`idleTimeout` as a bounded cap rather than the long-lived-stream disable; a cut
+is recovered client-side off the fetch reader's clean EOF.
+*/
+export function resolveStreamResponse(token: string): Response {
+    const stash = takePendingStream(token)
+    if (!stash) {
+        return new Response('', { status: 404 })
+    }
+    const body = streamFromIterator(streamCacheResolutions(stash.store, stash.pending), {
+        encodeFrame: (resolution) => `${JSON.stringify(resolution)}\n`,
+        encodeError: () => '',
+    })
+    return new Response(body, {
+        headers: { 'Content-Type': 'application/x-ndjson', 'Cache-Control': NO_STORE },
+    })
+}

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

@@ -0,0 +1,57 @@
+import { createCacheStore } from '../../shared/createCacheStore.ts'
+import { log } from '../../shared/log.ts'
+import type { AppModule } from '../AppModule.ts'
+import { internalErrorResponse } from './internalErrorResponse.ts'
+import { requestContext } from './requestContext.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+/*
+Establishes the per-request scope and runs `body` inside it: a fresh
+CacheStore plus request metadata published through the AsyncLocalStorage
+RequestStore (so cache() and request()/server() resolve without threading
+args), the app's handleError — or the framework's 500 fallback — on a thrown
+body, and optional request logging. The single seam every dynamic route
+crosses; extracted from createServer so the scope, error, and logging
+behaviour is exercisable through this interface without booting a Bun server.
+*/
+export function runWithRequestScope(
+    req: Request,
+    options: { app?: AppModule; logRequests: boolean },
+    body: (store: RequestStore) => Promise<Response>,
+): Promise<Response> {
+    const url = new URL(req.url)
+    const store: RequestStore = {
+        url,
+        req,
+        cache: createCacheStore(),
+    }
+    return requestContext.run(store, async () => {
+        const start = options.logRequests ? Bun.nanoseconds() : 0
+        let response: Response
+        try {
+            response = await body(store)
+        } catch (error) {
+            if (options.app?.handleError) {
+                response = await options.app.handleError(error, req)
+            } else {
+                log.error(error)
+                response = internalErrorResponse(error)
+            }
+        }
+        /*
+        Flush any cookies the handler set onto the outgoing response. Only when
+        a jar was materialized (cookies() was called) and only via append, so a
+        Set-Cookie the handler already placed on the response init survives.
+        */
+        if (store.cookies) {
+            store.cookies.toSetCookieHeaders().forEach((header) => {
+                response.headers.append('set-cookie', header)
+            })
+        }
+        if (options.logRequests) {
+            const ms = (Bun.nanoseconds() - start) / 1e6
+            log.request(req.method, `${url.pathname}${url.search}`, response.status, ms)
+        }
+        return response
+    })
+}

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

@@ -0,0 +1,17 @@
+/*
+Escapes characters that could prematurely terminate the surrounding <script>
+tag or be interpreted as HTML comment delimiters when a JSON literal is
+inlined into an HTML document. U+2028 (LS) and U+2029 (PS) are valid in JSON
+but break a `<script>` tag's inline content because the JavaScript lexer
+treats them as line terminators; encode them as Unicode escapes.
+*/
+const LINE_SEPARATOR = String.fromCharCode(0x2028)
+const PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029)
+
+export function safeJsonForScript(value: unknown): string {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/-->/g, '--\\u003e')
+        .replaceAll(LINE_SEPARATOR, '\\u2028')
+        .replaceAll(PARAGRAPH_SEPARATOR, '\\u2029')
+}