primocode 8.42.2 → 9.0.0

package/lib/estudio/identidade.js

@@ -0,0 +1,560 @@
+/**
+ * identidade.js — o vídeo a partir de um link.
+ *
+ *   "Eu devo poder mandar só um link: 'analise esse site e faça o vídeo'. A
+ *    IA abre o site, analisa, extrai a identidade visual (cores, tipografia,
+ *    logo, tom), monta o roteiro, planeja a estrutura cena a cena, produz e
+ *    renderiza."
+ *
+ * ── O QUE ESTE MÓDULO FAZ, E O QUE ELE NÃO FAZ ───────────────────────────
+ * Ele FAZ a parte que é medição: baixa a página e as folhas de estilo dela,
+ * conta as cores que realmente aparecem, lê as famílias de fonte declaradas,
+ * acha o logo e recolhe o texto que a marca usa para se descrever.
+ *
+ * Ele NÃO escreve o roteiro nem monta as cenas. Isso é trabalho do modelo, e
+ * um módulo que tentasse fazê-lo viraria um gerador de vídeo padrão — o
+ * problema que este trabalho inteiro está desfazendo.
+ *
+ * A divisão importa: o que sai daqui é FATO sobre a marca (esta cor aparece
+ * 41 vezes, esta fonte é a dos títulos, este é o logo). Fato o modelo não
+ * inventa. O que ele faz com isso é dele.
+ *
+ * ── POR QUE CONTAR A FREQUÊNCIA, E NÃO PEGAR A PRIMEIRA COR ──────────────
+ * Uma folha de estilo tem dezenas de cores, e a primeira delas costuma ser um
+ * cinza de borda. A cor da MARCA é a que se repete — ela está no botão, no
+ * link, no cabeçalho e no rodapé. Contar ocorrências acha a cor certa sem
+ * ninguém precisar dizer qual é.
+ *
+ * Cinzas e quase-pretos são separados das cores com vida, porque um site
+ * qualquer tem muito mais cinza que cor — e a paleta da marca não é cinza.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const referencia = require('../referencia.js');
+const assets = require('./assets.js');
+const marca = require('../marca.js');
+const acervo = require('../acervo.js');
+const http = require('http');
+const { URL } = require('url');
+
+const PRAZO = 15000;
+const MAX_BYTES = 3 * 1024 * 1024;
+
+function buscar(endereco, { redirecoes = 3 } = {}) {
+    return new Promise((resolve, reject) => {
+        let u;
+        try { u = new URL(endereco); } catch { return reject(new Error(`"${endereco}" não é um endereço`)); }
+        const lib = u.protocol === 'https:' ? https : http;
+        const req = lib.get({
+            hostname: u.hostname,
+            port: u.port || undefined,
+            path: u.pathname + u.search,
+            headers: {
+                'User-Agent': 'Mozilla/5.0 (compatible; PrimoCode-Studio/1.0)',
+                Accept: 'text/html,text/css,*/*',
+            },
+        }, (res) => {
+            if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location && redirecoes > 0) {
+                res.resume();
+                return resolve(buscar(new URL(res.headers.location, endereco).toString(), { redirecoes: redirecoes - 1 }));
+            }
+            if (res.statusCode >= 400) { res.resume(); return reject(new Error(`HTTP ${res.statusCode}`)); }
+            let corpo = '';
+            let tamanho = 0;
+            res.setEncoding('utf8');
+            res.on('data', (d) => {
+                tamanho += d.length;
+                // Página gigante não é útil: o que interessa está no começo,
+                // e ler 50 MB de HTML gerado trava o processo por nada.
+                if (tamanho > MAX_BYTES) { req.destroy(); return; }
+                corpo += d;
+            });
+            res.on('end', () => resolve({ corpo, url: endereco }));
+        });
+        const relogio = setTimeout(() => req.destroy(new Error('o site demorou demais')), PRAZO);
+        if (relogio.unref) relogio.unref();
+        req.on('close', () => clearTimeout(relogio));
+        req.on('error', reject);
+    });
+}
+
+// ── cores ────────────────────────────────────────────────────────────────
+
+const HEX = /#([0-9a-f]{3}|[0-9a-f]{6})\b/gi;
+const RGB = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/gi;
+
+function normalizarHex(h) {
+    const s = h.replace('#', '').toLowerCase();
+    const cheio = s.length === 3 ? s.split('').map((x) => x + x).join('') : s;
+    return '#' + cheio;
+}
+
+function paraHex(r, g, b) {
+    return '#' + [r, g, b].map((n) => Math.max(0, Math.min(255, n)).toString(16).padStart(2, '0')).join('');
+}
+
+/** Saturação e luminosidade, para separar cor de cinza. */
+function vivacidade(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const r = (n >> 16) / 255, g = ((n >> 8) & 255) / 255, b = (n & 255) / 255;
+    const max = Math.max(r, g, b), min = Math.min(r, g, b);
+    const lum = (max + min) / 2;
+    const sat = max === min ? 0 : (max - min) / (lum > 0.5 ? 2 - max - min : max + min);
+    return { sat, lum };
+}
+
+function colherCores(css) {
+    const conta = new Map();
+    const somar = (hex) => conta.set(hex, (conta.get(hex) || 0) + 1);
+
+    let m;
+    HEX.lastIndex = 0;
+    while ((m = HEX.exec(css))) somar(normalizarHex(m[0]));
+    RGB.lastIndex = 0;
+    while ((m = RGB.exec(css))) somar(paraHex(+m[1], +m[2], +m[3]));
+
+    const todas = [...conta.entries()]
+        .map(([hex, vezes]) => ({ hex, vezes, ...vivacidade(hex) }))
+        .sort((a, b) => b.vezes - a.vezes);
+
+    // A cor da marca tem saturação e não é quase branca nem quase preta.
+    const declaradas = new Set(variaveisDeCor(css).map((v) => v.cor));
+    // A cor que a marca declarou como tema entra na frente, por mais que ela
+    // apareça poucas vezes no arquivo.
+    const vivas = todas
+        .filter((c) => (c.sat > 0.22 && c.lum > 0.12 && c.lum < 0.9) || declaradas.has(c.hex))
+        .sort((a, b) => (declaradas.has(b.hex) - declaradas.has(a.hex)) || b.vezes - a.vezes);
+    const neutras = todas.filter((c) => c.sat <= 0.22);
+
+    return {
+        marca: vivas.slice(0, 5).map((c) => ({ cor: c.hex, vezes: c.vezes, declarada: declaradas.has(c.hex) })),
+        neutras: neutras.slice(0, 5).map((c) => ({ cor: c.hex, vezes: c.vezes })),
+        variaveis: variaveisDeCor(css).slice(0, 8),
+    };
+}
+
+// ── fontes ───────────────────────────────────────────────────────────────
+
+const GENERICAS = new Set(['inherit', 'initial', 'unset', 'sans-serif', 'serif', 'monospace',
+    'system-ui', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'cursive', 'fantasy',
+    '-apple-system', 'blinkmacsystemfont', 'segoe ui', 'roboto', 'helvetica', 'arial',
+    'helvetica neue', 'apple color emoji', 'segoe ui emoji', 'noto sans', 'liberation sans']);
+
+function colherFontes(css) {
+    const conta = new Map();
+    const re = /font-family\s*:\s*([^;}"]+)/gi;
+    let m;
+    while ((m = re.exec(css))) {
+        for (const bruto of m[1].split(',')) {
+            const nome = bruto.trim().replace(/^["']|["']$/g, '');
+            if (!nome || GENERICAS.has(nome.toLowerCase())) continue;
+            if (nome.startsWith('var(') || nome.length > 40) continue;
+            conta.set(nome, (conta.get(nome) || 0) + 1);
+        }
+    }
+    // O Google Fonts aparece no @import e no <link>: é a pista mais confiável
+    // de qual fonte a marca escolheu, porque ela pagou o carregamento dela.
+    const doGoogle = new Set();
+    const g = /fonts\.googleapis\.com\/css2?\?([^"')]+)/gi;
+    while ((m = g.exec(css))) {
+        for (const par of m[1].split('&')) {
+            const f = par.match(/family=([^:&]+)/);
+            if (f) doGoogle.add(decodeURIComponent(f[1].replace(/\+/g, ' ')));
+        }
+    }
+    return {
+        declaradas: [...conta.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6)
+            .map(([nome, vezes]) => ({ fonte: nome, vezes })),
+        doGoogleFonts: [...doGoogle],
+    };
+}
+
+// ── o resto da identidade ────────────────────────────────────────────────
+
+function tag(html, re) { const m = html.match(re); return m ? m[1].trim() : ''; }
+
+function colherTexto(html) {
+    const titulo = tag(html, /<title[^>]*>([\s\S]{1,200}?)<\/title>/i);
+    const descricao = tag(html, /<meta[^>]+name=["']description["'][^>]+content=["']([^"']{1,400})/i)
+        || tag(html, /<meta[^>]+property=["']og:description["'][^>]+content=["']([^"']{1,400})/i);
+    const marca = tag(html, /<meta[^>]+property=["']og:site_name["'][^>]+content=["']([^"']{1,80})/i);
+
+    // Os títulos da página são o que a marca escolheu dizer primeiro — a
+    // matéria-prima do roteiro, e a única que não é invenção.
+    const titulos = [];
+    const re = /<h([12])[^>]*>([\s\S]{1,160}?)<\/h\1>/gi;
+    let m;
+    while ((m = re.exec(html)) && titulos.length < 14) {
+        const limpo = m[2].replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+        if (limpo.length > 2) titulos.push(limpo);
+    }
+    return { titulo, descricao, marca: marca || titulo.split(/[|\-–—]/)[0].trim(), titulos };
+}
+
+function colherImagens(html, base) {
+    const absoluto = (u) => { try { return new URL(u, base).toString(); } catch { return null; } };
+    const logo = tag(html, /<link[^>]+rel=["'](?:icon|shortcut icon|apple-touch-icon)["'][^>]+href=["']([^"']+)/i)
+        || tag(html, /<img[^>]+(?:class|id|alt)=["'][^"']*logo[^"']*["'][^>]*src=["']([^"']+)/i)
+        || tag(html, /<img[^>]+src=["']([^"']+)["'][^>]*(?:class|id|alt)=["'][^"']*logo/i);
+    const capa = tag(html, /<meta[^>]+property=["']og:image["'][^>]+content=["']([^"']+)/i);
+    return { logo: logo ? absoluto(logo) : null, capa: capa ? absoluto(capa) : null };
+}
+
+/**
+ * Os endereços das folhas de estilo.
+ *
+ * Pegar só `rel="stylesheet"` perde metade dos sites modernos: eles declaram
+ * `rel="preload" as="style"` para carregar antes, e os atributos vêm em
+ * qualquer ordem. Então a regra é mais simples e mais certeira: todo `<link>`
+ * cujo href termina em `.css`.
+ */
+function folhasDe(html, base) {
+    const saida = [];
+    const re = /<link\b[^>]*href=["']([^"']+\.css[^"']*)["'][^>]*>/gi;
+    let m;
+    while ((m = re.exec(html)) && saida.length < 8) {
+        try { saida.push(new URL(m[1], base).toString()); } catch { /* ignora */ }
+    }
+    return [...new Set(saida)];
+}
+
+/**
+ * As cores declaradas como VARIÁVEL de tema (`--brand: #00c86f`).
+ *
+ * Valem mais que a contagem bruta: uma variável de tema é a marca dizendo,
+ * por escrito, qual é a cor dela. Numa folha minificada de 400 KB, a cor do
+ * botão aparece uma vez e o cinza de borda aparece oitenta — a contagem
+ * sozinha elegeria o cinza.
+ */
+function variaveisDeCor(css) {
+    const achadas = [];
+    const re = /--([\w-]*(?:brand|primar|accent|main|theme|color|cor)[\w-]*)\s*:\s*(#[0-9a-f]{3,8}|rgba?\([^)]+\))/gi;
+    let m;
+    while ((m = re.exec(css)) && achadas.length < 12) {
+        const bruto = m[2].trim();
+        const hex = bruto.startsWith('#') ? normalizarHex(bruto)
+            : (() => { const n = bruto.match(/(\d+)\D+(\d+)\D+(\d+)/); return n ? paraHex(+n[1], +n[2], +n[3]) : null; })();
+        if (hex) achadas.push({ nome: '--' + m[1], cor: hex });
+    }
+    return achadas;
+}
+
+/**
+ * Lê um site e devolve a identidade dele, em FATOS.
+ *
+ * O CSS das folhas externas entra na conta junto com o de dentro do HTML:
+ * quase todo site sério põe o tema numa folha à parte, e olhar só o `<style>`
+ * inline devolveria a paleta do menu e mais nada.
+ */
+async function analisar(endereco) {
+    let pagina;
+    try { pagina = await buscar(endereco); }
+    catch (e) { return { ok: false, error: `não consegui abrir o site: ${e.message}` }; }
+
+    const html = pagina.corpo;
+    let css = (html.match(/<style[^>]*>([\s\S]*?)<\/style>/gi) || []).join('\n');
+    css += '\n' + (html.match(/style=["'][^"']+["']/gi) || []).join('\n');
+    css += '\n' + (html.match(/fonts\.googleapis\.com\/css2?\?[^"')]+/gi) || []).join('\n');
+
+    const folhas = folhasDe(html, pagina.url);
+    for (const folha of folhas.slice(0, 4)) {
+        try { css += '\n' + (await buscar(folha)).corpo; } catch { /* uma que falta não impede */ }
+    }
+
+    const texto = colherTexto(html);
+    const cores = colherCores(css);
+
+    /* Site que monta o visual por JavaScript (SPA) entrega HTML quase vazio:
+       a folha de estilo existe, mas o que ela pinta só aparece depois de o
+       navegador rodar o bundle. Medido: o PicPay devolve zero cor por aqui e
+       o Tailwind devolve a paleta inteira.
+       Quando a colheita volta vazia, o caminho não é insistir — é abrir de
+       verdade, e o agente já tem navegador. Dizer isso aqui evita que ele
+       conclua que o site não tem identidade visual. */
+    const porJavaScript = !cores.marca.length;
+
+    return {
+        ok: true,
+        ...(porJavaScript ? {
+            aviso: 'não achei cor de marca no CSS — este site pinta por JavaScript, '
+                + 'e o que ele mostra só existe depois de o navegador rodar.',
+            comoResolver: 'abra com browser_open e leia o que está NA TELA: '
+                + "browser_eval com getComputedStyle nos elementos principais, ou um print com browser_screenshot.",
+        } : {}),
+        url: pagina.url,
+        marca: texto.marca,
+        titulo: texto.titulo,
+        descricao: texto.descricao,
+        // Os títulos da página, que são o que a marca diz de si mesma.
+        frases: texto.titulos,
+        cores,
+        fontes: colherFontes(css),
+        imagens: colherImagens(html, pagina.url),
+        folhasLidas: folhas.slice(0, 4).length,
+        // O HTML cru sai junto para quem vai atrás da logo (pegarLogo) não
+        // precisar baixar a mesma página de novo. Não é para o modelo ver:
+        // `ferramentaSite` tira antes de responder.
+        html,
+    };
+}
+
+/**
+ * O site de uma empresa, a partir do NOME dela.
+ *
+ * ── POR QUE ISTO PRECISA EXISTIR ─────────────────────────────────────────
+ * "Faz um vídeo para a Paris Group" não traz link nenhum. Sem este caminho, o
+ * agente ia inventar as cores da marca — e inventar identidade visual de uma
+ * empresa que existe é o tipo de erro que aparece pronto no vídeo entregue.
+ *
+ * ── POR QUE NÃO UM BUSCADOR NOVO ─────────────────────────────────────────
+ * O `referencia.js` já resolve isto, e resolve com um cuidado que custou
+ * medição: ele só chuta domínio quando o pedido dá SINAL de que fala de um
+ * negócio. Sem essa exigência, "como usar react hooks" viraria react.com e
+ * "como fazer um bolo" viraria fazer.com.
+ *
+ * Um segundo buscador aqui seria uma segunda heurística para manter, e a que
+ * ficasse velha erraria calada. Então o que este módulo faz é acrescentar o
+ * passo que faltava: dos chutes, ficar com o que RESPONDE, e ler a identidade
+ * dele.
+ */
+async function acharSite(nome) {
+    const texto = String(nome || '').trim();
+    if (!texto) return { ok: false, error: 'diga o nome da empresa.' };
+
+    /* O `sitesProvaveis` exige sinal de negócio no texto. Quem chamou aqui já
+       disse que está falando de uma marca — o nome dela é o argumento — então
+       a palavra entra explícita, em vez de a heurística ter de adivinhar de
+       uma palavra solta. */
+    const chutes = referencia.sitesProvaveis(`a empresa "${texto}"`);
+    if (!chutes.length) {
+        return { ok: false, error: `não consegui derivar um domínio de "${texto}".`,
+            comoResolver: 'mande a URL do site direto, se você souber' };
+    }
+
+    const { vivos } = await referencia.chutesVivos(chutes, 2);
+    if (!vivos.length) {
+        return {
+            ok: false,
+            error: `nenhum dos domínios prováveis de "${texto}" respondeu.`,
+            tentados: chutes.slice(0, 6).map((c) => c.url),
+            comoResolver: 'mande a URL do site, ou peça para eu pesquisar com pesquisar_referencia',
+        };
+    }
+    return { ok: true, url: vivos[0].url, outros: vivos.slice(1).map((v) => v.url) };
+}
+
+
+
+/**
+ * Reordena as candidatas sabendo DE QUEM é a logo.
+ *
+ * `candidatasALogo` pontua pelo LUGAR onde a imagem estava (um <img> chamado
+ * "logo" vale mais que o favicon). Isso basta até o site pôr no cabeçalho uma
+ * imagem que É uma logo e NÃO é a dele: o selo do prêmio, o "as seen on", o
+ * parceiro. Medido no nubank.com.br: a primeira candidata era
+ * "brand-finance-wordmark-mono.svg" — a logo da consultoria que premiou o
+ * Nubank. Baixar aquilo e chamar de logo do cliente é erro que só aparece com
+ * o vídeo pronto na frente dele.
+ *
+ * ── ONDE O NOME DA MARCA CONTA, E ONDE ELE ENGANA ────────────────────────
+ * Conta no CAMINHO do arquivo e no `alt`: "/nubank-logo.svg", alt="Logo do
+ * Nubank". Engana no HOST — e engana sempre, porque o host é o mesmo para
+ * TODO asset do site. Na primeira versão disto o casamento valia na URL
+ * inteira, e o resultado foi a Stripe entregar uma foto da Hertz: o arquivo
+ * morava em `images.stripeassets.com`, onde "stripe" está no endereço de
+ * qualquer imagem do site, inclusive das que não são logo nenhuma.
+ *
+ * Por isso: o nome da marca é procurado no caminho e no alt, nunca no host;
+ * e o host serve só para a outra pergunta, a de origem — arquivo servido de
+ * outro domínio registrável, sem o nome da marca no caminho, é de terceiro
+ * até prova em contrário e cai para o fim da fila. Cai, não some: CDN da
+ * própria empresa também é outro domínio, e sem candidata melhor ela
+ * continua valendo.
+ */
+
+// "nubank.com.br" tem raiz "nubank", não "com": sem esta lista, o sufixo
+// composto vira o nome da marca — e aí "com" casa com QUALQUER endereço.
+const SUFIXOS_COMPOSTOS = new Set(['com', 'co', 'org', 'net', 'gov', 'edu', 'ac', 'mil']);
+
+function dominioRegistravel(hostname) {
+    const partes = String(hostname || '').replace(/^www\./, '').split('.');
+    if (partes.length <= 2) return partes.join('.');
+    return SUFIXOS_COMPOSTOS.has(partes[partes.length - 2])
+        ? partes.slice(-3).join('.')     // nubank.com.br
+        : partes.slice(-2).join('.');    // www.stripe.com → stripe.com
+}
+
+function raizDoDominio(hostname) {
+    return dominioRegistravel(hostname).split('.')[0] || '';
+}
+
+// Palavras que aparecem em nome de empresa e não identificam ninguém.
+const VAZIAS = new Set(['about', 'home', 'sobre', 'site', 'www', 'com', 'net', 'org', 'the', 'and',
+    'ltda', 'sa', 'inc', 'group', 'grupo', 'brasil', 'brazil', 'oficial', 'official', 'page', 'pagina']);
+
+function ordenarPelaMarca(candidatas, nome, urlDoSite) {
+    const tokens = new Set(String(nome || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+        .split(/[^a-z0-9]+/).filter((t) => t.length >= 3 && !VAZIAS.has(t)));
+    let host = '';
+    try { host = new URL(urlDoSite).hostname; } catch { /* sem domínio: só o nome decide */ }
+    const raiz = raizDoDominio(host);
+    if (raiz.length >= 3 && !VAZIAS.has(raiz)) tokens.add(raiz);
+    const doSite = dominioRegistravel(host);
+    const lista = [...tokens];
+
+    return candidatas.map((c, i) => {
+        let caminho = c.url;
+        let deFora = false;
+        try {
+            const u = new URL(c.url);
+            caminho = u.pathname + u.search;              // o host fica de FORA de propósito
+            deFora = dominioRegistravel(u.hostname) !== doSite;
+        } catch { /* url torta: compara o texto todo mesmo */ }
+        const alvo = `${caminho} ${c.alt || ''}`.toLowerCase();
+        // `nomeia` é o que separa "a logo deles" de "uma imagem no site
+        // deles". Quem usa isso é `pegarLogo`, para decidir entre entregar
+        // direto e guardar como reserva atrás do Wikimedia Commons.
+        const nomeia = lista.some((t) => alvo.includes(t));
+        let nota = c.nota || 0;
+        if (nomeia) nota += 100;
+        else if (deFora) nota -= 50;
+        return { c: { ...c, nomeia }, nota, i };
+    }).sort((a, b) => (b.nota - a.nota) || (a.i - b.i)).map((x) => x.c);
+}
+
+/**
+ * A LOGO da empresa, baixada para a pasta do projeto.
+ *
+ * ── POR QUE O SITE NÃO É A PRIMEIRA PORTA ────────────────────────────────
+ * A intuição diz "a logo está no site". Ela está — como <svg> INLINE dentro
+ * do cabeçalho, que é como todo site moderno serve a logo, e que não é um
+ * arquivo para baixar. O que sobra em <img> costuma ser outra coisa: medido
+ * ao vivo, o nubank.com.br devolveu a logo da consultoria que premiou o
+ * Nubank e depois uma foto de reunião (o card tinha "brand" na classe); a
+ * stripe.com devolveu uma foto da Hertz; a spotify.com devolveu o print da
+ * tela de download. Três marcas conhecidíssimas, três imagens erradas — e
+ * nenhuma delas erra de um jeito que dê para perceber sem abrir o arquivo.
+ *
+ * Então a ordem é por CONFIANÇA na fonte, não por proximidade do site:
+ *
+ *   1. SIMPLE ICONS (via Iconify) — a marca desenhada, em SVG, conferida por
+ *      gente. Escala sem borrar e é monocromática: a cor entra na cena, o que
+ *      para motion é melhor que um PNG com a cor cravada. Só tem marca
+ *      conhecida, e é justamente onde o chute do site mais erra.
+ *   2. O SITE, quando a imagem DIZ o nome da marca no caminho ou no alt
+ *      ("/nubank-logo.svg", alt="Logo do Nubank"). Aí é a logo de verdade,
+ *      colorida, do dono.
+ *   3. apple-touch-icon — todo site tem, tem 180 px ou mais, e é sempre a
+ *      marca (é o que vira ícone na tela do telefone).
+ *   4. WIKIMEDIA COMMONS — o wordmark colorido das marcas conhecidas.
+ *   5. og:image e favicon — só quando não sobrou nada, e a resposta AVISA o
+ *      que é. Um borrão entregue calado vira um vídeo refeito.
+ *
+ * Nada disso adivinha: cada porta que falha entra em `tentativas`, e o
+ * `aviso` diz o que a logo escolhida tem de errado. O agente precisa poder
+ * decidir usar o nome em texto — que é melhor que uma logo errada.
+ */
+async function pegarLogo(html, urlDoSite, { pasta, nome = 'marca' } = {}) {
+    const tentadas = [];
+    const guardar = (bytes, ext, extra) => {
+        const arquivo = path.join(pasta, 'midia', `logo-${limpar(nome)}${ext}`);
+        fs.mkdirSync(path.dirname(arquivo), { recursive: true });
+        fs.writeFileSync(arquivo, bytes);
+        fs.writeFileSync(arquivo + '.licenca.json', JSON.stringify({
+            titulo: `logo ${nome}`, origem: extra.origem, fonte: extra.achadaEm,
+            licenca: 'marca registrada do titular — o uso depende da autorização dele',
+            quando: new Date().toISOString(),
+        }, null, 2), 'utf8');
+        return {
+            ok: true, src: path.relative(pasta, arquivo).replace(/\\/g, '/'),
+            formato: ext.slice(1), ...extra,
+            tentativas: tentadas.length ? tentadas : undefined,
+        };
+    };
+
+    // 1. Simple Icons: a marca conferida, em SVG.
+    const slug = String(nome).toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]/g, '');
+    if (slug.length >= 2) {
+        const r = await assets.icone(`simple-icons:${slug}`);
+        if (r.ok) {
+            return guardar(Buffer.from(r.svg, 'utf8'), '.svg', {
+                origem: `https://simpleicons.org/?q=${slug}`, achadaEm: 'simple-icons',
+                aviso: 'é o símbolo MONOCROMÁTICO da marca (currentColor): pinte na cena com a cor da '
+                    + 'identidade. Se a peça exigir a logo colorida oficial, peça o arquivo ao usuário.',
+            });
+        }
+        tentadas.push(`simple-icons: não tem "${slug}"`);
+    }
+
+    // 2/3/5. O site — com a ordem corrigida por quem a imagem diz ser.
+    const candidatas = ordenarPelaMarca(marca.candidatasALogo(html, urlDoSite), nome, urlDoSite);
+    let deReserva = null;
+    for (const c of candidatas) {
+        // og:image e favicon ficam GUARDADOS: valem menos que o Commons.
+        const duvidosa = c.fonte === 'og:image' || c.fonte === 'favicon' || c.fonte === 'icon' || !c.nomeia;
+        const bytes = await referencia.pegar(c.url, { timeout: 20000, binario: true });
+        if (!bytes || bytes.length < 200) { tentadas.push(`${c.fonte}: não baixou`); continue; }
+        const ext = assets.extensaoPorConteudo(bytes);
+        if (!ext || !/^\.(svg|png|jpg|webp|gif|ico)$/.test(ext)) { tentadas.push(`${c.fonte}: não é imagem`); continue; }
+        if (duvidosa || ext === '.ico') {
+            if (!deReserva) deReserva = { c, bytes, ext };
+            tentadas.push(`${c.fonte}: não diz o nome da marca, guardado como reserva`);
+            continue;
+        }
+        return guardar(bytes, ext, { origem: c.url, achadaEm: c.fonte });
+    }
+
+    // 4. Wikimedia Commons.
+    try {
+        const doCommons = await acervo.wikimediaLogos(nome, 3);
+        if (doCommons && doCommons.length) {
+            const r = await assets.baixar({ ...doCommons[0], fonte: 'wikimedia' },
+                { pasta, nome: `logo-${limpar(nome)}` });
+            if (r.ok) {
+                return {
+                    ok: true, src: r.relativo,
+                    formato: (r.arquivo.match(/\.([a-z0-9]+)$/i) || [])[1] || null,
+                    origem: doCommons[0].url, achadaEm: 'wikimedia-commons',
+                    aviso: 'veio do Wikimedia Commons, não do site da empresa — confira se é a logo atual.',
+                    tentativas: tentadas.length ? tentadas : undefined,
+                };
+            }
+        }
+    } catch { /* o Commons é porta de reserva; falhar nele não derruba a análise */ }
+
+    // 5. A reserva, dizendo o que ela é.
+    if (deReserva) {
+        return guardar(deReserva.bytes, deReserva.ext, {
+            origem: deReserva.c.url, achadaEm: deReserva.c.fonte,
+            aviso: deReserva.ext === '.ico'
+                ? 'é o FAVICON (.ico, quase sempre 32 px): num quadro 1920x1080 isso é um borrão. '
+                    + 'Use só como referência de forma e cor; na peça, prefira o nome em texto.'
+                : 'esta imagem NÃO diz ser a logo (veio do og:image ou de um <img> que não nomeia a marca): '
+                    + 'pode ser foto de campanha ou print de tela. ABRA o arquivo antes de pôr num fundo limpo — '
+                    + 'se não for a logo, use o nome em texto com a fonte e a cor da identidade.',
+        });
+    }
+
+    return {
+        ok: false,
+        error: 'não achei a logo: nem no Simple Icons, nem no site, nem no Wikimedia Commons.',
+        comoResolver: 'siga sem ela: ponha o nome da empresa em texto, com a fonte e a cor que a análise trouxe. '
+            + 'Se a peça for de marca, peça o arquivo da logo ao usuário.',
+        tentativas: tentadas.length ? tentadas : undefined,
+    };
+}
+
+function limpar(t) {
+    return String(t || '').normalize('NFD').replace(/[̀-ͯ]/g, '')
+        .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'marca';
+}
+
+module.exports = {
+    analisar, acharSite, pegarLogo,
+    colherCores, colherFontes, colherTexto, variaveisDeCor, folhasDe, buscar,
+};