@belte/belte 0.19.0

package/src/lib/shared/queryStringFromArgs.ts

@@ -0,0 +1,27 @@
+/*
+Canonical query-string encoding for a query-carrying verb's args bag. The
+single definition both the synthesized Request (buildRpcRequest) and its
+cache key (keyForRemoteCall) build their query from, so the request URL and
+the key encode every value identically and can't drift. `undefined` values
+are dropped; each surviving value is coerced with String() and percent-
+encoded with encodeURIComponent on both name and value. Keys come in
+insertion order for the request and sorted for the key (`sort`), so the key
+is stable under arg reordering. Returns the query body without a leading
+`?` (empty string when nothing survives the filter). Concatenated in one
+walk — no entries / filtered / URLSearchParams intermediates — to keep the
+hot GET-cache path allocation-light. Callers validate that `args` is a
+plain object first; this assumes that.
+*/
+export function queryStringFromArgs(args: Record<string, unknown>, sort: boolean): string {
+    const keys = sort ? Object.keys(args).sort() : Object.keys(args)
+    let query = ''
+    for (const key of keys) {
+        const value = args[key]
+        if (value === undefined) {
+            continue
+        }
+        query += query ? '&' : ''
+        query += `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`
+    }
+    return query
+}

package/src/lib/shared/readEnvFile.ts

@@ -0,0 +1,15 @@
+import { existsSync } from 'node:fs'
+import { parseEnv } from './parseEnv.ts'
+
+/*
+Reads a `.env` at `path` into a key→value record, or {} when it doesn't exist.
+The shared read-and-parse primitive: loadEnvFile builds on it to merge into
+process.env, and the bundle launcher uses the record directly to resolve config
+form pre-fills.
+*/
+export async function readEnvFile(path: string): Promise<Record<string, string>> {
+    if (!existsSync(path)) {
+        return {}
+    }
+    return parseEnv(await Bun.file(path).text())
+}

package/src/lib/shared/readLastConnection.ts

@@ -0,0 +1,18 @@
+import { lastConnectionPath } from './lastConnectionPath.ts'
+import type { LastConnection } from './types/LastConnection.ts'
+
+/*
+Reads the saved connection intent, or undefined when none is recorded or the file
+is unreadable/corrupt — callers treat undefined as "nothing to resume".
+*/
+export async function readLastConnection(programName: string): Promise<LastConnection | undefined> {
+    const file = Bun.file(lastConnectionPath(programName))
+    if (!(await file.exists())) {
+        return undefined
+    }
+    try {
+        return (await file.json()) as LastConnection
+    } catch {
+        return undefined
+    }
+}

package/src/lib/shared/readPackageJson.ts

@@ -0,0 +1,9 @@
+/*
+Reads and parses a project's `package.json`, or undefined when absent. Callers
+apply their own field defaults — this centralizes only the exists-check + parse
+boilerplate. Bun.file().json() so no Node fs.
+*/
+export async function readPackageJson(cwd: string): Promise<Record<string, unknown> | undefined> {
+    const file = Bun.file(`${cwd}/package.json`)
+    return (await file.exists()) ? ((await file.json()) as Record<string, unknown>) : undefined
+}

package/src/lib/shared/recordRemoteMeta.ts

@@ -0,0 +1,5 @@
+import { remoteMetaStore } from './remoteMetaStore.ts'
+
+export function recordRemoteMeta(promise: Promise<unknown>, getRequest: () => Request): void {
+    remoteMetaStore.set(promise, getRequest)
+}

package/src/lib/shared/remoteMetaStore.ts

@@ -0,0 +1,16 @@
+/*
+WeakMap that records how to obtain the synthesized Request for a verb
+call. The cache layer reads it to populate an entry's stored request
+without rebuilding from scratch.
+
+Stored as a thunk rather than the Request itself so SSR pages that fire
+dozens of in-process verb calls without ever reaching cache() don't pay
+the URL + Headers + Request allocation per call. The thunk memoises its
+own first call inside createRemoteFunction, so cache() and any future
+meta reader see the same Request instance.
+
+method/url/key are intentionally not stored — they're derivable from
+the RemoteFunction itself, and cache() does that derivation
+independently.
+*/
+export const remoteMetaStore = new WeakMap<Promise<unknown>, () => Request>()

package/src/lib/shared/resolveClientFlags.ts

