@briancray/belte 0.3.1 → 0.5.0

package/bin/belte.ts

@@ -26,6 +26,26 @@ function parseFlag(name: string): string | undefined {
     return undefined
 }
 
+/*
+Runs the server as a child and owns its shutdown. Ctrl+C delivers SIGINT to
+the whole foreground process group, so without a parent handler the parent's
+default action kills it instantly — abandoning the `await child.exited` and
+orphaning the child, which can then linger holding the port. Forwarding the
+signal and awaiting the child's exit (with a SIGKILL watchdog for a wedged
+child) guarantees the child is reaped before the parent leaves. Mirrors the
+child's exit code so callers and CI see the real result.
+*/
+async function runServerChild(cmd: string[]): Promise<never> {
+    const child = Bun.spawn({ cmd, cwd, stdio: ['inherit', 'inherit', 'inherit'] })
+    const forward = (signal: NodeJS.Signals) => {
+        child.kill(signal)
+        setTimeout(() => child.kill('SIGKILL'), 3000).unref()
+    }
+    process.on('SIGINT', () => forward('SIGINT'))
+    process.on('SIGTERM', () => forward('SIGTERM'))
+    process.exit(await child.exited)
+}
+
 /*
 Spawns the server under `bun --watch` against the dev entry. The dev entry
 re-runs the client build and eagerly imports every page/layout/rpc/socket
@@ -34,12 +54,7 @@ restarts the whole process whenever any file in the graph changes. The
 browser is not auto-reloaded — refresh manually after the server is back.
 */
 async function dev(): Promise<void> {
-    const child = Bun.spawn({
-        cmd: ['bun', '--watch', '--preload', PRELOAD, DEV_ENTRY],
-        cwd,
-        stdio: ['inherit', 'inherit', 'inherit'],
-    })
-    process.exit(await child.exited)
+    await runServerChild(['bun', '--watch', '--preload', PRELOAD, DEV_ENTRY])
 }
 
 // Performs a single client build with no server attached (for CI / static deploys).
@@ -48,14 +63,8 @@ async function buildOnce(): Promise<void> {
 }
 
 // Starts the production server against an already-built dist directory.
-// Awaits the child process so the parent's exit code mirrors the server's.
 async function start(): Promise<void> {
-    const child = Bun.spawn({
-        cmd: ['bun', '--preload', PRELOAD, SERVER_ENTRY],
-        cwd,
-        stdio: ['inherit', 'inherit', 'inherit'],
-    })
-    process.exit(await child.exited)
+    await runServerChild(['bun', '--preload', PRELOAD, SERVER_ENTRY])
 }
 
 // Parses the --target and --out flags and produces a standalone executable.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.3.1",
+    "version": "0.5.0",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/appEntry.ts

@@ -7,6 +7,7 @@ import programName from './_virtual/cli-name.ts'
 import type { BundleMenu } from './lib/bundle/BundleMenu.ts'
 import type { BundleWindow } from './lib/bundle/BundleWindow.ts'
 import { openWebview } from './lib/bundle/openWebview.ts'
