@metamesh/modeling 0.0.0-bootstrap.0 → 0.6.0

package/dist/engine/native/scoped-primitives.js

@@ -0,0 +1,127 @@
+import { resolveCylinderPrimitive } from "../../geometry/cylinder.js";
+import { assertMeshAllocationWithinLimits, resolveModelingLimits, } from "../../geometry/model-limits.js";
+import { boxFaceAxes, resolveBoxPrimitive, resolveSpherePrimitive, resolveTorusPrimitive, resolveTubePrimitive, } from "../../geometry/primitive-resolvers.js";
+import { ownScopedManifoldValue, scopedManifoldModule, } from "./context.js";
+import { transform } from "./transforms.js";
+const meshBudget = (vertices, triangles, operation, limits) => assertMeshAllocationWithinLimits(vertices, triangles, 12 * (vertices + triangles), operation, resolveModelingLimits(limits));
+const sphereCounts = (segments) => {
+    const frequency = Math.ceil(segments / 4);
+    return { vertices: 4 * frequency * frequency + 2, triangles: 8 * frequency * frequency };
+};
+/** Creates an axis-aligned scope-owned box. */
+export function box(context, options) {
+    const { center, dimensions, treatment } = resolveBoxPrimitive(options);
+    if (treatment?.kind === "selected") {
+        const module = scopedManifoldModule(context);
+        let result = ownScopedManifoldValue(context, module.Manifold.cube(dimensions, center));
+        for (const { edge, profile } of treatment.cuts) {
+            const section = ownScopedManifoldValue(context, new module.CrossSection([[[0, 0], ...profile.map(([x, y]) => [x, y])]]));
+            const [first, second] = edge.split("-");
+            const [a, signA] = boxFaceAxes[first], [b, signB] = boxFaceAxes[second];
+            const axis = 3 - a - b;
+            const origin = dimensions.map((size) => (center ? -size / 2 : 0));
+            origin[a] = (center ? signA / 2 : signA > 0 ? 1 : 0) * dimensions[a];
+            origin[b] = (center ? signB / 2 : signB > 0 ? 1 : 0) * dimensions[b];
+            const matrix = [0, 0, 0, origin[0], 0, 0, 0, origin[1], 0, 0, 0, origin[2], 0, 0, 0, 1];
+            matrix[b * 4] = -signB;
+            matrix[a * 4 + 1] = -signA;
+            matrix[axis * 4 + 2] = 1;
+            const cutter = ownScopedManifoldValue(context, section.extrude(dimensions[axis]));
+            result = ownScopedManifoldValue(context, result.subtract(transform(context, cutter, matrix)));
+        }
+        meshBudget(result.numVert(), result.numTri(), "box", options.limits);
+        return result;
+    }
+    if (treatment === undefined)
+        meshBudget(8, 12, "box", options.limits);
+    else if (treatment.kind === "chamfer")
+        meshBudget(24, 44, "box", options.limits);
+    else {
+        const vertices = 8 * sphereCounts(treatment.segments).vertices;
+        meshBudget(vertices, 2 * vertices - 4, "box", options.limits);
+    }
+    const module = scopedManifoldModule(context);
+    if (treatment === undefined) {
+        return ownScopedManifoldValue(context, module.Manifold.cube(dimensions, center));
+    }
+    const { inner } = treatment;
+    let treated;
+    if (treatment.kind === "round") {
+        const core = ownScopedManifoldValue(context, module.Manifold.cube(inner, true));
+        const ball = ownScopedManifoldValue(context, module.Manifold.sphere(treatment.radius, treatment.segments));
+        treated = ownScopedManifoldValue(context, core.minkowskiSum(ball));
+    }
+    else {
+        const cores = [
+            ownScopedManifoldValue(context, module.Manifold.cube([dimensions[0], inner[1], inner[2]], true)),
+            ownScopedManifoldValue(context, module.Manifold.cube([inner[0], dimensions[1], inner[2]], true)),
+            ownScopedManifoldValue(context, module.Manifold.cube([inner[0], inner[1], dimensions[2]], true)),
+        ];
+        treated = ownScopedManifoldValue(context, module.Manifold.hull(cores));
+    }
+    return center
+        ? treated
+        : ownScopedManifoldValue(context, treated.translate([dimensions[0] / 2, dimensions[1] / 2, dimensions[2] / 2]));
+}
+/**
+ * Creates a scope-owned cylinder, cone, or frustum along +Z.
+ *
+ * A scalar radius is uniform; a tuple is `[bottom, top]` in +Z order. End
+ * treatments use cap inset and sloped-side setback coordinates; roundovers retain actual radii.
+ */
+export function cylinder(context, options) {
+    const resolved = resolveCylinderPrimitive(options);
+    let vertices;
+    if (resolved.profile === undefined)
+        vertices =
+            resolved.bottomRadius === 0 || resolved.topRadius === 0
+                ? resolved.segments + 1
+                : 2 * resolved.segments;
+    else
+        vertices = resolved.profile.reduce((count, [radius]) => count + (radius > 0 ? resolved.segments : 1), 0);
+    meshBudget(vertices, Math.max(0, 2 * vertices - 4), "cylinder", options.limits);
+    const module = scopedManifoldModule(context);
+    if (resolved.profile === undefined) {
+        return ownScopedManifoldValue(context, module.Manifold.cylinder(resolved.height, resolved.bottomRadius, resolved.topRadius, resolved.segments, resolved.center));
+    }
+    const contour = resolved.profile.map(([radius, z]) => [radius, z]);
+    const section = ownScopedManifoldValue(context, new module.CrossSection([contour]));
+    return ownScopedManifoldValue(context, section.revolve(resolved.segments));
+}
+/** Creates a scope-owned hollow tube along +Z. */
+export function tube(context, options) {
+    resolveTubePrimitive(options);
+    const segments = resolveCylinderPrimitive({ ...options, radius: options.outerRadius }).segments;
+    meshBudget(4 * segments, 8 * segments, "tube", options.limits);
+    const outer = cylinder(context, {
+        ...options,
+        radius: options.outerRadius,
+    });
+    const inner = cylinder(context, {
+        ...options,
+        center: true,
+        height: options.height + 0.02,
+        radius: options.innerRadius,
+    });
+    const positionedInner = options.center === false
+        ? ownScopedManifoldValue(context, inner.translate([0, 0, options.height / 2]))
+        : inner;
+    return ownScopedManifoldValue(context, outer.subtract(positionedInner));
+}
+/** Creates a scope-owned sphere centered at the origin. */
+export function sphere(context, options) {
+    const { radius, segments } = resolveSpherePrimitive(options);
+    const counts = sphereCounts(segments);
+    meshBudget(counts.vertices, counts.triangles, "sphere", options.limits);
+    return ownScopedManifoldValue(context, scopedManifoldModule(context).Manifold.sphere(radius, segments));
+}
+/** Creates a scope-owned torus centered around +Z. */
+export function torus(context, options) {
+    const { profileSegments, sweepSegments } = resolveTorusPrimitive(options);
+    const vertices = profileSegments * sweepSegments;
+    meshBudget(vertices, 2 * vertices, "torus", options.limits);
+    const module = scopedManifoldModule(context);
+    const circle = ownScopedManifoldValue(context, module.CrossSection.circle(options.minorRadius, profileSegments));
+    const translated = ownScopedManifoldValue(context, circle.translate([options.majorRadius, 0]));
+    return ownScopedManifoldValue(context, translated.revolve(sweepSegments));
+}

