forgecad 0.10.4 → 0.10.5

package/dist-skill/docs/guides/structural-fea.md

@@ -0,0 +1,224 @@
+---
+skill-group: cli
+skill-order: 3
+---
+
+# Structural FEA Stress Inspection
+
+Use structural FEA when you want a ForgeCAD model to answer a load-case question:
+
+- Where does this part see the highest stress?
+- How far does it deflect?
+- What is the minimum safety factor against the material yield strength?
+- Did the mesh and solver produce evidence that is good enough to inspect?
+
+ForgeCAD owns the authoring contract, solver orchestration, result feedback, and inspection report. The numerical solve is done out of process with Gmsh and CalculiX. Users author a study in the model, run `forgecad fea run`, and inspect a result bundle.
+
+## What You Get
+
+A solved FEA result bundle can produce:
+
+- max von Mises stress
+- max displacement
+- minimum safety factor
+- mesh quality and solver trust flags
+- region-level hot spots
+- `report.html`
+- `summary.json`
+- a safety-factor heatmap PNG
+- a solver stress heatmap PNG
+- a displacement magnitude heatmap PNG
+
+The deformed render is display-only. It helps explain the displacement shape; it does not change the stress, displacement, or safety-factor numbers reported by the solver.
+
+## What You Need Installed
+
+The ForgeCAD CLI creates the package and renders the heatmap. The package runner uses self-contained `uv` Python scripts for Gmsh so every package resolves the same Python dependency set by default.
+
+Run `forgecad doctor` to check these optional FEA tools in a separate section. Missing FEA tools do not block core ForgeCAD modeling, export, or render commands.
+
+| Tool | Used For | Quick Check |
+| --- | --- | --- |
+| `uv` | Runs the packaged Python scripts with pinned dependencies | `uv --version` |
+| CalculiX `ccx` | Solves the static stress deck | `ccx -v` |
+| Bash | Runs the package script | `bash --version` |
+| Chrome or Chromium | Renders PNG heatmaps from solved evidence | Chrome installed in a standard location, `CHROME_PATH=/path/to/chrome`, or `--chrome-path /path/to/chrome` |
+
+If `uv` is not on `PATH`, set `UV=/path/to/uv` when running `forgecad fea run` or `forgecad fea check`.
+
+If `ccx` is not on `PATH`, set `CCX=/path/to/ccx` when running `forgecad fea run` or `forgecad fea check`.
+
+If you need an offline or pre-provisioned Python environment, set `PYTHON=/path/to/python`. That opt-out Python must be able to `import gmsh`; use `GMSH_PYTHONPATH` / `GMSH_PYTHON_PATH` only for that override path.
+
+ForgeCAD does not bundle CalculiX. The generated `uv` scripts pin the Gmsh Python package, and `uv` downloads/caches it from the configured Python package index. If you redistribute solver binaries or Python wheels to customers, handle their licenses as part of your distribution.
+
+## Author The Study
+
+Structural FEA starts in the `.forge.js` file. The script should return an authored `assembly(...)` with:
+
+1. a structural part marked with `Fea.body(...)`
+2. one or more static stress studies from `Fea.study.staticStress(...)`
+3. explicit fixtures and loads
+4. a second-order tetrahedral mesh intent
+
+```js
+const aluminum = Fea.material("6061-T6", {
+  densityKgM3: 2700,
+  youngsModulusMPa: 68900,
+  poissonRatio: 0.33,
+  yieldStrengthMPa: 276,
+});
+
+const beam = box(120, 12, 12);
+
+return assembly("Cantilever Stress Study")
+  .addPart("Beam", beam, {
+    fea: Fea.body({ material: aluminum }),
+  })
+  .withFeaStudy(
+    Fea.study.staticStress("end-load", {
+      fixtures: [
+        Fea.fix.fixed(Fea.region.face("fixed-end", beam.face("left"))),
+      ],
+      loads: [
+        Fea.load.force(Fea.region.face("load-end", beam.face("right")), {
+          newtons: 80,
+          direction: [0, 0, -1],
+        }),
+      ],
+      target: Fea.target.minSafetyFactor(2),
+      mesh: Fea.mesh.quadraticTets({ maxSizeMm: 4 }),
+    }),
+  );
+```
+
+The complete API reference is generated from source in [Assembly](../generated/assembly.md). Keep reusable examples in `.forge.js` files; do not duplicate every API signature in handwritten docs.
+
+## Choose Stable Regions
+
+Fixtures and loads must name real geometric regions. ForgeCAD will not guess them later.
+
+Use `Fea.region.face(...)` when you can refer to a compiler-owned exact face, such as a simple box face or a named face from the model API.
+
+Use `Fea.region.plane(...)` when the target is a planar face created by profiles, booleans, or imported geometry and the face name is not stable enough. Make the plane specific enough that it matches exactly one STEP/Gmsh surface.
+
+During export, ForgeCAD writes a region map and a STEP tag plan. During the package run, the Gmsh preflight matches every authored fixture/load region against the STEP surfaces. Missing or ambiguous matches fail hard. That is intentional: a silent substitute face would make the stress result untrustworthy.
+
+## Run The Flow
+
+Installed users run the CLI as `forgecad`. Developers running inside this repository can replace `forgecad` with `node dist-cli/forgecad.js`.
+
+Run every authored FEA study and save an inspection result bundle:
+
+```bash
+forgecad fea run examples/analysis/structural-stress-fea.forge.js
+```
+
+Run one named study:
+
+```bash
+forgecad fea run bracket.forge.js --study side-load
+```
+
+Open the report:
+
+```bash
+forgecad fea open out/bracket-fea
+```
+
+Render a customer-facing safety view:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field safety
+```
+
+Render the engineering stress heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field stress
+```
+
+Render the displacement magnitude heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field displacement
+```
+
+Render a deformed stress view only when the displacement shape is useful to inspect:
+
+```bash
+forgecad fea render out/bracket-fea/side-load \
+  --field stress \
+  --shape deformed \
+  --exaggerate 10
+```
+
+The deformation scale only affects the render. It does not change the reported stress, displacement, or safety factor.
+
+Each solved study result directory includes:
+
+- `report.html` for the human inspection report
+- `summary.json` for automation
+- `renders/safety-factor.png` for the customer-facing safety heatmap
+- `renders/stress.png` for the engineering von Mises stress heatmap
+
+Displacement and deformed-shape PNGs are explicit render outputs from `forgecad fea render --field displacement` or `--shape deformed`.
+
+Compare two solved result bundles:
+
+```bash
+forgecad fea compare out/baseline-fea/side-load out/four-x-fea/side-load
+```
+
+Comparison renders use one shared camera, image size, and safety-factor legend.
+
+Run in CI and fail the process when authored targets fail:
+
+```bash
+forgecad fea check bracket.forge.js --json
+```
+
+## Read The Results
+
+Start with `report.html` or `summary.json` in the result directory. The important fields are the maximum stress, maximum displacement, minimum safety factor, hot spots, and any mesh or solver trust findings.
+
+The default user-facing result is safety factor because it answers "is this part okay?" Use stress when you need the raw engineering von Mises field.
+
+Advanced users can still run the lower-level package flow:
+
+```bash
+forgecad export fea model.forge.js --output out/beam.feapkg
+forgecad sim fea out/beam.feapkg --json
+forgecad inspect structural stress out/beam.feapkg --camera iso --output out/stress.png
+```
+
+Those commands are useful for debugging package evidence. Customer docs should prefer `forgecad fea ...`.
+
+## Current Scope
+
+Structural FEA V1 is intentionally narrow:
+
+- linear static stress only
+- one structural body per package
+- exact OCCT STEP export only
+- second-order tetrahedral elements only
+- fixed fixtures and force loads only
+- no contacts, bonded assemblies, thermal loads, buckling, fatigue, plasticity, or certification workflow
+
+ForgeCAD refuses mesh or faceted fallback for FEA export. If exact geometry export, region mapping, mesh quality, solver convergence, result parsing, or evidence trust fails, the command should fail with an actionable error instead of inventing a weaker path.
+
+## Troubleshooting
+
+| Symptom | What It Means | What To Do |
+| --- | --- | --- |
+| `FEA.TOOLCHAIN_UV_MISSING` | The package runner cannot find `uv`. | Install `uv` or run with `UV=/path/to/uv`. |
+| `FEA.TOOLCHAIN_PYTHON_MISSING` | A `PYTHON=...` override points to a missing Python executable. | Install Python 3 or fix the `PYTHON` path. |
+| `FEA.TOOLCHAIN_GMSH_MISSING` | The selected Python process cannot import Gmsh. | Prefer the default `uv` path, or install the Gmsh Python module for the `PYTHON=...` override. |
+| `FEA.TOOLCHAIN_CCX_MISSING` | CalculiX is not available as `ccx`. | Install CalculiX or run with `CCX=/path/to/ccx`. |
+| `FEA.GMSH_FACE_MATCH_NONE` | An authored fixture/load region did not match a STEP surface. | Use a more stable face reference or a more precise planar region. |
+| `FEA.GMSH_FACE_MATCH_AMBIGUOUS` | A region matched more than one STEP surface. | Make the target region more specific or change the model so the load/fixture face is unique. |
+| `FEA.MESH_QUALITY_BELOW_TARGET` | The mesh exists but did not meet the package quality target. | Reduce mesh size, simplify tiny features, or improve the geometry around the hot area. |
+| `FEA.SOLVER_FAILED` | CalculiX did not complete the solve. | Inspect `solver/static_stress.log`, then check fixtures, loads, material values, and over-constraint. |
+| `FEA.FIELD_UNTRUSTED` | The heatmap input is not trusted package evidence. | Run inspection on the `.feapkg` directory after `forgecad sim fea`, not a copied JSON file. |
+
+For command flags, use the [CLI reference](../CLI.md). For the public API, use the generated [Assembly reference](../generated/assembly.md).

package/dist-skill/website/skills/forgecad.md

@@ -114,6 +114,7 @@ Test-run, export pipelines, debug flags.
 
 - `docs/skill/CLI.md`
 - `docs/skill/guides/inspection-bundles.md`
+- `docs/skill/guides/structural-fea.md`
 
 #### SDF Modeling (smooth booleans, TPMS, deformations, fromFunction)
 

package/examples/analysis/structural-stress-fea.forge.js

@@ -0,0 +1,19 @@
+const aluminum = Fea.material('6061-T6', {
+  densityKgM3: 2700,
+  youngsModulusMPa: 68900,
+  poissonRatio: 0.33,
+  yieldStrengthMPa: 276,
+});
+
+const beam = box(200, 20, 10);
+
+return assembly('Cantilever FEA')
+  .addPart('Beam', beam, { fea: Fea.body({ material: aluminum }) })
+  .withFeaStudy(
+    Fea.study.staticStress('tip-load', {
+      fixtures: [Fea.fix.fixed(Fea.region.face('Beam', 'left'))],
+      loads: [Fea.load.force(Fea.region.face('Beam', 'right'), { newtons: 100, direction: [0, 0, -1] })],
+      target: Fea.target.minSafetyFactor(2),
+      mesh: Fea.mesh.quadraticTets({ maxSizeMm: 3 }),
+    }),
+  );

package/examples/api/blend-full-round.forge.js

@@ -0,0 +1,37 @@
+// Full round and face fillet — two face-driven blends. Both require OCCT.
+const length = param('Length', 90);
+const railWidth = param('Rail Width', 14);
+const height = param('Height', 30);
+const gap = length * 0.75;
+
+// A bar whose narrow top face ("top") sits between the two long side faces.
+function bar() {
+  return box(length, railWidth, height);
+}
+
+// Full round: roll a blend over the narrow top face so the two sides meet
+// tangentially. The radius defaults to half the center-face span.
+const rounded = Blend.FullRound({
+  shape: bar(),
+  centerFace: bar().face('top'),
+})
+  .translate(-gap, 0, 0)
+  .color('#9ed892');
+
+// Face fillet: blend every edge shared by the top face and one side face.
+const seed = bar();
+const faceFilleted = Blend.Face({
+  shape: seed,
+  faces: [seed.face('top'), seed.face('side-right')],
+  radius: 5,
+})
+  .translate(gap, 0, 0)
+  .color('#e8c06a');
+
+verify.noSelfIntersection('Full round is a valid solid', rounded);
+verify.noSelfIntersection('Face fillet is a valid solid', faceFilleted);
+
+return [
+  { name: 'Full Round (top consumed)', shape: rounded },
+  { name: 'Face Fillet (top x side-right)', shape: faceFilleted },
+];

package/examples/api/blend-variable-radius.forge.js

@@ -0,0 +1,51 @@
+// Variable-radius edge fillet — the blend tapers along the edge instead of
+// holding a single radius. Requires the OCCT backend.
+const width = param('Width', 80);
+const depth = param('Depth', 40);
+const height = param('Height', 24);
+const gap = width * 0.95;
+
+function block() {
+  return box(width, depth, height);
+}
+
+// Constant radius — the reference.
+const constant = Blend.Edge({
+  shape: block(),
+  edges: [block().edge('top-right')],
+  radius: 4,
+})
+  .translate(-gap, 0, 0)
+  .color('#8aa0c8');
+
+// Linear taper from 1mm at u=0 to 8mm at u=1 along the same edge.
+const tapered = Blend.Edge({
+  shape: block(),
+  edges: [block().edge('top-right')],
+  variableRadius: { start: 1, end: 8 },
+})
+  .color('#9ed892');
+
+// Station law — a bulge in the middle of the edge.
+const bulged = Blend.Edge({
+  shape: block(),
+  edges: [block().edge('top-right')],
+  variableRadius: {
+    stations: [
+      { at: 0, radius: 1 },
+      { at: 0.5, radius: 7 },
+      { at: 1, radius: 1 },
+    ],
+  },
+})
+  .translate(gap, 0, 0)
+  .color('#e8c06a');
+
+verify.noSelfIntersection('Tapered fillet is a valid solid', tapered);
+verify.noSelfIntersection('Bulged fillet is a valid solid', bulged);
+
+return [
+  { name: 'Constant r=4', shape: constant },
+  { name: 'Linear taper 1->8', shape: tapered },
+  { name: 'Station bulge 1-7-1', shape: bulged },
+];

package/examples/api/curve-project-and-intersect.forge.js

@@ -0,0 +1,59 @@
+// Projected curve & surface-surface intersection curve on Surface.Net sheets.
+//
+// Curve.ProjectOnSurface drapes a planned guide line onto a freeform panel along
+// the surface normal; the foot curve becomes a real on-surface seam bead.
+// Curve.Intersect follows the surface-surface intersection of two sheets and
+// returns the exact NURBS seam where they meet, which we sweep into a weld bead.
+
+const span = param('Span', 120);
+const depth = param('Depth', 100);
+const crown = param('Crown', 22);
+
+// A gently crowned panel.
+const panelCage = [];
+const M = 6;
+const N = 6;
+for (let i = 0; i <= M; i++) {
+  const row = [];
+  for (let j = 0; j <= N; j++) {
+    const x = (i / M) * span - span / 2;
+    const y = (j / N) * depth - depth / 2;
+    const z = Math.sin((i / M) * Math.PI) * crown + Math.cos((j / N) * Math.PI) * (crown * 0.4);
+    row.push([x, y, z]);
+  }
+  panelCage.push(row);
+}
+const panel = Surface.Net().cage(panelCage).degree(3, 3);
+const panelSolid = panel.thicken(2).color('#9fd3ff');
+
+// 1) Project a straight guide onto the crowned panel → on-surface seam.
+const guide = Curve.Line([-span * 0.4, -depth * 0.2, crown * 2], [span * 0.4, depth * 0.2, crown * 2]);
+const seam = Curve.ProjectOnSurface(guide, panel, { samples: 64, maxGap: crown * 3 });
+const seamBead = sweep(circle2d(0.8), seam).color('#ffd166');
+
+// 2) Intersect the panel with a vertical cutting sheet → exact intersection curve.
+const cutCage = [];
+for (let i = 0; i <= 4; i++) {
+  const row = [];
+  for (let j = 0; j <= 4; j++) {
+    const t = i / 4;
+    row.push([(t - 0.5) * span * 0.9, (t - 0.5) * depth * 0.4, (j / 4) * crown * 2]);
+  }
+  cutCage.push(row);
+}
+const cutSheet = Surface.Net().cage(cutCage).degree(3, 1);
+
+const branches = Curve.Intersect(panel, cutSheet, { samples: 40 });
+if (branches.length === 0) throw new Error('Expected the panel and cutting sheet to intersect.');
+const weldBeads = branches.map((branch) => sweep(circle2d(0.9), branch).color('#ef476f'));
+
+scene({
+  background: { top: '#eef3f8', bottom: '#fbfdff' },
+  camera: { position: [0, -260, 150], target: [0, 0, 24], fov: 34 },
+});
+
+return [
+  { name: 'Crowned Panel', shape: panelSolid },
+  { name: 'Projected Seam Bead', shape: seamBead },
+  ...weldBeads.map((shape, index) => ({ name: `Intersection Weld ${index + 1}`, shape })),
+];

package/examples/api/extrude-up-to-face.forge.js

@@ -0,0 +1,47 @@
+/**
+ * Reference-based extrude end conditions.
+ *
+ * Instead of guessing a numeric height, terminate an extrusion against a real
+ * reference: a face on another part, an arbitrary plane, or a vertex. The extent
+ * collapses to a numeric distance before the solid is built, so this works on
+ * every backend.
+ *
+ * - `extrude({ upToFace })`  — flush with another shape's planar face.
+ * - `extrude({ upToPlane, offset })` — to a plane, then a margin past it.
+ */
+
+scene({
+  camera: { position: [120, -140, 90], target: [0, 0, 25], fov: 32 },
+});
+
+// A lid sitting above the build plate; its bottom face is the termination target.
+const lid = box(60, 60, 6).translate(0, 0, 40).color('#9aa7b4');
+
+// Boss grown from the plate exactly up to the lid's underside (z = 40).
+const boss = circle2d(10).extrude({ upToFace: lid.face('bottom') }).color('#d98c5f');
+
+// A post that rises to a plane at z = 30, then 4 mm past it (a press-fit stub).
+const post = rect(10, 10)
+  .translate(22, 0)
+  .extrude({ upToPlane: { normal: [0, 0, 1], offset: 30 }, offset: 4 })
+  .color('#5f9ed9');
+
+// A pin that stops at the plane through a vertex.
+const pin = circle2d(4)
+  .translate(-22, 0)
+  .extrude({ upToVertex: [0, 0, 18] })
+  .color('#6fb86f');
+
+verify.notEmpty('boss is a solid', boss);
+verify.boundingBoxSize('boss reaches the lid underside (height 40)', boss, [20, 20, 40], 1);
+verify.boundingBoxSize('post stops 4 mm past the z=30 plane', post, [10, 10, 34], 1);
+verify.boundingBoxSize('pin stops at the z=18 vertex plane', pin, [8, 8, 18], 1);
+
+return [
+  { name: 'extrude up-to references', group: [
+    { name: 'Lid', shape: lid },
+    { name: 'Boss (upToFace)', shape: boss },
+    { name: 'Post (upToPlane + offset)', shape: post },
+    { name: 'Pin (upToVertex)', shape: pin },
+  ] },
+];

package/examples/api/spoon-full-tang-handle.forge.js

@@ -0,0 +1,148 @@
+/**
+ * Spoon — v4 smooth-clamp metal bowl + full-tang polymer handle.
+ *
+ * Built like a full-tang kitchen knife, in two materials:
+ *  - METAL HEAD: the smooth-clamp dished bowl (see the spoon tutorial / step5_v4),
+ *    flowing into a flat steel TANG that runs the whole length of the handle.
+ *  - POLYMER GRIP: a comfortable rounded handle (variableSweep) that is SPLIT by the
+ *    tang into a top + bottom scale, so the steel tang reads as a liner line around
+ *    the handle's equator — the classic full-tang look.
+ *  - Exposed steel BOLSTER where the bowl meets the handle, a steel BUTT at the end,
+ *    and three steel RIVETS pinning the scales to the tang.
+ *
+ * Two materials are returned as a colored group (steel + dark polymer).
+ *
+ * The bowl recipe is the key idea from the build: a smooth-clamped parabola
+ *   f(s) = s / sqrt(1 + (s/S)^2),   s = (y/hw)^2
+ * which is a pure (round) parabola in the visible bowl but C-infinity smooth, so the
+ * wall has no kink to ring around — the rim stays glassy, not wavy.
+ */
+
+scene({
+  camera: { position: [95, -260, 250], target: [20, 2, -6], fov: 36 },
+});
+
+// ───────────────────────── 1. the v4 metal bowl ─────────────────────────
+const H = 5.5; // rim level
+const S = 5.0; // smooth-clamp knee
+const stations = [
+  { x: -92, hw: 0, lowZ: 5.0 },
+  { x: -90.5, hw: 12, lowZ: 2.0 },
+  { x: -88, hw: 17.5, lowZ: -0.5 },
+  { x: -82, hw: 22.5, lowZ: -4.0 },
+  { x: -67, hw: 28, lowZ: -8.5 },
+  { x: -48, hw: 32, lowZ: -10.2 }, // widest & deepest
+  { x: -28, hw: 29, lowZ: -8.4 },
+  { x: -6, hw: 13, lowZ: -2.0 },
+  { x: 12, hw: 8.4, lowZ: 2.5 },
+  { x: 24, hw: 7.1, lowZ: 4.0 }, // neck
+];
+
+function smoothField(key) {
+  const pts = Curve.Fit(stations.map((s) => [s.x, s[key], 0]), { tolerance: 0.0005 }).sample(600);
+  return (x) => {
+    if (x <= pts[0][0]) return pts[0][1];
+    if (x >= pts[pts.length - 1][0]) return pts[pts.length - 1][1];
+    for (let i = 1; i < pts.length; i += 1) {
+      if (x <= pts[i][0]) {
+        const t = (x - pts[i - 1][0]) / (pts[i][0] - pts[i - 1][0]);
+        return pts[i - 1][1] + (pts[i][1] - pts[i - 1][1]) * t;
+      }
+    }
+    return pts[pts.length - 1][1];
+  };
+}
+const lowAt = smoothField('lowZ');
+const hwAt = smoothField('hw');
+
+function dishZ(x, y) {
+  const hw = hwAt(x);
+  const lz = lowAt(x);
+  if (hw < 1e-6) return lz + (H - lz) * S;
+  const s = (y / hw) * (y / hw);
+  const f = s / Math.sqrt(1 + (s / S) * (s / S)); // smooth-clamp parabola
+  return lz + (H - lz) * f;
+}
+
+const X0 = -97, X1 = 28, Y0 = -40, Y1 = 40;
+const NX = 52, NY = 38;
+const grid = [];
+for (let i = 0; i < NX; i += 1) {
+  const x = X0 + ((X1 - X0) * i) / (NX - 1);
+  const row = [];
+  for (let j = 0; j < NY; j += 1) {
+    const y = Y0 + ((Y1 - Y0) * j) / (NY - 1);
+    row.push([x, y, dishZ(x, y)]);
+  }
+  grid.push(row);
+}
+
+const bowl = Surface.Net()
+  .cage(grid)
+  .degree(3, 3)
+  .toSheet()
+  .thicken(1.2, { resolution: 160 })
+  .trimByPlane([0, 0, -1], -H); // exact level rim
+
+// ───────────────────────── 2. the rounded grip volume ─────────────────────────
+const spine = Curve.Fit(
+  [
+    [16, 0, 4.0],
+    [34, 0, 4.4],
+    [74, 0, 4.2],
+    [110, 0, 3.5],
+  ],
+  { tolerance: 0.02 },
+);
+
+const gripProfile = (width, thickness) => roundedRect(width, thickness, thickness / 2);
+
+const grip = variableSweep(
+  spine,
+  [
+    { t: 0.0, profile: gripProfile(15.0, 7.0) },
+    { t: 0.16, profile: gripProfile(16.6, 9.0) },
+    { t: 0.62, profile: gripProfile(13.6, 9.8) },
+    { t: 1.0, profile: gripProfile(16.2, 9.2) },
+  ],
+  { edgeLength: 0.65, samples: 90, up: [0, 0, 1] },
+);
+
+// ───────────────────────── 3. split into tang + scales ─────────────────────────
+const TANG_Z = 4.0; // grip equator
+const TANG_T = 3.2; // tang thickness
+const tangSlab = box(240, 70, TANG_T).translate(20, 0, TANG_Z); // flat slab at the equator
+
+// Tang = grip ∩ slab (flush to the grip outline), fused into the bowl → metal head.
+const tang = grip.intersect(tangSlab);
+const metalHead = union(bowl, tang);
+
+// Polymer scales = grip − slab, with the bolster (front) and butt (back) trimmed off
+// so the steel shows there.
+const bolsterCut = box(60, 70, 60).translate(2, 0, TANG_Z); // expose metal for x < 32
+const buttCut = box(30, 70, 60).translate(121, 0, TANG_Z); // expose metal for x > 106
+const scales = grip.subtract(tangSlab).subtract(bolsterCut).subtract(buttCut);
+
+// ───────────────────────── 4. rivets ─────────────────────────
+const rivetXs = [46, 72, 96];
+const rivets = rivetXs.map((rx) =>
+  cylinder(14, 1.7).translate(rx, 0, TANG_Z - 7), // cylinder(height, radius); base at 0, along Z
+);
+
+// ───────────────────────── 5. materials & assembly ─────────────────────────
+const steel = (shape) => shape.color('#c9d0d8').material({ roughness: 0.22, metalness: 0.86 });
+const polymer = (shape) => shape.color('#141619').material({ roughness: 0.55, metalness: 0.0 });
+
+const wholeForMeasure = union(metalHead, scales, ...rivets);
+
+verify.notEmpty('metal head (bowl + tang) is solid', metalHead);
+verify.notEmpty('polymer scales are solid', scales);
+verify.boundingBoxSize('full-tang spoon keeps its proportions', wholeForMeasure, [203, 69, 23], 16);
+verify.lessThan('mid-bowl is deeper than the neck', dishZ(-48, 0), dishZ(24, 0) - 8);
+verify.greaterThan('bowl has real spoon width', hwAt(-48) * 2, 50);
+
+return [
+  steel(metalHead),
+  polymer(scales),
+  ...rivets.map(steel),
+];

package/examples/api/surface-boundarynet-dished-bowl.forge.js

@@ -0,0 +1,63 @@
+/**
+ * Smooth closed-rim dished bowl built with ONLY the Boundary Surface primitive.
+ *
+ * This is the headline case for `Surface.BoundaryNet()`'s closed/periodic form:
+ * a dished bowl whose around-rim seam must be tangent-continuous (no G0 kink).
+ *
+ * Construction (a class-A "boundary surface" cage):
+ *  - U runs radially, rim -> center (rings of decreasing radius, dishing down).
+ *  - V runs around the rim; the first and last V columns coincide so the loop
+ *    closes in position.
+ *  - `.closedV()` welds those two ends into one smooth seam, so the surface has
+ *    NO crease where the around-rim parameterization wraps.
+ *
+ * The innermost ring is a small non-degenerate disk (not a single pole), so the
+ * floor rounds over cleanly and `.thicken()` stays watertight.
+ */
+
+scene({
+  camera: { position: [140, -150, 120], target: [0, 0, -14], fov: 32 },
+  views: {
+    iso: { position: [140, -150, 120], target: [0, 0, -14], fov: 32 },
+    top: { position: [0, 0, 230], target: [0, 0, -12], fov: 32 },
+  },
+});
+
+const RIM_RADIUS = 60;
+const DEPTH = 22; // dish depth at the floor (down -z)
+const AROUND = 48; // around-rim samples (V); seam wraps here
+const RINGS = 10; // radial rings rim -> center (U)
+const CENTER_SCALE = 0.02; // innermost ring radius as a fraction of the rim (near-closed floor, no hard pole)
+
+// Radial profile: round dished bottom. t = 0 at rim, 1 at center.
+// radius shrinks to the floor; z dips so the rim tangent rolls in and the floor
+// is flat (cosine dish: flat tangent at BOTH the rim and the floor -> no throat).
+function ringRadius(t) {
+  return RIM_RADIUS * (CENTER_SCALE + (1 - CENTER_SCALE) * (1 - t));
+}
+function ringDepth(t) {
+  return -DEPTH * 0.5 * (1 - Math.cos(Math.PI * t));
+}
+
+// Build the (RINGS x AROUND+1) cage. Each row is a ring; columns go around.
+// Column 0 and column AROUND are the SAME point so the V loop closes.
+const cage = [];
+for (let r = 0; r < RINGS; r++) {
+  const t = r / (RINGS - 1);
+  const radius = ringRadius(t);
+  const z = ringDepth(t);
+  const ring = [];
+  for (let a = 0; a <= AROUND; a++) {
+    const angle = (a / AROUND) * 2 * Math.PI; // a=0 and a=AROUND coincide
+    ring.push([radius * Math.cos(angle), radius * Math.sin(angle), z]);
+  }
+  cage.push(ring);
+}
+
+// The Boundary Surface: Gordon fill of the cage, with the around-rim seam welded
+// into a tangent-continuous loop via the closed/periodic form.
+const bowl = Surface.BoundaryNet().cage(cage).degree(3, 3).closedV().thicken(1.2);
+
+bowl.color('#b9c4cc');
+
+return bowl;