@metamesh/modeling 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @metamesh/modeling
 
+## 0.17.0
+
+### Minor Changes
+
+- Expose `resolveCircularSampling` for the resolved count and actual vertex/face radii of a sampled
+  circle without allocating points. It shares sampling rules with `resolveCircularSegments`, aligned
+  counts, and `circleContour`, including exact-count precedence and physical error ceilings.
+
+  Construct fluent bounds directly with `bounds2({ size: [width, height] })` and
+  `bounds3({ size: [width, depth, height], center: false })`. Size construction accepts finite
+  nonnegative dimensions, centers by default, and is mutually exclusive with min/max construction.
+  Remove `boundsFromSize`, `BoundsFromSizeOptions`, and the standalone `containsBounds` export.
+  Containment remains available on `Bounds2` and `Bounds3`, including touching boundaries.
+
+  Migration: replace `boundsFromSize(size, { center })` with the dimension-specific
+  `bounds2({ size, center })` or `bounds3({ size, center })`. Use `.toData()` when a plain record is
+  required. For sampled bore and wall checks, use `vertexRadius` and `faceRadius` from
+  `resolveCircularSampling` instead of repeating faceting trigonometry.
+  Replace `containsBounds(outer, inner)` with `bounds2(outer).containsBounds(inner)` or the matching
+  XYZ bounds value's method.
+
+- d0cc194: Rename per-half `barrelChamfer` to `chamfer` in `knuckleHinge`. The same 45-degree setback now finishes barrel outer rims and exposed web edges. Keep the buried root square and share bevel coordinates with the barrel and mounting body to avoid microscopic steps and collapsed placement triangles. Reject chamfers that consume the web band or collapse its end contours.
+- Add deferred `holeCutter` recipes for circular screw holes and existing Section pocket profiles.
+  Circular cutters support counterbores and countersinks; convex single-contour profiles support
+  45-degree entry chamfers. Explicit `overrun.bottom` and `overrun.top` preserve blind-pocket floors
+  unless the caller deliberately extends the cutter.
+  Circular entry chamfers retain nominal circular radii; Section entry chamfers offset the supplied
+  sampled contour's edges.
+
+  Advance the Modeling host runtime to major 9 for hole cutters and fitted SVG recipe options.
+  Rebuild Generator packages against the new library set; old host/runtime packages are rejected.
+
+  Migration tip: reuse `regularPolygon`, `rectangle`, or other Section constructors as the cutter's
+  `profile`. Position a blind cutter at its intended floor and set only `overrun.top` for opening
+  padding. Keep allowances, minimum floor thickness and feature-specific assertions in your model.
+
+- Add an optional positioned XY `fit` target to `preflightSvgRegion` and `svgSection`. Reuse `fitBounds` for uniform scale and translation while resampling original SVG curves at the final millimetre tolerance and edge spacing. Normalize fitted source units before topology checks, and use relative matrix conditioning so tiny well-conditioned SVG coordinates can be enlarged safely. Preserve holes, painted strokes, exact circular-count overrides, bounded work, and host-owned sampling ceilings. Preflight results expose the applied fit for registered layers and measure the final region.
+
+  Migration tip: replace import → measure → scale → re-import code with `preflightSvgRegion(svg, { fit: bounds2({ size: [30, 18] }), resolution: { maxChordError: 0.05 } })`. `svgSection` preserves positioned fit targets instead of centering them again.
+
 ## 0.16.0
 
 ### Minor Changes

package/README.md

@@ -113,12 +113,29 @@ Closed `Path2` values describe traversal, not material; `polygon(path)` fills th
 winding. Path transforms preserve traversal under reflection. `toData()` supplies a frozen record with points, closure, and dimension for interchange.
 
 Use `bounds2({ min, max })` and `bounds3({ min, max })` for axis-aligned extents with fluent
-`size()`, `center()`, and `containsBounds()` queries. Path `bounds()` returns these values, or
+`size()`, `center()`, and `containsBounds()` queries. Construct from dimensions with
+`bounds2({ size: [30, 18] })` or `bounds3({ size: [30, 18, 8], center: false })`; centered size
+construction is the default, and size cannot be combined with min/max. Path `bounds()` returns these values, or
 `undefined` for an empty path. Measurements and snapshots retain plain `Bounds2Data` / `Bounds3Data`;
 wrap them once for fluent queries and use `toData()` for a frozen min/max record.
 Containment includes touching boundaries in the same coordinate frame; it does not establish
 manufacturing fit. Pure `fitBounds` and `layoutRow` accept values or data for fitting and row placement.
 
