okgeometry-api 1.16.0 → 1.17.0

package/src/GeometryBoolean.ts

@@ -0,0 +1,863 @@
+import { Mesh } from "./Mesh.js";
+import { Brep } from "./Brep.js";
+import { NurbsSurface } from "./NurbsSurface.js";
+import { NurbsCurve } from "./NurbsCurve.js";
+import { Polyline } from "./Polyline.js";
+import { Polygon } from "./Polygon.js";
+import { PolyCurve } from "./PolyCurve.js";
+import { Arc } from "./Arc.js";
+import { Circle } from "./Circle.js";
+import { Line } from "./Line.js";
+import { Point } from "./Point.js";
+import type { SweepableCurve } from "./types.js";
+
+/**
+ * Universal geometry boolean dispatcher, the single source of truth for
+ * "any geometry x any geometry" boolean semantics. Both okdraw and oknodes
+ * consume this module instead of re-implementing the dispatch matrix.
+ *
+ * Operands are classified by EFFECTIVE DIMENSION (what the geometry actually
+ * is, not what class it arrived as):
+ * - brep solid — closed Brep
+ * - brep sheet — open Brep, or a NurbsSurface (via Brep.fromSurface)
+ * - mesh solid — closed-volume triangle mesh
+ * - mesh sheet — open triangle mesh
+ * - curve — NurbsCurve, Polyline, Polygon (a Polyline subclass, always
+ *   closed), PolyCurve, Arc, Circle, Line (all coerce to an exact
+ *   NurbsCurve; piecewise-linear inputs keep their native polyline where
+ *   polyline ops are cheaper or exact)
+ *
+ * Closedness caveat: curve closedness is decided by each operand's own
+ * isClosed() test, which for NurbsCurve / Polyline / PolyCurve is an
+ * ENDPOINT-PROXIMITY gate — start and end must coincide within 1e-10
+ * (Arc closes on a full 2π sweep; Circle and Polygon are always closed).
+ * A curve whose endpoints coincide within that tolerance therefore gets the
+ * closed-curve semantics (region booleans); a curve with a genuine endpoint
+ * gap gets the open-curve semantics (no region booleans,
+ * point-intersections). The region-boolean kernel re-verifies closure with a
+ * scale-relative tolerance and rejects open curves instead of silently
+ * chord-closing them.
+ *
+ * Result kinds follow the dimension of the result set:
+ * - solid/sheet x solid/sheet — 'brep' (parametric path) or 'mesh'
+ *   (tessellated path, the documented downgrade when the parametric
+ *   pipeline is unavailable or fails)
+ * - curve x solid — 'curves' (clip pieces)
+ * - curve x sheet — 'points' (crossings) for intersect, 'curves' for subtract
+ * - curve x curve — 'curves' (region boundaries) when both are closed +
+ *   coplanar (Rhino CurveBoolean); 'points' for intersect of open curves
+ *
+ * Unsupported combinations throw typed, actionable errors.
+ */
+
+export type BooleanOpKind = "union" | "subtract" | "intersect";
+
+export type BooleanOperand =
+  | Mesh
+  | Brep
+  | NurbsSurface
+  | NurbsCurve
+  | Polyline
+  | Polygon
+  | PolyCurve
+  | Arc
+  | Circle
+  | Line;
+
+export interface GeometryBooleanOptions {
+  /**
+   * PARAMETRIC tolerance: the SSI edge / classification tolerance of the
+   * exact BREP paths (default 1e-6). It is NEVER used as a tessellation
+   * tolerance — feeding an SSI-grade tolerance to toMesh would produce
+   * pathologically dense fallback meshes.
+   */
+  tolerance?: number;
+  /**
+   * TESSELLATION tolerance: used whenever a BREP/surface must be converted
+   * to a mesh (toMesh conversions, tessellated fallbacks, side-probe
+   * meshes). When omitted the default is SCALE-RELATIVE: the combined
+   * operands' bounds diagonal × 2e-3 (the render pipeline's recipe), floored
+   * at 1e-6 — an absolute default breaks mm-scale models (degenerate probe
+   * tessellations) and wastes time on 100 m models. An explicit value always
+   * wins.
+   */
+  meshTolerance?: number;
+}
+
+export interface GeometryBooleanResult {
+  kind: "brep" | "mesh" | "curves" | "points";
+  /** Single BREP result (set when the result is exactly one BREP). */
+  brep?: Brep;
+  /** All BREP pieces ('brep' results always set this, booleans have one entry). */
+  breps?: Brep[];
+  /** Merged mesh result (all pieces in one multi-component mesh). */
+  mesh?: Mesh;
+  /** Individual mesh pieces ('mesh' results always set this). */
+  meshes?: Mesh[];
+  /** Curve pieces. NurbsCurve pieces are exact (they lie exactly on the input curve); Polyline pieces come from polyline-native or tessellated paths. */
+  curves?: (NurbsCurve | Polyline)[];
+  /** Intersection points. */
+  points?: Point[];
+}
+
+/** Fallback tessellation tolerance when no operand yields usable bounds. */
+const DEFAULT_TESS_TOLERANCE = 0.005;
+/** Scale-relative default: bounds diagonal × this (render pipeline recipe). */
+const MESH_TOLERANCE_DIAG_FACTOR = 2e-3;
+/** Absolute floor for the scale-relative default. */
+const MESH_TOLERANCE_FLOOR = 1e-6;
+/** Coarse probe tolerance for BREP bounds estimation (minimal tessellation). */
+const BOUNDS_PROBE_TOLERANCE = 1e6;
+
+// ── operand classification ──────────────────────────────────────────
+
+interface SurfaceLikeOperand {
+  kind: "brep" | "mesh";
+  closed: boolean;
+  brep?: Brep;
+  mesh?: Mesh;
+}
+
+interface CurveOperand {
+  kind: "curve";
+  raw: BooleanOperand;
+  closed: boolean;
+  /** Native polyline when the input was already piecewise linear (exact). */
+  polyline: Polyline | null;
+  /** Exact NURBS coercion (lazy, cached). */
+  nurbs: () => NurbsCurve;
+}
+
+type Operand = SurfaceLikeOperand | CurveOperand;
+
+function cached<T>(build: () => T): () => T {
+  let value: T | null = null;
+  return () => {
+    if (value === null) value = build();
+    return value;
+  };
+}
+
+const TAU = Math.PI * 2;
+
+function classifyOperand(operand: BooleanOperand, label: string): Operand {
+  if (operand instanceof Brep) {
+    return { kind: "brep", closed: operand.isClosed(), brep: operand };
+  }
+  if (operand instanceof NurbsSurface) {
+    // A surface is an (untrimmed) sheet; the sheet BREP carries the exact
+    // surface so the parametric paths stay exact.
+    return { kind: "brep", closed: false, brep: Brep.fromSurface(operand) };
+  }
+  if (operand instanceof Mesh) {
+    return { kind: "mesh", closed: operand.isClosedVolume(), mesh: operand };
+  }
+  if (operand instanceof NurbsCurve) {
+    return {
+      kind: "curve",
+      raw: operand,
+      closed: operand.isClosed(),
+      polyline: null,
+      nurbs: () => operand,
+    };
+  }
+  if (operand instanceof Polyline) {
+    // Polygon extends Polyline with automatic closure, so it lands here and
+    // classifies as a CLOSED polyline (region-boolean capable).
+    return {
+      kind: "curve",
+      raw: operand,
+      closed: operand.isClosed(),
+      polyline: operand,
+      nurbs: cached(() => NurbsCurve.fromPoints(1, operand.points)),
+    };
+  }
+  if (operand instanceof Line) {
+    const polyline = new Polyline([operand.start, operand.end]);
+    return {
+      kind: "curve",
+      raw: operand,
+      closed: false,
+      polyline,
+      nurbs: cached(() => NurbsCurve.fromLine(operand)),
+    };
+  }
+  if (operand instanceof Arc) {
+    const closed = Math.abs(operand.endAngle - operand.startAngle) >= TAU - 1e-9;
+    return {
+      kind: "curve",
+      raw: operand,
+      closed,
+      polyline: null,
+      nurbs: cached(() => NurbsCurve.fromArc(operand)),
+    };
+  }
+  if (operand instanceof Circle) {
+    return {
+      kind: "curve",
+      raw: operand,
+      closed: true,
+      polyline: null,
+      nurbs: cached(() =>
+        NurbsCurve.fromArc(new Arc(operand.center, operand.radius, 0, TAU, operand.normal)),
+      ),
+    };
+  }
+  if (operand instanceof PolyCurve) {
+    return {
+      kind: "curve",
+      raw: operand,
+      closed: operand.isClosed(),
+      polyline: null,
+      nurbs: cached(() => operand.toNurbs()),
+    };
+  }
+  throw new Error(
+    `geometryBoolean operand ${label} has an unsupported type, expected `
+    + "Mesh, Brep, NurbsSurface, NurbsCurve, Polyline, Polygon, PolyCurve, "
+    + "Arc, Circle, or Line",
+  );
+}
+
+function operandMesh(operand: SurfaceLikeOperand, tolerance: number): Mesh {
+  if (operand.mesh) return operand.mesh;
+  return operand.brep!.toMesh(tolerance);
+}
+
+// ── scale-relative tessellation tolerance ───────────────────────────
+
+interface BoundsAcc {
+  minX: number;
+  minY: number;
+  minZ: number;
+  maxX: number;
+  maxY: number;
+  maxZ: number;
+}
+
+/**
+ * Accumulate an operand's world bounds for the scale-relative default
+ * tessellation tolerance. Mesh operands use their exact vertex bounds; BREP
+ * operands use a MINIMAL probe tessellation (huge chordal tolerance → one
+ * segment per knot span — cheap, and adequate for a scale estimate); curve
+ * operands use their polyline points or NURBS control points (a convex-hull
+ * bound). Operands that fail to yield bounds are skipped.
+ */
+function accumulateOperandBounds(operand: Operand, acc: BoundsAcc): void {
+  const add = (x: number, y: number, z: number): void => {
+    acc.minX = Math.min(acc.minX, x);
+    acc.minY = Math.min(acc.minY, y);
+    acc.minZ = Math.min(acc.minZ, z);
+    acc.maxX = Math.max(acc.maxX, x);
+    acc.maxY = Math.max(acc.maxY, y);
+    acc.maxZ = Math.max(acc.maxZ, z);
+  };
+  try {
+    if (operand.kind === "curve") {
+      const points = operand.polyline
+        ? operand.polyline.points
+        : operand.nurbs().controlPoints;
+      for (const p of points) add(p.x, p.y, p.z);
+      return;
+    }
+    const mesh = operand.mesh ?? operand.brep!.tessellate(BOUNDS_PROBE_TOLERANCE);
+    const bounds = mesh.getBounds();
+    add(bounds.min.x, bounds.min.y, bounds.min.z);
+    add(bounds.max.x, bounds.max.y, bounds.max.z);
+  } catch {
+    // Bounds are a scale ESTIMATE — a failing operand is skipped, never fatal.
+  }
+}
+
+/**
+ * Resolve the tessellation tolerance: an explicit `meshTolerance` wins;
+ * otherwise combined-operand bounds diagonal × 2e-3 (floored at 1e-6), so
+ * mm-scale models get mm-scale probe tessellations and 100 m models don't
+ * over-tessellate. Falls back to the legacy 0.005 when no operand yields
+ * bounds.
+ */
+function resolveMeshTolerance(
+  options: GeometryBooleanOptions | undefined,
+  ...operands: Operand[]
+): number {
+  if (options?.meshTolerance !== undefined) return options.meshTolerance;
+  const acc: BoundsAcc = {
+    minX: Infinity,
+    minY: Infinity,
+    minZ: Infinity,
+    maxX: -Infinity,
+    maxY: -Infinity,
+    maxZ: -Infinity,
+  };
+  for (const operand of operands) accumulateOperandBounds(operand, acc);
+  if (!Number.isFinite(acc.minX) || !Number.isFinite(acc.maxX)) {
+    return DEFAULT_TESS_TOLERANCE;
+  }
+  const diag = Math.hypot(acc.maxX - acc.minX, acc.maxY - acc.minY, acc.maxZ - acc.minZ);
+  if (!(diag > 0)) return DEFAULT_TESS_TOLERANCE;
+  return Math.max(diag * MESH_TOLERANCE_DIAG_FACTOR, MESH_TOLERANCE_FLOOR);
+}
+
+/** A parametric-path operand plus whether it was COERCED from a mesh. */
+interface ParametricOperand {
+  brep: Brep;
+  coercedFromMesh: boolean;
+}
+
+/**
+ * Try to view a surface-like operand as a BREP for the parametric paths.
+ * Mesh operands convert via Brep.fromMesh with a 512-face guard (planar
+ * faceted solids only, densely tessellated curved meshes fall back to the
+ * mesh path instead of producing a pathological per-triangle BREP).
+ *
+ * Facet-planarity heuristic: fromMesh can "succeed" on a curved closed mesh
+ * under the face guard by emitting nearly one BREP face per triangle. A BREP
+ * face count CLOSE TO the mesh triangle count means barely any coplanar
+ * clustering happened — reject it (mesh path) instead of running the exact
+ * pipeline on a per-facet pseudo-BREP. The threshold is tris × 0.55: a
+ * quad-faceted planar solid legitimately has faces ≈ tris / 2 (every planar
+ * face triangulated as one quad), so a tris / 3 cutoff wrongly rejected it,
+ * while a per-facet pseudo-BREP (faces ≈ tris) still lands far above 0.55.
+ */
+function tryOperandBrep(operand: SurfaceLikeOperand): ParametricOperand | null {
+  if (operand.brep) return { brep: operand.brep, coercedFromMesh: false };
+  if (!operand.closed) return null; // Brep.fromMesh rejects open meshes.
+  try {
+    const mesh = operand.mesh!;
+    const brep = Brep.fromMesh(mesh, { maxFaces: 512 });
+    if (brep.faceCount > Math.max(32, mesh.faceCount * 0.55)) {
+      return null;
+    }
+    return { brep, coercedFromMesh: true };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The parametric BREP pipeline runs only when at least one operand arrived
+ * as exact geometry (Brep or NurbsSurface); mesh x mesh pairs always use the
+ * mesh kernel directly.
+ */
+function shouldTryParametric(a: SurfaceLikeOperand, b: SurfaceLikeOperand): boolean {
+  return a.kind === "brep" || b.kind === "brep";
+}
+
+/**
+ * Sample a curve operand into a polyline with KNOWN uniform parameters:
+ * point i sits at curve parameter i / segmentCount (closed) or
+ * i / (sampleCount - 1) (open), so mesh-side hits map back to curve
+ * parameters via (segmentIndex + segmentT) / segmentCount.
+ *
+ * Polyline-NATIVE operands never reach this sampler — every dispatch row
+ * handles `operand.polyline` on a native path first; a polyline that did
+ * arrive here would simply sample its exact degree-1 NURBS coercion.
+ */
+function sampleCurveOperand(
+  operand: CurveOperand,
+  samples = 128,
+): { points: Point[]; closed: boolean; segmentCount: number } {
+  const curve = operand.nurbs();
+  const points: Point[] = [];
+  if (operand.closed) {
+    // Closed sampling omits the duplicate seam point and flags closedness
+    // explicitly; segment i runs i/n to (i+1)/n with the wrap segment last.
+    for (let i = 0; i < samples; i++) points.push(curve.pointAt(i / samples));
+    return { points, closed: true, segmentCount: samples };
+  }
+  for (let i = 0; i < samples; i++) points.push(curve.pointAt(i / (samples - 1)));
+  return { points, closed: false, segmentCount: samples - 1 };
+}
+
+/**
+ * Which side of an oriented sheet mesh a crossing-free curve piece lies on.
+ *
+ * Classifies probe POINTS — interior parameter samples of the piece — by
+ * their signed side against the sheet, each through a tiny 2-point probe
+ * polyline (a crossing-free micro-span classifies by its midpoint's signed
+ * side, i.e. a point probe). Points are used instead of clipping whole
+ * probe CHORDS between distant samples: a chord can shortcut across a
+ * curved sheet (crossing it even though the curve piece does not) and
+ * misclassify, and a degenerate micro-piece chord probe can throw and abort
+ * the whole operation.
+ *
+ * Robustness contract: a sample whose probe fails (degenerate span) is
+ * skipped; a piece with no classifiable samples, or an exact tie, defaults
+ * to "front" — the documented ON convention (a sheet's material is the
+ * CLOSED front half-space, so on-sheet pieces belong to the front and are
+ * dropped by subtract). This function never throws.
+ */
+function pieceSideOfSheet(piece: NurbsCurve, sheetMesh: Mesh): "front" | "back" {
+  let front = 0;
+  let back = 0;
+  for (let i = 1; i <= 5; i++) {
+    const t = i / 6;
+    const p = piece.pointAt(t);
+    // Tiny tangent-direction partner keeps the probe span on the sample's
+    // side of the sheet (the piece is crossing-free).
+    const q = piece.pointAt(Math.min(1, t + 1e-3));
+    try {
+      const groups = sheetMesh.clipPolylineBySheet([p, q], false);
+      const total = (list: Polyline[]) => list.reduce((sum, pl) => sum + pl.length(), 0);
+      const inside = total(groups.inside);
+      const outside = total(groups.outside);
+      if (inside > outside) front++;
+      else if (outside > inside) back++;
+    } catch {
+      // Degenerate probe: skip this sample, never abort the operation.
+    }
+  }
+  return back > front ? "back" : "front";
+}
+
+// ── result assembly ─────────────────────────────────────────────────
+
+function brepResult(pieces: (Brep | null | undefined)[]): GeometryBooleanResult {
+  const breps = pieces.filter((piece): piece is Brep => piece != null);
+  return {
+    kind: "brep",
+    breps,
+    brep: breps.length === 1 ? breps[0] : undefined,
+  };
+}
+
+function meshResult(pieces: Mesh[]): GeometryBooleanResult {
+  if (pieces.length === 0) return { kind: "mesh", meshes: [] };
+  const mesh = pieces.length === 1 ? pieces[0] : Mesh.mergeMeshes(pieces);
+  return { kind: "mesh", mesh, meshes: pieces };
+}
+
+function curvesResult(curves: (NurbsCurve | Polyline)[]): GeometryBooleanResult {
+  return { kind: "curves", curves };
+}
+
+function pointsResult(points: Point[]): GeometryBooleanResult {
+  return { kind: "points", points };
+}
+
+// ── curve x curve region booleans ───────────────────────────────────
+
+/**
+ * 2D region boolean between two CLOSED coplanar curve operands (Rhino
+ * CurveBoolean). Both operands are coerced to exact NURBS; the kernel fits a
+ * common plane, verifies coplanarity, and returns the result region boundary
+ * loops (polyline fidelity — outer CCW, holes CW). Throws with a clear message
+ * when the curves are not coplanar.
+ */
+function regionBoolean(
+  a: CurveOperand,
+  b: CurveOperand,
+  op: BooleanOpKind,
+): (NurbsCurve | Polyline)[] {
+  const na = a.nurbs();
+  const nb = b.nurbs();
+  switch (op) {
+    case "union":
+      return na.regionUnion(nb);
+    case "subtract":
+      return na.regionSubtract(nb);
+    case "intersect":
+      return na.regionIntersect(nb);
+  }
+}
+
+// ── surface-like x surface-like ─────────────────────────────────────
+
+function meshBoolean(
+  a: SurfaceLikeOperand,
+  b: SurfaceLikeOperand,
+  op: BooleanOpKind,
+  tolerance: number,
+): GeometryBooleanResult {
+  const meshA = operandMesh(a, tolerance);
+  const meshB = operandMesh(b, tolerance);
+
+  if (a.closed && !b.closed) {
+    // solid x sheet: cut the solid along the oriented sheet and keep the
+    // CAPPED half, matching the parametric solid/sheet convention
+    // (subtract keeps the half behind the sheet normal, intersect the front).
+    const split = meshA.splitSolidBySurface(meshB);
+    return meshResult(op === "subtract" ? split.outside : split.inside);
+  }
+  if (!a.closed && (b.closed || op !== "union")) {
+    // sheet x solid trims by containment; sheet x sheet subtract/intersect
+    // classify by the other sheet's signed side (back/front).
+    const split = meshA.split(meshB);
+    return meshResult(op === "subtract" ? split.outside : split.inside);
+  }
+  if (op === "union") {
+    // closed x closed volumetric union, or open x open sheet union
+    // (mutual trim + join) — Mesh.union dispatches on closedness.
+    return meshResult([meshA.union(meshB)]);
+  }
+  return meshResult([op === "subtract" ? meshA.subtract(meshB) : meshA.intersect(meshB)]);
+}
+
+function surfaceBoolean(
+  a: SurfaceLikeOperand,
+  b: SurfaceLikeOperand,
+  op: BooleanOpKind,
+  options?: GeometryBooleanOptions,
+): GeometryBooleanResult {
+  // Union of a solid and a sheet is not defined in ANY representation, and
+  // this is a semantic error, never a fallback trigger.
+  if (op === "union" && a.closed !== b.closed) {
+    throw new Error(
+      "Union of a solid and a sheet is not defined, trim the sheet with "
+      + "subtract or intersect, or close the sheet into a solid first",
+    );
+  }
+
+  if (shouldTryParametric(a, b)) {
+    const brepA = tryOperandBrep(a);
+    const brepB = tryOperandBrep(b);
+    if (brepA && brepB) {
+      try {
+        const parametricOptions =
+          options?.tolerance !== undefined ? { tolerance: options.tolerance } : undefined;
+        const result =
+          op === "union"
+            ? brepA.brep.unionBrep(brepB.brep, parametricOptions)
+            : op === "subtract"
+              ? brepA.brep.subtractBrep(brepB.brep, parametricOptions)
+              : brepA.brep.intersectBrep(brepB.brep, parametricOptions);
+        // Validation gate for COERCED mesh operands: fromMesh conversion can
+        // hand the exact pipeline a borderline pseudo-BREP; when both inputs
+        // are closed, the boolean of two solids must come back closed —
+        // otherwise reject the parametric result and use the mesh path.
+        if (
+          (brepA.coercedFromMesh || brepB.coercedFromMesh)
+          && a.closed && b.closed
+          && result.faceCount > 0
+          && !result.isClosed()
+        ) {
+          throw new Error("parametric result of coerced mesh operand is not closed");
+        }
+        return brepResult([result]);
+      } catch {
+        // Documented downgrade: the parametric pipeline failed, fall back to
+        // the tessellated mesh path below.
+      }
+    }
+  }
+
+  return meshBoolean(a, b, op, resolveMeshTolerance(options, a, b));
+}
+
+// ── curve x surface-like ────────────────────────────────────────────
+
+function curveSolidPieces(
+  curve: CurveOperand,
+  solid: SurfaceLikeOperand,
+): { inside: (NurbsCurve | Polyline)[]; outside: (NurbsCurve | Polyline)[] } {
+  if (solid.kind === "brep") {
+    // Exact: knot-insertion split + containment classification.
+    return curve.nurbs().clipByBrep(solid.brep!);
+  }
+  if (curve.polyline) {
+    return solid.mesh!.clipPolyline(curve.polyline);
+  }
+  // Exact curve against a mesh solid: tessellated clip (documented
+  // approximation, pieces come back as Polylines). Pass the solid as a Brep
+  // for the exact path instead.
+  const sampled = sampleCurveOperand(curve);
+  return solid.mesh!.clipPolyline(sampled.points, sampled.closed);
+}
+
+function curveSheetCrossings(curve: CurveOperand, sheet: SurfaceLikeOperand): Point[] {
+  if (sheet.kind === "brep") {
+    return sheet.brep!.intersectCurve(curve.nurbs()).map((hit) => hit.point);
+  }
+  const sampled = curve.polyline
+    ? { points: curve.polyline.points, closed: curve.closed }
+    : sampleCurveOperand(curve);
+  return sheet
+    .mesh!.intersectPolyline(sampled.points, sampled.closed)
+    .map((hit) => hit.point);
+}
+
+function curveMinusSheet(
+  curve: CurveOperand,
+  sheet: SurfaceLikeOperand,
+  tolerance: number,
+): (NurbsCurve | Polyline)[] {
+  if (sheet.kind === "brep") {
+    // Exact split parameters from the trim-checked curve x BREP hits, then
+    // exact knot-insertion splitting; side classification uses the
+    // tessellated sheet (no exact open-sheet clip exists, clipCurve
+    // requires a closed solid).
+    const hits = sheet.brep!.intersectCurve(curve.nurbs());
+    const pieces = curve
+      .nurbs()
+      .splitAtParams(hits.map((hit) => hit.curveParam), curve.closed);
+    const sheetMesh = sheet.brep!.toMesh(tolerance);
+    return pieces.filter((piece) => pieceSideOfSheet(piece, sheetMesh) === "back");
+  }
+  if (curve.polyline) {
+    return sheet.mesh!.clipPolylineBySheet(curve.polyline).outside;
+  }
+  // Exact curve against a mesh sheet: exact split at sampled-hit parameters
+  // (hit parameters are exact in parameter space up to chord deviation),
+  // then signed-side classification per piece.
+  const sampled = sampleCurveOperand(curve);
+  const hits = sheet.mesh!.intersectPolyline(sampled.points, sampled.closed);
+  const params = hits.map((hit) => (hit.segmentIndex + hit.segmentT) / sampled.segmentCount);
+  const pieces = curve.nurbs().splitAtParams(params, curve.closed);
+  return pieces.filter((piece) => pieceSideOfSheet(piece, sheet.mesh!) === "back");
+}
+
+function curveSurfaceBoolean(
+  curve: CurveOperand,
+  other: SurfaceLikeOperand,
+  op: BooleanOpKind,
+  curveIsFirst: boolean,
+  options?: GeometryBooleanOptions,
+): GeometryBooleanResult {
+  if (op === "union") {
+    throw new Error(
+      "Union with a curve operand is not defined, curves have no area or volume",
+    );
+  }
+  if (op === "subtract" && !curveIsFirst) {
+    throw new Error(
+      "Subtracting a curve from a solid or sheet is not defined, curves have "
+      + "no volume or area to remove",
+    );
+  }
+
+  if (other.closed) {
+    // curve x solid: intersect keeps the inside pieces, subtract the outside.
+    const pieces = curveSolidPieces(curve, other);
+    return curvesResult(op === "intersect" ? pieces.inside : pieces.outside);
+  }
+
+  // curve x sheet: the intersection set is the crossing POINTS; subtract
+  // keeps the pieces behind the sheet normal. The tessellation tolerance is
+  // resolved LAZILY here — the exact paths above never pay the bounds probe.
+  if (op === "intersect") {
+    return pointsResult(curveSheetCrossings(curve, other));
+  }
+  return curvesResult(curveMinusSheet(curve, other, resolveMeshTolerance(options, curve, other)));
+}
+
+// ── public API: boolean ─────────────────────────────────────────────
+
+/**
+ * Boolean of any two geometries, dispatched by effective dimension.
+ *
+ * Dispatch matrix (A x B):
+ * - brep x brep (any closedness) — parametric unionBrep/subtractBrep/
+ *   intersectBrep (sheet-capable) returning kind 'brep'; parametric failures
+ *   fall back to the tessellated mesh path (kind 'mesh').
+ * - brep x mesh — the closed mesh side is converted with Brep.fromMesh
+ *   (planar-faceted) for the parametric path; otherwise tessellated mesh ops.
+ * - mesh x mesh — solid x solid runs CSG; a sheet operand uses the
+ *   split-based trim semantics (subtract keeps outside/back, intersect keeps
+ *   inside/front; solid x sheet returns the CAPPED clicked-side halves);
+ *   sheet union sheet runs the kernel mutual trim + join. A sheet's material
+ *   is its FRONT half-space, so the sheet union keeps each sheet's pieces
+ *   BEHIND the other (front pieces are interior to the union material);
+ *   uncut regions are kept, coincident overlaps keep A's copy.
+ * - union of a solid and a sheet (any representation) throws.
+ * - curve x solid — intersect keeps the inside clip pieces, subtract the
+ *   outside pieces (kind 'curves'); union throws.
+ * - curve x sheet — intersect returns the crossing points (kind 'points');
+ *   subtract keeps the pieces behind the sheet normal (kind 'curves').
+ * - curve x curve — when BOTH curves are closed and coplanar, union /
+ *   subtract / intersect are 2D REGION booleans (Rhino CurveBoolean): the
+ *   result is the region boundary CURVES (kind 'curves', outer CCW / holes
+ *   CW, polyline fidelity). For open curves, intersect returns the crossing
+ *   POINTS (kind 'points') and union / subtract throw (open curves bound no
+ *   region). Note: region-intersect returns the overlapping region's
+ *   BOUNDARY, distinct from the point-set intersection of the open case.
+ */
+export function geometryBoolean(
+  a: BooleanOperand,
+  b: BooleanOperand,
+  op: BooleanOpKind,
+  options?: GeometryBooleanOptions,
+): GeometryBooleanResult {
+  const oa = classifyOperand(a, "A");
+  const ob = classifyOperand(b, "B");
+
+  if (oa.kind === "curve" && ob.kind === "curve") {
+    // Two CLOSED coplanar curves bound 2D regions, so union / subtract /
+    // intersect are the REGION booleans (Rhino CurveBoolean). The region
+    // op returns the boundary CURVES (outer CCW, holes CW). Coplanarity is
+    // verified kernel-side; a non-coplanar pair throws with a clear message.
+    if (oa.closed && ob.closed) {
+      return curvesResult(regionBoolean(oa, ob, op));
+    }
+    // Open curves cannot bound a region. Intersect still returns the crossing
+    // POINTS (the meaningful lower-dimensional result); union / subtract of an
+    // open curve is undefined.
+    if (op !== "intersect") {
+      throw new Error(
+        `Boolean ${op} of two curves requires BOTH curves to be closed and `
+        + "coplanar (open curves bound no region)",
+      );
+    }
+    const hits = oa.nurbs().intersectCurveParams(ob.nurbs());
+    return pointsResult(hits.map((hit) => hit.point));
+  }
+
+  if (oa.kind === "curve") {
+    return curveSurfaceBoolean(oa, ob as SurfaceLikeOperand, op, true, options);
+  }
+  if (ob.kind === "curve") {
+    return curveSurfaceBoolean(ob, oa, op, false, options);
+  }
+
+  return surfaceBoolean(oa, ob, op, options);
+}
+
+// ── public API: split ───────────────────────────────────────────────
+
+function splitCurveByOperand(
+  curve: CurveOperand,
+  blade: Operand,
+): GeometryBooleanResult {
+  if (blade.kind === "curve") {
+    // Two CLOSED coplanar curves → REGION split (Rhino "region split"): the
+    // arrangement of the two loops partitions the plane into all its regions,
+    // returned as closed boundary curves (outer CCW, holes CW).
+    if (curve.closed && blade.closed) {
+      return curvesResult(curve.nurbs().regionSplit(blade.nurbs()));
+    }
+    // Otherwise split THIS curve exactly at every crossing parameter (the
+    // blade is untouched), the pre-region behavior.
+    const hits = curve.nurbs().intersectCurveParams(blade.nurbs());
+    return curvesResult(
+      curve.nurbs().splitAtParams(hits.map((hit) => hit.paramA), curve.closed),
+    );
+  }
+  if (blade.kind === "brep") {
+    if (blade.closed) {
+      // Exact containment clip, all pieces (inside then outside).
+      const clipped = curve.nurbs().clipByBrep(blade.brep!);
+      return curvesResult([...clipped.inside, ...clipped.outside]);
+    }
+    const hits = blade.brep!.intersectCurve(curve.nurbs());
+    return curvesResult(
+      curve.nurbs().splitAtParams(hits.map((hit) => hit.curveParam), curve.closed),
+    );
+  }
+  // Mesh blade (open or closed): polyline-native input splits natively;
+  // exact curves split EXACTLY at the sampled-hit parameters so the pieces
+  // stay on the curve.
+  if (curve.polyline) {
+    return curvesResult(blade.mesh!.splitPolyline(curve.polyline));
+  }
+  const sampled = sampleCurveOperand(curve);
+  const hits = blade.mesh!.intersectPolyline(sampled.points, sampled.closed);
+  const params = hits.map((hit) => (hit.segmentIndex + hit.segmentT) / sampled.segmentCount);
+  return curvesResult(curve.nurbs().splitAtParams(params, curve.closed));
+}
+
+function splitSurfaceByOperand(
+  a: SurfaceLikeOperand,
+  blade: Operand,
+  options?: GeometryBooleanOptions,
+): GeometryBooleanResult {
+  if (blade.kind === "curve") {
+    if (!blade.closed) {
+      throw new Error(
+        "geometrySplit: an OPEN curve cannot cut a solid or sheet — only a "
+        + "CLOSED planar curve acts as a through-cut blade; close the curve "
+        + "(or use a Polygon), or split with a sheet or solid blade instead",
+      );
+    }
+    // Closed planar blade curves become through-cut cutter solids
+    // (Mesh.split's curve mode). BREP hosts tessellate first (documented
+    // downgrade).
+    const hostMesh = operandMesh(a, resolveMeshTolerance(options, a, blade));
+    const split = hostMesh.split(blade.raw as SweepableCurve);
+    return meshResult([...split.outside, ...split.inside]);
+  }
+
+  const parametricOptions =
+    options?.tolerance !== undefined ? { tolerance: options.tolerance } : undefined;
+
+  // Parametric splits where an exact pipeline exists (only when at least one
+  // side arrived as exact geometry, mesh x mesh always splits in the mesh
+  // kernel).
+  if (shouldTryParametric(a, blade)) {
+    const brepA = tryOperandBrep(a);
+    const brepB = tryOperandBrep(blade);
+    if (brepA && brepB) {
+      try {
+        if (a.closed && !blade.closed) {
+          const halves = brepA.brep.splitBySheet(brepB.brep, parametricOptions);
+          // Validation gate for coerced-mesh hosts: a genuine cut of a closed
+          // solid must yield closed halves, else use the mesh path.
+          if (
+            brepA.coercedFromMesh
+            && [halves.negative, halves.positive].some(
+              (h) => h != null && h.faceCount > 0 && !h.isClosed(),
+            )
+          ) {
+            throw new Error("parametric split of coerced mesh host is not closed");
+          }
+          return brepResult([halves.negative, halves.positive]);
+        }
+        if (!a.closed && blade.closed) {
+          const sides = brepA.brep.splitSheetBySolid(brepB.brep, parametricOptions);
+          return brepResult([sides.outside, sides.inside]);
+        }
+        if (!a.closed && !blade.closed) {
+          const sides = brepA.brep.splitSheetBySheet(brepB.brep, parametricOptions);
+          return brepResult([sides.outside, sides.inside]);
+        }
+        // solid / solid has no parametric split pipeline, use the mesh path.
+      } catch {
+        // Documented downgrade: fall through to the tessellated mesh path.
+      }
+    }
+  }
+
+  // Tessellated fallback: the tolerance is resolved LAZILY here so the
+  // parametric success paths above never pay the bounds probe.
+  const tolerance = resolveMeshTolerance(options, a, blade);
+  const hostMesh = operandMesh(a, tolerance);
+  const bladeMesh = operandMesh(blade, tolerance);
+  if (a.closed && !blade.closed) {
+    // Capped halves on both sides of the oriented sheet.
+    const split = hostMesh.splitSolidBySurface(bladeMesh);
+    return meshResult([...split.outside, ...split.inside]);
+  }
+  const split = hostMesh.split(bladeMesh);
+  return meshResult([...split.outside, ...split.inside]);
+}
+
+/**
+ * Split geometry A by blade B, returning ALL pieces of A (the blade is
+ * untouched). Dispatch mirrors {@link geometryBoolean}:
+ * - brep solid / sheet blades use the parametric splitBySheet /
+ *   splitSheetBySolid / splitSheetBySheet pipelines (kind 'brep', both
+ *   sides); failures fall back to the tessellated mesh path.
+ * - mesh hosts use Mesh.split / Mesh.splitSolidBySurface (kind 'mesh',
+ *   outside pieces then inside pieces).
+ * - curve hosts split exactly: clipByBrep (closed BREP blade), exact
+ *   parameters from trim-checked BREP hits (sheet BREP blade),
+ *   splitPolyline or exact splitAtParams (mesh blade). For a closed curve
+ *   host split by a closed coplanar curve blade → 2D REGION split (all region
+ *   boundaries, Rhino "region split"); an open host splits at
+ *   intersectCurveParams hits (curve blade). Kind 'curves'.
+ * - a closed planar curve blade cuts mesh and BREP hosts through
+ *   Mesh.split's curve mode (through-cut cutter); an OPEN curve blade
+ *   against a solid/sheet host throws a typed error (an open curve cannot
+ *   bound a through-cut).
+ */
+export function geometrySplit(
+  a: BooleanOperand,
+  b: BooleanOperand,
+  options?: GeometryBooleanOptions,
+): GeometryBooleanResult {
+  const oa = classifyOperand(a, "A");
+  const ob = classifyOperand(b, "B");
+
+  if (oa.kind === "curve") {
+    return splitCurveByOperand(oa, ob);
+  }
+  return splitSurfaceByOperand(oa, ob, options);
+}