@rulecad/cad 0.0.0-stage → 0.1.0

package/lib/assembly.mjs

@@ -0,0 +1,308 @@
+// Assemblies: objects placed together, in projects/<project>/assemblies/<name>.json.
+//   kind "fit":   to check how parts go together (references allowed: the switch a keycap fits on). Supports are
+//                 left out: they're removed before parts go together.
+//   kind "plate": a print plate, everything laid out on the bed and exported as one 3MF
+// {
+//   "title": "Keycap on a switch", "kind": "fit", "uses": ["mx"],
+//   "requires": { "keycap": "^0.2.0" },                      versions each object must be (^ same major, ~ same minor)
+//   "items": [ { "id": "switch", "object": "mx-switch" },
+//              { "id": "cap", "object": "keycap", "at": [0, 0, "switch.housing_top - cap.lift"], "rotate": [0, 0, 90] } ],
+//   "fits": [ { "a": "cap.cap", "b": "switch.stem", "min": 0, "max": "x1c.fit", "note": "slot over the stem" } ]
+// }
+// Positions are expressions over rules (mx.pitch) and items' variables (cap.lift); rotate is degrees about x, y, z,
+// applied before at (a repeated item turns as a whole, its copies with it). An item can pin a release: "object": "keycap@0.2.1". fits measure the closest gap between two
+// items or item.parts; a negative min allows a press fit to overlap.
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { evaluate, loadRuleSet } from './rules.mjs';
+import { paths, printerOf } from './workspace.mjs';
+import { locate, build, readObject, jscad } from './design.mjs';
+import { materialise } from './versions.mjs';
+import { satisfies } from '@rulecad/versions';
+import { bounds } from '@rulecad/printcheck';
+import { closest } from '@rulecad/fit';
+import { keys as keyCentres, readLayout, hasLayout } from './layout.mjs';
+
+export const assemblyPath = (ref) => { const [project, name] = String(ref).split('/'); return path.join(paths.project(project || ''), 'assemblies', `${name || ''}.json`); };
+export const isAssembly = (ref) => String(ref).includes('/') && fs.existsSync(assemblyPath(ref.split('@')[0]));
+
+export { satisfies }; // from @rulecad/versions
+
+// buildAssembly('keyboard/keycap-on-switch') -> { a, project, name, items, parts, objects, fits, requires, values, num }
+//   parts: [{ name: 'cap.cap', item, leaf, role, label, geometry, polygons, triangles, shape, m }], placed. item: the
+//   top-level item it belongs to; leaf: the object instance (key-0-0.cap), for overlap checks inside components too;
+//   shape: which built object part it is (the same for every copy), with its faces unmoved in local and localTriangles,
+//   and m its placement (a JSCAD mat4), so repeated shapes can be sent once and placed (shapes()).
+//   objects: every object instance, nested ones included; fits and requires: this assembly's and its components'.
+// An item is an object ("object": "keycap") or another assembly ("assembly": "keycap-on-switch"), placed by at and
+// rotate. "repeat": { "x": { "count": "plate.cols", "step": "mx.pitch" }, "y": { … } } makes a grid of copies, with
+// ids like key-0-2 (column, row) and at as the first copy's place.
+// "repeat": { "layout": "plate/staggered-54", "step": "mx.pitch", "width": "cap.units" } places a copy at each key of
+// an object's layout (layouts in plate.json), centred on at, with ids like key-0-11 (row, key; row 0 at the back).
+// width names a variable set to each key's width in units: in a component, <item>.<variable>. "rows": { "cap.row":
+// ["R1", "R2", …] } sets a variable to one value per row, and "each": { "cap.profile": "oem" } one value for every copy.
+// With a layout file ("layout": "staggered", in projects/<project>/layouts/), "per": { "cap.legend": "legend",
+// "cap.row": "row" } sets inputs from each key's own properties: the layout says what each key is.
+// "place": false builds an item only for its values (what other items' from and positions read): nothing of it is placed,
+// checked or printed.
+// An object item can be a variant: "object": "keycap:oem-r3" (or "variant": "oem-r3"), and pin a release: "keycap@0.4.0".
+// overrides: { itemId: { variable: value } }, set on this assembly's items by the assembly that uses it.
+// opts: { mirror: true } builds each object with its mirror settings (cad show).
+export async function buildAssembly(ref, stack = [], overrides = {}, opts = {}) {
+  const [project, name] = ref.split('/');
+  if (stack.includes(ref)) throw new Error(`assembly ${ref} contains itself (${[...stack, ref].join(' → ')})`);
+  const a = JSON.parse(fs.readFileSync(assemblyPath(ref), 'utf8'));
+  const printer = printerOf(project);
+  if (a.kind === 'plate' && !(a.uses || []).includes(printer)) a.uses = [...(a.uses || []), printer]; // a plate is checked as a print
+  const values = Object.fromEntries((a.uses || []).map((u) => { const s = loadRuleSet(u); return [u, Object.fromEntries(Object.entries(s.rules).map(([k, r]) => [k, r.value]))]; }));
+
+  // Names in positions: rule sets (mx.pitch), items' variables (cap.lift), or into components (key-0-0.cap.lift).
+  // Rule values may still be expressions (rules referring to rules): resolved on demand.
+  const seen = new Set(), ids = [];
+  const lookup = (n) => {
+    const path = n.split('.');
+    if ((a.uses || []).includes(path[0])) seen.add(n);
+    if (!(path[0] in values)) throw new Error(`"${n}": no item or rule set "${path[0]}" (items: ${ids.join(', ') || 'none yet'}; uses: ${(a.uses || []).join(', ') || 'none'})`);
+    let v = values;
+    for (const k of path) v = v?.[k];
+    if (typeof v === 'string') v = evaluate(v, (k) => lookup(k.includes('.') ? k : `${path.slice(0, -1).join('.')}.${k}`));
+    if (typeof v !== 'number') throw new Error(`"${n}" isn't a number`);
+    return v;
+  };
+  const num = (x) => evaluate(x, lookup);
+  const { translate, rotate, transform } = jscad.transforms, deg = Math.PI / 180;
+
+  const items = [], parts = [], objects = [], fits = [], requires = [];
+  for (const [k, r] of Object.entries(a.requires || {})) requires.push({ object: k, range: r, from: ref });
+  const built = new Map(); // each object or component is built once per set of values, however many copies are placed
+  const source = async (it, extra) => {
+    // from: inputs worked out from items built before this one ({ "usb_y": "board.pcb.pico_y" }): numbers, in this
+    // assembly's names, so a part can take a value only another part knows once it's built
+    const from = Object.fromEntries(Object.entries(it.from || {}).map(([k, x]) => [k, num(x)]));
+    const set = { ...(it.set || {}), ...from, ...(overrides[it.id] || {}), ...(it.assembly ? {} : extra) };
+    // Built for the mirror, an object's mirror settings win (no legends), so copies that differ only there are one shape
+    if (opts.mirror && it.object) for (const k of Object.keys(readObject(locate(`${project}/${String(it.object).split(/[:@]/)[0]}`)).mirror || {})) delete set[k];
+    const sub = it.assembly ? extra : {}; // a component's values go to its items: { cap: { units: 1.5 } }
+    const key = JSON.stringify([it.object, it.variant, it.assembly, set, sub]);
+    if (!built.has(key)) {
+      if (it.assembly) built.set(key, { key, sub: await buildAssembly(`${project}/${it.assembly}`, [...stack, ref], sub, opts) });
+      else {
+        const [ref, named] = String(it.object).split(':'), [objName, pin] = ref.split('@'), variant = named || it.variant;
+        const d = locate(`${project}/${objName}`), at = { ...(pin ? materialise(d, pin) : d), ...(variant ? { variant } : {}) };
+        const b = await build(at, set, opts);
+        built.set(key, { key, objName, b, version: pin || b.object.version, variant, role: ['reference', 'board'].includes(b.object.role) ? 'reference' : 'part' }); // a board is made by a fab: checked, never printed
+      }
+    }
+    return built.get(key);
+  };
+  const placing = [];
+  for (const it of a.items || []) {
+    if (!/^[a-z][\w-]*$/.test(it.id || '')) throw new Error(`each item needs an id (letters, digits, - or _): got ${JSON.stringify(it.id)}`);
+    if (!it.object === !it.assembly) throw new Error(`item ${it.id}: give either "object" or "assembly"`);
+    // Copies: one, a grid from repeat x/y, or a layout's keys. Each: { id, offset (from at), extra (values to set) }
+    const rx = it.repeat?.x, ry = it.repeat?.y, rl = it.repeat?.layout, copies = [];
+    if (rl) {
+      // A layout file in the project's layouts/, or (older assemblies) object/name: a layout kept in an object's .json
+      const [lp, ln] = String(rl).includes('/') ? String(rl).split('/') : [null, rl];
+      const data = lp ? readObject(locate(`${project}/${lp}`)).layouts?.[ln] : readLayout(project, ln);
+      if (!data) throw new Error(`item ${it.id}: no layout "${ln}" in ${lp}.json`);
+      const step = num(it.repeat.step);
+      // Values each copy sets: its width, a value for its row (rows: { "cap.row": ["R1", …] }) and constants (each)
+      // per: { "cap.legend": "legend" } sets an input from each key's own property (skipped where the key has none)
+      const per = (k) => Object.fromEntries(Object.entries(it.repeat.per || {}).filter(([, f]) => k[f] != null).map(([n, f]) => [n, k[f]]));
+      const values = (k) => ({ ...(it.repeat.width ? { [it.repeat.width]: k.units } : {}), ...(it.repeat.each || {}), ...per(k),
+        ...Object.fromEntries(Object.entries(it.repeat.rows || {}).map(([n, list]) => {
+          if (k.index >= list.length) throw new Error(`item ${it.id}: repeat.rows ${n} has ${list.length} values, the layout ${rows(data)} rows`);
+          return [n, list[k.index]];
+        })) });
+      const rows = (l) => (l.rows || []).length;
+      for (const k of keyCentres(data)) {
+        const extra = {};
+        for (const [n, val] of Object.entries(values(k))) {
+          if (!it.assembly) { extra[n] = val; continue; }
+          const [item, name] = n.split('.'); // in a component: <item>.<variable>
+          if (!name) throw new Error(`item ${it.id}: name a component's variable as <item>.<variable>, e.g. cap.units (got ${n})`);
+          (extra[item] ||= {})[name] = val;
+        }
+        copies.push({ id: `${it.id}-${k.index}-${k.col}`, offset: [k.x * step, k.y * step], extra, label: k.label });
+      }
+    } else {
+      const nx = rx ? Math.round(num(rx.count)) : 1, ny = ry ? Math.round(num(ry.count)) : 1;
+      for (let i = 0; i < nx; i++) for (let j = 0; j < ny; j++) {
+        copies.push({ id: it.repeat ? `${it.id}-${i}${ry ? `-${j}` : ''}` : it.id, offset: [rx ? i * num(rx.step) : 0, ry ? j * num(ry.step) : 0], extra: {} });
+      }
+    }
+    const first = await source(it, copies[0].extra);
+    values[it.id] = first.sub ? first.sub.values : first.b.values; // a repeated item's own name works too: cap.base, not only cap-0-0
+    for (const c of copies) { c.src = await source(it, c.extra); values[c.id] = c.src.sub ? c.src.sub.values : c.src.b.values; }
+    placing.push([it, copies]);
+  }
+  // Then place them: every item is built by now, so a position can refer to any item, before or after it (a board
+  // placed under the case's top, the case built with the board's Pico position)
+  for (const [it, copies] of placing) {
+    if (it.place === false) { // built only for its values ("place": false): a board a print plate's case is sized from
+      for (const c of copies) if (!c.src.sub) objects.push({ id: c.id, objName: c.src.objName, version: c.src.version, built: c.src.b, role: c.src.role, unplaced: true });
+      continue;
+    }
+    for (const c of copies) {
+      const src = c.src, id = c.id, key = src.key;
+      const base = (it.at || [0, 0, 0]).map(num), rot = (it.rotate || [0, 0, 0]).map((r) => num(r) * deg);
+      // A repeated item turns as a whole about its at: each copy's offset turns with it (keys on a tilted plate)
+      // Faces are moved as they are, not re-triangulated in place: triangulating again after a move rounds differently
+      const m = translate(base, rotate(rot, translate([c.offset[0], c.offset[1], 0], jscad.geometries.geom3.create()))).transforms;
+      const move = (polys) => polys.map((poly) => poly.map((v) => jscad.maths.vec3.transform([0, 0, 0], v, m)));
+      ids.push(id);
+      if (src.sub) {
+        const sub = src.sub;
+        for (const p of sub.parts) {
+          if (p.role === 'support' && a.kind !== 'plate') continue;
+          parts.push({ ...p, name: `${id}.${p.name}`, item: id, leaf: `${id}.${p.leaf}`, label: `${id} ${p.label}`,
+            geometry: transform(m, p.geometry), polygons: move(p.polygons), triangles: move(p.triangles), m: jscad.maths.mat4.multiply(jscad.maths.mat4.create(), m, p.m) });
+        }
+        for (const o of sub.objects) objects.push({ ...o, id: `${id}.${o.id}` });
+        for (const x of sub.fits) fits.push({ ...x, a: `${id}.${x.a}`, b: `${id}.${x.b}`, label: x.label && `${x.label} (${id})` });
+        requires.push(...sub.requires);
+        for (const n of sub.seen) seen.add(n);
+        items.push({ ...it, id, sub, role: 'part' });
+      } else {
+        const { b } = src;
+        for (const p of b.parts) {
+          if (p.role === 'support' && a.kind !== 'plate') continue; // supports are snipped off before parts go together
+          parts.push({ name: `${id}.${p.name}`, item: id, leaf: id, object: src.objName, role: src.role === 'reference' ? 'reference' : p.role, label: `${id}: ${p.label}`,
+            ...(p.filament ? { filament: p.filament } : {}), ...(p.mirror === false ? { mirror: false } : {}), part: p.name,
+            geometry: transform(m, p.geometry), polygons: move(p.polygons), triangles: move(p.triangles),
+            shape: `${key}:${p.name}`, hash: `${b.hash}:${p.name}`, local: p.polygons, localTriangles: p.triangles, m });
+        }
+        objects.push({ id, objName: src.objName, version: src.version, built: b, role: src.role });
+        items.push({ ...it, id, objName: src.objName, built: b, version: src.version, role: src.role });
+      }
+    }
+  }
+  // A fit with * applies to every copy: "key-*.switch.bottom" becomes one fit for key-0-0, key-0-1, …
+  // With * on both sides, each copy is checked against all the others: { "a": "key-*.cap", "b": "key-*.cap" }
+  for (const x of a.fits || []) {
+    const star = [x.a, x.b].find((n) => n.includes('*'));
+    if (!star) { fits.push({ ...x, num }); continue; }
+    const match = (n) => { const re = new RegExp(`^${n.split('.')[0].replace(/[-]/g, '\\-').replace('*', '([\\w-]+)')}$`); return ids.filter((id) => re.test(id)); };
+    const copies = match(star), at = (id, n) => [id, ...n.split('.').slice(1)].join('.');
+    if (!copies.length) throw new Error(`fit ${x.a} / ${x.b}: nothing matches ${star}`);
+    if (x.a.includes('*') && x.b.includes('*')) {
+      const others = match(x.b);
+      for (const id of copies) fits.push({ ...x, a: at(id, x.a), b: others.filter((o) => o !== id).map((o) => at(o, x.b)), num });
+      continue;
+    }
+    for (const id of copies) { const swap = (n) => (n === star ? at(id, n) : n); fits.push({ ...x, a: swap(x.a), b: swap(x.b), num }); }
+  }
+  return { a, project, name, items, parts, objects, fits, requires, values, num, seen,
+    polygons: parts.flatMap((p) => p.polygons), triangles: parts.flatMap((p) => p.triangles) };
+}
+
+// keyCentres(layout): each key's centre, from lib/layout.mjs (kept under this name for older callers)
+export { keyCentres };
+
+// ---------- checks ----------
+export { closest };
+
+// How much two parts overlap (mm³), from JSCAD's intersection.
+export function overlap(ga, gb) {
+  const v = jscad.measurements.measureVolume(jscad.booleans.intersect(ga, gb));
+  return Math.abs(v) < 1e-6 ? 0 : Math.abs(v);
+}
+
+// Overlaps between placed parts, remembered across runs (.cache/overlaps.json): a part is its build (the build cache's
+// hash: everything it's made from) and where it's placed, so after an edit only the pairs it touches are measured again
+const OVERLAPS = paths.cache('overlaps.json');
+let remembered = null, fresh = 0;
+function pairOverlap(pa, pb) {
+  if (!pa.hash || !pb.hash) return overlap(pa.geometry, pb.geometry);
+  remembered ||= (() => { try { return JSON.parse(fs.readFileSync(OVERLAPS, 'utf8')); } catch { return {}; } })();
+  const at = (p) => `${p.hash}@${Array.from(p.m || []).map((x) => Math.round(x * 1e6) / 1e6).join(',')}`;
+  const [x, y] = [at(pa), at(pb)].sort(), k = crypto.createHash('sha1').update(`${x}|${y}`).digest('hex');
+  if (!(k in remembered)) { remembered[k] = overlap(pa.geometry, pb.geometry); fresh++; }
+  return remembered[k];
+}
+function saveOverlaps() {
+  if (!fresh) return;
+  try { fs.mkdirSync(path.dirname(OVERLAPS), { recursive: true }); fs.writeFileSync(OVERLAPS, JSON.stringify(remembered)); fresh = 0; } catch {} // only slower without it
+}
+
+// checkAssembly(built) -> findings, as @rulecad/printcheck: { level, text, card? } (card: a short line for the mirror)
+export function checkAssembly(s) {
+  const out = [], f = (level, text, card) => out.push({ level, text, ...(card && { card }) }), mm = (n) => `${Number(n.toFixed(3))}`;
+  // Versions: every pin, from this assembly and its components, against every copy of that object
+  const pins = new Map();
+  for (const r of s.requires) pins.set(`${r.object} ${r.range}`, r);
+  for (const { object, range } of pins.values()) {
+    const copies = s.objects.filter((o) => o.objName === object);
+    if (!copies.length) { f('fail', `requires ${object} ${range}, but nothing uses it`); continue; }
+    const bad = copies.filter((o) => !satisfies(o.version, range));
+    f(bad.length ? 'fail' : 'pass', bad.length ? `${object} ${bad[0].version} doesn't meet ${range} (${bad.map((o) => o.id).join(', ')})`
+      : `${object} ${copies[0].version} meets ${range}${copies.length > 1 ? ` (${copies.length} copies)` : ''}`);
+  }
+  // Overlaps between object instances, inside components too. Bounding boxes first: most pairs can't touch.
+  const named = (p, n) => p.name === n || p.leaf === n || p.item === n || p.name.startsWith(`${n}.`);
+  const allowed = (a, b) => s.fits.some((x) => x.min != null && x.num(x.min) < 0 && ((named(a, x.a) && named(b, x.b)) || (named(a, x.b) && named(b, x.a))));
+  const box = new Map(), bx = (p) => box.get(p) || (box.set(p, bounds(p.triangles)), box.get(p));
+  const touch = (a, b) => [0, 1, 2].every((k) => bx(a).lo[k] <= bx(b).hi[k] + 1e-6 && bx(b).lo[k] <= bx(a).hi[k] + 1e-6);
+  const clashes = [];
+  for (let i = 0; i < s.parts.length; i++) for (let j = i + 1; j < s.parts.length; j++) {
+    const pa = s.parts[i], pb = s.parts[j];
+    if (pa.leaf === pb.leaf || !touch(pa, pb) || allowed(pa, pb)) continue;
+    const v = pairOverlap(pa, pb);
+    if (v > 0.01) clashes.push(`${pa.name} and ${pb.name} overlap by ${mm(v)} mm³`);
+  }
+  if (clashes.length) f('fail', clashes.slice(0, 5).join('; ') + (clashes.length > 5 ? `; and ${clashes.length - 5} more` : ''), `${clashes.length} overlaps`);
+  else f('pass', `no parts overlap (${new Set(s.parts.map((p) => p.leaf)).size} object instances)`, 'No parts overlap');
+  // Fits: the closest gap between two named things, against a range. Copies of one fit are reported together, worst first.
+  const pick = (n) => (Array.isArray(n) ? n.flatMap(pick) : s.parts.filter((p) => named(p, n)));
+  const groups = new Map();
+  for (const x of s.fits) {
+    const A = pick(x.a), key = x.note || `${x.a} / ${x.b}`;
+    const lo = x.min != null ? x.num(x.min) : -Infinity, hi = x.max != null ? x.num(x.max) : Infinity;
+    const reach = Math.max(2, ...[lo, hi].filter(Number.isFinite)) + 1; // look past the range, so a gap near it is measured
+    let B = pick(x.b);
+    if (Array.isArray(x.b) && A.length) { // against many others: only those within reach
+      const lo3 = [0, 1, 2].map((k) => Math.min(...A.map((p) => bx(p).lo[k]))), hi3 = [0, 1, 2].map((k) => Math.max(...A.map((p) => bx(p).hi[k])));
+      B = B.filter((p) => [0, 1, 2].every((k) => bx(p).lo[k] <= hi3[k] + reach && lo3[k] <= bx(p).hi[k] + reach));
+    }
+    if (!A.length || (!B.length && !Array.isArray(x.b))) { f('fail', `fit ${x.a} / ${x.b}: no such ${A.length ? x.b : x.a}`); continue; }
+    const vol = A.reduce((t, pa) => t + B.reduce((u, pb) => u + (touch(pa, pb) ? pairOverlap(pa, pb) : 0), 0), 0);
+    const gap = !B.length ? Infinity : vol > 0.01 ? -vol : closest(A.flatMap((p) => p.polygons), B.flatMap((p) => p.polygons), reach); // negative: overlap, mm³
+    const ok = vol > 0.01 ? lo < 0 : gap >= lo && gap <= hi;
+    if (!groups.has(key)) groups.set(key, { x, lo, hi, results: [] });
+    groups.get(key).results.push({ ok, gap, id: x.a });
+  }
+  for (const [key, { x, lo, hi, results }] of groups) {
+    const worst = results.reduce((w, r) => (!r.ok && w.ok ? r : r.ok === w.ok && r.gap < w.gap ? r : w), results[0]);
+    const say = (g) => (g < 0 ? `press fit, ${mm(-g)} mm³ overlap` : g === Infinity ? 'not near each other' : `closest gap ${mm(g)} mm`);
+    const n = results.length > 1 ? ` (${results.filter((r) => r.ok).length} of ${results.length} in range)` : '';
+    const label = (x.label || x.a).replace(/ \(.*\)$/, '');
+    f(worst.ok ? 'pass' : 'warn', `${key}: ${say(worst.gap)}${n}${worst.ok ? '' : `, wanted ${lo === -Infinity ? '' : `${mm(lo)} `}to ${hi === Infinity ? 'any' : mm(hi)} mm (${results.filter((r) => !r.ok).map((r) => r.id).join(', ')})`}`,
+      `${label}: ${worst.gap < 0 ? `press fit ${mm(-worst.gap)} mm³` : worst.gap === Infinity ? 'apart' : `gap ${Number(worst.gap.toFixed(2))} mm`}${worst.ok ? '' : ' (out of range)'}`);
+  }
+  // Plates print everything: no references
+  if (s.a.kind === 'plate') {
+    const refs = s.objects.filter((o) => o.role === 'reference' && !o.unplaced); // an unplaced item only lends its numbers
+    if (refs.length) f('fail', `a plate can't print references: ${refs.map((o) => o.id).join(', ')}`);
+  }
+  // Rules that are only estimates, anywhere in the assembly or its components
+  const est = new Set();
+  for (const o of s.objects) for (const e of o.built.entries) if (e.kind === 'estimate' && (e.used || !e.name.includes('.'))) est.add(e.name);
+  for (const n of s.seen) { const [u, k] = n.split('.'); if (loadRuleSet(u).rules[k]?.kind === 'estimate') est.add(n); }
+  if (est.size) f('warn', `uses estimates, not measurements: ${[...est].join(', ')}. Measure them and record kind: measured`, `Estimate: ${[...est].join(', ')}`);
+  saveOverlaps();
+  return out;
+}
+
+// shapes(parts) -> { shapes: [{ part, polygons, triangles }], place: [[shape index, 12 numbers], …] }
+// Each distinct shape once, then where each copy goes: a 3 × 4 transform by rows (x' = a·x + b·y + c·z + d, …).
+export function shapes(parts) {
+  const index = new Map(), list = [], place = [];
+  for (const p of parts) {
+    if (!index.has(p.shape)) { index.set(p.shape, list.length); list.push({ part: p, polygons: p.local, triangles: p.localTriangles }); }
+    const m = p.m, r = (x) => Number(x.toFixed(6)); // JSCAD's mat4 is column-major
+    place.push([index.get(p.shape), ...[m[0], m[4], m[8], m[12], m[1], m[5], m[9], m[13], m[2], m[6], m[10], m[14]].map(r)]);
+  }
+  return { shapes: list, place };
+}

