primocode 9.0.0 → 9.1.0

package/lib/boas-vindas.js

@@ -122,8 +122,12 @@ async function rodar({ perguntar, mostrar, cores: c, interativo = true,
         return { liberado: false, motivo: 'sem-plano', plano };
     }
 
-    mostrar('');
-    mostrar(c.ok('  Conta liberada.') + c.muted(`  Plano ${plano}.`));
+    /* Nada de "Conta liberada." na abertura.
+       Estar logado é o estado NORMAL do produto — anunciar isso toda vez é
+       ruído, e ruído no primeiro instante empurra para baixo o que importa,
+       que é a caixa de digitar. O selo do plano continua existindo onde quem
+       procura vai olhar (/account, /status); a abertura só diz alguma coisa
+       quando há algo a resolver. */
 
     /* Não há etapa 3. O que vinha aqui era a escolha do provedor de IA, e
        ela morreu junto com o `/claude` e o `/gpt`: a API já vem com o
@@ -133,9 +137,13 @@ async function rodar({ perguntar, mostrar, cores: c, interativo = true,
     const primeira = !jaEscolheu();
     if (primeira) marcar({ plano });
 
-    mostrar('');
-    mostrar(c.muted(primeira ? '  Tudo pronto. Pode pedir a primeira coisa.'
-        : '  Pode pedir.'));
+    /* Na primeira vez a frase serve: a pessoa acabou de instalar e não sabe
+       que já pode pedir. Da segunda em diante ela é só mais uma linha entre
+       a pessoa e o cursor. */
+    if (primeira) {
+        mostrar('');
+        mostrar(c.muted('  Tudo pronto. Pode pedir a primeira coisa.'));
+    }
     mostrar('');
     return { liberado: true, plano, primeira, perguntou: false };
 }

package/lib/catalogo.js

@@ -206,4 +206,43 @@ function escreveArquivo(tool) {
     return ESCREVEM.has(tool);
 }
 
-module.exports = { GRUPOS, TODAS, ESCREVEM, escreveArquivo };
+
+/**
+ * As ferramentas de nome mais parecido com o que foi chamado.
+ *
+ * Serve a um caso só, e ele é real: o modelo chamou uma tool que não existe.
+ * Isso acontece quando a lista que o servidor oferece diverge deste catálogo
+ * — foi o que houve quando o Estúdio trocou de vocabulário e o servidor
+ * continuou oferecendo `studio_criar` e `studio_listar`. Sem esta lista, a
+ * resposta ao modelo era "Tool não implementada", ele não tinha como saber o
+ * que existe, e dizia ao usuário que a ferramenta "não está disponível".
+ *
+ * A semelhança é por prefixo e por pedaço de nome, não por distância de
+ * edição: os erros reais são de FAMÍLIA ("studio_criar" quando o certo é
+ * "estudio_plano"), não de digitação.
+ */
+function parecidasCom(nome) {
+    const alvo = String(nome || '').toLowerCase().replace(/^estudio_|^studio_/, '');
+    const familia = /^e?studio_/.test(String(nome || '').toLowerCase());
+    const pontos = TODAS.map((t) => {
+        let p = 0;
+        if (familia && /^estudio_|^planejar_/.test(t)) p += 3;
+        const semPrefixo = t.replace(/^estudio_/, '');
+        if (semPrefixo === alvo) p += 10;
+        else if (semPrefixo.includes(alvo) || alvo.includes(semPrefixo)) p += 5;
+        // pedaços em comum (criar/listar/plano/midia…)
+        for (const parte of alvo.split('_')) {
+            if (parte.length >= 4 && t.includes(parte)) p += 2;
+        }
+        return { t, p };
+    }).filter((x) => x.p > 0).sort((a, b) => b.p - a.p);
+    // Sem nada parecido, a resposta honesta é o grupo inteiro a que ele
+    // provavelmente queria chegar — melhor que uma lista vazia.
+    if (!pontos.length) {
+        return familia ? TODAS.filter((t) => /^estudio_|^planejar_/.test(t)) : TODAS.slice(0, 8);
+    }
+    return pontos.slice(0, 6).map((x) => x.t);
+}
+
+module.exports = {
+    parecidasCom, GRUPOS, TODAS, ESCREVEM, escreveArquivo };

package/lib/entrada.js

