🖥️ The Interface

O que e: Um custom react-reconciler conecta ao proprio DOM do Ink. Nos ink-virtual-text nao tem backing Yoga. O dirty flag sinaliza se re-rendering e necessario, nos limpos sao copiados do frame anterior com O(changed cells).

Por que aprender: Entender como React se conecta a uma saida de terminal e fundamental para compreender a arquitetura de UI do Claude Code.

Conceitos-chave: react-reconciler host, DOMElement tree, ink-virtual-text ghost nodes, dirty flag optimization, event handler isolation.

O que e: Yoga e um motor Flexbox C++ compilado para WebAssembly. A interface LayoutNode desacopla o codigo dos bindings Yoga. DOM index != yoga index para nos virtuais, exigindo contagem manual de siblings.

Por que aprender: Yoga e o mesmo algoritmo de layout do React Native. Entender suas limitacoes no terminal e crucial para custom components.

Conceitos-chave: C++ to WASM compilation, LayoutNode interface, sibling counting for virtual nodes, ink-link/ink-progress without Yoga backing.

O que e: Tree walk recursivo convertendo nos em operacoes Output. Blit Fast Path copia nos limpos diretamente. O Output class e um command-buffer com operacoes write, blit, clear, clip/unclip. Replay em dois passes: expansao de damage box e execucao.

Por que aprender: O command buffer pattern e a chave para entender como o Ink atinge performance de microsegundos no terminal.

Conceitos-chave: Blit fast path, ScrollBox hardware scroll (DECSTBM + SU/SD), damage bounding box, two-pass replay design.

O que e: Screen buffer com Int32Array: 2 words por celula (8 bytes). word0=charId, word1=styleId+hyperlinkId+width. Elimina alocacao de objeto por celula. StylePool faz intern, transition e cache de escape ANSI.

Por que aprender: Este design elimina 24,000 objetos por frame em um terminal 200x120, zerando a pressao no garbage collector.

Conceitos-chave: Packed Int32Array, zero GC pressure, StylePool transition() pre-computation, CellWidth enum (Narrow/Wide/SpacerTail/SpacerHead).

O que e: O diff final caminha apenas pelo damage bounding box. Para cada celula alterada, emite sequencia ANSI minimal. Steady-state frames tocam apenas O(changed cells).

Por que aprender: O diff granular e o que torna o rendering de terminal viavel em tempo real sem flickering.

Conceitos-chave: Damage bounding box walk, minimal ANSI emission, alt-screen height clamping, charCache hot path accelerator.

O que e: Dirty flag como otimizacao central, Yoga como engine Flexbox WASM, screen buffer como typed array (nao objetos), Output como command buffer, alt-screen com 3 invariantes interlocking.

Por que aprender: Esses patterns sao aplicaveis a qualquer rendering engine de alto desempenho, nao apenas terminais.

Conceitos-chave: 7-stage pipeline, zero GC architecture, command buffer pattern, O(changed cells) steady-state, reconciler event handler isolation.

O que e: Local Commands sao TypeScript puro e sincronos (/clear, /compact). Local JSX Commands renderizam componentes React/Ink (/help, /model). Prompt Commands expandem para blocos de conteudo enviados ao modelo (/commit, /review).

Por que aprender: Saber qual tipo usar define a arquitetura de qualquer extensao de comando.

Conceitos-chave: local (sync TypeScript), local-jsx (React/Ink), prompt (text expansion), lazy loading via load: () => import().

O que e: Pipeline: Static COMMANDS() + Skills dirs + Plugins + Workflows -> loadAllCommands(cwd) -> filter(availability + isEnabled) -> getCommands(cwd). Quatro fontes de skills: skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills.

Por que aprender: O pipeline de registro explica como comandos sao descobertos, filtrados e disponibilizados ao usuario.

Conceitos-chave: Four skill sources, availability gate (static auth-provider), isEnabled gate (runtime feature-flag), neither is memoized.

