Skip to content

Looksmaxxing for motion graphics. An agent skill that turns AI slop videos into films that look made by a motion designer.

38.9 KB
Raw Blame
// hero3d.js: one seek-safe hero 3D object for a motionmaxxing film (ported from motion-unslop v2 + the gen-1 SVG-logo extrusion).
//
// Runs INSIDE the renderer (plain HTML + Motion runtime, or HyperFrames) on Three.js r186. No Blender, no DCC, no network at render time.
// Normal use is through the Motion runtime: M.hero3d(canvas, { objects | build, state }) loads this module for you (see runtime/README.md "3D").
// Direct use:
//   const hero = await createHero3D(canvas, { objects: [{ id: 'mark', kind: 'logo', svg: 'M0 0 ...' }], state: (t, objs, ctx) => ({ ... }) });
//   hero.renderAt(t);          // every visible property is a pure function of (t, state)
//
// Seek-safety contract (why this file looks the way it does):
//   * renderAt() RESETS every transform, light and uniform from options + state on every call.
//     Nothing accumulates between frames, so frame 75 is identical whether you jumped to it or
//     played through 0..74 (HyperFrames renders in parallel workers that seek out of order).
//   * No clocks, no requestAnimationFrame, no Math.random(). Use rng(seed) for scatter.
//   * All assets (font, env image, glTF, screen image) load inside createHero3D(); await it
//     before the first render. No fetch happens in renderAt().
//
// Imports: the vendored three.js and addons import each other by RELATIVE path (vendor/addons/* were patched from the bare specifier 'three'),
// so no importmap is needed. Never mix this vendor copy with a second copy of three on the page.

import * as THREE from "./vendor/three.module.js";
import { RoomEnvironment } from "./vendor/addons/environments/RoomEnvironment.js";
import { HDRLoader } from "./vendor/addons/loaders/HDRLoader.js";
import { EXRLoader } from "./vendor/addons/loaders/EXRLoader.js";
import { FontLoader } from "./vendor/addons/loaders/FontLoader.js";
import { TTFLoader } from "./vendor/addons/loaders/TTFLoader.js";
import { GLTFLoader } from "./vendor/addons/loaders/GLTFLoader.js";
import { SVGLoader } from "./vendor/addons/loaders/SVGLoader.js";
import { RoundedBoxGeometry } from "./vendor/addons/geometries/RoundedBoxGeometry.js";
import { mergeGeometries, toCreasedNormals } from "./vendor/addons/utils/BufferGeometryUtils.js";
import { EffectComposer } from "./vendor/addons/postprocessing/EffectComposer.js";
import { RenderPass } from "./vendor/addons/postprocessing/RenderPass.js";
import { UnrealBloomPass } from "./vendor/addons/postprocessing/UnrealBloomPass.js";
import { BokehPass } from "./vendor/addons/postprocessing/BokehPass.js";
import { OutputPass } from "./vendor/addons/postprocessing/OutputPass.js";

export { THREE };

// ---------------------------------------------------------------------------------------------
// Time helpers (pure). Use these to write state(t) without a separate animation library.
// ---------------------------------------------------------------------------------------------
export const clamp01 = (x) => Math.min(1, Math.max(0, x));
export const ease = {
  linear: (x) => x,
  smooth: (x) => x * x * (3 - 2 * x),
  cubicOut: (x) => 1 - (1 - x) ** 3,
  quartOut: (x) => 1 - (1 - x) ** 4, // motion-unslop default arrival
  expoOut: (x) => (x >= 1 ? 1 : 1 - 2 ** (-10 * x)),
  expoInOut: (x) =>
    x <= 0 ? 0 : x >= 1 ? 1 : x < 0.5 ? 2 ** (20 * x - 10) / 2 : (2 - 2 ** (-20 * x + 10)) / 2,
  launchIn: (x) => x * x * x,
};
// M.hero3d merges Motion.ease (softLand, whip, glide, snapSettle, popOver, crashIn, accelExit ...) into this table, so key(t, [..., 'softLand']) works.
const lerp = (a, b, u) => (Array.isArray(a) ? a.map((v, i) => v + (b[i] - v) * u) : a + (b - a) * u);

/** key(t, [[t0, v0], [t1, v1, 'quartOut'], ...]) -> value at t. v may be a number or an array.
 *  The ease on a key shapes the segment that ARRIVES at that key. Clamped at both ends. */
export function key(t, keys) {
  if (t <= keys[0][0]) return keys[0][1];
  for (let i = 1; i < keys.length; i++) {
    const [t1, v1, e = "smooth"] = keys[i];
    const [t0, v0] = keys[i - 1];
    if (t <= t1) return lerp(v0, v1, (typeof e === "function" ? e : ease[e] || ease.smooth)((t - t0) / (t1 - t0)));
  }
  return keys[keys.length - 1][1];
}
/** Gaussian bump: 1 at c, falls off with width w. For one-off flashes / sweeps. */
export const pulse = (t, c, w) => Math.exp(-(((t - c) / w) ** 2));
/** Seeded PRNG (mulberry32). Never use Math.random() in a film. */
export function rng(seed = 1) {
  let a = seed >>> 0;
  return () => {
    a = (a + 0x6d2b79f5) >>> 0;
    let r = Math.imul(a ^ (a >>> 15), 1 | a);
    r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
    return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
  };
}

