partforge 0.50.0 → 0.52.0

package/README.md

@@ -114,6 +114,10 @@ runtime.setHostPane("rail");  // narrow layout only: show just the controls
                                // built-in tab bar. null hands selection back.
 runtime.setActive(false);      // park the viewer: stop the render loop, release the
                                // drawing buffer. setActive(true) restores both.
+runtime.attachTooltips([{ element: myButton }]);  // host chrome buttons join the mount's
+                               // shared hover tooltip (label = the button's title or
+                               // aria-label, or a per-entry getLabel()); returns
+                               // { sync, hide, detach }, auto-detached on dispose()
 const off = runtime.onContextLost(() => {});  // WebGL context loss; returns an unsubscribe
 runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU resources
 ```

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.

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.50.0",
+  "version": "0.52.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/chrome.css

@@ -79,6 +79,74 @@
 .pf-rail-head, .pf-rail-foot { flex: none; }
 .pf-rail-head { padding: 12px var(--pf-rail-pad); border-bottom: 1px solid var(--pf-border); }
 .pf-rail-foot { padding: 12px var(--pf-rail-pad); border-top: 1px solid var(--pf-border); }
+
+/* Foot ACTIONS, the counterpart to app.css's `#viewbar button`: any button a
+   host puts in the foot inherits the shared chrome, so a host-drawn control
+   sits beside a built-in one without restating the metrics — or, more to the
+   point, without re-deriving the states. Both hosts had independently written
+   the same padding/radius/mono stack, and only one of them had remembered to
+   exclude :disabled from :hover, so a dead button still lit up under the
+   pointer in the other. That bug is unreachable from here.
+
+   Buttons only; the ROW is the host's. A foot can hold a bare row
+   (partforge-cloud) or a labelled group (the demo pages' .dl/.dl-head), and a
+   container rule here would have to pick one. This mirrors the viewbar only
+   as far as the analogy holds: there, the pill itself is a single known
+   element partforge can own outright.
+
+   Base is the quiet outline treatment, because that is the safe thing to
+   inherit by accident; the loud one is opt-in via .pf-primary. Equal
+   specificity to app.css's `.dl-row button`, which is imported after this
+   file and therefore still wins — the legacy download row renders exactly as
+   before, and can drop .dl-row whenever it likes. */
+.pf-rail-foot button {
+  flex: 1;
+  padding: 8px 0;
+  border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control);
+  background: transparent;
+  color: var(--pf-text-2);
+  font-family: var(--pf-mono);
+  font-weight: 600;
+  font-size: 11px;
+  letter-spacing: 0.06em;
+  cursor: pointer;
+}
+.pf-rail-foot button:hover:not(:disabled) {
+  border-color: var(--pf-accent);
+  color: var(--pf-text-strong);
+}
+.pf-rail-foot button:disabled { opacity: .45; cursor: default; }
+
+/* The foot's main call to action — accent-filled, so it reads as the primary
+   thing to do with a finished part. */
+.pf-rail-foot button.pf-primary {
+  border-color: var(--pf-accent);
+  background: var(--pf-accent);
+  color: var(--pf-on-accent);
+}
+.pf-rail-foot button.pf-primary:hover:not(:disabled) {
+  background: color-mix(in oklab, var(--pf-accent) 88%, #000);
+  border-color: color-mix(in oklab, var(--pf-accent) 88%, #000);
+}
+
+/* A square icon-only action sitting beside the primary one. Sized to match
+   the viewbar's icon buttons, and flex-none so the primary action keeps the
+   remaining width rather than the two splitting it evenly. */
+.pf-rail-foot button.pf-icon {
+  flex: 0 0 auto;
+  width: 34px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--pf-muted);
+}
+.pf-rail-foot button.pf-icon:hover:not(:disabled) {
+  background: var(--pf-surface-2);
+  border-color: var(--pf-border);
+  color: var(--pf-text-2);
+}
+
 .pf-rail-body {
   flex: 1;
   min-height: 0;

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

@@ -5,7 +5,7 @@ import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
 import { attachRail } from "./rail.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
-import { createTooltipPresenter } from "./tooltip.js";
+import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
 import { loadCamera } from "./view-state.js";
 import { buildControls } from "./controls.js";
 import { relevantParamKeys } from "./param-deps.js";
@@ -29,7 +29,11 @@ import { resolveDefaultView } from "./default-view.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView }) {
+// The default no-op tooltip binding, so a host can hold on to whatever
+// attachTooltips returned without caring whether this mount resolved one.
+const NOOP_TOOLTIP_BINDING = { sync: () => {}, hide: () => {}, detach: () => {} };
+
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -60,6 +64,12 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // (partforge-cloud does, at the window level). Defaulted to a no-op so the
     // handle's shape never depends on whether this mount resolved a rail.
     setHostPane: setHostPane ?? (() => {}),
+    // Join host-owned chrome buttons to this mount's shared hover tooltip, so
+    // a host's own viewbar/rail-foot buttons match the built-in ones. Entries
+    // are [{ element, getLabel? }] (label falls back to the button's
+    // title/aria-label); returns { sync, hide, detach }. Same no-op default
+    // stance as setHostPane above.
+    attachTooltips: attachTooltips ?? (() => NOOP_TOOLTIP_BINDING),
   };
 }
 
