# ADR 0001 — Camada de tema e overlays na TUI (estilo OpenCode)

## Rastreabilidade
- Orquestração: Precisamos que o layout em si do TUI tenha uma experiência similar à do OpenCode
- Slug: `precisamos-que-o-layout-em-si-do-tui-tenha-uma-experiencia-similar-a-do-opencode`
- Documento: ADR (Architecture Decision Record)
- Artefatos de origem: `03-techspec.md`, `05-refinement.md`
- Código: `src/tui/theme.rs`, `src/tui/palette.rs`, `src/tui/app.rs`, `src/tui/event.rs`, `src/tui/ui.rs`, `src/tui/mod.rs`

## Status
Aceito (implementação parcial em andamento — fundação + palette/telemetria + casco/listas concluídos e testados).

## Contexto
A TUI do `sdd` (ratatui 0.29 + crossterm 0.28) seguia uma estética de painéis com `Borders::ALL` em todas as telas, cores espalhadas (ciano/azul/amarelo/verde) e densidade alta por padrão. O objetivo de produto é uma experiência minimalista no estilo OpenCode, sem alterar o motor de orquestração (etapas, checkpoints, providers, persistência). A renderização já era organizada em funções puras (`ui.rs`) desenhando a partir de `App`, com input mapeado por `map_key -> Action` e reduzido por `App::update`.

## Problema
Como introduzir uma estética/experiência nova (acento único, borderless, listas agrupadas, command palette, telemetria sob demanda) preservando 100% do domínio e a testabilidade, num arquivo de renderização grande, sem regressões e com degradação graciosa entre terminais?

## Decisão
Adotar **duas camadas aditivas** sobre a arquitetura existente:
1. **Camada de tema** (`theme.rs`): tokens semânticos (`Theme`), detecção de capacidade do terminal (`ColorDepth::detect` via `COLORTERM`/`TERM`) com fallback 16-cores, e helpers de estilo/layout (`selection_style`, `section_header`, `label_value`, `footer_line`, `centered_rect`, `overlay_dim`, `figlet_banner`). `ui.rs` passa a desenhar a partir do tema, sem cores literais.
2. **Camada de overlays** (`palette.rs` + `Overlay` em `app.rs`): command palette e telemetria como modais flutuantes desenhados por cima da tela, com fundo escurecido. O palette usa um enum próprio `CommandId` (desacoplado de `Action`); cada comando resolve para uma `Action` já existente, re-despachada pela tela ativa.

Princípio inegociável: overlays/tema são apresentação/entrada; **não** tocam `stage.rs::can_navigate` nem auto-aprovam checkpoints.

## Alternativas consideradas
- **Só tokens compartilhados sobre o layout atual** (sem reestruturar telas nem palette): menor esforço, mas não entrega a experiência OpenCode pedida (sem palette, sem minimalismo real). Rejeitada pelo escopo aprovado.
- **Reescrever a TUI do zero / trocar de biblioteca**: alto risco e custo, joga fora testes e domínio estáveis. Rejeitada.
- **Acoplar o palette diretamente ao enum `Action`**: simplificaria o mapeamento, mas acoplaria o módulo novo ao input e impediria testes isolados. Rejeitada em favor do `CommandId` desacoplado.
- **Feature flag `SDD_TUI_THEME=legacy|opencode`**: rollout gradual, mas mantém código morto e dobra a superfície de teste. Rejeitada (decisão de produto: substituição direta).

## Consequências
- Estilos centralizados: telas não definem mais cores literais; manutenção e consistência melhoram.
- Paridade palette↔teclas garantida por construção (comando → `Action`), sem duplicar domínio.
- `ui.rs` cresce com as funções de overlay, mas as assinaturas de render permanecem estáveis.
- Telemetria densa sai do default; descoberta via hint no board/footer e item no palette.

## Impactos e riscos
- **R1 (terminal)**: fidelidade depende de truecolor/largura/glifos → mitigado por `ColorDepth` + fallback 16-cores + `figlet_banner` com versão curta + testes em 40/80/120.
- **R2 (regressão visual)**: `ui.rs` grande → mitigado por tema aditivo, migração tela-a-tela e testes de render (`renders_overlays_no_panic`).
- **R3 (input)**: novos bindings (`Ctrl+K`, `/`, `t`) → cobertos por testes de `map_key`; `/` e `t` só fora de text_mode.

## Plano de adoção
Sequência incremental por fase (tema → casco → borderless/seleção → home → palette → telemetria → seletor agrupado → polimento). Cada fase compila e mantém `cargo test` verde. Telas restantes (provider setup, viewer, checkpoint, help, summary, error) migram para o tema nas fases finais.

## Plano de reversão
Como não há feature flag, a reversão é por VCS: reverter os commits da camada de tema/overlays restaura a UI anterior. Os módulos novos (`theme.rs`, `palette.rs`) são aditivos e podem ser removidos junto com os pontos de integração em `app.rs`/`event.rs`/`ui.rs`/`mod.rs` sem afetar o domínio.

## Evidências
- `cargo test`: 126 testes verdes (inclui 21 de `theme`, 10 de `palette`, 2 de bindings de palette, 1 de render de overlays em 40/80/120).
- `cargo clippy`: sem warnings nos módulos novos/alterados (`theme`, `palette`, `ui`, `app`, `event`).
- Integração de domínio inalterada (`stage.rs`, `runner.rs`, `persist.rs`).

## Histórico de revisão
- 2026-06-06 — Criado durante a Execução (Etapa 6) da orquestração; status Aceito com implementação parcial.
