@ashley-shrok/viewmodel-shell 0.4.4 → 0.4.5

package/README.md

@@ -56,6 +56,8 @@ 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.
+
 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

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,7 +615,7 @@ function TableFilterInput(props) {
 function App(props) {
     const { vm, renderWith } = props;
     const { isRawModeSupported } = useStdin();
-    const { write } = useStdout();
+    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
@@ -626,6 +626,31 @@ function App(props) {
     // `{ 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
@@ -967,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.
@@ -1006,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
@@ -1029,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 });
@@ -1041,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
@@ -1481,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.4",
+  "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",