@@ -0,0 +1,20 @@
+import type { ClientFlags } from './types/ClientFlags.ts'
+
+/*
+Fills in the missing keys of a user-supplied `clients` option. Browser
+always defaults to true (the historical surface). The mcp/cli auto-on
+defaults are decided by the caller and passed in, since the safe default
+differs per declaration: a read-only verb may auto-expose to MCP while a
+mutating one must not, and sockets gate differently again. Explicit
+values in `flags` always win over the computed defaults.
+*/
+export function resolveClientFlags(
+    flags: Partial<ClientFlags> | undefined,
+    defaults: { mcp: boolean; cli: boolean },
+): ClientFlags {
+    return {
+        browser: flags?.browser ?? true,
+        mcp: flags?.mcp ?? defaults.mcp,
+        cli: flags?.cli ?? defaults.cli,
+    }
+}

package/src/lib/shared/responseErrorText.ts

@@ -0,0 +1,9 @@
+/*
+Human-readable message for a non-2xx Response: `status statusText: body`.
+Shared by the CLI error path and the MCP tool result so the two frame a
+failed request identically. Consumes the body, so call only on a response
+you're done with.
+*/
+export async function responseErrorText(response: Response): Promise<string> {
+    return `${response.status} ${response.statusText}: ${await response.text()}`
+}

package/src/lib/shared/rpcUrlForFile.ts

@@ -0,0 +1,19 @@
+/*
+Maps an rpc-relative path (under `src/server/rpc/`) to its URL. Each file
+is one endpoint at `/rpc/<file path>`, dropping the `.ts` extension.
+$rpc URLs are flat function-call endpoints (args go in query or body), so
+bracket-style `[name]` / `[...rest]` segments are rejected — those belong
+in `src/browser/pages/` where they map to dynamic path params.
+*/
+export function rpcUrlForFile(relPath: string): string {
+    const withoutExt = relPath.replace(/\.ts$/, '')
+    const segments = withoutExt.split('/').filter(Boolean)
+    for (const segment of segments) {
+        if (segment.startsWith('[')) {
+            throw new Error(
+                `[belte] src/server/rpc/${relPath} has a dynamic segment '${segment}' — $rpc URLs are flat; pass identifiers via args, not the path`,
+            )
+        }
+    }
+    return `/rpc/${segments.join('/')}`
+}

package/src/lib/shared/runningAsStandaloneBinary.ts

@@ -0,0 +1,13 @@
+/*
+True when this code runs inside a `bun build --compile` standalone executable
+(the bundle's embedded server, or an install-tarball server binary) rather than
+under the `bun` CLI. Bun mounts a compiled binary's embedded modules under a
+synthetic root — `/$bunfs/…` on posix, `…~BUN…` on Windows — so `Bun.main`
+carries that marker only in a standalone binary; under `bun dev`/`bun start`
+it's a real on-disk path. Used to scope the bundle's data-dir/binary-dir `.env`
+loading to the shipped app, so `bun dev`/`bun start` keep to their project-local
+CWD `.env` alone.
+*/
+export function runningAsStandaloneBinary(): boolean {
+    return Bun.main.includes('$bunfs') || Bun.main.includes('~BUN')
+}

package/src/lib/shared/serializeEnv.ts

@@ -0,0 +1,18 @@
+// Quote only values that wouldn't round-trip bare through parseEnv — empties and
+// anything carrying whitespace or a `#` (which would otherwise read as a comment).
+function needsQuoting(value: string): boolean {
+    return value === '' || /[\s#]/.test(value)
+}
+
+/*
+Serializes a key→value record to `.env` text — the inverse of parseEnv, used by
+the connect-screen config form to persist the user's answers to the data-dir
+`.env`. One `KEY=value` per line; values that need it are wrapped in double
+quotes so parseEnv reads them back unchanged.
+*/
+export function serializeEnv(values: Record<string, string>): string {
+    const lines = Object.entries(values).map(([key, value]) =>
+        needsQuoting(value) ? `${key}="${value}"` : `${key}=${value}`,
+    )
+    return `${lines.join('\n')}\n`
+}

package/src/lib/shared/setCacheStoreResolver.ts

@@ -0,0 +1,6 @@
+import { cacheStoreSlot } from './cacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+export function setCacheStoreResolver(fn: () => CacheStore | undefined): void {
+    cacheStoreSlot.resolver = fn
+}

package/src/lib/shared/setGlobalCacheStoreResolver.ts

@@ -0,0 +1,6 @@
+import { globalCacheStoreSlot } from './globalCacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+export function setGlobalCacheStoreResolver(fn: () => CacheStore | undefined): void {
+    globalCacheStoreSlot.resolver = fn
+}

