primocode 11.1.0 → 11.2.0

package/lib/motor/eventos.js

@@ -0,0 +1,77 @@
+// Eventos do motor (docs/estrutura.md, seção 3). O motor só EMITE; quem
+// desenha (terminal, app desktop, -p) assina. Node puro, sem dependência.
+'use strict';
+
+const EVENTOS = Object.freeze({
+    TURNO_COMECOU: 'turn/started',
+    TURNO_TERMINOU: 'turn/completed',
+    TURNO_INTERROMPIDO: 'turn/interrupted',
+    ITEM_COMECOU: 'item/started',
+    ITEM_DELTA: 'item/delta',
+    ITEM_TERMINOU: 'item/completed',
+    STATUS: 'status/changed',
+    USO: 'usage/updated',
+    APROVACAO: 'approval/requested',
+    PERGUNTA: 'question/requested',
+    AVISO: 'notice/created',
+});
+
+const TIPOS = Object.freeze(Object.values(EVENTOS));
+
+/* Cada "vista" é uma coisa que a tela do terminal sabe desenhar. O evento
+   carrega os campos do contrato (`evento`, `id`, `tipo`, `estado`) e os dados
+   que a tela precisa. Estados: rodando · ok · erro · interrompido. */
+const VISTAS = Object.freeze({
+    'spinner-inicia':  { evento: EVENTOS.STATUS, tipo: 'status', estado: 'rodando' },
+    'spinner-detalhe': { evento: EVENTOS.STATUS, tipo: 'status', estado: 'rodando' },
+    'spinner-para':    { evento: EVENTOS.STATUS, tipo: 'status', estado: 'parado' },
+    'pensamento':      { evento: EVENTOS.ITEM_TERMINOU, tipo: 'raciocinio', estado: 'ok' },
+    'resposta':        { evento: EVENTOS.ITEM_TERMINOU, tipo: 'mensagem', estado: 'ok' },
+    'fluxo-inicia':    { evento: EVENTOS.ITEM_COMECOU, tipo: 'mensagem', estado: 'rodando' },
+    'fluxo-escreve':   { evento: EVENTOS.ITEM_DELTA, tipo: 'mensagem', estado: 'rodando' },
+    'fluxo-fecha':     { evento: EVENTOS.ITEM_TERMINOU, tipo: 'mensagem', estado: 'ok' },
+    'acao':            { evento: EVENTOS.ITEM_COMECOU, tipo: 'chamada', estado: 'rodando' },
+    'resultado':       { evento: EVENTOS.ITEM_TERMINOU, tipo: 'chamada', estado: 'ok' },
+    'resultado-linha': { evento: EVENTOS.ITEM_TERMINOU, tipo: 'chamada', estado: 'ok' },
+    'paralelo':        { evento: EVENTOS.ITEM_COMECOU, tipo: 'agente', estado: 'rodando' },
+    'agente':          { evento: EVENTOS.ITEM_COMECOU, tipo: 'agente', estado: 'rodando' },
+    'agente-voltou':   { evento: EVENTOS.ITEM_TERMINOU, tipo: 'agente', estado: 'ok' },
+    'estudio-progresso': { evento: EVENTOS.ITEM_DELTA, tipo: 'estudio', estado: 'rodando' },
+    'aviso':           { evento: EVENTOS.AVISO, tipo: 'aviso', estado: 'ok' },
+    'problema':        { evento: EVENTOS.AVISO, tipo: 'aviso', estado: 'erro' },
+    'linha':           { evento: EVENTOS.AVISO, tipo: 'aviso', estado: 'ok' },
+});
+
+let SEQ = 0;
+const novoId = () => `i${++SEQ}`;
+
+/* Monta um evento a partir de uma vista. `dados.id` junta eventos do mesmo
+   item (spinner, fluxo); sem ele nasce um id novo. */
+function montar(vista, dados) {
+    const base = VISTAS[vista];
+    if (!base) throw new Error(`vista desconhecida: ${vista}`);
+    return Object.assign({ vista, id: novoId() }, base, dados || {});
+}
+
+/* Emissor mínimo. on('*', fn) escuta tudo. Um assinante que quebra não
+   derruba o turno. emitir(evento) aceita o objeto montado por `montar`. */
+function criarEmissor() {
+    const ouvintes = new Map();
+    const on = (tipo, fn) => {
+        if (!ouvintes.has(tipo)) ouvintes.set(tipo, new Set());
+        ouvintes.get(tipo).add(fn);
+        return () => off(tipo, fn);
+    };
+    const off = (tipo, fn) => { const s = ouvintes.get(tipo); if (s) s.delete(fn); };
+    const emitir = (evento) => {
+        if (!evento || !evento.evento) return;
+        for (const chave of [evento.evento, '*']) {
+            for (const fn of [...(ouvintes.get(chave) || [])]) {
+                try { fn(evento); } catch (e) { if (process.env.PRIMOCODE_DEBUG) console.error('[motor] ouvinte falhou:', e && e.message); }
+            }
+        }
+    };
+    return { on, off, emitir };
+}
+
+module.exports = { EVENTOS, TIPOS, VISTAS, montar, novoId, criarEmissor };

