@valyrianjs/terminal 0.1.0 → 0.1.2

package/docs/session-runtime.md

@@ -1,451 +1,220 @@
 # Session Runtime
 
-Esta guia documenta el runtime interactivo de `valyrianjs-terminal`: cuando conviene usar `mountTerminal()`, como configurar una sesion y que capacidades expone `TerminalSession` durante su ciclo de vida.
+This guide explains how to use `mountTerminal()` in common cases first, then how to integrate it with host streams and runtime features.
 
-Si vienes desde cero, lee antes `docs/core-concepts.md`. Para el modelo general de interaccion por primitiva, consulta `docs/interaction-model.md`. Aqui el foco es operativo: montaje, rerender, streams, foco, teclado, clipboard y mouse.
+## When to use the session runtime
 
-## Cuando usar `mountTerminal()`
+Use `mountTerminal()` when the UI needs one or more of these capabilities:
 
-Usa `mountTerminal()` cuando necesites una sesion viva que:
+- 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
 
-- reevalua el arbol al cambiar estado externo
-- mantiene foco entre renders
-- despacha teclado por sesion
-- conecta `stdin` y `stdout`
-- responde a coordenadas y eventos de mouse
+Use `renderTerminal()` for deterministic static plain text.
 
-Si solo quieres inspeccionar layout, generar snapshots o producir una salida estatica, `renderTerminal()` sigue siendo la opcion mas simple.
+## 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
 
-import { v } from "valyrian.js";
-import { Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+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`.
+
+```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?)` acepta un `TerminalMountOptions` con cuatro puntos de integracion:
-
-### `ansi?: boolean`
-
-Activa salida ANSI incremental hacia `stdout`. `session.ansiOutput()` sigue disponible aunque no actives esta opcion; lo que cambia es la escritura automatica de la sesion cuando hace rerender. Si no lo activas, la salida principal enviada a `stdout` es texto plano.
-
-### `clipboard?: TerminalClipboardAdapter | false`
-
-- si pasas un adapter, la sesion usa `readText()` y `writeText()` cuando ejecuta atajos como `CTRL_C` o `CTRL_V`
-- si pasas `false`, desactivas la integracion con clipboard del sistema
-- aun con `clipboard: false`, `session.clipboard()` y `session.setClipboard()` siguen funcionando como buffer de la sesion
-
-```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 */
+The session lifecycle is:
 
-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");
-```
+1. mount with `mountTerminal()`
+2. read `output()` or `ansiOutput()`
+3. dispatch input or update external state
+4. rerender with `update()` when needed
+5. close with `destroy()`
 
-### `stdin?`
+## Input, output, and cleanup
 
-Stream de entrada para teclado y mouse. La sesion se suscribe a `data`, intenta activar `raw mode` si existe `setRawMode(true)` y llama `resume()` si el stream lo soporta.
-
-Contrato esperado:
+### `output()`
 
-- `on("data", listener)` obligatorio
-- `off(...)` o `removeListener(...)` opcional para cleanup
-- `setRawMode?(boolean)` opcional
-- `resume?()` y `pause?()` opcionales
+Returns the current plain-text frame. Use it for snapshots, examples, and content inspection.
 
-### `stdout?`
+### `ansiOutput()`
 
-Destino de escritura para la salida producida en cada rerender.
+Returns the current frame serialized with ANSI cursor movement and style spans.
 
-- con `ansi: false`, escribe texto plano
-- con `ansi: true`, escribe diffs ANSI incrementales
+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";
+import { Screen, mountTerminal } from "@valyrianjs/terminal";
 
-const app = () => <Screen title="ANSI Stream Demo" />;
+function App() {
+  return <Screen title="ANSI frame" />;
+}
 
-const writes: string[] = [];
+const session = mountTerminal(<App />, { runtime: "headless" });
 
-const session = mountTerminal(app, {
-  ansi: true,
-  stdout: {
-    write(chunk) {
-      writes.push(String(chunk));
-    }
-  }
-});
+console.log(session.ansiOutput());
+session.destroy();
 ```
 
