@ashley-shrok/viewmodel-shell 0.4.3 → 0.4.5

package/README.md

@@ -56,7 +56,15 @@ const shell = new ViewModelShell({
 shell.load();
 ```
 
-The TUI is built on [Ink](https://github.com/vadimdemedes/ink), declared as an **optional** dependency: CLI/`npx` use installs it automatically, while web and server consumers are unaffected — it is never imported by the browser, server, or core entrypoints. See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for what the terminal renders.
+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.
+
+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`):
+
+```bash
+npm i @ashley-shrok/viewmodel-shell ink react ink-text-input ink-select-input
+```
+
+See [AGENTS.md](https://github.com/ashley-shrok/ViewModelShell/blob/main/AGENTS.md) for what the terminal renders.
 
 ## Themes
 

package/dist/tui-cli.js

@@ -40,8 +40,9 @@ async function main() {
         ({ TuiAdapter, openExternal, classify } = await import("./tui.js"));
     }
     catch (err) {
-        process.stderr.write("vms-tui requires the optional 'ink' and 'react' packages.\n" +
-            "Install them:  npm i ink react\n" +
+        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" +
             `(load error: ${err.message})\n`);
         process.exitCode = 1;
         return;
@@ -119,6 +120,14 @@ async function main() {
     // 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.
+    const nonInteractive = !process.stdout.isTTY || !process.stdin.isTTY;
     const handleRedirect = (url, fromEndpoint) => {
         const c = classify(url, fromEndpoint);
         if (c.kind === "same-origin") {
@@ -127,9 +136,9 @@ async function main() {
             void currentShell.load(); // failures flow through the shared onError
             return;
         }
-        if (!process.stdout.isTTY) {
-            // Non-TTY: never spawn a browser; loud stderr + nonzero exit via the
-            // SINGLE shutdown funnel (redirectFailed is read at the exit site).
+        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;
             return;
@@ -167,9 +176,9 @@ async function main() {
         loadFailed = true;
         process.stderr.write(`vms-tui: ${err.message}\n`);
     }
-    if (!process.stdout.isTTY) {
-        // Non-TTY (piped / CI): nothing to interact with — emit one static frame
-        // and exit instead of hanging on a Ctrl-C that can never come. The delay
+    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.)

package/dist/tui.d.ts

@@ -58,6 +58,17 @@ export declare function classify(url: string, fromEndpoint: string): RedirectKin
 export declare class TuiAdapter implements Adapter {
     private instance;
     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;
+    /** 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";
+    });
     /** 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

package/dist/tui.js

@@ -615,8 +615,42 @@ function TableFilterInput(props) {
 function App(props) {
     const { vm, renderWith } = props;
     const { isRawModeSupported } = useStdin();
-    const { write } = useStdout();
-    const interactive = isRawModeSupported;
+    const { write, stdout } = useStdout();
+    // `=== true` is LOAD-BEARING, not defensive. Ink's App.isRawModeSupported()
+    // returns `this.props.stdin.isTTY`, which is `true` on a TTY but `undefined`
+    // (never `false`) on a non-TTY stdin (pipe / </dev/null / agent / CI). Ink's
+    // useInput skips raw mode ONLY when `options.isActive === false` (strict).
+    // So passing the raw `undefined` as isActive does NOT skip → Ink calls
+    // setRawMode → throws "Raw mode is not supported" and dumps a react error
+    // frame on the non-TTY path. Coercing to a real boolean makes the gate
+    // `{ isActive: false }`, which Ink honors → clean static render. (A TTY
+    // gives `true`; ink-testing-library gives `true` → tests unchanged.)
+    const interactive = isRawModeSupported === true;
+    // Viewport fill (0.4.5). On a real interactive terminal, occupy the whole
+    // window so layout presets — especially `sidebar`'s flexGrow main pane —
+    // can expand: the terminal analog of BrowserAdapter filling the viewport
+    // via CSS. Gated on the REAL process TTYs, NOT Ink's isRawModeSupported
+    // (which ink-testing-library forces `true`): under vitest
+    // `process.stdout.isTTY` is false ⇒ no wrap ⇒ every existing App and
+    // conformance frame stays byte-identical by construction (and the pure
+    // `renderTree` path never reaches here). Opt out with
+    // `new TuiAdapter({ viewport: "content" })`.
+    const realTTY = process.stdout.isTTY === true && process.stdin.isTTY === true;
+    const fillViewport = realTTY && props.viewport !== "content";
+    const [vp, setVp] = useState(() => ({
+        cols: stdout?.columns,
+        rows: stdout?.rows,
+    }));
+    useEffect(() => {
+        if (!fillViewport || !stdout)
+            return;
+        const onResize = () => setVp({ cols: stdout.columns, rows: stdout.rows });
+        onResize(); // sync to the live size on (re)mount
+        stdout.on("resize", onResize);
+        return () => {
+            stdout.off("resize", onResize);
+        };
+    }, [fillViewport, stdout]);
     const [focusedKey, setFocusedKey] = useState(null);
     const [copiedKey, setCopiedKey] = useState(null);
     // User-typed field drafts, keyed by focus key. Mirrors BrowserAdapter's
@@ -958,15 +992,23 @@ function App(props) {
         onFieldSubmit,
         onTableFilter: tableFilter,
     };
-    if (props.interstitial != null)
-        return _jsx(Interstitial, { msg: props.interstitial });
-    if (modal)
-        // Screen-ownership: render ONLY the modal, horizontally centered (the
-        // honest terminal "z-layer" — Ink has no z-index; base tree suppressed).
-        // Vertical centering deferred (no reliable terminal-height center in Ink;
-        // cosmetic, not load-bearing).
-        return (_jsx(Box, { flexDirection: "column", alignItems: "center", children: renderWith(modal, rctx) }));
-    return renderWith(vm, rctx);
+    const content = props.interstitial != null ? (_jsx(Interstitial, { msg: props.interstitial })) : modal ? (
+    // Screen-ownership: render ONLY the modal, horizontally centered (the
+    // honest terminal "z-layer" — Ink has no z-index; base tree suppressed).
+    // Vertical centering deferred (no reliable terminal-height center in Ink;
+    // cosmetic, not load-bearing).
+    _jsx(Box, { flexDirection: "column", alignItems: "center", children: renderWith(modal, rctx) })) : (renderWith(vm, rctx));
+    // Fill the terminal so flexGrow children (the sidebar main pane) have a
+    // terminal-sized parent to expand into. `width` is the load-bearing dim
+    // (horizontal sidebar fill); `height` makes it a true full-screen surface
+    // (paired with the adapter's alternate-screen). `cols` is always present on
+    // a real TTY; if a host omits `rows`, height falls back to auto without
+    // breaking width. When !fillViewport (every test; non-TTY; opt-out) this
+    // returns `content` unchanged ⇒ byte-identical to pre-0.4.5.
+    if (fillViewport && typeof vp.cols === "number" && vp.cols > 0) {
+        return (_jsx(Box, { width: vp.cols, height: vp.rows, flexDirection: "column", children: content }));
+    }
+    return content;
 }
 /**
  * Phase 5b terminal adapter — single-line + multi-line editors + selects.
@@ -997,6 +1039,17 @@ function App(props) {
 export class TuiAdapter {
     instance;
     disposed = false;
+    /** "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). */
+    viewport;
+    /** 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). */
+    altEntered = false;
+    constructor(opts) {
+        this.viewport = opts?.viewport ?? "fill";
+    }
     /** 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
@@ -1020,6 +1073,25 @@ export class TuiAdapter {
         this.interstitial = null; // a fresh view supersedes any prior notice
         const app = this.createApp(vm, onAction);
         if (!this.instance) {
+            // Enter the alternate-screen buffer BEFORE the first mount so every
+            // frame draws there and the user's prior scrollback is untouched
+            // (restored verbatim by dispose()'s paired ESC[?1049l). Gated on the
+            // REAL process TTYs — the exact complement of the CLI's `nonInteractive`
+            // — so the 0.4.4 non-TTY static one-shot (pipe/CI/agent) emits NO
+            // escape, and unit tests (process.stdout.isTTY false under vitest)
+            // never enter it. "content" opts out entirely.
+            if (this.viewport !== "content" &&
+                process.stdout.isTTY === true &&
+                process.stdin.isTTY === true &&
+                !this.altEntered) {
+                try {
+                    process.stdout.write("\x1b[?1049h");
+                    this.altEntered = true;
+                }
+                catch {
+                    /* if the enter write fails, dispose() must not emit the leave */
+                }
+            }
             // exitOnCtrlC:false — the CLI is the single owner of teardown; Ink must
             // not race it. Ctrl-C is handled in App and routed via requestExit.
             this.instance = inkRender(app, { exitOnCtrlC: false });
@@ -1032,7 +1104,7 @@ export class TuiAdapter {
     }
     /** The interactive element used by render() and by interaction unit tests. */
     createApp(vm, onAction, opts) {
-        return (_jsx(App, { vm: vm, onAction: onAction, requestExit: opts?.requestExit ?? this.requestExit, interstitial: this.interstitial, renderWith: (v, rctx) => this.renderNode(v, 0, "comfortable", undefined, rctx) }));
+        return (_jsx(App, { vm: vm, onAction: onAction, requestExit: opts?.requestExit ?? this.requestExit, interstitial: this.interstitial, viewport: this.viewport, renderWith: (v, rctx) => this.renderNode(v, 0, "comfortable", undefined, rctx) }));
     }
     /** 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
@@ -1472,6 +1544,21 @@ export class TuiAdapter {
         if (this.disposed)
             return;
         this.disposed = true;
-        this.instance?.unmount();
+        this.instance?.unmount(); // Ink restores cursor/raw mode on the alt screen
+        if (this.altEntered) {
+            // THEN leave the alternate-screen buffer → the user's prior terminal
+            // (scrollback, cursor) is restored verbatim. Reached on EVERY exit
+            // path: the CLI funnels shutdown / SIGINT / SIGTERM / uncaught /
+            // unhandledRejection / process 'exit' all through dispose(), so a
+            // crash or kill cannot strand the user on the alt screen. Idempotent
+            // (disposed guard + altEntered cleared).
+            this.altEntered = false;
+            try {
+                process.stdout.write("\x1b[?1049l");
+            }
+            catch {
+                /* stdout gone during teardown — nothing more we can do */
+            }
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ashley-shrok/viewmodel-shell",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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",