@valyrianjs/terminal 0.1.2 → 0.2.1

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`.
 
@@ -666,7 +666,7 @@ console.log(session.output());
 session.destroy();
 ```
 
-For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split.
+For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split. The virtualized workbench shows the normal uncontrolled API with `itemKey`, the `children` callback, event observation, and internal active, selected, and viewport state: [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
 
 ## Local state to Valyrian state module bridge
 
@@ -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,16 +1196,20 @@ 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`, `children` callback, `renderItem`, `itemKey`, `virtualized`, `showActive`, `onchange`, `onviewportchange`, `onpress`, `ondoublepress`, `oncontextpress`. `List` owns its active row, selected row, and viewport state internally; observe those values from event payloads.
 
 **Minimal example:**
 
 ```tsx
-<List id="menu" items={["Inbox", "Done"]} onchange={(event) => { selected = event.value; }} />
+<List id="menu" items={["Inbox", "Done"]} itemKey={(item) => item}>
+  {(item, ctx) => `${ctx.active ? "› " : "  "}${item}`}
+</List>
 ```
 
 **Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
 
+**Virtualized demo:** [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
+
 ### `Table`
 
 Use `Table` for compact data detail and aligned text pairs.
@@ -1259,7 +1268,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 +1304,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. Later sibling overlays paint and receive pointer/focus routing above earlier overlays. Overlay background styles cover their full assigned surface, not just text cells.
 
 **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 +1325,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 +1388,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,24 +1433,32 @@ 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`
 
-`List` models row selection and activation.
+`List` models active row movement, optional visible selection, viewport scroll, and activation. In virtualized mode the component receives the full `items` array and owns the viewport; wheel input moves the viewport, while keyboard list commands move the active row and emit `change`. A JSX `children` callback receives `(item, ctx)` with `ctx.active`, `ctx.selected`, `ctx.index`, `ctx.key`, and `ctx.viewportIndex`; it takes precedence over `renderItem`. Use `itemKey` when rows have stable identities across reorder or filtering.
 
 Supported behavior includes:
 
-- `UP` and `LEFT` move selection up
-- `DOWN` and `RIGHT` move selection down
-- `ENTER` activates the selected row
+- `UP` and `DOWN` move the active row and emit `onchange`
+- `PageUp`, `PageDown`, `Home`, and `End` jump the active row and keep it visible
+- `LEFT` and `RIGHT` have no default list command, so applications can bind them
+- `ENTER` selects and activates the active row
+- mouse click selects and activates the target row
 - mouse hover reports row details when mouse input is connected
+- quick primary mouse clicks on the same row emit `ondoublepress` without a second `onpress`
+- secondary mouse presses emit `oncontextpress` for the target row
 
 Main handlers:
 
 - `onchange`
 - `onpress`
+- `ondoublepress`
+- `oncontextpress`
 - `onhover`
 - `onrowenter`
 - `onrowleave`
@@ -1458,12 +1477,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 +4957,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 +4969,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 +4980,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 +5036,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 +5046,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 +5164,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. Direct sibling overlays use source order: later overlays paint above earlier overlays, receive pointer hits first, and lead trapped focus traversal. Overlay styles paint the full assigned surface, including empty cells behind child controls.
 
 ### `FocusScope`
 
@@ -5195,13 +5215,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 +5257,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>`
 
@@ -5253,12 +5275,20 @@ Props:
 - `pointerCapture?: boolean`
 - `items?: T[]`
 - `virtualized?: boolean`
+- `height?: number`
 - `itemHeight?: 1`
 - `overscan?: number`
+- `wrap?: boolean`
+- `itemKey?(item, index): string | number`
+- `showActive?: boolean`
 - shared visual props: `style`, `styles`, `state`
-- `renderItem?(item, index): string`
+- `children?(item, ctx): any`
+- `renderItem?(item, index): any`
 - `onchange?(event)`
+- `onviewportchange?(event)`
 - `onpress?(event)`
+- `ondoublepress?(event)`
+- `oncontextpress?(event)`
 - `onhover?(event)`
 - `onrowenter?(event)`
 - `onrowleave?(event)`
@@ -5267,12 +5297,13 @@ Props:
 
 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 }`
+- `TerminalListChangeEventPayload<T>` - `{ type: "change", id, index, key?, value, activeIndex, selectedIndex, viewportOffset, viewportRows }`
+- `TerminalListViewportChangeEventPayload` - `{ type: "viewportchange", id, offset, rows, activeIndex, selectedIndex, viewportOffset, viewportRows }`
+- `TerminalListPressEventPayload<T>` - `{ type: "press" | "doublepress" | "contextpress", id, index, key?, value, activeIndex, selectedIndex, viewportOffset, viewportRows }`
+- `TerminalListPointerEventPayload<T>` - `{ type: "hover" | "rowenter" | "rowleave", id, row, index, key?, value, x, y }`
 - `TerminalCaptureEventPayload` - `{ type: "capturestart" | "captureend", id, source, row, x, y }`
 
-Supports selection, activation, hover payloads, optional virtualization, and pointer capture.
+Supports internal active row movement, internal selection, activation, double press on the same row, context press for the target row, hover payloads, optional wrapping, optional virtualization, viewport scroll, and pointer capture. `Up`/`Down`, `PageUp`, `PageDown`, `Home`, and `End` are built-in list navigation keys; `Left` and `Right` stay available for application bindings. Keyboard navigation moves the active row and emits `change`; `Enter` selects and activates the active row. Pointer click selects and activates the clicked row. A quick second primary click on the same row emits `doublepress` without a second `press`. The default renderer displays the active row as `list.current`; when the selected row differs from the active row, it displays the selected row as `list.selected`. A JSX `children` callback is the recommended item renderer and wins over `renderItem` when both are present. `children` receives `ctx.active` and `ctx.selected` separately. `renderItem` remains as a compatibility alias with the legacy `(item, index)` signature. `wrap` wraps long default-rendered item text to the list width. Virtualized lists receive the full `items` array and calculate the visible viewport internally; use `itemKey` for stable event identity when items can reorder. Observe the resulting active row, selected row, and viewport through the list event payloads. Run [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx) with `bun examples/docs/virtualized-list-workbench.tsx` to inspect those values from events in one bounded split layout.
 
 ### `ScrollView`
 
@@ -5284,15 +5315,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 +5347,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.1",
   "description": "Terminal adapter for valyrian.js",
   "license": "Apache-2.0",
   "private": false,

package/src/ansi.ts

@@ -5,6 +5,8 @@ export const ANSI_ENTER_ALTERNATE_SCREEN = "\u001b[?1049h";
 export const ANSI_EXIT_ALTERNATE_SCREEN = "\u001b[?1049l";
 export const ANSI_HIDE_CURSOR = "\u001b[?25l";
 export const ANSI_SHOW_CURSOR = "\u001b[?25h";
+export const ANSI_ENABLE_MOUSE_REPORTING = "\u001b[?1000h\u001b[?1002h\u001b[?1006h";
+export const ANSI_DISABLE_MOUSE_REPORTING = "\u001b[?1002l\u001b[?1000l\u001b[?1006l";
 
 type AnsiFrameOptions = {
   showCursor?: boolean;
@@ -112,16 +114,26 @@ function renderAnsiLine(line: string, spans: TerminalStyleSpan[], y: number, the
     output += char;
     visibleColumn += 1;
 
+    let closedSpan = false;
     for (const span of rowSpans) {
       if (span.x2 === visibleColumn) {
         if (span.kind !== "focus") {
           output += spanAnsiClose(span, theme);
+          closedSpan = true;
         }
       }
     }
     for (const span of rowSpans) {
       if (span.x2 === visibleColumn && span.kind === "focus") {
         output += spanAnsiClose(span, theme);
+        closedSpan = true;
+      }
+    }
+    if (closedSpan && visibleColumn <= line.length && line[visibleColumn - 1] === " ") {
+      for (const span of rowSpans) {
+        if (span.x1 < visibleColumn && span.x2 > visibleColumn) {
+          output += spanAnsiOpen(span, theme);
+        }
       }
     }
   }

package/src/events.ts

@@ -151,9 +151,11 @@ export function parseTerminalKey(chunk: string | Uint8Array) {
   if (value === "\u001b[1;3C" || value === "\u001bf") return "ALT_RIGHT";
   if (value === "\u001b[1;3D" || value === "\u001bb") return "ALT_LEFT";
   if (value === "\u001b[3~") return "DELETE";
+  if (value === "\u001b[5~") return "PAGEUP";
+  if (value === "\u001b[6~") return "PAGEDOWN";
   if (value === "\u0008" || value === "\u007f") return "BACKSPACE";
-  if (value === "\u001b[H") return "HOME";
-  if (value === "\u001b[F") return "END";
+  if (value === "\u001b[H" || value === "\u001b[1~") return "HOME";
+  if (value === "\u001b[F" || value === "\u001b[4~") return "END";
   if (value === "\u0001") return "CTRL_A";
   if (value === "\u0003") return "CTRL_C";
   if (value === "\u000b") return "CTRL_K";

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/keymap.ts

@@ -32,9 +32,11 @@ export const defaultTerminalKeyBindings: TerminalKeyBinding[] = [
   { key: "ENTER", command: { id: "button.press" }, scope: "button", when: { focusedTag: "terminal-button" } },
   { key: "SPACE", command: { id: "button.press" }, scope: "button", when: { focusedTag: "terminal-button" } },
   { key: "UP", command: { id: "list.prev" }, scope: "list", when: { focusedTag: "terminal-list" } },
-  { key: "LEFT", command: { id: "list.prev" }, scope: "list", when: { focusedTag: "terminal-list" } },
   { key: "DOWN", command: { id: "list.next" }, scope: "list", when: { focusedTag: "terminal-list" } },
-  { key: "RIGHT", command: { id: "list.next" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "PAGEUP", command: { id: "list.pageUp" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "PAGEDOWN", command: { id: "list.pageDown" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "HOME", command: { id: "list.home" }, scope: "list", when: { focusedTag: "terminal-list" } },
+  { key: "END", command: { id: "list.end" }, scope: "list", when: { focusedTag: "terminal-list" } },
   { key: "ENTER", command: { id: "list.press" }, scope: "list", when: { focusedTag: "terminal-list" } },
   { key: "UP", command: { id: "scroll.up" }, scope: "scroll", when: { focusedTag: "terminal-scroll" } },
   { key: "DOWN", command: { id: "scroll.down" }, scope: "scroll", when: { focusedTag: "terminal-scroll" } }

package/src/layout.ts

@@ -25,7 +25,8 @@ export function shiftFrame(frame: TerminalFrame, dx: number, dy: number): Termin
       x2: box.x2 + dx,
       y1: box.y1 + dy,
       y2: box.y2 + dy,
-      textStartX: typeof box.textStartX === "number" ? box.textStartX + dx : undefined
+      textStartX: typeof box.textStartX === "number" ? box.textStartX + dx : undefined,
+      contentY: typeof box.contentY === "number" ? box.contentY + dy : undefined
     })),
     cursor: frame.cursor ? { x: frame.cursor.x + dx, y: frame.cursor.y + dy } : null,
     spans: frame.spans.map((span) => ({ ...span, x1: span.x1 + dx, x2: span.x2 + dx, y: span.y + dy }))

package/src/mouse.ts

@@ -2,7 +2,7 @@ import { parseTerminalKey } from "./events.js";
 
 import type { ParsedTerminalInput, TerminalHitbox } from "./types.js";
 
-const nestedParentTags = new Set(["terminal-box", "terminal-view"]);
+const nestedParentTags = new Set(["terminal-box", "terminal-view", "terminal-list"]);
 
 function containsHitbox(parent: TerminalHitbox, child: TerminalHitbox) {
   return child.x1 >= parent.x1 && child.x2 <= parent.x2 && child.y1 >= parent.y1 && child.y2 <= parent.y2;
@@ -12,24 +12,40 @@ function samePointerLayer(left: TerminalHitbox, right: TerminalHitbox) {
   return (left.pointerLayer ?? 0) === (right.pointerLayer ?? 0);
 }
 
+function parseMouseMatch(match: RegExpExecArray): Extract<ParsedTerminalInput, { type: "mouse" }> {
+  const code = Number(match[1]);
+  let action: "press" | "release" | "drag" | "wheel-up" | "wheel-down" = match[4] === "M" ? "press" : "release";
+  if (code >= 64) {
+    action = code === 64 ? "wheel-up" : "wheel-down";
+  } else if (code >= 32 && match[4] === "M") {
+    action = "drag";
+  }
+  return {
+    type: "mouse",
+    button: code,
+    x: Number(match[2]),
+    y: Number(match[3]),
+    action
+  };
+}
+
+export function parseTerminalMousePrefix(chunk: string | Uint8Array): { input: Extract<ParsedTerminalInput, { type: "mouse" }>; rest: string } | null {
+  const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+  const match = /^\u001b\[<(\d+);(\d+);(\d+)([Mm])/.exec(value);
+  if (!match) {
+    return null;
+  }
+  return {
+    input: parseMouseMatch(match),
+    rest: value.slice(match[0].length)
+  };
+}
+
 export function parseTerminalInput(chunk: string | Uint8Array): ParsedTerminalInput {
   const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
   const match = /^\u001b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(value);
   if (match) {
-    const code = Number(match[1]);
-    let action: "press" | "release" | "drag" | "wheel-up" | "wheel-down" = match[4] === "M" ? "press" : "release";
-    if (code >= 64) {
-      action = code === 64 ? "wheel-up" : "wheel-down";
-    } else if (code >= 32 && match[4] === "M") {
-      action = "drag";
-    }
-    return {
-      type: "mouse",
-      button: code,
-      x: Number(match[2]),
-      y: Number(match[3]),
-      action
-    };
+    return parseMouseMatch(match);
   }
   return { type: "key", key: parseTerminalKey(value) };
 }

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,14 @@ 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 = function TerminalList(props: TerminalPrimitiveComponentProps<TerminalListProps<any>> | null | undefined, children: any[]) {
+  const nextProps = { ...(props || {}) } as Record<string, any>;
+  if (children.length === 1 && typeof children[0] === "function") {
+    nextProps.__childrenRenderer = children[0];
+    return v("terminal-list", nextProps);
+  }
+  return v("terminal-list", nextProps, ...children);
+} as TerminalListComponent;
 export const Table = primitive<TerminalTableProps>("terminal-table");
 export const Row = primitive<TerminalRowProps>("terminal-row");
 export const Td = primitive<TerminalTdProps>("terminal-td");