package/lib/design.mjs

@@ -0,0 +1,197 @@
+// Designs: projects/<project>/objects/<object>.js (the shape) and <object>.json (its variables and metadata).
+// The .js exports main(v), where v holds the resolved variables (v.stem_arm) and rule sets (v.x1c.line). It
+// should hold no measurements of its own: lint() flags number literals other than 0, 1 and 2.
+// main() returns a shape, or named parts ({ cap, pillar }) described in the .json's "parts":
+//   { "pillar": { "role": "support", "label": "Breakaway pillar" } }   role: part (default) or support (printed, then
+//   removed). Checks and print files use every part; the mirror shows only real parts.
+//   "filament": "legend" prints the part in another of the project's filaments (project.json "filaments"); "mirror":
+//   false leaves it off the on-screen copy (fine detail); "optional": true lets main() leave it out (a keycap with no legend).
+// Variants: named sets of inputs in the .json ("variants": { "oem-r3": { "profile": "oem", "row": "R3" } }), built as
+// keyboard/keycap:oem-r3. Versions are the design over time; variants are alternatives that exist side by side.
+// Layouts: a "type": "layout" variable picks a file in the project's layouts/; the design gets every layout it can pick
+// as v.layouts[name] = { …the file, keys (each key's centre and properties), width, depth } (lib/layout.mjs).
+// Boards: "engine": "pcb" in the .json makes main(v) return a tscircuit board ({ board, matrix }, built with v.pcb, as
+// @rulecad/pcb describes); the build then carries its Circuit JSON (circuit) and matrix, and one part: the bare board
+// (its copper is in the 2D views).
+// Builds are cached in .cache/builds/, by everything they're made from (CAD_NO_CACHE=1 to skip).
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import crypto from 'node:crypto';
+import { resolve, loadRuleSet } from './rules.mjs';
+import { WS, paths, printerOf } from './workspace.mjs';
+import { readLayout, hasLayout, keys, width, depth } from './layout.mjs';
+import * as shapes from '@rulecad/shapes';
+import { engineId, packageVersion } from './versions.mjs';
+
+const require = createRequire(import.meta.url);
+const jscad = require('@jscad/modeling');
+
+// "keyboard/keycap", "keyboard/keycap:oem-r3" (a variant) or a path to the .js or .json
+//   -> { project, name, js, json, dir, variant }
+export function locate(ref) {
+  const [plain, variant] = String(ref).split(':');
+  ref = plain;
+  let base = ref.replace(/\.(js|json)$/, '');
+  if (!base.includes(path.sep) || !fs.existsSync(`${base}.json`)) {
+    const [project, name] = ref.split('/');
+    if (!project || !name) throw new Error(`name a design as <project>/<object>, e.g. keyboard/keycap (got "${ref}")`);
+    base = path.join(paths.project(project), 'objects', name);
+  }
+  if (!fs.existsSync(`${base}.json`) || !fs.existsSync(`${base}.js`)) throw new Error(`no design at ${path.relative(WS, base)}.{js,json}`);
+  const dir = path.dirname(path.dirname(base));
+  return { project: path.basename(dir), name: path.basename(base), js: `${base}.js`, json: `${base}.json`, dir, ...(variant ? { variant } : {}) };
+}
+
+// The layouts an object can pick, by name, from its layout variables' choices (built-ins like grid have no file)
+export function layoutsOf(d, object) {
+  const out = {};
+  for (const v of Object.values(object.variables || {})) if (v.type === 'layout') {
+    for (const n of v.choice || [v.value]) if (hasLayout(d.project, n, d.layoutsDir)) out[n] = readLayout(d.project, n, d.layoutsDir);
+  }
+  return out;
+}
+
+// A variant's inputs, under what's set explicitly
+export function variantSet(d, object, set = {}) {
+  if (!d.variant) return set;
+  const v = (object.variants || {})[d.variant];
+  if (!v) throw new Error(`${d.name} has no variant "${d.variant}" (variants: ${Object.keys(object.variants || {}).join(', ') || 'none'})`);
+  return { ...v, ...set };
+}
+
+const CACHE = paths.cache('builds'), CACHE_VERSION = 2;
+const source = (f) => fs.readFileSync(new URL(f, import.meta.url), 'utf8');
+// What every build is made with: this code, the shape helpers and JSCAD's version (an upgrade rebuilds everything);
+// boards also with the board engine (engineId: its code and tscircuit's version), loaded only for boards
+const own = source(import.meta.url) + source(import.meta.resolve('@rulecad/shapes')) + packageVersion('@jscad/modeling');
+export const pcbEngine = () => import('@rulecad/pcb').catch((e) => {
+  if (e.code === 'ERR_MODULE_NOT_FOUND' && /@rulecad\/pcb/.test(e.message)) throw new Error('boards need the board engine: npm install @rulecad/pcb');
+  throw e;
+});
+
+// An object's on-screen settings are "display" ({ "smooth": 24 }), and a part left off screen is "display": false.
+// Their first name, "mirror", still works: read here, the rest of the tool sees it as mirror either way.
+export const readObject = (d) => {
+  const o = JSON.parse(fs.readFileSync(d.json, 'utf8'));
+  if (o.display && !o.mirror) o.mirror = o.display;
+  for (const p of Object.values(o.parts || {})) if (p.display === false) p.mirror = false;
+  return o;
+};
+
+// build(design, set, { mirror }) -> { object, values, entries, parts, polygons (for the mirror), triangles (for checks and export) }
+//   parts: [{ name, role, label, geometry, polygons, triangles }]; polygons and triangles: every part together
+export async function build(d, set = {}, { mirror = false } = {}) {
+  const object = readObject(d);
+  set = variantSet(d, object, set);
+  const sets = d.rulesDir ? Object.fromEntries((object.uses || []).map((u) => [u, loadRuleSet(u, d.rulesDir)])) : {}; // a release's own rules
+  const display = mirror ? object.mirror || {} : {};
+  const { values, entries } = resolve(object, { set, sets, display }); // mirror: lighter for the display
+  const files = layoutsOf(d, object);
+  if (object.layouts) values.layouts = object.layouts; // older designs kept layouts in their .json
+  if (Object.keys(files).length) values.layouts = Object.fromEntries(Object.entries(files).map(([n, l]) => [n, { ...l, keys: keys(l), width: width(l), depth: depth(l) }]));
+
+  // The cache: everything the build is made from. A hit skips running the design (and its booleans) altogether
+  const ruleText = (object.uses || []).map((u) => JSON.stringify(sets[u] || loadRuleSet(u)));
+  const key = crypto.createHash('sha256').update(JSON.stringify([CACHE_VERSION, own, object.engine === 'pcb' ? engineId() : '', fs.readFileSync(d.js, 'utf8'), JSON.stringify(object), ruleText, files, set, display])).digest('hex');
+  const hit = path.join(CACHE, `${key}.json`);
+  if (!process.env.CAD_NO_CACHE && fs.existsSync(hit)) {
+    const c = JSON.parse(fs.readFileSync(hit, 'utf8'));
+    try { const now = new Date(); fs.utimesSync(hit, now, now); } catch {} // recently used: kept when the cache is pruned
+    for (const e of entries) if (c.used.includes(e.name)) e.used = true;
+    const parts = c.parts.map(({ solid: f, ...p }) => ({ ...p, geometry: fromFaces(f) }));
+    if (c.circuit) Object.assign(values, (await pcbEngine()).outputs(c.circuit, c.matrix));
+    return { object, values, entries, parts, polygons: parts.flatMap((p) => p.polygons), triangles: parts.flatMap((p) => p.triangles), cached: true, hash: key, ...(c.circuit ? { circuit: c.circuit, matrix: c.matrix } : {}) };
+  }
+
+  const mod = await import(`${d.js}?t=${fs.statSync(d.js).mtimeMs}`).catch((e) => { // a fresh copy after each edit
+    // Designs import JSCAD themselves, so it has to be installed where they are (it's the workspace's dependency)
+    if (e.code === 'ERR_MODULE_NOT_FOUND' && /@jscad\/modeling/.test(e.message)) throw new Error(`designs need JSCAD in the workspace: npm install @jscad/modeling (in ${WS})`);
+    if (/import statement outside a module/.test(e.message)) throw new Error(`designs are ES modules: set "type": "module" in ${path.join(WS, 'package.json')}`);
+    throw e;
+  });
+  if (typeof mod.main !== 'function') throw new Error(`${path.relative(WS, d.js)} has no exported main(v)`);
+  // Rules the code reads directly (v.mx.housing_top) count as used too, so estimates it relies on get flagged
+  const read = new Set(), watched = Object.fromEntries(Object.entries(values).map(([k, v]) => [k, v && typeof v === 'object'
+    ? new Proxy(v, { get: (t, r) => { if (typeof r === 'string' && r in t) read.add(`${k}.${r}`); return t[r]; } }) : v]));
+  const pcb = object.engine === 'pcb' ? await pcbEngine() : null;
+  watched.shapes = shapes; if (pcb) watched.pcb = pcb;
+  let made = await mod.main(watched), board = null;
+  if (object.engine === 'pcb') { // a circuit board: tscircuit builds it, and the bare board is its one part
+    const { board: b, matrix } = made && made.board ? made : { board: made };
+    board = { circuit: await pcb.render(b), ...(matrix ? { matrix } : {}) };
+    Object.assign(values, pcb.outputs(board.circuit, matrix)); // what it tells the parts around it: outline, Pico
+    made = pcb.solids(board.circuit, { thickness: values.thickness, smooth: values.smooth });
+  }
+  const parts = named(made, object.parts || {});
+  for (const e of entries) if (read.has(e.name)) e.used = true;
+  try {
+    fs.mkdirSync(CACHE, { recursive: true });
+    prune();
+    fs.writeFileSync(hit, JSON.stringify({ used: entries.filter((e) => e.used).map((e) => e.name), parts: parts.map(({ geometry, ...p }) => ({ ...p, solid: faces(geometry) })), ...(board || {}) }));
+  } catch {} // a cache that can't be written is only slower
+  return { object, values, entries, parts, polygons: parts.flatMap((p) => p.polygons), triangles: parts.flatMap((p) => p.triangles), hash: key, ...(board || {}) };
+}
+
+// The cache keeps its most recently used builds, about CACHE_KEEP of them (an old version's builds go first)
+const CACHE_KEEP = 800;
+function prune() {
+  if (Math.random() > 0.05) return; // now and then is enough
+  const files = fs.readdirSync(CACHE).map((f) => { const p = path.join(CACHE, f); return { p, t: fs.statSync(p).mtimeMs }; }).sort((a, b) => b.t - a.t);
+  for (const { p } of files.slice(CACHE_KEEP)) fs.rmSync(p, { force: true });
+}
+
+// A design's result as parts: named ({ cap, pillar }) or one unnamed shape ("body").
+function named(result, meta) {
+  const isShape = (r) => Array.isArray(r) || jscad.geometries.geom3.isA(r) || jscad.geometries.geom2.isA(r);
+  const entries = isShape(result) ? [['body', result]] : Object.entries(result || {});
+  const empty = (g) => g == null || (Array.isArray(g) && !g.length);
+  for (const k of Object.keys(meta)) if (!meta[k].optional && !entries.some(([n, g]) => n === k && !empty(g))) throw new Error(`parts in the .json lists "${k}", but main() returns no such part`);
+  return entries.filter(([name, g]) => !(empty(g) && meta[name]?.optional)).map(([name, g]) => {
+    const m = meta[name] || {};
+    if (m.role && !['part', 'support'].includes(m.role)) throw new Error(`part ${name}: role is part or support`);
+    // The solid for booleans (fit checks) is JSCAD's own, exactly; a cached build restores the very same faces
+    const geometry = solid(g);
+    return { name, role: m.role || 'part', label: m.label || name, ...(m.filament ? { filament: m.filament } : {}), ...(m.mirror === false ? { mirror: false } : {}),
+      geometry, polygons: polygons(g), triangles: polygons(g, { triangulate: true }) };
+  });
+}
+
+// A part's result as one JSCAD solid with its transforms applied (several solids become one set of faces), and back from
+// the exact faces a cache keeps: the same numbers, so booleans on a cached build agree with a fresh one.
+const { geom3, poly3 } = jscad.geometries;
+const solid = (g) => geom3.create([g].flat(Infinity).filter((x) => geom3.isA(x)).flatMap((x) => geom3.toPolygons(x)));
+const faces = (g) => geom3.toPolygons(g).map((p) => p.vertices.map((v) => [v[0], v[1], v[2]]));
+const fromFaces = (list) => geom3.create(list.map((vs) => poly3.create(vs)));
+
+// The rules of the printer a build is checked against (the project's, else the workspace's), resolved
+export const printer = (b, d) => { const n = printerOf(d.project); return b.values[n] || resolve({ uses: [n] }).values[n]; };
+
+// Only some parts: --part cap (by name), the real parts without supports, or what the mirror shows (no supports, and
+// no parts marked mirror: false).
+export function pick(b, { part, noSupports = false, forMirror = false } = {}) {
+  let parts = b.parts;
+  if (part) { parts = parts.filter((p) => p.name === part); if (!parts.length) throw new Error(`no part "${part}" (parts: ${b.parts.map((p) => p.name).join(', ')})`); }
+  if (noSupports || forMirror) parts = parts.filter((p) => p.role !== 'support');
+  if (forMirror) parts = parts.filter((p) => p.mirror !== false);
+  return { ...b, parts, polygons: parts.flatMap((p) => p.polygons), triangles: parts.flatMap((p) => p.triangles) };
+}
+
+// Any JSCAD result -> polygons (corner lists), transforms applied. triangulate: also split faces at T-junctions (a
+// corner of one face in the middle of a neighbour's edge, left by booleans) so every edge pairs up, as slicers want.
+export function polygons(result, { triangulate = false } = {}) {
+  const { geom3, geom2 } = jscad.geometries;
+  const out = [];
+  for (const g of [result].flat(Infinity)) {
+    if (geom2.isA(g)) throw new Error("2D shapes can't be printed or shown: extrude them first");
+    if (!geom3.isA(g)) continue;
+    const fixed = jscad.modifiers.generalize({ snap: true, triangulate }, g);
+    for (const p of geom3.toPolygons(fixed)) out.push(p.vertices.map((v) => [v[0], v[1], v[2]]));
+  }
+  if (!out.length) throw new Error('the design has no 3D shapes');
+  return out;
+}
+
+export { lint } from '@rulecad/variables'; // number literals that should be variables
+
+export { jscad };

