@metamesh/modeling 0.18.0 → 0.20.0

package/dist/api/mechanical.d.ts

@@ -0,0 +1,1041 @@
+import type {
+  Anchor3,
+  Contour,
+  GeometryResolution,
+  GeometrySamplingLimits,
+  GeometryToleranceOptions,
+  ModelingLimits,
+  Vector2Data,
+  Vector3Data,
+} from "@metamesh/modeling/geometry";
+/** Pure mechanical dimensions, fit policies, standards, and preflight calculations. @packageDocumentation */
+
+/** ACME 29-degree included-angle profile. */
+export declare interface AcmeThreadProfileSpec extends ThreadProfileBaseSpec {
+  /** Selects the 29-degree ACME profile family. */
+  readonly kind: "acme";
+  /**
+   * Radial depth in millimetres.
+   * @defaultValue `pitch / 2`
+   */
+  readonly depth?: number;
+}
+
+/** 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";
+
+/** Axial side carrying the near-normal pressure flank of a buttress thread. */
+export declare type ButtressPressureFlankSide = "negative" | "positive";
+
+/** Asymmetric printable buttress profile with 7/45-degree flanks. */
+export declare interface ButtressThreadProfileSpec extends ThreadProfileBaseSpec {
+  /** Selects the asymmetric printable buttress profile family. */
+  readonly kind: "buttress";
+  /**
+   * Radial depth in millimetres.
+   * @defaultValue `0.66271 * pitch`
+   */
+  readonly depth?: number;
+  /**
+   * Axial side of each tooth carrying the 7-degree pressure flank. The opposite side uses the
+   * 45-degree clearance flank.
+   * @defaultValue `"positive"`
+   */
+  readonly pressureFlankSide?: ButtressPressureFlankSide;
+}
+
+/** Close, normal, and loose metric clearance-hole diameters in millimetres. */
+export declare interface ClearanceHoleDimensions {
+  /** Close-fit clearance-hole diameter. */
+  readonly close: number;
+  /** Loose-fit clearance-hole diameter. */
+  readonly loose: number;
+  /** Normal-fit clearance-hole diameter. */
+  readonly normal: number;
+}
+
+/** Common clearance-hole fit categories, ordered from smallest to largest. */
+export declare type ClearanceHoleFit = "close" | "normal" | "loose";
+
+/** Compensated major/minor envelopes and the policy values used. */
+export declare interface CompensatedThreadDiameters {
+  /** Axial backlash from the selected policy. */
+  readonly axialBacklash: number;
+  /** Compensated major diameter in millimetres. */
+  readonly majorDiameter: number;
+  /** Compensated minor diameter in millimetres. */
+  readonly minorDiameter: number;
+  /** Signed radial shift: negative for male inset, positive for female outset. */
+  readonly radialShift: number;
+}
+
+/**
+ * Applies role-specific radial compensation while preserving thread depth.
+ *
+ * Male envelopes move inward by the policy inset; female envelopes move
+ * outward by the policy outset. Combining both parts produces the sum of those
+ * allowances as radial mating clearance.
+ */
+export declare function compensateThreadDiameters(
+  options: ThreadCompensationOptions,
+): CompensatedThreadDiameters;
+
+/**
+ * Applies axial fit allowance to a validated periodic profile.
+ *
+ * Each flank moves by one quarter of the mating pair's total backlash: male ridges narrow and
+ * female cutter ridges widen. Periodic root endpoints remain fixed, preserving pitch and lead.
+ * Changed profiles are deeply immutable; zero backlash returns the input unchanged.
+ *
+ * @param profile - Validated `[axial, radial]` profile in millimetres.
+ * @param axialBacklash - Nonnegative total pair allowance in millimetres, below half the pitch.
+ * @param role - Male ridge to narrow or female cutter ridge to widen.
+ */
+export declare function compensateThreadProfileAxially(
+  profile: ThreadProfile,
+  axialBacklash: number,
+  role: "female" | "male",
+): ThreadProfile;
+
+/**
+ * Applies printable axial fit plus the conservative phase allowance required by circular facets.
+ *
+ * One triangulated facet spans `pitch * starts / circularSegments` axially. A directed zipper
+ * triangle can expose either end of that complete span when independently faceted parts rotate.
+ * This helper distributes the full conservative flank clearance between the male crest and female
+ * root according to their available flat widths, and rejects a resolution that cannot represent
+ * it exactly.
+ *
+ * @param profile - Uncompensated `[axial, radial]` profile in millimetres.
+ * @param axialBacklash - Nonnegative total pair allowance in millimetres, below half the pitch.
+ * @param role - Male ridge or female cutter receiving its share of the allowances.
+ * @param starts - Integer start count from 1 through 32.
+ * @param circularSegments - Full-circle facet count, at least 3 and divisible by starts.
+ */
+export declare function compensateThreadProfileForFaceting(
+  profile: ThreadProfile,
+  axialBacklash: number,
+  role: "female" | "male",
+  starts: number,
+  circularSegments: number,
+): ThreadProfile;
+
+/** Caller-defined periodic axial/radial profile in millimetres. */
+export declare interface CustomThreadProfileSpec extends ThreadProfileBaseSpec {
+  /** Selects a caller-defined periodic profile. */
+  readonly kind: "custom";
+  /**
+   * Open path spanning exactly `[-pitch/2, pitch/2]`, with both endpoints on the minor envelope,
+   * one connected ridge, one contiguous crest, and radial zero at the major envelope.
+   */
+  readonly points: readonly Vector2Data[];
+}
+
+/** Resolved transverse pitch-plane dimensions for one cylindrical gear. */
+export declare interface CylindricalGearDimensions {
+  /** Addendum above the pitch circle, in millimetres. */
+  readonly addendum: number;
+  /** Angular pitch between adjacent teeth, in radians. */
+  readonly angularPitchRadians: number;
+  /** Tangential backlash applied to this gear, in millimetres. */
+  readonly backlash: number;
+  /** Base-circle radius used by the involute, in millimetres. */
+  readonly baseRadius: number;
+  /** Dedendum below the pitch circle, in millimetres. */
+  readonly dedendum: number;
+  /** Signed helix angle, in radians. */
+  readonly helixAngleRadians: number;
+  /** Caller-supplied normal module, in millimetres. */
+  readonly module: number;
+  /** Minimum physical tooth count for this unshifted full-depth external profile. */
+  readonly minimumToothCountWithoutUndercut: number;
+  /** Outside radius at the tooth tips, in millimetres. */
+  readonly outsideRadius: number;
+  /** Pitch-circle radius, in millimetres. */
+  readonly pitchRadius: number;
+  /** Normal pressure angle, in radians. */
+  readonly pressureAngleRadians: number;
+  /** Root radius at the bottom lands, in millimetres. */
+  readonly rootRadius: number;
+  /** Integer number of teeth. */
+  readonly toothCount: number;
+  /** Tangential tooth thickness at the pitch circle, in millimetres. */
+  readonly toothThicknessAtPitch: number;
+  /** Module measured in the transverse pitch plane, in millimetres. */
+  readonly transverseModule: number;
+  /** Pressure angle measured in the transverse pitch plane, in radians. */
+  readonly transversePressureAngleRadians: number;
+  /** Helical equivalent spur tooth count, `toothCount / cos³(helixAngle)`. */
+  readonly virtualToothCount: number;
+}
+
+/** Whether two cylindrical gears mesh on their outside teeth or as a pinion inside a ring. */
+export declare type CylindricalGearMeshKind = "external" | "internal";
+
+/** Sampling controls for a complete non-duplicated gear outline. */
+export declare interface CylindricalGearOutlineOptions {
+  /** Exact samples per involute flank, at least two, within the aggregate profile ceiling. */
+  readonly flankSamples?: number;
+  /** Exact samples along each bottom land, at least one, within selected circular/profile ceilings. */
+  readonly rootArcSamples?: number;
+  /** Explicit profile and circular allocation ceilings. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+  /** Explicit physical sampling policy for adaptive defaults. */
+  readonly resolution?: GeometryResolution;
+  /** Exact samples along each tooth tip, at least one, within selected circular/profile ceilings. */
+  readonly tipArcSamples?: number;
+}
+
+/** Pitch solution for a coordinated cylindrical gear pair. */
+export declare interface CylindricalGearPairDimensions {
+  /** Nominal distance between the two +Z gear axes, in millimetres. */
+  readonly centerDistance: number;
+  /** Resolved driver dimensions. */
+  readonly driver: CylindricalGearDimensions;
+  /** `-1` for opposite external rotation and `1` for same-direction internal rotation. */
+  readonly drivenDirection: -1 | 1;
+  /** Resolved driven dimensions. */
+  readonly driven: CylindricalGearDimensions;
+  /** Absolute driven-to-driver tooth-count ratio. */
+  readonly ratio: number;
+  /** Helix angle required on the driven member for conjugate teeth, in degrees. */
+  readonly requiredDrivenHelixAngle: number;
+}
+
+/** Sampling controls for one coupled internal-gear tooth cycle. */
+export declare interface CylindricalGearPairMotionOptions {
+  /** Optional deterministic outline sampling overrides. */
+  readonly outline?: CylindricalGearOutlineOptions;
+  /** Coupled poses sampled over one driver tooth pitch. Defaults to 24. */
+  readonly samples?: number;
+}
+
+/** Maximum sampled planar overlap for an external pinion inside an internal ring. */
+export declare interface CylindricalGearPairMotionReport {
+  /** Driver phase at the maximum overlap, in radians. */
+  readonly driverPhaseRadians: number;
+  /** Maximum pinion area lying inside ring material, in square millimetres. */
+  readonly maximumOverlapArea: number;
+  /** Number of evenly spaced coupled poses inspected. */
+  readonly samples: number;
+}
+
+/** Inputs for resolving a coordinated cylindrical gear pair. */
+export declare interface CylindricalGearPairSpec {
+  /** Driving gear or pinion. */
+  readonly driver: CylindricalGearSpec;
+  /** Driven external gear or internal ring gear. */
+  readonly driven: CylindricalGearSpec;
+  /** External/external or external/internal mesh. */
+  readonly mesh: CylindricalGearMeshKind;
+}
+
+/**
+ * Nominal dimensions for a standard full-depth cylindrical involute gear.
+ *
+ * Lengths use millimetres. `module` and `pressureAngle` are measured in
+ * the normal plane; a non-zero signed helix angle is converted to transverse
+ * pitch-plane dimensions. Positive and negative helix angles identify
+ * opposite hands but produce the same 2D pitch geometry.
+ */
+export declare interface CylindricalGearSpec {
+  /** Tangential tooth-thickness reduction at the pitch circle, in millimetres. */
+  readonly backlash?: number;
+  /** Dedendum clearance as a multiple of normal module; defaults to `0.25`. */
+  readonly clearanceFactor?: number;
+  /** Signed helix angle in degrees; zero creates a spur pitch system. */
+  readonly helixAngle?: number;
+  /** Normal module in millimetres per tooth. */
+  readonly module: number;
+  /** Normal pressure angle in degrees; defaults to 20 degrees. */
+  readonly pressureAngle?: number;
+  /** Integer tooth count from 6 through 1,000; external profiles also enforce the no-undercut limit. */
+  readonly toothCount: number;
+}
+
+/** Returns one recommended metric clearance-hole diameter in millimetres. */
+export declare function getMetricClearanceHoleDiameter(
+  size: MetricFastenerSize,
+  fit?: ClearanceHoleFit,
+): number;
+
+/** Returns the immutable standards record for one supported metric size. */
+export declare function getMetricFastenerStandard(
+  size: MetricFastenerSize,
+): MetricFastenerStandard;
+
+/** Options for a compensated internal-thread subtraction tool along +Z. */
+export declare interface InternalThreadCutterOptions
+  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. */
+  readonly nominalMajorDiameter: number;
+}
+
+/** Shared knuckle-joint dimensions in millimetres, independent of mounting geometry. */
+export declare interface KnuckleHingeBaseSpec {
+  /** Total extent along the +X pin axis, centered at the origin. */
+  readonly length: number;
+  /** Number of equal alternating intervals, starting with half A. */
+  readonly knuckleCount: number;
+  /** Outside vertex-sized barrel diameter. */
+  readonly barrelDiameter: number;
+  /** Vertex-sized shaft diameter, including an externally supplied shaft. */
+  readonly pinDiameter: number;
+  /** Nonnegative per-side radial allowance; bores circumscribe this running envelope. */
+  readonly radialClearance: number;
+  /** Nonnegative total air gap between each neighboring pair of knuckle ends. */
+  readonly axialGap: number;
+}
+
+/** Immutable joint layout and conservative faceted envelopes; no engine initialization. */
+export declare interface KnuckleHingeDimensions {
+  /** Validated, copied nominal inputs. */
+  readonly spec: KnuckleHingeSpec;
+  /** Nominal outside barrel radius. */
+  readonly barrelRadius: number;
+  /** Maximum shaft radius under any rotation. */
+  readonly pinRadius: number;
+  /** Minimum face-sized bore radius, including radial clearance. */
+  readonly boreRadius: number;
+  /** Maximum radius at the faceted bore vertices. */
+  readonly boreOuterRadius: number;
+  /** Conservative radial wall before outer end chamfers, accounting for both polygons. */
+  readonly minimumBarrelWall: number;
+  /** Equal length of every interval. */
+  readonly knuckleLength: number;
+  /** Common exact full-circle segment count. */
+  readonly segments: number;
+  /** Alternating schedule ordered from negative to positive X. */
+  readonly knuckles: readonly KnuckleHingeInterval[];
+  /** Integral pin interval; null when the consumer supplies an inserted pin. */
+  readonly pin: Readonly<{
+    /** Start coordinate along X, in millimetres. */
+    start: number;
+    /** Total integral shaft length, including material inside A. */
+    length: number;
+  }> | null;
+  /** Origin at the joint center, direction +X, roll guide +Z. */
+  readonly axis: Anchor3;
+}
+
+/** One equal-length barrel interval in the shared pin-centered frame. */
+export declare interface KnuckleHingeInterval {
+  /** Alternating owner, beginning with A at the negative end of X. */
+  readonly side: "a" | "b";
+  /** Start along X, in millimetres. */
+  readonly start: number;
+  /** Axial length, excluding the neighboring gaps. */
+  readonly length: number;
+}
+
+/** Shared circular sampling for barrels, shafts, and bores. */
+export declare interface KnuckleHingeSamplingOptions {
+  /** Exact full-circle count, divisible by four and at least four; overrides adaptive sampling. */
+  readonly segments?: number;
+  /** Physical tessellation policy. Exact circular counts must also be divisible by four. */
+  readonly resolution?: GeometryResolution;
+  /** Explicit allocation ceilings; defaults to the pure geometry sampling limits. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+}
+
+/**
+ * Knuckle-joint construction modes and interval ownership.
+ *
+ * Print-in-place requires an odd count of at least three: A owns both
+ * end anchors and the entire shaft. Inserted-pin bores both halves and supplies no shaft.
+ * Lift-off requires exactly two intervals; A's integral pin enters B without a far anchor.
+ */
+export declare type KnuckleHingeSpec = KnuckleHingeBaseSpec &
+  (
+    | {
+        /** Captive integral shaft or bores for an externally supplied pin. */
+        readonly mode: "print-in-place" | "inserted-pin";
+        /** Engagement applies only to lift-off construction. */
+        readonly pinEngagement?: never;
+      }
+    | {
+        /** Detachable socket on a finite integral pin. */
+        readonly mode: "lift-off";
+        /** Lift-off has one fixed interval and one removable interval. */
+        readonly knuckleCount: 2;
+        /** Positive axial engagement into B, no greater than its knuckle length. */
+        readonly pinEngagement: number;
+      }
+  );
+
+/**
+ * Measures sampled kinematic interference over one tooth cycle of an internal gear pair.
+ *
+ * The driver and ring start with half-tooth offsets for odd tooth counts, then rotate in the
+ * same direction at their resolved tooth-count ratio. Subtracting the ring's center-and-space
+ * opening from each sampled pinion outline leaves the area overlapping ring material. This detects
+ * involute, tip, and trimming interference that a single assembled pose misses.
+ * It is a deterministic model check, not a certified gear-rating calculation.
+ *
+ * @param spec - Internal pair: external driver pinion and internal driven ring.
+ */
+export declare function measureInternalCylindricalGearPairMotion(
+  spec: CylindricalGearPairSpec,
+  options?: CylindricalGearPairMotionOptions,
+): CylindricalGearPairMotionReport;
+
+/**
+ * Curated metric modeling dimensions for clearance holes, regular hex nuts,
+ * and socket-head cap screws.
+ *
+ * Values are nominal reference dimensions intended for parametric envelopes.
+ * Manufacturing tolerances, coatings, and printer compensation remain caller
+ * responsibilities.
+ */
+export declare const METRIC_FASTENER_STANDARDS: Readonly<{
+  /** Nominal M2 coarse-thread modeling dimensions. */
+  M2: MetricFastenerStandard;
+  /** Nominal M2.5 coarse-thread modeling dimensions. */
+  "M2.5": MetricFastenerStandard;
+  /** Nominal M3 coarse-thread modeling dimensions. */
+  M3: MetricFastenerStandard;
+  /** Nominal M4 coarse-thread modeling dimensions. */
+  M4: MetricFastenerStandard;
+  /** Nominal M5 coarse-thread modeling dimensions. */
+  M5: MetricFastenerStandard;
+  /** Nominal M6 coarse-thread modeling dimensions. */
+  M6: MetricFastenerStandard;
+  /** Nominal M8 coarse-thread modeling dimensions. */
+  M8: MetricFastenerStandard;
+  /** Nominal M10 coarse-thread modeling dimensions. */
+  M10: MetricFastenerStandard;
+  /** Nominal M12 coarse-thread modeling dimensions. */
+  M12: MetricFastenerStandard;
+}>;
+
+/** Supported metric fastener sizes. */
+export declare type MetricFastenerSize =
+  "M2" | "M2.5" | "M3" | "M4" | "M5" | "M6" | "M8" | "M10" | "M12";
+
+/** Small immutable metric fastener record for modeling common mating features. */
+export declare interface MetricFastenerStandard {
+  /** Coarse thread pitch in millimetres. */
+  readonly coarsePitch: number;
+  /** Recommended clearance-hole diameters. */
+  readonly clearanceHoles: ClearanceHoleDimensions;
+  /** Regular hex-nut envelope. */
+  readonly hexNut: MetricHexNutDimensions;
+  /** Nominal fastener diameter in millimetres. */
+  readonly nominalDiameter: number;
+  /** Socket-head cap screw envelope and drive size. */
+  readonly socketCapHead: MetricSocketCapHeadDimensions;
+}
+
+/** Regular hex-nut envelope dimensions in millimetres. */
+export declare interface MetricHexNutDimensions {
+  /** Nominal wrench size across flats. */
+  readonly acrossFlats: number;
+  /** Nominal full-nut thickness. */
+  readonly thickness: number;
+}
+
+/** Socket-head cap screw head and drive dimensions in millimetres. */
+export declare interface MetricSocketCapHeadDimensions {
+  /** Nominal cylindrical head diameter. */
+  readonly diameter: number;
+  /** Nominal head height. */
+  readonly height: number;
+  /** Nominal internal hex key size across flats. */
+  readonly hexKey: number;
+}
+
+/**
+ * Returns the smallest unshifted full-depth external tooth count that avoids rack-cutter undercut.
+ *
+ * The normal-plane limit is `2 / sin²(alpha_n)`. Helical gears use the standard virtual tooth
+ * count `z_v = z / cos³(beta)`, so increasing helix angle can reduce the physical tooth count.
+ *
+ * @param spec - Pressure and signed helix angles in degrees; defaults are 20 and zero.
+ */
+export declare function minimumCylindricalGearToothCountWithoutUndercut(
+  spec?: Readonly<Pick<CylindricalGearSpec, "helixAngle" | "pressureAngle">>,
+): number;
+
+/**
+ * Resolves compensated cutter dimensions and checks extended mesh estimates against output limits.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It includes the cutter's one-pitch extension beyond each requested face and
+ * creates planning data without mesh buffers or native objects. Row and triangle counts are
+ * estimates; mesh validity and native construction are checked later.
+ *
+ * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Nominal cavity dimensions in millimetres, before fit and face extension.
+ */
+export declare function preflightInternalThreadCutter(
+  options: InternalThreadCutterOptions,
+): ThreadSolidPreflight;
+
+/**
+ * Checks nut dimensions, chamfers, end-face wall, and the extended compensated cutter's allocation plan.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It resolves body/cutter dimensions without mesh buffers or native objects.
+ * `thread` contains conservative cutter estimates, excluding the body and Boolean result.
+ * Successful preflight leaves mesh validity, native construction, and manufacturing fit to later checks.
+ *
+ * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ *
+ * @param options - Nominal nut dimensions in millimetres, fit, and sampling controls.
+ */
+export declare function preflightThreadedNut(
+  options: ThreadedNutOptions,
+): ThreadedNutPreflight;
+
+/**
+ * Resolves compensated rod dimensions and checks conservative mesh estimates against output limits.
+ *
+ * This pure operation uses explicit resolution and limits or package defaults, without an active
+ * host execution. It creates planning data without mesh buffers or native objects; returned row
+ * and triangle counts are estimates. Mesh validity and native construction are checked later.
+ *
+ * See `mesh.preflightThreadSolid` for standalone mesh estimates.
+ * See `mesh.threadSolid` for standalone mesh construction.
+ *
+ * @param options - Nominal rod dimensions in millimetres, fit, and sampling controls.
+ */
+export declare function preflightThreadedRod(
+  options: ThreadedRodOptions,
+): ThreadSolidPreflight;
+
+/**
+ * Conservative baseline print-fit policies in millimetres.
+ *
+ * These are modeling defaults, not manufacturing guarantees. A caller should
+ * calibrate them for its printer, material, layer height, and thread scale.
+ */
+export declare const PRINTABLE_THREAD_FIT_POLICIES: Readonly<{
+  /** Small baseline clearance for calibrated, accurate printers. */
+  tight: PrintableThreadFitPolicy;
+  /** General-purpose baseline clearance. */
+  normal: PrintableThreadFitPolicy;
+  /** Generous baseline clearance for rougher prints or easy assembly. */
+  loose: PrintableThreadFitPolicy;
+}>;
+
+/** Named baseline fit policies for calibrated FDM-style printed threads. */
+export declare type PrintableThreadFit = "tight" | "normal" | "loose";
+
+/**
+ * Explicit radial and axial allowances for a mating printed thread pair.
+ *
+ * Male and female radial values are applied independently, so their sum is the
+ * assembled radial clearance. Values are millimetres and intentionally do not
+ * encode printer, material, or process calibration.
+ */
+export declare interface PrintableThreadFitPolicy {
+  /** Nominal axial backlash available between opposing flanks. */
+  readonly axialBacklash: number;
+  /** Radial increase applied to an internal thread envelope. */
+  readonly femaleRadialOutset: number;
+  /** Radial reduction applied to an external thread envelope. */
+  readonly maleRadialInset: number;
+}
+
+/** Resolved pitch-line dimensions for a finite rack segment. */
+export declare interface RackPitchDimensions {
+  /** Tooth height above the pitch line, in millimetres. */
+  readonly addendum: number;
+  /** Tooth root depth below the pitch line, in millimetres. */
+  readonly dedendum: number;
+  /** Signed helix angle, in radians. */
+  readonly helixAngleRadians: number;
+  /** Total pitch-line length for the requested tooth count, in millimetres. */
+  readonly length: number;
+  /** Transverse linear pitch between teeth, in millimetres. */
+  readonly pitch: number;
+  /** Transverse pressure angle, in radians. */
+  readonly pressureAngleRadians: number;
+  /** Tangential tooth thickness at the pitch line, in millimetres. */
+  readonly toothThicknessAtPitch: number;
+  /** Number of complete teeth represented by the segment. */
+  readonly toothCount: number;
+  /** Normal module supplied by the caller, in millimetres. */
+  readonly module: number;
+}
+
+/** Normal-plane inputs for a finite rack pitch segment. */
+export declare interface RackPitchSpec {
+  /** Tangential tooth-thickness reduction at the pitch line, in millimetres. */
+  readonly backlash?: number;
+  /** Dedendum clearance as a multiple of normal module; defaults to `0.25`. */
+  readonly clearanceFactor?: number;
+  /** Signed helix angle in degrees; zero creates a straight rack. */
+  readonly helixAngle?: number;
+  /** Normal module in millimetres per tooth. */
+  readonly module: number;
+  /** Normal pressure angle in degrees; defaults to 20 degrees. */
+  readonly pressureAngle?: number;
+  /** Number of complete rack teeth represented by the segment. */
+  readonly toothCount: number;
+}
+
+/**
+ * Resolves a validated unshifted full-depth external cylindrical gear.
+ *
+ * The gear axis is +Z and the returned radii describe its XY pitch plane. Inputs below the
+ * pressure- and helix-dependent no-undercut tooth count are rejected because profile shift is not
+ * currently supported.
+ *
+ * @param spec - Nominal gear dimensions in millimetres and degrees.
+ */
+export declare function resolveCylindricalGear(
+  spec: CylindricalGearSpec,
+): CylindricalGearDimensions;
+
+/**
+ * Resolves ratio, center distance, and helix relationship for a gear pair.
+ *
+ * Both gears must use the same normal module, pressure angle, and helix-angle
+ * magnitude. An external pair uses opposite helix hands; an internal pair uses
+ * the same hand. The function validates those conjugate pitch invariants.
+ *
+ * @param spec - Driver and driven gears using the same normal pitch system.
+ */
+export declare function resolveCylindricalGearPair(
+  spec: CylindricalGearPairSpec,
+): CylindricalGearPairDimensions;
+
+/**
+ * Resolves equal alternating knuckles along +X, centered at the origin, in millimetres.
+ *
+ * Both faces of each running pair use a common polygon count; face-sized bores contain the
+ * shaft's complete rotational envelope. Adaptive sampling satisfies both face and vertex error
+ * bounds; an insufficient ceiling rejects instead of reducing quality. Exact counts are intentional
+ * facets. Zero allowances describe ideal contact, not a printable running fit.
+ *
+ * Rejects non-finite or non-positive dimensions, invalid mode/count combinations, exhausted axial
+ * length, missing/excessive lift-off engagement, and non-positive conservative faceted barrel walls.
+ * Manufacturing minima, strength, mounting, retention, handedness, and motion remain caller policy.
+ *
+ * @param spec - Joint dimensions in millimetres, mode, and knuckle count.
+ */
+export declare function resolveKnuckleHinge(
+  spec: KnuckleHingeSpec,
+  options?: KnuckleHingeSamplingOptions,
+): KnuckleHingeDimensions;
+
+/**
+ * Resolves and validates a named or caller-defined print-fit policy.
+ *
+ * @param fit - Named fit or non-negative per-side radial and total axial allowances, in millimetres.
+ */
+export declare function resolvePrintableThreadFitPolicy(
+  fit?: PrintableThreadFit | PrintableThreadFitPolicy,
+): PrintableThreadFitPolicy;
+
+/**
+ * Resolves a rack segment that is conjugate with the same normal cylindrical pitch system.
+ *
+ * @param spec - Rack dimensions in millimetres and degrees.
+ */
+export declare function resolveRackPitch(
+  spec: RackPitchSpec,
+): RackPitchDimensions;
+
+/**
+ * Resolves a role-independent, start-aligned facet count from the larger female mating envelope.
+ *
+ * An exact `circularSegments` value must already be divisible by `starts`; it is never silently
+ * raised. Adaptive policies align upward and fail if that would exceed `maxSegments`.
+ *
+ * @param options - Nominal diameter, uncompensated profile, and shared mating resolution.
+ */
+export declare function resolveThreadCircularSegments(
+  options: ThreadCircularSegmentsOptions,
+): number;
+
+/**
+ * Samples a complete external involute gear boundary in the XY plane.
+ *
+ * The returned loop is counter-clockwise, closed implicitly without a repeated
+ * seam point, and contains no holes. Its center is the origin and its axis is
+ * +Z. Bore, hub, keyway, twist, and face-width choices remain generator-owned.
+ *
+ * @param spec - External gear dimensions in millimetres and degrees; undercut profiles reject.
+ */
+export declare function sampleCylindricalGearOutline(
+  spec: CylindricalGearSpec,
+  options?: CylindricalGearOutlineOptions,
+): Contour;
+
+/** Sampled paths plus conventional pitch and lead measurements. */
+export declare interface SampledThreadHelices {
+  /** Axial advance over one revolution, equal to `pitch * starts`. */
+  readonly lead: number;
+  /** One immutable sampled path for each thread start. */
+  readonly paths: readonly (readonly Vector3Data[])[];
+  /** Adjacent axial thread spacing in millimetres. */
+  readonly pitch: number;
+  /** Number of revolutions represented by each path. */
+  readonly turns: number;
+}
+
+/**
+ * Samples the center opening and tooth spaces used to subtract an internal ring gear.
+ *
+ * Internal tooth tips lie one addendum below the pitch radius and their roots lie one
+ * dedendum above it. At the pitch circle, positive backlash widens each sampled space
+ * tangentially. The returned CCW loop encloses the center and is intended to be reversed
+ * when used as a region hole.
+ *
+ * @param spec - Internal ring dimensions in millimetres and degrees; backlash widens tooth spaces.
+ */
+export declare function sampleInternalCylindricalGearSpaceOutline(
+  spec: CylindricalGearSpec,
+  options?: CylindricalGearOutlineOptions,
+): Contour;
+
+/**
+ * Samples the open top boundary of a finite rack in its XY pitch plane.
+ *
+ * X follows rack travel, Y is tooth height, and the pitch line is `Y = 0`.
+ * The path begins and ends on the root line, omits duplicate adjacent points,
+ * and leaves base thickness, mounting features, extrusion, and helical sweep to
+ * the owning generator.
+ *
+ * @param spec - Rack dimensions in millimetres and degrees, along +X.
+ * @param limits - Sampling limits; exceeding them throws without coarsening.
+ */
+export declare function sampleRackToothPath(
+  spec: RackPitchSpec,
+  limits?: Partial<GeometrySamplingLimits>,
+): readonly Vector2Data[];
+
+/**
+ * Samples evenly phased thread helices with finite `lead = pitch * starts`.
+ * All starts together respect `maxPathPoints`; excessive counts fail before allocation.
+ *
+ * @param options - Dimensions in millimetres; lead is pitch multiplied by starts.
+ */
+export declare function sampleThreadHelices(
+  options: ThreadHelixOptions,
+): SampledThreadHelices;
+
+/** Square profile with equal crest and root widths. */
+export declare interface SquareThreadProfileSpec extends ThreadProfileBaseSpec {
+  /** Selects the square profile family. */
+  readonly kind: "square";
+  /**
+   * Radial depth in millimetres.
+   * @defaultValue `pitch / 2`
+   */
+  readonly depth?: number;
+}
+
+/** 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;
+}
+
+/** Inputs for resolving one shared circular facet count for a mating thread pair. */
+export declare interface ThreadCircularSegmentsOptions {
+  /** Explicit circular allocation ceiling for the shared mating grid. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+  /** Printable fit whose larger compensated female envelope governs tessellation. */
+  readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
+  /** Nominal major diameter before role-specific compensation. */
+  readonly nominalMajorDiameter: number;
+  /**
+   * Maximum active female face outset beyond the compensated major envelope, in millimetres.
+   * This keeps a compensated male/female pair on one role-independent grid when an internal
+   * cutter has an enlarged entrance bevel. Default: `0`.
+   */
+  readonly maxRadialOutset?: number;
+  /** Validated mating profile whose pitch and flank capacities govern tessellation. */
+  readonly profile: ThreadProfile;
+  /** Physical or exact circular resolution policy. */
+  readonly resolution?: GeometryResolution;
+  /** Number of phased starts. Default: `1`. */
+  readonly starts?: number;
+}
+
+/** Options for compensating nominal male or female thread diameters. */
+export declare interface ThreadCompensationOptions {
+  /** Named policy or explicit caller-calibrated allowances. */
+  readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
+  /** Nominal sharp or truncated major diameter in millimetres. */
+  readonly nominalMajorDiameter: number;
+  /** Male or female geometry being compensated. */
+  readonly role: ThreadRole;
+  /** Radial depth from major to minor envelope in millimetres. */
+  readonly threadDepth: number;
+  /** Optional numerical tolerance overrides. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
+/** Options for a compensated nut with an internal thread. */
+export declare interface ThreadedNutOptions extends Omit<
+  InternalThreadCutterOptions,
+  "bevel" | "length"
+> {
+  /** 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;
+  /** Nut body shape. */
+  readonly shape: ThreadedNutShape;
+  /** Nut thickness along +Z in millimetres. */
+  readonly thickness: number;
+  /** Across-flats width for hex/square or diameter for round, in millimetres. */
+  readonly width: number;
+}
+
+/** Resolved body and end-face dimensions plus conservative allocation estimates for the thread cutter. */
+export declare interface ThreadedNutPreflight {
+  /** Polygon segment count used by the nut body. */
+  readonly bodySegments: 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. */
+  readonly minimumBodyFaceInradius: number;
+  /** 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: ThreadSolidPreflight;
+  /** Start-aligned circular facet count used by the compensated thread cutter. */
+  readonly threadCircularSegments: number;
+}
+
+/** Supported printable nut body shapes. */
+export declare type ThreadedNutShape = "hex" | "round" | "square";
+
+/** Options for a compensated external threaded rod along +Z. */
+export declare interface ThreadedRodOptions
+  extends Omit<ThreadRidgeOptions, "majorDiameter">, ThreadBevelOptions {
+  /** Printable fit or caller-calibrated allowances. Default: `normal`. */
+  readonly fit?: PrintableThreadFit | PrintableThreadFitPolicy;
+  /** Nominal major diameter before male compensation. */
+  readonly nominalMajorDiameter: number;
+}
+
+/** End shape of a generated helical ridge. */
+export declare type ThreadEndStyle = "blunt" | "standard" | "tapered";
+
+/** Axial end controls for a generated ridge. */
+export declare interface ThreadEndTreatmentOptions {
+  /**
+   * Ridge shape at the lower working boundary. `blunt` ends at full profile height, `standard`
+   * clips the periodic profile at the face, and `tapered` ramps out from the minor envelope.
+   * @defaultValue `"blunt"`
+   */
+  readonly bottom?: ThreadEndStyle;
+  /**
+   * Non-negative unthreaded envelope length reserved at each non-standard end, in millimetres.
+   * Active blunt bevels may raise this reservation to the effective bevel size.
+   * @defaultValue `0`
+   */
+  readonly endLength?: number;
+  /**
+   * Radial envelope toward which a blunt lead-in collapses.
+   * @defaultValue `"minor"`
+   */
+  readonly leadInEnvelope?: ThreadLeadInEnvelope;
+  /**
+   * Physical circumferential lead-in length in millimetres.
+   * @defaultValue The profile depth.
+   */
+  readonly leadInLength?: number;
+  /**
+   * Cross-section scaling curve used by blunt ends. `cut` switches abruptly to the full profile.
+   * @defaultValue `"cut"`
+   */
+  readonly leadInShape?: ThreadLeadInShape;
+  /**
+   * Ridge shape at the upper working boundary. `blunt` ends at full profile height, `standard`
+   * clips the periodic profile at the face, and `tapered` ramps into the minor envelope.
+   * @defaultValue `"blunt"`
+   */
+  readonly top?: ThreadEndStyle;
+}
+
+/** Direction in which a conventional helical thread advances around +Z. */
+export declare type ThreadHandedness = "left" | "right";
+
+/** Conventional helix options: `pitch` is adjacent spacing and lead is `pitch * starts`. */
+export declare interface ThreadHelixOptions {
+  /** Helix direction. Default: `right`. */
+  readonly handedness?: ThreadHandedness;
+  /** Explicit aggregate path allocation ceilings across all starts. */
+  readonly limits?: Partial<GeometrySamplingLimits>;
+  /** Total sampled axial length in millimetres. */
+  readonly length: number;
+  /** Angular offset of the first start in degrees. Default: `0`. */
+  readonly phase?: number;
+  /** Adjacent axial thread spacing in millimetres. */
+  readonly pitch: number;
+  /** Radial distance from the +Z axis in millimetres. */
+  readonly radius: number;
+  /** Angular sampling density for each revolution. Default: `32`. */
+  readonly segmentsPerTurn?: number;
+  /** Number of evenly phased helices. Default: `1`. */
+  readonly starts?: number;
+  /** Optional numerical tolerance overrides. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
+/** Radial envelope toward which a blunt lead-in collapses. */
+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. */
+export declare interface ThreadProfile {
+  /** Axial width of the flat at the major envelope. */
+  readonly crestFlatWidth: number;
+  /** Radial distance from the major envelope to the root. */
+  readonly depth: number;
+  /** Profile family that produced this validated profile. */
+  readonly kind: ThreadProfileSpec["kind"];
+  /** Adjacent axial thread spacing in millimetres. */
+  readonly pitch: number;
+  /** Immutable open `[axial, radial]` path spanning one pitch. */
+  readonly points: readonly Vector2Data[];
+  /** Axial width of the flat at the minor envelope. */
+  readonly rootFlatWidth: number;
+}
+
+/**
+ * Creates a periodic thread profile for the shaft-locked helical mesher.
+ *
+ * The open path spans one pitch. Radial zero is the major envelope; negative
+ * values point toward the shaft. Custom paths must be finite, axially
+ * non-decreasing, periodic at their endpoints, and reach radial zero.
+ *
+ * @param spec - Profile family or custom one-pitch `[axial, radial]` path, in millimetres.
+ *
+ * @example Printable triangular thread profile
+ * ```ts
+ * import { threadProfile } from "@metamesh/modeling/geometry/mechanical";
+ *
+ * threadProfile({ kind: "triangular", pitch: 1.75 });
+ * ```
+ */
+export declare function threadProfile(spec: ThreadProfileSpec): ThreadProfile;
+
+/** Fields shared by all thread profile specifications. */
+export declare interface ThreadProfileBaseSpec {
+  /** Adjacent axial thread spacing in millimetres. */
+  readonly pitch: number;
+  /** Optional numerical tolerance overrides. */
+  readonly tolerance?: GeometryToleranceOptions;
+}
+
+/** Supported built-in and caller-defined thread profiles. */
+export declare type ThreadProfileSpec =
+  | AcmeThreadProfileSpec
+  | ButtressThreadProfileSpec
+  | CustomThreadProfileSpec
+  | SquareThreadProfileSpec
+  | TrapezoidalThreadProfileSpec
+  | TriangularThreadProfileSpec;
+
+/** 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>;
+  /** Major diameter in millimetres; apply any caller-owned fit compensation before construction. */
+  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;
+}
+
+/** Whether compensation is being applied to an external or internal thread. */
+export declare type ThreadRole = "male" | "female";
+
+/** Options for a complete threaded-cylinder mesh; base semantics match the ridge builder. */
+export declare interface ThreadSolidOptions extends ThreadRidgeOptions {
+  /** Independent 45-degree bottom/top bevels; omitted disables both. Auto uses profile depth. */
+  readonly bevel?: Bevel;
+  /** Distance in millimetres of each bevel target face inward from the corresponding mesh end. */
+  readonly bevelOffset?: number;
+  /** `inset` trims an external rod; `outset` expands an internal cutter. */
+  readonly bevelMode?: "inset" | "outset";
+}
+
+/** 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;
+}
+
+/** Trapezoidal thread profile with a configurable included angle. */
+export declare interface TrapezoidalThreadProfileSpec extends ThreadProfileBaseSpec {
+  /** Selects the trapezoidal profile family. */
+  readonly kind: "trapezoidal";
+  /**
+   * Radial depth in millimetres.
+   * @defaultValue `pitch / 2`
+   */
+  readonly depth?: number;
+  /**
+   * Full angle between the flanks in degrees, from `0` inclusive to `180` exclusive.
+   * Each flank uses half this angle from the radial direction; `90` gives 45-degree slopes.
+   * @defaultValue `30`
+   */
+  readonly includedAngle?: number;
+}
+
+/** ISO/UTS-like 60-degree truncated triangular profile. */
+export declare interface TriangularThreadProfileSpec extends ThreadProfileBaseSpec {
+  /** Selects the 60-degree triangular profile family. */
+  readonly kind: "triangular";
+  /**
+   * Crest width divided by pitch.
+   * @defaultValue `1 / 8`
+   */
+  readonly crestFlatRatio?: number;
+  /**
+   * Root width divided by pitch.
+   * @defaultValue `1 / 4`
+   */
+  readonly rootFlatRatio?: number;
+}
+
+export {};