@metamesh/modeling 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @metamesh/modeling
 
+## 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, and transforms for ordinary modeling. Chains apply in written order,
 rotations use degrees, and an optional `pivot` is a fixed world-space point:
 
 ```ts
@@ -92,9 +98,18 @@ and `applyNormal`. `andThen` composes placements in execution order; `inverse` r
 Use `toArray()` and `toMatrix()` for interchange. 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. `toArray()` supplies frozen tuple
+data for interchange; closure remains on the path value.
 
 ## Reuse unchanged work
 
@@ -118,12 +133,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
 

package/dist/api/engine.d.ts

@@ -70,7 +70,11 @@ 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;
@@ -87,7 +91,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 +151,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>;
 }