@valyrianjs/terminal 0.1.0 → 0.1.2

package/docs/interaction-model.md

@@ -1,68 +1,104 @@
 # Interaction Model
 
-Esta guia describe como responden las primitivas interactivas del paquete. Si todavia no tienes claro el modelo base, empieza por `docs/core-concepts.md`. Si necesitas lifecycle, streams o runtime de sesion, sigue con `docs/session-runtime.md`.
+This guide explains how interactive primitives receive input and report events. For lifecycle and stream details, see [Session Runtime](./session-runtime.md).
 
-## Reglas compartidas
+## Shared rules
 
-- `Tab` avanza al siguiente elemento enfocable.
-- `Shift+Tab` regresa al anterior.
-- Los nodos interactivos necesitan `id` si quieres enfocarlos o activarlos programaticamente.
-- `focusAt(x, y)` y `clickAt(x, y)` dependen de los hitboxes del frame actual.
+- Interactive nodes need stable `id` values for programmatic focus, click, and coordinate lookup.
+- `Tab` moves to the next focusable node; `Shift+Tab` moves back.
+- `focusAt(x, y)` and `clickAt(x, y)` use hitboxes from the current rendered frame.
+- Components report events to your handlers; your app owns the resulting state changes.
+- Connected streams, mouse input, clipboard integration, and modified keys follow terminal and runtime capabilities.
 
-## `Input`
+## Input events
 
-`Input` es una primitiva de edicion de una sola linea con cursor, seleccion y submit.
+Keyboard dispatch uses normalized key names such as `ENTER`, `TAB`, `SHIFT_TAB`, `LEFT`, `RIGHT`, `CTRL_V`, and single-character strings. When a session is connected to `stdin`, terminal input is parsed and routed to the focused primitive.
 
-Comportamiento observable:
+Pasted text is treated as text input for the focused primitive. Do not treat pasted strings or key sequences as terminal control instructions inside rendered content.
 
-- texto normal: inserta caracteres
-- `Enter`: dispara `onsubmit`
-- `Left` / `Right`: mueve cursor
-- `Shift+Left` / `Shift+Right`: extiende seleccion
-- `Alt+Left` / `Alt+Right`: navega por palabra
-- `Home` / `End`: salta al inicio o final
-- `Ctrl+A`: selecciona todo
-- `Ctrl+C`: copia seleccion
-- `Ctrl+X`: corta seleccion
-- `Ctrl+V`: pega desde clipboard
-- `Backspace` / `Delete`: elimina contenido
+## Focus and ids
 
-Handlers principales:
+Focus is session state. The session can:
+
+- focus by id with `focus(id)`
+- move sequentially with `focusNext()` and `focusPrev()`
+- dispatch keys to the focused primitive with `dispatchKey(key)`
+- resolve coordinates with `focusAt(x, y)` and `clickAt(x, y)`
+
+`FocusScope` bounds sequential focus traversal to a local group when focus is already inside that active scope. `Overlay trapFocus` keeps traversal inside an overlay-like region while the overlay is present. These primitives help compose popovers and lightweight dialog surfaces while routing and command execution stay in the app layer.
+
+## Component interaction
+
+### `Input`
+
+`Input` is a single-line editing primitive.
+
+Supported behavior includes:
+
+- character insertion
+- `ENTER` submit
+- cursor movement with `LEFT`, `RIGHT`, `HOME`, and `END`
+- selection with `SHIFT_LEFT`, `SHIFT_RIGHT`, and `CTRL_A`
+- copy, cut, and paste through `CTRL_C`, `CTRL_X`, and `CTRL_V`
+- deletion with `BACKSPACE` and `DELETE`
+
+Main handlers:
+
+- `onchange`
+- `oninput`
+- `onsubmit`
+
+### `Editor`
+
+`Editor` is a multiline editing primitive.
+
+Supported behavior includes:
+
+- character insertion
+- `SHIFT_ENTER` newline when the terminal reports that modified key
+- `ENTER` submit
+- `ESCAPE` cancel
+- line and cursor movement with arrow keys, `HOME`, and `END`
+- paste through `CTRL_V` or terminal paste input
+- deletion with `BACKSPACE` and `DELETE`
+
+Main handlers:
 
 - `onchange`
 - `oninput`
 - `onsubmit`
-- `onChangeText`
+- `oncancel`
+
+Cursor positions use JavaScript string columns for deterministic common-text editing. Keep specialized grapheme-width handling in app-level formatting when a workflow needs exact terminal cell width for complex character sequences.
 
