primocode 10.17.1 → 11.0.0

package/lib/comecar.js

@@ -0,0 +1,56 @@
+'use strict';
+/* /comecar: o primeiro app de quem nunca programou.
+   Aqui só mora a função pura que junta as três respostas num pedido. Ela
+   descreve o que a pessoa quer e COMO falar com ela, e nunca escolhe
+   tecnologia: quem decide o caminho é a IA (regra da casa). Citar um
+   framework aqui empurraria todo iniciante para o mesmo lugar, quer o pedido
+   combine com ele ou não. */
+
+const ORIENTACAO = 'Quem pediu nunca programou: explique cada passo em linguagem simples, '
+    + 'sem jargão, e no fim diga como abrir e usar.';
+
+function limpar(v) {
+    return typeof v === 'string' ? v.replace(/\s+/g, ' ').trim().replace(/[.,;:\s]+$/, '') : '';
+}
+
+/* Devolve null quando não há o que criar: sem a primeira resposta não existe
+   pedido, e o chamador cancela com uma linha gentil. Campos pulados somem do
+   texto, para não sobrar "pra , que abre". */
+function montarPedidoComecar({ oque, praQuem, onde } = {}) {
+    const o = limpar(oque);
+    if (!o) return null;
+    const partes = [o];
+    const p = limpar(praQuem);
+    if (p) partes.push(/^(pra|para)\s/i.test(p) ? p : `pra ${p}`);
+    const d = limpar(onde);
+    // "tanto faz" não é uma preferência: a IA escolhe onde abrir.
+    if (d && !/^tanto faz$/i.test(d)) partes.push(/^(que|abre)\b/i.test(d) ? d : `que abre ${d}`);
+    return `${partes.join(', ')}. ${ORIENTACAO}`;
+}
+
+/* Pra quem chega sem ideia: o prompt vazio trava mais que pergunta difícil.
+   São pontos de partida pequenos, que funcionam no primeiro pedido — e só
+   dizem O QUE fazer; o como continua sendo da IA. */
+const IDEIAS = [
+    'uma lista de compras que a família toda edita',
+    'um site da minha loja, com o cardápio e o WhatsApp',
+    'um controle de gastos do mês, com gráfico',
+    'um quiz pra eu estudar pra prova',
+    'uma agenda de clientes com horário marcado',
+    'um joguinho simples pra jogar no celular',
+];
+
+/* A resposta à lista: número escolhe a ideia, texto vale como ideia própria,
+   vazio cancela. */
+function escolherIdeia(resposta) {
+    const r = String(resposta || '').trim();
+    if (!r) return null;
+    const n = Number(r);
+    if (Number.isInteger(n)) return IDEIAS[n - 1] || null;
+    return r;
+}
+
+/* O que dizer logo depois do primeiro app: os dois comandos que salvam quem nunca programou. */
+const DEPOIS_DO_PRIMEIRO_APP = 'Pra ver se o app abre sem erro: /check. Mexeu e quebrou? /restore volta pro último ponto que funcionava.';
+
+module.exports = { montarPedidoComecar, IDEIAS, escolherIdeia, DEPOIS_DO_PRIMEIRO_APP };

package/lib/como-rodar.js

