partforge 0.121.1 → 0.123.0

package/src/framework/materials/assets/SOURCES.md

@@ -0,0 +1,90 @@
+# Asset sources
+
+All source assets are CC0 (public domain dedication — no attribution required). Each
+source page was checked for "CC0" at download time (2026-09-24). Baked outputs are
+produced by `scripts/bake-environments.mjs`.
+
+Environments and ground/pattern textures are keyed by the file names `assets.js`
+resolves — see that module for the name -> URL map, and `environments.js` for which
+file each render environment uses.
+
+## Environments (HDRIs -> UltraHDR gainmap JPEGs)
+
+| File | Source asset | Source URL | Fetched | Processing |
+| --- | --- | --- | --- | --- |
+| `env-studio.jpg` | Poly Haven HDRI "Studio Small 09" | https://polyhaven.com/a/studio_small_09 | 2026-09-24 | 2K `.hdr` -> `node scripts/bake-environments.mjs studio_small_09_2k.hdr env-studio.jpg` |
+| `env-workshop.jpg` | Poly Haven HDRI "Industrial Workshop Foundry" | https://polyhaven.com/a/industrial_workshop_foundry | 2026-09-24 | 2K `.hdr` -> `node scripts/bake-environments.mjs industrial_workshop_foundry_2k.hdr env-workshop.jpg` |
+| `env-print-bed.jpg` | Poly Haven HDRI "Brown Photostudio 02" | https://polyhaven.com/a/brown_photostudio_02 | 2026-09-24 | 2K `.hdr` -> `node scripts/bake-environments.mjs brown_photostudio_02_2k.hdr env-print-bed.jpg --contrast 2`. The contrast curve (luminance raised to the power 2 about the image's log-average) darkens the room and sharpens its lights, for the inside of a printer enclosure; the environment record adds a hard overhead key light and dims the backdrop further. |
+| `env-outdoor.jpg` | Poly Haven HDRI "Kloofendal Overcast" | https://polyhaven.com/a/kloofendal_overcast | 2026-09-24 | 2K `.hdr` -> `node scripts/bake-environments.mjs kloofendal_overcast_2k.hdr env-outdoor.jpg` |
+
+Poly Haven publishes every asset under CC0 (https://polyhaven.com/license, checked
+2026-09-24). Licence text at fetch time also confirmed per-asset via
+`https://api.polyhaven.com/info/<slug>` (categories/metadata only — the site-wide
+license statement is what governs).
+
+### Environment baking detail
+
+`ultrahdr_app` (libultrahdr 2.0.2, `brew install libultrahdr`) only writes the newer
+ISO 21496-1 binary-box gainmap metadata, not the legacy Adobe XMP ("hdrgm"-prefixed)
+block. The baker therefore: (1) decodes the `.hdr` with three's own `HDRLoader` (pure
+JS) into a raw RGBA half-float buffer, (2) hands that to `ultrahdr_app -m 0` to derive
+the SDR rendition and gain map (`-a 4 -t 0`, sdr/gainmap quality 80, gainmap
+downsampled 2x), (3) splits the two embedded JPEG streams `ultrahdr_app` produced back
+apart, and (4) re-merges them with `@monogrid/gainmap-js`'s `encodeJPEGMetadata` (pure
+JS — no WebGL, only JPEG marker writing) using the boost/offset/gamma values read back
+off `ultrahdr_app`'s own probe of its ISO output, so both metadata conventions agree.
+A re-probe of each committed file (`ultrahdr_app -m 1 -j <file> -P`) round-trips the
+same boost numbers back out, confirming the legacy block is self-consistent. See
+`scripts/bake-environments.mjs`'s header comment for the fuller account, including why
+`@monogrid/gainmap-js`'s WebGL-based `encode()`/`findTextureMinMax()` path (the one the
+task brief originally sketched) is impractical in plain Node — no WebGL context is
+available, and this tree has no headless-GL shim.
+
+Before the re-merge, the baker also strips `ultrahdr_app`'s own APP2 MPF and ISO
+21496-1 metadata segments out of both the SDR and gain-map halves
+(`stripAppSegments` in the baker). Without this, `encodeJPEGMetadata` prepends its
+own freshly-computed MPF/XMP but leaves `ultrahdr_app`'s originals sitting later in
+the same file; three's `UltraHDRLoader` walks every top-level JPEG section across the
+whole concatenated file and keeps whichever MPF/ISO segment it sees LAST, so the
+stale one silently won — its offsets were computed for the old, smaller file, so the
+primary/gain-map slices it produced didn't even end on a real EOI marker. Verified
+fixed by driving three's actual `UltraHDRLoader.parse()` (via a `happy-dom` DOMParser
+polyfill, short-circuiting before the GPU decode step) against each committed file:
+the sliced primary and gain-map buffers now start with SOI (`FF D8`) and end with EOI
+(`FF D9`), and there is exactly one MPF segment and no leftover ISO box in the file.
+
+## Ground and pattern textures
+
+| File | Source asset | Source URL | Fetched | Processing |
+| --- | --- | --- | --- | --- |
+| `ground-paper.jpg` | ambientCG "Paper 001" (Color) | https://ambientcg.com/a/Paper001 | 2026-09-24 | 1K JPG -> `node scripts/bake-environments.mjs --texture Paper001_1K-JPG_Color.jpg ground-paper.jpg` |
+| `ground-paper-normal.jpg` | ambientCG "Paper 001" (NormalGL) | https://ambientcg.com/a/Paper001 | 2026-09-24 | 2K JPG -> `node scripts/bake-environments.mjs --texture Paper001_2K-JPG_NormalGL.jpg ground-paper-normal.jpg --data --size 1024 --quality 70`. The paper's grain lives in its relief; the colour map is nearly flat. |
+| `ground-paper-rough.jpg` | ambientCG "Paper 001" (Roughness) | https://ambientcg.com/a/Paper001 | 2026-09-24 | 2K JPG, grayscale -> `node scripts/bake-environments.mjs --texture Paper001_2K-JPG_Roughness.jpg ground-paper-rough.jpg --gray --size 1024` |
+| `pattern-oak-color.jpg` | Poly Haven "Oak Veneer 01" (colour; API key `Diffuse`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_diff_1k.jpg | 2026-09-24 | 1K JPG, sRGB colour -> `node scripts/bake-environments.mjs --texture oak_veneer_01_diff_1k.jpg pattern-oak-color.jpg` (q82). Scanned tile 1830 mm (`api.polyhaven.com/info/oak_veneer_01` dimensions). |
+| `pattern-oak-normal.jpg` | Poly Haven "Oak Veneer 01" (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_nor_gl_1k.jpg | 2026-09-24 | 1K JPG, OpenGL (+Y up) tangent normals, kept as data -> `node scripts/bake-environments.mjs --texture oak_veneer_01_nor_gl_1k.jpg pattern-oak-normal.jpg --data --quality 95` (4:4:4 chroma, no grayscale/tint; q95 because the map is nearly flat and the viewer amplifies it, so q90's 8x8 blocks showed). |
+| `pattern-oak-rough.jpg` | Poly Haven "Oak Veneer 01" (roughness; API key `Rough`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_rough_1k.jpg | 2026-09-24 | 1K JPG, grayscale data -> `node scripts/bake-environments.mjs --texture oak_veneer_01_rough_1k.jpg pattern-oak-rough.jpg --gray` (source is neutral grey; channel means unchanged). |
+| `pattern-walnut-color.jpg` | Poly Haven "Dark Wood" (colour; API key `Diffuse`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_diff_1k.jpg | 2026-09-24 | 1K JPG, sRGB colour -> `node scripts/bake-environments.mjs --texture dark_wood_diff_1k.jpg pattern-walnut-color.jpg` (q82). Scanned tile 2000 mm (`api.polyhaven.com/info/dark_wood` dimensions). |
+| `pattern-walnut-normal.jpg` | Poly Haven "Dark Wood" (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_nor_gl_1k.jpg | 2026-09-24 | 1K JPG, OpenGL (+Y up) tangent normals, kept as data -> `node scripts/bake-environments.mjs --texture dark_wood_nor_gl_1k.jpg pattern-walnut-normal.jpg --data --quality 95` (4:4:4 chroma, no grayscale/tint; q95 because the map is nearly flat and the viewer amplifies it, so q90's 8x8 blocks showed). |
+| `pattern-walnut-rough.jpg` | Poly Haven "Dark Wood" (roughness; API key `Rough`) | https://polyhaven.com/a/dark_wood — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/dark_wood/dark_wood_rough_1k.jpg | 2026-09-24 | 1K JPG, grayscale data -> `node scripts/bake-environments.mjs --texture dark_wood_rough_1k.jpg pattern-walnut-rough.jpg --gray` (source is neutral grey; channel means unchanged). |
+| `ground-maple-color.jpg` | Poly Haven "Oak Veneer 01" (colour; API key `Diffuse`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_diff_1k.jpg | 2026-09-24 | Workshop floor, "unfinished maple": `node scripts/bake-environments.mjs --texture oak_veneer_01_diff_1k.jpg ground-maple-color.jpg --modulate 1.5,0.7 --quality 85` (lightened 1.5x, saturation 0.7). |
+| `ground-maple-normal.jpg` | Poly Haven "Oak Veneer 01" (OpenGL normal map; API key `nor_gl`) | https://polyhaven.com/a/oak_veneer_01 — file https://dl.polyhaven.org/file/ph-assets/Textures/jpg/1k/oak_veneer_01/oak_veneer_01_nor_gl_1k.jpg | 2026-09-24 | Workshop floor relief: `node scripts/bake-environments.mjs --texture oak_veneer_01_nor_gl_1k.jpg ground-maple-normal.jpg --data --quality 92`. A separate file from `pattern-oak-normal.jpg` so the floor and the oak material never share (and dispose) one texture. |
+| `ground-pei.jpg` | None — procedural | n/a | n/a | Gold-brown fine-grain speckle, no external source. First attempt tinted ambientCG "Plastic 010"'s colour map (near-uniform, stdev < 1/channel — visibly flat, no grain, when actually viewed) gold-brown; that colour map carries no usable grain at all (its roughness map does, which is why `ground-pei-rough.jpg` below is still Plastic010's roughness). Checked ambientCG alternatives (Metal049A — also flat; Granite006A — real speckle but reads as rock, not powder-coat) and found nothing closer. Generated in-baker instead, same procedural precedent as `pattern-carbon.jpg`: per-pixel triangular-distributed noise around a `196,154,82` gold-brown base (asymmetric per channel so flecks warm rather than grey), then a 0.5px blur to turn single-pixel noise into soft grains -> `node scripts/bake-environments.mjs --speckle ground-pei.jpg --tint 196,154,82`. |
+| `ground-pei-rough.jpg` | ambientCG "Plastic 010" (Roughness) | https://ambientcg.com/a/Plastic010 | 2026-09-24 | 1K JPG, grayscale -> `node scripts/bake-environments.mjs --texture Plastic010_1K-JPG_Roughness.jpg ground-pei-rough.jpg --gray` |
+| `ground-concrete.jpg` | ambientCG "Concrete 047 A" (Color) | https://ambientcg.com/a/Concrete047A | 2026-09-24 | 2K JPG -> `node scripts/bake-environments.mjs --texture Concrete047A_2K-JPG_Color.jpg ground-concrete.jpg --size 1024 --modulate 1.35,0 --flatten 0.7 --quality 82` (grey, brightened to the old map's mean so the concrete material preset keeps its tone; `--flatten 0.7` is 30% less grain contrast). Replaced ambientCG "Concrete 034", whose colour map was nearly flat (stdev ~5/255) and read as blur up close; 047 A's exposed aggregate keeps fine grain. |
+| `ground-concrete-rough.jpg` | ambientCG "Concrete 047 A" (Roughness) | https://ambientcg.com/a/Concrete047A | 2026-09-24 | 2K JPG, grayscale -> `node scripts/bake-environments.mjs --texture Concrete047A_2K-JPG_Roughness.jpg ground-concrete-rough.jpg --gray --size 1024` |
+| `ground-concrete-normal.jpg` | ambientCG "Concrete 047 A" (NormalGL) | https://ambientcg.com/a/Concrete047A | 2026-09-24 | 2K JPG -> `node scripts/bake-environments.mjs --texture Concrete047A_2K-JPG_NormalGL.jpg ground-concrete-normal.jpg --data --size 1024 --quality 85` |
+| `pattern-carbon.jpg` | None — procedural | n/a | n/a | ambientCG has no CC0 carbon-fiber weave (searched "carbon"; only unrelated fabric hits). Generated in-baker: a 256x256 2x2 twill tile (32 threads/tile, alternating dark/light grey diagonal bands) -> `node scripts/bake-environments.mjs --carbon pattern-carbon.jpg`. No external source/licence to record. |
+
+ambientCG publishes every asset under CC0 (https://ambientcg.com/, "CC0 Public Domain
+license", checked 2026-09-24). The wood sets (`pattern-oak-*`, `pattern-walnut-*`,
+`ground-maple-*`) are Poly Haven textures, CC0 like its HDRIs above
+(https://polyhaven.com/license, checked 2026-09-24); the exact 1K JPG URLs came
+from `https://api.polyhaven.com/files/<slug>` (keys `Diffuse`, `nor_gl`, `Rough`).
+The presets tile them smaller than the scanned size — see the comment on `oak` in
+`presets.js` and on `workshop` in `environments.js`.
+
+## Budgets
+
+Environments stay under 1.5 MB (largest: `env-workshop.jpg` at ~398 KB); ground/pattern
+textures stay under 400 KB (largest: `pattern-oak-rough.jpg` at ~218 KB). All committed
+outputs are well inside both ceilings — see `test/framework/materials-assets.test.js`.

package/src/framework/materials/assets.js

@@ -0,0 +1,39 @@
+// src/framework/materials/assets.js
+// The ONLY module that turns an asset file name into a URL. `new URL("./assets/x",
+// import.meta.url)` with a LITERAL path is what makes a consuming Vite build emit
+// the file and rewrite the URL — a computed path is invisible to the bundler and
+// ships a 404 (the partforge/geometry incident class). So every file is listed
+// literally, once, here.
+const URLS = {
+  "env-studio.jpg": new URL("./assets/env-studio.jpg", import.meta.url).href,
+  "env-workshop.jpg": new URL("./assets/env-workshop.jpg", import.meta.url).href,
+  "env-print-bed.jpg": new URL("./assets/env-print-bed.jpg", import.meta.url).href,
+  "env-outdoor.jpg": new URL("./assets/env-outdoor.jpg", import.meta.url).href,
+  "ground-paper.jpg": new URL("./assets/ground-paper.jpg", import.meta.url).href,
+  "ground-paper-normal.jpg": new URL("./assets/ground-paper-normal.jpg", import.meta.url).href,
+  "ground-paper-rough.jpg": new URL("./assets/ground-paper-rough.jpg", import.meta.url).href,
+  "ground-maple-color.jpg": new URL("./assets/ground-maple-color.jpg", import.meta.url).href,
+  "ground-maple-normal.jpg": new URL("./assets/ground-maple-normal.jpg", import.meta.url).href,
+  "ground-pei.jpg": new URL("./assets/ground-pei.jpg", import.meta.url).href,
+  "ground-pei-rough.jpg": new URL("./assets/ground-pei-rough.jpg", import.meta.url).href,
+  "ground-concrete.jpg": new URL("./assets/ground-concrete.jpg", import.meta.url).href,
+  "ground-concrete-rough.jpg": new URL("./assets/ground-concrete-rough.jpg", import.meta.url).href,
+  "ground-concrete-normal.jpg": new URL("./assets/ground-concrete-normal.jpg", import.meta.url).href,
+  "pattern-oak-color.jpg": new URL("./assets/pattern-oak-color.jpg", import.meta.url).href,
+  "pattern-oak-normal.jpg": new URL("./assets/pattern-oak-normal.jpg", import.meta.url).href,
+  "pattern-oak-rough.jpg": new URL("./assets/pattern-oak-rough.jpg", import.meta.url).href,
+  "pattern-walnut-color.jpg": new URL("./assets/pattern-walnut-color.jpg", import.meta.url).href,
+  "pattern-walnut-normal.jpg": new URL("./assets/pattern-walnut-normal.jpg", import.meta.url).href,
+  "pattern-walnut-rough.jpg": new URL("./assets/pattern-walnut-rough.jpg", import.meta.url).href,
+  "pattern-carbon.jpg": new URL("./assets/pattern-carbon.jpg", import.meta.url).href,
+};
+
+// Single-mask patterns. Wood is a full PBR set named per preset (presets.js
+// `textures`), so it has no entry here.
+export const PATTERN_TEXTURES = { carbon: "pattern-carbon.jpg", concrete: "ground-concrete.jpg" };
+
+export function assetUrl(name) {
+  const url = URLS[name];
+  if (!url) throw new Error(`partforge: unknown material asset "${name}"`);
+  return url;
+}

package/src/framework/materials/contact-shadow.js

@@ -0,0 +1,155 @@
+// src/framework/materials/contact-shadow.js
+// A contact shadow for realistic mode (after three's webgl_shadow_contact
+// example): render the casters' depth from BELOW into a target, blur it, and
+// lay it on the ground. Rendered on demand — on geometry change, and at low
+// resolution while an animation moves a sub-part — never every frame.
+//
+// Two layers, like a real shadow: a TIGHT one (high resolution, a millimetre
+// or so of blur, a steep height falloff) that follows the part's own outline
+// where it meets the ground, over a faint SOFT one (low resolution, a blur
+// that scales with the part) that stands in for the ambient darkening around
+// it. The tight layer alone reads as a cut-out; the soft one alone as a blob.
+import * as THREE from "three";
+import { HorizontalBlurShader } from "three/addons/shaders/HorizontalBlurShader.js";
+import { VerticalBlurShader } from "three/addons/shaders/VerticalBlurShader.js";
+
+const LAYERS = [
+  // blurMm: a fixed reach in millimetres; blurFrac: a reach as a fraction of
+  // the shadow plane (so it grows with the part). falloff: the power the
+  // height fade is raised to — higher is denser at contact, thinner above.
+  { name: "soft", resolution: 256, darkness: 0.22, blurFrac: 0.035, falloff: 1.5 },
+  { name: "tight", resolution: 1024, darkness: 0.42, blurMm: 1.2, falloff: 2.5 },
+];
+
+function depthMaterialFor(darkness, falloff) {
+  const m = new THREE.MeshDepthMaterial();
+  m.onBeforeCompile = (shader) => {
+    shader.fragmentShader = shader.fragmentShader.replace(
+      "gl_FragColor = vec4( vec3( 1.0 - fragCoordZ ), opacity );",
+      `gl_FragColor = vec4( vec3( 0.0 ), pow( 1.0 - fragCoordZ, ${falloff.toFixed(2)} ) * ${darkness.toFixed(3)} );`,
+    );
+  };
+  m.customProgramCacheKey = () => `pf-contact-${darkness}-${falloff}`;
+  m.depthTest = false;
+  m.depthWrite = false;
+  return m;
+}
+
+export function createContactShadow({ renderer, sizeMm = 400 }) {
+  const group = new THREE.Group();
+  const planeGeo = new THREE.PlaneGeometry(1, 1).rotateX(Math.PI / 2);
+
+  const layers = LAYERS.map((spec, i) => {
+    const rt = new THREE.WebGLRenderTarget(spec.resolution, spec.resolution);
+    rt.texture.generateMipmaps = false;
+    const rtBlur = new THREE.WebGLRenderTarget(spec.resolution, spec.resolution);
+    rtBlur.texture.generateMipmaps = false;
+    // polygonOffset: the ground sits a hair below this plane and writes
+    // depth; at a normal viewing distance that hair is inside the depth
+    // buffer's precision, so without the offset the shadow z-fights it.
+    const plane = new THREE.Mesh(planeGeo, new THREE.MeshBasicMaterial({
+      map: rt.texture, opacity: 1, transparent: true, depthWrite: false,
+      polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -4 - i,
+    }));
+    plane.renderOrder = 1 + i; // tight over soft
+    group.add(plane);
+    return { spec, rt, rtBlur, plane, depthMaterial: depthMaterialFor(spec.darkness, spec.falloff) };
+  });
+
+  const blurPlane = new THREE.Mesh(planeGeo);
+  blurPlane.visible = false;
+  group.add(blurPlane);
+
+  const cam = new THREE.OrthographicCamera(-0.5, 0.5, 0.5, -0.5, 0, 1);
+  cam.rotation.x = Math.PI / 2;
+  group.add(cam);
+
+  const hBlur = new THREE.ShaderMaterial(HorizontalBlurShader); hBlur.depthTest = false;
+  const vBlur = new THREE.ShaderMaterial(VerticalBlurShader); vBlur.depthTest = false;
+
+  // The meshes are scaled; the camera is SIZED. three leaves scale out of a
+  // camera's view matrix, so a camera sized by a scaled parent would see a
+  // 1 mm square (it did: the shadow was empty in every environment).
+  let planeSize = sizeMm;
+  function setSize(size, height = size) {
+    planeSize = size;
+    for (const l of layers) l.plane.scale.set(size, -1, size); // y = -1: rendered from below
+    blurPlane.scale.set(size, 1, size);
+    cam.left = -size / 2; cam.right = size / 2;
+    cam.top = size / 2; cam.bottom = -size / 2;
+    cam.far = height;
+    cam.updateProjectionMatrix();
+  }
+  setSize(sizeMm);
+
+  // The blur plane sits in the shadow group, i.e. in the user's scene, so it
+  // is hidden again even if a blur render throws. three's blur shaders reach
+  // four taps either side, `h` apart in UV: a reach of `mm` millimetres on a
+  // plane `planeSize` across is h = mm / planeSize / 4.
+  function blurPass(layer, mm) {
+    const step = mm / planeSize / 4;
+    blurPlane.visible = true;
+    try {
+      blurPlane.material = hBlur; hBlur.uniforms.tDiffuse.value = layer.rt.texture; hBlur.uniforms.h.value = step;
+      renderer.setRenderTarget(layer.rtBlur); renderer.render(blurPlane, cam);
+      blurPlane.material = vBlur; vBlur.uniforms.tDiffuse.value = layer.rtBlur.texture; vBlur.uniforms.v.value = step;
+      renderer.setRenderTarget(layer.rt); renderer.render(blurPlane, cam);
+    } finally {
+      blurPlane.visible = false;
+    }
+  }
+
+  // `casters` are the visible sub-part meshes; everything else in `scene` is
+  // hidden for the depth pass so only the part casts. Every mutation here —
+  // to the scene and to the renderer's own state — is captured up front and
+  // restored in `finally`, so a throw mid-render (context loss, a shader
+  // compile failure) never leaves the user's scene with hidden objects, the
+  // depth override material pinned, no background, or the wrong render
+  // target bound.
+  //
+  // While a part moves (lowRes) only the soft layer is redrawn and the tight
+  // one is hidden: an outline left where the part WAS would be wrong, and the
+  // settle render that follows brings it back.
+  function render(scene, casters, { lowRes = false } = {}) {
+    const bg = scene.background;
+    const overrideBefore = scene.overrideMaterial;
+    const clear = renderer.getClearAlpha();
+    const prevRT = renderer.getRenderTarget();
+    const hidden = [];
+    scene.traverseVisible((o) => { if (o.isMesh || o.isLine || o.isLineSegments || o.isSprite) if (!casters.includes(o)) { o.visible = false; hidden.push(o); } });
+    for (const l of layers) l.plane.visible = false;
+    try {
+      scene.background = null;
+      renderer.setClearAlpha(0);
+      for (const l of layers) {
+        if (lowRes && l.spec.name === "tight") continue;
+        scene.overrideMaterial = l.depthMaterial;
+        renderer.setRenderTarget(l.rt);
+        renderer.render(scene, cam);
+        scene.overrideMaterial = overrideBefore;
+        const reach = l.spec.blurMm ?? l.spec.blurFrac * planeSize;
+        blurPass(l, reach);
+        if (!lowRes) blurPass(l, reach * 0.5);
+      }
+    } finally {
+      scene.overrideMaterial = overrideBefore;
+      renderer.setRenderTarget(prevRT);
+      renderer.setClearAlpha(clear);
+      for (const o of hidden) o.visible = true;
+      // After the restore above: the planes are in the scene too, so they were
+      // among `hidden`, and restoring them first would undo this.
+      for (const l of layers) l.plane.visible = !(lowRes && l.spec.name === "tight");
+      scene.background = bg;
+    }
+  }
+
+  return {
+    group,
+    render,
+    setSize,
+    dispose() {
+      for (const l of layers) { l.rt.dispose(); l.rtBlur.dispose(); l.plane.material.dispose(); l.depthMaterial.dispose(); }
+      planeGeo.dispose(); hBlur.dispose(); vBlur.dispose();
+    },
+  };
+}

package/src/framework/materials/environment.js

@@ -0,0 +1,157 @@
+// src/framework/materials/environment.js
+// One environment "rig": PMREM-filtered lighting from a baked UltraHDR JPEG, a
+// backdrop, a textured ground disc that fades into the backdrop at its rim, and a
+// contact shadow. Loaded lazily the first time an environment is shown; the
+// loaders are injected so this is testable without GL or network.
+import * as THREE from "three";
+import { ENVIRONMENTS } from "./environments.js";
+import { resolveEnvironmentId } from "./resolve.js";
+import { assetUrl } from "./assets.js";
+import { createContactShadow } from "./contact-shadow.js";
+import { createPrintBed } from "./print-bed.js";
+
+const GROUND_RADIUS_FACTOR = 4; // ground disc radius, in part radii
+
+// A ground normal map is OpenGL-format (+Y up, Poly Haven's "nor_gl"), which is
+// what three's tangent-space normal maps expect: a positive normalScale.
+const GROUND_NORMAL_SCALE = 1.5;
+
+// ground.detail: {scale, strength} re-samples the colour map `scale` times
+// finer and multiplies it in at `strength`, so a ground seen up close under a
+// small part keeps crisp grain after the base map's texels have gone soft.
+// `mean` is the map's average linear luminance, so the detail layer darkens
+// and lightens about 1 rather than shifting the ground's overall tone.
+function injectDetail(shader, { scale, strength, mean }) {
+  shader.fragmentShader = shader.fragmentShader.replace(
+    "#include <map_fragment>",
+    `#include <map_fragment>
+#ifdef USE_MAP
+  {
+    float pfDl = dot(texture2D(map, vMapUv * ${scale.toFixed(3)}).rgb, vec3(0.3333));
+    diffuseColor.rgb *= mix(1.0, pfDl / ${mean.toFixed(3)}, ${strength.toFixed(3)});
+  }
+#endif`,
+  );
+}
+
+function groundMaterial(tex, rough, normal, { tint, roughness = 1, normalScale = GROUND_NORMAL_SCALE, bed = false, detail }) {
+  const m = new THREE.MeshStandardMaterial({
+    color: tint, map: tex, roughnessMap: rough ?? null, roughness, metalness: 0, transparent: !bed,
+    ...(normal ? { normalMap: normal, normalScale: new THREE.Vector2(normalScale, normalScale) } : {}),
+  });
+  if (bed) {
+    // a build plate has a hard edge: no rim fade
+    if (detail) {
+      m.onBeforeCompile = (shader) => injectDetail(shader, detail);
+      m.customProgramCacheKey = () => "pf-ground-bed-detail";
+    }
+    return m;
+  }
+  // Radial fade to transparent at the rim so the disc melts into the backdrop.
+  m.onBeforeCompile = (shader) => {
+    if (detail) injectDetail(shader, detail);
+    shader.vertexShader = shader.vertexShader
+      .replace("#include <common>", "#include <common>\nvarying vec2 vPfDisc;")
+      .replace("#include <begin_vertex>", "#include <begin_vertex>\nvPfDisc = position.xz;");
+    shader.fragmentShader = shader.fragmentShader
+      .replace("#include <common>", "#include <common>\nvarying vec2 vPfDisc;")
+      .replace("#include <dithering_fragment>", "#include <dithering_fragment>\ngl_FragColor.a *= 1.0 - smoothstep(0.35, 0.5, length(vPfDisc));");
+  };
+  m.customProgramCacheKey = () => (detail ? "pf-ground-detail" : "pf-ground");
+  return m;
+}
+
+export async function loadEnvironmentRig(renderer, requestedId, { loadHdr, loadTexture, pmrem, createCanvas }) {
+  const { id } = resolveEnvironmentId(requestedId);
+  const env = ENVIRONMENTS[id];
+  const hdr = await loadHdr(assetUrl(env.hdr));
+  hdr.mapping = THREE.EquirectangularReflectionMapping;
+  let envMap;
+  try { envMap = pmrem.fromEquirectangular(hdr).texture; } catch (e) { hdr.dispose(); throw e; }
+
+  // Every environment draws its own photo, blurred, as the backdrop — so the
+  // equirect stays alive for the rig's life (freed in dispose()).
+  const background = hdr;
+  const backgroundBlurriness = env.blurriness ?? 0.6;
+  const backgroundIntensity = env.backgroundIntensity ?? 1;
+
+  const tex = loadTexture(env.ground.texture);
+  tex.wrapS = tex.wrapT = THREE.RepeatWrapping;
+  tex.colorSpace = THREE.SRGBColorSpace;
+  // Roughness and normal maps are data, not colour: never sRGB-decoded.
+  const dataMap = (file) => {
+    if (!file) return null;
+    const t = loadTexture(file);
+    t.wrapS = t.wrapT = THREE.RepeatWrapping;
+    t.colorSpace = THREE.NoColorSpace;
+    return t;
+  };
+  const rough = dataMap(env.ground.roughnessTexture);
+  const normal = dataMap(env.ground.normalTexture);
+  const shadow = createContactShadow({ renderer, sizeMm: env.ground.sizeMm });
+
+  // env.ground.bed: a standard-size build plate instead of the fading disc.
+  if (env.ground.bed) {
+    const material = groundMaterial(tex, rough, normal, { ...env.ground, bed: true });
+    const bed = createPrintBed({ pei: material, tileMm: env.ground.tileMm ?? env.ground.sizeMm, createCanvas });
+    // An enclosure's LED bar: one hard overhead light, riding with the bed so
+    // it always falls on the part from the same place.
+    let keyLight = null;
+    if (env.keyLight) {
+      keyLight = new THREE.DirectionalLight(0xffffff, env.keyLight.intensity);
+      keyLight.position.set(...env.keyLight.direction);
+      bed.object.add(keyLight, keyLight.target);
+    }
+    return {
+      id, exposure: env.exposure, envMap, background, backgroundBlurriness, backgroundIntensity,
+      rotationY: ((env.rotationDeg ?? 0) * Math.PI) / 180,
+      ground: bed.object,
+      shadow,
+      setGround({ y, centerX = 0, centerZ = 0, radius, footprintMm = radius }) {
+        bed.place({ y, centerX, centerZ, footprintMm });
+        shadow.group.position.set(centerX, y, centerZ);
+        // The shadow plane never hangs past the plate's edge into thin air.
+        const s = Math.min(Math.max(radius * 3, 20), bed.sizeMm);
+        shadow.setSize(s, Math.max(radius * 4, 20));
+      },
+      dispose() {
+        envMap.dispose(); hdr.dispose(); tex.dispose(); rough?.dispose(); normal?.dispose();
+        material.dispose(); bed.dispose(); shadow.dispose(); keyLight?.dispose();
+      },
+    };
+  }
+
+  const discGeo = new THREE.CircleGeometry(0.5, 96).rotateX(-Math.PI / 2);
+  const ground = new THREE.Mesh(discGeo, groundMaterial(tex, rough, normal, env.ground));
+  ground.renderOrder = -1;
+
+  function setGround({ y, centerX = 0, centerZ = 0, radius }) {
+    const r = Math.max(radius * GROUND_RADIUS_FACTOR, env.ground.sizeMm / 2);
+    ground.position.set(centerX, y - 0.01, centerZ);
+    ground.scale.setScalar(r * 2);
+    // Keep the texture at real millimetres however large the disc is.
+    const repeat = (r * 2) / (env.ground.tileMm ?? env.ground.sizeMm);
+    tex.repeat.set(repeat, repeat);
+    if (rough) rough.repeat.set(repeat, repeat);
+    if (normal) normal.repeat.set(repeat, repeat);
+    shadow.group.position.set(centerX, y, centerZ);
+    shadow.setSize(Math.max(radius * 3, 20), Math.max(radius * 4, 20));
+  }
+
+  return {
+    id,
+    exposure: env.exposure,
+    envMap,
+    background,
+    backgroundBlurriness,
+    backgroundIntensity,
+    rotationY: ((env.rotationDeg ?? 0) * Math.PI) / 180,
+    ground,
+    shadow,
+    setGround,
+    dispose() {
+      envMap.dispose(); hdr.dispose(); tex.dispose(); rough?.dispose(); normal?.dispose();
+      discGeo.dispose(); ground.material.dispose(); shadow.dispose();
+    },
+  };
+}

package/src/framework/materials/environments.js

@@ -0,0 +1,82 @@
+// src/framework/materials/environments.js
+// Environment records — plain data like presets.js. `hdr` and the ground textures
+// are FILE NAMES under ./assets/, resolved to URLs by assets.js (which is the only
+// module that may use `new URL(..., import.meta.url)`, so this one stays importable
+// by lint and the worker).
+//
+// ground.sizeMm is the smallest the ground disc ever gets (and the shadow's
+// starting size); ground.tileMm, when set, is how many millimetres one repeat of
+// the ground texture covers — defaulting to sizeMm. rotationDeg, when set, turns
+// the environment (lighting and backdrop together) about the vertical axis.
+// ground.roughnessTexture and ground.normalTexture are optional data maps
+// (normal maps OpenGL-format, +Y up) tiled the same way as the colour map;
+// ground.roughness (default 1) scales the roughness map. backgroundIntensity
+// (default 1) dims the drawn backdrop without dimming the light on the part.
+// ground.detail ({scale, strength, mean}) blends the colour map back in at a
+// finer scale so the ground keeps grain up close (environment.js).
+
+export const DEFAULT_ENVIRONMENT_ID = "studio";
+
+export const ENVIRONMENTS = {
+  studio: {
+    id: "studio", label: "Studio", exposure: 0.8,
+    hdr: "env-studio.jpg",
+    // Paper 001's fibre relief (normal + roughness) does the work: its colour
+    // map is nearly flat, so without them the sweep read as soft blotches up
+    // close. The detail layer keeps the grain crisp under a small part.
+    ground: {
+      texture: "ground-paper.jpg", normalTexture: "ground-paper-normal.jpg", roughnessTexture: "ground-paper-rough.jpg",
+      normalScale: 0.6, sizeMm: 400, tileMm: 200, tint: 0xf2f2f2,
+      detail: { scale: 5.17, strength: 0.5, mean: 0.9 },
+    },
+    // Turns the studio photo so its two octagonal softboxes glow behind the part
+    // from the viewer's default camera, the classic product-shot backdrop.
+    rotationDeg: 300,
+    blurriness: 0.3,
+  },
+  workshop: {
+    id: "workshop", label: "Workshop", exposure: 0.88,
+    hdr: "env-workshop.jpg",
+    // Unfinished maple: Poly Haven "Oak Veneer 01" lightened and desaturated
+    // at bake time, with its normal map at a gentle strength and NO roughness
+    // map — a flat, fully matte roughness, so the floor never shows a glossy
+    // spot. Tiled at 600 mm (finer grain than the 1.83 m scan, as maple is).
+    ground: {
+      texture: "ground-maple-color.jpg", normalTexture: "ground-maple-normal.jpg",
+      sizeMm: 600, tileMm: 600, roughness: 0.92, normalScale: 0.8, tint: 0xffffff,
+    },
+  },
+  "print-bed": {
+    id: "print-bed", label: "Print bed", exposure: 0.42,
+    // The studio photo re-baked with --contrast: a darker, harsher room, like
+    // the inside of a printer's enclosure.
+    hdr: "env-print-bed.jpg",
+    blurriness: 0.4,
+    backgroundIntensity: 0.6, // the enclosure walls sit darker than the light on the part
+    // A hard overhead light from above and a little in front, like the LED bar
+    // in a printer's enclosure (direction is toward the light, from the bed).
+    keyLight: { intensity: 4.5, direction: [0.4, 1, 0.6] },
+    // bed: a cut-out, standard-size build plate (print-bed.js) with printed
+    // markings, instead of a disc fading into the backdrop. tileMm is one PEI
+    // texture repeat.
+    ground: {
+      texture: "ground-pei.jpg", roughnessTexture: "ground-pei-rough.jpg", sizeMm: 256, tileMm: 128,
+      tint: 0xffffff, bed: true,
+    },
+  },
+  outdoor: {
+    id: "outdoor", label: "Outdoor", exposure: 0.72,
+    hdr: "env-outdoor.jpg",
+    // Tinted to a warm mid-grey: the overcast sky lights an untinted concrete
+    // map near-white and blue. Exposed-aggregate concrete with its own normal
+    // map, tiled at 400 mm so the grain stays crisp (about 0.4 mm a texel)
+    // under a small part seen up close.
+    ground: {
+      texture: "ground-concrete.jpg", roughnessTexture: "ground-concrete-rough.jpg",
+      normalTexture: "ground-concrete-normal.jpg", normalScale: 0.7,
+      sizeMm: 800, tileMm: 400, tint: 0x9e9282,
+      // Micro-grain for close-ups: the same map ~7x finer, blended lightly.
+      detail: { scale: 7.13, strength: 0.245, mean: 0.5 },
+    },
+  },
+};