Migrate Replicad to OCCT v8 bindings

docs/occt-v8-migration.md

@@ -0,0 +1,104 @@
+# OCCT V8 Migration — replicad Perspective
+
+This document covers the replicad-specific changes for the OCCT V8 migration.
+
+## Summary
+
+The OCCT V8 migration consolidates replicad's three WASM builds (`single`, `with_exceptions`, `multi`) into a **single unified build** using native WASM exceptions (`-fwasm-exceptions`).
+
+| Build variant | V7.6 / V8 (before) | V8 (after) |
+|---|---|---|
+| `replicad_single` | No exception support | Full exception support via `-fwasm-exceptions` |
+| `replicad_with_exceptions` | Separate build with `-fexceptions` | **Removed** — merged into single build |
+| `replicad_multi` | pthread-based multi-threading | **Removed** — deferred (see below) |
+
+## Why a Single Build?
+
+### Native WASM Exceptions (`-fwasm-exceptions`)
+
+The WebAssembly Exception Handling proposal (Phase 4) is now supported by 94.5%+ of browsers (Chrome 95+, Firefox 100+, Safari 15.2+). It provides:
+
+- **Zero-cost happy path**: No `invoke_SIG` wrapper overhead on every function call
+- **Proper stack traces**: `WebAssembly.Exception` objects preserve the call stack
+- **Smaller binary**: ~10-15% smaller than JavaScript-based exception handling (`-fexceptions`)
+- **No performance penalty**: Unlike `-fexceptions`, which added ~75% binary size and measurable runtime overhead, `-fwasm-exceptions` has negligible impact on non-throwing code paths
+
+This eliminates the need for a separate "with_exceptions" build. The single build has full exception decoding support with `OCJS.getStandard_FailureData()`.
+
+### Multi-threading Deferred
+
+Analysis revealed that OCCT's parallel algorithms were never actually activated in the replicad codebase:
+
+- `BRepMesh_IncrementalMesh`: called with `isInParallel=false` (hardcoded in `shapes.ts`)
+- `BOPAlgo_Options::SetRunParallel()`: defaults to `false`
+- All benchmark operations showed **slower** performance with the multi-threaded build due to pthread infrastructure overhead (SharedArrayBuffer, mutex costs, pre-spawned workers)
+
+Multi-threading will be revisited when explicit parallel algorithm activation is implemented upstream.
+
+## replicad Source Changes
+
+The following replicad source files were modified for OCCT V8 compatibility:
+
+- **`packages/replicad/src/Sketcher.ts`**: Updated for V8 API changes
+- **`packages/replicad/src/shapes.ts`**: Updated mesh and shape operations
+- **`packages/replicad/src/geom.ts`**: Geometry utility updates
+
+## Build Configuration
+
+### Single V8 YAML (`custom_build_single_v8.yml`)
+
+Key changes from the V7.6 configuration:
+
+```yaml
+emccFlags:
+  - -flto                                    # Dead-code elimination at link
+  - -fwasm-exceptions                        # Native WASM exceptions
+  - -sEXPORT_EXCEPTION_HANDLING_HELPERS      # JS helpers for exception decoding
+  - -sEXPORT_ES6=1
+  - -sALLOW_MEMORY_GROWTH=1
+  - -sINITIAL_MEMORY=100MB
+  - -sMAXIMUM_MEMORY=4GB
+  - --no-entry
+  - --emit-symbol-map
+  - -O3
+```
+
+Bindings include `OCJS` and `Standard_Failure` for exception decoding (previously only in the `with_exceptions` build).
+
+## Performance
+
+Benchmarks show V8 is significantly faster than V7.6, especially for boolean operations:
+
+| Operation | V7.6.2 (ms) | V8 Single (ms) | Delta |
+|---|---|---|---|
+| fuse-two-boxes | 26.6 | 20.7 | -22% |
+| n-body-fuse | 65.1 | 48.3 | -26% |
+| deep-boolean-chain | 132.1 | 91.7 | -31% |
+| bottle | 342.3 | 254.4 | -26% |
+| birdhouse | 271.1 | 198.3 | -27% |
+| vase | 226.4 | 162.8 | -28% |
+
+## Package Structure
+
+```
+dist/
+  replicad-opencascadejs-0.21.0-v8.XX.tgz   # WASM + JS glue
+  replicad-0.21.0-v8.XX.tgz                 # replicad library
+```
+
+Consumers reference these tarballs via GitHub raw URLs:
+
+```yaml
+catalog:
+  replicad: "https://github.com/taucad/replicad/raw/main/dist/replicad-0.21.0-v8.XX.tgz"
+  replicad-opencascadejs: "https://github.com/taucad/replicad/raw/main/dist/replicad-opencascadejs-0.21.0-v8.XX.tgz"
+```
+
+## Removed Files
+
+- `build-config/custom_build_with_exceptions_v8.yml` — merged into `custom_build_single_v8.yml`
+- `build-config/custom_build_multi_v8.yml` — multi-threading deferred
+- `src/replicad_with_exceptions.*` — no longer needed
+- `src/replicad_multi.*` — no longer needed
+
+See `repos/opencascade.js/docs/occt-v8-migration.md` for build-level details.

