primocode 10.15.2 → 10.17.0

package/lib/editor-pro.js

@@ -0,0 +1,786 @@
+/**
+ * editor-pro.js — o motor de edição de VÍDEO FALADO do PrimoCode.
+ *
+ *   "ficou muito bom a edição do EDIT IA PRO; pode usar só ele pra edição,
+ *    toda a arquitetura dele, os arquivos e tudo" (Joel, 20/10/2026)
+ *
+ * O motor é o EDIT IA PRO (SHK Soluções Digitais), usado com autorização por
+ * escrito do autor (19/10/2026), com o crédito em LICENSES/edit-ia-pro.txt.
+ * Ele mora em `editor/` com a arquitetura dele: os helpers Python medem e
+ * fazem o trabalho pesado (transcrição, corte pela onda, voz, rosto, sons,
+ * portão), o projeto HyperFrames (`editor/modelo-projeto`) monta a edição
+ * (legenda animada, câmera viva, peças, b-roll) e renderiza.
+ *
+ * ── ONDE AS COISAS FICAM ────────────────────────────────────────────────
+ *   editor/                    no pacote: só texto (helpers, modelo, guias)
+ *   ~/.primocode/editor/<fp>/  a cópia que roda, com os arquivos grandes
+ *                              (modelos, fontes, sons) baixados na primeira
+ *                              edição e conferidos pelo sha256
+ *   ~/.primocode/editor/cache/ cada arquivo baixado, pelo sha256 (uma
+ *                              atualização do PrimoCode não baixa de novo)
+ *   ~/.primocode/editor-venv/  o Python do editor: venv próprio, criado sob
+ *                              demanda (uv se existir, senão venv + pip).
+ *                              Nada no Python do sistema.
+ *
+ * ── O CAMINHO ───────────────────────────────────────────────────────────
+ *   cortar  transcreve, monta o corte (a última tomada inteira de cada
+ *           frase), mede e aplica o GANHO POR TRECHO (a voz baixa chega no
+ *           alvo antes do loudnorm, que fica linear), corta os respiros pela
+ *           onda, renderiza, limpa a voz e confere. Devolve a fala do corte
+ *           com os tempos: é com ela que o modelo escreve o plano.
+ *   montar  cria o projeto HyperFrames, aplica o plano (gancho, peças,
+ *           b-roll, blocos), câmera viva, sons casados com cada animação,
+ *           renderiza, mixa a trilha com ducking e roda o PORTÃO. Só entrega
+ *           com PASSOU.
+ *   editar  os dois de uma vez. Sem plano, o plano automático entra (gancho
+ *           da primeira frase + as peças que a fala pede).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn, spawnSync } = require('child_process');
+
+const ORIGEM = path.join(__dirname, '..', 'editor');
+const casa = () => process.env.PRIMOCODE_EDITOR_CASA || path.join(os.homedir(), '.primocode', 'editor');
+const venvDir = () => process.env.PRIMOCODE_EDITOR_VENV || path.join(os.homedir(), '.primocode', 'editor-venv');
+const WIN = process.platform === 'win32';
+const venvPython = (v = venvDir()) => path.join(v, WIN ? 'Scripts' : 'bin', WIN ? 'python.exe' : 'python');
+const MANIFESTO = () => JSON.parse(fs.readFileSync(path.join(ORIGEM, 'assets', 'baixar.json'), 'utf8'));
+
+const VIDEO_EXT = /\.(mov|mp4|m4v|mkv|webm)$/i;
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex');
+const sha256Arquivo = (p) => sha256(fs.readFileSync(p));
+const r3 = (x) => Math.round(x * 1000) / 1000;
+const falar = (ctx) => (ctx && typeof ctx.progresso === 'function') ? ctx.progresso : ((m) => { try { process.stderr.write(`  · ${m}\n`); } catch { /* sem terminal */ } });
+
+// ── 1. os arquivos do editor ─────────────────────────────────────────────
+
+function listar(dir, base = dir, out = []) {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (e.name === '__pycache__' || e.name === '.DS_Store') continue;
+        const p = path.join(dir, e.name);
+        if (e.isDirectory()) listar(p, base, out);
+        else out.push(path.relative(base, p));
+    }
+    return out.sort();
+}
+
+/** A impressão digital da pasta `editor/` do pacote: muda quando um helper muda, e a cópia que roda é refeita. */
+function impressao(origem = ORIGEM) {
+    const h = crypto.createHash('sha1');
+    for (const rel of listar(origem)) h.update(rel + ':' + fs.statSync(path.join(origem, rel)).size + '\n');
+    return h.digest('hex').slice(0, 12);
+}
+
+async function baixarUrl(url) {
+    if (/^(file:\/\/|\/)/.test(url) || /^[A-Za-z]:\\/.test(url)) return fs.readFileSync(url.replace(/^file:\/\//, ''));
+    const r = await fetch(url, { redirect: 'follow' });
+    if (!r.ok) throw new Error(`HTTP ${r.status} em ${url}`);
+    return Buffer.from(await r.arrayBuffer());
+}
+
+/** De onde vem um arquivo do grupo `espelho`: PRIMOCODE_EDITOR_ESPELHO (pasta local ou URL) ou o espelho do manifesto. */
+function urlDoEspelho(item, manifesto) {
+    const base = process.env.PRIMOCODE_EDITOR_ESPELHO || manifesto.espelho;
+    if (!base) return null;
+    if (/^https?:\/\//.test(base)) return base.replace(/\/?$/, '/') + item.caminho;
+    return path.join(base, item.caminho);
+}
+
+/**
+ * Um arquivo do manifesto no lugar, conferido. Cache por sha256 em ~/.primocode/editor/cache.
+ * deps.baixar(url) → Buffer (testes).
+ */
+async function garantirArquivo(destino, item, manifesto, { deps = {} } = {}) {
+    const alvo = path.join(destino, item.caminho);
+    if (fs.existsSync(alvo) && fs.statSync(alvo).size === item.bytes && sha256Arquivo(alvo) === item.sha256) return { ok: true, ja: true };
+    const cache = path.join(casa(), 'cache', item.sha256);
+    let buf = null;
+    if (fs.existsSync(cache)) {
+        const b = fs.readFileSync(cache);
+        if (sha256(b) === item.sha256) buf = b;
+    }
+    if (!buf) {
+        const url = item.url || urlDoEspelho(item, manifesto);
+        if (!url) return { ok: false, error: `sem origem para ${item.caminho}` };
+        const b = await (deps.baixar || baixarUrl)(url);
+        const got = sha256(b);
+        if (got !== item.sha256) return { ok: false, error: `sha256 de ${item.caminho} não confere (veio ${got.slice(0, 12)}…, esperado ${item.sha256.slice(0, 12)}…)` };
+        fs.mkdirSync(path.dirname(cache), { recursive: true });
+        fs.writeFileSync(cache, b);
+        buf = b;
+    }
+    fs.mkdirSync(path.dirname(alvo), { recursive: true });
+    fs.writeFileSync(alvo, buf);
+    return { ok: true };
+}
+
+/**
+ * A cópia do editor que roda, com os arquivos grandes. Idempotente: na segunda vez só confere a marca.
+ * grupos: 'essencial' sempre; 'espelho' quando pedido (tela verde, kit de sons), sem falhar a edição.
+ */
+async function instalarArquivos({ ctx, deps = {}, espelho = false } = {}) {
+    const dizer = falar(ctx);
+    const fp = impressao();
+    const destino = path.join(casa(), fp);
+    const marca = path.join(destino, '.primocode-pronto.json');
+    const manifesto = MANIFESTO();
+    let estado = null;
+    try { estado = JSON.parse(fs.readFileSync(marca, 'utf8')); } catch { /* primeira vez */ }
+    if (!estado) {
+        dizer('preparando o editor de vídeo (só na primeira vez): copiando os arquivos…');
+        fs.mkdirSync(destino, { recursive: true });
+        fs.cpSync(ORIGEM, destino, { recursive: true, filter: (s) => !/__pycache__|\.DS_Store$/.test(s) });
+        const essenciais = manifesto.arquivos.filter((a) => a.grupo === 'essencial' && !a.gerado);
+        const mb = (essenciais.reduce((s, a) => s + a.bytes, 0) / 1048576).toFixed(0);
+        dizer(`baixando os sons, as fontes e o modelo de rosto (${mb} MB, conferidos um a um)…`);
+        const falhas = [];
+        let feitos = 0;
+        await Promise.all(Array.from({ length: 6 }, async () => {
+            while (essenciais.length) {
+                const it = essenciais.shift();
+                try {
+                    const r = await garantirArquivo(destino, it, manifesto, { deps });
+                    if (!r.ok) falhas.push(r.error);
+                } catch (e) { falhas.push(`${it.caminho}: ${e.message}`); }
+                feitos++;
+            }
+        }));
+        if (falhas.length) return { ok: false, error: `não consegui baixar ${falhas.length} arquivo(s) do editor: ${falhas.slice(0, 3).join('; ')}`, destino };
+        estado = { fp, em: new Date().toISOString(), arquivos: feitos, espelho: false, gerados: false };
+        fs.writeFileSync(marca, JSON.stringify(estado, null, 1));
+        // a cópia de uma versão anterior do editor sai (os arquivos grandes ficam no cache)
+        for (const d of fs.readdirSync(casa())) {
+            if (d !== fp && d !== 'cache' && /^[0-9a-f]{12}$/.test(d)) { try { fs.rmSync(path.join(casa(), d), { recursive: true, force: true }); } catch { /* em uso */ } }
+        }
+    }
+    const avisos = [];
+    if (espelho && !estado.espelho) {
+        const extras = manifesto.arquivos.filter((a) => a.grupo === 'espelho');
+        let ok = 0;
+        for (const it of extras) {
+            try { const r = await garantirArquivo(destino, it, manifesto, { deps }); if (r.ok) ok++; else avisos.push(r.error); }
+            catch (e) { avisos.push(`${it.caminho}: ${e.message}`); }
+        }
+        if (ok === extras.length) { estado.espelho = true; fs.writeFileSync(marca, JSON.stringify(estado, null, 1)); }
+        else avisos.unshift(`${extras.length - ok} arquivo(s) extra(s) do editor não vieram (tela verde e o kit de sons reserva ficam de fora)`);
+    }
+    return { ok: true, destino, avisos };
+}
+
+/** Os sons que o próprio editor gera (make_sfx, semente fixa): refeitos no lugar e conferidos pelo sha256. */
+function gerarSintetizados(destino, py, { ctx } = {}) {
+    const marca = path.join(destino, '.primocode-pronto.json');
+    let estado = {};
+    try { estado = JSON.parse(fs.readFileSync(marca, 'utf8')); } catch { /* sem marca */ }
+    if (estado.gerados) return { ok: true, ja: true };
+    const itens = MANIFESTO().arquivos.filter((a) => a.gerado === 'make_sfx');
+    if (!itens.length) return { ok: true };
+    falar(ctx)('gerando os efeitos sintéticos do editor…');
+    const dir = path.join(destino, 'assets', 'sfx', 'sinteticos');
+    const r = spawnSync(py, [path.join(destino, 'helpers', 'make_sfx.py'), '--out-dir', dir], { cwd: destino, encoding: 'utf8', timeout: 300000, env: ambiente(destino, py) });
+    if (r.status !== 0) return { ok: false, error: 'o make_sfx falhou: ' + String(r.stderr || r.stdout).slice(-300) };
+    const errados = itens.filter((it) => { const p = path.join(destino, it.caminho); return !fs.existsSync(p) || sha256Arquivo(p) !== it.sha256; }).map((it) => it.caminho);
+    estado.gerados = true;
+    if (errados.length) estado.geradosDiferentes = errados;
+    fs.writeFileSync(marca, JSON.stringify(estado, null, 1));
+    return { ok: true, diferentes: errados };
+}
+
+// ── 2. o Python do editor ────────────────────────────────────────────────
+
+function acharUv() {
+    if (process.env.PRIMOCODE_EDITOR_UV) return process.env.PRIMOCODE_EDITOR_UV === 'nenhum' ? null : process.env.PRIMOCODE_EDITOR_UV;
+    const cands = [path.join(os.homedir(), '.local', 'bin', WIN ? 'uv.exe' : 'uv'), path.join(os.homedir(), '.cargo', 'bin', 'uv'), '/opt/homebrew/bin/uv', '/usr/local/bin/uv'];
+    try { const r = spawnSync(WIN ? 'where' : 'which', ['uv'], { encoding: 'utf8', timeout: 5000 }); if (r.status === 0) cands.unshift(r.stdout.split('\n')[0].trim()); } catch { /* sem which */ }
+    return cands.find((c) => c && fs.existsSync(c)) || null;
+}
+
+/** Um Python 3.10 a 3.13 do sistema (o pyproject do editor pede >=3.10,<3.14), só para criar o venv. */
+function acharPython() {
+    if (process.env.PRIMOCODE_EDITOR_PY_SISTEMA) return process.env.PRIMOCODE_EDITOR_PY_SISTEMA;
+    const nomes = WIN ? ['py', 'python', 'python3'] : ['python3.12', 'python3.11', 'python3.13', 'python3.10', 'python3', '/opt/homebrew/bin/python3.12', '/opt/homebrew/bin/python3.11', '/usr/local/bin/python3.12'];
+    for (const n of nomes) {
+        try {
+            const v = spawnSync(n, ['-c', 'import sys;print(sys.version_info[0],sys.version_info[1])'], { encoding: 'utf8', timeout: 8000 });
+            if (v.status !== 0) continue;
+            const [a, b] = v.stdout.trim().split(/\s+/).map(Number);
+            if (a === 3 && b >= 10 && b <= 13) return n;
+        } catch { /* próximo */ }
+    }
+    return null;
+}
+
+/** As dependências do pyproject.toml do editor (com os marcadores de sistema: o pip os entende). */
+function dependencias(pyproject) {
+    const txt = fs.readFileSync(pyproject, 'utf8');
+    const m = txt.match(/dependencies\s*=\s*\[([\s\S]*?)\n\]/);
+    if (!m) return [];
+    return [...m[1].matchAll(/^\s*"([^"]+)"\s*,?\s*$/gm)].map((x) => x[1]);
+}
+
+function correr(cmd, args, opts = {}) {
+    return new Promise((resolve) => {
+        let saida = '';
+        let p;
+        try { p = spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] }); }
+        catch (e) { resolve({ code: -1, saida: e.message }); return; }
+        const pega = (d) => { saida += d.toString(); if (saida.length > 400000) saida = saida.slice(-200000); if (opts.aoLer) opts.aoLer(d.toString()); };
+        p.stdout.on('data', pega);
+        p.stderr.on('data', pega);
+        let timer = null;
+        if (opts.timeout) timer = setTimeout(() => { try { p.kill('SIGKILL'); } catch { /* já foi */ } saida += `\n[parado: passou de ${Math.round(opts.timeout / 1000)} s]`; }, opts.timeout);
+        p.on('error', (e) => { if (timer) clearTimeout(timer); resolve({ code: -1, saida: saida + e.message }); });
+        p.on('close', (code) => { if (timer) clearTimeout(timer); resolve({ code, saida }); });
+    });
+}
+
+/**
+ * O venv do editor, criado sob demanda. Marca em <venv>/.primocode-editor.json com o sha do pyproject: mudou a
+ * lista de bibliotecas, sincroniza de novo. deps: { uv, pythonSistema, correr } (testes).
+ */
+async function garantirVenv(destino, { ctx, deps = {} } = {}) {
+    const dizer = falar(ctx);
+    const v = venvDir();
+    const py = venvPython(v);
+    const pyproject = path.join(destino, 'pyproject.toml');
+    const assinatura = sha256Arquivo(pyproject).slice(0, 16);
+    const marca = path.join(v, '.primocode-editor.json');
+    try {
+        const m = JSON.parse(fs.readFileSync(marca, 'utf8'));
+        if (m.pyproject === assinatura && fs.existsSync(py)) return { ok: true, python: py, ja: true };
+    } catch { /* sem marca */ }
+    const run = deps.correr || correr;
+    const uv = deps.uv !== undefined ? deps.uv : acharUv();
+    dizer('instalando as bibliotecas do editor num Python só dele (só na primeira vez; uns minutos)…');
+    let jeito;
+    if (uv) {
+        jeito = 'uv';
+        const env = { ...process.env, UV_PROJECT_ENVIRONMENT: v };
+        const r = await run(uv, ['sync', '--frozen', '--project', destino], { env, cwd: destino, timeout: 1800000 });
+        if (r.code !== 0) return { ok: false, error: 'o uv não conseguiu instalar as bibliotecas do editor: ' + String(r.saida).trim().split('\n').slice(-3).join(' ') };
+    } else {
+        jeito = 'pip';
+        const base = deps.pythonSistema !== undefined ? deps.pythonSistema : acharPython();
+        if (!base) return { ok: false, error: 'o editor precisa do Python 3.10 a 3.13 (ou do uv). No Mac: brew install uv · no Windows: winget install astral-sh.uv' };
+        const r1 = await run(base, ['-m', 'venv', v], { timeout: 300000 });
+        if (r1.code !== 0) return { ok: false, error: 'não consegui criar o venv do editor: ' + String(r1.saida).slice(-300) };
+        // PEP 668: o pip roda DENTRO do venv do editor, então não precisa (nem deve) usar --break-system-packages
+        const r2 = await run(py, ['-m', 'pip', 'install', '--quiet', '--disable-pip-version-check', ...dependencias(pyproject)], { timeout: 1800000 });
+        if (r2.code !== 0) return { ok: false, error: 'o pip não conseguiu instalar as bibliotecas do editor: ' + String(r2.saida).trim().split('\n').slice(-3).join(' ') };
+    }
+    if (!fs.existsSync(py)) return { ok: false, error: `o venv do editor não ficou de pé (${py} não existe)` };
+    fs.mkdirSync(v, { recursive: true });
+    fs.writeFileSync(marca, JSON.stringify({ pyproject: assinatura, jeito, em: new Date().toISOString() }, null, 1));
+    dizer(`Python do editor pronto (${jeito}).`);
+    return { ok: true, python: py, jeito };
+}
+
+function ambiente(destino, py) {
+    const env = { ...process.env, PYTHONUNBUFFERED: '1', PYTHONIOENCODING: 'utf-8', PRIMOCODE_EDITOR_PYTHON: py, UV_PROJECT_ENVIRONMENT: venvDir() };
+    // o npx do HyperFrames chama o node da mesma pasta: o Node que roda o PrimoCode vai na frente
+    env.PATH = [path.dirname(process.execPath), '/opt/homebrew/bin', '/usr/local/bin', env.PATH || ''].join(path.delimiter);
+    return env;
+}
+
+/** Tudo de pé: arquivos, venv, sons gerados, ffmpeg. Devolve { ok, destino, python }. */
+async function garantir({ ctx, deps = {}, espelho = false } = {}) {
+    const ff = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8', timeout: 8000, env: ambiente('', '') });
+    if (ff.status !== 0 && !deps.semFfmpeg) return { ok: false, error: 'o editor precisa do ffmpeg. No Mac: brew install ffmpeg · no Windows: winget install Gyan.FFmpeg' };
+    const a = await instalarArquivos({ ctx, deps, espelho });
+    if (!a.ok) return a;
+    const v = await garantirVenv(a.destino, { ctx, deps });
+    if (!v.ok) return v;
+    const g = deps.semGerar ? { ok: true } : gerarSintetizados(a.destino, v.python, { ctx });
+    return { ok: true, destino: a.destino, python: v.python, avisos: [...(a.avisos || []), ...(g.ok ? [] : [g.error])] };
+}
+
+// ── 3. rodar um helper ───────────────────────────────────────────────────
+
+/** Roda helpers/<nome>.py com o Python do editor. { ok, code, saida }. */
+async function helper(E, nome, args, { timeout = 1800000, cwd, ctx, mostrar = false } = {}) {
+    const arq = path.join(E.destino, 'helpers', nome.endsWith('.py') ? nome : nome + '.py');
+    const aoLer = mostrar ? ((t) => t.split('\n').filter((l) => /^(ok|baixando|recortando|transcrevendo|render|\s*\d+%)/i.test(l.trim())).forEach((l) => falar(ctx)(l.trim()))) : undefined;
+    const r = await correr(E.python, [arq, ...args.map(String)], { cwd: cwd || E.destino, env: ambiente(E.destino, E.python), timeout, aoLer });
+    return { ok: r.code === 0, code: r.code, saida: r.saida };
+}
+
+/** Roda o build.py do projeto HyperFrames. */
+async function build(E, proj, args, { timeout = 3600000 } = {}) {
+    const r = await correr(E.python, [path.join(proj, 'build.py'), ...args.map(String)], { cwd: proj, env: ambiente(E.destino, E.python), timeout });
+    return { ok: r.code === 0, code: r.code, saida: r.saida };
+}
+
+const cauda = (txt, n = 12) => String(txt || '').trim().split('\n').slice(-n).join('\n');
+const lerJson = (p, padrao = null) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return padrao; } };
+const gravarJson = (p, d) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, JSON.stringify(d, null, 1)); };
+
+function sondar(video) {
+    const r = spawnSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height:stream_side_data=rotation:format=duration', '-of', 'json', video], { encoding: 'utf8', env: ambiente('', '') });
+    try {
+        const j = JSON.parse(r.stdout);
+        const s = (j.streams || [])[0] || {};
+        let w = s.width, h = s.height;
+        const rot = Math.abs(Number(((s.side_data_list || [])[0] || {}).rotation || 0));
+        if (rot === 90 || rot === 270) [w, h] = [h, w];
+        return { largura: w, altura: h, duracao: Number(j.format && j.format.duration) || 0 };
+    } catch { return { largura: 0, altura: 0, duracao: 0 }; }
+}
+
+function slug(t) {
+    return String(t || 'video').normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'video';
+}
+
+/** A pasta de trabalho de uma edição e as gravações dentro dela (o original nunca é tocado: vai uma cópia). */
+function prepararPasta({ video, videos, pasta }, projectDir) {
+    const lista = [].concat(videos || [], video || []).filter(Boolean).map((v) => path.resolve(String(v).replace(/^~(?=\/)/, os.homedir())));
+    for (const v of lista) if (!fs.existsSync(v)) throw new Error(`não achei a gravação: ${v}`);
+    let dir = pasta ? path.resolve(String(pasta).replace(/^~(?=\/)/, os.homedir())) : null;
+    if (!dir) {
+        if (!lista.length) throw new Error('diga qual gravação editar (video) ou a pasta da edição (pasta)');
+        dir = path.join(projectDir || path.join(os.homedir(), 'primocode'), 'edicao-' + slug(path.basename(lista[0]).replace(VIDEO_EXT, '')));
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const fontes = [];
+    for (const v of lista) {
+        const destino = path.join(dir, path.basename(v));
+        if (path.resolve(v) !== path.resolve(destino) && !fs.existsSync(destino)) {
+            try { fs.copyFileSync(v, destino, fs.constants.COPYFILE_FICLONE); } catch { fs.copyFileSync(v, destino); }
+        }
+        fontes.push(destino);
+    }
+    if (!fontes.length) {
+        const estado = lerJson(path.join(dir, 'edit', 'primocode.json'), {});
+        for (const f of estado.fontes || []) if (fs.existsSync(f)) fontes.push(f);
+        if (!fontes.length) {
+            for (const f of fs.readdirSync(dir)) if (VIDEO_EXT.test(f) && !/^final/i.test(f)) fontes.push(path.join(dir, f));
+        }
+    }
+    if (!fontes.length) throw new Error(`nenhuma gravação em ${dir}`);
+    return { pasta: dir, edit: path.join(dir, 'edit'), proj: path.join(dir, 'projeto'), fontes };
+}
+
+// ── 4. cortar ────────────────────────────────────────────────────────────
+
+/** Trechos sem palavra (barulho, respiro, o "preparando" antes de falar) saem do corte automático. */
+function limparTrechos(ranges) {
+    return (ranges || []).filter((r) => {
+        const q = String(r.quote || '').trim();
+        return q && !/sem transcri/i.test(q);
+    });
+}
+
+/** O EDL que o modelo pediu: [{inicio, fim, fonte?, frase?}] → ranges no formato do editor. */
+function trechosDoModelo(trechos, fontes) {
+    const chave = (f) => path.basename(f).replace(VIDEO_EXT, '');
+    return trechos.map((t, i) => {
+        const f = t.fonte ? fontes.find((x) => chave(x) === t.fonte || path.basename(x) === t.fonte) || fontes[0] : fontes[0];
+        return { id: 'm' + String(i + 1).padStart(2, '0'), source: chave(f), start: Number(t.inicio), end: Number(t.fim), beat: t.parte || '', quote: t.frase || '', reason: 'escolhido pelo modelo', gain_db: 0 };
+    });
+}
+
+function falaCompacta(edit, max = 60) {
+    const tr = lerJson(path.join(edit, 'transcripts', 'cut.json'));
+    if (!tr || !Array.isArray(tr.words)) return [];
+    const linhas = [];
+    let atual = null;
+    for (const w of tr.words) {
+        const txt = String(w.text || w.word || '').trim();
+        if (!txt) continue;
+        if (!atual || w.start - atual.fim > 0.6 || atual.palavras >= 12) {
+            if (atual) linhas.push(atual);
+            atual = { de: w.start, fim: w.end, texto: txt, palavras: 1 };
+        } else { atual.texto += ' ' + txt; atual.fim = w.end; atual.palavras++; }
+        if (/[.!?]$/.test(txt) && atual) { linhas.push(atual); atual = null; }
+    }
+    if (atual) linhas.push(atual);
+    return linhas.slice(0, max).map((l) => `${l.de.toFixed(2)}-${l.fim.toFixed(2)} ${l.texto}`);
+}
+
+async function respirosDe(E, video) {
+    const r = await helper(E, 'respiros', [video, '--json']);
+    try { return JSON.parse(r.saida.slice(r.saida.indexOf('{'), r.saida.lastIndexOf('}') + 1)); } catch { return null; }
+}
+
+/**
+ * O corte. opts: { video|videos|pasta, prompt, trechos, grade ('vivo' padrão; '' sem), limpar ('leve'|'forte'|false) }.
+ */
+async function cortar(opts = {}, ctx = {}) {
+    const dizer = falar(ctx);
+    const E = opts.__E || await garantir({ ctx, deps: opts.__deps });
+    if (!E.ok) return E;
+    const P = prepararPasta(opts, ctx.projectDir);
+    fs.mkdirSync(P.edit, { recursive: true });
+    const chave = (f) => path.basename(f).replace(VIDEO_EXT, '');
+    const prompt = opts.prompt ? ['--prompt', String(opts.prompt)] : [];
+    const log = [];
+    const passo = async (rotulo, nome, args, extra = {}) => {
+        dizer(rotulo);
+        const r = await helper(E, nome, args, { ctx, ...extra });
+        log.push({ passo: nome, ok: r.ok });
+        if (!r.ok) throw new Error(`${rotulo.replace(/…$/, '')} falhou: ${cauda(r.saida, 6)}`);
+        return r;
+    };
+    try {
+        const dur = P.fontes.reduce((s, f) => s + sondar(f).duracao, 0);
+        for (const f of P.fontes) {
+            await passo(`ouvindo a gravação ${path.basename(f)} (${Math.round(dur)} s; na primeira vez baixa o modelo de voz, ~1,6 GB)…`, 'transcribe', [f, '--edit-dir', P.edit, ...prompt], { mostrar: true });
+        }
+        await passo('juntando as tomadas…', 'pack_transcripts', ['--edit-dir', P.edit]);
+        let ranges;
+        if (Array.isArray(opts.trechos) && opts.trechos.length) {
+            ranges = trechosDoModelo(opts.trechos, P.fontes);
+        } else {
+            await passo('escolhendo a última tomada inteira de cada frase…', 'montar_corte', ['--edit-dir', P.edit, '--fontes', ...P.fontes]);
+            ranges = limparTrechos((lerJson(path.join(P.edit, 'edl.json')) || {}).ranges);
+            for (const r of ranges) { r.gain_db = Number(r.gain_db) || 0; }
+        }
+        if (!ranges.length) return { ok: false, error: 'não achei fala para cortar nessa gravação', pasta: P.pasta };
+        const info = sondar(P.fontes[0]);
+        const em_pe = info.altura > info.largura;
+        const edlManual = {
+            version: 1,
+            sources: Object.fromEntries(P.fontes.map((f) => [chave(f), f])),
+            output: em_pe ? { format: 'vertical', width: 1080, height: 1920 } : { format: 'source', width: info.largura, height: info.altura },
+            grade: opts.grade === undefined ? 'vivo' : String(opts.grade || ''),
+            jcut: { lead_frames: 4, tail_trim_frames: 2 },
+            ranges,
+        };
+        const manual = path.join(P.edit, 'edl_manual.json');
+        gravarJson(manual, edlManual);
+        const g = await passo('medindo a voz de cada trecho e acertando o ganho (a voz baixa sobe antes do volume final)…', 'ganho_por_trecho', [manual, '--json']);
+        let ganho = null;
+        try { ganho = JSON.parse(g.saida.slice(g.saida.indexOf('{'), g.saida.lastIndexOf('}') + 1)); } catch { /* sem relatório */ }
+        // respiro é erro: corta pela onda e confere; se sobrou, sobe o limiar (no máximo 3 voltas)
+        let limiar = null;
+        let resp = null;
+        for (let volta = 0; volta < 4; volta++) {
+            await passo(volta ? `sobrou respiro: cortando de novo pela onda (limiar ${limiar} dB)…` : 'tirando os respiros pela onda do áudio…', 'corte_por_onda', [manual, '-o', path.join(P.edit, 'edl.json'), ...(limiar != null ? ['--limiar', limiar] : [])]);
+            await passo('renderizando o corte…', 'render_cut', [path.join(P.edit, 'edl.json')]);
+            resp = await respirosDe(E, path.join(P.edit, 'cut.mp4'));
+            if (!resp || !resp.respiros || !resp.respiros.length || volta === 3) break;
+            // o limiar do respiros.py vale no corte já com ganho e volume final; na fonte ele fica esse tanto abaixo
+            const ln = (lerJson(path.join(P.edit, 'cut_timeline.json'), {}).loudnorm_input) || {};
+            const rs = lerJson(manual, {}).ranges || [];
+            const ganhoMedio = rs.reduce((s, r) => s + (Number(r.gain_db) || 0), 0) / Math.max(1, rs.length);
+            const total = ganhoMedio + (-14 - (Number(ln.input_i) || -14));
+            limiar = limiar == null ? Math.round(resp.limiar_db - total + 1) : limiar + 3;
+        }
+        if (opts.limpar !== false) {
+            await passo('limpando o ruído de fundo da voz…', 'voz_limpa', [P.edit, '--modo', opts.limpar === 'forte' ? 'forte' : 'leve']);
+        }
+        await passo('conferindo o corte (transcreve de novo, mede bordas e respiros)…', 'conferir_corte', [P.edit, ...prompt], { mostrar: true });
+        await passo('achando o rosto em cada trecho…', 'face_layout', ['--edit-dir', P.edit, '--force']);
+        await passo('medindo o tempo de cada palavra na onda…', 'palavras_na_onda', [P.edit]);
+        const tl = lerJson(path.join(P.edit, 'cut_timeline.json'), {});
+        const vl = lerJson(path.join(P.edit, 'verify', 'voz_limpa.json'), {});
+        const estado = { fontes: P.fontes, cortado_em: new Date().toISOString(), duracao: tl.duration };
+        gravarJson(path.join(P.edit, 'primocode.json'), estado);
+        return {
+            ok: true, pasta: P.pasta, edit: P.edit, corte: path.join(P.edit, 'cut.mp4'),
+            duracao: r3(tl.duration || 0), trechos: (lerJson(path.join(P.edit, 'edl.json'), {}).ranges || []).length,
+            volume: { ganho_base_db: ganho && ganho.ganho_base_db, voz_antes_lufs: ganho && ganho.referencia_lufs, ajuste: tl.loudnorm_modo, voz_limpa: (vl.relatorio || {}).loudnorm_modo || null },
+            respiros: resp ? (resp.respiros || []).length : null,
+            fala: falaCompacta(P.edit),
+            proximo: 'escreva o plano (gancho, pecas, broll) com os tempos da fala e chame acao:"montar" com a mesma pasta',
+        };
+    } catch (e) {
+        return { ok: false, error: e.message, pasta: P.pasta, passos: log };
+    }
+}
+
+// ── 5. o plano ───────────────────────────────────────────────────────────
+
+const PALAVRAS_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(' '));
+
+/** O gancho automático: a frase que abre, em até 4 palavras fortes, com a última em destaque. */
+function ganchoAutomatico(fala) {
+    const primeira = (fala[0] || '').replace(/^[\d.]+-[\d.]+\s+/, '');
+    const palavras = primeira.replace(/[.,!?;:]/g, '').split(/\s+/).filter(Boolean);
+    const fortes = palavras.filter((p) => !PALAVRAS_FRACAS.has(p.toLowerCase()) && (p.length > 2 || /^[A-ZÀ-Ú]{2}$/.test(p))).slice(-4);
+    if (!fortes.length) return null;
+    const ult = fortes.pop();
+    return (fortes.length ? fortes.join(' ') + ' ' : '') + `*${ult}*`;
+}
+
+function encurtar(texto, max = 22) {
+    const ps = String(texto).split(/\s+/);
+    let out = '';
+    for (const p of ps) { if ((out + ' ' + p).trim().length > max) break; out = (out + ' ' + p).trim(); }
+    return out || String(texto).slice(0, max);
+}
+
+/** As sugestões do motion_sugerir (fala → peça) no formato do catálogo do projeto HyperFrames. */
+function pecasDasSugestoes(motion) {
+    const out = [];
+    for (const [i, m] of (motion || []).entries()) {
+        const p = m.params || {};
+        const t = (k) => r3(m.start + ((p.times || [])[k] || 0));
+        if ((m.template === 'checklist' || m.template === 'riscado') && Array.isArray(p.items) && p.items.length >= 2) {
+            out.push({ id: 'lista' + i, tipo: 'lista_check', titulo: p.title || undefined, marca: m.template === 'riscado' ? 'x' : 'check', depois_de: r3(m.start - 0.1), sai: r3(m.end), itens: p.items.slice(0, 5).map((it, k) => ({ texto: encurtar(it), em: t(k) })) });
+        } else if (m.template === 'passos' && Array.isArray(p.items) && p.items.length >= 2) {
+            out.push({ id: 'passos' + i, tipo: 'passo_a_passo', depois_de: r3(m.start - 0.1), sai: r3(m.end), passos: p.items.slice(0, 4).map((it, k) => ({ texto: encurtar(it, 20), em: t(k) })) });
+        } else if ((m.template === 'contador' || m.template === 'barra_progresso') && p.value != null) {
+            out.push({ id: 'conta' + i, tipo: 'contador', valor_inicial: 0, valor_final: Number(p.value), prefixo: p.prefix || undefined, sufixo: p.suffix ? ' ' + String(p.suffix).trim() : undefined, em: r3(m.start), sai: r3(Math.min(m.end, m.start + 3.5)), duracao: 0.9, casas: Number.isInteger(Number(p.value)) ? 0 : 1 });
+        }
+    }
+    return out;
+}
+
+const PECA_GRANDE = new Set(['lista_check', 'passo_a_passo', 'notificacao', 'polaroide', 'hud']);
+const tempoNum = (x) => (typeof x === 'number' ? x : null);
+
+/** Monta o projeto.json a partir do plano (do modelo ou automático). */
+function aplicarPlano(cfg, plano, { fala, duracao, broll = [] }) {
+    cfg.titulo = plano.titulo || cfg.titulo;
+    cfg.formato = plano.formato || cfg.formato || '9:16';
+    cfg.estilo = plano.estilo || 'laranja';
+    cfg.legenda = Object.assign({ ligada: true, estilo: 'padrao', max_palavras: 3, na_moldura: false }, cfg.legenda || {}, typeof plano.legenda === 'string' ? { estilo: plano.legenda } : (plano.legenda || {}));
+    if (plano.correcoes) cfg.correcoes = Object.assign({}, cfg.correcoes || {}, plano.correcoes);
+    const animacoes = [];
+    const gancho = plano.gancho === false ? null : (plano.gancho || ganchoAutomatico(fala));
+    if (gancho) {
+        const prim = fala[0] ? Number(fala[0].split('-')[0]) : 0;
+        const fimFrase = fala[0] ? Number(fala[0].split(' ')[0].split('-')[1]) : 3;
+        const g = typeof gancho === 'object' ? gancho : { principal: gancho };
+        animacoes.push(Object.assign({ id: 'gancho', tipo: 'lettering', em: r3(Math.max(0, prim)), sai: r3(Math.min(Math.max(fimFrase, prim + 2.2), prim + 4.5)), posicao: 'topo', estilo: 'bloco' }, g));
+    }
+    for (const p of plano.pecas || []) animacoes.push(p);
+    cfg.animacoes = animacoes;
+    if (plano.cenas_proprias) cfg.cenas_proprias = plano.cenas_proprias;
+    // blocos: os do plano; senão moldura onde há peça grande e prova/tela verde no b-roll; o resto é tela cheia (câmera viva)
+    let blocos = Array.isArray(plano.blocos) ? plano.blocos.slice() : [];
+    if (!Array.isArray(plano.blocos)) {
+        const vagos = [];
+        for (const b of broll) vagos.push(b);
+        for (const a of animacoes) {
+            if (!PECA_GRANDE.has(a.tipo)) continue;
+            const de = tempoNum(a.depois_de) ?? tempoNum(a.em);
+            const ate = tempoNum(a.sai);
+            if (de == null || ate == null || ate - de < 2) continue;
+            vagos.push({ cena: 'moldura', de: r3(Math.max(0, de - 0.15)), ate: r3(Math.min(duracao, ate + 0.25)), fundo: 'desfocado' });
+        }
+        vagos.sort((a, b) => a.de - b.de);
+        for (const b0 of vagos) {
+            const b = { ...b0 };
+            const ant = blocos[blocos.length - 1];
+            // sem encostar: a câmera volta ao rosto entre um e outro (o que sobrar com 1,2 s ou mais fica, mais curto)
+            if (ant && b.de < ant.ate + 0.5) b.de = r3(ant.ate + 0.5);
+            if (b.de < 1.5) b.de = 1.5;                    // o gancho fica em tela cheia
+            if (b.ate - b.de < 1.2) { (cfg._avisos = cfg._avisos || []).push(`${b.cena} de ${b0.de} a ${b0.ate} ficou de fora: encosta em outro bloco`); continue; }
+            if (b.de !== b0.de) (cfg._avisos = cfg._avisos || []).push(`${b.cena} de ${b0.de} começa em ${b.de} (encostava no bloco de antes)`);
+            blocos.push(b);
+        }
+    }
+    cfg.blocos = blocos;
+    cfg.segura_fim = plano.segura_fim != null ? plano.segura_fim : 1.0;
+    if (plano.cartao_final) cfg.cartao_final = plano.cartao_final;
+    if (plano.projeto && typeof plano.projeto === 'object') Object.assign(cfg, plano.projeto);
+    return cfg;
+}
+
+// ── 6. montar ────────────────────────────────────────────────────────────
+
+async function buscarBroll(E, P, itens, ctx) {
+    const out = [];
+    for (const [i, b] of (itens || []).entries()) {
+        if (!b || !b.busca || b.de == null || b.ate == null) continue;
+        falar(ctx)(`buscando imagem livre para "${b.busca}"…`);
+        const r = await helper(E, 'fetch_images', [String(b.busca), '--edit-dir', P.edit, '--count', '1', '--json', ...(b.credito ? ['--allow-attribution'] : [])], { timeout: 120000 });
+        let arq = null;
+        try {
+            const j = JSON.parse(r.saida.slice(r.saida.indexOf('{'), r.saida.lastIndexOf('}') + 1));
+            const it = (j.images || [])[0];
+            arq = it && it.file ? path.join(P.edit, it.file) : null;
+            if (it && it.credit_line) b.credito_linha = it.credit_line;
+        } catch { /* sem imagem */ }
+        if (!arq || typeof arq !== 'string' || !fs.existsSync(arq)) { out.push({ busca: b.busca, ok: false }); continue; }
+        const nome = `broll-${i + 1}${path.extname(arq) || '.jpg'}`;
+        fs.mkdirSync(path.join(P.proj, 'assets'), { recursive: true });
+        fs.copyFileSync(arq, path.join(P.proj, 'assets', nome));
+        const modo = b.modo === 'tela_verde' ? 'tela_verde' : 'prova';
+        const bloco = modo === 'tela_verde'
+            ? { cena: 'tela_verde', de: Number(b.de), ate: Number(b.ate), fundo: 'assets/' + nome, posicao: b.posicao || 'centro', altura: 0.55, legenda: false }
+            : { cena: 'prova', de: Number(b.de), ate: Number(b.ate), arquivo: 'assets/' + nome, encaixe: b.encaixe || 'inteiro', ...(b.rotulo ? { rotulo: b.rotulo } : {}) };
+        out.push({ busca: b.busca, ok: true, arquivo: nome, bloco });
+    }
+    return out;
+}
+
+function quadros(video, pastaSaida, nome = 'quadro') {
+    const { duracao } = sondar(video);
+    fs.mkdirSync(pastaSaida, { recursive: true });
+    const out = [];
+    for (const pct of [5, 20, 40, 60, 80, 95]) {
+        const t = (duracao * pct / 100).toFixed(2);
+        const arq = path.join(pastaSaida, `${nome}-${String(pct).padStart(2, '0')}.png`);
+        spawnSync('ffmpeg', ['-v', 'error', '-y', '-ss', t, '-i', video, '-frames:v', '1', arq], { env: ambiente('', '') });
+        if (fs.existsSync(arq)) out.push(arq);
+    }
+    return out;
+}
+
+function medirAudio(video) {
+    const r = spawnSync('ffmpeg', ['-hide_banner', '-nostats', '-i', video, '-vn', '-af', 'ebur128=peak=true', '-f', 'null', '-'], { encoding: 'utf8', env: ambiente('', '') });
+    const t = String(r.stderr || '');
+    const resumo = t.slice(t.lastIndexOf('Summary:'));
+    const num = (re) => { const m = resumo.match(re); return m ? Number(m[1]) : null; };
+    const p = spawnSync('ffprobe', ['-v', 'error', '-select_streams', 'a:0', '-show_entries', 'stream=sample_rate', '-of', 'csv=p=0', video], { encoding: 'utf8', env: ambiente('', '') });
+    return { lufs: num(/I:\s+(-?[\d.]+)\s+LUFS/), pico_dbtp: num(/Peak:\s+(-?[\d.]+)\s+dBFS/), hz: Number(String(p.stdout).trim()) || null };
+}
+
+/**
+ * A montagem. opts: { pasta, plano, trilha ('auto' | arquivo | false), render (true) }.
+ */
+async function montar(opts = {}, ctx = {}) {
+    const dizer = falar(ctx);
+    const precisaEspelho = JSON.stringify(opts.plano || {}).includes('tela_verde');
+    const E = opts.__E || await garantir({ ctx, deps: opts.__deps, espelho: precisaEspelho });
+    if (!E.ok) return E;
+    let P;
+    try { P = prepararPasta({ pasta: opts.pasta, video: opts.video }, ctx.projectDir); } catch (e) { return { ok: false, error: e.message }; }
+    if (!fs.existsSync(path.join(P.edit, 'cut.mp4'))) return { ok: false, error: 'falta o corte: chame acao:"cortar" antes (ou acao:"editar")', pasta: P.pasta };
+    const plano = opts.plano || {};
+    const etapas = [];
+    const passo = async (rotulo, fn) => {
+        dizer(rotulo);
+        const r = await fn();
+        etapas.push({ etapa: rotulo.replace(/…$/, ''), ok: r.ok });
+        if (!r.ok) throw new Error(`${rotulo.replace(/…$/, '')} falhou: ${cauda(r.saida, 8)}`);
+        return r;
+    };
+    try {
+        if (!fs.existsSync(path.join(P.proj, 'projeto.json'))) {
+            await passo('criando o projeto da edição…', () => correr(E.python, [path.join(E.destino, 'modelo-projeto', 'build.py'), 'novo', P.proj, '--edit', P.edit, '--estilo', plano.estilo || 'laranja'], { cwd: path.join(E.destino, 'modelo-projeto'), env: ambiente(E.destino, E.python) }).then((r) => ({ ok: r.code === 0, saida: r.saida })));
+        }
+        const fala = falaCompacta(P.edit, 400);
+        const tl = lerJson(path.join(P.edit, 'cut_timeline.json'), {});
+        let pecasAuto = [];
+        if (!Array.isArray(plano.pecas)) {
+            const s = await helper(E, 'motion_sugerir', ['--edit-dir', P.edit, '--json']);
+            try { pecasAuto = pecasDasSugestoes(JSON.parse(s.saida.trim().split('\n').pop()).motion); } catch { pecasAuto = []; }
+        }
+        const broll = await buscarBroll(E, P, plano.broll, ctx);
+        const cfgPath = path.join(P.proj, 'projeto.json');
+        const cfg = lerJson(cfgPath, {});
+        aplicarPlano(cfg, { ...plano, pecas: Array.isArray(plano.pecas) ? plano.pecas : pecasAuto }, { fala, duracao: tl.duration || 0, broll: broll.filter((b) => b.ok).map((b) => b.bloco) });
+        if (Array.isArray(plano.blocos)) for (const b of broll) if (b.ok) cfg.blocos.push(b.bloco);
+        cfg.blocos.sort((a, b) => (tempoNum(a.de) ?? 0) - (tempoNum(b.de) ?? 0));
+        cfg.sons = [];
+        const avisosPlano = cfg._avisos || [];
+        delete cfg._avisos;
+        gravarJson(cfgPath, cfg);
+        if (cfg.blocos.some((b) => b.cena === 'tela_verde')) {
+            for (const b of cfg.blocos.filter((x) => x.cena === 'tela_verde')) {
+                await passo(`recortando você do fundo de ${Number(b.de).toFixed(1)} s a ${Number(b.ate).toFixed(1)} s (uns minutos)…`, () => correr(E.python, [path.join(P.proj, 'ferramentas', 'pessoa_recortada.py'), '--edit', P.edit, '--de', Math.max(0, b.de - 0.5).toFixed(2), '--ate', (Number(b.ate) + 0.5).toFixed(2)], { cwd: P.proj, env: ambiente(E.destino, E.python), timeout: 3600000 }).then((r) => ({ ok: r.code === 0, saida: r.saida })));
+            }
+        }
+        if (plano.camera_viva !== false) await passo('pondo a câmera viva (zoom por frase e aproximação na ênfase)…', () => helper(E, 'camera_viva', [P.proj]));
+        await passo('montando a edição…', () => build(E, P.proj, ['completo']));
+        if (plano.sons !== false) {
+            await passo('escolhendo os efeitos sonoros casados com cada animação…', () => helper(E, 'plano_sfx', ['--projeto', P.proj]));
+            await passo('montando a edição com os sons…', () => build(E, P.proj, ['completo']));
+        }
+        const lint = await build(E, P.proj, ['hf', 'lint']);
+        if (opts.render === false) return { ok: true, pasta: P.pasta, projeto: P.proj, lint: cauda(lint.saida, 6), broll };
+        await passo('renderizando o vídeo (leva alguns minutos)…', () => build(E, P.proj, ['hf', 'render', '--quality', 'delivery', '--output', 'renders/final.mp4'], { timeout: 5400000 }));
+        let final = path.join(P.proj, 'renders', 'final.mp4');
+        // trilha: arquivo da pessoa, ou a busca do PrimoCode (energia alta), ou nenhuma
+        let trilha = null;
+        const pedido = plano.trilha !== undefined ? plano.trilha : opts.trilha;
+        if (pedido !== false && pedido !== 'nenhuma') {
+            if (pedido && pedido !== 'auto' && fs.existsSync(String(pedido))) trilha = { arquivo: String(pedido) };
+            else {
+                dizer('procurando uma trilha com energia…');
+                try {
+                    const mt = require('./estudio/maquina-trilha.js');
+                    const t = await mt.escolher({ chave: 'geral', busca: pedido && pedido !== 'auto' ? String(pedido) : null, pasta: P.pasta });
+                    if (t && t.arquivo) trilha = t;
+                } catch { /* sem trilha */ }
+            }
+        }
+        if (trilha) {
+            const comTrilha = path.join(P.proj, 'renders', 'final_trilha.mp4');
+            await passo('mixando a trilha por baixo da voz (abaixa quando você fala)…', () => helper(E, 'mixar_trilha', ['--video', final, '--trilha', trilha.arquivo, '--abaixo-da-voz', String(plano.trilha_abaixo || 20), '--saida', comTrilha]));
+            final = comTrilha;
+        }
+        dizer('conferindo no portão de qualidade (som, respiros, quadro preto, texto na zona segura)…');
+        let portao = await helper(E, 'portao', [final, '--projeto', P.proj, '--json'], { timeout: 1800000 });
+        let rel = null;
+        try { rel = JSON.parse(portao.saida.slice(portao.saida.indexOf('{'), portao.saida.lastIndexOf('}') + 1)); } catch { /* sem json */ }
+        const saida = path.join(P.pasta, 'final.mp4');
+        fs.copyFileSync(final, saida);
+        if (trilha && trilha.creditos) fs.writeFileSync(path.join(P.pasta, 'final.creditos.txt'), String(trilha.creditos) + '\n');
+        const fotos = quadros(saida, path.join(P.pasta, 'quadros'));
+        const audio = medirAudio(saida);
+        return {
+            ok: !!(rel && rel.passou), passou: !!(rel && rel.passou), video: saida, quadros: fotos,
+            audio, portao: rel ? { passou: rel.passou, falhas: rel.falhas, modos: rel.modos_do_volume, clipadas: rel.amostras_clipadas, folha: rel.folha, leitor: rel.leitor_de_texto } : cauda(portao.saida),
+            trilha: trilha ? { arquivo: trilha.arquivo, titulo: trilha.titulo, creditos: trilha.creditos } : null,
+            broll, avisos: avisosPlano, projeto: P.proj, pasta: P.pasta,
+            ...(rel && !rel.passou ? { error: 'o portão REPROVOU: ' + (rel.falhas || []).join(' | ') + ' — conserte no plano e chame montar de novo' } : {}),
+        };
+    } catch (e) {
+        return { ok: false, error: e.message, pasta: P.pasta, etapas };
+    }
+}
+
+/** Corte + montagem de uma vez. */
+async function editar(opts = {}, ctx = {}) {
+    const E = await garantir({ ctx, deps: opts.__deps, espelho: JSON.stringify(opts.plano || {}).includes('tela_verde') });
+    if (!E.ok) return E;
+    const c = await cortar({ ...opts, __E: E }, ctx);
+    if (!c.ok) return c;
+    const m = await montar({ ...opts, pasta: c.pasta, __E: E }, ctx);
+    return { ...m, corte: { duracao: c.duracao, trechos: c.trechos, volume: c.volume, respiros: c.respiros } };
+}
+
+// ── 7. a ferramenta e o comando ──────────────────────────────────────────
+
+const AJUDA = `editor_pro — edição completa de VÍDEO FALADO (motor EDIT IA PRO)
+  acao "editar"  {video, prompt?, plano?, trilha?}   corte + montagem + portão, de uma vez
+  acao "cortar"  {video|pasta, prompt?, trechos?}    transcreve, corta (ganho por trecho, sem respiro), limpa a voz; devolve a fala com tempos
+  acao "montar"  {pasta, plano?, trilha?}            gancho, peças, b-roll, câmera viva, sons, render, trilha com ducking, portão
+  acao "preparar"                                    baixa os arquivos e cria o Python do editor (sem editar nada)
+  acao "estado"  {pasta}                             onde a edição parou
+plano: {gancho:"Texto *destaque*", pecas:[peças do catálogo], broll:[{busca,de,ate,rotulo?}], blocos?, estilo?, legenda?, correcoes?, trilha?}`;
+
+async function ferramenta(args = {}, ctx = {}) {
+    const acao = String(args.acao || 'editar');
+    try {
+        if (acao === 'ajuda' || acao === 'help') return { ok: true, ajuda: AJUDA };
+        if (acao === 'preparar') { const E = await garantir({ ctx, espelho: !!args.espelho }); return E.ok ? { ok: true, editor: E.destino, python: E.python, avisos: E.avisos } : E; }
+        if (acao === 'estado') {
+            const P = prepararPasta({ pasta: args.pasta, video: args.video }, ctx.projectDir);
+            return { ok: true, pasta: P.pasta, cortado: fs.existsSync(path.join(P.edit, 'cut.mp4')), projeto: fs.existsSync(path.join(P.proj, 'projeto.json')), final: fs.existsSync(path.join(P.pasta, 'final.mp4')) ? path.join(P.pasta, 'final.mp4') : null, fala: falaCompacta(P.edit) };
+        }
+        if (acao === 'cortar') return await cortar(args, ctx);
+        if (acao === 'montar') return await montar(args, ctx);
+        if (acao === 'editar') return await editar(args, ctx);
+        return { ok: false, error: `acao "${acao}" não existe`, ajuda: AJUDA };
+    } catch (e) {
+        return { ok: false, error: e.message || String(e) };
+    }
+}
+
+/** `primocode editor <acao> --json '{...}'`: o mesmo, pelo run_shell (servidor antigo sem a ferramenta). */
+async function main(argv = [], { out = process.stdout } = {}) {
+    const acao = argv[0] && !argv[0].startsWith('-') ? argv[0] : 'ajuda';
+    let args = {};
+    const i = argv.indexOf('--json');
+    if (i >= 0) { try { args = JSON.parse(argv[i + 1] || '{}'); } catch (e) { out.write(JSON.stringify({ ok: false, error: '--json inválido: ' + e.message }) + '\n'); return 1; } }
+    if (acao === 'ajuda' || acao === 'help' || acao === '--help') { out.write(AJUDA + '\n'); return 0; }
+    const r = await ferramenta({ ...args, acao }, { projectDir: process.cwd() });
+    out.write(JSON.stringify(r) + '\n');
+    return r.ok ? 0 : 1;
+}
+
+module.exports = {
+    ORIGEM, AJUDA, casa, venvDir, venvPython, impressao, instalarArquivos, garantirArquivo, garantirVenv, gerarSintetizados,
+    dependencias, acharUv, acharPython, garantir, helper, cortar, montar, editar, ferramenta, main,
+    limparTrechos, trechosDoModelo, ganchoAutomatico, pecasDasSugestoes, aplicarPlano, prepararPasta, falaCompacta, urlDoEspelho,
+};