@briancray/belte 0.2.2 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.2.2",
+    "version": "0.3.1",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/lib/bundle/disconnected.svelte

@@ -29,8 +29,7 @@ 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 heading = (globalThis as { __BELTE_TITLE__?: string }).__BELTE_TITLE__ ?? 'belte app'
 const logo = (globalThis as { __BELTE_LOGO__?: string }).__BELTE_LOGO__
 
 const placeholder = 'https://example.com'
@@ -134,10 +133,12 @@ async function start(): Promise<void> {
 }
 </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">
+<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
+        class="w-full max-w-sm rounded-2xl bg-white p-8 shadow-sm ring-1 ring-gray-200 dark:bg-gray-900 dark:ring-gray-800">
         {#if logo}
-            <img src={logo} alt="" class="mx-auto mb-5 h-16 w-16 rounded-xl object-contain" />
+            <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>
 
@@ -146,45 +147,43 @@ async function start(): Promise<void> {
             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"
-            />
+                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">
             <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"
-            >
+                class="w-full rounded-lg bg-gray-900 px-3 py-2 text-sm font-medium text-white hover:bg-gray-700 dark:bg-gray-100 dark:text-gray-900 dark:hover:bg-gray-300">
                 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>
+        <div class="my-5 flex items-center gap-3 text-xs text-gray-400 dark:text-gray-500">
+            <span class="h-px flex-1 bg-gray-200 dark:bg-gray-800"></span>
             or
-            <span class="h-px flex-1 bg-gray-200"></span>
+            <span class="h-px flex-1 bg-gray-200 dark:bg-gray-800"></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"
-        >
+            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'}
         </button>
 
         {#if error}
-            <p class="mt-4 text-center text-sm text-red-600">{error}</p>
+            <p class="mt-4 text-center text-sm text-red-600 dark:text-red-400">{error}</p>
         {/if}
 
-        <p class="mt-8 text-center text-xs text-gray-400">
+        <p class="mt-8 text-center text-xs text-gray-400 dark:text-gray-500">
             made with
-            <a href="https://github.com/briancray/belte" class="underline hover:text-gray-600">
+            <a
+                href="https://github.com/briancray/belte"
+                class="underline hover:text-gray-600 dark:hover:text-gray-300">
                 belte
             </a>
         </p>

package/src/lib/bundle/installDownloads.ts

@@ -0,0 +1,24 @@
+import { dlopen, FFIType, type Pointer } from 'bun:ffi'
+
+/*
+Wires belte's native download delegate onto the bundle's WKWebView, so `<a
+download>` clicks, blob:/data: links, and attachment responses save a real file
+into the user's Downloads folder and reveal it in Finder — the bare upstream
+webview sets no navigation delegate and silently drops all of these.
+
+A no-op off macOS (the shim symbol isn't compiled into the library there) and on
+macOS before 11.3 (no WKDownload API). Opened as its own short-lived handle,
+mirroring installMacMenu, to keep openWebview's FFI map fully typed — a
+conditional symbol there defeats Bun's argument-type inference. The delegate
+attaches to the live WKWebView, so it persists after this handle closes.
+*/
+export function installDownloads(libPath: string, webviewHandle: Pointer | null): void {
+    if (process.platform !== 'darwin') {
+        return
+    }
+    const { symbols, close } = dlopen(libPath, {
+        belte_install_downloads: { args: [FFIType.ptr], returns: FFIType.void },
+    })
+    symbols.belte_install_downloads(webviewHandle)
+    close()
+}

package/src/lib/bundle/native/belteMenu.mm

@@ -6,6 +6,8 @@
 // the built-in File menu (Start / Disconnect), and the bundle's custom menus
 // whose items emit events into the page.
 #import <Cocoa/Cocoa.h>
+#import <WebKit/WebKit.h>
+#import <objc/runtime.h>
 #include <cstdlib>
 #include <cstring>
 
@@ -15,6 +17,9 @@ extern "C" int webview_eval(void *w, const char *js);
 // Marshals a callback onto the UI thread; the only safe way to touch the window
 // from another thread (the launcher runs its control server off the main thread).
 extern "C" int webview_dispatch(void *w, void (*fn)(void *w, void *arg), void *arg);
+// Returns a backend-native handle for the webview; with kind
+// WEBVIEW_NATIVE_HANDLE_KIND_BROWSER_CONTROLLER (2) that's the WKWebView.
+extern "C" void *webview_get_native_handle(void *w, int kind);
 
 // Exported despite -fvisibility=hidden so belte's FFI layer can resolve it.
 #define BELTE_EXPORT __attribute__((visibility("default")))
@@ -296,3 +301,122 @@ extern "C" BELTE_EXPORT void belte_install_app_menu(void *webview_handle,
         [app setMainMenu:mainMenu];
     }
 }
+
+// WEBVIEW_NATIVE_HANDLE_KIND_BROWSER_CONTROLLER — the WKWebView pointer.
+static const int kBelteBrowserController = 2;
+
+// Associated-object key under which each WKDownload stashes its chosen
+// destination URL, so downloadDidFinish: can reveal the saved file in Finder.
+static const char kBelteDownloadDestKey = 0;
+
+/*
+Navigation + download delegate for the bundle's WKWebView. The upstream webview
+sets no navigation delegate, so WKWebView silently drops `<a download>` clicks,
+blob:/data: downloads, and attachment responses — leaving every belte bundle app
+unable to save a file. This routes those to a real download saved into the user's
+Downloads folder and reveals it in Finder, while passing every ordinary
+navigation straight through (the app's own page loads must not be hijacked).
+A process-lifetime singleton, never released (MRC), matching the menu objects
+above; WKWebView holds its navigationDelegate weakly, so the strong global is
+what keeps it alive.
+*/
+API_AVAILABLE(macos(11.3))
+@interface BelteDownloadDelegate : NSObject <WKNavigationDelegate, WKDownloadDelegate>
+@end
+
+@implementation BelteDownloadDelegate
+
+// A link with a `download` attribute (e.g. URL.createObjectURL + a.download)
+// sets shouldPerformDownload; turn only those into downloads and allow the rest
+// — notably the app's own navigations, which must load normally.
+- (void)webView:(WKWebView *)webView
+    decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
+                    decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
+    if (navigationAction.shouldPerformDownload) {
+        decisionHandler(WKNavigationActionPolicyDownload);
+    } else {
+        decisionHandler(WKNavigationActionPolicyAllow);
+    }
+}
+
+// A response the webview can't render (or that the server marks as an
+// attachment) becomes a download too, mirroring how a browser behaves.
+- (void)webView:(WKWebView *)webView
+    decidePolicyForNavigationResponse:(WKNavigationResponse *)navigationResponse
+                      decisionHandler:(void (^)(WKNavigationResponsePolicy))decisionHandler {
+    if (navigationResponse.canShowMIMEType) {
+        decisionHandler(WKNavigationResponsePolicyAllow);
+    } else {
+        decisionHandler(WKNavigationResponsePolicyDownload);
+    }
+}
+
+- (void)webView:(WKWebView *)webView
+     navigationAction:(WKNavigationAction *)navigationAction
+    didBecomeDownload:(WKDownload *)download {
+    download.delegate = self;
+}
+
+- (void)webView:(WKWebView *)webView
+    navigationResponse:(WKNavigationResponse *)navigationResponse
+     didBecomeDownload:(WKDownload *)download {
+    download.delegate = self;
+}
+
+// Save under ~/Downloads using the browser-suggested name, de-duplicating with a
+// " (n)" suffix so a repeat export never silently clobbers the previous file.
+- (void)download:(WKDownload *)download
+    decideDestinationUsingResponse:(NSURLResponse *)response
+                 suggestedFilename:(NSString *)suggestedFilename
+                 completionHandler:(void (^)(NSURL *))completionHandler {
+    NSFileManager *fm = [NSFileManager defaultManager];
+    NSURL *dir =
+        [[fm URLsForDirectory:NSDownloadsDirectory inDomains:NSUserDomainMask] firstObject];
+    if (dir == nil) {
+        dir = [NSURL fileURLWithPath:NSHomeDirectory()];
+    }
+    NSString *name = suggestedFilename.length ? suggestedFilename : @"download";
+    NSURL *dest = [dir URLByAppendingPathComponent:name];
+    NSString *base = [name stringByDeletingPathExtension];
+    NSString *ext = [name pathExtension];
+    for (int i = 1; [fm fileExistsAtPath:dest.path]; i++) {
+        NSString *candidate =
+            ext.length ? [NSString stringWithFormat:@"%@ (%d).%@", base, i, ext]
+                       : [NSString stringWithFormat:@"%@ (%d)", base, i];
+        dest = [dir URLByAppendingPathComponent:candidate];
+    }
+    objc_setAssociatedObject(download, &kBelteDownloadDestKey, dest,
+                             OBJC_ASSOCIATION_RETAIN_NONATOMIC);
+    completionHandler(dest);
+}
+
+- (void)downloadDidFinish:(WKDownload *)download {
+    NSURL *dest = objc_getAssociatedObject(download, &kBelteDownloadDestKey);
+    if (dest != nil) {
+        [[NSWorkspace sharedWorkspace] activateFileViewerSelectingURLs:@[ dest ]];
+    }
+}
+
+@end
+
+/*
+Attaches the download delegate to the bundle's WKWebView. Safe to call after
+webview_create and must run before the first navigation. A no-op on macOS
+versions before 11.3 (no WKDownload API) — there downloads stay unsupported, as
+they were. The delegate is a strong process-lifetime singleton because WKWebView
+holds its navigationDelegate weakly.
+*/
+extern "C" BELTE_EXPORT void belte_install_downloads(void *webview_handle) {
+    if (@available(macOS 11.3, *)) {
+        WKWebView *webView =
+            (WKWebView *)webview_get_native_handle(webview_handle, kBelteBrowserController);
+        if (webView == nil) {
+            return;
+        }
+        static BelteDownloadDelegate *delegate = nil;
+        if (delegate == nil) {
+            delegate = [[BelteDownloadDelegate alloc] init];
+        }
+        webView.navigationDelegate = delegate;
+    }
+}

package/src/lib/bundle/openWebview.ts

@@ -1,5 +1,6 @@
 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'
 
@@ -71,6 +72,12 @@ export async function openWebview({
     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)
 
     symbols.webview_navigate(handle, cString(url))

package/src/lib/bundle/webviewBuildRevision.ts

@@ -6,4 +6,4 @@ cache key alongside the upstream version, so changing belte's native build
 selects a fresh cache path and bypasses any library built before the change.
 Bump this whenever the shim sources or their compile invocation change.
 */
-export const webviewBuildRevision = 8
+export const webviewBuildRevision = 9

package/src/lib/server/prompts/renderPromptTemplate.ts

@@ -6,7 +6,7 @@ const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g
 Renders a markdown prompt body by substituting each `{{name}}` placeholder
 with the matching argument value. Missing arguments collapse to an empty
 string — MCP only enforces `required` at the client, so an optional
-argument the model omits should simply vanish from the text. Called by the
+argument the model omits should vanish from the text. Called by the
 render closure the resolver plugin generates for every `.md` prompt.
 */
 export function renderPromptTemplate(template: string, args: Record<string, string>): string {

package/src/lib/server/rpc/types/RemoteHandler.ts

@@ -15,7 +15,7 @@ carries the body shape through the function's inferred return type so the
 verb helper can infer `Return` automatically — no need to annotate
 `GET<Args, Return>` when the handler returns one of the respond helpers.
 A bare `new Response(...)` is still acceptable: the brand is optional, so
-untagged Responses simply fall back to `Return = unknown`.
+untagged Responses fall back to `Return = unknown`.
 
 Handlers that need the inbound Request (headers, `request.signal`, …) read
 it via `request()` from `belte/server` rather than a handler parameter, so

package/src/lib/shared/belteImportName.ts

@@ -7,7 +7,7 @@ belte directly (`@briancray/belte`) or behind a package alias
 (`"belte": "npm:@briancray/belte@..."`, or `workspace:@briancray/belte@*`
 inside this repo). An alias-only install resolves only under the alias key and
 a direct install only under the canonical name, so the generated rpc / socket
-/ prompt modules must import under whichever name the project actually
+/ prompt modules must import under whichever name the project
 declared.
 
 Prefers a `belte` alias (the ergonomic surface the docs use) when present, then

package/src/lib/shared/subscribableFromResponse.ts

@@ -176,7 +176,7 @@ async function* parseJsonLines<T>(response: Response): AsyncGenerator<T> {
 Builds the Subscribable returned by `fn.stream(args)`. The carried
 `name` is the cache-style key for (method, url, args) so subscribe()
 dedupes multiple subscribers to identical args into one underlying
-fetch. The fetch is deferred until the first iterator pull so simply
+fetch. The fetch is deferred until the first iterator pull so
 constructing the Subscribable (which happens on every $derived
 re-evaluation) doesn't open a connection — subscribe()'s registry
 short-circuits the second instance before it iterates.