partforge 0.121.1 → 0.123.0

package/src/framework/materials/patterns.js

@@ -0,0 +1,243 @@
+// The ONE shader-injection module (onBeforeCompile). Everything a future TSL /
+// WebGPU port would have to rewrite lives here and nowhere else.
+//
+// All patterns work in OBJECT space (the sub-part's delivered mesh frame), so
+// they move with the sub-part under animation and never slide when the camera
+// moves. Layer lines additionally map object space through `pfPrintFrame`
+// (print-frame.js: display→export), so they run the way the part will print.
+import * as THREE from "three";
+
+const VERT_DECL = "varying vec3 vPfObjPos;\nvarying vec3 vPfObjNormal;\nvarying vec3 vPfPrintUpView;\nuniform mat4 pfPrintFrame;\n";
+// Wood's triplanar normal map builds its normal in OBJECT space; the fragment
+// stage has no normalMatrix, so its three columns ride along as varyings.
+const VERT_DECL_NM = "varying vec3 vPfNmX;\nvarying vec3 vPfNmY;\nvarying vec3 vPfNmZ;\n";
+const VERT_BODY_NM = "vPfNmX = normalMatrix[0];\nvPfNmY = normalMatrix[1];\nvPfNmZ = normalMatrix[2];\n";
+// vPfPrintUpView: the print direction (export +Z) in VIEW space — the gradient
+// of the layer height, carried by normalMatrix like any other normal — so the
+// layer-line normal map can tilt normals along it (identity print frame for the
+// other patterns, which never read it).
+const VERT_BODY = "vPfObjPos = position;\nvPfObjNormal = normal;\nvPfPrintUpView = normalMatrix * vec3(pfPrintFrame[0].z, pfPrintFrame[1].z, pfPrintFrame[2].z);\n";
+
+const FRAG_DECL = `
+varying vec3 vPfObjPos;
+varying vec3 vPfObjNormal;
+varying vec3 vPfPrintUpView;
+uniform float pfPatternScale;
+uniform mat4 pfPrintFrame;
+uniform sampler2D pfPatternMap;
+float pfHash(vec3 p) { p = fract(p * 0.3183099 + 0.1); p *= 17.0; return fract(p.x * p.y * p.z * (p.x + p.y + p.z)); }
+float pfNoise(vec3 x) {
+  vec3 i = floor(x); vec3 f = fract(x); f = f * f * (3.0 - 2.0 * f);
+  return mix(mix(mix(pfHash(i), pfHash(i + vec3(1,0,0)), f.x), mix(pfHash(i + vec3(0,1,0)), pfHash(i + vec3(1,1,0)), f.x), f.y),
+             mix(mix(pfHash(i + vec3(0,0,1)), pfHash(i + vec3(1,0,1)), f.x), mix(pfHash(i + vec3(0,1,1)), pfHash(i + vec3(1,1,1)), f.x), f.y), f.z);
+}
+vec3 pfTriplanar(sampler2D map, vec3 p, vec3 n, float scale) {
+  vec3 w = pow(abs(normalize(n)), vec3(4.0)); w /= (w.x + w.y + w.z);
+  return texture2D(map, p.yz / scale).rgb * w.x + texture2D(map, p.xz / scale).rgb * w.y + texture2D(map, p.xy / scale).rgb * w.z;
+}
+`;
+
+// Extra declarations only the wood kind needs: its normal and roughness maps and
+// the normal-matrix varyings. Kept out of FRAG_DECL so the other kinds don't bind
+// two empty samplers.
+const FRAG_DECL_WOOD = `
+uniform sampler2D pfNormalMap;
+uniform sampler2D pfRoughMap;
+uniform float pfRoughMean;
+uniform float pfNormalStrength;
+varying vec3 vPfNmX;
+varying vec3 vPfNmY;
+varying vec3 vPfNmZ;
+vec3 pfTriplanarWeights(vec3 n) { vec3 w = pow(abs(n), vec3(4.0)); return w / (w.x + w.y + w.z); }
+// Triplanar tangent-space normal map, whiteout-blended (Golus, "Normal Mapping
+// for a Triplanar Shader"). Each projection's map is read as a height field over
+// the two object axes its UVs run along, so its tangent normal (x, y) is a slope
+// along those axes and z points along the face's own axis — the whiteout form
+// (t.xy + n.<uv axes>, |t.z| * n.<face axis>) needs no per-side sign flips: on
+// the back face n.<face axis> is negative and the swizzle follows the same height
+// field, so light still catches the same grain. OpenGL-format maps (+Y up), the
+// Poly Haven "nor_gl" convention. Returns an OBJECT-space unit normal.
+vec3 pfTriplanarNormal(vec3 p, vec3 n, float scale) {
+  vec3 w = pfTriplanarWeights(n);
+  vec3 tx = texture2D(pfNormalMap, p.yz / scale).xyz * 2.0 - 1.0;
+  vec3 ty = texture2D(pfNormalMap, p.xz / scale).xyz * 2.0 - 1.0;
+  vec3 tz = texture2D(pfNormalMap, p.xy / scale).xyz * 2.0 - 1.0;
+  tx.xy *= pfNormalStrength; ty.xy *= pfNormalStrength; tz.xy *= pfNormalStrength;
+  tx = vec3(tx.xy + n.yz, abs(tx.z) * n.x);   // uv = (y, z), face axis x
+  ty = vec3(ty.xy + n.xz, abs(ty.z) * n.y);   // uv = (x, z), face axis y
+  tz = vec3(tz.xy + n.xy, abs(tz.z) * n.z);   // uv = (x, y), face axis z
+  return normalize(tx.zxy * w.x + ty.xzy * w.y + tz.xyz * w.z);
+}
+`;
+
+// Per-kind fragment code, injected after <roughnessmap_fragment> so it can
+// modulate both diffuseColor (already written by <map_fragment>) and roughnessFactor.
+const FRAG_BODY = {
+  "layer-lines": `
+  {
+    float h = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;
+    float ridge = abs(fract(h) - 0.5) * 2.0;            // 0 at a layer seam, 1 mid-layer
+    float groove = smoothstep(0.0, 0.35, ridge);
+    // Anti-alias: fwidth(h) is layers per pixel. Where a layer spans fewer
+    // than ~6 px the band fades to its mean over a period (0.825: the groove
+    // ramps over 35% of it, the rest is flat), and past ~2.5 px it is gone —
+    // point-sampling finer layers than that is what aliased into moiré.
+    groove = mix(0.825, groove, 1.0 - smoothstep(0.16, 0.4, fwidth(h)));
+    diffuseColor.rgb *= mix(0.9, 1.0, groove); // the normal map (FRAG_NORMAL) carries most of the relief
+    roughnessFactor = clamp(roughnessFactor + (1.0 - groove) * 0.18, 0.0, 1.0);
+    // Filament mottling: a fine grain (~0.17 mm) over slow blotches (~2 mm),
+    // fixed to the part, so a print doesn't read as flat injection-moulded plastic.
+    float mottle = pfNoise(vPfObjPos * 6.0) * 0.6 + pfNoise(vPfObjPos * 0.51) * 0.4;
+    diffuseColor.rgb *= mix(0.893, 1.047, mottle);
+    roughnessFactor = clamp(roughnessFactor + (mottle - 0.5) * 0.084, 0.0, 1.0);
+  }`,
+  "sls-grain": `
+  {
+    float g = pfNoise(vPfObjPos / pfPatternScale);
+    diffuseColor.rgb *= mix(0.92, 1.04, g);
+    roughnessFactor = clamp(roughnessFactor + (g - 0.5) * 0.1, 0.0, 1.0);
+  }`,
+  // Wood is a full PBR set sampled triplanar in object space: the colour map
+  // (sRGB, so already linear here) multiplies diffuseColor — white unless the
+  // author tinted it, physical.js — and the roughness map varies roughnessFactor
+  // around the preset's value (divided by the map's own mean, so the preset sets
+  // the average). Mipmaps (and RepeatWrapping) do the far-distance filtering.
+  wood: `
+  {
+    vec3 pfN = normalize(vPfObjNormal);
+    diffuseColor.rgb *= pfTriplanar(pfPatternMap, vPfObjPos, pfN, pfPatternScale);
+    float r = pfTriplanar(pfRoughMap, vPfObjPos, pfN, pfPatternScale).g;
+    roughnessFactor = clamp(roughnessFactor * r / pfRoughMean, 0.02, 1.0);
+  }`,
+  // Carbon samples a luminance MASK (raw, not sRGB-decoded: physical.js) and
+  // modulates around the texture's own mean (0.171; its spread is ~0.06), so a
+  // mipmapped far swatch keeps its preset colour and the weave reads at full
+  // contrast up close.
+  carbon: `
+  {
+    vec3 t = pfTriplanar(pfPatternMap, vPfObjPos, vPfObjNormal, pfPatternScale);
+    float l = dot(t, vec3(0.2126, 0.7152, 0.0722));
+    float n = clamp((l - 0.171) / 0.06, -1.0, 1.0);
+    diffuseColor.rgb *= 1.0 + n * 0.75;
+    roughnessFactor = clamp(roughnessFactor - n * 0.2, 0.0, 1.0);
+  }`,
+  concrete: `
+  {
+    vec3 t = pfTriplanar(pfPatternMap, vPfObjPos, vPfObjNormal, pfPatternScale);
+    diffuseColor.rgb *= t * 1.4;
+  }`,
+};
+
+// Per-kind NORMAL perturbation, injected after <normal_fragment_maps> (where the
+// view-space \`normal\` is final). Layer lines are a procedural normal map: each
+// layer is a round bead, so across one layer the surface normal swings from
+// facing down (bottom of the bead) through straight out to facing up, along
+// the print direction projected onto the surface. Faces parallel to the layers
+// (tops and bottoms) get no ridges, as on a real print. Same fwidth fade as the
+// colour bands, so far-away layers don't alias.
+const FRAG_NORMAL = {
+  "layer-lines": `
+  {
+    float h = (pfPrintFrame * vec4(vPfObjPos, 1.0)).z / pfPatternScale;
+    float aa = 1.0 - smoothstep(0.16, 0.4, fwidth(h));
+    float t = fract(h) * 2.0 - 1.0;                       // -1 at a seam, 0 bead crest, 1 next seam
+    float slope = clamp(t / sqrt(max(1.0 - t * t, 0.04)), -3.0, 3.0);
+    vec3 up = normalize(vPfPrintUpView);
+    // NOT normalised: its length is how steeply the surface cuts across the
+    // layers (1 on a vertical wall, 0 on a face parallel to them), so ridges fade
+    // out on tops and bottoms. Normalising it once made a flat top pick up a
+    // full-strength tilt in a direction set by rounding noise, flipping sign
+    // wherever the face sat on a layer boundary — a visible patch.
+    vec3 along = up - normal * dot(normal, up);
+    normal = normalize(normal + along * slope * 0.35 * aa);
+  }`,
+  // Wood replaces the view-space normal with its triplanar normal map, built in
+  // object space and carried to view space through the normal matrix. A
+  // double-sided back face is flipped the way <normal_fragment_begin> flips it.
+  wood: `
+  {
+    vec3 pfObjN = pfTriplanarNormal(vPfObjPos, normalize(vPfObjNormal), pfPatternScale);
+    normal = normalize(mat3(vPfNmX, vPfNmY, vPfNmZ) * pfObjN);
+    #ifdef DOUBLE_SIDED
+      normal *= faceDirection;
+    #endif
+  }`,
+};
+
+export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1 } = {}) {
+  if (!kind || !FRAG_BODY[kind]) return material;
+  const wood = kind === "wood";
+  const uniforms = {
+    pfPatternScale: { value: scale },
+    pfPrintFrame: { value: new THREE.Matrix4().fromArray(printFrame ?? new THREE.Matrix4().toArray()) },
+    pfPatternMap: { value: texture ?? null },
+    ...(wood ? {
+      pfNormalMap: { value: normalMap ?? null },
+      pfRoughMap: { value: roughnessMap ?? null },
+      pfRoughMean: { value: roughnessMean },
+      pfNormalStrength: { value: normalScale },
+    } : {}),
+  };
+  material.userData.patternUniforms = uniforms;
+  material.onBeforeCompile = (shader) => {
+    Object.assign(shader.uniforms, uniforms);
+    shader.vertexShader = shader.vertexShader
+      .replace("#include <common>", `#include <common>\n${VERT_DECL}${wood ? VERT_DECL_NM : ""}`)
+      .replace("#include <begin_vertex>", `#include <begin_vertex>\n${VERT_BODY}${wood ? VERT_BODY_NM : ""}`);
+    shader.fragmentShader = shader.fragmentShader
+      .replace("#include <common>", `#include <common>\n${FRAG_DECL}${wood ? FRAG_DECL_WOOD : ""}`)
+      .replace("#include <roughnessmap_fragment>", `#include <roughnessmap_fragment>\n${FRAG_BODY[kind]}`)
+      .replace("#include <normal_fragment_maps>", `#include <normal_fragment_maps>\n${FRAG_NORMAL[kind] ?? ""}`);
+  };
+  material.customProgramCacheKey = () => `pf-pattern:${kind}`;
+  material.needsUpdate = true;
+  return material;
+}
+
+// Brush frame for anisotropic (brushed) metal, chosen PER PIXEL. three follows the
+// tangent frame `tbn`; built from per-vertex data it interpolates across each
+// triangle, so wherever the brush direction has to turn (it must, somewhere, on
+// any closed part) the turn followed the triangulation — a jagged staircase across
+// a fillet corner's small facets. Here the box-projection rule (brush along object
+// X, or along Y where X dominates the normal) runs on the interpolated object
+// normal in the fragment, so the turn lands on the smooth |nx| = max(|ny|,|nz|)
+// contour instead. The frame is rebuilt from the final shading `normal`, just
+// before <lights_physical_fragment> reads it. Composes with a pattern's own
+// injection (applied first) rather than replacing it.
+const BRUSH_VERT_DECL = "varying vec3 vPfBrushN;\nvarying vec3 vPfBrushNmX;\nvarying vec3 vPfBrushNmY;\nvarying vec3 vPfBrushNmZ;\n";
+const BRUSH_VERT_BODY = "vPfBrushN = normal;\nvPfBrushNmX = normalMatrix[0];\nvPfBrushNmY = normalMatrix[1];\nvPfBrushNmZ = normalMatrix[2];\n";
+const BRUSH_FRAG_DECL = "varying vec3 vPfBrushN;\nvarying vec3 vPfBrushNmX;\nvarying vec3 vPfBrushNmY;\nvarying vec3 vPfBrushNmZ;\n";
+const BRUSH_FRAG_BODY = `
+  #ifdef USE_ANISOTROPY
+  {
+    vec3 pfN = normalize(vPfBrushN);
+    vec3 pfA = abs(pfN);
+    vec3 pfAxis = (pfA.x > pfA.y && pfA.x > pfA.z) ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0);
+    vec3 pfT = mat3(vPfBrushNmX, vPfBrushNmY, vPfBrushNmZ) * (pfAxis - pfN * dot(pfAxis, pfN));
+    pfT = pfT - normal * dot(normal, pfT);
+    if (dot(pfT, pfT) > 1e-12) {
+      pfT = normalize(pfT);
+      tbn[0] = pfT;
+      tbn[1] = cross(normal, pfT);
+    }
+  }
+  #endif
+`;
+
+export function applyBrushFrame(material) {
+  const prev = material.onBeforeCompile;
+  const prevKey = material.customProgramCacheKey;
+  material.onBeforeCompile = (shader, renderer) => {
+    prev?.call(material, shader, renderer);
+    shader.vertexShader = shader.vertexShader
+      .replace("#include <common>", `#include <common>\n${BRUSH_VERT_DECL}`)
+      .replace("#include <begin_vertex>", `#include <begin_vertex>\n${BRUSH_VERT_BODY}`);
+    shader.fragmentShader = shader.fragmentShader
+      .replace("#include <common>", `#include <common>\n${BRUSH_FRAG_DECL}`)
+      .replace("#include <lights_physical_fragment>", `${BRUSH_FRAG_BODY}\n#include <lights_physical_fragment>`);
+  };
+  const base = prevKey && prevKey !== THREE.Material.prototype.customProgramCacheKey ? prevKey.call(material) : "";
+  material.customProgramCacheKey = () => `${base}|pf-brush`;
+  material.needsUpdate = true;
+  return material;
+}

