@valyrianjs/terminal 0.1.1 → 0.1.2

package/docs/api-reference.md

@@ -1,191 +1,343 @@
 # API Reference
 
-Reference for the actual public surface published by `valyrianjs-terminal`.
+Reference for the public surface published by `@valyrianjs/terminal`. For a guided first project, start with [Getting Started](./getting-started.md). For practical primitive selection, use [Primitive Gallery](./primitive-gallery.md).
 
-## Published Entrypoints
+## Published entrypoints
 
-### `valyrianjs-terminal`
+### `@valyrianjs/terminal`
 
-Main entrypoint. At a high level, it exposes:
+Main entrypoint for terminal primitives, rendering, sessions, props, payloads, and types.
 
-- `renderTerminal()`
-- `mountTerminal()`
-- primitives `Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `ScrollView`, `List`, `Table`, `Row`, `Td`
-- prop, event, node, and session types
+Common imports:
 
-### `valyrianjs-terminal/render`
+```tsx
+import { Screen, Text, mountTerminal, renderTerminal } from "@valyrianjs/terminal";
+```
 
-Published subpath for lower-level rendering utilities.
+### `@valyrianjs/terminal/render`
+
+Rendering-only subpath for lower-level rendering utilities:
 
 - `renderTerminal(input): string`
 - `renderTerminalNode(node): string`
 - `renderTerminalFrame(node): TerminalFrame`
 
-Use this subpath when you only need to transform terminal nodes into text or a `TerminalFrame`, without mounting an interactive session.
+Use this subpath for rendering-focused integrations that produce output without mounting an interactive session.
 
-## Main Functions
+## Root exports overview
 
-### `renderTerminal(input): string`
+The root entrypoint exports the public primitives (`Screen`, `Box`, `View`, `Pane`, `Split`, `Fixed`, `Overlay`, `FocusScope`, `Text`, `Input`, `Editor`, `Button`, `List`, `ScrollView`, `LogView`, `Table`, `Row`, and `Td`), the main functions `renderTerminal()` and `mountTerminal()`, public prop and payload types, keymap helpers, and theme helpers.
 
-Resolves the provided root and returns terminal output as plain text.
+## Main functions
 
-Use cases supported by the current implementation:
+### `renderTerminal(input): string`
 
-- snapshots and tests
-- layout validation without `stdin` or `stdout`
-- content inspection in non-interactive mode
+Resolves the provided terminal tree and returns plain text.
 
-Notes:
+Use it for:
 
-- concatenates root nodes with newlines
-- removes only trailing whitespace with `trimEnd()`
-- does not create listeners or interactive state
+- snapshots
+- static examples
+- non-interactive command output
+- layout checks without session state
 
 ### `mountTerminal(input, options?): TerminalSession`
 
-Mounts an interactive session on the terminal tree and returns a `TerminalSession`.
+Creates an interactive session around a terminal tree.
 
-High-level behavior:
+The session can:
 
-- resolves the current tree and re-renders it with `session.update()`
-- manages focus by `id`
-- handles keyboard, mouse, selection, and clipboard interaction
-- can write to `stdout` automatically when provided
-- if it receives `stdin`, it enables raw mode on mount and restores it in `destroy()`
+- rerender with `update()`
+- preserve and move focus
+- dispatch keyboard input
+- handle mouse and coordinate interaction
+- use clipboard integration
+- write ANSI diffs to `stdout` in app runtime
+- clean up connected streams with `destroy()`
 
 ## `TerminalMountOptions`
 
-- `ansi?: boolean` - if `stdout` is present, writes ANSI diffs instead of plain text
-- `clipboard?: TerminalClipboardAdapter | false` - custom adapter or disables the system clipboard
-- `stdin?` - stream with `on("data")`; `off()`, `removeListener()`, `setRawMode()`, `resume()`, and `pause()` are optional
-- `stdout?` - writer with `write(chunk: string)`
+- `runtime?: "app" | "headless"` - selects real app output or scriptable plain output. Omitted runtime becomes app mode for interactive TTY hosts and headless in non-TTY/CI contexts.
+- `alternateScreen?: boolean` - enters alternate screen mode and restores it on destroy by default. Real interactive app mode enables it by default unless overridden.
+- `hideCursor?: boolean` - hides the terminal cursor and restores it on destroy by default. Real interactive app mode enables it by default unless overridden.
+- `restoreOnDestroy?: boolean` - controls restore behavior for cursor and alternate screen state.
+- `clipboard?: TerminalClipboardAdapter | false` - custom clipboard adapter or disabled external clipboard integration.
+- `cols?: number` - initial terminal width in columns.
+- `rows?: number` - initial terminal height in rows.
+- `stdin?` - input stream with `on("data")`; cleanup and raw-mode methods are optional.
+- `stdout?` - output stream with `write(chunk)`; optional dimensions, resize events, and drain events are used when supported.
+- `theme?` - terminal theme for semantic style spans.
+- `keymap?` - custom key bindings for built-in terminal interaction behavior.
+
+If no explicit dimensions or stream dimensions are available, sessions default to `80x24`. Dimensions must be positive integers.
+
+`hideCursor` and `restoreOnDestroy` describe cursor and terminal-restore intent for sessions connected to compatible hosts. Cursor restore follows the connected terminal and stream capabilities. Run `bun examples/docs/cursor.tsx`, type text, press `C`, and quit with `Ctrl+C`; or open [`examples/docs/cursor.tsx`](../examples/docs/cursor.tsx).
+
+## Keymap helpers
+
+- `defaultTerminalKeyBindings` - built-in key bindings for focus traversal, editing, lists, buttons, and scroll views.
+- `createTerminalKeyBindings(bindings?)` - returns a normalized binding list that can extend or replace default behavior.
+- `createResolvedTerminalKeymap(options?)` - creates a keymap object used by sessions.
+- `resolveTerminalKeyBinding(key, context, keymap)` - resolves a normalized key against a context.
+- `validateTerminalKeyBindings(bindings)` - validates key binding shape and rejects ambiguous entries.
+
+Use `keymap` in `TerminalMountOptions` when an app needs custom keyboard behavior while keeping predictable focus and primitive events.
+
+## Theme helpers
+
+- `defaultTerminalTheme` - bundled app-like recipes for common controls.
+- `highContrastTerminalTheme` - alternate recipes with stronger contrast.
+- `mergeTerminalTheme(base, override)` - combines theme recipes and span tokens.
+- `resolveTerminalStyle(style, theme?)` - resolves dot path recipes or inline style objects.
+- `resolveTerminalStyleToken(kind, theme?)` - resolves semantic span tokens for ANSI/plain serialization.
+
+Theme recipes belong in `theme.styles`. Use `color`, `background`, padding, and border values with hex colors for normal app styling.
+
+## Visual style system
+
+`theme.styles` stores named style recipes. A recipe may define color, background, padding, border, and nested visual-state recipes. The bundled default theme includes app-like recipes for core controls such as `button.base`, `button.focus`, `input.base`, `input.focus`, `input.selection`, `list.base`, `list.current`, `list.selected`, `list.hover`, and `list.empty`. Components resolve recipes by dot path, so `style="panel.queue"` reads `theme.styles.panel.queue`. Inline style objects work too when the style belongs to one component instance.
+
+Use `style`, `styles`, and `state` for normal component styling:
+
+- `style` sets the base recipe or inline style for the component frame.
+- `styles` maps visual states to dot path recipes or inline style objects.
+- `state` declares app-owned states such as `loading`, `warning`, `success`, `muted`, `expanded`, or `dropTarget`.
+
+Renderer-owned states come from the runtime when the renderer has the fact itself. Focus, hover, selection, current rows, and pointer capture fall in this group when the primitive supports them. App-owned state should describe product state that the app already knows. Do not mark a ready button as `loading` or an editable field as `readonly`; that teaches a lie to the UI and then the UI repeats it with confidence.
+
+Precedence: the renderer starts with the component default recipe, applies the instance `style`, then applies `styles` entries for current states in stable visual-state order. Geometry fields such as supported padding and border come from the component default plus the instance `style` so layout, hitboxes, and cursors stay stable across focus, hover, and pressed state changes. State styles affect the rendered spans after layout; later current states override earlier visual fields when they set the same property. Inline style objects and dot path recipes use the same merge path after resolution.
+
+Renderer notes:
+
+- Raw ANSI escape control is not the normal public styling API. Use semantic styles and let `ansiOutput()` serialize frames.
+- Layout margin is not supported; use padding, `gap`, `Fixed`, `Split`, or explicit text spacing.
+- The renderer owns terminal frame spans, clipping, focus, and selection; the app owns business state and labels.
+
+Run `bun examples/docs/style-system.tsx`, try `Tab`, `Enter`, and `W`, and quit with `Ctrl+C`; or open [`examples/docs/style-system.tsx`](../examples/docs/style-system.tsx). Run `bun examples/docs/theme-colors.tsx`, press `Tab`, and quit with `Ctrl+C`; or open [`examples/docs/theme-colors.tsx`](../examples/docs/theme-colors.tsx).
+
+### TerminalStyleSpan
+
+`TerminalStyleSpan` is a low-level frame API for renderer integrations and frame serialization. It describes a styled range in a rendered frame and may carry `kind`, coordinates, and `style?` when the renderer resolves an inline style object. App components get their everyday styling surface from semantic styles.
+
+Use `style`, `styles`, and `state` for component styling. Use `TerminalStyleSpan` when a low-level frame integration needs styled ranges after render.
+
+### Advanced: span serialization tokens
+
+`ansiOpen`, `ansiClose`, `plainPrefix`, and `plainSuffix` are low-level fields for trusted renderer integrations that already own frame spans and need exact serialization behavior. Application components get their styling API from semantic styles.
+
+Apps should prefer `theme.styles`, `style`, `styles`, `state`, `color`, `background`, and hex colors. Those fields keep styling semantic, portable, and safe for both `output()` and `ansiOutput()`. When a token defines `color`, `background`, or `style`, ANSI serialization uses the resolved style fields before raw ANSI fallback tokens.
+
+Token behavior:
+
+- `ansiOpen` writes a raw ANSI opening sequence around the span in ANSI output when no `color`, `background`, or `style` field supplies a safer style.
+- `ansiClose` writes the matching raw ANSI close sequence in ANSI output for the same low-level case.
+- `plainPrefix` adds text before the span only in plain output.
+- `plainSuffix` adds text after the span only in plain output.
+
+Prefer semantic styles first: `theme.styles`, `style`, `styles`, `state`, hex `color`, and `background` keep output portable across plain and ANSI render paths. Use raw ANSI tokens for trusted low-level integrations that own frame serialization. Keep token input trusted, pair open and close tokens exactly, verify both `output()` and `ansiOutput()`, and document the integration reason when semantic hex style does not cover the serialization requirement.
+
+## Layout primitives
+
+Use [Primitive Gallery](./primitive-gallery.md) for practical composition examples, including [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx), [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx), [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx), [`examples/docs/primitive-activity-console.tsx`](../examples/docs/primitive-activity-console.tsx), and [`examples/docs/primitive-command-panel.tsx`](../examples/docs/primitive-command-panel.tsx). Run them with `bun examples/docs/primitive-layout-shell.tsx`, `bun examples/docs/primitive-input-workbench.tsx`, `bun examples/docs/primitive-data-explorer.tsx`, `bun examples/docs/primitive-activity-console.tsx`, or `bun examples/docs/primitive-command-panel.tsx`; quit with `Ctrl+C`. Use API Reference for prop-level details.
 
-## Layout Primitives
 
 ### `Screen`
 
-`TerminalScreenProps` props:
+Props:
 
 - `title?: string`
 
-Role: root container. If `title` exists, it renders as the first line of the frame.
+Root container. If `title` is present, it renders as the first line. In a mounted session or render call with dimensions, `Screen` passes the available viewport context to children.
 
 ### `Box`
 
-`TerminalBoxProps` props:
+Props:
 
 - `direction?: "row" | "column"`
 - `gap?: number`
-- `padding?: number`
-- `border?: boolean`
+- `padding?: number | { x?: number; y?: number; top?: number; right?: number; bottom?: number; left?: number }`
+- `style?: string | TerminalStyleDefinition`
+- `styles?: Partial<Record<TerminalVisualState, string | TerminalStyleDefinition>>`
+- `state?: TerminalVisualState | TerminalVisualState[]`
 - `width?: number`
 - `height?: number`
+- `fill?: boolean`
 - `id?: string`
 - `focusable?: boolean`
 
-Role: layout container. In `row`, it composes horizontally; in `column`, vertically.
+Layout container. `Box`, `View`, and `Pane` behave like block elements in a sized context: they use available width by default and keep content height by default, so stacked containers do not all become full-height. Numeric dimensions constrain the final frame and explicit `width` or `height` wins over context defaults. Use `fill` when a surface should consume the full available height as well as width. Put background fill, border, and padding in `style` or a `theme.styles` recipe. Margin is not supported; compose spacing with layout, padding, and explicit text when needed.
 
 ### `View`
 
-`TerminalViewProps` props:
+Props: layout props from `Box`, plus `role?: string`.
 
-- all layout props from `Box`
-- `role?: string`
+Semantic layout container with the same sizing behavior as `Box`.
 
-Role: semantic container equivalent to `terminal-view`.
+### `Pane`
 
-### `Text`
+Props: layout props from `Box`.
 
-`TerminalTextProps` props:
+Named layout boundary for composing terminal regions.
 
-- `value?: any`
+### `Split`
+
+Props:
+
+- `direction?: "row" | "column"`
+- `width?: number`
+- `height?: number`
+- `fill?: boolean`
+- `sizes?: Array<number | `${number}%` | `${number}fr`>`
+- `breakpoints?: Array<{ maxCols?: number; maxRows?: number; direction?: "row" | "column"; sizes?: TerminalSplitSize[]; gap?: number }>`
+- `gap?: number`
+- `id?: string`
+- `focusable?: boolean`
+
+Split layout. Split uses the available render area when width and height are omitted inside a sized context. In `row`, it divides width; in `column`, it divides height. `sizes` may mix absolute numbers, percentages, and `fr` units. Percentages and fractions use the available axis after gaps. Rounding is deterministic: floor the ideal sizes, then give remaining cells to the largest fractional remainders with index order as the tie breaker. Breakpoints are local to the resolved split width and height, and the first matching breakpoint wins. Run `bun examples/docs/responsive-split.tsx`, resize the terminal to change the layout, and quit with `Ctrl+C`; or open [`examples/docs/responsive-split.tsx`](../examples/docs/responsive-split.tsx).
+
+## Visual states
+
+State families:
+
+| Family | States |
+| --- | --- |
+| Common | `focus`, `hover`, `disabled`, `loading` |
+| Activation/controls | `pressed`, `checked`, `unchecked`, `indeterminate` |
+| Selection/navigation | `selected`, `current`, `expanded`, `collapsed` |
+| Entry/text | `invalid`, `valid`, `readonly`, `placeholder`, `selection`, `editing`, `submitted` |
+| Data/content | `empty`, `error`, `warning`, `success`, `muted` |
+| Pointer/capture/composition | `dragging`, `dropTarget`, `capturing` |
+
+Buttons, inputs, editors, lists, tables, panes, boxes, overlays, scroll views, log views, and text can use `style`, `styles`, and `state` where the style affects their rendered frame. Use renderer-owned states such as focus or selection when the component knows them, and use `state` for app-owned statuses such as loading, warning, success, dragging, or drop target.
+
+Shared visual props for styled primitives:
+
+- `style?: string | TerminalStyleDefinition` - base style recipe or inline style.
+- `styles?: Partial<Record<TerminalVisualState, string | TerminalStyleDefinition>>` - visual-state style map.
+- `state?: TerminalVisualState | TerminalVisualState[]` - app-owned visual state or states.
 
-Role: renders `value` or the concatenated text from its children. If there are line breaks, they are preserved.
+### `Fixed`
 
-### `Table`
+Props:
 
-`TerminalTableProps` props:
+- `position: "top" | "bottom" | "left" | "right"`
+- `size: number`
 
-- `v-for?: any[]`
+Direct-child marker consumed by `Screen` and `Pane` to reserve stable rows or columns.
 
-Role: composes rows and automatically calculates the maximum width for each column.
+### `Overlay`
 
-### `Row`
+Props:
 
-`TerminalRowProps` props:
+- `x: number`
+- `y: number`
+- `width: number`
+- `height: number`
+- shared visual props: `style`, `styles`, `state`
+- `trapFocus?: boolean`
+- `id?: string`
+- `focusable?: boolean`
+
+Draws a clipped region over the current frame. Use it for popovers and lightweight dialog-like surfaces. `trapFocus` keeps traversal inside the overlay while it is active.
+
+Overlay keeps focused surfaces clipped and positioned; app routing and pane movement stay in your app layer.
+
+### `FocusScope`
+
+Props:
 
-- `separator?: string`
+- `active?: boolean`
 
-Role: joins cells using `separator` or `" | "` by default.
+Bounds sequential focus traversal to descendants when focus is already inside the scope.
 
-### `Td`
+### `Text`
+
+Props:
 
-`TerminalTdProps` props:
+- `value?: any`
+- shared visual props: `style`, `styles`, `state`
 
-- `padding?: number`
+Renders `value` or child text. Line breaks are preserved.
 
-Role: wraps cell content and applies internal padding when defined.
+### `Table`, `Row`, and `Td`
 
-## Interactive Primitives
+`Table` composes rows and calculates column widths. `Row` joins cells with `separator?: string`. `Td` supports `padding?: number` and shared visual props: `style`, `styles`, `state`.
 
-All of them depend on `id` to fully participate in focus, hitboxes, coordinate lookup, and several `TerminalSession` helpers.
+## Interactive primitives
 
 ### `Input`
 
-`TerminalInputProps` props:
+Props:
 
 - `id?: string`
 - `focusable?: boolean`
 - `value?: string`
 - `placeholder?: string`
+- shared visual props: `style`, `styles`, `state`
 - `onchange?(event)`
 - `oninput?(event)`
 - `onsubmit?(event)`
-- `onChangeText?(value)`
 
-Current interaction support:
-
-- cursor movement and text selection
-- `LEFT`, `RIGHT`, `SHIFT_LEFT`, `SHIFT_RIGHT`
-- `ALT_LEFT`, `ALT_RIGHT`, `HOME`, `END`
-- `CTRL_A`, `CTRL_C`, `CTRL_X`, `CTRL_V`
-- `BACKSPACE`, `DELETE`, character input, and `ENTER`
-
-Important payloads:
+Payloads:
 
 - `TerminalInputChangeEventPayload` - `{ type: "change" | "input", id, value }`
 - `TerminalInputSubmitEventPayload` - `{ type: "submit", id, value }`
 
+Supports single-line editing, cursor movement, selection, copy/cut/paste, deletion, and submit.
+
+### `Editor`
+
+Props:
+
+- `id?: string`
+- `focusable?: boolean`
+- `value?: string`
+- `placeholder?: string`
+- `height?: number`
+- shared visual props: `style`, `styles`, `state`
+- `onchange?(event)`
+- `oninput?(event)`
+- `onsubmit?(event)`
+- `oncancel?(event)`
+
+Payloads:
+
+- `TerminalEditorChangeEventPayload` - `{ type: "change" | "input", id, value }`
+- `TerminalEditorSubmitEventPayload` - `{ type: "submit", id, value }`
+- `TerminalEditorCancelEventPayload` - `{ type: "cancel", id, value }`
+
+Supports multiline editing, submit, cancel, cursor movement, paste, and deletion. Cursor columns use JavaScript string columns rather than a complete terminal-width model.
+
 ### `Button`
 
-`TerminalButtonProps` props:
+Props:
 
 - `id?: string`
 - `focusable?: boolean`
 - `label?: string`
+- shared visual props: `style`, `styles`, `state`
 - `onpress?(event)`
 - `onclick?(event)`
 - `action?(event)`
-- `onPress?(event)`
-
-Current activation paths:
 
-- `session.click(id?)`
-- `session.clickAt(x, y)`
-- `dispatchKey("ENTER")` or `dispatchKey("SPACE")` when focus is on the button
-
-Important payload:
+Payload:
 
 - `TerminalButtonPressEventPayload` - `{ type: "press" | "click", id }`
 
+Activation paths include focused `ENTER`, focused `SPACE`, `session.click(id)`, and `session.clickAt(x, y)`.
+
 ### `List<T>`
 
-`TerminalListProps<T>` props:
+Props:
 
 - `id?: string`
 - `focusable?: boolean`
 - `pointerCapture?: boolean`
 - `items?: T[]`
+- `virtualized?: boolean`
+- `itemHeight?: 1`
+- `overscan?: number`
+- shared visual props: `style`, `styles`, `state`
 - `renderItem?(item, index): string`
 - `onchange?(event)`
 - `onpress?(event)`
@@ -195,25 +347,20 @@ Important payload:
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
-Current interaction:
-
-- `UP` and `LEFT` move selection up
-- `DOWN` and `RIGHT` move selection down
-- `ENTER` triggers `onpress`
-- mouse hover exposes row, index, and value
-
-Important payloads:
+Payloads:
 
 - `TerminalListChangeEventPayload<T>` - `{ type: "change", id, index, value }`
 - `TerminalListPressEventPayload<T>` - `{ type: "press", id, index, value }`
 - `TerminalListPointerEventPayload<T>` - `{ type: "hover" | "rowenter" | "rowleave", id, row, index, value, x, y }`
 - `TerminalCaptureEventPayload` - `{ type: "capturestart" | "captureend", id, source, row, x, y }`
 
+Supports selection, activation, hover payloads, optional virtualization, and pointer capture.
+
 ### `ScrollView`
 
-`TerminalScrollViewProps` props:
+Props:
 
-- layout props (`direction`, `gap`, `padding`, `border`, `width`, `height`, `id`, `focusable`)
+- layout props: `direction`, `gap`, `padding`, `width`, `height`, `fill`, `id`, `focusable`, `style`, `styles`, `state`
 - `pointerCapture?: boolean`
 - `highlightRows?: number[]`
 - `onhover?(event)`
@@ -222,52 +369,71 @@ Important payloads:
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
-Current interaction:
-
-- `UP` and `DOWN` adjust the vertical offset when it has focus
-- rendering clips visible content based on `height`
-- `highlightRows` marks specific visible rows
-- mouse hover exposes the visible row and rendered text
-
-Important payloads:
+Payloads:
 
 - `TerminalScrollPointerEventPayload` - `{ type: "hover" | "rowenter" | "rowleave", id, row, value, x, y }`
 - `TerminalCaptureEventPayload` - `{ type: "capturestart" | "captureend", id, source, row, x, y }`
 
+Clips vertical content and supports keyboard scrolling, highlighted rows, hover payloads, and pointer capture.
+
+### `LogView`
+
+Props:
+
+- layout props: `direction`, `gap`, `padding`, `width`, `height`, `fill`, `id`, `focusable`, `style`, `styles`, `state`
+- `entries?: readonly TerminalLogViewEntry[]`
+- `followTail?: boolean`
+- `emptyText?: string`
+- `renderEntry?(entry, index): string`
+
+Entry shape:
+
+- `TerminalLogViewEntry` - `{ id: string, content: string }`
+
+Renders append-only logs and transcript-like panes. `followTail` keeps the visible frame at the bottom of the rendered entries. Use `followTail` as the `LogView` option for bottom-pinned transcript views while log storage and export stay in the app layer.
+
+## Render subpath exports
+
+The `@valyrianjs/terminal/render` subpath exports:
+
+- `renderTerminal(input): string`
+- `renderTerminalNode(node): string`
+- `renderTerminalFrame(node): TerminalFrame`
+
+These functions are useful for render-only integrations that should not import session runtime helpers.
+
 ## `TerminalSession`
 
-Public contract for the interactive session.
-
-- `update(): string` - resolves the root again and returns the current plain-text output
-- `output(): string` - returns the last rendered plain frame
-- `ansiOutput(): string` - returns the current frame serialized as ANSI
-- `tree(): TerminalNode[]` - exposes the current resolved terminal tree
-- `focus(id: string): boolean` - focuses an interactive node by `id`
-- `focusAt(x: number, y: number): boolean` - focuses by computed hitbox
-- `focusNext(): boolean` - moves focus forward in render order
-- `focusPrev(): boolean` - moves focus backward in render order
-- `dispatchKey(key: string): string` - injects a normalized key and returns the current output
-- `click(id?: string): string` - activates the focused button or a specific one by `id`
-- `clickAt(x: number, y: number): string` - activates or focuses using coordinates
-- `clipboard(): string` - returns the last clipboard value known by the session
-- `setClipboard(value: string): string` - updates the internal clipboard and, if present, the adapter
-- `selectAll(): string` - selects all content in the focused `Input`
-- `destroy(): void` - removes `stdin` listeners, exits raw mode, and pauses the stream when applicable
-
-## Relevant Utility Types
-
-- `TerminalMountOptions` - options for mounting the session
-- `TerminalClipboardAdapter` - minimum contract for integrating an external clipboard
-- `TerminalFrame` - rendered frame with `lines`, `hitboxes`, `cursor`, and `spans`
-- `TerminalHitbox` - computed interactive region for focus and coordinate-based clicks
-- `TerminalStyleSpan` - visual marker such as `selection`, `focus`, or `highlight`
-- `TerminalNode`, `TerminalElementNode`, `TerminalTextNode` - resolved terminal tree
-- `TerminalLayoutProps` - shared base for `Box`, `View`, and `ScrollView`
-- `TerminalFocusableProps` - `id` and `focusable`
-- `TerminalPointerCaptureProps` - `pointerCapture` for lists and scroll views
-- `InputInteractionState` - cursor position and selection anchor
-- `TerminalChangeEventPayload` - union of `Input` and `List` change events
-- `TerminalPressEventPayload` - union of `Button` and `List` press events
-- `TerminalPointerCoordinates` - optional `x` and `y` coordinates in mouse payloads
-- `TerminalMouseEventType` - `"hover" | "rowenter" | "rowleave"`
-- `TerminalPointerSource` - `"press" | "drag" | "release"`
+- `size(): TerminalSize` - returns `{ cols, rows }`.
+- `resize(cols: number, rows: number): void` - validates and stores a new size, then rerenders.
+- `update(): string` - rerenders and returns plain text.
+- `output(): string` - returns the current plain-text frame.
+- `ansiOutput(): string` - returns the current ANSI frame.
+- `tree(): TerminalNode[]` - returns the current resolved terminal tree.
+- `focus(id: string): boolean` - focuses a node by id.
+- `focusAt(x: number, y: number): boolean` - focuses by coordinates.
+- `focusNext(): boolean` - moves focus forward.
+- `focusPrev(): boolean` - moves focus backward.
+- `dispatchKey(key: string): string` - dispatches a normalized key and returns plain text.
+- `click(id?: string): string` - activates the focused button or a button by id.
+- `clickAt(x: number, y: number): string` - activates or focuses by coordinates.
+- `clipboard(): string` - returns the session clipboard buffer.
+- `setClipboard(value: string): string` - updates the session clipboard buffer and adapter when present.
+- `selectAll(): string` - selects all content in the focused `Input`.
+- `destroy(): void` - removes listeners and restores supported terminal state.
+
+## Package scope
+
+- Use the package for terminal primitives, rendering, sessions, focus, input, and output.
+- Compose command-palette surfaces with `Overlay`, `FocusScope`, `Input`, `List`, and `Button`.
+- Keep log storage, export, routing, and business rules in your app layer.
+- Use semantic text and styles for rendered content; reserve terminal escape control for documented integration paths.
+- Host features such as resize, mouse input, and modified keys follow the terminal/runtime environment.
+
+## Related docs
+
+- [Getting Started](./getting-started.md) for the first project.
+- [Core Concepts](./core-concepts.md) for the mental model.
+- [Cookbook](./cookbook.md) for practical recipes.
+- [Interaction Model](./interaction-model.md) for behavior by primitive.
+- [Session Runtime](./session-runtime.md) for host integration.

package/docs/assets/quick-note.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="220" viewBox="0 0 640 220" role="img" aria-labelledby="title desc">
+  <title id="title">Quick note terminal result</title>
+  <desc id="desc">A terminal window with a quick note app, an input hint, and Ctrl+C exit guidance.</desc>
+  <rect width="640" height="220" rx="18" fill="#0d1117"/>
+  <rect x="24" y="24" width="592" height="172" rx="12" fill="#161b22" stroke="#30363d"/>
+  <circle cx="52" cy="52" r="6" fill="#ff7b72"/>
+  <circle cx="72" cy="52" r="6" fill="#f2cc60"/>
+  <circle cx="92" cy="52" r="6" fill="#56d364"/>
+  <text x="44" y="92" fill="#e6edf3" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="18">Quick note</text>
+  <text x="44" y="124" fill="#8b949e" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="16">Type a note. Ctrl+C: exit.</text>
+  <rect x="44" y="144" width="360" height="28" rx="6" fill="#0d1117" stroke="#58a6ff"/>
+  <text x="58" y="164" fill="#c9d1d9" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="15">Write a note</text>
+</svg>