@metamesh/modeling 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @metamesh/modeling
 
+## 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,32 @@ 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. 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.
+
+## 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 `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
+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 +172,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 {