okgeometry-api 1.26.1 → 1.27.0

package/src/NurbsSurface.ts

@@ -1,721 +1,721 @@
-import { ensureInit } from "./engine.js";
-import { Point } from "./Point.js";
-import { Vec3 } from "./Vec3.js";
-import { Plane } from "./Plane.js";
-import { Mesh } from "./Mesh.js";
-import { Polyline } from "./Polyline.js";
-import { Polygon } from "./Polygon.js";
-import { Line } from "./Line.js";
-import { Arc } from "./Arc.js";
-import { PolyCurve } from "./PolyCurve.js";
-import { NurbsCurve } from "./NurbsCurve.js";
-import type { Surface } from "./Surface.js";
-import type { LoftableCurve, RotationAxis } from "./types.js";
-import {
-  decodePointResult,
-  decodeVec3Result,
-  parsePolylineBuffer as parsePolylineBuf,
-} from "./BufferCodec.js";
-import * as wasm from "./wasm-bindings.js";
-
-/**
- * Non-Uniform Rational B-Spline (NURBS) surface backed by WASM.
- * Tensor-product surface defined by a 2D grid of control points.
- *
- * WASM data format: [degree_u, degree_v, num_u, num_v, ...cp(flat)..., ...weights..., ...knots_u..., ...knots_v...]
- */
-export class NurbsSurface implements Surface {
-  private _data: Float64Array;
-
-  /**
-   * Create a new NURBS surface.
-   * @param degreeU - Polynomial degree in U direction
-   * @param degreeV - Polynomial degree in V direction
-   * @param controlPoints - 2D grid of control points [u][v]
-   * @param weights - 2D grid of weights corresponding to control points
-   * @param knotsU - Knot vector in U direction
-   * @param knotsV - Knot vector in V direction
-   */
-  constructor(
-    public readonly degreeU: number,
-    public readonly degreeV: number,
-    public readonly controlPoints: Point[][],
-    public readonly weights: number[][],
-    public readonly knotsU: number[],
-    public readonly knotsV: number[]
-  ) {
-    this._data = NurbsSurface.encode(degreeU, degreeV, controlPoints, weights, knotsU, knotsV);
-  }
-
-  /**
-   * Rotate this surface around an axis.
-   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
-   * @param angle - Rotation angle in radians
-   * @returns New rotated surface
-   */
-  rotate(axis: RotationAxis, angle: number): NurbsSurface {
-    return new NurbsSurface(
-      this.degreeU,
-      this.degreeV,
-      this.controlPoints.map(row => row.map(p => p.rotate(axis, angle))),
-      this.weights,
-      this.knotsU,
-      this.knotsV
-    );
-  }
-
-  /**
-   * Translate this surface by an offset vector.
-   * @param offset - Translation vector
-   * @returns New translated surface
-   */
-  translate(offset: Vec3): NurbsSurface {
-    const newCps = this.controlPoints.map(row => row.map(p => p.add(offset)));
-    return new NurbsSurface(
-      this.degreeU,
-      this.degreeV,
-      newCps,
-      this.weights,
-      this.knotsU,
-      this.knotsV
-    );
-  }
-
-  /**
-   * Apply a row-major 4x4 AFFINE matrix to this surface. NURBS are invariant
-   * under affine maps of their control net, so rigid transforms, scaling
-   * (uniform or not) and shear are EXACT — weights and knots are unchanged.
-   * @param matrix - Row-major 4x4 matrix (16 entries)
-   * @returns New transformed surface
-   */
-  applyMatrix(matrix: number[] | Float64Array): NurbsSurface {
-    const newCps = this.controlPoints.map(row => row.map(p => p.applyMatrix(matrix)));
-    return new NurbsSurface(
-      this.degreeU,
-      this.degreeV,
-      newCps,
-      this.weights,
-      this.knotsU,
-      this.knotsV
-    );
-  }
-
-  /**
-   * Evaluate a point on the surface at parameters (u, v).
-   * @param u - Parameter in U direction [0, 1]
-   * @param v - Parameter in V direction [0, 1]
-   * @returns Point on surface at (u, v)
-   */
-  evaluate(u: number, v: number): Point {
-    ensureInit();
-    return decodePointResult(wasm.nurbs_surface_evaluate(this._data, u, v));
-  }
-
-  /**
-   * Evaluate the unit normal on the surface at parameters (u, v).
-   * @param u - Parameter in U direction [0, 1]
-   * @param v - Parameter in V direction [0, 1]
-   * @returns Unit surface normal at (u, v)
-   */
-  normal(u: number, v: number): Vec3 {
-    ensureInit();
-    return decodeVec3Result(wasm.nurbs_surface_normal(this._data, u, v));
-  }
-
-  /**
-   * Tessellate this surface into a triangle mesh.
-   * @param uSegs - Number of segments in U direction
-   * @param vSegs - Number of segments in V direction
-   * @returns Mesh approximating the surface
-   */
-  tessellate(uSegs: number, vSegs: number): Mesh {
-    ensureInit();
-    const full = new Float64Array(this._data.length + 2);
-    full.set(this._data);
-    full[this._data.length] = uSegs;
-    full[this._data.length + 1] = vSegs;
-    return Mesh.fromBuffer(wasm.tessellate_nurbs_surface(full));
-  }
-
-  /**
-   * Find intersection curves with a plane.
-   * @param plane - Cutting plane
-   * @param tess - Tessellation resolution for intersection detection (default 20)
-   * @returns Array of polylines representing intersection curves
-   */
-  intersectPlane(plane: Plane, tess = 20): Polyline[] {
-    ensureInit();
-    const buf = wasm.nurbs_surface_plane_intersect(
-      this._data,
-      plane.normal.x, plane.normal.y, plane.normal.z,
-      plane.d,
-      tess
-    );
-    return parsePolylineBuf(buf).map(pts => new Polyline(pts));
-  }
-
-  /**
-   * Find intersection curves with another NURBS surface.
-   * @param other - Other surface to intersect with
-   * @param tess - Tessellation resolution for intersection detection (default 20)
-   * @returns Array of polylines representing intersection curves
-   */
-  intersectSurface(other: NurbsSurface, tess = 20): Polyline[] {
-    ensureInit();
-    const buf = wasm.nurbs_surface_surface_intersect(this._data, other._data, tess);
-    return parsePolylineBuf(buf).map(pts => new Polyline(pts));
-  }
-
-  /**
-   * EXACT intersection curves with another NURBS surface.
-   *
-   * Unlike {@link intersectSurface} (tessellation-based, returns polylines at
-   * a fixed sampling resolution), this runs the parametric boolean's
-   * surface–surface intersection pipeline — seeded tri-tri detection,
-   * chaining, and Newton/tangent-plane relaxation of every point onto the
-   * true intersection — and fits each chain to an interpolating NURBS curve,
-   * densified until the fitted curve stays within `tolerance` of the exact
-   * intersection.
-   *
-   * Closed intersection loops (e.g. cylinder × plane) come back as ONE closed
-   * curve. Coincident (overlapping) surfaces return an empty array — their
-   * overlap is a 2D region, not a curve set.
-   *
-   * @param other - Other surface to intersect with
-   * @param tolerance - Absolute geometric tolerance of the fitted curves
-   *   (model units; floored relative to the combined model scale)
-   * @returns Exact fitted NURBS intersection curves
-   */
-  intersectSurfaceCurves(other: NurbsSurface, tolerance = 1e-6): NurbsCurve[] {
-    ensureInit();
-    const buf = wasm.nurbs_surface_surface_intersect_curves(this._data, other._data, tolerance);
-    return NurbsSurface.parseCurveList(buf);
-  }
-
-  /** Parse [count, (bufLen, curveData…)·count] into NurbsCurves. */
-  private static parseCurveList(buf: Float64Array): NurbsCurve[] {
-    if (buf.length < 1) return [];
-    const out: NurbsCurve[] = [];
-    const count = Number(buf[0]);
-    let offset = 1;
-    for (let k = 0; k < count && offset < buf.length; k++) {
-      const len = Number(buf[offset]);
-      offset += 1;
-      out.push(NurbsCurve.fromData(buf.subarray(offset, offset + len)));
-      offset += len;
-    }
-    return out;
-  }
-
-  /**
-   * Convert any supported curve type to a NurbsCurve.
-   * @param c - Curve to convert
-   * @returns NurbsCurve representation
-   */
-  private static toNurbs(c: LoftableCurve): NurbsCurve {
-    if (c instanceof NurbsCurve) return c;
-    if (c instanceof PolyCurve) return c.toNurbs();
-    if (c instanceof Polygon || c instanceof Polyline) return PolyCurve.byPoints((c as Polyline).points).toNurbs();
-    if (c instanceof Arc) return NurbsCurve.fromArc(c);
-    if (c instanceof Line) return NurbsCurve.fromLine(c);
-    throw new Error(`Unsupported curve type for loft`);
-  }
-
-  /**
-   * Loft a NURBS surface through multiple curves.
-   * Accepts NurbsCurve, PolyCurve, Polyline, Polygon, Arc, or Line.
-   * Automatically converts to NURBS and unifies knot vectors.
-   *
-   * @param curves - Array of curves to loft through (minimum 2)
-   * @param degreeV - Polynomial degree in the loft direction (default 3)
-   * @returns New NurbsSurface passing through all input curves
-   */
-  static loftCurves(curves: LoftableCurve[], degreeV = 3): NurbsSurface {
-    ensureInit();
-
-    // Step 0: Convert all curves to NurbsCurve
-    const nurbsCurves = curves.map(c => NurbsSurface.toNurbs(c));
-
-    // Step 1: Make curves compatible (same degree, unified knot vectors,
-    // same CP count). Mixed degrees are fine — the kernel degree-elevates
-    // lower-degree curves to the max degree exactly (a 2-point line lofts
-    // with a cubic).
-    let loftCurves = nurbsCurves;
-    if (nurbsCurves.length >= 2) {
-      const ref = nurbsCurves[0];
-      const matchesRef = (c: NurbsCurve) =>
-        c.degree === ref.degree &&
-        c.controlPoints.length === ref.controlPoints.length &&
-        c.knots.length === ref.knots.length &&
-        c.knots.every((k, i) => Math.abs(k - (ref.knots[i] as number)) < 1e-12);
-      const allSame = nurbsCurves.every(matchesRef);
-      if (!allSame) {
-        const compatParts: number[] = [nurbsCurves.length];
-        for (const c of nurbsCurves) {
-          compatParts.push(c.degree, c.controlPoints.length);
-          for (const p of c.controlPoints) { compatParts.push(p.x, p.y, p.z); }
-          for (const w of c.weights) { compatParts.push(w); }
-          for (const k of c.knots) { compatParts.push(k); }
-        }
-        const compatBuf = wasm.make_nurbs_curves_compatible(new Float64Array(compatParts));
-        if (compatBuf.length === 0) {
-          throw new Error("NurbsSurface loft: profile curves could not be made compatible");
-        }
-        const count = Number(compatBuf[0] ?? 0);
-        const decoded: NurbsCurve[] = [];
-        let off = 1;
-        for (let i = 0; i < count; i++) {
-          const deg = Number(compatBuf[off] ?? 0);
-          const n = Number(compatBuf[off + 1] ?? 0);
-          const curveLen = 2 + n * 3 + n + (n + deg + 1);
-          decoded.push(NurbsCurve.fromData(compatBuf.slice(off, off + curveLen)));
-          off += curveLen;
-        }
-        loftCurves = decoded;
-      }
-    }
-
-    // Step 2: Encode for loft_nurbs_surface
-    const parts: number[] = [loftCurves.length, degreeV];
-    for (const c of loftCurves) {
-      const pts = c.controlPoints;
-      parts.push(c.degree, pts.length);
-      for (const p of pts) { parts.push(p.x, p.y, p.z); }
-      for (const w of c.weights) { parts.push(w); }
-      for (const k of c.knots) { parts.push(k); }
-    }
-    const buf = wasm.loft_nurbs_surface(new Float64Array(parts));
-    if (buf.length < 4) throw new Error("NurbsSurface loft failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /**
-   * Decode a NurbsSurface from the standard WASM surface buffer
-   * [degU, degV, numU, numV, cps..., weights..., knotsU..., knotsV...].
-   */
-  static fromData(buf: Float64Array | number[]): NurbsSurface {
-    if (buf.length < 4) throw new Error("NurbsSurface.fromData: buffer too short");
-    const degU = Number(buf[0] ?? 0);
-    const degV = Number(buf[1] ?? 0);
-    const numU = Number(buf[2] ?? 0);
-    const numV = Number(buf[3] ?? 0);
-    const totalPts = numU * numV;
-    const expectedLen = 4 + totalPts * 3 + totalPts + (degU + numU + 1) + (degV + numV + 1);
-    if (buf.length < expectedLen) throw new Error("NurbsSurface.fromData: buffer too short");
-    let idx = 4;
-    const cp: Point[][] = [];
-    for (let u = 0; u < numU; u++) {
-      const row: Point[] = [];
-      for (let v = 0; v < numV; v++) {
-        row.push(new Point(Number(buf[idx]), Number(buf[idx + 1]), Number(buf[idx + 2])));
-        idx += 3;
-      }
-      cp.push(row);
-    }
-    const weights: number[][] = [];
-    for (let u = 0; u < numU; u++) {
-      const row: number[] = [];
-      for (let v = 0; v < numV; v++) { row.push(Number(buf[idx++])); }
-      weights.push(row);
-    }
-    const knotsULen = degU + numU + 1;
-    const knotsVLen = degV + numV + 1;
-    const knotsU: number[] = Array.from(buf.slice(idx, idx + knotsULen), (value) => Number(value));
-    idx += knotsULen;
-    const knotsV: number[] = Array.from(buf.slice(idx, idx + knotsVLen), (value) => Number(value));
-    return new NurbsSurface(degU, degV, cp, weights, knotsU, knotsV);
-  }
-
-  /** Raw WASM surface buffer (advanced use). */
-  get data(): Float64Array {
-    return this._data;
-  }
-
-  /**
-   * Offset this surface by `distance` along its oriented normal field,
-   * refit to `tolerance` (default 1e-4) against the exact offset. Rational
-   * surfaces (cylinders, spheres, revolves) offset exactly; closed seams
-   * stay closed and degenerate poles stay degenerate.
-   *
-   * Throws for creased surfaces or when the offset cannot reach tolerance
-   * (for example offsetting inward past the curvature radius).
-   */
-  offset(distance: number, options: { tolerance?: number } = {}): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_offset(this.data, distance, options.tolerance ?? 1e-4);
-    if (buf.length < 4) {
-      throw new Error(
-        `NurbsSurface.offset() failed: ${wasm.geometry_last_error() || "unknown error"}`,
-      );
-    }
-    return NurbsSurface.fromData(buf);
-  }
-
-  /**
-   * Rebuild this surface with the given degrees and control point counts
-   * (Rhino-style Rebuild): a two-stage global least-squares refit with clean
-   * approximation knots and chord-length-ish parameterization over
-   * [0, 1] x [0, 1]. The result is always NON-RATIONAL; closed directions
-   * stay seamlessly closed (periodic basis); degenerate pole rows (spheres,
-   * cones of revolution) stay exactly degenerate; open boundaries keep their
-   * exact corner points.
-   *
-   * Returns the rebuilt surface together with the measured deviation from
-   * the original (max and mean over a dense validation grid).
-   *
-   * Throws for invalid degree/count combinations (degree 1..11, counts
-   * >= degree + 1, per-direction cap 512) or degenerate surfaces.
-   */
-  rebuild(options: {
-    degreeU: number;
-    degreeV: number;
-    countU: number;
-    countV: number;
-  }): { surface: NurbsSurface; maxDeviation: number; avgDeviation: number } {
-    ensureInit();
-    const buf = wasm.nurbs_surface_rebuild(
-      this.data,
-      options.degreeU,
-      options.degreeV,
-      options.countU,
-      options.countV,
-    );
-    if (buf.length < 6) {
-      throw new Error(
-        `NurbsSurface.rebuild() failed: ${wasm.geometry_last_error() || "unknown error"}`,
-      );
-    }
-    return {
-      maxDeviation: Number(buf[0]),
-      avgDeviation: Number(buf[1]),
-      surface: NurbsSurface.fromData(buf.subarray(2)),
-    };
-  }
-
-  // ── Analytic queries ──
-
-  /**
-   * Analytic surface derivatives at (u, v) — exact rational derivatives
-   * (Piegl & Tiller A4.4), with respect to the normalized [0,1] parameters.
-   */
-  derivatives(u: number, v: number): {
-    point: Point;
-    du: Vec3;
-    dv: Vec3;
-    duu: Vec3;
-    duv: Vec3;
-    dvv: Vec3;
-  } {
-    ensureInit();
-    const r = wasm.nurbs_surface_derivatives(this._data, u, v);
-    if (r.length < 18) throw new Error("NurbsSurface.derivatives failed");
-    const vec = (i: number) => new Vec3(r[i], r[i + 1], r[i + 2]);
-    return {
-      point: new Point(r[0], r[1], r[2]),
-      du: vec(3),
-      dv: vec(6),
-      duu: vec(9),
-      duv: vec(12),
-      dvv: vec(15),
-    };
-  }
-
-  /**
-   * Principal curvatures and curvature invariants at (u, v), from the exact
-   * first/second fundamental forms.
-   */
-  curvature(u: number, v: number): {
-    k1: number;
-    k2: number;
-    gaussian: number;
-    mean: number;
-    normal: Vec3;
-  } {
-    ensureInit();
-    const r = wasm.nurbs_surface_curvature(this._data, u, v);
-    if (r.length < 7) throw new Error("NurbsSurface.curvature failed");
-    return {
-      k1: r[0],
-      k2: r[1],
-      gaussian: r[2],
-      mean: r[3],
-      normal: new Vec3(r[4], r[5], r[6]),
-    };
-  }
-
-  /**
-   * Closest point on the surface to `p` (Newton point inversion with grid
-   * seeding). Returns normalized (u, v) and the surface point.
-   */
-  closestPoint(p: Point): { u: number; v: number; point: Point } {
-    ensureInit();
-    const r = wasm.nurbs_surface_closest_point(this._data, p.x, p.y, p.z);
-    if (r.length < 5) throw new Error("NurbsSurface.closestPoint failed");
-    return { u: r[0], v: r[1], point: new Point(r[2], r[3], r[4]) };
-  }
-
-  // ── Iso-curves (exact rational extraction) ──
-
-  /**
-   * Exact iso-parametric curve running along the U direction at constant v.
-   * Rational surfaces yield exact rational curves (weights preserved).
-   * @param v - Normalized v parameter [0, 1]
-   */
-  isoCurveU(v: number): NurbsCurve {
-    ensureInit();
-    const buf = wasm.nurbs_surface_iso_curve(this._data, v, true);
-    if (buf.length < 2) throw new Error("NurbsSurface.isoCurveU failed");
-    return NurbsCurve.fromData(buf);
-  }
-
-  /**
-   * Exact iso-parametric curve running along the V direction at constant u.
-   * @param u - Normalized u parameter [0, 1]
-   */
-  isoCurveV(u: number): NurbsCurve {
-    ensureInit();
-    const buf = wasm.nurbs_surface_iso_curve(this._data, u, false);
-    if (buf.length < 2) throw new Error("NurbsSurface.isoCurveV failed");
-    return NurbsCurve.fromData(buf);
-  }
-
-  // ── Exact refinement / editing ──
-
-  /**
-   * Exact knot insertion at normalized parameter t (shape-preserving; adds a
-   * row/column of control points for finer editing).
-   */
-  insertKnot(direction: "u" | "v", t: number, times = 1): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_insert_knot(this._data, direction === "u", t, times);
-    if (buf.length < 4) throw new Error("NurbsSurface.insertKnot failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /**
-   * Exact degree elevation by `t` in one direction (shape-preserving).
-   */
-  elevateDegree(direction: "u" | "v", t = 1): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_elevate_degree(this._data, direction === "u", t);
-    if (buf.length < 4) throw new Error("NurbsSurface.elevateDegree failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /**
-   * Exact split at normalized parameter t. Returns [lower, upper].
-   */
-  split(direction: "u" | "v", t: number): [NurbsSurface, NurbsSurface] {
-    ensureInit();
-    const buf = wasm.nurbs_surface_split(this._data, direction === "u", t);
-    if (buf.length < 2) throw new Error("NurbsSurface.split failed");
-    const lenA = Number(buf[0]);
-    const a = buf.slice(1, 1 + lenA);
-    const lenB = Number(buf[1 + lenA]);
-    const b = buf.slice(2 + lenA, 2 + lenA + lenB);
-    return [NurbsSurface.fromData(a), NurbsSurface.fromData(b)];
-  }
-
-  /**
-   * Exact sub-patch over normalized parameter ranges.
-   */
-  extractRegion(u0: number, u1: number, v0: number, v1: number): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_extract_region(this._data, u0, u1, v0, v1);
-    if (buf.length < 4) throw new Error("NurbsSurface.extractRegion failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /**
-   * Return a copy with one control point (and optionally its weight) replaced —
-   * the primitive for interactive control-point editing.
-   */
-  withControlPoint(i: number, j: number, point: Point, weight?: number): NurbsSurface {
-    if (i < 0 || i >= this.controlPoints.length || j < 0 || j >= (this.controlPoints[0]?.length ?? 0)) {
-      throw new Error(`Control point index (${i}, ${j}) out of range`);
-    }
-    const cps = this.controlPoints.map((row, ri) =>
-      row.map((p, rj) => (ri === i && rj === j ? point : p))
-    );
-    const weights = this.weights.map((row, ri) =>
-      row.map((w, rj) => (ri === i && rj === j && weight !== undefined ? weight : w))
-    );
-    return new NurbsSurface(this.degreeU, this.degreeV, cps, weights, this.knotsU, this.knotsV);
-  }
-
-  // ── Tessellation ──
-
-  /**
-   * Curvature-adaptive tessellation: flat regions stay coarse, curved regions
-   * refine until the chordal `tolerance` is met.
-   */
-  tessellateAdaptive(tolerance: number, maxSegmentsPerSpan = 64): Mesh {
-    ensureInit();
-    const buf = wasm.nurbs_surface_tessellate_adaptive(this._data, tolerance, maxSegmentsPerSpan);
-    if (buf.length < 1) throw new Error("NurbsSurface.tessellateAdaptive failed");
-    return Mesh.fromBuffer(buf);
-  }
-
-  /**
-   * Convert to a mesh sheet for boolean/trim operations with meshes
-   * (adaptive tessellation at the given chordal tolerance). A sheet
-   * intersected with a closed solid via `Mesh.intersect`/`Mesh.subtract`
-   * trims to the portion inside/outside that solid.
-   */
-  toMesh(tolerance = 0.01): Mesh {
-    return this.tessellateAdaptive(tolerance);
-  }
-
-  /**
-   * Display-ready render tessellation computed in one kernel pass: a
-   * twist-aware adaptive grid with ANALYTIC surface normals, plus feature
-   * edges only where the surface genuinely has them (boundary iso-lines,
-   * kinked C0 knot lines, kinked closed seams — never quad diagonals).
-   *
-   * Prefer this over `tessellateAdaptive(...).buildRenderBuffers(...)` for
-   * displaying a NURBS surface: the mesh path reconstructs normals from
-   * triangle geometry and flags spurious crease edges on anisotropic grids.
-   *
-   * `positions`/`normals` are non-indexed, three floats per vertex;
-   * `featureEdges` holds two endpoints (six floats) per segment.
-   */
-  tessellateRender(
-    tolerance: number,
-    maxSegmentsPerSpan = 64,
-    creaseAngleDeg = 30
-  ): { positions: Float32Array; normals: Float32Array; featureEdges: Float32Array } {
-    ensureInit();
-    const r: Float32Array = wasm.nurbs_surface_tessellate_render(
-      this._data,
-      tolerance,
-      maxSegmentsPerSpan,
-      creaseAngleDeg
-    );
-    const vertexCount = Math.max(0, Math.floor(r[0] ?? 0));
-    const posStart = 1;
-    const norStart = posStart + vertexCount * 3;
-    const edgeCountIndex = norStart + vertexCount * 3;
-    const edgeCount = Math.max(0, Math.floor(r[edgeCountIndex] ?? 0));
-    const edgeStart = edgeCountIndex + 1;
-    return {
-      positions: r.subarray(posStart, posStart + vertexCount * 3),
-      normals: r.subarray(norStart, norStart + vertexCount * 3),
-      featureEdges: r.subarray(edgeStart, edgeStart + edgeCount * 6),
-    };
-  }
-
-  // ── Exact constructors ──
-
-  /**
-   * Exact surface of revolution: revolve a profile curve around an axis.
-   * The circular direction is exactly rational (true circles, not approximations).
-   * @param angle - Revolve angle in radians (up to 2π)
-   */
-  static revolve(profile: NurbsCurve, origin: Point, axis: Vec3, angle: number): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_revolve(
-      profile.data,
-      origin.x, origin.y, origin.z,
-      axis.x, axis.y, axis.z,
-      angle
-    );
-    if (buf.length < 4) throw new Error("NurbsSurface.revolve failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Exact extruded (translational) surface from a profile curve. */
-  static extrudeCurve(profile: NurbsCurve, direction: Vec3): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_extrude(profile.data, direction.x, direction.y, direction.z);
-    if (buf.length < 4) throw new Error("NurbsSurface.extrudeCurve failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Exact ruled surface between two curves (degrees/knots unified automatically). */
-  static ruled(a: NurbsCurve, b: NurbsCurve): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_ruled(a.data, b.data);
-    if (buf.length < 4) throw new Error("NurbsSurface.ruled failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Exact rational cylinder side surface. */
-  static cylinder(base: Point, axis: Vec3, radius: number, height: number): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_primitive(
-      "cylinder",
-      new Float64Array([base.x, base.y, base.z, axis.x, axis.y, axis.z, radius, height])
-    );
-    if (buf.length < 4) throw new Error("NurbsSurface.cylinder failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Exact rational sphere surface. */
-  static sphere(center: Point, radius: number): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_primitive(
-      "sphere",
-      new Float64Array([center.x, center.y, center.z, radius])
-    );
-    if (buf.length < 4) throw new Error("NurbsSurface.sphere failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Exact rational cone/frustum side surface (radius1 may be 0). */
-  static cone(base: Point, axis: Vec3, radius0: number, radius1: number, height: number): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_primitive(
-      "cone",
-      new Float64Array([base.x, base.y, base.z, axis.x, axis.y, axis.z, radius0, radius1, height])
-    );
-    if (buf.length < 4) throw new Error("NurbsSurface.cone failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Exact rational torus surface (axis +Z through center). */
-  static torus(center: Point, major: number, minor: number): NurbsSurface {
-    ensureInit();
-    const buf = wasm.nurbs_surface_primitive(
-      "torus",
-      new Float64Array([center.x, center.y, center.z, major, minor])
-    );
-    if (buf.length < 4) throw new Error("NurbsSurface.torus failed");
-    return NurbsSurface.fromData(buf);
-  }
-
-  /** Encode to WASM format */
-  private static encode(
-    degU: number,
-    degV: number,
-    controlPoints: Point[][],
-    weights: number[][],
-    knotsU: number[],
-    knotsV: number[]
-  ): Float64Array {
-    const numU = controlPoints.length;
-    const numV = controlPoints[0]?.length ?? 0;
-    const totalPts = numU * numV;
-    const data = new Float64Array(4 + totalPts * 3 + totalPts + knotsU.length + knotsV.length);
-    data[0] = degU;
-    data[1] = degV;
-    data[2] = numU;
-    data[3] = numV;
-    let idx = 4;
-    for (let u = 0; u < numU; u++) {
-      for (let v = 0; v < numV; v++) {
-        const p = controlPoints[u][v];
-        data[idx++] = p.x;
-        data[idx++] = p.y;
-        data[idx++] = p.z;
-      }
-    }
-    for (let u = 0; u < numU; u++) {
-      for (let v = 0; v < numV; v++) {
-        data[idx++] = weights[u][v];
-      }
-    }
-    for (const k of knotsU) data[idx++] = k;
-    for (const k of knotsV) data[idx++] = k;
-    return data;
-  }
-}
+import { ensureInit } from "./engine.js";
+import { Point } from "./Point.js";
+import { Vec3 } from "./Vec3.js";
+import { Plane } from "./Plane.js";
+import { Mesh } from "./Mesh.js";
+import { Polyline } from "./Polyline.js";
+import { Polygon } from "./Polygon.js";
+import { Line } from "./Line.js";
+import { Arc } from "./Arc.js";
+import { PolyCurve } from "./PolyCurve.js";
+import { NurbsCurve } from "./NurbsCurve.js";
+import type { Surface } from "./Surface.js";
+import type { LoftableCurve, RotationAxis } from "./types.js";
+import {
+  decodePointResult,
+  decodeVec3Result,
+  parsePolylineBuffer as parsePolylineBuf,
+} from "./BufferCodec.js";
+import { wasm } from "./wasm-active.js";
+
+/**
+ * Non-Uniform Rational B-Spline (NURBS) surface backed by WASM.
+ * Tensor-product surface defined by a 2D grid of control points.
+ *
+ * WASM data format: [degree_u, degree_v, num_u, num_v, ...cp(flat)..., ...weights..., ...knots_u..., ...knots_v...]
+ */
+export class NurbsSurface implements Surface {
+  private _data: Float64Array;
+
+  /**
+   * Create a new NURBS surface.
+   * @param degreeU - Polynomial degree in U direction
+   * @param degreeV - Polynomial degree in V direction
+   * @param controlPoints - 2D grid of control points [u][v]
+   * @param weights - 2D grid of weights corresponding to control points
+   * @param knotsU - Knot vector in U direction
+   * @param knotsV - Knot vector in V direction
+   */
+  constructor(
+    public readonly degreeU: number,
+    public readonly degreeV: number,
+    public readonly controlPoints: Point[][],
+    public readonly weights: number[][],
+    public readonly knotsU: number[],
+    public readonly knotsV: number[]
+  ) {
+    this._data = NurbsSurface.encode(degreeU, degreeV, controlPoints, weights, knotsU, knotsV);
+  }
+
+  /**
+   * Rotate this surface around an axis.
+   * @param axis - Rotation axis (Vec3 through origin, or Line for arbitrary axis)
+   * @param angle - Rotation angle in radians
+   * @returns New rotated surface
+   */
+  rotate(axis: RotationAxis, angle: number): NurbsSurface {
+    return new NurbsSurface(
+      this.degreeU,
+      this.degreeV,
+      this.controlPoints.map(row => row.map(p => p.rotate(axis, angle))),
+      this.weights,
+      this.knotsU,
+      this.knotsV
+    );
+  }
+
+  /**
+   * Translate this surface by an offset vector.
+   * @param offset - Translation vector
+   * @returns New translated surface
+   */
+  translate(offset: Vec3): NurbsSurface {
+    const newCps = this.controlPoints.map(row => row.map(p => p.add(offset)));
+    return new NurbsSurface(
+      this.degreeU,
+      this.degreeV,
+      newCps,
+      this.weights,
+      this.knotsU,
+      this.knotsV
+    );
+  }
+
+  /**
+   * Apply a row-major 4x4 AFFINE matrix to this surface. NURBS are invariant
+   * under affine maps of their control net, so rigid transforms, scaling
+   * (uniform or not) and shear are EXACT — weights and knots are unchanged.
+   * @param matrix - Row-major 4x4 matrix (16 entries)
+   * @returns New transformed surface
+   */
+  applyMatrix(matrix: number[] | Float64Array): NurbsSurface {
+    const newCps = this.controlPoints.map(row => row.map(p => p.applyMatrix(matrix)));
+    return new NurbsSurface(
+      this.degreeU,
+      this.degreeV,
+      newCps,
+      this.weights,
+      this.knotsU,
+      this.knotsV
+    );
+  }
+
+  /**
+   * Evaluate a point on the surface at parameters (u, v).
+   * @param u - Parameter in U direction [0, 1]
+   * @param v - Parameter in V direction [0, 1]
+   * @returns Point on surface at (u, v)
+   */
+  evaluate(u: number, v: number): Point {
+    ensureInit();
+    return decodePointResult(wasm.nurbs_surface_evaluate(this._data, u, v));
+  }
+
+  /**
+   * Evaluate the unit normal on the surface at parameters (u, v).
+   * @param u - Parameter in U direction [0, 1]
+   * @param v - Parameter in V direction [0, 1]
+   * @returns Unit surface normal at (u, v)
+   */
+  normal(u: number, v: number): Vec3 {
+    ensureInit();
+    return decodeVec3Result(wasm.nurbs_surface_normal(this._data, u, v));
+  }
+
+  /**
+   * Tessellate this surface into a triangle mesh.
+   * @param uSegs - Number of segments in U direction
+   * @param vSegs - Number of segments in V direction
+   * @returns Mesh approximating the surface
+   */
+  tessellate(uSegs: number, vSegs: number): Mesh {
+    ensureInit();
+    const full = new Float64Array(this._data.length + 2);
+    full.set(this._data);
+    full[this._data.length] = uSegs;
+    full[this._data.length + 1] = vSegs;
+    return Mesh.fromBuffer(wasm.tessellate_nurbs_surface(full));
+  }
+
+  /**
+   * Find intersection curves with a plane.
+   * @param plane - Cutting plane
+   * @param tess - Tessellation resolution for intersection detection (default 20)
+   * @returns Array of polylines representing intersection curves
+   */
+  intersectPlane(plane: Plane, tess = 20): Polyline[] {
+    ensureInit();
+    const buf = wasm.nurbs_surface_plane_intersect(
+      this._data,
+      plane.normal.x, plane.normal.y, plane.normal.z,
+      plane.d,
+      tess
+    );
+    return parsePolylineBuf(buf).map(pts => new Polyline(pts));
+  }
+
+  /**
+   * Find intersection curves with another NURBS surface.
+   * @param other - Other surface to intersect with
+   * @param tess - Tessellation resolution for intersection detection (default 20)
+   * @returns Array of polylines representing intersection curves
+   */
+  intersectSurface(other: NurbsSurface, tess = 20): Polyline[] {
+    ensureInit();
+    const buf = wasm.nurbs_surface_surface_intersect(this._data, other._data, tess);
+    return parsePolylineBuf(buf).map(pts => new Polyline(pts));
+  }
+
+  /**
+   * EXACT intersection curves with another NURBS surface.
+   *
+   * Unlike {@link intersectSurface} (tessellation-based, returns polylines at
+   * a fixed sampling resolution), this runs the parametric boolean's
+   * surface–surface intersection pipeline — seeded tri-tri detection,
+   * chaining, and Newton/tangent-plane relaxation of every point onto the
+   * true intersection — and fits each chain to an interpolating NURBS curve,
+   * densified until the fitted curve stays within `tolerance` of the exact
+   * intersection.
+   *
+   * Closed intersection loops (e.g. cylinder × plane) come back as ONE closed
+   * curve. Coincident (overlapping) surfaces return an empty array — their
+   * overlap is a 2D region, not a curve set.
+   *
+   * @param other - Other surface to intersect with
+   * @param tolerance - Absolute geometric tolerance of the fitted curves
+   *   (model units; floored relative to the combined model scale)
+   * @returns Exact fitted NURBS intersection curves
+   */
+  intersectSurfaceCurves(other: NurbsSurface, tolerance = 1e-6): NurbsCurve[] {
+    ensureInit();
+    const buf = wasm.nurbs_surface_surface_intersect_curves(this._data, other._data, tolerance);
+    return NurbsSurface.parseCurveList(buf);
+  }
+
+  /** Parse [count, (bufLen, curveData…)·count] into NurbsCurves. */
+  private static parseCurveList(buf: Float64Array): NurbsCurve[] {
+    if (buf.length < 1) return [];
+    const out: NurbsCurve[] = [];
+    const count = Number(buf[0]);
+    let offset = 1;
+    for (let k = 0; k < count && offset < buf.length; k++) {
+      const len = Number(buf[offset]);
+      offset += 1;
+      out.push(NurbsCurve.fromData(buf.subarray(offset, offset + len)));
+      offset += len;
+    }
+    return out;
+  }
+
+  /**
+   * Convert any supported curve type to a NurbsCurve.
+   * @param c - Curve to convert
+   * @returns NurbsCurve representation
+   */
+  private static toNurbs(c: LoftableCurve): NurbsCurve {
+    if (c instanceof NurbsCurve) return c;
+    if (c instanceof PolyCurve) return c.toNurbs();
+    if (c instanceof Polygon || c instanceof Polyline) return PolyCurve.byPoints((c as Polyline).points).toNurbs();
+    if (c instanceof Arc) return NurbsCurve.fromArc(c);
+    if (c instanceof Line) return NurbsCurve.fromLine(c);
+    throw new Error(`Unsupported curve type for loft`);
+  }
+
+  /**
+   * Loft a NURBS surface through multiple curves.
+   * Accepts NurbsCurve, PolyCurve, Polyline, Polygon, Arc, or Line.
+   * Automatically converts to NURBS and unifies knot vectors.
+   *
+   * @param curves - Array of curves to loft through (minimum 2)
+   * @param degreeV - Polynomial degree in the loft direction (default 3)
+   * @returns New NurbsSurface passing through all input curves
+   */
+  static loftCurves(curves: LoftableCurve[], degreeV = 3): NurbsSurface {
+    ensureInit();
+
+    // Step 0: Convert all curves to NurbsCurve
+    const nurbsCurves = curves.map(c => NurbsSurface.toNurbs(c));
+
+    // Step 1: Make curves compatible (same degree, unified knot vectors,
+    // same CP count). Mixed degrees are fine — the kernel degree-elevates
+    // lower-degree curves to the max degree exactly (a 2-point line lofts
+    // with a cubic).
+    let loftCurves = nurbsCurves;
+    if (nurbsCurves.length >= 2) {
+      const ref = nurbsCurves[0];
+      const matchesRef = (c: NurbsCurve) =>
+        c.degree === ref.degree &&
+        c.controlPoints.length === ref.controlPoints.length &&
+        c.knots.length === ref.knots.length &&
+        c.knots.every((k, i) => Math.abs(k - (ref.knots[i] as number)) < 1e-12);
+      const allSame = nurbsCurves.every(matchesRef);
+      if (!allSame) {
+        const compatParts: number[] = [nurbsCurves.length];
+        for (const c of nurbsCurves) {
+          compatParts.push(c.degree, c.controlPoints.length);
+          for (const p of c.controlPoints) { compatParts.push(p.x, p.y, p.z); }
+          for (const w of c.weights) { compatParts.push(w); }
+          for (const k of c.knots) { compatParts.push(k); }
+        }
+        const compatBuf = wasm.make_nurbs_curves_compatible(new Float64Array(compatParts));
+        if (compatBuf.length === 0) {
+          throw new Error("NurbsSurface loft: profile curves could not be made compatible");
+        }
+        const count = Number(compatBuf[0] ?? 0);
+        const decoded: NurbsCurve[] = [];
+        let off = 1;
+        for (let i = 0; i < count; i++) {
+          const deg = Number(compatBuf[off] ?? 0);
+          const n = Number(compatBuf[off + 1] ?? 0);
+          const curveLen = 2 + n * 3 + n + (n + deg + 1);
+          decoded.push(NurbsCurve.fromData(compatBuf.slice(off, off + curveLen)));
+          off += curveLen;
+        }
+        loftCurves = decoded;
+      }
+    }
+
+    // Step 2: Encode for loft_nurbs_surface
+    const parts: number[] = [loftCurves.length, degreeV];
+    for (const c of loftCurves) {
+      const pts = c.controlPoints;
+      parts.push(c.degree, pts.length);
+      for (const p of pts) { parts.push(p.x, p.y, p.z); }
+      for (const w of c.weights) { parts.push(w); }
+      for (const k of c.knots) { parts.push(k); }
+    }
+    const buf = wasm.loft_nurbs_surface(new Float64Array(parts));
+    if (buf.length < 4) throw new Error("NurbsSurface loft failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /**
+   * Decode a NurbsSurface from the standard WASM surface buffer
+   * [degU, degV, numU, numV, cps..., weights..., knotsU..., knotsV...].
+   */
+  static fromData(buf: Float64Array | number[]): NurbsSurface {
+    if (buf.length < 4) throw new Error("NurbsSurface.fromData: buffer too short");
+    const degU = Number(buf[0] ?? 0);
+    const degV = Number(buf[1] ?? 0);
+    const numU = Number(buf[2] ?? 0);
+    const numV = Number(buf[3] ?? 0);
+    const totalPts = numU * numV;
+    const expectedLen = 4 + totalPts * 3 + totalPts + (degU + numU + 1) + (degV + numV + 1);
+    if (buf.length < expectedLen) throw new Error("NurbsSurface.fromData: buffer too short");
+    let idx = 4;
+    const cp: Point[][] = [];
+    for (let u = 0; u < numU; u++) {
+      const row: Point[] = [];
+      for (let v = 0; v < numV; v++) {
+        row.push(new Point(Number(buf[idx]), Number(buf[idx + 1]), Number(buf[idx + 2])));
+        idx += 3;
+      }
+      cp.push(row);
+    }
+    const weights: number[][] = [];
+    for (let u = 0; u < numU; u++) {
+      const row: number[] = [];
+      for (let v = 0; v < numV; v++) { row.push(Number(buf[idx++])); }
+      weights.push(row);
+    }
+    const knotsULen = degU + numU + 1;
+    const knotsVLen = degV + numV + 1;
+    const knotsU: number[] = Array.from(buf.slice(idx, idx + knotsULen), (value) => Number(value));
+    idx += knotsULen;
+    const knotsV: number[] = Array.from(buf.slice(idx, idx + knotsVLen), (value) => Number(value));
+    return new NurbsSurface(degU, degV, cp, weights, knotsU, knotsV);
+  }
+
+  /** Raw WASM surface buffer (advanced use). */
+  get data(): Float64Array {
+    return this._data;
+  }
+
+  /**
+   * Offset this surface by `distance` along its oriented normal field,
+   * refit to `tolerance` (default 1e-4) against the exact offset. Rational
+   * surfaces (cylinders, spheres, revolves) offset exactly; closed seams
+   * stay closed and degenerate poles stay degenerate.
+   *
+   * Throws for creased surfaces or when the offset cannot reach tolerance
+   * (for example offsetting inward past the curvature radius).
+   */
+  offset(distance: number, options: { tolerance?: number } = {}): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_offset(this.data, distance, options.tolerance ?? 1e-4);
+    if (buf.length < 4) {
+      throw new Error(
+        `NurbsSurface.offset() failed: ${wasm.geometry_last_error() || "unknown error"}`,
+      );
+    }
+    return NurbsSurface.fromData(buf);
+  }
+
+  /**
+   * Rebuild this surface with the given degrees and control point counts
+   * (Rhino-style Rebuild): a two-stage global least-squares refit with clean
+   * approximation knots and chord-length-ish parameterization over
+   * [0, 1] x [0, 1]. The result is always NON-RATIONAL; closed directions
+   * stay seamlessly closed (periodic basis); degenerate pole rows (spheres,
+   * cones of revolution) stay exactly degenerate; open boundaries keep their
+   * exact corner points.
+   *
+   * Returns the rebuilt surface together with the measured deviation from
+   * the original (max and mean over a dense validation grid).
+   *
+   * Throws for invalid degree/count combinations (degree 1..11, counts
+   * >= degree + 1, per-direction cap 512) or degenerate surfaces.
+   */
+  rebuild(options: {
+    degreeU: number;
+    degreeV: number;
+    countU: number;
+    countV: number;
+  }): { surface: NurbsSurface; maxDeviation: number; avgDeviation: number } {
+    ensureInit();
+    const buf = wasm.nurbs_surface_rebuild(
+      this.data,
+      options.degreeU,
+      options.degreeV,
+      options.countU,
+      options.countV,
+    );
+    if (buf.length < 6) {
+      throw new Error(
+        `NurbsSurface.rebuild() failed: ${wasm.geometry_last_error() || "unknown error"}`,
+      );
+    }
+    return {
+      maxDeviation: Number(buf[0]),
+      avgDeviation: Number(buf[1]),
+      surface: NurbsSurface.fromData(buf.subarray(2)),
+    };
+  }
+
+  // ── Analytic queries ──
+
+  /**
+   * Analytic surface derivatives at (u, v) — exact rational derivatives
+   * (Piegl & Tiller A4.4), with respect to the normalized [0,1] parameters.
+   */
+  derivatives(u: number, v: number): {
+    point: Point;
+    du: Vec3;
+    dv: Vec3;
+    duu: Vec3;
+    duv: Vec3;
+    dvv: Vec3;
+  } {
+    ensureInit();
+    const r = wasm.nurbs_surface_derivatives(this._data, u, v);
+    if (r.length < 18) throw new Error("NurbsSurface.derivatives failed");
+    const vec = (i: number) => new Vec3(r[i], r[i + 1], r[i + 2]);
+    return {
+      point: new Point(r[0], r[1], r[2]),
+      du: vec(3),
+      dv: vec(6),
+      duu: vec(9),
+      duv: vec(12),
+      dvv: vec(15),
+    };
+  }
+
+  /**
+   * Principal curvatures and curvature invariants at (u, v), from the exact
+   * first/second fundamental forms.
+   */
+  curvature(u: number, v: number): {
+    k1: number;
+    k2: number;
+    gaussian: number;
+    mean: number;
+    normal: Vec3;
+  } {
+    ensureInit();
+    const r = wasm.nurbs_surface_curvature(this._data, u, v);
+    if (r.length < 7) throw new Error("NurbsSurface.curvature failed");
+    return {
+      k1: r[0],
+      k2: r[1],
+      gaussian: r[2],
+      mean: r[3],
+      normal: new Vec3(r[4], r[5], r[6]),
+    };
+  }
+
+  /**
+   * Closest point on the surface to `p` (Newton point inversion with grid
+   * seeding). Returns normalized (u, v) and the surface point.
+   */
+  closestPoint(p: Point): { u: number; v: number; point: Point } {
+    ensureInit();
+    const r = wasm.nurbs_surface_closest_point(this._data, p.x, p.y, p.z);
+    if (r.length < 5) throw new Error("NurbsSurface.closestPoint failed");
+    return { u: r[0], v: r[1], point: new Point(r[2], r[3], r[4]) };
+  }
+
+  // ── Iso-curves (exact rational extraction) ──
+
+  /**
+   * Exact iso-parametric curve running along the U direction at constant v.
+   * Rational surfaces yield exact rational curves (weights preserved).
+   * @param v - Normalized v parameter [0, 1]
+   */
+  isoCurveU(v: number): NurbsCurve {
+    ensureInit();
+    const buf = wasm.nurbs_surface_iso_curve(this._data, v, true);
+    if (buf.length < 2) throw new Error("NurbsSurface.isoCurveU failed");
+    return NurbsCurve.fromData(buf);
+  }
+
+  /**
+   * Exact iso-parametric curve running along the V direction at constant u.
+   * @param u - Normalized u parameter [0, 1]
+   */
+  isoCurveV(u: number): NurbsCurve {
+    ensureInit();
+    const buf = wasm.nurbs_surface_iso_curve(this._data, u, false);
+    if (buf.length < 2) throw new Error("NurbsSurface.isoCurveV failed");
+    return NurbsCurve.fromData(buf);
+  }
+
+  // ── Exact refinement / editing ──
+
+  /**
+   * Exact knot insertion at normalized parameter t (shape-preserving; adds a
+   * row/column of control points for finer editing).
+   */
+  insertKnot(direction: "u" | "v", t: number, times = 1): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_insert_knot(this._data, direction === "u", t, times);
+    if (buf.length < 4) throw new Error("NurbsSurface.insertKnot failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /**
+   * Exact degree elevation by `t` in one direction (shape-preserving).
+   */
+  elevateDegree(direction: "u" | "v", t = 1): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_elevate_degree(this._data, direction === "u", t);
+    if (buf.length < 4) throw new Error("NurbsSurface.elevateDegree failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /**
+   * Exact split at normalized parameter t. Returns [lower, upper].
+   */
+  split(direction: "u" | "v", t: number): [NurbsSurface, NurbsSurface] {
+    ensureInit();
+    const buf = wasm.nurbs_surface_split(this._data, direction === "u", t);
+    if (buf.length < 2) throw new Error("NurbsSurface.split failed");
+    const lenA = Number(buf[0]);
+    const a = buf.slice(1, 1 + lenA);
+    const lenB = Number(buf[1 + lenA]);
+    const b = buf.slice(2 + lenA, 2 + lenA + lenB);
+    return [NurbsSurface.fromData(a), NurbsSurface.fromData(b)];
+  }
+
+  /**
+   * Exact sub-patch over normalized parameter ranges.
+   */
+  extractRegion(u0: number, u1: number, v0: number, v1: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_extract_region(this._data, u0, u1, v0, v1);
+    if (buf.length < 4) throw new Error("NurbsSurface.extractRegion failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /**
+   * Return a copy with one control point (and optionally its weight) replaced —
+   * the primitive for interactive control-point editing.
+   */
+  withControlPoint(i: number, j: number, point: Point, weight?: number): NurbsSurface {
+    if (i < 0 || i >= this.controlPoints.length || j < 0 || j >= (this.controlPoints[0]?.length ?? 0)) {
+      throw new Error(`Control point index (${i}, ${j}) out of range`);
+    }
+    const cps = this.controlPoints.map((row, ri) =>
+      row.map((p, rj) => (ri === i && rj === j ? point : p))
+    );
+    const weights = this.weights.map((row, ri) =>
+      row.map((w, rj) => (ri === i && rj === j && weight !== undefined ? weight : w))
+    );
+    return new NurbsSurface(this.degreeU, this.degreeV, cps, weights, this.knotsU, this.knotsV);
+  }
+
+  // ── Tessellation ──
+
+  /**
+   * Curvature-adaptive tessellation: flat regions stay coarse, curved regions
+   * refine until the chordal `tolerance` is met.
+   */
+  tessellateAdaptive(tolerance: number, maxSegmentsPerSpan = 64): Mesh {
+    ensureInit();
+    const buf = wasm.nurbs_surface_tessellate_adaptive(this._data, tolerance, maxSegmentsPerSpan);
+    if (buf.length < 1) throw new Error("NurbsSurface.tessellateAdaptive failed");
+    return Mesh.fromBuffer(buf);
+  }
+
+  /**
+   * Convert to a mesh sheet for boolean/trim operations with meshes
+   * (adaptive tessellation at the given chordal tolerance). A sheet
+   * intersected with a closed solid via `Mesh.intersect`/`Mesh.subtract`
+   * trims to the portion inside/outside that solid.
+   */
+  toMesh(tolerance = 0.01): Mesh {
+    return this.tessellateAdaptive(tolerance);
+  }
+
+  /**
+   * Display-ready render tessellation computed in one kernel pass: a
+   * twist-aware adaptive grid with ANALYTIC surface normals, plus feature
+   * edges only where the surface genuinely has them (boundary iso-lines,
+   * kinked C0 knot lines, kinked closed seams — never quad diagonals).
+   *
+   * Prefer this over `tessellateAdaptive(...).buildRenderBuffers(...)` for
+   * displaying a NURBS surface: the mesh path reconstructs normals from
+   * triangle geometry and flags spurious crease edges on anisotropic grids.
+   *
+   * `positions`/`normals` are non-indexed, three floats per vertex;
+   * `featureEdges` holds two endpoints (six floats) per segment.
+   */
+  tessellateRender(
+    tolerance: number,
+    maxSegmentsPerSpan = 64,
+    creaseAngleDeg = 30
+  ): { positions: Float32Array; normals: Float32Array; featureEdges: Float32Array } {
+    ensureInit();
+    const r: Float32Array = wasm.nurbs_surface_tessellate_render(
+      this._data,
+      tolerance,
+      maxSegmentsPerSpan,
+      creaseAngleDeg
+    );
+    const vertexCount = Math.max(0, Math.floor(r[0] ?? 0));
+    const posStart = 1;
+    const norStart = posStart + vertexCount * 3;
+    const edgeCountIndex = norStart + vertexCount * 3;
+    const edgeCount = Math.max(0, Math.floor(r[edgeCountIndex] ?? 0));
+    const edgeStart = edgeCountIndex + 1;
+    return {
+      positions: r.subarray(posStart, posStart + vertexCount * 3),
+      normals: r.subarray(norStart, norStart + vertexCount * 3),
+      featureEdges: r.subarray(edgeStart, edgeStart + edgeCount * 6),
+    };
+  }
+
+  // ── Exact constructors ──
+
+  /**
+   * Exact surface of revolution: revolve a profile curve around an axis.
+   * The circular direction is exactly rational (true circles, not approximations).
+   * @param angle - Revolve angle in radians (up to 2π)
+   */
+  static revolve(profile: NurbsCurve, origin: Point, axis: Vec3, angle: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_revolve(
+      profile.data,
+      origin.x, origin.y, origin.z,
+      axis.x, axis.y, axis.z,
+      angle
+    );
+    if (buf.length < 4) throw new Error("NurbsSurface.revolve failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Exact extruded (translational) surface from a profile curve. */
+  static extrudeCurve(profile: NurbsCurve, direction: Vec3): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_extrude(profile.data, direction.x, direction.y, direction.z);
+    if (buf.length < 4) throw new Error("NurbsSurface.extrudeCurve failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Exact ruled surface between two curves (degrees/knots unified automatically). */
+  static ruled(a: NurbsCurve, b: NurbsCurve): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_ruled(a.data, b.data);
+    if (buf.length < 4) throw new Error("NurbsSurface.ruled failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Exact rational cylinder side surface. */
+  static cylinder(base: Point, axis: Vec3, radius: number, height: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_primitive(
+      "cylinder",
+      new Float64Array([base.x, base.y, base.z, axis.x, axis.y, axis.z, radius, height])
+    );
+    if (buf.length < 4) throw new Error("NurbsSurface.cylinder failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Exact rational sphere surface. */
+  static sphere(center: Point, radius: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_primitive(
+      "sphere",
+      new Float64Array([center.x, center.y, center.z, radius])
+    );
+    if (buf.length < 4) throw new Error("NurbsSurface.sphere failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Exact rational cone/frustum side surface (radius1 may be 0). */
+  static cone(base: Point, axis: Vec3, radius0: number, radius1: number, height: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_primitive(
+      "cone",
+      new Float64Array([base.x, base.y, base.z, axis.x, axis.y, axis.z, radius0, radius1, height])
+    );
+    if (buf.length < 4) throw new Error("NurbsSurface.cone failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Exact rational torus surface (axis +Z through center). */
+  static torus(center: Point, major: number, minor: number): NurbsSurface {
+    ensureInit();
+    const buf = wasm.nurbs_surface_primitive(
+      "torus",
+      new Float64Array([center.x, center.y, center.z, major, minor])
+    );
+    if (buf.length < 4) throw new Error("NurbsSurface.torus failed");
+    return NurbsSurface.fromData(buf);
+  }
+
+  /** Encode to WASM format */
+  private static encode(
+    degU: number,
+    degV: number,
+    controlPoints: Point[][],
+    weights: number[][],
+    knotsU: number[],
+    knotsV: number[]
+  ): Float64Array {
+    const numU = controlPoints.length;
+    const numV = controlPoints[0]?.length ?? 0;
+    const totalPts = numU * numV;
+    const data = new Float64Array(4 + totalPts * 3 + totalPts + knotsU.length + knotsV.length);
+    data[0] = degU;
+    data[1] = degV;
+    data[2] = numU;
+    data[3] = numV;
+    let idx = 4;
+    for (let u = 0; u < numU; u++) {
+      for (let v = 0; v < numV; v++) {
+        const p = controlPoints[u][v];
+        data[idx++] = p.x;
+        data[idx++] = p.y;
+        data[idx++] = p.z;
+      }
+    }
+    for (let u = 0; u < numU; u++) {
+      for (let v = 0; v < numV; v++) {
+        data[idx++] = weights[u][v];
+      }
+    }
+    for (const k of knotsU) data[idx++] = k;
+    for (const k of knotsV) data[idx++] = k;
+    return data;
+  }
+}