@flyingrobots/bijou-tui 0.1.0 → 0.2.0

package/README.md

@@ -1,35 +1,50 @@
 # @flyingrobots/bijou-tui
 
-TEA runtime for terminal UIs — model/update/view with keyboard input, alt screen, and layout helpers.
+TEA runtime for terminal UIs — model/update/view with physics-based animation, flexbox layout, declarative keybindings, and a centralized event bus.
 
-Inspired by [Bubble Tea](https://github.com/charmbracelet/bubbletea) (Go), bijou-tui brings The Elm Architecture to TypeScript terminals.
+Inspired by [Bubble Tea](https://github.com/charmbracelet/bubbletea) (Go) and [GSAP](https://gsap.com/) animation.
+
+## What's New in 0.2.0?
+
+- **Industrial-Grade Renderer** — Flicker-free, scroll-safe rendering loop with `WRAP_DISABLE` and `CLEAR_LINE_TO_END` support.
+- **Spring animation engine** — physics-based springs with 6 presets, plus multi-frame emission for 60fps+ fluidity.
+- **`animate()`** — GSAP-style animation commands for TEA, with `onComplete` signals and `immediate: true` for reduced-motion.
+- **`viewport()`** — scrollable content pane with proportional scrollbar and ANSI-aware clipping.
+- **`flex()`** — flexbox layout with grow/basis/min/max, true horizontal centering, and auto-reflow.
+- **`ResizeMsg`** — terminal resize events auto-dispatched by the runtime.
+- **`EventBus`** — centralized typed event emitter unifying keyboard, resize, and multi-message commands.
+- **Keybinding manager** — `createKeyMap()` for declarative key binding with modifiers, named groups, runtime enable/disable.
+- **Help generator** — `helpView()`, `helpShort()`, `helpFor()` auto-generated from registered keybindings.
+- **Input stack** — `createInputStack()` for layered input dispatch with opaque (modal) and passthrough layers.
+
+See the [CHANGELOG](https://github.com/flyingrobots/bijou/blob/main/CHANGELOG.md) for the full release history.
 
 ## Install
 
 ```bash
-npm install @flyingrobots/bijou @flyingrobots/bijou-tui
+npm install @flyingrobots/bijou @flyingrobots/bijou-node @flyingrobots/bijou-tui
 ```
 
 ## Quick Start
 
 ```typescript
+import { initDefaultContext } from '@flyingrobots/bijou-node';
 import { run, quit, tick, type App, type KeyMsg } from '@flyingrobots/bijou-tui';
 
+initDefaultContext();
+
 type Model = { count: number };
 
 const app: App<Model> = {
-  init: () => [{ count: 0 }, tick(1000)],
+  init: () => [{ count: 0 }, []],
 
   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)];
+      if (msg.key === 'q') return [model, [quit()]];
+      if (msg.key === '+') return [{ count: model.count + 1 }, []];
+      if (msg.key === '-') return [{ count: model.count - 1 }, []];
     }
-    return [model, null];
+    return [model, []];
   },
 
   view: (model) => `Count: ${model.count}\n\nPress +/- to change, q to quit`,
@@ -38,35 +53,211 @@ const app: App<Model> = {
 run(app);
 ```
 
-## API
+## Animation
+
+### Spring Physics
+
+```typescript
+import { animate, SPRING_PRESETS } from '@flyingrobots/bijou-tui';
+
+// Physics-based (default) — runs until the spring settles
+const cmd = animate({
+  from: 0,
+  to: 100,
+  spring: 'wobbly',  // or 'default', 'gentle', 'stiff', 'slow', 'molasses'
+  onFrame: (v) => ({ type: 'scroll', y: v }),
+});
+
+// Duration-based with easing
+const fade = animate({
+  type: 'tween',
+  from: 0,
+  to: 1,
+  duration: 300,
+  ease: EASINGS.easeOutCubic,
+  onFrame: (v) => ({ type: 'fade', opacity: v }),
+});
+
+// Skip animation (reduced motion)
+const jump = animate({
+  from: 0, to: 100,
+  immediate: true,
+  onFrame: (v) => ({ type: 'scroll', y: v }),
+});
+```
+
+### Timeline
 
-### Core Types
+GSAP-style orchestration — pure state machine, no timers:
 
-- **`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
+```typescript
+import { timeline } from '@flyingrobots/bijou-tui';
 
-### Commands
+const tl = timeline()
+  .add('slideIn',  { type: 'tween', from: -100, to: 0, duration: 300 })
+  .add('fadeIn',   { type: 'tween', from: 0, to: 1, duration: 200 }, '-=100')
+  .label('settled')
+  .add('bounce',   { from: 0, to: 10, spring: 'wobbly' }, 'settled')
+  .call('onReady', 'settled+=50')
+  .build();
 
-- **`quit()`** — exit the app
-- **`tick(ms)`** — schedule a tick after `ms` milliseconds
-- **`batch(...cmds)`** — combine multiple commands
+// Drive from TEA update:
+let tlState = tl.init();
+// on each frame:
+tlState = tl.step(tlState, 1/60);
+const { slideIn, fadeIn, bounce } = tl.values(tlState);
+const fired = tl.firedCallbacks(prev, tlState); // ['onReady']
+```
+
+Position syntax: `'<'` (parallel), `'+=N'` (gap), `'-=N'` (overlap), `'<+=N'` (offset from previous start), absolute ms, `'label'`, `'label+=N'`.
 
-### Screen Control
+## Layout
 
-- **`enterScreen()` / `exitScreen()`** — alt screen buffer management
-- **`clearAndHome()`** — clear screen and move cursor to top-left
-- **`renderFrame(content)`** — efficient frame rendering
+### Flexbox
 
-### Layout
+```typescript
+import { flex } from '@flyingrobots/bijou-tui';
 
-- **`vstack(...lines)`** — vertical stack (join with newlines)
-- **`hstack(...cols)`** — horizontal stack (side-by-side columns)
+// Sidebar + main content, responsive to terminal width
+flex({ direction: 'row', width: cols, height: rows, gap: 1 },
+  { basis: 20, content: sidebarText },
+  { flex: 1, content: (w, h) => renderMain(w, h) },
+);
 
-### Key Parsing
+// Header + body + footer
+flex({ direction: 'column', width: cols, height: rows },
+  { basis: 1, content: headerLine },
+  { flex: 1, content: (w, h) => renderBody(w, h) },
+  { basis: 1, content: statusLine },
+);
+```
+
+Children can be **render functions** `(width, height) => string` — they receive their allocated space and reflow automatically when the terminal resizes.
+
+### Viewport
+
+```typescript
+import { viewport, createScrollState, scrollBy, pageDown } from '@flyingrobots/bijou-tui';
+
+let scroll = createScrollState(content, viewportHeight);
+
+// Render visible window with scrollbar
+const view = viewport({ width: 60, height: 20, content, scrollY: scroll.y });
+
+// Handle scroll keys
+scroll = scrollBy(scroll, 1);   // down one line
+scroll = pageDown(scroll);       // down one page
+```
+
+### Basic Layout
+
+```typescript
+import { vstack, hstack } from '@flyingrobots/bijou-tui';
+
+vstack(header, content, footer);       // vertical stack
+hstack(2, leftPanel, rightPanel);      // side-by-side with gap
+```
+
+## Resize Handling
+
+Terminal resize events are dispatched automatically as `ResizeMsg`:
+
+```typescript
+update(msg, model) {
+  if (msg.type === 'resize') {
+    return [{ ...model, cols: msg.columns, rows: msg.rows }, []];
+  }
+  // ...
+}
+
+view(model) {
+  return flex(
+    { direction: 'row', width: model.cols, height: model.rows },
+    { basis: 20, content: sidebar },
+    { flex: 1, content: (w, h) => mainContent(w, h) },
+  );
+}
+```
+
+## Event Bus
+
+The runtime uses an `EventBus` internally. You can also create your own for custom event sources:
+
+```typescript
+import { createEventBus } from '@flyingrobots/bijou-tui';
+
+const bus = createEventBus<MyMsg>();
+bus.connectIO(ctx.io);           // keyboard + resize
+bus.on((msg) => { /* ... */ });  // single subscription
+bus.emit(customMsg);             // synthetic events
+bus.runCmd(someCommand);         // command results re-emitted
+bus.dispose();                   // clean shutdown
+```
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full event flow and [GUIDE.md](./GUIDE.md) for detailed usage patterns.
+
+## Keybinding Manager
+
+Declarative key binding with modifier support, named groups, and runtime enable/disable:
+
+```typescript
+import { createKeyMap, type KeyMsg } from '@flyingrobots/bijou-tui';
+
+type Msg = { type: 'quit' } | { type: 'help' } | { type: 'move'; dir: string };
+
+const kb = createKeyMap<Msg>()
+  .bind('q', 'Quit', { type: 'quit' })
+  .bind('?', 'Help', { type: 'help' })
+  .bind('ctrl+c', 'Force quit', { type: 'quit' })
+  .group('Navigation', (g) => g
+    .bind('j', 'Down', { type: 'move', dir: 'down' })
+    .bind('k', 'Up', { type: 'move', dir: 'up' })
+  );
+
+// In TEA update:
+const action = kb.handle(keyMsg);
+if (action !== undefined) return [model, [/* ... */]];
+
+// Runtime enable/disable
+kb.disableGroup('Navigation');
+kb.enable('Quit');
+```
+
+### Help Generation
+
+Auto-generate help text from registered bindings:
+
+```typescript
+import { helpView, helpShort, helpFor } from '@flyingrobots/bijou-tui';
+
+helpView(kb);           // full grouped multi-line help
+helpShort(kb);          // "q Quit • ? Help • Ctrl+c Force quit • j Down • k Up"
+helpFor(kb, 'Nav');     // only Navigation group
+```
+
+### Input Stack
+
+Layered input dispatch for modal UIs — push/pop handlers with opaque or passthrough behavior:
+
+```typescript
+import { createInputStack, type KeyMsg } from '@flyingrobots/bijou-tui';
+
+const stack = createInputStack<KeyMsg, Msg>();
+
+// Base layer — global keys, lets unmatched events fall through
+stack.push(appKeys, { passthrough: true });
+
+// Modal opens — captures all input (opaque by default)
+const modalId = stack.push(modalKeys);
+
+// Dispatch returns first matched action, top-down
+const action = stack.dispatch(keyMsg);
+
+// Modal closes
+stack.remove(modalId);
+```
 
-- **`parseKey(data)`** — parse raw stdin bytes into a `KeyMsg`
+`KeyMap` implements `InputHandler`, so it plugs directly into the input stack.
 
 ## Related Packages
 

package/dist/animate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TEA-integrated animation commands.
+ *
+ * GSAP-style API: `animate()` returns a `Cmd` that fires `onFrame`
+ * messages as the animation progresses, fitting naturally into the
+ * TEA update cycle.
+ *
+ * Two animation modes:
+ *   - **spring**: Physics-based (default). No fixed duration — runs until
+ *     the spring settles. Use for organic, responsive motion.
+ *   - **tween**: Duration-based with easing curves. Use for predictable,
+ *     timed transitions.
+ *
+ * Both modes support `immediate: true` to skip animation and jump to
+ * the target value in a single frame.
+ */
+import type { Cmd } from './types.js';
+import { type SpringConfig, type SpringPreset, type EasingFn } from './spring.js';
+interface AnimateBase<M> {
+    /** Starting value. */
+    readonly from: number;
+    /** Target value. */
+    readonly to: number;
+    /** Frames per second. Default: 60. */
+    readonly fps?: number;
+    /** Skip animation — jump to target in one frame. Default: false. */
+    readonly immediate?: boolean;
+    /** Called each frame with the interpolated value. Return a message for TEA. */
+    readonly onFrame: (value: number) => M;
+    /** Optional message to emit when the animation is fully complete. */
+    readonly onComplete?: () => M;
+}
+export interface SpringAnimateOptions<M> extends AnimateBase<M> {
+    readonly type?: 'spring';
+    /** Spring config — preset name or custom values. */
+    readonly spring?: Partial<SpringConfig> | SpringPreset;
+}
+export interface TweenAnimateOptions<M> extends AnimateBase<M> {
+    readonly type: 'tween';
+    /** Duration in milliseconds. */
+    readonly duration: number;
+    /** Easing function. Default: easeOutCubic. */
+    readonly ease?: EasingFn;
+}
+export type AnimateOptions<M> = SpringAnimateOptions<M> | TweenAnimateOptions<M>;
+/**
+ * Create a TEA command that drives an animation.
+ *
+ * Spring mode (default):
+ * ```ts
+ * animate({ from: 0, to: 100, spring: 'wobbly', onFrame: (v) => ({ type: 'scroll', y: v }) })
+ * ```
+ */
+export declare function animate<M>(options: AnimateOptions<M>): Cmd<M>;
+/**
+ * Run animations in sequence. Each animation completes before the next starts.
+ */
+export declare function sequence<M>(...cmds: Cmd<M>[]): Cmd<M>;
+export {};
+//# sourceMappingURL=animate.d.ts.map

package/dist/animate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animate.d.ts","sourceRoot":"","sources":["../src/animate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,QAAQ,EAQd,MAAM,aAAa,CAAC;AAMrB,UAAU,WAAW,CAAC,CAAC;IACrB,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;CACxD;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAMjF;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAiB7D;AAsED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAMrD"}

package/dist/animate.js

@@ -0,0 +1,98 @@
+/**
+ * TEA-integrated animation commands.
+ *
+ * GSAP-style API: `animate()` returns a `Cmd` that fires `onFrame`
+ * messages as the animation progresses, fitting naturally into the
+ * TEA update cycle.
+ *
+ * Two animation modes:
+ *   - **spring**: Physics-based (default). No fixed duration — runs until
+ *     the spring settles. Use for organic, responsive motion.
+ *   - **tween**: Duration-based with easing curves. Use for predictable,
+ *     timed transitions.
+ *
+ * Both modes support `immediate: true` to skip animation and jump to
+ * the target value in a single frame.
+ */
+import { springStep, createSpringState, resolveSpringConfig, tweenStep, createTweenState, resolveTweenConfig, EASINGS, } from './spring.js';
+// ---------------------------------------------------------------------------
+// animate() — the main API
+// ---------------------------------------------------------------------------
+/**
+ * Create a TEA command that drives an animation.
+ *
+ * Spring mode (default):
+ * ```ts
+ * animate({ from: 0, to: 100, spring: 'wobbly', onFrame: (v) => ({ type: 'scroll', y: v }) })
+ * ```
+ */
+export function animate(options) {
+    const { from, to, fps = 60, immediate = false, onFrame, onComplete } = options;
+    // Immediate mode — single frame, no physics
+    if (immediate) {
+        return async (emit) => {
+            emit(onFrame(to));
+            if (onComplete)
+                emit(onComplete());
+        };
+    }
+    if (options.type === 'tween') {
+        return createTweenCmd(from, to, options.duration, options.ease ?? EASINGS.easeOutCubic, fps, onFrame, onComplete);
+    }
+    const config = resolveSpringConfig(options.spring);
+    return createSpringCmd(from, to, config, fps, onFrame, onComplete);
+}
+// ---------------------------------------------------------------------------
+// Internal: spring command
+// ---------------------------------------------------------------------------
+function createSpringCmd(from, to, config, fps, onFrame, onComplete) {
+    return (emit) => new Promise((resolve) => {
+        let state = createSpringState(from);
+        const dt = 1 / fps;
+        const intervalMs = Math.round(1000 / fps);
+        const id = setInterval(() => {
+            state = springStep(state, to, config, dt);
+            emit(onFrame(state.value));
+            if (state.done) {
+                clearInterval(id);
+                if (onComplete)
+                    emit(onComplete());
+                resolve();
+            }
+        }, intervalMs);
+    });
+}
+// ---------------------------------------------------------------------------
+// Internal: tween command
+// ---------------------------------------------------------------------------
+function createTweenCmd(from, to, duration, ease, fps, onFrame, onComplete) {
+    const config = resolveTweenConfig({ from, to, duration, ease });
+    return (emit) => new Promise((resolve) => {
+        let state = createTweenState(from);
+        const intervalMs = Math.round(1000 / fps);
+        const id = setInterval(() => {
+            state = tweenStep(state, config, intervalMs);
+            emit(onFrame(state.value));
+            if (state.done) {
+                clearInterval(id);
+                if (onComplete)
+                    emit(onComplete());
+                resolve();
+            }
+        }, intervalMs);
+    });
+}
+// ---------------------------------------------------------------------------
+// sequence() — chain animations like a GSAP timeline
+// ---------------------------------------------------------------------------
+/**
+ * Run animations in sequence. Each animation completes before the next starts.
+ */
+export function sequence(...cmds) {
+    return async (emit) => {
+        for (const cmd of cmds) {
+            await cmd(emit);
+        }
+    };
+}
+//# sourceMappingURL=animate.js.map

package/dist/animate.js.map

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

package/dist/commands.d.ts.map

@@ -1 +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"}
+{"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,CAKlD;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

@@ -1,11 +1,11 @@
 import { QUIT } from './types.js';
 /** Command that signals the runtime to quit. */
 export function quit() {
-    return () => Promise.resolve(QUIT);
+    return async (_emit) => QUIT;
 }
 /** Command that delivers a message after a delay (one-shot). */
 export function tick(ms, msg) {
-    return () => new Promise((resolve) => {
+    return (_emit) => new Promise((resolve) => {
         setTimeout(() => resolve(msg), ms);
     });
 }

package/dist/commands.js.map

@@ -1 +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"}
+{"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,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,IAAkB,CAAC;AAC7C,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,IAAI,CAAI,EAAU,EAAE,GAAM;IACxC,OAAO,CAAC,KAAK,EAAE,EAAE,CACf,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,EAAE;QACzB,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;AACP,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,KAAK,CAAI,GAAG,IAAc;IACxC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/eventbus.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Centralized event bus for TUI applications.
+ *
+ * Unifies all input sources (keyboard, resize, commands, custom) into
+ * a single typed event stream. The TEA runtime subscribes to the bus
+ * instead of manually wiring callbacks.
+ *
+ * ```ts
+ * const bus = createEventBus<Msg>();
+ *
+ * // Connect I/O sources (keyboard + resize)
+ * bus.connectIO(ctx.io);
+ *
+ * // Subscribe to all events
+ * bus.on((msg) => {
+ *   const [model, cmds] = app.update(msg, model);
+ *   cmds.forEach(cmd => bus.runCmd(cmd));
+ * });
+ *
+ * // Emit custom events
+ * bus.emit({ type: 'tick' });
+ *
+ * // In tests — emit directly, no I/O needed
+ * bus.emit({ type: 'key', key: 'a', ctrl: false, alt: false, shift: false });
+ * ```
+ */
+import type { IOPort } from '@flyingrobots/bijou';
+import type { Cmd, KeyMsg, ResizeMsg } from './types.js';
+/** Any message the bus can carry — built-in or app-defined. */
+export type BusMsg<M> = KeyMsg | ResizeMsg | M;
+export interface EventBus<M> {
+    /**
+     * Subscribe to all events. Returns a dispose function.
+     * Multiple subscribers are supported — all receive every event.
+     */
+    on(handler: (msg: BusMsg<M>) => void): Disposable;
+    /** Emit a message to all subscribers. */
+    emit(msg: BusMsg<M>): void;
+    /**
+     * Connect keyboard and resize sources from an IOPort.
+     * Raw stdin bytes are parsed into KeyMsg automatically.
+     * Returns a dispose function that disconnects both.
+     */
+    connectIO(io: IOPort): Disposable;
+    /**
+     * Run a command. The command receives the bus's `emit` function to
+     * dispatch intermediate messages during execution. When it resolves:
+     * - QUIT signal → fires onQuit handlers
+     * - Message → emitted to all subscribers
+     * - void/undefined → ignored
+     *
+     * Rejected commands are logged to stderr via `console.error`.
+     */
+    runCmd(cmd: Cmd<M>): void;
+    /**
+     * Register a quit handler. Called when a command resolves to QUIT.
+     * Separate from `on()` so the runtime can handle shutdown without
+     * the app needing to filter for it.
+     */
+    onQuit(handler: () => void): Disposable;
+    /** Disconnect all sources and remove all subscribers. */
+    dispose(): void;
+}
+interface Disposable {
+    dispose(): void;
+}
+export declare function createEventBus<M>(): EventBus<M>;
+export {};
+//# sourceMappingURL=eventbus.d.ts.map

package/dist/eventbus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventbus.d.ts","sourceRoot":"","sources":["../src/eventbus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQzD,+DAA+D;AAC/D,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC;AAE/C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB;;;OAGG;IACH,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,UAAU,CAAC;IAElD,yCAAyC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAAC;IAElC;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE1B;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;IAExC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,UAAU,UAAU;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD,wBAAgB,cAAc,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CA0F/C"}