primocode 10.13.0 → 10.14.1

package/lib/estudio/dados/projetos-ae/processo-motion-100-ia/take-unico/take.js

@@ -0,0 +1,235 @@
+/* take.js — motor do "take único" (lousa contínua) em HTML seek(t). window.TK no navegador, require() no node.
+ *
+ * Tudo aqui é função pura do tempo: os mesmos argumentos dão sempre o mesmo número. Por isso o render pode pedir
+ * qualquer instante (e vários instantes dentro de um quadro, para o desfoque de movimento do obturador).
+ * Método estudado no onetake (05-pesquisa/referencias/2026-10-12-onetake-take-unico.md), código escrito do zero.
+ * Tutorial: 07-videos/linguagem-edicao/tutorial-take-unico.md.
+ *
+ *   curvas    ease.* · bezier · spring · springVel · ring · rng · spline
+ *   entrada   wordRise · letterDrop · popIn · typeOn · drawOn
+ *   carry     morphRect · iris · zoomThrough · hop · gather · carryTela (+ chain)
+ *   contato   impact · press · click · shake
+ *   câmera    operador (molas que perseguem) · flutuar · view · project · unproject · projectBox · screenTravel · lattice
+ */
+(function (root) {
+  'use strict';
+  const clamp = (v, a = 0, b = 1) => Math.max(a, Math.min(b, v));
+  const lerp = (a, b, k) => a + (b - a) * k;
+  const seg = (t, t0, t1) => (t1 === t0 ? (t >= t1 ? 1 : 0) : clamp((t - t0) / (t1 - t0)));
+
+  // ── curvas ─────────────────────────────────────────────────────────────────────────────────────────────────
+  // cubic-bezier do CSS/AE como função de u. board e saas são as curvas da casa (regras-vigentes.md).
+  function bezier(x1, y1, x2, y2) {
+    const cx = 3 * x1, bx = 3 * (x2 - x1) - cx, ax = 1 - cx - bx, cy = 3 * y1, by = 3 * (y2 - y1) - cy, ay = 1 - cy - by;
+    const X = s => ((ax * s + bx) * s + cx) * s, Y = s => ((ay * s + by) * s + cy) * s, dX = s => (3 * ax * s + 2 * bx) * s + cx;
+    return u => {
+      if (u <= 0) return 0; if (u >= 1) return 1;
+      let s = u;
+      for (let i = 0; i < 8; i++) { const e = X(s) - u, d = dX(s); if (Math.abs(e) < 1e-7) return Y(s); if (Math.abs(d) < 1e-6) break; s -= e / d; }
+      let lo = 0, hi = 1; s = u;
+      for (let i = 0; i < 50; i++) { const v = X(s); if (Math.abs(v - u) < 1e-7) break; if (v < u) lo = s; else hi = s; s = (lo + hi) / 2; }
+      return Y(s);
+    };
+  }
+  const pOut = n => u => 1 - Math.pow(1 - u, n);
+  const pInOut = n => u => (u < 0.5 ? Math.pow(2, n - 1) * Math.pow(u, n) : 1 - Math.pow(2 - 2 * u, n) / 2);
+  const expoIn = u => (u <= 0 ? 0 : (Math.pow(2, 10 * u) - 1) / 1023);
+  // t80 entre parênteses: fração do tempo até 80 % do caminho. Baixo = estalo que assenta; ~.7 = S mole.
+  const ease = {
+    linear: u => u,
+    smooth: u => u * u * (3 - 2 * u),                      // .71
+    sineInOut: u => (1 - Math.cos(Math.PI * u)) / 2,       // câmera que acompanha
+    cubicInOut: pInOut(3), quintInOut: pInOut(5),
+    cubicOut: pOut(3), quartOut: pOut(4), quintOut: pOut(5), // .42 · .33 · .28
+    expoOut: u => (u >= 1 ? 1 : (1 - Math.pow(2, -10 * u)) / (1 - Math.pow(2, -10))), // .23 estalo
+    expoInOut: u => (u < 0.5 ? expoIn(2 * u) / 2 : 1 - expoIn(2 - 2 * u) / 2),         // chicote
+    board: bezier(0.333, 0, 0.2285, 1),                    // viagem da lousa (Shelby v3)
+    saas: bezier(0.86, 0, 0.07, 1),                        // troca de cena SaaS
+  };
+  const tween = (t, t0, t1, c = ease.expoOut) => c(seg(t, t0, t1));
+
+  // Mola amortecida 0 → 1 em forma fechada. Padrão da casa ζ .56 ω 12 (~112 %, assenta em ~.6 s).
+  function spring(tau, zeta = 0.56, omega = 12) {
+    if (tau <= 0) return 0;
+    if (zeta < 1) { const wd = omega * Math.sqrt(1 - zeta * zeta); return 1 - Math.exp(-zeta * omega * tau) * (Math.cos(wd * tau) + (zeta * omega / wd) * Math.sin(wd * tau)); }
+    return 1 - Math.exp(-omega * tau) * (1 + omega * tau);
+  }
+  function springVel(tau, zeta = 0.56, omega = 12) {
+    if (tau <= 0) return 0;
+    if (zeta < 1) { const s = Math.sqrt(1 - zeta * zeta); return (omega / s) * Math.exp(-zeta * omega * tau) * Math.sin(omega * s * tau); }
+    return omega * omega * tau * Math.exp(-omega * tau);
+  }
+  const ring = (tau, decay = 9, omega = 26) => (tau <= 0 ? 0 : Math.exp(-decay * tau) * Math.sin(omega * tau));
+  function rng(seed = 1) { let s = (seed >>> 0) || 1; return () => { s ^= s << 13; s ^= s >>> 17; s ^= s << 5; return (s >>> 0) / 4294967296; }; }
+  // Hermite por nós {t, x, y}: o caminho da mão / do ponto.
+  function spline(K, t) {
+    if (t <= K[0].t) return [K[0].x, K[0].y];
+    const L = K.length; if (t >= K[L - 1].t) return [K[L - 1].x, K[L - 1].y];
+    let i = 0; while (K[i + 1].t < t) i++;
+    const a = K[i], b = K[i + 1], h = b.t - a.t, u = (t - a.t) / h, p = K[Math.max(0, i - 1)], n = K[Math.min(L - 1, i + 2)];
+    const m0 = [(b.x - p.x) / (b.t - p.t) * h, (b.y - p.y) / (b.t - p.t) * h], m1 = [(n.x - a.x) / (n.t - a.t) * h, (n.y - a.y) / (n.t - a.t) * h];
+    const h00 = 2 * u ** 3 - 3 * u ** 2 + 1, h10 = u ** 3 - 2 * u ** 2 + u, h01 = -2 * u ** 3 + 3 * u ** 2, h11 = u ** 3 - u ** 2;
+    return [h00 * a.x + h10 * m0[0] + h01 * b.x + h11 * m1[0], h00 * a.y + h10 * m0[1] + h01 * b.y + h11 * m1[1]];
+  }
+
+  // ── entrada ────────────────────────────────────────────────────────────────────────────────────────────────
+  // Palavra que pousa: mola com subida e escala; a opacidade vai na frente da mola para nunca ler como fade.
+  function wordRise(t, t0, { zeta = 0.62, omega = 20, dist = 28, s0 = 0.92, fade = 1.6 } = {}) {
+    const k = spring(t - t0, zeta, omega);
+    return { k, op: clamp(k * fade), y: (1 - k) * dist, s: s0 + (1 - s0) * k };
+  }
+  // Letra que cai e achata pela velocidade (squash), escalonada.
+  function letterDrop(t, t0, i, { stagger = 0.05, zeta = 0.5, omega = 24, dist = 60, squash = 0.006, max = 0.22 } = {}) {
+    const tau = t - t0 - i * stagger, k = spring(tau, zeta, omega), sq = clamp(Math.abs(springVel(tau, zeta, omega)) * squash, 0, max);
+    return { k, op: clamp(k * 1.6), y: (1 - k) * -dist, sx: 1 + sq * 0.6, sy: 1 - sq };
+  }
+  function popIn(t, t0, { zeta = 0.62, omega = 16, rise = 34, s0 = 0.9, fade = 1.5 } = {}) {
+    const k = spring(t - t0, zeta, omega);
+    return { k, op: clamp(k * fade), s: s0 + (1 - s0) * k, dy: (1 - k) * rise };
+  }
+  function typeOn(t, t0, txt, { cps = 30 } = {}) { const n = clamp(Math.floor((t - t0) * cps), 0, txt.length); return { n, str: txt.slice(0, n), done: n >= txt.length }; }
+  // Traço desenhado (SVG stroke-dashoffset): 0 → 1 do comprimento.
+  const drawOn = (t, t0, t1, c = ease.cubicInOut) => c(seg(t, t0, t1));
+
+  // ── carry: a próxima cena nasce desta ─────────────────────────────────────────────────────────────────────
+  // Um retângulo vira outro (botão → janela, foto → pílula). Com spring: {zeta, omega}.
+  function morphRect(t, t0, t1, A, B, { curve = ease.expoOut, spring: sp = null } = {}) {
+    const k = sp ? spring(t - t0, sp.zeta ?? 0.7, sp.omega ?? 14) : curve(seg(t, t0, t1));
+    const x = lerp(A.x, B.x, k), y = lerp(A.y, B.y, k), w = lerp(A.w, B.w, k), h = lerp(A.h, B.h, k);
+    return { k, x, y, w, h, r: lerp(A.r ?? 0, B.r ?? 0, k) };
+  }
+  // Círculo que abre do assunto até cobrir o quadro. Regra da casa: inOut cúbico de .3–.4 s, borda suave.
+  function iris(t, t0, t1, cx, cy, { W = 1080, H = 1920, curve = ease.cubicInOut, r0 = 0 } = {}) {
+    const k = curve(seg(t, t0, t1)), far = Math.max(Math.hypot(cx, cy), Math.hypot(W - cx, cy), Math.hypot(cx, H - cy), Math.hypot(W - cx, H - cy)) + 4;
+    return { k, r: lerp(r0, far, k) };
+  }
+  // Mergulho em escala log até o alvo (mundo) encher a tela; devolve a câmera {x, y, zoom} que faz isso.
+  function zoomThrough(t, t0, t1, from, target, { W = 1080, H = 1920, curve = ease.cubicInOut, fit = 'cover' } = {}) {
+    const k = curve(seg(t, t0, t1)), zEnd = fit === 'cover' ? Math.max(W / target.w, H / target.h) : Math.min(W / target.w, H / target.h);
+    return { k, x: lerp(from.x, target.x + target.w / 2, k), y: lerp(from.y, target.y + target.h / 2, k), zoom: Math.exp(lerp(Math.log(from.zoom), Math.log(zEnd), k)) };
+  }
+  // Pulo em arco de um lugar ao outro (pouse com impact).
+  function hop(t, t0, t1, a, b, { height = 160, curve = ease.smooth } = {}) {
+    const k = curve(seg(t, t0, t1));
+    return { k, x: lerp(a.x, b.x, k), y: lerp(a.y, b.y, k) - Math.sin(k * Math.PI) * height };
+  }
+  // Item i de n viaja em arco até o lugar novo, em leque e escalonado.
+  function gather(t, t0, t1, i, n, a, b, { stagger = 0.06, arc = 90, spin = 0.25, curve = ease.cubicInOut } = {}) {
+    const k = curve(seg(t, t0 + i * stagger, t1 + i * stagger)), o = i - (n - 1) / 2, bump = Math.sin(k * Math.PI);
+    return { k, x: lerp(a.x, b.x, k), y: lerp(a.y, b.y, k) - bump * arc, rot: bump * o * spin };
+  }
+
+  // Vários movimentos de um mesmo valor em sequência: passos [[t0, dur, v1, curva?], …] (da clínica, 13/10).
+  function chain(t, v0, passos) { let v = v0; for (const [t0, d, v1, c] of passos) { if (t < t0) break; v = lerp(v, v1, (c || ease.cubicInOut)(seg(t, t0, t0 + d))); } return v; }
+  // Carry em tela: A (mundo, visto pela câmera em t0) → B (mundo, visto em t1), interpolado NA TELA e devolvido ao mundo
+  // pela câmera de agora. O que é carregado nunca fica para trás nem sai do quadro durante um chicote (clínica, 13/10).
+  // camAt(t) → {x, y, zoom, rot}; arco em px de tela (bump para cima).
+  function carryTela(t, t0, t1, A, B, camAt, { curve = ease.cubicInOut, arco = 0, W = 1080, H = 1920 } = {}) {
+    const k = curve(seg(t, t0, t1)), sa = project(view(camAt(t0), { W, H }), A.x, A.y), sb = project(view(camAt(t1), { W, H }), B.x, B.y);
+    const [x, y] = unproject(view(camAt(t), { W, H }), lerp(sa[0], sb[0], k), lerp(sa[1], sb[1], k) - arco * Math.sin(Math.PI * clamp(k)));
+    return { x, y, k };
+  }
+
+  // ── contato ────────────────────────────────────────────────────────────────────────────────────────────────
+  function impact(t, tHit, { decay = 7, omega = 22, sqx = 0.12, sqy = 0.15 } = {}) { const r = ring(t - tHit, decay, omega); return { r, sx: 1 + r * sqx, sy: 1 - r * sqy }; }
+  function press(t, tc, { depth = 0.14, decay = 10, omega = 30 } = {}) { const d = t - tc, sq = d > 0 ? ring(d, decay, omega) * depth : 0; return { s: 1 - Math.abs(sq), down: d > 0 }; }
+  // Clique (medido no .aep do Click VFX da MahdiEdits, 05-pesquisa/referencias/2026-10-12-click-vfx-mahdiedits.md):
+  // o aperto começa em tc; cursor 1 → .636 em `down` s e volta em `up` s (Easy Ease); botão 1 → .875 no mesmo tempo.
+  // Anel pequeno de apoio (cliques em rajada): r0 → r1 em `dur`. Para o anel grande use anelClique().
+  const easyEase = bezier(1 / 3, 0, 2 / 3, 1);
+  function click(t, tc, { dip = 0.636, btn = 0.875, down = 0.233, up = 0.233, r0 = 12, r1 = 120, dur = 0.5 } = {}) {
+    const d = t - tc;
+    const k = d < 0 ? 0 : d < down ? easyEase(d / down) : 1 - easyEase(seg(d, down, down + up));
+    const u = seg(d, 0, dur);
+    return { s: 1 - (1 - dip) * k, btn: 1 - (1 - btn) * k, ring: d >= 0 && u < 1 ? { r: lerp(r0, r1, ease.quartOut(u)), op: (1 - u) * (1 - u), w: lerp(6, 1.5, u) } : null };
+  }
+  // Anel grande do clique: nasce no aperto e cresce até sair do quadro, sem fade (some porque sai da tela).
+  // Raio = r1 · bezier(.145, 0, 0, 1)(d / 2,883), r1 = 1,17 × a distância até o canto mais longe.
+  const anelCurva = bezier(0.145, 0, 0, 1);
+  function anelClique(t, tc, x, y, { W = 1080, H = 1920, dur = 2.883 } = {}) {
+    const d = t - tc; if (d < 0 || d > dur) return null;
+    const far = Math.max(Math.hypot(x, y), Math.hypot(W - x, y), Math.hypot(x, H - y), Math.hypot(W - x, H - y));
+    return { r: 1.17 * far * anelCurva(d / dur), k: d / dur };
+  }
+  // Desenha o anel visto através de uma grade de pontos, com glow em tela (screen). k = escala do original (W/2357).
+  const _fx = {};
+  function desenhaAnel(ctx, x, y, r, { cor = '#C8102E', k = 1080 / 2357, glow = 0.59 } = {}) {
+    if (!r || r < 1) return;
+    const Wc = ctx.canvas.width, Hc = ctx.canvas.height;
+    if (!_fx.off || _fx.off.width !== Wc) {
+      _fx.off = document.createElement('canvas'); _fx.off.width = Wc; _fx.off.height = Hc;
+      const p = document.createElement('canvas'), pas = Math.max(4, Math.round(21.6 * k)); p.width = p.height = pas;
+      const pg = p.getContext('2d'); pg.fillStyle = '#fff'; pg.beginPath(); pg.arc(pas / 2, pas / 2, 10.9 * k / 2, 0, 6.2832); pg.fill();
+      _fx.pat = p;
+    }
+    const o = _fx.off.getContext('2d');
+    o.setTransform(1, 0, 0, 1, 0, 0); o.globalCompositeOperation = 'source-over'; o.clearRect(0, 0, Wc, Hc);
+    o.filter = `blur(${(40 * k).toFixed(1)}px)`; o.strokeStyle = cor; o.lineWidth = 103 * k;
+    o.beginPath(); o.arc(x, y, r, 0, 6.2832); o.stroke(); o.filter = 'none';
+    o.globalCompositeOperation = 'destination-in'; o.fillStyle = o.createPattern(_fx.pat, 'repeat'); o.fillRect(0, 0, Wc, Hc);
+    ctx.save(); ctx.drawImage(_fx.off, 0, 0);
+    ctx.globalCompositeOperation = 'screen'; ctx.globalAlpha = glow;
+    ctx.filter = `blur(${(40 * k).toFixed(1)}px)`; ctx.drawImage(_fx.off, 0, 0);
+    ctx.filter = `blur(${(120 * k).toFixed(1)}px)`; ctx.drawImage(_fx.off, 0, 0);
+    ctx.restore();
+  }
+  // Tremor que decai depois de um pouso; zero antes do golpe; determinístico.
+  function shake(t, tHit, { amp = 8, decay = 9, freq = 17, seed = 1 } = {}) {
+    const tau = t - tHit; if (tau <= 0) return { x: 0, y: 0, rot: 0 };
+    const r = rng(seed), fx = freq * (1 + 0.1 * r()), fy = freq * (1.31 + 0.1 * r()), e = amp * Math.exp(-decay * tau), w = 2 * Math.PI * tau;
+    return { x: e * Math.sin(w * fx), y: 0.7 * e * Math.sin(w * fy), rot: 0.0012 * e * Math.sin(w * freq * 0.77) };
+  }
+
+  // ── câmera ─────────────────────────────────────────────────────────────────────────────────────────────────
+  // Operador: want(t) diz o que enquadrar {x, y, zoom, w}; uma mola por eixo persegue (posição ζ .82, zoom em log
+  // ζ .95 a .8 w), integrada uma vez a 240 Hz e amostrada. Assim ela atrasa, inclina e assenta, e cada quadro
+  // continua função de t. Saída quantizada (1/16 px, 0,05 % de zoom): câmera assentada repete o quadro exato.
+  // Estalo mais rápido que a mola: mire o pouso ~.15 s antes.
+  function operador(want, { dur, hz = 240, zeta = 0.82, zetaZ = 0.95 } = {}) {
+    const n = Math.ceil(dur * hz) + 2, X = new Float64Array(n), Y = new Float64Array(n), Z = new Float64Array(n), dt = 1 / hz;
+    const w0 = want(0); let x = w0.x, y = w0.y, lz = Math.log(w0.zoom), vx = 0, vy = 0, vz = 0;
+    for (let i = 0; i < n; i++) {
+      const g = want(i * dt), w = g.w ?? 8, wz = 0.8 * w;
+      vx += (-2 * zeta * w * vx - w * w * (x - g.x)) * dt; vy += (-2 * zeta * w * vy - w * w * (y - g.y)) * dt;
+      vz += (-2 * zetaZ * wz * vz - wz * wz * (lz - Math.log(g.zoom))) * dt;
+      x += vx * dt; y += vy * dt; lz += vz * dt;
+      X[i] = Math.round(x * 16) / 16; Y[i] = Math.round(y * 16) / 16; Z[i] = Math.round(Math.exp(lz) * 2000) / 2000;
+    }
+    return { at(t) { const f = clamp(t * hz, 0, n - 1), i = Math.floor(f), j = Math.min(n - 1, i + 1), u = f - i; return { x: lerp(X[i], X[j], u), y: lerp(Y[i], Y[j], u), zoom: lerp(Z[i], Z[j], u), rot: 0 }; } };
+  }
+  // Alvo em degraus: a cada chave {t, x, y, zoom, w} o operador passa a perseguir aquele enquadramento.
+  function alvos(keys) { return t => { let k = keys[0]; for (const c of keys) if (c.t <= t) k = c; return k; }; }
+  // Mão do operador: duas senoides lentas. amp em px de tela; env(t) 0..1 baixa nos respiros (nunca zero: regra da casa).
+  function flutuar(t, amp = 4) { return { x: amp * (Math.sin(1.7 * t) + 0.6 * Math.sin(2.9 * t + 1)), y: amp * (Math.sin(1.3 * t + 2) + 0.5 * Math.sin(3.3 * t)) }; }
+  // Matriz [a, b, c, d, e, f] de uma camada a `depth` vista pela câmera: CSS matrix(...) com transform-origin 0 0.
+  function view(cam, { W = 1080, H = 1920, depth = 0 } = {}) {
+    const f = 1 / (1 + Math.max(-0.9, depth)), cx = W / 2 + (cam.x - W / 2) * f, cy = H / 2 + (cam.y - H / 2) * f;
+    const z = Math.exp(Math.log(cam.zoom) * f), c = Math.cos((cam.rot || 0) * f) * z, s = Math.sin((cam.rot || 0) * f) * z;
+    return [c, s, -s, c, W / 2 - (c * cx - s * cy), H / 2 - (s * cx + c * cy)];
+  }
+  const project = (M, x, y) => [M[0] * x + M[2] * y + M[4], M[1] * x + M[3] * y + M[5]];
+  const unproject = (M, x, y) => { const d = M[0] * M[3] - M[1] * M[2], u = x - M[4], v = y - M[5]; return [(M[3] * u - M[2] * v) / d, (M[0] * v - M[1] * u) / d]; };
+  function projectBox(M, b) {
+    const P = [[b.x, b.y], [b.x + b.w, b.y], [b.x, b.y + b.h], [b.x + b.w, b.y + b.h]].map(p => project(M, p[0], p[1]));
+    const xs = P.map(p => p[0]), ys = P.map(p => p[1]), x0 = Math.min(...xs), y0 = Math.min(...ys);
+    return { x: x0, y: y0, w: Math.max(...xs) - x0, h: Math.max(...ys) - y0 };
+  }
+  // Quanto os cantos da tela andam entre duas câmeras: a parte da câmera no __motion (que dimensiona o obturador).
+  function screenTravel(c0, c1, { W = 1080, H = 1920 } = {}) {
+    const A = view(c0, { W, H }), B = view(c1, { W, H }); let d = 0;
+    for (const [sx, sy] of [[0, 0], [W, 0], [0, H], [W, H], [W / 2, H / 2]]) { const [wx, wy] = unproject(A, sx, sy), p = project(B, wx, wy); d = Math.max(d, Math.hypot(p[0] - sx, p[1] - sy)); }
+    return d;
+  }
+  // Grade de pontos distante: algo para o movimento deslizar contra. Pontos com `px` constante na tela.
+  function lattice(cam, { W = 1080, H = 1920, depth = 1.2, spacing = 44, px = 1.5 } = {}) {
+    const M = view(cam, { W, H, depth }), c = [[0, 0], [W, 0], [0, H], [W, H]].map(p => unproject(M, p[0], p[1]));
+    const xs = c.map(p => p[0]), ys = c.map(p => p[1]);
+    return { M, spacing, r: px / Math.hypot(M[0], M[1]), x0: Math.floor(Math.min(...xs) / spacing) * spacing, x1: Math.max(...xs), y0: Math.floor(Math.min(...ys) / spacing) * spacing, y1: Math.max(...ys) };
+  }
+
+  const TK = { clamp, lerp, seg, bezier, ease, tween, chain, carryTela, spring, springVel, ring, rng, spline,
+    wordRise, letterDrop, popIn, typeOn, drawOn, morphRect, iris, zoomThrough, hop, gather,
+    impact, press, click, anelClique, desenhaAnel, shake, operador, alvos, flutuar, view, project, unproject, projectBox, screenTravel, lattice };
+  root.TK = TK;
+  if (typeof module === 'object' && module.exports) module.exports = TK;
+})(typeof window !== 'undefined' ? window : globalThis);

