partforge 0.121.0 → 0.122.0

package/src/framework/geometry/paper-bridge.js

@@ -3,6 +3,7 @@
 // package-global project — another consumer in the same worker may import paper too.
 import paper from "paper/dist/paper-core.js";
 import { tessellateContour, reverseContour, closeContourGap } from "./profile.js";
+import { arcCenterAndSweep } from "./arc-math.js";
 
 const ORIENT_SEGS = 8;   // points/segment for the local orientation sampler below
 
@@ -12,27 +13,9 @@ function paperScope() {
   return _scope;
 }
 
-// Circumcircle center + signed sweep for the arc through (p0, via, to) — the sweep is the
-// one passing through `via` (sign-free, winding-free), same recovery as profile.js's
-// sampleArc. Returns null for a collinear (degenerate) triple. Shared by arcToCubicSegments
-// below and contour-ops.js's jointTangents (arc tangents are ⊥ radius, oriented by dA's sign).
-export function arcCenterAndSweep(p0, via, to) {
-  const [ax, ay] = p0, [bx, by] = via, [cx, cy] = to;
-  const d = 2 * (ax * (by - cy) + bx * (cy - ay) + cx * (ay - by));
-  if (Math.abs(d) < 1e-12) return null;
-  const sa = ax*ax + ay*ay, sb = bx*bx + by*by, sc = cx*cx + cy*cy;
-  const ux = (sa * (by - cy) + sb * (cy - ay) + sc * (ay - by)) / d;
-  const uy = (sa * (cx - bx) + sb * (ax - cx) + sc * (bx - ax)) / d;
-  const r = Math.hypot(ax - ux, ay - uy);
-  const a0 = Math.atan2(ay - uy, ax - ux);
-  const av = Math.atan2(by - uy, bx - ux);
-  const a1 = Math.atan2(cy - uy, cx - ux);
-  const twoPi = 2 * Math.PI;
-  const ccw = (x) => { let v = x % twoPi; if (v < 0) v += twoPi; return v; };
-  const dCCW = ccw(a1 - a0), vCCW = ccw(av - a0);
-  const dA = vCCW <= dCCW ? dCCW : dCCW - twoPi;
-  return { center: [ux, uy], r, dA };
-}
+// arcCenterAndSweep now lives in arc-math.js (paper-free), re-exported here so every
+// existing importer of it from this module keeps working unchanged.
+export { arcCenterAndSweep } from "./arc-math.js";
 
 // Circular arc through (p0, via, to) → cubic Bézier segments, ≤90° each, endpoints
 // exact. Each piece uses the standard k = (4/3)·tan(θ/4) control-point offset.

package/src/framework/geometry/threemf.js

@@ -1,6 +1,7 @@
 // Minimal 3MF writer. 3MF is an OPC package (a zip) holding an XML model; it's a
 // mesh format like STL but supports units and multiple named objects in one file,
 // so a multi-part view exports as a single .3mf. Built from indexed meshes.
+// Each object may carry an optional colour (0xRRGGBB).
 import { zipSync, strToU8 } from "fflate";
 
 const CONTENT_TYPES =
@@ -67,16 +68,44 @@ function weld(positions, indices) {
   return { verts, tris };
 }
 
-// parts: [{ name, positions: Float32Array (x,y,z per vertex), indices: Uint32Array (3 per triangle) }]
-// → ArrayBuffer of the .3mf zip (millimetre units; one <object> + <build> item per part).
+// Default for an uncoloured object in an export where some other object IS
+// coloured: the viewer's own default look (presets.js "default"). Written as a
+// literal so this module keeps its fflate-only import closure.
+const DEFAULT_DISPLAY_COLOR = 0x9fb4cc;
+// Base-material group id: outside the object id range (objects are 1..n).
+const BASE_MATERIALS_ID = 1000;
+const hexColor = (c) => `#${c.toString(16).padStart(6, "0").toUpperCase()}FF`;
+
+// parts: [{ name, positions, indices, color? }] → ArrayBuffer of the .3mf zip.
+// `color` (0xRRGGBB) is optional per part. When NO part carries one, the model is
+// byte-for-byte what it was before colour support — no <basematerials>, no pid.
+// When any does, every object points (pid/pindex) into one core-spec
+// <basematerials> group, one <base> per distinct colour, so a slicer opens the
+// file pre-split into coloured objects.
 export function meshTo3MF(parts) {
+  const colored = parts.some((p) => p.color != null);
+  const palette = [];
+  const pindexOf = (c) => {
+    const color = c ?? DEFAULT_DISPLAY_COLOR;
+    let i = palette.indexOf(color);
+    if (i < 0) { i = palette.length; palette.push(color); }
+    return i;
+  };
+  const pindex = colored ? parts.map((p) => pindexOf(p.color)) : [];
+
   const out = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     '<model unit="millimeter" xml:lang="en-US" xmlns="http://schemas.microsoft.com/3dmanufacturing/core/2015/02">',
     "<resources>",
   ];
