partforge 0.121.1 → 0.123.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/docs/KERNEL-CONTRACT.md

@@ -406,6 +406,16 @@ are present:
 - `normals` — per-vertex shading normals. Smooth within one surface, hard
   across boolean-cut seams. OCCT ships analytic B-rep normals; Manifold ships
   the policy-aware crease pass (`src/framework/geometry/creased-normals.js`).
+  Fillet bands are analytic on both backends: each Manifold fillet tool registers
+  its rolling-ball spine (`src/framework/geometry/blend-surfaces.js` — a line,
+  circle, point or planar path), and the crease pass shades any smooth group the
+  band takes part in with that exact normal, so a band meets the faces it is
+  tangent to with matching normals (within 0.1° of the true surface on a
+  filleted box — `test/mesh-fillet-normals.test.js`, with its OCCT twin in
+  `test/occt-shading.test.js`). The spine follows the band through later
+  booleans, poses and `label()`. Planar-path bands (rims of extrusions) shade
+  the smooth curve their polyline samples; at a line-to-arc junction in that
+  polyline the normal is off by up to half an arc segment, as before.
 - `edges` — flat feature-edge segment pairs (6 floats per segment). An EMPTY
   array means "this solid has no feature edges"; it is not "unknown". OCCT
   ships true B-rep edges with tangent edges (fillet blends, seam lines)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.121.1",
+  "version": "0.123.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/blend-surfaces.js