package/dist/engine/native/scoped-threads.js

@@ -0,0 +1,34 @@
+import { scopedManifoldModule, scopedManifoldScope, trackScopedManifoldValue, } from "./context.js";
+import { internalThreadCutterSolid, preflightInternalThreadCutterSolid, preflightThreadedNutSolid, preflightThreadedRodSolid, threadedNutSolid, threadedRodSolid, threadRidgeSolid, } from "./threads.js";
+/** Converts a runtime-neutral helical ridge mesh into a context-owned Manifold. */
+export function threadRidge(context, options) {
+    const solid = threadRidgeSolid(scopedManifoldModule(context), options, scopedManifoldScope(context));
+    return trackScopedManifoldValue(context, solid);
+}
+/** Preflights the exact compensated direct mesh used by {@link threadedRod}. */
+export function preflightThreadedRod(options) {
+    return preflightThreadedRodSolid(options);
+}
+/** Preflights the exact extended mesh used by {@link internalThreadCutter}. */
+export function preflightInternalThreadCutter(options) {
+    return preflightInternalThreadCutterSolid(options);
+}
+/** Creates a compensated context-owned external threaded rod along +Z. */
+export function threadedRod(context, options) {
+    const solid = threadedRodSolid(scopedManifoldModule(context), options, scopedManifoldScope(context));
+    return trackScopedManifoldValue(context, solid);
+}
+/** Creates a compensated context-owned internal-thread subtraction tool. */
+export function internalThreadCutter(context, options) {
+    const solid = internalThreadCutterSolid(scopedManifoldModule(context), options, scopedManifoldScope(context));
+    return trackScopedManifoldValue(context, solid);
+}
+/** Preflights a nut's exact body, cutter, and chamfer geometry without WASM allocation. */
+export function preflightThreadedNut(options) {
+    return preflightThreadedNutSolid(options);
+}
+/** Creates a context-owned nut body and subtracts its compensated internal thread. */
+export function threadedNut(context, options) {
+    const solid = threadedNutSolid(scopedManifoldModule(context), options, scopedManifoldScope(context));
+    return trackScopedManifoldValue(context, solid);
+}

