@belte/belte 0.19.0

package/src/lib/bundle/onMenu.ts

@@ -0,0 +1,41 @@
+/*
+Subscribes to bundle menu clicks. Each custom menu item declared in the bundle
+window config dispatches a `belte:menu` CustomEvent into the page when clicked.
+Two forms, both returning an unsubscribe so they drop straight into a Svelte
+`$effect`:
+
+    // catch-all — every emit name flows through one handler
+    $effect(() =>
+        onMenu((name) => {
+            if (name === 'reload') location.reload()
+        }),
+    )
+
+    // filtered — handler fires only for the named item
+    $effect(() => onMenu('reload', () => location.reload()))
+
+Inert during SSR and in a plain browser tab — `$effect` only runs client-side,
+the native menu that fires the event exists only in the bundled desktop app,
+and `window` is guarded so importing the module never assumes a DOM.
+*/
+export function onMenu(handler: (name: string) => void): () => void
+export function onMenu(name: string, handler: () => void): () => void
+export function onMenu(
+    nameOrHandler: string | ((name: string) => void),
+    maybeHandler?: () => void,
+): () => void {
+    if (typeof window === 'undefined') {
+        return () => {}
+    }
+    // String first arg = filter to that emit name; otherwise a catch-all handler.
+    const filter = typeof nameOrHandler === 'string' ? nameOrHandler : undefined
+    const handler = typeof nameOrHandler === 'string' ? maybeHandler : nameOrHandler
+    function listener(event: Event) {
+        const name = (event as CustomEvent<{ name: string }>).detail.name
+        if (filter === undefined || filter === name) {
+            handler?.(name)
+        }
+    }
+    window.addEventListener('belte:menu', listener)
+    return () => window.removeEventListener('belte:menu', listener)
+}

package/src/lib/bundle/openWebview.ts

@@ -0,0 +1,104 @@
+import { dlopen, FFIType, type Pointer } from 'bun:ffi'
+import type { BundleMenu } from './BundleMenu.ts'
+import { installDownloads } from './installDownloads.ts'
+import { installMacMenu } from './installMacMenu.ts'
+import { resolveWebviewLib } from './resolveWebviewLib.ts'
+
+// WEBVIEW_HINT_NONE — the window is freely resizable (the only hint we need).
+const WEBVIEW_HINT_NONE = 0
+
+/*
+Encodes a string as a NUL-terminated UTF-8 buffer for the C ABI. bun:ffi
+passes a TypedArray to a `ptr` argument as a raw pointer, and the webview
+C functions expect NUL-terminated `const char *`.
+*/
+function cString(value: string): Uint8Array {
+    return new TextEncoder().encode(`${value}\0`)
+}
+
+/*
+Opens a native OS webview window pointed at `url` and blocks until the
+user closes it. This drives the platform UI run loop (WebKit on macOS,
+WebView2 on Windows, WebKitGTK on Linux) via FFI against the webview C
+library — no Chromium is bundled. Because `webview_run` enters a blocking
+native event loop on the calling thread, the belte server must already be
+running in a separate process; this call owns the main thread until the
+window closes, then destroys the handle and releases the library.
+*/
+export async function openWebview({
+    url,
+    title,
+    width = 1024,
+    height = 768,
+    menu,
+    fileMenu,
+    onWindow,
+}: {
+    url: string
+    title: string
+    width?: number
+    height?: number
+    menu?: BundleMenu[]
+    // The File menu, inserted before Edit — the launcher's Start/Disconnect.
+    fileMenu?: BundleMenu
+    /*
+    Hands back the window handle once it exists, before the run loop blocks the
+    thread. The launcher forwards it to its control-server worker so the worker
+    can navigate the window from off-thread (e.g. bounce back to the connect
+    screen when the connected server dies).
+    */
+    onWindow?: (handle: Pointer | null) => void
+}): Promise<void> {
+    const libPath = await resolveWebviewLib()
+    const { symbols, close } = dlopen(libPath, {
+        webview_create: { args: [FFIType.i32, FFIType.ptr], returns: FFIType.ptr },
+        webview_set_title: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+        webview_set_size: {
+            args: [FFIType.ptr, FFIType.i32, FFIType.i32, FFIType.i32],
+            returns: FFIType.void,
+        },
+        webview_init: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+        webview_navigate: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+        webview_run: { args: [FFIType.ptr], returns: FFIType.void },
+        webview_destroy: { args: [FFIType.ptr], returns: FFIType.void },
+    })
+
+    /*
+    First arg is the webview's `debug` flag: 1 enables the native inspector
+    (WKWebView's Web Inspector, WebView2 DevTools, WebKitGTK inspector) so a JS
+    error on the loaded page — otherwise silent in a bare bundle window — can be
+    read via right-click → Inspect. Gated behind BELTE_INSPECT so release bundles
+    ship without it. The second arg is an optional parent handle; null = fresh window.
+    */
+    const debug = process.env.BELTE_INSPECT ? 1 : 0
+    const handle = symbols.webview_create(debug, null)
+    symbols.webview_set_title(handle, cString(title))
+    symbols.webview_set_size(handle, width, height, WEBVIEW_HINT_NONE)
+    /*
+    Install the macOS menu bar (no-op off macOS) after the application exists
+    but before the run loop starts, so Quit and the Edit shortcuts work — the
+    upstream webview omits the menu entirely — plus the bundle's custom menus.
+    */
+    installMacMenu(libPath, handle, title, menu, fileMenu)
+    /*
+    Attach the download delegate (no-op off macOS / before 11.3) before the
+    first navigation, so `<a download>`, blob/data links, and attachment
+    responses save a file instead of being silently dropped by the bare webview.
+    */
+    installDownloads(libPath, handle)
+    onWindow?.(handle)
+
+    /*
+    Stamp the bundle marker before navigation so it runs ahead of page scripts on
+    every document the webview loads — local embedded server or a remote one. This
+    is what makes browser-side bundled() report "in the webview" regardless of who
+    served the page; a plain browser tab (even hitting the embedded localhost
+    server) never runs this, so it stays false there.
+    */
+    symbols.webview_init(handle, cString('window.__BELTE_BUNDLE__=true'))
+    symbols.webview_navigate(handle, cString(url))
+    // Blocks here, running the native UI loop, until the window is closed.
+    symbols.webview_run(handle)
+    symbols.webview_destroy(handle)
+    close()
+}

