brepjs 18.111.0 → 18.113.0

package/dist/brepjs.cjs

@@ -16,7 +16,7 @@ const require_meshFns = require("./meshFns-1hQSn1p2.cjs");
 const require_arrayAccess = require("./arrayAccess-e4H9cBfh.cjs");
 const require_surfaceBuilders = require("./surfaceBuilders-UyyfZy8w.cjs");
 const require_solidBuilders = require("./solidBuilders-DiUv_mD0.cjs");
-const require_healingFns = require("./healingFns-C4UE1ZyM.cjs");
+const require_healingFns = require("./healingFns-x1sHV-HO.cjs");
 const require_threadFns = require("./threadFns-C8bErjVC.cjs");
 const require_blueprintSketcher = require("./blueprintSketcher-RK-cH6ps.cjs");
 const require_helpers = require("./helpers-BSLPCflF.cjs");
@@ -1175,9 +1175,16 @@ function withKernelDir(v, fn) {
 	}
 }
 //#endregion
-//#region src/topology/shapeRef/edgeRefFns.ts
-/** Midpoint of an edge's endpoint vertices (a closed edge collapses to one). */
-function endpointMidpoint(verts) {
+//#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;
@@ -1195,33 +1202,29 @@ function endpointMidpoint(verts) {
 		z / n
 	];
 }
-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);
-}
-function captureEdgeHint(edge) {
-	const lengthResult = require_measureFns.measureLength(edge);
-	return {
-		entityType: "edge",
-		length: lengthResult.ok ? lengthResult.value : void 0,
-		midpoint: endpointMidpoint(require_healingFns.verticesOfEdge(edge))
-	};
-}
-/** Reverse the role table: the role whose tracked hashes include this face. */
+/** 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`). */
+/** 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_healingFns.verticesOfEdge(edge))
+	};
+}
 function dedupeEdges(edges) {
 	const seen = /* @__PURE__ */ new Set();
 	const out = [];
@@ -1235,7 +1238,7 @@ function dedupeEdges(edges) {
 	return out;
 }
 /** Hint scores closer than this are treated as indistinguishable (→ ambiguous). */
-var HINT_MARGIN = 1e-6;
+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
@@ -1254,7 +1257,7 @@ function bestByHint(candidates, hint) {
 			if (len.ok) score += Math.abs(len.value - hint.length);
 		}
 		if (hint.midpoint !== void 0) {
-			const mid = endpointMidpoint(require_healingFns.verticesOfEdge(edge));
+			const mid = vertexCentroid(require_healingFns.verticesOfEdge(edge));
 			if (mid !== void 0) score += distance(hint.midpoint, mid);
 		}
 		if (score < bestScore) {
@@ -1263,7 +1266,7 @@ function bestByHint(candidates, hint) {
 			best = edge;
 		} else if (score < secondScore) secondScore = score;
 	}
