brepjs 18.112.0 → 18.114.0

package/dist/refResolveFns-BK5NSDFd.cjs

@@ -0,0 +1,857 @@
+const require_topologyQueryFns = require("./topologyQueryFns-CoXVHuN7.cjs");
+const require_faceFns = require("./faceFns-BV0GnTlt.cjs");
+const require_shapeFns = require("./shapeFns-ybo0INGL.cjs");
+const require_measureFns = require("./measureFns-DblG0Yaz.cjs");
+const require_adjacencyFns = require("./adjacencyFns-d8ZabkvX.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] < -.9) return "box:bottom";
+	if (n[1] > AXIS_THRESHOLD) return "box:back";
+	if (n[1] < -.9) return "box:front";
+	if (n[0] > AXIS_THRESHOLD) return "box:right";
+	if (n[0] < -.9) 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 its face hash codes (one at assignment time;
+*   a role accrues more hashes only later, when `updateRoles` tracks a split).
+*/
+function assignRoles(shape, operationType) {
+	const faces = require_topologyQueryFns.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)
+	};
+}
+/**
+* Advance a role's face hashes through one evolution: drop deleted faces,
+* replace a modified face with *all* its successors (a 1→many split keeps every
+* fragment), and keep unchanged faces. Deduped so a shared successor isn't
+* doubled.
+*/
+function nextHashes(hashes, evolution) {
+	const successors = [];
+	for (const hash of hashes) {
+		if (evolution.deleted.has(hash)) continue;
+		const modified = evolution.modified.get(hash);
+		const targets = modified && modified.length > 0 ? modified : [hash];
+		for (const h of targets) if (!successors.includes(h)) successors.push(h);
+	}
+	return successors;
+}
+/**
+* Propagate a role table through a ShapeEvolution record.
+* Returns a new RoleTable with hashes updated according to the evolution.
+*
+* - Deleted faces: hash dropped (role removed once all its hashes are gone).
+* - Modified faces: hash replaced by **all** successor hashes — so a 1→many
+*   split keeps every fragment, and `resolveRef` disambiguates among them.
+* - Unchanged faces: hash preserved.
+*
+* Note: `evolution.generated` is intentionally not consumed here — on the OCCT
+* kernels its hashes refer to an intermediate shape, not the final result, so
+* naming generated faces produces roles that never resolve (verified: 0 live
+* generated hashes across cut/fuse on occt-wasm). Stable names for generated
+* geometry (fillet rounds, boolean seams) need history-fidelity work tracked
+* separately.
+*/
+function updateRoles(roles, origin, evolution) {
+	const originRoles = roles.get(origin);
+	if (!originRoles) return roles;
+	const updatedOriginRoles = /* @__PURE__ */ new Map();
+	for (const [role, hashes] of originRoles) {
+		const successors = nextHashes(hashes, evolution);
+		if (successors.length > 0) updatedOriginRoles.set(role, successors);
+	}
+	const newRoles = /* @__PURE__ */ new Map();
+	for (const [key, value] of roles) newRoles.set(key, key === origin ? updatedOriginRoles : 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;
+/**
+* Score `candidates` against `hint`, returning the best match, a tie within
+* {@link AMBIGUITY_THRESHOLD}, or nothing above {@link MIN_SCORE}. Scoping the
+* candidates to a role's tracked successors (rather than every face) is what
+* makes split-face disambiguation reliable — the fragments compete only with
+* each other, not with unrelated geometry.
+*/
+function scoreFaces(hint, candidates, scoreFn) {
+	let bestScore = -Infinity;
+	let bestFace;
+	let secondBestScore = -Infinity;
+	const scored = [];
+	for (const face of candidates) {
+		const score = scoreFn(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 {
+			kind: "ambiguous",
+			candidates: scored.filter(([, s]) => s >= bestScore - AMBIGUITY_THRESHOLD).map(([f]) => f)
+		};
+		return {
+			kind: "match",
+			face: bestFace
+		};
+	}
+	return { kind: "none" };
+}
+/**
+* Resolve a ShapeRef to a face in the current shape.
+*
+* Resolution strategy:
+* 1. Exact: the role's tracked successor hashes. One survivor → exact match;
+*    several survivors (a face that split) → disambiguate among *only those*
+*    fragments; none survive → deleted.
+* 2. Geometric fallback over the whole shape when the role isn't tracked (or a
+*    scoped score turned up nothing): best-scoring face, else ambiguous /
+*    not-found.
+*/
+function resolveRef(ref, roles, currentShape, scorer) {
+	const faces = require_topologyQueryFns.getFaces(currentShape);
+	const scoreFn = scorer ?? defaultScorer;
+	const targetHashes = roles.get(ref.origin)?.get(ref.role);
+	if (targetHashes !== void 0 && targetHashes.length > 0) {
+		const survivors = faces.filter((f) => targetHashes.includes(require_shapeFns.getHashCode(f)));
+		if (survivors.length === 1) {
+			const [only] = survivors;
+			if (only !== void 0) return {
+				face: only,
+				confidence: "exact"
+			};
+		} else if (survivors.length === 0) return {
+			ref,
+			reason: "deleted"
+		};
+		else {
+			const outcome = scoreFaces(ref.hint, survivors, scoreFn);
+			if (outcome.kind === "match") return {
+				face: outcome.face,
+				confidence: "geometric-fallback"
+			};
+			if (outcome.kind === "ambiguous") return {
+				ref,
+				reason: "ambiguous",
+				candidates: outcome.candidates
+			};
+		}
+	}
+	const outcome = scoreFaces(ref.hint, faces, scoreFn);
+	if (outcome.kind === "match") return {
+		face: outcome.face,
+		confidence: "geometric-fallback"
+	};
+	if (outcome.kind === "ambiguous") return {
+		ref,
+		reason: "ambiguous",
+		candidates: outcome.candidates
+	};
+	return {
+		ref,
+		reason: "not-found"
+	};
+}
+//#endregion
+//#region src/topology/shapeRef/roleLookup.ts
+/** Euclidean distance between two points. */
+function distance(a, b) {
+	const dx = a[0] - b[0];
+	const dy = a[1] - b[1];
+	const dz = a[2] - b[2];
+	return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/** Mean of a set of vertices' positions (e.g. an edge's endpoints). */
+function vertexCentroid(verts) {
+	if (verts.length === 0) return void 0;
+	let x = 0;
+	let y = 0;
+	let z = 0;
+	for (const v of verts) {
+		const p = require_topologyQueryFns.vertexPosition(v);
+		x += p[0];
+		y += p[1];
+		z += p[2];
+	}
+	const n = verts.length;
+	return [
+		x / n,
+		y / n,
+		z / n
+	];
+}
+/** The role whose tracked hashes include this face (reverse lookup). */
+function roleOfFace(face, origin, roles) {
+	const originRoles = roles.get(origin);
+	if (!originRoles) return void 0;
+	const hash = require_shapeFns.getHashCode(face);
+	for (const [role, hashes] of originRoles) if (hashes.includes(hash)) return role;
+}
+/** Current faces a role resolves to — its tracked successors present in `shape`. */
+function facesForRole(shape, origin, role, roles) {
+	const hashes = roles.get(origin)?.get(role);
+	if (hashes === void 0 || hashes.length === 0) return [];
+	return require_topologyQueryFns.getFaces(shape).filter((f) => hashes.includes(require_shapeFns.getHashCode(f)));
+}
+//#endregion
+//#region src/topology/shapeRef/edgeRefFns.ts
+function captureEdgeHint(edge) {
+	const lengthResult = require_measureFns.measureLength(edge);
+	return {
+		entityType: "edge",
+		length: lengthResult.ok ? lengthResult.value : void 0,
+		midpoint: vertexCentroid(require_adjacencyFns.verticesOfEdge(edge))
+	};
+}
+function dedupeEdges(edges) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const e of edges) {
+		const h = require_shapeFns.getHashCode(e);
+		if (!seen.has(h)) {
+			seen.add(h);
+			out.push(e);
+		}
+	}
+	return out;
+}
+/** Hint scores closer than this are treated as indistinguishable (→ ambiguous). */
+var HINT_MARGIN$2 = 1e-6;
+/**
+* Pick the candidate edge closest to the hint (length + endpoint midpoint).
+* Returns undefined when it genuinely can't discriminate — the hint carries no
+* signal, or the two best candidates score within {@link HINT_MARGIN} — so the
+* caller can report `ambiguous` rather than committing to an arbitrary edge.
+*/
+function bestByHint(candidates, hint) {
+	if (hint.length === void 0 && hint.midpoint === void 0) return void 0;
+	let best;
+	let bestScore = Infinity;
+	let secondScore = Infinity;
+	for (const edge of candidates) {
+		let score = 0;
+		if (hint.length !== void 0) {
+			const len = require_measureFns.measureLength(edge);
+			if (len.ok) score += Math.abs(len.value - hint.length);
+		}
+		if (hint.midpoint !== void 0) {
+			const mid = vertexCentroid(require_adjacencyFns.verticesOfEdge(edge));
+			if (mid !== void 0) score += distance(hint.midpoint, mid);
+		}
+		if (score < bestScore) {
+			secondScore = bestScore;
+			bestScore = score;
+			best = edge;
+		} else if (score < secondScore) secondScore = score;
+	}
+	if (best === void 0 || secondScore - bestScore < HINT_MARGIN$2) return void 0;
+	return best;
+}
+/**
+* Capture a lineage-based reference to `edge`: its two adjacent faces' roles
+* plus a geometric hint. Returns undefined when the edge doesn't bound two faces
+* (a boundary/degenerate edge) or when either bounding face has no role yet.
+*/
+function createEdgeRef(origin, edge, shape, roles) {
+	const [faceA, faceB] = require_adjacencyFns.facesOfEdge(shape, edge);
+	if (faceA === void 0 || faceB === void 0) return void 0;
+	const roleA = roleOfFace(faceA, origin, roles);
+	const roleB = roleOfFace(faceB, origin, roles);
+	if (roleA === void 0 || roleB === void 0) return void 0;
+	return {
+		origin,
+		faceRoles: [roleA, roleB],
+		hint: captureEdgeHint(edge)
+	};
+}
+/**
+* Resolve an EdgeRef in `shape`: resolve its two face-roles to current faces,
+* then return the edge they share. One shared edge → exact; several (the two
+* faces meet along more than one edge) → disambiguate by hint; none, or a
+* missing bounding face → broken.
+*/
+function resolveEdgeRef(ref, roles, shape) {
+	const [roleA, roleB] = ref.faceRoles;
+	const facesA = facesForRole(shape, ref.origin, roleA, roles);
+	const facesB = facesForRole(shape, ref.origin, roleB, roles);
+	if (facesA.length === 0 || facesB.length === 0) return {
+		ref,
+		reason: "not-found"
+	};
+	const candidates = [];
+	for (const a of facesA) for (const b of facesB) candidates.push(...require_adjacencyFns.sharedEdges(a, b));
+	const unique = dedupeEdges(candidates);
+	if (unique.length === 1) {
+		const [only] = unique;
+		if (only !== void 0) return {
+			edge: only,
+			confidence: "exact"
+		};
+	}
+	if (unique.length > 1) {
+		const best = bestByHint(unique, ref.hint);
+		if (best !== void 0) return {
+			edge: best,
+			confidence: "geometric-fallback"
+		};
+		return {
+			ref,
+			reason: "ambiguous",
+			candidates: unique
+		};
+	}
+	return {
+		ref,
+		reason: "not-found"
+	};
+}
+//#endregion
+//#region src/topology/shapeRef/vertexRefFns.ts
+/** A corner needs at least this many faces to pin a unique point. */
+var MIN_VERTEX_FACES = 3;
+/** Hint distances closer than this are indistinguishable (→ ambiguous). */
+var HINT_MARGIN$1 = 1e-6;
+/** Hashes of all vertices across `faces`, recording one handle per hash. */
+function vertexHashes(faces, handles) {
+	const hashes = /* @__PURE__ */ new Set();
+	for (const f of faces) for (const v of require_adjacencyFns.verticesOfFace(f)) {
+		const h = require_shapeFns.getHashCode(v);
+		hashes.add(h);
+		if (!handles.has(h)) handles.set(h, v);
+	}
+	return hashes;
+}
+function intersect(a, b) {
+	const out = /* @__PURE__ */ new Set();
+	for (const h of a) if (b.has(h)) out.add(h);
+	return out;
+}
+/** Vertices present in (a face of) every face-set — the shared corner(s). */
+function commonVertices(faceSets) {
+	const handles = /* @__PURE__ */ new Map();
+	let common;
+	for (const faces of faceSets) {
+		const hashes = vertexHashes(faces, handles);
+		common = common === void 0 ? hashes : intersect(common, hashes);
+	}
+	if (common === void 0) return [];
+	const result = [];
+	for (const h of common) {
+		const v = handles.get(h);
+		if (v !== void 0) result.push(v);
+	}
+	return result;
+}
+/** Nearest candidate to the hint position; undefined if no signal or a tie. */
+function nearestToHint(vertices, hint) {
+	if (hint.position === void 0) return void 0;
+	let best;
+	let bestDist = Infinity;
+	let secondDist = Infinity;
+	for (const v of vertices) {
+		const d = distance(require_topologyQueryFns.vertexPosition(v), hint.position);
+		if (d < bestDist) {
+			secondDist = bestDist;
+			bestDist = d;
+			best = v;
+		} else if (d < secondDist) secondDist = d;
+	}
+	if (best === void 0 || secondDist - bestDist < HINT_MARGIN$1) return void 0;
+	return best;
+}
+/**
+* Capture a lineage-based reference to `vertex`: the roles of the ≥3 faces
+* meeting at it, plus a position hint. Returns undefined when fewer than three
+* named faces meet there (a 2-face "vertex" is ambiguous — an edge has two).
+*/
+function createVertexRef(origin, vertex, shape, roles) {
+	const faces = require_adjacencyFns.facesOfVertex(shape, vertex);
+	if (faces.length < MIN_VERTEX_FACES) return void 0;
+	const roleSet = /* @__PURE__ */ new Set();
+	for (const f of faces) {
+		const role = roleOfFace(f, origin, roles);
+		if (role !== void 0) roleSet.add(role);
+	}
+	if (roleSet.size < MIN_VERTEX_FACES) return void 0;
+	return {
+		origin,
+		faceRoles: [...roleSet].sort(),
+		hint: {
+			entityType: "vertex",
+			position: require_topologyQueryFns.vertexPosition(vertex)
+		}
+	};
+}
+/**
+* Resolve a VertexRef in `shape`: gather the current faces of each role, then
+* return the vertex common to all of them. One common vertex → exact; several →
+* disambiguate by hint position; none, or a missing role → broken.
+*/
+function resolveVertexRef(ref, roles, shape) {
+	const faceSets = [];
+	for (const role of ref.faceRoles) {
+		const faces = facesForRole(shape, ref.origin, role, roles);
+		if (faces.length === 0) return {
+			ref,
+			reason: "not-found"
+		};
+		faceSets.push(faces);
+	}
+	const common = commonVertices(faceSets);
+	if (common.length === 1) {
+		const [only] = common;
+		if (only !== void 0) return {
+			vertex: only,
+			confidence: "exact"
+		};
+	}
+	if (common.length > 1) {
+		const best = nearestToHint(common, ref.hint);
+		if (best !== void 0) return {
+			vertex: best,
+			confidence: "geometric-fallback"
+		};
+		return {
+			ref,
+			reason: "ambiguous",
+			candidates: common
+		};
+	}
+	return {
+		ref,
+		reason: "not-found"
+	};
+}
+//#endregion
+//#region src/topology/shapeRef/derivedFaceRefFns.ts
+/** A face re-derives a bridged face when its normal is nearly identical. */
+var NORMAL_MATCH = .99;
+/** A generated face's normal has a positive component along BOTH bridged normals. */
+var BLEND_THRESHOLD = .1;
+/** Tiebreak distances closer than this are indistinguishable (→ ambiguous). */
+var HINT_MARGIN = 1e-6;
+function normalDot(a, b) {
+	return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+/** Faces whose outward normal nearly matches `normal` (re-derives a bridged face). */
+function facesByNormal(shape, normal) {
+	return require_topologyQueryFns.getFaces(shape).filter((f) => normalDot(require_faceFns.normalAt(f), normal) > NORMAL_MATCH);
+}
+/**
+* Faces adjacent to BOTH face sets, excluding the sets themselves. Uses the
+* cached edge→faces adjacency (`adjacentFaces`) rather than an O(F·N) per-pair
+* `sharedEdges` scan.
+*/
+function betweenFaces(shape, aFaces, bFaces) {
+	const exclude = new Set([...aFaces, ...bFaces].map(require_shapeFns.getHashCode));
+	const adjacentToA = /* @__PURE__ */ new Set();
+	for (const a of aFaces) for (const f of require_adjacencyFns.adjacentFaces(shape, a)) adjacentToA.add(require_shapeFns.getHashCode(f));
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const b of bFaces) for (const f of require_adjacencyFns.adjacentFaces(shape, b)) {
+		const h = require_shapeFns.getHashCode(f);
+		if (exclude.has(h) || seen.has(h) || !adjacentToA.has(h)) continue;
+		seen.add(h);
+		result.push(f);
+	}
+	return result;
+}
+/** Face whose center is nearest `point`; undefined on a tie (→ ambiguous). */
+function nearestFace(faces, point) {
+	let best;
+	let bestDist = Infinity;
+	let secondDist = Infinity;
+	for (const f of faces) {
+		const d = distance(require_faceFns.faceCenter(f), point);
+		if (d < bestDist) {
+			secondDist = bestDist;
+			bestDist = d;
+			best = f;
+		} else if (d < secondDist) secondDist = d;
+	}
+	if (best === void 0 || secondDist - bestDist < HINT_MARGIN) return void 0;
+	return best;
+}
+/**
+* Capture a reference to the face an `op` (fillet/chamfer) will generate across
+* `edge`: the roles of the edge's two faces, their outward normals, and the edge
+* midpoint. Call this on the PRE-op shape. Returns undefined when the edge
+* doesn't bound two named faces.
+*/
+function createDerivedFaceRef(origin, op, edge, preShape, roles) {
+	const [faceA, faceB] = require_adjacencyFns.facesOfEdge(preShape, edge);
+	if (faceA === void 0 || faceB === void 0) return void 0;
+	const roleA = roleOfFace(faceA, origin, roles);
+	const roleB = roleOfFace(faceB, origin, roles);
+	if (roleA === void 0 || roleB === void 0) return void 0;
+	return {
+		origin,
+		op,
+		betweenRoles: [roleA, roleB],
+		hint: {
+			entityType: "derived-face",
+			normalA: require_faceFns.normalAt(faceA),
+			normalB: require_faceFns.normalAt(faceB),
+			edgeMidpoint: vertexCentroid(require_adjacencyFns.verticesOfEdge(edge))
+		}
+	};
+}
+/**
+* Resolve a DerivedFaceRef in the post-op `shape`: re-derive the two bridged
+* faces (role table, else by captured normal), then return the face adjacent to
+* both whose normal blends both. One survivor → resolved; several →
+* nearest-to-edge-midpoint; none → broken.
+*/
+function resolveDerivedFaceRef(ref, roles, shape) {
+	let aFaces = facesForRole(shape, ref.origin, ref.betweenRoles[0], roles);
+	if (aFaces.length === 0) aFaces = facesByNormal(shape, ref.hint.normalA);
+	let bFaces = facesForRole(shape, ref.origin, ref.betweenRoles[1], roles);
+	if (bFaces.length === 0) bFaces = facesByNormal(shape, ref.hint.normalB);
+	if (aFaces.length === 0 || bFaces.length === 0) return {
+		ref,
+		reason: "not-found"
+	};
+	const blended = betweenFaces(shape, aFaces, bFaces).filter((f) => normalDot(require_faceFns.normalAt(f), ref.hint.normalA) > BLEND_THRESHOLD && normalDot(require_faceFns.normalAt(f), ref.hint.normalB) > BLEND_THRESHOLD);
+	if (blended.length === 1) {
+		const [only] = blended;
+		if (only !== void 0) return {
+			face: only,
+			confidence: "geometric-fallback"
+		};
+	}
+	if (blended.length > 1) {
+		const best = ref.hint.edgeMidpoint && nearestFace(blended, ref.hint.edgeMidpoint);
+		if (best) return {
+			face: best,
+			confidence: "geometric-fallback"
+		};
+		return {
+			ref,
+			reason: "ambiguous",
+			candidates: blended
+		};
+	}
+	return {
+		ref,
+		reason: "not-found"
+	};
+}
+//#endregion
+//#region src/topology/shapeRef/refResolveFns.ts
+function isRefObject(v) {
+	return typeof v === "object" && v !== null && "origin" in v;
+}
+/** A generated-face ref: carries the bridged roles + the op that made it. */
+function isDerivedFaceRef(v) {
+	return isRefObject(v) && "betweenRoles" in v && "op" in v;
+}
+/** An edge ref: exactly two adjacent face-roles. */
+function isEdgeRef(v) {
+	return isRefObject(v) && Array.isArray(v["faceRoles"]) && v["faceRoles"].length === 2;
+}
+/** A vertex ref: three or more adjacent face-roles. */
+function isVertexRef(v) {
+	return isRefObject(v) && Array.isArray(v["faceRoles"]) && v["faceRoles"].length >= 3;
+}
+/** A face ref: a single role name. */
+function isFaceRef(v) {
+	return isRefObject(v) && typeof v["role"] === "string";
+}
+/** True for any of the four lineage reference kinds. */
+function isLineageRef(v) {
+	return isFaceRef(v) || isEdgeRef(v) || isVertexRef(v) || isDerivedFaceRef(v);
+}
+function brokenResolution(reason, candidates) {
+	return candidates === void 0 ? {
+		ok: false,
+		reason
+	} : {
+		ok: false,
+		reason,
+		candidates
+	};
+}
+/**
+* Resolve a lineage ref against `shape` using a prepared role table (the robust
+* path — the table is maintained across edits via `updateRoles`). Returns the
+* live entity on success, or the failure reason (and tied candidates) on failure.
+*/
+function resolveLineageRef(ref, roles, shape) {
+	if (isDerivedFaceRef(ref)) {
+		const r = resolveDerivedFaceRef(ref, roles, shape);
+		return "face" in r ? {
+			ok: true,
+			entity: r.face
+		} : brokenResolution(r.reason, r.candidates);
+	}
+	if (isEdgeRef(ref)) {
+		const r = resolveEdgeRef(ref, roles, shape);
+		return "edge" in r ? {
+			ok: true,
+			entity: r.edge
+		} : brokenResolution(r.reason, r.candidates);
+	}
+	if (isVertexRef(ref)) {
+		const r = resolveVertexRef(ref, roles, shape);
+		return "vertex" in r ? {
+			ok: true,
+			entity: r.vertex
+		} : brokenResolution(r.reason, r.candidates);
+	}
+	const r = resolveRef(ref, roles, shape);
+	return "face" in r ? {
+		ok: true,
+		entity: r.face
+	} : brokenResolution(r.reason, r.candidates);
+}
+/** Role table for a from-scratch rebuild, reusing a per-origin cache. */
+function rolesFor(ref, shape, cache) {
+	const cached = cache.get(ref.origin);
+	if (cached !== void 0) return cached;
+	const roles = new Map([[ref.origin, assignRoles(shape, ref.origin)]]);
+	cache.set(ref.origin, roles);
+	return roles;
+}
+/**
+* Resolve a lineage ref against a freshly rebuilt `shape` with no maintained
+* role table, re-deriving roles via `assignRoles(shape, ref.origin)`. The ref's
+* `origin` must therefore be the role-assignment scheme (e.g. `'box'`), and
+* stability is bounded by that scheme — `'box'` names faces semantically
+* (rebuild-stable); other schemes fall back to positional `face_N`.
+*/
+function resolveRefIn(ref, shape) {
+	return resolveLineageRef(ref, rolesFor(ref, shape, /* @__PURE__ */ new Map()), shape);
+}
+/**
+* Replace every lineage ref in an operation's params with the live entity it
+* resolves to in `shape`, recursing into arrays (multi-entity selections like a
+* fillet's edge list). Refs that can't resolve are left as-is. Role tables are
+* re-derived once per `origin` and reused across the whole params map. Lets a
+* replay engine pass stable entity selections that survive upstream edits.
+*/
+function resolveRefParams(params, shape) {
+	const roleCache = /* @__PURE__ */ new Map();
+	const resolveValue = (value) => {
+		if (Array.isArray(value)) return value.map(resolveValue);
+		if (!isLineageRef(value)) return value;
+		const res = resolveLineageRef(value, rolesFor(value, shape, roleCache), shape);
+		return res.ok ? res.entity : value;
+	};
+	const out = { ...params };
+	for (const [key, value] of Object.entries(params)) out[key] = resolveValue(value);
+	return out;
+}
+//#endregion
+Object.defineProperty(exports, "assignRoles", {
+	enumerable: true,
+	get: function() {
+		return assignRoles;
+	}
+});
+Object.defineProperty(exports, "captureHint", {
+	enumerable: true,
+	get: function() {
+		return captureHint;
+	}
+});
+Object.defineProperty(exports, "createDerivedFaceRef", {
+	enumerable: true,
+	get: function() {
+		return createDerivedFaceRef;
+	}
+});
+Object.defineProperty(exports, "createEdgeRef", {
+	enumerable: true,
+	get: function() {
+		return createEdgeRef;
+	}
+});
+Object.defineProperty(exports, "createRef", {
+	enumerable: true,
+	get: function() {
+		return createRef;
+	}
+});
+Object.defineProperty(exports, "createVertexRef", {
+	enumerable: true,
+	get: function() {
+		return createVertexRef;
+	}
+});
+Object.defineProperty(exports, "defaultScorer", {
+	enumerable: true,
+	get: function() {
+		return defaultScorer;
+	}
+});
+Object.defineProperty(exports, "isDerivedFaceRef", {
+	enumerable: true,
+	get: function() {
+		return isDerivedFaceRef;
+	}
+});
+Object.defineProperty(exports, "isEdgeRef", {
+	enumerable: true,
+	get: function() {
+		return isEdgeRef;
+	}
+});
+Object.defineProperty(exports, "isFaceRef", {
+	enumerable: true,
+	get: function() {
+		return isFaceRef;
+	}
+});
+Object.defineProperty(exports, "isLineageRef", {
+	enumerable: true,
+	get: function() {
+		return isLineageRef;
+	}
+});
+Object.defineProperty(exports, "isVertexRef", {
+	enumerable: true,
+	get: function() {
+		return isVertexRef;
+	}
+});
+Object.defineProperty(exports, "resolveDerivedFaceRef", {
+	enumerable: true,
+	get: function() {
+		return resolveDerivedFaceRef;
+	}
+});
+Object.defineProperty(exports, "resolveEdgeRef", {
+	enumerable: true,
+	get: function() {
+		return resolveEdgeRef;
+	}
+});
+Object.defineProperty(exports, "resolveLineageRef", {
+	enumerable: true,
+	get: function() {
+		return resolveLineageRef;
+	}
+});
+Object.defineProperty(exports, "resolveRef", {
+	enumerable: true,
+	get: function() {
+		return resolveRef;
+	}
+});
+Object.defineProperty(exports, "resolveRefIn", {
+	enumerable: true,
+	get: function() {
+		return resolveRefIn;
+	}
+});
+Object.defineProperty(exports, "resolveRefParams", {
+	enumerable: true,
+	get: function() {
+		return resolveRefParams;
+	}
+});
+Object.defineProperty(exports, "resolveVertexRef", {
+	enumerable: true,
+	get: function() {
+		return resolveVertexRef;
+	}
+});
+Object.defineProperty(exports, "updateRoles", {
+	enumerable: true,
+	get: function() {
+		return updateRoles;
+	}
+});