@abide/abide 0.28.0

package/src/lib/bundle/onMenu.ts

@@ -0,0 +1,42 @@
+/*
+Subscribes to bundle menu clicks. Each custom menu item declared in the bundle
+window config dispatches a `abide:menu` CustomEvent into the page when clicked.
+Two forms, both returning an unsubscribe so they drop straight into an
+`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.
+*/
+// @readme bundle
+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('abide:menu', listener)
+    return () => window.removeEventListener('abide: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 abide 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 ABIDE_INSPECT so release bundles
+    ship without it. The second arg is an optional parent handle; null = fresh window.
+    */
+    const debug = process.env.ABIDE_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.__ABIDE_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 { abideLog } from '../shared/abideLog.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) {
+        abideLog.warn(`could not convert ${pngPath} to .icns — bundling without an icon`)
+        abideLog.error(error)
+        return false
+    } finally {
+        await Bun.$`rm -rf ${iconset}`.quiet()
+    }
+}

package/src/lib/bundle/probeAbideServer.ts

@@ -0,0 +1,57 @@
+import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
+import { IDENTITY_PATH } from '../shared/IDENTITY_PATH.ts'
+import { isAbideHealthPayload } from '../shared/isAbideHealthPayload.ts'
+
+// The identity shape a abide server returns from GET /__abide/health (and its /__abide/identity alias).
+export type AbideIdentity = { name: string; version: string }
+
+/*
+Confirms a URL points at a abide server before the launcher navigates the app
+window there, by fetching its unauthenticated health endpoint. Returns the
+server's identity on success, or undefined when nothing abide answers — a network
+error, the wrong port, or a non-abide page (a bare 403/404, a different app, a
+captive portal's 200 — hence the `abide: true` body check, never response.ok
+alone). The endpoint bypasses the app's own middleware, so an auth-guarded abide
+app still verifies here even though its pages would later redirect to a login.
+Probes HEALTH_PATH first, falling back to the IDENTITY_PATH alias so a newer
+launcher still recognises an older abide server. The fallback only runs when
+the host actually answered (an older server 404s the health path) — a network
+error or timeout skips it, because a host that didn't answer one path won't
+answer the other and each attempt costs the full timeout (this probe sits in
+the launcher's liveness loop).
+*/
+export async function probeAbideServer(target: string): Promise<AbideIdentity | undefined> {
+    const base = target.replace(/\/+$/, '')
+    try {
+        return (
+            (await probeIdentityAt(`${base}${HEALTH_PATH}`)) ??
+            (await probeIdentityAt(`${base}${IDENTITY_PATH}`))
+        )
+    } catch {
+        return undefined
+    }
+}
+
+/* Throws on network error/timeout; undefined means the host answered but isn't a abide server at this path. */
+async function probeIdentityAt(url: string): Promise<AbideIdentity | undefined> {
+    const response = await fetch(url, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+    })
+    if (!response.ok) {
+        return undefined
+    }
+    try {
+        const body = (await response.json()) as {
+            abide?: unknown
+            name?: string
+            version?: string
+        }
+        if (!isAbideHealthPayload(body)) {
+            return undefined
+        }
+        return { name: body.name ?? 'abide 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. ABIDE_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. abide's own build cache — the library compiled from the vendored
+     header by buildWebviewLib (populated at build time via ensureWebviewLib).
+
+abide ships the vendored source rather than a prebuilt binary, so the
+toolchain path (`abide 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.ABIDE_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(
+        '[abide] no native webview library found. Run `abide bundle` to ' +
+            'build it from the vendored source, or set ABIDE_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,37 @@
+import { abideLog } from '../shared/abideLog.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) {
+        abideLog.warn(
+            `could not code-sign ${bundleRoot} — it may not launch when copied to another Mac`,
+        )
+        abideLog.error(error)
+    }
+}

package/src/lib/bundle/spawnEmbeddedServer.ts

@@ -0,0 +1,64 @@
+import { DEFAULT_PORT } from '../server/runtime/DEFAULT_PORT.ts'
+import { findOpenPort } from '../server/runtime/findOpenPort.ts'
+import { parsePort } from '../server/runtime/parsePort.ts'
+import { binaryDirEnvPath } from '../shared/binaryDirEnvPath.ts'
+import { dataDirEnvPath } from '../shared/dataDirEnvPath.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(dataDirEnvPath(programName)),
+        readEnvFile(binaryDirEnvPath()),
+    ])
+    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()],
+        // ABIDE_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), ABIDE_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(`[abide] 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(`[abide] 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. abide
+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 abide package, so it
+is shared across every project on the machine that uses this abide 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 abide 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 { probeAbideServer } from '../bundle/probeAbideServer.ts'
+import { abideLog } from '../shared/abideLog.ts'
+import { writeLastConnection } from '../shared/writeLastConnection.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Connects to a remote abide server: probes its identity endpoint first so we never
+record or talk to a non-abide 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 abide answers.
+*/
+export async function connectToServer(
+    programName: string,
+    url: string,
+): Promise<CliTarget | undefined> {
+    const identity = await probeAbideServer(url)
+    if (!identity) {
+        abideLog.warn(`no abide server responded at ${url}`)
+        return undefined
+    }
+    await writeLastConnection(programName, { kind: 'url', url })
+    return { url, token: process.env.ABIDE_APP_TOKEN, name: identity.name }
+}

package/src/lib/cli/createClient.ts

@@ -0,0 +1,108 @@
+import { dispatchVerbInProcess } from '../server/rpc/dispatchVerbInProcess.ts'
+import { findVerbByCommandName } from '../server/rpc/findVerbByCommandName.ts'
+import { buildRpcProxy } from '../shared/buildRpcProxy.ts'
+import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import type { HttpVerb } from '../shared/types/HttpVerb.ts'
+import type { RpcInvoker } from '../shared/types/RpcInvoker.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+
+/*
+Each property of the client is a callable: invoking it decodes the body
+(plain call), while `.raw(args)` returns the underlying Response without
+decoding or throwing on non-2xx — the escape hatch the CLI uses to sniff
+the Content-Type and stream sse/jsonl bodies frame-by-frame instead of
+buffering through decodeResponse. buildRpcProxy owns that invoker contract.
+*/
+type AnyApi = Record<string, RpcInvoker>
+
+/*
+Builds a typed proxy over the project's RPCs for use in scripts, tests,
+server-to-server calls, and the standalone CLI binary. Modes are
+decided at construction:
+
+  - With `url`: remote-mode. Each property access becomes an HTTP call
+    against `<url>/<manifest[name].url>` using the manifest's method.
+    Auth header is set from `token` when provided.
+  - Without `url`: in-process mode. Each property access looks up the
+    verb in the registry (populated by importing the project's rpc
+    modules) and calls `verb.fetch(synthesizedRequest)` — same code
+    path the HTTP router uses, no network hop.
+
+The `manifest` is the bundler-emitted CLI manifest baked into the thin
+binary. In in-process mode it's optional (registry is the source of
+truth); in remote mode it supplies the method + url per command without
+needing the rpc modules loaded. The mode is chosen solely by whether
+`url` is set — the shipped CLI binary (see runCli) always passes `url`,
+so it runs remote-only; in-process mode is for same-project scripts and
+tests that import this directly without a `url`.
+*/
+export function createClient<Api extends AnyApi = AnyApi>(opts?: {
+    url?: string
+    token?: string
+    manifest?: CliManifest
+}): Api {
+    const url = opts?.url
+    const token = opts?.token
+    const manifest = opts?.manifest
+
+    // Auth + content-negotiation headers both dispatch modes attach.
+    function requestHeaders(accept?: string): Headers {
+        const headers = new Headers()
+        if (token) {
+            headers.set('authorization', `Bearer ${token}`)
+        }
+        if (accept) {
+            headers.set('accept', accept)
+        }
+        return headers
+    }
+
+    /*
+    Resolves a command name to the closure that issues its wire call, or
+    undefined when the name is unknown in the active mode. Remote mode (url set)
+    resolves method + url from the baked manifest — registry fallback for
+    same-project callers — and sends the synthesized Request over the network.
+    In-process mode resolves the verb from the registry and routes through
+    dispatchVerbInProcess, the same synthesize-and-fetch the MCP dispatcher
+    uses, so the two consumer surfaces can't drift on how a verb is invoked.
+    */
+    function resolveSend(name: string): ((args?: unknown) => Promise<Response>) | undefined {
+        if (url) {
+            const command = manifest?.[name] ?? registryCommand(name)
+            if (!command) {
+                return undefined
+            }
+            return (args) =>
+                fetch(
+                    buildRpcRequest({
+                        method: command.method,
+                        url: command.url,
+                        args,
+                        baseUrl: url,
+                        headers: requestHeaders(command.accept),
+                    }),
+                )
+        }
+        const entry = findVerbByCommandName(name)
+        if (!entry) {
+            return undefined
+        }
+        return (args) =>
+            dispatchVerbInProcess({
+                remote: entry.remote,
+                args,
+                baseUrl: 'http://localhost/',
+                headers: requestHeaders(),
+            })
+    }
+
+    // Remote-mode registry fallback for callers passing a url but no manifest.
+    function registryCommand(
+        name: string,
+    ): { method: HttpVerb; url: string; accept?: string } | undefined {
+        const found = findVerbByCommandName(name)
+        return found ? { method: found.remote.method, url: found.remote.url } : undefined
+    }
+
+    return buildRpcProxy<Api>(resolveSend)
+}