+## Hole and pocket cutters
+
+`holeCutter({ diameter, height })` declares a circular cutter from Z=0 to `height`.
+Use `profile: regularPolygon(...)` or `profile: rectangle(...)` instead of `diameter` for
+existing Section outlines. Plain profiles may have holes or disconnected regions. A positive
+`entryChamfer` must be smaller than `height`. Circular entries use nominal frustum radii;
+profile entries expand one strictly convex contour without holes by 45-degree parallel-edge
+offsets of its sampled boundary.
+
+Circular cutters additionally accept a `recess` with `kind: "counterbore"`, `diameter` and `depth`,
+or `kind: "countersink"`, `diameter` and full `includedAngle` in degrees. Recesses and entry chamfers
+are alternatives; `face` selects the top opening by default or the bottom opening explicitly.
+Both `overrun.bottom` and `overrun.top` default to zero. To preserve a blind pocket floor, position
+the cutter at that floor and extend only its top. Consumers own fit allowances and retained walls.
+
 ## Mechanical joints
 
 `knuckleHinge(options)` declares separate `halfA` and `halfB` solids with a centered +X pin axis
@@ -126,10 +143,14 @@ and +Z roll guide. Choose `print-in-place`, `inserted-pin`, or `lift-off` constr
 joints require an odd knuckle count; lift-off joints require two knuckles and an explicit
 `pinEngagement`. Inserted-pin joints supply no pin or retention hardware.
 
-Each half accepts an optional rectangular web with its own Y direction, lower-face Z coordinate (`zMin`), thickness, and
-reach, or can remain barrels only. Optional `barrelChamfer` sets the 45-degree setback in millimetres at both ends of every barrel; web edges
-remain square. Consumers connect disconnected intervals to their plates or shells, preserve bores
-when adding material, and own mounting holes, part placement, and motion. Arbitrary attachments
+Each half accepts an optional rectangular web with its own Y direction, lower-face Z coordinate
+(`zMin`), thickness, and reach, or can remain barrels only. Optional per-half `chamfer` sets the
+45-degree setback in millimetres at both ends of every barrel and on exposed web edges. The root
+at the pin centreline stays square so its faces merge with the barrel. The setback defaults to
+zero and 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.
+Consumers connect disconnected intervals to their plates or shells, preserve bores when adding
+material, and own mounting holes, part placement, and motion. Arbitrary attachments
 have no guaranteed opening range. Use `resolveKnuckleHinge(spec, sampling)` from `/geometry` for
 the immutable interval schedule, axis frame, integral pin extent, and conservative faceted wall.
 

package/dist/api/geometry.d.ts

@@ -248,14 +248,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 9.0.0 or newer in major 9.
  */
