@valyrianjs/terminal 0.1.0 → 0.1.2

package/docs/api-reference.md

@@ -1,191 +1,343 @@
 # API Reference
 
-Referencia de la superficie publica real publicada por `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).
 
-## Entrypoints publicados
+## Published entrypoints
 
-### `valyrianjs-terminal`
+### `@valyrianjs/terminal`
 
-Entrada principal. Expone a alto nivel:
+Main entrypoint for terminal primitives, rendering, sessions, props, payloads, and types.
 
-- `renderTerminal()`
-- `mountTerminal()`
-- primitivas `Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `ScrollView`, `List`, `Table`, `Row`, `Td`
-- tipos de props, eventos, nodos y sesion
+Common imports:
 
-### `valyrianjs-terminal/render`
+```tsx
+import { Screen, Text, mountTerminal, renderTerminal } from "@valyrianjs/terminal";
+```
 
-Subpath publicado para utilidades de render de bajo nivel.
+### `@valyrianjs/terminal/render`
+
+Rendering-only subpath for lower-level rendering utilities:
 
 - `renderTerminal(input): string`
 - `renderTerminalNode(node): string`
 - `renderTerminalFrame(node): TerminalFrame`
 
-Usa este subpath cuando solo necesites transformar nodos terminales a texto o `TerminalFrame`, sin montar una sesion interactiva.
+Use this subpath for rendering-focused integrations that produce output without mounting an interactive session.
 
-## Funciones principales
+## 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.
 
-Resuelve la raiz recibida y devuelve la salida terminal en texto plano.
+## Main functions
 
-Casos de uso respaldados por la implementacion actual:
+### `renderTerminal(input): string`
 
-- snapshots y pruebas
-- validacion de layout sin `stdin` ni `stdout`
-- inspeccion de contenido en modo no interactivo
+Resolves the provided terminal tree and returns plain text.
 
-Notas:
+Use it for:
 
-- concatena los nodos raiz con saltos de linea
-- elimina solo el whitespace final con `trimEnd()`
-- no crea listeners ni estado interactivo
+- snapshots
+- static examples
+- non-interactive command output
+- layout checks without session state
 
 ### `mountTerminal(input, options?): TerminalSession`
 
-Monta una sesion interactiva sobre el arbol terminal y devuelve un `TerminalSession`.
+Creates an interactive session around a terminal tree.
 
-Comportamiento de alto nivel:
+The session can:
 
-- resuelve el arbol actual y lo rerenderiza con `session.update()`
-- administra foco por `id`
-- procesa teclado, mouse, seleccion y clipboard
-- puede escribir automaticamente a `stdout` si se provee
-- si recibe `stdin`, activa raw mode al montar y lo revierte en `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` - si hay `stdout`, escribe diffs ANSI en vez de texto plano
-- `clipboard?: TerminalClipboardAdapter | false` - adapter custom o desactiva el clipboard del sistema
-- `stdin?` - stream con `on("data")`; `off()`, `removeListener()`, `setRawMode()`, `resume()` y `pause()` son opcionales
-- `stdout?` - writer con `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.
 
-## Primitivas de layout
 
 ### `Screen`
 
-Props de `TerminalScreenProps`:
+Props:
 
 - `title?: string`
 
-Funcion: contenedor raiz. Si `title` existe, se renderiza como primera linea del 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`
 
-Props de `TerminalBoxProps`:
+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`
 
-Funcion: contenedor de layout. En `row` compone horizontalmente; en `column`, verticalmente.
+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`
 
-Props de `TerminalViewProps`:
+Props: layout props from `Box`, plus `role?: string`.
 
-- todas las props de layout de `Box`
-- `role?: string`
+Semantic layout container with the same sizing behavior as `Box`.
 
-Funcion: contenedor semantico equivalente a `terminal-view`.
+### `Pane`
 
-### `Text`
+Props: layout props from `Box`.
 
-Props de `TerminalTextProps`:
+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.
 
-Funcion: renderiza `value` o el texto concatenado de sus hijos. Si hay saltos de linea, se preservan.
+### `Fixed`
 
-### `Table`
+Props:
 
-Props de `TerminalTableProps`:
+- `position: "top" | "bottom" | "left" | "right"`
+- `size: number`
 
-- `v-for?: any[]`
+Direct-child marker consumed by `Screen` and `Pane` to reserve stable rows or columns.
 
-Funcion: compone filas y calcula automaticamente el ancho maximo por columna.
+### `Overlay`
 
-### `Row`
+Props:
 
-Props de `TerminalRowProps`:
+- `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`
 
-Funcion: une celdas usando `separator` o `" | "` por default.
+Bounds sequential focus traversal to descendants when focus is already inside the scope.
 
-### `Td`
+### `Text`
+
+Props:
 
-Props de `TerminalTdProps`:
+- `value?: any`
+- shared visual props: `style`, `styles`, `state`
 
-- `padding?: number`
+Renders `value` or child text. Line breaks are preserved.
 
-Funcion: envuelve el contenido de la celda y aplica padding interno si se define.
+### `Table`, `Row`, and `Td`
 
-## Primitivas interactivas
+`Table` composes rows and calculates column widths. `Row` joins cells with `separator?: string`. `Td` supports `padding?: number` and shared visual props: `style`, `styles`, `state`.
 