@@ -93,7 +93,7 @@ function montar(e) {
     const colunas = Math.max(24, Math.min(e.colunas || 80, 200));
     const largura = colunas - 1;    // a última coluna fica livre: escrever nela
                                     // faz o terminal quebrar a linha sozinho
-    const w = Math.max(8, largura - 6);   // │ + espaço + recuo(2) + … + espaço + │
+    const w = Math.max(8, largura - 3);   // espaço + '❯ ' — e mais nada à direita
 
     const cursor = Math.max(0, Math.min(e.cursor | 0, String(e.texto).length));
     const linhas = quebrar(e.texto, w);
@@ -108,9 +108,16 @@ function montar(e) {
         if (cursor >= l.de && cursor <= fim) { cursorLinha = i; cursorColuna = cursor - l.de; }
     }
 
+    /* DUAS RÉGUAS, NÃO UMA CAIXA.
+       Era uma caixa fechada — cantos e barras laterais. O Claude Code, que é a
+       referência pedida, usa só a linha de cima e a de baixo, e a diferença
+       não é gosto: a barra lateral direita obriga a reservar duas colunas em
+       toda linha e a preencher o resto com espaço, e é ela que faz o texto
+       colado parecer desalinhado quando o terminal é estreito. Sem as laterais
+       o campo ganha as colunas de volta e a emenda some. */
     const out = [];
-    const regua = c.dim(BORDA.h.repeat(largura - 2));
-    out.push(c.dim(BORDA.ne) + regua + c.dim(BORDA.no));
+    const regua = c.dim(BORDA.h.repeat(largura));
+    out.push(regua);
 
     const vazio = !String(e.texto).length;
     linhas.forEach((l, i) => {
@@ -124,10 +131,12 @@ function montar(e) {
             conteudo += c.dim(e.fantasma);
         }
         if (i === 0 && vazio && e.vazio) conteudo = c.dim(e.vazio);
-        out.push(c.dim(BORDA.v) + ' ' + marca + encher(conteudo, w) + ' ' + c.dim(BORDA.v));
+        // Sem `encher`: sem barra à direita não há nada para alinhar, e o
+        // espaço sobrando só apagaria o que estivesse embaixo.
+        out.push(' ' + marca + conteudo);
     });
 
-    out.push(c.dim(BORDA.se) + regua + c.dim(BORDA.so));
+    out.push(regua);
 
     // ── o menu dos comandos ──────────────────────────────────────────────
     // Fica ABAIXO da caixa, não dentro: dentro, ele empurraria o campo de
@@ -157,8 +166,8 @@ function montar(e) {
 
     return {
         linhas: out,
-        cursorLinha: 1 + cursorLinha,                   // +1 pela borda de cima
-        cursorColuna: 1 + 1 + 2 + cursorColuna,         // │ + espaço + recuo
+        cursorLinha: 1 + cursorLinha,                   // +1 pela régua de cima
+        cursorColuna: 1 + 2 + cursorColuna,             // espaço + '❯ '
     };
 }
 
@@ -221,10 +230,27 @@ class Entrada extends EventEmitter {
         this._stdoutOriginal = process.stdout.write;
         const eu = this;
         process.stdout.write = function (texto, ...resto) {
-            if (eu._pintando || !eu.desenhado) return eu._stdoutOriginal.call(this, texto, ...resto);
+            if (eu._pintando) return eu._stdoutOriginal.call(this, texto, ...resto);
             eu._apagar();
             const r = eu._stdoutOriginal.call(this, texto, ...resto);
-            eu._desenhar();
+            /* ── O TEXTO QUE CHEGA EM PEDAÇOS ────────────────────────────
+               A resposta do chat sai em fluxo: dezenas de `write` pequenos,
+               nenhum deles terminando em quebra de linha. Cada um deixa o
+               cursor NO MEIO da linha — e o desenho da caixa começa com
+               "\r\x1b[0J", que volta ao início da linha e limpa dali para
+               baixo. Ou seja: redesenhar ali apagava o pedaço que acabara de
+               ser escrito, e o seguinte apagava o próximo.
+
+               O efeito para quem usa era o pior possível: no modo chat a
+               mensagem ia, o modelo respondia, e a tela não mostrava NADA —
+               parecia que o programa tinha ignorado a pessoa.
+
+               Então a caixa espera a linha fechar. Enquanto o cursor estiver
+               no meio de uma, ela não é redesenhada; quando a quebra de linha
+               chega (o `fechar()` do fluxo manda uma), ela volta. */
+            const t = String(texto == null ? '' : texto);
+            eu._meiaLinha = t.length > 0 && !t.endsWith('\n');
+            if (!eu._meiaLinha) eu._desenhar();
             return r;
         };
         return this;
@@ -311,6 +337,11 @@ class Entrada extends EventEmitter {
         if (!this.tty || this.suspenso || this.fechado) return;
         const q = this._quadro();
         this._pintando = true;
+        /* Cursor no meio de uma linha (fluxo que ainda não fechou): desce uma
+           antes de desenhar. Vale para quem chama `_desenhar` por fora do
+           embrulho do stdout — `prompt()`, o fim de uma tela suspensa — e é o
+           que garante que a caixa nunca começa em cima de texto pela metade. */
+        if (this._meiaLinha) { this.escreverCru('\n'); this._meiaLinha = false; }
         // `\x1b[0J` limpa daqui até o fim da tela: sem isso, um quadro mais
         // curto que o anterior (menu que fechou) deixa lixo embaixo.
         this.escreverCru('\r\x1b[0J' + q.linhas.join('\n'));

package/lib/estudio/remotion.js

@@ -570,6 +570,20 @@ function fontesCSS(plano) {
  * `npm install` roda uma vez por projeto e demora minutos — é o preço do
  * Remotion, e está dito no README. Daí em diante, só o render.
  */
+/**
+ * Cita um argumento para a linha de comando do cmd.exe.
+ *
+ * Só serve ao Windows, e só porque o `shell: true` é obrigatório ali (o Node
+ * recusa spawnar npm.cmd/npx.cmd sem ele desde a correção do CVE-2024-27980).
+ * Quem não tem espaço nem metacaractere passa intacto: citar tudo deixaria a
+ * linha ilegível no log sem ganhar nada.
+ */
+function citarWin(a) {
+    const t = String(a);
+    if (!/[\s&|<>^"()]/.test(t)) return t;
+    return '"' + t.replace(/"/g, '""') + '"';
+}
+
 function renderizar({ raiz, saida, minutos = 30, aoFalar = () => {} }) {
     return new Promise((resolve) => {
         const temNodeModules = fs.existsSync(path.join(raiz, 'node_modules'));
@@ -582,7 +596,17 @@ function renderizar({ raiz, saida, minutos = 30, aoFalar = () => {} }) {
             aoFalar(i === 0 && !temNodeModules
                 ? 'instalando o Remotion nesta pasta (uma vez só, alguns minutos)'
                 : 'renderizando quadro a quadro');
-            const p = spawn(cmd, args, { cwd: raiz, shell: process.platform === 'win32' });
+            /* NO WINDOWS O `shell: true` NÃO CITA NADA.
+               Ele monta a linha do cmd.exe concatenando os argumentos crus, e
+               o `saida` é um caminho de arquivo que quase sempre tem espaço
+               (C:\Users\Joel Silva\primocode\...\saida\video.mp4). Sem
+               aspas, aquilo vira dois argumentos e o render falha — ou, pior,
+               escreve num lugar que ninguém pediu.
+               O `shell: true` não dá para tirar: desde a correção do
+               CVE-2024-27980 o Node recusa spawnar npm.cmd/npx.cmd sem shell.
+               Então as aspas entram na mão, só onde o shell existe. */
+            const citados = process.platform === 'win32' ? args.map(citarWin) : args;
+            const p = spawn(cmd, citados, { cwd: raiz, shell: process.platform === 'win32' });
             let erro = '';
             p.stderr.on('data', (d) => { erro += d.toString().slice(0, 2000); });
             p.stdout.on('data', (d) => {
@@ -597,7 +621,21 @@ function renderizar({ raiz, saida, minutos = 30, aoFalar = () => {} }) {
                 }
                 correr(i + 1);
             });
-            p.on('error', (e) => { clearTimeout(relogio); resolve({ ok: false, error: e.message }); });
+            p.on('error', (e) => {
+                clearTimeout(relogio);
+                /* "spawn npx ENOENT" não diz nada a quem instalou pelo ícone.
+                   Aplicativo aberto pela interface gráfica não herda o PATH do
+                   terminal: o node vem por caminho absoluto (lib/instalar-app.js),
+                   mas o npm e o npx não estão em lugar nenhum que ele enxergue. */
+                if (e.code === 'ENOENT') {
+                    return resolve({ ok: false,
+                        error: `não achei o "${cmd}" nesta máquina — o Remotion precisa dele para renderizar.`,
+                        comoResolver: 'instale o Node.js completo em nodejs.org (o npm vem junto). '
+                            + 'Se ele já está instalado e isto apareceu com o PrimoCode aberto pelo ícone, '
+                            + 'abra pelo terminal: o aplicativo não herda o PATH.' });
+                }
+                resolve({ ok: false, error: e.message });
+            });
         };
         correr(0);
     });

package/lib/fala.js

@@ -38,6 +38,7 @@
 'use strict';
 
 const { c, actionHeader, friendlyError } = require('./ui');
+const markdown = require('./markdown.js');
 
 /* Até este tamanho, o texto que o modelo escreve antes de chamar uma tool é
    guardado e sai de uma vez, como pensamento. Passou disso sem tool à vista,
@@ -89,10 +90,18 @@ function formatar(texto, marca) {
     return linhas(texto).map((l, i) => (i === 0 ? `${marca} ${c.white(l)}` : `  ${c.white(l)}`)).join('\n');
 }
 
-/** A resposta final, pronta. Espelha o ❯ de quem perguntou. */
+/** A resposta final, pronta. Espelha o ❯ de quem perguntou.
+ *
+ *  Passa pelo desenhador de Markdown pelo mesmo motivo do fluxo: o modelo
+ *  escreve com negrito, lista, tabela e bloco de código, e sem desenhar isso
+ *  a resposta chega com a marcação à mostra. `formatar` continua servindo ao
+ *  que NÃO é resposta do modelo (aviso, erro), que é texto nosso e já vem
+ *  pronto. */
 function resposta(texto) {
     if (!String(texto || '').trim()) return '';
-    const saida = '\n' + formatar(texto, c.brand('●'));
+    const largura = Math.max(40, (process.stdout.columns || 80) - 4);
+    const linhasMd = markdown.renderizar(texto, largura);
+    const saida = '\n' + linhasMd.map((l, i) => (i === 0 ? `${c.brand('●')} ${l}` : `  ${l}`)).join('\n');
     console.log(saida);
     return saida;
 }
@@ -120,15 +129,37 @@ const frase = friendlyError;
  * recuo, para o bloco continuar alinhado ao marcador.
  */
 function fluxo() {
+    /* A resposta do modelo vem em MARKDOWN — é o que ele escreve, e é o que o
+       prompt pede. Antes ela saía crua: "**importante**" aparecia com os
+       asteriscos, a tabela virava um monte de barras desalinhadas e o bloco de
+       código vinha com as três crases à mostra. Quem lia recebia o material
+       bruto e formatava de cabeça.
+
+       O desenho é por LINHA, não no fim: a resposta continua aparecendo
+       enquanto chega. Só a tabela e o bloco de código esperam fechar, porque
+       meia tabela na tela é pior que a tabela um segundo depois. */
     let escreveu = false;
+    const largura = Math.max(40, (process.stdout.columns || 80) - 4);
+    const desenho = markdown.fluxo(largura);
+
+    const sair = (linhas) => {
+        for (const linha of linhas) {
+            if (!escreveu) { process.stdout.write('\n' + c.brand('●') + ' '); escreveu = true; }
+            else process.stdout.write('\n  ');
+            process.stdout.write(linha);
+        }
+    };
+
     return {
         escrever(delta) {
             const t = String(delta || '');
             if (!t) return;
-            if (!escreveu) { process.stdout.write('\n' + c.brand('●') + ' '); escreveu = true; }
-            process.stdout.write(c.white(t.replace(/\n/g, '\n  ')));
+            sair(desenho.pedaco(t));
+        },
+        fechar() {
+            sair(desenho.fim());
+            if (escreveu) process.stdout.write('\n');
         },
-        fechar() { if (escreveu) process.stdout.write('\n'); },
         escreveu: () => escreveu,
     };
 }

package/lib/markdown.js

@@ -0,0 +1,376 @@
+/**
+ * markdown.js — a resposta do modelo, desenhada no terminal.
+ *
+ * ── POR QUE ISTO PRECISOU EXISTIR ────────────────────────────────────────
+ * O modelo escreve em Markdown; é o que ele sabe fazer, e é o que o prompt
+ * pede. Só que a resposta saía CRUA na tela: `**importante**` aparecia com os
+ * asteriscos, a tabela virava um monte de barras verticais desalinhadas, e o
+ * bloco de código vinha com as três crases à mostra. Quem lê recebe o material
+ * bruto e faz a formatação de cabeça — que é justamente o trabalho que a
+ * ferramenta deveria poupar.
+ *
+ * ── O QUE ESTE ARQUIVO NÃO É ─────────────────────────────────────────────
+ * Não é um parser de Markdown. Markdown completo tem aninhamento, HTML embutido
+ * e ambiguidade de sobra, e nada disso aparece numa resposta de terminal. Aqui
+ * é linha a linha, com três exceções que PRECISAM de bloco: a cerca de código,
+ * a tabela e a lista que continua na linha seguinte. O resto é uma passada de
+ * expressões regulares sobre o texto da linha.
+ *
+ * A vantagem prática é o FLUXO: como quase tudo se resolve por linha, a
+ * resposta pode ser desenhada enquanto chega, sem esperar terminar. Quem usa
+ * vê o texto aparecendo, e não uma tela parada que de repente enche.
+ *
+ * ── A REGRA DE OURO DO ALINHAMENTO ───────────────────────────────────────
+ * Código de cor NÃO ocupa coluna. Toda conta de largura (tabela, régua, quebra)
+ * usa `visibleWidth`, nunca `.length` — senão a tabela com uma célula colorida
+ * sai torta, e ninguém entende por quê.
+ */
+
+'use strict';
+
+const { c, visibleWidth, stripAnsi } = require('./ui.js');
+
+/* Zero dependências, então as cores que faltam no ui.js nascem aqui. O
+   itálico e o sublinhado não estão lá porque nada mais no programa usa. */
+const ANSI = (n) => (t) => `\x1b[${n}m${t}\x1b[0m`;
+const italico = ANSI(3);
+const riscado = ANSI(9);
+const inverso = ANSI(7);
+
+// ── o que se reconhece numa linha ────────────────────────────────────────
+
+const CERCA = /^\s{0,3}(```|~~~)\s*([a-zA-Z0-9+#._-]*)\s*$/;
+const TITULO = /^\s{0,3}(#{1,6})\s+(.*)$/;
+const MARCADOR = /^(\s*)([-*+])\s+(.*)$/;
+const NUMERADA = /^(\s*)(\d{1,3})([.)])\s+(.*)$/;
+const TAREFA = /^(\s*)[-*+]\s+\[([ xX])\]\s+(.*)$/;
+const CITACAO = /^\s{0,3}>\s?(.*)$/;
+const REGUA = /^\s{0,3}([-*_])\s*(?:\1\s*){2,}$/;
+const LINHA_TABELA = /^\s*\|.*\|\s*$/;
+const SEPARADOR_TABELA = /^\s*\|(?:\s*:?-{2,}:?\s*\|)+\s*$/;
+
+/**
+ * As marcas DENTRO de uma linha: negrito, itálico, código, link, riscado.
+ *
+ * O código inline é resolvido PRIMEIRO e sai de cena: um `**` dentro de
+ * `código` é código, não negrito, e resolver na ordem errada come as marcas do
+ * próprio trecho literal. Os pedaços saem, o resto é formatado, e eles voltam.
+ */
+function inline(texto) {
+    const guardados = [];
+    let t = String(texto)
+        .replace(/`([^`\n]+)`/g, (_, codigo) => {
+            guardados.push(inverso(' ' + codigo + ' '));
+            return `\u0000${guardados.length - 1}\u0000`;
+        });
+
+    t = t
+        // Link: o texto fica, o endereço vai junto em cinza — num terminal
+        // ninguém clica no texto, então esconder a URL é esconder a fonte.
+        .replace(/\[([^\]\n]+)\]\(([^)\s]+)[^)]*\)/g, (_, rotulo, url) => c.white(rotulo) + ' ' + c.dim(`(${url})`))
+        .replace(/(\*\*\*|___)([^\s].*?[^\s]|\S)\1/g, (_, __, x) => c.bold(italico(x)))
+        .replace(/(\*\*|__)([^\s].*?[^\s]|\S)\1/g, (_, __, x) => c.bold(c.white(x)))
+        .replace(/~~([^\s].*?[^\s]|\S)~~/g, (_, x) => riscado(x))
+        // Itálico com UM asterisco/sublinhado. O sublinhado só conta entre
+        // limites de palavra: nome_de_variavel_assim não é itálico, e tratá-lo
+        // como itálico embaralha todo texto sobre código.
+        .replace(/(^|[^*\w])\*([^\s*][^*]*?)\*(?![*\w])/g, (_, antes, x) => antes + italico(x))
+        .replace(/(^|[^_\w])_([^\s_][^_]*?)_(?![_\w])/g, (_, antes, x) => antes + italico(x));
+
+    return t.replace(/\u0000(\d+)\u0000/g, (_, i) => guardados[Number(i)]);
+}
+
+// ── blocos ───────────────────────────────────────────────────────────────
+
+/* As palavras que ganham cor dentro de um bloco de código. Não é um
+   analisador de sintaxe: é a lista das palavras que aparecem em quase toda
+   linguagem, mais os literais. Colorir demais fica pior que não colorir, e
+   inventar um parser por linguagem é trabalho sem fim para ganho pequeno. */
+const PALAVRAS = new RegExp('\\b(' + [
+    'function', 'return', 'const', 'let', 'var', 'class', 'extends', 'new', 'this',
+    'if', 'else', 'for', 'while', 'switch', 'case', 'break', 'continue', 'try', 'catch',
+    'finally', 'throw', 'async', 'await', 'import', 'from', 'export', 'default',
+    'def', 'elif', 'lambda', 'pass', 'with', 'as', 'in', 'is', 'not', 'and', 'or',
+    'self', 'None', 'True', 'False', 'null', 'undefined', 'true', 'false',
+    'public', 'private', 'static', 'void', 'int', 'string', 'bool', 'struct', 'type',
+    'func', 'package', 'interface', 'require', 'module',
+].join('|') + ')\\b', 'g');
+
+/* UMA passada só, com alternância — e isso não é preciosismo.
+   Na primeira versão eram três `replace` em sequência, e o terceiro (números)
+   pintava os dígitos DENTRO dos códigos de cor que os dois primeiros tinham
+   acabado de inserir: o "38;5;214" de um escape virava três números coloridos,
+   o escape se desmanchava e o terminal cuspia "[38;5;45m" como texto. Com uma
+   expressão só, cada pedaço da linha é consumido uma vez e nada pinta o que já
+   foi pintado. */
+const CODIGO = new RegExp([
+    '(["\'`])(?:\\\\.|(?!\\1)[^\\\\])*\\1',   // texto entre aspas
+    '(?://|#|--)[^\\n]*$',                     // comentário até o fim da linha
+    PALAVRAS.source,                        // palavra-chave
+    '\\b\\d+(?:\\.\\d+)?\\b',                 // número
+].join('|'), 'g');
+
+function pintarCodigo(linha) {
+    return String(linha).replace(CODIGO, (achado) => {
+        if (/^["'`]/.test(achado)) return c.ok(achado);
+        if (/^(\/\/|#|--)/.test(achado)) return c.dim(achado);
+        if (/^\d/.test(achado)) return c.cyan(achado);
+        return c.magenta(achado);
+    });
+}
+
+/** O bloco de código, com a linguagem no canto e uma barra à esquerda. */
+function blocoDeCodigo(linhas, linguagem, largura) {
+    const fora = [];
+    const barra = c.dim('│');
+    if (linguagem) fora.push('  ' + c.dim(linguagem));
+    for (const l of linhas) {
+        // Corta o que passa da largura em vez de deixar quebrar sozinho: uma
+        // linha de código quebrada no meio pela borda do terminal engana quem
+        // lê sobre onde ela termina.
+        const util = Math.max(20, largura - 4);
+        const corpo = visibleWidth(l) > util ? l.slice(0, util - 1) + '…' : l;
+        fora.push('  ' + barra + ' ' + pintarCodigo(corpo));
+    }
+    return fora;
+}
+
+/**
+ * A tabela, com as colunas alinhadas.
+ *
+ * A largura de cada coluna é a do conteúdo VISÍVEL mais largo — e por isso a
+ * conta é com `visibleWidth`: a célula em negrito tem código ANSI dentro, e
+ * medir por `.length` faz a coluna crescer sem motivo e desalinhar as outras.
+ */
+function tabela(linhas, largura) {
+    const celulas = linhas.map((l) => l.trim().replace(/^\||\|$/g, '').split('|').map((x) => x.trim()));
+    const alinhamentos = [];
+    let corpo = celulas;
+    if (celulas.length > 1 && SEPARADOR_TABELA.test(linhas[1])) {
+        for (const s of celulas[1]) {
+            alinhamentos.push(/^:.*:$/.test(s) ? 'centro' : /:$/.test(s) ? 'direita' : 'esquerda');
+        }
+        corpo = [celulas[0], ...celulas.slice(2)];
+    }
+    const formatadas = corpo.map((linha) => linha.map(inline));
+    const colunas = Math.max(...formatadas.map((l) => l.length));
+    const larguras = [];
+    for (let i = 0; i < colunas; i++) {
+        larguras.push(Math.max(...formatadas.map((l) => visibleWidth(l[i] || ''))));
+    }
+
+    // Tabela mais larga que o terminal: encolhe a coluna maior até caber. É
+    // melhor que deixar a linha quebrar — quebrada, a tabela deixa de ser
+    // tabela e vira um monte de texto solto.
+    const gasto = () => larguras.reduce((s, w) => s + w + 3, 1);
+    while (gasto() > largura - 2 && Math.max(...larguras) > 6) {
+        larguras[larguras.indexOf(Math.max(...larguras))] -= 1;
+    }
+
+    const encaixar = (txt, w, alinhamento) => {
+        let t = txt;
+        if (visibleWidth(t) > w) {
+            // Corta contando só o que é visível, para não decepar um código de
+            // cor no meio e vazar o escape para a tela.
+            const cru = stripAnsi(t).slice(0, Math.max(1, w - 1)) + '…';
+            t = cru;
+        }
+        const falta = w - visibleWidth(t);
+        if (alinhamento === 'direita') return ' '.repeat(falta) + t;
+        if (alinhamento === 'centro') {
+            const e = Math.floor(falta / 2);
+            return ' '.repeat(e) + t + ' '.repeat(falta - e);
+        }
+        return t + ' '.repeat(falta);
+    };
+
+    const risco = (e, meio, d) => c.dim(e + larguras.map((w) => '─'.repeat(w + 2)).join(meio) + d);
+    const fora = [risco('╭', '┬', '╮')];
+    formatadas.forEach((linha, i) => {
+        const cel = larguras.map((w, j) => encaixar(
+            i === 0 ? c.bold(c.white(stripAnsi(linha[j] || ''))) : (linha[j] || ''),
+            w, alinhamentos[j] || 'esquerda'));
+        fora.push(c.dim('│') + ' ' + cel.join(' ' + c.dim('│') + ' ') + ' ' + c.dim('│'));
+        if (i === 0) fora.push(risco('├', '┼', '┤'));
+    });
+    fora.push(risco('╰', '┴', '╯'));
+    return fora;
+}
+
+/** Quebra um parágrafo na largura, sem partir palavra e sem contar cor. */
+function dobrar(texto, largura, recuo = '') {
+    const palavras = String(texto).split(/\s+/).filter(Boolean);
+    if (!palavras.length) return [''];
+    const fora = [];
+    let linha = '';
+    for (const p of palavras) {
+        const teste = linha ? linha + ' ' + p : p;
+        if (visibleWidth(teste) + visibleWidth(recuo) > largura && linha) {
+            fora.push(linha);
+            linha = p;
+        } else {
+            linha = teste;
+        }
+    }
+    if (linha) fora.push(linha);
+    return fora;
+}
+
+/**
+ * O texto inteiro, pronto para a tela.
+ *
+ * @param {string} texto      o Markdown
+ * @param {number} largura    colunas úteis
+ * @returns {string[]}        as linhas, já com cor
+ */
+function renderizar(texto, largura = 80) {
+    const w = Math.max(24, Number(largura) || 80);
+    const linhas = String(texto == null ? '' : texto).split('\n');
+    const fora = [];
+
+    let i = 0;
+    while (i < linhas.length) {
+        const linha = linhas[i];
+
+        const cerca = linha.match(CERCA);
+        if (cerca) {
+            const fim = cerca[1];
+            const dentro = [];
+            i++;
+            while (i < linhas.length && !linhas[i].trim().startsWith(fim)) { dentro.push(linhas[i]); i++; }
+            i++;                                     // pula a cerca de baixo
+            fora.push(...blocoDeCodigo(dentro, cerca[2], w));
+            continue;
+        }
+
+        if (LINHA_TABELA.test(linha)) {
+            const bloco = [];
+            while (i < linhas.length && LINHA_TABELA.test(linhas[i])) { bloco.push(linhas[i]); i++; }
+            // Uma linha só entre barras não é tabela: é texto com barra.
+            if (bloco.length >= 2) { fora.push(...tabela(bloco, w)); continue; }
+            fora.push(inline(bloco[0]));
+            continue;
+        }
+
+        if (REGUA.test(linha)) { fora.push(c.dim('─'.repeat(Math.min(w, 60)))); i++; continue; }
+
+        const titulo = linha.match(TITULO);
+        if (titulo) {
+            const nivel = titulo[1].length;
+            const texto1 = stripAnsi(inline(titulo[2]));
+            fora.push('');
+            fora.push(nivel === 1 ? c.bold(c.brand(texto1.toUpperCase())) : c.bold(c.white(texto1)));
+            if (nivel === 1) fora.push(c.dim('─'.repeat(Math.min(w, visibleWidth(texto1)))));
+            i++;
+            continue;
+        }
+
+        const tarefa = linha.match(TAREFA);
+        if (tarefa) {
+            const marca = /[xX]/.test(tarefa[2]) ? c.ok('✔') : c.dim('○');
+            fora.push(...dobrarItem(tarefa[1] + marca + ' ', inline(tarefa[3]), w));
+            i++;
+            continue;
+        }
+
+        const numerada = linha.match(NUMERADA);
+        if (numerada) {
+            fora.push(...dobrarItem(numerada[1] + c.brand(numerada[2] + '.') + ' ', inline(numerada[4]), w));
+            i++;
+            continue;
+        }
+
+        const marcador = linha.match(MARCADOR);
+        if (marcador) {
+            // O ponto acompanha o nível: subitem não pode ter a mesma marca do
+            // item de cima, ou a hierarquia some.
+            const nivel = Math.floor(marcador[1].length / 2);
+            const ponto = [c.brand('•'), c.brand('◦'), c.brand('▪')][Math.min(nivel, 2)];
+            fora.push(...dobrarItem(marcador[1] + ponto + ' ', inline(marcador[3]), w));
+            i++;
+            continue;
+        }
+
+        const citacao = linha.match(CITACAO);
+        if (citacao) {
+            for (const l of dobrar(inline(citacao[1]), w - 4)) fora.push(c.dim('▏ ') + c.muted(l));
+            i++;
+            continue;
+        }
+
+        if (!linha.trim()) { fora.push(''); i++; continue; }
+
+        for (const l of dobrar(inline(linha), w)) fora.push(l);
+        i++;
+    }
+
+    // Linha em branco no fim é espaço morto no terminal.
+    while (fora.length && !fora[fora.length - 1].trim()) fora.pop();
+    return fora;
+}
+
+/** Item de lista: a primeira linha leva a marca, as seguintes se alinham a ela. */
+function dobrarItem(marca, conteudo, largura) {
+    const recuo = ' '.repeat(visibleWidth(marca));
+    const partes = dobrar(conteudo, largura - visibleWidth(marca));
+    return partes.map((p, i) => (i === 0 ? marca : recuo) + p);
+}
+
+/**
+ * O desenhador de FLUXO: recebe a resposta em pedaços e devolve o que já dá
+ * para mostrar.
+ *
+ * A resposta do chat chega em dezenas de pedaços, e esperar o fim para
+ * formatar deixaria a tela parada até tudo chegar. Quase tudo aqui se resolve
+ * por linha, então a linha é a unidade: fechou, sai formatada.
+ *
+ * As exceções são os blocos que só fazem sentido inteiros — a cerca de código
+ * e a tabela. Enquanto um deles está aberto, as linhas ficam retidas; elas
+ * saem juntas quando ele fecha. É o comportamento certo: meia tabela na tela
+ * é pior que a tabela um segundo depois.
+ */
+function fluxo(largura = 80) {
+    let resto = '';
+    let retido = [];
+    let dentroDaCerca = false;
+    let fimDaCerca = '';
+
+    const soltar = () => {
+        if (!retido.length) return [];
+        const saida = renderizar(retido.join('\n'), largura);
+        retido = [];
+        return saida;
+    };
+
+    return {
+        /** Devolve as linhas prontas para escrever agora. */
+        pedaco(texto) {
+            resto += String(texto == null ? '' : texto);
+            const partes = resto.split('\n');
+            resto = partes.pop();                 // a última fica para a próxima
+            const fora = [];
+            for (const linha of partes) {
+                const cerca = linha.match(CERCA);
+                if (dentroDaCerca) {
+                    retido.push(linha);
+                    if (linha.trim().startsWith(fimDaCerca)) { dentroDaCerca = false; fora.push(...soltar()); }
+                    continue;
+                }
+                if (cerca) { dentroDaCerca = true; fimDaCerca = cerca[1]; retido.push(linha); continue; }
+                if (LINHA_TABELA.test(linha)) { retido.push(linha); continue; }
+                // Saiu da tabela: agora ela está inteira.
+                if (retido.length) fora.push(...soltar());
+                fora.push(...renderizar(linha, largura));
+            }
+            return fora;
+        },
+        /** O que sobrou quando a resposta terminou. */
+        fim() {
+            const pendente = [...retido, ...(resto ? [resto] : [])];
+            retido = []; resto = ''; dentroDaCerca = false;
+            return pendente.length ? renderizar(pendente.join('\n'), largura) : [];
+        },
+    };
+}
+
+module.exports = { renderizar, fluxo, inline, tabela, dobrar, pintarCodigo, blocoDeCodigo };

package/lib/pasta.js

@@ -64,16 +64,27 @@ function detectarPasta(texto) {
     const s = String(texto || '');
     if (!s.trim()) return null;
 
-    // 1. Caminho explícito — `~/...` ou absoluto com pelo menos dois segmentos.
-    //    Um `/algo` solto não conta: seria confundido com comando (`/dir`).
-    const explicito = s.match(new RegExp(`(?:^|\\s)(~[${CARACTERES_DE_CAMINHO}]*|/[${CARACTERES_DE_CAMINHO}]+/[${CARACTERES_DE_CAMINHO}]*)`));
+    /* 1. Caminho explícito — `~/...`, absoluto unix com pelo menos dois
+          segmentos, ou o caminho do Windows com letra de unidade.
+          Um `/algo` solto não conta: seria confundido com comando (`/dir`).
+
+          O ramo do Windows (`C:\\Users\\joel\\loja`) não existia, e o dois-pontos
+          NÃO pode entrar em CARACTERES_DE_CAMINHO para resolver isso: ali ele
+          estragaria outros casamentos, como "veja isto: src/app", onde o
+          dois-pontos é pontuação da frase e não faz parte do caminho. Por isso
+          a unidade é um padrão à parte, ancorado na forma "letra + : + barra". */
+    const DRIVE_WIN = `[A-Za-z]:[\\\\/][${CARACTERES_DE_CAMINHO}]*`;
+    const explicito = s.match(new RegExp(`(?:^|\\s)(${DRIVE_WIN}|~[${CARACTERES_DE_CAMINHO}]*|/[${CARACTERES_DE_CAMINHO}]+/[${CARACTERES_DE_CAMINHO}]*)`));
     if (explicito) {
         const bruto = limpar(explicito[1]);
         if (bruto && !TEM_EXTENSAO.test(bruto)) return bruto;
     }
 
     // 2. Marca explícita de pasta.
-    const marcado = s.match(new RegExp(`\\b(?:pasta|diret[óo]rio|dir)\\s+(?:d[eoa]s?\\s+|no\\s+|na\\s+|em\\s+)?["'\`]?([${CARACTERES_DE_CAMINHO}]+)["'\`]?`, 'i'));
+    // A unidade do Windows entra aqui também: sem ela, "abre a pasta
+    // C:\\Users\\joel\\loja" casava só o "C" e o agente ia trabalhar numa pasta
+    // chamada "C".
+    const marcado = s.match(new RegExp(`\\b(?:pasta|diret[óo]rio|dir)\\s+(?:d[eoa]s?\\s+|no\\s+|na\\s+|em\\s+)?["'\`]?(${DRIVE_WIN}|[${CARACTERES_DE_CAMINHO}]+)["'\`]?`, 'i'));
     if (marcado) {
         const bruto = limpar(marcado[1]);
         if (bruto && !TEM_EXTENSAO.test(bruto) && !NAO_E_NOME.has(bruto.toLowerCase())) return bruto;

package/lib/tools.js

@@ -7,6 +7,8 @@
 
 'use strict';
 
+const catalogo = require('./catalogo.js');
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -193,14 +195,43 @@ async function runInNewTerminal(command, cwd) {
     // mesmo tempo (osascript, cmd.exe, sh) — "command" continua livre de
     // propósito, é o próprio contrato desta tool (abrir terminal com um
     // comando de shell de verdade).
-    if (/["'`;&|$\\]/.test(pastaAlvo)) {
+    /* A CONTRABARRA NÃO PODE ENTRAR NESTA LISTA NO WINDOWS.
+       Ela estava, e com isso a tool NUNCA funcionou lá: a pasta de trabalho é
+       sempre C:\Users\<nome>\primocode\<projeto> (path.join no win32 usa "\"),
+       então TODO caminho casava e a resposta era "Pasta com caractere não
+       permitido" — culpando a pasta criada pelo próprio produto, antes de
+       tentar abrir terminal nenhum. "sobe o servidor" quebrava 100% das vezes.
+       A contrabarra só é perigosa onde ela é ESCAPE (sh, osascript); no cmd.exe
+       ela é separador de caminho e nada mais. */
+    const proibidos = p === 'win32' ? /["'`;&|%^<>\r\n]/ : /["'`;&|$\\\r\n]/;
+    if (proibidos.test(pastaAlvo)) {
         return { ok: false, error: `Pasta com caractere não permitido: ${pastaAlvo}` };
     }
     let cmd;
-    if (p === 'darwin') cmd = `osascript -e 'tell application "Terminal" to do script "cd ${pastaAlvo} && ${command}"'`;
-    else if (p === 'win32') cmd = `start cmd /k "cd /d ${pastaAlvo} && ${command}"`;
-    else cmd = `x-terminal-emulator -e "bash -c 'cd ${pastaAlvo} && ${command}; exec bash'"`;
-    const r = await runShell(cmd);
+    let pastaDoProcesso;
+    if (p === 'darwin') {
+        /* O Terminal.app é outro processo, já rodando: ele NÃO herda a pasta
+           daqui, então o `cd` tem de ir no script mesmo. O espaço é escapado
+           com contrabarra — "\\ " neste template vira "\ " dentro da string do
+           AppleScript, que é o escape que o shell entende. Sem isso, uma pasta
+           como ~/Documents/Meus Projetos virava dois argumentos e o cd falhava
+           calado: o terminal abria na pasta errada e o comando rodava no lugar
+           errado, que é pior que não abrir. */
+        cmd = `osascript -e 'tell application "Terminal" to do script "cd ${pastaAlvo.replace(/ /g, '\\\\ ')} && ${command}"'`;
+    } else if (p === 'win32') {
+        // Aspas em volta do caminho: "C:\Users\Joel Silva\..." é comum, e sem
+        // elas o cmd corta no espaço. A aspa dupla já está barrada acima, então
+        // não há como sair delas.
+        cmd = `start cmd /k "cd /d "${pastaAlvo}" && ${command}"`;
+    } else {
+        /* No Linux o terminal é filho DESTE processo e herda a pasta — então
+           o caminho não precisa entrar na string de shell nenhuma. É a solução
+           mais segura das três: o que não é interpolado não pode ser mal
+           escapado. */
+        cmd = `x-terminal-emulator -e "bash -c '${command}; exec bash'"`;
+        pastaDoProcesso = pastaAlvo;
+    }
+    const r = await runShell(cmd, 60000, pastaDoProcesso);
     return r.ok ? { ok: true, opener: cmd.split(' ')[0] } : { ok: false, error: r.stderr || 'falhou' };
 }
 
@@ -568,7 +599,25 @@ async function despachar(name, args, ctx) {
                 });
 
             default:
-                return { ok: false, error: `Tool não implementada: ${name}` };
+                /* O MODELO PRECISA CONSEGUIR SE CORRIGIR AQUI.
+                   "Tool não implementada: studio_criar" não diz o que existe,
+                   e o que acontecia era o agente desistir e responder ao
+                   usuário que a ferramenta necessária "não está disponível".
+                   Dizendo QUAIS existem — e a mais parecida — ele chama a
+                   certa na volta seguinte, na mesma tarefa.
+
+                   Isto é rede, não conserto: a causa é a lista do servidor
+                   divergir do catálogo daqui, e ela se conserta lá. Mas a rede
+                   é o que separa uma tarefa que se recupera de uma que morre
+                   com o usuário esperando. */
+                return {
+                    ok: false,
+                    error: `A ferramenta "${name}" não existe.`,
+                    parecidas: catalogo.parecidasCom(name),
+                    comoResolver: 'chame uma das ferramentas que existem de verdade — as "parecidas" '
+                        + 'acima são as de nome mais próximo. Não invente nome de ferramenta, e não '
+                        + 'desista da tarefa por causa disto.',
+                };
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Requer conta Conecta Primo AI (Premium ou Super). Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/primocode.js",
-    "test": "node test/tools.test.js && node test/ui.test.js && node test/entrada.test.js && node test/transparencia.test.js && node test/permissao.test.js && node test/skills.test.js && node test/estudio.test.js && node test/voz.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/pipeline.test.js && node test/app.test.js && node test/aplicativo.test.js && node test/conta.test.mjs && node test/nuvem.test.js && node test/prazo.test.js && node test/primeira-vez.test.js && node test/janela.test.js && node test/pareamento.test.js && node test/fala.test.js && node test/especialistas.test.js && node test/empurrao.test.js"
+    "test": "node test/tools.test.js && node test/ui.test.js && node test/entrada.test.js && node test/transparencia.test.js && node test/permissao.test.js && node test/skills.test.js && node test/estudio.test.js && node test/voz.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/pipeline.test.js && node test/app.test.js && node test/aplicativo.test.js && node test/conta.test.mjs && node test/nuvem.test.js && node test/prazo.test.js && node test/primeira-vez.test.js && node test/janela.test.js && node test/pareamento.test.js && node test/fala.test.js && node test/especialistas.test.js && node test/empurrao.test.js && node test/terminal-novo.test.js && node test/markdown.test.js"
   },
   "engines": {
     "node": ">=18.17.0"

package/studio/pessoa.py

@@ -36,10 +36,30 @@ Uso:
 
 import argparse
 import json
+import shutil
+import os
 import subprocess
 import sys
 
 
+def achar_ffmpeg():
+    """Onde está o ffmpeg — pelo PATH, e nos lugares onde ele costuma cair.
+
+    O PATH de um processo aberto pela interface gráfica não é o PATH do
+    terminal: no macOS um app aberto pelo ícone não enxerga /opt/homebrew/bin,
+    onde o Homebrew instala. Procurar nos lugares conhecidos evita um "não
+    achei" para quem tem o programa instalado.
+    """
+    achado = shutil.which("ffmpeg")
+    if achado:
+        return achado
+    for c in ("/opt/homebrew/bin/ffmpeg", "/usr/local/bin/ffmpeg", "/usr/bin/ffmpeg",
+              r"C:\Program Files\ffmpeg\bin\ffmpeg.exe"):
+        if os.path.exists(c):
+            return c
+    return None
+
+
 def faltando():
     """O que precisa estar instalado, e não está."""
     falta = []
@@ -76,8 +96,20 @@ def recortar(entrada, saida, suavizar=7, encolher=2, limiar=0.6):
 
     # VP9 num .webm é o formato de vídeo com transparência que o Chromium do
     # Remotion abre — e é o Chromium dele que vai desenhar isto.
+    # O ffmpeg pelo nome cru estoura FileNotFoundError, e o que chega ao
+    # usuário é o traceback do Python — que não diz o que instalar. Pior: aqui
+    # o vídeo já foi ABERTO e a segmentação está prestes a começar, então a
+    # falha aparece depois da espera, não antes dela.
+    binario = achar_ffmpeg()
+    if not binario:
+        captura.release()
+        return {"ok": False,
+                "error": "o recorte de pessoa precisa do ffmpeg, e não achei nenhum nesta máquina.",
+                "comoResolver": "macOS: brew install ffmpeg · Linux: sudo apt install ffmpeg · "
+                                "Windows: winget install ffmpeg"}
+
     escritor = subprocess.Popen(
-        ["ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
+        [binario, "-hide_banner", "-loglevel", "error", "-y",
          "-f", "rawvideo", "-pix_fmt", "bgra",
          "-s", f"{largura}x{altura}", "-r", str(fps), "-i", "-",
          "-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-b:v", "3M",

package/voz/primo_voz/__main__.py

@@ -65,6 +65,44 @@ def avisar(texto: str) -> None:
     sys.stderr.flush()
 
 
+# O PowerShell que toca MP3 no Windows. MediaPlayer é assíncrono: Play()
+# devolve na hora, então é preciso esperar a duração — e esperar com teto, ou
+# um Open que falha deixaria a thread da fala pendurada para sempre.
+def motivo_da_narracao(r) -> str:
+    """O que o narrar.py disse que houve — em vez do código de saída.
+
+    Ele responde JSON em stdout, com "error" e "comoResolver". Quando esse
+    JSON não vem (o processo morreu antes de escrever), sobra o stderr, que
+    ainda diz mais que "returned non-zero exit status 1".
+    """
+    try:
+        d = json.loads((r.stdout or b"").decode("utf-8", "replace"))
+        if isinstance(d, dict) and d.get("error"):
+            comoResolver = d.get("comoResolver") or ""
+            return "não deu para gerar a voz: " + str(d["error"]) + (
+                " — " + str(comoResolver) if comoResolver else "")
+    except Exception:
+        pass
+    erro = (r.stderr or b"").decode("utf-8", "replace").strip()
+    ultima = erro.splitlines()[-1] if erro else ""
+    return "não deu para gerar a voz" + (f": {ultima[:300]}" if ultima else
+                                         f" (o narrar.py saiu com {r.returncode})")
+
+
+PS_TOCAR_MP3 = (
+    "Add-Type -AssemblyName PresentationCore; "
+    "$p = New-Object System.Windows.Media.MediaPlayer; "
+    "$p.Open([uri]'{arquivo}'); "
+    "$n = 0; "
+    "while (-not $p.NaturalDuration.HasTimeSpan -and $n -lt 100) "
+    "{{ Start-Sleep -Milliseconds 50; $n++ }}; "
+    "if (-not $p.NaturalDuration.HasTimeSpan) {{ exit 1 }}; "
+    "$p.Play(); "
+    "Start-Sleep -Seconds $p.NaturalDuration.TimeSpan.TotalSeconds; "
+    "$p.Close()"
+)
+
+
 class Voz:
     """A costura: microfone → transcrição → Node → voz → microfone."""
 
@@ -227,13 +265,17 @@ class Voz:
 
         mp3 = Path(tempfile.gettempdir()) / f"primo-voz-{int(time.time() * 1000)}.mp3"
         narrar = AQUI.parent.parent / "studio" / "narrar.py"
-        try:
-            subprocess.run(
-                [sys.executable, str(narrar), "falar", "--texto", limpo,
-                 "--saida", str(mp3), "--voz", self.voz],
-                capture_output=True, timeout=180, check=True)
-        except Exception as e:
-            avisar(f"não deu para gerar a voz: {e}")
+        # O narrar.py IMPRIME um JSON dizendo o que faltou e como resolver
+        # ("instale o edge-tts com… "). Com check=True isso virava uma
+        # CalledProcessError cujo texto é "Command '[...]' returned non-zero
+        # exit status 1" — e era ISSO que chegava ao usuário, com o conselho
+        # útil jogado fora dentro do capture_output. Agora a saída é lida.
+        r = subprocess.run(
+            [sys.executable, str(narrar), "falar", "--texto", limpo,
+             "--saida", str(mp3), "--voz", self.voz],
+            capture_output=True, timeout=180)
+        if r.returncode != 0 or not mp3.exists():
+            avisar(motivo_da_narracao(r))
             return
 
         self._falando = True
@@ -260,8 +302,15 @@ class Voz:
         if sys.platform == "darwin":
             tentativas.append(["afplay", str(arquivo)])
         elif sys.platform == "win32":
-            tentativas.append(["powershell", "-c",
-                               f"(New-Object Media.SoundPlayer '{arquivo}').PlaySync()"])
+            # Media.SoundPlayer NÃO toca MP3 — ele só lê WAV, e o que o
+            # narrar.py entrega é MP3. Era a primeira tentativa da fila, e
+            # levantava exceção sempre; como o laço abaixo aceitava qualquer
+            # processo que tivesse CONSEGUIDO INICIAR, ele dava por tocado e
+            # voltava. Resultado: o modo voz era MUDO no Windows, sem nenhum
+            # aviso — a orb piscava "falando" e não saía som nenhum.
+            # MediaPlayer decodifica MP3; a espera é limitada para não travar
+            # a thread se o Open falhar.
+            tentativas.append(["powershell", "-NoProfile", "-Command", PS_TOCAR_MP3.format(arquivo=arquivo)])
         tentativas += [
             ["ffplay", "-nodisp", "-autoexit", "-loglevel", "quiet", str(arquivo)],
             ["mpg123", "-q", str(arquivo)],
@@ -271,7 +320,7 @@ class Voz:
         for cmd in tentativas:
             try:
                 p = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-            except FileNotFoundError:
+            except (FileNotFoundError, OSError):
                 continue
             while p.poll() is None:
                 if self._parar_fala.is_set() or not self._vivo:
@@ -279,10 +328,19 @@ class Voz:
                         p.terminate()
                     except Exception:
                         pass
-                    return
+                    return          # calado de propósito: falaram por cima
                 time.sleep(0.05)
-            return
-        avisar("não achei um tocador de áudio (ffplay, mpg123, mpv ou afplay).")
+            if p.returncode == 0:
+                return
+            # INICIAR não é TOCAR. O tocador existia e falhou (formato que ele
+            # não lê, dispositivo de áudio ocupado): a fila continua. Sair aqui
+            # era o que transformava "o primeiro tocador não serve" em silêncio
+            # absoluto, com quatro alternativas por tentar logo abaixo.
+            continue
+        avisar("não achei um tocador de áudio que funcione neste computador."
+               + (" Instale o ffmpeg: winget install ffmpeg" if sys.platform == "win32"
+                  else " Instale o ffmpeg: brew install ffmpeg" if sys.platform == "darwin"
+                  else " Instale o ffmpeg: sudo apt install ffmpeg"))
 
     # ── ciclo de vida ────────────────────────────────────────────────────
     def parar(self) -> None: