@metamesh/modeling 0.16.0 → 0.18.0

package/dist/api/index.d.ts

@@ -1,7 +1,17 @@
+import type {
+  ImmutableBuffer,
+  ImmutableTriangleMesh,
+  NumericArray,
+} from "@metamesh/modeling/geometry";
+export type {
+  ImmutableBuffer,
+  ImmutableTriangleMesh,
+  NumericArray,
+} from "@metamesh/modeling/geometry";
 /** Immutable modeling recipes and math values; the host owns geometry evaluation. @packageDocumentation */
 
 /** ACME 29-degree included-angle profile. */
-declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
+export declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects the 29-degree ACME profile family. */
   readonly kind: "acme";
   /**
@@ -11,17 +21,6 @@ declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
   readonly depth?: number;
 }
 
-/**
- * Reads a copied, immutable named anchor from this exact active generation.
- *
- * @example Read the top datum
- * ```ts
- * const plate = box({ size: [30, 20, 6] });
- * anchor(plate, "top"); // position [0, 0, 3], direction [0, 0, 1]
- * ```
- */
-export declare function anchor(shape: Solid | Section, name: string): Anchor3;
-
 /**
  * An attachment pose on a solid or assembly.
  *
@@ -49,6 +48,13 @@ export declare interface AttachOptions {
   readonly tolerance?: GeometryToleranceOptions;
 }
 
+/** One size for both ends, or independent sizes in bottom/top order. Zero disables an end. */
+export declare type Bevel =
+  BevelSize | readonly [bottom: BevelSize, top: BevelSize];
+
+/** Nonnegative 45-degree axial/radial bevel size in millimetres, or factory automatic sizing. */
+export declare type BevelSize = number | "auto";
+
 /** Immutable finite XY bounds in millimetres, with tuple coordinates for data interoperability. */
 export declare interface Bounds2 extends Bounds2Data {
   /** Returns nonnegative X/Y dimensions in millimetres, including zero extents. */
@@ -62,14 +68,15 @@ export declare interface Bounds2 extends Bounds2Data {
 }
 
 /**
- * Snapshots finite ordered XY bounds in millimetres as an immutable fluent value.
+ * Constructs immutable finite XY bounds from ordered extrema or nonnegative size in millimetres.
  *
  * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
  * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
  * Compiled Generator packages passing these values to host recipes or computed data require
- * runtime 8.0.0 or newer in major 8.
+ * runtime 10.0.0 or newer in major 10.
  */
-export declare function bounds2(input: Bounds2Input): Bounds2;
+export declare function bounds2(input: Bounds2Options | Bounds2): Bounds2;
 
 /** Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. */
 export declare interface Bounds2Data {
@@ -82,6 +89,29 @@ export declare interface Bounds2Data {
 /** An immutable XY bounds value or its plain min/max representation. */
 export declare type Bounds2Input = Bounds2 | Bounds2Data;
 
+/** XY bounds construction from existing extrema or nonnegative dimensions, never both. */
+export declare type Bounds2Options =
+  | {
+      /** Inclusive minimum XY coordinates in millimetres. */
+      readonly min: Vector2Input;
+      /** Inclusive maximum XY coordinates in millimetres. */
+      readonly max: Vector2Input;
+      /** Size construction cannot be combined with extrema. */
+      readonly size?: never;
+      /** Center applies only to size construction. */
+      readonly center?: never;
+    }
+  | {
+      /** Nonnegative XY dimensions in millimetres. */
+      readonly size: Vector2Input;
+      /** Center on the origin; false starts at the origin. Defaults to true. */
+      readonly center?: boolean;
+      /** Minimum coordinates are unavailable when size is supplied. */
+      readonly min?: never;
+      /** Maximum coordinates are unavailable when size is supplied. */
+      readonly max?: never;
+    };
+
 /** Immutable finite XYZ bounds in millimetres, with tuple coordinates for data interoperability. */
 export declare interface Bounds3 extends Bounds3Data {
   /** Returns nonnegative X/Y/Z dimensions in millimetres, including zero extents. */
@@ -95,14 +125,15 @@ export declare interface Bounds3 extends Bounds3Data {
 }
 
 /**
- * Snapshots finite ordered XYZ bounds in millimetres as an immutable fluent value.
+ * Constructs immutable finite XYZ bounds from ordered extrema or nonnegative size in millimetres.
  *
  * Zero extents are valid. Invalid dimensions, nonfinite coordinates, reversed bounds and
  * overflowing extents throw `INVALID_ARGUMENT` GeometryError. Use `toData()` for plain records.
+ * Size construction centers on the origin unless `center` is false. Size and extrema are exclusive.
  * Compiled Generator packages passing these values to host recipes or computed data require
- * runtime 8.0.0 or newer in major 8.
+ * runtime 10.0.0 or newer in major 10.
  */
-export declare function bounds3(input: Bounds3Input): Bounds3;
+export declare function bounds3(input: Bounds3Options | Bounds3): Bounds3;
 
 /** Plain axis-aligned XYZ bounds for interchange; use bounds3 for immutable measurement methods. */
 export declare interface Bounds3Data {
@@ -115,6 +146,29 @@ export declare interface Bounds3Data {
 /** An immutable XYZ bounds value or its plain min/max representation. */
 export declare type Bounds3Input = Bounds3 | Bounds3Data;
 
+/** XYZ bounds construction from existing extrema or nonnegative dimensions, never both. */
+export declare type Bounds3Options =
+  | {
+      /** Inclusive minimum XYZ coordinates in millimetres. */
+      readonly min: Vector3Input;
+      /** Inclusive maximum XYZ coordinates in millimetres. */
+      readonly max: Vector3Input;
+      /** Size construction cannot be combined with extrema. */
+      readonly size?: never;
+      /** Center applies only to size construction. */
+      readonly center?: never;
+    }
+  | {
+      /** Nonnegative XYZ dimensions in millimetres. */
+      readonly size: Vector3Input;
+      /** Center on the origin; false starts at the origin. Defaults to true. */
+      readonly center?: boolean;
+      /** Minimum coordinates are unavailable when size is supplied. */
+      readonly min?: never;
+      /** Maximum coordinates are unavailable when size is supplied. */
+      readonly max?: never;
+    };
+
 /**
  * Axis-aligned box with uniform or disjoint named edge/group treatments.
  *
@@ -160,16 +214,16 @@ export declare interface BoxOptions extends PrimitiveAttachment {
    */
   readonly center?: boolean;
   /** Positive uniform size or explicit `[X, Y, Z]` extents in millimetres. */
-  readonly size: number | Vector3Data;
+  readonly size: number | Vector3Input;
   /** Uniform treatment or independent disjoint nominal edge/group treatments. */
   readonly treatment?: EdgeTreatment | BoxEdgeTreatments;
 }
 
 /** Axial side carrying the near-normal pressure flank of a buttress thread. */
-declare type ButtressPressureFlankSide = "negative" | "positive";
+export declare type ButtressPressureFlankSide = "negative" | "positive";
 
 /** Asymmetric printable buttress profile with 7/45-degree flanks. */
-declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
+export declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects the asymmetric printable buttress profile family. */
   readonly kind: "buttress";
   /**
@@ -185,13 +239,6 @@ declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
   readonly pressureFlankSide?: ButtressPressureFlankSide;
 }
 
-/** Copies intersections along the finite directed origin-to-endpoint segment. */
-export declare function castSegment(
-  solid: Solid,
-  origin: Vector3Input,
-  endpoint: Vector3Input,
-): readonly SolidSegmentHit[];
-
 /**
  * A planar edge or corner chamfer with equal or independent surface setbacks.
  */
@@ -212,20 +259,18 @@ export declare interface ChamferedEdgeTreatment {
  */
 export declare function circle(options: CircleOptions): Section;
 
-/**
- * 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 CircleContourOptions = CircularPrimitiveOptions &
   RadialSizingOptions &
   (
     | {
-        /** Positive nominal radius in millimetres; mutually exclusive with diameter. */
+        /** Positive nominal radius in millimetres. */
         readonly radius: number;
-        /** Full diameter is unavailable when radius is supplied. */
+        /** Diameter is unavailable when radius is supplied. */
         readonly diameter?: never;
       }
     | {
-        /** Positive full diameter in millimetres; mutually exclusive with radius. */
+        /** Positive nominal diameter in millimetres. */
         readonly diameter: number;
         /** Radius is unavailable when diameter is supplied. */
         readonly radius?: never;
@@ -254,40 +299,12 @@ export declare interface CircularPrimitiveOptions {
   readonly resolution?: GeometryResolution;
 }
 
-/**
- * Observes disconnected material pieces as session-restricted solid selections.
- *
- * Each piece retains its enclosed cavities. A sealed hollow box is one component; adding a loose
- * ball inside its cavity produces two. Recombining the pieces preserves the original material.
- * This does not cut connected geometry. Containment is bounded to 2,000,000 comparisons.
- * Selection order and cardinality depend on evaluated topology. Results and recipes using them
- * can only be evaluated in this session; composition itself requires no engine.
- *
- * @example Move disconnected pieces independently
- * ```ts
- * const islands = union([box({ size: 8 }), box({ size: 8 }).translate([12, 0, 0])]);
- * const pieces = components(islands);
- * // Component order is unspecified; the index only sets a display height here.
- * union(pieces.map((piece, index) => piece.translate([0, 0, index * 6])));
- * ```
- */
-export declare function components(solid: Solid): readonly Solid[];
-
-/**
- * Observes filled 2D islands, retaining each island's holes; empty gives [].
- * Selections and recipes using them can only be evaluated in this session.
- */
-export declare function components(section: Section): readonly Section[];
-
-/** Combines disjoint components without resolving overlap. */
-export declare function compose(solids: readonly Solid[]): Solid;
-
 /** A lazy session-owned reader. Calling it tracks its output in the current computation. */
 export declare interface Computed<T> {
   /** Compile-time ownership brand; readers are created by the engine's context helper. */
   readonly [computedBrand]: "Computed";
   /** Reads immutable data or a deferred recipe; evaluation is synchronous and cached. */
-  (): T;
+  (): ImmutableValue<T>;
 }
 
 declare const computedBrand: unique symbol;
@@ -342,7 +359,7 @@ export declare type CorrespondingProfileStation = LoftPlacement & {
 /**
  * Explicit physical sampling and allocation policy for reusable curves.
  */
-declare interface CurveSamplingOptions {
+export declare interface CurveSamplingOptions {
   /** Exact segment count overrides physical criteria; curve parameters are spaced uniformly. */
   readonly segments?: number;
   /** Millimetre sampling policy; circularSegments applies only to arcs. */
@@ -354,7 +371,7 @@ declare interface CurveSamplingOptions {
 }
 
 /** Caller-defined periodic axial/radial profile in millimetres. */
-declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
+export declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects a caller-defined periodic profile. */
   readonly kind: "custom";
   /**
@@ -413,25 +430,13 @@ export declare type CylinderOptions = CircularPrimitiveOptions &
 export declare interface DiagnosticOptions<P> {
   /** Existing top-level parameter key. */
   readonly parameterId?: Extract<keyof P, string> | undefined;
+  /** Relative field path, at most 32 nonnegative safe indices or 1–120 character field names.
+   * Starts within parameterId's value, or the whole input map when no parameterId is supplied.
+   * Omitted or empty addresses the whole value; paths do not validate field existence.
+   */
+  readonly path?: readonly (string | number)[] | undefined;
 }
 
-/**
- * Measures the minimum separation between two nonempty solids in millimetres.
- *
- * Uses actual geometry, not bounding-box separation or distance between object origins.
- * Contact or overlapping material returns zero, including one solid inside another.
- * The kernel's search range is managed internally; the result is not capped at a caller limit.
- * Empty geometry and component selections from another session reject. Results follow native numeric precision.
- *
- * @example Measure the gap between two blocks
- * ```ts
- * const left = box({ size: 10 });
- * const right = box({ size: 10 }).translate([13, 0, 0]);
- * const gap = distance(left, right); // 3 mm
- * ```
- */
-export declare function distance(solid: Solid, other: Solid): number;
-
 /**
  * Uniform finishing vocabulary shared by applicable solid edges and profile corners.
  */
@@ -458,13 +463,13 @@ export declare type EllipseContourOptions = CircularPrimitiveOptions &
   (
     | {
         /** Positive XY radii in millimetres; mutually exclusive with size. */
-        readonly radius: Vector2Data;
+        readonly radius: Vector2Input;
         /** Full XY extents are unavailable when radius is supplied. */
         readonly size?: never;
       }
     | {
         /** Positive full XY extents in millimetres; mutually exclusive with radius. */
-        readonly size: Vector2Data;
+        readonly size: Vector2Input;
         /** XY radii are unavailable when size is supplied. */
         readonly radius?: never;
       }
@@ -488,8 +493,8 @@ export declare interface EndTreatments {
 }
 
 /**
- * Extrudes explicit corresponding contours along +Z with degree twist and top scaling.
- * Filled Sections use `section.extrude(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.
  *
  * @example Extrude
  * ```ts
@@ -501,24 +506,28 @@ export declare interface EndTreatments {
  * ```
  */
 export declare function extrude(
-  shape: CorrespondingProfile,
+  shape: Section | CorrespondingProfile,
   options: ExtrudeOptions,
 ): Solid;
 
 /**
- * Dimensions and sampling shared by native and pure +Z extrusion.
+ * Dimensions and sampling for pure +Z mesh extrusion, without end treatments.
  */
-export declare interface ExtrudeOptions extends ExtrusionSamplingOptions {
+export declare interface ExtrudeMeshOptions extends ExtrusionSamplingOptions {
   /** Positive extrusion height in millimetres. */
   readonly height: number;
   /** Center the extrusion on Z; otherwise its bottom is at zero. Defaults to false. */
   readonly center?: boolean;
+}
+
+/** Native +Z extrusion with optional inward end treatments. */
+export declare interface ExtrudeOptions extends ExtrudeMeshOptions {
   /** Independent inward end treatments on straight convex single-contour extrusions. */
   readonly ends?: EndTreatments;
 }
 
 /** Shared sampling controls for a twisted or scaled linear extrusion. */
-declare interface ExtrusionSamplingOptions {
+export declare interface ExtrusionSamplingOptions {
   /** Exact number of intermediate profiles, nonnegative; overrides physical sampling. */
   readonly divisions?: number;
   /** Explicit output and sampling allocation ceilings. */
@@ -531,43 +540,6 @@ declare interface ExtrusionSamplingOptions {
   readonly twist?: number;
 }
 
-/** Finalized manufacturing snapshot. Its arrays are independent of all native values. */
-export declare interface FinalizedModel {
-  /** Ordered finalized manufacturing parts with copied transferable arrays. */
-  readonly parts: readonly FinalizedPart[];
-  /** Axis-aligned XYZ bounds in millimetres. */
-  readonly bounds: Bounds3Data;
-  /** Aggregate counts, unique backing storage, volume, and execution timings. */
-  readonly stats: {
-    /** Number of declared output parts, including repeated geometry instances. */
-    readonly partCount: number;
-    /** Aggregate position-buffer vertex count. */
-    readonly vertexCount: number;
-    /** Aggregate indexed triangle count. */
-    readonly triangleCount: number;
-    /** Signed enclosed volume of all selected parts in cubic millimetres. */
-    readonly volumeMm3: number;
-    /** Unique transferable backing-buffer bytes, counted once across all parts. */
-    readonly byteCount: number;
-    /** Synchronous callback duration in milliseconds. */
-    readonly buildMs: number;
-    /** Manufacturing validation and buffer finalization duration in milliseconds. */
-    readonly finalizationMs: number;
-    /** Total generation duration, including cache retention and native cleanup, in milliseconds. */
-    readonly generationMs: number;
-  };
-}
-
-/** Copied manufacturing part with facts computed from the finalized mesh. */
-export declare interface FinalizedPart extends TriangleMesh {
-  /** Stable canonical lowercase identity; unique within the containing topology or output. */
-  readonly id: string;
-  /** Optional six-digit hex RGB display color. */
-  readonly color?: string;
-  /** Fresh validated facts for these exact finalized buffers. */
-  readonly measurements: TriangleMeshAnalysis;
-}
-
 /** A right-handed orthonormal coordinate frame expressed in world coordinates. */
 export declare interface Frame3 {
   /** World-space origin of the local frame. */
@@ -581,7 +553,9 @@ export declare interface Frame3 {
 }
 
 /**
- * Defines a typed model without executing it. Use `computed` only for work worth reusing.
+ * 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.
  *
  * @example A simple model
  * ```ts
@@ -591,19 +565,25 @@ export declare interface Frame3 {
  * });
  * ```
  */
-export declare function generate<P, S = Record<never, never>>(
+export declare function generate<P extends object, S = Record<never, never>>(
   callback: GenerateCallback<P, S>,
 ): ModelProgram<P, S>;
 
 /** Pure synchronous callback returning one declared part or an array; caches are optional. */
-export declare type GenerateCallback<P, S = Record<never, never>> = (
+export declare type GenerateCallback<
+  P extends object,
+  S = Record<never, never>,
+> = (
   context: GenerateContext<P, S>,
-) => GeneratedPart | readonly GeneratedPart[];
+) => PartDeclaration | readonly PartDeclaration[];
 
 /** The sole synchronous authoring context, supplied independently of Studio. */
-export declare interface GenerateContext<P, S = Record<never, never>> {
+export declare interface GenerateContext<
+  P extends object,
+  S = Record<never, never>,
+> {
   /** Frozen ordinary parameter values; synchronous top-level reads are tracked. */
-  readonly params: Readonly<P>;
+  readonly params: ImmutableValue<P>;
   /** Host-prepared readonly synchronous capabilities, fixed for the session. */
   readonly services: Readonly<S>;
   /**
@@ -617,11 +597,13 @@ export declare interface GenerateContext<P, S = Record<never, never>> {
     dependencies?: readonly unknown[],
   ) => Computed<T>;
   /** Declares a semantic part with identity placement, or explicit placement and appearance. */
-  readonly part: {
-    (id: string, geometry: ComputedValue<PartGeometry>): GeneratedPart;
-    (id: string, options: PartOptions): GeneratedPart;
-  };
-  /** Immediately aborts on false; geometry observations in the condition run first. */
+  readonly part: (
+    id: string,
+    input: ComputedValue<PartGeometry> | PartOptions,
+  ) => PartDeclaration;
+  /** Immediately aborts on false; geometry observations in the condition run first.
+   * This diagnostic helper does not narrow TypeScript types; use an explicit conditional guard when needed.
+   */
   readonly assert: {
     (condition: false, message: string, options?: DiagnosticOptions<P>): never;
     (condition: boolean, message: string, options?: DiagnosticOptions<P>): void;
@@ -630,12 +612,6 @@ export declare interface GenerateContext<P, S = Record<never, never>> {
   readonly warn: (message: string, options?: DiagnosticOptions<P>) => void;
 }
 
-/** One declared output part. Construct with the context's `part` helper. */
-export declare interface GeneratedPart extends PartOptions {
-  /** Unique canonical lowercase hyphen-separated identity, at most 64 characters. */
-  readonly id: string;
-}
-
 /** Structured user-facing issue associated with the attempted revision. */
 export declare interface GenerationDiagnostic {
   /** An error aborts generation; a warning allows generation to continue. */
@@ -644,6 +620,8 @@ export declare interface GenerationDiagnostic {
   readonly message: string;
   /** Optional control identity, validated against the supplied parameters. */
   readonly parameterId?: string | undefined;
+  /** Relative field location within the parameter, or input map when parameterId is omitted. */
+  readonly path?: readonly (string | number)[] | undefined;
 }
 
 /** A user-correctable assertion failure. Successful computation caches never retain failures. */
@@ -654,6 +632,60 @@ export declare class GenerationError extends Error {
   constructor(diagnostics: readonly GenerationDiagnostic[]);
 }
 
+/**
+ * Error raised when a geometry precondition or invariant is not satisfied.
+ *
+ * Callers may use `code` for coarse recovery decisions. Human-facing details
+ * remain in `message`; messages are descriptive but are not a stable API.
+ *
+ * @example
+ * ```ts
+ * const error = new GeometryError("INVALID_ARGUMENT", "Radius must be positive.", {
+ *   operation: "example",
+ *   details: { radius: 0 },
+ * });
+ * ```
+ */
+export declare class GeometryError extends Error {
+  /** Machine-readable failure category. */
+  readonly code: GeometryErrorCode;
+  /** Operation and scalar facts associated with the failure. */
+  readonly context: GeometryErrorContext;
+  /**
+   * Creates a geometry error with a stable category, operation, and descriptive message.
+   *
+   * @param code - Machine-readable failure category.
+   * @param message - Human-readable diagnostic message.
+   * @param context - Operation and optional scalar facts. Defaults to `{ operation: "geometry" }`.
+   */
+  constructor(
+    code: GeometryErrorCode,
+    message: string,
+    context?: GeometryErrorContext,
+  );
+}
+
+/** Stable categories for invalid inputs, topology, allocation, and runtime failures. */
+export declare type GeometryErrorCode =
+  | "COMPLEXITY_LIMIT"
+  | "DEGENERATE_GEOMETRY"
+  | "INVALID_ARGUMENT"
+  | "INVALID_MESH"
+  | "INVALID_TOPOLOGY"
+  | "INVALID_TOLERANCE"
+  | "NON_FINITE_VALUE"
+  | "SELF_INTERSECTION"
+  | "SINGULAR_TRANSFORM"
+  | "UNSUPPORTED_RUNTIME";
+
+/** Serializable context attached to a geometry failure. */
+export declare interface GeometryErrorContext {
+  /** Optional scalar facts useful for diagnostics without parsing the message. */
+  readonly details?: Readonly<Record<string, boolean | number | string>>;
+  /** Stable operation name, such as `normalizeContour` or `extrude`. */
+  readonly operation: string;
+}
+
 /**
  * Tessellation policy for sampled geometry measured in millimetres.
  */
@@ -777,11 +809,11 @@ export declare type HeightfieldOptions = {
 } & (
   | {
       /** Positive XY footprint for uniform sampling. */
-      readonly size: Vector2Data;
+      readonly size: Vector2Input;
       /** Exact positive integer X/Y interval counts. */
       readonly segments: readonly [x: number, y: number];
       /** Lower-left footprint XY. Omitted centers the footprint on XY. */
-      readonly origin?: Vector2Data;
+      readonly origin?: Vector2Input;
       /** Explicit coordinates cannot be combined with uniform sampling. */
       readonly coordinates?: never;
     }
@@ -805,45 +837,109 @@ export declare type HeightfieldOptions = {
     }
 );
 
-/** Runtime-neutral options for the dedicated helical ridge mesher. */
-export declare interface HelicalThreadRidgeMeshOptions {
-  /**
-   * Optional bottom/top ridge-end treatments. Standalone ridges honor the requested boundaries;
-   * BOSL2-style non-cut lead-in scaling is available on complete thread solids.
-   */
-  readonly ends?: ThreadEndTreatmentOptions;
-  /** Helix direction. Default: `right`. */
-  readonly handedness?: ThreadHandedness;
-  /** Total threaded axial length in millimetres. */
-  readonly length: number;
-  /** Explicit output and circular allocation ceilings. */
-  readonly limits?: Partial<ModelingLimits>;
-  /** Nominal major diameter before any caller-owned fit compensation. */
-  readonly majorDiameter: number;
-  /** Angular offset of the first start in degrees. Default: `0`. */
-  readonly phase?: number;
-  /** Validated periodic profile repeated around the shaft. */
-  readonly profile: ThreadProfile;
-  /** Optional circular-resolution policy. */
+/**
+ * Declares a +Z hole or blind-pocket cutter with explicit end overrun in millimetres.
+ *
+ * @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.
+ * Existing Section samples are authoritative; limits and unspecified circular sampling belong
+ * to the evaluating host.
+ *
+ * @example A blind hex pocket with an open top
+ * ```ts
+ * holeCutter({
+ *   profile: regularPolygon({ sides: 6, radius: 3.5, sizing: "face", rotation: 30 }),
+ *   height: 12, entryChamfer: 0.5, overrun: { top: 0.05 },
+ * });
+ * ```
+ */
+export declare function holeCutter(options: HoleCutterOptions): Solid;
+
+/**
+ * A deferred +Z hole or pocket cutter, with exactly one circular diameter or existing Section.
+ * Profile entry chamfers expand one strictly convex contour without holes by parallel-edge offsets;
+ * the supplied sampled boundary remains authoritative. Plain profile cutters accept any Section.
+ * Circular entry chamfers retain nominal circular/frustum radii under the selected radial sizing.
+ */
+export declare type HoleCutterOptions = {
+  /** Positive nominal depth along +Z, starting exactly at Z=0. */
+  readonly height: number;
+  /** Opening carrying the recess or entry chamfer; defaults to top. */
+  readonly face?: "bottom" | "top";
+  /** Extra length outside each nominal face; both ends default to zero. */
+  readonly overrun?: HoleCutterOverrun;
+  /** Operation-level physical sampling; an existing Section retains its sampled boundary. */
   readonly resolution?: GeometryResolution;
-  /** Number of evenly phased starts. Default: `1`. */
-  readonly starts?: number;
-  /** Optional numerical tolerance overrides. */
-  readonly tolerance?: GeometryToleranceOptions;
-}
+  /** Local allocation ceilings may only lower the evaluating host's limits. */
+  readonly limits?: Partial<ModelingLimits>;
+} & (
+  | (CircularPrimitiveOptions &
+      RadialSizingOptions & {
+        /** Positive nominal circular bore diameter in millimetres. */
+        readonly diameter: number;
+        /** Unavailable in this input form. */
+        readonly profile?: never;
+      } & (
+        | {
+            /** Nonnegative 45-degree entry setback; must be smaller than height. Defaults to zero. */
+            readonly entryChamfer?: number;
+            /** Unavailable in this input form. */
+            readonly recess?: never;
+          }
+        | {
+            /** Circular head seating; mutually exclusive with entryChamfer. */
+            readonly recess: HoleCutterRecess;
+            /** Unavailable in this input form. */
+            readonly entryChamfer?: never;
+          }
+      ))
+  | {
+      /** Local XY material to remove, retaining its position, orientation and physical sampling. */
+      readonly profile: Section;
+      /** Unavailable in this input form. */
+      readonly diameter?: never;
+      /** Unavailable in this input form. */
+      readonly recess?: never;
+      /** Unavailable in this input form. */
+      readonly segments?: never;
+      /** Unavailable in this input form. */
+      readonly sizing?: never;
+      /** Nonnegative 45-degree entry setback for a strictly convex single contour without holes. */
+      readonly entryChamfer?: number;
+    }
+);
 
-/** Selected sampling counts and conservative allocation estimates, before thread mesh construction. */
-export declare interface HelicalThreadSolidMeshPreflight {
-  /** Uniform axial intervals required only by a requested physical segment-length limit. */
-  readonly axialIntervals: number;
-  /** Start-aligned full-circle segment count used by the surface mesh. */
-  readonly circularSegments: number;
-  /** Conservative surface-row count across profile breaks, ends, and bevel stations. */
-  readonly estimatedRows: number;
-  /** Conservative triangle count used by the selected output allocation policy. */
-  readonly estimatedTriangles: number;
+/** Explicit extra cutter length outside the nominal Z=0..height interval, in millimetres. */
+export declare interface HoleCutterOverrun {
+  /** Extension below Z=0. Omitted means zero, preserving a blind pocket's floor. */
+  readonly bottom?: number;
+  /** Extension above Z=height. Omitted means zero. */
+  readonly top?: number;
 }
 
+/** Circular screw seating dimensions in millimetres; allowances belong to the caller. */
+export declare type HoleCutterRecess =
+  | {
+      /** Cylindrical seat. */
+      readonly kind: "counterbore";
+      /** Positive seat diameter greater than the bore, in millimetres. */
+      readonly diameter: number;
+      /** Positive seat depth no greater than height, in millimetres. */
+      readonly depth: number;
+    }
+  | {
+      /** Conical seat. */
+      readonly kind: "countersink";
+      /** Positive mouth diameter greater than the bore, in millimetres. */
+      readonly diameter: number;
+      /** Full included angle strictly between zero and 180 degrees; derived depth must fit height. */
+      readonly includedAngle: number;
+    };
+
 /**
  * Convex hull of points or solids.
  *
@@ -874,18 +970,6 @@ export declare type HullOptions =
       readonly points?: never;
     };
 
-/** Owned immutable numeric data. Use copy() to obtain mutable storage for numerical work. */
-export declare interface ImmutableBuffer<T extends NumericArray> {
-  /** Opaque element-storage brand; construct buffers with immutableBuffer(). */
-  readonly [immutableBufferBrand]: T;
-  /** Number of numeric elements, independent of their byte width. */
-  readonly length: number;
-  /** Reads an integer offset; negative offsets count from the end. Invalid offsets return undefined. */
-  at(this: void, index: number): number | undefined;
-  /** Returns a fresh mutable array of the original numeric type; never exposes cached storage. */
-  copy(this: void): T;
-}
-
 /**
  * Copies numeric data once into private storage. This pure helper needs no active generation.
  * @example
@@ -894,6 +978,7 @@ export declare interface ImmutableBuffer<T extends NumericArray> {
  * const heights = immutableBuffer(new Float32Array([2, 4, 6]));
  * const count = heights.length;
  * const first = heights.at(0);
+ * const doubled = Array.from(heights, (height) => height * 2);
  * const editable = heights.copy();
  * editable[0] = 8; // heights still contains 2, 4, 6.
  * ```
@@ -902,33 +987,18 @@ export declare function immutableBuffer<T extends NumericArray>(
   source: T,
 ): ImmutableBuffer<T>;
 
-declare const immutableBufferBrand: unique symbol;
-
 /**
- * Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
- * @example
- * ```ts
- * import { generate, immutableMesh } from "@metamesh/modeling";
- * import { heightfieldMesh } from "@metamesh/modeling/geometry";
- * const model = generate(({ computed, part }) => {
- *   const surface = computed("surface", () => immutableMesh(heightfieldMesh({
- *     size: [10, 10], segments: [8, 8], height: () => 2,
- *   })));
- *   return [part("surface", surface)];
- * });
- * ```
+ * Deeply readonly view of captured generation data, including nested arrays and tuples.
+ * Modeling value methods keep their signatures, including explicit mutable copies.
+ * This type does not make unsupported runtime values valid generation data.
  */
-export declare function immutableMesh(
-  mesh: TriangleMesh,
-): ImmutableTriangleMesh;
-
-/** Immutable local XYZ positions and triangle indices, suitable for a computed value or part. */
-export declare interface ImmutableTriangleMesh {
-  /** Packed XYZ coordinates in millimetres. */
-  readonly positions: ImmutableBuffer<Float32Array>;
-  /** Zero-based vertex indices, three per triangle. */
-  readonly indices: ImmutableBuffer<Uint32Array>;
-}
+export declare type ImmutableValue<T> = T extends (...args: never[]) => unknown
+  ? T
+  : T extends object
+    ? {
+        readonly [Key in keyof T]: ImmutableValue<T[Key]>;
+      }
+    : T;
 
 /**
  * Bounded positive-inside implicit field constructor.
@@ -950,28 +1020,6 @@ export declare interface ImplicitOptions {
   readonly tolerance?: number;
 }
 
-/**
- * Copies lightweight section measurements.
- *
- * @example Check filled area
- * ```ts
- * const facts = inspectSection(rectangle({ size: [20, 10] }));
- * facts.area; // 200 mm²
- * ```
- */
-export declare function inspectSection(section: Section): SectionInspection;
-
-/**
- * Reads immutable native facts once per solid; 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³
- * ```
- */
-export declare function inspectSolid(solid: Solid): SolidInspection;
-
 /**
  * Compensated internal threaded cutter.
  *
@@ -991,9 +1039,7 @@ export declare function internalThreadCutter(
 
 /** Options for a compensated internal-thread subtraction tool along +Z. */
 export declare interface InternalThreadCutterOptions
-  extends
-    Omit<HelicalThreadRidgeMeshOptions, "majorDiameter">,
-    ThreadBevelOptions {
+  extends Omit<ThreadRidgeOptions, "majorDiameter">, ThreadBevelOptions {
   /** Printable fit or caller-calibrated allowances. Default: `normal`. */
   readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
   /** Nominal major diameter before female compensation and faceting correction. */
@@ -1001,7 +1047,7 @@ export declare interface InternalThreadCutterOptions
 }
 
 /**
- * Robust intersection.
+ * Robust intersection of one or more shapes; empty input rejects during declaration.
  *
  * @example Intersect
  * ```ts
@@ -1014,20 +1060,12 @@ export declare function intersect(solids: readonly Solid[]): Solid;
 export declare function intersect(sections: readonly Section[]): Section;
 
 /**
- * Checks whether a solid or filled section contains no geometry during host execution.
+ * Recognizes structured geometry errors from separately bundled Modeling copies in the same realm.
  *
- * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
- * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
- *
- * @example Check a missed intersection
- * ```ts
- * const body = box({ size: 10 });
- * const distant = box({ size: 10 }).translate([30, 0, 0]);
- * const empty = intersect([body, distant]);
- * const missed = isEmpty(empty); // true
- * ```
+ * Ordinary errors and unmarked code-shaped objects are rejected. The marker is execution-local and
+ * does not survive structured cloning; worker protocols carry their own serialized error envelope.
  */
-export declare function isEmpty(shape: Solid | Section): boolean;
+export declare function isGeometryError(value: unknown): value is GeometryError;
 
 /** Portable local geometry; consumers own plates, holes, part declarations, and final placement. */
 export declare interface KnuckleHinge {
@@ -1046,10 +1084,10 @@ export declare interface KnuckleHinge {
  * otherwise disconnected intervals. Returns portable recipes without initializing the engine.
  * Unspecified resolution inherits the evaluating session. Axis direction is +X with +Z up.
  *
- * Barrel end chamfers affect outer rims only; webs have square edges. Consumers own plates, screw holes,
+ * 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 8.0.0 or newer in major 8.
+ * 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
@@ -1081,20 +1119,26 @@ export declare interface KnuckleHingeBaseSpec {
   readonly axialGap: number;
 }
 
-/** Optional mounting and outer-rim treatment for one knuckle owner. */
+/** Optional mounting and edge treatment for one knuckle owner. */
 export declare interface KnuckleHingeHalfOptions {
   /** Omit for barrels only. Each interval receives one web; disconnected intervals need caller geometry. */
   readonly web?: KnuckleHingeWeb;
-  /** 45° setback in millimetres at both ends of every barrel; defaults to 0. */
-  readonly barrelChamfer?: number;
+  /**
+   * Nonnegative 45° setback in millimetres on barrel outer rims and exposed web edges; defaults to 0.
+   * The root at the pin centreline stays square so its faces can merge with the barrel.
+   *
+   * Must leave a positive barrel wall and axial band. Web thickness must exceed twice the setback;
+   * web reach and knuckle length must exceed `2 * Math.SQRT2 * chamfer` to retain the end contours.
+   */
+  readonly chamfer?: number;
 }
 
 /** Joint declaration with independent attachments; unspecified sampling inherits the evaluating host. */
 export declare type KnuckleHingeOptions = KnuckleHingeSpec &
   KnuckleHingeSamplingOptions & {
-    /** Optional attachment and rim treatment for A, which owns an integral pin when present. */
+    /** Optional attachment and edge treatment for A, which owns an integral pin when present. */
     readonly halfA?: KnuckleHingeHalfOptions;
-    /** Optional attachment and rim treatment for B, which always carries a running bore. */
+    /** Optional attachment and edge treatment for B, which always carries a running bore. */
     readonly halfB?: KnuckleHingeHalfOptions;
   };
 
@@ -1141,7 +1185,7 @@ export declare interface KnuckleHingeWeb {
   readonly reach: number;
   /** Lower-face Z coordinate in the pin-centered frame, in millimetres. Must overlap the barrel's interior. */
   readonly zMin: number;
-  /** Positive thickness along +Z. Webs have square edges and span their own barrel intervals. */
+  /** Positive thickness along +Z. Each web spans its own barrel interval. */
   readonly thickness: number;
 }
 
@@ -1199,7 +1243,8 @@ export declare type LinearPatternOptions<Dimension extends 2 | 3 = 3> = {
 );
 
 /**
- * Lofts primitive Sections at z heights or frames; arbitrary Sections and loops require an explicit correspondence method.
+ * Lofts Sections and point loops at z heights or frames. Known primitive landmarks are retained;
+ * other profiles default to direct correspondence, preserving their supplied seams.
  *
  * @example Loft
  * ```ts
@@ -1237,10 +1282,10 @@ 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 default to direct 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. */
+  /** One method or one per consecutive station gap. Omitted preserves known primitive landmarks, including circle/ellipse-to-rectangle corners, and otherwise uses direct correspondence with the supplied seams. */
   readonly correspondence?: LoftCorrespondence | readonly LoftCorrespondence[];
   /** Extra points follow edge length or distribute equally across existing segments. Defaults to perimeter for direct/reindex, or segments when any distance method is selected; distance methods require segments. */
   readonly distribution?: "perimeter" | "segments";
@@ -1312,16 +1357,21 @@ export declare interface ModelingLimits extends GeometrySamplingLimits {
 }
 
 /** Stateless portable program descriptor. Execution and caches belong to an engine session. */
-export declare interface ModelProgram<P, S = Record<never, never>> {
+export declare interface ModelProgram<
+  P extends object,
+  S = Record<never, never>,
+> {
   /** Exact generation protocol discriminator. */
   readonly kind: "metamesh-model";
   /** Typed synchronous declaration callback. */
   readonly generate: GenerateCallback<P, S>;
 }
 
-/** Numeric storage supported by immutable generation buffers. */
-export declare type NumericArray =
-  Float32Array | Float64Array | Uint32Array | Uint8Array | Int32Array;
+/** One declared output part. Construct with the context's `part` helper. */
+export declare interface PartDeclaration extends PartOptions {
+  /** Unique canonical lowercase hyphen-separated identity, at most 64 characters. */
+  readonly id: string;
+}
 
 /** Manufacturing geometry; filled sections are intermediate construction values. */
 export declare type PartGeometry = Solid | TriangleMesh | ImmutableTriangleMesh;
@@ -1330,10 +1380,10 @@ export declare type PartGeometry = Solid | TriangleMesh | ImmutableTriangleMesh;
 export declare interface PartOptions {
   /** Local geometry or a lazy reader; native objects never cross a revision. */
   readonly geometry: ComputedValue<PartGeometry>;
-  /** XYZ vector or tuple translation in millimetres, applied after rotation; defaults to zero. */
-  readonly position?: ComputedValue<Vector3Input>;
-  /** XYZ vector or tuple of fixed global X, Y, Z rotations in degrees; defaults to zero. */
-  readonly rotation?: ComputedValue<Vector3Input>;
+  /** Rigid local-to-world transform; translation uses millimetres. Defaults to identity.
+   * Accepts a fluent transform or row-major 4x4 matrix. Scale, shear, and reflection are invalid.
+   */
+  readonly transform?: ComputedValue<Transform3Input>;
   /** Optional six-digit hexadecimal semantic part color. */
   readonly color?: string;
 }
@@ -1609,7 +1659,7 @@ export declare type PolygonOptions =
  */
 export declare function preflightInternalThreadCutter(
   options: InternalThreadCutterOptions,
-): HelicalThreadSolidMeshPreflight;
+): ThreadSolidPreflight;
 
 /**
  * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
@@ -1635,7 +1685,7 @@ export declare function preflightThreadedNut(
  */
 export declare function preflightThreadedRod(
   options: ThreadedRodOptions,
-): HelicalThreadSolidMeshPreflight;
+): ThreadSolidPreflight;
 
 /** Anchor attachment shared by solid and filled-section factories. */
 export declare interface PrimitiveAttachment {
@@ -1834,7 +1884,7 @@ export declare function rectangle(options: RectangleOptions): Section;
  */
 export declare interface RectangleContourOptions {
   /** Positive uniform size or explicit XY extents in millimetres. */
-  readonly size: number | Vector2Data;
+  readonly size: number | Vector2Input;
   /** Center on XY; otherwise the minimum corner is the origin. Defaults to true. */
   readonly center?: boolean;
   /** Uniform treatment or four corner treatments. Exact round segments describe a complete circle and must divide by four. */
@@ -1897,8 +1947,8 @@ export declare type RegularPolygonOptions = RadialSizingOptions &
   };
 
 /**
- * Revolves explicit corresponding radial/Z contours around +Z, with caps for partial sweeps.
- * Filled Sections use `section.revolve(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.
  *
  * @example Revolve
  * ```ts
@@ -1911,7 +1961,7 @@ export declare type RegularPolygonOptions = RadialSizingOptions &
  * ```
  */
 export declare function revolve(
-  shape: CorrespondingProfile,
+  shape: Section | CorrespondingProfile,
   options?: RevolveOptions,
 ): Solid;
 
@@ -1924,7 +1974,7 @@ export declare interface RevolveOptions extends CircularPrimitiveOptions {
    * smaller sweeps form partial revolutions with end caps.
    * Segment counts describe a complete circle and scale to this angular span. Native filled
    * revolutions require at least three sweep intervals: adaptive sampling refines to that floor,
-   * while exact counts that imply fewer intervals reject. Pure revolveMesh supports one interval.
+   * while exact counts that imply fewer intervals reject. Pure mesh.revolve supports one interval.
    * @defaultValue `360`
    */
   readonly degrees?: number;
@@ -1955,7 +2005,7 @@ export declare interface RoundedEdgeTreatment extends CircularPrimitiveOptions {
  * @example Extrude an outline with a border
  * ```ts
  * const body = rectangle({ size: [20, 12] })
- *   .subtract([rectangle({ size: [16, 8] })])
+ *   .subtract(rectangle({ size: [16, 8] }))
  *   .offset(0.5)
  *   .extrude({ height: 4 });
  * ```
@@ -1985,8 +2035,14 @@ export declare interface Section {
   transform(this: Section, placement: Transform2Input): Section;
   /** Copies canonical filled polygons for interchange; requires an active model execution. */
   toRegionData(this: Section): RegionData;
-  /** Native section difference; an empty cutter array preserves the source. */
-  subtract(this: Section, cutters: readonly Section[]): Section;
+  /** Filled union with one or more sections; an empty operand array preserves this section. */
+  union(this: Section, operands: Section | readonly Section[]): Section;
+  /** Filled intersection with every supplied section; an empty operand array preserves this section. */
+  intersect(this: Section, operands: Section | readonly Section[]): Section;
+  /** Filled difference removing one cutter or the union of all supplied cutters.
+   * An empty cutter array preserves this section.
+   */
+  subtract(this: Section, cutters: Section | readonly Section[]): Section;
   /**
    * Simplifies filled 2D contours using an explicit positive millimetre tolerance.
    *
@@ -2021,6 +2077,19 @@ export declare interface Section {
    * Sweeps this filled section using the selected frame policy and degree twist.
    */
   sweep(this: Section, path: Path3Input, options?: SweepOptions): Solid;
+  /** Reads immutable bounds, filled area in mm², and component/contour/vertex counts.
+   * Requires active synchronous model execution; repeated reads share scoped native results.
+   */
+  inspect(this: Section): SectionInspection;
+  /** Checks whether this section contains no filled geometry during active synchronous model execution. */
+  isEmpty(this: Section): boolean;
+  /** Observes filled XY islands, retaining each island's holes; empty geometry gives [].
+   * Requires active synchronous model execution. Selection order is unspecified.
+   * Selections and recipes using them can only be evaluated in this session.
+   */
+  components(this: Section): readonly Section[];
+  /** Reads a copied immutable named anchor during active synchronous model execution. */
+  anchor(this: Section, name: string): Anchor3;
 }
 
 declare const sectionBrand: unique symbol;
@@ -2051,10 +2120,8 @@ export declare interface SectionInspection {
   readonly area: number;
   /** Number of extracted outer and hole contours. */
   readonly contourCount: number;
-  /** Inclusive maximum coordinates in millimetres. */
-  readonly max: Vector2Data;
-  /** Inclusive minimum coordinates in millimetres. */
-  readonly min: Vector2Data;
+  /** Immutable axis-aligned XY bounds in millimetres. */
+  readonly bounds: Bounds2Data;
   /** Number of disconnected filled section components. */
   readonly componentCount: number;
   /** Number of native section vertices. */
@@ -2103,7 +2170,7 @@ export declare interface SmoothEdgeTreatment {
  * @example Shape a body with a through bore
  * ```ts
  * const body = box({ size: [30, 20, 6] })
- *   .subtract([cylinder({ height: 8, radius: 3 })])
+ *   .subtract(cylinder({ height: 8, radius: 3 }))
  *   .rotate([0, 0, 45]);
  * ```
  */
@@ -2134,12 +2201,19 @@ export declare interface Solid {
   mirror(this: Solid, normal: Vector3Input): Solid;
   /** Applies a reusable XYZ placement or canonical row-major matrix. */
   transform(this: Solid, placement: Transform3Input): Solid;
-  /** Copies manufacturing mesh buffers for interchange; requires an active model execution. */
-  toTriangleMesh(this: Solid): TriangleMesh;
+  /** Copies indexed Float32 XYZ and Uint32 triangle buffers in millimetres for interchange.
+   * Requires an active synchronous model execution; the returned TriangleMesh is caller-owned.
+   */
+  toMesh(this: Solid): TriangleMesh;
+  /** Robust union with one or more solids; an empty operand array preserves this solid. */
+  union(this: Solid, operands: Solid | readonly Solid[]): Solid;
+  /** Robust intersection with every supplied solid; an empty operand array preserves this solid. */
+  intersect(this: Solid, operands: Solid | readonly Solid[]): Solid;
   /**
-   * Robust difference; an empty cutter array preserves the source.
+   * Robust difference removing one cutter or the union of all supplied cutters.
+   * An empty cutter array preserves this solid.
    */
-  subtract(this: Solid, cutters: readonly Solid[]): Solid;
+  subtract(this: Solid, cutters: Solid | readonly Solid[]): Solid;
   /**
    * Simplifies a solid using an explicit positive millimetre tolerance.
    *
@@ -2166,6 +2240,42 @@ export declare interface Solid {
   projectSection(this: Solid): Section;
   /** Takes a filled horizontal slice at Z millimetres. */
   sliceSection(this: Solid, z: number): Section;
+  /** Reads immutable bounds, volume in mm³, surface area in mm², and material-component count.
+   * Requires active synchronous model execution; repeated reads share scoped native results.
+   */
+  inspect(this: Solid): SolidInspection;
+  /** Checks whether this solid contains no geometry during active synchronous model execution. */
+  isEmpty(this: Solid): boolean;
+  /** Observes disconnected material pieces, retaining each piece's enclosed cavities.
+   * Requires active synchronous model execution. Empty geometry gives []; order is unspecified.
+   * Selections and recipes using them can only be evaluated in this session.
+   * Containment is bounded to 2,000,000 comparisons; this does not cut connected geometry.
+   */
+  components(this: Solid): readonly Solid[];
+  /** Reads a copied immutable named anchor during active synchronous model execution. */
+  anchor(this: Solid, name: string): Anchor3;
+  /** Measures actual minimum separation in millimetres during active synchronous model execution.
+   * Contact or overlapping material gives zero; empty geometry and cross-session selections reject.
+   * The kernel manages its search range; results follow native numeric precision.
+   */
+  distance(this: Solid, other: Solid): number;
+  /** Copies intersections along the finite directed origin-to-endpoint segment in millimetres.
+   * Requires active synchronous model execution.
+   */
+  castSegment(
+    this: Solid,
+    origin: Vector3Input,
+    endpoint: Vector3Input,
+  ): readonly SolidSegmentHit[];
+  /** Splits into [inside the cutter, outside the cutter]; the cutter itself is not returned.
+   * Either result may be empty or contain multiple disconnected components.
+   */
+  split(this: Solid, cutter: Solid): readonly [Solid, Solid];
+  /** Splits into [positive-normal side, negative side] with closed cut faces.
+   * The nonzero normal is normalized; offset is its signed distance from the origin in millimetres.
+   * Offset defaults to zero. Either result may be empty.
+   */
+  splitByPlane(this: Solid, plane: PlaneOptions): readonly [Solid, Solid];
 }
 
 declare const solidBrand: unique symbol;
@@ -2176,10 +2286,11 @@ declare const solidBrand: unique symbol;
  * @example Mesh import
  * ```ts
  * import { solidFromMesh } from "@metamesh/modeling";
- * import { extrudeMesh, rectangleContour } from "@metamesh/modeling/geometry";
+ * import * as mesh from "@metamesh/modeling/geometry/mesh";
+ * import { rectangleContour } from "@metamesh/modeling/geometry";
  *
- * const mesh = extrudeMesh(rectangleContour({ size: [20, 12] }), { height: 6 });
- * solidFromMesh(mesh);
+ * const plate = mesh.extrude(rectangleContour({ size: [20, 12] }), { height: 6 });
+ * solidFromMesh(plate);
  * ```
  */
 export declare function solidFromMesh(
@@ -2193,10 +2304,8 @@ export declare function solidFromMesh(
 export declare interface SolidInspection {
   /** Whether this native solid contains no material. */
   readonly isEmpty: boolean;
-  /** Inclusive maximum coordinates in millimetres. */
-  readonly max: Vector3Data;
-  /** Inclusive minimum coordinates in millimetres. */
-  readonly min: Vector3Data;
+  /** Immutable axis-aligned XYZ bounds in millimetres. */
+  readonly bounds: Bounds3Data;
   /** Number of disconnected material components, each retaining enclosed cavities. */
   readonly componentCount: number;
   /** Enclosed native solid volume in cubic millimetres. */
@@ -2249,54 +2358,8 @@ export declare type SphereOptions = CircularPrimitiveOptions &
       }
   );
 
-/**
- * Splits a solid into [inside the cutter, outside the cutter].
- *
- * The first result is the intersection; the second is the subtraction. The cutter itself
- * is not returned. Either result may be empty or contain multiple disconnected components.
- *
- * @example Keep the plug and the surrounding body
- * ```ts
- * const body = box({ size: [30, 20, 8] });
- * const cutter = cylinder({ height: 10, diameter: 8 });
- * const [plug, remainder] = split(body, cutter);
- * // Move the plug beside the body to show both results.
- * union([plug.translate([0, -20, 0]), remainder]);
- * ```
- */
-export declare function split(
-  solid: Solid,
-  cutter: Solid,
-): readonly [Solid, Solid];
-
-/**
- * Splits a solid into [positive-normal side, negative side] at a world-space plane.
- *
- * The nonzero normal is normalized; offset is the signed distance from the origin in
- * millimetres, defaulting to zero. Both cut faces are closed. Select either tuple result
- * to retain one side; either result may be empty.
- *
- * @example Separate two halves at X = 0
- * ```ts
- * const body = box({ size: [30, 20, 8] });
- * const [right, left] = splitByPlane(body, { normal: [1, 0, 0] });
- * // The gap is only for display; the cut itself removes no material.
- * union([right.translate([4, 0, 0]), left.translate([-4, 0, 0])]);
- * ```
- *
- * @example Keep only the positive half
- * ```ts
- * const [right] = splitByPlane(box({ size: [30, 20, 8] }), { normal: [1, 0, 0] });
- * right;
- * ```
- */
-export declare function splitByPlane(
-  solid: Solid,
-  plane: PlaneOptions,
-): readonly [Solid, Solid];
-
 /** Square profile with equal crest and root widths. */
-declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
+export declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects the square profile family. */
   readonly kind: "square";
   /**
@@ -2316,22 +2379,26 @@ declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
  */
 export declare function star(options: StarOptions): Section;
 
-/**
- * Alternating outer and inner vertices, centered on the XY origin.
- */
-export declare interface StarOptions extends PrimitiveAttachment {
-  /** Explicit sampling ceilings, bounded by the host policy. */
-  readonly limits?: Partial<GeometrySamplingLimits>;
+/** Alternating vertex radii and exact point count for a centered XY star. */
+export declare interface StarContourOptions {
   /** Positive outer vertex radius in millimetres. */
   readonly outerRadius: number;
-  /** Positive inner vertex radius, smaller than the outer radius. */
+  /** Positive inner vertex radius in millimetres, smaller than the outer radius. */
   readonly innerRadius: number;
-  /** Integer outer point count from three through 50000. */
+  /** Integer outer point count, at least three; output contains twice as many vertices. */
   readonly points: number;
-  /** Initial counterclockwise rotation in degrees; defaults to zero. */
+  /** Counterclockwise rotation in degrees; defaults to zero with an outer vertex on +X. */
   readonly rotation?: number;
+  /** Explicit sampling ceilings, bounded by the host policy during modeling. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
 }
 
+/**
+ * Alternating outer and inner vertices, centered on the XY origin.
+ */
+export declare interface StarOptions
+  extends StarContourOptions, PrimitiveAttachment {}
+
 /**
  * Creates a centered-width native Section along a sampled XY path.
  *
@@ -2421,6 +2488,8 @@ export declare function svgSection(
  * Bounded SVG document sampling. Center origin uses the final painted bounds.
  */
 export declare interface SvgSectionOptions {
+  /** Fit painted bounds uniformly inside positioned XY millimetre bounds; adaptive resolution applies at the fitted size. */
+  readonly fit?: Bounds2Input;
   /** Local allocation ceilings may only lower the configured engine policy. */
   readonly limits?: Partial<GeometrySamplingLimits>;
   /** Exact circular tessellation count overriding physical sampling. */
@@ -2432,8 +2501,8 @@ export declare interface SvgSectionOptions {
 }
 
 /**
- * Sweeps explicit corresponding contours using the selected frame policy.
- * Filled Sections use `section.sweep(path, 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
@@ -2447,7 +2516,7 @@ export declare interface SvgSectionOptions {
  * ```
  */
 export declare function sweep(
-  shape: CorrespondingProfile,
+  shape: Section | CorrespondingProfile,
   path: Path3Input,
   options?: SweepOptions,
 ): Solid;
@@ -2527,17 +2596,11 @@ export declare interface TextSectionOptions {
   readonly resolution?: GeometryResolution;
 }
 
-/** End bevel controls shared by threaded rods and cutters. */
-declare interface ThreadBevelOptions {
-  /** Apply a 45-degree bevel at Z=0. */
-  readonly bevelBottom?: boolean;
-  /**
-   * Axial bevel extent in millimetres. Active blunt ends default to one sixth of the compensated
-   * male minor radius or female major radius; other ends default to the profile depth.
-   */
-  readonly bevelSize?: number;
-  /** Apply a 45-degree bevel at Z=length. */
-  readonly bevelTop?: boolean;
+/** 45-degree end bevels for compensated rods and cutters. */
+export declare interface ThreadBevelOptions {
+  /** Bottom/top sizes in millimetres. Omitted disables both. Auto uses profile depth for standard/tapered ends,
+   * or one sixth of the compensated male minor/female major radius for blunt ends. */
+  readonly bevel?: Bevel;
 }
 
 /**
@@ -2554,25 +2617,20 @@ declare interface ThreadBevelOptions {
  */
 export declare function threadedNut(options: ThreadedNutOptions): Solid;
 
-/** Nut-edge bevel selection. */
-export declare type ThreadedNutBevel =
-  "automatic" | "both" | "inside" | "none" | "outside";
-
 /**
  * Options for a compensated nut with an internal thread.
  */
 export declare interface ThreadedNutOptions extends Omit<
   InternalThreadCutterOptions,
-  "bevelBottom" | "bevelSize" | "bevelTop" | "length"
+  "bevel" | "length"
 > {
-  /** Nut body bevel selection. Default: `automatic`. */
-  readonly bevel?: ThreadedNutBevel;
+  /** Opening bevels in [bottom, top] order. Omitted or auto uses min(profile.depth, thickness/4); zero disables. */
+  readonly innerBevel?: Bevel;
+  /** Body bevels in [bottom, top] order. Omitted or auto uses min(profile.depth, thickness/4).
+   * Use [0, "auto"] to keep the outside bottom flat without disabling its inner opening bevel. */
+  readonly outerBevel?: Bevel;
   /** Optional physical policy for a round body, independent of the thread's matched facet grid. */
   readonly bodyResolution?: GeometryResolution;
-  /** 45-degree body chamfer extent. Default: `min(profile.depth, thickness/4)`. */
-  readonly chamferSize?: number;
-  /** Leave the bottom outside edge flat for build-plate adhesion. Default: `false`. */
-  readonly flushBuildPlateBottom?: boolean;
   /** Nut body shape. */
   readonly shape: ThreadedNutShape;
   /** Nut thickness along +Z in millimetres. */
@@ -2585,8 +2643,10 @@ export declare interface ThreadedNutOptions extends Omit<
 export declare interface ThreadedNutPreflight {
   /** Polygon segment count used by the nut body. */
   readonly bodySegments: number;
-  /** Shared 45-degree chamfer size applied to the selected body and cutter edges. */
-  readonly chamferSize: number;
+  /** Resolved opening bevel sizes in millimetres, [bottom, top]. */
+  readonly innerBevel: readonly [bottom: number, top: number];
+  /** Resolved body bevel sizes in millimetres, [bottom, top]. */
+  readonly outerBevel: readonly [bottom: number, top: number];
   /** Maximum compensated cutter radius at either requested face. */
   readonly cutterFaceRadius: number;
   /** Minimum nut-body inradius across the requested top and bottom faces. */
@@ -2594,7 +2654,7 @@ export declare interface ThreadedNutPreflight {
   /** Smallest radial wall left between the body and cutter at either requested face. */
   readonly minimumFaceWall: number;
   /** Conservative allocation estimates for the extended cutter; excludes the body and Boolean result. */
-  readonly thread: HelicalThreadSolidMeshPreflight;
+  readonly thread: ThreadSolidPreflight;
   /** Start-aligned circular facet count used by the compensated thread cutter. */
   readonly threadCircularSegments: number;
 }
@@ -2622,9 +2682,7 @@ export declare function threadedRod(options: ThreadedRodOptions): Solid;
  * Options for a compensated external threaded rod along +Z.
  */
 export declare interface ThreadedRodOptions
-  extends
-    Omit<HelicalThreadRidgeMeshOptions, "majorDiameter">,
-    ThreadBevelOptions {
+  extends Omit<ThreadRidgeOptions, "majorDiameter">, ThreadBevelOptions {
   /** Printable fit or caller-calibrated allowances. Default: `normal`. */
   readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
   /** Nominal major diameter before male compensation. */
@@ -2701,7 +2759,7 @@ export declare interface ThreadProfile {
 }
 
 /** Fields shared by all thread profile specifications. */
-declare interface ThreadProfileBaseSpec {
+export declare interface ThreadProfileBaseSpec {
   /** Adjacent axial thread spacing in millimetres. */
   readonly pitch: number;
   /** Optional numerical tolerance overrides. */
@@ -2711,7 +2769,7 @@ declare interface ThreadProfileBaseSpec {
 /**
  * Supported built-in and caller-defined thread profiles.
  */
-declare type ThreadProfileSpec =
+export declare type ThreadProfileSpec =
   | AcmeThreadProfileSpec
   | ButtressThreadProfileSpec
   | CustomThreadProfileSpec
@@ -2722,8 +2780,44 @@ declare type ThreadProfileSpec =
 /** Helical ridge mesh construction. */
 export declare function threadRidge(options: ThreadRidgeOptions): Solid;
 
-/** Parameters for a helical ridge before solid construction. */
-export declare type ThreadRidgeOptions = HelicalThreadRidgeMeshOptions;
+/** Runtime-neutral options for the dedicated helical ridge mesher. */
+export declare interface ThreadRidgeOptions {
+  /**
+   * Optional bottom/top ridge-end treatments. Standalone ridges honor the requested boundaries;
+   * BOSL2-style non-cut lead-in scaling is available on complete thread solids.
+   */
+  readonly ends?: ThreadEndTreatmentOptions;
+  /** Helix direction. Default: `right`. */
+  readonly handedness?: ThreadHandedness;
+  /** Total threaded axial length in millimetres. */
+  readonly length: number;
+  /** Explicit output and circular allocation ceilings. */
+  readonly limits?: Partial<ModelingLimits>;
+  /** Nominal major diameter before any caller-owned fit compensation. */
+  readonly majorDiameter: number;
+  /** Angular offset of the first start in degrees. Default: `0`. */
+  readonly phase?: number;
+  /** Validated periodic profile repeated around the shaft. */
+  readonly profile: ThreadProfile;
+  /** Optional circular-resolution policy. */
+  readonly resolution?: GeometryResolution;
+  /** Number of evenly phased starts. Default: `1`. */
+  readonly starts?: number;
+  /** Optional numerical tolerance overrides. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
+/** Selected sampling counts and conservative allocation estimates, before thread mesh construction. */
+export declare interface ThreadSolidPreflight {
+  /** Uniform axial intervals required only by a requested physical segment-length limit. */
+  readonly axialIntervals: number;
+  /** Start-aligned full-circle segment count used by the surface mesh. */
+  readonly circularSegments: number;
+  /** Conservative surface-row count across profile breaks, ends, and bevel stations. */
+  readonly estimatedRows: number;
+  /** Conservative triangle count used by the selected output allocation policy. */
+  readonly estimatedTriangles: number;
+}
 
 /**
  * Torus around +Z.
@@ -2891,7 +2985,7 @@ export declare type Transform3Data = readonly [
 export declare type Transform3Input = Transform3 | Transform3Data;
 
 /** Trapezoidal thread profile with a configurable included angle. */
-declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
+export declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects the trapezoidal profile family. */
   readonly kind: "trapezoidal";
   /**
@@ -2907,13 +3001,11 @@ declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
   readonly includedAngle?: number;
 }
 
-/**
- * A topology-preserving indexed triangle mesh with XYZ vertex positions.
- */
+/** A topology-preserving indexed triangle mesh with mutable owned XYZ buffers. */
 export declare interface TriangleMesh {
   /** Three unsigned vertex indices per triangle. */
   readonly indices: Uint32Array;
-  /** Flat XYZ coordinates, three finite values per vertex. */
+  /** Flat XYZ coordinates in millimetres. */
   readonly positions: Float32Array;
 }
 
@@ -2921,8 +3013,9 @@ export declare interface TriangleMesh {
  * Measurements and optional edge-connected topology from one validated mesh traversal.
  */
 export declare interface TriangleMeshAnalysis extends TriangleMeshMeasurements {
-  /** Number of referenced edge-connected boundary shells when `includeTopology` is requested; cavities count separately. */
-  readonly connectedComponentCount?: number;
+  /** Number of surface shells connected by shared indexed edges when includeTopology is requested.
+   * Cavities count separately; shells may be open unless requireClosed is enabled. Coordinates are not welded. */
+  readonly shellCount?: number;
   /** Number of distinct indexed undirected edges when `includeTopology` is requested. */
   readonly edgeCount?: number;
 }
@@ -2943,10 +3036,18 @@ export declare interface TriangleMeshMeasurements {
   readonly vertexCount: number;
 }
 
+/** Mesh measurements with the indexed surface-shell and edge counts requested by includeTopology. */
+export declare interface TriangleMeshTopologyAnalysis extends TriangleMeshAnalysis {
+  /** Number of surface shells connected by shared indexed edges; cavities count separately. */
+  readonly shellCount: number;
+  /** Number of distinct indexed undirected edges. */
+  readonly edgeCount: number;
+}
+
 /**
  * ISO/UTS-like 60-degree truncated triangular profile.
  */
-declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
+export declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
   /** Selects the 60-degree triangular profile family. */
   readonly kind: "triangular";
   /**
@@ -2974,23 +3075,44 @@ export declare function tube(options: TubeOptions): Solid;
 /**
  * Dimensions, placement, and tessellation for a hollow Z-axis tube.
  */
-export declare interface TubeOptions
-  extends CircularPrimitiveOptions, PrimitiveAttachment {
-  /**
-   * Centers the tube on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
-   * @defaultValue `true`
-   */
-  readonly center?: boolean;
-  /** Total height along Z in millimetres. */
-  readonly height: number;
-  /** Positive inner radius in millimetres. */
-  readonly innerRadius: number;
-  /** Outer radius in millimetres; greater than {@link TubeOptions.innerRadius}. */
-  readonly outerRadius: number;
-}
+export declare type TubeOptions = CircularPrimitiveOptions &
+  PrimitiveAttachment & {
+    /**
+     * Centers the tube on the Z origin when `true`; otherwise its bottom is at `Z = 0`.
+     * @defaultValue `true`
+     */
+    readonly center?: boolean;
+    /** Total height along Z in millimetres. */
+    readonly height: number;
+    /** Inner nominal dimension meets polygon vertices or faces; defaults to vertex. */
+    readonly innerSizing?: RadialSizing;
+    /** Outer nominal dimension meets polygon vertices or faces; defaults to vertex. */
+    readonly outerSizing?: RadialSizing;
+  } & (
+    | {
+        /** Positive nominal inner radius in millimetres. */
+        readonly innerRadius: number;
+        /** Nominal outer radius in millimetres, greater than innerRadius. */
+        readonly outerRadius: number;
+        /** Diameter dimensions cannot be combined with radius dimensions. */
+        readonly innerDiameter?: never;
+        /** Diameter dimensions cannot be combined with radius dimensions. */
+        readonly outerDiameter?: never;
+      }
+    | {
+        /** Positive nominal inner diameter in millimetres. */
+        readonly innerDiameter: number;
+        /** Nominal outer diameter in millimetres, greater than innerDiameter. */
+        readonly outerDiameter: number;
+        /** Radius dimensions cannot be combined with diameter dimensions. */
+        readonly innerRadius?: never;
+        /** Radius dimensions cannot be combined with diameter dimensions. */
+        readonly outerRadius?: never;
+      }
+  );
 
 /**
- * Robust union.
+ * Robust union of one or more shapes; empty input rejects during declaration.
  *
  * @example Union
  * ```ts