-Todas dependen de `id` para participar completamente en foco, hitboxes, busqueda por coordenadas y varios helpers de `TerminalSession`.
+## Interactive primitives
 
 ### `Input`
 
-Props de `TerminalInputProps`:
+Props:
 
 - `id?: string`
 - `focusable?: boolean`
 - `value?: string`
 - `placeholder?: string`
+- shared visual props: `style`, `styles`, `state`
 - `onchange?(event)`
 - `oninput?(event)`
 - `onsubmit?(event)`
-- `onChangeText?(value)`
 
-Soporte actual de interaccion:
-
-- cursor y seleccion de texto
-- `LEFT`, `RIGHT`, `SHIFT_LEFT`, `SHIFT_RIGHT`
-- `ALT_LEFT`, `ALT_RIGHT`, `HOME`, `END`
-- `CTRL_A`, `CTRL_C`, `CTRL_X`, `CTRL_V`
-- `BACKSPACE`, `DELETE`, escritura de caracteres y `ENTER`
-
-Payloads importantes:
+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`
 
-Props de `TerminalButtonProps`:
+Props:
 
 - `id?: string`
 - `focusable?: boolean`
 - `label?: string`
+- shared visual props: `style`, `styles`, `state`
 - `onpress?(event)`
 - `onclick?(event)`
 - `action?(event)`
-- `onPress?(event)`
-
-Activacion actual:
 
-- `session.click(id?)`
-- `session.clickAt(x, y)`
-- `dispatchKey("ENTER")` o `dispatchKey("SPACE")` cuando el foco esta en el boton
-
-Payload importante:
+Payload:
 
 - `TerminalButtonPressEventPayload` - `{ type: "press" | "click", id }`
 
+Activation paths include focused `ENTER`, focused `SPACE`, `session.click(id)`, and `session.clickAt(x, y)`.
+
 ### `List<T>`
 
-Props de `TerminalListProps<T>`:
+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 @@ Props de `TerminalListProps<T>`:
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
-Interaccion actual:
-
-- `UP` y `LEFT` mueven la seleccion hacia arriba
-- `DOWN` y `RIGHT` mueven la seleccion hacia abajo
-- `ENTER` dispara `onpress`
-- el hover por mouse expone fila, indice y valor
-
-Payloads importantes:
+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`
 
-Props de `TerminalScrollViewProps`:
+Props:
 
-- props de layout (`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 @@ Props de `TerminalScrollViewProps`:
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
-Interaccion actual:
-
-- `UP` y `DOWN` ajustan el offset vertical cuando tiene foco
-- el render recorta el contenido visible segun `height`
-- `highlightRows` marca filas visibles concretas
-- el hover por mouse expone fila visible y texto renderizado
-
-Payloads importantes:
+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`
 
-Contrato publico de la sesion interactiva.
-
-- `update(): string` - vuelve a resolver la raiz y retorna la salida actual en texto plano
-- `output(): string` - devuelve el ultimo frame plano renderizado
-- `ansiOutput(): string` - devuelve el frame actual serializado con ANSI
-- `tree(): TerminalNode[]` - expone el arbol terminal resuelto actual
-- `focus(id: string): boolean` - enfoca un nodo interactivo por `id`
-- `focusAt(x: number, y: number): boolean` - enfoca por hitbox calculado
-- `focusNext(): boolean` - recorre el foco en orden de render
-- `focusPrev(): boolean` - recorre el foco hacia atras
-- `dispatchKey(key: string): string` - inyecta una tecla normalizada y devuelve la salida actual
-- `click(id?: string): string` - activa el boton enfocado o uno especifico por `id`
-- `clickAt(x: number, y: number): string` - activa o enfoca usando coordenadas
-- `clipboard(): string` - devuelve el ultimo valor de clipboard conocido por la sesion
-- `setClipboard(value: string): string` - actualiza el clipboard interno y, si existe, el adapter
-- `selectAll(): string` - selecciona todo el contenido del `Input` enfocado
-- `destroy(): void` - desmonta listeners de `stdin`, sale de raw mode y pausa el stream si aplica
-
-## Tipos utilitarios relevantes
-
-- `TerminalMountOptions` - opciones para montar la sesion
-- `TerminalClipboardAdapter` - contrato minimo para integrar clipboard externo
-- `TerminalFrame` - frame renderizado con `lines`, `hitboxes`, `cursor` y `spans`
-- `TerminalHitbox` - region interactiva calculada para foco y clicks por coordenadas
-- `TerminalStyleSpan` - marca visual como `selection`, `focus` o `highlight`
-- `TerminalNode`, `TerminalElementNode`, `TerminalTextNode` - arbol terminal resuelto
-- `TerminalLayoutProps` - base comun para `Box`, `View` y `ScrollView`
-- `TerminalFocusableProps` - `id` y `focusable`
-- `TerminalPointerCaptureProps` - `pointerCapture` para listas y scroll
-- `InputInteractionState` - posicion de cursor y ancla de seleccion
-- `TerminalChangeEventPayload` - union de cambios de `Input` y `List`
-- `TerminalPressEventPayload` - union de presses de `Button` y `List`
-- `TerminalPointerCoordinates` - coordenadas `x` y `y` opcionales en payloads de mouse
-- `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>