blessed-components 0.0.1 → 1.0.0

package/ROADMAP.md

@@ -1,53 +1,93 @@
 # blessed-components — Roadmap
 
-Biblioteca de componentes reutilizables para interfaces de terminal construidas
-sobre `blessed`.
+Composable, typed terminal UI components built on top of `blessed`.
 
-## Visión
+## Vision
 
-Convertir bloques de texto, tags, Unicode, cálculo de ancho y estado en
-componentes con:
+Turn manual strings, Blessed tags, Unicode glyphs, width calculations, keyboard
+handling, and lifecycle cleanup into reusable components with:
 
-- API pequeña y consistente.
-- renderizado determinista.
-- actualización de datos sin reconstruir pantalla.
-- soporte para terminales estrechas, sin color y sin Unicode.
-- integración directa con elementos `blessed`.
-- pruebas mediante API pública.
+- small, consistent public APIs;
+- deterministic renderers;
+- structured data instead of presentation strings;
+- responsive behavior for narrow terminals;
+- Unicode, ASCII, color, and no-color modes;
+- predictable focus and keyboard interaction;
+- direct integration with Blessed elements;
+- tests through public behavior;
+- no leaked listeners, timers, or processes.
 
-## Vocabulario
+## Product position
 
-Los ejemplos iniciales representan dos componentes distintos:
+Blessed already provides low-level elements such as boxes, lists, forms,
+prompts, tables, progress bars, logs, terminals, images, and layouts.
+`blessed-contrib` adds dashboard-oriented charts, gauges, maps, sparklines,
+tables, trees, Markdown, grids, and carousels.
 
-| Nombre        | Responsabilidad                                          |
-| ------------- | -------------------------------------------------------- |
-| `Sparkline`   | Serie temporal compacta usando `▁▂▃▄▅▆▇█`.               |
-| `MetricBars`  | Grupo de métricas con barras horizontales y porcentajes. |
-| `ProgressBar` | Una sola barra horizontal. Base usada por `MetricBars`.  |
-| `Stat`        | Etiqueta y valor destacado.                              |
-| `Card`        | Marco opcional que compone título, contenido y pie.      |
+This library should not become another collection of thin aliases.
 
-`BarChart` queda reservado para barras que representan categorías o series. No
-debe usarse para `Sparkline` ni `ProgressBar`.
+Its advantage should be:
 
-## API pública propuesta
+1. typed and consistent APIs;
+2. pure renderers that work without a live terminal;
+3. composition from small primitives;
+4. responsive width and height behavior;
+5. explicit controlled and uncontrolled state;
+6. keyboard maps and focus contracts;
+7. themes and semantic visual tokens;
+8. lifecycle safety;
+9. maintained tests and documentation;
+10. optional adapters for existing Blessed capabilities.
 
-Dos capas:
+## Artifact taxonomy
 
-1. Renderers puros: reciben datos y retornan contenido compatible con
-   `blessed`.
-2. Widgets: crean elementos `blessed`, conservan estado y exponen `setData`.
+| Artifact  | Meaning in this project                               | Examples                      |
+| --------- | ----------------------------------------------------- | ----------------------------- |
+| Utility   | Non-visual, framework-independent logic.              | width, scale, format, keymaps |
+| Primitive | One low-level terminal behavior with minimal styling. | focus scope, viewport         |
+| Component | Reusable visual unit with useful defaults.            | progress bar, badge           |
+| Pattern   | Documented composition solving recurring behavior.    | async state, confirm flow     |
+| Block     | Opinionated application-level composition.            | process monitor, git status   |
+| Template  | Complete terminal application scaffold.               | dashboard starter             |
+
+Components belong in the npm package. Blocks and templates should remain
+examples until repeated use proves a stable public API.
+
+## Naming
+
+The initial examples represent different components:
+
+| Name          | Responsibility                                          |
+| ------------- | ------------------------------------------------------- |
+| `Sparkline`   | Compact time series using `▁▂▃▄▅▆▇█`.                   |
+| `MetricBars`  | Labeled metrics rendered as aligned horizontal bars.    |
+| `ProgressBar` | One bounded horizontal bar.                             |
+| `BarChart`    | Comparison of categories or series.                     |
+| `Stat`        | Label, highlighted value, and optional trend.           |
+| `Card`        | Composable frame with header, body, and footer regions. |
+
+`Sparkline`, `ProgressBar`, and `BarChart` must not be used as interchangeable
+names.
+
+## Proposed public API
+
+Use two layers:
+
+1. Pure renderers receive data and return Blessed-compatible content or render
+   models.
+2. Blessed adapters create elements, connect events, retain state, and expose
+   lifecycle methods.
 
 ```ts
 import {
-  renderSparkline,
+  metricBars,
   renderMetricBars,
+  renderSparkline,
   sparkline,
-  metricBars,
 } from 'blessed-components'
 ```
 
-### Renderer puro
+### Pure renderer
 
 ```ts
 const content = renderSparkline({
@@ -58,7 +98,7 @@ const content = renderSparkline({
 })
 ```
 
-### Widget Blessed
+### Blessed component
 
 ```ts
 const downloads = sparkline({
@@ -76,7 +116,7 @@ const downloads = sparkline({
 downloads.setData(nextDownloadsByDay)
 ```
 
-### MetricBars
+### Metric bars
 
 ```ts
 const score = metricBars({
@@ -93,314 +133,667 @@ const score = metricBars({
 })
 ```
 
