redmine-context 1.0.0

package/dist/surfaces/tui/screens/welcome.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Tela de boas-vindas da TUI — scaffold M2-01, com hints de doctor/config
+ * (M2-12, #35), o ponto de entrada do onboarding (M2-05.1, #27) e o desvio
+ * direto para a home quando já há credencial salva (M2-06, #29).
+ *
+ * Mostra nome do produto + versão (via a superfície pública do core,
+ * `../../../index.js`, ADR-005) e a dica de teclas. Cores vêm do tema
+ * central (M2-02, `useTheme()`) — nenhum literal de cor aqui, ver
+ * `theme.ts` para o guideline de uso de cada token.
+ *
+ * `Enter` checa a cascata de credenciais (`resolveApiKey`, mesma convenção
+ * de instância — `REDMINE_URL` — usada pelo doctor/CLI/MCP): com credencial
+ * já resolvida, pula direto para `home` (#29); sem ela (ou sem
+ * `REDMINE_URL` configurada, ou se a cascata falhar), segue o fluxo de
+ * onboarding de sempre. A checagem é assíncrona; `checkingRef` evita
+ * disparar mais de uma em paralelo se `Enter` for pressionado repetidas
+ * vezes antes da primeira resolver.
+ */
+import { useCallback, useRef, useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { resolveApiKey, TOOL_NAME, TOOL_VERSION } from '../../../index.js';
+import { GradientText } from '../components/gradient-text.js';
+import { useEnvFallbackAllowed } from '../instance.js';
+import { useNavigation } from '../navigation.js';
+import { useTheme } from '../theme.js';
+/** Lê `REDMINE_URL` do ambiente, tratando string vazia como ausente (mesma convenção do doctor). */
+function instanceFromEnv(env) {
+    const value = env.REDMINE_URL;
+    return value !== undefined && value.length > 0 ? value : undefined;
+}
+/**
+ * Tela inicial do roteador: `Enter` vai para `home` (credencial já salva) ou
+ * inicia o onboarding (M2-05.1), `?` atalhos, `d` doctor, `c` config, `q`
+ * sai (ver `app.tsx`).
+ */
+export function WelcomeScreen() {
+    const { navigate } = useNavigation();
+    const theme = useTheme();
+    const [checking, setChecking] = useState(false);
+    // Handlers ESTÁVEIS (useCallback+refs) — mesmo padrão do TextInput/app.tsx:
+    // identidade nova por render des/re-subscreve o useInput e perde teclas.
+    const navigateRef = useRef(navigate);
+    navigateRef.current = navigate;
+    const checkingRef = useRef(checking);
+    checkingRef.current = checking;
+    // SEGURANÇA (#187): instância de origem `config` (URL persistida) não pode usar a
+    // env-key instance-agnóstica. Ref pelo padrão de handler estável desta tela.
+    const allowEnvFallbackRef = useRef(true);
+    allowEnvFallbackRef.current = useEnvFallbackAllowed();
+    const handleInput = useCallback((input, key) => {
+        // Reason: o Ink reporta Ctrl+<letra> com o MESMO `input` da letra solta
+        // (ex.: Ctrl+C chega como `input === 'c'`, `key.ctrl === true`) — sem essa
+        // guarda, o atalho global de sair (duplo Ctrl+C, `app.tsx`) navegaria
+        // para `config` por engano a cada Ctrl+C pressionado nesta tela.
+        if (key.ctrl) {
+            return;
+        }
+        if (input === '?') {
+            navigateRef.current('about');
+            return;
+        }
+        if (key.return) {
+            if (checkingRef.current) {
+                return;
+            }
+            const instanceUrl = instanceFromEnv(process.env);
+            if (instanceUrl === undefined) {
+                navigateRef.current('onboarding-url');
+                return;
+            }
+            setChecking(true);
+            void (async () => {
+                const apiKey = await resolveApiKey(instanceUrl, {
+                    env: process.env,
+                    allowEnvFallback: allowEnvFallbackRef.current,
+                }).catch(() => undefined);
+                setChecking(false);
+                navigateRef.current(apiKey !== undefined ? 'home' : 'onboarding-url');
+            })();
+            return;
+        }
+        if (input === 'd') {
+            navigateRef.current('doctor');
+        }
+        if (input === 'c') {
+            navigateRef.current('config');
+        }
+        if (input === 'a') {
+            navigateRef.current('appearance');
+        }
+    }, []);
+    useInput(handleInput);
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, paddingY: 1, children: [_jsx(GradientText, { colors: theme.gradient ?? [theme.primary], children: TOOL_NAME }), _jsxs(Text, { color: theme.muted, children: ["v", TOOL_VERSION] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { children: "Contexto completo de issues do Redmine, pronto para qualquer LLM." }) }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: theme.muted, children: ["Pressione ", _jsx(Text, { color: theme.accent, children: "Enter" }), " para continuar,", ' ', _jsx(Text, { color: theme.accent, children: "?" }), " para atalhos,", ' ', _jsx(Text, { color: theme.accent, children: "d" }), " para o doctor,", ' ', _jsx(Text, { color: theme.accent, children: "c" }), " para configura\u00E7\u00E3o,", ' ', _jsx(Text, { color: theme.accent, children: "a" }), " para apar\u00EAncia,", ' ', _jsx(Text, { color: theme.accent, children: "q" }), " para sair."] }) })] }));
+}