package/src/lib/bundle/pngToIcns.ts

@@ -0,0 +1,47 @@
+import { log } from '../shared/log.ts'
+
+/*
+The conventional macOS `.iconset` contents — each variant is a square PNG
+at the named pixel size. `iconutil` packs a directory of exactly these
+into a multi-resolution `.icns`. @2x entries are the retina variants.
+*/
+const ICONSET_VARIANTS = [
+    { name: 'icon_16x16.png', size: 16 },
+    { name: 'icon_16x16@2x.png', size: 32 },
+    { name: 'icon_32x32.png', size: 32 },
+    { name: 'icon_32x32@2x.png', size: 64 },
+    { name: 'icon_128x128.png', size: 128 },
+    { name: 'icon_128x128@2x.png', size: 256 },
+    { name: 'icon_256x256.png', size: 256 },
+    { name: 'icon_256x256@2x.png', size: 512 },
+    { name: 'icon_512x512.png', size: 512 },
+    { name: 'icon_512x512@2x.png', size: 1024 },
+]
+
+/*
+Converts a PNG into a macOS `.icns` using the system `sips` + `iconutil`
+tools, which ship with macOS. `sips` resizes the source into each iconset
+variant; `iconutil` packs the iconset directory into the `.icns`. Returns
+true on success. On any failure (tools missing, unreadable source) it logs
+a warning and returns false so the bundle still completes without an icon
+rather than aborting the whole build.
+*/
+export async function pngToIcns(pngPath: string, outPath: string): Promise<boolean> {
+    const iconset = `${outPath}.iconset`
+    try {
+        await Bun.$`mkdir -p ${iconset}`.quiet()
+        await Promise.all(
+            ICONSET_VARIANTS.map(({ name, size }) =>
+                Bun.$`sips -z ${size} ${size} ${pngPath} --out ${`${iconset}/${name}`}`.quiet(),
+            ),
+        )
+        await Bun.$`iconutil -c icns ${iconset} -o ${outPath}`.quiet()
+        return true
+    } catch (error) {
+        log.warn(`could not convert ${pngPath} to .icns — bundling without an icon`)
+        log.error(error)
+        return false
+    } finally {
+        await Bun.$`rm -rf ${iconset}`.quiet()
+    }
+}

package/src/lib/bundle/probeBelteServer.ts