@@ -0,0 +1,66 @@
+/**
+ * como-rodar.js — o /como-rodar: o bloco "Como rodar" do PRIMO.md, escrito sem modelo, pra o dia seguinte.
+ *
+ *   passos(projectDir)          → [{ texto, comando? }]            (lê package.json, a página e o Python)
+ *   bloco(passos)               → o markdown do bloco, entre marcas  (puro)
+ *   gravar(projectDir)          → { arquivo, criou, passos }        (troca só o bloco; o resto do PRIMO.md fica)
+ *
+ * Quem volta ao app no dia seguinte não lembra como abrir ("vibe coding for beginners", tomsguide.com [VERIFICAR]). O
+ * PRIMO.md é lido no começo de todo pedido (o /init escreve ele inteiro, com o modelo); aqui só o pedaço de rodar,
+ * que dá pra tirar do disco sem errar. Rodar de novo substitui o bloco entre as marcas, nunca duplica.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const INICIO = '<!-- primocode:como-rodar -->', FIM = '<!-- /primocode:como-rodar -->';
+const lerJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const TESTE_PADRAO = /no test specified/;
+
+function passos(projectDir) {
+    const out = [];
+    const pkg = lerJson(path.join(projectDir, 'package.json'));
+    if (pkg) {
+        const s = pkg.scripts || {};
+        if (!fs.existsSync(path.join(projectDir, 'node_modules')) && (pkg.dependencies || pkg.devDependencies)) out.push({ texto: 'Instalar as dependências (uma vez só)', comando: 'npm install' });
+        if (s.dev) out.push({ texto: 'Abrir pra mexer (recarrega sozinho)', comando: 'npm run dev' });
+        else if (s.start) out.push({ texto: 'Abrir o app', comando: 'npm start' });
+        if (s.test && !TESTE_PADRAO.test(s.test)) out.push({ texto: 'Conferir se está funcionando', comando: 'npm test' });
+        if (s.build) out.push({ texto: 'Gerar a versão final', comando: 'npm run build' });
+    }
+    if (!out.some((p) => p.comando && /run dev|start/.test(p.comando))) {
+        const pagina = ['index.html', 'public/index.html'].find((f) => fs.existsSync(path.join(projectDir, f)));
+        if (pagina) out.push({ texto: `Abrir ${pagina} no navegador (dois cliques no arquivo), ou /open ${pagina} no PrimoCode` });
+        for (const py of ['main.py', 'app.py']) if (fs.existsSync(path.join(projectDir, py))) out.push({ texto: 'Rodar o programa', comando: `python3 ${py}` });
+    }
+    if (out.length) {
+        out.push({ texto: 'Mostrar no celular de alguém no mesmo Wi-Fi, sem publicar: /show no PrimoCode' });
+        out.push({ texto: 'Ver se ainda funciona depois de mexer: /check; quebrou, /restore' });
+    }
+    return out;
+}
+
+function bloco(lista) {
+    const linhas = [INICIO, '## Como rodar', ''];
+    if (!lista.length) linhas.push('Ainda não deu pra saber como este projeto roda: não tem package.json, index.html nem main.py.');
+    lista.forEach((p, i) => linhas.push(`${i + 1}. ${p.texto}${p.comando ? `: \`${p.comando}\`` : ''}`));
+    linhas.push('', '_Escrito pelo /howto do PrimoCode. Rodar de novo atualiza este bloco._', FIM);
+    return linhas.join('\n');
+}
+
+function gravar(projectDir) {
+    const arquivo = path.join(projectDir, 'PRIMO.md');
+    const lista = passos(projectDir);
+    const novo = bloco(lista);
+    let atual = '';
+    try { atual = fs.readFileSync(arquivo, 'utf8'); } catch { /* nasce agora */ }
+    const i = atual.indexOf(INICIO), f = atual.indexOf(FIM);
+    const texto = i >= 0 && f > i ? atual.slice(0, i) + novo + atual.slice(f + FIM.length)
+        : (atual.trim() ? atual.replace(/\s*$/, '\n\n') : '') + novo + '\n';
+    fs.writeFileSync(arquivo, texto);
+    return { arquivo, criou: !atual, passos: lista };
+}
+
+module.exports = { passos, bloco, gravar, INICIO, FIM };

package/lib/conferir.js

