@ashley-shrok/viewmodel-shell 0.4.4 → 0.4.6

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

@@ -12,6 +12,7 @@ const NO_CTX = {
     copiedKey: null,
     focusKey: () => undefined,
     interactive: false,
+    fill: false,
     draft: () => undefined,
 };
 /** OSC 52 clipboard write — the terminal-native analog of the clipboard API.
@@ -615,7 +616,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 +627,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
@@ -962,20 +988,29 @@ function App(props) {
         copiedKey,
         focusKey: (o) => map.get(o),
         interactive,
+        fill: fillViewport,
         draft: (k) => draftFor(k),
         onFieldChange: (k, v) => setDraft((s) => ({ ...s, [k]: v })),
         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 +1041,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 +1075,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 +1106,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
@@ -1182,9 +1247,16 @@ export class TuiAdapter {
     layoutContainer(layout, children, density, rctx) {
         const sp = this.spacing(density);
         const kids = (children ?? []).map((c, i) => this.renderNode(c, this.keyOf(c, i), density, undefined, rctx));
+        // 0.4.6 — when filling a real terminal, the layout spine must carry the
+        // terminal width into the panes. Probed fact: Yoga align-stretch ALONE
+        // does NOT fill here; an explicit width:"100%" on the content wrapper
+        // does. `cards` is intentionally excluded (a uniform small-tile grid by
+        // design — force-filling defeats the preset). fill=false on the static /
+        // non-TTY path ⇒ {} ⇒ byte-identical to pre-0.4.6.
+        const fillW = rctx.fill ? { width: "100%" } : {};
         switch (layout) {
             case "split":
-                return (_jsx(Box, { flexDirection: "row", gap: sp.gap || 1, children: kids.map((el, i) => (_jsx(Box, { flexGrow: 1, flexShrink: 1, flexBasis: 0, children: el }, i))) }));
+                return (_jsx(Box, { flexDirection: "row", gap: sp.gap || 1, ...fillW, children: kids.map((el, i) => (_jsx(Box, { flexGrow: 1, flexShrink: 1, flexBasis: 0, children: rctx.fill ? (_jsx(Box, { width: "100%", flexDirection: "column", children: el })) : (el) }, i))) }));
             case "cards":
                 return (_jsx(Box, { flexDirection: "row", flexWrap: "wrap", gap: sp.gap || 1, children: kids.map((el, i) => (_jsx(Box, { flexGrow: 0, flexShrink: 1, flexBasis: 28, minWidth: 20, children: el }, i))) }));
             case "sidebar": {
@@ -1194,10 +1266,10 @@ export class TuiAdapter {
                 if (rest.length === 0) {
                     return (_jsx(Box, { flexShrink: 0, flexBasis: 24, minWidth: 18, children: rail }));
                 }
-                return (_jsxs(Box, { flexDirection: "row", gap: sp.gap || 1, children: [_jsx(Box, { flexShrink: 0, flexBasis: 24, minWidth: 18, children: rail }), _jsx(Box, { flexGrow: 1, flexShrink: 1, flexBasis: 0, children: _jsx(Box, { flexDirection: "column", gap: sp.gap, children: rest }) })] }));
+                return (_jsxs(Box, { flexDirection: "row", gap: sp.gap || 1, ...fillW, children: [_jsx(Box, { flexShrink: 0, flexBasis: 24, minWidth: 18, children: rail }), _jsx(Box, { flexGrow: 1, flexShrink: 1, flexBasis: 0, children: _jsx(Box, { flexDirection: "column", gap: sp.gap, ...fillW, children: rest }) })] }));
             }
             default: // "stack" / undefined
-                return (_jsx(Box, { flexDirection: "column", gap: sp.gap, children: kids }));
+                return (_jsx(Box, { flexDirection: "column", gap: sp.gap, ...fillW, children: kids }));
         }
     }
     // ── the node switch ──────────────────────────────────────────────────────
@@ -1206,7 +1278,7 @@ export class TuiAdapter {
             case "page": {
                 const d = node.density === "compact" ? "compact" : "comfortable";
                 const sp = this.spacing(d);
-                return (_jsxs(Box, { flexDirection: "column", gap: sp.gap, children: [node.title ? (_jsx(Box, { children: _jsx(Text, { bold: true, underline: true, children: node.title }) })) : null, this.layoutContainer(node.layout, node.children ?? [], d, rctx)] }, key));
+                return (_jsxs(Box, { flexDirection: "column", gap: sp.gap, ...(rctx.fill ? { width: "100%", flexGrow: 1 } : {}), children: [node.title ? (_jsx(Box, { children: _jsx(Text, { bold: true, underline: true, children: node.title }) })) : null, this.layoutContainer(node.layout, node.children ?? [], d, rctx)] }, key));
             }
             case "section": {
                 const sp = this.spacing(density);
@@ -1481,6 +1553,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.6",
   "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",