partforge 0.121.1 → 0.123.0

package/src/framework/viewer.js

@@ -4,6 +4,13 @@ import { toCreasedNormals } from "three/addons/utils/BufferGeometryUtils.js";
 import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
+import { UltraHDRLoader } from "three/addons/loaders/UltraHDRLoader.js";
+import { buildCadMaterial, buildPhysicalMaterial } from "./materials/physical.js";
+import { ensureBoxUVs } from "./materials/uv.js";
+import { loadEnvironmentRig } from "./materials/environment.js";
+import { assetUrl } from "./materials/assets.js";
+import { resolveEnvironmentId } from "./materials/resolve.js";
+import { neutralToneMapToSrgb8 } from "./materials/tonemap-readback.js";
 import { createCutaway } from "./cutaway.js";
 import { CUTAWAY_OVERLAY_RENDER_ORDER } from "./cutaway-render.js";
 import { flashWorldRadius, projectToScreen, anchorMoved } from "./pick-flash.js";
@@ -41,6 +48,31 @@ export function srgbEncodeInPlace(data) {
   return data;
 }
 
+// Readback (a realistic capture's target) → linear floats: half-float bits,
+// or linear bytes from the 8-bit fallback target.
+function readbackToLinear(buf) {
+  const out = new Float32Array(buf.length);
+  if (buf instanceof Uint16Array) for (let i = 0; i < buf.length; i++) out[i] = THREE.DataUtils.fromHalfFloat(buf[i]);
+  else for (let i = 0; i < buf.length; i++) out[i] = buf[i] / 255;
+  return out;
+}
+
+// Can a realistic capture render HDR into a half-float target and read it
+// back? Both halves fail SILENTLY otherwise: three's readRenderTargetPixels
+// logs and returns when the type is not readable, and gl.readPixels with
+// RGBA/HALF_FLOAT raises an unseen INVALID_OPERATION unless that is the
+// implementation's read type — either way the buffer stays zero and the
+// capture is a valid, all-black JPEG. `readable` is three's
+// capabilities.textureTypeReadable(HalfFloatType) (needs a colour-buffer
+// float extension, which is also what makes the target renderable);
+// `readType` is the implementation read type for a bound, complete
+// half-float framebuffer, or null when no GL context was there to ask (a
+// failed probe passes something that is not `halfFloat`).
+export function halfFloatCaptureSupported({ readable, readType = null, halfFloat = null }) {
+  if (readable !== true) return false;
+  return readType === null || readType === halfFloat;
+}
+
 // Render a set of canonical views without disturbing the live camera/canvas.
 // `renderer.renderOffscreen(pose)` does the GL work (temp camera → offscreen
 // target → readback → JPEG data URL); injected so this is unit-testable without