package/src/lib/shared/socketNameForFile.ts

@@ -0,0 +1,11 @@
+/*
+Translates a socket file path under `src/server/sockets/` into the socket's
+identity used on the wire. The name is the file path minus `.ts` so
+nested paths (e.g. `orders/new.ts`) become `orders/new`. Sockets don't
+need a URL prefix the way rpc routes do — they multiplex over the
+framework-owned `/__belte/sockets` ws and are dispatched by name in the
+registry, not by HTTP path.
+*/
+export function socketNameForFile(relativePath: string): string {
+    return relativePath.replace(/\.ts$/, '')
+}

package/src/lib/shared/sseErrorFrame.ts

@@ -0,0 +1,29 @@
+/*
+The in-band error sentinel for an SSE stream: when a handler's generator
+throws, `sse()` emits an `event: error` frame whose data is `{ message }`,
+and `streamResponse` re-throws it on the consumer side. Encoder and decoder
+live together here so the sentinel (event name + payload shape) has one
+definition and can't drift between the two ends of the wire.
+*/
+export const sseErrorFrame = {
+    // Full `event: error` frame for a thrown message, including the SSE delimiters.
+    encode(message: string): string {
+        return `event: error\ndata: ${JSON.stringify({ message })}\n\n`
+    },
+    /*
+    The message carried by an error frame, or undefined when `event` isn't
+    the error sentinel. Falls back to the raw data when it isn't the JSON
+    the encoder produces.
+    */
+    decode(event: string, data: string): string | undefined {
+        if (event !== 'error') {
+            return undefined
+        }
+        try {
+            const decoded = JSON.parse(data) as { message?: string }
+            return decoded?.message ?? 'sse stream error'
+        } catch {
+            return data || 'sse stream error'
+        }
+    },
+}

package/src/lib/shared/streamResponse.ts

