How zalo/cascadestudio works
1. Overall shape
- This is an npm workspaces monorepo with two runtime packages: cascade-core and cascade-studio.
- cascade-core is the reusable CAD engine; cascade-studio is the browser-based IDE built on top of it.
- The architectural boundary is clear: core contains modeling/runtime logic, studio contains UI, layout, and user interaction.
2. cascade-core: modeling engine boundary
- packages/cascade-core/src/index.js exposes the package API.
- CascadeEngine.js is the main-thread façade that clients use to initialize the engine and submit code.
- It talks to a Web Worker through MessageBus.js, which is the main isolation boundary between UI code and CAD execution.
3. Worker-based execution model
- packages/cascade-core/src/worker/CascadeWorker.js is the worker entry point.
- User-authored model code is evaluated inside the worker, not on the main thread.
- This keeps heavy geometry operations and kernel interaction off the UI thread and makes the engine embeddable in other web apps.
4. CAD standard library and geometry operations
- StandardLibrary.js provides the modeling API exposed to users: primitives, sketches, transforms, booleans, fillets, selectors, measurements, and similar operations.
- The README’s Box, Sketch, Union, FilletEdges, Edges, Volume, etc. all come from this layer.
- This library is the semantic layer that user scripts target before any rendering or export happens.
5. OpenCascade kernel integration
- The repo’s CAD backend is OpenCascade via opencascade.js/OCCT, which is a major architectural dependency.
- ShapeToMesh.js converts kernel shapes into renderable mesh data.
- FileUtils.js handles CAD file import/export paths such as STEP, IGES, STL, and related shape I/O.
6. OpenSCAD support as a separate input language
- packages/cascade-core/src/openscad/OpenSCADTranspiler.js converts OpenSCAD into the JavaScript standard-library form used by the engine.
- This means OpenSCAD is not a parallel execution engine; it is a source-language front end feeding the same core modeling pipeline.
- In the studio, packages/cascade-studio/src/openscad/OpenSCADMonaco.js provides the editor-side language integration.
7. cascade-studio: browser application shell
- packages/cascade-studio/src/main.js is the entry point for the IDE.
- CascadeMain.js coordinates the application shell and layout.
- The app is structured as a browser SPA with static assets, PWA support, and deployment to GitHub Pages/Vercel.
8. Studio UI subsystem boundaries
- CascadeView.js owns the 3D viewport and modeling timeline.
- EditorManager.js owns the Monaco editor and code evaluation flow.
- ConsoleManager.js captures logs/errors, and GUIManager.js manages Tweakpane-based parameter controls.
- These modules are separate UI concerns; they do not own CAD logic themselves.
9. Studio-to-core integration
- CascadeAPI.js exposes window.CascadeAPI for automation and external control, including Playwright-driven tests.
- The studio uses the core engine as a service boundary: editor input is compiled/evaluated by the engine, and results come back as mesh/history/log data.
- The viewport then renders mesh output, while the console and GUI reflect evaluation state and parameters.
10. Data flow from code to model
- User edits JavaScript or OpenSCAD in Monaco.
- The source is passed into the engine worker through the CascadeEngine/MessageBus path.
- The worker evaluates the code using the standard library, builds OCCT shapes, optionally applies imports/transforms/booleans, and then triangulates to mesh data.
- Studio receives the result for rendering, history scrubbing, exporting, and URL serialization/sharing.
11. Import/export and persistence
- File import/export is a cross-cutting capability in cascade-core, not a studio-only feature.
- The README indicates support for .STEP, .IGES, .STL import and .STEP, .STL, .OBJ export.
- Project state is also serialized into the URL, which is a key persistence/share boundary in the system.
12. Build and distribution
- The repo is built with esbuild, with cascade-core built before cascade-studio.
- packages/cascade-core/scripts/build.cjs and packages/cascade-studio/scripts/build.cjs produce the distributed artifacts.
- The studio output is served from packages/cascade-studio/dist, with PWA/service-worker support for offline use.
13. Testing and automation
- The root test/ directory contains Playwright-based end-to-end tests.
- Tests cover geometry operations, OpenSCAD support, exports, and screenshot regression.
- The browser automation surface is important architecturally because CascadeAPI is designed to support it.
14. Key diagram boundaries to draw
- One boundary around the browser UI layer (cascade-studio).
- One boundary around the engine layer (cascade-core), split into main-thread API and worker execution.
- One boundary around the OpenCascade kernel/WASM-backed geometry runtime inside the worker.
- One boundary around static assets and deployment (icons, fonts, service worker, GitHub Pages/Vercel), which support distribution but do not change modeling logic.
Main entry points: CascadeMain.js Shell · CascadeWorker.js Worker · CascadeEngine.js Engine · EditorManager.js Editor
Components 20
Workspace
npm workspaces monorepo
- Workspaces · Root workspace coordinating core and studio packages
cascade-core
Reusable CAD engine
- API · Public entry point for cascade-core
packages/cascade-core/src/index.js - Engine · Initializes the engine and submits model code
packages/cascade-core/src/engine/CascadeEngine.js - Message Bus · Isolation boundary between UI code and CAD execution
packages/cascade-core/src/engine/MessageBus.js - Worker · Worker entry point that evaluates user-authored model code
packages/cascade-core/src/worker/CascadeWorker.js - Stdlib · User-facing CAD primitives, transforms, booleans, selectors, and measurements
packages/cascade-core/src/worker/StandardLibrary.js - OpenCascade · WASM-backed geometry kernel used for modeling and shape operations
- Mesh · Converts kernel shapes into renderable mesh data
packages/cascade-core/src/worker/ShapeToMesh.js - CAD I/O · STEP, IGES, STL, OBJ and related shape file handling
packages/cascade-core/src/worker/FileUtils.js - OpenSCAD · Transpiles OpenSCAD into the shared JavaScript modeling pipeline
packages/cascade-core/src/openscad/OpenSCADTranspiler.js
cascade-studio
Browser IDE built on core
- Main · Browser IDE entry point
packages/cascade-studio/src/main.js - Shell · Coordinates the studio application shell and layout
packages/cascade-studio/src/CascadeMain.js - Viewport · Owns the model view and timeline rendering
packages/cascade-studio/src/CascadeView.js - Editor · Monaco editor and code evaluation flow
packages/cascade-studio/src/EditorManager.js - Console · Captures logs, errors, and evaluation feedback
packages/cascade-studio/src/ConsoleManager.js - GUI · Tweakpane-based parameter controls
packages/cascade-studio/src/GUIManager.js - CascadeAPI · Window-level control surface for automation and external scripting
packages/cascade-studio/src/CascadeAPI.js - SCAD Monaco · OpenSCAD editor support in the studio
packages/cascade-studio/src/openscad/OpenSCADMonaco.js
Delivery
Build, PWA, and deployment boundary
- PWA + Deploy · Static assets, service worker, and deployment packaging
packages/cascade-studio/service-worker.js
Testing
Automation and regression coverage
- Playwright · Browser automation and regression tests
test/cascade-studio.spec.js
Connections 21
- Workspaces → API: contains · Workspace includes the reusable engine package
- Workspaces → Main: contains · Workspace includes the browser IDE package
- API → Engine: exports · Package entry exposes the engine API
- Engine → Message Bus: dispatches · Main thread communicates through the message bus
- Message Bus → Worker: isolates · Worker boundary runs model execution off the UI thread
- Worker → Stdlib: evaluates · Worker executes user code against the modeling API
- Stdlib → OpenCascade: drives · Standard library builds geometry through OpenCascade
- Worker → Mesh: triangulates · Shapes are converted into renderable mesh data
- Worker → CAD I/O: imports/exports · Worker handles CAD file I/O paths
- OpenSCAD → Stdlib: transpiles to · OpenSCAD is lowered into the shared modeling API
- Main → Shell: boots · Application entry initializes the studio shell
- Shell → Viewport: coordinates · Shell manages the 3D viewport
- Shell → Editor: coordinates · Shell manages source editing
- Shell → Console: coordinates · Shell manages logging and errors
- Shell → GUI: coordinates · Shell manages parameter controls
- Editor → Engine: runs code · Editor submits JS/OpenSCAD source to the engine
- Engine → Viewport: returns model · Engine results feed the viewport as meshes/history
- CascadeAPI → Playwright: drives · Automation surface supports Playwright-based testing
- SCAD Monaco → Editor: extends · OpenSCAD editor support plugs into the code editor
- PWA + Deploy → Main: packages · Static app shell is bundled for distribution and offline use
- Editor → CascadeAPI: exposes · Studio state can be controlled externally through the API