package/lib/estudio/editor.js

@@ -0,0 +1,290 @@
+/**
+ * editor.js — o editor de vídeo por comando: `estudio_editar` reabre o plano que a máquina de motion usou
+ * (cenas.json, salvo junto do vídeo), aplica as mudanças, re-renderiza e guarda a versão (v1, v2…).
+ *
+ * Operações (cada mudança é {op, ...}; o modelo traduz o pedido em linguagem natural):
+ *   texto {cena, campo?='titulo', valor} · texto {de, para}   cor {fundo?, destaque?, tinta?} · cor {paleta}
+ *   fonte {titulo?, texto?, destaque?}   ritmo {fator} (0.8 = mais rápido) · duracao {cena, segundos} · duracao {total}
+ *   remover {cena} · mover {cena, para} · duplicar {cena, para?}   (cena = 1, 2, 3…)
+ *   trilha {valor: false | "busca" | caminho}   volume {alvo: voz|trilha|sfx, db}   formato {valor: 9:16|1:1|16:9}
+ * Com narração, o tempo é da voz: ritmo, duração, remover, mover e duplicar ficam de fora (avisa).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const maq = () => require('./maquina.js');
+const dir = () => require('./maquina-diretor.js');
+const ler = (f) => JSON.parse(fs.readFileSync(f, 'utf8'));
+const gravar = (f, o) => { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, JSON.stringify(o)); };
+const ARQ = (pasta) => path.join(pasta, 'cenas.json');
+const IDX = (pasta) => path.join(pasta, 'versoes', 'indice.json');
+const arred = (v, n = 100) => Math.round(v * n) / n;
+
+// ── versões ──────────────────────────────────────────────────────────────
+
+function indice(pasta) {
+    try { return ler(IDX(pasta)); } catch { return { atual: 0, versoes: [] }; }
+}
+function registrarVersao(pasta, spec, video, resumo) {
+    const ix = indice(pasta);
+    const n = ix.versoes.reduce((m, v) => Math.max(m, v.n), 0) + 1;
+    const d = path.join(pasta, 'versoes', 'v' + n);
+    fs.mkdirSync(d, { recursive: true });
+    gravar(path.join(d, 'cenas.json'), spec);
+    let arq = null;
+    if (video && fs.existsSync(video)) { arq = path.join(d, 'video.mp4'); fs.copyFileSync(video, arq); }
+    ix.versoes.push({ n, resumo: resumo || '', previa: !!spec.previa, video: arq ? path.relative(pasta, arq) : null });
+    ix.atual = n;
+    gravar(IDX(pasta), ix);
+    gravar(ARQ(pasta), spec);
+    return n;
+}
+
+/** Gancho da máquina: guarda o plano e abre a versão. Prévia só guarda o plano (sem versão). */
+function salvarSpec(pasta, { pl, args = {}, trilha = null, voz = null, video, previa = false }) {
+    const { saida, ...resto } = args;
+    const spec = { pl, args: resto, trilha, voz, volumes: {}, previa: !!previa };
+    if (previa) {
+        gravar(ARQ(pasta), spec);
+        let v = video;
+        if (video && fs.existsSync(video)) { v = path.join(pasta, 'video-previa.mp4'); if (v !== video) fs.copyFileSync(video, v); }
+        return { video: v, versao: null };
+    }
+    fs.rmSync(path.join(pasta, 'versoes'), { recursive: true, force: true });
+    return { versao: registrarVersao(pasta, spec, video, 'original'), video };
+}
+
+// ── operações sobre o plano ──────────────────────────────────────────────
+
+function refluir(pl) {
+    let t = 0;
+    pl.cenas.forEach((c, i) => { c.inicio = arred(t, 1000); t += c.dur; if (pl.cenas[i + 1]) c.proxBg = null; });
+    pl.cenas.forEach((c, i) => { if (pl.cenas[i + 1]) c.proxBg = pl.cenas[i + 1].pal.bg; else delete c.proxBg; });
+    pl.duracao = arred(t);
+}
+const idx = (pl, n) => { const i = Number(n) - 1; return Number.isInteger(i) && i >= 0 && i < pl.cenas.length ? i : -1; };
+const limpo = (s) => String(s == null ? '' : s).replace(/[\r\n]+/g, ' ').trim().slice(0, 200);
+const hexOk = (h) => /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(String(h || ''));
+const hex = (h) => (String(h).startsWith('#') ? String(h) : '#' + h);
+
+function recolorir(pl, paleta) {
+    const velho = pl.variacoes || {};
+    const novo = maq().variacoes(paleta);
+    pl.cenas.forEach((c) => {
+        const chave = ['normal', 'fundo', 'destaque'].find((k) => velho[k] && velho[k].bg === (c.pal && c.pal.bg)) || 'normal';
+        c.pal = { ...novo[chave] };
+    });
+    pl.paleta = paleta; pl.variacoes = novo;
+    if (pl.legenda) {
+        const ac = paleta.destaque, C = maq().contraste;
+        pl.legenda.corDestaque = C(ac, '#000000') >= 4.5 ? ac : (C(paleta.tinta, '#000000') >= 4.5 ? paleta.tinta : '#FFD54A');
+    }
+}
+
+const ESTRUTURAIS = new Set(['ritmo', 'duracao', 'remover', 'mover', 'duplicar']);
+
+/** Aplica uma mudança ao spec. Devolve {ok, resumo} ou {ok:false, error}. */
+function aplicar(spec, m, ctx = {}) {
+    const pl = spec.pl;
+    const op = String(m && m.op || '').toLowerCase().replace(/-/g, '_');
+    if (spec.voz && ESTRUTURAIS.has(op)) return { ok: false, error: `com narração o tempo é da voz: "${op}" não se aplica (gere de novo sem voz, ou mude só texto, cor, fonte, trilha e volume).` };
+    const falta = (n) => ({ ok: false, error: `não existe a cena ${n} (o vídeo tem ${pl.cenas.length}).` });
+    switch (op) {
+        case 'texto': {
+            if (m.de != null) {
+                let n = 0;
+                const tr = (o) => { for (const k of Object.keys(o)) { if (typeof o[k] === 'string' && o[k].includes(m.de)) { o[k] = o[k].split(m.de).join(String(m.para == null ? '' : m.para)); n++; } else if (Array.isArray(o[k])) o[k] = o[k].map((x) => (typeof x === 'string' && x.includes(m.de) ? (n++, x.split(m.de).join(String(m.para == null ? '' : m.para))) : x)); } };
+                pl.cenas.forEach((c) => tr(c));
+                return n ? { ok: true, resumo: `"${m.de}" → "${m.para}" em ${n} campo(s)` } : { ok: false, error: `não achei "${m.de}" no texto das cenas.` };
+            }
+            const i = idx(pl, m.cena); if (i < 0) return falta(m.cena);
+            const campo = String(m.campo || 'titulo');
+            if (!/^(titulo|sub|texto|autor|botao|rotulo|valor|antes|depois|tela|fala)$/.test(campo) && !(campo in pl.cenas[i])) return { ok: false, error: 'campo desconhecido: ' + campo };
+            pl.cenas[i][campo] = Array.isArray(m.valor) ? m.valor.map(limpo) : limpo(m.valor);
+            return { ok: true, resumo: `cena ${m.cena}: ${campo} = "${String(m.valor).slice(0, 40)}"` };
+        }
+        case 'cor': case 'paleta': {
+            let p = { ...pl.paleta };
+            if (m.paleta || (m.valor && !m.fundo && !m.destaque && !m.tinta)) {
+                const nome = String(m.paleta || m.valor).toLowerCase();
+                const base = dir().PALETAS[nome];
+                if (!base) return { ok: false, error: 'paleta desconhecida: ' + nome + ' (' + Object.keys(dir().PALETAS).join(', ') + ')' };
+                p = { fundo: base.fundo, tinta: base.tinta, destaque: base.destaque };
+                if (pl.direcao) pl.direcao.paleta = nome;
+            }
+            for (const k of ['fundo', 'tinta', 'destaque']) if (m[k] != null) { if (!hexOk(m[k])) return { ok: false, error: `cor inválida em ${k}: ${m[k]}` }; p[k] = hex(m[k]); }
+            recolorir(pl, p);
+            return { ok: true, resumo: `cores: fundo ${p.fundo}, tinta ${p.tinta}, destaque ${p.destaque}` };
+        }
+        case 'fonte': {
+            let n = 0;
+            for (const k of ['titulo', 'texto', 'destaque']) if (m[k]) { pl.fontes[k] = limpo(m[k]).slice(0, 40); n++; }
+            if (m.valor && !n) { pl.fontes.titulo = pl.fontes.texto = pl.fontes.destaque = limpo(m.valor).slice(0, 40); n = 1; }
+            if (pl.legenda) { pl.legenda.fonte = pl.fontes.texto; pl.legenda.fonteDestaque = pl.fontes.destaque; }
+            return n ? { ok: true, resumo: 'fontes: ' + JSON.stringify(pl.fontes) } : { ok: false, error: 'fonte pede titulo, texto ou destaque.' };
+        }
+        case 'ritmo': {
+            const f = Number(m.fator);
+            if (!(f > 0.2 && f < 5)) return { ok: false, error: 'ritmo pede fator entre 0.2 e 5 (0.8 = 20% mais rápido).' };
+            pl.cenas.forEach((c) => { c.dur = arred(Math.max(1.2, Math.min(7.5, c.dur * f))); });
+            refluir(pl);
+            return { ok: true, resumo: `ritmo ×${f}: ${pl.duracao}s` };
+        }
+        case 'duracao': {
+            if (m.total != null) {
+                const k = Number(m.total) / pl.duracao;
+                if (!(k > 0.2 && k < 5)) return { ok: false, error: 'duração total fora do limite.' };
+                pl.cenas.forEach((c) => { c.dur = arred(Math.max(1.2, Math.min(7.5, c.dur * k))); });
+            } else {
+                const i = idx(pl, m.cena); if (i < 0) return falta(m.cena);
+                const s = Number(m.segundos); if (!(s >= 1 && s <= 10)) return { ok: false, error: 'segundos entre 1 e 10.' };
+                pl.cenas[i].dur = arred(s);
+            }
+            refluir(pl);
+            return { ok: true, resumo: `duração: ${pl.duracao}s` };
+        }
+        case 'remover': {
+            const i = idx(pl, m.cena); if (i < 0) return falta(m.cena);
+            if (pl.cenas.length < 2) return { ok: false, error: 'o vídeo precisa de ao menos 1 cena.' };
+            pl.cenas.splice(i, 1); pl.trocas.splice(Math.max(0, i - 1), 1);
+            refluir(pl);
+            return { ok: true, resumo: `cena ${m.cena} removida (${pl.cenas.length} cenas, ${pl.duracao}s)` };
+        }
+        case 'mover': {
+            const i = idx(pl, m.cena), j = idx(pl, m.para);
+            if (i < 0) return falta(m.cena); if (j < 0) return falta(m.para);
+            const [c] = pl.cenas.splice(i, 1); pl.cenas.splice(j, 0, c);
+            refluir(pl);
+            return { ok: true, resumo: `cena ${m.cena} → posição ${m.para}` };
+        }
+        case 'duplicar': {
+            const i = idx(pl, m.cena); if (i < 0) return falta(m.cena);
+            const para = m.para == null ? i + 1 : Math.max(0, Math.min(pl.cenas.length, Number(m.para) - 1));
+            pl.cenas.splice(para, 0, JSON.parse(JSON.stringify(pl.cenas[i])));
+            pl.trocas.splice(Math.max(0, para - 1), 0, pl.trocas[Math.min(pl.trocas.length - 1, Math.max(0, para - 1))] || 'corte');
+            refluir(pl);
+            return { ok: true, resumo: `cena ${m.cena} duplicada (${pl.cenas.length} cenas, ${pl.duracao}s)` };
+        }
+        case 'trilha': {
+            const v = m.valor;
+            if (v === false || v === 0 || /^(nenhuma|sem|sem_trilha|false|off|nao|não)$/i.test(String(v))) { spec.trilha = null; spec.semTrilha = true; pl.bpm = 0; return { ok: true, resumo: 'sem trilha' }; }
+            if (typeof v === 'string' && fs.existsSync(v)) { spec.trilha = { arquivo: v, inicio: 0 }; spec.semTrilha = false; return { ok: true, resumo: 'trilha: ' + path.basename(v) }; }
+            spec.buscaTrilha = typeof v === 'string' && v !== 'true' ? v : null; spec.semTrilha = false; spec.trilha = null; spec.trocarTrilha = true;
+            return { ok: true, resumo: 'trilha nova' + (spec.buscaTrilha ? ': ' + spec.buscaTrilha : '') };
+        }
+        case 'volume': {
+            const alvo = String(m.alvo || '').toLowerCase();
+            if (!['voz', 'trilha', 'sfx'].includes(alvo)) return { ok: false, error: 'volume pede alvo voz, trilha ou sfx.' };
+            const db = m.mudo ? -60 : Number(m.db);
+            if (!isFinite(db) || db < -60 || db > 12) return { ok: false, error: 'volume pede db entre -60 e 12 (0 = como a máquina mixou).' };
+            spec.volumes = { ...(spec.volumes || {}), [alvo]: db };
+            return { ok: true, resumo: `volume ${alvo}: ${db} dB` };
+        }
+        case 'formato': {
+            const f = maq().FORMATOS[String(m.valor)]; if (!f) return { ok: false, error: 'formato: 9:16, 1:1 ou 16:9.' };
+            pl.w = f[0]; pl.h = f[1]; pl.formato = String(m.valor);
+            if (pl.legenda) { pl.legenda.tamanho = pl.h > pl.w ? 52 : 44; pl.legenda.y = pl.h > pl.w ? 0.91 : 0.9; }
+            return { ok: true, resumo: 'formato ' + m.valor };
+        }
+        default:
+            return { ok: false, error: 'mudança desconhecida: "' + op + '" (texto, cor, fonte, ritmo, duracao, remover, mover, duplicar, trilha, volume, formato).' };
+    }
+}
+
+// ── render ───────────────────────────────────────────────────────────────
+
+async function renderizarSpec(spec, pasta, { previa = false, deps = {}, semRede = false } = {}) {
+    const M = maq();
+    const pl = spec.pl;
+    const renderizar = deps.renderizar || require('./effectcraft.js').renderizar;
+    const tm = M.tempos(pl);
+    const r = await renderizar({ pasta, script: M.script(pl), comp: 'MAIN', fontes: M.fontesDoPlano(pl), conferir: previa ? [] : tm.map((x) => x.conferir), previa });
+    if (!r.ok) return r;
+    if (previa) {
+        const v = path.join(pasta, 'video-previa.mp4');
+        fs.copyFileSync(r.video, v);
+        return { ok: true, video: v, quadros: r.quadros || [], mix: null };
+    }
+    const som = require('./maquina-som.js');
+    const eventos = M.lerSons(r.saida);
+    const final = path.join(pasta, 'video-motion.mp4');
+    let mix = { ok: false, video: r.video }, sons = [];
+    try {
+        const vol = spec.volumes || {};
+        const indice = deps.sfxIndice || await som.prepararBiblioteca({ assunto: spec.args && spec.args.assunto || '', acoes: [...new Set(eventos.map((e) => e.tipo))], rede: !semRede });
+        sons = som.escolherSons(eventos, { assunto: spec.args && spec.args.assunto || '', indice, semente: pl.semente || 1 });
+        // a voz mais alta = o resto mais baixo (o final fecha em −14 LUFS, então só a diferença conta)
+        const dv = vol.voz || 0;
+        const mixar = deps.mixar || som.mixar;
+        mix = mixar({ pasta, mudo: r.video, saida: final, sons, trilha: spec.trilha && spec.trilha.arquivo, trilhaInicio: spec.trilha ? spec.trilha.inicio || 0 : 0, voz: spec.voz && spec.voz.mp3, duracao: pl.duracao, vol: { trilha: (vol.trilha || 0) - dv, sfx: (vol.sfx || 0) - dv } });
+    } catch (e) { mix = { ok: false, error: e.message, video: r.video }; }
+    let video = mix.ok ? mix.video : r.video;
+    if (video !== final && fs.existsSync(video)) { fs.copyFileSync(video, final); video = final; }
+    return { ok: true, video, quadros: r.quadros || [], mix, lufs: mix.ok ? mix.lufs : null, aviso: mix.ok ? undefined : 'o vídeo saiu sem a mixagem de áudio: ' + (mix.error || 'sem ffmpeg') };
+}
+
+// ── a ferramenta ─────────────────────────────────────────────────────────
+
+/**
+ * estudio_editar. `args`: {mudancas:[...], voltar_para?, previa?, final?, listar?}. `deps`: renderizar, mixar, sfxIndice, trilha, semRede.
+ */
+async function editar(args = {}, { pasta, deps = {} } = {}) {
+    if (!pasta) return { ok: false, error: 'faltou a pasta do projeto.' };
+    const ix = indice(pasta);
+    if (!fs.existsSync(ARQ(pasta))) return { ok: false, error: 'esse vídeo não tem cenas.json: só dá para editar o que a máquina de motion (estudio_motion) gerou.' };
+    const lista = () => ix.versoes.map((v) => ({ n: v.n, resumo: v.resumo, previa: v.previa || undefined, atual: v.n === ix.atual || undefined }));
+    if (args.listar) return { ok: true, atual: ix.atual, versoes: lista() };
+
+    if (args.voltar_para != null) {
+        const v = ix.versoes.find((x) => x.n === Number(args.voltar_para));
+        if (!v) return { ok: false, error: `não existe a v${args.voltar_para} (há ${ix.versoes.map((x) => 'v' + x.n).join(', ') || 'nenhuma'}).` };
+        const spec = ler(path.join(pasta, 'versoes', 'v' + v.n, 'cenas.json'));
+        gravar(ARQ(pasta), spec);
+        ix.atual = v.n; gravar(IDX(pasta), ix);
+        let video = v.video ? path.join(pasta, v.video) : null;
+        if (video && fs.existsSync(video)) { const f = path.join(pasta, 'video-motion.mp4'); fs.copyFileSync(video, f); video = f; }
+        return { ok: true, versao: v.n, video, versoes: lista(), nota: `voltou para a v${v.n}; a próxima mudança vira a v${ix.versoes.reduce((m, x) => Math.max(m, x.n), 0) + 1}.` };
+    }
+
+    // O plano limita as edições guardadas por vídeo (grátis 3). Prévia e a versão original não contam.
+    const gastas = indice(pasta).versoes.filter((v) => !v.previa && v.resumo !== 'original').length;
+    const lim = await (deps.cabeMais ? deps.cabeMais(gastas) : require('../limites.js').cabeMais('versoesEditor', gastas));
+    if (!lim.ok && !args.previa) return { ok: false, error: lim.error + ' Dá para voltar a uma versão (voltar_para) ou ver as prévias.' };
+
+    const spec = ler(ARQ(pasta));
+    const mudancas = Array.isArray(args.mudancas) ? args.mudancas : [];
+    if (!mudancas.length && !args.final) return { ok: false, error: 'mudancas está vazio (ou use final:true para renderizar a prévia em qualidade final).' };
+    const feitas = [], recusadas = [];
+    for (const m of mudancas) {
+        const r = aplicar(spec, m, { pasta });
+        (r.ok ? feitas : recusadas).push(r.ok ? r.resumo : r.error);
+    }
+    if (!feitas.length && !args.final) return { ok: false, error: 'nenhuma mudança valeu: ' + recusadas.join(' | ') };
+
+    if (spec.trocarTrilha) {   // trilha nova por busca
+        const semRede = !!(deps.semRede || args.semRede);
+        try {
+            let r;
+            if (deps.trilha) { const t0 = await deps.trilha(pasta, spec.buscaTrilha); r = t0 && t0.arquivo ? t0 : null; }
+            else { r = await require('./maquina-trilha.js').escolher({ chave: dir().achar(String(spec.args && spec.args.assunto || '')).chave, busca: spec.buscaTrilha, pasta, rede: !semRede }); if (!(r && r.arquivo)) r = null; }
+            if (r) { spec.trilha = { arquivo: r.arquivo, inicio: 0 }; spec.pl.bpm = r.bpm || 0; }
+            else recusadas.push('não achei trilha nova; o vídeo fica sem música.');
+        } catch (e) { recusadas.push('trilha: ' + e.message); }
+        delete spec.trocarTrilha;
+    }
+
+    const previa = !!args.previa;
+    spec.previa = previa;
+    const r = await renderizarSpec(spec, pasta, { previa, deps, semRede: !!(deps.semRede || args.semRede) });
+    if (!r.ok) return r;
+    const resumo = feitas.join('; ') || 'render final';
+    // versão: a prévia também entra (marcada), pra dar pra voltar
+    const versao = registrarVersao(pasta, spec, r.video, resumo);
+    return { ok: true, versao, previa, video: r.video, quadros: r.quadros, duracao: spec.pl.duracao, cenas: spec.pl.cenas.length, feitas, recusadas, versoes: lista2(pasta), lufs: r.lufs, aviso: r.aviso };
+}
+const lista2 = (pasta) => indice(pasta).versoes.map((v) => ({ n: v.n, resumo: v.resumo, previa: v.previa || undefined }));
+
+module.exports = { salvarSpec, aplicar, editar, indice, renderizarSpec, registrarVersao };