okgeometry-api 1.26.1 → 1.27.0

package/src/engine-threaded.ts

@@ -0,0 +1,39 @@
+/**
+ * Threaded engine loader (KERNEL-PERF-ARC lever 3).
+ *
+ * Loaded LAZILY (dynamic import from engine.ts) so the threaded wasm's
+ * inlined bytes are only fetched on pages that can actually use them
+ * (cross-origin isolated, SharedArrayBuffer available). Instantiates the
+ * rayon-enabled artifact, starts the worker thread pool, and swaps the
+ * active bindings module. Never call directly — use `initThreads()` from
+ * engine.ts, which enforces the boot-time ordering rules.
+ */
+import { WASM_THREADED_B64 } from "./wasm-base64-threaded.js";
+import { setActiveWasmModule } from "./wasm-active.js";
+import threadedInit, { initThreadPool } from "./wasm-bindings-threaded.js";
+import * as threadedModule from "./wasm-bindings-threaded.js";
+
+export async function initThreadedEngine(threads?: number): Promise<boolean> {
+  if (!WASM_THREADED_B64) return false; // artifact absent at build time
+
+  const raw = atob(WASM_THREADED_B64);
+  const bytes = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
+
+  await threadedInit({ module_or_path: bytes });
+
+  // Default pool: compute-bound kernel loops saturate well before core
+  // count, and each worker holds a wasm instance — cap at 8.
+  const requested =
+    threads ??
+    Math.min(
+      8,
+      typeof navigator !== "undefined" && Number.isFinite(navigator.hardwareConcurrency)
+        ? Math.max(1, Math.floor(navigator.hardwareConcurrency))
+        : 4,
+    );
+  await initThreadPool(requested);
+
+  setActiveWasmModule(threadedModule as unknown as Parameters<typeof setActiveWasmModule>[0]);
+  return true;
+}

package/src/engine.ts