package/dist/engine/native/threads.js

@@ -0,0 +1,52 @@
+import { buildHelicalThreadRidgeMesh, buildHelicalThreadSolidMesh, } from "../../geometry/mechanical/index.js";
+import { resolveCompensatedThreadSolidMesh, resolveThreadedNutSolid, } from "../../geometry/mechanical/thread-solids.js";
+import { triangleMeshToManifold } from "./adapter.js";
+export { preflightThreadedRodSolid, preflightInternalThreadCutterSolid, preflightThreadedNutSolid, } from "../../geometry/mechanical/thread-solids.js";
+/** Converts the runtime-neutral ridge mesh into a scope-owned Manifold solid. */
+export function threadRidgeSolid(module, options, scope) {
+    return triangleMeshToManifold(module, buildHelicalThreadRidgeMesh(options), scope);
+}
+const compensatedThreadSolid = (module, options, role, scope) => {
+    const resolved = resolveCompensatedThreadSolidMesh(options, role);
+    return compensatedThreadSolidFromResolved(module, resolved, scope);
+};
+const compensatedThreadSolidFromResolved = (module, resolved, scope) => {
+    const { axialExtension, meshOptions } = resolved;
+    const combined = triangleMeshToManifold(module, buildHelicalThreadSolidMesh(meshOptions), scope);
+    return axialExtension === 0 ? combined : scope.own(combined.translate([0, 0, -axialExtension]));
+};
+/** Creates a compensated, scope-owned external threaded rod along +Z. */
+export function threadedRodSolid(module, options, scope) {
+    return compensatedThreadSolid(module, options, "male", scope);
+}
+/**
+ * Creates a compensated, faceting-corrected internal-thread subtraction tool.
+ * The tool extends one pitch beyond both requested faces for a complete
+ * through-thread cavity.
+ */
+export function internalThreadCutterSolid(module, options, scope) {
+    return compensatedThreadSolid(module, options, "female", scope);
+}
+/** Creates a scope-owned nut body and subtracts its compensated internal thread. */
+export function threadedNutSolid(module, options, scope) {
+    const resolved = resolveThreadedNutSolid(options, "threadedNutSolid");
+    const { bevelBottom, bevelTop, outerRadius } = resolved;
+    const { bodySegments: segments, chamferSize: chamfer } = resolved.preflight;
+    const bodyParts = [];
+    if (bevelBottom) {
+        bodyParts.push(scope.own(module.Manifold.cylinder(chamfer, outerRadius - chamfer, outerRadius, segments, false)));
+    }
+    const middleStart = bevelBottom ? chamfer : 0;
+    const middleEnd = options.thickness - (bevelTop ? chamfer : 0);
+    if (middleEnd > middleStart) {
+        const middle = scope.own(module.Manifold.cylinder(middleEnd - middleStart, outerRadius, outerRadius, segments, false));
+        bodyParts.push(middleStart === 0 ? middle : scope.own(middle.translate([0, 0, middleStart])));
+    }
+    if (bevelTop) {
+        const top = scope.own(module.Manifold.cylinder(chamfer, outerRadius, outerRadius - chamfer, segments, false));
+        bodyParts.push(scope.own(top.translate([0, 0, options.thickness - chamfer])));
+    }
+    const body = bodyParts.length === 1 ? bodyParts[0] : scope.own(module.Manifold.union(bodyParts));
+    const cutter = compensatedThreadSolidFromResolved(module, resolved.cutter, scope);
+    return scope.own(body.subtract(cutter));
+}

