@metamesh/modeling 0.15.0 → 0.17.0

package/dist/docs/reference/model/transform3.md

@@ -1,8 +1,8 @@
 # transform3
 
-Creates an immutable XYZ transform, identity by default. Matrices are copied and validated. Calls apply in written order; rotations use degrees and pivots use current world coordinates. Zero scales, singular matrices, nonfinite inputs and zero rotation axes throw GeometryError. Use frameTransform3(frame) as the input for existing orthonormal frame placement.
+Creates an immutable XYZ transform, identity by default.
 
-**transform3**(`matrix?`: [`Transform3Matrix`](Transform3Matrix.md)): [`Transform3`](Transform3-type.md)
+**transform3**(`input?`: [`Transform3Input`](Transform3Input.md)): [`Transform3`](Transform3-type.md)
 
 
 
@@ -10,14 +10,22 @@ Creates an immutable XYZ transform, identity by default. Matrices are copied and
 
 ```ts
 const placement = transform3().rotate([0, 0, 90]).translate([10, 0, 0]);
-placement.applyPoint([1, 0, 0]).toArray(); // approximately [10, 1, 0]
+placement.applyPoint([1, 0, 0]).toData(); // approximately [10, 1, 0]
 ```
 
+Values and data are copied and validated.
+Calls apply in written order; rotations use degrees and pivots use current world coordinates.
+Zero scales, singular matrices, nonfinite inputs and zero rotation axes throw GeometryError.
+Use frameTransform3(frame) as the input for existing orthonormal frame placement.
+
+Use `toData()` for frozen matrix interchange.
+[composeTransform3](../geometry/composeTransform3.md) takes matrices in after, before order.
+
 ## Parameters
 
-<a id="matrix"></a>
+<a id="input"></a>
 
-**`matrix`** · [`Transform3Matrix`](Transform3Matrix.md) · Optional
+**`input`** · [`Transform3Input`](Transform3Input.md) · Optional
 
 
 
@@ -29,11 +37,12 @@ placement.applyPoint([1, 0, 0]).toArray(); // approximately [10, 1, 0]
 ## Related APIs
 
 - [Transform3](Transform3-type.md)