-## `Button`
+### `Button`
 
-`Button` representa una accion discreta.
+`Button` represents a discrete action.
 
-Comportamiento observable:
+Activation paths:
 
-- responde a `Enter` y `Space` cuando tiene foco
-- responde a `session.click(id)`
-- responde a `session.clickAt(x, y)` cuando el hitbox cae en el boton
+- `ENTER` or `SPACE` when focused
+- `session.click(id)`
+- `session.clickAt(x, y)` when the coordinate lands on the button
 
-Handlers principales:
+Main handlers:
 
 - `onpress`
 - `onclick`
 - `action`
-- `onPress`
 
-## `List`
+### `List`
 
-`List` modela seleccion y activacion por fila.
+`List` models row selection and activation.
 
-Comportamiento observable:
+Supported behavior includes:
 
-- `Up` / `Left`: mueve seleccion hacia arriba
-- `Down` / `Right`: mueve seleccion hacia abajo
-- `Enter`: dispara `onpress`
-- el hover por mouse expone fila, indice y valor actual
+- `UP` and `LEFT` move selection up
+- `DOWN` and `RIGHT` move selection down
+- `ENTER` activates the selected row
+- mouse hover reports row details when mouse input is connected
 
-Handlers principales:
+Main handlers:
 
 - `onchange`
 - `onpress`
@@ -72,21 +108,20 @@ Handlers principales:
 - `oncapturestart`
 - `oncaptureend`
 
-Con `pointerCapture`, la lista conserva la interaccion durante drag aunque el puntero salga del hitbox inicial.
+`pointerCapture` lets a list keep drag interaction even when the pointer leaves the initial hitbox.
 
-## `ScrollView`
+### `ScrollView`
 
-`ScrollView` recorta contenido vertical y expone interaccion por viewport.
+`ScrollView` clips vertical content and exposes viewport-based interaction.
 
-Comportamiento observable:
+Supported behavior includes:
 
-- `Up`: desplaza hacia arriba
-- `Down`: desplaza hacia abajo
-- `height`: define el viewport visible
-- `highlightRows`: resalta filas visibles concretas
-- el hover por mouse expone fila visible y texto renderizado
+- `UP` and `DOWN` scrolling when focused
+- `height` as the visible viewport
+- `highlightRows` for marking visible rows
+- mouse hover details when mouse input is connected
 
-Handlers principales:
+Main handlers:
 
 - `onhover`
 - `onrowenter`
@@ -94,22 +129,21 @@ Handlers principales:
 - `oncapturestart`
 - `oncaptureend`
 
-Con `pointerCapture`, el scroll mantiene la interaccion durante drag aunque el puntero salga del viewport.
+`pointerCapture` lets a scroll view keep drag interaction even when the pointer leaves the viewport.
 
-## Mouse y pointer capture
+## Mouse and pointer behavior
 
-Cuando la sesion recibe eventos SGR de mouse:
+When a connected session receives supported SGR mouse input:
 
-- `press`: enfoca y activa el hitbox correspondiente
-- `drag`: extiende seleccion en `Input` o actualiza hover en `List` y `ScrollView`
-- `release`: cierra captura y limpia hover cuando corresponde
-- `wheel-up` / `wheel-down`: se traducen a navegacion vertical
+- press focuses or activates the matching hitbox
+- drag extends input selection or updates list/scroll hover
+- release ends capture when capture is active
+- wheel input maps to vertical navigation
 
-`pointerCapture` solo aplica hoy a `List` y `ScrollView`.
+Mouse behavior follows supported terminal input sequences and the active session connection. Keep a keyboard path for important actions.
 
-## Donde seguir
+## Where to go next
 
-- `docs/core-concepts.md` para el modelo mental del paquete
-- `docs/session-runtime.md` para lifecycle, streams, clipboard y runtime
-- `docs/cookbook.md` para recetas practicas
-- `docs/api-reference.md` para consulta puntual de props, payloads y tipos
+- [Cookbook](./cookbook.md) for recipes that combine primitives.
+- [Session Runtime](./session-runtime.md) for streams, clipboard adapters, mouse input, and cleanup.
+- [API Reference](./api-reference.md) for props and event payloads.

package/docs/primitive-gallery.md

