partforge 0.121.1 → 0.122.0

package/docs/AUTHORING-PARTS.md

@@ -69,7 +69,7 @@ A part is a default-exported object. Full shape (optional fields marked `?`):
 
 ```js
 export default {
-  meta: { title, units, background? },     // title string; units e.g. "mm"; background = 0xRRGGBB scene colour
+  meta: { title, units, background?, environment? },     // title string; units e.g. "mm"; background = 0xRRGGBB scene colour
   parameters,                              // the control-panel schema (array of sections — see below)
   defaults,                                // flat { paramKey: value } — seeds params + control values
   fonts?,                                  // { name: source } — or (p) => ({ name: source }) when a control drives the typeface
@@ -83,7 +83,7 @@ export default {
       place?: (solid, { view, purpose, p, d }) => Solid,   // optional reposition; default identity
       views,                               // string[] — which views show this sub-part
       enabled?: (p) => boolean,            // optional — gate a conditional sub-part
-      display?: { color?, opacity? },      // optional viewer-only override (0xRRGGBB / 0..1) — e.g. a reference/ghost part
+      display?: { color?, opacity?, material?, …overrides }, // viewer-only appearance — see "Materials and appearance"
       export?: { name },                   // filename/object name on export; defaults to the key
       reference?: string,                  // name of a declared import — measure() computes a deviation fact against it (see below)
     },
@@ -294,6 +294,97 @@ and asks for the existing positional view argument
 
 ---
 
+## Materials and appearance
+
+A sub-part's `display` block says how it LOOKS. Appearance never changes
+geometry, exports (other than 3MF colour, below), `measure` or `verify`, and a
+mistake in it never fails a build — lint warns and the viewer falls back.
+
+```js
+parts: {
+  body:   { build: …, display: { material: "anodized-aluminum", color: 0xb3261e } },
+  knob:   { build: …, display: { material: "abs-plastic", color: 0x111111, roughness: 0.25 } },
+  gasket: { build: …, display: { material: "rubber" } },
+},
+meta: { title: "…", units: "mm", environment: "studio" },
+```
+
+- `material` — a preset id from the table below. Without one the sub-part keeps
+  the default look.
+- `color` — the base colour (`0xRRGGBB`). With a preset it is the TINT. Presets
+  marked tintable are normally coloured this way (anodizing, plastic, paint);
+  the others have an intrinsic colour (brass) but still accept one.
+- Overrides — each clamped to its range: `roughness` (0–1), `metalness` (0–1),
+  `clearcoat` (0–1), `clearcoatRoughness` (0–1), `anisotropy` (0–1), `textureScale` (0.01–1000).
+  Transmission, index of refraction, sheen and iridescence come only from a preset.
+- `opacity` — unchanged: a ghost stays a ghost and casts no shadow.
+- **One material per sub-part.** Something that needs two finishes (a knurled
+  grip in rubber on an aluminium body) is two sub-parts.
+
+**Where it shows.** The CAD view (with feature lines) shows each material's
+colour, flattened so dark materials stay readable. **Realistic** mode — the
+viewer's toggle — shows the full material under environment lighting, with a
+ground and soft shadow and no feature lines. The part never moves when the
+mode changes.
+
+**3D-print layer lines** (`pla-print`, `petg-print`) run perpendicular to the
+**export** pose's +Z — the way the part will be printed, not the way it is
+displayed. If the lines run the wrong way, fix the export pose with `place()`
+(`purpose: "export"`), not the material. Wood, carbon fibre and SLS grain are
+fixed to the sub-part, so they never slide when the camera or an animation
+moves.
+
+**`textureScale` is millimetres, and what it measures depends on the preset's
+pattern** — so a value copied from one preset family is wrong on another (0.2
+on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise):
+
+| Pattern | Presets | `textureScale` means | Default |
+| --- | --- | --- | --- |
+| layer lines | `pla-print`, `petg-print` | layer height | 0.2 |
+| SLS grain | `nylon-sls` | grain size | 0.15 |
+| wood | `oak`, `walnut` | size of one texture tile (the grain repeats every this many mm) | 250 (`oak`), 400 (`walnut`) |
+| carbon weave | `carbon-fiber` | size of one texture tile | 48 |
+
+Presets without a pattern ignore it.
+
+**3MF export** carries each sub-part's colour (its `color`, else its preset's
+colour), so a multi-colour print opens in a slicer already split and coloured.
+A part with no `color` or `material` exports exactly as before.
+
+| Preset | Name | Tintable | Use |
+| --- | --- | --- | --- |
+| `machined-aluminum` | Machined aluminium | — | Bare CNC-milled aluminium, fine tool marks, satin sheen. |
+| `brushed-aluminum` | Brushed aluminium | — | Directionally brushed aluminium panels and enclosures. |
+| `anodized-aluminum` | Anodized aluminium | yes | Dyed anodized aluminium; tint with `color` (e.g. red, black, blue). |
+| `bead-blasted-aluminum` | Bead-blasted aluminium | — | Matte, even-textured aluminium (laptop-shell finish). |
+| `brushed-stainless` | Brushed stainless steel | — | Brushed 304 stainless: kitchen, marine and fastener hardware. |
+| `polished-chrome` | Polished chrome | — | Mirror chrome plating; shows the environment strongly. |
+| `black-oxide-steel` | Black-oxide steel | — | Blackened steel tooling and fasteners with a slight oily sheen. |
+| `cast-iron` | Cast iron | — | Raw sand-cast iron: dark, rough and matte. |
+| `titanium` | Titanium | — | Bare titanium: slightly warm grey, satin. |
+| `brass` | Brass | — | Yellow brass fittings and decorative hardware. |
+| `copper` | Copper | — | Bare copper: busbars, heat sinks, decorative parts. |
+| `bronze` | Bronze | — | Cast bronze bushings and sculpture. |
+| `powder-coat` | Powder coat | yes | Durable textured paint over metal; tint with `color`. |
+| `painted-metal` | Painted metal | yes | Glossy enamel or automotive-style paint; tint with `color`. |
+| `pla-print` | PLA print | yes | FDM-printed PLA with visible layer lines; tint with `color`. |
+| `petg-print` | PETG print | yes | FDM-printed PETG: glossier than PLA, visible layers; tint with `color`. |
+| `resin-print` | Resin print | yes | SLA/MSLA resin print: smooth, faintly waxy; tint with `color`. |
+| `nylon-sls` | Nylon SLS | yes | Powder-bed nylon: matte, grainy, usually white or dyed black. |
+| `abs-plastic` | ABS plastic | yes | Injection-moulded ABS housings and knobs; tint with `color`. |
+| `clear-acrylic` | Clear acrylic | yes | Transparent PMMA/polycarbonate windows and covers; tint for coloured acrylic. |
+| `rubber` | Rubber | yes | Matte elastomer: gaskets, feet, grips; tint with `color`. |
+| `oak` | Oak | — | Light oak with open grain. |
+| `walnut` | Walnut | — | Dark oiled walnut. |
+| `carbon-fiber` | Carbon fibre | — | 2x2 twill carbon fibre under clear coat. |
+
+**Environments** (`meta.environment`, default `studio`; viewers can switch):
+`studio` (neutral soft boxes, paper sweep), `workshop` (warm interior, unfinished
+maple table), `print-bed` (a dim, hard-lit enclosure over a standard-size PEI build plate (180, 220, 256 or 350 mm) marked with its size), `outdoor` (overcast sky,
+concrete).
+
+---
+
 ## Geometry: the kernel / `Solid` API
 
 `build` receives a backend-agnostic `kernel` (`k`). It returns and combines `Solid`
@@ -2498,7 +2589,7 @@ stylesheet). `mount` looks up these element IDs:
 | `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` and opens the resolved default (see the "Which view the viewer opens on" rule above) |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
-| `#viewbar` with `#annotate` / `#measure` / `#cutaway` / `#reframe` / `#theme` | optional viewer controls (omit any you don't want) |
+| `#viewbar` with `#annotate` / `#measure` / `#cutaway` / `#reframe` / `#realistic` / `#environment` / `#theme` | optional viewer controls (omit any you don't want) |
 | `#panel` | the full-height controls rail (`class="pf-rail"`); programmatic hosts pass `elements.rail` instead |
 | `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#reframe`/`#theme`. A sibling of `#viewbar`, not a child of it: give it `class="pf-float-rail-toggle"` and it floats at the stage's top right |
 
@@ -2506,6 +2597,17 @@ Copy `demo.html` and change the title, the panel heading, and the `<script src>`
 workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
 `"occt"` for STEP — handled for you).
 
