brepjs 18.101.0 → 18.103.0

package/dist/brepjs.cjs

@@ -2132,6 +2132,139 @@ function roof(w, options) {
 	}
 }
 //#endregion
+//#region src/operations/instanceFns.ts
+/**
+* Transform-only instancing — hold ONE source shape + N placements without
+* copying the kernel shape. Real geometry (a Compound, or a fused solid) or a
+* render payload (one mesh + N matrices) is produced only on demand.
+*
+* A 10x10 grid is 1 solid + 100 transforms, not 100 booleans. Materialize-on-
+* export keeps the kernel work deferred; `instancedMesh` meshes the source once
+* for an instanced (e.g. three.js InstancedMesh) preview.
+*/
+function translation(v) {
+	return [
+		[
+			1,
+			0,
+			0,
+			v[0]
+		],
+		[
+			0,
+			1,
+			0,
+			v[1]
+		],
+		[
+			0,
+			0,
+			1,
+			v[2]
+		],
+		[
+			0,
+			0,
+			0,
+			1
+		]
+	];
+}
+function isVec3Array(p) {
+	const first = p[0];
+	return first !== void 0 && typeof first[0] === "number";
+}
+function make(source, placements, grid) {
+	return {
+		__instanced: true,
+		source,
+		placements,
+		grid,
+		[Symbol.dispose]() {
+			source[Symbol.dispose]();
+		}
+	};
+}
+/** Type guard for an InstancedShape. */
+function isInstanced(x) {
+	return typeof x === "object" && x !== null && x.__instanced === true;
+}
+/**
+* Instance a shape across explicit placements. `Vec3[]` is translate-only sugar
+* for `Matrix4x4[]`. The source is owned by the returned container.
+*/
+function instance(source, placements) {
+	return make(source, isVec3Array(placements) ? placements.map(translation) : placements.map((m) => m.map((row) => [...row])));
+}
+/** Instance a shape across a cols x rows grid in the XY plane. */
+function instanceGrid(source, opts) {
+	const { cols, rows, pitchX, pitchY } = opts;
+	if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 1 || rows < 1) throw new RangeError(`instanceGrid: cols and rows must be positive integers, got ${cols}x${rows}`);
+	const placements = [];
+	for (let i = 0; i < cols; i++) for (let j = 0; j < rows; j++) placements.push(translation([
+		i * pitchX,
+		j * pitchY,
+		0
+	]));
+	return make(source, placements, {
+		cols,
+		rows,
+		pitchX,
+		pitchY
+	});
+}
+/** Number of placements. */
+function instanceCount(inst) {
+	return inst.placements.length;
+}
+/**
+* Produce real geometry: a Compound of N placed copies (default), or a single
+* fused solid (`fuse: true`, 3D only). This is where the N kernel transforms
+* happen. A grid-built instance fuses via the faster kernel `gridPattern`.
+*/
+function materialize(inst, opts = {}) {
+	const { source, placements, grid } = inst;
+	if (placements.length === 0) return require_errors.err(require_errors.validationError("INSTANCE_EMPTY", "materialize: instance has no placements"));
+	if (opts.fuse) {
+		if (!require_shapeTypes.isShape3D(source)) return require_errors.err(require_errors.validationError("MATERIALIZE_NOT_3D", "materialize({fuse:true}) requires a 3D source shape"));
+		if (grid) return require_threadFns.gridPattern(source, [
+			1,
+			0,
+			0
+		], [
+			0,
+			1,
+			0
+		], grid.cols, grid.rows, grid.pitchX, grid.pitchY);
+		return combine(source, placements, true);
+	}
+	return combine(source, placements, false);
+}
+function combine(source, placements, fuse) {
+	const copies = [];
+	for (const m of placements) {
+		const placed = require_shapeFns.applyMatrix(source, m);
+		if (!placed.ok) {
+			for (const c of copies) c[Symbol.dispose]();
+			return placed;
+		}
+		copies.push(placed.value);
+	}
+	const result = fuse ? require_solidBuilders.fuseAll(copies, { unsafe: true }) : require_errors.ok(require_solidBuilders.makeCompound(copies));
+	for (const c of copies) if (!result.ok || c !== result.value) c[Symbol.dispose]();
+	return result;
+}
+/**
+* Mesh the source once and return it alongside the placements — the
+* "one tessellation, N placements" render payload for an instanced draw.
+*/
+function instancedMesh(inst, opts) {
+	return {
+		geometry: require_meshFns.mesh(inst.source, opts),
+		instances: inst.placements
+	};
+}
+//#endregion
 //#region src/kernel/solverAdapter.ts
 /**
 * Constraint solver adapter — analytical solver for simple assembly mates.
@@ -5338,6 +5471,19 @@ function compound$1(children) {
 		freeParams: depsOf(...children)
 	};
 }
+function instance$1(source, placements, fuse = false) {
+	const copied = placements.map((m) => m.map((row) => [...row]));
+	let h = fnvMixInt32(fnvMixBool(mix(startHash("Instance"), source), fuse), copied.length);
+	for (const m of copied) for (const v of m.flat()) h = fnvMixNumber(h, v);
+	return {
+		kind: "Instance",
+		source,
+		placements: copied,
+		fuse,
+		structuralHash: h,
+		freeParams: depsOf(source)
+	};
+}
 //#endregion
 //#region src/csg/types.ts
 function outputKindOf(node) {
@@ -5362,6 +5508,7 @@ function outputKindOf(node) {
 		case "Scale":
 		case "Mirror": return outputKindOf(node.target);
 		case "Compound": return "Compound";
+		case "Instance": return node.fuse ? "Solid" : "Compound";
 	}
 }
 //#endregion
@@ -5595,6 +5742,13 @@ function evalEmpty() {
 	return require_errors.err(require_errors.computationError(require_errors.BrepErrorCode.NULL_SHAPE_INPUT, "Empty: cannot materialize an Empty node directly — only valid as boolean/transform operand"));
 }
 //#endregion
+//#region src/csg/evaluators/instance.ts
+function evalInstance(node, ctx) {
+	const r = ctx.evalNode(node.source);
+	if (!r.ok) return r;
+	return materialize(instance(r.value, node.placements), { fuse: node.fuse });
+}
+//#endregion
 //#region src/csg/evaluate.ts
 function dispatch(node, ctx) {
 	switch (node.kind) {
@@ -5618,6 +5772,7 @@ function dispatch(node, ctx) {
 		case "Scale": return evalScale(node, ctx);
 		case "Mirror": return evalMirror(node, ctx);
 		case "Compound": return evalCompound(node, ctx);
+		case "Instance": return evalInstance(node, ctx);
 	}
 }
 function hashExprValue(h, v) {
@@ -5952,6 +6107,12 @@ function nodeToJson(n) {
 		kind: "Compound",
 		children: n.children.map(nodeToJson)
 	};
+	if (n.kind === "Instance") return {
+		kind: "Instance",
+		source: nodeToJson(n.source),
+		placements: n.placements,
+		fuse: n.fuse
+	};
 	return primitiveToJson(n) ?? booleanToJson(n) ?? transformToJson(n);
 }
 function bad(msg) {
@@ -6092,6 +6253,7 @@ function readNode(j) {
 		case "Scale":
 		case "Mirror": return readTransform(kind, j);
 		case "Compound": return readCompound(j);
+		case "Instance": return readInstance(j);
 		default: return bad(`unknown node kind: ${String(kind)}`);
 	}
 }
@@ -6250,6 +6412,16 @@ function readCompound(j) {
 	const children = readNodeArray(j["children"], "Compound.children");
 	return children.ok ? require_errors.ok(compound$1(children.value)) : children;
 }
+function isMatrix4x4(v) {
+	return Array.isArray(v) && v.length === 4 && v.every((row) => Array.isArray(row) && row.length === 4 && row.every(isNumber$1));
+}
+function readInstance(j) {
+	const source = readNode(j["source"]);
+	if (!source.ok) return source;
+	const placements = j["placements"];
+	if (!Array.isArray(placements) || !placements.every(isMatrix4x4)) return bad("Instance.placements must be an array of 4x4 number matrices");
+	return require_errors.ok(instance$1(source.value, placements, j["fuse"] === true));
+}
 //#endregion
 //#region src/csg/optimize.ts
 function optimize(node) {
@@ -6346,6 +6518,7 @@ function optimizeNode(n) {
 			at: n.at ? foldExpr(n.at) : void 0
 		});
 		case "Compound": return compound$1(n.children.map(optimizeNode).filter((c) => c.kind !== "Empty"));
+		case "Instance": return instance$1(optimizeNode(n.source), n.placements, n.fuse);
 	}
 }
 function optimizeFuse(a, b, tol) {
@@ -6435,6 +6608,7 @@ function rebuildChildren(n, pred, repl) {
 			at: n.at
 		});
 		case "Compound": return compound$1(n.children.map((c) => walk(c, pred, repl)));
+		case "Instance": return instance$1(walk(n.source, pred, repl), n.placements, n.fuse);
 	}
 }
 function forEachNode(root, fn) {
@@ -6463,6 +6637,7 @@ function childrenOf(n) {
 		case "Scale":
 		case "Mirror": return [n.target];
 		case "Compound": return n.children;
+		case "Instance": return [n.source];
 	}
 }
 function nodeCount(root) {
@@ -6499,6 +6674,7 @@ var csg_exports = /* @__PURE__ */ require_textBlueprints.__exportAll({
 	fromJSON: () => fromJSON,
 	fuse: () => fuse$1,
 	fuseAll: () => fuseAll$1,
+	instance: () => instance$1,
 	intersect: () => intersect$1,
 	line: () => line$1,
 	mirror: () => mirror$1,
@@ -6788,6 +6964,7 @@ exports.getTagMetadata = require_shapeFns.getTagMetadata;
 exports.getVertices = require_topologyQueryFns.getVertices;
 exports.getVoxel = getVoxel;
 exports.getWires = require_topologyQueryFns.getWires;
+exports.gridPattern = require_threadFns.gridPattern;
 exports.guidedSweep = require_loftFns.guidedSweep;
 exports.heal = heal;
 exports.healFace = require_healingFns.healFace;
@@ -6810,6 +6987,10 @@ exports.initFromManifold = require_shapeTypes.initFromManifold;
 exports.initFromOC = require_shapeTypes.initFromOC;
 exports.initVoxel = initVoxel;
 exports.innerWires = require_faceFns.innerWires;
+exports.instance = instance;
+exports.instanceCount = instanceCount;
+exports.instanceGrid = instanceGrid;
+exports.instancedMesh = instancedMesh;
 exports.interpolateCurve = require_curveFns.interpolateCurve;
 exports.intersect = intersect;
 exports.intersect2D = require_boolean2D.intersect2D;
@@ -6840,6 +7021,7 @@ exports.isFace = require_shapeTypes.isFace;
 exports.isFilletRadius = isFilletRadius;
 exports.isInitRequest = require_workerHandler.isInitRequest;
 exports.isInside2D = require_blueprintFns.isInside2D;
+exports.isInstanced = isInstanced;
 exports.isLive = require_shapeTypes.isLive;
 exports.isManifoldShell = require_shapeTypes.isManifoldShell;
 exports.isNumber = isNumber;
@@ -6893,6 +7075,7 @@ exports.map = require_errors.map;
 exports.mapBoth = require_errors.mapBoth;
 exports.mapErr = require_errors.mapErr;
 exports.match = require_errors.match;
+exports.materialize = materialize;
 exports.measureArea = require_measureFns.measureArea;
 exports.measureCurvatureAt = require_measureFns.measureCurvatureAt;
 exports.measureCurvatureAtMid = require_measureFns.measureCurvatureAtMid;

package/dist/brepjs.js

@@ -13,9 +13,9 @@ import { a as curveIsPeriodic, c as curvePointAt, d as flipOrientation, f as get
 import { a as meshEdges$1, c as createMeshCache, i as mesh$1, n as exportSTEP, o as meshMultiLOD, r as exportSTL, s as clearMeshCache, t as exportIGES } from "./meshFns-CAAarhVm.js";
 import { n as getAtOrThrow, r as lastOrThrow, t as firstOrThrow } from "./arrayAccess-DrUGPADn.js";
 import { _ as makeThreePointArc, d as makeCircle, h as makeLine, l as makeBSplineInterpolation, n as fill, r as makeFace, s as assembleWire } from "./surfaceBuilders-Bww4jhBo.js";
-import { _ as section$1, b as split$1, d as booleanPipeline, f as cut$2, g as intersect$2, h as fuseAll$2, m as fuse$2, p as cutAll$2, r as makeCylinder, v as sectionToFace$1, y as slice$1 } from "./solidBuilders-Biwv2cW3.js";
+import { _ as section$1, b as split$1, d as booleanPipeline, f as cut$2, g as intersect$2, h as fuseAll$2, m as fuse$2, p as cutAll$2, r as makeCylinder, t as makeCompound, v as sectionToFace$1, y as slice$1 } from "./solidBuilders-Biwv2cW3.js";
 import { A as edgesOfFace, C as shellWithEvolution, D as getNurbsCurveData, E as fuseAllBisect, F as chamferDistAngle, I as toBufferGeometryData, L as toGroupedBufferGeometryData, M as sharedEdges, N as verticesOfEdge, O as getNurbsSurfaceData, P as wiresOfFace, R as toLODGeometryData, S as intersectWithEvolution, T as cutAllBisect, _ as positionOnCurve, a as healFace, b as filletWithEvolution, c as isValid$1, d as draft$1, f as fillet$1, g as variableFillet, h as thicken$1, i as heal$1, j as facesOfEdge, k as adjacentFaces, l as solidFromShell, m as shell$1, n as fixSelfIntersection, o as healSolid, p as offset$1, r as fixShape, s as healWire, t as autoHeal, u as chamfer$1, v as chamferWithEvolution, w as checkBoolean, x as fuseWithEvolution, y as cutWithEvolution, z as toLineGeometryData } from "./healingFns-Bb3eEBNm.js";
-import { A as setJointValue, B as findNode, C as cylindricalJoint, D as planarJoint, E as mechanismDOF, F as quatRotate, H as updateNode, I as addChild, J as createAssembly, K as linearPattern, L as collectShapes, M as sphericalJoint, N as quatFromAxisAngle, O as prismaticJoint, P as quatFromTo, R as countNodes, S as addJoint, T as jointTransform, U as walkAssembly, V as removeChild, W as circularPattern, _ as exportURDF, a as deserializeHistory, b as inverseKinematics, c as modifyStep, d as replayFrom, f as replayHistory, g as undoLast, h as stepsFrom, i as createRegistry, j as setJointValues, k as revoluteJoint, l as registerOperation, m as stepCount, n as addStep, o as findStep, p as serializeHistory, q as exportAssemblySTEP, r as createHistory, s as getShape, t as thread, u as registerShape, v as importURDF, w as forwardKinematics, x as jointTrajectory, y as jointsFromDH, z as createAssemblyNode } from "./threadFns-8rKpQXiR.js";
+import { A as setJointValue, B as findNode, C as cylindricalJoint, D as planarJoint, E as mechanismDOF, F as quatRotate, G as gridPattern, H as updateNode, I as addChild, J as createAssembly, K as linearPattern, L as collectShapes, M as sphericalJoint, N as quatFromAxisAngle, O as prismaticJoint, P as quatFromTo, R as countNodes, S as addJoint, T as jointTransform, U as walkAssembly, V as removeChild, W as circularPattern, _ as exportURDF, a as deserializeHistory, b as inverseKinematics, c as modifyStep, d as replayFrom, f as replayHistory, g as undoLast, h as stepsFrom, i as createRegistry, j as setJointValues, k as revoluteJoint, l as registerOperation, m as stepCount, n as addStep, o as findStep, p as serializeHistory, q as exportAssemblySTEP, r as createHistory, s as getShape, t as thread, u as registerShape, v as importURDF, w as forwardKinematics, x as jointTrajectory, y as jointsFromDH, z as createAssemblyNode } from "./threadFns-8rKpQXiR.js";
 import { n as BaseSketcher2d, r as organiseBlueprints, t as BlueprintSketcher } from "./blueprintSketcher-CEQ8s7TD.js";
 import { a as createTypedFinder, i as wireFinder, n as edgeFinder, r as faceFinder, t as getSingleFace } from "./helpers-DT44wBAD.js";
 import { A as sketchEllipse, D as makeBaseBox, E as deserializeDrawing, F as sketchRectangle, I as sketchRoundedRectangle, L as FaceSketcher, M as sketchHelix, N as sketchParametricFunction, O as polysideInnerRadius, P as sketchPolysides, R as Sketcher, S as drawText, _ as drawPolysides, a as drawingIntersect, b as drawSingleCircle, c as rotateDrawing, d as drawFaceOutline, f as drawProjection, g as drawPointsInterpolation, h as drawParametricFunction, i as drawingFuse, j as sketchFaceOffset, k as sketchCircle, l as scaleDrawing, m as drawEllipse, n as drawingCut, o as drawingToSketchOnPlane, p as drawCircle, r as drawingFillet, s as mirrorDrawing, t as drawingChamfer, u as translateDrawing, v as drawRectangle, w as draw, x as drawSingleEllipse, y as drawRoundedRectangle } from "./drawFns-CsXPFyDe.js";
@@ -2143,6 +2143,139 @@ function roof(w, options) {
 	}
 }
 //#endregion
+//#region src/operations/instanceFns.ts
+/**
+* Transform-only instancing — hold ONE source shape + N placements without
+* copying the kernel shape. Real geometry (a Compound, or a fused solid) or a
+* render payload (one mesh + N matrices) is produced only on demand.
+*
+* A 10x10 grid is 1 solid + 100 transforms, not 100 booleans. Materialize-on-
+* export keeps the kernel work deferred; `instancedMesh` meshes the source once
+* for an instanced (e.g. three.js InstancedMesh) preview.
+*/
+function translation(v) {
+	return [
+		[
+			1,
+			0,
+			0,
+			v[0]
+		],
+		[
+			0,
+			1,
+			0,
+			v[1]
+		],
+		[
+			0,
+			0,
+			1,
+			v[2]
+		],
+		[
+			0,
+			0,
+			0,
+			1
+		]
+	];
+}
+function isVec3Array(p) {
+	const first = p[0];
+	return first !== void 0 && typeof first[0] === "number";
+}
+function make(source, placements, grid) {
+	return {
+		__instanced: true,
+		source,
+		placements,
+		grid,
+		[Symbol.dispose]() {
+			source[Symbol.dispose]();
+		}
+	};
+}
+/** Type guard for an InstancedShape. */
+function isInstanced(x) {
+	return typeof x === "object" && x !== null && x.__instanced === true;
+}
+/**
+* Instance a shape across explicit placements. `Vec3[]` is translate-only sugar
+* for `Matrix4x4[]`. The source is owned by the returned container.
+*/
+function instance(source, placements) {
+	return make(source, isVec3Array(placements) ? placements.map(translation) : placements.map((m) => m.map((row) => [...row])));
+}
+/** Instance a shape across a cols x rows grid in the XY plane. */
+function instanceGrid(source, opts) {
+	const { cols, rows, pitchX, pitchY } = opts;
+	if (!Number.isInteger(cols) || !Number.isInteger(rows) || cols < 1 || rows < 1) throw new RangeError(`instanceGrid: cols and rows must be positive integers, got ${cols}x${rows}`);
+	const placements = [];
+	for (let i = 0; i < cols; i++) for (let j = 0; j < rows; j++) placements.push(translation([
+		i * pitchX,
+		j * pitchY,
+		0
+	]));
+	return make(source, placements, {
+		cols,
+		rows,
+		pitchX,
+		pitchY
+	});
+}
+/** Number of placements. */
+function instanceCount(inst) {
+	return inst.placements.length;
+}
+/**
+* Produce real geometry: a Compound of N placed copies (default), or a single
+* fused solid (`fuse: true`, 3D only). This is where the N kernel transforms
+* happen. A grid-built instance fuses via the faster kernel `gridPattern`.
+*/
+function materialize(inst, opts = {}) {
+	const { source, placements, grid } = inst;
+	if (placements.length === 0) return err(validationError("INSTANCE_EMPTY", "materialize: instance has no placements"));
+	if (opts.fuse) {
+		if (!isShape3D(source)) return err(validationError("MATERIALIZE_NOT_3D", "materialize({fuse:true}) requires a 3D source shape"));
+		if (grid) return gridPattern(source, [
+			1,
+			0,
+			0
+		], [
+			0,
+			1,
+			0
+		], grid.cols, grid.rows, grid.pitchX, grid.pitchY);
+		return combine(source, placements, true);
+	}
+	return combine(source, placements, false);
+}
+function combine(source, placements, fuse) {
+	const copies = [];
+	for (const m of placements) {
+		const placed = applyMatrix$1(source, m);
+		if (!placed.ok) {
+			for (const c of copies) c[Symbol.dispose]();
+			return placed;
+		}
+		copies.push(placed.value);
+	}
+	const result = fuse ? fuseAll$2(copies, { unsafe: true }) : ok(makeCompound(copies));
+	for (const c of copies) if (!result.ok || c !== result.value) c[Symbol.dispose]();
+	return result;
+}
+/**
+* Mesh the source once and return it alongside the placements — the
+* "one tessellation, N placements" render payload for an instanced draw.
+*/
+function instancedMesh(inst, opts) {
+	return {
+		geometry: mesh$1(inst.source, opts),
+		instances: inst.placements
+	};
+}
+//#endregion
 //#region src/kernel/solverAdapter.ts
 /**
 * Constraint solver adapter — analytical solver for simple assembly mates.
@@ -5341,6 +5474,19 @@ function compound$1(children) {
 		freeParams: depsOf(...children)
 	};
 }
+function instance$1(source, placements, fuse = false) {
+	const copied = placements.map((m) => m.map((row) => [...row]));
+	let h = fnvMixInt32(fnvMixBool(mix(startHash("Instance"), source), fuse), copied.length);
+	for (const m of copied) for (const v of m.flat()) h = fnvMixNumber(h, v);
+	return {
+		kind: "Instance",
+		source,
+		placements: copied,
+		fuse,
+		structuralHash: h,
+		freeParams: depsOf(source)
+	};
+}
 //#endregion
 //#region src/csg/types.ts
 function outputKindOf(node) {
@@ -5365,6 +5511,7 @@ function outputKindOf(node) {
 		case "Scale":
 		case "Mirror": return outputKindOf(node.target);
 		case "Compound": return "Compound";
+		case "Instance": return node.fuse ? "Solid" : "Compound";
 	}
 }
 //#endregion
@@ -5598,6 +5745,13 @@ function evalEmpty() {
 	return err(computationError(BrepErrorCode.NULL_SHAPE_INPUT, "Empty: cannot materialize an Empty node directly — only valid as boolean/transform operand"));
 }
 //#endregion
+//#region src/csg/evaluators/instance.ts
+function evalInstance(node, ctx) {
+	const r = ctx.evalNode(node.source);
+	if (!r.ok) return r;
+	return materialize(instance(r.value, node.placements), { fuse: node.fuse });
+}
+//#endregion
 //#region src/csg/evaluate.ts
 function dispatch(node, ctx) {
 	switch (node.kind) {
@@ -5621,6 +5775,7 @@ function dispatch(node, ctx) {
 		case "Scale": return evalScale(node, ctx);
 		case "Mirror": return evalMirror(node, ctx);
 		case "Compound": return evalCompound(node, ctx);
+		case "Instance": return evalInstance(node, ctx);
 	}
 }
 function hashExprValue(h, v) {
@@ -5955,6 +6110,12 @@ function nodeToJson(n) {
 		kind: "Compound",
 		children: n.children.map(nodeToJson)
 	};
+	if (n.kind === "Instance") return {
+		kind: "Instance",
+		source: nodeToJson(n.source),
+		placements: n.placements,
+		fuse: n.fuse
+	};
 	return primitiveToJson(n) ?? booleanToJson(n) ?? transformToJson(n);
 }
 function bad(msg) {
@@ -6095,6 +6256,7 @@ function readNode(j) {
 		case "Scale":
 		case "Mirror": return readTransform(kind, j);
 		case "Compound": return readCompound(j);
+		case "Instance": return readInstance(j);
 		default: return bad(`unknown node kind: ${String(kind)}`);
 	}
 }
@@ -6253,6 +6415,16 @@ function readCompound(j) {
 	const children = readNodeArray(j["children"], "Compound.children");
 	return children.ok ? ok(compound$1(children.value)) : children;
 }
+function isMatrix4x4(v) {
+	return Array.isArray(v) && v.length === 4 && v.every((row) => Array.isArray(row) && row.length === 4 && row.every(isNumber$1));
+}
+function readInstance(j) {
+	const source = readNode(j["source"]);
+	if (!source.ok) return source;
+	const placements = j["placements"];
+	if (!Array.isArray(placements) || !placements.every(isMatrix4x4)) return bad("Instance.placements must be an array of 4x4 number matrices");
+	return ok(instance$1(source.value, placements, j["fuse"] === true));
+}
 //#endregion
 //#region src/csg/optimize.ts
 function optimize(node) {
@@ -6349,6 +6521,7 @@ function optimizeNode(n) {
 			at: n.at ? foldExpr(n.at) : void 0
 		});
 		case "Compound": return compound$1(n.children.map(optimizeNode).filter((c) => c.kind !== "Empty"));
+		case "Instance": return instance$1(optimizeNode(n.source), n.placements, n.fuse);
 	}
 }
 function optimizeFuse(a, b, tol) {
@@ -6438,6 +6611,7 @@ function rebuildChildren(n, pred, repl) {
 			at: n.at
 		});
 		case "Compound": return compound$1(n.children.map((c) => walk(c, pred, repl)));
+		case "Instance": return instance$1(walk(n.source, pred, repl), n.placements, n.fuse);
 	}
 }
 function forEachNode(root, fn) {
@@ -6466,6 +6640,7 @@ function childrenOf(n) {
 		case "Scale":
 		case "Mirror": return [n.target];
 		case "Compound": return n.children;
+		case "Instance": return [n.source];
 	}
 }
 function nodeCount(root) {
@@ -6502,6 +6677,7 @@ var csg_exports = /* @__PURE__ */ __exportAll({
 	fromJSON: () => fromJSON,
 	fuse: () => fuse$1,
 	fuseAll: () => fuseAll$1,
+	instance: () => instance$1,
 	intersect: () => intersect$1,
 	line: () => line$1,
 	mirror: () => mirror$1,
@@ -6526,4 +6702,4 @@ var csg_exports = /* @__PURE__ */ __exportAll({
 	withEvaluator: () => withEvaluator
 });
 //#endregion
-export { BaseSketcher2d, BlueprintSketcher, BrepBugError, BrepErrorCode, BrepWrapperError, BrepkitAdapter, CompoundSketch, DEFAULT_CAPABILITIES, DEG2RAD, DisposalScope, EXACT_BREP_CAPABILITIES, FaceSketcher, HASH_CODE_MAX, OK, OcctWasmAdapter, RAD2DEG, Sketch, Sketcher, Sketches, addChild, addHoles, addJoint, addMate, addStep, adjacentFaces, all, andThen, applyGlue, applyMatrix, approximateCurve, as2D, as3D, asTopo, assignRoles, autoHeal, bezier, blueprintToDXF, booleanPipeline, booleans_exports as booleans, boss, box, bsplineApprox, bug, cameraFromPlane, cameraLookAt, captureHint, cast, castShape, castShape3D, chamfer, chamferDistAngle as chamferDistAngleShape, chamferWithEvolution, checkAllInterferences, checkBoolean, checkInterference, circle, circularPattern, classifyPointOnFace, clearMeshCache, clone, closedWire, collect, collectShapes, colorFaces, colorShape, complexExtrude, composeTransforms, compound, compoundSketchExtrude, compoundSketchFace, compoundSketchLoft, compoundSketchRevolve, computationError, computeStraightSkeleton, cone, construction_exports as construction, convexHull, cornerFinder, countNodes, createAssembly, createAssemblyNode, createBlueprint, createCamera, createCompound, createCompoundBlueprint, createDistanceQuery, createEdge, createFace, createHandle, createHistory, createKernelHandle, createMeshCache, createNamedPlane, createOperationRegistry, createPlane, createRef, createRegistry, createShell, createSolid, createTaskQueue, createVertex, createWire, createWorkerClient, createWorkerHandler, csg_exports as csg, currentQuality, curve2dBoundingBox, curve2dDistanceFrom, curve2dFirstPoint, curve2dIsOnCurve, curve2dLastPoint, curve2dParameter, curve2dSplitAt, curve2dTangentAt, curveAxis, curveEndPoint, curveIsClosed, curveIsPeriodic, curveLength, curvePeriod, curvePointAt, curveStartPoint, curveTangentAt, cut, cut2D, cutAll, cutAllBisect, cutBlueprints, cutWithEvolution, cylinder, cylindricalJoint, defaultScorer, dequeueTask, describe, deserializeDrawing, deserializeHistory, fromBREP as deserializeShape, downcast, draft, draw, drawCircle, drawEllipse, drawFaceOutline, drawParametricFunction, drawPointsInterpolation, drawPolysides, drawProjection, drawRectangle, drawRoundedRectangle, drawSingleCircle, drawSingleEllipse, drawText, drawingChamfer, drawingCut, drawingFillet, drawingFuse, drawingIntersect, drawingToSketchOnPlane, drill, edgeFinder, edgesOfFace, ellipse, ellipseArc, ellipsoid, enqueueTask, err, exportAssemblySTEP, exportDXF, exportGlb, exportGltf, exportIGES, exportOBJ, exportSTEP, exportSTEPConfigured, exportSTL, exportThreeMF, exportURDF, extrude, extrudeAll, face, faceAxis, faceCenter, faceFinder, faceGeomType, faceOrientation, facesOfEdge, fieldBoolean, fieldContour, fieldOffset, fieldReinit, fieldShell, fill, filledFace, fillet, filletWithEvolution, findFacesByTag, findNode, findStep, fixSelfIntersection, fixShape, flatMap, flatten, flipFaceOrientation, flipOrientation, fontMetrics, forwardKinematics, fromBREP$1 as fromBREP, fromKernelDir, fromKernelPnt, fromKernelVec, fromNullable, fuse, fuse2D, fuseAll, fuseAllBisect, fuseBlueprints, fuseWithEvolution, gearGeometry, getActiveVoxelId, getBounds, getBounds2D, getCompSolids, getCurveType, getDisposalStats, getEdges, getFaceColor, getFaceOrigins, getFaceTags, getFaces, getFont, getHashCode, getShape as getHistoryShape, getKernel, getKernelCapabilities, getKernelTier, getNurbsCurveData, getNurbsSurfaceData, getOrientation, getOrientation2D, getPerformanceStats, getShapeColor, getShapeKind, getShells, getSingleFace, getSolids, getSurfaceType, getTagMetadata, getVertices, getVoxel, getWires, guidedSweep, heal, healFace, healSolid, healWire, helix, hull, importDXF, importGLB, importIGES, importOBJ, importSTEP, importSTL, importSVG, importSVGPathD, importThreeMF, importURDF, init, initFromManifold, initFromOC, initVoxel, innerWires, interpolateCurve, intersect, intersect2D, intersectBlueprints, intersectWithEvolution, invalidateShapeCache, inverseKinematics, ioNs_exports as io, ioError, is2D, is3D, isChamferRadius, isClosedWire, isCompSolid, isCompound, isDisposeRequest, isEdge, isEmpty, isEqualShape, isErr, isErrorResponse, isFace, isFilletRadius, isInitRequest, isInside2D, isLive, isManifoldShell, isNumber, isOk, isOperationRequest, isOrientedFace, isPlanarFace, isPlanarWire, isProjectionPlane, isEmpty$1 as isQueueEmpty, isSameShape, isShape1D, isShape3D, isShell, isSolid, isSuccessResponse, isValid, isValidSolid, isVertex, isWire, iterCompSolids, iterEdges, iterFaces, iterShells, iterSolids, iterTopo, iterVertices, iterWires, jointTrajectory, jointTransform, jointsFromDH, kernelCall, kernelCallRaw, kernelCallScoped, kernelError, latticeInfill, latticeInfillShape, line, linearPattern, loadFont, loft, loftAll, makeBaseBox, makeExternalGear, makeInternalGear, makePlane, makePlanetaryGear, makeProjectedEdges, manifoldShell, map, mapBoth, mapErr, match, measureArea, measureCurvatureAt, measureCurvatureAtMid, measureDistance, measureDistanceProps, measureLength, measureLinearProps, measureSurfaceProps, measureVolume, measureVolumeProps, measurement_exports as measurement, mechanismDOF, mesh, meshEdges, meshMultiLOD, minkowski, mirror, mirror2D, mirrorDrawing, mirrorJoin, modifiers_exports as modifiers, modifyStep, moduleInitError, multiSectionSweep, normalAt, offset, offsetFace, offsetMesh, offsetShape, offsetWire2D, ok, or, orElse, organiseBlueprints, orientedFace, outerWire, patterns_exports as patterns, pendingCount, pipeline, pivotPlane, planarFace, planarJoint, planarWire, planetPlacements, pocket, pointOnSurface, pointsInside, polygon, polyhedron, polysideInnerRadius, polysidesBlueprint, positionOnCurve, prewarm, primitives_exports as primitives, prismaticJoint, projectEdges, projectPointOnFace, query_exports as query, queryError, rectangularPattern, registerHandler, registerKernel, registerKernelTier, registerOperation, registerShape, registerVoxel, rejectAll, removeChild, removeHolesFromFace, repairMesh, replayFrom, replayHistory, resetDisposalStats, resetPerformanceStats, resize, resolve, resolve3D, resolveDirection, resolvePlane, resolveRef, reverseCurve, revoluteJoint, revolve, roof, rotate, rotate2D, rotateDrawing, roundedRectangleBlueprint, scale, scale2D, scaleDrawing, box$1 as sdfBox, capsule as sdfCapsule, cone$1 as sdfCone, cylinder$1 as sdfCylinder, fieldAxialRamp as sdfFieldAxialRamp, fieldClamp as sdfFieldClamp, fieldConst as sdfFieldConst, fieldFromSdf as sdfFieldFromSdf, fieldRadialRamp as sdfFieldRadialRamp, lattice as sdfLattice, plane as sdfPlane, roundedBox as sdfRoundedBox, sphere as sdfSphere, strutLattice as sdfStrutLattice, sweep as sdfSweep, torus as sdfTorus, section, sectionToFace, serializeHistory, setJointValue, setJointValues, setShapeOrigin, setTagMetadata, sewShells, shape, shapeToMeshInput, shapeType, sharedEdges, shell, shellMesh, shellShape, shellWithEvolution, simplify, sketchCircle, sketchEllipse, sketchExtrude, sketchFace, sketchFaceOffset, sketchHelix, sketchLoft, sketchOnFace2D, sketchOnPlane2D, sketchParametricFunction, sketchPolysides, sketchRectangle, sketchRevolve, sketchRoundedRectangle, sketchSweep, sketchText, sketchWires, sketcherStateError, slice, solid, solidFromShell, solveAssembly, sphere$1 as sphere, sphericalJoint, split, stepCount, stepsFrom, stretch2D, subFace, supportExtrude, supportsConstraintSketch, supportsProjection, surfaceFromGrid, surfaceFromImage, sweep$1 as sweep, tagFaces, tangentArc, tap, tapErr, textBlueprints, textMetrics, thicken, thread, threePointArc, toBREP, toBufferGeometryData, toGroupedBufferGeometryData, toKernelVec, toLODGeometryData, toLineGeometryData, toSVGPathD, toVec2, toVec3, torus$1 as torus, tpmsLattice, transformCopy, transforms_exports as transforms, translate, translate2D, translateDrawing, translatePlane, tryCatch, tryCatchAsync, twistExtrude, typeCastError, undoLast, unsupportedError, unwrap, unwrapErr, unwrapOr, unwrapOrElse, updateNode, updateRoles, uvBounds, uvCoordinates, validSolid, validatePlanetary, validationError, variableFillet, vecAdd, vecAngle, vecCross, vecDistance, vecDot, vecEquals, vecIsZero, vecLength, vecLengthSq, vecNegate, vecNormalize, vecProjectToPlane, vecRepr, vecRotate, vecScale, vecSub, vertex, vertexFinder, vertexPosition, verticesOfEdge, voxelBoolean, voxelBooleanField, voxelBooleanFieldShapes, voxelBooleanShapes, voxelField, voxelFieldFromShape, walkAssembly, windingNumbers, wire, wireFinder, wireLoop, wiresOfFace, withKernel, withKernelDir, withKernelPnt, withKernelVec, withQuality, withScope, withScopeResult, withScopeResultAsync, withTier, zip as zipResults };
+export { BaseSketcher2d, BlueprintSketcher, BrepBugError, BrepErrorCode, BrepWrapperError, BrepkitAdapter, CompoundSketch, DEFAULT_CAPABILITIES, DEG2RAD, DisposalScope, EXACT_BREP_CAPABILITIES, FaceSketcher, HASH_CODE_MAX, OK, OcctWasmAdapter, RAD2DEG, Sketch, Sketcher, Sketches, addChild, addHoles, addJoint, addMate, addStep, adjacentFaces, all, andThen, applyGlue, applyMatrix, approximateCurve, as2D, as3D, asTopo, assignRoles, autoHeal, bezier, blueprintToDXF, booleanPipeline, booleans_exports as booleans, boss, box, bsplineApprox, bug, cameraFromPlane, cameraLookAt, captureHint, cast, castShape, castShape3D, chamfer, chamferDistAngle as chamferDistAngleShape, chamferWithEvolution, checkAllInterferences, checkBoolean, checkInterference, circle, circularPattern, classifyPointOnFace, clearMeshCache, clone, closedWire, collect, collectShapes, colorFaces, colorShape, complexExtrude, composeTransforms, compound, compoundSketchExtrude, compoundSketchFace, compoundSketchLoft, compoundSketchRevolve, computationError, computeStraightSkeleton, cone, construction_exports as construction, convexHull, cornerFinder, countNodes, createAssembly, createAssemblyNode, createBlueprint, createCamera, createCompound, createCompoundBlueprint, createDistanceQuery, createEdge, createFace, createHandle, createHistory, createKernelHandle, createMeshCache, createNamedPlane, createOperationRegistry, createPlane, createRef, createRegistry, createShell, createSolid, createTaskQueue, createVertex, createWire, createWorkerClient, createWorkerHandler, csg_exports as csg, currentQuality, curve2dBoundingBox, curve2dDistanceFrom, curve2dFirstPoint, curve2dIsOnCurve, curve2dLastPoint, curve2dParameter, curve2dSplitAt, curve2dTangentAt, curveAxis, curveEndPoint, curveIsClosed, curveIsPeriodic, curveLength, curvePeriod, curvePointAt, curveStartPoint, curveTangentAt, cut, cut2D, cutAll, cutAllBisect, cutBlueprints, cutWithEvolution, cylinder, cylindricalJoint, defaultScorer, dequeueTask, describe, deserializeDrawing, deserializeHistory, fromBREP as deserializeShape, downcast, draft, draw, drawCircle, drawEllipse, drawFaceOutline, drawParametricFunction, drawPointsInterpolation, drawPolysides, drawProjection, drawRectangle, drawRoundedRectangle, drawSingleCircle, drawSingleEllipse, drawText, drawingChamfer, drawingCut, drawingFillet, drawingFuse, drawingIntersect, drawingToSketchOnPlane, drill, edgeFinder, edgesOfFace, ellipse, ellipseArc, ellipsoid, enqueueTask, err, exportAssemblySTEP, exportDXF, exportGlb, exportGltf, exportIGES, exportOBJ, exportSTEP, exportSTEPConfigured, exportSTL, exportThreeMF, exportURDF, extrude, extrudeAll, face, faceAxis, faceCenter, faceFinder, faceGeomType, faceOrientation, facesOfEdge, fieldBoolean, fieldContour, fieldOffset, fieldReinit, fieldShell, fill, filledFace, fillet, filletWithEvolution, findFacesByTag, findNode, findStep, fixSelfIntersection, fixShape, flatMap, flatten, flipFaceOrientation, flipOrientation, fontMetrics, forwardKinematics, fromBREP$1 as fromBREP, fromKernelDir, fromKernelPnt, fromKernelVec, fromNullable, fuse, fuse2D, fuseAll, fuseAllBisect, fuseBlueprints, fuseWithEvolution, gearGeometry, getActiveVoxelId, getBounds, getBounds2D, getCompSolids, getCurveType, getDisposalStats, getEdges, getFaceColor, getFaceOrigins, getFaceTags, getFaces, getFont, getHashCode, getShape as getHistoryShape, getKernel, getKernelCapabilities, getKernelTier, getNurbsCurveData, getNurbsSurfaceData, getOrientation, getOrientation2D, getPerformanceStats, getShapeColor, getShapeKind, getShells, getSingleFace, getSolids, getSurfaceType, getTagMetadata, getVertices, getVoxel, getWires, gridPattern, guidedSweep, heal, healFace, healSolid, healWire, helix, hull, importDXF, importGLB, importIGES, importOBJ, importSTEP, importSTL, importSVG, importSVGPathD, importThreeMF, importURDF, init, initFromManifold, initFromOC, initVoxel, innerWires, instance, instanceCount, instanceGrid, instancedMesh, interpolateCurve, intersect, intersect2D, intersectBlueprints, intersectWithEvolution, invalidateShapeCache, inverseKinematics, ioNs_exports as io, ioError, is2D, is3D, isChamferRadius, isClosedWire, isCompSolid, isCompound, isDisposeRequest, isEdge, isEmpty, isEqualShape, isErr, isErrorResponse, isFace, isFilletRadius, isInitRequest, isInside2D, isInstanced, isLive, isManifoldShell, isNumber, isOk, isOperationRequest, isOrientedFace, isPlanarFace, isPlanarWire, isProjectionPlane, isEmpty$1 as isQueueEmpty, isSameShape, isShape1D, isShape3D, isShell, isSolid, isSuccessResponse, isValid, isValidSolid, isVertex, isWire, iterCompSolids, iterEdges, iterFaces, iterShells, iterSolids, iterTopo, iterVertices, iterWires, jointTrajectory, jointTransform, jointsFromDH, kernelCall, kernelCallRaw, kernelCallScoped, kernelError, latticeInfill, latticeInfillShape, line, linearPattern, loadFont, loft, loftAll, makeBaseBox, makeExternalGear, makeInternalGear, makePlane, makePlanetaryGear, makeProjectedEdges, manifoldShell, map, mapBoth, mapErr, match, materialize, measureArea, measureCurvatureAt, measureCurvatureAtMid, measureDistance, measureDistanceProps, measureLength, measureLinearProps, measureSurfaceProps, measureVolume, measureVolumeProps, measurement_exports as measurement, mechanismDOF, mesh, meshEdges, meshMultiLOD, minkowski, mirror, mirror2D, mirrorDrawing, mirrorJoin, modifiers_exports as modifiers, modifyStep, moduleInitError, multiSectionSweep, normalAt, offset, offsetFace, offsetMesh, offsetShape, offsetWire2D, ok, or, orElse, organiseBlueprints, orientedFace, outerWire, patterns_exports as patterns, pendingCount, pipeline, pivotPlane, planarFace, planarJoint, planarWire, planetPlacements, pocket, pointOnSurface, pointsInside, polygon, polyhedron, polysideInnerRadius, polysidesBlueprint, positionOnCurve, prewarm, primitives_exports as primitives, prismaticJoint, projectEdges, projectPointOnFace, query_exports as query, queryError, rectangularPattern, registerHandler, registerKernel, registerKernelTier, registerOperation, registerShape, registerVoxel, rejectAll, removeChild, removeHolesFromFace, repairMesh, replayFrom, replayHistory, resetDisposalStats, resetPerformanceStats, resize, resolve, resolve3D, resolveDirection, resolvePlane, resolveRef, reverseCurve, revoluteJoint, revolve, roof, rotate, rotate2D, rotateDrawing, roundedRectangleBlueprint, scale, scale2D, scaleDrawing, box$1 as sdfBox, capsule as sdfCapsule, cone$1 as sdfCone, cylinder$1 as sdfCylinder, fieldAxialRamp as sdfFieldAxialRamp, fieldClamp as sdfFieldClamp, fieldConst as sdfFieldConst, fieldFromSdf as sdfFieldFromSdf, fieldRadialRamp as sdfFieldRadialRamp, lattice as sdfLattice, plane as sdfPlane, roundedBox as sdfRoundedBox, sphere as sdfSphere, strutLattice as sdfStrutLattice, sweep as sdfSweep, torus as sdfTorus, section, sectionToFace, serializeHistory, setJointValue, setJointValues, setShapeOrigin, setTagMetadata, sewShells, shape, shapeToMeshInput, shapeType, sharedEdges, shell, shellMesh, shellShape, shellWithEvolution, simplify, sketchCircle, sketchEllipse, sketchExtrude, sketchFace, sketchFaceOffset, sketchHelix, sketchLoft, sketchOnFace2D, sketchOnPlane2D, sketchParametricFunction, sketchPolysides, sketchRectangle, sketchRevolve, sketchRoundedRectangle, sketchSweep, sketchText, sketchWires, sketcherStateError, slice, solid, solidFromShell, solveAssembly, sphere$1 as sphere, sphericalJoint, split, stepCount, stepsFrom, stretch2D, subFace, supportExtrude, supportsConstraintSketch, supportsProjection, surfaceFromGrid, surfaceFromImage, sweep$1 as sweep, tagFaces, tangentArc, tap, tapErr, textBlueprints, textMetrics, thicken, thread, threePointArc, toBREP, toBufferGeometryData, toGroupedBufferGeometryData, toKernelVec, toLODGeometryData, toLineGeometryData, toSVGPathD, toVec2, toVec3, torus$1 as torus, tpmsLattice, transformCopy, transforms_exports as transforms, translate, translate2D, translateDrawing, translatePlane, tryCatch, tryCatchAsync, twistExtrude, typeCastError, undoLast, unsupportedError, unwrap, unwrapErr, unwrapOr, unwrapOrElse, updateNode, updateRoles, uvBounds, uvCoordinates, validSolid, validatePlanetary, validationError, variableFillet, vecAdd, vecAngle, vecCross, vecDistance, vecDot, vecEquals, vecIsZero, vecLength, vecLengthSq, vecNegate, vecNormalize, vecProjectToPlane, vecRepr, vecRotate, vecScale, vecSub, vertex, vertexFinder, vertexPosition, verticesOfEdge, voxelBoolean, voxelBooleanField, voxelBooleanFieldShapes, voxelBooleanShapes, voxelField, voxelFieldFromShape, walkAssembly, windingNumbers, wire, wireFinder, wireLoop, wiresOfFace, withKernel, withKernelDir, withKernelPnt, withKernelVec, withQuality, withScope, withScopeResult, withScopeResultAsync, withTier, zip as zipResults };

package/dist/csg/builders.d.ts

@@ -1,5 +1,6 @@
 import { ScalarInput, Vec3Input } from './expressions.js';
-import { BoxNode, SphereNode, CylinderNode, ConeNode, TorusNode, PolygonNode, CircleNode, LineNode, VertexLitNode, EmptyNode, FuseNode, CutNode, IntersectNode, FuseAllNode, CutAllNode, TranslateNode, RotateNode, ScaleNode, MirrorNode, CompoundNode, IRNode, SolidNode, FaceNode, EdgeNode, VertexNode } from './types.js';
+import { Matrix4x4 } from '../core/types.js';
+import { BoxNode, SphereNode, CylinderNode, ConeNode, TorusNode, PolygonNode, CircleNode, LineNode, VertexLitNode, EmptyNode, FuseNode, CutNode, IntersectNode, FuseAllNode, CutAllNode, TranslateNode, RotateNode, ScaleNode, MirrorNode, CompoundNode, InstanceNode, IRNode, SolidNode, FaceNode, EdgeNode, VertexNode } from './types.js';
 export declare function box(x: ScalarInput, y: ScalarInput, z: ScalarInput): BoxNode;
 export declare function sphere(radius: ScalarInput): SphereNode;
 export declare function cylinder(radius: ScalarInput, height: ScalarInput): CylinderNode;
@@ -33,4 +34,5 @@ export interface MirrorOptions {
 }
 export declare function mirror(target: IRNode, options?: MirrorOptions): MirrorNode;
 export declare function compound(children: ReadonlyArray<IRNode>): CompoundNode;
+export declare function instance(source: IRNode, placements: ReadonlyArray<Matrix4x4>, fuse?: boolean): InstanceNode;
 export type { FaceNode, EdgeNode, VertexNode, SolidNode };

package/dist/csg/evaluators/instance.d.ts

@@ -0,0 +1,5 @@
+import { Result } from '../../core/result.js';
+import { AnyShape, Dimension } from '../../core/shapeTypes.js';
+import { InstanceNode } from '../types.js';
+import { EvalContext } from './context.js';
+export declare function evalInstance(node: InstanceNode, ctx: EvalContext): Result<AnyShape<Dimension>>;

package/dist/csg/index.d.ts

@@ -5,9 +5,9 @@
  * parameterize via named expression bindings; evaluate against the active
  * kernel with subtree-level cache reuse for incremental parametric edits.
  */
-export { box, sphere, cylinder, cone, torus, polygon, circle, line, vertex, emptySolid, emptyFace, emptyWire, fuse, cut, intersect, fuseAll, cutAll, translate, rotate, scale, mirror, compound, type RotateOptions, type ScaleOptions, type MirrorOptions, } from './builders.js';
+export { box, sphere, cylinder, cone, torus, polygon, circle, line, vertex, emptySolid, emptyFace, emptyWire, fuse, cut, intersect, fuseAll, cutAll, translate, rotate, scale, mirror, compound, instance, type RotateOptions, type ScaleOptions, type MirrorOptions, } from './builders.js';
 export { numLit, vec3Lit, vec2Lit, param, binOp, unaryOp, component, buildVec, add, mul, asScalarExpr, asVec3Expr, asVec2Expr, type Expr, type ExprValue, type Env, type ScalarInput, type Vec3Input, type Vec2Input, type BinaryOp, type UnaryOp, } from './expressions.js';
-export type { IRNode, NodeKind, OutputKind, PrimitiveNode, BooleanNode, TransformIRNode, SolidNode, FaceNode, EdgeNode, VertexNode, AnyNode, } from './types.js';
+export type { IRNode, NodeKind, OutputKind, PrimitiveNode, BooleanNode, TransformIRNode, InstanceNode, SolidNode, FaceNode, EdgeNode, VertexNode, AnyNode, } from './types.js';
 export { outputKindOf } from './types.js';
 export { Evaluator, withEvaluator, type EvaluatorOptions, type StepInfo, type CacheStats, } from './evaluate.js';
 export { toJSON, fromJSON, CSG_VERSION, type CsgEnvelope } from './serialize.js';

package/dist/csg/types.d.ts

@@ -1,4 +1,5 @@
 import { Expr } from './expressions.js';
+import { Matrix4x4 } from '../core/types.js';
 export type OutputKind = 'Solid' | 'Face' | 'Wire' | 'Edge' | 'Vertex' | 'Compound';
 /** Output kinds that have a corresponding empty-shape builder + serializer. */
 export type EmptyOutputKind = 'Solid' | 'Face' | 'Wire';
@@ -111,10 +112,18 @@ export interface CompoundNode extends IRNodeBase {
     readonly kind: 'Compound';
     readonly children: readonly IRNode[];
 }
+export interface InstanceNode extends IRNodeBase {
+    readonly kind: 'Instance';
+    readonly source: IRNode;
+    /** Per-instance world transforms (row-major 4x4 literals). */
+    readonly placements: readonly Matrix4x4[];
+    /** Fuse the placed copies into one solid; otherwise a Compound. */
+    readonly fuse: boolean;
+}
 export type PrimitiveNode = BoxNode | SphereNode | CylinderNode | ConeNode | TorusNode | PolygonNode | CircleNode | LineNode | VertexLitNode | EmptyNode;
 export type BooleanNode = FuseNode | CutNode | IntersectNode | FuseAllNode | CutAllNode;
 export type TransformIRNode = TranslateNode | RotateNode | ScaleNode | MirrorNode;
-export type IRNode = PrimitiveNode | BooleanNode | TransformIRNode | CompoundNode;
+export type IRNode = PrimitiveNode | BooleanNode | TransformIRNode | CompoundNode | InstanceNode;
 export type NodeKind = IRNode['kind'];
 export type AnyNode = IRNode;
 /** Nodes that produce a 3D solid. */

package/dist/index.d.ts

@@ -118,7 +118,8 @@ export { guidedSweep, type GuidedSweepOptions } from './operations/guidedSweepFn
 export { roof, type RoofOptions } from './operations/roofFns.js';
 export { computeStraightSkeleton, type SkPoint2D, type SkeletonNode, type SkeletonFace, type StraightSkeleton, } from './operations/straightSkeleton.js';
 export { exportAssemblySTEP, type ShapeOptions, type SupportedUnit, } from './operations/exporterFns.js';
-export { linearPattern, circularPattern } from './operations/patternFns.js';
+export { linearPattern, circularPattern, gridPattern } from './operations/patternFns.js';
+export { instance, instanceGrid, materialize, instancedMesh, instanceCount, isInstanced, type InstancedShape, type InstancedMesh, type InstanceGridOptions, type MaterializeOptions, } from './operations/instanceFns.js';
 export { createAssemblyNode, addChild, removeChild, updateNode, findNode, walkAssembly, countNodes, collectShapes, type AssemblyNode, type AssemblyNodeOptions, } from './operations/assemblyFns.js';
 export { addMate, solveAssembly, type MateConstraint, type MateEntity, type AssemblySolveResult, } from './operations/mateFns.js';
 export { revoluteJoint, prismaticJoint, cylindricalJoint, planarJoint, sphericalJoint, setJointValue, setJointValues, jointTransform, addJoint, forwardKinematics, mechanismDOF, type Joint, type JointDOF, type JointAxis, type JointType, type JointPose, type JointOptions, type CylindricalOptions, type PlanarOptions, type SphericalOptions, } from './operations/jointFns.js';

package/dist/operations/instanceFns.d.ts

@@ -0,0 +1,66 @@
+import { Result } from '../core/result.js';
+import { AnyShape, Dimension } from '../core/shapeTypes.js';
+import { Matrix4x4, Vec3 } from '../core/types.js';
+import { ShapeMesh, MeshOptions } from '../topology/meshFns.js';
+/** Grid provenance, set by `instanceGrid`, lets `materialize({fuse})` route
+ *  through the faster kernel `gridPattern` path instead of fusing N copies. */
+interface GridSpec {
+    readonly cols: number;
+    readonly rows: number;
+    readonly pitchX: number;
+    readonly pitchY: number;
+}
+/**
+ * One source shape replicated across N placements. Not a kernel-backed shape
+ * (no `.wrapped`) — an app-level container that owns the single source handle.
+ */
+export interface InstancedShape<D extends Dimension = '3D'> extends Disposable {
+    readonly __instanced: true;
+    /** The single shared source shape (owned — disposed with this container). */
+    readonly source: AnyShape<D>;
+    /** Per-instance world transforms (row-major 4x4). */
+    readonly placements: ReadonlyArray<Matrix4x4>;
+    /** Present when built by `instanceGrid` — enables the gridPattern fuse path. */
+    readonly grid?: GridSpec | undefined;
+    [Symbol.dispose](): void;
+}
+/** Type guard for an InstancedShape. */
+export declare function isInstanced(x: unknown): x is InstancedShape<Dimension>;
+/**
+ * Instance a shape across explicit placements. `Vec3[]` is translate-only sugar
+ * for `Matrix4x4[]`. The source is owned by the returned container.
+ */
+export declare function instance<D extends Dimension>(source: AnyShape<D>, placements: readonly Matrix4x4[] | readonly Vec3[]): InstancedShape<D>;
+export interface InstanceGridOptions {
+    readonly cols: number;
+    readonly rows: number;
+    readonly pitchX: number;
+    readonly pitchY: number;
+}
+/** Instance a shape across a cols x rows grid in the XY plane. */
+export declare function instanceGrid<D extends Dimension>(source: AnyShape<D>, opts: InstanceGridOptions): InstancedShape<D>;
+/** Number of placements. */
+export declare function instanceCount(inst: InstancedShape<Dimension>): number;
+export interface MaterializeOptions {
+    /** Fuse the placed copies into a single solid (3D only). Default: false —
+     *  returns a Compound of separate placed parts. */
+    readonly fuse?: boolean;
+}
+/**
+ * Produce real geometry: a Compound of N placed copies (default), or a single
+ * fused solid (`fuse: true`, 3D only). This is where the N kernel transforms
+ * happen. A grid-built instance fuses via the faster kernel `gridPattern`.
+ */
+export declare function materialize<D extends Dimension>(inst: InstancedShape<D>, opts?: MaterializeOptions): Result<AnyShape<Dimension>>;
+export interface InstancedMesh {
+    /** The source shape meshed ONCE. */
+    readonly geometry: ShapeMesh;
+    /** Per-instance transforms — feed to e.g. three.js InstancedMesh. */
+    readonly instances: ReadonlyArray<Matrix4x4>;
+}
+/**
+ * Mesh the source once and return it alongside the placements — the
+ * "one tessellation, N placements" render payload for an instanced draw.
+ */
+export declare function instancedMesh(inst: InstancedShape<Dimension>, opts?: MeshOptions): InstancedMesh;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brepjs",
-  "version": "18.101.0",
+  "version": "18.103.0",
   "description": "Web CAD library with pluggable geometry kernel",
   "keywords": [
     "cad",