partforge 0.52.0 → 0.53.0

package/docs/AUTHORING-PARTS.md

@@ -1250,9 +1250,14 @@ 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). Resolves `null` on
-  failure rather than throwing (a build error, a part with no sub-parts in that view, a
-  disposed runtime).
+  scene; `opts` forwards to the underlying render (size, quality, angle, background).
+  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.
 
 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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.52.0",
+  "version": "0.53.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",

package/src/framework/mount.js

@@ -644,7 +644,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // renders it in a throwaway scene via viewer.renderMeshPayloads. Never
     // 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.
+    // settles rather than throwing), returns null. `opts` is spread last, so
+    // renderMeshPayloads' own options (including `background`) pass straight
+    // through from the caller.
     const captureView = async (viewName, opts = {}) => {
       try {
         const target = (viewName && part.views?.[viewName]) ? viewName : resolveDefaultView(part);

package/src/framework/viewer.js

@@ -57,6 +57,36 @@ 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;
+
+// Resolve renderMeshPayloads' `background` option to what Scene.background
+// wants. Exported for its own sake: renderMeshPayloads needs a GL context and
+// so is untestable directly, and this is the whole of the decision. `null` is
+// a real escape hatch — the pre-existing no-background behaviour, clearing to
+// the renderer's clear colour — so it is passed through rather than treated as
+// "unset"; only `undefined` (an absent option) takes the default.
+export function thumbnailBackground(background = THUMBNAIL_BG) {
+  return background === null ? null : new THREE.Color(background);
+}
+
 // Render the LIVE camera's current framing offscreen, once, at a caller-chosen
 // resolution — the showcase capture behind the runtime handle's captureCurrent.
 // Same injected-renderer split as captureViewsFromScene so it runs without a GL
@@ -646,12 +676,18 @@ 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
-  // everything. Never touches the live scene, camera, subMesh, or subCache. `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 } = {}) {
+  // everything. Never touches the live scene, camera, subMesh, or subCache. The scene
+  // gets THUMBNAIL_BG 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 } = {}) {
     if (disposed) return null; // same guard as captureCurrent/captureCanonicalViews — never touch a torn-down renderer
     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);
     const tmpPivot = new THREE.Group();
     tmpPivot.rotation.x = -Math.PI / 2; // model Z (CAD up) -> vertical, same as live pivot
     tmpScene.add(tmpPivot);