@flyingrobots/bijou-tui 1.2.0 → 1.4.0

package/README.md

@@ -4,14 +4,24 @@ TEA runtime for terminal UIs — model/update/view with physics-based animation,
 
 Inspired by [Bubble Tea](https://github.com/charmbracelet/bubbletea) (Go) and [GSAP](https://gsap.com/) animation.
 
-## What's New in 0.6.0?
+## What's New (v1.3.0 Snapshot)?
 
-- **`navigableTable()`** — keyboard-navigable table with focus management, vertical scrolling, and vim-style keybindings
-- **`browsableList()`** — navigable list with focus tracking, scroll viewport, descriptions, and convenience keymap
-- **`filePicker()`** — directory browser with focus navigation, extension filtering, and `IOPort` integration
+- **`splitPane()`** — ratio-based split layout with pure reducers and deterministic rect introspection.
+- **`grid()`** — fixed + fractional track solver with named areas and stable layout geometry.
+- **`createFramedApp()`** — shell scaffolding for tabs, pane focus/scroll isolation, help, overlays, and command palette.
+- **`drawer()` upgrades** — supports `left`/`right`/`top`/`bottom` anchors and optional panel `region` mounting.
+- **`runScript()` upgrades** — scripted driver now supports key, resize, and custom-message steps for richer integration harnesses.
 
 See the [CHANGELOG](https://github.com/flyingrobots/bijou/blob/main/docs/CHANGELOG.md) for the full release history.
 
+## Documentation Status
+
+This npm README is a quick overview and may lag behind the repository.
+
+- Canonical API details and behavior notes live in [`GUIDE.md`](./GUIDE.md)
+- End-to-end examples live in [`/examples`](https://github.com/flyingrobots/bijou/tree/main/examples)
+- Release-level changes live in the [CHANGELOG](https://github.com/flyingrobots/bijou/blob/main/docs/CHANGELOG.md)
+
 ## Install
 
 ```bash
@@ -46,6 +56,25 @@ const app: App<Model> = {
 run(app);
 ```
 
+## Runtime Behavior Note
+
+`run()` behaves differently by output mode:
+
+- `interactive`: full TEA loop (event bus, key/resize/mouse handling, command-driven updates).
+- `pipe` / `static` / `accessible`: render `view(initModel)` once and return immediately.
+
+In non-interactive modes, there is no normal interactive event loop.
+
+## Features Breakdown
+
+- **TEA runtime core**: deterministic model/update/view loop with command-driven side effects.
+- **Motion system**: spring physics, tweens, and timeline sequencing for orchestrated terminal animation.
+- **Layout engine**: flexbox helpers, stacks, split panes, named-area grids, viewport scrolling, and resize-aware rendering.
+- **Input architecture**: keymaps, grouped bindings, generated help views, and layered input stack for modal flows.
+- **Overlay composition**: modal, toast, drawer, tooltip, and painter-style compositing primitives (including panel-scoped drawers).
+- **App shell**: `createFramedApp()` for tabs/help/chrome/pane-focus boilerplate with optional command palette.
+- **Stateful building blocks**: navigable table, browsable list, file picker, focus area, and DAG pane with vim-friendly keymaps.
+
 ## Animation
 
 ### Spring Physics
@@ -151,6 +180,56 @@ vstack(header, content, footer);       // vertical stack
 hstack(2, leftPanel, rightPanel);      // side-by-side with gap
 ```
 
+### Split Pane
+
+```typescript
+import {
+  createSplitPaneState, splitPane, splitPaneResizeBy, splitPaneFocusNext,
+} from '@flyingrobots/bijou-tui';
+
+let state = createSplitPaneState({ ratio: 0.35 });
+
+// in update:
+state = splitPaneResizeBy(state, 2, { total: cols, minA: 16, minB: 16 });
+state = splitPaneFocusNext(state);
+
+// in view:
+const output = splitPane(state, {
+  direction: 'row',
+  width: cols,
+  height: rows,
+  minA: 16,
+  minB: 16,
+  paneA: (w, h) => renderSidebar(w, h),
+  paneB: (w, h) => renderMain(w, h),
+});
+```
+
+### Grid
+
+```typescript
+import { grid } from '@flyingrobots/bijou-tui';
+
+const output = grid({
+  width: cols,
+  height: rows,
+  columns: [24, '1fr'],
+  rows: [3, '1fr', 8],
+  areas: [
+    'header header',
+    'nav main',
+    'logs main',
+  ],
+  gap: 1,
+  cells: {
+    header: (w, h) => renderHeader(w, h),
+    nav: (w, h) => renderNav(w, h),
+    logs: (w, h) => renderLogs(w, h),
+    main: (w, h) => renderMain(w, h),
+  },
+});
+```
+
 ## Resize Handling
 
 Terminal resize events are dispatched automatically as `ResizeMsg`:
@@ -283,6 +362,19 @@ const output = composite(backgroundView, [dialog, notification], { dim: true });
 
 Each overlay is a `{ content, row, col }` object. `composite()` splices them onto the background using painter's algorithm (last overlay wins on overlap). The `dim` option fades the background with ANSI dim.
 
+`drawer()` now supports `left`/`right`/`top`/`bottom` anchors and optional `region` mounting for panel-scoped overlays.
+
+## App Frame
+
+`createFramedApp()` wraps page-level TEA logic in a shared shell:
+
+- tabs + page switching
+- pane focus and per-pane scroll isolation
+- frame help (`?`) and optional command palette (`ctrl+p` / `:`)
+- overlay factory with pane rects for panel-scoped drawers/modals
+
+See `examples/release-workbench/main.ts` for the canonical shell demo and `examples/app-frame/main.ts` for a compact focused example.
+
 ## Building Blocks
 
 Reusable stateful components that follow the TEA state + pure transformers + sync render + convenience keymap pattern:
@@ -361,3 +453,24 @@ All building blocks include `*KeyMap()` factories for preconfigured vim-style ke
 ## License
 
 MIT
+
+---
+
+<p align="center">
+Built with 💎 by <a href="https://github.com/flyingrobots">FLYING ROBOTS</a>
+</p>
+
+```rust
+.-:::::':::   .-:.     ::-.::::::.    :::.  .,-:::::/
+;;;'''' ;;;    ';;.   ;;;;';;;`;;;;,  `;;;,;;-'````'
+[[[,,== [[[      '[[,[[['  [[[  [[[[[. '[[[[[   [[[[[[/
+`$$$"`` $$'        c$$"    $$$  $$$ "Y$c$$"$$c.    "$$
+ 888   o88oo,.__ ,8P"`     888  888    Y88 `Y8bo,,,o88o
+ "MM,  """"YUMMMmM"        MMM  MMM     YM   `'YMUP"YMM
+:::::::..       ...     :::::::.      ...   :::::::::::: .::::::.
+;;;;``;;;;   .;;;;;;;.   ;;;'';;'  .;;;;;;;.;;;;;;;;'''';;;`    `
+ [[[,/[[['  ,[[     \[[, [[[__[[\.,[[     \[[,   [[     '[==/[[[[,
+ $$$$$$c    $$$,     $$$ $$""""Y$$$$$,     $$$   $$       '''    $
+ 888b "88bo,"888,_ _,88P_88o,,od8P"888,_ _,88P   88,     88b    dP
+ MMMM   "W"   "YMMMMMP" ""YUMMMP"   "YMMMMMP"    MMM      "YMmMY"
+```

package/dist/animate.d.ts.map

@@ -1 +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;;;;GAIG;AACH,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;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC7D,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC5D,sEAAsE;IACtE,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;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAMjF;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAiB7D;AA+FD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAMrD"}
+{"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;;;;GAIG;AACH,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;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC7D,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC5D,sEAAsE;IACtE,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;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAMjF;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAiB7D;AA4GD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAMrD"}

package/dist/animate.js

@@ -64,9 +64,12 @@ export function animate(options) {
 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);
+        let lastMs = Date.now();
         const id = setInterval(() => {
+            const nowMs = Date.now();
+            const dt = Math.max(0, (nowMs - lastMs) / 1000);
+            lastMs = nowMs;
             state = springStep(state, to, config, dt);
             emit(onFrame(state.value));
             if (state.done) {
@@ -84,6 +87,10 @@ function createSpringCmd(from, to, config, fps, onFrame, onComplete) {
 /**
  * Build a TEA command that runs a tween animation via `setInterval`.
  *
+ * Uses wall-clock time (`Date.now()`) to compute actual elapsed time
+ * per frame, so animations run at the correct speed regardless of
+ * timer jitter or system load.
+ *
  * @template M - The message type emitted into the TEA update cycle.
  * @param from       - Starting value.
  * @param to         - Target value.
@@ -99,8 +106,12 @@ function createTweenCmd(from, to, duration, ease, fps, onFrame, onComplete) {
     return (emit) => new Promise((resolve) => {
         let state = createTweenState(from);
         const intervalMs = Math.round(1000 / fps);
+        let lastMs = Date.now();
         const id = setInterval(() => {
-            state = tweenStep(state, config, intervalMs);
+            const nowMs = Date.now();
+            const dtMs = Math.max(0, nowMs - lastMs);
+            lastMs = nowMs;
+            state = tweenStep(state, config, dtMs);
             emit(onFrame(state.value));
             if (state.done) {
                 clearInterval(id);

package/dist/animate.js.map

@@ -1 +1 @@
-{"version":3,"file":"animate.js","sourceRoot":"","sources":["../src/animate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAIL,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,OAAO,GACR,MAAM,aAAa,CAAC;AA2DrB,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAI,OAA0B;IACnD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,GAAG,EAAE,EAAE,SAAS,GAAG,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAE/E,4CAA4C;IAC5C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;YACpB,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YAClB,IAAI,UAAU;gBAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACrC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACpH,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AACrE,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAS,eAAe,CACtB,IAAY,EACZ,EAAU,EACV,MAAoB,EACpB,GAAW,EACX,OAA6B,EAC7B,UAAoB;IAEpB,OAAO,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5B,IAAI,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC;QACnB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QAE1C,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE;YAC1B,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YAE3B,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACf,aAAa,CAAC,EAAE,CAAC,CAAC;gBAClB,IAAI,UAAU;oBAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;gBACnC,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,SAAS,cAAc,CACrB,IAAY,EACZ,EAAU,EACV,QAAgB,EAChB,IAAc,EACd,GAAW,EACX,OAA6B,EAC7B,UAAoB;IAEpB,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAEhE,OAAO,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5B,IAAI,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QAE1C,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE;YAC1B,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;YAC7C,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YAE3B,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACf,aAAa,CAAC,EAAE,CAAC,CAAC;gBAClB,IAAI,UAAU;oBAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;gBACnC,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,8EAA8E;AAC9E,qDAAqD;AACrD,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAG,IAAc;IAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"animate.js","sourceRoot":"","sources":["../src/animate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAIL,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,OAAO,GACR,MAAM,aAAa,CAAC;AA2DrB,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAI,OAA0B;IACnD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,GAAG,EAAE,EAAE,SAAS,GAAG,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAE/E,4CAA4C;IAC5C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;YACpB,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YAClB,IAAI,UAAU;gBAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QACrC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,cAAc,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IACpH,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO,eAAe,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AACrE,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,SAAS,eAAe,CACtB,IAAY,EACZ,EAAU,EACV,MAAoB,EACpB,GAAW,EACX,OAA6B,EAC7B,UAAoB;IAEpB,OAAO,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5B,IAAI,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QAC1C,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAExB,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE;YAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;YAChD,MAAM,GAAG,KAAK,CAAC;YAEf,KAAK,GAAG,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YAE3B,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACf,aAAa,CAAC,EAAE,CAAC,CAAC;gBAClB,IAAI,UAAU;oBAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;gBACnC,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,cAAc,CACrB,IAAY,EACZ,EAAU,EACV,QAAgB,EAChB,IAAc,EACd,GAAW,EACX,OAA6B,EAC7B,UAAoB;IAEpB,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAEhE,OAAO,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5B,IAAI,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;QAC1C,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAExB,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE;YAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,CAAC;YACzC,MAAM,GAAG,KAAK,CAAC;YAEf,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YAE3B,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACf,aAAa,CAAC,EAAE,CAAC,CAAC;gBAClB,IAAI,UAAU;oBAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;gBACnC,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACjB,CAAC,CAAC,CAAC;AACP,CAAC;AAED,8EAA8E;AAC9E,qDAAqD;AACrD,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAG,IAAc;IAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,EAAE;QACpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/app-frame.d.ts

@@ -0,0 +1,176 @@
+/**
+ * `appFrame()` — high-level TEA app shell.
+ *
+ * Provides tabs, pane focus/scroll isolation, shell key handling, help,
+ * panel-scoped overlay context, and optional frame-level command palette.
+ */
+import { type BindingSource } from './help.js';
+import { type KeyMap } from './keybindings.js';
+import type { App, Cmd } from './types.js';
+import type { Overlay } from './overlay.js';
+import type { TransitionShaderFn } from './transition-shaders.js';
+import { type BuiltinTransition } from './transition-shaders.js';
+import type { CommandPaletteItem, CommandPaletteState } from './command-palette.js';
+import type { GridTrack } from './grid.js';
+import { type OverflowX } from './focus-area.js';
+import { type SplitPaneDirection, type SplitPaneState } from './split-pane.js';
+import type { LayoutRect } from './layout-rect.js';
+import { type Timeline, type TimelineState } from './timeline.js';
+/** Page declaration consumed by {@link createFramedApp}. */
+export interface FramePage<PageModel, Msg> {
+    /** Stable page id. */
+    readonly id: string;
+    /** Tab title. */
+    readonly title: string;
+    /** Page-level initializer. */
+    init(): [PageModel, Cmd<Msg>[]];
+    /** Page-level updater (custom messages only). */
+    update(msg: Msg, model: PageModel): [PageModel, Cmd<Msg>[]];
+    /** Page layout tree. */
+    layout(model: PageModel): FrameLayoutNode;
+    /** Optional page keymap. */
+    keyMap?: KeyMap<Msg>;
+    /** Optional help source override. */
+    helpSource?: BindingSource;
+    /** Optional page-scoped command items for command palette listing/execution. */
+    commandItems?: (model: PageModel) => readonly FrameCommandItem<Msg>[];
+}
+/** Custom command-palette item with optional message dispatch action. */
+export interface FrameCommandItem<Msg> extends CommandPaletteItem {
+    /** Message dispatched when this item is selected. */
+    readonly action?: Msg;
+}
+/** Declarative frame layout node. */
+export type FrameLayoutNode = {
+    readonly kind: 'pane';
+    readonly paneId: string;
+    readonly render: (width: number, height: number) => string;
+    readonly overflowX?: OverflowX;
+} | {
+    readonly kind: 'split';
+    readonly splitId: string;
+    readonly direction?: SplitPaneDirection;
+    readonly state: SplitPaneState;
+    readonly minA?: number;
+    readonly minB?: number;
+    readonly paneA: FrameLayoutNode;
+    readonly paneB: FrameLayoutNode;
+    readonly dividerChar?: string;
+} | {
+    readonly kind: 'grid';
+    readonly gridId: string;
+    readonly columns: readonly GridTrack[];
+    readonly rows: readonly GridTrack[];
+    readonly areas: readonly string[];
+    readonly gap?: number;
+    readonly cells: Readonly<Record<string, FrameLayoutNode>>;
+};
+/** Context passed to overlay factory. */
+export interface FrameOverlayContext<PageModel> {
+    /** Active page id. */
+    readonly activePageId: string;
+    /** Active page model. */
+    readonly pageModel: PageModel;
+    /** Absolute pane rectangles for the active page. */
+    readonly paneRects: ReadonlyMap<string, LayoutRect>;
+    /** Full-screen bounds. */
+    readonly screenRect: LayoutRect;
+}
+/** Page transition styles — a built-in name or a custom shader function. */
+export type PageTransition = BuiltinTransition | TransitionShaderFn;
+/** `createFramedApp()` options. */
+export interface CreateFramedAppOptions<PageModel, Msg> {
+    /** Registered pages. */
+    readonly pages: readonly FramePage<PageModel, Msg>[];
+    /** Optional default page id (falls back to first page). */
+    readonly defaultPageId?: string;
+    /** Optional frame title. */
+    readonly title?: string;
+    /** Initial terminal width before runtime resize events. Default: 80. */
+    readonly initialColumns?: number;
+    /** Initial terminal height before runtime resize events. Default: 24. */
+    readonly initialRows?: number;
+    /** Optional global keymap layered above page keymap. */
+    readonly globalKeys?: KeyMap<Msg>;
+    /** Enable frame-level command palette (`ctrl+p` / `:`). */
+    readonly enableCommandPalette?: boolean;
+    /** Optional overlay provider (receives pane rects for panel scoping). */
+    readonly overlayFactory?: (ctx: FrameOverlayContext<PageModel>) => readonly Overlay[];
+    /** Optional page transition style. Default: 'none'. */
+    readonly transition?: PageTransition;
+    /** Transition duration in milliseconds. Default: 300. */
+    readonly transitionDuration?: number;
+    /** Optional function to determine the transition style dynamically. */
+    readonly transitionOverride?: (model: PageModel) => PageTransition;
+    /**
+     * Optional compiled timeline that drives the transition animation.
+     *
+     * Must contain a `'progress'` track that tweens from 0 to 1.
+     * When provided, replaces the default ease/duration with whatever
+     * the timeline defines — springs, multi-track orchestration, etc.
+     *
+     * ```ts
+     * import { timeline, EASINGS } from '@flyingrobots/bijou-tui';
+     *
+     * createFramedApp({
+     *   transition: 'melt',
+     *   transitionTimeline: timeline()
+     *     .add('progress', {
+     *       type: 'tween',
+     *       from: 0, to: 1,
+     *       duration: 600,
+     *       ease: EASINGS.easeInOutCubic,
+     *     })
+     *     .build(),
+     * });
+     * ```
+     */
+    readonly transitionTimeline?: Timeline;
+}
+/** Stored pane scroll coordinates. */
+export interface FramePaneScroll {
+    /** Horizontal offset. */
+    readonly x: number;
+    /** Vertical offset. */
+    readonly y: number;
+}
+/** Runtime model owned by the frame. */
+export interface FrameModel<PageModel> {
+    /** Current active page id. */
+    readonly activePageId: string;
+    /** Stable page order. */
+    readonly pageOrder: readonly string[];
+    /** Current model per page id. */
+    readonly pageModels: Readonly<Record<string, PageModel>>;
+    /** Focused pane id per page (if any). */
+    readonly focusedPaneByPage: Readonly<Record<string, string | undefined>>;
+    /** Per-page/per-pane scroll positions. */
+    readonly scrollByPage: Readonly<Record<string, Readonly<Record<string, FramePaneScroll>>>>;
+    /** Current terminal width. */
+    readonly columns: number;
+    /** Current terminal height. */
+    readonly rows: number;
+    /** Help visibility flag. */
+    readonly helpOpen: boolean;
+    /** Command palette state (undefined when closed). */
+    readonly commandPalette?: CommandPaletteState;
+    /** ID of the page we are transitioning away from. */
+    readonly previousPageId?: string;
+    /** Transition progress (0 to 1). */
+    readonly transitionProgress: number;
+    /** Monotonic counter to discard stale transition ticks. */
+    readonly transitionGeneration: number;
+    /** Currently active transition style. */
+    readonly activeTransition?: PageTransition;
+    /** Wall-clock start time of the active transition (ms since epoch). */
+    readonly transitionStartMs?: number;
+    /** Compiled timeline driving the active transition. */
+    readonly transitionTimeline?: Timeline;
+    /** Timeline state for the active transition. */
+    readonly transitionTimelineState?: TimelineState;
+}
+/**
+ * Create a fully framed TEA app shell.
+ */
+export declare function createFramedApp<PageModel, Msg>(options: CreateFramedAppOptions<PageModel, Msg>): App<FrameModel<PageModel>, Msg>;
+//# sourceMappingURL=app-frame.d.ts.map

package/dist/app-frame.d.ts.map

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