okgeometry-api 1.2.0 → 1.4.0

package/src/Mesh.ts

@@ -7,6 +7,7 @@ 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 type { SweepableCurve, RotationAxis } from "./types.js";
@@ -56,6 +57,16 @@ export interface PlanarArc {
   sweepAngle: number;
 }
 
+export interface MeshPlanarFace {
+  index: number;
+  seedTriangleIndex: number;
+  triangleIndices: number[];
+  triangleCount: number;
+  centroid: Point;
+  normal: Vec3;
+  area: number;
+}
+
 interface RawMeshBounds {
   minX: number;
   minY: number;
@@ -177,41 +188,41 @@ export interface MeshBooleanReproPayload {
   error?: MeshBooleanReproError;
 }
 
-export interface MeshBooleanReproOptions {
-  includeResult?: boolean;
-  debugOptions?: MeshBooleanDebugOptions;
-}
-
-export interface MeshSplitResult {
-  outside: Mesh[];
-  inside: Mesh[];
-  all: Mesh[];
-  classification?: "volume" | "surface";
-  negative?: Mesh[];
-  positive?: Mesh[];
-}
-
-export interface MeshPlaneSplitResult extends MeshSplitResult {
-  negative: Mesh[];
-  positive: Mesh[];
-}
-
-export interface MeshPlaneSplitOptions extends MeshBooleanOptions {
-  planePaddingScale?: number;
-}
-
-export interface MeshCurveSplitOptions extends MeshBooleanOptions {
-  /**
-   * Explicit cutter extrusion direction. If omitted, a through-cut is generated
-   * automatically along the detected curve normal across the host mesh.
-   */
-  direction?: Vec3;
-  /**
-   * Tessellation density for curved closed profiles such as circles, polycurves,
-   * and NURBS curves.
-   */
-  curveSegments?: number;
-}
+export interface MeshBooleanReproOptions {
+  includeResult?: boolean;
+  debugOptions?: MeshBooleanDebugOptions;
+}
+
+export interface MeshSplitResult {
+  outside: Mesh[];
+  inside: Mesh[];
+  all: Mesh[];
+  classification?: "volume" | "surface";
+  negative?: Mesh[];
+  positive?: Mesh[];
+}
+
+export interface MeshPlaneSplitResult extends MeshSplitResult {
+  negative: Mesh[];
+  positive: Mesh[];
+}
+
+export interface MeshPlaneSplitOptions extends MeshBooleanOptions {
+  planePaddingScale?: number;
+}
+
+export interface MeshCurveSplitOptions extends MeshBooleanOptions {
+  /**
+   * Explicit cutter extrusion direction. If omitted, a through-cut is generated
+   * automatically along the detected curve normal across the host mesh.
+   */
+  direction?: Vec3;
+  /**
+   * Tessellation density for curved closed profiles such as circles, polycurves,
+   * and NURBS curves.
+   */
+  curveSegments?: number;
+}
 
 function shouldFallbackFromWorkerFailure(error: unknown): boolean {
   if (!error || typeof error !== "object") return false;
@@ -250,6 +261,10 @@ export class Mesh {
   private _indexBuffer: Uint32Array | null = null;
   private _vertices: Point[] | null = null;
   private _faces: number[][] | null = null;
+  private _planarFaces: MeshPlanarFace[] | null = null;
+  private _planarFacesByTriangleIndex: Array<MeshPlanarFace | null> | null = null;
+  private _surfaces: MeshSurface[] | null = null;
+  private _surfacesByTriangleIndex: Array<MeshSurface | null> | null = null;
   private _edgeVertexPairs: Array<[number, number]> | null = null;
   private _topologyMetricsCache: { boundaryEdges: number; nonManifoldEdges: number } | null = null;
   private _isClosedVolumeCache: boolean | null = null;
@@ -339,6 +354,60 @@ export class Mesh {
     return Number.isFinite(diag) && diag > 0 ? diag : 1;
   }
 
+  private static computeSignedVolumeFromBuffer(buffer: Float64Array): number {
+    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;
+  }
+
+  private static reverseTriangleWinding(buffer: Float64Array): Float64Array {
+    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;
+  }
+
+  private static normalizeClosedVolumeOrientation(mesh: Mesh): 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);
+  }
+
   private static booleanContactTolerance(a: RawMeshBounds | null, b: RawMeshBounds | null): number {
     const scale = Math.max(Mesh.boundsDiag(a), Mesh.boundsDiag(b));
     return Math.min(1e-4, Math.max(1e-9, scale * 1e-6));
@@ -673,203 +742,203 @@ export class Mesh {
     });
   }
 