package/dist/surfaces/tui/status-color.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Heurística de cor de status compartilhada entre telas de issue (M2-06/#29,
+ * extraída na #31 para ser reaproveitada por `screens/issue-detail.tsx` sem
+ * duplicar a lógica antes privada de `screens/home.tsx`).
+ *
+ * Sempre devolve um token do tema (nunca um literal de cor) — a varredura
+ * anti-hardcode (`tests/surfaces/tui/no-hardcoded-colors.test.ts`) cobre
+ * qualquer arquivo desta árvore.
+ */
+import type { Theme } from './theme.js';
+/**
+ * Cor do badge de status: heurística por nome do status. `theme.primary` é o
+ * fallback para status sem correspondência (ex.: "Nova", "Em espera").
+ *
+ * @param theme - Tema ativo (via `useTheme()` no chamador).
+ * @param statusName - Nome do status vindo do Redmine (`issue.status.name`).
+ * @returns O token de cor do tema mais adequado ao status.
+ * @example
+ * statusColor(theme, 'Fechado') // theme.success
+ */
+export declare function statusColor(theme: Theme, statusName: string): string;

package/dist/surfaces/tui/status-color.js

@@ -0,0 +1,23 @@
+/**
+ * Cor do badge de status: heurística por nome do status. `theme.primary` é o
+ * fallback para status sem correspondência (ex.: "Nova", "Em espera").
+ *
+ * @param theme - Tema ativo (via `useTheme()` no chamador).
+ * @param statusName - Nome do status vindo do Redmine (`issue.status.name`).
+ * @returns O token de cor do tema mais adequado ao status.
+ * @example
+ * statusColor(theme, 'Fechado') // theme.success
+ */
+export function statusColor(theme, statusName) {
+    const normalized = statusName.toLowerCase();
+    if (/fechad|closed|resolvid|resolved|conclu[ií]d/.test(normalized)) {
+        return theme.success;
+    }
+    if (/cancel/.test(normalized)) {
+        return theme.danger;
+    }
+    if (/andamento|progress|curso/.test(normalized)) {
+        return theme.warning;
+    }
+    return theme.primary;
+}

package/dist/surfaces/tui/symbols.d.ts