@@ -0,0 +1,34 @@
+// The identity shape a belte server returns from GET /__belte/identity.
+export type BelteIdentity = { name: string; version: string }
+
+/*
+Confirms a URL points at a belte server before the launcher navigates the app
+window there, by fetching its unauthenticated identity endpoint. Returns the
+server's identity on success, or undefined when nothing belte answers — a network
+error, the wrong port, or a non-belte page (a bare 403/404, a different app). The
+endpoint bypasses the app's own middleware, so an auth-guarded belte app still
+verifies here even though its pages would later redirect to a login.
+*/
+export async function probeBelteServer(target: string): Promise<BelteIdentity | undefined> {
+    try {
+        const base = target.replace(/\/+$/, '')
+        const response = await fetch(`${base}/__belte/identity`, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(5000),
+        })
+        if (!response.ok) {
+            return undefined
+        }
+        const body = (await response.json()) as {
+            belte?: boolean
+            name?: string
+            version?: string
+        }
+        if (body.belte !== true) {
+            return undefined
+        }
+        return { name: body.name ?? 'belte app', version: body.version ?? '0.0.0' }
+    } catch {
+        return undefined
+    }
+}

package/src/lib/bundle/resolveServerBinary.ts

@@ -0,0 +1,12 @@
+import { dirname, join } from 'node:path'
+import { serverBinaryFilename } from './serverBinaryFilename.ts'
+
+/*
+Locates the embedded server binary that ships beside the launcher inside a
+bundle. The launcher's own path is `process.execPath` (the compiled binary
+itself), so the server sits in the same directory — true for both the
+flat-directory layout and a macOS `.app`'s `Contents/MacOS/`.
+*/
+export function resolveServerBinary(): string {
+    return join(dirname(process.execPath), serverBinaryFilename())
+}

package/src/lib/bundle/resolveWebviewLib.ts

@@ -0,0 +1,53 @@
+import { dirname, join } from 'node:path'
+import { bundleLayout } from '../shared/bundleLayout.ts'
+import { webviewCachePath } from './webviewCachePath.ts'
+import { webviewLibName } from './webviewLibName.ts'
+
+/*
+Locates the native webview shared library to load over FFI, without ever
+compiling — this runs in the compiled launcher too, where no toolchain is
+present. Resolution order:
+
+  1. BELTE_WEBVIEW_LIB — explicit path, the escape hatch for any layout.
+  2. inside a bundle — beside the launcher binary (flat layout) or in
+     `../Frameworks` (macOS `.app`), so a shipped bundle is self-contained.
+  3. belte's own build cache — the library compiled from the vendored
+     header by buildWebviewLib (populated at build time via ensureWebviewLib).
+
+belte ships the vendored source rather than a prebuilt binary, so the
+toolchain path (`belte bundle`) calls ensureWebviewLib to build-on-miss;
+this resolver only reports what already exists. Throws with
+guidance when nothing resolves rather than letting dlopen fail opaquely.
+*/
+export async function resolveWebviewLib(cwd: string = process.cwd()): Promise<string> {
+    const fromEnv = process.env.BELTE_WEBVIEW_LIB
+    if (fromEnv) {
+        return fromEnv
+    }
+
+    const libName = webviewLibName()
+
+    /*
+    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 (flat layout)
+    or its sibling Frameworks dir (macOS `.app`) — bundleLayout knows which.
+    */
+    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
+        }
+    }
+
+    const cached = webviewCachePath()
+    if (await Bun.file(cached).exists()) {
+        return cached
+    }
+
+    throw new Error(
+        '[belte] no native webview library found. Run `belte bundle` to ' +
+            'build it from the vendored source, or set BELTE_WEBVIEW_LIB to a prebuilt one.',
+    )
+}

package/src/lib/bundle/serverBinaryFilename.ts

@@ -0,0 +1,8 @@
+/*
+Filename of the embedded server binary that ships beside the launcher
+inside a bundle. Both the bundler (which writes it) and the launcher
+(which spawns it) derive the name here so they can't drift apart.
+*/
+export function serverBinaryFilename(platform: NodeJS.Platform = process.platform): string {
+    return platform === 'win32' ? 'server.exe' : 'server'
+}

package/src/lib/bundle/signMacApp.ts