// ---------------------------------------------------------------------------------------------
// Material recipes. MeshPhysicalMaterial everywhere: MeshStandardMaterial with default values
// is the "plastic CG" look. Every recipe assumes an environment map is present.
// ---------------------------------------------------------------------------------------------
export const MATERIALS = {
  // Polished metal. Colour tints it: '#ffffff' chrome, '#f1c16b' gold, '#c9a18a' rose gold.
  chrome: { color: "#ffffff", metalness: 1, roughness: 0.07 },
  // Real refraction. attenuationColor tints the body by thickness, dispersion splits edges.
  glass: {
    color: "#ffffff",
    metalness: 0,
    roughness: 0.03,
    transmission: 1,
    thickness: 0.8,
    ior: 1.5,
    attenuationDistance: 3,
    dispersion: 0.25,
    specularIntensity: 1,
    clearcoat: 0.3,
  },
  // Soft anodised / powder-coat look: broad highlight, sheen on grazing edges.
  satin: {
    color: "#d9d5cf",
    metalness: 0.25,
    roughness: 0.38,
    sheen: 0.5,
    sheenRoughness: 0.4,
    sheenColor: "#ffffff",
    clearcoat: 0.25,
    clearcoatRoughness: 0.35,
  },
  // Thin-film metal (holo coin, oil-slick). Needs a contrasty env or it reads as grey.
  iridescent: {
    // Base must NOT be a perfect mirror: over F0=1 (white metal) thin-film interference cancels
    // out and the result is plain chrome. A mid-grey metal base leaves room for the colours.
    color: "#cfcfcf",
    metalness: 1,
    roughness: 0.12,
    iridescence: 1,
    iridescenceIOR: 1.8,
    iridescenceThicknessRange: [180, 400], // thin + narrow = pastel holo foil; wide (250-900) = oil slick
  },
  // Glossy injection-moulded plastic in the brand colour, with a lacquer coat.
  brandPlastic: {
    color: "#3355ff",
    metalness: 0,
    roughness: 0.32,
    clearcoat: 1,
    clearcoatRoughness: 0.04,
    specularIntensity: 0.7,
  },
};

export function makeMaterial(name = "chrome", color, extra = {}) {
  const recipe = { ...(MATERIALS[name] || MATERIALS.chrome), ...extra };
  if (color) recipe[name === "glass" ? "attenuationColor" : "color"] = color;
  const { color: c, attenuationColor: ac, sheenColor: sc, warp, ...rest } = recipe;
  const m = new THREE.MeshPhysicalMaterial(rest);
  if (c) m.color.set(c);
  if (ac) m.attenuationColor.set(ac);
  if (sc) m.sheenColor.set(sc);
  if (warp) addWarp(m, warp === true ? {} : warp);
  // Without a thickness map three uses the MAX thickness everywhere: one flat hue (reads as copper).
  if (m.iridescence > 0 && !m.iridescenceThicknessMap) m.iridescenceThicknessMap = filmThicknessMap();
  return m;
}

let filmMap = null;
/** Smooth deterministic 256x256 pattern (sum of sines, no randomness) used as thin-film thickness. */
function filmThicknessMap() {
  if (filmMap) return filmMap;
  const n = 256,
    d = new Uint8Array(n * n * 4);
  for (let y = 0; y < n; y++)
    for (let x = 0; x < n; x++) {
      const u = (x / n) * Math.PI * 2,
        v = (y / n) * Math.PI * 2;
      const f = 0.5 + 0.3 * Math.sin(u + Math.sin(v) * 1.2) + 0.2 * Math.sin(v + Math.cos(u) * 0.8); // one soft cycle, tileable
      const i = (y * n + x) * 4;
      d[i] = d[i + 1] = d[i + 2] = Math.round(f * 255);
      d[i + 3] = 255;
    }
  filmMap = new THREE.DataTexture(d, n, n); // thickness is read from the G channel
  filmMap.wrapS = filmMap.wrapT = THREE.RepeatWrapping;
  filmMap.needsUpdate = true;
  return filmMap;
}

/** Liquid-surface normal warp. Flat extruded faces reflect ONE direction of the environment, so
 *  a whole letter face is either all-lit or all-dark ("mirror tile" look). Bending the shading
 *  normal with smooth object-space waves makes each face show a band of the environment, which
 *  is what real polished type and liquid chrome look like. Pure function of (position, uWarpTime);
 *  renderAt() sets uWarpTime from state.warpTime (default: frozen at 0, i.e. no flow).
 *  { amount: 0.18 (0.08 subtle polish .. 0.4 liquid), scale: 1.4 (waves per unit), flow: 1 } */
function addWarp(m, { amount = 0.18, scale = 1.4 } = {}) {
  m.userData.warp = {
    uWarpTime: { value: 0 },
    uWarpAmount: { value: amount },
    uWarpScale: { value: scale },
  };
  m.onBeforeCompile = (sh) => {
    Object.assign(sh.uniforms, m.userData.warp);
    sh.vertexShader = sh.vertexShader
      .replace(
        "#include <common>",
        "#include <common>\nvarying vec3 vWarpP; varying vec3 vWX; varying vec3 vWY; varying vec3 vWZ;",
      )
      .replace(
        "#include <begin_vertex>",
        `#include <begin_vertex>
        vWarpP = position; vWX = normalMatrix * vec3(1.,0.,0.); vWY = normalMatrix * vec3(0.,1.,0.); vWZ = normalMatrix * vec3(0.,0.,1.);`,
      );
    sh.fragmentShader = sh.fragmentShader
      .replace(
        "#include <common>",
        `#include <common>
        varying vec3 vWarpP; varying vec3 vWX; varying vec3 vWY; varying vec3 vWZ;
        uniform float uWarpTime, uWarpAmount, uWarpScale;`,
      )
      .replace(
        "#include <normal_fragment_maps>",
        `#include <normal_fragment_maps>
        {
          vec3 q = vWarpP * uWarpScale; float T = uWarpTime;
          vec3 w = vec3(
            sin(q.y * 1.7 + 1.5 * sin(q.x * 1.3 + T) + q.z * 0.8),
            sin(q.x * 1.9 + 1.5 * sin(q.y * 1.1 - T * 0.8) + 0.6),
            sin((q.x + q.y) * 1.2 + T * 0.6));
          vec3 wv = vWX * w.x + vWY * w.y + vWZ * w.z;
          wv -= dot(wv, normal) * normal;              // keep the bend tangential
          normal = normalize(normal + wv * uWarpAmount);
        }`,
      );
  };
  m.customProgramCacheKey = () => "hero3d-warp";
}

