@briancray/belte 0.3.1 → 0.5.0

package/src/lib/browser/startClient.ts

@@ -25,10 +25,11 @@ pass finds the data via cache() without issuing a network round-trip.
 */
 function hydrateCacheFromSnapshot(store: CacheStore, snapshot: CacheSnapshotEntry[]): void {
     for (const entry of snapshot) {
+        const headers = new Headers(entry.headers)
         const response = new Response(entry.body, {
             status: entry.status,
             statusText: entry.statusText,
-            headers: new Headers(entry.headers),
+            headers,
         })
         store.entries.set(entry.key, {
             key: entry.key,
@@ -36,10 +37,32 @@ function hydrateCacheFromSnapshot(store: CacheStore, snapshot: CacheSnapshotEntr
             request: new Request(entry.url, { method: entry.method }),
             ttl: undefined,
             expiresAt: undefined,
+            value: warmValueFromSnapshot(entry.status, headers, entry.body),
         })
     }
 }
 
+/*
+Synchronously decodes a snapshot body so the warm entry reads without a
+microtask hop on first render. Mirrors decodeResponse for the textual cases
+the snapshot ships; non-2xx and 204 yield no warm value and fall back to the
+async path, which throws HttpError / returns undefined exactly as a live call
+would. Binary/xml bodies also skip the warm path and decode asynchronously.
+*/
+function warmValueFromSnapshot(status: number, headers: Headers, body: string): unknown {
+    if (status === 204 || status < 200 || status >= 300) {
+        return undefined
+    }
+    const contentType = (headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.includes('json')) {
+        return JSON.parse(body)
+    }
+    if (contentType.startsWith('text/')) {
+        return body
+    }
+    return undefined
+}
+
 function isInternalLinkEvent(event: MouseEvent): HTMLAnchorElement | undefined {
     if (event.defaultPrevented) {
         return undefined

package/src/lib/bundle/BundleWindow.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '../server/rpc/types/StandardSchemaV1.ts'
 import type { BundleMenu } from './BundleMenu.ts'
 
 /*
@@ -17,4 +18,14 @@ export type BundleWindow = {
     width?: number
     height?: number
     menu?: BundleMenu[]
+    /*
+    Config the embedded server needs before it can run, as a Standard Schema (the
+    same kind belte accepts for RPC/MCP). Its JSON Schema drives the connect
+    screen's first-run form, shown as a modal when Start is clicked with a required
+    key still unset; the user's answers persist to the data-dir `.env` the server
+    loads at boot. Each property maps to one env var of the same name; `title` is
+    the field label, `description` the hint, `format: 'password'` masks the input,
+    and `default` pre-fills it.
+    */
+    config?: StandardSchemaV1
 }

package/src/lib/bundle/disconnected.svelte

@@ -11,20 +11,9 @@ 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.
+The last remote URL that successfully connected — only prefills the form's input
+on a later visit; it never drives a reconnect (the launcher owns auto-resume now,
+deciding before the window even opens). Survives disconnect and quitting.
 */
 const LAST_URL_KEY = 'belte:last-server-url'
 
@@ -36,9 +25,51 @@ 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)
 
+/*
+`?action=` set by the File menu (Start/Disconnect) or the launcher when a live
+connection dies (`lost`). Auto-resume of a saved connection now happens in the
+launcher before the window opens, so this screen only ever loads as a real
+destination — there's no no-action auto-resume left to handle here.
+*/
+const launchAction = new URLSearchParams(location.search).get('action')
+
+/*
+Two phases so the screen never flashes before a redirect. A menu Start may boot
+straight through, so it opens on a neutral splash; every other entry is a genuine
+destination, so the connect screen shows immediately. Boot/connect re-enter the
+splash so a redirect (including after saving config) never flashes the form.
+*/
+let phase = $state<'splash' | 'connect'>(launchAction === 'start' ? 'splash' : 'connect')
+
+/*
+First-run config form, surfaced as a modal only when Start is clicked (or
+auto-start fires) with a required key still unset. Fields are derived from the
+app's config JSON Schema served by the launcher; answers post back to the
+data-dir `.env` the embedded server loads at boot.
+*/
+type ConfigField = {
+    key: string
+    label: string
+    description?: string
+    inputType: 'text' | 'password' | 'number' | 'checkbox'
+    required: boolean
+}
+let configFields = $state<ConfigField[]>([])
+let configValues = $state<Record<string, string>>({})
+let showConfig = $state(false)
+let savingConfig = $state(false)
+// Every required field has a value — gates the modal's Save button.
+const canSaveConfig = $derived(
+    configFields.every(
+        (field) =>
+            !field.required ||
+            field.inputType === 'checkbox' ||
+            (configValues[field.key] ?? '').trim() !== '',
+    ),
+)
+
 /*
 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
@@ -51,30 +82,19 @@ remembered server reconnects automatically:
   - (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') {
+    if (launchAction === 'start') {
+        // File-menu Start Server is an explicit click → run the Start flow.
         void start()
         return
     }
-    if (action === 'lost') {
+    if (launchAction === '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)
+    if (launchAction === 'disconnect') {
+        // Have the launcher forget the auto-resume choice and reap any embedded
+        // server; LAST_URL_KEY stays so the form is still prefilled to reconnect.
         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)
     }
 })
 
@@ -92,6 +112,8 @@ async function connect(target: string = url.trim()): Promise<void> {
         return
     }
     error = undefined
+    // Hide the form while connecting so a successful redirect doesn't flash it.
+    phase = 'splash'
     try {
         const response = await fetch('/connect', {
             method: 'POST',
@@ -103,21 +125,44 @@ async function connect(target: string = url.trim()): Promise<void> {
             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.
+        // Prefill the form with this server on a later visit (the launcher records
+        // the auto-resume choice itself, on the /connect it just handled).
         localStorage.setItem(LAST_URL_KEY, cleaned)
         location.href = redirect
     } catch (cause) {
         error = `Could not connect: ${String(cause)}`
+        // Failed — bring the form back so the error and a retry are visible.
+        phase = 'connect'
     }
 }
 
-// Boot the embedded server via the launcher, then follow it once it answers.
+/*
+Start, always an explicit click (button or File-menu) — auto-resume happens in
+the launcher before the window opens, so this is never a launch path. Asks the
+launcher what config the app needs: if it declares any, open the modal (prefilled
+with the last-used values) so the user can review or change settings before
+booting — re-running Start after a disconnect is how you reconfigure. With no
+config schema, boot straight through. The modal's save path resumes the boot.
+*/
 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)
