primocode 10.19.0 → 11.1.0

package/lib/plugin/editor-pro.js

@@ -0,0 +1,1022 @@
+/**
+ * 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 MAQ = require('./editor-pro-maquina.js');
+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 };
+    });
+}
+
+const chaveTexto = (t) => String(t || '').normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/**
+ * As palavras do corte com o começo MEDIDO NA ONDA (palavras_onda.json do helpers/palavras_na_onda.py): o Whisper
+ * adianta a palavra até 0,3 s, e a peça, o som e a legenda têm que cair NA palavra. Casa pela hora do Whisper e pelo
+ * texto (como o build.py); arquivo de outro corte (menos de 80% casadas) é ignorado e o tempo fica o do Whisper.
+ * { palavras: [{text, start, end, whisper}], tempos: 'onda'|'whisper'|null, limiar_db }
+ */
+function palavrasDoCorte(edit) {
+    const tr = lerJson(path.join(edit, 'transcripts', 'cut.json'));
+    if (!tr || !Array.isArray(tr.words)) return { palavras: [], tempos: null };
+    const ws = tr.words.map((w) => ({ text: String(w.text || w.word || '').trim(), start: Number(w.start), end: Number(w.end) }))
+        .filter((w) => w.text && Number.isFinite(w.start));
+    const po = lerJson(path.join(edit, 'palavras_onda.json'));
+    const lista = po && Array.isArray(po.palavras) ? po.palavras : [];
+    if (!lista.length) return { palavras: ws, tempos: 'whisper' };
+    const porHora = new Map();
+    for (const r of lista) {
+        const k = Math.round(Number(r.whisper) * 100);
+        if (Number.isFinite(k)) porHora.set(k, [...(porHora.get(k) || []), r]);
+    }
+    let casadas = 0;
+    const novas = ws.map((w) => {
+        const k = Math.round(w.start * 100);
+        const r = [k, k - 1, k + 1].flatMap((x) => porHora.get(x) || [])
+            .find((x) => Math.abs(Number(x.whisper) - w.start) < 0.011 && chaveTexto(x.text) === chaveTexto(w.text));
+        if (!r) return { ...w, whisper: w.start };
+        casadas++;
+        const s = Number(r.start);
+        if (!Number.isFinite(s) || Math.abs(s - w.start) > 0.45) return { ...w, whisper: w.start };
+        return { text: w.text, start: r3(s), end: r3(Math.max(w.end, s + 0.05)), whisper: w.start };
+    });
+    if (casadas < 0.8 * ws.length) return { palavras: ws.map((w) => ({ ...w, whisper: w.start })), tempos: 'whisper', aviso: 'palavras_onda.json é de outro corte: tempos do Whisper' };
+    return { palavras: novas, tempos: 'onda', limiar_db: Number(po.limiar_db) };
+}
+
+/** Um tempo do Whisper (das sugestões do motion_sugerir) levado ao começo medido na onda da palavra que começa ali. */
+function naOnda(palavras) {
+    return (t) => {
+        if (typeof t !== 'number') return t;
+        let melhor = null;
+        for (const w of palavras || []) {
+            const d = Math.abs(w.whisper - t);
+            if (d <= 0.03 && (!melhor || d < melhor.d)) melhor = { d, w };
+        }
+        return melhor ? r3(t + (melhor.w.start - melhor.w.whisper)) : t;
+    };
+}
+
+/** A fala em linhas "de-fim texto" com o começo de cada linha NA ONDA: é com esses tempos que o modelo escreve o plano. */
+function falaCompacta(edit, max = 60) {
+    const { palavras } = palavrasDoCorte(edit);
+    if (!palavras.length) return [];
+    const linhas = [];
+    let atual = null;
+    for (const w of palavras) {
+        const txt = w.text;
+        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}`);
+}
+
+/** O que o corte_por_onda mediu em cada fonte: o limiar de pausa sai do chão de ruído e da voz, não de um número fixo. */
+function limiaresDaOnda(saida) {
+    const out = [];
+    for (const m of String(saida || '').matchAll(/^(.+?): chão (-?\d+) dB, fala forte (-?\d+) dB, pausa abaixo de (-?\d+) dB/gm)) {
+        out.push({ fonte: m[1].trim(), chao_db: Number(m[2]), fala_db: Number(m[3]), limiar_db: Number(m[4]) });
+    }
+    return out;
+}
+
+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;
+        let onda = [];
+        for (let volta = 0; volta < 4; volta++) {
+            const co = 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] : [])]);
+            onda = limiaresDaOnda(co.saida);
+            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 pc = palavrasDoCorte(P.edit);
+        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,
+            // o limiar de pausa de cada fonte (chão de ruído + folga, abaixo da voz) e de onde vêm os tempos da fala
+            onda, tempos: pc.tempos, palavras_movidas: pc.palavras.filter((w) => Math.abs(w.start - w.whisper) >= 0.05).length,
+            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}*`;
+}
+
+const NAO_CHAVE = new Set('fica ficar assim aqui coisa muito mais sobre então porque quando depois antes também isso esse essa está estou tenho fazer faz'.split(' '));
+const ENFASE = new Set('nunca zero nada ninguém todos todas tudo sempre grátis sozinho pronto agora rápido erro segredo dobro metade'.split(' '));
+
+/**
+ * As palavras-chave DESTE vídeo (as que a legenda cinética pinta no degradê): o que a fala repete, número, palavra de
+ * ênfase e palavra longa, nessa ordem. Cada vídeo tem as suas, e o modelo pode trocar (plano.legenda.chaves).
+ */
+function palavrasChave(fala, max = null) {
+    const conta = new Map();
+    const ordem = [];
+    for (const linha of fala || []) {
+        for (const cru of String(linha).replace(/^[\d.]+-[\d.]+\s+/, '').split(/\s+/)) {
+            const w = cru.replace(/^[^\p{L}\p{N}$]+|[^\p{L}\p{N}%]+$/gu, '');
+            const k = w.toLowerCase();
+            if (!k || PALAVRAS_FRACAS.has(k) || NAO_CHAVE.has(k) || (k.length < 4 && !/\d/.test(k))) continue;
+            if (!conta.has(k)) { conta.set(k, 0); ordem.push(k); }
+            conta.set(k, conta.get(k) + 1);
+        }
+    }
+    const nota = (k) => 2 * (conta.get(k) - 1) + (/\d/.test(k) ? 3 : 0) + (ENFASE.has(k) ? 2 : 0) + (k.length >= 7 ? 1 : 0);
+    const total = [...conta.values()].reduce((a, b) => a + b, 0);
+    const n = max || Math.max(3, Math.min(12, Math.round(total / 6)));
+    return ordem.map((k, i) => ({ k, i, n: nota(k) })).filter((x) => x.n > 0)
+        .sort((a, b) => b.n - a.n || a.i - b.i).slice(0, n).map((x) => x.k);
+}
+
+/** O degradê da marca: destaque → apoio do kit /marca ativo; sem kit, o build usa o rosa → violeta. */
+function gradienteDaMarca(pastas, marcaKit = require('./marca-kit.js')) {
+    try {
+        const k = marcaKit.ativa(pastas);
+        const c = (k && k.cores) || {};
+        const a = marcaKit.normHex(c.destaque);
+        const b = marcaKit.normHex(c.apoio) || marcaKit.normHex(c.tinta);
+        return a && b && a !== b ? [a, b] : null;
+    } catch { return null; }
+}
+
+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, ajuste = (t) => t, avisos = []) {
+    const out = [];
+    for (let [i, m] of (motion || []).entries()) {
+        const p = m.params || {};
+        const ini = m.start;                       // tempo do Whisper: cada item vai para a onda da palavra dele
+        const t = (k) => r3(ajuste(ini + ((p.times || [])[k] || 0)));
+        m = { ...m, start: ajuste(ini) };
+        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 });
+        } else if (m.template === 'palavra_impacto' && String(p.text || '').replace(/[|*]/g, '').trim()) {
+            // a virada da fala vira lettering cinético embaixo do rosto (o gancho cobre os primeiros 2,2 s)
+            const texto = String(p.text).replace(/\s*\|\s*/g, ' ').trim();
+            if (m.start < 2.4) { avisos.push(`palavra_impacto "${texto}" em ${r3(m.start)} s ficou de fora: cai em cima do gancho`); continue; }
+            out.push({ id: 'impacto' + i, tipo: 'lettering', principal: texto, em: r3(m.start), sai: r3(Math.min(m.end + 0.6, m.start + 2.6)), posicao: 'base', estilo: 'cinetico' });
+        } else {
+            avisos.push(`sugestão "${m.template}" em ${r3(m.start)} s não virou peça (${['checklist', 'riscado', 'passos'].includes(m.template) ? 'menos de 2 itens' : 'o catálogo não tem peça para esse modelo'})`);
+        }
+    }
+    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 = [], marca = null, rostoGrande = null }) {
+    cfg.titulo = plano.titulo || cfg.titulo;
+    cfg.formato = plano.formato || cfg.formato || '9:16';
+    // limpo (a régua: chão claro, cartão branco, sem brilho) é o padrão; papelaria, noite e laranja continuam
+    cfg.estilo = plano.estilo || MAQ.escolherEstilo(fala, plano.variante || 0);
+    // a legenda cinética é o padrão (Inter 800, palavra por palavra, a palavra-chave no degradê); padrao e discreta continuam
+    cfg.legenda = Object.assign({ ligada: true, estilo: 'cinetica', max_palavras: 3, na_moldura: false }, cfg.legenda || {}, typeof plano.legenda === 'string' ? { estilo: plano.legenda } : (plano.legenda || {}));
+    const pedida = typeof plano.legenda === 'string' ? plano.legenda : (plano.legenda && plano.legenda.estilo);
+    if (!pedida) cfg.legenda.estilo = 'cinetica';           // o 'padrao' do projeto novo não é escolha de ninguém
+    cfg.legenda.max_palavras = Math.min(3, Number(cfg.legenda.max_palavras) || 3);
+    // as chaves são do vídeo: o modelo escolhe (plano.legenda.chaves) ou saem da fala, de novo a cada montar
+    cfg.legenda.chaves = plano.legenda && Array.isArray(plano.legenda.chaves) ? plano.legenda.chaves : palavrasChave(fala);
+    const grad = plano.gradiente || marca;
+    if (Array.isArray(grad) && grad.length >= 2) cfg.gradiente = grad.slice(0, 2);
+    if (plano.correcoes) cfg.correcoes = Object.assign({}, cfg.correcoes || {}, plano.correcoes);
+    const animacoes = [];
+    const gancho = plano.gancho === false ? null : (plano.gancho || MAQ.escolherGancho(fala, plano.variante || 0) || 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 };
+        // o título cinético vai embaixo do rosto, onde cabe gigante (no topo a cabeça encolhia a letra)
+        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: cfg.legenda.estilo === 'cinetica' ? 'base' : 'topo', estilo: cfg.legenda.estilo === 'cinetica' ? 'cinetico' : '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);
+        // o chão da moldura: no limpo, o papel claro do estilo (a pessoa num quadro arredondado); nos outros, o vídeo desfocado
+        const chao = cfg.estilo === 'limpo' ? 'papel' : 'desfocado';
+        for (const m of [].concat(plano.moldura || [])) {
+            if (m && tempoNum(m.de) != null && tempoNum(m.ate) != null) vagos.push({ cena: 'moldura', de: m.de, ate: m.ate, fundo: m.fundo || chao, ...(m.flutua === false ? { flutua: false } : {}) });
+        }
+        for (const c of [].concat(plano.comparar || [])) {
+            if (!c || tempoNum(c.de) == null || tempoNum(c.ate) == null || !c.a || !c.b) continue;
+            vagos.push({ cena: 'comparar', de: c.de, ate: c.ate, modo: c.modo || 'lado_a_lado', arranjo: c.arranjo || 'auto', som: c.som || 'voz', a: c.a, b: c.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: chao });
+        }
+        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);
+        }
+    }
+    // rosto grande (webcam de perto): a pessoa num quadro de largura total sobre o fundo desfocado, em vez do corte que cobre a tela
+    // (o texto não teria onde ficar sem cobrir olhos e boca). B-roll e peças grandes do plano continuam valendo por cima.
+    if (rostoGrande && !Array.isArray(plano.blocos)) {   // as molduras pequenas das peças viram o próprio quadro grande
+        cfg.moldura = Object.assign({}, cfg.moldura || {}, { caixa: rostoGrande.caixa });
+        // o chão é o vídeo desfocado (escuro, câmera de perto em quarto): estilo claro daria texto escuro sobre cabelo e fundo escuros
+        if (!plano.estilo && ['limpo', 'papelaria'].includes(cfg.estilo)) cfg.estilo = 'noite';
+        const fora = blocos.filter((b) => b.cena !== 'moldura');
+        blocos = [];
+        let t = 0;
+        for (const b of fora.sort((x, y) => x.de - y.de)) {
+            if (b.de - t >= 1.2) blocos.push({ cena: 'moldura', de: r3(t), ate: r3(b.de), fundo: 'desfocado', flutua: false, rosto_grande: true });
+            blocos.push(b); t = b.ate;
+        }
+        if (duracao - t >= 0.1) blocos.push({ cena: 'moldura', de: r3(t), ate: r3(duracao), fundo: 'desfocado', flutua: false, rosto_grande: true });
+        (cfg._avisos = cfg._avisos || []).push(`rosto grande na câmera (${Math.round(rostoGrande.rosto_h * 100)}% da altura no corte normal): a pessoa fica em um quadro de largura total com o rosto em ${Math.round(rostoGrande.fracao_rosto * 100)}% da altura, e o texto vai nas faixas livres`);
+    }
+    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;
+}
+
+/** Cria em PROJ/assets/sfx as camadas de som (grave, ar, brilho) e a ambiência (ruído rosa filtrado, "ar de sala") com ffmpeg:
+    nada baixado, nada com licença. { ok, erro? }. A ambiência tem a duração do vídeo + 2 s. */
+function gerarCamadasDeSom(proj, duracao) {
+    const dir = path.join(proj, 'assets', 'sfx');
+    fs.mkdirSync(dir, { recursive: true });
+    const SR = '48000';
+    const feitos = [
+        ['camada_grave.wav', ['-f', 'lavfi', '-i', `aevalsrc=sin(2*PI*(46+44*exp(-t*16))*t)*exp(-t*6.5)*0.9:d=0.6:s=${SR}`]],
+        ['camada_ar.wav', ['-f', 'lavfi', '-i', `anoisesrc=d=0.5:c=white:r=${SR}:a=0.6`, '-af', 'highpass=f=3800,afade=t=in:d=0.01,afade=t=out:st=0.06:d=0.44']],
+        ['camada_brilho.wav', ['-f', 'lavfi', '-i', `aevalsrc=(sin(2*PI*2093*t)*exp(-t*9)*0.5+sin(2*PI*3136*t)*exp(-t*12)*0.35):d=0.5:s=${SR}`]],
+        ['ambiente.wav', ['-f', 'lavfi', '-i', `anoisesrc=d=${Math.ceil(duracao + 2)}:c=pink:r=${SR}:a=0.5`, '-af', 'highpass=f=80,lowpass=f=1100']],
+    ];
+    for (const [nome, args] of feitos) {
+        const r = spawnSync('ffmpeg', ['-y', '-hide_banner', '-loglevel', 'error', ...args, '-ac', '2', '-ar', SR, path.join(dir, nome)], { encoding: 'utf8', timeout: 60000 });
+        if (r.status !== 0) return { ok: false, erro: `${nome}: ${cauda(r.stderr, 3)}` };
+    }
+    return { ok: true };
+}
+
+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 };
+}
+
+/** O que a câmera viva fez (a última linha JSON do camera_viva.py --json): aproximações, derivas e onde ficou parada. */
+function resumoCamera(saida) {
+    const linha = String(saida || '').trim().split('\n').reverse().find((l) => l.trim().startsWith('{'));
+    let r = null;
+    try { r = JSON.parse(linha); } catch { return null; }
+    return { aproximacoes: (r.punches || []).map((p) => ({ em: p.em, palavra: p.palavra })), derivas: r.derivas || 0,
+        maior_parado_s: r.maior_intervalo, parados: Array.isArray(r.parados) ? r.parados : [] };
+}
+
+/**
+ * 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 || 'limpo'], { 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 = [];
+        const avisosPecas = [];
+        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, naOnda(palavrasDoCorte(P.edit).palavras), avisosPecas); } catch (e) { pecasAuto = []; avisosPecas.push('sugestões de peça perdidas: ' + e.message); }
+        }
+        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 }, { rostoGrande: plano.rosto_grande === false ? null : MAQ.layoutRostoGrande(lerJson(path.join(P.edit, 'face_layout.json'), null)), fala, duracao: tl.duration || 0, broll: broll.filter((b) => b.ok).map((b) => b.bloco), marca: gradienteDaMarca([P.pasta, ctx.projectDir]) });
+        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 || []), ...avisosPecas];
+        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 })));
+            }
+        }
+        let camera = null;
+        if (plano.camera_viva !== false) {
+            const cv = await passo('pondo a câmera viva (zoom por frase, aproximação na ênfase, deriva lenta no resto)…', () => helper(E, 'camera_viva', [P.proj, '--json']));
+            camera = resumoCamera(cv.saida);
+            for (const [de, ate] of (camera && camera.parados) || []) avisosPlano.push(`câmera parada de ${de} a ${ate} s (${(ate - de).toFixed(1)} s): ponha uma peça, um b-roll ou uma moldura nesse trecho`);
+        }
+        await passo('montando a edição…', () => build(E, P.proj, ['completo']));
+        const dur = tl.duration || 0;
+        const emocao = MAQ.emocaoDaFala(fala);
+        // os sons: o plano_sfx escolhe um por animação; as camadas (grave, ar/brilho por impacto + ambiência) entram por cima, pela energia da frase
+        const refazerSons = async (extra = []) => {
+            const c0 = lerJson(cfgPath, {});
+            c0.sons = (c0.sons || []).filter((x) => !x.camada && !x.reedicao);
+            gravarJson(cfgPath, c0);
+            if (plano.sons === false) return;
+            await passo('escolhendo os efeitos sonoros casados com cada animação…', () => helper(E, 'plano_sfx', ['--projeto', P.proj, '--variar', ...extra]));
+            const c1 = lerJson(cfgPath, {});
+            if (plano.camadas !== false) {
+                const g = gerarCamadasDeSom(P.proj, dur);
+                if (g.ok) c1.sons = [...(c1.sons || []), ...MAQ.camadasDeSom(c1, { duracao: dur, frases: MAQ.entenderFrases(fala) })];
+                else avisosPlano.push('camadas de som não geradas: ' + g.erro);
+            }
+            c1.sons = [...(c1.sons || []), ...(extra.length ? MAQ.sonsNosCortes(c1) : [])];
+            gravarJson(cfgPath, c1);
+        };
+        if (plano.sons !== false) {
+            await refazerSons();
+            await passo('montando a edição com os sons e as camadas…', () => build(E, P.proj, ['completo']));
+        }
+        let critica = MAQ.criticar(lerJson(cfgPath, {}), { duracao: dur });
+        // reedição ÚNICA: conserta o que a régua reprovou, remonta e confere de novo (nunca um laço)
+        let reedicao = { feita: false, motivo: critica.falhas.length ? 'desligada no plano' : 'a régua passou de primeira' };
+        if (critica.falhas.length && plano.reeditar !== false) {
+            const cfgAntes = lerJson(cfgPath, {});
+            const r = MAQ.consertarPlano(cfgAntes, critica, { duracao: dur, fala });
+            const sonsFalharam = critica.falhas.some((f) => f.regra === 'sfx_por_min' || f.regra === 'sfx_no_corte');
+            if (r.mexeu || sonsFalharam) {
+                dizer(`reeditando uma vez o que a régua reprovou (${critica.falhas.map((f) => f.regra).join(', ')})…`);
+                gravarJson(cfgPath, r.cfg);
+                await refazerSons(['--espaco', '0.4']);
+                await passo('montando de novo, com os consertos…', () => build(E, P.proj, ['completo']));
+                const critica2 = MAQ.criticar(lerJson(cfgPath, {}), { duracao: dur });
+                reedicao = { feita: true, nota_antes: critica.nota, nota_depois: critica2.nota, falhas_antes: critica.falhas.map((f) => f.regra), falhas_depois: critica2.falhas.map((f) => f.regra), mudancas: r.mudancas };
+                if (critica2.nota >= critica.nota) critica = critica2;
+                else {
+                    reedicao.revertida = true;
+                    gravarJson(cfgPath, cfgAntes);
+                    await passo('a reedição piorou a nota: voltando ao plano de antes…', () => build(E, P.proj, ['completo']));
+                }
+            }
+        }
+        for (const f of critica.falhas) avisosPlano.push(`régua: ${f.regra} = ${f.valor} (limite ${f.limite}): ${f.conserto}`);
+        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, camera, critica, reedicao, emocao: { humor: emocao.humor, energia: emocao.energia }, avisos: avisosPlano };
+        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 pelo humor da fala (a emoção das frases) com energia, ou nenhuma. Falha NUNCA é engolida: vira aviso.
+        let trilha = null;
+        let trilhaAviso = 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), pessoa: true };
+            else {
+                dizer(`procurando uma trilha para a emoção da fala (${emocao.humor})…`);
+                try {
+                    const mt = opts.__trilha || require('./estudio/maquina-trilha.js');
+                    const t = await mt.escolher({ chave: 'geral', humor: plano.humor || emocao.humor, busca: pedido && pedido !== 'auto' ? String(pedido) : null, pasta: P.pasta });
+                    if (t && t.arquivo) trilha = t;
+                    else trilhaAviso = 'sem trilha: ' + ((t && t.motivo) || 'a busca não achou faixa');
+                } catch (e) { trilhaAviso = 'a busca de trilha falhou: ' + (e && e.message || e); }
+            }
+        }
+        if (trilhaAviso) avisosPlano.push(trilhaAviso);
+        if (trilha) {
+            const comTrilha = path.join(P.proj, 'renders', 'final_trilha.mp4');
+            // o drop da faixa cai na frase mais forte (o mesmo olhar da emoção que escolheu o humor)
+            let inicioTrilha = 0;
+            try {
+                if (trilha.batidas && emocao.cortes.length) { const d = require('./estudio/maquina-trilha.js').inicioNoDrop(emocao.cortes, trilha, dur); if (d && d.inicio > 0) inicioTrilha = d.inicio; }
+            } catch (e) { avisosPlano.push('drop da trilha não alinhado: ' + e.message); }
+            trilha.inicio = inicioTrilha;
+            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), '--inicio-trilha', String(inicioTrilha), '--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, humor: trilha.humor || null, inicio: trilha.inicio } : null, trilha_aviso: trilhaAviso,
+            emocao: { humor: emocao.humor, energia: emocao.energia, curva: emocao.curva.map((c) => c.humor) }, reedicao,
+            broll, avisos: avisosPlano, camera, critica, 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?}], moldura?, comparar?, blocos?, estilo?, variante? (0,1,2…: outro gancho e outro estilo, pelo conteúdo), legenda?, correcoes?, trilha?}
+estilo: "limpo" (padrão: chão claro, cartão branco, sem brilho) | "laranja" | "noite" | "papelaria"
+moldura: [{de, ate, fundo?:"papel"|"desfocado"}]  a pessoa num quadro arredondado que flutua devagar sobre o chão
+comparar: [{de, ate, arranjo:"lado"|"empilhado"|"auto", a:{arquivo|"corte", inicio, rotulo}, b:{...}}]  dois vídeos na mesma escala, rótulo literal
+legenda: "cinetica" (padrão: Inter 800, palavra por palavra, a palavra-chave no degradê) | "padrao" | "discreta";
+  {estilo, chaves:["palavra",...]} troca as palavras-chave (sem chaves, saem da fala); gradiente:["#rrggbb","#rrggbb"] (padrão: o kit /marca)`;
+
+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,
+    gerarCamadasDeSom, limparTrechos, trechosDoModelo, ganchoAutomatico, pecasDasSugestoes, aplicarPlano, prepararPasta, falaCompacta, urlDoEspelho,
+    palavrasDoCorte, naOnda, limiaresDaOnda, resumoCamera, palavrasChave, gradienteDaMarca, maquina: MAQ,
+};