@genex-ai/cli-demo 1.5.2-dev.398 → 1.6.0-dev.403

package/templates/asset-viewer/src/viewer/stage.js

@@ -0,0 +1,776 @@
+// The neutral stage every asset is shown on: renderer, camera, environment,
+// lights, ground shadow and the turntable. Deliberately no floor, no grid, no
+// scale figure.
+//
+// The library is not only floor-standing props. A wall bracket, a ceiling lamp
+// or a hand tool standing on a ground plane reads as a mistake rather than as a
+// stage, and a grid that is right for a pallet is wrong for the next asset in.
+// What replaces the floor is a LIT BACKDROP plus a soft ground shadow that has
+// no edges of its own - both are presentation that is never wrong for whatever
+// it is showing, and the HUD already states the real size in metres.
+//
+// This is the file that makes the library look like one product, which is why it
+// is copied verbatim and hashed by gate G13. Edit it in
+// packages/asset-viewer-template/template/src/viewer, never in an asset folder.
+
+import * as THREE from "three";
+
+const TURNTABLE_PERIOD_S = 12;
+const MAX_DPR = 1.5;
+
+// --- Backdrop --------------------------------------------------------------
+// A pool of light behind the subject, falling off to near-black in the corners.
+//
+// The flat grey it replaces was measured (L* 32.5) as the one value that kept
+// every asset's outline above the just-noticeable difference - a flat backdrop
+// has to serve the darkest asset and the lightest one with a single number, and
+// at L* 20.6 a third of the wheelie bin's outline disappeared into it.
+//
+// A pool removes that compromise instead of re-tuning it. The subject is
+// silhouetted against POOL, which lands within a couple of points of that
+// measured-safe grey, so the outline separation it was chosen for still holds;
+// the darkness lives out at the corners, where no asset has any geometry. Both
+// values are final sRGB - the backdrop is chrome, not lit geometry, so it is
+// written straight to the output buffer with no tone mapping and no colour
+// conversion applied to it.
+// Raised 2026-08-13 (owner: "make the whole scene a little brighter"). The
+// previous pool measured L* 23.7 - about nine points BELOW the L* 32.5 this
+// comment already names as the outline-safe value, so brightening moves it onto
+// that measurement rather than away from it: #444a54 measures L* 31.5. The
+// corners come up with it so the whole field reads lighter, while the pool-to-
+// corner ratio is kept close to what it was, which is what preserves the
+// vignette instead of flattening the backdrop into one grey.
+const POOL = [0x44 / 255, 0x4a / 255, 0x54 / 255];
+const CORNER = [0x22 / 255, 0x25 / 255, 0x2b / 255];
+// The pool sits above centre: the camera aims a little above the centroid, so
+// this puts the brightest part of the backdrop behind the subject's mass.
+const POOL_CENTRE_Y = 0.56;
+
+const BACKDROP_VERT = /* glsl */ `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+
+// The dither is not decoration. A pool this wide crosses ~60 8-bit steps over
+// ~900 px, which is textbook Mach banding; one pixel of ordered noise costs
+// nothing and removes every ring.
+const BACKDROP_FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vUv;
+uniform vec3 uPool;
+uniform vec3 uCorner;
+uniform float uAspect;
+
+void main() {
+  vec2 p = vUv - vec2(0.5, ${POOL_CENTRE_Y.toFixed(2)});
+  p.x *= uAspect;
+  float d = length(p);
+  float pool = smoothstep(0.92, 0.02, d);
+  // The exponent is the pool's focus, and it is the ONE knob here that softens
+  // the light without lifting the corners. Widening the smoothstep would blur
+  // it too, but the outer edge is what holds the corners at CORNER - push that
+  // out and the darkness goes with it. Lowering the exponent spreads brightness
+  // through the mid-field while d >= 0.92 still lands on exactly zero.
+  pool = pow(pool, 1.08);
+  vec3 col = mix(uCorner, uPool, pool);
+  float n = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
+  col += (n - 0.5) / 255.0;
+  gl_FragColor = vec4(col, 1.0);
+}
+`;
+
+function createBackdrop() {
+  const scene = new THREE.Scene();
+  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+  const material = new THREE.ShaderMaterial({
+    vertexShader: BACKDROP_VERT,
+    fragmentShader: BACKDROP_FRAG,
+    uniforms: {
+      uPool: { value: new THREE.Vector3(...POOL) },
+      uCorner: { value: new THREE.Vector3(...CORNER) },
+      uAspect: { value: 1 },
+    },
+    depthTest: false,
+    depthWrite: false,
+  });
+  const mesh = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), material);
+  mesh.frustumCulled = false;
+  scene.add(mesh);
+  return { scene, camera, material, mesh };
+}
+
+// --- Environment -----------------------------------------------------------
+// Indirect light, which is the half of a real room that a directional light
+// cannot fake. Without it a metal reads as flat grey paint - metalness 1.0 has
+// no diffuse term at all, so with only analytic lights it has nothing to
+// reflect and renders near-black - and every unlit face is a single ambient
+// constant, which is exactly what made the old turntable's dark side look like
+// a cut-out.
+//
+// Built procedurally out of coloured panels and pre-filtered with PMREM, so the
+// viewer still ships no HDRI and still loads no external file: the same rule the
+// asset modules live under, applied to their host.
+//
+// Panel colours are set with setRGB, which is working (linear) space, NOT
+// setHex, which converts from sRGB - these are light intensities above 1.0 and
+// converting them would clamp the whole point of the environment away.
+const ENV_PANELS = [
+  // [x, y, z, w, h, d, r, g, b] - a soft box key upper front-right, a broad
+  // cool fill to the left, a warm bounce low and front (the floor light a room
+  // has and this stage does not), and a dim rim behind.
+  [3.4, 3.0, 3.0, 4.2, 3.0, 0.1, 3.4, 3.2, 2.9],
+  [-4.0, 1.8, 1.4, 0.1, 4.0, 5.0, 0.9, 1.05, 1.35],
+  [0.0, -2.4, 2.6, 6.0, 0.1, 4.0, 0.62, 0.55, 0.48],
+  [0.0, 2.2, -4.2, 5.0, 3.0, 0.1, 0.5, 0.58, 0.72],
+  [0.0, 4.4, 0.0, 5.0, 0.1, 5.0, 0.85, 0.9, 1.0],
+];
+
+function buildEnvironment(renderer) {
+  const scene = new THREE.Scene();
+  const disposables = [];
+
+  const shellGeo = new THREE.BoxGeometry(14, 10, 14);
+  const shellMat = new THREE.MeshBasicMaterial({ side: THREE.BackSide });
+  shellMat.color.setRGB(0.055, 0.06, 0.072);
+  scene.add(new THREE.Mesh(shellGeo, shellMat));
+  disposables.push(shellGeo, shellMat);
+
+  for (const [x, y, z, w, h, d, r, g, b] of ENV_PANELS) {
+    const geo = new THREE.BoxGeometry(w, h, d);
+    const mat = new THREE.MeshBasicMaterial();
+    mat.color.setRGB(r, g, b);
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.position.set(x, y, z);
+    scene.add(mesh);
+    disposables.push(geo, mat);
+  }
+
+  const pmrem = new THREE.PMREMGenerator(renderer);
+  pmrem.compileEquirectangularShader();
+  const target = pmrem.fromScene(scene, 0.02);
+  pmrem.dispose();
+  for (const d of disposables) d.dispose();
+  return target.texture;
+}
+
+// --- Ground shadow ---------------------------------------------------------
+// A soft contact shadow, rendered once per fit into a texture and shown on a
+// plane at the asset's base.
+//
+// A shadow-mapped floor was the obvious alternative and is the wrong one here:
+// a floor plane has EDGES, and the moment the camera drops toward the horizon
+// the stage stops being a backdrop and becomes a room with a visible tabletop
+// in it. This has no edges - the darkness only exists where the asset is, and
+// fades to nothing well inside the plane, so a wall bracket gets a drop shadow
+// rather than a floor.
+const SHADOW_RES = 512;
+const SHADOW_STRENGTH = 0.74;
+// Two separable passes at falling radii, in texels. The first cut ran one pass
+// at 1.6 texels - about a centimetre across a metre-wide plane - which is a blur
+// nobody can see.
+const SHADOW_BLUR_TEXELS = [30, 12];
+// How much room to leave around the shadow's own bounds, as a fraction of the
+// footprint, so the blur has somewhere to spill and its soft edge is never cut
+// off square.
+const SHADOW_PAD = 0.26;
+// The elevation the ground shadow is CAST from - deliberately steeper than the
+// 35-degree key, and this is the number that decides whether the shadow exists
+// as far as a viewer is concerned.
+//
+// Straight down (the first cut) is the honest ambient-occlusion answer and it is
+// invisible: the shadow lands exactly under the asset's own footprint, so the
+// asset covers every pixel of it from every angle that can see the ground at
+// all. Measured on the espresso machine - a correct, well-formed shadow that
+// nothing could ever see. At the key's own 35 degrees the shadow stretches 1.4x
+// the asset's height and the stage turns into a room with a floor in it. 52
+// throws it about 0.8x the height, which clears the silhouette and stays a pool
+// rather than becoming scenery.
+const SHADOW_ELEVATION_DEG = 52;
+
+// Where the key stands, and it is a presentation decision rather than a detail.
+//
+// The old value put the key at the SAME azimuth as the camera's home angle -
+// the light sitting exactly behind the viewer's head. That is the one placement
+// that carves no form at all (every surface the camera can see is lit straight
+// on) and it is also the one placement whose shadow is invisible, because the
+// shadow falls along the view axis and hides behind the asset that cast it.
+// Both symptoms, one cause. 45 degrees off the camera is the ordinary studio
+// three-quarter key: it models the form, and it throws the shadow out to the
+// side where it can be seen.
+const KEY_AZIMUTH_DEG = 0;
+const KEY_ELEVATION_DEG = 35;
+
+// Every vertex is slid down its own light ray onto the ground plane, which is
+// the whole trick: the pass is an ordinary render of the asset, but the asset
+// arrives already flattened into the shape of its own shadow.
+const SHADOW_CAST_VERT = /* glsl */ `
+varying float vHeight;
+uniform float uBaseY;
+uniform vec2 uSlide;
+void main() {
+  vec4 world = modelMatrix * vec4(position, 1.0);
+  vHeight = max(world.y - uBaseY, 0.0);
+  world.xz += uSlide * vHeight;
+  world.y = uBaseY;
+  gl_Position = projectionMatrix * viewMatrix * world;
+}
+`;
+// The floor term is the difference between this working on every asset and
+// working on the ones that happen to be closed solids. Height alone says "the
+// nearest surface above this point is high up, so barely shade it" - but a prop
+// modelled as an open shell has NO underside, so the nearest surface above its
+// own footprint is the inside of its lid, and it casts almost nothing. Measured
+// on the espresso machine: alpha 0.08 under the middle of a solid-looking body.
+// Any occluder at all now shades to at least SHADOW_FLOOR; height decides how
+// much darker it gets from there.
+const SHADOW_FLOOR = 0.42;
+
+const SHADOW_CAST_FRAG = /* glsl */ `
+precision highp float;
+varying float vHeight;
+uniform float uFalloff;
+void main() {
+  float a = 1.0 - clamp(vHeight / uFalloff, 0.0, 1.0);
+  float shade = ${SHADOW_FLOOR.toFixed(2)} + ${(1 - SHADOW_FLOOR).toFixed(2)} * pow(a, 1.5);
+  gl_FragColor = vec4(vec3(1.0 - shade), 1.0);
+}
+`;
+
+// Fullscreen: the blur passes are screen-space and want NDC straight out.
+const BLUR_VERT = /* glsl */ `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+
+// The display plane is a real object in the world and needs the real transform.
+// Sharing BLUR_VERT with it - which is what the first cut did - draws the shadow
+// as a screen-space rectangle instead, and since it lands in front of the asset
+// at NDC depth 0 the failure does not look like a missing shadow at all.
+const PLANE_VERT = /* glsl */ `
+varying vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+`;
+
+const BLUR_FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D uMap;
+uniform vec2 uStep;
+void main() {
+  float sum = 0.0;
+  sum += texture2D(uMap, vUv - uStep * 4.0).r * 0.051;
+  sum += texture2D(uMap, vUv - uStep * 3.0).r * 0.0918;
+  sum += texture2D(uMap, vUv - uStep * 2.0).r * 0.12245;
+  sum += texture2D(uMap, vUv - uStep * 1.0).r * 0.1531;
+  sum += texture2D(uMap, vUv).r * 0.1633;
+  sum += texture2D(uMap, vUv + uStep * 1.0).r * 0.1531;
+  sum += texture2D(uMap, vUv + uStep * 2.0).r * 0.12245;
+  sum += texture2D(uMap, vUv + uStep * 3.0).r * 0.0918;
+  sum += texture2D(uMap, vUv + uStep * 4.0).r * 0.051;
+  gl_FragColor = vec4(vec3(sum), 1.0);
+}
+`;
+
+const SHADOW_SHOW_FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D uMap;
+uniform float uStrength;
+void main() {
+  float shade = 1.0 - texture2D(uMap, vUv).r;
+  // Fade the plane out before its own border, so the quad's edge can never be
+  // what the eye finds. Radial, not per-axis: a square fade leaves four faint
+  // corners that read as a sheet of paper under the asset.
+  float edge = 1.0 - smoothstep(0.80, 1.0, length(vUv - 0.5) * 2.0);
+  gl_FragColor = vec4(0.0, 0.0, 0.0, shade * uStrength * edge);
+}
+`;
+
+function createGroundShadow() {
+  const options = { depthBuffer: true, generateMipmaps: false };
+  const renderTarget = new THREE.WebGLRenderTarget(SHADOW_RES, SHADOW_RES, options);
+  const blurTarget = new THREE.WebGLRenderTarget(SHADOW_RES, SHADOW_RES, options);
+
+  // Looks DOWN, one metre above the ground plane. Down rather than up because
+  // the display plane's own UVs run that way: an up-looking camera mirrors the
+  // texture in Z, which a symmetric blob hides completely and an offset shadow
+  // shows immediately by landing on the wrong side of the asset.
+  const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.5, 1.5);
+  camera.rotation.x = -Math.PI / 2;
+
+  const castMaterial = new THREE.ShaderMaterial({
+    vertexShader: SHADOW_CAST_VERT,
+    fragmentShader: SHADOW_CAST_FRAG,
+    uniforms: { uBaseY: { value: 0 }, uFalloff: { value: 1 }, uSlide: { value: new THREE.Vector2() } },
+    side: THREE.DoubleSide,
+    // Everything lands on one plane, so there is no depth order to resolve -
+    // what is wanted is the DARKEST contribution over each point, which is a min
+    // blend. Ordinary alpha blending would instead stack every overlapping part
+    // and turn a lattice into a solid.
+    depthTest: false,
+    depthWrite: false,
+    blending: THREE.CustomBlending,
+    blendEquation: THREE.MinEquation,
+    blendSrc: THREE.OneFactor,
+    blendDst: THREE.OneFactor,
+  });
+
+  const blurScene = new THREE.Scene();
+  const blurCamera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+  const blurMaterial = new THREE.ShaderMaterial({
+    vertexShader: BLUR_VERT,
+    fragmentShader: BLUR_FRAG,
+    uniforms: { uMap: { value: null }, uStep: { value: new THREE.Vector2() } },
+    depthTest: false,
+    depthWrite: false,
+  });
+  const blurQuad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), blurMaterial);
+  blurQuad.frustumCulled = false;
+  blurScene.add(blurQuad);
+
+  const showMaterial = new THREE.ShaderMaterial({
+    vertexShader: PLANE_VERT,
+    fragmentShader: SHADOW_SHOW_FRAG,
+    uniforms: { uMap: { value: blurTarget.texture }, uStrength: { value: SHADOW_STRENGTH } },
+    transparent: true,
+    depthWrite: false,
+  });
+  const plane = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), showMaterial);
+  plane.rotation.x = -Math.PI / 2;
+  plane.renderOrder = -1;
+
+  return { renderTarget, blurTarget, camera, castMaterial, blurScene, blurCamera, blurMaterial, blurQuad, plane };
+}
+
+/**
+ * @param {{ container: HTMLElement, deterministic?: boolean, groundShadow?: boolean }} opts
+ *
+ * groundShadow is the one presentation switch an asset owns, and it exists
+ * because there is no geometric way to earn it: every asset's lowest point is
+ * its own bounding box floor, so a chandelier "stands on" the ground exactly as
+ * much as a table does. Left on, a hanging or wall-mounted asset gets a smear of
+ * shadow floating in mid-air under it, which reads as dirt on the lens.
+ */
+export function createStage({ container, deterministic = false, groundShadow = true }) {
+  const renderer = new THREE.WebGLRenderer({
+    antialias: true,
+    // The gate runner reads pixels back after the frame; three's default
+    // discards the buffer on present.
+    preserveDrawingBuffer: deterministic,
+  });
+  renderer.setPixelRatio(deterministic ? 1 : Math.min(globalThis.devicePixelRatio || 1, MAX_DPR));
+  renderer.outputColorSpace = THREE.SRGBColorSpace;
+  renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  // Down from 1.0. The environment is a whole extra light source on top of what
+  // the old preset already had, and left at 1.0 the first pass blew the espresso
+  // machine's brushed steel to near-white - the roughness map was still there,
+  // it was just above the point where the highlight rolls off.
+  renderer.toneMappingExposure = 0.88;
+  // Shadows are on. The old preset had none because there was no floor for one
+  // to fall on, but that argument only ever covered the CAST shadow: with a real
+  // environment doing the ambient, self-shadowing is what tells an overhang from
+  // a recess, and the ground shadow below has no floor in it.
+  renderer.shadowMap.enabled = true;
+  // PCF, not PCFSoft: three deprecated PCFSoftShadowMap and now warns on it,
+  // which G7 counts as a failure. No loss here - the soft half of the look is
+  // the ground shadow below, and what the map is for is self-shadowing, where
+  // a crisp terminator is the point.
+  renderer.shadowMap.type = THREE.PCFShadowMap;
+  container.appendChild(renderer.domElement);
+
+  const scene = new THREE.Scene();
+  scene.background = null;
+  scene.environment = buildEnvironment(renderer);
+  // Raised 0.78 -> 0.94 for the 2026-08-13 brightness pass. The environment is
+  // the knob to reach for here rather than toneMappingExposure: exposure scales
+  // the specular highlight too, and 1.0 is the value already measured to blow
+  // the espresso machine's brushed steel (see below). Environment intensity
+  // lifts the diffuse and the ambient occlusion-facing sides - the parts that
+  // actually read as "dark" - and leaves the highlight roll-off where it is.
+  scene.environmentIntensity = 0.94;
+
+  const backdrop = createBackdrop();
+  const ground = groundShadow ? createGroundShadow() : null;
+
+  const camera = new THREE.PerspectiveCamera(38, 1, 0.02, 200);
+
+  // The environment is now the PRIMARY light and the analytic lights are down
+  // hard from what they were (key 2.2 → 1.25, fill 0.85 → 0.2). The old preset
+  // had to carry the whole image on three lamps; this only needs a key sharp
+  // enough to cast and to put one specular edge on a curve.
+  //
+  // The hemisphere light is gone rather than reduced. It was one flat constant
+  // standing in for a room, and the environment has a room in it - a top panel,
+  // a floor bounce and a cool wall - so keeping both would just be adding the
+  // approximation back on top of the thing that replaced it.
+  // 1.65 -> 1.85 with the 2026-08-13 brightness pass: a small bump so the key
+  // keeps its lead over the raised environment. Lifting the environment alone
+  // flattens the form, because the lit side and the shaded side rise together.
+  const key = new THREE.DirectionalLight(0xfff3e2, 1.85);
+  key.castShadow = true;
+  key.shadow.mapSize.set(2048, 2048);
+  scene.add(key);
+  scene.add(key.target);
+
+  const fill = new THREE.DirectionalLight(0xe4eaf2, 0.2);
+  scene.add(fill);
+
+  // Everything the VIEWER draws that is not the asset. Hidden while gate G2
+  // counts draw calls, so the stage never spends the asset's budget.
+  const chrome = new THREE.Group();
+  chrome.name = "viewer-chrome";
+  if (ground) chrome.add(ground.plane);
+  scene.add(chrome);
+
+  const assetRoot = new THREE.Group();
+  assetRoot.name = "asset-root";
+  scene.add(assetRoot);
+
+  const orbit = createOrbit(camera, renderer.domElement, () => {
+    dirty = true;
+  });
+
+  let turntable = !deterministic;
+  let dirty = true;
+  let running = false;
+  let last = 0;
+
+  function resize() {
+    const w = container.clientWidth || 1;
+    const h = container.clientHeight || 1;
+    renderer.setSize(w, h, false);
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    backdrop.material.uniforms.uAspect.value = w / h;
+    dirty = true;
+  }
+  const resizeObserver = new ResizeObserver(resize);
+  resizeObserver.observe(container);
+  resize();
+
+  function placeLights(box) {
+    const size = box.getSize(new THREE.Vector3());
+    const centre = box.getCenter(new THREE.Vector3());
+    const r = Math.max(size.length() * 0.6, 0.5);
+    const az = THREE.MathUtils.degToRad(KEY_AZIMUTH_DEG);
+    const el = THREE.MathUtils.degToRad(KEY_ELEVATION_DEG);
+    key.position.set(
+      centre.x + Math.cos(el) * Math.cos(az) * r * 4,
+      centre.y + Math.sin(el) * r * 4,
+      centre.z + Math.cos(el) * Math.sin(az) * r * 4,
+    );
+    key.target.position.copy(centre);
+    key.target.updateMatrixWorld();
+    fill.position.set(centre.x - r * 3, centre.y + r * 1.6, centre.z - r * 3.4);
+
+    // Fit the shadow camera to the asset instead of leaving it at three's 5-unit
+    // default: a 0.36 m traffic cone inside a 10 m frustum spends its whole 2048
+    // map on empty space and comes out as a staircase.
+    const extent = Math.max(size.length() * 0.62, 0.05);
+    const cam = key.shadow.camera;
+    cam.left = -extent;
+    cam.right = extent;
+    cam.top = extent;
+    cam.bottom = -extent;
+    cam.near = Math.max(r * 4 - extent * 2, 0.01);
+    cam.far = r * 8 + extent * 2;
+    cam.updateProjectionMatrix();
+    // Both biases scale with the asset: a constant that stops acne on a 3.6 m
+    // lantern peels the shadow clean off a 0.36 m cone.
+    key.shadow.bias = -0.00035 * Math.max(extent, 0.2);
+    key.shadow.normalBias = extent * 0.012;
+  }
+
+  /** Re-render the ground shadow. Cheap, and only on fit/explode - the
+   *  turntable moves the CAMERA, so the shadow itself never changes. */
+  function bakeGroundShadow(box) {
+    if (!ground) return;
+    const size = box.getSize(new THREE.Vector3());
+    const centre = box.getCenter(new THREE.Vector3());
+    const baseY = box.min.y;
+    const falloff = Math.max(Math.min(size.y, Math.max(size.x, size.z)) * 0.9, 0.05);
+
+    // Where the top of the asset's shadow lands, and therefore how much ground
+    // the bake has to cover.
+    const el = THREE.MathUtils.degToRad(SHADOW_ELEVATION_DEG);
+    const az = THREE.MathUtils.degToRad(KEY_AZIMUTH_DEG);
+    const cot = Math.cos(el) / Math.sin(el);
+    const slideX = -Math.cos(az) * cot;
+    const slideZ = -Math.sin(az) * cot;
+    const reachX = slideX * size.y;
+    const reachZ = slideZ * size.y;
+
+    const pad = Math.max(size.x, size.z) * SHADOW_PAD;
+    const minX = Math.min(box.min.x, box.min.x + reachX) - pad;
+    const maxX = Math.max(box.max.x, box.max.x + reachX) + pad;
+    const minZ = Math.min(box.min.z, box.min.z + reachZ) - pad;
+    const maxZ = Math.max(box.max.z, box.max.z + reachZ) + pad;
+    // One square extent, so the texture's texels stay square and the two blur
+    // radii mean the same distance along both axes.
+    const half = Math.max(maxX - minX, maxZ - minZ) / 2 || 0.5;
+    const shadowCentre = new THREE.Vector3((minX + maxX) / 2, baseY, (minZ + maxZ) / 2);
+
+    ground.camera.left = -half;
+    ground.camera.right = half;
+    ground.camera.top = half;
+    ground.camera.bottom = -half;
+    ground.camera.position.set(shadowCentre.x, baseY + 1, shadowCentre.z);
+    ground.camera.updateProjectionMatrix();
+    ground.camera.updateMatrixWorld();
+
+    ground.castMaterial.uniforms.uBaseY.value = baseY;
+    ground.castMaterial.uniforms.uFalloff.value = falloff;
+    ground.castMaterial.uniforms.uSlide.value.set(slideX, slideZ);
+
+    const previousTarget = renderer.getRenderTarget();
+    const chromeWasVisible = chrome.visible;
+    const shadowsWereOn = renderer.shadowMap.enabled;
+    chrome.visible = false;
+    renderer.shadowMap.enabled = false;
+    scene.overrideMaterial = ground.castMaterial;
+    const clear = new THREE.Color(0xffffff);
+    const previousClear = renderer.getClearColor(new THREE.Color());
+    const previousAlpha = renderer.getClearAlpha();
+    renderer.setClearColor(clear, 1);
+    renderer.setRenderTarget(ground.renderTarget);
+    renderer.clear();
+    renderer.render(scene, ground.camera);
+    scene.overrideMaterial = null;
+
+    // Separable blur, ping-ponging between the two targets. Each radius is one
+    // horizontal pass and one vertical, and every pair leaves the result back in
+    // renderTarget - so however many radii the list holds, the display plane
+    // always samples the same texture.
+    for (const texels of SHADOW_BLUR_TEXELS) {
+      const step = texels / 4 / SHADOW_RES; // the kernel reaches +-4 steps
+      ground.blurMaterial.uniforms.uMap.value = ground.renderTarget.texture;
+      ground.blurMaterial.uniforms.uStep.value.set(step, 0);
+      renderer.setRenderTarget(ground.blurTarget);
+      renderer.render(ground.blurScene, ground.blurCamera);
+
+      ground.blurMaterial.uniforms.uMap.value = ground.blurTarget.texture;
+      ground.blurMaterial.uniforms.uStep.value.set(0, step);
+      renderer.setRenderTarget(ground.renderTarget);
+      renderer.render(ground.blurScene, ground.blurCamera);
+    }
+    ground.blurMaterial.uniforms.uMap.value = null;
+    ground.plane.material.uniforms.uMap.value = ground.renderTarget.texture;
+
+    renderer.setRenderTarget(previousTarget);
+    renderer.setClearColor(previousClear, previousAlpha);
+    renderer.shadowMap.enabled = shadowsWereOn;
+    chrome.visible = chromeWasVisible;
+
+    ground.plane.scale.set(half * 2, half * 2, 1);
+    ground.plane.position.set(shadowCentre.x, baseY + Math.max(size.y, 0.1) * 0.0015, shadowCentre.z);
+    ground.plane.updateMatrixWorld();
+  }
+
+  /** One frame: the backdrop first, then the scene over it. */
+  function draw() {
+    // autoClear is restored immediately: the gate passes render their own scenes
+    // into their own targets through this same renderer and rely on it.
+    renderer.autoClear = true;
+    backdrop.material.uniforms.uAspect.value = camera.aspect;
+    renderer.render(backdrop.scene, backdrop.camera);
+    renderer.autoClear = false;
+    renderer.render(scene, camera);
+    renderer.autoClear = true;
+  }
+
+  return {
+    renderer,
+    scene,
+    camera,
+    assetRoot,
+    chrome,
+    orbit,
+
+    /** Frame the camera, place the lights, bake the ground shadow. */
+    fit(box, mul = 1) {
+      // Shadows are the viewer's business, not the asset's - the modules already
+      // expose castShadow/receiveShadow for a game, and this turns them on for
+      // the presentation without the module having to know.
+      assetRoot.traverse((obj) => {
+        if (obj.isMesh) {
+          obj.castShadow = true;
+          obj.receiveShadow = true;
+        }
+      });
+      placeLights(box);
+      bakeGroundShadow(box);
+      orbit.frame(box, mul);
+      dirty = true;
+    },
+
+    /** Re-bake after the parts moved (explode), where the shadow really changed. */
+    refreshShadow(box) {
+      bakeGroundShadow(box);
+      dirty = true;
+    },
+
+    setTurntable(v) {
+      turntable = v;
+      dirty = true;
+      return turntable;
+    },
+    toggleTurntable() {
+      return this.setTurntable(!turntable);
+    },
+    get turntable() {
+      return turntable;
+    },
+    invalidate() {
+      dirty = true;
+    },
+    renderOnce() {
+      draw();
+      dirty = false;
+    },
+    start(onFrame) {
+      if (running) return;
+      running = true;
+      last = 0;
+      const tick = (t) => {
+        if (!running) return;
+        const dt = last ? Math.min((t - last) / 1000, 0.1) : 0;
+        last = t;
+        if (turntable && !orbit.dragging) {
+          orbit.spherical.theta += (Math.PI * 2 * dt) / TURNTABLE_PERIOD_S;
+          orbit.apply();
+        }
+        onFrame?.(dt);
+        // Render on demand: a still view costs nothing, which matters on a
+        // phone looking at a prop that is not moving.
+        if (dirty) {
+          draw();
+          dirty = false;
+        }
+        requestAnimationFrame(tick);
+      };
+      requestAnimationFrame(tick);
+    },
+    stop() {
+      running = false;
+    },
+    dispose() {
+      running = false;
+      resizeObserver.disconnect();
+      scene.environment?.dispose();
+      backdrop.mesh.geometry.dispose();
+      backdrop.material.dispose();
+      if (ground) {
+        ground.renderTarget.dispose();
+        ground.blurTarget.dispose();
+        ground.castMaterial.dispose();
+        ground.blurMaterial.dispose();
+        ground.blurQuad.geometry.dispose();
+        ground.plane.geometry.dispose();
+        ground.plane.material.dispose();
+      }
+      renderer.dispose();
+    },
+  };
+}
+
+/**
+ * Camera orbit, hand-rolled so the viewer needs no three/examples addon -
+ * the same rule the asset modules live under, applied to their host.
+ */
+function createOrbit(camera, dom, onChange) {
+  const target = new THREE.Vector3();
+  const spherical = new THREE.Spherical(4, Math.PI * 0.38, Math.PI * 0.25);
+  const home = { radius: 4, phi: Math.PI * 0.38, theta: Math.PI * 0.25 };
+  let dragging = false;
+  let lastX = 0;
+  let lastY = 0;
+  let pointerId = null;
+
+  function apply() {
+    spherical.phi = THREE.MathUtils.clamp(spherical.phi, 0.08, Math.PI * 0.495);
+    spherical.radius = THREE.MathUtils.clamp(spherical.radius, home.radius * 0.25, home.radius * 6);
+    camera.position.setFromSpherical(spherical).add(target);
+    camera.lookAt(target);
+    onChange?.();
+  }
+
+  dom.addEventListener("pointerdown", (e) => {
+    if (pointerId !== null) return;
+    pointerId = e.pointerId;
+    dragging = true;
+    lastX = e.clientX;
+    lastY = e.clientY;
+    dom.setPointerCapture(e.pointerId);
+  });
+  dom.addEventListener("pointermove", (e) => {
+    if (!dragging || e.pointerId !== pointerId) return;
+    // Drag right turns the model to the right: one pan convention, everywhere.
+    spherical.theta -= (e.clientX - lastX) * 0.006;
+    spherical.phi -= (e.clientY - lastY) * 0.006;
+    lastX = e.clientX;
+    lastY = e.clientY;
+    apply();
+  });
+  const release = (e) => {
+    if (e.pointerId !== pointerId) return;
+    dragging = false;
+    pointerId = null;
+  };
+  dom.addEventListener("pointerup", release);
+  dom.addEventListener("pointercancel", release);
+  dom.addEventListener(
+    "wheel",
+    (e) => {
+      e.preventDefault();
+      spherical.radius *= Math.exp(e.deltaY * 0.0012);
+      apply();
+    },
+    { passive: false },
+  );
+
+  return {
+    get dragging() {
+      return dragging;
+    },
+    spherical,
+    target,
+    apply,
+    frame(box, distanceMul = 1) {
+      const centre = box.getCenter(new THREE.Vector3());
+      const size = box.getSize(new THREE.Vector3());
+      target.copy(centre);
+      // Aim slightly above the centroid, which seats the model a little below
+      // the middle of frame: a tall prop (the 3.6 m lantern) reads better with
+      // its mass low than dead-centred.
+      target.y = box.min.y + size.y * 0.55;
+
+      // Fit the bounding sphere against whichever field of view is narrower -
+      // on a phone in portrait that is the horizontal one, and framing off the
+      // vertical alone is what crops an asset off the sides.
+      const sphere = Math.max(size.length() * 0.5 + Math.abs(target.y - centre.y), 0.05);
+      const vFov = THREE.MathUtils.degToRad(camera.fov);
+      const hFov = 2 * Math.atan(Math.tan(vFov / 2) * Math.max(camera.aspect, 0.2));
+      home.radius = (sphere / Math.sin(Math.min(vFov, hFov) / 2)) * 1.22 * distanceMul;
+
+      spherical.radius = home.radius;
+      spherical.phi = home.phi;
+      spherical.theta = home.theta;
+      apply();
+    },
+    reset() {
+      spherical.radius = home.radius;
+      spherical.phi = home.phi;
+      spherical.theta = home.theta;
+      apply();
+    },
+  };
+}