package/lib/motor/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+    ...require('./eventos'),
+    ...require('./turno'),
+    ...require('./aprovacao'),
+    telaTerminal: require('./tela-terminal'),
+};

package/lib/motor/tela-terminal.js

@@ -0,0 +1,64 @@
+// A tela de terminal: assina os eventos do motor e chama exatamente o que
+// `runAct` chamava antes de a tela sair do turno (fala.*, Spinner, logResult).
+// Mesma saída, mesma ordem. O motor não sabe que isto existe.
+'use strict';
+
+const { criarEmissor } = require('./eventos');
+
+/* Uma tela por turno: guarda os spinners e os fluxos abertos, por id. */
+function conectar(emissor) {
+    const em = emissor || criarEmissor();
+    const spinners = new Map();
+    const fluxos = new Map();
+
+    em.on('*', (e) => {
+        // Carregados na hora de usar: act.js carrega este arquivo, e o contrário seria um ciclo.
+        const fala = require('../fala');
+        const { c, Spinner } = require('../tui/ui');
+        const act = require('../session/runner/act');
+        const p = e.profundidade;
+        switch (e.vista) {
+            case 'spinner-inicia':
+                spinners.set(e.id, new Spinner(e.rotulo).start());
+                break;
+            case 'spinner-detalhe': {
+                const sp = spinners.get(e.id);
+                if (sp) sp.detalhe = e.detalhe;
+                break;
+            }
+            case 'spinner-para': {
+                const sp = spinners.get(e.id);
+                if (sp) sp.stop();
+                break;
+            }
+            case 'pensamento': fala.pensamento(e.texto, p); break;
+            case 'resposta': fala.resposta(e.texto); break;
+            case 'fluxo-inicia': {
+                const f = fala.fluxo();
+                fluxos.set(e.id, f);
+                if (e.texto) f.escrever(e.texto);
+                break;
+            }
+            case 'fluxo-escreve': { const f = fluxos.get(e.id); if (f) f.escrever(e.texto); break; }
+            case 'fluxo-fecha': { const f = fluxos.get(e.id); if (f) { f.fechar(); fluxos.delete(e.id); } break; }
+            case 'acao': require('../cli-nova').contar(); fala.acao(e.nome, e.args, p); break;
+            case 'resultado': act.logResult(e.nome, e.resultado, p); break;
+            case 'resultado-linha':
+                console.log(fala.resultado(p) + (e.nivel === 'aviso' ? c.warn(e.texto) : c.muted(e.texto)));
+                break;
+            case 'paralelo': fala.paralelo(e.quantos, p); break;
+            case 'agente': fala.agente(e.rotulo, e.descricao, p); break;
+            case 'agente-voltou': fala.agenteVoltou(e.texto, p); break;
+            case 'aviso': fala.aviso(e.texto); break;
+            case 'problema': fala.problema(e.erro); break;
+            case 'linha': console.log(e.nivel === 'aviso' ? c.warn(e.texto) : e.nivel === 'ok' ? c.ok(e.texto) : e.nivel === 'dim' ? c.dim(e.texto) : e.texto); break;
+            default: break;
+        }
+    });
+    return em;
+}
+
+/* A função `emitir` pronta para o runAct: uma tela de terminal nova. */
+function criar() { return conectar().emitir; }
+
+module.exports = { conectar, criar };

package/lib/motor/turno.js