@@ -116,6 +126,15 @@ function createCleanupStack() {
 //   runtime.setHostPane("rail");  // narrow layout only: show just the controls
 //                                 // rail ('stage' | 'rail'), suppressing the
 //                                 // built-in tab bar. null hands selection back.
+//   runtime.attachTooltips([{ element: myButton }]);  // host chrome buttons join the
+//                                 // mount's shared hover tooltip (the viewbar one).
+//                                 // Label = the button's title (or aria-label), or a
+//                                 // per-entry getLabel(); the title attribute is
+//                                 // absorbed while attached so it can't double up as a
+//                                 // native tooltip, and restored on detach. Returns
+//                                 // { sync, hide, detach } — call sync() after you
+//                                 // toggle a button's disabled state. Detached
+//                                 // automatically on dispose().
 //   runtime.setActive(false);     // park the viewer: stop the render loop and release
 //                                 // both large GPU allocations (the drawing buffer and
 //                                 // the cached capture target). For a host that hides the
@@ -203,7 +222,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     cleanup.defer(() => cutawayChrome.detach());
     // Resizable/collapsible controls rail. No-ops when the host lays out the
     // framework itself (no #panel / no elements.rail).
-    const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell });
+    const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell, tooltip });
     cleanup.defer(() => railChrome.detach());
     // Narrow-layout pane tabs. Below RAIL_NARROW_BREAKPOINT the rail cannot sit
     // beside the viewer, so exactly one pane shows and this bar picks it. Same
@@ -639,8 +658,19 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       }
     };
 
+    // Host chrome buttons joining the mount's shared tooltip (the one the
+    // viewbar and cutaway buttons already use). Bindings are detached by
+    // dispose() via the cleanup stack; a host detaching earlier is fine —
+    // attachButtonTooltips.detach is idempotent.
+    const attachHostTooltips = (entries) => {
+      const binding = attachButtonTooltips(tooltip, entries);
+      cleanup.defer(() => binding.detach());
+      return binding;
+    };
+
     return makeHandle({
       ready, dispose, viewer, setParams,
+      attachTooltips: attachHostTooltips,
       setHostPane: paneTabs.setHostPane,
       getView: view,                         // () => tabsCtl.current()
       setView: (name) => tabsCtl.select(name),

package/src/framework/rail.js

@@ -2,6 +2,7 @@ import {
   RAIL_DEFAULT_WIDTH, RAIL_MIN_WIDTH, RAIL_NARROW_BREAKPOINT,
   clampRailWidth, railMaxWidth, readRailPref, resolveRailDrag, writeRailPref,
 } from "./rail-state.js";
+import { attachButtonTooltips } from "./tooltip.js";
 
 const KEY_STEP = 16;
 const KEY_STEP_SHIFT = 64;
@@ -75,7 +76,11 @@ function safeStorage() {
 //
 // Everything is optional. With no rail this returns a no-op, so hosts that lay
 // the framework out themselves (see embed-test.html) are unaffected.
-export function attachRail({ rail, toggle, shell = rail?.parentElement, storage = safeStorage() } = {}) {
+//
+// `tooltip` is the mount's shared presenter (tooltip.js). With it, the toggle's
+// Hide/Show-controls label renders as the same anchored pf-hover-tip the
+// viewbar buttons use; without it, the label falls back to a native title.
+export function attachRail({ rail, toggle, shell = rail?.parentElement, storage = safeStorage(), tooltip } = {}) {
   if (!rail || !shell) {
     // No rail to resolve in this document: --pf-rail-w still defaults to 288px
     // from tokens.css, but nothing is reserving that space, so anything that
@@ -107,6 +112,12 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
     toggle.replaceChildren(svg);
     toggleChevron = chevron;
   }
+  // Attached BEFORE the first apply() below writes an aria-label, so the
+  // binding's original-attribute capture (what its detach() restores) sees the
+  // host's own markup, not our first label.
+  const tooltipBinding = toggle && tooltip
+    ? attachButtonTooltips(tooltip, [{ element: toggle }])
+    : null;
 
   const seam = document.createElement("div");
   seam.className = "pf-rail-seam";
@@ -157,8 +168,11 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
       const label = collapsed ? "Show controls" : "Hide controls";
       toggle.setAttribute("aria-expanded", String(!collapsed));
       toggle.setAttribute("aria-label", label);
-      toggle.title = label;
+      // The shared tooltip reads the aria-label at show time, so a native
+      // title would double up as a second, competing tooltip.
+      if (!tooltipBinding) toggle.title = label;
       toggle.classList.toggle("on", collapsed);
+      tooltipBinding?.sync();
     }
     if (persist) writeRailPref(state, storage);
   }
@@ -324,6 +338,9 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
       shell.removeAttribute("data-pf-dragging");
       rail.removeAttribute("inert");
       root.style.removeProperty("--pf-rail-w");
+      // Before the attribute restore below: the binding's own detach rewrites
+      // title/aria-label from its capture, and ours must win.
+      tooltipBinding?.detach();
       if (toggle) {
         toggle.innerHTML = toggleOriginal.html;
         toggle.title = toggleOriginal.title;

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;