@valyrianjs/terminal 0.1.1 → 0.2.0

package/docs/api-reference.md

@@ -1,273 +1,444 @@
 # 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`
 
-- `renderTerminal(input): string`
-- `renderTerminalNode(node): string`
-- `renderTerminalFrame(node): TerminalFrame`
+Rendering-only subpath for lower-level rendering utilities:
 
-Use this subpath when you only need to transform terminal nodes into text or a `TerminalFrame`, without mounting an interactive session.
+- `renderTerminal(input, context?): string`
+- `renderTerminalNode(node, context?): string`
+- `renderTerminalFrame(node, context?): TerminalFrame`
 
-## Main Functions
+Use this subpath for rendering-focused integrations that produce output without mounting an interactive session.
 
-### `renderTerminal(input): string`
+## Root exports overview
 
-Resolves the provided root and returns terminal output as plain text.
+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.
 
-Use cases supported by the current implementation:
+## Main functions
 
-- snapshots and tests
-- layout validation without `stdin` or `stdout`
-- content inspection in non-interactive mode
+### `renderTerminal(input, context?): string`
 
-Notes:
+Resolves the provided terminal tree and returns plain text. Pass `{ cols, rows }` when the root tree uses viewport-dependent primitives such as standalone `Overlay` with `margin` or standalone `Fixed`.
 
-- concatenates root nodes with newlines
-- removes only trailing whitespace with `trimEnd()`
-- does not create listeners or interactive state
+Use it for:
+
+- snapshots
+- static examples
+- non-interactive command output
+- layout checks without session state
+
+`context` accepts exact terminal dimensions as positive integers and an optional theme: `{ cols, rows, theme? }`. Mounted sessions infer dimensions from `mountTerminal()` options or the host terminal.
 
 ### `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 renderer applies `theme.styles.<element>.base` automatically to public primitives that have a matching `.base` recipe, before any instance `style`. The bundled default theme uses that rule for app-like 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 also 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 automatic `<element>.base` recipe when the primitive has one, 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 automatic base recipe 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.
 
-Role: renders `value` or the concatenated text from its children. If there are line breaks, they are preserved.
+Shared visual props for styled primitives:
 
-### `Table`
+- `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.
 
-`TerminalTableProps` props:
+### `Fixed`
 
-- `v-for?: any[]`
+Props:
 
-Role: composes rows and automatically calculates the maximum width for each column.
+- `position: "top" | "bottom" | "left" | "right"`
+- `size: number`
 
-### `Row`
+Reserves stable rows or columns at a frame edge. When `Fixed` is a direct child of `Screen` or `Pane`, that parent supplies the frame and consumes the fixed region before it lays out the remaining content. When `Fixed` is rendered as the root tree passed directly to `renderTerminal()`, it is viewport-dependent and the render call must pass exact dimensions with `{ cols, rows }`. Mounted sessions get those dimensions from `mountTerminal()` options or the host terminal.
 
-`TerminalRowProps` props:
+### `Overlay`
 
-- `separator?: string`
+Props:
 
-Role: joins cells using `separator` or `" | "` by default.
+- `margin: number | "<number>%" | { x: number | "<number>%"; y: number | "<number>%" }`
+- shared visual props: `style`, `styles`, `state`
+- `trapFocus?: boolean`
+- `id?: string`
+- `focusable?: boolean`
+
+Draws a clipped region over the current frame. `margin` sets the distance from the overlay to the frame edges; numbers use cells and percentage strings such as `"10%"` resolve per axis. Use `{ x, y }` when the two axes need different margins. `trapFocus` keeps traversal inside the overlay while it is active.
+
+Overlay calculates its size from the available frame, stays centered by its margins, and keeps app routing and pane movement in your app layer.
+
+### `FocusScope`
+
+Props:
 
-### `Td`
+- `active?: boolean`
 
-`TerminalTdProps` props:
+Bounds sequential focus traversal to descendants when focus is already inside the scope.
 
-- `padding?: number`
+### `Text`
+
+Props:
+
+- `value?: any`
+- shared visual props: `style`, `styles`, `state`
+
+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:
+- `oncontextpress?(event)`
 
-- 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 }`
+- `TerminalInputContextPressEventPayload` - `{ type: "contextpress", id, value, cursor, x, y }`
+
+Supports single-line editing, cursor movement, selection, copy/cut/paste, deletion, submit, and context press.
+
+### `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:
+- `ondoublepress?(event)`
+- `oncontextpress?(event)`
 
-- `session.click(id?)`
-- `session.clickAt(x, y)`
-- `dispatchKey("ENTER")` or `dispatchKey("SPACE")` when focus is on the button
+Payload:
 
-Important payload:
+- `TerminalButtonPressEventPayload` - `{ type: "press" | "doublepress" | "contextpress", id }`
 
-- `TerminalButtonPressEventPayload` - `{ type: "press" | "click", id }`
+Activation paths include focused `ENTER`, focused `SPACE`, `session.click(id)`, and `session.clickAt(x, y)`. A quick second primary mouse press still dispatches the normal activation path and also dispatches `ondoublepress` when present. A secondary mouse press dispatches `oncontextpress`.
 
 ### `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)`
+- `ondoublepress?(event)`
+- `oncontextpress?(event)`
 - `onhover?(event)`
 - `onrowenter?(event)`
 - `onrowleave?(event)`
 - `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 }`
+- `TerminalListPressEventPayload<T>` - `{ type: "press" | "doublepress" | "contextpress", 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, double press on the same row, context press for the target row, 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)`
 - `onrowenter?(event)`
 - `onrowleave?(event)`
+- `oncontextpress?(event)`
 - `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 }`
+- `TerminalScrollContextPressEventPayload` - `{ type: "contextpress", 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, context press for the target visible row, 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, context?): string`
+- `renderTerminalNode(node, context?): string`
+- `renderTerminalFrame(node, context?): 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>