-## Principios de diseño
+## Design principles
+
+- Separate data, rendering, and Blessed lifecycle.
+- Keep pure renderers as the source of visual truth.
+- Make Blessed adapters thin.
+- Prefer composition over components with dozens of options.
+- Reuse one scaling primitive across progress bars, gauges, and charts.
+- Reuse one selection model across lists, tables, trees, menus, and palettes.
+- Let callers decide when `screen.render()` runs.
+- Calculate dimensions from actual inner width and height.
+- Clamp bounded values.
+- Never mutate caller-owned arrays or objects.
+- Escape dynamic text before applying Blessed tags.
+- Use semantic theme tokens, not hard-coded presentation tags.
+- Export all public option, state, event, and handle types.
+- Keep `blessed` as a peer dependency.
+- Add dependencies only when they provide substantial value.
+
+## State model
+
+Interactive components should support both modes when useful:
+
+- Controlled: caller supplies state and receives change events.
+- Uncontrolled: component owns state from a `defaultValue`.
+
+Examples:
+
+```ts
+select({ value, onValueChange })
+select({ defaultValue })
+
+tabs({ activeId, onActiveIdChange })
+tabs({ defaultActiveId })
+```
+
+Do not add both modes to display-only components.
+
+## Common component handle
+
+Candidate interface:
+
+```ts
+interface ComponentHandle<TData, TElement> {
+  readonly element: TElement
+  setData(data: TData): void
+  focus(): void
+  render(): void
+  destroy(): void
+}
+```
 
-- Datos separados de presentación.
-- Renderer puro como fuente única del contenido.
-- Widget `blessed` como adaptador fino.
-- `setData` actualiza contenido; caller decide cuándo ejecutar
-  `screen.render()`.
-- Dimensiones automáticas usan ancho interior real.
-- Valores fuera de rango se limitan mediante `clamp`.
-- Datos inválidos producen error descriptivo o estado vacío documentado.
-- Tema mediante tokens semánticos, no tags escritos por consumidor.
-- Colores y caracteres configurables por componente.
-- Sin mutación de arrays u objetos recibidos.
-- TypeScript primero; tipos publicados con paquete.
-- Dependencia `blessed` como `peerDependency`.
+Adopt only after the first vertical slice. Returning an extended Blessed
+element may produce a smaller API. The tracer bullet must decide this.
 
-## Arquitectura objetivo
+## Target architecture
 
 ```text
 src/
   core/
-    width.ts
-    scale.ts
+    capabilities.ts
+    characters.ts
+    color.ts
+    crop.ts
+    events.ts
+    focus.ts
     format.ts
-    theme.ts
+    keymap.ts
+    layout.ts
+    render-model.ts
+    scale.ts
     tags.ts
+    theme.ts
+    truncate.ts
+    width.ts
+  primitives/
+    collection/
+    focus-scope/
+    overlay/
+    scroll-area/
+    selection/
+    viewport/
   components/
-    stat/
-    progress-bar/
-    sparkline/
-    metric-bars/
+    data-display/
+    feedback/
+    input/
+    layout/
+    navigation/
+    visualization/
   adapters/
-    blessed.ts
+    blessed/
+  blocks/
+    examples-only/
   index.ts
 tests/
   public-api/
   blessed-integration/
+  terminal-fixtures/
 examples/
+  component-gallery/
   dashboard/
+  process-monitor/
 ```
 