// ---------------------------------------------------------------------------------------------
// Environment. The env map IS the lighting: chrome reflects it, glass refracts it.
//   'studio' (default): black cyclorama + softboxes. High contrast, the classic product look.
//   'room':             three.js RoomEnvironment (neutral grey interior; softer, lower contrast).
//   'plate.jpg|png':    an equirectangular image, e.g. an AI-generated plate. LDR images are
//                       expanded to pseudo-HDR (envBoost) so highlights are bright enough to bloom.
//   'x.hdr' | 'x.exr':  a real HDRI.
// A moving "sweep" softbox can be added to ANY of these; it is baked into the PMREM per frame,
// so the light sweep is a real reflection travelling across the surface, not a 2D gradient.
// ---------------------------------------------------------------------------------------------
function softbox(w, h, intensity, color = "#ffffff") {
  const m = new THREE.Mesh(
    new THREE.PlaneGeometry(w, h),
    new THREE.MeshBasicMaterial({
      color: new THREE.Color(color).multiplyScalar(intensity),
      side: THREE.DoubleSide,
    }),
  );
  return m;
}

function studioScene() {
  const s = new THREE.Scene();
  // Cyclorama: near-black vertex-coloured sphere with a faint glow at the horizon.
  // Chrome shows the environment, not the object: keep most of it DARK so the few cards read.
  const g = new THREE.SphereGeometry(30, 48, 24);
  const col = [],
    p = g.attributes.position;
  for (let i = 0; i < p.count; i++) {
    const y = p.getY(i) / 30;
    const v = y < 0 ? 0.001 + 0.008 * Math.exp(-((y * 7) ** 2)) : 0.002 + 0.012 * Math.exp(-((y * 5) ** 2));
    col.push(v, v, v * 1.05);
  }
  g.setAttribute("color", new THREE.Float32BufferAttribute(col, 3));
  s.add(new THREE.Mesh(g, new THREE.MeshBasicMaterial({ vertexColors: true, side: THREE.BackSide })));
  const add = (m, pos) => {
    m.position.set(...pos);
    m.lookAt(0, 0, 0);
    s.add(m);
  };
  // Front faces of flat type reflect what is BEHIND THE CAMERA, so that is where the structure goes.
  add(softbox(24, 0.5, 3.5), [0, -1.4, 16]); // horizon strip: the bright line across chrome faces
  add(softbox(5, 7, 5, "#fff1e0"), [-9, 6, 8]); // warm key card, top-left
  add(softbox(2, 16, 6, "#dcefff"), [12, 1, -7]); // cool rim strip, back-right: lights edges/bevels
  add(softbox(10, 3, 1.5), [0, 16, 0]); // small overhead: tops of letters and bevels
  return s;
}

function imageScene(texture, boost) {
  // Equirect on a sphere so the same PMREM path handles images, HDRIs and the sweep card.
  const s = new THREE.Scene();
  const mat = new THREE.ShaderMaterial({
    side: THREE.BackSide,
    depthWrite: false,
    uniforms: { map: { value: texture }, boost: { value: boost } },
    vertexShader:
      "varying vec2 vUv; void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position,1.); }",
    // LDR -> pseudo-HDR: brightest ~10% of the plate is pushed to 1+boost so it can bloom.
    fragmentShader: `uniform sampler2D map; uniform float boost; varying vec2 vUv;
      void main(){ vec3 c = texture2D(map, vec2(1.0 - vUv.x, vUv.y)).rgb;
        float l = max(c.r, max(c.g, c.b));
        gl_FragColor = vec4(c * (1.0 + boost * pow(l, 6.0)), 1.0); }`,
  });
  s.add(new THREE.Mesh(new THREE.SphereGeometry(30, 64, 32), mat));
  return s;
}

async function loadEnvScene(env, boost) {
  if (!env || env === "studio") return studioScene();
  if (env === "room") return new RoomEnvironment();
  const ext = env.split("?")[0].split(".").pop().toLowerCase();
  if (ext === "hdr") return imageScene(await new HDRLoader().loadAsync(env), 0);
  if (ext === "exr") return imageScene(await new EXRLoader().loadAsync(env), 0);
  const tex = await new THREE.TextureLoader().loadAsync(env);
  tex.colorSpace = THREE.SRGBColorSpace;
  return imageScene(tex, boost);
}

// ---------------------------------------------------------------------------------------------
// Geometry kinds
// ---------------------------------------------------------------------------------------------
const fontCache = new Map();
const DEFAULT_FONT = new URL("./fonts/Inter-Bold-Latin.ttf", import.meta.url).href; // static Inter Bold, Latin subset (OFL); pass opts.font for the brand face
async function loadFont(url) {
  url = url || DEFAULT_FONT;
  // opentype.js cannot read woff2 or variable axes: convert with runtime/hero3d/tools/fontconv.py first.
  if (/\.woff2(\?|$)/i.test(url)) throw new Error("hero3d: woff2 is not readable by opentype.js. Run runtime/hero3d/tools/fontconv.py (woff2/variable -> static .ttf).");
  if (!fontCache.has(url)) {
    const loader = /\.json(\?|$)/i.test(url) ? new FontLoader() : new TTFLoader();
    fontCache.set(
      url,
      loader.loadAsync(url).then((d) => (d.generateShapes ? d : new FontLoader().parse(d))),
    );
  }
  return fontCache.get(url);
}

