@faicad/faijs 0.13.0

package/dist/vendored/brepjs/topology/shapeRef/shapeRefFns.js

@@ -0,0 +1,266 @@
+/**
+ * Core ShapeRef functions — capture hints, assign roles, create refs,
+ * update roles through evolution, and resolve refs back to faces.
+ */
+import { getKernel } from '../../kernel/index.js';
+import { castShapeWithKnownType, disposeTransientSubShape } from '../../core/shapeTypes.js';
+import { getFaces } from '../topologyQueryFns.js';
+import { getHashCode } from '../shapeFns.js';
+import { normalAt, faceCenter, faceGeomType } from '../faceFns.js';
+import { measureArea } from '../../measurement/measureFns.js';
+import { defaultScorer } from './scoring.js';
+// ---------------------------------------------------------------------------
+// captureHint — snapshot geometric properties of a face
+// ---------------------------------------------------------------------------
+/** Snapshot the geometric properties of a face for later matching. */
+export function captureHint(face) {
+    const surfaceType = faceGeomType(face);
+    const normal = normalAt(face);
+    const centroid = faceCenter(face);
+    const areaResult = measureArea(face);
+    const area = areaResult.ok ? areaResult.value : undefined;
+    return { entityType: 'face', surfaceType, normal, centroid, area };
+}
+// ---------------------------------------------------------------------------
+// assignRoles — auto-name faces based on operation type
+// ---------------------------------------------------------------------------
+/** Threshold for dominant-axis detection (abs(component) > 0.9). */
+const AXIS_THRESHOLD = 0.9;
+/** Determine the cardinal role name for a box face from its outward normal. */
+function boxRoleFromNormal(n) {
+    if (n[2] > AXIS_THRESHOLD)
+        return 'box:top';
+    if (n[2] < -AXIS_THRESHOLD)
+        return 'box:bottom';
+    if (n[1] > AXIS_THRESHOLD)
+        return 'box:back';
+    if (n[1] < -AXIS_THRESHOLD)
+        return 'box:front';
+    if (n[0] > AXIS_THRESHOLD)
+        return 'box:right';
+    if (n[0] < -AXIS_THRESHOLD)
+        return 'box:left';
+    return undefined;
+}
+/** Axial cap name for a Z-axis primitive: 'top' (+Z) / 'bottom' (-Z). */
+function axialCapName(prefix, face) {
+    if (faceGeomType(face) !== 'PLANE')
+        return undefined;
+    const z = normalAt(face)[2];
+    if (z > AXIS_THRESHOLD)
+        return `${prefix}:top`;
+    if (z < -AXIS_THRESHOLD)
+        return `${prefix}:bottom`;
+    return undefined;
+}
+/** 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' : undefined;
+}
+/** Per-primitive semantic face namers, keyed by operation type. */
+const 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).
+ */
+export function assignRoles(shape, operationType) {
+    const roles = new Map();
+    const assigner = ROLE_ASSIGNERS[operationType];
+    const kernel = getKernel();
+    let index = 0;
+    // Iterate transient faces rather than the cached getFaces(): only the hash
+    // and geometric role are read, so each face's arena slot is released here
+    // instead of being retained for the shape's whole lifetime.
+    for (const raw of kernel.iterShapes(shape.wrapped, 'face')) {
+        const face = castShapeWithKnownType(raw, 'face');
+        try {
+            const semantic = assigner?.(face);
+            const role = semantic !== undefined && !roles.has(semantic)
+                ? semantic
+                : `${operationType}:face_${index}`;
+            roles.set(role, [getHashCode(face)]);
+            index++;
+        }
+        finally {
+            disposeTransientSubShape(face, raw);
+        }
+    }
+    return roles;
+}
+// ---------------------------------------------------------------------------
+// createRef — factory for ShapeRef
+// ---------------------------------------------------------------------------
+/** Create a ShapeRef from an origin ID, role name, and face. */
+export function createRef(origin, role, face) {
+    return { origin, role, hint: captureHint(face) };
+}
+// ---------------------------------------------------------------------------
+// updateRoles — immutable role table update through evolution
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+export function updateRoles(roles, origin, evolution) {
+    const originRoles = roles.get(origin);
+    if (!originRoles)
+        return roles;
+    const updatedOriginRoles = new Map();
+    // Carry each role's faces forward through deleted/modified/unchanged.
+    for (const [role, hashes] of originRoles) {
+        const successors = nextHashes(hashes, evolution);
+        if (successors.length > 0)
+            updatedOriginRoles.set(role, successors);
+    }
+    // Build new RoleTable immutably
+    const newRoles = new Map();
+    for (const [key, value] of roles) {
+        newRoles.set(key, key === origin ? updatedOriginRoles : value);
+    }
+    return newRoles;
+}
+// ---------------------------------------------------------------------------
+// resolveRef — resolve a ShapeRef back to a face
+// ---------------------------------------------------------------------------
+/** Ambiguity threshold: if two scores are within this range, it's ambiguous. */
+const AMBIGUITY_THRESHOLD = 0.1;
+/** Minimum score for geometric fallback to accept a match. */
+const MIN_SCORE = 0.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 !== undefined && bestScore > MIN_SCORE) {
+        if (bestScore - secondBestScore < AMBIGUITY_THRESHOLD && scored.length > 1) {
+            const competitive = scored
+                .filter(([, s]) => s >= bestScore - AMBIGUITY_THRESHOLD)
+                .map(([f]) => f);
+            return { kind: 'ambiguous', candidates: competitive };
+        }
+        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.
+ */
+export function resolveRef(ref, roles, currentShape, scorer) {
+    const faces = getFaces(currentShape);
+    const scoreFn = scorer ?? defaultScorer;
+    // 1. Exact lookup, scoped to the role's tracked successor hashes.
+    const targetHashes = roles.get(ref.origin)?.get(ref.role);
+    if (targetHashes !== undefined && targetHashes.length > 0) {
+        const survivors = faces.filter((f) => targetHashes.includes(getHashCode(f)));
+        if (survivors.length === 1) {
+            const [only] = survivors;
+            if (only !== undefined)
+                return { face: only, confidence: 'exact' };
+        }
+        else if (survivors.length === 0) {
+            return { ref, reason: 'deleted' };
+        }
+        else {
+            // A face that split — pick the right fragment from the tracked set only.
+            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 };
+            }
+            // 'none' → fall through to the whole-shape geometric fallback.
+        }
+    }
+    // 2. Geometric fallback over all faces.
+    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' };
+}
+//# sourceMappingURL=shapeRefFns.js.map

