okgeometry-api 1.26.1 → 1.28.0

package/src/Mesh.ts

@@ -1,4 +1,4 @@
-import { ensureInit } from "./engine.js";
+import { ensureInit, isInitialized } from "./engine.js";
 import { Point } from "./Point.js";
 import { Vec3 } from "./Vec3.js";
 import { Plane } from "./Plane.js";
@@ -17,6 +17,7 @@ import {
   configureDefaultMeshBooleanWorkerPool,
   disposeMeshBooleanWorkerPools,
   runMeshBooleanInWorkerPool,
+  runMeshHeavyInWorkerPool,
 } from "./mesh-boolean.pool.js";
 import { MeshBooleanExecutionError } from "./mesh-boolean.protocol.js";
 import type {
@@ -24,8 +25,7 @@ import type {
   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 { wasm } from "./wasm-active.js";
 
 export { MeshBooleanExecutionError };
 export type {
@@ -277,6 +277,26 @@ export interface MeshRepairResult {
   filledHoles: number;
 }
 
+/** Which side of the source the thickened band occupies, relative to the
+ * surface normal: `"centered"` = ±d/2, `"up"` = [0, d], `"down"` = [-d, 0]. */
+export type ThickenMode = "centered" | "up" | "down";
+
+/** Options for {@link Mesh.thicken}. */
+export interface MeshThickenOptions {
+  /** Band placement relative to the vertex normals. Default: `"centered"`. */
+  mode?: ThickenMode;
+  /** Miter compensation for uniform wall distance across creases
+   * (Blender Solidify "even thickness"). Default: true. */
+  evenThickness?: boolean;
+  /** Clamp for the even-thickness displacement multiplier at sharp creases.
+   * Default: 4. */
+  miterLimit?: number;
+  /** Proximity-weld the input first. Set false when the mesh's indices
+   * already carry the intended connectivity (kernel-produced meshes) — the
+   * weld is the largest cost at high triangle counts. Default: true. */
+  weldInput?: boolean;
+}
+
 /** Result of {@link Mesh.makeWatertight}. */
 export interface MakeWatertightResult {
   mesh: Mesh;
@@ -362,6 +382,83 @@ export class Mesh {
     this._trustedBooleanInput = trustedBooleanInput;
   }
 
+  // ---- WASM-side residency (KERNEL-PERF-ARC lever 2) -----------------------
+  //
+  // Repeated queries on the same mesh (hover face groups, raycasts, render
+  // buffers, diagnostics) skip the per-call JS→WASM buffer copy by storing
+  // the buffer WASM-side once; raycasts additionally reuse a cached BVH.
+  // Residency is self-tuning: the FIRST hot call uses the classic buffer
+  // path (one-shot meshes never pay the store), the second call onward
+  // stores. `dispose()` releases eagerly; a FinalizationRegistry frees
+  // leaked ids on GC as a safety net. Buffers are immutable, so stored
+  // copies never need invalidation.
+
+  private _storeId: number | null = null;
+  private _hotCallCount = 0;
+
+  private static residencyFinalizer: FinalizationRegistry<number> | null =
+    typeof FinalizationRegistry !== "undefined"
+      ? new FinalizationRegistry<number>((id) => {
+          try {
+            if (isInitialized()) wasm.mesh_store_free(id);
+          } catch {
+            // engine torn down — nothing to free
+          }
+        })
+      : null;
+
+  /**
+   * WASM-side stored-mesh id, or 0 when this call should use the buffer
+   * path (first hot call, store failure, or disposed-and-cold mesh).
+   */
+  private storedId(): number {
+    if (this._storeId !== null) return this._storeId;
+    if (this._hotCallCount < 1) {
+      this._hotCallCount++;
+      return 0;
+    }
+    let id = 0;
+    try {
+      id = wasm.mesh_store(this._vertexCount, this._buffer);
+    } catch {
+      id = 0;
+    }
+    this._storeId = id;
+    if (id > 0) Mesh.residencyFinalizer?.register(this, id, this);
+    return id;
+  }
+
+  /**
+   * Release this mesh's WASM-side stored copy (idempotent). The mesh stays
+   * fully usable — the next repeated hot call re-stores it. Call from
+   * long-lived hosts (okdraw engine-bridge release paths) to return WASM
+   * memory promptly instead of waiting for GC.
+   */
+  dispose(): void {
+    if (this._storeId !== null && this._storeId > 0) {
+      try {
+        wasm.mesh_store_free(this._storeId);
+      } catch {
+        // engine torn down — nothing to free
+      }
+      Mesh.residencyFinalizer?.unregister(this);
+    }
+    this._storeId = null;
+    this._hotCallCount = 0;
+  }
+
+  /** Number of meshes currently resident WASM-side (diagnostics/tests). */
+  static residentMeshCount(): number {
+    ensureInit();
+    return wasm.mesh_store_count();
+  }
+
+  /** Approximate bytes of WASM-side resident mesh buffers (diagnostics). */
+  static residentMeshBytes(): number {
+    ensureInit();
+    return wasm.mesh_store_bytes();
+  }
+
   /**
    * Configure default size for the shared boolean worker pool.
    */
@@ -2198,7 +2295,10 @@ export class Mesh {
     if (this._edgeVertexPairs) return this._edgeVertexPairs;
 
     ensureInit();
-    const packed = wasm.mesh_get_edge_vertex_pairs(this._vertexCount, this._buffer);
+    const sidEdges = this.storedId();
+    const packed = sidEdges > 0
+      ? wasm.mesh_get_edge_vertex_pairs_h(sidEdges)
+      : wasm.mesh_get_edge_vertex_pairs(this._vertexCount, this._buffer);
     const edgeCount = Math.max(0, Math.floor(packed[0] ?? 0));
     const pairs: Array<[number, number]> = [];
     let off = 1;
@@ -3111,6 +3211,141 @@ export class Mesh {
     }
   }
 
+  // ── Heavy async ops on the worker pool (KERNEL-PERF-ARC lever 4) ──
+  //
+  // Multi-second operations run off the main thread with the same
+  // fallback contract as the pairwise async booleans: any worker-side
+  // failure falls back to the synchronous main-thread path.
+
+  /** Async `Mesh.unionAll` on the worker pool. */
+  static async unionAllAsync(
+    meshes: Mesh[],
+    options?: MeshBooleanAsyncOptions,
+  ): Promise<Mesh> {
+    try {
+      const { buffer } = await runMeshHeavyInWorkerPool(
+        "unionAll",
+        meshes.map((m) => m._buffer),
+        { ...options, trusted: meshes.map((m) => m._trustedBooleanInput) },
+      );
+      return Mesh.fromTrustedBuffer(buffer);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.unionAllAsync worker failed; falling back to main thread.", error);
+      return Mesh.unionAll(meshes, {
+        allowUnsafe: options?.allowUnsafe ?? true,
+        limits: options?.limits,
+      });
+    }
+  }
+
+  /** Async `mesh.subtractAll` on the worker pool. */
+  async subtractAllAsync(
+    cutters: Mesh[],
+    options?: MeshBooleanAsyncOptions,
+  ): Promise<Mesh> {
+    try {
+      const { buffer } = await runMeshHeavyInWorkerPool(
+        "differenceAll",
+        [this._buffer, ...cutters.map((m) => m._buffer)],
+        {
+          ...options,
+          trusted: [this._trustedBooleanInput, ...cutters.map((m) => m._trustedBooleanInput)],
+        },
+      );
+      return Mesh.fromTrustedBuffer(buffer);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.subtractAllAsync worker failed; falling back to main thread.", error);
+      return this.subtractAll(cutters, {
+        allowUnsafe: options?.allowUnsafe ?? true,
+        limits: options?.limits,
+      });
+    }
+  }
+
+  /** Async `mesh.makeWatertight` on the worker pool. NOTE: the async
+   * variant reports the result mesh, method and effective resolution;
+   * before/after diagnostics can be recomputed by the caller if needed. */
+  async makeWatertightAsync(
+    options: { resolution?: number; iso?: number } & MeshBooleanAsyncOptions = {},
+  ): Promise<{ mesh: Mesh; method: "repair" | "remesh"; effectiveResolution: number }> {
+    try {
+      const { buffer, meta } = await runMeshHeavyInWorkerPool(
+        "makeWatertight",
+        [this._buffer],
+        {
+          ...options,
+          trusted: [this._trustedBooleanInput],
+          params: { resolution: options.resolution, iso: options.iso },
+        },
+      );
+      return {
+        mesh: Mesh.fromTrustedBuffer(buffer),
+        method: (meta?.method as "repair" | "remesh") ?? "repair",
+        effectiveResolution: Number(meta?.effectiveResolution ?? 0),
+      };
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.makeWatertightAsync worker failed; falling back to main thread.", error);
+      const r = this.makeWatertight({ resolution: options.resolution, iso: options.iso });
+      return { mesh: r.mesh, method: r.method, effectiveResolution: r.effectiveResolution };
+    }
+  }
+
+  /** Async `mesh.voxelRemesh` on the worker pool. */
+  async voxelRemeshAsync(
+    resolution = 0,
+    iso = 0.5,
+    options?: MeshBooleanAsyncOptions,
+  ): Promise<Mesh> {
+    try {
+      const { buffer } = await runMeshHeavyInWorkerPool("voxelRemesh", [this._buffer], {
+        ...options,
+        trusted: [this._trustedBooleanInput],
+        params: { resolution, iso },
+      });
+      return Mesh.fromTrustedBuffer(buffer);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.voxelRemeshAsync worker failed; falling back to main thread.", error);
+      return this.voxelRemesh(resolution, iso);
+    }
+  }
+
+  /** Async `mesh.chamferEdges` on the worker pool. */
+  async chamferEdgesAsync(
+    edges: Array<{ a: Point | Vec3; b: Point | Vec3 }>,
+    distance: number,
+    options?: MeshBooleanAsyncOptions,
+  ): Promise<Mesh> {
+    const flat = new Float64Array(edges.length * 6);
+    edges.forEach((edge, i) => {
+      flat[i * 6] = edge.a.x;
+      flat[i * 6 + 1] = edge.a.y;
+      flat[i * 6 + 2] = edge.a.z;
+      flat[i * 6 + 3] = edge.b.x;
+      flat[i * 6 + 4] = edge.b.y;
+      flat[i * 6 + 5] = edge.b.z;
+    });
+    try {
+      const { buffer } = await runMeshHeavyInWorkerPool(
+        "chamferEdges",
+        [this._buffer, flat],
+        {
+          ...options,
+          trusted: [this._trustedBooleanInput],
+          params: { distance },
+        },
+      );
+      return Mesh.fromTrustedBuffer(buffer);
+    } catch (error) {
+      if (!shouldFallbackFromWorkerFailure(error)) throw error;
+      console.warn("Mesh.chamferEdgesAsync worker failed; falling back to main thread.", error);
+      return this.chamferEdges(edges, distance);
+    }
+  }
+
   // ── Intersection queries ───────────────────────────────────────
 
   /**
@@ -3459,7 +3694,10 @@ export class Mesh {
   getCoplanarFaceIndices(faceIndex: number): number[] {
     ensureInit();
     if (!Number.isFinite(faceIndex) || faceIndex < 0) return [];
-    const r = wasm.mesh_get_coplanar_face_indices(this._vertexCount, this._buffer, Math.floor(faceIndex));
+    const sidCfi = this.storedId();
+    const r = sidCfi > 0
+      ? wasm.mesh_get_coplanar_face_indices_h(sidCfi, Math.floor(faceIndex))
+      : wasm.mesh_get_coplanar_face_indices(this._vertexCount, this._buffer, Math.floor(faceIndex));
     const count = Math.max(0, Math.floor(r[0] ?? 0));
     const out: number[] = [];
     for (let i = 0; i < count; i++) {
@@ -3483,12 +3721,15 @@ export class Mesh {
     if (!Number.isFinite(faceIndex) || faceIndex < 0) {
       return { faceIndices: [], isPlanar: true };
     }
-    const r = wasm.mesh_get_smooth_face_group(
-      this._vertexCount,
-      this._buffer,
-      Math.floor(faceIndex),
-      maxAngleDeg,
-    );
+    const sidSfg = this.storedId();
+    const r = sidSfg > 0
+      ? wasm.mesh_get_smooth_face_group_h(sidSfg, Math.floor(faceIndex), maxAngleDeg)
+      : wasm.mesh_get_smooth_face_group(
+          this._vertexCount,
+          this._buffer,
+          Math.floor(faceIndex),
+          maxAngleDeg,
+        );
     const count = Math.max(0, Math.floor(r[0] ?? 0));
     const isPlanar = (r[1] ?? 1) !== 0;
     const faceIndices: number[] = [];
@@ -3515,11 +3756,14 @@ export class Mesh {
     featureEdges: Float32Array;
   } {
     ensureInit();
-    const r: Float32Array = wasm.mesh_build_render_buffers(
-      this._vertexCount,
-      this._buffer,
-      creaseAngleDeg,
-    );
+    const sidRb = this.storedId();
+    const r: Float32Array = sidRb > 0
+      ? wasm.mesh_build_render_buffers_h(sidRb, creaseAngleDeg)
+      : wasm.mesh_build_render_buffers(
+          this._vertexCount,
+          this._buffer,
+          creaseAngleDeg,
+        );
     const vertexCount = Math.max(0, Math.floor(r[0] ?? 0));
     const posStart = 1;
     const norStart = posStart + vertexCount * 3;
@@ -3582,11 +3826,14 @@ export class Mesh {
   getCoplanarFaceGroupCentroid(faceIndex: number): Point | null {
     ensureInit();
     if (!Number.isFinite(faceIndex) || faceIndex < 0) return null;
-    const r = wasm.mesh_get_coplanar_face_group_centroid(
-      this._vertexCount,
-      this._buffer,
-      Math.floor(faceIndex),
-    );
+    const sidCent = this.storedId();
+    const r = sidCent > 0
+      ? wasm.mesh_get_coplanar_face_group_centroid_h(sidCent, Math.floor(faceIndex))
+      : wasm.mesh_get_coplanar_face_group_centroid(
+          this._vertexCount,
+          this._buffer,
+          Math.floor(faceIndex),
+        );
     if (!r || r.length < 3) return null;
     return new Point(r[0], r[1], r[2]);
   }
@@ -3600,11 +3847,14 @@ export class Mesh {
   getFaceBoundaryLoops(faceIndex: number): Point[][] {
     ensureInit();
     if (!Number.isFinite(faceIndex) || faceIndex < 0) return [];
-    const r = wasm.mesh_get_face_boundary_loops(
-      this._vertexCount,
-      this._buffer,
-      Math.floor(faceIndex),
-    );
+    const sidLoops = this.storedId();
+    const r = sidLoops > 0
+      ? wasm.mesh_get_face_boundary_loops_h(sidLoops, Math.floor(faceIndex))
+      : wasm.mesh_get_face_boundary_loops(
+          this._vertexCount,
+          this._buffer,
+          Math.floor(faceIndex),
+        );
     if (!r || r.length < 1) return [];
     const loopCount = Math.floor(r[0]);
     const loops: Point[][] = [];
@@ -3658,13 +3908,21 @@ export class Mesh {
     maxDistance = Number.POSITIVE_INFINITY,
   ): { point: Point; normal: Vec3; faceIndex: number; distance: number } | null {
     ensureInit();
-    const r = wasm.mesh_raycast(
-      this._vertexCount,
-      this._buffer,
-      origin.x, origin.y, origin.z,
-      direction.x, direction.y, direction.z,
-      maxDistance,
-    );
+    const sidRay = this.storedId();
+    const r = sidRay > 0
+      ? wasm.mesh_raycast_h(
+          sidRay,
+          origin.x, origin.y, origin.z,
+          direction.x, direction.y, direction.z,
+          maxDistance,
+        )
+      : wasm.mesh_raycast(
+          this._vertexCount,
+          this._buffer,
+          origin.x, origin.y, origin.z,
+          direction.x, direction.y, direction.z,
+          maxDistance,
+        );
     if (!r || r.length < 8) return null;
     return {
       point: new Point(r[0], r[1], r[2]),
@@ -3683,13 +3941,21 @@ export class Mesh {
     maxDistance = Number.POSITIVE_INFINITY,
   ): Array<{ point: Point; normal: Vec3; faceIndex: number; distance: number }> {
     ensureInit();
-    const buf = wasm.mesh_raycast_all(
-      this._vertexCount,
-      this._buffer,
-      origin.x, origin.y, origin.z,
-      direction.x, direction.y, direction.z,
-      maxDistance,
-    );
+    const sidRayAll = this.storedId();
+    const buf = sidRayAll > 0
+      ? wasm.mesh_raycast_all_h(
+          sidRayAll,
+          origin.x, origin.y, origin.z,
+          direction.x, direction.y, direction.z,
+          maxDistance,
+        )
+      : wasm.mesh_raycast_all(
+          this._vertexCount,
+          this._buffer,
+          origin.x, origin.y, origin.z,
+          direction.x, direction.y, direction.z,
+          maxDistance,
+        );
     const count = Math.max(0, Math.floor(buf[0] ?? 0));
     const hits: Array<{ point: Point; normal: Vec3; faceIndex: number; distance: number }> = [];
     let off = 1;
@@ -3774,8 +4040,8 @@ export class Mesh {
 
     ensureInit();
     const metrics = this._trustedBooleanInput
-      ? mesh_topology_metrics_raw(this._vertexCount, this._buffer)
-      : mesh_topology_metrics(this._vertexCount, this._buffer);
+      ? wasm.mesh_topology_metrics_raw(this._vertexCount, this._buffer)
+      : wasm.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 };
@@ -3795,7 +4061,10 @@ export class Mesh {
    */
   diagnostics(): MeshDiagnostics {
     ensureInit();
-    const r = wasm.mesh_repair_diagnostics(this._vertexCount, this._buffer);
+    const sidDiag = this.storedId();
+    const r = sidDiag > 0
+      ? wasm.mesh_repair_diagnostics_h(sidDiag)
+      : wasm.mesh_repair_diagnostics(this._vertexCount, this._buffer);
     return parseMeshDiagnostics(r, 0);
   }
 
@@ -3806,7 +4075,10 @@ export class Mesh {
    */
   boundaryEdgeSegments(): Float64Array {
     ensureInit();
-    return wasm.mesh_boundary_edge_segments(this._vertexCount, this._buffer);
+    const sidBes = this.storedId();
+    return sidBes > 0
+      ? wasm.mesh_boundary_edge_segments_h(sidBes)
+      : wasm.mesh_boundary_edge_segments(this._vertexCount, this._buffer);
   }
 
   /**
@@ -3857,7 +4129,10 @@ export class Mesh {
    */
   featureEdgeChains(): Array<{ closed: boolean; points: Float64Array }> {
     ensureInit();
-    const r = wasm.mesh_feature_edge_chains(this._vertexCount, this._buffer);
+    const sidFec = this.storedId();
+    const r = sidFec > 0
+      ? wasm.mesh_feature_edge_chains_h(sidFec)
+      : wasm.mesh_feature_edge_chains(this._vertexCount, this._buffer);
     if (!r.length) {
       throw new Error(
         `Mesh.featureEdgeChains() failed: ${wasm.geometry_last_error() || "unknown error"}`,
@@ -3876,6 +4151,47 @@ export class Mesh {
     return chains;
   }
 
+  /**
+   * Thicken (solidify) this mesh into a solid: an open sheet becomes a
+   * watertight solid (bottom shell + top shell + boundary walls); a closed
+   * mesh becomes a hollow shell of wall thickness `distance`. Displacement is
+   * along angle-weighted vertex normals with even-thickness miter
+   * compensation (see {@link MeshThickenOptions}). Linear complexity — no CSG.
+   *
+   * Self-intersection where the thickness exceeds the local curvature radius
+   * is not resolved (standard offset semantics). Throws on non-manifold or
+   * non-orientable input, or non-positive distance.
+   */
+  thicken(distance: number, options: MeshThickenOptions = {}): Mesh {
+    ensureInit();
+    if (!Number.isFinite(distance) || distance <= 0) {
+      throw new Error("Mesh.thicken() requires a positive distance");
+    }
+    const mode = options.mode ?? "centered";
+    const [bottom, top] =
+      mode === "up"
+        ? [0, distance]
+        : mode === "down"
+          ? [-distance, 0]
+          : [-distance / 2, distance / 2];
+    const flags =
+      (options.evenThickness === false ? 1 : 0) | (options.weldInput === false ? 2 : 0);
+    const r = wasm.mesh_thicken(
+      this._vertexCount,
+      this._buffer,
+      bottom,
+      top,
+      flags,
+      options.miterLimit ?? 0,
+    );
+    if (!r.length) {
+      throw new Error(
+        `Mesh.thicken() failed: ${wasm.geometry_last_error() || "unknown error"}`,
+      );
+    }
+    return Mesh.fromTrustedBuffer(r as Float64Array);
+  }
+
   /**
    * Geometry-preserving repair: weld coincident vertices, drop degenerate /
    * duplicate triangles, remove orphan vertices, make winding consistent +

package/src/MeshSurface.ts

@@ -4,7 +4,7 @@ import type { Mesh, MeshPlanarFace } from "./Mesh.js";
 import { Point } from "./Point.js";
 import type { Surface } from "./Surface.js";
 import { Vec3 } from "./Vec3.js";
-import * as wasm from "./wasm-bindings.js";
+import { wasm } from "./wasm-active.js";
 
 /**
  * Logical planar surface extracted from a coplanar connected face group on a mesh.