primocode 10.17.1 → 11.0.0

package/lib/entregaveis/slides.js

@@ -0,0 +1,221 @@
+/**
+ * slides.js — o deck de ponta a ponta: plano → conferência numérica → .pptx + PDF.
+ *
+ * O MODELO escreve o plano (JSON): brief, direção de arte e os slides. Este
+ * arquivo NÃO escolhe cor nem texto. Ele (1) confere o plano com números,
+ * (2) desenha o mesmo plano em duas saídas: .pptx editável (pptxgenjs, MIT)
+ * e PDF (HTML → Chrome sem cabeça).
+ *
+ * Os layouts abaixo são GEOMETRIA (onde cabe o quê), não estilo: cor, fonte e
+ * conceito vêm sempre da direção que a IA escolheu para aquele assunto.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const nucleo = require('./nucleo');
+
+const LARGURA = 13.333; const ALTURA = 7.5; // polegadas, 16:9
+const PX = 144; // 13.333 pol * 144 = 1920 px
+
+/** Geometria por layout: caixas em polegadas e tamanho da letra em pt. */
+const LAYOUTS = {
+    capa: { titulo: { x: 0.8, y: 1.5, w: 11.7, h: 3.6, pt: 80 }, sub: { x: 0.8, y: 5.3, w: 11.7, h: 1.2, pt: 28 } },
+    gigante: { titulo: { x: 0.8, y: 0.9, w: 11.7, h: 3.6, pt: 66 }, corpo: { x: 0.8, y: 4.7, w: 11.7, h: 2.2, pt: 28 } },
+    numero: { numero: { x: 0.6, y: 1.0, w: 6.4, h: 4.6, pt: 190 }, titulo: { x: 7.2, y: 1.6, w: 5.5, h: 2.6, pt: 40 }, corpo: { x: 7.2, y: 4.3, w: 5.5, h: 2.4, pt: 26 } },
+    colunas: { titulo: { x: 0.8, y: 0.6, w: 11.7, h: 1.4, pt: 40 }, col1: { x: 0.8, y: 2.3, w: 5.6, h: 4.2, pt: 26 }, col2: { x: 6.9, y: 2.3, w: 5.6, h: 4.2, pt: 26 } },
+    citacao: { citacao: { x: 1.3, y: 1.4, w: 10.7, h: 3.9, pt: 44 }, autor: { x: 1.3, y: 5.6, w: 10.7, h: 0.8, pt: 24 } },
+    lista: { titulo: { x: 0.8, y: 0.6, w: 11.7, h: 1.4, pt: 44 }, corpo: { x: 0.8, y: 2.3, w: 11.7, h: 4.4, pt: 28 } },
+    divisor: { titulo: { x: 0.8, y: 2.4, w: 11.7, h: 2.4, pt: 60 } },
+    fechamento: { titulo: { x: 0.8, y: 1.2, w: 11.7, h: 3.0, pt: 64 }, acao: { x: 0.8, y: 4.8, w: 11.7, h: 1.4, pt: 34 } },
+};
+const NOMES_LAYOUT = Object.keys(LAYOUTS);
+
+/** Cabe o texto na caixa? Estimativa conservadora (0,52 em por letra, entrelinha 1,2). */
+function cabe(texto, pt, wIn, hIn) {
+    const t = String(texto || '');
+    if (!t) return true;
+    const porLinha = Math.max(1, Math.floor((wIn * 72) / (pt * 0.52)));
+    let linhas = 0;
+    for (const par of t.split('\n')) linhas += Math.max(1, Math.ceil(par.length / porLinha));
+    return linhas * pt * 1.2 / 72 <= hIn;
+}
+
+function itens(s) { return Array.isArray(s.corpo) ? s.corpo : (s.corpo ? [String(s.corpo)] : []); }
+
+function textoDoSlide(s) {
+    return [s.titulo, s.subtitulo, s.numero, s.legenda, s.citacao, s.autor, s.acao, ...itens(s)].filter(Boolean).join(' ');
+}
+
+const REGRAS = [
+    { id: 'tamanho-do-deck', peso: 10, testa: (p) => (p.slides.length < 5 || p.slides.length > 20) ? [{ msg: `${p.slides.length} slides: o deck tem de ter entre 5 e 20` }] : [] },
+    { id: 'layout-valido', peso: 10, bloqueia: true, testa: (p) => p.slides.flatMap((s, i) => NOMES_LAYOUT.includes(s.layout) ? [] : [{ slide: i + 1, msg: `layout "${s.layout}" não existe (${NOMES_LAYOUT.join(', ')})` }]) },
+    { id: 'palavras-por-slide', peso: 15, testa: (p) => p.slides.flatMap((s, i) => {
+        const max = ['capa', 'divisor', 'fechamento', 'numero', 'citacao'].includes(s.layout) ? 30 : 40;
+        const n = nucleo.palavras(textoDoSlide(s));
+        return n > max ? [{ slide: i + 1, msg: `${n} palavras (máx ${max}): corte ou divida em dois slides` }] : [];
+    }) },
+    { id: 'titulo-afirmacao', peso: 10, testa: (p) => p.slides.flatMap((s, i) => {
+        if (s.layout === 'citacao' || s.layout === 'divisor' || s.layout === 'numero') return [];
+        const n = nucleo.palavras(s.titulo);
+        return n < 3 ? [{ slide: i + 1, msg: `título com ${n} palavra(s): escreva a afirmação (3 a 12 palavras), não o tema` }]
+            : n > 12 ? [{ slide: i + 1, msg: `título com ${n} palavras (máx 12)` }] : [];
+    }) },
+    { id: 'uma-ideia', peso: 10, testa: (p) => p.slides.flatMap((s, i) => {
+        const it = itens(s); const out = [];
+        if (it.length > 4) out.push({ slide: i + 1, msg: `${it.length} itens (máx 4): uma ideia por slide` });
+        it.forEach((x) => { if (nucleo.palavras(x) > 14) out.push({ slide: i + 1, msg: `item com ${nucleo.palavras(x)} palavras (máx 14): "${String(x).slice(0, 30)}…"` }); });
+        return out;
+    }) },
+    { id: 'layout-repetido', peso: 15, testa: (p) => p.slides.flatMap((s, i) => (i && s.layout === p.slides[i - 1].layout) ? [{ slide: i + 1, msg: `layout "${s.layout}" igual ao slide anterior` }] : []) },
+    { id: 'variedade', peso: 10, testa: (p) => {
+        const n = p.slides.length; const dist = new Set(p.slides.map((s) => s.layout)).size; const meta = Math.min(4, Math.ceil(n / 2));
+        return n >= 6 && dist < meta ? [{ msg: `${dist} layouts diferentes em ${n} slides (mínimo ${meta})` }] : [];
+    } },
+    { id: 'abertura-e-fim', peso: 10, testa: (p) => {
+        const f = []; const a = p.slides[0]; const z = p.slides[p.slides.length - 1];
+        if (!a || a.layout !== 'capa') f.push({ slide: 1, msg: 'o primeiro slide tem de ser a capa' });
+        if (!z || z.layout !== 'fechamento') f.push({ slide: p.slides.length, msg: 'o último slide tem de ser o fechamento' });
+        else if (nucleo.palavras(z.acao) < 2) f.push({ slide: p.slides.length, msg: 'o fechamento precisa de uma ação (campo "acao"): o que o público faz agora' });
+        return f;
+    } },
+    { id: 'notas-do-orador', peso: 5, testa: (p) => p.slides.flatMap((s, i) => (s.layout === 'divisor' || nucleo.palavras(s.nota) >= 8) ? [] : [{ slide: i + 1, msg: 'sem nota do orador (mín 8 palavras): o texto do slide é o que se lê, a fala vai na nota' }]) },
+    { id: 'tamanho-da-letra', peso: 10, bloqueia: true, testa: (p) => {
+        const t = (p.direcao || {}).tamanhoCorpo || 28;
+        return t < 24 ? [{ msg: `corpo com ${t}pt (mín 24pt): lê-se de longe` }] : [];
+    } },
+    { id: 'encaixe', peso: 10, bloqueia: true, testa: (p) => p.slides.flatMap((s, i) => {
+        const g = LAYOUTS[s.layout]; if (!g) return [];
+        const mapa = { titulo: s.titulo, sub: s.subtitulo, numero: s.numero, citacao: s.citacao, autor: s.autor, acao: s.acao,
+            corpo: itens(s).join('\n'), col1: itens(s).filter((_, k) => k % 2 === 0).join('\n'), col2: itens(s).filter((_, k) => k % 2 === 1).join('\n') };
+        return Object.keys(g).filter((k) => mapa[k] && !cabe(mapa[k], g[k].pt, g[k].w, g[k].h))
+            .map((k) => ({ slide: i + 1, msg: `${k} não cabe na caixa (${g[k].pt}pt em ${g[k].w}x${g[k].h} pol): encurte` }));
+    }) },
+    { id: 'visual-com-motivo', peso: 10, testa: (p) => p.slides.flatMap((s, i) => (s.visual && nucleo.palavras(s.visual.motivo) < 4)
+        ? [{ slide: i + 1, msg: 'visual sem "motivo": todo elemento tem de ter a ver com o conteúdo do slide' }] : []) },
+    { id: 'direcao-de-arte', peso: 15, bloqueia: true, testa: (p) => nucleo.conferirDirecao(p.direcao).map((f) => ({ msg: f.msg })) },
+];
+
+/** Confere o plano. Devolve { nota, falhas, passou }. Plano malformado reprova sem estourar. */
+function conferirDeck(plano, opcoes) {
+    if (!plano || !Array.isArray(plano.slides) || !plano.slides.length) {
+        return { nota: 0, passou: false, falhas: [{ regra: 'plano', msg: 'plano sem slides' }] };
+    }
+    const brief = nucleo.conferirBrief(plano.brief);
+    const r = nucleo.conferir(plano, REGRAS, opcoes);
+    if (!brief.ok) { r.falhas.unshift({ regra: 'brief', msg: `brief sem: ${brief.faltam.join(', ')}` }); r.nota = Math.max(0, r.nota - 10); r.passou = false; }
+    return r;
+}
+
+/** Resumo para o agente ler e consertar: uma linha por falha. */
+function relatorio(r) {
+    const linhas = r.falhas.map((f) => `- [${f.regra}]${f.slide ? ` slide ${f.slide}:` : ''} ${f.msg}`);
+    return `nota ${r.nota}/100 — ${r.passou ? 'PASSOU' : 'REPROVADO'}${linhas.length ? '\n' + linhas.join('\n') : ''}`;
+}
+
+// ───────────────────────── .pptx editável ─────────────────────────
+
+const semHash = (c) => String(c).replace('#', '').toUpperCase();
+
+async function gerarPptx(plano, destino) {
+    const PptxGenJS = require('../../vendor/pptxgenjs/carregar.js');
+    const pptx = new PptxGenJS();
+    pptx.defineLayout({ name: 'W169', width: LARGURA, height: ALTURA });
+    pptx.layout = 'W169';
+    pptx.title = (plano.brief || {}).tema || 'Apresentação';
+    pptx.author = 'PrimoCode';
+    const d = plano.direcao; const c = d.paleta;
+    const fundo = semHash(c.fundo); const texto = semHash(c.texto); const dest = semHash(c.destaque);
+    const suave = semHash(c.suave || c.texto);
+    const T = (s, caixa, extra) => s.addText(extra.text, { x: caixa.x, y: caixa.y, w: caixa.w, h: caixa.h, fontSize: caixa.pt,
+        fontFace: extra.face || d.fonteCorpo, color: extra.color || texto, bold: !!extra.bold, italic: !!extra.italic,
+        valign: extra.valign || 'top', margin: 0, fit: 'none', align: extra.align || 'left', lineSpacingMultiple: extra.ls || 1 });
+    plano.slides.forEach((sl) => {
+        const s = pptx.addSlide();
+        s.background = { color: fundo };
+        const g = LAYOUTS[sl.layout];
+        // Cada layout carrega UM gesto visual feito só de forma + cor da direção.
+        if (sl.layout === 'capa') s.addShape('rect', { x: 0, y: 0, w: 0.35, h: ALTURA, fill: { color: dest }, line: { color: dest, width: 0 } });
+        if (sl.layout === 'gigante') s.addShape('rect', { x: 0.8, y: 0.5, w: 1.6, h: 0.12, fill: { color: dest }, line: { color: dest, width: 0 } });
+        if (sl.layout === 'numero') s.addShape('rect', { x: 7.0, y: 1.2, w: 0.06, h: 5.2, fill: { color: dest }, line: { color: dest, width: 0 } });
+        if (sl.layout === 'divisor') s.addShape('rect', { x: 0, y: 0, w: LARGURA, h: ALTURA, fill: { color: dest }, line: { color: dest, width: 0 } });
+        if (sl.layout === 'fechamento') s.addShape('rect', { x: 0.8, y: 4.55, w: 3, h: 0.1, fill: { color: dest }, line: { color: dest, width: 0 } });
+        if (sl.visual && sl.visual.imagem && fs.existsSync(sl.visual.imagem)) {
+            s.addImage({ path: sl.visual.imagem, x: 9.0, y: 4.6, w: 3.8, h: 2.6, sizing: { type: 'cover', w: 3.8, h: 2.6 } });
+        }
+        const sobreDestaque = sl.layout === 'divisor' ? { color: fundo } : {};
+        if (sl.layout === 'capa') { T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true, color: texto, valign: 'bottom', ls: 0.9 }); if (sl.subtitulo) T(s, g.sub, { text: sl.subtitulo, color: dest }); }
+        else if (sl.layout === 'gigante') { T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true, color: dest, ls: 0.9 }); if (itens(sl).length) T(s, g.corpo, { text: itens(sl).join('\n') }); }
+        else if (sl.layout === 'numero') { T(s, g.numero, { text: sl.numero, face: d.fonteTitulo, bold: true, color: dest, valign: 'middle' }); T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true }); if (sl.legenda || itens(sl).length) T(s, g.corpo, { text: sl.legenda || itens(sl).join('\n'), color: suave }); }
+        else if (sl.layout === 'colunas') { T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true }); T(s, g.col1, { text: itens(sl).filter((_, k) => k % 2 === 0).join('\n') }); T(s, g.col2, { text: itens(sl).filter((_, k) => k % 2 === 1).join('\n') }); }
+        else if (sl.layout === 'citacao') { T(s, g.citacao, { text: '“' + sl.citacao + '”', face: d.fonteTitulo, italic: true, color: dest, valign: 'middle' }); if (sl.autor) T(s, g.autor, { text: '— ' + sl.autor, color: suave }); }
+        else if (sl.layout === 'lista') { T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true }); s.addText(itens(sl).map((t) => ({ text: t, options: { bullet: { code: '25A0', color: dest }, breakLine: true, paraSpaceAfter: 10 } })), { x: g.corpo.x, y: g.corpo.y, w: g.corpo.w, h: g.corpo.h, fontSize: g.corpo.pt, fontFace: d.fonteCorpo, color: texto, margin: 0, valign: 'top', fit: 'none' }); }
+        else if (sl.layout === 'divisor') T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true, color: sobreDestaque.color, valign: 'middle' });
+        else if (sl.layout === 'fechamento') { T(s, g.titulo, { text: sl.titulo, face: d.fonteTitulo, bold: true, valign: 'bottom', ls: 0.9 }); T(s, g.acao, { text: sl.acao, color: dest, bold: true }); }
+        if (sl.nota) s.addNotes(sl.nota);
+    });
+    await pptx.writeFile({ fileName: destino });
+    return destino;
+}
+
+// ───────────────────────── HTML → PDF ─────────────────────────
+
+const esc = (t) => String(t == null ? '' : t).replace(/[&<>"]/g, (m) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[m]));
+const px = (pol) => Math.round(pol * PX) + 'px';
+const pt2px = (pt) => Math.round(pt * PX / 72) + 'px';
+
+function gerarHtml(plano) {
+    const d = plano.direcao; const c = d.paleta;
+    const dest2 = c.destaque2 || c.destaque;
+    const caixa = (g, extra = '') => `position:absolute;left:${px(g.x)};top:${px(g.y)};width:${px(g.w)};height:${px(g.h)};font-size:${pt2px(g.pt)};${extra}`;
+    const grad = `color:${c.destaque};`; // o degradê vai no <span> interno (ver gradiente)
+    // background-clip:text vira retângulo cheio no print-to-pdf do Chrome (visto em 29/10): título gigante sai em cor sólida; degradê de texto só via SVG (ver entregaveis-proximos.md).
+    const gradiente = `color:${c.destaque}`;
+    const fam = (f) => `'${esc(f)}',system-ui,sans-serif`;
+    const secoes = plano.slides.map((s) => {
+        const g = LAYOUTS[s.layout]; let h = '';
+        const t = (k, txt, extra = '') => {
+            if (!txt) return '';
+            const miolo = esc(txt).replace(/\n/g, '<br>');
+            return `<div style="${caixa(g[k], extra)}">${extra.includes(grad) ? `<span style="${gradiente}">${miolo}</span>` : miolo}</div>`;
+        };
+        if (s.layout === 'capa') h = `<i style="position:absolute;left:0;top:0;width:${px(0.35)};height:100%;background:${c.destaque}"></i>` + t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:800;line-height:.92;display:flex;align-items:flex-end;${grad}`) + t('sub', s.subtitulo, `color:${c.destaque}`);
+        else if (s.layout === 'gigante') h = `<i style="position:absolute;left:${px(0.8)};top:${px(0.5)};width:${px(1.6)};height:${px(0.12)};background:${c.destaque}"></i>` + t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:800;line-height:.92;${grad}`) + t('corpo', itens(s).join('\n'));
+        else if (s.layout === 'numero') h = `<i style="position:absolute;left:${px(7.0)};top:${px(1.2)};width:${px(0.06)};height:${px(5.2)};background:${c.destaque}"></i>` + t('numero', s.numero, `font-family:${fam(d.fonteTitulo)};font-weight:800;line-height:1;display:flex;align-items:center;${grad}`) + t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:700`) + t('corpo', s.legenda || itens(s).join('\n'), `color:${c.suave || c.texto}`);
+        else if (s.layout === 'colunas') h = t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:700`) + t('col1', itens(s).filter((_, k) => k % 2 === 0).join('\n')) + t('col2', itens(s).filter((_, k) => k % 2 === 1).join('\n'));
+        else if (s.layout === 'citacao') h = t('citacao', '“' + s.citacao + '”', `font-family:${fam(d.fonteTitulo)};font-style:italic;display:flex;align-items:center;color:${c.destaque}`) + t('autor', s.autor && '— ' + s.autor, `color:${c.suave || c.texto}`);
+        else if (s.layout === 'lista') h = t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:700`) + `<ul style="${caixa(LAYOUTS.lista.corpo, 'margin:0;padding:0;list-style:none')}">${itens(s).map((x) => `<li style="margin-bottom:${px(0.14)};padding-left:${px(0.5)};position:relative"><b style="position:absolute;left:0;color:${c.destaque}">■</b>${esc(x)}</li>`).join('')}</ul>`;
+        else if (s.layout === 'divisor') h = t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:800;display:flex;align-items:center;color:${c.fundo}`);
+        else if (s.layout === 'fechamento') h = `<i style="position:absolute;left:${px(0.8)};top:${px(4.55)};width:${px(3)};height:${px(0.1)};background:${c.destaque}"></i>` + t('titulo', s.titulo, `font-family:${fam(d.fonteTitulo)};font-weight:800;line-height:.92;display:flex;align-items:flex-end;${grad}`) + t('acao', s.acao, `color:${c.destaque};font-weight:700`);
+        if (s.visual && s.visual.imagem && fs.existsSync(s.visual.imagem)) {
+            const b64 = fs.readFileSync(s.visual.imagem).toString('base64');
+            const ext = path.extname(s.visual.imagem).slice(1).toLowerCase().replace('jpg', 'jpeg');
+            h += `<img alt="" src="data:image/${ext};base64,${b64}" style="position:absolute;left:${px(9)};top:${px(4.6)};width:${px(3.8)};height:${px(2.6)};object-fit:cover">`;
+        }
+        const fundo = s.layout === 'divisor' ? c.destaque : c.fundo;
+        return `<section style="background:${fundo};color:${c.texto};font-family:${fam(d.fonteCorpo)}">${h}</section>`;
+    }).join('\n');
+    return `<!doctype html><html lang="pt-BR"><head><meta charset="utf-8"><title>${esc((plano.brief || {}).tema || 'Apresentação')}</title>
+<style>@page{size:1920px 1080px;margin:0}*{box-sizing:border-box}html,body{margin:0;background:${c.fundo}}
+section{position:relative;width:1920px;height:1080px;overflow:hidden;page-break-after:always;break-after:page;-webkit-print-color-adjust:exact;print-color-adjust:exact}
+section>div{line-height:1.2}</style></head><body>\n${secoes}\n</body></html>`;
+}
+
+/**
+ * Exporta o deck: confere, escreve .pptx, .html e (se houver Chrome) .pdf.
+ * Plano reprovado não exporta, a menos que { forcar: true }.
+ */
+async function exportarDeck(plano, pasta, { forcar = false, pdf = true, nome } = {}) {
+    const resultado = conferirDeck(plano);
+    if (!resultado.passou && !forcar) return { exportado: false, conferencia: resultado, arquivos: [] };
+    fs.mkdirSync(pasta, { recursive: true });
+    const base = path.join(pasta, nome || nucleo.slug((plano.brief || {}).tema || plano.titulo));
+    const arquivos = [];
+    await gerarPptx(plano, base + '.pptx'); arquivos.push(base + '.pptx');
+    fs.writeFileSync(base + '.html', gerarHtml(plano)); arquivos.push(base + '.html');
+    let erroPdf = null;
+    if (pdf) { const r = nucleo.htmlParaPdf(base + '.html', base + '.pdf'); if (r.ok) arquivos.push(base + '.pdf'); else erroPdf = r.erro; }
+    return { exportado: true, conferencia: resultado, arquivos, erroPdf };
+}
+
+module.exports = { LAYOUTS, NOMES_LAYOUT, cabe, conferirDeck, relatorio, gerarPptx, gerarHtml, exportarDeck };