+**`#realistic` (a `<button>`) / `#environment` (an empty `<select>`) are the
+realistic-mode viewbar controls**, resolved by id or as `elements.chrome.realistic`
+/ `elements.chrome.environment`. Both optional and independent: supply `#realistic`
+alone for a bare toggle, or add `#environment` too and `mount` fills it with the
+part's available environments (see "Materials and appearance" above) and keeps it
+in sync — hidden while the view is in CAD mode, showing the environment in effect
+once realistic lands. Omit either and drive `runtime.renderMode` /
+`runtime.environment` from your own UI instead (see below). Both preferences
+persist across reloads the same way the theme does, and are carried in
+`viewerState` (below), which outranks what is stored.
+
 **`#reframe` is supported but no longer shipped.** The framework's own pages dropped
 the button on 2026-08-20: clicking a face, edge or corner on the view cube reframes
 too, so a separate control was one more thing in a crowded bottom-right corner. The
@@ -2660,6 +2762,58 @@ them, and the sketch that gets sent is misaligned, not merely mis-labelled.
 Deliberately unguarded, the same way it's always been free to call
 `setCameraState` during Sketch.
 
+### `runtime.renderMode`, `runtime.environment`, `runtime.renderViews`, `runtime.declaresMaterials`
+
+For an embedder driving realistic mode from its own UI instead of (or in
+addition to) the `#realistic` / `#environment` viewbar controls above:
+
+- `runtime.renderMode` — `{ get(), set(mode), onChange(cb) }` where `mode` is
+  `"cad"` or `"realistic"`. `set()` resolves to the mode actually in effect —
+  `"cad"` if the realistic environment's assets fail to load — and
+  `onChange` receives `{ mode, busy, error }` so a host can show its own
+  loading/error state. Same shape as `runtime.projection`. It drives the live
+  view, and `runtime.captureCurrent()` follows it by default (a "capture from
+  viewer" captures what the user sees). It never changes what an agent sees:
+  `runtime.captureViews()` is always CAD, in either live mode, and a
+  realistic agent render is only ever an explicit
+  `renderViews(…, { renderMode: "realistic" })`.
+- `runtime.captureCurrent({ renderMode })` — pins the showcase capture's look
+  instead of following the live view. `"cad"` always works. `"realistic"` from
+  a CAD view works only once the current environment's assets have loaded
+  (the call is synchronous and can't wait for them); before that it falls
+  back to the live look. Use `renderViews` when realistic must be guaranteed.
+- `runtime.environment` — `{ get(), set(id), onChange(cb), list() }` for the
+  realistic environment (`"studio"` | `"workshop"` | `"print-bed"` |
+  `"outdoor"`, per "Materials and appearance" above). `list()` returns every
+  environment as `[{ id, label }]`, for building your own picker. `set()`
+  resolves to the id actually in effect; a failed switch while realistic is
+  showing reverts to the environment still on screen, and `onChange` hears the
+  revert too.
+- `runtime.declaresMaterials` — `true` when any sub-part names a
+  `display.material`. A part with none still supports realistic mode (every
+  sub-part just renders under the library's `default` look), so use this to
+  decide whether to surface the realistic toggle at all, not whether it works.
+- `await runtime.renderViews(viewNames, { renderMode? })` — the appearance-aware
+  sibling of `runtime.captureViews` (canonical angles, framed to the visible
+  assembly, grid hidden): `{ renderMode: "cad" }` (the default) is exactly
+  `captureViews` — CAD whatever the live view shows — and `{ renderMode: "realistic" }` borrows the realistic look
+  for the capture — waiting on the chosen environment's assets — **without**
+  switching the live view. Rejects if the realistic assets fail to load.
+
+Both preferences round-trip through `mount()`'s `viewerState`: a
+previous mount's `runtime.getViewerState()` carries `viewerState.renderMode`
+(`"cad"` or `"realistic"`) and, only when the viewer's environment was
+actually CHOSEN rather than merely defaulted from `meta.environment`,
+`viewerState.environment`. `renderMode` reports the mode the user is **headed
+for**, not only the one on screen: a realistic restore or switch that's still
+loading reports `"realistic"`, so a host that remounts on every edit (as an
+embedder applying edits by remounting typically does) doesn't drop the
+in-flight choice — a load that ultimately fails still settles back to
+`"cad"`. Pass `viewerState` back into the next `mount()` call to resume both
+where the previous mount left them; omit it on a first mount and the viewer
+restores its own persisted choice instead, the same way it does for the
+camera and projection.
+
 ### The annotation payload's camera block
 
 `onAnnotationSend(payload)` receives a `camera` block in two frames — `world`
@@ -3121,6 +3275,13 @@ motion — translate/rotate — never a reshape) (both errors). An untrusted pro
 nothing either way and stays silent, matching `animation-track-rebuilds`'s own
 trust handling.
 
+**Appearance** (all warnings) — `unknown-material` (a `display.material` the
+library does not know; the viewer shows the default look), `unknown-environment`
+(`meta.environment` not known; realistic mode uses `studio`),
+`material-key-unknown` (a `display` key that is not colour, opacity, material
+or one of the six overrides; ignored), `material-override-clamped` (an override
+outside its range, or not a number; clamped).
+
 **Geometry imports** — `import-unknown-name` (a build calls `k.import` with a
 name the part's `imports` field doesn't declare — this throws at build time;
 lint reaches it in microseconds instead), `import-mesh-on-occt` (a declared

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.121.1",
+  "version": "0.122.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -132,11 +132,13 @@
     "@eslint/js": "^10.0.1",
     "@fontsource-variable/geist": "^5.3.0",
     "@fontsource-variable/geist-mono": "^5.3.0",
+    "@monogrid/gainmap-js": "^3.4.0",
     "eslint": "^10.10.0",
     "globals": "^17.12.0",
     "happy-dom": "^20.10.6",
     "knip": "^6.35.1",
     "playwright": "^1.49.0",
+    "sharp": "^0.35.4",
     "typescript": "^5.9.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"

package/src/app-materials.js

@@ -0,0 +1,23 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import materialSwatchesPart from "./parts/material-swatches.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only contact sheet app for the material library (parts/material-swatches.js).
+// Identical wiring to app.js — the only thing that differs per part is which
+// definition you import and which worker entry you point at. `npm run dev`, then
+// open /materials.html. Not part of the production build — check materials.html
+// by eye after any preset or shader change (see AGENTS.md "Architecture").
+// Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
+// the embedding contract (runtime.captureCurrent) the way an embedder would.
+window.__pfRuntime = mount(materialSwatchesPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./materials-worker.js", import.meta.url), { type: "module", name }),
+  onAnnotationSend: (payload) => {
+    window.__pfLastAnnotation = payload;
+    console.log("annotation payload", payload);
+  },
+});

package/src/framework/app.css

@@ -476,7 +476,7 @@ button.action:disabled { opacity: .5; cursor: default; }
 /* keyboard focus ring shared across the panel's interactive controls */
 .seg button:focus-visible, select.preset:focus-visible, .dl-row button:focus-visible,
 button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible, #viewbar button:focus-visible,
-.pf-view-select:focus-visible,
+#viewbar select:focus-visible, .pf-view-select:focus-visible,
 .pf-viewcube-toggle:focus-visible, .pf-float-rail-toggle:focus-visible, .pf-sketch-toolbar button:focus-visible {
   outline: none;
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
@@ -595,6 +595,21 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 #viewbar button:disabled:hover { color: var(--pf-muted-2); background: transparent; }
 #viewbar button:hover { color: var(--pf-text); background: var(--pf-surface-2); }
 #viewbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
+/* Realistic view (realistic-controls.js). The toggle is an ordinary viewbar
+   button that pulses while its environment loads; the environment picker is a
+   native <select> — the accessible choice on a phone — dressed as a viewbar
+   button, shown only while realistic. Keyed on `#viewbar select` rather than
+   an id so a host's own element in the pill gets the same look. */
+#viewbar button[data-busy] { animation: pf-busy-pulse .8s ease-in-out infinite alternate; }
+@keyframes pf-busy-pulse { from { opacity: 1; } to { opacity: .45; } }
+@media (prefers-reduced-motion: reduce) { #viewbar button[data-busy] { animation: none; opacity: .6; } }
+#viewbar select {
+  height: 34px; padding: 0 8px; border: 0; border-radius: var(--pf-radius-control);
+  background: transparent; color: var(--pf-muted-2); cursor: pointer;
+  font: inherit; font-size: 13px;
+}
+#viewbar select:hover { color: var(--pf-text); background: var(--pf-surface-2); }
+#viewbar select[hidden] { display: none; }
 
 /* Sketch-mode toolbar: the #viewbar pill idiom, top-centre, owning the mode
    while the viewbar itself is hidden (mount toggles both).

package/src/framework/cutaway.js

@@ -493,6 +493,17 @@ export function createCutaway({
     return true;
   }
 
+  // Swap one sub-part's SOURCE material (realistic mode). The render set
+  // re-derives its clipped clone and cap colour from it and reassigns
+  // mesh.material for the current enabled state.
+  function refreshSubpartMaterial(name, meshMaterial) {
+    if (disposed) return false;
+    const entry = renderSets.get(name);
+    if (!entry) return false;
+    entry.renderSet.refreshSourceMaterial(meshMaterial);
+    return true;
+  }
+
   // Per-frame maintenance while the cutaway is on: the gizmo rescales for the
   // camera, and every visible section re-slices its outline if anything it
   // depends on moved. Both are cheap no-ops when nothing changed.
@@ -581,6 +592,7 @@ export function createCutaway({
     setVisible,
     setEnabled,
     resyncSubpart,
+    refreshSubpartMaterial,
     reset,
     flip,
     getState,

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`.