@@ -0,0 +1,169 @@
+import { decodeResponse } from './decodeResponse.ts'
+import { HttpError } from './HttpError.ts'
+import { jsonlErrorFrame } from './jsonlErrorFrame.ts'
+import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
+import { sseErrorFrame } from './sseErrorFrame.ts'
+
+/*
+Turns a Response into an AsyncIterable of frames, regardless of the
+handler's chosen body format. Shared by `fn.stream(args)` (via
+subscribableFromResponse), the CLI's streaming print path, and the MCP
+tool dispatcher's stream drain — so every surface consumes sse/jsonl
+identically. Three shapes are handled:
+
+- text/event-stream (SSE): emits the JSON-parsed `data:` payload of
+  each event. The `event: error\ndata: {message}` frame the `sse()`
+  helper emits on generator throws is mapped back to a thrown Error so
+  consumers see the failure mid-iteration.
+- application/jsonl + application/x-ndjson: emits one JSON value per
+  line. The trailing `{"$error":"..."}` line the `jsonl()` helper
+  emits on generator throws is likewise re-thrown.
+- everything else: one-shot — yields the Content-Type-decoded body
+  once, then completes. Lets callers iterate uniformly on every rpc
+  handler, not just the streaming ones.
+
+Non-2xx responses surface as a thrown HttpError on the first pull,
+mirroring the plain `fn(args)` decode path.
+*/
+export function streamResponse<T>(response: Response): AsyncIterable<T> {
+    if (!response.ok) {
+        return errorIterable<T>(new HttpError(response))
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.startsWith('text/event-stream')) {
+        return parseSse<T>(response)
+    }
+    if (STREAMING_CONTENT_TYPES.some((type) => contentType.startsWith(type))) {
+        return parseJsonLines<T>(response)
+    }
+    return oneShot<T>(response)
+}
+
+/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
+// biome-ignore lint/correctness/useYield: throws on first pull; the generator shape is intentional so callers iterate it uniformly
+async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
+    throw error
+}
+
+/*
+One-shot iterator over a non-streaming Response: decodes the body once
+via the same Content-Type sniffing the plain call uses, yields it, then
+completes. Makes streaming symmetrical across streaming and
+non-streaming handlers — callers can pick the iteration shape without
+worrying about which body the handler returned.
+*/
+async function* oneShot<T>(response: Response): AsyncGenerator<T> {
+    yield (await decodeResponse(response)) as T
+}
+
+/*
+Reads a streaming text Response and yields raw frame strings split on
+`delimiter` (`\n\n` for SSE events, `\n` for JSON lines). Owns the whole
+buffering lifecycle: incremental decode, amortised-O(n) compaction, a
+final flush of the trailing partial frame, and reader cancellation when
+the consumer stops iterating (the generator's `finally` runs on
+`return()`). The SSE and jsonl parsers layer their per-frame parsing on
+top of this single machine so the two can't drift.
+*/
+async function* frameReader(response: Response, delimiter: string): AsyncGenerator<string> {
+    const body = response.body
+    if (!body) {
+        return
+    }
+    const reader = body.pipeThrough(new TextDecoderStream()).getReader()
+    let buffer = ''
+    let bufferStart = 0
+    try {
+        while (true) {
+            const { value, done } = await reader.read()
+            if (done) {
+                if (bufferStart < buffer.length) {
+                    yield buffer.slice(bufferStart)
+                }
+                return
+            }
+            /*
+            Compact only when the unread region is small relative to the
+            consumed prefix — keeps amortised work O(n) instead of
+            quadratic slicing per frame boundary.
+            */
+            if (bufferStart > buffer.length / 2) {
+                buffer = buffer.slice(bufferStart) + value
+                bufferStart = 0
+            } else {
+                buffer += value
+            }
+            let boundary = buffer.indexOf(delimiter, bufferStart)
+            while (boundary !== -1) {
+                yield buffer.slice(bufferStart, boundary)
+                bufferStart = boundary + delimiter.length
+                boundary = buffer.indexOf(delimiter, bufferStart)
+            }
+        }
+    } finally {
+        await reader.cancel().catch(() => undefined)
+    }
+}
+
+/*
+SSE parser: yields the JSON-parsed `data` payload of each `event:`/`data:`
+frame. The error sentinel (`sseErrorFrame`) the `sse()` helper emits on a
+generator throw is surfaced as a thrown Error so consumer loops can react
+to mid-stream failure rather than silently stopping.
+*/
+async function* parseSse<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n\n')) {
+        const frame = parseFrame(raw)
+        if (!frame) {
+            continue
+        }
+        const errorMessage = sseErrorFrame.decode(frame.event, frame.data)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield JSON.parse(frame.data) as T
+    }
+}
+
+function parseFrame(raw: string): { event: string; data: string } | undefined {
+    const lines = raw.split('\n').filter((line) => line.length > 0 && !line.startsWith(':'))
+    if (lines.length === 0) {
+        return undefined
+    }
+    let event = 'message'
+    const dataLines: string[] = []
+    for (const line of lines) {
+        const colon = line.indexOf(':')
+        const field = colon === -1 ? line : line.slice(0, colon)
+        const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '')
+        if (field === 'event') {
+            event = value
+        } else if (field === 'data') {
+            dataLines.push(value)
+        }
+    }
+    if (dataLines.length === 0) {
+        return undefined
+    }
+    return { event, data: dataLines.join('\n') }
+}
+
+/*
+JSONL/NDJSON parser: parses each non-empty line as JSON and yields the
+value. The error sentinel (`jsonlErrorFrame`) the `jsonl()` helper emits as
+a trailing line on a generator throw is surfaced here as a thrown Error so
+consumer loops can react to mid-stream failure.
+*/
+async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
+    for await (const raw of frameReader(response, '\n')) {
+        if (raw.length === 0) {
+            continue
+        }
+        const parsed = JSON.parse(raw)
+        const errorMessage = jsonlErrorFrame.decode(parsed)
+        if (errorMessage !== undefined) {
+            throw new Error(errorMessage)
+        }
+        yield parsed as T
+    }
+}

package/src/lib/shared/stripImport.ts

@@ -0,0 +1,27 @@
+/*
+Strips the user's `import { … } from '<moduleName>'` declaration from a
+module source. Used by the $rpc / $sockets rewriters to remove the
+verb / `socket` import after its call site has been replaced by the
+runtime-injected binding (defineVerb / defineSocket). Without this
+strip the dead import would still side-effect-load the verb/socket
+helper module into the server bundle for every $rpc / $sockets file.
+
+The braced body is `[^}]*` rather than `[\s\S]*?` so the lazy match
+can't backtrack across a `}` and accidentally swallow a preceding
+import whose `from` clause doesn't match (e.g. stripping
+`import { GET } from 'belte/server/GET'` from a file that also has
+`import { json } from 'belte/server/json'` on the line above). `[^}]`
+includes newlines, so multi-line braced imports like
+  import {
+    GET,
+  } from 'belte/server/GET'
+still match — the body just can't contain another `}` to bound it.
+*/
+export function stripImport(source: string, moduleName: string): string {
+    const escaped = moduleName.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')
+    const pattern = new RegExp(
+        `^\\s*import\\s*\\{[^}]*\\}\\s*from\\s*['"]${escaped}['"]\\s*;?\\s*$`,
+        'gm',
+    )
+    return source.replace(pattern, '')
+}

