partforge 0.136.0 → 0.137.0

package/src/framework/softrender/index.js

@@ -0,0 +1,136 @@
+// src/framework/softrender/index.js
+// renderStyled: one view of a set of sub-part meshes in a named capture style
+// (renderStyles.js), as raw sRGB RGBA. The CPU twin of the viewer's offscreen
+// captures: same framing (style-camera.js), same lights and material model
+// (shade.js), same contact shadow (contact-shadow.js). Encoding is the
+// caller's. Opacity keeps the old contract: pre-blended toward the
+// background, still occluding — real transparency is out of scope.
+import { getRenderStyle, srgbHexToLinear, SRGB8 } from "../renderStyles.js";
+import { stylePose, modelToWorld, boundsOf } from "../style-camera.js";
+import { contactShadowMask, sampleShadowMask } from "../contact-shadow.js";
+import { cadAppearance, hasAppearance } from "../materials/resolve.js";
+import { makeCamera } from "./camera.js";
+import { createGBuffer, rasterizeMesh } from "./raster.js";
+import { prepareMaterial, prepareLights, shade } from "./shade.js";
+import { drawEdges } from "./edges.js";
+
+const NORMAL_SAME = 0.9995; // samples this aligned share one shading evaluation
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+export function renderStyled(subparts, { view, style = "cad", size = [1024, 1024], supersample = 2, edges = true } = {}) {
+  const st = getRenderStyle(style);
+  const angle = view ?? st.view ?? "iso";
+  const [W, H] = size;
+  const ss = Math.round(supersample);
+  if (!Number.isFinite(ss) || ss < 1) throw new Error("renderStyled: supersample must be a positive integer");
+  const WS = W * ss, HS = H * ss;
+
+  const parts = subparts.map((sp) => {
+    const opacity = Number.isFinite(sp.opacity) ? clamp01(sp.opacity) : 1;
+    const look = hasAppearance(sp.display) ? cadAppearance(sp.display) : { ...st.material, opacity: 1 };
+    return {
+      positions: modelToWorld(sp.mesh.positions ?? []),
+      normals: sp.mesh.normals?.length ? modelToWorld(sp.mesh.normals) : null,
+      indices: sp.mesh.indices,
+      edges: sp.mesh.edges?.length ? modelToWorld(sp.mesh.edges) : null,
+      opacity: opacity * (Number.isFinite(look.opacity) ? look.opacity : 1),
+      material: prepareMaterial(look),
+    };
+  });
+  // Framing counts EVERY sub-part, visible or not: a fade must not reframe.
+  const box = boundsOf(parts.map((p) => p.positions));
+  const points = new Float32Array(parts.reduce((n, p) => n + p.positions.length, 0));
+  parts.reduce((o, p) => { points.set(p.positions, o); return o + p.positions.length; }, 0);
+  const { pose, fov, sceneBounds } = stylePose(st, angle, box, { aspect: W / H, points });
+  const cam = makeCamera(pose, { fov, width: WS, height: HS });
+  const visible = parts.map((p, i) => ({ ...p, owner: i })).filter((p) => p.opacity > 0);
+
+  const gb = createGBuffer(WS, HS);
+  for (const p of visible) rasterizeMesh(gb, cam, { positions: p.positions, normals: p.normals, indices: p.indices }, p.owner);
+
+  const bg = srgbHexToLinear(st.background);
+  const lights = prepareLights(st.lights, pose);
+  const color = new Float32Array(WS * HS * 3);
+
+  // Shadow: only from visible geometry, only seen from above the floor.
+  const mask = st.shadow && box && pose.position[1] > box.min[1]
+    ? contactShadowMask(visible.map((p) => ({ positions: p.positions, indices: p.indices })), box, st.shadow)
+    : null;
+
+  const N = [0, 0, 0], V = [0, 0, 0], R = [0, 0, 0], tmp = new Float32Array(3);
+  const background = (k, sx, sy) => {
+    let a = 0;
+    if (mask) {
+      const r = cam.ray(sx, sy, R);
+      if (r[1] < 0) {
+        const t = (mask.y - cam.position[1]) / r[1];
+        a = sampleShadowMask(mask, cam.position[0] + r[0] * t, cam.position[2] + r[2] * t) * st.shadow.opacity;
+      }
+    }
+    color[k * 3] = bg[0] * (1 - a); color[k * 3 + 1] = bg[1] * (1 - a); color[k * 3 + 2] = bg[2] * (1 - a);
+  };
+  const surface = (k, owner, sx, sy, out, o) => {
+    N[0] = gb.normal[k * 3]; N[1] = gb.normal[k * 3 + 1]; N[2] = gb.normal[k * 3 + 2];
+    const r = cam.ray(sx, sy, R);
+    const l = Math.hypot(r[0], r[1], r[2]);
+    V[0] = -r[0] / l; V[1] = -r[1] / l; V[2] = -r[2] / l;
+    const p = parts[owner];
+    shade(N, V, p.material, lights, out, o);
+    if (p.opacity < 1) for (let c = 0; c < 3; c++) out[o + c] = bg[c] + (out[o + c] - bg[c]) * p.opacity;
+  };
+
+  // Shade per output pixel; a pixel whose samples all belong to one sub-part
+  // with near-identical normals is shaded once (most of the image), others
+  // per sample (silhouettes, creases). Same picture, far fewer evaluations.
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    const k0 = (y * ss) * WS + x * ss;
+    const owner0 = gb.owner[k0];
+    let uniform = owner0 >= 0;
+    for (let j = 0; j < ss && uniform; j++) for (let i = 0; i < ss && uniform; i++) {
+      const k = (y * ss + j) * WS + x * ss + i;
+      if (gb.owner[k] !== owner0) uniform = false;
+      else {
+        const d = gb.normal[k * 3] * gb.normal[k0 * 3] + gb.normal[k * 3 + 1] * gb.normal[k0 * 3 + 1] + gb.normal[k * 3 + 2] * gb.normal[k0 * 3 + 2];
+        if (d < NORMAL_SAME) uniform = false;
+      }
+    }
+    if (uniform) {
+      surface(k0, owner0, (x + 0.5) * ss, (y + 0.5) * ss, tmp, 0);
+      for (let j = 0; j < ss; j++) for (let i = 0; i < ss; i++) color.set(tmp, ((y * ss + j) * WS + x * ss + i) * 3);
+    } else {
+      for (let j = 0; j < ss; j++) for (let i = 0; i < ss; i++) {
+        const k = (y * ss + j) * WS + x * ss + i;
+        const sx = x * ss + i + 0.5, sy = y * ss + j + 0.5;
+        if (gb.owner[k] < 0) background(k, sx, sy);
+        else surface(k, gb.owner[k], sx, sy, color, k * 3);
+      }
+    }
+  }
+
+  if (edges) {
+    const edgeRgb = srgbHexToLinear(st.edges.color);
+    const bias = sceneBounds.radius * 0.01;
+    for (const p of visible) {
+      const rgb = p.opacity < 1 ? edgeRgb.map((c, i) => bg[i] + (c - bg[i]) * p.opacity) : edgeRgb;
+      drawEdges(color, gb, cam, p.edges, rgb, st.edges.opacity, st.edges.widthPx, ss, bias);
+    }
+  }
+
+  // Resolve: average linear samples (as an MSAA resolve does), quantize to a
+  // linear byte, then the same sRGB LUT the viewer's readback uses.
+  const rgba = new Uint8ClampedArray(W * H * 4);
+  const inv = 1 / (ss * ss);
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) {
+    let r = 0, g = 0, b = 0;
+    for (let j = 0; j < ss; j++) for (let i = 0; i < ss; i++) {
+      const o = ((y * ss + j) * WS + x * ss + i) * 3;
+      r += color[o]; g += color[o + 1]; b += color[o + 2];
+    }
+    const q = (y * W + x) * 4;
+    rgba[q] = SRGB8[Math.round(clamp01(r * inv) * 255)];
+    rgba[q + 1] = SRGB8[Math.round(clamp01(g * inv) * 255)];
+    rgba[q + 2] = SRGB8[Math.round(clamp01(b * inv) * 255)];
+    rgba[q + 3] = 255;
+  }
+  return { width: W, height: H, rgba, view: angle };
+}

