brepjs 13.4.0 → 14.1.2

package/dist/{arrayAccess-t2dlxGSK.cjs → shapeFns-aEeSHNqX.cjs}

@@ -1,7 +1,7 @@
-const require_shapeTypes = require("./shapeTypes-8eK48l-X.cjs");
-const require_errors = require("./errors-BlC5ZWv4.cjs");
-const require_vecOps = require("./vecOps-DKGelwGL.cjs");
-const require_faceFns = require("./faceFns-BywUjlJ7.cjs");
+const require_shapeTypes = require("./shapeTypes-BqWQlrYE.cjs");
+const require_errors = require("./errors-9zQcQK1H.cjs");
+const require_faceFns = require("./faceFns-cE2WxY6I.cjs");
+const require_constants = require("./constants-unWN8k4c.cjs");
 //#region src/topology/topologyQueryFns.ts
 /**
 * Topology query functions — extract sub-shapes, compute bounds, and
@@ -145,7 +145,7 @@ function vertexPosition(vertex) {
 function setShapeOrigin(shape, origin) {
 	const cache = getOrCreateCache(shape);
 	const map = /* @__PURE__ */ new Map();
-	for (const f of getFaces(shape)) map.set(require_shapeTypes.getKernel().hashCode(f.wrapped, require_vecOps.HASH_CODE_MAX), origin);
+	for (const f of getFaces(shape)) map.set(require_shapeTypes.getKernel().hashCode(f.wrapped, require_constants.HASH_CODE_MAX), origin);
 	cache.faceOrigins = map;
 }
 /**
@@ -222,7 +222,7 @@ function propagateOriginsByHash(inputs, result) {
 	const resultMap = /* @__PURE__ */ new Map();
 	const resultFaces = getFaces(result);
 	for (const f of resultFaces) {
-		const hash = kernel.hashCode(f.wrapped, require_vecOps.HASH_CODE_MAX);
+		const hash = kernel.hashCode(f.wrapped, require_constants.HASH_CODE_MAX);
 		const origin = lookup.get(hash);
 		if (origin !== void 0) resultMap.set(hash, origin);
 	}