@@ -0,0 +1,256 @@
+// Analytic blend-surface descriptors — the exact normal field of a mesh fillet band.
+//
+// A mesh fillet (mesh-fillet.js) is a boolean against tool solids whose curved wall
+// IS the rolling-ball surface. Facet-averaged vertex normals on that wall are only
+// approximately right: one-sided at the band's tangent boundary (half a facet off
+// the face it is tangent to — ~1-2° at preview density), biased by the boolean's
+// uneven fans, and on a coarse corner sphere several degrees off the edge cylinders
+// it meets. Every blend surface is a canal surface — the envelope of a ball rolling
+// along a SPINE — so its exact normal at any point is the direction from the nearest
+// spine point, and the spine is known when the tool is built. A descriptor records
+// that spine:
+//
+//   { kind: "line",   p, d }        straight edge → cylinder (prism tools)
+//   { kind: "circle", c, a, R }     arc edge → torus (revolve / pivot tools); R may
+//                                   be 0 (a sphere about c)
+//   { kind: "point",  c }           sphere (corner patches)
+//   { kind: "path", pts, closed, dirs, f, kf, kd }
+//                                   planar polyline edge (planar sweep tools): pts is
+//                                   the swept path, f its face normal, dirs[i] the
+//                                   in-plane wall-side direction at vertex i, and the
+//                                   ball centre sits at kf·f + kd·dir off the edge
+//
+// A path's polyline usually STANDS FOR a smooth curve (a circle's rim, an outline's
+// rounded corner): its per-segment cylinders would shade faceted around the curve,
+// while the facet average this replaces blurred those joints smooth. So the path
+// normal is Phong-style: the in-plane direction is interpolated between the vertex
+// directions (each the bisector of its two segments), giving the normal of the
+// smooth canal surface the polyline samples — exact on a straight stretch, and on
+// a sampled curve exact at the samples and continuous between them.
+//
+// The normal is sign-free here (a spine direction); the caller orients it against
+// the facet, which also makes one descriptor serve cutters and fillers alike.
+//
+// Descriptors are registered per Manifold originalID in the tool's ORIGINAL frame
+// (the inverse of the run's runTransform at registration), and evaluated per output
+// run through that run's transform — so they follow every later translate, rotate,
+// boolean and re-stamp that carries runTransform along (Manifold does, verified).
+// Pure module: no DOM, no node:, no three.
+
+const EPS = 1e-12;
+
+// --- 3x4 column-major affine helpers (Manifold's runTransform layout) -------------
+export function affineAt(rt, run) {
+  const o = run * 12;
+  return [rt[o], rt[o + 1], rt[o + 2], rt[o + 3], rt[o + 4], rt[o + 5],
+    rt[o + 6], rt[o + 7], rt[o + 8], rt[o + 9], rt[o + 10], rt[o + 11]];
+}
+export const IDENTITY = Object.freeze([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]);
+const applyPt = (M, p) => [
+  M[0] * p[0] + M[3] * p[1] + M[6] * p[2] + M[9],
+  M[1] * p[0] + M[4] * p[1] + M[7] * p[2] + M[10],
+  M[2] * p[0] + M[5] * p[1] + M[8] * p[2] + M[11],
+];
+const applyDir = (M, d) => [
+  M[0] * d[0] + M[3] * d[1] + M[6] * d[2],
+  M[1] * d[0] + M[4] * d[1] + M[7] * d[2],
+  M[2] * d[0] + M[5] * d[1] + M[8] * d[2],
+];
+// Inverse of an affine; null when singular.
+export function invertAffine(M) {
+  const [a, b, c, d, e, f, g, h, i] = M; // columns (a,b,c) (d,e,f) (g,h,i)
+  const A = e * i - f * h, B = f * g - d * i, C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  if (!(Math.abs(det) > EPS)) return null;
+  const s = 1 / det;
+  // rows of the inverse = cofactor columns; stored column-major
+  const L = [
+    A * s, (c * h - b * i) * s, (b * f - c * e) * s,
+    B * s, (a * i - c * g) * s, (c * d - a * f) * s,
+    C * s, (b * g - a * h) * s, (a * e - b * d) * s,
+  ];
+  const t = applyDir([...L, 0, 0, 0], [M[9], M[10], M[11]]);
+  return [...L, -t[0], -t[1], -t[2]];
+}
+
+const norm = (v) => {
+  const l = Math.hypot(v[0], v[1], v[2]);
+  return l > EPS ? [v[0] / l, v[1] / l, v[2] / l] : null;
+};
+
+// Map a descriptor through an affine (used with the INVERSE run transform at
+// registration: world → original frame). Exact for rigid maps, which is what the
+// tools are posed with; radii scale by the map's mean axis stretch.
+export function mapSurface(desc, M) {
+  switch (desc.kind) {
+    case "line": return { kind: "line", p: applyPt(M, desc.p), d: norm(applyDir(M, desc.d)) ?? desc.d };
+    case "point": return { kind: "point", c: applyPt(M, desc.c) };
+    case "circle": {
+      const s = Math.cbrt(Math.abs(
+        M[0] * (M[4] * M[8] - M[5] * M[7]) - M[3] * (M[1] * M[8] - M[2] * M[7]) + M[6] * (M[1] * M[5] - M[2] * M[4])));
+      return { kind: "circle", c: applyPt(M, desc.c), a: norm(applyDir(M, desc.a)) ?? desc.a, R: desc.R * s };
+    }
+    case "path": {
+      const s = Math.cbrt(Math.abs(
+        M[0] * (M[4] * M[8] - M[5] * M[7]) - M[3] * (M[1] * M[8] - M[2] * M[7]) + M[6] * (M[1] * M[5] - M[2] * M[4])));
+      return { kind: "path", closed: desc.closed, pts: desc.pts.map((p) => applyPt(M, p)),
+        dirs: desc.dirs.map((d) => norm(applyDir(M, d)) ?? d), f: norm(applyDir(M, desc.f)) ?? desc.f,
+        kf: desc.kf * s, kd: desc.kd * s };
+    }
+    default: throw new Error(`blend surface: unknown kind ${desc.kind}`);
+  }
+}
+
+// Nearest spine point to x, in the descriptor's own frame.
+function spinePoint(desc, x) {
+  switch (desc.kind) {
+    case "point": return desc.c;
+    case "line": {
+      const { p, d } = desc;
+      const t = (x[0] - p[0]) * d[0] + (x[1] - p[1]) * d[1] + (x[2] - p[2]) * d[2];
+      return [p[0] + t * d[0], p[1] + t * d[1], p[2] + t * d[2]];
+    }
+    case "circle": {
+      const { c, a, R } = desc;
+      const q = [x[0] - c[0], x[1] - c[1], x[2] - c[2]];
+      const t = q[0] * a[0] + q[1] * a[1] + q[2] * a[2];
+      const rad = norm([q[0] - t * a[0], q[1] - t * a[1], q[2] - t * a[2]]);
+      if (!rad) return R > 0 ? null : c; // on the axis: the normal is undefined unless the spine is a point
+      return [c[0] + R * rad[0], c[1] + R * rad[1], c[2] + R * rad[2]];
+    }
+    default: return null;
+  }
+}
+
+// Path normal (see the header): nearest edge segment i at parameter t, the in-plane
+// direction lerped between its vertex directions, the ball centre offset along it,
+// and the normal rebuilt from x's height above the centre (along f) and its signed
+// in-plane distance across the segment.
+function pathNormal(desc, x) {
+  const { pts, dirs, f, kf, kd } = desc;
+  const n = pts.length;
+  const { bi, bt } = nearestSegment(desc, x);
+  if (bi < 0) return null;
+  const p = pts[bi], q = pts[(bi + 1) % n], d0 = dirs[bi], d1 = dirs[(bi + 1) % n];
+  const dir = norm([d0[0] + (d1[0] - d0[0]) * bt, d0[1] + (d1[1] - d0[1]) * bt, d0[2] + (d1[2] - d0[2]) * bt]);
+  if (!dir) return null;
+  const e = [p[0] + (q[0] - p[0]) * bt, p[1] + (q[1] - p[1]) * bt, p[2] + (q[2] - p[2]) * bt];
+  const c = [e[0] + kf * f[0] + kd * dir[0], e[1] + kf * f[1] + kd * dir[1], e[2] + kf * f[2] + kd * dir[2]];
+  const v = [x[0] - c[0], x[1] - c[1], x[2] - c[2]];
+  const h = v[0] * f[0] + v[1] * f[1] + v[2] * f[2];
+  // signed in-plane distance across the SEGMENT (the local surface's own measure)
+  const segN = norm([q[0] - p[0], q[1] - p[1], q[2] - p[2]]);
+  const perp = segN ? norm([f[1] * segN[2] - f[2] * segN[1], f[2] * segN[0] - f[0] * segN[2], f[0] * segN[1] - f[1] * segN[0]]) : null;
+  if (!perp) return null;
+  const sgn = perp[0] * dir[0] + perp[1] * dir[1] + perp[2] * dir[2] >= 0 ? 1 : -1;
+  const w = sgn * (v[0] * perp[0] + v[1] * perp[1] + v[2] * perp[2]);
+  return norm([h * f[0] + w * dir[0], h * f[1] + w * dir[1], h * f[2] + w * dir[2]]);
+}
+
+// Nearest path segment to x (index + clamped parameter). A text rim's path runs to
+// hundreds of segments and every band vertex asks, so the segments are bucketed
+// once per descriptor into a uniform grid (lazily, off the enumerable fields) and
+// the query widens ring by ring only until no unvisited cell can hold a closer one.
+// squared distance from x to segment pq; the clamped parameter lands in segT
+let segT = 0;
+function segDist2(p, q, x) {
+  const dx = q[0] - p[0], dy = q[1] - p[1], dz = q[2] - p[2];
+  const dd = dx * dx + dy * dy + dz * dz;
+  let t = dd > EPS ? ((x[0] - p[0]) * dx + (x[1] - p[1]) * dy + (x[2] - p[2]) * dz) / dd : 0;
+  t = t < 0 ? 0 : t > 1 ? 1 : t;
+  segT = t;
+  return (x[0] - p[0] - t * dx) ** 2 + (x[1] - p[1] - t * dy) ** 2 + (x[2] - p[2] - t * dz) ** 2;
+}
+const GRID_MIN_SEGS = 16;
+function segmentGrid(desc) {
+  let g = desc[GRID];
+  if (g) return g;
+  const { pts, closed } = desc, n = pts.length, nSeg = closed ? n : n - 1;
+  let total = 0;
+  for (let i = 0; i < nSeg; i++) { const p = pts[i], q = pts[(i + 1) % n]; total += Math.hypot(q[0] - p[0], q[1] - p[1], q[2] - p[2]); }
+  const h = Math.max(total / Math.max(1, nSeg), Math.abs(desc.kf) + Math.abs(desc.kd), 1e-6);
+  const cells = new Map();
+  // numeric hashed cell keys: a collision only adds candidates, each distance-checked
+  const key = (a, b, c) => (Math.imul(a, 73856093) ^ Math.imul(b, 19349663) ^ Math.imul(c, 83492791)) | 0;
+  for (let i = 0; i < nSeg; i++) {
+    const p = pts[i], q = pts[(i + 1) % n];
+    const lo = [0, 1, 2].map((a) => Math.floor(Math.min(p[a], q[a]) / h));
+    const hi = [0, 1, 2].map((a) => Math.floor(Math.max(p[a], q[a]) / h));
+    for (let a = lo[0]; a <= hi[0]; a++) for (let b = lo[1]; b <= hi[1]; b++) for (let c = lo[2]; c <= hi[2]; c++) {
+      const k = key(a, b, c);
+      const list = cells.get(k);
+      if (list) list.push(i); else cells.set(k, [i]);
+    }
+  }
+  g = { h, cells, key, nSeg, stamp: new Uint32Array(nSeg), epoch: 0 };
+  Object.defineProperty(desc, GRID, { value: g, enumerable: false });
+  return g;
+}
+const GRID = Symbol("segmentGrid");
+function nearestSegment(desc, x) {
+  const { pts, closed } = desc, n = pts.length, nSeg = closed ? n : n - 1;
+  let bi = -1, bt = 0, bestD = Infinity;
+  if (nSeg < GRID_MIN_SEGS) {
+    for (let i = 0; i < nSeg; i++) {
+      const D = segDist2(pts[i], pts[(i + 1) % n], x);
+      if (D < bestD) { bestD = D; bi = i; bt = segT; }
+    }
+    return { bi, bt };
+  }
+  const g = segmentGrid(desc), { h, cells, key, stamp } = g;
+  const epoch = ++g.epoch;
+  const c0 = Math.floor(x[0] / h), c1 = Math.floor(x[1] / h), c2 = Math.floor(x[2] / h);
+  for (let ring = 0; ; ring++) {
+    // every cell at Chebyshev distance `ring`; its points lie ≥ (ring-1)·h away
+    if (bi >= 0 && (ring - 1) * h > Math.sqrt(bestD)) break;
+    let any = false;
+    for (let a = -ring; a <= ring; a++) for (let b = -ring; b <= ring; b++) for (let c = -ring; c <= ring; c++) {
+      if (Math.max(Math.abs(a), Math.abs(b), Math.abs(c)) !== ring) continue;
+      const list = cells.get(key(c0 + a, c1 + b, c2 + c));
+      if (!list) continue;
+      any = true;
+      for (const i of list) {
+        if (stamp[i] === epoch) continue;
+        stamp[i] = epoch;
+        const D = segDist2(pts[i], pts[(i + 1) % n], x);
+        if (D < bestD) { bestD = D; bi = i; bt = segT; }
+      }
+    }
+    // h ≥ the ball-centre offset, so a band point finds its segment within a ring or
+    // two; a point this far from the path is not on the band — scan and be done
+    if (!any && bi < 0 && ring >= 3) {
+      for (let i = 0; i < nSeg; i++) {
+        const D = segDist2(pts[i], pts[(i + 1) % n], x);
+        if (D < bestD) { bestD = D; bi = i; bt = segT; }
+      }
+      break;
+    }
+  }
+  return { bi, bt };
+}
+
+// Unit spine→point direction at x in the descriptor's frame, or null where undefined.
+export function surfaceNormal(desc, x) {
+  if (desc.kind === "path") return pathNormal(desc, x);
+  const s = spinePoint(desc, x);
+  return s ? norm([x[0] - s[0], x[1] - s[1], x[2] - s[2]]) : null;
+}
+
+// Per-run evaluator for creased-normals: world-frame analytic normal at world point
+// x for a run whose original-frame descriptor is `desc` and whose runTransform is M.
+// Normals map by the inverse-transpose of M's linear part, so this stays exact under
+// any affine a part applies after the fillet (mirrors, non-uniform scales).
+export function runEvaluator(desc, M) {
+  const inv = invertAffine(M);
+  if (!inv) return null;
+  return (x) => {
+    const n0 = surfaceNormal(desc, applyPt(inv, x));
+    if (!n0) return null;
+    // (M^-1)^T n0: the inverse's COLUMNS dotted with n0
+    return norm([
+      inv[0] * n0[0] + inv[1] * n0[1] + inv[2] * n0[2],
+      inv[3] * n0[0] + inv[4] * n0[1] + inv[5] * n0[2],
+      inv[6] * n0[0] + inv[7] * n0[1] + inv[8] * n0[2],
+    ]);
+  };
+}