O que e: Prompts podem incluir shell substitution com backtick prefixado por !. Exemplo: git status e git diff HEAD sao executados e o resultado e injetado no prompt.

Por que aprender: Shell substitution permite criar prompts dinamicos que incluem contexto do ambiente atual.

Conceitos-chave: !backtick syntax, live output embedding, dynamic prompt construction.

O que e: Em bridge/remote mode: local-jsx e sempre bloqueado (renderiza UI de terminal), prompt e sempre seguro (expande para texto), local deve estar explicitamente em BRIDGE_SAFE_COMMANDS.

Por que aprender: Entender restricoes de modo remoto e essencial para desenvolver comandos compativeis com todos os modos de execucao.

Conceitos-chave: Bridge safety classification, BRIDGE_SAFE_COMMANDS allowlist, remote mode constraints, dead-code elimination by Bun.

O que e: Dois gates independentes: availability (static auth-provider check) e isEnabled (runtime feature-flag check). Nenhum e memoizado, mudancas de auth tomam efeito imediatamente. Lazy loading via load: () => import().

Por que aprender: O sistema de gates controla quais comandos cada tipo de usuario ve, sem necessidade de restart.

Conceitos-chave: availability gate (claude-ai/console), isEnabled() gate, no memoization, lazy import pattern, internal commands dead-code-eliminated.

O que e: 3 tipos de execucao (local, local-jsx, prompt), lazy loading, dois gates independentes, shell substitution embeds live output, internal-only commands eliminados pelo Bun em builds.

Por que aprender: Este resumo consolida os conceitos e serve como referencia rapida para o design do sistema.

Conceitos-chave: Three execution types, lazy loading, two independent gates, shell substitution, dead-code elimination.

O que e: Layer 1: Launchers (funcoes async retornando typed Promises). Layer 2: Helpers (showDialog/showSetupDialog wrappers). Layer 3: Design System (Dialog, Pane, PermissionDialog primitives). Layer 4: Feature Components (tool-specific permission requests).

Por que aprender: A separacao em camadas permite reutilizar primitivas de UI em qualquer contexto do Claude Code.

Conceitos-chave: dialogLaunchers.tsx, interactiveHelpers.tsx, Dialog/Pane/PermissionDialog primitives, async-to-promise bridge.

O que e: BashPermissionRequest e o mais complexo: integracao com classifier, regras "allow prefix", warnings de comandos destrutivos e fallback de sandbox. ClassifierCheckingSubtitle foi extraido porque um clock de shimmer a 20fps re-renderizava a arvore inteira de 535 linhas.

Por que aprender: Permission requests sao o ponto critico de interacao entre seguranca e UX.

Conceitos-chave: BashPermissionRequest complexity, ClassifierCheckingSubtitle extraction, 20fps shimmer optimization, single switch routing.

O que e: Widget universal de input com duas variantes: TextOption (opcao labeled padrao) e InputOption (campo de texto live embarcado na lista de selecao).

Por que aprender: CustomSelect e o building block reutilizado em quase toda interacao de selecao no Claude Code.

Conceitos-chave: Two variant types, embedded text field, isCancelActive text input conflict resolution.

O que e: WizardProvider como state container, useWizard como hook de navegacao, WizardDialogLayout com titulo auto-computed por step, WizardNavigationFooter contextual. Wizards gerenciam seu proprio ciclo de vida de exit.

Por que aprender: O wizard pattern e o padrao para qualquer fluxo multi-step no Claude Code.

Conceitos-chave: WizardProvider state container, useWizard navigation hook, auto-computed titles, contextual footer, self-managed exit lifecycle.

O que e: showSetupDialog e o unico local onde AppStateProvider e KeybindingSetup sao adicionados. Dialogs tornam-se funcoes async retornando typed Promises.

Por que aprender: Centralizar o setup garante consistencia de contexto em todos os dialogs do sistema.

Conceitos-chave: Sole location for AppStateProvider/KeybindingSetup, async function pattern, typed Promise returns.