-`core` no conoce `blessed`. `components` usa `core` para producir modelos o
-contenido. `adapters` conecta contenido, eventos y ciclo de vida con
-`blessed`.
-
-## Estrategia TDD
-
-Desarrollo por cortes verticales. Nunca escribir todas las pruebas antes de
-toda la implementación.
-
-```text
-RED: prueba de un comportamiento público
-  ↓
-GREEN: implementación mínima
-  ↓
-REFACTOR: limpiar manteniendo verde
-  ↓
-siguiente comportamiento
-```
-
-Prioridad de pruebas:
-
-1. Salida visible del renderer público.
-2. Límites, escalado y ancho disponible.
-3. Actualización mediante `setData`.
-4. Integración real con elemento `blessed`.
-5. Fallbacks ASCII, sin color y estado vacío.
-
-Evitar pruebas de funciones privadas, mocks internos o estructura de carpetas.
-Snapshots grandes no serán contrato principal; usar expectativas pequeñas y
-legibles.
-
-## Hitos
-
-### M0 — Fundación del paquete
-
-Objetivo: paquete instalable, testeable y publicable.
-
-- Configurar TypeScript.
-- Elegir runner de pruebas.
-- Definir builds ESM y CommonJS según compatibilidad real de `blessed`.
-- Configurar lint, format, coverage y CI.
-- Publicar exports y tipos.
-- Añadir ejemplo mínimo que monte un componente en `blessed`.
-
-Criterio de salida:
-
-- `npm test`, `npm run build` y typecheck pasan.
-- consumidor externo puede importar un renderer.
-- CI prueba versiones Node soportadas.
-
-### M1 — Tracer bullet: ProgressBar
-
-Objetivo: probar camino completo renderer → widget → pantalla.
-
-Ciclos RED→GREEN:
-
-1. Renderiza barra al 50% con ancho fijo.
-2. Limita valores menores que `min` y mayores que `max`.
-3. Muestra etiqueta y valor formateado.
-4. Respeta ancho interior estrecho.
-5. `setData` cambia contenido del widget.
-6. Usa caracteres ASCII cuando Unicode está desactivado.
-
-Criterio de salida:
-
-- API pública validada con un componente pequeño.
-- patrón reutilizable para próximos widgets.
-
-### M2 — Sparkline
-
-Objetivo: componetizar gráfico de descargas.
-
-Ciclos RED→GREEN:
-
-1. Escala valores al rango `▁`…`█`.
-2. Conserva orden de serie.
-3. Maneja serie constante sin división por cero.
-4. Maneja serie vacía con placeholder.
-5. Reduce o recorta datos según ancho disponible.
-6. Renderiza label, valor principal y summary opcionales.
-7. Actualiza serie mediante `setData`.
-8. Permite dominio explícito `{ min, max }`.
-
-Criterio de salida:
-
-- ejemplo `downloads` ya no contiene strings de presentación manuales.
-- salida estable en terminal estrecha.
-
-### M3 — MetricBars
-
-Objetivo: componetizar score general y desglose.
-
-Ciclos RED→GREEN:
-
-1. Renderiza una métrica mediante `ProgressBar`.
-2. Alinea labels usando ancho visible, no longitud bruta con tags.
-3. Renderiza varias métricas en orden.
-4. Calcula ancho restante para barra y valor.
-5. Trunca labels largos.
-6. Admite valor general opcional.
-7. Actualiza una lista completa mediante `setData`.
-
-Criterio de salida:
-
-- ejemplo `score` usa datos estructurados.
-- `MetricBars` compone `ProgressBar`; no duplica escalado.
-
-### M4 — Sistema visual
-
-Objetivo: consistencia entre componentes.
-
-- `Theme`: `primary`, `muted`, `success`, `warning`, `danger`, `border`.
-- Presets `unicode`, `ascii`, `noColor`.
-- `formatNumber`, `formatPercent`, `formatDuration`, `formatBytes`.
-- Utilidad de ancho visible compatible con tags `blessed`.
-- Escape seguro de texto dinámico.
-- Estados `empty`, `loading`, `error`, `disabled`.
-
-Criterio de salida:
-
-- consumidor cambia apariencia sin construir tags manuales.
-- texto con llaves o tags no rompe contenido.
-
-### M5 — Composición de dashboard
+`core` must not import Blessed. `primitives` model shared behavior.
+`components` compose core logic and primitives. `adapters/blessed` owns Blessed
+elements and events.
+
+## Component opportunity analysis
+
+Legend:
+
+- **Build**: strong fit and clear differentiation.
+- **Adapt**: wrap or compose existing Blessed behavior with better contracts.
+- **Research**: valuable, but API or terminal behavior needs validation.
+- **Defer**: expensive, niche, or already served well elsewhere.
+
+### 1. Foundation utilities
+
+These unlock almost every visual component and should be built first.
+
+| Utility              | Purpose                                                   | Decision | Priority |
+| -------------------- | --------------------------------------------------------- | -------- | -------- |
+| `visibleWidth`       | Measure text while ignoring Blessed tags and ANSI codes.  | Build    | P0       |
+| `truncate`           | End, middle, and start truncation by terminal cell width. | Build    | P0       |
+| `wrapText`           | Cell-aware wrapping with indentation.                     | Build    | P0       |
+| `escapeTags`         | Prevent dynamic text from becoming Blessed markup.        | Build    | P0       |
+| `scaleValue`         | Map numeric domains into cell or glyph ranges.            | Build    | P0       |
+| `clamp`              | Bound values safely.                                      | Build    | P0       |
+| `sampleSeries`       | Downsample time-series data to available width.           | Build    | P0       |
+| `formatNumber`       | Locale-aware compact and full numbers.                    | Build    | P0       |
+| `formatPercent`      | Consistent percentages and precision.                     | Build    | P0       |
+| `formatBytes`        | IEC/SI byte formatting.                                   | Build    | P1       |
+| `formatDuration`     | Human and clock duration formats.                         | Build    | P1       |
+| `formatRate`         | Values per second or interval.                            | Build    | P1       |
+| `formatDateTime`     | Terminal-friendly timestamps.                             | Build    | P1       |
+| `detectCapabilities` | Unicode, color depth, mouse, and terminal features.       | Build    | P1       |
+| `createKeymap`       | Normalized key bindings with help metadata.               | Build    | P1       |
+| `createTheme`        | Merge semantic tokens and component overrides.            | Build    | P1       |
+| `renderToString`     | Render pure models for tests and static terminal output.  | Build    | P1       |
+| `diffRows`           | Identify changed rows for high-frequency updates.         | Research | P2       |
+
+### 2. Layout and composition
+
+Blessed has positioning and a basic layout element. Opportunity exists in
+predictable, typed composition and responsive rules.
+
+| Component       | Purpose                                                 | Decision | Priority |
+| --------------- | ------------------------------------------------------- | -------- | -------- |
+| `Box`           | Typed base container with theme defaults.               | Adapt    | P1       |
+| `Card`          | Root, header, title, description, body, footer.         | Build    | P1       |
+| `Stack`         | Vertical or horizontal flow with gaps.                  | Build    | P1       |
+| `Cluster`       | Wrapping inline group for badges and actions.           | Build    | P2       |
+| `Grid`          | Responsive row/column placement with spans.             | Build    | P2       |
+| `SplitPane`     | Resizable horizontal or vertical regions.               | Research | P2       |
+| `SidebarLayout` | Sidebar plus main content with collapse rules.          | Build    | P2       |
+| `Center`        | Center one child in available space.                    | Build    | P2       |
+| `Spacer`        | Flexible or fixed empty space.                          | Build    | P2       |
+| `Divider`       | Horizontal or vertical separator with optional label.   | Build    | P1       |
+| `AspectRatio`   | Preserve cell-aware proportions.                        | Research | P3       |
+| `Viewport`      | Measure and expose available inner dimensions.          | Build    | P1       |
+| `ScrollArea`    | Consistent scrollbar, paging, and scroll events.        | Adapt    | P1       |
+| `Resizable`     | Keyboard/mouse resize behavior for one region.          | Research | P3       |
+| `Collapsible`   | Show or hide a region while preserving state.           | Build    | P2       |
+| `Accordion`     | Multiple collapsible sections with keyboard navigation. | Build    | P2       |
+| `Page`          | Full-screen region with title and action slots.         | Build    | P2       |
+| `AppShell`      | Header, footer, sidebar, content, and overlay layers.   | Build    | P2       |
+
+### 3. Typography and small data display
+
+High value, low complexity, excellent early components.
+
+| Component         | Purpose                                               | Decision | Priority |
+| ----------------- | ----------------------------------------------------- | -------- | -------- |
+| `Text`            | Safe themed text with truncation and wrapping.        | Adapt    | P0       |
+| `Heading`         | Hierarchical terminal heading styles.                 | Build    | P1       |
+| `Label`           | Stable labels for controls and values.                | Build    | P1       |
+| `MutedText`       | Secondary information using semantic theme tokens.    | Build    | P1       |
+| `Code`            | Inline code with safe escaping.                       | Build    | P2       |
+| `Preformatted`    | Preserve whitespace with horizontal scroll policy.    | Build    | P2       |
+| `Stat`            | Label, value, unit, trend, and description.           | Build    | P0       |
+| `KeyValue`        | Aligned label/value rows.                             | Build    | P1       |
+| `DescriptionList` | Responsive term/description groups.                   | Build    | P2       |
+| `Badge`           | Compact semantic status.                              | Build    | P1       |
+| `Tag`             | Removable or static categorization token.             | Build    | P2       |
+| `Pill`            | Rounded-character compact label where supported.      | Defer    | P3       |
+| `Timestamp`       | Formatted absolute or relative time.                  | Build    | P2       |
+| `Trend`           | Up/down/flat indicator with accessible text fallback. | Build    | P1       |
+| `Rating`          | Discrete score using symbols and text fallback.       | Research | P3       |
+| `Kbd`             | Display keyboard shortcuts consistently.              | Build    | P1       |
+| `Breadcrumb`      | Current location path with truncation.                | Build    | P2       |
+
+### 4. Progress, status, and feedback
+
+These components share bounded values, semantic tones, and live updates.
+
+| Component            | Purpose                                                 | Decision | Priority |
+| -------------------- | ------------------------------------------------------- | -------- | -------- |
+| `ProgressBar`        | One determinate horizontal progress bar.                | Build    | P0       |
+| `ProgressStack`      | Segmented progress across categories.                   | Build    | P1       |
+| `ProgressList`       | Multiple labeled progress rows.                         | Build    | P1       |
+| `Spinner`            | Indeterminate activity indicator.                       | Build    | P1       |
+| `Status`             | State icon, label, and optional detail.                 | Build    | P1       |
+| `Alert`              | Inline information, success, warning, or error message. | Build    | P1       |
+| `Callout`            | Framed explanatory content.                             | Build    | P2       |
+| `Toast`              | Timed transient notification stack.                     | Build    | P2       |
+| `NotificationCenter` | Persistent notification list and unread state.          | Research | P3       |
+| `Skeleton`           | Placeholder rows while content loads.                   | Research | P2       |
+| `EmptyState`         | Empty result message with optional action.              | Build    | P1       |
+| `ErrorState`         | Error details, cause, and retry action.                 | Build    | P1       |
+| `LoadingOverlay`     | Block interaction while work runs.                      | Build    | P2       |
+| `TaskProgress`       | Multi-step task status with current activity.           | Build    | P1       |
+| `StepIndicator`      | Completed, active, and pending steps.                   | Build    | P1       |
+| `ConnectionStatus`   | Online, reconnecting, offline, latency.                 | Build    | P2       |
+| `HealthIndicator`    | Service health summary with reasons.                    | Build    | P2       |
+
+### 5. Collections and structured data
+
+This family should share selection, focus, sorting, filtering, scrolling, and
+virtualization primitives.
+
+| Component      | Purpose                                                    | Decision    | Priority |
+| -------------- | ---------------------------------------------------------- | ----------- | -------- |
+| `List`         | Typed items, selection, empty state, and render callbacks. | Adapt       | P1       |
+| `VirtualList`  | Render large lists using visible rows only.                | Build       | P2       |
+| `GroupedList`  | Sections with sticky or repeated headings.                 | Build       | P2       |
+| `Table`        | Typed columns, alignment, truncation, and selection.       | Build       | P1       |
+| `DataTable`    | Sort, filter, paginate, resize, and column visibility.     | Build       | P2       |
+| `VirtualTable` | Large row sets with bounded rendering.                     | Research    | P2       |
+| `Tree`         | Expandable hierarchical navigation.                        | Build       | P2       |
+| `TreeTable`    | Hierarchical rows plus columns.                            | Research    | P3       |
+| `Timeline`     | Ordered events with time and status.                       | Build       | P2       |
+| `ActivityFeed` | Live events with grouping and retention.                   | Build       | P2       |
+| `DiffView`     | Side-by-side or unified text differences.                  | Build       | P2       |
+| `FileTree`     | File-specific tree with icons and git state.               | Build       | P2       |
+| `ProcessList`  | PID, CPU, memory, status, and actions.                     | Block first | P3       |
+| `LogViewer`    | Streaming logs with retention and pause.                   | Build       | P1       |
+| `LogExplorer`  | Search, filters, levels, timestamps, and follow mode.      | Build       | P2       |
+| `JsonViewer`   | Expandable structured JSON values.                         | Build       | P2       |
+| `Inspector`    | Generic nested object inspection.                          | Build       | P2       |
+| `HexViewer`    | Byte offsets, hex, and text representation.                | Defer       | P3       |
+| `AnsiViewer`   | Safely display ANSI-formatted output.                      | Research    | P3       |
+
+### 6. Charts and numeric visualization
+
+Charts are useful but expensive. Build shared axes, domains, legends, and
+sampling first. Avoid duplicating `blessed-contrib` without a measurable API,
+quality, or maintenance advantage.
+
+| Component          | Purpose                                             | Decision     | Priority |
+| ------------------ | --------------------------------------------------- | ------------ | -------- |
+| `Sparkline`        | Compact single-series trend.                        | Build        | P0       |
+| `MultiSparkline`   | Aligned compact series with labels.                 | Build        | P1       |
+| `MetricBars`       | Labeled horizontal metric bars.                     | Build        | P0       |
+| `Gauge`            | One bounded value with label and thresholds.        | Build        | P1       |
+| `StackedGauge`     | Composition of portions in one track.               | Build        | P2       |
+| `BulletChart`      | Actual value against target and qualitative ranges. | Build        | P2       |
+| `BarChart`         | Categorical value comparison.                       | Research     | P2       |
+| `StackedBarChart`  | Category composition over multiple series.          | Research     | P3       |
+| `LineChart`        | One or more series over an axis.                    | Research     | P2       |
+| `AreaChart`        | Filled time-series trend.                           | Defer        | P3       |
+| `Histogram`        | Numeric distribution by bins.                       | Build        | P2       |
+| `Heatmap`          | Dense matrix of intensity values.                   | Research     | P3       |
+| `CalendarHeatmap`  | Activity intensity by date.                         | Build        | P3       |
+| `ScatterPlot`      | Relationship between two numeric values.            | Defer        | P3       |
+| `BoxPlot`          | Statistical distribution summary.                   | Defer        | P3       |
+| `Donut`            | Part-to-whole radial display.                       | Defer        | P3       |
+| `PieChart`         | Part-to-whole radial display.                       | Do not build | —        |
+| `CandlestickChart` | Open/high/low/close financial series.               | Defer        | P3       |
+| `WaterfallChart`   | Sequential positive and negative contributions.     | Defer        | P3       |
+| `Legend`           | Shared series labels and glyphs.                    | Build        | P1       |
+| `Axis`             | Shared numeric/category axis renderer.              | Build        | P2       |
+| `Thresholds`       | Shared warning and critical ranges.                 | Build        | P1       |
+
+`PieChart` is a non-goal: terminal cell aspect ratios and low resolution make
+angle and area comparison poor. Prefer `MetricBars`, `ProgressStack`, or
+`Donut` only when visual familiarity outweighs precision.
+
+### 7. Navigation
+
+Navigation components need a shared focus model and documented keyboard maps.
+
+| Component        | Purpose                                        | Decision | Priority |
+| ---------------- | ---------------------------------------------- | -------- | -------- |
+| `Tabs`           | Switch between labeled views.                  | Build    | P1       |
+| `TabList`        | Compound tab trigger collection.               | Build    | P1       |
+| `Menu`           | Vertical action navigation.                    | Build    | P1       |
+| `MenuBar`        | Top-level horizontal menus.                    | Build    | P2       |
+| `ContextMenu`    | Mouse or keyboard anchored action menu.        | Research | P3       |
+| `NavigationList` | Route or view navigation with active state.    | Build    | P2       |
+| `Pagination`     | Move through bounded result pages.             | Build    | P2       |
+| `Pager`          | Previous/next navigation for views or records. | Build    | P2       |
+| `Carousel`       | Manual or timed view rotation.                 | Adapt    | P3       |
+| `CommandPalette` | Searchable command execution.                  | Build    | P2       |
+| `QuickSwitcher`  | Search and switch resources or views.          | Build    | P2       |
+| `HelpOverlay`    | Searchable keyboard shortcut reference.        | Build    | P1       |
+
+### 8. Inputs and forms
+
+Blessed already has form elements. Value comes from typed values, validation,
+consistent state, composition, and cleanup.
+
+| Component         | Purpose                                                | Decision | Priority |
+| ----------------- | ------------------------------------------------------ | -------- | -------- |
+| `Button`          | Typed action with tone, disabled, and loading states.  | Adapt    | P1       |
+| `IconButton`      | Compact action with required text description.         | Build    | P2       |
+| `TextField`       | Single-line text with label, hint, and error.          | Adapt    | P1       |
+| `PasswordField`   | Masked input with reveal behavior.                     | Build    | P2       |
+| `TextArea`        | Multiline text with validation and counters.           | Adapt    | P2       |
+| `NumberField`     | Numeric input with parsing, bounds, and step.          | Build    | P2       |
+| `SearchField`     | Query input with clear and submit actions.             | Build    | P1       |
+| `Checkbox`        | Boolean value with indeterminate state.                | Adapt    | P1       |
+| `RadioGroup`      | One value from visible choices.                        | Adapt    | P1       |
+| `Switch`          | Immediate boolean setting.                             | Build    | P2       |
+| `Select`          | One value from a popup or inline list.                 | Build    | P1       |
+| `MultiSelect`     | Multiple values with filtering.                        | Build    | P2       |
+| `Combobox`        | Searchable input plus suggestions.                     | Build    | P2       |
+| `Autocomplete`    | Suggest completions while typing.                      | Build    | P2       |
+| `DateInput`       | Parse and validate a date string.                      | Research | P3       |
+| `TimeInput`       | Parse and validate time.                               | Research | P3       |
+| `KeybindingInput` | Capture and display shortcut combinations.             | Build    | P3       |
+| `FilePicker`      | Navigate and select files or directories.              | Adapt    | P2       |
+| `FormField`       | Label, control, hint, required, and error composition. | Build    | P1       |
+| `Form`            | Submission, validation, reset, and field registry.     | Adapt    | P1       |
+
+### 9. Overlays and transient UI
+
+Terminal overlays require layering, focus capture, focus restoration, and
+global key cleanup.
+
+| Component       | Purpose                                         | Decision | Priority |
+| --------------- | ----------------------------------------------- | -------- | -------- |
+| `Overlay`       | Shared screen layer and dismissal behavior.     | Build    | P1       |
+| `Dialog`        | Modal content with focus capture and restore.   | Build    | P1       |
+| `ConfirmDialog` | Confirm or cancel a consequential action.       | Build    | P1       |
+| `PromptDialog`  | Request one value in a modal flow.              | Adapt    | P2       |
+| `Drawer`        | Edge-attached temporary panel.                  | Build    | P2       |
+| `Popover`       | Anchored temporary content.                     | Research | P3       |
+| `Tooltip`       | Delayed contextual help.                        | Adapt    | P3       |
+| `ToastViewport` | Position and manage toast notifications.        | Build    | P2       |
+| `Spotlight`     | Full-screen searchable action/resource overlay. | Build    | P2       |
+
+### 10. Developer-tool components
+
+Strong opportunity: terminal applications are frequently developer tools.
+These components can differentiate the package from generic dashboard
+libraries.
+
+| Component          | Purpose                                             | Decision    | Priority |
+| ------------------ | --------------------------------------------------- | ----------- | -------- |
+| `CodeViewer`       | Syntax-highlighted, scrollable source.              | Build       | P2       |
+| `DiffViewer`       | Unified or split patch rendering.                   | Build       | P2       |
+| `StackTrace`       | Parse and navigate stack frames.                    | Build       | P2       |
+| `TestResults`      | Suites, tests, failures, duration, and retry state. | Block first | P2       |
+| `BuildStatus`      | Build phases, duration, logs, and outcome.          | Block first | P2       |
+| `GitStatus`        | Branch, staged, modified, untracked, conflicts.     | Block first | P2       |
+| `CommitList`       | Commit summary, author, date, and refs.             | Block first | P3       |
+| `DependencyTree`   | Package dependency hierarchy and problems.          | Block first | P3       |
+| `RequestInspector` | HTTP request/response headers and body.             | Block first | P3       |
+| `QueryResults`     | Database result table and execution metadata.       | Block first | P3       |
+| `EnvironmentTable` | Masked environment variable inspection.             | Build       | P3       |
+| `ShortcutRecorder` | Inspect keypress names emitted by terminal.         | Build       | P3       |
+| `EventLog`         | Structured event stream for debugging TUI behavior. | Build       | P2       |
+| `PerformancePanel` | FPS, render time, memory, and event-loop delay.     | Research    | P3       |
+
+### 11. Terminal and process components
+
+High power, high lifecycle and security cost.
+
+| Component       | Purpose                                         | Decision    | Priority |
+| --------------- | ----------------------------------------------- | ----------- | -------- |
+| `TerminalPane`  | Embed a subprocess terminal.                    | Adapt       | P3       |
+| `ProcessRunner` | Run command, stream output, expose exit state.  | Research    | P3       |
+| `ProcessTable`  | Monitor multiple child processes.               | Block first | P3       |
+| `CommandOutput` | Read-only stdout/stderr viewer with status.     | Build       | P2       |
+| `TaskRunner`    | Execute named tasks with logs and cancellation. | Block first | P3       |
+| `REPL`          | Prompt, history, evaluation, and results.       | Research    | P3       |
+| `ShellHistory`  | Search and select previous commands.            | Research    | P3       |
+
+Process APIs must never execute shell strings implicitly. Commands, arguments,
+environment, cancellation, and signal behavior require explicit contracts.
+
+### 12. Content and media
+
+Useful, but dependency-heavy features should remain optional entry points.
+
+| Component        | Purpose                                                | Decision | Priority |
+| ---------------- | ------------------------------------------------------ | -------- | -------- |
+| `MarkdownViewer` | Render Markdown into terminal-safe content.            | Research | P3       |
+| `RichText`       | Styled spans, links, and selectable text.              | Research | P3       |
+| `Link`           | Visible URL plus optional terminal hyperlink sequence. | Build    | P2       |
+| `Image`          | Capability-aware terminal image or text fallback.      | Adapt    | P3       |
+| `AsciiArt`       | Render static art with alignment and cropping.         | Build    | P3       |
+| `BigText`        | Large glyph text through Blessed.                      | Adapt    | P3       |
+| `QRCode`         | Render QR codes using terminal cells.                  | Build    | P3       |
+| `ColorSwatch`    | Show terminal color and numeric representation.        | Build    | P3       |
+| `Palette`        | Display semantic theme colors and contrast pairs.      | Build    | P3       |
+
+### 13. Date, time, and scheduling
+
+| Component         | Purpose                                   | Decision | Priority |
+| ----------------- | ----------------------------------------- | -------- | -------- |
+| `Clock`           | Live local or zoned time.                 | Build    | P2       |
+| `Timer`           | Elapsed duration with pause and reset.    | Build    | P2       |
+| `Countdown`       | Remaining duration with completion event. | Build    | P2       |
+| `Calendar`        | Navigate and select dates.                | Research | P3       |
+| `DateRangePicker` | Select a bounded date interval.           | Defer    | P3       |
+| `Schedule`        | Ordered upcoming events.                  | Build    | P3       |
+| `Gantt`           | Time-based task spans.                    | Defer    | P3       |
+
+### 14. Application blocks
+
+Build as examples first. Promote lower-level pieces only after reuse appears.
+
+| Block                 | Components it validates                          |
+| --------------------- | ------------------------------------------------ |
+| `SystemMonitor`       | stats, sparklines, process table, gauges         |
+| `ServiceDashboard`    | health, latency, logs, alerts, timelines         |
+| `GitClient`           | file tree, status, commit list, diff viewer      |
+| `TestRunner`          | tree, progress, failures, logs, command output   |
+| `TaskDashboard`       | task progress, process output, notifications     |
+| `DatabaseExplorer`    | tree, query editor, results table, inspector     |
+| `HTTPInspector`       | request list, headers, body, timing bars         |
+| `PackageExplorer`     | search, dependency tree, metadata, versions      |
+| `FileManager`         | tree, list, preview, actions, dialogs            |
+| `LogDashboard`        | filters, virtual log viewer, histogram, timeline |
+| `KubernetesDashboard` | resource table, status, events, logs             |
+| `QueueMonitor`        | rates, depth, workers, failures, retries         |
+| `CI Dashboard`        | pipelines, jobs, duration, logs, artifacts       |
+| `CommandCenter`       | command palette, shortcuts, task runner          |
+
+## Recommended scope
+
+### Release 0.1 — Display foundation
+
+- `visibleWidth`
+- `truncate`
+- `escapeTags`
+- `scaleValue`
+- number and percent formatters
+- `Text`
+- `ProgressBar`
+- `Sparkline`
+- `MetricBars`
+- `Stat`
 