@@ -233,7 +233,7 @@ function propagateOriginsByHash(inputs, result) {
 			const origins = getFaceOrigins(input);
 			if (!origins) continue;
 			for (const f of getFaces(input)) {
-				const hash = kernel.hashCode(f.wrapped, require_vecOps.HASH_CODE_MAX);
+				const hash = kernel.hashCode(f.wrapped, require_constants.HASH_CODE_MAX);
 				const origin = origins.get(hash);
 				if (origin === void 0) continue;
 				try {
@@ -249,7 +249,7 @@ function propagateOriginsByHash(inputs, result) {
 			}
 		}
 		if (inputSigs.length > 0) for (const f of resultFaces) {
-			const hash = kernel.hashCode(f.wrapped, require_vecOps.HASH_CODE_MAX);
+			const hash = kernel.hashCode(f.wrapped, require_constants.HASH_CODE_MAX);
 			try {
 				const outBounds = kernel.uvBounds(f.wrapped);
 				const bestOrigin = findBestOriginMatch(kernel.surfaceNormal(f.wrapped, .5 * (outBounds.uMin + outBounds.uMax), .5 * (outBounds.vMin + outBounds.vMax)), kernel.surfaceCenterOfMass(f.wrapped), inputSigs);
@@ -299,7 +299,7 @@ function tagFaces(shape, selector, tag) {
 	const faces = Array.isArray(selector) ? selector : getFaces(shape).filter(selector);
 	const tagMap = getTagMap(shape);
 	const existing = tagMap.get(tag) ?? /* @__PURE__ */ new Set();
-	for (const face of faces) existing.add(require_shapeTypes.getKernel().hashCode(face.wrapped, require_vecOps.HASH_CODE_MAX));
+	for (const face of faces) existing.add(require_shapeTypes.getKernel().hashCode(face.wrapped, require_constants.HASH_CODE_MAX));
 	tagMap.set(tag, existing);
 	return shape;
 }
@@ -316,7 +316,7 @@ function findFacesByTag(shape, tag) {
 	if (!hashes || hashes.size === 0) return [];
 	const result = [];
 	for (const face of getFaces(shape)) {
-		const hash = require_shapeTypes.getKernel().hashCode(face.wrapped, require_vecOps.HASH_CODE_MAX);
+		const hash = require_shapeTypes.getKernel().hashCode(face.wrapped, require_constants.HASH_CODE_MAX);
 		if (hashes.has(hash)) result.push(face);
 	}
 	return result;
@@ -330,7 +330,7 @@ function getFaceTags(shape) {
 	if (!tagMap) return result;
 	const faces = getFaces(shape);
 	const faceByHash = /* @__PURE__ */ new Map();
-	for (const face of faces) faceByHash.set(require_shapeTypes.getKernel().hashCode(face.wrapped, require_vecOps.HASH_CODE_MAX), face);
+	for (const face of faces) faceByHash.set(require_shapeTypes.getKernel().hashCode(face.wrapped, require_constants.HASH_CODE_MAX), face);
 	for (const [tag, hashes] of tagMap) {
 		const taggedFaces = [];
 		for (const hash of hashes) {
@@ -442,7 +442,7 @@ function colorShape(shape, color) {
 function colorFaces(shape, faces, color) {
 	const parsed = parseColor(color);
 	const map = getFaceColorMap(shape);
-	for (const face of faces) map.set(require_shapeTypes.getKernel().hashCode(face.wrapped, require_vecOps.HASH_CODE_MAX), parsed);
+	for (const face of faces) map.set(require_shapeTypes.getKernel().hashCode(face.wrapped, require_constants.HASH_CODE_MAX), parsed);
 	return shape;
 }
 /**
@@ -457,7 +457,7 @@ function getShapeColor(shape) {
 function getFaceColor(shape, face) {
 	const map = faceColorStore.get(shape.wrapped);
 	if (!map) return void 0;
-	return map.get(require_shapeTypes.getKernel().hashCode(face.wrapped, require_vecOps.HASH_CODE_MAX));
+	return map.get(require_shapeTypes.getKernel().hashCode(face.wrapped, require_constants.HASH_CODE_MAX));
 }
 /**
 * Propagate colors from input shapes to a result shape using a
@@ -497,7 +497,7 @@ function collectInputFaceHashes(inputs) {
 	const hashes = [];
 	for (const input of inputs) {
 		const faces = kernel.iterShapes(input.wrapped, "face");
-		for (const face of faces) hashes.push(kernel.hashCode(face, require_vecOps.HASH_CODE_MAX));
+		for (const face of faces) hashes.push(kernel.hashCode(face, require_constants.HASH_CODE_MAX));
 	}
 	return hashes;
 }
@@ -536,7 +536,7 @@ function propagateMetadataByHash(inputs, result) {
 /** Translate a shape by a vector. Returns a new shape. */
 function translate(shape, v) {
 	const inputFaceHashes = collectInputFaceHashes([shape]);
-	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().translateWithHistory(shape.wrapped, v[0], v[1], v[2], inputFaceHashes, require_vecOps.HASH_CODE_MAX);
+	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().translateWithHistory(shape.wrapped, v[0], v[1], v[2], inputFaceHashes, require_constants.HASH_CODE_MAX);
 	const result = require_shapeTypes.castShape(resultShape);
 	propagateAllMetadata(evolution, [shape], result);
 	return result;
@@ -552,7 +552,7 @@ function rotate(shape, angle, position = [
 	1
 ]) {
 	const inputFaceHashes = collectInputFaceHashes([shape]);
-	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().rotateWithHistory(shape.wrapped, angle * require_vecOps.DEG2RAD, inputFaceHashes, require_vecOps.HASH_CODE_MAX, direction, position);
+	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().rotateWithHistory(shape.wrapped, angle * require_constants.DEG2RAD, inputFaceHashes, require_constants.HASH_CODE_MAX, direction, position);
 	const result = require_shapeTypes.castShape(resultShape);
 	propagateAllMetadata(evolution, [shape], result);
 	return result;
@@ -568,7 +568,7 @@ function mirror(shape, planeNormal = [
 	0
 ]) {
 	const inputFaceHashes = collectInputFaceHashes([shape]);
-	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().mirrorWithHistory(shape.wrapped, planeOrigin, planeNormal, inputFaceHashes, require_vecOps.HASH_CODE_MAX);
+	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().mirrorWithHistory(shape.wrapped, planeOrigin, planeNormal, inputFaceHashes, require_constants.HASH_CODE_MAX);
 	const result = require_shapeTypes.castShape(resultShape);
 	propagateAllMetadata(evolution, [shape], result);
 	return result;
@@ -580,7 +580,7 @@ function scale(shape, factor, center = [
 	0
 ]) {
 	const inputFaceHashes = collectInputFaceHashes([shape]);
-	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().scaleWithHistory(shape.wrapped, center, factor, inputFaceHashes, require_vecOps.HASH_CODE_MAX);
+	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().scaleWithHistory(shape.wrapped, center, factor, inputFaceHashes, require_constants.HASH_CODE_MAX);
 	const result = require_shapeTypes.castShape(resultShape);
 	propagateAllMetadata(evolution, [shape], result);
 	return result;
@@ -682,7 +682,7 @@ function applyMatrix(shape, matrix) {
 	if (Math.abs(d) < 1e-12) return require_errors.err(require_errors.validationError(require_errors.BrepErrorCode.VALIDATION_FAILED, "applyMatrix: singular matrix (determinant ≈ 0). Cannot apply a non-invertible transform."));
 	if (isOrthogonalMatrix(linear)) {
 		const inputFaceHashes = collectInputFaceHashes([shape]);
-		const { shape: resultShape, evolution } = require_shapeTypes.getKernel().generalTransformWithHistory(shape.wrapped, linear, translation, true, inputFaceHashes, require_vecOps.HASH_CODE_MAX);
+		const { shape: resultShape, evolution } = require_shapeTypes.getKernel().generalTransformWithHistory(shape.wrapped, linear, translation, true, inputFaceHashes, require_constants.HASH_CODE_MAX);
 		const result = require_shapeTypes.castShape(resultShape);
 		propagateAllMetadata(evolution, [shape], result);
 		return require_errors.ok(result);
@@ -724,7 +724,7 @@ function composeTransforms(ops) {
 */
 function transformCopy(shape, composed) {
 	const inputFaceHashes = collectInputFaceHashes([shape]);
-	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().applyComposedTransformWithHistory(shape.wrapped, composed.trsf, inputFaceHashes, require_vecOps.HASH_CODE_MAX);
+	const { shape: resultShape, evolution } = require_shapeTypes.getKernel().applyComposedTransformWithHistory(shape.wrapped, composed.trsf, inputFaceHashes, require_constants.HASH_CODE_MAX);
 	const result = require_shapeTypes.castShape(resultShape);
 	propagateAllMetadata(evolution, [shape], result);
 	return result;
@@ -741,15 +741,15 @@ function transformCopy(shape, composed) {
 */
 /** Clone a shape (deep copy via kernel topology downcast). */
 function clone(shape) {
-	return require_shapeTypes.castShape(require_errors.unwrap(require_faceFns.downcast(shape.wrapped)));
+	return require_faceFns.kernelCall(() => require_shapeTypes.getKernel().downcast(shape.wrapped), require_errors.BrepErrorCode.CLONE_FAILED, "Failed to clone shape");
 }
 /** Serialize a shape to BREP string format. */
 function toBREP(shape) {
-	return require_shapeTypes.getKernel().toBREP(shape.wrapped);
+	return require_faceFns.kernelCallRaw(() => require_shapeTypes.getKernel().toBREP(shape.wrapped), require_errors.BrepErrorCode.TO_BREP_FAILED, "Failed to serialize shape to BREP");
 }
 /** Get the topology hash code of a shape. */
 function getHashCode(shape) {
-	return require_shapeTypes.getKernel().hashCode(shape.wrapped, require_vecOps.HASH_CODE_MAX);
+	return require_shapeTypes.getKernel().hashCode(shape.wrapped, require_constants.HASH_CODE_MAX);
 }
 /** Check if a shape is null. */
 function isEmpty(shape) {
@@ -765,29 +765,7 @@ function isEqualShape(a, b) {
 }
 /** Simplify a shape by merging same-domain faces/edges. Returns a new shape. */
 function simplify(shape) {
-	return require_shapeTypes.castShape(require_shapeTypes.getKernel().simplify(shape.wrapped));
-}
-//#endregion
-//#region src/utils/arrayAccess.ts
-/**
-* Safe array access utilities.
-* Replaces `arr[i]!` patterns where TypeScript's `noUncheckedIndexedAccess` requires
-* a non-null assertion but bounds are proven by surrounding code.
-*/
-/** Access element by index, throwing if out of bounds. Use when bounds are logically guaranteed. */
-function getAtOrThrow(arr, index, msg) {
-	if (index < 0 || index >= arr.length) throw new Error(msg ?? `Index ${index} out of bounds (length ${arr.length})`);
-	return arr[index];
-}
-/** Get the first element of a non-empty array, throwing if empty. */
-function firstOrThrow(arr, msg) {
-	if (arr.length === 0) throw new Error(msg ?? "Expected non-empty array");
-	return arr[0];
-}
-/** Get the last element of a non-empty array, throwing if empty. */
-function lastOrThrow(arr, msg) {
-	if (arr.length === 0) throw new Error(msg ?? "Expected non-empty array");
-	return arr[arr.length - 1];
+	return require_faceFns.kernelCall(() => require_shapeTypes.getKernel().simplify(shape.wrapped), require_errors.BrepErrorCode.SIMPLIFY_FAILED, "Failed to simplify shape");
 }
 //#endregion
 Object.defineProperty(exports, "applyMatrix", {
@@ -838,18 +816,6 @@ Object.defineProperty(exports, "findFacesByTag", {
 		return findFacesByTag;
 	}
 });
-Object.defineProperty(exports, "firstOrThrow", {
-	enumerable: true,
-	get: function() {
-		return firstOrThrow;
-	}
-});
-Object.defineProperty(exports, "getAtOrThrow", {
-	enumerable: true,
-	get: function() {
-		return getAtOrThrow;
-	}
-});
 Object.defineProperty(exports, "getBounds", {
 	enumerable: true,
 	get: function() {
@@ -970,12 +936,6 @@ Object.defineProperty(exports, "iterWires", {
 		return iterWires;
 	}
 });
-Object.defineProperty(exports, "lastOrThrow", {
-	enumerable: true,
-	get: function() {
-		return lastOrThrow;
-	}
-});
 Object.defineProperty(exports, "mirror", {
 	enumerable: true,
 	get: function() {

package/dist/shapeRef.cjs

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_shapeRefFns = require("./shapeRefFns-CVdS6jWS.cjs");
+exports.assignRoles = require_shapeRefFns.assignRoles;
+exports.captureHint = require_shapeRefFns.captureHint;
+exports.createRef = require_shapeRefFns.createRef;
+exports.defaultScorer = require_shapeRefFns.defaultScorer;
+exports.resolveRef = require_shapeRefFns.resolveRef;
+exports.updateRoles = require_shapeRefFns.updateRoles;

package/dist/shapeRef.d.ts

@@ -0,0 +1,5 @@
+/**
+ * brepjs/shapeRef — Stable face references for parametric replay.
+ */
+export { type GeometricHint, type ShapeRef, type RoleTable, type ResolvedRef, type BrokenRef, type FaceScorer, defaultScorer, captureHint, assignRoles, createRef, updateRoles, resolveRef, } from './topology/shapeRef/index.js';
+//# sourceMappingURL=shapeRef.d.ts.map

package/dist/shapeRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeRef.d.ts","sourceRoot":"","sources":["../src/shapeRef.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,aAAa,EACb,WAAW,EACX,WAAW,EACX,SAAS,EACT,WAAW,EACX,UAAU,GACX,MAAM,8BAA8B,CAAC"}

package/dist/shapeRef.js

@@ -0,0 +1,2 @@
+import { a as updateRoles, i as resolveRef, n as captureHint, o as defaultScorer, r as createRef, t as assignRoles } from "./shapeRefFns-B1TODUMl.js";
+export { assignRoles, captureHint, createRef, defaultScorer, resolveRef, updateRoles };

package/dist/shapeRefFns-B1TODUMl.js

@@ -0,0 +1,194 @@
+import { c as normalAt, n as faceCenter, r as faceGeomType } from "./faceFns-TSH54pPQ.js";
+import { N as getFaces, n as getHashCode } from "./shapeFns-DCi9O27X.js";
+import { n as measureArea } from "./measureFns-DHByqdmn.js";
+//#region src/topology/shapeRef/scoring.ts
+/**
+* Default face scorer combining surface type, normal alignment, centroid proximity,
+* and area similarity.
+*
+* Scoring breakdown:
+* - Surface type match: +1.0 (mismatch when both defined: -Infinity)
+* - Normal dot product: weighted contribution (rejected if < 0.707)
+* - Centroid distance: quadratic penalty (rejected if distSq > 100)
+* - Area ratio: penalized if |log(hintArea / faceArea)| > 1.0
+*/
+function defaultScorer(hint, face) {
+	let score = 0;
+	const faceType = faceGeomType(face);
+	if (hint.surfaceType !== void 0) if (faceType === hint.surfaceType) score += 1;
+	else return -Infinity;
+	if (hint.normal !== void 0) {
+		const faceNormal = normalAt(face);
+		const dot = hint.normal[0] * faceNormal[0] + hint.normal[1] * faceNormal[1] + hint.normal[2] * faceNormal[2];
+		if (dot < .707) return -Infinity;
+		score += dot;
+	}
+	if (hint.centroid !== void 0) {
+		const faceCentroid = faceCenter(face);
+		const dx = hint.centroid[0] - faceCentroid[0];
+		const dy = hint.centroid[1] - faceCentroid[1];
+		const dz = hint.centroid[2] - faceCentroid[2];
+		const distSq = dx * dx + dy * dy + dz * dz;
+		if (distSq > 100) return -Infinity;
+		score -= distSq / 100;
+	}
+	if (hint.area !== void 0 && hint.area > 0) {
+		const areaResult = measureArea(face);
+		if (areaResult.ok && areaResult.value > 0) {
+			const logRatio = Math.abs(Math.log(hint.area / areaResult.value));
+			if (logRatio > 1) score -= logRatio;
+		}
+	}
+	return score;
+}
+//#endregion
+//#region src/topology/shapeRef/shapeRefFns.ts
+/** Snapshot the geometric properties of a face for later matching. */
+function captureHint(face) {
+	const surfaceType = faceGeomType(face);
+	const normal = normalAt(face);
+	const centroid = faceCenter(face);
+	const areaResult = measureArea(face);
+	return {
+		entityType: "face",
+		surfaceType,
+		normal,
+		centroid,
+		area: areaResult.ok ? areaResult.value : void 0
+	};
+}
+/** Threshold for dominant-axis detection (abs(component) > 0.9). */
+var AXIS_THRESHOLD = .9;
+/** Determine the cardinal role name for a box face from its outward normal. */
+function boxRoleFromNormal(n) {
+	if (n[2] > AXIS_THRESHOLD) return "box:top";
+	if (n[2] < -AXIS_THRESHOLD) return "box:bottom";
+	if (n[1] > AXIS_THRESHOLD) return "box:back";
+	if (n[1] < -AXIS_THRESHOLD) return "box:front";
+	if (n[0] > AXIS_THRESHOLD) return "box:right";
+	if (n[0] < -AXIS_THRESHOLD) return "box:left";
+}
+/**
+* Auto-assign role names to the faces of a shape based on operation type.
+*
+* For 'box': uses face normals to assign cardinal names
+* ('box:top', 'box:bottom', 'box:front', 'box:back', 'box:left', 'box:right').
+* **Note:** Box role detection assumes axis-aligned faces (normal within 0.9 of
+* a cardinal axis). Rotated boxes may receive fewer than 6 named roles; remaining
+* faces fall through to sequential naming.
+*
+* For other types: sequential naming ('opType:face_0', 'opType:face_1', ...).
+*
+* @returns Map from role name to face hash code
+*/
+function assignRoles(shape, operationType) {
+	const faces = getFaces(shape);
+	const roles = /* @__PURE__ */ new Map();
+	if (operationType === "box") {
+		for (const face of faces) {
+			const role = boxRoleFromNormal(normalAt(face));
+			if (role !== void 0 && !roles.has(role)) roles.set(role, getHashCode(face));
+		}
+		return roles;
+	}
+	let index = 0;
+	for (const face of faces) {
+		roles.set(`${operationType}:face_${index}`, getHashCode(face));
+		index++;
+	}
+	return roles;
+}
+/** Create a ShapeRef from an origin ID, role name, and face. */
+function createRef(origin, role, face) {
+	return {
+		origin,
+		role,
+		hint: captureHint(face)
+	};
+}
+/**
+* Propagate a role table through a ShapeEvolution record.
+* Returns a new RoleTable with hashes updated according to the evolution.
+*
+* - Deleted faces: role removed
+* - Modified faces: hash updated to first result hash
+* - Unchanged faces: hash preserved
+*
+* **Limitation:** When a face splits (1→many in `evolution.modified`), only the
+* first successor hash is tracked. The geometric fallback in `resolveRef` handles
+* cases where this picks the "wrong" successor. A future version may return
+* multi-hash mappings for split-aware resolution.
+*/
+function updateRoles(roles, origin, evolution) {
+	const originRoles = roles.get(origin);
+	if (!originRoles) return roles;
+	const updatedOriginRoles = /* @__PURE__ */ new Map();
+	for (const [role, hash] of originRoles) {
+		if (evolution.deleted.has(hash)) continue;
+		const modifiedHashes = evolution.modified.get(hash);
+		if (modifiedHashes && modifiedHashes.length > 0) updatedOriginRoles.set(role, modifiedHashes[0]);
+		else updatedOriginRoles.set(role, hash);
+	}
+	const newRoles = /* @__PURE__ */ new Map();
+	for (const [key, value] of roles) if (key === origin) newRoles.set(key, updatedOriginRoles);
+	else newRoles.set(key, value);
+	return newRoles;
+}
+/** Ambiguity threshold: if two scores are within this range, it's ambiguous. */
+var AMBIGUITY_THRESHOLD = .1;
+/** Minimum score for geometric fallback to accept a match. */
+var MIN_SCORE = .5;
+/**
+* Resolve a ShapeRef to a face in the current shape.
+*
+* Resolution strategy:
+* 1. Exact lookup via role table hash match
+* 2. Geometric fallback using scorer against all faces
+* 3. Ambiguous if multiple faces score within threshold
+* 4. Not-found if no match above minimum score
+*/
+function resolveRef(ref, roles, currentShape, scorer) {
+	const faces = getFaces(currentShape);
+	const scoreFn = scorer ?? defaultScorer;
+	const targetHash = roles.get(ref.origin)?.get(ref.role);
+	if (targetHash !== void 0) {
+		for (const face of faces) if (getHashCode(face) === targetHash) return {
+			face,
+			confidence: "exact"
+		};
+		return {
+			ref,
+			reason: "deleted"
+		};
+	}
+	let bestScore = -Infinity;
+	let bestFace;
+	let secondBestScore = -Infinity;
+	const scored = [];
+	for (const face of faces) {
+		const score = scoreFn(ref.hint, face);
+		if (score > MIN_SCORE) scored.push([face, score]);
+		if (score > bestScore) {
+			secondBestScore = bestScore;
+			bestScore = score;
+			bestFace = face;
+		} else if (score > secondBestScore) secondBestScore = score;
+	}
+	if (bestFace !== void 0 && bestScore > MIN_SCORE) {
+		if (bestScore - secondBestScore < AMBIGUITY_THRESHOLD && scored.length > 1) return {
+			ref,
+			reason: "ambiguous",
+			candidates: scored.filter(([, s]) => s >= bestScore - AMBIGUITY_THRESHOLD).map(([f]) => f)
+		};
+		return {
+			face: bestFace,
+			confidence: "geometric-fallback"
+		};
+	}
+	return {
+		ref,
+		reason: "not-found"
+	};
+}
+//#endregion
+export { updateRoles as a, resolveRef as i, captureHint as n, defaultScorer as o, createRef as r, assignRoles as t };

package/dist/shapeRefFns-CVdS6jWS.cjs

@@ -0,0 +1,229 @@
+const require_faceFns = require("./faceFns-cE2WxY6I.cjs");
+const require_shapeFns = require("./shapeFns-aEeSHNqX.cjs");
+const require_measureFns = require("./measureFns-D_QKZ5yg.cjs");
+//#region src/topology/shapeRef/scoring.ts
+/**
+* Default face scorer combining surface type, normal alignment, centroid proximity,
+* and area similarity.
+*
+* Scoring breakdown:
+* - Surface type match: +1.0 (mismatch when both defined: -Infinity)
+* - Normal dot product: weighted contribution (rejected if < 0.707)
+* - Centroid distance: quadratic penalty (rejected if distSq > 100)
+* - Area ratio: penalized if |log(hintArea / faceArea)| > 1.0
+*/
+function defaultScorer(hint, face) {
+	let score = 0;
+	const faceType = require_faceFns.faceGeomType(face);
+	if (hint.surfaceType !== void 0) if (faceType === hint.surfaceType) score += 1;
+	else return -Infinity;
+	if (hint.normal !== void 0) {
+		const faceNormal = require_faceFns.normalAt(face);
+		const dot = hint.normal[0] * faceNormal[0] + hint.normal[1] * faceNormal[1] + hint.normal[2] * faceNormal[2];
+		if (dot < .707) return -Infinity;
+		score += dot;
+	}
+	if (hint.centroid !== void 0) {
+		const faceCentroid = require_faceFns.faceCenter(face);
+		const dx = hint.centroid[0] - faceCentroid[0];
+		const dy = hint.centroid[1] - faceCentroid[1];
+		const dz = hint.centroid[2] - faceCentroid[2];
+		const distSq = dx * dx + dy * dy + dz * dz;
+		if (distSq > 100) return -Infinity;
+		score -= distSq / 100;
+	}
+	if (hint.area !== void 0 && hint.area > 0) {
+		const areaResult = require_measureFns.measureArea(face);
+		if (areaResult.ok && areaResult.value > 0) {
+			const logRatio = Math.abs(Math.log(hint.area / areaResult.value));
+			if (logRatio > 1) score -= logRatio;
+		}
+	}
+	return score;
+}
+//#endregion
+//#region src/topology/shapeRef/shapeRefFns.ts
+/** Snapshot the geometric properties of a face for later matching. */
+function captureHint(face) {
+	const surfaceType = require_faceFns.faceGeomType(face);
+	const normal = require_faceFns.normalAt(face);
+	const centroid = require_faceFns.faceCenter(face);
+	const areaResult = require_measureFns.measureArea(face);
+	return {
+		entityType: "face",
+		surfaceType,
+		normal,
+		centroid,
+		area: areaResult.ok ? areaResult.value : void 0
+	};
+}
+/** Threshold for dominant-axis detection (abs(component) > 0.9). */
+var AXIS_THRESHOLD = .9;
+/** Determine the cardinal role name for a box face from its outward normal. */
+function boxRoleFromNormal(n) {
+	if (n[2] > AXIS_THRESHOLD) return "box:top";
+	if (n[2] < -AXIS_THRESHOLD) return "box:bottom";
+	if (n[1] > AXIS_THRESHOLD) return "box:back";
+	if (n[1] < -AXIS_THRESHOLD) return "box:front";
+	if (n[0] > AXIS_THRESHOLD) return "box:right";
+	if (n[0] < -AXIS_THRESHOLD) return "box:left";
+}
+/**
+* Auto-assign role names to the faces of a shape based on operation type.
+*
+* For 'box': uses face normals to assign cardinal names
+* ('box:top', 'box:bottom', 'box:front', 'box:back', 'box:left', 'box:right').
+* **Note:** Box role detection assumes axis-aligned faces (normal within 0.9 of
+* a cardinal axis). Rotated boxes may receive fewer than 6 named roles; remaining
+* faces fall through to sequential naming.
+*
+* For other types: sequential naming ('opType:face_0', 'opType:face_1', ...).
+*
+* @returns Map from role name to face hash code
+*/
+function assignRoles(shape, operationType) {
+	const faces = require_shapeFns.getFaces(shape);
+	const roles = /* @__PURE__ */ new Map();
+	if (operationType === "box") {
+		for (const face of faces) {
+			const role = boxRoleFromNormal(require_faceFns.normalAt(face));
+			if (role !== void 0 && !roles.has(role)) roles.set(role, require_shapeFns.getHashCode(face));
+		}
+		return roles;
+	}
+	let index = 0;
+	for (const face of faces) {
+		roles.set(`${operationType}:face_${index}`, require_shapeFns.getHashCode(face));
+		index++;
+	}
+	return roles;
+}
+/** Create a ShapeRef from an origin ID, role name, and face. */
+function createRef(origin, role, face) {
+	return {
+		origin,
+		role,
+		hint: captureHint(face)
+	};
+}
+/**
+* Propagate a role table through a ShapeEvolution record.
+* Returns a new RoleTable with hashes updated according to the evolution.
+*
+* - Deleted faces: role removed
+* - Modified faces: hash updated to first result hash
+* - Unchanged faces: hash preserved
+*
+* **Limitation:** When a face splits (1→many in `evolution.modified`), only the
+* first successor hash is tracked. The geometric fallback in `resolveRef` handles
+* cases where this picks the "wrong" successor. A future version may return
+* multi-hash mappings for split-aware resolution.
+*/
+function updateRoles(roles, origin, evolution) {
+	const originRoles = roles.get(origin);
+	if (!originRoles) return roles;
+	const updatedOriginRoles = /* @__PURE__ */ new Map();
+	for (const [role, hash] of originRoles) {
+		if (evolution.deleted.has(hash)) continue;
+		const modifiedHashes = evolution.modified.get(hash);
+		if (modifiedHashes && modifiedHashes.length > 0) updatedOriginRoles.set(role, modifiedHashes[0]);
+		else updatedOriginRoles.set(role, hash);
+	}
+	const newRoles = /* @__PURE__ */ new Map();
+	for (const [key, value] of roles) if (key === origin) newRoles.set(key, updatedOriginRoles);
+	else newRoles.set(key, value);
+	return newRoles;
+}
+/** Ambiguity threshold: if two scores are within this range, it's ambiguous. */
+var AMBIGUITY_THRESHOLD = .1;
+/** Minimum score for geometric fallback to accept a match. */
+var MIN_SCORE = .5;
+/**
+* Resolve a ShapeRef to a face in the current shape.
+*
+* Resolution strategy:
+* 1. Exact lookup via role table hash match
+* 2. Geometric fallback using scorer against all faces
+* 3. Ambiguous if multiple faces score within threshold
+* 4. Not-found if no match above minimum score
+*/
+function resolveRef(ref, roles, currentShape, scorer) {
+	const faces = require_shapeFns.getFaces(currentShape);
+	const scoreFn = scorer ?? defaultScorer;
+	const targetHash = roles.get(ref.origin)?.get(ref.role);
+	if (targetHash !== void 0) {
+		for (const face of faces) if (require_shapeFns.getHashCode(face) === targetHash) return {
+			face,
+			confidence: "exact"
+		};
+		return {
+			ref,
+			reason: "deleted"
+		};
+	}
+	let bestScore = -Infinity;
+	let bestFace;
+	let secondBestScore = -Infinity;
+	const scored = [];
+	for (const face of faces) {
+		const score = scoreFn(ref.hint, face);
+		if (score > MIN_SCORE) scored.push([face, score]);
+		if (score > bestScore) {
+			secondBestScore = bestScore;
+			bestScore = score;
+			bestFace = face;
+		} else if (score > secondBestScore) secondBestScore = score;
+	}
+	if (bestFace !== void 0 && bestScore > MIN_SCORE) {
+		if (bestScore - secondBestScore < AMBIGUITY_THRESHOLD && scored.length > 1) return {
+			ref,
+			reason: "ambiguous",
+			candidates: scored.filter(([, s]) => s >= bestScore - AMBIGUITY_THRESHOLD).map(([f]) => f)
+		};
+		return {
+			face: bestFace,
+			confidence: "geometric-fallback"
+		};
+	}
+	return {
+		ref,
+		reason: "not-found"
+	};
+}
+//#endregion
+Object.defineProperty(exports, "assignRoles", {
+	enumerable: true,
+	get: function() {
+		return assignRoles;
+	}
+});
+Object.defineProperty(exports, "captureHint", {
+	enumerable: true,
+	get: function() {
+		return captureHint;
+	}
+});
+Object.defineProperty(exports, "createRef", {
+	enumerable: true,
+	get: function() {
+		return createRef;
+	}
+});
+Object.defineProperty(exports, "defaultScorer", {
+	enumerable: true,
+	get: function() {
+		return defaultScorer;
+	}
+});
+Object.defineProperty(exports, "resolveRef", {
+	enumerable: true,
+	get: function() {
+		return resolveRef;
+	}
+});
+Object.defineProperty(exports, "updateRoles", {
+	enumerable: true,
+	get: function() {
+		return updateRoles;
+	}
+});