@briancray/belte 0.5.1 → 0.5.3

package/package.json

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

package/src/belteResolverPlugin.ts

@@ -6,6 +6,7 @@ import { belteImportName } from './lib/shared/belteImportName.ts'
 import { fileStem } from './lib/shared/fileStem.ts'
 import { jsonSchemaForPromptArguments } from './lib/shared/jsonSchemaForPromptArguments.ts'
 import { log } from './lib/shared/log.ts'
+import { manifestModule } from './lib/shared/manifestModule.ts'
 import { pageUrlForFile } from './lib/shared/pageUrlForFile.ts'
 import { parsePromptMarkdown } from './lib/shared/parsePromptMarkdown.ts'
 import { prepareRpcModule } from './lib/shared/prepareRpcModule.ts'
@@ -315,111 +316,56 @@ ${optionLines}
 
             build.onLoad({ filter: /.*/, namespace: NS }, async (args) => {
                 if (args.path === 'belte:rpc') {
-                    const files = await scanRpcOnce()
-                    const byUrl = files
-                        .toSorted()
-                        .map((file) => ({ url: rpcUrlForFile(file), file }))
-                    const entries = byUrl
-                        .map(
-                            ({ url, file }) =>
-                                `    ${JSON.stringify(url)}: () => import(${JSON.stringify(`${rpcDir}/${file}`)}),`,
-                        )
-                        .join('\n')
-                    if (byUrl.length > 0) {
-                        log.info(
-                            `resolved ${byUrl.length} rpc modules: ${byUrl.map((b) => b.url).join(', ')}`,
-                        )
-                    }
-                    return {
-                        contents: `export const rpc = {\n${entries}\n}\n`,
-                        loader: 'js',
-                    }
+                    return manifestModule({
+                        files: await scanRpcOnce(),
+                        keyForFile: rpcUrlForFile,
+                        importDir: rpcDir,
+                        exportName: 'rpc',
+                        label: 'rpc modules',
+                    })
                 }
 
                 if (args.path === 'belte:sockets') {
-                    const files = await scanSocketsOnce()
-                    const byName = files
-                        .toSorted()
-                        .map((file) => ({ name: socketNameForFile(file), file }))
-                    const entries = byName
-                        .map(
-                            ({ name, file }) =>
-                                `    ${JSON.stringify(name)}: () => import(${JSON.stringify(`${socketsDir}/${file}`)}),`,
-                        )
-                        .join('\n')
-                    if (byName.length > 0) {
-                        log.info(
-                            `resolved ${byName.length} socket modules: ${byName.map((b) => b.name).join(', ')}`,
-                        )
-                    }
-                    return {
-                        contents: `export const sockets = {\n${entries}\n}\n`,
-                        loader: 'js',
-                    }
+                    return manifestModule({
+                        files: await scanSocketsOnce(),
+                        keyForFile: socketNameForFile,
+                        importDir: socketsDir,
+                        exportName: 'sockets',
+                        label: 'socket modules',
+                    })
                 }
 
                 if (args.path === 'belte:prompts') {
-                    const files = await scanPromptsOnce()
-                    const byName = files
-                        .toSorted()
-                        .map((file) => ({ name: promptNameForFile(file), file }))
-                    const entries = byName
-                        .map(
-                            ({ name, file }) =>
-                                `    ${JSON.stringify(name)}: () => import(${JSON.stringify(`${promptsDir}/${file}`)}),`,
-                        )
-                        .join('\n')
-                    if (byName.length > 0) {
-                        log.info(
-                            `resolved ${byName.length} prompt modules: ${byName.map((b) => b.name).join(', ')}`,
-                        )
-                    }
-                    return {
-                        contents: `export const prompts = {\n${entries}\n}\n`,
-                        loader: 'js',
-                    }
+                    return manifestModule({
+                        files: await scanPromptsOnce(),
+                        keyForFile: promptNameForFile,
+                        importDir: promptsDir,
+                        exportName: 'prompts',
+                        label: 'prompt modules',
+                    })
                 }
 
                 if (args.path === 'belte:pages') {
-                    const { pageFiles: files } = await scanPagesOnce()
-                    const byUrl = files
-                        .toSorted()
-                        .map((file) => ({ url: pageUrlForFile(file), file }))
-                    const entries = byUrl
-                        .map(
-                            ({ url, file }) =>
-                                `    ${JSON.stringify(url)}: () => import(${JSON.stringify(`${pagesDir}/${file}`)}),`,
-                        )
-                        .join('\n')
-                    log.info(
-                        `resolved ${byUrl.length} pages: ${byUrl.map((b) => b.url).join(', ')}`,
-                    )
-                    return {
-                        contents: `export const pages = {\n${entries}\n}\n`,
-                        loader: 'js',
-                    }
+                    const { pageFiles } = await scanPagesOnce()
+                    return manifestModule({
+                        files: pageFiles,
+                        keyForFile: pageUrlForFile,
+                        importDir: pagesDir,
+                        exportName: 'pages',
+                        label: 'pages',
+                        logWhenEmpty: true,
+                    })
                 }
 
                 if (args.path === 'belte:layouts') {
-                    const { layoutFiles: files } = await scanPagesOnce()
-                    const byPrefix = files
-                        .toSorted()
-                        .map((file) => ({ prefix: pageUrlForFile(file), file }))
-                    const entries = byPrefix
-                        .map(
-                            ({ prefix, file }) =>
-                                `    ${JSON.stringify(prefix)}: () => import(${JSON.stringify(`${pagesDir}/${file}`)}),`,
-                        )
-                        .join('\n')
-                    if (byPrefix.length > 0) {
-                        log.info(
-                            `resolved ${byPrefix.length} layouts: ${byPrefix.map((b) => b.prefix).join(', ')}`,
-                        )
-                    }
-                    return {
-                        contents: `export const layouts = {\n${entries}\n}\n`,
-                        loader: 'js',
-                    }
+                    const { layoutFiles } = await scanPagesOnce()
+                    return manifestModule({
+                        files: layoutFiles,
+                        keyForFile: pageUrlForFile,
+                        importDir: pagesDir,
+                        exportName: 'layouts',
+                        label: 'layouts',
+                    })
                 }
 
                 if (args.path === 'belte:app') {

package/src/buildCli.ts

@@ -1,9 +1,11 @@
 import type { CompileTarget } from './lib/server/runtime/types/CompileTarget.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
+import { exeSuffix } from './lib/shared/exeSuffix.ts'
 import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
 import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
 import { log } from './lib/shared/log.ts'
 import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
+import { readPackageJson } from './lib/shared/readPackageJson.ts'
 import { serverBuildPlugins } from './serverBuildPlugins.ts'
 
 const DISCOVERY_ENTRY = new URL('./discoveryEntry.ts', import.meta.url).pathname
@@ -92,7 +94,7 @@ export async function buildCli({
         return Promise.all(
             platforms.map(async (platformTarget) => {
                 const shortName = platformTarget.replace(/^bun-/, '')
-                const suffix = platformTarget.includes('windows') ? '.exe' : ''
+                const suffix = exeSuffix(platformTarget)
                 const platformOut = `${distDir}/cli-thin/${shortName}/${programName}${suffix}`
                 await Bun.$`mkdir -p ${`${distDir}/cli-thin/${shortName}`}`.quiet()
                 const result = await Bun.build({
@@ -108,7 +110,7 @@ export async function buildCli({
         )
     }
 
-    const suffix = target.includes('windows') ? '.exe' : ''
+    const suffix = exeSuffix(target)
     const outPath = outfile ?? `${distDir}/cli${suffix}`
 
     const cliResult = await Bun.build({
@@ -124,10 +126,6 @@ export async function buildCli({
 }
 
 async function readProgramName(cwd: string): Promise<string> {
-    const pkgFile = Bun.file(`${cwd}/package.json`)
-    if (!(await pkgFile.exists())) {
-        return 'app'
-    }
-    const pkg = (await pkgFile.json()) as { name?: string }
-    return programNameForPackage(pkg.name)
+    const pkg = (await readPackageJson(cwd)) as { name?: string } | undefined
+    return programNameForPackage(pkg?.name)
 }

package/src/bundleApp.ts

@@ -1,3 +1,4 @@
+import { dirname } from 'node:path'
 import { buildDisconnected } from './buildDisconnected.ts'
 import { compile } from './compile.ts'
 import { ensureWebviewLib } from './lib/bundle/ensureWebviewLib.ts'
@@ -6,11 +7,13 @@ 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 { bundleLayout } from './lib/shared/bundleLayout.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
 import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
 import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
 import { log } from './lib/shared/log.ts'
 import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
+import { readPackageJson } from './lib/shared/readPackageJson.ts'
 import { serverBuildPlugins } from './serverBuildPlugins.ts'
 
 const APP_ENTRY = new URL('./appEntry.ts', import.meta.url).pathname
@@ -38,15 +41,16 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
     const svelteConfig = await loadSvelteConfig(cwd)
 
     /*
-    Layout differs by OS: a macOS .app nests binaries under Contents/MacOS
-    and the lib under Contents/Frameworks; elsewhere everything sits flat
-    in one directory. binDir is where the launcher + server land, libDir
-    where the webview lib lands — matching resolveWebviewLib's candidates.
+    Layout differs by OS: a macOS .app nests binaries under Contents/MacOS, the
+    lib under Contents/Frameworks, and data under Contents/Resources; elsewhere
+    everything sits flat in one directory. bundleLayout derives the rest from
+    binDir — the same source the boot readers resolve from — so build and runtime
+    agree on where the lib, resources, and shipped `.env` land.
     */
     const isMac = process.platform === 'darwin'
     const bundleRoot = isMac ? `${cwd}/dist/${programName}.app` : `${cwd}/dist/${programName}`
     const binDir = isMac ? `${bundleRoot}/Contents/MacOS` : bundleRoot
-    const libDir = isMac ? `${bundleRoot}/Contents/Frameworks` : bundleRoot
+    const { libDir, resourcesDir, envPath } = bundleLayout(binDir)
 
     await Bun.$`rm -rf ${bundleRoot}`.quiet()
     await Bun.$`mkdir -p ${binDir} ${libDir}`.quiet()
@@ -57,15 +61,18 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
     await compile({ cwd, target, outfile: `${binDir}/${serverBinaryFilename()}` })
 
     /*
-    Opt-in: ship the project's `.env.bundle` as the binary-dir `.env`, which the
+    Opt-in: ship the project's `.env.bundle` as the shipped `.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.
+    the data-dir `.env` instead. bundleLayout places it under Contents/Resources
+    in a macOS `.app` (sealed as a resource, so it survives codesign) and beside
+    the binaries otherwise. Skipped when absent.
     */
     const bundleEnv = Bun.file(`${cwd}/.env.bundle`)
     if (await bundleEnv.exists()) {
-        await Bun.write(`${binDir}/.env`, bundleEnv)
+        await Bun.$`mkdir -p ${dirname(envPath)}`.quiet()
+        await Bun.write(envPath, bundleEnv)
     }
 
     // 2. Connect screen — bake dist/bundle-disconnected.html before the launcher
@@ -104,7 +111,6 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
     converted via sips + iconutil so authors don't need to make an .icns.
     */
     if (isMac) {
-        const resourcesDir = `${bundleRoot}/Contents/Resources`
         const icnsSource = `${cwd}/src/bundle/icon.icns`
         const pngSource = `${cwd}/src/bundle/icon.png`
         let hasIcon = false
@@ -136,10 +142,6 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
 
 // Reads name + version from package.json, with fallbacks when absent.
 async function readPackage(cwd: string): Promise<{ name: string | undefined; version: string }> {
-    const pkgFile = Bun.file(`${cwd}/package.json`)
-    if (!(await pkgFile.exists())) {
-        return { name: undefined, version: '0.0.0' }
-    }
-    const pkg = (await pkgFile.json()) as { name?: string; version?: string }
-    return { name: pkg.name, version: pkg.version ?? '0.0.0' }
+    const pkg = (await readPackageJson(cwd)) as { name?: string; version?: string } | undefined
+    return { name: pkg?.name, version: pkg?.version ?? '0.0.0' }
 }

package/src/compile.ts

@@ -1,6 +1,7 @@
 import { build } from './build.ts'
 import type { CompileTarget } from './lib/server/runtime/types/CompileTarget.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
+import { exeSuffix } from './lib/shared/exeSuffix.ts'
 import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
 import { loadSvelteConfig } from './lib/shared/loadSvelteConfig.ts'
 import { log } from './lib/shared/log.ts'
@@ -28,7 +29,7 @@ export async function compile({
     const svelteConfig = await loadSvelteConfig(cwd)
     await build({ cwd, svelteConfig })
 
-    const outPath = outfile ?? `${cwd}/dist/app${target.includes('windows') ? '.exe' : ''}`
+    const outPath = outfile ?? `${cwd}/dist/app${exeSuffix(target)}`
 
     const result = await Bun.build({
         entrypoints: [SERVER_ENTRY],

package/src/controlServerWorker.ts

@@ -11,6 +11,7 @@ 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 { bundleLayout } from './lib/shared/bundleLayout.ts'
 import { log } from './lib/shared/log.ts'
 import { readEnvFile } from './lib/shared/readEnvFile.ts'
 import { serializeEnv } from './lib/shared/serializeEnv.ts'
@@ -285,9 +286,11 @@ function dataDirEnvPath(): string {
     return join(appDataDir(programName), '.env')
 }
 
-// The shipped `.env` beside the server binary (the bundle's default config layer).
+// The bundle's shipped `.env` (its default config layer), resolved from the binary
+// directory — same source loadEnvFromBinaryDir reads at boot (dirname of the running
+// binary): beside the binary in the flat layout, under Resources in a `.app`.
 function binaryDirEnvPath(): string {
-    return join(dirname(resolveServerBinary()), '.env')
+    return bundleLayout(dirname(process.execPath)).envPath
 }
 
 /*
@@ -362,68 +365,81 @@ 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.
-*/
-async function handleControlRequest(request: Request): Promise<Response> {
-    const url = new URL(request.url)
-    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() })
+// GET /__belte/config — the form's schema + current values, or null schema to skip the gate.
+async function handleConfigGet(): Promise<Response> {
+    if (!configSchema) {
+        return Response.json({ schema: null, values: {} })
     }
-    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 })
+    return Response.json({ schema: configSchema, values: await resolveConfigValues() })
+}
+
+// POST /__belte/config — persist the form's answers to the data-dir `.env`.
+async function handleConfigPost(request: Request): Promise<Response> {
+    const { values } = (await request.json()) as { values: Record<string, string> }
+    await writeConfig(values)
+    return new Response(undefined, { status: 204 })
+}
+
+// POST /connect — point the window at a remote belte server after probing it.
+async function handleConnect(request: Request): Promise<Response> {
+    const { url: target } = (await request.json()) as { url: string }
+    // Verify it's actually a belte server before pointing the window at it.
+    const identity = await probeBelteServer(target)
+    if (!identity) {
+        log.warn(`no belte server responded at ${target}`)
+        return Response.json({ error: `No belte server responded at ${target}` }, { status: 502 })
     }
-    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.
-        const identity = await probeBelteServer(target)
-        if (!identity) {
-            log.warn(`no belte server responded at ${target}`)
-            return Response.json(
-                { error: `No belte server responded at ${target}` },
-                { status: 502 },
-            )
-        }
+    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 })
+}
+
+// POST /start — boot the embedded server and point the window at it.
+async function handleStart(): Promise<Response> {
+    try {
+        const localUrl = await startEmbeddedServer()
         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 })
-    }
-    if (request.method === 'POST' && url.pathname === '/start') {
-        try {
-            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) {
-            killServerChild()
-            return Response.json({ error: String(error) }, { status: 500 })
-        }
-    }
-    if (request.method === 'GET' && url.pathname === '/__belte/disconnect') {
-        stopLivenessWatch()
+        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) {
         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 Response.json({ error: String(error) }, { status: 500 })
     }
-    return new Response('not found', { status: 404 })
+}
+
+// GET /__belte/disconnect — tear down the embedded server and forget the auto-resume choice.
+async function handleDisconnect(): Promise<Response> {
+    stopLivenessWatch()
+    killServerChild()
+    flag?.setConnected(false)
+    await clearLastConnection()
+    return new Response(undefined, { status: 204 })
+}
+
+/*
+The control server's routes, keyed by `${method} ${pathname}` (exact match). The
+connect screen owns localStorage + navigation; this worker owns the embedded-
+server process and the native flag.
+*/
+const controlRoutes: Record<string, (request: Request) => Promise<Response> | Response> = {
+    'GET /': () => renderConnectScreen(),
+    'GET /__belte/config': handleConfigGet,
+    'POST /__belte/config': handleConfigPost,
+    'POST /connect': handleConnect,
+    'POST /start': handleStart,
+    'GET /__belte/disconnect': handleDisconnect,
+}
+
+function handleControlRequest(request: Request): Promise<Response> | Response {
+    const { pathname } = new URL(request.url)
+    const route = controlRoutes[`${request.method} ${pathname}`]
+    return route ? route(request) : new Response('not found', { status: 404 })
 }
 
 /*

package/src/lib/browser/page.svelte.ts

@@ -118,7 +118,7 @@ function applyState(
     const mutable = page as PageStateFor<string>
     mutable.route = route
     mutable.params = params
-    mutable.url = new URL(window.location.href)
+    syncUrl()
 }
 
 function syncUrl(): void {

package/src/lib/browser/remoteProxy.ts

@@ -1,16 +1,9 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
 import type { RemoteFunction } from '../server/rpc/types/RemoteFunction.ts'
+import { browserClientFlags } from '../shared/browserClientFlags.ts'
 import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
 import { createRemoteFunction } from '../shared/createRemoteFunction.ts'
 
-/*
-The browser stub is only emitted when the verb has `clients.browser:
-true`, so the value is always true here. mcp/cli flags are server-only
-discovery state and the browser bundle has no use for them; default
-false so the public RemoteFunction shape stays the same on both sides.
-*/
-const BROWSER_CLIENT_FLAGS = { browser: true, mcp: false, cli: false } as const
-
 /*
 Client-side substitute for a verb-defined handler. The bundler emits one
 call per verb export inside an `$rpc/**` module (GET / POST / …): server
@@ -31,7 +24,7 @@ export function remoteProxy<Args, Return>(
     return createRemoteFunction<Args, Return>({
         method,
         url,
-        clients: BROWSER_CLIENT_FLAGS,
+        clients: browserClientFlags,
         buildRequest: (args) =>
             buildRpcRequest({ method, url, args, baseUrl: window.location.href }),
         /*

package/src/lib/browser/socketProxy.ts

@@ -1,17 +1,10 @@
 import type { Socket } from '../server/sockets/types/Socket.ts'
+import { browserClientFlags } from '../shared/browserClientFlags.ts'
 import { createPushIterator } from '../shared/createPushIterator.ts'
 import { getSocketChannel } from './socketChannel.ts'
 
 let nextId = 0
 
-/*
-Browser stub is only emitted when `clients.browser: true`, so the value
-is always true here. mcp/cli flags are server-only discovery state; the
-browser bundle has no use for them. Default false so the public Socket
-shape stays consistent on both sides.
-*/
-const BROWSER_CLIENT_FLAGS = { browser: true, mcp: false, cli: false } as const
-
 /*
 Client-side substitute for a server-declared Socket. The bundler emits
 one call per socket export under `src/server/sockets/`: server target uses
@@ -54,7 +47,7 @@ export function socketProxy<T>(name: string): Socket<T> {
 
     return {
         name,
-        clients: BROWSER_CLIENT_FLAGS,
+        clients: browserClientFlags,
         publish(message: T) {
             getSocketChannel().publish(name, message)
         },

package/src/lib/bundle/resolveWebviewLib.ts

@@ -1,4 +1,5 @@
 import { dirname, join } from 'node:path'
+import { bundleLayout } from '../shared/bundleLayout.ts'
 import { webviewCachePath } from './webviewCachePath.ts'
 import { webviewLibName } from './webviewLibName.ts'
 
@@ -29,10 +30,11 @@ export async function resolveWebviewLib(cwd: string = process.cwd()): Promise<st
     /*
     Bundle-relative candidates. In dev `process.execPath` is the `bun`
     binary, so these miss and we fall through to the build cache; in a
-    shipped bundle the launcher's own directory holds the lib.
+    shipped bundle the launcher's own directory holds the lib (flat layout)
+    or its sibling Frameworks dir (macOS `.app`) — bundleLayout knows which.
     */
-    const binDir = dirname(process.execPath)
-    const bundledCandidates = [join(binDir, libName), join(binDir, '..', 'Frameworks', libName)]
+    const { binDir, libDir } = bundleLayout(dirname(process.execPath))
+    const bundledCandidates = [join(binDir, libName), join(libDir, libName)]
     for (const candidate of bundledCandidates) {
         if (await Bun.file(candidate).exists()) {
             return candidate

package/src/lib/cli/loadEnvFromBinaryDir.ts

@@ -1,14 +1,16 @@
 import { dirname } from 'node:path'
+import { bundleLayout } from '../shared/bundleLayout.ts'
 import { loadEnvFile } from '../shared/loadEnvFile.ts'
 
 /*
-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
+Loads the bundle's shipped `.env` into `process.env`, resolved from the running
+binary's directory (`process.execPath`) via bundleLayout — beside the binary in
+the flat layout, under `Contents/Resources` in a macOS `.app`. 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> {
-    await loadEnvFile(`${dirname(process.execPath)}/.env`)
+    await loadEnvFile(bundleLayout(dirname(process.execPath)).envPath)
 }

package/src/lib/cli/runCli.ts

@@ -8,6 +8,8 @@ import { parseArgvForRpc } from './parseArgvForRpc.ts'
 import { printCommandHelp, printTopLevelHelp } from './printHelp.ts'
 import type { CliManifest } from './types/CliManifest.ts'
 
+const isHelpFlag = (arg: string): boolean => arg === '--help' || arg === '-h'
+
 // String results print verbatim (with a trailing newline); everything else as a JSON line.
 function printValue(value: unknown, pretty: boolean): void {
     if (typeof value === 'string') {
@@ -54,12 +56,12 @@ export async function runCli({
     await loadEnvFromBinaryDir()
 
     const first = argv[0]
-    if (!first || first === '--help' || first === '-h') {
+    if (!first || isHelpFlag(first)) {
         printTopLevelHelp(programName, manifest, banner, footer)
         return 0
     }
 
-    if (argv.includes('--help') || argv.includes('-h')) {
+    if (argv.some(isHelpFlag)) {
         printCommandHelp(programName, first, manifest)
         return 0
     }

package/src/lib/mcp/dispatchMcpRequest.ts

@@ -224,8 +224,7 @@ function dispatchVerb(
     args: Record<string, unknown> | undefined,
     inbound: Request,
 ): Promise<Response> {
-    const inboundUrl = new URL(inbound.url)
-    const baseUrl = `${inboundUrl.protocol}//${inboundUrl.host}/`
+    const baseUrl = `${new URL(inbound.url).origin}/`
     const request = buildRpcRequest({
         method: entry.remote.method,
         url: entry.remote.url,

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

@@ -1,3 +1,5 @@
+import { serializeEnv } from '../../shared/serializeEnv.ts'
+
 /*
 Generates the `.env` file content shipped alongside the CLI binary in
 the download tarball. APP_URL is always present (derived from the
@@ -10,9 +12,8 @@ user's auth code at the actual RPC endpoints validates whatever value
 arrives back in subsequent calls.
 */
 export function buildEnvContent(appUrl: string, bearerToken: string | undefined): string {
-    const lines = [`APP_URL=${appUrl}`]
-    if (bearerToken) {
-        lines.push(`APP_TOKEN=${bearerToken}`)
-    }
-    return `${lines.join('\n')}\n`
+    return serializeEnv({
+        APP_URL: appUrl,
+        ...(bearerToken ? { APP_TOKEN: bearerToken } : {}),
+    })
 }

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

@@ -101,8 +101,7 @@ export async function handleCliDownload(
             headers: { 'Cache-Control': NO_STORE },
         })
     }
-    const url = new URL(request.url)
-    const appUrl = `${url.protocol}//${url.host}`
+    const appUrl = new URL(request.url).origin
     const auth = request.headers.get('authorization')
     const bearer =
         auth && auth.toLowerCase().startsWith('bearer ') ? auth.slice('bearer '.length) : undefined

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

@@ -26,7 +26,7 @@ export function handleCliInstall(request: Request, programName: string): Respons
             headers: { 'Cache-Control': NO_STORE },
         })
     }
-    const appUrl = `${url.protocol}//${url.host}`
+    const appUrl = url.origin
     const script = installScript(appUrl, programName)
     return new Response(script, {
         headers: {

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

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import { Glob } from 'bun'
 
 /*
@@ -6,22 +6,21 @@ Returns the most-recent mtime across every rpc + socket source file in
 the project, or 0 when both directories are absent. The lazy CLI
 download path compares this to the binary's mtime to decide whether to
 rebuild — covers the common dev iteration of "user edited an rpc
-handler" without needing to scan transitively-imported modules.
+handler" without needing to scan transitively-imported modules. Globs and
+stats run concurrently since each file is independent.
 */
 export async function maxSourceMtime(cwd: string): Promise<number> {
-    const roots = [`${cwd}/src/server/rpc`, `${cwd}/src/server/sockets`]
-    let newest = 0
-    for (const root of roots) {
-        if (!existsSync(root)) {
-            continue
-        }
-        const files = new Glob('**/*.ts').scan({ cwd: root, onlyFiles: true })
-        for await (const file of files) {
-            const stat = statSync(`${root}/${file}`)
-            if (stat.mtimeMs > newest) {
-                newest = stat.mtimeMs
-            }
-        }
-    }
-    return newest
+    const roots = [`${cwd}/src/server/rpc`, `${cwd}/src/server/sockets`].filter(existsSync)
+    const perRoot = await Promise.all(
+        roots.map(async (root) => {
+            const files = await Array.fromAsync(
+                new Glob('**/*.ts').scan({ cwd: root, onlyFiles: true }),
+            )
+            return files.map((file) => `${root}/${file}`)
+        }),
+    )
+    const mtimes = await Promise.all(
+        perRoot.flat().map(async (path) => (await Bun.file(path).stat()).mtimeMs),
+    )
+    return mtimes.reduce((newest, mtime) => Math.max(newest, mtime), 0)
 }

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

@@ -11,6 +11,7 @@ import { NO_STORE, SSR_CACHE_CONTROL } from '../../shared/cacheControlValues.ts'
 import { createCacheStore } from '../../shared/createCacheStore.ts'
 import { isDebugEnabled } from '../../shared/isDebugEnabled.ts'
 import { log } from '../../shared/log.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { nearestLayoutPrefix, normalizeLayoutPrefixes } from '../../shared/nearestLayoutPrefix.ts'
 import { toBunRoutePattern } from '../../shared/toBunRoutePattern.ts'
 import type { AppModule } from '../AppModule.ts'
@@ -43,6 +44,9 @@ function wantsJson(req: Request): boolean {
     return (req.headers.get('accept') ?? '').includes('application/json')
 }
 
+// SSR placeholders the shell carries; filled in a single pass per render.
+const SSR_MARKER = /<!--ssr:(head|body|state)-->/g
+
 /*
 The framework's default 500 response — a `<pre>` stack dump. Shared by the
 per-request catch and Bun.serve's global error() fallback so the two can't
@@ -146,12 +150,7 @@ export async function createServer({
               (file) => `/_app/${file.replace(/\.zst$/, '')}`,
           )
 
-    const rpcModuleCache = new Map<string, Promise<AnyRemoteFunction | undefined>>()
-    function loadRpc(url: string): Promise<AnyRemoteFunction | undefined> | undefined {
-        const existing = rpcModuleCache.get(url)
-        if (existing) {
-            return existing
-        }
+    const loadRpc = memoizeByKey((url): Promise<AnyRemoteFunction | undefined> | undefined => {
         const loader = rpc[url]
         if (!loader) {
             return undefined
@@ -161,7 +160,7 @@ export async function createServer({
         time. Pick the first export that looks like a RemoteFunction so the
         framework stays tolerant of incidental re-exports.
         */
-        const promise = loader().then((mod) => {
+        return loader().then((mod) => {
             for (const value of Object.values(mod)) {
                 if (typeof value === 'function' && 'method' in value && 'url' in value) {
                     return value as AnyRemoteFunction
@@ -169,9 +168,7 @@ export async function createServer({
             }
             return undefined
         })
-        rpcModuleCache.set(url, promise)
-        return promise
-    }
+    })
 
     const logRequests = isDebugEnabled('belte')
 
@@ -258,10 +255,12 @@ export async function createServer({
             params,
             cache: cacheSnapshot,
         })};</script>`
-        const html = shell
-            .replace('<!--ssr:head-->', rendered.head)
-            .replace('<!--ssr:body-->', rendered.body)
-            .replace('<!--ssr:state-->', stateTag)
+        const fills: Record<string, string> = {
+            head: rendered.head,
+            body: rendered.body,
+            state: stateTag,
+        }
+        const html = shell.replace(SSR_MARKER, (_match, key: string) => fills[key])
         return new Response(html, {
             headers: {
                 'Content-Type': 'text/html; charset=utf-8',

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,5 +1,6 @@
 import type { ServerWebSocket } from 'bun'
 import { log } from '../../shared/log.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { error } from '../error.ts'
 import { json } from '../json.ts'
 import { sse } from '../sse.ts'
@@ -52,22 +53,12 @@ module triggers its `defineSocket` call, which inserts into the
 registry. After that the dispatcher just reads the registry.
 */
 export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher {
-    const moduleCache = new Map<string, Promise<void>>()
     const connections = new WeakMap<ServerWebSocket<unknown>, ConnectionState>()
 
-    function ensureLoaded(name: string): Promise<void> | undefined {
-        const existing = moduleCache.get(name)
-        if (existing) {
-            return existing
-        }
+    const ensureLoaded = memoizeByKey((name): Promise<void> | undefined => {
         const loader = sockets[name]
-        if (!loader) {
-            return undefined
-        }
-        const promise = loader().then(() => undefined)
-        moduleCache.set(name, promise)
-        return promise
-    }
+        return loader ? loader().then(() => undefined) : undefined
+    })
 
     function send(ws: ServerWebSocket<unknown>, frame: SocketServerFrame): void {
         if (ws.readyState !== WebSocket.OPEN) {
@@ -111,37 +102,24 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         state: ConnectionState,
         frame: Extract<SocketClientFrame, { type: 'sub' }>,
     ): Promise<void> {
+        // Reject this sub: emit the error then the terminal end frame for its id.
+        function fail(message: string): void {
+            send(ws, { type: 'err', sub: frame.sub, message })
+            send(ws, { type: 'end', sub: frame.sub })
+        }
         const loader = ensureLoaded(frame.socket)
         if (!loader) {
-            send(ws, {
-                type: 'err',
-                sub: frame.sub,
-                message: `[belte] no socket registered at ${frame.socket}`,
-            })
-            send(ws, { type: 'end', sub: frame.sub })
-            return
+            return fail(`[belte] no socket registered at ${frame.socket}`)
         }
         try {
             await loader
         } catch (error) {
             log.error(error)
-            send(ws, {
-                type: 'err',
-                sub: frame.sub,
-                message: error instanceof Error ? error.message : String(error),
-            })
-            send(ws, { type: 'end', sub: frame.sub })
-            return
+            return fail(error instanceof Error ? error.message : String(error))
         }
         const entry = lookupSocket(frame.socket)
         if (!entry) {
-            send(ws, {
-                type: 'err',
-                sub: frame.sub,
-                message: `[belte] socket module at ${frame.socket} did not register a Socket export`,
-            })
-            send(ws, { type: 'end', sub: frame.sub })
-            return
+            return fail(`[belte] socket module at ${frame.socket} did not register a Socket export`)
         }
         const isFirstLocalSub = addSub(state, frame.socket, frame.sub)
         if (isFirstLocalSub) {

package/src/lib/shared/belteImportName.ts

@@ -1,4 +1,5 @@
 import { beltePackageName } from './beltePackageName.ts'
+import { readPackageJson } from './readPackageJson.ts'
 
 /*
 Resolves the bare specifier prefix a consuming project imports belte under —
@@ -17,14 +18,12 @@ resolve belte at all in that case, and the canonical name yields the clearest
 resolution error.
 */
 export async function belteImportName(cwd: string): Promise<string> {
-    const packageJsonPath = `${cwd}/package.json`
-    if (!(await Bun.file(packageJsonPath).exists())) {
+    const packageJson = (await readPackageJson(cwd)) as
+        | { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+        | undefined
+    if (!packageJson) {
         return beltePackageName
     }
-    const packageJson = (await Bun.file(packageJsonPath).json()) as {
-        dependencies?: Record<string, string>
-        devDependencies?: Record<string, string>
-    }
     const dependencies = { ...packageJson.devDependencies, ...packageJson.dependencies }
     /*
     Alias entries whose target is belte — `npm:` for a published install,

package/src/lib/shared/browserClientFlags.ts

@@ -0,0 +1,10 @@
+import type { ClientFlags } from './types/ClientFlags.ts'
+
+/*
+Client surface flags for a browser-emitted RPC/socket stub. The bundler only
+emits the browser proxy when clients.browser is true, so browser is always true
+here; mcp/cli are server-only discovery state with no meaning in the browser
+bundle, defaulted false so the public RemoteFunction/Socket shape matches the
+server side. Single source shared by remoteProxy and socketProxy.
+*/
+export const browserClientFlags: ClientFlags = { browser: true, mcp: false, cli: false }

package/src/lib/shared/bundleLayout.ts

@@ -0,0 +1,36 @@
+import { basename, dirname, join } from 'node:path'
+
+/*
+Where a bundle's files live relative to its binary directory (the dir holding the
+launcher + server — `dirname(process.execPath)` at runtime). A macOS `.app` nests
+binaries under `Contents/MacOS`, the webview lib under `Contents/Frameworks`, and
+data under `Contents/Resources` — the only one `codesign` seals as a *resource*,
+so the shipped `.env` survives signing. Every other platform keeps everything
+flat beside the binaries. The single source the bundler writes against and the
+boot readers resolve from, so build and runtime can't disagree. Pure: computes
+paths, never touches disk.
+*/
+export function bundleLayout(binaryDir: string): {
+    binDir: string
+    libDir: string
+    resourcesDir: string
+    envPath: string
+} {
+    const isMacApp = basename(binaryDir) === 'MacOS' && basename(dirname(binaryDir)) === 'Contents'
+    if (isMacApp) {
+        const contents = dirname(binaryDir)
+        const resourcesDir = join(contents, 'Resources')
+        return {
+            binDir: binaryDir,
+            libDir: join(contents, 'Frameworks'),
+            resourcesDir,
+            envPath: join(resourcesDir, '.env'),
+        }
+    }
+    return {
+        binDir: binaryDir,
+        libDir: binaryDir,
+        resourcesDir: binaryDir,
+        envPath: join(binaryDir, '.env'),
+    }
+}

package/src/lib/shared/exeSuffix.ts

@@ -0,0 +1,9 @@
+import type { CompileTarget } from '../server/runtime/types/CompileTarget.ts'
+
+/*
+Executable filename suffix for a compile target — `.exe` on Windows targets,
+empty elsewhere. Single source so every cross-compile output path agrees.
+*/
+export function exeSuffix(target: CompileTarget): string {
+    return target.includes('windows') ? '.exe' : ''
+}

package/src/lib/shared/manifestModule.ts

@@ -0,0 +1,34 @@
+import { log } from './log.ts'
+
+/*
+Builds one of belte's virtual manifest modules — the `{ key: () => import(...) }`
+map the bundler emits for rpc / sockets / prompts / pages / layouts. They differ
+only in their files, the key derived per file, the import dir, the export name,
+and the log label; this is the single shape they share.
+*/
+export function manifestModule(options: {
+    files: string[]
+    keyForFile: (file: string) => string
+    importDir: string
+    exportName: string
+    label: string
+    // pages logs its count even at zero (a route-less app is worth surfacing);
+    // the other manifests stay quiet when empty.
+    logWhenEmpty?: boolean
+}): { contents: string; loader: 'js' } {
+    const entries = options.files
+        .toSorted()
+        .map((file) => ({ key: options.keyForFile(file), file }))
+    const lines = entries
+        .map(
+            ({ key, file }) =>
+                `    ${JSON.stringify(key)}: () => import(${JSON.stringify(`${options.importDir}/${file}`)}),`,
+        )
+        .join('\n')
+    if (entries.length > 0 || options.logWhenEmpty) {
+        log.info(
+            `resolved ${entries.length} ${options.label}: ${entries.map((entry) => entry.key).join(', ')}`,
+        )
+    }
+    return { contents: `export const ${options.exportName} = {\n${lines}\n}\n`, loader: 'js' }
+}

package/src/lib/shared/memoizeByKey.ts

@@ -0,0 +1,24 @@
+/*
+Memoises an async loader keyed by string: the first call for a key starts the
+load and caches its promise; later calls reuse it. `load` returns undefined when
+the key has no loader, which is passed through (and not cached) so the caller can
+treat "unknown key" distinctly from "loaded value". Used by the rpc-module and
+socket-module load caches, which share this exact shape.
+*/
+export function memoizeByKey<T>(
+    load: (key: string) => Promise<T> | undefined,
+): (key: string) => Promise<T> | undefined {
+    const cache = new Map<string, Promise<T>>()
+    return (key) => {
+        const existing = cache.get(key)
+        if (existing) {
+            return existing
+        }
+        const started = load(key)
+        if (!started) {
+            return undefined
+        }
+        cache.set(key, started)
+        return started
+    }
+}

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
+}