+    const config = await loadConfig().catch(() => undefined)
+    if (config) {
+        configFields = config.fields
+        configValues = { ...config.values }
+        // Reveal the connect screen as the modal's backdrop.
+        phase = 'connect'
+        showConfig = true
+        return
+    }
+    await boot()
+}
+
+// Boot the embedded server via the launcher, then follow it once it answers.
+async function boot(): Promise<void> {
+    // Splash while booting so the connect screen doesn't flash before the redirect
+    // (including straight after saving config).
+    phase = 'splash'
     try {
         const response = await fetch('/start', { method: 'POST' })
         if (!response.ok) {
@@ -128,11 +173,92 @@ async function start(): Promise<void> {
         location.href = redirect
     } catch (cause) {
         error = `Could not start the server: ${String(cause)}`
-        starting = false
+        // Boot failed — bring the connect screen back to show the error.
+        phase = 'connect'
+    }
+}
+
+/*
+Fetches the app's config schema + resolved current values from the launcher and
+turns the JSON Schema into render-ready fields. Returns undefined when no schema
+is declared, so Start never gates.
+*/
+async function loadConfig(): Promise<
+    { fields: ConfigField[]; values: Record<string, string> } | undefined
+> {
+    const response = await fetch('/__belte/config')
+    const { schema, values } = (await response.json()) as {
+        schema: Record<string, unknown> | null
+        values: Record<string, string>
+    }
+    if (!schema) {
+        return undefined
+    }
+    return { fields: fieldsFromSchema(schema), values: values ?? {} }
+}
+
+// Derives one render-ready field per JSON Schema property, reusing the standard
+// slots: `title` → label, `description` → hint, `format`/`type` → input kind.
+function fieldsFromSchema(schema: Record<string, unknown>): ConfigField[] {
+    const properties = (schema.properties ?? {}) as Record<string, Record<string, unknown>>
+    const required = new Set((schema.required as string[]) ?? [])
+    return Object.entries(properties).map(([key, property]) => ({
+        key,
+        label: (property.title as string) ?? key,
+        description: property.description as string | undefined,
+        inputType: inputType(property),
+        required: required.has(key),
+    }))
+}
+
+// Maps a JSON Schema property to an HTML input kind (directory falls back to text
+// until a native picker exists).
+function inputType(property: Record<string, unknown>): ConfigField['inputType'] {
+    if (property.type === 'boolean') {
+        return 'checkbox'
+    }
+    if (property.type === 'number' || property.type === 'integer') {
+        return 'number'
+    }
+    if (property.format === 'password') {
+        return 'password'
+    }
+    return 'text'
+}
+
+// Persist the form's answers to the data-dir `.env`, then resume the boot.
+async function saveConfig(): Promise<void> {
+    error = undefined
+    savingConfig = true
+    try {
+        const response = await fetch('/__belte/config', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ values: configValues }),
+        })
+        if (!response.ok) {
+            throw new Error(`save failed (${response.status})`)
+        }
+        showConfig = false
+        savingConfig = false
+        await boot()
+    } catch (cause) {
+        error = `Could not save settings: ${String(cause)}`
+        savingConfig = false
     }
 }
 </script>
 
