fluidcad 0.0.26 → 0.0.28

package/lib/dist/oc/color-transfer.js

@@ -0,0 +1,135 @@
+import { getOC } from "./init.js";
+import { Explorer } from "./explorer.js";
+import { ShapeOps } from "./shape-ops.js";
+import { Face } from "../common/face.js";
+/**
+ * Walk each source shape's `colorMap`, find where each colored face ended up in
+ * the result shapes via `maker.Modified()` (falling back to the unchanged face
+ * if `!IsDeleted`), and apply the color to whichever result shape now owns it.
+ *
+ * Works for any `BRepBuilderAPI_MakeShape`-derived maker — fuse, cut, fillet,
+ * chamfer, transform, etc.
+ */
+export class ColorTransfer {
+    static applyThroughMaker(sources, results, maker) {
+        const oc = getOC();
+        const FACE = oc.TopAbs_ShapeEnum.TopAbs_FACE;
+        for (const source of sources) {
+            if (!source.hasColors()) {
+                continue;
+            }
+            for (const entry of source.colorMap) {
+                const modifiedRaws = ShapeOps.shapeListToArray(maker.Modified(entry.shape))
+                    .filter(s => s.ShapeType() === FACE);
+                let targets;
+                if (modifiedRaws.length > 0) {
+                    targets = modifiedRaws;
+                }
+                else if (!maker.IsDeleted(entry.shape)) {
+                    targets = [entry.shape];
+                }
+                else {
+                    continue;
+                }
+                for (const target of targets) {
+                    for (const result of results) {
+                        const faces = Explorer.findShapes(result.getShape(), FACE);
+                        if (faces.some(f => f.IsSame(target))) {
+                            result.setColor(target, entry.color);
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Color bleed pass: spreads colors to result faces that came from new
+     * geometry (tool inputs, generated faces, or just brand-new) by walking
+     * face-edge adjacency in each result solid.
+     *
+     * Faces that came from `sceneSources` (whether modified or unchanged) are
+     * NOT bled — those represent existing geometry whose color state the user
+     * explicitly chose. Faces NOT from any sceneSource are eligible: this
+     * covers tool extrusions, fillet/chamfer-generated surfaces, and cut
+     * section faces.
+     *
+     * Iterates until stable so newly-bled faces can spread color further.
+     * Call AFTER `applyThroughMaker` so the colored seeds are in place.
+     */
+    static applyBleeding(sceneSources, results, maker) {
+        const oc = getOC();
+        const FACE = oc.TopAbs_ShapeEnum.TopAbs_FACE;
+        const EDGE = oc.TopAbs_ShapeEnum.TopAbs_EDGE;
+        const protectedFaces = new oc.TopTools_MapOfShape();
+        for (const scene of sceneSources) {
+            for (const inputFace of Explorer.findShapes(scene.getShape(), FACE)) {
+                const modified = ShapeOps.shapeListToArray(maker.Modified(inputFace))
+                    .filter(s => s.ShapeType() === FACE);
+                if (modified.length > 0) {
+                    for (const r of modified) {
+                        protectedFaces.Add(r);
+                    }
+                }
+                else if (!maker.IsDeleted(inputFace)) {
+                    protectedFaces.Add(inputFace);
+                }
+            }
+        }
+        for (const result of results) {
+            const allFaces = Explorer.findShapes(result.getShape(), FACE);
+            // Cache edges per face — repeated `findShapes` is expensive.
+            const faceEdges = allFaces.map(f => Explorer.findShapes(f, EDGE));
+            let changed = true;
+            while (changed) {
+                changed = false;
+                for (let i = 0; i < allFaces.length; i++) {
+                    const face = allFaces[i];
+                    if (protectedFaces.Contains(face)) {
+                        continue;
+                    }
+                    if (result.getColor(face)) {
+                        continue;
+                    }
+                    const myEdges = faceEdges[i];
+                    for (let j = 0; j < allFaces.length; j++) {
+                        if (i === j) {
+                            continue;
+                        }
+                        const otherEdges = faceEdges[j];
+                        const adjacent = myEdges.some(me => otherEdges.some(oe => me.IsSame(oe)));
+                        if (!adjacent) {
+                            continue;
+                        }
+                        const otherColor = result.getColor(allFaces[j]);
+                        if (otherColor) {
+                            result.setColor(face, otherColor);
+                            changed = true;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        protectedFaces.delete();
+    }
+    /**
+     * Transfer colors from a pre-clean source shape through a `cleanShapeWithLineage`
+     * cleanup's `BRepTools_History` onto the post-clean result. Use this when an
+     * op is chained as `maker → cleanShape` — first apply `applyThroughMaker` to
+     * move colors from the original source onto the pre-clean result, then call
+     * this to chain them through the cleanup's UnifySameDomain history.
+     */
+    static applyThroughCleanup(source, cleanup) {
+        for (const entry of source.colorMap) {
+            const preFace = Face.fromTopoDSFace(Explorer.toFace(entry.shape));
+            const postFaces = cleanup.remapFace(preFace);
+            if (!postFaces) {
+                continue;
+            }
+            for (const postFace of postFaces) {
+                cleanup.shape.setColor(postFace.getShape(), entry.color);
+            }
+        }
+    }
+}

package/lib/dist/oc/extrude-ops.js

@@ -59,11 +59,33 @@ export class ExtrudeOps {
     static makeRevol(shape, axis, angle) {
         const oc = getOC();
         const [ax1, disposeAx1] = Convert.toGpAx1(axis);
-        const revol = new oc.BRepPrimAPI_MakeRevol(shape.getShape(), ax1, angle, true);
-        const result = revol.Shape();
+        let revol;
+        try {
+            revol = new oc.BRepPrimAPI_MakeRevol(shape.getShape(), ax1, angle, true);
+        }
+        catch {
+            disposeAx1();
+            throw new Error("Revolution failed");
+        }
+        if (!revol.IsDone()) {
+            revol.delete();
+            disposeAx1();
+            throw new Error("Revolution failed");
+        }
+        const rawResult = revol.Shape();
         revol.delete();
         disposeAx1();
-        const clean = ShapeOps.cleanShapeRaw(result);
+        // A profile face whose normal points "backwards" relative to the axis
+        // produces a closed solid with inverted shell orientation. Volume can
+        // still be positive but downstream boolean ops fail. OrientClosedSolid
+        // flips the shell to outward-facing when needed.
+        let oriented = rawResult;
+        if (Explorer.isSolid(rawResult)) {
+            const solid = Explorer.toSolid(rawResult);
+            oc.BRepLib.OrientClosedSolid(solid);
+            oriented = solid;
+        }
+        const clean = ShapeOps.cleanShapeRaw(oriented);
         return ShapeFactory.fromShape(clean);
     }
     static applyDraftOnSideFaces(solid, firstFace, lastFace, plane, angle) {

package/lib/dist/oc/face-ops.d.ts

@@ -20,7 +20,6 @@ export declare class FaceOps {
     static fixFaceOrientation(face: Face | TopoDS_Face): Face;
     static makeFaceWithHoles(outerWire: Wire, holes: Wire[]): Face;
     static isPointInsideFace(point: Point, face: Face | TopoDS_Face): boolean;
-    static getFreeBoundsWire(compound: any): TopoDS_Wire | null;
     static makeFaceFromPlane2(plane: gp_Pln): TopoDS_Face;
     static makeFaceFromPlane(plane: gp_Pln): TopoDS_Face;
     static makeFaceFromCylinder(cylinder: gp_Cylinder): TopoDS_Face;

package/lib/dist/oc/face-ops.js

@@ -197,19 +197,6 @@ export class FaceOps {
         disposePnt();
         return isInside;
     }
-    static getFreeBoundsWire(compound) {
-        const oc = getOC();
-        const freeBounds = new oc.ShapeAnalysis_FreeBounds(compound, oc.Precision.Confusion(), true, true);
-        const closedWiresCompound = freeBounds.GetClosedWires();
-        const explorer = new oc.TopExp_Explorer(closedWiresCompound, oc.TopAbs_ShapeEnum.TopAbs_WIRE, oc.TopAbs_ShapeEnum.TopAbs_SHAPE);
-        let result = null;
-        if (explorer.More()) {
-            result = oc.TopoDS.Wire(explorer.Current());
-        }
-        explorer.delete();
-        freeBounds.delete();
-        return result;
-    }
     static makeFaceFromPlane2(plane) {
         const oc = getOC();
         const faceMaker = new oc.BRepBuilderAPI_MakeFace(plane, -1000, 1000, -1000, 1000);

package/lib/dist/oc/face-query.d.ts

@@ -8,6 +8,7 @@ export declare class FaceQuery {
     static isConeFace(face: Shape): boolean;
     static isCylinderFace(face: Shape, diameter?: number): boolean;
     static isCylinderCurveFace(face: Shape, diameter?: number): boolean;
+    static isTorusFace(face: Shape, majorRadius?: number, minorRadius?: number): boolean;
     static isFaceOnPlane(face: Shape, plane: Plane): boolean;
     static doesFaceIntersectPlane(face: Shape, plane: Plane): boolean;
     static isFaceParallelToPlane(face: Shape, plane: Plane): boolean;
@@ -23,6 +24,7 @@ export declare class FaceQuery {
     static isConeFaceRaw(face: TopoDS_Shape): boolean;
     static isCylinderFaceRaw(face: TopoDS_Shape, diameter?: number): boolean;
     static isCylinderCurveFaceRaw(face: TopoDS_Shape, diameter?: number): boolean;
+    static isTorusFaceRaw(face: TopoDS_Shape, majorRadius?: number, minorRadius?: number): boolean;
     static isFaceOnPlaneRaw(face: TopoDS_Shape, plane: gp_Pln): boolean;
     static isFaceParallelToPlaneRaw(face: TopoDS_Shape, plane: gp_Pln): boolean;
     static isPlanarFaceRaw(face: TopoDS_Shape): boolean;

package/lib/dist/oc/face-query.js

@@ -17,6 +17,9 @@ export class FaceQuery {
     static isCylinderCurveFace(face, diameter) {
         return FaceQuery.isCylinderCurveFaceRaw(face.getShape(), diameter);
     }
+    static isTorusFace(face, majorRadius, minorRadius) {
+        return FaceQuery.isTorusFaceRaw(face.getShape(), majorRadius, minorRadius);
+    }
     static isFaceOnPlane(face, plane) {
         const [gpPln, dispose] = Convert.toGpPln(plane);
         const result = FaceQuery.isFaceOnPlaneRaw(face.getShape(), gpPln);
@@ -198,6 +201,33 @@ export class FaceQuery {
         }
         return false;
     }
+    static isTorusFaceRaw(face, majorRadius, minorRadius) {
+        const oc = getOC();
+        const ocFace = oc.TopoDS.Face(face);
+        const faceAdaptor = new oc.BRepAdaptor_Surface(ocFace, true);
+        const type = faceAdaptor.GetType();
+        if (type !== oc.GeomAbs_SurfaceType.GeomAbs_Torus) {
+            faceAdaptor.delete();
+            return false;
+        }
+        if (majorRadius === undefined && minorRadius === undefined) {
+            faceAdaptor.delete();
+            return true;
+        }
+        const torus = faceAdaptor.Torus();
+        const actualMajor = torus.MajorRadius();
+        const actualMinor = torus.MinorRadius();
+        torus.delete();
+        faceAdaptor.delete();
+        const tol = oc.Precision.Confusion();
+        if (majorRadius !== undefined && Math.abs(actualMajor - majorRadius) > tol) {
+            return false;
+        }
+        if (minorRadius !== undefined && Math.abs(actualMinor - minorRadius) > tol) {
+            return false;
+        }
+        return true;
+    }
     static isFaceOnPlaneRaw(face, plane) {
         const oc = getOC();
         return FaceOps.faceOnPlane(oc.TopoDS.Face(face), plane);

package/lib/dist/oc/fillet-ops.d.ts

@@ -2,12 +2,14 @@ import type { gp_Pln, TopoDS_Wire } from "occjs-wrapper";
 import { Shape } from "../common/shape.js";
 import { Edge } from "../common/edge.js";
 import { Face } from "../common/face.js";
+import { Solid } from "../common/solid.js";
 import { Wire } from "../common/wire.js";
 import { Plane } from "../math/plane.js";
 export declare class FilletOps {
-    static makeFillet(solid: Shape, edges: Edge[], radius: number): Shape;
-    static makeChamfer(solid: Shape, edges: Edge[], distance: number): Shape;
-    static makeChamferTwoDistances(solid: Shape, edges: Edge[], distance1: number, distance2: number, faces: Face[], isAngle?: boolean): Shape;
+    static makeFillet(solid: Shape, edges: Edge[], radius: number): Solid[];
+    static makeChamfer(solid: Shape, edges: Edge[], distance: number): Solid[];
+    private static wrapResultSolids;
+    static makeChamferTwoDistances(solid: Shape, edges: Edge[], distance1: number, distance2: number, faces: Face[], isAngle?: boolean): Solid[];
     static fillet2d(shape: Wire | Edge, plane: Plane, radius: number): Wire;
     static fillet2dRaw(wire: TopoDS_Wire, plane: gp_Pln, radius: number): TopoDS_Wire;
 }

package/lib/dist/oc/fillet-ops.js

@@ -1,9 +1,11 @@
 import { getOC } from "./init.js";
 import { Convert } from "./convert.js";
+import { Solid } from "../common/solid.js";
 import { Wire } from "../common/wire.js";
-import { ShapeFactory } from "../common/shape-factory.js";
 import { WireOps } from "./wire-ops.js";
 import { rad } from "../helpers/math-helpers.js";
+import { ColorTransfer } from "./color-transfer.js";
+import { Explorer } from "./explorer.js";
 export class FilletOps {
     static makeFillet(solid, edges, radius) {
         const oc = getOC();
@@ -19,8 +21,11 @@ export class FilletOps {
             throw new Error("Failed to create fillet.");
         }
         const result = maker.Shape();
+        const solids = FilletOps.wrapResultSolids(result);
+        ColorTransfer.applyThroughMaker([solid], solids, maker);
+        ColorTransfer.applyBleeding([solid], solids, maker);
         maker.delete();
-        return ShapeFactory.fromShape(result);
+        return solids;
     }
     static makeChamfer(solid, edges, distance) {
         const oc = getOC();
@@ -36,8 +41,19 @@ export class FilletOps {
             throw new Error("Failed to create chamfer.");
         }
         const result = maker.Shape();
+        const solids = FilletOps.wrapResultSolids(result);
+        ColorTransfer.applyThroughMaker([solid], solids, maker);
+        ColorTransfer.applyBleeding([solid], solids, maker);
         maker.delete();
-        return ShapeFactory.fromShape(result);
+        return solids;
+    }
+    static wrapResultSolids(result) {
+        const oc = getOC();
+        if (Explorer.isSolid(result)) {
+            return [Solid.fromTopoDSSolid(Explorer.toSolid(result))];
+        }
+        const solidRaws = Explorer.findShapes(result, oc.TopAbs_ShapeEnum.TopAbs_SOLID);
+        return solidRaws.map(r => Solid.fromTopoDSSolid(Explorer.toSolid(r)));
     }
     static makeChamferTwoDistances(solid, edges, distance1, distance2, faces, isAngle = false) {
         const oc = getOC();
@@ -62,8 +78,11 @@ export class FilletOps {
             throw new Error("Failed to create chamfer.");
         }
         const result = maker.Shape();
+        const solids = FilletOps.wrapResultSolids(result);
+        ColorTransfer.applyThroughMaker([solid], solids, maker);
+        ColorTransfer.applyBleeding([solid], solids, maker);
         maker.delete();
-        return ShapeFactory.fromShape(result);
+        return solids;
     }
     static fillet2d(shape, plane, radius) {
         const wire = shape instanceof Wire ? shape : WireOps.makeWireFromEdges([shape]);
@@ -74,80 +93,98 @@ export class FilletOps {
     }
     static fillet2dRaw(wire, plane, radius) {
         const oc = getOC();
-        let currentWire = wire;
-        let cornerIndex = 0;
         const isClosed = wire.Closed();
-        try {
-            while (true) {
-                const edges = [];
-                const explorer = new oc.BRepTools_WireExplorer(currentWire);
-                while (explorer.More()) {
-                    edges.push(oc.TopoDS.Edge(explorer.Current()));
-                    explorer.Next();
-                }
-                explorer.delete();
-                const maxCorners = isClosed ? edges.length : edges.length - 1;
-                if (cornerIndex >= maxCorners) {
-                    edges.forEach(e => e.delete());
-                    break;
+        const ownedEdges = [];
+        // Extract edges in wire traversal order and canonicalize: for each REVERSED edge,
+        // build a new FORWARD edge whose natural parameterization matches the wire traversal.
+        // ChFi2d_FilletAPI returns modified edges whose natural direction matches the input's
+        // natural direction, so aligning natural direction with wire traversal makes the
+        // modEdges directly usable when rebuilding the final wire.
+        const wireEdges = [];
+        {
+            const explorer = new oc.BRepTools_WireExplorer(wire);
+            while (explorer.More()) {
+                const raw = oc.TopoDS.Edge(explorer.Current());
+                const isReversed = raw.Orientation().value === oc.TopAbs_Orientation.TopAbs_REVERSED.value;
+                if (!isReversed) {
+                    wireEdges.push(raw);
+                    ownedEdges.push(raw);
                 }
-                const edge1 = edges[cornerIndex];
-                const edge2 = edges[(cornerIndex + 1) % edges.length];
-                const sharedVertex = oc.TopExp.LastVertex(edge1, false);
-                const sharedPoint = oc.BRep_Tool.Pnt(sharedVertex);
-                sharedVertex.delete();
-                const pairWireBuilder = new oc.BRepBuilderAPI_MakeWire(edge1, edge2);
-                const pairWire = pairWireBuilder.Wire();
-                const filletAPI = new oc.ChFi2d_FilletAPI(pairWire, plane);
-                const success = filletAPI.Perform(radius);
-                if (!success) {
-                    filletAPI.delete();
-                    pairWire.delete();
-                    pairWireBuilder.delete();
-                    edges.forEach(e => e.delete());
-                    cornerIndex++;
-                    continue;
+                else {
+                    const adaptor = new oc.BRepAdaptor_Curve(raw);
+                    const edgeFirst = adaptor.FirstParameter();
+                    const edgeLast = adaptor.LastParameter();
+                    adaptor.delete();
+                    const curveHandle = oc.BRep_Tool.Curve(raw, 0, 1);
+                    if (!curveHandle || curveHandle.IsNull()) {
+                        raw.delete();
+                        explorer.delete();
+                        ownedEdges.forEach(e => e.delete());
+                        throw new Error("fillet2d: edge has no 3D curve");
+                    }
+                    const curve = curveHandle.get();
+                    const reversedHandle = curve.Reversed();
+                    const newFirst = curve.ReversedParameter(edgeLast);
+                    const newLast = curve.ReversedParameter(edgeFirst);
+                    const maker = new oc.BRepBuilderAPI_MakeEdge(reversedHandle, newFirst, newLast);
+                    const newEdge = oc.TopoDS.Edge(maker.Edge());
+                    maker.delete();
+                    reversedHandle.delete();
+                    curveHandle.delete();
+                    raw.delete();
+                    wireEdges.push(newEdge);
+                    ownedEdges.push(newEdge);
                 }
-                const modEdge1 = new oc.TopoDS_Edge();
-                const modEdge2 = new oc.TopoDS_Edge();
-                const filletEdge = filletAPI.Result(sharedPoint, modEdge1, modEdge2, -1);
+                explorer.Next();
+            }
+            explorer.delete();
+        }
+        const currentEdges = wireEdges.slice();
+        const filletArcs = new Map();
+        const maxCorners = isClosed ? currentEdges.length : currentEdges.length - 1;
+        for (let cornerIndex = 0; cornerIndex < maxCorners; cornerIndex++) {
+            const nextIndex = (cornerIndex + 1) % currentEdges.length;
+            const edge1 = currentEdges[cornerIndex];
+            const edge2 = currentEdges[nextIndex];
+            const sharedVertex = oc.TopExp.LastVertex(edge1, true);
+            const sharedPoint = oc.BRep_Tool.Pnt(sharedVertex);
+            sharedVertex.delete();
+            const filletAPI = new oc.ChFi2d_FilletAPI(edge1, edge2, plane);
+            const success = filletAPI.Perform(radius);
+            if (!success || filletAPI.NbResults(sharedPoint) === 0) {
                 sharedPoint.delete();
                 filletAPI.delete();
-                pairWire.delete();
-                pairWireBuilder.delete();
-                const newWireBuilder = new oc.BRepBuilderAPI_MakeWire();
-                const nextIndex = (cornerIndex + 1) % edges.length;
-                for (let i = 0; i < edges.length; i++) {
-                    if (i === cornerIndex) {
-                        newWireBuilder.Add(modEdge1);
-                        newWireBuilder.Add(filletEdge);
-                    }
-                    else if (i === nextIndex) {
-                        newWireBuilder.Add(modEdge2);
-                    }
-                    else {
-                        newWireBuilder.Add(edges[i]);
-                    }
-                }
-                const prevWire = currentWire;
-                currentWire = newWireBuilder.Wire();
-                newWireBuilder.delete();
-                if (prevWire !== wire) {
-                    prevWire.delete();
-                }
-                modEdge1.delete();
-                modEdge2.delete();
-                filletEdge.delete();
-                edges.forEach(e => e.delete());
-                cornerIndex += 2;
+                continue;
             }
-            return currentWire;
+            const modEdge1 = new oc.TopoDS_Edge();
+            const modEdge2 = new oc.TopoDS_Edge();
+            const filletEdge = filletAPI.Result(sharedPoint, modEdge1, modEdge2, -1);
+            sharedPoint.delete();
+            filletAPI.delete();
+            currentEdges[cornerIndex] = modEdge1;
+            currentEdges[nextIndex] = modEdge2;
+            filletArcs.set(cornerIndex, filletEdge);
+            ownedEdges.push(modEdge1, modEdge2, filletEdge);
         }
-        catch (e) {
-            if (currentWire !== wire) {
-                currentWire.delete();
+        const edgeList = new oc.TopTools_ListOfShape();
+        for (let i = 0; i < currentEdges.length; i++) {
+            edgeList.Append(oc.TopoDS.Edge(currentEdges[i]));
+            const arc = filletArcs.get(i);
+            if (arc) {
+                edgeList.Append(oc.TopoDS.Edge(arc));
             }
-            throw e;
         }
+        const wireBuilder = new oc.BRepBuilderAPI_MakeWire();
+        wireBuilder.Add(edgeList);
+        edgeList.delete();
+        if (!wireBuilder.IsDone()) {
+            wireBuilder.delete();
+            ownedEdges.forEach(e => e.delete());
+            throw new Error("fillet2d: failed to build filleted wire");
+        }
+        const result = wireBuilder.Wire();
+        wireBuilder.delete();
+        ownedEdges.forEach(e => e.delete());
+        return result;
     }
 }

package/lib/dist/oc/intersection.js

@@ -27,9 +27,12 @@ export class ProjectionOps {
             // handle.delete();
         }
         if (wirePlane && wirePlane.isParallelTo(targetPlane)) {
-            const distance = wirePlane.distanceToPlane(targetPlane);
-            console.log('Wire is coplanar with plane, applying translation if necessary');
-            const translation = targetPlane.normal.multiply(-distance);
+            // Translation along the target normal that moves a point from the wire
+            // plane onto the target plane. Use the *signed* distance — `distanceToPlane`
+            // is abs-valued and picks the wrong direction when the wire sits on the
+            // negative side of the target normal.
+            const signedDist = targetPlane.signedDistanceToPoint(wirePlane.origin);
+            const translation = targetPlane.normal.multiply(-signedDist);
             const matrix = Matrix4.fromTranslation(translation.x, translation.y, translation.z);
             const transformed = ShapeOps.transform(wire, matrix);
             return [transformed];

package/lib/dist/oc/mesh.d.ts

@@ -1,4 +1,4 @@
-import type { TopoDS_Face, TopoDS_Shape } from "occjs-wrapper";
+import type { TopoDS_Edge, TopoDS_Face, TopoDS_Shape } from "occjs-wrapper";
 import { Face } from "../common/face.js";
 import { Shape } from "../common/shape.js";
 export interface MeshData {
@@ -7,11 +7,34 @@ export interface MeshData {
     indices: number[];
     count?: number;
 }
+export interface EnsureTriangulatedOptions {
+    linDefl?: number;
+    angDefl?: number;
+    parallel?: boolean;
+    relative?: boolean;
+    checkFreeEdges?: boolean;
+}
 export declare class Mesh {
     static triangulateFace(face: Face, vertexOffset?: number): MeshData | null;
     static discretizeEdge(edge: Shape): MeshData;
-    static premeshShape(shape: TopoDS_Shape): void;
+    /**
+     * Triangulates `shape` only if it doesn't already have an up-to-date
+     * triangulation at the requested deflection. Returns true when a fresh
+     * mesh was built, false when the stored one was reused.
+     */
+    static ensureTriangulated(shape: TopoDS_Shape, opts?: EnsureTriangulatedOptions): boolean;
     static triangulateFaceRaw(face: TopoDS_Face, vertexOffset?: number): MeshData | null;
     static extractFaceTriangulationRaw(face: TopoDS_Face, vertexOffset?: number): MeshData | null;
+    /**
+     * Reads the polyline stored for `edge` as a polygon-on-triangulation of
+     * `face`. Node indices point into the face's triangulation, so the edge
+     * samples coincide exactly with the face mesh vertices (watertight).
+     */
+    static discretizeEdgeOnFace(edge: TopoDS_Edge, face: TopoDS_Face): MeshData | null;
+    /**
+     * Reads the stored 3D polygon for a free edge (one not attached to a
+     * meshed face). Caller must have already run `ensureTriangulated` on the
+     * edge or its parent wire.
+     */
     static discretizeEdgeRaw(edge: TopoDS_Shape): MeshData;
 }