@briancray/belte 0.1.0 → 0.2.1

package/src/lib/bundle/buildWebviewLib.ts

@@ -0,0 +1,111 @@
+import { dirname } from 'node:path'
+import { log } from '../shared/log.ts'
+import { webviewCachePath } from './webviewCachePath.ts'
+import { webviewVersion } from './webviewVersion.ts'
+
+// Vendored upstream amalgamation; the host compiler turns it into a lib.
+const HEADER = new URL('./native/webview.h', import.meta.url).pathname
+
+// belte's own native shim, linked into the same dylib on macOS to add the
+// standard application menu bar the upstream webview omits.
+const MAC_MENU_SOURCE = new URL('./native/belteMenu.mm', import.meta.url).pathname
+
+/*
+Linux GTK/WebKit pkg-config module sets, newest first. The vendored header
+auto-selects the GTK4 or GTK3 backend from GTK_MAJOR_VERSION in the include
+path, so supplying the right cflags/libs is all that's needed — no backend
+macro. The first set whose packages are installed wins.
+*/
+const LINUX_PKG_SETS = [
+    ['gtk4', 'webkitgtk-6.0'],
+    ['gtk+-3.0', 'webkit2gtk-4.1'],
+    ['gtk+-3.0', 'webkit2gtk-4.0'],
+]
+
+/*
+Compiles the vendored webview header into a native shared library for the
+host platform and caches it (webviewCachePath), so `belte bundle` needs
+no prebuilt binary and no third-party webview package — just
+the platform's C++ toolchain. Returns the cached path. Throws actionable
+guidance when the toolchain or native webview dev packages are missing,
+rather than letting the compiler fail opaquely.
+*/
+export async function buildWebviewLib(): Promise<string> {
+    const outfile = webviewCachePath()
+    await Bun.$`mkdir -p ${dirname(outfile)}`.quiet()
+    log.info(`building webview ${webviewVersion} for ${process.platform}-${process.arch}…`)
+
+    if (process.platform === 'darwin') {
+        await compileDarwin(outfile)
+    } else if (process.platform === 'linux') {
+        await compileLinux(outfile)
+    } else {
+        /*
+        Windows needs MSVC + the WebView2 SDK header (WebView2.h), which
+        isn't a turnkey shell invocation. Until that build path lands,
+        point Windows users at the explicit-path escape hatch.
+        */
+        throw new Error(
+            `[belte] building the webview library on ${process.platform} isn't supported yet. ` +
+                'Set BELTE_WEBVIEW_LIB to a prebuilt webview library to continue.',
+        )
+    }
+
+    log.success(`built webview library: ${outfile}`)
+    return outfile
+}
+
+// macOS: clang against the WebKit + Cocoa frameworks (always present with the
+// Command Line Tools), linking belte's Objective-C++ menu shim into the same
+// dylib. The `-x` flags switch the input language per file: the vendored
+// header compiles as C++ (it uses the C objc runtime, not objc syntax), the
+// shim as Objective-C++. Maps a missing compiler to the install hint.
+async function compileDarwin(outfile: string): Promise<void> {
+    try {
+        await Bun.$`clang++ -std=c++17 -DWEBVIEW_BUILD_SHARED -fvisibility=hidden -shared -framework WebKit -framework Cocoa -x c++ ${HEADER} -x objective-c++ ${MAC_MENU_SOURCE} -o ${outfile}`.quiet()
+    } catch (error) {
+        throw new Error(
+            '[belte] failed to compile the webview library. Install the Xcode Command ' +
+                'Line Tools with `xcode-select --install` and try again.\n' +
+                describeShellError(error),
+        )
+    }
+}
+
+// Linux: detect an installed GTK/WebKit set via pkg-config, then compile a
+// position-independent shared object. Maps missing packages to install hints.
+async function compileLinux(outfile: string): Promise<void> {
+    const flags = await linuxPkgFlags()
+    try {
+        await Bun.$`c++ -std=c++17 -DWEBVIEW_BUILD_SHARED -fvisibility=hidden -fPIC -shared -x c++ ${HEADER} ${flags} -o ${outfile}`.quiet()
+    } catch (error) {
+        throw new Error(
+            '[belte] failed to compile the webview library. Ensure a C++ compiler ' +
+                '(e.g. `build-essential`) is installed.\n' +
+                describeShellError(error),
+        )
+    }
+}
+
+// Returns combined cflags + libs for the first available GTK/WebKit set, or
+// throws with the package names to install when none resolve.
+async function linuxPkgFlags(): Promise<string[]> {
+    for (const modules of LINUX_PKG_SETS) {
+        const probe = await Bun.$`pkg-config --exists ${modules}`.nothrow().quiet()
+        if (probe.exitCode === 0) {
+            const flags = await Bun.$`pkg-config --cflags --libs ${modules}`.quiet().text()
+            return flags.trim().split(/\s+/)
+        }
+    }
+    throw new Error(
+        '[belte] no GTK/WebKit development packages found. Install one set, e.g. ' +
+            '`libgtk-4-dev libwebkitgtk-6.0-dev` or `libgtk-3-dev libwebkit2gtk-4.1-dev`, ' +
+            'or set BELTE_WEBVIEW_LIB to a prebuilt webview library.',
+    )
+}
+
+// Surfaces the compiler's own stderr when a Bun shell command throws.
+function describeShellError(error: unknown): string {
+    const stderr = (error as { stderr?: Uint8Array }).stderr
+    return stderr ? new TextDecoder().decode(stderr) : String(error)
+}