package/lib/entregaveis.js

@@ -0,0 +1,67 @@
+/**
+ * entregaveis.js — o arquivo que o pedido manda gravar tem que existir no fim (26/10).
+ *
+ * Visto num `primocode -p` de verdade: "grave o PLANO.md" e o agente disse
+ * "pronto!" com o PLANO.md sem existir. Quem nunca programou acredita no
+ * "pronto" e só descobre depois.
+ *
+ * `pedidos(texto)` acha os arquivos que o pedido manda CRIAR ou ESCREVER (o
+ * nome vem depois de um verbo de escrever: grave, escreva, crie, salve…). O
+ * que vem depois de um verbo de ler ("leia o README.md", "com base no X.md")
+ * não conta: esse já existe, ou não é o agente que faz. `faltando` diz quais
+ * ainda não estão no disco. Sem modelo, sem rede.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const EXTENSOES = 'md|txt|html?|css|js|mjs|cjs|ts|tsx|jsx|json|py|rb|go|rs|java|sh|ya?ml|toml|csv|sql|xml|svg|php|vue|svelte|ini';
+const ARQUIVO = new RegExp(`^[\\w.~/-]*[\\w-]\\.(?:${EXTENSOES})$`, 'i');
+const ESCREVER = /^(grav[ea]r?|grava|escrev[ae]r?|escreve|cri[ea]r?|cria|ger[ea]r?|gera|salv[ea]r?|salva|fa[çc]a|fazer|faz|mont[ea]r?|monta|write|create|save|generate|make|produce)$/i;
+// Depois destes, o arquivo citado é de LER (ou de editar, que é outra trava).
+const OUTRO = /^(lei?a|ler|l[êe]|abr[ae]|abrir|olh[ae]|olhar|vej?a|ver|use|usar|usando|base|partir|segu[ei]ndo|conforme|edit[ae]r?|mud[ae]r?|alter[ae]r?|apag[ae]r?|remov[ae]r?|read|open|use|using|based|from|edit|update|delete|remove|following)$/i;
+
+/** Os arquivos que o pedido manda criar ou escrever, na ordem, sem repetir. */
+function pedidos(texto) {
+    const achados = [];
+    const frases = String(texto || '').replace(/```[\s\S]*?```/g, ' ').split(/[.!?;\n]+(?=\s|$)/);
+    for (const frase of frases) {
+        let escrevendo = false;
+        for (const cru of frase.split(/\s+/)) {
+            const palavra = cru.replace(/^[("'`[]+|[)"'`\],:]+$/g, '');
+            if (!palavra) continue;
+            if (ESCREVER.test(palavra)) { escrevendo = true; continue; }
+            if (OUTRO.test(palavra)) { escrevendo = false; continue; }
+            if (escrevendo && ARQUIVO.test(palavra) && !/^https?:/i.test(palavra) && !achados.includes(palavra)) achados.push(palavra);
+        }
+    }
+    return achados;
+}
+
+/**
+ * Dos arquivos pedidos, os que não existem. Vale achar na pasta do projeto, ou
+ * um arquivo com o mesmo nome que a tarefa escreveu (ele pôs em docs/PLANO.md).
+ */
+function faltando(texto, pasta, escritos = []) {
+    const mesmoNome = new Set([...escritos].filter((f) => { try { return fs.existsSync(f); } catch { return false; } })
+        .map((f) => path.basename(f).toLowerCase()));
+    return pedidos(texto).filter((nome) => {
+        const caminho = nome.startsWith('~') ? path.join(os.homedir(), nome.slice(1)) : path.resolve(pasta || '.', nome);
+        if (fs.existsSync(caminho)) return false;
+        return !mesmoNome.has(path.basename(nome).toLowerCase());
+    });
+}
+
+/** O recado pro agente, ou null quando não falta nada. */
+function recado(falta) {
+    if (!falta.length) return null;
+    const lista = falta.join(', ');
+    return falta.length === 1
+        ? `o arquivo ${lista} ainda não existe. O pedido manda gravar esse arquivo: crie ele agora (write_file) e finalize de novo. Se não der, diga em uma frase por quê.`
+        : `os arquivos ${lista} ainda não existem. O pedido manda gravar esses arquivos: crie eles agora (write_file) e finalize de novo. Se não der, diga em uma frase por quê.`;
+}
+
+module.exports = { pedidos, faltando, recado };

package/lib/escopo.js

@@ -0,0 +1,68 @@
+/**
+ * escopo.js — "pedi pra mexer no login.js e ele mexeu em mais três": o aviso, e o "/desfazer fora".
+ *
+ *   citados(pedido)                          → ['login.js', …]          (os arquivos que o pedido nomeia; puro)
+ *   foraDoPedido(pedido, mudou, projectDir)  → [{ caminho, rel, acao }]  (o que o pedido mudou sem ser citado; puro)
+ *   texto(citados, fora)                     → as linhas pro terminal    (puro)
+ *   nota(pedido)                             → o aviso que vai junto do pedido pro agente, ou ''  (puro)
+ *
+ * Fórum do Cursor, maio a agosto de 2026: um pedido de um arquivo mexe em 18 (forum.cursor.com/t/165633 e /161320), e a
+ * única saída que a equipe deles dá é "liste os arquivos permitidos no pedido". Aqui, quando o pedido nomeia arquivo, o
+ * PrimoCode compara com o que o checkpoint do pedido viu mudar (lib/checkpoint.js) e diz o que ficou de fora — sem
+ * modelo. Pedido que não nomeia arquivo nenhum não gera aviso: "melhora o site" pode mexer em tudo.
+ */
+
+'use strict';
+
+const path = require('path');
+
+const EXT = 'html?|css|scss|jsx?|tsx?|mjs|cjs|json|py|rb|go|rs|php|vue|svelte|md|txt|svg|ya?ml|toml|sql|sh';
+const RE = new RegExp(`(?:^|[\\s"'\`(@])((?:\\.{0,2}/)?[\\w\\-./]*\\w\\.(?:${EXT}))(?=$|[\\s"'\`),.;:!?])`, 'gi');
+// o que muda sozinho junto (lockfile) ou é do próprio PrimoCode: nunca conta como "fora"
+const DE_FORA_NUNCA = /(^|\/)(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|PRIMO\.md|memory\.md)$/;
+
+function citados(pedido) {
+    const out = [];
+    for (const m of String(pedido || '').matchAll(RE)) {
+        const c = m[1].replace(/^\.\//, '').toLowerCase();
+        if (/^https?:|^www\./.test(c) || out.includes(c)) continue;
+        out.push(c);
+    }
+    return out;
+}
+
+function foraDoPedido(pedido, mudou, projectDir) {
+    const lista = citados(pedido);
+    if (!lista.length) return [];
+    const bate = (rel) => {
+        const r = rel.toLowerCase();
+        return lista.some((c) => r === c || r.endsWith('/' + c) || (!c.includes('/') && path.basename(r) === c));
+    };
+    return (mudou || [])
+        .map((m) => ({ ...m, rel: path.relative(projectDir, m.caminho).split(path.sep).join('/') }))
+        .filter((m) => m.rel && !m.rel.startsWith('..') && !DE_FORA_NUNCA.test(m.rel) && !bate(m.rel));
+}
+
+const VERBO = { criado: 'criei', mudou: 'mudei', apagado: 'apaguei' };
+
+function texto(lista, fora) {
+    if (!fora.length) return [];
+    const pediu = lista.length === 1 ? lista[0] : lista.slice(0, -1).join(', ') + ' e ' + lista[lista.length - 1];
+    const linhas = [`Você pediu pra mexer em ${pediu}. Eu também mexi em ${fora.length === 1 ? 'outro arquivo' : fora.length + ' outros'}:`];
+    for (const f of fora.slice(0, 8)) linhas.push(`  ${VERBO[f.acao] || 'mudei'} ${f.rel}`);
+    if (fora.length > 8) linhas.push(`  e mais ${fora.length - 8}`);
+    linhas.push(`Se não era pra mexer, /undo fora volta só ${fora.length === 1 ? 'ele' : 'esses'}. O que você pediu fica.`);
+    return linhas;
+}
+
+/** Antes, e não só depois: o agente fica sabendo do escopo junto do pedido. Não proíbe (às vezes o conserto do
+    login.js precisa mesmo do util.js), pede que ele diga o porquê — e o aviso do fim continua de pé. */
+function nota(pedido) {
+    const lista = citados(pedido);
+    if (!lista.length) return '';
+    const quais = lista.slice(0, 6).join(', ');
+    return `\n\nESCOPO: o pedido citou ${quais}. Mexa só ${lista.length === 1 ? 'nele' : 'neles'}. `
+        + 'Se precisar mudar outro arquivo, mude só o necessário e diga na resposta qual e por quê.';
+}
+
+module.exports = { citados, foraDoPedido, texto, nota };

package/lib/especialistas.js

@@ -64,7 +64,7 @@ const ESPECIALISTAS = {
     ambiente: {
         faz: 'instalar dependências, configurar e fazer rodar',
         sinais: /\b(instal\w*|depend[êe]ncias?|npm|pnpm|yarn|pip|uv|brew|apt(-get)?|winget|ffmpeg|configur\w*|ambiente|setup|rodar o projeto|node_modules|docker|venv)\b/gi,
-        briefing: `Você é o especialista em AMBIENTE — dependências, instalação e execução. Descubra o que a máquina tem (node --version, python3 --version, qual gerenciador: npm/pnpm/yarn, pip/uv, brew/apt/winget) antes de mandar instalar; use o gerenciador que o projeto já usa (o lockfile diz). Instale só o que a tarefa pede, com a versão fixada no manifesto (package.json, requirements.txt), nunca global sem motivo. Comando que demora ou fica de pé vai em run_in_new_terminal; o resto em run_shell, lendo a saída inteira — "warning" não é erro, "ERR!" é. Falta algo no sistema (ffmpeg, git, python)? Instale pelo gerenciador do sistema e confira com --version. PROVE: o comando de rodar funcionando, e um LEIA.md com instalar e rodar que qualquer um siga.`,
+        briefing: `Você é o especialista em AMBIENTE — dependências, instalação e execução. Descubra o que a máquina tem (node --version, python3 --version, qual gerenciador: npm/pnpm/yarn, pip/uv, brew/apt/winget) antes de mandar instalar; use o gerenciador que o projeto já usa (o lockfile diz). Instale só o que a tarefa pede, com a versão fixada no manifesto (package.json, requirements.txt), nunca global sem motivo. Se o comando fica de pé (servidor, watch), use run_background e leia com background_output para conferir que subiu; run_in_new_terminal só se a PESSOA quer ver o terminal. O resto em run_shell, lendo a saída inteira — "warning" não é erro, "ERR!" é. Falta algo no sistema (ffmpeg, git, python)? Instale pelo gerenciador do sistema e confira com --version. PROVE: o comando de rodar funcionando, e um LEIA.md com instalar e rodar que qualquer um siga.`,
     },
 };
 

package/lib/estudio/conferencia.js

@@ -18,13 +18,22 @@
  *            imagem dá 6,5 s a 8,3 s ("torrado" parado, a pílula vazia, e
  *            para quando "café" entra), e os vídeos 3D não dão nada.
  *
- * Só mede e avisa. Não conserta nada: quem decide se refaz é o agente.
- * As duas leituras (lerSom, lerParados) são puras e testáveis sem vídeo.
+ *   olho     8 quadros espaçados lidos pelo Vision do macOS (visao.js), em todo caminho (AE, Remotion, Hyperframes):
+ *            texto colado na borda, sobre rosto, encavalado (conferencia-visual) e o contraste de cada texto contra o
+ *            fundo atrás dele, 3:1 no mínimo (regras-motion). Sem o Vision, o olho fica de fora e nada quebra.
+ *
+ * Só mede e avisa (agora também olha). Não conserta nada: quem decide se refaz é o agente.
+ * As leituras (lerSom, lerParados) e o julgamento do olho são puros e testáveis sem vídeo.
  */
 
 'use strict';
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const video = require('./video.js');
+const conferenciaVisual = require('./conferencia-visual.js');
+const regras = require('./regras-motion.js');
 
 const ALVO = { lufs: -14, folgaLufs: 2, picoMax: -1, paradoMin: 2 };
 const r1 = (n) => Math.round(n * 10) / 10;
@@ -79,8 +88,53 @@ function julgar({ som, parados = [] }, alvo = ALVO) {
     return avisos;
 }
 
-/** Mede o arquivo numa passada só do ffmpeg e devolve medidas e avisos. */
-async function conferir(arquivo, { duracao = 0 } = {}) {
+/** Tira `quadros` quadros do vídeo e lê no Vision. `visao` injetável (null = sem olho). Nunca falha: sem olho devolve {olho:'sem'}. */
+async function olhar(arquivo, { duracao = 0, visao, quadros = 8, pasta } = {}) {
+    let V = visao;
+    if (V === undefined) { try { V = require('./visao.js'); } catch { V = null; } }
+    if (!V || !V.disponivel() || !(duracao > 0)) return { olho: 'sem', problemas: [] };
+    const tmp = pasta || fs.mkdtempSync(path.join(os.tmpdir(), 'olho-'));
+    try {
+        const segundos = [], arquivos = [];
+        for (let i = 0; i < quadros; i++) {
+            const s = (i + 0.5) * duracao / quadros, png = path.join(tmp, `q${i}.png`);
+            const q = await video.quadro(arquivo, png, s);
+            if (q.ok) { segundos.push(s); arquivos.push(png); }
+        }
+        const r = arquivos.length ? V.ler(arquivos) : null;
+        if (!r || !r.ok) return { olho: 'sem', problemas: [] };
+        const problemas = [];
+        for (const q of r.quadros) {
+            const i = arquivos.indexOf(q.arquivo);
+            if (i < 0) continue;
+            const seg = r1(segundos[i]);
+            const achados = conferenciaVisual.julgarLeitura(q, i).map((p) => ({ ...p, segundo: seg }));
+            achados.push(...regras.julgarContraste(q, pixels(q.arquivo, 540), { cena: i, segundo: seg }));
+            problemas.push(...achados);
+        }
+        return { olho: 'vision', problemas };
+    } finally {
+        if (!pasta) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* o sistema limpa */ } }
+    }
+}
+
+// carregado na hora: maquina-layout puxa mais coisa, e a medida de som não precisa dele
+function pixels(png, largura) { return require('./maquina-layout.js').pixels(png, largura); }
+
+/** Os problemas do olho viram avisos com o segundo; o mesmo texto e tipo só aparece uma vez (no 1º segundo). */
+function avisosDoOlho(problemas) {
+    const vistos = new Set(), avisos = [];
+    for (const p of problemas) {
+        const chave = `${p.tipo}|${(p.texto.match(/"([^"]*)"/) || [, p.texto])[1]}`;
+        if (vistos.has(chave)) continue;
+        vistos.add(chave);
+        avisos.push(`aos ${String(p.segundo).replace('.', ',')} s: ${p.texto}`);
+    }
+    return avisos;
+}
+
+/** Mede o arquivo numa passada só do ffmpeg, olha os quadros e devolve medidas e avisos. */
+async function conferir(arquivo, { duracao = 0, olho = true, visao } = {}) {
     const c = video.conferir();
     if (!c.ok) return c;
     const r = await video.rodar(video.ffmpeg(), [
@@ -92,7 +146,18 @@ async function conferir(arquivo, { duracao = 0 } = {}) {
     if (!r.ok) return { ok: false, error: `a conferência não leu o vídeo: ${r.erro.slice(-200)}` };
     const som = lerSom(r.erro);
     const parados = lerParados(r.erro, duracao);
-    return { ok: true, som, parados, avisos: julgar({ som, parados }) };
+    const visto = olho ? await olhar(arquivo, { duracao, visao }) : { olho: 'sem', problemas: [] };
+    return { ok: true, som, parados, avisos: [...julgar({ som, parados }), ...avisosDoOlho(visto.problemas)], olho: visto };
+}
+
+/* O que a PESSOA vê no terminal depois do render: os avisos só iam pro modelo, e quem olhava a tela
+   achava que o vídeo tinha saído limpo. Até `max` linhas, o resto vira "e mais N". Pura. */
+function linhasPraPessoa(conf, max = 4) {
+    const av = (conf && Array.isArray(conf.avisos) ? conf.avisos : []).filter(Boolean);
+    if (!av.length) return [];
+    const out = ['a conferência do vídeo pronto achou:', ...av.slice(0, max).map((a) => '· ' + a)];
+    if (av.length > max) out.push(`· e mais ${av.length - max}`);
+    return out;
 }
 
-module.exports = { ALVO, lerSom, lerParados, julgar, conferir };
+module.exports = { ALVO, lerSom, lerParados, julgar, olhar, avisosDoOlho, conferir, linhasPraPessoa };