-- [Transform3Matrix](Transform3Matrix.md)
+- [Transform3Input](Transform3Input.md)
 
 ## Guides
 
 - [Named anchors and custom frames](../../guides/recipes.md#named-anchors-and-custom-frames)
 - [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
+- [Fluent values and standalone algorithms](../../guides/concepts.md#choose-fluent-values-or-standalone-algorithms)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/model/tube.md

@@ -74,4 +74,4 @@ tube({ height: 20, outerRadius: 10, innerRadius: 6 });
 - [Choose a primitive](../../guides/recipes.md#choose-a-primitive)
 - [Treated boxes, frustums, and mirrored arrays](../../guides/recipes.md#treated-boxes-frustums-and-mirrored-arrays)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/model/union.md

@@ -69,4 +69,4 @@ Native filled section union; dimensions cannot be mixed.
 - [Choose the Boolean by the material you want](../../guides/fundamentals.md#choose-the-boolean-by-the-material-you-want)
 - [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/model/vector2.md

@@ -1,11 +1,18 @@
 # vector2
 
-Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates. Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates and overflow throw `NON_FINITE_VALUE` GeometryError. Use transform2().applyDirection(value) for rotations and nonuniform scaling.
+Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the coordinates.
 
 **vector2**(`input`: [`Vector2Input`](Vector2Input.md)): [`Vector2`](Vector2-type.md)
 
 
 
+Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
+and overflow throw `NON_FINITE_VALUE` GeometryError.
+Use transform2().applyDirection(value) for rotations and nonuniform scaling.
+
+Use `toData()` for frozen tuple interchange, or
+[normalize2](../geometry/normalize2.md) for tuple-based normalization in numerical loops.
+
 ## Parameters
 
 <a id="input"></a>
@@ -28,5 +35,6 @@ Creates immutable XY arithmetic from a finite tuple or vector, snapshotting the
 
 - [Named anchors and custom frames](../../guides/recipes.md#named-anchors-and-custom-frames)
 - [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
+- [Fluent values and standalone algorithms](../../guides/concepts.md#choose-fluent-values-or-standalone-algorithms)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/model/vector3.md

@@ -1,6 +1,6 @@
 # vector3
 
-Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates. Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates and overflow throw `NON_FINITE_VALUE` GeometryError. Use transform3().applyDirection(value) for rotations and nonuniform scaling.
+Creates immutable XYZ arithmetic from a finite tuple or vector, snapshotting the coordinates.
 
 **vector3**(`input`: [`Vector3Input`](Vector3Input.md)): [`Vector3`](Vector3-type.md)
 
@@ -13,6 +13,13 @@ const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
 const alignment = direction.dot([0, 0, 1]);
 ```
 
+Values and results are finite. Invalid dimensions throw `INVALID_ARGUMENT`; nonfinite coordinates
+and overflow throw `NON_FINITE_VALUE` GeometryError.
+Use transform3().applyDirection(value) for rotations and nonuniform scaling.
+
+Use `toData()` for frozen tuple interchange, or
+[normalize3](../geometry/normalize3.md) for tuple-based normalization in numerical loops.
+
 ## Parameters
 
 <a id="input"></a>
@@ -35,5 +42,6 @@ const alignment = direction.dot([0, 0, 1]);
 
 - [Named anchors and custom frames](../../guides/recipes.md#named-anchors-and-custom-frames)
 - [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
+- [Fluent values and standalone algorithms](../../guides/concepts.md#choose-fluent-values-or-standalone-algorithms)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/model.md

@@ -15,7 +15,12 @@ snapshot.dispose();
 session.dispose();
 ```
 
-Computed data and recipes reuse unchanged work. Part placement and color are separate from local geometry. Section recipes preserve holes through Boolean and offset chains. Construction and composition work without an engine. Ordinary recipes may be reused across sessions regardless of where constructed. Explicit resolution settings are captured; unspecified settings inherit the evaluating host defaults. Observed component selections remain restricted to their originating session. Observations require synchronous host execution. Temporary native allocations belong to the current transaction; sessions may retain bounded evaluated geometry privately. Copied snapshots remain valid after session disposal until they are disposed.
+Computed data and recipes reuse unchanged work. Part placement and color are separate from local geometry. Section recipes preserve holes through Boolean and offset chains.
+
+- **Construction:** recipes and composition require no engine. Ordinary recipes can be reused across sessions, wherever constructed.
+- **Resolution:** explicit settings are captured; unspecified settings inherit the evaluating host's defaults.
+- **Observation:** synchronous host execution is required. Observed component selections stay restricted to their originating session.
+- **Ownership:** the current transaction owns temporary native allocations; sessions may retain bounded evaluated geometry privately. Copied snapshots remain valid after session disposal until you dispose them.
 
 See [host lifecycle](engine.md) and [pure foundations](geometry.md).
 
@@ -23,18 +28,20 @@ See [host lifecycle](engine.md) and [pure foundations](geometry.md).
 
 - [Primitives](model/categories/primitives.md) — Create foundational solid geometry and configure its dimensions and tessellation.
 - [Local resolution](model/categories/resolution.md) — Choose physical curve sampling and explicit native tolerance.
-- [2D Sections](model/categories/sections.md) — Create immutable filled XY shapes, including prepared text and bounded painted SVG.
+- [2D sections](model/categories/sections.md) — Create immutable filled XY shapes, including prepared text and bounded painted SVG.
 - [Sampled paths](model/categories/paths.md) — Reusable immutable planar and spatial trajectories.
-- [Boolean Operations](model/categories/boolean-operations.md) — Combine, intersect and subtract same-dimensional shapes; construct solid envelopes and sums.
-- [Transforms, Vectors & Placement](model/categories/transforms-placement.md) — Calculate with immutable vectors, reuse transforms, and arrange geometry with explicit placement contracts.
-- [Extrude, Revolve & Sweep](model/categories/extrude-revolve-sweep.md) — Turn sections and paths into extruded, lofted, revolved, or swept solids.
+- [Boolean operations](model/categories/boolean-operations.md) — Combine, intersect and subtract same-dimensional shapes; construct solid envelopes and sums.
+- [Transforms, vectors, and placement](model/categories/transforms-placement.md) — Calculate with immutable vectors, reuse transforms, and arrange geometry with explicit placement contracts.
+- [Extrude, revolve, and sweep](model/categories/extrude-revolve-sweep.md) — Turn sections and paths into extruded, lofted, revolved, or swept solids.
+- [Knuckle joints](model/categories/hinges.md) — Compose reusable knuckle joints with independent mounting attachments.
 - [Printable threads](model/categories/threads.md) — Construct compensated thread forms and inspect bounded preflight facts.
-- [Mesh & Inspection](model/categories/mesh-inspection.md) — Convert validated meshes and inspect stable section or solid measurements.
-- [Core Values & Errors](model/categories/core-values-errors.md) — Use the small shared vocabulary for authored geometry, coordinates, paths, and stable failures.
+- [Mesh and inspection](model/categories/mesh-inspection.md) — Convert validated meshes and inspect stable section or solid measurements.
+- [Core values](model/categories/core-values-errors.md) — Use shared coordinate, path, polygon, and bounds data.
+- [Bounds](model/categories/bounds.md) — Measure immutable axis-aligned extents and test positioned containment.
 - [Explicit matching profiles](model/categories/explicit-profiles.md) — Build hollow or multicomponent lofts and sweeps using stable landmarks.
 - [Sampled surfaces](model/categories/bounded-surfaces.md) — Construct bounded heightfields and positive-inside implicit fields.
 - [Solid inspection](model/categories/inspection.md) — Evaluate recipes and copy observations while the host owns native resources.
 - [Model generation](model/categories/generation.md) — Declare typed programs, optional computations, semantic parts and structured diagnostics.
 - [Model contracts](model/categories/contracts.md) — Describe opaque handles, dimensions, manufacturing parts, and completed snapshots.
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/Bounds2Data.md

@@ -0,0 +1,34 @@
+# Bounds2Data
+
+Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods.
+
+## Properties
+
+### max
+
+
+
+`readonly` **max**: [`Vector2Data`](Vector2Data.md)
+
+
+
+Inclusive maximum X/Y coordinates.
+
+***
+
+### min
+
+
+
+`readonly` **min**: [`Vector2Data`](Vector2Data.md)
+
+
+
+Inclusive minimum X/Y coordinates.
+
+
+## Related APIs
+
+- [Vector2Data](Vector2Data.md)
+
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/MAX_VECTOR_FONT_BYTES.md

@@ -4,4 +4,4 @@ Limits apply before parsing or shaping untrusted font data.
 
 `const` **MAX\_VECTOR\_FONT\_BYTES**: `number`
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/Vector2Data.md

@@ -0,0 +1,7 @@
+# Vector2Data
+
+A two-dimensional Cartesian vector or point.
+
+**Vector2Data** = readonly \[`x`: `number`, `y`: `number`\]
+
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorFont.md

@@ -30,7 +30,7 @@ Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and sup
 
   Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
 
-- [`align`](VectorTextLayoutOptions.md#align) · `"left"` \| `"right"` \| `"center"` · Optional
+- [`align`](VectorTextLayoutOptions.md#align) · `"center"` \| `"left"` \| `"right"` · Optional
 
   Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
 
@@ -42,7 +42,7 @@ Shape horizontal lines or one circular line; bounded to 512 UTF-16 units and sup
 
   Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
 
-- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"top"` \| `"bottom"` \| `"center"` \| `"baseline"` · Optional
+- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"center"` \| `"top"` \| `"bottom"` \| `"baseline"` · Optional
 
   Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
 
@@ -88,7 +88,7 @@ Measure the same cached vector layout; all returned lengths are in millimetres.
 
   Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
 
-- [`align`](VectorTextLayoutOptions.md#align) · `"left"` \| `"right"` \| `"center"` · Optional
+- [`align`](VectorTextLayoutOptions.md#align) · `"center"` \| `"left"` \| `"right"` · Optional
 
   Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
 
@@ -100,7 +100,7 @@ Measure the same cached vector layout; all returned lengths are in millimetres.
 
   Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
 
-- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"top"` \| `"bottom"` \| `"center"` \| `"baseline"` · Optional
+- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"center"` \| `"top"` \| `"bottom"` \| `"baseline"` · Optional
 
   Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
 
@@ -146,7 +146,7 @@ Serialize visible horizontal or circular outlines as bounded path-only SVG in ph
 
   Em size in millimetres, greater than zero and at most 10000; not the visible glyph height.
 
-- [`align`](VectorTextLayoutOptions.md#align) · `"left"` \| `"right"` \| `"center"` · Optional
+- [`align`](VectorTextLayoutOptions.md#align) · `"center"` \| `"left"` \| `"right"` · Optional
 
   Place the advance's start, midpoint or end at the datum; defaults to center on arcs, otherwise left.
 
@@ -158,7 +158,7 @@ Serialize visible horizontal or circular outlines as bounded path-only SVG in ph
 
   Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural vertical metrics.
 
-- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"top"` \| `"bottom"` \| `"center"` \| `"baseline"` · Optional
+- [`verticalAlign`](VectorTextLayoutOptions.md#verticalalign) · `"center"` \| `"top"` \| `"bottom"` \| `"baseline"` · Optional
 
   Place the first baseline or complete ink bounds at Y=0; arcs only accept baseline.
 
@@ -183,4 +183,4 @@ Serialize visible horizontal or circular outlines as bounded path-only SVG in ph
 - [VectorTextLayoutOptions](VectorTextLayoutOptions.md)
 - [VectorTextMetrics](VectorTextMetrics.md)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorFontOptions.md

@@ -14,4 +14,4 @@ Identifies the actual weight of a static face, without synthesizing a different
 
 Actual weight of a static face, 1–1000; defaults to 400.
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorTextArcBaseline.md

@@ -50,4 +50,4 @@ Alignment datum in degrees counterclockwise from +X; defaults to 90.
 
 Reading direction around the circle; defaults to clockwise.
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorTextLayout.md

@@ -31,4 +31,4 @@ Exact measurements of these paths and their logical text layout.
 
 - [VectorTextMetrics](VectorTextMetrics.md)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorTextLayoutOptions.md

@@ -12,7 +12,7 @@ Text bounded to 512 UTF-16 units: horizontal lines or one circular line without
 
 
 
-`readonly` `optional` **align?**: `"left"` \| `"right"` \| `"center"`
+`readonly` `optional` **align?**: `"center"` \| `"left"` \| `"right"`
 
 
 
@@ -48,7 +48,7 @@ Baseline spacing in ems, 0.5–5; omitted uses the selected face's natural verti
 
 
 
-`readonly` `optional` **verticalAlign?**: `"top"` \| `"bottom"` \| `"center"` \| `"baseline"`
+`readonly` `optional` **verticalAlign?**: `"center"` \| `"top"` \| `"bottom"` \| `"baseline"`
 
 
 
@@ -108,4 +108,4 @@ Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
 - [VectorTextArcBaseline](VectorTextArcBaseline.md)
 - [VectorTextOptions](VectorTextOptions.md)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorTextMetrics.md

@@ -8,7 +8,7 @@ Text measurements from the same immutable layout that supplies geometry and SVG
 
 
 
-`readonly` **bounds**: [`Bounds2`](Bounds2.md) \| `null`
+`readonly` **bounds**: [`Bounds2Data`](Bounds2Data.md) \| `null`
 
 
 
@@ -89,6 +89,6 @@ Number of lines, including empty and trailing lines; empty text occupies one lin
 
 ## Related APIs
 
-- [Bounds2](Bounds2.md)
+- [Bounds2Data](Bounds2Data.md)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/VectorTextOptions.md

@@ -47,4 +47,4 @@ Tracking between glyph clusters in millimetres, -100–100; defaults to zero.
 
 - [VectorTextLayoutOptions](VectorTextLayoutOptions.md)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/categories/font-preparation.md

@@ -2,7 +2,9 @@
 
 Prepare bounded exact font bytes and reusable vector layouts.
 
-Prepare fonts before modeling. TTF, OTF, and WOFF are parsed directly; WOFF2 decoding loads lazily. No fetching occurs in this library. Font layout returns immutable paths and metrics in Y-up millimetres. Pass that prepared layout to textSection inside a build; do not shape it again.
+Prepare fonts before modeling. TTF, OTF, and WOFF are parsed directly; WOFF2 decoding loads lazily. Supply font bytes yourself; this library never fetches fonts.
+
+Layout returns immutable paths and metrics in Y-up millimetres. Pass the prepared layout to `textSection` inside a build without shaping again.
 
 ## Functions
 
@@ -21,13 +23,13 @@ Prepare fonts before modeling. TTF, OTF, and WOFF are parsed directly; WOFF2 dec
 | [VectorTextLayoutOptions](../VectorTextLayoutOptions.md) | Text bounded to 512 UTF-16 units: horizontal lines or one circular line without wrapping. |
 | [VectorTextMetrics](../VectorTextMetrics.md) | Text measurements from the same immutable layout that supplies geometry and SVG outlines. |
 | [VectorTextOptions](../VectorTextOptions.md) | Shaping controls for a prepared exact font face; all lengths are in millimetres. |
-| [Bounds2](../Bounds2.md) | Axis-aligned bounds in two-dimensional model space. |
+| [Bounds2Data](../Bounds2Data.md) | Plain axis-aligned XY bounds for interchange; use bounds2 for immutable measurement methods. |
 
 ## Type aliases
 
 | API | Summary |
 | --- | --- |
-| [Vector2Tuple](../Vector2Tuple.md) | A two-dimensional Cartesian vector or point. |
+| [Vector2Data](../Vector2Data.md) | A two-dimensional Cartesian vector or point. |
 
 ## Values
 
@@ -35,4 +37,4 @@ Prepare fonts before modeling. TTF, OTF, and WOFF are parsed directly; WOFF2 dec
 | --- | --- |
 | [MAX_VECTOR_FONT_BYTES](../MAX_VECTOR_FONT_BYTES.md) | Limits apply before parsing or shaping untrusted font data. |
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text/prepareVectorFont.md

@@ -43,4 +43,4 @@ async function prepareLabel(fontBytes: Uint8Array) {
 - [VectorFont](VectorFont.md)
 - [VectorFontOptions](VectorFontOptions.md)
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/docs/reference/text.md

@@ -2,7 +2,9 @@
 
 Prepare exact font bytes and shape reusable vector layouts before entering synchronous modeling.
 
-Install `fontkit` for font preparation and `woff2-encoder` for WOFF2 decoding. Import optional exact-font preparation from `@metamesh/modeling/text`. Supply already acquired font bytes; this entrypoint never fetches a font. Shape once during preparation and pass the immutable layout to modeling.
+Install `fontkit` for font preparation and `woff2-encoder` for WOFF2 decoding. Import optional exact-font preparation from `@metamesh/modeling/text`.
+
+Supply font bytes yourself; this entry point never fetches fonts. Shape once during preparation and pass the immutable layout to modeling.
 
 ```ts
 import { prepareVectorFont } from "@metamesh/modeling/text";
@@ -18,4 +20,4 @@ Paths and metrics use Y-up millimetres and a baseline origin. Empty layouts can
 
 - [Font preparation](text/categories/font-preparation.md) — Prepare bounded exact font bytes and reusable vector layouts.
 
-Package: `@metamesh/modeling@0.15.0`.
+Package: `@metamesh/modeling@0.17.0`.

package/dist/engine/construction-operations.js

@@ -141,7 +141,7 @@ export function createConstructionOperations(environment, sections) {
                 assertSamplingCount(value.points.length, "hull", 100_000);
             }
             const first = value.points?.[0];
-            const coordinates = typeof first === "object" && first !== null && "toArray" in first ? first.toArray() : first;
+            const coordinates = typeof first === "object" && first !== null && "toData" in first ? first.toData() : first;
             if (value.points !== undefined && coordinates?.length === 2) {
                 const points = value.points;
                 if (!Array.isArray(points) || points.length < 3)

package/dist/engine/extrusion-finishing.js

@@ -1,3 +1,4 @@
+import { convexContourOffsets } from "../geometry/convex-offset.js";
 import { edgeTreatmentPointCount, edgeTreatmentSetbacks, sampleEdgeTreatment, } from "../geometry/edge-finishing.js";
 import { GeometryError } from "../geometry/errors.js";
 import { resolveExtrusionControls } from "../geometry/extrusion.js";
@@ -19,22 +20,7 @@ export function buildFinishedExtrusion(module, profile, options) {
     if (profile.components.length !== 1 || profile.components[0].holes.length !== 0)
         fail("End treatments require one convex contour without holes; use explicit loft profiles for other topology.");
     const contour = profile.components[0].outer, points = contour.points;
-    const edges = points.map((point, index) => {
-        const next = points[(index + 1) % points.length], dx = next[0] - point[0], dy = next[1] - point[1];
-        const length = Math.hypot(dx, dy);
-        if (!(length > 0) || !Number.isFinite(length))
-            fail("End treatment contours must have distinct finite vertices.");
-        return [dx / length, dy / length];
-    });
-    const miters = edges.map((edge, index) => {
-        const previous = edges[(index + edges.length - 1) % edges.length];
-        const turn = previous[0] * edge[1] - previous[1] * edge[0];
-        if (!(turn > 1e-12))
-            fail("End treatments require a strictly convex counterclockwise contour without collinear vertices.");
-        const denominator = 1 + previous[0] * edge[0] + previous[1] * edge[1];
-        return [(-previous[1] - edge[1]) / denominator, (previous[0] + edge[0]) / denominator];
-    });
-    const magnification = miters.reduce((maximum, [x, y]) => Math.max(maximum, Math.hypot(x, y)), 1);
+    const { magnification, offset } = convexContourOffsets(points, "extrude");
     const sampling = {
         resolution: options.resolution,
         limits: options.limits,
@@ -58,19 +44,6 @@ export function buildFinishedExtrusion(module, profile, options) {
         ...bottomPoints.map(([inset, depth]) => ({ inset, z: depth })),
         ...[...topPoints].reverse().map(([inset, depth]) => ({ inset, z: options.height - depth })),
     ];
-    const offset = (inset) => {
-        const result = points.map(([x, y], index) => [
-            x + miters[index][0] * inset,
-            y + miters[index][1] * inset,
-        ]);
-        for (let index = 0; index < result.length; index++) {
-            const point = result[index], next = result[(index + 1) % result.length], edge = edges[index];
-            if (!point.every(Number.isFinite) ||
-                !((next[0] - point[0]) * edge[0] + (next[1] - point[1]) * edge[1] > 0))
-                fail("End treatment inset collapses or reverses a contour edge.");
-        }
-        return result;
-    };
     offset(Math.max(bottomSize[0], topSize[0])); // fit fails before allocating the full station family
     const stations = rows.map(({ inset, z }) => ({
         z: controls.center ? z - options.height / 2 : z,

package/dist/engine/hole-cutter-operation.js

@@ -0,0 +1,148 @@
+import { convexContourOffsets } from "../geometry/convex-offset.js";
+import { GeometryError } from "../geometry/errors.js";
+import { assertPrimitiveOptions } from "../geometry/primitive-resolvers.js";
+/** Composes cutters inside the evaluating host, retaining deferred Section and sampling ownership. */
+export function createHoleCutterOperation(environment, operations) {
+    return (options) => {
+        environment.assertActive();
+        assertPrimitiveOptions(options, "holeCutter");
+        const fail = (message) => {
+            throw new GeometryError("INVALID_ARGUMENT", message, { operation: "holeCutter" });
+        };
+        const positive = (value, name) => {
+            if (!Number.isFinite(value) || value <= 0)
+                fail(`${name} must be finite and positive.`);
+            return value;
+        };
+        const nonnegative = (value, name) => {
+            if (!Number.isFinite(value) || value < 0)
+                fail(`${name} must be finite and nonnegative.`);
+            return value;
+        };
+        const height = positive(options.height, "height");
+        const circular = options.diameter !== undefined;
+        if (circular === (options.profile !== undefined))
+            fail("Specify exactly one diameter or Section profile.");
+        if (!circular &&
+            (options.recess !== undefined ||
+                options.segments !== undefined ||
+                options.sizing !== undefined))
+            fail("Circular recess, segments and sizing options require a diameter.");
+        if (options.recess !== undefined && options.entryChamfer !== undefined)
+            fail("A recess and entryChamfer are mutually exclusive.");
+        const face = options.face ?? "top";
+        if (face !== "top" && face !== "bottom")
+            fail("face must be top or bottom.");
+        if (options.overrun !== undefined)
+            assertPrimitiveOptions(options.overrun, "holeCutter");
+        const bottom = nonnegative(options.overrun?.bottom ?? 0, "overrun.bottom");
+        const top = nonnegative(options.overrun?.top ?? 0, "overrun.top");
+        const length = positive(height + bottom + top, "extended height");
+        const chamfer = nonnegative(options.entryChamfer ?? 0, "entryChamfer");
+        if (chamfer >= height)
+            fail("entryChamfer must be smaller than height.");
+        const selected = environment.withResolutionDefaults(options);
+        const sampling = { resolution: selected.resolution, limits: selected.limits };
+        if (circular)
+            positive(options.diameter, "diameter");
+        if (options.recess !== undefined) {
+            const recess = options.recess;
+            assertPrimitiveOptions(recess, "holeCutter");
+            positive(recess.diameter, "recess.diameter");
+            if (recess.diameter <= options.diameter)
+                fail("The recess diameter must exceed the bore diameter.");
+            let depth;
+            if (recess.kind === "counterbore")
+                depth = positive(recess.depth, "recess.depth");
+            else if (recess.kind === "countersink") {
+                if (!Number.isFinite(recess.includedAngle) ||
+                    recess.includedAngle <= 0 ||
+                    recess.includedAngle >= 180)
+                    fail("Countersink includedAngle must be between zero and 180 degrees.");
+                depth = positive((recess.diameter - options.diameter) /
+                    (2 * Math.tan((recess.includedAngle * Math.PI) / 360)), "recess depth");
+            }
+            else
+                return fail("Unsupported recess kind.");
+            if (depth > height)
+                fail("The recess must fit within height.");
+            const segments = environment.resolveCircularSegments(recess.diameter / 2, options);
+            const common = { ...sampling, segments, sizing: options.sizing ?? "vertex", center: false };
+            const bore = operations.translate(operations.cylinder({ ...common, diameter: options.diameter, height: length }), [0, 0, -bottom]);
+            const seat = operations.translate(operations.cylinder({
+                ...common,
+                diameter: recess.kind === "counterbore"
+                    ? recess.diameter
+                    : face === "top"
+                        ? [options.diameter, recess.diameter]
+                        : [recess.diameter, options.diameter],
+                height: depth,
+            }), [0, 0, face === "top" ? height - depth : 0]);
+            const excess = face === "top" ? top : bottom;
+            return operations.union([
+                bore,
+                seat,
+                ...(excess === 0
+                    ? []
+                    : [
+                        operations.translate(operations.cylinder({
+                            ...common,
+                            diameter: recess.diameter,
+                            height: excess,
+                        }), [0, 0, face === "top" ? height : -bottom]),
+                    ]),
+            ]);
+        }
+        if (circular) {
+            const openingOverrun = face === "top" ? top : bottom;
+            const segments = environment.resolveCircularSegments(options.diameter / 2 + chamfer + (chamfer === 0 ? 0 : openingOverrun), options);
+            const common = { ...sampling, segments, sizing: options.sizing ?? "vertex", center: false };
+            const bore = operations.translate(operations.cylinder({
+                ...common,
+                diameter: options.diameter,
+                height: length,
+            }), [0, 0, -bottom]);
+            if (chamfer === 0)
+                return bore;
+            // Circular entries retain nominal radial dimensions. Section entries below instead
+            // offset their supplied polygon edges; their faceted envelope remains authoritative.
+            const mouth = options.diameter + 2 * (chamfer + openingOverrun);
+            const entry = operations.translate(operations.cylinder({
+                ...common,
+                diameter: face === "top" ? [options.diameter, mouth] : [mouth, options.diameter],
+                height: chamfer + openingOverrun,
+            }), [0, 0, face === "top" ? height - chamfer : -bottom]);
+            return operations.union([bore, entry]);
+        }
+        const profile = options.profile;
+        if (chamfer === 0)
+            return operations.translate(operations.extrude(profile, { ...sampling, height: length }), [
+                0,
+                0,
+                -bottom,
+            ]);
+        const source = environment.sectionProfileFor(profile);
+        if (source.components.length !== 1 || source.components[0].holes.length !== 0)
+            fail("Entry chamfers require one strictly convex contour without holes.");
+        const component = source.components[0];
+        const offset = convexContourOffsets(component.outer.points, "holeCutter").offset;
+        const rows = face === "top"
+            ? [
+                { z: -bottom, inset: 0 },
+                { z: height - chamfer, inset: 0 },
+                { z: height + top, inset: -chamfer - top },
+            ]
+            : [
+                { z: -bottom, inset: -chamfer - bottom },
+                { z: chamfer, inset: 0 },
+                { z: height + top, inset: 0 },
+            ];
+        const stations = rows.map(({ z, inset }) => ({
+            z,
+            profile: {
+                components: [{ ...component, outer: { ...component.outer, points: offset(inset) } }],
+            },
+        }));
+        return operations.loft(stations, sampling);
+    };
+}