primocode 10.19.0 → 11.1.0

package/lib/plugin/estudio/diretor.js

@@ -0,0 +1,392 @@
+/**
+ * diretor.js — o agente que ESTRUTURA antes de alguém produzir.
+ *
+ *   "Tenha uma IA específica pra roteiro que monta tudo: narração, qual voz,
+ *    roteiro, etc. Ela estrutura tudo antes de mandar pra IA. Funciona assim:
+ *    a IA identifica que precisa criar vídeo, ativa o agente, esse agente faz
+ *    a estrutura e manda pra IA, e depois ela só faz o vídeo."
+ *
+ * ── POR QUE UM PAPEL SEPARADO, E NÃO UM PARÁGRAFO NO PROMPT ──────────────
+ * É o mesmo motivo do pipeline.js: o modelo que está montando as cenas já
+ * gastou a atenção dele em JSON — fonte, cor, duração, layout — e é ali que o
+ * roteiro morre. Vira legenda do que aparece na tela ("Vantagens", "Nossos
+ * serviços"), sem arco, sem narração escrita, sem decisão de voz. O diretor
+ * roda numa conversa PRÓPRIA, sem ver JSON nenhum, e só decide: o que se
+ * conta, em que ordem, em quantos segundos, com que voz, com quais imagens e
+ * qual música. Depois disso o produtor tem pouco a inventar — e inventar é
+ * justamente onde ele erra.
+ *
+ * ── O PLANO É UM CONTRATO, NÃO UM TEXTO BONITO ───────────────────────────
+ * A saída do diretor é JSON com forma conhecida, e este módulo NORMALIZA e
+ * CONFERE o que voltou: duração que fecha, narração em toda cena, keyframes
+ * onde faz sentido, lista de mídia a buscar. Um plano que não fecha volta ao
+ * diretor com o defeito apontado — uma vez. Aceitar "quase certo" aqui custa
+ * um vídeo de 40 segundos que dura 12.
+ *
+ * ── O QUE O DIRETOR NÃO ESCOLHE MAIS ─────────────────────────────────────
+ * Ele escolhia o MOTOR (estúdio ou Remotion) e o TEMA, o LAYOUT e o FUNDO,
+ * cada um numa lista fechada — "meia-noite | claro | papel | neon", "capa |
+ * titulo | secao | duas-colunas". Motor não existe mais: o Remotion é o
+ * único renderizador. E as outras três listas saíram por decisão do produto:
+ *
+ *   "tira os templates e os estilos prontos, eles deixam a IA preguiçosa e
+ *    todo vídeo sai igual e genérico"
+ *
+ * Uma lista de seis temas é um template com outro nome — o modelo escolhe um
+ * dos seis e para de pensar em cor. No lugar delas o diretor DESCREVE: que
+ * paleta, que ar, o que está na tela, como a cena troca. Descrição não tem
+ * seis opções, e é o produtor quem compõe aquilo com os primitivos.
+ */
+
+'use strict';
+
+// ── 1. reconhecer que o pedido é de vídeo ────────────────────────────────
+
+const PEDE_VIDEO = /\b(v[ií]deo|reels?|tiktok|short|shorts|motion|anima[cç][aã]o|anima\b|teaser|trailer|comercial|propaganda|v[ií]nheta|vinheta|abertura|capcut|premiere|after\s*effects|aftereffects)\b/i;
+const PEDE_SLIDE = /\b(slide|slides|deck|apresenta[cç][aã]o|pitch|powerpoint|keynote|prisma)\b/i;
+const SO_TEXTO = /\b(roteiro apenas|s[oó] o roteiro|s[oó] o texto|sem v[ií]deo)\b/i;
+
+/**
+ * O pedido precisa de produção audiovisual? E de que tipo?
+ *
+ * Isto é o gatilho do agente: o CLI pergunta aqui antes de deixar o produtor
+ * começar. Pedir "só o roteiro" NÃO liga a produção — quem pediu texto quer
+ * texto, e devolver um mp4 é ignorar a pessoa.
+ */
+function precisaDeProducao(texto) {
+    const t = String(texto || '');
+    if (!t.trim()) return { producao: false };
+    if (SO_TEXTO.test(t)) return { producao: false, motivo: 'pediu só o texto' };
+    if (PEDE_VIDEO.test(t)) return { producao: true, formato: 'video', motivo: 'o pedido é de vídeo' };
+    if (PEDE_SLIDE.test(t)) return { producao: true, formato: 'apresentacao', motivo: 'o pedido é de apresentação' };
+    return { producao: false };
+}
+
+/* Editar a GRAVAÇÃO da pessoa não é produzir vídeo do zero: aí o caminho é o
+   editor por linha do tempo (`primocode video`, lib/plugin/video/), não o roteiro. */
+const PEDE_EDICAO = /\b(edit[ae]r?|edi[cç][aã]o|cort[ae]r?|legend[ae]r?|tir[ae]r?\s+(o|os)\s+sil[eê]ncios?)\b[\s\S]{0,80}\b(grava[cç][aã]o|meu\s+v[ií]deo|esse\s+v[ií]deo|este\s+v[ií]deo|[\w-]+\.(mp4|mov|mkv|webm|m4v))\b|\b[\w-]+\.(mp4|mov|mkv|webm|m4v)\b[\s\S]{0,80}\b(edit|cort|legend|sil[eê]nci)/i;
+
+/* Os pedidos de EFEITO sobre a gravação (lib/plugin/video/ops-fx.js): fundo, camadas,
+   estalo, objeto na mão, legenda na cabeça. Falam da pessoa ("me", "minha
+   mão"), não do arquivo — por isso não casavam com a regra de cima. */
+const PEDE_EFEITO = /\b(tir[ae]r?|remov\w*|troc\w*)\s+(o\s+)?fundo\b|\bsepar\w*\s+em\s+camadas\b|\bestal\w*\s+(o\s+)?dedo\b|\b(logo|objeto)\b[\s\S]{0,40}\bm[aã]os?\b|\bjunt\w*\s+as\s+m[aã]os\b|\blegenda\b[\s\S]{0,40}\b(azul|vermelh|verde|amarel|rosa|roxa|branc|cabe[cç]a|em cima|embaixo)/i;
+
+/* "edite: /Users/…/Fototeca do Photo Booth/…/Filme em 30-09-2026 às 23.56.mov": o caminho
+   do Photo Booth tem mais de 80 caracteres, e o pedido ia para o Estúdio de
+   motion — que tratava a gravação como b-roll (01/10). Verbo de editar + um
+   arquivo de vídeo em qualquer lugar da frase é edição. */
+const EDITA_ARQUIVO = /\b(edit\w*|edi[cç][aã]o|p[oõ]e\s+(ele\s+)?pra\s+editar)\b[\s\S]*\.(mp4|mov|mkv|webm|m4v)\b|\.(mp4|mov|mkv|webm|m4v)\b[\s\S]*\b(edit\w*|edi[cç][aã]o)\b/i;
+
+/* A gravação da pessoa FALANDO, sem caminho de arquivo na frase (20/10, a edição completa do
+   editor_pro): "edita meu vídeo", "faz um reels disso", "coloca legenda e efeitos nele". Fala de
+   uma gravação que JÁ existe ("disso", "meu vídeo", "nele"), não de criar um vídeo do zero. */
+const PEDE_EDICAO_FALADA = /\bedit\w*\s+(o\s+|esse\s+|este\s+)?(meu\s+)?(v[ií]deo|grava[cç][aã]o)\s+(meu|que\s+eu\s+gravei)\b|\bedit\w*\s+(o\s+)?meu\s+v[ií]deo\b|\b(faz|fa[cç]a|transform\w*|vir\w*)\s+(um\s+|uma\s+|em\s+)?(reels?|tiktok|shorts?|criativo|corte)\s+(disso|desse|dessa|deste|desta|com\s+(esse|essa|este|esta|a\s+minha|o\s+meu))\b|\bcoloc\w*\s+(uma\s+)?legendas?\s+e\s+(uns\s+)?efeitos?\b|\b(legend\w*|efeitos?)\b[\s\S]{0,30}\b(no\s+meu\s+v[ií]deo|na\s+minha\s+grava[cç][aã]o|nele|nessa\s+grava[cç][aã]o)\b/i;
+
+function precisaDeEdicao(texto) {
+    const t = String(texto || '');
+    return PEDE_EDICAO.test(t) || PEDE_EFEITO.test(t) || EDITA_ARQUIVO.test(t) || PEDE_EDICAO_FALADA.test(t);
+}
+
+// ── 2. as decisões que não são do modelo ─────────────────────────────────
+
+/**
+ * A voz. Tom e idioma decidem; o nome exato quem resolve é o estúdio, que
+ * sabe o que está instalado — aqui sai a INTENÇÃO, que é o que o diretor
+ * precisa escrever no plano.
+ */
+function vozPara({ tom = 'neutro', idioma = 'pt-BR', genero } = {}) {
+    const t = String(tom).toLowerCase();
+    const perfil = /urgente|energ|hype|an[uú]ncio|venda/.test(t) ? 'energica'
+        : /calm|institucional|corporativ|s[eé]ri/.test(t) ? 'firme'
+            : /doc|narrativ|hist[oó]ria|documental/.test(t) ? 'grave'
+                : /leve|simp[aá]tic|amig|casual/.test(t) ? 'proxima'
+                    : 'neutra';
+    const ritmo = perfil === 'energica' ? 1.08 : perfil === 'grave' ? 0.94 : 1;
+    return { perfil, idioma, genero: genero || 'indiferente', ritmo,
+        instrucao: {
+            energica: 'projeção alta, frases curtas, corte seco entre elas',
+            firme: 'ritmo constante, sem exagero, pausa depois do número',
+            grave: 'grave e pausada, respira entre as frases',
+            proxima: 'como quem conversa, sorriso na voz',
+            neutra: 'clara e neutra, sem cor demais',
+        }[perfil] };
+}
+
+/** Quantas cenas cabem, e de que tamanho, num vídeo desta duração. */
+function ritmoPara(segundos) {
+    const s = Math.max(5, Number(segundos) || 30);
+    // (15/10) As referências cortam a cada 1 a 2 s; o PrimoCode pedia 2,6 a 5 s e saía lento.
+    const media = s <= 20 ? 1.8 : s <= 45 ? 2.2 : s <= 90 ? 2.6 : 3;
+    return { cenas: Math.max(3, Math.round(s / media)), duracaoMedia: media,
+        palavrasPorCena: Math.round(media * 2.6) };   // ~155 palavras/minuto de narração
+}
+
+// ── 2b. a estrutura: um cardápio, e a memória do que já saiu ─────────────
+
+/* "o roteiro vicia: todo vídeo começa igual, não escolhe outra estrutura"
+   (Joel, 09/10). A regra 3 do diretor tinha UM arco só — prende em 2
+   segundos, entrega, pede ação — e o produtor nem isso via: todo roteiro
+   saía com a mesma abertura de impacto e o mesmo miolo de lista. Aqui não
+   tem regex escolhendo pelo pedido: o modelo recebe o CARDÁPIO (cada
+   estrutura com o "quando serve" e o jeito de abrir) e o que os últimos
+   vídeos já usaram. Quem escolhe é ele; o código só lembra. */
+const ESTRUTURAS = [
+    { id: 'historia', nome: 'história', quando: 'tem uma pessoa, um caso real ou um antes e depois', abre: 'uma cena concreta: alguém, um lugar, um momento ("Às 6h, a Ana abriu o caixa e…")' },
+    { id: 'problema-solucao', nome: 'problema → solução', quando: 'o assunto resolve uma dor clara', abre: 'a dor dita como quem sente ("Você perde duas horas por semana com…")' },
+    { id: 'lista', nome: 'lista', quando: 'são dicas, razões ou passos que se sustentam sozinhos', abre: 'a promessa com o número ("3 erros que…")' },
+    { id: 'pergunta-resposta', nome: 'pergunta → resposta', quando: 'o público já tem uma dúvida', abre: 'a pergunta, direta, sem a resposta ainda' },
+    { id: 'dialogo', nome: 'diálogo', quando: 'o pedido fala em duas pessoas, duas vozes, conversa ou entrevista', abre: 'a fala de um, e o outro responde' },
+    { id: 'demonstracao', nome: 'demonstração', quando: 'o valor está em VER funcionando', abre: 'o resultado pronto primeiro; depois, como se chega lá' },
+    { id: 'mito-verdade', nome: 'contraste (mito × verdade)', quando: 'existe uma crença comum que está errada', abre: 'o mito, dito como se fosse verdade' },
+    { id: 'dado-surpresa', nome: 'dado que surpreende', quando: 'há um número que muda o jeito de ver o assunto', abre: 'o número sozinho, e a frase que diz por que ele importa' },
+];
+
+const vari = () => require('./variedade.js');   // tardio: a memória mora em ~/.primocode/studio
+const idEstrutura = (x) => String(x || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+
+/** As últimas estruturas e aberturas que saíram em vídeo, mais nova primeiro. */
+function recentes(n = 3) {
+    return { estruturas: vari().usadas('estrutura').slice(0, n), aberturas: vari().usadas('abertura').slice(0, n) };
+}
+
+/** O cardápio em texto, para o prompt — com o que foi usado por último. */
+function cardapioEstruturas({ usadas = recentes() } = {}) {
+    const linhas = ESTRUTURAS.map((e) => `- ${e.id} (${e.nome}): se ${e.quando}. Abre com ${e.abre}.`);
+    if (usadas.estruturas.length) linhas.push(`Usadas recentemente: ${usadas.estruturas.join(', ')} — prefira outra, a menos que o pedido peça essa.`);
+    if (usadas.aberturas.length) linhas.push(`Os últimos vídeos começaram assim: ${usadas.aberturas.map((a) => `"${a}"`).join(' · ')} — não comece do mesmo jeito.`);
+    linhas.push('Nenhuma serve? Invente a estrutura e dê um nome a ela.');
+    return 'CARDÁPIO DE ESTRUTURAS (você escolhe pelo pedido):\n' + linhas.join('\n');
+}
+
+/**
+ * Depois que o roteiro virou plano: guarda a estrutura que o modelo escolheu
+ * e como o vídeo abriu. Aceita o roteiro (partes/fala) ou o plano do diretor
+ * (cenas/narracao). Não julga a escolha — só lembra dela.
+ */
+function registrarEstrutura(r) {
+    const x = r && typeof r === 'object' ? r : {};
+    const estrutura = idEstrutura(x.estrutura) || null;
+    const p0 = (x.partes || x.cenas || [])[0] || {};
+    const abertura = String(p0.fala || p0.narracao || p0.titulo || '').split(/\s+/).filter(Boolean).slice(0, 8).join(' ') || null;
+    if (estrutura) vari().marcar('estrutura', estrutura);
+    if (abertura) vari().marcar('abertura', abertura);
+    return { estrutura, abertura };
+}
+
+// ── 3. o plano ───────────────────────────────────────────────────────────
+
+const CAMPOS_CENA = ['titulo', 'falante', 'narracao', 'duracao', 'aTela', 'fundo', 'transicao',
+    'elementos', 'midia', 'camera', 'chaves', 'notas'];
+
+/**
+ * Normaliza o que o diretor devolveu e aponta o que ficou faltando.
+ *
+ * Não conserta conteúdo — conteúdo é dele. Conserta FORMA: duração que virou
+ * string, cena sem transição, o total que não fecha com o pedido. E lista os
+ * defeitos que só o diretor resolve (cena muda, narração vazia), para voltar
+ * com o apontamento em vez de seguir com o plano torto.
+ */
+function normalizarPlano(bruto, { segundos } = {}) {
+    const p = bruto && typeof bruto === 'object' ? bruto : {};
+    const defeitos = [];
+    const cenas = Array.isArray(p.cenas) ? p.cenas : [];
+    if (!cenas.length) defeitos.push('o plano veio sem cenas');
+
+    const limpas = cenas.map((c, i) => {
+        const cena = {};
+        for (const k of CAMPOS_CENA) if (c && c[k] !== undefined) cena[k] = c[k];
+        cena.duracao = Math.max(1.2, Math.min(15, Number(cena.duracao) || 3.5));
+        cena.narracao = typeof cena.narracao === 'string' ? cena.narracao.trim() : '';
+        if (!cena.narracao) defeitos.push(`cena ${i + 1} sem narração`);
+        if (!cena.titulo && !cena.aTela && !cena.elementos) defeitos.push(`cena ${i + 1} sem nada na tela`);
+        /* A transição é texto: "o logo desce e o fundo abre com ele", não um
+           item de lista. O rodízio que havia aqui (fade, deslizar, subir…
+           em ordem) escondia o defeito em vez de apontá-lo: preenchia a
+           lacuna com a próxima palavra da fila, e o vídeo saía com oito
+           transições que ninguém escolheu. Cena sem transição é DEFEITO, e
+           volta para o diretor decidir. */
+        cena.transicao = typeof cena.transicao === 'string' ? cena.transicao.trim() : '';
+        if (!cena.transicao) defeitos.push(`cena ${i + 1} não diz como entra`);
+        cena.midia = Array.isArray(cena.midia) ? cena.midia.filter((m) => m && m.busca) : [];
+        return cena;
+    });
+
+    const total = Math.round(limpas.reduce((s, c) => s + c.duracao, 0) * 10) / 10;
+    const alvo = Number(segundos) || Number(p.segundos) || total;
+    // 20% de folga: o alvo é intenção, não cronômetro. Fora disso o vídeo
+    // entrega outra coisa — 12 segundos onde pediram 40.
+    const fecha = !alvo || Math.abs(total - alvo) <= Math.max(3, alvo * 0.2);
+    if (!fecha) defeitos.push(`a soma das cenas dá ${total}s e o pedido é ${alvo}s`);
+
+    if (!String(p.visual || '').trim()) defeitos.push('o plano não diz a direção de arte (visual): paleta, ar e tipografia');
+
+    const plano = {
+        titulo: String(p.titulo || '').trim() || 'Sem título',
+        formato: p.formato === 'apresentacao' ? 'apresentacao' : 'video',
+        proporcao: ['16:9', '9:16', '1:1', '4:5'].includes(p.proporcao) ? p.proporcao : '16:9',
+        visual: String(p.visual || '').trim() || null,
+        tom: p.tom || 'neutro',
+        publico: p.publico || null,
+        promessa: p.promessa || null,          // o que a pessoa leva do vídeo
+        estrutura: idEstrutura(p.estrutura) || null,
+        segundos: total,
+        voz: vozPara({ tom: p.tom, idioma: p.idioma || 'pt-BR',
+            genero: p.voz && p.voz.genero }),
+        trilha: p.trilha && (p.trilha.busca || p.trilha.arquivo)
+            ? { busca: p.trilha.busca || null, arquivo: p.trilha.arquivo || null,
+                volume: Number(p.trilha.volume) || 0.18, humor: p.trilha.humor || p.tom || null }
+            : null,
+        cenas: limpas,
+        midia: limpas.flatMap((c, i) => c.midia.map((m) => ({ cena: i + 1, ...m }))),
+        creditos: !!p.creditos,
+    };
+    // Duas vozes (falantes.js): o mapa e quem fala cada cena, quando o diretor escreveu diálogo.
+    const { vozes } = require('./falantes.js').normalizar({ vozes: p.vozes, partes: limpas });
+    if (vozes) plano.vozes = vozes;
+    return { plano, defeitos, ok: defeitos.length === 0 };
+}
+
+// ── 4. o prompt do diretor ───────────────────────────────────────────────
+
+const DIRETOR = (pedido, { segundos = 30, formato = 'video', contexto = '' } = {}) => {
+    const r = ritmoPara(segundos);
+    return `Você é o DIRETOR de conteúdo. Você NÃO produz nada: você ESTRUTURA, e outra IA produz a partir do que você escrever. Não escreva código, não escreva JSON de cena de ferramenta, não chame ferramenta nenhuma.
+
+PEDIDO: ${pedido}
+${contexto ? `CONTEXTO: ${contexto}\n` : ''}FORMATO: ${formato} · DURAÇÃO ALVO: ${segundos}s · RITMO: ~${r.cenas} cenas de ~${r.duracaoMedia}s (~${r.palavrasPorCena} palavras de narração por cena)
+
+Devolva SÓ um bloco \`\`\`json com este formato, sem texto antes nem depois:
+
+{
+  "titulo": "…",
+  "estrutura": "o id que você escolheu no cardápio abaixo (ou o nome da que inventou)",
+  "formato": "${formato}",
+  "proporcao": "16:9 | 9:16 | 1:1 | 4:5",
+  "visual": "a direção de arte em uma ou duas frases: paleta (diga as cores em hex), que ar tem (limpo, denso, luminoso, sujo), que tipografia pede. NÃO existe lista de temas — descreva o que este vídeo tem de próprio.",
+  "tom": "como deve soar (institucional, urgente, documental, leve…)",
+  "publico": "para quem é",
+  "promessa": "o que a pessoa leva ao terminar de ver",
+  "trilha": { "busca": "termo de busca da música", "humor": "…", "volume": 0.18 },
+  "vozes": { "nome de quem fala": "antonio | thalita | francisca" },
+  "cenas": [
+    {
+      "titulo": "o que aparece grande na tela",
+      "falante": "quem fala esta cena (um nome de vozes) — só quando houver mais de uma voz",
+      "narracao": "a frase FALADA, escrita para ser lida em voz alta",
+      "duracao": 3.5,
+      "aTela": "o que se vê nesta cena, descrito como você descreveria para um motion designer: onde está cada coisa, que tamanho tem, o que domina o quadro",
+      "fundo": "o fundo desta cena — uma cor, um gradiente (diga as cores), uma imagem da lista midia, ou o que ele vira no meio da cena",
+      "transicao": "como esta cena ENTRA, descrito: o que se move, em que direção, quanto dura. Corte seco também é resposta — diga 'corte'.",
+      "midia": [ { "busca": "o que procurar", "tipo": "imagem | logo", "papel": "fundo | destaque | selo", "semFundo": false } ],
+      "camera": "aproximar | afastar | pan-direita | pan-esquerda | subir | descer | empurrar | balanco | nenhuma",
+      "chaves": "descreva em uma frase o movimento principal desta cena (o que entra, o que atravessa, o que cresce)",
+      "notas": "o que o produtor precisa saber e não está acima"
+    }
+  ]
+}
+
+REGRAS QUE SEPARAM UM VÍDEO BOM DE UM GENÉRICO:
+1. NARRAÇÃO É FALA, NÃO LEGENDA. "Vantagens" não é narração. Escreva a frase que a pessoa ouve.
+2. O QUE SE OUVE E O QUE SE VÊ NÃO SE REPETEM. A tela mostra a prova (número, imagem, logo); a voz conta o que ela significa.
+3. ESTRUTURA. Escolha no cardápio do fim a que serve a ESTE pedido; a primeira cena abre do jeito dela e prende em 2 segundos, a última pede uma ação. Sem "Introdução / Desenvolvimento / Conclusão".
+4. NÚMERO É CONCRETO. Nada de "muitos clientes": ou tem o número, ou a frase muda.
+5. RITMO VARIADO. Cenas de durações diferentes e transições diferentes. Tudo em fade parece slide.
+5b. NADA DE GAVETA. Não existe tema pronto, layout pronto nem fundo pronto: é você que decide a cor, a tipografia e a composição DESTE vídeo. Dois vídeos seus sobre assuntos diferentes não podem sair parecidos.
+6. MÍDIA COM PROPÓSITO. Só peça imagem ou logo quando ela PROVA algo. Diga o termo de busca de verdade ("painel solar em telhado residencial", não "imagem legal").
+6b. CADA FRASE PEDE UMA ROTA DE IMAGEM, nesta ordem: número ou citação → nenhuma (a tipografia é a imagem); fala do produto → a tela ou a logo dele; coisa concreta → o vídeo DELA, com a busca no substantivo ("espresso cup", não a frase inteira); ideia abstrata → textura que se move. A imagem entra logo DEPOIS da palavra que a nomeia, nunca antes.
+7. MOVIMENTO. Em cada cena diga em "chaves" o movimento principal — é ele que tira a cara de apresentação parada.
+8. CÂMERA COM PARCIMÔNIA. Movimento de quadro em UMA cena a cada duas ou três ("camera": "nenhuma" nas outras): o que dá ritmo é alternar cena parada e cena que se move. Em cena com foto de fundo, prefira "aproximar" ou "empurrar".
+9. UMA VOZ OU DUAS. Se o pedido fala em dois narradores, duas vozes, diálogo, conversa ou entrevista, escreva como DIÁLOGO: dê nome a cada um em "vozes" (com vozes diferentes) e diga em cada cena quem fala ("falante"). Com uma voz só, deixe "vozes" e "falante" de fora.
+
+${cardapioEstruturas()}`;
+};
+
+const REVISAO = (defeitos) => `O plano voltou com defeitos de FORMA. Corrija SÓ o que está listado e devolva o JSON inteiro de novo, no mesmo formato:
+
+${defeitos.map((d) => '- ' + d).join('\n')}
+
+Nada de explicação: só o bloco \`\`\`json.`;
+
+/** Tira o JSON do que o modelo escreveu, com ou sem cerca. */
+function extrairJSON(texto) {
+    const t = String(texto || '');
+    const cerca = t.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const cru = cerca ? cerca[1] : t.slice(t.indexOf('{'), t.lastIndexOf('}') + 1);
+    try { return JSON.parse(cru); } catch { /* tenta limpar vírgula sobrando */ }
+    try { return JSON.parse(String(cru).replace(/,\s*([}\]])/g, '$1')); } catch { return null; }
+}
+
+/**
+ * Roda o diretor: uma conversa própria, o plano de volta, conferido, e uma
+ * segunda chance quando a forma não fecha.
+ *
+ * @param {object} op
+ * @param {string} op.pedido
+ * @param {(prompt:string, papel:string)=>Promise<string>} op.correr  uma conversa NOVA
+ * @param {number} [op.segundos]
+ * @param {(s:string)=>void} [op.mostrar]
+ */
+async function planejar({ pedido, correr, segundos = 30, formato = 'video',
+    contexto = '', mostrar = () => {} } = {}) {
+    if (!pedido) return { ok: false, error: 'Diga o que produzir.' };
+    if (typeof correr !== 'function') return { ok: false, error: 'sem quem rode o diretor' };
+
+    mostrar('diretor — roteiro, narração e voz');
+    let bruto = extrairJSON(await correr(DIRETOR(pedido, { segundos, formato, contexto }), 'diretor'));
+    if (!bruto) return { ok: false, error: 'o diretor não devolveu um plano legível' };
+
+    let { plano, defeitos, ok } = normalizarPlano({ ...bruto, pedido }, { segundos });
+    if (!ok) {
+        mostrar('diretor — corrigindo o plano');
+        const segunda = extrairJSON(await correr(REVISAO(defeitos), 'diretor (revisão)'));
+        if (segunda) {
+            const r2 = normalizarPlano({ ...segunda, pedido }, { segundos });
+            // Fica com o melhor dos dois: a segunda volta só vale se corrigiu.
+            if (r2.defeitos.length <= defeitos.length) ({ plano, defeitos, ok } = r2);
+        }
+    }
+    return { ok: true, plano, defeitos, aprovado: defeitos.length === 0 };
+}
+
+/**
+ * O plano vira a PAUTA do produtor — o texto que a IA de produção recebe no
+ * lugar do pedido cru. Ela não precisa mais decidir o que contar: só montar.
+ */
+function pauta(plano) {
+    const p = plano || {};
+    const linhas = [];
+    linhas.push(`PLANO DE PRODUÇÃO — ${p.titulo}`);
+    linhas.push(`formato ${p.formato} · ${p.proporcao} · ${p.segundos}s · tom ${p.tom}`);
+    if (p.visual) linhas.push(`visual: ${p.visual}`);
+    if (p.estrutura) linhas.push(`estrutura: ${p.estrutura} (mande em roteiro.estrutura)`);
+    if (p.promessa) linhas.push(`promessa: ${p.promessa}`);
+    if (p.publico) linhas.push(`público: ${p.publico}`);
+    linhas.push(`voz: ${p.voz && p.voz.perfil} · ${p.voz && p.voz.instrucao} · ${p.voz && p.voz.idioma}`);
+    if (p.vozes) linhas.push(`vozes: ${Object.entries(p.vozes).map(([k, v]) => `${k} = ${v}`).join(', ')} (mande em roteiro.vozes, e falante em cada parte)`);
+    if (p.trilha) linhas.push(`trilha: ${p.trilha.busca || p.trilha.arquivo} (volume ${p.trilha.volume})`);
+    linhas.push('');
+    (p.cenas || []).forEach((c, i) => {
+        linhas.push(`CENA ${i + 1} — ${c.duracao}s · entra: ${c.transicao}`);
+        if (c.titulo) linhas.push(`  na tela: ${c.titulo}`);
+        if (c.aTela) linhas.push(`  composição: ${c.aTela}`);
+        if (c.fundo) linhas.push(`  fundo: ${typeof c.fundo === 'string' ? c.fundo : JSON.stringify(c.fundo)}`);
+        linhas.push(`  narração${c.falante ? ` (${c.falante})` : ''}: ${c.narracao}`);
+        if (c.camera && c.camera !== 'nenhuma') linhas.push(`  câmera: ${c.camera}`);
+        if (c.chaves) linhas.push(`  movimento: ${c.chaves}`);
+        (c.midia || []).forEach((m) => linhas.push(
+            `  mídia: ${m.tipo || 'imagem'} "${m.busca}" como ${m.papel || 'destaque'}${m.semFundo ? ' (sem fundo)' : ''}`));
+        if (c.notas) linhas.push(`  nota: ${c.notas}`);
+        linhas.push('');
+    });
+    linhas.push('Produza EXATAMENTE este plano. As decisões de conteúdo já foram tomadas:');
+    linhas.push('não invente cena, não troque a ordem, não reescreva a narração.');
+    return linhas.join('\n');
+}
+
+module.exports = {
+    precisaDeProducao, precisaDeEdicao, vozPara, ritmoPara,
+    ESTRUTURAS, recentes, cardapioEstruturas, registrarEstrutura,
+    normalizarPlano, extrairJSON, planejar, pauta,
+    DIRETOR, REVISAO,
+};