package/dist/engine/native/transforms.js

@@ -0,0 +1,111 @@
+import { attachTransform } from "../../geometry/anchors.js";
+import { GeometryError } from "../../geometry/errors.js";
+import { assertScopedManifoldValue, ownScopedManifoldValue, } from "./context.js";
+const finiteVector = (value, name, operation) => {
+    if (!value.every(Number.isFinite)) {
+        throw new GeometryError("NON_FINITE_VALUE", `${name} coordinates must be finite.`, {
+            operation,
+        });
+    }
+};
+/** Translates a context-owned solid in world coordinates. */
+export function translate(context, solid, offset) {
+    assertScopedManifoldValue(context, solid);
+    finiteVector(offset, "offset", "translate");
+    if (offset.every((value) => value === 0))
+        return solid;
+    return ownScopedManifoldValue(context, solid.translate(offset));
+}
+/**
+ * Rotates a context-owned solid about global X, then Y, then Z.
+ *
+ * `xyzDegrees` is an XYZ Euler-angle tuple in degrees. Scoped Manifold modeling
+ * uses degrees consistently; callers should convert radians at their boundary.
+ */
+export function rotate(context, solid, xyzDegrees) {
+    assertScopedManifoldValue(context, solid);
+    finiteVector(xyzDegrees, "xyzDegrees", "rotate");
+    if (xyzDegrees.every((value) => value === 0))
+        return solid;
+    return ownScopedManifoldValue(context, solid.rotate(xyzDegrees));
+}
+/** Scales a context-owned solid about the world origin. */
+export function scale(context, solid, factors) {
+    assertScopedManifoldValue(context, solid);
+    const values = typeof factors === "number" ? [factors] : factors;
+    if (!values.every(Number.isFinite) || values.some((value) => value === 0)) {
+        throw new GeometryError("SINGULAR_TRANSFORM", "Scale factors must be finite and non-zero.", {
+            operation: "scale",
+        });
+    }
+    if (values.every((value) => value === 1))
+        return solid;
+    return ownScopedManifoldValue(context, solid.scale(factors));
+}
+/** Reflects a context-owned solid across an origin plane. */
+export function mirror(context, solid, normal) {
+    assertScopedManifoldValue(context, solid);
+    finiteVector(normal, "normal", "mirror");
+    if (normal.every((value) => value === 0)) {
+        throw new GeometryError("INVALID_ARGUMENT", "normal must be non-zero.", {
+            operation: "mirror",
+        });
+    }
+    return ownScopedManifoldValue(context, solid.mirror(normal));
+}
+/** Applies a row-major affine 4x4 transform to a context-owned solid. */
+export function transform(context, solid, matrix) {
+    assertScopedManifoldValue(context, solid);
+    if (!matrix.every(Number.isFinite)) {
+        throw new GeometryError("NON_FINITE_VALUE", "Transform entries must be finite.", {
+            operation: "transform",
+        });
+    }
+    if (matrix[12] !== 0 || matrix[13] !== 0 || matrix[14] !== 0 || matrix[15] !== 1) {
+        throw new GeometryError("INVALID_ARGUMENT", "Transform must be affine with a [0, 0, 0, 1] final row.", { operation: "transform" });
+    }
+    if (matrix.every((value, index) => value === (index === 0 || index === 5 || index === 10 || index === 15 ? 1 : 0))) {
+        return solid;
+    }
+    const determinant = matrix[0] * (matrix[5] * matrix[10] - matrix[6] * matrix[9]) -
+        matrix[1] * (matrix[4] * matrix[10] - matrix[6] * matrix[8]) +
+        matrix[2] * (matrix[4] * matrix[9] - matrix[5] * matrix[8]);
+    if (!Number.isFinite(determinant) || determinant === 0) {
+        throw new GeometryError("SINGULAR_TRANSFORM", "Transform linear component must be non-singular.", { operation: "transform" });
+    }
+    const columnMajor = [
+        matrix[0],
+        matrix[4],
+        matrix[8],
+        matrix[12],
+        matrix[1],
+        matrix[5],
+        matrix[9],
+        matrix[13],
+        matrix[2],
+        matrix[6],
+        matrix[10],
+        matrix[14],
+        matrix[3],
+        matrix[7],
+        matrix[11],
+        matrix[15],
+    ];
+    return ownScopedManifoldValue(context, solid.transform(columnMajor));
+}
+/** Moves a local source anchor onto a world-space target anchor. */
+export function attach(context, solid, source, target, options = {}) {
+    if (options.spinDegrees !== undefined && !Number.isFinite(options.spinDegrees)) {
+        throw new GeometryError("NON_FINITE_VALUE", "spinDegrees must be finite.", {
+            operation: "attach",
+        });
+    }
+    return transform(context, solid, attachTransform(source, target, {
+        ...(options.alignment === undefined ? {} : { alignment: options.alignment }),
+        ...(options.gap === undefined ? {} : { gap: options.gap }),
+        ...(options.spinDegrees === undefined
+            ? {}
+            : { spinRadians: (options.spinDegrees * Math.PI) / 180 }),
+        ...(options.tolerance === undefined ? {} : { tolerance: options.tolerance }),
+    }));
+}

