primocode 9.8.0-beta.2 → 9.8.0-beta.21

package/lib/local/entrada.js

@@ -17,7 +17,7 @@
  *
  * ── A IDEIA ──────────────────────────────────────────────────────────────
  * Ninguém precisa das 45 ferramentas para fazer um slide. Quem pede um vídeo
- * não usa `desktop_click`; quem conserta um bug não usa `studio_criar`. Então
+ * não usa `desktop_click`; quem conserta um bug não usa `estudio_render`. Então
  * cada pedido leva só o que aquele pedido pode usar — ferramentas E seções do
  * prompt — e o que sobra do orçamento vira espaço para a conversa.
  *
@@ -74,10 +74,19 @@ const GRUPOS = [
     },
     {
         nome: 'estudio',
-        tools: ['studio_manual', 'studio_spec', 'studio_criar', 'studio_ler',
-            'studio_atualizar', 'studio_versoes', 'studio_listar', 'studio_midia'],
-        // O que o estúdio produz, e os apps que ele substitui.
-        gatilho: /\b(slides?|apresenta[çc][ãa]o|deck|v[íi]deo|reels?|anima[çc][ãa]o|post|banner|capa|thumbnail|arte|cartaz|logo|planilha|tabela|or[çc]amento|documento|relat[óo]rio|artigo|proposta|contrato|diagrama|fluxograma|organograma|mapa mental|narra[çc][ãa]o|trilha|est[úu]dio|canva|powerpoint|keynote|word|docs|excel|sheets|photoshop|figma|capcut|premiere|miro)\b/i,
+        tools: ['estudio_projeto', 'estudio_plano', 'estudio_midia', 'estudio_narrar',
+            'estudio_render', 'estudio_site', 'planejar_producao'],
+        // O que o estúdio produz, e os apps que ele substitui. Documento,
+        // planilha e PDF saíram: o Estúdio novo faz vídeo, slides e arte, e o
+        // resto é arquivo escrito com código.
+        gatilho: /\b(slides?|apresenta[çc][ãa]o|deck|v[íi]deo|reels?|anima[çc][ãa]o|motion|vinheta|teaser|an[úu]ncio|post|banner|capa|thumbnail|arte|cartaz|narra[çc][ãa]o|trilha|legenda|grava[çc][ãa]o|est[úu]dio|canva|powerpoint|keynote|photoshop|figma|capcut|premiere)\b/i,
+    },
+    {
+        /* A GRAVAÇÃO do usuário é outra ferramenta, e só entra quando o pedido
+           fala dela: "faz um vídeo" não precisa cortar silêncio de ninguém. */
+        nome: 'gravacao',
+        tools: ['estudio_video'],
+        gatilho: /\b(grava[çc][ãa]o|gravei|filmagem|filmei|meu v[íi]deo|edit\w* (o |a |meu |minha |esse |essa |este |esta )?(v[íi]deo|grava[çc][ãa]o)|\.mp4|\.mov|legendas?|cort(a|ar|e) (o )?sil[êe]ncio|recort(a|ar|e) (a )?pessoa|transcrev\w*|importa\w* (o )?v[íi]deo)\b/i,
     },
     {
         nome: 'navegador',
@@ -118,7 +127,7 @@ const GRUPOS = [
            quando o pedido fala do arquivo — é o que mantém o pedido de vídeo
            dentro do teto do minuto (medido: ela custa ~180 tokens). */
         nome: 'exportar',
-        tools: ['studio_exportar'],
+        tools: ['estudio_render'],
         gatilho: /\b(mp4|webm|baix[ae]r?|download|exporta\w*|salv[ae]r? (o )?v[íi]deo|arquivo (do|de) v[íi]deo|me manda o v[íi]deo|manda o arquivo|renderiza\w*)\b/i,
     },
     {
@@ -196,7 +205,8 @@ function jaAprendeu(messages) {
         if (m && m.role === 'tool' && nomePorId.has(m.tool_call_id)) feitas.add(nomePorId.get(m.tool_call_id));
     }
     const dispensaveis = new Set();
-    if (feitas.has('studio_spec') || feitas.has('studio_manual')) dispensaveis.add('estudio');
+    // O Estúdio novo não tem spec para ler: a seção dele é o único mapa do
+    // fluxo, e fica até o fim.
     if (feitas.has('pesquisar_referencia')) dispensaveis.add('pesquisa');
     return dispensaveis;
 }
@@ -253,7 +263,7 @@ function relatorio({ prompt, ferramentas, messages }) {
 // O CLI já protege as mesmas mensagens antes de mandar (lib/repeticao.js), mas
 // quem falava por último aqui era `caberNoTeto`, que não sabia disso e cortava
 // assim mesmo. Dois compactadores brigando, e o do servidor ganhava.
-const REFERENCIAS = new Set(['studio_manual', 'studio_spec']);
+const REFERENCIAS = new Set(['planejar_producao', 'estudio_site']);
 
 // Referência tem teto GENEROSO, não infinito.
 //

package/lib/local/motor-cli.js

@@ -37,7 +37,7 @@ function motorDe(id) {
 function perguntar(id, texto) {
     if (id === 'codex') return String(motorDe('codex').chamarCodex(texto) || '').trim();
     const claude = motorDe('claude-code');
-    const saida = execFileSync('claude', ['-p', '--output-format', 'json', ...claude.argsDoModelo()], {
+    const saida = execFileSync('claude', ['-p', '--output-format', 'json', ...claude.argsDoMotor()], {
         encoding: 'utf-8', timeout: 120000, input: texto, maxBuffer: 8 * 1024 * 1024, ...SEM_APARECER,
     });
     try { return String(JSON.parse(saida).result || '').trim(); } catch { return String(saida || '').trim(); }

package/lib/mencoes.js

@@ -0,0 +1,98 @@
+// O que a pessoa TRAZ para o pedido, além do texto: as instruções do projeto
+// (PRIMO.md, AGENTS.md, CLAUDE.md) e os arquivos citados com @.
+//
+// Ideia tirada do Claude Code (CLAUDE.md, @arquivo, /init) e do Codex
+// (AGENTS.md). Quem já escreveu um AGENTS.md para outro agente não deveria ter
+// de escrever de novo para o PrimoCode — então os três nomes valem.
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/* ── INSTRUÇÕES DO PROJETO ───────────────────────────────────────────────
+ * Só o PRIMEIRO que existir, na ordem abaixo: um repo com AGENTS.md e
+ * CLAUDE.md quase sempre tem o mesmo texto nos dois (um aponta pro outro), e
+ * mandar os dois é pagar duas vezes pela mesma regra. O PRIMO.md vem antes
+ * porque é o que a pessoa escreveu PARA nós. */
+const NOMES_INSTRUCOES = ['PRIMO.md', 'AGENTS.md', 'CLAUDE.md'];
+const LIMITE_INSTRUCOES = 6000;
+
+// A cabeça fica, o rabo sai: é no começo que se escreve o que mais importa.
+function cortar(texto, limite) {
+    if (texto.length <= limite) return texto;
+    return texto.slice(0, limite).trimEnd() + '\n(cortado)';
+}
+
+function lerSeExiste(arquivo) {
+    try {
+        if (!fs.statSync(arquivo).isFile()) return '';
+        return fs.readFileSync(arquivo, 'utf-8');
+    } catch { return ''; }
+}
+
+/** O texto que entra no contexto, ou '' se não há instrução nenhuma. */
+function instrucoesDoProjeto(projectDir, limite = LIMITE_INSTRUCOES) {
+    const partes = [];
+    // HOME lido na hora, não na carga do módulo: o teste troca a casa.
+    const global = lerSeExiste(path.join(os.homedir(), '.primocode', 'PRIMO.md'));
+    if (global.trim()) partes.push(`[~/.primocode/PRIMO.md — suas instruções para todo projeto]\n${cortar(global, limite)}`);
+    if (projectDir) {
+        for (const nome of NOMES_INSTRUCOES) {
+            const texto = lerSeExiste(path.join(projectDir, nome));
+            if (!texto.trim()) continue;
+            partes.push(`[${nome} — instruções deste projeto: siga]\n${cortar(texto, limite)}`);
+            break;
+        }
+    }
+    return partes.join('\n\n');
+}
+
+/* ── @ARQUIVO ────────────────────────────────────────────────────────────
+ * O @ só conta no começo de uma palavra: "joel@x.com" e "@" solto passam
+ * direto. E só vira anexo o que existe DENTRO da pasta do projeto — "@../../
+ * .ssh/id_rsa" não pode mandar a chave de ninguém para o modelo. O que não
+ * resolve fica como está no texto: pode ser um @usuario de verdade. */
+const LIMITE_ARQUIVO = 40 * 1024;
+const LIMITE_TOTAL = 120 * 1024;
+const RE_MENCAO = /(^|[\s(])@(?:"([^"]+)"|([^\s"]+))/g;
+
+function pareceBinario(abs) {
+    let fd;
+    try {
+        fd = fs.openSync(abs, 'r');
+        const buf = Buffer.alloc(8000);
+        const lidos = fs.readSync(fd, buf, 0, buf.length, 0);
+        return buf.subarray(0, lidos).includes(0);
+    } catch { return true; }
+    finally { if (fd !== undefined) try { fs.closeSync(fd); } catch { /* já fechado */ } }
+}
+
+function mencoes(texto, projectDir, limites = {}) {
+    const porArquivo = limites.porArquivo || LIMITE_ARQUIVO;
+    const total = limites.total || LIMITE_TOTAL;
+    const arquivos = [];
+    const ignorados = [];
+    if (!texto || !projectDir) return { arquivos, ignorados };
+    const raiz = path.resolve(projectDir);
+    const vistos = new Set();
+    let soma = 0;
+    for (const m of String(texto).matchAll(RE_MENCAO)) {
+        // Pontuação colada ("veja @index.html.") é da frase, não do nome.
+        const bruto = m[2] || m[3].replace(/[.,;:!?)\]]+$/, '');
+        if (!bruto) continue;
+        const abs = path.resolve(raiz, bruto);
+        const rel = path.relative(raiz, abs);
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        let st;
+        try { st = fs.statSync(abs); } catch { continue; }
+        if (!st.isFile() || vistos.has(abs)) continue;
+        vistos.add(abs);
+        if (st.size > porArquivo) { ignorados.push({ rel, motivo: `grande demais (limite ${Math.round(porArquivo / 1024)} KB)` }); continue; }
+        if (pareceBinario(abs)) { ignorados.push({ rel, motivo: 'arquivo binário' }); continue; }
+        if (soma + st.size > total) { ignorados.push({ rel, motivo: `passou do total de ${Math.round(total / 1024)} KB` }); continue; }
+        soma += st.size;
+        arquivos.push({ rel, abs, bytes: st.size });
+    }
+    return { arquivos, ignorados };
+}
+
+module.exports = { mencoes, instrucoesDoProjeto, NOMES_INSTRUCOES, LIMITE_INSTRUCOES, LIMITE_ARQUIVO, LIMITE_TOTAL };

package/lib/offline.js

@@ -0,0 +1,168 @@
+/**
+ * offline.js — o primocode-server rodando AQUI, no computador da pessoa.
+ *
+ *   "Como eu não tenho acesso ao Railway, enquanto isso eu posso testar com o
+ *    projeto rodando localmente, chamando as APIs pelo meu computador."
+ *   (24/09/2026)
+ *
+ * O /offline sobe o servidor da pasta primocode-server com as MESMAS chaves
+ * que o Render usa (coladas em ~/.primocode/servidor.env) e aponta o CLI para
+ * ele até a sessão acabar. É temporário: serve para testar o servidor novo
+ * antes de ele ir para produção.
+ *
+ * "Offline" é o nome que o pedido deu, e ele mente um pouco: as IAs continuam
+ * na internet. O que sai do caminho é o servidor de produção.
+ *
+ * ── O QUE NUNCA APARECE ──────────────────────────────────────────────────
+ * O valor de uma chave. Mostram-se só os NOMES das variáveis que o arquivo
+ * tem, o bastante para ver o que falta.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const { spawn } = require('child_process');
+
+const PORTA = Number(process.env.PRIMOCODE_OFFLINE_PORTA || 3190);
+const CASA = path.join(os.homedir(), '.primocode');
+const ARQUIVO_ENV = path.join(CASA, 'servidor.env');
+const ARQUIVO_LOG = path.join(CASA, 'servidor-local.log');
+
+// As variáveis que o primocode-server lê. As de chave vêm primeiro: sem pelo
+// menos uma delas, o servidor sobe mas não tem com quem falar.
+const CHAVES = ['GROQ_API_KEY', 'OPENROUTER_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'COHERE_API_KEY', 'HF_TOKEN', 'HUGGINGFACE_API_KEY', 'PG_GATEWAY_API_KEY'];
+const OUTRAS = ['PG_GATEWAY_BASE_URL', 'CONECTA_API', 'PRIMOCODE_TOKEN', 'REQUIRE_TOKEN', 'RATE_LIMIT_PER_HOUR'];
+
+const MODELO_ENV = `# As chaves do primocode-server rodando no seu computador (/offline).
+# Copie do Render: o serviço primocode-server → Environment. Uma por linha,
+# NOME=valor, sem aspas. Este arquivo é só seu: não mande para ninguém.
+#
+${CHAVES.map((k) => `# ${k}=`).join('\n')}
+#
+${OUTRAS.map((k) => `# ${k}=`).join('\n')}
+`;
+
+/** Lê um .env simples: NOME=valor, # comenta, aspas em volta saem. */
+function lerEnv(texto) {
+    const env = {};
+    for (const linha of String(texto || '').split(/\r?\n/)) {
+        const m = linha.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+        if (!m) continue;
+        let valor = m[2];
+        if (/^(['"]).*\1$/.test(valor)) valor = valor.slice(1, -1);
+        if (valor) env[m[1]] = valor;
+    }
+    return env;
+}
+
+/** O arquivo de chaves: cria o modelo (vazio, 600) na primeira vez. */
+function prepararEnv(arquivo = ARQUIVO_ENV) {
+    let criado = false;
+    if (!fs.existsSync(arquivo)) {
+        fs.mkdirSync(path.dirname(arquivo), { recursive: true });
+        fs.writeFileSync(arquivo, MODELO_ENV, { mode: 0o600 });
+        criado = true;
+    }
+    const env = lerEnv(fs.readFileSync(arquivo, 'utf8'));
+    return { arquivo, criado, env, nomes: Object.keys(env), temChave: CHAVES.some((k) => env[k]) };
+}
+
+function ehServidor(dir) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        return pkg.name === 'primocode-server' && fs.existsSync(path.join(dir, 'server.js'));
+    } catch { return false; }
+}
+
+/** Onde está a pasta do primocode-server. A primeira que existir ganha. */
+function acharServidor({ pedido = '', raizCli = path.join(__dirname, '..') } = {}) {
+    const candidatos = [
+        pedido,
+        process.env.PRIMOCODE_SERVER_DIR,
+        path.join(raizCli, '..', 'primocode-server'),
+        path.join(os.homedir(), 'Primocode CLI', 'primocode-server'),
+        path.join(os.homedir(), 'primocode-server'),
+    ].filter(Boolean).map((p) => path.resolve(p.replace(/^~(?=$|\/)/, os.homedir())));
+    return candidatos.find(ehServidor) || null;
+}
+
+/** GET /health; devolve o JSON ou null. */
+function saude(url, espera = 1500) {
+    return new Promise((resolve) => {
+        const req = http.get(url + '/health', { timeout: espera }, (res) => {
+            let corpo = '';
+            res.on('data', (d) => { corpo += d; });
+            res.on('end', () => { try { resolve(JSON.parse(corpo)); } catch { resolve(null); } });
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve(null));
+    });
+}
+
+let filho = null;
+
+/**
+ * Sobe o servidor (ou reaproveita um que já responde na porta).
+ * Devolve { ok, url, versao, reaproveitado } ou { ok: false, error, comoResolver }.
+ */
+async function ligar({ dir, env = {}, porta = PORTA, log = ARQUIVO_LOG, prazo = 20000 } = {}) {
+    const url = `http://localhost:${porta}`;
+    const ja = await saude(url);
+    if (ja && ja.status === 'ok') return { ok: true, url, versao: ja.version, reaproveitado: true };
+    if (!dir) {
+        return {
+            ok: false,
+            error: 'Não achei a pasta do primocode-server.',
+            comoResolver: 'clone o repo ao lado do primocode, ou diga onde ele está: /offline ~/caminho/primocode-server',
+        };
+    }
+    if (!fs.existsSync(path.join(dir, 'node_modules'))) {
+        return {
+            ok: false,
+            error: `O servidor em ${dir} ainda não tem as dependências.`,
+            comoResolver: `rode uma vez: cd "${dir}" && npm install`,
+        };
+    }
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    const saida = fs.openSync(log, 'a');
+    filho = spawn(process.execPath, ['server.js'], {
+        cwd: dir,
+        env: { ...process.env, ...env, PORT: String(porta) },
+        stdio: ['ignore', saida, saida],
+    });
+    let morreu = null;
+    filho.on('exit', (codigo) => { morreu = codigo; filho = null; });
+
+    const fim = Date.now() + prazo;
+    while (Date.now() < fim) {
+        if (morreu !== null) {
+            return { ok: false, error: `O servidor fechou sozinho (código ${morreu}).`, comoResolver: `veja o fim de ${log}` };
+        }
+        const h = await saude(url);
+        if (h && h.status === 'ok') return { ok: true, url, versao: h.version, reaproveitado: false };
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    desligar();
+    return { ok: false, error: `O servidor não respondeu em ${Math.round(prazo / 1000)}s.`, comoResolver: `veja o fim de ${log}` };
+}
+
+/** Desliga o servidor que ESTE processo subiu. Um reaproveitado fica de pé. */
+function desligar() {
+    if (!filho) return false;
+    try { filho.kill(); } catch {}
+    filho = null;
+    return true;
+}
+
+function ligado() { return Boolean(filho); }
+
+// O servidor não pode sobrar rodando quando o CLI fecha.
+process.on('exit', desligar);
+
+module.exports = {
+    PORTA, ARQUIVO_ENV, ARQUIVO_LOG, CHAVES,
+    lerEnv, prepararEnv, acharServidor, ehServidor, saude, ligar, desligar, ligado,
+};

package/lib/painel.js

@@ -0,0 +1,291 @@
+/**
+ * painel.js — o painel da direita da janela: a prévia do site e os arquivos.
+ *
+ *   "Remove a IDE ou deixa idêntico ao Codex."
+ *
+ * Antes isto era a PrimoCode IDE: árvore, EDITOR de código, prévia e chat. O
+ * editor saiu. Quem usa o PrimoCode não programa — um editor de código na
+ * cara dessa pessoa é uma porta para quebrar o que o agente fez, sem saber
+ * como voltar. O que ficou é o que ela usa de verdade: ver o site que está
+ * nascendo (Prévia) e olhar o que tem na pasta (Arquivos), só leitura.
+ *
+ * ── POR QUE MORA DENTRO DO SERVIDOR DA JANELA ────────────────────────────
+ * A janela (lib/app.js) já resolveu o difícil: 127.0.0.1, chave sorteada e o
+ * fluxo de eventos (SSE). Aqui só entram as rotas do painel (árvore, ler,
+ * prévia) e o vigia da pasta, que empurra "arquivo mudou" pelo MESMO fluxo —
+ * é o que faz a prévia recarregar enquanto o agente escreve.
+ *
+ * ── SEGURANÇA ────────────────────────────────────────────────────────────
+ *   · a chave do app.js vale aqui também (tudo mora em /api/);
+ *   · todo caminho é resolvido DENTRO da pasta do projeto — "../", caminho
+ *     absoluto e link simbólico que aponta para fora são recusados;
+ *   · nada aqui escreve no disco: sem editor, não há rota de salvar;
+ *   · a prévia roda num iframe sandbox SEM allow-same-origin, e o servidor
+ *     manda o mesmo sandbox no cabeçalho. O código da prévia foi escrito pelo
+ *     agente; se ele herdasse a origem da janela, poderia chamar /api/enviar
+ *     e dar ordens ao agente. Com origem opaca, o fetch dele sai com
+ *     `Origin: null` e o app.js recusa.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/* O que a árvore não mostra e o vigia não escuta. node_modules sozinho tem
+   dezenas de milhares de arquivos: listar travaria a janela, e vigiar faria
+   cada `npm install` virar uma avalanche de eventos. */
+const IGNORADOS = new Set(['node_modules', '.git', '.DS_Store', '.next', '.cache',
+    '__pycache__', '.venv', 'venv', '.turbo', '.parcel-cache']);
+const MAX_ITENS = 4000;
+const MAX_PROFUNDIDADE = 12;
+// 1 MB: acima disso o visualizador engasga, e arquivo desse tamanho num
+// projeto de iniciante é quase sempre gerado (bundle, dado).
+const MAX_LEITURA = 1024 * 1024;
+
+// ── caminhos ─────────────────────────────────────────────────────────────
+
+/* Resolve `relativo` dentro de `raiz`, ou devolve null.
+ *
+ * `path.relative` pega o "../" e o caminho absoluto; o `realpath` pega o link
+ * simbólico, que passa pelo primeiro teste com cara de arquivo de dentro e
+ * aponta para ~/.ssh. Caminho que ainda não existe é checado
+ * pela pasta onde vai nascer. */
+function dentro(raiz, relativo) {
+    if (typeof relativo !== 'string' || relativo.includes('\0')) return null;
+    // Absoluto é recusado de cara, e não "reinterpretado" como relativo:
+    // quem manda /etc/hosts quer o /etc/hosts, e ler <projeto>/etc/hosts
+    // no lugar seria uma surpresa. `C:\` e `\\servidor` também contam.
+    if (path.isAbsolute(relativo) || path.win32.isAbsolute(relativo)) return null;
+    const base = path.resolve(raiz);
+    const alvo = path.resolve(base, relativo);
+    if (!contido(base, alvo)) return null;
+    let real = base;
+    try { real = fs.realpathSync(base); } catch { return null; }
+    let existente = alvo;
+    while (!fs.existsSync(existente) && existente !== base) existente = path.dirname(existente);
+    try {
+        if (!contido(real, fs.realpathSync(existente))) return null;
+    } catch { return null; }
+    return alvo;
+}
+
+function contido(base, alvo) {
+    const rel = path.relative(base, alvo);
+    return rel === '' || (rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel));
+}
+
+function relativoDe(raiz, abs) {
+    return path.relative(raiz, abs).split(path.sep).join('/');
+}
+
+function ignorado(rel) {
+    return rel.split(/[/\\]/).some((p) => IGNORADOS.has(p));
+}
+
+// ── árvore ───────────────────────────────────────────────────────────────
+
+/* Lista plana, pastas antes de arquivos, em ordem alfabética. Plana porque a
+   página monta a árvore dela do jeito que quiser, e o teste confere sem ter de
+   descer em objetos aninhados. */
+function arvore(raiz) {
+    const itens = [];
+    let cortada = false;
+    function andar(dir, prof) {
+        if (prof > MAX_PROFUNDIDADE || cortada) return;
+        let entradas;
+        try { entradas = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+        entradas = entradas.filter((e) => !IGNORADOS.has(e.name));
+        entradas.sort((a, b) => (b.isDirectory() - a.isDirectory())
+            || a.name.localeCompare(b.name, 'pt-BR', { sensitivity: 'base' }));
+        for (const e of entradas) {
+            if (itens.length >= MAX_ITENS) { cortada = true; return; }
+            const abs = path.join(dir, e.name);
+            const rel = relativoDe(raiz, abs);
+            if (e.isDirectory()) {
+                itens.push({ caminho: rel, tipo: 'pasta' });
+                andar(abs, prof + 1);
+            } else if (e.isFile()) {
+                let tamanho = 0;
+                try { tamanho = fs.statSync(abs).size; } catch {}
+                itens.push({ caminho: rel, tipo: 'arquivo', tamanho });
+            }
+        }
+    }
+    andar(raiz, 0);
+    return { itens, cortada };
+}
+
+// ── ler ──────────────────────────────────────────────────────────────────
+
+/* Binário é o que tem byte zero nos primeiros 8 KB — o mesmo teste do git.
+   Mostrar um PNG como texto é uma tela de lixo que parece arquivo quebrado. */
+function ehBinario(buf) {
+    const n = Math.min(buf.length, 8000);
+    for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+    return false;
+}
+
+function ler(raiz, rel) {
+    const abs = dentro(raiz, rel);
+    if (!abs) return { status: 403, corpo: { ok: false, error: 'fora da pasta do projeto' } };
+    let st;
+    try { st = fs.statSync(abs); } catch { return { status: 404, corpo: { ok: false, error: 'não existe' } }; }
+    if (!st.isFile()) return { status: 400, corpo: { ok: false, error: 'não é arquivo' } };
+    const base = { ok: true, caminho: relativoDe(raiz, abs), tamanho: st.size, mtime: st.mtimeMs };
+    if (st.size > MAX_LEITURA) return { status: 200, corpo: Object.assign(base, { grande: true }) };
+    const buf = fs.readFileSync(abs);
+    if (ehBinario(buf)) return { status: 200, corpo: Object.assign(base, { binario: true }) };
+    return { status: 200, corpo: Object.assign(base, { conteudo: buf.toString('utf8') }) };
+}
+
+// ── prévia ───────────────────────────────────────────────────────────────
+
+const TIPOS = {
+    '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8', '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8', '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.ico': 'image/x-icon', '.txt': 'text/plain; charset=utf-8',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.mp4': 'video/mp4', '.webm': 'video/webm',
+    '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.md': 'text/plain; charset=utf-8',
+};
+
+/* Onde está a página de entrada do projeto. index.html na raiz é o caso de
+   quase todo pedido ("crie um site"); os kits de Vite e afins põem em public/
+   ou src/. Sem nenhum, a prévia diz isso em vez de mostrar um 404. */
+function entradaDaPrevia(raiz) {
+    for (const c of ['index.html', 'public/index.html', 'src/index.html', 'dist/index.html']) {
+        if (fs.existsSync(path.join(raiz, c))) return c;
+    }
+    return null;
+}
+
+function servirPrevia(raiz, rel, res) {
+    const abs = dentro(raiz, decodeURIComponent(rel || '') || 'index.html');
+    const alvo = abs && fs.existsSync(abs) && fs.statSync(abs).isDirectory() ? path.join(abs, 'index.html') : abs;
+    if (!alvo || !fs.existsSync(alvo)) {
+        res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+        return res.end('não encontrado');
+    }
+    res.writeHead(200, {
+        'Content-Type': TIPOS[path.extname(alvo).toLowerCase()] || 'application/octet-stream',
+        'Cache-Control': 'no-store',
+        // O mesmo sandbox do iframe, dito pelo servidor: vale até se alguém
+        // abrir o endereço da prévia fora da janela.
+        'Content-Security-Policy': 'sandbox allow-scripts allow-forms allow-modals allow-popups allow-pointer-lock',
+    });
+    fs.createReadStream(alvo).pipe(res);
+}
+
+// ── vigia ────────────────────────────────────────────────────────────────
+
+/* fs.watch recursivo existe no Mac e no Windows desde sempre e no Linux desde
+   o Node 20. Onde não existe, vigia só a raiz — a prévia de um index.html
+   continua acompanhando, que é o que mais importa.
+
+   Os eventos vêm em rajada (um write vira 2–3 avisos, um `npm run build` vira
+   centenas), então juntam-se por 150 ms e saem numa mensagem só. */
+function vigiar(raiz, aoMudar, espera = 150) {
+    const pendentes = new Set();
+    let timer = null;
+    const soltar = () => {
+        timer = null;
+        const lista = [...pendentes];
+        pendentes.clear();
+        if (lista.length) aoMudar(lista);
+    };
+    const anotar = (_tipo, nome) => {
+        if (!nome) return;
+        const rel = String(nome).split(path.sep).join('/');
+        if (ignorado(rel)) return;
+        pendentes.add(rel);
+        if (!timer) timer = setTimeout(soltar, espera);
+    };
+    let vigia;
+    try { vigia = fs.watch(raiz, { recursive: true }, anotar); } catch {
+        try { vigia = fs.watch(raiz, anotar); } catch { return () => {}; }
+    }
+    vigia.on('error', () => {});
+    return function parar() {
+        try { vigia.close(); } catch {}
+        if (timer) clearTimeout(timer);
+    };
+}
+
+// ── as rotas ─────────────────────────────────────────────────────────────
+
+/**
+ * Monta o painel num servidor do app.js.
+ *
+ * @param {object} op
+ * @param {()=>string} op.pasta   a pasta do projeto AGORA (o /dir muda ela)
+ * @param {(evento:string, dados:any)=>void} op.emitir  o fluxo SSE do app.js
+ * @returns {{atender:Function, fechar:Function, conferirPasta:Function}}
+ */
+function montar(op) {
+    let pastaVigiada = null;
+    let pararVigia = () => {};
+
+    function conferirPasta() {
+        const atual = op.pasta && op.pasta();
+        if (!atual || atual === pastaVigiada) return atual;
+        pararVigia();
+        pastaVigiada = atual;
+        if (!fs.existsSync(atual)) { pararVigia = () => {}; return atual; }
+        pararVigia = vigiar(atual, (mudados) => op.emitir('arquivos', { pasta: atual, mudados }));
+        op.emitir('arquivos', { pasta: atual, mudados: [], trocou: true });
+        return atual;
+    }
+    /* O /dir e os projetos da barra lateral trocam a pasta sem passar por
+       aqui: sem esta ronda o painel vigiaria o projeto anterior. E só depois
+       que o painel foi aberto de verdade — no Linux o fs.watch recursivo custa
+       um aviso do sistema por pasta, e quem só conversa não precisa disso. */
+    let usada = false;
+    const ronda = setInterval(() => { if (usada) conferirPasta(); }, 2000);
+    if (ronda.unref) ronda.unref();
+
+    function json(res, status, corpo) {
+        res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+        res.end(JSON.stringify(corpo));
+    }
+
+    /* Devolve true se a rota era do painel. A chave já foi conferida pelo
+       app.js antes de chegar aqui — por isso a prévia também mora em /api/. */
+    async function atender(req, res, url) {
+        const rota = url.pathname;
+        const ehArquivos = rota.startsWith('/api/arquivos/');
+        const m = rota.match(/^\/api\/previa\/[0-9a-f]+\/?(.*)$/);
+        if (!ehArquivos && !m) return false;
+        usada = true;
+        const raiz = conferirPasta();
+        if (!raiz || !fs.existsSync(raiz)) { json(res, 404, { ok: false, error: 'sem pasta de projeto' }); return true; }
+
+        if (rota === '/api/arquivos/arvore') {
+            const a = arvore(raiz);
+            json(res, 200, { ok: true, pasta: raiz, nome: path.basename(raiz), itens: a.itens,
+                cortada: a.cortada, entrada: entradaDaPrevia(raiz) });
+            return true;
+        }
+        if (rota === '/api/arquivos/ler') {
+            const r = ler(raiz, url.searchParams.get('p') || '');
+            json(res, r.status, r.corpo);
+            return true;
+        }
+        /* /api/previa/<chave>/<caminho>: a chave vai no CAMINHO, não na
+           query, porque a página da prévia pede style.css e script.js por
+           endereço relativo — e o relativo herda o caminho, não a query. */
+        if (m) { servirPrevia(raiz, m[1], res); return true; }
+
+        json(res, 404, { ok: false, error: 'rota desconhecida' });
+        return true;
+    }
+
+    return {
+        atender,
+        conferirPasta,
+        fechar() { clearInterval(ronda); pararVigia(); },
+    };
+}
+
+module.exports = { montar, dentro, arvore, ler, vigiar, ehBinario, entradaDaPrevia, MAX_LEITURA };