@valyrianjs/terminal 0.1.2 → 0.2.0

package/docs/interaction-model.md

@@ -41,12 +41,14 @@ Supported behavior includes:
 - 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`
 
@@ -84,8 +86,10 @@ Activation paths:
 Main handlers:
 
 - `onpress`
-- `onclick`
-- `action`
+- `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`
 
@@ -97,11 +101,15 @@ Supported behavior includes:
 - `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`
@@ -120,12 +128,14 @@ Supported behavior includes:
 - `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`
 

package/docs/primitive-gallery.md

@@ -133,14 +133,19 @@ Use `Split` for resizable shells and master/detail layouts.
 
 Use `Fixed` for headers, footers, rails, and persistent status bars.
 
-**What it is:** A reserved region attached to an edge of `Screen` or `Pane`.
+**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
-<Fixed position="bottom" size={1}><Text>Ctrl+C: quit</Text></Fixed>
+<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`.
@@ -155,7 +160,7 @@ 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`.
+**Core props:** `id`, `value`, `placeholder`, `onchange`, `oninput`, `onsubmit`, `oncontextpress`.
 
 **Minimal example:**
 
@@ -187,7 +192,7 @@ Use `Button` for save actions, confirmations, command triggers, and app actions.
 
 **What it is:** A focusable action control.
 **Use it for:** save actions, confirmations, command triggers, and app actions.
-**Core props:** `id`, `label`, `onpress`, `onclick`, `action`, `style`, `styles`, `state`.
+**Core props:** `id`, `label`, `onpress`, `ondoublepress`, `oncontextpress`, `style`, `styles`, `state`.
 
 **Minimal example:**
 
@@ -223,7 +228,7 @@ 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`.
+**Core props:** `id`, `items`, `renderItem`, `virtualized`, `onchange`, `onpress`, `ondoublepress`, `oncontextpress`.
 
 **Minimal example:**
 
@@ -291,7 +296,7 @@ Use `ScrollView` for long instructions, timelines, and scrollable panels.
 
 **What it is:** A bounded viewport for child content.
 **Use it for:** long instructions, timelines, and scrollable panels.
-**Core props:** `id`, `height`, `highlightRows`, `pointerCapture`, row pointer events.
+**Core props:** `id`, `height`, `highlightRows`, `pointerCapture`, `oncontextpress`, row pointer events.
 
 **Minimal example:**
 
@@ -327,12 +332,12 @@ Use `Overlay` for command panels, dialogs, palettes, and focused chooser surface
 
 **What it is:** A positioned layer over the current frame.
 **Use it for:** command panels, dialogs, palettes, and focused chooser surfaces.
-**Core props:** `id`, `x`, `y`, `width`, `height`, `trapFocus`, `style`.
+**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 x={4} y={2} width={40} height={8} trapFocus><Text>Command Panel</Text></Overlay>
+<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`.
@@ -348,7 +353,7 @@ Use `FocusScope` to keep input, lists, and actions together inside a panel.
 **Minimal example:**
 
 ```tsx
-<Overlay x={2} y={2} width={32} height={8} trapFocus><FocusScope><Input id="query" /><List id="commands" items={commands} /></FocusScope></Overlay>
+<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`.

package/llms-full.txt

@@ -530,7 +530,7 @@ Focus belongs to the `TerminalSession`; app state remains yours. `FocusScope` ca
 
 ## Styling and visual states
 
-Use `theme.styles` for named recipes with hex colors, border, and padding. The default theme already gives `Button`, `Input`, and `List` app-like base, focus, selection, current, hover, loading, and disabled styles, so `<Button><Text>Ok</Text></Button>` renders as a styled control without per-instance chrome. Components still use `style` for their base recipe, `styles` to map visual states to recipes, and `state` when the app owns a visual status. Raw span serialization tokens belong to low-level renderer integrations; normal styling uses semantic styles and hex colors.
+Use `theme.styles` for named recipes with hex colors, border, and padding. The default theme already gives `Button`, `Input`, and `List` app-like base, focus, selection, current, hover, loading, and disabled styles, so `<Button><Text>Ok</Text></Button>` renders as a styled control without per-instance chrome. When a primitive has a matching `<element>.base` recipe, the renderer applies it automatically before instance styles. Components still use `style` for their base recipe, `styles` to map visual states to recipes, and `state` when the app owns a visual status. Raw span serialization tokens belong to low-level renderer integrations; normal styling uses semantic styles and hex colors.
 
 Related example: [`examples/docs/style-system.tsx`](../examples/docs/style-system.tsx). Run it with `bun examples/docs/style-system.tsx`, try `Tab`, `Enter`, and `W`, and quit with `Ctrl+C`.
 
@@ -756,7 +756,7 @@ function App() {
   return (
     <Screen title="Overlay recipe">
       <Text>{state.executed ? `Executed: ${state.executed}` : "Choose a command"}</Text>
-      <Overlay x={2} y={2} width={40} height={6} trapFocus>
+      <Overlay margin={{ x: 2, y: 2 }} trapFocus>
         <FocusScope>
           <Input
             id="query"
@@ -1101,14 +1101,19 @@ Use `Split` for resizable shells and master/detail layouts.
 
 Use `Fixed` for headers, footers, rails, and persistent status bars.
 
-**What it is:** A reserved region attached to an edge of `Screen` or `Pane`.
+**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
-<Fixed position="bottom" size={1}><Text>Ctrl+C: quit</Text></Fixed>
+<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`.
@@ -1123,7 +1128,7 @@ 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`.
+**Core props:** `id`, `value`, `placeholder`, `onchange`, `oninput`, `onsubmit`, `oncontextpress`.
 
 **Minimal example:**
 
@@ -1155,7 +1160,7 @@ Use `Button` for save actions, confirmations, command triggers, and app actions.
 
 **What it is:** A focusable action control.
 **Use it for:** save actions, confirmations, command triggers, and app actions.
-**Core props:** `id`, `label`, `onpress`, `onclick`, `action`, `style`, `styles`, `state`.
+**Core props:** `id`, `label`, `onpress`, `ondoublepress`, `oncontextpress`, `style`, `styles`, `state`.
 
 **Minimal example:**
 
@@ -1191,7 +1196,7 @@ 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`.
+**Core props:** `id`, `items`, `renderItem`, `virtualized`, `onchange`, `onpress`, `ondoublepress`, `oncontextpress`.
 
 **Minimal example:**
 
@@ -1259,7 +1264,7 @@ Use `ScrollView` for long instructions, timelines, and scrollable panels.
 
 **What it is:** A bounded viewport for child content.
 **Use it for:** long instructions, timelines, and scrollable panels.
-**Core props:** `id`, `height`, `highlightRows`, `pointerCapture`, row pointer events.
+**Core props:** `id`, `height`, `highlightRows`, `pointerCapture`, `oncontextpress`, row pointer events.
 
 **Minimal example:**
 
@@ -1295,12 +1300,12 @@ Use `Overlay` for command panels, dialogs, palettes, and focused chooser surface
 
 **What it is:** A positioned layer over the current frame.
 **Use it for:** command panels, dialogs, palettes, and focused chooser surfaces.
-**Core props:** `id`, `x`, `y`, `width`, `height`, `trapFocus`, `style`.
+**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 x={4} y={2} width={40} height={8} trapFocus><Text>Command Panel</Text></Overlay>
+<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`.
@@ -1316,7 +1321,7 @@ Use `FocusScope` to keep input, lists, and actions together inside a panel.
 **Minimal example:**
 
 ```tsx
-<Overlay x={2} y={2} width={32} height={8} trapFocus><FocusScope><Input id="query" /><List id="commands" items={commands} /></FocusScope></Overlay>
+<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`.
@@ -1379,12 +1384,14 @@ Supported behavior includes:
 - 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`
 
