@briancray/belte 0.1.0 → 0.2.0

package/src/controlServerWorker.ts

@@ -0,0 +1,261 @@
+import { bindConnectedFlag } from './lib/bundle/bindConnectedFlag.ts'
+import { bindRequestNavigate } from './lib/bundle/bindRequestNavigate.ts'
+import { findFreePort } from './lib/bundle/findFreePort.ts'
+import { listenLocalControlServer } from './lib/bundle/listenLocalControlServer.ts'
+import { probeBelteServer } from './lib/bundle/probeBelteServer.ts'
+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 { log } from './lib/shared/log.ts'
+
+/*
+The bundle's control server, run in a Worker so it owns its own thread.
+
+`webview_run` enters a native UI run loop that blocks the launcher's main thread
+indefinitely (the window owns it until close), which freezes the main thread's
+JS event loop. An in-process `Bun.serve` there can never answer a request, so the
+webview pointed at it would only ever see a hung navigation — a blank window.
+
+Running the control server on this Worker thread keeps it answering the whole time
+the window is open. It owns the pieces that must live beside it: the embedded
+server child it spawns, and its own FFI handle to the native menu flag (set here
+because the main thread can't process a postMessage while blocked in webview_run,
+yet the flag is a process-global the main-thread menu still reads).
+
+Bun does not apply the launcher build's plugins to a worker entry, so this module
+can't import belte's virtual modules (the connect-screen HTML, app title). The
+launcher — which can — passes them in the `init` message; on `shutdown` it has us
+reap the embedded child before the launcher exits.
+
+Once connected it also watches the chosen server's liveness — polling its identity
+endpoint — and, when it stops answering, corrects the menu flag and bounces the
+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)
+  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 }
+let disconnectedHtml = ''
+let title = ''
+let flag: ReturnType<typeof bindConnectedFlag> | undefined
+let server: ReturnType<typeof listenLocalControlServer> | undefined
+
+// The control-server origin (where the connect screen lives) and the webview
+// handle, forwarded by the launcher — together they let the watch bounce a dead
+// window back to the connect screen.
+let controlOrigin = ''
+let navigate: ReturnType<typeof bindRequestNavigate> | undefined
+let webviewHandle: number | undefined
+
+/*
+Liveness watch over the currently-connected server. A recursive timer (not
+setInterval, so a slow probe never overlaps the next) probes the identity endpoint;
+a couple of consecutive misses — tolerating a transient blip or a quick restart —
+count as a death. Cleared whenever we're not connected.
+*/
+const LIVENESS_INTERVAL_MS = 4000
+const LIVENESS_FAILURE_LIMIT = 2
+let connectedUrl: string | undefined
+let livenessTimer: ReturnType<typeof setTimeout> | undefined
+let livenessFailures = 0
+
+// Embedded-server child, spawned on demand by Start server; undefined when none.
+let serverChild: ReturnType<typeof Bun.spawn> | undefined
+
+// Reaps the embedded server child if one is running.
+function killServerChild(): void {
+    if (serverChild) {
+        serverChild.kill()
+        serverChild = undefined
+    }
+}
+
+// Begin (or restart) watching `url` for liveness once the window points at it.
+function startLivenessWatch(url: string): void {
+    stopLivenessWatch()
+    connectedUrl = url
+    livenessFailures = 0
+    livenessTimer = setTimeout(runLivenessProbe, LIVENESS_INTERVAL_MS)
+}
+
+// Stop watching — on explicit disconnect, on detected death, or at shutdown.
+function stopLivenessWatch(): void {
+    if (livenessTimer) {
+        clearTimeout(livenessTimer)
+        livenessTimer = undefined
+    }
+    connectedUrl = undefined
+    livenessFailures = 0
+}
+
+/*
+One liveness probe of the connected server. Successes reset the miss count;
+LIVENESS_FAILURE_LIMIT consecutive misses declare it dead and hand off to
+handleConnectionLost. Reschedules itself while still connected.
+*/
+async function runLivenessProbe(): Promise<void> {
+    const url = connectedUrl
+    if (!url) {
+        return
+    }
+    const identity = await probeBelteServer(url)
+    // A disconnect or reconnect during the await may have moved us on.
+    if (connectedUrl !== url) {
+        return
+    }
+    if (identity) {
+        livenessFailures = 0
+    } else {
+        livenessFailures += 1
+        if (livenessFailures >= LIVENESS_FAILURE_LIMIT) {
+            handleConnectionLost(url)
+            return
+        }
+    }
+    livenessTimer = setTimeout(runLivenessProbe, LIVENESS_INTERVAL_MS)
+}
+
+/*
+The connected server stopped answering. Reap any (now-dead) embedded child, clear
+the connected flag so the menu stops claiming connected, and bounce the window
+back to the connect screen with a `lost` notice. The flag flip alone keeps the
+menu honest even when the navigate is a no-op (off macOS, or no handle yet).
+*/
+function handleConnectionLost(url: string): void {
+    log.warn(`connected server stopped responding: ${url}`)
+    stopLivenessWatch()
+    killServerChild()
+    flag?.setConnected(false)
+    if (webviewHandle !== undefined) {
+        navigate?.requestNavigate(webviewHandle, `${controlOrigin}/?action=lost`)
+    }
+}
+
+/*
+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> {
+    killServerChild()
+    const port = findFreePort()
+    const url = `http://localhost:${port}`
+    serverChild = Bun.spawn({
+        cmd: [resolveServerBinary()],
+        // BELTE_PARENT_PID lets the child exit if the launcher is force-quit
+        // (a clean window close reaps it directly; see exitWithParent).
+        env: { ...process.env, PORT: String(port), BELTE_PARENT_PID: String(process.pid) },
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    await waitForServer(url)
+    return url
+}
+
+/*
+Injects the app title into the connect-screen HTML just before serving — the build
+left a `<!--belte:connect-config-->` marker in <head>.
+*/
+function renderConnectScreen(): Response {
+    const script = `<script>window.__BELTE_TITLE__=${JSON.stringify(title)}</script>`
+    const html = disconnectedHtml.replace('<!--belte:connect-config-->', script)
+    return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } })
+}
+
+/*
+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 === '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)
+        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)
+            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()
+        killServerChild()
+        flag?.setConnected(false)
+        return new Response(undefined, { status: 204 })
+    }
+    return new Response('not found', { status: 404 })
+}
+
+/*
+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.
+*/
+async function start(init: Init): Promise<void> {
+    disconnectedHtml = init.disconnectedHtml
+    title = init.title
+    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 })
+}
+
+// Reap the child + release the server and FFI handles, then confirm so the
+// launcher can exit cleanly.
+function shutdown(): void {
+    stopLivenessWatch()
+    killServerChild()
+    server?.stop(true)
+    flag?.close()
+    navigate?.close()
+    self.postMessage({ type: 'shutdownDone' })
+}
+
+/*
+The launcher drives the lifecycle: `init` (with the data this worker can't import)
+starts the server, `window` forwards the webview handle the liveness watch needs to
+navigate, and `shutdown` tears it all down once the window closes.
+*/
+self.addEventListener('message', (event: MessageEvent) => {
+    const data = event.data as
+        | { type: 'init'; init: Init }
+        | { type: 'window'; handle: number }
+        | { type: 'shutdown' }
+    if (data.type === 'init') {
+        void start(data.init)
+    } else if (data.type === 'window') {
+        webviewHandle = data.handle
+    } else if (data.type === 'shutdown') {
+        shutdown()
+    }
+})

