@ashley-shrok/viewmodel-shell 0.4.9 → 0.6.0

package/README.md

@@ -33,15 +33,33 @@ 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:
+The same backend renders in a terminal — same wire, no backend change, with a real lazygit-style UX: mouse clicks, wheel scroll, per-pane focus cycle, and a context-aware status bar. Point the CLI at any ViewModel Shell endpoint:
 
 ```bash
-npx vms-tui https://your-app.example/api/tasks
+bunx vms-tui https://your-app.example/api/tasks
 ```
 
-The action endpoint is derived by convention (`<endpoint>/action`). Or wire it programmatically, exactly like `BrowserAdapter`:
+The action endpoint is derived by convention (`<endpoint>/action`). The TUI requires the [Bun](https://bun.sh) runtime — install once via `curl -fsSL https://bun.sh/install | bash` (or any installer on bun.sh). Browser and server consumers are unaffected; only `/tui` + `vms-tui` need Bun.
+
+Wire it programmatically, exactly like `BrowserAdapter`:
 
 ```ts
 import { ViewModelShell } from "@ashley-shrok/viewmodel-shell";
@@ -56,12 +74,14 @@ const shell = new ViewModelShell({
 shell.load();
 ```
 
-On an interactive terminal the app **fills the screen** via the alternate-screen buffer — a vim/htop-style takeover that re-flows on resize and restores your prior terminal verbatim on exit (every exit path: quit, Ctrl-C, SIGTERM, crash). Opt out with `new TuiAdapter({ viewport: "content" })` for intrinsic content size and no screen takeover. Non-interactive runs (pipe / CI / agent / `</dev/null`) are unaffected — one static frame, no alternate screen.
+**Interaction model.** Every `section`, top-level `list`, and top-level `table` is its own scrollable focus pane with a border. Tab/Shift-Tab cycles focus across panes; ↑↓ PgUp/PgDn scroll inside the focused pane; click any button, checkbox, link, copy-button, table header, or table row to act on it. Enter activates the focused pane's primary actionable (first button → dispatch, first link → navigate, first copy-button → OSC-52 copy). Space toggles the focused pane's first checkbox-with-action. When the pane has a text field, Enter submits the enclosing form (Field's `<input onSubmit>`) and Space is a normal character.
+
+On an interactive terminal the app **fills the screen** via the alternate-screen buffer — a vim/htop-style takeover that re-flows on resize and restores your prior terminal verbatim on exit (every exit path: quit, Ctrl-C, SIGTERM, crash). Opt out with `new TuiAdapter({ viewport: "content" })` for intrinsic content size and no screen takeover. Non-interactive runs (pipe / CI / agent / `</dev/null`) are unaffected.
 
-The TUI is built on [Ink](https://github.com/vadimdemedes/ink) and friends, declared as **optional** dependencies (`ink`, `react`, `ink-text-input`, `ink-select-input`) so web and server consumers are unaffected — they are never imported by the browser, server, or core entrypoints. `npx vms-tui` installs them automatically. **Project consumers using `TuiAdapter` programmatically must add all four explicitly** — optional dependencies are *not* pulled transitively when another project depends on this package (notably with `bun install`):
+The TUI is built on [OpenTUI](https://github.com/anomalyco/opentui), declared as **optional** dependencies (`@opentui/core`, `@opentui/react`, `react@19`) so web and server consumers are unaffected — they are never imported by the browser, server, or core entrypoints. `bunx vms-tui` installs them automatically. **Project consumers using `TuiAdapter` programmatically must add all three explicitly** — optional dependencies are *not* pulled transitively:
 
 ```bash
-npm i @ashley-shrok/viewmodel-shell ink react ink-text-input ink-select-input
+bun add @ashley-shrok/viewmodel-shell @opentui/core @opentui/react react
 ```
 
 See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for what the terminal renders.

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-cli.js

@@ -1,18 +1,31 @@
 #!/usr/bin/env node
 // vms-tui — drive any ViewModel Shell backend from a terminal.
 //
-//   vms-tui <endpoint-url>
-//   e.g.  vms-tui http://localhost:3000/api/tasks
+//   bunx vms-tui <endpoint-url>
+//   e.g.  bunx vms-tui http://localhost:3000/api/tasks
 //
 // Convention: actions POST to `<endpoint>/action` (matches the demos:
-// GET /api/tasks  +  POST /api/tasks/action). A future flag can override it.
+// GET /api/tasks  +  POST /api/tasks/action).
 //
-// Pure entrypoint — never imported as a library (the importable surface is
-// TuiAdapter via the "./tui" export), so no import.meta.main guard is needed.
-import { ViewModelShell } from "./index.js";
+// Runtime requirement (0.6.0+): Bun. The shebang above is Node so that an
+// accidental `npx vms-tui …` prints a clear "needs Bun" message instead of
+// crashing inside an FFI-laden OpenTUI import. Under `bunx`, `typeof Bun`
+// is defined and the script proceeds normally.
 const USAGE = "Usage: vms-tui <endpoint-url>\n" +
-    "  e.g.  vms-tui http://localhost:3000/api/tasks\n" +
-    "  Actions POST to <endpoint>/action.";
+    "  e.g.  bunx vms-tui http://localhost:3000/api/tasks\n" +
+    "  Actions POST to <endpoint>/action.\n" +
+    "  Requires Bun runtime: https://bun.sh/install";
+// ── Bun runtime guard ─────────────────────────────────────────────────────
+// vms-tui's TUI substrate (OpenTUI) uses Bun's FFI APIs and is not yet
+// Node-compatible. Failing fast with a clear message here beats a confusing
+// ESM resolution stack trace deeper in the import chain.
+if (typeof Bun === "undefined") {
+    process.stderr.write("vms-tui requires the Bun runtime.\n" +
+        "  Install:   curl -fsSL https://bun.sh/install | bash\n" +
+        "  Then run:  bunx vms-tui <endpoint-url>\n" +
+        "(see https://bun.sh for other installers)\n");
+    process.exit(1);
+}
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function main() {
     const arg = process.argv[2];
@@ -22,7 +35,6 @@ async function main() {
         return;
     }
     try {
-        // Validate; rejects garbage early instead of failing deep in fetch.
         void new URL(arg);
     }
     catch {
@@ -31,55 +43,44 @@ async function main() {
         return;
     }
     const endpoint = arg;
-    // Guarded dynamic import: if the optional `ink`/`react` deps are absent,
-    // fail loud with an install hint instead of an ESM resolution stack trace.
+    // Dynamic import — under Bun, this resolves to the OpenTUI-backed adapter.
+    // Under Node we'd never get here (the Bun guard above exits first).
     let TuiAdapter;
-    let openExternal;
-    let classify;
     try {
-        ({ TuiAdapter, openExternal, classify } = await import("./tui.js"));
+        ({ TuiAdapter } = await import("./tui.js"));
     }
     catch (err) {
-        process.stderr.write("vms-tui requires its optional peer packages: 'ink', 'react', " +
-            "'ink-text-input', 'ink-select-input'.\n" +
-            "Install them:  npm i ink react ink-text-input ink-select-input\n" +
+        process.stderr.write("vms-tui: failed to load the TUI adapter — make sure '@opentui/core' " +
+            "and '@opentui/react' are installed.\n" +
+            "  bun install @opentui/core @opentui/react react\n" +
             `(load error: ${err.message})\n`);
         process.exitCode = 1;
         return;
     }
+    // Dynamically import ViewModelShell (the framework core; not Bun-specific)
+    // alongside, to keep the import topology clean.
+    const { ViewModelShell } = await import("./index.js");
     const adapter = new TuiAdapter();
     let loadFailed = false;
     let exiting = false;
-    // Single, idempotent teardown owned by the CLI.
-    //
-    // Ink registers `signal-exit` and resolving its waitUntilExit() promise
-    // (which adapter.dispose() → Ink unmount does) lets main()'s tail resume.
-    // Without the `exiting` guard that tail would set process.exitCode = 0 and
-    // race the real signal code away (observed: SIGINT exited 0, not 130).
-    // So: set the code FIRST, restore the terminal, then exit — and let the
-    // first caller win; any later caller (incl. the resumed await-tail) no-ops.
     const shutdown = (code) => {
         if (exiting)
             return;
         exiting = true;
         process.exitCode = code;
         try {
-            adapter.dispose(); // Ink unmount → cursor/raw-mode restored
-        }
-        catch {
-            /* best-effort, idempotent */
+            adapter.dispose();
         }
+        catch { /* idempotent */ }
         process.exit(code);
     };
     process.once("SIGINT", () => shutdown(130));
     process.once("SIGTERM", () => shutdown(143));
     process.once("uncaughtException", (err) => {
         try {
-            adapter.dispose(); // restore BEFORE printing so the message is readable
-        }
-        catch {
-            /* idempotent */
+            adapter.dispose();
         }
+        catch { /* idempotent */ }
         process.stderr.write(`vms-tui: ${err?.stack ?? String(err)}\n`);
         shutdown(1);
     });
@@ -87,74 +88,45 @@ async function main() {
         try {
             adapter.dispose();
         }
-        catch {
-            /* idempotent */
-        }
+        catch { /* idempotent */ }
         process.stderr.write(`vms-tui: ${String(reason)}\n`);
         shutdown(1);
     });
-    // Final safety net: any other exit path still restores the terminal.
     process.once("exit", () => {
         try {
             adapter.dispose();
         }
-        catch {
-            /* idempotent */
-        }
+        catch { /* idempotent */ }
     });
-    // Phase 2: the adapter now uses Ink input hooks → Ink puts stdin in raw
-    // mode, which clears ISIG, so a *keyboard* Ctrl-C is delivered as input
-    // byte 0x03 and never raises SIGINT (the process.once("SIGINT") above only
-    // fires for a *programmatic* kill -INT). Route that keyboard Ctrl-C, caught
-    // in the adapter's input handler, into this same idempotent shutdown so the
-    // terminal is always restored. SIGTERM and programmatic SIGINT are
-    // unaffected by raw mode and keep working via the handlers above. (The
-    // keep-alive below is now redundant on the TTY path — Ink's resumed raw
-    // stdin holds the loop — but is harmless and kept as belt-and-suspenders.)
-    adapter.setRequestExit((code) => shutdown(code));
-    // Phase 4: server-initiated redirects via the existing core onRedirect seam
-    // (no new wire). A ViewModelShell's endpoint is immutable and load() takes
-    // no URL, so a same-origin redirect is followed by building a FRESH shell
-    // that reuses the SAME single adapter (Ink rerenders in place — no remount,
-    // teardown topology unchanged). connect()'s options carry this same
-    // onRedirect, so redirects chain.
-    let redirectFailed = false;
-    let currentShell;
-    // Non-interactive iff EITHER stream is not a TTY. Checking stdin too (not
-    // just stdout) is load-bearing: with the tui.tsx isActive fix the App's
-    // useInput is correctly inert on non-TTY stdin, so nothing holds the event
-    // loop — if stdout were a TTY but stdin a pipe (`vms-tui url </dev/null`
-    // from an interactive shell), a stdout-only guard would fall through to the
-    // keep-alive + waitUntilExit() and HANG forever (no input can ever arrive).
-    // One static frame + exit is the only correct behavior when stdin is dead.
+    // Non-interactive: render one frame, then exit. Either stream not being a
+    // TTY is the signal — a stdout TTY with a piped stdin would hang forever
+    // (no input can ever arrive), so we check both.
     const nonInteractive = !process.stdout.isTTY || !process.stdin.isTTY;
+    // ── Redirect handling (B1: minimal) ────────────────────────────────────
+    // Same-origin: rebuild the shell against the new endpoint and reload, so
+    // the polling/state cycle continues seamlessly. Different-origin or
+    // invalid: delegate to adapter.navigate (which spawns xdg-open / open
+    // / start), or, on non-TTY, print a loud stderr line. B5 will re-add
+    // the in-app interstitial UX the Ink CLI had.
+    let currentShell;
     const handleRedirect = (url, fromEndpoint) => {
-        const c = classify(url, fromEndpoint);
+        const c = classifyRedirect(url, fromEndpoint);
         if (c.kind === "same-origin") {
-            currentShell.stopPolling(); // no timer armed today; defends a future one
+            currentShell.stopPolling();
             currentShell = connect(c.endpoint);
-            void currentShell.load(); // failures flow through the shared onError
+            void currentShell.load();
             return;
         }
         if (nonInteractive) {
-            // Non-interactive: never spawn a browser; loud stderr + nonzero exit via
-            // the SINGLE shutdown funnel (redirectFailed is read at the exit site).
             process.stderr.write(`vms-tui: cannot follow redirect (${c.kind}): ${url}\n`);
-            redirectFailed = true;
+            loadFailed = true;
             return;
         }
         if (c.kind === "different-origin") {
-            const detail = `This app asked to open an external URL:\n\n  ${c.url}`;
-            const fb = () => adapter.showInterstitial(`${detail}\n\n(no browser could be launched — open it manually)`);
-            if (openExternal(c.url, fb)) {
-                adapter.showInterstitial(`${detail}\n\n(opening in your browser…)`);
-            }
-            else {
-                fb();
-            }
+            adapter.navigate(c.url);
         }
         else {
-            adapter.showInterstitial(`This app returned an invalid redirect:\n\n  ${JSON.stringify(url)}`);
+            process.stderr.write(`vms-tui: invalid redirect URL: ${JSON.stringify(url)}\n`);
         }
     };
     const connect = (ep) => new ViewModelShell({
@@ -163,7 +135,6 @@ async function main() {
         adapter,
         onError: (err) => {
             loadFailed = true;
-            // A stderr line guarantees visibility even before the first render.
             process.stderr.write(`vms-tui: ${err.message}\n`);
         },
         onRedirect: (url) => handleRedirect(url, ep),
@@ -177,26 +148,42 @@ async function main() {
         process.stderr.write(`vms-tui: ${err.message}\n`);
     }
     if (nonInteractive) {
-        // Non-interactive (piped / CI / dead stdin): nothing to interact with —
-        // emit one static frame and exit instead of hanging forever. The delay
-        // lets Ink flush its throttled render. (Redirects can't fire here: load()
-        // ignores response.redirect and non-TTY performs no dispatch — so
-        // redirectFailed stays false unless a future code path dispatches.)
-        await delay(80);
-        return shutdown(loadFailed || redirectFailed ? 1 : 0);
+        // Let OpenTUI's renderer flush one frame, then exit. 100ms is generous;
+        // OpenTUI's render pipeline is microtask-fast.
+        await delay(100);
+        return shutdown(loadFailed ? 1 : 0);
     }
-    // Load/connection failure → nothing rendered; exit now rather than wait for
-    // a Ctrl-C the user has no reason to send.
     if (loadFailed) {
         return shutdown(1);
     }
-    // TTY + rendered: keep the frame up until the user quits (Ctrl-C). Ink's
-    // resumed raw stdin holds the loop (Phase 2+), but the no-op timer is kept
-    // as belt-and-suspenders; the SIGINT/SIGTERM handlers own exit + restore.
-    // (waitUntilExit() wins the race if Ink unmounts for another reason.)
-    const keepAlive = setInterval(() => { }, 1 << 30);
-    await adapter.waitUntilExit();
-    clearInterval(keepAlive);
-    shutdown(0);
+    // TTY + rendered: keep the frame up until the user quits (Ctrl-C / SIGTERM).
+    // OpenTUI's renderer owns the keep-alive (its async event loop holds the
+    // process), so we just await a never-resolving promise — SIGINT/SIGTERM
+    // handlers funnel into shutdown().
+    await new Promise(() => { });
+}
+function classifyRedirect(target, fromEndpoint) {
+    let from;
+    try {
+        from = new URL(fromEndpoint);
+    }
+    catch {
+        return { kind: "invalid", reason: "current endpoint is not a valid URL" };
+    }
+    let to;
+    try {
+        to = new URL(target, from);
+    }
+    catch {
+        return { kind: "invalid", reason: "redirect target is not a valid URL" };
+    }
+    if (to.protocol !== "http:" && to.protocol !== "https:") {
+        return { kind: "invalid", reason: `unsupported protocol: ${to.protocol}` };
+    }
+    if (to.origin === from.origin) {
+        return { kind: "same-origin", endpoint: to.toString() };
+    }
+    return { kind: "different-origin", url: to.toString() };
 }
 void main();
+export {};