@briancray/belte 0.2.2 → 0.3.0

package/package.json

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

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.