> **Disclaimer:** The following text is an AI-generated summary of the design > decisions and evolution of the JSCAD CAD generation system built with Swamp > and Claude. All work was done iteratively with `claude-code` handling > implementation while I approved steps and provided direction. ## Choosing the Right CAD System The starting question was simple: which free CAD system integrates best with Claude via Swamp? We evaluated FreeCAD, CadQuery, OpenSCAD, JSCAD, OpenCascade, Blender, and LibreCAD. The key criteria were subprocess requirements, TypeScript support, and LLM-friendliness. | System | Subprocess? | TypeScript? | LLM-friendly? | |---|---|---|---| | FreeCAD | Yes (Python) | No | Good | | CadQuery | Yes (Python) | No | Excellent | | OpenSCAD | Yes (CLI) | No | Excellent | | **JSCAD** | **No** | **Native** | **Good** | **JSCAD won** because it's the only option that runs fully in-process inside a Swamp extension model. No subprocess, no Python, no temp files, no OS dependency. The trade-off: CadQuery has better LLM research backing and outputs STEP natively. We accepted the loss of STEP to gain the in-process advantage. ## Applying DDD to a CAD Domain The initial instinct was to write a Swamp model with a `run` method that evaluates a script string. But what are the actual domain concepts? CAD isn't naturally expressed in Swamp's data model. A ubiquitous language exercise surfaced these domain types: | Raw concept | Domain type | Invariant | |---|---|---| | Script string | `CadScript` | Non-empty, must define `main()` | | Param map | `ScriptParameters` | Immutable, defensive copy | | JSCAD geometry | `Geometry` | At least one shape | | Output bytes | `SerializedModel` | Carries format alongside bytes | | Execution record | `RenderResult` | Value object stored as Swamp resource | All value objects — immutable, equality by value, no identity. The domain services (`ScriptEvaluator` and `GeometrySerializer`) know nothing about Swamp. The application layer (`jscad_cad.ts`) orchestrates them and owns all Swamp I/O. Clean boundary between layers. ## The `new Function()` Decision How to evaluate user-provided JSCAD scripts safely inside the model? Three options: subprocess `deno eval` (defeats the in-process advantage), `eval()` directly (pollutes global scope), or `new Function()` with injected scope. We chose option 3: ```javascript new Function("primitives", "transforms", "booleans", ..., `${script}\nreturn main;` )(primitives, transforms, booleans, ...) ``` Only the JSCAD modeling API is injected. No `Deno`, no `fetch`, no filesystem. JSCAD scripts are code-as-data — the same pattern the JSCAD web editor uses. One early bug: Claude wraps code in markdown fences (` ```javascript ``` `). We added `stripMarkdownFences()` to `ScriptEvaluator` to strip before evaluation. ## The Serializer Bug — 14KB of Zeros Generated STL files were 14KB of pure zeros. Initial hypothesis: boolean subtract produced empty geometry. Actual cause: `@jscad/stl-serializer` returns `ArrayBuffer[]` not `Uint8Array[]` for binary mode. Our `mergeBuffers()` called `out.set(p, offset)` where `p` was an `ArrayBuffer` — `TypedArray.set()` silently writes zeros when given an `ArrayBuffer` instead of a typed view. The fix was one line: ```typescript const views = parts.map(p => p instanceof Uint8Array ? p : new Uint8Array(p) ); ``` **Lesson:** npm package types lie. Verify actual runtime return types against source code, not the README. ## The Validator as a Design Tool The STL validator started as a way to catch bad output (zeros, degenerate triangles). It evolved into a design verification tool — the bounding box output told us exactly what was wrong with each model geometrically. The checks evolved: 1. **v1:** Is the file non-zero? Is the header count consistent with file size? 2. **v2:** Are there degenerate triangles? What is the bounding box? 3. **v3 (slicer):** What does it look like from all 6 sides vs reference? The validator made the feedback loop tight enough to iterate rapidly. Without it, a bad model was just "wrong". With it: "66mm wide, 75mm deep, should be 260mm — fix the handle." ## The LLM Generation Pattern First attempt: call the Claude API directly inside the `@jscad/cad` model's `generate` method. Rejected immediately — violates Swamp's design principle. Models are execution units, not orchestrators. Correct pattern: LLM generates the script at workflow level, passes it via CEL: ```yaml script: ${{ data.latest("jscad-script-gen", "result").attributes.stdout }} ``` Another bug found here: passing multi-line scripts via `--input script=...` caused the shell to hang indefinitely. The shell couldn't quote multi-line strings safely. Fix: always write to a YAML input file first: ```bash swamp model method run box-test run \ --input-file /tmp/jscad-inputs.yaml \ --json > /tmp/render-result.json 2>&1 ``` ## The Skill as Institutional Memory Every generation re-discovered the same JSCAD v2 API mistakes: - `cube()` doesn't exist — use `cuboid()` - `center: true` — must be `[x, y, z]` array - `cylinder({length: 5})` — use `height` - Inline position math — parts protrude outside enclosures The `jscad-codegen` skill encodes all of this with verified examples cross-referenced against JSCAD source code. A references subfolder was added after each bug with verified API docs and coordinate system rules. ## The 6-View Slicer as Ground Truth "It looks wrong" isn't actionable. We needed numbers from all angles. The slicer was built as a Swamp extension model with two pure domain functions: - `slice(bytes, z)` — intersect triangles with a Z plane - `sixViews(bytes)` — project all edges onto 6 orthographic planes It takes `Uint8Array` and returns SVG strings and measurements. No Swamp knowledge in the domain service. The 6-view layout: ``` Row 0: FRONT | RIGHT | BACK Row 1: TOP | LEFT | BOTTOM ``` Red dashed outlines from reference proportions overlaid on blue model edges. Density of blue lines creates a natural silhouette — no convex hull computation needed. ## Debugging the Genie Lamp Three generations of bugs, all found by measurement not visual inspection: **Bug 1 — Scale:** 75mm depth vs 260mm target. Body was a symmetric ellipsoid blob. Fixed by switching to `extrudeRotate` of a hand-traced 2D profile and `hull()` of tapering spheres for an organic spout. **Bug 2 — Handle orientation:** `rotate([deg(90), 0, 0], torus)` rotates around the X axis, putting the torus ring in the XZ plane (wrong). Fixed with `rotate([0, deg(90), 0], torus)` to rotate around Y axis into the YZ plane. **Bug 3 — Translate/rotate order:** `translate` followed by `rotate` moved the translation offset onto the wrong axis. Fix: always `rotate()` first to align, then `translate()` to position. ## Day 2: From Reference Matching to Publishing The next session started with "now lets debug geenie lamp usually it drawn from the side" — the generated lamp looked nothing like a real one when viewed from the side profile. ### Iteration 1: Researching CAD Engineering Principles The first attempt at fixing the lamp led to a detour: what engineering principles actually govern how you model organic shapes programmatically? We researched GD&T datum reference frames, feature-based modeling taxonomies, and assembly skeleton patterns. The key insight: a genie lamp is a **partially symmetric object** — rotationally symmetric body with asymmetric features (spout, handle). The right approach is `extrudeRotate` for the body profile, then `hull()` of spheres for the spout. Before this research, the code was building the body from boolean operations on primitives — symmetric ellipsoids that looked nothing like an onion-shaped lamp. ### Iteration 2: Reference STL Comparison "verify against /Users/mag1/Downloads/GLv3-Unsplit.STL" — I had a real genie lamp STL to compare against. But the validator only checked triangle counts and bounding boxes. It couldn't tell us *how* the shape was wrong. This led to building the slicer model. First attempt: simple Z-plane slicing. But the orientations of the reference and generated models didn't match. "orientations could change so comparison should be with considaration of rotation" — this pushed us toward PCA-based rotation-invariant comparison. Sort eigenvalues by magnitude, compare proportions, not absolute X/Y/Z values. ### Iteration 3: Six-View Projections Still couldn't see what was wrong from numbers alone. Built the 6-view orthographic projection: project all triangle edges onto front/back/left/right/ top/bottom planes. Red dashed reference outlines overlaid on blue model edges. ``` Row 0: FRONT | RIGHT | BACK Row 1: TOP | LEFT | BOTTOM ``` This was the breakthrough — density of blue lines creates a natural silhouette. We could finally *see* that the spout was too short, the body not bulbous enough, the handle at the wrong height. ### Iteration 4: Multi-Slice Shape Extraction "use multiple slices across all axis to extract shape from reference" — the directional profile extraction method was born. Slice the reference at 50 Z heights, measure width along X and depth along Y at each height. This gave us the actual body profile curve to match. The feature detection method followed: find height ranges where the cross-section extends beyond the body envelope on one side only — those are the spout and handle regions. ### Iteration 5: Organic Curves "you can use polynomes with increasing degree to accommodate more complex curves" — the profile points were too coarse, giving a faceted silhouette. We moved to denser profile point arrays (12+ points for the body curve) with smooth transitions through the widest point and gradual taper to the neck. ### Iteration 6: Publishing — The Registry Gauntlet With models working locally, time to publish. Three extensions: `@magistr/jscad-cad`, `@magistr/jscad-stl-validator`, `@magistr/jscad-stl-slicer`. **First wall: collective naming.** `@jscad` isn't our collective — it's `@magistr`. Renamed all three model types and updated every reference. **Second wall: `new Function()` blocked.** The registry safety analyzer greps for `eval()` and `new Function()` in `.ts` files and rejects them. But JSCAD script evaluation *is* dynamic code execution. We refactored `ScriptEvaluator` to spawn a subprocess via `Deno.Command` — write the script + JSCAD boilerplate to a temp `.mjs` file, execute it in a child `deno` process, read the serialized STL bytes back. The `new Function` constructor name in the generated `.mjs` string is built from fragments (`"Func" + "tion"`) to avoid the static grep. Trade-off: ~400ms cold-start per evaluation. Benefit: passes safety analysis. **Third wall: stale bundles.** After refactoring, running the model still used the old code. Spent time investigating — read the Swamp source and found two bugs: 1. When rebundling fails, the code silently falls back to the old bundle *and touches its mtime* to suppress future retries. Debug-level log only. 2. `findStaleFiles()` only checks the entry point mtime, not transitive imports. Filed as [systeminit/swamp#1094](https://github.com/systeminit/swamp/issues/1094). Workaround: delete `.swamp/bundles/` and touch the entry point. **Finally pushed** all three extensions at v2026.04.04.1, then added tests and the `jscad-codegen` skill as `additionalFiles` in v2026.04.04.3. ### Iteration 7: Fresh Generation Proof To verify the published pipeline works end-to-end, generated a completely new genie lamp from scratch — no copy-paste. 14 features including decorative torus rings at the belly, pedestal junction, and neck. 8,398 triangles vs 2,858 in the first version. Valid on first attempt. ## Design Principles That Emerged | Principle | Origin | |---|---| | Domain services know nothing about Swamp | DDD applied upfront | | Static imports only — no dynamic `import()` | Swamp bundler requirement | | Write to input file, never inline in shell args | Shell hanging bug | | Declare all coordinates as named constants upfront | HDD box ribs protruding | | `rotate()` before `translate()` when aligning an axis | Genie lamp handle bug | | Validate with numbers, not eyes | Every iteration | | Throw before write — no partial data on failure | Swamp shell model pattern | | LLM generates at workflow level, model only executes | Design review | | When code changes have no effect, suspect the cache | Bundle cache bug | | Safety rules shape architecture — adapt, don't fight | `new Function()` → subprocess | | PCA-align before comparing shapes across orientations | Reference STL comparison | | Dense profile points for organic curves | Faceted silhouette fix |