+import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
 import { log } from './lib/shared/log.ts'
 
 /*
@@ -31,6 +32,14 @@ The window owns the main thread; on close we tell the worker to reap its child.
 const window = bundleWindow as BundleWindow
 const title = window.title ?? programName
 
+/*
+Derive the config form's JSON Schema here (the worker can't import the virtual
+that carries window.config) and pass the plain object through init — the
+validator itself isn't serializable, but its JSON Schema is. Undefined when the
+app declares no config, so the connect screen never gates Start.
+*/
+const configSchema = window.config ? jsonSchemaForSchema(window.config, undefined) : undefined
+
 /*
 Spawn the control server worker. `__BELTE_WORKER_ENTRY__` is the worker's absolute
 path, injected by bundleApp via Bun's `define` so the specifier is a static literal
@@ -49,15 +58,22 @@ worker.addEventListener('error', (event: ErrorEvent) => {
 // Hand the worker the plugin-resolved data it can't import itself, then start it.
 worker.postMessage({
     type: 'init',
-    init: { disconnectedHtml: disconnectedHtml as string, title, programName },
+    init: { disconnectedHtml: disconnectedHtml as string, title, programName, configSchema },
 })
 
-// The worker posts its control-server origin once bound; the window points here.
-const origin = await new Promise<string>((resolve) => {
+/*
+The worker, once bound, resolves where the window should open and posts both the
+control-server `origin` (for the File-menu action URLs) and the `target` to point
+the window at now: the live server when it could resume the last connection, else
+the connect screen. Resolving before this means a successful resume opens straight
+at the app — no connect-screen flash — at the cost of a brief window-less moment
+while it boots/probes (the OS shows the launching dock icon meanwhile).
+*/
+const { origin, target } = await new Promise<{ origin: string; target: string }>((resolve) => {
     worker.addEventListener('message', (event: MessageEvent) => {
-        const data = event.data as { type: string; origin?: string }
-        if (data.type === 'ready' && data.origin) {
-            resolve(data.origin)
+        const data = event.data as { type: string; origin?: string; target?: string }
+        if (data.type === 'ready' && data.origin && data.target) {
+            resolve({ origin: data.origin, target: data.target })
         }
     })
 })
@@ -89,9 +105,9 @@ const fileMenu: { label: string; items: FileMenuItem[] } = {
     ],
 }
 
