@rulecad/cad 0.1.4 → 0.2.1

package/AGENTS.md

@@ -47,10 +47,23 @@ variable says which rule it comes from. Follow these steps; they're what makes a
   with ranges from rules. An overlap or gap outside its range is a finding: report it with the numbers, and never
   widen a range to make it pass without saying why.
 - Build bigger things from checked assemblies used as items, rather than placing their objects again.
+- A part is named in fits as `<item>.<part>`; an object that returns one unnamed shape has one part, `body`.
+- A gap fit can't tell whether holes line up. Where a board screws into a part, add a holes fit
+  (`{ "holes": "pcb.board", "into": "case.body", "depth": "m2.insert_length" }`).
+- A part built around another (a case around its board) reads it: `"uses": ["node/carrier"]`, then
+  `carrier.board_w` and `v.carrier.board_holes`. Never copy another object's numbers by hand.
+
+## Circuit boards
+- `"engine": "pcb"` in the .json; `main(v)` returns a board built with `v.pcb` (see @rulecad/pcb's README).
+- Parts come from rule sets where one exists (`v.pcb.xiao`, `qwiic`, `jstph`, `header`), or any standard footprint by
+  name (`v.pcb.part('U2', 'soic8', x, y)`). Turn parts in quarter turns with `rotation`, held in a variable.
+- Join pins with `nets` (`GND: ['U1.GND', 'J1.GND']`) and let the autorouter draw them; `cad check` runs the fab's
+  design rules. Look at the copper preview: connectors should face the edge their plug comes from.
 
 ## Talking to the person
 - Give links as one labelled line (`npx cad link <project>/<object> --md`), never a raw URL. If it says
-  "(not a release)", say so.
+  "(not a release)", say so. If it says the link is too long for chat, don't paste it: tell the person, and offer
+  short links (a secret Gist), which upload the model, so ask first.
 - Say what the checks found, with numbers. Ask before anything that leaves the computer: releases with `--push`,
   ordering boards, publishing.
 - Designs are code: only run designs you or the person trust. Links and rule files are data and never run.

package/README.md

@@ -69,9 +69,13 @@ fragment, which never reaches the web host, so the public page can open private
 which version it holds (`keyboard/keycap@0.1.0`, or `+changes` if it isn't a release). The page is to become `@rulecad/viewer`;
 `scripts/publish-view.sh "message"` publishes it (only that folder) to the public repo.
 
-- **Short links** (`--short`, and the default for `--md`): the link's data goes in a secret GitHub Gist (unlisted,
-  but anyone with the link can open it) and the link carries only its ID: `…/#s=<id>`. The page fetches it from
-  GitHub's API. The same model reuses its Gist (`.cache/links.json`).
+- **Short links** (`--short`, and the default for `--md`, once `"shorten": "gist"` is in `cad.config.json`'s
+  `targets`): the link's data goes in a secret GitHub Gist (unlisted, but anyone with the link can open it) and the
+  link carries only its ID: `…/#s=<id>`. The page fetches it from GitHub's API. The same model reuses its Gist
+  (`.cache/links.json`). `npm create rulecad` asks which you want. Without it, links carry the model, and `cad link`
+  says when one is too long for chat or email (over 8,000 characters).
+- **Boards** travel light: the board drawn from both sides (the page makes the front and back views from its layers)
+  and the schematic, with coordinates rounded to what a screen can show.
 - **Parts panel:** the page lists parts by kind (keycap ×9), opening to each copy (key-1-1). Each row shows or hides
   its parts and sets their style (solid, wireframe, x-ray, faint); the view has a mode, an explode slider, and
   switches for supports and references. Click a part in the model to select its copy and see its size.
@@ -92,6 +96,12 @@ which version it holds (`keyboard/keycap@0.1.0`, or `+changes` if it isn't a rel
 
 - `value`: a number, or arithmetic over numbers and names (`+ - * /`, brackets, `min`, `max`, `round`). Rule sets are
   `<namespace>.<rule>`; the object's own variables are bare names. Parsed, never evaluated as code.
+- **Other objects' numbers:** `"uses": ["node/carrier"]` reads another object as a rule set named after it:
+  `carrier.board_w` in an expression, `v.carrier.board_w` in code. It gets the object's variables and, from a board, its
+  outline (`board_x`, `board_y`, `board_w`, `board_d`) and, in code, its mounting holes (`v.carrier.board_holes`, each
+  `{ x, y, d }`). So a case follows its board: change the board and the case rebuilds around it. `"node/carrier@^0.2.0"`
+  also checks the version; `"node/carrier@0.2.0"` reads that release. `cad rules` shows each borrowed number with the
+  object and version it came from; two objects can't read each other.
 - `show`: on the rules card `cad show` hands its target (six at most). `interface`: other parts depend on it (versioning will compare these).
 - `tweak: { min, max }`: may be changed with `--set`. Variables without one are fixed by their rule.
 - Inputs that hold names or text, not numbers (the design reads them; expressions can't), all settable with `--set`:
@@ -196,6 +206,10 @@ other items' variables, so a keycap can sit exactly where its slot meets the swi
 - A fit with `*` applies to every copy: `{ "a": "plate", "b": "key-*.switch.bottom", … }`. With `*` on both sides,
   each copy is checked against every other copy near it: `{ "a": "key-*.cap", "b": "key-*.cap", "min": 0.5 }`. Repeated fits are reported
   together: the worst case, and how many of the copies are in range.
+- **Holes fits** follow a board's mounting holes into what they screw into: `{ "holes": "pcb.board", "into":
+  "case.body", "depth": "m2.insert_length" }`. Each screw's path must be clear for `depth` mm and solid within `ring`
+  mm of it (default: the hole's diameter) half way down. A gap fit can't see this: a board that rests on its bosses
+  passes even when the bosses are in the wrong place. `"direction": "up"` for screws from below.
 - `requires` pins versions (`^` same major, at least this version, 0.x included, since a minor release never breaks a
   fit here; `~` same minor); an item can use a release: `"object": "keycap@0.2.1"`, or a variant: `"keycap:oem-r3"`.
 - The check names any `estimate` rule an assembly relies on, through its positions or its objects, so guesses get
@@ -254,6 +268,8 @@ about 10 s, and a re-check after an edit measures only what the edit moved. The
 recently used builds.
 
 ### Assemblies: values from other parts
+(An object can also read another object directly, outside any assembly: see "Other objects' numbers" under Variables.
+That suits a case built around one board; `from` suits values that only mean something where items meet.)
 An item's `from` sets inputs from other items' values, in the assembly's names: `"from": { "usb_y":
 "board.pcb.pico_y" }`. Every item is built before any is placed, so positions can refer to items listed after them
 (the board placed under the case's top while the case is built from the board's Pico position). `"place": false`

package/bin/cad.mjs

@@ -7,7 +7,7 @@ import { fmt, loadRuleSet } from '../lib/rules.mjs';
 import { WS, TOOL, paths, config, printerOf } from '../lib/workspace.mjs';
 import { fromKLE } from '@rulecad/keyboard-layout';
 import { target, hasTarget } from '../lib/targets.mjs';
-import { locate, build, pick, lint, readObject, printer, pcbEngine } from '../lib/design.mjs';
+import { locate, build, pick, lint, readObject, printer, pcbEngine, objectSets } from '../lib/design.mjs';
 import { git, tags, bump, bigger, newer, compare, snapshot, materialise, files, prints, printsFile, engineId } from '../lib/versions.mjs';
 import { check } from '@rulecad/printcheck';
 import { preview } from '../lib/preview.mjs';
@@ -299,7 +299,7 @@ async function assembly(cmd, ref) {
 // ---------- links ----------
 // The model as a link: full print precision (triangles), the rules card, and exactly which version it is.
 async function links(d, b, set) {
-  const s = d.tag ? { kind: null } : since(d), fil = filaments(d.project);
+  const s = d.tag ? { kind: null } : await since(d), fil = filaments(d.project);
   const version = d.version || b.object.version || '0.0.0';
   const src = `${d.project}/${d.name}${d.variant ? `:${d.variant}` : ''}@${version}${s.kind && s.kind !== 'first' ? '+changes' : s.kind === 'first' ? '+unreleased' : ''}`;
   const model = {
@@ -330,8 +330,11 @@ async function shorten(l) {
 
 // --md: one line of labelled Markdown links, the form agents paste into chat (CLAUDE.md, "Replies with links").
 // Short (a Gist) unless --long; plain output is long (nothing uploaded) unless --short.
+const TOO_LONG = 8000; // characters: past this, chat apps and email cut a link short or refuse it
 async function printLinks(l) {
   if ((opt('md') && !opt('long')) || opt('short')) l = await shorten(l);
+  if (!l.short && l.view.length > TOO_LONG) console.error(`this link is ${(l.view.length / 1024).toFixed(0)} KB, too long for chat or email. ${hasTarget('shorten')
+    ? 'Leave out --long for a short one.' : 'For short links, add "shorten": "gist" to "targets" in cad.config.json: each model you share is then stored in a secret GitHub Gist (needs the gh command, signed in).'}`);
   // One link: the page picks which parts go in a download (all of them, one key, only the case)
   if (opt('md')) return console.log(`**${[l.title, l.version].filter(Boolean).join(' ')}**${l.src.includes('+') ? ' (not a release)' : ''}: [View and download](${l.view})`);
   console.log(`${l.src}, ${l.short ? 'short links (data in a secret Gist)' : `${(l.size / 1024).toFixed(1)} KB links`}${l.src.includes('+') ? ' (not a release: the link shows it)' : ''}`);
@@ -353,10 +356,12 @@ const KINDS = ['patch', 'minor', 'major'];
 const today = () => new Date().toISOString().slice(0, 10);
 
 // Unreleased changes: compare with the last release. -> { last, kind, reasons } (kind null: nothing changed)
-function since(d) {
+// A design that reads other objects is resolved with their numbers (each side with the objects it named then).
+const snap = async (d) => snapshot(d, (await objectSets(d, readObject(d))).sets);
+async function since(d) {
   const last = tags(d.project, d.name).at(-1);
   if (!last) return { last: null, kind: 'first', reasons: [] };
-  return { last, ...compare(snapshot(materialise(d, last.version)), snapshot(d)) };
+  return { last, ...compare(await snap(materialise(d, last.version)), await snap(d)) };
 }
 
 // Only the design's own files (and its project's changelog and print log) may have uncommitted changes.
@@ -391,7 +396,7 @@ async function releaseObject(d, { batch = false } = {}) {
   const raw = lint(fs.readFileSync(d.js, 'utf8')), fails = (b.circuit ? await (await pcbEngine()).checks(b.circuit, b.values, b.matrix) // boards: the board's checks
     : b.object.role === 'reference' ? [] : check(b.triangles, printer(b, d), { parts: b.parts })).filter((r) => r.level === 'fail'); // references aren't printed
   if (raw.length || fails.length) throw new Error(`fix the check first: ${[...raw.map((r) => `raw number ${r.text} on line ${r.line}`), ...fails.map((f) => f.text)].join('; ')}`);
-  let { last, kind, reasons } = since(d);
+  let { last, kind, reasons } = await since(d);
   if (!kind) throw new Error(`nothing has changed since ${last.version}`);
   const asked = opt('bump');
   if (asked && last) {
@@ -419,7 +424,7 @@ async function releaseProject(project) {
   if (!fs.existsSync(pj)) throw new Error(`no project "${project}"`);
   const p = JSON.parse(fs.readFileSync(pj, 'utf8')), manifest = {};
   for (const name of p.objects) {
-    const d = locate(`${project}/${name}`), s = since(d);
+    const d = locate(`${project}/${name}`), s = await since(d);
     if (!s.last) throw new Error(`${name} has no release yet: cad release ${project}/${name} -m "…"`);
     if (s.kind) throw new Error(`${name} has changes since ${s.last.version}: release it first`);
     manifest[name] = s.last.version;
@@ -453,7 +458,8 @@ async function releaseProject(project) {
 // Release every object in a project that changed, then the project: the tree may hold changes only to their files.
 async function releaseAll(project) {
   const pj = JSON.parse(fs.readFileSync(path.join(paths.project(project), 'project.json'), 'utf8'));
-  const changed = pj.objects.map((n) => locate(`${project}/${n}`)).filter((d) => since(d).kind);
+  const changed = [];
+  for (const n of pj.objects) { const d = locate(`${project}/${n}`); if ((await since(d)).kind) changed.push(d); }
   const allowed = new Set([`projects/${project}/project.json`, `projects/${project}/CHANGELOG.md`, `projects/${project}/prints.jsonl`,
     ...changed.flatMap((d) => files(d, readObject(d)))]);
   onlyChanged([...allowed]);
@@ -482,25 +488,25 @@ async function compareVariants(d, a, b) {
   console.log(out);
 }
 
-function status(project) {
+async function status(project) {
   for (const p of project ? [project] : fs.readdirSync(paths.projects)) {
     const pj = JSON.parse(fs.readFileSync(path.join(paths.project(p), 'project.json'), 'utf8'));
     console.log(`${p}${pj.version ? `@${pj.version}` : ''}`);
     for (const name of pj.objects) {
-      const s = since(locate(`${p}/${name}`));
+      const s = await since(locate(`${p}/${name}`));
       console.log(`  ${name.padEnd(16)} ${s.last ? s.last.version.padEnd(8) : 'unreleased'} ${s.kind === 'first' ? '' : s.kind ? `changed since: needs a ${s.kind} release` : 'up to date'}`);
     }
   }
 }
 
-function history(ref) {
+async function history(ref) {
   const [project, name] = ref.split('/');
   if (!name) {
     for (const t of tags(project).reverse()) console.log(`${t.tag}  ${t.date}  ${t.kind}  ${t.message}`);
     return status(project);
   }
   const d = locate(ref), done = prints(d);
-  const s = since(d);
+  const s = await since(d);
   if (s.kind && s.last) { console.log(`unreleased (needs ${s.kind}):`); for (const r of s.reasons) console.log(`  ${r.text}`); }
   for (const t of tags(d.project, d.name).reverse()) {
     console.log(`${t.version.padEnd(8)} ${t.date}  ${t.kind.padEnd(5)}  ${t.message}`);
@@ -508,9 +514,9 @@ function history(ref) {
   }
 }
 
-function diff(d, from, to) {
+async function diff(d, from, to) {
   if (!from) throw new Error('usage: cad diff <project>/<object> <from> [<to>]');
-  const a = snapshot(materialise(d, from)), b = snapshot(to ? materialise(d, to) : d);
+  const a = await snap(materialise(d, from)), b = await snap(to ? materialise(d, to) : d);
   const r = compare(a, b);
   console.log(`${d.project}/${d.name} ${from} → ${to || 'now'}: ${r.kind ? `a ${r.kind} change` : 'no changes'}`);
   for (const x of r.reasons) console.log(`  ${x.kind.padEnd(5)} ${x.text}`);

package/lib/assembly.mjs

@@ -12,6 +12,10 @@
 // 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.
+// A holes fit follows each of a board's mounting holes down its screw's path into another part:
+//   { "holes": "pcb.board", "into": "case.body", "depth": "m2.insert_length", "label": "Screws find their inserts" }
+// The path must be clear for depth mm (it lands in a hole) and solid within "ring" mm of it (default: the hole's
+// diameter) half way down, so the screw has something to grip. "direction": "up" for screws from below.
 import fs from 'node:fs';
 import crypto from 'node:crypto';
 import path from 'node:path';
@@ -21,7 +25,7 @@ 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 { closest, inside } 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`); };
@@ -181,7 +185,8 @@ export async function buildAssembly(ref, stack = [], overrides = {}, opts = {})
   }
   // 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 || []) {