-  private static emptyMesh(): Mesh {
-    return Mesh.fromTrustedBuffer(new Float64Array(0));
-  }
-
-  private static createSplitResult(
-    outside: Mesh[],
-    inside: Mesh[],
-    classification: "volume" | "surface" = "volume",
-  ): MeshSplitResult {
-    const result: MeshSplitResult = {
-      outside,
-      inside,
-      all: outside.concat(inside),
-      classification,
-    };
-    if (classification === "surface") {
-      result.negative = outside;
-      result.positive = inside;
-    }
-    return result;
-  }
-
-  private static createSurfaceSplitResult(negative: Mesh[], positive: Mesh[]): MeshSplitResult {
-    return Mesh.createSplitResult(negative, positive, "surface");
-  }
-
-  private static createPlaneSplitResult(
-    negative: Mesh[],
-    positive: Mesh[],
-    classification: "volume" | "surface" = "surface",
-  ): MeshPlaneSplitResult {
-    return {
-      ...Mesh.createSplitResult(negative, positive, classification),
-      negative,
-      positive,
-    };
-  }
-
-  private static parseSplitResultBuffer(buffer: Float64Array): MeshSplitResult {
-    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: number): Mesh[] => {
-      const meshes: Mesh[] = [];
-      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);
-  }
-
-  private static orthonormalPlaneFrame(plane: Plane): { uAxis: Vec3; vAxis: Vec3; normal: Vec3 } {
-    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 };
-  }
-
-  private static createOrientedBox(
-    center: Point,
-    uAxis: Vec3,
-    vAxis: Vec3,
-    wAxis: Vec3,
-    halfU: number,
-    halfV: number,
-    halfW: number,
-  ): Mesh {
-    const axes = [uAxis.normalize(), vAxis.normalize(), wAxis.normalize()] as const;
-    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 });
-  }
-
-  private static classifyPlaneDistances(mesh: Mesh, plane: Plane): { min: number; max: number } {
-    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 };
-  }
-
-  private static createPlaneHalfSpaceCutter(
-    host: Mesh,
-    plane: Plane,
-    options?: MeshPlaneSplitOptions,
-  ): Mesh {
-    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);
-  }
-
-  private static detectClosedCurveNormal(curve: SweepableCurve, points: Point[]): Vec3 {
-    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;
-  }
-
-  private static createCurveSplitCutter(
-    host: Mesh,
-    curve: SweepableCurve,
-    options?: MeshCurveSplitOptions,
-  ): Mesh {
-    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);
-  }
+  private static emptyMesh(): Mesh {
+    return Mesh.fromTrustedBuffer(new Float64Array(0));
+  }
+
+  private static createSplitResult(
+    outside: Mesh[],
+    inside: Mesh[],
+    classification: "volume" | "surface" = "volume",
+  ): MeshSplitResult {
+    const result: MeshSplitResult = {
+      outside,
+      inside,
+      all: outside.concat(inside),
+      classification,
+    };
+    if (classification === "surface") {
+      result.negative = outside;
+      result.positive = inside;
+    }
+    return result;
+  }
+
+  private static createSurfaceSplitResult(negative: Mesh[], positive: Mesh[]): MeshSplitResult {
+    return Mesh.createSplitResult(negative, positive, "surface");
+  }
+
+  private static createPlaneSplitResult(
+    negative: Mesh[],
+    positive: Mesh[],
+    classification: "volume" | "surface" = "surface",
+  ): MeshPlaneSplitResult {
+    return {
+      ...Mesh.createSplitResult(negative, positive, classification),
+      negative,
+      positive,
+    };
+  }
+
+  private static parseSplitResultBuffer(buffer: Float64Array): MeshSplitResult {
+    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: number): Mesh[] => {
+      const meshes: Mesh[] = [];
+      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);
+  }
+
+  private static orthonormalPlaneFrame(plane: Plane): { uAxis: Vec3; vAxis: Vec3; normal: Vec3 } {
+    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 };
+  }
+
+  private static createOrientedBox(
+    center: Point,
+    uAxis: Vec3,
+    vAxis: Vec3,
+    wAxis: Vec3,
+    halfU: number,
+    halfV: number,
+    halfW: number,
+  ): Mesh {
+    const axes = [uAxis.normalize(), vAxis.normalize(), wAxis.normalize()] as const;
+    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 });
+  }
+
+  private static classifyPlaneDistances(mesh: Mesh, plane: Plane): { min: number; max: number } {
+    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 };
+  }
+
+  private static createPlaneHalfSpaceCutter(
+    host: Mesh,
+    plane: Plane,
+    options?: MeshPlaneSplitOptions,
+  ): Mesh {
+    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);
+  }
+
+  private static detectClosedCurveNormal(curve: SweepableCurve, points: Point[]): Vec3 {
+    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;
+  }
+
+  private static createCurveSplitCutter(
+    host: Mesh,
+    curve: SweepableCurve,
+    options?: MeshCurveSplitOptions,
+  ): Mesh {
+    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 ──────────────────────────────────────────
 
@@ -909,7 +978,7 @@ export class Mesh {
     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(): number {
     const start = 1 + this._vertexCount * 3;
     if (this._buffer.length <= start) return 0;
@@ -937,6 +1006,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(): number[][] {
@@ -951,6 +1021,47 @@ 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(): number[][] {
+    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(): number {
+    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(): MeshPlanarFace[] {
+    this.ensurePlanarFaceCache();
+    return this._planarFaces ?? [];
+  }
+
+  /**
+   * Number of logical planar surfaces in this mesh.
+   * Mirrors `planarFaceCount`, but returns wrapper objects with surface queries.
+   */
+  get surfaceCount(): number {
+    return this.surfaces.length;
+  }
+
+  /**
+   * Logical planar mesh surfaces with `evaluate(u, v)` and `normal(u, v)` methods.
+   */
+  get surfaces(): MeshSurface[] {
+    this.ensureSurfaceCache();
+    return this._surfaces ?? [];
+  }
+
   /** Raw WASM buffer (for advanced use / re-passing to WASM) */
   get rawBuffer(): Float64Array {
     return this._buffer;
@@ -971,13 +1082,134 @@ export class Mesh {
   }
 
   private static fromTrustedBuffer(buffer: Float64Array): Mesh {
-    return new Mesh(buffer, true);
+    return Mesh.normalizeClosedVolumeOrientation(new Mesh(buffer, true));
   }
 
   get trustedBooleanInput(): boolean {
     return this._trustedBooleanInput;
   }
 
+  private getTriangleVertexIndices(faceIndex: number): [number, number, number] | null {
+    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]];
+  }
+
+  private computeTriangleAreaByIndex(faceIndex: number): number {
+    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);
+  }
+
+  private ensurePlanarFaceCache(): void {
+    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: MeshPlanarFace[] = [];
+    const planarFacesByTriangleIndex: Array<MeshPlanarFace | null> = 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: number[] = [];
+      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: MeshPlanarFace = {
+        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;
+  }
+
+  private ensureSurfaceCache(): void {
+    if (this._surfaces && this._surfacesByTriangleIndex) return;
+
+    const surfaces = this.planarFaces.map(face => new MeshSurface(this, face));
+    const surfacesByTriangleIndex: Array<MeshSurface | null> = 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(): MeshDebugSummary {
     const bounds = Mesh.toDebugBounds(this.getBounds());
     const topology = this.topologyMetrics();
@@ -1397,6 +1629,32 @@ export class Mesh {
     return Mesh.fromTrustedBuffer(wasm.loft_polylines(new Float64Array(parts), segments, caps));
   }
 
+  /**
+   * Loft through multiple raw profiles with kernel-managed compatibility:
+   * profiles are resampled to a common point count (uniform arc length), and
+   * closed profiles get seam alignment + winding direction matching so the
+   * loft does not twist.
+   *
+   * @param profiles - Array of point arrays defining cross-sections. Closed
+   *   profiles must NOT repeat the first point at the end.
+   * @param closed - Whether profiles are closed loops (tube) or open rows (sheet)
+   * @param caps - Cap first/last profiles (closed profiles only) to produce a
+   *   watertight solid ready for booleans (default false)
+   * @returns New Mesh representing the lofted surface
+   */
+  static loftProfiles(profiles: Point[][], closed: boolean, caps = false): Mesh {
+    ensureInit();
+    // Format: [count1, x,y,z,..., count2, x,y,z,...]
+    const parts: number[] = [];
+    for (const profile of profiles) {
+      parts.push(profile.length);
+      for (const p of profile) {
+        parts.push(p.x, p.y, p.z);
+      }
+    }
+    return Mesh.fromTrustedBuffer(wasm.loft_profiles(new Float64Array(parts), closed, caps));
+  }
+
   /**
    * Sweep a profile polyline along a path polyline.
    * @param profilePoints - Profile cross-section points
@@ -1816,10 +2074,53 @@ export class Mesh {
     return Mesh.fromTrustedBuffer(result);
   }
 
-  static encodeBooleanOperationToken(
-    operation: MeshBooleanOperation,
-    a: Mesh,
-    b: Mesh,
+  private static mergeMeshComponents(meshes: Mesh[]): Mesh {
+    if (meshes.length === 0) return Mesh.emptyMesh();
+    if (meshes.length === 1) return Mesh.cloneMesh(meshes[0]);
+    return Mesh.mergeMeshes(meshes);
+  }
+
+  private static createUnsupportedOpenMeshBooleanError(
+    operation: MeshBooleanOperation,
+    aClosed: boolean,
+    bClosed: boolean,
+  ): Error {
+    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.",
+    );
+  }
+
+  private resolveOpenMeshBooleanFallback(
+    other: Mesh,
+    operation: MeshBooleanOperation,
+    options?: MeshBooleanOptions,
+  ): Mesh | null {
+    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: MeshBooleanOperation,
+    a: Mesh,
+    b: Mesh,
     options?: MeshBooleanOptions,
   ): string {
     const tokens: string[] = [operation];
@@ -1828,44 +2129,48 @@ export class Mesh {
     }
     if (options?.debugForceFaceID) {
       tokens.push("forceFaceID");
-    }
-    return tokens.join("@");
-  }
-
-  static encodeBooleanSplitToken(
-    a: Mesh,
-    b: Mesh,
-    options?: MeshBooleanOptions,
-  ): string {
-    const tokens: string[] = ["split"];
-    if (a._trustedBooleanInput && b._trustedBooleanInput) {
-      tokens.push("trustedInput");
-    }
-    if (options?.debugForceFaceID) {
-      tokens.push("forceFaceID");
-    }
-    return tokens.join("@");
-  }
+    }
+    return tokens.join("@");
+  }
+
+  static encodeBooleanSplitToken(
+    a: Mesh,
+    b: Mesh,
+    options?: MeshBooleanOptions,
+  ): string {
+    const tokens: string[] = ["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: Mesh, options?: MeshBooleanOptions): Mesh {
     ensureInit();
-    const operationToken = Mesh.encodeBooleanOperationToken("union", this, other, options);
-    return this.runBoolean(
-      other,
+    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(
-        this._vertexCount,
-        this._buffer,
-        other._vertexCount,
-        other._buffer,
+        lhs._vertexCount,
+        lhs._buffer,
+        rhs._vertexCount,
+        rhs._buffer,
         operationToken,
       ),
       options,
@@ -1874,21 +2179,27 @@ export class Mesh {
 
   /**
    * 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: Mesh, options?: MeshBooleanOptions): Mesh {
     ensureInit();
-    const operationToken = Mesh.encodeBooleanOperationToken("subtraction", this, other, options);
-    return this.runBoolean(
-      other,
+    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(
-        this._vertexCount,
-        this._buffer,
-        other._vertexCount,
-        other._buffer,
+        lhs._vertexCount,
+        lhs._buffer,
+        rhs._vertexCount,
+        rhs._buffer,
         operationToken,
       ),
       options,
@@ -1897,179 +2208,185 @@ export class Mesh {
 
   /**
    * 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: Mesh, options?: MeshBooleanOptions): Mesh {
-    ensureInit();
-    const operationToken = Mesh.encodeBooleanOperationToken("intersection", this, other, options);
-    return this.runBoolean(
-      other,
+  intersect(other: Mesh, options?: MeshBooleanOptions): Mesh {
+    ensureInit();
+    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,
+    );
+  }
+
+  private splitWithMesh(other: Mesh, options?: MeshBooleanOptions): MeshSplitResult {
+    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,
-        operationToken,
-      ),
-      options,
-    );
-  }
-
-  private splitWithMesh(other: Mesh, options?: MeshBooleanOptions): MeshSplitResult {
-    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);
-  }
-
-  private splitWithPlane(plane: Plane, options?: MeshPlaneSplitOptions): MeshPlaneSplitResult {
-    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");
-  }
-
-  private splitWithCurve(curve: SweepableCurve, options?: MeshCurveSplitOptions): MeshSplitResult {
-    ensureInit();
-    if (this.faceCount === 0) return Mesh.createSplitResult([], []);
-    const cutter = Mesh.createCurveSplitCutter(this, curve, options);
-    return this.splitWithMesh(cutter, options);
-  }
-
-  /**
-   * Split this mesh by another mesh, a plane, or a closed planar curve.
-   * Mesh split: `outside = this - cutter`, `inside = this ∩ cutter`.
-   * Plane split: `negative` is opposite the plane normal, `positive` follows the plane normal.
-   * Curve split: the curve is converted into a cutter solid, either from the
-   * explicit direction you pass or via an automatic through-cut along the
-   * detected curve normal across the host mesh.
-   */
-  split(other: Mesh, options?: MeshBooleanOptions): MeshSplitResult;
-  split(plane: Plane, options?: MeshPlaneSplitOptions): MeshPlaneSplitResult;
-  split(curve: SweepableCurve, options?: MeshCurveSplitOptions): MeshSplitResult;
-  split(
-    target: Mesh | Plane | SweepableCurve,
-    options?: MeshBooleanOptions | MeshPlaneSplitOptions | MeshCurveSplitOptions,
-  ): MeshSplitResult | MeshPlaneSplitResult {
-    if (target instanceof Mesh) {
-      return this.splitWithMesh(target, options as MeshBooleanOptions | undefined);
-    }
-    if (target instanceof Plane) {
-      return this.splitWithPlane(target, options as MeshPlaneSplitOptions | undefined);
-    }
-    return this.splitWithCurve(target, options as MeshCurveSplitOptions | undefined);
-  }
-
-  debugBoolean(
-    other: Mesh,
-    operation: MeshBooleanOperation,
+        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);
+  }
+
+  private splitWithPlane(plane: Plane, options?: MeshPlaneSplitOptions): MeshPlaneSplitResult {
+    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");
+  }
+
+  private splitWithCurve(curve: SweepableCurve, options?: MeshCurveSplitOptions): MeshSplitResult {
+    ensureInit();
+    if (this.faceCount === 0) return Mesh.createSplitResult([], []);
+    const cutter = Mesh.createCurveSplitCutter(this, curve, options);
+    return this.splitWithMesh(cutter, options);
+  }
+
+  /**
+   * Split this mesh by another mesh, a plane, or a closed planar curve.
+   * Mesh split: `outside = this - cutter`, `inside = this ∩ cutter`.
+   * Plane split: `negative` is opposite the plane normal, `positive` follows the plane normal.
+   * Curve split: the curve is converted into a cutter solid, either from the
+   * explicit direction you pass or via an automatic through-cut along the
+   * detected curve normal across the host mesh.
+   */
+  split(other: Mesh, options?: MeshBooleanOptions): MeshSplitResult;
+  split(plane: Plane, options?: MeshPlaneSplitOptions): MeshPlaneSplitResult;
+  split(curve: SweepableCurve, options?: MeshCurveSplitOptions): MeshSplitResult;
+  split(
+    target: Mesh | Plane | SweepableCurve,
+    options?: MeshBooleanOptions | MeshPlaneSplitOptions | MeshCurveSplitOptions,
+  ): MeshSplitResult | MeshPlaneSplitResult {
+    if (target instanceof Mesh) {
+      return this.splitWithMesh(target, options as MeshBooleanOptions | undefined);
+    }
+    if (target instanceof Plane) {
+      return this.splitWithPlane(target, options as MeshPlaneSplitOptions | undefined);
+    }
+    return this.splitWithCurve(target, options as MeshCurveSplitOptions | undefined);
+  }
+
+  debugBoolean(
+    other: Mesh,
+    operation: MeshBooleanOperation,
     options?: MeshBooleanOptions,
     debugOptions?: MeshBooleanDebugOptions,
   ): MeshBooleanDebugReport {
@@ -2405,6 +2722,71 @@ export class Mesh {
     return out;
   }
 
+  /**
+   * Find the edge-connected smooth face group containing a triangle: flood
+   * fill crossing only edges whose dihedral angle is below `maxAngleDeg`.
+   * On a tessellated curved surface (cylinder wall, lofted patch) this
+   * returns the whole smooth region (`isPlanar: false`); on a flat face it
+   * matches the coplanar group (`isPlanar: true`).
+   */
+  getSmoothFaceGroup(
+    faceIndex: number,
+    maxAngleDeg = 30,
+  ): { faceIndices: number[]; isPlanar: boolean } {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) {
+      return { faceIndices: [], isPlanar: true };
+    }
+    const r = wasm.mesh_get_smooth_face_group(
+      this._vertexCount,
+      this._buffer,
+      Math.floor(faceIndex),
+      maxAngleDeg,
+    );
+    const count = Math.max(0, Math.floor(r[0] ?? 0));
+    const isPlanar = (r[1] ?? 1) !== 0;
+    const faceIndices: number[] = [];
+    for (let i = 0; i < count; i++) {
+      faceIndices.push(Math.floor(r[2 + i] ?? 0));
+    }
+    return { faceIndices, isPlanar };
+  }
+
+  /**
+   * Display-ready render buffers computed in one kernel pass: creased
+   * (crease-split) vertex normals plus feature edge segments. Replaces
+   * per-mesh THREE.toCreasedNormals + EdgesGeometry in app layers.
+   *
+   * `positions`/`normals` are non-indexed, three floats per vertex, in the
+   * mesh's triangle order (raycast face indices stay valid). `featureEdges`
+   * holds two endpoints (six floats) per feature edge segment: boundary
+   * edges, non-manifold edges, and edges whose dihedral angle exceeds
+   * `creaseAngleDeg`.
+   */
+  buildRenderBuffers(creaseAngleDeg = 30): {
+    positions: Float32Array;
+    normals: Float32Array;
+    featureEdges: Float32Array;
+  } {
+    ensureInit();
+    const r: Float32Array = wasm.mesh_build_render_buffers(
+      this._vertexCount,
+      this._buffer,
+      creaseAngleDeg,
+    );
+    const vertexCount = Math.max(0, Math.floor(r[0] ?? 0));
+    const posStart = 1;
+    const norStart = posStart + vertexCount * 3;
+    const edgeCountIndex = norStart + vertexCount * 3;
+    const edgeCount = Math.max(0, Math.floor(r[edgeCountIndex] ?? 0));
+    const edgeStart = edgeCountIndex + 1;
+    return {
+      positions: r.subarray(posStart, posStart + vertexCount * 3),
+      normals: r.subarray(norStart, norStart + vertexCount * 3),
+      featureEdges: r.subarray(edgeStart, edgeStart + edgeCount * 6),
+    };
+  }
+
   /**
    * Coplanar connected face region and its projection bounds on a plane basis.
    * Returns null for invalid inputs or empty regions.
@@ -2629,6 +3011,96 @@ export class Mesh {
     };
   }
 
+  /**
+   * Get a logical planar face by its planar-face index.
+   */
+  getPlanarFace(index: number): MeshPlanarFace | null {
+    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: number): MeshSurface | null {
+    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: number): MeshPlanarFace | null {
+    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: number): MeshSurface | null {
+    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: Vec3, nearPoint?: Point): MeshPlanarFace | null {
+    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: MeshPlanarFace | null = 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: Vec3, nearPoint?: Point): MeshSurface | null {
+    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.
@@ -2641,43 +3113,16 @@ export class Mesh {
   /**
    * Find the coplanar + edge-connected face group containing a triangle.
    */
-  findFaceByTriangleIndex(triangleIndex: number): { centroid: Point; normal: Vec3 } | null {
-    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]),
-    };
+  findFaceByTriangleIndex(triangleIndex: number): MeshPlanarFace | null {
+    return this.getPlanarFaceByTriangleIndex(triangleIndex);
   }
 
   /**
    * Find the best matching coplanar + edge-connected face group by normal
    * similarity and optional point proximity.
    */
-  findFaceByNormal(targetNormal: Vec3, nearPoint?: Point): { centroid: Point; normal: Vec3 } | null {
-    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]),
-    };
+  findFaceByNormal(targetNormal: Vec3, nearPoint?: Point): MeshPlanarFace | null {
+    return this.findPlanarFaceByNormal(targetNormal, nearPoint);
   }
 
   // ── Export ──────────────────────────────────────────────────────