@ashley-shrok/viewmodel-shell 0.5.0 → 0.7.0

package/README.md

@@ -51,13 +51,15 @@ The download endpoint stays auth-gated and the server authorizes in the action h
 
 ## 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";
@@ -72,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.js

@@ -186,7 +186,10 @@ export class BrowserAdapter {
     }
     page(n, parent, on) {
         const el = document.createElement("div");
-        el.className = `vms-page${n.density === "compact" ? " vms-page--compact" : ""}${n.layout && n.layout !== "stack" ? ` vms-page--${n.layout}` : ""}`;
+        el.className = `vms-page${n.density === "compact" ? " vms-page--compact" : ""}${n.layout && n.layout !== "stack" ? ` vms-page--${n.layout}` : ""}${
+        // 0.7.0 (#13) — width override: "wide" or "full" opt-in via a closed
+        // union. Omitted = no modifier class (existing 1080px cap holds).
+        n.width ? ` vms-page--${n.width}` : ""}`;
         if (n.title) {
             const h = document.createElement("h1");
             h.className = "vms-page__title";

package/dist/index.d.ts

@@ -41,6 +41,8 @@ export interface PageNode {
     density?: "comfortable" | "compact";
     /** Layout preset arranging direct children. Omitted or "stack" = current vertical flow (no modifier class). "split" (equal 2-up), "cards" (uniform grid), "sidebar" (thin + wide app shell) emit .vms-page--{value}. Closed union (D-01/D-02; sidebar D-28). */
     layout?: "stack" | "split" | "cards" | "sidebar";
+    /** Page-shell max-width override. Omitted = framework default cap (`--vms-page-max`, 1080px). "wide" = `--vms-page-max-wide` (1440px default), for data-heavy pages with wide tables. "full" = uncapped (max-width: none), for full-bleed dashboards. TUI ignores this (terminals fill naturally). Closed union (D-13 / issue #13). */
+    width?: "wide" | "full";
     children: ViewNode[];
 }
 export interface SectionNode {

package/dist/server.js

@@ -19,7 +19,12 @@ export function parseFormDataAction(formData) {
     const state = JSON.parse(stateRaw);
     const files = {};
     for (const [key, value] of formData.entries()) {
-        if (key !== "_action" && key !== "_state" && value instanceof File) {
+        // Narrow via typeof, NOT `instanceof File`: @types/node@22.19+ declares
+        // its own `File` interface alongside DOM's, and the TS narrowing for
+        // `instanceof File` ambiguates between the two on
+        // `FormDataEntryValue = string | File`. `typeof !== "string"` narrows
+        // the union to File unambiguously and is identical at runtime.
+        if (key !== "_action" && key !== "_state" && typeof value !== "string") {
             files[key] = value;
         }
     }

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 {};

package/dist/tui.d.ts

@@ -1,158 +1,75 @@
-import type { ReactElement } from "react";
 import type { Adapter, ActionEvent, ViewNode } from "./index.js";
-/** OSC 52 clipboard write — the terminal-native analog of the clipboard API.
- *  Works over SSH (no local clipboard dependency). Exported for a direct,
- *  deterministic unit test of the byte format. */
-export declare function osc52(text: string): string;
-/** Hand a URL to a real browser — the terminal analog of a redirect. Zero-dep
- *  (node:child_process). Opener order: $BROWSER → platform default. Detached +
- *  unref so a launched browser can never hold or block the Node event loop
- *  (teardown discipline). Returns false only if spawn threw *synchronously*
- *  (no opener attempted); an async spawn failure (e.g. ENOENT — no xdg-open)
- *  invokes `onSpawnError`. Callers map BOTH false and onSpawnError to the loud
- *  interstitial, so a redirect is never silently lost. Exported so a unit test
- *  can drive it with a stubbed node:child_process. */
-export declare function openExternal(url: string, onSpawnError?: () => void): boolean;
-/** How the vms-tui CLI's default onRedirect classifies a server redirect.
- *  No new wire — pure URL/origin analysis against the current endpoint. A
- *  relative path resolves against the endpoint ⇒ same-origin by construction;
- *  an absolute URL is same-origin iff its `origin` matches (origin compare,
- *  never a string prefix — `http://evil/?x=http://good` must NOT pass). */
-export type RedirectKind = {
-    kind: "same-origin";
-    endpoint: string;
-} | {
-    kind: "different-origin";
-    url: string;
-} | {
-    kind: "invalid";
-    url: string;
-};
-export declare function classify(url: string, fromEndpoint: string): RedirectKind;
-/**
- * Phase 5b terminal adapter — single-line + multi-line editors + selects.
- *
- * Every node renders byte-identically to Phase 1/2 when UNFOCUSED and on the
- * pure `renderTree`/non-TTY path (NO_CTX → interactive:false → no editor). On
- * a TTY the shell's view is interactive: a self-managed focus ring
- * (Tab/Shift-Tab/arrows), Enter/Space dispatch, focus continuity; button /
- * checkbox (`{checked}`) / tabs (`{value}`) / link / copy-button (OSC 52) /
- * form-submit. The focused single-line `field` is an editable
- * `ink-text-input`; the focused `textarea`/`code` field is the contained
- * `MultilineEditor` (Enter→newline; submit via the ring's submit button;
- * `code` adds a dim language label, no literal-tab). The focused `select` is
- * an `ink-select-input` list; the focused `select-multiple` is the contained
- * `MultiSelectInput` (Space toggles; comma-joined wire value; submit via the
- * ring's submit button). Typed drafts survive poll/dispatch re-renders unless
- * the field disappears or the server changes its value — mirroring
- * BrowserAdapter; selects are additionally server-authoritative on ANY server
- * re-render (excluded from draft preservation); password is masked;
- * form-`checkbox` toggles on Space. The still-deferred tier (`file`/`modal`/
- * `table`) arrives in later phases and still renders a visible fail-loud
- * placeholder — never blank, never silent.
- *
- * LEAF MODULE: never imported by src/index.ts / src/browser.ts /
- * src/server.ts, so `ink`/`react` never enter the web or server dependency
- * graph (a unit test asserts this).
- */
+interface TuiOpts {
+    /** "fill" (default) takes the full terminal via alternate-screen buffer;
+     *  "content" renders intrinsic content size in the inline scrollback. */
+    viewport?: "fill" | "content";
+    /** Sidebar rail fraction (0.15–0.6; default 1/3). When `page.layout === "sidebar"`
+     *  (and the same on `section.layout`), the FIRST child occupies this fraction
+     *  of the available width; the remainder fills with the rest of the children. */
+    sidebarFraction?: number;
+}
 export declare class TuiAdapter implements Adapter {
-    private instance;
+    private renderer;
+    private root;
+    private pending;
+    private initPromise;
     private disposed;
-    /** "fill" (default) = occupy the terminal + alternate-screen on a real
-     *  interactive TTY; "content" = legacy intrinsic-content size, no
-     *  alt-screen (the opt-out escape hatch — pre-0.4.5 behavior). */
     private readonly viewport;
-    /** `sidebar` rail width as a fraction of the terminal (fill path only).
-     *  Default 1/3; clamped to a sane [0.15, 0.6] so a bad value can't break
-     *  the layout. Adapter-level styling knob (NOT wire — appearance, not
-     *  arrangement). */
     private readonly sidebarFraction;
-    /** Set once ESC[?1049h was written, so dispose() emits the paired
-     *  ESC[?1049l exactly once (idempotent restore — same discipline as the
-     *  cursor restore Ink does on unmount). */
-    private altEntered;
-    constructor(opts?: {
-        viewport?: "fill" | "content";
-        sidebarFraction?: number;
-    });
-    /** Injected by tui-cli.ts: lets a keyboard Ctrl-C (which, under Ink's raw
-     *  mode, is delivered as input 0x03 and never raises SIGINT) reach the
-     *  CLI's single idempotent shutdown. A TUI-internal seam between our two
-     *  leaf files — NOT part of the core Adapter interface. */
-    private requestExit;
-    /** session storage — in-memory, process lifetime (browser sessionStorage
-     *  analog for a single-process CLI). Write-only per the wire contract. */
-    private sessionStore;
-    /** When non-null, App renders the loud Interstitial instead of the vm. */
-    private interstitial;
-    /** Last rendered vm/onAction — so showInterstitial can rerender through the
-     *  SAME single Ink instance (never a 2nd inkRender). */
-    private lastVm;
-    private lastOnAction;
-    setRequestExit(fn: (code: number) => void): void;
+    private readonly sessionStore;
+    private focusedPaneIndex;
+    private lastPaneCount;
+    private readonly fieldValues;
+    private readonly fieldWireValues;
+    private copiedKey;
+    private copiedTimer;
+    constructor(opts?: TuiOpts);
+    private setFieldValue;
+    /** Resolve a field's display value at render time. The draft-preservation
+     *  contract (AGENTS.md) is "user edits survive re-renders UNLESS the server
+     *  explicitly sets a new value for that field." Three states:
+     *    1. First time we see this field name — initialize the wire baseline
+     *       WITHOUT clobbering any pre-existing edit value (matters when a test
+     *       primes fieldValues via setFieldValue before the first render).
+     *    2. Wire value unchanged since last render — preserve the edit value.
+     *    3. Wire value differs from the prior wire baseline — server intent
+     *       change → reset the edit value to match. */
+    private copy;
+    private resolveFieldValue;
     render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
-    /** The interactive element used by render() and by interaction unit tests. */
-    createApp(vm: ViewNode, onAction: (a: ActionEvent) => void, opts?: {
-        requestExit?: (code: number) => void;
-    }): ReactElement;
-    /** Render a full-screen loud notice through the SINGLE existing Ink instance
-     *  (never a 2nd inkRender, never a raw stdout write that would corrupt Ink's
-     *  diff / the ESC[?25h restore). No-op once disposed — closes the
-     *  redirect-during-teardown rerender-after-unmount race. Process stays
-     *  alive; the CLI owns exit (Ctrl-C via App's existing useInput → shutdown).
-     *  Mounts the instance if a notice somehow precedes the first render (that
-     *  is still the FIRST inkRender, not a second). */
-    showInterstitial(msg: string): void;
-    /** Standalone redirect fallback. Only reached when a consumer wires
-     *  TuiAdapter WITHOUT ShellOptions.onRedirect — core precedence means the
-     *  vms-tui CLI's onRedirect suppresses this (proven by adapter-seam C/F).
-     *  Origin-blind (the adapter has no shell/endpoint ref): hand off to a
-     *  browser, else the loud interstitial. Never silent, never throws into
-     *  core. No-op once disposed. */
+    private init;
+    private flushPending;
+    private navigateForLinks;
+    /** Test-only: read the current edit value for a named field (for asserting
+     *  draft preservation across server re-renders). */
+    _peekFieldValue(name: string): string | undefined;
+    /** Test-only: read the current "copied" key for asserting that activation
+     *  set the feedback state. Returns null when no button is currently flashing. */
+    _peekCopiedKey(): string | null;
+    private cycleFocus;
+    /** B5 — keyboard activation of the focused pane's primary actionable.
+     *
+     *  Mode mapping:
+     *    "enter" → dispatch the first button.action / link → navigate /
+     *              copy-button → copy(). No-op if the pane has inputs
+     *              (FieldView's <input onSubmit> handles Enter for forms).
+     *    "space" → toggle the first checkbox (dispatch action with
+     *              {checked: !node.checked}). No-op if the pane has inputs
+     *              (Space is a printable character in text fields).
+     *
+     *  Always reads pane state from the CURRENT vm (this.pending), so a key
+     *  pressed mid-render still acts on the structure the user can see.
+     */
+    private activatePane;
+    /** Teardown — restore terminal cleanly. Idempotent. */
+    dispose(): void;
     navigate(url: string): void;
-    /** Write-only client storage. `session` → in-memory (process lifetime).
-     *  `local` → a SYNCHRONOUS XDG state-file write — synchronous is mandatory:
-     *  the core applies side-effects before the redirect branch (adapter-seam
-     *  Case E), so the token must land before navigation. Fail-loud, never
-     *  swallow, never re-throw into core (push() has no try/catch): an I/O error
-     *  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). */
+    /** Test-only: read back a session value. The wire contract has no
+     *  storage read; this exists solely so unit tests can prove the write
+     *  landed (parity with the Ink adapter's _peekSession). */
     _peekSession(key: string): string | undefined;
-    /** Pure ViewNode → Ink element, UNFOCUSED (NO_CTX). Used by static unit
-     *  tests; byte-identical to Phase 1 output. */
-    renderTree(vm: ViewNode): ReactElement;
-    /** Spacing rhythm. compact collapses gaps/padding (mirrors .vms--compact). */
-    private spacing;
-    /**
-     * React key: the roadmap's identity heuristic — explicit id/name where
-     * present, else positional index. Render-only; never a wire field.
-     */
-    private keyOf;
-    /** Fail-loud placeholder — single source of the phase string. */
-    private unsupported;
-    /** Focused-node affordance. Unfocused → returns the element unchanged, so
-     *  the static path stays byte-identical to Phase 1. Focused → a leading
-     *  cyan caret (deterministic + information-honest; ▸ U+25B8 is distinct
-     *  from the list-item markers › / ·). */
-    private focusWrap;
-    /** Shipped list-item variant → marker + child tint (fail-soft: unknown ok). */
-    private listItemStyle;
-    /** page & section share the 4 layout presets. Information-honest, not pixel. */
-    private layoutContainer;
-    private renderNode;
-    /** Resolves when the Ink app unmounts; immediate if nothing was rendered. */
-    waitUntilExit(): Promise<void>;
-    /** Idempotent terminal restore — unmount restores cursor/raw mode. */
-    dispose(): void;
 }
+export declare function renderTree(vm: ViewNode): React.ReactNode;
+export {};