+{#if phase === 'splash'}
+    <!-- Neutral splash shown while an auto-start/auto-reconnect resolves, so the
+    connect screen never flashes before it redirects. Same background as the card. -->
+    <div
+        class="flex min-h-screen items-center justify-center bg-gray-50 dark:bg-gray-950">
+        {#if logo}
+            <img src={logo} alt="" class="h-16 w-16 rounded-xl object-contain opacity-90">
+        {/if}
+    </div>
+{:else}
 <main
     class="flex min-h-screen items-center justify-center bg-gray-50 p-6 text-gray-900 dark:bg-gray-950 dark:text-gray-100">
     <div
@@ -170,9 +296,8 @@ async function start(): Promise<void> {
         <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 dark:border-gray-700 dark:hover:bg-gray-800">
-            {starting ? 'Starting…' : 'Start server'}
+            class="w-full rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium hover:bg-gray-50 dark:border-gray-700 dark:hover:bg-gray-800">
+            Start server
         </button>
 
         {#if error}
@@ -189,3 +314,74 @@ async function start(): Promise<void> {
         </p>
     </div>
 </main>
+{/if}
+
+{#if showConfig}
+    <!-- First-run config modal — shown only when Start needs settings the app lacks. -->
+    <div
+        class="fixed inset-0 z-10 flex items-center justify-center bg-black/40 p-6 text-gray-900 dark:text-gray-100">
+        <div
+            class="w-full max-w-sm rounded-2xl bg-white p-8 shadow-lg ring-1 ring-gray-200 dark:bg-gray-900 dark:ring-gray-800">
+            <h2 class="mb-5 text-lg font-semibold tracking-tight">Set up {heading}</h2>
+
+            <form
+                class="flex flex-col gap-4"
+                onsubmit={(event) => {
+                    event.preventDefault()
+                    void saveConfig()
+                }}>
+                {#each configFields as field (field.key)}
+                    <label class="flex flex-col gap-1 text-sm">
+                        <span class="font-medium">
+                            {field.label}
+                            {#if field.required}
+                                <span class="text-red-500">*</span>
+                            {/if}
+                        </span>
+                        {#if field.inputType === 'checkbox'}
+                            <input
+                                type="checkbox"
+                                checked={configValues[field.key] === 'true'}
+                                onchange={(event) =>
+                                    (configValues[field.key] = event.currentTarget.checked
+                                        ? 'true'
+                                        : 'false')}
+                                class="mt-1 size-4 self-start rounded border-gray-300 dark:border-gray-700">
+                        {:else}
+                            <input
+                                type={field.inputType}
+                                value={configValues[field.key] ?? ''}
+                                oninput={(event) =>
+                                    (configValues[field.key] = event.currentTarget.value)}
+                                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 dark:border-gray-700 dark:bg-gray-800 dark:focus:border-gray-100 dark:focus:ring-gray-100">
+                        {/if}
+                        {#if field.description}
+                            <span class="text-xs text-gray-400 dark:text-gray-500">
+                                {field.description}
+                            </span>
+                        {/if}
+                    </label>
+                {/each}
+
+                <div class="mt-1 flex gap-3">
+                    <button
+                        type="button"
+                        onclick={() => (showConfig = false)}
+                        class="flex-1 rounded-lg border border-gray-300 px-3 py-2 text-sm font-medium hover:bg-gray-50 dark:border-gray-700 dark:hover:bg-gray-800">
+                        Cancel
+                    </button>
+                    <button
+                        type="submit"
+                        disabled={!canSaveConfig || savingConfig}
+                        class="flex-1 rounded-lg bg-gray-900 px-3 py-2 text-sm font-medium text-white hover:bg-gray-700 disabled:opacity-60 dark:bg-gray-100 dark:text-gray-900 dark:hover:bg-gray-300">
+                        {savingConfig ? 'Saving…' : 'Save & start'}
+                    </button>
+                </div>
+            </form>
+
+            {#if error}
+                <p class="mt-4 text-center text-sm text-red-600 dark:text-red-400">{error}</p>
+            {/if}
+        </div>
+    </div>
+{/if}

package/src/lib/bundle/onMenu.ts

@@ -1,25 +1,40 @@
 /*
 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;
-this registers `handler`, called with the item's `emit` name. Returns an
-unsubscribe function, so it drops straight into a Svelte `$effect`:
+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(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) {
-        handler((event as CustomEvent<{ name: string }>).detail.name)
+        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

@@ -62,8 +62,15 @@ export async function openWebview({
         webview_destroy: { args: [FFIType.ptr], returns: FFIType.void },
     })
 
-    // The second arg is an optional parent window handle; null means a fresh window.
-    const handle = symbols.webview_create(0, null)
+    /*
+    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)
     /*

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/cli/createClient.ts

@@ -5,7 +5,21 @@ import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
 import { decodeResponse } from '../shared/decodeResponse.ts'
 import type { CliManifest } from './types/CliManifest.ts'
 
-type AnyApi = Record<string, (args?: unknown) => Promise<unknown>>
+/*
+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.
+*/
+type ClientInvoker = ((args?: unknown) => Promise<unknown>) & {
+    raw: (args?: unknown) => Promise<Response>
+}
+
+type AnyApi = Record<string, ClientInvoker>
+
+// A command resolved to its HTTP shape — the manifest/registry lookup result.
+type ResolvedCommand = { method: HttpVerb; url: string; accept?: string }
 
 /*
 Builds a typed proxy over the project's RPCs for use in scripts, tests,
@@ -42,35 +56,56 @@ export function createClient<Api extends AnyApi = AnyApi>(opts?: {
     baked-in source of truth); registry is the in-process fallback for
     use in same-project code where defineVerb has run.
     */
-    function resolve(name: string): { method: HttpVerb; url: string } | undefined {
+    function resolve(name: string): ResolvedCommand | undefined {
         const entry = manifest?.[name]
         if (entry) {
-            return { method: entry.method, url: entry.url }
+            return { method: entry.method, url: entry.url, accept: entry.accept }
         }
         const found = findVerbByCommandName(name)
         return found ? { method: found.remote.method, url: found.remote.url } : undefined
     }
 
     /*
-    Single call path for both modes — only the base URL and how the Request
-    is dispatched differ. Remote mode fetches over the network; in-process
-    mode looks the verb up in the registry and runs verb.fetch (no hop).
+    Single dispatch path for both modes — only the base URL and how the
+    Request is sent differ. Remote mode fetches over the network;
+    in-process mode looks the verb up in the registry and runs verb.fetch
+    (no hop). Returns the raw Response; callers decode or stream it.
     */
-    async function call(
-        method: HttpVerb,
-        path: string,
+    function send(
+        resolved: ResolvedCommand,
         args: unknown,
         baseUrl: string,
         dispatch: (request: Request) => Promise<Response>,
-    ): Promise<unknown> {
+    ): Promise<Response> {
         const headers = new Headers()
         if (token) {
             headers.set('authorization', `Bearer ${token}`)
         }
-        const request = buildRpcRequest({ method, url: path, args, baseUrl, headers })
-        const response = await dispatch(request)
+        if (resolved.accept) {
+            headers.set('accept', resolved.accept)
+        }
+        const request = buildRpcRequest({
+            method: resolved.method,
+            url: resolved.url,
+            args,
+            baseUrl,
+            headers,
+        })
+        return dispatch(request)
+    }
+
+    // Decoding plain-call path: throws on non-2xx, returns the decoded body.
+    async function call(
+        resolved: ResolvedCommand,
+        args: unknown,
+        baseUrl: string,
+        dispatch: (request: Request) => Promise<Response>,
+    ): Promise<unknown> {
+        const response = await send(resolved, args, baseUrl, dispatch)
         if (!response.ok) {
-            throw new Error(`${method} ${path} failed: ${response.status} ${response.statusText}`)
+            throw new Error(
+                `${resolved.method} ${resolved.url} failed: ${response.status} ${response.statusText}`,
+            )
         }
         return decodeResponse(response)
     }
@@ -94,10 +129,24 @@ export function createClient<Api extends AnyApi = AnyApi>(opts?: {
     manifest + registry are fixed for a client's lifetime, so a resolved
     invoker (or its absence) never changes.
     */
-    const invokerCache = new Map<string, ((args?: unknown) => Promise<unknown>) | undefined>()
+    const invokerCache = new Map<string, ClientInvoker | undefined>()
+
+    /*
+    Build a memoised invoker for a resolved command. The plain call and
+    `.raw` share one dispatch — remote mode hits the network, in-process
+    mode runs verb.fetch — so the two can't diverge on URL/headers.
+    */
+    function buildInvoker(resolved: ResolvedCommand): ClientInvoker {
+        const baseUrl = url ?? 'http://localhost/'
+        const dispatch = url ? fetch : inProcessDispatch(resolved.url)
+        const invoker = ((args?: unknown) =>
+            call(resolved, args, baseUrl, dispatch)) as ClientInvoker
+        invoker.raw = (args?: unknown) => send(resolved, args, baseUrl, dispatch)
+        return invoker
+    }
 
     return new Proxy({} as Api, {
-        get(_target, prop): ((args?: unknown) => Promise<unknown>) | undefined {
+        get(_target, prop): ClientInvoker | undefined {
             if (typeof prop !== 'string') {
                 return undefined
             }
@@ -105,18 +154,7 @@ export function createClient<Api extends AnyApi = AnyApi>(opts?: {
                 return invokerCache.get(prop)
             }
             const resolved = resolve(prop)
-            const invoker = resolved
-                ? (args?: unknown) =>
-                      url
-                          ? call(resolved.method, resolved.url, args, url, fetch)
-                          : call(
-                                resolved.method,
-                                resolved.url,
-                                args,
-                                'http://localhost/',
-                                inProcessDispatch(resolved.url),
-                            )
-                : undefined
+            const invoker = resolved ? buildInvoker(resolved) : undefined
             invokerCache.set(prop, invoker)
             return invoker
         },