# Refinement — Layout do 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: Refinamento técnico (grooming)
- Risco: **medium** (`00-risk-classification.md`, fator `external_dependency`)
- Etapa anterior: `04-tasks.md` (aprovado)
- Estado: draft — **aguardando checkpoint humano**

## Resumo
Overhaul de apresentação e entrada do TUI (`src/tui/`) para a estética OpenCode, sem tocar o domínio. Entrega em 6 fases / 16 tarefas, com dois módulos novos aditivos (`theme.rs`, `palette.rs`) e migração tela-a-tela de `ui.rs`. O critério de pronto de cada fase é o mesmo gate do projeto: `cargo test`/`fmt`/`clippy` verdes e telas renderizando sem panic em 40/80/120.

## Solução proposta
- **Camada de tema** (`theme.rs`): tokens semânticos + `ColorDepth::detect` + helpers de layout (seleção full-width, section header, centered_rect, overlay_dim, figlet). `ui.rs` desenha só a partir do tema.
- **Camada de overlays** (`palette.rs` + `Overlay` em `app.rs`): command palette e telemetria como modais; comando resolve para `Action` existente (paridade RF-10, sem mudar domínio).
- **Ordem de ataque**: tema → borderless/seleção → home → palette → telemetria sob demanda → seletor agrupado/polimento.
- **Estratégia de menor risco**: assinaturas de render preservadas; cada fase é um PR verde; testes de render acompanham cada mudança.

## Pontos de observação
- **PO-1 (R3 teclas)**: validar `Ctrl+K` e `/` em terminais reais; garantir que `/` não dispare palette em text_mode. Cobrir com testes de `map_key`.
- **PO-2 (R1 terminal)**: `figlet_banner` precisa de versão curta < 60 colunas; conferir glifos (`▸`, `●`, `✓`) em fallback 16-cores.
- **PO-3 (RN-03)**: ao enxugar board/checkpoint/running, NÃO remover info crítica de decisão (artefato, critério, provider/rota) — só telemetria de consumo.
- **PO-4 (R2 regressão)**: `ui.rs` tem 1484 linhas; migrar incremental e rodar testes de render a cada tela.
- **PO-5 (home/landing)**: decisão de renderizar home sem novo `Screen`; se a revisão de execução achar que polui `OrchestrationList`, promover a `Screen::Home` (alternativa já registrada na Tech Spec).
- **PO-6 (paridade)**: checklist explícito de que toda ação por tecla também existe no palette antes de fechar a Fase 4.

## Checklist
- [ ] Fase 1 — `theme.rs` (tokens + detect + helpers) e casco migrado
- [ ] Fase 2 — borderless + barra de seleção full-width
- [ ] Fase 3 — home/launcher com figlet
- [ ] Fase 4 — command palette (módulo, estado, bindings, render) com paridade verificada
- [ ] Fase 5 — telemetria sob demanda + default minimalista
- [ ] Fase 6 — seletor agrupado, observabilidade, testes/guardrail, degradação, `visual-review`
- [ ] `cargo test` + `cargo fmt --check` + `cargo clippy` verdes
- [ ] ADR registrado (`sdd adr`) para a decisão de camada de tema + overlays

## Subtasks
Resumo do backlog de `04-tasks.md` com estimativa relativa (P=pequeno, M=médio):

| ID | Tarefa | Fase | Tam. | Depende |
|----|--------|------|------|---------|
| T-01 | `theme.rs` tokens + detect | 1 | M | — |
| T-02 | helpers de estilo | 1 | M | T-01 |
| T-03 | migrar casco header/footer | 1 | P | T-02 |
| T-04 | remover `Borders::ALL` | 2 | M | T-03 |
| T-05 | barra de seleção full-width | 2 | P | T-02 |
| T-06 | `render_home` figlet | 3 | M | T-02,T-04 |
| T-07 | `palette.rs` Command/filter | 4 | M | — |
| T-08 | `Overlay`+`CommandPalette` em app | 4 | M | T-07 |
| T-09 | bindings/Action do palette | 4 | P | T-08 |
| T-10 | `render_command_palette` | 4 | M | T-08,T-02 |
| T-11 | `render_telemetry`+Action | 5 | M | T-08 |
| T-12 | enxugar default denso | 5 | P | T-11 |
| T-13 | seletor agrupado | 6 | M | T-04,T-05 |
| T-14 | observabilidade overlays | 6 | P | T-08,T-11 |
| T-15 | testes render + guardrail | 6 | M | T-06,T-10,T-11 |
| T-16 | degradação + visual-review | 6 | P | T-13,T-15 |

Ramos paralelizáveis (Agent Team na Execução): **tema** (T-01→T-05) ⟂ **palette** (T-07→T-10), convergindo em T-15.

## Definition of Done
- Todas as 16 tarefas concluídas e os critérios Gherkin de `04-tasks.md` verdes.
- `cargo test` (incluindo render em 40/80/120 e overlays), `cargo fmt --check`, `cargo clippy` sem erros.
- Zero `Borders::ALL` como moldura padrão de conteúdo (guardrail M-1).
- Paridade palette↔teclas confirmada (PO-6); telemetria fora do default mas acessível em ≤1 atalho.
- Fluxo Ideia→Memória, checkpoints e persistência inalterados (sem regressão de domínio).
- ADR criado/atualizado; `visual-review` aprovando home e seletor contra as referências do OpenCode.

## Flags e configurações
- **Sem feature flag de runtime** por padrão (overhaul é a nova UI). Caso a revisão de execução queira rollout gradual, registrar variável de ambiente opcional `SDD_TUI_THEME=legacy|opencode` como ponto de reversão — decisão a confirmar na Execução, não bloqueante.
- Sem mudança em `sdd.config.yaml`, schemas ou persistência.
- Capacidade de cor derivada de `COLORTERM`/`TERM` em runtime (sem config nova).

Próxima etapa: **Execução (Etapa 6)**, uma tarefa por vez (ou Agent Team nos ramos paralelos), rodando os testes antes de concluir cada uma. **Checkpoint humano obrigatório após este Refinement.**
