@valyrianjs/terminal 0.1.0

package/docs/session-runtime.md

@@ -0,0 +1,451 @@
+# 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.
+
+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.
+
+## Cuando usar `mountTerminal()`
+
+Usa `mountTerminal()` cuando necesites una sesion viva que:
+
+- 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
+
+Si solo quieres inspeccionar layout, generar snapshots o producir una salida estatica, `renderTerminal()` sigue siendo la opcion mas simple.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+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>
+));
+
+session.focus("name");
+session.dispatchKey("A");
+session.dispatchKey("B");
+
+console.log(session.output());
+```
+
+## `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 */
+
+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?`
+
+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:
+
+- `on("data", listener)` obligatorio
+- `off(...)` o `removeListener(...)` opcional para cleanup
+- `setRawMode?(boolean)` opcional
+- `resume?()` y `pause?()` opcionales
+
+### `stdout?`
+
+Destino de escritura para la salida producida en cada rerender.
+
+- con `ansi: false`, escribe texto plano
+- con `ansi: true`, escribe diffs ANSI incrementales
+
+```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));
+    }
+  }
+});
+```
+
+## 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()`
+
+### `update()`
+
+Vuelve a evaluar `input`, recalcula el frame y devuelve la salida plana actual.
+
+Usalo cuando mutaste estado fuera de handlers de la sesion.
+
+```tsx
+const state = { count: 0 };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Text>Count: {state.count}</Text>
+  </Screen>
+));
+
+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`
+
+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.
+
+```tsx
+const state = { value: "abcd" };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Input
+      id="name"
+      value={state.value}
+      onchange={(event) => {
+        state.value = event.value;
+      }}
+    />
+  </Screen>
+), { clipboard: false });
+
+session.focus("name");
+session.setClipboard("XY");
+session.dispatchKey("END");
+session.dispatchKey("CTRL_V");
+```
+
+## Streams `stdin` y `stdout`
+
+Conectar streams vuelve a la sesion util como runtime de CLI, no solo como helper de pruebas.
+
+Comportamiento observable:
+
+- 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`
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { EventEmitter } from "node:events";
+import { v } from "valyrian.js";
+import { Screen, mountTerminal } from "valyrianjs-terminal";
+
+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));
+    }
+  }
+});
+
+stdin.emit("data", "A");
+stdin.emit("data", "\r");
+session.destroy();
+```
+
+## ANSI output
+
+Hay dos formas practicas de trabajar con ANSI:
+
+- `ansi: true` + `stdout`: la sesion emite diffs incrementales en cada rerender
+- `session.ansiOutput()`: recupera el frame ANSI completo del estado actual
+
+Esto es especialmente util cuando la terminal consumidora necesita minimizar repaints o cuando quieres verificar cursor, foco y seleccion con escape sequences reales.
+
+```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());
+```
+
+## 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.
+
+### Wheel
+
+El wheel se despacha como navegacion vertical sobre el nodo bajo el puntero:
+
+- `wheel-up` equivale a `dispatchKey("UP")`
+- `wheel-down` equivale a `dispatchKey("DOWN")`
+
+```ts
+stdin.emit("data", "\u001b[<65;2;1M");
+```
+
+En un `ScrollView` enfocado o localizado por coordenadas, eso desplaza el viewport.
+
+### Pointer capture a nivel practico
+
+`pointerCapture` hoy aplica a `List` y `ScrollView`.
+
+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:
+
+- `oncapturestart`
+- `oncaptureend`
+
+Esto es util para:
+
+- 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");
+```
+
+## Recomendaciones practicas
+
+- 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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@valyrianjs/terminal",
+  "version": "0.1.0",
+  "description": "Terminal adapter for valyrian.js",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "import": "./dist/render.js",
+      "default": "./dist/render.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "tsconfig.json",
+    "tsconfig.build.json"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc -p tsconfig.json --noEmit",
+    "build": "rm -rf dist && bunx tsc -p tsconfig.build.json"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "bun-types": "latest",
+    "typescript": "^5.9.3",
+    "valyrian.js": "^9.1.3"
+  },
+  "peerDependencies": {
+    "valyrian.js": "^9.1.3"
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "allowImportingTsExtensions": false,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "emitDeclarationOnly": false,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "lib": ["esnext", "dom"],
+    "module": "NodeNext",
+    "target": "ESNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "moduleDetection": "force",
+    "jsx": "react",
+    "jsxFactory": "v",
+    "jsxFragmentFactory": "v.fragment",
+    "allowJs": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["bun-types", "node"],
+    "downlevelIteration": true,
+    "allowSyntheticDefaultImports": true,
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "baseUrl": "."
+  },
+  "include": ["src", "test", "examples"]
+}