package/dist/engine/operation-environment.js

@@ -0,0 +1,20 @@
+import { resolveModelingLimits } from "../geometry/model-limits.js";
+import { resolveCircularPrimitiveSegments } from "../geometry/primitive-resolution.js";
+/** Applies explicit resolution inheritance once for this bound context. */
+export function createOperationEnvironment(owner, resolution) {
+    const withResolutionDefaults = (value) => {
+        const limits = resolveModelingLimits(value.limits, owner.limits);
+        return {
+            ...value,
+            resolution: {
+                ...resolution,
+                maximumSegments: Math.min(resolution.maximumSegments ?? limits.maxCircularSegments, limits.maxCircularSegments),
+                minimumSegments: Math.min(resolution.minimumSegments ?? 16, limits.maxCircularSegments),
+                ...value.resolution,
+            },
+            limits,
+        };
+    };
+    const resolveCircularSegments = (radius, value) => resolveCircularPrimitiveSegments(radius, withResolutionDefaults(value), "model");
+    return { ...owner, resolution, withResolutionDefaults, resolveCircularSegments };
+}

package/dist/engine/pattern-operations.js

@@ -0,0 +1,36 @@
+import { IDENTITY_TRANSFORM3 } from "../geometry/transform3.js";
+import { gridPatternPlan, linearPatternPlan, pathPatternPlan, radialPatternPlan, } from "./pattern-placements.js";
+/** Private pattern owner; all copies use the shared transform/metadata/lifetime path. */
+export function createPatternOperations(environment, transforms) {
+    const apply = (source, makePlan, operation) => {
+        environment.assertActive();
+        const plan = makePlan();
+        let vertices = 0, triangles = 0;
+        const budget = (solid, multiplier) => {
+            const native = environment.nativeSolid(solid);
+            vertices += native.numVert() * multiplier;
+            triangles += native.numTri() * multiplier;
+            environment.assertMeshAllocation(vertices, triangles, (vertices + triangles) * 12, operation);
+        };
+        if (typeof source !== "function")
+            budget(source, plan.count);
+        const copies = [];
+        for (let index = 0; index < plan.count; index++) {
+            const solid = typeof source === "function" ? source(index) : source;
+            if (typeof source === "function")
+                budget(solid, 1);
+            const matrix = plan.transformAt(index);
+            copies.push(matrix.every((value, i) => value === IDENTITY_TRANSFORM3[i])
+                ? solid
+                : transforms.operations.transform(solid, matrix));
+        }
+        return copies;
+    };
+    const operations = {
+        linearPattern: (source, options) => apply(source, () => linearPatternPlan(options), "linearPattern"),
+        radialPattern: (source, options) => apply(source, () => radialPatternPlan(options), "radialPattern"),
+        gridPattern: (source, options) => apply(source, () => gridPatternPlan(options), "gridPattern"),
+        pathPattern: (source, path, options) => apply(source, () => pathPatternPlan(path, options, environment.limits), "pathPattern"),
+    };
+    return operations;
+}

