@valyrianjs/terminal 0.1.0 → 0.1.1

package/docs/session-runtime.md

@@ -1,20 +1,20 @@
 # 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 documents the interactive runtime of `valyrianjs-terminal`: when to use `mountTerminal()`, how to configure a session, and which capabilities `TerminalSession` exposes during its lifecycle.
 
-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.
+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.
 
-## Cuando usar `mountTerminal()`
+## When to use `mountTerminal()`
 
-Usa `mountTerminal()` cuando necesites una sesion viva que:
+Use `mountTerminal()` when you need a live session that:
 
-- 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
+- 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
 
-Si solo quieres inspeccionar layout, generar snapshots o producir una salida estatica, `renderTerminal()` sigue siendo la opcion mas simple.
+If you only want to inspect layout, generate snapshots, or produce static output, `renderTerminal()` is still the simplest option.
 
 ```tsx
 /** @jsx v */
@@ -47,17 +47,17 @@ console.log(session.output());
 
 ## `TerminalMountOptions`
 
-`mountTerminal(input, options?)` acepta un `TerminalMountOptions` con cuatro puntos de integracion:
+`mountTerminal(input, options?)` accepts `TerminalMountOptions` with four integration points:
 
 ### `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.
+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`
 
-- 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
+- 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 */
@@ -95,21 +95,21 @@ 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.
+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.
 
-Contrato esperado:
+Expected contract:
 
-- `on("data", listener)` obligatorio
-- `off(...)` o `removeListener(...)` opcional para cleanup
-- `setRawMode?(boolean)` opcional
-- `resume?()` y `pause?()` opcionales
+- `on("data", listener)` is required
+- `off(...)` or `removeListener(...)` is optional for cleanup
+- `setRawMode?(boolean)` is optional
+- `resume?()` and `pause?()` are optional
 
 ### `stdout?`
 
-Destino de escritura para la salida producida en cada rerender.
+Write target for the output produced on each rerender.
 
-- con `ansi: false`, escribe texto plano
-- con `ansi: true`, escribe diffs ANSI incrementales
+- with `ansi: false`, writes plain text
+- with `ansi: true`, writes incremental ANSI diffs
 
 ```tsx
 /** @jsx v */
@@ -132,21 +132,21 @@ const session = mountTerminal(app, {
 });
 ```
 
-## Lifecycle de `TerminalSession`
+## `TerminalSession` lifecycle
 
-La sesion mantiene un frame actual, una salida actual y el estado interactivo asociado al arbol enfocable. El ciclo practico es:
+The session keeps a current frame, a current output, and the interactive state associated with the focusable tree. In practice, the cycle is:
 
-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()`
+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
+5. close with `destroy()`
 
 ### `update()`
 
-Vuelve a evaluar `input`, recalcula el frame y devuelve la salida plana actual.
+Reevaluates `input`, recalculates the frame, and returns the current plain-text output.
 
-Usalo cuando mutaste estado fuera de handlers de la sesion.
+Use it when you changed state outside the session handlers.
 
 ```tsx
 const state = { count: 0 };
@@ -165,19 +165,19 @@ console.log(session.output());
 
 ### `output()`
 
-Devuelve el frame actual en texto plano. Es la forma mas directa de:
+Returns the current frame as plain text. It is the most direct way to:
 
-- inspeccionar estado actual
-- validar snapshots
-- probar foco y contenido sin ANSI
+- inspect the current state
+- validate snapshots
+- test focus and content without ANSI
 
 ### `ansiOutput()`
 
-Devuelve el frame actual serializado como ANSI completo, incluyendo cursor y spans visuales. Es util cuando quieres:
+Returns the current frame serialized as full ANSI output, including the cursor and visual spans. It is useful when you want to:
 
-- inspeccionar posicion de cursor
-- validar seleccion o foco en una terminal ANSI
-- integrar una capa que consume escape sequences completas
+- inspect cursor position
+- validate selection or focus in an ANSI terminal
+- integrate with a layer that consumes full escape sequences
 
 ```tsx
 /** @jsx v */
@@ -195,35 +195,35 @@ console.log(ansi);
 
 ### `destroy()`
 
-Desmonta listeners de `stdin`, intenta salir de raw mode con `setRawMode(false)` y llama `pause()` si existe.
+Removes `stdin` listeners, tries to exit raw mode with `setRawMode(false)`, and calls `pause()` if available.
 
-Llamalo siempre cuando montaste la sesion con `stdin` real o un emisor conectado.
+Always call it when you mounted the session with a real `stdin` or a connected emitter.
 
 ```ts
 session.destroy();
 ```
 
-## Foco y coordenadas
+## Focus and coordinates
 
-El foco vive a nivel de sesion. Para participar en este flujo, los nodos interactivos necesitan `id`.
+Focus lives at the session level. To participate in this flow, interactive nodes need an `id`.
 
 ### `focus(id)`
 
-Enfoca un nodo por `id`. Devuelve `true` si lo encontro.
+Focuses a node by `id`. Returns `true` if it found one.
 
-### `focusNext()` y `focusPrev()`
+### `focusNext()` and `focusPrev()`
 
