okgeometry-api 1.2.0 → 1.2.1

package/src/Mesh.ts

@@ -5,10 +5,11 @@ 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 { NurbsCurve } from "./NurbsCurve.js";
-import { PolyCurve } from "./PolyCurve.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";
 import { CurveTypeCode, SegmentTypeCode } from "./types.js";
 import { pointsToCoords, parsePolylineBuffer as parsePolylineBuf } from "./BufferCodec.js";
@@ -47,14 +48,24 @@ export interface PlanarCircle {
   radius: number;
 }
 
-export interface PlanarArc {
-  points: Point[];
-  center: Point;
-  radius: number;
-  startAngle: number;
-  endAngle: number;
-  sweepAngle: number;
-}
+export interface PlanarArc {
+  points: Point[];
+  center: Point;
+  radius: number;
+  startAngle: number;
+  endAngle: number;
+  sweepAngle: number;
+}
+
+export interface MeshPlanarFace {
+  index: number;
+  seedTriangleIndex: number;
+  triangleIndices: number[];
+  triangleCount: number;
+  centroid: Point;
+  normal: Vec3;
+  area: number;
+}
 
 interface RawMeshBounds {
   minX: number;
@@ -247,13 +258,17 @@ export class Mesh {
 
   // Lazy caches
   private _positionBuffer: Float32Array | null = null;
-  private _indexBuffer: Uint32Array | null = null;
-  private _vertices: Point[] | null = null;
-  private _faces: number[][] | null = null;
-  private _edgeVertexPairs: Array<[number, number]> | null = null;
-  private _topologyMetricsCache: { boundaryEdges: number; nonManifoldEdges: number } | null = null;
-  private _isClosedVolumeCache: boolean | null = null;
-  private _rawBoundsCache: RawMeshBounds | null | undefined = undefined;
+  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;
+  private _rawBoundsCache: RawMeshBounds | null | undefined = undefined;
 
   private constructor(buffer: Float64Array, trustedBooleanInput = false) {
     this._buffer = buffer;
@@ -330,14 +345,68 @@ export class Mesh {
       && a.maxZ + eps >= b.minZ;
   }
 
-  private static boundsDiag(bounds: RawMeshBounds | null): number {
-    if (!bounds) return 1;
-    const dx = bounds.maxX - bounds.minX;
-    const dy = bounds.maxY - bounds.minY;
-    const dz = bounds.maxZ - bounds.minZ;
-    const diag = Math.hypot(dx, dy, dz);
-    return Number.isFinite(diag) && diag > 0 ? diag : 1;
-  }
+  private static boundsDiag(bounds: RawMeshBounds | null): number {
+    if (!bounds) return 1;
+    const dx = bounds.maxX - bounds.minX;
+    const dy = bounds.maxY - bounds.minY;
+    const dz = bounds.maxZ - bounds.minZ;
+    const diag = Math.hypot(dx, dy, dz);
+    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));
@@ -909,12 +978,12 @@ export class Mesh {
     return this._vertexCount;
   }
 
-  /** Number of triangular faces in this mesh */
-  get faceCount(): number {
-    const start = 1 + this._vertexCount * 3;
-    if (this._buffer.length <= start) return 0;
-    return Math.floor((this._buffer.length - start) / 3);
-  }
+  /** 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;
+    return Math.floor((this._buffer.length - start) / 3);
+  }
 
   // ── High-level accessors (lazy) ────────────────────────────────
 
@@ -934,22 +1003,64 @@ export class Mesh {
     return this._vertices;
   }
 
-  /**
-   * Get all faces as arrays of vertex indices.
-   * Each face is [i0, i1, i2] for the three triangle vertices.
-   * Lazy-computed and cached.
-   */
-  get faces(): number[][] {
-    if (!this._faces) {
-      const idx = this.indexBuffer;
+  /**
+   * 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[][] {
+    if (!this._faces) {
+      const idx = this.indexBuffer;
       const f: number[][] = [];
       for (let i = 0; i < idx.length; i += 3) {
         f.push([idx[i], idx[i + 1], idx[i + 2]]);
       }
       this._faces = f;
-    }
-    return this._faces;
-  }
+    }
+    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 {
@@ -963,25 +1074,146 @@ export class Mesh {
    * @param buffer - Float64Array in mesh buffer format
    * @returns New Mesh instance
    */
-  static fromBuffer(
-    buffer: Float64Array,
-    options?: { trustedBooleanInput?: boolean },
-  ): Mesh {
-    return new Mesh(buffer, options?.trustedBooleanInput ?? false);
-  }
-
-  private static fromTrustedBuffer(buffer: Float64Array): Mesh {
-    return new Mesh(buffer, true);
-  }
+  static fromBuffer(
+    buffer: Float64Array,
+    options?: { trustedBooleanInput?: boolean },
+  ): Mesh {
+    return new Mesh(buffer, options?.trustedBooleanInput ?? false);
+  }
+
+  private static fromTrustedBuffer(buffer: Float64Array): Mesh {
+    return Mesh.normalizeClosedVolumeOrientation(new Mesh(buffer, true));
+  }
 
-  get trustedBooleanInput(): boolean {
-    return this._trustedBooleanInput;
-  }
+  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();
-    return {
+  debugSummary(): MeshDebugSummary {
+    const bounds = Mesh.toDebugBounds(this.getBounds());
+    const topology = this.topologyMetrics();
+    return {
       vertexCount: this.vertexCount,
       faceCount: this.faceCount,
       trustedBooleanInput: this._trustedBooleanInput,
@@ -1759,11 +1991,11 @@ export class Mesh {
     return Mesh.fromTrustedBuffer(wasm.mesh_scale(this._vertexCount, this._buffer, sx, sy, sz));
   }
 
-  private runBoolean(
-    other: Mesh,
-    operation: "union" | "subtraction" | "intersection",
-    invoke: () => Float64Array,
-    options?: MeshBooleanOptions,
+  private runBoolean(
+    other: Mesh,
+    operation: "union" | "subtraction" | "intersection",
+    invoke: () => Float64Array,
+    options?: MeshBooleanOptions,
   ): Mesh {
     const faceCountA = this.faceCount;
     const faceCountB = other.faceCount;
@@ -1812,10 +2044,53 @@ export class Mesh {
     const vertexCount = result[0];
     if (!Number.isFinite(vertexCount) || vertexCount < 0) {
       throw new Error(`Boolean ${operation} failed and returned a corrupt mesh buffer.`);
-    }
-    return Mesh.fromTrustedBuffer(result);
-  }
-
+    }
+    return Mesh.fromTrustedBuffer(result);
+  }
+
+  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,
@@ -1849,71 +2124,87 @@ export class Mesh {
 
   // ── Booleans ───────────────────────────────────────────────────
 
-  /**
-   * Compute boolean union with another mesh.
-   * @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,
-      "union",
-      () => wasm.mesh_boolean_operation(
-        this._vertexCount,
-        this._buffer,
-        other._vertexCount,
-        other._buffer,
-        operationToken,
-      ),
-      options,
-    );
-  }
+  /**
+   * 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 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.
-   * @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,
-      "subtraction",
-      () => wasm.mesh_boolean_operation(
-        this._vertexCount,
-        this._buffer,
-        other._vertexCount,
-        other._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: Mesh, options?: MeshBooleanOptions): Mesh {
+    ensureInit();
+    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.
-   * @param other - Mesh to intersect with
-   * @param options - Optional safety overrides
-   * @returns New mesh containing only the overlapping volume
-   */
+  /**
+   * 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,
-      "intersection",
-      () => wasm.mesh_boolean_operation(
-        this._vertexCount,
-        this._buffer,
-        other._vertexCount,
-        other._buffer,
-        operationToken,
-      ),
+    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,
     );
   }
@@ -2451,9 +2742,9 @@ export class Mesh {
   /**
    * Centroid of the coplanar edge-connected face group containing faceIndex.
    */
-  getCoplanarFaceGroupCentroid(faceIndex: number): Point | null {
-    ensureInit();
-    if (!Number.isFinite(faceIndex) || faceIndex < 0) return null;
+  getCoplanarFaceGroupCentroid(faceIndex: number): Point | null {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return null;
     const r = wasm.mesh_get_coplanar_face_group_centroid(
       this._vertexCount,
       this._buffer,
@@ -2623,62 +2914,125 @@ export class Mesh {
     if (this._isClosedVolumeCache === null) {
       this._isClosedVolumeCache = boundaryEdges === 0;
     }
-    return {
-      boundaryEdges,
-      nonManifoldEdges,
-    };
-  }
-
-  /**
-   * Odd/even point containment test against a closed mesh.
-   * Uses majority vote across multiple ray directions for robustness.
+    return {
+      boundaryEdges,
+      nonManifoldEdges,
+    };
+  }
+
+  /**
+   * 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.
    */
   containsPoint(point: Point): boolean {
     ensureInit();
     return wasm.mesh_contains_point(this._vertexCount, this._buffer, point.x, point.y, point.z);
   }
 
-  /**
-   * 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]),
-    };
-  }
-
-  /**
-   * 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]),
-    };
-  }
+  /**
+   * Find the coplanar + edge-connected face group containing a triangle.
+   */
+  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): MeshPlanarFace | null {
+    return this.findPlanarFaceByNormal(targetNormal, nearPoint);
+  }
 
   // ── Export ──────────────────────────────────────────────────────