GBR: ADR-0022 Interface de Terminal Avançada (TUI) Nativa via Étui

• *Status:* Aceito
• *Data:* 2026-06-09

Contexto

Após a rejeição do ADR-0014 (Ratatui/Rustler) devido ao acoplamento com o compilador Rust e a complexidade na fronteira de NIFs assíncronas, o projeto precisava de uma solução que mantivesse as schedulers da Erlang VM desimpedidas e com recuperação de falhas nativa, sem abrir mão de um design visual rico de console para gerenciar sessões do agente e processos do orquestrador.

Decisão

Adotamos a biblioteca local *Étui* (etui), desenvolvida especificamente para o ecossistema Gleam e Erlang.

1. *TEA puro em Gleam:* A interface opera no padrão The Elm Architecture (Model, Update, View) estruturado sob atores Gleam, mantendo o estado da tela isolado.
2. *Buffer-Diffing nativo:* Étui escreve dados em buffers puramente funcionais e calcula a diferença de renderização (diff) a cada frame, evitando repinturas completas da tela e cintilações (jitter).
3. *Resiliência e Recuperação (Crash-Restore):* O loop principal é envolvido em blocos nativos try...after do Erlang. Qualquer exceção ou crash na interface é capturado, limpando os códigos ANSI e restaurando o terminal do desenvolvedor ao estado original antes de propagar a falha.
4. *Unicode correto:* Étui processa larguras de células (cell width) de forma adequada utilizando segmentação UAX #29 da Erlang para caracteres CJK, emojis e ZWJ, evitando deformidades visuais.

Consequências

• *Positivas:* - Redução drástica na pilha de dependências (eliminando Cargo e bibliotecas nativas de C/Rust). - Robustez nativa provida pela Erlang VM em caso de pane do terminal. - Testabilidade completa da TUI sem console (as funções de geometria e renderização de buffers são puras).
• *Negativas:* - Menor ecossistema de widgets prontos comparado ao Ratatui tradicional, exigindo implementações personalizadas de elementos mais complexos de layout no próprio Étui.