O que e: Dialogs como async functions, showSetupDialog como unico ponto de setup, isCancelActive para conflitos de input, permission requests via single switch, wizards com lifecycle proprio.

Por que aprender: Consolida os patterns de design que regem toda a UI interativa do Claude Code.

Conceitos-chave: Async dialog pattern, sole setup location, input conflict resolution, switch-based routing, self-managed wizards.

O que e: Fila com 4 niveis de prioridade (immediate/high/medium/low). Campo fold permite merge de notificacoes com mesma key. immediate preempta o display atual, devolvendo itens deslocados a fila.

Por que aprender: O sistema de prioridades garante que alertas criticos como rate limits nunca sejam perdidos em meio a notificacoes de baixa prioridade.

Conceitos-chave: 4-level priority (immediate/high/medium/low), fold field as Array.reduce(), synchronous cancellation via currentTimeoutId, preempt-and-queue pattern.

O que e: 14 hooks especializados: rate-limit-warning (high), limit-reached (immediate), model-deprecation (high), lsp-error (medium), fast-mode (high), mcp-connectivity (medium), ide-status (medium), settings-error (high).

Por que aprender: Cada hook tem key e prioridade cuidadosamente escolhidas para garantir comportamento correto no sistema de filas.

Conceitos-chave: Hook catalog, keyed notifications, priority assignment rationale, limit-reached as sole immediate priority.

O que e: 5 canais: iterm2 (OSC 9), kitty (OSC 99 em 3 passos), ghostty (OSC single), terminal_bell (BEL unwrapped para tmux), notifications_disabled (no-op). BEL permanece unwrapped para que bell-action do tmux funcione nativamente.

Por que aprender: Notificacoes nativas sao cruciais para sessoes em background e integracao com multiplexadores de terminal.

Conceitos-chave: OSC escape sequences per terminal, BEL unwrapped for tmux, progress reporting (ConEmu/Ghostty/iTerm2), channel routing.

O que e: Apenas completamentos bem-sucedidos colapsam. Tasks falhadas e mortas permanecem individuais. Modo verbose ignora o collapsing.

Por que aprender: O collapsing inteligente evita poluicao visual sem esconder informacoes de erro.

Conceitos-chave: Success-only collapsing, failed/killed remain individual, verbose mode bypass, message-list level.

O que e: Notificacoes MCP passam por 6 camadas de seguranca: Capability -> Runtime flag -> Auth -> Org policy -> Session opt-in -> Allowlist.

Por que aprender: MCP channel notifications demonstram o modelo de seguranca em profundidade aplicado a cada feature do Claude Code.

Conceitos-chave: 6-layer gate, capability check, runtime flag, auth verification, org policy, session opt-in, allowlist.

O que e: Toast queue para status interativo, OS notifier para sessoes em background. Queue usa dequeuing baseado em prioridade, nao FIFO. BEL unwrapped para compatibilidade tmux.

Por que aprender: Resume os trade-offs de design entre os dois pipelines e suas respectivas garantias.

Conceitos-chave: Two pipelines, priority-based dequeuing, immediate preemption, BEL tmux compatibility, 6-layer MCP security.

O que e: VimState e uma discriminated union com INSERT (insertedText para dot-repeat) e NORMAL (CommandState). CommandState tem 11 variantes (idle, count, operator, operatorCount, find, etc.) que codificam exatamente o que o parser precisa lembrar.

Por que aprender: TypeScript's exhaustive switch-checking garante que adicionar um novo estado produz erro de compilacao ate que um handler seja adicionado.

Conceitos-chave: Discriminated unions, exhaustive switch, 11 CommandState variants, PersistentState (lastChange, lastFind, register).

O que e: transition() despacha por state.type para funcoes por estado. TransitionResult contem opcionalmente next state e execute callback. Callers chamam execute() e atualizam para next (ou resetam para idle). A logica nunca muta estado diretamente.