-	if (best === void 0 || secondScore - bestScore < HINT_MARGIN) return void 0;
+	if (best === void 0 || secondScore - bestScore < HINT_MARGIN$2) return void 0;
 	return best;
 }
 /**
@@ -1325,6 +1328,237 @@ function resolveEdgeRef(ref, roles, shape) {
 	};
 }
 //#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_healingFns.verticesOfFace(f)) {
+		const h = require_shapeFns.getHashCode(v);
+		hashes.add(h);
+		if (!handles.has(h)) handles.set(h, v);
+	}
+	return hashes;
+}
+function intersect$2(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$2(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_healingFns.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_healingFns.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_healingFns.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_healingFns.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_healingFns.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/surfaceFns.ts
 /**
 * Surface creation functions — generate faces from height-map grids.
@@ -7028,6 +7262,7 @@ exports.createBlueprint = require_blueprintFns.createBlueprint;
 exports.createCamera = require_cameraFns.createCamera;
 exports.createCompound = require_shapeTypes.createCompound;
 exports.createCompoundBlueprint = require_blueprintFns.createCompoundBlueprint;
+exports.createDerivedFaceRef = createDerivedFaceRef;
 exports.createDistanceQuery = require_measureFns.createDistanceQuery;
 exports.createEdge = require_shapeTypes.createEdge;
 exports.createEdgeRef = createEdgeRef;
@@ -7045,6 +7280,7 @@ exports.createShell = require_shapeTypes.createShell;
 exports.createSolid = require_shapeTypes.createSolid;
 exports.createTaskQueue = require_workerPool.createTaskQueue;
 exports.createVertex = require_shapeTypes.createVertex;
+exports.createVertexRef = createVertexRef;
 exports.createWire = require_shapeTypes.createWire;
 exports.createWorkerClient = require_workerPool.createWorkerClient;
 exports.createWorkerHandler = require_workerPool.createWorkerHandler;
@@ -7136,6 +7372,7 @@ exports.faceFinder = require_helpers.faceFinder;
 exports.faceGeomType = require_faceFns.faceGeomType;
 exports.faceOrientation = require_faceFns.faceOrientation;
 exports.facesOfEdge = require_healingFns.facesOfEdge;
+exports.facesOfVertex = require_healingFns.facesOfVertex;
 exports.fieldBoolean = fieldBoolean;
 exports.fieldContour = fieldContour;
 exports.fieldOffset = fieldOffset;
@@ -7417,10 +7654,12 @@ exports.resetPerformanceStats = require_shapeTypes.resetPerformanceStats;
 exports.resize = require_shapeFns.resize;
 exports.resolve = resolve;
 exports.resolve3D = resolve3D;
+exports.resolveDerivedFaceRef = resolveDerivedFaceRef;
 exports.resolveDirection = require_types.resolveDirection;
 exports.resolveEdgeRef = resolveEdgeRef;
 exports.resolvePlane = require_planeOps.resolvePlane;
 exports.resolveRef = require_shapeRefFns.resolveRef;
+exports.resolveVertexRef = resolveVertexRef;
 exports.reverseCurve = require_blueprintFns.reverseCurve;
 exports.revoluteJoint = require_threadFns.revoluteJoint;
 exports.revolve = revolve;
@@ -7570,6 +7809,7 @@ exports.vertex = require_primitiveFns.vertex;
 exports.vertexFinder = vertexFinder;
 exports.vertexPosition = require_topologyQueryFns.vertexPosition;
 exports.verticesOfEdge = require_healingFns.verticesOfEdge;
+exports.verticesOfFace = require_healingFns.verticesOfFace;
 exports.voxelBoolean = voxelBoolean;
 exports.voxelBooleanField = voxelBooleanField;
 exports.voxelBooleanFieldShapes = voxelBooleanFieldShapes;

package/dist/brepjs.js

@@ -13,8 +13,8 @@ import { a as curveIsPeriodic, c as curvePointAt, d as flipOrientation, f as get
 import { a as meshEdges$1, c as meshMultiLOD, d as createMeshCache, i as mesh$1, l as buildMeshCacheKey, n as exportSTEP, o as meshLODs, r as exportSTL, s as meshLODsProgressive, t as exportIGES, u as clearMeshCache } from "./meshFns-DbmidUzH.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-rkE-jE90.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-C32wXQWG.js";
-import { A as edgesOfFace, B as toLineGeometryData, 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 toLODGeometryLevels } from "./healingFns-CPm_VFck.js";
+import { _ as section$1, b as split$1, d as booleanPipeline, f as cut$2, g as intersect$3, 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-C32wXQWG.js";
+import { A as edgesOfFace, B as toLODGeometryData, C as shellWithEvolution, D as getNurbsCurveData, E as fuseAllBisect, F as verticesOfFace, H as toLineGeometryData, I as wiresOfFace, L as chamferDistAngle, M as facesOfVertex, N as sharedEdges, O as getNurbsSurfaceData, P as verticesOfEdge, R as toBufferGeometryData, S as intersectWithEvolution, T as cutAllBisect, V as toLODGeometryLevels, _ 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 toGroupedBufferGeometryData } from "./healingFns-D00TPE9p.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-bCOhVQLb.js";
 import { n as BaseSketcher2d, r as organiseBlueprints, t as BlueprintSketcher } from "./blueprintSketcher-7rtwqUHZ.js";
 import { a as createTypedFinder, i as wireFinder, n as edgeFinder, r as faceFinder, t as getSingleFace } from "./helpers-DhJwFrkC.js";
@@ -1186,9 +1186,16 @@ function withKernelDir(v, fn) {
 	}
 }
 //#endregion
-//#region src/topology/shapeRef/edgeRefFns.ts
-/** Midpoint of an edge's endpoint vertices (a closed edge collapses to one). */
-function endpointMidpoint(verts) {
+//#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;
@@ -1206,33 +1213,29 @@ function endpointMidpoint(verts) {
 		z / n
 	];
 }
-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);
-}
-function captureEdgeHint(edge) {
-	const lengthResult = measureLength(edge);
-	return {
-		entityType: "edge",
-		length: lengthResult.ok ? lengthResult.value : void 0,
-		midpoint: endpointMidpoint(verticesOfEdge(edge))
-	};
-}
-/** Reverse the role table: the role whose tracked hashes include this face. */
+/** 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`). */
+/** 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 = [];
@@ -1246,7 +1249,7 @@ function dedupeEdges(edges) {
 	return out;
 }
 /** Hint scores closer than this are treated as indistinguishable (→ ambiguous). */
-var HINT_MARGIN = 1e-6;
+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
@@ -1265,7 +1268,7 @@ function bestByHint(candidates, hint) {
 			if (len.ok) score += Math.abs(len.value - hint.length);
 		}
 		if (hint.midpoint !== void 0) {
-			const mid = endpointMidpoint(verticesOfEdge(edge));
+			const mid = vertexCentroid(verticesOfEdge(edge));
 			if (mid !== void 0) score += distance(hint.midpoint, mid);
 		}
 		if (score < bestScore) {
@@ -1274,7 +1277,7 @@ function bestByHint(candidates, hint) {
 			best = edge;
 		} else if (score < secondScore) secondScore = score;
 	}
