@metamesh/modeling 0.18.0 → 0.20.0

package/dist/model/generation.js

@@ -1,5 +1,5 @@
 import { captureDiagnosticPath } from "./diagnostic-path.js";
-/** A user-correctable assertion failure. Successful computation caches never retain failures. */
+/** A user-correctable assertion failure. Successful memo caches never retain failures. */
 export class GenerationError extends Error {
     /** Issues reached in normal JavaScript order, ending with the first failed assertion. */
     diagnostics;
@@ -16,7 +16,9 @@ export class GenerationError extends Error {
 /**
  * Defines a typed model without executing it. Parameters are an object map of capturable data;
  * runtime capture rejects arrays at the root, ordinary class instances, mutable buffers, and functions.
- * Supply live capabilities through services. Use `computed` only for work worth reusing.
+ * Supply live capabilities through services. Use `memo` only for work worth reusing.
+ *
+ * @param callback - Synchronous callback returning one part or a readonly part array.
  *
  * @example A simple model
  * ```ts

package/dist/model/immutable-generation-data.js

@@ -2,7 +2,7 @@ import { GeometryError } from "../geometry/errors.js";
 import { adoptImmutableBuffer, immutableBuffer, immutableBufferView, isImmutableBuffer, } from "../geometry/immutable-buffer.js";
 import { isImmutableMathValue } from "../geometry/math/immutable-value.js";
 import { geometryRecipe, isGeometryRecipe } from "./geometry-recipes.js";
-const mutableBufferMessage = "Generation data cannot contain mutable typed arrays or raw ArrayBuffers. Use immutableBuffer(array) or mesh.immutable(mesh) before caching them or declaring dependencies.";
+const mutableBufferMessage = "Generation data cannot contain mutable typed arrays or raw ArrayBuffers. Use immutableBuffer(array) or mesh.immutable(mesh) before passing them to memo or capturing generation data.";
 const capturedMetadata = new WeakMap();
 const immutableInputs = new WeakSet();
 const noChildren = Object.freeze([]);
@@ -51,7 +51,7 @@ export function* generationDataEntries(value, captureAccessors = false) {
             continue;
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (!captureAccessors && !("value" in descriptor))
-            throw new GeometryError("INVALID_ARGUMENT", "Generation data requires own data fields, not accessors.", { operation: "computed" });
+            throw new GeometryError("INVALID_ARGUMENT", "Generation data requires own data fields, not accessors.", { operation: "memo" });
         if (typeof key !== "string" || !descriptor.enumerable)
             throw new TypeError("Generation data requires enumerable string-keyed fields.");
         yield [
@@ -221,13 +221,15 @@ function mathValueData(value) {
         throw new TypeError("Immutable math values must expose canonical data through toData().");
     return Reflect.apply(method, value, []);
 }
-function captureValue(value, mode, readerAllowed = () => false, validated) {
+// Data and recipe modes copy containers; dependency mode validates them in place for memo identity.
+// Recipe mode also captures accessor values and numeric buffers while retaining deferred callbacks.
+function captureValue(value, mode, validated) {
     const recipeInputs = mode === "recipe";
     const seen = new Map();
     const metadata = new Map();
     const copy = (input) => {
-        if (typeof input === "function" && !recipeInputs && !readerAllowed(input))
-            throw new GeometryError("INVALID_ARGUMENT", "Computed values and dependencies cannot contain arbitrary function closures.", { operation: "computed" });
+        if (typeof input === "function" && !recipeInputs)
+            throw new GeometryError("INVALID_ARGUMENT", "Memo arguments and results cannot contain arbitrary function closures.", { operation: "memo" });
         if (typeof input !== "object" ||
             input === null ||
             isGeometryRecipe(input) ||
@@ -261,7 +263,7 @@ function captureValue(value, mode, readerAllowed = () => false, validated) {
         };
         if (mode === "dependency") {
             if (!Object.isFrozen(input))
-                throw new GeometryError("INVALID_ARGUMENT", "Computed dependencies require deeply immutable objects and arrays. Read params inside the callback, use a computed value, or depend on individual scalar values.", { operation: "computed" });
+                throw new GeometryError("INVALID_ARGUMENT", "Memo arguments require deeply immutable objects and arrays. Pass params directly, use a memo result, or pass individual scalar values.", { operation: "memo" });
             seen.set(input, input);
             for (const [key, field] of entries) {
                 copy(field);
@@ -297,22 +299,22 @@ function captureValue(value, mode, readerAllowed = () => false, validated) {
         capturedMetadata.set(value, entry);
     return result;
 }
-/** Validates while capturing immutable data; only explicitly allowed session readers may be functions. */
-export function captureGenerationValue(value, readerAllowed) {
-    return captureValue(value, "data", readerAllowed);
+/** Captures immutable ordinary generation data; arbitrary function closures are invalid. */
+export function captureGenerationValue(value) {
+    return captureValue(value, "data");
 }
 /** Snapshots the list, preserving immutable entry identities and validating each object only once. */
-export function captureGenerationDependencies(values, readerAllowed, validated) {
+export function captureGenerationArguments(values, validated) {
     const inputs = [];
     for (const [key, value] of generationDataEntries(values)) {
         if (key !== String(inputs.length))
-            throw new TypeError("Computed dependencies must be a dense array without extra fields.");
+            throw new TypeError("Memo arguments must be a dense array without extra fields.");
         inputs.push(value);
     }
     if (inputs.length !== values.length)
-        throw new TypeError("Computed dependencies must be a dense array without extra fields.");
+        throw new TypeError("Memo arguments must be a dense array without extra fields.");
     const result = Object.freeze(inputs);
-    captureValue(result, "dependency", readerAllowed, validated);
+    captureValue(result, "dependency", validated);
     return result;
 }
 /** Captures ordinary inputs once, including accessor values and mutable numeric arrays. */

package/dist/model/join.js

@@ -0,0 +1 @@
+export {};

package/dist/model/operations.js

@@ -10,6 +10,29 @@ import { invokeModelOperation as invoke } from "./operation-dispatch.js";
 export function box(options) {
     return invoke("box", [options]);
 }
+/**
+ * Fuses two positioned solids with a dimensioned transition at the feature's source datum.
+ *
+ * Requires a local straight feature collar and a continuous support patch single-valued along
+ * that collar's axis. Angled and curved sampled supports are admitted when those proofs hold.
+ * Width is a parallel-edge offset; height is axial rise above local contact, both in millimetres.
+ * The default smooth profile matches tangents; kind "straight" gives a linear bevel profile.
+ * Neither operand moves, loses material, or changes sampling. The result has no inherited anchors.
+ * This operation promises neither a circular radius, a constant bevel angle, nor global curvature continuity.
+ *
+ * @param base - Support solid in shared modeling coordinates.
+ * @param feature - Positioned feature that owns the source datum.
+ *
+ * @example Join a mounting boss
+ * ```ts
+ * const base = box({ size: [50, 40, 6] });
+ * const feature = cylinder({ diameter: 12, height: 14, center: false }).translate([0, 0, 2]);
+ * base.join(feature, { source: "bottom", transition: { width: 2, height: 3 } });
+ * ```
+ */
+export function join(base, feature, options) {
+    return invoke("join", [base, feature, options]);
+}
 /**
  * +Z cylinder or frustum. Face sizing compensates polygon faceting.
  *
@@ -27,28 +50,92 @@ export function cylinder(options) {
     return invoke("cylinder", [options]);
 }
 /**
- * Declares a +Z hole or blind-pocket cutter with explicit end overrun in millimetres.
+ * Declares a +Z hole or blind-pocket cutter with independent opening treatments.
  *
  * @remarks
- * Choose exactly one circular diameter or existing Section. A 45-degree entry chamfer
- * supports one strictly convex contour without holes; plain profiles may have any topology.
- * Circular entries retain nominal frustum radii; profile entries offset the supplied polygon edges.
- * Circular head recesses are mutually exclusive with entryChamfer. Both overrun ends default
- * to zero, so the nominal bottom remains at Z=0 and blind pocket floors are preserved.
+ * Choose exactly one circular diameter or existing Section. Finished profiles require one
+ * strictly convex contour without holes; plain profiles may have any topology. Opening treatments
+ * widen the mouth while retaining a positive nominal throat. Circular openings also admit
+ * counterbores and countersinks. An omitted opening leaves that end unchanged.
+ * Overrun extends each terminal cross section outside Z=0..height; both ends default to zero,
+ * preserving blind-pocket floors. It is independent of manufacturing clearance.
  * Existing Section samples are authoritative; limits and unspecified circular sampling belong
  * to the evaluating host.
  *
- * @example A blind hex pocket with an open top
+ * @example Amber cutter · Blue blind hex pocket
  * ```ts
- * holeCutter({
- *   profile: regularPolygon({ sides: 6, radius: 3.5, sizing: "face", rotation: 30 }),
- *   height: 12, entryChamfer: 0.5, overrun: { top: 0.05 },
+ * import { box, generate, holeCutter, regularPolygon } from "@metamesh/modeling";
+ * import { transform3 } from "@metamesh/modeling/geometry";
+ *
+ * const cutter = holeCutter({
+ *   profile: regularPolygon({ sides: 6, radius: 5, sizing: "face", rotation: 30 }),
+ *   height: 5,
+ *   openings: { top: { kind: "chamfer", distance: 1.5 } },
+ *   overrun: { top: 0.05 },
  * });
+ * // A 3 mm floor remains beneath the pocket. Display the cutter separately on the left.
+ * const stock = box({ size: [22, 20, 8] }).translate([0, 0, 4]);
+ * const result = stock.subtract(cutter.translate([0, 0, 3]));
+ * export default generate(({ part }) => [
+ *   part("cutter", { geometry: cutter, color: "#f6ad55", transform: transform3().translate([-12, -12, 0]) }),
+ *   part("result", { geometry: result, color: "#4f83a6", transform: transform3().translate([12, 12, 0]) }),
+ * ]);
  * ```
  */
 export function holeCutter(options) {
     return invoke("holeCutter", [options]);
 }
+/**
+ * Creates a cutter for one straight convex edge along +Z, with its sharp reference at XY=0.
+ * Position it explicitly before subtraction; the included material angle defaults to 90 degrees.
+ *
+ * @example Amber cutter · Blue rounded edge
+ * ```ts
+ * import { box, edgeCutter, generate } from "@metamesh/modeling";
+ * import { transform3 } from "@metamesh/modeling/geometry";
+ *
+ * const cutter = edgeCutter({ length: 18, treatment: { kind: "round", radius: 6 }, excess: 0 });
+ * const result = box({ size: 18, center: false }).subtract(cutter);
+ * // Turn the concave mask and convex result toward the viewer independently.
+ * export default generate(({ part }) => [
+ *   part("cutter", { geometry: cutter.translate([-3, -3, 0]).rotate([0, 0, -90]), color: "#f6ad55", transform: transform3().translate([-11, -11, 0]) }),
+ *   part("result", { geometry: result.translate([-9, -9, 0]).rotate([0, 0, 90]), color: "#4f83a6", transform: transform3().translate([11, 11, 0]) }),
+ * ]);
+ * ```
+ */
+export function edgeCutter(options) {
+    return invoke("edgeCutter", [options]);
+}
+/**
+ * Creates a round or chamfer cutter at the origin for three perpendicular positive-axis faces.
+ * Complements matching edge cutters; construction, placement, and subtraction remain explicit.
+ *
+ * @example Amber corner cutter · Blue three-edge junction
+ * ```ts
+ * import { box, cornerCutter, edgeCutter, generate } from "@metamesh/modeling";
+ * import { transform3 } from "@metamesh/modeling/geometry";
+ *
+ * const treatment = { kind: "round", radius: 5 } as const;
+ * const cutter = cornerCutter({ treatment, excess: 0 });
+ * const edge = edgeCutter({ length: 12, treatment, excess: 0 });
+ * const result = box({ size: 12, center: false }).subtract([
+ *   edge,
+ *   edge.rotate([0, -90, 0]).translate([12, 0, 0]),
+ *   edge.rotate([90, 0, 0]).translate([0, 12, 0]),
+ *   cutter,
+ * ]);
+ * // Display the concave mask and completed upper junction from opposite sides.
+ * const view = (shape: typeof result, center: number, height: number) =>
+ *   shape.translate([-center, -center, 0]).mirror([0, 0, 1]).translate([0, 0, height]).rotate([0, 0, 90]);
+ * export default generate(({ part }) => [
+ *   part("cutter", { geometry: cutter.translate([-2.5, -2.5, 0]).rotate([0, 0, -90]), color: "#f6ad55", transform: transform3().translate([-8, -8, 0]) }),
+ *   part("result", { geometry: view(result, 6, 12), color: "#4f83a6", transform: transform3().translate([8, 8, 0]) }),
+ * ]);
+ * ```
+ */
+export function cornerCutter(options) {
+    return invoke("cornerCutter", [options]);
+}
 /**
  * Hollow +Z tube.
  *
@@ -61,7 +148,8 @@ export function tube(options) {
     return invoke("tube", [options]);
 }
 /**
- * Origin-centered sphere.
+ * Origin-centered sphere with adaptive sampling that bounds spherical triangle error.
+ * Explicit segment requests select octahedral refinement and round up to a multiple of four.
  *
  * @example Sphere
  * ```ts
@@ -91,13 +179,15 @@ export function intersect(shapes) {
 export function hull(options) {
     return invoke("hull", [options]);
 }
-/** Three-dimensional Minkowski sum. */
+/** Declares the three-dimensional Minkowski sum of two Solid recipes. */
 export function minkowskiSum(a, b) {
     return invoke("minkowskiSum", [a, b]);
 }
 /**
  * Imports a bounded closed indexed mesh.
  *
+ * @param mesh - Closed, oriented mesh in millimetres; ownership stays with the caller.
+ *
  * @example Mesh import
  * ```ts
  * import { solidFromMesh } from "@metamesh/modeling";
@@ -117,6 +207,8 @@ export function solidFromMesh(mesh) {
  * Closing edges are implicit. Compound contours use nonzero fill unless selected otherwise.
  * Explicit topology must be simple and disjoint; compound winding may resolve overlaps.
  *
+ * @param input - XY outline in millimetres, or explicit or compound topology.
+ *
  * @example Extrude a triangular plate
  * ```ts
  * polygon([[0, 0], [20, 0], [10, 12]]).extrude({ height: 3 });
@@ -126,12 +218,14 @@ export function polygon(input) {
     return invoke("polygon", [input]);
 }
 /**
- * Creates a centered-width native Section along a sampled XY path.
+ * Declares a centered-width Section recipe along a sampled XY path.
  *
- * Shares caps, joins and physical sampling with Geometry's strokeRegionData. Native union
- * resolves overlapping stroke primitives. Session resolution and resource ceilings apply;
+ * Shares caps, joins and physical sampling with Geometry's strokeRegionData. During evaluation,
+ * union resolves overlapping stroke primitives. Session resolution and resource ceilings apply;
  * closed paths omit the duplicated seam. Returns an immutable deferred recipe.
  *
+ * @param path - XY path in millimetres.
+ *
  * @example Extrude a rounded track
  * ```ts
  * stroke([[0, 0], [20, 0], [20, 10]], { width: 3, join: "round", cap: "round" }).extrude({ height: 2 });
@@ -148,7 +242,7 @@ export function stroke(path, options) {
  *
  * @example Round the corners
  * ```ts
- * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } }).extrude({ height: 3 });
  * ```
  */
 export function rectangle(options) {
@@ -159,7 +253,7 @@ export function rectangle(options) {
  *
  * @example Size to polygon faces
  * ```ts
- * circle({ diameter: 12, sizing: "face" });
+ * circle({ diameter: 12, sizing: "face" }).extrude({ height: 3 });
  * ```
  */
 export function circle(options) {
@@ -170,7 +264,7 @@ export function circle(options) {
  *
  * @example Ellipse by full dimensions
  * ```ts
- * ellipse({ size: [30, 20] });
+ * ellipse({ size: [30, 20] }).extrude({ height: 3 });
  * ```
  */
 export function ellipse(options) {
@@ -181,7 +275,7 @@ export function ellipse(options) {
  *
  * @example Hexagonal section
  * ```ts
- * regularPolygon({ radius: 10, sides: 6, sizing: "face" });
+ * regularPolygon({ radius: 10, sides: 6, sizing: "face" }).extrude({ height: 3 });
  * ```
  */
 export function regularPolygon(options) {
@@ -192,7 +286,7 @@ export function regularPolygon(options) {
  *
  * @example Five-point section
  * ```ts
- * star({ outerRadius: 12, innerRadius: 6, points: 5 });
+ * star({ outerRadius: 12, innerRadius: 6, points: 5 }).extrude({ height: 3 });
  * ```
  */
 export function star(options) {
@@ -202,10 +296,12 @@ export function star(options) {
  * Extrudes a filled Section or explicit corresponding contours along +Z with degree twist and top scaling.
  * Use `section.extrude(options)` in fluent sequences, or this function for generic profile inputs.
  *
+ * @param shape - Filled XY profile in millimetres.
+ *
  * @example Extrude
  * ```ts
- * import { extrude, matchProfiles } from "@metamesh/modeling";
- * import { rectangleProfile } from "@metamesh/modeling/geometry";
+ * import { extrude } from "@metamesh/modeling";
+ * import { matchProfiles, rectangleProfile } from "@metamesh/modeling/geometry";
  *
  * const [profile] = matchProfiles([rectangleProfile({ size: [30, 20] })]);
  * extrude(profile!, { height: 8 });
@@ -218,10 +314,12 @@ export function extrude(shape, options) {
  * Revolves a filled Section or explicit corresponding radial/Z contours around +Z, with caps for partial sweeps.
  * Use `section.revolve(options)` in fluent sequences, or this function for generic profile inputs.
  *
+ * @param shape - Profile coordinates are [radius, Z] in millimetres.
+ *
  * @example Revolve
  * ```ts
- * import { matchProfiles, revolve } from "@metamesh/modeling";
- * import { rectangleProfile } from "@metamesh/modeling/geometry";
+ * import { revolve } from "@metamesh/modeling";
+ * import { matchProfiles, rectangleProfile } from "@metamesh/modeling/geometry";
  *
  * // Contour coordinates are [radius, Z].
  * const [profile] = matchProfiles([rectangleProfile({ size: [4, 16], center: false })]);
@@ -234,30 +332,8 @@ export function revolve(shape, options) {
 export function loft(stations, options) {
     return invoke("loft", [stations, options]);
 }
-/**
- * Matches a profile family using operation settings over host resolution and limits.
- * Requires active synchronous model execution. Use Geometry's matchProfiles for standalone preparation.
- */
-export function matchProfiles(profiles, options) {
-    return invoke("matchProfiles", [profiles, options]);
-}
-/**
- * Sweeps a filled Section or explicit corresponding contours using the selected frame policy.
- * Use `section.sweep(path, options)` in fluent sequences, or this function for generic profile inputs.
- *
- * @example Sweep
- * ```ts
- * import { matchProfiles, sweep } from "@metamesh/modeling";
- * import { rectangleProfile } from "@metamesh/modeling/geometry";
- *
- * const [profile] = matchProfiles([rectangleProfile({ size: [6, 3] })]);
- * sweep(profile!, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
- *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
- * });
- * ```
- */
-export function sweep(shape, path, options) {
-    return invoke("sweep", [shape, path, options]);
+export function sweep(shape, route, options = {}) {
+    return invoke("sweep", [shape, route, options]);
 }
 /**
  * Bounded positive-inside implicit field constructor.
@@ -295,7 +371,7 @@ export function gridPattern(...args) {
 export function pathPattern(...args) {
     return invoke("pathPattern", args);
 }
-/** Helical ridge mesh construction. */
+/** Declares a helical ridge Solid recipe along +Z, with lengths in millimetres. */
 export function threadRidge(options) {
     return invoke("threadRidge", [options]);
 }
@@ -309,7 +385,6 @@ export function threadRidge(options) {
  * Each half's `chamfer` bevels its barrel outer rims and all web edges. Consumers own plates, screw holes,
  * pin retention, fit policy, and part placement. Added mounting material must preserve the bores.
  * No opening range or collision freedom is implied for arbitrary caller attachments.
- * Compiled Generator packages using this operation require runtime 10.0.0 or newer in major 10.
  *
  * @example Integral-pin hinge with two mounting webs
  * ```ts
@@ -330,7 +405,7 @@ export function knuckleHinge(options) {
  * @example Threaded rod
  * ```ts
  * import { threadedRod } from "@metamesh/modeling";
- * import { threadProfile } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry/mechanical";
  *
  * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
@@ -342,14 +417,22 @@ export function threadedRod(options) {
 /**
  * Compensated internal threaded cutter.
  *
- * @example Internal thread
+ * @example Amber thread cutter · Blue cutaway result
  * ```ts
- * import { cylinder, internalThreadCutter } from "@metamesh/modeling";
- * import { threadProfile } from "@metamesh/modeling/geometry";
+ * import { box, cylinder, generate, internalThreadCutter } from "@metamesh/modeling";
+ * import { transform3 } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry/mechanical";
+ *
  * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * const body = cylinder({ diameter: 20, height: 12, center: false });
  * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
- * body.subtract([cutter]);
+ * // Remove the front quarter of the stock to expose the actual internal thread.
+ * const cutaway = box({ size: [11, 11, 14], center: false }).translate([0, -11, -1]);
+ * const result = body.subtract([cutter, cutaway]);
+ * export default generate(({ part }) => [
+ *   part("cutter", { geometry: cutter, color: "#f6ad55", transform: transform3().translate([-12, -12, 0]) }),
+ *   part("result", { geometry: result, color: "#4f83a6", transform: transform3().translate([12, 12, 0]) }),
+ * ]);
  * ```
  */
 export function internalThreadCutter(options) {
@@ -361,7 +444,7 @@ export function internalThreadCutter(options) {
  * @example Threaded nut
  * ```ts
  * import { threadedNut } from "@metamesh/modeling";
- * import { threadProfile } from "@metamesh/modeling/geometry";
+ * import { threadProfile } from "@metamesh/modeling/geometry/mechanical";
  *
  * const profile = threadProfile({ kind: "triangular", pitch: 1.75 });
  * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
@@ -370,47 +453,16 @@ export function internalThreadCutter(options) {
 export function threadedNut(options) {
     return invoke("threadedNut", [options]);
 }
-/**
- * Checks compensated rod dimensions and conservative mesh estimates against host output limits.
- *
- * Requires active synchronous model execution and uses its resolution and limits. Returns selected
- * sampling and conservative row/triangle estimates without mesh buffers or native objects.
- * Mesh validity, native construction, and aggregate output limits are checked later.
- *
- * @see {@link threadedRod}
- */
-export function preflightThreadedRod(options) {
-    return invoke("preflightThreadedRod", [options]);
-}
-/**
- * Checks compensated cutter dimensions and conservative mesh estimates against host output limits.
- *
- * Requires active synchronous model execution and uses its resolution and limits. Estimates include
- * the one-pitch extension beyond each requested face, without mesh buffers or native objects.
- * Mesh validity, native construction, and aggregate output limits are checked later.
- *
- * @see {@link internalThreadCutter}
- */
-export function preflightInternalThreadCutter(options) {
-    return invoke("preflightInternalThreadCutter", [options]);
-}
-/**
- * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
- *
- * Requires active synchronous model execution and uses its resolution and limits, without mesh
- * buffers or native objects. Returned thread estimates cover the cutter, excluding the body and
- * Boolean result. Mesh validity, native construction, and aggregate output limits are checked later.
- *
- * @see {@link threadedNut}
- */
-export function preflightThreadedNut(options) {
-    return invoke("preflightThreadedNut", [options]);
-}
 /**
  * Consumes a previously prepared layout; never shapes or fetches a font.
  *
+ * @param layout - Prepared millimetre outlines; create the layout before generation.
+ *
  * @example Use a prepared text layout
  * ```ts
+ * import { textSection } from "@metamesh/modeling";
+ * import type { VectorTextLayout } from "@metamesh/modeling/geometry";
+ *
  * // Prepare the exact font and layout before entering build.
  * function labelSection(layout: VectorTextLayout) {
  *   return textSection(layout);
@@ -423,12 +475,14 @@ export function textSection(layout, options) {
 /**
  * Imports bounded painted SVG document geometry.
  *
+ * @param svg - Complete SVG XML, at most 256 KiB of UTF-8.
+ *
  * @example Import a physical SVG rectangle
  * ```ts
  * svgSection(
  *   '<svg xmlns="http://www.w3.org/2000/svg" width="30mm" height="20mm" viewBox="0 0 30 20"><rect width="30" height="20"/></svg>',
  *   { origin: "center" },
- * );
+ * ).extrude({ height: 3 });
  * ```
  */
 export function svgSection(svg, options) {
@@ -437,9 +491,11 @@ export function svgSection(svg, options) {
 /**
  * Imports bounded filled SVG path data.
  *
+ * @param path - SVG path data, at most 1 MiB of UTF-8; omit the XML wrapper.
+ *
  * @example Fill an SVG path in millimetres
  * ```ts
- * svgPathSection("M0 0H20V12H0Z", { origin: "center", scale: 1 });
+ * svgPathSection("M0 0H20V12H0Z", { origin: "center", scale: 1 }).extrude({ height: 3 });
  * ```
  */
 export function svgPathSection(path, options) {

package/dist/model/recipe-declaration.js

@@ -1,8 +1,8 @@
 import { GeometryError } from "../geometry/errors.js";
+import { defaultModelingLimits } from "../geometry/limits.js";
 import { knuckleHingeAxis } from "../geometry/mechanical/knuckle-hinge.js";
-import { defaultModelingLimits } from "../geometry/model-limits.js";
 import { gridPatternPlan, linearPatternPlan, pathPatternPlan, radialPatternPlan, } from "../geometry/patterns/placements.js";
-import { restrictTransform3 } from "../geometry/transform2.js";
+import { restrictTransform3 } from "../geometry/transforms/dimensions.js";
 import { geometryRecipe, recordGeometryRecipe, } from "./geometry-recipes.js";
 import { captureRecipeInputs } from "./immutable-generation-data.js";
 // Every public operation must explicitly choose its realization and result behavior.
@@ -11,12 +11,15 @@ const operationBehaviors = {
     box: "solid",
     cylinder: "solid",
     holeCutter: "solid",
+    edgeCutter: "solid",
+    cornerCutter: "solid",
     tube: "solid",
     sphere: "solid",
     torus: "solid",
     heightfield: "solid",
     implicit: "solid",
     extrude: "solid",
+    join: "solid",
     revolve: "solid",
     loft: "solid",
     sweep: "solid",
@@ -61,10 +64,6 @@ const operationBehaviors = {
     distance: "observation",
     castSegment: "observation",
     anchor: "observation",
-    matchProfiles: "observation",
-    preflightThreadedRod: "observation",
-    preflightInternalThreadCutter: "observation",
-    preflightThreadedNut: "observation",
     split: "split",
     splitByPlane: "split",
     components: "components",
@@ -84,7 +83,7 @@ export function createRecipeContext(resolution, declaration) {
     ])));
 }
 /** Captures and validates inputs before deciding whether an operation needs native geometry now. */
-export function declareRecipeOperation(operation, resolution, supplied, declaration) {
+function declareRecipeOperation(operation, resolution, supplied, declaration) {
     declaration.assertActive?.();
     const behavior = operationBehaviors[operation];
     if (behavior === "observation" || behavior === "components")

package/dist/model/shape-handles.js

@@ -43,6 +43,7 @@ const common = {
 };
 const solidPrototype = prototype({
     ...common,
+    join: forward("join"),
     toMesh: forward("toMesh"),
     attach: forward("attach"),
     withTolerance: forward("withTolerance"),

package/dist/text/index.js

@@ -10,6 +10,7 @@ function serializeVectorText({ paths, metrics }) {
     const bounds = metrics.bounds;
     if (bounds === null || paths.length === 0)
         throw new GeometryError("DEGENERATE_GEOMETRY", "The selected font produced no visible glyph outlines.", { operation: "VectorFont.toSvg" });
+    // Text uses Y-up coordinates; SVG's viewport uses Y-down coordinates.
     const d = paths
         .map((path) => new SVGPathData(path).transform(SVGPathDataTransformer.MATRIX(1, 0, 0, -1, 0, 0)).encode())
         .join(" ");
@@ -24,6 +25,8 @@ function serializeVectorText({ paths, metrics }) {
  * Parses bounded font bytes using optional fontkit and WOFF2 peers; no font fetching occurs here.
  * Argument and resource failures use GeometryError; parser and decoder exceptions propagate unchanged.
  *
+ * @param bytes - Non-empty font bytes, at most 16 MiB; copied before parsing.
+ *
  * @example Prepare a label before building geometry
  * ```ts
  * async function prepareLabel(fontBytes: Uint8Array) {

package/dist/text/vector-text-layout.js

@@ -251,6 +251,7 @@ function buildLayout(font, fontMetrics, lines, controls) {
                     const clockwise = direction === "clockwise";
                     if (clockwise ? radius + bounds.minY <= 0 : radius - bounds.maxY <= 0)
                         fail("Arc glyph outlines cross the circle's center axis. Increase the radius or reduce text size.");
+                    // Convert baseline arc length to an angle, then rotate the intact glyph group onto its tangent.
                     const angleRadians = (centerAngle * Math.PI) / 180 + ((clockwise ? -1 : 1) * groupCenter) / radius;
                     const rotationRadians = angleRadians + (clockwise ? -Math.PI / 2 : Math.PI / 2);
                     const cosine = Math.cos(rotationRadians);