@valyrianjs/terminal 0.1.1 → 0.2.0

package/docs/session-runtime.md

@@ -1,451 +1,220 @@
 # Session Runtime
 
-This guide documents the interactive runtime of `valyrianjs-terminal`: when to use `mountTerminal()`, how to configure a session, and which capabilities `TerminalSession` exposes during its lifecycle.
+This guide explains how to use `mountTerminal()` in common cases first, then how to integrate it with host streams and runtime features.
 
-If you are starting from scratch, read `docs/core-concepts.md` first. For the general per-primitive interaction model, see `docs/interaction-model.md`. The focus here is operational: mounting, rerendering, streams, focus, keyboard, clipboard, and mouse.
+## When to use the session runtime
 
-## When to use `mountTerminal()`
+Use `mountTerminal()` when the UI needs one or more of these capabilities:
 
-Use `mountTerminal()` when you need a live session that:
+- focus and keyboard dispatch
+- repeated renders after state changes
+- clipboard integration
+- mouse and coordinate-based interaction
+- `stdin` and `stdout` connection
+- ANSI output for a real terminal
 
-- reevaluates the tree when external state changes
-- preserves focus across renders
-- dispatches keyboard input per session
-- connects `stdin` and `stdout`
-- responds to coordinates and mouse events
+Use `renderTerminal()` for deterministic static plain text.
 
-If you only want to inspect layout, generate snapshots, or produce static output, `renderTerminal()` is still the simplest option.
+## Practical recommendations
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+- Start without streams while building examples and scripted flows.
+- Give stable `id` values to focusable primitives you want to control.
+- Keep application state outside the renderer.
+- Valyrian reactive state read by components refreshes the terminal when it changes, including external async changes. Call `session.update()` for non-reactive state or an explicit manual refresh.
+- Call `session.destroy()` when a session is connected to real streams.
+- Design keyboard-first flows and connect resize, modified keys, clipboard, and mouse through the host capabilities available in each terminal environment.
+
+## Common runtime usage
+
+Full example: [`examples/docs/interactive-note.tsx`](../examples/docs/interactive-note.tsx). Run it with `bun examples/docs/interactive-note.tsx`, type a note, press `Enter`, and quit with `Ctrl+C`.
 
