cadcode 0.0.0-stage → 0.2.0

package/client/viewer.js

@@ -0,0 +1,331 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+const DEFAULT_COLOR = '#f2c14e';
+const EDGE_ANGLE = 25;
+
+const canvas = document.getElementById('view');
+const partSelect = document.getElementById('part');
+const statusEl = document.getElementById('status');
+const fileEl = document.getElementById('file');
+const errorEl = document.getElementById('error');
+const errorText = document.getElementById('error-text');
+const logsEl = document.getElementById('logs');
+
+// --- Scene -------------------------------------------------------------------
+
+THREE.Object3D.DEFAULT_UP.set(0, 0, 1); // CAD convention: Z is up
+
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setClearColor(0xeef0f3);
+
+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, canvas);
+controls.enableDamping = true;
+controls.dampingFactor = 0.15;
+controls.screenSpacePanning = true; // shift+drag and right-drag pan in the view plane
+
+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);
+
+function resize() {
+  const { clientWidth: w, clientHeight: h } = canvas;
+  renderer.setSize(w, h, false);
+  camera.aspect = w / h;
+  camera.updateProjectionMatrix();
+}
+window.addEventListener('resize', resize);
+resize();
+
+renderer.setAnimationLoop(() => {
+  controls.update();
+  renderer.render(scene, camera);
+});
+
+// --- Camera persistence ------------------------------------------------------
+// The camera survives model reloads untouched; it is also stored per file so a
+// browser refresh or a restarted server comes back to the same view.
+
+let fileKey = null;
+
+const storage = {
+  get(key) {
+    try {
+      return JSON.parse(localStorage.getItem(key));
+    } catch {
+      return null;
+    }
+  },
+  set(key, value) {
+    try {
+      localStorage.setItem(key, JSON.stringify(value));
+    } catch {
+      // Storage unavailable (private window): the view just isn't remembered.
+    }
+  },
+};
+
+function saveCamera() {
+  if (!fileKey) return;
+  storage.set(`cadcode:camera:${fileKey}`, {
+    position: camera.position.toArray(),
+    target: controls.target.toArray(),
+    zoom: camera.zoom,
+  });
+}
+
+function restoreCamera() {
+  const saved = storage.get(`cadcode:camera:${fileKey}`);
+  if (!saved) return false;
+  camera.position.fromArray(saved.position);
+  controls.target.fromArray(saved.target);
+  camera.zoom = saved.zoom ?? 1;
+  camera.updateProjectionMatrix();
+  controls.update();
+  return true;
+}
+
+let saveTimer = 0;
+controls.addEventListener('change', () => {
+  clearTimeout(saveTimer);
+  saveTimer = setTimeout(saveCamera, 200);
+});
+window.addEventListener('beforeunload', saveCamera);
+
+function modelSphere() {
+  return new THREE.Box3().setFromObject(model).getBoundingSphere(new THREE.Sphere());
+}
+
+function fitView() {
+  const sphere = modelSphere();
+  if (sphere.isEmpty()) return;
+  const distance = (sphere.radius / Math.sin(THREE.MathUtils.degToRad(camera.fov / 2))) * 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();
+  saveCamera();
+}
+
+document.getElementById('fit').addEventListener('click', fitView);
+window.addEventListener('keydown', (event) => {
+  if (event.target instanceof HTMLSelectElement) return;
+  if (event.key === 'f' || event.key === 'F') fitView();
+});
+
+// --- Model -------------------------------------------------------------------
+
+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, 0xb9bec7, 0xd6d9df);
+  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);
+}
+
+/** Decodes a binary model frame: u32 header length, JSON header, then f32 positions and u32 indices per group. */
+function decodeModel(buffer) {
+  const headerLength = new DataView(buffer).getUint32(0, true);
+  const header = JSON.parse(new TextDecoder().decode(new Uint8Array(buffer, 4, headerLength)));
+  let offset = 4 + headerLength;
+  const groups = header.groups.map((g) => {
+    const positions = new Float32Array(buffer, offset, g.vertices * 3);
+    offset += positions.byteLength;
+    const indices = new Uint32Array(buffer, offset, g.indices);
+    offset += indices.byteLength;
+    return { ...g, positions, indices };
+  });
+  return { header, groups };
+}
+
+function showModel({ header, groups }) {
+  const next = new THREE.Group();
+  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));
+    geometry.computeVertexNormals();
+
+    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 edges = new THREE.LineSegments(
+      new THREE.EdgesGeometry(geometry, EDGE_ANGLE),
+      new THREE.LineBasicMaterial({ color: 0x2a2f36, transparent: true, opacity: transparent ? 0.25 : 0.55 }),
+    );
+    next.add(edges);
+  }
+
+  scene.remove(model);
+  disposeGroup(model);
+  model = next;
+  scene.add(model);
+
+  const sphere = modelSphere();
+  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);
+  }
+
+  const triangles = groups.reduce((n, g) => n + g.indices.length / 3, 0);
+  setStatus('ready', `${header.part} · ${triangles.toLocaleString()} tris · ${header.ms} ms`);
+}
+
+// --- UI state ----------------------------------------------------------------
+
+function setStatus(state, text = state) {
+  statusEl.dataset.state = state;
+  statusEl.textContent = text;
+}
+
+function showError(message) {
+  errorText.textContent = message;
+  errorEl.hidden = !message;
+}
+
+function showLogs(logs = []) {
+  logsEl.replaceChildren(
+    ...logs.map(({ level, text }) => {
+      const line = document.createElement('div');
+      line.className = `log-${level}`;
+      line.textContent = text;
+      return line;
+    }),
+  );
+  logsEl.hidden = logs.length === 0;
+}
+
+function showParts(names, current) {
+  partSelect.replaceChildren(...names.map((name) => new Option(name, name, false, name === current)));
+}
+
+// --- Download ----------------------------------------------------------------
+// Fetched rather than navigated to, so a failing program shows its error here
+// instead of replacing the viewer.
+
+const downloadButton = document.getElementById('download');
+
+downloadButton.addEventListener('click', async () => {
+  downloadButton.disabled = true;
+  try {
+    const response = await fetch(`/stl?part=${encodeURIComponent(partSelect.value)}`);
+    if (!response.ok) throw new Error(await response.text());
+    const link = document.createElement('a');
+    link.href = URL.createObjectURL(await response.blob());
+    link.download = response.headers.get('Content-Disposition').match(/filename="(.+)"/)[1];
+    link.click();
+    setTimeout(() => URL.revokeObjectURL(link.href)); // after the browser has started the download
+  } catch (error) {
+    showError(`STL download failed: ${error.message}`);
+  } finally {
+    downloadButton.disabled = false;
+  }
+});
+
+// --- Connection --------------------------------------------------------------
+
+let socket = null;
+let firstModel = true;
+
+function requestPart(name) {
+  if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ type: 'part', name }));
+}
+
+partSelect.addEventListener('change', () => {
+  storage.set(`cadcode:part:${fileKey}`, partSelect.value);
+  requestPart(partSelect.value);
+});
+
+function connect() {
+  socket = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/`);
+  socket.binaryType = 'arraybuffer';
+
+  socket.addEventListener('message', (event) => {
+    if (typeof event.data === 'string') {
+      const message = JSON.parse(event.data);
+      if (message.type === 'status') setStatus(message.status);
+      if (message.type === 'error') {
+        setStatus('error');
+        showError(message.stack && message.stack.includes(message.message) ? message.stack : message.message);
+        showLogs(message.logs);
+      }
+      return;
+    }
+
+    const frame = decodeModel(event.data);
+    const { header } = frame;
+    if (fileKey !== header.file) {
+      fileKey = header.file;
+      const slash = header.file.lastIndexOf('/') + 1;
+      fileEl.querySelector('.dir').textContent = header.file.slice(0, slash);
+      fileEl.querySelector('.name').textContent = header.file.slice(slash);
+      fileEl.title = header.file;
+      document.title = `${header.file} · cadcode`;
+    }
+    showParts(header.partNames, header.part);
+    showError('');
+    showLogs(header.logs);
+    showModel(frame);
+
+    if (firstModel) {
+      firstModel = false;
+      if (!restoreCamera()) fitView();
+      const preferred = storage.get(`cadcode:part:${fileKey}`);
+      if (preferred && preferred !== header.part && header.partNames.includes(preferred)) requestPart(preferred);
+    }
+  });
+
+  socket.addEventListener('close', () => {
+    setStatus('disconnected');
+    setTimeout(connect, 1000);
+  });
+}
+
+connect();

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "cadcode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "keywords": [
+    "cad",
+    "csg",
+    "3d-printing",
+    "stl",
+    "manifold"
+  ],
+  "license": "MIT",
+  "description": "Code-first CAD: write models in JavaScript, preview live in the browser, export STL and PNG.",
+  "dependencies": {
+    "esbuild": "^0.28.2",
+    "manifold-3d": "^3.5.4",
+    "three": "^0.187.0",
+    "ws": "^8.22.1"
+  },
+  "type": "module",
+  "bin": {
+    "cadcode": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/lib/index.js"
+  },
+  "files": [
+    "src",
+    "client"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/cli.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { bundleProgram, evaluateProgram, parseOverrides } from './core/program.js';
+
+process.setSourceMapsEnabled(true);
+
+const USAGE = `cadcode — code-first CAD
+
+Usage:
+  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
+
+Options:
+  -p, --part <name>     Part to use (default: the first one)
+  -a, --all             stl/png: export every part
+  -s, --set <k=v>       Override a parameter (repeatable); values are JSON or strings
+  -o, --out <path>      Output file, or directory with --all
+      --view <name>     png: iso, iso-back, front, back, left, right, top, bottom, sheet (default: iso)
+      --size <WxH>      png: image size (default: 800x600)
+      --port <n>        dev: port (default: 5173)
+      --host <addr>     dev: address to bind (default: 127.0.0.1)
+      --open            dev: open the browser
+`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    part: { type: 'string', short: 'p' },
+    all: { type: 'boolean', short: 'a' },
+    set: { type: 'string', short: 's', multiple: true },
+    out: { type: 'string', short: 'o' },
+    view: { type: 'string', default: 'iso' },
+    size: { type: 'string', default: '800x600' },
+    port: { type: 'string', default: '5173' },
+    host: { type: 'string', default: '127.0.0.1' },
+    open: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+  },
+});
+
+const [command, file] = positionals;
+
+async function main() {
+  if (values.help || !command) return void process.stdout.write(USAGE);
+  if (!file) throw new Error(`Missing <file>. Try: cadcode ${command} model.js`);
+  if (!fs.existsSync(file)) throw new Error(`No such file: ${file}`);
+  const overrides = parseOverrides(values.set);
+
+  if (command === 'dev') {
+    const { startDevServer } = await import('./dev/server.js');
+    return startDevServer({ file, port: Number(values.port), host: values.host, part: values.part, overrides, open: values.open });
+  }
+
+  const bundle = await bundleProgram(file);
+  const first = await evaluateProgram(bundle, { part: values.part, overrides });
+
+  if (command === 'parts') return void console.log(first.partNames.join('\n'));
+  if (command !== 'stl' && command !== 'png') throw new Error(`Unknown command "${command}"\n\n${USAGE}`);
+
+  const ext = command;
+  const base = path.basename(file).replace(/\.[^.]+$/, '');
+  const parts = values.all ? first.partNames : [first.part];
+  for (const part of parts) {
+    const result = part === first.part ? first : await evaluateProgram(bundle, { part, overrides });
+    const name = parts.length > 1 || first.partNames.length > 1 ? `${base}-${part}.${ext}` : `${base}.${ext}`;
+    const out = values.all ? path.join(values.out ?? '.', name) : (values.out ?? name);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+
+    const started = performance.now();
+    if (ext === 'stl') {
+      const { toSTL } = await import('./export/stl.js');
+      fs.writeFileSync(out, toSTL(result.solids));
+    } else {
+      const { toPNG } = await import('./export/png.js');
+      const [width, height] = values.size.split('x').map(Number);
+      if (!width || !height) throw new Error(`--size must look like 800x600, got "${values.size}"`);
+      fs.writeFileSync(out, toPNG(result.solids, { width, height, view: values.view }));
+    }
+    console.log(`${part} → ${out} (${Math.round(performance.now() - started)} ms)`);
+  }
+}
+
+const OWN_SOURCES = path.dirname(new URL(import.meta.url).pathname);
+
+main().catch((error) => {
+  console.error(`cadcode: ${error.message}`);
+  // Point at the user's code: the first stack frame outside cadcode itself.
+  const where = error.stack?.split('\n').find((line) => line.trim().startsWith('at ') && !line.includes(OWN_SOURCES));
+  if (where) console.error(`  ${where.trim()}`);
+  if (process.env.CADCODE_DEBUG) console.error(error.stack);
+  process.exit(1);
+});

package/src/core/mesh.js

@@ -0,0 +1,69 @@
+import { colorOfId, union } from '../lib/shapes.js';
+
+/**
+ * @typedef {object} MeshGroup
+ * @property {number} body index of the solid this group came from
+ * @property {[number, number, number, number] | null} color RGBA in 0..1, null when uncolored
+ * @property {Float32Array} positions xyz per vertex
+ * @property {Uint32Array} indices three per triangle
+ */
+
+/**
+ * Splits each solid's mesh into groups of one color each, for rendering.
+ * @param {import('../lib/shapes.js').Solid[]} solids
+ * @returns {MeshGroup[]}
+ */
+export function meshGroups(solids) {
+  const groups = [];
+  solids.forEach((solid, body) => {
+    const mesh = solid.manifold.getMesh();
+    const { numProp, vertProperties, triVerts, runIndex, runOriginalID } = mesh;
+
+    /** @type {Map<string, { color: any, tris: number[] }>} */
+    const byColor = new Map();
+    for (let run = 0; run < runOriginalID.length; run++) {
+      const color = colorOfId(runOriginalID[run]) ?? null;
+      const key = color ? color.join(',') : '';
+      if (!byColor.has(key)) byColor.set(key, { color, tris: [] });
+      const tris = byColor.get(key).tris;
+      for (let i = runIndex[run]; i < runIndex[run + 1]; i++) tris.push(triVerts[i]);
+    }
+
+    for (const { color, tris } of byColor.values()) {
+      const remap = new Map();
+      const positions = [];
+      const indices = new Uint32Array(tris.length);
+      tris.forEach((v, i) => {
+        let n = remap.get(v);
+        if (n === undefined) {
+          n = remap.size;
+          remap.set(v, n);
+          positions.push(vertProperties[v * numProp], vertProperties[v * numProp + 1], vertProperties[v * numProp + 2]);
+        }
+        indices[i] = n;
+      });
+      groups.push({ body, color, positions: new Float32Array(positions), indices });
+    }
+  });
+  return groups;
+}
+
+/** Bounding box over all groups. */
+export function groupBounds(groups) {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (const { positions } of groups) {
+    for (let i = 0; i < positions.length; i += 3) {
+      for (let k = 0; k < 3; k++) {
+        min[k] = Math.min(min[k], positions[i + k]);
+        max[k] = Math.max(max[k], positions[i + k]);
+      }
+    }
+  }
+  return { min, max };
+}
+
+/** The solids of a part merged into one, as written to STL. */
+export function mergedSolid(solids) {
+  return union(solids);
+}

package/src/core/program.js

@@ -0,0 +1,118 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as esbuild from 'esbuild';
+import { Solid, Shape2 } from '../lib/index.js';
+
+const LIB_URL = pathToFileURL(fileURLToPath(new URL('../lib/index.js', import.meta.url))).href;
+
+// User programs import 'cadcode'. It must resolve to this very copy of the
+// library: colors are tracked in module state, and the program's solids are
+// read back by our exporters.
+const cadcodePlugin = {
+  name: 'cadcode',
+  setup(build) {
+    build.onResolve({ filter: /^cadcode$/ }, () => ({ path: LIB_URL, external: true }));
+  },
+};
+
+/**
+ * esbuild options that bundle a user program (and its local imports) into one ESM file.
+ * Bundling lets programs import their own helper files and npm packages, and
+ * gives the dev server the list of files to watch.
+ */
+export function bundleOptions(entry) {
+  // Real paths: on macOS the temp dir is behind a symlink, and source maps would
+  // otherwise resolve the program's path against the wrong base.
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cadcode-')));
+  return {
+    entryPoints: [fs.realpathSync(entry)],
+    outfile: path.join(dir, 'program.mjs'),
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    sourcemap: 'inline',
+    metafile: true,
+    logLevel: 'silent',
+    plugins: [cadcodePlugin],
+  };
+}
+
+/** Bundles a program once and returns the path of the bundle. */
+export async function bundleProgram(entry) {
+  const options = bundleOptions(entry);
+  await esbuild.build(options);
+  return options.outfile;
+}
+
+function flattenModel(model, partName) {
+  const solids = [];
+  const walk = (item) => {
+    if (Array.isArray(item)) item.forEach(walk);
+    else if (item instanceof Solid) solids.push(item);
+    else if (item instanceof Shape2) throw new Error(`Part "${partName}" contains a 2D shape; extrude it to make a solid`);
+    else if (item) throw new Error(`Part "${partName}" contains ${typeof item} ${String(item)}, not a solid`);
+  };
+  walk(model);
+  return solids;
+}
+
+const isModel = (value) => value instanceof Solid || value instanceof Shape2 || Array.isArray(value);
+
+/**
+ * Loads a bundled program and evaluates one part.
+ *
+ * A program `export default`s either a model (a solid or an array of solids), or an
+ * object of named parts whose values are models or functions returning models, or a
+ * function of `params` returning either. `export const params = {...}` declares the
+ * parameters that `overrides` may change.
+ *
+ * @param {string} bundlePath
+ * `fallbackToFirst` shows the first part instead of failing when `part` no longer
+ * exists — the dev server uses it so renaming a part doesn't blank the preview.
+ *
+ * @param {string} bundlePath
+ * @param {{ part?: string, overrides?: Record<string, unknown>, fallbackToFirst?: boolean }} [options]
+ */
+export async function evaluateProgram(bundlePath, { part, overrides = {}, fallbackToFirst = false } = {}) {
+  const mod = await import(`${pathToFileURL(bundlePath).href}?t=${Date.now()}`);
+  if (mod.default === undefined) throw new Error('The program has no `export default`');
+
+  const declared = mod.params ?? {};
+  for (const key of Object.keys(overrides)) {
+    if (!(key in declared)) throw new Error(`Unknown parameter "${key}". Declared: ${Object.keys(declared).join(', ') || 'none'}`);
+  }
+  const params = { ...declared, ...overrides };
+
+  const value = typeof mod.default === 'function' ? await mod.default(params) : mod.default;
+  const parts = isModel(value) ? { default: value } : value;
+  if (!parts || typeof parts !== 'object') throw new Error('The default export must be a model, an object of parts, or a function returning one');
+
+  const partNames = Object.keys(parts);
+  if (partNames.length === 0) throw new Error('The program defines no parts');
+  const name = part && partNames.includes(part) ? part : partNames[0];
+  if (part && part !== name && !fallbackToFirst) throw new Error(`No part "${part}". Parts: ${partNames.join(', ')}`);
+
+  const entry = parts[name];
+  const model = typeof entry === 'function' ? await entry(params) : entry;
+  return { partNames, part: name, params, solids: flattenModel(model, name) };
+}
+
+/** Parses `key=value` overrides; values are JSON when they parse, strings otherwise. */
+export function parseOverrides(pairs = []) {
+  const out = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf('=');
+    if (eq < 1) throw new Error(`Expected key=value, got "${pair}"`);
+    const raw = pair.slice(eq + 1);
+    let value;
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      value = raw;
+    }
+    out[pair.slice(0, eq)] = value;
+  }
+  return out;
+}