+  for (let x of a.fits || []) {
+    if (x.holes) x = { ...x, a: x.holes, b: x.into }; // a holes fit: a board's holes (a) over what its screws go into (b)
     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)); };
@@ -258,6 +263,7 @@ export function checkAssembly(s) {
   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) {
+    if (x.holes) { holesFit(x); continue; }
     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
@@ -281,6 +287,27 @@ export function checkAssembly(s) {
     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)'}`);
   }
+  // Holes fits: each mounting hole's screw path, clear into a hole, with material round it
+  function holesFit(x) {
+    const A = pick(x.a), B = pick(x.b), label = x.label || `${x.a} into ${x.b}`;
+    const board = A.length && s.objects.find((o) => o.id === A[0].leaf)?.built;
+    if (!board?.circuit) return f('fail', `${label}: ${x.a} isn't a circuit board, so it has no mounting holes to follow`);
+    if (!B.length) return f('fail', `${label}: no such ${x.b}`);
+    const holes = board.circuit.filter((e) => e.type === 'pcb_hole' && !e.pcb_component_id);
+    if (!holes.length) return f('fail', `${label}: ${x.a} has no mounting holes`);
+    const depth = x.num(x.depth), down = x.direction === 'up' ? 1 : -1, faces = B.flatMap((p) => p.triangles);
+    const base = down < 0 ? 0 : board.values.thickness ?? 0, at = (h, dx, dy, t) => jscad.maths.vec3.transform([0, 0, 0], [h.x + dx, h.y + dy, base + down * t], A[0].m);
+    const steps = 8, misses = [];
+    for (const h of holes) {
+      const ring = x.ring != null ? x.num(x.ring) : h.hole_diameter, where = `hole at ${mm(h.x)}, ${mm(h.y)} mm`;
+      const blocked = Array.from({ length: steps }, (_, i) => (depth * (i + 0.5)) / steps).find((t) => inside(at(h, 0, 0, t), faces));
+      if (blocked != null) { misses.push(`${where}: solid ${mm(blocked)} mm along the screw's path`); continue; }
+      const round = Array.from({ length: steps }, (_, i) => (2 * Math.PI * i) / steps).filter((a) => !inside(at(h, ring * Math.cos(a), ring * Math.sin(a), depth / 2), faces));
+      if (round.length) misses.push(`${where}: no material ${mm(ring)} mm from the screw on ${round.length} of ${steps} sides`);
+    }
+    f(misses.length ? 'fail' : 'pass', misses.length ? `${label}: ${misses.join('; ')}` : `${label}: ${holes.length} of ${holes.length} holes clear for ${mm(depth)} mm, with material around each`,
+      `${label}: ${misses.length ? `${misses.length} of ${holes.length} miss` : `${holes.length} of ${holes.length} line up`}`);
+  }
   // 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

