@briancray/belte 0.4.0 → 0.5.1

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.4.0",
+    "version": "0.5.1",
     "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

@@ -56,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 })

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,11 @@ 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 { parsePort } from './lib/server/runtime/parsePort.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 +40,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 +161,115 @@ 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> {
+/*
+The port the embedded server binds. A `PORT` configured in the data-dir `.env`
+(where the config form writes), the shipped binary-dir `.env`, or the launcher's
+own env is honored — so the server answers at a fixed, known address another
+machine can reliably connect to. With none set, a free port is chosen (the
+historical behaviour). Precedence matches the server's own env stack: shell >
+data-dir > binary-dir. A configured port is used as-is and not second-guessed —
+if it's taken, the bind failure surfaces rather than silently moving.
+*/
+async function resolveEmbeddedPort(): Promise<number> {
+    const [dataDirEnv, binaryDirEnv] = await Promise.all([
+        readEnvFile(dataDirEnvPath()),
+        readEnvFile(binaryDirEnvPath()),
+    ])
+    return parsePort(process.env.PORT ?? dataDirEnv.PORT ?? binaryDirEnv.PORT) ?? findFreePort()
+}
+
+async function startEmbeddedServer(timeoutMs?: number): Promise<string> {
     killServerChild()
-    const port = findFreePort()
+    const port = await resolveEmbeddedPort()
     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 +280,88 @@ 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')
+}
+
+// The shipped `.env` beside the server binary (the bundle's default config layer).
+function binaryDirEnvPath(): string {
+    return join(dirname(resolveServerBinary()), '.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(binaryDirEnvPath()),
+    ])
+    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 +371,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 +396,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 +406,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 +419,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 +429,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/lib/bundle/BundleWindow.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '../server/rpc/types/StandardSchemaV1.ts'
 import type { BundleMenu } from './BundleMenu.ts'
 
 /*
@@ -17,4 +18,14 @@ export type BundleWindow = {
     width?: number
     height?: number
     menu?: BundleMenu[]
+    /*
+    Config the embedded server needs before it can run, as a Standard Schema (the
+    same kind belte accepts for RPC/MCP). Its JSON Schema drives the connect
+    screen's first-run form, shown as a modal when Start is clicked with a required
+    key still unset; the user's answers persist to the data-dir `.env` the server
+    loads at boot. Each property maps to one env var of the same name; `title` is
+    the field label, `description` the hint, `format: 'password'` masks the input,
+    and `default` pre-fills it.
+    */
+    config?: StandardSchemaV1
 }

package/src/lib/bundle/disconnected.svelte

@@ -11,20 +11,9 @@ connection so the native File menu's enabled state stays authoritative.
 */
 
 /*
-localStorage key holding the last connection so a relaunch repeats it: either a
-remote server URL, or the START_EMBEDDED sentinel meaning "boot the embedded
-server". The embedded server's own URL can't be persisted — it picks a fresh
-port each launch — so we persist the intent and re-run start() instead.
-Disconnect clears it so a relaunch never auto-retries a forgotten server.
-*/
-const STORAGE_KEY = 'belte:server-url'
-const START_EMBEDDED = 'belte:start-embedded'
-
-/*
-The last remote URL that successfully connected, kept separate from STORAGE_KEY
-so it survives disconnect (and the app quitting): it only prefills the form, it
-never drives an auto-reconnect, so reconnecting to the same server stays one
-click away even after an explicit disconnect.
+The last remote URL that successfully connected — only prefills the form's input
+on a later visit; it never drives a reconnect (the launcher owns auto-resume now,
+deciding before the window even opens). Survives disconnect and quitting.
 */
 const LAST_URL_KEY = 'belte:last-server-url'
 
@@ -36,9 +25,51 @@ const placeholder = 'https://example.com'
 
 // Prefill the form with the last server we connected to, from any prior launch.
 let url = $state(localStorage.getItem(LAST_URL_KEY) ?? '')
-let starting = $state(false)
 let error = $state<string | undefined>(undefined)
 
