@metamesh/modeling 0.12.0 → 0.14.0

package/dist/model/operation-dispatch.js

@@ -0,0 +1,13 @@
+import { activeModelContext } from "./execution-binding.js";
+import { declarePortableOperation } from "./recipe-declaration.js";
+/** Resolves a typed operation for this execution without retaining the host context. */
+export function invokeModelOperation(name, args) {
+    return dispatchModelOperation(name, args);
+}
+/** Shared facade dispatcher; portable declaration and execution use the same operation contract. */
+export function dispatchModelOperation(name, args) {
+    const context = activeModelContext();
+    return context === undefined
+        ? declarePortableOperation(name, args, dispatchModelOperation)
+        : Reflect.apply(context[name], undefined, args);
+}

package/dist/model/operations.js

@@ -1,9 +1,5 @@
 import { GeometryError } from "../geometry/errors.js";
-import { currentModelContext } from "./execution-binding.js";
-function invoke(name, args) {
-    const context = currentModelContext(name);
-    return Reflect.apply(context[name], undefined, args);
-}
+import { invokeModelOperation as invoke } from "./operation-dispatch.js";
 function requireProfile(shape, operation) {
     if (typeof shape !== "object" || shape === null || !("components" in shape)) {
         throw new GeometryError("INVALID_ARGUMENT", `${operation}() requires a CorrespondingProfile. Use section.${operation}() for a Section.`, { operation });
@@ -69,11 +65,11 @@ export function sphere(options) {
 export function torus(options) {
     return invoke("torus", [options]);
 }
-export function union(solids) {
-    return invoke("union", [solids]);
+export function union(shapes) {
+    return invoke("union", [shapes]);
 }
-export function intersect(solids) {
-    return invoke("intersect", [solids]);
+export function intersect(shapes) {
+    return invoke("intersect", [shapes]);
 }
 /**
  * Splits a solid into [inside the cutter, outside the cutter].
@@ -134,9 +130,9 @@ export function minkowskiSum(a, b) {
  * @example Mesh import
  * ```ts
  * import { solidFromMesh } from "@metamesh/modeling";
- * import { extrudeMesh, rectangleLoop } from "@metamesh/modeling/geometry";
+ * import { extrudeMesh, rectangleContour } from "@metamesh/modeling/geometry";
  *
- * const mesh = extrudeMesh(rectangleLoop({ size: [20, 12] }), { height: 6 });
+ * const mesh = extrudeMesh(rectangleContour({ size: [20, 12] }), { height: 6 });
  * solidFromMesh(mesh);
  * ```
  */
@@ -160,18 +156,32 @@ export function anchor(shape, name) {
     return invoke("anchor", [shape, name]);
 }
 /**
- * Creates a native filled section without an intermediate Region2 conversion.
+ * Fills one closed millimetre XY outline, explicit outer/hole topology, or compound contours.
+ * Closing edges are implicit. Compound contours use nonzero fill unless selected otherwise.
+ * Explicit topology must be simple and disjoint; compound winding may resolve overlaps.
+ *
+ * @example Extrude a triangular plate
+ * ```ts
+ * polygon([[0, 0], [20, 0], [10, 12]]).extrude({ height: 3 });
+ * ```
  */
-export function sectionFromContours(contours, options) {
-    return invoke("sectionFromContours", [contours, options]);
-}
-/** Imports explicit region topology once. */
-export function fromRegion(region) {
-    return invoke("fromRegion", [region]);
+export function polygon(input) {
+    return invoke("polygon", [input]);
 }
-/** 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.
@@ -314,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.
@@ -336,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
@@ -352,16 +362,20 @@ export function distance(solid, other) {
 export function rayCast(solid, origin, endpoint) {
     return invoke("rayCast", [solid, origin, endpoint]);
 }
-export function components(solid) {
-    return invoke("components", [solid]);
+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
@@ -374,48 +388,15 @@ export function implicit(options) {
 export function heightfield(options) {
     return invoke("heightfield", [options]);
 }
-/**
- * Repeats one solid along a normalized direction.
- *
- * @example Three copies along X
- * ```ts
- * linearPattern(box({ size: 4 }), { count: 3, spacing: 10 });
- * ```
- */
 export function linearPattern(source, options) {
     return invoke("linearPattern", [source, options]);
 }
-/**
- * Repeats one solid about an axis.
- *
- * @example Six copies around Z
- * ```ts
- * const pin = cylinder({ height: 6, radius: 2 }).translate([12, 0, 0]);
- * radialPattern(pin, { count: 6, axis: [0, 0, 1], angleDegrees: 60 });
- * ```
- */
 export function radialPattern(source, options) {
     return invoke("radialPattern", [source, options]);
 }
-/**
- * XY or XYZ copies, optionally centered or placed in an explicit frame.
- *
- * @example Centered XY grid
- * ```ts
- * gridPattern(box({ size: 4 }), { count: [3, 2], spacing: [10, 10], center: true });
- * ```
- */
 export function gridPattern(source, options) {
     return invoke("gridPattern", [source, options]);
 }
-/**
- * Physical arc-length copies along a sampled path, with optional tangent orientation.
- *
- * @example Copies along a bent path
- * ```ts
- * pathPattern(box({ size: 4 }), [[0, 0, 0], [20, 0, 0], [20, 20, 0]], { count: 5 });
- * ```
- */
 export function pathPattern(source, path, options) {
     return invoke("pathPattern", [source, path, options]);
 }

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.12.0",
+  "version": "0.14.0",
   "description": "Scoped solid modeling and pure geometry foundations for Node and browsers.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,6 +18,7 @@
     "CHANGELOG.md",
     "dist/**/*.js",
     "dist/api/*.d.ts",
+    "dist/docs/**",
     "THIRD_PARTY_NOTICES.md",
     "dist/**/*.wasm",
     "dist/engine/kernel/LICENSE",
@@ -40,7 +41,8 @@
     "./text": {
       "types": "./dist/api/text.d.ts",
       "import": "./dist/text/index.js"
-    }
+    },
+    "./docs/manifest.json": "./dist/docs/manifest.json"
   },
   "publishConfig": {
     "access": "public",
@@ -82,15 +84,15 @@
   "scripts": {
     "api:extract:check": "api-extractor run --config config/api-extractor.root.json && api-extractor run --config config/api-extractor.geometry.json && api-extractor run --config config/api-extractor.engine.json && api-extractor run --config config/api-extractor.text.json && node scripts/build-engine-declarations.mjs && node scripts/check-model-declarations.mjs",
     "api:extract:update": "api-extractor run --local --config config/api-extractor.root.json && api-extractor run --local --config config/api-extractor.geometry.json && api-extractor run --local --config config/api-extractor.engine.json && api-extractor run --local --config config/api-extractor.text.json && node scripts/build-engine-declarations.mjs && node scripts/check-model-declarations.mjs",
-    "build": "pnpm run build:declarations && pnpm run api:extract:check && pnpm run runtime:verify",
-    "build:update-api": "pnpm run build:declarations && pnpm run api:extract:update && pnpm run runtime:verify",
+    "build": "pnpm run build:declarations && pnpm run api:extract:check && pnpm run runtime:verify && node ../../scripts/package-docs/build.mjs modeling",
+    "build:update-api": "pnpm run build:declarations && pnpm run api:extract:update && pnpm run runtime:verify && node ../../scripts/package-docs/build.mjs modeling",
     "build:declarations": "node ../../scripts/clean-dist.mjs && node scripts/build-kernel-assets.mjs && tsc -p tsconfig.build.json && node scripts/build-geometry-module.mjs && node scripts/build-modeling-module.mjs",
     "coverage": "node scripts/build-kernel-assets.mjs && vitest run src --coverage",
     "docs": "pnpm run build && typedoc --options typedoc.json",
-    "docs:reference:generate": "pnpm run build:update-api && pnpm run docs:reference:test && node scripts/generate-reference-docs.mjs",
-    "docs:reference:check": "pnpm run build && pnpm run docs:reference:verify",
-    "docs:reference:test": "node --test scripts/reference-model.spec.mjs",
-    "docs:reference:verify": "pnpm run docs:reference:test && node scripts/generate-reference-docs.mjs --check",
+    "docs:reference:generate": "pnpm run build:update-api && pnpm --filter @metamesh/generator-sdk build && pnpm run docs:reference:test && node scripts/reference/generate-reference-docs.mjs",
+    "docs:reference:check": "pnpm run build && pnpm --filter @metamesh/generator-sdk build && pnpm run docs:reference:verify",
+    "docs:reference:test": "node --test scripts/reference/reference-model.spec.mjs",
+    "docs:reference:verify": "pnpm run docs:reference:test && node scripts/reference/generate-reference-docs.mjs --check",
     "fixtures:check": "pnpm run build && pnpm run fixtures:verify",
     "fixtures:verify": "tsc -p fixtures/tsconfig.json --pretty false && node scripts/check-pure-virtual-module.mjs",
     "lint": "node scripts/check-import-boundaries.mjs && eslint .",

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;
-}