packages/replicad-app-example/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicad-app-example",
-  "version": "0.23.1",
+  "version": "0.21.0",
   "description": "A simple React app based on replicad.",
   "private": true,
   "license": "MIT",
@@ -16,9 +16,9 @@
     "file-saver": "^2.0.5",
     "react": "18.2.0",
     "react-dom": "18.2.0",
-    "replicad": "^0.23.1",
-    "replicad-opencascadejs": "^0.23.0",
-    "replicad-threejs-helper": "^0.23.0",
+    "replicad": "^0.21.0",
+    "replicad-opencascadejs": "workspace:@taucad/replicad-opencascadejs@^",
+    "replicad-threejs-helper": "^0.21.0",
     "three": "^0.155.0"
   },
   "devDependencies": {

packages/replicad-app-example/src/index.jsx

@@ -3,7 +3,7 @@ import ReactDOM from "react-dom";
 import App from "./App.jsx";
 
 // This is here to compensate for a bug in vite
-import "replicad-opencascadejs/src/replicad_single.wasm?url";
+import "replicad-opencascadejs/wasm?url";
 
 ReactDOM.render(
   <React.StrictMode>

packages/replicad-app-example/src/worker.js

@@ -1,10 +1,10 @@
-import opencascade from "replicad-opencascadejs/src/replicad_single.js";
-import opencascadeWasm from "replicad-opencascadejs/src/replicad_single.wasm?url";
-import { setOC } from "replicad";
-import { expose } from "comlink";
+import opencascade from 'replicad-opencascadejs';
+import opencascadeWasm from 'replicad-opencascadejs/wasm?url';
+import { setOC } from 'replicad';
+import { expose } from 'comlink';
 
 // We import our model as a simple function
-import { drawBox } from "./cad";
+import { drawBox } from './cad';
 
 // This is the logic to load the web assembly code into replicad
 let loaded = false;

packages/replicad-app-example/vite.config.js

@@ -7,6 +7,9 @@ export default defineConfig({
   build: {
     outDir: "build",
   },
+  worker: {
+    format: "es",
+  },
   server: {
     port: 4444,
   },

packages/replicad-cli/package.json

@@ -43,9 +43,9 @@
     "commander": "^14.0.1",
     "jszip": "^3.10.1",
     "manifold-3d": "^3.0.1",
-    "replicad": "workspace:^",
+    "replicad": "workspace:@taucad/replicad@^",
     "replicad-evaluator": "workspace:^",
-    "replicad-opencascadejs": "workspace:^",
+    "replicad-opencascadejs": "workspace:@taucad/replicad-opencascadejs@^",
     "tsx": "^4.20.6"
   },
   "devDependencies": {

packages/replicad-cli/src/cli.ts

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
 import { getManifoldModule, setWasmUrl } from "manifold-3d/lib/wasm.js";
-import opencascadeModule from "replicad-opencascadejs/src/replicad_single.js";
+import opencascadeModule from "replicad-opencascadejs";
 import * as replicad from "replicad";
 import { createEvaluator } from "replicad-evaluator";
 import packageJson from "../package.json" with { type: "json" };
@@ -97,7 +97,7 @@ async function createCliEvaluator() {
     (opencascadeModule as any)?.default?.default ||
     (opencascadeModule as any)?.default ||
     opencascadeModule;
-  const wasmPath = require.resolve("replicad-opencascadejs/src/replicad_single.wasm");
+  const wasmPath = require.resolve("replicad-opencascadejs/wasm");
   const manifoldWasmPath = require.resolve("manifold-3d/manifold.wasm");
   setWasmUrl(manifoldWasmPath);
   const oc = await openCascadeFactory({

packages/replicad-evaluator/__tests__/setup.ts

@@ -1,7 +1,6 @@
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import { beforeAll } from "vitest";
-import opencascade from "../../replicad-opencascadejs/src/replicad_single.js";
+import opencascade from "replicad-opencascadejs";
 import * as replicad from "../../replicad/src/index";
 
 declare global {
@@ -12,11 +11,8 @@ declare global {
 beforeAll(async () => {
   if (globalThis.replicadEvaluatorReady) return;
 
-  const here = dirname(fileURLToPath(import.meta.url));
-  const opencascadeWasm = join(
-    here,
-    "../../replicad-opencascadejs/src/replicad_single.wasm"
-  );
+  const require = createRequire(import.meta.url);
+  const opencascadeWasm = require.resolve("replicad-opencascadejs/wasm");
 
   globalThis.replicadEvaluatorOC = await opencascade({
     locateFile: () => opencascadeWasm,

packages/replicad-evaluator/package.json

@@ -32,6 +32,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.1",
+    "replicad": "workspace:@taucad/replicad@^",
+    "replicad-opencascadejs": "workspace:@taucad/replicad-opencascadejs@^",
     "typescript": "5.1.6",
     "vite": "^4.5.5",
     "vite-plugin-dts": "^3.5.2",

packages/replicad-opencascadejs/.npmignore

@@ -0,0 +1 @@
+.npm-pack-all-tmp