package/src/lib/shared/subscribableFromResponse.ts

@@ -0,0 +1,51 @@
+import { streamResponse } from './streamResponse.ts'
+import type { Subscribable } from './types/Subscribable.ts'
+
+/*
+Builds the Subscribable returned by `fn.stream(args)`. The carried
+`name` is the cache-style key for (method, url, args) so subscribe()
+dedupes multiple subscribers to identical args into one underlying
+fetch. The fetch is deferred until the first iterator pull so
+constructing the Subscribable (which happens on every $derived
+re-evaluation) doesn't open a connection — subscribe()'s registry
+short-circuits the second instance before it iterates.
+*/
+export function subscribableFromResponse<T>(
+    name: string,
+    fetchResponse: () => Promise<Response>,
+): Subscribable<T> {
+    return {
+        name,
+        [Symbol.asyncIterator]() {
+            let inner: AsyncIterator<T, void, undefined> | undefined
+            let cancelled = false
+            return {
+                async next() {
+                    if (cancelled) {
+                        return { value: undefined, done: true }
+                    }
+                    if (!inner) {
+                        const response = await fetchResponse()
+                        inner = streamResponse<T>(response)[Symbol.asyncIterator]()
+                        /*
+                        If return() landed while we were awaiting the
+                        fetch, `inner` was still undefined then so its
+                        reader was never cancelled — release the body now
+                        rather than leaving the HTTP stream open.
+                        */
+                        if (cancelled) {
+                            await inner.return?.(undefined)
+                            return { value: undefined, done: true }
+                        }
+                    }
+                    return inner.next()
+                },
+                async return() {
+                    cancelled = true
+                    await inner?.return?.(undefined)
+                    return { value: undefined, done: true }
+                },
+            }
+        },
+    }
+}

package/src/lib/shared/toBunRoutePattern.ts

@@ -0,0 +1,28 @@
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+Translates a belte route URL (`/media/[id]/[...rest]`) into the pattern Bun
+needs (`/media/:id/*`) for `Bun.serve({ routes })`. Returns the catch-all
+segment's original name alongside so the server can rename Bun's `*` param
+back to that name on the way out, keeping page-prop destructuring consistent
+with the route file path.
+*/
+export function toBunRoutePattern(routeUrl: string): {
+    pattern: string
+    catchAllName: string | undefined
+} {
+    let catchAllName: string | undefined
+    const pattern = parseRouteSegments(routeUrl)
+        .map((segment) => {
+            if (segment.kind === 'literal') {
+                return segment.value
+            }
+            if (segment.catchAll) {
+                catchAllName = segment.name
+                return '*'
+            }
+            return `:${segment.name}`
+        })
+        .join('/')
+    return { pattern, catchAllName }
+}

package/src/lib/shared/types/CacheEntry.ts

@@ -0,0 +1,63 @@
+/*
+Stored shape per cache key. The stored promise resolves to the raw Response for
+a remote function (the snapshot reads its status/headers/body and the cache
+layer hands callers a decoded view derived from it) or to the producer's value
+for a plain producer — hence `Promise<unknown>`.
+
+`request` is retained for remote entries so SSR snapshot serialization can
+record the URL and method without re-deriving them from the function. Producer
+entries have no wire request, so it is absent — and the snapshot readers skip
+any entry lacking it (a producer value has no rpc identity to rehydrate against).
+
+`ttl`/`expiresAt` drive eviction: expiresAt = undefined means "no TTL" (lives
+forever); ttl = 0 means "dedupe only" (entry is pruned as soon as the promise
+settles).
+
+`value` is set only for entries hydrated from the SSR snapshot: the
+snapshot body is pre-decoded synchronously so the first client render can
+read it without a microtask hop and byte-match the SSR DOM. Live fetches
+leave it undefined and take the async decode path.
+
+`scope` holds the cache() call's scope tags as a Set so
+`cache.invalidate({ scope })` can drop every entry sharing any tag with O(1)
+membership; a re-read merges new tags in rather than replacing them.
+
+`settled` flips true once the stored promise resolves. SSR snapshot
+serialization reads it after `render()` returns to partition entries: ones
+settled by then were consumed via `await` (render blocked on them) and inline
+into `__SSR__`; ones still pending were consumed via `{#await}` (render emitted
+the pending branch without blocking) and stream a resolve chunk instead.
+
+`refreshing` flips true while this entry is reloading data it already held —
+either a policy stale-while-revalidate refetch (value still visible) or the
+default drop-then-reload (the prior entry was invalidated and dropped, this is
+its replacement read). It backs cache.refreshing, distinguishing a reload from a
+first-ever load; cleared when the read settles.
+
+`invalidation` is present only when the cache() call set an `invalidate`
+throttle/debounce policy: it holds the refetch thunk (the original call captured
+with its args) plus the policy and its runtime timer state, so invalidate() can
+rate-limit refetches of this key instead of dropping the entry and refetching on
+every invalidation.
+*/
+export type CacheEntry = {
+    key: string
+    promise: Promise<unknown>
+    request?: Request
+    ttl: number | undefined
+    expiresAt: number | undefined
+    value?: unknown
+    scope?: Set<string>
+    settled?: boolean
+    refreshing?: boolean
+    invalidation?: InvalidationState
+}
+
+/* Per-key invalidate coalescing: the throttle/debounce policy plus the timer/in-flight state. */
+export type InvalidationState = {
+    refetch: () => Promise<unknown>
+    throttle?: number
+    debounce?: number
+    lastFiredAt?: number
+    timer?: ReturnType<typeof setTimeout>
+}

