@flyingrobots/bijou-tui 3.1.0 → 4.1.0

package/LICENSE

@@ -1,21 +1,159 @@
-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.
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability to
+use the Work (including but not limited to damages for loss of goodwill, work
+stoppage, computer failure or malfunction, or any and all other commercial
+damages or losses), even if such Contributor has been advised of the
+possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -4,27 +4,27 @@ The high-fidelity TEA runtime for Bijou.
 
 `bijou-tui` provides the application loop, layout primitives, motion, and orchestration needed to build complex interactive terminal apps on top of the Bijou core.
 
-## V3.0.0 Evolution
+## Package Role in v4.0.0
 
-The TUI package has been completely overhauled in v3.0.0 to operate as a true graphics engine.
+The TUI package is the surface-first fullscreen runtime in the Bijou stack.
 
-### 🌟 What's New
-- **Honest view contract:** `App.view` and framed pane renderers now speak `ViewOutput` (`string | Surface | LayoutNode`). Strings still work, but they are the legacy compatibility path.
+### What's Included
+- **Pure view contract:** `App.view` and framed pane renderers now speak `ViewOutput` (`Surface | LayoutNode`).
 - **Programmable Rendering Pipeline:** The TEA `view` output is now processed through a 5-stage middleware pipeline (`Layout -> Paint -> PostProcess -> Diff -> Output`). Add custom fragment shaders or logging middleware effortlessly.
 - **Fractal TEA (Sub-Apps):** Compose nested apps with `initSubApp()`, `updateSubApp()`, `mount()`, and `mapCmds()` instead of flattening everything into one update loop.
-- **Bijou CSS (BCSS):** Style supported V3 surface components and frame shell regions with type/class/id selectors, `var()` token lookups, and terminal-aware media queries (`@media (width < 80)`). This is not yet a global cascade across arbitrary layout nodes.
+- **Bijou CSS (BCSS):** Style supported runtime surface components and frame shell regions with type/class/id selectors, `var()` token lookups, and terminal-aware media queries (`@media (width < 80)`). This is not yet a global cascade across arbitrary layout nodes.
 - **Declarative Motion:** Wrap any component in `motion({ key: 'id' }, ...)` and watch it smoothly interpolate layout changes (move, resize) using physics-based springs.
 - **Unified Heartbeat:** All animations and physics calculations are now synchronized to a single `PulseMsg`, eliminating timer jitter and saving CPU.
 
 ## Installation
 
 ```bash
-npm install @flyingrobots/bijou@3.0.0 @flyingrobots/bijou-node@3.0.0 @flyingrobots/bijou-tui@3.0.0
+npm install @flyingrobots/bijou @flyingrobots/bijou-node @flyingrobots/bijou-tui
 ```
 
-If you are upgrading an existing app, see [`../../docs/MIGRATING_TO_V3.md`](../../docs/MIGRATING_TO_V3.md).
+If you are upgrading an existing app, see [`../../docs/MIGRATING_TO_V4.md`](../../docs/MIGRATING_TO_V4.md).
 
-## Quick Start (V3 Sub-App Composition)
+## Quick Start (Sub-App Composition)
 
 ```typescript
 import { initDefaultContext } from '@flyingrobots/bijou-node';
@@ -73,6 +73,7 @@ run(app);
 
 ```typescript
 import { initDefaultContext } from '@flyingrobots/bijou-node';
+import { stringToSurface } from '@flyingrobots/bijou';
 import { run, quit, type App, isKeyMsg } from '@flyingrobots/bijou-tui';
 
 initDefaultContext();
@@ -91,7 +92,11 @@ const app: App<Model> = {
     return [model, []];
   },
 
-  view: (model) => `Count: ${model.count}\n\nPress +/- to change, q to quit`,
+  view: (model) => {
+    const text = `Count: ${model.count}\n\nPress +/- to change, q to quit`;
+    const lines = text.split('\n');
+    return stringToSurface(text, Math.max(1, ...lines.map((line) => line.length)), lines.length);
+  },
 };
 
 run(app);
@@ -106,6 +111,17 @@ run(app);
 
 In non-interactive modes, there is no normal interactive event loop.
 
