@metamesh/modeling 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @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
+
+- 25561f6: Consolidate sampled paths into immutable `path2` and `path3` values with explicit closure,
+  transformation, resampling, measurements, and closest-point queries. Geometry accepts paths and
+  fluent vector collections directly; tuple path data is named `Path2Data` and `Path3Data`.
+  Remove redundant public path query and transform helpers and move mesh observation to
+  `solid.toTriangleMesh()`. Runtime protocol 7 rejects incompatible older compiled generators.
+
+  Complete dimensional XY patterning and fluent geometry interoperability. Consolidate degree-based
+  attachment options under `AttachOptions` and primitive `attachment`, rename immutable tolerance
+  changes to `withTolerance`, and use `analyzeTriangleMesh` as the single mesh measurement operation.
+  Geometry and text validation report structured errors; host lifecycle and copying contracts are explicit.
+
+  Use concise value factories and semantic degree options, including `anchor3`, `threadProfile`,
+  attachment `spin`, full thread `includedAngle`, and revolution `degrees`. Segment intersections use
+  `castSegment`; stroke APIs share `StrokeOptions`, `StrokeCap`, and `StrokeJoin`. Engines accept a
+  fixed `wasmUrl`. Remove superseded public names and update included consumers.
+
+  Make `components()` return disconnected material with holes and enclosed cavities intact.
+  Inspection uses `componentCount`; snapshots use `partCount`, `vertexCount`, `triangleCount`, and
+  `byteCount`, preserving instance counts and shared-storage accounting.
+
+  Inspect zero-volume Boolean contacts without treating their native boundary remnants as
+  material components. Retain thin material pieces and inward cavity boundaries without a volume
+  tolerance cutoff.
+
+  Keep ordinary component inspection on a certified native fast path, reserving exact arithmetic
+  for ambiguous contact boundaries. Reuse captured generation-data metadata during cache retention,
+  and include retention, commit, and cleanup in total generation timing.
+
+  Preserve shared snapshot buffers and rigid placements in Testkit part assertions. Validate CLI
+  capture bounds by coordinates, independently of JSON property order.
+
+  Use concise input bounds such as `maxTriangles`, `maxVertices`, `minSegments`, and `maxSegments`,
+  including mesh-optimization work budgets. Remove the superseded long option spellings.
+
+  Refresh Testkit sessions when prepared services change, validate CLI callback results against the
+  installed Modeling contract, and reject conflicting buffers for one generated geometry identity
+  and revision. Correct closest-point projection when finite path edges have overflowing squared lengths.
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -43,9 +43,10 @@ try {
 }
 ```
 
-Use `stroke(path, { width, cap, join })` to create a filled Section along a sampled XY path.
-Pure `closestPointOnPath(path, point, { closed })` queries in `/geometry` return the nearest
-boundary position, distance, edge index, and interpolation fraction without initializing an engine.
+Use `path2(points, { closed })` or `path3(points)` for reusable sampled trajectories.
+Paths own closure and chain `transform`, `reverse`, and `resample` immutably. `path.closestPoint(point)`
+returns the nearest boundary position, distance, edge index, and fraction within that edge.
+Use `stroke(path, { width, cap, join })` to fill a sampled XY path without conversion.
 
 Generation is synchronous. Return a single `part(...)` or a readonly array of parts. Shape constructors
 and methods create immutable recipes without an engine. Ordinary recipes can be reused across
@@ -56,6 +57,11 @@ recipes into a snapshot for rendering or export. Sessions own evaluated caches a
 while snapshots remain usable after their session is disposed.
 Dispose both when finished. Export uses the captured geometry without running the model again.
 
+`components()` returns disconnected material pieces with their holes and enclosed cavities intact.
+Inspection `componentCount` counts these pieces; snapshot `stats.partCount` counts declared output
+parts. Snapshot `stats.vertexCount` and `stats.triangleCount` count all instances, while
+`stats.byteCount` counts shared backing storage once.
+
 Lengths use millimetres and modeling rotations use degrees. Physical resolution controls curve
 sampling for both preview and manufacturing output. See the
 [hosting guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/engine/hosting.mdx)
@@ -63,7 +69,7 @@ for browser WASM setup, resource limits, and lifecycle details.
 
 ## Reusable math and shapes
 
-Use immutable fluent vectors 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
@@ -89,12 +95,47 @@ 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
+`AttachOptions` as `solid.attach()`. Rotation references use `pivot`; immutable tolerance changes
+use `solid.withTolerance(value)`. Final part `position` and `rotation` remain rigid placement data,
+separate from reusable geometry.
+
 `Section` is the filled 2D modeling value. Its serialized representation is `RegionData`;
 `polygon({ polygons: data })` constructs a Section from it. `section.toRegionData()` and other
 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. `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
 
@@ -118,12 +159,12 @@ covers dependency tracking, immutable data, cache verification, and part placeme
 
 ## API discovery and ownership
 
-| Import                                                                                                                                      | Use it for                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)             | Immutable shapes, vectors, transforms, and modeling operations |
-| [`@metamesh/modeling/geometry`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/geometry/index.mdx) | Pure paths, profiles, meshes, and calculations                 |
-| [`@metamesh/modeling/engine`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/engine/index.mdx)     | Sessions, snapshots, limits, and 3MF export                    |
-| [`@metamesh/modeling/text`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/text/index.mdx)         | Optional font preparation and vector layouts                   |
+| Import                                                                                                                                      | Use it for                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [`@metamesh/modeling`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/model/index.mdx)             | Immutable shapes, vectors, paths, transforms, and modeling operations |
+| [`@metamesh/modeling/geometry`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/geometry/index.mdx) | Pure paths, profiles, meshes, and calculations                        |
+| [`@metamesh/modeling/engine`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/engine/index.mdx)     | Sessions, snapshots, limits, and 3MF export                           |
+| [`@metamesh/modeling/text`](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/reference/generated/text/index.mdx)         | Optional font preparation and vector layouts                          |
 
 ## Documentation
 
@@ -131,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>;
@@ -70,14 +70,19 @@ export interface GeometryResource extends TriangleMesh {
   /** Facts for the exact local manufacturing buffers. */
   readonly measurements: FinalizedPart["measurements"];
 }
-/** A world-space manufacturing part plus its reusable local renderer resource. */
+/**
+ * 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.
+ */
 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 {
@@ -87,7 +92,10 @@ export interface ModelSnapshot extends FinalizedModel {
   readonly diagnostics: readonly GenerationDiagnostic[];
   /** Known dependency graph; outer reads remain conservative model-wide dependencies. */
   readonly dependencies: ModelDependencies;
-  /** Releases this snapshot's references; idempotent, further access is invalid. */
+  /**
+   * Releases this snapshot's geometry references and invalidates its parts, bounds and stats accessors.
+   * Idempotent. Diagnostics, dependencies and previously obtained parts remain usable.
+   */
   dispose(): void;
 }
 /** Known dependencies for inspection; plain JavaScript bindings do not reveal their parameter origin. */
@@ -144,8 +152,8 @@ export interface Export3mfOptions {
 }
 /** Kernel asset initialization. Networking and Worker ownership remain with the host. */
 export interface ModelEngineOptions {
-  /** Resolves the kernel's WASM asset. Browser hosts supply their bundled asset URL. */
-  readonly locateFile?: () => string;
+  /** Fixed kernel WASM asset URL; defaults to the package asset. Browser hosts supply their emitted URL. */
+  readonly wasmUrl?: string;
   /** Trusted application ceilings. Builds may lower them; generators receive no engine. */
   readonly limits?: Partial<ModelingLimits>;
 }