partforge 0.136.1 → 0.137.1

package/src/framework/viewer.js

@@ -25,31 +25,11 @@ import { addViewerLights, captureLightPoses, createCaptureLights, createHemisphe
 import { makeCaptureCamera, recenteredView, captureDepthRange } from "./capture-frame.js";
 import { CANONICAL_VIEWS, cameraPoseForView } from "./view-angles.js";
 
-// 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.
-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;
-}
+import { srgbEncodeInPlace, RENDER_STYLES, getRenderStyle, CAD_LIGHT_THEME, CAD_DARK_THEME } from "./renderStyles.js";
+import { stylePose, modelToWorld } from "./style-camera.js";
+import { contactShadowMask } from "./contact-shadow.js";
+import { buildContactShadowPlane } from "./contact-shadow-plane.js";
+export { srgbEncodeInPlace }; // was exported from here; keep the name importable
 
 // Readback (a realistic capture's target) → linear floats: half-float bits,
 // or linear bytes from the 8-bit fallback target.
@@ -80,7 +60,9 @@ export function halfFloatCaptureSupported({ readable, readType = null, halfFloat
 // `renderer.renderOffscreen(pose)` does the GL work (temp camera → offscreen
 // target → readback → JPEG data URL); injected so this is unit-testable without
 // a GL context. The grid is hidden for the whole synchronous pass and restored.
-export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, bounds, sceneBounds, hidden = [] }) {
+// `poseFor(view)`, when given, places each view's camera in place of
+// cameraPoseForView(view, bounds) — the viewer passes the cad style's fit.
+export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, bounds, sceneBounds, hidden = [], poseFor }) {
   const views = (viewNames?.length ? viewNames : ["iso", "front", "top"])
     .filter((v) => CANONICAL_VIEWS.includes(v))
     .slice(0, CANONICAL_VIEWS.length);
@@ -91,10 +73,11 @@ export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, b
   for (const o of hidden) o.visible = false;
   try {
     return views.map((view) => {
-      const pose = cameraPoseForView(view, bounds);
-      // `bounds` frames (half the max extent, by cameraPoseForView's contract);
-      // `sceneBounds` is the sphere the depth planes must hold. The grid is
-      // hidden for this whole pass, so the part alone is in the second one.
+      const pose = poseFor ? poseFor(view) : cameraPoseForView(view, bounds);
+      // `bounds` frames (half the max extent, by cameraPoseForView's contract)
+      // when there is no `poseFor`; `sceneBounds` is the sphere the depth planes
+      // must hold. The grid is hidden for this whole pass, so the part alone is
+      // in the second one.
       return { view, dataUrl: renderer.renderOffscreen(pose, { sceneBounds }) };
     });
   } finally {
@@ -106,23 +89,12 @@ export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, b
 
 // The off-loop thumbnail capture (renderMeshPayloads, behind the handle's
 // captureView) renders a THROWAWAY scene, so it gets no background from the
-// live scene's theme — and before this constant existed it set none at all,
-// which meant every thumbnail came back on the renderer's default opaque
-// black, in light mode as much as dark. One deliberately theme-INDEPENDENT
-// colour is the right answer rather than either THEME entry below: a thumbnail
-// is baked at capture time and displayed later under host chrome this renderer
-// cannot know (partforge-cloud's card grid draws them on both). Near the
-// perceptual midpoint of THEME.light.bg / THEME.dark.bg, so it commits to
-// neither, and clear of both the part material (0x9fb4cc, lighter) and the
-// feature-edge lines (0x1c232d, much darker).
-//
-// The near-ZERO chroma is the part that looks arbitrary and isn't: the default
-// part material is blue-grey, so a blue-grey background of the same value
-// (0x6b7280 was the first try) competes with it and the shaded side of a part
-// half-disappears into the plate. A neutral grey separates by hue as well as
-// value. Judged on real captures of demo.js and hinged-box.js — if this is
-// ever retuned, retune it the same way and not by eye on the hex.
-export const THUMBNAIL_BG = 0x6e6e73;
+// live scene's theme. Its background is the product-shot style's light
+// background (renderStyles.js): fixed, and never following the viewer theme,
+// because a thumbnail is baked at capture time and displayed later under host
+// chrome this renderer cannot know. Retune it in renderStyles.js, on real
+// captures against the CPU renderer's parity check, not by eye on the hex.
+export const THUMBNAIL_BG = RENDER_STYLES.thumbnail.background;
 
 // Resolve renderMeshPayloads' `background` option to what Scene.background
 // wants. Exported for its own sake: renderMeshPayloads needs a GL context and
@@ -202,8 +174,8 @@ export function createViewer(container, part) {
   // Light/dark scene palettes (the page chrome is themed separately, via CSS on the
   // host page). A part can override the dark background through meta.background.
   const THEME = {
-    dark:  { bg: part.meta?.background ?? 0x15181d, grid: [0x2c333d, 0x222831], line: 0x1c232d },
-    light: { bg: 0xe9edf2, grid: [0xc4ccd6, 0xd6dce4], line: 0x33414f },
+    dark:  { bg: part.meta?.background ?? CAD_DARK_THEME.bg, grid: [0x2c333d, 0x222831], line: CAD_DARK_THEME.line },
+    light: { bg: CAD_LIGHT_THEME.bg, grid: [0xc4ccd6, 0xd6dce4], line: CAD_LIGHT_THEME.line },
   };
   scene.background = new THREE.Color(THEME.dark.bg);
 
@@ -272,9 +244,9 @@ export function createViewer(container, part) {
 
   // --- material + part groups -----------------------------------------------
   const material = new THREE.MeshStandardMaterial({
-    color: 0x9fb4cc,
-    metalness: 0.25,
-    roughness: 0.55,
+    color: RENDER_STYLES.cad.material.color,
+    metalness: RENDER_STYLES.cad.material.metalness,
+    roughness: RENDER_STYLES.cad.material.roughness,
     flatShading: false,
     polygonOffset: true, // push the surface back so edge lines sit cleanly on top
     polygonOffsetFactor: 1,
@@ -490,6 +462,24 @@ export function createViewer(container, part) {
     return _worldBounds;
   }
 
+  // Every vertex of the visible sub-part meshes in WORLD space, flat xyz — what
+  // the canonical captures fit their framing to (getVisibleWorldBounds' meshes).
+  const _worldVertex = new THREE.Vector3();
+  function visibleWorldPositions() {
+    const meshes = Object.values(subMesh).filter((m) => m.visible && m.geometry?.attributes?.position);
+    const out = new Float32Array(meshes.reduce((n, m) => n + m.geometry.attributes.position.count * 3, 0));
+    let o = 0;
+    for (const mesh of meshes) {
+      mesh.updateWorldMatrix(true, false);
+      const pos = mesh.geometry.attributes.position;
+      for (let i = 0; i < pos.count; i++, o += 3) {
+        _worldVertex.fromBufferAttribute(pos, i).applyMatrix4(mesh.matrixWorld);
+        out[o] = _worldVertex.x; out[o + 1] = _worldVertex.y; out[o + 2] = _worldVertex.z;
+      }
+    }
+    return out;
+  }
+
   // --- depth range ------------------------------------------------------------
   // The sphere the near/far planes are sized against: everything a render will
   // actually draw, as `{ center, radius }`. `withGrid` is a parameter rather
@@ -1929,6 +1919,25 @@ export function createViewer(container, part) {
     // blue wash over it (an orange PLA sample came out pink).
     const reshowFlashDots = [];
     for (const dot of [...flashDots, ...captureHidden]) if (dot.visible) { dot.visible = false; reshowFlashDots.push(dot); }
+    // Fat lines (LineSegments2: part edges, their fade clones, the cutaway
+    // outline) take their pixel width from material.resolution, and three's
+    // LineSegments2.onBeforeRender resets that to the CANVAS viewport on every
+    // draw — so a 1px edge in a 1024² capture came out 1024/canvas px wide, under
+    // half a pixel on a high-DPI screen. For this render each visible line's hook
+    // is a no-op and each material's resolution is the target's width × height.
+    // With a viewOffset that is still width × height, not the full frame: the
+    // offset projection maps just the sub-window onto clip space, and the line
+    // shader converts its pixel width through clip space, so the pixels it
+    // counts are the target's. Put back exactly in the finally below.
+    const lineHooks = [];
+    const lineRes = new Map();
+    renderScene.traverseVisible((obj) => {
+      if (!obj.isLineSegments2) return;
+      lineHooks.push({ obj, own: Object.hasOwn(obj, "onBeforeRender"), hook: obj.onBeforeRender });
+      obj.onBeforeRender = () => {};
+      const m = obj.material;
+      if (m?.isLineMaterial && !lineRes.has(m)) { lineRes.set(m, m.resolution.clone()); m.resolution.set(width, height); }
+    });
     try {
       renderer.setRenderTarget(rt);
       renderWithBackdrop(renderScene, cam);
@@ -1945,6 +1954,8 @@ export function createViewer(container, part) {
         liveLights.fill.visible = fillWas;
       }
       for (const dot of reshowFlashDots) dot.visible = true;
+      for (const { obj, own, hook } of lineHooks) { if (own) obj.onBeforeRender = hook; else delete obj.onBeforeRender; }
+      for (const [m, res] of lineRes) m.resolution.copy(res);
       if (!cachedSize) rt.dispose();
     }
     const canvas = document.createElement("canvas");
@@ -2010,18 +2021,21 @@ export function createViewer(container, part) {
     if (!box || box.isEmpty()) return [];
     const center = box.getCenter(new THREE.Vector3()).toArray();
     const size = box.getSize(new THREE.Vector3());
-    const radius = Math.max(size.x, size.y, size.z) / 2 || 10;
+    // Framed like the CPU renderer frames the same views: the cad style's fit to
+    // the visible geometry's WORLD positions (stylePose), so a part fills the
+    // frame by its own silhouette rather than a fixed distance from its box.
+    const styleBox = { min: box.min.toArray(), max: box.max.toArray() };
+    const points = visibleWorldPositions();
     return captureViewsFromScene(viewNames, {
+      poseFor: (view) => stylePose(RENDER_STYLES.cad, view, styleBox, { aspect: 1, points }).pose,
       renderer: { renderOffscreen },
       // The live camera only to save/restore its position around the pass; the
       // renders themselves pass no `projection`, so they stay perspective.
       liveCamera: activeCamera,
       grid,
       hidden: [...canonicalCaptureHidden],
-      bounds: { center, radius },
-      // The ENCLOSING radius, which is a different number from the framing one
-      // above: a box's corners reach √3 further than half its max extent, and
-      // the depth planes have to clear the corners. A realistic capture keeps
+      // The ENCLOSING radius the depth planes must clear (half the diagonal: the
+      // box's corners, not just its faces). A realistic capture keeps
       // its ground disc, which is several part radii across, so it counts too.
       sceneBounds: (realisticRig && sceneDepthBounds()) || { center, radius: size.length() / 2 || 10 },
     });
@@ -2176,19 +2190,21 @@ export function createViewer(container, part) {
 
   // Offscreen render of an arbitrary mesh set (a non-active view), for thumbnails.
   // Assembles a THROWAWAY scene mirroring the live pivot convention, frames it from a
-  // canonical angle, renders through the parameterized renderOffscreen, and disposes
+  // canonical angle (fitted to the payloads' geometry), renders through the parameterized renderOffscreen, and disposes
   // everything. Never touches the live scene, camera, subMesh, or subCache. The scene
-  // gets THUMBNAIL_BG unless `background` says otherwise (`null` = no background, the
+  // renders the `thumbnail` style unless `style` says otherwise (the style's
+  // background unless `background` says otherwise; `null` = no background, the
   // renderer's clear colour). `payloads` is the worker's [{name, positions, normals,
   // indices, …}] array — placement is already baked into shared-frame coords, so
   // meshes are NOT recentred.
-  function renderMeshPayloads(payloads, { angle = "iso", size = 640, quality = 0.8, background } = {}) {
+  function renderMeshPayloads(payloads, { angle = "iso", size = 640, quality = 0.8, background, style = "thumbnail" } = {}) {
     if (disposed) return null; // same guard as captureCurrent/captureCanonicalViews — never touch a torn-down renderer
+    const st = getRenderStyle(style);
     const tmpScene = new THREE.Scene();
     // Deliberately the throwaway scene's own background, never the live one's:
     // this must not follow the viewer theme (see THUMBNAIL_BG) and must not
     // reach the live-scene captures, which correctly do follow it.
-    tmpScene.background = thumbnailBackground(background);
+    tmpScene.background = thumbnailBackground(background === undefined ? st.background : background);
     const tmpPivot = new THREE.Group();
     tmpPivot.rotation.x = -Math.PI / 2; // model Z (CAD up) -> vertical, same as live pivot
     tmpScene.add(tmpPivot);
@@ -2205,17 +2221,21 @@ export function createViewer(container, part) {
     // coords but rendered rotated by tmpPivot, so a model-space bbox centre would aim
     // the camera at the wrong point — an off-origin part would render off-centre or blank.
     tmpPivot.updateMatrixWorld(true);
-    const box = new THREE.Box3().setFromObject(tmpPivot);
-    const center = box.getCenter(new THREE.Vector3()).toArray();
-    const radius = box.getSize(new THREE.Vector3()).length() / 2 || 1;
-    const pose = cameraPoseForView(angle, { center, radius });
+    const b3 = new THREE.Box3().setFromObject(tmpPivot);
+    const box = b3.isEmpty() ? null : { min: b3.min.toArray(), max: b3.max.toArray() };
+    // The same world positions frame the view (fit to the geometry, not its box)
+    // and cast the contact shadow below.
+    const worldPositions = payloads.map((p) => modelToWorld(p.positions));
+    const points = new Float32Array(worldPositions.reduce((n, a) => n + a.length, 0));
+    worldPositions.reduce((o, a) => { points.set(a, o); return o + a.length; }, 0);
+    const { pose, fov, sceneBounds } = stylePose(st, angle, box, { aspect: 1, points });
 
     // Light the throwaway scene ourselves: renderOffscreen's own key/fill (and the
     // persistent hemisphere) live in the LIVE scene, which is never rendered here — so
     // without our own ambient + camera-relative key/fill it comes back near-black.
-    const hemi = createHemisphereLight();
-    const capLights = createCaptureLights();
-    const poses = captureLightPoses(pose);
+    const hemi = createHemisphereLight(st.lights);
+    const capLights = createCaptureLights(st.lights);
+    const poses = captureLightPoses(pose, st.lights);
     capLights.key.position.set(poses.key[0], poses.key[1], poses.key[2]);
     capLights.fill.position.set(poses.fill[0], poses.fill[1], poses.fill[2]);
     for (const light of [capLights.key, capLights.fill]) {
@@ -2224,25 +2244,35 @@ export function createViewer(container, part) {
     tmpScene.add(hemi, capLights.key, capLights.key.target, capLights.fill, capLights.fill.target);
 
     // Feature-edge lines, so the thumbnail carries the same hole/seam/chamfer outlines the
-    // live viewer shows. A dedicated LineMaterial at the render resolution (the live one is
-    // sized to the on-screen canvas); added after framing so it can't perturb the bbox.
-    const lineMat = new LineMaterial({ color: THEME.dark.line, linewidth: 1.0 });
-    lineMat.resolution.set(size, size);
+    // live viewer shows. A dedicated LineMaterial in the style's colour and width
+    // (renderOffscreen sizes its resolution to the target, as for every capture); added
+    // after framing so it can't perturb the bbox.
+    const lineMat = new LineMaterial({ color: st.edges.color, linewidth: st.edges.widthPx, transparent: st.edges.opacity < 1, opacity: st.edges.opacity });
     for (const mesh of built) {
       const edges = mesh.geometry.userData.edges;
-      if (edges) tmpPivot.add(new LineSegments2(edges, lineMat));
+      if (!edges) continue;
+      tmpPivot.add(new LineSegments2(edges, lineMat));
+    }
+
+    // The product shot's contact shadow, the same mask the CPU renderer samples.
+    // Only from above: a camera under the floor would see the shadow's underside.
+    let shadowPlane = null;
+    if (st.shadow && box && pose.position[1] > box.min[1]) {
+      const worldMeshes = payloads.map((p, i) => ({ positions: worldPositions[i], indices: p.indices }));
+      const mask = contactShadowMask(worldMeshes, box, st.shadow);
+      if (mask) { shadowPlane = buildContactShadowPlane(mask, st.shadow); tmpScene.add(shadowPlane); }
     }
 
     try {
       // fov comes from the PERSPECTIVE camera, deliberately, not from whichever
       // camera is live: thumbnails are canonical captures and stay perspective
-      // whichever projection is live. cameraPoseForView's distance
-      // is tuned to this fov, so a narrower one would crop long, thin parts.
+      // whichever projection is live. The fit (stylePose) solves its distance
+      // for the style's own fov, and the render must use that same fov.
       return renderOffscreen(
         pose,
         // The throwaway scene holds these meshes and nothing else — no grid, no
         // gizmo — so its own bounds are the whole of what the planes must hold.
-        { width: size, height: size, fov: camera.fov, quality, sceneBounds: { center, radius } },
+        { width: size, height: size, fov, quality, sceneBounds },
         tmpScene,
       );
     } finally {
@@ -2252,6 +2282,7 @@ export function createViewer(container, part) {
         if (mesh.material !== material) mesh.material.dispose(); // clone only — never the shared singleton
       }
       lineMat.dispose();
+      if (shadowPlane) { shadowPlane.geometry.dispose(); shadowPlane.material.alphaMap.dispose(); shadowPlane.material.dispose(); }
       hemi.dispose?.();
       capLights.key.dispose?.();
       capLights.fill.dispose?.();

package/src/testing/render.js

@@ -3,7 +3,8 @@ import { join, resolve, sep } from "node:path";
 import { safeName } from "../framework/safe-name.js";
 import { ORIENTATIONS } from "../framework/view-angles.js";
 import { buildView } from "../framework/oracle/build.js";
-import { bounds } from "../framework/oracle/mesh.js";
+import { renderStyled } from "../framework/softrender/index.js";
+import { getRenderStyle } from "../framework/renderStyles.js";
 
 // Canonical view directions in MODEL space (Z-up). `dir` is the direction from
 // the part centre toward the camera; `up` is the camera up vector.
@@ -35,34 +36,28 @@ export function renderAngle(name) {
   return { dir: toModel(o.dir), up: toModel(o.up) };
 }
 
-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 dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
-const norm = (a) => { const l = Math.hypot(a[0], a[1], a[2]) || 1; return [a[0] / l, a[1] / l, a[2] / l]; };
 
-// Render canonical-angle PNGs of one view of a part with a pure-JS software
-// rasterizer (orthographic, z-buffered, Lambert-shaded, with depth-tested edge
-// overlays). No native module, no browser. Returns the written file paths.
-// pngjs is lazy-imported so importing the testing barrel for measure never loads it.
+// Render canonical-angle PNGs of one view of a part, in memory, through the
+// styled CPU renderer (framework/softrender) — the same look the viewer's
+// offscreen captures have (`style`: "cad" for the agent's renders, "thumbnail"
+// for the product shot). No native module, no browser. pngjs is lazy-imported
+// so importing the testing barrel for measure never loads it.
 //
-// `opacity` is a Record<subPartName, number> (an animation's evaluate() output,
-// typically): a sub-part at 0 is skipped entirely — faces AND edges — but it
-// still counts toward the SCENE BOUNDS, so a part crossing 0 cannot silently
-// reframe the still. Framing is a property of the pose, not of what happens to
-// be visible: without that, `--at 0,0.5,1` over a fade drew the same base at
-// three different scales and the sequence read as a zoom.
-// Values in (0,1) fade by PRE-BLENDING that part's shaded base and edge
-// colours toward the background. That is a z-buffered approximation: a faded
-// part still fully occludes whatever is behind it, because real transparency
-// needs back-to-front sorting this rasterizer does not do. Stills only need to
-// read as faded, so the approximation is the contract, not a stopgap.
-export async function renderViews(kernel, part, view = Object.keys(part.views)[0], {
-  views = ["iso", "front", "top"], out = "render", size = [800, 600], edges = true, params = {}, tag = "",
-  opacity = {},
+// `opacity` is a Record<subPartName, number> (an animation's evaluate()
+// output, typically): a sub-part at 0 draws nothing — faces, edges, shadow —
+// but still counts toward the FRAMING, so a part crossing 0 cannot silently
+// reframe the still. Values in (0,1) PRE-BLEND toward the background: a faded
+// part still occludes what is behind it (real transparency needs a depth sort
+// this renderer does not do; stills only need to read as faded).
+export async function renderViewImages(kernel, part, view = Object.keys(part.views)[0], {
+  views = ["iso", "front", "top"], size = [800, 600], edges = true, params = {}, opacity = {},
+  style = "cad", supersample = 2,
 } = {}) {
   const { PNG } = await import("pngjs");
-  const [W, H] = size;
-  // Sub-part names are kept alongside the meshes: opacity is keyed by name.
+  getRenderStyle(style); // a bad style fails here, before the kernel build
+  for (const angle of views) {
+    if (!renderAngle(angle)) throw new Error(`unknown angle "${angle}" (use: ${RENDER_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left)`);
+  }
   // Own-key lookups only — a part named "constructor" must not inherit a value
   // off Object.prototype and vanish from the render.
   const opacityOf = (name) => {
@@ -70,165 +65,34 @@ export async function renderViews(kernel, part, view = Object.keys(part.views)[0
     const v = Number(opacity[name]);
     return Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 1; // a junk value renders solid
   };
-  const built = buildView(kernel, part, view, params) // copied out
-    .map((b) => ({ name: b.name, mesh: b.mesh }));
-
-  // Scene bounds over EVERY built sub-part, visible or not (positions are
-  // JS-owned; safe after cleanup). Opacity is deliberately NOT consulted here —
-  // see the note above on why a fade must not move the camera.
-  const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
-  for (const { mesh: m } of built) {
-    const b = bounds(m.positions);
-    for (let i = 0; i < 3; i++) { lo[i] = Math.min(lo[i], b.min[i]); hi[i] = Math.max(hi[i], b.max[i]); }
-  }
-  // kernel.cleanup() walks the backend's own tracked list, not this array, so
-  // dropping the hidden sub-parts afterwards frees nothing and skips nothing.
+  const subparts = buildView(kernel, part, view, params) // meshes are JS-owned: safe after cleanup
+    .map((b) => ({ name: b.name, mesh: b.mesh, display: part.parts?.[b.name]?.display, opacity: opacityOf(b.name) }));
   kernel.cleanup?.();
+  return views.map((angle) => {
+    const img = renderStyled(subparts, { view: angle, style, size, supersample, edges });
+    const png = new PNG({ width: img.width, height: img.height });
+    png.data.set(img.rgba);
+    return { angle, png: PNG.sync.write(png) };
+  });
+}
 
-  // …and only the visible ones are rasterized: faces AND edges below iterate this.
-  const meshes = built.filter(({ name }) => opacityOf(name) > 0);
-
-  const center = [(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, (lo[2] + hi[2]) / 2];
-  const radius = Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) / 2 || 5;
-
-  const bg = [0x15, 0x18, 0x1d], base = [0x9f, 0xb4, 0xcc], edgeColor = [0x1c, 0x23, 0x2d];
-  const ambient = 0.35, diffuse = 0.75;
-  const bias = radius * 0.02;           // edge depth bias so visible edges win ties
-
+// renderViewImages, written to disk as `<title>-<view>-<angle>[-<tag>].png`
+// under `out`. Returns the written paths (relative to `out`, as the CLI echoes them).
+export async function renderViews(kernel, part, view = Object.keys(part.views)[0], opts = {}) {
+  const { out = "render", tag = "", ...rest } = opts;
+  const images = await renderViewImages(kernel, part, view, rest);
   // `out` is operator-supplied (a CLI flag) and stays verbatim; the part-derived
-  // title and view key are sanitized, since this is the one place a part's
+  // title, view key and frame tag are sanitized — the one place a part's
   // strings reach the filesystem.
   const outDir = resolve(out);
   mkdirSync(outDir, { recursive: true });
   const name = safeName(part.meta?.title ?? view);
   const viewName = safeName(view);
-  const written = [];
-
-  for (const angle of views) {
-    const a = renderAngle(angle);
-    if (!a) throw new Error(`unknown angle "${angle}" (use: ${RENDER_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left)`);
-    // orthographic camera basis: zc toward camera, xc right, yc up
-    const zc = norm(a.dir), xc = norm(cross(a.up, zc)), yc = cross(zc, xc);
-    // Key direction (toward the light), placed over the viewer's shoulder — up and to
-    // the right of the view axis — so every angle is lit and shaded. A world-fixed key
-    // would leave whichever face the camera happens to be looking at in flat ambient:
-    // that is what made `bottom` a featureless disc, and the browser viewer's offscreen
-    // captures had the same bug (framework/viewer-lighting.js captureLightPoses).
-    const light = norm([0, 1, 2].map((i) => zc[i] + 0.45 * xc[i] + 0.75 * yc[i]));
-    const ppu = Math.min(W, H) / (2 * radius * 1.25); // pixels per mm (uniform; margin)
-    const project = (p) => {
-      const r = sub(p, center);
-      return [W / 2 + dot(r, xc) * ppu, H / 2 - dot(r, yc) * ppu, dot(r, zc)]; // [sx, sy, depth]
-    };
-
-    const color = new Uint8Array(W * H * 3);
-    for (let i = 0; i < W * H; i++) { color[i * 3] = bg[0]; color[i * 3 + 1] = bg[1]; color[i * 3 + 2] = bg[2]; }
-    const zbuf = new Float32Array(W * H).fill(-Infinity); // larger depth = nearer camera
-
-    for (const { name, mesh: m } of meshes) {
-      // Pre-blend toward the background: the fade is baked into the material
-      // colour before shading, so no per-pixel compositing (and no depth sort)
-      // is needed. See the note on renderViews for why that is enough here.
-      const v = opacityOf(name);
-      const faded = v < 1 ? base.map((c, i) => Math.round(c * v + bg[i] * (1 - v))) : base;
-      const P = m.positions, N = m.normals, ind = m.indices;
-      // Manifold meshes are a non-indexed soup (3 consecutive verts/triangle);
-      // OCCT meshes are indexed. Both carry per-vertex normals.
-      const triCount = ind?.length ? ind.length / 3 : P.length / 9;
-      for (let t = 0; t < triCount; t++) {
-        const ai = ind?.length ? ind[t * 3] * 3 : t * 9;
-        const bi = ind?.length ? ind[t * 3 + 1] * 3 : t * 9 + 3;
-        const ci = ind?.length ? ind[t * 3 + 2] * 3 : t * 9 + 6;
-        const va = [P[ai], P[ai + 1], P[ai + 2]], vb = [P[bi], P[bi + 1], P[bi + 2]], vc = [P[ci], P[ci + 1], P[ci + 2]];
-        const sp = [va, vb, vc].map(project);
-        let inten;
-        if (N?.length) {
-          // per-vertex normals (same layout/offset as positions)
-          inten = [ai, bi, ci].map((o) =>
-            Math.min(1, ambient + diffuse * Math.max(0, N[o] * light[0] + N[o + 1] * light[1] + N[o + 2] * light[2])));
-        } else {
-          // no normals → flat face normal, two-sided so it lights regardless of winding
-          const ux = vb[0] - va[0], uy = vb[1] - va[1], uz = vb[2] - va[2];
-          const wx = vc[0] - va[0], wy = vc[1] - va[1], wz = vc[2] - va[2];
-          const nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx;
-          const L = Math.hypot(nx, ny, nz) || 1;
-          const I0 = Math.min(1, ambient + diffuse * Math.abs((nx * light[0] + ny * light[1] + nz * light[2]) / L));
-          inten = [I0, I0, I0];
-        }
-        rasterTri(sp, inten, faded, color, zbuf, W, H);
-      }
-    }
-
-    if (edges) {
-      for (const { name, mesh: m } of meshes) {
-        const E = m.edges;
-        if (!E?.length) continue;
-        const v = opacityOf(name);
-        const fadedEdge = v < 1 ? edgeColor.map((c, i) => Math.round(c * v + bg[i] * (1 - v))) : edgeColor;
-        for (let i = 0; i < E.length; i += 6)
-          drawLine(project([E[i], E[i + 1], E[i + 2]]), project([E[i + 3], E[i + 4], E[i + 5]]), fadedEdge, color, zbuf, W, H, bias);
-      }
-    }
-
-    const png = new PNG({ width: W, height: H });
-    for (let i = 0; i < W * H; i++) {
-      png.data[i * 4] = color[i * 3]; png.data[i * 4 + 1] = color[i * 3 + 1]; png.data[i * 4 + 2] = color[i * 3 + 2]; png.data[i * 4 + 3] = 255;
-    }
-    // The animation frame tag goes through safeName() as well — one rule for
-    // every string that reaches a filename here.
+  return images.map(({ angle, png }) => {
     const file = join(out, `${name}-${viewName}-${angle}${tag ? `-${safeName(tag)}` : ""}.png`);
-    // Belt and braces over safeName(): assert the escape never happened rather
-    // than trusting the slug, because a miss here writes bytes to disk. (The
-    // returned paths stay relative to `out` — the CLI echoes them.)
+    // Belt and braces over safeName(): assert the escape never happened.
     if (!resolve(file).startsWith(outDir + sep)) throw new Error(`renderViews: refusing to write outside ${out}`);
-    writeFileSync(file, PNG.sync.write(png));
-    written.push(file);
-  }
-  return written;
-}
-
-// signed area of the 2-D edge from a to b evaluated at p (for barycentric coords)
-const edgeFn = (a, b, p) => (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]);
-
-// Fill one projected triangle, z-buffered, with Gouraud-interpolated Lambert shading.
-function rasterTri(sp, inten, base, color, zbuf, W, H) {
-  const [a, b, c] = sp;
-  const area = edgeFn(a, b, c);
-  if (Math.abs(area) < 1e-9) return;
-  const minX = Math.max(0, Math.floor(Math.min(a[0], b[0], c[0])));
-  const maxX = Math.min(W - 1, Math.ceil(Math.max(a[0], b[0], c[0])));
-  const minY = Math.max(0, Math.floor(Math.min(a[1], b[1], c[1])));
-  const maxY = Math.min(H - 1, Math.ceil(Math.max(a[1], b[1], c[1])));
-  for (let y = minY; y <= maxY; y++) {
-    for (let x = minX; x <= maxX; x++) {
-      const p = [x + 0.5, y + 0.5];
-      const w0 = edgeFn(b, c, p), w1 = edgeFn(c, a, p), w2 = edgeFn(a, b, p);
-      // inside if all the same sign (handle either winding from the projection)
-      if (!((w0 >= 0 && w1 >= 0 && w2 >= 0) || (w0 <= 0 && w1 <= 0 && w2 <= 0))) continue;
-      const l0 = w0 / area, l1 = w1 / area, l2 = w2 / area;
-      const depth = l0 * a[2] + l1 * b[2] + l2 * c[2];
-      const idx = y * W + x;
-      if (depth <= zbuf[idx]) continue;
-      zbuf[idx] = depth;
-      const I = l0 * inten[0] + l1 * inten[1] + l2 * inten[2];
-      color[idx * 3] = Math.min(255, base[0] * I);
-      color[idx * 3 + 1] = Math.min(255, base[1] * I);
-      color[idx * 3 + 2] = Math.min(255, base[2] * I);
-    }
-  }
-}
-
-// Depth-tested line for edge overlays: drawn only where it isn't behind the
-// surface (within `bias`), so the silhouette and feature edges read as crisp lines.
-function drawLine(p0, p1, col, color, zbuf, W, H, bias) {
-  const steps = Math.max(1, Math.ceil(Math.max(Math.abs(p1[0] - p0[0]), Math.abs(p1[1] - p0[1]))));
-  for (let s = 0; s <= steps; s++) {
-    const t = s / steps;
-    const x = Math.round(p0[0] + (p1[0] - p0[0]) * t), y = Math.round(p0[1] + (p1[1] - p0[1]) * t);
-    if (x < 0 || x >= W || y < 0 || y >= H) continue;
-    const depth = p0[2] + (p1[2] - p0[2]) * t;
-    const idx = y * W + x;
-    if (depth + bias < zbuf[idx]) continue; // occluded
-    color[idx * 3] = col[0]; color[idx * 3 + 1] = col[1]; color[idx * 3 + 2] = col[2];
-  }
+    writeFileSync(file, png);
+    return file;
+  });
 }

package/src/testing.js

@@ -15,7 +15,8 @@ export { resolveDerived } from "./framework/derive.js";
 export { relevantParamKeys, RELEVANT_ALL } from "./framework/param-deps.js";
 export { assemblyOverlaps } from "./framework/assembly.js";
 export { bootOcctKernel } from "./testing/occt.js";
-export { renderViews, RENDER_VIEWS } from "./testing/render.js";
+export { renderViews, renderViewImages, RENDER_VIEWS } from "./testing/render.js";
+export { RENDER_STYLES } from "./framework/renderStyles.js";
 // The whole oracle surface (measure/verify/buildView, gaps/BVH/min-wall, silhouette
 // match scoring, and the semantic mesh oracle) comes through partforge/oracle — one
 // list of names, two doors. See src/oracle.js for what each group is.

package/types/index.d.ts

@@ -426,6 +426,8 @@ export interface CaptureViewOptions {
   quality?: number;
   /** Canonical angle to render from. Default `"iso"`. */
   angle?: CanonicalView | string;
+  /** Capture style. `"thumbnail"` (the default) is the light product shot with a contact shadow; `"cad"` is the agent-facing CAD look. */
+  style?: "cad" | "thumbnail";
 }
 
 /**

package/types/testing.d.ts

@@ -668,7 +668,7 @@ export function matchViews(
 export const RENDER_VIEWS: string[];
 
 /**
- * Render canonical-angle PNGs of one view with a pure-JS software rasterizer —
+ * Render canonical-angle PNGs of one view with the styled pure-JS renderer —
  * no native module, no browser. Returns the written file paths.
  */
 export function renderViews(
@@ -689,9 +689,35 @@ export function renderViews(
      * background. Absent keys render solid.
      */
     opacity?: Record<string, number>;
+    style?: "cad" | "thumbnail";
+    /** Samples per pixel per axis (default 2). */
+    supersample?: number;
   },
 ): Promise<string[]>;
 
+/** The built-in capture looks: "cad" (agent renders) and "thumbnail" (product shot). */
+export const RENDER_STYLES: Readonly<Record<"cad" | "thumbnail", unknown>>;
+
+/**
+ * Render canonical-angle PNGs of one view in memory with the styled pure-JS
+ * renderer — the same looks as the viewer's offscreen captures.
+ */
+export function renderViewImages(
+  kernel: GeometryKernel,
+  part: PartDefinition,
+  view?: string,
+  opts?: {
+    views?: string[];
+    size?: [number, number];
+    edges?: boolean;
+    params?: ResolvedParams;
+    opacity?: Record<string, number>;
+    style?: "cad" | "thumbnail";
+    /** Samples per pixel per axis (default 2). */
+    supersample?: number;
+  },
+): Promise<{ angle: string; png: Uint8Array }[]>;
+
 // --- sketch-annotation rays --------------------------------------------------
 export interface AnnotationRay { origin: [number, number, number]; dir: [number, number, number] }
 export interface RayPlaneHit { point: [number, number, number]; t: number }