/** Creased normals for extruded shapes: smooth across the bevel steps, crisp at the face/wall edges, and the big flat caps keep their exact +-z normal (otherwise caps pick up the
 *  bevel's tilt at their boundary vertices and show fan-shaped shading). */
function smoothBevel(geo, crease = 0.5) {
  const g = toCreasedNormals(geo.index ? geo.toNonIndexed() : geo, crease),
    p = g.attributes.position,
    n = g.attributes.normal,
    a = new THREE.Vector3(),
    b = new THREE.Vector3(),
    c = new THREE.Vector3();
  for (let i = 0; i < p.count; i += 3) {
    a.fromBufferAttribute(p, i);
    b.fromBufferAttribute(p, i + 1).sub(a);
    c.fromBufferAttribute(p, i + 2).sub(a);
    b.cross(c).normalize();
    if (Math.abs(b.z) > 0.9995) for (let k = 0; k < 3; k++) n.setXYZ(i + k, 0, 0, Math.sign(b.z));
  }
  return g;
}

/** Extruded, bevelled type. The bevel is what catches light; without it chrome text looks flat.
 *  tracking is in em (negative = tighter, display type usually wants -0.02..-0.05). */
function textGeometry(font, text, o = {}) {
  const size = o.size ?? 1,
    tracking = o.tracking ?? -0.02;
  const extrude = {
    depth: o.depth ?? 0.3 * size,
    curveSegments: o.curveSegments ?? 12,
    bevelEnabled: true,
    bevelThickness: o.bevelThickness ?? 0.05 * size,
    bevelSize: o.bevelSize ?? 0.03 * size,
    bevelSegments: o.bevelSegments ?? 6,
  };
  const scale = size / font.data.resolution;
  const parts = [];
  let x = 0;
  for (const ch of text) {
    const glyph = font.data.glyphs[ch] || font.data.glyphs["?"];
    if (ch.trim()) {
      const g = new THREE.ExtrudeGeometry(font.generateShapes(ch, size), extrude);
      g.translate(x, 0, 0);
      parts.push(g);
    }
    x += glyph.ha * scale + tracking * size;
  }
  // creased normals: smooth bevels, crisp face/wall edges (flat per-triangle normals make a lacquer or chrome bevel read as facets)
  const geo = smoothBevel(
    mergeGeometries(
      parts.map((g) => (g.index ? g.toNonIndexed() : g)),
      false,
    ),
    o.crease ?? 0.5,
  );
  geo.computeBoundingBox();
  const c = new THREE.Vector3();
  geo.boundingBox.getCenter(c);
  geo.translate(-c.x, -c.y, -c.z); // pivot at the visual centre
  return geo;
}

/** SVG mark extruded with a bevel. Several parts that must line up (ring + dot) use { center:false, perUnit: <world units per SVG unit>, ref: <reference size> } so they share one
 *  coordinate system (SVG origin = object origin) and one depth/bevel. `svg` = a path `d` string, an array of d strings (one outline each), or full <svg> markup (every path/fill rule is read by SVGLoader;
 *  holes come from winding / evenodd). Centred, y flipped (SVG y is down), scaled so the WIDTH is `size` world units; depth / bevel are fractions of `size`. */
function logoGeometry(o = {}) {
  const markup = Array.isArray(o.svg)
    ? `<svg xmlns="http://www.w3.org/2000/svg">${o.svg.map((d) => `<path d="${d}"/>`).join("")}</svg>`
    : /^\s*<svg/i.test(o.svg || "")
      ? o.svg
      : `<svg xmlns="http://www.w3.org/2000/svg"><path d="${o.svg}"/></svg>`;
  const shapes = new SVGLoader().parse(markup).paths.flatMap((p) => p.toShapes());
  if (!shapes.length) throw new Error("hero3d: logo svg has no fillable shapes (strokes are ignored; outline them first)");
  // work in SVG units first, then normalise (bevel values are relative to the final width)
  const probe = new THREE.ShapeGeometry(shapes);
  probe.computeBoundingBox();
  const w = probe.boundingBox.max.x - probe.boundingBox.min.x,
    k = o.perUnit ?? (o.size ?? 2.6) / w,
    size = o.ref ?? w * k;
  const geo = new THREE.ExtrudeGeometry(shapes, {
    depth: (o.depth ?? 0.16) * size / k,
    bevelEnabled: true,
    bevelThickness: (o.bevelThickness ?? 0.022) * size / k,
    bevelSize: (o.bevelSize ?? 0.016) * size / k,
    bevelSegments: o.bevelSegments ?? 6,
    curveSegments: o.curveSegments ?? 48,
  });
  geo.scale(k, -k, k);
  // the y mirror reverses triangle winding: swap vertices 1 and 2 of every triangle so faces point outward again
  const swap = (arr, n) => { for (let i = 0; i < arr.count; i += 3) for (let j = 0; j < n; j++) { const a = arr.array[(i + 1) * n + j]; arr.array[(i + 1) * n + j] = arr.array[(i + 2) * n + j]; arr.array[(i + 2) * n + j] = a; } };
  if (geo.index) { const ix = geo.index; for (let i = 0; i < ix.count; i += 3) { const a = ix.getX(i + 1); ix.setX(i + 1, ix.getX(i + 2)); ix.setX(i + 2, a); } }
  else { swap(geo.attributes.position, 3); if (geo.attributes.uv) swap(geo.attributes.uv, 2); }
  // smooth the bevel (creaseAngle ~29 deg) but keep the face / wall edges crisp; without this a chrome or lacquer bevel shows facets
  const out = smoothBevel(geo, o.crease ?? 0.5);
  out.computeBoundingBox();
  const c = new THREE.Vector3();
  out.boundingBox.getCenter(c);
  if (o.center !== false) out.translate(-c.x, -c.y, -c.z);
  return out;
}