+## Command Model
+
+`Cmd<M>` may resolve synchronously or asynchronously to:
+
+- a final message
+- `QUIT`
+- a cleanup handle or cleanup function for a long-lived effect
+- `void`
+
+If a command installs a long-lived effect through `onPulse()` or another runtime-backed capability, return that cleanup so the event bus/runtime can dispose it on shutdown.
+
 ## Features Breakdown
 
 - **TEA runtime core**: deterministic model/update/view loop with command-driven side effects.
@@ -116,6 +132,37 @@ In non-interactive modes, there is no normal interactive event loop.
 - **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.
 
+## Choosing Component Families
+
+### Overlays and interruption
+
+- Use `toast()` when you are composing a single transient overlay directly.
+- Use the notification system when the app needs stacking, placement, actions, routing, or history.
+- Use `drawer()` when the user should keep the main surface visible while working in supplemental detail.
+- Use `modal()` when background shortcuts and pointer actions should be blocked.
+- Use `tooltip()` only for tiny local explanation, not for decisions or scrollable content.
+- If the overlay needs embedded component surfaces or multiple real rows, keep it on the structured `Surface` path with `compositeSurface()`.
+
+### Collection interaction
+
+- Use core `table()` or `tableSurface()` for passive comparison.
+- Use `navigableTable()` when row/cell focus and keyboard traversal are the real job.
+- Use `browsableList()` when the content is one-dimensional and description-led rather than grid-oriented.
+- Use `commandPaletteSurface()` when the outcome is an action or navigation target, not a stored form value.
+- If users are really choosing persisted values, keep that work in core `select()` / `filter()` / `multiselect()` instead of turning the palette into a value picker.
+
+### Shell and workspace layout
+
+- Use `createFramedApp()` when the app has multiple destinations, overlays, and workspace state that should be standardized.
+- Use `splitPane()` when the user benefits from primary-versus-secondary context or side-by-side comparison.
+- Use `grid()` when multiple stable regions deserve simultaneous visibility.
+- Use `statusBarSurface()` when shell chrome already lives on the structured `Surface` path; keep `statusBar()` for explicit text output.
+- Use `helpShortSurface()` or `helpViewSurface()` when shortcut guidance stays inside the rich shell; keep `helpShort()` / `helpView()` for explicit text output.
+- Use `commandPaletteSurface()` for action discovery and navigation inside the shell, not as a substitute value picker.
+- Use notifications for events and follow-up, not as a replacement for the status rail.
+- Keep status rails concise and global; explanatory text belongs in the page, not in shell chrome.
+- Mouse is enhancement, not baseline. Overlay layers should consume pointer input before shell chrome or page content, and every click target should mirror an existing keyboard path.
+
 ## Animation
 
 ### Spring Physics
@@ -174,6 +221,25 @@ const fired = tl.firedCallbacks(prev, tlState); // ['onReady']
 
 Position syntax: `'<'` (parallel), `'+=N'` (gap), `'-=N'` (overlap), `'<+=N'` (offset from previous start), absolute ms, `'label'`, `'label+=N'`.
 
+## Transition Shaders
+
+Custom page transitions are surface-native in v4. Shader functions decide whether each cell shows the previous page or next page, and may optionally provide override data for that cell.
+
+```typescript
+import { type TransitionShaderFn } from '@flyingrobots/bijou-tui';
+
+const shimmer: TransitionShaderFn = ({ progress, x, width }) => {
+  const edge = Math.floor(progress * width);
+  if (x < edge) return { showNext: true };
+  if (x === edge) return { showNext: false, overrideChar: '░', overrideRole: 'marker' };
+  return { showNext: false };
+};
+```
+
+Use `overrideChar` when the base cell styling should stay intact, `overrideCell` when the shader needs full fg/bg/modifier control, and `overrideRole` to tell combinators whether an override is ambient (`'decoration'`) or positional (`'marker'`).
+
+Use transition shaders to reinforce workspace change, not as default spectacle. If the effect makes the new page harder to read or hides state meaning that should remain explicit in static or accessible modes, it is the wrong transition.
+
 ## Layout
 
 ### Flexbox