package/lib/layout.mjs

@@ -0,0 +1,14 @@
+// Layout files: projects/<project>/layouts/<name>.json, in the format @rulecad/keyboard-layout describes and reads.
+import fs from 'node:fs';
+import path from 'node:path';
+import { WS, paths } from './workspace.mjs';
+
+export const layoutPath = (project, name, dir) => path.join(dir || path.join(paths.project(project), 'layouts'), `${name}.json`);
+export const hasLayout = (project, name, dir) => fs.existsSync(layoutPath(project, name, dir));
+export function readLayout(project, name, dir) {
+  const f = layoutPath(project, name, dir);
+  if (!fs.existsSync(f)) throw new Error(`no layout "${name}" (${path.relative(WS, f)})`);
+  return JSON.parse(fs.readFileSync(f, 'utf8'));
+}
+
+export { keys, width, depth, project } from '@rulecad/keyboard-layout';

package/lib/preview/page.html

@@ -0,0 +1,72 @@
+<!doctype html>
+<!-- Preview sheet: six views of a design in a dark style (black ground, light as the only material), for people
+     and for Claude to look at before printing. Rendered headlessly by lib/preview.mjs; data from /data.json. -->
+<html><head><meta charset="utf-8"><title>preview</title>
+<style>
+  html, body { margin: 0; background: #000; color: #b4b4b4; font: 400 22px -apple-system, "Helvetica Neue", sans-serif; }
+  canvas { display: block; }
+  .label { position: absolute; color: #5c5c5c; font-size: 18px; letter-spacing: 0.12em; text-transform: uppercase; }
+  #title { position: absolute; left: 32px; top: 24px; color: #fff; font-size: 30px; }
+  #meta { position: absolute; left: 32px; top: 64px; }
+</style>
+<script type="importmap">{ "imports": { "three": "/three/three.module.js" } }</script>
+</head><body>
+<div id="title"></div><div id="meta"></div>
+<script type="module">
+import * as THREE from 'three';
+const W = 1800, H = 1200, V = 600; // three views across, two down
+const data = await (await fetch('/data.json')).json();
+document.getElementById('title').textContent = data.title;
+document.getElementById('meta').textContent = data.meta;
+
+// Each part as its own geometry, Z-up (JSCAD, the bed) turned Y-up. Exploded: supports drop below, and in an
+// assembly each item rises above the one before, so what touches what can be seen.
+const geos = data.parts.map((p) => { const g = new THREE.BufferGeometry(); g.setAttribute('position', new THREE.Float32BufferAttribute(p.positions, 3)); g.rotateX(-Math.PI / 2); g.computeVertexNormals(); g.computeBoundingBox(); return g; });
+if (data.explode) {
+  const all = new THREE.Box3(); geos.forEach((g) => all.union(g.boundingBox));
+  const gap = (all.max.y - all.min.y) * 0.8;
+  let drop = 0;
+  data.parts.forEach((p, i) => { if (p.role === 'support') { drop += gap; geos[i].translate(0, -drop, 0); geos[i].computeBoundingBox(); } });
+  const items = [...new Set(data.parts.map((p) => p.item).filter(Boolean))]; // assemblies: each item above the last
+  data.parts.forEach((p, i) => { const k = items.indexOf(p.item); if (k > 0) { geos[i].translate(0, k * gap, 0); geos[i].computeBoundingBox(); } });
+}
+const box = new THREE.Box3(); geos.forEach((g) => box.union(g.boundingBox));
+const center = box.getCenter(new THREE.Vector3()), radius = box.getSize(new THREE.Vector3()).length() / 2;
+geos.forEach((g) => g.translate(-center.x, -center.y, -center.z));
+const geo = { boundingBox: box.translate(center.clone().negate()), computeBoundingBox() {} };
+
+const scene = new THREE.Scene();
+// Faces: dark, flat-lit, so shape reads without lighting up the screen. Creases: thin ink lines. Supports: faint
+// lines only (ink-3), so the part they hold up shows through them; references (not printed) the same.
+data.parts.forEach((p, i) => {
+  if (p.role === 'part') scene.add(new THREE.Mesh(geos[i], new THREE.MeshLambertMaterial({ color: 0x3a3a3a, flatShading: true, polygonOffset: true, polygonOffsetFactor: 1, polygonOffsetUnits: 1 })));
+  scene.add(new THREE.LineSegments(new THREE.EdgesGeometry(geos[i], 25), new THREE.LineBasicMaterial({ color: p.role === 'part' ? 0xffffff : 0x5c5c5c })));
+});
+scene.add(new THREE.AmbientLight(0xffffff, 0.6));
+const sun = new THREE.DirectionalLight(0xffffff, 2.2); sun.position.set(-1, 2, 1.5); scene.add(sun);
+const under = new THREE.DirectionalLight(0xffffff, 1.2); under.position.set(1, -2, 1); scene.add(under); // so views from below aren't black
+// The bed as a faint grid, so up and down are clear
+const grid = new THREE.GridHelper(radius * 4, 16, 0x2a2a2a, 0x1a1a1a);
+grid.position.y = geo.boundingBox.min.y; scene.add(grid);
+
+const renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });
+renderer.setPixelRatio(1); renderer.setSize(W, H); renderer.setScissorTest(true); renderer.setClearColor(0x000000);
+document.body.append(renderer.domElement);
+
+const d = radius * 3.2;
+const views = [
+  ['front', [0, 0, d]], ['side', [d, 0, 0]], ['3/4', [d * 0.62, d * 0.5, d * 0.62]],
+  ['top', [0, d, 0.0001]], ['bottom', [0, -d, 0.0001]], ['3/4 below', [d * 0.62, -d * 0.5, d * 0.62]],
+];
+views.forEach(([name, pos], i) => {
+  const x = (i % 3) * V, y = i < 3 ? V : 0; // WebGL's y runs up: the first row is the top half
+  const cam = new THREE.OrthographicCamera(-radius * 1.25, radius * 1.25, radius * 1.25, -radius * 1.25, 0.01, d * 4);
+  cam.position.set(...pos); cam.lookAt(0, 0, 0);
+  renderer.setViewport(x, y, V, V); renderer.setScissor(x, y, V, V);
+  renderer.render(scene, cam);
+  const l = document.createElement('div'); l.className = 'label'; l.textContent = name;
+  l.style.left = `${x + 32}px`; l.style.top = `${(i < 3 ? 112 : V + 24)}px`; document.body.append(l);
+});
+document.body.dataset.ready = '1';
+</script>
+</body></html>