/** Coin: lathe profile with a raised rim and recessed face, so the rim reads as a bright ring. */
function coinGeometry(r = 1, t = 0.16) {
  const h = t / 2,
    prof = [
      [0, h * 0.55],
      [0.8, h * 0.55],
      [0.83, h * 0.8],
      [0.86, h],
      [0.965, h],
      [1, h * 0.72],
      [1, -h * 0.72],
      [0.965, -h],
      [0.86, -h],
      [0.83, -h * 0.8],
      [0.8, -h * 0.55],
      [0, -h * 0.55],
    ];
  // Profile runs bottom -> top so LatheGeometry's normals face OUT (top -> bottom renders inside-out).
  const g = new THREE.LatheGeometry(
    prof.reverse().map(([x, y]) => new THREE.Vector2(x * r, y)),
    160,
  );
  g.rotateX(Math.PI / 2); // face the camera (+Z)
  // Planar UVs across the face (lathe UVs run around the rim, so a texture or thin-film
  // thickness map would be constant across the face).
  const p = g.attributes.position,
    uv = g.attributes.uv;
  for (let i = 0; i < p.count; i++) uv.setXY(i, p.getX(i) / (2 * r) + 0.5, p.getY(i) / (2 * r) + 0.5);
  return g;
}

function roundedRectShape(w, h, r) {
  const s = new THREE.Shape(),
    x = -w / 2,
    y = -h / 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 + h - r);
  s.quadraticCurveTo(x + w, y + h, x + w - r, y + h);
  s.lineTo(x + r, y + h);
  s.quadraticCurveTo(x, y + h, x, y + h - r);
  s.lineTo(x, y + r);
  s.quadraticCurveTo(x, y, x + r, y);
  return s;
}

async function buildObject(o, defaults) {
  const mat = o.materialInstance || makeMaterial(o.material ?? defaults.material, o.color, o.materialParams);
  const root = new THREE.Group();
  let mixer = null;
  switch (o.kind) {
    case "group":
      break; // empty transform node for parenting parts
    case "extrudedText": {
      const font = await loadFont(o.font ?? defaults.font);
      root.add(new THREE.Mesh(textGeometry(font, o.text ?? "Launch", o), mat));
      break;
    }
    case "logo": {
      if (!o.svg) throw new Error('hero3d: kind "logo" needs opts.svg (path d, array of d, or <svg> markup)');
      root.add(new THREE.Mesh(logoGeometry(o), mat));
      break;
    }
    case "coin": {
      const r = o.radius ?? 1;
      root.add(new THREE.Mesh(coinGeometry(r, o.thickness ?? 0.16 * r), mat));
      if (o.text) {
        // embossed mark on both faces
        const font = await loadFont(o.font ?? defaults.font);
        const g = textGeometry(font, o.text, {
          size: r * (o.markSize ?? 0.9),
          depth: 0.02 * r,
          bevelThickness: 0.012 * r,
          bevelSize: 0.01 * r,
          bevelSegments: 3,
          tracking: 0,
        });
        const front = new THREE.Mesh(g, mat);
        front.position.z = 0.16 * r * 0.28;
        const back = front.clone();
        back.rotation.y = Math.PI;
        back.position.z *= -1;
        root.add(front, back);
      }
      break;
    }
    case "glassSlab": {
      const [w, h, d] = o.dimensions ?? [2.4, 3, 0.3];
      root.add(new THREE.Mesh(new RoundedBoxGeometry(w, h, d, 6, o.cornerRadius ?? 0.14), mat));
      break;
    }
    case "phone": {
      const [w, h, d] = o.dimensions ?? [1, 2.08, 0.11],
        r = o.cornerRadius ?? 0.14;
      root.add(new THREE.Mesh(new RoundedBoxGeometry(w, h, d, 8, r), mat)); // frame + back
      const sg = new THREE.ShapeGeometry(roundedRectShape(w * 0.94, h * 0.965, r * 0.85), 12);
      sg.computeBoundingBox();
      const bb = sg.boundingBox,
        uv = sg.attributes.uv,
        p = sg.attributes.position;
      for (let i = 0; i < uv.count; i++)
        uv.setXY(
          i,
          (p.getX(i) - bb.min.x) / (bb.max.x - bb.min.x),
          (p.getY(i) - bb.min.y) / (bb.max.y - bb.min.y),
        );
      const glass = new THREE.MeshPhysicalMaterial({
        color: "#000000",
        roughness: 0.04,
        metalness: 0,
        clearcoat: 1,
        clearcoatRoughness: 0.02,
        emissive: "#ffffff",
        emissiveIntensity: o.screenIntensity ?? 1,
      });
      if (o.screen) {
        const tx = await new THREE.TextureLoader().loadAsync(o.screen);
        tx.colorSpace = THREE.SRGBColorSpace;
        glass.emissiveMap = tx;
      } else glass.emissive.set("#050608");
      const screen = new THREE.Mesh(sg, glass);
      screen.position.z = d / 2 + 0.001;
      root.add(screen);
      break;
    }
    case "gltf": {
      const gltf = await new GLTFLoader().loadAsync(o.src);
      const model = gltf.scene;
      if (o.material)
        model.traverse((m) => {
          if (m.isMesh) m.material = mat;
        });
      const box = new THREE.Box3().setFromObject(model),
        size = box.getSize(new THREE.Vector3());
      const k = (o.fit ?? 2) / Math.max(size.x, size.y, size.z); // fit longest side to `fit`
      model.scale.setScalar(k);
      model.position.copy(box.getCenter(new THREE.Vector3()).multiplyScalar(-k));
      root.add(model);
      if (gltf.animations.length) {
        mixer = new THREE.AnimationMixer(model);
        gltf.animations.forEach((a) => mixer.clipAction(a).play());
      }
      break;
    }
    default:
      throw new Error(`hero3d: unknown kind "${o.kind}"`);
  }
  root.traverse((m) => {
    if (m.isMesh) {
      m.castShadow = true;
      m.receiveShadow = true;
    }
  });
  return {
    id: o.id ?? "hero",
    root,
    mixer,
    base: {
      position: o.position ?? [0, 0, 0],
      rotation: o.rotation ?? [0, 0, 0],
      scale: o.scale ?? 1,
    },
  };
}

