@metamesh/modeling 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @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
+
+- fbd7276: Standardize immutable value interchange on domain names, Data representations, Input construction
+  forms, and toData(). Rename vector tuples and transform matrices to Vector2Data/Vector3Data and
+  Transform2Data/Transform3Data. Path2Data and Path3Data now preserve dimension, points, and closure;
+  path factories accept complete data records as well as coordinate collections. Advance the host
+  runtime to major 8 for the new value protocol, and update consumers, examples, and references.
+- 1585391: Add immutable `bounds2()` and `bounds3()` values with fluent measurements, positioned containment,
+  and plain-data conversion. Path bounds now return these values. Rename plain bounds records to
+  `Bounds2Data` and `Bounds3Data` across geometry, model snapshots, CLI captures, and Testkit contracts.
+  Bounds values in recipe inputs and computed data use the runtime 8 value interchange protocol.
+- 29e19a5: Add portable knuckle hinge joint recipes and a pure layout resolver, with captive, inserted-pin,
+  and lift-off construction, independent per-half mounting webs, and shared bounded physical sampling.
+  Per-half `barrelChamfer` sets the 45-degree outer-rim setback at both ends of every barrel;
+  web `zMin` places the lower face in the pin-centered frame, both in millimetres.
+  The operation uses the runtime 8 modeling contract.
+
 ## 0.15.0
 
 ### Minor Changes

package/README.md

@@ -69,7 +69,7 @@ for browser WASM setup, resource limits, and lifecycle details.
 
 ## Reusable math and shapes
 
-Use immutable fluent vectors, paths, and transforms for ordinary modeling. Chains apply in written order,
+Use immutable fluent vectors, paths, bounds, and transforms for ordinary modeling. Transform chains apply in written order,
 rotations use degrees, and an optional `pivot` is a fixed world-space point:
 
 ```ts
@@ -95,7 +95,9 @@ const alignment = direction.dot([0, 0, 1]);
 
 Transforms apply separately to points, directions and normals with `applyPoint`, `applyDirection`
 and `applyNormal`. `andThen` composes placements in execution order; `inverse` reverses them.
-Use `toArray()` and `toMatrix()` for interchange. Tuple arithmetic kernels remain available in
+Value types use domain names (`Vector2`, `Transform2`, `Path2`, `Bounds2`); their plain
+representations use `Data`, and accepted construction forms use `Input`. Use `toData()` for
+canonical plain interchange, including path dimension and closure. Tuple arithmetic kernels remain available in
 `/geometry` for dense numerical loops.
 
 Primitive `attachment` maps a local anchor to a target anchor using the same degree-based
@@ -108,8 +110,53 @@ separate from reusable geometry.
 geometry observations need an active synchronous host execution.
 `solid.toTriangleMesh()` follows the same observation rule and returns copied mesh buffers.
 Closed `Path2` values describe traversal, not material; `polygon(path)` fills them and normalizes
-winding. Path transforms preserve traversal under reflection. `toArray()` supplies frozen tuple
-data for interchange; closure remains on the path value.
+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. 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
+and +Z roll guide. Choose `print-in-place`, `inserted-pin`, or `lift-off` construction. Captive
+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 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.
+
+Radial clearance is a per-side allowance; axial gap is the total space between neighboring
+knuckle ends. Both may be zero for ideal contact, which does not establish a printable fit.
+Sampling follows the normal resolution contract; exact circular counts must be divisible by four.
 
 ## Reuse unchanged work
 
@@ -146,8 +193,9 @@ The installed package exposes `@metamesh/modeling/docs/manifest.json`: an exact-
 plain Markdown guides and every public API symbol. Resolve that export from your project to find
 the documentation beside your installed release. Its paths are relative to the manifest.
 With `@metamesh/cli` installed, use `pnpm exec metamesh docs search "your topic"` and
-`pnpm exec metamesh docs show DOCUMENT_ID` for bounded offline lookup. Start with
-`modeling/guide/concepts` and `modeling/guide/hosting` when choosing an execution environment.
+`pnpm exec metamesh docs show DOCUMENT_ID` for bounded offline lookup. Read
+`modeling/guide/standalone-model` for a short complete example, `modeling/guide/concepts` to choose
+geometry, or `modeling/guide/hosting` to run a program in your application.
 
 - [Geometry concepts](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-package.mdx) — coordinates, resolution, and supported modeling paths.
 - [Geometry recipes](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/geometry-recipes.mdx) — primitives, sweeps, lofts, text, SVG, and booleans.

package/dist/api/engine.d.ts

@@ -6,7 +6,7 @@ import type {
   GeometryResolution,
   ModelingLimits,
   ModelProgram,
-  Vector3Tuple,
+  Vector3Data,
 } from "@metamesh/modeling";
 /** Default host resource ceilings for parts, vertices, triangles, and transferable bytes. */
 declare const defaultModelingLimits: Readonly<ModelingLimits>;
@@ -72,6 +72,7 @@ export interface GeometryResource extends TriangleMesh {
 }
 /**
  * A world-space manufacturing part plus its reusable local renderer resource.
+ *
  * Each `positions` or `indices` read returns an owned buffer copy; retain that copy when
  * traversing the mesh. Measurements and placement are immutable data and do not copy on access.
  */
@@ -79,9 +80,9 @@ export interface SnapshotPart extends FinalizedPart {
   /** Validated geometry in local coordinates, independent of placement and appearance. */
   readonly geometry: GeometryResource;
   /** XYZ translation in millimetres after rotation. */
-  readonly position: Vector3Tuple;
+  readonly position: Vector3Data;
   /** Fixed global X, then Y, then Z rotation in degrees. */
-  readonly rotation: Vector3Tuple;
+  readonly rotation: Vector3Data;
 }
 /** Captured immutable revision; disposal never changes another snapshot or an in-flight export. */
 export interface ModelSnapshot extends FinalizedModel {