@@ -1422,8 +1429,10 @@ Activation paths:
 Main handlers:
 
 - `onpress`
-- `onclick`
-- `action`
+- `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`
 
@@ -1435,11 +1444,15 @@ Supported behavior includes:
 - `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`
@@ -1458,12 +1471,14 @@ Supported behavior includes:
 - `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`
 
@@ -4936,9 +4951,9 @@ import { Screen, Text, mountTerminal, renderTerminal } from "@valyrianjs/termina
 
 Rendering-only subpath for lower-level rendering utilities:
 
-- `renderTerminal(input): string`
-- `renderTerminalNode(node): string`
-- `renderTerminalFrame(node): TerminalFrame`
+- `renderTerminal(input, context?): string`
+- `renderTerminalNode(node, context?): string`
+- `renderTerminalFrame(node, context?): TerminalFrame`
 
 Use this subpath for rendering-focused integrations that produce output without mounting an interactive session.
 
@@ -4948,9 +4963,9 @@ The root entrypoint exports the public primitives (`Screen`, `Box`, `View`, `Pan
 
 ## Main functions
 
-### `renderTerminal(input): string`
+### `renderTerminal(input, context?): string`
 
-Resolves the provided terminal tree and returns plain text.
+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`.
 
 Use it for:
 
@@ -4959,6 +4974,8 @@ Use it for:
 - 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`
 
 Creates an interactive session around a terminal tree.
@@ -5013,7 +5030,7 @@ Theme recipes belong in `theme.styles`. Use `color`, `background`, padding, and
 
 ## 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.
+`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:
 
@@ -5023,7 +5040,7 @@ Use `style`, `styles`, and `state` for normal component styling:
 
 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.
+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:
 
@@ -5141,24 +5158,21 @@ Props:
 - `position: "top" | "bottom" | "left" | "right"`
 - `size: number`
 
-Direct-child marker consumed by `Screen` and `Pane` to reserve stable rows or columns.
+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.
 
 ### `Overlay`
 
 Props:
 
-- `x: number`
-- `y: number`
-- `width: number`
-- `height: number`
+- `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. Use it for popovers and lightweight dialog-like surfaces. `trapFocus` keeps traversal inside the overlay while it is active.
+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 keeps focused surfaces clipped and positioned; app routing and pane movement stay in your app layer.
+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`
 
@@ -5195,13 +5209,15 @@ Props:
 - `onchange?(event)`
 - `oninput?(event)`
 - `onsubmit?(event)`
+- `oncontextpress?(event)`
 
 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, and submit.
+Supports single-line editing, cursor movement, selection, copy/cut/paste, deletion, submit, and context press.
 
 ### `Editor`
 
@@ -5235,14 +5251,14 @@ Props:
 - `label?: string`
 - shared visual props: `style`, `styles`, `state`
 - `onpress?(event)`
-- `onclick?(event)`
-- `action?(event)`
+- `ondoublepress?(event)`
+- `oncontextpress?(event)`
 
 Payload:
 
-- `TerminalButtonPressEventPayload` - `{ type: "press" | "click", id }`
+- `TerminalButtonPressEventPayload` - `{ type: "press" | "doublepress" | "contextpress", id }`
 
-Activation paths include focused `ENTER`, focused `SPACE`, `session.click(id)`, and `session.clickAt(x, y)`.
+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>`
 
@@ -5259,6 +5275,8 @@ Props:
 - `renderItem?(item, index): string`
 - `onchange?(event)`
 - `onpress?(event)`
+- `ondoublepress?(event)`
+- `oncontextpress?(event)`
 - `onhover?(event)`
 - `onrowenter?(event)`
 - `onrowleave?(event)`
@@ -5268,11 +5286,11 @@ Props:
 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, hover payloads, optional virtualization, and pointer capture.
+Supports selection, activation, double press on the same row, context press for the target row, hover payloads, optional virtualization, and pointer capture.
 
 ### `ScrollView`
 
@@ -5284,15 +5302,17 @@ Props:
 - `onhover?(event)`
 - `onrowenter?(event)`
 - `onrowleave?(event)`
+- `oncontextpress?(event)`
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
 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, and pointer capture.
+Clips vertical content and supports keyboard scrolling, highlighted rows, hover payloads, context press for the target visible row, and pointer capture.
 
 ### `LogView`
 
@@ -5314,9 +5334,9 @@ Renders append-only logs and transcript-like panes. `followTail` keeps the visib
 
 The `@valyrianjs/terminal/render` subpath exports:
 
-- `renderTerminal(input): string`
-- `renderTerminalNode(node): string`
-- `renderTerminalFrame(node): TerminalFrame`
+- `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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valyrianjs/terminal",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Terminal adapter for valyrian.js",
   "license": "Apache-2.0",
   "private": false,

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   TerminalFrame,
   TerminalHitbox,
   TerminalInputChangeEventPayload,
+  TerminalInputContextPressEventPayload,
   TerminalInputProps,
   TerminalInputSubmitEventPayload,
   TerminalKeyBinding,
@@ -46,6 +47,7 @@ export type {
   TerminalRowProps,
   TerminalScreenProps,
   TerminalScrollPointerEventPayload,
+  TerminalScrollContextPressEventPayload,
   TerminalScrollViewProps,
   TerminalSemanticStyleKind,
   TerminalSession,
@@ -89,4 +91,5 @@ export {
 } from "./keymap.js";
 export { defaultTerminalTheme, highContrastTerminalTheme, mergeTerminalTheme, resolveTerminalStyle, resolveTerminalStyleToken } from "./theme.js";
 export { renderTerminal } from "./render.js";
+export type { TerminalRenderContext } from "./render.js";
 export { mountTerminal } from "./session.js";

package/src/primitives.ts

@@ -1,7 +1,6 @@
 import { v } from "valyrian.js";
 
 import type {
-  AnyProps,
   TerminalBoxProps,
   TerminalButtonProps,
   TerminalEditorProps,
@@ -23,10 +22,14 @@ import type {
   TerminalViewProps
 } from "./types.js";
 
-type TerminalPrimitiveComponent<P> = (props: P | AnyProps, children: any[]) => any;
+type TerminalPrimitiveComponentProps<P> = P & { children?: any; key?: any };
 
-function primitive<P = Record<string, any>>(tag: TerminalPrimitiveTag): TerminalPrimitiveComponent<P> {
-  return function TerminalPrimitive(props: P | AnyProps, children: any[]) {
+type TerminalPrimitiveComponent<P> = (props: TerminalPrimitiveComponentProps<P>, children: any[]) => any;
+
+type TerminalListComponent = <T>(props: TerminalPrimitiveComponentProps<TerminalListProps<T>>, children: any[]) => any;
+
+function primitive<P>(tag: TerminalPrimitiveTag): TerminalPrimitiveComponent<P> {
+  return function TerminalPrimitive(props: TerminalPrimitiveComponentProps<P> | null | undefined, children: any[]) {
     const nextProps = { ...(props || {}) } as Record<string, any>;
     return v(tag, nextProps, ...children);
   };
@@ -46,7 +49,7 @@ export const Editor = primitive<TerminalEditorProps>("terminal-editor");
 export const Button = primitive<TerminalButtonProps>("terminal-button");
 export const ScrollView = primitive<TerminalScrollViewProps>("terminal-scroll");
 export const LogView = primitive<TerminalLogViewProps>("terminal-log-view");
-export const List = primitive<TerminalListProps<any>>("terminal-list");
+export const List = primitive("terminal-list") as TerminalListComponent;
 export const Table = primitive<TerminalTableProps>("terminal-table");
 export const Row = primitive<TerminalRowProps>("terminal-row");
 export const Td = primitive<TerminalTdProps>("terminal-td");