package/src/dedupeSveltePlugin.ts

@@ -0,0 +1,66 @@
+import type { BunPlugin } from 'bun'
+
+type ExportEntry = string | { [condition: string]: ExportEntry }
+
+/*
+Walks a package.json `exports` entry, returning the first leaf string that
+matches the supplied condition list in order. Returns undefined when no
+branch resolves.
+*/
+function pickExport(entry: ExportEntry, conditions: string[]): string | undefined {
+    if (typeof entry === 'string') {
+        return entry
+    }
+    for (const condition of conditions) {
+        if (entry[condition]) {
+            const resolved = pickExport(entry[condition], conditions)
+            if (resolved) {
+                return resolved
+            }
+        }
+    }
+    return undefined
+}
+
+/*
+Forces every `import 'svelte/...'` (from belte's own source, the consumer's
+source, or any transitive dep) to resolve against the consumer app's svelte
+install, picking the export condition that matches the build target.
+Without this, belte's symlinked source can pick up a second svelte from its
+install location, ship both runtimes, and break hydration. Shared by the
+client build and the bundle connect-screen build.
+*/
+export function dedupeSveltePlugin({
+    cwd,
+    conditions,
+}: {
+    cwd: string
+    conditions: string[]
+}): BunPlugin {
+    const consumerSvelte = `${cwd}/node_modules/svelte`
+    return {
+        name: 'belte-dedupe-svelte',
+        async setup(build) {
+            const pkgFile = Bun.file(`${consumerSvelte}/package.json`)
+            if (!(await pkgFile.exists())) {
+                return
+            }
+            const consumerPackage = (await pkgFile.json()) as {
+                exports: Record<string, ExportEntry>
+            }
+            build.onResolve({ filter: /^svelte(\/.*)?$/ }, (args) => {
+                const subpath =
+                    args.path === 'svelte' ? '.' : `.${args.path.slice('svelte'.length)}`
+                const entry = consumerPackage.exports[subpath]
+                if (!entry) {
+                    return undefined
+                }
+                const resolvedFile = pickExport(entry, conditions)
+                if (!resolvedFile) {
+                    return undefined
+                }
+                return { path: `${consumerSvelte}/${resolvedFile.replace(/^\.\//, '')}` }
+            })
+        },
+    }
+}

