forgecad 0.9.16 → 0.10.0

package/dist/docs-raw/generated/legacy.md

@@ -0,0 +1,162 @@
+<!-- AUTO-GENERATED by scripts/gen-api-docs.mjs. Do not edit by hand. -->
+<!-- BUILD GUARD: no skill-group frontmatter, ever — this file is a lookup table for
+     agents editing old models, not taught context. Banned from the skill bundle via
+     BUNDLE_BANNED_DOCS in scripts/build-forgecad-skill.mjs. -->
+
+# Legacy API Names
+
+These names still run but are no longer taught; new code must use the replacement.
+Each emits a one-time deprecation warning per script run.
+They may be removed in a future release.
+
+## core
+
+| Old name | Use instead |
+|----------|-------------|
+| `composeChain()` | `Transform.compose(a, b, ...)` |
+| `importSvgSketch()` | `Import.svgSketch(file, options)` |
+| `importMesh()` | `Import.mesh(file, options)` |
+| `importStep()` | `Import.step(file)` |
+| `Constraint.makeParallel()` | `sk.parallel(a, b)` |
+| `Constraint.horizontal()` | `sk.horizontal(line)` |
+| `Constraint.vertical()` | `sk.vertical(line)` |
+| `Constraint.equalLength()` | `sk.equal(a, b)` |
+| `Constraint.distance()` | `sk.distance(a, b, value)` |
+| `Constraint.fix()` | `sk.fix(point, x, y)` |
+| `Constraint.coincident()` | `sk.coincident(a, b)` |
+| `Constraint.perpendicular()` | `sk.perpendicular(a, b)` |
+| `Constraint.length()` | `sk.length(line, value)` |
+| `Slot.rounded()` | `SurfaceMembers.roundedSlot({ length, width }) — same builder, same fluent chain` |
+| `Counterbore.cylindrical()` | `SurfaceMembers.counterbore({ diameter, clearanceDiameter, depth }) — same builder, same fluent chain` |
+| `Ribs.repeated()` | `SurfaceMembers.ribs({ count, height }) — same feature object` |
+
+## sketch
+
+| Old name | Use instead |
+|----------|-------------|
+| `point()` | `new Point2D(x, y) — or cs.point(x, y) inside constrainedSketch()` |
+| `line()` | `Line2D.fromCoordinates(x1, y1, x2, y2) — or cs.line(a, b) inside constrainedSketch()` |
+| `circle()` | `Circle2D.fromCenterAndRadius(new Point2D(cx, cy), r) — or circle2d(r) for a sketch profile` |
+| `addRect()` | `sk.rect({ x: 0, y: 0, width: 100, height: 50 }) — same options, called on the constrainedSketch() builder` |
+| `addPolygon()` | `sk.addPolygon({ points: [[0,0],[100,0],[50,80]] }) — same options, called on the constrainedSketch() builder` |
+| `addRegularPolygon()` | `sk.regularPolygon({ sides: 6, radius: 25 }) — same options, called on the constrainedSketch() builder` |
+| `filletTrackedEdge()` | `fillet(shape, radius, shape.edge('vert-br')) — same exact compiler-owned path, no quadrant tuple needed` |
+| `chamferTrackedEdge()` | `chamfer(shape, size, shape.edge('vert-br')) — same exact compiler-owned path, no quadrant tuple needed` |
+| `filletCorners()` | `polygon(points).filletCorner([x, y], radius) — seed-point corner selection; or .filletCorners(radius) for all corners` |
+| `star()` | `polygon(tips.flatMap((tip, i) => [tip, valleys[i]])) with tips = polygonVertices(n, outerR, { startDeg: -90 }) and valleys = polygonVertices(n, innerR, { startDeg: -90 + 180 / n })` |
+| `ConstrainedSketchBuilder.importPoint()` | `sk.point(pt.x, pt.y, fixed) — constraint methods auto-import Point2D values directly` |
+| `ConstrainedSketchBuilder.importLine()` | `sk.line(sk.point(l.start.x, l.start.y, fixed), sk.point(l.end.x, l.end.y, fixed)) — constraint methods auto-import Line2D values directly` |
+| `ConstrainedSketchBuilder.importRectangle()` | `sk.rect({ x, y, width, height }) — returns richer named sides (bottom/right/top/left) and vertices` |
+
+## assembly
+
+| Old name | Use instead |
+|----------|-------------|
+| `bomToCsv()` | `solvedAssembly.bomCsv() — the method form covers BOM CSV export` |
+| `SolvedAssembly.mateExplodeHints()` | `explode hints derive automatically from connect()/match() joints — use explodeView()` |
+| `SolvedAssembly.mateDof()` | `diagnostics for the legacy mate() solver — position parts with connect()/match() and inspect kinematics instead` |
+| `SolvedAssembly.mateConverged()` | `diagnostics for the legacy mate() solver — position parts with connect()/match() and inspect kinematics instead` |
+| `SolvedAssembly.toScene()` | `toSceneObjects() — same return shape; or return the SolvedAssembly directly` |
+| `Assembly.usedPortRefs()` | `usedConnectorRefs — same ReadonlySet` |
+| `Assembly.mate()` | `connect("Parent.connectorA", "Child.connectorB") / match("Child.connectorB", "Parent.connectorA") — connector-frame joints replace string-ref mates` |
+| `Assembly.getPort()` | `getConnector(ref) — same "PartName.connectorName" ref; fields are partName/connectorName/connector` |
+| `Assembly.linkToward()` | `linkAlong(name, fromLink, towardLink, distance) — same arguments; positive distance moves toward towardLink, negative moves away` |
+| `Assembly.linkAwayFrom()` | `linkAlong(name, fromLink, awayFromLink, -distance) — negate the distance: negative values extend away from the reference link` |
+| `Assembly.toJointsView()` | `return the Assembly directly (return mech) — solver-backed controls appear automatically; use addAnimation(name, { keyframes }) for animation clips` |
+| `ImportedAssembly.part()` | `getPart(name, state?) — same offset-aware accessor; note that solve(state).getPart(name) does NOT apply the placeReference() offset stored on the imported assembly` |
+| `ImportedAssembly.translate()` | `toGroup().translate(x, y, z) — the explicit toGroup(state?) call shows where kinematics become a static group; or placeReference() to position by a named point` |
+| `ImportedAssembly.rotate()` | `toGroup().rotate(axis, angleDeg, options) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+| `ImportedAssembly.rotateX()` | `toGroup().rotateX(angleDeg, options) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+| `ImportedAssembly.rotateY()` | `toGroup().rotateY(angleDeg, options) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+| `ImportedAssembly.rotateZ()` | `toGroup().rotateZ(angleDeg, options) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+| `ImportedAssembly.scale()` | `toGroup().scale(v) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+| `ImportedAssembly.mirror()` | `toGroup().mirror(normal) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+| `ImportedAssembly.color()` | `toGroup().color(hex) — the explicit toGroup(state?) call shows where kinematics become a static group` |
+
+## curves
+
+| Old name | Use instead |
+|----------|-------------|
+| `nurbsSurface()` | `Surface.Nurbs(controlGrid, options) — same arguments and options, including thickness` |
+| `surfacePatch()` | `Surface.Patch(curves, { approximate: true }) — Surface.Patch defaults approximate: false (pass { approximate: true } for sampled Curve3D/Vec3[] boundaries) and returns an open sheet; use .thicken(t) instead of the thickness option` |
+| `Surface.MatchEdge()` | `Surface.Match()` |
+| `Product.ovalProfile()` | `Product.profiles.oval(width, depth, options) — identical arguments` |
+| `Product.roundedRectProfile()` | `Product.profiles.roundedRect(width, depth, radius) — identical arguments` |
+| `Product.circleProfile()` | `Product.profiles.circle(diameter, options) — identical arguments` |
+| `Product.superEllipseProfile()` | `Product.profiles.superEllipse(width, depth, options) — identical arguments` |
+| `Product.spout()` | `Product.place(loft(sectionSketches, heights).as('spout'), ref) — loft the local spout sections at origin, then place the result on the ProductSurfaceRef frame (or ref.attach(...) with offset/inset options)` |
+| `Product.handle()` | `sweep(gripProfile, spinePoints) with spine points derived from ref.frame().point, plus Product.place(padShape, ref) for landing pads — composes loft/sweep with connector frames instead of a fixed handle archetype` |
+| `Curve.Polyline()` | `pass the Vec3[] points array directly — sweep(profile, points) and Curve.Trim/Reverse accept raw point arrays; use Curve.Route.fromPolyline(points) when the centerline needs bend/port metadata` |
+| `Curve.Spline()` | `Curve.Fit(points) — exact NURBS interpolation through the same points (add { closed: true } for loops); unlike the sampled Catmull-Rom spline it works with Curve.Trim/Reverse, sweeps, and exact surface boundaries` |
+
+## sheet-metal
+
+| Old name | Use instead |
+|----------|-------------|
+| `kerfCompensateOutline()` | `sketch.offset(-kerf / 2) — or let FlatPart.profile(kerf) / Laser.kit({ kerf }) apply kerf compensation automatically` |
+| `kerfCompensateTabs()` | `sketch.offset(kerf / 2) — or let FlatPart.profile(kerf) / Laser.kit({ kerf }) apply kerf compensation automatically` |
+| `kerfCompensateSlots()` | `sketch.offset(kerf / 2) — or let FlatPart.profile(kerf) / Laser.kit({ kerf }) apply kerf compensation automatically` |
+| `kerfCompensatePart()` | `FlatPart.profile(kerf) / FlatPart.solid(kerf) — or Laser.kit({ kerf }), which compensates every part automatically` |
+| `lookupKerf()` | `Laser.lookupKerf(material, thickness, laserType)` |
+| `flatPanel()` | `Laser.panel(name, width, height, thickness, options) — identical arguments` |
+| `flatPart()` | `Laser.part(name, profile, thickness, edges, options) — identical arguments` |
+| `fingerJoint()` | `Laser.fingerJoint(partA, edgeA, partB, edgeB, options) — identical arguments` |
+| `tabSlot()` | `Laser.tabSlot(partA, edgeA, partB, edgeB, options) — identical arguments` |
+| `assemblyPreview()` | `Laser.kit(...).assemblyPreview(options) — the kit collects joints and applies its kerf (default 0.2 mm; this standalone form defaulted kerf to 0, so use Laser.kit({ kerf: 0 }) for byte-identical preview geometry); Laser.assemblyPreview(parts, joints, options) keeps the standalone form` |
+| `assemblyInstructions()` | `Laser.kit(...).assemblyInstructions(options) — the kit collects joints for you; Laser.instructions(parts, joints, options) keeps the standalone form` |
+| `formatInstructions()` | `Laser.kit(...).formatInstructions(options) — or Laser.formatInstructions(result) for the standalone form` |
+| `laserKit()` | `Laser.kit(options) — identical arguments` |
+| `COMMON_KERFS` | `Laser.COMMON_KERFS` |
+
+## viewport
+
+| Old name | Use instead |
+|----------|-------------|
+| `viewConfig()` | `scene({ jointOverlay: { ... } }) — same keys, on the one renderer-config global` |
+| `jointsView()` | `return the Assembly directly (return mech) — solver-backed controls appear automatically; use mech.addAnimation(name, { keyframes }) for animation clips` |
+| `showLabels()` | `Viewport.highlight(shape, { labels: true }) — then return the shape; highlight returns void` |
+| `highlight()` | `Viewport.highlight(target, options) — same arguments, namespaced with the other render-only overlays` |
+
+## output
+
+| Old name | Use instead |
+|----------|-------------|
+| `dimLine()` | `dim(line, opts) — dim() accepts a Line2D (or EdgeRef) directly` |
+
+## lib
+
+| Old name | Use instead |
+|----------|-------------|
+| `lib.boltHole()` | `shape.hole(face, { diameter, depth }) — face-relative blind/through holes with counterbore/countersink/thread support` |
+| `lib.counterbore()` | `shape.hole(face, { diameter: holeDia, counterbore: { diameter: boreDia, depth: boreDepth } }) — through by default; pass depth for blind holes` |
+| `lib.hexNut()` | `lib.nut(holeDia, { acrossFlats, height, boreDiameter: holeDia }) — exact same geometry` |
+| `lib.sideGear()` | `lib.faceGear(options) — identical arguments` |
+| `lib.sideGearPair()` | `lib.faceGearPair({ face, vertical, ... }) — same options with the side member renamed to face; diagnostics use facegear.* codes` |
+| `lib.gearBodyDisk()` | `lib.gearBodies.disk(options) — identical arguments` |
+| `lib.gearBodyDiskWithHub()` | `lib.gearBodies.diskWithHub(options) — identical arguments` |
+| `lib.gearBodySpoked()` | `lib.gearBodies.spoked(options) — identical arguments` |
+| `lib.gearBodyFromProfile()` | `lib.gearBodies.fromProfile(profile, options) — identical arguments` |
+
+## sdf
+
+| Old name | Use instead |
+|----------|-------------|
+| `combine()` | `sdf.combine(value, { op })` |
+| `Sculpt.circle()` | `Sculpt.disk(radius, thickness)` |
+| `Sculpt.path()` | `Sculpt.tube(points, options)` |
+| `sdf.morph()` | `a.morph(b, t)` |
+| `sdf.tpmsBlock()` | `sdf.gyroid({ cellSize, wallThickness }).intersect(sdf.box(x, y, z))` |
+| `sdf.withinBox()` | `shape.intersect(sdf.box(x, y, z))` |
+| `sdf.twist()` | `shape.twist(degreesPerUnit)` |
+| `sdf.bend()` | `shape.bend(radius)` |
+| `sdf.repeat()` | `shape.repeat(spacing, count)` |
+| `sdf.circularArray()` | `shape.circularArray(count, offset)` |
+| `SdfShape.move()` | `.at(x, y, z)` |
+| `SdfShape.goop()` | `.blend(other, { radius })` |
+| `SdfShape.keep()` | `.smoothIntersect(other, radius)` |
+| `SdfShape.clipBox()` | `.intersect(sdf.box(x, y, z))` |
+| `SdfShape.fillWith()` | `.intersect(pattern)` |
+| `SdfShape.fillWithGyroid()` | `.intersect(sdf.gyroid({ cellSize, wallThickness }))` |
+| `SdfShape.fillWithSchwarzP()` | `.intersect(sdf.schwarzP({ cellSize, wallThickness }))` |
+| `SdfShape.fillWithDiamond()` | `.intersect(sdf.diamond({ cellSize, wallThickness }))` |
+| `SdfShape.fillWithLidinoid()` | `.intersect(sdf.lidinoid({ cellSize, wallThickness }))` |