@@ -31,3 +31,49 @@ export function ensureInit(): void {
 export function isInitialized(): boolean {
   return initialized;
 }
+
+/**
+ * Initialize the THREADED engine (KERNEL-PERF-ARC lever 3): rayon worker
+ * pool over shared WebAssembly memory. Requires a cross-origin isolated
+ * page (COOP: same-origin + COEP; check `crossOriginIsolated`). Returns
+ * false — without touching engine state — when the environment cannot run
+ * threads or the threaded artifact is unavailable, so callers can fall
+ * back to `init()`.
+ *
+ * MUST be the first init call: stored meshes and sculpt sessions are
+ * per-wasm-instance state, so the module cannot be swapped after use.
+ */
+export async function initThreads(options: { threads?: number } = {}): Promise<boolean> {
+  if (initialized) {
+    throw new Error(
+      "OkGeometry already initialized — initThreads() must run INSTEAD of init(), before any geometry use.",
+    );
+  }
+  const g = globalThis as typeof globalThis & {
+    crossOriginIsolated?: boolean;
+    SharedArrayBuffer?: unknown;
+  };
+  if (!g.crossOriginIsolated || typeof g.SharedArrayBuffer === "undefined") {
+    return false;
+  }
+  try {
+    const mod = await import("./engine-threaded.js");
+    const ok = await mod.initThreadedEngine(options.threads);
+    if (!ok) return false;
+    initialized = true;
+    return true;
+  } catch (error) {
+    console.warn("okgeometry threaded init failed; falling back to single-thread.", error);
+    return false;
+  }
+}
+
+/**
+ * Convenience boot: try the threaded engine, fall back to the standard
+ * single-thread engine. Returns which one is active.
+ */
+export async function initAuto(options: { threads?: number } = {}): Promise<"threaded" | "standard"> {
+  if (await initThreads(options)) return "threaded";
+  await init();
+  return "standard";
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 // Core initialization
-export { init, isInitialized } from "./engine.js";
+export { init, initThreads, initAuto, isInitialized } from "./engine.js";
 
 // Shared types and utilities
 export type {

package/src/mesh-boolean.pool.ts

@@ -1,36 +1,49 @@
-import {
-  MeshBooleanExecutionError,
-  type MeshBooleanAsyncOptions,
-  type MeshBooleanErrorPayload,
-  type MeshBooleanOperation,
-  type MeshBooleanOptions,
-  type MeshBooleanProgressEvent,
-  type MeshBooleanWorkerRequest,
-  type MeshBooleanWorkerResponse,
-} from "./mesh-boolean.protocol.js";
+import {
+  MeshBooleanExecutionError,
+  type MeshBooleanAsyncOptions,
+  type MeshBooleanErrorPayload,
+  type MeshBooleanOperation,
+  type MeshBooleanOptions,
+  type MeshBooleanProgressEvent,
+  type MeshBooleanWorkerRequest,
+  type MeshBooleanWorkerResponse,
+  type MeshHeavyMeta,
+  type MeshHeavyOperation,
+  type MeshHeavyParams,
+  type MeshHeavyWorkerRequest,
+} from "./mesh-boolean.protocol.js";
 
 interface PoolAcquireOptions {
   size?: number;
   workerFactory?: () => Worker;
 }
 
-interface BooleanJob {
-  id: number;
-  operation: MeshBooleanOperation;
-  options: MeshBooleanOptions;
-  onProgress?: (event: MeshBooleanProgressEvent) => void;
-  signal?: AbortSignal;
-  timeoutMs?: number;
-  bufferA: ArrayBuffer;
+interface BooleanJob {
+  id: number;
+  operation: MeshBooleanOperation | MeshHeavyOperation;
+  options: MeshBooleanOptions;
+  onProgress?: (event: MeshBooleanProgressEvent) => void;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  bufferA: ArrayBuffer;
   bufferB: ArrayBuffer;
   trustedInputA: boolean;
   trustedInputB: boolean;
+  /** Heavy multi-buffer job payload (KERNEL-PERF-ARC lever 4); when set,
+   * bufferA/bufferB are unused empty buffers. */
+  heavy?: {
+    buffers: ArrayBuffer[];
+    trusted?: boolean[];
+    params?: MeshHeavyParams;
+  };
+  /** Receives structured extras from heavy job responses before resolve. */
+  onMeta?: (meta: MeshHeavyMeta | undefined) => void;
   cancelView?: Int32Array;
-  timeoutToken?: number;
-  abortHandler?: () => void;
-  resolve: (value: Float64Array) => void;
-  reject: (reason: Error) => void;
-}
+  timeoutToken?: number;
+  abortHandler?: () => void;
+  resolve: (value: Float64Array) => void;
+  reject: (reason: Error) => void;
+}
 
 interface WorkerSlot {
   id: number;
@@ -127,22 +140,22 @@ export class MeshBooleanWorkerPool {
       const job: BooleanJob = {
         id: jobId,
         operation,
-        options: {
-          allowUnsafe: options?.allowUnsafe ?? true,
-          limits: options?.limits,
-          debugForceFaceID: options?.debugForceFaceID,
-        },
-        onProgress: options?.onProgress,
-        signal: options?.signal,
-        timeoutMs: options?.timeoutMs,
-        bufferA: new Float64Array(bufferA).buffer,
+        options: {
+          allowUnsafe: options?.allowUnsafe ?? true,
+          limits: options?.limits,
+          debugForceFaceID: options?.debugForceFaceID,
+        },
+        onProgress: options?.onProgress,
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs,
+        bufferA: new Float64Array(bufferA).buffer,
         bufferB: new Float64Array(bufferB).buffer,
-        trustedInputA,
-        trustedInputB,
-        cancelView: createCancellationView(),
-        resolve,
-        reject,
-      };
+        trustedInputA,
+        trustedInputB,
+        cancelView: createCancellationView(),
+        resolve,
+        reject,
+      };
 
       if (job.signal?.aborted) {
         this.rejectJob(job, rejectPayload("worker_aborted", `Boolean ${operation} aborted.`));
@@ -162,6 +175,78 @@ export class MeshBooleanWorkerPool {
     });
   }
 
+  /**
+   * Run a heavy multi-buffer kernel job (KERNEL-PERF-ARC lever 4) on the
+   * pool. Buffers are COPIED before transfer, so callers keep their meshes.
+   */
+  runHeavy(
+    operation: MeshHeavyOperation,
+    buffers: Float64Array[],
+    heavyOptions?: MeshBooleanAsyncOptions & {
+      trusted?: boolean[];
+      params?: MeshHeavyParams;
+    },
+  ): Promise<{ buffer: Float64Array; meta?: MeshHeavyMeta }> {
+    if (this.disposed) {
+      return Promise.reject(
+        new MeshBooleanExecutionError(
+          rejectPayload("worker_unavailable", "Boolean worker pool has been disposed."),
+        ),
+      );
+    }
+
+    this.ensureWorkers();
+    const jobId = this.nextJobId++;
+    const empty = new ArrayBuffer(0);
+
+    return new Promise((resolve, reject) => {
+      let meta: MeshHeavyMeta | undefined;
+      const job: BooleanJob = {
+        id: jobId,
+        operation,
+        options: {
+          allowUnsafe: heavyOptions?.allowUnsafe ?? true,
+          limits: heavyOptions?.limits,
+          debugForceFaceID: heavyOptions?.debugForceFaceID,
+        },
+        onProgress: heavyOptions?.onProgress,
+        signal: heavyOptions?.signal,
+        timeoutMs: heavyOptions?.timeoutMs,
+        bufferA: empty,
+        bufferB: empty,
+        trustedInputA: false,
+        trustedInputB: false,
+        heavy: {
+          buffers: buffers.map((b) => new Float64Array(b).buffer),
+          trusted: heavyOptions?.trusted,
+          params: heavyOptions?.params,
+        },
+        onMeta: (m) => {
+          meta = m;
+        },
+        cancelView: createCancellationView(),
+        resolve: (buffer) => resolve({ buffer, meta }),
+        reject,
+      };
+
+      if (job.signal?.aborted) {
+        this.rejectJob(job, rejectPayload("worker_aborted", `${operation} aborted.`));
+        return;
+      }
+
+      if (job.signal) {
+        job.abortHandler = () => {
+          this.cancelJob(job.id, "worker_aborted", `${job.operation} aborted.`);
+        };
+        job.signal.addEventListener("abort", job.abortHandler, { once: true });
+      }
+
+      this.queue.push(job);
+      this.emitProgress(job, "queued");
+      this.dispatch();
+    });
+  }
+
   dispose(): void {
     if (this.disposed) return;
     this.disposed = true;
@@ -239,9 +324,9 @@ export class MeshBooleanWorkerPool {
         continue;
       }
 
-      slot.currentJobId = job.id;
-      this.running.set(job.id, job);
-      this.emitProgress(job, "running", slot.id);
+      slot.currentJobId = job.id;
+      this.running.set(job.id, job);
+      this.emitProgress(job, "running", slot.id);
 
       if (job.timeoutMs !== undefined && Number.isFinite(job.timeoutMs) && job.timeoutMs > 0) {
         job.timeoutToken = setTimeout(() => {
@@ -249,20 +334,37 @@ export class MeshBooleanWorkerPool {
         }, job.timeoutMs) as unknown as number;
       }
 
-      const request: MeshBooleanWorkerRequest = {
-        kind: "mesh-boolean-request",
-        jobId: job.id,
-        operation: job.operation,
-        bufferA: job.bufferA,
-        bufferB: job.bufferB,
-        trustedInputA: job.trustedInputA,
-        trustedInputB: job.trustedInputB,
-        cancelBuffer: job.cancelView?.buffer as SharedArrayBuffer | undefined,
-        options: job.options,
-      };
+      let request: MeshBooleanWorkerRequest | MeshHeavyWorkerRequest;
+      let transfers: ArrayBuffer[];
+      if (job.heavy) {
+        request = {
+          kind: "mesh-heavy-request",
+          jobId: job.id,
+          operation: job.operation as MeshHeavyOperation,
+          buffers: job.heavy.buffers,
+          trusted: job.heavy.trusted,
+          params: job.heavy.params,
+          cancelBuffer: job.cancelView?.buffer as SharedArrayBuffer | undefined,
+          options: job.options,
+        };
+        transfers = job.heavy.buffers;
+      } else {
+        request = {
+          kind: "mesh-boolean-request",
+          jobId: job.id,
+          operation: job.operation as MeshBooleanOperation,
+          bufferA: job.bufferA,
+          bufferB: job.bufferB,
+          trustedInputA: job.trustedInputA,
+          trustedInputB: job.trustedInputB,
+          cancelBuffer: job.cancelView?.buffer as SharedArrayBuffer | undefined,
+          options: job.options,
+        };
+        transfers = [request.bufferA, request.bufferB];
+      }
 
       try {
-        slot.worker.postMessage(request, [request.bufferA, request.bufferB]);
+        slot.worker.postMessage(request, transfers);
       } catch (error) {
         const details = error instanceof Error ? error.message : String(error);
         this.finishRunningJob(
@@ -300,18 +402,19 @@ export class MeshBooleanWorkerPool {
       return;
     }
 
-    if (data.ok) {
-      this.finishRunningJob(slot, job, undefined, new Float64Array(data.buffer));
-      return;
-    }
-
-    this.finishRunningJob(
-      slot,
-      job,
-      new MeshBooleanExecutionError(data.error),
-      undefined,
-    );
-  }
+    if (data.ok) {
+      job.onMeta?.(data.meta);
+      this.finishRunningJob(slot, job, undefined, new Float64Array(data.buffer));
+      return;
+    }
+
+    this.finishRunningJob(
+      slot,
+      job,
+      new MeshBooleanExecutionError(data.error),
+      undefined,
+    );
+  }
 
   private failWorker(slot: WorkerSlot, payload: MeshBooleanErrorPayload): void {
     const jobId = slot.currentJobId;
@@ -371,18 +474,18 @@ export class MeshBooleanWorkerPool {
     this.dispatch();
   }
 
-  private finishRunningJob(
-    slot: WorkerSlot,
-    job: BooleanJob,
-    error: Error | undefined,
-    result: Float64Array | undefined,
-  ): void {
-    this.running.delete(job.id);
-    slot.currentJobId = null;
-    this.cleanupJob(job);
-
-    if (error) {
-      job.reject(error);
+  private finishRunningJob(
+    slot: WorkerSlot,
+    job: BooleanJob,
+    error: Error | undefined,
+    result: Float64Array | undefined,
+  ): void {
+    this.running.delete(job.id);
+    slot.currentJobId = null;
+    this.cleanupJob(job);
+
+    if (error) {
+      job.reject(error);
     } else if (result) {
       job.resolve(result);
     } else {
@@ -410,15 +513,15 @@ export class MeshBooleanWorkerPool {
   }
 
   private emitProgress(job: BooleanJob, stage: MeshBooleanProgressEvent["stage"], workerId?: number): void {
-    if (!job.onProgress) return;
-    job.onProgress({
-      stage,
-      jobId: job.id,
-      workerId,
-      queueSize: this.queue.length,
-    });
-  }
-}
+    if (!job.onProgress) return;
+    job.onProgress({
+      stage,
+      jobId: job.id,
+      workerId,
+      queueSize: this.queue.length,
+    });
+  }
+}
 
 let defaultPoolSizeOverride: number | undefined;
 const defaultPools = new Map<number, MeshBooleanWorkerPool>();
@@ -489,3 +592,22 @@ export function runMeshBooleanInWorkerPool(
   });
   return pool.run(operation, bufferA, bufferB, trustedInputA, trustedInputB, options);
 }
+
+/**
+ * Run a heavy multi-buffer kernel job on the shared worker pool
+ * (KERNEL-PERF-ARC lever 4). See MeshHeavyWorkerRequest for buffer shapes.
+ */
+export function runMeshHeavyInWorkerPool(
+  operation: MeshHeavyOperation,
+  buffers: Float64Array[],
+  options?: MeshBooleanAsyncOptions & {
+    trusted?: boolean[];
+    params?: MeshHeavyParams;
+  },
+): Promise<{ buffer: Float64Array; meta?: MeshHeavyMeta }> {
+  const pool = getMeshBooleanWorkerPool({
+    workerFactory: options?.workerFactory,
+    size: options?.poolSize,
+  });
+  return pool.runHeavy(operation, buffers, options);
+}

package/src/mesh-boolean.protocol.ts

@@ -90,13 +90,18 @@ export interface MeshBooleanWorkerCancel {
   jobId: number;
 }
 
-export type MeshBooleanWorkerInbound = MeshBooleanWorkerRequest | MeshBooleanWorkerCancel;
+export type MeshBooleanWorkerInbound =
+  | MeshBooleanWorkerRequest
+  | MeshHeavyWorkerRequest
+  | MeshBooleanWorkerCancel;
 
 export interface MeshBooleanWorkerSuccessResponse {
   kind: "mesh-boolean-result";
   jobId: number;
   ok: true;
   buffer: ArrayBuffer;
+  /** Structured extras for heavy jobs (e.g. makeWatertight method). */
+  meta?: Record<string, string | number | boolean>;
 }
 
 export interface MeshBooleanWorkerErrorResponse {
@@ -119,3 +124,41 @@ export class MeshBooleanExecutionError extends Error {
     this.details = payload.details;
   }
 }
+
+// ---- Heavy kernel jobs (KERNEL-PERF-ARC lever 4) ---------------------------
+//
+// Multi-second kernel operations beyond pairwise booleans run on the same
+// worker pool: batch booleans, watertight repair, voxel remesh, solid edge
+// chamfer. Buffers are op-specific:
+//   unionAll:       [mesh0, mesh1, ...]
+//   differenceAll:  [host, cutter0, cutter1, ...]
+//   makeWatertight: [mesh]
+//   voxelRemesh:    [mesh]
+//   chamferEdges:   [mesh, edgeSegments] (flat [ax,ay,az,bx,by,bz] per edge)
+
+export type MeshHeavyOperation =
+  | "unionAll"
+  | "differenceAll"
+  | "makeWatertight"
+  | "voxelRemesh"
+  | "chamferEdges";
+
+export interface MeshHeavyParams {
+  resolution?: number;
+  iso?: number;
+  distance?: number;
+}
+
+export interface MeshHeavyWorkerRequest {
+  kind: "mesh-heavy-request";
+  jobId: number;
+  operation: MeshHeavyOperation;
+  buffers: ArrayBuffer[];
+  trusted?: boolean[];
+  params?: MeshHeavyParams;
+  cancelBuffer?: SharedArrayBuffer;
+  options: MeshBooleanOptions;
+}
+
+/** Structured extras for heavy results (e.g. makeWatertight method). */
+export type MeshHeavyMeta = Record<string, string | number | boolean>;