primocode 10.17.1 → 11.0.0

package/lib/estudio/kits-tela.js

@@ -0,0 +1,199 @@
+/**
+ * kits-tela.js — a tela de estilos: os 50 kits (lib/kits.js) no mesmo carrossel da tela de gosto.
+ *
+ *   "O primeiro pedido de motion e o /styles abrem ESTA tela; a escolha volta pro PrimoCode
+ *    como a da tela de gosto." (Joel, 26/10)
+ *
+ * A página é lib/estudio/kits/tela.html, uma CÓPIA de gosto/tela.html (que não muda) com os kits no lugar
+ * dos 20 estilos fixos: capa.jpg no cartão, preview.mp4 com o mouse em cima (renderizado aqui na primeira
+ * vez, num filho `primocode kit preview <slug>`, pra não travar o servidor), nome, família e descrição.
+ *
+ * Abre igual à de gosto: no terminal, o navegador; no app (PRIMOCODE_APP=1), a linha `primocode:abrir-gosto <url>`
+ * no stderr (mesmo formato de URL: o app já abre e fecha a janela sozinho no /salvar e /pular).
+ *
+ *   abrirTela()        servidor 127.0.0.1 + token; resolve {ok:true, slug} | {ok:false, motivo}
+ *   abrirOndeDer()     /styles: terminal → navegador, app → linha de protocolo
+ *   primeiroMotion()   só abre se a pessoa nunca escolheu (nem pulou) e há gente do outro lado
+ *   lerEscolha()       ~/.primocode/kit-escolhido.json: {slug, quando} ou {pulou:true}
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+
+const arquivoEscolha = (home = os.homedir()) => path.join(home, '.primocode', 'kit-escolhido.json');
+function lerEscolha(home) { try { return JSON.parse(fs.readFileSync(arquivoEscolha(home), 'utf8')); } catch { return null; } }
+function salvarEscolha(dados, home) {
+    const arq = arquivoEscolha(home);
+    fs.mkdirSync(path.dirname(arq), { recursive: true });
+    const d = { ...dados, quando: new Date().toISOString() };
+    fs.writeFileSync(arq, JSON.stringify(d, null, 1));
+    return d;
+}
+
+/** Mesma regra da tela de gosto: 'app' (linha de protocolo), 'terminal' (navegador) ou null (CI, script sem app). */
+function modoTela(env = process.env, tty = !!process.stdout.isTTY) {
+    if (env.CI) return null;
+    if (env.PRIMOCODE_APP === '1') return 'app';
+    if (env.PRIMOCODE_SEM_TELA || !tty) return null;
+    return 'terminal';
+}
+
+/** O preview de um kit, renderizado num filho (o render leva ~20 s; a 1ª vez instala o estúdio dos kits). */
+function renderEmFilho(slug, { home, env = process.env } = {}) {
+    return new Promise((resolve) => {
+        const bin = path.join(__dirname, '..', '..', 'bin', 'primocode.js');
+        const p = spawn(process.execPath, [bin, 'kit', 'preview', slug], { env: { ...env, ...(home ? { HOME: home } : {}), PRIMOCODE_SEM_TELA: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+        let saida = '';
+        p.stdout.on('data', (d) => { saida = (saida + d).slice(-2000); });
+        p.stderr.on('data', (d) => { saida = (saida + d).slice(-2000); });
+        p.on('close', (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: saida.split('\n').filter(Boolean).slice(-1)[0] || `saiu com ${code}` }));
+        p.on('error', (e) => resolve({ ok: false, error: e.message }));
+    });
+}
+
+function dadosDaTela(K, home, inicial) {
+    const todos = K.listar({ home });
+    const familias = [...new Set([...K.FAMILIAS, ...todos.map((k) => k.familia)])].filter((f) => todos.some((k) => k.familia === f));
+    // na ordem das famílias, pra o chip de família levar a um bloco seguido
+    const kits = familias.flatMap((f) => todos.filter((k) => k.familia === f)).map((k) => ({
+        slug: k.slug, nome: k.nome, familia: k.familia, descricao: k.descricao, preview: !!K.previewPronto(k, { home }),
+    }));
+    return { kits, familias, inicial: inicial && kits.some((k) => k.slug === inicial) ? inicial : null };
+}
+
+/** Manda um arquivo com suporte a Range (o <video> do WebKit pede pedaços). */
+function servirArquivo(req, res, arq, tipo) {
+    let st;
+    try { st = fs.statSync(arq); } catch { res.writeHead(404); return res.end(); }
+    const r = /bytes=(\d*)-(\d*)/.exec(req.headers.range || '');
+    if (r) {
+        const ini = r[1] ? Number(r[1]) : Math.max(0, st.size - Number(r[2] || 0));
+        const fim = r[1] && r[2] ? Math.min(Number(r[2]), st.size - 1) : st.size - 1;
+        if (ini >= st.size || ini > fim) { res.writeHead(416, { 'content-range': `bytes */${st.size}` }); return res.end(); }
+        res.writeHead(206, { 'content-type': tipo, 'content-length': fim - ini + 1, 'content-range': `bytes ${ini}-${fim}/${st.size}`, 'accept-ranges': 'bytes', 'cache-control': 'no-store' });
+        return fs.createReadStream(arq, { start: ini, end: fim }).pipe(res);
+    }
+    res.writeHead(200, { 'content-type': tipo, 'content-length': st.size, 'accept-ranges': 'bytes', 'cache-control': 'no-store' });
+    fs.createReadStream(arq).pipe(res);
+}
+
+/**
+ * Abre a tela. Resolve {ok:true, slug, kit} (escolheu), {ok:false, motivo:'pulou'|'fechou'|'tempo'|'sem_tela'}.
+ * `abrir(url)`, `home`, `renderPreview(slug)` e `timeoutMs` são injetáveis (testes). `inicial`: o kit que já vem marcado.
+ */
+function abrirTela({ home, abrir, timeoutMs = 10 * 60 * 1000, porta = 0, inicial, renderPreview, env = process.env } = {}) {
+    const K = require('../kits.js');
+    const render = renderPreview || ((slug) => renderEmFilho(slug, { home, env }));
+    return new Promise((resolve) => {
+        const token = crypto.randomBytes(16).toString('hex');
+        let html;
+        try { html = fs.readFileSync(path.join(__dirname, 'kits', 'tela.html'), 'utf8'); } catch { return resolve({ ok: false, motivo: 'sem_tela' }); }
+        const dados = JSON.stringify(dadosDaTela(K, home, inicial)).replace(/</g, '\\u003c');
+        const previews = new Map();   // slug → {estado:'fazendo'|'erro', motivo}
+        const fila = [];
+        let rodando = false;
+        const proximo = async () => {
+            if (rodando || !fila.length) return;
+            rodando = true;
+            const slug = fila.shift();
+            previews.set(slug, { estado: 'fazendo', motivo: 'renderizando o preview (~20 s)…' });
+            let r;
+            try { r = await render(slug); } catch (e) { r = { ok: false, error: e.message }; }
+            previews.set(slug, r && r.ok ? { estado: 'pronto' } : { estado: 'erro', motivo: String((r && r.error) || 'falhou').slice(0, 160) });
+            rodando = false;
+            proximo();
+        };
+        let fim = false, timer = null;
+        const srv = http.createServer(async (req, res) => {
+            const u = new URL(req.url, 'http://127.0.0.1');
+            const dizer = (cod, corpo, tipo = 'application/json; charset=utf-8') => { res.writeHead(cod, { 'content-type': tipo, 'cache-control': 'no-store' }); res.end(typeof corpo === 'string' ? corpo : JSON.stringify(corpo)); };
+            const slugDa = (pre) => decodeURIComponent(u.pathname.slice(pre.length));
+            try {
+                if (req.method === 'GET') {
+                    if (u.searchParams.get('t') !== token) return dizer(403, 'token inválido', 'text/plain; charset=utf-8');
+                    if (u.pathname === '/') return dizer(200, html.split('__TOKEN__').join(token).split('__DADOS__').join(dados), 'text/html; charset=utf-8');
+                    if (u.pathname.startsWith('/capa/')) {
+                        const k = K.achar(slugDa('/capa/'), { home });
+                        if (!k || !k.capa) return dizer(404, 'sem capa', 'text/plain; charset=utf-8');
+                        return servirArquivo(req, res, k.capa, 'image/jpeg');
+                    }
+                    if (u.pathname.startsWith('/preview/')) {
+                        const k = K.achar(slugDa('/preview/'), { home });
+                        const arq = k && K.previewPronto(k, { home });
+                        if (!arq) return dizer(404, 'sem preview', 'text/plain; charset=utf-8');
+                        return servirArquivo(req, res, arq, 'video/mp4');
+                    }
+                    return dizer(404, 'não achei', 'text/plain; charset=utf-8');
+                }
+                if (req.method !== 'POST') return dizer(405, 'não', 'text/plain; charset=utf-8');
+                if (req.headers['x-gosto-token'] !== token) return dizer(403, { ok: false, error: 'token inválido' });
+                if (u.pathname.startsWith('/preview/')) {
+                    const k = K.achar(slugDa('/preview/'), { home });
+                    if (!k) return dizer(404, { ok: false, error: 'kit não existe' });
+                    if (K.previewPronto(k, { home })) return dizer(200, { ok: true, estado: 'pronto' });
+                    const e = previews.get(k.slug);
+                    if (e && e.estado === 'erro') return dizer(200, { ok: true, ...e });
+                    if (!e) { previews.set(k.slug, { estado: 'fazendo', motivo: fila.length || rodando ? 'na fila do preview…' : 'preparando o preview…' }); fila.push(k.slug); proximo(); }
+                    return dizer(200, { ok: true, ...previews.get(k.slug) });
+                }
+                if (u.pathname === '/fechar') { dizer(200, { ok: true }); return terminar({ ok: false, motivo: 'fechou' }); }
+                if (u.pathname === '/pular') { salvarEscolha({ pulou: true }, home); dizer(200, { ok: true }); return terminar({ ok: false, motivo: 'pulou' }); }
+                if (u.pathname === '/salvar') {
+                    let corpo = '';
+                    for await (const c of req) { corpo += c; if (corpo.length > 4096) return dizer(413, { ok: false, error: 'grande' }); }
+                    let slug = '';
+                    try { slug = String(JSON.parse(corpo).slug || ''); } catch { /* corpo ruim */ }
+                    const k = slug && K.achar(slug, { home });
+                    if (!k || k.slug !== slug) return dizer(400, { ok: false, error: `o estilo "${slug}" não existe` });
+                    salvarEscolha({ slug: k.slug }, home);
+                    dizer(200, { ok: true, slug: k.slug });
+                    return terminar({ ok: true, slug: k.slug, kit: k });
+                }
+                dizer(404, { ok: false, error: 'não achei' });
+            } catch (e) { try { dizer(500, { ok: false, error: String(e.message || e) }); } catch { /* já respondeu */ } }
+        });
+        function terminar(r) {
+            if (fim) return;
+            fim = true;
+            clearTimeout(timer);
+            try { srv.close(); } catch { /* já fechou */ }
+            const t = setTimeout(() => { try { if (srv.closeAllConnections) srv.closeAllConnections(); } catch { /* ok */ } }, 300);
+            if (t.unref) t.unref();
+            resolve(r);
+        }
+        srv.on('error', () => terminar({ ok: false, motivo: 'sem_tela' }));
+        srv.listen(porta, '127.0.0.1', () => {
+            timer = setTimeout(() => terminar({ ok: false, motivo: 'tempo' }), timeoutMs);
+            const url = `http://127.0.0.1:${srv.address().port}/?t=${token}`;
+            try {
+                const r = (abrir || ((x) => require('../tools.js').openInBrowser(x)))(url);
+                if (r && typeof r.catch === 'function') r.catch(() => {});
+            } catch { /* sem navegador */ }
+        });
+    });
+}
+
+/** /styles: no app vai pela linha de protocolo (o app abre a janela); no terminal, pelo navegador. */
+function abrirOndeDer(opcoes = {}, { env = process.env, stderr = process.stderr } = {}) {
+    if (env.PRIMOCODE_APP === '1') {
+        const { linhaProtocolo } = require('./gosto.js');
+        return abrirTela({ ...opcoes, env, abrir: (url) => stderr.write(linhaProtocolo(url)) });
+    }
+    return abrirTela({ ...opcoes, env });
+}
+
+/** O primeiro motion: só abre se a pessoa nunca escolheu nem pulou, e se há gente do outro lado. */
+async function primeiroMotion(opcoes = {}, { env = process.env, tty, stderr = process.stderr } = {}) {
+    if (lerEscolha(opcoes.home)) return { ok: false, motivo: 'ja_escolheu' };
+    const modo = modoTela(env, tty);
+    if (!modo) return { ok: false, motivo: 'nao_abre' };
+    if (modo === 'terminal') { try { stderr.write('  ⎿ Antes do primeiro motion: abri a tela de estilos (até 10 min). Escolha um ou deixe o PrimoCode escolher.\n'); } catch { /* sem terminal */ } }
+    return abrirOndeDer(opcoes, { env, stderr });
+}
+
+module.exports = { abrirTela, abrirOndeDer, primeiroMotion, lerEscolha, salvarEscolha, arquivoEscolha, modoTela, dadosDaTela, renderEmFilho };

package/lib/estudio/maquina-diretor.js

@@ -333,7 +333,11 @@ function montarDirecao({ args, assunto, meta, duracao, hist, rnd, temElemento })
     if (!pedidas) {
         const n = Math.max(4, Math.round(duracao / media));
         let papeis = papeisPara(duracao, rnd, ultimo && ultimo.molde);
-        while (papeis.length > n + 1 && papeis.includes('processo')) papeis.splice(papeis.lastIndexOf('processo'), 1);
+        while (papeis.length > n && papeis.includes('processo')) papeis.splice(papeis.lastIndexOf('processo'), 1);
+        /* E o contrário: o ritmo pede MAIS cenas que o molde trouxe. Sem isto o "rápido" não cortava mais rápido: o plano
+           reescala a duração pro tempo total (maquina.js), e com o mesmo número de cenas o ritmo sumia (medido em 24/10:
+           2,92 s por cena com e sem gosto). Entra processo ou prova antes do fechamento, até 12 cenas. */
+        while (papeis.length < n && papeis.length < 12) papeis.splice(Math.max(1, papeis.length - 1), 0, papeis.length % 2 ? 'prova' : 'processo');
         pedidas = papeis.map((papel) => ({ papel }));
     }
     const nFotosPedido = Array.isArray(args.fotos) ? args.fotos.length : (Number(args.nFotos) || 0);
@@ -395,7 +399,7 @@ function montarDirecao({ args, assunto, meta, duracao, hist, rnd, temElemento })
 
     // paleta
     const recP = new Map(); hist.slice(-3).forEach((h) => recP.set(h.paleta, (recP.get(h.paleta) || 0) + 1));
-    const paleta = PALETAS[args.paleta] ? args.paleta : sortear(rnd, meta.paletas.map((x) => [x, Math.pow(0.35, recP.get(x) || 0)]));
+    const paleta = PALETAS[args.paleta] ? args.paleta : sortear(rnd, meta.paletas.map((x) => [x, Math.pow(0.35, recP.get(x) || 0) * gm('paletas', x)]));
     const ordemPal = sortear(rnd, [[0, 1], [1, 1], [2, 1]]);
 
     const assinatura = {

package/lib/estudio/materiais.js

@@ -0,0 +1,172 @@
+/**
+ * materiais.js — peças soltas por estilo. A IA monta o vídeo DO ZERO.
+ *
+ * Um estilo migrado tem `materiais/<estilo>/` com só peças (formas, texturas, transições, tipografia, câmera, sons),
+ * a paleta, as regras e o índice `pecas.json`. Não existe Montagem, receita nem plano pronto: a IA lista as peças,
+ * lê as que quer, escreve a cena nova (TSX) e o conferir cobra a densidade mínima.
+ *
+ *   primocode kit pecas <estilo>                 as peças (nome · o que é · params · duração)
+ *   primocode kit pecas <estilo> ver <peça>      o código da peça (ou os dados do áudio)
+ *   primocode kit pecas <estilo> regras          as regras e a densidade mínima
+ *   primocode kit pecas <estilo> escrever <nome> --arquivo <cena.tsx>   grava a cena em motion/ e confere
+ *   primocode kit pecas <estilo> conferir <cena.tsx>
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ = path.join(__dirname, '..', '..', 'materiais');
+const CATEGORIAS = ['formas', 'texturas', 'transicoes', 'tipografia', 'camera', 'sons', 'paleta'];
+/** Nada disto pode existir como peça, nem ser lido nem importado no caminho da IA. */
+const PROIBIDO = /(^|[\\/'"._-])(Montagem|receita|plano)(\.(tsx?|jsx?|json))?(['"]|$)|Montagem\.tsx|receita\.json|plano\.json/;
+const MINIMO = { camadas: 4, pecasDiferentes: 6, chavesCamera: 4, efeitosPorCorte: 1 };
+
+const pastaDe = (estilo, raiz = RAIZ) => path.join(raiz, String(estilo || '').replace(/[^a-z0-9-]/gi, ''));
+
+/** O estilo foi migrado pra peças soltas? */
+function migrado(estilo, raiz = RAIZ) { return !!estilo && fs.existsSync(path.join(pastaDe(estilo, raiz), 'pecas.json')); }
+function estilos(raiz = RAIZ) {
+    try { return fs.readdirSync(raiz, { withFileTypes: true }).filter((d) => d.isDirectory() && migrado(d.name, raiz)).map((d) => d.name); } catch { return []; }
+}
+
+function ler(estilo, raiz = RAIZ) {
+    try { return JSON.parse(fs.readFileSync(path.join(pastaDe(estilo, raiz), 'pecas.json'), 'utf8')); } catch { return null; }
+}
+
+/** Confere o índice: campos, arquivos que existem, nenhuma peça que seja cena/vídeo pronto. Devolve a lista de erros. */
+function validar(estilo, raiz = RAIZ) {
+    const erros = [];
+    const idx = ler(estilo, raiz);
+    if (!idx) return [`materiais/${estilo}/pecas.json ausente ou inválido`];
+    const base = pastaDe(estilo, raiz);
+    if (!Array.isArray(idx.pecas) || !idx.pecas.length) return ['pecas.json sem peças'];
+    const nomes = new Set();
+    for (const p of idx.pecas) {
+        const q = `peça "${p && p.nome}"`;
+        if (!p || !p.nome || !p.categoria || !p.arquivo || !p.descricao) { erros.push(`${q}: faltam nome, categoria, arquivo ou descricao`); continue; }
+        if (nomes.has(p.nome)) erros.push(`${q}: nome repetido`);
+        nomes.add(p.nome);
+        if (!CATEGORIAS.includes(p.categoria)) erros.push(`${q}: categoria "${p.categoria}" fora de ${CATEGORIAS.join(', ')}`);
+        if (!Array.isArray(p.params)) erros.push(`${q}: params precisa ser lista`);
+        if (p.duracao != null && !(Array.isArray(p.duracao) && p.duracao.length === 2 && p.duracao[0] <= p.duracao[1])) erros.push(`${q}: duracao é null ou [min, max]`);
+        if (!Array.isArray(p.tags)) erros.push(`${q}: tags precisa ser lista`);
+        if (/\n/.test(p.descricao) || p.descricao.length > 200) erros.push(`${q}: a descrição é de uma linha (até 200 caracteres)`);
+        if (PROIBIDO.test(p.arquivo) || PROIBIDO.test(p.nome)) erros.push(`${q}: peça não pode ser Montagem, receita ou plano`);
+        const arq = path.join(base, p.arquivo);
+        if (!arq.startsWith(base + path.sep)) erros.push(`${q}: arquivo fora da pasta do estilo`);
+        else if (!fs.existsSync(arq)) erros.push(`${q}: arquivo ${p.arquivo} não existe`);
+        else if (/\.tsx?$/.test(arq) && fs.readFileSync(arq, 'utf8').split('\n').length > 140) erros.push(`${q}: arquivo grande demais pra ser uma peça (mais de 140 linhas)`);
+    }
+    for (const f of ['regras.md', 'paleta.json']) if (!fs.existsSync(path.join(base, f))) erros.push(`falta ${f}`);
+    return erros;
+}
+
+const linha = (p) => `- ${p.nome} [${p.categoria}] ${p.descricao} | params: ${(p.params || []).join(', ') || '-'} | duração: ${p.duracao ? p.duracao.join('-') + ' quadros' : 'contínua'} | tags: ${(p.tags || []).join(', ')}`;
+
+function listar(estilo, raiz = RAIZ) {
+    const idx = ler(estilo, raiz);
+    if (!idx) return { ok: false, texto: `O estilo "${estilo}" não tem peças soltas. Migrados: ${estilos(raiz).join(', ') || 'nenhum'}.` };
+    const porCat = {};
+    for (const p of idx.pecas) (porCat[p.categoria] = porCat[p.categoria] || []).push(p);
+    const out = [`# Peças de ${idx.estilo} (${idx.pecas.length}): só peças soltas, nenhuma cena pronta.`,
+        `Leia as regras (primocode kit pecas ${estilo} regras), leia as peças que vai usar (… ver <peça>), escreva a cena NOVA e grave (… escrever <nome> --arquivo <cena.tsx>).`, ''];
+    for (const c of CATEGORIAS) if (porCat[c]) out.push(`## ${c}`, ...porCat[c].map(linha), '');
+    return { ok: true, texto: out.join('\n').trim() };
+}
+
+function lerPeca(estilo, nome, raiz = RAIZ) {
+    const idx = ler(estilo, raiz);
+    const p = idx && idx.pecas.find((x) => x.nome.toLowerCase() === String(nome || '').toLowerCase());
+    if (!p) return { ok: false, texto: `Peça "${nome}" não existe em ${estilo}. Veja: primocode kit pecas ${estilo}` };
+    const arq = path.join(pastaDe(estilo, raiz), p.arquivo);
+    const cab = linha(p);
+    if (/\.(mp3|wav)$/.test(arq)) return { ok: true, texto: `${cab}\narquivo de áudio: ${p.arquivo} (toque com <Efeito som="${p.nome}" em={quadro}/> ou <Trilha/>; volume sugerido ${p.volumeSugerido ?? '-'})`, peca: p };
+    return { ok: true, texto: `${cab}\nimport: ${p.arquivo.replace(/\.tsx?$/, '')}\n\n${fs.readFileSync(arq, 'utf8')}`, peca: p };
+}
+
+function regras(estilo, raiz = RAIZ) {
+    try { return { ok: true, texto: fs.readFileSync(path.join(pastaDe(estilo, raiz), 'regras.md'), 'utf8') }; } catch { return { ok: false, texto: `Sem regras para ${estilo}.` }; }
+}
+
+/** O texto que entra no prompt da IA pra um estilo migrado (no lugar do `kit ver`). */
+function promptDoEstilo(estilo, raiz = RAIZ) {
+    const l = listar(estilo, raiz);
+    if (!l.ok) return l.texto;
+    return [`ESTILO ${estilo}: montagem a partir de peças soltas. Você COMPÕE a cena do zero; não há vídeo, receita nem plano pronto pra copiar.`,
+        'Passos: 1) leia o pedido e o roteiro; 2) escreva o plano da cena (linha do tempo em quadros, camadas, chaves de câmera, cues de som); 3) leia as peças que vai usar;',
+        '4) escreva UM arquivo TSX com a composição nova: import só do remotion e das peças, no caminho `./pecas/<categoria>/<Peça>` (ex.: `import {Agenda} from "./pecas/formas/Agenda"`, `import {e4} from "./pecas/base"`); exporte `Video` (componente) e `DURACAO` (quadros); 5) grave com `escrever`, que confere a densidade; 6) conserte o que o conferir apontar; 7) renderize.',
+        '', l.texto, '', '## regras', regras(estilo, raiz).texto].join('\n');
+}
+
+const SEM_COMENTARIO = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+
+/**
+ * Conferir uma cena escrita pela IA (estático, sem render). Cobra: só importa peças do estilo, nada de Montagem/receita/plano,
+ * camadas, peças diferentes, chaves de câmera, SFX em todo corte, trilha. Devolve {ok, erros, medidas}.
+ */
+function conferirCena(estilo, codigo, raiz = RAIZ) {
+    const idx = ler(estilo, raiz);
+    const erros = [];
+    if (!idx) return { ok: false, erros: [`estilo ${estilo} sem peças`], medidas: {} };
+    const src = SEM_COMENTARIO(String(codigo || ''));
+    if (PROIBIDO.test(src)) erros.push('a cena não pode usar Montagem, receita nem plano: componha as peças direto');
+    const nomes = new Set(idx.pecas.map((p) => p.nome));
+    const usadas = new Set();
+    for (const m of src.matchAll(/import\s+(?:type\s+)?(?:\{([^}]*)\}|(\w+))\s+from\s+['"]([^'"]+)['"]/g)) {
+        const de = m[3];
+        if (/^(react|remotion)(\/|$)/.test(de)) continue;
+        if (!/(^|\/)(formas|texturas|transicoes|tipografia|camera|sons)\/|(^|\/)base$|(^|\/)paleta/.test(de) && !/\.(json|mp3|svg|png|jpg)$/.test(de)) { erros.push(`import fora das peças: "${de}"`); continue; }
+        for (const n of (m[1] || m[2] || '').split(',').map((x) => x.trim().split(/\s+as\s+/)[0]).filter(Boolean)) if (nomes.has(n)) usadas.add(n);
+    }
+    const cenas = (src.match(/<Cena\b/g) || []).length;
+    const cortes = Math.max(0, cenas - 1);
+    const efeitos = (src.match(/<Efeito\b/g) || []).length;
+    const chaves = (src.match(/\{\s*em\s*:/g) || []).length;
+    const camadasPorCena = cenas ? Math.round(([...usadas].filter((n) => !['Cena', 'Camera', 'Som'].includes(n)).length)) : 0;
+    const medidas = { cenas, cortes, efeitos, chavesCamera: chaves, pecasDiferentes: usadas.size, camadas: camadasPorCena };
+    if (!/<Camera\b/.test(src)) erros.push('falta <Camera> (a câmera nunca para)');
+    if (!/<Trilha\b/.test(src)) erros.push('falta <Trilha> (trilha forte sempre)');
+    if (cenas < 2) erros.push('use ao menos 2 <Cena> (um vídeo é uma sequência de cenas)');
+    if (usadas.size < MINIMO.pecasDiferentes) erros.push(`só ${usadas.size} peças diferentes; mínimo ${MINIMO.pecasDiferentes}`);
+    if (camadasPorCena < MINIMO.camadas) erros.push(`só ${camadasPorCena} tipos de camada; mínimo ${MINIMO.camadas} (fundo, partículas, herói, apoio)`);
+    if (chaves < MINIMO.chavesCamera) erros.push(`só ${chaves} chaves de câmera; mínimo ${MINIMO.chavesCamera}`);
+    if (efeitos < cortes * MINIMO.efeitosPorCorte) erros.push(`${efeitos} <Efeito> para ${cortes} cortes: SFX em todo corte (alvo 2 por corte)`);
+    return { ok: !erros.length, erros, medidas };
+}
+
+/** Grava a cena em <pasta>/motion/<nome>.tsx (com as peças ao lado, em motion/pecas/) e confere. */
+function escreverCena(estilo, pasta, nome, codigo, raiz = RAIZ) {
+    const slug = String(nome || '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!slug) return { ok: false, texto: 'Dê um nome à cena: … escrever <nome> --arquivo <cena.tsx>' };
+    const c = conferirCena(estilo, codigo, raiz);
+    const proibido = c.erros.some((e) => /Montagem|receita|plano|import fora/.test(e));
+    if (proibido) return { ok: false, texto: `Cena recusada:\n- ${c.erros.join('\n- ')}`, ...c };
+    const dir = path.join(pasta, 'motion');
+    fs.mkdirSync(dir, { recursive: true });
+    const arq = path.join(dir, `${slug}.tsx`);
+    fs.writeFileSync(arq, codigo);
+    const texto = c.ok ? `Cena gravada em ${arq}. Conferida: ${JSON.stringify(c.medidas)}.`
+        : `Cena gravada em ${arq}, mas NÃO passou no conferir; conserte e grave de novo:\n- ${c.erros.join('\n- ')}`;
+    return { ok: true, passou: c.ok, texto, arquivo: arq, ...c };
+}
+
+/** Copia as peças do estilo pra <dir>/pecas e escreve a entrada do render que registra a cena da IA. */
+function prepararRender(estilo, dir, arqCena, { duracao, raiz = RAIZ } = {}) {
+    fs.mkdirSync(dir, { recursive: true });
+    const alvo = path.join(dir, 'pecas');
+    fs.rmSync(alvo, { recursive: true, force: true });
+    fs.cpSync(pastaDe(estilo, raiz), alvo, { recursive: true });
+    fs.copyFileSync(arqCena, path.join(dir, 'Cena-ia.tsx'));
+    fs.writeFileSync(path.join(dir, 'entrada.tsx'), `// gerado por lib/estudio/materiais.js
+import React from 'react';
+import {Composition, registerRoot} from 'remotion';
+import {Video, DURACAO} from './Cena-ia';
+const Raiz: React.FC = () => <Composition id="Video" component={Video as React.FC} durationInFrames={${duracao || 'DURACAO'}} fps={30} width={1080} height={1920} />;
+registerRoot(Raiz);
+`);
+    return { dir, entrada: path.join(dir, 'entrada.tsx') };
+}
+
+module.exports = { RAIZ, CATEGORIAS, MINIMO, PROIBIDO, migrado, estilos, ler, validar, listar, lerPeca, regras, promptDoEstilo, conferirCena, escreverCena, prepararRender };

package/lib/estudio/regras-motion.js

@@ -0,0 +1,69 @@
+/**
+ * regras-motion.js — as regras do motion como CONTA no quadro do vídeo pronto.
+ *
+ *   "não é dica no prompt (o modelo esquece); é conta, antes do render" (a regra da casa, margem.js)
+ *
+ * O dono reclamou de "elemento sobreposto" e de "letra branca em fundo branco". A máquina AE já confere isso
+ * (maquina.js), mas Remotion e Hyperframes só mediam som e imagem parada. Aqui mora a conta que faltava, pura e
+ * sem I/O, pra conferencia.js rodar em todo vídeo, qualquer que seja o caminho:
+ *
+ *   REGRAS            as regras, com a frase curta e o limite (os de borda, rosto e encavalado vêm do conferencia-visual)
+ *   contrasteDoTexto  o texto contra o fundo atrás dele: mediana do anel em volta da caixa x tinta da caixa (WCAG)
+ *   julgarContraste   os textos lidos pelo Vision que ficam abaixo de 3:1
+ */
+'use strict';
+
+const { LIM } = require('./conferencia-visual.js');
+
+const CONTRASTE_MIN = 3;
+const REGRAS = [
+    { id: 'contraste', frase: 'texto legível contra o fundo atrás dele', limite: CONTRASTE_MIN },
+    { id: 'borda', frase: 'texto longe da beira do quadro', limite: LIM.borda },
+    { id: 'rosto', frase: 'texto fora de cima do rosto', limite: LIM.rostoMin },
+    { id: 'encavalado', frase: 'uma linha de texto não cobre a outra', limite: 0.3 },
+];
+
+// a mesma luminância de maquina-layout.js (WCAG, sRGB linear)
+const lin = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); };
+const lumi = (buf, i) => 0.2126 * lin(buf[i]) + 0.7152 * lin(buf[i + 1]) + 0.0722 * lin(buf[i + 2]);
+const vg = (n) => String(Math.round(n * 10) / 10).replace('.', ',');
+
+/** `buf` rgb24, `caixa` [x0,y0,x1,y1] em pixels do buffer → {contraste, tinta, fundo} (tinta e fundo são luminâncias 0..1), ou null. */
+function contrasteDoTexto({ buf, W, H }, caixa) {
+    if (!buf || !W || !H || !caixa) return null;
+    const x0 = Math.max(0, Math.floor(caixa[0])), y0 = Math.max(0, Math.floor(caixa[1]));
+    const x1 = Math.min(W, Math.ceil(caixa[2])), y1 = Math.min(H, Math.ceil(caixa[3]));
+    if (x1 <= x0 || y1 <= y0) return null;
+    const m = Math.max(2, Math.round((y1 - y0) * 0.06));          // o anel: ~6% da altura da caixa, cortado na borda da imagem
+    const ax0 = Math.max(0, x0 - m), ay0 = Math.max(0, y0 - m), ax1 = Math.min(W, x1 + m), ay1 = Math.min(H, y1 + m);
+    const anel = [];
+    for (let y = ay0; y < ay1; y++) for (let x = ax0; x < ax1; x++) {
+        if (x >= x0 && x < x1 && y >= y0 && y < y1) continue;
+        anel.push(lumi(buf, (y * W + x) * 3));
+    }
+    if (!anel.length) return null;
+    anel.sort((a, b) => a - b);
+    const fundo = anel[anel.length >> 1];
+    const dentro = [];
+    for (let y = y0; y < y1; y++) for (let x = x0; x < x1; x++) dentro.push(lumi(buf, (y * W + x) * 3));
+    dentro.sort((a, b) => Math.abs(a - fundo) - Math.abs(b - fundo));
+    const tinta = dentro[Math.floor((dentro.length - 1) * 0.97)];  // o percentil 97 da distância ao fundo: letra fina cobre pouco da caixa, e um pixel solto não decide
+    const claro = Math.max(tinta, fundo), escuro = Math.min(tinta, fundo);
+    return { contraste: (claro + 0.05) / (escuro + 0.05), tinta, fundo };
+}
+
+/** Os problemas de contraste de UM quadro lido pelo Vision (mesmos filtros de julgarLeitura). `px` = {buf, W, H}. */
+function julgarContraste(q, px, { cena, segundo } = {}) {
+    const out = [];
+    if (!q || !q.ok || !q.w || !q.h || !px) return out;
+    const k = px.W / q.w;                                          // do quadro do Vision pro buffer
+    for (const t of q.textos || []) {
+        if (t.conf < LIM.conf || (t.caixa[3] - t.caixa[1]) < q.h * LIM.alturaMin || String(t.texto).replace(/[^A-Za-zÀ-ÿ0-9]/g, '').length < 2) continue;
+        const c = contrasteDoTexto(px, t.caixa.map((v) => v * k));
+        if (!c || c.contraste >= CONTRASTE_MIN) continue;
+        out.push({ cena, segundo, tipo: 'contraste', texto: `texto "${t.texto}" quase some no fundo (contraste ${vg(c.contraste)}:1; o mínimo é ${CONTRASTE_MIN}:1)` });
+    }
+    return out;
+}
+
+module.exports = { REGRAS, CONTRASTE_MIN, contrasteDoTexto, julgarContraste };

package/lib/explicar.js

@@ -0,0 +1,48 @@
+/**
+ * explicar.js — o /explain: três jeitos de entender, sem jargão.
+ *
+ *   modo(rest)                  → { tipo: 'ultimo' | 'projeto' | 'termo', termo? }   (puro)
+ *   pedidoDoUltimo({ pedido, mudou, resumo })  → o pedido que vai pro modelo         (puro)
+ *   pedidoDoTermo(termo)        → o pedido de UMA linha pra palavra                  (puro)
+ *   doUltimoPedido(projectDir)  → { pedido, mudou, resumo } | null                   (lê o checkpoint e o /changes)
+ *
+ * Sem argumento: o que o último pedido mudou e por quê, em até 5 linhas. Quem escreve a explicação é o modelo; aqui só
+ * se junta o que o /changes e o ponto do /undo já sabem, pra ele não ter de adivinhar. `/explain projeto` segue o
+ * comando de fábrica (comandos/explain.md). `/explain commit` explica a palavra em uma linha.
+ */
+
+'use strict';
+
+const path = require('path');
+
+function modo(rest) {
+    const t = String(rest || '').trim();
+    if (!t) return { tipo: 'ultimo' };
+    if (/^(projeto|project)$/i.test(t)) return { tipo: 'projeto' };
+    return { tipo: 'termo', termo: t.slice(0, 80) };
+}
+
+function pedidoDoUltimo({ pedido, mudou = [], resumo = '' } = {}) {
+    const arquivos = mudou.slice(0, 15).map((m) => `- ${m.arquivo}${m.acao ? ` (${m.acao})` : ''}`).join('\n');
+    return `Explique para quem nunca programou o que o meu ÚLTIMO pedido mudou neste projeto e por que o PrimoCode fez isso.\n\n`
+        + `O último pedido foi: "${String(pedido || '').slice(0, 200)}"\n`
+        + (resumo ? `O que mudou, em números: ${resumo}\n` : '')
+        + (arquivos ? `Arquivos:\n${arquivos}\n` : '')
+        + `\nLeia os arquivos antes de falar, não chute. Responda em NO MÁXIMO 5 linhas curtas, sem jargão, uma ideia por linha. `
+        + `Não mude arquivo nenhum e não rode comando que mude coisa: é só uma explicação.`;
+}
+
+function pedidoDoTermo(termo) {
+    return `Explique em UMA linha, para quem nunca programou, o que quer dizer "${termo}" (se for uma palavra de programação). `
+        + `Use uma comparação do dia a dia. Sem jargão, sem lista, sem mexer em arquivo nenhum.`;
+}
+
+function doUltimoPedido(projectDir, { checkpoint = require('./checkpoint.js'), mudou = require('./mudou.js') } = {}) {
+    const cp = checkpoint.lista(projectDir)[0];
+    const m = mudou.medir(projectDir);
+    if (!cp && !m.arquivos.length) return null;
+    const arquivos = cp ? (cp.mudou || []).map((x) => ({ arquivo: path.relative(projectDir, x.caminho), acao: x.acao })) : m.arquivos;
+    return { pedido: cp ? cp.pedido : '(o que está sem salvar no projeto)', mudou: arquivos, resumo: m.frase };
+}
+
+module.exports = { modo, pedidoDoUltimo, pedidoDoTermo, doUltimoPedido };

package/lib/exportar-conversa.js

@@ -0,0 +1,49 @@
+/**
+ * exportar-conversa.js — o /exportar: a conversa vira um .md pra guardar ou mandar pra alguém.
+ *
+ *   mascarar(texto)                              → o texto sem chave nem senha        (puro)
+ *   montarMd(historico, { projeto, quando })     → o .md                               (puro)
+ *   gravar(historico, { projeto, quando, raiz }) → caminho do arquivo
+ *
+ * O OpenCode tirou o /share em 15/10/2026 (rohitai.com [VERIFICAR]) e quem usava pra mostrar a conversa ficou sem.
+ * Aqui é local, sem link público: um arquivo em ~/primocode/conversas/, com chave e senha trocadas por
+ * "[chave escondida]" (os mesmos padrões da varredura do "pronto", lib/chave-exposta.js).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { TIPOS } = require('./chave-exposta.js');
+
+function mascarar(texto) {
+    let t = String(texto == null ? '' : texto);
+    for (const [, re] of TIPOS) t = t.replace(new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g'), '[chave escondida]');
+    return t;
+}
+
+const QUEM = { user: 'Você', assistant: 'PrimoCode' };
+
+function montarMd(historico, { projeto = '', quando = new Date() } = {}) {
+    const data = quando.toLocaleString('pt-BR', { dateStyle: 'long', timeStyle: 'short' });
+    const linhas = [`# Conversa${projeto ? ` em ${projeto}` : ''}`, '', `_${data} · exportada pelo PrimoCode_`, ''];
+    for (const m of historico || []) {
+        if (!QUEM[m.role]) continue;   // ferramenta e sistema ficam de fora: é a conversa, não o log
+        const texto = typeof m.content === 'string' ? m.content : JSON.stringify(m.content || '');
+        linhas.push(`## ${QUEM[m.role]}`, '', mascarar(texto).trim(), '');
+    }
+    return linhas.join('\n');
+}
+
+function gravar(historico, { projeto = '', quando = new Date(), raiz = path.join(os.homedir(), 'primocode', 'conversas') } = {}) {
+    const p2 = (n) => String(n).padStart(2, '0');
+    const carimbo = `${quando.getFullYear()}-${p2(quando.getMonth() + 1)}-${p2(quando.getDate())}-${p2(quando.getHours())}${p2(quando.getMinutes())}`;
+    const nome = `${(projeto || 'conversa').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'conversa'}-${carimbo}.md`;
+    fs.mkdirSync(raiz, { recursive: true });
+    const arq = path.join(raiz, nome);
+    fs.writeFileSync(arq, montarMd(historico, { projeto, quando }));
+    return arq;
+}
+
+module.exports = { mascarar, montarMd, gravar };