package/src/lib/shared/types/CacheInvalidation.ts

@@ -0,0 +1,9 @@
+/*
+Detail payload of the cache store's 'invalidate' event — the set of cache
+keys one invalidation touched. A Set so each subscriber's membership check
+is O(1) regardless of how many keys a single invalidate spans. Shared
+between both dispatchers (cache.invalidate + streamed-resolution settling)
+and the cache store's listener, so the event's shape has one definition
+instead of an inline cast repeated at every site.
+*/
+export type CacheInvalidation = Set<string>

package/src/lib/shared/types/CacheOptions.ts

@@ -0,0 +1,33 @@
+/*
+Options for cache(). The key is always auto-derived (method+url+args for a remote
+function, producer-reference+args for a plain producer): hoist a producer to a
+stable reference to share its entry across calls. `ttl` is the
+milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
+dedupe only (entry dropped once the promise settles), any other number = TTL.
+`scope` is one or more free-form tags grouping unrelated calls so one
+`cache.invalidate({ scope })` drops every entry sharing any of them — pass an
+array when a call belongs to multiple invalidation groups. A unique tag (e.g. a
+uuid) shared by a set of calls gives them their own private invalidation group.
+
+`global` opts the entry into the process-level store instead of the default
+request-scoped one (server) — so a value computed in one request is reused by
+later requests, e.g. memoising an external endpoint the server calls. Omit it
+for per-request data: the default keeps a per-user response from leaking across
+requests. Write only `global: true`; there is no `false` form. On the client
+there is a single tab store, so the flag is a no-op there.
+
+`invalidate` controls how a `cache.invalidate` hit on this key is applied, in ms.
+`{ throttle: N }` refetches on the leading edge then at most once per N ms while
+invalidations keep arriving; `{ debounce: N }` refetches only after N ms of
+quiet. Both coalesce a burst of invalidations (e.g. a socket spraying
+`cache.invalidate`) into far fewer calls and keep serving the existing (stale)
+value until the refetch resolves — stale-while-revalidate. They affect only the
+refetch-after-invalidate; the first fetch and arg-change fetches stay immediate.
+Set at most one.
+*/
+export type CacheOptions = {
+    ttl?: number
+    scope?: string | string[]
+    global?: boolean
+    invalidate?: { throttle?: number; debounce?: number }
+}

package/src/lib/shared/types/CacheSnapshot.ts

@@ -0,0 +1,16 @@
+import type { CacheEntry } from './CacheEntry.ts'
+import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
+
+/*
+The SSR partition of a request's cache, read after `render()` returns.
+`inline` are entries settled by then (consumed via `await`, so render blocked
+on them) — they ship in the first chunk's `__SSR__` blob. `pending` are
+GET/DELETE entries still in flight (consumed via `{#await}`, which render emits
+as a pending branch without blocking) — the streamer awaits each and pushes a
+`__belteResolve` chunk as it lands. Non-GET/DELETE pending entries are dropped:
+they can't be snapshotted, so the client re-fetches them live on cache miss.
+*/
+export type CacheSnapshot = {
+    inline: CacheSnapshotEntry[]
+    pending: CacheEntry[]
+}