@metamesh/modeling 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @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
+
+- be565ad: Add native `stroke()` sections and pure `closestPointOnPath()` queries. Correct face-sized
+  circular sampling and odd-pinion internal gear motion. Native stroke uses the current runtime
+  contract so older hosts reject packages requiring the new operation before execution.
+- bd33fb0: Add immutable `vector2`/`vector3` arithmetic and reusable `transform2`/`transform3` placements at the Modeling root and pure Geometry entry. Transform calls apply in written order with `andThen` composition, named world-space `{ pivot }` options, inversion and explicit XY/XYZ conversion. Points, directions and inverse-transpose unit normals have distinct application methods; each returns a fluent vector. Shapes and path helpers accept transforms directly. Tuple kernels remain available for numerical loops. Fluent class initialization supports tree shaking so consumers can omit unused value implementations.
+
+  Shape construction and composition now work without an initialized engine. Ordinary recipes are portable regardless of where constructed. Explicit resolution settings are captured; unspecified settings inherit the evaluating host's defaults. Native caches and computed readers remain session-owned. Observed `components()` selections and recipes using them can only be evaluated in their originating session. Geometry observations still require synchronous host execution. This changes the Modeling runtime protocol to version 6 and requires matching host and authored/package runtimes.
+
+  Breaking Preview changes: `Vector2`/`Vector3` and `Transform2`/`Transform3` name fluent values; raw data types are `Vector2Tuple`/`Vector3Tuple` and `Transform2Matrix`/`Transform3Matrix`. Rename filled serialized geometry to `RegionData`/`PolygonData`; use `polygon({ polygons: data })` and `section.toRegionData()` instead of `fromRegion`/`toRegion`. `transformRegionData` remains a low-level preparation utility. Planar helpers accept only XY transforms or canonical 3x3 matrices; crossing dimensions requires explicit `to2D`/`to3D`. Remove the public radians-only `rotateAroundAxis3` helper; modeling rotations use degrees, while raw `rotationTransform3` requires an explicit degrees or radians object. Vector normalization now uses structured geometry errors and validates epsilon.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -43,16 +43,74 @@ try {
 }
 ```
 
+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; the engine evaluates them into a snapshot for rendering or
-export. Sessions own reusable work, while snapshots remain usable after their session is disposed.
+and methods create immutable recipes without an engine. Ordinary recipes can be reused across
+sessions regardless of where they were constructed. Explicit resolution settings are captured;
+unspecified settings inherit the evaluating host's defaults. Observed `components()` selections
+and recipes using them can only be evaluated in their originating session. The engine evaluates
+recipes into a snapshot for rendering or export. Sessions own evaluated caches and native resources,
+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)
 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,
+rotations use degrees, and an optional `pivot` is a fixed world-space point:
+
+```ts
+import { polygon, transform2, vector3 } from "@metamesh/modeling";
+
+const placement = transform2()
+  .rotate(30, { pivot: [10, 5] })
+  .scale([2, 1])
+  .translate([20, 0]);
+const body = polygon({
+  outer: [
+    [0, 0],
+    [20, 0],
+    [10, 10],
+  ],
+  holes: [],
+})
+  .transform(placement)
+  .extrude({ height: 8 });
+const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+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
+`/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
 
 Use optional `computed` values for expensive geometry or data. Keep ordinary arithmetic and part
@@ -75,19 +133,19 @@ 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)             | Solids, sections, 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
 
 The installed package exposes `@metamesh/modeling/docs/manifest.json`: an exact-version index of
 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 Testkit installed, use `pnpm exec metamesh docs search "your topic"` and
+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.
 

package/dist/api/engine.d.ts

@@ -6,7 +6,7 @@ import type {
   GeometryResolution,
   ModelingLimits,
   ModelProgram,
-  Vector3,
+  Vector3Tuple,
 } from "@metamesh/modeling";
 /** Default host resource ceilings for parts, vertices, triangles, and transferable bytes. */
 declare const defaultModelingLimits: Readonly<ModelingLimits>;
@@ -70,14 +70,18 @@ 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: Vector3;
+  readonly position: Vector3Tuple;
   /** Fixed global X, then Y, then Z rotation in degrees. */
-  readonly rotation: Vector3;
+  readonly rotation: Vector3Tuple;
 }
 /** Captured immutable revision; disposal never changes another snapshot or an in-flight export. */
 export interface ModelSnapshot extends FinalizedModel {
@@ -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>;
 }