@@ -0,0 +1,35 @@
+import { log } from '../shared/log.ts'
+
+/*
+Ad-hoc code-signs an assembled macOS `.app` so it launches on other Macs.
+
+Apple Silicon mandates a valid code signature for every executable. `bun
+build --compile` emits an ad-hoc, linker-signed binary, but assembling the
+`.app` around it (writing Info.plist, dropping in the lib) leaves the bundle
+unsealed — `codesign --verify` then reports the signature as modified, and a
+copy that picks up a quarantine flag (AirDrop, USB, download) gets silently
+killed by Gatekeeper/AMFI: the icon bounces once and nothing opens.
+
+Re-signing inside-out fixes that. Nested Mach-O code (the webview dylib, the
+embedded server binary, the launcher) is signed first, then the bundle as a
+whole, which seals Resources and binds Info.plist. The identity is `-`,
+ad-hoc: no certificate, no Developer account, no network — as far as signing
+goes without a paid Developer ID. Recipients copying a quarantined bundle
+still need `xattr -cr <app>` once, but the app no longer fails to launch.
+
+Best-effort: if `codesign` is missing or fails, warn and return rather than
+abort the bundle, which is otherwise complete and usable on the build host.
+*/
+export async function signMacApp(bundleRoot: string, innerPaths: string[]): Promise<void> {
+    try {
+        // Inner Mach-O code inside-out, then the bundle, which re-signs the
+        // main executable as part of sealing — order matters for nested seals.
+        for (const path of innerPaths) {
+            await Bun.$`codesign --force --sign - ${path}`.quiet()
+        }
+        await Bun.$`codesign --force --sign - ${bundleRoot}`.quiet()
+    } catch (error) {
+        log.warn(`could not code-sign ${bundleRoot} — it may not launch when copied to another Mac`)
+        log.error(error)
+    }
+}

package/src/lib/bundle/spawnEmbeddedServer.ts

@@ -0,0 +1,65 @@
+import { dirname, join } from 'node:path'
+import { DEFAULT_PORT } from '../server/runtime/DEFAULT_PORT.ts'
+import { findOpenPort } from '../server/runtime/findOpenPort.ts'
+import { parsePort } from '../server/runtime/parsePort.ts'
+import { appDataDir } from '../shared/appDataDir.ts'
+import { bundleLayout } from '../shared/bundleLayout.ts'
+import { readEnvFile } from '../shared/readEnvFile.ts'
+import { resolveServerBinary } from './resolveServerBinary.ts'
+import { waitForServer } from './waitForServer.ts'
+
+/*
+The port the embedded server binds. A `PORT` from the shell, the data-dir `.env`
+(where the config form writes), or the shipped binary-dir `.env` is honored — so
+the server answers at a fixed, known address another machine can reliably connect
+to. With none set, the first open port at/above 3000 is chosen (matching the
+standalone server's default). Precedence matches the server's own env stack:
+shell > data-dir > binary-dir. A configured port is used as-is — if it's taken,
+the bind failure surfaces rather than silently moving.
+*/
+async function resolveEmbeddedPort(programName: string): Promise<number> {
+    const [dataDirEnv, binaryDirEnv] = await Promise.all([
+        readEnvFile(join(appDataDir(programName), '.env')),
+        readEnvFile(bundleLayout(dirname(process.execPath)).envPath),
+    ])
+    return (
+        parsePort(process.env.PORT ?? dataDirEnv.PORT ?? binaryDirEnv.PORT) ??
+        findOpenPort(DEFAULT_PORT)
+    )
+}
+
+/*
+Spawns the sibling server binary on a free port and waits for it to answer,
+returning the live URL plus the child so the caller owns its lifetime (reaping on
+disconnect/exit). Readiness is raced against the child's exit so a server that
+crashes on boot (missing config) surfaces immediately instead of stalling out
+waitForServer's full timeout; the loser branch resolves (never rejects) so it
+can't surface as an unhandled rejection once the child is later reaped. Does not
+reap a previous child — the caller owns that.
+*/
+export async function spawnEmbeddedServer({
+    programName,
+    timeoutMs,
+}: {
+    programName: string
+    timeoutMs?: number
+}): Promise<{ url: string; child: ReturnType<typeof Bun.spawn> }> {
+    const port = await resolveEmbeddedPort(programName)
+    const url = `http://localhost:${port}`
+    const child = Bun.spawn({
+        cmd: [resolveServerBinary()],
+        // BELTE_PARENT_PID lets the child exit if the parent is force-quit (a clean
+        // shutdown reaps it directly). The server resolves its own config from its
+        // data-dir/binary-dir .env at boot, so nothing else is injected.
+        env: { ...process.env, PORT: String(port), BELTE_PARENT_PID: String(process.pid) },
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    const outcome = await Promise.race([
+        waitForServer(url, timeoutMs ? { timeoutMs } : undefined).then(() => undefined),
+        child.exited,
+    ])
+    if (outcome !== undefined) {
+        throw new Error(`[belte] embedded server exited (code ${outcome}) before binding`)
+    }
+    return { url, child }
+}

package/src/lib/bundle/stableLocalPort.ts

@@ -0,0 +1,19 @@
+/*
+Derives a deterministic localhost port from the program name so the connect
+screen's origin (and thus its localStorage) stays stable across launches — a
+remembered server URL survives a relaunch only if the page is reloaded from the
+same origin. Hashes the name with FNV-1a (32-bit) and maps it into the
+dynamic/private range (49152–65535). The caller probes availability and falls
+back to a random free port on collision, so determinism is a best effort, not a
+guarantee.
+*/
+export function stableLocalPort(programName: string): number {
+    // FNV-1a 32-bit: offset basis 2166136261, prime 16777619. Math.imul keeps
+    // the multiply in 32-bit space; `>>> 0` reads the result back as unsigned.
+    let hash = 0x811c9dc5
+    for (const character of programName) {
+        hash ^= character.charCodeAt(0)
+        hash = Math.imul(hash, 0x01000193)
+    }
+    return 49152 + ((hash >>> 0) % 16384)
+}

package/src/lib/bundle/waitForServer.ts

@@ -0,0 +1,23 @@
+/*
+Polls an HTTP URL until it answers (any status) or the deadline passes.
+The spawned server child binds asynchronously, so the launcher can't open
+the webview until a request round-trips. A connection refusal throws and
+is swallowed; once Bun.serve is listening the fetch resolves and we
+return. Throws on timeout so the launcher can report a failed boot rather
+than open a blank window.
+*/
+export async function waitForServer(
+    url: string,
+    { timeoutMs = 10_000, intervalMs = 50 }: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<void> {
+    const deadline = Bun.nanoseconds() + timeoutMs * 1e6
+    while (Bun.nanoseconds() < deadline) {
+        try {
+            await fetch(url)
+            return
+        } catch {
+            await Bun.sleep(intervalMs)
+        }
+    }
+    throw new Error(`[belte] server did not become ready at ${url} within ${timeoutMs}ms`)
+}

package/src/lib/bundle/webviewCachePath.ts

@@ -0,0 +1,23 @@
+import { join } from 'node:path'
+import { WEBVIEW_BUILD_REVISION } from './WEBVIEW_BUILD_REVISION.ts'
+import { WEBVIEW_VERSION } from './WEBVIEW_VERSION.ts'
+import { webviewLibName } from './webviewLibName.ts'
+
+/*
+Absolute path where the locally built webview library is cached. belte
+compiles the vendored `native/webview.h` once per host and reuses the
+result; both buildWebviewLib (the writer) and resolveWebviewLib (a reader)
+derive the location here so they never drift.
+
+The cache sits next to the vendored source inside the belte package, so it
+is shared across every project on the machine that uses this belte install
+and survives independently of any consumer's `cwd`. Namespacing by
+platform + arch + upstream version keeps a single cache correct across
+architectures and makes a header bump — or a belte native-build bump — select
+a fresh path automatically.
+*/
+export function webviewCachePath(): string {
+    const nativeDir = new URL('./native', import.meta.url).pathname
+    const key = `${process.platform}-${process.arch}-${WEBVIEW_VERSION}-${WEBVIEW_BUILD_REVISION}`
+    return join(nativeDir, '.cache', key, webviewLibName())
+}

package/src/lib/bundle/webviewLibName.ts

@@ -0,0 +1,11 @@
+import { suffix } from 'bun:ffi'
+
+/*
+Native webview shared-library filename for a platform. `suffix` is Bun's
+host shared-library extension (`dylib`/`so`/`dll`). The bundler copies a
+file under this name and the loader looks for it under the same name, so
+both derive it here.
+*/
+export function webviewLibName(platform: NodeJS.Platform = process.platform): string {
+    return platform === 'win32' ? `webview.${suffix}` : `libwebview.${suffix}`
+}

package/src/lib/cli/connectToServer.ts

@@ -0,0 +1,23 @@
+import { probeBelteServer } from '../bundle/probeBelteServer.ts'
+import { log } from '../shared/log.ts'
+import { writeLastConnection } from '../shared/writeLastConnection.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Connects to a remote belte server: probes its identity endpoint first so we never
+record or talk to a non-belte URL, then persists the intent so the next bare run
+resumes here. Carries the env bearer token (baked or shell) for authed servers.
+Returns the target, or undefined when nothing belte answers.
+*/
+export async function connectToServer(
+    programName: string,
+    url: string,
+): Promise<CliTarget | undefined> {
+    const identity = await probeBelteServer(url)
+    if (!identity) {
+        log.warn(`no belte server responded at ${url}`)
+        return undefined
+    }
+    await writeLastConnection(programName, { kind: 'url', url })
+    return { url, token: process.env.BELTE_APP_TOKEN, name: identity.name }
+}