package/src/framework/softrender/raster.js

@@ -0,0 +1,78 @@
+// Triangle rasterizer into a G-buffer: nearest view depth, perspective-correct
+// interpolated normal, and which sub-part owns each sample. No culling — the
+// z-buffer resolves closed meshes, and a no-normals mesh gets a two-sided face
+// normal turned toward the camera. A triangle crossing the near plane is
+// skipped: the framing keeps the camera well outside the part, so only
+// degenerate input can produce one, and clipping it buys nothing here.
+import { triangleCount } from "./triangles.js";
+
+export const NEAR = 1e-3;
+
+export function createGBuffer(width, height) {
+  const n = width * height;
+  return { width, height, depth: new Float32Array(n).fill(Infinity), normal: new Float32Array(n * 3), owner: new Int16Array(n).fill(-1) };
+}
+
+const edge = (ax, ay, bx, by, px, py) => (bx - ax) * (py - ay) - (by - ay) * (px - ax);
+
+export function rasterizeMesh(gb, cam, mesh, owner) {
+  const P = mesh.positions, N = mesh.normals?.length ? mesh.normals : null;
+  const { width: W, height: H, depth, normal, owner: own } = gb;
+  const n = triangleCount(mesh);
+  const I = mesh.indices?.length ? mesh.indices : null;
+  const a = [0, 0, 0], b = [0, 0, 0], c = [0, 0, 0]; // scratch: no per-vertex allocation
+  for (let t = 0; t < n; t++) {
+    // triangleOffsets, inlined: its returned array was a per-triangle allocation
+    const ai = I ? I[t * 3] * 3 : t * 9, bi = I ? I[t * 3 + 1] * 3 : t * 9 + 3, ci = I ? I[t * 3 + 2] * 3 : t * 9 + 6;
+    cam.project(P[ai], P[ai + 1], P[ai + 2], a);
+    cam.project(P[bi], P[bi + 1], P[bi + 2], b);
+    cam.project(P[ci], P[ci + 1], P[ci + 2], c);
+    if (a[2] < NEAR || b[2] < NEAR || c[2] < NEAR) continue;
+    const area = edge(a[0], a[1], b[0], b[1], c[0], c[1]);
+    if (Math.abs(area) < 1e-12) continue;
+    const invArea = 1 / area;
+
+    let fx = 0, fy = 0, fz = 0;
+    if (!N) {
+      const ux = P[bi] - P[ai], uy = P[bi + 1] - P[ai + 1], uz = P[bi + 2] - P[ai + 2];
+      const vx = P[ci] - P[ai], vy = P[ci + 1] - P[ai + 1], vz = P[ci + 2] - P[ai + 2];
+      fx = uy * vz - uz * vy; fy = uz * vx - ux * vz; fz = ux * vy - uy * vx;
+      const l = Math.hypot(fx, fy, fz) || 1; fx /= l; fy /= l; fz /= l;
+      // turn toward the camera: compare with the direction to the camera
+      const tx = cam.position[0] - P[ai], ty = cam.position[1] - P[ai + 1], tz = cam.position[2] - P[ai + 2];
+      if (fx * tx + fy * ty + fz * tz < 0) { fx = -fx; fy = -fy; fz = -fz; }
+    }
+
+    const wa = 1 / a[2], wb = 1 / b[2], wc = 1 / c[2];
+    const x0 = Math.max(0, Math.floor(Math.min(a[0], b[0], c[0]))), x1 = Math.min(W - 1, Math.ceil(Math.max(a[0], b[0], c[0])));
+    const y0 = Math.max(0, Math.floor(Math.min(a[1], b[1], c[1]))), y1 = Math.min(H - 1, Math.ceil(Math.max(a[1], b[1], c[1])));
+    // Barycentrics are affine in screen space: step them per pixel instead of
+    // re-evaluating both edge functions (the dominant cost on dense meshes).
+    const d0x = -(c[1] - b[1]) * invArea, d1x = -(a[1] - c[1]) * invArea;
+    for (let y = y0; y <= y1; y++) {
+      const py = y + 0.5, px0 = x0 + 0.5;
+      // dividing by the signed area makes "inside" non-negative for either winding
+      let l0 = edge(b[0], b[1], c[0], c[1], px0, py) * invArea;
+      let l1 = edge(c[0], c[1], a[0], a[1], px0, py) * invArea;
+      for (let x = x0; x <= x1; x++, l0 += d0x, l1 += d1x) {
+        const l2 = 1 - l0 - l1;
+        if (l0 < 0 || l1 < 0 || l2 < 0) continue;
+        const inv = l0 * wa + l1 * wb + l2 * wc;
+        const z = 1 / inv;
+        const k = y * W + x;
+        if (z >= depth[k]) continue;
+        depth[k] = z; own[k] = owner;
+        if (N) {
+          const p0 = (l0 * wa) / inv, p1 = (l1 * wb) / inv, p2 = (l2 * wc) / inv;
+          let nx = p0 * N[ai] + p1 * N[bi] + p2 * N[ci];
+          let ny = p0 * N[ai + 1] + p1 * N[bi + 1] + p2 * N[ci + 1];
+          let nz = p0 * N[ai + 2] + p1 * N[bi + 2] + p2 * N[ci + 2];
+          const l = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+          normal[k * 3] = nx / l; normal[k * 3 + 1] = ny / l; normal[k * 3 + 2] = nz / l;
+        } else {
+          normal[k * 3] = fx; normal[k * 3 + 1] = fy; normal[k * 3 + 2] = fz;
+        }
+      }
+    }
+  }
+}

