partforge 0.51.0 → 0.53.0

package/docs/AUTHORING-PARTS.md

@@ -312,7 +312,8 @@ future contract v2 — but are not shown here; see `docs/KERNEL-CONTRACT.md`
 | `k.roundedCylinder({ r\|d, h, center?, round })` | cylinder with rounded rims — `round` = number (both) or `{ top?, bottom? }`; `round: r` with `top+bottom = h` gives a sphere (capsule when `h > 2r`); one lathe revolve, curve-exact in STEP |
 | `k.torus({ rMajor, rMinor })` | torus centered at the origin (tube centerline in z=0); `0 < rMinor < rMajor` |
 | `k.revolve({ profile, degrees? })` | revolve a lathe profile `[[r,z],…]` (r ≥ 0) around the Z axis (full or partial) |
-| `k.helixSweptTube({ pathR, profileR, pitch, turns, z0, lefthand })` | circle swept along a helix (e.g. a rope groove) |
+| `k.helixSweptTube({ pathR, profileR, pitch, turns, z0, lefthand })` | circle swept along a helix (e.g. a rope groove). **Not for threads** — the profile is always circular and rides a frenet frame that rolls with the helix, tilting a tooth off-axis. For threads use `k.screwSweep` |
+| `k.screwSweep({ profile, pitch, turns, lefthand? })` | screw-motion sweep of an **axial** lathe profile `[[r, z], …]` (same convention as `k.revolve`) — threads, worms, helical ridges. `h = pitch · turns`. The profile's axial extent must not exceed `pitch`; a profile spanning exactly `pitch` must be **periodic** (first radius == last radius) and yields a complete threaded body with no boolean (both backends) |
 | `k.union(solids[])` | boolean union |
 
 **`loft` rings** — each ring is `{ polygon:[[x,y],…] | sides+radius, z, rotate?, scale? }`