-## Lifecycle de `TerminalSession`
-
-La sesion mantiene un frame actual, una salida actual y el estado interactivo asociado al arbol enfocable. El ciclo practico es:
-
-1. montar con `mountTerminal()`
-2. leer con `output()` o `ansiOutput()`
-3. mutar estado externo o despachar interacciones
-4. rerender con `update()` o mediante eventos que ya disparan rerender
-5. cerrar con `destroy()`
+`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.
 
 ### `update()`
 
-Vuelve a evaluar `input`, recalcula el frame y devuelve la salida plana actual.
+Re-evaluates the session input and returns the current plain-text output.
 
-Usalo cuando mutaste estado fuera de handlers de la sesion.
+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
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+
 const state = { count: 0 };
 
-const session = mountTerminal(() => (
-  <Screen>
-    <Text>Count: {state.count}</Text>
-  </Screen>
-));
+function App() {
+  return (
+    <Screen title="Update demo">
+      <Text>Count: {state.count}</Text>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
 
 state.count += 1;
 session.update();
 
 console.log(session.output());
-```
-
-### `output()`
-
-Devuelve el frame actual en texto plano. Es la forma mas directa de:
-
-- inspeccionar estado actual
-- validar snapshots
-- probar foco y contenido sin ANSI
-
-### `ansiOutput()`
-
-Devuelve el frame actual serializado como ANSI completo, incluyendo cursor y spans visuales. Es util cuando quieres:
-
-- inspeccionar posicion de cursor
-- validar seleccion o foco en una terminal ANSI
-- integrar una capa que consume escape sequences completas
-
-```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);
-```
-
-### `destroy()`
-
-Desmonta listeners de `stdin`, intenta salir de raw mode con `setRawMode(false)` y llama `pause()` si existe.
-
-Llamalo siempre cuando montaste la sesion con `stdin` real o un emisor conectado.
-
-```ts
 session.destroy();
 ```
 
-## Foco y coordenadas
-
-El foco vive a nivel de sesion. Para participar en este flujo, los nodos interactivos necesitan `id`.
-
-### `focus(id)`
-
-Enfoca un nodo por `id`. Devuelve `true` si lo encontro.
-
-### `focusNext()` y `focusPrev()`
-
-Recorren el orden actual de elementos enfocables. `dispatchKey("TAB")` y `dispatchKey("SHIFT_TAB")` usan este mismo flujo.
-
-### `focusAt(x, y)`
-
-Busca el hitbox en las coordenadas actuales, actualiza hover semantico cuando aplica y enfoca ese nodo.
-
-### `clickAt(x, y)`
-
-- si cae sobre un `Button`, dispara su accion
-- si cae sobre un `Input`, enfoca y coloca cursor segun la coordenada
-- si cae sobre otra superficie enfocable, mueve el foco
-
-```tsx
-const session = mountTerminal(() => (
-  <Screen>
-    <Input id="name" value="abc" />
-    <Button id="save">Save</Button>
-  </Screen>
-));
-
-session.focusAt(2, 1);
-session.clickAt(3, 2);
-```
-
-## Keyboard dispatch por sesion
-
-`dispatchKey(key)` procesa una tecla ya normalizada contra el nodo enfocado y devuelve la salida plana actual.
-
-Atajos soportados por la API publica observables en pruebas:
-
-- globales: `TAB`, `SHIFT_TAB`
-- `Input`: caracteres de un solo byte, `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`
-
-```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>
-));
-
-session.focus("name");
-session.dispatchKey("A");
-session.dispatchKey("B");
-session.dispatchKey("LEFT");
-session.dispatchKey("C");
-session.dispatchKey("ENTER");
-```
-
-## Clipboard adapter y `clipboard: false`
-
-La sesion separa dos conceptos:
-
-- buffer de clipboard de la sesion: `clipboard()` y `setClipboard()`
-- integracion con el sistema: `options.clipboard`
+### `destroy()`
 
-Con un adapter, los atajos de input leen y escriben contra ese adapter. Sin adapter, la sesion conserva un valor local. Con `clipboard: false`, desactivas la integracion externa pero puedes seguir usando el buffer local de la sesion para pruebas o integraciones manuales.
+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
 
-## Streams `stdin` y `stdout`
+`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.
 
-Conectar streams vuelve a la sesion util como runtime de CLI, no solo como helper de pruebas.
+- `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.
 