Por que aprender: A separacao entre transicao e efeito colateral torna o engine testavel e livre de dependencias de UI.

Conceitos-chave: Per-state dispatch functions, TransitionResult (next + execute), handleNormalInput shared helper, null = unrecognized input.

O que e: Funcoes puras: resolveMotion aplica um step por vez com early break em boundary. isInclusiveMotion (e, E, $) e isLinewiseMotion (j, k, G) controlam o range de operadores. Suporte completo: character, line, word, WORD, positions, file.

Por que aprender: Motions puras sao o fundamento composicional sobre o qual operadores constroem ranges de bytes.

Conceitos-chave: Pure functions, per-step application with boundary break, inclusive vs exclusive, linewise vs charwise, 7 motion categories.

O que e: 4 entry points: executeOperatorMotion, executeOperatorFind, executeOperatorTextObj, executeLineOp. cw trata diferente de dw (ate end of word, nao start of next). Text objects: bracket pairs (depth-counting bidirectional) vs quote pairs (linear pairing).

Por que aprender: O design de operators e text objects mostra como composition funciona em pratica: motions fornecem ranges, operators aplicam transformacoes.

Conceitos-chave: applyOperator (shared helper), cw special case, bracket depth-counting, quote linear pairing, Intl.Segmenter for unicode safety.

O que e: Dot-repeat funciona via RecordedChange (discriminated union capturando tudo para replay). Compound counts (2d3w) usam operatorCount state com multiplicacao de counts. MAX_VIM_COUNT = 10000 previne catastrophes de performance.

Por que aprender: Dot-repeat e o recurso mais poderoso do vim para produtividade. Entender o mecanismo de replay e essencial.

Conceitos-chave: RecordedChange union, operatorCount state for compound counts, count multiplication, MAX_VIM_COUNT safety limit.

O que e: Nenhum arquivo vim importa React, Ink ou framework de UI. Todos os efeitos fluem por OperatorContext e TransitionContext. O engine e testavel contra qualquer objeto que satisfaca a interface.

Por que aprender: Dependency inversion textbook: o engine opera puramente via interfaces, permitindo unit testing sem terminal.

Conceitos-chave: OperatorContext (cursor, text, setText, setOffset, enterInsert, register), TransitionContext extends with onUndo/onDotRepeat, zero UI knowledge.

O que e: parse-keypress.ts converte escape sequences em ParsedKey com nome, flags de modificadores e deteccao de paste. 3 protocolos: Legacy VT (arrow/function keys), CSI u/Kitty (Shift+Enter, Ctrl+Space), xterm modifyOtherKeys.

Por que aprender: Entender como bytes brutos do terminal se tornam eventos estruturados e o fundamento de toda a input layer.

Conceitos-chave: ParsedKey structure, XTerm modifier bitmask (1+shift+alt+ctrl+super), 3 keyboard protocols, ParsedMouse separate type.

O que e: DEFAULT_BINDINGS com 18 contextos UI. Keys dinamicas por plataforma (Windows: alt+v para image paste). Alt/meta unificacao porque legacy terminals nao distinguem. Escape special case: Ink interpreta como meta=true.

Por que aprender: O sistema de contextos e o mecanismo que permite keybindings diferentes em diferentes partes da UI.

Conceitos-chave: 18 UI contexts, platform-aware dynamic keys, feature-flag conditional bindings, alt/meta unification, escape stripping.

O que e: Resolver retorna 5 outcomes: match, none, unbound, chord_started, chord_cancelled. Last-wins override: user bindings sao appended apos defaults. Chord prefix detection prioriza sequencias longas sobre bindings simples.

Por que aprender: Chord resolution e o que permite shortcuts multi-key como ctrl+x ctrl+k sem conflitar com ctrl+x sozinho.

Conceitos-chave: 5 resolution outcomes, last-wins model, chordWinners map, null-unbinding, chord prefix detection priority.