+/*
+`?action=` set by the File menu (Start/Disconnect) or the launcher when a live
+connection dies (`lost`). Auto-resume of a saved connection now happens in the
+launcher before the window opens, so this screen only ever loads as a real
+destination — there's no no-action auto-resume left to handle here.
+*/
+const launchAction = new URLSearchParams(location.search).get('action')
+
+/*
+Two phases so the screen never flashes before a redirect. A menu Start may boot
+straight through, so it opens on a neutral splash; every other entry is a genuine
+destination, so the connect screen shows immediately. Boot/connect re-enter the
+splash so a redirect (including after saving config) never flashes the form.
+*/
+let phase = $state<'splash' | 'connect'>(launchAction === 'start' ? 'splash' : 'connect')
+
+/*
+First-run config form, surfaced as a modal only when Start is clicked (or
+auto-start fires) with a required key still unset. Fields are derived from the
+app's config JSON Schema served by the launcher; answers post back to the
+data-dir `.env` the embedded server loads at boot.
+*/
+type ConfigField = {
+    key: string
+    label: string
+    description?: string
+    inputType: 'text' | 'password' | 'number' | 'checkbox'
+    required: boolean
+}
+let configFields = $state<ConfigField[]>([])
+let configValues = $state<Record<string, string>>({})
+let showConfig = $state(false)
+let savingConfig = $state(false)
+// Every required field has a value — gates the modal's Save button.
+const canSaveConfig = $derived(
+    configFields.every(
+        (field) =>
+            !field.required ||
+            field.inputType === 'checkbox' ||
+            (configValues[field.key] ?? '').trim() !== '',
+    ),
+)
+
 /*
 Interpret the boot intent once on load. `?action=` is set by the native File
 menu's navigate items (or the launcher when a live connection dies); absent it, a
@@ -51,30 +82,19 @@ remembered server reconnects automatically:
   - (none)     → reconnect to the saved server if there is one.
 */
 $effect(() => {
-    const action = new URLSearchParams(location.search).get('action')
-    const saved = localStorage.getItem(STORAGE_KEY) ?? undefined
-    if (action === 'start') {
+    if (launchAction === 'start') {
+        // File-menu Start Server is an explicit click → run the Start flow.
         void start()
         return
     }
-    if (action === 'lost') {
+    if (launchAction === 'lost') {
         error = 'The server stopped responding.'
         return
     }
-    if (action === 'disconnect') {
-        // Forget the auto-reconnect intent but keep LAST_URL_KEY, so the form
-        // stays prefilled with the server we just left for a one-click return.
-        localStorage.removeItem(STORAGE_KEY)
+    if (launchAction === 'disconnect') {
+        // Have the launcher forget the auto-resume choice and reap any embedded
+        // server; LAST_URL_KEY stays so the form is still prefilled to reconnect.
         void fetch('/__belte/disconnect').catch(() => {})
-        return
-    }
-    // No action: repeat the last choice — re-boot the embedded server, or reconnect.
-    if (saved === START_EMBEDDED) {
-        void start()
-        return
-    }
-    if (saved) {
-        void connect(saved)
     }
 })
 
@@ -92,6 +112,8 @@ async function connect(target: string = url.trim()): Promise<void> {
         return
     }
     error = undefined
+    // Hide the form while connecting so a successful redirect doesn't flash it.
+    phase = 'splash'
     try {
         const response = await fetch('/connect', {
             method: 'POST',
@@ -103,21 +125,44 @@ async function connect(target: string = url.trim()): Promise<void> {
             throw new Error(body.error ?? `connect failed (${response.status})`)
         }
         const { redirect } = (await response.json()) as { redirect: string }
-        localStorage.setItem(STORAGE_KEY, cleaned)
-        // Remember it separately so it outlives a later disconnect and prefills the form.
+        // Prefill the form with this server on a later visit (the launcher records
+        // the auto-resume choice itself, on the /connect it just handled).
         localStorage.setItem(LAST_URL_KEY, cleaned)
         location.href = redirect
     } catch (cause) {
         error = `Could not connect: ${String(cause)}`
+        // Failed — bring the form back so the error and a retry are visible.
+        phase = 'connect'
     }
 }
 
-// Boot the embedded server via the launcher, then follow it once it answers.
+/*
+Start, always an explicit click (button or File-menu) — auto-resume happens in
+the launcher before the window opens, so this is never a launch path. Asks the
+launcher what config the app needs: if it declares any, open the modal (prefilled
+with the last-used values) so the user can review or change settings before
+booting — re-running Start after a disconnect is how you reconfigure. With no
+config schema, boot straight through. The modal's save path resumes the boot.
+*/
 async function start(): Promise<void> {
     error = undefined
-    starting = true
-    // Remember the embedded-server choice so the next launch boots it automatically.
-    localStorage.setItem(STORAGE_KEY, START_EMBEDDED)
+    const config = await loadConfig().catch(() => undefined)
+    if (config) {
+        configFields = config.fields
+        configValues = { ...config.values }
+        // Reveal the connect screen as the modal's backdrop.
+        phase = 'connect'
+        showConfig = true
+        return
+    }
+    await boot()
+}
+
+// Boot the embedded server via the launcher, then follow it once it answers.
+async function boot(): Promise<void> {
+    // Splash while booting so the connect screen doesn't flash before the redirect
+    // (including straight after saving config).
+    phase = 'splash'
     try {
         const response = await fetch('/start', { method: 'POST' })
         if (!response.ok) {
@@ -128,11 +173,92 @@ async function start(): Promise<void> {
         location.href = redirect
     } catch (cause) {
         error = `Could not start the server: ${String(cause)}`
-        starting = false
+        // Boot failed — bring the connect screen back to show the error.
+        phase = 'connect'
+    }
+}
+
+/*
+Fetches the app's config schema + resolved current values from the launcher and
+turns the JSON Schema into render-ready fields. Returns undefined when no schema
+is declared, so Start never gates.
+*/
+async function loadConfig(): Promise<
+    { fields: ConfigField[]; values: Record<string, string> } | undefined
+> {
+    const response = await fetch('/__belte/config')
+    const { schema, values } = (await response.json()) as {
+        schema: Record<string, unknown> | null
+        values: Record<string, string>
+    }
+    if (!schema) {
+        return undefined
+    }
+    return { fields: fieldsFromSchema(schema), values: values ?? {} }
+}
+
+// Derives one render-ready field per JSON Schema property, reusing the standard
+// slots: `title` → label, `description` → hint, `format`/`type` → input kind.
+function fieldsFromSchema(schema: Record<string, unknown>): ConfigField[] {
+    const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>
+    const required = new Set((schema.required as string[]) ?? [])
+    return Object.entries(properties).map(([key, property]) => ({
+        key,
+        label: (property.title as string) ?? key,
+        description: property.description as string | undefined,
+        inputType: inputType(property),
+        required: required.has(key),
+    }))
+}
+
+// Maps a JSON Schema property to an HTML input kind (directory falls back to text
+// until a native picker exists).
+function inputType(property: Record<string, unknown>): ConfigField['inputType'] {
+    if (property.type === 'boolean') {
+        return 'checkbox'
+    }
+    if (property.type === 'number' || property.type === 'integer') {
+        return 'number'
+    }
+    if (property.format === 'password') {
+        return 'password'
+    }
+    return 'text'
+}
+
+// Persist the form's answers to the data-dir `.env`, then resume the boot.
+async function saveConfig(): Promise<void> {
+    error = undefined
+    savingConfig = true
+    try {
+        const response = await fetch('/__belte/config', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ values: configValues }),
+        })
+        if (!response.ok) {
+            throw new Error(`save failed (${response.status})`)
+        }
+        showConfig = false
+        savingConfig = false
+        await boot()
+    } catch (cause) {
+        error = `Could not save settings: ${String(cause)}`
+        savingConfig = false
     }
 }
 </script>
 
+{#if phase === 'splash'}
+    <!-- Neutral splash shown while an auto-start/auto-reconnect resolves, so the
+    connect screen never flashes before it redirects. Same background as the card. -->
+    <div
+        class="flex min-h-screen items-center justify-center bg-gray-50 dark:bg-gray-950">
+        {#if logo}
+            <img src={logo} alt="" class="h-16 w-16 rounded-xl object-contain opacity-90">
+        {/if}
+    </div>
+{:else}
 <main
     class="flex min-h-screen items-center justify-center bg-gray-50 p-6 text-gray-900 dark:bg-gray-950 dark:text-gray-100">
     <div
@@ -170,9 +296,8 @@ async function start(): Promise<void> {
         <button
             type="button"
             onclick={() => void start()}
-            disabled={starting}
-            class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium hover:bg-gray-50 disabled:opacity-60 dark:border-gray-700 dark:hover:bg-gray-800">
-            {starting ? 'Starting…' : 'Start server'}
+            class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium hover:bg-gray-50 dark:border-gray-700 dark:hover:bg-gray-800">
+            Start server
         </button>
 
         {#if error}
@@ -189,3 +314,74 @@ async function start(): Promise<void> {
         </p>
     </div>
 </main>
+{/if}
+
+{#if showConfig}
+    <!-- First-run config modal — shown only when Start needs settings the app lacks. -->
+    <div
+        class="fixed inset-0 z-10 flex items-center justify-center bg-black/40 p-6 text-gray-900 dark:text-gray-100">
+        <div
+            class="w-full max-w-sm rounded-2xl bg-white p-8 shadow-lg ring-1 ring-gray-200 dark:bg-gray-900 dark:ring-gray-800">
+            <h2 class="mb-5 text-lg font-semibold tracking-tight">Set up {heading}</h2>
+
+            <form
+                class="flex flex-col gap-4"
+                onsubmit={(event) => {
+                    event.preventDefault()
+                    void saveConfig()
+                }}>
+                {#each configFields as field (field.key)}
+                    <label class="flex flex-col gap-1 text-sm">
+                        <span class="font-medium">
+                            {field.label}
+                            {#if field.required}
+                                <span class="text-red-500">*</span>
+                            {/if}
+                        </span>
+                        {#if field.inputType === 'checkbox'}
+                            <input
+                                type="checkbox"
+                                checked={configValues[field.key] === 'true'}
+                                onchange={(event) =>
+                                    (configValues[field.key] = event.currentTarget.checked
+                                        ? 'true'
+                                        : 'false')}
+                                class="mt-1 size-4 self-start rounded border-gray-300 dark:border-gray-700">
+                        {:else}
+                            <input
+                                type={field.inputType}
+                                value={configValues[field.key] ?? ''}
+                                oninput={(event) =>
+                                    (configValues[field.key] = event.currentTarget.value)}
+                                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm outline-none focus:border-gray-900 focus:ring-1 focus:ring-gray-900 dark:border-gray-700 dark:bg-gray-800 dark:focus:border-gray-100 dark:focus:ring-gray-100">
+                        {/if}
+                        {#if field.description}
+                            <span class="text-xs text-gray-400 dark:text-gray-500">
+                                {field.description}
+                            </span>
+                        {/if}
+                    </label>
+                {/each}
+
+                <div class="mt-1 flex gap-3">
+                    <button
+                        type="button"
+                        onclick={() => (showConfig = false)}
+                        class="flex-1 rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium hover:bg-gray-50 dark:border-gray-700 dark:hover:bg-gray-800">
+                        Cancel
+                    </button>
+                    <button
+                        type="submit"
+                        disabled={!canSaveConfig || savingConfig}
+                        class="flex-1 rounded-lg bg-gray-900 px-3 py-2 text-sm font-medium text-white hover:bg-gray-700 disabled:opacity-60 dark:bg-gray-100 dark:text-gray-900 dark:hover:bg-gray-300">
+                        {savingConfig ? 'Saving…' : 'Save & start'}
+                    </button>
+                </div>
+            </form>
+
+            {#if error}
+                <p class="mt-4 text-center text-sm text-red-600 dark:text-red-400">{error}</p>
+            {/if}
+        </div>
+    </div>
+{/if}

package/src/lib/cli/loadEnvFromBinaryDir.ts

@@ -1,44 +1,14 @@
-import { existsSync } from 'node:fs'
 import { dirname } from 'node:path'
-
-const ENV_LINE = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/
+import { loadEnvFile } from '../shared/loadEnvFile.ts'
 
 /*
-Reads a `.env` next to the running binary (resolved via
-`process.execPath`) and merges each declared var into `process.env`
-only when not already set. The binary-dir `.env` is the file the
-install tarball ships next to the executable; per-shell exports and
-Bun's automatic CWD `.env` loading both naturally override it.
-
-Strips surrounding single or double quotes off values; otherwise the
-parser is intentionally minimal — no variable expansion, no escape
-handling, no multi-line. Matches what the install tarball writes.
+Loads a `.env` sitting next to the running binary (resolved via
+`process.execPath`) into `process.env`. This is the file the install tarball
+ships beside the executable — and, for a bundle, the one `bundleApp` copies
+from the project's `.env.bundle`. It carries the app's shipped defaults; the
+fill-when-unset merge (see loadEnvFile) lets per-shell exports, Bun's CWD
+`.env`, and the user's data-dir config all override it.
 */
 export async function loadEnvFromBinaryDir(): Promise<void> {
-    const binDir = dirname(process.execPath)
-    const envPath = `${binDir}/.env`
-    if (!existsSync(envPath)) {
-        return
-    }
-    const text = await Bun.file(envPath).text()
-    for (const line of text.split('\n')) {
-        if (!line || line.startsWith('#')) {
-            continue
-        }
-        const match = ENV_LINE.exec(line)
-        if (!match) {
-            continue
-        }
-        const [, key, rawValue] = match
-        if (process.env[key as string] !== undefined) {
-            continue
-        }
-        const trimmed = rawValue?.trim() ?? ''
-        const unquoted =
-            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-            (trimmed.startsWith("'") && trimmed.endsWith("'"))
-                ? trimmed.slice(1, -1)
-                : trimmed
-        process.env[key as string] = unquoted
-    }
+    await loadEnvFile(`${dirname(process.execPath)}/.env`)
 }

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

@@ -30,6 +30,7 @@ import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
 import { globToPathSet } from './globToPathSet.ts'
 import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
+import { parsePort } from './parsePort.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
 import { requestContext } from './requestContext.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
@@ -103,7 +104,7 @@ export async function createServer({
     distDir = `${process.cwd()}/dist`,
     publicDir = `${process.cwd()}/src/browser/public`,
     resourcesDir = `${process.cwd()}/src/mcp/resources`,
-    port = Number(process.env.PORT ?? 3000),
+    port = parsePort(process.env.PORT) ?? 3000,
 }: {
     pages: Pages
     rpc: RemoteRoutes
@@ -546,21 +547,28 @@ export async function createServer({
     */
     setActiveServer(server)
 
-    if (app?.init) {
-        const cleanup = await app.init({ server })
+    const cleanup = app?.init ? await app.init({ server }) : undefined
+    /*
+    Close the listener deterministically on shutdown. Always registered (even
+    with no init cleanup) so the socket is released via server.stop rather than
+    left to abrupt process exit — which leaves the port in TIME_WAIT and races
+    a fast restart. A watchdog force-exits if a user cleanup hangs, so a stuck
+    cleanup can't keep the process (and its port) alive.
+    */
+    const shutdown = async () => {
+        server.stop(true)
         if (typeof cleanup === 'function') {
-            const shutdown = async () => {
-                try {
-                    await cleanup()
-                } catch (err) {
-                    log.error(err)
-                }
-                process.exit(0)
+            setTimeout(() => process.exit(0), 3000).unref()
+            try {
+                await cleanup()
+            } catch (err) {
+                log.error(err)
             }
-            process.once('SIGINT', shutdown)
-            process.once('SIGTERM', shutdown)
         }
+        process.exit(0)
     }
+    process.once('SIGINT', shutdown)
+    process.once('SIGTERM', shutdown)
 
     log.success(`ready at http://localhost:${server.port}`)
     /*

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

@@ -0,0 +1,16 @@
+/*
+Parses a PORT env value into a usable TCP port, returning undefined for
+missing, empty, or out-of-range/non-integer input so the caller can fall back
+to a default. A bare Number() turns '' into 0 (a random kernel-assigned port)
+and 'abc' into NaN, both silently wrong; this rejects them instead.
+*/
+export function parsePort(value: string | undefined): number | undefined {
+    if (value === undefined || value.trim() === '') {
+        return undefined
+    }
+    const port = Number(value)
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        return undefined
+    }
+    return port
+}

package/src/lib/shared/appDataDir.ts

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/*
+Platform-standard per-user data directory for a bundle, keyed by its program
+name. cwd-independent on purpose: the path derives from `programName`, not the
+process working directory — which the OS `open` command sets to `/`, so anything
+relying on cwd (Bun's `.env` autoload, relative paths) finds nothing inside a
+launched `.app`. This is where a bundle keeps what can't be baked at compile time
+— the user's config, DB, and cache. macOS Application Support, Windows %APPDATA%,
+XDG data home elsewhere. Pure: computes the path, never touches the filesystem.
+*/
+export function appDataDir(programName: string): string {
+    const home = homedir()
+    if (process.platform === 'darwin') {
+        return join(home, 'Library', 'Application Support', programName)
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), programName)
+    }
+    return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), programName)
+}

package/src/lib/shared/loadEnvFile.ts

@@ -0,0 +1,17 @@
+import { readEnvFile } from './readEnvFile.ts'
+
+/*
+Reads a `.env` at `path` and merges each declared var into `process.env`
+only when not already set. Fill-when-unset is the precedence rule the whole
+env stack relies on: layers loaded earlier (shell/ambient, Bun's CWD `.env`)
+win, and later callers back-fill only what's still missing. So a value's
+source is invisible to the app — it reads one flat `process.env` (Bun.env is
+the same object). Missing file is a no-op.
+*/
+export async function loadEnvFile(path: string): Promise<void> {
+    for (const [key, value] of Object.entries(await readEnvFile(path))) {
+        if (process.env[key] === undefined) {
+            process.env[key] = value
+        }
+    }
+}

package/src/lib/shared/loadEnvFromDataDir.ts

@@ -0,0 +1,15 @@
+import { join } from 'node:path'
+import { appDataDir } from './appDataDir.ts'
+import { loadEnvFile } from './loadEnvFile.ts'
+
+/*
+Loads the user's `.env` from the program's per-user data dir into `process.env`.
+This is the cwd-independent config layer — where the connect-screen form writes
+the user's answers, and where a bundle launched via `open` (cwd `/`, so Bun's
+CWD `.env` autoload finds nothing) actually picks up its config. Loaded before
+the binary-dir `.env`, so a user's saved config overrides the shipped default;
+still loses to a shell export or a CWD `.env` (fill-when-unset, see loadEnvFile).
+*/
+export async function loadEnvFromDataDir(programName: string): Promise<void> {
+    await loadEnvFile(join(appDataDir(programName), '.env'))
+}

package/src/lib/shared/parseEnv.ts

@@ -0,0 +1,30 @@
+const ENV_LINE = /^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/
+
+/*
+Parses `.env` text into a key→value record. Skips blanks, comments, and
+malformed lines; strips a single layer of surrounding single or double quotes.
+Intentionally minimal — no variable expansion, escapes, or multi-line. The pure
+counterpart to loadEnvFile (which merges into process.env) and serializeEnv
+(which writes records back), so all three round-trip the same shape.
+*/
+export function parseEnv(text: string): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const line of text.split('\n')) {
+        if (!line || line.startsWith('#')) {
+            continue
+        }
+        const match = ENV_LINE.exec(line)
+        if (!match) {
+            continue
+        }
+        const [, key, rawValue] = match
+        const trimmed = rawValue?.trim() ?? ''
+        const unquoted =
+            (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'"))
+                ? trimmed.slice(1, -1)
+                : trimmed
+        result[key as string] = unquoted
+    }
+    return result
+}

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

@@ -25,10 +25,22 @@ import { shell } from './_virtual/shell.ts'
 // @ts-expect-error virtual module resolved by belteResolverPlugin
 import { sockets } from './_virtual/sockets.ts'
 import { exitWithParent } from './lib/bundle/exitWithParent.ts'
+import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
+import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { setCacheStoreResolver } from './lib/shared/setCacheStoreResolver.ts'
 
+/*
+Resolve config into process.env before anything reads it (createServer reads
+PORT, app code reads Bun.env.*). Data-dir first so the user's saved config wins
+over the binary-dir shipped default; both back-fill only what the shell or Bun's
+CWD `.env` didn't already set. A bundle launched via `open` has cwd `/`, so the
+data-dir `.env` is how it gets its config at all.
+*/
+await loadEnvFromDataDir(cliProgramName)
+await loadEnvFromBinaryDir()
+
 // In a bundle, tie this server's life to the launcher's (no-op standalone).
 exitWithParent()