package/dist/vendored/brepjs/topology/shapeRef/shapeRefFns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeRefFns.js","sourceRoot":"","sources":["../../../../../src/vendored/brepjs/topology/shapeRef/shapeRefFns.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Core ShapeRef functions — capture hints, assign roles, create refs,\n * update roles through evolution, and resolve refs back to faces.\n */\n\nimport type { Face, Shape3D } from '../../core/shapeTypes.js';\nimport type { ShapeEvolution } from '../../kernel/types.js';\nimport { getKernel } from '../../kernel/index.js';\nimport { castShapeWithKnownType, disposeTransientSubShape } from '../../core/shapeTypes.js';\nimport { getFaces } from '../topologyQueryFns.js';\nimport { getHashCode } from '../shapeFns.js';\nimport { normalAt, faceCenter, faceGeomType } from '../faceFns.js';\nimport { measureArea } from '../../measurement/measureFns.js';\nimport type {\n  GeometricHint,\n  ShapeRef,\n  RoleTable,\n  ResolvedRef,\n  BrokenRef,\n} from './shapeRefTypes.js';\nimport { type FaceScorer, defaultScorer } from './scoring.js';\n\n// ---------------------------------------------------------------------------\n// captureHint — snapshot geometric properties of a face\n// ---------------------------------------------------------------------------\n\n/** Snapshot the geometric properties of a face for later matching. */\nexport function captureHint(face: Face): GeometricHint {\n  const surfaceType = faceGeomType(face);\n  const normal = normalAt(face);\n  const centroid = faceCenter(face);\n\n  const areaResult = measureArea(face);\n  const area = areaResult.ok ? areaResult.value : undefined;\n\n  return { entityType: 'face', surfaceType, normal, centroid, area };\n}\n\n// ---------------------------------------------------------------------------\n// assignRoles — auto-name faces based on operation type\n// ---------------------------------------------------------------------------\n\n/** Threshold for dominant-axis detection (abs(component) > 0.9). */\nconst AXIS_THRESHOLD = 0.9;\n\n/** Determine the cardinal role name for a box face from its outward normal. */\nfunction boxRoleFromNormal(n: readonly [number, number, number]): string | undefined {\n  if (n[2] > AXIS_THRESHOLD) return 'box:top';\n  if (n[2] < -AXIS_THRESHOLD) return 'box:bottom';\n  if (n[1] > AXIS_THRESHOLD) return 'box:back';\n  if (n[1] < -AXIS_THRESHOLD) return 'box:front';\n  if (n[0] > AXIS_THRESHOLD) return 'box:right';\n  if (n[0] < -AXIS_THRESHOLD) return 'box:left';\n  return undefined;\n}\n\n/** Axial cap name for a Z-axis primitive: 'top' (+Z) / 'bottom' (-Z). */\nfunction axialCapName(prefix: string, face: Face): string | undefined {\n  if (faceGeomType(face) !== 'PLANE') return undefined;\n  const z = normalAt(face)[2];\n  if (z > AXIS_THRESHOLD) return `${prefix}:top`;\n  if (z < -AXIS_THRESHOLD) return `${prefix}:bottom`;\n  return undefined;\n}\n\n/** Semantic role for a Z-axis cylinder face: top/bottom caps + lateral wall. */\nfunction cylinderRole(face: Face): string | undefined {\n  return faceGeomType(face) === 'CYLINDRE' ? 'cylinder:lateral' : axialCapName('cylinder', face);\n}\n\n/** Semantic role for a Z-axis cone/frustum face: top/bottom caps + lateral. */\nfunction coneRole(face: Face): string | undefined {\n  return faceGeomType(face) === 'CONE' ? 'cone:lateral' : axialCapName('cone', face);\n}\n\n/** Semantic role for a sphere's single spherical face. */\nfunction sphereRole(face: Face): string | undefined {\n  return faceGeomType(face) === 'SPHERE' ? 'sphere:surface' : undefined;\n}\n\n/** Per-primitive semantic face namers, keyed by operation type. */\nconst ROLE_ASSIGNERS: Record<string, (face: Face) => string | undefined> = {\n  box: (face) => boxRoleFromNormal(normalAt(face)),\n  cylinder: cylinderRole,\n  cone: coneRole,\n  sphere: sphereRole,\n};\n\n/**\n * Auto-assign role names to a shape's faces from its operation type.\n *\n * Known primitives get **semantic** names from face geometry — rebuild-stable\n * across parameter edits that preserve orientation:\n * - `box`: cardinal names by normal ('box:top'/'bottom'/'front'/'back'/'left'/'right').\n * - `cylinder`/`cone` (Z-axis): 'top'/'bottom' caps + 'lateral' wall.\n * - `sphere`: 'sphere:surface'.\n *\n * Faces a primitive namer doesn't recognize (a rotated box's non-cardinal faces),\n * and every face of any other operation type, fall back to positional names\n * ('opType:face_0', 'opType:face_1', ...) — so each face always gets a role.\n *\n * @returns Map from role name to its face hash codes (one at assignment time;\n *   a role accrues more hashes only later, when `updateRoles` tracks a split).\n */\nexport function assignRoles(shape: Shape3D, operationType: string): Map<string, number[]> {\n  const roles = new Map<string, number[]>();\n  const assigner = ROLE_ASSIGNERS[operationType];\n  const kernel = getKernel();\n  let index = 0;\n  // Iterate transient faces rather than the cached getFaces(): only the hash\n  // and geometric role are read, so each face's arena slot is released here\n  // instead of being retained for the shape's whole lifetime.\n  for (const raw of kernel.iterShapes(shape.wrapped, 'face')) {\n    const face = castShapeWithKnownType(raw, 'face') as Face;\n    try {\n      const semantic = assigner?.(face);\n      const role =\n        semantic !== undefined && !roles.has(semantic)\n          ? semantic\n          : `${operationType}:face_${index}`;\n      roles.set(role, [getHashCode(face)]);\n      index++;\n    } finally {\n      disposeTransientSubShape(face, raw);\n    }\n  }\n  return roles;\n}\n\n// ---------------------------------------------------------------------------\n// createRef — factory for ShapeRef\n// ---------------------------------------------------------------------------\n\n/** Create a ShapeRef from an origin ID, role name, and face. */\nexport function createRef(origin: string, role: string, face: Face): ShapeRef {\n  return { origin, role, hint: captureHint(face) };\n}\n\n// ---------------------------------------------------------------------------\n// updateRoles — immutable role table update through evolution\n// ---------------------------------------------------------------------------\n\n/**\n * Advance a role's face hashes through one evolution: drop deleted faces,\n * replace a modified face with *all* its successors (a 1→many split keeps every\n * fragment), and keep unchanged faces. Deduped so a shared successor isn't\n * doubled.\n */\nfunction nextHashes(hashes: readonly number[], evolution: ShapeEvolution): number[] {\n  const successors: number[] = [];\n  for (const hash of hashes) {\n    if (evolution.deleted.has(hash)) continue;\n    const modified = evolution.modified.get(hash);\n    const targets = modified && modified.length > 0 ? modified : [hash];\n    for (const h of targets) if (!successors.includes(h)) successors.push(h);\n  }\n  return successors;\n}\n\n/**\n * Propagate a role table through a ShapeEvolution record.\n * Returns a new RoleTable with hashes updated according to the evolution.\n *\n * - Deleted faces: hash dropped (role removed once all its hashes are gone).\n * - Modified faces: hash replaced by **all** successor hashes — so a 1→many\n *   split keeps every fragment, and `resolveRef` disambiguates among them.\n * - Unchanged faces: hash preserved.\n *\n * Note: `evolution.generated` is intentionally not consumed here — on the OCCT\n * kernels its hashes refer to an intermediate shape, not the final result, so\n * naming generated faces produces roles that never resolve (verified: 0 live\n * generated hashes across cut/fuse on occt-wasm). Stable names for generated\n * geometry (fillet rounds, boolean seams) need history-fidelity work tracked\n * separately.\n */\nexport function updateRoles(\n  roles: RoleTable,\n  origin: string,\n  evolution: ShapeEvolution\n): RoleTable {\n  const originRoles = roles.get(origin);\n  if (!originRoles) return roles;\n\n  const updatedOriginRoles = new Map<string, number[]>();\n\n  // Carry each role's faces forward through deleted/modified/unchanged.\n  for (const [role, hashes] of originRoles) {\n    const successors = nextHashes(hashes, evolution);\n    if (successors.length > 0) updatedOriginRoles.set(role, successors);\n  }\n\n  // Build new RoleTable immutably\n  const newRoles = new Map<string, ReadonlyMap<string, readonly number[]>>();\n  for (const [key, value] of roles) {\n    newRoles.set(key, key === origin ? updatedOriginRoles : value);\n  }\n  return newRoles;\n}\n\n// ---------------------------------------------------------------------------\n// resolveRef — resolve a ShapeRef back to a face\n// ---------------------------------------------------------------------------\n\n/** Ambiguity threshold: if two scores are within this range, it's ambiguous. */\nconst AMBIGUITY_THRESHOLD = 0.1;\n/** Minimum score for geometric fallback to accept a match. */\nconst MIN_SCORE = 0.5;\n\n/** Outcome of scoring a candidate face set against a hint. */\ntype ScoreOutcome =\n  { kind: 'match'; face: Face } | { kind: 'ambiguous'; candidates: Face[] } | { kind: 'none' };\n\n/**\n * Score `candidates` against `hint`, returning the best match, a tie within\n * {@link AMBIGUITY_THRESHOLD}, or nothing above {@link MIN_SCORE}. Scoping the\n * candidates to a role's tracked successors (rather than every face) is what\n * makes split-face disambiguation reliable — the fragments compete only with\n * each other, not with unrelated geometry.\n */\nfunction scoreFaces(\n  hint: GeometricHint,\n  candidates: readonly Face[],\n  scoreFn: FaceScorer\n): ScoreOutcome {\n  let bestScore = -Infinity;\n  let bestFace: Face | undefined;\n  let secondBestScore = -Infinity;\n  const scored: Array<[Face, number]> = [];\n\n  for (const face of candidates) {\n    const score = scoreFn(hint, face);\n    if (score > MIN_SCORE) scored.push([face, score]);\n    if (score > bestScore) {\n      secondBestScore = bestScore;\n      bestScore = score;\n      bestFace = face;\n    } else if (score > secondBestScore) {\n      secondBestScore = score;\n    }\n  }\n\n  if (bestFace !== undefined && bestScore > MIN_SCORE) {\n    if (bestScore - secondBestScore < AMBIGUITY_THRESHOLD && scored.length > 1) {\n      const competitive = scored\n        .filter(([, s]) => s >= bestScore - AMBIGUITY_THRESHOLD)\n        .map(([f]) => f);\n      return { kind: 'ambiguous', candidates: competitive };\n    }\n    return { kind: 'match', face: bestFace };\n  }\n  return { kind: 'none' };\n}\n\n/**\n * Resolve a ShapeRef to a face in the current shape.\n *\n * Resolution strategy:\n * 1. Exact: the role's tracked successor hashes. One survivor → exact match;\n *    several survivors (a face that split) → disambiguate among *only those*\n *    fragments; none survive → deleted.\n * 2. Geometric fallback over the whole shape when the role isn't tracked (or a\n *    scoped score turned up nothing): best-scoring face, else ambiguous /\n *    not-found.\n */\nexport function resolveRef(\n  ref: ShapeRef,\n  roles: RoleTable,\n  currentShape: Shape3D,\n  scorer?: FaceScorer\n): ResolvedRef | BrokenRef {\n  const faces = getFaces(currentShape);\n  const scoreFn = scorer ?? defaultScorer;\n\n  // 1. Exact lookup, scoped to the role's tracked successor hashes.\n  const targetHashes = roles.get(ref.origin)?.get(ref.role);\n  if (targetHashes !== undefined && targetHashes.length > 0) {\n    const survivors = faces.filter((f) => targetHashes.includes(getHashCode(f)));\n    if (survivors.length === 1) {\n      const [only] = survivors;\n      if (only !== undefined) return { face: only, confidence: 'exact' };\n    } else if (survivors.length === 0) {\n      return { ref, reason: 'deleted' };\n    } else {\n      // A face that split — pick the right fragment from the tracked set only.\n      const outcome = scoreFaces(ref.hint, survivors, scoreFn);\n      if (outcome.kind === 'match') return { face: outcome.face, confidence: 'geometric-fallback' };\n      if (outcome.kind === 'ambiguous') {\n        return { ref, reason: 'ambiguous', candidates: outcome.candidates };\n      }\n      // 'none' → fall through to the whole-shape geometric fallback.\n    }\n  }\n\n  // 2. Geometric fallback over all faces.\n  const outcome = scoreFaces(ref.hint, faces, scoreFn);\n  if (outcome.kind === 'match') return { face: outcome.face, confidence: 'geometric-fallback' };\n  if (outcome.kind === 'ambiguous')\n    return { ref, reason: 'ambiguous', candidates: outcome.candidates };\n  return { ref, reason: 'not-found' };\n}\n"]}

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