package/dist/docs-raw/generated/lib.md

@@ -33,55 +33,27 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 
 **Methods:**
 
-#### `toSketch()` — Convert the loop centerline into a thin visual sketch.
+#### `toSketch(width?: number): Sketch` — Convert the loop centerline into a thin visual sketch.
 
-```ts
-toSketch(width?: number): Sketch
-```
+#### `toProfile(): Sketch` — Convert the loop into a filled profile using the pitch path itself as the boundary.
 
-#### `toProfile()` — Convert the loop into a filled profile using the pitch path itself as the boundary.
-
-```ts
-toProfile(): Sketch
-```
-
-#### `offsetBand()` — Build a belt band sketch by offsetting the route to inner and outer pulley radii.
-
-```ts
-offsetBand(thickness: number): Sketch
-```
+#### `offsetBand(thickness: number): Sketch` — Build a belt band sketch by offsetting the route to inner and outer pulley radii.
 
 ### `DriveWheelBuilder`
 
-#### `addSpurTeethBetween()` — Add an involute spur-tooth window on part of the pitch circle.
-
-```ts
-addSpurTeethBetween(options: DriveWheelSpurTeethRegionOptions): this
-```
+#### `addSpurTeethBetween(options: DriveWheelSpurTeethRegionOptions): this` — Add an involute spur-tooth window on part of the pitch circle.
 
 `DriveWheelSpurTeethRegionOptions`: `{ name?: string, teethOnFullCircle: number, toothCount: number, firstTooth?: number, faceWidth?: number }`
 