-export declare function bounds2(input: Bounds2Input): Bounds2;
+export declare function bounds2(input: Bounds2Options): Bounds2;
 
 /** Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. */
 export declare interface Bounds2Data {
@@ -268,6 +269,25 @@ 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 =
+  | (Bounds2Input & {
+      /** Preserves the size query when snapshotting an existing fluent value. */
+      readonly size?: Bounds2["size"];
+      /** Preserves the center query when snapshotting an existing fluent value. */
+      readonly center?: Bounds2["center"];
+    })
+  | {
+      /** Nonnegative XY dimensions in millimetres. */
+      readonly size: Vector2Data;
+      /** 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. */
@@ -281,14 +301,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 9.0.0 or newer in major 9.
  */
-export declare function bounds3(input: Bounds3Input): Bounds3;
+export declare function bounds3(input: Bounds3Options): Bounds3;
 
 /** Plain axis-aligned XYZ bounds for interchange; use bounds3 for immutable measurement methods. */
 export declare interface Bounds3Data {
@@ -301,6 +322,25 @@ 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 =
+  | (Bounds3Input & {
+      /** Preserves the size query when snapshotting an existing fluent value. */
+      readonly size?: Bounds3["size"];
+      /** Preserves the center query when snapshotting an existing fluent value. */
+      readonly center?: Bounds3["center"];
+    })
+  | {
+      /** Nonnegative XYZ dimensions in millimetres. */
+      readonly size: Vector3Data;
+      /** 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;
+    };
+
 /** Midpoint of finite XY bounds in millimetres. */
 export declare function boundsCenter(bounds: Bounds2Data): Vector2Data;
 
@@ -333,24 +373,6 @@ export declare interface BoundsFitOptions {
   readonly maxScale?: number;
 }
 
-/** Creates immutable centered XY bounds from nonnegative dimensions in millimetres. */
-export declare function boundsFromSize(
-  size: Vector2Data,
-  options?: BoundsFromSizeOptions,
-): Bounds2Data;
-
-/** Creates immutable centered XYZ bounds from nonnegative dimensions in millimetres. */
-export declare function boundsFromSize(
-  size: Vector3Data,
-  options?: BoundsFromSizeOptions,
-): Bounds3Data;
-
-/** Placement of bounds constructed from nonnegative millimetre dimensions. */
-export declare interface BoundsFromSizeOptions {
-  /** Center on the origin; false starts at the origin. Defaults to true. */
-  readonly center?: boolean;
-}
-
 /** Inclusive XY dimensions in millimetres; zero extents are retained. */
 export declare function boundsSize(bounds: Bounds2Data): Vector2Data;
 
@@ -459,20 +481,18 @@ export declare interface ChamferedEdgeTreatment {
  */
 export declare const circleContour: (options: CircleContourOptions) => Contour;
 
-/**
- * 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;
@@ -502,6 +522,19 @@ export declare interface CircularResolutionOptions extends GeometryResolution {
   readonly sizing?: RadialSizing;
 }
 
+/** Full-circle count and radial envelopes of its regular sampled polygon, in millimetres. */
+export declare interface CircularSampling {
+  /** Exact resolved full-circle segment count. */
+  readonly segments: number;
+  /** Distance from the origin to every sampled vertex. */
+  readonly vertexRadius: number;
+  /** Minimum distance from the origin to each straight sampled edge. */
+  readonly faceRadius: number;
+}
+
+/** Nominal circle size and explicit physical sampling; supply exactly one radius or diameter. */
+export declare type CircularSamplingOptions = CircleContourOptions;
+
 /** Close, normal, and loose metric clearance-hole diameters in millimetres. */
 export declare interface ClearanceHoleDimensions {
   /** Close-fit clearance-hole diameter. */
@@ -658,18 +691,6 @@ export declare function computeTriangleMeshSignature(
   options?: TriangleMeshSignatureOptions,
 ): TriangleMeshSignature;
 
-/** Tests actual XY containment, including touching boundaries; dimensions must match. */
-export declare function containsBounds(
-  outer: Bounds2Data,
-  inner: Bounds2Data,
-): boolean;
-
-/** Tests actual XYZ containment, including touching boundaries; dimensions must match. */
-export declare function containsBounds(
-  outer: Bounds3Data,
-  inner: Bounds3Data,
-): boolean;
-
 /**
  * A sampled closed two-dimensional boundary whose first point is not repeated at the end.
  *
@@ -2407,8 +2428,11 @@ export declare function preflightInternalThreadCutter(
  *
  * This pure operation performs curve flattening, fill and stroke construction, and polygon union;
  * it needs no browser or engine. Geometry counts measure the returned region at the selected
- * resolution, rather than predicting later mesh allocation. The region may be empty; tiny-island
- * and short-edge indicators do not establish manufacturability or later solid validity.
+ * resolution, rather than predicting later mesh allocation. With `fit`, painted bounds are
+ * uniformly centered inside the target and adaptive sampling remains in final millimetres.
+ * Refinement runs at most eight bounded import passes; exact circular counts retain precedence.
+ * Without `fit` the region may be empty. Tiny-island and short-edge indicators do not establish
+ * manufacturability or later solid validity.
  *
  * @param svg - Complete SVG XML source, limited to 256 KiB of UTF-8.
  * @param options - Physical flattening and viewport-origin controls.
@@ -2865,6 +2889,25 @@ export declare function resolveArcSegments(
   limits?: Partial<GeometrySamplingLimits>,
 ): number;
 
+/**
+ * Resolves circular sampling and its actual radial envelopes without allocating boundary points.
+ *
+ * Vertex sizing retains the nominal vertex radius; face sizing retains the nominal face radius.
+ * Exact `segments` override resolution, while allocation ceilings still apply. Adaptive sampling
+ * uses the same count calculation as `resolveCircularSegments` and `circleContour` and rejects
+ * exhausted limits rather than coarsening. The returned record is immutable and needs no engine.
+ *
+ * @example Check a nominal 8 mm face-sized bore
+ * ```ts
+ * const bore = resolveCircularSampling({ diameter: 8, segments: 64, sizing: "face" });
+ * bore.faceRadius; // 4 mm
+ * bore.vertexRadius; // slightly larger than 4 mm
+ * ```
+ */
+export declare function resolveCircularSampling(
+  options: CircularSamplingOptions,
+): CircularSampling;
+
 /**
  * Resolves a deterministic full-circle segment count for one radius.
  *
@@ -3536,6 +3579,12 @@ export declare const subtract3: (a: Vector3Data, b: Vector3Data) => Vector3Data;
 
 /** Sampling controls for deterministic SVG-to-region conversion. */
 export declare interface SvgImportOptions {
+  /**
+   * Uniformly fit painted bounds inside this positioned XY target in millimetres.
+   * Adaptive resolution describes the fitted size; exact circular counts retain precedence.
+   * Empty painted geometry cannot be fitted. Omitted preserves the document's physical size.
+   */
+  readonly fit?: Bounds2Input;
   /** Explicit profile and circular allocation ceilings; bounded SVG source/work limits remain fixed. */
   readonly limits?: Partial<GeometrySamplingLimits>;
   /** Exact segments for a complete ellipse or round stroke feature. */
@@ -3551,6 +3600,12 @@ export declare interface SvgImportOptions {
 
 /** Normalized sampled SVG region plus bounded source, geometry, and safe-repair diagnostics. */
 export declare interface SvgRegionPreflight {
+  /**
+   * Applied scale and translation from origin-normalized SVG millimetres to final model
+   * millimetres, present only when a fit target was supplied. Reuse it for registered layers
+   * imported with the same origin and document coordinate system.
+   */
+  readonly fit?: BoundsFit2;
   /** Physical and final-topology measurements of `region`. */
   readonly geometry: SvgRegionPreflightGeometryMetrics;
   /** Appearance-preserving cleanup observed during parsing and normalization. */

package/dist/api/index.d.ts

@@ -62,14 +62,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 9.0.0 or newer in major 9.
  */
-export declare function bounds2(input: Bounds2Input): Bounds2;
+export declare function bounds2(input: Bounds2Options): Bounds2;
 
 /** Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. */
 export declare interface Bounds2Data {
@@ -82,6 +83,25 @@ 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 =
+  | (Bounds2Input & {
+      /** Preserves the size query when snapshotting an existing fluent value. */
+      readonly size?: Bounds2["size"];
+      /** Preserves the center query when snapshotting an existing fluent value. */
+      readonly center?: Bounds2["center"];
+    })
+  | {
+      /** Nonnegative XY dimensions in millimetres. */
+      readonly size: Vector2Data;
+      /** 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 +115,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 9.0.0 or newer in major 9.
  */
-export declare function bounds3(input: Bounds3Input): Bounds3;
+export declare function bounds3(input: Bounds3Options): Bounds3;
 
 /** Plain axis-aligned XYZ bounds for interchange; use bounds3 for immutable measurement methods. */
 export declare interface Bounds3Data {
@@ -115,6 +136,25 @@ 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 =
+  | (Bounds3Input & {
+      /** Preserves the size query when snapshotting an existing fluent value. */
+      readonly size?: Bounds3["size"];
+      /** Preserves the center query when snapshotting an existing fluent value. */
+      readonly center?: Bounds3["center"];
+    })
+  | {
+      /** Nonnegative XYZ dimensions in millimetres. */
+      readonly size: Vector3Data;
+      /** 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.
  *
@@ -212,20 +252,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;
@@ -844,6 +882,107 @@ export declare interface HelicalThreadSolidMeshPreflight {
   readonly estimatedTriangles: number;
 }
 
+/**
+ * Declares a +Z hole or blind-pocket cutter with explicit end overrun in millimetres.
+ * 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. Compiled packages require runtime major 9.
+ *
+ * @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;
+  /** 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;
+    }
+);
+
+/** 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.
  *
@@ -1046,10 +1185,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 9.0.0 or newer in major 9.
  *
  * @example Integral-pin hinge with two mounting webs
  * ```ts
@@ -1081,20 +1220,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 +1286,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;
 }
 
@@ -2421,6 +2566,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. */

package/dist/docs/guides/concepts.md

@@ -407,12 +407,15 @@ export const positions = layoutRow([measured, envelope], { gap: 2 });
 
 
 Factories snapshot finite, ordered coordinates with finite extents; zero extents are valid.
+Alternatively construct from nonnegative dimensions with `bounds2({ size: [30, 18] })` or
+`bounds3({ size: [30, 18, 8], center: false })`. Size construction centers on the origin by default;
+size and min/max construction are mutually exclusive.
 `min` and `max` are frozen tuples, and `toData()` returns the value's stable frozen plain record.
 Path `bounds()` queries return matching fluent bounds, or `undefined` for an empty path.
 Mesh and region measurements, inspection results, and engine snapshots retain plain
 `Bounds2Data` or `Bounds3Data`; wrap a measurement when you need fluent queries.
 Compiled Generator packages passing bounds values to host recipes or computed data require
-runtime `8.0.0` or newer in major 8.
+runtime `9.0.0` or newer in major 9.
 
 Keep [`fitBounds`](../reference/geometry/fitBounds.md) and
 [`layoutRow`](../reference/geometry/layoutRow.md) as standalone algorithms: they compute placement