// ---------------------------------------------------------------------------------------------
// createHero3D
// ---------------------------------------------------------------------------------------------
/**
 * @param {HTMLCanvasElement} canvas
 * @param {object} opts
 *   kind, text, font, material, color, materialParams  single-object shorthand (id 'hero')
 *   objects: [{ id, kind, ...same keys, position, rotation, scale, parent }]   several objects (keep it to 1-2 visible
 *            subjects; a mark built from parts is ONE subject: give the parts `parent: '<group id>'`,
 *            where the group is { id, kind: 'group' } with no geometry)
 *   width=1920, height=1080, pixelRatio=1            pinned: never read devicePixelRatio for video
 *   background: null (transparent, default) | '#0b0b0c'
 *   envMap: 'studio' | 'room' | url(.jpg/.png/.hdr/.exr);  envIntensity=1; envRotation=[0,0,0]; envBoost=4
 *   sweep: { width: 0.8, intensity: 14, color, from: [-9,1,12], to: [9,1,12], tilt: 0.35 }  moving softbox (state.sweep drives it).
 *          It sits on the CAMERA side: flat faces reflect what is behind the camera.
 *   key:   { position: [-5,6,5], intensity: 2, color }   top-left key by default; false to disable
 *   rim:   { position: [5,3,-6], intensity: 3, color }   false to disable
 *   ground: false | { y: -1, opacity: 0.45 }  shadow catcher (only the shadow is drawn; works transparent)
 *   camera: { fov: 30, position: [0,0.3,9], target: [0,0,0] }
 *   toneMapping: 'neutral' (brand-accurate, default) | 'agx' | 'aces';  exposure=1
 *   bloom: false | { strength: 0.06, radius: 0, threshold: 3, falloff: [1,.55,.25,.08,.02], clamp: 6 }  (threshold in linear HDR: only real highlights)
 *   dof:   false | { aperture: 0.0015, maxblur: 0.006, focus }   focus defaults to camera->target distance
 *   msaa=4   samples on the post-processing target (the canvas's own antialias is lost behind a composer)
 *   state(t, objs, ctx) -> state | void   the shot as a pure function (alias: motion). Runs AFTER every transform/light/camera was reset to base, so anything it does
 *          not touch is back at base. objs = { id: Object3D } (also usable directly: objs.mark.rotation.y = ...), ctx = { f, t, W, H, THREE, scene, camera, keyLight, rimLight, objects, key, pulse, ease, rng, hero }.
 *          Return a state object (below) for camera/lights/post; objects may be driven by return value or by mutation.
 *   build(THREE, scene, camera, ctx) -> Object3D[] | { id: Object3D }   build your own meshes/groups; returned objects join the per-frame reset and state.objects[id]
 *   objects[].kind: extrudedText | logo (svg: path d | [d..] | <svg> markup; size, depth, bevelThickness, bevelSize, crease) | coin | glassSlab | phone | gltf | group
 * @returns {Promise<{renderAt(t:number, state?:object):void, scene, camera, renderer, objects, dispose()}>}
 *
 * state (all optional, all absolute, never deltas):
 *   camera: { position, target, fov }
 *   keyPosition, rimPosition: [x,y,z]   move the lights (a travelling key makes the bevel catch light)
 *   objects: { [id]: { position, rotation, scale, visible } }   (single-object: id 'hero')
 *   sweep: 0..1 position of the sweep softbox along from->to; null/undefined = no sweep
 *   exposure, bloom (strength), focus (DOF distance), envIntensity, keyIntensity, rimIntensity
 *   animTime: glTF clip time (defaults to t);  warpTime: phase of the liquid warp (materialParams.warp)
 */