@@ -0,0 +1,153 @@
+/**
+ * Type definitions for the ShapeRef system — stable, serializable face references
+ * that survive parametric replay.
+ */
+import type { Vec3 } from '../../core/types.js';
+import type { SurfaceType } from '../faceFns.js';
+import type { 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';
+    readonly surfaceType?: SurfaceType;
+    readonly normal?: Vec3;
+    readonly centroid?: Vec3;
+    readonly area?: number | undefined;
+}
+/**
+ * A stable reference to a face, combining a role-based name with a geometric hint.
+ * Survives parametric replay even when face hashes change.
+ */
+export interface ShapeRef {
+    /** Generic command/step identifier (e.g., 'step_0', 'box_1'). */
+    readonly origin: string;
+    /** Role name within the origin (e.g., 'box:top', 'fillet:round_0'). */
+    readonly role: string;
+    /** Geometric snapshot for fallback matching. */
+    readonly hint: GeometricHint;
+}
+/**
+ * Immutable table mapping `origin -> role -> faceHashes`.
+ * Updated through evolution records when the model is rebuilt.
+ *
+ * A role usually maps to a single hash, but maps to several after its face
+ * splits (a 1→many `modified` evolution); resolution then disambiguates among
+ * the surviving successors rather than competing against the whole shape.
+ */
+export type RoleTable = ReadonlyMap<string, ReadonlyMap<string, readonly number[]>>;
+/** A successfully resolved face reference. */
+export interface ResolvedRef {
+    readonly face: Face;
+    readonly confidence: 'exact' | 'geometric-fallback';
+}
+/** A face reference that could not be resolved. */
+export interface BrokenRef {
+    readonly ref: ShapeRef;
+    readonly reason: 'deleted' | 'ambiguous' | 'not-found';
+    readonly candidates?: readonly Face[];
+}
+/**
+ * Geometric snapshot of an edge — a tiebreaker for the rare case where an edge's
+ * two faces share more than one edge.
+ */
+export interface EdgeHint {
+    readonly entityType: 'edge';
+    readonly length?: number | undefined;
+    /** Midpoint of the edge's endpoint vertices. */
+    readonly midpoint?: Vec3 | undefined;
+}
+/**
+ * A stable reference to an edge, identified by the roles of its two adjacent
+ * faces — its lineage. An edge *is* the intersection of its two faces, so this
+ * resolves by finding the edge shared by the current faces of those roles
+ * (`sharedEdges`). Identity rides on the already-stable face roles rather than
+ * the edge's own hash, so it survives edits that re-hash the edge — and it
+ * sidesteps the kernel's unreliable `generated`-face hashes entirely.
+ */
+export interface EdgeRef {
+    readonly origin: string;
+    /** Roles of the two faces this edge bounds. */
+    readonly faceRoles: readonly [string, string];
+    readonly hint: EdgeHint;
+}
+/** A successfully resolved edge reference. */
+export interface ResolvedEdgeRef {
+    readonly edge: Edge;
+    readonly confidence: 'exact' | 'geometric-fallback';
+}
+/** An edge reference that could not be resolved. */
+export interface BrokenEdgeRef {
+    readonly ref: EdgeRef;
+    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[];
+}
+//# sourceMappingURL=shapeRefTypes.d.ts.map