-log.info(`opening ${title} connect screen at ${origin}`)
+log.info(`opening ${title} window at ${target}`)
 await openWebview({
-    url: origin,
+    url: target,
     title,
     width: window.width,
     height: window.height,

package/src/buildDisconnected.ts

@@ -116,6 +116,9 @@ function composeHtml({ js, css, logo }: { js: string; css: string; logo: string
 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 <!--belte:connect-config-->
 <script>${escapeScriptBody(logoScript)}</script>
+<!-- Paint the screen background before the client mounts, so there's no white
+flash ahead of the splash (gray-50 / gray-950 to match the rendered screen). -->
+<style>html,body{margin:0;background:#f9fafb}@media (prefers-color-scheme:dark){html,body{background:#030712}}</style>
 <style>${css}</style>
 </head>
 <body>

package/src/bundleApp.ts

@@ -4,6 +4,7 @@ import { ensureWebviewLib } from './lib/bundle/ensureWebviewLib.ts'
 import { infoPlist } from './lib/bundle/infoPlist.ts'
 import { pngToIcns } from './lib/bundle/pngToIcns.ts'
 import { serverBinaryFilename } from './lib/bundle/serverBinaryFilename.ts'
+import { signMacApp } from './lib/bundle/signMacApp.ts'
 import { webviewLibName } from './lib/bundle/webviewLibName.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
 import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
@@ -17,8 +18,9 @@ const WORKER_ENTRY = new URL('./controlServerWorker.ts', import.meta.url).pathna
 
 /*
 Assembles a movable, self-contained app bundle for the host platform —
-no signing, no cross-compilation. Three pieces travel together so the app
-runs on another machine of the same OS with nothing installed:
+no cross-compilation, and on macOS an ad-hoc seal so it launches on other
+Macs (signMacApp). Three pieces travel together so the app runs on another
+machine of the same OS with nothing installed:
 
   - the standalone server binary (`compile()`, assets embedded)
   - the launcher binary (appEntry — spawns the server, opens the webview)
@@ -54,6 +56,18 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
     // connect-screen build that writes into dist.
     await compile({ cwd, target, outfile: `${binDir}/${serverBinaryFilename()}` })
 
+    /*
+    Opt-in: ship the project's `.env.bundle` as the binary-dir `.env`, which the
+    server loads at boot (loadEnvFromBinaryDir) as its default config layer. A
+    dedicated file, never the working `.env` — a compiled bundle is extractable,
+    so only ship-safe defaults belong here; user-specific/secret values come from
+    the data-dir `.env` instead. Skipped when absent.
+    */
+    const bundleEnv = Bun.file(`${cwd}/.env.bundle`)
+    if (await bundleEnv.exists()) {
+        await Bun.write(`${binDir}/.env`, bundleEnv)
+    }
+
     // 2. Connect screen — bake dist/bundle-disconnected.html before the launcher
     // build, which inlines it via the belte:bundle-disconnected virtual.
     await buildDisconnected({ cwd, svelteConfig })
@@ -106,6 +120,14 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
             `${bundleRoot}/Contents/Info.plist`,
             infoPlist({ name: programName, version, icon: hasIcon ? 'icon' : undefined }),
         )
+
+        // Seal the finished bundle so it launches on other Macs — must run last,
+        // after every binary, the lib, and Info.plist are in place.
+        await signMacApp(bundleRoot, [
+            `${libDir}/${webviewLibName()}`,
+            `${binDir}/${serverBinaryFilename()}`,
+            launcherPath,
+        ])
     }
 
     log.success(`bundled app: ${bundleRoot} (target: ${target})`)

package/src/controlServerWorker.ts

@@ -1,3 +1,5 @@
+import { mkdir, rm } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
 import { bindConnectedFlag } from './lib/bundle/bindConnectedFlag.ts'
 import { bindRequestNavigate } from './lib/bundle/bindRequestNavigate.ts'
 import { findFreePort } from './lib/bundle/findFreePort.ts'
@@ -7,7 +9,10 @@ import { resolveServerBinary } from './lib/bundle/resolveServerBinary.ts'
 import { resolveWebviewLib } from './lib/bundle/resolveWebviewLib.ts'
 import { stableLocalPort } from './lib/bundle/stableLocalPort.ts'
 import { waitForServer } from './lib/bundle/waitForServer.ts'
+import { appDataDir } from './lib/shared/appDataDir.ts'
 import { log } from './lib/shared/log.ts'
+import { readEnvFile } from './lib/shared/readEnvFile.ts'
+import { serializeEnv } from './lib/shared/serializeEnv.ts'
 
 /*
 The bundle's control server, run in a Worker so it owns its own thread.
@@ -34,15 +39,28 @@ window back to the connect screen, since a dead server (local crash or remote
 outage) otherwise leaves a frozen page and a menu that still claims connected.
 
   GET  /                   → the connect screen (title injected at serve time)
+  GET  /__belte/config     → { schema, values } for the first-run config form
+  POST /__belte/config     → persist the form's answers to the data-dir .env
   POST /connect {url}      → record connected, reply { redirect: url }
   POST /start              → spawn the server binary, reply { redirect: localUrl }
   GET  /__belte/disconnect → reap the child, clear connected
 */
 
-// Init payload from the launcher, plus the per-run state the handlers close over.
-type Init = { disconnectedHtml: string; title: string; programName: string }
+/*
+Init payload from the launcher, plus the per-run state the handlers close over.
+`configSchema` is the JSON Schema derived from the app's BundleWindow.config
+(undefined when none declared), driving the connect screen's first-run form.
+*/
+type Init = {
+    disconnectedHtml: string
+    title: string
+    programName: string
+    configSchema?: Record<string, unknown>
+}
 let disconnectedHtml = ''
 let title = ''
+let programName = ''
+let configSchema: Record<string, unknown> | undefined
 let flag: ReturnType<typeof bindConnectedFlag> | undefined
 let server: ReturnType<typeof listenLocalControlServer> | undefined
 
@@ -142,21 +160,98 @@ Spawns the sibling server binary on a free port and waits for it to answer,
 returning the URL to point the window at. Any previous child is reaped first so
 only one embedded server runs at a time.
 */
-async function startEmbeddedServer(): Promise<string> {
+async function startEmbeddedServer(timeoutMs?: number): Promise<string> {
     killServerChild()
     const port = findFreePort()
     const url = `http://localhost:${port}`
     serverChild = Bun.spawn({
         cmd: [resolveServerBinary()],
         // BELTE_PARENT_PID lets the child exit if the launcher is force-quit
-        // (a clean window close reaps it directly; see exitWithParent).
+        // (a clean window close reaps it directly; see exitWithParent). The
+        // server resolves its own config from its data-dir/binary-dir .env at
+        // boot (see serverEntry), so the launcher injects nothing else.
         env: { ...process.env, PORT: String(port), BELTE_PARENT_PID: String(process.pid) },
         stdio: ['inherit', 'inherit', 'inherit'],
     })
-    await waitForServer(url)
+    /*
+    Race readiness against the child's exit. A misconfigured bundle (missing env
+    the server needs to bind) crashes immediately; without this the launcher
+    would wait out waitForServer's full timeout and report a generic stall
+    instead of the actual crash. The exit branch resolves (never rejects) so the
+    race loser still pending after a successful boot can't surface as an
+    unhandled rejection when the child is later reaped on disconnect.
+    */
+    const exited = serverChild.exited
+    const outcome = await Promise.race([
+        waitForServer(url, timeoutMs ? { timeoutMs } : undefined).then(() => undefined),
+        exited,
+    ])
+    if (outcome !== undefined) {
+        throw new Error(`[belte] embedded server exited (code ${outcome}) before binding`)
+    }
     return url
 }
 
+/*
+Where the window should point on launch, resolved before it ever opens so the
+connect screen never flashes. Repeats the last connection from the launcher-owned
+record (which survives relaunch where the embedded server's fresh port can't):
+
+  - embedded, config complete → boot it and point at the live server
+  - embedded, config missing  → the connect screen, so the user can configure
+  - remote url, still alive   → point straight at it
+  - remote url, now dead       → the connect screen with a `lost` notice
+  - nothing recorded           → the connect screen
+
+Boot is bounded by a short ceiling: a failed or slow boot falls back to the
+connect screen rather than leaving the launcher window-less, and reaps the child
+so a half-started server doesn't hold its port.
+*/
+const AUTO_START_CEILING_MS = 3000
+async function resolveLaunchTarget(): Promise<string> {
+    const last = await readLastConnection()
+    if (!last) {
+        return controlOrigin
+    }
+    if (last.kind === 'embedded') {
+        if (await autoStartBlockedByConfig()) {
+            return controlOrigin
+        }
+        try {
+            const url = await startEmbeddedServer(AUTO_START_CEILING_MS)
+            flag?.setConnected(true)
+            startLivenessWatch(url)
+            log.info(`resumed embedded server at ${url}`)
+            return url
+        } catch (error) {
+            killServerChild()
+            log.warn(`embedded server did not resume: ${String(error)}`)
+            return controlOrigin
+        }
+    }
+    const identity = await probeBelteServer(last.url)
+    if (identity) {
+        flag?.setConnected(true)
+        startLivenessWatch(last.url)
+        log.info(`reconnected to ${identity.name} at ${last.url}`)
+        return last.url
+    }
+    log.warn(`saved server did not respond: ${last.url}`)
+    return `${controlOrigin}/?action=lost`
+}
+
+// True when the app declares required config that nothing yet supplies, so an
+// embedded auto-start would only crash for the lack of it — land on the connect
+// screen (and its setup modal) instead.
+async function autoStartBlockedByConfig(): Promise<boolean> {
+    const required = (configSchema?.required as string[] | undefined) ?? []
+    if (required.length === 0) {
+        return false
+    }
+    const values = await resolveConfigValues()
+    return required.some((key) => !values[key])
+}
+
 /*
 Injects the app title into the connect-screen HTML just before serving — the build
 left a `<!--belte:connect-config-->` marker in <head>.
@@ -167,6 +262,83 @@ function renderConnectScreen(): Response {
     return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } })
 }
 
+// The data-dir `.env` the form writes and the server loads first at boot.
+function dataDirEnvPath(): string {
+    return join(appDataDir(programName), '.env')
+}
+
+/*
+Resolves the value to pre-fill each config field with, following the same
+precedence the server applies below the shell: the user's saved data-dir `.env`,
+then the bundle's shipped binary-dir `.env`, then the schema's own `default`.
+Empty string when nothing supplies it — which is how the form spots an unmet
+required field.
+*/
+async function resolveConfigValues(): Promise<Record<string, string>> {
+    const properties = (configSchema?.properties ?? {}) as Record<string, { default?: unknown }>
+    // Independent reads — fetch together; precedence is applied in the merge below.
+    const [dataDirEnv, binaryDirEnv] = await Promise.all([
+        readEnvFile(dataDirEnvPath()),
+        readEnvFile(join(dirname(resolveServerBinary()), '.env')),
+    ])
+    return Object.fromEntries(
+        Object.keys(properties).map((key) => {
+            const fallback = properties[key]?.default
+            const value =
+                dataDirEnv[key] ??
+                binaryDirEnv[key] ??
+                (fallback === undefined ? '' : String(fallback))
+            return [key, value]
+        }),
+    )
+}
+
+/*
+Persists the form's answers to the data-dir `.env`, merged over any existing
+file so keys the form didn't touch survive. Creates the data dir on first run
+(appDataDir only computes the path).
+*/
+async function writeConfig(values: Record<string, string>): Promise<void> {
+    const path = dataDirEnvPath()
+    const merged = { ...(await readEnvFile(path)), ...values }
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(path, serializeEnv(merged))
+}
+
+/*
+The launcher-owned record of the last connection, in the data dir so it survives
+relaunch and is readable before the window opens — unlike the webview's
+localStorage, and unlike the embedded server's URL, which can't be persisted
+because it picks a fresh port each launch (so we record the intent, not the URL).
+resolveLaunchTarget reads it; /connect and /start write it; /disconnect clears it.
+*/
+type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }
+
+function lastConnectionPath(): string {
+    return join(appDataDir(programName), 'last-connection.json')
+}
+
+async function readLastConnection(): Promise<LastConnection | undefined> {
+    const file = Bun.file(lastConnectionPath())
+    if (!(await file.exists())) {
+        return undefined
+    }
+    try {
+        return (await file.json()) as LastConnection
+    } catch {
+        return undefined
+    }
+}
+
+async function writeLastConnection(value: LastConnection): Promise<void> {
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(lastConnectionPath(), JSON.stringify(value))
+}
+
+async function clearLastConnection(): Promise<void> {
+    await rm(lastConnectionPath(), { force: true })
+}
+
 /*
 The control server's request handler. The connect screen owns localStorage +
 navigation; this worker owns the embedded-server process and the native flag.
@@ -176,6 +348,18 @@ async function handleControlRequest(request: Request): Promise<Response> {
     if (request.method === 'GET' && url.pathname === '/') {
         return renderConnectScreen()
     }
+    if (request.method === 'GET' && url.pathname === '/__belte/config') {
+        // No schema declared → null tells the form to skip the gate entirely.
+        if (!configSchema) {
+            return Response.json({ schema: null, values: {} })
+        }
+        return Response.json({ schema: configSchema, values: await resolveConfigValues() })
+    }
+    if (request.method === 'POST' && url.pathname === '/__belte/config') {
+        const { values } = (await request.json()) as { values: Record<string, string> }
+        await writeConfig(values)
+        return new Response(undefined, { status: 204 })
+    }
     if (request.method === 'POST' && url.pathname === '/connect') {
         const { url: target } = (await request.json()) as { url: string }
         // Verify it's actually a belte server before pointing the window at it.
@@ -189,6 +373,8 @@ async function handleControlRequest(request: Request): Promise<Response> {
         }
         flag?.setConnected(true)
         startLivenessWatch(target)
+        // Record the choice so the next launch reconnects here before opening.
+        await writeLastConnection({ kind: 'url', url: target })
         log.info(`connecting to ${identity.name} at ${target}`)
         return Response.json({ redirect: target })
     }
@@ -197,6 +383,8 @@ async function handleControlRequest(request: Request): Promise<Response> {
             const localUrl = await startEmbeddedServer()
             flag?.setConnected(true)
             startLivenessWatch(localUrl)
+            // Record the choice so the next launch boots the embedded server first.
+            await writeLastConnection({ kind: 'embedded' })
             log.info(`started embedded server at ${localUrl}`)
             return Response.json({ redirect: localUrl })
         } catch (error) {
@@ -208,6 +396,8 @@ async function handleControlRequest(request: Request): Promise<Response> {
         stopLivenessWatch()
         killServerChild()
         flag?.setConnected(false)
+        // Forget the auto-resume choice so the next launch lands on the connect screen.
+        await clearLastConnection()
         return new Response(undefined, { status: 204 })
     }
     return new Response('not found', { status: 404 })
@@ -216,18 +406,26 @@ async function handleControlRequest(request: Request): Promise<Response> {
 /*
 Bind the control server to 127.0.0.1 literally (not `localhost`) so the webview
 reaches it without any IPv4/IPv6 name-resolution ambiguity, open the native flag
-handle, and hand the launcher the origin to navigate the window at.
+handle, then resolve where the window should open before handing back. Resolving
+the launch target here — booting/probing the last connection before `ready` — is
+what lets the launcher open the window straight at the live server, so the
+connect screen never flashes; only an unconfigured, failed, or absent resume
+falls back to it. The launcher gets both `origin` (for the File-menu actions) and
+`target` (where to point the window now).
 */
 async function start(init: Init): Promise<void> {
     disconnectedHtml = init.disconnectedHtml
     title = init.title
+    programName = init.programName
+    configSchema = init.configSchema
     const libPath = await resolveWebviewLib()
     flag = bindConnectedFlag(libPath)
     navigate = bindRequestNavigate(libPath)
     server = listenLocalControlServer(stableLocalPort(init.programName), handleControlRequest)
     controlOrigin = `http://127.0.0.1:${server.port}`
     log.info(`${title} control server listening at ${controlOrigin}`)
-    self.postMessage({ type: 'ready', origin: controlOrigin })
+    const target = await resolveLaunchTarget()
+    self.postMessage({ type: 'ready', origin: controlOrigin, target })
 }
 
 // Reap the child + release the server and FFI handles, then confirm so the

package/src/discoveryEntry.ts

@@ -2,7 +2,10 @@
 import { rpc } from './_virtual/rpc.ts'
 // @ts-expect-error virtual module resolved by belteResolverPlugin
 import { sockets } from './_virtual/sockets.ts'
+import type { CliManifestEntry } from './lib/cli/types/CliManifestEntry.ts'
 import { verbRegistry } from './lib/server/rpc/verbRegistry.ts'
+import { socketOperations } from './lib/server/sockets/socketOperations.ts'
+import { socketRegistry } from './lib/server/sockets/socketRegistry.ts'
 import { commandNameForUrl } from './lib/shared/commandNameForUrl.ts'
 import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
 
@@ -18,17 +21,61 @@ await Promise.all([
     ...Object.values(sockets).map((loader) => (loader as () => Promise<unknown>)()),
 ])
 
-const manifest = Object.fromEntries(
-    Array.from(verbRegistry.values())
-        .filter((entry) => entry.clients.cli)
-        .map((entry) => [
-            commandNameForUrl(entry.remote.url),
-            {
-                method: entry.remote.method,
-                url: entry.remote.url,
-                jsonSchema: jsonSchemaForSchema(entry.schema, entry.jsonSchema),
+const manifest: Record<string, CliManifestEntry> = {}
+
+for (const entry of verbRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    manifest[commandNameForUrl(entry.remote.url)] = {
+        method: entry.remote.method,
+        url: entry.remote.url,
+        jsonSchema: jsonSchemaForSchema(entry.inputSchema, entry.inputJsonSchema),
+    }
+}
+
+/*
+Sockets advertised to the CLI become commands against the socket's HTTP
+face (see socketOperations): `<base>-tail` streams live (GET +
+text/event-stream, with an optional --tail N to replay recent history
+first) and, when clientPublish is set, `<base>-publish` sends the args bag
+as a message (POST).
+*/
+for (const entry of socketRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    for (const operation of socketOperations(entry)) {
+        if (operation.kind === 'tail') {
+            manifest[operation.name] = {
+                method: operation.method,
+                url: operation.restUrl,
+                accept: 'text/event-stream',
+                jsonSchema: {
+                    type: 'object',
+                    description: `tail the "${operation.socketName}" socket`,
+                    properties: {
+                        tail: {
+                            type: 'number',
+                            description: 'replay last N messages before tailing live',
+                        },
+                    },
+                },
+            }
+            continue
+        }
+        const payloadSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
+        manifest[operation.name] = {
+            method: operation.method,
+            url: operation.restUrl,
+            jsonSchema: {
+                ...payloadSchema,
+                description:
+                    (payloadSchema.description as string | undefined) ??
+                    `publish a message to the "${operation.socketName}" socket`,
             },
-        ]),
-)
+        }
+    }
+}
 
 process.stdout.write(JSON.stringify(manifest))

package/src/lib/browser/cache.ts

@@ -5,6 +5,7 @@ import { canonicalJson } from '../shared/canonicalJson.ts'
 import { decodeResponse } from '../shared/decodeResponse.ts'
 import { getRemoteMeta } from '../shared/getRemoteMeta.ts'
 import { keyForRemoteCall } from '../shared/keyForRemoteCall.ts'
+import type { CacheEntry } from '../shared/types/CacheEntry.ts'
 import type { CacheOptions } from '../shared/types/CacheOptions.ts'
 
 type AnyRemote<Args, Return> = RemoteFunction<Args, Return> | RawRemoteFunction<Args>
@@ -46,7 +47,7 @@ export function cache<Args>(
 export function cache<Args, Return>(
     fn: AnyRemote<Args, Return>,
     options?: CacheOptions,
-): (args?: Args) => Promise<Return | Response> {
+): (args?: Args) => Promise<Return | Response> | Return {
     /*
     The "raw" variant lacks its own `.raw` sibling; only the decoded
     callable carries one. Tell them apart by that presence and dispatch the
@@ -55,20 +56,42 @@ export function cache<Args, Return>(
     const isRaw = !('raw' in fn)
     const rawFn = isRaw ? (fn as RawRemoteFunction<Args>) : (fn as RemoteFunction<Args, Return>).raw
     return (args) => {
-        const responsePromise = invokeWithCache(rawFn, args, options)
+        const store = activeCacheStore()
+        const key = resolveKey(rawFn, args, options?.key)
+        store.subscribe(key)
+        const existing = store.entries.get(key)
+        /*
+        Snapshot warm path: hydration pre-decoded the SSR body onto the
+        entry, so the decoded variant returns it synchronously — the first
+        {#await} render resolves without a microtask suspension and matches
+        the SSR DOM. Raw callers always take the Response path. After an
+        invalidate the replacement entry carries no value and falls through
+        to the async fetch as before.
+
+        The public overload stays typed Promise<Return> on purpose: a
+        non-thenable is the only thing {#await} can render synchronously, so
+        the sync return is left as an internal optimization rather than
+        widened to `Return | Promise<Return>` (which would leak it into every
+        caller's types). The one cost is that `.then`/`.catch`/`.finally`
+        directly on a warm result throws — consume cache via `await`/`{#await}`,
+        never `.then`. Don't "fix" the type; see memory cache-warm-sync-tradeoff.
+        */
+        if (!isRaw && existing?.value !== undefined) {
+            return existing.value as Return
+        }
+        const responsePromise = invokeWithCache(store, key, existing, rawFn, args, options)
         return isRaw ? responsePromise : (responsePromise.then(decodeResponse) as Promise<Return>)
     }
 }
 
 function invokeWithCache<Args>(
+    store: ReturnType<typeof activeCacheStore>,
+    key: string,
+    existing: CacheEntry | undefined,
     rawFn: RawRemoteFunction<Args>,
     args: Args | undefined,
     options: CacheOptions | undefined,
 ): Promise<Response> {
-    const store = activeCacheStore()
-    const key = resolveKey(rawFn, args, options?.key)
-    store.subscribe(key)
-    const existing = store.entries.get(key)
     if (existing) {
         return shareable(existing.promise)
     }