primocode 8.27.0 → 8.30.0

package/lib/remotion.js

@@ -0,0 +1,463 @@
+/**
+ * remotion.js — a mesma peça, renderizada por Remotion.
+ *
+ *   "Também ele vai poder usar o Remotion. Aí ele decide qual usar, ou usa o
+ *    que o usuário pedir."
+ *
+ * ── POR QUE ISTO NÃO É UMA DEPENDÊNCIA DO PRIMOCODE ──────────────────────
+ * Remotion é React + um Chromium próprio + ffmpeg: perto de meio giga. Pôr
+ * isso no `dependencies` do PrimoCode faria `npm i -g primocode` baixar meio
+ * giga para todo mundo — inclusive para quem nunca vai fazer um vídeo.
+ *
+ * E não precisa: Remotion é um projeto, não uma biblioteca de linha de
+ * comando. O jeito certo de usá-lo é ter um projeto Remotion, e é isso que
+ * este módulo escreve — na pasta do USUÁRIO, com as dependências dele. O
+ * PrimoCode continua com zero dependência, e quem quiser Remotion tem um
+ * projeto de verdade, que abre no `remotion studio`, entra no git e pode ser
+ * editado à mão depois.
+ *
+ * ── POR QUE ELE PARTE DO DOCUMENTO DO ESTÚDIO ────────────────────────────
+ * A tentação era inventar um segundo vocabulário — "para o Remotion escreva
+ * assim". Seriam duas gramáticas para o agente aprender, duas para manter, e
+ * uma ficaria velha.
+ *
+ * O projeto gerado leva junto o `render.js` e o `render.css` do estúdio, que
+ * é quem sabe desenhar uma cena. A composição React só decide QUAL cena está
+ * no ar em cada quadro e aplica entrada e transição a partir de
+ * `useCurrentFrame()`. O mesmo `doc` que toca no navegador renderiza aqui.
+ *
+ * ── QUANDO VALE A PENA ───────────────────────────────────────────────────
+ * O estúdio exporta em segundos, sem instalar nada, e é o padrão. Remotion
+ * pede `npm install` (uma vez, minutos) e devolve outra coisa:
+ *
+ *   · quadro a quadro determinístico — o mesmo arquivo em toda máquina, sem
+ *     depender de a aba estar em foco nem da carga do computador;
+ *   · vídeo longo sem risco de o navegador engasgar no meio;
+ *   · fps e qualidade escolhidos, ProRes, canal alfa, renderização paralela;
+ *   · e um projeto que a pessoa pode abrir e mexer em React.
+ *
+ * ── LICENÇA ──────────────────────────────────────────────────────────────
+ * Remotion é grátis para pessoa física e para empresa pequena, mas EMPRESA
+ * ACIMA DE TRÊS PESSOAS precisa de licença paga. Isso vale para o projeto que
+ * nasce na pasta do usuário, não para o PrimoCode — e por isso o aviso vai no
+ * README gerado e na resposta da tool. Descobrir isso depois de montar o
+ * fluxo de trabalho em cima dele seria péssimo.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const ORIGEM_ESTUDIO = path.join(__dirname, '..', 'studio', 'web');
+const VERSAO_REMOTION = '4.0.522';
+
+// Arquivos do estúdio que o projeto Remotion precisa para desenhar uma cena.
+// São os mesmos que o navegador carrega — nada é reescrito.
+const DO_ESTUDIO = [
+    ['js/render.js', 'render.js'],
+    ['js/icones.js', 'icones.js'],
+    ['render.css', 'render.css'],
+    ['fontes.css', 'fontes.css'],
+];
+
+function escrever(destino, conteudo) {
+    fs.mkdirSync(path.dirname(destino), { recursive: true });
+    fs.writeFileSync(destino, conteudo, 'utf-8');
+}
+
+/* Quantos quadros dura cada cena, com a MESMA conta do player.
+ *
+ * Duplicar esta conta aqui foi tentador e seria errado: se ela divergisse do
+ * player, o vídeo exportado por Remotion teria duração diferente do que a
+ * pessoa aprovou na tela — e ninguém desconfiaria, porque os dois estariam
+ * "funcionando". Então a regra é uma só e está escrita em um lugar; o
+ * projeto gerado importa daqui. */
+function segundosDaCena(c) {
+    let d = Number(c && c.duracao);
+    let clipe = 0;
+    for (const e of (c && c.elementos) || []) {
+        if (!e || e.tipo !== 'clipe') continue;
+        const de = Number(e.de) || 0;
+        const ate = Number(e.ate);
+        if (isFinite(ate) && ate > de) clipe = Math.max(clipe, ate - de);
+    }
+    if (!(isFinite(d) && d > 0)) d = clipe > 0 ? Math.min(600, clipe) : 4;
+    else d = Math.min(clipe > 0 ? 600 : 60, d);
+
+    const n = Number(c && c.narracaoDur);
+    if (isFinite(n) && n > 0 && c && c.narracaoAudio) d = Math.max(d, Math.min(90, n + 0.4));
+    return d;
+}
+
+function totalSegundos(doc) {
+    return ((doc && doc.cenas) || []).reduce((s, c) => s + segundosDaCena(c), 0);
+}
+
+// ── os arquivos do projeto ───────────────────────────────────────────────
+
+function pkgJson(nome) {
+    return JSON.stringify({
+        name: nome || 'video-primocode',
+        version: '1.0.0',
+        private: true,
+        scripts: {
+            /* `studio` abre a pré-visualização com linha do tempo; `render`
+               escreve o mp4.
+
+               O ponto de entrada vai ESCRITO. O Remotion procura sozinho por
+               `src/index.ts` e alguns outros nomes fixos, e este projeto é
+               .jsx — sem TypeScript, para não arrastar um toolchain inteiro
+               para dentro da pasta de quem só quer um vídeo. Sem o caminho,
+               ele responde "No entry point specified" e não renderiza nada. */
+            studio: 'remotion studio src/index.jsx',
+            render: 'remotion render src/index.jsx Video saida/video.mp4',
+            build: 'remotion render src/index.jsx Video saida/video.mp4 --codec=h264 --crf=16',
+        },
+        dependencies: {
+            remotion: VERSAO_REMOTION,
+            '@remotion/cli': VERSAO_REMOTION,
+            react: '19.0.0',
+            'react-dom': '19.0.0',
+        },
+    }, null, 2) + '\n';
+}
+
+const INDEX_JSX = `import { registerRoot } from "remotion";
+import { Raiz } from "./Raiz.jsx";
+
+registerRoot(Raiz);
+`;
+
+function raizJsx(doc, fps) {
+    return `import { Composition } from "remotion";
+import { Filme } from "./Filme.jsx";
+import doc from "./doc.json";
+import { totalQuadros } from "./tempo.js";
+
+/* A composição. \`durationInFrames\` sai da MESMA conta de duração que o
+   player do estúdio usa (ver tempo.js) — se as duas divergissem, o arquivo
+   exportado teria outro tamanho que o vídeo aprovado na tela, e nada
+   denunciaria. */
+export const Raiz = () => (
+  <Composition
+    id="Video"
+    component={Filme}
+    durationInFrames={totalQuadros(doc, ${fps})}
+    fps={${fps}}
+    width={${doc.largura || 1920}}
+    height={${doc.altura || 1080}}
+    defaultProps={{ doc }}
+  />
+);
+`;
+}
+
+/* A conta de tempo, em módulo próprio, gerada a partir da função acima.
+   Assim o projeto do usuário não depende do PrimoCode estar instalado. */
+function tempoJs(fps) {
+    return `/* Quanto dura cada cena — a MESMA regra do player do estúdio.
+ *
+ * Copiada de propósito para dentro do projeto: ele tem de renderizar sozinho,
+ * sem o PrimoCode instalado. Se você mudar a duração de uma cena, mude no
+ * doc.json — não aqui.
+ */
+export const FPS = ${fps};
+
+export function segundosDaCena(c) {
+  let d = Number(c && c.duracao);
+  let clipe = 0;
+  for (const e of (c && c.elementos) || []) {
+    if (!e || e.tipo !== "clipe") continue;
+    const de = Number(e.de) || 0;
+    const ate = Number(e.ate);
+    if (isFinite(ate) && ate > de) clipe = Math.max(clipe, ate - de);
+  }
+  if (!(isFinite(d) && d > 0)) d = clipe > 0 ? Math.min(600, clipe) : 4;
+  else d = Math.min(clipe > 0 ? 600 : 60, d);
+
+  const n = Number(c && c.narracaoDur);
+  if (isFinite(n) && n > 0 && c && c.narracaoAudio) d = Math.max(d, Math.min(90, n + 0.4));
+  return d;
+}
+
+/* Quadros, não segundos: dentro do Remotion o tempo é inteiro. Arredondar
+ * para cima em cada cena evita a cena de 3,02s virar 3,0 e comer dois
+ * quadros do fim — e evita o acúmulo desse erro ao longo do filme. */
+export function quadrosDaCena(c, fps = FPS) {
+  return Math.max(1, Math.round(segundosDaCena(c) * fps));
+}
+
+export function totalQuadros(doc, fps = FPS) {
+  const cenas = (doc && doc.cenas) || [];
+  const soma = cenas.reduce((s, c) => s + quadrosDaCena(c, fps), 0);
+  return Math.max(1, soma);
+}
+
+/* Qual cena está no ar no quadro \`q\`, e há quantos quadros ela começou.
+ * Devolver o "dentro" junto evita o chamador refazer a soma — e refazer a
+ * soma com outra regra de arredondamento é exatamente como as duas metades
+ * de um render saem fora de sincronia. */
+export function cenaNoQuadro(doc, q, fps = FPS) {
+  const cenas = (doc && doc.cenas) || [];
+  let acc = 0;
+  for (let i = 0; i < cenas.length; i++) {
+    const dur = quadrosDaCena(cenas[i], fps);
+    if (q < acc + dur) return { i, dentro: q - acc, dur };
+    acc += dur;
+  }
+  const ult = cenas.length - 1;
+  const dur = ult >= 0 ? quadrosDaCena(cenas[ult], fps) : 1;
+  return { i: Math.max(0, ult), dentro: dur - 1, dur };
+}
+`;
+}
+
+const FILME_JSX = `import { useCurrentFrame, useVideoConfig, AbsoluteFill, Audio, staticFile } from "remotion";
+import { useEffect, useRef } from "react";
+import { cenaNoQuadro, quadrosDaCena } from "./tempo.js";
+import "./render.css";
+import "./fontes.css";
+import { renderCena } from "./render.js";
+
+/* O desenho de uma cena é do ESTÚDIO — render.js é o mesmo arquivo que o
+   navegador carrega. Aqui só se decide qual cena está no ar e como ela entra.
+   Inventar um segundo desenhista daria duas gramáticas para manter, e uma
+   ficaria velha. */
+function Cena({ cena, doc, dentro, dur }) {
+  const caixa = useRef(null);
+
+  useEffect(() => {
+    if (!caixa.current) return;
+    caixa.current.innerHTML = "";
+    // \`animar: false\`: quem anima aqui é o Remotion, quadro a quadro. Com as
+    // animações CSS ligadas, cada quadro renderizado recomeçaria a animação
+    // do zero — o vídeo sairia com o primeiro instante repetido do começo ao
+    // fim, tecnicamente perfeito e visualmente parado.
+    caixa.current.appendChild(renderCena(cena, doc, { animar: false }));
+  }, [cena, doc]);
+
+  return <div ref={caixa} style={{ width: "100%", height: "100%" }} />;
+}
+
+/* Entrada e transição vindas do quadro, não do CSS.
+
+   \`t\` vai de 0 a 1 nos primeiros 18 quadros da cena. A curva é a mesma do
+   estúdio (cubic-bezier .22 1 .36 1, aproximada por um easeOutCubic): sem
+   isso a peça exportada por Remotion teria outro tempo de entrada que a
+   mesma peça vista no navegador. */
+function entrada(transicao, t) {
+  const s = 1 - Math.pow(1 - t, 3);
+  switch (transicao) {
+    case "corte":     return {};
+    case "deslizar":  return { opacity: s, transform: \`translateX(\${(1 - s) * 8}%)\` };
+    case "subir":     return { opacity: s, transform: \`translateY(\${(1 - s) * 8}%)\` };
+    case "zoom":      return { opacity: s, transform: \`scale(\${0.92 + s * 0.08})\` };
+    case "flash":     return { opacity: s, filter: \`brightness(\${1 + (1 - s) * 2.2})\` };
+    case "limpar":    return { opacity: 1, clipPath: \`inset(0 \${(1 - s) * 100}% 0 0)\` };
+    case "persiana":  return { opacity: 1, clipPath: \`inset(\${(1 - s) * 50}% 0 \${(1 - s) * 50}% 0)\` };
+    default:          return { opacity: s };            // fade
+  }
+}
+
+export const Filme = ({ doc }) => {
+  const quadro = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const { i, dentro } = cenaNoQuadro(doc, quadro, fps);
+  const cenas = doc.cenas || [];
+  const cena = cenas[i] || {};
+  const dur = quadrosDaCena(cena, fps);
+
+  const QUADROS_ENTRADA = Math.max(1, Math.round(0.62 * fps));
+  const t = Math.min(1, dentro / QUADROS_ENTRADA);
+
+  return (
+    <AbsoluteFill style={{ backgroundColor: "#000" }}>
+      <AbsoluteFill style={entrada(cena.transicao, t)}>
+        <Cena cena={cena} doc={doc} dentro={dentro} dur={dur} />
+      </AbsoluteFill>
+      {doc.trilha && doc.trilha.src ? (
+        <Audio src={doc.trilha.src.startsWith("http") ? doc.trilha.src : staticFile(doc.trilha.src)}
+               volume={doc.trilha.volume == null ? 0.7 : doc.trilha.volume} />
+      ) : null}
+    </AbsoluteFill>
+  );
+};
+`;
+
+/* O render.js do estúdio é um script de navegador: define funções soltas, sem
+ * export nenhum. O bundler do Remotion precisa de módulo.
+ *
+ * A saída é o arquivo ORIGINAL, sem uma linha alterada, com um `export` no
+ * fim. Reescrever o conteúdo seria criar uma segunda versão do desenhista
+ * para manter — e a que ficasse velha seria justamente a que renderiza o
+ * arquivo final, onde ninguém olha até estar publicado. */
+function comoModulo(fonte, nomes) {
+    return fonte
+        + '\n\n/* ── acrescentado pelo PrimoCode ─────────────────────────────────────\n'
+        + '   O arquivo acima é o render do estúdio, byte por byte. Só o export é\n'
+        + '   novo: no navegador ele é um script solto, e aqui precisa ser módulo.\n'
+        + '   Não edite o que está em cima — atualize o PrimoCode e gere de novo. */\n'
+        + `export { ${nomes.join(', ')} };\n`;
+}
+
+/* `icones.js` é lido pelo render.js pelo nome global. Em módulo, o nome não
+   vaza para o escopo global sozinho — daí o empurrão explícito. */
+function iconesComoModulo(fonte) {
+    return fonte
+        + '\n\n/* ── acrescentado pelo PrimoCode ────────────────────────────────────\n'
+        + '   O render.js procura os ícones no escopo global, como no navegador. */\n'
+        + 'if (typeof globalThis !== "undefined") {\n'
+        + '  if (typeof ICONES !== "undefined") globalThis.ICONES = ICONES;\n'
+        + '  if (typeof svgIcone === "function") globalThis.svgIcone = svgIcone;\n'
+        + '}\n';
+}
+
+function readme(titulo, doc) {
+    const seg = totalSegundos(doc);
+    return `# ${titulo || 'Vídeo'} — projeto Remotion
+
+Gerado pelo PrimoCode a partir da peça do Studio. As cenas estão em
+\`src/doc.json\`; o desenho delas é o mesmo do Studio (\`src/render.js\`).
+
+## Rodar
+
+\`\`\`bash
+npm install          # uma vez, e demora — Remotion traz o próprio navegador
+npm run studio       # pré-visualização com linha do tempo
+npm run render       # escreve saida/video.mp4
+\`\`\`
+
+Duração: ${seg.toFixed(1)}s · ${doc.largura || 1920}×${doc.altura || 1080}
+· ${(doc.cenas || []).length} cena(s).
+
+## Quando usar isto em vez do Studio
+
+O Studio exporta o MP4 num clique, sem instalar nada, e é o caminho normal.
+Este projeto existe para o que ele não faz:
+
+- **quadro a quadro determinístico** — o mesmo arquivo em qualquer máquina,
+  sem depender de a aba estar em foco nem da carga do computador;
+- **vídeo longo** sem risco de o navegador engasgar no meio;
+- **fps, CRF, ProRes, canal alfa** e renderização paralela;
+- **mexer no código**: daqui para a frente é React, e é seu.
+
+## Editar
+
+- Conteúdo, cores e tempo: \`src/doc.json\`.
+- Como cada cena entra: \`entrada()\` em \`src/Filme.jsx\`.
+- Como um elemento é desenhado: \`src/render.js\` — mas ele é copiado do
+  Studio. Mexendo ali, um novo \`remotion_projeto\` sobrescreve. Se for
+  mudança para valer, mude no PrimoCode.
+
+## Licença do Remotion
+
+Remotion é **grátis para pessoa física e para empresa de até três pessoas**.
+Acima disso, a empresa precisa de licença paga — veja
+<https://remotion.dev/license>. Isso vale para ESTE projeto, que é seu; o
+PrimoCode não depende de Remotion e não muda de licença por causa disto.
+`;
+}
+
+const GITIGNORE = 'node_modules/\nsaida/\n.remotion/\n';
+
+// ── montar o projeto ─────────────────────────────────────────────────────
+
+/**
+ * Escreve um projeto Remotion completo a partir de uma peça do Studio.
+ *
+ * @param {object} op
+ * @param {string} op.destino  pasta onde o projeto nasce
+ * @param {string} op.titulo
+ * @param {object} op.doc      o documento da peça (cenas, tema, trilha…)
+ * @param {number} [op.fps]
+ */
+function montar({ destino, titulo, doc, fps }) {
+    if (!destino) return { ok: false, error: 'diga em que pasta o projeto vai nascer' };
+    if (!doc || !Array.isArray(doc.cenas) || !doc.cenas.length) {
+        return { ok: false, error: 'esta peça não tem cenas — Remotion renderiza cenas, como o Studio' };
+    }
+    const taxa = Math.max(1, Math.min(120, Number(fps) || 30));
+
+    const src = path.join(destino, 'src');
+    fs.mkdirSync(src, { recursive: true });
+
+    // Os arquivos do estúdio, sem reescrever conteúdo.
+    for (const [de, para] of DO_ESTUDIO) {
+        const origem = path.join(ORIGEM_ESTUDIO, de);
+        if (!fs.existsSync(origem)) continue;
+        let conteudo = fs.readFileSync(origem, 'utf-8');
+        if (para === 'render.js') conteudo = comoModulo(conteudo, ['renderCena', 'renderElemento']);
+        else if (para === 'icones.js') conteudo = iconesComoModulo(conteudo);
+        escrever(path.join(src, para), conteudo);
+    }
+    // A ordem importa: render.js procura os ícones no global.
+    const alvoRender = path.join(src, 'render.js');
+    if (fs.existsSync(alvoRender)) {
+        escrever(alvoRender, 'import "./icones.js";\n' + fs.readFileSync(alvoRender, 'utf-8'));
+    }
+
+    escrever(path.join(destino, 'package.json'), pkgJson(titulo));
+    escrever(path.join(destino, 'README.md'), readme(titulo, doc));
+    escrever(path.join(destino, '.gitignore'), GITIGNORE);
+    escrever(path.join(src, 'index.jsx'), INDEX_JSX);
+    escrever(path.join(src, 'Raiz.jsx'), raizJsx(doc, taxa));
+    escrever(path.join(src, 'Filme.jsx'), FILME_JSX);
+    escrever(path.join(src, 'tempo.js'), tempoJs(taxa));
+    escrever(path.join(src, 'doc.json'), JSON.stringify(doc, null, 2) + '\n');
+
+    return {
+        ok: true,
+        pasta: destino,
+        fps: taxa,
+        segundos: +totalSegundos(doc).toFixed(2),
+        quadros: Math.round(totalSegundos(doc) * taxa),
+        cenas: doc.cenas.length,
+        comoRodar: `cd ${destino} && npm install && npm run render`,
+        licenca: 'Remotion é grátis para pessoa física e empresa de até 3 pessoas; '
+            + 'acima disso a empresa precisa de licença paga (remotion.dev/license). '
+            + 'Vale para este projeto, não para o PrimoCode.',
+    };
+}
+
+/**
+ * Roda o render de um projeto já montado. Só faz sentido depois do
+ * `npm install` — Remotion baixa o próprio navegador, e isso leva minutos na
+ * primeira vez.
+ */
+function renderizar({ pasta, saida, minutos = 20 }) {
+    return new Promise((resolve) => {
+        if (!fs.existsSync(path.join(pasta, 'node_modules'))) {
+            return resolve({
+                ok: false,
+                error: `Falta instalar. Rode: cd ${pasta} && npm install  (demora — o Remotion `
+                    + 'traz o próprio navegador). Depois peça o render de novo.',
+            });
+        }
+        const arquivo = saida || path.join('saida', 'video.mp4');
+        const proc = spawn(process.platform === 'win32' ? 'npx.cmd' : 'npx',
+            ['remotion', 'render', 'src/index.jsx', 'Video', arquivo, '--log=error'],
+            { cwd: pasta, stdio: ['ignore', 'pipe', 'pipe'] });
+
+        let fora = '';
+        proc.stdout.on('data', (d) => { fora += d; });
+        proc.stderr.on('data', (d) => { fora += d; });
+
+        const prazo = setTimeout(() => { try { proc.kill(); } catch {} }, minutos * 60000);
+        proc.on('close', (codigo) => {
+            clearTimeout(prazo);
+            const alvo = path.join(pasta, arquivo);
+            if (codigo === 0 && fs.existsSync(alvo)) {
+                return resolve({
+                    ok: true, arquivo: alvo,
+                    bytes: fs.statSync(alvo).size,
+                });
+            }
+            resolve({ ok: false, error: (fora || `remotion saiu com ${codigo}`).slice(-1200) });
+        });
+        proc.on('error', (e) => { clearTimeout(prazo); resolve({ ok: false, error: e.message }); });
+    });
+}
+
+module.exports = { montar, renderizar, segundosDaCena, totalSegundos, VERSAO_REMOTION };