@@ -0,0 +1,43 @@
+// Um turno sem tela: chama o runAct e emite o ciclo do turno.
+'use strict';
+
+const { EVENTOS, novoId } = require('./eventos');
+
+/* `iniciarTurno({ texto, ...opts, emitir })`. Sem `emitir`, usa a tela de terminal.
+   `opts` são os mesmos do runAct (server, model, token, history, projectDir…). */
+async function iniciarTurno({ texto, emitir, portao, ...opts }) {
+    const act = require('../session/runner/act');
+    const saida = emitir || require('./tela-terminal').criar();
+    const id = novoId();
+    const t0 = Date.now();
+    saida({ evento: EVENTOS.TURNO_COMECOU, id, tipo: 'turno', estado: 'rodando', texto });
+    let r;
+    try {
+        // Com `portao` (lib/motor/aprovacao.js), aprovações e perguntas viram eventos.
+        const viaPortao = portao ? { autorizar: portao.autorizar, mudarPasta: opts.mudarPasta || portao.mudarPasta } : {};
+        r = await act.runAct(texto, { ...opts, ...viaPortao, emitir: saida });
+    } catch (erro) {
+        if (portao) portao.cancelar();
+        saida({ evento: EVENTOS.TURNO_INTERROMPIDO, id, tipo: 'turno', estado: 'erro', duracao: Date.now() - t0, erro });
+        throw erro;
+    }
+    const duracao = Date.now() - t0;
+    if (portao) portao.cancelar();
+    // Contexto da conversa para a status line (régua do /compact, lib/memoria-conversa.js).
+    try {
+        const memoria = require('../session/memoria-conversa');
+        const hist = (opts.history || []).concat(r && r.userMessage ? [r.userMessage] : [], r && r.assistantMessage ? [r.assistantMessage] : []);
+        saida({ evento: EVENTOS.USO, id: novoId(), tipo: 'uso', estado: 'ok', contexto: memoria.usoDoContexto(memoria.nova(), hist) });
+    } catch { /* sem medida, a status line fica sem o número */ }
+    if (act.interrompido()) {
+        saida({ evento: EVENTOS.TURNO_INTERROMPIDO, id, tipo: 'turno', estado: 'interrompido', duracao, resultado: r });
+    } else {
+        saida({ evento: EVENTOS.TURNO_TERMINOU, id, tipo: 'turno', estado: 'ok', duracao, resultado: r });
+    }
+    return r;
+}
+
+const interromper = (...a) => require('../session/runner/act').interromper(...a);
+const mandarDuranteATarefa = (...a) => require('../session/runner/act').mandarDuranteATarefa(...a);
+
+module.exports = { iniciarTurno, interromper, mandarDuranteATarefa };

package/lib/motor/voz.js

