okgeometry-api 0.5.0 → 0.5.2

package/src/Mesh.ts

@@ -0,0 +1,1476 @@
+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 { 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";
+import {
+  configureDefaultMeshBooleanWorkerPool,
+  disposeMeshBooleanWorkerPools,
+  runMeshBooleanInWorkerPool,
+} from "./mesh-boolean.pool.js";
+import { MeshBooleanExecutionError } from "./mesh-boolean.protocol.js";
+import type {
+  MeshBooleanAsyncOptions,
+  MeshBooleanBackend,
+  MeshBooleanLimits,
+  MeshBooleanOptions,
+} from "./mesh-boolean.protocol.js";
+import * as wasm from "../wasm/okgeometrycore_bg.js";
+
+export { MeshBooleanExecutionError };
+export type {
+  MeshBooleanAsyncOptions,
+  MeshBooleanBackend,
+  MeshBooleanLimits,
+  MeshBooleanOptions,
+  MeshBooleanErrorCode,
+  MeshBooleanErrorPayload,
+  MeshBooleanProgressEvent,
+} from "./mesh-boolean.protocol.js";
+
+export interface PlanarRectangle {
+  corners: [Point, Point, Point, Point];
+  width: number;
+  height: number;
+}
+
+export interface PlanarCircle {
+  points: Point[];
+  radius: number;
+}
+
+export interface PlanarArc {
+  points: Point[];
+  center: Point;
+  radius: number;
+  startAngle: number;
+  endAngle: number;
+  sweepAngle: number;
+}
+
+interface RawMeshBounds {
+  minX: number;
+  minY: number;
+  minZ: number;
+  maxX: number;
+  maxY: number;
+  maxZ: number;
+}
+
+/**
+ * Buffer-backed triangle mesh with GPU-ready accessors.
+ * All geometry lives in a Float64Array from WASM.
+ *
+ * Buffer format: [vertexCount, x1,y1,z1, ..., i1,i2,i3, ...]
+ */
+export class Mesh {
+  private _buffer: Float64Array;
+  private _vertexCount: number;
+
+  private static readonly DEFAULT_BOOLEAN_LIMITS: MeshBooleanLimits = {
+    maxInputFacesPerMesh: 120_000,
+    maxCombinedInputFaces: 180_000,
+    maxFaceProduct: 500_000_000,
+  };
+
+  // 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 constructor(buffer: Float64Array) {
+    this._buffer = buffer;
+    this._vertexCount = buffer.length > 0 ? buffer[0] : 0;
+  }
+
+  /**
+   * Configure default size for the shared boolean worker pool.
+   */
+  static configureBooleanWorkerPool(options: { size: number }): void {
+    configureDefaultMeshBooleanWorkerPool(options);
+  }
+
+  /**
+   * Dispose all shared boolean worker pools.
+   */
+  static disposeBooleanWorkerPools(): void {
+    disposeMeshBooleanWorkerPools();
+  }
+
+  private static resolveBooleanLimits(
+    overrides?: Partial<MeshBooleanLimits>,
+  ): MeshBooleanLimits {
+    const defaults = Mesh.DEFAULT_BOOLEAN_LIMITS;
+    return {
+      maxInputFacesPerMesh: overrides?.maxInputFacesPerMesh ?? defaults.maxInputFacesPerMesh,
+      maxCombinedInputFaces: overrides?.maxCombinedInputFaces ?? defaults.maxCombinedInputFaces,
+      maxFaceProduct: overrides?.maxFaceProduct ?? defaults.maxFaceProduct,
+    };
+  }
+
+  private static computeRawBounds(mesh: Mesh): RawMeshBounds | null {
+    if (mesh._vertexCount <= 0) return null;
+
+    const data = mesh._buffer;
+    const limit = 1 + mesh._vertexCount * 3;
+
+    let minX = data[1];
+    let minY = data[2];
+    let minZ = data[3];
+    let maxX = minX;
+    let maxY = minY;
+    let maxZ = minZ;
+
+    for (let i = 4; i < limit; i += 3) {
+      const x = data[i];
+      const y = data[i + 1];
+      const z = data[i + 2];
+      if (x < minX) minX = x;
+      if (y < minY) minY = y;
+      if (z < minZ) minZ = z;
+      if (x > maxX) maxX = x;
+      if (y > maxY) maxY = y;
+      if (z > maxZ) maxZ = z;
+    }
+
+    return { minX, minY, minZ, maxX, maxY, maxZ };
+  }
+
+  private static boundsOverlap(a: RawMeshBounds | null, b: RawMeshBounds | null, eps = 1e-9): boolean {
+    if (!a || !b) return false;
+    return a.minX <= b.maxX + eps
+      && a.maxX + eps >= b.minX
+      && a.minY <= b.maxY + eps
+      && a.maxY + eps >= b.minY
+      && a.minZ <= b.maxZ + eps
+      && a.maxZ + eps >= b.minZ;
+  }
+
+  private static cloneMesh(mesh: Mesh): Mesh {
+    return Mesh.fromBuffer(new Float64Array(mesh._buffer));
+  }
+
+  private static emptyMesh(): Mesh {
+    return Mesh.fromBuffer(new Float64Array(0));
+  }
+
+  // ── GPU-ready buffers ──────────────────────────────────────────
+
+  /**
+   * Float32 xyz positions for Three.js BufferGeometry.
+   * Lazy-computed and cached.
+   */
+  get positionBuffer(): Float32Array {
+    if (!this._positionBuffer) {
+      const n = this._vertexCount * 3;
+      this._positionBuffer = new Float32Array(n);
+      for (let i = 0; i < n; i++) {
+        this._positionBuffer[i] = this._buffer[1 + i];
+      }
+    }
+    return this._positionBuffer;
+  }
+
+  /**
+   * Uint32 triangle indices for Three.js BufferGeometry.setIndex.
+   * Lazy-computed and cached.
+   */
+  get indexBuffer(): Uint32Array {
+    if (!this._indexBuffer) {
+      const start = 1 + this._vertexCount * 3;
+      const len = Math.max(0, this._buffer.length - start);
+      this._indexBuffer = new Uint32Array(len);
+      for (let i = 0; i < len; i++) {
+        this._indexBuffer[i] = this._buffer[start + i];
+      }
+    }
+    return this._indexBuffer;
+  }
+
+  /** Number of vertices in this mesh */
+  get vertexCount(): number {
+    return this._vertexCount;
+  }
+
+  /** Number of triangular faces in this mesh */
+  get faceCount(): number {
+    return this.indexBuffer.length / 3;
+  }
+
+  // ── High-level accessors (lazy) ────────────────────────────────
+
+  /**
+   * Get all vertices as Point objects.
+   * Lazy-computed and cached.
+   */
+  get vertices(): Point[] {
+    if (!this._vertices) {
+      const pts: Point[] = [];
+      for (let i = 0; i < this._vertexCount; i++) {
+        const off = 1 + i * 3;
+        pts.push(new Point(this._buffer[off], this._buffer[off + 1], this._buffer[off + 2]));
+      }
+      this._vertices = pts;
+    }
+    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;
+      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;
+  }
+
+  /** Raw WASM buffer (for advanced use / re-passing to WASM) */
+  get rawBuffer(): Float64Array {
+    return this._buffer;
+  }
+
+  // ── Static factories ───────────────────────────────────────────
+
+  /**
+   * Create a Mesh from a raw WASM buffer.
+   * @param buffer - Float64Array in mesh buffer format
+   * @returns New Mesh instance
+   */
+  static fromBuffer(buffer: Float64Array): Mesh {
+    return new Mesh(buffer);
+  }
+
+  /**
+   * Build an axis-aligned rectangle on a plane basis from opposite corners.
+   * The resulting corners are ordered [p0, p1, p2, p3] and form a closed loop.
+   */
+  static buildPlanarRectangle(
+    startPoint: Point,
+    endPoint: Point,
+    uAxis: Vec3,
+    vAxis: Vec3,
+  ): PlanarRectangle {
+    const delta = endPoint.sub(startPoint);
+    const uLen = delta.dot(uAxis);
+    const vLen = delta.dot(vAxis);
+
+    const p0 = startPoint;
+    const p1 = startPoint.add(uAxis.scale(uLen));
+    const p3 = startPoint.add(vAxis.scale(vLen));
+    const p2 = p1.add(vAxis.scale(vLen));
+
+    return {
+      corners: [p0, p1, p2, p3],
+      width: Math.abs(uLen),
+      height: Math.abs(vLen),
+    };
+  }
+
+  /**
+   * Build a planar circle from center and a point on/near its radius direction.
+   * Radius is measured in the plane orthogonal to `normal`.
+   */
+  static buildPlanarCircle(
+    center: Point,
+    radiusPoint: Point,
+    normal: Vec3,
+    segments = 64,
+  ): PlanarCircle {
+    const n = normal.normalize();
+    const radial = radiusPoint.sub(center);
+    const radialInPlane = radial.sub(n.scale(radial.dot(n)));
+    const radius = radialInPlane.length();
+
+    if (radius < 1e-12 || segments < 3) {
+      return { points: [], radius: 0 };
+    }
+
+    const circle = new Circle(center, radius, n);
+    return {
+      points: circle.sample(Math.floor(segments)),
+      radius,
+    };
+  }
+
+  /**
+   * Build a planar arc from center, start, and end points.
+   * Uses the shortest signed sweep between start and end around `normal`.
+   */
+  static buildPlanarArcCenterStartEnd(
+    center: Point,
+    startPoint: Point,
+    endPoint: Point,
+    normal: Vec3,
+    segments = 64,
+  ): PlanarArc {
+    const n = normal.normalize();
+    const minSegments = Math.max(2, Math.floor(segments));
+
+    const startRaw = startPoint.sub(center);
+    const endRaw = endPoint.sub(center);
+    const startVec = startRaw.sub(n.scale(startRaw.dot(n)));
+    const endVec = endRaw.sub(n.scale(endRaw.dot(n)));
+
+    const radius = startVec.length();
+    const endLen = endVec.length();
+
+    if (radius < 1e-12 || endLen < 1e-12) {
+      return {
+        points: [],
+        center,
+        radius: 0,
+        startAngle: 0,
+        endAngle: 0,
+        sweepAngle: 0,
+      };
+    }
+
+    const basis = Mesh.resolveArcBasis(center, radius, n);
+    const startAngle = Mesh.angleOnBasis(startVec, basis.uAxis, basis.vAxis);
+    const endAngleRaw = Mesh.angleOnBasis(endVec.scale(radius / endLen), basis.uAxis, basis.vAxis);
+    const sweepAngle = Mesh.normalizeSignedAngle(endAngleRaw - startAngle);
+    if (Math.abs(sweepAngle) < 1e-9) {
+      return {
+        points: [],
+        center,
+        radius: 0,
+        startAngle: 0,
+        endAngle: 0,
+        sweepAngle: 0,
+      };
+    }
+
+    const endAngle = startAngle + sweepAngle;
+    const arc = new Arc(center, radius, startAngle, endAngle, n);
+    return {
+      points: arc.sample(minSegments),
+      center,
+      radius,
+      startAngle,
+      endAngle,
+      sweepAngle,
+    };
+  }
+
+  /**
+   * Build a planar arc from start/end points and a radius control point.
+   * Radius is measured from start point to radiusPoint in the active plane.
+   * The best of 4 candidates (2 centers x minor/major sweeps) is selected by
+   * midpoint proximity to radiusPoint.
+   */
+  static buildPlanarArcStartEndRadius(
+    startPoint: Point,
+    endPoint: Point,
+    radiusPoint: Point,
+    normal: Vec3,
+    segments = 64,
+  ): PlanarArc | null {
+    const n = normal.normalize();
+    const minSegments = Math.max(2, Math.floor(segments));
+    const start = Mesh.projectPointToPlane(startPoint, startPoint, n);
+    const end = Mesh.projectPointToPlane(endPoint, startPoint, n);
+    const guide = Mesh.projectPointToPlane(radiusPoint, startPoint, n);
+
+    const chord = end.sub(start);
+    const chordLength = chord.length();
+    if (chordLength < 1e-9) {
+      return null;
+    }
+
+    const radius = guide.sub(start).length();
+    const halfChord = chordLength * 0.5;
+    if (!Number.isFinite(radius) || radius < halfChord + 1e-9) {
+      return null;
+    }
+
+    const chordDir = chord.scale(1 / chordLength);
+    const perpRaw = n.cross(chordDir);
+    const perpLen = perpRaw.length();
+    if (perpLen < 1e-12) {
+      return null;
+    }
+    const perp = perpRaw.scale(1 / perpLen);
+
+    const hSq = radius * radius - halfChord * halfChord;
+    if (hSq < 0) {
+      return null;
+    }
+    const h = Math.sqrt(Math.max(0, hSq));
+    const mid = start.add(chord.scale(0.5));
+    const centers = [mid.add(perp.scale(h)), mid.add(perp.scale(-h))];
+
+    type ArcCandidate = {
+      center: Point;
+      radius: number;
+      startAngle: number;
+      endAngle: number;
+      sweepAngle: number;
+      points: Point[];
+      score: number;
+    };
+    const candidates: ArcCandidate[] = [];
+
+    for (const center of centers) {
+      const startVec = start.sub(center);
+      const endVec = end.sub(center);
+      if (startVec.length() < 1e-12 || endVec.length() < 1e-12) {
+        continue;
+      }
+
+      const basis = Mesh.resolveArcBasis(center, radius, n);
+      const startAngle = Mesh.angleOnBasis(startVec, basis.uAxis, basis.vAxis);
+      const endAngleRaw = Mesh.angleOnBasis(endVec, basis.uAxis, basis.vAxis);
+      const minorSweep = Mesh.normalizeSignedAngle(endAngleRaw - startAngle);
+      if (Math.abs(minorSweep) < 1e-9) {
+        continue;
+      }
+
+      // Keep this mode on the minor arc branch for stable radius editing.
+      const sweepAngle = minorSweep;
+      const endAngle = startAngle + sweepAngle;
+      const arc = new Arc(center, radius, startAngle, endAngle, n);
+      const midPoint = arc.pointAt(0.5);
+      candidates.push({
+        center,
+        radius,
+        startAngle,
+        endAngle,
+        sweepAngle,
+        points: arc.sample(minSegments),
+        score: midPoint.distanceTo(guide),
+      });
+    }
+
+    if (candidates.length === 0) {
+      return null;
+    }
+
+    candidates.sort((a, b) => a.score - b.score);
+    const winner = candidates[0];
+    return {
+      points: winner.points,
+      center: winner.center,
+      radius: winner.radius,
+      startAngle: winner.startAngle,
+      endAngle: winner.endAngle,
+      sweepAngle: winner.sweepAngle,
+    };
+  }
+
+  private static resolveArcBasis(
+    center: Point,
+    radius: number,
+    normal: Vec3,
+  ): { uAxis: Vec3; vAxis: Vec3 } {
+    if (radius > 1e-12) {
+      const circle = new Circle(center, radius, normal);
+      const p0 = circle.pointAt(0);
+      const pQuarter = circle.pointAt(0.25);
+      const uRaw = p0.sub(center);
+      const vRaw = pQuarter.sub(center);
+      const uLen = uRaw.length();
+      const vLen = vRaw.length();
+      if (uLen > 1e-12 && vLen > 1e-12) {
+        return {
+          uAxis: uRaw.scale(1 / uLen),
+          vAxis: vRaw.scale(1 / vLen),
+        };
+      }
+    }
+
+    const n = normal.normalize();
+    const reference = Math.abs(n.z) < 0.9 ? Vec3.Z : Vec3.X;
+    const uRaw = n.cross(reference);
+    const uLen = uRaw.length();
+    if (uLen < 1e-12) {
+      return { uAxis: Vec3.X, vAxis: Vec3.Y };
+    }
+    const uAxis = uRaw.scale(1 / uLen);
+    const vRaw = n.cross(uAxis);
+    const vLen = vRaw.length();
+    if (vLen < 1e-12) {
+      return { uAxis, vAxis: Vec3.Y };
+    }
+    return { uAxis, vAxis: vRaw.scale(1 / vLen) };
+  }
+
+  private static angleOnBasis(vector: Vec3, uAxis: Vec3, vAxis: Vec3): number {
+    return Math.atan2(vector.dot(vAxis), vector.dot(uAxis));
+  }
+
+  private static normalizeSignedAngle(angle: number): number {
+    const twoPi = Math.PI * 2;
+    let wrapped = angle % twoPi;
+    if (wrapped <= -Math.PI) {
+      wrapped += twoPi;
+    } else if (wrapped > Math.PI) {
+      wrapped -= twoPi;
+    }
+    return wrapped;
+  }
+
+  private static projectPointToPlane(point: Point, planeOrigin: Point, planeNormal: Vec3): Point {
+    const offset = point.sub(planeOrigin);
+    const projected = offset.sub(planeNormal.scale(offset.dot(planeNormal)));
+    return planeOrigin.add(projected);
+  }
+
+  /**
+   * Create a planar patch mesh from boundary points using CDT (Constrained Delaunay Triangulation).
+   * Correctly handles both convex and concave polygons.
+   * @param pts - Ordered boundary points defining a closed polygon (minimum 3)
+   * @returns New Mesh triangulating the polygon interior
+   */
+  static patchFromPoints(pts: Point[]): Mesh {
+    ensureInit();
+    const coords = pointsToCoords(pts);
+    const buf = wasm.mesh_patch_from_points(coords);
+    return new Mesh(buf);
+  }
+
+  /**
+   * Create an axis-aligned box centered at origin.
+   * @param width - Size along X axis
+   * @param height - Size along Y axis
+   * @param depth - Size along Z axis
+   * @returns New Mesh with 8 vertices and 12 triangles
+   */
+  static createBox(width: number, height: number, depth: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_create_box(width, height, depth));
+  }
+
+  /**
+   * Create a UV sphere centered at origin.
+   * @param radius - Sphere radius
+   * @param segments - Number of longitudinal segments
+   * @param rings - Number of latitudinal rings
+   * @returns New Mesh representing the sphere
+   */
+  static createSphere(radius: number, segments: number, rings: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_create_sphere(radius, segments, rings));
+  }
+
+  /**
+   * Create a cylinder centered at origin with axis along Y.
+   * @param radius - Cylinder radius
+   * @param height - Total height (extends height/2 above and below origin)
+   * @param segments - Number of circumferential segments
+   * @returns New Mesh with caps
+   */
+  static createCylinder(radius: number, height: number, segments: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_create_cylinder(radius, height, segments));
+  }
+
+  /**
+   * Create a regular prism centered at origin.
+   * @param radius - Circumradius of the base polygon
+   * @param height - Total height
+   * @param sides - Number of sides (3 = triangular prism, 6 = hexagonal, etc.)
+   * @returns New Mesh with caps
+   */
+  static createPrism(radius: number, height: number, sides: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_create_prism(radius, height, sides));
+  }
+
+  /**
+   * Create a cone centered at origin with apex at top.
+   * @param radius - Base radius
+   * @param height - Height from base to apex
+   * @param segments - Number of circumferential segments
+   * @returns New Mesh with base cap
+   */
+  static createCone(radius: number, height: number, segments: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_create_cone(radius, height, segments));
+  }
+
+  /**
+   * Import a mesh from OBJ format string.
+   * @param objString - OBJ file content
+   * @returns New Mesh parsed from OBJ
+   */
+  static fromOBJ(objString: string): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_import_obj(objString));
+  }
+
+  /**
+   * Loft through multiple circles to create a surface of revolution.
+   * @param circles - Array of circle definitions (center, normal, radius)
+   * @param segments - Number of circumferential segments
+   * @param caps - Whether to cap the ends (default false)
+   * @returns New Mesh representing the lofted surface
+   */
+  static loftCircles(
+    circles: Array<{ center: Point; normal?: { x: number; y: number; z: number }; radius: number }>,
+    segments: number,
+    caps = false
+  ): Mesh {
+    ensureInit();
+    const data = new Float64Array(circles.length * 7);
+    for (let i = 0; i < circles.length; i++) {
+      const c = circles[i];
+      const off = i * 7;
+      data[off] = c.center.x;
+      data[off + 1] = c.center.y;
+      data[off + 2] = c.center.z;
+      data[off + 3] = c.normal?.x ?? 0;
+      data[off + 4] = c.normal?.y ?? 1;
+      data[off + 5] = c.normal?.z ?? 0;
+      data[off + 6] = c.radius;
+    }
+    return new Mesh(wasm.loft_circles(data, segments, caps));
+  }
+
+  /**
+   * Loft through multiple polylines to create a ruled surface.
+   * @param polylines - Array of point arrays defining cross-sections
+   * @param segments - Interpolation segments between sections
+   * @param caps - Whether to cap the ends (default false)
+   * @returns New Mesh representing the lofted surface
+   */
+  static loftPolylines(polylines: Point[][], segments: number, caps = false): Mesh {
+    ensureInit();
+    // Format: [count1, x,y,z,..., count2, x,y,z,...]
+    const parts: number[] = [];
+    for (const pl of polylines) {
+      parts.push(pl.length);
+      for (const p of pl) {
+        parts.push(p.x, p.y, p.z);
+      }
+    }
+    return new Mesh(wasm.loft_polylines(new Float64Array(parts), segments, caps));
+  }
+
+  /**
+   * Sweep a profile polyline along a path polyline.
+   * @param profilePoints - Profile cross-section points
+   * @param pathPoints - Path points to sweep along
+   * @param caps - Whether to cap the ends (default false)
+   * @returns New Mesh representing the swept surface
+   */
+  static sweep(profilePoints: Point[], pathPoints: Point[], caps = false): Mesh {
+    ensureInit();
+    return new Mesh(wasm.sweep_polylines(pointsToCoords(profilePoints), pointsToCoords(pathPoints), caps));
+  }
+
+  /**
+   * Compute a stable planar normal from ordered curve points.
+   * Closed curves use Newell's method; open curves use first non-collinear triple.
+   */
+  static computePlanarCurveNormal(points: Point[], closed: boolean): Vec3 {
+    ensureInit();
+    const r = wasm.mesh_compute_planar_curve_normal(pointsToCoords(points), closed);
+    return new Vec3(r[0] ?? 0, r[1] ?? 1, r[2] ?? 0);
+  }
+
+  /**
+   * Extrude a planar curve along a direction.
+   * Open curves return an uncapped polysurface; closed curves are capped solids.
+   */
+  static extrudePlanarCurve(points: Point[], normal: Vec3, height: number, closed: boolean): Mesh {
+    ensureInit();
+    const buf = wasm.mesh_extrude_planar_curve(
+      pointsToCoords(points),
+      normal.x, normal.y, normal.z,
+      height,
+      closed,
+    );
+    return Mesh.fromBuffer(buf);
+  }
+
+  /**
+   * Shift a closed cutter profile slightly opposite to travel direction and
+   * compensate height so the distal end remains at the user-intended depth.
+   */
+  static prepareBooleanCutterCurve(
+    points: Point[],
+    closed: boolean,
+    normal: Vec3,
+    height: number,
+  ): { points: Point[]; height: number; epsilon: number } {
+    ensureInit();
+    const buf = wasm.mesh_prepare_boolean_cutter_curve(
+      pointsToCoords(points),
+      closed,
+      normal.x, normal.y, normal.z,
+      height,
+    );
+    const outHeight = buf[0] ?? height;
+    const epsilon = buf[1] ?? 0;
+    const count = Math.max(0, Math.floor(buf[2] ?? 0));
+    const shifted: Point[] = [];
+    let off = 3;
+    for (let i = 0; i < count; i++) {
+      shifted.push(new Point(buf[off], buf[off + 1], buf[off + 2]));
+      off += 3;
+    }
+    return { points: shifted, height: outHeight, epsilon };
+  }
+
+  /**
+   * Sweep any curve type along any curve type.
+   * Passes exact curve data to WASM for native evaluation (no pre-sampling).
+   * @param profile - Profile curve (cross-section)
+   * @param path - Path curve to sweep along
+   * @param segments - Number of samples along path (default 32)
+   * @param caps - Whether to cap the ends (default false)
+   * @returns New Mesh representing the swept surface
+   */
+  static sweepCurves(profile: SweepableCurve, path: SweepableCurve, segments = 32, caps = false): Mesh {
+    ensureInit();
+    const profileData = Mesh.encodeCurve(profile);
+    const pathData = Mesh.encodeCurve(path);
+    return new Mesh(wasm.sweep_curves(profileData, pathData, segments, segments, caps));
+  }
+
+  /** Encode a curve into the WASM format for sweep_curves. */
+  private static encodeCurve(curve: SweepableCurve): Float64Array {
+    if (curve instanceof Line) {
+      return new Float64Array([CurveTypeCode.Line,
+        curve.start.x, curve.start.y, curve.start.z,
+        curve.end.x, curve.end.y, curve.end.z]);
+    }
+    if (curve instanceof Circle) {
+      // Include uAxis if present (11 floats), otherwise just 8
+      if (curve.uAxis) {
+        return new Float64Array([CurveTypeCode.Circle,
+          curve.center.x, curve.center.y, curve.center.z,
+          curve.normal.x, curve.normal.y, curve.normal.z,
+          curve.radius,
+          curve.uAxis.x, curve.uAxis.y, curve.uAxis.z]);
+      } else {
+        return new Float64Array([CurveTypeCode.Circle,
+          curve.center.x, curve.center.y, curve.center.z,
+          curve.normal.x, curve.normal.y, curve.normal.z,
+          curve.radius]);
+      }
+    }
+    if (curve instanceof Arc) {
+      return new Float64Array([CurveTypeCode.Arc,
+        curve.center.x, curve.center.y, curve.center.z,
+        curve.normal.x, curve.normal.y, curve.normal.z,
+        curve.radius, curve.startAngle, curve.endAngle]);
+    }
+    if (curve instanceof Polygon || curve instanceof Polyline) {
+      const pts = curve.points;
+      const coords = pointsToCoords(pts);
+      const data = new Float64Array(2 + coords.length);
+      data[0] = CurveTypeCode.Polyline;
+      data[1] = pts.length;
+      data.set(coords, 2);
+      return data;
+    }
+    if (curve instanceof NurbsCurve) {
+      const n = curve.controlPoints.length;
+      const data = new Float64Array(3 + n * 3 + curve.weights.length + curve.knots.length);
+      data[0] = CurveTypeCode.NurbsCurve;
+      data[1] = curve.degree;
+      data[2] = n;
+      let idx = 3;
+      for (const p of curve.controlPoints) { data[idx++] = p.x; data[idx++] = p.y; data[idx++] = p.z; }
+      for (const w of curve.weights) data[idx++] = w;
+      for (const k of curve.knots) data[idx++] = k;
+      return data;
+    }
+    if (curve instanceof PolyCurve) {
+      const parts: number[] = [CurveTypeCode.PolyCurve, curve.segments.length];
+      for (const seg of curve.segments) {
+        if (seg instanceof Line) {
+          parts.push(SegmentTypeCode.Line, seg.start.x, seg.start.y, seg.start.z, seg.end.x, seg.end.y, seg.end.z);
+        } else {
+          parts.push(CurveTypeCode.Arc, seg.center.x, seg.center.y, seg.center.z,
+            seg.normal.x, seg.normal.y, seg.normal.z,
+            seg.radius, seg.startAngle, seg.endAngle);
+        }
+      }
+      return new Float64Array(parts);
+    }
+    // Fallback: sample to polyline
+    const pts: Point[] = [];
+    for (let i = 0; i <= 32; i++) pts.push((curve as any).pointAt(i / 32));
+    const coords = pointsToCoords(pts);
+    const data = new Float64Array(2 + coords.length);
+    data[0] = CurveTypeCode.Polyline;
+    data[1] = pts.length;
+    data.set(coords, 2);
+    return data;
+  }
+  private static mergeMeshes(meshes: Mesh[]): Mesh {
+    ensureInit();
+    const packed = Mesh.packMeshes(meshes);
+    return Mesh.fromBuffer(wasm.mesh_merge(packed));
+  }
+
+  /**
+   * Raycast against many meshes and return all hits sorted by distance.
+   */
+  static raycastMany(
+    meshes: Mesh[],
+    origin: Point,
+    direction: Vec3,
+    maxDistance = Number.POSITIVE_INFINITY,
+  ): Array<{ meshIndex: number; point: Point; normal: Vec3; faceIndex: number; distance: number }> {
+    ensureInit();
+    if (meshes.length === 0) return [];
+
+    const packed = Mesh.packMeshes(meshes);
+    const raycastMany = (wasm as unknown as {
+      mesh_raycast_many: (
+        meshData: Float64Array,
+        ox: number, oy: number, oz: number,
+        dx: number, dy: number, dz: number,
+        maxDistance: number,
+      ) => Float64Array;
+    }).mesh_raycast_many;
+    const buf = raycastMany(
+      packed,
+      origin.x, origin.y, origin.z,
+      direction.x, direction.y, direction.z,
+      maxDistance,
+    );
+    const count = Math.max(0, Math.floor(buf[0] ?? 0));
+    const hits: Array<{ meshIndex: number; point: Point; normal: Vec3; faceIndex: number; distance: number }> = [];
+    let off = 1;
+    for (let i = 0; i < count; i++) {
+      hits.push({
+        meshIndex: Math.floor(buf[off]),
+        point: new Point(buf[off + 1], buf[off + 2], buf[off + 3]),
+        normal: new Vec3(buf[off + 4], buf[off + 5], buf[off + 6]),
+        faceIndex: Math.floor(buf[off + 7]),
+        distance: buf[off + 8],
+      });
+      off += 9;
+    }
+    return hits;
+  }
+
+  private static packMeshes(meshes: Mesh[]): Float64Array {
+    const totalLen = meshes.reduce((sum, m) => sum + 1 + m.rawBuffer.length, 1);
+    const packed = new Float64Array(totalLen);
+    packed[0] = meshes.length;
+    let off = 1;
+    for (const mesh of meshes) {
+      const raw = mesh.rawBuffer;
+      packed[off++] = raw.length;
+      packed.set(raw, off);
+      off += raw.length;
+    }
+    return packed;
+  }
+
+  /**
+   * Unique undirected triangle edges as vertex-index pairs.
+   */
+  private getUniqueEdgeVertexPairs(): Array<[number, number]> {
+    if (this._edgeVertexPairs) return this._edgeVertexPairs;
+
+    ensureInit();
+    const packed = wasm.mesh_get_edge_vertex_pairs(this._vertexCount, this._buffer);
+    const edgeCount = Math.max(0, Math.floor(packed[0] ?? 0));
+    const pairs: Array<[number, number]> = [];
+    let off = 1;
+
+    for (let i = 0; i < edgeCount; i++) {
+      const a = Math.floor(packed[off++] ?? -1);
+      const b = Math.floor(packed[off++] ?? -1);
+      if (a < 0 || b < 0) break;
+      pairs.push([a, b]);
+    }
+
+    this._edgeVertexPairs = pairs;
+    return this._edgeVertexPairs;
+  }
+
+  // ── Transforms ────────────────────────────────────────────────
+
+  /**
+   * Translate this mesh by an offset vector.
+   * @param offset - Translation vector
+   * @returns New translated mesh
+   */
+  translate(offset: Vec3): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_translate(this._vertexCount, this._buffer, offset.x, offset.y, offset.z));
+  }
+
+  /**
+   * Rotate this mesh around an axis.
+   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
+   * @param angleRadians - Rotation angle in radians
+   * @returns New rotated mesh
+   */
+  rotate(axis: RotationAxis, angleRadians: number): Mesh {
+    ensureInit();
+    if ('start' in axis && 'end' in axis) {
+      const dir = new Vec3(axis.end.x - axis.start.x, axis.end.y - axis.start.y, axis.end.z - axis.start.z).normalize();
+      const c = axis.start;
+      return this.translate(new Vec3(-c.x, -c.y, -c.z))
+        .rotate(dir, angleRadians)
+        .translate(new Vec3(c.x, c.y, c.z));
+    }
+    return new Mesh(wasm.mesh_rotate(this._vertexCount, this._buffer, axis.x, axis.y, axis.z, angleRadians));
+  }
+
+  /**
+   * Scale this mesh uniformly.
+   * @param factor - Scale factor (1 = no change, 2 = double size)
+   * @returns New scaled mesh
+   */
+  scale(factor: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_scale(this._vertexCount, this._buffer, factor, factor, factor));
+  }
+
+  /**
+   * Scale this mesh non-uniformly along each axis.
+   * @param sx - Scale factor along X
+   * @param sy - Scale factor along Y
+   * @param sz - Scale factor along Z
+   * @returns New scaled mesh
+   */
+  scaleXYZ(sx: number, sy: number, sz: number): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_scale(this._vertexCount, this._buffer, sx, sy, sz));
+  }
+
+  private runBoolean(
+    other: Mesh,
+    operation: "union" | "subtraction" | "intersection",
+    invoke: () => Float64Array,
+    options?: MeshBooleanOptions,
+  ): Mesh {
+    const faceCountA = this.faceCount;
+    const faceCountB = other.faceCount;
+
+    if (operation === "union") {
+      if (faceCountA === 0) return Mesh.cloneMesh(other);
+      if (faceCountB === 0) return Mesh.cloneMesh(this);
+    } else if (operation === "intersection") {
+      if (faceCountA === 0 || faceCountB === 0) return Mesh.emptyMesh();
+    } else {
+      if (faceCountA === 0) return Mesh.emptyMesh();
+      if (faceCountB === 0) return Mesh.cloneMesh(this);
+    }
+
+    const boundsA = Mesh.computeRawBounds(this);
+    const boundsB = Mesh.computeRawBounds(other);
+    if (!Mesh.boundsOverlap(boundsA, boundsB)) {
+      if (operation === "union") return Mesh.mergeMeshes([this, other]);
+      if (operation === "intersection") return Mesh.emptyMesh();
+      return Mesh.cloneMesh(this);
+    }
+
+    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(
+          `Boolean ${operation} blocked by safety limits `
+          + `(A faces=${faceCountA}, B faces=${faceCountB}, faceProduct=${faceProduct}). `
+          + "Simplify inputs, run in a Worker, or pass allowUnsafe: true to force execution.",
+        );
+      }
+    }
+
+    const result = invoke();
+    if (result.length === 0) {
+      throw new Error(`Boolean ${operation} failed and returned an invalid mesh buffer.`);
+    }
+    const vertexCount = result[0];
+    if (!Number.isFinite(vertexCount) || vertexCount < 0) {
+      throw new Error(`Boolean ${operation} failed and returned a corrupt mesh buffer.`);
+    }
+    return Mesh.fromBuffer(result);
+  }
+
+  private static encodeBooleanOperationWithBackend(
+    operation: "union" | "subtraction" | "intersection",
+    _backend: MeshBooleanBackend | undefined,
+  ): string {
+    return `${operation}@nextgen`;
+  }
+
+  // ── 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.encodeBooleanOperationWithBackend("union", options?.backend);
+    return this.runBoolean(
+      other,
+      "union",
+      () => wasm.mesh_boolean_operation(
+        this._vertexCount,
+        this._buffer,
+        other._vertexCount,
+        other._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.encodeBooleanOperationWithBackend("subtraction", options?.backend);
+    return this.runBoolean(
+      other,
+      "subtraction",
+      () => wasm.mesh_boolean_operation(
+        this._vertexCount,
+        this._buffer,
+        other._vertexCount,
+        other._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
+   */
+  intersect(other: Mesh, options?: MeshBooleanOptions): Mesh {
+    ensureInit();
+    const operationToken = Mesh.encodeBooleanOperationWithBackend("intersection", options?.backend);
+    return this.runBoolean(
+      other,
+      "intersection",
+      () => wasm.mesh_boolean_operation(
+        this._vertexCount,
+        this._buffer,
+        other._vertexCount,
+        other._buffer,
+        operationToken,
+      ),
+      options,
+    );
+  }
+
+  /**
+   * Compute boolean union in a dedicated Web Worker (non-blocking).
+   * Defaults to allowUnsafe=true so high-poly jobs can run off the UI thread.
+   */
+  async unionAsync(other: Mesh, options?: MeshBooleanAsyncOptions): Promise<Mesh> {
+    const result = await runMeshBooleanInWorkerPool("union", this._buffer, other._buffer, options);
+    return Mesh.fromBuffer(result);
+  }
+
+  /**
+   * Compute boolean subtraction in a dedicated Web Worker (non-blocking).
+   * Defaults to allowUnsafe=true so high-poly jobs can run off the UI thread.
+   */
+  async subtractAsync(other: Mesh, options?: MeshBooleanAsyncOptions): Promise<Mesh> {
+    const result = await runMeshBooleanInWorkerPool("subtraction", this._buffer, other._buffer, options);
+    return Mesh.fromBuffer(result);
+  }
+
+  /**
+   * Compute boolean intersection in a dedicated Web Worker (non-blocking).
+   * Defaults to allowUnsafe=true so high-poly jobs can run off the UI thread.
+   */
+  async intersectAsync(other: Mesh, options?: MeshBooleanAsyncOptions): Promise<Mesh> {
+    const result = await runMeshBooleanInWorkerPool("intersection", this._buffer, other._buffer, options);
+    return Mesh.fromBuffer(result);
+  }
+
+  // ── Intersection queries ───────────────────────────────────────
+
+  /**
+   * Compute intersection curves with a plane.
+   * @param plane - Cutting plane
+   * @returns Array of polylines representing intersection curves
+   */
+  intersectPlane(plane: Plane): Polyline[] {
+    ensureInit();
+    const result = wasm.mesh_plane_intersect(
+      this._vertexCount,
+      this._buffer,
+      plane.normal.x,
+      plane.normal.y,
+      plane.normal.z,
+      plane.d
+    );
+    return parsePolylineBuf(result).map(pts => new Polyline(pts));
+  }
+
+  /**
+   * Compute intersection curves with another mesh.
+   * @param other - Mesh to intersect with
+   * @returns Array of polylines representing intersection curves
+   */
+  intersectMesh(other: Mesh): Polyline[] {
+    ensureInit();
+    const result = wasm.mesh_mesh_intersect(
+      this._vertexCount,
+      this._buffer,
+      other._vertexCount,
+      other._buffer
+    );
+    return parsePolylineBuf(result).map(pts => new Polyline(pts));
+  }
+
+  /**
+   * Apply a 4x4 transformation matrix.
+   * @param matrix - Row-major flat array of 16 numbers
+   * @returns New transformed mesh
+   */
+  applyMatrix(matrix: number[]): Mesh {
+    ensureInit();
+    return new Mesh(wasm.mesh_apply_matrix(this._vertexCount, this._buffer, new Float64Array(matrix)));
+  }
+
+  /**
+   * Evaluate a point on the mesh surface at parametric coordinates.
+   * Maps u ∈ [0,1] and v ∈ [0,1] across the mesh's bounding box and
+   * finds the corresponding surface point via ray casting.
+   *
+   * @param u - Parameter in first surface direction [0, 1]
+   * @param v - Parameter in second surface direction [0, 1]
+   * @returns Point on surface, or Point(NaN, NaN, NaN) if no intersection found
+   */
+  evaluate(u: number, v: number): Point {
+    ensureInit();
+    const r = wasm.mesh_evaluate(this._vertexCount, this._buffer, u, v);
+    return new Point(r[0], r[1], r[2]);
+  }
+
+  /**
+   * Extract boundary (perimeter) edges as polylines.
+   * Boundary edges are edges that belong to only one face.
+   * @returns Array of polylines representing open boundaries
+   */
+  boundaryPolylines(): Polyline[] {
+    ensureInit();
+    const buf = wasm.mesh_boundary_polylines(this._vertexCount, this._buffer);
+    return parsePolylineBuf(buf).map(pts => new Polyline(pts));
+  }
+
+  /**
+   * Axis-aligned bounds of this mesh.
+   */
+  getBounds(): { min: Point; max: Point } {
+    ensureInit();
+    const b = wasm.mesh_get_bounds(this._vertexCount, this._buffer);
+    return {
+      min: new Point(b[0] ?? 0, b[1] ?? 0, b[2] ?? 0),
+      max: new Point(b[3] ?? 0, b[4] ?? 0, b[5] ?? 0),
+    };
+  }
+
+  /**
+   * Unit normal of a triangle face.
+   */
+  getFaceNormal(faceIndex: number): Vec3 {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return Vec3.Y;
+    const n = wasm.mesh_get_face_normal(this._vertexCount, this._buffer, Math.floor(faceIndex));
+    return new Vec3(n[0] ?? 0, n[1] ?? 1, n[2] ?? 0);
+  }
+
+  /**
+   * Centroid of a triangle face.
+   */
+  getFaceCentroid(faceIndex: number): Point {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return Point.ORIGIN;
+    const c = wasm.mesh_get_face_centroid(this._vertexCount, this._buffer, Math.floor(faceIndex));
+    return new Point(c[0] ?? 0, c[1] ?? 0, c[2] ?? 0);
+  }
+
+  /**
+   * Area of a triangle face.
+   */
+  getFaceArea(faceIndex: number): number {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return 0;
+    return wasm.mesh_get_face_area(this._vertexCount, this._buffer, Math.floor(faceIndex));
+  }
+
+  /**
+   * Find edge-connected coplanar triangles that belong to the same planar face.
+   */
+  getCoplanarFaceIndices(faceIndex: number): number[] {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return [];
+    const r = wasm.mesh_get_coplanar_face_indices(this._vertexCount, this._buffer, Math.floor(faceIndex));
+    const count = Math.max(0, Math.floor(r[0] ?? 0));
+    const out: number[] = [];
+    for (let i = 0; i < count; i++) {
+      out.push(Math.floor(r[1 + i] ?? 0));
+    }
+    return out;
+  }
+
+  /**
+   * Coplanar connected face region and its projection bounds on a plane basis.
+   * Returns null for invalid inputs or empty regions.
+   */
+  getCoplanarFaceRegion(
+    faceIndex: number,
+    origin: Point,
+    uAxis: Vec3,
+    vAxis: Vec3,
+    marginScale = 0.1,
+    minMargin = 0.2,
+  ): { faceIndices: number[]; uMin: number; uMax: number; vMin: number; vMax: number } | null {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) return null;
+
+    const r = wasm.mesh_get_coplanar_face_region(
+      this._vertexCount,
+      this._buffer,
+      Math.floor(faceIndex),
+      origin.x, origin.y, origin.z,
+      uAxis.x, uAxis.y, uAxis.z,
+      vAxis.x, vAxis.y, vAxis.z,
+      marginScale,
+      minMargin,
+    );
+
+    const count = Math.max(0, Math.floor(r[0] ?? 0));
+    if (count <= 0 || r.length < 1 + count + 4) return null;
+
+    const faceIndices: number[] = [];
+    for (let i = 0; i < count; i++) {
+      faceIndices.push(Math.floor(r[1 + i] ?? 0));
+    }
+    const off = 1 + count;
+    return {
+      faceIndices,
+      uMin: r[off],
+      uMax: r[off + 1],
+      vMin: r[off + 2],
+      vMax: r[off + 3],
+    };
+  }
+
+  /**
+   * Centroid of the coplanar edge-connected face group containing faceIndex.
+   */
+  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,
+      Math.floor(faceIndex),
+    );
+    if (!r || r.length < 3) return null;
+    return new Point(r[0], r[1], r[2]);
+  }
+
+  /**
+   * Unique edge count for this triangulated mesh.
+   */
+  getEdgeCount(): number {
+    return this.getUniqueEdgeVertexPairs().length;
+  }
+
+  /**
+   * Return edge endpoints by edge index in the unique edge list.
+   */
+  getEdgeVertices(edgeIndex: number): [Point, Point] {
+    const pairs = this.getUniqueEdgeVertexPairs();
+    if (!Number.isFinite(edgeIndex) || edgeIndex < 0 || edgeIndex >= pairs.length) {
+      return [Point.ORIGIN, Point.ORIGIN];
+    }
+
+    const [i0, i1] = pairs[Math.floor(edgeIndex)];
+    const pos = this.positionBuffer;
+    const off0 = i0 * 3;
+    const off1 = i1 * 3;
+
+    return [
+      new Point(pos[off0], pos[off0 + 1], pos[off0 + 2]),
+      new Point(pos[off1], pos[off1 + 1], pos[off1 + 2]),
+    ];
+  }
+
+  /**
+   * Raycast against this mesh and return nearest hit.
+   */
+  raycast(
+    origin: Point,
+    direction: Vec3,
+    maxDistance = Number.POSITIVE_INFINITY,
+  ): { point: Point; normal: Vec3; faceIndex: number; distance: number } | null {
+    ensureInit();
+    const r = wasm.mesh_raycast(
+      this._vertexCount,
+      this._buffer,
+      origin.x, origin.y, origin.z,
+      direction.x, direction.y, direction.z,
+      maxDistance,
+    );
+    if (!r || r.length < 8) return null;
+    return {
+      point: new Point(r[0], r[1], r[2]),
+      normal: new Vec3(r[3], r[4], r[5]),
+      faceIndex: Math.floor(r[6]),
+      distance: r[7],
+    };
+  }
+
+  /**
+   * Raycast against this mesh and return all hits sorted by distance.
+   */
+  raycastAll(
+    origin: Point,
+    direction: Vec3,
+    maxDistance = Number.POSITIVE_INFINITY,
+  ): Array<{ point: Point; normal: Vec3; faceIndex: number; distance: number }> {
+    ensureInit();
+    const buf = wasm.mesh_raycast_all(
+      this._vertexCount,
+      this._buffer,
+      origin.x, origin.y, origin.z,
+      direction.x, direction.y, direction.z,
+      maxDistance,
+    );
+    const count = Math.max(0, Math.floor(buf[0] ?? 0));
+    const hits: Array<{ point: Point; normal: Vec3; faceIndex: number; distance: number }> = [];
+    let off = 1;
+    for (let i = 0; i < count; i++) {
+      hits.push({
+        point: new Point(buf[off], buf[off + 1], buf[off + 2]),
+        normal: new Vec3(buf[off + 3], buf[off + 4], buf[off + 5]),
+        faceIndex: Math.floor(buf[off + 6]),
+        distance: buf[off + 7],
+      });
+      off += 8;
+    }
+    return hits;
+  }
+
+  /**
+   * Push/pull a planar face set by moving its coplanar connected region.
+   */
+  extrudeFace(faceIndex: number, distance: number): Mesh {
+    ensureInit();
+    if (!Number.isFinite(faceIndex) || faceIndex < 0) {
+      return Mesh.fromBuffer(new Float64Array(this._buffer));
+    }
+    return Mesh.fromBuffer(
+      wasm.mesh_extrude_face(this._vertexCount, this._buffer, Math.floor(faceIndex), distance),
+    );
+  }
+
+  /**
+   * Check if this triangulated mesh represents a closed volume.
+   * Returns true when no welded topological boundary edges are found.
+   */
+  isClosedVolume(): boolean {
+    ensureInit();
+    return wasm.mesh_is_closed_volume(this._vertexCount, this._buffer);
+  }
+
+  /**
+   * 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]),
+    };
+  }
+
+  // ── Export ──────────────────────────────────────────────────────
+
+  /**
+   * Export this mesh to OBJ format.
+   * @returns OBJ file content as string
+   */
+  toOBJ(): string {
+    ensureInit();
+    return wasm.mesh_export_obj(this._vertexCount, this._buffer);
+  }
+}
+
+
+