🎨 ui.render e as superfícies

Um hook em ui.render recebe uma instância de um componente por vez: a faixa acima do prompt, um painel, a linha de saída de um comando, uma mensagem do modelo. Ele devolve uma árvore de elementos, ou passa adiante com next.

O e de um ui.render tem cinco campos que você vai usar sempre. O matcher filtra por eles: { component: 'Pane', requestId: 'meu-painel' } faz o hook acordar só para o seu painel.

O que olhar na tabela: o e.viewport é opcional (use e.viewport?.rows ?? 24, como o exemplo oficial do painel). E para a faixa e o painel, a largura certa não é viewport.columns: é e.props.bodyColumns, a caixa que sobra sem as marcas do engine.

Como ler o desenho: o cartão da esquerda é o e que chega. O hook olha esses campos e escolhe um dos dois caminhos: devolve uma árvore própria (seta azul) ou passa a vez (seta cinza). Existe um terceiro caminho, next({ ...e, props }), que muda os dados antes de o engine desenhar.

O módulo do mod não tem Box nem Text globais. Quem entrega os elementos é $.ui.resolve(e): uma tabela de construtores da superfície em que aquele e vai ser desenhado.

Você desestrutura o que precisa e usa como tag JSX. Não é uma chamada ao engine: o engine já resolveu a tabela quando os plugins carregaram. Por isso pode ser chamada no começo de todo render, sem custo.

on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
  const { Box, Text } = $.ui.resolve(e)
  const list = await read($, calls)
  const room = Math.max(1, (e.viewport?.rows ?? 24) - 4)

  return (
    <Box flexDirection="column">
      {list.length === 0 && <Text dimColor>No tool calls yet.</Text>}
      {list.slice(-room).map(call => (
        <Text dimColor={call.isDone}>
          {call.isDone ? 'done' : 'runs'} {call.tool}
        </Text>
      ))}
    </Box>
  )
})

Cada superfície pede o desenho por conta própria. O terminal desenha a árvore inteira com Ink; as outras recebem a árvore pela rede e desenham do jeito delas. Por isso cada uma tem sua tabela de elementos.

E nem todo componente existe em toda superfície: a faixa AbovePrompt só é pedida no terminal e no desktop; o Pane é pedido em todas.

O que olhar na tabela: o básico (Box, Text, Button) funciona em todo lugar. O resto exige um if (e.surface === ...). Um Svg devolvido ao terminal é uma árvore que não valida (tópico 5).

if (e.surface === "desktop") {
  const { Svg } = $.ui.resolve(e);
  // ... desenha o bicho como SVG animado
}
const fits = e.surface === "terminal" && columns >= COLS + 2 && (e.props.maxRows || 0) >= ROWS + 1;
if (!fits) {
  stopTicker();
  return stack(fallbackLine(Text, prefs, mood, stats, fill));
}
const { Raster } = $.ui.resolve(e);

O render é uma leitura. Ele lê o $.state (direto ou com read) e devolve uma árvore. A leitura feita durante o desenho inscreve aquela instância: quando alguém grava um valor novo, o engine redesenha exatamente quem leu. Ninguém precisa pedir redesenho.

Quem escreve é outro: um evento (tool.call, turn.complete) ou um handler de botão. Uma escrita feita dentro do render é recusada. Você viu o porquê do estado em $.state no módulo 2.3: variável de módulo some no hot-reload.

const isHidden = atom({ plugin: 'turn-band', key: 'isHidden' } as const, false)
// ...
on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
  const turn = await read($, last)
  // ...
  <Button
    key="hide"
    label="Hide"
    onPress={() => update($, isHidden, () => true)}
  />

Uma árvore não valida quando usa um elemento que a superfície não tem, uma prop que o elemento não aceita, ou um filho onde não cabe filho. O engine não quebra a sessão: desenha a dele no lugar e anota o motivo.

Por isso um mod com erro de desenho parece "não fazer nada". O motivo está escrito; você só precisa saber onde olhar.

Como ler o desenho: o portão do meio confere três coisas. Passou, a sua árvore aparece. Não passou, a tela mostra o desenho padrão e o motivo vai para o log. O módulo 4.3 mostra como corrigir uma árvore recusada.

O Rafa quer um mapa de calor do repositório: uma grade de quadradinhos coloridos. O instinto é um Box por célula. Não faça: uma grade colorida é um único Raster, com todas as células empacotadas numa string.

Para uma figura de verdade (PNG, quadro de vídeo) existe o Image. Os dois só existem no terminal.

Como ler o desenho: as duas grades mostram a mesma coisa. A da esquerda custa um elemento por célula; a da direita, um só. O repo-heatmap do kit vai além: dois "pixels" por célula com o meio bloco ▀ (frente = pixel de cima, fundo = pixel de baixo) e animação por $.ui.blit num $.clock.every.