@@ -0,0 +1,231 @@
+/** Conjunto de símbolos disponível às telas da TUI (tick, cross, pointer, etc.). */
+export declare const symbols: {
+    readonly tick: string;
+    readonly info: string;
+    readonly warning: string;
+    readonly cross: string;
+    readonly square: string;
+    readonly squareSmall: string;
+    readonly squareSmallFilled: string;
+    readonly squareDarkShade: string;
+    readonly squareMediumShade: string;
+    readonly squareLightShade: string;
+    readonly squareTop: string;
+    readonly squareBottom: string;
+    readonly squareLeft: string;
+    readonly squareRight: string;
+    readonly squareCenter: string;
+    readonly circle: string;
+    readonly circleFilled: string;
+    readonly circleDotted: string;
+    readonly circleDouble: string;
+    readonly circleCircle: string;
+    readonly circleCross: string;
+    readonly circlePipe: string;
+    readonly circleQuestionMark: string;
+    readonly radioOn: string;
+    readonly radioOff: string;
+    readonly checkboxOn: string;
+    readonly checkboxOff: string;
+    readonly checkboxCircleOn: string;
+    readonly checkboxCircleOff: string;
+    readonly questionMarkPrefix: string;
+    readonly bullet: string;
+    readonly dot: string;
+    readonly ellipsis: string;
+    readonly pointer: string;
+    readonly pointerSmall: string;
+    readonly triangleUp: string;
+    readonly triangleUpSmall: string;
+    readonly triangleUpOutline: string;
+    readonly triangleDown: string;
+    readonly triangleDownSmall: string;
+    readonly triangleLeft: string;
+    readonly triangleLeftSmall: string;
+    readonly triangleRight: string;
+    readonly triangleRightSmall: string;
+    readonly lozenge: string;
+    readonly lozengeOutline: string;
+    readonly home: string;
+    readonly hamburger: string;
+    readonly smiley: string;
+    readonly mustache: string;
+    readonly heart: string;
+    readonly star: string;
+    readonly play: string;
+    readonly musicNote: string;
+    readonly musicNoteBeamed: string;
+    readonly nodejs: string;
+    readonly arrowUp: string;
+    readonly arrowDown: string;
+    readonly arrowLeft: string;
+    readonly arrowRight: string;
+    readonly arrowLeftRight: string;
+    readonly arrowUpDown: string;
+    readonly almostEqual: string;
+    readonly notEqual: string;
+    readonly lessOrEqual: string;
+    readonly greaterOrEqual: string;
+    readonly identical: string;
+    readonly infinity: string;
+    readonly subscriptZero: string;
+    readonly subscriptOne: string;
+    readonly subscriptTwo: string;
+    readonly subscriptThree: string;
+    readonly subscriptFour: string;
+    readonly subscriptFive: string;
+    readonly subscriptSix: string;
+    readonly subscriptSeven: string;
+    readonly subscriptEight: string;
+    readonly subscriptNine: string;
+    readonly oneHalf: string;
+    readonly oneThird: string;
+    readonly oneQuarter: string;
+    readonly oneFifth: string;
+    readonly oneSixth: string;
+    readonly oneSeventh: string;
+    readonly oneEighth: string;
+    readonly oneNinth: string;
+    readonly oneTenth: string;
+    readonly twoThirds: string;
+    readonly twoFifths: string;
+    readonly threeQuarters: string;
+    readonly threeFifths: string;
+    readonly threeEighths: string;
+    readonly fourFifths: string;
+    readonly fiveSixths: string;
+    readonly fiveEighths: string;
+    readonly sevenEighth: string;
+    readonly line: string;
+    readonly lineBold: string;
+    readonly lineDouble: string;
+    readonly lineDashed0: string;
+    readonly lineDashed1: string;
+    readonly lineDashed2: string;
+    readonly lineDashed3: string;
+    readonly lineDashed4: string;
+    readonly lineDashed5: string;
+    readonly lineDashed6: string;
+    readonly lineDashed7: string;
+    readonly lineDashed8: string;
+    readonly lineDashed9: string;
+    readonly lineDashed10: string;
+    readonly lineDashed11: string;
+    readonly lineDashed12: string;
+    readonly lineDashed13: string;
+    readonly lineDashed14: string;
+    readonly lineDashed15: string;
+    readonly lineVertical: string;
+    readonly lineVerticalBold: string;
+    readonly lineVerticalDouble: string;
+    readonly lineVerticalDashed0: string;
+    readonly lineVerticalDashed1: string;
+    readonly lineVerticalDashed2: string;
+    readonly lineVerticalDashed3: string;
+    readonly lineVerticalDashed4: string;
+    readonly lineVerticalDashed5: string;
+    readonly lineVerticalDashed6: string;
+    readonly lineVerticalDashed7: string;
+    readonly lineVerticalDashed8: string;
+    readonly lineVerticalDashed9: string;
+    readonly lineVerticalDashed10: string;
+    readonly lineVerticalDashed11: string;
+    readonly lineDownLeft: string;
+    readonly lineDownLeftArc: string;
+    readonly lineDownBoldLeftBold: string;
+    readonly lineDownBoldLeft: string;
+    readonly lineDownLeftBold: string;
+    readonly lineDownDoubleLeftDouble: string;
+    readonly lineDownDoubleLeft: string;
+    readonly lineDownLeftDouble: string;
+    readonly lineDownRight: string;
+    readonly lineDownRightArc: string;
+    readonly lineDownBoldRightBold: string;
+    readonly lineDownBoldRight: string;
+    readonly lineDownRightBold: string;
+    readonly lineDownDoubleRightDouble: string;
+    readonly lineDownDoubleRight: string;
+    readonly lineDownRightDouble: string;
+    readonly lineUpLeft: string;
+    readonly lineUpLeftArc: string;
+    readonly lineUpBoldLeftBold: string;
+    readonly lineUpBoldLeft: string;
+    readonly lineUpLeftBold: string;
+    readonly lineUpDoubleLeftDouble: string;
+    readonly lineUpDoubleLeft: string;
+    readonly lineUpLeftDouble: string;
+    readonly lineUpRight: string;
+    readonly lineUpRightArc: string;
+    readonly lineUpBoldRightBold: string;
+    readonly lineUpBoldRight: string;
+    readonly lineUpRightBold: string;
+    readonly lineUpDoubleRightDouble: string;
+    readonly lineUpDoubleRight: string;
+    readonly lineUpRightDouble: string;
+    readonly lineUpDownLeft: string;
+    readonly lineUpBoldDownBoldLeftBold: string;
+    readonly lineUpBoldDownBoldLeft: string;
+    readonly lineUpDownLeftBold: string;
+    readonly lineUpBoldDownLeftBold: string;
+    readonly lineUpDownBoldLeftBold: string;
+    readonly lineUpDownBoldLeft: string;
+    readonly lineUpBoldDownLeft: string;
+    readonly lineUpDoubleDownDoubleLeftDouble: string;
+    readonly lineUpDoubleDownDoubleLeft: string;
+    readonly lineUpDownLeftDouble: string;
+    readonly lineUpDownRight: string;
+    readonly lineUpBoldDownBoldRightBold: string;
+    readonly lineUpBoldDownBoldRight: string;
+    readonly lineUpDownRightBold: string;
+    readonly lineUpBoldDownRightBold: string;
+    readonly lineUpDownBoldRightBold: string;
+    readonly lineUpDownBoldRight: string;
+    readonly lineUpBoldDownRight: string;
+    readonly lineUpDoubleDownDoubleRightDouble: string;
+    readonly lineUpDoubleDownDoubleRight: string;
+    readonly lineUpDownRightDouble: string;
+    readonly lineDownLeftRight: string;
+    readonly lineDownBoldLeftBoldRightBold: string;
+    readonly lineDownLeftBoldRightBold: string;
+    readonly lineDownBoldLeftRight: string;
+    readonly lineDownBoldLeftBoldRight: string;
+    readonly lineDownBoldLeftRightBold: string;
+    readonly lineDownLeftRightBold: string;
+    readonly lineDownLeftBoldRight: string;
+    readonly lineDownDoubleLeftDoubleRightDouble: string;
+    readonly lineDownDoubleLeftRight: string;
+    readonly lineDownLeftDoubleRightDouble: string;
+    readonly lineUpLeftRight: string;
+    readonly lineUpBoldLeftBoldRightBold: string;
+    readonly lineUpLeftBoldRightBold: string;
+    readonly lineUpBoldLeftRight: string;
+    readonly lineUpBoldLeftBoldRight: string;
+    readonly lineUpBoldLeftRightBold: string;
+    readonly lineUpLeftRightBold: string;
+    readonly lineUpLeftBoldRight: string;
+    readonly lineUpDoubleLeftDoubleRightDouble: string;
+    readonly lineUpDoubleLeftRight: string;
+    readonly lineUpLeftDoubleRightDouble: string;
+    readonly lineUpDownLeftRight: string;
+    readonly lineUpBoldDownBoldLeftBoldRightBold: string;
+    readonly lineUpDownBoldLeftBoldRightBold: string;
+    readonly lineUpBoldDownLeftBoldRightBold: string;
+    readonly lineUpBoldDownBoldLeftRightBold: string;
+    readonly lineUpBoldDownBoldLeftBoldRight: string;
+    readonly lineUpBoldDownLeftRight: string;
+    readonly lineUpDownBoldLeftRight: string;
+    readonly lineUpDownLeftBoldRight: string;
+    readonly lineUpDownLeftRightBold: string;
+    readonly lineUpBoldDownBoldLeftRight: string;
+    readonly lineUpDownLeftBoldRightBold: string;
+    readonly lineUpBoldDownLeftBoldRight: string;
+    readonly lineUpBoldDownLeftRightBold: string;
+    readonly lineUpDownBoldLeftBoldRight: string;
+    readonly lineUpDownBoldLeftRightBold: string;
+    readonly lineUpDoubleDownDoubleLeftDoubleRightDouble: string;
+    readonly lineUpDoubleDownDoubleLeftRight: string;
+    readonly lineUpDownLeftDoubleRightDouble: string;
+    readonly lineCross: string;
+    readonly lineBackslash: string;
+    readonly lineSlash: string;
+};