-Objetivo: construir pantallas completas sin strings monolíticos.
+This release proves rendering, width calculations, themes, packaging, and
+updates without requiring complex focus behavior.
 
-Componentes:
+### Release 0.2 — Composition and states
 
-- `Stat`
 - `Card`
+- `Stack`
+- `Divider`
 - `KeyValue`
 - `Badge`
-- `Divider`
-- `Stack`
-
-Validación:
-
-- dashboard de ejemplo combina `Stat`, `Sparkline` y `MetricBars`.
-- resize recalcula contenido sin fugas de listeners.
-- navegación de foco sigue siendo responsabilidad clara.
-
-### M6 — Feedback y datos vivos
-
-Componentes:
-
+- `Trend`
 - `Spinner`
-- `Status`
 - `Alert`
+- `EmptyState`
+- `TaskProgress`
+
+### Release 0.3 — Collections and live output
+
+- shared selection primitive
+- `List`
+- `Table`
 - `LogViewer`
-- `Timer`
+- `Timeline`
+- `JsonViewer`
+- virtualization experiment
 
-Capacidades:
+### Release 0.4 — Navigation and overlays
+
+- shared keymap and focus-scope primitives
+- `Tabs`
+- `Menu`
+- `HelpOverlay`
+- `Overlay`
+- `Dialog`
+- `ConfirmDialog`
+- `CommandPalette`
 
