@flyingrobots/bijou-tui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flying Robots
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @flyingrobots/bijou-tui
+
+TEA runtime for terminal UIs — model/update/view with keyboard input, alt screen, and layout helpers.
+
+Inspired by [Bubble Tea](https://github.com/charmbracelet/bubbletea) (Go), bijou-tui brings The Elm Architecture to TypeScript terminals.
+
+## Install
+
+```bash
+npm install @flyingrobots/bijou @flyingrobots/bijou-tui
+```
+
+## Quick Start
+
+```typescript
+import { run, quit, tick, type App, type KeyMsg } from '@flyingrobots/bijou-tui';
+
+type Model = { count: number };
+
+const app: App<Model> = {
+  init: () => [{ count: 0 }, tick(1000)],
+
+  update: (msg, model) => {
+    if (msg.type === 'key') {
+      if (msg.key === 'q') return [model, quit()];
+      if (msg.key === '+') return [{ count: model.count + 1 }, null];
+      if (msg.key === '-') return [{ count: model.count - 1 }, null];
+    }
+    if (msg.type === 'tick') {
+      return [model, tick(1000)];
+    }
+    return [model, null];
+  },
+
+  view: (model) => `Count: ${model.count}\n\nPress +/- to change, q to quit`,
+};
+
+run(app);
+```
+
+## API
+
+### Core Types
+
+- **`App<M>`** — defines `init`, `update(msg, model)`, and `view(model)` functions
+- **`KeyMsg`** — keyboard input message with `key`, `ctrl`, `shift`, `alt` fields
+- **`Cmd`** — side-effect commands returned from `update`
+- **`QUIT`** — sentinel value to signal app termination
+
+### Commands
+
+- **`quit()`** — exit the app
+- **`tick(ms)`** — schedule a tick after `ms` milliseconds
+- **`batch(...cmds)`** — combine multiple commands
+
+### Screen Control
+
+- **`enterScreen()` / `exitScreen()`** — alt screen buffer management
+- **`clearAndHome()`** — clear screen and move cursor to top-left
+- **`renderFrame(content)`** — efficient frame rendering
+
+### Layout
+
+- **`vstack(...lines)`** — vertical stack (join with newlines)
+- **`hstack(...cols)`** — horizontal stack (side-by-side columns)
+
+### Key Parsing
+
+- **`parseKey(data)`** — parse raw stdin bytes into a `KeyMsg`
+
+## Related Packages
+
+- [`@flyingrobots/bijou`](https://www.npmjs.com/package/@flyingrobots/bijou) — Zero-dependency core with all components and theme engine
+- [`@flyingrobots/bijou-node`](https://www.npmjs.com/package/@flyingrobots/bijou-node) — Node.js runtime adapter (chalk, readline, process)
+
+## License
+
+MIT

package/dist/commands.d.ts

@@ -0,0 +1,8 @@
+import { type Cmd } from './types.js';
+/** Command that signals the runtime to quit. */
+export declare function quit<M>(): Cmd<M>;
+/** Command that delivers a message after a delay (one-shot). */
+export declare function tick<M>(ms: number, msg: M): Cmd<M>;
+/** Convenience: group multiple commands into an array. */
+export declare function batch<M>(...cmds: Cmd<M>[]): Cmd<M>[];
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,GAAG,EAAmB,MAAM,YAAY,CAAC;AAE7D,gDAAgD;AAChD,wBAAgB,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAEhC;AAED,gEAAgE;AAChE,wBAAgB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAIlD;AAED,0DAA0D;AAC1D,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAEpD"}

package/dist/commands.js

@@ -0,0 +1,16 @@
+import { QUIT } from './types.js';
+/** Command that signals the runtime to quit. */
+export function quit() {
+    return () => Promise.resolve(QUIT);
+}
+/** Command that delivers a message after a delay (one-shot). */
+export function tick(ms, msg) {
+    return () => new Promise((resolve) => {
+        setTimeout(() => resolve(msg), ms);
+    });
+}
+/** Convenience: group multiple commands into an array. */
+export function batch(...cmds) {
+    return cmds;
+}
+//# sourceMappingURL=commands.js.map

package/dist/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAA6B,MAAM,YAAY,CAAC;AAE7D,gDAAgD;AAChD,MAAM,UAAU,IAAI;IAClB,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAkB,CAAC,CAAC;AACnD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,IAAI,CAAI,EAAU,EAAE,GAAM;IACxC,OAAO,GAAG,EAAE,CAAC,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,EAAE;QACtC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,KAAK,CAAI,GAAG,IAAc;IACxC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { App, Cmd, KeyMsg, QuitSignal, RunOptions } from './types.js';
+export { QUIT } from './types.js';
+export { parseKey } from './keys.js';
+export { enterScreen, exitScreen, clearAndHome, renderFrame, ENTER_ALT_SCREEN, EXIT_ALT_SCREEN, HIDE_CURSOR, SHOW_CURSOR, CLEAR_SCREEN, CLEAR_TO_END, CLEAR_LINE, HOME, } from './screen.js';
+export { quit, tick, batch } from './commands.js';
+export { run } from './runtime.js';
+export { vstack, hstack } from './layout.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGrC,OAAO,EACL,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,IAAI,GACL,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAGlD,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGnC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export { QUIT } from './types.js';
+// Key parsing
+export { parseKey } from './keys.js';
+// Screen control
+export { enterScreen, exitScreen, clearAndHome, renderFrame, ENTER_ALT_SCREEN, EXIT_ALT_SCREEN, HIDE_CURSOR, SHOW_CURSOR, CLEAR_SCREEN, CLEAR_TO_END, CLEAR_LINE, HOME, } from './screen.js';
+// Commands
+export { quit, tick, batch } from './commands.js';
+// Runtime
+export { run } from './runtime.js';
+// Layout
+export { vstack, hstack } from './layout.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAElC,cAAc;AACd,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC,iBAAiB;AACjB,OAAO,EACL,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,IAAI,GACL,MAAM,aAAa,CAAC;AAErB,WAAW;AACX,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAElD,UAAU;AACV,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,SAAS;AACT,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,7 @@
+import type { KeyMsg } from './types.js';
+/**
+ * Parse a raw ANSI byte string from rawInput() into a structured KeyMsg.
+ * Unrecognized sequences produce { key: 'unknown' }.
+ */
+export declare function parseKey(raw: string): KeyMsg;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2C5C"}

package/dist/keys.js

@@ -0,0 +1,62 @@
+function keyMsg(key, ctrl = false, alt = false, shift = false) {
+    return { type: 'key', key, ctrl, alt, shift };
+}
+/**
+ * Parse a raw ANSI byte string from rawInput() into a structured KeyMsg.
+ * Unrecognized sequences produce { key: 'unknown' }.
+ */
+export function parseKey(raw) {
+    // Arrow keys and other CSI sequences
+    if (raw === '\x1b[A')
+        return keyMsg('up');
+    if (raw === '\x1b[B')
+        return keyMsg('down');
+    if (raw === '\x1b[C')
+        return keyMsg('right');
+    if (raw === '\x1b[D')
+        return keyMsg('left');
+    if (raw === '\x1b[H')
+        return keyMsg('home');
+    if (raw === '\x1b[F')
+        return keyMsg('end');
+    if (raw === '\x1b[3~')
+        return keyMsg('delete');
+    if (raw === '\x1b[5~')
+        return keyMsg('pageup');
+    if (raw === '\x1b[6~')
+        return keyMsg('pagedown');
+    // Enter, tab, backspace, space, escape
+    if (raw === '\r' || raw === '\n')
+        return keyMsg('enter');
+    if (raw === '\t')
+        return keyMsg('tab');
+    if (raw === '\x1b[Z')
+        return keyMsg('tab', false, false, true); // shift-tab
+    if (raw === '\x7f')
+        return keyMsg('backspace');
+    if (raw === ' ')
+        return keyMsg('space');
+    // Escape (alone)
+    if (raw === '\x1b')
+        return keyMsg('escape');
+    // Ctrl+C
+    if (raw === '\x03')
+        return keyMsg('c', true);
+    // Ctrl+A through Ctrl+Z (0x01-0x1a), excluding already-handled cases
+    if (raw.length === 1) {
+        const code = raw.charCodeAt(0);
+        if (code >= 0x01 && code <= 0x1a) {
+            const letter = String.fromCharCode(code + 0x60); // 0x01 → 'a', 0x02 → 'b', etc.
+            return keyMsg(letter, true);
+        }
+    }
+    // Printable single characters
+    if (raw.length === 1) {
+        const code = raw.charCodeAt(0);
+        if (code >= 0x20 && code <= 0x7e) {
+            return keyMsg(raw);
+        }
+    }
+    return keyMsg('unknown');
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAEA,SAAS,MAAM,CAAC,GAAW,EAAE,IAAI,GAAG,KAAK,EAAE,GAAG,GAAG,KAAK,EAAE,KAAK,GAAG,KAAK;IACnE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,qCAAqC;IACrC,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;IAEjD,uCAAuC;IACvC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY;IAC5E,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAExC,iBAAiB;IACjB,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE5C,SAAS;IACT,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAE7C,qEAAqE;IACrE,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,+BAA+B;YAChF,OAAO,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3B,CAAC"}

package/dist/layout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Vertical stack — join blocks with newlines.
+ * Filters out empty strings.
+ */
+export declare function vstack(...blocks: string[]): string;
+/**
+ * Horizontal stack — place blocks side by side with a gap between columns.
+ * Pads shorter blocks with empty lines to align rows.
+ */
+export declare function hstack(gap: number, ...blocks: string[]): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAwB/D"}

package/dist/layout.js

@@ -0,0 +1,44 @@
+/**
+ * Vertical stack — join blocks with newlines.
+ * Filters out empty strings.
+ */
+export function vstack(...blocks) {
+    return blocks.filter((b) => b !== '').join('\n');
+}
+/**
+ * Horizontal stack — place blocks side by side with a gap between columns.
+ * Pads shorter blocks with empty lines to align rows.
+ */
+export function hstack(gap, ...blocks) {
+    if (blocks.length === 0)
+        return '';
+    if (blocks.length === 1)
+        return blocks[0];
+    const split = blocks.map((b) => b.split('\n'));
+    const maxRows = Math.max(...split.map((lines) => lines.length));
+    const widths = split.map((lines) => Math.max(...lines.map(visualWidth)));
+    const spacer = ' '.repeat(gap);
+    const rows = [];
+    for (let r = 0; r < maxRows; r++) {
+        const parts = [];
+        for (let c = 0; c < split.length; c++) {
+            const line = split[c][r] ?? '';
+            // Last column doesn't need right-padding
+            if (c < split.length - 1) {
+                parts.push(line + ' '.repeat(widths[c] - visualWidth(line)));
+            }
+            else {
+                parts.push(line);
+            }
+        }
+        rows.push(parts.join(spacer).trimEnd());
+    }
+    return rows.join('\n');
+}
+/** Width of a string with ANSI escapes stripped. */
+function visualWidth(s) {
+    // Strip ANSI escape sequences
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,GAAG,MAAgB;IACxC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,GAAG,MAAgB;IACrD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAE,CAAC;IAE3C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAE/B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAChC,yCAAyC;YACzC,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChE,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,oDAAoD;AACpD,SAAS,WAAW,CAAC,CAAS;IAC5B,8BAA8B;IAC9B,4CAA4C;IAC5C,OAAO,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;AACjD,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,10 @@
+import type { App, RunOptions } from './types.js';
+/**
+ * Run a TEA application.
+ *
+ * In non-interactive modes (pipe/static/accessible), renders the initial view
+ * once and exits. In interactive mode, enters the alt screen, starts the
+ * keyboard event loop, and drives the model/update/view cycle.
+ */
+export declare function run<Model, M>(app: App<Model, M>, options?: RunOptions): Promise<void>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAe,UAAU,EAAE,MAAM,YAAY,CAAC;AAW/D;;;;;;GAMG;AACH,wBAAsB,GAAG,CAAC,KAAK,EAAE,CAAC,EAChC,GAAG,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAsGf"}

package/dist/runtime.js

@@ -0,0 +1,110 @@
+import { getDefaultContext } from '@flyingrobots/bijou';
+import { QUIT } from './types.js';
+import { parseKey } from './keys.js';
+import { enterScreen, exitScreen, renderFrame } from './screen.js';
+/**
+ * Disable mouse reporting sequences that terminals may send.
+ * Some terminals auto-enable mouse tracking in alt screen mode.
+ */
+const DISABLE_MOUSE = '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l';
+/**
+ * Run a TEA application.
+ *
+ * In non-interactive modes (pipe/static/accessible), renders the initial view
+ * once and exits. In interactive mode, enters the alt screen, starts the
+ * keyboard event loop, and drives the model/update/view cycle.
+ */
+export async function run(app, options) {
+    const ctx = options?.ctx ?? getDefaultContext();
+    const useAltScreen = options?.altScreen ?? true;
+    const useHideCursor = options?.hideCursor ?? true;
+    const [initModel, initCmds] = app.init();
+    // Non-interactive: render once and return
+    if (ctx.mode !== 'interactive') {
+        ctx.io.write(app.view(initModel));
+        return;
+    }
+    // Interactive mode
+    let model = initModel;
+    let running = true;
+    let lastCtrlC = 0;
+    let resolveQuit = null;
+    function shutdown() {
+        if (!running)
+            return;
+        running = false;
+        if (resolveQuit)
+            resolveQuit();
+    }
+    // Setup screen
+    if (useAltScreen || useHideCursor) {
+        enterScreen(ctx.io);
+    }
+    // Disable mouse reporting to avoid garbage from mouse events
+    ctx.io.write(DISABLE_MOUSE);
+    // Render helper
+    function render() {
+        if (!running)
+            return;
+        renderFrame(ctx.io, app.view(model));
+    }
+    // Message handler
+    function handleMsg(msg) {
+        if (!running)
+            return;
+        const [newModel, cmds] = app.update(msg, model);
+        model = newModel;
+        render();
+        executeCommands(cmds);
+    }
+    // Execute commands, feeding results back as messages
+    function executeCommands(cmds) {
+        for (const cmd of cmds) {
+            void cmd().then((result) => {
+                if (result === QUIT) {
+                    shutdown();
+                    return;
+                }
+                if (result !== undefined) {
+                    handleMsg(result);
+                }
+            });
+        }
+    }
+    // Initial render
+    render();
+    // Execute startup commands
+    executeCommands(initCmds);
+    // Start keyboard listener
+    const inputHandle = ctx.io.rawInput((raw) => {
+        if (!running)
+            return;
+        const keyMsg = parseKey(raw);
+        // Skip unknown sequences (mouse events, etc.)
+        if (keyMsg.key === 'unknown')
+            return;
+        // Double Ctrl+C force-quit
+        if (keyMsg.key === 'c' && keyMsg.ctrl) {
+            const now = Date.now();
+            if (now - lastCtrlC < 1000) {
+                shutdown();
+                return;
+            }
+            lastCtrlC = now;
+        }
+        handleMsg(keyMsg);
+    });
+    // Wait for quit signal
+    await new Promise((resolve) => {
+        resolveQuit = resolve;
+        // In case shutdown was already called before we got here
+        if (!running)
+            resolve();
+    });
+    // Cleanup
+    inputHandle.dispose();
+    if (useAltScreen || useHideCursor) {
+        exitScreen(ctx.io);
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/screen.d.ts

@@ -0,0 +1,21 @@
+import type { IOPort } from '@flyingrobots/bijou';
+export declare const ENTER_ALT_SCREEN = "\u001B[?1049h";
+export declare const EXIT_ALT_SCREEN = "\u001B[?1049l";
+export declare const HIDE_CURSOR = "\u001B[?25l";
+export declare const SHOW_CURSOR = "\u001B[?25h";
+export declare const CLEAR_SCREEN = "\u001B[2J";
+export declare const CLEAR_TO_END = "\u001B[J";
+export declare const HOME = "\u001B[H";
+export declare const CLEAR_LINE = "\u001B[2K";
+/** Enter alt screen buffer, hide cursor, and clear screen. */
+export declare function enterScreen(io: IOPort): void;
+/** Show cursor and exit alt screen buffer. */
+export declare function exitScreen(io: IOPort): void;
+/** Clear screen and move cursor to home position. */
+export declare function clearAndHome(io: IOPort): void;
+/**
+ * Flicker-free render: move cursor home, write content line-by-line
+ * (clearing each line first), then erase everything below.
+ */
+export declare function renderFrame(io: IOPort, content: string): void;
+//# sourceMappingURL=screen.d.ts.map

package/dist/screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,eAAO,MAAM,gBAAgB,kBAAgB,CAAC;AAC9C,eAAO,MAAM,eAAe,kBAAgB,CAAC;AAC7C,eAAO,MAAM,WAAW,gBAAc,CAAC;AACvC,eAAO,MAAM,WAAW,gBAAc,CAAC;AACvC,eAAO,MAAM,YAAY,cAAY,CAAC;AACtC,eAAO,MAAM,YAAY,aAAW,CAAC;AACrC,eAAO,MAAM,IAAI,aAAW,CAAC;AAC7B,eAAO,MAAM,UAAU,cAAY,CAAC;AAEpC,8DAA8D;AAC9D,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,qDAAqD;AACrD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ7D"}

package/dist/screen.js

@@ -0,0 +1,34 @@
+export const ENTER_ALT_SCREEN = '\x1b[?1049h';
+export const EXIT_ALT_SCREEN = '\x1b[?1049l';
+export const HIDE_CURSOR = '\x1b[?25l';
+export const SHOW_CURSOR = '\x1b[?25h';
+export const CLEAR_SCREEN = '\x1b[2J';
+export const CLEAR_TO_END = '\x1b[J';
+export const HOME = '\x1b[H';
+export const CLEAR_LINE = '\x1b[2K';
+/** Enter alt screen buffer, hide cursor, and clear screen. */
+export function enterScreen(io) {
+    io.write(ENTER_ALT_SCREEN + HIDE_CURSOR + CLEAR_SCREEN + HOME);
+}
+/** Show cursor and exit alt screen buffer. */
+export function exitScreen(io) {
+    io.write(SHOW_CURSOR + EXIT_ALT_SCREEN);
+}
+/** Clear screen and move cursor to home position. */
+export function clearAndHome(io) {
+    io.write(CLEAR_SCREEN + HOME);
+}
+/**
+ * Flicker-free render: move cursor home, write content line-by-line
+ * (clearing each line first), then erase everything below.
+ */
+export function renderFrame(io, content) {
+    const lines = content.split('\n');
+    let frame = HOME;
+    for (const line of lines) {
+        frame += CLEAR_LINE + line + '\n';
+    }
+    frame += CLEAR_TO_END;
+    io.write(frame);
+}
+//# sourceMappingURL=screen.js.map

package/dist/screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.js","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAC9C,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAC7C,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AACvC,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC;AACtC,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;AACrC,MAAM,CAAC,MAAM,IAAI,GAAG,QAAQ,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,SAAS,CAAC;AAEpC,8DAA8D;AAC9D,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,EAAE,CAAC,KAAK,CAAC,gBAAgB,GAAG,WAAW,GAAG,YAAY,GAAG,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,EAAE,CAAC,KAAK,CAAC,WAAW,GAAG,eAAe,CAAC,CAAC;AAC1C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,EAAE,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,OAAe;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,IAAI,UAAU,GAAG,IAAI,GAAG,IAAI,CAAC;IACpC,CAAC;IACD,KAAK,IAAI,YAAY,CAAC;IACtB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAClB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,22 @@
+import type { BijouContext } from '@flyingrobots/bijou';
+export interface KeyMsg {
+    readonly type: 'key';
+    readonly key: string;
+    readonly ctrl: boolean;
+    readonly alt: boolean;
+    readonly shift: boolean;
+}
+export declare const QUIT: unique symbol;
+export type QuitSignal = typeof QUIT;
+export type Cmd<M> = () => Promise<M | QuitSignal | void>;
+export interface App<Model, M = never> {
+    init(): [Model, Cmd<M>[]];
+    update(msg: KeyMsg | M, model: Model): [Model, Cmd<M>[]];
+    view(model: Model): string;
+}
+export interface RunOptions {
+    altScreen?: boolean;
+    hideCursor?: boolean;
+    ctx?: BijouContext;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAID,eAAO,MAAM,IAAI,EAAE,OAAO,MAAuB,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC;AAErC,MAAM,MAAM,GAAG,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,GAAG,UAAU,GAAG,IAAI,CAAC,CAAC;AAI1D,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,KAAK;IACnC,IAAI,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;CAC5B;AAID,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// --- Commands ---
+export const QUIT = Symbol('QUIT');
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAYA,mBAAmB;AAEnB,MAAM,CAAC,MAAM,IAAI,GAAkB,MAAM,CAAC,MAAM,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@flyingrobots/bijou-tui",
+  "version": "0.1.0",
+  "description": "TEA runtime for terminal UIs — model/update/view with keyboard input, alt screen, and layout helpers.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "tsc -b",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@flyingrobots/bijou": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "cli",
+    "terminal",
+    "tui",
+    "bijou",
+    "tea",
+    "elm-architecture",
+    "interactive"
+  ],
+  "author": "James Ross <james@flyingrobots.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flyingrobots/bijou.git",
+    "directory": "packages/bijou-tui"
+  },
+  "homepage": "https://github.com/flyingrobots/bijou",
+  "bugs": "https://github.com/flyingrobots/bijou/issues",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}