package/src/discoveryEntry.ts

@@ -18,16 +18,17 @@ await Promise.all([
     ...Object.values(sockets).map((loader) => (loader as () => Promise<unknown>)()),
 ])
 
-const manifest: Record<string, unknown> = {}
-for (const entry of verbRegistry.values()) {
-    if (!entry.clients.cli) {
-        continue
-    }
-    manifest[commandNameForUrl(entry.remote.url)] = {
-        method: entry.remote.method,
-        url: entry.remote.url,
-        jsonSchema: jsonSchemaForSchema(entry.schema, entry.jsonSchema),
-    }
-}
+const manifest = Object.fromEntries(
+    Array.from(verbRegistry.values())
+        .filter((entry) => entry.clients.cli)
+        .map((entry) => [
+            commandNameForUrl(entry.remote.url),
+            {
+                method: entry.remote.method,
+                url: entry.remote.url,
+                jsonSchema: jsonSchemaForSchema(entry.schema, entry.jsonSchema),
+            },
+        ]),
+)
 
 process.stdout.write(JSON.stringify(manifest))

package/src/lib/browser/cache.ts

@@ -145,12 +145,9 @@ cache.invalidate = function invalidate<Args, Return>(
         same set because they share method+url.
         */
         const prefix = `${arg.method} ${arg.url}`
-        const affected: string[] = []
-        for (const key of store.entries.keys()) {
-            if (key === prefix || key.startsWith(`${prefix}?`) || key.startsWith(`${prefix} `)) {
-                affected.push(key)
-            }
-        }
+        const affected = Array.from(store.entries.keys()).filter(
+            (key) => key === prefix || key.startsWith(`${prefix}?`) || key.startsWith(`${prefix} `),
+        )
         affected.forEach((key) => store.entries.delete(key))
         emit(store, affected)
         return

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

@@ -13,8 +13,13 @@ block that fills this interface with `routePath: paramShape` pairs derived
 from the project's `src/browser/pages/**` tree. A bare belte install has no routes,
 so the fallback arm below keeps the union inhabited before the generated
 d.ts lands.
+
+Declared as an `interface` (not a `type` alias) because the generated d.ts
+augments it via `declare module … { interface Routes { … } }`, and module
+augmentation only merges into interfaces.
 */
-export type Routes = {}
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated routes.d.ts
+export interface Routes {}
 
 type RouteKey = keyof Routes extends never ? string : keyof Routes
 type ParamsFor<R extends RouteKey> = R extends keyof Routes ? Routes[R] : Record<string, string>
@@ -121,26 +126,19 @@ function syncUrl(): void {
     mutable.url = new URL(window.location.href)
 }
 
-type FetchOutcome =
-    | { kind: 'ok'; response: Response }
-    | { kind: 'network-error' }
-    | { kind: 'not-found' }
-    | { kind: 'http-error'; status: number }
-
-async function safeResolveFetch(target: string): Promise<FetchOutcome> {
-    let response: Response
+/*
+Resolves the JSON view payload for a target URL, or undefined when the fetch
+fails for any reason (network error or non-2xx, including 404). The caller
+falls back to a hard navigation in every failure case, so the failure modes
+don't need to be distinguished.
+*/
+async function safeResolveFetch(target: string): Promise<Response | undefined> {
     try {
-        response = await fetch(target, { headers: { Accept: 'application/json' } })
+        const response = await fetch(target, { headers: { Accept: 'application/json' } })
+        return response.ok ? response : undefined
     } catch {
-        return { kind: 'network-error' }
-    }
-    if (response.status === 404) {
-        return { kind: 'not-found' }
-    }
-    if (!response.ok) {
-        return { kind: 'http-error', status: response.status }
+        return undefined
     }
-    return { kind: 'ok', response }
 }
 
 export type NavigateOptions = { replace?: boolean; scroll?: boolean }
@@ -185,12 +183,12 @@ async function applyTarget(
         syncUrl()
         return
     }
-    const outcome = await safeResolveFetch(fullTarget)
-    if (outcome.kind !== 'ok') {
+    const response = await safeResolveFetch(fullTarget)
+    if (!response) {
         window.location.href = fullTarget
         return
     }
-    const result = (await outcome.response.json()) as SsrPayload
+    const result = (await response.json()) as SsrPayload
     try {
         const { Page, Layout } = await loadView(result.route)
         applyState(result.route, result.params, Page, Layout)

package/src/lib/browser/socketChannel.ts

@@ -132,8 +132,18 @@ export function getSocketChannel(): Channel {
             for (const [, sub] of active) {
                 sub.callbacks.onError('socket channel disconnected')
             }
+            /*
+            Drop any queued frames too. We've just torn down every local
+            sub, so replaying their `sub`/`unsub`/`pub` frames on
+            reconnect would open ghost subscriptions on the server that
+            no client object tracks (and never gets an `unsub`). This
+            keeps the "no silent re-subscribe across a reconnect"
+            contract above honest — consumers re-open fresh subs.
+            */
+            const hadPending = pendingSends.length > 0
+            pendingSends = []
             ws = undefined
-            if (active.length === 0 && pendingSends.length === 0) {
+            if (active.length === 0 && !hadPending) {
                 return
             }
             setTimeout(connect, backoffMs)

package/src/lib/browser/types/Pages.ts

@@ -2,6 +2,6 @@ import type { Component } from 'svelte'
 
 /*
 Manifest of route URL → page.svelte module loader. Produced by the resolver
-plugin from `page.svelte` files anywhere under src/routes.
+plugin from `page.svelte` files anywhere under src/browser/pages.
 */
 export type Pages = Record<string, () => Promise<{ default: Component }>>

package/src/lib/bundle/BundleMenu.ts

@@ -0,0 +1,11 @@
+import type { BundleMenuItem } from './BundleMenuItem.ts'
+
+/*
+A top-level bundle menu, inserted into the macOS menu bar between the standard
+Edit and Window menus. `label` titles the menu; `items` are its entries top to
+bottom.
+*/
+export type BundleMenu = {
+    label: string
+    items: BundleMenuItem[]
+}

package/src/lib/bundle/BundleMenuItem.ts

@@ -0,0 +1,24 @@
+/*
+A single entry in a bundle menu. Serializable data — the native shim builds the
+matching NSMenuItem. Either a divider or a clickable item that dispatches a
+`belte:menu` CustomEvent into the page (detail `{ name }`); the app's own code
+handles it:
+
+    window.addEventListener('belte:menu', (event) => {
+        if (event.detail.name === 'sync') syncNow()
+    })
+
+Emitting an event (rather than calling a verb directly) is what lets a menu
+drive parameterised work: a click carries no arguments, so the app computes
+them and makes the call itself. `shortcut` is the key for the Cmd-based
+equivalent (e.g. `'r'` → Cmd-R).
+
+A `navigate` item moves the window instead of talking to the page: clicking it
+calls `webview_navigate` with the given URL (the native side, on the UI thread).
+That's how the built-in Server menu drives the connect screen — `emit` reaches
+the loaded page, `navigate` repoints the window itself.
+*/
+export type BundleMenuItem =
+    | { separator: true }
+    | { label: string; shortcut?: string; emit: string }
+    | { label: string; shortcut?: string; navigate: string }

package/src/lib/bundle/BundleWindow.ts

@@ -0,0 +1,20 @@
+import type { BundleMenu } from './BundleMenu.ts'
+
+/*
+User-authored bundle window configuration, default-exported from an
+optional `src/bundle/window.ts`. Baked into the launcher at build time
+(via the `belte:bundle-window` virtual) and read directly in dev. Every
+field is optional — the launcher falls back to the program name for the
+title and to openWebview's defaults for size.
+
+The standard App/Edit/Window menus (Quit, copy/paste, minimize/close) plus the
+built-in File menu (Start server / Connect / Disconnect) are always installed.
+`menu` adds custom top-level menus between the Edit and Window menus; their items
+emit `belte:menu` events the app handles. See BundleMenuItem.
+*/
+export type BundleWindow = {
+    title?: string
+    width?: number
+    height?: number
+    menu?: BundleMenu[]
+}

package/src/lib/bundle/bindConnectedFlag.ts

@@ -0,0 +1,29 @@
+import { dlopen, FFIType } from 'bun:ffi'
+
+/*
+Binds belte_set_connected — the native flag the macOS Server menu's
+validateMenuItem: reads to enable/disable Start/Disconnect. The symbol is
+compiled only into the macOS lib (the Cocoa menu shim), so a failed lookup
+degrades to a no-op setter rather than throwing on Linux/Windows.
+
+The flag is a process-global, which is what lets the bundle's control server set
+it from off the main thread: that server runs in a Worker because `webview_run`
+blocks the main thread's JS event loop, yet the main-thread menu still reads the
+same value through the shared dylib image. The returned close releases the handle.
+*/
+export function bindConnectedFlag(libPath: string): {
+    setConnected: (connected: boolean) => void
+    close: () => void
+} {
+    try {
+        const lib = dlopen(libPath, {
+            belte_set_connected: { args: [FFIType.i32], returns: FFIType.void },
+        })
+        return {
+            setConnected: (connected) => lib.symbols.belte_set_connected(connected ? 1 : 0),
+            close: () => lib.close(),
+        }
+    } catch {
+        return { setConnected: () => {}, close: () => {} }
+    }
+}

package/src/lib/bundle/bindRequestNavigate.ts

@@ -0,0 +1,31 @@
+import { dlopen, FFIType } from 'bun:ffi'
+
+/*
+Binds belte_request_navigate — points the live webview window at a URL from any
+thread by hopping onto the UI thread via webview_dispatch. The launcher's control
+server runs in a Worker (off the main thread that webview_run blocks), so when it
+detects the connected server has died it uses this to bounce the window back to the
+connect screen. macOS-only symbol (the Cocoa shim), so a failed lookup degrades to
+a no-op — elsewhere the worker can still correct the menu flag, just not the window.
+
+`handle` is the webview pointer created on the main thread, forwarded to the worker
+as a number; bun:ffi accepts it for a ptr argument from either thread because the
+pointer addresses the same process heap.
+*/
+export function bindRequestNavigate(libPath: string): {
+    requestNavigate: (handle: number, url: string) => void
+    close: () => void
+} {
+    try {
+        const lib = dlopen(libPath, {
+            belte_request_navigate: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+        })
+        return {
+            requestNavigate: (handle, url) =>
+                lib.symbols.belte_request_navigate(handle, new TextEncoder().encode(`${url}\0`)),
+            close: () => lib.close(),
+        }
+    } catch {
+        return { requestNavigate: () => {}, close: () => {} }
+    }
+}