package/dist/surfaces/tui/symbols.js

@@ -0,0 +1,14 @@
+/**
+ * Símbolos da TUI (M2-03).
+ *
+ * Fonte única de símbolos para as telas — nada de caracteres Unicode
+ * hardcoded (ex.: `'✔'`, `'✖'`) espalhados pelo código das telas. Reexporta o
+ * conjunto padrão de `figures`, que já detecta o suporte a Unicode do
+ * terminal e degrada sozinho para ASCII quando necessário (principalmente no
+ * Windows/cmd.exe — ver AC da issue M2-03).
+ *
+ * As telas importam daqui: `import { symbols } from '../symbols.js'`.
+ */
+import figures from 'figures';
+/** Conjunto de símbolos disponível às telas da TUI (tick, cross, pointer, etc.). */
+export const symbols = figures;

package/dist/surfaces/tui/terminal-colors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Aplica as cores da paleta como DEFAULT do terminal via OSC (#190).
+ *
+ * Em vez de pintar um Box de fundo (que deixava emenda e não cobria a tela toda),
+ * setamos o fundo (OSC 11) e o texto (OSC 10) DEFAULT do terminal para os da
+ * paleta. Efeito: o buffer inteiro (inclusive áreas vazias) ganha o fundo temático,
+ * e todo texto SEM cor explícita usa a cor de texto da paleta — legível em qualquer
+ * terminal (claro ou escuro). Ao sair, {@link resetTerminalColors} restaura o padrão.
+ *
+ * OSC = "Operating System Command": `ESC ] <n> ; <valor> BEL`. Suportado pelos
+ * emuladores modernos (iTerm2, Terminal.app, etc.); onde não houver suporte, os
+ * códigos são ignorados — as paletas CLARAS ainda ficam legíveis sobre o fundo
+ * claro do terminal (degradação graciosa).
+ */
+import type { Theme } from './theme.js';
+/**
+ * Escreve OSC 11 (fundo) e OSC 10 (texto) com as cores da paleta, quando definidas.
+ *
+ * @param out - Stream do terminal.
+ * @param theme - Tema/paleta ativa (usa `background`/`text`).
+ */
+export declare function applyTerminalColors(out: NodeJS.WriteStream, theme: Theme): void;
+/**
+ * Restaura o fundo (OSC 111) e o texto (OSC 110) DEFAULT do terminal ao valor
+ * original — chamado ao sair do full-screen (inclusive em sinal, via alt-screen).
+ *
+ * @param out - Stream do terminal.
+ */
+export declare function resetTerminalColors(out: NodeJS.WriteStream): void;

package/dist/surfaces/tui/terminal-colors.js

@@ -0,0 +1,39 @@
+/**
+ * Aplica as cores da paleta como DEFAULT do terminal via OSC (#190).
+ *
+ * Em vez de pintar um Box de fundo (que deixava emenda e não cobria a tela toda),
+ * setamos o fundo (OSC 11) e o texto (OSC 10) DEFAULT do terminal para os da
+ * paleta. Efeito: o buffer inteiro (inclusive áreas vazias) ganha o fundo temático,
+ * e todo texto SEM cor explícita usa a cor de texto da paleta — legível em qualquer
+ * terminal (claro ou escuro). Ao sair, {@link resetTerminalColors} restaura o padrão.
+ *
+ * OSC = "Operating System Command": `ESC ] <n> ; <valor> BEL`. Suportado pelos
+ * emuladores modernos (iTerm2, Terminal.app, etc.); onde não houver suporte, os
+ * códigos são ignorados — as paletas CLARAS ainda ficam legíveis sobre o fundo
+ * claro do terminal (degradação graciosa).
+ */
+const BEL = '\x07';
+/**
+ * Escreve OSC 11 (fundo) e OSC 10 (texto) com as cores da paleta, quando definidas.
+ *
+ * @param out - Stream do terminal.
+ * @param theme - Tema/paleta ativa (usa `background`/`text`).
+ */
+export function applyTerminalColors(out, theme) {
+    let seq = '';
+    if (theme.background !== undefined)
+        seq += `\x1b]11;${theme.background}${BEL}`;
+    if (theme.text !== undefined)
+        seq += `\x1b]10;${theme.text}${BEL}`;
+    if (seq.length > 0)
+        out.write(seq);
+}
+/**
+ * Restaura o fundo (OSC 111) e o texto (OSC 110) DEFAULT do terminal ao valor
+ * original — chamado ao sair do full-screen (inclusive em sinal, via alt-screen).
+ *
+ * @param out - Stream do terminal.
+ */
+export function resetTerminalColors(out) {
+    out.write(`\x1b]110${BEL}\x1b]111${BEL}`);
+}

package/dist/surfaces/tui/theme.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Tema central da TUI (M2-02).
+ *
+ * Fonte de literais de cor da TUI (junto de `palettes.ts`, #190, que guarda os
+ * hex das paletas como DADOS de objeto, não como props JSX): toda tela consome
+ * cores via {@link useTheme}, nunca com `color="magenta"` direto no JSX — a
+ * varredura `tests/surfaces/tui/no-hardcoded-colors.test.ts` garante isso em CI
+ * (ela pega `color=`/`backgroundColor=` com literal; as chaves `primary:` de
+ * `palettes.ts` não são props, por isso passam). Centralizar aqui/em `palettes.ts`
+ * torna trocar a paleta uma mudança localizada.
+ *
+ * ## Paleta e guideline de uso
+ *
+ * Combinação sóbria sobre fundo escuro (a paleta padrão de 16 cores do
+ * terminal, resolvida pelo próprio emulador — sem hex fixo, para respeitar o
+ * esquema de cores do usuário):
+ *
+ * - **primary** (`cyan`) — cor de identidade/foco: títulos, item selecionado,
+ *   estado ativo. É a cor mais usada na TUI; se uma tela parece "sem cor
+ *   nenhuma", provavelmente falta um `primary` nela.
+ * - **accent** (`magenta`) — destaque raro: uma call-to-action pontual (ex.:
+ *   a tecla que o usuário deve apertar agora). Usar com moderação — se
+ *   `accent` aparece em toda linha da tela, ele deixou de ser um destaque.
+ * - **muted** (`gray`) — texto secundário/de apoio: dicas, timestamps,
+ *   metadados. Substitui o uso solto de `dimColor` por um tom deliberado.
+ * - **success** (`green`) / **warning** (`yellow`) / **danger** (`red`) —
+ *   reservadas para *estado*, nunca para decoração: resultado de uma
+ *   operação (sucesso/erro) ou um alerta acionável. Não usar `danger` só
+ *   porque "fica bonito" — é reservada para sinalizar problema real.
+ *
+ * Reaproveita os nomes de cor nativos do Ink/chalk (paleta ANSI de 16 cores),
+ * então funciona em qualquer terminal sem depender de suporte a true color.
+ */
+import { type ReactNode } from 'react';
+/**
+ * Tokens semânticos de cor da TUI.
+ *
+ * Os valores são nomes de cor aceitos por `color`/`backgroundColor` do Ink
+ * (ver guideline de uso no topo do arquivo).
+ */
+export interface Theme {
+    /** Identidade/foco: títulos, seleção, estado ativo. */
+    primary: string;
+    /** Destaque raro: uma call-to-action pontual por tela. */
+    accent: string;
+    /** Texto secundário/de apoio: dicas, metadados. */
+    muted: string;
+    /** Resultado positivo de uma operação. */
+    success: string;
+    /** Alerta acionável, não bloqueante. */
+    warning: string;
+    /** Erro ou operação que falhou. */
+    danger: string;
+    /** Bordas de Box (painéis, cards, modais). Discreta por padrão. */
+    border: string;
+    /**
+     * Segunda cor de identidade (opcional) — variedade em listas/cabeçalhos sem
+     * abusar do `accent`. Ausente ⇒ cai em {@link Theme.primary}.
+     */
+    secondary?: string;
+    /**
+     * Cor de FUNDO da paleta (opcional, #190). Aplicada como fundo DEFAULT do
+     * terminal (OSC 11) ao entrar em full-screen — cobre a tela inteira sem pintar
+     * um Box (evita emenda/altura fixa). Ausente ⇒ herda o fundo do terminal.
+     */
+    background?: string;
+    /**
+     * Cor de TEXTO padrão da paleta (opcional, #190). Aplicada como foreground
+     * DEFAULT do terminal (OSC 10) ao entrar em full-screen — assim TODO texto sem
+     * cor explícita (ex.: o assunto da issue) fica legível sobre o {@link background}
+     * (nada de "preto sobre escuro" no terminal claro do usuário). Ausente ⇒ herda o
+     * foreground do terminal.
+     */
+    text?: string;
+    /**
+     * Ramp de cores (2+ hex) para efeitos de GRADIENTE em títulos/breadcrumb
+     * (opcional, #190). Ausente ⇒ texto sólido em {@link Theme.primary}.
+     */
+    gradient?: readonly string[];
+}
+/** Tema padrão da TUI — ver guideline de uso na documentação do arquivo. */
+export declare const DEFAULT_THEME: Theme;
+/**
+ * Provider do tema — envolve toda a árvore da TUI em `app.tsx`.
+ *
+ * Aceita um `theme` customizado (para testes ou temas alternativos
+ * futuros); sem ele, usa {@link DEFAULT_THEME}.
+ */
+export declare function ThemeProvider({ theme, children, }: {
+    theme?: Theme;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Hook de tema consumido pelas telas — única forma permitida de obter uma
+ * cor na TUI (ver varredura anti-hardcode).
+ *
+ * @throws {Error} Se chamado fora de um `<ThemeProvider>` — indica erro de
+ *   composição (tela renderizada sem passar pelo roteador/`app.tsx`).
+ */
+export declare function useTheme(): Theme;
+/**
+ * Controlador de PALETA (#190) — permite ao seletor de tema trocar a paleta ao
+ * vivo (preview ao navegar) e confirmar (persistindo). Fornecido pelo `App`, que
+ * mantém o estado da paleta ativa e o repassa ao {@link ThemeProvider}.
+ */
+export interface ThemeController {
+    /** Id da paleta atualmente ativa. */
+    readonly paletteId: string;
+    /** Aplica uma paleta AO VIVO, sem persistir (preview ao navegar no seletor). */
+    preview(id: string): void;
+    /** Aplica E persiste a paleta (Enter no seletor). */
+    select(id: string): Promise<void>;
+}
+/** Provider do controlador de paleta — montado pelo `App`. */
+export declare function ThemeControllerProvider({ value, children, }: {
+    value: ThemeController;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Hook do controlador de paleta — usado pelo seletor de tema.
+ *
+ * @throws {Error} Se chamado fora de um `<ThemeControllerProvider>`.
+ */
+export declare function useThemeController(): ThemeController;
+/**
+ * Mapeamento previsto para `@inkjs/ui` (dependência já presente no projeto,
+ * ainda não consumida por nenhuma tela — nada é importado daqui, isso é só o
+ * plano de integração para quando o primeiro componente entrar).
+ *
+ * `@inkjs/ui` recebe cores por `extendTheme(defaultTheme, { components })`
+ * (ver docs da lib). Quando isso acontecer, a extensão deve ler os tokens
+ * daqui em vez de duplicar paleta:
+ *
+ * ```tsx
+ * import { extendTheme, defaultTheme } from '@inkjs/ui';
+ * import { DEFAULT_THEME } from './theme.js';
+ *
+ * const inkUiTheme = extendTheme(defaultTheme, {
+ *   components: {
+ *     Spinner: { styles: { frame: () => ({ color: DEFAULT_THEME.primary }) } },
+ *     Select: {
+ *       styles: {
+ *         focusIndicator: () => ({ color: DEFAULT_THEME.primary }),
+ *         highlightedText: () => ({ color: DEFAULT_THEME.accent }),
+ *       },
+ *     },
+ *     // ...demais componentes do @inkjs/ui conforme forem adotados.
+ *   },
+ * });
+ * ```
+ *
+ * Se `@inkjs/ui` ganhar suporte a um tema dinâmico (não apenas estático no
+ * módulo), essa extensão deve ser recalculada dentro de um hook que chame
+ * {@link useTheme} — hoje o tema é estático, então o esboço acima já é
+ * suficiente como referência.
+ */