primocode 10.19.0 → 11.1.0

package/lib/plugin/kits.js

@@ -0,0 +1,585 @@
+/**
+ * kits.js — os estilos de motion. Cada estilo é um conjunto de PEÇAS SOLTAS (materiais/<estilo>/): formas, texturas,
+ * transições, tipografia, câmera e sons, mais 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
+ * (camadas, peças, chaves de câmera, SFX por corte e movimento por segundo). O kit (kits/<slug>/) guarda só a
+ * identidade do estilo na galeria: SKILL.md (nome, quando serve) e capa.jpg.
+ *
+ * ── QUEM DECIDE ──────────────────────────────────────────────────────────
+ * A IA. O menu (uma linha por estilo: slug, nome, quando) vai na frente do pedido e ela escolhe; o regex de
+ * "parece motion" só decide se o menu vai inteiro ou numa linha só (economia de token), nunca qual estilo.
+ *
+ * ── O CAMINHO ────────────────────────────────────────────────────────────
+ *   primocode kit menu         no primeiro motion abre a tela de estilos e devolve o menu com o estilo escolhido lá
+ *   primocode kit ver <slug>   as peças e as regras do estilo (o mesmo que `pecas <slug>`)
+ *   primocode kit pecas <slug> [ver <peça> | regras | escrever <nome> --arquivo <cena.tsx> | conferir <cena.tsx> | renderizar <nome>]
+ *   primocode kit referencia   abre a tela de referências (a do /taste referencias) e devolve o que ela mediu
+ *   primocode kit criar …      estilo novo: copia as peças de um estilo base pra ~/.primocode/materiais/<slug>
+ *   primocode kit preview <s>  o preview.mp4 do estilo, se existir; senão a capa
+ *   primocode kit galeria      a tela de estilos (capa + preview + nome); a escolha volta e vira o padrão
+ *
+ * O run_shell roda `primocode kit …` aqui dentro (lib/tool/tools.js), não num filho:
+ * a tela de estilos no app sai pela linha de protocolo do stderr DESTE processo.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn, spawnSync } = require('child_process');
+
+const RAIZ = path.join(__dirname, '..', '..', 'kits');
+const MATERIAIS = require('./estudio/materiais.js');
+const ESTUDIO = path.join(RAIZ, 'estudio');
+const FAMILIAS = ['SaaS e tecnologia', 'Tipografia em movimento', 'Retrô', 'Feito à mão', '3D e abstrato', 'Redes sociais', 'Marca e evento'];
+const REGRAS = ['tipografia.md', 'cor.md', 'movimento.md', 'som.md', 'ritmo.md', 'area-segura.md'];
+const MIDIA = /\.(png|jpe?g|webp|gif|svg|mp4|webm|mov|mp3|wav|m4a)$/i;
+const FPS = 30;
+
+const casa = (home = os.homedir()) => path.join(home, '.primocode', 'kits');
+const baseEstudio = (home = os.homedir()) => path.join(home, '.primocode', 'kits-estudio');
+const usuarioMateriais = (home = os.homedir()) => path.join(home, '.primocode', 'materiais');
+const semAcento = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+const slugar = (s) => semAcento(s).replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+
+// ── o turno: um por pedido da pessoa ─────────────────────────────────────
+
+let turnoLocal = `${process.pid}-${Date.now().toString(36)}`;
+/** Chamado no começo de cada pedido da pessoa (lib/session/runner/act.js). Vai no env: o `primocode kit` num filho herda. */
+function novoTurno() {
+    turnoLocal = crypto.randomBytes(6).toString('hex');
+    process.env.PRIMOCODE_TURNO = turnoLocal;
+    return turnoLocal;
+}
+const turnoAtual = () => process.env.PRIMOCODE_TURNO || turnoLocal;
+const autoConfirma = (env = process.env) => env.PRIMOCODE_KIT_CONFIRMAR === '1';
+
+// ── ler os kits ──────────────────────────────────────────────────────────
+
+/** frontmatter simples: `chave: valor` e listas com `- item` (o mesmo leitor do repo dos kits). */
+function lerFrontmatter(texto) {
+    const m = String(texto || '').replace(/\r\n/g, '\n').match(/^---\n([\s\S]*?)\n---/);
+    if (!m) return null;
+    const out = {}; let lista = null;
+    for (const linha of m[1].split('\n')) {
+        const item = linha.match(/^\s+-\s+(.*)$/);
+        if (item && lista) { out[lista].push(item[1].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '')); continue; }
+        const kv = linha.match(/^([a-z_]+):\s*(.*)$/);
+        if (!kv) continue;
+        const v = kv[2].replace(/\s+#.*$/, '');
+        if (v === '') { out[kv[1]] = []; lista = kv[1]; } else { out[kv[1]] = v.replace(/^["']|["']$/g, ''); lista = null; }
+    }
+    return out;
+}
+
+function lerKit(pasta, origem, extra = {}) {
+    let fm = null;
+    try { fm = lerFrontmatter(fs.readFileSync(path.join(pasta, 'SKILL.md'), 'utf8')); } catch { return null; }
+    if (!fm) return null;
+    const slug = fm.slug || path.basename(pasta);
+    const capa = path.join(pasta, 'capa.jpg');
+    return {
+        slug, nome: extra.nome || fm.nome || slug, familia: fm.familia || extra.familia || '',
+        descricao: fm.descricao || extra.descricao || '',
+        quando: Array.isArray(fm.quando) ? fm.quando : [], nao_serve: Array.isArray(fm.nao_serve) ? fm.nao_serve : [],
+        versao: Number(fm.versao) || 1, pasta, origem, capa: fs.existsSync(capa) ? capa : null,
+        ...(fm.base ? { base: fm.base } : {}),
+    };
+}
+
+/** Os kits do pacote (kits/manifest.json) e os que a pessoa criou (~/.primocode/kits/<slug>). */
+function listar({ home, raiz = RAIZ } = {}) {
+    const out = [];
+    let manifesto = [];
+    try { manifesto = JSON.parse(fs.readFileSync(path.join(raiz, 'manifest.json'), 'utf8')); } catch { /* pacote sem kits */ }
+    for (const m of manifesto) {
+        if (!m || !m.slug || m.status === 'rascunho') continue;
+        const k = lerKit(path.join(raiz, m.slug), 'pacote', m);
+        if (k) out.push(k);
+    }
+    const dela = casa(home);
+    let pastas = [];
+    try { pastas = fs.readdirSync(dela, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'previews'); } catch { /* nenhum criado */ }
+    for (const d of pastas) {
+        const k = lerKit(path.join(dela, d.name), 'seu');
+        if (k && !out.some((x) => x.slug === k.slug)) out.push(k);
+    }
+    return out;
+}
+
+/** O kit pelo slug (ou começo do slug, ou nome sem acento). */
+function achar(nome, op = {}) {
+    const alvo = slugar(nome);
+    if (!alvo) return null;
+    const todos = op.todos || listar(op);
+    return todos.find((k) => k.slug === alvo) || todos.find((k) => slugar(k.nome) === alvo)
+        || todos.find((k) => k.slug.startsWith(alvo)) || null;
+}
+
+// ── o menu pra IA ────────────────────────────────────────────────────────
+
+const linhaDoMenu = (k) => `- ${k.slug} · ${k.nome.split(' · ')[0]}${k.origem === 'seu' ? ' (seu)' : ''}${MATERIAIS.migrado(k.slug) ? ' [peças soltas]' : ''}: ${(k.quando.length ? k.quando.slice(0, 2) : [k.descricao]).join('; ').replace(/\s+/g, ' ').replace(/"/g, '')}`.slice(0, 92);
+
+/** "estilo apple", "estilo papel recortado": a palavra depois de "estilo" que é o slug ou o nome de um kit. Só sugere. */
+function kitCitado(texto, todos) {
+    const m = semAcento(texto).match(/estilos?\s+(?:de\s+|do\s+|da\s+)?([a-z0-9-]+(?:\s+[a-z0-9-]+)?)/);
+    if (!m) return null;
+    for (const cand of [m[1], m[1].split(/\s+/)[0]]) {
+        const s = slugar(cand);
+        const k = todos.find((x) => x.slug === s) || todos.find((x) => slugar(x.nome.split(' · ')[0]) === s) || todos.find((x) => x.slug.startsWith(s + '-'));
+        if (k) return { k, palavra: cand };
+    }
+    return null;
+}
+
+/** O menu compacto: uma linha por kit. É a IA que escolhe por ele. */
+function menuParaIA(op = {}) {
+    const todos = op.todos || listar(op);
+    if (!todos.length) return '';
+    return todos.map(linhaDoMenu).join('\n');
+}
+
+/* Só SUGERE que o pedido é de motion, pra mandar o menu inteiro em vez de uma linha. Não escolhe kit nem caminho. */
+const PARECE_MOTION = /(^|[^a-z])(motion|motions|animad[oa]s?|animacao|animacoes|vinheta|reels?|teaser|intro|explainer|lancamento|video|videos|estilo apple)([^a-z]|$)/;
+const pareceMotion = (texto) => PARECE_MOTION.test(semAcento(texto));
+
+const CAMINHO = [
+    '1) run_shell "primocode kit menu": no primeiro motion abre a tela de estilos e devolve o estilo que a pessoa escolheu lá.',
+    '2) Escolha o estilo que casa com o pedido e o gosto (você decide; o pedido explícito da pessoa ganha).',
+    '3) "primocode kit pecas <slug>": a lista de peças (formas, texturas, transições, tipografia, câmera, sons). "… regras": a identidade e a densidade mínima. "… ver <peça>": o código e os params.',
+    '4) Escreva o roteiro (o que o vídeo diz, cena a cena) e a cena NOVA em TSX, do zero, com as peças e o conteúdo DA PESSOA (texto, produto, logo, cores): fundo vivo + partículas, câmera com 4+ chaves, CorteImpacto e 2 SFX em cada corte, trilha.',
+    '5) "primocode kit pecas <slug> escrever <nome> --arquivo cena.tsx": grava e confere (camadas, peças, chaves, SFX por corte, movimento por segundo). Conserte o que ele apontar e grave de novo.',
+    '6) "primocode kit pecas <slug> renderizar <nome>": renderiza e devolve os quadros; confira.',
+    'Ela mandou ou citou um vídeo de referência? "primocode kit referencia" abre a tela de referências.',
+    'O estilo pedido não existe? "primocode kit criar --nome \\"<nome>\\" --descricao \\"<como é>\\" --base <slug mais parecido> [--ref <vídeo>]" e use o estilo novo.',
+    'Nenhum estilo serve e ela não quer estilo novo: o estudio_motion continua valendo.',
+].join('\n');
+
+/**
+ * O que vai na frente do pedido (lib/session/runner/act.js). Pedido com cara de motion: o caminho + o menu inteiro;
+ * o resto: uma linha que lembra que os kits existem. Nos dois casos quem decide é a IA.
+ */
+function cabecaDoPedido(texto, op = {}) {
+    const todos = op.todos || listar(op);
+    if (!todos.length) return '';
+    if (!pareceMotion(texto)) {
+        return `[estilos de motion] ${todos.length} estilos de motion prontos (${todos.slice(0, 6).map((k) => k.nome.split(' · ')[0]).join(', ')}…). Se o pedido for um vídeo de motion, rode "primocode kit menu"; você decide.`;
+    }
+    const citado = kitCitado(texto, todos);
+    const dica = citado ? `\nO pedido cita o estilo "${citado.palavra}": é o kit ${citado.k.slug} (${citado.k.nome}). Pedido de motion com estilo vai pelo caminho abaixo (peças soltas), não pelo estudio_motion.` : '';
+    return `[estilos de motion: você decide] Há ${todos.length} kits de estilo (cada um é um conjunto de peças Remotion soltas, com regras em números e sons). Para um motion:\n${CAMINHO}${dica}\n\nOs kits:\n${menuParaIA({ todos })}`;
+}
+
+// ── a skill de um kit ────────────────────────────────────────────────────
+
+function lerSe(arq) { try { return fs.readFileSync(arq, 'utf8'); } catch { return ''; } }
+function depsDoEstudio() { try { return JSON.stringify(JSON.parse(fs.readFileSync(path.join(ESTUDIO, 'package.json'), 'utf8')).dependencies); } catch { return ''; } }
+
+/** O node_modules com o Remotion dos kits. PRIMOCODE_KITS_MODULOS aponta um pronto (dev/teste). */
+function garantirEstudio({ home, aoFalar = () => {}, env = process.env } = {}) {
+    if (env.PRIMOCODE_KITS_MODULOS && fs.existsSync(path.join(env.PRIMOCODE_KITS_MODULOS, 'remotion'))) return { ok: true, modulos: env.PRIMOCODE_KITS_MODULOS };
+    const base = baseEstudio(home);
+    const modulos = path.join(base, 'node_modules');
+    const deps = depsDoEstudio();
+    if (fs.existsSync(path.join(modulos, '@remotion', 'renderer')) && lerSe(path.join(base, 'deps.json')) === deps) return { ok: true, modulos };
+    fs.mkdirSync(base, { recursive: true });
+    fs.copyFileSync(path.join(ESTUDIO, 'package.json'), path.join(base, 'package.json'));
+    aoFalar('instalando o estúdio dos kits (uma vez só, alguns minutos)');
+    let r = null;
+    for (let t = 0; t < 2; t++) {
+        r = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], { cwd: base, encoding: 'utf8', shell: process.platform === 'win32', timeout: 15 * 60000 });
+        if (r.status === 0) break;
+    }
+    if (!r || r.status !== 0) return { ok: false, error: `não consegui instalar o Remotion dos kits: ${String((r && (r.stderr || r.error)) || '').slice(-300)}` };
+    fs.writeFileSync(path.join(base, 'deps.json'), deps);
+    return { ok: true, modulos };
+}
+
+// ── montar a pasta do vídeo e renderizar ─────────────────────────────────
+
+function entradaDoPreview() {
+    return `// gerado por lib/plugin/kits.js — o preview do kit
+import React from 'react';
+import {Composition, registerRoot} from 'remotion';
+import {preview} from './kit/preview';
+const Raiz: React.FC = () => <Composition id="Video" component={preview.Componente as React.FC} durationInFrames={preview.duracaoEmQuadros} fps={${FPS}} width={1080} height={1920} />;
+registerRoot(Raiz);
+`;
+}
+
+function ligarModulos(dir, modulos) {
+    const alvo = path.join(dir, 'node_modules');
+    try { fs.rmSync(alvo, { recursive: true, force: true }); } catch { /* não havia */ }
+    fs.symlinkSync(modulos, alvo, 'dir');
+}
+
+function rodarRender(dir, saida, { escala = 1, quadros, aoFalar = () => {}, minutos = 30 } = {}) {
+    return new Promise((resolve) => {
+        fs.copyFileSync(path.join(ESTUDIO, 'render.mjs'), path.join(dir, 'render.mjs'));
+        const args = [path.join(dir, 'render.mjs'), path.join(dir, 'entrada.tsx'), saida, '--escala', String(escala)];
+        if (quadros && quadros.length) args.push('--quadros', quadros.join(','));
+        const p = spawn(process.execPath, args, { cwd: dir });
+        let fim = null, erro = '', resto = '';
+        const rel = setTimeout(() => { try { p.kill(); } catch { /* já foi */ } }, minutos * 60000);
+        p.stdout.on('data', (d) => {
+            resto += d.toString();
+            const linhas = resto.split('\n'); resto = linhas.pop();
+            for (const l of linhas) {
+                let o; try { o = JSON.parse(l); } catch { continue; }
+                if (o.passo) aoFalar(o.passo);
+                else if (o.progresso != null) aoFalar(`renderizando ${o.progresso}%`);
+                else if ('ok' in o) fim = o;
+            }
+        });
+        p.stderr.on('data', (d) => { erro = (erro + d.toString()).slice(-3000); });
+        p.on('close', () => {
+            clearTimeout(rel);
+            if (resto.trim()) { try { const o = JSON.parse(resto); if ('ok' in o) fim = o; } catch { /* resto não é JSON */ } }
+            resolve(fim || { ok: false, error: `o render parou sem dizer por quê: ${erro.split('\n').filter(Boolean).slice(-4).join(' | ')}` });
+        });
+        p.on('error', (e) => { clearTimeout(rel); resolve({ ok: false, error: e.message }); });
+    });
+}
+
+async function cmdMenu(op) {
+    const { home } = op;
+    const T = require('./estudio/kits-tela.js');
+    // no primeiro motion abre a tela de estilos (os kits no carrossel da tela de gosto); a escolha volta aqui
+    let tela = null;
+    try { tela = await (op.abrirKits || ((o) => T.primeiroMotion(o, { env: op.env || process.env })))({ home }); } catch { /* sem tela, segue */ }
+    const G = require('./estudio/gosto.js');
+    const g = G.ler(home);
+    const todos = listar({ home });
+    const linhas = [];
+    const escolha = T.lerEscolha(home);
+    const kEsc = escolha && escolha.slug ? achar(escolha.slug, { home, todos }) : null;
+    if (tela && tela.ok && kEsc) linhas.push(`A pessoa acabou de escolher na tela de estilos: ${kEsc.nome} (${kEsc.slug}). Use este kit (só troque se o pedido dela disser outro estilo com todas as letras).`);
+    else if (kEsc) linhas.push(`O estilo que a pessoa escolheu na tela de estilos: ${kEsc.nome} (${kEsc.slug}). É o padrão dela; o pedido explícito ganha.`);
+    else if (tela && tela.motivo === 'pulou') linhas.push('Na tela de estilos a pessoa deixou você escolher.');
+    else if (tela && tela.motivo && !/nao_abre|ja_escolheu/.test(tela.motivo)) linhas.push(`A tela de estilos fechou sem escolha (${tela.motivo}).`);
+    const resumo = g && !g.pulou ? G.resumo(g) : '';
+    if (resumo) linhas.push(`O gosto de motion dela: ${resumo}`);
+    linhas.push('', `Os ${todos.length} kits de estilo (escolha um; o pedido explícito ganha):`, menuParaIA({ todos }), '',
+        'Depois: primocode kit ver <slug>. Nenhum serve? primocode kit criar --nome … --descricao … --base <slug>.');
+    return { ok: true, texto: linhas.join('\n'), escolha: kEsc ? kEsc.slug : null };
+}
+
+function cmdVer(slug, op) {
+    const k = achar(slug, op);
+    if (!k) return naoExiste(slug, op);
+    if (!MATERIAIS.migrado(k.slug)) return { ok: false, texto: `O estilo ${k.slug} não tem peças soltas (materiais/${k.slug}/pecas.json). Crie de novo com: primocode kit criar --nome "…" --base <estilo>` };
+    return { ok: true, texto: MATERIAIS.promptDoEstilo(k.slug) };
+}
+
+function naoExiste(slug, op) {
+    const todos = listar(op);
+    const s = semAcento(slug).split(/[^a-z0-9]+/).filter((x) => x.length > 2);
+    const parecidos = todos.filter((k) => s.some((p) => semAcento(`${k.slug} ${k.nome} ${k.descricao}`).includes(p))).slice(0, 5).map((k) => k.slug);
+    return { ok: false, texto: `Não existe o estilo "${slug}".${parecidos.length ? ` Parecidos: ${parecidos.join(', ')}.` : ''} `
+        + `Se nenhum serve, crie: primocode kit criar --nome "${slug}" --descricao "<como é o estilo>" --base <slug mais parecido> [--ref <vídeo>]` };
+}
+
+async function cmdReferencia(a, op) {
+    const G = require('./estudio/gosto.js');
+    const desde = Date.now() - 1000;
+    const r = await (op.abrirReferencias || ((o) => G.abrirOndeDer(o)))({ inicio: 'referencias', home: op.home });
+    if (!r || !r.ok) return { ok: false, texto: `A tela de referências fechou sem salvar (${(r && r.motivo) || 'sem tela'}). Siga com o pedido ou peça o vídeo de novo.` };
+    const pastaRef = path.join(op.home || os.homedir(), '.primocode', 'gosto-referencias');
+    let videos = [];
+    try { videos = fs.readdirSync(pastaRef).map((f) => path.join(pastaRef, f)).filter((f) => !path.basename(f).startsWith('.') && fs.statSync(f).mtimeMs >= desde); } catch { /* nenhum */ }
+    const refs = (r.gosto && r.gosto.referencias) || [];
+    const linhas = ['As referências que a pessoa trouxe (medidas na tela):'];
+    for (const x of refs.slice(-5)) linhas.push(`- ${x.nome}: ${G.fraseDeUmaReferencia(x.medida)}${x.descricao && x.descricao.frases ? ' · ' + x.descricao.frases.join('; ') : ''}`);
+    if (videos.length) linhas.push('', `Os vídeos: ${videos.join(', ')}`);
+    // os kits mais perto do vídeo (paleta da capa + ritmo da receita): sugestão, quem escolhe é a IA
+    const ultima = refs.length ? refs[refs.length - 1].medida : null;
+    let perto = [];
+    try { perto = require('./kits-parecidos.js').parecidos(ultima, listar(op), { home: op.home }); } catch { /* sem ffmpeg */ }
+    if (perto.length) linhas.push('', 'Os kits mais parecidos com o vídeo (sugestão; você decide):', ...perto.map((p, i) => `${i + 1}. ${p.k.slug} · ${p.k.nome.split(' · ')[0]}: ${p.porque}`));
+    linhas.push('', 'Escolha o kit mais próximo (primocode kit menu) ou, se nenhum chega perto, crie um a partir do vídeo: primocode kit criar --nome "<nome>" --descricao "<como é>" --base <slug> --ref <vídeo>');
+    return { ok: true, texto: linhas.join('\n'), videos };
+}
+
+/** Estilo novo: copia as peças de um estilo base pra ~/.primocode/materiais/<slug> e escreve o SKILL.md em ~/.primocode/kits/<slug>. */
+function cmdCriar(a, op) {
+    const nome = String(a.nome || '').trim();
+    if (!nome) return { ok: false, texto: 'Falta --nome "<nome do estilo>".' };
+    const slug = slugar(a.slug || nome);
+    const todos = listar(op);
+    if (todos.some((k) => k.slug === slug)) return { ok: false, texto: `O estilo ${slug} já existe: primocode kit ver ${slug}` };
+    const base = achar(a.base || 'minimal', { todos }) || todos[0];
+    if (!base || !MATERIAIS.migrado(base.slug)) return { ok: false, texto: 'Não há estilo de peças soltas pra servir de base neste pacote.' };
+    const descricao = String(a.descricao || '').replace(/\s+/g, ' ').trim() || `estilo ${nome}`;
+    const destino = path.join(casa(op.home), slug);
+    const pecas = path.join(usuarioMateriais(op.home), slug);
+    fs.mkdirSync(destino, { recursive: true });
+    fs.mkdirSync(path.dirname(pecas), { recursive: true });
+    fs.cpSync(path.join(MATERIAIS.RAIZ, base.slug), pecas, { recursive: true, filter: (src) => !/[\\/]referencia([\\/]|$)/.test(src) });
+    const idx = JSON.parse(fs.readFileSync(path.join(pecas, 'pecas.json'), 'utf8'));
+    idx.estilo = slug; idx.nome = nome; idx.base = base.slug;
+    fs.writeFileSync(path.join(pecas, 'pecas.json'), JSON.stringify(idx, null, 2) + '\n');
+    const quando = String(a.quando || '').split(/\s*;\s*/).filter(Boolean);
+    while (quando.length < 3) quando.push([`vídeo no estilo ${nome}`, descricao, `motion ${nome.toLowerCase()}`][quando.length]);
+    const familia = FAMILIAS.includes(a.familia) ? a.familia : base.familia;
+    const fm = ['---', `slug: ${slug}`, `nome: ${nome}`, `descricao: ${descricao}`, `familia: ${familia}`, 'versao: 1', `base: ${base.slug}`, 'quando:', ...quando.map((q) => `  - "${q.replace(/"/g, "'")}"`), '---', ''].join('\n');
+    fs.writeFileSync(path.join(destino, 'SKILL.md'), fm + `> Estilo criado pelo PrimoCode em ${new Date().toISOString().slice(0, 10)} a partir de **${base.nome}** (${base.slug}), pro pedido: "${descricao}".\n`);
+    const linhas = [`Criei o estilo ${nome} (${slug}): peças em ${pecas}, a partir de ${base.nome} (${base.slug}).`];
+    if (a.ref) {
+        const mc = require('./motioncraft.js').CLI;
+        const dirRef = path.join(pecas, 'referencia');
+        const rodar = (...args) => spawnSync(process.execPath, [mc, 'ref', ...args, '--dir', dirRef], { encoding: 'utf8', timeout: 5 * 60000 });
+        const g = rodar('get', path.resolve(op.projectDir || process.cwd(), String(a.ref)));
+        const rep = g.status === 0 ? rodar('report') : g;
+        if (rep.status === 0) {
+            linhas.push(`Analisei a referência (MotionCraft ref): ${path.join(dirRef, 'ref_report.md')} — cortes, BPM, movimento por segundo, paleta (palette.png) e folhas de contato (sheet_*.jpg).`);
+            fs.appendFileSync(path.join(pecas, 'regras.md'), `\n## Referência\n\nVídeo: ${a.ref}\n\n${lerSe(path.join(dirRef, 'ref_report.md'))}\n`);
+        } else linhas.push(`Não consegui analisar a referência: ${String(rep.stderr || rep.stdout || rep.error || '').split('\n').filter(Boolean).slice(-2).join(' ')}`);
+    }
+    const erros = MATERIAIS.validar(slug);
+    if (erros.length) linhas.push(`Formato: ${erros.length} pendência(s): ${erros.join('; ')}`);
+    linhas.push('', 'Agora faça o estilo virar o pedido (você edita os arquivos do estilo):',
+        `1) ${path.join(pecas, 'regras.md')} e cores/paleta.json: troque pelos números do estilo pedido${a.ref ? ' (abra palette.png e as folhas de contato em referencia/)' : ''}.`,
+        '2) base.ts: as cores, a fonte e as curvas (os tokens). Fonte nova só OFL/Apache, em fontes/.',
+        '3) Peças que não servem: edite o código no lugar, ou acrescente outras e registre em pecas.json (primocode kit checar <slug> confere).',
+        `Depois use como os outros: primocode kit pecas ${slug}.`);
+    return { ok: true, texto: linhas.join('\n'), slug, pasta: destino, pecas };
+}
+
+async function cmdPreview(slug, op) {
+    const k = achar(slug, op);
+    if (!k) return naoExiste(slug, op);
+    const pronto = previewPronto(k, op);
+    if (pronto) return { ok: true, texto: `Preview: ${pronto}`, video: pronto };
+    if (k.capa) return { ok: true, texto: `Capa: ${k.capa} (o estilo ainda não tem preview.mp4; as cenas saem de: primocode kit pecas ${k.slug})`, video: k.capa };
+    return { ok: false, texto: `O estilo ${k.slug} não tem capa nem preview.` };
+}
+
+/** O preview do estilo: o vídeo de referência (materiais/<estilo>/referencia/referencia.mp4), o preview.mp4 da pasta do kit ou o renderizado aqui. */
+function previewPronto(k, op = {}) {
+    for (const f of [path.join(MATERIAIS.pastaDe(k.slug), 'referencia', 'referencia.mp4'), path.join(k.pasta, 'preview.mp4'), path.join(casa(op.home), 'previews', `${k.slug}.mp4`)]) if (fs.existsSync(f)) return f;
+    return null;
+}
+
+// ── a galeria (/styles) ──────────────────────────────────────────────────
+
+const esc = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const urlDe = (arq) => 'file://' + encodeURI(arq.split(path.sep).join('/'));
+
+/** A galeria em HTML: capa, preview (o local, ou PRIMOCODE_KITS_PREVIEW_URL/<slug>/preview.mp4) e nome de cada kit. */
+function galeriaHtml(op = {}) {
+    const env = op.env || process.env;
+    const remoto = String(env.PRIMOCODE_KITS_PREVIEW_URL || '').replace(/\/+$/, '');
+    const todos = listar(op);
+    const grupos = [...new Set([...FAMILIAS, ...todos.map((k) => k.familia)])].filter((f) => todos.some((k) => k.familia === f));
+    const cartao = (k) => {
+        const local = previewPronto(k, op);
+        const video = local ? urlDe(local) : (remoto && k.origem === 'pacote' ? `${remoto}/${k.slug}/preview.mp4` : '');
+        return `<figure class="kit" data-slug="${esc(k.slug)}">
+  <div class="tela">${k.capa ? `<img src="${esc(urlDe(k.capa))}" alt="" loading="lazy">` : '<div class="sem"></div>'}${video ? `<video muted loop playsinline preload="none" data-src="${esc(video)}"></video>` : ''}</div>
+  <figcaption><b>${esc(k.nome)}</b><span>${esc(k.descricao)}</span><code>/styles ${esc(k.slug)}</code></figcaption>
+</figure>`;
+    };
+    return `<!doctype html><html lang="pt-BR"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Estilos de motion</title>
+<style>
+:root{--bg:#0c0b0f;--surface:#16141b;--line:#2e2a37;--fg:#efeaf3;--muted:#9a93a6;--accent:#ff4d7d;color-scheme:dark}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.5 "Instrument Sans","Helvetica Neue",system-ui,sans-serif}
+.wrap{max-width:1480px;margin:0 auto;padding:28px 16px 64px}
+h1{font:800 clamp(30px,5vw,54px)/1 "Bricolage Grotesque","Avenir Next",system-ui,sans-serif;letter-spacing:-.03em;margin:0 0 6px}
+.sub{color:var(--muted);margin:0 0 28px}.sub b{color:var(--accent)}
+h2{font:700 13px/1 ui-monospace,"SF Mono",Menlo,monospace;text-transform:uppercase;letter-spacing:.12em;color:var(--muted);margin:36px 0 14px}
+.grade{display:grid;grid-template-columns:repeat(auto-fill,minmax(170px,1fr));gap:16px}
+.kit{margin:0;background:var(--surface);border:1px solid var(--line);border-radius:14px;overflow:hidden;transition:transform .25s cubic-bezier(.2,.8,.2,1),border-color .25s}
+.kit:hover{transform:translateY(-4px) rotate(-.4deg);border-color:var(--accent)}
+.tela{position:relative;aspect-ratio:9/16;background:#000}.tela img,.tela video{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
+.tela video{opacity:0;transition:opacity .2s}.kit.toca video{opacity:1}.sem{position:absolute;inset:0;background:repeating-linear-gradient(45deg,#1b1922 0 10px,#15131a 10px 20px)}
+figcaption{padding:10px 12px 12px;display:grid;gap:4px}figcaption b{font-weight:600}figcaption span{color:var(--muted);font-size:12.5px;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+code{font:12px ui-monospace,"SF Mono",Menlo,monospace;color:var(--accent)}
+</style></head><body><div class="wrap">
+<h1>Estilos de motion</h1><p class="sub"><b>${todos.length}</b> kits. Passe o mouse pra ver mexendo. No pedido, é só dizer o estilo ("estilo apple") ou deixar o PrimoCode escolher.</p>
+${grupos.map((f) => `<h2>${esc(f || 'Outros')}</h2><div class="grade">${todos.filter((k) => k.familia === f).map(cartao).join('\n')}</div>`).join('\n')}
+</div><script>
+document.querySelectorAll('.kit').forEach(function (k) {
+  var v = k.querySelector('video'); if (!v) return;
+  k.addEventListener('mouseenter', function () { if (!v.src) v.src = v.dataset.src; k.classList.add('toca'); v.play().catch(function () {}); });
+  k.addEventListener('mouseleave', function () { k.classList.remove('toca'); v.pause(); });
+});
+</script></body></html>`;
+}
+
+/** A tela de estilos (lib/plugin/estudio/kits-tela.js): capa, preview com o mouse em cima, nome; a escolha volta. */
+async function cmdGaleria(op) {
+    const T = require('./estudio/kits-tela.js');
+    const r = await (op.abrirKits || ((o) => T.abrirOndeDer(o, { env: op.env || process.env })))({ home: op.home, inicial: op.inicial });
+    if (r && r.ok) return { ok: true, texto: `Estilo escolhido: ${r.kit ? r.kit.nome : r.slug} (${r.slug}). O próximo motion sai nele.`, slug: r.slug };
+    const motivo = { pulou: 'você deixou o PrimoCode escolher pelo pedido', fechou: 'a tela fechou sem escolha', tempo: 'acabou o tempo (10 min)', sem_tela: 'não consegui abrir a tela' }[r && r.motivo] || (r && r.motivo) || 'sem escolha';
+    return { ok: r && r.motivo === 'pulou', texto: `Tela de estilos: ${motivo}.` };
+}
+
+/** O texto do /styles: os kits por família. */
+function listaParaPessoa(op = {}) {
+    const todos = listar(op);
+    if (!todos.length) return ['Este PrimoCode não tem kits de estilo.'];
+    const linhas = [];
+    for (const f of [...new Set(todos.map((k) => k.familia))]) {
+        linhas.push(f || 'Outros');
+        for (const k of todos.filter((x) => x.familia === f)) linhas.push(`  ${k.slug.padEnd(20)} ${k.nome}${k.origem === 'seu' ? '  (seu)' : ''}`);
+    }
+    return linhas;
+}
+
+// ── a linha de comando ───────────────────────────────────────────────────
+
+/** Separa a linha como o shell faria: aspas simples e duplas, contrabarra. null se tiver operador de shell fora de aspas. */
+function palavras(linha) {
+    const out = []; let atual = null, aspas = null;
+    const s = String(linha || '');
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (aspas) {
+            if (ch === aspas) { aspas = null; continue; }
+            if (ch === '\\' && aspas === '"' && i + 1 < s.length && /["\\$`]/.test(s[i + 1])) { atual += s[++i]; continue; }
+            atual += ch; continue;
+        }
+        if (ch === '"' || ch === "'") { aspas = ch; if (atual == null) atual = ''; continue; }
+        if (ch === '\\' && i + 1 < s.length) { atual = (atual || '') + s[++i]; continue; }
+        if (/\s/.test(ch)) { if (atual != null) { out.push(atual); atual = null; } continue; }
+        if (/[;&|<>`$()]/.test(ch)) return null;
+        atual = (atual || '') + ch;
+    }
+    if (aspas) return null;
+    if (atual != null) out.push(atual);
+    return out;
+}
+
+// ── peças soltas (lib/plugin/estudio/materiais.js): a IA lista, lê e escreve a cena do zero ──
+
+async function cmdPecas(a, op) {
+    const [estilo, sub, alvo] = a._;
+    if (!estilo) return { ok: true, texto: `Estilos com peças soltas: ${MATERIAIS.estilos().join(', ') || 'nenhum'}. Uso: primocode kit pecas <estilo> [ver <peça> | regras | escrever <nome> --arquivo <cena.tsx> | conferir <cena.tsx> | renderizar <nome>]` };
+    if (!MATERIAIS.migrado(estilo)) return { ok: false, texto: `O estilo "${estilo}" ainda não tem peças soltas (migrados: ${MATERIAIS.estilos().join(', ') || 'nenhum'}).` };
+    const pasta = op.projectDir || process.cwd();
+    const lerArq = (f) => fs.readFileSync(path.resolve(pasta, String(f)), 'utf8');
+    try {
+        switch (sub) {
+            case undefined: case 'listar': return MATERIAIS.listar(estilo);
+            case 'ver': return alvo ? MATERIAIS.lerPeca(estilo, alvo) : { ok: false, texto: 'Uso: primocode kit pecas <estilo> ver <peça>' };
+            case 'regras': return MATERIAIS.regras(estilo);
+            case 'escrever': return alvo && a.arquivo ? MATERIAIS.escreverCena(estilo, pasta, alvo, lerArq(a.arquivo)) : { ok: false, texto: 'Uso: primocode kit pecas <estilo> escrever <nome> --arquivo <cena.tsx>' };
+            case 'conferir': { const c = MATERIAIS.conferirCena(estilo, lerArq(alvo || a.arquivo)); return { ok: c.ok, texto: c.ok ? `ok ${JSON.stringify(c.medidas)}` : c.erros.join('\n') }; }
+            case 'renderizar': {
+                const arq = path.join(pasta, 'motion', `${alvo}.tsx`);
+                if (!alvo || !fs.existsSync(arq)) return { ok: false, texto: 'Grave a cena antes: … escrever <nome> --arquivo <cena.tsx>' };
+                const est = garantirEstudio({ home: op.home, aoFalar: op.aoFalar, env: op.env || process.env });
+                if (!est.ok) return { ok: false, texto: est.error };
+                const dir = path.join(pasta, 'motion', `.render-${alvo}`);
+                MATERIAIS.prepararRender(estilo, dir, arq, { duracao: a.quadros ? Number(a.quadros) : undefined });
+                ligarModulos(dir, est.modulos);
+                const saida = path.resolve(pasta, String(a.saida || path.join('motion', `${alvo}.mp4`)));
+                const CQ = require('./estudio/conferir-quadros.js');
+                const cenas = CQ.cenasDe(fs.readFileSync(arq, 'utf8'));
+                const r = await rodarRender(dir, saida, { escala: Number(a.escala) || 1, quadros: cenas.map((c) => c.meio), aoFalar: op.aoFalar || (() => {}) });
+                if (!r.ok) return { ok: false, texto: `O render falhou: ${r.error}` };
+                const problemas = cenas.length ? CQ.conferirQuadros(cenas, r.quadros || [], op.visao) : [];
+                const aviso = problemas.length ? `\nConferi o quadro do meio de cada cena e vi ${problemas.length} problema(s); conserte a cena e renderize de novo:\n- ${problemas.map((x) => `cena ${x.cena} (${x.tipo}): ${x.texto}`).join('\n- ')}` : (cenas.length ? '\nConferi o quadro do meio de cada cena: sem quadro vazio, texto cortado, texto sobre rosto nem texto ilegível.' : '');
+                return { ok: true, texto: `Vídeo: ${r.video} (${r.segundos}s). Quadros pra conferir: ${(r.quadros || []).join(', ')}${aviso}`, video: r.video, problemas };
+            }
+            default: return { ok: false, texto: `Subcomando "${sub}" desconhecido. Use listar, ver, regras, escrever, conferir ou renderizar.` };
+        }
+    } catch (e) { return { ok: false, texto: `pecas: ${e.message}` }; }
+}
+
+function opcoes(args) {
+    const a = { _: [] };
+    for (let i = 0; i < args.length; i++) {
+        const m = String(args[i]).match(/^--([a-z-]+)(?:=(.*))?$/);
+        if (!m) { a._.push(args[i]); continue; }
+        if (m[2] != null) a[m[1]] = m[2];
+        else if (i + 1 < args.length && !String(args[i + 1]).startsWith('--')) a[m[1]] = args[++i];
+        else a[m[1]] = true;
+    }
+    return a;
+}
+
+const AJUDA = `primocode kit — os estilos de motion (peças soltas)
+  menu                      o menu dos estilos (no primeiro motion abre a tela de estilos)
+  ver <slug>                as peças e as regras do estilo (igual a pecas <slug>)
+  pecas <estilo> [ver <peça>|regras|escrever <nome> --arquivo <tsx>|conferir <tsx>|renderizar <nome>]
+                            a IA compõe a cena do zero com as peças; o conferir cobra a densidade
+  referencia                abre a tela de referências e devolve o que mediu
+  criar --nome "<nome>" --descricao "<como é>" [--base <slug>] [--ref <vídeo>] [--quando "a; b; c"] [--familia "<família>"]
+  preview <slug>            o preview.mp4 do estilo, se existir; senão a capa
+  galeria                   abre a tela de estilos (capa + preview + nome) e devolve a escolha
+  checar <slug>             confere o índice de peças do estilo
+  lista                     os estilos por família`;
+
+/** Roda um comando. Resolve {ok, texto}. `op`: {projectDir, home, env, aoFalar, abrir, abrirVideo, gostoOp, narrar, abrirReferencias}. */
+async function main(argv, op = {}) {
+    const [cmd, ...resto] = argv;
+    const a = opcoes(resto);
+    if (op.home) process.env.PRIMOCODE_MATERIAIS_USUARIO = usuarioMateriais(op.home);
+    try {
+        switch (cmd) {
+            case 'menu': return await cmdMenu(op);
+            case 'ver': case 'skill': return a._[0] ? cmdVer(a._[0], op) : { ok: false, texto: 'Uso: primocode kit ver <slug>' };
+            case 'referencia': case 'referencias': return await cmdReferencia(a, op);
+            case 'pecas': case 'materiais': return await cmdPecas(a, op);
+            case 'montar': case 'batida': case 'plano': case 'fazer': case 'confirmar': return { ok: false, texto: `"kit ${cmd}" saiu: não há esqueleto, batida nem plano pronto. Componha a cena do zero com as peças: primocode kit pecas <estilo> (ver, regras, escrever, renderizar).` };
+            case 'criar': return cmdCriar(a, op);
+            case 'preview': return a._[0] ? await cmdPreview(a._[0], op) : { ok: false, texto: 'Uso: primocode kit preview <slug>' };
+            case 'galeria': case 'escolher': return await cmdGaleria(op);
+            case 'lista': case 'list': case undefined: return { ok: true, texto: listaParaPessoa(op).join('\n') };
+            case 'checar': { const k = achar(a._[0] || '', op); if (!k) return naoExiste(a._[0] || '', op); const e = MATERIAIS.validar(k.slug); return { ok: !e.length, texto: e.length ? e.join('\n') : `ok ${k.slug}` }; }
+            default: return { ok: cmd === 'help' || cmd === 'ajuda', texto: AJUDA };
+        }
+    } catch (e) { return { ok: false, texto: `primocode kit ${cmd}: ${e.message}` }; }
+}
+
+/**
+ * O run_shell chama isto antes de abrir um shell (lib/tool/tools.js): `primocode kit …` roda AQUI, no processo do
+ * PrimoCode, pra tela de estilos e a de referências abrirem do jeito certo (no app, pela linha de protocolo).
+ * null quando o comando não é de kit (ou tem operador de shell): aí segue o shell de sempre.
+ */
+async function doShell(comando, op = {}) {
+    const linha = String(comando || '').trim();
+    let w = palavras(linha), resto = '';
+    // "primocode kit batida 2 --help || true", "… 2>&1 | head -50": o modelo cola operador de shell. Sem isto a linha ia
+    // pro shell de verdade, que rodava OUTRO primocode (o instalado no sistema) e abria uma sessão aninhada até o prazo.
+    if (!w) {
+        const pre = antesDoOperador(linha).replace(/\s+\d$/, '');
+        w = palavras(pre);
+        resto = linha.slice(pre.length).trim();
+    }
+    if (!w || w.length < 2 || !/^(primocode|primo)$/.test(path.basename(w[0])) || !/^(kit|kits)$/.test(w[1])) return null;
+    const r = await main(w.slice(2), op);
+    const nota = resto ? `\n(rodei só "${w.join(' ')}" aqui dentro; "${resto.slice(0, 60)}" não roda: o primocode kit responde inteiro, sem pipe)` : '';
+    return { ok: r.ok, code: r.ok ? 0 : 1, stdout: r.texto + nota + '\n', stderr: '', ...(r.ok ? {} : { error: r.texto }) };
+}
+
+/** O começo da linha até o primeiro operador de shell fora de aspas (; & | < > ` $ ( )). */
+function antesDoOperador(linha) {
+    let aspas = null;
+    for (let i = 0; i < linha.length; i++) {
+        const ch = linha[i];
+        if (aspas) { if (ch === aspas) aspas = null; else if (ch === '\\' && aspas === '"') i++; continue; }
+        if (ch === '"' || ch === "'") { aspas = ch; continue; }
+        if (ch === '\\') { i++; continue; }
+        if (/[;&|<>`$()]/.test(ch)) return linha.slice(0, i).trimEnd();
+    }
+    return linha;
+}
+
+/** Já não há esqueleto com batidas pra completar (o caminho de peças soltas não empurra): sempre vazio. */
+function batidasFaltando() { return []; }
+/** O pedido da pessoa continua o vídeo? (motion, ou um "sim/continua/pode/segue"): só então a montagem empurra. */
+const CONTINUA = /^\s*(sim|s|ok|okay|pode|continua|continue|segue|siga|bora|vai|manda|faz|isso|beleza|claro|yes|go)\b/i;
+const continuaVideo = (texto) => pareceMotion(texto) || CONTINUA.test(semAcento(texto));
+
+module.exports = {
+    batidasFaltando, continuaVideo,
+    RAIZ, FAMILIAS, casa, listar, achar, lerFrontmatter, menuParaIA, cabecaDoPedido, pareceMotion,
+    cmdPecas, palavras, opcoes, galeriaHtml, listaParaPessoa, previewPronto,
+    novoTurno, turnoAtual, main, doShell, garantirEstudio, usuarioMateriais,
+};