cadcode 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,215 @@
-# Temporary Holding Version
+# cadcode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Code-first CAD. Write a model in JavaScript, see it live in the browser while you edit, and export STL for printing and PNG for previews. There is no modeling UI: your editor is the CAD system.
+
+The geometry runs on [manifold](https://github.com/elalish/manifold), the same boolean engine recent OpenSCAD uses, so solids always come out watertight. The API keeps OpenSCAD's ideas (cube, cylinder, hull, difference, `$fn`), so OpenSCAD models port line by line.
+
+```js
+import { cube, cylinder, difference } from 'cadcode';
+
+export default difference(
+  cube([20, 20, 5], { center: true }),
+  cylinder({ d: 6, h: 10, center: true }),
+);
+```
+
+```bash
+npx cadcode dev plate.js
+```
+
+## Install
+
+```bash
+npm install cadcode
+```
+
+Requires Node 20 or newer.
+
+## Commands
+
+```bash
+cadcode dev <file>      # live preview in the browser, reloads on save
+cadcode stl <file>      # export a part to binary STL
+cadcode png <file>      # render a part to a PNG preview
+cadcode parts <file>    # list the parts a program defines
+```
+
+| Option | Applies to | Meaning |
+| --- | --- | --- |
+| `-p, --part <name>` | all | Part to use. The default is the first one. |
+| `-a, --all` | stl, png | Export every part, one file each. |
+| `-s, --set <key=value>` | all | Override a parameter. Repeatable. Values are parsed as JSON, falling back to strings. |
+| `-o, --out <path>` | stl, png | Output file, or a directory with `--all`. The default is `<name>.stl` or `<name>-<part>.stl` in the current directory. |
+| `--view <name>` | png | `iso` (default), `iso-back`, `front`, `back`, `left`, `right`, `top`, `bottom`, or `sheet` for iso, front, right and top in one image. |
+| `--size <WxH>` | png | Image size. The default is `800x600`. |
+| `--port <n>` | dev | The default is `5173`. |
+| `--host <addr>` | dev | The default is `127.0.0.1`. |
+| `--open` | dev | Open the browser. |
+
+```bash
+cadcode stl case.js --part box --set wall=2.4
+cadcode stl case.js --all -o out/
+cadcode png case.js --part assembly --view sheet --size 1600x1200
+```
+
+### The dev viewer
+
+`cadcode dev` watches the program and every file it imports. On each save it rebuilds the model and swaps it into the page without touching the camera, so you keep your angle, position and zoom while you iterate. The camera is also remembered per file across browser refreshes and server restarts.
+
+- **Rotate**: drag
+- **Pan**: shift+drag or right-drag
+- **Zoom**: mouse wheel
+- **Fit the model to the view**: F, or the Fit button
+- **Switch parts**: the part dropdown
+
+Errors appear in the page and in the terminal, with the line in your file. The last good model stays on screen until you fix them. Whatever the program prints with `console.log` appears in the corner of the page.
+
+## Writing a program
+
+A program is an ES module. Its default export is one of these:
+
+- **A model**: a solid, or an array of solids. Arrays may nest.
+- **An object of named parts**: each value is a model, or a function that returns one. Functions are only called for the part being shown or exported.
+- **A function of `params`**: it returns either of the above.
+
+Parameters you might want to change from the command line go in `export const params`. `--set` can only override a parameter declared there, so a typo is an error instead of being silently ignored.
+
+```js
+import { cube, cylinder, hull, product, setResolution } from 'cadcode';
+
+setResolution({ fn: 48 });
+
+export const params = {
+  width: 40,
+  depth: 30,
+  height: 12,
+  wall: 2,
+  radius: 3,
+};
+
+export default (p) => {
+  const roundedBox = (w, d, h, r) =>
+    hull(product([r, w - r], [r, d - r]).map(([x, y]) => cylinder({ r, h }).translate([x, y, 0])));
+
+  const tray = () =>
+    roundedBox(p.width, p.depth, p.height, p.radius).subtract(
+      roundedBox(p.width - 2 * p.wall, p.depth - 2 * p.wall, p.height, p.radius - p.wall).translate([p.wall, p.wall, p.wall]),
+    );
+
+  return {
+    assembly: () => [tray().color('steelblue'), cube([10, 10, 4]).translate([5, 5, p.wall]).color('orange', 0.6)],
+    tray,
+  };
+};
+```
+
+The first part is the default one. The STL of a part merges all its solids into one body. In the viewer and in PNGs each solid keeps its own color and transparency, which is what assembly views are for.
+
+A program can import its own helper files and npm packages like any module. TypeScript files work too.
+
+[`examples/sensor-case.js`](examples/sensor-case.js) is a complete project: a snap-fit case for a board, a battery and a sensor, with `assembly`, `box`, `lid` and `print` parts.
+
+## API
+
+Every shape is immutable: methods return a new shape. Units are whatever your slicer assumes, usually millimeters. Angles are in degrees.
+
+Wherever a list of shapes is accepted, it may contain nested arrays and falsy values. That makes loops and conditionals read naturally:
+
+```js
+difference(base, holes.map(([x, y]) => cylinder({ d: 3, h: 10 }).translate([x, y, -1])), withSlot && slot);
+```
+
+### 3D primitives
+
+| Function | Notes |
+| --- | --- |
+| `cube(size, { center })` | `size` is a number or `[x, y, z]`. A corner sits at the origin unless `center: true`. |
+| `cylinder({ h, r \| d, r1, r2, d1, d2, center, fn })` | Stands on XY along +Z. Give `r1`/`r2` for a cone. |
+| `sphere(r)` or `sphere({ r \| d, fn })` | Centered on the origin. |
+| `polyhedron(points, faces)` | Faces list point indices clockwise when seen from outside, as in OpenSCAD. |
+
+### 2D primitives
+
+| Function | Notes |
+| --- | --- |
+| `square(size, { center })` | `size` is a number or `[x, y]`. |
+| `circle(r)` or `circle({ r \| d, fn })` | |
+| `polygon(points, paths?)` | Paths inside other paths become holes. |
+
+### Solid methods
+
+| Method | Notes |
+| --- | --- |
+| `.translate([x, y, z])` | |
+| `.rotate([x, y, z])` | Around X, then Y, then Z, like OpenSCAD. `.rotate(a)` turns around Z, and `.rotate(a, [x, y, z])` around any axis. |
+| `.scale(s)` or `.scale([x, y, z])` | |
+| `.mirror([nx, ny, nz])` | Across the plane through the origin with this normal. |
+| `.transform(matrix)` | A column-major 4×4 matrix, as 16 numbers. |
+| `.color(name, alpha?)` | A CSS color name, `#rrggbb`, or `[r, g, b, a]` in 0..1. Colors survive booleans. |
+| `.union(...shapes)` | |
+| `.subtract(...shapes)` | |
+| `.intersect(...shapes)` | |
+| `.hull(...shapes)` | Convex hull of this shape and the others. |
+| `.slice(z)` | The 2D cross-section at height `z`. |
+| `.project()` | The 2D outline seen from above. |
+| `.volume()`, `.surfaceArea()`, `.bounds()`, `.isEmpty()` | `bounds()` returns `{ min: [x, y, z], max: [x, y, z] }`. |
+
+### 2D shape methods
+
+| Method | Notes |
+| --- | --- |
+| `.translate([x, y])`, `.rotate(a)`, `.scale(s)`, `.mirror([nx, ny])` | |
+| `.offset(r)` | Grow (or shrink, when negative) with rounded corners. `.offset({ delta })` keeps corners sharp, and `.offset({ delta, chamfer: true })` cuts them. |
+| `.union()`, `.subtract()`, `.intersect()`, `.hull()` | Same as for solids. |
+| `.extrude(h, { center, twist, scale, divisions })` | Extrudes along +Z, like `linear_extrude`. |
+| `.revolve({ angle, fn })` | Revolves the shape around the Y axis into a solid around Z, like `rotate_extrude`. |
+| `.area()`, `.bounds()`, `.isEmpty()`, `.toPolygons()` | |
+
+### Functions
+
+These take any mix of shapes and nested arrays, so OpenSCAD's nesting style works as well as method chaining:
+
+| Function | Equivalent |
+| --- | --- |
+| `union(...shapes)` | |
+| `difference(base, ...cutters)` | `base.subtract(...cutters)` |
+| `intersection(...shapes)` | |
+| `hull(...shapes)` | |
+| `translate(v, ...shapes)` | `union(...shapes).translate(v)` |
+| `rotate(a, ...shapes)` | `union(...shapes).rotate(a)` |
+| `scale(v, ...shapes)` | `union(...shapes).scale(v)` |
+| `mirror(n, ...shapes)` | `union(...shapes).mirror(n)` |
+| `color(c, alpha?, ...shapes)` | `union(...shapes).color(c, alpha)` |
+| `offset(r, ...shapes)` | `union(...shapes).offset(r)` |
+| `linearExtrude(h, options, ...shapes)` | `union(...shapes).extrude(h, options)` |
+
+### Helpers
+
+| Function | Notes |
+| --- | --- |
+| `range(start, end, step = 1)` | Includes `end`, like OpenSCAD's `[start : step : end]`. |
+| `product(...lists)` | Every combination, like `for (x = xs, y = ys)`: `product([1, 2], ['a', 'b'])` gives `[[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]`. |
+| `setResolution({ fn, fa, fs })` | Default segment count for curves, with the same rules as OpenSCAD's `$fn`, `$fa` and `$fs`. Any primitive also takes its own `fn`. |
+
+## Porting from OpenSCAD
+
+| OpenSCAD | cadcode |
+| --- | --- |
+| `$fn = 40;` | `setResolution({ fn: 40 });` |
+| `cylinder(d = 5, h = 2, center = true);` | `cylinder({ d: 5, h: 2, center: true })` |
+| `translate([x, y, 0]) rotate([0, 90, 0]) cube(s);` | `cube(s).rotate([0, 90, 0]).translate([x, y, 0])` |
+| `difference() { a(); b(); c(); }` | `difference(a(), b(), c())` |
+| `for (x = xs, y = ys) translate([x, y]) c();` | `product(xs, ys).map(([x, y]) => c().translate([x, y]))` |
+| `for (i = [0 : n - 1])` | `range(0, n - 1).map((i) => ...)` |
+| `linear_extrude(h) offset(r = 1) square(s, center = true);` | `square(s, { center: true }).offset(1).extrude(h)` |
+| `color("orange", 0.35) lid();` | `lid().color('orange', 0.35)` |
+| `module box() { ... }` | `const box = () => ...` |
+| `part = "box";` with `-D 'part="box"'` | Named parts and `--part box` |
+| `wall = 2;` with `-D wall=2.4` | `export const params = { wall: 2 }` and `--set wall=2.4` |
+| `echo(...)` | `console.log(...)` |
+
+When chaining, read OpenSCAD's transforms from the innermost one out. `translate(t) rotate(r) child` becomes `child.rotate(r).translate(t)`.
+
+## License
+
+MIT

package/client/index.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>cadcode</title>
+    <link rel="stylesheet" href="/viewer.css" />
+    <script type="importmap">
+      {
+        "imports": {
+          "three": "/vendor/three/build/three.module.js",
+          "three/addons/": "/vendor/three/examples/jsm/"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <canvas id="view"></canvas>
+
+    <div class="top">
+      <header class="bar">
+        <span class="brand">cadcode</span>
+        <span id="file" class="file"
+          ><span class="dir"></span><span class="name"></span
+        ></span>
+        <label class="part">
+          <span>part</span>
+          <select id="part"></select>
+        </label>
+        <span id="status" class="status" data-state="connecting"
+          >connecting</span
+        >
+        <button id="fit" type="button" title="Fit model to view (F)">
+          Fit
+        </button>
+      </header>
+
+      <section id="logs" class="logs" hidden></section>
+    </div>
+
+    <section id="error" class="error" hidden>
+      <pre id="error-text"></pre>
+    </section>
+
+    <footer class="hint">
+      drag: rotate · shift+drag or right-drag: pan · wheel: zoom · F: fit
+    </footer>
+
+    <script type="module" src="/viewer.js"></script>
+  </body>
+</html>

package/client/viewer.css

@@ -0,0 +1,216 @@
+:root {
+  --bg: #eef0f3;
+  --panel: rgba(255, 255, 255, 0.86);
+  --text: #1d2228;
+  --muted: #6b7480;
+  --border: rgba(20, 30, 40, 0.12);
+  --ok: #2f9e5b;
+  --busy: #c98a12;
+  --bad: #c8372d;
+  font: 13px/1.4 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
+  color: var(--text);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  height: 100%;
+  overflow: hidden;
+  background: var(--bg);
+}
+
+#view {
+  position: fixed;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+/* Toolbar on the left, program output on the right; they share one row so they never overlap. */
+.top {
+  position: fixed;
+  top: 12px;
+  left: 12px;
+  right: 12px;
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 12px;
+  pointer-events: none;
+}
+
+.top > * {
+  pointer-events: auto;
+}
+
+.bar {
+  flex: 0 1 auto;
+  min-width: 0;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 6px 8px 6px 12px;
+  background: var(--panel);
+  backdrop-filter: blur(8px);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.06);
+}
+
+.bar > :not(.file) {
+  flex-shrink: 0;
+}
+
+.brand {
+  font-weight: 650;
+  letter-spacing: 0.02em;
+}
+
+.file {
+  display: flex;
+  min-width: 0;
+  color: var(--muted);
+  font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+/* A long path gives up its directory first; the file name always stays. */
+.file .dir {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file .name {
+  flex-shrink: 0;
+}
+
+.part {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--muted);
+}
+
+select,
+button {
+  font: inherit;
+  color: var(--text);
+  background: #fff;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 3px 8px;
+}
+
+button {
+  cursor: pointer;
+}
+
+button:hover,
+select:hover {
+  border-color: rgba(20, 30, 40, 0.28);
+}
+
+.status {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--muted);
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+
+.status::before {
+  content: '';
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--muted);
+}
+
+.status[data-state='ready']::before {
+  background: var(--ok);
+}
+
+.status[data-state='building']::before,
+.status[data-state='evaluating']::before {
+  background: var(--busy);
+}
+
+.status[data-state='error']::before,
+.status[data-state='disconnected']::before {
+  background: var(--bad);
+}
+
+.error {
+  position: fixed;
+  left: 12px;
+  right: 12px;
+  bottom: 40px;
+  max-height: 45vh;
+  overflow: auto;
+  background: #fff6f5;
+  border: 1px solid rgba(200, 55, 45, 0.35);
+  border-left: 4px solid var(--bad);
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+}
+
+.error pre {
+  margin: 0;
+  padding: 12px 14px;
+  font: 12px/1.5 ui-monospace, 'SF Mono', Menlo, monospace;
+  white-space: pre-wrap;
+  color: #7a1d16;
+}
+
+.logs {
+  flex: 0 1 auto;
+  min-width: 0;
+  max-width: min(420px, 40vw);
+  max-height: 40vh;
+  overflow: auto;
+  padding: 8px 10px;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  font: 12px/1.5 ui-monospace, 'SF Mono', Menlo, monospace;
+  white-space: pre-wrap;
+}
+
+.logs .log-warn {
+  color: var(--busy);
+}
+
+.logs .log-error {
+  color: var(--bad);
+}
+
+.hint {
+  position: fixed;
+  left: 12px;
+  bottom: 12px;
+  color: var(--muted);
+  font-size: 12px;
+  pointer-events: none;
+}
+
+@media (max-width: 720px) {
+  .file,
+  .hint {
+    display: none;
+  }
+  .logs {
+    position: fixed;
+    left: 12px;
+    right: 12px;
+    bottom: 40px;
+    max-width: none;
+  }
+}