package/dist/vendored/brepjs/topology/shapeRef/shapeRefTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeRefTypes.d.ts","sourceRoot":"","sources":["../../../../../src/vendored/brepjs/topology/shapeRef/shapeRefTypes.ts"],"names":[],"mappings":"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"}

package/dist/vendored/brepjs/topology/shapeRef/shapeRefTypes.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for the ShapeRef system — stable, serializable face references
+ * that survive parametric replay.
+ */
+export {};
+//# sourceMappingURL=shapeRefTypes.js.map

package/dist/vendored/brepjs/topology/shapeRef/shapeRefTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeRefTypes.js","sourceRoot":"","sources":["../../../../../src/vendored/brepjs/topology/shapeRef/shapeRefTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/**\n * Type definitions for the ShapeRef system — stable, serializable face references\n * that survive parametric replay.\n */\n\nimport type { Vec3 } from '../../core/types.js';\nimport type { SurfaceType } from '../faceFns.js';\nimport type { Face, Edge, Vertex } from '../../core/shapeTypes.js';\n\n// ---------------------------------------------------------------------------\n// Geometric hint — snapshot of a face's geometric properties\n// ---------------------------------------------------------------------------\n\n/** Geometric snapshot of a face, used for fallback matching when hashes change. */\nexport interface GeometricHint {\n  readonly entityType: 'face';\n  readonly surfaceType?: SurfaceType;\n  readonly normal?: Vec3;\n  readonly centroid?: Vec3;\n  readonly area?: number | undefined;\n}\n\n// ---------------------------------------------------------------------------\n// ShapeRef — stable, serializable face reference\n// ---------------------------------------------------------------------------\n\n/**\n * A stable reference to a face, combining a role-based name with a geometric hint.\n * Survives parametric replay even when face hashes change.\n */\nexport interface ShapeRef {\n  /** Generic command/step identifier (e.g., 'step_0', 'box_1'). */\n  readonly origin: string;\n  /** Role name within the origin (e.g., 'box:top', 'fillet:round_0'). */\n  readonly role: string;\n  /** Geometric snapshot for fallback matching. */\n  readonly hint: GeometricHint;\n}\n\n// ---------------------------------------------------------------------------\n// Role table — maps origin -> role -> face hash\n// ---------------------------------------------------------------------------\n\n/**\n * Immutable table mapping `origin -> role -> faceHashes`.\n * Updated through evolution records when the model is rebuilt.\n *\n * A role usually maps to a single hash, but maps to several after its face\n * splits (a 1→many `modified` evolution); resolution then disambiguates among\n * the surviving successors rather than competing against the whole shape.\n */\nexport type RoleTable = ReadonlyMap<string, ReadonlyMap<string, readonly number[]>>;\n\n// ---------------------------------------------------------------------------\n// Resolution results\n// ---------------------------------------------------------------------------\n\n/** A successfully resolved face reference. */\nexport interface ResolvedRef {\n  readonly face: Face;\n  readonly confidence: 'exact' | 'geometric-fallback';\n}\n\n/** A face reference that could not be resolved. */\nexport interface BrokenRef {\n  readonly ref: ShapeRef;\n  readonly reason: 'deleted' | 'ambiguous' | 'not-found';\n  readonly candidates?: readonly Face[];\n}\n\n// ---------------------------------------------------------------------------\n// EdgeRef — lineage-based edge reference (named by its two adjacent faces)\n// ---------------------------------------------------------------------------\n\n/**\n * Geometric snapshot of an edge — a tiebreaker for the rare case where an edge's\n * two faces share more than one edge.\n */\nexport interface EdgeHint {\n  readonly entityType: 'edge';\n  readonly length?: number | undefined;\n  /** Midpoint of the edge's endpoint vertices. */\n  readonly midpoint?: Vec3 | undefined;\n}\n\n/**\n * A stable reference to an edge, identified by the roles of its two adjacent\n * faces — its lineage. An edge *is* the intersection of its two faces, so this\n * resolves by finding the edge shared by the current faces of those roles\n * (`sharedEdges`). Identity rides on the already-stable face roles rather than\n * the edge's own hash, so it survives edits that re-hash the edge — and it\n * sidesteps the kernel's unreliable `generated`-face hashes entirely.\n */\nexport interface EdgeRef {\n  readonly origin: string;\n  /** Roles of the two faces this edge bounds. */\n  readonly faceRoles: readonly [string, string];\n  readonly hint: EdgeHint;\n}\n\n/** A successfully resolved edge reference. */\nexport interface ResolvedEdgeRef {\n  readonly edge: Edge;\n  readonly confidence: 'exact' | 'geometric-fallback';\n}\n\n/** An edge reference that could not be resolved. */\nexport interface BrokenEdgeRef {\n  readonly ref: EdgeRef;\n  // No 'deleted': an edge ref tracks its faces, not the edge's own hash, so a\n  // vanished edge surfaces as 'not-found' (no shared edge) — it can't be\n  // distinguished from never-resolved.\n  readonly reason: 'ambiguous' | 'not-found';\n  readonly candidates?: readonly Edge[];\n}\n\n// ---------------------------------------------------------------------------\n// VertexRef — lineage-based vertex reference (named by its ≥3 adjacent faces)\n// ---------------------------------------------------------------------------\n\n/** Geometric snapshot of a vertex — a tiebreaker when several candidates survive. */\nexport interface VertexHint {\n  readonly entityType: 'vertex';\n  readonly position?: Vec3 | undefined;\n}\n\n/**\n * A stable reference to a vertex, identified by the roles of the faces meeting\n * at it. A solid corner is where **≥3** faces meet at a point; two faces meet\n * along an *edge* (two endpoints → ambiguous), so a vertex needs ≥3 face-roles.\n * Resolves by finding the vertex common to those roles' current faces.\n */\nexport interface VertexRef {\n  readonly origin: string;\n  /** Roles of the ≥3 faces meeting at this vertex (sorted). */\n  readonly faceRoles: readonly string[];\n  readonly hint: VertexHint;\n}\n\n/** A successfully resolved vertex reference. */\nexport interface ResolvedVertexRef {\n  readonly vertex: Vertex;\n  readonly confidence: 'exact' | 'geometric-fallback';\n}\n\n/** A vertex reference that could not be resolved. */\nexport interface BrokenVertexRef {\n  readonly ref: VertexRef;\n  readonly reason: 'ambiguous' | 'not-found';\n  readonly candidates?: readonly Vertex[];\n}\n\n// ---------------------------------------------------------------------------\n// DerivedFaceRef — a generated face (fillet/chamfer) named by the faces it bridges\n// ---------------------------------------------------------------------------\n\n/**\n * Snapshot for re-deriving a generated face. fillet/chamfer evolution is empty\n * on the OCCT kernels, so the role table can't track the bridged faces — they\n * are re-found by their captured outward normals; the edge midpoint breaks ties.\n */\nexport interface DerivedFaceHint {\n  readonly entityType: 'derived-face';\n  readonly normalA: Vec3;\n  readonly normalB: Vec3;\n  readonly edgeMidpoint?: Vec3 | undefined;\n}\n\n/**\n * A reference to a *generated* face — a fillet round or chamfer bevel — named by\n * the two faces it bridges. The generated face has no stable hash (it didn't\n * exist at capture time, and fillet evolution is empty), so it's resolved as the\n * face adjacent to both bridged faces whose normal blends both — the orthogonal\n * flanking faces are rejected. Lineage-by-neighbors for geometry created by the\n * very edit being referenced across.\n */\nexport interface DerivedFaceRef {\n  readonly origin: string;\n  /**\n   * Which op generated the face — descriptive metadata for consumers. Resolution\n   * is op-agnostic (the normal-blend isolates both a fillet round and a chamfer\n   * bevel), so the resolver doesn't consult it.\n   */\n  readonly op: 'fillet' | 'chamfer';\n  /** Roles of the two faces the generated face bridges. */\n  readonly betweenRoles: readonly [string, string];\n  readonly hint: DerivedFaceHint;\n}\n\n/** A successfully resolved derived-face reference (always geometric). */\nexport interface ResolvedDerivedFaceRef {\n  readonly face: Face;\n  readonly confidence: 'geometric-fallback';\n}\n\n/** A derived-face reference that could not be resolved. */\nexport interface BrokenDerivedFaceRef {\n  readonly ref: DerivedFaceRef;\n  readonly reason: 'ambiguous' | 'not-found';\n  readonly candidates?: readonly Face[];\n}\n"]}

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

