primocode 10.16.0 → 10.17.0

package/lib/estudio/maquina-foto.js

@@ -0,0 +1,177 @@
+/**
+ * maquina-foto.js — a FOTO que a pessoa manda vira peça do motion (a primitiva "foto" do kit-ae).
+ *
+ * Antes (20/10): a foto do pedido virava só "referência" (cores, em index.js:importarReferencia) e nenhuma primitiva
+ * aceitava imagem: o motion não tinha onde pôr a foto e o pedido travava. Agora, ANTES do render e uma vez só:
+ *
+ *   1. confere o arquivo (formato, tamanho, se abre) e diz o porquê em português quando não serve;
+ *   2. copia para <projeto>/midia/fotos/ (o motion nunca aponta para fora do projeto), já com o lado maior em ≤ 2400 px;
+ *   3. faz o fundo desfocado (o plano de trás do parallax) com o ffmpeg;
+ *   4. tenta o recorte da pessoa: o Vision do macOS primeiro (lib/estudio/visao.js), o MediaPipe (studio/pessoa.py) depois;
+ *      sem pessoa ou sem nenhum dos dois, a foto vai inteira, com moldura arredondada.
+ *
+ *   preparar({fotos, pasta, deps}) → {fotos:[{arquivo, fundo, recorte, w, h, nome, de, moldura}], recusadas:[{arquivo, motivo}]}
+ *
+ * `deps` (injetáveis; testes): sondar(arq) → {w,h}|null, recortar(entrada, saida) → {ok, semPessoa?}, converter(entrada, saida) → bool.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const FORMATOS = ['jpg', 'jpeg', 'png', 'webp', 'heic', 'heif'];
+const MAX_BYTES = 25 * 1024 * 1024;
+const MAX_LADO = 2400;
+const MAX_FOTOS = 6;
+
+const slug = (s) => String(s).normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/gi, '-').toLowerCase().replace(/^-|-$/g, '').slice(0, 30) || 'foto';
+
+function ff(args, timeout = 60000) {
+    const r = spawnSync('ffmpeg', ['-y', '-hide_banner', '-loglevel', 'error', ...args], { encoding: 'utf8', timeout });
+    return r.status === 0;
+}
+
+/** Largura e altura pelo ffprobe (o que o ffmpeg abre, o motion abre). null = não abre. */
+function sondar(arq) {
+    const r = spawnSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height', '-of', 'csv=p=0:s=x', arq], { encoding: 'utf8', timeout: 20000 });
+    const m = r.status === 0 && String(r.stdout).trim().match(/^(\d+)x(\d+)/);
+    return m ? { w: Number(m[1]), h: Number(m[2]) } : null;
+}
+
+/** HEIC/HEIF → JPG: sips (macOS) ou o ffmpeg, se ele leu HEIC. false = sem conversor. */
+function converter(entrada, saida) {
+    if (process.platform === 'darwin') {
+        const r = spawnSync('sips', ['-s', 'format', 'jpeg', entrada, '--out', saida], { encoding: 'utf8', timeout: 60000 });
+        if (r.status === 0 && fs.existsSync(saida)) return true;
+    }
+    return ff(['-i', entrada, '-frames:v', '1', saida]) && fs.existsSync(saida);
+}
+
+function extensao(arq) { return path.extname(String(arq || '')).replace('.', '').toLowerCase(); }
+
+/** Confere uma foto SEM mexer nela. {ok:true, ext, bytes} ou {ok:false, error} (em português, dizendo o que fazer). */
+function validar(arq, { sondar: sd = sondar } = {}) {
+    const nome = path.basename(String(arq || '')) || String(arq || '');
+    if (!arq || typeof arq !== 'string') return { ok: false, error: 'faltou o caminho da foto.' };
+    const ext = extensao(arq);
+    if (!FORMATOS.includes(ext)) {
+        return { ok: false, error: `a foto "${nome}" é ${ext ? '.' + ext : 'de um tipo sem extensão'}: aceito ${FORMATOS.map((f) => '.' + f).join(', ')}. Salve ou exporte como JPG ou PNG e mande de novo.` };
+    }
+    let st;
+    try { st = fs.statSync(arq); } catch { return { ok: false, error: `não achei a foto "${nome}" em ${path.dirname(arq)}. Confira o caminho.` }; }
+    if (!st.isFile()) return { ok: false, error: `"${nome}" não é um arquivo de foto.` };
+    if (st.size === 0) return { ok: false, error: `a foto "${nome}" está vazia (0 bytes).` };
+    if (st.size > MAX_BYTES) return { ok: false, error: `a foto "${nome}" tem ${(st.size / 1048576).toFixed(1)} MB: o máximo é ${MAX_BYTES / 1048576} MB. Reduza o tamanho e mande de novo.` };
+    if (ext !== 'heic' && ext !== 'heif') {
+        const d = sd(arq);
+        if (!d || !(d.w > 0 && d.h > 0)) return { ok: false, error: `não consegui abrir a foto "${nome}": o arquivo está corrompido ou não é uma imagem de verdade. Tente exportar de novo.` };
+        if (d.w < 200 || d.h < 200) return { ok: false, error: `a foto "${nome}" é pequena demais (${d.w}x${d.h}): precisa ter pelo menos 200 px de lado para não ficar borrada no vídeo.` };
+    }
+    return { ok: true, ext, bytes: st.size };
+}
+
+function acharPython() {
+    for (const p of [process.env.PRIMOCODE_PYTHON, 'python3', 'python'].filter(Boolean)) {
+        const r = spawnSync(p, ['--version'], { encoding: 'utf8', timeout: 10000 });
+        if (r.status === 0) return p;
+    }
+    return null;
+}
+
+/** Apara a margem transparente do recorte (o que sobra é a pessoa): grava no próprio arquivo e devolve {w,h}; null se não deu. */
+function aparar(png) {
+    const r = spawnSync('ffmpeg', ['-hide_banner', '-i', png, '-vf', 'alphaextract,cropdetect=limit=24:round=2:skip=0', '-f', 'null', '-'], { encoding: 'utf8', timeout: 60000 });
+    const todos = [...String(r.stderr || '').matchAll(/crop=(\d+):(\d+):(\d+):(\d+)/g)];
+    if (!todos.length) return null;
+    const [, w, h, x, y] = todos[todos.length - 1].map(Number);
+    if (!(w >= 64 && h >= 64)) return null;
+    const tmp = png.replace(/\.png$/, '-aparado.png');
+    if (!ff(['-i', png, '-vf', `crop=${w}:${h}:${x}:${y}`, tmp]) || !fs.existsSync(tmp)) return null;
+    fs.renameSync(tmp, png);
+    return { w, h };
+}
+
+/** O recorte pelo MediaPipe (studio/pessoa.py). {ok:true} | {ok:false, semPessoa?, semMediaPipe?, error}. Nunca lança. */
+function recortarMediaPipe(entrada, saida) {
+    const py = acharPython();
+    if (!py) return { ok: false, error: 'sem Python 3 para o recorte' };
+    const r = spawnSync(py, [path.join(__dirname, '..', '..', 'studio', 'pessoa.py'), 'recortar-foto', '--entrada', entrada, '--saida', saida], { encoding: 'utf8', timeout: 90000 });
+    try { return { ...JSON.parse(String(r.stdout || '').trim().split('\n').pop()), motor: 'mediapipe' }; } catch { return { ok: false, error: String(r.stderr || r.stdout || 'o recorte não respondeu').slice(-200) }; }
+}
+
+/**
+ * O recorte da pessoa, do melhor pro último caso: 1) o Vision do macOS (VNGeneratePersonSegmentationRequest, sem instalar
+ * nada; lib/estudio/visao.js), 2) o MediaPipe (studio/pessoa.py), 3) nenhum → a foto vai inteira, com moldura.
+ * {ok:true, motor} | {ok:false, semPessoa?, error}. Nunca lança. `deps.visao` é injetável (testes).
+ */
+function recortarPessoa(entrada, saida, { visao } = {}) {
+    let V = visao;
+    if (V === undefined) { try { V = require('./visao.js'); } catch { V = null; } }
+    if (V && V.disponivel()) {
+        const r = V.recortar(entrada, saida);
+        if (r && r.ok && fs.existsSync(saida)) return { ok: true, motor: 'vision', cobertura: r.cobertura };
+        if (r && r.semPessoa) return { ok: false, semPessoa: true, motor: 'vision', error: 'sem pessoa na foto' };
+    }
+    return recortarMediaPipe(entrada, saida);
+}
+
+/**
+ * Prepara as fotos do pedido. Nunca lança: o que não serve vai em `recusadas`, com o porquê.
+ * `opc.max` limita quantas entram (padrão 6).
+ */
+async function preparar({ fotos = [], pasta, deps = {}, max = MAX_FOTOS } = {}) {
+    const out = { fotos: [], recusadas: [] };
+    if (!pasta) return { ...out, recusadas: [{ arquivo: '', motivo: 'faltou a pasta do projeto.' }] };
+    const lista = (Array.isArray(fotos) ? fotos : [fotos]).filter(Boolean).map((f) => String(f).replace(/^file:\/\//, ''));
+    const unicas = [...new Set(lista)];
+    const sd = deps.sondar || sondar;
+    const dir = path.join(pasta, 'midia', 'fotos');
+    for (const orig of unicas) {
+        if (out.fotos.length >= max) { out.recusadas.push({ arquivo: orig, motivo: `o motion usa até ${max} fotos: "${path.basename(orig)}" ficou de fora.` }); continue; }
+        const v = validar(orig, { sondar: sd });
+        if (!v.ok) { out.recusadas.push({ arquivo: orig, motivo: v.error }); continue; }
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            const n = out.fotos.length + 1;
+            const base = `foto-${n}-${slug(path.basename(orig, path.extname(orig)))}`;
+            let entrada = orig;
+            if (v.ext === 'heic' || v.ext === 'heif') {
+                const jpgTmp = path.join(dir, base + '-heic.jpg');
+                const ok = (deps.converter || converter)(orig, jpgTmp);
+                if (!ok || !fs.existsSync(jpgTmp)) {
+                    out.recusadas.push({ arquivo: orig, motivo: `a foto "${path.basename(orig)}" é HEIC e esta máquina não tem conversor (no macOS vem o sips; no Windows/Linux, instale o ffmpeg com suporte a HEIC). Exporte como JPG e mande de novo.` });
+                    continue;
+                }
+                entrada = jpgTmp;
+            }
+            // cópia dentro do projeto, no lado máximo de 2400 px (a rotação do EXIF o ffmpeg já aplica)
+            const alvo = path.join(dir, base + (v.ext === 'png' ? '.png' : '.jpg'));
+            const filtro = `scale='if(gt(iw,ih),min(${MAX_LADO},iw),-2)':'if(gt(iw,ih),-2,min(${MAX_LADO},ih))'`;
+            const ok = ff(['-i', entrada, '-frames:v', '1', '-vf', filtro, ...(v.ext === 'png' ? [] : ['-q:v', '2']), alvo]);
+            // sem ffmpeg ou ele recusou: copia como veio (o kit ainda tenta abrir)
+            if (!ok || !fs.existsSync(alvo) || fs.statSync(alvo).size === 0) fs.copyFileSync(entrada, alvo);
+            if (entrada !== orig) fs.rmSync(entrada, { force: true });
+            const dims = sd(alvo);
+            const d = dims || { w: 1080, h: 1080 };
+            // o plano de trás do parallax: pequeno e muito desfocado (o kit amplia)
+            const fundo = path.join(dir, base + '-fundo.jpg');
+            const okF = ff(['-i', alvo, '-frames:v', '1', '-vf', 'scale=480:-2,gblur=sigma=16', '-q:v', '4', fundo]) && fs.existsSync(fundo);
+            // o recorte da pessoa, uma vez; sem pessoa ou sem MediaPipe: foto inteira com moldura
+            let recorte = null, motivoRecorte = null, rdims = null, motorRecorte = null;
+            if (deps.recortar !== false) {
+                const png = path.join(dir, base + '-recorte.png');
+                const rc = await (deps.recortar || ((e, s2) => recortarPessoa(e, s2, { visao: deps.visao })))(alvo, png);
+                if (rc && rc.ok && fs.existsSync(png)) { recorte = png; motorRecorte = rc.motor || null; rdims = (deps.aparar || aparar)(png) || sd(png); }
+                else motivoRecorte = (rc && rc.semPessoa) ? 'sem pessoa na foto' : ((rc && rc.error) || 'sem recorte');
+            }
+            out.fotos.push({ arquivo: alvo, fundo: okF ? fundo : alvo, recorte, w: d.w, h: d.h, nome: path.basename(orig), de: orig, moldura: !recorte, ...(rdims ? { rw: rdims.w, rh: rdims.h } : {}), ...(motorRecorte ? { recorteMotor: motorRecorte } : {}), ...(motivoRecorte ? { semRecorte: motivoRecorte } : {}) });
+        } catch (e) {
+            out.recusadas.push({ arquivo: orig, motivo: `não consegui preparar a foto "${path.basename(orig)}": ${e.message}` });
+        }
+    }
+    return out;
+}
+
+module.exports = { FORMATOS, MAX_BYTES, MAX_LADO, MAX_FOTOS, validar, preparar, sondar, converter, recortarPessoa, recortarMediaPipe, aparar, slug, extensao };

package/lib/estudio/maquina-guarda.js

@@ -0,0 +1,207 @@
+/**
+ * maquina-guarda.js — a GUARDA de layout no Node, ANTES do render.
+ *
+ * As regras e os consertos moram em kit-ae/guarda.jsx (ES3), carregado aqui pelo `vm`: o MESMO código roda no kit (no fecha() de
+ * cada cena, com as caixas reais do After Effects) e aqui (sobre o plano, com a largura medida da fonte). Uma fonte da verdade.
+ *
+ *   medirTexto(str, {fonte, peso, tamanho})          → largura em px (avanços do .ttf do cache; sem a fonte, estimativa)
+ *   blocoTexto(str, opc, pl)                          → {w, h, tam, linhas}: a mesma quebra e o mesmo encolhe do texto() do kit
+ *   zonaLayout(pl)                                    → a zona segura no espaço do layout (antes da câmera)
+ *   planejarFoto(cena, pl)                            → cena.layout {foto, halo, titulo, icones, particulas} + cena.guarda (log)
+ *   guardar(pl)                                       → roda a guarda em todas as cenas; devolve [{cena, log}]
+ *   verificarCaixas(caixas, W, H, opc)                → o que ainda viola (a conferência por caixa, sem o olho do Vision)
+ *   core                                              → as funções do guarda.jsx (gConsertar, gVerificar, gZona, ...)
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const ARQ = path.join(__dirname, 'kit-ae', 'guarda.jsx');
+const core = (() => {
+    const ctx = vm.createContext({ Math });
+    vm.runInContext(fs.readFileSync(ARQ, 'utf8') + '\n;this.__g = { GUARDA, gZona, gConsertar, gVerificar, gToca, gCabe, gCaixa, gEscala, gMove, gW, gH, gCx, gCy, gLugarLivre, gCursor, gCaixaCursor, gDentroAlvo, gTextoNoCartao };', ctx, { filename: ARQ });
+    return ctx.__g;
+})();
+
+// ── medir texto pela fonte ────────────────────────────────────────────────
+const fontes = new Map();
+function abrirFonte(familia, peso) {
+    const k = familia + '|' + peso;
+    if (fontes.has(k)) return fontes.get(k);
+    let f = null;
+    try {
+        const G = require('./glifos.js');
+        const base = String(familia).replace(/[^a-z0-9]+/gi, '-').toLowerCase();
+        for (const p of [peso, String(peso).replace(/i$/, ''), 800, 700, 400]) {
+            const arq = path.join(G.CACHE, base + '-' + p + '.ttf');
+            if (fs.existsSync(arq)) { f = G.abrirFonte(fs.readFileSync(arq)); break; }
+        }
+    } catch { f = null; }
+    fontes.set(k, f);
+    return f;
+}
+/** Largura (px) de `str` na fonte, pelos avanços do hmtx; sem a fonte no cache, 0,58 em por caractere (Poppins pesada). */
+function medirTexto(str, { fonte = 'Poppins', peso = 800, tamanho = 100, tracking = 0 } = {}) {
+    const s = String(str || '');
+    const f = abrirFonte(fonte, peso);
+    let em = 0;
+    if (f) { for (const ch of s) em += f.avanco(f.glifo(ch.codePointAt(0))) / f.porEm; }
+    else em = s.length * 0.58;
+    return em * tamanho + (tracking / 1000) * tamanho * Math.max(0, s.length - 1);
+}
+function quebra(ws, sw, maxW) {
+    const linhas = [[]]; let larg = 0;
+    ws.forEach((w, i) => {
+        const add = w + (linhas[linhas.length - 1].length ? sw : 0);
+        if (larg + add > maxW && linhas[linhas.length - 1].length) { linhas.push([i]); larg = w; }
+        else { linhas[linhas.length - 1].push(i); larg += add; }
+    });
+    return linhas;
+}
+const SO_400 = new Set(['Anton', 'Archivo Black', 'Instrument Serif', 'Bebas Neue', 'Caveat']);
+/** O bloco de texto como o texto() do kit monta (base.jsx): mesmo mínimo, mesma quebra equilibrada, mesmo encolhe de 8%. */
+function blocoTexto(str, { tamanho = 90, largura, maxLinhas = 4, principal = false, entreLinhas } = {}, pl = {}) {
+    const W = pl.w || 1080, H = pl.h || 1920, tall = H / W > 1.6, princ = principal && tall;
+    const T = pl.tipo || {}, fontesPl = pl.fontes || {};
+    const fonte = fontesPl.titulo || 'Poppins', fonteD = T.realce === 'italico' ? (fontesPl.destaque || fonte) : fonte;
+    const pesoT = SO_400.has(fonte) ? 400 : 800, pesoD = T.realce === 'italico' ? (SO_400.has(fonteD) ? '400i' : '700i') : pesoT;
+    let s = String(str || ''); if (T.caixa === 'alta') s = s.toUpperCase();
+    const pal = s.replace(/\s+/g, ' ').split(' ').filter(Boolean).map((t) => ({ t: t.replace(/\*/g, ''), kw: t.charAt(0) === '*' }));
+    if (!pal.length) return { w: 0, h: 0, tam: 0, linhas: 0 };
+    let tam = tamanho * (pl.ajuste || 1) * (pl.ajusteCena || 1);
+    tam = Math.max(tam, H * 0.036); if (princ) tam = Math.max(tam, 120);
+    const maxW = Math.min(largura || W * 0.84, W * 0.84), maxLin = maxLinhas + (princ ? 1 : 0), trk = T.tracking || 0;
+    let linhas, ws, sw, tent = 0;
+    for (;;) {
+        ws = pal.map((p) => medirTexto(p.t, { fonte: p.kw ? fonteD : fonte, peso: p.kw ? pesoD : pesoT, tamanho: tam, tracking: trk }));
+        sw = Math.max(tam * 0.27, medirTexto('a a', { fonte, peso: pesoT, tamanho: tam }) - medirTexto('aa', { fonte, peso: pesoT, tamanho: tam }));
+        const mx = Math.max(...ws);
+        linhas = quebra(ws, sw, maxW);
+        if (linhas.length > 1) { const tot = ws.reduce((a, w) => a + w + sw, 0); const l2 = quebra(ws, sw, Math.min(maxW, Math.max(mx, tot / linhas.length * 1.12))); if (l2.length <= linhas.length) linhas = l2; }
+        if ((mx <= maxW && linhas.length <= maxLin) || tent > 14 || tam < (princ ? 112 : H * 0.036)) break;
+        tam *= 0.92; tent++;
+    }
+    const lh = tam * (entreLinhas || T.entreLinhas || 1.12);
+    const w = Math.max(...linhas.map((l) => l.reduce((a, i, k) => a + ws[i] + (k ? sw : 0), 0)));
+    return { w, h: linhas.length * lh, tam, linhas: linhas.length };
+}
+
+// ── a zona no espaço do layout ────────────────────────────────────────────
+/** A zona segura do MUNDO traduzida para o LAYOUT (antes da câmera), como o kParaLayout do kit: enq × 1,12 de zoom máximo. */
+function zonaLayout(pl) {
+    const W = pl.w, H = pl.h, legenda = !!(pl.legenda && pl.legenda.chunks && pl.legenda.chunks.length);
+    const z = core.gZona(W, H, { legenda });
+    const enq = legenda ? 0.85 : 0.88, dy = legenda ? H * 0.07 : 0, f = enq * 1.12, cx = W / 2, cy = H / 2;
+    const X = (x) => cx + (x - cx) / f, Y = (y) => cy + (y - cy + dy) / f;
+    return { x0: X(z.x0), x1: X(z.x1), y0: Y(z.y0), y1: Y(z.y1), trilho: z.trilho ? [X(z.trilho[0]), Y(z.trilho[1]), W * 2, H * 2] : null };
+}
+
+/** Quanto do layout chega à tela: o kit monta o conteúdo a 88% (85% com legenda) e a câmera respira até ~6% (média ~0,9). */
+function escalaMundo(pl) { const leg = !!(pl.legenda && pl.legenda.chunks && pl.legenda.chunks.length); return (leg ? 0.85 : 0.88) * 1.03; }
+
+// ── a cena "foto" ─────────────────────────────────────────────────────────
+/** Quanto a caixa cresce no passeio (escala e deslocamento por movimento): o envelope de todos os quadros-chave. */
+function inflarFoto(recorte, mov, W, H) {
+    if (!recorte) return { kx: 1.04, ky: 1.04, dx: 0, dy: 0 };   // moldura: o passeio é DENTRO dela; só a rotação 3D (perspectiva) e a sombra
+    const esc = 1.06;   // o kit (cenaFoto com layout) anda de 1,0 a 1,06 ou de 1,06 a 0,97
+    const lateral = mov === 'passeio' || mov === 'orbita';
+    return { kx: esc * 1.03, ky: esc * 1.03, dx: lateral ? W * 0.025 : 0, dy: lateral ? 0 : H * 0.015 };
+}
+
+/**
+ * Planeja a cena "foto": a foto o maior possível (55–80% da largura no 9:16), o título sem encostar nela, os ícones só em espaço livre.
+ * Escreve `cena.layout` (o kit lê) e `cena.guarda` (o log). Sem caber, encolhe o título; sem saída, a cena troca de peça.
+ */
+function planejarFoto(c, pl, { tentativa = 0 } = {}) {
+    const F = c.foto;
+    if (!F) return null;
+    const W = pl.w, H = pl.h, v = H >= W * 0.95, alto = H / W > 1.6, u = Math.min(W, H) / 1080;
+    const z = zonaLayout(pl), folga = core.GUARDA.folga * u;
+    const mundo = escalaMundo(pl);   // layout → o que o espectador vê (a câmera monta a 88% e respira até ~6%)
+    const recorte = !!F.recorte, fw = recorte ? (F.rw || F.w) : F.w, fh0 = recorte ? (F.rh || F.h) : F.h;
+    // foto alta (retrato, celular em pé, pessoa de corpo inteiro): no 9:16 a caixa vai até 4:5 e o resto é cortado (embaixo no
+    // recorte, com degradê; no meio na moldura, onde o passeio anda) — senão a foto não cabe grande junto do título
+    const ASP = v ? [1.25, 1.1, 1.0, 0.9] : [1.6, 1.3];   // sem caber, a caixa fica mais baixa (corta mais) antes de desistir
+    const maxAsp = ASP[Math.min(tentativa, ASP.length - 1)], corte = fh0 / fw > maxAsp ? maxAsp / (fh0 / fw) : 1, fh = fh0 * corte;
+    const inf = inflarFoto(recorte, c.movimento || 'aproxima', W, H);
+    const log = [];
+    // o título, medido na fonte (o kit pode mudar alguns px: a guarda do kit confere de novo com a caixa real)
+    const tamT = (v ? 86 : 74) * (c.ajuste || 1);
+    // no 9:16 o título fica entre a margem esquerda e o trilho de botões do Reels (centro ~30 px à esquerda: não se nota, e ganha uma linha)
+    const xDir = z.trilho ? Math.min(z.x1, z.trilho[0]) : z.x1;
+    const largT = v ? Math.min(W * 0.84, xDir - z.x0 - 8) : W * 0.42;
+    const tb = c.titulo ? blocoTexto(c.titulo, { tamanho: tamT, largura: largT, maxLinhas: 3, principal: true }, { ...pl, ajusteCena: 1 }) : null;
+    const tw = tb ? tb.w * 1.04 : 0, th = tb ? tb.h * 1.06 : 0;
+    const itens = [];
+    let fotoW, fotoH, px, py, tx, ty;
+    if (v) {
+        const zh = z.y1 - z.y0, livre = zh - (tb ? th + folga : 0);
+        fotoW = W * (alto ? Math.max(core.GUARDA.fotoMin, core.GUARDA.fotoMax * (c.fotoMenor || 1)) / mundo : 0.6); fotoH = fotoW * fh / fw;   // fotoMenor: o olho achou texto no rosto
+        // a foto alta demais pro espaço: encolhe pela altura (o guarda reclama se ficar abaixo de 55%)
+        const envH = (h) => h * inf.ky + 2 * inf.dy;
+        if (envH(fotoH) > livre * 0.94) { fotoH = (livre * 0.94 - 2 * inf.dy) / inf.ky; fotoW = fotoH * fw / fh; }
+        // título embaixo (no fim da zona), a foto em cima dele com folga; o espaço que sobra fica em cima, pros ícones
+        ty = tb ? z.y1 - th / 2 : null; tx = z.trilho ? (z.x0 + xDir) / 2 : W / 2;
+        const baseFoto = tb ? ty - th / 2 - folga : z.y1;
+        py = baseFoto - envH(fotoH) / 2; px = W / 2;
+    } else {
+        fotoW = Math.min(W * 0.4, (H * 0.74) * fw / fh); fotoH = fotoW * fh / fw;
+        px = W * 0.3; py = H / 2; tx = W * 0.73; ty = H / 2;
+    }
+    const fotoItem = { id: 'foto', tipo: 'foto', nome: 'a foto', c: core.gCaixa(px, py, fotoW * inf.kx + 2 * inf.dx, fotoH * inf.ky + 2 * inf.dy), infla: inf.kx + 2 * inf.dx / fotoW, prio: 9 };
+    itens.push(fotoItem);
+    const titItem = tb ? { id: 'titulo', tipo: 'texto', nome: 'o título', c: core.gCaixa(tx, ty, tw, th), prio: 10 } : null;
+    if (titItem) itens.push(titItem);
+    // os ícones (elementos reais do assunto) começam onde o kit punha; a guarda tira de cima do texto e da foto
+    const nEl = Math.min((pl.elementos || []).length, v ? 3 : 2), S = Math.min(W, H) * (v ? 0.2 : 0.24);
+    const posV = [[W * 0.2, H * 0.17], [W * 0.84, H * 0.5], [W * 0.18, H * 0.58]], posH = [[W * 0.54, H * 0.2], [W * 0.5, H * 0.8]];
+    const ondula = (12 + 0.05 * W / u) * u, inflaI = 1.15;   // o balanço (seno) e o quique da entrada
+    for (let i = 0; i < nEl; i++) {
+        const p = (v ? posV : posH)[i];
+        itens.push({ id: 'icone' + i, idx: i, tipo: 'icone', nome: 'ícone ' + ((pl.elementos[i] && pl.elementos[i].nome) || i + 1), c: core.gCaixa(p[0], p[1], S * inflaI + 2 * ondula, S * inflaI + 2 * 13 * u), infla: (S * inflaI + 2 * ondula) / S, prio: 3 - i });
+    }
+    const r = core.gConsertar(itens, W, H, { zona: z, folga, escalaMundo: mundo });
+    log.push(...r.log);
+    if (r.trocar) {
+        if (tentativa < ASP.length - 1 && fh0 / fw > ASP[tentativa + 1]) return planejarFoto(c, pl, { tentativa: tentativa + 1 });
+        c.guarda = [...log, 'a foto e o título não cabem juntos: a cena vira herói (sem a foto)'];
+        c.tipo = 'heroi'; c.layout = null;
+        return c.guarda;
+    }
+    if (corte < 1) log.unshift(`foto alta: a caixa vai até ${maxAsp === 1.25 ? '4:5' : '1:' + maxAsp} e ${Math.round((1 - corte) * 100)}% da altura fica de fora (${recorte ? 'embaixo, com degradê' : 'o passeio anda por ela'})`);
+    const fi = r.itens.find((x) => x.id === 'foto');
+    const k = fi.k, fW = fotoW * k, fH = fotoH * k;
+    const cxF = (fi.c[0] + fi.c[2]) / 2, cyF = (fi.c[1] + fi.c[3]) / 2;
+    const ti = r.itens.find((x) => x.id === 'titulo');
+    const fotoPct = Math.round(fW * mundo / W * 100);   // no mundo (o que se vê)
+    c.layout = {
+        foto: { x: Math.round(cxF), y: Math.round(cyF), w: Math.round(fW), h: Math.round(fH), ...(corte < 1 ? { corte: Math.round(corte * 1000) / 1000 } : {}) },
+        // o halo abraça a foto (nunca vaza pro título): círculo atrás da cabeça no recorte, placa arredondada na moldura
+        halo: recorte ? { x: Math.round(cxF), y: Math.round(cyF - fH * 0.06), d: Math.round(Math.min(fW * 0.92, fH * 1.02)) } : { x: Math.round(cxF), y: Math.round(cyF), w: Math.round(fW * 1.04), h: Math.round(fH * 1.04) },
+        titulo: ti ? { x: Math.round((ti.c[0] + ti.c[2]) / 2), y: Math.round((ti.c[1] + ti.c[3]) / 2), largura: Math.round(largT), tam: Math.round(tamT * 100) / 100 } : null,
+        icones: r.itens.filter((x) => x.tipo === 'icone').map((x) => (x.removido ? { i: x.idx, fora: true } : { i: x.idx, x: Math.round((x.c[0] + x.c[2]) / 2), y: Math.round((x.c[1] + x.c[3]) / 2), w: Math.round(S * x.k) })),
+        particulas: [Math.round(fi.c[0]), Math.round(fi.c[1]), Math.round(fi.c[2]), Math.round(fi.c[3])],
+        fotoPct,
+    };
+    c.guarda = log.length ? log : [`ok: foto ${fotoPct}% da largura, nada encostado`];
+    return c.guarda;
+}
+
+/** A guarda em todas as cenas do plano (hoje a "foto" é planejada aqui; as outras, a guarda do kit conserta com a caixa real). */
+function guardar(pl) {
+    const out = [];
+    (pl.cenas || []).forEach((c, i) => {
+        if (c.tipo === 'foto' && c.foto) { const l = planejarFoto(c, pl); if (l && l.length) out.push({ cena: i, log: l }); }
+    });
+    return out;
+}
+
+/** As caixas finais (a linha GUARDA do kit) conferidas de novo: o que ainda viola. */
+function verificarCaixas(caixas, W, H, { legenda = false } = {}) {
+    const itens = (caixas || []).map((x, i) => ({ id: i, tipo: x.tipo, nome: x.nome, c: x.c, removido: !!x.fora, livre: !!x.livre }));
+    return core.gVerificar(itens, W, H, { zona: zonaLayout({ w: W, h: H, legenda: legenda ? { chunks: [1] } : null }), folga: 0 });
+}
+
+module.exports = { core, escalaMundo, medirTexto, blocoTexto, zonaLayout, inflarFoto, planejarFoto, guardar, verificarCaixas };

package/lib/estudio/maquina-layout.js

@@ -143,7 +143,11 @@ function corrigir(plano, r, { tentativa = 1, paletaFundo = null } = {}) {
         const l = por[k];
         const comAmbiente = l.some((x) => /ambiente/.test(x));
         if (comAmbiente && !c.semAmbiente) { c.semAmbiente = true; mudou.push(`cena ${k}: sem o elemento de enfeite (${l.find((x) => /ambiente/.test(x))})`); }
-        const outros = l.filter((x) => !/ambiente/.test(x) && !/herói pequeno|texto principal pequeno/.test(x));
+        // texto que a câmera leva pra cima da faixa de cima (o título do topo, com chicote/pulso): o título desce 1,2% em vez de
+        // encolher (encolher não tira ele do topo: só deixa a letra pequena)
+        const emCima = l.filter((x) => { const m = x.match(/texto fora da área segura[^[]*\[(-?\d+),(-?\d+),(-?\d+),(-?\d+)\]/); return m && Number(m[2]) < (plano.h || 1920) * 0.16 && Number(m[4]) < (plano.h || 1920) * 0.5; });
+        if (emCima.length && (c.tituloDesce || 0) < 0.05) { c.tituloDesce = Math.round(((c.tituloDesce || 0) + 0.012) * 1000) / 1000; mudou.push(`cena ${k}: o título desce ${Math.round(c.tituloDesce * 1000) / 10}% (${emCima[0]})`); }
+        const outros = l.filter((x) => !/ambiente/.test(x) && !/herói pequeno|texto principal pequeno/.test(x) && !/^guarda: /.test(x) && !(emCima.includes(x) && (c.tituloDesce || 0) <= 0.05));
         if (outros.length) {
             if ((c.ajuste || 1) <= 0.9 || c.semRotulos === undefined && (c.ajuste || 1) < 1) {   // 2ª vez: some o que é opcional (rótulos e enfeite) em vez de encolher o texto até ficar ilegível
                 if (!c.semRotulos) { c.semRotulos = true; c.semAmbiente = true; mudou.push(`cena ${k}: sem rótulos opcionais e sem enfeite (${outros[0]})`); }
@@ -179,6 +183,23 @@ function corrigir(plano, r, { tentativa = 1, paletaFundo = null } = {}) {
         c.f = Math.round(Math.min(2.4, Math.max((c.f || 1) * 1.2, (t.entrou * (c.f || 1)) / (0.36 * c.dur))) * 100) / 100;
         mudou.push(`cena ${t.cena}: entrada tardia (${t.entrou} s de ${t.dur} s), acelera ${c.f}×`);
     }
+    // a guarda do kit não achou saída: a peça troca (a foto encolhe o título antes; na 2ª vez vira herói)
+    for (const k of Object.keys(por)) {
+        const c = plano.cenas[Number(k)];
+        if (!c || !por[k].some((x) => /^guarda: troca a peça/.test(x))) continue;
+        if (c.tipo === 'foto' && !c.trocouGuarda) { c.trocouGuarda = true; c.ajuste = Math.round((c.ajuste || 1) * 0.85 * 100) / 100; mudou.push(`cena ${k}: guarda sem saída, título ${Math.round(c.ajuste * 100)}%`); }
+        else if (c.tipo !== 'cinetico') { mudou.push(`cena ${k}: guarda sem saída, ${c.tipo} vira cinetico`); c.tipo = 'cinetico'; c.elemento = false; }
+    }
+    // o olho depois do render (conferencia-visual.js): texto colado na borda, sobre o rosto, encavalado; caixa sobreposta ou fora da zona
+    const vistas = new Set();
+    for (const p of (r.pixels && r.pixels.visual) || []) {
+        const c = plano.cenas[p.cena];
+        if (!c || vistas.has(p.cena + p.tipo)) continue;
+        vistas.add(p.cena + p.tipo);
+        if (p.tipo === 'rosto' && c.tipo === 'foto') { c.fotoMenor = Math.round((c.fotoMenor || 1) * 0.9 * 100) / 100; mudou.push(`cena ${p.cena}: ${p.texto}; foto ${Math.round(c.fotoMenor * 100)}%`); }
+        else if (p.tipo === 'sobreposicao' && !c.semAmbiente) { c.semAmbiente = true; c.semRotulos = true; mudou.push(`cena ${p.cena}: ${p.texto}; sem enfeite e sem rótulos opcionais`); }
+        else { c.ajuste = Math.round((c.ajuste || 1) * 0.9 * 100) / 100; mudou.push(`cena ${p.cena}: ${p.texto}; corpo ${Math.round(c.ajuste * 100)}%`); }
+    }
     for (const b of r.bordas || []) {
         const c = plano.cenas[b.cena];
         if (!c) continue;

package/lib/estudio/maquina.js

@@ -68,6 +68,25 @@ function paletaDoAssunto(assunto) {
     return achou || PALETAS[hashTexto(a) % PALETAS.length];
 }
 
+/** Saturação (HSL, 0–1) e luminosidade de uma cor: separa cor de verdade de preto, branco e cinza. */
+function saturacao(h) {
+    const c = (rgb(h) || [0, 0, 0]).map((v) => v / 255);
+    const mx = Math.max(...c), mn = Math.min(...c), l = (mx + mn) / 2;
+    if (mx === mn) return { s: 0, l };
+    return { s: (mx - mn) / (1 - Math.abs(2 * l - 1)), l };
+}
+/**
+ * O cartão EM DESTAQUE de uma cena (o último da lista, o painel, a barra que ganha). Todo cartão vem da paleta da cena:
+ * o destaque só vira cartão quando é COR (saturada, nem quase preta nem quase branca); senão — o fundo de destaque
+ * ganha a tinta escura como acento e o cartão saía PRETO — o cartão é o brilho (o fundo puxado para o acento), e
+ * o texto em cima é o que mais contrasta com ele.
+ */
+function cartaoDestaque(bg, fg, ac, brilho) {
+    const { s, l } = saturacao(ac);
+    const cor = s >= 0.35 && l >= 0.18 && l <= 0.88 ? ac : brilho;
+    return { cardAc: cor, sobreCardAc: melhorCor(cor, [fg, bg, '#FFFFFF', '#14110F']) };
+}
+
 /** As 3 variações da paleta: normal, fundo profundo e fundo de destaque, sempre com contraste de leitura. */
 function variacoes(base) {
     const fundo = base.fundo, tinta = base.tinta, dest = base.destaque;
@@ -77,7 +96,8 @@ function variacoes(base) {
         if (contraste(fg, bg) < 4.5) fg = melhorCor(bg, ['#FFFFFF', '#111111']);
         if (contraste(ac, bg) < 3) ac = melhorCor(bg, [dest, fg, tinta, fundo]);
         const mudo = misturar(bg, fg, 0.66);
-        return { bg, fg, ac, mudo: contraste(mudo, bg) >= 3 ? mudo : fg, card: misturar(bg, fg, 0.1), brilho: misturar(bg, ac, 0.32) };
+        const brilho = misturar(bg, ac, 0.32);
+        return { bg, fg, ac, mudo: contraste(mudo, bg) >= 3 ? mudo : fg, card: misturar(bg, fg, 0.1), brilho, ...cartaoDestaque(bg, fg, ac, brilho) };
     };
     return {
         normal: fix(fundo, tinta, dest),
@@ -114,7 +134,7 @@ function normalizarCena(c, i) {
     return diretor.completar(c, tipo, { assunto: c.titulo || '', meta: diretor.METAFORAS.geral, proxima: null });
 }
 
-const maxDur = (tipo) => (tipo === 'celular' || tipo === 'prompt' ? 5 : 4.2);
+const maxDur = (tipo) => (tipo === 'celular' || tipo === 'prompt' ? 5 : tipo === 'foto' ? 4.8 : 4.2);
 
 /**
  * Do pedido ao PLANO que o kit entende (sem rede nem disco; o histórico de assinaturas vem por `opc.historico`).
@@ -128,10 +148,15 @@ function plano(args = {}, opc = {}) {
     const [w, h] = FORMATOS[formato];
     const alvo = Math.max(6, Math.min(60, Number(args.duracao) || duracaoDaFicha(ficha) || 15));
     const elementos = opc.elementos || [];
-    const dir = diretor.dirigir({ ...args, duracao: alvo }, { historico: opc.historico || [], semente: opc.semente != null ? opc.semente : null, temElemento: opc.elementos ? opc.elementos.length > 0 : true });
+    // só o que mora no projeto vai pro plano: o caminho de origem (`de`) fica de fora, pra nada apontar pra fora da pasta
+    const fotos = Array.isArray(opc.fotos) ? opc.fotos.filter((f) => f && f.arquivo).map(({ de, ...resto }) => resto) : [];
+    const dir = diretor.dirigir({ ...args, duracao: alvo, fotos }, { historico: opc.historico || [], semente: opc.semente != null ? opc.semente : null, temElemento: opc.elementos ? opc.elementos.length > 0 : true });
     const cenas = dir.cenas;
+    // a cena "foto" leva a foto preparada (arquivo no projeto, fundo desfocado, recorte) e o passeio que o diretor sorteou
+    cenas.forEach((c) => { if (c.tipo === 'foto') { const f = fotos[(c.foto || 0) % Math.max(1, fotos.length)]; if (f) c.foto = { ...f }; else c.foto = null; } });
 
     // o ritmo: sem pedido de duração por cena, ajusta ao alvo (cada cena entre 1,4 e 4,2 s)
+    cenas.forEach((c) => { if (c.tipo === 'foto') c.dur = Math.min(maxDur('foto'), c.dur * 1.5); });   // a foto precisa de tempo pro passeio
     const soma = cenas.reduce((s, c) => s + c.dur, 0);
     if (!args.cenas || args.duracao) {
         const k = alvo / soma;
@@ -169,7 +194,7 @@ function plano(args = {}, opc = {}) {
     const duracao = Math.round(cenas.reduce((s, c) => s + c.dur, 0) * 100) / 100;
     cenas.forEach((c, i) => { c.inicio = Math.round(cenas.slice(0, i).reduce((s, x) => s + x.dur, 0) * 1000) / 1000; });
     return { w, h, fps: 30, formato, fontes, tipo, paleta, trocas: dir.trocas, cenas, ajuste: 1, receita: receita ? receita.id : null, duracao,
-        camera: dir.camera, elementos, bpm: 0, voz: null, legenda: null, direcao: dir.assinatura, semente: dir.semente, variacoes: v };
+        camera: dir.camera, elementos, fotos, bpm: 0, voz: null, legenda: null, direcao: dir.assinatura, semente: dir.semente, variacoes: v };
 }
 
 /** A voz manda: cada cena começa na 1ª palavra da fala dela e dura até a próxima. `voz` = resultado de falarEMedir. */
@@ -226,9 +251,9 @@ function ajustarCortes(pl, batidas, { tolerancia = 0.28 } = {}) {
 }
 
 const lerKit = (n) => fs.readFileSync(path.join(KIT, n), 'utf8');
-/** O JSX completo: o kit, as primitivas, as cenas e a chamada `montar(PLANO)`. */
+/** O JSX completo: o kit, a guarda de layout, as primitivas, as cenas e a chamada `montar(PLANO)`. */
 function script(pl) {
-    return lerKit('base.jsx') + '\n' + lerKit('primitivas.jsx') + '\n' + lerKit('cenas.jsx') + '\nmontar(' + JSON.stringify(pl) + ');\n';
+    return lerKit('base.jsx') + '\n' + lerKit('guarda.jsx') + '\n' + lerKit('primitivas.jsx') + '\n' + lerKit('cenas.jsx') + '\nmontar(' + JSON.stringify(pl) + ');\n';
 }
 /** Os tempos medidos de cada cena (início de cada uma e o instante de conferir). */
 function tempos(pl) {
@@ -367,6 +392,18 @@ async function motion(args = {}, { pasta, receita = null, deps = {} } = {}) {
     const historico = deps.historico || diretor.lerHistorico(arqHist);
     const assunto = limpa(args.assunto || (args.cenas[0] && (args.cenas[0].titulo || args.cenas[0].texto)) || '', 160);
 
+    // 0. as fotos do pedido: validadas, copiadas pro projeto, com fundo desfocado e recorte (uma vez, antes do render)
+    const pedidasFotos = Array.isArray(args.fotos) ? args.fotos : (args.fotos ? [args.fotos] : []);
+    let fotos = [], fotosRecusadas = [];
+    if (pedidasFotos.length) {
+        const F = require('./maquina-foto.js');
+        const pf = await F.preparar({ fotos: pedidasFotos, pasta, deps: deps.foto || {} });
+        fotos = pf.fotos; fotosRecusadas = pf.recusadas;
+        // a pessoa mandou foto (em `fotos`) e NENHUMA serve: diz o porquê em vez de entregar um vídeo sem a foto dela.
+        // As fotos achadas no texto do pedido (fotosImplicitas) só avisam: o vídeo sai sem elas.
+        if (!fotos.length && !args.fotosImplicitas) return { ok: false, error: 'nenhuma das fotos serve: ' + fotosRecusadas.map((x) => x.motivo).join(' '), fotosRecusadas };
+    }
+
     // 1. os elementos reais do assunto
     const meta = diretor.achar(assunto + ' ' + (args.metafora || ''));
     const pedidos = Array.isArray(args.elementos) ? args.elementos : (args.elementos ? [args.elementos] : []);
@@ -378,8 +415,9 @@ async function motion(args = {}, { pasta, receita = null, deps = {} } = {}) {
     // o gosto salvo da pessoa entra como PESO no sorteio do diretor (não como molde)
     const G = require('./gosto.js');
     const gostoP = deps.gosto !== undefined ? deps.gosto : G.pesos(G.ler());
-    let pl = plano({ ...args, assunto, gosto: gostoP }, { receita, historico, elementos });
-    const avisosDeMotor = [];
+    let pl = plano({ ...args, assunto, gosto: gostoP }, { receita, historico, elementos, fotos });
+    const avisosDeMotor = fotosRecusadas.map((x) => 'foto recusada: ' + x.motivo);
+    if (fotos.length && !pl.cenas.some((c) => c.tipo === 'foto')) avisosDeMotor.push('as fotos não entraram em nenhuma cena (o roteiro fixou todas as cenas com outro tipo).');
     if (elementos.length < 3) avisosDeMotor.push(`só ${elementos.length} elemento(s) real(is) do assunto (o pedido é ≥ 3)`);
 
     // 3. a narração (opcional) manda no tempo
@@ -438,7 +476,12 @@ async function motion(args = {}, { pasta, receita = null, deps = {} } = {}) {
     };
     const lerAudit = (saida) => String(saida || '').split('\n').filter((l) => /^AUDIT \{/.test(l)).map((l) => { try { return JSON.parse(l.slice(6)); } catch { return null; } }).filter(Boolean);
     const tm0 = tempos(pl);
+    // a GUARDA de layout: antes de cada render, o plano é conferido e consertado (maquina-guarda.js: a cena "foto" sai planejada com a
+    // fonte medida); no kit, o fecha() de cada cena roda a mesma guarda com as caixas reais. Depois do render, o olho (Vision) confere.
+    const GU = require('./maquina-guarda.js'), CV = require('./conferencia-visual.js');
+    let guardaPlano = [], guardaKit = [], olho = null;
     for (let tentativa = 1; tentativa <= 5; tentativa++) {
+        guardaPlano = GU.guardar(pl);
         const tm = tempos(pl);
         // quadros: 1 por cena (no instante de ler) + 2 em cada troca (+0,08 s e +0,22 s) para pegar borda de comp aparecendo e borrão
         const trTempos = []; pl.cenas.slice(1).forEach((c) => trTempos.push(Math.round((c.inicio + 0.08) * 100) / 100, Math.round((c.inicio + 0.22) * 100) / 100));
@@ -460,11 +503,16 @@ async function motion(args = {}, { pasta, receita = null, deps = {} } = {}) {
         quadrosCena.forEach((q, i) => { const px = layout.lerPixels(q); if (!px) return; nitidezCena.push(layout.nitidez(px)); const fb = layout.faixaDeBorda(px); if (fb) pxChecks.bordaDaComp.push({ cena: i, ...fb }); const pc = pl.cenas[i].pal; const so = layout.solidosForaDaPaleta(px, [pc.bg, pc.fg, pc.ac, pc.mudo, pc.card]); if (so >= 0.025) pxChecks.solidoForaDaPaleta.push({ cena: i, fracao: Math.round(so * 1000) / 1000 }); });
         const nitMed = nitidezCena.slice().sort((a, b) => a - b)[Math.floor(nitidezCena.length / 2)] || 0;
         quadrosTroca.forEach((q, k) => { const px = layout.lerPixels(q); if (!px) return; const cutIdx = Math.floor(k / 2) + 1; const nt = layout.nitidez(px); if (nitMed > 0 && layout.varLum(px) > 400 && nt < nitMed * 0.01) pxChecks.borrao.push({ cena: cutIdx, nitidez: nt, referencia: nitMed }); });
+        guardaKit = CV.lerGuarda(r.saida);
+        olho = CV.conferir({ quadros: quadrosCena, pl, guarda: guardaKit, visao: deps.visao });
+        pxChecks.visual = olho.problemas;
         const graves = c.baixoContraste.filter((b) => b.contraste < 3);
         const contagem = classificar(avisos, auditorias, entradas, vazios, c.baixoContraste, tardias);
         contagem.bordaDaComp = pxChecks.bordaDaComp.length; contagem.solidoForaDaPaleta = pxChecks.solidoForaDaPaleta.length; contagem.borrao = pxChecks.borrao.length;
+        contagem.visual = olho.problemas.length; contagem.consertosDaGuarda = guardaPlano.reduce((n, g) => n + g.log.filter((x) => !/^ok:/.test(x)).length, 0) + guardaKit.reduce((n, g) => n + g.log.length, 0);
         passadas.push({ passada: tentativa, ...contagem });
-        conferencia = { tentativas: tentativa, quadros: (r.quadros || []).length, pixels: pxChecks, vazios, baixoContraste: c.baixoContraste, bordas: c.bordas, avisos, auditoria: auditorias, elementosNaCena: nReais, entradas: entradas.map((x) => ({ cena: x.cena, entrou: Math.round(x.max / (x.f || 1) * 100) / 100, dur: x.dur, f: x.f })), entradaTardia: tardias, ok: !vazios.length && !graves.length && !avisos.length && !tardias.length && !pxChecks.bordaDaComp.length && !pxChecks.solidoForaDaPaleta.length && !pxChecks.borrao.length };
+        conferencia = { tentativas: tentativa, quadros: (r.quadros || []).length, pixels: pxChecks, vazios, baixoContraste: c.baixoContraste, bordas: c.bordas, avisos, auditoria: auditorias, elementosNaCena: nReais, entradas: entradas.map((x) => ({ cena: x.cena, entrou: Math.round(x.max / (x.f || 1) * 100) / 100, dur: x.dur, f: x.f })), entradaTardia: tardias, ok: !vazios.length && !graves.length && !avisos.length && !tardias.length && !pxChecks.bordaDaComp.length && !pxChecks.solidoForaDaPaleta.length && !pxChecks.borrao.length && !olho.problemas.length,
+            guarda: { plano: guardaPlano, kit: guardaKit.filter((g) => g.log.length).map((g) => ({ cena: g.cena, log: g.log })), olho: olho.olho } };
         if (conferencia.ok || tentativa === 5) break;
         const mudou = layout.corrigir(pl, { avisos, vazios, baixoContraste: c.baixoContraste, bordas: [], tardias, pixels: pxChecks }, { tentativa, paletaFundo: pl.variacoes && pl.variacoes.fundo });
         historicoDeTentativas.push({ tentativa, mudou });
@@ -505,10 +553,11 @@ async function motion(args = {}, { pasta, receita = null, deps = {} } = {}) {
     try { sv = require('./editor.js').salvarSpec(pasta, { pl, args, trilha: trilha && { arquivo: trilha.arquivo, inicio: trilhaInicio }, voz: voz && { mp3: voz.mp3 }, video, previa: !!args.previa }) || {}; } catch { /* sem versão */ }
     return {
         ok: true, video: sv.video || video, versao: sv.versao, previa: !!args.previa, quadros: r.quadros || [], folha, duracao: dur,
-        lufs: mix.ok ? mix.lufs : null, formato: pl.formato, cenas: pl.cenas.map((c) => ({ tipo: c.tipo, dur: c.dur, papel: c.papel, camera: c.camera })),
+        lufs: mix.ok ? mix.lufs : null, formato: pl.formato, cenas: pl.cenas.map((c) => ({ tipo: c.tipo, dur: c.dur, papel: c.papel, camera: c.camera, ...(c.tipo === 'foto' ? { movimento: c.movimento } : {}) })),
         trocas: pl.trocas, tipografia: pl.tipo.nome, camera: pl.camera, paleta: pl.direcao.paleta,
         sons: eventos.length, sonsBrutos: eventosBrutos.length, sfxReais, mix: mix.mix || null, trilha: trilha ? { titulo: trilha.titulo, autor: trilha.autor, creditos: trilha.creditos, bpm: trilha.bpm, nota: trilha.nota, lufs: trilha.lufs, inicio: trilhaInicio, cortesNaBatida: analise && analise.cortesNaBatida, pessoa: !!trilha.pessoa } : null, semMusica,
         voz: !!voz, vozMotor: voz && voz.motor, vozMedida: voz && voz.medido, conferencia, receita: pl.receita, projeto: r.projeto, assinatura,
+        fotos: fotos.map((f) => ({ arquivo: path.relative(pasta, f.arquivo).replace(/\\/g, '/'), recorte: !!f.recorte, moldura: !!f.moldura })), fotosRecusadas,
         elementos: elementos.map((e) => ({ nome: e.nome, tipo: e.tipo, licenca: e.licenca })), creditos: (el && el.creditos) || [],
         avisos: avisosDeMotor,
         ...(gostoP && gostoP.overshoot != null ? { gosto: { overshoot: gostoP.overshoot } } : {}),
@@ -517,4 +566,4 @@ async function motion(args = {}, { pasta, receita = null, deps = {} } = {}) {
     };
 }
 
-module.exports = { filtrarSons, FORMATOS, TIPOS, TROCAS, PALETAS, plano, aplicarVoz, ajustarCortes, roteiroPadrao, normalizarCena, paletaDoAssunto, variacoes, contraste, script, tempos, lerSons, lerAvisos, lerElementos, lerEntradas, mixar, variancia, medirLufs, motion, marcarChave, fontesDoPlano, repartirFala, LIMIAR_VAZIO };
+module.exports = { cartaoDestaque, saturacao, filtrarSons, FORMATOS, TIPOS, TROCAS, PALETAS, plano, aplicarVoz, ajustarCortes, roteiroPadrao, normalizarCena, paletaDoAssunto, variacoes, contraste, script, tempos, lerSons, lerAvisos, lerElementos, lerEntradas, mixar, variancia, medirLufs, motion, marcarChave, fontesDoPlano, repartirFala, LIMIAR_VAZIO };

package/lib/estudio/referencias.js

@@ -169,7 +169,7 @@ function instrucaoDasImagens(lista = IMAGENS) {
     return `[REFERÊNCIA VISUAL] A pessoa mandou ${lista.length} imagem(ns): ${lista.map((f) => require('path').basename(f)).join(', ')}. `
         + 'Elas SÃO a referência do pedido, mesmo em "só motion". Se o pedido é vídeo, o Estúdio já guarda cada uma no projeto e tira as '
         + 'cores dela (com site, as cores do site mandam). Escreva o roteiro seguindo o que a referência mostra e diga no fim, '
-        + 'em uma linha, o que dela o vídeo usou.';
+        + 'em uma linha, o que dela o vídeo usou. No estudio_motion a foto também entra NA CENA (peça "foto": fundo desfocado, foto ou recorte da pessoa em 3D, passeio de câmera); passe os caminhos em "fotos" ou deixe o Estúdio pegar os do pedido.';
 }
 
 module.exports = { definir, atual, limpar, semImagem, termos, entender, inferir, instrucao, dominios, filtrar,