package/dist/engine/pattern-placements.js

@@ -0,0 +1,176 @@
+import { GeometryError } from "../geometry/errors.js";
+import { cross3, dot3, scale3 } from "../geometry/math/vector3.js";
+import { distributeAlongPath } from "../geometry/paths/planar.js";
+import { normalizeSweepPath } from "../geometry/sweeps/validation.js";
+import { composeTransform3, frameTransform3, IDENTITY_TRANSFORM3, rotationTransform3, translationTransform3, } from "../geometry/transform3.js";
+const fail = (operation, message) => {
+    throw new GeometryError("INVALID_ARGUMENT", message, { operation });
+};
+export function patternCount(count, operation) {
+    if (!Number.isSafeInteger(count) || count < 1)
+        fail(operation, "Pattern count must be a positive safe integer.");
+    if (count > 100_000)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Patterns allow at most 100000 copies.", {
+            operation,
+            details: { requiredCount: count, allowedCount: 100_000 },
+        });
+    return count;
+}
+const finite = (value, operation) => {
+    if (!Number.isFinite(value))
+        throw new GeometryError("NON_FINITE_VALUE", "Pattern dimensions must be finite.", {
+            operation,
+        });
+    return value;
+};
+const vector = (value, operation) => {
+    if (!Array.isArray(value) || value.length !== 3 || !value.every(Number.isFinite))
+        fail(operation, "Pattern vectors require three finite coordinates.");
+    return value;
+};
+const direction = (value, operation) => {
+    vector(value, operation);
+    const maximum = Math.max(...value.map(Math.abs));
+    if (maximum === 0)
+        fail(operation, "Pattern direction must be nonzero.");
+    const scaled = value.map((coordinate) => coordinate / maximum);
+    return scale3(scaled, 1 / Math.hypot(...scaled));
+};
+const optionsObject = (value, operation) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        fail(operation, "Pattern options must be an object.");
+};
+/** Private lazy placements: count/extent validation precedes copy or callback allocation. */
+export function linearPatternPlan(options) {
+    const operation = "linearPattern";
+    optionsObject(options, operation);
+    const supplied = [options.count, options.spacing, options.length].filter((v) => v !== undefined);
+    if (supplied.length !== 2)
+        fail(operation, "Specify exactly two of count, spacing and length.");
+    supplied.forEach((v) => finite(v, operation));
+    let count, spacing;
+    if (options.count !== undefined) {
+        count = patternCount(options.count, operation);
+        if (options.spacing !== undefined) {
+            spacing = options.spacing;
+            if (spacing === 0)
+                fail(operation, "Pattern spacing must be nonzero.");
+        }
+        else {
+            const length = options.length;
+            if (count === 1 && length !== 0)
+                fail(operation, "A one-copy pattern requires zero total length.");
+            if (count > 1 && length === 0)
+                fail(operation, "Pattern total length must be nonzero.");
+            spacing = count === 1 ? 0 : length / (count - 1);
+        }
+    }
+    else {
+        spacing = options.spacing;
+        if (spacing === 0)
+            fail(operation, "Pattern spacing must be nonzero.");
+        const intervals = options.length / spacing;
+        if (!Number.isFinite(intervals) ||
+            intervals < 0 ||
+            Math.abs(intervals - Math.round(intervals)) >
+                Number.EPSILON * 8 * Math.max(1, Math.abs(intervals)))
+            fail(operation, "Length must be a nonnegative whole multiple of the signed spacing.");
+        count = patternCount(Math.round(intervals) + 1, operation);
+    }
+    const axis = direction(options.direction ?? [1, 0, 0], operation);
+    finite(spacing * (count - 1), operation);
+    return { count, transformAt: (index) => translationTransform3(scale3(axis, spacing * index)) };
+}
+export function radialPatternPlan(options) {
+    const operation = "radialPattern";
+    optionsObject(options, operation);
+    const count = patternCount(options.count, operation);
+    const axis = direction(options.axis, operation);
+    const angle = finite((options.angleDegrees / 180) * Math.PI, operation);
+    if (angle === 0)
+        fail(operation, "Pattern angleDegrees must be nonzero.");
+    finite(angle * (count - 1), operation);
+    const center = vector(options.center ?? [0, 0, 0], operation);
+    const before = translationTransform3(scale3(center, -1));
+    const after = translationTransform3(center);
+    return {
+        count,
+        transformAt: (index) => index === 0
+            ? IDENTITY_TRANSFORM3
+            : composeTransform3(after, composeTransform3(rotationTransform3(axis, { radians: angle * index }), before)),
+    };
+}
+export function gridPatternPlan(options) {
+    const operation = "gridPattern";
+    optionsObject(options, operation);
+    const dimensions = options.count?.length;
+    if (!Array.isArray(options.count) ||
+        !Array.isArray(options.spacing) ||
+        (dimensions !== 2 && dimensions !== 3) ||
+        options.spacing?.length !== dimensions)
+        fail(operation, "Grid count and spacing require matching XY or XYZ tuples.");
+    if (options.center !== undefined && typeof options.center !== "boolean")
+        fail(operation, "Grid center must be a boolean.");
+    const counts = [options.count[0], options.count[1], options.count[2] ?? 1];
+    counts.forEach((count) => patternCount(count, operation));
+    const count = patternCount(counts[0] * counts[1] * counts[2], operation);
+    const spacing = [options.spacing[0], options.spacing[1], options.spacing[2] ?? 0];
+    const extent = spacing.map((distance, axis) => {
+        finite(distance, operation);
+        if (counts[axis] > 1 && distance === 0)
+            fail(operation, "Repeated grid axes require nonzero spacing.");
+        return finite(distance * (counts[axis] - 1), operation);
+    });
+    const frame = options.frame === undefined ? IDENTITY_TRANSFORM3 : frameTransform3(options.frame);
+    return {
+        count,
+        transformAt: (index) => {
+            const coordinates = [
+                index % counts[0],
+                Math.floor(index / counts[0]) % counts[1],
+                Math.floor(index / (counts[0] * counts[1])),
+            ];
+            const offset = coordinates.map((value, axis) => value * spacing[axis] - (options.center === true ? extent[axis] / 2 : 0));
+            return composeTransform3(frame, translationTransform3(offset));
+        },
+    };
+}
+export function pathPatternPlan(input, options, limits) {
+    const operation = "pathPattern";
+    optionsObject(options, operation);
+    const count = patternCount(options.count, operation);
+    if (count > limits.maxPathPoints)
+        throw new GeometryError("COMPLEXITY_LIMIT", "Path placements exceed the selected path point ceiling.", {
+            operation,
+            details: { requiredCount: count, allowedCount: limits.maxPathPoints },
+        });
+    if (options.closed !== undefined && typeof options.closed !== "boolean")
+        fail(operation, "Path closed must be a boolean.");
+    if (options.orientation !== undefined &&
+        options.orientation !== "fixed" &&
+        options.orientation !== "tangent")
+        fail(operation, "Path orientation must be fixed or tangent.");
+    const path = normalizeSweepPath(input, options.closed ?? false, operation, limits);
+    // Defer the output placement array until the operation has checked the source copy budget.
+    let placements;
+    return {
+        count,
+        transformAt: (index) => {
+            placements ??= distributeAlongPath(path, count, options.closed ?? false, limits);
+            const placement = placements[index];
+            const translation = translationTransform3(placement.position);
+            if (options.orientation !== "tangent")
+                return translation;
+            const tangent = placement.tangent;
+            const cosine = Math.max(-1, Math.min(1, dot3([0, 0, 1], tangent)));
+            const axis = cross3([0, 0, 1], tangent);
+            const sine = Math.hypot(...axis);
+            const rotation = sine > 1e-12
+                ? rotationTransform3(scale3(axis, 1 / sine), { radians: Math.atan2(sine, cosine) })
+                : cosine < 0
+                    ? rotationTransform3([1, 0, 0], { radians: Math.PI })
+                    : IDENTITY_TRANSFORM3;
+            return composeTransform3(translation, rotation);
+        },
+    };
+}