@@ -200,32 +266,55 @@ Children can be **render functions** `(width, height) => string` — they receiv
 ### Viewport
 
 ```typescript
-import { viewport, createScrollState, scrollBy, pageDown } from '@flyingrobots/bijou-tui';
+import { viewportSurface, createScrollStateForContent, scrollBy, pageDown } from '@flyingrobots/bijou-tui';
+import { boxSurface } from '@flyingrobots/bijou';
 
-let scroll = createScrollState(content, viewportHeight);
+const content = boxSurface(longText, { width: 72 });
+let scroll = createScrollStateForContent(content, viewportHeight);
 
-// Render visible window with scrollbar
-const view = viewport({ width: 60, height: 20, content, scrollY: scroll.y });
+// Mask the content to a visible window with scrollbar
+const view = viewportSurface({ width: 60, height: 20, content, scrollY: scroll.y });
 
 // Handle scroll keys
 scroll = scrollBy(scroll, 1);   // down one line
 scroll = pageDown(scroll);       // down one page
 ```
 
+Treat `viewportSurface()` as the canonical scroll mask for rich TUI composition. Keep `viewport()` for explicit text-lowering paths.
+
 ### Basic Layout
 
 ```typescript
-import { vstack, hstack } from '@flyingrobots/bijou-tui';
+import {
+  hstack,
+  hstackSurface,
+  place,
+  placeSurface,
+  vstack,
+  vstackSurface,
+} from '@flyingrobots/bijou-tui';
+
+vstack(header, content, footer);                   // explicit text-lowering path
+hstack(2, leftPanel, rightPanel);                  // explicit text-lowering path
+place('Title', { width: 20, height: 3 });          // text placement
 
-vstack(header, content, footer);       // vertical stack
-hstack(2, leftPanel, rightPanel);      // side-by-side with gap
+vstackSurface(headerSurface, bodySurface);         // structured surface stack
+hstackSurface(2, navSurface, mainSurface);         // structured horizontal stack
+placeSurface(dialogSurface, {                      // structured placement/alignment
+  width: cols,
+  height: rows,
+  hAlign: 'center',
+  vAlign: 'middle',
+});
 ```
 
+Prefer `vstackSurface()` / `hstackSurface()` / `placeSurface()` when the view is already composed from `Surface` values. Keep `vstack()` / `hstack()` / `place()` for explicit text composition or lowering paths.
+
 ### Split Pane
 
 ```typescript
 import {
-  createSplitPaneState, splitPane, splitPaneResizeBy, splitPaneFocusNext,
+  createSplitPaneState, splitPaneSurface, splitPaneResizeBy, splitPaneFocusNext,
 } from '@flyingrobots/bijou-tui';
 
 let state = createSplitPaneState({ ratio: 0.35 });
@@ -235,7 +324,7 @@ state = splitPaneResizeBy(state, 2, { total: cols, minA: 16, minB: 16 });
 state = splitPaneFocusNext(state);
 
 // in view:
-const output = splitPane(state, {
+const output = splitPaneSurface(state, {
   direction: 'row',
   width: cols,
   height: rows,
@@ -246,12 +335,14 @@ const output = splitPane(state, {
 });
 ```
 
+Prefer `splitPaneSurface()` when the panes are already structured `Surface` views. Keep `splitPane()` for explicit text composition or lowering paths.
+
 ### Grid
 
 ```typescript
-import { grid } from '@flyingrobots/bijou-tui';
+import { gridSurface } from '@flyingrobots/bijou-tui';
 
-const output = grid({
+const output = gridSurface({
   width: cols,
   height: rows,
   columns: [24, '1fr'],
@@ -271,6 +362,8 @@ const output = grid({
 });
 ```
 
+Prefer `gridSurface()` when the regions are already structured `Surface` views. Keep `grid()` for explicit text composition or lowering paths.
+
 ## Resize Handling
 
 Terminal resize events are dispatched automatically as `ResizeMsg`:
@@ -303,7 +396,7 @@ 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.runCmd(someCommand);         // final messages re-emitted, cleanup retained
 bus.dispose();                   // clean shutdown
 ```
 
@@ -341,11 +434,21 @@ kb.enable('Quit');
 Auto-generate help text from registered bindings:
 
 ```typescript