-#### `addSolidArcBetween()` — Add a constant-radius solid arc region such as a dwell, stop, or pusher.
-
-```ts
-addSolidArcBetween(options: DriveWheelSolidArcRegionOptions): this
-```
+#### `addSolidArcBetween(options: DriveWheelSolidArcRegionOptions): this` — Add a constant-radius solid arc region such as a dwell, stop, or pusher.
 
 **`DriveWheelSolidArcRegionOptions`**: `name?: string`, `fromAngleDeg: number`, `toAngleDeg: number`, `innerRadius?: number`, `outerRadius: number`, `faceWidth?: number`, `segments?: number`
 
-#### `addShapeRegion()` — Add a fully custom region shape while preserving region metadata.
-
-```ts
-addShapeRegion(name: string, shape: Shape, options?: DriveWheelShapeRegionOptions): this
-```
+#### `addShapeRegion(name: string, shape: Shape, options?: DriveWheelShapeRegionOptions): this` — Add a fully custom region shape while preserving region metadata.
 
 `DriveWheelShapeRegionOptions`: `{ fromAngleDeg?: number, toAngleDeg?: number, innerRadius?: number, outerRadius?: number }`
 
-#### `build()` — Build the final wheel shape with a bore connector and region metadata.
-
-```ts
-build(): Shape
-```
+#### `build(): Shape` — Build the final wheel shape with a bore connector and region metadata.
 
 ---
 
@@ -91,69 +63,239 @@ build(): Shape
 
 Pre-built parametric parts available in user scripts as `lib.*`.
 