-- actualizaciones frecuentes con render mínimo.
-- pausa, reanudación y limpieza de timers/listeners.
-- límite configurable de historial.
+### Release 0.5 — Forms
 
-### M7 — Datos avanzados
+- `Button`
+- `FormField`
+- `TextField`
+- `SearchField`
+- `Checkbox`
+- `RadioGroup`
+- `Select`
+- `Form`
 
-Componentes:
+### Release 0.6 — Advanced data display
 
-- `BarChart`
-- `LineChart`
-- `Histogram`
-- `Heatmap`
-- `Table`
+- `DataTable`
 - `Tree`
+- `DiffView`
+- `LogExplorer`
+- `CodeViewer`
+- `StackTrace`
+
+### Release 0.7 — Layout system
+
+- `Viewport`
+- `ScrollArea`
+- `Grid`
+- `SidebarLayout`
+- `Collapsible`
+- `Accordion`
+- `AppShell`
+
+### Release 0.8 — Visualization primitives
+
+- `Legend`
+- `Axis`
+- `Thresholds`
+- `Gauge`
+- `ProgressStack`
+- `Histogram`
+- chart prototype evaluation
 
-Regla: construir solo cuando primitives actuales no puedan componer caso.
-Evitar duplicar `blessed-contrib` sin ventaja clara de API, tamaño, pruebas o
-accesibilidad.
+### Release 0.9 — Hardening
 
