@valyrianjs/terminal 0.1.0 → 0.1.2

package/docs/core-concepts.md

@@ -1,93 +1,181 @@
 # Core Concepts
 
-Esta guia explica el modelo mental del paquete antes de entrar al detalle de runtime o referencia.
+This document explains the mental model for ValyrianJS Terminal. Read it after [Getting Started](./getting-started.md), then use the Cookbook, Primitive Gallery, and interaction guides before opening the API Reference as a lookup document.
 
-## 1. Primitivas terminal-first
+## Primitives
 
-`valyrianjs-terminal` no renderiza HTML ni componentes de navegador. Sus primitivas generan nodos terminales propios que luego se convierten en texto plano o en un frame ANSI.
+ValyrianJS Terminal renders terminal nodes, not HTML. The public primitives are grouped by role:
 
-Las piezas base se agrupan asi:
+- layout: `Screen`, `Box`, `View`, `Pane`, `Split`, `Fixed`, `Overlay`, `FocusScope`, `Table`, `Row`, `Td`
+- content: `Text`, `LogView`
+- interaction: `Input`, `Editor`, `Button`, `List`, `ScrollView`
 
-- layout: `Screen`, `Box`, `View`, `Text`, `Table`, `Row`, `Td`
-- interaccion: `Input`, `Button`, `List`, `ScrollView`
+`Screen` is the usual root. `Box`, `View`, `Pane`, and `Split` compose rows and columns. See [Primitive Gallery](./primitive-gallery.md) for a practical map of every primitive and complete mini apps such as [`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx), which runs with `bun examples/docs/primitive-layout-shell.tsx` and exits with `Ctrl+C`. `Fixed` reserves top, bottom, left, or right regions when it is a direct child of `Screen` or `Pane`. `Overlay` draws a clipped region over the current frame.
 
-Piensalo como un DSL de interfaces de texto, no como una adaptacion visual del DOM.
+`Screen`, `Box`, `View`, `Pane`, and `Split` use block-like layout defaults inside a render or session context. `Box`, `View`, and `Pane` take available width by default and keep content height by default. `Split` takes the available render area by default because it needs both axes to divide cells. Explicit numeric `width` and `height` always win. Use `fill` when a block surface should consume the full available height instead of stacking at content height.
 
-## 2. Dos modos de trabajo
+## Static render vs mounted session
 
-Hay dos entrypoints principales:
+There are two main entry points:
 
-- `renderTerminal()` para generar texto plano a partir de un arbol terminal
-- `mountTerminal()` para crear una sesion interactiva con foco, teclado, mouse y escritura opcional a streams
+- `renderTerminal()` returns plain text for a terminal tree.
+- `mountTerminal()` creates a `TerminalSession` with focus, dispatch, output, lifecycle, and optional stream integration.
 
-Regla simple:
+Use `renderTerminal()` for static output, examples, and snapshots. Use `mountTerminal()` when a UI needs interaction or repeated renders.
 
-- si solo quieres inspeccionar contenido, usa `renderTerminal()`
-- si necesitas interaccion o runtime vivo, usa `mountTerminal()`
+Related example: [`examples/docs/hello.tsx`](../examples/docs/hello.tsx). Run it with `bun examples/docs/hello.tsx`, press `Enter` for details, and quit with `Ctrl+C`.
 
-## 3. El estado vive fuera de la libreria
+```tsx
+import { Screen, Text, renderTerminal } from "@valyrianjs/terminal";
 
-La libreria renderiza lo que tu funcion de UI devuelve con el estado actual. No guarda un store de aplicacion por ti.
+const output = renderTerminal(
+  <Screen title="Static">
+    <Text>Hello terminal</Text>
+  </Screen>
+);
 
-Eso significa que:
+console.log(output);
+```
 
-- tus handlers mutan estado externo
-- `mountTerminal()` vuelve a evaluar la funcion de render
-- `session.update()` solo hace falta cuando mutaste estado fuera de un handler que ya detona rerender
+## State lives outside the renderer
 
-## 4. `id` es la llave de la interaccion
+Keep application state in your app layer. The renderer turns the tree returned by your function into terminal output using the state your app provides.
 
-Los nodos interactivos pueden renderizarse sin `id`, pero pierdes gran parte del control programatico.
+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`.
 
-Necesitas `id` estable si quieres:
+```tsx
+import { Button, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
-- enfocar con `session.focus(id)`
-- activar con `session.click(id)`
-- participar de hitboxes por coordenadas
-- recibir bien flujos de foco y navegacion
+const state = { count: 0 };
 
-Recomendacion practica: da `id` a todo `Input`, `Button`, `List` y `ScrollView` que vaya a vivir mas de una prueba trivial.
+function App() {
+  return (
+    <Screen title="Counter">
+      <Text>Count: {state.count}</Text>
+      <Button id="increment" onpress={() => {
+        state.count += 1;
+      }}>
+        Increment
+      </Button>
+    </Screen>
+  );
+}
 
-## 5. Foco e hitboxes
+const session = mountTerminal(<App />);
 
-La sesion calcula hitboxes a partir del frame renderizado actual. Eso permite dos clases de interaccion:
+session.focus("increment");
+session.dispatchKey("ENTER");
 
-- por identificador: `focus(id)`, `click(id)`
-- por coordenadas: `focusAt(x, y)`, `clickAt(x, y)`
+console.log(session.output());
+session.destroy();
+```
 
-El foco secuencial tambien sale del arbol actual:
+For larger UIs, Valyrian state modules can hold shared state outside the terminal tree. `createPulseStore` is useful when named transitions make state changes clearer.
 
-- `focusNext()`
-- `focusPrev()`
-- `dispatchKey("TAB")`
-- `dispatchKey("SHIFT_TAB")`
+Related example: [`examples/docs/employees-list.tsx`](../examples/docs/employees-list.tsx). Run it with `bun examples/docs/employees-list.tsx`, choose a person with `J/K` or arrows, and quit with `Ctrl+C`.
 
-Si cambia el arbol, cambia tambien el orden y la geometria del foco.
+```tsx
+import { createPulseStore } from "valyrian.js/pulses";
+import { Button, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
-## 6. Salida plana vs salida ANSI
+const counter = createPulseStore(
+  { count: 0 },
+  {
+    increment(state) {
+      state.count += 1;
+    }
+  }
+);
 
-El paquete maneja dos representaciones utiles:
+function App() {
+  return (
+    <Screen title="Pulse store">
+      <Text>Count: {counter.state.count}</Text>
+      <Button id="increment" onpress={() => counter.increment()}>
+        Increment
+      </Button>
+    </Screen>
+  );
+}
 
-- salida plana: la devuelven `renderTerminal()` y `session.output()`
-- salida ANSI: la devuelve `session.ansiOutput()` y, si activas `ansi: true`, tambien se escribe a `stdout`
+const session = mountTerminal(<App />);
 
-Usa salida plana para snapshots y pruebas. Usa ANSI cuando necesitas cursor, spans visuales, foco o integracion con una terminal real.
+session.focus("increment");
+session.dispatchKey("ENTER");
 
-## 7. Streams y cleanup
+console.log(session.output());
+session.destroy();
+```
 
-`mountTerminal()` puede trabajar sin streams, pero si conectas `stdin` y `stdout` la sesion entra en modo runtime real.
+If components read Valyrian reactive state, the terminal refreshes when that state changes. Call `session.update()` for non-reactive state or for an explicit manual refresh.
 
-Cuando montas con `stdin`:
+## Valyrian.js modules as app-layer state and workflow
 
-- la sesion escucha `data`
-- intenta activar raw mode si el stream lo soporta
-- intenta restaurarlo al llamar `destroy()`
+Valyrian.js modules in terminal apps stay in the app layer. The terminal adapter renders terminal nodes, handles focus, dispatches input, and exposes session output. Your app still owns routing choices, command design, data loading, persistence, and state transitions.
 
-Por eso `destroy()` no es opcional cuando conectaste streams reales.
+Use `valyrian.js/pulses` and `valyrian.js/flux-store` for shared state, `valyrian.js/forms` for canonical input state, `valyrian.js/request` and `valyrian.js/query` for API and cached reads, `valyrian.js/tasks` for async actions, `valyrian.js/translate` and `valyrian.js/money` for user-facing formatting, and `valyrian.js/native-store` plus `valyrian.js/utils` for local settings and helper logic. When async work changes Valyrian reactive state read by components, the terminal refreshes automatically.
 
-## 8. Donde seguir
+Read the dedicated guide at [`docs/valyrian-modules.md`](./valyrian-modules.md) for terminal-specific module patterns. Related complete demos: **Operations Workbench** ([`examples/docs/module-state-workbench.tsx`](../examples/docs/module-state-workbench.tsx)), **API Operations Dashboard** ([`examples/docs/module-api-dashboard.tsx`](../examples/docs/module-api-dashboard.tsx)), and **Billing/Settings Wizard** ([`examples/docs/module-form-workflow.tsx`](../examples/docs/module-form-workflow.tsx)). Run them with `bun examples/docs/module-state-workbench.tsx`, `bun examples/docs/module-api-dashboard.tsx`, or `bun examples/docs/module-form-workflow.tsx`, try the keys shown in each footer, and quit with `Ctrl+C`.
 
-- `docs/interaction-model.md` explica que hace cada primitiva interactiva
-- `docs/session-runtime.md` explica lifecycle, streams, clipboard, coordenadas y mouse
-- `docs/cookbook.md` muestra recetas cortas para tareas comunes
-- `docs/api-reference.md` sirve como consulta puntual
+## Stable ids and focus
+
+Interactive nodes can render without an `id`, but stable ids are required for most programmatic interaction.
+
+Use stable ids when you need:
+
+- `session.focus(id)`
+- `session.click(id)`
+- `focusAt(x, y)` or `clickAt(x, y)` to resolve a hitbox consistently
+- keyboard traversal with predictable focus order
+
+Practical rule: give every long-lived `Input`, `Editor`, `Button`, `List`, and `ScrollView` an `id`.
+
+Focus belongs to the `TerminalSession`; app state remains yours. `FocusScope` can bound sequential traversal inside a local group, and `Overlay trapFocus` can keep traversal inside an overlay while it is present.
+
+## 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.
+
+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`.
+
+Common states include `focus`, `hover`, `disabled`, and `loading`. Controls can use `pressed`, `checked`, `unchecked`, and `indeterminate`. Navigation can use `selected`, `current`, `expanded`, and `collapsed`. Entry fields can use `invalid`, `valid`, `readonly`, `placeholder`, `selection`, `editing`, and `submitted`. Content can use `empty`, `error`, `warning`, `success`, and `muted`. Pointer-style composition can use `dragging`, `dropTarget`, and `capturing`.
+
+Use `style={{ background: "#111111" }}` or a theme recipe to fill a surface. `margin` is not included; compose spacing with layout, padding, and explicit text when needed.
+
+## Plain text vs ANSI output
+
+The package exposes two output representations:
+
+- plain text: `renderTerminal()` and `session.output()`
+- ANSI output: `session.ansiOutput()` and app-runtime `stdout` writes
+
+Plain text belongs to `renderTerminal()`, `session.output()`, snapshots, and scripted checks. ANSI output is for runtime integration when a terminal needs cursor movement or style spans.
+
+Keep ordinary rendered content as text. Do not build normal app behavior by placing escape sequences in `Text`, input values, list rows, or log entries. Use semantic spans, themes, and the documented runtime output paths instead.
+
+Style borders are opt-in through style recipes. Plain output remains readable, and ANSI output applies style spans when supported.
+
+## Cleanup and lifecycle
+
+`mountTerminal()` can run without streams, which is useful for examples and scripted interaction. When you connect real streams, cleanup matters.
+
+The session lifecycle is:
+
+1. mount with `mountTerminal()`
+2. read `output()` or `ansiOutput()`
+3. dispatch input or mutate state
+4. call `update()` when needed
+5. call `destroy()` when finished
+
+When `stdin` is connected, the session may attach listeners, enable raw mode when supported, and resume the stream. `destroy()` removes listeners and restores terminal state where the connected streams support it.
+
+Connected streams follow terminal and runtime capabilities. Use [Session Runtime](./session-runtime.md) when integrating with `stdin`, `stdout`, resize events, clipboard adapters, or mouse input.
+
+## Where to go next
+
+- [Cookbook](./cookbook.md) for practical recipes.
+- [Primitive Gallery](./primitive-gallery.md) for choosing and composing public terminal primitives.
+- [Interaction Model](./interaction-model.md) for focus, keys, mouse, and event payloads.
+- [Session Runtime](./session-runtime.md) for common usage and advanced host integration.
+- [Valyrian Modules](./valyrian-modules.md) for terminal app patterns with Valyrian.js modules.
+- [API Reference](./api-reference.md) for props and session methods.

package/docs/getting-started.md

@@ -1,148 +1,267 @@
 # Getting Started
 
-Esta guia cubre el happy path minimo para empezar con `valyrianjs-terminal`.
+This guide creates a first functional terminal UI. You will configure JSX, create `main.tsx`, render a static frame, then mount an interactive session.
 
-## 1. Instala los paquetes
+## What you will build
+
+You will build a small note UI with:
+
+- a static render path for snapshots or one-off output
+- an interactive input path for keyboard-driven sessions
+- a simple bridge from local state to Valyrian state modules when the UI grows
+
+## Install
 
 ```bash
-npm install valyrianjs-terminal valyrian.js
+npm install @valyrianjs/terminal valyrian.js
 ```
 
-## 2. Empieza con render estatico
+## Configure JSX
 
-Primero valida layout y contenido sin streams ni runtime interactivo.
+Add this JSX config to your TypeScript configuration so TSX files can use Valyrian's automatic JSX runtime:
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "valyrian.js"
+  }
+}
+```
+
+Manual `v(...)` nodes still work, but the examples below use TSX.
 
-import { v } from "valyrian.js";
-import { Screen, Text, renderTerminal } from "valyrianjs-terminal";
+## Create `main.tsx`
+
+Create `main.tsx` with a render-only first pass:
+
+```tsx
+import { Screen, Text, renderTerminal } from "@valyrianjs/terminal";
 
 const output = renderTerminal(
-  <Screen title="Status">
+  <Screen title="First terminal UI">
     <Text>Hello terminal</Text>
-    <Text>Status: ok</Text>
+    <Text>Status: ready</Text>
   </Screen>
 );
 
 console.log(output);
 ```
 
-Usa este camino cuando quieras:
+## Run it
 
-- generar snapshots
-- validar layout
-- probar salida plana sin conectar `stdin` ni `stdout`
+Use your TypeScript runner of choice for the run command. With Bun:
 
-## 3. Sube a una sesion interactiva minima
+```bash
+bun run main.tsx
+```
 
-Cuando ya necesitas editar texto, manejar foco o reaccionar a teclado, cambia a `mountTerminal()`.
+Expected plain output:
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+```text
+First terminal UI
+Hello terminal
+Status: ready
+```
+
+## Static rendering with `renderTerminal`
+
+Use `renderTerminal()` for deterministic plain-text output:
+
+- snapshots
+- examples in docs
+- layout checks
+- non-interactive command output
+
+This path fits snapshots, documentation examples, layout checks, and non-interactive command output. Move to `mountTerminal()` when the experience needs focus, keyboard input, clipboard behavior, mouse behavior, or repeated renders.
+
+## Interactive sessions with `mountTerminal`
 
-import { v } from "valyrian.js";
-import { Button, Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+Switch to `mountTerminal()` when the UI needs focus, keyboard input, clipboard behavior, mouse behavior, or repeated renders.
+
+Replace `main.tsx` with this interactive version:
+
+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` to save, and quit with `Ctrl+C`.
+
+```tsx
+import { Button, Input, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
 const state = { value: "", saved: "" };
 
-const session = mountTerminal(() => (
-  <Screen title="Quick Note">
-    <Input
-      id="note"
-      value={state.value}
-      placeholder="Write a quick note"
-      onchange={(event) => {
-        state.value = event.value;
-      }}
-      onsubmit={(event) => {
-        state.saved = event.value;
-      }}
-    />
-    <Button
-      id="save"
-      onpress={() => {
-        state.saved = state.value;
-      }}
-    >
-      Save
-    </Button>
-    <Text>{state.saved || "Nothing saved yet"}</Text>
-  </Screen>
-));
+function App() {
+  return (
+    <Screen title="Quick note">
+      <Input
+        id="note"
+        value={state.value}
+        placeholder="Write a quick note"
+        onchange={(event) => {
+          state.value = event.value;
+        }}
+        onsubmit={(event) => {
+          state.saved = event.value;
+        }}
+      />
+      <Button
+        id="save"
+        onpress={() => {
+          state.saved = state.value;
+        }}
+      >
+        Save
+      </Button>
+      <Text>{state.saved || "Nothing saved yet"}</Text>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
 
 session.focus("note");
 session.dispatchKey("H");
 session.dispatchKey("i");
+session.dispatchKey("ENTER");
 
 console.log(session.output());
+session.destroy();
 ```
 
-Regla practica: da `id` estables a `Input`, `Button`, `List` y `ScrollView` si quieres usar foco, coordenadas o interaccion programatica.
+This example uses programmatic key dispatch for a complete first project. In a real terminal session, pass compatible `stdin` and `stdout` options and call `destroy()` when the session is done.
 
-## 4. Entiende el lifecycle minimo
+For styled surfaces and visual states, run `bun examples/docs/style-system.tsx`, try `Tab`, `Enter`, and `W`, and quit with `Ctrl+C`; or open [`examples/docs/style-system.tsx`](../examples/docs/style-system.tsx). For responsive columns and rows, run `bun examples/docs/responsive-split.tsx`, resize the terminal to change the layout, and quit with `Ctrl+C`; or open [`examples/docs/responsive-split.tsx`](../examples/docs/responsive-split.tsx).
 
-La sesion no guarda tu estado de negocio; vuelve a evaluar la funcion de render con el estado externo actual.
+## Add state when the UI grows
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+Small examples can use local state. As the UI grows, keep application state in your app layer and use Valyrian state modules such as `createPulseStore` when named transitions fit your app.
+
+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`.
 
-import { v } from "valyrian.js";
-import { Screen, Text, mountTerminal } from "valyrianjs-terminal";
+```tsx
+import { createPulseStore } from "valyrian.js/pulses";
+import { Button, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+
+const counter = createPulseStore(
+  { count: 0 },
+  {
+    increment(state) {
+      state.count += 1;
+    }
+  }
+);
 
-const state = { count: 0 };
+function App() {
+  return (
+    <Screen title="Counter">
+      <Text>Count: {counter.state.count}</Text>
+      <Button id="increment" onpress={() => counter.increment()}>
+        Increment
+      </Button>
+    </Screen>
+  );
+}
 
-const session = mountTerminal(() => (
-  <Screen>
-    <Text>Count: {state.count}</Text>
-  </Screen>
-));
+const session = mountTerminal(<App />);
 
-state.count += 1;
-session.update();
+session.focus("increment");
+session.dispatchKey("ENTER");
 
 console.log(session.output());
 session.destroy();
 ```
 
-Resumen rapido:
+ValyrianJS Terminal renders the current state and reports events while your app layer owns product state, routing, and workflow choices.
 
-- `output()` devuelve el frame actual en texto plano
-- `ansiOutput()` devuelve el frame actual como ANSI completo
-- `update()` reevalua la funcion de render
-- `destroy()` desmonta listeners y limpia `stdin` cuando aplica
+## Compose reusable components
 
-## 5. Cuando conectar streams
+Terminal UIs are regular Valyrian component trees. Extract small components when a screen repeats a pattern, pass scalar props for simple labels, pass object props for domain rows, and render arrays as lists of components.
 
-Conecta `stdin`, `stdout` y `ansi: true` solo cuando ya vas a correr una UI real en terminal.
+Full 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
-/** @jsx v */
-/** @jsxFrag v.fragment */
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
-import { v } from "valyrian.js";
-import { Screen, Text, mountTerminal } from "valyrianjs-terminal";
+function StatusBadge() {
+  return <Text>Status: Ready</Text>;
+}
 
-const session = mountTerminal(() => (
-  <Screen title="Live App">
-    <Text>Streaming to the terminal</Text>
-  </Screen>
-), {
-  stdin: process.stdin,
-  stdout: process.stdout,
-  ansi: true
-});
+function Greeting({ name }: { name: string }) {
+  return <Text>Hello, {name}</Text>;
+}
+
+function App() {
+  return (
+    <Screen title="Components">
+      <StatusBadge />
+      <Greeting name="Maya" />
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
+
+console.log(session.output());
+session.destroy();
 ```
 
-Para pruebas o snapshots, normalmente basta con `renderTerminal()` o `mountTerminal()` sin streams.
+`StatusBadge` demonstrates a component with no props: it always renders the same terminal content. `Greeting` demonstrates a scalar prop: the parent keeps the value and passes a plain string into the reusable component.
+
+Full example: [`examples/docs/employees-list.tsx`](../examples/docs/employees-list.tsx). Run it with `bun examples/docs/employees-list.tsx`, choose a person with `J/K` or arrows, and quit with `Ctrl+C`.
+
+```tsx
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+
+type EmployeeData = {
+  name: string;
+  role: string;
+};
+
+const employees: EmployeeData[] = [
+  { name: "Ana", role: "Design" },
+  { name: "Luis", role: "Support" },
+  { name: "Maya", role: "Engineering" }
+];
+
+function Employee({ data }: { data: EmployeeData }) {
+  return <Text>{`${data.name} — ${data.role}`}</Text>;
+}
+
+function Employees({ items }: { items: EmployeeData[] }) {
+  return (
+    <>
+      {items.map((employee) => (
+        <Employee data={employee} />
+      ))}
+    </>
+  );
+}
+
+function App() {
+  return (
+    <Screen title="Team">
+      <Employees items={employees} />
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
+
+console.log(session.output());
+session.destroy();
+```
+
+`Employee data={...}` demonstrates an object prop for a domain row. `Employees items={...}` demonstrates list composition: the parent owns the array and maps each item into a reusable child component.
+
+Use the same composition rules as any declarative terminal tree:
+
+- Treat components as small JSX functions that receive props and return terminal elements.
+- The app owns state, data loading, routing decisions, and effects. When components read Valyrian reactive state, external async changes refresh the terminal automatically. Use `session.update()` for non-reactive state or an explicit manual refresh.
+- Use stable `id` values when focus or programmatic dispatch targets a specific interactive node.
+- Keep terminal-specific behavior in public primitives, props, and events instead of hidden component side effects.
 
-## Siguiente lectura
+## Next steps
 
-- `docs/core-concepts.md`
-- `docs/interaction-model.md`
-- `docs/session-runtime.md`
-- `docs/cookbook.md`
-- `docs/api-reference.md`
+- [Core Concepts](./core-concepts.md) for the package mental model.
+- [Cookbook](./cookbook.md) for practical recipes after the first project.
+- [Interaction Model](./interaction-model.md) for focus, keyboard, mouse, and events.
+- [Session Runtime](./session-runtime.md) for stream and host integration.
+- [API Reference](./api-reference.md) for props, payloads, and session methods.