-Recorren el orden actual de elementos enfocables. `dispatchKey("TAB")` y `dispatchKey("SHIFT_TAB")` usan este mismo flujo.
+Walk the current focusable-element order. `dispatchKey("TAB")` and `dispatchKey("SHIFT_TAB")` use the same flow.
 
 ### `focusAt(x, y)`
 
-Busca el hitbox en las coordenadas actuales, actualiza hover semantico cuando aplica y enfoca ese nodo.
+Looks up the hitbox at the current coordinates, updates semantic hover when applicable, and focuses that node.
 
 ### `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
+- 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
 
 ```tsx
 const session = mountTerminal(() => (
@@ -237,14 +237,14 @@ session.focusAt(2, 1);
 session.clickAt(3, 2);
 ```
 
-## Keyboard dispatch por sesion
+## Per-session keyboard dispatch
 
-`dispatchKey(key)` procesa una tecla ya normalizada contra el nodo enfocado y devuelve la salida plana actual.
+`dispatchKey(key)` processes a normalized key against the focused node and returns the current plain-text output.
 
-Atajos soportados por la API publica observables en pruebas:
+Shortcuts supported by the public API and observable in tests:
 
-- 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`
+- 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`
@@ -275,14 +275,14 @@ session.dispatchKey("C");
 session.dispatchKey("ENTER");
 ```
 
-## Clipboard adapter y `clipboard: false`
+## Clipboard adapter and `clipboard: false`
 
-La sesion separa dos conceptos:
+The session separates two concepts:
 
-- buffer de clipboard de la sesion: `clipboard()` y `setClipboard()`
-- integracion con el sistema: `options.clipboard`
+- the session clipboard buffer: `clipboard()` and `setClipboard()`
+- system integration: `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.
+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.
 
 ```tsx
 const state = { value: "abcd" };
@@ -305,17 +305,17 @@ session.dispatchKey("END");
 session.dispatchKey("CTRL_V");
 ```
 
-## Streams `stdin` y `stdout`
+## `stdin` and `stdout` streams
 
-Conectar streams vuelve a la sesion util como runtime de CLI, no solo como helper de pruebas.
+Connecting streams makes the session useful as a CLI runtime, not just as a test helper.
 
-Comportamiento observable:
+Observable behavior:
 
-- 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`
+- 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
 
 ```tsx
 /** @jsx v */
@@ -351,12 +351,12 @@ session.destroy();
 
 ## ANSI output
 
-Hay dos formas practicas de trabajar con ANSI:
+There are two practical ways to work with ANSI:
 
-- `ansi: true` + `stdout`: la sesion emite diffs incrementales en cada rerender
-- `session.ansiOutput()`: recupera el frame ANSI completo del estado actual
+- `ansi: true` + `stdout`: the session emits incremental diffs on each rerender
+- `session.ansiOutput()`: retrieves the full ANSI frame for the current state
 
-Esto es especialmente util cuando la terminal consumidora necesita minimizar repaints o cuando quieres verificar cursor, foco y seleccion con escape sequences reales.
+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.
 
 ```tsx
 const state = { value: "AB" };
@@ -379,15 +379,15 @@ session.dispatchKey("LEFT");
 console.log(session.ansiOutput());
 ```
 
-## Mouse SGR, wheel y pointer capture
+## SGR mouse, wheel, and pointer capture
 
-Cuando conectas `stdin`, la sesion acepta secuencias SGR de mouse y las traduce a interaccion practica sobre el frame actual.
+When you connect `stdin`, the session accepts SGR mouse sequences and translates them into practical interaction over the current frame.
 
-### Press, drag y release
+### Press, drag, and 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
+- `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");
@@ -395,34 +395,34 @@ 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.
+That pattern is enough to select text inside an `Input` by coordinates.
 
 ### Wheel
 
-El wheel se despacha como navegacion vertical sobre el nodo bajo el puntero:
+Wheel input is dispatched as vertical navigation on the node under the pointer:
 
-- `wheel-up` equivale a `dispatchKey("UP")`
-- `wheel-down` equivale a `dispatchKey("DOWN")`
+- `wheel-up` is equivalent to `dispatchKey("UP")`
+- `wheel-down` is equivalent to `dispatchKey("DOWN")`
 
 ```ts
 stdin.emit("data", "\u001b[<65;2;1M");
 ```
 
-En un `ScrollView` enfocado o localizado por coordenadas, eso desplaza el viewport.
+In a focused `ScrollView`, or one resolved by coordinates, that scrolls the viewport.
 
-### Pointer capture a nivel practico
+### Pointer capture in practice
 
-`pointerCapture` hoy aplica a `List` y `ScrollView`.
+`pointerCapture` currently applies to `List` and `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:
+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:
 
 - `oncapturestart`
 - `oncaptureend`
 
-Esto es util para:
+This is useful for:
 
-- listas que deben seguir rastreando la fila activa durante drag
-- scroll views que conservan hover o release aunque el puntero termine fuera del viewport
+- 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
 
 ```tsx
 const session = mountTerminal(() => (
@@ -442,10 +442,10 @@ stdin.emit("data", "\u001b[<32;99;99M");
 stdin.emit("data", "\u001b[<0;99;99m");
 ```
 
-## Recomendaciones practicas
+## Practical recommendations
 
-- 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
+- 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

package/package.json

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