cadcode 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandr Ivashkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,20 +1,30 @@
 # cadcode
 
-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.
+CAD for people who write code. If you have a 3D printer and know JavaScript, you don't have to learn a CAD program to make a bracket: describe the part in code, watch it update in the browser on every save, and send the STL to your slicer.
 
-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.
+Try it in the browser: [the playground](https://jwo1f.github.io/cadcode/playground.html).
+
+- **Nothing new to learn.** Variables, loops and functions instead of menus and modes.
+- **Models live in git.** A model is a text file: diff it, branch it, revert the change that broke the fit.
+- **Tweak, don't redraw.** Sizes are `params`; reprint a variant with `--set width=80`.
+- **Ready for the slicer.** Geometry runs on [manifold](https://github.com/elalish/manifold), the boolean engine recent OpenSCAD uses, so solids always come out watertight.
+
+Coming from OpenSCAD? The API keeps its ideas (cube, cylinder, hull, difference, `$fn`), so models port line by line.
 
 ```js
-import { cube, cylinder, difference } from 'cadcode';
+import { cube } from 'cadcode';
+
+export const params = { width: 60, depth: 40, height: 25, wall: 2 };
 
-export default difference(
-  cube([20, 20, 5], { center: true }),
-  cylinder({ d: 6, h: 10, center: true }),
-);
+export default (p) =>
+  cube([p.width, p.depth, p.height]).subtract(
+    cube([p.width - 2 * p.wall, p.depth - 2 * p.wall, p.height]).translate([p.wall, p.wall, p.wall]),
+  );
 ```
 
 ```bash
-npx cadcode dev plate.js
+npx cadcode dev box.js
+npx cadcode stl box.js --set width=80
 ```
 
 ## Install
@@ -60,8 +70,10 @@ cadcode png case.js --part assembly --view sheet --size 1600x1200
 - **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
-- **Download the part as STL**: the STL button. It is the same file `cadcode stl` writes.
+- **Wireframe**: the Wire button shows only the triangle edges, Solid+Wire draws them over the solid. Press the lit button again to go back to the plain solid.
+- **Switch parts**: the Part menu, shown when the program has more than one part
+- **Download the part as STL**: the Download STL button. It is the same file `cadcode stl` writes.
+- **Save the view as PNG**: the PNG button. It takes the camera as it is, without the grid and axes.
 
 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.
 

package/client/favicon.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <!-- The README's first model: a cube with a hole through it, in isometric view. -->
+  <defs>
+    <clipPath id="hole">
+      <ellipse cx="32" cy="19" rx="9.5" ry="5.5" />
+    </clipPath>
+  </defs>
+  <g stroke="#1d2228" stroke-width="2.5" stroke-linejoin="round">
+    <path d="M32 6 55 19 32 32 9 19Z" fill="#f6cf6a" />
+    <path d="M9 19 32 32V58L9 45Z" fill="#d9a321" />
+    <path d="M55 19 32 32V58L55 45Z" fill="#b07f17" />
+  </g>
+  <!-- The hole: its far wall catches light, the near side is in shadow. -->
+  <ellipse cx="32" cy="19" rx="9.5" ry="5.5" fill="#8a6412" />
+  <ellipse cx="32" cy="23" rx="9.5" ry="5.5" fill="#1d2228" clip-path="url(#hole)" />
+  <ellipse cx="32" cy="19" rx="9.5" ry="5.5" fill="none" stroke="#1d2228" stroke-width="2" />
+</svg>

package/client/index.html

@@ -4,50 +4,63 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>cadcode</title>
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" />
     <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>
+    <!-- The whole page is the stage; everything else floats on it, in the corners. -->
+    <main id="stage" class="stage" data-empty data-busy>
+      <canvas id="view"></canvas>
+      <div class="progress" aria-hidden="true"></div>
+      <p id="empty" class="empty">Waiting for the model…</p>
 
-    <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>
-        <button id="download" type="button" title="Download the part as STL">
-          STL
+      <header class="corner top-left">
+        <span class="brand"><img src="/favicon.svg" alt="" width="26" height="26" />cadcode</span>
+        <span id="file" class="pill file" hidden><span class="dir"></span><span class="name"></span></span>
+        <button id="part-open" class="pill field" type="button" popovertarget="part-menu" aria-haspopup="menu" hidden>
+          <span>Part</span>
+          <strong id="part-title"></strong>
+          <svg viewBox="0 0 10 6" width="10" height="6" aria-hidden="true"><path d="M1 1l4 4 4-4" fill="none" stroke="currentColor" stroke-width="1.5" /></svg>
         </button>
       </header>
 
-      <section id="logs" class="logs" hidden></section>
-    </div>
+      <nav class="corner top-right" aria-label="Export">
+        <button id="png" class="pill" type="button" title="Save the current view as PNG">PNG</button>
+        <button id="download" class="pill primary" type="button" title="Download the part as STL"><span class="wide">Download </span>STL</button>
+      </nav>
+
+      <section id="logs" class="card logs" aria-label="Program output" hidden></section>
 
-    <section id="error" class="error" hidden>
-      <pre id="error-text"></pre>
-    </section>
+      <footer class="corner bottom-left">
+        <section id="error" class="card error" hidden>
+          <pre id="error-text"></pre>
+        </section>
+        <div class="readout" aria-live="polite">
+          <p id="readout-size" class="size">&nbsp;</p>
+          <p class="meta">
+            <span id="status" class="status" data-state="connecting">Connecting</span>
+            <span id="readout-mesh"></span>
+            <span id="readout-time"></span>
+          </p>
+        </div>
+        <p class="hint">Drag to rotate, shift-drag or right-drag to pan, scroll to zoom, F to fit</p>
+      </footer>
+
+      <div class="corner bottom-right">
+        <div class="tools" role="group" aria-label="Display">
+          <button class="pill" type="button" data-display="wire" aria-pressed="false" title="Show only the triangle edges">Wire</button>
+          <button class="pill" type="button" data-display="both" aria-pressed="false" title="Show the solid with its triangle edges">Solid+Wire</button>
+        </div>
+        <button id="fit" class="pill round" type="button" aria-label="Fit the model to the view" title="Fit the model to the view (F)">
+          <svg viewBox="0 0 20 20" width="18" height="18" aria-hidden="true"><path d="M3 7V3h4M13 3h4v4M17 13v4h-4M7 17H3v-4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" /></svg>
+        </button>
+      </div>
+    </main>
 
-    <footer class="hint">
-      drag: rotate · shift+drag or right-drag: pan · wheel: zoom · F: fit
-    </footer>
+    <div id="part-menu" class="menu" popover role="menu" aria-label="Parts"></div>
 
     <script type="module" src="/viewer.js"></script>
   </body>

package/client/render-worker.js

@@ -0,0 +1,333 @@
+// The three.js view, run in a worker on an OffscreenCanvas so that building a large
+// mesh never stalls the page: renderer, camera and controls, the grid, and turning
+// mesh groups into meshes. client/scene.js is the page's side: it hands over the
+// canvas, forwards input and size, and sends commands; see it for the messages.
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const DEFAULT_COLOR = '#f2c14e';
+const EDGE_ANGLE = 25;
+
+THREE.Object3D.DEFAULT_UP.set(0, 0, 1); // CAD convention: Z is up
+
+/**
+ * Stands in for the canvas element, which OrbitControls listens to and measures.
+ * The page forwards its events here; pointermove and pointerup go to the
+ * "document", where OrbitControls listens for them during a drag.
+ */
+class ElementProxy extends EventTarget {
+  ownerDocument = new EventTarget();
+  clientWidth = 1;
+  clientHeight = 1;
+  left = 0;
+  top = 0;
+  // OrbitControls sets the cursor while dragging; the page applies it to the real canvas.
+  style = new Proxy(
+    {},
+    {
+      set(target, key, value) {
+        if (key === 'cursor' && target.cursor !== value) self.postMessage({ type: 'cursor', value });
+        target[key] = value;
+        return true;
+      },
+    },
+  );
+
+  getBoundingClientRect() {
+    const { left, top, clientWidth: width, clientHeight: height } = this;
+    return { left, top, width, height, x: left, y: top, right: left + width, bottom: top + height };
+  }
+
+  getRootNode() {
+    return this.ownerDocument;
+  }
+
+  setPointerCapture() {} // the page captures the pointer on the real canvas
+  releasePointerCapture() {}
+  focus() {}
+}
+
+/** Re-creates a forwarded event; the page has already called preventDefault where it matters. */
+function dispatch(target, data) {
+  const event = new Event(data.type, { cancelable: true });
+  for (const [key, value] of Object.entries(data)) if (key !== 'type') Object.defineProperty(event, key, { value });
+  target.dispatchEvent(event);
+}
+
+let view = null;
+const queue = []; // messages that arrived before init
+
+self.onmessage = ({ data }) => {
+  if (data.type === 'init') {
+    view = createView(data);
+    for (const message of queue.splice(0)) handle(message);
+    return;
+  }
+  if (view) handle(data);
+  else queue.push(data);
+};
+
+async function handle(message) {
+  switch (message.type) {
+    case 'resize':
+      return view.resize(message);
+    case 'event':
+      return dispatch(message.target === 'document' ? view.element.ownerDocument : view.element, message.event);
+    case 'fit':
+      return view.fitView();
+    case 'inset':
+      return view.setInset(message.inset);
+    case 'set-camera':
+      return view.setCamera(message.camera);
+    case 'display':
+      return view.setDisplay(message.mode);
+  }
+  // The rest answer the page.
+  try {
+    const value = message.type === 'show' ? view.showModel(message.groups) : await view.snapshotPNG();
+    self.postMessage({ type: 'reply', id: message.id, value });
+  } catch (error) {
+    self.postMessage({ type: 'reply', id: message.id, error: error.message });
+  }
+}
+
+function createView({ canvas, colors, ...size }) {
+  // A null background leaves the canvas transparent, for the page to paint behind it.
+  const { background = 0xeef0f3, gridMajor = 0xb9bec7, gridMinor = 0xd6d9df, edges = 0x2a2f36 } = colors ?? {};
+  const element = new ElementProxy();
+
+  const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: background === null });
+  if (background === null) renderer.setClearColor(0x000000, 0);
+  else renderer.setClearColor(background);
+
+  const scene = new THREE.Scene();
+  const camera = new THREE.PerspectiveCamera(40, 1, 0.1, 10000);
+  camera.up.set(0, 0, 1);
+  camera.position.set(120, -160, 110);
+  scene.add(camera);
+
+  scene.add(new THREE.HemisphereLight(0xffffff, 0x8a8f99, 1.6));
+  const keyLight = new THREE.DirectionalLight(0xffffff, 1.5);
+  keyLight.position.set(-0.4, 0.8, 1); // relative to the camera, so shading follows the view
+  camera.add(keyLight);
+
+  const controls = new OrbitControls(camera, element);
+  controls.enableDamping = true;
+  controls.dampingFactor = 0.15;
+  controls.screenSpacePanning = true; // shift+drag and right-drag pan in the view plane
+
+  // The page keeps the camera across reloads; it hears of every move.
+  controls.addEventListener('change', () => self.postMessage({ type: 'camera', camera: getCamera() }));
+
+  const grid = new THREE.Group();
+  scene.add(grid);
+  const axes = new THREE.AxesHelper(10);
+  scene.add(axes);
+
+  let model = new THREE.Group();
+  scene.add(model);
+
+  // What the model is drawn as: 'solid' (faces and feature edges), 'wire' (every
+  // triangle edge, no faces) or 'both' (the solid with every triangle edge over it).
+  let display = 'solid';
+  let shapes = []; // per mesh group: { mesh, outline, wire, transparent }; wire is built on first need
+
+  // The page measures the canvas, which its CSS may resize at any time.
+  function resize({ width, height, left, top, dpr }) {
+    Object.assign(element, { clientWidth: width, clientHeight: height, left, top });
+    if (width === 0 || height === 0) return;
+    renderer.setPixelRatio(dpr);
+    renderer.setSize(width, height, false);
+    applyProjection();
+  }
+
+  // The part of the canvas the page covers with a panel, on the right or the bottom.
+  // The view centres on what is left, so the model is never framed under the panel.
+  let inset = { right: 0, bottom: 0 };
+
+  function setInset(next) {
+    inset = { right: next.right ?? 0, bottom: next.bottom ?? 0 };
+    applyProjection();
+  }
+
+  function applyProjection() {
+    const { clientWidth: width, clientHeight: height } = element;
+    camera.aspect = width / height;
+    if (inset.right || inset.bottom) camera.setViewOffset(width, height, inset.right / 2, inset.bottom / 2, width, height);
+    else camera.clearViewOffset();
+    camera.updateProjectionMatrix();
+  }
+
+  resize(size);
+
+  let paused = false; // while a snapshot is being encoded
+  renderer.setAnimationLoop(() => {
+    if (paused) return;
+    controls.update();
+    renderer.render(scene, camera);
+  });
+
+  function modelSphere() {
+    return new THREE.Box3().setFromObject(model).getBoundingSphere(new THREE.Sphere());
+  }
+
+  function fitView() {
+    const sphere = modelSphere();
+    if (sphere.isEmpty()) return;
+    // Fit the sphere in the uncovered part of the canvas, by its narrower side.
+    const { clientWidth: width, clientHeight: height } = element;
+    const tanHalf = Math.tan(THREE.MathUtils.degToRad(camera.fov / 2));
+    const visible = Math.min(Math.max(height - inset.bottom, 1), Math.max(width - inset.right, 1)) / height;
+    const distance = (sphere.radius / Math.sin(Math.atan(tanHalf * visible))) * 1.15;
+    const direction = new THREE.Vector3(1, -1.3, 0.9).normalize();
+    controls.target.copy(sphere.center);
+    camera.position.copy(sphere.center).addScaledVector(direction, distance);
+    camera.zoom = 1;
+    camera.updateProjectionMatrix();
+    controls.update();
+  }
+
+  function getCamera() {
+    return { position: camera.position.toArray(), target: controls.target.toArray(), zoom: camera.zoom };
+  }
+
+  function setCamera({ position, target, zoom }) {
+    camera.position.fromArray(position);
+    controls.target.fromArray(target);
+    camera.zoom = zoom ?? 1;
+    camera.updateProjectionMatrix();
+    controls.update();
+  }
+
+  function setDisplay(mode) {
+    display = mode;
+    applyDisplay();
+  }
+
+  function applyDisplay() {
+    const solid = display !== 'wire';
+    const wired = display !== 'solid';
+    for (const shape of shapes) {
+      shape.mesh.visible = shape.outline.visible = solid;
+      if (wired && !shape.wire) {
+        shape.wire = new THREE.LineSegments(
+          new THREE.WireframeGeometry(shape.mesh.geometry),
+          new THREE.LineBasicMaterial({ color: edges, transparent: true }),
+        );
+        model.add(shape.wire);
+      }
+      if (!shape.wire) continue;
+      shape.wire.visible = wired;
+      // Over faces the lines only hint at the triangles; alone they are the picture.
+      shape.wire.material.opacity = solid ? (shape.transparent ? 0.15 : 0.3) : 0.7;
+    }
+  }
+
+  function disposeGroup(group) {
+    group.traverse((object) => {
+      object.geometry?.dispose();
+      object.material?.dispose();
+    });
+  }
+
+  function buildGrid(sphere) {
+    disposeGroup(grid);
+    grid.clear();
+    const step = 10 ** Math.floor(Math.log10(Math.max(sphere.radius, 1)));
+    const size = Math.ceil((sphere.radius * 3) / step) * step;
+    const helper = new THREE.GridHelper(size, size / step, gridMajor, gridMinor);
+    helper.rotation.x = Math.PI / 2;
+    helper.position.set(Math.round(sphere.center.x / step) * step, Math.round(sphere.center.y / step) * step, 0);
+    grid.add(helper);
+    axes.scale.setScalar(step / 10);
+  }
+
+  /**
+   * Replaces the model with mesh groups ({ color, positions, indices }) and returns
+   * its triangle count and bounding box size ([x, y, z], or null when empty).
+   * The camera is left where it is.
+   */
+  function showModel(groups) {
+    const next = new THREE.Group();
+    const nextShapes = [];
+    for (const g of groups) {
+      const geometry = new THREE.BufferGeometry();
+      geometry.setAttribute('position', new THREE.BufferAttribute(g.positions, 3));
+      geometry.setIndex(new THREE.BufferAttribute(g.indices, 1));
+      // No vertex normals: flat shading derives them per fragment.
+
+      const [r, gr, b, a] = g.color ?? [...new THREE.Color(DEFAULT_COLOR).toArray(), 1];
+      const transparent = a < 0.999;
+      const material = new THREE.MeshStandardMaterial({
+        color: new THREE.Color(r, gr, b),
+        roughness: 0.65,
+        metalness: 0.05,
+        flatShading: true,
+        transparent,
+        opacity: a,
+        depthWrite: !transparent,
+        side: transparent ? THREE.DoubleSide : THREE.FrontSide,
+        polygonOffset: true,
+        polygonOffsetFactor: 1,
+        polygonOffsetUnits: 1,
+      });
+      const mesh = new THREE.Mesh(geometry, material);
+      mesh.renderOrder = transparent ? 1 : 0;
+      next.add(mesh);
+
+      const outline = new THREE.LineSegments(
+        new THREE.EdgesGeometry(geometry, EDGE_ANGLE),
+        new THREE.LineBasicMaterial({ color: edges, transparent: true, opacity: transparent ? 0.25 : 0.55 }),
+      );
+      next.add(outline);
+      nextShapes.push({ mesh, outline, wire: null, transparent });
+    }
+
+    scene.remove(model);
+    disposeGroup(model);
+    model = next;
+    shapes = nextShapes;
+    scene.add(model);
+    applyDisplay();
+
+    const box = new THREE.Box3().setFromObject(model);
+    const sphere = box.getBoundingSphere(new THREE.Sphere());
+    if (!sphere.isEmpty()) {
+      camera.near = Math.max(sphere.radius / 1000, 0.01);
+      camera.far = sphere.radius * 200 + camera.position.distanceTo(sphere.center);
+      camera.updateProjectionMatrix();
+      buildGrid(sphere);
+    }
+
+    return {
+      triangles: groups.reduce((n, g) => n + g.indices.length / 3, 0),
+      size: box.isEmpty() ? null : box.getSize(new THREE.Vector3()).toArray(),
+    };
+  }
+
+  /**
+   * The current view as a PNG, without the grid and axes, cut to the part of the
+   * canvas no panel covers. The loop is paused while the frame is encoded, so no
+   * frame with the grid replaces it in the meantime.
+   */
+  async function snapshotPNG() {
+    paused = true;
+    grid.visible = axes.visible = false;
+    try {
+      renderer.render(scene, camera);
+      if (!inset.right && !inset.bottom) return await canvas.convertToBlob({ type: 'image/png' });
+      // Copied in the same task as the render, before the drawing buffer is cleared.
+      const dpr = renderer.getPixelRatio();
+      const width = Math.max(1, canvas.width - Math.round(inset.right * dpr));
+      const height = Math.max(1, canvas.height - Math.round(inset.bottom * dpr));
+      const visible = new OffscreenCanvas(width, height);
+      visible.getContext('2d').drawImage(canvas, 0, 0, width, height, 0, 0, width, height);
+      return await visible.convertToBlob({ type: 'image/png' });
+    } finally {
+      grid.visible = axes.visible = true;
+      paused = false;
+    }
+  }
+
+  return { element, resize, setInset, fitView, setCamera, setDisplay, showModel, snapshotPNG };
+}