-### M8 — Interacción
+- Windows, macOS, and Linux compatibility;
+- terminal capability matrix;
+- mouse and keyboard integration tests;
+- high-frequency update benchmarks;
+- memory and listener leak tests;
+- public API review;
+- migration tooling;
+- documentation site and component gallery.
 
-Componentes:
+### Release 1.0 — Stable core
 
-- `Tabs`
-- `Menu`
-- `CommandPalette`
-- `Select`
-- `TextField`
-- `Form`
+- stable semantic versioning policy;
+- stable component lifecycle contract;
+- stable theme token contract;
+- documented keyboard maps;
+- runnable examples for every component;
+- performance budgets;
+- accessibility and fallback guidance;
+- upgrade and deprecation policy.
 
-Requisitos:
-
-- teclado configurable.
-- foco visible.
-- cleanup completo de eventos.
-- acciones públicas testeables sin inspeccionar internals.
-
-### M9 — Release 1.0
-
-- API estable y política SemVer.
-- documentación por componente.
-- ejemplos copiables.
-- tabla de compatibilidad Node, terminal y `blessed`.
-- changelog y guía de migración.
-- pruebas en Linux, macOS y Windows.
-- presupuesto de tamaño y rendimiento.
-
-## Backlog de componentes
-
-| Prioridad | Componente                                  | Estado objetivo   |
-| --------- | ------------------------------------------- | ----------------- |
-| P0        | `ProgressBar`                               | tracer bullet     |
-| P0        | `Sparkline`                                 | ejemplo downloads |
-| P0        | `MetricBars`                                | ejemplo score     |
-| P0        | `Stat`                                      | valor destacado   |
-| P1        | `Card`, `KeyValue`, `Badge`, `Divider`      | composición       |
-| P1        | `Spinner`, `Status`, `Alert`                | feedback          |
-| P1        | `Table`, `LogViewer`                        | datos             |
-| P2        | `Stack`, `Tabs`, `Menu`                     | layout/navegación |
-| P2        | `BarChart`, `LineChart`, `Histogram`        | charts            |
-| P3        | `CommandPalette`, `Form`, `Tree`, `Heatmap` | avanzado          |
-
-## Contratos comunes
-
-Todos los componentes deben definir:
-
-- datos aceptados.
-- salida para datos vacíos.
-- comportamiento ante valores inválidos.
-- política de truncado y resize.
-- soporte color/Unicode.
-- métodos de actualización.
-- eventos emitidos, si existen.
-- ownership de listeners, timers y destrucción.
-
-Interfaz común candidata:
+## TDD strategy
 