-import { v } from "valyrian.js";
-import { Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+```tsx
+import { Input, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
 const state = { value: "" };
 
-const session = mountTerminal(() => (
-  <Screen title="Runtime Demo">
-    <Input
-      id="name"
-      value={state.value}
-      onchange={(event) => {
-        state.value = event.value;
-      }}
-    />
-    <Text>Current: {state.value || "(empty)"}</Text>
-  </Screen>
-));
+function App() {
+  return (
+    <Screen title="Runtime demo">
+      <Input
+        id="name"
+        value={state.value}
+        placeholder="Name"
+        onchange={(event) => {
+          state.value = event.value;
+        }}
+      />
+      <Text>Current: {state.value || "(empty)"}</Text>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
 
 session.focus("name");
 session.dispatchKey("A");
 session.dispatchKey("B");
 
 console.log(session.output());
+session.destroy();
 ```
 
-## `TerminalMountOptions`
-
-`mountTerminal(input, options?)` accepts `TerminalMountOptions` with four integration points:
-
-### `ansi?: boolean`
-
-Enables incremental ANSI output to `stdout`. `session.ansiOutput()` is still available even if you do not enable this option; what changes is the session's automatic write behavior when it rerenders. If you do not enable it, the primary output written to `stdout` is plain text.
-
-### `clipboard?: TerminalClipboardAdapter | false`
-
-- if you pass an adapter, the session uses `readText()` and `writeText()` when handling shortcuts such as `CTRL_C` or `CTRL_V`
-- if you pass `false`, system clipboard integration is disabled
-- even with `clipboard: false`, `session.clipboard()` and `session.setClipboard()` still work as the session buffer
-
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
-
-import { v } from "valyrian.js";
-import { Screen, mountTerminal } from "valyrianjs-terminal";
-
-const app = () => <Screen title="Clipboard Demo" />;
-
-const session = mountTerminal(app, {
-  clipboard: {
-    readText() {
-      return "pasted value";
-    },
-    writeText(value) {
-      console.log("copied:", value);
-    }
-  }
-});
-```
-
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
-
-import { v } from "valyrian.js";
-import { Screen, mountTerminal } from "valyrianjs-terminal";
-
-const app = () => <Screen title="Clipboard Disabled" />;
-
-const session = mountTerminal(app, { clipboard: false });
-session.setClipboard("fallback value");
-```
-
-### `stdin?`
-
-Input stream for keyboard and mouse. The session subscribes to `data`, tries to enable raw mode with `setRawMode(true)` if available, and calls `resume()` if the stream supports it.
-
-Expected contract:
-
-- `on("data", listener)` is required
-- `off(...)` or `removeListener(...)` is optional for cleanup
-- `setRawMode?(boolean)` is optional
-- `resume?()` and `pause?()` are optional
-
-### `stdout?`
-
-Write target for the output produced on each rerender.
-
-- with `ansi: false`, writes plain text
-- with `ansi: true`, writes incremental ANSI diffs
-
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
-
-import { v } from "valyrian.js";
-import { Screen, mountTerminal } from "valyrianjs-terminal";
-
-const app = () => <Screen title="ANSI Stream Demo" />;
-
-const writes: string[] = [];
-
-const session = mountTerminal(app, {
-  ansi: true,
-  stdout: {
-    write(chunk) {
-      writes.push(String(chunk));
-    }
-  }
-});
-```
-
-## `TerminalSession` lifecycle
-
-The session keeps a current frame, a current output, and the interactive state associated with the focusable tree. In practice, the cycle is:
+The session lifecycle is:
 
 1. mount with `mountTerminal()`
-2. read with `output()` or `ansiOutput()`
-3. mutate external state or dispatch interactions
-4. rerender with `update()` or through events that already trigger rerenders
+2. read `output()` or `ansiOutput()`
+3. dispatch input or update external state
+4. rerender with `update()` when needed
 5. close with `destroy()`
 
-### `update()`
-
-Reevaluates `input`, recalculates the frame, and returns the current plain-text output.
-
-Use it when you changed state outside the session handlers.
-
-```tsx
-const state = { count: 0 };
-
-const session = mountTerminal(() => (
-  <Screen>
-    <Text>Count: {state.count}</Text>
-  </Screen>
-));
-
-state.count += 1;
-session.update();
-
-console.log(session.output());
-```
+## Input, output, and cleanup
 
 ### `output()`
 
-Returns the current frame as plain text. It is the most direct way to:
-
-- inspect the current state
-- validate snapshots
-- test focus and content without ANSI
+Returns the current plain-text frame. Use it for snapshots, examples, and content inspection.
 
 ### `ansiOutput()`
 
-Returns the current frame serialized as full ANSI output, including the cursor and visual spans. It is useful when you want to:
+Returns the current frame serialized with ANSI cursor movement and style spans.
 
-- inspect cursor position
-- validate selection or focus in an ANSI terminal
-- integrate with a layer that consumes full escape sequences
+Related example: [`examples/docs/theme-colors.tsx`](../examples/docs/theme-colors.tsx). Run it with `bun examples/docs/theme-colors.tsx`, press `Tab`, and quit with `Ctrl+C`.
 
 ```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
-
-import { v } from "valyrian.js";
-import { Screen, mountTerminal } from "valyrianjs-terminal";
-
-const app = () => <Screen title="ANSI Frame Demo" />;
-
-const session = mountTerminal(app, { ansi: true });
-const ansi = session.ansiOutput();
-console.log(ansi);
-```
+import { Screen, mountTerminal } from "@valyrianjs/terminal";
 
-### `destroy()`
-
-Removes `stdin` listeners, tries to exit raw mode with `setRawMode(false)`, and calls `pause()` if available.
+function App() {
+  return <Screen title="ANSI frame" />;
+}
 
-Always call it when you mounted the session with a real `stdin` or a connected emitter.
+const session = mountTerminal(<App />, { runtime: "headless" });
 
-```ts
+console.log(session.ansiOutput());
 session.destroy();
 ```
 
-## Focus and coordinates
-
-Focus lives at the session level. To participate in this flow, interactive nodes need an `id`.
-
-### `focus(id)`
-
-Focuses a node by `id`. Returns `true` if it found one.
-
-### `focusNext()` and `focusPrev()`
-
-Walk the current focusable-element order. `dispatchKey("TAB")` and `dispatchKey("SHIFT_TAB")` use the same flow.
+`ansiOutput()` is an explicit inspection/export path. Keep ordinary `Text`, input values, list rows, and log entries as text content. Advanced span serialization tokens are documented in [Advanced: span serialization tokens](./api-reference.md#advanced-span-serialization-tokens) for low-level renderer integrations.
 
-### `focusAt(x, y)`
-
-Looks up the hitbox at the current coordinates, updates semantic hover when applicable, and focuses that node.
+### `update()`
 
-### `clickAt(x, y)`
+Re-evaluates the session input and returns the current plain-text output.
 
-- if it lands on a `Button`, it triggers its action
-- if it lands on an `Input`, it focuses it and places the cursor based on the coordinate
-- if it lands on another focusable surface, it moves focus there
+Related example: [`examples/docs/component-composition.tsx`](../examples/docs/component-composition.tsx). Run it with `bun examples/docs/component-composition.tsx`, switch cards with `N/P`, and quit with `Ctrl+C`.
 
 ```tsx
-const session = mountTerminal(() => (
-  <Screen>
-    <Input id="name" value="abc" />
-    <Button id="save">Save</Button>
-  </Screen>
-));
-
-session.focusAt(2, 1);
-session.clickAt(3, 2);
-```
-
-## Per-session keyboard dispatch
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
-`dispatchKey(key)` processes a normalized key against the focused node and returns the current plain-text output.
+const state = { count: 0 };
 
-Shortcuts supported by the public API and observable in tests:
+function App() {
+  return (
+    <Screen title="Update demo">
+      <Text>Count: {state.count}</Text>
+    </Screen>
+  );
+}
 
-- global: `TAB`, `SHIFT_TAB`
-- `Input`: single-byte characters, `ENTER`, `LEFT`, `RIGHT`, `SHIFT_LEFT`, `SHIFT_RIGHT`, `ALT_LEFT`, `ALT_RIGHT`, `HOME`, `END`, `CTRL_A`, `CTRL_C`, `CTRL_X`, `CTRL_V`, `BACKSPACE`, `DELETE`
-- `Button`: `ENTER`, `SPACE`
-- `List`: `UP`, `DOWN`, `LEFT`, `RIGHT`, `ENTER`
-- `ScrollView`: `UP`, `DOWN`
+const session = mountTerminal(<App />);
 
-```tsx
-const state = { value: "", saved: "" };
-
-const session = mountTerminal(() => (
-  <Screen>
-    <Input
-      id="name"
-      value={state.value}
-      onchange={(event) => {
-        state.value = event.value;
-      }}
-      onsubmit={(event) => {
-        state.saved = event.value;
-      }}
-    />
-  </Screen>
-));
+state.count += 1;
+session.update();
 
-session.focus("name");
-session.dispatchKey("A");
-session.dispatchKey("B");
-session.dispatchKey("LEFT");
-session.dispatchKey("C");
-session.dispatchKey("ENTER");
+console.log(session.output());
+session.destroy();
 ```
 
-## Clipboard adapter and `clipboard: false`
-
-The session separates two concepts:
-
-- the session clipboard buffer: `clipboard()` and `setClipboard()`
-- system integration: `options.clipboard`
+### `destroy()`
 
-With an adapter, input shortcuts read from and write to that adapter. Without an adapter, the session keeps a local value. With `clipboard: false`, external integration is disabled, but you can still use the local session buffer for tests or manual integrations.
+Removes listeners and restores supported terminal state when a session connected to streams changed it. Always call it when the session owns real input or output resources.
 
-```tsx
-const state = { value: "abcd" };
-
-const session = mountTerminal(() => (
-  <Screen>
-    <Input
-      id="name"
-      value={state.value}
-      onchange={(event) => {
-        state.value = event.value;
-      }}
-    />
-  </Screen>
-), { clipboard: false });
+## Advanced host integration
 
-session.focus("name");
-session.setClipboard("XY");
-session.dispatchKey("END");
-session.dispatchKey("CTRL_V");
-```
+### Mount options
 
-## `stdin` and `stdout` streams
+`mountTerminal(input, options?)` accepts options for host integration. `mountTerminal(<App />)` is the normal interactive path; it uses process stdio, ANSI diffs, alternate screen, and a hidden cursor only when called from a real interactive TTY. Imports and non-TTY/test runs do not auto-attach stdio.
 
-Connecting streams makes the session useful as a CLI runtime, not just as a test helper.
+- `runtime?: "app" | "headless"` - selects interactive app behavior or scriptable plain output. Omitted runtime uses app mode only for interactive TTY hosts and stays headless in non-TTY/CI contexts.
+- `alternateScreen?: boolean` - enters the terminal alternate screen and restores it on destroy by default. Real interactive app mode enables it by default unless overridden.
+- `hideCursor?: boolean` - expresses that the session should hide the terminal cursor while it owns the screen when the host supports it. Real interactive app mode enables it by default unless overridden.
+- `restoreOnDestroy?: boolean` - controls whether destroy should restore supported cursor and alternate-screen state.
+- `clipboard?: TerminalClipboardAdapter | false` - connects a custom clipboard adapter or disables external clipboard integration.
+- `cols?: number` and `rows?: number` - set the initial terminal size.
+- `stdin?` - receives keyboard, paste, and mouse input.
+- `stdout?` - receives rendered output.
 
-Observable behavior:
+### Clipboard adapter
 
-- on mount, the session subscribes to `stdin.on("data", listener)`
-- if `stdin.setRawMode` exists, it tries `setRawMode(true)`
-- if `stdin.resume` exists, it tries `resume()`
-- on each rerender, if `stdout.write` exists, the session writes the current frame
-- on destroy, it tries to unsubscribe and restore raw mode
+Related example: [`examples/docs/interactive-note.tsx`](../examples/docs/interactive-note.tsx). Run it with `bun examples/docs/interactive-note.tsx`, type a note, press `Enter`, and quit with `Ctrl+C`.
 
 ```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+import { Screen, mountTerminal } from "@valyrianjs/terminal";
 
-import { EventEmitter } from "node:events";
-import { v } from "valyrian.js";
-import { Screen, mountTerminal } from "valyrianjs-terminal";
+function App() {
+  return <Screen title="Clipboard" />;
+}
 
-const app = () => <Screen title="Stream Demo" />;
-
-const stdin = new EventEmitter() as EventEmitter & {
-  setRawMode?: (value: boolean) => void;
-  resume?: () => void;
-  pause?: () => void;
-};
-
-const writes: string[] = [];
-
-const session = mountTerminal(app, {
-  stdin,
-  stdout: {
-    write(chunk) {
-      writes.push(String(chunk));
+const session = mountTerminal(<App />, {
+  clipboard: {
+    readText() {
+      return "pasted value";
+    },
+    writeText(value) {
+      console.log("copied:", value);
     }
   }
 });
 
-stdin.emit("data", "A");
-stdin.emit("data", "\r");
 session.destroy();
 ```
 
-## ANSI output
-
-There are two practical ways to work with ANSI:
-
-- `ansi: true` + `stdout`: the session emits incremental diffs on each rerender
-- `session.ansiOutput()`: retrieves the full ANSI frame for the current state
+Passing `clipboard: false` disables external clipboard integration while preserving the session clipboard buffer through `clipboard()` and `setClipboard()`.
 
-This is especially useful when the consuming terminal needs to minimize repaints or when you want to verify cursor, focus, and selection with real escape sequences.
+### Streams
 
-```tsx
-const state = { value: "AB" };
-
-const session = mountTerminal(() => (
-  <Screen title="ANSI Demo">
-    <Input
-      id="name"
-      value={state.value}
-      onchange={(event) => {
-        state.value = event.value;
-      }}
-    />
-  </Screen>
-), { ansi: true });
-
-session.focus("name");
-session.dispatchKey("LEFT");
-
-console.log(session.ansiOutput());
-```
+`stdin` should provide `on("data", listener)`. Cleanup methods such as `off(...)` or `removeListener(...)` are used when available. `setRawMode`, `resume`, and `pause` are optional.
 
-## SGR mouse, wheel, and pointer capture
+`stdout` should provide `write(chunk: string)`. Optional `columns` and `rows` can provide initial dimensions. Optional `resize` and `drain` events are used only when the stream also provides listener cleanup.
 
-When you connect `stdin`, the session accepts SGR mouse sequences and translates them into practical interaction over the current frame.
+### Size and resize
 
-### Press, drag, and release
+`size()` returns `{ cols, rows }`. `resize(cols, rows)` validates positive integer dimensions, stores them, and rerenders once.
 
-- `press`: focuses and activates the hitbox at the coordinate
-- `drag`: if an `Input` is active through the mouse, it extends selection; in `List` and `ScrollView`, it updates row hover
-- `release`: ends mouse selection and closes capture when applicable
-
-```ts
-stdin.emit("data", "\u001b[<0;4;1M");
-stdin.emit("data", "\u001b[<32;7;1M");
-stdin.emit("data", "\u001b[<0;7;1m");
-```
+Related example: [`examples/docs/background-fill.tsx`](../examples/docs/background-fill.tsx). Run it with `bun examples/docs/background-fill.tsx`, switch surfaces with `B`, and quit with `Ctrl+C`.
 
-That pattern is enough to select text inside an `Input` by coordinates.
-
-### Wheel
+```tsx
+import { Screen, mountTerminal } from "@valyrianjs/terminal";
 
-Wheel input is dispatched as vertical navigation on the node under the pointer:
+function App() {
+  return <Screen title="Resizable" />;
+}
 
-- `wheel-up` is equivalent to `dispatchKey("UP")`
-- `wheel-down` is equivalent to `dispatchKey("DOWN")`
+const session = mountTerminal(<App />, { cols: 80, rows: 24 });
 
-```ts
-stdin.emit("data", "\u001b[<65;2;1M");
+console.log(session.size());
+session.resize(100, 30);
+console.log(session.size());
+session.destroy();
 ```
 
-In a focused `ScrollView`, or one resolved by coordinates, that scrolls the viewport.
+Automatic resize works with compatible output sources that emit supported resize events after updating their `columns` and `rows` values.
 
-### Pointer capture in practice
+### Keyboard, paste, and mouse input
 
-`pointerCapture` currently applies to `List` and `ScrollView`.
+`dispatchKey(key)` injects a normalized key directly. Connected `stdin` can also deliver keyboard input, terminal paste input, and supported SGR mouse input.
 
-Without `pointerCapture`, semantic hover depends on the drag staying inside the visible hitbox. With `pointerCapture`, the session keeps the interaction during the drag even if the pointer leaves the initial area, and triggers:
+Bracketed paste is handled as terminal input: pasted text is inserted into the focused `Input` or `Editor` as content instead of being treated as separate key commands. Multiline `Editor` cursor columns are reported as JavaScript UTF-16 string columns, not as a complete terminal grapheme-width model.
 
-- `oncapturestart`
-- `oncaptureend`
+Mouse input can focus or activate hitboxes, update hover state, and map wheel input to vertical navigation. Keep keyboard alternatives for important actions so every terminal workflow has a reliable input path.
 
-This is useful for:
+## Host integration behavior
 
-- lists that need to keep tracking the active row during a drag
-- scroll views that keep hover or release behavior even if the pointer ends outside the viewport
+- Modified keys follow sequences reported by the connected terminal.
+- Clipboard behavior uses the provided adapter or the session clipboard buffer.
+- Mouse behavior uses supported terminal input sequences.
+- Automatic resize works with compatible output sources and cleanup-capable listeners.
+- Use session runtime for terminal rendering, focus, input, output, and cleanup. Keep routing, persistence, command orchestration, and process management in the app layer.
 
-```tsx
-const session = mountTerminal(() => (
-  <Screen>
-    <List
-      id="menu"
-      pointerCapture
-      items={["Open", "Save", "Exit"]}
-      oncapturestart={(event) => console.log(event)}
-      oncaptureend={(event) => console.log(event)}
-    />
-  </Screen>
-), { stdin, clipboard: false });
-
-stdin.emit("data", "\u001b[<0;2;1M");
-stdin.emit("data", "\u001b[<32;99;99M");
-stdin.emit("data", "\u001b[<0;99;99m");
-```
-
-## Practical recommendations
+## Where to go next
 
-- use `renderTerminal()` for snapshots and `mountTerminal()` for interactive runtime
-- give stable `id` values to `Input`, `Button`, `List`, and `ScrollView` if you plan to use focus, coordinates, or programmatic dispatch
-- call `update()` only when you changed state outside handlers already connected to the session
-- always call `destroy()` when mounting with `stdin`
-- use `clipboard: false` in tests or environments where you do not want to depend on the system clipboard
+- [Getting Started](./getting-started.md) for the first project.
+- [Interaction Model](./interaction-model.md) for per-primitive behavior.
+- [API Reference](./api-reference.md) for exact methods, props, and payloads.