-Every key in this object becomes a method or namespace on the `lib` object exposed to `.forge.js` scripts. The catalog includes:
+Every key in this object becomes a method or namespace on the `lib` object exposed to `.forge.js` scripts — see the member list below for the catalog. Sizes outside the supported ranges throw at runtime with a descriptive error.
+
+- `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink.
+
+  Returns a cutter shape (subtract from a solid to produce the hole). Sizes outside M2–M10 will throw.
+
+  ```ts
+  const plate = box(60, 40, 8)
+    .subtract(lib.fastenerHole({ size: 'M5', fit: 'normal', depth: 8 })
+      .translate(15, 10, 4));
+  ```
+- `tube(outerX: number, outerY: number, outerZ: number, wall: number): Shape` — Rectangular hollow tube (thin-wall box section).
+
+  Both the outer and inner boxes are centered on the XY plane with their base at Z=0.
+- `pipe(height: number, outerRadius: number, wall: number, segments?: number): Shape` — Hollow cylindrical pipe.
+
+  Centered on the XY plane, extending upward along +Z from z=0 to z=height. For complex routed pipe geometry, see `lib.pipeRoute`.
+- `explode<T extends ExplodeItem[] | ShapeGroup>(items: T, options?: ExplodeOptions): T` — Apply deterministic exploded-view offsets to an assembly tree.
+
+  Traverses arrays, nested `{ name, group: [...] }` structures, and [`ShapeGroup`](/docs/core#shapegroup) outputs, translating each node while preserving names, colors, and nesting; returns the same structure type as the input. `radial` mode is branch-aware and parent-relative — nested assemblies peel apart level by level. Named items accept an inline `explode: { stage?, direction?, axisLock? }` override. Bakes the offset into geometry (e.g. driven by a `param()` slider); for a viewport-only slider use [`explodeView()`](/docs/viewport#explodeview) instead.
+
+  ```js
+  const explodeAmt = param('Explode', 0, { min: 0, max: 40, unit: 'mm' });
+
+  return lib.explode(assembly, {
+    amount: explodeAmt,
+    stages: [0.4, 0.8],
+    mode: 'radial',
+    byName: { Shaft: { direction: [1, 0, 0], stage: 1.4 } },
+  });
+  ```
+- `bracket(width: number, height: number, depth: number, thick: number, holeDia?: number): Shape` — L-shaped mounting bracket with optional through-holes.
+
+  Produces a right-angle bracket: a horizontal base plate and a vertical wall. Both legs share `width`. Optional holes are drilled through the base (along Z) and the wall (along Y).
+- `holePattern(rows: number, cols: number, spacingX: number, spacingY: number, holeDia: number, depth: number): Shape` — Rectangular grid of cylindrical hole cutters.
+
+  Returns the union of `rows × cols` cylinders laid out on a regular grid. Subtract from a solid to produce the full pattern.
+
+  ```ts
+  const pattern = lib.holePattern(3, 4, 20, 20, 4, 10);
+  const panel = box(80, 70, 10).subtract(pattern.translate(-30, -20, 0));
+  ```
+- `thread(diameter: number, pitch: number, length: number, options?: { depth?: number; segments?: number; }): Shape` — External helical thread — clean mesh, no SDF grid artifacts.
+
+  Builds a cross-section with a single trapezoidal tooth from the root radius out to the crest radius, then twist-extrudes it so the tooth traces a helix. Manifold's extrude+twist produces structured quad-based geometry that follows the thread profile cleanly.
+
+  Returns a threaded cylinder along +Z from z=0 to z=length.
+- `bolt(diameter: number, length: number, options?: { ... }): Shape` — ISO-style hex bolt with real helical threads.
+
+  The hex head sits from z=0 up to z=headHeight. The shaft extends downward along −Z by `length` mm. An unthreaded shank section is included when `threadLength < length`.
+
+  Default proportions follow ISO 4762 loosely: pitch ≈ 0.15×diameter, head height ≈ 0.65×diameter, across-flats ≈ 1.6×diameter.
+
+  For standard M-size bolts pre-configured for a complete joint, use `fastenerSet` instead.
+- `nut(diameter: number, options?: { ... }): Shape` — ISO-style hex nut with a clearance bore.
+
+  Constructed from the intersection of three rotated slabs with a cylindrical bore subtracted. The nut is centered at the origin, height along Z (−height/2 to +height/2).
+
+  Default proportions follow ISO 4032 loosely: height ≈ 0.8×diameter, across-flats ≈ 1.6×diameter. The bore is a clearance bore — `diameter` + 0.2 mm by default, override with `boreDiameter` for exact bore control — not modelled with helical threads, for rendering efficiency.
+
+  For standard M-size nuts pre-configured for a complete joint, use `fastenerSet` instead.
+- `washer(size: MetricSize, options?: { standard?: WasherStandard; segments?: number; }): Shape` — ISO metric flat washer (DIN 125-A).
+
+  Returns a flat ring centered at the origin, thickness along Z. Dimensions are taken from `WASHER_TABLE`. Sizes outside M2–M10 will throw.
+- `fastenerSet(size: MetricSize, boltLength: number, options?: FastenerSetOptions): FastenerSetResult` — Complete ISO metric fastener set — bolt, nut, optional washers, and matching hole cutters.
+
+  Returns all geometry for one bolted joint: the bolt, nut, up to two washers, a clearance-hole cutter, and a tap-drill cutter. All shapes are returned **un-positioned** (each on the Z-axis). Place them with `.translate()`.
+
+  Sizes outside M4–M10 are supported for the washer (M2–M10); unsupported combinations will throw.
 
-**Fasteners and hardware patterns:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern`
+  ```ts
+  const hw = lib.fastenerSet('M5', 20);
 
-**Structure:** `tube`, `pipe`, `bracket`, `pipeRoute`, `elbow`, `tSlotProfile`, `tSlotExtrusion`, `profile2020BSlot6Profile`, `profile2020BSlot6`
+  const topPlate = box(60, 40, 8).translate(0, 0, 12)
+    .subtract(hw.clearanceHole.translate(15, 10, 12));
+  const botPlate = box(60, 40, 8)
+    .subtract(hw.clearanceHole.translate(15, 10, 0));
 
-**Belt drives:** `beltDrive`, `tangentLoop2d`
+  return [
+    { name: 'Top Plate', shape: topPlate },
+    { name: 'Bot Plate', shape: botPlate },
+    { name: 'Bolt',      shape: hw.bolt.translate(15, 10, 20) },
+    { name: 'Nut',       shape: hw.nut.translate(15, 10, -4) },
+  ];
+  ```
+- `pipeRoute(points: Vec3[], radius: number, options?: { bendRadius?: number; wall?: number; segments?: number; }): Shape` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends.
 
-**Threads:** `thread`
+  This is a convenience recipe over `Curve.Route.fromPolyline()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route` directly when you need route metadata, named ports, or custom swept profiles.
+- `elbow(pipeRadius: number, bendRadius: number, angle?: number | { ... }, options?: { ... }): Shape` — Pipe elbow — a curved pipe section for connecting two pipe directions.
 