package/dist/engine/primitive-anchors.js

@@ -0,0 +1,70 @@
+import { boxAnchor3, createAnchor3 } from "../geometry/anchors.js";
+import { resolveCylinderRadii } from "../geometry/cylinder.js";
+const faces = ["left", "right", "back", "front", "bottom", "top"];
+/** Nominal primitive datums; construction validates dimensions before these factories run. */
+export function boxAnchors(options) {
+    const size = typeof options.size === "number" ? [options.size, options.size, options.size] : options.size;
+    const center = options.center === false ? [size[0] / 2, size[1] / 2, size[2] / 2] : [0, 0, 0];
+    return {
+        center: createAnchor3(center, [0, 0, 1]),
+        ...Object.fromEntries(faces.map((face) => [
+            face,
+            boxAnchor3({
+                size,
+                face,
+                ...(options.center === undefined ? {} : { center: options.center }),
+            }),
+        ])),
+    };
+}
+/** Cap planes and nominal radial midsection, with the analytic tapered-side outward normal. */
+function axialAnchors(radii, height, centered) {
+    const bottom = centered ? -height / 2 : 0;
+    const middle = bottom + height / 2;
+    const radius = (radii[0] + radii[1]) / 2;
+    const slope = (radii[1] - radii[0]) / height;
+    return {
+        center: createAnchor3([0, 0, middle], [0, 0, 1]),
+        ...(radii[0] === 0 ? {} : { bottom: createAnchor3([0, 0, bottom], [0, 0, -1]) }),
+        ...(radii[1] === 0 ? {} : { top: createAnchor3([0, 0, bottom + height], [0, 0, 1]) }),
+        right: createAnchor3([radius, 0, middle], [1, 0, -slope], [0, 0, 1]),
+        left: createAnchor3([-radius, 0, middle], [-1, 0, -slope], [0, 0, 1]),
+        front: createAnchor3([0, radius, middle], [0, 1, -slope], [0, 0, 1]),
+        back: createAnchor3([0, -radius, middle], [0, -1, -slope], [0, 0, 1]),
+    };
+}
+/** Cylinder and frustum cap anchors omit an end whose nominal radius is zero. */
+export function cylinderAnchors(options) {
+    return axialAnchors(resolveCylinderRadii(options), options.height, options.center ?? true);
+}
+/** Tube cap centers lie on the nominal cap planes, including the central opening. */
+export function tubeAnchors(options) {
+    return axialAnchors([options.outerRadius, options.outerRadius], options.height, options.center ?? true);
+}
+/** Sphere principal surface points and its origin reference. */
+export function sphereAnchors(options) {
+    const radius = options.radius ?? options.diameter / 2;
+    return boxAnchors({ size: 2 * radius });
+}
+/** Torus envelope-plane datums around its axis; axial centers may lie over the opening. */
+export function torusAnchors(options) {
+    const radial = options.majorRadius + options.minorRadius;
+    return boxAnchors({ size: [2 * radial, 2 * radial, 2 * options.minorRadius] });
+}
+/** Filled XY shapes use world-axis names; top/bottom reference the two sides of the XY plane. */
+export function planarAnchors(size, centered = true) {
+    const x = centered ? 0 : size[0] / 2, y = centered ? 0 : size[1] / 2;
+    return {
+        center: createAnchor3([x, y, 0], [0, 0, 1]),
+        top: createAnchor3([x, y, 0], [0, 0, 1]),
+        bottom: createAnchor3([x, y, 0], [0, 0, -1]),
+        right: createAnchor3([x + size[0] / 2, y, 0], [1, 0, 0], [0, 0, 1]),
+        left: createAnchor3([x - size[0] / 2, y, 0], [-1, 0, 0], [0, 0, 1]),
+        front: createAnchor3([x, y + size[1] / 2, 0], [0, 1, 0], [0, 0, 1]),
+        back: createAnchor3([x, y - size[1] / 2, 0], [0, -1, 0], [0, 0, 1]),
+    };
+}
+/** A construction-origin reference for primitives without meaningful principal side datums. */
+export const originAnchor = () => ({
+    center: createAnchor3([0, 0, 0], [0, 0, 1]),
+});