@@ -0,0 +1,365 @@
+# Primitive Gallery
+
+Build complete terminal interfaces from focused primitives.
+
+Use this gallery to choose primitives, see their main props, and compose terminal mini apps. The gallery teaches what each primitive does and how it fits with the others. Use API Reference for prop-level details.
+
+| Primitive | Use it for | Demo |
+| --- | --- | --- |
+| `Screen` | the top-level surface of a terminal app | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `Text` | copy that should render as terminal text | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `Box` | small surfaces, cards, and stacked sections | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `View` | named regions that help app code describe purpose | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `Pane` | sidebars, detail panels, and app sections | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `Split` | resizable app shells and master/detail layouts | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `Fixed` | headers, footers, rails, and persistent status bars | [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx) |
+| `Input` | names, filters, prompts, and short commands | [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx) |
+| `Editor` | notes, descriptions, and longer messages | [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx) |
+| `Button` | save actions, confirmations, command triggers, and app actions | [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx) |
+| `FocusScope` | forms, panels, and overlays where Tab should stay within a focused area | [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx) |
+| `List` | menus, choosers, command lists, and item browsers | [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx) |
+| `Table` | compact data detail and aligned text pairs | [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx) |
+| `Row` | one record line inside a `Table` | [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx) |
+| `Td` | styled or padded data cells | [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx) |
+| `ScrollView` | long instructions, timelines, and scrollable panels | [`examples/docs/primitive-activity-console.tsx`](../examples/docs/primitive-activity-console.tsx) |
+| `LogView` | activity feeds, status streams, and event output | [`examples/docs/primitive-activity-console.tsx`](../examples/docs/primitive-activity-console.tsx) |
+| `Overlay` | command panels, dialogs, palettes, and focused chooser surfaces | [`examples/docs/primitive-command-panel.tsx`](../examples/docs/primitive-command-panel.tsx) |
+
+## Start with the shell
+
+Use `Screen` and `Text` to establish the app root and clear terminal copy.
+
+### `Screen`
+
+Use `Screen` as the top-level surface for a terminal app.
+
+**What it is:** A screen root that gives the terminal tree a title and viewport context.
+**Use it for:** the top-level surface of a terminal app.
+**Core props:** `title`, `id`, `focusable`.
+
+**Minimal example:**
+
+```tsx
+<Screen title="Desk"><Text>Ready</Text></Screen>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+### `Text`
+
+Use `Text` for labels, status lines, and short terminal copy.
+
+**What it is:** A text node for labels, status lines, and short messages.
+**Use it for:** copy that should render as terminal text.
+**Core props:** `value`, `style`, `styles`, `state`.
+
+**Minimal example:**
+
+```tsx
+<Text>Status: ready</Text>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+## Compose layout surfaces
+
+Use `Split` to compose responsive rows and columns, then fill each region with `Pane`, `Box`, or `View`.
+
+### `Box`
+
+Use `Box` for cards, stacked sections, and grouped content.
+
+**What it is:** A layout container for grouped content.
+**Use it for:** small surfaces, cards, and stacked sections.
+**Core props:** `direction`, `gap`, `padding`, `width`, `height`, `fill`, `style`.
+
+**Minimal example:**
+
+```tsx
+<Box direction="column" gap={1}><Text>Summary</Text></Box>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+### `View`
+
+Use `View` to name semantic regions in your terminal layout.
+
+**What it is:** A semantic layout container with the same layout behavior as `Box`.
+**Use it for:** named regions that help app code describe purpose.
+**Core props:** `role`, plus Box layout props.
+
+**Minimal example:**
+
+```tsx
+<View role="main"><Text>Work area</Text></View>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+### `Pane`
+
+Use `Pane` for sidebars, detail panels, and app sections.
+
+**What it is:** A layout boundary for a terminal region.
+**Use it for:** sidebars, detail panels, and app sections.
+**Core props:** `direction`, `gap`, `padding`, `fill`, `style`, `id`, `focusable`.
+
+**Minimal example:**
+
+```tsx
+<Pane style={{ background: "#111827" }}><Text>Inbox</Text></Pane>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+### `Split`
+
+Use `Split` for resizable shells and master/detail layouts.
+
+**What it is:** A split layout primitive for rows and columns.
+**Use it for:** resizable app shells and master/detail layouts.
+**Core props:** `direction`, `sizes`, `breakpoints`, `gap`, `width`, `height`, `fill`.
+
+**Minimal example:**
+
+```tsx
+<Split sizes={["30%", "1fr"]}><Pane><Text>List</Text></Pane><Pane><Text>Detail</Text></Pane></Split>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+### `Fixed`
+
+Use `Fixed` for headers, footers, rails, and persistent status bars.
+
+**What it is:** A reserved region attached to an edge of `Screen` or `Pane`.
+**Use it for:** headers, footers, rails, and persistent status bars.
+**Core props:** `position`, `size`.
+
+**Minimal example:**
+
+```tsx
+<Fixed position="bottom" size={1}><Text>Ctrl+C: quit</Text></Fixed>
+```
+
+**Complete demo:** [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx). Run it with `bun examples/docs/primitive-layout-shell.tsx` and quit with `Ctrl+C`.
+
+## Collect input
+
+Use `Input`, `Editor`, `Button`, and `FocusScope` to collect intent and move it into app state.
+
+### `Input`
+
+Use `Input` for names, filters, prompts, and short commands.
+
+**What it is:** A single-line editable field.
+**Use it for:** names, filters, prompts, and short commands.
+**Core props:** `id`, `value`, `placeholder`, `onchange`, `oninput`, `onsubmit`.
+
+**Minimal example:**
+
+```tsx
+<Input id="name" value={name} placeholder="Name" onchange={(event) => { name = event.value; }} />
+```
+
+**Complete demo:** [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx). Run it with `bun examples/docs/primitive-input-workbench.tsx` and quit with `Ctrl+C`.
+
+### `Editor`
+
+Use `Editor` for notes, descriptions, and longer messages.
+
+**What it is:** A multi-line editable field.
+**Use it for:** notes, descriptions, and longer messages.
+**Core props:** `id`, `value`, `placeholder`, `height`, `onchange`, `oninput`, `onsubmit`, `oncancel`.
+
+**Minimal example:**
+
+```tsx
+<Editor id="details" height={4} value={details} onchange={(event) => { details = event.value; }} />
+```
+
+**Complete demo:** [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx). Run it with `bun examples/docs/primitive-input-workbench.tsx` and quit with `Ctrl+C`.
+
+### `Button`
+
+Use `Button` for save actions, confirmations, command triggers, and app actions.
+
+**What it is:** A focusable action control.
+**Use it for:** save actions, confirmations, command triggers, and app actions.
+**Core props:** `id`, `label`, `onpress`, `onclick`, `action`, `style`, `styles`, `state`.
+
+**Minimal example:**
+
+```tsx
+<Button id="save" onpress={() => save()}>Save</Button>
+```
+
+**Complete demo:** [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx). Run it with `bun examples/docs/primitive-input-workbench.tsx` and quit with `Ctrl+C`.
+
+### `FocusScope`
+
+Use `FocusScope` to keep input, lists, and actions together inside a panel.
+
+**What it is:** A focus boundary for a local group.
+**Use it for:** forms, panels, and overlays where Tab should stay within a focused area.
+**Core props:** `active`.
+
+**Minimal example:**
+
+```tsx
+<FocusScope><Input id="query" /><Button id="run">Run</Button></FocusScope>
+```
+
+**Complete demo:** [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx). Run it with `bun examples/docs/primitive-input-workbench.tsx` and quit with `Ctrl+C`.
+
+## Navigate collections
+
+Use `List` for selection and `Table`, `Row`, and `Td` for compact detail views.
+
+### `List`
+
+Use `List` for menus, choosers, command lists, and item browsers.
+
+**What it is:** A focusable collection control with selection and press events.
+**Use it for:** menus, choosers, command lists, and item browsers.
+**Core props:** `id`, `items`, `renderItem`, `virtualized`, `onchange`, `onpress`.
+
+**Minimal example:**
+
+```tsx
+<List id="menu" items={["Inbox", "Done"]} onchange={(event) => { selected = event.value; }} />
+```
+
+**Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
+
+### `Table`
+
+Use `Table` for compact data detail and aligned text pairs.
+
+**What it is:** A table container for rows and cells.
+**Use it for:** compact data detail and aligned text pairs.
+**Core props:** `v-for` when Valyrian loop helpers fit your app.
+
+**Minimal example:**
+
+```tsx
+<Table><Row><Td><Text>Name</Text></Td><Td><Text>Ada</Text></Td></Row></Table>
+```
+
+**Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
+
+### `Row`
+
+Use `Row` for one record line inside a `Table`.
+
+**What it is:** A table row that separates child cells.
+**Use it for:** one record line inside a `Table`.
+**Core props:** `separator`.
+
+**Minimal example:**
+
+```tsx
+<Row separator="  "><Td><Text>Status</Text></Td><Td><Text>Ready</Text></Td></Row>
+```
+
+**Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
+
+### `Td`
+
+Use `Td` for styled or padded data cells.
+
+**What it is:** A table cell that can carry padding and styles.
+**Use it for:** styled or padded data cells.
+**Core props:** `padding`, `style`, `styles`, `state`.
+
+**Minimal example:**
+
+```tsx
+<Td padding={{ x: 1 }}><Text>Ready</Text></Td>
+```
+
+**Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
+
+## Show scrollable activity
+
+Use `ScrollView` and `LogView` when content grows past the visible region.
+
+### `ScrollView`
+
+Use `ScrollView` for long instructions, timelines, and scrollable panels.
+
+**What it is:** A bounded viewport for child content.
+**Use it for:** long instructions, timelines, and scrollable panels.
+**Core props:** `id`, `height`, `highlightRows`, `pointerCapture`, row pointer events.
+
+**Minimal example:**
+
+```tsx
+<ScrollView id="activity" height={6}><Text>One</Text><Text>Two</Text></ScrollView>
+```
+
+**Complete demo:** [`examples/docs/primitive-activity-console.tsx`](../examples/docs/primitive-activity-console.tsx). Run it with `bun examples/docs/primitive-activity-console.tsx` and quit with `Ctrl+C`.
+
+### `LogView`
+
+Use `LogView` for activity feeds, status streams, and event output.
+
+**What it is:** A log renderer for growing activity streams.
+**Use it for:** activity feeds, status streams, and event output.
+**Core props:** `entries`, `followTail`, `emptyText`, `renderEntry`.
+
+**Minimal example:**
+
+```tsx
+<LogView entries={[{ id: "1", content: "ready" }]} followTail />
+```
+
+**Complete demo:** [`examples/docs/primitive-activity-console.tsx`](../examples/docs/primitive-activity-console.tsx). Run it with `bun examples/docs/primitive-activity-console.tsx` and quit with `Ctrl+C`.
+
+## Layer focused panels
+
+Use `Overlay` with `FocusScope` to place a focused chooser over the current screen.
+
+### `Overlay`
+
+Use `Overlay` for command panels, dialogs, palettes, and focused chooser surfaces.
+
+**What it is:** A positioned layer over the current frame.
+**Use it for:** command panels, dialogs, palettes, and focused chooser surfaces.
+**Core props:** `id`, `x`, `y`, `width`, `height`, `trapFocus`, `style`.
+
+**Minimal example:**
+
+```tsx
+<Overlay x={4} y={2} width={40} height={8} trapFocus><Text>Command Panel</Text></Overlay>
+```
+
+**Complete demo:** [`examples/docs/primitive-command-panel.tsx`](../examples/docs/primitive-command-panel.tsx). Run it with `bun examples/docs/primitive-command-panel.tsx` and quit with `Ctrl+C`.
+
+### `FocusScope`
+
+Use `FocusScope` to keep input, lists, and actions together inside a panel.
+
+**What it is:** A focus boundary that pairs well with overlay content.
+**Use it for:** keeping input, lists, and actions together inside a panel.
+**Core props:** `active`.
+
+**Minimal example:**
+
+```tsx
+<Overlay x={2} y={2} width={32} height={8} trapFocus><FocusScope><Input id="query" /><List id="commands" items={commands} /></FocusScope></Overlay>
+```
+
+**Complete demo:** [`examples/docs/primitive-command-panel.tsx`](../examples/docs/primitive-command-panel.tsx). Run it with `bun examples/docs/primitive-command-panel.tsx` and quit with `Ctrl+C`.
+
+## Primitive map
+
+- Shell: `Screen`, `Text`.
+- Layout: `Box`, `View`, `Pane`, `Split`, `Fixed`.
+- Input: `Input`, `Editor`, `Button`, `FocusScope`.
+- Collections: `List`, `Table`, `Row`, `Td`.
+- Activity: `ScrollView`, `LogView`.
+- Layers: `Overlay`, `FocusScope`.
+
+Start with a shell, divide the screen into layout regions, add input or navigation, then layer focused panels when a local task needs priority. Use API Reference for prop-level details: [`docs/api-reference.md`](./api-reference.md).