@@ -1036,6 +1037,55 @@ const hole = k.cylinder({ r: 2, h: 20 }).translate([20, 0, 0]);
 body = body.cutAll(circularPattern(hole, 8, { axis: "Z" }));   // 8 bolt holes on a 40mm circle
 ```
 
+**Helical & threaded features** (screws, threads, bolts, worms, helical ridges):
+
+Use `k.screwSweep({ profile, pitch, turns })`. The profile is an **axial**
+`[[r, z]]` contour — the shape you would see slicing the thread down its axis —
+exactly `k.revolve`'s convention, with an axial rise added.
+
+The strongly preferred form is **periodic**: span exactly one `pitch`, start and
+end at the same radius. That makes the cross-section enclose the axis, so one op
+gives you the whole threaded body — no union with a core cylinder, which is both
+faster and avoids a boolean the B-rep backend handles badly
+([screw-thread-vanishes-on-occt](ERROR-PATTERNS.md#screw-thread-vanishes-on-occt)).
+
+```js
+// an ISO-ish M10x1.5 external thread: 60° flanks, crest flat P/8, root flat P/4
+const pitch = 1.5, majorR = 5;
+const rootR = majorR - (5 / 8) * (Math.sqrt(3) / 2) * pitch;
+const crest = pitch / 8, root = pitch / 4;
+const rise = (pitch - crest - root) / 2;
+const rod = k.screwSweep({
+  profile: [
+    [rootR,  0],
+    [rootR,  root],                    // root flat
+    [majorR, root + rise],             // up the flank
+    [majorR, root + rise + crest],     // crest flat
+    [rootR,  pitch],                   // down the flank, back to the start radius
+  ],
+  pitch, turns: 6,
+});
+```
+
+The ends are flat z-planes, which is what a threaded rod wants; intersect a cone
+for a lead-in chamfer. For a bolt, build the head as its own solid — that is what
+**`src/parts/screw.js`** does, the worked example for this recipe: an ISO-style
+metric bolt, periodic thread plus a hex head, presets and all.
+
+Cost scales with `turns` (= `length / pitch`), and steeply: the section is
+resampled every 5° of the twist, so an M10×1.5 shank costs ~10.5k triangles per
+turn. A 30 mm shank is 20 turns and about half a second on Manifold; hundreds of
+turns is millions of triangles and minutes behind the STEP button. Bound the
+`length` and `pitch` your schema exposes accordingly.
+
+The hand-rolled equivalent, for the record: `screwSweep` is
+`k.extrude({ profile, h, twist })` with the axial profile remapped to polar
+(`ψ = −360·z/pitch`) and `twist = 360 · turns` — one full turn of twist per pitch
+of height *is* screw motion. The op exists because that identity is easy to
+want and hard to find, and because the remap must be densified (see
+`geometry/screw-profile.js`) or the chords between profile points cut deep into
+the tooth.
+
 ## 2-D booleans
 
 `k.shape2d(profile)` lifts a point list, arc profile, or region into a `Shape2D` — an opaque 2-D boolean value. You can then compose booleans, and feed the result directly to `extrude` or `revolve` without materializing intermediate regions. The same `content-hash caching` discipline applies: identical arguments produce identical geometry.
@@ -1200,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/docs/ERROR-PATTERNS.md

@@ -361,6 +361,52 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** `defaults[key]` is not among the control's `options` values — often a value-type mismatch (`12` is not `"12"`).
 - **Fix:** Add the default to `options`, or change the default to one of the existing options; `npx partforge lint` errors via `select-default-not-in-options`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Rule catalog".
 
+## screw-thread-vanishes-on-occt
+
+- **Symptom:** a threaded part previews correctly but its STEP export is a plain
+  cylinder, or a valid-looking but implausibly small STEP file (~2 KB, a few
+  dozen entities, where a real thread is megabytes) that opens with no solid
+  geometry; on the OCCT backend the union of a thread with a core returns
+  exactly the core's volume, or `0`, with no error thrown.
+- **Cause:** the thread was built as a thin sub-pitch helical sliver and unioned
+  onto a core. OCCT's boolean fails on a near-self-touching swept operand and
+  silently returns the other operand — or nothing — rather than throwing.
+- **Fix:** build the thread in the **periodic** form instead — a profile spanning
+  exactly one `pitch` with equal first and last radius encloses the axis, so
+  `k.screwSweep` yields the whole threaded body with no boolean at all. See
+  [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Helical & threaded features".
+
+The hazard is specific to that sliver-riding-a-core shape, not to unions
+involving screw geometry in general: a filled periodic `screwSweep` rod
+unioned with an unrelated solid — a bolt head, say — booleans correctly. A
+measured rod (585.545) unioned with a head (804.248) returned 1324.732 —
+inside the geometrically expected range, not the bare-rod or empty-solid
+signature above. It's the thin near-self-touching sliver that OCCT's boolean
+mishandles, not screw geometry as such.
+
+## occt-bbox-too-large-on-twist
+
+- **Symptom:** `solid.boundingBox()` inside a `build()` reports a solid far larger
+  than it is — on a twisted solid (`extrude`/`prism` with `twist`, or
+  `k.screwSweep`) whose true max radius is 5, OCCT reports **7.209** where
+  Manifold reports **5.000** — so anything placed off that query lands ~44% too
+  far out in the STEP export while the preview looks right. The axial extent is
+  exact; it is the twisted directions that inflate.
+- **Cause:** OCCT derives the bounding box of a twisted B-spline surface from its
+  **control hull**, not from the surface. The control points of a twisted section
+  bow outward, so the box is a valid outer bound but a loose one. Volume and the
+  meshed surface are exact; only the bbox query is loose.
+- **Fix:** don't place geometry off `solid.boundingBox()` on a twisted solid —
+  compute the extent from the parameters that built it (they are right there in
+  `p`/`d`), or bound the twisted part with an untwisted proxy solid.
+
+**The `measure` / `verify` gate is not affected**: `src/framework/oracle/measure.js`
+takes its bbox from `bounds(mesh.positions)` — the meshed surface — never from
+`solid.boundingBox()`, so `bbox` assertions read 5.000 on both backends. The
+exposure is a `build()` that queries a twisted solid's box itself, which is the
+normal idiom for placing something relative to a solid and now silently disagrees
+between the Manifold preview and the OCCT STEP export.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -131,9 +131,9 @@ for free.
 | `loft` | `{rings, ruled?, closed?}` | `(rings, {ruled?,closed?})` |
 | `sweep` | `{profile, path, closed?, cornerRadius?, ruled?, smooth?}` | `(profile2D, path3D, opts?)` |
 
-`boredCylinder` and `helixSweptTube` were always options-only (no positional
-legacy form exists); they get the same unknown-key / required-key validation as
-the ops above.
+`boredCylinder`, `helixSweptTube` and `screwSweep` were always options-only (no
+positional legacy form exists); they get the same unknown-key / required-key
+validation as the ops above.
 `union(solids[])` and `toSTEP(named[])` take a single array — unchanged.
 
 ### Solid ops
@@ -186,7 +186,8 @@ above. All ops return a `Solid`.
 | `revolve({profile, degrees?})` | Revolve a lathe profile `[[r, z], …]` (r ≥ 0) about Z; `degrees` < 360 gives a capped partial revolve. Default 360. |
 | `loft({rings, ruled?, closed?})` | Stack polygon cross-sections (per-ring `z`/`rotate`/`scale`, equal vertex counts) with ruled walls and capped ends. Must self-correct a fully inverted result (CW rings / descending z) to an outward solid. |
 | `sweep({profile, path, closed?, cornerRadius?, ruled?, smooth?})` | Sweep a fixed CCW profile along a polyline with a rotation-minimizing frame; sharp mitered corners, or `cornerRadius` fillets; capped ends. |
-| `helixSweptTube({pathR, profileR, pitch, turns, z0, lefthand})` | Circle of radius `profileR` swept along a helix (e.g. a rope groove). |
+| `helixSweptTube({pathR, profileR, pitch, turns, z0, lefthand})` | Circle of radius `profileR` swept along a helix (e.g. a rope groove). Circular profile on a frenet frame that rolls with the helix — **not for threads**; use `screwSweep`. |
+| `screwSweep({profile, pitch, turns, lefthand})` | Screw-motion sweep of an axial lathe profile `[[r, z], …]` (r ≥ 0) — threads. The profile travels to `(r·cosθ, r·sinθ, z + pitch·θ/2π)`; `h = pitch · turns`. Axial extent must not exceed `pitch` or consecutive turns interpenetrate (throws). A profile spanning exactly `pitch` is **periodic**: first and last radius must agree, and it yields a complete threaded body needing no boolean. Compound: the polar-remapped, densified section extruded with `twist = 360 · turns`, exactly as composed in `kernel-front.js`; a backend may override only for caching, never for different geometry. Options-only. Parity: **within tolerance, not by construction** — both backends receive the identical densified polygon, but the mesh backend facets the twist at its own resolution while the B-rep backend builds an exact spline (`hull`'s parity class). |
 | `union(solids[])` | Boolean union of one or more solids. |
 | `text2d(string, {size, font?, align?, valign?, lineHeight?, tracking?, kerning?})` | Outline-font text → `Shape2D`. `size` = cap height (mm). `font` = declared name / inline bytes / default. Build-time; curve-exact on OCCT, faceted on Manifold. |
 | `hull(inputs[])` | Convex hull of all inputs (each a `Shape2D`, a curve contour, or an `[[x,y],…]` point list) → a convex `Shape2D`. Backend-agnostic: a pure-JS monotone-chain hull over the inputs' sampled points (curved inputs tessellated at a fixed LOD), lifted via `shape2d` (see the parity note below). Throws on an empty input array or a degenerate (collinear/point-count < 3) hull. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.51.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/app-screw.js

@@ -0,0 +1,16 @@
+// Self-hosted Geist + Geist Mono for the dev demos, so a standalone forge looks
+// like the product. Dev-only: --pf-sans/--pf-mono fall back to system stacks for
+// any consumer that doesn't load them (spec §2.2).
+import "@fontsource-variable/geist";
+import "@fontsource-variable/geist-mono";
+import screwPart from "./parts/screw.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the screw reference part. `npm run dev`, then open /screw.html.
+// The `new Worker(new URL(...))` call must stay inline here or Vite will not bundle it.
+// Dev-only: the handle is stashed on window so scripts/check-app.mjs can drive
+// the embedding contract (runtime.captureCurrent) the way an embedder would.
+window.__pfRuntime = mount(screwPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./screw-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/framework/geometry/kernel-front.js

@@ -29,6 +29,7 @@ import { beveledExtrude } from "./rim-bevel.js";
 import { DEFAULT_FONT_BYTES } from "./fonts/default-font.js";
 import { convexHull, hullPoints } from "./hull.js";
 import { latheRoundedRect, torusContour } from "./rounded-solids.js";
+import { screwCrossSection } from "./screw-profile.js";
 
 export function finishKernel(k) {
   // Compound default: bored-through cylinder (tool overshoots 2 mm each end for
@@ -47,6 +48,18 @@ export function finishKernel(k) {
   k.torus ??= ({ rMajor, rMinor }) =>
     k.revolve({ profile: k.shape2d(torusContour(rMajor, rMinor)) });
 
+  // Compound default: a screw-motion sweep of an axial [[r, z]] profile. Exactly
+  // k.extrude with a polar-remapped section and one full turn of twist per pitch
+  // (see screw-profile.js for why that identity holds, and why the profile must be
+  // densified first). No backend override: both backends twist natively, so this
+  // is one implementation and STEP gets a real twisted B-rep rather than a loft.
+  k.screwSweep ??= ({ profile, pitch, turns, lefthand = false }) =>
+    k.extrude({
+      profile: screwCrossSection(profile, pitch, { lefthand }),
+      h: pitch * turns,
+      twist: (lefthand ? -360 : 360) * turns,
+    });
+
   for (const [op, { toArgs, check }] of Object.entries(KERNEL_OP_SPECS)) {
     const raw = k[op];
     if (!raw) continue;

package/src/framework/geometry/kernel.js

@@ -19,7 +19,7 @@ export const CONTRACT_VERSION = 1;
 // Ops every backend kernel must implement.
 export const KERNEL_OPS = [
   "cylinder", "boredCylinder", "sphere", "box", "prism", "extrude", "revolve",
-  "loft", "sweep", "helixSweptTube", "union", "shape2d", "text2d", "hull", "hullChain", "toSTEP",
+  "loft", "sweep", "helixSweptTube", "screwSweep", "union", "shape2d", "text2d", "hull", "hullChain", "toSTEP",
   "roundedCylinder", "torus", "roundedBox",
 ];
 
@@ -110,6 +110,7 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  * @property {(o:{profile:number[][],path:number[][],closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a 2-D profile along a 3-D polyline; legacy (profile,path,opts) accepted until v2
  * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted until v2
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
+ * @property {(o:{profile:number[][],pitch:number,turns:number,lefthand?:boolean}) => Solid} screwSweep   screw-motion sweep of an axial [[r,z]] profile — threads; options-only
  * @property {(solids:Solid[]) => Solid} union
  * @property {(profile: number[][]|{outer:number[][],holes?:number[][][]}|Shape2D) => Shape2D} shape2d   2-D boolean value (both backends: Manifold wraps a CrossSection, OCCT a replicad Drawing)
  * @property {(inputs: (Shape2D|number[][]|{start:number[],segments:object[]})[]) => Shape2D} hull   convex hull of all inputs → a convex Shape2D (faceted; pure-JS monotone chain)

package/src/framework/geometry/op-options.js

@@ -253,6 +253,13 @@ export const KERNEL_OP_SPECS = {
   boredCylinder:  { toArgs: passThrough("boredCylinder", ["od", "h", "bore"], ["od", "h", "bore"]) },
   helixSweptTube: { toArgs: passThrough("helixSweptTube",
     ["pathR", "profileR", "pitch", "turns", "z0", "lefthand"], ["pathR", "profileR", "pitch", "turns"]) },
+  screwSweep: {
+    toArgs: passThrough("screwSweep", ["profile", "pitch", "turns", "lefthand"], ["profile", "pitch", "turns"]),
+    check: (o) => {
+      if (!(o.pitch > 0)) throw new Error("screwSweep: pitch must be > 0");
+      if (!(o.turns > 0)) throw new Error("screwSweep: turns must be > 0");
+    },
+  },
   roundedBox:      { toArgs: roundedBoxArgs },
   roundedCylinder: { toArgs: roundedCylinderArgs },
   torus:           { toArgs: torusArgs },

package/src/framework/geometry/screw-profile.js

@@ -0,0 +1,88 @@
+// Screw motion as a transverse cross-section. A profile point (r, z) in the axial
+// half-plane travels to (r·cos θ, r·sin θ, z + pitch·θ/2π) under screw motion, and
+// that whole solid is reproduced EXACTLY by extruding a polar-remapped section with
+// twist = 360°·turns — one full turn of twist per pitch of height. So screwSweep
+// needs no backend op: it is k.extrude in disguise (see kernel-front.js).
+//
+// The subtlety that makes this correct rather than nearly-correct: the map sends
+// profile POINTS to polar, but the EDGES between them become straight chords where
+// the true surface needs spiral arcs. Undensified, an ISO tooth loses ~42% of its
+// volume. So every segment is subdivided to a fixed 5° polar step — fixed, not a
+// per-call tolerance, so both backends see the identical polygon and the solid
+// cache keys stay stable. "Every segment" includes the contour's implicit closing
+// edge, except in the periodic case where that edge is a single polar point.
+
+// Degrees of polar sweep per emitted point. Matches Manifold's twist division
+// resolution (nDiv = ceil(|twist|/5) in manifold-backend.js), so the angular and
+// axial sampling of the same solid agree. Converges to 0.03% of the exact volume.
+export const SCREW_STEP_DEG = 5;
+
+const EPS = 1e-9;
+
+export function screwCrossSection(profile, pitch, { lefthand = false } = {}) {
+  if (!Array.isArray(profile) || profile.length < 2)
+    throw new Error("screwSweep: profile must be an array of at least 2 [r, z] points");
+  if (!(pitch > 0)) throw new Error("screwSweep: pitch must be > 0");
+  for (const p of profile) {
+    if (!Array.isArray(p) || !Number.isFinite(p[0]) || !Number.isFinite(p[1]))
+      throw new Error("screwSweep: every profile point must be a finite [r, z]");
+    if (p[0] < 0) throw new Error("screwSweep: profile radius must be ≥ 0");
+  }
+
+  const zs = profile.map(([, z]) => z);
+  const extent = Math.max(...zs) - Math.min(...zs);
+  if (extent > pitch + EPS)
+    throw new Error(
+      `screwSweep: profile axial extent ${extent} exceeds pitch ${pitch} — consecutive ` +
+      "turns would interpenetrate; reduce the profile height or increase pitch");
+
+  const n = profile.length;
+  const first = profile[0], last = profile[n - 1];
+  const periodic = extent > pitch - EPS;
+
+  // Subdivide by POLAR span, not by length: a segment with no z change sweeps no
+  // angle and needs no extra points.
+  const dense = [];
+  const densify = ([r0, z0], [r1, z1], { includeStart }) => {
+    const span = Math.abs((360 * (z1 - z0)) / pitch);
+    const steps = Math.max(1, Math.ceil(span / SCREW_STEP_DEG));
+    for (let j = includeStart ? 0 : 1; j < steps; j++)
+      dense.push([r0 + ((r1 - r0) * j) / steps, z0 + ((z1 - z0) * j) / steps]);
+  };
+  for (let i = 0; i < n - 1; i++) densify(profile[i], profile[i + 1], { includeStart: true });
+  dense.push(last);
+
+  // A profile spanning exactly one pitch closes on itself by periodicity: its last
+  // point maps to the same polar angle as its first, so it must agree in radius and
+  // the duplicate is dropped (a zero-length edge would otherwise reach the backend).
+  // Nothing is densified between them — they ARE the same polar point, and a
+  // densified edge would trace a spurious full circle back around the axis.
+  if (periodic) {
+    if (Math.abs(last[1] - first[1]) < pitch - EPS)
+      throw new Error(
+        `screwSweep: a full-pitch profile must start and end at its extreme z values — ` +
+        `the first and last points span ${Math.abs(last[1] - first[1])}, not the full ` +
+        `pitch ${pitch}; reorder the profile so it opens and closes on the wrap`);
+    if (Math.abs(first[0] - last[0]) > 1e-6)
+      throw new Error(
+        `screwSweep: a full-pitch profile must be periodic — first radius ${first[0]} ` +
+        `must equal last radius ${last[0]}`);
+    dense.pop();
+  } else {
+    // Sub-pitch: the contour's implicit closing edge (last → first) is a real edge
+    // spanning real polar angle, so it needs the same treatment as every other one.
+    // Undensified it is a straight chord across the unused part of the pitch, which
+    // turns a slim ridge into a twisted half-disc. `first` already opens the
+    // contour, so only the intermediate points are appended.
+    densify(last, first, { includeStart: false });
+  }
+
+  const sign = lefthand ? 1 : -1;
+  return dense.map(([r, z]) => {
+    const psi = (sign * 2 * Math.PI * z) / pitch;
+    const x = r * Math.cos(psi);
+    let y = r * Math.sin(psi);
+    if (y === 0) y = 0; // Normalize -0 to 0
+    return [x, y];
+  });
+}

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);

package/src/parts/screw.js

@@ -0,0 +1,82 @@
+// Reference part for k.screwSweep — an ISO-style metric bolt. The thread uses the
+// PERIODIC profile form (spans exactly one pitch, first radius == last radius), so
+// one screwSweep call yields the whole threaded shank with no boolean against a
+// core. See docs/AUTHORING-PARTS.md "Helical & threaded features".
+export default {
+  meta: { title: "Screw", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "thread",
+      title: "Thread",
+      description: "Nominal thread size. Pick a preset, or open **Advanced** for exact dimensions.",
+      presets: { M6: { major: 6, pitch: 1.0, length: 20 }, M10: { major: 10, pitch: 1.5, length: 30 } },
+      advanced: [
+        { key: "major", label: "Major diameter", unit: "mm", min: 4, max: 24, step: 0.5,
+          description: "Outside diameter measured across the thread crests." },
+        { key: "pitch", label: "Pitch", unit: "mm", min: 0.5, max: 3, step: 0.05, control: "number",
+          description: "Axial rise per turn. A coarse pitch on a small major diameter runs the root radius down toward zero, which is why Major diameter starts at 4 mm. The 0.5 mm floor is the ISO fine pitch for the smallest diameter offered here — and a floor is needed, because cost scales with turns = length / pitch." },
+        { key: "length", label: "Threaded length", unit: "mm", min: 5, max: 40, step: 1,
+          description: "Length of the threaded shank, excluding the head. Capped at 40 mm so the worst case reachable from these sliders — 40 mm at a 0.5 mm pitch, 80 turns — stays a couple of seconds of preview rather than minutes." },
+        { key: "lefthand", label: "Left-hand thread", control: "toggle",
+          description: "Reverses the helix. Rare outside gas fittings and bicycle pedals." },
+      ],
+    },
+    {
+      id: "head",
+      title: "Head",
+      description: "The hex head at the top of the shank.",
+      advanced: [
+        { key: "headAcross", label: "Head width across flats", unit: "mm", min: 0, max: 40, step: 0.5,
+          description: "Spanner size. Zero gives a headless threaded rod." },
+        { key: "headH", label: "Head height", unit: "mm", min: 1, max: 20, step: 0.5,
+          description: "Head thickness along the axis." },
+      ],
+    },
+  ],
+  defaults: { major: 10, pitch: 1.5, length: 30, lefthand: false, headAcross: 17, headH: 6.4 },
+  // derive(): the ISO 60-degree tooth, expressed as radii the build consumes directly.
+  derive: (p) => {
+    const H = (Math.sqrt(3) / 2) * p.pitch;   // sharp-V height
+    const majorR = p.major / 2;
+    const rootR = majorR - (5 / 8) * H;
+    const rootFlat = p.pitch / 4, crestFlat = p.pitch / 8;
+    return {
+      majorR, rootR, rootFlat, crestFlat,
+      rise: (p.pitch - crestFlat - rootFlat) / 2,
+      turns: p.length / p.pitch,
+      headR: p.headAcross / Math.sqrt(3),      // circumradius of a hex across flats
+    };
+  },
+  parts: {
+    screw: {
+      label: "Screw",
+      views: ["screw"],
+      export: { name: "screw" },
+      build: (k, p, d) => {
+        // Periodic profile: exactly one pitch tall, first radius == last radius.
+        const shank = k.screwSweep({
+          profile: [
+            [d.rootR,  0],
+            [d.rootR,  d.rootFlat],
+            [d.majorR, d.rootFlat + d.rise],
+            [d.majorR, d.rootFlat + d.rise + d.crestFlat],
+            [d.rootR,  p.pitch],
+          ],
+          pitch: p.pitch,
+          turns: d.turns,
+          lefthand: p.lefthand,
+        });
+        if (p.headAcross <= 0) return shank;
+        const head = k.prism({ points: hexPoints(d.headR), h: p.headH }).at([0, 0, p.length]);
+        return shank.union(head);
+      },
+    },
+  },
+  views: { screw: { label: "Screw" } },
+};
+
+const hexPoints = (r) =>
+  Array.from({ length: 6 }, (_, i) => {
+    const a = (Math.PI / 3) * i;
+    return [r * Math.cos(a), r * Math.sin(a)];
+  });

package/src/screw-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/screw.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/types/kernel.d.ts

@@ -298,6 +298,17 @@ export interface HelixSweptTubeOptions {
   lefthand: boolean;
 }
 
+/** `k.screwSweep` — an axial lathe profile `[[r, z], …]` swept by screw motion. */
+export interface ScrewSweepOptions {
+  /** Closed axial contour; axial extent must not exceed `pitch`. */
+  profile: number[][];
+  /** Axial rise per turn, mm. */
+  pitch: number;
+  /** Number of turns swept; total height is `pitch * turns`. Cost scales with it. */
+  turns: number;
+  lefthand?: boolean;
+}
+
 export interface RoundedCylinderOptions {
   r?: number;
   d?: number;
@@ -376,6 +387,8 @@ export interface GeometryKernel {
   /** Sweep a 2-D profile along a 3-D polyline. */
   sweep(o: SweepOptions): Solid;
   helixSweptTube(o: HelixSweptTubeOptions): Solid;
+  /** Sweep an axial lathe profile by screw motion — threads. */
+  screwSweep(o: ScrewSweepOptions): Solid;
   /** Rim round-overs via one lathe revolve; curve-exact in STEP. */
   roundedCylinder(o: RoundedCylinderOptions): Solid;
   torus(o: TorusOptions): Solid;