@@ -0,0 +1,117 @@
+/**
+ * conferir.js — o "funcionou / não funcionou" para quem não programa.
+ *
+ * A queixa nº 1 de quem constrói sem saber código é "conserta um, quebra
+ * outro", sem ninguém dizer se o projeto ainda funciona. O `/conferir` acha
+ * sozinho o jeito de testar a pasta (teste, build ou lint), roda e responde
+ * em português simples. Quando passa, o checkpoint marca o ponto como
+ * "funcionava" e o `/voltar` sabe para onde ir.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const tools = require('./tools');
+
+const TIMEOUT = 5 * 60 * 1000;
+/** O `npm init` cria esse script de mentira; rodá-lo sempre "falha" e não diz nada. */
+const TESTE_PADRAO_NPM = /no test specified/i;
+
+function lerJson(arquivo) {
+    try { return JSON.parse(fs.readFileSync(arquivo, 'utf8')); } catch { return null; }
+}
+
+/* Só conta como "tem teste" quando existe arquivo de teste: um pyproject.toml sozinho (todo projeto Python moderno
+   tem) fazia o pytest sair com "no tests ran" e virar "✗ os testes falharam" (achado da revisão de 24/10). */
+const ARQ_TESTE_PY = /^(test_.*|.*_test)\.py$/;
+function temTestePython(projectDir) {
+    const tem = (dir) => { try { return fs.readdirSync(dir).some((f) => ARQ_TESTE_PY.test(f)); } catch { return false; } };
+    return tem(projectDir) || tem(path.join(projectDir, 'tests')) || tem(path.join(projectDir, 'test'));
+}
+
+/** Como testar esta pasta: { comando, rotulo } ou null. Do mais forte (teste)
+    ao mais fraco (lint): um build que passa ainda prova que o projeto monta. */
+/** O gerenciador do projeto: o `packageManager` do package.json, senão o lockfile. `npm test` num projeto pnpm
+    falha por motivo que não é do código (node_modules de outro formato, workspace) e o agente "consertava" o certo. */
+function gerenciador(projectDir, pkg) {
+    const pm = String((pkg && pkg.packageManager) || '').split('@')[0];
+    if (['pnpm', 'yarn', 'bun', 'npm'].includes(pm)) return pm;
+    const tem = (f) => fs.existsSync(path.join(projectDir, f));
+    if (tem('pnpm-lock.yaml')) return 'pnpm';
+    if (tem('yarn.lock')) return 'yarn';
+    if (tem('bun.lock') || tem('bun.lockb')) return 'bun';
+    return 'npm';
+}
+function comandoDo(pm, script) {
+    if (script === 'test') return pm === 'bun' ? 'bun run test' : `${pm} test`;
+    return pm === 'yarn' ? `yarn ${script}` : `${pm} run ${script}`;
+}
+
+function descobrir(projectDir) {
+    const pkg = lerJson(path.join(projectDir, 'package.json'));
+    const scripts = (pkg && pkg.scripts) || {};
+    const pm = pkg ? gerenciador(projectDir, pkg) : 'npm';
+    if (scripts.test && !TESTE_PADRAO_NPM.test(scripts.test)) return { comando: comandoDo(pm, 'test'), rotulo: 'os testes' };
+    if (scripts.build) return { comando: comandoDo(pm, 'build'), rotulo: 'o build' };
+    if (scripts.lint) return { comando: comandoDo(pm, 'lint'), rotulo: 'o lint' };
+    if (temTestePython(projectDir)) return { comando: 'python3 -m pytest -q', rotulo: 'os testes' };
+    if (fs.existsSync(path.join(projectDir, 'Cargo.toml'))) return { comando: 'cargo test', rotulo: 'os testes' };
+    if (fs.existsSync(path.join(projectDir, 'go.mod'))) return { comando: 'go test ./...', rotulo: 'os testes' };
+    return null;
+}
+
+/** Roda o comando na pasta. Mesmo ambiente limpo do run_shell do agente:
+    o que a pessoa vê aqui é o que a IA veria, sem vazar chave para o teste. */
+async function rodar(cmd, projectDir, { timeout = TIMEOUT } = {}) {
+    const env = tools.ambienteLimpo(process.env, tools.permitidasNoShell());
+    // pela mesma cerca do run_shell do agente (lib/sandbox.js): com o /sandbox ligado, o teste também roda dentro dela,
+    // porque o script de teste é código do projeto, que o agente pode ter escrito (achado da revisão de 24/10)
+    const r = await require('./sandbox.js').executar(cmd, { projectDir, timeout, env });
+    // a saída longa guarda o começo, as linhas de falha do meio e o fim (lib/saida.js): o fim sozinho perdia a falha
+    const saida = require('./saida.js').cortar(`${r.stdout || ''}${r.stderr || ''}`.replace(/\s+$/, ''), 3500).split('\n');
+    while (saida.length && !saida[saida.length - 1].trim()) saida.pop();
+    // `estourou`: o prazo matou o comando. Não é "falhou": quem chama não deve julgar o projeto por isso.
+    // O mesmo pro pytest que não achou teste (código 5) ou nem está instalado: não é o projeto que quebrou.
+    const semTeste = /pytest/.test(cmd) && (r.code === 5 || /No module named pytest/.test(`${r.stdout || ''}${r.stderr || ''}`));
+    return { ok: !!r.ok, codigo: r.code, estourou: (!r.ok && !!r.killed) || semTeste, semTeste, saida: saida.join('\n') };
+}
+
+/* Quando o agente roda os testes sozinho, no fim da tarefa (lib/act.js): só se mexeu em arquivo desde a
+   última vez, no máximo 2 vezes por tarefa (entregar, e conferir o conserto), nunca no subagente, e nunca
+   com PRIMOCODE_SEM_TESTE_AUTO=1. Puro. */
+function podeRodarSozinho({ subagent = false, mexeu = false, rodadas = 0, parar = false, modo = 'auto', env = process.env } = {}) {
+    // no "perguntar" a pessoa quer aprovar cada comando, e no "plano" nada roda: rodar sozinho seria passar por cima
+    if (modo === 'perguntar' || modo === 'plano') return false;
+    return !subagent && mexeu && rodadas < 2 && !parar && env.PRIMOCODE_SEM_TESTE_AUTO !== '1';
+}
+const PRAZO_SOZINHO = Number(process.env.PRIMOCODE_PRAZO_TESTE_AUTO) || 2 * 60 * 1000;
+
+const LINHA_DE_ERRO = /error|erro|fail|falh|✗|assert|traceback/i;
+
+/** A resposta para a pessoa. Na falha, só as linhas que explicam (3 a 6): a
+    saída inteira de um build assusta e esconde o motivo. */
+function explicar(r, { rotulo }) {
+    if (r.ok) return { titulo: `Funcionou: ${rotulo} passaram.`, linhas: [] };
+    const todas = String(r.saida || '').split('\n').map((l) => l.trimEnd()).filter((l) => l.trim());
+    let linhas = todas.filter((l) => LINHA_DE_ERRO.test(l)).slice(0, 6);
+    if (linhas.length < 3) {
+        // Achou pouco: a frase do erro mais o que vem logo depois dela (o
+        // trecho do código) explica melhor do que o rabo da saída.
+        const primeira = todas.findIndex((l) => LINHA_DE_ERRO.test(l));
+        linhas = primeira >= 0 ? todas.slice(primeira, primeira + 4) : todas.slice(-6);
+    }
+    return { titulo: `Não funcionou: ${rotulo} falharam.`, linhas };
+}
+
+/* Sem script de teste mas com página (o app que o /comecar faz é index.html): abrir escondido e olhar é o teste
+   que existe (lib/pipeline.js medirNoNavegador, o mesmo olho que o agente usa antes do "pronto"). Puro. */
+function explicarPagina(m) {
+    if (!m || !m.testou) return { ok: false, testou: false, titulo: 'Não consegui abrir a página pra testar.', linhas: m && m.relato ? [String(m.relato).slice(0, 200)] : [] };
+    if (m.limpo) return { ok: true, testou: true, titulo: 'Funcionou: a página abre sem erro.', linhas: [] };
+    const linhas = String(m.relato || '').split('\n').filter((l) => /·|EM BRANCO/.test(l)).map((l) => l.trim()).slice(0, 6);
+    const branco = m.medida && m.medida.vazio;
+    return { ok: false, testou: true, titulo: branco ? 'Não funcionou: a página abre em branco.' : 'Não funcionou: a página abre com erro.', linhas };
+}
+
+module.exports = { descobrir, rodar, explicar, explicarPagina, podeRodarSozinho, PRAZO_SOZINHO };

