@metamesh/modeling 0.6.0 → 0.7.0

package/dist/api/index.d.ts

@@ -32,7 +32,9 @@ export declare interface Anchor3 {
 /** Host-bound attach operation. Valid only during a synchronous build. */
 export declare const attach: ModelingContext["attach"];
 
-/** Degree-based anchor attachment controls for a scoped solid. */
+/**
+ * Degree-based anchor attachment controls for a scoped solid.
+ */
 export declare interface AttachOptions {
     /** Align outward directions face-to-face (`opposed`) or in parallel (`same`). */
     readonly alignment?: "opposed" | "same";
@@ -56,7 +58,9 @@ export declare type BoxEdgeSelection = BoxEdge | "top" | "bottom" | "vertical";
 /** Independent treatments for disjoint named edge selections; overlapping selections fail. */
 export declare type BoxEdgeTreatments = Readonly<Partial<Record<BoxEdgeSelection, EdgeTreatment>>>;
 
-/** Dimensions, placement, and uniform or independently selected finishing for an axis-aligned box. */
+/**
+ * Dimensions, placement, and uniform or independently selected finishing for an axis-aligned box.
+ */
 export declare interface BoxOptions extends PrimitivePlacement {
     /** Explicit sampling ceilings for edge treatments, bounded by the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -94,7 +98,9 @@ declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
     readonly pressureFlankSide?: ButtressPressureFlankSide;
 }
 
-/** A planar edge or corner chamfer with equal or independent surface setbacks. */
+/**
+ * A planar edge or corner chamfer with equal or independent surface setbacks.
+ */
 export declare interface ChamferedEdgeTreatment {
     /** Selects a straight bevel between adjoining surfaces. */
     readonly kind: "chamfer";
@@ -105,7 +111,9 @@ export declare interface ChamferedEdgeTreatment {
 /** Host-bound circle operation. Valid only during a synchronous build. */
 export declare const circle: ModelingContext["circle"];
 
-/** Circular profile dimensions with exactly one radius or diameter and explicit sampling. */
+/**
+ * Circular profile dimensions with exactly one radius or diameter and explicit sampling.
+ */
 export declare type CircleLoopOptions = CircularPrimitiveOptions & RadialSizingOptions & ({
     /** Positive nominal radius in millimetres; mutually exclusive with diameter. */
     readonly radius: number;
@@ -118,10 +126,14 @@ export declare type CircleLoopOptions = CircularPrimitiveOptions & RadialSizingO
     readonly radius?: never;
 });
 
-/** Circular dimensions with exactly one nominal radius or diameter. */
+/**
+ * Circular dimensions with exactly one nominal radius or diameter.
+ */
 export declare type CircleOptions = CircleLoopOptions & PrimitivePlacement;
 
-/** Tessellation controls shared by circular primitives across Geometry entry points. */
+/**
+ * Tessellation controls shared by circular primitives across Geometry entry points.
+ */
 export declare interface CircularPrimitiveOptions {
     /** Explicit sampling ceilings; bound modeling operations may only lower the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -188,7 +200,9 @@ declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
 /** Host-bound cylinder operation. Valid only during a synchronous build. */
 export declare const cylinder: ModelingContext["cylinder"];
 
-/** Dimensions, placement, independent end finishing, and tessellation for a Z-axis cylinder or frustum. */
+/**
+ * Dimensions, placement, independent end finishing, and tessellation for a Z-axis cylinder or frustum.
+ */
 export declare type CylinderOptions = CircularPrimitiveOptions & RadialSizingOptions & PrimitivePlacement & {
     /**
      * Centers the solid on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
@@ -211,13 +225,17 @@ export declare type CylinderOptions = CircularPrimitiveOptions & RadialSizingOpt
     readonly radius?: never;
 });
 
-/** Uniform finishing vocabulary shared by applicable solid edges and profile corners. */
+/**
+ * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
+ */
 export declare type EdgeTreatment = ChamferedEdgeTreatment | RoundedEdgeTreatment | SmoothEdgeTreatment | ProfiledEdgeTreatment;
 
 /** Host-bound ellipse operation. Valid only during a synchronous build. */
 export declare const ellipse: ModelingContext["ellipse"];
 
-/** Ellipse dimensions with exactly one XY radii or full-size tuple and explicit sampling. */
+/**
+ * Ellipse dimensions with exactly one XY radii or full-size tuple and explicit sampling.
+ */
 export declare type EllipseLoopOptions = CircularPrimitiveOptions & ({
     /** Positive XY radii in millimetres; mutually exclusive with size. */
     readonly radius: Vec2;
@@ -230,10 +248,14 @@ export declare type EllipseLoopOptions = CircularPrimitiveOptions & ({
     readonly radius?: never;
 });
 
-/** Ellipse dimensions in local XY, with exactly one radii or full-size tuple. */
+/**
+ * Ellipse dimensions in local XY, with exactly one radii or full-size tuple.
+ */
 export declare type EllipseOptions = EllipseLoopOptions & PrimitivePlacement;
 
-/** Independent inward finishing on primitive or straight convex extrusion ends. */
+/**
+ * Independent inward finishing on primitive or straight convex extrusion ends.
+ */
 export declare interface EndTreatments {
     /** Bottom cap and adjoining side; omitted leaves the end untreated. */
     readonly bottom?: EdgeTreatment;
@@ -244,7 +266,9 @@ export declare interface EndTreatments {
 /** Host-bound extrude operation. Valid only during a synchronous build. */
 export declare const extrude: ModelingContext["extrude"];
 
-/** Dimensions and sampling shared by native and pure +Z extrusion. */
+/**
+ * Dimensions and sampling shared by native and pure +Z extrusion.
+ */
 export declare interface ExtrudeOptions extends ExtrusionSamplingOptions {
     /** Positive extrusion height in millimetres. */
     readonly height: number;
@@ -318,7 +342,9 @@ export declare interface Frame3 {
 /** Host-bound fromRegion operation. Valid only during a synchronous build. */
 export declare const fromRegion: ModelingContext["fromRegion"];
 
-/** Tessellation policy for sampled geometry measured in millimetres. */
+/**
+ * Tessellation policy for sampled geometry measured in millimetres.
+ */
 export declare interface GeometryResolution {
     /** Optional exact full-circle segment count, of at least three, bounded by the selected circular ceiling. */
     readonly circularSegments?: number;
@@ -357,7 +383,9 @@ export declare interface GeometryToleranceOptions {
 /** Host-bound gridPattern operation. Valid only during a synchronous build. */
 export declare const gridPattern: ModelingContext["gridPattern"];
 
-/** XY or XYZ grid with X varying fastest. The first item starts at the local origin. */
+/**
+ * XY or XYZ grid with X varying fastest. The first item starts at the local origin.
+ */
 export declare type GridPatternOptions = {
     /** Center the complete distribution around its local origin; defaults to false. */
     readonly center?: boolean;
@@ -487,7 +515,9 @@ export declare const intersect: ModelingContext["intersect"];
 /** Host-bound linearPattern operation. Valid only during a synchronous build. */
 export declare const linearPattern: ModelingContext["linearPattern"];
 
-/** Equal linear intervals determined by exactly two of count, spacing and total length. */
+/**
+ * Equal linear intervals determined by exactly two of count, spacing and total length.
+ */
 export declare type LinearPatternOptions = {
     /** Direction of repetition; magnitude is ignored. Defaults to +X. */
     readonly direction?: Vec3;
@@ -520,7 +550,9 @@ export declare const loft: ModelingContext["loft"];
 /** Deterministic ordered edge subdivision or bounded geometric vertex association. */
 export declare type LoftCorrespondence = "direct" | "reindex" | "fast-distance" | "distance";
 
-/** Shared controls for native and pure lofts. Point data and arbitrary Sections require explicit correspondence. */
+/**
+ * Shared controls for native and pure lofts. Point data and arbitrary Sections require explicit correspondence.
+ */
 export declare interface LoftOptions {
     /** One method or one per consecutive station gap. Omitted preserves known landmarks, including circle/ellipse-to-rectangle corners, or maps other unlike primitive seams directly. */
     readonly correspondence?: LoftCorrespondence | readonly LoftCorrespondence[];
@@ -536,7 +568,9 @@ export declare interface LoftOptions {
     readonly limits?: Partial<ModelingLimits>;
 }
 
-/** A horizontal XY station height, or an explicit right-handed spatial frame, never both. */
+/**
+ * A horizontal XY station height, or an explicit right-handed spatial frame, never both.
+ */
 export declare type LoftPlacement = {
     /** Horizontal XY station height in millimetres. */
     readonly z: number;
@@ -549,7 +583,9 @@ export declare type LoftPlacement = {
     readonly z?: never;
 };
 
-/** A Section or point loop at an explicit height or frame. */
+/**
+ * A Section or point loop at an explicit height or frame.
+ */
 export declare type LoftStation = LoftPlacement & {
     /** Same-build filled Section or ordered XY boundary point data. */
     readonly profile: Section | Loop2;
@@ -574,7 +610,9 @@ export declare interface MatchProfilesOptions {
     readonly limits?: Partial<GeometrySamplingLimits>;
 }
 
-/** Axis-aligned bounds of a non-empty triangle mesh. */
+/**
+ * Axis-aligned bounds of a non-empty triangle mesh.
+ */
 export declare interface MeshBounds {
     /** Inclusive minimum XYZ coordinates. */
     readonly min: Vec3;
@@ -607,101 +645,335 @@ export declare const mirror: ModelingContext["mirror"];
 export declare interface ModelingContext {
     /** Derives a context with explicit physical sampling defaults in the same execution. */
     withResolution(this: void, resolution: GeometryResolution): ModelingContext;
-    /** Axis-aligned box with uniform or disjoint named edge/group treatments. */
+    /**
+     * Axis-aligned box with uniform or disjoint named edge/group treatments.
+     *
+     * @example Rounded box
+     * ```ts
+     * box({ size: [30, 20, 8], treatment: { kind: "round", radius: 2 } });
+     * ```
+     */
     box(this: void, options: BoxOptions): Solid;
-    /** +Z cylinder or frustum. Face sizing compensates polygon faceting. */
+    /**
+     * +Z cylinder or frustum. Face sizing compensates polygon faceting.
+     *
+     * @example Cylinder
+     * ```ts
+     * cylinder({ height: 20, radius: 10 });
+     * ```
+     *
+     * @example Cone
+     * ```ts
+     * cylinder({ height: 20, radius: [10, 0] });
+     * ```
+     */
     cylinder(this: void, options: CylinderOptions): Solid;
-    /** Hollow +Z tube. */
+    /**
+     * Hollow +Z tube.
+     *
+     * @example Tube
+     * ```ts
+     * tube({ height: 20, outerRadius: 10, innerRadius: 6 });
+     * ```
+     */
     tube(this: void, options: TubeOptions): Solid;
-    /** Origin-centered sphere. */
+    /**
+     * Origin-centered sphere.
+     *
+     * @example Sphere
+     * ```ts
+     * sphere({ diameter: 20 });
+     * ```
+     */
     sphere(this: void, options: SphereOptions): Solid;
-    /** Torus around +Z. */
+    /**
+     * Torus around +Z.
+     *
+     * @example Torus
+     * ```ts
+     * torus({ majorRadius: 12, minorRadius: 3 });
+     * ```
+     */
     torus(this: void, options: TorusOptions): Solid;
-    /** Robust union. */
+    /**
+     * Robust union.
+     *
+     * @example Union
+     * ```ts
+     * const block = box({ size: 20 });
+     * const cap = translate(sphere({ radius: 10 }), [0, 0, 10]);
+     * union([block, cap]);
+     * ```
+     */
     union(this: void, solids: readonly Solid[]): Solid;
     /** Native filled section union; dimensions cannot be mixed. */
     union(this: void, sections: readonly Section[]): Section;
-    /** Robust difference; an empty cutter array preserves the source. */
+    /**
+     * Robust difference; an empty cutter array preserves the source.
+     *
+     * @example Subtract
+     * ```ts
+     * const plate = box({ size: [30, 20, 6] });
+     * // Extend the cutter beyond both faces.
+     * const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+     * subtract(plate, [bore]);
+     * ```
+     */
     subtract(this: void, solid: Solid, cutters: readonly Solid[]): Solid;
     /** Native section difference; an empty cutter array preserves the source. */
     subtract(this: void, section: Section, cutters: readonly Section[]): Section;
-    /** Robust intersection. */
+    /**
+     * Robust intersection.
+     *
+     * @example Intersect
+     * ```ts
+     * intersect([box({ size: 20 }), sphere({ radius: 12 })]);
+     * ```
+     */
     intersect(this: void, solids: readonly Solid[]): Solid;
     /** Native filled section intersection; dimensions cannot be mixed. */
     intersect(this: void, sections: readonly Section[]): Section;
     /** Combines disjoint components without resolving overlap. */
     compose(this: void, solids: readonly Solid[]): Solid;
-    /** Convex hull of points or solids. */
+    /**
+     * Convex hull of points or solids.
+     *
+     * @example Hull
+     * ```ts
+     * const left = translate(sphere({ radius: 5 }), [-10, 0, 0]);
+     * const right = translate(sphere({ radius: 5 }), [10, 0, 0]);
+     * hull({ solids: [left, right] });
+     * ```
+     */
     hull(this: void, options: HullOptions): Solid;
     /** Three-dimensional Minkowski sum. */
     minkowskiSum(this: void, a: Solid, b: Solid): Solid;
-    /** Imports a bounded closed indexed mesh. */
+    /**
+     * Imports a bounded closed indexed mesh.
+     *
+     * @example Mesh import
+     * ```ts
+     * import { solidFromMesh } from "@metamesh/modeling";
+     * import { extrudeMesh, rectangleLoop } from "@metamesh/modeling/geometry";
+     *
+     * const mesh = extrudeMesh(rectangleLoop({ size: [20, 12] }), { height: 6 });
+     * solidFromMesh(mesh);
+     * ```
+     */
     solidFromMesh(this: void, mesh: TriangleMesh): Solid;
     /** Copies a handle to manufacturing mesh buffers. */
     toTriangleMesh(this: void, solid: Solid): TriangleMesh;
     /** Translation preserving dimensionality. */
     translate(this: void, section: Section, offset: Vec2): Section;
-    /** Translation preserving dimensionality. */
+    /**
+     * Translation preserving dimensionality.
+     *
+     * @example Translate
+     * ```ts
+     * translate(box({ size: [12, 8, 4] }), [15, 0, 0]);
+     * ```
+     */
     translate(this: void, solid: Solid, offset: Vec3): Solid;
     /** Degree rotation; scalar XY rotation or XYZ solid Euler angles. */
     rotate(this: void, section: Section, degrees: number): Section;
-    /** Degree rotation; scalar XY rotation or XYZ solid Euler angles. */
+    /**
+     * Degree rotation; scalar XY rotation or XYZ solid Euler angles.
+     *
+     * @example Rotate
+     * ```ts
+     * rotate(box({ size: [20, 10, 6] }), [0, 0, 30]);
+     * ```
+     */
     rotate(this: void, solid: Solid, degrees: Vec3): Solid;
-    /** Nonsingular scaling about the origin. */
+    /**
+     * Nonsingular scaling about the origin.
+     */
     scale(this: void, section: Section, factors: number | Vec2): Section;
-    /** Nonsingular scaling about the origin. */
+    /**
+     * Nonsingular scaling about the origin.
+     *
+     * @example Scale
+     * ```ts
+     * scale(sphere({ radius: 8 }), [2, 1, 1]);
+     * ```
+     */
     scale(this: void, solid: Solid, factors: number | Vec3): Solid;
     /** Reflection across an origin line/plane. */
     mirror(this: void, section: Section, normal: Vec2): Section;
-    /** Reflection across an origin line/plane. */
+    /**
+     * Reflection across an origin line/plane.
+     *
+     * @example Mirror
+     * ```ts
+     * const block = translate(box({ size: [12, 8, 4] }), [10, 0, 0]);
+     * mirror(block, [1, 0, 0]);
+     * ```
+     */
     mirror(this: void, solid: Solid, normal: Vec3): Solid;
     /** Row-major affine transform preserving dimensionality. */
     transform(this: void, section: Section, matrix: Transform2): Section;
     /** Row-major affine transform preserving dimensionality. */
     transform(this: void, solid: Solid, matrix: Transform3): Solid;
-    /** Reads a copied, immutable named anchor from this exact active build. */
+    /**
+     * Reads a copied, immutable named anchor from this exact active build.
+     *
+     * @example Read the top datum
+     * ```ts
+     * const plate = box({ size: [30, 20, 6] });
+     * anchor(plate, "top"); // position [0, 0, 3], direction [0, 0, 1]
+     * ```
+     */
     anchor(this: void, shape: Solid | Section, name: string): Anchor3;
-    /** Returns a new same-build handle with copied named anchors; existing names may be replaced. */
+    /**
+     * Returns a new same-build handle with copied named anchors; existing names may be replaced.
+     */
     withAnchors<T extends Solid | Section>(this: void, shape: T, anchors: Readonly<Record<string, Anchor3>>): T;
-    /** Places an explicit or named source anchor against an explicit target anchor. */
+    /**
+     * Places an explicit or named source anchor against an explicit target anchor.
+     *
+     * @example Anchor attachment
+     * ```ts
+     * const plate = box({ size: [30, 20, 6] });
+     * const pin = cylinder({ height: 12, radius: 3 });
+     * attach(pin, "bottom", anchor(plate, "top"), { gap: 1 });
+     * ```
+     */
     attach(this: void, solid: Solid, source: Anchor3 | string, target: Anchor3, options?: AttachOptions): Solid;
-    /** Creates a native filled section without an intermediate Region2 conversion. */
+    /**
+     * Creates a native filled section without an intermediate Region2 conversion.
+     */
     sectionFromContours(this: void, contours: readonly Loop2[], options?: SectionFromContoursOptions): Section;
     /** Imports explicit region topology once. */
     fromRegion(this: void, region: Region2): Section;
     /** Explicit copied topology inspection; not needed for section operations. */
     toRegion(this: void, section: Section): Region2;
-    /** Filled rectangular section with uniform or independently treated corners. */
+    /**
+     * Filled rectangular section with uniform or independently treated corners.
+     *
+     * @example Round the corners
+     * ```ts
+     * rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+     * ```
+     */
     rectangle(this: void, options: RectangleOptions): Section;
-    /** Centered circular section. */
+    /**
+     * Centered circular section.
+     *
+     * @example Size to polygon faces
+     * ```ts
+     * circle({ diameter: 12, sizing: "face" });
+     * ```
+     */
     circle(this: void, options: CircleOptions): Section;
-    /** Centered elliptical section. */
+    /**
+     * Centered elliptical section.
+     *
+     * @example Ellipse by full dimensions
+     * ```ts
+     * ellipse({ size: [30, 20] });
+     * ```
+     */
     ellipse(this: void, options: EllipseOptions): Section;
-    /** Regular polygon with a vertex on +X. */
+    /**
+     * Regular polygon with a vertex on +X.
+     *
+     * @example Hexagonal section
+     * ```ts
+     * regularPolygon({ radius: 10, sides: 6, sizing: "face" });
+     * ```
+     */
     regularPolygon(this: void, options: RegularPolygonOptions): Section;
-    /** Alternating outer/inner star vertices. */
+    /**
+     * Alternating outer/inner star vertices.
+     *
+     * @example Five-point section
+     * ```ts
+     * star({ outerRadius: 12, innerRadius: 6, points: 5 });
+     * ```
+     */
     star(this: void, options: StarOptions): Section;
-    /** Native millimetre offset preserving holes. */
+    /**
+     * Native millimetre offset preserving holes.
+     *
+     * @example Add a 2 mm margin
+     * ```ts
+     * const outline = rectangle({ size: [20, 12] });
+     * offset(outline, 2, { join: "round" });
+     * ```
+     */
     offset(this: void, section: Section, distance: number, options?: RegionOffsetOptions): Section;
-    /** Extrudes along +Z with degree twist and top scaling. */
+    /**
+     * Extrudes along +Z with degree twist and top scaling.
+     *
+     * @example Extrude
+     * ```ts
+     * const outline = rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+     * extrude(outline, { height: 8 });
+     * ```
+     */
     extrude(this: void, shape: ModelingShape, options: ExtrudeOptions): Solid;
-    /** Revolves a filled radial/Z shape around +Z, with caps for partial sweeps. */
+    /**
+     * Revolves a filled radial/Z shape around +Z, with caps for partial sweeps.
+     *
+     * @example Revolve
+     * ```ts
+     * // Contour coordinates are [radius, Z].
+     * const profile = sectionFromContours([[[8, 0], [12, 0], [12, 16], [8, 16]]]);
+     * revolve(profile, { revolveDegrees: 270 });
+     * ```
+     */
     revolve(this: void, shape: ModelingShape, options?: RevolveOptions): Solid;
     /** Filled XY projection. */
     projectSection(this: void, solid: Solid): Section;
     /** Horizontal filled slice. */
     sliceSection(this: void, solid: Solid, z: number): Section;
-    /** Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method. */
+    /**
+     * Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method.
+     *
+     * @example Loft
+     * ```ts
+     * loft([
+     *   { profile: circle({ diameter: 16 }), z: 0 },
+     *   { profile: rectangle({ size: [30, 20], treatment: { kind: "round", radius: 3 } }), z: 30 },
+     * ]);
+     * ```
+     */
     loft(this: void, stations: readonly LoftStation[], options?: LoftOptions): Solid;
     /** Lofts explicit corresponding contours, including holes and collapsed logical slots. */
     loft(this: void, stations: readonly CorrespondingProfileStation[], options?: LoftOptions): Solid;
     /** Explicit family matching on a shared physical span grid using context resolution. */
     matchProfiles(this: void, profiles: readonly Profile[], options?: MatchProfilesOptions): readonly CorrespondingProfile[];
-    /** Sweeps filled or explicitly corresponding contours using the selected frame policy. */
+    /**
+     * Sweeps filled or explicitly corresponding contours using the selected frame policy.
+     *
+     * @example Sweep
+     * ```ts
+     * const profile = rectangle({ size: [6, 3], treatment: { kind: "round", radius: 1 } });
+     * sweep(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+     *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
+     * });
+     * ```
+     */
     sweep(this: void, shape: ModelingShape, path: readonly Vec3[], options?: SweepOptions): Solid;
-    /** Copies lightweight section measurements. */
+    /**
+     * Copies lightweight section measurements.
+     *
+     * @example Check filled area
+     * ```ts
+     * const facts = inspectSection(rectangle({ size: [20, 10] }));
+     * facts.area; // 200 mm²
+     * ```
+     */
     inspectSection(this: void, section: Section): SectionInspection;
-    /** Copies solid bounds and volume; temporary components are owned by the build. */
+    /**
+     * Copies solid bounds and volume; temporary components are owned by the build.
+     *
+     * @example Check dimensions and volume
+     * ```ts
+     * const facts = inspectSolid(box({ size: [30, 20, 6] }));
+     * facts.volume; // 3600 mm³
+     * ```
+     */
     inspectSolid(this: void, solid: Solid): SolidInspection;
     /** Copies intersections along the finite directed origin-to-endpoint segment. */
     rayCast(this: void, solid: Solid, origin: Vec3, endpoint: Vec3): readonly SolidRayHit[];
@@ -713,23 +985,97 @@ export declare interface ModelingContext {
     implicit(this: void, options: ImplicitOptions): Solid;
     /** Replaces native tolerance on an immutable copy; zero selects the kernel minimum. */
     setTolerance(this: void, solid: Solid, tolerance: number): Solid;
-    /** Closed regular-grid top above a flat base; every height is sampled once. */
+    /**
+     * Closed regular-grid top above a flat base; every height is sampled once.
+     *
+     * @example Heightfield
+     * ```ts
+     * heightfield({
+     *   size: [30, 20], segments: [24, 16],
+     *   height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+     * });
+     * ```
+     */
     heightfield(this: void, options: HeightfieldOptions): Solid;
-    /** Repeats one solid along a normalized direction. */
+    /**
+     * Repeats one solid along a normalized direction.
+     *
+     * @example Three copies along X
+     * ```ts
+     * linearPattern(box({ size: 4 }), { count: 3, spacing: 10 });
+     * ```
+     */
     linearPattern(this: void, source: PatternSource, options: LinearPatternOptions): readonly Solid[];
-    /** Repeats one solid about an axis. */
+    /**
+     * Repeats one solid about an axis.
+     *
+     * @example Six copies around Z
+     * ```ts
+     * const pin = translate(cylinder({ height: 6, radius: 2 }), [12, 0, 0]);
+     * radialPattern(pin, { count: 6, axis: [0, 0, 1], angleDegrees: 60 });
+     * ```
+     */
     radialPattern(this: void, source: PatternSource, options: RadialPatternOptions): readonly Solid[];
-    /** XY or XYZ copies, optionally centered or placed in an explicit frame. */
+    /**
+     * XY or XYZ copies, optionally centered or placed in an explicit frame.
+     *
+     * @example Centered XY grid
+     * ```ts
+     * gridPattern(box({ size: 4 }), { count: [3, 2], spacing: [10, 10], center: true });
+     * ```
+     */
     gridPattern(this: void, source: PatternSource, options: GridPatternOptions): readonly Solid[];
-    /** Physical arc-length copies along a sampled path, with optional tangent orientation. */
+    /**
+     * Physical arc-length copies along a sampled path, with optional tangent orientation.
+     *
+     * @example Copies along a bent path
+     * ```ts
+     * pathPattern(box({ size: 4 }), [[0, 0, 0], [20, 0, 0], [20, 20, 0]], { count: 5 });
+     * ```
+     */
     pathPattern(this: void, source: PatternSource, path: readonly Vec3[], options: PathPatternOptions): readonly Solid[];
     /** Helical ridge mesh construction. */
     threadRidge(this: void, options: ThreadRidgeOptions): Solid;
-    /** Compensated external threaded rod. */
+    /**
+     * Compensated external threaded rod.
+     *
+     * @example Threaded rod
+     * ```ts
+     * import { threadedRod } from "@metamesh/modeling";
+     * import { createThreadProfile } from "@metamesh/modeling/geometry";
+     *
+     * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+     * threadedRod({ nominalMajorDiameter: 12, length: 24, profile, fit: "normal" });
+     * ```
+     */
     threadedRod(this: void, options: ThreadedRodOptions): Solid;
-    /** Compensated internal threaded cutter. */
+    /**
+     * Compensated internal threaded cutter.
+     *
+     * @example Internal thread
+     * ```ts
+     * import { cylinder, internalThreadCutter, subtract } from "@metamesh/modeling";
+     * import { createThreadProfile } from "@metamesh/modeling/geometry";
+     *
+     * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+     * const body = cylinder({ diameter: 20, height: 12, center: false });
+     * const cutter = internalThreadCutter({ nominalMajorDiameter: 12, length: 12, profile });
+     * subtract(body, [cutter]);
+     * ```
+     */
     internalThreadCutter(this: void, options: InternalThreadCutterOptions): Solid;
-    /** Compensated threaded nut. */
+    /**
+     * Compensated threaded nut.
+     *
+     * @example Threaded nut
+     * ```ts
+     * import { threadedNut } from "@metamesh/modeling";
+     * import { createThreadProfile } from "@metamesh/modeling/geometry";
+     *
+     * const profile = createThreadProfile({ kind: "triangular", pitch: 1.75 });
+     * threadedNut({ nominalMajorDiameter: 12, thickness: 8, width: 20, shape: "hex", profile, fit: "normal" });
+     * ```
+     */
     threadedNut(this: void, options: ThreadedNutOptions): Solid;
     /** Allocation-free external-thread facts. */
     preflightThreadedRod(this: void, options: ThreadedRodOptions): HelicalThreadSolidMeshPreflight;
@@ -737,15 +1083,44 @@ export declare interface ModelingContext {
     preflightInternalThreadCutter(this: void, options: InternalThreadCutterOptions): HelicalThreadSolidMeshPreflight;
     /** Allocation-free nut/cutter facts. */
     preflightThreadedNut(this: void, options: ThreadedNutOptions): ThreadedNutPreflight;
-    /** Consumes a previously prepared layout; never shapes or fetches a font. */
+    /**
+     * Consumes a previously prepared layout; never shapes or fetches a font.
+     *
+     * @example Use a prepared text layout
+     * ```ts
+     * // Prepare the exact font and layout before entering build.
+     * function labelSection(layout: VectorTextLayout) {
+     *   return textSection(layout);
+     * }
+     * ```
+     */
     textSection(this: void, layout: VectorTextLayout, options?: TextSectionOptions): Section;
-    /** Imports bounded painted SVG document geometry. */
+    /**
+     * Imports bounded painted SVG document geometry.
+     *
+     * @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" },
+     * );
+     * ```
+     */
     svgSection(this: void, svg: string, options?: SvgSectionOptions): Section;
-    /** Imports bounded filled SVG path data. */
+    /**
+     * Imports bounded filled SVG path data.
+     *
+     * @example Fill an SVG path in millimetres
+     * ```ts
+     * svgPathSection("M0 0H20V12H0Z", { origin: "center", scale: 1 });
+     * ```
+     */
     svgPathSection(this: void, path: string, options?: SvgPathSectionOptions): Section;
 }
 
-/** Returns bound local operations, optionally with derived resolution, without changing imported operations. */
+/**
+ * Returns bound local operations, optionally with derived resolution, without changing imported operations.
+ */
 export declare function modelingFunctions(resolution?: GeometryResolution): ModelingContext;
 
 /** Aggregate manufacturing output ceilings selected by a trusted host. */
@@ -791,7 +1166,9 @@ export declare interface PathPatternOptions {
     readonly orientation?: "fixed" | "tangent";
 }
 
-/** One same-build shape, or a synchronous factory called once per copy in index order. */
+/**
+ * One same-build shape, or a synchronous factory called once per copy in index order.
+ */
 export declare type PatternSource = Solid | ((index: number) => Solid);
 
 /**
@@ -839,7 +1216,9 @@ export declare interface PrimitivePlacementOptions {
     readonly tolerance?: GeometryToleranceOptions;
 }
 
-/** Named baseline fit policies for calibrated FDM-style printed threads. */
+/**
+ * Named baseline fit policies for calibrated FDM-style printed threads.
+ */
 export declare type PrintableThreadFit = "tight" | "normal" | "loose";
 
 /**
@@ -939,7 +1318,9 @@ export declare const projectSection: ModelingContext["projectSection"];
 /** Host-bound radialPattern operation. Valid only during a synchronous build. */
 export declare const radialPattern: ModelingContext["radialPattern"];
 
-/** Options for repeating one solid around an axis through a center point. */
+/**
+ * Options for repeating one solid around an axis through a center point.
+ */
 export declare interface RadialPatternOptions {
     /** Number of solids to return, including the original. */
     readonly count: number;
@@ -951,10 +1332,14 @@ export declare interface RadialPatternOptions {
     readonly center?: Vec3;
 }
 
-/** Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces. */
+/**
+ * Radial dimensions refer to polygon vertices or compensate faceting to meet polygon faces.
+ */
 export declare type RadialSizing = "vertex" | "face";
 
-/** Nominal radial sizing shared by circular and regular polygon construction. */
+/**
+ * Nominal radial sizing shared by circular and regular polygon construction.
+ */
 export declare interface RadialSizingOptions {
     /** Explicit sampling ceilings; bound modeling operations may only lower the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -982,7 +1367,9 @@ bottomLeft: RectangleCornerTreatment,
 bottomRight: RectangleCornerTreatment
 ];
 
-/** Shared rectangle dimensions, origin and uniform or per-corner treatment. */
+/**
+ * Shared rectangle dimensions, origin and uniform or per-corner treatment.
+ */
 export declare interface RectangleLoopOptions {
     /** Positive uniform size or explicit XY extents in millimetres. */
     readonly size: number | Vec2;
@@ -994,7 +1381,9 @@ export declare interface RectangleLoopOptions {
     readonly limits?: Partial<GeometrySamplingLimits>;
 }
 
-/** Rectangle dimensions, placement and uniform or per-corner treatment. */
+/**
+ * Rectangle dimensions, placement and uniform or per-corner treatment.
+ */
 export declare interface RectangleOptions extends RectangleLoopOptions, PrimitivePlacement {
 }
 
@@ -1019,7 +1408,9 @@ export declare interface RegionOffsetOptions {
 /** Host-bound regularPolygon operation. Valid only during a synchronous build. */
 export declare const regularPolygon: ModelingContext["regularPolygon"];
 
-/** Regular polygon dimensions, radial convention and degree rotation. */
+/**
+ * Regular polygon dimensions, radial convention and degree rotation.
+ */
 export declare type RegularPolygonOptions = RadialSizingOptions & PrimitivePlacement & {
     /** Positive nominal radius in millimetres, interpreted according to sizing. */
     readonly radius: number;
@@ -1032,7 +1423,9 @@ export declare type RegularPolygonOptions = RadialSizingOptions & PrimitivePlace
 /** Host-bound revolve operation. Valid only during a synchronous build. */
 export declare const revolve: ModelingContext["revolve"];
 
-/** Circumferential sampling and degree sweep shared by pure and filled revolution. */
+/**
+ * Circumferential sampling and degree sweep shared by pure and filled revolution.
+ */
 export declare interface RevolveOptions extends CircularPrimitiveOptions {
     /**
      * Positive angular sweep no greater than 360 degrees; partial revolutions have end caps.
@@ -1048,7 +1441,9 @@ export declare interface RevolveOptions extends CircularPrimitiveOptions {
 /** Host-bound rotate operation. Valid only during a synchronous build. */
 export declare const rotate: ModelingContext["rotate"];
 
-/** A circular edge or corner roundover with explicit physical sampling. */
+/**
+ * A circular edge or corner roundover with explicit physical sampling.
+ */
 export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
     /** Selects circular corners or spherical all-edge roundovers. */
     readonly kind: "round";
@@ -1070,13 +1465,17 @@ declare const sectionBrand: unique symbol;
 /** Host-bound sectionFromContours operation. Valid only during a synchronous build. */
 export declare const sectionFromContours: ModelingContext["sectionFromContours"];
 
-/** Filled-contour resolution. Closing vertices are implicit. */
+/**
+ * Filled-contour resolution. Closing vertices are implicit.
+ */
 export declare interface SectionFromContoursOptions {
     /** Nonzero or even-odd filled-contour rule; defaults to nonzero. */
     readonly fillRule?: "nonzero" | "evenodd";
 }
 
-/** Copied native filled section facts in millimetres and square millimetres. */
+/**
+ * Copied native filled section facts in millimetres and square millimetres.
+ */
 export declare interface SectionInspection {
     /** Filled section area in square millimetres. */
     readonly area: number;
@@ -1126,7 +1525,9 @@ declare const solidBrand: unique symbol;
 /** Host-bound solidFromMesh operation. Valid only during a synchronous build. */
 export declare const solidFromMesh: ModelingContext["solidFromMesh"];
 
-/** Copied solid bounds, connected component count, and cubic millimetre volume. */
+/**
+ * Copied solid bounds, connected component count, and cubic millimetre volume.
+ */
 export declare interface SolidInspection {
     /** Inclusive maximum coordinates in millimetres. */
     readonly max: Vec3;
@@ -1165,7 +1566,9 @@ export declare interface SolidRayHit {
 /** Host-bound sphere operation. Valid only during a synchronous build. */
 export declare const sphere: ModelingContext["sphere"];
 
-/** Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere. */
+/**
+ * Exactly one radius or diameter, placement, and tessellation for an origin-centered sphere.
+ */
 export declare type SphereOptions = CircularPrimitiveOptions & PrimitivePlacement & ({
     /** Positive radius in millimetres; mutually exclusive with diameter. */
     readonly radius: number;
@@ -1192,7 +1595,9 @@ declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
 /** Host-bound star operation. Valid only during a synchronous build. */
 export declare const star: ModelingContext["star"];
 
-/** Alternating outer and inner vertices, centered on the XY origin. */
+/**
+ * Alternating outer and inner vertices, centered on the XY origin.
+ */
 export declare interface StarOptions extends PrimitivePlacement {
     /** Explicit sampling ceilings, bounded by the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1232,7 +1637,9 @@ export declare interface SvgPathSectionOptions {
 /** Host-bound svgSection operation. Valid only during a synchronous build. */
 export declare const svgSection: ModelingContext["svgSection"];
 
-/** Bounded SVG document sampling. Center origin uses the final painted bounds. */
+/**
+ * Bounded SVG document sampling. Center origin uses the final painted bounds.
+ */
 export declare interface SvgSectionOptions {
     /** Local allocation ceilings may only lower the configured engine policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1247,7 +1654,9 @@ export declare interface SvgSectionOptions {
 /** Host-bound sweep operation. Valid only during a synchronous build. */
 export declare const sweep: ModelingContext["sweep"];
 
-/** Controls shared by pure mesh construction and filled modeling sweeps. */
+/**
+ * Controls shared by pure mesh construction and filled modeling sweeps.
+ */
 export declare interface SweepOptions {
     /** Join the path's last station to its first. Open paths retain watertight end caps. */
     readonly closed?: boolean;
@@ -1267,7 +1676,9 @@ export declare interface SweepOptions {
     readonly seamProfileOffset?: number;
 }
 
-/** Explicit profile-X frame policy; all normals are directed, and selected singular policies reject. */
+/**
+ * Explicit profile-X frame policy; all normals are directed, and selected singular policies reject.
+ */
 export declare type SweepOrientation = {
     /** Minimizes frame rotation by parallel transport. */
     readonly kind: "transport";
@@ -1291,7 +1702,9 @@ export declare type SweepOrientation = {
 /** Host-bound textSection operation. Valid only during a synchronous build. */
 export declare const textSection: ModelingContext["textSection"];
 
-/** Physical curve sampling applied to already prepared vector text. */
+/**
+ * Physical curve sampling applied to already prepared vector text.
+ */
 export declare interface TextSectionOptions {
     /** Local allocation ceilings may only lower the configured engine policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1318,7 +1731,9 @@ export declare const threadedNut: ModelingContext["threadedNut"];
 /** Nut-edge bevel selection. */
 export declare type ThreadedNutBevel = "automatic" | "both" | "inside" | "none" | "outside";
 
-/** Options for a compensated nut with an internal thread. */
+/**
+ * Options for a compensated nut with an internal thread.
+ */
 export declare interface ThreadedNutOptions extends Omit<InternalThreadCutterOptions, "bevelBottom" | "bevelSize" | "bevelTop" | "length"> {
     /** Nut body bevel selection. Default: `automatic`. */
     readonly bevel?: ThreadedNutBevel;
@@ -1354,13 +1769,17 @@ export declare interface ThreadedNutPreflight {
     readonly threadCircularSegments: number;
 }
 
-/** Supported printable nut body shapes. */
+/**
+ * Supported printable nut body shapes.
+ */
 export declare type ThreadedNutShape = "hex" | "round" | "square";
 
 /** Host-bound threadedRod operation. Valid only during a synchronous build. */
 export declare const threadedRod: ModelingContext["threadedRod"];
 
-/** Options for a compensated external threaded rod along +Z. */
+/**
+ * Options for a compensated external threaded rod along +Z.
+ */
 export declare interface ThreadedRodOptions extends Omit<HelicalThreadRidgeMeshOptions, "majorDiameter">, ThreadBevelOptions {
     /** Printable fit or caller-calibrated allowances. Default: `normal`. */
     readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
@@ -1408,7 +1827,9 @@ export declare interface ThreadEndTreatmentOptions {
     readonly top?: ThreadEndStyle;
 }
 
-/** Direction in which a conventional helical thread advances around +Z. */
+/**
+ * Direction in which a conventional helical thread advances around +Z.
+ */
 export declare type ThreadHandedness = "left" | "right";
 
 /** Radial envelope toward which a blunt lead-in collapses. */
@@ -1417,7 +1838,9 @@ export declare type ThreadLeadInEnvelope = "major" | "minor";
 /** BOSL2-compatible cross-section scaling curve for a blunt thread lead-in. */
 export declare type ThreadLeadInShape = "cut" | "linear" | "smooth" | "sqrt";
 
-/** A validated immutable periodic thread profile in `[axial, radial]` millimetres. */
+/**
+ * A validated immutable periodic thread profile in `[axial, radial]` millimetres.
+ */
 export declare interface ThreadProfile {
     /** Axial width of the flat at the major envelope. */
     readonly crestFlatWidth: number;
@@ -1441,7 +1864,9 @@ declare interface ThreadProfileBaseSpec {
     readonly tolerance?: GeometryToleranceOptions;
 }
 
-/** Supported built-in and caller-defined thread profiles. */
+/**
+ * Supported built-in and caller-defined thread profiles.
+ */
 declare type ThreadProfileSpec = AcmeThreadProfileSpec | ButtressThreadProfileSpec | CustomThreadProfileSpec | SquareThreadProfileSpec | TrapezoidalThreadProfileSpec | TriangularThreadProfileSpec;
 
 /** Host-bound threadRidge operation. Valid only during a synchronous build. */
@@ -1456,7 +1881,9 @@ export declare const toRegion: ModelingContext["toRegion"];
 /** Host-bound torus operation. Valid only during a synchronous build. */
 export declare const torus: ModelingContext["torus"];
 
-/** Dimensions and independent ring/profile tessellation for a torus around the Z axis. */
+/**
+ * Dimensions and independent ring/profile tessellation for a torus around the Z axis.
+ */
 export declare interface TorusOptions extends PrimitivePlacement {
     /** Explicit sampling ceilings, bounded by the host policy. */
     readonly limits?: Partial<GeometrySamplingLimits>;
@@ -1535,7 +1962,9 @@ declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
     readonly threadAngle?: number;
 }
 
-/** A topology-preserving indexed triangle mesh with XYZ vertex positions. */
+/**
+ * A topology-preserving indexed triangle mesh with XYZ vertex positions.
+ */
 export declare interface TriangleMesh {
     /** Three unsigned vertex indices per triangle. */
     readonly indices: Uint32Array;
@@ -1543,7 +1972,9 @@ export declare interface TriangleMesh {
     readonly positions: Float32Array;
 }
 
-/** Measurements and optional edge-connected topology from one validated mesh traversal. */
+/**
+ * Measurements and optional edge-connected topology from one validated mesh traversal.
+ */
 export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
     /** Number of referenced edge-connected components when `includeTopology` is requested. */
     readonly connectedComponentCount?: number;
@@ -1551,7 +1982,9 @@ export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
     readonly edgeCount?: number;
 }
 
-/** Geometric measurements derived from a validated, non-empty triangle mesh. */
+/**
+ * Geometric measurements derived from a validated, non-empty triangle mesh.
+ */
 export declare interface TriangleMeshMeasurements {
     /** Axis-aligned bounds. */
     readonly bounds: MeshBounds;
@@ -1565,7 +1998,9 @@ export declare interface TriangleMeshMeasurements {
     readonly vertexCount: number;
 }
 
-/** ISO/UTS-like 60-degree truncated triangular profile. */
+/**
+ * ISO/UTS-like 60-degree truncated triangular profile.
+ */
 declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
     /** Selects the 60-degree triangular profile family. */
     readonly kind: "triangular";
@@ -1584,7 +2019,9 @@ declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
 /** Host-bound tube operation. Valid only during a synchronous build. */
 export declare const tube: ModelingContext["tube"];
 
-/** Dimensions, placement, and tessellation for a hollow Z-axis tube. */
+/**
+ * Dimensions, placement, and tessellation for a hollow Z-axis tube.
+ */
 export declare interface TubeOptions extends CircularPrimitiveOptions, PrimitivePlacement {
     /**
      * Centers the tube on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
@@ -1616,7 +2053,9 @@ export declare interface VectorTextBounds {
     readonly max: readonly [number, number];
 }
 
-/** Immutable vector layout with no browser, font parser, or kernel ownership. */
+/**
+ * Immutable vector layout with no browser, font parser, or kernel ownership.
+ */
 export declare interface VectorTextLayout {
     /** Nonzero-filled path data in millimetres, positive Y upward; empty for text with no ink. */
     readonly paths: readonly string[];