primocode 8.38.1 → 8.40.0

package/lib/act.js

@@ -19,7 +19,13 @@ const cfg = require('./config');
 const catalogo = require('./catalogo');
 const repeticao = require('./repeticao');
 
-const MAX_ITERATIONS = 15;
+// 40, não 15: com o freio de repetição (repeticao.js) e o de rodada parada,
+// volta a mais não é volta em círculo — é trabalho. Quinze acabavam no meio
+// de um vídeo de dez cenas com pesquisa, e a pessoa lia "gastei as voltas".
+const MAX_ITERATIONS = Number(process.env.PRIMOCODE_MAX_VOLTAS || 40);
+// Quantas vezes o agente é EMPURRADO quando para no meio para narrar
+// ("agora vou criar o arquivo…") em vez de fazer. Ver `pareceParadaNoMeio`.
+const MAX_EMPURROES = 3;
 // Voltas seguidas sem executar nada antes de desistir.
 const MAX_RODADAS_PARADAS = 3;
 const MAX_PROFUNDIDADE = 2; // principal + 1 nível de subagente
@@ -182,6 +188,20 @@ function logResult(kind, result, profundidade) {
             }
             return;
         }
+        case 'buscar_audio': {
+            console.log(p + c.muted(`${result.tipo === 'efeito' ? 'efeito' : 'música'}: `) + c.white(`${result.titulo}`)
+                + c.muted(` — ${result.autor || 'autor desconhecido'}${result.duracao ? ` · ${result.duracao}s` : ''} · ${result.licenca}`));
+            console.log(p + c.dim(`${result.url}`));
+            return;
+        }
+        case 'marca_da_empresa': {
+            const cores = (result.cores && result.cores.paleta || []).slice(0, 4).join(' ');
+            console.log(p + c.white(result.nome || '') + c.muted(` · ${result.site || ''}`));
+            console.log(p + c.dim(`cor ${(result.cores && result.cores.principal) || '—'}${cores ? ` · paleta ${cores}` : ''}`
+                + `${(result.fontes || []).length ? ` · fonte ${result.fontes[0]}` : ''}`
+                + `${result.logo ? ` · logo ${result.logo.formato} (${result.logo.fonte})` : ' · sem logo'}`));
+            return;
+        }
         case 'desktop_windows': {
             console.log(p + c.muted(`${result.total} janela${result.total === 1 ? '' : 's'}`));
             for (const j of (result.janelas || []).slice(0, 5)) console.log(p + c.dim(`${j.app ? j.app + ' · ' : ''}${j.titulo}`.slice(0, 120)));
@@ -338,6 +358,39 @@ async function pausar(ms, subagent) {
     if (sp) sp.stop();
 }
 
+/**
+ * O modelo devolveu TEXTO, sem tool e sem finish. Isso é resposta — ou é o
+ * agente parando no meio para narrar o que ia fazer?
+ *
+ * Reclamação do dono: "ele tá parando sem concluir, ele deve continuar até o
+ * fim". Medido: o modelo escreve "Agora vou criar o vídeo com as cenas…" e
+ * para, porque texto sem tool encerra a rodada. Quem lê vê uma promessa no
+ * lugar da entrega. Três sinais dizem que foi parada, não resposta:
+ *
+ *   1. Há um plano (write_todos) com item por fazer — ele mesmo disse que
+ *      não acabou.
+ *   2. O texto é INTENÇÃO: começa ou termina anunciando o próximo passo
+ *      ("vou", "em seguida", "próximo passo", dois-pontos no fim, reticências).
+ *   3. É curto. Uma resposta de verdade a "explique este erro" tem corpo; um
+ *      "vou abrir o arquivo agora" não tem.
+ *
+ * Pergunta ao usuário NÃO conta como parada: o prompt proíbe perguntar, mas
+ * se o modelo perguntou, empurrá-lo faria ele decidir sozinho o que talvez
+ * não devesse — e o texto de conversa ("oi, sou o PrimoCode") também não é
+ * parada. Só intenção declarada e plano aberto.
+ */
+const INTENCAO = /(^|[.!\n]\s*)(agora\s+)?(vou|irei|deixa eu|deixe-me|preciso (agora )?(de )?(criar|ler|abrir|rodar|ver|conferir|pesquisar|mandar|fazer|gerar|escrever|ajustar)|primeiro (vou|eu)|em seguida|pr[óo]ximo passo|a seguir,?\s+(vou|eu)|vamos (criar|ler|abrir|rodar|ver|conferir|come[çc]ar|fazer|gerar|escrever))\b/i;
+function pareceParadaNoMeio(texto, { todosPendentes = 0, rodouTool = false } = {}) {
+    const t = String(texto || '').trim();
+    if (!t) return false;
+    if (todosPendentes > 0) return true;
+    if (t.length > 700) return false;                       // resposta com corpo
+    if (/\?\s*$/.test(t)) return false;                      // perguntou: não é parada
+    if (INTENCAO.test(t)) return true;
+    if (rodouTool && /[:…]\s*$|\.\.\.\s*$/.test(t)) return true;   // "Criando as cenas:" e nada depois
+    return false;
+}
+
 function motivoDaParada({ voltas, voltasEmFalso, falhasPendentes, travou }) {
     if (falhasPendentes.length) {
         return `Parei sem concluir. A última falha foi: ${falhasPendentes[falhasPendentes.length - 1].texto}`;
@@ -391,6 +444,13 @@ async function runAct(userPrompt, opts) {
     // assim que "crie um vídeo para a tostudy" morreu sem entregar nada.
     let pesquisasSecas = 0;
     let rodadasParadas = 0;
+    // Para o `pareceParadaNoMeio`: alguma tool já rodou nesta tarefa, e o
+    // último plano que o modelo escreveu (write_todos) — desta tarefa, não da
+    // sessão: um plano velho de um pedido interrompido não pode empurrar o
+    // pedido seguinte.
+    let rodouTool = false;
+    let todosDaTarefa = [];
+    let empurroes = 0;
 
     const messages = [];
     if (!subagent) {
@@ -579,6 +639,29 @@ async function runAct(userPrompt, opts) {
                 iteration--;
                 continue;
             }
+            // PAROU NO MEIO? Texto de intenção ("agora vou criar…") ou plano
+            // com item aberto não é entrega. Em vez de encerrar, a tarefa é
+            // devolvida: "isso foi uma promessa — faça". Três empurrões; se
+            // depois disso ele insistir em só falar, a resposta é dele.
+            const pendentes = todosDaTarefa.filter((t) => t.status !== 'completed').length;
+            if (finalText && empurroes < MAX_EMPURROES && !PARAR
+                && pareceParadaNoMeio(finalText, { todosPendentes: pendentes, rodouTool })) {
+                empurroes++;
+                if (!subagent) {
+                    if (fluxo) fluxo.fechar();
+                    else fala.pensamento(finalText, profundidade);
+                }
+                messages.push({ role: 'assistant', content: finalText });
+                messages.push({
+                    role: 'user',
+                    content: 'Isso foi uma intenção, não uma entrega: você parou no meio. Não narre o próximo '
+                        + 'passo — CHAME a tool agora e siga até o fim'
+                        + (pendentes ? `, o seu plano ainda tem ${pendentes} item(ns) por fazer` : '')
+                        + '. Só pare quando tudo estiver feito, com finish("o que foi feito").',
+                });
+                finalText = '';
+                continue;
+            }
             if (!subagent) {
                 if (fluxo) fluxo.fechar();
                 else fala.resposta(finalText);
@@ -711,9 +794,11 @@ async function runAct(userPrompt, opts) {
             }
 
             algoRodou = true;
+            rodouTool = true;
             fala.acao(tc.name, tc.arguments, profundidade);
             const result = await tools.execute(tc.name, tc.arguments, { projectDir: pastaAtual });
             logResult(tc.name, result, profundidade);
+            if (tc.name === 'write_todos' && result && Array.isArray(result.todos)) todosDaTarefa = result.todos;
 
             // Uma escrita bem-sucedida limpa a dívida — mas só a do MESMO
             // arquivo. Escrever algo sem relação (ou um run_shell qualquer)
@@ -910,4 +995,4 @@ async function rodarPipeline(args, ctx) {
 }
 
 module.exports = { runAct, interromper, compactar, motivoDaParada, ehTetoDeToken, ehTransitorio, esperaDoErro,
-    anotacaoDoQueJaFoi, encolherParaContinuar, MAX_ITERATIONS };
+    anotacaoDoQueJaFoi, encolherParaContinuar, pareceParadaNoMeio, MAX_ITERATIONS, MAX_EMPURROES };

package/lib/audio-livre.js

@@ -0,0 +1,172 @@
+/**
+ * audio-livre.js — música e efeitos sonoros da internet, com licença.
+ *
+ * Pedido do dono: "selecione músicas da internet, efeitos sonoros". O que
+ * existia era a trilha SINTETIZADA (quatro osciladores e um ruído) e o
+ * arquivo do próprio usuário. Faltava o meio: uma faixa de verdade, tocada
+ * por gente, que ele não precise ter no disco.
+ *
+ * ── DE ONDE VEM ──────────────────────────────────────────────────────────
+ * Da API do Openverse (openverse.org, mantida pela WordPress Foundation):
+ * ela indexa áudio com licença Creative Commons de fontes abertas — música
+ * do Jamendo, efeitos do Freesound, arquivos da Wikimedia — e devolve, para
+ * cada faixa, a URL do arquivo, a licença e o crédito pronto. Sem chave, sem
+ * conta. Não é YouTube nem Spotify: aqui a licença permite usar, e o crédito
+ * vai junto para a peça não sair devendo.
+ *
+ * ── O QUE ELA DEVOLVE ────────────────────────────────────────────────────
+ * O arquivo já BAIXADO para a pasta do projeto e ENVIADO ao estúdio: a URL
+ * "/midia/…" que entra direto em `trilha.src` ou em `som: {arquivo}`, mais o
+ * crédito ("Título — Autor, CC BY 4.0"). A licença decide o que o agente
+ * tem de fazer: BY pede o crédito na peça; CC0/PDM não pede nada. Licença
+ * NC (não comercial) não entra por padrão — a peça pode ser um anúncio.
+ *
+ * Zero dependências: o `pegar` do referencia.js, em modo binário.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const referencia = require('./referencia.js');
+
+const API = 'https://api.openverse.org/v1/audio/';
+
+// Licenças que permitem uso comercial sem pedir nada além do crédito.
+const LIVRES = new Set(['by', 'by-sa', 'cc0', 'pdm']);
+const NOME_LICENCA = {
+    by: 'CC BY', 'by-sa': 'CC BY-SA', 'by-nc': 'CC BY-NC', 'by-nd': 'CC BY-ND',
+    'by-nc-sa': 'CC BY-NC-SA', 'by-nc-nd': 'CC BY-NC-ND', cc0: 'CC0', pdm: 'Domínio público',
+};
+
+function slug(t) {
+    return String(t || '').normalize('NFD').replace(/[̀-ͯ]/g, '')
+        .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'audio';
+}
+
+function credito(f) {
+    const lic = NOME_LICENCA[f.license] || String(f.license || '').toUpperCase();
+    const versao = f.license_version && !/cc0|pdm/.test(f.license) ? ' ' + f.license_version : '';
+    return `${f.title || 'Sem título'} — ${f.creator || 'autor desconhecido'} (${lic}${versao}, via ${f.provider || 'Openverse'})`;
+}
+
+/**
+ * Pergunta ao Openverse. `tipo` "musica" restringe à categoria music; "efeito"
+ * pede coisa curta (até ~12 s). `dur` em segundos aproxima a duração desejada
+ * da trilha — uma faixa de 4 min para um reels de 30 s é desperdício, mas
+ * uma de 20 s para um vídeo de 60 s acaba antes; a nota pesa isso.
+ */
+async function procurar({ consulta, tipo = 'musica', dur = 0, comercial = true, pagina = 1 }) {
+    const q = new URLSearchParams({ q: consulta, page_size: '20', page: String(pagina) });
+    if (tipo === 'musica') q.set('category', 'music');
+    if (comercial) q.set('license_type', 'commercial');
+    const bruto = await referencia.pegar(`${API}?${q}`, { timeout: 12000 });
+    if (!bruto) return { ok: false, error: 'o Openverse não respondeu (rede?)' };
+    let j;
+    try { j = JSON.parse(bruto); } catch { return { ok: false, error: 'resposta ilegível do Openverse' }; }
+    const itens = (j.results || []).filter((f) => f.url && LIVRES.has(String(f.license || '').toLowerCase()) || !comercial);
+    const alvoMs = tipo === 'efeito' ? 2500 : (dur ? dur * 1000 : 90000);
+    const notas = itens.map((f) => {
+        let n = 0;
+        const d = Number(f.duration) || 0;
+        if (tipo === 'efeito') {
+            if (d > 15000) n -= 50;                            // não é efeito, é faixa
+            else n += 20 - Math.abs(d - alvoMs) / 500;
+        } else {
+            if (d && d < alvoMs * 0.6) n -= 20;                // acaba antes do vídeo
+            n -= Math.abs(d - alvoMs) / 20000;                 // perto da duração pedida
+            if (f.category === 'music') n += 5;
+        }
+        if (/cc0|pdm/.test(f.license)) n += 3;                 // sem crédito obrigatório
+        if (/mp3/i.test(f.filetype || '') || /\.mp3(\?|$)/i.test(f.url)) n += 4;   // toca em qualquer lugar
+        // As palavras da consulta no título/tags contam.
+        const alvo = `${f.title} ${(f.tags || []).map((t) => t.name).join(' ')} ${(f.genres || []).join(' ')}`.toLowerCase();
+        for (const p of consulta.toLowerCase().split(/\s+/)) if (p.length > 2 && alvo.includes(p)) n += 3;
+        return { f, n };
+    }).sort((a, b) => b.n - a.n);
+    return {
+        ok: true,
+        total: j.result_count || itens.length,
+        itens: notas.map(({ f }) => ({
+            id: f.id, titulo: f.title, autor: f.creator, licenca: f.license, licencaUrl: f.license_url,
+            duracao: f.duration ? Math.round(f.duration / 1000) : null, url: f.url, pagina: f.foreign_landing_url,
+            provedor: f.provider, tipoArquivo: f.filetype || null, generos: f.genres || [], credito: credito(f),
+        })),
+    };
+}
+
+/** Baixa a faixa para <projeto>/midia/ e manda ao estúdio. */
+async function trazer(item, { projectDir, studio }) {
+    const bytes = await referencia.pegar(item.url, { timeout: 45000, binario: true });
+    if (!bytes || bytes.length < 2000) return { ok: false, error: `não consegui baixar "${item.titulo}" de ${item.provedor}` };
+    // A extensão pelo conteúdo, não pela URL: o Jamendo entrega mp3 numa URL
+    // sem extensão ("?trackid=…&format=mp32").
+    const cab = bytes.subarray(0, 12);
+    const ext = cab.subarray(0, 3).toString() === 'ID3' || (cab[0] === 0xff && (cab[1] & 0xe0) === 0xe0) ? '.mp3'
+        : cab.subarray(0, 4).toString() === 'RIFF' ? '.wav'
+            : cab.subarray(0, 4).toString() === 'OggS' ? '.ogg'
+                : cab.subarray(0, 4).toString() === 'fLaC' ? '.flac'
+                    : (item.tipoArquivo ? '.' + item.tipoArquivo.replace(/^\./, '') : '.mp3');
+    const pasta = path.join(projectDir || process.cwd(), 'midia');
+    fs.mkdirSync(pasta, { recursive: true });
+    const nome = `${slug(item.titulo)}-${String(item.id || '').slice(0, 6)}${ext}`;
+    const caminho = path.join(pasta, nome);
+    fs.writeFileSync(caminho, bytes);
+    // FLAC/OGG do Freesound: o navegador toca, mas o MP4 exportado quer AAC —
+    // o estúdio cuida disso na exportação; aqui só entregamos o arquivo.
+    const envio = await studio.midiaEnviar({ arquivo: caminho, nome });
+    if (!envio || envio.ok === false) return { ok: false, error: (envio && envio.error) || 'o estúdio não aceitou o arquivo', arquivoLocal: caminho };
+    return { ok: true, url: envio.url, arquivoLocal: path.relative(projectDir || process.cwd(), caminho), bytes: bytes.length };
+}
+
+/**
+ * A tool: procura, escolhe a melhor, baixa e devolve a URL pronta — e as
+ * alternativas, para o agente trocar sem pesquisar de novo.
+ */
+async function buscarAudio(args, { projectDir, studio }) {
+    const consulta = String(args.consulta || args.query || '').trim();
+    if (!consulta) return { ok: false, error: 'Diga o que procurar: o clima da música ("upbeat corporate", "piano calmo") ou o efeito ("whoosh", "ding", "click").' };
+    const tipo = /^(efeito|som|sfx|sound)/i.test(String(args.tipo || '')) ? 'efeito' : 'musica';
+    const dur = Number(args.duracao) || 0;
+    const busca = await procurar({ consulta, tipo, dur, comercial: args.comercial !== false });
+    if (!busca.ok) return busca;
+    if (!busca.itens.length) {
+        return {
+            ok: false,
+            error: `Nenhuma faixa livre para "${consulta}".`,
+            comoCorrigir: tipo === 'efeito'
+                ? 'Use um som SINTETIZADO do estúdio, que não precisa de arquivo: som: "whoosh" | "impacto" | "click" | "pop" | "ding" | "subida" | "tique" | "brilho".'
+                : 'Tente a consulta em inglês e mais genérica ("upbeat electronic", "calm piano", "epic cinematic"), ou use a trilha GERADA: "trilha": {"tipo":"gerada","estilo":"pulso"}.',
+        };
+    }
+    // Baixa a melhor; se ela falhar, a próxima. Três tentativas.
+    let trazido = null;
+    let escolhida = null;
+    for (const item of busca.itens.slice(0, 3)) {
+        trazido = await trazer(item, { projectDir, studio });
+        if (trazido.ok) { escolhida = item; break; }
+    }
+    if (!trazido || !trazido.ok) return { ok: false, error: (trazido && trazido.error) || 'não consegui baixar nenhuma faixa', alternativas: busca.itens.slice(0, 5) };
+    const precisaCredito = !/cc0|pdm/.test(escolhida.licenca);
+    return {
+        ok: true,
+        tipo,
+        url: trazido.url,
+        titulo: escolhida.titulo,
+        autor: escolhida.autor,
+        duracao: escolhida.duracao,
+        licenca: NOME_LICENCA[escolhida.licenca] || escolhida.licenca,
+        licencaUrl: escolhida.licencaUrl,
+        credito: escolhida.credito,
+        pagina: escolhida.pagina,
+        arquivoLocal: trazido.arquivoLocal,
+        comoUsar: tipo === 'efeito'
+            ? `No elemento ou na cena: "som": {"arquivo": "${trazido.url}", "volume": 0.8}.`
+            : `No documento: "trilha": {"tipo":"arquivo","src":"${trazido.url}","volume":0.55,"repetir":true}.`
+              + (precisaCredito ? ` A licença pede CRÉDITO: ponha "${escolhida.credito}" na assinatura ou numa legenda da última cena.` : ' Licença sem exigência de crédito.'),
+        alternativas: busca.itens.filter((i) => i.id !== escolhida.id).slice(0, 4)
+            .map((i) => ({ titulo: i.titulo, autor: i.autor, duracao: i.duracao, licenca: i.licenca, id: i.id })),
+    };
+}
+
+module.exports = { buscarAudio, procurar, trazer, credito, LIVRES, NOME_LICENCA };

package/lib/catalogo.js

@@ -143,6 +143,13 @@ const GRUPOS = [
               args: 'todos: lista de {content: a tarefa curta no imperativo, status: pending|in_progress|completed}. Reescreve a lista inteira a cada chamada; só uma "in_progress" por vez.' },
             { tool: 'pesquisar_referencia', escreve: false, faz: 'lê docs e exemplos antes de escrever — sobe a qualidade',
               args: 'consulta: o que pesquisar, de preferência em inglês. paginas (opcional, número, padrão 3, máximo 5).' },
+            // Baixa o arquivo para <projeto>/midia/ — por isso `escreve: true`.
+            { tool: 'buscar_audio', escreve: true, faz: 'acha música ou efeito sonoro livre na internet (Creative Commons), baixa e manda para o estúdio, com o crédito',
+              args: 'consulta: o clima ou o som, em inglês ("upbeat corporate", "calm piano", "whoosh", "ding"). tipo (opcional): "musica" (padrão) ou "efeito". '
+                + 'duracao (opcional, segundos): quanto o vídeo dura, para a faixa combinar. Devolve url para trilha.src ou som.arquivo, e o crédito a pôr na peça quando a licença pedir.' },
+            { tool: 'marca_da_empresa', escreve: true, faz: 'puxa do site da empresa a logo, a cor principal, a paleta, as fontes e a frase — pronto para `marca` no estúdio',
+              args: 'nome: a empresa como o usuário falou. site (opcional): o endereço, se souber — sem ele, o site é descoberto. '
+                + 'Devolve marca:{cor, logo} para colar no documento, mais cores.paleta, fontes e frase. Chame ANTES de criar uma peça de marca.' },
             // Vai para memory-geral.md, FORA da pasta do projeto — por isso não
             // é write_file/edit_file (a sandbox de resolveInProject bloqueia
             // qualquer caminho fora do projeto, e é assim mesmo que tem que

package/lib/marca.js

@@ -0,0 +1,280 @@
+/**
+ * marca.js — a logo e a identidade visual de uma empresa, puxadas do site.
+ *
+ * Pedido do dono: "puxe a logo e identidade visual da empresa". O agente
+ * fazia peça de marca com `marca.cor` chutada e sem logo, ou pedia o arquivo
+ * ao usuário — e o usuário, que só disse "faz um vídeo para a Paris Group",
+ * não estava ali para mandar arquivo nenhum. O site da empresa TEM a logo,
+ * as cores e as fontes; é só ler como uma pessoa leria.
+ *
+ * ── O QUE SE LÊ, E EM QUE ORDEM ──────────────────────────────────────────
+ *   nome   og:site_name → <title> (sem o " | slogan")
+ *   frase  meta description / og:description (o "sobre" em uma linha)
+ *   logo   <img> com "logo" no src/alt/class (a de verdade, no cabeçalho) →
+ *          apple-touch-icon (180 px, o melhor ícone que todo site tem) →
+ *          og:image (é a imagem de compartilhar, às vezes é a logo, às vezes
+ *          uma foto — por isso vem por último) → favicon.
+ *          SVG ganha de PNG no mesmo lugar: escala sem borrar.
+ *   cores  meta theme-color primeiro (a empresa DISSE qual é a cor), depois
+ *          as cores mais repetidas no CSS (inline e nas folhas ligadas),
+ *          fora branco/preto/cinza — o que sobra é a paleta.
+ *   fontes os "family=" do Google Fonts e os font-family do CSS, fora as
+ *          genéricas (sans-serif, Arial, system-ui).
+ *
+ * A logo é BAIXADA para o projeto e ENVIADA ao estúdio: volta como
+ * "/midia/…", pronta para `marca.logo`. O resto volta como `marca` pronta
+ * para colar no documento.
+ *
+ * Zero dependências: o `pegar` do referencia.js (texto e binário), e o
+ * chute de domínio dele quando a pessoa deu só o nome.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const referencia = require('./referencia.js');
+
+const GENERICAS_FONTE = /^(sans-serif|serif|monospace|system-ui|-apple-system|blinkmacsystemfont|segoe ui|arial|helvetica( neue)?|roboto|inherit|initial|ui-sans-serif|ui-serif|ui-monospace|apple color emoji|segoe ui emoji|noto color emoji|times new roman|courier new|verdana|tahoma|georgia)$/i;
+
+function absoluta(href, base) {
+    try { return new URL(String(href || '').replace(/&amp;/g, '&'), base).href; } catch { return null; }
+}
+
+function atributo(tag, nome) {
+    const m = new RegExp(`\\b${nome}\\s*=\\s*("([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i').exec(tag);
+    return m ? (m[2] != null ? m[2] : m[3] != null ? m[3] : m[4]) : null;
+}
+
+function metas(html) {
+    const saida = {};
+    for (const tag of html.match(/<meta\b[^>]*>/gi) || []) {
+        const chave = atributo(tag, 'property') || atributo(tag, 'name');
+        const valor = atributo(tag, 'content');
+        if (chave && valor && saida[chave.toLowerCase()] == null) saida[chave.toLowerCase()] = valor.trim();
+    }
+    return saida;
+}
+
+/** As candidatas a logo, da melhor para a pior. */
+function candidatasALogo(html, base) {
+    const lista = [];
+    // 1. <img> que se chama logo — no cabeçalho é a logo de verdade.
+    for (const tag of html.match(/<img\b[^>]*>/gi) || []) {
+        const src = atributo(tag, 'src') || atributo(tag, 'data-src') || '';
+        const alt = atributo(tag, 'alt') || '';
+        const cls = atributo(tag, 'class') || '';
+        const id = atributo(tag, 'id') || '';
+        if (/logo|brand|marca/i.test(`${src} ${alt} ${cls} ${id}`) && !/sponsor|partner|cliente|client|parceir/i.test(`${alt} ${cls} ${src}`)) {
+            const u = absoluta(src, base);
+            if (u && !/^data:/.test(u)) lista.push({ url: u, fonte: 'img-logo', nota: /\.svg(\?|$)/i.test(u) ? 30 : 20 });
+        }
+    }
+    // 1b. SVG inline no cabeçalho com "logo" no nome — não dá para baixar,
+    //     mas o agente pode saber que existe (e usar o nome em texto).
+    // 2. Ícones declarados.
+    for (const tag of html.match(/<link\b[^>]*>/gi) || []) {
+        const rel = (atributo(tag, 'rel') || '').toLowerCase();
+        const href = atributo(tag, 'href');
+        if (!href) continue;
+        const u = absoluta(href, base);
+        if (!u) continue;
+        if (/apple-touch-icon/.test(rel)) lista.push({ url: u, fonte: 'apple-touch-icon', nota: 15 });
+        else if (/\bicon\b/.test(rel)) {
+            const tam = parseInt((atributo(tag, 'sizes') || '0').split('x')[0], 10) || 0;
+            lista.push({ url: u, fonte: 'icon', nota: /\.svg(\?|$)/i.test(u) ? 14 : (tam >= 128 ? 10 : 4) });
+        }
+    }
+    // 3. og:image — a imagem de compartilhar. Às vezes é a logo, às vezes é
+    //    uma foto: fica atrás das declaradas.
+    const m = metas(html);
+    const og = m['og:image'] || m['twitter:image'];
+    if (og) { const u = absoluta(og, base); if (u) lista.push({ url: u, fonte: 'og:image', nota: 6 }); }
+    // 4. O favicon padrão, quando nada foi declarado.
+    lista.push({ url: absoluta('/favicon.ico', base), fonte: 'favicon', nota: 1 });
+    // Ordena e tira repetidos.
+    const vistos = new Set();
+    return lista.filter((c) => c.url && !vistos.has(c.url) && vistos.add(c.url)).sort((a, b) => b.nota - a.nota);
+}
+
+/** As cores de um CSS, contadas. Fora branco, preto e cinza. */
+function coresDe(css, contagem) {
+    const re = /#([0-9a-f]{6}|[0-9a-f]{3})\b|rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})/gi;
+    let m;
+    while ((m = re.exec(css))) {
+        let hex;
+        if (m[1]) {
+            hex = m[1].length === 3 ? m[1].split('').map((c) => c + c).join('') : m[1];
+        } else {
+            hex = [m[2], m[3], m[4]].map((n) => Math.min(255, +n).toString(16).padStart(2, '0')).join('');
+        }
+        hex = '#' + hex.toLowerCase();
+        const r = parseInt(hex.slice(1, 3), 16), g = parseInt(hex.slice(3, 5), 16), b = parseInt(hex.slice(5, 7), 16);
+        const max = Math.max(r, g, b), min = Math.min(r, g, b);
+        const sat = max === 0 ? 0 : (max - min) / max;
+        // Cinza (pouca saturação), quase branco e quase preto não são
+        // identidade — são o papel e a tinta de todo site.
+        if (sat < 0.18 || max < 40 || (min > 225)) continue;
+        contagem.set(hex, (contagem.get(hex) || 0) + 1);
+    }
+}
+
+function fontesDe(html, css) {
+    const achadas = new Map();
+    // Google Fonts: family=Plus+Jakarta+Sans:wght@400;700&family=Inter
+    for (const m of html.matchAll(/fonts\.googleapis\.com\/css2?\?([^"' >]+)/gi)) {
+        for (const f of m[1].matchAll(/family=([^&:]+)/g)) {
+            const nome = decodeURIComponent(f[1].replace(/\+/g, ' ')).trim();
+            if (nome) achadas.set(nome, (achadas.get(nome) || 0) + 10);
+        }
+    }
+    // Para em ; } e aspas: o CSS aqui inclui atributos style="…" da página,
+    // e sem a aspa como fim o nome da fonte engolia o atributo seguinte
+    // (medido: 'sans-serif"  style="color:#7fa6ff').
+    for (const m of css.matchAll(/font-family\s*:\s*([^;}]+)/gi)) {
+        for (const parte of m[1].split(',')) {
+            const nome = parte.trim().replace(/\s*!important/, '').replace(/^["']|["']$/g, '').trim();
+            if (!nome || nome.length > 40 || GENERICAS_FONTE.test(nome) || /[(){}:="']/.test(nome)) continue;
+            achadas.set(nome, (achadas.get(nome) || 0) + 1);
+        }
+    }
+    return [...achadas.entries()].sort((a, b) => b[1] - a[1]).map(([n]) => n).slice(0, 3);
+}
+
+/** Descobre o site quando veio só o nome: o chute de domínio do referencia.js. */
+async function acharSite(nome) {
+    const palpites = referencia.sitesProvaveis(`site da empresa "${nome}"`);
+    const { vivos, html } = await referencia.chutesVivos(palpites, 1);
+    if (vivos.length) return { url: vivos[0].url, html: html.get(vivos[0].url) };
+    // Sem chute vivo, o buscador.
+    const achados = await referencia.buscar(`${nome} site oficial`, 4);
+    for (const a of achados) {
+        if (/wikipedia|linkedin|instagram|facebook|youtube|twitter|x\.com/i.test(a.url)) continue;
+        const h = await referencia.pegar(a.url, { timeout: 8000 });
+        if (h && h.length > 500) return { url: a.url, html: h };
+    }
+    return null;
+}
+
+/**
+ * A tool. `site` (URL) ou `nome` (a empresa). Devolve a identidade e a
+ * `marca` pronta para o documento do estúdio.
+ */
+async function marcaDaEmpresa(args, { projectDir, studio }) {
+    const nome = String(args.nome || args.empresa || '').trim();
+    let site = String(args.site || args.url || '').trim();
+    if (!nome && !site) return { ok: false, error: 'Diga o nome da empresa (nome) ou o endereço do site (site).' };
+    if (site && !/^https?:\/\//i.test(site)) site = 'https://' + site;
+
+    let html = null;
+    if (site) html = await referencia.pegar(site, { timeout: 12000 });
+    if (!html && site && !/\/\/www\./i.test(site)) {
+        const comWww = site.replace(/^(https?:\/\/)/i, '$1www.');
+        html = await referencia.pegar(comWww, { timeout: 12000 });
+        if (html) site = comWww;
+    }
+    if (!html && nome) {
+        const achado = await acharSite(nome);
+        if (achado) { site = achado.url; html = achado.html; }
+    }
+    if (!html) {
+        return {
+            ok: false,
+            error: `Não achei o site de "${nome || site}".`,
+            comoCorrigir: 'Se souber o endereço, chame de novo com site:"https://…". Se não, siga SEM a logo: '
+                + 'use o nome em texto na assinatura ("tipo":"assinatura","nome":…) e uma cor de tema — '
+                + 'e diga ao usuário que a logo não foi encontrada para ele mandar o arquivo (studio_midia).',
+        };
+    }
+
+    const m = metas(html);
+    const titulo = (html.match(/<title[^>]*>([\s\S]*?)<\/title>/i) || [])[1] || '';
+    // Sem og:site_name nem <title> (site montado por JavaScript), o nome vem
+    // do domínio: "nubank.com.br" → "Nubank". Melhor que campo vazio.
+    const dominio = ((site.match(/^https?:\/\/(?:www\.)?([^/]+)/i) || [])[1] || '').split('.')[0];
+    const nomeSite = (m['og:site_name'] || m['application-name'] || titulo.split(/\s[|–—-]\s|\s·\s/)[0] || nome
+        || (dominio ? dominio.charAt(0).toUpperCase() + dominio.slice(1) : '')).trim().slice(0, 80);
+    const frase = (m['description'] || m['og:description'] || '').trim().slice(0, 240);
+
+    // Cores: theme-color declarada, depois o CSS (inline + até 3 folhas).
+    const contagem = new Map();
+    let css = (html.match(/<style\b[^>]*>([\s\S]*?)<\/style>/gi) || []).join('\n');
+    // Só o MIOLO do style="…": com o `style="` junto, o fim de um atributo
+    // virava começo do nome da fonte seguinte (medido: 'sans-serif" style=…').
+    css += ' ' + (html.match(/\sstyle\s*=\s*"[^"]*"/gi) || []).map((a) => a.replace(/^\sstyle\s*=\s*"|"$/g, '')).join('; ');
+    const folhas = [];
+    for (const tag of html.match(/<link\b[^>]*>/gi) || []) {
+        if (/stylesheet/i.test(atributo(tag, 'rel') || '')) {
+            const u = absoluta(atributo(tag, 'href'), site);
+            if (u && !/fonts\.googleapis/i.test(u)) folhas.push(u);
+        }
+    }
+    const conteudos = await Promise.all(folhas.slice(0, 3).map((u) => referencia.pegar(u, { timeout: 8000 })));
+    for (const c of conteudos) if (c) css += '\n' + c.slice(0, 300000);
+    coresDe(css, contagem);
+    const paleta = [...contagem.entries()].sort((a, b) => b[1] - a[1]).map(([c]) => c).slice(0, 6);
+    let principal = null;
+    const tema = m['theme-color'];
+    if (tema && /^#?[0-9a-f]{3,8}$/i.test(tema.replace('#', ''))) {
+        const h = tema.replace('#', '').toLowerCase();
+        principal = '#' + (h.length === 3 ? h.split('').map((c) => c + c).join('') : h.slice(0, 6));
+        const r = parseInt(principal.slice(1, 3), 16), g = parseInt(principal.slice(3, 5), 16), b = parseInt(principal.slice(5, 7), 16);
+        const max = Math.max(r, g, b), min = Math.min(r, g, b);
+        if (max === 0 || (max - min) / max < 0.18 || min > 225) principal = null;   // theme-color branco/preto não é a cor da marca
+    }
+    if (!principal) principal = paleta[0] || null;
+
+    const fontes = fontesDe(html, css);
+
+    // A logo: tenta as candidatas em ordem até uma baixar de verdade.
+    let logo = null;
+    const candidatas = candidatasALogo(html, site);
+    const tentadas = [];
+    for (const c of candidatas.slice(0, 6)) {
+        const bytes = await referencia.pegar(c.url, { timeout: 10000, binario: true });
+        if (!bytes || bytes.length < 200) { tentadas.push(`${c.fonte}: não abriu`); continue; }
+        const cab = bytes.subarray(0, 16);
+        const ext = /^<\?xml|^<svg/i.test(bytes.subarray(0, 64).toString('utf8').trim()) ? '.svg'
+            : cab[0] === 0x89 && cab[1] === 0x50 ? '.png'
+                : cab[0] === 0xff && cab[1] === 0xd8 ? '.jpg'
+                    : cab.subarray(0, 4).toString() === 'RIFF' ? '.webp'
+                        : cab[0] === 0x00 && cab[1] === 0x00 && cab[2] === 0x01 && cab[3] === 0x00 ? '.ico'
+                            : cab.subarray(0, 3).toString() === 'GIF' ? '.gif' : null;
+        if (!ext) { tentadas.push(`${c.fonte}: não é imagem`); continue; }
+        if (ext === '.ico' && candidatas.length > 1 && c.fonte === 'favicon') { tentadas.push('favicon: só .ico'); }
+        const pasta = path.join(projectDir || process.cwd(), 'midia');
+        fs.mkdirSync(pasta, { recursive: true });
+        const arquivo = path.join(pasta, `logo-${nomeSite.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'marca'}${ext}`);
+        fs.writeFileSync(arquivo, bytes);
+        let url = null;
+        if (studio && ext !== '.ico') {
+            const envio = await studio.midiaEnviar({ arquivo });
+            if (envio && envio.ok !== false) url = envio.url;
+        }
+        logo = { url: url || null, arquivoLocal: path.relative(projectDir || process.cwd(), arquivo), origem: c.url, fonte: c.fonte, formato: ext.slice(1), bytes: bytes.length };
+        break;
+    }
+
+    const marca = {};
+    if (principal) marca.cor = principal;
+    if (logo && logo.url) marca.logo = logo.url;
+    return {
+        ok: true,
+        nome: nomeSite || nome,
+        site,
+        frase: frase || null,
+        cores: { principal, paleta },
+        fontes,
+        logo,
+        marca,
+        comoUsar: (Object.keys(marca).length
+            ? `No documento do estúdio: "marca": ${JSON.stringify(marca)}. `
+            : 'Sem cor nem logo confiáveis: use o nome em texto na assinatura e o tema pelo assunto. ')
+            + (fontes.length ? `Fonte da marca: ${fontes[0]} (o estúdio usa a do tema; cite a fonte só se for pedir código/HTML). ` : '')
+            + (logo && !logo.url && logo.formato === 'ico' ? 'A única logo encontrada foi o favicon .ico, que o estúdio não usa — peça o arquivo ao usuário se a peça for de marca. ' : '')
+            + (frase ? `Uma linha sobre a empresa, do próprio site: "${frase}".` : ''),
+        tentativasDeLogo: tentadas.length ? tentadas : undefined,
+    };
+}
+
+module.exports = { marcaDaEmpresa, candidatasALogo, coresDe, fontesDe, metas, atributo };