package/src/lib/bundle/disconnected.css

@@ -0,0 +1,9 @@
+/*
+Tailwind entry for the bundle connect screen. `@import "tailwindcss"` pulls the
+engine in; the explicit `@source` guarantees the default component is scanned for
+utility classes even if automatic source detection misses it. bun-plugin-tailwind
+compiles this at build time; buildDisconnected inlines the result into the served
+HTML so the screen needs zero external requests.
+*/
+@import 'tailwindcss';
+@source './disconnected.svelte';

package/src/lib/bundle/disconnected.svelte

@@ -0,0 +1,192 @@
+<script lang="ts">
+/*
+Default bundle connect screen. The launcher serves this (with the logo baked in
+at build time and the app title injected at runtime) instead of a blank window,
+and overriding it is a matter of dropping a `src/bundle/disconnected.svelte`.
+
+It both connects to a remote server by URL and boots the embedded server, talking
+to the launcher's in-process control server: POST /connect and POST /start each
+reply with a `{ redirect }` the page follows, while the launcher records the
+connection so the native File menu's enabled state stays authoritative.
+*/
+
+/*
+localStorage key holding the last connection so a relaunch repeats it: either a
+remote server URL, or the START_EMBEDDED sentinel meaning "boot the embedded
+server". The embedded server's own URL can't be persisted — it picks a fresh
+port each launch — so we persist the intent and re-run start() instead.
+Disconnect clears it so a relaunch never auto-retries a forgotten server.
+*/
+const STORAGE_KEY = 'belte:server-url'
+const START_EMBEDDED = 'belte:start-embedded'
+
+/*
+The last remote URL that successfully connected, kept separate from STORAGE_KEY
+so it survives disconnect (and the app quitting): it only prefills the form, it
+never drives an auto-reconnect, so reconnecting to the same server stays one
+click away even after an explicit disconnect.
+*/
+const LAST_URL_KEY = 'belte:last-server-url'
+
+// Injected globals: app title from the launcher, logo data URI from the build.
+const heading =
+    (globalThis as { __BELTE_TITLE__?: string }).__BELTE_TITLE__ ?? 'belte app'
+const logo = (globalThis as { __BELTE_LOGO__?: string }).__BELTE_LOGO__
+
+const placeholder = 'https://example.com'
+
+// Prefill the form with the last server we connected to, from any prior launch.
+let url = $state(localStorage.getItem(LAST_URL_KEY) ?? '')
+let starting = $state(false)
+let error = $state<string | undefined>(undefined)
+
+/*
+Interpret the boot intent once on load. `?action=` is set by the native File
+menu's navigate items (or the launcher when a live connection dies); absent it, a
+remembered server reconnects automatically:
+  - start      → boot the embedded server (matches the Start Server menu item).
+  - lost       → the connected server stopped responding; explain and wait (the
+                 form is already prefilled with the last URL for a one-click retry).
+  - disconnect → forget the URL + tear down any embedded server, stay here so the
+                 form is the place to point at another server.
+  - (none)     → reconnect to the saved server if there is one.
+*/
+$effect(() => {
+    const action = new URLSearchParams(location.search).get('action')
+    const saved = localStorage.getItem(STORAGE_KEY) ?? undefined
+    if (action === 'start') {
+        void start()
+        return
+    }
+    if (action === 'lost') {
+        error = 'The server stopped responding.'
+        return
+    }
+    if (action === 'disconnect') {
+        // Forget the auto-reconnect intent but keep LAST_URL_KEY, so the form
+        // stays prefilled with the server we just left for a one-click return.
+        localStorage.removeItem(STORAGE_KEY)
+        void fetch('/__belte/disconnect').catch(() => {})
+        return
+    }
+    // No action: repeat the last choice — re-boot the embedded server, or reconnect.
+    if (saved === START_EMBEDDED) {
+        void start()
+        return
+    }
+    if (saved) {
+        void connect(saved)
+    }
+})
+
+/*
+Ask the launcher to connect to a server by URL. It verifies the URL really is a
+belte server — POST /connect probes the target's identity endpoint — and flips the
+native menu's connected flag before replying with the `{ redirect }` to follow; a
+URL that isn't a belte server comes back as an error shown below the form. Only a
+confirmed URL is remembered, so a relaunch never auto-retries a dead or wrong
+address. The saved-URL reconnect path runs through here too.
+*/
+async function connect(target: string = url.trim()): Promise<void> {
+    const cleaned = target.trim()
+    if (!cleaned) {
+        return
+    }
+    error = undefined
+    try {
+        const response = await fetch('/connect', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ url: cleaned }),
+        })
+        if (!response.ok) {
+            const body = (await response.json()) as { error?: string }
+            throw new Error(body.error ?? `connect failed (${response.status})`)
+        }
+        const { redirect } = (await response.json()) as { redirect: string }
+        localStorage.setItem(STORAGE_KEY, cleaned)
+        // Remember it separately so it outlives a later disconnect and prefills the form.
+        localStorage.setItem(LAST_URL_KEY, cleaned)
+        location.href = redirect
+    } catch (cause) {
+        error = `Could not connect: ${String(cause)}`
+    }
+}
+
+// Boot the embedded server via the launcher, then follow it once it answers.
+async function start(): Promise<void> {
+    error = undefined
+    starting = true
+    // Remember the embedded-server choice so the next launch boots it automatically.
+    localStorage.setItem(STORAGE_KEY, START_EMBEDDED)
+    try {
+        const response = await fetch('/start', { method: 'POST' })
+        if (!response.ok) {
+            const body = (await response.json()) as { error?: string }
+            throw new Error(body.error ?? `start failed (${response.status})`)
+        }
+        const { redirect } = (await response.json()) as { redirect: string }
+        location.href = redirect
+    } catch (cause) {
+        error = `Could not start the server: ${String(cause)}`
+        starting = false
+    }
+}
+</script>
+
+<main class="flex min-h-screen items-center justify-center bg-gray-50 p-6 text-gray-900">
+    <div class="w-full max-w-sm rounded-2xl bg-white p-8 shadow-sm ring-1 ring-gray-200">
+        {#if logo}
+            <img src={logo} alt="" class="mx-auto mb-5 h-16 w-16 rounded-xl object-contain" />
+        {/if}
+        <h1 class="mb-6 text-center text-xl font-semibold tracking-tight">{heading}</h1>
+
+        <form
+            class="flex flex-col gap-3"
+            onsubmit={(event) => {
+                event.preventDefault()
+                void connect()
+            }}
+        >
+            <input
+                type="url"
+                bind:value={url}
+                {placeholder}
+                autocomplete="url"
+                class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm outline-none focus:border-gray-900 focus:ring-1 focus:ring-gray-900"
+            />
+            <button
+                type="submit"
+                class="w-full rounded-lg bg-gray-900 px-3 py-2 text-sm font-medium text-white hover:bg-gray-700"
+            >
+                Connect
+            </button>
+        </form>
+
+        <div class="my-5 flex items-center gap-3 text-xs text-gray-400">
+            <span class="h-px flex-1 bg-gray-200"></span>
+            or
+            <span class="h-px flex-1 bg-gray-200"></span>
+        </div>
+
+        <button
+            type="button"
+            onclick={() => void start()}
+            disabled={starting}
+            class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium hover:bg-gray-50 disabled:opacity-60"
+        >
+            {starting ? 'Starting…' : 'Start server'}
+        </button>
+
+        {#if error}
+            <p class="mt-4 text-center text-sm text-red-600">{error}</p>
+        {/if}
+
+        <p class="mt-8 text-center text-xs text-gray-400">
+            made with
+            <a href="https://github.com/briancray/belte" class="underline hover:text-gray-600">
+                belte
+            </a>
+        </p>
+    </div>
+</main>

package/src/lib/bundle/ensureWebviewLib.ts

@@ -0,0 +1,20 @@
+import { buildWebviewLib } from './buildWebviewLib.ts'
+import { resolveWebviewLib } from './resolveWebviewLib.ts'
+
+/*
+Build-time guarantee that a webview library exists, returning its path.
+Tries plain resolution first (an explicit BELTE_WEBVIEW_LIB, a bundle-local
+copy, or a previously built cache); on a miss it compiles the vendored
+header for the host (buildWebviewLib) and caches the result.
+
+Used by `belte bundle` (bundleApp), which runs under bun on a developer's
+machine — never by the compiled launcher, which only ever resolves the copy
+shipped beside it and must not invoke a compiler on an end user's machine.
+*/
+export async function ensureWebviewLib(cwd: string = process.cwd()): Promise<string> {
+    try {
+        return await resolveWebviewLib(cwd)
+    } catch {
+        return await buildWebviewLib()
+    }
+}

package/src/lib/bundle/exitWithParent.ts

@@ -0,0 +1,28 @@
+/*
+Tie the embedded server's lifetime to the bundle launcher's.
+
+The launcher spawns this server with BELTE_PARENT_PID set to its own pid. On a
+clean window close the launcher reaps the child directly, but a force-quit (or
+crash) of the launcher can't run that cleanup, which would leave the server
+orphaned and holding its port. So when that env var is present, poll the parent
+and exit once it's gone. A no-op when the var is absent (standalone `belte
+start`), so it only ever activates inside a bundle.
+*/
+export function exitWithParent(): void {
+    const parent = process.env.BELTE_PARENT_PID
+    if (!parent) {
+        return
+    }
+    const parentPid = Number(parent)
+    const timer = setInterval(() => {
+        try {
+            // Signal 0 sends nothing — it only probes existence, throwing when the
+            // parent has exited (or its pid is no longer reachable).
+            process.kill(parentPid, 0)
+        } catch {
+            process.exit(0)
+        }
+    }, 1000)
+    // The watchdog alone shouldn't keep the server process alive.
+    timer.unref()
+}

package/src/lib/bundle/findFreePort.ts

@@ -0,0 +1,14 @@
+/*
+Asks the OS for an unused TCP port by binding a throwaway Bun server to
+port 0 (the kernel assigns a free port), reading the assigned port, then
+stopping it immediately. There is an unavoidable race between releasing
+the port here and the server child re-binding it, but for a
+single-user bundle launch the window is negligible.
+*/
+export function findFreePort(): number {
+    const probe = Bun.serve({ port: 0, fetch: () => new Response() })
+    // A TCP server bound to port 0 always reports a numeric assigned port.
+    const port = probe.port as number
+    probe.stop(true)
+    return port
+}

package/src/lib/bundle/infoPlist.ts

@@ -0,0 +1,46 @@
+/*
+Renders the `Info.plist` for a macOS `.app` bundle. CFBundleExecutable
+must match the launcher's filename in `Contents/MacOS/` or the app won't
+launch. `icon` is the filename (without extension) of an `.icns` under
+`Contents/Resources/`; omitted when the project ships no icon. The
+identifier is synthesized from the program name; a real distribution would
+override it with a registered reverse-DNS id.
+*/
+export function infoPlist({
+    name,
+    version,
+    icon,
+}: {
+    name: string
+    version: string
+    icon?: string
+}): string {
+    const iconEntry = icon
+        ? `    <key>CFBundleIconFile</key>
+    <string>${icon}</string>
+`
+        : ''
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleName</key>
+    <string>${name}</string>
+    <key>CFBundleDisplayName</key>
+    <string>${name}</string>
+    <key>CFBundleExecutable</key>
+    <string>${name}</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.belte.${name}</string>
+    <key>CFBundleVersion</key>
+    <string>${version}</string>
+    <key>CFBundleShortVersionString</key>
+    <string>${version}</string>
+${iconEntry}    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+</dict>
+</plist>
+`
+}

package/src/lib/bundle/installMacMenu.ts

@@ -0,0 +1,39 @@
+import { dlopen, FFIType, type Pointer } from 'bun:ffi'
+import type { BundleMenu } from './BundleMenu.ts'
+
+/*
+Installs the macOS application menu bar via belte's native shim in the webview
+library. The standard App/Edit/Window menus are always present — so Cmd-Q and the
+Edit shortcuts (Cmd-C/V/X/A/Z) work, which the bare upstream webview window lacks
+— plus the launcher's `fileMenu` (inserted as File, before Edit) and the bundle's
+custom `menu` (between Edit and Window). Menu items are serialised as
+`{ separator: true }`, `{ label, shortcut?, navigate, role? }`, or
+`{ label, shortcut?, emit }`: `navigate` items repoint the live window (the
+launcher's File menu uses these, with `role` gating their enabled state against the
+native connected flag set by `belte_set_connected`), `emit` items dispatch
+`belte:menu` events into the page. `appName` labels the App-menu items.
+
+The config is serialised to JSON and parsed natively, so the launcher never
+touches FFI. A no-op off macOS, where the shim symbol isn't compiled into the
+library; opened as its own short-lived handle to keep openWebview's FFI map
+fully typed (a conditional symbol there defeats Bun's argument-type inference).
+The native menu attaches to the shared NSApplication, so it persists after this
+handle closes.
+*/
+export function installMacMenu(
+    libPath: string,
+    webviewHandle: Pointer | null,
+    appName: string,
+    menu: BundleMenu[] | undefined,
+    fileMenu: BundleMenu | undefined,
+): void {
+    if (process.platform !== 'darwin') {
+        return
+    }
+    const { symbols, close } = dlopen(libPath, {
+        belte_install_app_menu: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+    })
+    const config = JSON.stringify({ appName, fileMenu, menu })
+    symbols.belte_install_app_menu(webviewHandle, new TextEncoder().encode(`${config}\0`))
+    close()
+}

package/src/lib/bundle/listenLocalControlServer.ts

@@ -0,0 +1,19 @@
+/*
+Binds the launcher's in-process control server to the given localhost port,
+falling back to a kernel-assigned free port when that port is already taken
+(another instance of the same app, or an unrelated process). The stable port
+keeps the connect screen's origin — and its localStorage — constant across
+launches; the fallback trades that stability for the app still booting. Callers
+read the actual port from the returned server's `.port` to build the origin.
+*/
+export function listenLocalControlServer(
+    port: number,
+    fetch: (request: Request) => Response | Promise<Response>,
+): ReturnType<typeof Bun.serve> {
+    try {
+        return Bun.serve({ port, hostname: '127.0.0.1', fetch })
+    } catch {
+        // EADDRINUSE (or any bind failure) on the stable port → take any free one.
+        return Bun.serve({ port: 0, hostname: '127.0.0.1', fetch })
+    }
+}