1# CLAUDE.md
3Tips for future agents working in this repo.
5## Architecture
7```
8src/occ/ ALL OpenCASCADE.js access lives here. The rest of the app never
9 touches OCCT — it only sees the SurfaceModel from src/model.
10 loader.ts initOpenCascade({ mainWasm: wasmUrl }) once; wasm imported with
11 `?url` so Vite emits it as a static asset. Lazy on first use.
12 primitives.ts BRepPrimAPI_* builders returning TopoDS_Shape.
13 importCad.ts STEP/IGES via FS.createDataFile + STEPControl_Reader/IGESControl_Reader.
14 exportCad.ts STEPControl_Writer -> bytes.
15 extract.ts shape -> SurfaceModel. Runs BRepMesh (triangulation, always) and
16 BRepBuilderAPI_NurbsConvert + Geom_BSplineSurface reads (per-face,
17 best-effort). retessellate() re-meshes at a new quality reusing NURBS.
18src/model/ types.ts: SurfaceModel = list of Patch (discriminated union).
19 v1 emits `nurbs` patches. tessellate.ts: pure geometry helpers
20 (modelBounds, controlNet, mergeTriMeshes) — no three, no OCCT.
21src/render/ SurfaceView.tsx: plain three.js, one mesh per patch (for picking),
22 modes shaded/wire/net/iso. palette.ts: per-face colors.
23src/export/ meshWriters.ts (OBJ/PLY/STL, dependency-free), nurbsJson.ts.
24src/App.tsx sidebar + viewport; keeps the OpenCascade instance and the
25 (NURBS-converted) mesh shape in refs for re-tessellation.
26```
28## Key gotchas
30- **OCCT is typed as `any`** (`src/occ/types.ts`). opencascade.js ships a huge
31 generated `.d.ts`, and the overload-suffixed member names (`_1`, `_2`, …) are
32 only verifiable at runtime. Keep all OCCT calls in `src/occ/*`; everything
33 else is strictly typed against `SurfaceModel`. The **build gate is `tsc -b &&
34 vite build`** — runtime correctness of OCCT calls must be checked in a real
35 browser (`npm run dev`).
36- **opencascade.js is pinned to the beta** (`2.0.0-beta.b5ff984`). `latest`
37 (1.1.1) is an older, different API. Overload suffixes and the `?url` wasm
38 recipe follow the beta and its examples (donalffons/opencascade.js-examples).
39- **NURBS extraction is best-effort.** Rendering only needs the BRepMesh
40 triangulation, which always runs. `extractNurbs` is wrapped in try/catch per
41 face and returns null on any failure; the sidebar shows "N/M faces" coverage.
42 If a binding is missing in the build, coverage drops but the app still works.
43- **Mesh density uses BRepMesh relative mode** (`isRelative = true`), so the
44 quality slider is a dimensionless fraction independent of model scale — no
45 bounding-box computation needed. `retessellate` calls `BRepTools.Clean` first
46 (in a try/catch) so a finer deflection actually refines.
47- **The "Sample STEP" button** round-trips a box through `shapeToStep` +
48 `importCadFile` — it exercises the whole STEP export+import pipeline with no
49 bundled asset, and is the quickest end-to-end check of the CAD path.
51## Verification
53Browser is the real verification surface (WASM). `npm run build` confirms TS +
54bundling (including the OCCT wasm asset). Then `npm run dev` and:
55- load each primitive; toggle shaded / wireframe / control-net / isocurves;
56- drag the resolution slider (faceting should visibly change);
57- click a face → the inspector shows degree / poles / knots;
58- "Sample STEP" and a real uploaded STEP/IGES both render;
59- export OBJ/PLY/STL/NURBS-JSON/STEP.
61Not yet deployed to the org Pages site (same procedure as mesh-converter /
62mesh-pde-solver when ready).