@@ -0,0 +1,24 @@
+/**
+ * Lineage-based vertex references. A solid corner is where ≥3 faces meet at a
+ * point, so a vertex's stable identity is the SET of its adjacent face-roles
+ * (two faces meet along an edge with two endpoints → ambiguous; three pin a
+ * point). Capture snapshots those roles (`facesOfVertex` + reverse lookup);
+ * resolution finds the vertex common to the current faces of those roles
+ * (`verticesOfFace` intersection). Rides the split-aware role table, and — like
+ * edges — never touches the kernel's unreliable `generated` hashes.
+ */
+import type { Shape3D, Vertex } from '../../core/shapeTypes.js';
+import type { 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;
+//# sourceMappingURL=vertexRefFns.d.ts.map

package/dist/vendored/brepjs/topology/shapeRef/vertexRefFns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertexRefFns.d.ts","sourceRoot":"","sources":["../../../../../src/vendored/brepjs/topology/shapeRef/vertexRefFns.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAQ,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAKtE,OAAO,KAAK,EAEV,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,SAAS,EACV,MAAM,oBAAoB,CAAC;AA+D5B;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,GACf,SAAS,GAAG,SAAS,CAcvB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,OAAO,GACb,iBAAiB,GAAG,eAAe,CAmBrC"}

package/dist/vendored/brepjs/topology/shapeRef/vertexRefFns.js

@@ -0,0 +1,128 @@
+/**
+ * Lineage-based vertex references. A solid corner is where ≥3 faces meet at a
+ * point, so a vertex's stable identity is the SET of its adjacent face-roles
+ * (two faces meet along an edge with two endpoints → ambiguous; three pin a
+ * point). Capture snapshots those roles (`facesOfVertex` + reverse lookup);
+ * resolution finds the vertex common to the current faces of those roles
+ * (`verticesOfFace` intersection). Rides the split-aware role table, and — like
+ * edges — never touches the kernel's unreliable `generated` hashes.
+ */
+import { vertexPosition } from '../topologyQueryFns.js';
+import { getHashCode } from '../shapeFns.js';
+import { facesOfVertex, verticesOfFace } from '../adjacencyFns.js';
+import { distance, facesForRole, roleOfFace } from './roleLookup.js';
+/** A corner needs at least this many faces to pin a unique point. */
+const MIN_VERTEX_FACES = 3;
+/** Hint distances closer than this are indistinguishable (→ ambiguous). */
+const HINT_MARGIN = 1e-6;
+/** Hashes of all vertices across `faces`, recording one handle per hash. */
+function vertexHashes(faces, handles) {
+    const hashes = 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 = 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 = new Map();
+    let common;
+    for (const faces of faceSets) {
+        const hashes = vertexHashes(faces, handles);
+        common = common === undefined ? hashes : intersect(common, hashes);
+    }
+    if (common === undefined)
+        return [];
+    const result = [];
+    for (const h of common) {
+        const v = handles.get(h);
+        if (v !== undefined)
+            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 === undefined)
+        return undefined;
+    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 === undefined || secondDist - bestDist < HINT_MARGIN)
+        return undefined;
+    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).
+ */
+export function createVertexRef(origin, vertex, shape, roles) {
+    const faces = facesOfVertex(shape, vertex);
+    if (faces.length < MIN_VERTEX_FACES)
+        return undefined;
+    const roleSet = new Set();
+    for (const f of faces) {
+        const role = roleOfFace(f, origin, roles);
+        if (role !== undefined)
+            roleSet.add(role);
+    }
+    if (roleSet.size < MIN_VERTEX_FACES)
+        return undefined;
+    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.
+ */
+export 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 !== undefined)
+            return { vertex: only, confidence: 'exact' };
+    }
+    if (common.length > 1) {
+        const best = nearestToHint(common, ref.hint);
+        if (best !== undefined)
+            return { vertex: best, confidence: 'geometric-fallback' };
+        return { ref, reason: 'ambiguous', candidates: common };
+    }
+    return { ref, reason: 'not-found' };
+}
+//# sourceMappingURL=vertexRefFns.js.map