package/lib/design.mjs

@@ -23,7 +23,8 @@ 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';
+import { engineId, packageVersion, materialise } from './versions.mjs';
+import { satisfies } from '@rulecad/versions';
 
 const require = createRequire(import.meta.url);
 const jscad = require('@jscad/modeling');
@@ -44,6 +45,36 @@ export function locate(ref) {
   return { project: path.basename(dir), name: path.basename(base), js: `${base}.js`, json: `${base}.json`, dir, ...(variant ? { variant } : {}) };
 }
 
+// ---------- objects that read each other ----------
+// "uses": ["node/carrier"] reads another object's numbers as a rule set named after it (carrier.board_w in an
+// expression, v.carrier.board_w in code): its variables, and what a board tells the parts around it (board_x, board_y,
+// board_w, board_d, and board_holes for code). The object is built (cached) first. "node/carrier@^0.2.0" also checks
+// its version; "node/carrier@0.2.0" reads that release instead of the working copy.
+export const isObjectRef = (u) => String(u).includes('/');
+const building = new Set();
+export async function objectSets(d, object) {
+  const refs = (object.uses || []).filter(isObjectRef), sets = {}, extra = {};
+  if (!refs.length) return { sets, extra };
+  const self = `${d.project}/${d.name}`;
+  building.add(self);
+  try {
+    for (const u of refs) {
+      const [ref, want] = u.split('@'), exact = /^\d+\.\d+\.\d+$/.test(want || '');
+      if (building.has(ref)) throw new Error(`${self} and ${ref} read each other's numbers: one of them has to give its numbers to the other, not both`);
+      const base = locate(ref), b = await build(exact ? materialise(base, want) : base), version = b.object.version;
+      if (want && !exact && !satisfies(version, want)) throw new Error(`${self} uses ${ref} ${want}, but ${ref} is ${version}: change the range, or the design to suit ${version}`);
+      const units = Object.fromEntries(Object.entries(b.object.variables || {}).map(([k, x]) => [k, x.unit]));
+      const rules = {};
+      for (const [k, v] of Object.entries(b.values)) if (typeof v === 'number' && Number.isFinite(v)) {
+        rules[k] = { value: v, unit: units[k] ?? 'mm', rule: `${ref}'s ${k}`, kind: 'design', source: `${ref}@${version}` };
+      }
+      sets[u] = { name: base.name, rules };
+      if (b.circuit) extra[base.name] = { board_holes: (await pcbEngine()).holes(b.circuit) };
+    }
+  } finally { building.delete(self); }
+  return { sets, extra };
+}
+
 // 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 = {};