@@ -0,0 +1,65 @@
+// Voz do app (docs/estrutura.md 6.9): interface com provedor trocável.
+// DECISÃO FINAL DO PROVEDOR PENDENTE com o dono. Aqui só o mínimo que não trava a escolha:
+//  - fala (TTS): provedor "kokoro" (voz local do Estúdio, grátis, gera arquivo de áudio; este módulo NUNCA toca som);
+//  - escuta (STT): fica no renderer (Web Speech API do navegador); o motor só informa que é do navegador.
+// Provedor = { nome, disponivel() -> {ok, motivo?}, falar(texto, arquivo) -> Promise<{ok, error?}> }.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const TETO_TEXTO = 600;
+
+function provedorKokoro({ uv, voz, executar } = {}) {
+    const K = require('../plugin/estudio/kokoro');
+    const achar = () => uv || (() => { try { return require('child_process').execFileSync('which', ['uv'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || null; } catch { return null; } })();
+    return {
+        nome: 'kokoro',
+        disponivel() {
+            if (!achar()) return { ok: false, motivo: 'falta o uv (voz local)' };
+            if (!K.acharEspeak()) return { ok: false, motivo: 'falta o espeak-ng (brew install espeak-ng)' };
+            return { ok: true };
+        },
+        async falar(texto, arquivo) {
+            const r = await K.narrar([{ texto }], arquivo, { voz, uv: achar(), ...(executar ? { executar } : {}) });
+            return r && r.ok ? { ok: true } : { ok: false, error: (r && r.error) || 'a voz não respondeu' };
+        },
+    };
+}
+
+const PROVEDORES = { kokoro: (o) => provedorKokoro(o) };
+
+function criarVoz({ provedor, pasta, escuta = 'navegador' } = {}) {
+    const prov = provedor || PROVEDORES.kokoro();
+    const saida = pasta || path.join(os.tmpdir(), 'primocode-voz');
+    let ativa = false;
+    let n = 0;
+
+    const estado = () => {
+        const d = prov.disponivel();
+        return {
+            ativa, provedor: prov.nome, fala: { disponivel: !!d.ok, motivo: d.ok ? undefined : d.motivo },
+            escuta, decisaoPendente: true,
+        };
+    };
+
+    return {
+        estado,
+        /** Liga o modo voz; com `texto`, gera o arquivo de áudio da fala (não toca). */
+        async iniciar({ texto } = {}) {
+            ativa = true;
+            const e = estado();
+            const t = typeof texto === 'string' ? texto.trim().slice(0, TETO_TEXTO) : '';
+            if (!t) return e;
+            if (!e.fala.disponivel) return { ...e, fala: { ...e.fala, gerou: false } };
+            fs.mkdirSync(saida, { recursive: true });
+            const arquivo = path.join(saida, `fala-${Date.now()}-${++n}.mp3`);
+            const r = await prov.falar(t, arquivo);
+            return r.ok ? { ...e, arquivo } : { ...e, fala: { ...e.fala, gerou: false, motivo: r.error } };
+        },
+        parar() { ativa = false; return estado(); },
+    };
+}
+
+module.exports = { criarVoz, provedorKokoro, PROVEDORES, TETO_TEXTO };

package/lib/piloto.js

@@ -0,0 +1,39 @@
+// Piloto automático (docs/estrutura.md, seção 9): os agentes ligados procuram o que fazer e fazem.
+// Este módulo só decide QUEM roda e QUANDO parar; quem executa é injetado (o app-server passa o motor).
+// Node puro. Um ciclo roda os agentes ligados um de cada vez e para no freio da cota.
+'use strict';
+
+/* O que o agente recebe quando ninguém pediu nada: procurar trabalho no seu terreno. */
+function pedidoDoPiloto(agente, { grupo = false } = {}) {
+    return `[piloto automático] Você é @${agente.nome}. Procure UMA coisa útil para fazer no seu terreno `
+        + `(${agente.onde && agente.onde !== 'fora' ? `projeto ${agente.onde}` : 'fora de projetos'}) e faça. `
+        + 'Tudo que escrever arquivo vai para a pessoa aprovar antes de valer. Se não houver nada a fazer, diga isso em uma frase.'
+        + (grupo ? ' Se precisar de outro agente ligado, chame com spawn_agent (profundidade 1).' : '');
+}
+
+/* Freio padrão: a cota do plano (lib/limites.js). Sem rede vale o modo local generoso. */
+async function freioDaCota() {
+    try {
+        const c = await require('./config/limites').situacao();
+        if (c && (c.ok === false || c.liberado === false || c.restam === 0)) return { parar: true, motivo: 'a cota do plano acabou' };
+    } catch { /* sem leitura, não barra */ }
+    return { parar: false };
+}
+
+/* `ciclo({ agentes, executar, freio, ocupado, grupo })` → { executados:[{agente,ok,resumo}], parou? }.
+   `executar(agente, pedido)` devolve o resumo (texto) ou lança. */
+async function ciclo({ agentes = [], executar, freio = freioDaCota, ocupado = () => false, grupo = false } = {}) {
+    const ligados = agentes.filter((a) => a.ligado);
+    const r = { executados: [], parou: null };
+    if (!ligados.length) { r.parou = 'nenhum agente ligado'; return r; }
+    for (const a of ligados) {
+        if (ocupado()) { r.parou = 'a pessoa está trabalhando'; break; }
+        const f = await freio();
+        if (f && f.parar) { r.parou = f.motivo || 'freio'; break; }
+        try { r.executados.push({ agente: a.nome, ok: true, resumo: String(await executar(a, pedidoDoPiloto(a, { grupo })) || '').slice(0, 400) }); }
+        catch (e) { r.executados.push({ agente: a.nome, ok: false, resumo: (e && e.message) || 'falhou' }); }
+    }
+    return r;
+}
+
+module.exports = { ciclo, pedidoDoPiloto, freioDaCota };

package/lib/plugin/estudio/criar.js

@@ -0,0 +1,113 @@
+// estudio_criar: a porta de entrada simples do Estúdio (docs/estrutura.md, seção 8).
+// Quatro parâmetros fixos (tipo, briefing, duracao, formato); por dentro escolhe a receita,
+// abre o projeto e chama as ferramentas que já existem (estudio_plano, estudio_motion,
+// estudio_render). Não reescreve nada do Estúdio. As dependências entram por parâmetro,
+// para o teste rodar sem rede e sem render.
+'use strict';
+
+const path = require('path');
+
+/* tipo → receita. `via`: 'roteiro' (plano pelo roteirista + render) ou 'motion' (a máquina de motion). */
+const TIPOS = Object.freeze({
+    slides:   { rotulo: 'Slides', via: 'roteiro', formato: '16:9', projeto: 'slides' },
+    video:    { rotulo: 'Vídeo curto', via: 'roteiro', formato: '9:16', projeto: 'video', duracao: [15, 60, 30] },
+    motion:   { rotulo: 'Motion', via: 'motion', formato: '9:16', duracao: [6, 60, 15] },
+    anuncio:  { rotulo: 'Anúncio', via: 'motion', formato: '9:16', duracao: [10, 30, 15], prefixo: 'Anúncio para chamar pra comprar: ' },
+    abertura: { rotulo: 'Abertura de canal', via: 'motion', formato: '16:9', duracao: [5, 5, 5], prefixo: 'Abertura de canal com a marca: ' },
+});
+const FORMATOS = ['9:16', '16:9', '1:1'];
+
+const limitar = (n, [min, max, padrao]) => { n = Number(n); return Number.isFinite(n) && n > 0 ? Math.min(max, Math.max(min, Math.round(n))) : padrao; };
+
+/** Confere os parâmetros. Devolve { ok, tipo, briefing, duracao, formato } ou { ok:false, error }. */
+function normalizar(args = {}) {
+    const tipo = String(args.tipo || '').toLowerCase().trim();
+    const receita = TIPOS[tipo];
+    if (!receita) return { ok: false, error: `tipo "${args.tipo || ''}" não existe. Use um de: ${Object.keys(TIPOS).join(', ')}.` };
+    const briefing = String(args.briefing || '').replace(/\s+/g, ' ').trim();
+    if (briefing.length < 3) return { ok: false, error: 'falta o briefing: diga em uma frase o que criar.' };
+    const formato = FORMATOS.includes(String(args.formato)) ? String(args.formato) : receita.formato;
+    const duracao = receita.duracao ? limitar(args.duracao, receita.duracao) : undefined;
+    return { ok: true, tipo, receita, briefing: briefing.slice(0, 600), formato, duracao };
+}
+
+/** Os arquivos entregues, com o tipo que a tela sabe abrir. */
+function arquivosDe(r) {
+    const lista = [];
+    const por = (caminho, extra) => { if (caminho) lista.push({ nome: path.basename(caminho), caminho, tipo: tipoDoArquivo(caminho), ...extra }); };
+    por(r.arquivo || r.video);
+    if (r.entrega && r.entrega.pasta && Array.isArray(r.entrega.arquivos)) {
+        for (const n of r.entrega.arquivos) { const c = path.join(r.entrega.pasta, n); if (!lista.some((x) => x.caminho === c)) por(c); }
+    }
+    return lista;
+}
+function tipoDoArquivo(c) {
+    const e = path.extname(c).toLowerCase();
+    if (e === '.mp4' || e === '.webm' || e === '.mov') return 'video';
+    if (e === '.pdf') return 'pdf';
+    if (['.png', '.jpg', '.jpeg', '.webp', '.gif'].includes(e)) return 'imagem';
+    if (e === '.html') return 'pagina';
+    return 'arquivo';
+}
+
+/**
+ * @param {object} args    { tipo, briefing, duracao?, formato? }
+ * @param {object} deps    { projeto, plano(args), motion(args), render(args), progresso(pct, etapa) }
+ */
+async function criar(args, deps) {
+    const n = normalizar(args);
+    if (!n.ok) return n;
+    const { tipo, receita, briefing, formato, duracao } = n;
+    const progresso = deps.progresso || (() => {});
+    const falha = (error, extra) => ({ ok: false, error, ...extra });
+
+    progresso(5, 'Abrindo o projeto');
+    const pedido = `${receita.prefixo || ''}${briefing}`;
+    const titulo = briefing.slice(0, 60);
+    const proj = deps.projeto.criar({ titulo, pedido: `${pedido} (${receita.rotulo}, ${formato}${duracao ? `, ${duracao} s` : ''})`, formato: receita.projeto || 'video' });
+    if (!proj || proj.ok === false) return falha((proj && proj.error) || 'não consegui abrir o projeto.');
+    const id = proj.id;
+    const base = { tipo, id, pasta: proj.pasta, formato, duracao, titulo };
+
+    if (receita.via === 'motion') {
+        progresso(15, 'Montando as cenas de motion');
+        const m = await deps.motion({ id, assunto: pedido, formato, duracao });
+        if (!m || m.ok === false) return falha((m && m.error) || 'o motion não saiu.', base);
+        progresso(100, 'Pronto');
+        return { ok: true, ...base, duracao: m.duracao || duracao, arquivo: m.video, arquivos: arquivosDe(m), resumo: `${receita.rotulo} de ${m.duracao || duracao} s.` };
+    }
+
+    progresso(15, 'Escrevendo o roteiro');
+    const pl = await deps.plano({ id, pedido: `${pedido}. Formato ${formato}.`, segundos: duracao });
+    if (!pl || pl.ok === false) return falha((pl && pl.error) || 'não consegui escrever o plano.', base);
+    progresso(40, tipo === 'slides' ? 'Desenhando os slides' : 'Montando o vídeo');
+    const r = await deps.render({ id });
+    if (!r || r.ok === false) return falha((r && r.error) || 'o render não saiu.', { ...base, problemas: r && r.problemas });
+    progresso(100, 'Pronto');
+    return {
+        ok: true, ...base, arquivo: r.arquivo, arquivos: arquivosDe(r), paginas: r.paginas,
+        duracao: r.segundos || duracao,
+        resumo: r.paginas ? `${r.paginas} slides em PDF.` : `${receita.rotulo} de ${r.segundos || duracao} s.`,
+    };
+}
+
+module.exports = { criar, normalizar, TIPOS, FORMATOS, tipoDoArquivo, arquivosDe };
+
+/* Os "quadrados" do Studio no app viram `tipo` no turn/start. O motor traduz o tipo em instrução:
+   o modelo escolhe o caminho (a IA decide); aqui só o cardápio do tipo. Carrossel não tem receita no Estúdio
+   (conferido na fase 7), por isso não há quadrado para ele. */
+const QUADRADOS = Object.freeze({
+    slides:  'Tipo escolhido na tela: Apresentação de slides. Use estudio_criar com tipo "slides" e o briefing do pedido (a skill slides-que-prendem ajuda no conteúdo).',
+    video:   'Tipo escolhido na tela: Vídeo curto vertical. Use estudio_criar com tipo "video" e o briefing do pedido.',
+    motion:  'Tipo escolhido na tela: Motion. Use estudio_criar com tipo "motion" e o briefing do pedido.',
+    anuncio: 'Tipo escolhido na tela: Anúncio de 15 s. Use estudio_criar com tipo "anuncio" e o briefing do pedido.',
+    abertura: 'Tipo escolhido na tela: Abertura de canal de 5 s. Use estudio_criar com tipo "abertura" e o briefing do pedido.',
+    pagina:  'Tipo escolhido na tela: Página ou app. Construa com write_file na pasta do projeto, confira abrindo no navegador e entregue o arquivo principal. Não use o Estúdio.',
+    bug:     'Tipo escolhido na tela: Corrigir um bug. Ache a causa lendo o código do projeto (read_file, grep), corrija com edit_file e crie um teste que pegue o caso; rode os testes e conte o que mudou. Não use o Estúdio.',
+    pr:      'Tipo escolhido na tela: Revisar um PR. Leia o diff do PR (o número ou o link que a pessoa der; gh ou git diff), aponte os riscos do mais grave ao menos grave e sugira a correção. Não use o Estúdio.',
+    app:     'Tipo escolhido na tela: Página ou app. Construa com write_file na pasta do projeto, confira abrindo no navegador e entregue o arquivo principal. Não use o Estúdio.',
+});
+const instrucaoDoTipo = (t) => QUADRADOS[String(t || '').toLowerCase()] || (t ? `Tipo de trabalho escolhido na tela: ${String(t).slice(0, 40)}` : '');
+
+module.exports.QUADRADOS = QUADRADOS;
+module.exports.instrucaoDoTipo = instrucaoDoTipo;

package/lib/plugin/estudio/historico.js

@@ -0,0 +1,60 @@
+// Histórico do Studio no app (studio/history): o que o Estúdio já gerou, com miniatura.
+// Lê as pastas de projeto (lib/estudio/projeto.js) sem mudar nada. Node puro.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { tipoDoArquivo } = require('./criar');
+const Miniatura = require('./miniatura');
+
+const PULAR = new Set(['node_modules', 'remotion', 'midia', 'entrada', 'versoes', '.git']);
+const SAIDAS = new Set(['video', 'pdf', 'imagem']);
+
+/* Procura as saídas em até 2 níveis; imagem solta (quadro de conferência) serve de miniatura, não de entrega. */
+function varrer(pasta, nivel = 0, achados = []) {
+    let itens = [];
+    try { itens = fs.readdirSync(pasta, { withFileTypes: true }); } catch { return achados; }
+    for (const d of itens) {
+        const c = path.join(pasta, d.name);
+        if (d.isDirectory()) { if (nivel < 2 && !PULAR.has(d.name) && !d.name.startsWith('.')) varrer(c, nivel + 1, achados); continue; }
+        const tipo = tipoDoArquivo(c);
+        if (!SAIDAS.has(tipo)) continue;
+        let st; try { st = fs.statSync(c); } catch { continue; }
+        achados.push({ nome: d.name, caminho: c, tipo, bytes: st.size, quando: st.mtimeMs, dentro: path.relative(pasta, c) });
+    }
+    return achados;
+}
+
+/** { itens, total }. `busca` filtra por título e pedido (sem acento); `limite` padrão 60. */
+function historico({ busca = '', limite = 60, projeto, miniaturaDeVideo } = {}) {
+    // Vídeo na grade vira um JPG (cache ao lado do vídeo). Até 4 saem na hora; o resto sai em segundo plano e aparece na próxima abertura.
+    const quadro = miniaturaDeVideo || Miniatura.gerar;
+    let gerados = 0;
+    const P = projeto || require('./projeto');
+    const sem = (s) => String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+    const q = sem(busca).trim();
+    const itens = [];
+    for (const p of P.listar({ limite: 400 })) {
+        if (q && !sem(`${p.titulo} ${p.pedido}`).includes(q)) continue;
+        const todos = varrer(p.pasta).sort((a, b) => b.quando - a.quando);
+        const entregas = todos.filter((a) => a.tipo !== 'imagem' || /^saida\b/.test(a.dentro) || !todos.some((x) => x.tipo !== 'imagem'));
+        const principal = entregas.find((a) => a.tipo === 'video') || entregas.find((a) => a.tipo === 'pdf') || entregas[0] || null;
+        const imagem = todos.find((a) => a.tipo === 'imagem');
+        let miniatura = null;
+        if (principal && principal.tipo === 'imagem') miniatura = { tipo: 'imagem', caminho: principal.caminho };
+        else if (principal && principal.tipo === 'video') {
+            let jpg = Miniatura.emCache(principal.caminho);
+            if (!jpg && gerados < 4) { gerados++; jpg = quadro(principal.caminho); }
+            else if (!jpg && !miniaturaDeVideo) Miniatura.gerarDepois(principal.caminho);
+            miniatura = jpg ? { tipo: 'imagem', caminho: jpg, deVideo: true } : (imagem ? { tipo: 'imagem', caminho: imagem.caminho } : { tipo: 'video-sem-quadro', caminho: principal.caminho });
+        } else if (imagem) miniatura = { tipo: 'imagem', caminho: imagem.caminho };
+        itens.push({
+            id: p.id, titulo: p.titulo, formato: p.formato || 'video', criado: p.criado, mudado: p.mudado || p.criado,
+            pasta: p.pasta, arquivos: entregas.map(({ dentro, ...a }) => a), principal: principal ? principal.caminho : null, miniatura,
+            pronto: entregas.length > 0,
+        });
+    }
+    return { itens: itens.slice(0, Math.max(1, Number(limite) || 60)), total: itens.length };
+}
+
+module.exports = { historico, varrer };

package/lib/plugin/estudio/index.js

@@ -748,6 +748,19 @@ async function renderMotion(args, p, receita) {
     return { ...r, ...(gostoResumo ? { gosto: gostoResumo } : {}), nota: 'Abra os quadros (png em ae/) para conferir. Se algo ficou torto, mude o JSON e rode de novo.' };
 }
 
+// ── estudio_criar ────────────────────────────────────────────────────────
+
+/** A porta simples (criar.js): escolhe a receita e chama as ferramentas de cima. `ctx.progresso(pct, etapa)` alimenta o item da tela. */
+async function ferramentaCriar(args, ctx = {}) {
+    return require('./criar.js').criar(args, {
+        projeto,
+        plano: (a) => ferramentaPlano({ ...a, __pasta: ctx.projectDir }),
+        motion: (a) => ferramentaMotion(a),
+        render: (a) => ferramentaRender({ ...a, __pasta: ctx.projectDir }, ctx),
+        progresso: ctx.progresso,
+    });
+}
+
 // ── estudio_editar ───────────────────────────────────────────────────────
 
 /** O editor por comando: reabre o plano da máquina de motion, aplica as mudanças e guarda a versão (editor.js). */
@@ -2706,7 +2719,7 @@ async function ferramentaSite(args) {
 
 module.exports = { proporcaoDoPedido,
     vazamentoNoComeco, variarIcones, objetosDoRoteiro,
-    ferramentaProjeto, ferramentaPlano, ferramentaMidia, ferramentaAE, ferramentaMotion, ferramentaEditar, ferramentaNarrar,
+    ferramentaProjeto, ferramentaPlano, ferramentaMidia, ferramentaAE, ferramentaMotion, ferramentaEditar, ferramentaNarrar, ferramentaCriar,
     ferramentaVideo, ferramentaRender, ferramentaSite,
     projeto, plano, remotion, assets, video, identidade, slides, python, rodarPython, alinharPartes, prepararRoteiro, roteiroValido, juntarVozes,
 };

package/lib/plugin/estudio/miniatura.js

@@ -0,0 +1,56 @@
+// Miniatura de vídeo para a grade do Studio: um quadro em JPG, gerado pelo ffmpeg e guardado em cache ao lado
+// do vídeo (<pasta do vídeo>/.miniaturas/<nome>.jpg). A tela mostra <img>, nunca <video> na grade: vídeo em formato
+// que o Chromium não decodifica loga "Unsupported pixel format" só de abrir. Node puro, só `ffmpeg` do sistema.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+
+const PASTA = '.miniaturas';
+const LARGURA = 480;
+const emAndamento = new Set();
+
+const destinoDe = (video) => path.join(path.dirname(video), PASTA, `${path.basename(video)}.jpg`);
+const argsDe = (video, saida) => ['-v', 'error', '-ss', '0.5', '-i', video, '-frames:v', '1', '-vf', `scale=${LARGURA}:-2`, '-q:v', '4', '-y', saida];
+
+/* O cache vale enquanto o JPG existe, tem conteúdo e não é mais velho que o vídeo. */
+function emCache(video) {
+    const jpg = destinoDe(video);
+    try {
+        const j = fs.statSync(jpg); const v = fs.statSync(video);
+        return j.size > 0 && j.mtimeMs >= v.mtimeMs ? jpg : null;
+    } catch { return null; }
+}
+
+function ffmpegExiste(ffmpeg = 'ffmpeg') {
+    try { return spawnSync(ffmpeg, ['-version'], { stdio: 'ignore', timeout: 4000 }).status === 0; } catch { return false; }
+}
+
+/* Gera agora (bloqueia até uns segundos). Devolve o caminho do JPG, ou null se não deu. */
+function gerar(video, { ffmpeg = 'ffmpeg', espera = 8000 } = {}) {
+    const hit = emCache(video);
+    if (hit) return hit;
+    const jpg = destinoDe(video);
+    try { fs.mkdirSync(path.dirname(jpg), { recursive: true }); } catch { return null; }
+    try { spawnSync(ffmpeg, argsDe(video, jpg), { stdio: 'ignore', timeout: espera }); } catch { /* sem ffmpeg */ }
+    const ok = emCache(video);
+    if (!ok) { try { fs.rmSync(jpg, { force: true }); } catch { /* nada */ } }
+    return ok;
+}
+
+/* Gera sem bloquear (a próxima abertura do histórico já acha o JPG). Um por vídeo ao mesmo tempo. */
+function gerarDepois(video, { ffmpeg = 'ffmpeg' } = {}) {
+    if (emAndamento.has(video) || emCache(video)) return;
+    const jpg = destinoDe(video);
+    try { fs.mkdirSync(path.dirname(jpg), { recursive: true }); } catch { return; }
+    emAndamento.add(video);
+    let p;
+    try { p = spawn(ffmpeg, argsDe(video, jpg), { stdio: 'ignore' }); } catch { emAndamento.delete(video); return; }
+    const fim = () => { emAndamento.delete(video); if (!emCache(video)) { try { fs.rmSync(jpg, { force: true }); } catch { /* nada */ } } };
+    p.on('error', fim); p.on('close', fim);
+    const t = setTimeout(() => { try { p.kill('SIGKILL'); } catch { /* já saiu */ } }, 20000);
+    if (t.unref) t.unref();
+}
+
+module.exports = { gerar, gerarDepois, emCache, destinoDe, ffmpegExiste, PASTA };

package/lib/plugin/video/auto.js

@@ -301,7 +301,7 @@ const OPS = {
             const ver = plano.passos.map((p) => ({ op: p.op, motivo: p.motivo, args: p.args }));
             if (a.dryRun) return { ok: true, plano: ver, legenda: plano.legenda, segundos: 'da gravação' };
 
-            const { OPS: TODAS } = require('./ops.js');
+            const TODAS = require('./catalogo.js').catalogo();
             const feitos = [];
             const roda = async (op, args, motivo) => {
                 const res = await TODAS[op].run(ctx, args);

package/lib/plugin/video/catalogo.js

@@ -0,0 +1,20 @@
+/**
+ * catalogo.js — o catálogo completo das operações. ops.js registra aqui ao
+ * carregar; auto.js e pedido.js leem daqui para encadear operações sem
+ * importar ops.js (que os importa: isso fechava um ciclo).
+ */
+
+'use strict';
+
+let todas = null;
+
+function registrar(ops) {
+    todas = ops;
+}
+
+function catalogo() {
+    if (!todas) throw new Error('catálogo de operações vazio: carregue lib/video/ops.js antes');
+    return todas;
+}
+
+module.exports = { registrar, catalogo };

package/lib/plugin/video/mutar.js

@@ -0,0 +1,28 @@
+/**
+ * mutar.js — o caminho de toda operação que MUDA o projeto: foto de antes,
+ * edição, validação, gravação, delta. Se qualquer passo falha, nada é gravado.
+ *
+ * Mora fora de ops.js para os módulos de operação (ops-fx, zoom) usarem sem
+ * importar o catálogo que os importa.
+ */
+
+'use strict';
+
+const T = require('./timeline.js');
+const { diff } = require('./delta.js');
+const P = require('./projeto.js');
+
+async function mutar(ctx, op, fn) {
+    const antes = T.clone(ctx.tl);
+    const extra = (await fn(ctx.tl)) || {};
+    T.ordenar(ctx.tl);
+    const probs = T.problemas(ctx.tl);
+    if (probs.length) throw T.erro(`edição recusada (nada mudou): ${probs.slice(0, 4).join('; ')}`);
+    P.fotografar(ctx.p, antes, op);
+    P.salvar(ctx.p, ctx.tl);
+    const d = diff(antes, ctx.tl, extra);
+    P.anotar(ctx.p, op, { dur: d.dur, added: (d.added || []).length, removed: (d.removed || []).length });
+    return d;
+}
+
+module.exports = { mutar };