package/lib/tools.js

@@ -579,6 +579,36 @@ async function despachar(name, args, ctx) {
                     arquivo: args.arquivo, pausa: args.pausa, abrir: openInBrowser,
                 });
 
+            /* A MESMA peça, virando projeto Remotion.
+             *
+             * O Studio continua sendo o caminho normal: exporta em segundos,
+             * sem instalar nada. Isto é para quando o usuário pede Remotion
+             * pelo nome, ou quando a peça precisa do que só ele dá — render
+             * determinístico, vídeo longo, fps e codec escolhidos, ou o
+             * projeto em React para a pessoa mexer.
+             *
+             * Parte do documento que já existe: nada de um segundo
+             * vocabulário para o agente aprender. */
+            case 'remotion_projeto': {
+                const remotion = require('./remotion.js');
+                const peca = await studio.ler(args.id);
+                if (!peca || peca.ok === false) {
+                    return peca || { ok: false, error: `não achei a peça ${args.id}` };
+                }
+                const arq = peca.arquivo || peca;
+                const base = projectDir || cfg.ROOT_DIR;
+                const nome = cfg.slugify(args.pasta || arq.titulo || 'video') + '-remotion';
+                const destino = path.join(base, nome);
+                const r = remotion.montar({
+                    destino, titulo: arq.titulo, doc: arq.doc, fps: args.fps,
+                });
+                if (!r.ok || !args.renderizar) return r;
+                // Só renderiza quando pedido: o `npm install` demora minutos e
+                // é escolha do usuário, não efeito colateral de criar a pasta.
+                const feito = await remotion.renderizar({ pasta: destino });
+                return Object.assign(r, { render: feito });
+            }
+
             case 'desktop_double_click':
                 return desktop.doubleClick(args.x, args.y);
             case 'desktop_open_app':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "8.27.0",
