primocode 10.16.0 → 10.17.1

package/editor/modelo-projeto/compositions/cenas/3d/motor-three.js

@@ -0,0 +1,728 @@
+// Motor das cenas 3D do kit (compositions/cenas/3d/). Código da skill em cima do three.js r181 (MIT), que fica
+// em assets/three/ com a licença ao lado. Nada é baixado na hora do render.
+//
+// Regra de ouro: tudo é função do tempo da cena. A cena escreve uma função atualizar(t) que põe peças, câmera,
+// luz e rótulos no lugar para aquele t, sem guardar nada do quadro anterior. O mesmo t desenha sempre o mesmo
+// quadro, em qualquer ordem, em qualquer processo do render (é o que deixa o render repetível).
+//
+// Quem chama: o <script> de cada cena do kit, com import() deste arquivo (veja k3d_volume.html). Guia completo:
+// references/3d.md da skill.
+import * as THREE from '../../../assets/three/three.module.min.js';
+import { RoomEnvironment } from '../../../assets/three/RoomEnvironment.js';
+
+export { THREE };
+export const REVISAO = THREE.REVISION;
+
+// ------------------------------------------------------------------------------------------ tempo
+export const lim = (v, a = 0, b = 1) => Math.min(b, Math.max(a, v));
+export const mistura = (a, b, p) => a + (b - a) * p;
+// começa e termina devagar (o movimento "abre parado" e "termina parado")
+export const suave = (p) => { p = lim(p); return p < 0.5 ? 4 * p * p * p : 1 - Math.pow(-2 * p + 2, 3) / 2; };
+// sai rápido e freia no fim
+export const freia = (p) => 1 - Math.pow(1 - lim(p), 3);
+// quanto (0 a 1) de um movimento que começa em `de` e dura `dur` já andou no tempo t
+export const trecho = (t, de, dur, curva = suave) => (dur <= 0 ? (t >= de ? 1 : 0) : curva(lim((t - de) / dur)));
+
+const semAcento = (s) => String(s).normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]/g, '');
+
+// tempo (s da cena) em que a palavra começa; `depois` escolhe a repetição; `padrao` vale quando a fala não tem a
+// palavra (cena aberta sozinha no estúdio, ou palavra trocada)
+export function palavra(C, texto, depois = 0, padrao = depois) {
+  const alvo = semAcento(texto);
+  const p = (C.palavras || []).find((w) => w.t >= depois - 1e-3 && semAcento(w.texto).startsWith(alvo));
+  return p ? p.t : padrao;
+}
+
+// um parâmetro de tempo da cena: número (s da cena), "palavra" ou {palavra, depois, padrao}
+export function momento(C, m, padrao = 0) {
+  if (typeof m === 'number') return m;
+  if (typeof m === 'string') return palavra(C, m, 0, padrao);
+  if (m && typeof m === 'object') {
+    const depois = m.depois == null ? 0 : momento(C, m.depois, 0);
+    return palavra(C, m.palavra || '', depois, m.padrao == null ? padrao : m.padrao);
+  }
+  return padrao;
+}
+
+// ------------------------------------------------------------------------------------------ câmera
+// pose = {alvo: [x, y, z], dist, azim (graus, 0 = de frente, positivo gira para a direita), elev (graus)}
+export function orbita(camera, pose) {
+  const a = (pose.azim * Math.PI) / 180;
+  const e = (pose.elev * Math.PI) / 180;
+  const [x, y, z] = pose.alvo || [0, 0, 0];
+  camera.position.set(x + pose.dist * Math.cos(e) * Math.sin(a), y + pose.dist * Math.sin(e), z + pose.dist * Math.cos(e) * Math.cos(a));
+  camera.lookAt(x, y, z);
+  camera.updateMatrixWorld();
+}
+
+export function misturaPose(p0, p1, k) {
+  const a0 = p0.alvo || [0, 0, 0];
+  const a1 = p1.alvo || a0;
+  return {
+    alvo: [mistura(a0[0], a1[0], k), mistura(a0[1], a1[1], k), mistura(a0[2], a1[2], k)],
+    dist: mistura(p0.dist, p1.dist == null ? p0.dist : p1.dist, k),
+    azim: mistura(p0.azim, p1.azim == null ? p0.azim : p1.azim, k),
+    elev: mistura(p0.elev, p1.elev == null ? p0.elev : p1.elev, k),
+  };
+}
+
+// põe o centro da imagem (para onde a câmera olha) no meio da área [x0, y0, x1, y1] da tela, em pixels
+export function enquadrar(camera, W, H, area) {
+  if (!area) { camera.clearViewOffset(); return; }
+  const cx = (area[0] + area[2]) / 2;
+  const cy = (area[1] + area[3]) / 2;
+  camera.setViewOffset(W, H, W / 2 - cx, H / 2 - cy, W, H);
+}
+
+// distância para uma esfera de raio r caber na área (com folga), com a câmera enquadrada nela
+export function distanciaParaCaber(camera, raio, H, area, folga = 1.12) {
+  const t = Math.tan((camera.fov * Math.PI) / 360);
+  const ah = area[3] - area[1];
+  const aw = area[2] - area[0];
+  const k = t * Math.min(ah, aw) / H;
+  return (raio * folga) / k;
+}
+
+// distância para um volume de largura x altura (na tela) caber na área, com folga
+export function distanciaParaCaixa(camera, largura, altura, H, area, folga = 1.1) {
+  const t = Math.tan((camera.fov * Math.PI) / 360);
+  const ah = area[3] - area[1];
+  const aw = area[2] - area[0];
+  return Math.max((altura / 2) * folga / (t * ah / H), (largura / 2) * folga / (t * aw / H));
+}
+
+// a menor distância em que a caixa (Box3) inteira aparece dentro da área, vista daquela pose (azim, elev, alvo).
+// Mede de verdade: projeta os 8 cantos na câmera enquadrada e procura a distância (busca binária).
+export function distanciaQueCabe(camera, W, H, area, caixa, pose, folga = 1.08) {
+  const cantos = [];
+  for (const x of [caixa.min.x, caixa.max.x]) for (const y of [caixa.min.y, caixa.max.y]) for (const z of [caixa.min.z, caixa.max.z]) cantos.push(new THREE.Vector3(x, y, z));
+  const cx = (area[0] + area[2]) / 2, cy = (area[1] + area[3]) / 2;
+  const hw = (area[2] - area[0]) / 2 / folga, hh = (area[3] - area[1]) / 2 / folga;
+  const v = new THREE.Vector3();
+  const cabe = (d) => {
+    orbita(camera, { ...pose, dist: d });
+    for (const c of cantos) {
+      v.copy(c).project(camera);
+      if (v.z > 1 || v.z < -1) return false;
+      if (Math.abs((v.x * 0.5 + 0.5) * W - cx) > hw || Math.abs((-v.y * 0.5 + 0.5) * H - cy) > hh) return false;
+    }
+    return true;
+  };
+  let lo = camera.near, hi = 1;
+  while (!cabe(hi) && hi < 1e4) hi *= 2;
+  for (let i = 0; i < 40; i++) { const m = (lo + hi) / 2; if (cabe(m)) hi = m; else lo = m; }
+  return hi;
+}
+
+// ------------------------------------------------------------------------------------------ texturas desenhadas
+function texturaDeCanvas(cv) {
+  const tex = new THREE.CanvasTexture(cv);
+  tex.colorSpace = THREE.SRGBColorSpace;
+  return tex;
+}
+
+function hexA(cor, a) {
+  const c = new THREE.Color(cor);
+  return `rgba(${Math.round(c.r * 255)},${Math.round(c.g * 255)},${Math.round(c.b * 255)},${a})`;
+}
+
+// grade do chão com as bordas sumindo (dá profundidade: as linhas convergem para o fundo)
+function texturaDeGrade(corLinha, passos = 24, px = 1024) {
+  const cv = document.createElement('canvas');
+  cv.width = cv.height = px;
+  const g = cv.getContext('2d');
+  g.strokeStyle = corLinha;
+  g.globalAlpha = 0.75;
+  g.lineWidth = Math.max(2, px / 420);
+  for (let i = 0; i <= passos; i++) {
+    const p = Math.round((i / passos) * (px - 2)) + 1;
+    g.beginPath(); g.moveTo(p, 0); g.lineTo(p, px); g.stroke();
+    g.beginPath(); g.moveTo(0, p); g.lineTo(px, p); g.stroke();
+  }
+  // some para as bordas
+  g.globalCompositeOperation = 'destination-in';
+  const r = g.createRadialGradient(px / 2, px / 2, px * 0.12, px / 2, px / 2, px / 2);
+  r.addColorStop(0, 'rgba(0,0,0,1)');
+  r.addColorStop(1, 'rgba(0,0,0,0)');
+  g.fillStyle = r;
+  g.fillRect(0, 0, px, px);
+  return texturaDeCanvas(cv);
+}
+
+let _manchaTex = null;
+function texturaDeMancha() {
+  if (_manchaTex) return _manchaTex;
+  const px = 256;
+  const cv = document.createElement('canvas');
+  cv.width = cv.height = px;
+  const g = cv.getContext('2d');
+  const r = g.createRadialGradient(px / 2, px / 2, 0, px / 2, px / 2, px / 2);
+  r.addColorStop(0, 'rgba(0,0,0,1)');
+  r.addColorStop(0.45, 'rgba(0,0,0,0.55)');
+  r.addColorStop(1, 'rgba(0,0,0,0)');
+  g.fillStyle = r;
+  g.fillRect(0, 0, px, px);
+  _manchaTex = new THREE.CanvasTexture(cv);
+  return _manchaTex;
+}
+
+// ------------------------------------------------------------------------------------------ sólidos
+export function material(cor, { rugosidade = 0.5, metal = 0, verniz = 0.25 } = {}) {
+  return new THREE.MeshPhysicalMaterial({ color: new THREE.Color(cor), roughness: rugosidade, metalness: metal, clearcoat: verniz, clearcoatRoughness: 0.35 });
+}
+
+function sombreia(obj) {
+  obj.traverse((o) => { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } });
+  return obj;
+}
+
+function retanguloArredondado(w, d, r) {
+  r = Math.max(0.001, Math.min(r, w / 2 - 0.001, d / 2 - 0.001));
+  const s = new THREE.Shape();
+  const x = -w / 2, y = -d / 2;
+  s.moveTo(x + r, y);
+  s.lineTo(x + w - r, y);
+  s.quadraticCurveTo(x + w, y, x + w, y + r);
+  s.lineTo(x + w, y + d - r);
+  s.quadraticCurveTo(x + w, y + d, x + w - r, y + d);
+  s.lineTo(x + r, y + d);
+  s.quadraticCurveTo(x, y + d, x, y + d - r);
+  s.lineTo(x, y + r);
+  s.quadraticCurveTo(x, y, x + r, y);
+  return s;
+}
+
+// peça de cantos arredondados e borda chanfrada, com a base em y = 0 (largura em x, altura em y, profundidade em z).
+// `lados` pinta as laterais de outra cor: é o que mostra a espessura quando a câmera gira.
+export function placa({ largura = 2, altura = 0.2, profundidade = 1.4, raio = 0.12, chanfro = 0.03, cor = '#c7b7ef', lados = null,
+  rugosidade = 0.5, metal = 0, verniz = 0.25 } = {}) {
+  const ch = Math.max(0.001, Math.min(chanfro, altura / 2 - 0.001, largura / 4, profundidade / 4));
+  const forma = retanguloArredondado(largura - 2 * ch, profundidade - 2 * ch, Math.max(0.002, raio - ch));
+  const geo = new THREE.ExtrudeGeometry(forma, { depth: Math.max(0.001, altura - 2 * ch), bevelEnabled: true, bevelThickness: ch,
+    bevelSize: ch, bevelSegments: 3, curveSegments: 10 });
+  geo.rotateX(-Math.PI / 2);
+  geo.translate(0, ch, 0);
+  geo.computeVertexNormals();
+  const tampa = material(cor, { rugosidade, metal, verniz });
+  const lateral = lados ? material(lados, { rugosidade, metal, verniz }) : tampa;
+  return sombreia(new THREE.Mesh(geo, [tampa, lateral]));
+}
+
+export function caixa(op = {}) {
+  return placa({ largura: 1, altura: 1, profundidade: 1, raio: 0.1, chanfro: 0.05, ...op });
+}
+
+export function cilindro({ raio = 0.5, altura = 1, cor = '#c7b7ef', segmentos = 48, rugosidade = 0.5, metal = 0, verniz = 0.25 } = {}) {
+  const geo = new THREE.CylinderGeometry(raio, raio, altura, segmentos, 1);
+  geo.translate(0, altura / 2, 0);
+  return sombreia(new THREE.Mesh(geo, material(cor, { rugosidade, metal, verniz })));
+}
+
+// ------------------------------------------------------------------------------------------ texto em volume
+// As letras são desenhadas na fonte do projeto (Montserrat), o contorno de cada uma é medido no desenho
+// (quadrados marchando, com o meio-termo entre pixels) e vira geometria extrudada de verdade, com chanfro.
+// Qualquer letra acentuada serve. Não usa arquivo de fonte 3D nem biblioteca extra.
+function contornosDoDesenho(linhas, fonteCss, tamanhoPx, entrelinha) {
+  const cv = document.createElement('canvas');
+  const g = cv.getContext('2d', { willReadFrequently: true });
+  g.font = fonteCss;
+  const larg = Math.max(...linhas.map((l) => g.measureText(l).width));
+  const pad = Math.ceil(tamanhoPx * 0.3);
+  const lh = Math.ceil(tamanhoPx * entrelinha);
+  const W = Math.ceil(larg) + pad * 2;
+  const H = lh * linhas.length + pad * 2;
+  cv.width = W;
+  cv.height = H;
+  g.font = fonteCss;
+  g.fillStyle = '#ffffff';
+  g.textAlign = 'center';
+  g.textBaseline = 'middle';
+  linhas.forEach((l, i) => g.fillText(l, W / 2, pad + lh * (i + 0.5)));
+  const px = g.getImageData(0, 0, W, H).data;
+  const v = new Float32Array(W * H);
+  for (let i = 0; i < W * H; i++) v[i] = px[i * 4 + 3] / 255;
+  const iso = 0.5;
+  const prox = new Int32Array(2 * W * H).fill(-1);
+  const pontoX = new Float32Array(2 * W * H);
+  const pontoY = new Float32Array(2 * W * H);
+  const idH = (x, y) => 2 * (y * W + x);
+  const idV = (x, y) => 2 * (y * W + x) + 1;
+  const ponto = (id) => {
+    if (pontoX[id] !== 0 || pontoY[id] !== 0) return;
+    const k = id >> 1;
+    const x = k % W;
+    const y = (k - x) / W;
+    if ((id & 1) === 0) { const a = v[y * W + x], b = v[y * W + x + 1]; pontoX[id] = x + (iso - a) / (b - a); pontoY[id] = y; } else { const a = v[y * W + x], b = v[(y + 1) * W + x]; pontoX[id] = x; pontoY[id] = y + (iso - a) / (b - a); }
+  };
+  const liga = (de, ate) => { prox[de] = ate; ponto(de); ponto(ate); };
+  for (let y = 0; y < H - 1; y++) {
+    for (let x = 0; x < W - 1; x++) {
+      const a = v[y * W + x] > iso, b = v[y * W + x + 1] > iso, c = v[(y + 1) * W + x + 1] > iso, d = v[(y + 1) * W + x] > iso;
+      const caso = (a ? 8 : 0) | (b ? 4 : 0) | (c ? 2 : 0) | (d ? 1 : 0);
+      if (caso === 0 || caso === 15) continue;
+      const T = idH(x, y), B = idH(x, y + 1), L = idV(x, y), R = idV(x + 1, y);
+      const meio = (v[y * W + x] + v[y * W + x + 1] + v[(y + 1) * W + x + 1] + v[(y + 1) * W + x]) / 4 > iso;
+      switch (caso) {
+        case 1: liga(L, B); break;
+        case 2: liga(B, R); break;
+        case 3: liga(L, R); break;
+        case 4: liga(R, T); break;
+        case 5: if (meio) { liga(L, T); liga(R, B); } else { liga(L, B); liga(R, T); } break;
+        case 6: liga(B, T); break;
+        case 7: liga(L, T); break;
+        case 8: liga(T, L); break;
+        case 9: liga(T, B); break;
+        case 10: if (meio) { liga(T, R); liga(B, L); } else { liga(T, L); liga(B, R); } break;
+        case 11: liga(T, R); break;
+        case 12: liga(R, L); break;
+        case 13: liga(R, B); break;
+        case 14: liga(B, L); break;
+        default: break;
+      }
+    }
+  }
+  const voltas = [];
+  for (let id = 0; id < prox.length; id++) {
+    if (prox[id] < 0) continue;
+    const pts = [];
+    let k = id;
+    let guarda = 0;
+    while (k >= 0 && guarda++ < 4000000) {
+      pts.push([pontoX[k], pontoY[k]]);
+      const n = prox[k];
+      prox[k] = -1;
+      k = n;
+      if (k === id) break;
+    }
+    if (pts.length >= 3) voltas.push(pts);
+  }
+  return { voltas, W, H };
+}
+
+function simplifica(pts, eps) {
+  // Ramer-Douglas-Peucker numa volta fechada: parte no ponto mais longe do primeiro
+  if (pts.length < 8) return pts;
+  let far = 0, dmax = -1;
+  for (let i = 1; i < pts.length; i++) {
+    const d = (pts[i][0] - pts[0][0]) ** 2 + (pts[i][1] - pts[0][1]) ** 2;
+    if (d > dmax) { dmax = d; far = i; }
+  }
+  const rdp = (arr) => {
+    const out = [arr[0]];
+    const pilha = [[0, arr.length - 1]];
+    const manter = new Uint8Array(arr.length);
+    manter[0] = manter[arr.length - 1] = 1;
+    while (pilha.length) {
+      const [i0, i1] = pilha.pop();
+      const [x0, y0] = arr[i0], [x1, y1] = arr[i1];
+      const dx = x1 - x0, dy = y1 - y0, n = Math.hypot(dx, dy) || 1e-9;
+      let im = -1, dm = eps;
+      for (let i = i0 + 1; i < i1; i++) {
+        const d = Math.abs(dy * arr[i][0] - dx * arr[i][1] + x1 * y0 - y1 * x0) / n;
+        if (d > dm) { dm = d; im = i; }
+      }
+      if (im >= 0) { manter[im] = 1; pilha.push([i0, im], [im, i1]); }
+    }
+    for (let i = 1; i < arr.length; i++) if (manter[i]) out.push(arr[i]);
+    return out;
+  };
+  const a = rdp(pts.slice(0, far + 1));
+  const b = rdp(pts.slice(far).concat([pts[0]]));
+  return a.concat(b.slice(1, -1));
+}
+
+const areaDe = (p) => { let s = 0; for (let i = 0, j = p.length - 1; i < p.length; j = i++) s += (p[j][0] + p[i][0]) * (p[j][1] - p[i][1]); return s / 2; };
+const dentro = (pt, p) => {
+  let c = false;
+  for (let i = 0, j = p.length - 1; i < p.length; j = i++) {
+    if ((p[i][1] > pt[1]) !== (p[j][1] > pt[1]) && pt[0] < ((p[j][0] - p[i][0]) * (pt[1] - p[i][1])) / (p[j][1] - p[i][1]) + p[i][0]) c = !c;
+  }
+  return c;
+};
+
+export async function textoEmVolume(texto, { fonte = 'Montserrat', peso = 900, tamanhoPx = 260, altura = 1, espessura = 0.3, chanfro = 0.02,
+  entrelinha = 1.05, cor = '#665080', lados = null, rugosidade = 0.4, metal = 0, verniz = 0.5 } = {}) {
+  const css = `${peso} ${tamanhoPx}px ${fonte}`;
+  try { await document.fonts.load(css, texto); } catch (e) { /* segue com a fonte que tiver */ }
+  if (document.fonts && !document.fonts.check(css, texto)) console.warn(`[cena 3D] a fonte ${fonte} não carregou; o texto sai em outra fonte`);
+  const linhas = String(texto).split('\n');
+  const { voltas } = contornosDoDesenho(linhas, css, tamanhoPx, entrelinha);
+  const esc = altura / tamanhoPx;             // 1 px do desenho em unidades da cena
+  const polis = voltas.map((p) => simplifica(p, 0.35)).filter((p) => p.length >= 3 && Math.abs(areaDe(p)) > 4);
+  if (!polis.length) throw new Error(`não consegui desenhar o texto "${texto}"`);
+  let maior = polis[0];
+  for (const p of polis) if (Math.abs(areaDe(p)) > Math.abs(areaDe(maior))) maior = p;
+  const sinalFora = Math.sign(areaDe(maior));
+  const fora = polis.filter((p) => Math.sign(areaDe(p)) === sinalFora);
+  const furos = polis.filter((p) => Math.sign(areaDe(p)) !== sinalFora);
+  const vira = (p) => p.map(([x, y]) => new THREE.Vector2(x * esc, -y * esc));
+  const formas = fora.map((p) => ({ p, s: new THREE.Shape(vira(p)), a: Math.abs(areaDe(p)) }));
+  for (const f of furos) {
+    const dono = formas.filter((o) => dentro(f[0], o.p)).sort((a, b) => a.a - b.a)[0];
+    if (dono) dono.s.holes.push(new THREE.Path(vira(f)));
+  }
+  const ch = Math.max(0.001, chanfro * altura);
+  const geo = new THREE.ExtrudeGeometry(formas.map((o) => o.s), { depth: Math.max(0.001, espessura * altura - 2 * ch), bevelEnabled: true,
+    bevelThickness: ch, bevelSize: ch, bevelSegments: 2, curveSegments: 1 });
+  geo.computeBoundingBox();
+  const bb = geo.boundingBox;
+  geo.translate(-(bb.min.x + bb.max.x) / 2, -bb.min.y, -(bb.min.z + bb.max.z) / 2);   // base no chão, centro em x e z
+  geo.computeVertexNormals();
+  const frente = material(cor, { rugosidade, metal, verniz });
+  const lateral = lados ? material(lados, { rugosidade, metal, verniz }) : frente;
+  return sombreia(new THREE.Mesh(geo, [frente, lateral]));
+}
+
+// ------------------------------------------------------------------------------------------ o palco
+function criarRotulos(palco, camada, itens) {
+  const { W, H, escala: e, cores } = palco;
+  const ns = 'http://www.w3.org/2000/svg';
+  const svg = document.createElementNS(ns, 'svg');
+  svg.setAttribute('width', W);
+  svg.setAttribute('height', H);
+  svg.setAttribute('viewBox', `0 0 ${W} ${H}`);
+  svg.style.cssText = 'position:absolute;left:0;top:0;overflow:visible;pointer-events:none';
+  camada.appendChild(svg);
+  const lista = itens.map((it) => {
+    const el = document.createElement('div');
+    el.textContent = it.texto;
+    el.style.cssText = `position:absolute;left:0;top:0;opacity:0;white-space:nowrap;font-family:Montserrat,sans-serif;font-weight:800;`
+      + `font-size:${Math.round((it.tamanho || 36) * e)}px;line-height:1.05;padding:${Math.round(14 * e)}px ${Math.round(22 * e)}px;`
+      + `border-radius:${Math.round(18 * e)}px;color:${it.cor || cores.tinta};background:${it.fundo || cores.papel};`
+      // sombra dura (sem desfoque): sombra desfocada do CSS varia um tico de um render para outro
+      + `box-shadow:0 0 0 ${Math.max(2, Math.round(3 * e))}px ${cores.base},0 ${Math.round(8 * e)}px 0 ${Math.round(-1 * e)}px ${cores.base}`;
+    camada.appendChild(el);
+    const linha = document.createElementNS(ns, 'line');
+    linha.setAttribute('stroke', it.corLinha || cores.destaque);
+    linha.setAttribute('stroke-width', String(Math.max(2, 4 * e)));
+    linha.setAttribute('stroke-linecap', 'round');
+    linha.setAttribute('opacity', '0');
+    const bola = document.createElementNS(ns, 'circle');
+    bola.setAttribute('r', String(Math.max(4, 10 * e)));
+    bola.setAttribute('fill', it.corLinha || cores.destaque);
+    bola.setAttribute('stroke', cores.papel);
+    bola.setAttribute('stroke-width', String(Math.max(2, 4 * e)));
+    bola.setAttribute('opacity', '0');
+    svg.appendChild(linha);
+    svg.appendChild(bola);
+    return { el, linha, bola, lado: it.lado || 'dir', w: el.offsetWidth, h: el.offsetHeight };
+  });
+  const v = new THREE.Vector3();
+  return {
+    medir() { for (const r of lista) { r.w = r.el.offsetWidth; r.h = r.el.offsetHeight; } },
+    // estados[i] = {ponto: [x, y, z] ou Vector3 (o que o rótulo descreve), opacidade (0 a 1)}
+    // op.coluna = true: os rótulos do mesmo lado ficam alinhados numa coluna, logo depois do ponto mais de fora
+    atualizar(estados, op = {}) {
+      const [sx0, sy0, sx1, sy1] = palco.limites;
+      const folga = (op.folga == null ? 70 : op.folga) * e;
+      const vivos = [];
+      lista.forEach((r, i) => {
+        const s = estados[i] || {};
+        const o = lim(s.opacidade == null ? 1 : s.opacidade);
+        if (!s.ponto || o <= 0.001) { r.el.style.opacity = '0'; r.linha.setAttribute('opacity', '0'); r.bola.setAttribute('opacity', '0'); return; }
+        if (!r.w) { r.w = r.el.offsetWidth; r.h = r.el.offsetHeight; }
+        if (s.ponto.isVector3) v.copy(s.ponto); else v.set(s.ponto[0], s.ponto[1], s.ponto[2]);
+        v.project(palco.camera);
+        if (v.z > 1 || v.z < -1) { r.el.style.opacity = '0'; r.linha.setAttribute('opacity', '0'); r.bola.setAttribute('opacity', '0'); return; }
+        const ax = (v.x * 0.5 + 0.5) * W, ay = (-v.y * 0.5 + 0.5) * H;
+        // o que o rótulo descreve saiu da área (ou da janela): o rótulo some junto, em vez de apontar para o nada
+        const fora = Math.max(sx0 - ax, ax - sx1, sy0 - ay, ay - sy1, 0);
+        const oo = o * (1 - lim(fora / (40 * e)));
+        if (oo <= 0.001) { r.el.style.opacity = '0'; r.linha.setAttribute('opacity', '0'); r.bola.setAttribute('opacity', '0'); return; }
+        vivos.push({ r, o: oo, ax, ay, x: 0, y: 0 });
+      });
+      const dir = vivos.filter((q) => q.r.lado === 'dir'), esq = vivos.filter((q) => q.r.lado === 'esq');
+      const colDir = op.coluna && dir.length ? Math.max(...dir.map((q) => q.ax)) + folga : null;
+      const colEsq = op.coluna && esq.length ? Math.min(...esq.map((q) => q.ax)) - folga : null;
+      for (const q of vivos) {
+        const { r } = q;
+        if (r.lado === 'cima') { q.x = q.ax - r.w / 2; q.y = q.ay - folga - r.h; } else if (r.lado === 'baixo') { q.x = q.ax - r.w / 2; q.y = q.ay + folga; } else if (r.lado === 'esq') { q.x = (colEsq != null ? colEsq : q.ax - folga) - r.w; q.y = q.ay - r.h / 2; } else { q.x = colDir != null ? colDir : q.ax + folga; q.y = q.ay - r.h / 2; }
+        q.x = lim(q.x, sx0, sx1 - r.w);
+        q.y = lim(q.y, sy0, sy1 - r.h);
+      }
+      // rótulos que se encostam descem (e, se passar do limite, o grupo sobe)
+      vivos.sort((a, b) => a.y - b.y);
+      const gap = 16 * e;
+      for (let i = 1; i < vivos.length; i++) {
+        for (let j = 0; j < i; j++) {
+          const A = vivos[j], B = vivos[i];
+          const cruzaX = B.x < A.x + A.r.w && A.x < B.x + B.r.w;
+          if (cruzaX && B.y < A.y + A.r.h + gap) B.y = A.y + A.r.h + gap;
+        }
+      }
+      const excesso = vivos.length ? Math.max(0, Math.max(...vivos.map((q) => q.y + q.r.h)) - sy1) : 0;
+      for (const q of vivos) {
+        q.y = Math.max(sy0, q.y - excesso);
+        const { r } = q;
+        r.el.style.transform = `translate(${q.x.toFixed(1)}px, ${q.y.toFixed(1)}px)`;
+        r.el.style.opacity = q.o.toFixed(3);
+        let lx = q.x, ly = q.y + r.h / 2;
+        if (r.lado === 'cima') { lx = q.x + r.w / 2; ly = q.y + r.h; } else if (r.lado === 'baixo') { lx = q.x + r.w / 2; ly = q.y; } else if (q.x + r.w / 2 < q.ax) { lx = q.x + r.w; }
+        r.linha.setAttribute('x1', q.ax.toFixed(1)); r.linha.setAttribute('y1', q.ay.toFixed(1));
+        r.linha.setAttribute('x2', lx.toFixed(1)); r.linha.setAttribute('y2', ly.toFixed(1));
+        r.linha.setAttribute('opacity', q.o.toFixed(3));
+        r.bola.setAttribute('cx', q.ax.toFixed(1)); r.bola.setAttribute('cy', q.ay.toFixed(1));
+        r.bola.setAttribute('opacity', q.o.toFixed(3));
+      }
+    },
+  };
+}
+
+// vídeo ou imagem como textura. É um plano chapado: girar a câmera mostra o plano de lado, não dá volume ao que
+// está na imagem. No render, o HyperFrames troca o <video> por um <img class="__render_frame__"> ao lado com o
+// quadro certo e manda desenhar de novo: a textura lê dali quando existe.
+// encaixe "cobrir": preenche e corta (foco = que altura da imagem fica, 0 topo, 0.5 meio); "conter": a imagem
+// inteira por cima de uma cópia ampliada e escurecida dela (fundo borrado feito por redução e ampliação: o
+// filtro blur() do canvas muda um pouco de um render para outro e quebraria o render repetível).
+export function texturaDeMidia(el, { largura = 1280, altura = 720, foco = 0.4, encaixe = 'cobrir' } = {}) {
+  const cv = document.createElement('canvas');
+  cv.width = largura;
+  cv.height = altura;
+  // canvas na CPU (willReadFrequently): o desenho sai igual em todo render
+  const g = cv.getContext('2d', { willReadFrequently: true });
+  g.fillStyle = '#000';
+  g.fillRect(0, 0, largura, altura);
+  const mini = document.createElement('canvas');
+  const gm = mini.getContext('2d', { willReadFrequently: true });
+  const tex = texturaDeCanvas(cv);
+  const fonte = () => {
+    const irmao = el.nextElementSibling;
+    if (irmao && irmao.classList && irmao.classList.contains('__render_frame__') && irmao.complete && irmao.naturalWidth > 0
+      && irmao.style.visibility !== 'hidden') return irmao;
+    if (el.tagName === 'VIDEO') return el.readyState >= 2 ? el : null;
+    return el.complete && el.naturalWidth > 0 ? el : null;
+  };
+  return {
+    textura: tex,
+    atualizar() {
+      const f = fonte();
+      if (!f) return false;
+      const sw = f.videoWidth || f.naturalWidth, sh = f.videoHeight || f.naturalHeight;
+      const kc = Math.max(largura / sw, altura / sh);
+      if (encaixe === 'conter') {
+        const km = 40 / Math.max(sw, sh);
+        mini.width = Math.max(2, Math.round(sw * km));
+        mini.height = Math.max(2, Math.round(sh * km));
+        gm.drawImage(f, 0, 0, mini.width, mini.height);
+        g.imageSmoothingEnabled = true;
+        g.drawImage(mini, (largura - sw * kc) / 2, (altura - sh * kc) / 2, sw * kc, sh * kc);
+        g.fillStyle = 'rgba(0,0,0,0.45)';
+        g.fillRect(0, 0, largura, altura);
+        const ki = Math.min(largura / sw, altura / sh);
+        g.drawImage(f, (largura - sw * ki) / 2, (altura - sh * ki) / 2, sw * ki, sh * ki);
+      } else {
+        g.drawImage(f, (largura - sw * kc) / 2, (altura - sh * kc) * foco, sw * kc, sh * kc);
+      }
+      tex.needsUpdate = true;
+      return true;
+    },
+  };
+}
+
+// modelo .glb/.gltf da pessoa (liberado para uso), carregado da pasta do projeto antes do render começar
+export async function carregarModelo(url, { altura = null, largura = null } = {}) {
+  const { GLTFLoader } = await import('../../../assets/three/GLTFLoader.js');
+  const gltf = await new GLTFLoader().loadAsync(url);
+  const obj = gltf.scene;
+  sombreia(obj);
+  const box = new THREE.Box3().setFromObject(obj);
+  const tam = box.getSize(new THREE.Vector3());
+  let k = 1;
+  if (altura) k = altura / (tam.y || 1);
+  else if (largura) k = largura / (Math.max(tam.x, tam.z) || 1);
+  obj.scale.setScalar(k);
+  const c = box.getCenter(new THREE.Vector3());
+  const grupo = new THREE.Group();
+  obj.position.set(-c.x * k, -box.min.y * k, -c.z * k);     // base no chão, centro em x e z
+  grupo.add(obj);
+  const mix = gltf.animations.length ? new THREE.AnimationMixer(obj) : null;
+  if (mix) gltf.animations.forEach((a) => mix.clipAction(a).play());
+  // animação do próprio modelo: posta no tempo (mix.setTime), nunca tocada pelo relógio
+  return { objeto: grupo, animacoes: gltf.animations, noTempo: (t) => { if (mix) mix.setTime(t); } };
+}
+
+function falhaVisivel(camada, texto) {
+  if (!camada) return;
+  const el = document.createElement('div');
+  el.textContent = texto;
+  el.style.cssText = 'position:absolute;left:60px;right:60px;top:40%;padding:28px;border-radius:20px;background:#fff;color:#b00020;'
+    + 'font:700 34px/1.25 Montserrat,sans-serif;box-shadow:0 0 0 6px #b00020;opacity:1';
+  camada.appendChild(el);
+}
+
+// Monta a cena e devolve desenhar(t). opcoes:
+//   id, C (window.__cenas[id] com os padrões), raiz (URL da pasta do projeto), canvas, camada (div dos rótulos),
+//   fundo ('#cor' ou null = transparente, para mostrar a pessoa numa moldura por baixo), area ([x0, y0, x1, y1]
+//   onde fica o 3D; padrão: a zona segura), limites (onde os rótulos podem ficar; padrão: a area), recorte
+//   ([x0, y0, x1, y1]: o 3D só aparece dentro desse retângulo de cantos redondos, a "janela" da cena quando a
+//   pessoa fica numa moldura ao lado; null = tela toda), fov, sombras,
+//   ambiente (luz de estúdio refletida, true),
+//   construir: async (palco) => (t) => {...}   a cena: monta os objetos e devolve atualizar(t)
+export async function iniciar(opcoes) {
+  const { id, C, canvas, camada } = opcoes;
+  const t0 = performance.now();   // só para medir a montagem (diagnóstico); nunca decide o que aparece
+  const estado = (window.__cena3d = window.__cena3d || {})[id] = { pronto: false, avisos: [], revisao: REVISAO };
+  const falha = (msg) => {
+    estado.erro = msg;
+    console.error(`[cena 3D ${id}] ${msg}`);
+    falhaVisivel(camada, `Cena 3D "${id}" não montou: ${msg}`);
+    return () => {};
+  };
+  const W = C.largura || 1080, H = C.altura || 1920;
+  let renderer;
+  try {
+    renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: opcoes.fundo == null || !!opcoes.recorte, preserveDrawingBuffer: true,
+      powerPreference: 'high-performance' });
+  } catch (e) {
+    return falha(`o WebGL não abriu neste navegador (${e && e.message ? e.message : e}). Veja references/3d.md, "Se o teste falhar".`);
+  }
+  renderer.setPixelRatio(1);
+  renderer.setSize(W, H, false);
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.toneMapping = THREE.NeutralToneMapping;
+  renderer.shadowMap.enabled = opcoes.sombras !== false;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+  const gl = renderer.getContext();
+  const info = gl.getExtension('WEBGL_debug_renderer_info');
+  estado.placa = info ? gl.getParameter(info.UNMASKED_RENDERER_WEBGL) : gl.getParameter(gl.RENDERER);
+  const cena = new THREE.Scene();
+  if (opcoes.fundo != null) cena.background = new THREE.Color(opcoes.fundo);
+  else renderer.setClearColor(0x000000, 0);
+  const rec = opcoes.recorte;
+  if (rec) {
+    // fora da janela o canvas fica vazio (transparente) e os cantos são arredondados
+    const r = Math.round(36 * Math.min(W, H) / 1080);
+    canvas.style.clipPath = `inset(${rec[1]}px ${W - rec[2]}px ${H - rec[3]}px ${rec[0]}px round ${r}px)`;
+  }
+  if (opcoes.ambiente !== false) {
+    const pm = new THREE.PMREMGenerator(renderer);
+    cena.environment = pm.fromScene(new RoomEnvironment(), 0.04).texture;
+    cena.environmentIntensity = opcoes.ambiente === true || opcoes.ambiente == null ? 0.55 : Number(opcoes.ambiente);
+    pm.dispose();
+  }
+  const camera = new THREE.PerspectiveCamera(opcoes.fov || 30, W / H, 0.05, 400);
+  const area = opcoes.area || C.seguro || [0, 0, W, H];
+  enquadrar(camera, W, H, area);
+  const raiz = opcoes.raiz || document.baseURI;
+  const solidos = [];
+  const texturas = [];
+  const palco = {
+    THREE, renderer, cena, camera, W, H, C, area, limites: opcoes.limites || area, cores: C.cores, escala: Math.min(W, H) / 1080,
+    transparente: opcoes.fundo == null,
+    url: (caminho) => new URL(caminho, raiz).href,
+    // registra um objeto para a conferência "a câmera nunca entra num objeto"
+    solido(obj, nome) { solidos.push({ obj, nome: nome || obj.name || 'objeto' }); return obj; },
+    luzes({ chave = [4, 9, 6], forca = 2.6, alvo = [0, 0.5, 0], area: tam = 6, contra = 0.9, ceu = 0.7 } = {}) {
+      const hemi = new THREE.HemisphereLight('#ffffff', C.cores.base, ceu);
+      cena.add(hemi);
+      const k = new THREE.DirectionalLight('#ffffff', forca);
+      k.position.set(...chave);
+      k.target.position.set(...alvo);
+      k.castShadow = palco.renderer.shadowMap.enabled;
+      k.shadow.mapSize.set(2048, 2048);
+      Object.assign(k.shadow.camera, { left: -tam, right: tam, top: tam, bottom: -tam, near: 0.5, far: 60 });
+      k.shadow.bias = -0.0004;
+      k.shadow.normalBias = 0.02;
+      k.shadow.radius = 4;
+      cena.add(k, k.target);
+      const r = new THREE.DirectionalLight('#ffffff', contra);
+      r.position.set(-chave[0] * 0.8, chave[1] * 0.6, -Math.abs(chave[2]) - 4);
+      cena.add(r);
+      return { hemi, chave: k, contra: r };
+    },
+    // chão: grade que some nas bordas + um plano que só mostra sombra. Sem fundo (transparente), só a sombra:
+    // a grade riscaria o vídeo que aparece por baixo.
+    chao({ tamanho = 24, passos = 24, grade = opcoes.fundo != null, sombra = 0.22, y = 0 } = {}) {
+      const g = new THREE.Group();
+      if (grade) {
+        const mapa = texturaDeGrade(C.cores.linha, passos);
+        mapa.anisotropy = renderer.capabilities.getMaxAnisotropy();   // linhas firmes mesmo vistas de lado
+        const m = new THREE.MeshBasicMaterial({ map: mapa, transparent: true, depthWrite: false });
+        const p = new THREE.Mesh(new THREE.PlaneGeometry(tamanho, tamanho), m);
+        p.rotation.x = -Math.PI / 2;
+        p.position.y = y + 0.0005;
+        p.renderOrder = -2;
+        g.add(p);
+      }
+      const s = new THREE.Mesh(new THREE.PlaneGeometry(tamanho, tamanho), new THREE.ShadowMaterial({ opacity: sombra }));
+      s.rotation.x = -Math.PI / 2;
+      s.position.y = y + 0.001;
+      s.receiveShadow = true;
+      s.renderOrder = -1;
+      g.add(s);
+      cena.add(g);
+      return g;
+    },
+    // sombra de contato: mancha escura e macia colada no chão, embaixo da peça; clareia quando a peça sobe
+    sombraDeContato({ largura = 1, profundidade = 1, forca = 0.45, y = 0 } = {}) {
+      const m = new THREE.MeshBasicMaterial({ map: texturaDeMancha(), transparent: true, opacity: forca, depthWrite: false, color: '#000000' });
+      const p = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), m);
+      p.rotation.x = -Math.PI / 2;
+      p.position.y = y + 0.002;
+      p.renderOrder = -1;
+      cena.add(p);
+      return {
+        malha: p,
+        colocar(x, z, alturaAcima = 0, escalaExtra = 1, anguloY = 0) {
+          const k = 1 + alturaAcima * 0.6;
+          p.position.set(x, y + 0.002, z);
+          p.rotation.set(-Math.PI / 2, 0, anguloY);
+          p.scale.set(largura * 1.25 * k * escalaExtra, profundidade * 1.25 * k * escalaExtra, 1);
+          m.opacity = forca / (1 + alturaAcima * 2.2);
+        },
+      };
+    },
+    placa, caixa, cilindro, material, textoEmVolume,
+    carregarModelo: (caminho, op) => carregarModelo(palco.url(caminho), op),
+    texturaDeMidia(el, op) { const t = texturaDeMidia(el, op); texturas.push(t); return t; },
+    rotulos: (itens) => criarRotulos(palco, camada, itens),
+    orbita: (pose) => orbita(camera, pose),
+    distanciaParaCaber: (raio, folga) => distanciaParaCaber(camera, raio, H, area, folga),
+    distanciaParaCaixa: (largura, altura, folga) => distanciaParaCaixa(camera, largura, altura, H, area, folga),
+    // a distância em que a caixa (THREE.Box3) cabe inteira na área, vista da pose {alvo, azim, elev}
+    distanciaQueCabe: (caixa, pose, folga) => distanciaQueCabe(camera, W, H, area, caixa, pose, folga),
+  };
+  try { await document.fonts.load(`800 ${Math.round(36 * palco.escala)}px Montserrat`); } catch (e) { /* segue */ }
+  let atualizar;
+  try {
+    atualizar = await opcoes.construir(palco);
+  } catch (e) {
+    return falha(`erro ao montar os objetos: ${e && e.message ? e.message : e}`);
+  }
+  // conferência: em cada quadro da cena, a câmera fica fora de todos os sólidos registrados
+  const DUR = C.duracao || 5;
+  const caixaDe = new THREE.Box3();
+  const folga = camera.near + 0.03;
+  const vistos = new Set();
+  for (let f = 0; f <= Math.ceil(DUR * 30); f++) {
+    const t = Math.min(DUR, f / 30);
+    atualizar(t);
+    for (const s of solidos) {
+      caixaDe.setFromObject(s.obj).expandByScalar(folga);
+      if (caixaDe.containsPoint(camera.position) && !vistos.has(s.nome)) {
+        vistos.add(s.nome);
+        const msg = `a câmera entra em "${s.nome}" em ${t.toFixed(2)} s: afaste a câmera ou mude o caminho`;
+        estado.avisos.push(msg);
+        console.error(`[cena 3D ${id}] ${msg}`);
+      }
+    }
+  }
+  const desenhar = (t) => {
+    const tt = lim(Number(t) || 0, 0, DUR);
+    estado.t = tt;              // o último tempo desenhado (diagnóstico: confira no console do estúdio)
+    atualizar(tt);
+    for (const tx of texturas) tx.atualizar();
+    if (rec) {
+      renderer.setScissorTest(false);
+      renderer.setClearColor(0x000000, 0);
+      renderer.clear();
+      renderer.setScissorTest(true);
+      renderer.setScissor(rec[0], H - rec[3], rec[2] - rec[0], rec[3] - rec[1]);
+    }
+    renderer.render(cena, camera);
+  };
+  estado.pronto = true;
+  estado.montagemMs = Math.round(performance.now() - t0);
+  estado.desenhar = desenhar;
+  return desenhar;
+}