package/src/framework/softrender/shade.js

@@ -0,0 +1,96 @@
+// Per-sample shading = three.js MeshStandardMaterial under a HemisphereLight
+// and two DirectionalLights, no environment map, no tone mapping (the CAD and
+// thumbnail captures render LDR, linear). Ported from three r184's shader
+// chunks (common, lights_physical_pars_fragment, lights_pars_begin,
+// lights_physical_fragment); if three changes them, re-port — the parity
+// script is what notices.
+//
+// r184 differs from the classic Lambert + GGX picture even with no env map:
+// direct specular carries a multiscattering term that reads the DFG LUT.
+// Not ported: `geometryRoughness` (a screen-space derivative of the geometric
+// normal, nonzero only across creases / smooth-normal gradients).
+import { srgbHexToLinear } from "../renderStyles.js";
+import { captureLightPoses } from "../style-camera.js";
+import { dfgLut } from "./dfgLut.js";
+
+const RECIPROCAL_PI = 1 / Math.PI;
+const EPSILON = 1e-6;
+const FAVG_K = 0.047619; // 1/21
+const sat = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+
+export function prepareMaterial({ color, metalness, roughness }) {
+  const base = srgbHexToLinear(color);
+  return {
+    diffuse: base.map((c) => c * (1 - metalness)), // diffuseContribution
+    f0: base.map((c) => 0.04 * (1 - metalness) + c * metalness), // specularColorBlended
+    roughness: Math.min(Math.max(roughness, 0.0525), 1),
+  };
+}
+
+export function prepareLights(lights, pose) {
+  const poses = captureLightPoses(pose, lights);
+  const lin = (hex, k) => srgbHexToLinear(hex).map((c) => c * k);
+  const dirTo = (p) => {
+    const d = [p[0] - pose.target[0], p[1] - pose.target[1], p[2] - pose.target[2]];
+    const l = Math.hypot(...d) || 1;
+    return d.map((c) => c / l);
+  };
+  return {
+    sky: lin(lights.hemisphere.sky, lights.hemisphere.intensity),
+    ground: lin(lights.hemisphere.ground, lights.hemisphere.intensity),
+    up: [0, 1, 0],
+    directional: [
+      { dir: dirTo(poses.key), color: lin(lights.key.color, lights.key.intensity) },
+      { dir: dirTo(poses.fill), color: lin(lights.fill.color, lights.fill.intensity) },
+    ],
+  };
+}
+
+export function shade(N, V, mat, lights, out, o) {
+  const { diffuse, f0, roughness } = mat;
+  const dotNV = sat(N[0] * V[0] + N[1] * V[1] + N[2] * V[2]);
+  const dfgV = dfgLut(roughness, dotNV);
+  const EssV = dfgV[0] + dfgV[1];
+  const EmsV = 1 - EssV;
+  const col = [0, 0, 0];
+
+  // Indirect: hemisphere irradiance only reaches RE_IndirectDiffuse. three
+  // passes RE_IndirectSpecular the env-map irradiance/radiance, both 0 here,
+  // so it contributes nothing without an environment map.
+  const w = 0.5 * (N[0] * lights.up[0] + N[1] * lights.up[1] + N[2] * lights.up[2]) + 0.5;
+  for (let i = 0; i < 3; i++) {
+    const irr = lights.ground[i] + (lights.sky[i] - lights.ground[i]) * w;
+    col[i] = irr * diffuse[i] * RECIPROCAL_PI;
+  }
+
+  const alpha = roughness * roughness, a2 = alpha * alpha;
+  for (const { dir: L, color } of lights.directional) {
+    const dotNL = sat(N[0] * L[0] + N[1] * L[1] + N[2] * L[2]);
+    if (dotNL <= 0) continue;
+    let hx = L[0] + V[0], hy = L[1] + V[1], hz = L[2] + V[2];
+    const hl = Math.hypot(hx, hy, hz) || 1; hx /= hl; hy /= hl; hz /= hl;
+    const dotNH = sat(N[0] * hx + N[1] * hy + N[2] * hz);
+    const dotVH = sat(V[0] * hx + V[1] * hy + V[2] * hz);
+    // F_Schlick, three's exp2 form, f90 = 1
+    const fresnel = 2 ** ((-5.55473 * dotVH - 6.98316) * dotVH);
+    // V_GGX_SmithCorrelated
+    const gv = dotNL * Math.sqrt(a2 + (1 - a2) * dotNV * dotNV);
+    const gl = dotNV * Math.sqrt(a2 + (1 - a2) * dotNL * dotNL);
+    const vis = 0.5 / Math.max(gv + gl, EPSILON);
+    // D_GGX
+    const denom = dotNH * dotNH * (a2 - 1) + 1;
+    const D = (RECIPROCAL_PI * a2) / (denom * denom);
+    const sv = vis * D;
+    // BRDF_GGX_Multiscatter's compensation (Turquin)
+    const dfgL = dfgLut(roughness, dotNL);
+    const EmsL = 1 - (dfgL[0] + dfgL[1]);
+    for (let i = 0; i < 3; i++) {
+      const single = (f0[i] * (1 - fresnel) + fresnel) * sv;
+      const favg = f0[i] + (1 - f0[i]) * FAVG_K;
+      const fssV = f0[i] * dfgV[0] + dfgV[1], fssL = f0[i] * dfgL[0] + dfgL[1];
+      const multi = ((fssV * fssL * favg) / (1 - EmsV * EmsL * favg + EPSILON)) * EmsV * EmsL;
+      col[i] += dotNL * color[i] * (diffuse[i] * RECIPROCAL_PI + single + multi);
+    }
+  }
+  out[o] = col[0]; out[o + 1] = col[1]; out[o + 2] = col[2];
+}