+  "version": "8.30.0",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/primocode.js",
-    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/studio-spec.test.js && node test/studio-versoes.test.js && node test/voz.test.js && node test/editor.test.js && node test/estudio-projeto.test.js && node test/vocabulario.test.js && node test/video-export.test.js && node test/monotonia.test.js && node test/clipe.test.js && node test/midia-envio.test.js && node test/pausas.test.js && node test/app.test.js && node test/elementos.test.js"
+    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/studio-spec.test.js && node test/studio-versoes.test.js && node test/voz.test.js && node test/editor.test.js && node test/estudio-projeto.test.js && node test/vocabulario.test.js && node test/video-export.test.js && node test/monotonia.test.js && node test/clipe.test.js && node test/midia-envio.test.js && node test/pausas.test.js && node test/app.test.js && node test/elementos.test.js && node test/remotion.test.js && node test/aplicativo.test.js && node test/conta.test.mjs"
   },
   "engines": {
     "node": ">=18.17.0"

package/studio/ferramentas/corte.md

@@ -180,6 +180,37 @@ livre de direitos, ou uma das trilhas geradas acima.
 
 ---
 
+## Studio ou Remotion?
+
+**O padrão é o Studio.** Ele exporta o MP4 num clique, em segundos, sem
+instalar nada. Não ofereça Remotion sem motivo — trocar um clique por
+`npm install` de 250 MB é piorar a vida de quem só quer o vídeo.
+
+Chame `remotion_projeto` (com o `id` da peça) em três casos, e só neles:
+
+1. **O usuário pediu Remotion pelo nome.** Não discuta, faça.
+2. **A peça precisa do que o Studio não dá:** render determinístico (o mesmo
+   arquivo em qualquer máquina, sem depender de a aba estar em foco), vídeo
+   muito longo, fps ou codec específico (ProRes, canal alfa), renderização em
+   servidor.
+3. **O usuário quer mexer no código.** O projeto que nasce é React, é dele, e
+   entra no git.
+
+A peça é a MESMA — `remotion_projeto` parte do documento que você já criou
+com `studio_criar`. Não existe um segundo formato para aprender: crie a peça
+normalmente, veja no navegador, e só então gere o projeto se fizer sentido.
+
+O projeto nasce sem `node_modules`. **Não rode `renderizar: true` antes de o
+`npm install` ter sido feito** — diga ao usuário os dois comandos e deixe ele
+decidir se quer esperar.
+
+**Licença:** Remotion é grátis para pessoa física e empresa de até três
+pessoas; acima disso a empresa precisa de licença paga. Avise ao oferecer —
+descobrir isso depois de montar o fluxo de trabalho em cima seria péssimo.
+Isso vale para o projeto do usuário, não para o PrimoCode.
+
+---
+
 ## Elementos que dão cara de produção
 
 Estes seis existem porque um vídeo genérico é feito só de título + texto. São