first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,87 @@
+# cadjs
+
+`cadjs` is the shared JavaScript runtime for CAD Viewer, documentation previews,
+and generated snapshot browser assets. It owns reusable parsing, scene-building,
+explicit-CAD rendering, STEP topology, selector, mesh, robot-description, and
+artifact helpers without depending on React or application chrome.
+
+Implicit CAD model loading, shader rendering, snapshots, SDF sampling, and
+mesh exports live in the sibling `implicitjs` package. Consumers that need
+implicit CAD should depend on `implicitjs` directly alongside `cadjs`.
+
+## Install
+
+In this workbench, consumers link the package directly:
+
+```json
+{
+  "dependencies": {
+    "cadjs": "file:../packages/cadjs"
+  }
+}
+```
+
+The package exports source files so local consumers can alias or install it and
+pick up edits without copying generated bundles.
+
+## Layout
+
+- `src/index.js`: public package entrypoint.
+- `src/common/`: browser-safe render pipeline used by interactive viewer,
+  docs previews, and snapshot browser runtime.
+- `src/lib/`: lower-level first-party helpers for assets, formats, mesh
+  decoding, selector runtimes, STEP sidecars, and URDF/SRDF/SDF.
+- `src/lib/viewer/`: shared non-React 3D viewer runtime helpers such as picking,
+  clipping, drawing geometry, reference geometry, stage theme, scene scale, and
+  visual state.
+- `scripts/run-tests.mjs`: package test discovery and Node test runner wrapper.
+- `docs/`: reference docs for package-owned APIs.
+
+Tests live beside the modules they cover as `*.test.js` or `*.test.mjs`.
+
+## Boundaries
+
+Keep this package UI-framework agnostic. Do not add React components, Tailwind
+helpers, browser workbench state, or CAD Viewer chrome utilities here. Those
+belong in consumer apps such as `viewer/`.
+
+Prefer moving logic into `cadjs` when it is reusable across:
+
+- interactive CAD Viewer rendering,
+- docs or marketing previews,
+- generated snapshot browser runtime,
+- testable CAD parsing or sidecar preparation.
+
+Prefer moving implicit model, shader, snapshot, SDF, or mesh-export behavior
+into `implicitjs` instead.
+
+Keep app-specific workflows in the app. A useful rule of thumb: `cadjs` should
+understand CAD data and rendering state, while `viewer/` should understand user
+interface and product workflow.
+
+## Commands
+
+From this package directory:
+
+```bash
+npm test
+```
+
+From the workbench repository root:
+
+```bash
+npm --prefix packages/cadjs test
+```
+
+The test command discovers all `*.test.js` and `*.test.mjs` files under
+`src/`. To run one file:
+
+```bash
+node scripts/run-tests.mjs src/lib/themeSettings.test.js
+```
+
+## Reference
+
+- [Render pipeline](./docs/render-pipeline.md): `loadSource`, `buildModel`,
+  `renderModel`, and `captureModel` stages shared by viewer, docs, and
+  snapshots.