primocode 8.42.2 → 9.0.0

package/lib/estudio/plano.js

@@ -0,0 +1,327 @@
+/**
+ * plano.js — o que é um vídeo, agora que não há mais modelos prontos.
+ *
+ *   "REMOVER todos os templates e estilos pré-prontos que existem hoje. Eles
+ *    deixam a IA preguiçosa e todos os vídeos acabam iguais e genéricos. A IA
+ *    cria tudo do zero, a cada vídeo."
+ *
+ * ── O QUE SAIU, E O QUE ENTROU NO LUGAR ──────────────────────────────────
+ * Saiu o vocabulário de LOOKS. O Studio antigo tinha `layout: "capa"`,
+ * `layout: "duas-colunas"`, `tema: "meia-noite"`, e um `corte.md` de 772
+ * linhas com um exemplo completo de vídeo. Pedir um vídeo era escolher entre
+ * as caixas que já existiam — e o resultado saía com a cara das caixas, não
+ * do assunto. Era isso que fazia todo vídeo parecer o anterior.
+ *
+ * Entrou um vocabulário de PRIMITIVAS: texto, forma, imagem, vídeo, ícone,
+ * legenda — cada um com posição, tamanho, cor e animação por quadro-chave,
+ * mais uma câmera por cena. Nenhuma primitiva tem aparência própria; ela não
+ * sabe o que é uma "capa".
+ *
+ * A diferença entre isso e um template é a mesma entre tinta e um quadro
+ * pintado. Duas peças feitas com estas primitivas não se parecem, a menos que
+ * quem escreveu tenha escolhido que se parecessem.
+ *
+ * ── E QUANDO A PRIMITIVA NÃO ALCANÇA ─────────────────────────────────────
+ * Existe cena que nenhum vocabulário fechado descreve: uma malha 3D girando,
+ * um morfismo entre dois traçados, um efeito escrito na hora. Para essas, a
+ * cena aponta um `componente`: um arquivo React que a própria IA escreve na
+ * pasta do projeto, e que o Remotion monta como qualquer outra cena.
+ *
+ * É a válvula que impede este arquivo de virar o que ele acabou de
+ * substituir — uma lista de efeitos permitidos, crescendo para sempre.
+ *
+ * ── O QUE ESTE ARQUIVO NÃO FAZ ───────────────────────────────────────────
+ * Ele não tem opinião sobre estética. Não recusa fundo roxo, não exige
+ * paleta, não conta quantas fontes você usou. Isso é assunto da skill que vai
+ * na frente do pedido (skills/motion-de-primeira/SKILL.md) — conselho que o
+ * modelo lê e pondera, não regra que o código impõe. Código que recusa uma
+ * cor é código que um dia recusa a cor certa.
+ *
+ * O que ele faz é conferir se o plano É EXECUTÁVEL: cena sem duração, cor
+ * escrita errada, imagem que não existe no disco, quadro-chave fora de ordem.
+ * Tudo isso vira vídeo quebrado ou renderização que morre no meio, e o erro
+ * aparece vinte minutos depois — então ele aparece agora.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TIPOS = new Set(['texto', 'forma', 'imagem', 'video', 'icone', 'legenda', 'componente']);
+const FORMAS = new Set(['retangulo', 'circulo', 'linha', 'poligono', 'traco']);
+const AJUSTES = new Set(['cover', 'contain', 'preencher']);
+const TRANSICOES = new Set(['corte', 'esmaecer', 'deslizar', 'zoom', 'giro', 'mascara', 'morph']);
+
+/* As propriedades que a animação por quadro-chave alcança. Cada uma é um
+   número no tempo; a curva entre dois quadros é a suavização declarada.
+   `z` e as rotações em X e Y são o que dá 3D de verdade quando a cena declara
+   perspectiva — não é um efeito à parte, é a mesma máquina. */
+const ANIMAVEIS = new Set([
+    'opacidade', 'x', 'y', 'z', 'escala', 'escalaX', 'escalaY',
+    'rotacao', 'rotacaoX', 'rotacaoY', 'desfoque', 'brilho', 'saturacao',
+    'corte', 'raio', 'espacamento',
+]);
+
+/* A CÂMERA tem vocabulário próprio, e é de propósito.
+ *
+ * Um elemento tem `escala` (ele cresce); a câmera tem `zoom` (o mundo inteiro
+ * se aproxima). São coisas diferentes, e chamar as duas de "escala" faria o
+ * agente escrever zoom de câmera dentro de um elemento — o que dá quase o
+ * mesmo resultado na cena de uma coisa só, e nenhum resultado na cena com
+ * cinco. Vocabulários separados tornam o erro impossível em vez de sutil. */
+const ANIMAVEIS_CAMERA = new Set(['zoom', 'x', 'y', 'rotacao']);
+
+const SUAVIZACOES = new Set(['linear', 'suave', 'entrada', 'saida', 'elastico', 'salto']);
+
+const COR = /^(#[0-9a-f]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|transparent|currentColor)$/i;
+
+const erro = (onde, oque) => ({ onde, oque });
+
+/** Um número, aceitando "50%" e "120px" nas posições. */
+function medida(v) {
+    if (typeof v === 'number' && Number.isFinite(v)) return true;
+    return typeof v === 'string' && /^-?\d+(\.\d+)?(%|px|vw|vh)?$/.test(v.trim());
+}
+
+/**
+ * Confere uma trilha de quadros-chave.
+ *
+ * Fora de ordem é o defeito que não dá erro: o Remotion interpola entre os
+ * valores na ordem em que vêm, então um quadro com tempo menor depois de um
+ * maior faz o elemento voltar no tempo, e o que se vê é um tremor que
+ * ninguém consegue explicar olhando o resultado.
+ */
+function conferirTrilha(caminho, trilha, problemas) {
+    if (!Array.isArray(trilha)) {
+        problemas.push(erro(caminho, 'a animação de uma propriedade é uma lista de quadros-chave'));
+        return;
+    }
+    let anterior = -Infinity;
+    trilha.forEach((q, i) => {
+        const onde = `${caminho}[${i}]`;
+        if (!q || typeof q !== 'object') return problemas.push(erro(onde, 'cada quadro é {t, v}'));
+        if (typeof q.t !== 'number' || !Number.isFinite(q.t) || q.t < 0) {
+            problemas.push(erro(onde, 't é o tempo em segundos dentro da cena, a partir de 0'));
+        }
+        if (typeof q.v !== 'number' || !Number.isFinite(q.v)) {
+            problemas.push(erro(onde, 'v é o valor numérico da propriedade nesse instante'));
+        }
+        if (q.e && !SUAVIZACOES.has(q.e)) {
+            problemas.push(erro(onde, `suavização "${q.e}" não existe — use ${[...SUAVIZACOES].join(', ')}`));
+        }
+        if (typeof q.t === 'number' && q.t < anterior) {
+            problemas.push(erro(onde, 'os quadros-chave vêm em ordem de tempo; fora de ordem o elemento volta no tempo'));
+        }
+        anterior = typeof q.t === 'number' ? q.t : anterior;
+    });
+}
+
+function conferirAnima(caminho, anima, problemas, permitidas = ANIMAVEIS) {
+    if (anima == null) return;
+    if (typeof anima !== 'object') return problemas.push(erro(caminho, 'anima é um objeto de propriedade → quadros'));
+    for (const [prop, trilha] of Object.entries(anima)) {
+        if (!permitidas.has(prop)) {
+            problemas.push(erro(`${caminho}.${prop}`,
+                `não dá para animar "${prop}" aqui. Dá para: ${[...permitidas].join(', ')}`));
+            continue;
+        }
+        conferirTrilha(`${caminho}.${prop}`, trilha, problemas);
+    }
+}
+
+function conferirCor(caminho, valor, problemas) {
+    if (valor == null) return;
+    if (typeof valor !== 'string' || !COR.test(valor.trim())) {
+        problemas.push(erro(caminho, `"${valor}" não é uma cor — use #rrggbb, rgb()/rgba() ou hsl()`));
+    }
+}
+
+/** O arquivo existe dentro da pasta do projeto? */
+function conferirArquivo(caminho, src, pasta, problemas) {
+    if (!src) return problemas.push(erro(caminho, 'falta o caminho do arquivo (src)'));
+    if (/^https?:/i.test(src)) {
+        return problemas.push(erro(caminho,
+            'endereço da internet não entra no plano — baixe com estudio_midia e aponte para o arquivo. '
+            + 'Render que depende da rede falha no meio, depois de tudo pronto.'));
+    }
+    if (!pasta) return;
+    const cheio = path.resolve(pasta, src);
+    if (!cheio.startsWith(path.resolve(pasta))) {
+        return problemas.push(erro(caminho, 'o arquivo tem de estar dentro da pasta do projeto'));
+    }
+    if (!fs.existsSync(cheio)) problemas.push(erro(caminho, `o arquivo "${src}" não existe na pasta do projeto`));
+}
+
+function conferirElemento(caminho, el, pasta, problemas, duracao) {
+    if (!el || typeof el !== 'object') return problemas.push(erro(caminho, 'cada elemento é um objeto'));
+    if (!TIPOS.has(el.tipo)) {
+        return problemas.push(erro(caminho, `tipo "${el.tipo}" não existe — use ${[...TIPOS].join(', ')}`));
+    }
+
+    for (const p of ['x', 'y', 'largura', 'altura']) {
+        if (el[p] != null && !medida(el[p])) {
+            problemas.push(erro(`${caminho}.${p}`, `"${el[p]}" não é medida — número, "50%" ou "120px"`));
+        }
+    }
+    conferirCor(`${caminho}.cor`, el.cor, problemas);
+    conferirCor(`${caminho}.fundo`, el.fundo, problemas);
+    conferirAnima(`${caminho}.anima`, el.anima, problemas);
+
+    // `de` e `ate` recortam o elemento no tempo DA CENA. Um elemento que
+    // entra depois de a cena acabar é trabalho jogado fora, e ninguém vê.
+    if (el.de != null && el.ate != null && Number(el.de) >= Number(el.ate)) {
+        problemas.push(erro(caminho, '"de" precisa ser menor que "ate"'));
+    }
+    if (el.de != null && duracao && Number(el.de) >= duracao) {
+        problemas.push(erro(caminho, `este elemento entra em ${el.de}s, mas a cena acaba em ${duracao}s`));
+    }
+
+    switch (el.tipo) {
+        case 'texto':
+            if (!String(el.texto || '').trim()) problemas.push(erro(caminho, 'texto vazio'));
+            // Texto de exemplo entregue como conteúdo é a falha que mais
+            // passa despercebida: o vídeo fica lindo e não diz nada.
+            if (/lorem ipsum|\[inserir|texto aqui|seu texto/i.test(String(el.texto || ''))) {
+                problemas.push(erro(caminho, 'isto é texto de exemplo — escreva o conteúdo de verdade'));
+            }
+            break;
+        case 'forma':
+            if (el.forma && !FORMAS.has(el.forma)) {
+                problemas.push(erro(`${caminho}.forma`, `forma "${el.forma}" não existe — ${[...FORMAS].join(', ')}`));
+            }
+            break;
+        case 'imagem':
+        case 'video':
+            conferirArquivo(`${caminho}.src`, el.src, pasta, problemas);
+            if (el.ajuste && !AJUSTES.has(el.ajuste)) {
+                problemas.push(erro(`${caminho}.ajuste`, `use ${[...AJUSTES].join(', ')}`));
+            }
+            break;
+        case 'icone':
+            // O nome do ícone é "coleção:nome" (ver estudio/assets.js). Sem a
+            // coleção não dá para buscar, e o ícone some do vídeo sem aviso.
+            if (!/^[a-z0-9-]+:[a-z0-9-]+$/i.test(String(el.nome || ''))) {
+                problemas.push(erro(`${caminho}.nome`,
+                    'o ícone é "coleção:nome", como "lucide:zap" ou "simple-icons:pix"'));
+            }
+            break;
+        case 'legenda':
+            if (!Array.isArray(el.fala) || !el.fala.length) {
+                problemas.push(erro(caminho, 'a legenda precisa da lista de falas com tempo'));
+            }
+            break;
+        case 'componente':
+            // A válvula de escape: um arquivo React escrito pela própria IA.
+            conferirArquivo(`${caminho}.src`, el.src, pasta, problemas);
+            break;
+    }
+}
+
+function conferirFundo(caminho, fundo, pasta, problemas) {
+    if (fundo == null) return;
+    if (typeof fundo === 'string') return conferirCor(caminho, fundo, problemas);
+    if (typeof fundo !== 'object') return problemas.push(erro(caminho, 'fundo é uma cor ou um objeto'));
+    if (fundo.tipo === 'cor') return conferirCor(`${caminho}.valor`, fundo.valor, problemas);
+    if (fundo.tipo === 'gradiente') {
+        if (!Array.isArray(fundo.cores) || fundo.cores.length < 2) {
+            problemas.push(erro(`${caminho}.cores`, 'um gradiente tem pelo menos duas cores'));
+        } else fundo.cores.forEach((cor, i) => conferirCor(`${caminho}.cores[${i}]`, cor, problemas));
+        return;
+    }
+    if (fundo.tipo === 'imagem' || fundo.tipo === 'video') {
+        return conferirArquivo(`${caminho}.src`, fundo.src, pasta, problemas);
+    }
+    problemas.push(erro(caminho, 'fundo.tipo é cor, gradiente, imagem ou video'));
+}
+
+/**
+ * Confere o plano inteiro.
+ *
+ * @returns {{ok: boolean, problemas: Array, duracao: number}}
+ */
+function conferir(plano, { pasta = null } = {}) {
+    const problemas = [];
+    if (!plano || typeof plano !== 'object') {
+        return { ok: false, problemas: [erro('plano', 'o plano é um objeto JSON')], duracao: 0 };
+    }
+
+    const f = plano.formato || {};
+    const largura = Number(f.largura) || 1920;
+    const altura = Number(f.altura) || 1080;
+    const fps = Number(f.fps) || 30;
+    if (largura < 64 || altura < 64) problemas.push(erro('formato', 'largura e altura em pixels'));
+    if (fps < 1 || fps > 120) problemas.push(erro('formato.fps', 'fps entre 1 e 120'));
+
+    if (!Array.isArray(plano.cenas) || !plano.cenas.length) {
+        problemas.push(erro('cenas', 'o plano precisa de pelo menos uma cena'));
+        return { ok: false, problemas, duracao: 0 };
+    }
+
+    let duracao = 0;
+    plano.cenas.forEach((cena, i) => {
+        const onde = `cenas[${i}]`;
+        if (!cena || typeof cena !== 'object') return problemas.push(erro(onde, 'cada cena é um objeto'));
+
+        const d = Number(cena.duracao);
+        if (!Number.isFinite(d) || d <= 0) {
+            problemas.push(erro(`${onde}.duracao`, 'a cena precisa de duração em segundos'));
+        } else if (d > 120) {
+            problemas.push(erro(`${onde}.duracao`, `${d}s numa cena só — divida, ou o espectador sai antes`));
+        } else duracao += d;
+
+        conferirFundo(`${onde}.fundo`, cena.fundo, pasta, problemas);
+        conferirAnima(`${onde}.camera`, cena.camera, problemas, ANIMAVEIS_CAMERA);
+
+        if (cena.transicao) {
+            const t = cena.transicao.tipo || cena.transicao;
+            if (!TRANSICOES.has(t)) {
+                problemas.push(erro(`${onde}.transicao`, `transição "${t}" não existe — ${[...TRANSICOES].join(', ')}`));
+            }
+        }
+
+        const elementos = cena.elementos || [];
+        if (!Array.isArray(elementos)) problemas.push(erro(`${onde}.elementos`, 'elementos é uma lista'));
+        else elementos.forEach((el, k) => conferirElemento(`${onde}.elementos[${k}]`, el, pasta, problemas, d));
+    });
+
+    const audio = plano.audio || {};
+    if (audio.narracao) conferirArquivo('audio.narracao', audio.narracao, pasta, problemas);
+    if (audio.trilha) conferirArquivo('audio.trilha.src', audio.trilha.src || audio.trilha, pasta, problemas);
+    for (const [i, e] of (audio.efeitos || []).entries()) {
+        conferirArquivo(`audio.efeitos[${i}].src`, e && e.src, pasta, problemas);
+    }
+
+    return { ok: problemas.length === 0, problemas, duracao: Number(duracao.toFixed(3)) };
+}
+
+/** Quantos quadros dura o vídeo inteiro. Uma conta, num lugar só. */
+function quadros(plano) {
+    const fps = Number((plano.formato || {}).fps) || 30;
+    const segundos = (plano.cenas || []).reduce((n, c) => n + (Number(c.duracao) || 0), 0);
+    return Math.max(1, Math.round(segundos * fps));
+}
+
+/** O que existe no plano, em texto curto — para o agente se situar sem reler tudo. */
+function resumo(plano) {
+    if (!plano || !Array.isArray(plano.cenas)) return 'plano vazio';
+    const f = plano.formato || {};
+    const linhas = [`${plano.cenas.length} cenas · ${(f.largura || 1920)}×${(f.altura || 1080)} · ${(f.fps || 30)}fps`];
+    plano.cenas.forEach((cena, i) => {
+        const tipos = {};
+        for (const el of cena.elementos || []) tipos[el.tipo] = (tipos[el.tipo] || 0) + 1;
+        const conteudo = (cena.elementos || [])
+            .filter((el) => el.tipo === 'texto')
+            .map((el) => String(el.texto).replace(/\s+/g, ' ').slice(0, 40))
+            .join(' / ');
+        linhas.push(`  ${i + 1}. ${cena.duracao}s`
+            + (Object.keys(tipos).length ? ` · ${Object.entries(tipos).map(([t, n]) => `${n} ${t}`).join(', ')}` : '')
+            + (conteudo ? ` · "${conteudo}"` : ''));
+    });
+    return linhas.join('\n');
+}
+
+module.exports = {
+    conferir, quadros, resumo,
+    TIPOS, FORMAS, ANIMAVEIS, ANIMAVEIS_CAMERA, SUAVIZACOES, TRANSICOES, AJUSTES,
+};

package/lib/estudio/projeto.js

@@ -0,0 +1,246 @@
+/**
+ * projeto.js — cada vídeo é uma pasta, e ela não some.
+ *
+ *   "Memória de projetos: todos os vídeos gerados ficam salvos. Semanas depois
+ *    eu posso dizer 'não gostei de tal parte daquele vídeo' e a IA precisa
+ *    localizar o projeto, lembrar o que fez e editar aquele trecho."
+ *
+ * ── O QUE MUDOU DE VERDADE ───────────────────────────────────────────────
+ * O Studio antigo guardava as peças dentro de um servidor Python, num
+ * `arquivos/` com id numérico, e o "histórico" era uma lista de versões do
+ * documento JSON. Duas coisas não funcionavam ali:
+ *
+ *   · para achar "aquele vídeo do PicPay de três semanas atrás" era preciso
+ *     saber o id; e
+ *   · o que ficava guardado era o RESULTADO, não as decisões. Reabrir um
+ *     projeto dizia o que existia, nunca por quê — e sem o porquê, mexer num
+ *     trecho vira refazer do zero.
+ *
+ * Aqui a pasta guarda as duas coisas: o plano (o que é cada cena) e o
+ * caderno (o que foi pedido, o que foi decidido e o que mudou, em ordem).
+ * Semanas depois, "não gostei da parte do cartão" acha o projeto pelo texto,
+ * lê o caderno, e mexe SÓ naquela cena.
+ *
+ * ── POR QUE NÃO HÁ SERVIDOR ──────────────────────────────────────────────
+ * O Studio antigo subia um servidor Python em localhost:7777 e falava com ele
+ * por HTTP. Isso existia porque a interface de edição era uma página web. A
+ * interface morreu — a IA faz tudo e abre o vídeo pronto —, e com ela morre o
+ * servidor. Sobra o que importa: pastas, arquivos e ffmpeg.
+ *
+ * Isso apaga uma classe inteira de defeito. "O estúdio não está rodando na sua
+ * máquina" era uma resposta real que o agente dava, e era um pedido de vídeo
+ * que morria por causa de uma porta ocupada.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const CASA = path.join(os.homedir(), '.primocode', 'studio');
+const PROJETOS = path.join(CASA, 'projetos');
+
+/** Nome de pasta a partir do que a pessoa pediu. */
+function apelidar(bruto) {
+    return String(bruto || '')
+        .normalize('NFD').replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40) || 'projeto';
+}
+
+function agora() { return new Date().toISOString(); }
+
+function garantirCasa() {
+    fs.mkdirSync(PROJETOS, { recursive: true });
+    return PROJETOS;
+}
+
+/**
+ * Abre um projeto novo.
+ *
+ * O id leva a DATA na frente. Não é enfeite: a pasta é listada em ordem
+ * alfabética por quase tudo que lê disco, e com a data na frente essa ordem
+ * já é a cronológica — que é como se procura um vídeo ("o de semana
+ * passada"), não por nome.
+ */
+function criar({ titulo, pedido, formato = 'video' }) {
+    garantirCasa();
+    const dia = new Date().toISOString().slice(0, 10);
+    const base = `${dia}-${apelidar(titulo || pedido)}`;
+    let id = base;
+    let n = 2;
+    while (fs.existsSync(path.join(PROJETOS, id))) { id = `${base}-${n}`; n++; }
+
+    const pasta = path.join(PROJETOS, id);
+    for (const sub of ['midia', 'saida', 'entrada']) {
+        fs.mkdirSync(path.join(pasta, sub), { recursive: true });
+    }
+
+    const meta = {
+        id,
+        titulo: String(titulo || pedido || 'sem título').slice(0, 120),
+        formato,                       // video | slides | arte | documento
+        pedido: String(pedido || ''),
+        criado: agora(),
+        mudado: agora(),
+        renders: [],
+    };
+    escreverJSON(path.join(pasta, 'projeto.json'), meta);
+    anotar(id, 'nasceu', String(pedido || ''));
+    return { ok: true, id, pasta, meta };
+}
+
+function escreverJSON(arquivo, valor) {
+    fs.mkdirSync(path.dirname(arquivo), { recursive: true });
+    fs.writeFileSync(arquivo, JSON.stringify(valor, null, 2), 'utf8');
+}
+
+function lerJSON(arquivo, padrao = null) {
+    try { return JSON.parse(fs.readFileSync(arquivo, 'utf8')); } catch { return padrao; }
+}
+
+const pastaDe = (id) => path.join(PROJETOS, id);
+
+/** O meta de um projeto, ou null. */
+function ler(id) {
+    const meta = lerJSON(path.join(pastaDe(id), 'projeto.json'));
+    if (!meta) return null;
+    return { ...meta, pasta: pastaDe(id) };
+}
+
+function salvar(id, mudancas) {
+    const meta = ler(id);
+    if (!meta) return { ok: false, error: `Projeto "${id}" não existe.` };
+    const novo = { ...meta, ...mudancas, id, mudado: agora() };
+    delete novo.pasta;
+    escreverJSON(path.join(pastaDe(id), 'projeto.json'), novo);
+    return { ok: true, meta: { ...novo, pasta: pastaDe(id) } };
+}
+
+/** Todos, do mais novo para o mais velho. */
+function listar({ limite = 50 } = {}) {
+    garantirCasa();
+    let nomes = [];
+    try {
+        nomes = fs.readdirSync(PROJETOS, { withFileTypes: true })
+            .filter((d) => d.isDirectory()).map((d) => d.name).sort().reverse();
+    } catch { return []; }
+    return nomes.slice(0, limite).map(ler).filter(Boolean);
+}
+
+// ── o caderno ────────────────────────────────────────────────────────────
+
+/**
+ * O que foi pedido, decidido e mudado — em ordem, uma linha por evento.
+ *
+ * Guardado como texto (JSONL), não como JSON de uma lista só: um caderno
+ * cresce sempre, e reescrever o arquivo inteiro a cada anotação é como se
+ * perde um caderno quando o processo morre no meio.
+ */
+function anotar(id, tipo, texto, extra = {}) {
+    const linha = JSON.stringify({ quando: agora(), tipo, texto: String(texto || ''), ...extra });
+    try {
+        fs.mkdirSync(pastaDe(id), { recursive: true });
+        fs.appendFileSync(path.join(pastaDe(id), 'caderno.jsonl'), linha + '\n', 'utf8');
+        return true;
+    } catch { return false; }
+}
+
+function caderno(id, { ultimas = 40 } = {}) {
+    let bruto = '';
+    try { bruto = fs.readFileSync(path.join(pastaDe(id), 'caderno.jsonl'), 'utf8'); } catch { return []; }
+    const linhas = bruto.split('\n').filter(Boolean).slice(-ultimas);
+    return linhas.map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+// ── achar de novo ────────────────────────────────────────────────────────
+
+const semAcento = (v) => String(v || '').toLowerCase()
+    .normalize('NFD').replace(/[̀-ͯ]/g, '');
+
+/**
+ * Acha o projeto pelo que a pessoa lembra.
+ *
+ * Ela não lembra do id. Ela diz "o vídeo do PicPay", "aquele do olho", "o de
+ * semana passada". Então a busca olha título, pedido e o CADERNO inteiro —
+ * porque o que ela lembra costuma ser um detalhe do meio do processo ("aquele
+ * com o cartão passando"), que nunca esteve no título.
+ *
+ * Empate desempata pelo mais novo: quem diz "aquele vídeo" quase sempre fala
+ * do último.
+ */
+function procurar(texto, { limite = 5 } = {}) {
+    const termos = semAcento(texto).split(/\s+/).filter((t) => t.length >= 3);
+    if (!termos.length) return listar({ limite });
+
+    const pontuados = listar({ limite: 200 }).map((p) => {
+        const palha = semAcento([
+            p.titulo, p.pedido,
+            ...caderno(p.id, { ultimas: 200 }).map((e) => e.texto),
+        ].join(' '));
+        let pontos = 0;
+        for (const t of termos) if (palha.includes(t)) pontos++;
+        return { projeto: p, pontos };
+    }).filter((x) => x.pontos > 0);
+
+    pontuados.sort((a, b) => b.pontos - a.pontos || (a.projeto.id < b.projeto.id ? 1 : -1));
+    return pontuados.slice(0, limite).map((x) => x.projeto);
+}
+
+// ── o plano ──────────────────────────────────────────────────────────────
+
+const planoDe = (id) => path.join(pastaDe(id), 'plano.json');
+
+function lerPlano(id) { return lerJSON(planoDe(id)); }
+
+/**
+ * Grava o plano e guarda a versão anterior.
+ *
+ * As versões existem para "volta como estava antes" e para o caso de uma
+ * edição pontual estragar o resto. Elas são numeradas e ficam em `versoes/`;
+ * nada é sobrescrito sem uma cópia ficar para trás.
+ */
+function salvarPlano(id, plano, motivo = '') {
+    const anterior = lerPlano(id);
+    if (anterior) {
+        const versoes = path.join(pastaDe(id), 'versoes');
+        fs.mkdirSync(versoes, { recursive: true });
+        const n = fs.readdirSync(versoes).filter((f) => f.endsWith('.json')).length + 1;
+        escreverJSON(path.join(versoes, `${String(n).padStart(3, '0')}.json`), anterior);
+    }
+    escreverJSON(planoDe(id), plano);
+    anotar(id, 'plano', motivo || 'plano atualizado', { cenas: (plano.cenas || []).length });
+    return { ok: true };
+}
+
+function versoes(id) {
+    const dir = path.join(pastaDe(id), 'versoes');
+    try { return fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort(); } catch { return []; }
+}
+
+function voltarPara(id, versao) {
+    const arquivo = path.join(pastaDe(id), 'versoes', versao);
+    const plano = lerJSON(arquivo);
+    if (!plano) return { ok: false, error: `Versão "${versao}" não existe.` };
+    salvarPlano(id, plano, `voltou para a versão ${versao}`);
+    return { ok: true, plano };
+}
+
+/** Onde guardar uma mídia baixada, com nome que não colide. */
+function caminhoDeMidia(id, nome) {
+    const limpo = String(nome || 'arquivo').replace(/[^\w.-]+/g, '-').slice(-60);
+    const marca = crypto.randomBytes(3).toString('hex');
+    return path.join(pastaDe(id), 'midia', `${marca}-${limpo}`);
+}
+
+module.exports = {
+    CASA, PROJETOS,
+    criar, ler, salvar, listar, procurar, pastaDe, apelidar,
+    anotar, caderno,
+    lerPlano, salvarPlano, versoes, voltarPara,
+    caminhoDeMidia, escreverJSON, lerJSON,
+};