partforge 0.136.0 → 0.137.0

package/docs/AUTHORING-PARTS.md

@@ -2396,7 +2396,7 @@ The framework resolves these — fetch/read bytes, detect the format (filename e
 - **STL/3MF on Manifold** — native: parsed, repaired (vertex merge + winding/orientation fix), and handed to `Manifold.ofMesh`. A mesh still non-manifold after repair throws loudly with the open-edge count — see [ERROR-PATTERNS.md#import-mesh-not-solid](ERROR-PATTERNS.md#import-mesh-not-solid).
 - **STL/3MF on OCCT** — never attempted: mesh-to-B-rep conversion isn't in scope for v1. Declaring a mesh import on a part (or sub-part, under per-sub-part routing) that routes to OCCT is an error — see [ERROR-PATTERNS.md#import-mesh-on-occt](ERROR-PATTERNS.md#import-mesh-on-occt).
 
-`import` is not in `OCCT_ONLY_OPS` — a STEP import does not by itself force OCCT routing (the crossover exists precisely so it doesn't have to); backend selection is still driven by `fillet`/`chamfer`/`shell` on a `Solid`, or `meta.backend`.
+`import` is not in `OCCT_ONLY_OPS` — a STEP import does not by itself force OCCT routing (the crossover exists precisely so it doesn't have to); backend selection is still driven by `shell` on a `Solid` or `meta.backend` (`fillet`/`chamfer` run on Manifold and send a sub-part to OCCT only when an edge they select is one the mesh fillet cannot blend).
 
 **Units:** everything normalizes to millimetres at parse time — STEP units are honored by the OCCT importer, a 3MF file's `unit` attribute is converted, and **STL is assumed to already be in millimetres** (the format carries no unit metadata).
 
@@ -3009,14 +3009,16 @@ instead of (or in addition to) the built-in `#part` bar:
   `viewName` rendered offscreen (falling back to the resolved default view — see
   `resolveDefaultView` / `default-view.js` — when `viewName` is omitted or names a view the
   part doesn't declare). Never disturbs the active tab, the live camera, or the on-screen
-  scene; `opts` forwards to the underlying render (size, quality, angle, background).
+  scene; `opts` forwards to the underlying render (size, quality, angle, background, style).
   Resolves `null` on failure rather than throwing (a build error, a part with no sub-parts
   in that view, a disposed runtime). The render happens in a throwaway scene, so it takes
-  no colour from the viewer's light/dark theme: it gets a fixed neutral grey, on the
-  reasoning that a thumbnail is captured once and then displayed under host chrome
-  partforge cannot see. Pass `background` (any `THREE.Color`-compatible value) to choose
-  your own, or `background: null` for no background at all — which clears to opaque black
-  unless the embedder has set a clear colour.
+  no colour from the viewer's light/dark theme. The default `style` is `"thumbnail"`, the
+  product shot: a fixed light background, soft lights, lighter edges, a contact shadow and
+  fit framing — a thumbnail is captured once and then displayed under host chrome
+  partforge cannot see. `style: "cad"` gives the agent-render look instead. `style.view` is
+  only a default angle; an explicit `angle` wins. Pass `background` (any
+  `THREE.Color`-compatible value) to override the style's, or `background: null` for no
+  background at all — which clears to opaque black unless the embedder has set a clear colour.
 
 Pass `onViewChange(name)` to `mount()` to be told the active view: it fires once
 synchronously during mount with the initial resolved view (before `runtime.ready` settles),
@@ -3143,7 +3145,8 @@ pane's pixel size:
   or when measurement dimensions are pinned (their labels sit beside the part and
   could otherwise be cut off).
 - `runtime.captureViews(viewNames) → [{ view, dataUrl }]` — the canonical-angle
-  counterpart (fixed poses, framed to the visible assembly, 1024², grid hidden). Sized
+  counterpart (fixed view directions, each fitted so the visible assembly's projected
+  geometry fills 90% of the frame and sits centred in it; 1024², grid hidden). Sized
   for feeding a vision model, not for display; use `captureCurrent` for showcase images.
 
 ### `runtime.projection`
@@ -3469,6 +3472,11 @@ the part's first declared view. Treat renders as complementary evidence, not a r
 use several views for complex parts and the interactive viewer's cutaway for hidden
 interfaces, but rely on `measure` / `verify` for dimensions, contact, and clearance.
 
+Headlessly, `renderViewImages(kernel, part, view, opts)` from `partforge/testing` returns
+the same stills in memory as `[{ angle, png }]` (PNG buffers; `renderViews` writes them to
+disk through it). Its `style` option is `"cad"` (default) or `"thumbnail"`; `style.view`
+is only a default, so explicit `views` always win.
+
 The `measure` function is also exported for vitest (boot a Manifold kernel as in
 "Testing a part", then `measure(kernel, part, "<view>")`):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.136.0",
+  "version": "0.137.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",
@@ -106,7 +106,9 @@
     "lint": "eslint .",
     "lint:dead": "knip",
     "check": "node scripts/check-app.mjs",
-    "offset-rates": "node scripts/offset-rates.mjs"
+    "offset-rates": "node scripts/offset-rates.mjs",
+    "bench:softrender": "node scripts/bench-softrender.mjs",
+    "check:softrender": "node scripts/check-softrender-parity.mjs"
   },
   "peerDependencies": {
     "happy-dom": ">=20"

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

@@ -0,0 +1,30 @@
+// src/framework/contact-shadow-plane.js
+// The viewer's half of the contact shadow (contact-shadow.js holds the mask):
+// a black, unlit, alpha-mapped plane a hair under the floor. MeshBasicMaterial
+// so no light touches it; depthWrite off so the part's bottom face never
+// z-fights it. The CPU renderer samples the same mask per pixel instead.
+import * as THREE from "three";
+
+export function buildContactShadowPlane(mask, shadow) {
+  const { width: W, height: H, data, rect, y } = mask;
+  // alphaMap reads the GREEN channel. PlaneGeometry's v runs along local +y,
+  // which rotation.x = -PI/2 turns into world -z: texture row 0 (v = 0) is
+  // world z1, so mask row j (world z0 + ...) goes to texture row H-1-j.
+  const px = new Uint8Array(W * H * 4);
+  for (let j = 0; j < H; j++) for (let i = 0; i < W; i++) {
+    const v = Math.round(Math.min(1, Math.max(0, data[j * W + i])) * 255);
+    const o = ((H - 1 - j) * W + i) * 4;
+    px[o] = px[o + 1] = px[o + 2] = v; px[o + 3] = 255;
+  }
+  const tex = new THREE.DataTexture(px, W, H, THREE.RGBAFormat);
+  tex.magFilter = THREE.LinearFilter; tex.minFilter = THREE.LinearFilter;
+  tex.needsUpdate = true;
+  const sx = rect.x1 - rect.x0, sz = rect.z1 - rect.z0;
+  const mat = new THREE.MeshBasicMaterial({
+    color: 0x000000, transparent: true, opacity: shadow.opacity, alphaMap: tex, depthWrite: false,
+  });
+  const mesh = new THREE.Mesh(new THREE.PlaneGeometry(sx, sz), mat);
+  mesh.rotation.x = -Math.PI / 2;
+  mesh.position.set((rect.x0 + rect.x1) / 2, y - 1e-3 * Math.max(sx, sz), (rect.z0 + rect.z1) / 2);
+  return mesh;
+}

package/src/framework/contact-shadow.js

@@ -0,0 +1,83 @@
+// The product shot's soft contact shadow, as a top-down mask over the floor
+// (the part's lowest world Y). Each cell is darkest where geometry sits ON the
+// floor and fades to nothing `falloff·diag` above it, then the mask is blurred.
+// Pure, so the viewer (as an alpha texture on a ground plane) and the CPU
+// renderer (sampled per background pixel) draw the SAME shadow.
+import { triangleCount, triangleOffsets } from "./softrender/triangles.js";
+
+export function contactShadowMask(meshes, box, shadow) {
+  const size = [0, 1, 2].map((k) => box.max[k] - box.min[k]);
+  const diag = Math.hypot(...size);
+  if (!(diag > 0)) return null;
+  const falloff = shadow.falloff * diag;
+  const blurW = shadow.blur * diag;
+  const x0 = box.min[0] - 2 * blurW, x1 = box.max[0] + 2 * blurW;
+  const z0 = box.min[2] - 2 * blurW, z1 = box.max[2] + 2 * blurW;
+  const spanX = Math.max(x1 - x0, 1e-9), spanZ = Math.max(z1 - z0, 1e-9);
+  const span = Math.max(spanX, spanZ);
+  const W = Math.max(1, Math.round((shadow.resolution * spanX) / span));
+  const H = Math.max(1, Math.round((shadow.resolution * spanZ) / span));
+  const floor = box.min[1];
+  const minH = new Float32Array(W * H).fill(Infinity);
+
+  const gx = (x) => ((x - x0) / spanX) * W, gz = (z) => ((z - z0) / spanZ) * H;
+  for (const m of meshes) {
+    const P = m.positions;
+    const n = triangleCount(m);
+    for (let t = 0; t < n; t++) {
+      const o = triangleOffsets(m, t);
+      const ax = gx(P[o[0]]), az = gz(P[o[0] + 2]), ah = P[o[0] + 1] - floor;
+      const bx = gx(P[o[1]]), bz = gz(P[o[1] + 2]), bh = P[o[1] + 1] - floor;
+      const cx = gx(P[o[2]]), cz = gz(P[o[2] + 2]), ch = P[o[2] + 1] - floor;
+      const area = (bx - ax) * (cz - az) - (bz - az) * (cx - ax);
+      if (Math.abs(area) < 1e-12) continue; // a wall seen from above covers no cells
+      const i0 = Math.max(0, Math.floor(Math.min(ax, bx, cx))), i1 = Math.min(W - 1, Math.ceil(Math.max(ax, bx, cx)));
+      const j0 = Math.max(0, Math.floor(Math.min(az, bz, cz))), j1 = Math.min(H - 1, Math.ceil(Math.max(az, bz, cz)));
+      for (let j = j0; j <= j1; j++) for (let i = i0; i <= i1; i++) {
+        const px = i + 0.5, pz = j + 0.5;
+        const w0 = ((cx - bx) * (pz - bz) - (cz - bz) * (px - bx)) / area;
+        const w1 = ((ax - cx) * (pz - cz) - (az - cz) * (px - cx)) / area;
+        const w2 = 1 - w0 - w1;
+        if (w0 < 0 || w1 < 0 || w2 < 0) continue;
+        const h = w0 * ah + w1 * bh + w2 * ch;
+        const k = j * W + i;
+        if (h < minH[k]) minH[k] = h;
+      }
+    }
+  }
+
+  let data = new Float32Array(W * H);
+  for (let k = 0; k < data.length; k++) {
+    const h = minH[k];
+    data[k] = Number.isFinite(h) ? Math.min(1, Math.max(0, 1 - Math.max(0, h) / falloff)) : 0;
+  }
+  const r = Math.max(1, Math.round((blurW / spanX) * W));
+  for (let pass = 0; pass < 3; pass++) data = boxBlur(boxBlur(data, W, H, r, true), W, H, r, false);
+  return { width: W, height: H, data, rect: { x0, x1, z0, z1 }, y: floor };
+}
+
+// One separable box-blur pass, edges clamped.
+function boxBlur(src, W, H, r, horizontal) {
+  const out = new Float32Array(src.length);
+  const n = horizontal ? W : H, lines = horizontal ? H : W;
+  for (let l = 0; l < lines; l++) {
+    const at = (i) => (horizontal ? l * W + i : i * W + l);
+    let sum = 0;
+    for (let i = -r; i <= r; i++) sum += src[at(Math.min(n - 1, Math.max(0, i)))];
+    for (let i = 0; i < n; i++) {
+      out[at(i)] = sum / (2 * r + 1);
+      sum += src[at(Math.min(n - 1, i + r + 1))] - src[at(Math.max(0, i - r))];
+    }
+  }
+  return out;
+}
+
+export function sampleShadowMask(mask, x, z) {
+  const { width: W, height: H, data, rect } = mask;
+  if (x < rect.x0 || x > rect.x1 || z < rect.z0 || z > rect.z1) return 0;
+  const u = ((x - rect.x0) / (rect.x1 - rect.x0)) * W - 0.5;
+  const v = ((z - rect.z0) / (rect.z1 - rect.z0)) * H - 0.5;
+  const i = Math.floor(u), j = Math.floor(v), fu = u - i, fv = v - j;
+  const at = (ii, jj) => data[Math.min(H - 1, Math.max(0, jj)) * W + Math.min(W - 1, Math.max(0, ii))];
+  return (at(i, j) * (1 - fu) + at(i + 1, j) * fu) * (1 - fv) + (at(i, j + 1) * (1 - fu) + at(i + 1, j + 1) * fu) * fv;
+}

package/src/framework/materials/physical.js

@@ -4,13 +4,10 @@
 // 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 { cadAppearance, resolveMaterial, hasAppearance } from "./resolve.js";
 import { applyBrushFrame, applyBurn, 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);

package/src/framework/materials/resolve.js

@@ -141,3 +141,9 @@ export function resolveEnvironmentId(id) {
   if (typeof id === "string" && Object.hasOwn(ENVIRONMENTS, id)) return { id, known: true };
   return { id: DEFAULT_ENVIRONMENT_ID, known: false };
 }
+
+// Whether a sub-part's `display` declares any appearance at all. Without one
+// the CAD view uses the shared default material untouched (physical.js
+// buildCadMaterial; softrender/index.js mirrors that rule).
+const APPEARANCE_KEYS = ["color", "opacity", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", "anisotropy", "textureScale"];
+export const hasAppearance = (display) => !!display && APPEARANCE_KEYS.some((k) => display[k] != null);

package/src/framework/mount.js

@@ -1390,7 +1390,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // touches the active tab, getView(), or the live scene — best-effort: any
     // failure, including a resolved-null from a worker build failure (4A
     // settles rather than throwing), returns null. `opts` is spread last, so
-    // renderMeshPayloads' own options (including `background`) pass straight
+    // renderMeshPayloads' own options (including `background` and
+    // `style`: "thumbnail" by default, "cad" for the agent look) pass straight
     // through from the caller.
     const captureView = async (viewName, opts = {}) => {
       try {

package/src/framework/renderStyles.js

@@ -0,0 +1,146 @@
+// src/framework/renderStyles.js
+// The two offscreen capture looks, as plain data: `cad` (the agent's renders)
+// and `thumbnail` (the card/product shot). Read by BOTH the three.js viewer
+// (viewer.js, viewer-lighting.js) and the CPU renderer (softrender/), so a
+// look is written down once and the two renderers cannot drift apart. No
+// three.js here: this module runs in the Vercel Sandbox under plain Node.
+//
+// Colours are sRGB hex, exactly as three.js receives them; consumers convert
+// to linear (srgbHexToLinear) the way three's ColorManagement does.
+
+export const CAD_LIGHT_THEME = Object.freeze({ bg: 0xe9edf2, line: 0x33414f });
+export const CAD_DARK_THEME = Object.freeze({ bg: 0x15181d, line: 0x1c232d });
+
+const CAD_LIGHTS = {
+  hemisphere: { sky: 0xdce9ff, ground: 0x687586, intensity: 1.35 },
+  // Offsets are camera-space multiples of the camera-to-target distance:
+  // key over the viewer's shoulder, fill opposing it at eye level
+  // (style-camera.js captureLightPoses places them).
+  key: { color: 0xffffff, intensity: 1.45, offset: { right: 0.45, up: 0.75 } },
+  fill: { color: 0xe5efff, intensity: 0.65, offset: { right: -0.7, up: 0.15 } },
+};
+const CAD_MATERIAL = { color: 0x9fb4cc, metalness: 0.25, roughness: 0.55 };
+
+// The product shot, tuned 2026-10-02 on demo / hinged-box / propeller captures
+// judged at card size (~300px from the 640px thumbnail): fill 0.88 (room for
+// the shadow and the card's corners), hemisphere 1.65, key
+// 1.25, fill light 1.05 (the shaded side stays off the background), 1.5px edges
+// at 0.7 (visible at card size, lighter than the editor's), and a contact shadow
+// of 0.5 opacity / 0.25 falloff / 0.07 blur (faint, but it reads — most of it
+// sits under the part at iso). Retune with scripts/check-softrender-parity.mjs
+// --out, on captures, never by eye on the hex; both renderers move together.
+// Both looks frame by "fit" (style-camera.js fitPoseToPoints): the canonical
+// direction, at the distance that brings the projected geometry to `fill` of
+// the frame, centred on it. cad's 0.9 leaves a margin so a silhouette never
+// touches the frame edge. "canonical" (cameraPoseForView's fixed distance)
+// stays valid for a caller-supplied style.
+const STYLES = {
+  cad: {
+    camera: { projection: "perspective", fov: 45, framing: "fit", fill: 0.9 },
+    lights: CAD_LIGHTS,
+    material: CAD_MATERIAL,
+    edges: { color: CAD_LIGHT_THEME.line, widthPx: 1, opacity: 1 },
+    background: CAD_LIGHT_THEME.bg,
+    shadow: null,
+    view: null,
+  },
+  thumbnail: {
+    camera: { projection: "perspective", fov: 45, framing: "fit", fill: 0.88 },
+    lights: {
+      hemisphere: { ...CAD_LIGHTS.hemisphere, intensity: 1.65 },
+      key: { ...CAD_LIGHTS.key, intensity: 1.25 },
+      fill: { ...CAD_LIGHTS.fill, intensity: 1.05 },
+    },
+    material: CAD_MATERIAL,
+    edges: { color: CAD_LIGHT_THEME.line, widthPx: 1.5, opacity: 0.7 },
+    background: 0xeef1f5,
+    // falloff/blur are fractions of the part's bounding-box diagonal;
+    // resolution is the mask's long side in cells.
+    shadow: { opacity: 0.5, falloff: 0.25, blur: 0.07, resolution: 128 },
+    view: "iso",
+  },
+};
+
+const isHex = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffffff;
+const inRange = (v, lo, hi) => typeof v === "number" && Number.isFinite(v) && v >= lo && v <= hi;
+function check(ok, field) { if (!ok) throw new Error(`render style: ${field} is invalid`); }
+
+export function validateRenderStyle(s) {
+  check(s && typeof s === "object", "style");
+  check(s.camera?.projection === "perspective", "camera.projection");
+  check(inRange(s.camera.fov, 1, 120), "camera.fov");
+  check(s.camera.framing === "canonical" || s.camera.framing === "fit", "camera.framing");
+  if (s.camera.framing === "fit") check(inRange(s.camera.fill, 0.05, 1), "camera.fill");
+  const h = s.lights?.hemisphere;
+  check(isHex(h?.sky) && isHex(h?.ground) && inRange(h?.intensity, 0, 20), "lights.hemisphere");
+  for (const k of ["key", "fill"]) {
+    const l = s.lights[k];
+    check(isHex(l?.color) && inRange(l?.intensity, 0, 20), `lights.${k}`);
+    check(inRange(l.offset?.right, -10, 10) && inRange(l.offset?.up, -10, 10), `lights.${k}.offset`);
+  }
+  check(isHex(s.material?.color), "material.color");
+  check(inRange(s.material.metalness, 0, 1), "material.metalness");
+  check(inRange(s.material.roughness, 0, 1), "material.roughness");
+  check(isHex(s.edges?.color) && inRange(s.edges?.widthPx, 0.25, 8) && inRange(s.edges?.opacity, 0, 1), "edges");
+  check(isHex(s.background), "background");
+  if (s.shadow !== null) {
+    const sh = s.shadow;
+    check(inRange(sh?.opacity, 0, 1) && inRange(sh?.falloff, 0.001, 10) && inRange(sh?.blur, 0, 1)
+      && Number.isInteger(sh?.resolution) && sh.resolution >= 8 && sh.resolution <= 1024, "shadow");
+  }
+  check(s.view === null || typeof s.view === "string", "view");
+  return s;
+}
+
+function deepFreeze(o) {
+  for (const v of Object.values(o)) if (v && typeof v === "object") deepFreeze(v);
+  return Object.freeze(o);
+}
+
+// Validated once, at load: a typo in the data above fails every test that
+// imports this module rather than producing odd images.
+for (const s of Object.values(STYLES)) validateRenderStyle(s);
+export const RENDER_STYLES = deepFreeze(structuredClone(STYLES));
+
+export function getRenderStyle(nameOrStyle) {
+  if (typeof nameOrStyle === "string") {
+    if (!Object.hasOwn(RENDER_STYLES, nameOrStyle)) throw new Error(`unknown render style "${nameOrStyle}"`);
+    return RENDER_STYLES[nameOrStyle];
+  }
+  return validateRenderStyle(nameOrStyle);
+}
+
+// sRGB hex → linear [r, g, b], the same transfer three's ColorManagement
+// applies to a hex colour handed to a material or a light.
+export function srgbHexToLinear(hex) {
+  return [(hex >> 16) & 255, (hex >> 8) & 255, hex & 255].map((b) => {
+    const c = b / 255;
+    return c < 0.04045 ? c * 0.0773993808 : ((c * 0.9478672986) + 0.0521327014) ** 2.4;
+  });
+}
+
+// three renders into a render target in the LINEAR working colour space: as of r184
+// WebGLRenderer only applies `outputColorSpace` on the canvas path (WebGLPrograms
+// substitutes workingColorSpace whenever a render target is bound), so readback pixels
+// are linear no matter what the target texture's colorSpace says. Writing them straight
+// into a JPEG is what made captured views come back muddy and dark compared to the live
+// canvas. Encode the transfer function ourselves. The 8-bit LUT loses precision only in
+// the deepest shadows, which a quality-0.9 JPEG would not have preserved anyway.
+export const SRGB8 = (() => {
+  const table = new Uint8Array(256);
+  for (let i = 0; i < 256; i++) {
+    const l = i / 255;
+    table[i] = Math.round(255 * (l <= 0.0031308 ? 12.92 * l : 1.055 * l ** (1 / 2.4) - 0.055));
+  }
+  return table;
+})();
+
+// Linear RGBA bytes → sRGB, in place. Alpha is a coverage value, not a colour: untouched.
+export function srgbEncodeInPlace(data) {
+  for (let i = 0; i < data.length; i += 4) {
+    data[i] = SRGB8[data[i]];
+    data[i + 1] = SRGB8[data[i + 1]];
+    data[i + 2] = SRGB8[data[i + 2]];
+  }
+  return data;
+}

package/src/framework/softrender/camera.js

@@ -0,0 +1,38 @@
+// A perspective camera with three.js's conventions (PerspectiveCamera +
+// lookAt: vertical fov, right = forward × up, screen y down in pixel space),
+// so a pose from style-camera.js lands every vertex where the viewer would.
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const norm = (v) => { const l = Math.hypot(v[0], v[1], v[2]) || 1; return [v[0] / l, v[1] / l, v[2] / l]; };
+
+export function makeCamera(pose, { fov, width, height }) {
+  const f = norm(sub(pose.target, pose.position));
+  let r = cross(f, pose.up);
+  if (Math.hypot(...r) < 1e-9) r = cross(f, [0, 0, 1]);
+  r = norm(r);
+  const u = cross(r, f);
+  const tanH = Math.tan((fov * Math.PI) / 360);
+  const aspect = width / height;
+  const [px, py, pz] = pose.position;
+  return {
+    position: pose.position, forward: f, right: r, up: u, tanH, aspect, width, height,
+    // Both write into `out` when given: the rasterizer and shading loops call
+    // them per vertex / per sample and pass one scratch array, so the hot
+    // path allocates nothing.
+    project(x, y, z, out = [0, 0, 0]) {
+      const dx = x - px, dy = y - py, dz = z - pz;
+      const vz = dx * f[0] + dy * f[1] + dz * f[2];
+      const vx = dx * r[0] + dy * r[1] + dz * r[2];
+      const vy = dx * u[0] + dy * u[1] + dz * u[2];
+      out[0] = (vx / (vz * tanH * aspect) * 0.5 + 0.5) * width;
+      out[1] = (0.5 - (vy / (vz * tanH)) * 0.5) * height;
+      out[2] = vz;
+      return out;
+    },
+    ray(sx, sy, out = [0, 0, 0]) {
+      const a = ((sx / width) * 2 - 1) * tanH * aspect, b = (1 - (sy / height) * 2) * tanH;
+      for (let i = 0; i < 3; i++) out[i] = f[i] + a * r[i] + b * u[i];
+      return out;
+    },
+  };
+}

package/src/framework/softrender/dfgLut.js

@@ -0,0 +1,65 @@
+// three r184's DFG look-up table (renderers/shaders/DFGLUTData.js), copied
+// verbatim: 16x16 texels of (scale, bias) as RG16F half floats, 4096 samples
+// each. Row = dot(N, V), column = roughness, as the shader samples it
+// (texture2D(dfgLUT, vec2(roughness, dotNV))). three feeds it to the standard
+// material's multiscattering terms even with no environment map, so shade.js
+// needs it. Pure data + a bilinear sampler; no three.js import.
+const DATA = new Uint16Array([
+	0x30b5, 0x3ad1, 0x314c, 0x3a4d, 0x33d2, 0x391c, 0x35ef, 0x3828, 0x37f3, 0x36a6, 0x38d1, 0x3539, 0x3979, 0x3410, 0x39f8, 0x3252,
+	0x3a53, 0x30f0, 0x3a94, 0x2fc9, 0x3abf, 0x2e35, 0x3ada, 0x2d05, 0x3ae8, 0x2c1f, 0x3aed, 0x2ae0, 0x3aea, 0x29d1, 0x3ae1, 0x28ff,
+	0x3638, 0x38e4, 0x364a, 0x38ce, 0x3699, 0x385e, 0x374e, 0x372c, 0x3839, 0x35a4, 0x38dc, 0x3462, 0x396e, 0x32c4, 0x39de, 0x3134,
+	0x3a2b, 0x3003, 0x3a59, 0x2e3a, 0x3a6d, 0x2ce1, 0x3a6e, 0x2bba, 0x3a5f, 0x2a33, 0x3a49, 0x290a, 0x3a2d, 0x2826, 0x3a0a, 0x26e8,
+	0x3894, 0x36d7, 0x3897, 0x36c9, 0x38a3, 0x3675, 0x38bc, 0x35ac, 0x38ee, 0x349c, 0x393e, 0x3332, 0x3997, 0x3186, 0x39e2, 0x3038,
+	0x3a13, 0x2e75, 0x3a29, 0x2cf5, 0x3a2d, 0x2bac, 0x3a21, 0x29ff, 0x3a04, 0x28bc, 0x39dc, 0x2790, 0x39ad, 0x261a, 0x3978, 0x24fa,
+	0x39ac, 0x34a8, 0x39ac, 0x34a3, 0x39ae, 0x3480, 0x39ae, 0x3423, 0x39b1, 0x330e, 0x39c2, 0x31a9, 0x39e0, 0x3063, 0x39fc, 0x2eb5,
+	0x3a0c, 0x2d1d, 0x3a14, 0x2bcf, 0x3a07, 0x29ff, 0x39e9, 0x28a3, 0x39be, 0x273c, 0x3989, 0x25b3, 0x394a, 0x2488, 0x3907, 0x2345,
+	0x3a77, 0x3223, 0x3a76, 0x321f, 0x3a73, 0x3204, 0x3a6a, 0x31b3, 0x3a58, 0x3114, 0x3a45, 0x303b, 0x3a34, 0x2eb6, 0x3a26, 0x2d31,
+	0x3a1e, 0x2bef, 0x3a0b, 0x2a0d, 0x39ec, 0x28a1, 0x39c0, 0x271b, 0x3987, 0x2580, 0x3944, 0x2449, 0x38fa, 0x22bd, 0x38ac, 0x2155,
+	0x3b07, 0x2fca, 0x3b06, 0x2fca, 0x3b00, 0x2fb8, 0x3af4, 0x2f7c, 0x3adb, 0x2eea, 0x3ab4, 0x2e00, 0x3a85, 0x2cec, 0x3a5e, 0x2bc5,
+	0x3a36, 0x2a00, 0x3a0d, 0x2899, 0x39dc, 0x2707, 0x39a0, 0x2562, 0x395a, 0x2424, 0x390b, 0x2268, 0x38b7, 0x20fd, 0x385f, 0x1fd1,
+	0x3b69, 0x2cb9, 0x3b68, 0x2cbb, 0x3b62, 0x2cbb, 0x3b56, 0x2cae, 0x3b3b, 0x2c78, 0x3b0d, 0x2c0a, 0x3acf, 0x2ae3, 0x3a92, 0x2998,
+	0x3a54, 0x2867, 0x3a17, 0x26d0, 0x39d3, 0x253c, 0x3989, 0x2402, 0x3935, 0x2226, 0x38dc, 0x20bd, 0x387d, 0x1f54, 0x381d, 0x1db3,
+	0x3ba9, 0x296b, 0x3ba8, 0x296f, 0x3ba3, 0x297b, 0x3b98, 0x2987, 0x3b7f, 0x2976, 0x3b4e, 0x2927, 0x3b0e, 0x2895, 0x3ac2, 0x27b7,
+	0x3a73, 0x263b, 0x3a23, 0x24e7, 0x39d0, 0x239b, 0x3976, 0x21d9, 0x3917, 0x207e, 0x38b2, 0x1ee7, 0x384b, 0x1d53, 0x37c7, 0x1c1e,
+	0x3bd2, 0x25cb, 0x3bd1, 0x25d3, 0x3bcd, 0x25f0, 0x3bc2, 0x261f, 0x3bad, 0x2645, 0x3b7d, 0x262d, 0x3b3e, 0x25c4, 0x3aec, 0x250f,
+	0x3a93, 0x243a, 0x3a32, 0x22ce, 0x39d0, 0x215b, 0x3969, 0x202a, 0x38fe, 0x1e6e, 0x388f, 0x1cf1, 0x381f, 0x1b9b, 0x3762, 0x19dd,
+	0x3be9, 0x21ab, 0x3be9, 0x21b7, 0x3be5, 0x21e5, 0x3bdd, 0x2241, 0x3bc9, 0x22a7, 0x3ba0, 0x22ec, 0x3b62, 0x22cd, 0x3b0f, 0x2247,
+	0x3aae, 0x2175, 0x3a44, 0x2088, 0x39d4, 0x1f49, 0x3960, 0x1dbe, 0x38e9, 0x1c77, 0x3870, 0x1ae8, 0x37f1, 0x1953, 0x3708, 0x181b,
+	0x3bf6, 0x1cea, 0x3bf6, 0x1cfb, 0x3bf3, 0x1d38, 0x3bec, 0x1dbd, 0x3bda, 0x1e7c, 0x3bb7, 0x1f25, 0x3b7d, 0x1f79, 0x3b2c, 0x1f4c,
+	0x3ac6, 0x1ea6, 0x3a55, 0x1dbb, 0x39da, 0x1cbd, 0x395a, 0x1b9d, 0x38d8, 0x1a00, 0x3855, 0x18ac, 0x37ab, 0x173c, 0x36b7, 0x1598,
+	0x3bfc, 0x1736, 0x3bfc, 0x1759, 0x3bf9, 0x17e7, 0x3bf4, 0x1896, 0x3be4, 0x1997, 0x3bc6, 0x1aa8, 0x3b91, 0x1b84, 0x3b43, 0x1bd2,
+	0x3ade, 0x1b8a, 0x3a65, 0x1acd, 0x39e2, 0x19d3, 0x3957, 0x18cd, 0x38ca, 0x17b3, 0x383e, 0x1613, 0x376d, 0x14bf, 0x366f, 0x135e,
+	0x3bff, 0x101b, 0x3bff, 0x1039, 0x3bfc, 0x10c8, 0x3bf9, 0x1226, 0x3bea, 0x1428, 0x3bcf, 0x1584, 0x3b9f, 0x16c5, 0x3b54, 0x179a,
+	0x3af0, 0x17ce, 0x3a76, 0x1771, 0x39ea, 0x16a4, 0x3956, 0x15a7, 0x38bf, 0x14a7, 0x3829, 0x1379, 0x3735, 0x11ea, 0x362d, 0x10a1,
+	0x3c00, 0x061b, 0x3c00, 0x066a, 0x3bfe, 0x081c, 0x3bfa, 0x0a4c, 0x3bed, 0x0d16, 0x3bd5, 0x0fb3, 0x3ba9, 0x114d, 0x3b63, 0x127c,
+	0x3b01, 0x132f, 0x3a85, 0x1344, 0x39f4, 0x12d2, 0x3957, 0x120d, 0x38b5, 0x1122, 0x3817, 0x103c, 0x3703, 0x0ed3, 0x35f0, 0x0d6d,
+	0x3c00, 0x007a, 0x3c00, 0x0089, 0x3bfe, 0x011d, 0x3bfb, 0x027c, 0x3bf0, 0x04fa, 0x3bda, 0x0881, 0x3bb1, 0x0acd, 0x3b6f, 0x0c97,
+	0x3b10, 0x0d7b, 0x3a93, 0x0df1, 0x39fe, 0x0def, 0x3959, 0x0d8a, 0x38af, 0x0ce9, 0x3808, 0x0c31, 0x36d5, 0x0af0, 0x35b9, 0x09a3,
+	0x3c00, 0x0000, 0x3c00, 0x0001, 0x3bff, 0x0015, 0x3bfb, 0x0059, 0x3bf2, 0x00fd, 0x3bdd, 0x01df, 0x3bb7, 0x031c, 0x3b79, 0x047c,
+	0x3b1d, 0x05d4, 0x3aa0, 0x06d5, 0x3a08, 0x075a, 0x395d, 0x075e, 0x38aa, 0x06f7, 0x37f4, 0x0648, 0x36ac, 0x0576, 0x3586, 0x049f,
+]);
+
+const SIZE = 16;
+
+function half(h) {
+  const e = (h >> 10) & 0x1f, f = h & 0x3ff, sign = h & 0x8000 ? -1 : 1;
+  if (e === 0) return sign * 2 ** -14 * (f / 1024);
+  return sign * 2 ** (e - 15) * (1 + f / 1024);
+}
+const LUT = Float32Array.from(DATA, half);
+
+// LinearFilter + ClampToEdge sample at (u, v) = (roughness, dotNV) -> [scale, bias].
+export function dfgLut(roughness, dotNV) {
+  const x = Math.min(Math.max(roughness * SIZE - 0.5, 0), SIZE - 1);
+  const y = Math.min(Math.max(dotNV * SIZE - 0.5, 0), SIZE - 1);
+  const x0 = Math.floor(x), y0 = Math.floor(y);
+  const x1 = Math.min(x0 + 1, SIZE - 1), y1 = Math.min(y0 + 1, SIZE - 1);
+  const fx = x - x0, fy = y - y0;
+  const at = (xi, yi, c) => LUT[(yi * SIZE + xi) * 2 + c];
+  const mix = (c) => {
+    const a = at(x0, y0, c) * (1 - fx) + at(x1, y0, c) * fx;
+    const b = at(x0, y1, c) * (1 - fx) + at(x1, y1, c) * fx;
+    return a * (1 - fy) + b * fy;
+  };
+  return [mix(0), mix(1)];
+}

package/src/framework/softrender/edges.js

@@ -0,0 +1,39 @@
+// src/framework/softrender/edges.js
+// Feature edges as lines of the style's width, stamped at supersample
+// resolution (so they come out antialiased after the downsample) and depth-
+// tested against the G-buffer with a scene-relative bias. Coverage is marked
+// first and blended ONCE per sample: overlapping stamps of a translucent line
+// must not darken where they overlap.
+import { NEAR } from "./raster.js";
+
+export function drawEdges(color, gb, cam, segments, rgb, opacity, widthPx, ss, bias) {
+  if (!segments?.length || opacity <= 0) return;
+  const { width: W, height: H, depth } = gb;
+  const mark = new Uint8Array(W * H);
+  const half = Math.max(0.5, (widthPx * ss) / 2);
+  const p0 = [0, 0, 0], p1 = [0, 0, 0];
+  for (let i = 0; i + 5 < segments.length; i += 6) {
+    cam.project(segments[i], segments[i + 1], segments[i + 2], p0);
+    cam.project(segments[i + 3], segments[i + 4], segments[i + 5], p1);
+    if (p0[2] < NEAR || p1[2] < NEAR) continue;
+    const steps = Math.max(1, Math.ceil(Math.hypot(p1[0] - p0[0], p1[1] - p0[1]) * 2));
+    for (let s = 0; s <= steps; s++) {
+      const t = s / steps;
+      const x = p0[0] + (p1[0] - p0[0]) * t, y = p0[1] + (p1[1] - p0[1]) * t;
+      const z = 1 / ((1 - t) / p0[2] + t / p1[2]); // depth is linear in 1/z on screen
+      const xmin = Math.max(0, Math.floor(x - half + 0.5)), xmax = Math.min(W - 1, Math.max(xmin, Math.floor(x + half - 0.5)));
+      const ymin = Math.max(0, Math.floor(y - half + 0.5)), ymax = Math.min(H - 1, Math.max(ymin, Math.floor(y + half - 0.5)));
+      for (let yy = ymin; yy <= ymax; yy++) for (let xx = xmin; xx <= xmax; xx++) {
+        const k = yy * W + xx;
+        if (z - bias <= depth[k]) mark[k] = 1;
+      }
+    }
+  }
+  for (let k = 0; k < mark.length; k++) {
+    if (!mark[k]) continue;
+    const o = k * 3;
+    color[o] += (rgb[0] - color[o]) * opacity;
+    color[o + 1] += (rgb[1] - color[o + 1]) * opacity;
+    color[o + 2] += (rgb[2] - color[o + 2]) * opacity;
+  }
+}