brepjs 18.113.0 → 18.115.0

package/dist/refResolveFns-hEOEcFZ8.js

@@ -0,0 +1,761 @@
+import { S as vertexPosition, c as getFaces } from "./topologyQueryFns-BeKaWpNm.js";
+import { i as faceGeomType, l as normalAt, r as faceCenter } from "./faceFns-B86WGqDg.js";
+import { n as getHashCode } from "./shapeFns-DrZOVwHX.js";
+import { n as measureArea, s as measureLength } from "./measureFns-a5Vx25or.js";
+import { a as sharedEdges, i as facesOfVertex, o as verticesOfEdge, r as facesOfEdge, s as verticesOfFace, t as adjacentFaces } from "./adjacencyFns-BYnyXXqt.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] < -.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";
+}
+/** Axial cap name for a Z-axis primitive: 'top' (+Z) / 'bottom' (-Z). */
+function axialCapName(prefix, face) {
+	if (faceGeomType(face) !== "PLANE") return void 0;
+	const z = normalAt(face)[2];
+	if (z > AXIS_THRESHOLD) return `${prefix}:top`;
+	if (z < -.9) return `${prefix}:bottom`;
+}
+/** Semantic role for a Z-axis cylinder face: top/bottom caps + lateral wall. */
+function cylinderRole(face) {
+	return faceGeomType(face) === "CYLINDRE" ? "cylinder:lateral" : axialCapName("cylinder", face);
+}
+/** Semantic role for a Z-axis cone/frustum face: top/bottom caps + lateral. */
+function coneRole(face) {
+	return faceGeomType(face) === "CONE" ? "cone:lateral" : axialCapName("cone", face);
+}
+/** Semantic role for a sphere's single spherical face. */
+function sphereRole(face) {
+	return faceGeomType(face) === "SPHERE" ? "sphere:surface" : void 0;
+}
+/** Per-primitive semantic face namers, keyed by operation type. */
+var ROLE_ASSIGNERS = {
+	box: (face) => boxRoleFromNormal(normalAt(face)),
+	cylinder: cylinderRole,
+	cone: coneRole,
+	sphere: sphereRole
+};
+/**
+* Auto-assign role names to a shape's faces from its operation type.
+*
+* Known primitives get **semantic** names from face geometry — rebuild-stable
+* across parameter edits that preserve orientation:
+* - `box`: cardinal names by normal ('box:top'/'bottom'/'front'/'back'/'left'/'right').
+* - `cylinder`/`cone` (Z-axis): 'top'/'bottom' caps + 'lateral' wall.
+* - `sphere`: 'sphere:surface'.
+*
+* Faces a primitive namer doesn't recognize (a rotated box's non-cardinal faces),
+* and every face of any other operation type, fall back to positional names
+* ('opType:face_0', 'opType:face_1', ...) — so each face always gets a role.
+*
+* @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 roles = /* @__PURE__ */ new Map();
+	const assigner = ROLE_ASSIGNERS[operationType];
+	let index = 0;
+	for (const face of getFaces(shape)) {
+		const semantic = assigner?.(face);
+		const role = semantic !== void 0 && !roles.has(semantic) ? semantic : `${operationType}:face_${index}`;
+		roles.set(role, [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 = 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(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 = 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 = 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 getFaces(shape).filter((f) => hashes.includes(getHashCode(f)));
+}
+//#endregion
+//#region src/topology/shapeRef/edgeRefFns.ts
+function captureEdgeHint(edge) {
+	const lengthResult = measureLength(edge);
+	return {
+		entityType: "edge",
+		length: lengthResult.ok ? lengthResult.value : void 0,
+		midpoint: vertexCentroid(verticesOfEdge(edge))
+	};
+}
+function dedupeEdges(edges) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const e of edges) {
+		const h = 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 = measureLength(edge);
+			if (len.ok) score += Math.abs(len.value - hint.length);
+		}
+		if (hint.midpoint !== void 0) {
+			const mid = vertexCentroid(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] = 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(...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 verticesOfFace(f)) {
+		const h = 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(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 = 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: 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 getFaces(shape).filter((f) => normalDot(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(getHashCode));
+	const adjacentToA = /* @__PURE__ */ new Set();
+	for (const a of aFaces) for (const f of adjacentFaces(shape, a)) adjacentToA.add(getHashCode(f));
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const b of bFaces) for (const f of adjacentFaces(shape, b)) {
+		const h = 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(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] = 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: normalAt(faceA),
+			normalB: normalAt(faceB),
+			edgeMidpoint: vertexCentroid(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(normalAt(f), ref.hint.normalA) > BLEND_THRESHOLD && normalDot(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
+export { createRef as _, isVertexRef as a, defaultScorer as b, resolveRefParams as c, createVertexRef as d, resolveVertexRef as f, captureHint as g, assignRoles as h, isLineageRef as i, createDerivedFaceRef as l, resolveEdgeRef as m, isEdgeRef as n, resolveLineageRef as o, createEdgeRef as p, isFaceRef as r, resolveRefIn as s, isDerivedFaceRef as t, resolveDerivedFaceRef as u, resolveRef as v, updateRoles as y };