@valyrianjs/terminal 0.1.1 → 0.2.0

package/docs/interaction-model.md

@@ -1,115 +1,159 @@
 # Interaction Model
 
-This guide describes how the package's interactive primitives respond. If the base model is not clear yet, start with `docs/core-concepts.md`. If you need session lifecycle, streams, or runtime details, continue with `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).
 
 ## Shared rules
 
-- `Tab` moves to the next focusable element.
-- `Shift+Tab` moves back to the previous one.
-- Interactive nodes need an `id` if you want to focus or activate them programmatically.
-- `focusAt(x, y)` and `clickAt(x, y)` depend on the hitboxes in the current frame.
+- 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` is a single-line editing primitive with a cursor, selection, and submit support.
+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.
 
-Observable behavior:
+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.
 
-- regular text: inserts characters
-- `Enter`: triggers `onsubmit`
-- `Left` / `Right`: moves the cursor
-- `Shift+Left` / `Shift+Right`: extends the selection
-- `Alt+Left` / `Alt+Right`: moves by word
-- `Home` / `End`: jumps to the start or end
-- `Ctrl+A`: selects all
-- `Ctrl+C`: copies the selection
-- `Ctrl+X`: cuts the selection
-- `Ctrl+V`: pastes from the clipboard
-- `Backspace` / `Delete`: removes content
+## Focus and ids
+
+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`
+- context press through pointer context input
+
+Main handlers:
+
+- `onchange`
+- `oninput`
+- `onsubmit`
+- `oncontextpress`
+
+### `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`
 
-## `Button`
+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` represents a discrete action.
 
-Observable behavior:
+Activation paths:
 
-- responds to `Enter` and `Space` when focused
-- responds to `session.click(id)`
-- responds to `session.clickAt(x, y)` when the hitbox lands on the button
+- `ENTER` or `SPACE` when focused
+- `session.click(id)`
+- `session.clickAt(x, y)` when the coordinate lands on the button
 
 Main handlers:
 
 - `onpress`
-- `onclick`
-- `action`
-- `onPress`
+- `ondoublepress`
+- `oncontextpress`
+
+A quick second primary mouse press keeps the normal activation behavior and also emits `ondoublepress` when the handler exists. A secondary mouse press emits `oncontextpress`.
 
-## `List`
+### `List`
 
 `List` models row selection and activation.
 
-Observable behavior:
+Supported behavior includes:
 
-- `Up` / `Left`: moves selection up
-- `Down` / `Right`: moves selection down
-- `Enter`: triggers `onpress`
-- mouse hover exposes the current row, index, and value
+- `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
+- quick primary mouse presses on the same row emit `ondoublepress`
+- secondary mouse presses emit `oncontextpress` for the target row
 
 Main handlers:
 
 - `onchange`
 - `onpress`
+- `ondoublepress`
+- `oncontextpress`
 - `onhover`
 - `onrowenter`
 - `onrowleave`
 - `oncapturestart`
 - `oncaptureend`
 
-With `pointerCapture`, the list keeps the interaction during a drag even if the pointer leaves the initial hitbox.
+`pointerCapture` lets a list keep drag interaction even when the pointer leaves the initial hitbox.
 
-## `ScrollView`
+### `ScrollView`
 
 `ScrollView` clips vertical content and exposes viewport-based interaction.
 
-Observable behavior:
+Supported behavior includes:
 
-- `Up`: scrolls up
-- `Down`: scrolls down
-- `height`: defines the visible viewport
-- `highlightRows`: highlights specific visible rows
-- mouse hover exposes the visible row and rendered text
+- `UP` and `DOWN` scrolling when focused
+- `height` as the visible viewport
+- `highlightRows` for marking visible rows
+- mouse hover details when mouse input is connected
+- context press reports the target visible row
 
 Main handlers:
 
 - `onhover`
 - `onrowenter`
 - `onrowleave`
+- `oncontextpress`
 - `oncapturestart`
 - `oncaptureend`
 
-With `pointerCapture`, scrolling keeps the interaction during a drag even if the pointer leaves the viewport.
+`pointerCapture` lets a scroll view keep drag interaction even when the pointer leaves the viewport.
 
-## Mouse and pointer capture
+## Mouse and pointer behavior
 
-When the session receives SGR mouse events:
+When a connected session receives supported SGR mouse input:
 
-- `press`: focuses and activates the matching hitbox
-- `drag`: extends selection in `Input` or updates hover in `List` and `ScrollView`
-- `release`: ends capture and clears hover when needed
-- `wheel-up` / `wheel-down`: translate to vertical navigation
+- 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` currently applies only to `List` and `ScrollView`.
+Mouse behavior follows supported terminal input sequences and the active session connection. Keep a keyboard path for important actions.
 
 ## Where to go next
 
-- `docs/core-concepts.md` for the package mental model
-- `docs/session-runtime.md` for lifecycle, streams, clipboard, and runtime
-- `docs/cookbook.md` for practical recipes
-- `docs/api-reference.md` for quick lookup of props, payloads, and types
+- [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,370 @@
+# 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 a parent frame.
+**Use it for:** headers, footers, rails, and persistent status bars.
+**Core props:** `position`, `size`.
+
+Inside `Screen` or `Pane`, `Fixed` uses the parent frame. If you pass a standalone `Fixed` root to `renderTerminal()`, pass `{ cols, rows }` so it has a viewport.
+
+**Minimal example:**
+
+```tsx
+<Screen>
+  <Fixed position="bottom" size={1}><Text>Ctrl+C: quit</Text></Fixed>
+  <Pane><Text>Work area</Text></Pane>
+</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`.
+
+## 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`, `oncontextpress`.
+
+**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`, `ondoublepress`, `oncontextpress`, `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`, `ondoublepress`, `oncontextpress`.
+
+**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`, `oncontextpress`, 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`, `margin`, `trapFocus`, `style`. `margin` is required and accepts a number, a percentage string, or `{ x, y }` with number or percentage-string values. When `Overlay` is the root passed to `renderTerminal()`, pass exact `{ cols, rows }` as the second argument so margin can resolve against terminal dimensions.
+
+**Minimal example:**
+
+```tsx
+<Overlay margin={{ x: 4, y: 2 }} 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 margin={{ x: 2, y: 2 }} 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).