CLAUDE.md#

Tips for future agents working in this repo.

Architecture#

src/occ/       ALL OpenCASCADE.js access lives here. The rest of the app never
               touches OCCT — it only sees the SurfaceModel from src/model.
  loader.ts      initOpenCascade({ mainWasm: wasmUrl }) once; wasm imported with
                 `?url` so Vite emits it as a static asset. Lazy on first use.
  primitives.ts  BRepPrimAPI_* builders returning TopoDS_Shape.
  importCad.ts   STEP/IGES via FS.createDataFile + STEPControl_Reader/IGESControl_Reader.
  exportCad.ts   STEPControl_Writer -> bytes.
  extract.ts     shape -> SurfaceModel. Runs BRepMesh (triangulation, always) and
                 BRepBuilderAPI_NurbsConvert + Geom_BSplineSurface reads (per-face,
                 best-effort). retessellate() re-meshes at a new quality reusing NURBS.
src/model/     types.ts: SurfaceModel = list of Patch (discriminated union).
               v1 emits `nurbs` patches. tessellate.ts: pure geometry helpers
               (modelBounds, controlNet, mergeTriMeshes) — no three, no OCCT.
src/render/    SurfaceView.tsx: plain three.js, one mesh per patch (for picking),
               modes shaded/wire/net/iso. palette.ts: per-face colors.
src/export/    meshWriters.ts (OBJ/PLY/STL, dependency-free), nurbsJson.ts.
src/App.tsx    sidebar + viewport; keeps the OpenCascade instance and the
               (NURBS-converted) mesh shape in refs for re-tessellation.
src/abcDataset.ts  "Random CAD model" source: fetches index.json from
               https://concept-collection.github.io/abc-step-1000/ (first 1000
               ABC-dataset STEP files, gzip-served), picks a random file ≤2 MB,
               gunzips via DecompressionStream, hands bytes to importCadFile.

Key gotchas#

• OCCT is typed as any (src/occ/types.ts). opencascade.js ships a huge generated .d.ts, and the overload-suffixed member names (_1, _2, …) are only verifiable at runtime. Keep all OCCT calls in src/occ/*; everything else is strictly typed against SurfaceModel. The build gate is tsc -b && vite build — runtime correctness of OCCT calls must be checked in a real browser (npm run dev).
• opencascade.js is pinned to the beta (2.0.0-beta.b5ff984). latest (1.1.1) is an older, different API. Overload suffixes and the ?url wasm recipe follow the beta and its examples (donalffons/opencascade.js-examples).
• NURBS extraction is best-effort. Rendering only needs the BRepMesh triangulation, which always runs. extractNurbs is wrapped in try/catch per face and returns null on any failure; the sidebar shows "N/M faces" coverage. If a binding is missing in the build, coverage drops but the app still works.
• Mesh density uses BRepMesh relative mode (isRelative = true), so the quality slider is a dimensionless fraction independent of model scale — no bounding-box computation needed. retessellate calls BRepTools.Clean first (in a try/catch) so a finer deflection actually refines.
• The "Sample STEP" button round-trips a box through shapeToStep + importCadFile — it exercises the whole STEP export+import pipeline with no bundled asset, and is the quickest end-to-end check of the CAD path.

Verification#

Browser is the real verification surface (WASM). npm run build confirms TS + bundling (including the OCCT wasm asset). Then npm run dev and:

• load each primitive; toggle shaded / wireframe / control-net / isocurves;
• drag the resolution slider (faceting should visibly change);
• click a face → the inspector shows degree / poles / knots;
• "Sample STEP" and a real uploaded STEP/IGES both render;
• "Random CAD model" downloads from abc-step-1000 and renders (needs that Pages site up, and the network);
• export OBJ/PLY/STL/NURBS-JSON/STEP.

Not yet deployed to the org Pages site (same procedure as mesh-converter / mesh-pde-solver when ready).