-```ts
-interface ComponentHandle<T> {
-  element: blessed.Widgets.BoxElement
-  setData(data: T): void
-  destroy(): void
-}
+Develop as vertical tracer bullets. Never write the complete test suite before
+implementation.
+
+```text
+RED: one public behavior fails
+  ↓
+GREEN: minimum implementation passes
+  ↓
+REFACTOR: improve design while green
+  ↓
+next behavior
 ```
 
-Adoptar solo después del tracer bullet. Si retornar directamente elemento
-`blessed` resulta más natural, preferir API menor.
-
-## Definition of Done por componente
-
-- API pública documentada.
-- cada comportamiento agregado mediante ciclo RED→GREEN.
-- tests ejercen renderer/widget público.
-- estados normal, vacío, inválido y estrecho cubiertos.
-- Unicode y ASCII cubiertos.
-- ejemplo ejecutable.
-- cero listeners o timers después de `destroy`.
-- exports y tipos verificados desde paquete compilado.
-- changelog actualizado.
-
-## Decisiones antes de implementar M0
-
-1. Runtime mínimo de Node.
-2. TypeScript obligatorio o JS con tipos generados.
-3. Runner: Vitest, Node test runner u otro.
-4. Soporte ESM, CommonJS o ambos.
-5. `blessed` exacto soportado: paquete original o fork mantenido.
-6. Primera API de widget:
-   - retornar elemento `blessed` extendido; o
-   - retornar `ComponentHandle`.
-7. Política de resize:
-   - automática mediante eventos; o
-   - explícita mediante `setSize`/`render`.
-
-Recomendación inicial: resolver estas decisiones durante M0; después ejecutar
-M1 como tracer bullet antes de ampliar catálogo.
+Test priority:
+
+1. visible output through a public renderer;
+2. bounds, scaling, truncation, and available width;
+3. state updates through public methods;
+4. real Blessed element integration;
+5. keyboard and focus behavior;
+6. ASCII, no-color, empty, invalid, and narrow states;
+7. listener, timer, and process cleanup;
+8. package-level ESM and CommonJS imports.
+
+Avoid:
+
+- testing private helpers directly when public behavior can prove them;
+- mocking internal collaborators;
+- asserting internal event call order;
+- large snapshots as the primary contract;
+- relying only on one terminal size;
+- tests that pass despite broken visible output.
+
+## First tracer bullet: ProgressBar
+
+RED → GREEN cycles:
+
+1. Render 50% at a fixed width.
+2. Clamp values below `min` and above `max`.
+3. Render label and formatted value.
+4. Respect narrow inner width.
+5. Update content through `setData`.
+6. Use ASCII characters when Unicode is disabled.
+7. Apply semantic theme tokens.
+8. Destroy adapter-owned listeners.
+9. Import built package from ESM and CommonJS.
+
+Exit criteria:
+
+- public renderer API is validated;
+- Blessed adapter contract is validated;
+- component handle decision is recorded;
+- pattern can be reused by `MetricBars` and `Gauge`.
+
+## Component admission criteria
+
+A new component enters the package only when:
+
+1. at least two realistic use cases exist;
+2. it provides more than a renamed Blessed constructor;
+3. its responsibilities cannot be composed clearly from existing exports;
+4. keyboard and focus behavior can be specified;
+5. narrow, empty, invalid, ASCII, and no-color states are understood;
+6. lifecycle ownership is explicit;
+7. a public-behavior test plan exists;
+8. maintenance cost is proportionate to expected use.
+
+Otherwise, keep it as a pattern, example, block, or external integration.
+
+## Common contracts
+
+Every component must document:
+
+- accepted data;
+- defaults;
+- empty output;
+- invalid input behavior;
+- truncation and wrapping;
+- resize behavior;
+- Unicode and color fallbacks;
+- controlled and uncontrolled state, if applicable;
+- keyboard map;
+- focus entry, movement, and restoration;
+- emitted events;
+- listener, timer, stream, and process ownership;
+- `setData`, `setOptions`, or immutable recreation policy;
+- destruction behavior;
+- performance limits.
+
+## Definition of Done
+
+- Public API and exported types documented.
+- Each behavior added through a RED → GREEN cycle.
+- Tests use public renderers or component handles.
+- Normal, empty, invalid, and narrow states covered.
+- Unicode, ASCII, color, and no-color behavior covered.
+- Keyboard map covered for interactive components.
+- Focus restoration covered for overlays.
+- No listeners, timers, streams, or processes survive `destroy()`.
+- Runnable example included.
+- ESM and CommonJS package imports verified.
+- Packed npm contents inspected.
+- Changelog entry generated by release workflow.
+
+## Decisions still requiring prototypes
+
+1. Return an extended Blessed element or `ComponentHandle`.
+2. Represent pure output as strings, rows, cells, or a richer render model.
+3. Automatic resize listeners or explicit resize/update calls.
+4. One package or optional subpath exports for charts and media.
+5. Mouse behavior enabled by default or opt-in.
+6. Theme inheritance through explicit options or screen-attached context.
+7. Virtualization API shared by lists, tables, trees, and logs.
+8. Supported Blessed implementation: original package, maintained fork, or
+   adapter compatibility layer.
+
+Resolve decisions through small prototypes and public behavior tests, not
+abstract API design alone.