-**Gears:** `spurGear`, `sectorGear`, `driveWheel`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair`
+  This is a convenience recipe over `Curve.Arc()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route.fromPolyline()` directly when you need named route ports, segment metadata, or multi-bend pipe runs.
+- `beltDrive(options: BeltDriveOptions): BeltDriveResult` — Create a flat open-belt body around two pulley pitch circles.
 
-**Gear bodies:** `gearBodies.disk`, `gearBodies.diskWithHub`, `gearBodies.spoked`, `gearBodies.fromProfile` plus direct aliases `gearBodyDisk`, `gearBodyDiskWithHub`, `gearBodySpoked`, `gearBodyFromProfile`
+  The belt is generated as a tangent loop in the XY plane and extruded along +Z by `beltWidth`. The result includes the solid belt, the 2D belt profile, a thin pitch-path sketch for visualization, total belt length, tangent spans, and wrap metadata for each pulley.
 
-**Gear ratios (pure math helpers):** `gearRatio`, `rackRatio`, `planetaryRatio`
+  For more than two pulleys, the API intentionally asks for route intent before geometry is created. Use `route: "outer"` for the future outside-envelope mode, or an ordered route for future serpentine/idler layouts.
 
-**Bolt patterns:** `boltPattern` — define hole positions once, cut them from multiple parts
+  ```ts
+  const drive = lib.beltDrive({
+    pulleys: [
+      { name: "motor", center: [0, 0], pitchRadius: 12 },
+      { name: "output", center: [80, 0], pitchRadius: 28 },
+    ],
+    beltWidth: 8,
+    beltThickness: 2,
+  });
+  return drive.belt;
+  ```
+- `tangentLoop2d(circles: TangentCircle2D[], options?: TangentLoop2DOptions): TangentLoop2D` — Build a closed 2D route made from common tangent spans and pulley wrap arcs.
 
-**Utilities:** `explode`
+  Use this when you need reusable belt/chain route geometry before creating a solid body. The first implementation supports two circles. `mode: "open"` uses external tangents; `mode: "crossed"` uses internal tangents.
 
-Sizes outside the supported ranges will throw at runtime with a descriptive error.
+  ```ts
+  const route = lib.tangentLoop2d([
+    { center: [0, 0], radius: 12 },
+    { center: [80, 0], radius: 28 },
+  ]);
+  const belt = route.offsetBand(2).extrude(8);
+  ```
+- `tSlotProfile(options?: TSlotProfileOptions): Sketch` — Build a 2D T-slot cross-section sketch.
 
-- `boltHole(diameter: number, depth: number): Shape` — Simple cylindrical through-hole cutter centered on Z=0. Subtract the result from a part to produce a plain cylindrical clearance hole. For ISO metric sizes with fit classes and counterbore/countersink, use {
-- `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink. **Details** Returns a cutter shape (subtract from a solid to produce the hole). Sizes outside M2–M10 will throw. Extend `METRIC_HOLE_TABLE` in this file to add new sizes. **Example** ```ts const plate = box(60, 40, 8) .subtract(lib.fastenerHole({ size: 'M5', fit: 'normal', depth: 8 }) .translate(15, 10, 4)); ```
-- `counterbore(holeDia: number, boreDia: number, boreDepth: number, totalDepth: number): Shape` — Counterbore hole cutter — through-hole with a wider cylindrical recess at the top. Use for socket-head cap screws that must sit flush. Subtract from a solid. For ISO metric sizing and fit classes, prefer {
-- `tube(outerX: number, outerY: number, outerZ: number, wall: number): Shape` — Rectangular hollow tube (thin-wall box section). Both the outer and inner boxes are centered on the XY plane with their base at Z=0.
-- `pipe(height: number, outerRadius: number, wall: number, segments?: number): Shape` — Hollow cylindrical pipe. Centered on the XY plane, extending upward along +Z from z=0 to z=height. For complex routed pipe geometry, see `lib.pipeRoute`.
-- `explode<T extends ExplodeItem[] | ShapeGroup>(items: T, options?: ExplodeOptions): T` — Apply deterministic exploded-view offsets to an assembly tree. **Details** Traverses arrays of shapes/sketches/named items, nested `{ name, group: [...] }` structures, and [`ShapeGroup`](/docs/core#shapegroup) outputs, translating each node by a computed offset while preserving names, colors, and nesting. Returns the same structure type as the input. In `radial` mode the algorithm is branch-aware and parent-relative: each node fans out from its immediate parent's center, so nested assemblies peel apart level by level. Named items may also include an inline `explode: { stage?, direction?, axisLock? }` property to override per-item behavior. Use this function when you want to bake the explode offset into the geometry before returning (e.g. to drive the amount with a `param()` slider). For a viewport-only explode slider without rerunning the script, use [`explodeView()`](/docs/viewport#explodeview) instead. **Example** ```js const explodeAmt = param('Explode', 0, { min: 0, max: 40, unit: 'mm' }); return lib.explode(assembly, { amount: explodeAmt, stages: [0.4, 0.8], mode: 'radial', byName: { Shaft: { direction: [1, 0, 0], stage: 1.4 } }, }); ```
-- `hexNut(acrossFlats: number, height: number, holeDia: number): Shape` — Generic hex nut with a cylindrical bore. Constructed via intersection of three rotated rectangular slabs, then a bore is subtracted. Centered at origin, height along Z. For standard ISO metric nuts by thread size, use `lib.nut` instead.
-- `bracket(width: number, height: number, depth: number, thick: number, holeDia?: number): Shape` — L-shaped mounting bracket with optional through-holes. Produces a right-angle bracket: a horizontal base plate and a vertical wall. Both legs share `width`. Optional holes are drilled through the base (along Z) and the wall (along Y).
-- `holePattern(rows: number, cols: number, spacingX: number, spacingY: number, holeDia: number, depth: number): Shape` — Rectangular grid of cylindrical hole cutters. Returns the union of `rows × cols` cylinders laid out on a regular grid. Subtract from a solid to produce the full pattern. **Example** ```ts const pattern = lib.holePattern(3, 4, 20, 20, 4, 10); const panel = box(80, 70, 10).subtract(pattern.translate(-30, -20, 0)); ```
-- `thread(diameter: number, pitch: number, length: number, options?: { depth?: number; segments?: number; }): Shape` — External helical thread — clean mesh, no SDF grid artifacts. **Details** Builds a cross-section with a single trapezoidal tooth from the root radius out to the crest radius, then twist-extrudes it so the tooth traces a helix. Manifold's extrude+twist produces structured quad-based geometry that follows the thread profile cleanly. Returns a threaded cylinder along +Z from z=0 to z=length. **Example** ```ts const t = lib.thread(5, 0.8, 12); // M5 × 0.8 pitch, 12 mm long ```
-- `bolt(diameter: number, length: number, options?: { ... }): Shape` — ISO-style hex bolt with real helical threads. **Details** The hex head sits from z=0 up to z=headHeight. The shaft extends downward along −Z by `length` mm. An unthreaded shank section is included when `threadLength < length`. Default proportions follow ISO 4762 loosely: pitch ≈ 0.15×diameter, head height ≈ 0.65×diameter, across-flats ≈ 1.6×diameter. For standard M-size bolts pre-configured for a complete joint, use { **Example** ```ts const b = lib.bolt(5, 20); // M5 × 20 mm ```
-- `nut(diameter: number, options?: { pitch?: number; height?: number; acrossFlats?: number; segments?: number; }): Shape` — ISO-style hex nut with a threaded bore. **Details** Constructed from the intersection of three rotated slabs with a cylindrical bore subtracted. The nut is centered at the origin, height along Z. Default proportions follow ISO 4032 loosely: height ≈ 0.8×diameter, across-flats ≈ 1.6×diameter. The bore is a clearance bore (not modelled with helical threads) for rendering efficiency. For standard M-size nuts pre-configured for a complete joint, use { **Example** ```ts const n = lib.nut(5); // M5 nut ```
-- `washer(size: MetricSize, options?: { standard?: WasherStandard; segments?: number; }): Shape` — ISO metric flat washer (DIN 125-A). **Details** Returns a flat ring centered at the origin, thickness along Z. Dimensions are taken from { **Example** ```ts const w = lib.washer('M5'); // DIN 125-A M5 washer ```
-- `fastenerSet(size: MetricSize, boltLength: number, options?: FastenerSetOptions): FastenerSetResult` — Complete ISO metric fastener set — bolt, nut, optional washers, and matching hole cutters. **Details** Returns all geometry for one bolted joint: the bolt, nut, up to two washers, a clearance-hole cutter, and a tap-drill cutter. All shapes are returned **un-positioned** (each on the Z-axis). Place them with `.translate()`. Sizes outside M4–M10 are supported for the washer (M2–M10); unsupported combinations will throw. **Example** ```ts const hw = lib.fastenerSet('M5', 20); const topPlate = box(60, 40, 8).translate(0, 0, 12) .subtract(hw.clearanceHole.translate(15, 10, 12)); const botPlate = box(60, 40, 8) .subtract(hw.clearanceHole.translate(15, 10, 0)); return [ { name: 'Top Plate', shape: topPlate }, { name: 'Bot Plate', shape: botPlate }, { name: 'Bolt', shape: hw.bolt.translate(15, 10, 20) }, { name: 'Nut', shape: hw.nut.translate(15, 10, -4) }, ]; ```
-- `pipeRoute(points: [ number, number, number ][], radius: number, options?: { bendRadius?: number; wall?: number; segments?: number; }): Shape` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends. This is a convenience recipe over `Curve.Route.fromPolyline()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route` directly when you need route metadata, named ports, or custom swept profiles.
-- `elbow(pipeRadius: number, bendRadius: number, angle?: number | { ... }, options?: { ... }): Shape` — Pipe elbow — a curved pipe section for connecting two pipe directions. This is a convenience recipe over `Curve.Arc()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route.fromPolyline()` directly when you need named route ports, segment metadata, or multi-bend pipe runs.
-- `beltDrive(options: BeltDriveOptions): BeltDriveResult` — Create a flat open-belt body around two pulley pitch circles. The belt is generated as a tangent loop in the XY plane and extruded along +Z by `beltWidth`. The result includes the solid belt, the 2D belt profile, a thin pitch-path sketch for visualization, total belt length, tangent spans, and wrap metadata for each pulley. For more than two pulleys, the API intentionally asks for route intent before geometry is created. Use `route: "outer"` for the future outside-envelope mode, or an ordered route for future serpentine/idler layouts. ```ts const drive = lib.beltDrive({ pulleys: [ { name: "motor", center: [0, 0], pitchRadius: 12 }, { name: "output", center: [80, 0], pitchRadius: 28 }, ], beltWidth: 8, beltThickness: 2, }); return drive.belt; ```
-- `tangentLoop2d(circles: TangentCircle2D[], options?: TangentLoop2DOptions): TangentLoop2D` — Build a closed 2D route made from common tangent spans and pulley wrap arcs. Use this when you need reusable belt/chain route geometry before creating a solid body. The first implementation supports two circles. `mode: "open"` uses external tangents; `mode: "crossed"` uses internal tangents. ```ts const route = lib.tangentLoop2d([ { center: [0, 0], radius: 12 }, { center: [80, 0], radius: 28 }, ]); const belt = route.offsetBand(2).extrude(8); ```
-- `tSlotProfile(options?: TSlotProfileOptions): Sketch` — Build a 2D T-slot cross-section sketch. Default parameters describe a 20x20 B-type profile with slot 6. Use this when you want a drawing-ready profile sketch before extrusion.
+  Default parameters describe a 20x20 B-type profile with slot 6. Use this when you want a drawing-ready profile sketch before extrusion.
 - `tSlotExtrusion(length: number, options?: TSlotExtrusionOptions): Shape` — Build a T-slot extrusion from the generated 2D profile. Extrudes along +Z by default.
-- `profile2020BSlot6Profile(options?: Profile2020BSlot6ProfileOptions): Sketch` — Accurate-ish 2D profile for 20x20 B-type slot 6. Returns a drawing-ready Sketch centered at origin.
-- `profile2020BSlot6(length: number, options?: Profile2020BSlot6Options): Shape` — 20x20 B-type slot 6 extrusion with profile-accurate defaults. Pass option overrides if your supplier's profile differs slightly.
-- `spurGear(options: SpurGearOptions): Shape` — Involute external spur gear with optional center bore. Specify module, teeth, faceWidth as required parameters. Optional tuning includes pressureAngleDeg (default 20), backlash, clearance, addendum, dedendum, boreDiameter, and segmentsPerTooth (default 10). **Connectors (for assembly-based positioning):** - `bore`: revolute connector at the bore center, axis along +Z. Carries measurements: `{ module, teeth, pitchRadius, outerRadius, faceWidth }`. Use `.connect("Housing.seat", "Gear.bore")` to mount a gear on a shaft seat.
-- `bevelGear(options: BevelGearOptions): Shape` — Conical bevel gear generated from a tapered involute extrusion. Specify pitchAngleDeg directly or derive it from mateTeeth + shaftAngleDeg. **Connectors (for assembly-based positioning):** - `bore`: revolute connector at the large-end bore center (Z=0), axis along -Z (away from teeth). - `apex`: connector at the cone apex above the gear (the point where the pitch cone converges), axis along +Z. Useful for meshing two bevel gears — their apices should coincide. Carries measurements: `{ module, teeth, pitchRadius, pitchAngleDeg, coneDistance, faceWidth }`.
-- `faceGear(options: FaceGearOptions): Shape` — Face gear (crown style) where teeth are on one face (top or bottom) instead of the outer rim. Uses the same involute tooth sizing as spurGear, then projects the tooth band axially from one side. Alias for sideGear (which is kept for backward compatibility).
-- `sideGear(options: SideGearOptions): Shape` — Crown/face style gear where the teeth project from one side of the disk instead of the outer cylindrical rim.
-- `ringGear(options: RingGearOptions): Shape` — Internal ring gear with involute-derived tooth spaces. Specify rimWidth or outerDiameter for the annular body. **Connectors (for assembly-based positioning):** - `bore`: connector at the ring center, axis along +Z. For planetary gearboxes, this is where the ring mounts to the housing. Carries measurements: `{ module, teeth, pitchRadius, innerRadius, outerRadius, faceWidth }`.
-- `rackGear(options: RackGearOptions): Shape` — Linear rack gear with pressure-angle flanks. Use with spurGear for rack-and-pinion mechanisms. **Orientation:** teeth run along the X axis with tooth tips pointing +Y (pitch line at Y=0). The rack is extruded +Z by `faceWidth`. Rotate the rack to align with a different slide axis. **Connectors (for assembly-based positioning):** - `teeth`: prismatic connector at the pitch line center, axis along +X (slide direction). Carries measurements: `{ module, teeth, faceWidth, length }`. Connect to a housing's rack channel: ```js housing.withConnectors({ rack_channel: connector("rack-channel", { origin: [pitchR, 0, channelZ], axis: [1, 0, 0], kind: "prismatic", }), }); assembly.connect("Housing.rack_channel", "Rack.teeth", { as: "slide" }); ```
-- `gearPair(options: GearPairOptions): GearPairResult` — Build or validate a spur-gear pair and return ratio, backlash, and mesh diagnostics. Accepts either shapes from spurGear() or analytical specs for each member. When place is true (default), the gear is auto-positioned at the correct center distance.
+- `profile2020BSlot6Profile(options?: Profile2020BSlot6ProfileOptions): Sketch` — Accurate-ish 2D profile for 20x20 B-type slot 6.
+
+  Returns a drawing-ready Sketch centered at origin.
+- `profile2020BSlot6(length: number, options?: Profile2020BSlot6Options): Shape` — 20x20 B-type slot 6 extrusion with profile-accurate defaults.
+
+  Pass option overrides if your supplier's profile differs slightly.
+- `spurGear(options: SpurGearOptions): Shape` — Involute external spur gear with optional center bore.
+
+  Specify module, teeth, faceWidth as required parameters. Optional tuning includes pressureAngleDeg (default 20), backlash, clearance, addendum, dedendum, boreDiameter, and segmentsPerTooth (default 10).
+
+  **Connectors (for assembly-based positioning):**
+
+  - `bore`: revolute connector at the bore center, axis along +Z. Carries measurements: `{ module, teeth, pitchRadius, outerRadius, faceWidth }`.
+
+  Use `.connect("Housing.seat", "Gear.bore")` to mount a gear on a shaft seat.
+- `bevelGear(options: BevelGearOptions): Shape` — Conical bevel gear generated from a tapered involute extrusion. Specify pitchAngleDeg directly or derive it from mateTeeth + shaftAngleDeg.
+
+  **Connectors (for assembly-based positioning):**
+
+  - `bore`: revolute connector at the large-end bore center (Z=0), axis along -Z (away from teeth).
+  - `apex`: connector at the cone apex above the gear (the point where the pitch cone converges), axis along +Z. Useful for meshing two bevel gears — their apices should coincide.
+
+  Carries measurements: `{ module, teeth, pitchRadius, pitchAngleDeg, coneDistance, faceWidth }`.
+- `faceGear(options: FaceGearOptions): Shape` — Face gear (crown style) where the teeth project axially from one face (top or bottom) of the disk instead of the outer cylindrical rim.
+
+  Uses the same involute tooth sizing as spurGear, then projects the tooth band axially from the chosen side (`side`, default `'top'`) with axial tooth height `toothHeight` (default: one module). To mesh it with a perpendicular spur pinion, prefer `lib.faceGearPair()` — it rotates and positions the pinion at the face tooth band for you.
+
+  **Connectors (for assembly-based positioning):**
+
+  - `bore`: revolute connector at the bore center on the body side (the face opposite the teeth), axis pointing away from the teeth. Carries measurements: `{ module, teeth, pitchRadius, outerRadius, faceWidth, toothSide }`.
+
+  ```js
+  const crown = lib.faceGear({ module: 1.5, teeth: 30, faceWidth: 5, boreDiameter: 6 });
+  assembly().connect("Housing.crown_seat", "Crown.bore");
+  ```
+- `ringGear(options: RingGearOptions): Shape` — Internal ring gear with involute-derived tooth spaces. Specify rimWidth or outerDiameter for the annular body.
+
+  **Connectors (for assembly-based positioning):**
+
+  - `bore`: connector at the ring center, axis along +Z. For planetary gearboxes, this is where the ring mounts to the housing. Carries measurements: `{ module, teeth, pitchRadius, innerRadius, outerRadius, faceWidth }`.
+- `rackGear(options: RackGearOptions): Shape` — Linear rack gear with pressure-angle flanks. Use with spurGear for rack-and-pinion mechanisms.
+
+  **Orientation:** teeth run along the X axis with tooth tips pointing +Y (pitch line at Y=0). The rack is extruded +Z by `faceWidth`. Rotate the rack to align with a different slide axis.
+
+  **Connectors (for assembly-based positioning):**
+
+  - `teeth`: prismatic connector at the pitch line center, axis along +X (slide direction). Carries measurements: `{ module, teeth, faceWidth, length }`.
+
+  Connect to a housing's rack channel:
+
+  ```js
+  housing.withConnectors({
+    rack_channel: connector("rack-channel", {
+      origin: [pitchR, 0, channelZ], axis: [1, 0, 0], kind: "prismatic",
+    }),
+  });
+  assembly.connect("Housing.rack_channel", "Rack.teeth", { as: "slide" });
+  ```
+- `gearPair(options: GearPairOptions): GearPairResult` — Build or validate a spur-gear pair and return ratio, backlash, and mesh diagnostics.
+
+  Accepts either shapes from spurGear() or analytical specs for each member. When place is true (default), the gear is auto-positioned at the correct center distance.
 - `bevelGearPair(options: BevelGearPairOptions): BevelGearPairResult` — Build or validate a bevel-gear pair and return ratio diagnostics plus recommended joint placement vectors.
-- `faceGearPair(options: FaceGearPairOptions): FaceGearPairResult` — Build or validate a perpendicular pair between a face gear and a vertical spur gear.
-- `sideGearPair(options: SideGearPairOptions): SideGearPairResult` — Pair helper for side (crown/face) gear + perpendicular "vertical" spur gear. Auto-placement rotates the spur around +Y and positions it to mesh at the side tooth band.
-- `gearRatio(teethA: number, teethB: number, options?: { internal?: boolean; }): number` — Coupling ratio between two meshed spur gears. When gear A turns 1°, gear B turns `-teethA / teethB` degrees (negative because meshed external gears rotate in opposite directions). Pass `{ internal: true }` for internal gear pairs (ring gear + spur/planet), where the two rotate in the same direction.
-- `rackRatio(module: number, pinionTeeth: number): number` — Coupling ratio between a pinion and a rack. When the pinion rotates by `θ` degrees, the rack slides by `θ × (π × module × teeth / 360)` mm. Equivalently, 1mm of rack travel = `180 / (π × pitchRadius)` degrees of pinion rotation.
-- `planetaryRatio(sunTeeth: number, ringTeeth: number): number` — Planetary gear reduction ratio when the ring is held fixed. Input: sun. Output: carrier. Ratio: `1 + ringTeeth / sunTeeth`. One turn of the sun produces `1 / ratio` turns of the carrier.
-- `boltPattern(options: BoltPatternOptions): BoltPattern` — Define a bolt pattern once and cut it from multiple parts. const base = bolts.cut(box(60, 50, 10), 12, { from: -1 }); const cover = bolts.cut(box(60, 50, 3), 5, { from: -1 }); // Same positions in both parts — guaranteed aligned. ```
+- `faceGearPair(options: FaceGearPairOptions): FaceGearPairResult` — Pair helper for a face (crown) gear + perpendicular "vertical" spur gear. Auto-placement rotates the spur around +Y and positions it to mesh at the face tooth band.
+- `gearRatio(teethA: number, teethB: number, options?: { internal?: boolean; }): number` — Coupling ratio between two meshed spur gears.
+
+  When gear A turns 1°, gear B turns `-teethA / teethB` degrees (negative because meshed external gears rotate in opposite directions).
+
+  ```js
+  const drivenPerDriver = lib.gearRatio(12, 24); // -0.5
+  verify.equal("external spur ratio", drivenPerDriver, -0.5);
+
+  Pass `{ internal: true }` for internal gear pairs (ring gear + spur/planet),
+  where the two rotate in the same direction.
+  ```
+- `rackRatio(module: number, pinionTeeth: number): number` — Coupling ratio between a pinion and a rack.
+
+  When the pinion rotates by `θ` degrees, the rack slides by `θ × (π × module × teeth / 360)` mm. Equivalently, 1mm of rack travel = `180 / (π × pitchRadius)` degrees of pinion rotation.
+
+  ```js
+  const pinionDegPerMm = lib.rackRatio(1.5, 12); // ~6.37 deg/mm
+  ```
+- `planetaryRatio(sunTeeth: number, ringTeeth: number): number` — Planetary gear reduction ratio when the ring is held fixed.
+
+  Input: sun. Output: carrier. Ratio: `1 + ringTeeth / sunTeeth`. One turn of the sun produces `1 / ratio` turns of the carrier.
+- `boltPattern(options: BoltPatternOptions): BoltPattern` — Define a bolt pattern once and cut it from multiple parts.
+
+  ```js
+  const bolts = lib.boltPattern({
+    size: 'M5',
+    positions: [[20, 15], [-20, 15], [20, -15], [-20, -15]],
+  });
+
+  const base  = bolts.cut(box(60, 50, 10), 12, { from: -1 });
+  const cover = bolts.cut(box(60, 50, 3), 5, { from: -1 });
+  // Same positions in both parts — guaranteed aligned.
+  ```
 - `driveWheel(options?: DriveWheelOptions): DriveWheelBuilder` — Start a composable exceptional gear or drive wheel.
 - `readDriveWheelMeta(shape: Shape): DriveWheelMeta | null` — Read the functional-region metadata attached by `driveWheel().build()`.
-- `sectorGear(options: SectorGearOptions): Shape` — Involute sector gear with teeth on only part of the pitch circle. Specify the full-circle pitch as `teethOnFullCircle`, then choose the active tooth window with `firstTooth` and `toothCount`. The body is separate from the tooth region: pass a `gearBody...` shape for spokes, hubs, and product styling, or omit it for a simple root-radius disk. **Example** ```ts const body = lib.gearBodies.spoked({ outerRadius: 22, rimWidth: 3, hubDiameter: 10, spokeCount: 5, spokeWidth: 2.5, faceWidth: 8, boreDiameter: 5, }); const sector = lib.sectorGear({ module: 1.25, teethOnFullCircle: 36, toothCount: 10, faceWidth: 8, body, }); ```
+- `sectorGear(options: SectorGearOptions): Shape` — Involute sector gear with teeth on only part of the pitch circle.
+
+  Specify the full-circle pitch as `teethOnFullCircle`, then choose the active tooth window with `firstTooth` and `toothCount`. The body is separate from the tooth region: pass a `gearBody...` shape for spokes, hubs, and product styling, or omit it for a simple root-radius disk.
+
+  ```ts
+  const body = lib.gearBodies.spoked({
+    outerRadius: 22, rimWidth: 3, hubDiameter: 10,
+    spokeCount: 5, spokeWidth: 2.5, faceWidth: 8, boreDiameter: 5,
+  });
+  const sector = lib.sectorGear({
+    module: 1.25, teethOnFullCircle: 36, toothCount: 10,
+    faceWidth: 8, body,
+  });
+  ```
 - `gearBodies: { ... }` — Gear body preset namespace: disk, diskWithHub, spoked, and fromProfile.
-- `gearBodyDisk(options: GearBodyDiskOptions): Shape` — Solid disk/ring gear body, independent from any tooth geometry.
-- `gearBodyDiskWithHub(options: GearBodyDiskWithHubOptions): Shape` — Disk gear body with a raised center hub.
-- `gearBodySpoked(options: GearBodySpokedOptions): Shape` — Spoked gear body with an outer rim, center hub, and radial spokes.
-- `gearBodyFromProfile(profile: Sketch, options: GearBodyFromProfileOptions): Shape` — Extrude a custom 2D profile into a gear body.