okgeometry-api 1.1.23 → 1.2.1

package/dist/Mesh.js

@@ -1,11 +1,13 @@
 import { ensureInit } from "./engine.js";
 import { Point } from "./Point.js";
 import { Vec3 } from "./Vec3.js";
+import { Plane } from "./Plane.js";
 import { Polyline } from "./Polyline.js";
 import { Line } from "./Line.js";
 import { Circle } from "./Circle.js";
 import { Arc } from "./Arc.js";
 import { Polygon } from "./Polygon.js";
+import { MeshSurface } from "./MeshSurface.js";
 import { NurbsCurve } from "./NurbsCurve.js";
 import { PolyCurve } from "./PolyCurve.js";
 import { pointsToCoords, parsePolylineBuffer as parsePolylineBuf } from "./BufferCodec.js";
@@ -33,6 +35,10 @@ export class Mesh {
         this._indexBuffer = null;
         this._vertices = null;
         this._faces = null;
+        this._planarFaces = null;
+        this._planarFacesByTriangleIndex = null;
+        this._surfaces = null;
+        this._surfacesByTriangleIndex = null;
         this._edgeVertexPairs = null;
         this._topologyMetricsCache = null;
         this._isClosedVolumeCache = null;
@@ -116,6 +122,55 @@ export class Mesh {
         const diag = Math.hypot(dx, dy, dz);
         return Number.isFinite(diag) && diag > 0 ? diag : 1;
     }
+    static computeSignedVolumeFromBuffer(buffer) {
+        const vertexCount = Math.max(0, Math.floor(buffer[0] ?? 0));
+        if (vertexCount <= 0)
+            return 0;
+        const indexStart = 1 + vertexCount * 3;
+        let signedVolume = 0;
+        for (let i = indexStart; i + 2 < buffer.length; i += 3) {
+            const ia = Math.floor(buffer[i] ?? -1);
+            const ib = Math.floor(buffer[i + 1] ?? -1);
+            const ic = Math.floor(buffer[i + 2] ?? -1);
+            if (ia < 0 || ib < 0 || ic < 0 || ia >= vertexCount || ib >= vertexCount || ic >= vertexCount)
+                continue;
+            const ax = buffer[1 + ia * 3];
+            const ay = buffer[1 + ia * 3 + 1];
+            const az = buffer[1 + ia * 3 + 2];
+            const bx = buffer[1 + ib * 3];
+            const by = buffer[1 + ib * 3 + 1];
+            const bz = buffer[1 + ib * 3 + 2];
+            const cx = buffer[1 + ic * 3];
+            const cy = buffer[1 + ic * 3 + 1];
+            const cz = buffer[1 + ic * 3 + 2];
+            signedVolume += ax * (by * cz - bz * cy)
+                - ay * (bx * cz - bz * cx)
+                + az * (bx * cy - by * cx);
+        }
+        return signedVolume / 6;
+    }
+    static reverseTriangleWinding(buffer) {
+        const flipped = new Float64Array(buffer);
+        const vertexCount = Math.max(0, Math.floor(flipped[0] ?? 0));
+        const indexStart = 1 + vertexCount * 3;
+        for (let i = indexStart; i + 2 < flipped.length; i += 3) {
+            const tmp = flipped[i + 1];
+            flipped[i + 1] = flipped[i + 2];
+            flipped[i + 2] = tmp;
+        }
+        return flipped;
+    }
+    static normalizeClosedVolumeOrientation(mesh) {
+        if (mesh.faceCount === 0 || mesh._vertexCount <= 0)
+            return mesh;
+        const topology = mesh.topologyMetrics();
+        if (topology.boundaryEdges !== 0 || topology.nonManifoldEdges !== 0)
+            return mesh;
+        const signedVolume = Mesh.computeSignedVolumeFromBuffer(mesh._buffer);
+        if (!Number.isFinite(signedVolume) || signedVolume >= 0)
+            return mesh;
+        return new Mesh(Mesh.reverseTriangleWinding(mesh._buffer), mesh._trustedBooleanInput);
+    }
     static booleanContactTolerance(a, b) {
         const scale = Math.max(Mesh.boundsDiag(a), Mesh.boundsDiag(b));
         return Math.min(1e-4, Math.max(1e-9, scale * 1e-6));
@@ -338,6 +393,165 @@ export class Mesh {
     static emptyMesh() {
         return Mesh.fromTrustedBuffer(new Float64Array(0));
     }
+    static createSplitResult(outside, inside, classification = "volume") {
+        const result = {
+            outside,
+            inside,
+            all: outside.concat(inside),
+            classification,
+        };
+        if (classification === "surface") {
+            result.negative = outside;
+            result.positive = inside;
+        }
+        return result;
+    }
+    static createSurfaceSplitResult(negative, positive) {
+        return Mesh.createSplitResult(negative, positive, "surface");
+    }
+    static createPlaneSplitResult(negative, positive, classification = "surface") {
+        return {
+            ...Mesh.createSplitResult(negative, positive, classification),
+            negative,
+            positive,
+        };
+    }
+    static parseSplitResultBuffer(buffer) {
+        if (buffer.length < 2) {
+            throw new Error("Mesh split failed and returned a corrupt split buffer.");
+        }
+        const outsideCount = Math.max(0, Math.floor(buffer[0] ?? 0));
+        const insideCount = Math.max(0, Math.floor(buffer[1] ?? 0));
+        let offset = 2;
+        const decodeGroup = (count) => {
+            const meshes = [];
+            for (let i = 0; i < count; i++) {
+                const rawLen = Math.floor(buffer[offset++] ?? -1);
+                if (rawLen < 0 || offset + rawLen > buffer.length) {
+                    throw new Error("Mesh split failed and returned an invalid component buffer.");
+                }
+                meshes.push(Mesh.fromTrustedBuffer(buffer.slice(offset, offset + rawLen)));
+                offset += rawLen;
+            }
+            return meshes;
+        };
+        const outside = decodeGroup(outsideCount);
+        const inside = decodeGroup(insideCount);
+        if (offset !== buffer.length) {
+            throw new Error("Mesh split failed and returned trailing buffer data.");
+        }
+        return Mesh.createSplitResult(outside, inside);
+    }
+    static orthonormalPlaneFrame(plane) {
+        const normal = plane.normal.normalize();
+        let uAxis = plane.getXAxis().normalize();
+        if (uAxis.length() < 1e-9) {
+            uAxis = Math.abs(normal.x) > 0.9 ? Vec3.Y : Vec3.X;
+            uAxis = uAxis.sub(normal.scale(uAxis.dot(normal))).normalize();
+        }
+        const vAxis = normal.cross(uAxis).normalize();
+        return { uAxis, vAxis, normal };
+    }
+    static createOrientedBox(center, uAxis, vAxis, wAxis, halfU, halfV, halfW) {
+        const axes = [uAxis.normalize(), vAxis.normalize(), wAxis.normalize()];
+        const [u, v, w] = axes;
+        const corners = [
+            center.add(u.scale(-halfU)).add(v.scale(-halfV)).add(w.scale(-halfW)),
+            center.add(u.scale(halfU)).add(v.scale(-halfV)).add(w.scale(-halfW)),
+            center.add(u.scale(halfU)).add(v.scale(halfV)).add(w.scale(-halfW)),
+            center.add(u.scale(-halfU)).add(v.scale(halfV)).add(w.scale(-halfW)),
+            center.add(u.scale(-halfU)).add(v.scale(-halfV)).add(w.scale(halfW)),
+            center.add(u.scale(halfU)).add(v.scale(-halfV)).add(w.scale(halfW)),
+            center.add(u.scale(halfU)).add(v.scale(halfV)).add(w.scale(halfW)),
+            center.add(u.scale(-halfU)).add(v.scale(halfV)).add(w.scale(halfW)),
+        ];
+        const indices = [
+            0, 2, 1, 0, 3, 2,
+            4, 5, 6, 4, 6, 7,
+            0, 1, 5, 0, 5, 4,
+            3, 7, 6, 3, 6, 2,
+            0, 4, 7, 0, 7, 3,
+            1, 2, 6, 1, 6, 5,
+        ];
+        const raw = new Float64Array(1 + corners.length * 3 + indices.length);
+        raw[0] = corners.length;
+        let offset = 1;
+        for (const corner of corners) {
+            raw[offset++] = corner.x;
+            raw[offset++] = corner.y;
+            raw[offset++] = corner.z;
+        }
+        for (const index of indices) {
+            raw[offset++] = index;
+        }
+        return Mesh.fromBuffer(raw, { trustedBooleanInput: true });
+    }
+    static classifyPlaneDistances(mesh, plane) {
+        if (mesh.vertexCount <= 0)
+            return { min: 0, max: 0 };
+        let min = Number.POSITIVE_INFINITY;
+        let max = Number.NEGATIVE_INFINITY;
+        for (const vertex of mesh.vertices) {
+            const distance = plane.distanceTo(vertex);
+            if (distance < min)
+                min = distance;
+            if (distance > max)
+                max = distance;
+        }
+        return { min, max };
+    }
+    static createPlaneHalfSpaceCutter(host, plane, options) {
+        const bounds = Mesh.toDebugBounds(host.getBounds());
+        const scale = Number.isFinite(options?.planePaddingScale)
+            ? Math.max(1.1, options?.planePaddingScale ?? 2.5)
+            : 2.5;
+        const radius = Math.max(1e-6, bounds.diagonal * 0.5);
+        const halfU = radius * scale;
+        const halfV = radius * scale;
+        const halfW = radius * scale;
+        const { uAxis, vAxis, normal } = Mesh.orthonormalPlaneFrame(plane);
+        const projectedCenter = plane.projectPoint(bounds.center);
+        const boxCenter = projectedCenter.add(normal.scale(halfW));
+        return Mesh.createOrientedBox(boxCenter, uAxis, vAxis, normal, halfU, halfV, halfW);
+    }
+    static detectClosedCurveNormal(curve, points) {
+        if (curve instanceof Circle || curve instanceof Arc) {
+            return curve.normal.normalize();
+        }
+        const normal = Mesh.computePlanarCurveNormal(points, true).normalize();
+        if (!Number.isFinite(normal.x) || !Number.isFinite(normal.y) || !Number.isFinite(normal.z) || normal.length() < 1e-9) {
+            throw new Error("Mesh.split(curve) requires a planar closed curve with a valid normal.");
+        }
+        return normal;
+    }
+    static createCurveSplitCutter(host, curve, options) {
+        const segments = Number.isFinite(options?.curveSegments)
+            ? Math.max(3, Math.floor(options?.curveSegments ?? 32))
+            : 32;
+        const points = Mesh.getClosedCurveLoopPoints(curve, segments);
+        const normal = Mesh.detectClosedCurveNormal(curve, points);
+        let extrusionDirection = options?.direction;
+        let basePoints = points;
+        if (extrusionDirection) {
+            if (!Number.isFinite(extrusionDirection.length()) || extrusionDirection.length() < 1e-9) {
+                throw new Error("Mesh.split(curve) requires a non-zero direction when direction is provided.");
+            }
+        }
+        else {
+            const bounds = Mesh.toDebugBounds(host.getBounds());
+            const margin = Math.max(1e-6, bounds.diagonal * 0.25);
+            const distances = host.vertices.map((vertex) => normal.dot(vertex.sub(points[0])));
+            const minDistance = Math.min(...distances);
+            const maxDistance = Math.max(...distances);
+            const halfDepth = Math.max(Math.abs(minDistance), Math.abs(maxDistance)) + margin;
+            extrusionDirection = normal.scale(halfDepth * 2);
+            basePoints = points.map((point) => point.add(normal.scale(-halfDepth)));
+        }
+        const height = extrusionDirection.length();
+        const unit = extrusionDirection.normalize();
+        const prepared = Mesh.prepareBooleanCutterCurve(basePoints, true, unit, height);
+        return Mesh.extrudePlanarCurve(prepared.points, unit, prepared.height, true);
+    }
     // ── GPU-ready buffers ──────────────────────────────────────────
     /**
      * Float32 xyz positions for Three.js BufferGeometry.
@@ -372,7 +586,7 @@ export class Mesh {
     get vertexCount() {
         return this._vertexCount;
     }
-    /** Number of triangular faces in this mesh */
+    /** Number of triangular faces in this mesh. Use `planarFaceCount` for logical planar faces. */
     get faceCount() {
         const start = 1 + this._vertexCount * 3;
         if (this._buffer.length <= start)
@@ -398,6 +612,7 @@ export class Mesh {
     /**
      * Get all faces as arrays of vertex indices.
      * Each face is [i0, i1, i2] for the three triangle vertices.
+     * For coplanar edge-connected logical faces, use `planarFaces`.
      * Lazy-computed and cached.
      */
     get faces() {
@@ -411,6 +626,42 @@ export class Mesh {
         }
         return this._faces;
     }
+    /**
+     * Alias for triangle faces, mirroring `faces`.
+     * Use `planarFaces` when you want logical mesh faces such as the 6 faces of a box.
+     */
+    get triangles() {
+        return this.faces;
+    }
+    /**
+     * Number of coplanar edge-connected planar faces in this mesh.
+     * Examples: a box has 6, an L-shaped extrusion has 8.
+     */
+    get planarFaceCount() {
+        return this.planarFaces.length;
+    }
+    /**
+     * Logical mesh faces built by grouping coplanar edge-connected triangles.
+     * Cached after the first query to keep repeated face access cheap.
+     */
+    get planarFaces() {
+        this.ensurePlanarFaceCache();
+        return this._planarFaces ?? [];
+    }
+    /**
+     * Number of logical planar surfaces in this mesh.
+     * Mirrors `planarFaceCount`, but returns wrapper objects with surface queries.
+     */
+    get surfaceCount() {
+        return this.surfaces.length;
+    }
+    /**
+     * Logical planar mesh surfaces with `evaluate(u, v)` and `normal(u, v)` methods.
+     */
+    get surfaces() {
+        this.ensureSurfaceCache();
+        return this._surfaces ?? [];
+    }
     /** Raw WASM buffer (for advanced use / re-passing to WASM) */
     get rawBuffer() {
         return this._buffer;
@@ -425,11 +676,111 @@ export class Mesh {
         return new Mesh(buffer, options?.trustedBooleanInput ?? false);
     }
     static fromTrustedBuffer(buffer) {
-        return new Mesh(buffer, true);
+        return Mesh.normalizeClosedVolumeOrientation(new Mesh(buffer, true));
     }
     get trustedBooleanInput() {
         return this._trustedBooleanInput;
     }
+    getTriangleVertexIndices(faceIndex) {
+        if (!Number.isFinite(faceIndex) || faceIndex < 0 || faceIndex >= this.faceCount)
+            return null;
+        const indexBuffer = this.indexBuffer;
+        const offset = Math.floor(faceIndex) * 3;
+        if (offset + 2 >= indexBuffer.length)
+            return null;
+        return [indexBuffer[offset], indexBuffer[offset + 1], indexBuffer[offset + 2]];
+    }
+    computeTriangleAreaByIndex(faceIndex) {
+        const tri = this.getTriangleVertexIndices(faceIndex);
+        if (!tri)
+            return 0;
+        const [i0, i1, i2] = tri;
+        const base = 1;
+        const off0 = base + i0 * 3;
+        const off1 = base + i1 * 3;
+        const off2 = base + i2 * 3;
+        const ax = this._buffer[off0] ?? 0;
+        const ay = this._buffer[off0 + 1] ?? 0;
+        const az = this._buffer[off0 + 2] ?? 0;
+        const bx = this._buffer[off1] ?? 0;
+        const by = this._buffer[off1 + 1] ?? 0;
+        const bz = this._buffer[off1 + 2] ?? 0;
+        const cx = this._buffer[off2] ?? 0;
+        const cy = this._buffer[off2 + 1] ?? 0;
+        const cz = this._buffer[off2 + 2] ?? 0;
+        const abx = bx - ax;
+        const aby = by - ay;
+        const abz = bz - az;
+        const acx = cx - ax;
+        const acy = cy - ay;
+        const acz = cz - az;
+        const crossX = aby * acz - abz * acy;
+        const crossY = abz * acx - abx * acz;
+        const crossZ = abx * acy - aby * acx;
+        return 0.5 * Math.sqrt(crossX * crossX + crossY * crossY + crossZ * crossZ);
+    }
+    ensurePlanarFaceCache() {
+        if (this._planarFaces && this._planarFacesByTriangleIndex)
+            return;
+        ensureInit();
+        const raw = wasm.mesh_build_coplanar_connected_face_groups(this._vertexCount, this._buffer);
+        const declaredGroupCount = Math.max(0, Math.floor(raw[0] ?? 0));
+        const planarFaces = [];
+        const planarFacesByTriangleIndex = new Array(this.faceCount).fill(null);
+        let offset = 1;
+        for (let groupIndex = 0; groupIndex < declaredGroupCount && offset < raw.length; groupIndex++) {
+            const declaredTriangleCount = Math.max(0, Math.floor(raw[offset] ?? 0));
+            offset += 1;
+            const triangleIndices = [];
+            let area = 0;
+            for (let i = 0; i < declaredTriangleCount && offset < raw.length; i++, offset++) {
+                const triangleIndex = Math.floor(raw[offset] ?? -1);
+                if (triangleIndex < 0 || triangleIndex >= this.faceCount)
+                    continue;
+                triangleIndices.push(triangleIndex);
+                area += this.computeTriangleAreaByIndex(triangleIndex);
+            }
+            if (offset + 5 >= raw.length)
+                break;
+            const centroid = new Point(raw[offset] ?? 0, raw[offset + 1] ?? 0, raw[offset + 2] ?? 0);
+            const normal = new Vec3(raw[offset + 3] ?? 0, raw[offset + 4] ?? 0, raw[offset + 5] ?? 0).normalize();
+            offset += 6;
+            if (triangleIndices.length === 0)
+                continue;
+            const planarFace = {
+                index: planarFaces.length,
+                seedTriangleIndex: triangleIndices[0],
+                triangleIndices,
+                triangleCount: triangleIndices.length,
+                centroid,
+                normal,
+                area,
+            };
+            planarFaces.push(planarFace);
+            for (const triangleIndex of triangleIndices) {
+                planarFacesByTriangleIndex[triangleIndex] = planarFace;
+            }
+        }
+        this._planarFaces = planarFaces;
+        this._planarFacesByTriangleIndex = planarFacesByTriangleIndex;
+        this._surfaces = null;
+        this._surfacesByTriangleIndex = null;
+    }
+    ensureSurfaceCache() {
+        if (this._surfaces && this._surfacesByTriangleIndex)
+            return;
+        const surfaces = this.planarFaces.map(face => new MeshSurface(this, face));
+        const surfacesByTriangleIndex = new Array(this.faceCount).fill(null);
+        for (const surface of surfaces) {
+            for (const triangleIndex of surface.triangleIndices) {
+                if (triangleIndex >= 0 && triangleIndex < surfacesByTriangleIndex.length) {
+                    surfacesByTriangleIndex[triangleIndex] = surface;
+                }
+            }
+        }
+        this._surfaces = surfaces;
+        this._surfacesByTriangleIndex = surfacesByTriangleIndex;
+    }
     debugSummary() {
         const bounds = Mesh.toDebugBounds(this.getBounds());
         const topology = this.topologyMetrics();
@@ -1138,6 +1489,34 @@ export class Mesh {
         }
         return Mesh.fromTrustedBuffer(result);
     }
+    static mergeMeshComponents(meshes) {
+        if (meshes.length === 0)
+            return Mesh.emptyMesh();
+        if (meshes.length === 1)
+            return Mesh.cloneMesh(meshes[0]);
+        return Mesh.mergeMeshes(meshes);
+    }
+    static createUnsupportedOpenMeshBooleanError(operation, aClosed, bClosed) {
+        const topology = `A=${aClosed ? "closed" : "open"}, B=${bClosed ? "closed" : "open"}`;
+        if (operation === "union") {
+            return new Error(`Boolean union requires both inputs to be closed volumes (${topology}). `
+                + "Close or cap the open mesh before calling union().");
+        }
+        return new Error(`Boolean ${operation} with open meshes is only supported when A is open and B is closed `
+            + `(surface trim mode). Got ${topology}. Use Mesh.split(...) and choose outside/inside explicitly `
+            + "for other open-mesh combinations.");
+    }
+    resolveOpenMeshBooleanFallback(other, operation, options) {
+        const aClosed = this.isClosedVolume();
+        const bClosed = other.isClosedVolume();
+        if (aClosed && bClosed)
+            return null;
+        if (!aClosed && bClosed && (operation === "subtraction" || operation === "intersection")) {
+            const split = this.splitWithMesh(other, options);
+            return Mesh.mergeMeshComponents(operation === "subtraction" ? split.outside : split.inside);
+        }
+        throw Mesh.createUnsupportedOpenMeshBooleanError(operation, aClosed, bClosed);
+    }
     static encodeBooleanOperationToken(operation, a, b, options) {
         const tokens = [operation];
         if (a._trustedBooleanInput && b._trustedBooleanInput) {
@@ -1148,39 +1527,157 @@ export class Mesh {
         }
         return tokens.join("@");
     }
+    static encodeBooleanSplitToken(a, b, options) {
+        const tokens = ["split"];
+        if (a._trustedBooleanInput && b._trustedBooleanInput) {
+            tokens.push("trustedInput");
+        }
+        if (options?.debugForceFaceID) {
+            tokens.push("forceFaceID");
+        }
+        return tokens.join("@");
+    }
     // ── Booleans ───────────────────────────────────────────────────
     /**
      * Compute boolean union with another mesh.
+     * Requires both inputs to be closed volumes.
      * @param other - Mesh to union with
      * @param options - Optional safety overrides
      * @returns New mesh containing volume of both inputs
      */
     union(other, options) {
         ensureInit();
-        const operationToken = Mesh.encodeBooleanOperationToken("union", this, other, options);
-        return this.runBoolean(other, "union", () => wasm.mesh_boolean_operation(this._vertexCount, this._buffer, other._vertexCount, other._buffer, operationToken), options);
+        const lhs = Mesh.normalizeClosedVolumeOrientation(this);
+        const rhs = Mesh.normalizeClosedVolumeOrientation(other);
+        lhs.resolveOpenMeshBooleanFallback(rhs, "union", options);
+        const operationToken = Mesh.encodeBooleanOperationToken("union", lhs, rhs, options);
+        return lhs.runBoolean(rhs, "union", () => wasm.mesh_boolean_operation(lhs._vertexCount, lhs._buffer, rhs._vertexCount, rhs._buffer, operationToken), options);
     }
     /**
      * Compute boolean subtraction with another mesh.
+     * If this mesh is open and `other` is a closed cutter, this trims the open
+     * host via `split()` and returns the outside surface pieces merged together.
      * @param other - Mesh to subtract
      * @param options - Optional safety overrides
      * @returns New mesh with other's volume removed from this
      */
     subtract(other, options) {
         ensureInit();
-        const operationToken = Mesh.encodeBooleanOperationToken("subtraction", this, other, options);
-        return this.runBoolean(other, "subtraction", () => wasm.mesh_boolean_operation(this._vertexCount, this._buffer, other._vertexCount, other._buffer, operationToken), options);
+        const lhs = Mesh.normalizeClosedVolumeOrientation(this);
+        const rhs = Mesh.normalizeClosedVolumeOrientation(other);
+        const fallback = lhs.resolveOpenMeshBooleanFallback(rhs, "subtraction", options);
+        if (fallback)
+            return fallback;
+        const operationToken = Mesh.encodeBooleanOperationToken("subtraction", lhs, rhs, options);
+        return lhs.runBoolean(rhs, "subtraction", () => wasm.mesh_boolean_operation(lhs._vertexCount, lhs._buffer, rhs._vertexCount, rhs._buffer, operationToken), options);
     }
     /**
      * Compute boolean intersection with another mesh.
+     * If this mesh is open and `other` is a closed cutter, this trims the open
+     * host via `split()` and returns the inside surface pieces merged together.
      * @param other - Mesh to intersect with
      * @param options - Optional safety overrides
      * @returns New mesh containing only the overlapping volume
      */
     intersect(other, options) {
         ensureInit();
-        const operationToken = Mesh.encodeBooleanOperationToken("intersection", this, other, options);
-        return this.runBoolean(other, "intersection", () => wasm.mesh_boolean_operation(this._vertexCount, this._buffer, other._vertexCount, other._buffer, operationToken), options);
+        const lhs = Mesh.normalizeClosedVolumeOrientation(this);
+        const rhs = Mesh.normalizeClosedVolumeOrientation(other);
+        const fallback = lhs.resolveOpenMeshBooleanFallback(rhs, "intersection", options);
+        if (fallback)
+            return fallback;
+        const operationToken = Mesh.encodeBooleanOperationToken("intersection", lhs, rhs, options);
+        return lhs.runBoolean(rhs, "intersection", () => wasm.mesh_boolean_operation(lhs._vertexCount, lhs._buffer, rhs._vertexCount, rhs._buffer, operationToken), options);
+    }
+    splitWithMesh(other, options) {
+        ensureInit();
+        const faceCountA = this.faceCount;
+        const faceCountB = other.faceCount;
+        const hostClosed = this.isClosedVolume();
+        const cutterClosed = other.isClosedVolume();
+        const useVolumetricSplit = hostClosed && cutterClosed;
+        if (faceCountA === 0)
+            return Mesh.createSplitResult([], [], useVolumetricSplit ? "volume" : "surface");
+        if (faceCountB === 0) {
+            return Mesh.createSplitResult([Mesh.cloneMesh(this)], [], useVolumetricSplit || cutterClosed ? "volume" : "surface");
+        }
+        const boundsA = Mesh.computeRawBounds(this);
+        const boundsB = Mesh.computeRawBounds(other);
+        const contactTol = Mesh.booleanContactTolerance(boundsA, boundsB);
+        if (useVolumetricSplit && !Mesh.boundsOverlap(boundsA, boundsB, contactTol)) {
+            return Mesh.createSplitResult([Mesh.cloneMesh(this)], [], "volume");
+        }
+        if (!useVolumetricSplit && cutterClosed && !Mesh.boundsOverlap(boundsA, boundsB, contactTol)) {
+            return Mesh.createSplitResult([Mesh.cloneMesh(this)], [], "volume");
+        }
+        if (!options?.allowUnsafe) {
+            const limits = Mesh.resolveBooleanLimits(options?.limits);
+            const maxInputFaces = Math.max(faceCountA, faceCountB);
+            const combinedInputFaces = faceCountA + faceCountB;
+            const faceProduct = faceCountA * faceCountB;
+            if (maxInputFaces > limits.maxInputFacesPerMesh
+                || combinedInputFaces > limits.maxCombinedInputFaces
+                || faceProduct > limits.maxFaceProduct) {
+                throw new Error(`Mesh split blocked by safety limits `
+                    + `(A faces=${faceCountA}, B faces=${faceCountB}, faceProduct=${faceProduct}). `
+                    + "Simplify inputs or pass allowUnsafe: true to force execution.");
+            }
+        }
+        const splitToken = Mesh.encodeBooleanSplitToken(this, other, options);
+        const result = useVolumetricSplit
+            ? wasm.mesh_boolean_split(this._vertexCount, this._buffer, other._vertexCount, other._buffer, splitToken)
+            : wasm.mesh_surface_split(this._vertexCount, this._buffer, other._vertexCount, other._buffer, splitToken);
+        if (result.length === 0) {
+            throw new Error("Mesh split failed and returned an invalid result buffer.");
+        }
+        const parsed = Mesh.parseSplitResultBuffer(result);
+        return cutterClosed
+            ? Mesh.createSplitResult(parsed.outside, parsed.inside, "volume")
+            : Mesh.createSurfaceSplitResult(parsed.outside, parsed.inside);
+    }
+    splitWithPlane(plane, options) {
+        ensureInit();
+        const hostClosed = this.isClosedVolume();
+        if (this.faceCount === 0)
+            return Mesh.createPlaneSplitResult([], [], hostClosed ? "volume" : "surface");
+        const distances = Mesh.classifyPlaneDistances(this, plane);
+        const eps = Mesh.boundsDiag(Mesh.computeRawBounds(this)) * 1e-9 + 1e-9;
+        if (distances.max <= eps) {
+            return Mesh.createPlaneSplitResult([Mesh.cloneMesh(this)], [], hostClosed ? "volume" : "surface");
+        }
+        if (distances.min >= -eps) {
+            return Mesh.createPlaneSplitResult([], [Mesh.cloneMesh(this)], hostClosed ? "volume" : "surface");
+        }
+        if (!hostClosed) {
+            const result = wasm.mesh_surface_split_plane(this._vertexCount, this._buffer, plane.normal.x, plane.normal.y, plane.normal.z, plane.d, Mesh.encodeBooleanSplitToken(this, this, options));
+            if (result.length === 0) {
+                throw new Error("Mesh split by plane failed and returned an invalid result buffer.");
+            }
+            const split = Mesh.parseSplitResultBuffer(result);
+            return Mesh.createPlaneSplitResult(split.outside, split.inside, "surface");
+        }
+        const result = wasm.mesh_solid_split_plane(this._vertexCount, this._buffer, plane.normal.x, plane.normal.y, plane.normal.z, plane.d, Mesh.encodeBooleanSplitToken(this, this, options));
+        if (result.length === 0) {
+            throw new Error("Mesh split by plane failed and returned an invalid result buffer.");
+        }
+        const split = Mesh.parseSplitResultBuffer(result);
+        return Mesh.createPlaneSplitResult(split.outside, split.inside, "volume");
+    }
+    splitWithCurve(curve, options) {
+        ensureInit();
+        if (this.faceCount === 0)
+            return Mesh.createSplitResult([], []);
+        const cutter = Mesh.createCurveSplitCutter(this, curve, options);
+        return this.splitWithMesh(cutter, options);
+    }
+    split(target, options) {
+        if (target instanceof Mesh) {
+            return this.splitWithMesh(target, options);
+        }
+        if (target instanceof Plane) {
+            return this.splitWithPlane(target, options);
+        }
+        return this.splitWithCurve(target, options);
     }
     debugBoolean(other, operation, options, debugOptions) {
         const result = operation === "union"
@@ -1581,6 +2078,88 @@ export class Mesh {
             nonManifoldEdges,
         };
     }
+    /**
+     * Get a logical planar face by its planar-face index.
+     */
+    getPlanarFace(index) {
+        if (!Number.isFinite(index) || index < 0)
+            return null;
+        const planarFaces = this.planarFaces;
+        return planarFaces[Math.floor(index)] ?? null;
+    }
+    /**
+     * Get a logical planar surface wrapper by its planar-face index.
+     */
+    getSurface(index) {
+        if (!Number.isFinite(index) || index < 0)
+            return null;
+        const surfaces = this.surfaces;
+        return surfaces[Math.floor(index)] ?? null;
+    }
+    /**
+     * Get the logical planar face that contains a triangle face index.
+     */
+    getPlanarFaceByTriangleIndex(triangleIndex) {
+        if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
+            return null;
+        this.ensurePlanarFaceCache();
+        return this._planarFacesByTriangleIndex?.[Math.floor(triangleIndex)] ?? null;
+    }
+    /**
+     * Get the logical planar surface wrapper that contains a triangle face index.
+     */
+    getSurfaceByTriangleIndex(triangleIndex) {
+        if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
+            return null;
+        this.ensureSurfaceCache();
+        return this._surfacesByTriangleIndex?.[Math.floor(triangleIndex)] ?? null;
+    }
+    /**
+     * Find the best matching logical planar face by normal and optional centroid proximity.
+     */
+    findPlanarFaceByNormal(targetNormal, nearPoint) {
+        const planarFaces = this.planarFaces;
+        if (planarFaces.length === 0)
+            return null;
+        const normalizedTarget = targetNormal.normalize();
+        if (normalizedTarget.length() < 1e-12)
+            return null;
+        const alignmentEps = 1e-9;
+        const distanceEps = 1e-9;
+        let best = null;
+        let bestAlignment = -Infinity;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        let bestArea = -Infinity;
+        for (const planarFace of planarFaces) {
+            const alignment = planarFace.normal.dot(normalizedTarget);
+            const distance = nearPoint ? planarFace.centroid.distanceTo(nearPoint) : 0;
+            const betterAlignment = alignment > bestAlignment + alignmentEps;
+            const similarAlignment = Math.abs(alignment - bestAlignment) <= alignmentEps;
+            const betterDistance = nearPoint !== undefined && distance < bestDistance - distanceEps;
+            const similarDistance = Math.abs(distance - bestDistance) <= distanceEps;
+            const betterArea = planarFace.area > bestArea + distanceEps;
+            if (best === null
+                || betterAlignment
+                || (similarAlignment && betterDistance)
+                || (similarAlignment && (!nearPoint || similarDistance) && betterArea)) {
+                best = planarFace;
+                bestAlignment = alignment;
+                bestDistance = distance;
+                bestArea = planarFace.area;
+            }
+        }
+        return best;
+    }
+    /**
+     * Find the best matching logical planar surface wrapper by normal
+     * similarity and optional point proximity.
+     */
+    findSurfaceByNormal(targetNormal, nearPoint) {
+        const face = this.findPlanarFaceByNormal(targetNormal, nearPoint);
+        if (!face)
+            return null;
+        return this.getSurface(face.index);
+    }
     /**
      * Odd/even point containment test against a closed mesh.
      * Uses majority vote across multiple ray directions for robustness.
@@ -1593,30 +2172,14 @@ export class Mesh {
      * Find the coplanar + edge-connected face group containing a triangle.
      */
     findFaceByTriangleIndex(triangleIndex) {
-        if (!Number.isFinite(triangleIndex) || triangleIndex < 0)
-            return null;
-        ensureInit();
-        const r = wasm.mesh_find_face_group_by_triangle_index(this._vertexCount, this._buffer, Math.floor(triangleIndex));
-        if (!r || r.length < 6)
-            return null;
-        return {
-            centroid: new Point(r[0], r[1], r[2]),
-            normal: new Vec3(r[3], r[4], r[5]),
-        };
+        return this.getPlanarFaceByTriangleIndex(triangleIndex);
     }
     /**
      * Find the best matching coplanar + edge-connected face group by normal
      * similarity and optional point proximity.
      */
     findFaceByNormal(targetNormal, nearPoint) {
-        ensureInit();
-        const r = wasm.mesh_find_face_group_by_normal(this._vertexCount, this._buffer, targetNormal.x, targetNormal.y, targetNormal.z, nearPoint?.x ?? 0, nearPoint?.y ?? 0, nearPoint?.z ?? 0, nearPoint !== undefined);
-        if (!r || r.length < 6)
-            return null;
-        return {
-            centroid: new Point(r[0], r[1], r[2]),
-            normal: new Vec3(r[3], r[4], r[5]),
-        };
+        return this.findPlanarFaceByNormal(targetNormal, nearPoint);
     }
     // ── Export ──────────────────────────────────────────────────────
     /**