A skill termfy-tui cria e revisa as screens da TUI do seu binário com a
API imperativa do OpenTUI Core. Ela monta o layout em células e trata a
navegação por teclado e por mouse, mantendo o foco no item selecionado. Nas
telas que consultam serviços, também trata o carregamento assíncrono e libera
os recursos ao sair da aba.
No fim, você tem uma screen registrada como aba, com número e ícone, com
estados de carregando, vazio, erro e pronto, testada por teclas, por clique
e por frames nas três faixas de largura. A conferência visual cobre os temas
terminal, night e day.
Quando usar
- Você quer uma aba nova, como a screen
orderscom a lista de pedidos. - Uma screen existente precisa de navegação por teclado, mouse, rolagem ou um campo de formulário.
- A tela precisa de ícones de papel e de uma barra de ações clicável.
- A tela consulta uma API e você precisa tratar carregamento, erro e respostas que chegam fora de ordem.
- Uma screen trava, vaza timers ou deixa o terminal sujo ao sair.
Para entregar a screen junto com o command e a tool do mesmo recurso, use termfy-command-set. A chamada HTTP fica no client da termfy-api: a screen apresenta o resultado.
Como pedir
Para uma aba nova:
Use a skill termfy-tui para criar a screen
orders, que lista os pedidos da loja e mostra o pedido selecionado ao apertar Enter.
Para uma tela que consulta um serviço:
Use a skill termfy-tui para a screen
orderscarregar ao entrar na aba, comrpara recarregar e mensagem própria quando a API falhar.
Para revisar uma tela existente:
Use a skill termfy-tui para revisar a screen
orders: a lista some quando troco de aba e volto.
O que a skill faz
- Confere o Git e lê a spec aberta em
specs/: a screen na Surface, o Behavior com teclas e estados, o Design e os itens#termfy-tui. - Confere a versão instalada de
@opentui/coreno lock antes de usar qualquer API. - Lê
src/tui/index.ts,src/tui/screen.ts,src/tui/components.ts,src/tui/theme.tsesrc/tui/screens/index.ts. Mostra um plano curto com arquivos, comportamentos e verificações. - Escolhe um dos cinco padrões de
references/screen-patterns.mde adapta só o necessário: lista e detalhe, painel de status, formulário por diálogos, visualizador de documento e tela de progresso. - Cria
src/tui/screens/<id>.ts, compõe parawide,mediumecompactcomctx.layout(), declaraicone asactionsda tela e registra a screen emsrc/tui/screens/index.ts. Para abrir direto na aba, acrescenta o id emtui.initialTabdesrc/config/settings.tse em--tabdesrc/cli/commands/tui.ts. - Liga cada comando a uma ação, com tecla, clique e entrada na paleta na
mesma função. Testa a lógica isolada, depois a screen com
createTestRenderere por fim a navegação commountTui, com tecla, clique e diálogos. - Confere
terminal,nightedayem 60×16, 80×24 e 120×32. - Passa a
references/quality-checklist.mdlinha a linha, atualizadocs/tui.md, rodabun run validatee marca[x]nos itens.
Padrões de tela e checklist
references/screen-patterns.md traz cinco composições. Cada uma descreve
quando usar, os componentes, as teclas, a composição em wide, medium e
compact e como testar.
| Padrão | Uso |
|---|---|
| lista e detalhe | coleção com seleção e painel de leitura, com table e keyValueTable |
| painel de status | resumo de saúde, versão ou configuração atual |
| formulário por diálogos | poucos campos, editados com confirm, prompt e choose |
| visualizador de documento | aba de documentação com índice e Markdown |
| tela de progresso | operação longa com spinner e progressBar |
references/quality-checklist.md é a conferência antes de declarar a tela
pronta: foco visível, estados vazio, carregando e erro, layout a partir de
60×16, ação com tecla, clique e paleta, confirmação antes de apagar, toast
no resultado, resumo em ctx.status, contraste nos três temas, glifo só em
icons.ts, segredo fora do frame, watch para arquivo lido e timers
parados em onLeave e onPause.
Exemplo
A screen orders recebe a função de carga pela factory. Assim cada
montagem tem o próprio estado e o teste injeta uma carga local:
import { BoxRenderable, TextRenderable } from "@opentui/core";import { listPanel } from "../components.ts";import type { Screen, ScreenAction, ScreenContext } from "../screen.ts";import { listOrders, type Order } from "../../api/shop.ts";
type Load = () => Promise<{ items: Order[] }>;
export function createOrdersScreen(load: Load = () => listOrders({ limit: 50 })): Screen { let root: BoxRenderable | undefined; let status: TextRenderable | undefined; let list: ReturnType<typeof listPanel> | undefined; let orders: Order[] = []; let generation = 0;
const show = (ctx: ScreenContext, items: Order[]) => { if (!root) return; if (list) { root.remove(list.box); list.box.destroyRecursively(); } orders = items; list = listPanel(ctx.renderer, ctx.theme, { title: "Orders", items: items.map((o) => `${o.id} ${o.status}`), onSelect: (i) => { if (status) status.content = `Order ${orders[i]?.id} selected`; }, }); root.add(list.box, 0); };
const reload = async (ctx: ScreenContext) => { const current = ++generation; if (status) status.content = "Loading orders..."; try { const page = await load(); if (current !== generation) return; show(ctx, page.items); if (status) status.content = page.items.length ? "Enter selects an order" : "No orders"; } catch { if (current === generation && status) status.content = "Unable to load orders. Press r to retry."; } };
const actions: ScreenAction[] = [ { keys: ["up", "k"], label: "↑/k", description: "up", run: () => list?.move(-1) }, { keys: ["down", "j"], label: "↓/j", description: "down", run: () => list?.move(1) }, { keys: ["return", "enter"], label: "Enter", description: "select", icon: "select", run: () => { const index = list?.selected() ?? -1; if (index >= 0) list?.select(index); }, }, { keys: ["r"], description: "reload", icon: "refresh", run: (ctx) => { void reload(ctx); } }, ];
return { id: "orders", title: "Orders", icon: "list", description: "Shop orders", actions, mount: (ctx) => { root = new BoxRenderable(ctx.renderer, { flexDirection: "column", flexGrow: 1 }); status = new TextRenderable(ctx.renderer, { content: "", height: 1, flexShrink: 0, fg: ctx.theme.textDim }); root.add(status); ctx.renderer.once("destroy", () => { generation++; }); return root; }, onEnter: (ctx) => { void reload(ctx); }, onLeave: () => { generation++; }, };}O registro entra em src/tui/screens/index.ts como
[overviewScreen, createOrdersScreen(), aboutScreen]. Com orders em
tui.initialTab e em --tab, a aba abre direto:
mycli tui --tab ordersmycli config set tui.initialTab ordersTrecho do frame em 80×24, depois da carga e de uma tecla j:
╭ Orders ──────────────────────────────────────────╮│ o1 open ││ > o7 paid │╰──────────────────────────────────────────────────╯Enter selects an orderO teste espera a carga controlada terminar, sem pausa fixa:
const setup = await createTestRenderer({ width: 80, height: 24 });(screens as Screen[]).push(createOrdersScreen(async () => ({ items: [{ id: "o1", status: "open" }, { id: "o7", status: "paid" }],})));const closed = mountTui(setup.renderer, { initialTab: "orders" }, themes.night);try { await setup.waitForFrame((frame) => frame.includes("o7 paid")); setup.mockInput.pressKey("j"); await setup.renderOnce(); expect(setup.captureCharFrame()).toContain("> o7 paid"); setup.mockInput.pressKey("q"); await closed;} finally { setup.renderer.destroy(); }Regras que a skill segue
- OpenTUI imperativo. A aba usa
@opentui/coredireto, sem React ou Solid, porque o host já entrega renderer e tema prontos. - Uma screen por arquivo, com factory. Estado no escopo do módulo vaza seleção entre duas montagens ou dois testes.
- Componentes compartilhados.
panel,table,listPanel,stateView,spinner,progressBar,link,keyValueTable,heading,dimespacermantêm o visual igual entre abas.spacer(renderer, height)não recebe tema. - Ação única para tecla, clique e paleta. Cada comando é uma
ScreenActioncomkeys,description,iconerun. O botão, a linha de tabela ou de lista e a entrada da paleta chamam a mesma função. - Layout por faixa. A tela lê
ctx.layout()e compõe parawide,mediumecompact. O shell remonta a tela quando a faixa muda. - Diálogo no lugar de formulário. Um ou dois campos usam
ctx.prompt,ctx.chooseectx.confirm. Efeito destrutivo usadangere valor oculto usasecret. - Resumo e toast.
ctx.statusmostra o resumo da tela ectx.notifymostra o resultado de cada ação. - Ícones de
ctx.icons. Nenhum glifo de papel fixo na screen, a keytui.iconstroca o conjuntonerd,unicodeouascii. - Mouse e teclado no mesmo efeito. O clique, o hover e a roda passam
pela mesma ação da tecla. O teste usa
setup.mockMouse. - Cores de
ctx.theme. Cor fixa no código quebra uma das paletas. No tematerminal, cada cor é uma referência à paleta do terminal. mountsíncrono.mountcria os nós. O trabalho ativo começa emonEntere para emonLeave.- Arquivo observado.
watch()lista os arquivos que a tela lê. O shell recarrega a tela quando outro processo muda um deles e avisa no toast. - Pausa no foco.
onPausepara timers eonResumeretoma.ctx.motiongoverna a animação curta de diálogos e toasts. - Cleanup em
onLeave. O shell chamaonLeavena troca de aba e no encerramento, então pare timers, assinaturas e consultas ali. - A aplicação é dona do renderer. A screen sai com
ctx.quit(), semprocess.exit(), sem outro renderer e sem escrever em stdout. onKeydevolvetruesó para tecla consumida. Assimq,?,Tab, as setas laterais e os dígitos continuam trocando de aba e encerrando.- Respostas antigas descartadas. O contador de geração impede que uma carga lenta substitua uma mais nova ou altere uma aba que já saiu.
- Mensagem própria no erro. A screen não mostra
String(error)da API, que pode trazer detalhes internos do serviço. - Serviço compartilhado. A screen chama o mesmo client do CLI e do MCP, sem duplicar autenticação nem HTTP.
O que ela entrega
A skill relata os arquivos alterados, as versões conferidas, as teclas, as ações, os estados cobertos, as dimensões ensaiadas e um frame real capturado. Separa testes executados, exemplos só compilados e comportamentos não exercitados.
| Arquivo | Mudança |
|---|---|
src/tui/screens/<id>.ts |
screen nova ou revisada |
src/tui/screens/index.ts |
screen na lista de abas |
src/config/settings.ts |
id em tui.initialTab, quando abre direto |
src/cli/commands/tui.ts |
id nos valores de --tab, idem |
tests/ |
testes com createTestRenderer e mountTui |
docs/tui.md |
teclas e uso da aba |
Próxima skill
Se a screen trouxe uma preferência nova, declare a key com termfy-config. Para expor o mesmo recurso a agentes, siga com termfy-mcp.