package/src/framework/softrender/triangles.js

@@ -0,0 +1,9 @@
+// Manifold meshes are a non-indexed soup (3 consecutive vertices per
+// triangle); OCCT meshes are indexed. Offsets returned are into the flat
+// positions/normals arrays (vertex index × 3).
+export const triangleCount = (m) => (m.indices?.length ? m.indices.length / 3 : (m.positions?.length ?? 0) / 9) | 0;
+
+export function triangleOffsets(m, t) {
+  if (m.indices?.length) return [m.indices[t * 3] * 3, m.indices[t * 3 + 1] * 3, m.indices[t * 3 + 2] * 3];
+  return [t * 9, t * 9 + 3, t * 9 + 6];
+}

package/src/framework/style-camera.js

@@ -0,0 +1,174 @@
+// Where a styled capture puts its camera, for BOTH renderers: the viewer's
+// captures (its throwaway thumbnail scene and its live-scene agent renders)
+// and the CPU renderer call this one function, so they frame every view
+// identically. World space is the viewer's Y-up frame
+// (the pivot's rotation.x = -PI/2 maps model (x, y, z) -> world (x, z, -y)).
+// Pure — no three.js.
+import { cameraPoseForView } from "./view-angles.js";
+import { RENDER_STYLES } from "./renderStyles.js";
+
+const DEFAULT_RADIUS = 10; // the viewer's own `|| 10` fallback for an empty box
+const RECENTER_PASSES = 3; // fitPoseToPoints' recentre/re-solve rounds (see there)
+
+export function modelToWorld(arr) {
+  const out = new Float32Array(arr.length);
+  for (let i = 0; i + 2 < arr.length; i += 3) {
+    out[i] = arr[i]; out[i + 1] = arr[i + 2]; out[i + 2] = -arr[i + 1];
+  }
+  return out;
+}
+
+export function boundsOf(arrays) {
+  const min = [Infinity, Infinity, Infinity], max = [-Infinity, -Infinity, -Infinity];
+  let any = false;
+  for (const a of arrays) {
+    for (let i = 0; i + 2 < (a?.length ?? 0); i += 3) {
+      any = true;
+      for (let k = 0; k < 3; k++) { if (a[i + k] < min[k]) min[k] = a[i + k]; if (a[i + k] > max[k]) max[k] = a[i + k]; }
+    }
+  }
+  return any ? { min, max } : null;
+}
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (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]; };
+
+// The camera basis a fit works in: d (target -> camera), right and trueUp,
+// from the canonical view's direction and up vector.
+function fitBasis(view, center) {
+  const base = cameraPoseForView(view, { center, radius: 1 });
+  const d = norm(sub(base.position, center)); // centre -> camera
+  const f = [-d[0], -d[1], -d[2]];
+  let right = cross(f, base.up);
+  if (Math.hypot(...right) < 1e-9) right = cross(f, [0, 0, 1]);
+  right = norm(right);
+  return { d, right, up: cross(right, f), baseUp: base.up };
+}
+
+// Fit a view to the geometry itself rather than to its bounding box: a box's
+// corners stand well outside a long, thin or L-shaped part, which then sits
+// small and off-centre. `points` are flat WORLD (Y-up) xyz triples; null when
+// there is nothing to frame (no points, or one point repeated).
+//
+// The view keeps its canonical direction and up. For a point at offset r from
+// the target, at camera distance D along d, it is inside `fill` of the frame
+// when
+//   |r·right| <= (D - r·d)·tanH·aspect·fill  and  |r·up| <= (D - r·d)·tanH·fill
+// so the nearest such D is the max over points of the two rearranged bounds.
+// Pass 1 aims at the bbox centre. The projected extent is then generally
+// lopsided (perspective, and a shape that is not symmetric about its box
+// centre), so the target slides sideways by the projected NDC bbox centre —
+// converted back to world units at distance D — and D is re-solved around the
+// shifted target. One recentre is not quite enough for a part with real depth
+// along the view (a 60 mm bar seen at iso was still ~0.04 NDC off after it,
+// because the re-solved D changes the perspective the recentre measured), so
+// the recentre/re-solve runs RECENTER_PASSES times: ~0.002 on that bar. The
+// last step is always a re-solve, so every point stays inside `fill` whatever
+// the recentring achieved. (Looking straight down a long bar puts its near end
+// almost at the eye, where no amount of sliding centres it; it stays in frame.)
+export function fitPoseToPoints(view, points, { fov, aspect = 1, fill }) {
+  const box = boundsOf([points]);
+  if (!box || box.min.every((v, i) => v === box.max[i])) return null;
+  const center = [0, 1, 2].map((i) => (box.min[i] + box.max[i]) / 2);
+  const { d, right, up, baseUp } = fitBasis(view, center);
+  const tanH = Math.tan((fov * Math.PI) / 360);
+  const t = tanH * fill;
+  const n = points.length - (points.length % 3);
+
+  // Per point: [depth, x, y] = r·d, r·right, r·up for r = p − target. Scalar
+  // and allocation-free — this runs over every vertex of the part, per view.
+  const project = (target, fn) => {
+    for (let i = 0; i < n; i += 3) {
+      const rx = points[i] - target[0], ry = points[i + 1] - target[1], rz = points[i + 2] - target[2];
+      fn(rx * d[0] + ry * d[1] + rz * d[2], rx * right[0] + ry * right[1] + rz * right[2], rx * up[0] + ry * up[1] + rz * up[2]);
+    }
+  };
+  const distance = (target) => {
+    let D = 0;
+    project(target, (depth, x, y) => {
+      D = Math.max(D, depth + Math.abs(x) / (t * aspect), depth + Math.abs(y) / t);
+    });
+    return D;
+  };
+
+  let target = center;
+  let D = distance(target);
+  for (let pass = 0; pass < RECENTER_PASSES; pass++) {
+    // Recentre: the NDC bbox of every point seen from target + d·D. A point at
+    // the eye plane (only a line along the view axis puts one there) has no
+    // projection and is left out rather than poisoning the bbox with Infinity.
+    let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+    project(target, (depth, x, y) => {
+      const z = D - depth;
+      if (!(z > 1e-12)) return;
+      const nx = x / (z * tanH * aspect), ny = y / (z * tanH);
+      if (nx < minX) minX = nx; if (nx > maxX) maxX = nx;
+      if (ny < minY) minY = ny; if (ny > maxY) maxY = ny;
+    });
+    if (!(minX <= maxX)) break;
+    const sx = ((minX + maxX) / 2) * D * tanH * aspect, sy = ((minY + maxY) / 2) * D * tanH;
+    target = [0, 1, 2].map((i) => target[i] + right[i] * sx + up[i] * sy);
+    D = distance(target);
+  }
+  return { position: [0, 1, 2].map((i) => target[i] + d[i] * D), up: baseUp, target };
+}
+
+// `points` (flat world xyz, optional) lets a "fit" style frame the geometry
+// itself (fitPoseToPoints); without them it fits the box's eight corners.
+export function stylePose(style, view, box, { aspect = 1, points } = {}) {
+  const fov = style.camera.fov;
+  const min = box?.min ?? [0, 0, 0], max = box?.max ?? [0, 0, 0];
+  const center = [(min[0] + max[0]) / 2, (min[1] + max[1]) / 2, (min[2] + max[2]) / 2];
+  const size = sub(max, min);
+  const diag = Math.hypot(size[0], size[1], size[2]);
+  // Enclosing radius for the depth planes; a shadow plane reaches 2·blur·diag
+  // past the footprint (contact-shadow.js pads by that much).
+  const pad = style.shadow ? 2 * style.shadow.blur * diag : 0;
+  const sceneBounds = { center, radius: (diag / 2 || DEFAULT_RADIUS) + pad };
+
+  if (style.camera.framing === "canonical" || diag === 0) {
+    const radius = Math.max(size[0], size[1], size[2]) / 2 || DEFAULT_RADIUS;
+    return { pose: cameraPoseForView(view, { center, radius }), fov, sceneBounds };
+  }
+
+  const fitted = points?.length >= 3 && fitPoseToPoints(view, points, { fov, aspect, fill: style.camera.fill });
+  if (fitted) return { pose: fitted, fov, sceneBounds };
+
+  // Fallback fit, with no points to hand: the same bound over the box's eight
+  // corners, aimed at the box centre (see fitPoseToPoints for the inequality).
+  const { d, right, up, baseUp } = fitBasis(view, center);
+  const t = Math.tan((fov * Math.PI) / 360) * style.camera.fill;
+  let D = 0;
+  for (const x of [min[0], max[0]]) for (const y of [min[1], max[1]]) for (const z of [min[2], max[2]]) {
+    const r = sub([x, y, z], center);
+    const depth = dot(r, d);
+    D = Math.max(D, depth + Math.abs(dot(r, right)) / (t * aspect), depth + Math.abs(dot(r, up)) / t);
+  }
+  const position = [center[0] + d[0] * D, center[1] + d[1] * D, center[2] + d[2] * D];
+  return { pose: { position, up: baseUp, target: center }, fov, sceneBounds };
+}
+
+// The offsets (renderStyles.js) are camera-space multiples of the camera-to-target
+// distance: the key sits over the viewer's shoulder (up and to the right, ~41° off the
+// view axis), the fill opposes it from the left at eye level. Both still shine mostly
+// ALONG the view direction, so whatever the camera can see is lit.
+
+// World-space positions for the capture key/fill, given a camera pose (the same
+// `{position, up, target}` shape cameraPoseForView returns). Pure — no THREE, no scene.
+export function captureLightPoses({ position, up, target }, lights = RENDER_STYLES.cad.lights) {
+  const forward = norm(sub(target, position));
+  // Camera basis. A canonical view never passes an `up` parallel to its own view axis,
+  // but a caller could, and a degenerate basis would put NaN into the light positions.
+  let right = cross(forward, up);
+  if (Math.hypot(...right) < 1e-6) right = cross(forward, [0, 0, 1]);
+  if (Math.hypot(...right) < 1e-6) right = cross(forward, [0, 1, 0]);
+  right = norm(right);
+  const trueUp = norm(cross(right, forward));
+  const dist = Math.hypot(...sub(target, position)) || 1;
+  const place = (offset) => [0, 1, 2].map(
+    (i) => position[i] + (right[i] * offset.right + trueUp[i] * offset.up) * dist,
+  );
+  return { key: place(lights.key.offset), fill: place(lights.fill.offset) };
+}