+  if (colored) {
+    out.push(`<basematerials id="${BASE_MATERIALS_ID}">`);
+    palette.forEach((c, i) => out.push(`<base name="color-${i + 1}" displaycolor="${hexColor(c)}"/>`));
+    out.push("</basematerials>");
+  }
   parts.forEach((p, i) => {
-    out.push(`<object id="${i + 1}" type="model" name="${xmlEsc(p.name)}"><mesh><vertices>`);
+    const mat = colored ? ` pid="${BASE_MATERIALS_ID}" pindex="${pindex[i]}"` : "";
+    out.push(`<object id="${i + 1}" type="model" name="${xmlEsc(p.name)}"${mat}><mesh><vertices>`);
     const { verts: v, tris: t } = weld(p.positions, p.indices);
     for (let k = 0; k < v.length; k += 3) out.push(`<vertex x="${v[k]}" y="${v[k + 1]}" z="${v[k + 2]}"/>`);
     out.push("</vertices><triangles>");

package/src/framework/jobs.js

@@ -3,6 +3,7 @@
 // the oracle and the collision check can share it without importing this async,
 // kernel-bound module back.
 import { meshTo3MF } from "./geometry/threemf.js";
+import { printColor } from "./materials/resolve.js";
 import { exportablePartNames } from "./export-select.js";
 import { fontControlAllows, fontSourceAllowed, isNoFontSource } from "./font-source.js";
 import { fontsFor, resolveFonts } from "./fonts.js";
@@ -449,7 +450,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const meshes = names.map((name) => {
         onProgress(`building ${label(name)}`);
         const { positions, indices } = posed(name, "export", onProgress).toIndexedMesh({ quality: msg.quality ?? "print" });
-        return { name: exportName(name), positions, indices };
+        return { name: exportName(name), positions, indices, color: printColor(part.parts[name]?.display) };
       });
       onProgress("writing 3MF file");
       const data = meshTo3MF(meshes);

package/src/framework/lint/index.js

@@ -20,8 +20,9 @@ import { FONT_RULES } from "./rules-fonts.js";
 import { IMAGE_RULES } from "./rules-images.js";
 import { SOURCE_RULES } from "./rules-source.js";
 import { VECTOR_RULES } from "./rules-vector.js";
+import { MATERIAL_RULES } from "./rules-materials.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...IMAGE_RULES, ...SOURCE_RULES, ...VECTOR_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES, ...IMPORT_RULES, ...FONT_RULES, ...IMAGE_RULES, ...SOURCE_RULES, ...VECTOR_RULES, ...MATERIAL_RULES];
 
 // A usable sources input, or null. Deliberately forgiving: lintPart's callers
 // include hosted paths handing over user/LLM-authored trees, so a malformed

package/src/framework/lint/rules-materials.js

@@ -0,0 +1,56 @@
+// src/framework/lint/rules-materials.js
+// Appearance findings. All WARNINGS by design: a misspelled material must never
+// block geometry, and the viewer already falls back (resolve.js). Pure — imports
+// only the three-free materials data (test/lint-purity.test.js).
+import { warn } from "./finding.js";
+import { PRESETS, DEFAULT_PRESET_ID } from "../materials/presets.js";
+import { ENVIRONMENTS } from "../materials/environments.js";
+import { resolveMaterial, resolveEnvironmentId, OVERRIDE_RANGES } from "../materials/resolve.js";
+import { suggest } from "../geometry/op-options.js";
+
+const listedPresets = () => Object.keys(PRESETS).filter((id) => id !== DEFAULT_PRESET_ID);
+const subParts = (part) => Object.entries(part?.parts ?? {}).filter(([, sp]) => sp && typeof sp === "object");
+const issuesOf = (part, kind) => subParts(part).flatMap(([name, sp]) =>
+  resolveMaterial(sp.display).issues.filter((i) => i.kind === kind).map((i) => ({ name, ...i })));
+
+export const MATERIAL_RULES = [
+  {
+    id: "unknown-material",
+    run: ({ part }) => issuesOf(part, "unknown-material").map(({ name, value }) => {
+      const near = typeof value === "string" ? suggest(value, listedPresets()) : null;
+      return warn("unknown-material",
+        `sub-part "${name}" names material ${JSON.stringify(value)}, which is not in the library`,
+        `${near ? `Did you mean "${near}"? ` : ""}The viewer shows the default look instead. Known materials: ${listedPresets().join(", ")}.`,
+        `parts.${name}.display.material`);
+    }),
+  },
+  {
+    id: "unknown-environment",
+    run: ({ part }) => {
+      const env = part?.meta?.environment;
+      if (resolveEnvironmentId(env).known) return [];
+      return [warn("unknown-environment",
+        `meta.environment ${JSON.stringify(env)} is not a known environment`,
+        `Realistic mode uses "studio" instead. Known environments: ${Object.keys(ENVIRONMENTS).join(", ")}.`,
+        "meta.environment")];
+    },
+  },
+  {
+    id: "material-key-unknown",
+    run: ({ part }) => issuesOf(part, "material-key-unknown").map(({ name, key }) =>
+      warn("material-key-unknown",
+        `sub-part "${name}" display has unknown key "${key}"`,
+        `It is ignored. display accepts color, opacity, material and the overrides ${Object.keys(OVERRIDE_RANGES).join(", ")}; transmission, IOR, sheen and iridescence come only from a preset.`,
+        `parts.${name}.display.${key}`)),
+  },
+  {
+    id: "material-override-clamped",
+    run: ({ part }) => issuesOf(part, "material-override-clamped").map(({ name, key, value, clampedTo }) => {
+      const [lo, hi] = OVERRIDE_RANGES[key];
+      return warn("material-override-clamped",
+        `sub-part "${name}" display.${key} = ${JSON.stringify(value)} is outside ${lo}..${hi}; using ${clampedTo}`,
+        `Give ${key} a number from ${lo} to ${hi}.`,
+        `parts.${name}.display.${key}`);
+    }),
+  },
+];

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();
+    },
+  };
+}