@@ -219,16 +251,11 @@ export function createViewer(container, part) {
   const partsGroup = new THREE.Group();
   pivot.add(partsGroup);
 
-  // Per-sub-part material: parts share the default material unless they declare
-  // `display: { color?, opacity? }` (e.g. a reference/ghost part shown in a
-  // distinct colour and/or semi-transparent so it reads as "not a printed part").
+  // Per-sub-part CAD material: the shared default unless the sub-part declares
+  // appearance in `display` (colour, opacity, or a library material flattened
+  // for the CAD view — materials/resolve.js cadAppearance).
   function materialFor(name) {
-    const disp = part.parts[name].display;
-    if (!disp || (disp.color == null && disp.opacity == null)) return material;
-    const m = material.clone();
-    if (disp.color != null) m.color = new THREE.Color(disp.color);
-    if (disp.opacity != null && disp.opacity < 1) { m.transparent = true; m.opacity = disp.opacity; m.depthWrite = false; }
-    return m;
+    return buildCadMaterial(part.parts[name].display, material);
   }
 
   const subMesh = Object.fromEntries(
@@ -259,10 +286,20 @@ export function createViewer(container, part) {
   // half of "fade a part in, then animate it into place".
   const animOpacity = new Map();     // name -> value in [0, 1)
   const baseMats = Object.fromEntries(names.map((n) => [n, subMesh[n].material]));
+  // baseMats is the CURRENT source material per sub-part, which realistic mode
+  // re-points at a physical material; cadMats keeps the CAD ones for the way
+  // back, and is what dispose() frees.
+  const cadMats = { ...baseMats };
   const fadeMats = new Map();        // name -> lazily cloned MeshStandardMaterial
   const fadeLineMats = new Map();    // name -> lazily cloned LineMaterial
   const fadeUnregisters = new Map(); // fade material -> its cutaway unregister fn
   let lastShown = [];                // names last passed to showAssembly
+  // The render mode's LOOK, read by applySubOpacity (feature lines are CAD-only)
+  // and the depth range (the realistic ground disc). Declared here, ahead of
+  // everything that reads it; the mode itself lives in the realistic-mode block.
+  let renderMode = "cad";
+  let realisticRig = null;
+  let shadowMovedAt = null;          // performance.now() of a pose change the contact shadow has not caught up with
 
   const effectiveVisible = () => lastShown.filter((n) => (animOpacity.get(n) ?? 1) > 0);
 
@@ -324,7 +361,7 @@ export function createViewer(container, part) {
       // every-regen showAssembly path stays a no-op for un-faded sub-parts.
       if (hadFade) cutaway.resyncSubpart(name);
       mesh.visible = shown;
-      lines.visible = shown;
+      lines.visible = shown && renderMode === "cad";
       return;
     }
     if (v <= 0) {
@@ -340,7 +377,7 @@ export function createViewer(container, part) {
     flm.opacity = v;
     lines.material = flm;
     mesh.visible = shown;
-    lines.visible = shown;
+    lines.visible = shown && renderMode === "cad";
   }
 
   function setSubPartOpacity(name, value) {
@@ -350,7 +387,10 @@ export function createViewer(container, part) {
     else animOpacity.set(name, Math.max(0, value));
     applySubOpacity(name);
     const isZero = (animOpacity.get(name) ?? 1) <= 0;
-    if (wasZero !== isZero) cutaway.setVisible(effectiveVisible());
+    if (wasZero !== isZero) {
+      cutaway.setVisible(effectiveVisible());
+      if (realisticRig) shadowMovedAt = performance.now(); // a caster came or went
+    }
   }
 
   function clearSubPartOpacities() {
@@ -396,6 +436,7 @@ export function createViewer(container, part) {
   const _depthCenter = new THREE.Vector3();
   const _depthSize = new THREE.Vector3();
   const _gridCorner = new THREE.Vector3();
+  const _groundBounds = new THREE.Box3();
   function sceneDepthBounds({ withGrid } = {}) {
     // getVisibleWorldBounds returns a SHARED Box3 that the cutaway also reads,
     // so copy before touching it.
@@ -405,6 +446,10 @@ export function createViewer(container, part) {
       _depthBounds.expandByPoint(_gridCorner.set(-half, floorY, -half));
       _depthBounds.expandByPoint(_gridCorner.set(half, floorY, half));
     }
+    // The realistic ground disc is several part radii across, so it is the
+    // bigger half of the answer the way the grid is in CAD: without it the far
+    // plane cuts the disc's back edge off.
+    if (realisticRig) _depthBounds.union(_groundBounds.setFromObject(realisticRig.ground));
     if (_depthBounds.isEmpty()) return null;
     return {
       center: _depthBounds.getCenter(_depthCenter).toArray(),
@@ -447,6 +492,371 @@ export function createViewer(container, part) {
     cutaway.setSubpart(name, subMesh[name], subLines[name]);
   }
 
+  // --- realistic mode ---------------------------------------------------------
+  // "cad" is the drafting view (flat lights, grid, feature lines); "realistic"
+  // swaps every sub-part onto a physical material lit by an environment rig,
+  // with a ground and contact shadow brought to the part — which never moves.
+  //
+  // Materials change through ONE seam, rebaseSubMaterial: baseMats is what the
+  // fade clones and the cutaway's clipped clones are derived from, so the swap
+  // re-points that and lets both re-derive, rather than writing mesh.material
+  // (which the cutaway and the fades own) directly.
+  //
+  // Everything a load can fail at (the rig, the physical materials, the shader
+  // compile) happens BEFORE the live scene is touched, and the swap itself is
+  // one synchronous block that rolls back to CAD if it throws — so a failure at
+  // any point leaves a whole CAD (or the previous realistic) view, never a
+  // half-swapped one. Rigs are cached for the viewer's life and freed only in
+  // dispose(): scene.environment/background may still point into one.
+  let environmentId = resolveEnvironmentId(part.meta?.environment).id;
+  let modeToken = 0;                 // bumped by every request; a stale completion does nothing
+  let realisticPending = false;      // a realistic request is in flight (setEnvironment joins it)
+  let environmentChosen = false;     // set by setEnvironment; false while seeded from meta/default
+  const physicalMats = new Map();    // name -> MeshPhysicalMaterial (environment-independent, cached)
+  const rigCache = new Map();        // environment id -> Promise<Rig>
+  const loadedRigs = new Map();      // environment id -> Rig, once its load has landed (synchronous captures)
+  const textureCache = new Map();    // asset file name -> Texture
+  const textureLoader = new THREE.TextureLoader();
+  let pmrem = null;
+  let printFrames = {};
+  const modeListeners = new Set();
+  const envListeners = new Set();
+  const SHADOW_LOWRES_MS = 100;      // at most one low-res shadow per this, while a part moves
+  const SHADOW_SETTLE_MS = 200;      // …and one full-res render this long after the last move
+  let shadowLowResAt = -Infinity;
+  const isCoarsePointer = () => {
+    try { return typeof matchMedia === "function" && matchMedia("(pointer: coarse)").matches; } catch { return false; }
+  };
+
+  // Anisotropic filtering: the ground disc and the wood grain are seen at grazing
+  // angles, where plain trilinear mip selection blurs them into smeared blocks.
+  const loadTexture = (file) => {
+    let t = textureCache.get(file);
+    if (!t) {
+      t = textureLoader.load(assetUrl(file));
+      t.anisotropy = Math.min(8, renderer.capabilities?.getMaxAnisotropy?.() ?? 1);
+      textureCache.set(file, t);
+    }
+    return t;
+  };
+  const loadHdr = (url) => new UltraHDRLoader().setDataType(THREE.HalfFloatType).loadAsync(url);
+  function rigFor(id) {
+    if (!rigCache.has(id)) {
+      pmrem ??= new THREE.PMREMGenerator(renderer);
+      const p = loadEnvironmentRig(renderer, id, { loadHdr, loadTexture, pmrem });
+      // A failure is retryable, not memoized — but only drop THIS attempt.
+      p.then((rig) => { if (rigCache.get(id) === p) loadedRigs.set(id, rig); },
+        () => { if (rigCache.get(id) === p) rigCache.delete(id); });
+      rigCache.set(id, p);
+    }
+    return rigCache.get(id);
+  }
+
+  // three's Material.copy carries neither onBeforeCompile nor
+  // customProgramCacheKey, and it JSON-copies userData. For a patterned
+  // physical material (patterns.js) that means every clone the cutaway or a
+  // fade makes silently drops the pattern — and serializes the pattern texture's
+  // image through a canvas to do it. So a patterned material's clone shares the
+  // hooks and the uniforms object (one print frame drives them all) instead.
+  function cloneKeepsPattern(m) {
+    if (!Object.hasOwn(m, "onBeforeCompile")) return m;
+    m.clone = function clone() {
+      const uniforms = this.userData.patternUniforms;
+      delete this.userData.patternUniforms;
+      let c;
+      try { c = THREE.MeshPhysicalMaterial.prototype.clone.call(this); } finally {
+        if (uniforms) this.userData.patternUniforms = uniforms;
+      }
+      if (uniforms) c.userData.patternUniforms = uniforms;
+      c.onBeforeCompile = this.onBeforeCompile;
+      c.customProgramCacheKey = this.customProgramCacheKey;
+      c.clone = clone;
+      return c;
+    };
+    return m;
+  }
+  function physicalFor(name) {
+    let m = physicalMats.get(name);
+    if (!m) {
+      m = cloneKeepsPattern(buildPhysicalMaterial(part.parts[name].display, { printFrame: printFrames[name], loadTexture }));
+      physicalMats.set(name, m);
+    }
+    return m;
+  }
+
+  function publishMode(extra = {}) {
+    const evt = { mode: renderMode, busy: false, error: null, ...extra };
+    for (const cb of [...modeListeners]) {
+      try { cb(evt); } catch (e) { console.warn("partforge: render-mode listener failed", e); }
+    }
+  }
+
+  // Point one sub-part at a new source material. The fade clones were cloned
+  // from the old one, so they go (applySubOpacity re-clones on demand); the
+  // cutaway re-derives its clipped clone and reassigns mesh.material for its
+  // current state; then any live fade is re-asserted on top.
+  function rebaseSubMaterial(name, mat) {
+    for (const map of [fadeMats, fadeLineMats]) {
+      const clone = map.get(name);
+      if (!clone) continue;
+      fadeUnregisters.get(clone)?.();
+      fadeUnregisters.delete(clone);
+      clone.dispose();
+      map.delete(name);
+    }
+    baseMats[name] = mat;
+    cutaway.refreshSubpartMaterial(name, mat);
+    applySubOpacity(name);
+  }
+  function setSubMaterials(matFor) {
+    for (const n of names) {
+      const m = matFor(n);
+      if (baseMats[n] !== m) rebaseSubMaterial(n, m);
+      else applySubOpacity(n); // same material, but the lines follow the mode
+    }
+  }
+
+  // Ghosts (a static display opacity below 1) cast no shadow.
+  const castersNow = () => names
+    .filter((n) => subMesh[n].visible && (part.parts[n].display?.opacity ?? 1) >= 1)
+    .map((n) => subMesh[n]);
+  // `force` renders even while parked: a capture is offscreen work a parked
+  // viewer still does, and it must not bake a stale (or absent) shadow.
+  function renderShadow(opts, { force = false } = {}) {
+    if (!realisticRig || (!active && !force)) return;
+    try {
+      if (opts) realisticRig.shadow.render(scene, castersNow(), opts);
+      else realisticRig.shadow.render(scene, castersNow());
+    } catch (e) {
+      console.warn("partforge: contact shadow failed", e);
+    }
+  }
+  // The ground comes to the part: it sits at the bottom of what is visible and
+  // is sized from it. Only on showAssembly (and on entering the mode) — an
+  // animated pose change moves the shadow, never the floor.
+  function placeGround({ force = false } = {}) {
+    if (!realisticRig) return;
+    const b = getVisibleWorldBounds(); // shared Box3: read it out before anything else runs
+    if (b.isEmpty()) return;
+    const center = b.getCenter(new THREE.Vector3());
+    const size = b.getSize(new THREE.Vector3());
+    realisticRig.setGround({
+      y: b.min.y, centerX: center.x, centerZ: center.z, radius: size.length() / 2, footprintMm: Math.max(size.x, size.z),
+    });
+    shadowMovedAt = null; // this render is the full-resolution one
+    renderShadow(undefined, { force });
+  }
+  // Called once per rendered frame: low-res while a part is moving, one full
+  // render once it has settled, nothing while it is still.
+  function updateMovingShadow() {
+    if (!realisticRig || shadowMovedAt == null) return;
+    const t = performance.now();
+    if (t - shadowMovedAt >= SHADOW_SETTLE_MS) {
+      shadowMovedAt = null;
+      renderShadow();
+    } else if (t - shadowLowResAt >= SHADOW_LOWRES_MS) {
+      shadowLowResAt = t;
+      renderShadow({ lowRes: true });
+    }
+  }
+
+  const livePixelRatio = (mode) =>
+    Math.min(devicePixelRatio, mode === "realistic" && isCoarsePointer() ? 1.5 : 2);
+  function applyPixelRatio(mode) {
+    const want = livePixelRatio(mode);
+    if (renderer.getPixelRatio() === want) return;
+    renderer.setPixelRatio(want);
+    resize();
+  }
+
+  // The two synchronous halves of a mode change. `live: false` is for a
+  // capture that borrows a look for one synchronous render (it leaves the
+  // canvas's pixel ratio alone, and renders the shadow even while parked);
+  // nothing here publishes — setRenderMode does. `reground: false` puts a rig
+  // back exactly where it was (after a CAD capture borrowed the scene): the
+  // ground only moves on showAssembly, never because a capture happened.
+  function enterRealistic(rig, { live = true, reground = true } = {}) {
+    try {
+      renderMode = "realistic";
+      // A regen can land between the proxy compile and here, while the mode
+      // was still CAD, so setSubGeometry skipped the UVs. Idempotent.
+      for (const n of names) if (subCache[n] && physicalFor(n).userData.pfAnisotropic) ensureBoxUVs(subCache[n]);
+      setSubMaterials(physicalFor);
+      if (realisticRig && realisticRig !== rig) scene.remove(realisticRig.ground, realisticRig.shadow.group);
+      realisticRig = rig;
+      scene.environment = rig.envMap;
+      scene.background = rig.background;
+      scene.backgroundBlurriness = rig.backgroundBlurriness;
+      scene.backgroundIntensity = rig.backgroundIntensity ?? 1;
+      scene.backgroundRotation.set(0, rig.rotationY ?? 0, 0);
+      scene.environmentRotation.set(0, rig.rotationY ?? 0, 0);
+      scene.add(rig.ground, rig.shadow.group);
+      for (const l of Object.values(liveLights)) l.visible = false;
+      grid.visible = false;
+      renderer.toneMapping = THREE.NeutralToneMapping;
+      renderer.toneMappingExposure = rig.exposure;
+      if (reground) placeGround({ force: !live });
+      if (live) applyPixelRatio("realistic");
+    } catch (e) {
+      try { enterCad({ live }); } catch (rollback) { console.warn("partforge: rolling back to CAD failed", rollback); }
+      throw e;
+    }
+  }
+  // Every step is attempted even if an earlier one throws (the first error is
+  // rethrown at the end): this is the rollback path too, and a half-restored
+  // CAD view is exactly what it exists to prevent. Tone mapping goes first.
+  function enterCad({ live = true } = {}) {
+    let firstError = null;
+    const attempt = (fn) => { try { fn(); } catch (e) { firstError ??= e; } };
+    attempt(() => {
+      renderer.toneMapping = THREE.NoToneMapping;
+      renderer.toneMappingExposure = 1;
+    });
+    renderMode = "cad";
+    attempt(() => {
+      if (realisticRig) scene.remove(realisticRig.ground, realisticRig.shadow.group);
+    });
+    realisticRig = null;
+    shadowMovedAt = null;
+    attempt(() => {
+      scene.environment = null;
+      scene.background = new THREE.Color(THEME[currentTheme].bg);
+      scene.backgroundBlurriness = 0;
+      scene.backgroundIntensity = 1;
+      scene.backgroundRotation.set(0, 0, 0);
+      scene.environmentRotation.set(0, 0, 0);
+    });
+    attempt(() => { for (const l of Object.values(liveLights)) l.visible = true; });
+    attempt(() => { grid.visible = true; });
+    for (const n of names) attempt(() => { if (baseMats[n] !== cadMats[n]) rebaseSubMaterial(n, cadMats[n]); else applySubOpacity(n); });
+    if (live) attempt(() => applyPixelRatio("cad"));
+    if (firstError) throw firstError;
+  }
+
+  const isStale = (token) => disposed || token !== modeToken;
+
+  // Compile every built sub-part's physical program against the rig before the
+  // look is swapped in, so the swap does not stall on shader compilation.
+  // Three keys a program on tone mapping and output colour space, and both
+  // differ with a render target bound, so the canvas variant compiles under
+  // the realistic tone mapping and a capture's variant with a render
+  // target bound — each only for the synchronous compile() inside
+  // compileAsync, so the view on screen is untouched while it waits.
+  function compileRealistic(rig, { forCapture = false } = {}) {
+    const proxy = new THREE.Scene();
+    proxy.environment = rig.envMap;
+    for (const n of names) {
+      const m = physicalFor(n);
+      const geo = subCache[n];
+      if (!geo) continue; // not built yet: it compiles when it is first shown
+      if (m.userData.pfAnisotropic) ensureBoxUVs(geo);
+      proxy.add(new THREE.Mesh(geo, m));
+    }
+    const toneMappingBefore = renderer.toneMapping;
+    // Any bound target gives the capture's key (NoToneMapping, linear output);
+    // an 8-bit one is always renderable.
+    const probe = forCapture ? new THREE.WebGLRenderTarget(1, 1) : null;
+    if (probe) renderer.setRenderTarget(probe);
+    else renderer.toneMapping = THREE.NeutralToneMapping;
+    let compiling;
+    try { compiling = renderer.compileAsync?.(proxy, activeCamera); } finally {
+      renderer.toneMapping = toneMappingBefore;
+      if (probe) renderer.setRenderTarget(null);
+    }
+    return Promise.resolve(compiling).finally(() => probe?.dispose());
+  }
+
+  // Resolves to the mode actually in effect. A later setRenderMode or
+  // setEnvironment supersedes this one; a superseded completion changes
+  // nothing (its rig and materials are cached, so there is nothing to undo).
+  async function setRenderMode(next) {
+    if (disposed) return renderMode;
+    const want = next === "realistic" ? "realistic" : "cad";
+    const token = ++modeToken;
+    if (want === "cad") {
+      realisticPending = false;
+      if (renderMode !== "cad") {
+        try { enterCad(); } catch (e) { console.warn("partforge: leaving the realistic view failed", e); }
+      }
+      publishMode();
+      return renderMode;
+    }
+    const envId = environmentId;
+    if (renderMode === "realistic" && realisticRig?.id === envId) {
+      realisticPending = false;
+      publishMode();
+      return renderMode;
+    }
+    const wasRealistic = renderMode === "realistic";
+    realisticPending = true;
+    publishMode({ busy: true });
+    try {
+      const rig = await rigFor(envId);
+      if (isStale(token)) return renderMode;
+      await compileRealistic(rig);
+      if (isStale(token)) return renderMode;
+      enterRealistic(rig);
+      realisticPending = false;
+      publishMode();
+    } catch (e) {
+      if (isStale(token)) return renderMode;
+      realisticPending = false;
+      console.warn("partforge: the realistic view failed to load", e);
+      // Still realistic means the previous rig is still what's on screen: the
+      // environment the switch asked for never landed, so the id (and anyone
+      // showing it) goes back to the one actually lit.
+      if (renderMode === "realistic" && realisticRig && realisticRig.id !== environmentId) {
+        announceEnvironment(realisticRig.id);
+      }
+      publishMode({ error: wasRealistic && renderMode === "realistic" ? "couldn't load that environment" : "couldn't load realistic view" });
+    }
+    return renderMode;
+  }
+
+  function announceEnvironment(id) {
+    environmentId = id;
+    for (const cb of [...envListeners]) {
+      try { cb(id); } catch (e) { console.warn("partforge: environment listener failed", e); }
+    }
+  }
+
+  // The id is recorded (and announced) at once; in realistic mode — or on the
+  // way into it — the new rig then loads and replaces the current one. If that
+  // load fails while realistic, setRenderMode reverts the id to the rig still
+  // shown and announces that too; in CAD nothing loads, so the id just stands.
+  async function setEnvironment(id) {
+    const next = resolveEnvironmentId(id).id;
+    environmentChosen = true;
+    if (next !== environmentId) announceEnvironment(next);
+    if (renderMode === "realistic" || realisticPending) await setRenderMode("realistic");
+    return environmentId;
+  }
+
+  // Per-sub-part print frames (display → export) for the layer-line pattern.
+  function setPrintFrames(frames) {
+    printFrames = frames ?? {};
+    const identity = new THREE.Matrix4().toArray();
+    for (const [n, m] of physicalMats) m.userData.patternUniforms?.pfPrintFrame.value.fromArray(printFrames[n] ?? identity);
+  }
+
+  // Resolves once the current environment's rig is loaded (captures wait on it).
+  const whenRealisticReady = () => rigFor(environmentId).then(() => {});
+
+  function disposeRealistic() {
+    modeToken++;
+    modeListeners.clear();
+    envListeners.clear();
+    for (const p of rigCache.values()) p.then((r) => r.dispose(), () => {});
+    rigCache.clear();
+    loadedRigs.clear();
+    for (const m of physicalMats.values()) m.dispose();
+    physicalMats.clear();
+    for (const t of textureCache.values()) t.dispose();
+    textureCache.clear();
+    pmrem?.dispose();
+    pmrem = null;
+  }
+
   // --- animation hooks --------------------------------------------------------
   // Frame listeners get dt (seconds, clamped so a background-tab return doesn't
   // fast-forward playback) inside the render loop — so a parked viewer
@@ -730,6 +1140,8 @@ export function createViewer(container, part) {
     setSubPose(name, null); // fresh worker mesh is baked at current params — clear any fast-path pose
     const prev = subCache[name];
     const next = buildGeometry(payload);
+    // Brushed metal needs UVs for its tangent frame; CAD meshes carry none.
+    if (renderMode === "realistic" && physicalMats.get(name)?.userData.pfAnisotropic) ensureBoxUVs(next);
     subCache[name] = next;
     // Section helpers must stop referring to the old buffers before those
     // buffers are released.
@@ -749,6 +1161,9 @@ export function createViewer(container, part) {
       else obj.matrix.identity();
       obj.matrixWorldNeedsUpdate = true;
     }
+    // The contact shadow follows on the render loop's throttle (see
+    // updateMovingShadow); the ground itself stays put until showAssembly.
+    if (realisticRig) shadowMovedAt = performance.now();
   }
 
   // Cache queries for the app's regenerate loop (so it never reaches into subCache).
@@ -802,6 +1217,7 @@ export function createViewer(container, part) {
     }
     if (frame) frameTo(visibleNames);
     cutaway.setVisible(effectiveVisible());
+    placeGround(); // realistic only: the ground comes to the part, and the shadow re-renders
   }
 
   // Re-frame whatever is currently visible (the reframe button).
@@ -840,10 +1256,13 @@ export function createViewer(container, part) {
   // Swap the scene background, grid, and edge-line colors for the given theme.
   function setTheme(mode) {
     const t = THEME[mode] ?? THEME.dark;
-    scene.background = new THREE.Color(t.bg);
+    // Realistic mode's backdrop belongs to the environment and its grid is off;
+    // enterCad puts the theme's background back on the way out.
+    if (renderMode === "cad") scene.background = new THREE.Color(t.bg);
     scene.remove(grid);
     grid = new THREE.GridHelper(GRID_SIZE, GRID_DIVS, t.grid[0], t.grid[1]);
     grid.position.y = floorY; // keep the floor at the bbox bottom across theme swaps
+    grid.visible = renderMode === "cad";
     scene.add(grid);
     lineMaterial.color.set(t.line);
     for (const m of fadeLineMats.values()) m.color.set(t.line); // clones follow the theme
@@ -908,6 +1327,45 @@ export function createViewer(container, part) {
   // the mask silently no-ops and every cap floods its whole plane with hatch —
   // no error, live view unaffected, wrong only in the capture.
   const RT_OPTIONS = { samples: 4, stencilBuffer: true };
+  // Decided once per viewer, on the first realistic capture (see
+  // halfFloatCaptureSupported). Two 1×1 probes, because a capture needs two
+  // things of half-float: RENDERING into the exact target a capture uses (4×
+  // MSAA with a stencil — a GPU can support single-sampled half-float and
+  // still refuse a multisampled one, which would come back as a black capture),
+  // and READING BACK, which three does from the resolved single-sampled
+  // framebuffer, so the read format is asked of a plain half-float target.
+  let _hdrReadback = null;
+  function hdrCaptureReadback() {
+    if (_hdrReadback !== null) return _hdrReadback;
+    const readable = renderer.capabilities?.textureTypeReadable?.(THREE.HalfFloatType) === true;
+    let readType = null, halfFloat = null;
+    const gl = renderer.getContext?.();
+    if (readable && typeof gl?.getParameter === "function") {
+      halfFloat = gl.HALF_FLOAT;
+      const complete = () => gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+      const renderProbe = new THREE.WebGLRenderTarget(1, 1, { ...RT_OPTIONS, type: THREE.HalfFloatType });
+      const readProbe = new THREE.WebGLRenderTarget(1, 1, { type: THREE.HalfFloatType });
+      try {
+        renderer.setRenderTarget(renderProbe);
+        const renderable = complete();
+        renderer.setRenderTarget(readProbe);
+        readType = renderable && complete() && gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_FORMAT) === gl.RGBA
+          ? gl.getParameter(gl.IMPLEMENTATION_COLOR_READ_TYPE)
+          : -1;
+      } catch {
+        readType = -1;
+      } finally {
+        renderer.setRenderTarget(null);
+        renderProbe.dispose();
+        readProbe.dispose();
+      }
+    }
+    _hdrReadback = halfFloatCaptureSupported({ readable, readType, halfFloat });
+    if (!_hdrReadback) {
+      console.warn("partforge: this device can't read back HDR renders; realistic captures are tone-mapped from 8-bit (highlights clip)");
+    }
+    return _hdrReadback;
+  }
   //
   // `viewOffset` ({ fullWidth, fullHeight, x, y }) renders the width×height
   // output as that sub-window of a larger virtual frame — the recentred
@@ -918,10 +1376,18 @@ export function createViewer(container, part) {
                            { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9,
                              projection = "perspective", orthoHalfH = 1, viewOffset, sceneBounds } = {},
                            renderScene = scene) {
-    const cachedSize = width === _rtSize && height === _rtSize;
+    // A realistic LIVE scene renders HDR into a half-float target and is tone
+    // mapped here (three tone-maps only the canvas path). It is lit by its
+    // environment alone, so the CAD capture lights stay out of it. A throwaway
+    // scene (renderMeshPayloads' thumbnails) is CAD whatever the live mode.
+    // Without HDR readback it falls back to the 8-bit target and tone-maps the
+    // clipped linear bytes: highlights clip, but it is still the realistic look.
+    const realistic = renderScene === scene && renderMode === "realistic";
+    const hdr = realistic && hdrCaptureReadback();
+    const cachedSize = !hdr && width === _rtSize && height === _rtSize;
     const rt = cachedSize
       ? (_rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize, RT_OPTIONS))
-      : new THREE.WebGLRenderTarget(width, height, RT_OPTIONS);
+      : new THREE.WebGLRenderTarget(width, height, hdr ? { ...RT_OPTIONS, type: THREE.HalfFloatType } : RT_OPTIONS);
     _capLights = _capLights ?? createCaptureLights();
     // Canonical captures never pass `projection`, so agent-facing renders and
     // the CLI stay perspective no matter what the user is looking at. Built
@@ -936,18 +1402,22 @@ export function createViewer(container, part) {
     });
     if (viewOffset) cam.setViewOffset(viewOffset.fullWidth, viewOffset.fullHeight, viewOffset.x, viewOffset.y, width, height);
     const { position, up, target } = pose;
-    const buf = new Uint8Array(width * height * 4);
+    const buf = hdr ? new Uint16Array(width * height * 4) : new Uint8Array(width * height * 4);
     // Swap the world-fixed key/fill for the camera-relative pair, for this one render
     // only. A DirectionalLight aims at its `target`, whose matrixWorld only updates
     // while it is in the scene graph, so both go in and both come back out.
-    const poses = captureLightPoses({ position, up, target });
     const { key: capKey, fill: capFill } = _capLights;
-    capKey.position.set(poses.key[0], poses.key[1], poses.key[2]);
-    capFill.position.set(poses.fill[0], poses.fill[1], poses.fill[2]);
-    for (const light of [capKey, capFill]) light.target.position.set(target[0], target[1], target[2]);
-    liveLights.key.visible = false;
-    liveLights.fill.visible = false;
-    scene.add(capKey, capKey.target, capFill, capFill.target);
+    // Restored to what they WERE, not to true: realistic mode keeps them off.
+    const keyWas = liveLights.key.visible, fillWas = liveLights.fill.visible;
+    if (!realistic) {
+      const poses = captureLightPoses({ position, up, target });
+      capKey.position.set(poses.key[0], poses.key[1], poses.key[2]);
+      capFill.position.set(poses.fill[0], poses.fill[1], poses.fill[2]);
+      for (const light of [capKey, capFill]) light.target.position.set(target[0], target[1], target[2]);
+      liveLights.key.visible = false;
+      liveLights.fill.visible = false;
+      scene.add(capKey, capKey.target, capFill, capFill.target);
+    }
     // A pick marker is transient UI feedback about a click, never part of the
     // part, so it belongs in no capture. It used to be near enough true that a
     // capture would miss one — a dot faded after 1200ms — but a HELD dot lives
@@ -957,8 +1427,12 @@ export function createViewer(container, part) {
     // than via canonicalCaptureHidden: captureCurrent deliberately ignores that
     // set. Only dots that were actually shown are restored, so this cannot
     // resurrect one the live canvas had hidden for its own reasons.
+    // The pointer's hover highlight (selection/feature-highlight.js) is the
+    // same kind of transient feedback, and it TINTS the surface under it: a
+    // capture taken with the pointer resting on a part baked a translucent
+    // blue wash over it (an orange PLA sample came out pink).
     const reshowFlashDots = [];
-    for (const dot of flashDots) if (dot.visible) { dot.visible = false; reshowFlashDots.push(dot); }
+    for (const dot of [...flashDots, ...captureHidden]) if (dot.visible) { dot.visible = false; reshowFlashDots.push(dot); }
     try {
       renderer.setRenderTarget(rt);
       renderer.render(renderScene, cam);
@@ -969,9 +1443,11 @@ export function createViewer(container, part) {
       // Never leave the user's own view unlit, pointed at the offscreen target,
       // or missing a marker the user is still looking at.
       renderer.setRenderTarget(null);
-      scene.remove(capKey, capKey.target, capFill, capFill.target);
-      liveLights.key.visible = true;
-      liveLights.fill.visible = true;
+      if (!realistic) {
+        scene.remove(capKey, capKey.target, capFill, capFill.target);
+        liveLights.key.visible = keyWas;
+        liveLights.fill.visible = fillWas;
+      }
       for (const dot of reshowFlashDots) dot.visible = true;
       if (!cachedSize) rt.dispose();
     }
@@ -979,16 +1455,26 @@ export function createViewer(container, part) {
     canvas.width = width; canvas.height = height;
     const ctx = canvas.getContext("2d");
     const img = ctx.createImageData(width, height);
+    // Linear pixels → sRGB bytes: tone-mapped for a realistic capture, only
+    // transfer-encoded for CAD (which renders LDR with no tone mapping).
+    const encoded = realistic ? neutralToneMapToSrgb8(readbackToLinear(buf), renderer.toneMappingExposure) : srgbEncodeInPlace(buf);
     // flip rows (GL origin is bottom-left)
     for (let y = 0; y < height; y++) {
       const src = (height - 1 - y) * width * 4;
-      img.data.set(buf.subarray(src, src + width * 4), y * width * 4);
+      img.data.set(encoded.subarray(src, src + width * 4), y * width * 4);
     }
-    srgbEncodeInPlace(img.data);
     ctx.putImageData(img, 0, 0);
     return canvas.toDataURL("image/jpeg", quality);
   }
 
+  // Pointer feedback excluded from EVERY offscreen render (renderOffscreen),
+  // showcase captures included — unlike canonicalCaptureHidden below.
+  const captureHidden = new Set();
+  function registerCaptureHidden(obj) {
+    captureHidden.add(obj);
+    return () => captureHidden.delete(obj);
+  }
+
   // Objects excluded from CANONICAL captures only (agent renders must stay
   // dimension-free); captureCurrent — the user-framed showcase capture —
   // deliberately does NOT consult this set.
@@ -1000,8 +1486,21 @@ export function createViewer(container, part) {
 
   // Render the canonical camera angles offscreen, framed to whatever is visible,
   // without disturbing the user's live view. Returns [{ view, dataUrl }].
+  //
+  // Always the CAD look, whatever the live view shows: these are the agent's
+  // renders, and the editor's on-screen mode must never change what the agent
+  // sees. A realistic live view lends its scene to CAD for the synchronous
+  // capture and gets it back exactly (captureIn). renderViews is the one way
+  // to ask for realistic canonical views.
   function captureCanonicalViews(viewNames) {
     if (disposed) return [];
+    const box = getVisibleWorldBounds();
+    if (!box || box.isEmpty()) return []; // nothing to draw: don't swap the look for it
+    return captureIn("cad", null, () => canonicalViewsInCurrentLook(viewNames));
+  }
+  // The canonical views in whatever look the scene has right now — the body
+  // both captureCanonicalViews and renderViews wrap in captureIn.
+  function canonicalViewsInCurrentLook(viewNames) {
     const box = getVisibleWorldBounds();
     if (!box || box.isEmpty()) return [];
     const center = box.getCenter(new THREE.Vector3()).toArray();
@@ -1017,18 +1516,37 @@ export function createViewer(container, part) {
       bounds: { center, radius },
       // The ENCLOSING radius, which is a different number from the framing one
       // above: a box's corners reach √3 further than half its max extent, and
-      // the depth planes have to clear the corners.
-      sceneBounds: { center, radius: size.length() / 2 || 10 },
+      // the depth planes have to clear the corners. A realistic capture keeps
+      // its ground disc, which is several part radii across, so it counts too.
+      sceneBounds: (realisticRig && sceneDepthBounds()) || { center, radius: size.length() / 2 || 10 },
     });
   }
 
   // One offscreen render of the user's CURRENT framing (live camera pose +
   // orbit target, live aspect) at a caller-chosen resolution — the showcase
   // capture. Returns a JPEG data URL, or null when disposed / nothing visible.
+  //
+  // `renderMode` picks the look. Omitted, it follows the live view (a gallery
+  // "Capture from viewer" captures what the user sees). "cad" borrows CAD for
+  // the synchronous capture if the live view is realistic. "realistic" from a
+  // CAD view borrows the realistic look only if the current environment's
+  // assets have ALREADY loaded — this call is synchronous and cannot wait for
+  // them — and otherwise falls back to the live look; renderViews is the async
+  // path that guarantees realistic.
   function captureCurrent(opts) {
     if (disposed) return null;
     const box = getVisibleWorldBounds();
     if (!box || box.isEmpty()) return null;
+    const { renderMode: want, ...rest } = opts ?? {};
+    const capture = () => currentFramingInCurrentLook(rest);
+    if (want === "cad") return captureIn("cad", null, capture);
+    if (want === "realistic" && renderMode !== "realistic") {
+      const rig = loadedRigs.get(environmentId);
+      if (rig) return captureIn("realistic", rig, capture);
+    }
+    return capture();
+  }
+  function currentFramingInCurrentLook(opts) {
     return captureCurrentFromScene(opts, {
       renderer: { renderOffscreen },
       liveCamera: activeCamera,
@@ -1049,6 +1567,53 @@ export function createViewer(container, part) {
     });
   }
 
+  // Run one synchronous capture in the `want` look, leaving the live view
+  // exactly as it was — even if the capture throws. The swap and the restore
+  // sit in one synchronous block, so the canvas never paints a borrowed frame,
+  // and nothing is published: the live mode never changed. A parked viewer
+  // still captures (offscreen work), so its shadow is rendered on demand.
+  function captureIn(want, rig, capture) {
+    if (want === renderMode) {
+      if (want === "realistic" && !active) renderShadow(undefined, { force: true });
+      return capture();
+    }
+    if (want === "realistic") {
+      enterRealistic(rig, { live: false }); // rolls itself back to CAD if it throws
+      try { return capture(); } finally { enterCad({ live: false }); }
+    }
+    const liveRig = realisticRig, movedAt = shadowMovedAt;
+    try {
+      enterCad({ live: false });
+      return capture();
+    } finally {
+      try {
+        enterRealistic(liveRig, { live: false, reground: false });
+        shadowMovedAt = movedAt;
+      } catch (e) {
+        // enterRealistic already rolled the scene back to CAD: make it the live mode.
+        console.warn("partforge: restoring the realistic view after a capture failed", e);
+        try { applyPixelRatio("cad"); } catch { /* the view is CAD either way */ }
+        publishMode({ error: "couldn't load realistic view" });
+      }
+    }
+  }
+
+  // Agent-facing canonical renders in a chosen appearance, whatever the live
+  // view shows. CAD is exactly captureCanonicalViews (which is always CAD).
+  // Realistic waits for the current environment's rig and the capture's
+  // shader programs, then borrows the realistic look for the synchronous
+  // capture only if the live view is not already realistic. A rig that fails
+  // to load rejects rather than silently returning CAD images.
+  async function renderViews(viewNames, { renderMode: want = "cad" } = {}) {
+    if (disposed) return [];
+    if (want !== "realistic") return captureCanonicalViews(viewNames);
+    const rig = await rigFor(environmentId);
+    if (disposed) return [];
+    await compileRealistic(rig, { forCapture: true });
+    if (disposed) return [];
+    return captureIn("realistic", rig, () => canonicalViewsInCurrentLook(viewNames));
+  }
+
   // Offscreen render of an arbitrary mesh set (a non-active view), for thumbnails.
   // Assembles a THROWAWAY scene mirroring the live pivot convention, frames it from a
   // canonical angle, renders through the parameterized renderOffscreen, and disposes
@@ -1153,6 +1718,7 @@ export function createViewer(container, part) {
     for (const cb of [...frameListeners]) {
       try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
     }
+    updateMovingShadow(); // after the listeners, so it sees this frame's poses
     // After the frame listeners, before anything reads the camera to draw with:
     // a playback frame may have moved sub-parts or the camera itself, and both
     // change where the planes belong.
@@ -1206,6 +1772,9 @@ export function createViewer(container, part) {
       return;
     }
     resize(); // rebuild the buffer at whatever size the container is now
+    // A parked viewer renders no contact shadow (placeGround skips it), so a
+    // regen while hidden left it stale.
+    placeGround();
     lastFrameTime = null; // parked time is not elapsed time — no dt jump on unpark
     renderer.setAnimationLoop(renderFrame);
   }
@@ -1409,9 +1978,11 @@ export function createViewer(container, part) {
     for (const n of names) {
       const g = subCache[n];
       if (g) { g.userData.edges?.dispose(); g.dispose(); subCache[n] = null; }
-      // baseMats[n], not subMesh[n].material: an active fade override has swapped
-      // the mesh onto a clone, and the base material would otherwise leak.
-      baseMats[n]?.dispose();
+      // cadMats[n], not subMesh[n].material: an active fade override has swapped
+      // the mesh onto a clone, and the base material would otherwise leak. Not
+      // baseMats[n] either — in realistic mode that is a physical material,
+      // freed with the rest of them in disposeRealistic below.
+      cadMats[n]?.dispose();
       subMesh[n].geometry?.dispose(); // the initial empty BufferGeometry, if never replaced
     }
     // Hand the fade clones back before freeing them. cutaway.dispose() above has
@@ -1425,6 +1996,7 @@ export function createViewer(container, part) {
     for (const m of fadeLineMats.values()) m.dispose();
     fadeMats.clear();
     fadeLineMats.clear();
+    disposeRealistic();
     material.dispose();
     lineMaterial.dispose();
     grid.geometry.dispose();
@@ -1447,6 +2019,7 @@ export function createViewer(container, part) {
     captureCanonicalViews,
     captureCurrent,
     renderMeshPayloads,
+    renderViews,
     onFrame,
     tweenCameraTo,
     cancelCameraTween,
@@ -1489,7 +2062,23 @@ export function createViewer(container, part) {
     getCutawayPlane: cutaway.getPlane,
     registerCutawayMaterial: cutaway.registerClippableMaterial,
     registerCanonicalCaptureHidden,
+    registerCaptureHidden,
     onCutawayHandleHover: cutaway.onHandleHoverChange,
+    setRenderMode,
+    getRenderMode: () => renderMode,
+    onRenderModeChange: (cb) => { modeListeners.add(cb); return () => modeListeners.delete(cb); },
+    setEnvironment,
+    getEnvironment: () => environmentId,
+    // Whether the environment was named through setEnvironment (by the user or
+    // a host) rather than seeded from the part's meta.environment / the
+    // default — so a carried viewer state only pins an environment someone chose.
+    isEnvironmentChosen: () => environmentChosen,
+    // A realistic request is loading (getRenderMode still reads the mode on
+    // screen until it lands); false once it lands, fails, or is superseded.
+    isRealisticPending: () => realisticPending,
+    onEnvironmentChange: (cb) => { envListeners.add(cb); return () => envListeners.delete(cb); },
+    setPrintFrames,
+    whenRealisticReady,
     dispose,
   };
 }