package/src/framework/viewer-lighting.js

@@ -1,20 +1,21 @@
 import * as THREE from "three";
+import { RENDER_STYLES } from "./renderStyles.js";
 
-const KEY_COLOR = 0xffffff, KEY_INTENSITY = 1.45;
-const FILL_COLOR = 0xe5efff, FILL_INTENSITY = 0.65;
+const CAD = RENDER_STYLES.cad.lights;
 
 // The persistent sky/ground ambient. Shared with the offscreen thumbnail path
 // (viewer.js renderMeshPayloads), which builds its own throwaway scene and so needs
 // the same hemisphere fill to avoid rendering faces outside the key/fill cones near-black.
-export function createHemisphereLight() {
-  return new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
+export function createHemisphereLight(lights = CAD) {
+  const h = lights.hemisphere;
+  return new THREE.HemisphereLight(h.sky, h.ground, h.intensity);
 }
 
 export function addViewerLights(scene) {
   const hemisphere = createHemisphereLight();
-  const key = new THREE.DirectionalLight(KEY_COLOR, KEY_INTENSITY);
+  const key = new THREE.DirectionalLight(CAD.key.color, CAD.key.intensity);
   key.position.set(8, 14, 10);
-  const fill = new THREE.DirectionalLight(FILL_COLOR, FILL_INTENSITY);
+  const fill = new THREE.DirectionalLight(CAD.fill.color, CAD.fill.intensity);
   fill.position.set(-10, 6, -8);
 
   scene.add(hemisphere, key, fill);
@@ -29,45 +30,10 @@ export function addViewerLights(scene) {
 // a 1 mm snap barb. These two lights are the capture-time stand-ins, swapped in for the
 // duration of one offscreen render (see viewer.js renderOffscreen) and posed relative to
 // the view axis, so every canonical view is exposed and shaded the same way.
-export function createCaptureLights() {
-  const key = new THREE.DirectionalLight(KEY_COLOR, KEY_INTENSITY);
-  const fill = new THREE.DirectionalLight(FILL_COLOR, FILL_INTENSITY);
+export function createCaptureLights(lights = CAD) {
+  const key = new THREE.DirectionalLight(lights.key.color, lights.key.intensity);
+  const fill = new THREE.DirectionalLight(lights.fill.color, lights.fill.intensity);
   return { key, fill };
 }
 
-// Offsets from the camera, in camera-space multiples of the camera-to-target distance:
-// the key sits over the viewer's shoulder (up and to the right, ~41° off the view axis),
-// the fill opposes it from the left at eye level. Both still shine mostly ALONG the view
-// direction, so whatever the camera can see is lit.
-const KEY_OFFSET = { right: 0.45, up: 0.75 };
-const FILL_OFFSET = { right: -0.7, up: 0.15 };
-
-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 length = (v) => Math.hypot(v[0], v[1], v[2]);
-const norm = (v) => {
-  const l = length(v) || 1;
-  return [v[0] / l, v[1] / l, v[2] / l];
-};
-
-// World-space positions for the capture key/fill, given a camera pose (the same
-// `{position, up, target}` shape cameraPoseForView returns). Pure — no THREE, no scene.
-export function captureLightPoses({ position, up, target }) {
-  const forward = norm(sub(target, position));
-  // Camera basis. A canonical view never passes an `up` parallel to its own view axis,
-  // but a caller could, and a degenerate basis would put NaN into the light positions.
-  let right = cross(forward, up);
-  if (length(right) < 1e-6) right = cross(forward, [0, 0, 1]);
-  if (length(right) < 1e-6) right = cross(forward, [0, 1, 0]);
-  right = norm(right);
-  const trueUp = norm(cross(right, forward));
-  const dist = length(sub(target, position)) || 1;
-  const place = (offset) => [0, 1, 2].map(
-    (i) => position[i] + (right[i] * offset.right + trueUp[i] * offset.up) * dist,
-  );
-  return { key: place(KEY_OFFSET), fill: place(FILL_OFFSET) };
-}
+export { captureLightPoses } from "./style-camera.js";