-import { helpView, helpShort, helpFor } from '@flyingrobots/bijou-tui';
+import {
+  helpView,
+  helpViewSurface,
+  helpShort,
+  helpShortSurface,
+  helpFor,
+  helpForSurface,
+} 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
+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
+helpShortSurface(kb, { width: 48 }); // shell hint that stays on the Surface path
+helpViewSurface(kb, { width: 48 });  // grouped help as a Surface
+helpForSurface(kb, 'Nav', { width: 48 });
 ```
 
 ### Input Stack
@@ -377,7 +480,7 @@ stack.remove(modalId);
 Paint overlays (modals, toasts) on top of existing content:
 
 ```typescript
-import { composite, modal, toast } from '@flyingrobots/bijou-tui';
+import { compositeSurface, modal, toast } from '@flyingrobots/bijou-tui';
 
 // Create a centered dialog
 const dialog = modal({
@@ -398,12 +501,17 @@ const notification = toast({
 });
 
 // Paint overlays onto background content
-const output = composite(backgroundView, [dialog, notification], { dim: true });
+const output = compositeSurface(backgroundSurface, [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.
+Each overlay now exposes both `surface` and `content` forms. Prefer `compositeSurface()` when your app is already on the surface-native path. Keep the string-oriented `composite()` path for explicit lowering boundaries, not as the default mental model. The `dim` option fades the background with ANSI dim.
+
+`modal().body`, `modal().hint`, `drawer().content`, and `tooltip().content` accept either plain strings or structured `Surface` content. Use surfaces when the overlay needs real rows, embedded component surfaces, or richer composition inside the interrupting layer.
+
+Reach for `toast()` when the app is composing a one-off overlay directly. Reach for the notification system when stacking, actions, routing, or history matter. The notification lab in `examples/notifications` is the canonical higher-level example.
 
 `drawer()` now supports `left`/`right`/`top`/`bottom` anchors and optional `region` mounting for panel-scoped overlays.
+Use `drawer()` when the user should keep the main task visible while consulting or editing supplemental context. Use `modal()` when the user must stop and decide. Use `tooltip()` only for tiny local explanation, not for commands or scrollable content.
 
 ## App Frame
 
@@ -414,10 +522,23 @@ Each overlay is a `{ content, row, col }` object. `composite()` splices them ont
 - frame help (`?`) and optional command palette (`ctrl+p` / `:`)
 - overlay factory with pane rects for panel-scoped drawers/modals
 
-Pane renderers may return a legacy string, a `Surface`, or a `LayoutNode`. The shell normalizes those outputs into the framed scroll/focus path for you.
+Pane renderers return a `Surface` or a `LayoutNode`. The shell normalizes those outputs into the framed scroll/focus path for you.
+
+Typed shell notes:
+
+- `createFramedApp<PageModel, Msg>()` returns `FramedApp<PageModel, Msg>`
+- page `update()` receives `FramePageMsg<Msg>` so raw `mouse` / `pulse` delivery is explicit
+- wrapped shell commands carry `FramedAppMsg<Msg>` instead of collapsing frame/page wrappers into plain `Msg`
 
 See `examples/release-workbench/main.ts` for the canonical shell demo and `examples/app-frame/main.ts` for a compact focused example.
 
+Shell role split matters:
+
+- `statusBarSurface()` communicates concise global state
+- `helpShortSurface()` / `helpViewSurface()` teach shortcuts and scope
+- `commandPaletteSurface()` handles action discovery and navigation
+- notifications surface events and follow-up
+
 ## Building Blocks
 
 Reusable stateful components that follow the TEA state + pure transformers + sync render + convenience keymap pattern:
@@ -426,55 +547,100 @@ Reusable stateful components that follow the TEA state + pure transformers + syn
 
 ```typescript
 import {
-  createNavigableTableState, navigableTable, navTableFocusNext,
+  createNavigableTableState, navigableTable, navigableTableSurface, navTableFocusNext,
   navTableKeyMap, helpShort,
 } from '@flyingrobots/bijou-tui';
 
 const state = createNavigableTableState({ columns, rows, height: 10 });
-const output = navigableTable(state, { ctx });
+const textOutput = navigableTable(state, { ctx });
+const surfaceOutput = navigableTableSurface(state, { ctx });
 const next = navTableFocusNext(state);
 ```
 
+Use `navigableTableSurface()` when the user should actively traverse a table inside a rich TUI surface. Keep `navigableTable()` for explicit text lowering. If the job is still passive comparison, prefer core `table()` or `tableSurface()` and keep the interaction layer simpler.
+
 ### Browsable List
 
 ```typescript
 import {
-  createBrowsableListState, browsableList, listFocusNext,
+  createBrowsableListState, browsableList, browsableListSurface, listFocusNext,
   browsableListKeyMap,
 } from '@flyingrobots/bijou-tui';
 
 const state = createBrowsableListState({ items, height: 10 });
-const output = browsableList(state);
+const textOutput = browsableList(state);
+const surfaceOutput = browsableListSurface(state, { width: 40 });
 ```
 
+Use `browsableListSurface()` when the list belongs inside a rich TUI region and should share viewport masking semantics with pagers and focus areas. Keep `browsableList()` for explicit text lowering.
+
 ### File Picker
 
 ```typescript
 import {
-  createFilePickerState, filePicker, fpFocusNext, fpEnter, fpBack,
+  createFilePickerState, filePicker, filePickerSurface, fpFocusNext, fpEnter, fpBack,
   filePickerKeyMap,
 } from '@flyingrobots/bijou-tui';
 import { nodeIO } from '@flyingrobots/bijou-node';
 
 const io = nodeIO();
 const state = createFilePickerState({ cwd: process.cwd(), io, height: 15 });
-const output = filePicker(state);
+const textOutput = filePicker(state);
+const surfaceOutput = filePickerSurface(state, { width: 60 });
+```
+
+Use `filePickerSurface()` when the browser lives inside a rich TUI pane and should inherit shared viewport masking semantics. Keep `filePicker()` for explicit text lowering.
+
+### Command Palette
+
+```typescript
+import {
+  createCommandPaletteState, commandPalette, commandPaletteSurface,
+  cpFilter, commandPaletteKeyMap,
+} from '@flyingrobots/bijou-tui';
+
+const state = createCommandPaletteState(items, 8);
+const textOutput = commandPalette(state, { width: 60 });
+const surfaceOutput = commandPaletteSurface(state, { width: 60, ctx });
+```
+
+Use `commandPaletteSurface()` when the palette is part of a structured shell or overlay and should share viewport masking semantics. Keep `commandPalette()` for explicit text lowering.
+
+### Pager
+
+```typescript
+import {
+  createPagerStateForSurface,
+  pagerSurface,
+  pagerScrollBy,
+} from '@flyingrobots/bijou-tui';
+
+const state = createPagerStateForSurface(contentSurface, { width: 60, height: 20 });
+const output = pagerSurface(contentSurface, state);
 ```
 
 ### Focus Area
 
 ```typescript
 import {
-  createFocusAreaState, focusArea, focusAreaScrollBy,
+  createFocusAreaStateForSurface, focusAreaScrollBy, focusAreaSurface,
   focusAreaKeyMap,
 } from '@flyingrobots/bijou-tui';
 
-const state = createFocusAreaState({ content, width: 60, height: 20, overflowX: 'scroll' });
-const output = focusArea(state, { focused: true, ctx });
+const state = createFocusAreaStateForSurface(contentSurface, {
+  width: 60,
+  height: 20,
+  overflowX: 'scroll',
+});
+const output = focusAreaSurface(contentSurface, state, { focused: true, ctx });
 ```
 
+If the pane is still intentionally text-composed, `createFocusAreaState()` + `focusArea()` remain the explicit lowering path.
+
 ### DAG Pane
 
+Use `dagPane()` when graph inspection is an active task and the user needs keyboard-owned selection, path highlighting, and scroll control. Keep plain `dag()` in `@flyingrobots/bijou` for passive graph explanation, and move to `dagSlice()` or `dagStats()` when a focused fragment or structural summary would be more honest than a full interactive graph.
+
 ```typescript
 import {
   createDagPaneState, dagPane, dagPaneSelectChild,
@@ -495,7 +661,7 @@ All building blocks include `*KeyMap()` factories for preconfigured vim-style ke
 
 ## License
 
-MIT
+Apache-2.0
 
 ---
 

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

@@ -5,19 +5,19 @@
  * page frame state sync, and transition tick command.
  */
 import type { FramePage, CreateFramedAppOptions } from './app-frame.js';
-import type { InternalFrameModel, FrameAction } from './app-frame-types.js';
+import type { InternalFrameModel, FrameAction, FramedAppMsg } from './app-frame-types.js';
 import type { Cmd } from './types.js';
 import type { DockDirection } from './panel-dock.js';
 /** Dispatch a frame-level action (tab switch, pane cycle, scroll, palette, help toggle, transitions). */
-export declare function applyFrameAction<PageModel, Msg>(action: FrameAction, model: InternalFrameModel<PageModel, Msg>, options: CreateFramedAppOptions<PageModel, Msg>, pagesById: Map<string, FramePage<PageModel, Msg>>): [InternalFrameModel<PageModel, Msg>, Cmd<Msg>[]];
+export declare function applyFrameAction<PageModel, Msg>(action: FrameAction, model: InternalFrameModel<PageModel, Msg>, options: CreateFramedAppOptions<PageModel, Msg>, pagesById: Map<string, FramePage<PageModel, Msg>>): [InternalFrameModel<PageModel, Msg>, Cmd<FramedAppMsg<Msg>>[]];
 /** Cycle the active tab by `delta` positions, optionally starting a transition. */
-export declare function switchTab<PageModel, Msg>(model: InternalFrameModel<PageModel, Msg>, delta: number, pagesById: Map<string, FramePage<PageModel, Msg>>, options: CreateFramedAppOptions<PageModel, Msg>): [InternalFrameModel<PageModel, Msg>, Cmd<Msg>[]];
+export declare function switchTab<PageModel, Msg>(model: InternalFrameModel<PageModel, Msg>, delta: number, pagesById: Map<string, FramePage<PageModel, Msg>>, options: CreateFramedAppOptions<PageModel, Msg>): [InternalFrameModel<PageModel, Msg>, Cmd<FramedAppMsg<Msg>>[]];
 /** Move focus to the next or previous pane in the active page's layout. */
 export declare function cyclePane<PageModel, Msg>(model: InternalFrameModel<PageModel, Msg>, delta: number, pagesById: Map<string, FramePage<PageModel, Msg>>): InternalFrameModel<PageModel, Msg>;
 /** Apply a scroll action to the currently focused pane. */
 export declare function scrollFocusedPane<PageModel, Msg>(model: InternalFrameModel<PageModel, Msg>, action: Extract<FrameAction, {
     type: 'scroll-up' | 'scroll-down' | 'page-up' | 'page-down' | 'top' | 'bottom' | 'scroll-left' | 'scroll-right';
-}>, pagesById: Map<string, FramePage<PageModel, Msg>>): InternalFrameModel<PageModel, Msg>;
+}>, pagesById: Map<string, FramePage<PageModel, Msg>>, options: CreateFramedAppOptions<PageModel, Msg>): InternalFrameModel<PageModel, Msg>;
 /** Toggle minimize on the focused pane of the active page. */
 export declare function applyToggleMinimize<PageModel, Msg>(model: InternalFrameModel<PageModel, Msg>, pagesById: Map<string, FramePage<PageModel, Msg>>): InternalFrameModel<PageModel, Msg>;
 /** Toggle maximize on the focused pane of the active page. */
@@ -29,5 +29,5 @@ export declare function syncPageFrameState<PageModel, Msg>(model: InternalFrameM
 /**
  * Create a TEA command that drives transition re-renders from the shared pulse.
  */
-export declare function createTransitionTickCmd<Msg>(durationMs: number, generation: number): Cmd<Msg>;
+export declare function createTransitionTickCmd<Msg>(durationMs: number, generation: number): Cmd<FramedAppMsg<Msg>>;
 //# sourceMappingURL=app-frame-actions.d.ts.map