@metamesh/modeling 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @metamesh/modeling
 
+## 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,9 +43,17 @@ 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.
+
 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.
 
 Lengths use millimetres and modeling rotations use degrees. Physical resolution controls curve
@@ -53,6 +61,41 @@ 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 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.
+
+`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.
+
 ## Reuse unchanged work
 
 Use optional `computed` values for expensive geometry or data. Keep ordinary arithmetic and part
@@ -75,19 +118,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, 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>;
@@ -75,9 +75,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: 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 {