O que e: useKeybinding/useKeybindings registram interesse. False return = propagate further. KeybindingContext com resolve(), setPendingChord(), getDisplayText(). Hot-reload via chokidar com 500ms write-stabilise delay.

Por que aprender: O sistema de hooks React e o que conecta keybindings a componentes de UI de forma reativa.

Conceitos-chave: false return convention, KeybindingContext shared bus, hot-reload pipeline, reserved shortcuts (ctrl+c/d/m), keybindings.json schema.

O que e: 5 tipos de warning: parse_error, duplicate, reserved, invalid_context, invalid_action. Non-rebindable: ctrl+c, ctrl+d, ctrl+m. Terminal reserved: ctrl+z, ctrl+\. macOS only: cmd+c/v/x/q/w/tab/space. ctrl+s NAO e reservado.

Por que aprender: Saber quais teclas sao reservadas e por que previne frustracao ao customizar keybindings.

Conceitos-chave: 5 warning types, non-rebindable keys (ctrl+c/d/m), ctrl+s intentionally not reserved, duplicate detection via regex pre-parse.

O que e: Raw bytes -> parse-keypress.ts (escape sequence decode) -> match.ts (Ink flag normalize) -> resolver.ts (chord logic + context matching) -> React hooks (handler invocation) -> stopImmediatePropagation (event bubble stop).

Por que aprender: O pipeline completo mostra como cada camada adiciona uma transformacao especifica ate chegar ao handler final.

Conceitos-chave: 5-stage pipeline, per-stage transformation, context-aware resolution, platform-specific display formatting.

O que e: DEC mode 1049 salva cursor, troca para alt screen e limpa. Mouse tracking empilha 4 modos (1000+1002+1003+1006). Desabilitacao em ordem reversa para teardown limpo. SGR (1006) desabilitado primeiro.

Por que aprender: Entender DEC modes e essencial para qualquer TUI que precise de fullscreen ou mouse tracking.

Conceitos-chave: DEC 1049 vs 47 (cursor save), mouse mode superset hierarchy, reverse-order disable, SGR format disable first.

O que e: isFullscreenActive() verifica interatividade, env vars, tmux -CC mode via probe sincrono (5ms). O probe e sincrono por design: async perdeu a corrida com React render e causou mouse wheel morto em iTerm2 -CC.

Por que aprender: Um caso classico de tradeoff correctness/performance: 5ms de bloqueio previne bug irrecuperavel de UX.

Conceitos-chave: probeTmuxControlModeSync(), 5ms correctness tradeoff, pre-seeded cache, two orthogonal mouse kill-switches.

O que e: useInsertionEffect (nao useLayoutEffect) garante que ENTER_ALT_SCREEN chega ao terminal antes do primeiro frame. Height fixado em size.rows porque alt screen nao tem scrollback. Signal-exit cleanup para saida limpa.

Por que aprender: A escolha de useInsertionEffect sobre useLayoutEffect e um detalhe sutil de timing do React que evita broken views.

Conceitos-chave: useInsertionEffect timing, mutation phase vs layout phase, height=size.rows constraint, signal-exit cleanup handler.

O que e: 5 slots: scrollable (message list), bottom (prompt), overlay (permissions), bottomFloat (speech bubble), modal (slash-command). Modal deixa exatamente 2 rows de transcript visivel acima. "N new messages" pill via useSyncExternalStore.

Por que aprender: O sistema de slots e o padrao para composicao de layout em aplicacoes de terminal complexas.

Conceitos-chave: 5 slot composition, MODAL_TRANSCRIPT_PEEK=2, ModalContext for interior dimensions, useSyncExternalStore pill.

O que e: Retorna cached ref enquanto offscreen, produzindo zero diff e zero terminal output. 'use no memo' opta-out do React Compiler que quebraria o mecanismo de freeze. Virtual list exemption para evitar conflito com ScrollBox.

Por que aprender: OffscreenFreeze demonstra como explorar o bail-out de identity do React para otimizar rendering de terminal.

