@metamesh/modeling 0.13.0 → 0.14.0

package/dist/model/operations.js

@@ -168,13 +168,20 @@ export function anchor(shape, name) {
 export function polygon(input) {
     return invoke("polygon", [input]);
 }
-/** Imports explicit region topology once. */
-export function fromRegion(region) {
-    return invoke("fromRegion", [region]);
-}
-/** Explicit copied topology inspection; not needed for section operations. */
-export function toRegion(section) {
-    return invoke("toRegion", [section]);
+/**
+ * Creates a centered-width native Section along a sampled XY path.
+ *
+ * Shares caps, joins and physical sampling with Geometry's strokePathRegion. Native union
+ * resolves overlapping stroke primitives. Session resolution and resource ceilings apply;
+ * closed paths omit the duplicated seam. Returns an immutable deferred recipe.
+ *
+ * @example Extrude a rounded track
+ * ```ts
+ * stroke([[0, 0], [20, 0], [20, 10]], { width: 3, join: "round", cap: "round" }).extrude({ height: 2 });
+ * ```
+ */
+export function stroke(path, options) {
+    return invoke("stroke", [path, options]);
 }
 /**
  * Filled rectangular section with uniform or independently treated corners.
@@ -317,7 +324,7 @@ export function inspectSolid(solid) {
     return invoke("inspectSolid", [solid]);
 }
 /**
- * Checks whether a same-session solid or filled section contains no geometry.
+ * Checks whether a solid or filled section contains no geometry during host execution.
  *
  * Accepts a 3D Solid or 2D Section handle, not a finalized model or raw triangle mesh.
  * Useful after a Boolean operation whose inputs may not overlap; no mesh is extracted.
@@ -339,7 +346,7 @@ export function isEmpty(shape) {
  * Uses actual geometry, not bounding-box separation or distance between object origins.
  * Contact or overlapping material returns zero, including one solid inside another.
  * The kernel's search range is managed internally; the result is not capped at a caller limit.
- * Empty, expired or foreign-build handles reject. Results follow native numeric precision.
+ * Empty geometry and component selections from another session reject. Results follow native numeric precision.
  *
  * @example Measure the gap between two blocks
  * ```ts
@@ -358,13 +365,17 @@ export function rayCast(solid, origin, endpoint) {
 export function components(shape) {
     return invoke("components", [shape]);
 }
-/** Bounded positive-inside implicit field constructor. */
+/**
+ * Bounded positive-inside implicit field constructor.
+ * The retained callback must capture independent immutable inputs, not live session readers or parameters.
+ */
 export function implicit(options) {
     return invoke("implicit", [options]);
 }
 /**
  * Closed rectilinear top above a flat base, with uniform or explicit XY coordinates.
  * Samples each grid height once; center-error triangulation also samples each cell centre.
+ * The retained callback must capture independent immutable inputs, not live session readers or parameters.
  *
  * @example Heightfield
  * ```ts

package/dist/model/recipe-declaration.js

@@ -0,0 +1,193 @@
+import { GeometryError } from "../geometry/errors.js";
+import { defaultModelingLimits } from "../geometry/model-limits.js";
+import { gridPatternPlan, linearPatternPlan, pathPatternPlan, radialPatternPlan, } from "../geometry/patterns/placements.js";
+import { restrictTransform3 } from "../geometry/transform2.js";
+import { geometryRecipe, recordGeometryRecipe, } from "./geometry-recipes.js";
+import { captureRecipeInputs } from "./immutable-generation-data.js";
+// Every public operation must explicitly choose its realization and result behavior.
+const operationBehaviors = {
+    withResolution: "resolution",
+    box: "solid",
+    cylinder: "solid",
+    tube: "solid",
+    sphere: "solid",
+    torus: "solid",
+    heightfield: "solid",
+    implicit: "solid",
+    extrude: "solid",
+    revolve: "solid",
+    loft: "solid",
+    sweep: "solid",
+    compose: "solid",
+    minkowskiSum: "solid",
+    solidFromMesh: "solid",
+    setTolerance: "solid",
+    threadRidge: "solid",
+    threadedRod: "solid",
+    threadedNut: "solid",
+    internalThreadCutter: "solid",
+    polygon: "section",
+    stroke: "section",
+    rectangle: "section",
+    circle: "section",
+    ellipse: "section",
+    regularPolygon: "section",
+    star: "section",
+    projectSection: "section",
+    sliceSection: "section",
+    textSection: "section",
+    svgSection: "section",
+    svgPathSection: "section",
+    translate: "preserve",
+    rotate: "preserve",
+    scale: "preserve",
+    mirror: "preserve",
+    transform: "preserve",
+    offset: "preserve",
+    simplify: "preserve",
+    withAnchors: "preserve",
+    attach: "preserve",
+    union: "preserve",
+    intersect: "preserve",
+    subtract: "preserve",
+    hull: "preserve",
+    toTriangleMesh: "observation",
+    toRegionData: "observation",
+    inspectSection: "observation",
+    inspectSolid: "observation",
+    isEmpty: "observation",
+    distance: "observation",
+    rayCast: "observation",
+    anchor: "observation",
+    matchProfiles: "observation",
+    preflightThreadedRod: "observation",
+    preflightInternalThreadCutter: "observation",
+    preflightThreadedNut: "observation",
+    split: "split",
+    splitByPlane: "split",
+    components: "components",
+    linearPattern: "pattern",
+    radialPattern: "pattern",
+    gridPattern: "pattern",
+    pathPattern: "pattern",
+};
+/**
+ * Creates the shared declaration surface for portable recipes or one active revision.
+ * Handles retain captured inputs; native results remain private to the host realization owner.
+ */
+export function createRecipeContext(resolution, declaration) {
+    return Object.freeze(Object.fromEntries(Object.keys(operationBehaviors).map((key) => [
+        key,
+        (...supplied) => declareRecipeOperation(key, resolution, supplied, declaration),
+    ])));
+}
+/** Captures and validates inputs before deciding whether an operation needs native geometry now. */
+export function declareRecipeOperation(operation, resolution, supplied, declaration) {
+    declaration.assertActive?.();
+    const behavior = operationBehaviors[operation];
+    if (behavior === "observation" || behavior === "components")
+        requireRealization(declaration, operation);
+    if (behavior === "resolution") {
+        const nextResolution = Object.freeze({ ...resolution, ...supplied[0] });
+        return createRecipeContext(nextResolution, declaration);
+    }
+    if (behavior === "pattern")
+        return declarePattern(operation, resolution, supplied, declaration);
+    const args = captureRecipeInputs(supplied);
+    const call = { method: operation, args, resolution };
+    if (behavior === "observation")
+        return requireRealization(declaration, operation).invoke(call);
+    const recipe = {
+        kind: resultKind(behavior, args[0]),
+        call,
+    };
+    if (behavior === "split")
+        return Object.freeze([
+            recordGeometryRecipe({ ...recipe, index: 0 }, declaration.dispatch),
+            recordGeometryRecipe({ ...recipe, index: 1 }, declaration.dispatch),
+        ]);
+    if (behavior === "components") {
+        // Cardinality and ordering are observations of this session's sampled geometry.
+        // Retain native precision rather than baking the selected component through mesh interchange.
+        const realization = requireRealization(declaration, operation);
+        const values = realization.evaluate(call);
+        return Object.freeze(values.map((_value, index) => recordGeometryRecipe({ ...recipe, index, observedSession: realization.session }, declaration.dispatch)));
+    }
+    return recordGeometryRecipe(recipe, declaration.dispatch);
+}
+/** Declares a portable recipe without resolving an engine, resolution or session identity. */
+export function declarePortableOperation(operation, args, dispatch) {
+    return declareRecipeOperation(operation, undefined, args, {
+        limits: defaultModelingLimits,
+        dispatch,
+    });
+}
+function requireRealization(declaration, operation) {
+    if (declaration.realization === undefined)
+        throw new GeometryError("INVALID_ARGUMENT", "Geometry observations require an active model execution.", { operation });
+    return declaration.realization;
+}
+function resultKind(behavior, input) {
+    if (behavior === "section")
+        return "section";
+    if (behavior === "preserve" || behavior === "components")
+        return inputKind(input);
+    return "solid";
+}
+function inputKind(value) {
+    if (Array.isArray(value))
+        return inputKind(value[0]);
+    if (typeof value !== "object" || value === null)
+        return "solid";
+    const recipe = geometryRecipe(value);
+    if (recipe !== undefined)
+        return recipe.kind;
+    if ("sections" in value)
+        return "section";
+    if ("points" in value &&
+        Array.isArray(value.points) &&
+        Array.isArray(value.points[0]) &&
+        value.points[0].length === 2)
+        return "section";
+    return "solid";
+}
+/** Runs every factory during declaration; each placed copy stays deferred until it is used. */
+function declarePattern(operation, resolution, supplied, declaration) {
+    const plan = patternPlan(operation, supplied, declaration.limits);
+    if (plan.count > declaration.limits.maxVertices)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Pattern declaration exceeds execution limits.", {
+            operation,
+        });
+    const source = supplied[0];
+    const copies = [];
+    let kind;
+    for (let index = 0; index < plan.count; index++) {
+        const shape = typeof source === "function"
+            ? source(index)
+            : source;
+        const currentKind = inputKind(shape);
+        if (kind !== undefined && kind !== currentKind)
+            throw new GeometryError("INVALID_ARGUMENT", "Pattern factories must return one shape dimension.", {
+                operation,
+            });
+        kind = currentKind;
+        const matrix = plan.transformAt(index);
+        copies.push(declareRecipeOperation("transform", resolution, [shape, kind === "section" ? restrictTransform3(matrix) : matrix], declaration));
+    }
+    return Object.freeze(copies);
+}
+function patternPlan(operation, supplied, limits) {
+    const options = supplied[1];
+    switch (operation) {
+        case "linearPattern":
+            return linearPatternPlan(options);
+        case "radialPattern":
+            return radialPatternPlan(options);
+        case "gridPattern":
+            return gridPatternPlan(options);
+        case "pathPattern":
+            return pathPatternPlan(options, supplied[2], limits);
+        default:
+            throw new Error(`Operation ${operation} does not declare a pattern.`);
+    }
+}

