okgeometry-api 1.1.22 → 1.2.0

package/src/Mesh.ts

@@ -17,24 +17,24 @@ import {
   disposeMeshBooleanWorkerPools,
   runMeshBooleanInWorkerPool,
 } from "./mesh-boolean.pool.js";
-import { MeshBooleanExecutionError } from "./mesh-boolean.protocol.js";
-import type {
-  MeshBooleanAsyncOptions,
-  MeshBooleanLimits,
-  MeshBooleanOptions,
-} from "./mesh-boolean.protocol.js";
-import * as wasm from "./wasm-bindings.js";
-import { mesh_topology_metrics, mesh_topology_metrics_raw } from "./wasm-bindings.js";
+import { MeshBooleanExecutionError } from "./mesh-boolean.protocol.js";
+import type {
+  MeshBooleanAsyncOptions,
+  MeshBooleanLimits,
+  MeshBooleanOptions,
+} from "./mesh-boolean.protocol.js";
+import * as wasm from "./wasm-bindings.js";
+import { mesh_topology_metrics, mesh_topology_metrics_raw } from "./wasm-bindings.js";
 
 export { MeshBooleanExecutionError };
-export type {
-  MeshBooleanAsyncOptions,
-  MeshBooleanLimits,
-  MeshBooleanOptions,
-  MeshBooleanErrorCode,
-  MeshBooleanErrorPayload,
-  MeshBooleanProgressEvent,
-} from "./mesh-boolean.protocol.js";
+export type {
+  MeshBooleanAsyncOptions,
+  MeshBooleanLimits,
+  MeshBooleanOptions,
+  MeshBooleanErrorCode,
+  MeshBooleanErrorPayload,
+  MeshBooleanProgressEvent,
+} from "./mesh-boolean.protocol.js";
 
 export interface PlanarRectangle {
   corners: [Point, Point, Point, Point];
@@ -113,86 +113,117 @@ export interface MeshBooleanDebugOptions {
   probes?: MeshBooleanDebugProbeId[];
 }
 
-export interface MeshBooleanDebugReport {
-  operation: MeshBooleanOperation;
-  inputA: MeshDebugSummary;
-  inputB: MeshDebugSummary;
-  result: Mesh;
-  resultSummary: MeshDebugSummary;
-  probes: MeshBooleanDebugProbe[];
-}
-
-export interface MeshBooleanDebugProbeSummary {
-  label: string;
-  origin: { x: number; y: number; z: number };
-  direction: { x: number; y: number; z: number };
-  inputAFirst: {
-    point: { x: number; y: number; z: number };
-    normal: { x: number; y: number; z: number };
-    faceIndex: number;
-    distance: number;
-  } | null;
-  inputBFirst: {
-    point: { x: number; y: number; z: number };
-    normal: { x: number; y: number; z: number };
-    faceIndex: number;
-    distance: number;
-  } | null;
-  resultFirst: {
-    point: { x: number; y: number; z: number };
-    normal: { x: number; y: number; z: number };
-    faceIndex: number;
-    distance: number;
-  } | null;
-  inputAHits: number;
-  inputBHits: number;
-  resultHits: number;
-}
-
-export interface MeshBooleanReproOperand {
-  trustedBooleanInput: boolean;
-  summary: MeshDebugSummary;
-  buffer: number[];
-}
-
-export interface MeshBooleanReproResult {
-  summary: MeshDebugSummary;
-  buffer: number[];
-  probeSummary?: MeshBooleanDebugProbeSummary[];
+export interface MeshBooleanDebugReport {
+  operation: MeshBooleanOperation;
+  inputA: MeshDebugSummary;
+  inputB: MeshDebugSummary;
+  result: Mesh;
+  resultSummary: MeshDebugSummary;
+  probes: MeshBooleanDebugProbe[];
+}
+
+export interface MeshBooleanDebugProbeSummary {
+  label: string;
+  origin: { x: number; y: number; z: number };
+  direction: { x: number; y: number; z: number };
+  inputAFirst: {
+    point: { x: number; y: number; z: number };
+    normal: { x: number; y: number; z: number };
+    faceIndex: number;
+    distance: number;
+  } | null;
+  inputBFirst: {
+    point: { x: number; y: number; z: number };
+    normal: { x: number; y: number; z: number };
+    faceIndex: number;
+    distance: number;
+  } | null;
+  resultFirst: {
+    point: { x: number; y: number; z: number };
+    normal: { x: number; y: number; z: number };
+    faceIndex: number;
+    distance: number;
+  } | null;
+  inputAHits: number;
+  inputBHits: number;
+  resultHits: number;
+}
+
+export interface MeshBooleanReproOperand {
+  trustedBooleanInput: boolean;
+  summary: MeshDebugSummary;
+  buffer: number[];
+}
+
+export interface MeshBooleanReproResult {
+  summary: MeshDebugSummary;
+  buffer: number[];
+  probeSummary?: MeshBooleanDebugProbeSummary[];
+}
+
+export interface MeshBooleanReproError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+export interface MeshBooleanReproPayload {
+  version: 1;
+  operation: MeshBooleanOperation;
+  options: MeshBooleanOptions | null;
+  inputA: MeshBooleanReproOperand;
+  inputB: MeshBooleanReproOperand;
+  result?: MeshBooleanReproResult;
+  error?: MeshBooleanReproError;
+}
+
+export interface MeshBooleanReproOptions {
+  includeResult?: boolean;
+  debugOptions?: MeshBooleanDebugOptions;
 }
 
-export interface MeshBooleanReproError {
-  name: string;
-  message: string;
-  stack?: string;
+export interface MeshSplitResult {
+  outside: Mesh[];
+  inside: Mesh[];
+  all: Mesh[];
+  classification?: "volume" | "surface";
+  negative?: Mesh[];
+  positive?: Mesh[];
 }
 
-export interface MeshBooleanReproPayload {
-  version: 1;
-  operation: MeshBooleanOperation;
-  options: MeshBooleanOptions | null;
-  inputA: MeshBooleanReproOperand;
-  inputB: MeshBooleanReproOperand;
-  result?: MeshBooleanReproResult;
-  error?: MeshBooleanReproError;
+export interface MeshPlaneSplitResult extends MeshSplitResult {
+  negative: Mesh[];
+  positive: Mesh[];
 }
 
-export interface MeshBooleanReproOptions {
-  includeResult?: boolean;
-  debugOptions?: MeshBooleanDebugOptions;
+export interface MeshPlaneSplitOptions extends MeshBooleanOptions {
+  planePaddingScale?: number;
 }
 
-function shouldFallbackFromWorkerFailure(error: unknown): boolean {
-  if (!error || typeof error !== "object") return false;
-  const code = "code" in error ? error.code : undefined;
-  return code === "worker_unavailable" || code === "worker_crashed" || code === "worker_protocol";
+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;
 }
-
-/**
- * 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, ...]
+
+function shouldFallbackFromWorkerFailure(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = "code" in error ? error.code : undefined;
+  return code === "worker_unavailable" || code === "worker_crashed" || code === "worker_protocol";
+}
+
+/**
+ * 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;
@@ -549,11 +580,11 @@ export class Mesh {
     };
   }
 
-  private static summarizeDebugProbe(probe: MeshBooleanDebugProbe): MeshBooleanDebugProbeSummary {
-    return {
-      label: probe.label,
-      origin: {
-        x: Mesh.roundDebugScalar(probe.origin.x),
+  private static summarizeDebugProbe(probe: MeshBooleanDebugProbe): MeshBooleanDebugProbeSummary {
+    return {
+      label: probe.label,
+      origin: {
+        x: Mesh.roundDebugScalar(probe.origin.x),
         y: Mesh.roundDebugScalar(probe.origin.y),
         z: Mesh.roundDebugScalar(probe.origin.z),
       },
@@ -567,84 +598,278 @@ export class Mesh {
       resultFirst: Mesh.summarizeDebugHit(probe.resultHits[0]),
       inputAHits: probe.inputAHits.length,
       inputBHits: probe.inputBHits.length,
-      resultHits: probe.resultHits.length,
-    };
+      resultHits: probe.resultHits.length,
+    };
+  }
+
+  private static serializeBooleanOptions(options?: MeshBooleanOptions): MeshBooleanOptions | null {
+    return options == null ? null : { ...options };
+  }
+
+  private static serializeBooleanError(error: unknown): MeshBooleanReproError {
+    if (error instanceof Error) {
+      return {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      };
+    }
+    return {
+      name: typeof error,
+      message: typeof error === "string" ? error : JSON.stringify(error),
+    };
+  }
+
+  private static exportBooleanReproOperand(mesh: Mesh): MeshBooleanReproOperand {
+    return {
+      trustedBooleanInput: mesh._trustedBooleanInput,
+      summary: mesh.debugSummary(),
+      buffer: Array.from(mesh._buffer),
+    };
+  }
+
+  private static createBooleanReproPayload(
+    inputA: Mesh,
+    inputB: Mesh,
+    operation: MeshBooleanOperation,
+    options?: MeshBooleanOptions,
+    result?: Mesh,
+    debugOptions?: MeshBooleanDebugOptions,
+    error?: unknown,
+  ): MeshBooleanReproPayload {
+    const payload: MeshBooleanReproPayload = {
+      version: 1,
+      operation,
+      options: Mesh.serializeBooleanOptions(options),
+      inputA: Mesh.exportBooleanReproOperand(inputA),
+      inputB: Mesh.exportBooleanReproOperand(inputB),
+    };
+
+    if (result) {
+      payload.result = {
+        summary: result.debugSummary(),
+        buffer: Array.from(result._buffer),
+      };
+      if (debugOptions) {
+        try {
+          const report = Mesh.createBooleanDebugReport(inputA, inputB, result, operation, debugOptions);
+          payload.result.probeSummary = report.probes.map((probe) => Mesh.summarizeDebugProbe(probe));
+        } catch {
+          // Keep the repro payload usable even when extra debug probes fail.
+        }
+      }
+    }
+
+    if (error !== undefined) {
+      payload.error = Mesh.serializeBooleanError(error);
+    }
+
+    return payload;
+  }
+
+  private static cloneMesh(mesh: Mesh): Mesh {
+    return Mesh.fromBuffer(new Float64Array(mesh._buffer), {
+      trustedBooleanInput: mesh._trustedBooleanInput,
+    });
+  }
+
+  private static emptyMesh(): Mesh {
+    return Mesh.fromTrustedBuffer(new Float64Array(0));
   }
 
-  private static serializeBooleanOptions(options?: MeshBooleanOptions): MeshBooleanOptions | null {
-    return options == null ? null : { ...options };
+  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 serializeBooleanError(error: unknown): MeshBooleanReproError {
-    if (error instanceof Error) {
-      return {
-        name: error.name,
-        message: error.message,
-        stack: error.stack,
-      };
-    }
-    return {
-      name: typeof error,
-      message: typeof error === "string" ? error : JSON.stringify(error),
-    };
+  private static createSurfaceSplitResult(negative: Mesh[], positive: Mesh[]): MeshSplitResult {
+    return Mesh.createSplitResult(negative, positive, "surface");
   }
 
-  private static exportBooleanReproOperand(mesh: Mesh): MeshBooleanReproOperand {
+  private static createPlaneSplitResult(
+    negative: Mesh[],
+    positive: Mesh[],
+    classification: "volume" | "surface" = "surface",
+  ): MeshPlaneSplitResult {
     return {
-      trustedBooleanInput: mesh._trustedBooleanInput,
-      summary: mesh.debugSummary(),
-      buffer: Array.from(mesh._buffer),
+      ...Mesh.createSplitResult(negative, positive, classification),
+      negative,
+      positive,
     };
   }
 
-  private static createBooleanReproPayload(
-    inputA: Mesh,
-    inputB: Mesh,
-    operation: MeshBooleanOperation,
-    options?: MeshBooleanOptions,
-    result?: Mesh,
-    debugOptions?: MeshBooleanDebugOptions,
-    error?: unknown,
-  ): MeshBooleanReproPayload {
-    const payload: MeshBooleanReproPayload = {
-      version: 1,
-      operation,
-      options: Mesh.serializeBooleanOptions(options),
-      inputA: Mesh.exportBooleanReproOperand(inputA),
-      inputB: Mesh.exportBooleanReproOperand(inputB),
-    };
+  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;
 
-    if (result) {
-      payload.result = {
-        summary: result.debugSummary(),
-        buffer: Array.from(result._buffer),
-      };
-      if (debugOptions) {
-        try {
-          const report = Mesh.createBooleanDebugReport(inputA, inputB, result, operation, debugOptions);
-          payload.result.probeSummary = report.probes.map((probe) => Mesh.summarizeDebugProbe(probe));
-        } catch {
-          // Keep the repro payload usable even when extra debug probes fail.
+    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);
+  }
 
-    if (error !== undefined) {
-      payload.error = Mesh.serializeBooleanError(error);
+  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 };
+  }
 
-    return payload;
+  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 cloneMesh(mesh: Mesh): Mesh {
-    return Mesh.fromBuffer(new Float64Array(mesh._buffer), {
-      trustedBooleanInput: mesh._trustedBooleanInput,
-    });
+  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));
-  }
 
   // ── GPU-ready buffers ──────────────────────────────────────────
 
@@ -1198,91 +1423,91 @@ export class Mesh {
    * 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,
+  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.fromTrustedBuffer(buf);
-  }
-
-  private static normalizeClosedCurvePoints(points: Point[], eps = 1e-10): Point[] {
-    const normalized: Point[] = [];
-    for (const point of points) {
-      if (normalized.length > 0 && normalized[normalized.length - 1].equals(point, eps)) continue;
-      normalized.push(point);
-    }
-    if (normalized.length > 1 && normalized[0].equals(normalized[normalized.length - 1], eps)) {
-      normalized.pop();
-    }
-    return normalized;
-  }
-
-  private static getClosedCurveLoopPoints(curve: SweepableCurve, segments: number): Point[] {
-    const closureEps = 1e-6;
-    const sampleCount = Number.isFinite(segments) ? Math.max(3, Math.floor(segments)) : 32;
-
-    if (curve instanceof Circle) {
-      return Mesh.normalizeClosedCurvePoints(curve.sample(sampleCount), closureEps);
-    }
-    if (curve instanceof Polygon || curve instanceof Polyline) {
-      if (!curve.isClosed(closureEps)) {
-        throw new Error("Mesh.extrudeCurveAsSolid() requires a closed polyline or polygon.");
-      }
-      return Mesh.normalizeClosedCurvePoints(curve.points, closureEps);
-    }
-    if (curve instanceof PolyCurve) {
-      if (!curve.isClosed(closureEps)) {
-        throw new Error("Mesh.extrudeCurveAsSolid() requires a closed polycurve.");
-      }
-      return Mesh.normalizeClosedCurvePoints(curve.sample(Math.max(2, sampleCount)), closureEps);
-    }
-    if (curve instanceof NurbsCurve) {
-      if (!curve.isClosed(closureEps)) {
-        throw new Error("Mesh.extrudeCurveAsSolid() requires a closed NURBS curve.");
-      }
-      return Mesh.normalizeClosedCurvePoints(curve.sample(sampleCount), closureEps);
-    }
-
-    throw new Error(
-      "Mesh.extrudeCurveAsSolid() requires a closed curve "
-      + "(Circle, closed Polyline/Polygon, closed PolyCurve, or closed NurbsCurve).",
-    );
-  }
-
-  /**
-   * Extrude a closed planar curve into a trusted closed solid suitable for booleans.
-   * Curved inputs are sampled first, so `segments` controls tessellation density
-   * for circles, polycurves, and NURBS curves.
-   */
-  static extrudeCurveAsSolid(curve: SweepableCurve, direction: Vec3, segments = 32): Mesh {
-    ensureInit();
-
-    const height = direction.length();
-    if (!Number.isFinite(height) || height < 1e-10) {
-      throw new Error("Mesh.extrudeCurveAsSolid() requires a non-zero extrusion direction.");
-    }
-
-    const points = Mesh.getClosedCurveLoopPoints(curve, segments);
-    if (points.length < 3) {
-      throw new Error("Mesh.extrudeCurveAsSolid() requires at least 3 unique boundary points.");
-    }
-
-    const normal = direction.scale(1 / height);
-    const mesh = Mesh.extrudePlanarCurve(points, normal, height, true);
-    if (mesh.vertexCount === 0) {
-      throw new Error("Mesh.extrudeCurveAsSolid() failed. Ensure the curve is planar and closed.");
-    }
-    return mesh;
-  }
-
-  /**
-   * Shift a closed cutter profile slightly opposite to travel direction and
-   * compensate height so the distal end remains at the user-intended depth.
-   */
+    );
+    return Mesh.fromTrustedBuffer(buf);
+  }
+
+  private static normalizeClosedCurvePoints(points: Point[], eps = 1e-10): Point[] {
+    const normalized: Point[] = [];
+    for (const point of points) {
+      if (normalized.length > 0 && normalized[normalized.length - 1].equals(point, eps)) continue;
+      normalized.push(point);
+    }
+    if (normalized.length > 1 && normalized[0].equals(normalized[normalized.length - 1], eps)) {
+      normalized.pop();
+    }
+    return normalized;
+  }
+
+  private static getClosedCurveLoopPoints(curve: SweepableCurve, segments: number): Point[] {
+    const closureEps = 1e-6;
+    const sampleCount = Number.isFinite(segments) ? Math.max(3, Math.floor(segments)) : 32;
+
+    if (curve instanceof Circle) {
+      return Mesh.normalizeClosedCurvePoints(curve.sample(sampleCount), closureEps);
+    }
+    if (curve instanceof Polygon || curve instanceof Polyline) {
+      if (!curve.isClosed(closureEps)) {
+        throw new Error("Mesh.extrudeCurveAsSolid() requires a closed polyline or polygon.");
+      }
+      return Mesh.normalizeClosedCurvePoints(curve.points, closureEps);
+    }
+    if (curve instanceof PolyCurve) {
+      if (!curve.isClosed(closureEps)) {
+        throw new Error("Mesh.extrudeCurveAsSolid() requires a closed polycurve.");
+      }
+      return Mesh.normalizeClosedCurvePoints(curve.sample(Math.max(2, sampleCount)), closureEps);
+    }
+    if (curve instanceof NurbsCurve) {
+      if (!curve.isClosed(closureEps)) {
+        throw new Error("Mesh.extrudeCurveAsSolid() requires a closed NURBS curve.");
+      }
+      return Mesh.normalizeClosedCurvePoints(curve.sample(sampleCount), closureEps);
+    }
+
+    throw new Error(
+      "Mesh.extrudeCurveAsSolid() requires a closed curve "
+      + "(Circle, closed Polyline/Polygon, closed PolyCurve, or closed NurbsCurve).",
+    );
+  }
+
+  /**
+   * Extrude a closed planar curve into a trusted closed solid suitable for booleans.
+   * Curved inputs are sampled first, so `segments` controls tessellation density
+   * for circles, polycurves, and NURBS curves.
+   */
+  static extrudeCurveAsSolid(curve: SweepableCurve, direction: Vec3, segments = 32): Mesh {
+    ensureInit();
+
+    const height = direction.length();
+    if (!Number.isFinite(height) || height < 1e-10) {
+      throw new Error("Mesh.extrudeCurveAsSolid() requires a non-zero extrusion direction.");
+    }
+
+    const points = Mesh.getClosedCurveLoopPoints(curve, segments);
+    if (points.length < 3) {
+      throw new Error("Mesh.extrudeCurveAsSolid() requires at least 3 unique boundary points.");
+    }
+
+    const normal = direction.scale(1 / height);
+    const mesh = Mesh.extrudePlanarCurve(points, normal, height, true);
+    if (mesh.vertexCount === 0) {
+      throw new Error("Mesh.extrudeCurveAsSolid() failed. Ensure the curve is planar and closed.");
+    }
+    return mesh;
+  }
+
+  /**
+   * 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,
@@ -1591,10 +1816,10 @@ export class Mesh {
     return Mesh.fromTrustedBuffer(result);
   }
 
-  static encodeBooleanOperationToken(
-    operation: MeshBooleanOperation,
-    a: Mesh,
-    b: Mesh,
+  static encodeBooleanOperationToken(
+    operation: MeshBooleanOperation,
+    a: Mesh,
+    b: Mesh,
     options?: MeshBooleanOptions,
   ): string {
     const tokens: string[] = [operation];
@@ -1603,9 +1828,24 @@ export class Mesh {
     }
     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 ───────────────────────────────────────────────────
 
@@ -1638,22 +1878,22 @@ export class Mesh {
    * @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,
-    );
-  }
+  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 intersection with another mesh.
@@ -1661,11 +1901,11 @@ export class Mesh {
    * @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 operationToken = Mesh.encodeBooleanOperationToken("intersection", this, other, options);
+    return this.runBoolean(
+      other,
       "intersection",
       () => wasm.mesh_boolean_operation(
         this._vertexCount,
@@ -1674,13 +1914,162 @@ export class Mesh {
         other._buffer,
         operationToken,
       ),
-      options,
-    );
-  }
-
-  debugBoolean(
-    other: Mesh,
-    operation: MeshBooleanOperation,
+      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,
     options?: MeshBooleanOptions,
     debugOptions?: MeshBooleanDebugOptions,
   ): MeshBooleanDebugReport {
@@ -1709,184 +2098,184 @@ export class Mesh {
     return this.debugBoolean(other, "subtraction", options, debugOptions);
   }
 
-  debugIntersect(
-    other: Mesh,
-    options?: MeshBooleanOptions,
-    debugOptions?: MeshBooleanDebugOptions,
-  ): MeshBooleanDebugReport {
-    return this.debugBoolean(other, "intersection", options, debugOptions);
-  }
-
-  exportBooleanRepro(
-    other: Mesh,
-    operation: MeshBooleanOperation,
-    options?: MeshBooleanOptions,
-    reproOptions?: MeshBooleanReproOptions,
-  ): MeshBooleanReproPayload {
-    if (!reproOptions?.includeResult) {
-      return Mesh.createBooleanReproPayload(this, other, operation, options);
-    }
-
-    try {
-      const result = operation === "union"
-        ? this.union(other, options)
-        : operation === "subtraction"
-          ? this.subtract(other, options)
-          : this.intersect(other, options);
-      return Mesh.createBooleanReproPayload(
-        this,
-        other,
-        operation,
-        options,
-        result,
-        reproOptions.debugOptions,
-      );
-    } catch (error) {
-      return Mesh.createBooleanReproPayload(
-        this,
-        other,
-        operation,
-        options,
-        undefined,
-        undefined,
-        error,
-      );
-    }
-  }
-
-  exportSubtractRepro(
-    other: Mesh,
-    options?: MeshBooleanOptions,
-    reproOptions?: MeshBooleanReproOptions,
-  ): MeshBooleanReproPayload {
-    return this.exportBooleanRepro(other, "subtraction", options, reproOptions);
-  }
-
-  exportBooleanReproJSON(
-    other: Mesh,
-    operation: MeshBooleanOperation,
-    options?: MeshBooleanOptions,
-    reproOptions?: MeshBooleanReproOptions,
-  ): string {
-    return JSON.stringify(this.exportBooleanRepro(other, operation, options, reproOptions), null, 2);
-  }
-
-  exportSubtractReproJSON(
-    other: Mesh,
-    options?: MeshBooleanOptions,
-    reproOptions?: MeshBooleanReproOptions,
-  ): string {
-    return this.exportBooleanReproJSON(other, "subtraction", options, reproOptions);
-  }
-
-  exportUnionRepro(
-    other: Mesh,
-    options?: MeshBooleanOptions,
-    reproOptions?: MeshBooleanReproOptions,
-  ): MeshBooleanReproPayload {
-    return this.exportBooleanRepro(other, "union", options, reproOptions);
-  }
-
-  exportIntersectRepro(
-    other: Mesh,
-    options?: MeshBooleanOptions,
-    reproOptions?: MeshBooleanReproOptions,
-  ): MeshBooleanReproPayload {
-    return this.exportBooleanRepro(other, "intersection", options, reproOptions);
-  }
-
-  static replayBooleanRepro(payload: MeshBooleanReproPayload): Mesh {
-    const inputA = Mesh.fromBuffer(new Float64Array(payload.inputA.buffer), {
-      trustedBooleanInput: payload.inputA.trustedBooleanInput,
-    });
-    const inputB = Mesh.fromBuffer(new Float64Array(payload.inputB.buffer), {
-      trustedBooleanInput: payload.inputB.trustedBooleanInput,
-    });
-
-    return payload.operation === "union"
-      ? inputA.union(inputB, payload.options ?? undefined)
-      : payload.operation === "subtraction"
-        ? inputA.subtract(inputB, payload.options ?? undefined)
-        : inputA.intersect(inputB, payload.options ?? undefined);
-  }
-
-  /**
-   * 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> {
-    try {
-      const result = await runMeshBooleanInWorkerPool(
-        "union",
-        this._buffer,
-        other._buffer,
-        this._trustedBooleanInput,
-        other._trustedBooleanInput,
-        options,
-      );
-      return Mesh.fromTrustedBuffer(result);
-    } catch (error) {
-      if (!shouldFallbackFromWorkerFailure(error)) throw error;
-      console.warn("Mesh.unionAsync worker failed; falling back to main-thread boolean.", error);
-      return this.union(other, {
-        allowUnsafe: options?.allowUnsafe ?? true,
-        limits: options?.limits,
-        debugForceFaceID: options?.debugForceFaceID,
-      });
-    }
-  }
+  debugIntersect(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    debugOptions?: MeshBooleanDebugOptions,
+  ): MeshBooleanDebugReport {
+    return this.debugBoolean(other, "intersection", options, debugOptions);
+  }
 
-  /**
-   * 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> {
-    try {
-      const result = await runMeshBooleanInWorkerPool(
-        "subtraction",
-        this._buffer,
-        other._buffer,
-        this._trustedBooleanInput,
-        other._trustedBooleanInput,
-        options,
-      );
-      return Mesh.fromTrustedBuffer(result);
-    } catch (error) {
-      if (!shouldFallbackFromWorkerFailure(error)) throw error;
-      console.warn("Mesh.subtractAsync worker failed; falling back to main-thread boolean.", error);
-      return this.subtract(other, {
-        allowUnsafe: options?.allowUnsafe ?? true,
-        limits: options?.limits,
-        debugForceFaceID: options?.debugForceFaceID,
-      });
-    }
-  }
+  exportBooleanRepro(
+    other: Mesh,
+    operation: MeshBooleanOperation,
+    options?: MeshBooleanOptions,
+    reproOptions?: MeshBooleanReproOptions,
+  ): MeshBooleanReproPayload {
+    if (!reproOptions?.includeResult) {
+      return Mesh.createBooleanReproPayload(this, other, operation, options);
+    }
 
-  /**
-   * 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> {
-    try {
-      const result = await runMeshBooleanInWorkerPool(
-        "intersection",
-        this._buffer,
-        other._buffer,
-        this._trustedBooleanInput,
-        other._trustedBooleanInput,
-        options,
-      );
-      return Mesh.fromTrustedBuffer(result);
-    } catch (error) {
-      if (!shouldFallbackFromWorkerFailure(error)) throw error;
-      console.warn("Mesh.intersectAsync worker failed; falling back to main-thread boolean.", error);
-      return this.intersect(other, {
-        allowUnsafe: options?.allowUnsafe ?? true,
-        limits: options?.limits,
-        debugForceFaceID: options?.debugForceFaceID,
-      });
-    }
-  }
+    try {
+      const result = operation === "union"
+        ? this.union(other, options)
+        : operation === "subtraction"
+          ? this.subtract(other, options)
+          : this.intersect(other, options);
+      return Mesh.createBooleanReproPayload(
+        this,
+        other,
+        operation,
+        options,
+        result,
+        reproOptions.debugOptions,
+      );
+    } catch (error) {
+      return Mesh.createBooleanReproPayload(
+        this,
+        other,
+        operation,
+        options,
+        undefined,
+        undefined,
+        error,
+      );
+    }
+  }
+
+  exportSubtractRepro(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    reproOptions?: MeshBooleanReproOptions,
+  ): MeshBooleanReproPayload {
+    return this.exportBooleanRepro(other, "subtraction", options, reproOptions);
+  }
+
+  exportBooleanReproJSON(
+    other: Mesh,
+    operation: MeshBooleanOperation,
+    options?: MeshBooleanOptions,
+    reproOptions?: MeshBooleanReproOptions,
+  ): string {
+    return JSON.stringify(this.exportBooleanRepro(other, operation, options, reproOptions), null, 2);
+  }
+
+  exportSubtractReproJSON(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    reproOptions?: MeshBooleanReproOptions,
+  ): string {
+    return this.exportBooleanReproJSON(other, "subtraction", options, reproOptions);
+  }
+
+  exportUnionRepro(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    reproOptions?: MeshBooleanReproOptions,
+  ): MeshBooleanReproPayload {
+    return this.exportBooleanRepro(other, "union", options, reproOptions);
+  }
+
+  exportIntersectRepro(
+    other: Mesh,
+    options?: MeshBooleanOptions,
+    reproOptions?: MeshBooleanReproOptions,
+  ): MeshBooleanReproPayload {
+    return this.exportBooleanRepro(other, "intersection", options, reproOptions);
+  }
+
+  static replayBooleanRepro(payload: MeshBooleanReproPayload): Mesh {
+    const inputA = Mesh.fromBuffer(new Float64Array(payload.inputA.buffer), {
+      trustedBooleanInput: payload.inputA.trustedBooleanInput,
+    });
+    const inputB = Mesh.fromBuffer(new Float64Array(payload.inputB.buffer), {
+      trustedBooleanInput: payload.inputB.trustedBooleanInput,
+    });
+
+    return payload.operation === "union"
+      ? inputA.union(inputB, payload.options ?? undefined)
+      : payload.operation === "subtraction"
+        ? inputA.subtract(inputB, payload.options ?? undefined)
+        : inputA.intersect(inputB, payload.options ?? undefined);
+  }
+
+  /**
+   * 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> {
+    try {
+      const result = await runMeshBooleanInWorkerPool(
+        "union",
+        this._buffer,
+        other._buffer,
+        this._trustedBooleanInput,
+        other._trustedBooleanInput,
+        options,
+      );
+      return Mesh.fromTrustedBuffer(result);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.unionAsync worker failed; falling back to main-thread boolean.", error);
+      return this.union(other, {
+        allowUnsafe: options?.allowUnsafe ?? true,
+        limits: options?.limits,
+        debugForceFaceID: options?.debugForceFaceID,
+      });
+    }
+  }
+
+  /**
+   * 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> {
+    try {
+      const result = await runMeshBooleanInWorkerPool(
+        "subtraction",
+        this._buffer,
+        other._buffer,
+        this._trustedBooleanInput,
+        other._trustedBooleanInput,
+        options,
+      );
+      return Mesh.fromTrustedBuffer(result);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.subtractAsync worker failed; falling back to main-thread boolean.", error);
+      return this.subtract(other, {
+        allowUnsafe: options?.allowUnsafe ?? true,
+        limits: options?.limits,
+        debugForceFaceID: options?.debugForceFaceID,
+      });
+    }
+  }
+
+  /**
+   * 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> {
+    try {
+      const result = await runMeshBooleanInWorkerPool(
+        "intersection",
+        this._buffer,
+        other._buffer,
+        this._trustedBooleanInput,
+        other._trustedBooleanInput,
+        options,
+      );
+      return Mesh.fromTrustedBuffer(result);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.intersectAsync worker failed; falling back to main-thread boolean.", error);
+      return this.intersect(other, {
+        allowUnsafe: options?.allowUnsafe ?? true,
+        limits: options?.limits,
+        debugForceFaceID: options?.debugForceFaceID,
+      });
+    }
+  }
 
   // ── Intersection queries ───────────────────────────────────────
 
@@ -2176,28 +2565,28 @@ export class Mesh {
    * Check if this triangulated mesh represents a closed volume.
    * Returns true when no welded topological boundary edges are found.
    */
-  isClosedVolume(): boolean {
-    if (this._isClosedVolumeCache !== null) {
-      return this._isClosedVolumeCache;
-    }
-    if (this._topologyMetricsCache) {
+  isClosedVolume(): boolean {
+    if (this._isClosedVolumeCache !== null) {
+      return this._isClosedVolumeCache;
+    }
+    if (this._topologyMetricsCache) {
       const closedFromMetrics = this._topologyMetricsCache.boundaryEdges === 0;
-      this._isClosedVolumeCache = closedFromMetrics;
-      return closedFromMetrics;
-    }
-
-    if (this._trustedBooleanInput) {
-      const metrics = this.topologyMetrics();
-      const closedFromMetrics = metrics.boundaryEdges === 0;
-      this._isClosedVolumeCache = closedFromMetrics;
-      return closedFromMetrics;
-    }
-
-    ensureInit();
-    if (this.faceCount >= Mesh.TOPOLOGY_METRICS_CACHE_FACE_THRESHOLD) {
-      const metrics = this.topologyMetrics();
-      const closedFromMetrics = metrics.boundaryEdges === 0;
-      this._isClosedVolumeCache = closedFromMetrics;
+      this._isClosedVolumeCache = closedFromMetrics;
+      return closedFromMetrics;
+    }
+
+    if (this._trustedBooleanInput) {
+      const metrics = this.topologyMetrics();
+      const closedFromMetrics = metrics.boundaryEdges === 0;
+      this._isClosedVolumeCache = closedFromMetrics;
+      return closedFromMetrics;
+    }
+
+    ensureInit();
+    if (this.faceCount >= Mesh.TOPOLOGY_METRICS_CACHE_FACE_THRESHOLD) {
+      const metrics = this.topologyMetrics();
+      const closedFromMetrics = metrics.boundaryEdges === 0;
+      this._isClosedVolumeCache = closedFromMetrics;
       return closedFromMetrics;
     }
 
@@ -2206,30 +2595,30 @@ export class Mesh {
     return closed;
   }
 
-  /**
-   * Return topology metrics for this triangulated mesh.
-   *
-   * For trusted boolean buffers we preserve raw index topology, which is closer
-   * to MeshGL semantics where same-position seam vertices can stay distinct.
-   * For ordinary triangle soups we continue to use welded-edge metrics.
-   *
-   * `boundaryEdges`: edges referenced by exactly one triangle.
-   * `nonManifoldEdges`: edges referenced by more than two triangles.
-   */
-  topologyMetrics(): { boundaryEdges: number; nonManifoldEdges: number } {
+  /**
+   * Return topology metrics for this triangulated mesh.
+   *
+   * For trusted boolean buffers we preserve raw index topology, which is closer
+   * to MeshGL semantics where same-position seam vertices can stay distinct.
+   * For ordinary triangle soups we continue to use welded-edge metrics.
+   *
+   * `boundaryEdges`: edges referenced by exactly one triangle.
+   * `nonManifoldEdges`: edges referenced by more than two triangles.
+   */
+  topologyMetrics(): { boundaryEdges: number; nonManifoldEdges: number } {
     if (this._topologyMetricsCache) {
       return {
         boundaryEdges: this._topologyMetricsCache.boundaryEdges,
         nonManifoldEdges: this._topologyMetricsCache.nonManifoldEdges,
       };
     }
-
-    ensureInit();
-    const metrics = this._trustedBooleanInput
-      ? mesh_topology_metrics_raw(this._vertexCount, this._buffer)
-      : mesh_topology_metrics(this._vertexCount, this._buffer);
-    const boundaryEdges = Math.floor(metrics[0] ?? 0);
-    const nonManifoldEdges = Math.floor(metrics[1] ?? 0);
+
+    ensureInit();
+    const metrics = this._trustedBooleanInput
+      ? mesh_topology_metrics_raw(this._vertexCount, this._buffer)
+      : mesh_topology_metrics(this._vertexCount, this._buffer);
+    const boundaryEdges = Math.floor(metrics[0] ?? 0);
+    const nonManifoldEdges = Math.floor(metrics[1] ?? 0);
     this._topologyMetricsCache = { boundaryEdges, nonManifoldEdges };
     if (this._isClosedVolumeCache === null) {
       this._isClosedVolumeCache = boundaryEdges === 0;