Conceitos-chave: Object-identity bail-out, 'use no memo' React Compiler opt-out, InVirtualListContext exemption, zero diff output.

O que e: Sequencia completa: check -> mount -> enter alt screen -> render frames -> unmount -> exit alt screen -> restore cursor. Fullscreen default on para ant, off para external. Dois kill-switches ortogonais.

Por que aprender: O lifecycle completo mostra como cada decisao de deteccao se conecta a ativacao e desativacao corretas.

Conceitos-chave: 10-step lifecycle, fullscreen on for ant/off for external, CLAUDE_CODE_DISABLE_MOUSE, CLAUDE_CODE_NO_FLICKER.

O que e: Layer 1: Semantic Color Palette (6 temas, ~70 tokens). Layer 2: Chalk Normalization (detect/boost/clamp). Layer 3: Layout + Style Types (CSS-like para terminal). Layer 4: Theme-Aware Colorizer (curried helper, theme key resolution).

Por que aprender: A separacao em camadas garante que cada nivel opera independentemente, sem ciclos de resolucao.

Conceitos-chave: 4 layers, ~70 semantic tokens, O(1) flat lookup, styles.ts unaware of themes, design-system/color.ts as sole bridge.

O que e: 6 temas: dark, light, light-daltonized, dark-daltonized, light-ansi, dark-ansi. Daltonized substitui verde por azul sistematicamente (deuteranopia). ANSI themes usam apenas 16 cores padrao. auto resolvido em runtime.

Por que aprender: O design daltonized mostra como acessibilidade de cor e implementada de forma sistematica, nao ad-hoc.

Conceitos-chave: 6 concrete themes, ThemeSetting (auto) vs ThemeName (resolved), green->blue channel swap for deuteranopia, ANSI themes for custom palettes.

O que e: VS Code mente sobre suporte a cor (chalk level 2 -> orange vira salmon). tmux dropa truecolor backgrounds silenciosamente. Boost roda primeiro, clamp depois. VS Code dentro de tmux: clamp re-clamps para 2. Escape hatch: CLAUDE_CODE_TMUX_TRUECOLOR=1.

Por que aprender: Dois bug fixes de module-load-time que afetam toda a saida de cor subsequente do Claude Code.

Conceitos-chave: boostChalkLevelForXtermJs (level 2->3), clampChalkLevelForTmux (level 3->2), ordering: boost then clamp, string-prefix dispatch.

O que e: Styles e o equivalente de CSS properties para terminal. TextStyles.color e sempre raw Color value, nunca theme key. Color e uma discriminated union (RGB/Hex/Ansi256/Ansi). noSelect controla exclusao de selecao de texto em fullscreen.

Por que aprender: A decisao de manter styles.ts completamente unaware de temas garante separacao de concerns limpa.

Conceitos-chave: Raw Color value (never theme key), template literal types for compile-time validation, noSelect from-left-edge variant, resolvedStyle for diff application.

O que e: /theme com live preview via usePreviewTheme(). /color para sub-agent sessions (proibido para teammates). AgentColorManager mapeia agent types para 8 slots de cor com satisfies Record<> compile-time check.

Por que aprender: Os comandos de tema demonstram como customizacao de usuario se conecta ao sistema de paletas subjacente.

Conceitos-chave: ThemePicker live preview, /color teammate guard, "default" sentinel (not empty string), _FOR_SUBAGENTS_ONLY naming convention, satisfies constraint.

O que e: Tres fases: palette definition, environment normalization, rendering. VS Code boost e tmux clamp em module-load time. Theme resolution separada de color rendering. Shimmer pairs para animacoes de pulse.

Por que aprender: Consolida o fluxo completo de ThemeName -> raw color -> chalk output -> ANSI escape.

Conceitos-chave: 3 phases, boost-then-clamp ordering, _FOR_SUBAGENTS_ONLY guardrails, Shimmer suffix pairs, "default" sentinel for reset persistence.