package/lib/config.js

@@ -338,6 +338,8 @@ function loadConfig() {
         // O /permissoes: quando ele pergunta antes de agir. Dura entre sessões
         // pelo mesmo motivo do modo — quem escolheu "perguntar" quer amanhã também.
         permissoes: file.permissoes || 'auto',
+        // O parceiro do /team (lib/team.js): quem revisa o que o PrimoCode faz. null = sozinho.
+        team: file.team || null,
         rootDir: ROOT_DIR,
         _file: file,
     };
@@ -347,8 +349,8 @@ function saveConfig(partial) {
     ensureDir(CONFIG_DIR);
     const cur = (() => { try { return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8')); } catch { return {}; } })();
     // Só persiste o que faz sentido guardar — nada de campos derivados.
-    const { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes } = { ...cur, ...partial };
-    const next = { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes };
+    const { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes, team } = { ...cur, ...partial };
+    const next = { server, model, effort, token, autoApply, currentProject, userName, mascot, reacoes, theme, mode, permissoes, team };
     fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), 'utf8');
     return next;
 }

package/lib/editor-pro-maquina.js

@@ -0,0 +1,165 @@
+/* A máquina de vídeo do editor: entende cada frase, escolhe gancho e estilo pelo CONTEÚDO (e pela variante),
+   e confere o plano com uma régua numérica (criticar). Sem rede, sem Python: só texto e números.
+   Ver docs/rebuild/editor-maquina-arquitetura.md. */
+'use strict';
+
+const FRACAS = new Set('a o e é de da do das dos em no na nos nas um uma uns umas que para pra por com como eu você ele ela isso esse essa este esta hoje vou vai ou se mas'.split(' '));
+const NEGACAO = /\b(nunca|n[aã]o|ningu[eé]m|nada|jamais|zero|sem)\b/i;
+const NUMERO = /\d|\b(dobro|metade|triplo|mil|milh[aã]o|dez|cem|vinte|trinta)\b/i;
+const PROMESSA = /\b(como|jeito|segredo|passo|m[eé]todo|f[aá]cil|r[aá]pido|grátis|gr[aá]tis|consegui|descobri)\b/i;
+const URGENCIA = /\b(agora|hoje|[uú]ltim[ao]s?|acaba|corre|r[aá]pido|j[aá])\b/i;
+const EMOCAO_FORTE = /\b(erro|medo|perd[ei]|caro|problema|pior|absurdo|chocante|incr[ií]vel|louco|nunca|dobro|segredo)\b/i;
+
+const limpar = (l) => String(l || '').replace(/^[\d.]+-[\d.]+\s+/, '').trim();
+const tempos = (l) => { const m = /^([\d.]+)-([\d.]+)/.exec(String(l || '')); return m ? [Number(m[1]), Number(m[2])] : [null, null]; };
+
+/** O que cada frase quer: intenção, emoção, palavra-chave e energia (0 a 1). Tudo medido no texto. */
+function entenderFrases(fala) {
+    return (fala || []).map((linha, i) => {
+        const texto = limpar(linha);
+        const [t0, t1] = tempos(linha);
+        const palavras = texto.replace(/[.,!?;:]/g, '').split(/\s+/).filter(Boolean);
+        const fortes = palavras.filter((p) => !FRACAS.has(p.toLowerCase()) && (p.length > 2 || /\d/.test(p) || /^[A-ZÀ-Ú]{2}$/.test(p)));
+        const chave = fortes.slice().sort((a, b) => (NUMERO.test(b) - NUMERO.test(a)) || (b.length - a.length))[0] || null;
+        let intencao = 'afirma';
+        if (/\?\s*$/.test(texto)) intencao = 'pergunta';
+        else if (NUMERO.test(texto)) intencao = 'prova';
+        else if (NEGACAO.test(texto)) intencao = 'nega';
+        else if (PROMESSA.test(texto)) intencao = 'promete';
+        else if (URGENCIA.test(texto)) intencao = 'urge';
+        const energia = Math.min(1, 0.25 + (/!/.test(texto) ? 0.25 : 0) + (EMOCAO_FORTE.test(texto) ? 0.25 : 0) + (NUMERO.test(texto) ? 0.15 : 0) + (NEGACAO.test(texto) ? 0.1 : 0));
+        return { i, texto, t0, t1, palavras, fortes, chave, intencao, energia, emocao: energia >= 0.6 ? 'forte' : energia >= 0.4 ? 'media' : 'calma' };
+    }).filter((f) => f.texto);
+}
+
+const marcar = (ps, ult) => (ps.length ? ps.join(' ') + ' ' : '') + `*${ult}*`;
+
+/** Candidatos a gancho, de tipos DIFERENTES, tirados das primeiras frases (o gancho pode nascer de qualquer uma). */
+function ganchosCandidatos(fala) {
+    const frases = entenderFrases(fala);
+    const out = [];
+    const jaTem = new Set();
+    const por = (tipo, f, nota, fn) => {
+        if (!f || !f.fortes.length) return;
+        const texto = fn(f);
+        if (!texto || jaTem.has(texto.toLowerCase())) return;
+        jaTem.add(texto.toLowerCase());
+        out.push({ tipo, texto, de: f.i, nota });
+    };
+    for (const f of frases.slice(0, 6)) {
+        if (f.intencao === 'prova') por('numero', f, 3 + f.energia, (x) => { const c = x.fortes.find((p) => NUMERO.test(p)) || x.chave; const ix = x.fortes.indexOf(c); return marcar(x.fortes.slice(Math.max(0, ix - 2), ix), c); });
+        if (f.intencao === 'nega') por('negacao', f, 2.5 + f.energia, (x) => marcar(x.fortes.slice(-3, -1), x.fortes[x.fortes.length - 1]));
+        if (f.intencao === 'pergunta') por('pergunta', f, 2 + f.energia, (x) => marcar(x.fortes.slice(0, 3).slice(0, -1), x.fortes.slice(0, 3).slice(-1)[0]));
+        if (f.intencao === 'promete') por('promessa', f, 2 + f.energia, (x) => marcar(x.fortes.slice(0, 3), x.chave || x.fortes[x.fortes.length - 1]).replace(/\*\*/g, '*'));
+        if (f.intencao === 'urge') por('urgencia', f, 1.5 + f.energia, (x) => marcar(x.fortes.slice(-3, -1), x.fortes[x.fortes.length - 1]));
+    }
+    if (frases[0]) por('palavra-forte', frases[0], 1, (x) => { const fs = x.fortes.slice(-4); const u = fs.pop(); return marcar(fs, u); });
+    return out.sort((a, b) => b.nota - a.nota);
+}
+
+/** O gancho da variante `variante` (0 = o de maior nota; 1 = o próximo TIPO; e assim por diante, girando). */
+function escolherGancho(fala, variante = 0) {
+    const c = ganchosCandidatos(fala);
+    if (!c.length) return null;
+    return c[((variante % c.length) + c.length) % c.length].texto;
+}
+
+const hash = (s) => { let h = 2166136261; for (const ch of String(s)) { h ^= ch.charCodeAt(0); h = Math.imul(h, 16777619); } return h >>> 0; };
+
+/** O estilo vem da energia do que é dito, não de um padrão fixo: conteúdo forte pede escuro/laranja; calmo, limpo.
+    A variante gira entre os estilos que servem, e o mesmo roteiro sempre dá a mesma resposta (sem sorteio). */
+function escolherEstilo(fala, variante = 0) {
+    const fr = entenderFrases(fala);
+    const e = fr.length ? fr.reduce((s, f) => s + f.energia, 0) / fr.length : 0.3;
+    const ordem = e >= 0.55 ? ['laranja', 'noite', 'papelaria', 'limpo'] : e >= 0.38 ? ['noite', 'laranja', 'limpo', 'papelaria'] : ['limpo', 'papelaria', 'noite', 'laranja'];
+    const sal = hash(fr.map((f) => f.texto).join('|')) % 2;
+    return ordem[(variante + sal) % ordem.length];
+}
+
+// ── a régua (autocrítica) ────────────────────────────────────────────────
+
+const REGUA = {
+    parado_max_s: 3.0,            // nenhum trecho maior que isso sem mudança visual
+    tratamentos_min_por_min: 12,  // eventos visuais (peça, bloco, zoom) por minuto
+    tipos_distintos_min: 4,       // famílias de tratamento diferentes no vídeo
+    sfx_no_corte_s: 0.15,         // todo corte de bloco tem som a até 150 ms
+    sfx_min_por_min: 10,          // camadas de som por minuto
+    gancho_ate_s: 1.0,            // o gancho aparece no primeiro segundo
+    zooms_distintos_min: 3,       // escalas de enquadramento diferentes
+    legenda_sobre_rosto: 0,       // trechos com texto sobre o rosto
+};
+const POS_ROSTO = new Set(['centro', 'rosto', 'meio-rosto']);
+const num = (x) => (typeof x === 'number' && isFinite(x) ? x : null);
+
+/** Pontos do tempo em que a imagem muda: começo e fim de peça, bloco e zoom. */
+function mudancasVisuais(cfg, duracao) {
+    const pts = [0, duracao];
+    const tipos = new Set();
+    let eventos = 0;
+    for (const a of cfg.animacoes || []) {
+        const e = num(a.em) ?? num(a.depois_de); const s = num(a.sai);
+        if (e != null) { pts.push(e); eventos++; } if (s != null) pts.push(s);
+        tipos.add('anim:' + (a.tipo || '?'));
+    }
+    for (const b of cfg.blocos || []) {
+        const d = num(b.de); const t = num(b.ate);
+        if (d != null) { pts.push(d); eventos++; } if (t != null) pts.push(t);
+        tipos.add('bloco:' + (b.cena || '?'));
+        for (const z of b.zooms || []) { if (num(z.em) != null) { pts.push(z.em); eventos++; } if (num(z.ate) != null) pts.push(z.ate); tipos.add('punch'); }
+    }
+    return { pts: pts.filter((p) => p >= 0 && p <= duracao).sort((a, b) => a - b), tipos, eventos };
+}
+
+/** Dá nota (0 a 100) a um plano montado (o projeto.json) e devolve as falhas, cada uma com o número e o que fazer. */
+function criticar(cfg, { duracao } = {}, regua = REGUA) {
+    const dur = duracao || Math.max(0, ...(cfg.blocos || []).map((b) => num(b.ate) || 0), ...(cfg.animacoes || []).map((a) => num(a.sai) || 0));
+    const falhas = [];
+    const m = {};
+    if (!dur) return { nota: 0, falhas: [{ regra: 'duracao', valor: 0, limite: '>0', conserto: 'sem duração não há o que conferir' }], metricas: m };
+    const { pts, tipos, eventos } = mudancasVisuais(cfg, dur);
+    let parado = 0; let onde = 0;
+    for (let k = 1; k < pts.length; k++) if (pts[k] - pts[k - 1] > parado) { parado = pts[k] - pts[k - 1]; onde = pts[k - 1]; }
+    m.parado_max_s = Math.round(parado * 100) / 100;
+    if (parado > regua.parado_max_s) falhas.push({ regra: 'parado_max_s', valor: m.parado_max_s, limite: regua.parado_max_s, em: onde, conserto: `ponha peça, zoom ou b-roll a partir de ${onde.toFixed(1)} s` });
+    m.tratamentos_por_min = Math.round((eventos / dur) * 60 * 10) / 10;
+    if (m.tratamentos_por_min < regua.tratamentos_min_por_min) falhas.push({ regra: 'tratamentos_por_min', valor: m.tratamentos_por_min, limite: regua.tratamentos_min_por_min, conserto: 'mais mudanças de imagem ligadas ao que se diz' });
+    m.tipos_distintos = tipos.size;
+    if (tipos.size < regua.tipos_distintos_min) falhas.push({ regra: 'tipos_distintos', valor: tipos.size, limite: regua.tipos_distintos_min, conserto: 'misture famílias: lettering, moldura, contador, b-roll, punch' });
+    const sons = (cfg.sons || []).map((s) => num(s.em)).filter((x) => x != null);
+    m.sfx_por_min = Math.round((sons.length / dur) * 60 * 10) / 10;
+    if (m.sfx_por_min < regua.sfx_min_por_min) falhas.push({ regra: 'sfx_por_min', valor: m.sfx_por_min, limite: regua.sfx_min_por_min, conserto: 'rode o plano_sfx com --variar e mais camadas' });
+    const cortes = (cfg.blocos || []).map((b) => num(b.de)).filter((x) => x != null && x > 0.05);
+    const semSom = cortes.filter((c) => !sons.some((s) => Math.abs(s - c) <= regua.sfx_no_corte_s));
+    m.cortes_sem_som = semSom.length;
+    if (semSom.length) falhas.push({ regra: 'sfx_no_corte', valor: semSom.length, limite: 0, em: semSom[0], conserto: `som nos cortes: ${semSom.slice(0, 4).join(', ')} s` });
+    const g = (cfg.animacoes || []).find((a) => a.id === 'gancho' || a.tipo === 'lettering');
+    m.gancho_em_s = g ? num(g.em) : null;
+    if (!g || (num(g.em) ?? 99) > regua.gancho_ate_s) falhas.push({ regra: 'gancho_ate_s', valor: m.gancho_em_s, limite: regua.gancho_ate_s, conserto: 'o gancho entra no primeiro segundo' });
+    const escalas = new Set();
+    for (const b of cfg.blocos || []) { if (num(b.zoom) != null) escalas.add(b.zoom); for (const z of b.zooms || []) if (num(z.escala) != null) escalas.add(z.escala); }
+    m.zooms_distintos = escalas.size;
+    if (escalas.size < regua.zooms_distintos_min) falhas.push({ regra: 'zooms_distintos', valor: escalas.size, limite: regua.zooms_distintos_min, conserto: 'varie o enquadramento (mais de duas escalas)' });
+    const sobreRosto = (cfg.animacoes || []).filter((a) => POS_ROSTO.has(a.posicao) || a.cobre_rosto === true);
+    m.texto_sobre_rosto = sobreRosto.length;
+    if (sobreRosto.length > regua.legenda_sobre_rosto) falhas.push({ regra: 'texto_sobre_rosto', valor: sobreRosto.length, limite: regua.legenda_sobre_rosto, conserto: 'mova o texto para baixo do rosto ou ponha o rosto em moldura' });
+    const nota = Math.max(0, Math.round(100 - falhas.length * (100 / 8)));
+    return { nota, passou: falhas.length === 0, falhas, metricas: m };
+}
+
+/** Duas variantes não podem abrir igual nem ter o mesmo jeito (gancho, estilo e ritmo). */
+function compararVariantes(cfgs) {
+    const falhas = [];
+    const sig = (c) => {
+        const g = (c.animacoes || []).find((a) => a.id === 'gancho');
+        const t = (c.blocos || []).length;
+        return { gancho: g ? JSON.stringify(g.principal || g.texto || g.titulo || '').toLowerCase() : '', estilo: c.estilo || '', ritmo: Math.round(t / 3) };
+    };
+    const s = cfgs.map(sig);
+    for (let a = 0; a < s.length; a++) for (let b = a + 1; b < s.length; b++) {
+        if (s[a].gancho && s[a].gancho === s[b].gancho) falhas.push({ regra: 'mesmo_gancho', entre: [a, b], valor: s[a].gancho });
+        if (s[a].estilo === s[b].estilo && s[a].ritmo === s[b].ritmo) falhas.push({ regra: 'mesmo_estilo_e_ritmo', entre: [a, b], valor: `${s[a].estilo}/${s[a].ritmo}` });
+    }
+    return { passou: falhas.length === 0, falhas };
+}
+
+module.exports = { REGUA, entenderFrases, ganchosCandidatos, escolherGancho, escolherEstilo, criticar, compararVariantes, mudancasVisuais };