package/dist/model/shape-handles.js

@@ -1,8 +1,12 @@
 import { currentModelContext } from "./execution-binding.js";
+const dispatchers = new WeakMap();
 // Resolve the current transaction on every call: cached recipes outlive the revision that
 // created them. Neither instances nor these shared methods retain an execution or native value.
 function forward(name) {
     return function (...args) {
+        const dispatch = dispatchers.get(this);
+        if (dispatch !== undefined)
+            return dispatch(name, [this, ...args]);
         const context = currentModelContext(name);
         return Reflect.apply(context[name], undefined, [this, ...args]);
     };
@@ -29,16 +33,23 @@ const solidPrototype = prototype({
 });
 const sectionPrototype = prototype({
     ...common,
+    toRegionData: forward("toRegionData"),
     offset: forward("offset"),
     extrude: forward("extrude"),
     revolve: forward("revolve"),
     sweep: forward("sweep"),
 });
 /** Creates only the immutable public facade; the caller owns its private geometry identity. */
-export function createSolidHandle() {
-    return Object.freeze(Object.create(solidPrototype));
+export function createSolidHandle(dispatch, properties) {
+    const handle = Object.freeze(Object.create(solidPrototype, properties ?? {}));
+    if (dispatch !== undefined)
+        dispatchers.set(handle, dispatch);
+    return handle;
 }
 /** Creates only the immutable public facade; the caller owns its private geometry identity. */
-export function createSectionHandle() {
-    return Object.freeze(Object.create(sectionPrototype));
+export function createSectionHandle(dispatch, properties) {
+    const handle = Object.freeze(Object.create(sectionPrototype, properties ?? {}));
+    if (dispatch !== undefined)
+        dispatchers.set(handle, dispatch);
+    return handle;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamesh/modeling",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Scoped solid modeling and pure geometry foundations for Node and browsers.",
   "license": "Apache-2.0",
   "repository": {

package/dist/docs/reference/geometry/Region.md

@@ -1,14 +0,0 @@
-# Region
-
-A two-dimensional region represented by disjoint filled polygons.
-
-**Region** = readonly [`Polygon`](Polygon.md)[]
-
-
-
-
-## Related APIs
-
-- [Polygon](Polygon.md)
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/geometry/Transform3.md

@@ -1,12 +0,0 @@
-# Transform3
-
-A row-major affine 4x4 matrix applied to column vectors.
-
-**Transform3** = readonly \[`m00`: `number`, `m01`: `number`, `m02`: `number`, `m03`: `number`, `m10`: `number`, `m11`: `number`, `m12`: `number`, `m13`: `number`, `m20`: `number`, `m21`: `number`, `m22`: `number`, `m23`: `number`, `m30`: `number`, `m31`: `number`, `m32`: `number`, `m33`: `number`\]
-
-
-
-Translation occupies indices 3, 7, and 11. The final row must be
-`[0, 0, 0, 1]` within the active geometry tolerance.
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/geometry/Vector2.md

@@ -1,7 +0,0 @@
-# Vector2
-
-A two-dimensional Cartesian vector or point.
-
-**Vector2** = readonly \[`x`: `number`, `y`: `number`\]
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/geometry/Vector3.md

@@ -1,7 +0,0 @@
-# Vector3
-
-A three-dimensional Cartesian vector or point.
-
-**Vector3** = readonly \[`x`: `number`, `y`: `number`, `z`: `number`\]
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/geometry/rotateAroundAxis3.md

@@ -1,38 +0,0 @@
-# rotateAroundAxis3
-
-Rotates a vector right-handed around an axis by `angle` radians.
-
-`const` **rotateAroundAxis3**: (`vector`: [`Vector3`](Vector3.md), `axis`: [`Vector3`](Vector3.md), `angle`: `number`) => [`Vector3`](Vector3.md)
-
-
-
-## Parameters
-
-<a id="vector"></a>
-
-**`vector`** · [`Vector3`](Vector3.md) · Required
-
-
-
-<a id="axis"></a>
-
-**`axis`** · [`Vector3`](Vector3.md) · Required
-
-
-
-<a id="angle"></a>
-
-**`angle`** · `number` · Required
-
-
-
-## Returns
-
-[`Vector3`](Vector3.md)
-
-
-## Related APIs
-
-- [Vector3](Vector3.md)
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/geometry/transformRegion.md

@@ -1,40 +0,0 @@
-# transformRegion
-
-Transforms an explicit outer/hole region with reflection-safe winding correction.
-
-**transformRegion**(`region`: [`Region`](Region.md), `transform`: [`Transform3`](Transform3.md), `tolerance?`: [`GeometryToleranceOptions`](GeometryToleranceOptions.md)): [`Region`](Region.md)
-
-
-
-## Parameters
-
-<a id="region"></a>
-
-**`region`** · [`Region`](Region.md) · Required
-
-
-
-<a id="transform"></a>
-
-**`transform`** · [`Transform3`](Transform3.md) · Required
-
-
-
-<a id="tolerance"></a>
-
-**`tolerance`** · [`GeometryToleranceOptions`](GeometryToleranceOptions.md) · Optional
-
-
-
-## Returns
-
-[`Region`](Region.md)
-
-
-## Related APIs
-
-- [GeometryToleranceOptions](GeometryToleranceOptions.md)
-- [Region](Region.md)
-- [Transform3](Transform3.md)
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/model/Transform2.md

@@ -1,15 +0,0 @@
-# Transform2
-
-Row-major affine XY matrix. Translation occupies m02/m12; final row is [0, 0, 1].
-
-**Transform2** = readonly \[`m00`: `number`, `m01`: `number`, `m02`: `number`, `m10`: `number`, `m11`: `number`, `m12`: `number`, `m20`: `number`, `m21`: `number`, `m22`: `number`\]
-
-
-
-
-## Guides
-
-- [Named anchors and custom frames](../../guides/recipes.md#named-anchors-and-custom-frames)
-- [Primitive booleans and repeated placement](../../guides/recipes.md#primitive-booleans-and-repeated-placement)
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/model/toRegion.md

@@ -1,33 +0,0 @@
-# toRegion
-
-Explicit copied topology inspection; not needed for section operations.
-
-**toRegion**(`section`: [`Section`](Section.md)): [`Region`](Region.md)
-
-
-
-## Parameters
-
-<a id="section"></a>
-
-**`section`** · [`Section`](Section.md) · Required
-
-
-
-## Returns
-
-[`Region`](Region.md)
-
-
-## Related APIs
-
-- [Region](Region.md)
-- [Section](Section.md)
-
-## Guides
-
-- [Section, hole, offset, and extrusion](../../guides/recipes.md#section-hole-offset-and-extrusion)
-- [SVG sections: fills and strokes are different inputs](../../guides/concepts.md#svg-sections-fills-and-strokes-are-different-inputs)
-- [Text and font variability](../../guides/concepts.md#text-and-font-variability)
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/docs/reference/text/Vector2.md

@@ -1,7 +0,0 @@
-# Vector2
-
-A two-dimensional Cartesian vector or point.
-
-**Vector2** = readonly \[`x`: `number`, `y`: `number`\]
-
-Package: `@metamesh/modeling@0.13.0`.

package/dist/engine/geometry-recipes.js

@@ -1,12 +0,0 @@
-import { createSectionHandle, createSolidHandle } from "../model/shape-handles.js";
-const recipes = new WeakMap();
-/** Reads private recipe metadata without requiring an execution context. */
-export const geometryRecipe = (value) => recipes.get(value);
-/** Recognizes only opaque recipe handles issued by this engine. */
-export const isGeometryRecipe = (value) => typeof value === "object" && value !== null && recipes.has(value);
-/** Creates an immutable opaque handle for a recorded operation. */
-export function recordGeometryRecipe(recipe) {
-    const handle = recipe.kind === "solid" ? createSolidHandle() : createSectionHandle();
-    recipes.set(handle, recipe);
-    return handle;
-}

package/dist/engine/pattern-transform.js

@@ -1,9 +0,0 @@
-import { GeometryError } from "../geometry/errors.js";
-/** Converts only plane-preserving pattern placements to a Section's affine XY transform. */
-export function sectionPatternTransform(matrix, operation) {
-    if (Math.abs(matrix[8]) > 1e-10 || Math.abs(matrix[9]) > 1e-10 || Math.abs(matrix[11]) > 1e-10)
-        throw new GeometryError("INVALID_ARGUMENT", "Section patterns must preserve the XY plane.", {
-            operation,
-        });
-    return [matrix[0], matrix[1], matrix[3], matrix[4], matrix[5], matrix[7], 0, 0, 1];
-}