@briancray/belte 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.2.1",
+    "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/belteResolverPlugin.ts

@@ -112,6 +112,13 @@ export function belteResolverPlugin({
     const promptsDir = `${mcpDir}/prompts`
     const resourcesDir = `${mcpDir}/resources`
 
+    /*
+    The bare specifier the project imports belte under (canonical
+    `@briancray/belte` or a package alias). Resolved once from the project's
+    package.json and threaded into every generated module so the codegen's
+    imports resolve regardless of which install style the project uses.
+    */
+    const belteImportNameOnce = once(() => belteImportName(cwd))
     /*
     The whole-tree validation + per-leaf classification only needs to run
     once per build. Memoise the promise so the virtual manifests
@@ -121,7 +128,11 @@ export function belteResolverPlugin({
     */
     const scanPagesOnce = once(() =>
         scanPages(pagesDir).then(async (scan) => {
-            await writeRoutesDts({ cwd, pageFiles: scan.pageFiles })
+            await writeRoutesDts({
+                cwd,
+                pageFiles: scan.pageFiles,
+                importName: await belteImportNameOnce(),
+            })
             return scan
         }),
     )
@@ -129,13 +140,6 @@ export function belteResolverPlugin({
     const scanSocketsOnce = once(() => scanSockets(socketsDir))
     const scanPromptsOnce = once(() => scanPrompts(promptsDir))
     const loadShellOnce = once(() => loadShell(cwd))
-    /*
-    The bare specifier the project imports belte under (canonical
-    `@briancray/belte` or a package alias). Resolved once from the project's
-    package.json and threaded into every generated module so the codegen's
-    imports resolve regardless of which install style the project uses.
-    */
-    const belteImportNameOnce = once(() => belteImportName(cwd))
 
     const rpcFilter = new RegExp(`^${escapeRegex(rpcDir)}/.*\\.ts$`)
     const socketsFilter = new RegExp(`^${escapeRegex(socketsDir)}/.*\\.ts$`)

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.

package/src/lib/shared/writeRoutesDts.ts

@@ -30,14 +30,19 @@ page file in the project. Page picks this up as a discriminated union keyed
 on `route`, so `if (page.route === '/media/[id]') page.params.id` is typed
 automatically without consumers writing route types by hand.
 The file is written to `src/.belte/routes.d.ts` so the consumer's existing
-src tsconfig include picks it up with no extra configuration.
+src tsconfig include picks it up with no extra configuration. The augmented
+module is keyed on the name the project imports belte under (`importName`),
+so the augmentation matches the consumer's `page` import whether belte is
+installed directly (`@briancray/belte`) or behind an alias.
 */
 export async function writeRoutesDts({
     cwd,
     pageFiles,
+    importName,
 }: {
     cwd: string
     pageFiles: string[]
+    importName: string
 }): Promise<void> {
     const entries = pageFiles
         .map((file) => ({
@@ -50,7 +55,7 @@ export async function writeRoutesDts({
         )
         .join('\n')
     const contents = `// Generated by belte. Do not edit by hand.
-declare module 'belte/browser/page' {
+declare module '${importName}/browser/page' {
     interface Routes {
 ${entries}
     }

package/template/package.json

@@ -11,7 +11,7 @@
         "bundle": "belte bundle"
     },
     "dependencies": {
-        "belte": "npm:@briancray/belte@^0.2.0",
+        "@briancray/belte": "^0.2.0",
         "svelte": "^5.0.0"
     }
 }

package/template/src/app.ts

@@ -7,7 +7,7 @@ module — no import is needed from your own code.
   handle      middleware wrapping the default request pipeline
   handleError custom 500 fallback
 */
-import type { AppModule } from 'belte/server/AppModule'
+import type { AppModule } from '@briancray/belte/server/AppModule'
 
 export const init: AppModule['init'] = ({ server }) => {
     console.log(`server listening on http://localhost:${server.port}`)

package/template/src/browser/pages/page.svelte

@@ -3,7 +3,7 @@ Root page — served at GET /. Every folder under src/browser/pages/ that
 contains a page.svelte mounts at that folder's URL.
 -->
 <script lang="ts">
-import { cache } from 'belte/browser/cache'
+import { cache } from '@briancray/belte/browser/cache'
 import { getHello } from '$server/rpc/getHello.ts'
 
 /*

package/template/src/server/rpc/getHello.ts

@@ -27,7 +27,7 @@ Every rpc value also exposes `.raw(args?)` (returns the underlying
 for callers that need headers/status or want to iterate SSE/JSONL frames.
 */
 
-import { GET } from 'belte/server/GET'
-import { json } from 'belte/server/json'
+import { GET } from '@briancray/belte/server/GET'
+import { json } from '@briancray/belte/server/json'
 
 export const getHello = GET(() => json({ message: 'Hello from belte' }))

package/template/svelte.config.js

@@ -3,7 +3,7 @@ Optional Svelte compiler configuration. Same shape as upstream Svelte.
 Delete this file to use defaults.
 */
 
-/** @type {import('belte').SvelteConfig} */
+/** @type {import('@briancray/belte').SvelteConfig} */
 export default {
     compilerOptions: {
         // Opt in to top-level await inside Svelte components.

package/template/tsconfig.json

@@ -1,5 +1,5 @@
 {
-    "extends": "belte/tsconfig",
+    "extends": "@briancray/belte/tsconfig",
     "include": ["src/**/*.ts", "src/**/*.svelte"],
     "compilerOptions": {
         "paths": {