@@ -85,15 +116,17 @@ export const readObject = (d) => {
 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 refs = await objectSets(d, object); // other objects' numbers, when it reads them
+  const sets = { ...(d.rulesDir ? Object.fromEntries((object.uses || []).filter((u) => !isObjectRef(u)).map((u) => [u, loadRuleSet(u, d.rulesDir)])) : {}), ...refs.sets }; // a release's own rules
   const display = mirror ? object.mirror || {} : {};
   const { values, entries } = resolve(object, { set, sets, display }); // mirror: lighter for the display
+  for (const [n, x] of Object.entries(refs.extra)) Object.assign(values[n], x);
   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 ruleText = [...(object.uses || []).map((u) => JSON.stringify(sets[u] || loadRuleSet(u))), JSON.stringify(refs.extra)];
   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)) {

package/lib/versions.mjs

@@ -39,7 +39,7 @@ const layoutNames = (d, object) => Object.values(object.variables || {}).filter(
 // The files a design depends on, relative to the workspace (its git repo): its .js and .json, the rule sets and the layouts it uses.
 // (A board's engine is the tool's code, not the workspace's: its release records engineId() instead.)
 export function files(d, object) {
-  return [path.relative(WS, d.js), path.relative(WS, d.json), ...(object.uses || []).map((u) => `rules/${u}.json`),
+  return [path.relative(WS, d.js), path.relative(WS, d.json), ...(object.uses || []).filter((u) => !u.includes('/')).map((u) => `rules/${u}.json`),
     ...layoutNames(d, object).map((n) => `projects/${d.project}/layouts/${n}.json`)];
 }
 
@@ -54,7 +54,7 @@ export function materialise(d, version) {
   const js = path.join(base, `${d.name}.js`), json = path.join(base, `${d.name}.json`);
   fs.writeFileSync(js, show(path.relative(WS, d.js)));
   fs.writeFileSync(json, JSON.stringify(object, null, 2));
-  for (const u of object.uses || []) fs.writeFileSync(path.join(base, 'rules', `${u}.json`), show(`rules/${u}.json`));
+  for (const u of (object.uses || []).filter((x) => !x.includes('/'))) fs.writeFileSync(path.join(base, 'rules', `${u}.json`), show(`rules/${u}.json`)); // objects it reads are released on their own
   // The layouts it could pick, as they were then (only files that existed in that release)
   fs.mkdirSync(path.join(base, 'layouts'), { recursive: true });
   for (const v of Object.values(object.variables || {})) if (v.type === 'layout') for (const n of v.choice || [v.value]) {
@@ -91,9 +91,10 @@ function taggedEngine(tag) {
 }
 
 // Resolve a design as it is on disk, or as materialised from a release.
-export function snapshot(d) {
+// refs: the numbers of objects it reads (design.mjs objectSets), which a snapshot can't build itself.
+export function snapshot(d, refs = {}) {
   const object = JSON.parse(fs.readFileSync(d.json, 'utf8'));
-  const sets = d.rulesDir ? Object.fromEntries((object.uses || []).map((u) => [u, loadRuleSet(u, d.rulesDir)])) : {};
+  const sets = { ...(d.rulesDir ? Object.fromEntries((object.uses || []).filter((u) => !u.includes('/')).map((u) => [u, loadRuleSet(u, d.rulesDir)])) : {}), ...refs };
   const layouts = Object.fromEntries(layoutNames(d, object).map((n) => [n, readLayout(d.project, n, d.layoutsDir)]));
   // A board is also made by the board engine (footprints, the router): which engine, as recorded at the release
   const engine = object.engine === 'pcb' ? (d.tag ? taggedEngine(d.tag) : engineId()) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulecad/cad",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "The cad command: JSCAD designs from traceable rules, checked for printing and fit, versioned by what fits, shared as links and exported as Bambu 3MF.",
   "type": "module",
   "bin": {
@@ -46,16 +46,16 @@
     "@rulecad/variables": "^0.1.0",
     "@rulecad/keyboard-layout": "^0.1.2",
     "@rulecad/printcheck": "^0.1.0",
-    "@rulecad/fit": "^0.1.0",
+    "@rulecad/fit": "^0.2.0",
     "@rulecad/model-link": "^0.1.2",
     "@rulecad/versions": "^0.1.0",
     "@rulecad/shapes": "^0.1.0",
-    "@rulecad/rules": "^0.1.0",
+    "@rulecad/rules": "^0.2.0",
     "@jscad/modeling": "^2.12.0",
     "three": "^0.186.1"
   },
   "peerDependencies": {
-    "@rulecad/pcb": "^0.1.0"
+    "@rulecad/pcb": "^0.1.0 || ^0.2.0"
   },
   "peerDependenciesMeta": {
     "@rulecad/pcb": {