@ashley-shrok/viewmodel-shell 0.4.9 → 0.5.0

package/README.md

@@ -33,6 +33,22 @@ If your backend is .NET: copy `demo/Tasks/AspNetCore/ViewModels.cs` from the [Gi
 
 For other backends, implement the same JSON shape: a `GET` returning `{ vm, state }`, and a `POST` that takes `multipart/form-data` with `_action` and `_state` form fields and returns the next `{ vm, state }`. See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for the full wire format.
 
+## Authenticated downloads
+
+When a header-authenticated consumer (e.g. `Authorization: Bearer <jwt>` via `ShellOptions.getRequestHeaders()`) needs to offer a file download, return a `"download"` side-effect from your action handler — the shell fetches the URL with the same headers merged in, parses `Content-Disposition` + `Content-Type`, and triggers a browser "Save As":
+
+```csharp
+return new ShellResponse<MyState>(BuildVm(state), state)
+    .WithEffect(ShellSideEffect.Download("/api/invoices/42/pdf", "invoice-42.pdf"));
+```
+
+```typescript
+return { vm: buildVm(state), state,
+  sideEffects: [shellSideEffect.download("/api/invoices/42/pdf", "invoice-42.pdf")] };
+```
+
+The download endpoint stays auth-gated and the server authorizes in the action handler — no signed-URL machinery. See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md#client-side-effects) for the wire format and pattern.
+
 ## Terminal (TUI)
 
 The same backend renders in a terminal — same wire, no backend change. Point the CLI at any ViewModel Shell endpoint:

package/dist/browser.d.ts

@@ -6,6 +6,10 @@ export declare class BrowserAdapter implements Adapter {
     render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
     navigate(url: string): void;
     storage(scope: "local" | "session", key: string, value: string): void;
+    /** Save an authenticated-download blob via the browser's native Save-As.
+     *  contentType is informational — the Blob's own .type takes precedence in
+     *  browsers. We accept the arg for adapter symmetry (other adapters use it). */
+    saveFile(data: Blob, filename: string, _contentType: string): void;
     transport(input: string, init: {
         method?: string;
         headers?: Record<string, string>;

package/dist/browser.js

@@ -68,6 +68,26 @@ export class BrowserAdapter {
         const store = scope === "session" ? sessionStorage : localStorage;
         store.setItem(key, value);
     }
+    /** Save an authenticated-download blob via the browser's native Save-As.
+     *  contentType is informational — the Blob's own .type takes precedence in
+     *  browsers. We accept the arg for adapter symmetry (other adapters use it). */
+    saveFile(data, filename, _contentType) {
+        const url = URL.createObjectURL(data);
+        try {
+            const a = document.createElement("a");
+            a.href = url;
+            a.download = filename;
+            a.style.display = "none";
+            document.body.appendChild(a);
+            a.click();
+            a.remove();
+        }
+        finally {
+            // Revoke async so the browser has time to start the download. The 0ms
+            // setTimeout is the established pattern (Chromium/Firefox/Safari).
+            setTimeout(() => URL.revokeObjectURL(url), 0);
+        }
+    }
     async transport(input, init, hooks) {
         const onUploadProgress = hooks?.onUploadProgress;
         if (!onUploadProgress) {

package/dist/index.d.ts

@@ -23,6 +23,15 @@ export interface Adapter {
     }, hooks?: {
         onUploadProgress?: (sent: number, total: number) => void;
     }): Promise<Response>;
+    /** Save an authenticated-download blob to platform-appropriate storage. The
+     *  shell fetches the URL with getRequestHeaders() merged, parses
+     *  Content-Disposition filename + Content-Type, and calls saveFile().
+     *  No safe no-op exists — a silently-dropped authenticated download is a
+     *  correctness/security bug (cf. navigate/storage). If a "download"
+     *  side-effect arrives and this method is absent, the shell fails loudly.
+     *  May return void or Promise<void>; the shell awaits the return value so
+     *  async I/O errors surface via onError. */
+    saveFile?(data: Blob, filename: string, contentType: string): void | Promise<void>;
 }
 export type ViewNode = PageNode | SectionNode | ListNode | ListItemNode | FormNode | FieldNode | CheckboxNode | ButtonNode | TextNode | LinkNode | StatBarNode | TabsNode | ProgressNode | ModalNode | TableNode | CopyButtonNode;
 export interface PageNode {
@@ -199,10 +208,17 @@ export interface ShellOptions {
     pollInterval?: number;
 }
 export interface ShellSideEffect {
-    /** "set-local-storage" | "set-session-storage" — unknown types are silently ignored. */
+    /** "set-local-storage" | "set-session-storage" | "download" — unknown types are silently ignored. */
     type: string;
+    /** For "set-local-storage" / "set-session-storage": the storage key. */
     key?: string;
+    /** For "set-local-storage" / "set-session-storage": the storage value. */
     value?: string;
+    /** For "download": the URL to fetch (shell merges getRequestHeaders() into the request). */
+    url?: string;
+    /** For "download": optional filename hint. Response Content-Disposition wins
+     *  when present; this is the fallback before the URL basename. */
+    filename?: string;
 }
 export interface ShellResponse {
     vm: ViewNode;
@@ -231,4 +247,18 @@ export declare class ViewModelShell {
     private failCapability;
     private processResponse;
     private schedulePoll;
+    /**
+     * Authenticated download: fetch the URL with getRequestHeaders() merged
+     * (Bearer / anti-forgery / etc.), parse the response filename + content
+     * type, and hand the bytes to the adapter's platform-specific save verb.
+     *
+     * Deliberately uses core `fetch`, NOT adapter.transport. The existing
+     * transport override (XHR for upload-progress) constructs Response from
+     * xhr.responseText (a string) and would corrupt binary blobs. Download
+     * progress is a future, opt-in extension on its own seam.
+     *
+     * Errors (missing capability / non-OK status / adapter throw) surface
+     * via onError; the download() call itself never throws into the caller.
+     */
+    private download;
 }

package/dist/index.js

@@ -101,9 +101,10 @@ export class ViewModelShell {
     failCapability(capability, detail) {
         const err = new Error(`[ViewModelShell] Adapter is missing the "${capability}" capability but the ` +
             `server response requires it (${detail}). This is a hard failure, not a no-op: ` +
-            `a silently-dropped ${capability} (e.g. an auth token never persisted, or a ` +
-            `redirect that never happens) is a correctness/security bug. Implement ` +
-            `${capability}() on your Adapter, or (for redirect) pass ShellOptions.onRedirect.`);
+            `a silently-dropped ${capability} (e.g. an auth token never persisted, a ` +
+            `redirect that never happens, or an authenticated download silently swallowed) ` +
+            `is a correctness/security bug. Implement ${capability}() on your Adapter, ` +
+            `or (for redirect) pass ShellOptions.onRedirect.`);
         this.options.onError ? this.options.onError(err) : console.error("[ViewModelShell]", err);
     }
     processResponse(body) {
@@ -121,6 +122,12 @@ export class ViewModelShell {
                 else
                     this.failCapability("storage", `side-effect "${effect.type}" key="${effect.key}"`);
             }
+            else if (effect.type === "download" && effect.url != null) {
+                // Fire-and-forget. Surfaces errors via onError. Does not block the
+                // render/redirect branch below — downloads are a side channel, like
+                // storage, and a slow download MUST NOT delay the user-visible update.
+                void this.download(effect.url, effect.filename);
+            }
         }
         if (body.redirect) {
             if (this.options.onRedirect) {
@@ -150,4 +157,93 @@ export class ViewModelShell {
             this.dispatch({ name: "poll" }, true);
         }, delay);
     }
+    /**
+     * Authenticated download: fetch the URL with getRequestHeaders() merged
+     * (Bearer / anti-forgery / etc.), parse the response filename + content
+     * type, and hand the bytes to the adapter's platform-specific save verb.
+     *
+     * Deliberately uses core `fetch`, NOT adapter.transport. The existing
+     * transport override (XHR for upload-progress) constructs Response from
+     * xhr.responseText (a string) and would corrupt binary blobs. Download
+     * progress is a future, opt-in extension on its own seam.
+     *
+     * Errors (missing capability / non-OK status / adapter throw) surface
+     * via onError; the download() call itself never throws into the caller.
+     */
+    async download(url, hintFilename) {
+        const adapter = this.options.adapter;
+        if (!adapter.saveFile) {
+            this.failCapability("saveFile", `download from "${url}"`);
+            return;
+        }
+        try {
+            const extraHeaders = this.options.getRequestHeaders
+                ? await this.options.getRequestHeaders()
+                : {};
+            const res = await fetch(url, { headers: extraHeaders });
+            if (!res.ok) {
+                throw new Error(`Download from ${url} failed: ${res.status} ${res.statusText}`);
+            }
+            const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+            const filename = parseContentDispositionFilename(res.headers.get("Content-Disposition")) ??
+                hintFilename ??
+                basenameFromUrl(url) ??
+                "download";
+            const blob = await res.blob();
+            await adapter.saveFile(blob, filename, contentType);
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.options.onError ? this.options.onError(error) : console.error("[ViewModelShell]", error);
+        }
+    }
+}
+// ─── Download helpers (file-private; no platform globals) ────────────────────
+// `Blob` and `URL` are universals (browser, Node 18+, Deno, Bun) — confirmed
+// off the check:core-globals denylist. `URL.createObjectURL` is browser-only
+// and stays in BrowserAdapter behind the capability seam.
+/**
+ * Parse a `Content-Disposition` header for a filename. RFC 5987 `filename*`
+ * (UTF-8, percent-encoded, internationalized) wins over the plain `filename`
+ * parameter when both are present — that's the spec-canonical preference.
+ * Returns null when the header is absent or no filename parameter is found.
+ */
+function parseContentDispositionFilename(header) {
+    if (header == null)
+        return null;
+    // RFC 5987 extended form: filename*=UTF-8''<percent-encoded>
+    const ext = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(header);
+    if (ext) {
+        try {
+            const decoded = decodeURIComponent(ext[2].trim());
+            if (decoded.length > 0)
+                return decoded;
+        }
+        catch {
+            // Malformed percent-encoding — fall through to plain `filename`.
+        }
+    }
+    // Plain form: filename="..." or filename=...
+    const plain = /filename\s*=\s*"([^"]*)"|filename\s*=\s*([^;]+)/i.exec(header);
+    if (plain) {
+        const val = (plain[1] ?? plain[2] ?? "").trim();
+        if (val.length > 0)
+            return val;
+    }
+    return null;
+}
+/**
+ * Extract a basename from a URL (relative or absolute). Returns null if the
+ * path is empty or ends with `/`. Uses a dummy base so relative URLs parse;
+ * the base is discarded.
+ */
+function basenameFromUrl(url) {
+    try {
+        const u = new URL(url, "http://_/");
+        const last = u.pathname.split("/").pop();
+        return last && last.length > 0 ? decodeURIComponent(last) : null;
+    }
+    catch {
+        return null;
+    }
 }

package/dist/server.d.ts

@@ -25,6 +25,13 @@ export declare function shellRedirect<TState = unknown>(url: string): ShellRespo
 export declare const shellSideEffect: {
     setLocalStorage: (key: string, value: string) => ShellSideEffect;
     setSessionStorage: (key: string, value: string) => ShellSideEffect;
+    /** Server-decided authenticated download. The shell fetches `url` with
+     *  getRequestHeaders() merged (Bearer / anti-forgery / etc.), parses
+     *  Content-Disposition + Content-Type, and saves via Adapter.saveFile.
+     *  `filename` is a fallback used only when Content-Disposition is absent.
+     *  The conditional spread keeps `filename` ABSENT (not undefined) on the
+     *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
+    download: (url: string, filename?: string) => ShellSideEffect;
 };
 /**
  * Web Fetch API–native request handler factory. Auto-detects content-type

package/dist/server.js

@@ -50,6 +50,13 @@ export function shellRedirect(url) {
 export const shellSideEffect = {
     setLocalStorage: (key, value) => ({ type: "set-local-storage", key, value }),
     setSessionStorage: (key, value) => ({ type: "set-session-storage", key, value }),
+    /** Server-decided authenticated download. The shell fetches `url` with
+     *  getRequestHeaders() merged (Bearer / anti-forgery / etc.), parses
+     *  Content-Disposition + Content-Type, and saves via Adapter.saveFile.
+     *  `filename` is a fallback used only when Content-Disposition is absent.
+     *  The conditional spread keeps `filename` ABSENT (not undefined) on the
+     *  JSON wire, matching the .NET WhenWritingNull null-omission contract. */
+    download: (url, filename) => ({ type: "download", url, ...(filename != null ? { filename } : {}) }),
 };
 // ─── Action handler factory ──────────────────────────────────────────────────
 /**

package/dist/tui.d.ts

@@ -118,6 +118,13 @@ export declare class TuiAdapter implements Adapter {
      *  or an unparseable EXISTING store surfaces the loud interstitial + a
      *  stderr line and does NOT clobber a possibly-unrelated user file. */
     storage(scope: "local" | "session", key: string, value: string): void;
+    /** Save an authenticated-download blob to the terminal user's filesystem.
+     *  Directory precedence: $XDG_DOWNLOAD_DIR → ~/Downloads (if it exists) →
+     *  process.cwd(). The chosen path is printed to stderr so the operator
+     *  can find it. The filename is sanitized (no path components / no `..`)
+     *  so a hostile/buggy server can't escape the download dir; this is the
+     *  TUI counterpart to the browser's built-in download-name sanitization. */
+    saveFile(data: Blob, filename: string, _contentType: string): Promise<void>;
     /** Test-only: read back a session value. The wire contract has no storage
      *  read; this exists solely so a unit test can prove the write landed
      *  (same rationale as exporting osc52 for a deterministic test). */

package/dist/tui.js

@@ -4,7 +4,7 @@ import { render as inkRender, Box, Text, useInput, useStdin, useStdout, } from "
 import TextInput from "ink-text-input";
 import SelectInput from "ink-select-input";
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const NO_CTX = {
@@ -1190,6 +1190,37 @@ export class TuiAdapter {
             this.showInterstitial(`Storage write FAILED — your data was NOT saved.\n\n  key:   ${key}\n  error: ${m}`);
         }
     }
+    /** Save an authenticated-download blob to the terminal user's filesystem.
+     *  Directory precedence: $XDG_DOWNLOAD_DIR → ~/Downloads (if it exists) →
+     *  process.cwd(). The chosen path is printed to stderr so the operator
+     *  can find it. The filename is sanitized (no path components / no `..`)
+     *  so a hostile/buggy server can't escape the download dir; this is the
+     *  TUI counterpart to the browser's built-in download-name sanitization. */
+    async saveFile(data, filename, _contentType) {
+        const xdg = process.env.XDG_DOWNLOAD_DIR;
+        const home = homedir();
+        const dir = xdg && xdg.trim()
+            ? xdg
+            : existsSync(join(home, "Downloads")) ? join(home, "Downloads") : process.cwd();
+        mkdirSync(dir, { recursive: true });
+        // Strip path separators (POSIX + Windows) and any leading dots so a
+        // server-supplied "../etc/passwd" or "foo/bar" becomes a flat basename.
+        // Empty/dot-only results fall back to literal "download".
+        const sanitized = filename
+            .split(/[/\\]/).pop() // drop everything before the last separator
+            .replace(/^\.+/, "") // strip leading dots (no hidden files via traversal)
+            .trim();
+        const safeName = sanitized.length > 0 ? sanitized : "download";
+        const out = join(dir, safeName);
+        const buf = Buffer.from(await data.arrayBuffer());
+        writeFileSync(out, buf);
+        try {
+            process.stderr.write(`vms-tui: saved ${out}\n`);
+        }
+        catch {
+            /* stderr unavailable — the file landed regardless */
+        }
+    }
     /** Test-only: read back a session value. The wire contract has no storage
      *  read; this exists solely so a unit test can prove the write landed
      *  (same rationale as exporting osc52 for a deterministic test). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "A server-driven UI framework where the wire format is structured enough that agents can build full-stack apps without ever opening a browser and all UI tests are pure unit tests with no browser runtime. Server returns a JSON tree of typed nodes; a thin TypeScript adapter renders it to DOM. Backend-agnostic — a .NET reference backend ships with the repo, but any language can produce the JSON contract.",
   "type": "module",
   "license": "MIT",