package/src/framework/materials/physical.js

@@ -0,0 +1,88 @@
+// src/framework/materials/physical.js
+// three.js materials from resolved library data. The CAD half keeps the viewer's
+// MeshStandardMaterial and only swaps its numbers; the realistic half (Task 8)
+// builds MeshPhysicalMaterial. Both read resolve.js, so the two modes can never
+// disagree about which preset a sub-part is.
+import * as THREE from "three";
+import { cadAppearance, resolveMaterial } from "./resolve.js";
+import { applyBrushFrame, applyPattern } from "./patterns.js";
+import { PATTERN_TEXTURES } from "./assets.js";
+
+const APPEARANCE_KEYS = ["color", "opacity", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", "anisotropy", "textureScale"];
+const hasAppearance = (display) => !!display && APPEARANCE_KEYS.some((k) => display[k] != null);
+
+export function buildCadMaterial(display, base) {
+  if (!hasAppearance(display)) return base;
+  const a = cadAppearance(display);
+  const m = base.clone();
+  m.color = new THREE.Color(a.color);
+  m.metalness = a.metalness;
+  m.roughness = a.roughness;
+  if (a.opacity < 1) { m.transparent = true; m.opacity = a.opacity; m.depthWrite = false; }
+  return m;
+}
+
+// Realistic-mode material. `loadTexture(fileName)` is injected (the viewer owns
+// a caching TextureLoader), so this stays unit-testable without a network.
+export function buildPhysicalMaterial(display, opts = {}) {
+  const m = buildPhysical(display, opts);
+  // brushed metal picks its brush direction per pixel (patterns.js applyBrushFrame)
+  return m.userData.pfAnisotropic ? applyBrushFrame(m) : m;
+}
+
+function buildPhysical(display, { printFrame, loadTexture } = {}) {
+  const { params, tinted } = resolveMaterial(display);
+  const set = params.textures;
+  // A textured preset's colour map carries its own colour; the preset `color` is
+  // only its average (for CAD and 3MF). So the material starts white and an
+  // explicit `color` tints the map.
+  const base = set?.color && !tinted ? 0xffffff : params.color;
+  const m = new THREE.MeshPhysicalMaterial({
+    color: new THREE.Color(base),
+    metalness: params.metalness,
+    roughness: params.roughness,
+    clearcoat: params.clearcoat,
+    clearcoatRoughness: params.clearcoatRoughness,
+    transmission: params.transmission,
+    thickness: params.thickness,
+    ior: params.ior,
+    anisotropy: params.anisotropy,
+    envMapIntensity: params.envIntensity,
+    specularIntensity: params.specularIntensity,
+  });
+  if (params.opacity < 1) { m.transparent = true; m.opacity = params.opacity; m.depthWrite = false; }
+  m.userData.pfAnisotropic = params.anisotropy > 0;
+  if (!loadTexture) {
+    applyPattern(m, { kind: params.pattern, scale: params.textureScale, printFrame });
+    return m;
+  }
+  if (set) {
+    // A full PBR set: colour decoded as sRGB, normal and roughness are data.
+    const load = (file, colorSpace) => {
+      if (!file) return undefined;
+      const t = loadTexture(file);
+      t.wrapS = t.wrapT = THREE.RepeatWrapping;
+      t.colorSpace = colorSpace;
+      return t;
+    };
+    applyPattern(m, {
+      kind: params.pattern, scale: params.textureScale, printFrame,
+      texture: load(set.color, THREE.SRGBColorSpace),
+      normalMap: load(set.normal, THREE.NoColorSpace),
+      roughnessMap: load(set.roughness, THREE.NoColorSpace),
+      roughnessMean: set.roughnessMean,
+      normalScale: set.normalScale,
+    });
+    return m;
+  }
+  const textureFile = PATTERN_TEXTURES[params.pattern];
+  const texture = textureFile ? loadTexture(textureFile) : undefined;
+  // The carbon texture is a luminance mask, read raw; decoding it as sRGB
+  // crushed its contrast to nothing. Concrete is a colour map.
+  if (texture) {
+    texture.wrapS = texture.wrapT = THREE.RepeatWrapping;
+    texture.colorSpace = params.pattern === "concrete" ? THREE.SRGBColorSpace : THREE.NoColorSpace;
+  }
+  applyPattern(m, { kind: params.pattern, scale: params.textureScale, printFrame, texture });
+  return m;
+}

package/src/framework/materials/presets.js

@@ -0,0 +1,89 @@
+// src/framework/materials/presets.js
+// The material library: plain data, deliberately three-free and DOM-free so lint,
+// the worker's 3MF writer and the docs parity test can all read it (see
+// test/lint-purity.test.js and test/worker-layering.test.js). The viewer turns a
+// record into a three.js material in physical.js; nothing here knows about three.
+//
+// Metal base colours are measured reflectance (F0) from physicallybased.info,
+// converted to sRGB. Adding a preset is one record here plus a look at the
+// contact sheet (materials.html) in every environment.
+
+export const DEFAULT_PRESET_ID = "default";
+
+const P = (id, label, category, use, fields) => ({ id, label, category, use, tintable: false, ...fields });
+
+export const PRESETS = {
+  // The viewer's look before this library existed. Not documented as a choice:
+  // it is what a sub-part with no `material` renders as.
+  default: P("default", "Default", "default", "The viewer's neutral blue-grey, used when a sub-part names no material.",
+    { color: 0x9fb4cc, metalness: 0.25, roughness: 0.55 }),
+
+  "machined-aluminum": P("machined-aluminum", "Machined aluminium", "aluminium", "Bare CNC-milled aluminium, fine tool marks, satin sheen.",
+    { color: 0xf5f6f6, metalness: 1, roughness: 0.32 }),
+  "brushed-aluminum": P("brushed-aluminum", "Brushed aluminium", "aluminium", "Directionally brushed aluminium panels and enclosures.",
+    { color: 0xf5f6f6, metalness: 1, roughness: 0.38, anisotropy: 0.7 }),
+  "anodized-aluminum": P("anodized-aluminum", "Anodized aluminium", "aluminium", "Dyed anodized aluminium; tint with `color` (e.g. red, black, blue).",
+    { color: 0xb9bcc0, metalness: 1, roughness: 0.3, clearcoat: 0.4, clearcoatRoughness: 0.25, tintable: true }),
+  "bead-blasted-aluminum": P("bead-blasted-aluminum", "Bead-blasted aluminium", "aluminium", "Matte, even-textured aluminium (laptop-shell finish).",
+    { color: 0xe8e9ea, metalness: 1, roughness: 0.62 }),
+
+  "brushed-stainless": P("brushed-stainless", "Brushed stainless steel", "steel", "Brushed 304 stainless: kitchen, marine and fastener hardware.",
+    { color: 0xc4c5c6, metalness: 1, roughness: 0.34, anisotropy: 0.6 }),
+  "polished-chrome": P("polished-chrome", "Polished chrome", "steel", "Mirror chrome plating; shows the environment strongly.",
+    { color: 0xcacbcc, metalness: 1, roughness: 0.05 }),
+  "black-oxide-steel": P("black-oxide-steel", "Black-oxide steel", "steel", "Blackened steel tooling and fasteners with a slight oily sheen.",
+    { color: 0x2c2d30, metalness: 1, roughness: 0.45 }),
+  "cast-iron": P("cast-iron", "Cast iron", "steel", "Raw sand-cast iron: dark, rough and matte.",
+    { color: 0x6d6b69, metalness: 1, roughness: 0.78 }),
+  titanium: P("titanium", "Titanium", "steel", "Bare titanium: slightly warm grey, satin.",
+    { color: 0xc1bab1, metalness: 1, roughness: 0.35 }),
+
+  brass: P("brass", "Brass", "warm-metal", "Yellow brass fittings and decorative hardware.",
+    { color: 0xf8dc82, metalness: 1, roughness: 0.28 }),
+  copper: P("copper", "Copper", "warm-metal", "Bare copper: busbars, heat sinks, decorative parts.",
+    { color: 0xfad0c0, metalness: 1, roughness: 0.3 }),
+  bronze: P("bronze", "Bronze", "warm-metal", "Cast bronze bushings and sculpture.",
+    { color: 0xd9a86c, metalness: 1, roughness: 0.42 }),
+
+  "powder-coat": P("powder-coat", "Powder coat", "coating", "Durable textured paint over metal; tint with `color`.",
+    { color: 0x303236, metalness: 0, roughness: 0.55, clearcoat: 0.15, clearcoatRoughness: 0.5, tintable: true }),
+  "painted-metal": P("painted-metal", "Painted metal", "coating", "Glossy enamel or automotive-style paint; tint with `color`.",
+    { color: 0xb3261e, metalness: 0, roughness: 0.4, clearcoat: 1, clearcoatRoughness: 0.08, tintable: true }),
+
+  "pla-print": P("pla-print", "PLA print", "print", "FDM-printed PLA with visible layer lines; tint with `color`.",
+    { color: 0xe8e4da, metalness: 0, roughness: 0.55, envIntensity: 0.6, specularIntensity: 0.5, pattern: "layer-lines", textureScale: 0.2, tintable: true }),
+  "petg-print": P("petg-print", "PETG print", "print", "FDM-printed PETG: glossier than PLA, visible layers; tint with `color`.",
+    { color: 0x2d6cdf, metalness: 0, roughness: 0.32, envIntensity: 0.7, specularIntensity: 0.7, pattern: "layer-lines", textureScale: 0.2, tintable: true }),
+  "resin-print": P("resin-print", "Resin print", "print", "SLA/MSLA resin print: smooth, faintly waxy; tint with `color`.",
+    { color: 0x8a8f96, metalness: 0, roughness: 0.35, clearcoat: 0.2, clearcoatRoughness: 0.3, tintable: true }),
+  "nylon-sls": P("nylon-sls", "Nylon SLS", "print", "Powder-bed nylon: matte, grainy, usually white or dyed black.",
+    { color: 0xf0eee8, metalness: 0, roughness: 0.85, pattern: "sls-grain", textureScale: 0.15, tintable: true }),
+
+  "abs-plastic": P("abs-plastic", "ABS plastic", "plastic", "Injection-moulded ABS housings and knobs; tint with `color`.",
+    { color: 0x1c1d20, metalness: 0, roughness: 0.42, tintable: true }),
+  "clear-acrylic": P("clear-acrylic", "Clear acrylic", "plastic", "Transparent PMMA/polycarbonate windows and covers; tint for coloured acrylic.",
+    { color: 0xffffff, metalness: 0, roughness: 0.04, transmission: 1, thickness: 3, ior: 1.49, tintable: true }),
+  rubber: P("rubber", "Rubber", "plastic", "Matte elastomer: gaskets, feet, grips; tint with `color`.",
+    { color: 0x1a1a1a, metalness: 0, roughness: 0.9, tintable: true }),
+
+  // Wood is a full PBR texture set (colour, normal, roughness — Poly Haven scans,
+  // assets/SOURCES.md), projected triplanar in object space (patterns.js).
+  // textureScale is one tile in mm. It is NOT the scans' stated size (1.83 m oak,
+  // 2 m walnut): a 1K map spread that wide is ~2 mm a texel, so a hand-sized part
+  // showed blurred blotches and no grain. 250/400 mm keep the grain crisp at part
+  // scale and still read as plausible figure (checked in the contact sheet). `color` is the
+  // texture's average colour: what the CAD view and a 3MF export show. In realistic
+  // mode the texture carries the colour itself; an explicit `color` tints it.
+  // `roughnessMean` is the roughness map's mean, so the preset `roughness` (or an
+  // override) sets the AVERAGE roughness and the map only varies it. `normalScale`
+  // strengthens the normal map: these scans' tangent normals barely leave +Z (a
+  // ~1% tilt), which reads as flat under an environment map.
+  oak: P("oak", "Oak", "natural", "Light oak with open grain.",
+    { color: 0xa17e57, metalness: 0, roughness: 0.65, pattern: "wood", textureScale: 250,
+      textures: { color: "pattern-oak-color.jpg", normal: "pattern-oak-normal.jpg", roughness: "pattern-oak-rough.jpg", roughnessMean: 0.53, normalScale: 2.5 } }),
+  walnut: P("walnut", "Walnut", "natural", "Dark oiled walnut.",
+    { color: 0x5d2a18, metalness: 0, roughness: 0.5, clearcoat: 0.3, clearcoatRoughness: 0.4, pattern: "wood", textureScale: 400,
+      textures: { color: "pattern-walnut-color.jpg", normal: "pattern-walnut-normal.jpg", roughness: "pattern-walnut-rough.jpg", roughnessMean: 0.628, normalScale: 3 } }),
+  "carbon-fiber": P("carbon-fiber", "Carbon fibre", "natural", "2x2 twill carbon fibre under clear coat.",
+    { color: 0x1b1c1e, metalness: 0.2, roughness: 0.35, clearcoat: 1, clearcoatRoughness: 0.05, pattern: "carbon", textureScale: 48 }),
+};

package/src/framework/materials/print-bed.js

@@ -0,0 +1,169 @@
+// src/framework/materials/print-bed.js
+// The print-bed environment's ground: not a disc fading into the backdrop but
+// a real build plate — a rounded, square PEI sheet of a standard size, cut out
+// of nothing, with white markings printed on it: a millimetre ruler along the
+// left and back edges, the partforge wordmark in the front-left corner, the
+// plate's own size in the front-right, and a lift tab with diagonal sides off
+// the middle of the front edge. Like the disc, it comes to the
+// part (centred under its footprint) and never moves it.
+import * as THREE from "three";
+
+// Common square bed sizes, smallest first; a footprint past the last rounds up
+// to the next 50 mm.
+export const BED_SIZES_MM = [180, 220, 256, 350];
+const MARGIN_MM = 16; // clear plate kept around the footprint when picking a size
+const THICKNESS_MM = 2.5;
+const CORNER_MM = 6;
+// The lift tab on the front edge: wide where it meets the plate, narrower at
+// its tip, so its two sides run diagonally.
+const TAB_BASE_MM = 132;
+const TAB_TIP_MM = 96;
+const TAB_DEPTH_MM = 9;
+
+export function bedSizeFor(footprintMm) {
+  const need = footprintMm + MARGIN_MM * 2;
+  return BED_SIZES_MM.find((s) => s >= need) ?? Math.ceil(need / 50) * 50;
+}
+
+function plateGeometry(size) {
+  const h = size / 2, r = CORNER_MM;
+  const shape = new THREE.Shape();
+  // Shape y = -h is the FRONT edge (it lands at +Z once laid flat), and the
+  // lift tab sticks out of its middle: a trapezoid with diagonal sides.
+  const tb = TAB_BASE_MM / 2, tt = TAB_TIP_MM / 2, td = TAB_DEPTH_MM;
+  shape.moveTo(-h + r, -h);
+  shape.lineTo(-tb, -h); shape.lineTo(-tt, -h - td); shape.lineTo(tt, -h - td); shape.lineTo(tb, -h);
+  shape.lineTo(h - r, -h); shape.quadraticCurveTo(h, -h, h, -h + r);
+  shape.lineTo(h, h - r); shape.quadraticCurveTo(h, h, h - r, h);
+  shape.lineTo(-h + r, h); shape.quadraticCurveTo(-h, h, -h, h - r);
+  shape.lineTo(-h, -h + r); shape.quadraticCurveTo(-h, -h, -h + r, -h);
+  // Extruded along +Z then laid flat: the top cap ends up at y = 0, the plate
+  // hangs below it, and the caps' UVs are shape coordinates — millimetres.
+  const g = new THREE.ExtrudeGeometry(shape, { depth: THICKNESS_MM, bevelEnabled: false, curveSegments: 6 });
+  g.rotateX(-Math.PI / 2);
+  g.translate(0, -THICKNESS_MM, 0);
+  return g;
+}
+
+function defaultCanvas(w, h) {
+  if (typeof OffscreenCanvas !== "undefined") return new OffscreenCanvas(w, h);
+  if (typeof document !== "undefined") return Object.assign(document.createElement("canvas"), { width: w, height: h });
+  return null;
+}
+
+// Draws the markings for a plate `size` mm square onto a transparent canvas
+// (top of the canvas = back of the bed). Returns null where there is no 2D
+// canvas (tests, a worker): the plate is then just unmarked PEI.
+export function drawBedMarkings(size, createCanvas = defaultCanvas) {
+  const px = 2048;
+  const canvas = createCanvas(px, px);
+  const ctx = canvas?.getContext?.("2d");
+  if (!ctx) return null;
+  const k = px / size; // pixels per millimetre
+  const ink = "rgba(255,255,255,0.88)";
+  const mono = (mm, weight = 600) => `${weight} ${Math.round(mm * k)}px "Geist Mono", ui-monospace, SFMono-Regular, Menlo, monospace`;
+  ctx.clearRect(0, 0, px, px);
+  ctx.strokeStyle = ink;
+  ctx.fillStyle = ink;
+  ctx.lineCap = "round";
+
+  // Printable-area outline, inset from the edge.
+  const inset = 5;
+  ctx.lineWidth = 0.35 * k;
+  ctx.beginPath();
+  ctx.roundRect(inset * k, inset * k, (size - inset * 2) * k, (size - inset * 2) * k, (CORNER_MM - 2) * k);
+  ctx.stroke();
+
+  // Ruler: a tick every 10 mm, a longer numbered one every 50 mm, along the
+  // back edge (left to right) and the left edge (front to back), measured
+  // from the front-left corner the way a slicer's bed is.
+  const ruler = inset + 1;
+  ctx.font = mono(3.2, 500);
+  for (let mm = 10; mm < size - inset; mm += 10) {
+    const major = mm % 50 === 0;
+    const len = (major ? 4 : 2) * k;
+    ctx.lineWidth = (major ? 0.45 : 0.3) * k;
+    ctx.beginPath(); // back edge: x = mm
+    ctx.moveTo(mm * k, ruler * k); ctx.lineTo(mm * k, ruler * k + len);
+    ctx.stroke();
+    ctx.beginPath(); // left edge: z = mm from the front
+    ctx.moveTo(ruler * k, (size - mm) * k); ctx.lineTo(ruler * k + len, (size - mm) * k);
+    ctx.stroke();
+    if (!major) continue;
+    ctx.textAlign = "center"; ctx.textBaseline = "top";
+    ctx.fillText(String(mm), mm * k, ruler * k + len + 1 * k);
+    ctx.textAlign = "left"; ctx.textBaseline = "middle";
+    ctx.fillText(String(mm), ruler * k + len + 1 * k, (size - mm) * k);
+  }
+
+  // A small centre cross.
+  ctx.lineWidth = 0.35 * k;
+  const c = (size / 2) * k, arm = 3 * k;
+  ctx.beginPath();
+  ctx.moveTo(c - arm, c); ctx.lineTo(c + arm, c);
+  ctx.moveTo(c, c - arm); ctx.lineTo(c, c + arm);
+  ctx.stroke();
+
+  // Front strip: the wordmark in the left corner, the plate's size in the
+  // right, leaving the middle clear for the lift tab.
+  const front = (size - inset - 7) * k;
+  ctx.textBaseline = "middle";
+  ctx.font = mono(Math.min(8, size * 0.03));
+  ctx.textAlign = "left";
+  ctx.fillText("partforge", (inset + 5) * k, front);
+  ctx.textAlign = "right";
+  ctx.font = mono(Math.min(5, size * 0.02), 500);
+  ctx.fillText(`${size} × ${size} mm`, (size - inset - 5) * k, front);
+  return canvas;
+}
+
+// `pei` is the plate's surface material (the PEI colour + roughness maps with
+// UVs in millimetres, repeat 1/tileMm); the rest is built and owned here.
+export function createPrintBed({ pei, tileMm, createCanvas }) {
+  const group = new THREE.Group();
+  const edge = new THREE.MeshStandardMaterial({ color: 0x2a2b2d, metalness: 0.6, roughness: 0.45 });
+  const plate = new THREE.Mesh(new THREE.BufferGeometry(), [pei, edge]);
+  const inkMat = new THREE.MeshStandardMaterial({
+    transparent: true, roughness: 0.6, metalness: 0,
+    polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1,
+  });
+  const ink = new THREE.Mesh(new THREE.PlaneGeometry(1, 1).rotateX(-Math.PI / 2), inkMat);
+  ink.visible = false;
+  group.add(plate, ink);
+  group.renderOrder = -1;
+  let size = 0;
+  let inkTex = null;
+
+  function setSize(next) {
+    if (next === size) return;
+    size = next;
+    plate.geometry.dispose();
+    plate.geometry = plateGeometry(size);
+    for (const t of [pei.map, pei.roughnessMap]) t?.repeat.set(1 / tileMm, 1 / tileMm);
+    inkTex?.dispose();
+    inkTex = null;
+    const canvas = drawBedMarkings(size, createCanvas);
+    if (canvas) {
+      inkTex = new THREE.CanvasTexture(canvas);
+      inkTex.colorSpace = THREE.SRGBColorSpace;
+      inkTex.anisotropy = 8;
+    }
+    inkMat.map = inkTex;
+    inkMat.needsUpdate = true;
+    ink.visible = !!inkTex;
+    ink.scale.set(size, 1, size);
+  }
+
+  return {
+    object: group,
+    get sizeMm() { return size; },
+    place({ y, centerX = 0, centerZ = 0, footprintMm }) {
+      setSize(bedSizeFor(footprintMm));
+      group.position.set(centerX, y - 0.01, centerZ);
+    },
+    dispose() {
+      plate.geometry.dispose(); ink.geometry.dispose();
+      edge.dispose(); inkMat.dispose(); inkTex?.dispose();
+    },
+  };
+}

package/src/framework/materials/print-frame.js

@@ -0,0 +1,18 @@
+// The frame 3D-print layer lines are drawn in. Delivered display meshes carry
+// the DISPLAY pose (place(..., {purpose:"display"})); the part is printed in the
+// EXPORT pose. partforge already requires the two to differ by a rigid motion
+// (lint place-not-rigid), and the geometry-free pose probe reports each as a
+// list of rigid steps — so the display→export map is E · D⁻¹, with no geometry.
+// Three-free and DOM-free: the pose probe and pose.js are pure.
+import { probeSubPartPose } from "../pose-probe-core.js";
+import { poseDelta } from "../geometry/pose.js";
+
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+
+export function printFrameMatrix(subPart, { view, p, d }) {
+  if (!subPart?.place) return [...IDENTITY];
+  const disp = probeSubPartPose(subPart, { view, purpose: "display", p, d });
+  const exp = probeSubPartPose(subPart, { view, purpose: "export", p, d });
+  if (!disp.trusted || !exp.trusted || disp.baseHash !== exp.baseHash) return [...IDENTITY];
+  return poseDelta(exp.pose, disp.pose);
+}