-Comportamiento observable:
+### Clipboard adapter
 
-- al montar, la sesion se suscribe a `stdin.on("data", listener)`
-- si `stdin.setRawMode` existe, intenta `setRawMode(true)`
-- si `stdin.resume` existe, intenta `resume()`
-- en cada rerender, si existe `stdout.write`, la sesion escribe el frame actual
-- al destruir, intenta desuscribirse y restaurar `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
+Passing `clipboard: false` disables external clipboard integration while preserving the session clipboard buffer through `clipboard()` and `setClipboard()`.
 
-Hay dos formas practicas de trabajar con ANSI:
+### Streams
 
-- `ansi: true` + `stdout`: la sesion emite diffs incrementales en cada rerender
-- `session.ansiOutput()`: recupera el frame ANSI completo del estado actual
+`stdin` should provide `on("data", listener)`. Cleanup methods such as `off(...)` or `removeListener(...)` are used when available. `setRawMode`, `resume`, and `pause` are optional.
 
-Esto es especialmente util cuando la terminal consumidora necesita minimizar repaints o cuando quieres verificar cursor, foco y seleccion con escape sequences reales.
+`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.
 
-```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 });
+### Size and resize
 
-session.focus("name");
-session.dispatchKey("LEFT");
+`size()` returns `{ cols, rows }`. `resize(cols, rows)` validates positive integer dimensions, stores them, and rerenders once.
 
-console.log(session.ansiOutput());
-```
-
-## Mouse SGR, wheel y pointer capture
-
-Cuando conectas `stdin`, la sesion acepta secuencias SGR de mouse y las traduce a interaccion practica sobre el frame actual.
-
-### Press, drag y release
-
-- `press`: enfoca y activa el hitbox en la coordenada
-- `drag`: si hay un `Input` activo por mouse, extiende seleccion; en `List` y `ScrollView`, actualiza hover por fila
-- `release`: termina seleccion por mouse y cierra captura cuando aplica
-
-```ts
-stdin.emit("data", "\u001b[<0;4;1M");
-stdin.emit("data", "\u001b[<32;7;1M");
-stdin.emit("data", "\u001b[<0;7;1m");
-```
-
-Ese patron es suficiente para seleccionar texto dentro de un `Input` por coordenadas.
+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`.
 
-### Wheel
+```tsx
+import { Screen, mountTerminal } from "@valyrianjs/terminal";
 
-El wheel se despacha como navegacion vertical sobre el nodo bajo el puntero:
+function App() {
+  return <Screen title="Resizable" />;
+}
 
-- `wheel-up` equivale a `dispatchKey("UP")`
-- `wheel-down` equivale a `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();
 ```
 
-En un `ScrollView` enfocado o localizado por coordenadas, eso desplaza el viewport.
+Automatic resize works with compatible output sources that emit supported resize events after updating their `columns` and `rows` values.
 
-### Pointer capture a nivel practico
+### Keyboard, paste, and mouse input
 
-`pointerCapture` hoy aplica a `List` y `ScrollView`.
+`dispatchKey(key)` injects a normalized key directly. Connected `stdin` can also deliver keyboard input, terminal paste input, and supported SGR mouse input.
 
-Sin `pointerCapture`, el hover semantico depende de que el drag siga dentro del hitbox visible. Con `pointerCapture`, la sesion mantiene la interaccion durante el drag aunque el puntero salga del area inicial, y dispara:
+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.
 
-Esto es util para:
+## Host integration behavior
 
-- listas que deben seguir rastreando la fila activa durante drag
-- scroll views que conservan hover o release aunque el puntero termine fuera del viewport
-
-```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");
-```
+- 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.
 
-## Recomendaciones practicas
+## Where to go next
 
-- usa `renderTerminal()` para snapshots y `mountTerminal()` para runtime interactivo
-- da `id` estables a `Input`, `Button`, `List` y `ScrollView` si vas a usar foco, coordenadas o dispatch programatico
-- llama `update()` solo cuando mutaste estado fuera de handlers ya conectados a la sesion
-- llama `destroy()` siempre que montes con `stdin`
-- usa `clipboard: false` en pruebas o entornos donde no quieres depender del clipboard del sistema
+- [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.