-	if (best === void 0 || secondScore - bestScore < HINT_MARGIN) return void 0;
+	if (best === void 0 || secondScore - bestScore < HINT_MARGIN$2) return void 0;
 	return best;
 }
 /**
@@ -1336,6 +1339,237 @@ function resolveEdgeRef(ref, roles, shape) {
 	};
 }
 //#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$2(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$2(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/surfaceFns.ts
 /**
 * Surface creation functions — generate faces from height-map grids.
@@ -3664,7 +3898,7 @@ function cutAll(base, tools, options) {
 }
 /** Compute the intersection of two shapes (boolean common). */
 function intersect(a, b, options) {
-	return intersect$2(resolve(a), resolve(b), {
+	return intersect$3(resolve(a), resolve(b), {
 		...options,
 		unsafe: true
 	});
@@ -5781,7 +6015,7 @@ function evalIntersect(node, ctx) {
 	if (!a.ok) return a;
 	const b = resolveOperand(ctx, node.b, "Intersect.b");
 	if (!b.ok) return b;
-	return intersect$2(a.value, b.value, boolOptions(node, ctx));
+	return intersect$3(a.value, b.value, boolOptions(node, ctx));
 }
 function resolveAll(ctx, nodes, where) {
 	const out = [];
@@ -6936,4 +7170,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, createEdgeRef, createFace, createHandle, createHistory, createKernelHandle, createMeshCache, createNamedPlane, createOperationRegistry, createPlane, createRef, createRegistry, createShell, createSolid, createTaskQueue, createVertex, createWire, createWorkerClient, createWorkerHandler, createWorkerPool, 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, isBatchRequest, 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, meshLODs, meshLODsProgressive, 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, resolveEdgeRef, 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, toLODGeometryLevels, 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, createDerivedFaceRef, createDistanceQuery, createEdge, createEdgeRef, createFace, createHandle, createHistory, createKernelHandle, createMeshCache, createNamedPlane, createOperationRegistry, createPlane, createRef, createRegistry, createShell, createSolid, createTaskQueue, createVertex, createVertexRef, createWire, createWorkerClient, createWorkerHandler, createWorkerPool, 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, facesOfVertex, 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, isBatchRequest, 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, meshLODs, meshLODsProgressive, 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, resolveDerivedFaceRef, resolveDirection, resolveEdgeRef, resolvePlane, resolveRef, resolveVertexRef, 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, toLODGeometryLevels, 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, verticesOfFace, 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/{healingFns-CPm_VFck.js → healingFns-D00TPE9p.js}

@@ -220,6 +220,30 @@ function getEdgeToFacesMap(parent) {
 	return edgeToFaces;
 }
 /**
+* Build or retrieve the cached vertex→faces adjacency map for a parent shape —
+* the vertex analogue of {@link getEdgeToFacesMap}.
+*/
+function getVertexToFacesMap(parent) {
+	const cache = getOrCreateCache(parent);
+	if (cache.vertexToFaces) return cache.vertexToFaces;
+	const kernel = getKernel();
+	const vertexToFaces = /* @__PURE__ */ new Map();
+	for (const f of kernel.iterShapes(parent.wrapped, "face")) for (const v of kernel.iterShapes(f, "vertex")) {
+		const hash = kernel.hashCode(v, HASH_CODE_MAX);
+		let bucket = vertexToFaces.get(hash);
+		if (!bucket) {
+			bucket = [];
+			vertexToFaces.set(hash, bucket);
+		}
+		if (!bucket.some((entry) => kernel.isSame(entry.vertex, v) && kernel.isSame(entry.face, f))) bucket.push({
+			vertex: v,
+			face: f
+		});
+	}
+	cache.vertexToFaces = vertexToFaces;
+	return vertexToFaces;
+}
+/**
 * Get all faces adjacent to a given edge within a parent shape.
 *
 * An edge typically borders exactly two faces in a solid, or one face
@@ -251,6 +275,35 @@ function facesOfEdge(parent, edge) {
 	return wrapAll(results, "face");
 }
 /**
+* Get all faces meeting at a vertex (≥3 for a solid corner, fewer on a
+* boundary), via the cached vertex→faces map. The vertex equivalent of
+* {@link facesOfEdge}, with the same hash-bucket + isSame verification.
+*
+* @param parent - The parent shape to search within.
+* @param vertex - The vertex whose adjacent faces to find.
+*/
+function facesOfVertex(parent, vertex) {
+	const kernel = getKernel();
+	const vertexToFaces = getVertexToFacesMap(parent);
+	const hash = kernel.hashCode(vertex.wrapped, HASH_CODE_MAX);
+	const bucket = vertexToFaces.get(hash) ?? [];
+	const results = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const entry of bucket) {
+		if (!kernel.isSame(entry.vertex, vertex.wrapped)) continue;
+		const fHash = kernel.hashCode(entry.face, HASH_CODE_MAX);
+		const fBucket = seen.get(fHash);
+		if (!fBucket) {
+			seen.set(fHash, [entry.face]);
+			results.push(entry.face);
+		} else if (!fBucket.some((r) => kernel.isSame(r, entry.face))) {
+			fBucket.push(entry.face);
+			results.push(entry.face);
+		}
+	}
+	return wrapAll(results, "face");
+}
+/**
 * Get all edges bounding a face.
 *
 * @param face - The face whose edges to enumerate.
@@ -260,6 +313,14 @@ function edgesOfFace(face) {
 	return deduplicatedSubShapes(face.wrapped, "edge");
 }
 /**
+* Get all vertices of a face. The vertex equivalent of {@link edgesOfFace}.
+*
+* @param face - The face whose vertices to enumerate.
+*/
+function verticesOfFace(face) {
+	return deduplicatedSubShapes(face.wrapped, "vertex");
+}
+/**
 * Get all wires of a face (outer wire + inner hole wires).
 * All wires bounding a face are closed by definition.
 *
@@ -1376,4 +1437,4 @@ function fixSelfIntersection(wire) {
 	}
 }
 //#endregion
-export { edgesOfFace as A, toLineGeometryData as B, shellWithEvolution as C, getNurbsCurveData as D, fuseAllBisect as E, chamferDistAngle as F, toBufferGeometryData as I, toGroupedBufferGeometryData as L, sharedEdges as M, verticesOfEdge as N, getNurbsSurfaceData as O, wiresOfFace as P, toLODGeometryData as R, intersectWithEvolution as S, cutAllBisect as T, positionOnCurve as _, healFace as a, filletWithEvolution as b, isValid as c, draft as d, fillet as f, variableFillet as g, thicken as h, heal as i, facesOfEdge as j, adjacentFaces as k, solidFromShell as l, shell as m, fixSelfIntersection as n, healSolid as o, offset as p, fixShape as r, healWire as s, autoHeal as t, chamfer as u, chamferWithEvolution as v, checkBoolean as w, fuseWithEvolution as x, cutWithEvolution as y, toLODGeometryLevels as z };
+export { edgesOfFace as A, toLODGeometryData as B, shellWithEvolution as C, getNurbsCurveData as D, fuseAllBisect as E, verticesOfFace as F, toLineGeometryData as H, wiresOfFace as I, chamferDistAngle as L, facesOfVertex as M, sharedEdges as N, getNurbsSurfaceData as O, verticesOfEdge as P, toBufferGeometryData as R, intersectWithEvolution as S, cutAllBisect as T, toLODGeometryLevels as V, positionOnCurve as _, healFace as a, filletWithEvolution as b, isValid as c, draft as d, fillet as f, variableFillet as g, thicken as h, heal as i, facesOfEdge as j, adjacentFaces as k, solidFromShell as l, shell as m, fixSelfIntersection as n, healSolid as o, offset as p, fixShape as r, healWire as s, autoHeal as t, chamfer as u, chamferWithEvolution as v, checkBoolean as w, fuseWithEvolution as x, cutWithEvolution as y, toGroupedBufferGeometryData as z };

package/dist/{healingFns-C4UE1ZyM.cjs → healingFns-x1sHV-HO.cjs}

@@ -220,6 +220,30 @@ function getEdgeToFacesMap(parent) {
 	return edgeToFaces;
 }
 /**
+* Build or retrieve the cached vertex→faces adjacency map for a parent shape —
+* the vertex analogue of {@link getEdgeToFacesMap}.
+*/
+function getVertexToFacesMap(parent) {
+	const cache = require_topologyQueryFns.getOrCreateCache(parent);
+	if (cache.vertexToFaces) return cache.vertexToFaces;
+	const kernel = require_shapeTypes.getKernel();
+	const vertexToFaces = /* @__PURE__ */ new Map();
+	for (const f of kernel.iterShapes(parent.wrapped, "face")) for (const v of kernel.iterShapes(f, "vertex")) {
+		const hash = kernel.hashCode(v, require_constants.HASH_CODE_MAX);
+		let bucket = vertexToFaces.get(hash);
+		if (!bucket) {
+			bucket = [];
+			vertexToFaces.set(hash, bucket);
+		}
+		if (!bucket.some((entry) => kernel.isSame(entry.vertex, v) && kernel.isSame(entry.face, f))) bucket.push({
+			vertex: v,
+			face: f
+		});
+	}
+	cache.vertexToFaces = vertexToFaces;
+	return vertexToFaces;
+}
+/**
 * Get all faces adjacent to a given edge within a parent shape.
 *
 * An edge typically borders exactly two faces in a solid, or one face
@@ -251,6 +275,35 @@ function facesOfEdge(parent, edge) {
 	return wrapAll(results, "face");
 }
 /**
+* Get all faces meeting at a vertex (≥3 for a solid corner, fewer on a
+* boundary), via the cached vertex→faces map. The vertex equivalent of
+* {@link facesOfEdge}, with the same hash-bucket + isSame verification.
+*
+* @param parent - The parent shape to search within.
+* @param vertex - The vertex whose adjacent faces to find.
+*/
+function facesOfVertex(parent, vertex) {
+	const kernel = require_shapeTypes.getKernel();
+	const vertexToFaces = getVertexToFacesMap(parent);
+	const hash = kernel.hashCode(vertex.wrapped, require_constants.HASH_CODE_MAX);
+	const bucket = vertexToFaces.get(hash) ?? [];
+	const results = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const entry of bucket) {
+		if (!kernel.isSame(entry.vertex, vertex.wrapped)) continue;
+		const fHash = kernel.hashCode(entry.face, require_constants.HASH_CODE_MAX);
+		const fBucket = seen.get(fHash);
+		if (!fBucket) {
+			seen.set(fHash, [entry.face]);
+			results.push(entry.face);
+		} else if (!fBucket.some((r) => kernel.isSame(r, entry.face))) {
+			fBucket.push(entry.face);
+			results.push(entry.face);
+		}
+	}
+	return wrapAll(results, "face");
+}
+/**
 * Get all edges bounding a face.
 *
 * @param face - The face whose edges to enumerate.
@@ -260,6 +313,14 @@ function edgesOfFace(face) {
 	return deduplicatedSubShapes(face.wrapped, "edge");
 }
 /**
+* Get all vertices of a face. The vertex equivalent of {@link edgesOfFace}.
+*
+* @param face - The face whose vertices to enumerate.
+*/
+function verticesOfFace(face) {
+	return deduplicatedSubShapes(face.wrapped, "vertex");
+}
+/**
 * Get all wires of a face (outer wire + inner hole wires).
 * All wires bounding a face are closed by definition.
 *
@@ -1442,6 +1503,12 @@ Object.defineProperty(exports, "facesOfEdge", {
 		return facesOfEdge;
 	}
 });
+Object.defineProperty(exports, "facesOfVertex", {
+	enumerable: true,
+	get: function() {
+		return facesOfVertex;
+	}
+});
 Object.defineProperty(exports, "fillet", {
 	enumerable: true,
 	get: function() {
@@ -1610,6 +1677,12 @@ Object.defineProperty(exports, "verticesOfEdge", {
 		return verticesOfEdge;
 	}
 });
+Object.defineProperty(exports, "verticesOfFace", {
+	enumerable: true,
+	get: function() {
+		return verticesOfFace;
+	}
+});
 Object.defineProperty(exports, "wiresOfFace", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.ts

@@ -87,7 +87,7 @@ export { tagFaces, findFacesByTag, getFaceTags, setTagMetadata, getTagMetadata,
 export { colorFaces, colorShape, getFaceColor, getShapeColor, } from './topology/metadata/colorFns.js';
 export type { Color, ColorInput } from './topology/metadata/colorFns.js';
 export { chamferDistAngle as chamferDistAngleShape } from './topology/chamferAngleFns.js';
-export { facesOfEdge, edgesOfFace, wiresOfFace, verticesOfEdge, adjacentFaces, sharedEdges, } from './topology/adjacencyFns.js';
+export { facesOfEdge, edgesOfFace, wiresOfFace, verticesOfEdge, verticesOfFace, facesOfVertex, adjacentFaces, sharedEdges, } from './topology/adjacencyFns.js';
 export { getCurveType, curveStartPoint, curveEndPoint, curvePointAt, curveTangentAt, curveAxis, curveLength, curveIsClosed, curveIsPeriodic, curvePeriod, getOrientation, flipOrientation, offsetWire2D, interpolateCurve, approximateCurve, type InterpolateCurveOptions, type ApproximateCurveOptions, } from './topology/curveFns.js';
 export { getNurbsCurveData, getNurbsSurfaceData } from './topology/nurbsFns.js';
 export type { NurbsCurveData, NurbsSurfaceData } from './kernel/types.js';
@@ -102,8 +102,8 @@ export { checkBoolean } from './topology/booleanDiagnosticFns.js';
 export type { CheckBooleanResult, BooleanIssue, BooleanOpType, BooleanDiagnostics, } from './kernel/types.js';
 export { fuseWithEvolution, cutWithEvolution, intersectWithEvolution, filletWithEvolution, chamferWithEvolution, shellWithEvolution, type EvolutionResult, } from './topology/evolutionFns.js';
 export type { ShapeEvolution } from './kernel/types.js';
-export { captureHint, assignRoles, createRef, updateRoles, resolveRef, defaultScorer, createEdgeRef, resolveEdgeRef, } from './topology/shapeRef/index.js';
-export type { GeometricHint, ShapeRef, RoleTable, ResolvedRef, BrokenRef, FaceScorer, EdgeHint, EdgeRef, ResolvedEdgeRef, BrokenEdgeRef, } from './topology/shapeRef/index.js';
+export { captureHint, assignRoles, createRef, updateRoles, resolveRef, defaultScorer, createEdgeRef, resolveEdgeRef, createVertexRef, resolveVertexRef, createDerivedFaceRef, resolveDerivedFaceRef, } from './topology/shapeRef/index.js';
+export type { GeometricHint, ShapeRef, RoleTable, ResolvedRef, BrokenRef, FaceScorer, EdgeHint, EdgeRef, ResolvedEdgeRef, BrokenEdgeRef, VertexHint, VertexRef, ResolvedVertexRef, BrokenVertexRef, DerivedFaceHint, DerivedFaceRef, ResolvedDerivedFaceRef, BrokenDerivedFaceRef, } from './topology/shapeRef/index.js';
 export { surfaceFromGrid, surfaceFromImage, type SurfaceFromGridOptions, type SurfaceFromImageOptions, } from './topology/surfaceFns.js';
 export { hull, type HullOptions } from './topology/hullFns.js';
 export { convexHull } from './operations/convexHullFns.js';

package/dist/topology/adjacencyFns.d.ts

@@ -10,6 +10,15 @@ import { AnyShape, ClosedWire, Dimension, Edge, Face, Vertex } from '../core/sha
  * @returns Array of unique faces containing the given edge.
  */
 export declare function facesOfEdge<D extends Dimension>(parent: AnyShape<D>, edge: Edge<D>): Face<D>[];
+/**
+ * Get all faces meeting at a vertex (≥3 for a solid corner, fewer on a
+ * boundary), via the cached vertex→faces map. The vertex equivalent of
+ * {@link facesOfEdge}, with the same hash-bucket + isSame verification.
+ *
+ * @param parent - The parent shape to search within.
+ * @param vertex - The vertex whose adjacent faces to find.
+ */
+export declare function facesOfVertex<D extends Dimension>(parent: AnyShape<D>, vertex: Vertex<D>): Face<D>[];
 /**
  * Get all edges bounding a face.
  *
@@ -17,6 +26,12 @@ export declare function facesOfEdge<D extends Dimension>(parent: AnyShape<D>, ed
  * @returns Array of unique edges forming the face boundary.
  */
 export declare function edgesOfFace<D extends Dimension>(face: Face<D>): Edge<D>[];
+/**
+ * Get all vertices of a face. The vertex equivalent of {@link edgesOfFace}.
+ *
+ * @param face - The face whose vertices to enumerate.
+ */
+export declare function verticesOfFace<D extends Dimension>(face: Face<D>): Vertex<D>[];
 /**
  * Get all wires of a face (outer wire + inner hole wires).
  * All wires bounding a face are closed by definition.

package/dist/topology/shapeRef/derivedFaceRefFns.d.ts

@@ -0,0 +1,16 @@
+import { Edge, Shape3D } from '../../core/shapeTypes.js';
+import { DerivedFaceRef, ResolvedDerivedFaceRef, BrokenDerivedFaceRef, RoleTable } from './shapeRefTypes.js';
+/**
+ * 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.
+ */
+export declare function createDerivedFaceRef(origin: string, op: 'fillet' | 'chamfer', edge: Edge, preShape: Shape3D, roles: RoleTable): DerivedFaceRef | undefined;
+/**
+ * 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.
+ */
+export declare function resolveDerivedFaceRef(ref: DerivedFaceRef, roles: RoleTable, shape: Shape3D): ResolvedDerivedFaceRef | BrokenDerivedFaceRef;

package/dist/topology/shapeRef/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * ShapeRef — stable, serializable face references for parametric replay.
  */
-export type { GeometricHint, ShapeRef, RoleTable, ResolvedRef, BrokenRef, EdgeHint, EdgeRef, ResolvedEdgeRef, BrokenEdgeRef, } from './shapeRefTypes.js';
+export type { GeometricHint, ShapeRef, RoleTable, ResolvedRef, BrokenRef, EdgeHint, EdgeRef, ResolvedEdgeRef, BrokenEdgeRef, VertexHint, VertexRef, ResolvedVertexRef, BrokenVertexRef, DerivedFaceHint, DerivedFaceRef, ResolvedDerivedFaceRef, BrokenDerivedFaceRef, } from './shapeRefTypes.js';
 export { type FaceScorer, defaultScorer } from './scoring.js';
 export { captureHint, assignRoles, createRef, updateRoles, resolveRef } from './shapeRefFns.js';
 export { createEdgeRef, resolveEdgeRef } from './edgeRefFns.js';
+export { createVertexRef, resolveVertexRef } from './vertexRefFns.js';
+export { createDerivedFaceRef, resolveDerivedFaceRef } from './derivedFaceRefFns.js';

package/dist/topology/shapeRef/roleLookup.d.ts

@@ -0,0 +1,11 @@
+import { Face, Shape3D, Vertex } from '../../core/shapeTypes.js';
+import { Vec3 } from '../../core/types.js';
+import { RoleTable } from './shapeRefTypes.js';
+/** Euclidean distance between two points. */
+export declare function distance(a: Vec3, b: Vec3): number;
+/** Mean of a set of vertices' positions (e.g. an edge's endpoints). */
+export declare function vertexCentroid(verts: readonly Vertex[]): Vec3 | undefined;
+/** The role whose tracked hashes include this face (reverse lookup). */
+export declare function roleOfFace(face: Face, origin: string, roles: RoleTable): string | undefined;
+/** Current faces a role resolves to — its tracked successors present in `shape`. */
+export declare function facesForRole(shape: Shape3D, origin: string, role: string, roles: RoleTable): Face[];

package/dist/topology/shapeRef/shapeRefTypes.d.ts

@@ -1,6 +1,6 @@
 import { Vec3 } from '../../core/types.js';
 import { SurfaceType } from '../faceFns.js';
-import { Face, Edge } from '../../core/shapeTypes.js';
+import { Face, Edge, Vertex } from '../../core/shapeTypes.js';
 /** Geometric snapshot of a face, used for fallback matching when hashes change. */
 export interface GeometricHint {
     readonly entityType: 'face';
@@ -76,3 +76,73 @@ export interface BrokenEdgeRef {
     readonly reason: 'ambiguous' | 'not-found';
     readonly candidates?: readonly Edge[];
 }
+/** Geometric snapshot of a vertex — a tiebreaker when several candidates survive. */
+export interface VertexHint {
+    readonly entityType: 'vertex';
+    readonly position?: Vec3 | undefined;
+}
+/**
+ * A stable reference to a vertex, identified by the roles of the faces meeting
+ * at it. A solid corner is where **≥3** faces meet at a point; two faces meet
+ * along an *edge* (two endpoints → ambiguous), so a vertex needs ≥3 face-roles.
+ * Resolves by finding the vertex common to those roles' current faces.
+ */
+export interface VertexRef {
+    readonly origin: string;
+    /** Roles of the ≥3 faces meeting at this vertex (sorted). */
+    readonly faceRoles: readonly string[];
+    readonly hint: VertexHint;
+}
+/** A successfully resolved vertex reference. */
+export interface ResolvedVertexRef {
+    readonly vertex: Vertex;
+    readonly confidence: 'exact' | 'geometric-fallback';
+}
+/** A vertex reference that could not be resolved. */
+export interface BrokenVertexRef {
+    readonly ref: VertexRef;
+    readonly reason: 'ambiguous' | 'not-found';
+    readonly candidates?: readonly Vertex[];
+}
+/**
+ * Snapshot for re-deriving a generated face. fillet/chamfer evolution is empty
+ * on the OCCT kernels, so the role table can't track the bridged faces — they
+ * are re-found by their captured outward normals; the edge midpoint breaks ties.
+ */
+export interface DerivedFaceHint {
+    readonly entityType: 'derived-face';
+    readonly normalA: Vec3;
+    readonly normalB: Vec3;
+    readonly edgeMidpoint?: Vec3 | undefined;
+}
+/**
+ * A reference to a *generated* face — a fillet round or chamfer bevel — named by
+ * the two faces it bridges. The generated face has no stable hash (it didn't
+ * exist at capture time, and fillet evolution is empty), so it's resolved as the
+ * face adjacent to both bridged faces whose normal blends both — the orthogonal
+ * flanking faces are rejected. Lineage-by-neighbors for geometry created by the
+ * very edit being referenced across.
+ */
+export interface DerivedFaceRef {
+    readonly origin: string;
+    /**
+     * Which op generated the face — descriptive metadata for consumers. Resolution
+     * is op-agnostic (the normal-blend isolates both a fillet round and a chamfer
+     * bevel), so the resolver doesn't consult it.
+     */
+    readonly op: 'fillet' | 'chamfer';
+    /** Roles of the two faces the generated face bridges. */
+    readonly betweenRoles: readonly [string, string];
+    readonly hint: DerivedFaceHint;
+}
+/** A successfully resolved derived-face reference (always geometric). */
+export interface ResolvedDerivedFaceRef {
+    readonly face: Face;
+    readonly confidence: 'geometric-fallback';
+}
+/** A derived-face reference that could not be resolved. */
+export interface BrokenDerivedFaceRef {
+    readonly ref: DerivedFaceRef;
+    readonly reason: 'ambiguous' | 'not-found';
+    readonly candidates?: readonly Face[];
+}

package/dist/topology/shapeRef/vertexRefFns.d.ts

@@ -0,0 +1,14 @@
+import { Shape3D, Vertex } from '../../core/shapeTypes.js';
+import { VertexRef, ResolvedVertexRef, BrokenVertexRef, RoleTable } from './shapeRefTypes.js';
+/**
+ * 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).
+ */
+export declare function createVertexRef(origin: string, vertex: Vertex, shape: Shape3D, roles: RoleTable): VertexRef | undefined;
+/**
+ * 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.
+ */
+export declare function resolveVertexRef(ref: VertexRef, roles: RoleTable, shape: Shape3D): ResolvedVertexRef | BrokenVertexRef;

package/dist/topology/topologyQueryFns.d.ts

@@ -20,6 +20,11 @@ export interface TopoCacheEntry {
         edge: KernelShape;
         face: KernelShape;
     }>>;
+    /** Vertex hash → vertex-face pairs — the vertex analogue of {@link edgeToFaces}. */
+    vertexToFaces?: Map<number, Array<{
+        vertex: KernelShape;
+        face: KernelShape;
+    }>>;
 }
 /** @internal Get or create a cache entry for a shape. Used by originTrackingFns. */
 export declare function getOrCreateCache(shape: AnyShape<Dimension>): TopoCacheEntry;

package/dist/topology.cjs

@@ -5,7 +5,7 @@ const require_shapeFns = require("./shapeFns-ybo0INGL.cjs");
 const require_curveFns = require("./curveFns-DgUJpH4z.cjs");
 const require_meshFns = require("./meshFns-1hQSn1p2.cjs");
 const require_solidBuilders = require("./solidBuilders-DiUv_mD0.cjs");
-const require_healingFns = require("./healingFns-C4UE1ZyM.cjs");
+const require_healingFns = require("./healingFns-x1sHV-HO.cjs");
 const require_primitiveFns = require("./primitiveFns-DLIWtQWA.cjs");
 exports.addHoles = require_primitiveFns.addHoles;
 exports.adjacentFaces = require_healingFns.adjacentFaces;

package/dist/topology.js

@@ -4,6 +4,6 @@ import { a as isSameShape, i as isEqualShape, n as getHashCode } from "./shapeFn
 import { a as curveIsPeriodic, c as curvePointAt, d as flipOrientation, f as getCurveType, h as offsetWire2D, i as curveIsClosed, l as curveStartPoint, m as interpolateCurve, n as curveAxis, o as curveLength, p as getOrientation, r as curveEndPoint, s as curvePeriod, t as approximateCurve, u as curveTangentAt } from "./curveFns-CcSn4-Rf.js";
 import { d as createMeshCache, n as exportSTEP, r as exportSTL, t as exportIGES, u as clearMeshCache } from "./meshFns-DbmidUzH.js";
 import { h as fuseAll, p as cutAll } from "./solidBuilders-C32wXQWG.js";
-import { A as edgesOfFace, B as toLineGeometryData, 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, S as intersectWithEvolution, T as cutAllBisect, _ as positionOnCurve, a as healFace, b as filletWithEvolution, g as variableFillet, j as facesOfEdge, k as adjacentFaces, l as solidFromShell, n as fixSelfIntersection, o as healSolid, r as fixShape, s as healWire, t as autoHeal, v as chamferWithEvolution, w as checkBoolean, x as fuseWithEvolution, y as cutWithEvolution } from "./healingFns-CPm_VFck.js";
+import { A as edgesOfFace, C as shellWithEvolution, D as getNurbsCurveData, E as fuseAllBisect, H as toLineGeometryData, I as wiresOfFace, L as chamferDistAngle, N as sharedEdges, O as getNurbsSurfaceData, P as verticesOfEdge, R as toBufferGeometryData, S as intersectWithEvolution, T as cutAllBisect, _ as positionOnCurve, a as healFace, b as filletWithEvolution, g as variableFillet, j as facesOfEdge, k as adjacentFaces, l as solidFromShell, n as fixSelfIntersection, o as healSolid, r as fixShape, s as healWire, t as autoHeal, v as chamferWithEvolution, w as checkBoolean, x as fuseWithEvolution, y as cutWithEvolution, z as toGroupedBufferGeometryData } from "./healingFns-D00TPE9p.js";
 import { C as threePointArc, D as wireLoop, E as wire, S as tangentArc, T as vertex, _ as polygon, a as circle, b as sphere, c as cylinder, d as ellipsoid, f as face, g as offsetFace, h as line, i as bsplineApprox, l as ellipse, m as helix, n as bezier, o as compound, p as filledFace, r as box, s as cone, t as addHoles, u as ellipseArc, v as sewShells, w as torus, x as subFace, y as solid } from "./primitiveFns-CBrOyk5S.js";
 export { addHoles, adjacentFaces, approximateCurve, asTopo, autoHeal, bezier, box, bsplineApprox, cast, chamferDistAngle as chamferDistAngleShape, chamferWithEvolution, checkBoolean, circle, classifyPointOnFace, clearMeshCache, compound, cone, createMeshCache, curveAxis, curveEndPoint, curveIsClosed, curveIsPeriodic, curveLength, curvePeriod, curvePointAt, curveStartPoint, curveTangentAt, cutAll, cutAllBisect, cutWithEvolution, cylinder, fromBREP as deserializeShape, downcast, edgesOfFace, ellipse, ellipseArc, ellipsoid, exportIGES, exportSTEP, exportSTL, face, faceAxis, faceCenter, faceGeomType, faceOrientation, facesOfEdge, filledFace, filletWithEvolution, fixSelfIntersection, fixShape, flipFaceOrientation, flipOrientation, fuseAll, fuseAllBisect, fuseWithEvolution, getBounds, getCurveType, getEdges, getFaces, getHashCode, getNurbsCurveData, getNurbsSurfaceData, getOrientation, getSurfaceType, getVertices, getWires, healFace, healSolid, healWire, helix, innerWires, interpolateCurve, intersectWithEvolution, invalidateShapeCache, isCompSolid, isEqualShape, isSameShape, iterEdges, iterFaces, iterTopo, iterVertices, iterWires, line, normalAt, offsetFace, offsetWire2D, outerWire, pointOnSurface, polygon, positionOnCurve, projectPointOnFace, sewShells, shapeType, sharedEdges, shellWithEvolution, solid, solidFromShell, sphere, subFace, tangentArc, threePointArc, toBufferGeometryData, toGroupedBufferGeometryData, toLineGeometryData, torus, uvBounds, uvCoordinates, variableFillet, vertex, vertexPosition, verticesOfEdge, wire, wireLoop, wiresOfFace };

package/package.json

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