export async function createHero3D(canvas, opts = {}) {
  const W = opts.width ?? 1920,
    H = opts.height ?? 1080;
  const renderer = new THREE.WebGLRenderer({
    canvas,
    alpha: true,
    antialias: true,
    preserveDrawingBuffer: true,
    premultipliedAlpha: true,
    powerPreference: "high-performance",
  });
  renderer.setPixelRatio(opts.pixelRatio ?? 1);
  renderer.setSize(W, H, false);
  renderer.outputColorSpace = THREE.SRGBColorSpace;
  renderer.toneMapping = {
    neutral: THREE.NeutralToneMapping,
    agx: THREE.AgXToneMapping,
    aces: THREE.ACESFilmicToneMapping,
    none: THREE.NoToneMapping,
  }[opts.toneMapping ?? "neutral"];
  renderer.shadowMap.enabled = !!opts.ground;
  renderer.shadowMap.type = THREE.PCFShadowMap;

  const scene = new THREE.Scene();
  if (opts.background) scene.background = new THREE.Color(opts.background);
  else renderer.setClearColor(0x000000, 0);

  // --- objects
  const specs = opts.objects ?? (opts.kind ? [{ id: "hero", ...opts }] : []);
  const objects = await Promise.all(specs.map((s) => buildObject(s, opts)));
  // `parent: '<id>'` nests an object under another (a mark built from parts moves as ONE object).
  // Safe with the per-frame reset: renderAt sets each root's LOCAL transform, parents first or not.
  const byId = Object.fromEntries(objects.map((o) => [o.id, o]));
  specs.forEach((sp, i) => {
    const parent = sp.parent && byId[sp.parent];
    if (sp.parent && !parent) throw new Error(`hero3d: parent "${sp.parent}" not found for "${objects[i].id}"`);
    (parent ? parent.root : scene).add(objects[i].root);
  });

  // --- environment (+ optional sweep card baked per frame)
  const pmrem = new THREE.PMREMGenerator(renderer);
  const envScene = await loadEnvScene(opts.envMap, opts.envBoost ?? 4);
  const sw = {
    width: 0.8, // keep it NARROW (~4 deg): a wide card flashes the whole object instead of travelling
    intensity: 14,
    color: "#ffffff",
    from: [-9, 1, 12],
    to: [9, 1, 12],
    tilt: 0.35, // radians of roll: a diagonal streak reads as a sweep, a vertical one as a wipe
    ...(opts.sweep || {}),
  };
  const card = softbox(sw.width, 26, sw.intensity, sw.color);
  card.visible = false;
  envScene.add(card);
  const envSize = opts.envSize ?? 256;
  const baseEnv = pmrem.fromScene(envScene, 0.02, 0.1, 100, { size: envSize });
  let sweepEnv = null,
    sweepKey = null;
  function envFor(sweep) {
    if (sweep == null || sweep <= 0 || sweep >= 1) return baseEnv.texture;
    const k = Math.round(sweep * 1e4); // cache by value: repeated seeks cost nothing
    if (k !== sweepKey) {
      card.position.fromArray(lerp(sw.from, sw.to, sweep));
      card.lookAt(0, 0, 0);
      card.rotateZ(sw.tilt);
      card.visible = true;
      sweepEnv?.dispose();
      sweepEnv = pmrem.fromScene(envScene, 0.02, 0.1, 100, { size: envSize });
      card.visible = false;
      sweepKey = k;
    }
    return sweepEnv.texture;
  }
  scene.environmentRotation.fromArray(opts.envRotation ?? [0, 0, 0]);

  // --- lights: env does the lighting; key/rim add the sharp speculars that bloom
  const mkLight = (cfg, def) => {
    if (cfg === false) return null;
    const c = { ...def, ...(cfg || {}) },
      l = new THREE.DirectionalLight(c.color ?? "#ffffff", c.intensity);
    l.position.fromArray(c.position);
    l.userData.base = c.intensity;
    l.userData.basePos = [...c.position];
    scene.add(l);
    return l;
  };
  const keyLight = mkLight(opts.key, { position: [-5, 6, 5], intensity: 2 });
  const rimLight = mkLight(opts.rim, { position: [5, 3, -6], intensity: 3 });
  if (opts.ground && keyLight) {
    keyLight.castShadow = true;
    keyLight.shadow.mapSize.set(2048, 2048);
    keyLight.shadow.radius = 6;
    keyLight.shadow.bias = -0.0005;
    Object.assign(keyLight.shadow.camera, {
      left: -6,
      right: 6,
      top: 6,
      bottom: -6,
      far: 40,
    });
    const ground = new THREE.Mesh(
      new THREE.PlaneGeometry(60, 60),
      new THREE.ShadowMaterial({ opacity: opts.ground.opacity ?? 0.45 }),
    );
    ground.rotation.x = -Math.PI / 2;
    ground.position.y = opts.ground.y ?? -1;
    ground.receiveShadow = true;
    scene.add(ground);
  }

  // --- camera
  const cam0 = {
    fov: 30,
    position: [0, 0.3, 9],
    target: [0, 0, 0],
    ...(opts.camera || {}),
  };
  const camera = new THREE.PerspectiveCamera(cam0.fov, W / H, 0.1, 200);

  // --- custom objects from opts.build: they join the per-frame reset and state.objects[id]
  const ctx = { W, H, THREE, scene, camera, keyLight, rimLight, key, pulse, ease, rng, f: 0, t: 0 };
  if (opts.build) {
    const made = await opts.build(THREE, scene, camera, ctx);
    const list = Array.isArray(made) ? made.map((m, i) => [m.name || "obj" + i, m]) : Object.entries(made || {});
    for (const [id, ob] of list) {
      const root = ob.isObject3D ? ob : ob.root;
      if (!root.parent) scene.add(root);
      root.traverse((m) => { if (m.isMesh) { m.castShadow = true; m.receiveShadow = true; } });
      const rec = { id, root, mixer: null, base: { position: root.position.toArray(), rotation: [root.rotation.x, root.rotation.y, root.rotation.z], scale: root.scale.toArray() } };
      objects.push(rec);
      byId[id] = rec;
    }
  }

  // --- post: Render -> Bokeh -> Bloom (on linear HDR, so only real highlights glow) -> Output
  let composer = null,
    bloomPass = null,
    bokehPass = null;
  if (opts.bloom || opts.dof) {
    const rt = new THREE.WebGLRenderTarget(W, H, {
      type: THREE.HalfFloatType,
      samples: opts.msaa ?? 4,
    });
    composer = new EffectComposer(renderer, rt);
    composer.setPixelRatio(opts.pixelRatio ?? 1);
    composer.setSize(W, H);
    composer.addPass(new RenderPass(scene, camera));
    if (opts.dof) {
      const d = {
        aperture: 0.0015,
        maxblur: 0.006,
        ...(opts.dof === true ? {} : opts.dof),
      };
      bokehPass = new BokehPass(scene, camera, {
        focus: d.focus ?? 9,
        aperture: d.aperture,
        maxblur: d.maxblur,
      });
      bokehPass.userData = d;
      composer.addPass(bokehPass);
    }
    if (opts.bloom) {
      const b = {
        strength: 0.06, // mirror materials: 0.03-0.08. Above ~0.15 the frame fogs.
        radius: 0,
        threshold: 3,
        ...(opts.bloom === true ? {} : opts.bloom),
      };
      bloomPass = new UnrealBloomPass(new THREE.Vector2(W, H), b.strength, b.radius, b.threshold);
      bloomPass.userData = b;
      // Tighter mip weights than three's default [1,.8,.6,.4,.2]: the glow hugs the highlight
      // instead of fogging the whole frame when a 10x-bright softbox hits a mirror surface.
      bloomPass.compositeMaterial.uniforms.bloomFactors.value = b.falloff ?? [1, 0.55, 0.25, 0.08, 0.02];
      // Clamp what feeds the bloom. A punctual light on a roughness-0.07 mirror has a GGX peak in the
      // thousands; unclamped, one glint fogs the entire frame. The picture itself is not clamped.
      const hp = bloomPass.materialHighPassFilter;
      hp.fragmentShader = hp.fragmentShader.replace(
        "mix( outputColor, texel, alpha )",
        `mix( outputColor, min( texel, vec4( ${(b.clamp ?? 6).toFixed(2)} ) ), alpha )`,
      );
      hp.needsUpdate = true;
      composer.addPass(bloomPass);
    }
    composer.addPass(new OutputPass());
  }

  const v3 = new THREE.Vector3();
  const warpUniforms = new Set();
  scene.traverse((m) => m.material?.userData?.warp && warpUniforms.add(m.material.userData.warp));
  const stateFn = opts.state ?? opts.motion;
  const objMap = Object.fromEntries(objects.map((o) => [o.id, o.root]));
  Object.assign(ctx, { keyLight, rimLight, objects: objMap, hero: null });
  function renderAt(t, state, f = Math.round(t * 30)) {
    // 1. Reset everything to base, THEN ask for the state. No carry-over from the previous call, so frame N is the same whether jumped to or played to.
    for (const o of objects) {
      o.root.position.fromArray(o.base.position);
      o.root.rotation.set(...o.base.rotation);
      Array.isArray(o.base.scale) ? o.root.scale.fromArray(o.base.scale) : o.root.scale.setScalar(o.base.scale);
      o.root.visible = true;
    }
    camera.position.fromArray(cam0.position);
    camera.fov = cam0.fov;
    if (keyLight) keyLight.position.fromArray(keyLight.userData.basePos);
    if (rimLight) rimLight.position.fromArray(rimLight.userData.basePos);
    ctx.t = t;
    ctx.f = f;
    if (state == null) state = (stateFn ? stateFn(t, objMap, ctx) : null) || {};
    for (const o of objects) {
      const s = state.objects?.[o.id];
      if (!s) { o.mixer?.setTime(state.animTime ?? t); continue; }
      if (s.position) o.root.position.fromArray(s.position);
      if (s.rotation) o.root.rotation.set(...s.rotation);
      if (s.scale != null) Array.isArray(s.scale) ? o.root.scale.fromArray(s.scale) : o.root.scale.setScalar(s.scale);
      o.root.visible = s.visible ?? true;
      o.mixer?.setTime(state.animTime ?? t);
    }
    const c = { ...cam0, ...(state.camera || {}) };
    camera.position.fromArray(c.position);
    camera.fov = c.fov;
    camera.updateProjectionMatrix();
    camera.lookAt(v3.fromArray(c.target));
    if (keyLight && state.keyPosition) keyLight.position.fromArray(state.keyPosition);
    if (rimLight && state.rimPosition) rimLight.position.fromArray(state.rimPosition);
    scene.environment = envFor(state.sweep);
    scene.environmentIntensity = state.envIntensity ?? opts.envIntensity ?? 1;
    if (keyLight) keyLight.intensity = state.keyIntensity ?? keyLight.userData.base;
    if (rimLight) rimLight.intensity = state.rimIntensity ?? rimLight.userData.base;
    renderer.toneMappingExposure = state.exposure ?? opts.exposure ?? 1;
    for (const u of warpUniforms) u.uWarpTime.value = state.warpTime ?? 0;
    // 2. Render.
    if (composer) {
      if (bokehPass) {
        bokehPass.uniforms.focus.value =
          state.focus ?? bokehPass.userData.focus ?? camera.position.distanceTo(v3.fromArray(c.target));
        bokehPass.uniforms.aperture.value = state.aperture ?? bokehPass.userData.aperture;
      }
      if (bloomPass) bloomPass.strength = state.bloom ?? bloomPass.userData.strength;
      composer.render();
    } else renderer.render(scene, camera);
  }

  // Compile every shader now so the first sought frame is not a blank compile frame.
  scene.environment = baseEnv.texture;
  renderer.compile(scene, camera);

  const handle = {
    renderAt,
    scene,
    camera,
    renderer,
    canvas,
    W,
    H,
    objects: Object.fromEntries(objects.map((o) => [o.id, o])),
    dispose() {
      composer?.dispose();
      baseEnv.dispose();
      sweepEnv?.dispose();
      pmrem.dispose();
      renderer.dispose();
    },
  };
  ctx.hero = handle;
  renderAt(0, undefined, 0); // warm-up draw: compiles the post chain and any transmission pass now, not on the first sought frame
  return handle;
}