ShapeItUp CLAUDE.md

ShapeItUp — Project Context for Claude

What is this?

ShapeItUp is a scripted CAD tool built as a VS Code extension. Users write .shape.ts TypeScript files using the Replicad library (OpenCascade WASM), and the extension renders them in a Three.js 3D viewer. It includes an MCP server so Claude Code can create, modify, and visually verify CAD models.

Tech Stack

• TypeScript — everything (extension, viewer, worker, MCP server, shape scripts)
• Replicad (npm: replicad) — CAD library wrapping OpenCascade compiled to WASM
• Three.js — 3D rendering in VS Code webview
• esbuild — builds all packages + bundles .shape.ts files at runtime (resolves local imports)
• pnpm workspaces — monorepo package management
• Node 24+ required

Architecture

Extension Host (Node.js)     Webview (Browser)           Web Worker (Browser)
┌──────────────────┐        ┌─────────────────┐        ┌──────────────────┐
│ File watcher      │──────→│ Three.js viewer  │──────→│ OCCT WASM        │
│ esbuild bundler   │       │ Orbit controls   │       │ Replicad         │
│ Export to disk    │←──────│ Edge rendering   │←──────│ Script execution │
│ MCP bridge        │       │ Params sliders   │       │ Tessellation     │
└──────────────────┘        └─────────────────┘        └──────────────────┘

Script execution flow:

1. User saves part.shape.ts
2. Extension host bundles it with esbuild.build() (resolves local imports, keeps replicad external)
3. Sends bundled JS to webview via postMessage
4. Webview forwards to Web Worker
5. Worker rewrites import {...} from "replicad" → destructures from pre-loaded module
6. Worker executes script, calls main(), gets Shape3D (or array of parts)
7. Worker tessellates → mesh arrays (vertices, normals, triangles, edges)
8. Posts arrays as Transferable buffers back to webview
9. Webview builds THREE.BufferGeometry + LineSegments, renders

Project Structure

packages/
  extension/     — VS Code extension host (commands, file watching, webview provider)
  viewer/        — Three.js 3D viewer (runs in webview)
  worker/        — OCCT WASM + Replicad script execution (runs in web worker)
  mcp-server/    — Claude Code MCP server (stdio)
  serve/         — Standalone HTTP+WS viewer host (browser instead of webview)
  shared/        — Shared types, message defs, viewer HTML template, bundle spec
examples/        — Example .shape.ts files
skills/          — Claude Code skill (skills/<name>/SKILL.md layout)