@protoboardai/ext-tscircuit 0.0.0-stage → 0.2.0

package/lib/stepfile.ts

@@ -0,0 +1,210 @@
+/**
+ * Small ISO 10303-21 (STEP) helpers for the 3D outputs: read the DATA section
+ * into entities, and drop named sub-shapes from a part's body file.
+ *
+ * UHD CAD bodies carry "body plus one named sub-shape per interface feature"
+ * (UHD src/authoring/cad.ts, cad_step): thin marker solids, 0.25 mm thick,
+ * on the faces an interface binds to (for an SMD part, its seating-plane pads,
+ * extruded downwards into the board). They identify features for binding;
+ * they are not part of the body. circuit-json-to-step and the GLB converter
+ * both take every solid in the file, so the provider strips the feature
+ * shapes before handing a part body to them.
+ */
+
+/** The DATA section as entity id → body (the text after `=`), in file order. */
+export function stepEntities(text: string): Map<number, string> {
+  const out = new Map<number, string>();
+  const data = text.indexOf("DATA;");
+  if (data < 0) return out;
+  let chunk = "";
+  let quoted = false;
+  for (let i = data + 5; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "'") quoted = !quoted; // '' inside a string toggles twice
+    if (ch !== ";" || quoted) {
+      chunk += ch;
+      continue;
+    }
+    const s = chunk.trim();
+    chunk = "";
+    if (s === "ENDSEC") break;
+    const m = /^#(\d+)\s*=\s*([\s\S]*)$/.exec(s);
+    if (m) out.set(Number(m[1]), m[2]);
+  }
+  return out;
+}
+
+const refs = (body: string) => [...body.matchAll(/#(\d+)/g)].map((m) => Number(m[1]));
+const typeOf = (body: string) => /^\s*([A-Z0-9_]+)\s*\(/.exec(body)?.[1] ?? "";
+
+/**
+ * `body` without its reference to `id` when that reference is one element of
+ * a list holding others (`(#1,#2)` → `(#2)`); undefined when the entity
+ * cannot do without it (a direct parameter, or the only element of a list).
+ */
+function dropReference(body: string, id: number): string | undefined {
+  let depth = 0;
+  let quoted = false;
+  let out = body;
+  const re = new RegExp(`#${id}(?!\\d)`, "g");
+  // positions of the reference, outside strings, with the depth of the parentheses around it
+  const hits: { at: number; depth: number }[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (ch === "'") quoted = !quoted;
+    if (quoted) continue;
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "#") {
+      re.lastIndex = i;
+      const m = re.exec(body);
+      if (m && m.index === i) hits.push({ at: i, depth });
+    }
+  }
+  if (!hits.length) return body;
+  if (typeOf(body) === "") return undefined; // a complex entity: never edited
+  for (const h of hits.reverse()) {
+    if (h.depth < 2) return undefined;
+    const len = `#${id}`.length;
+    const before = out.slice(0, h.at).replace(/\s+$/, "");
+    const after = out.slice(h.at + len).replace(/^\s+/, "");
+    if (before.endsWith("(") && after.startsWith(")")) return undefined;
+    out = before.endsWith(",") ? before.slice(0, -1) + after : before + after.replace(/^,/, "");
+  }
+  return out;
+}
+
+/**
+ * The STEP file without the solids of the products named in `names` (UHD
+ * interface feature shapes). Entities that referred to a removed one lose that
+ * list element, or go too when they cannot do without it. Returns the text
+ * unchanged when nothing matches.
+ */
+export function withoutShapes(text: string, names: Iterable<string>): { text: string; removed: string[] } {
+  const wanted = new Set(names);
+  const e = stepEntities(text);
+  const referrers = new Map<number, number[]>();
+  for (const [id, body] of e) for (const r of refs(body)) referrers.set(r, [...(referrers.get(r) ?? []), id]);
+  const using = (id: number, type: RegExp) => (referrers.get(id) ?? []).filter((r) => type.test(typeOf(e.get(r)!)));
+
+  // the named products' definitions, and every definition assembled under them
+  const usages = [...e].filter(([, b]) => typeOf(b) === "NEXT_ASSEMBLY_USAGE_OCCURRENCE").map(([, b]) => refs(b) as [number, number]);
+  const named = new Map<string, number[][]>();
+  for (const [id, body] of e) {
+    const m = /^PRODUCT\('((?:[^']|'')*)'/.exec(body);
+    if (!m || !wanted.has(m[1].replace(/''/g, "'"))) continue;
+    const pdefs = using(id, /^PRODUCT_DEFINITION_FORMATION/).flatMap((f) => using(f, /^PRODUCT_DEFINITION$/));
+    named.set(m[1], [...(named.get(m[1]) ?? []), pdefs]);
+  }
+  // a feature is a compound (an assembly of its pads); a body of the part that happens to share
+  // its name (a USB-C receptacle's `shell` solid beside its `shell` stake feature) stays
+  const assembly = (d: number) => usages.some(([p]) => p === d);
+  const removed: string[] = [];
+  const defs = new Set<number>();
+  for (const [name, products] of named) {
+    const compounds = products.filter((ds) => ds.some(assembly));
+    for (const ds of products.length > 1 && compounds.length ? compounds : products) for (const d of ds) defs.add(d);
+    removed.push(name);
+  }
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const [parent, child] of usages) {
+      // a child also used outside the named products stays
+      if (defs.has(parent) && !defs.has(child) && usages.every(([p, c]) => c !== child || defs.has(p))) defs.add(child), (grew = true);
+    }
+  }
+  // their shape representations' items: the solids (placements stay)
+  const doomed = new Set<number>();
+  for (const d of defs) {
+    const reps = using(d, /^PRODUCT_DEFINITION_SHAPE$/)
+      .flatMap((s) => using(s, /^SHAPE_DEFINITION_REPRESENTATION$/))
+      .map((sdr) => refs(e.get(sdr)!)[1]);
+    for (const rep of reps) {
+      const items = refs((e.get(rep) ?? "").replace(/,\s*#\d+\s*\)\s*$/, ")"));
+      for (const item of items) if (typeOf(e.get(item) ?? "") !== "AXIS2_PLACEMENT_3D") doomed.add(item);
+    }
+  }
+  if (!doomed.size) return { text, removed: [] };
+
+  const bodies = new Map(e);
+  const queue = [...doomed];
+  while (queue.length) {
+    const id = queue.pop()!;
+    if (!bodies.delete(id)) continue;
+    for (const r of referrers.get(id) ?? []) {
+      const body = bodies.get(r);
+      if (body === undefined) continue;
+      const kept = dropReference(body, id);
+      if (kept === undefined) queue.push(r);
+      else bodies.set(r, kept);
+    }
+  }
+  // then the removed solids' own geometry, wherever nothing kept still uses it
+  const below = new Set<number>();
+  const walk = [...doomed];
+  while (walk.length) for (const r of refs(e.get(walk.pop()!) ?? "")) if (!below.has(r)) below.add(r), walk.push(r);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const id of below) {
+      if (bodies.has(id) && (referrers.get(id) ?? []).every((r) => !bodies.has(r))) {
+        bodies.delete(id);
+        changed = true;
+      }
+    }
+  }
+  const head = text.slice(0, text.indexOf("DATA;"));
+  const data = [...bodies].map(([id, body]) => `#${id} = ${body};`).join("\n");
+  return { text: `${head}DATA;\n${data}\nENDSEC;\nEND-ISO-10303-21;\n`, removed };
+}
+
+/**
+ * A STEP assembly moved along Z by `dz` (mm): the placement of each top-level
+ * occurrence in the root product's shape representation is shifted (a new
+ * point for each, so nothing shared moves twice). The root is the product
+ * definition no assembly usage names as a component. KiCad writes its board
+ * this way, the board body and every footprint's model placed in the root
+ * (`pcb export step`), with z = 0 on the board's bottom face; the stack's
+ * board frame has z = 0 on the mid-plane (layout.ts), so a locked board's
+ * board.step is moved down by half its thickness. Unchanged (`moved: 0`) when
+ * the file has no such root.
+ */
+export function shiftStepAssembly(text: string, dz: number): { text: string; moved: number } {
+  const ents = stepEntities(text);
+  const related = new Set<number>();
+  const base = new Set<number>();
+  for (const body of ents.values()) {
+    const n = /^NEXT_ASSEMBLY_USAGE_OCCURRENCE\(.*,#(\d+),#(\d+),[^,]*\)$/s.exec(body.trim());
+    if (n) related.add(Number(n[2]));
+    const t = /^ITEM_DEFINED_TRANSFORMATION\('[^']*','[^']*',#(\d+),#(\d+)\)$/.exec(body.trim());
+    if (t) base.add(Number(t[1]));
+  }
+  const root = [...ents].find(([id, b]) => typeOf(b) === "PRODUCT_DEFINITION" && !related.has(id))?.[0];
+  const pds = [...ents].find(([, b]) => typeOf(b) === "PRODUCT_DEFINITION_SHAPE" && refs(b).at(-1) === root)?.[0];
+  const sdr = [...ents.values()].find((b) => typeOf(b) === "SHAPE_DEFINITION_REPRESENTATION" && refs(b)[0] === pds);
+  const rep = sdr ? ents.get(refs(sdr)[1]) : undefined;
+  if (root === undefined || !rep) return { text, moved: 0 };
+  const items = /^[A-Z_]+\(\s*'[^']*'\s*,\s*\(([^)]*)\)/s.exec(rep.trim())?.[1] ?? "";
+  let next = Math.max(0, ...ents.keys()) + 1;
+  const added: string[] = [];
+  const rewrite = new Map<number, string>();
+  for (const id of refs(items)) {
+    const axis = ents.get(id);
+    if (base.has(id) || !axis || typeOf(axis) !== "AXIS2_PLACEMENT_3D") continue;
+    const m = /^AXIS2_PLACEMENT_3D\(('[^']*'),#(\d+),(.*)\)$/s.exec(axis.trim());
+    const p = m ? /^CARTESIAN_POINT\(('[^']*'),\(([^)]*)\)\)$/.exec(ents.get(Number(m[2]))?.trim() ?? "") : null;
+    if (!m || !p) continue;
+    const xyz = p[2].split(",").map(Number);
+    if (xyz.length !== 3 || xyz.some((v) => !Number.isFinite(v))) continue;
+    const real = (v: number) => {
+      const s = (Math.round(v * 1e6) / 1e6 || 0).toString();
+      return s.includes(".") || s.includes("e") ? s.replace("e", "E") : `${s}.`;
+    };
+    added.push(`#${next} = CARTESIAN_POINT(${p[1]},(${[xyz[0], xyz[1], xyz[2] + dz].map(real).join(",")}));`);
+    rewrite.set(id, `AXIS2_PLACEMENT_3D(${m[1]},#${next++},${m[3]})`);
+  }
+  if (!rewrite.size) return { text, moved: 0 };
+  const out = text.replace(/^#(\d+)\s*=\s*AXIS2_PLACEMENT_3D\([^;]*\);/gm, (line, id) => (rewrite.has(Number(id)) ? `#${id} = ${rewrite.get(Number(id))};` : line));
+  const data = out.indexOf("DATA;");
+  const end = out.indexOf("ENDSEC;", data);
+  return { text: out.slice(0, end) + added.join("\n") + "\n" + out.slice(end), moved: rewrite.size };
+}

package/lib/suppliers.ts

@@ -0,0 +1,39 @@
+/**
+ * Supplier part numbers for the board's components, from the sourcing data the
+ * project already holds (no network), read through core's one offer reader
+ * (`@protoboardai/core/offers`, PB-1033):
+ *
+ *   parts/offers.json                     the library's offers by part id (`protoboard parts offers`)
+ *   parts/evidence/<part>/sourcing.json   the project's own sourcing record (ext-sourcing)
+ *
+ * A project part's own evidence comes first, a library part's library offers.
+ * An offer counts for a component when it names no ordering code or the
+ * component's own MPN (a series passive's offers are per value). Suppliers are
+ * read into tscircuit's keys; LCSC first (JLCPCB assembles from LCSC's
+ * C-numbers), then DigiKey and Mouser. They go into the generated source
+ * (`supplierPartNumbers`), the BOM, the pick-and-place and the KiCad fields,
+ * so a fab or a later KiCad export carries them.
+ */
+import type { BoardComponent } from "@protoboardai/core";
+import { readProjectOffers, supplierNumbersOf, SUPPLIER_ORDER, type ProjectOffers, type SupplierNumbers } from "@protoboardai/core/offers";
+
+export { supplierKey, type SupplierKey, type SupplierNumbers } from "@protoboardai/core/offers";
+
+/** The offers a capability's project holds (its catalog folder says which parts are library parts). */
+export const projectOffers = (project: { root: string; config: { catalog?: string } }): ProjectOffers => readProjectOffers(project.root, { catalog: project.config.catalog });
+
+/** Supplier part numbers by instance (components with none are left out), LCSC first, each supplier's in precedence order. */
+export function supplierNumbers(root: string, components: Pick<BoardComponent, "instance" | "part" | "mpn">[], offers: ProjectOffers = readProjectOffers(root)): Record<string, SupplierNumbers> {
+  const out: Record<string, SupplierNumbers> = {};
+  for (const c of components) {
+    const n = supplierNumbersOf(offers.forPart(c.part), c.mpn);
+    if (Object.keys(n).length) out[c.instance] = n;
+  }
+  return out;
+}
+
+/** The BOM and PnP columns: the first LCSC number, and every number as `supplier:number`. */
+export function supplierColumns(n: SupplierNumbers | undefined): { lcsc: string; suppliers: string } {
+  if (!n) return { lcsc: "", suppliers: "" };
+  return { lcsc: n.lcsc?.[0] ?? "", suppliers: SUPPLIER_ORDER.flatMap((k) => (n[k] ?? []).map((s) => `${k}:${s}`)).join(" ") };
+}

package/ops/circuit.ts

@@ -0,0 +1,270 @@
+/**
+ * The `circuit` capability with tscircuit (docs/specs/tool-integrations.md,
+ * docs/research/tscircuit-spike.md §9):
+ *
+ *   generate  UHD board → board netlist (core, tool-neutral) → tscircuit source
+ *             in tscircuit/, then a local build and route → circuit.json
+ *   export    circuit.json (rebuilt first if the source changed) → standard outputs in out/
+ *   extract   circuit.json → frames for the board's exports and interfaces, artifacts
+ *   check     tscircuit DRC + drift between the built board and the UHD board (pure)
+ */
+import { boardNetlist, boardOptions, declaredArtifacts, type BoardNetlist, type CapabilityDecl, type CapabilityContext, type CapabilityOperationFn, type ExtractedFacts } from "@protoboardai/core";
+import type { ArtifactDef, GeometryFrame } from "@deltarobotics/uhd";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkBoard } from "../lib/checks.ts";
+import { handPadJoins } from "../lib/layout.ts";
+import { readConstraints, type BoardConstraints } from "../lib/config.ts";
+import { boardDigest, boardProjection, EXPORT_SCHEMA, exportDrift, exportFile, exportInputs, fingerprintFormatChanged, readExportRecord, type ExportRecord } from "../lib/fingerprint.ts";
+import { applyBodies, boxStep, cadModels, chooseBodies, withMeshes, type ComponentBody } from "../lib/models.ts";
+import { projectOffers, supplierNumbers } from "../lib/suppliers.ts";
+import { buildAndRecord, buildErrors, digestOf, files, inputsDigest, readLayout, readNative, readOverrides, sourceDigest, type Native } from "../lib/native.ts";
+import { boardGlb, boardManifest, boardStep, bomCsv, fabricationFiles, laidOutNetlist, pnpCsv, renders, type PartEdgeFrame } from "../lib/outputs.ts";
+import { ENTRY_SOURCE, generateSource } from "../lib/source.ts";
+import { withoutShapes } from "../lib/stepfile.ts";
+import { isLocked } from "../lib/kicad/handoff.ts";
+import { checkLocked, exportLocked, lockedGenerate, refdesFor } from "./kicad.ts";
+
+/** The circuit capability as the manifest declares it: its artifacts are the ones extract reports. */
+const CIRCUIT_DECL = (JSON.parse(readFileSync(new URL("../protoboard-extension.json", import.meta.url), "utf8")) as { capabilities: CapabilityDecl[] }).capabilities.find((c) => c.id === "circuit")!;
+
+const netlistOf = (ctx: CapabilityContext): { netlist: BoardNetlist; digest: string } => {
+  const netlist = boardNetlist(ctx.module.definition, ctx.project.lookup, boardOptions(ctx.project));
+  return { netlist, digest: digestOf(JSON.stringify(netlist)) };
+};
+
+/** The mating frame each board export's part states for the exported interface (part coordinates), with the part's mount origin. */
+const edgeFrames = (ctx: CapabilityContext, netlist: BoardNetlist): Record<string, PartEdgeFrame> => {
+  const out: Record<string, PartEdgeFrame> = {};
+  for (const e of netlist.edge) {
+    const comp = netlist.components.find((c) => c.instance === e.instance);
+    const frame = ctx.project.lookup(comp?.part ?? "")?.interfaces.find((i) => i.id === e.interface)?.geometry?.frame;
+    if (!comp || !frame) continue;
+    const mount = comp.bodies.find((b) => b.mount)?.mount?.origin;
+    out[e.id] = { frame, ...(mount ? { mount: [mount[0], mount[1], mount[2]] as [number, number, number] } : {}) };
+  }
+  return out;
+};
+
+/** Digest of what the board depends on in UHD (fingerprint.ts boardProjection). */
+const boardFingerprint = (ctx: CapabilityContext, netlist: BoardNetlist) =>
+  boardDigest(boardProjection(netlist, edgeFrames(ctx, netlist), Object.fromEntries(netlist.components.map((c) => [c.part, (ctx.project.lookup(c.part)?.interfaces ?? []).map((i) => i.id)]))));
+
+/**
+ * Write what the chosen bodies need in the native folder: a box STEP for each package box, and a
+ * copy of each part STEP without its interface feature shapes; point each body at its copy.
+ */
+function prepareBodies(ctx: CapabilityContext, bodies: ComponentBody[]): void {
+  const root = ctx.project.root;
+  for (const b of bodies) if (b.box && !existsSync(join(root, b.box.path))) ctx.writeOutput(b.box.path, boxStep(`box ${b.box.size.join(" x ")} mm`, b.box.size), "component body box from package facts");
+  const copies = new Map<string, boolean>();
+  for (const b of bodies) {
+    if (!b.step || !b.stripped || !b.strip?.length) continue;
+    if (!copies.has(b.stripped)) {
+      const { text, removed } = withoutShapes(readFileSync(b.step, "utf8"), b.strip);
+      if (removed.length) ctx.writeOutput(b.stripped, text, `${b.label} without its interface feature shapes (${removed.join(", ")})`);
+      copies.set(b.stripped, removed.length > 0);
+    }
+    if (copies.get(b.stripped)) b.step = join(root, b.stripped);
+  }
+}
+
+/** Generate's inputs besides the board: layout.json, footprints.json, the constraints and the supplier numbers (native.ts). */
+const generateInputs = (ctx: CapabilityContext, netlist: BoardNetlist) => inputsDigest(ctx.project.root, ctx.module.native, ctx.constraints, supplierNumbers(ctx.project.root, netlist.components, projectOffers(ctx.project)));
+
+const constraintsOf = (ctx: CapabilityContext, netlist: BoardNetlist) => readConstraints(ctx.constraints, netlist.envelope);
+
+const failed = (summary: string, problems: string[]) => ({ status: "failed" as const, summary: `${summary}: ${problems[0]}${problems.length > 1 ? ` (+${problems.length - 1} more)` : ""}`, data: { problems } });
+
+/** Errors that mean the router never ran: the layout needs work before anything else is meaningful. */
+const blocking = (errors: { type: string; message: string }[]) => errors.filter((e) => e.type === "pcb_packing_error" || (e.type === "pcb_autorouting_error" && /skipped/.test(e.message)) || e.type === "pcb_missing_footprint_error");
+
+export const generate: CapabilityOperationFn = async (ctx) => {
+  const locked = lockedGenerate(ctx); // KiCad is the layout of record (ops/kicad.ts)
+  if (locked) return locked;
+  const root = ctx.project.root;
+  const f = files(ctx.module.native);
+  const { netlist, digest } = netlistOf(ctx);
+  if (netlist.problems.length) return failed(`${ctx.module.id} cannot be read as a board`, netlist.problems);
+  for (const n of netlist.notes ?? []) ctx.log(`warning: ${n}`);
+  const { constraints, problems, notes } = constraintsOf(ctx, netlist);
+  if (!constraints) return failed("circuit.config.ts constraints", problems);
+  for (const n of notes) ctx.log(`warning: ${n}`);
+  const { overrides, problems: fp } = readOverrides(root, ctx.module.native);
+  const { layout, problems: lp } = readLayout(root, ctx.module.native);
+  if (fp.length || lp.length) return failed("provider files", [...fp, ...lp]);
+
+  // each part's body as a cadModel (relative paths), and its supplier part numbers (LCSC first)
+  const bodies = chooseBodies(ctx.project, netlist.components, ctx.module.native);
+  prepareBodies(ctx, bodies);
+  const suppliers = supplierNumbers(root, netlist.components, projectOffers(ctx.project));
+  const g = generateSource({ netlist, constraints, overrides, layout, suppliers, models: cadModels(root, ctx.module.native, bodies) });
+  if (g.problems.length) return failed("no source written", g.problems);
+  for (const n of g.notes) ctx.log(`warning: ${n}`);
+  ctx.writeOutput(f.gen, g.source, "generated tscircuit source (rewritten by generate)");
+  if (!existsSync(join(root, f.entry))) ctx.writeOutput(f.entry, ENTRY_SOURCE, "tscircuit entry (written once; hand edits go here)");
+  if (!existsSync(join(root, f.layout))) {
+    ctx.writeOutput(f.layout, JSON.stringify({ $comment: "Positions for parts circuit.config.ts does not fix: { <instance>: { at: [x, y], rotation_deg, side } } (mm, board frame). Parts not listed are placed by tscircuit." }, null, 2) + "\n", "layout tweaks (hand-owned)");
+  }
+
+  // designators recorded per instance from the first build (F07), so the silkscreen prints them (F14) and a later KiCad lock keeps them
+  const designators = refdesFor(ctx, netlist, true).assigned;
+  const built = await buildAndRecord(ctx, g.map, digest, generateInputs(ctx, netlist), designators);
+  // traces written by hand between pads of one pin: generate joins them itself now (PB-1027, F22)
+  for (const h of handPadJoins(built.circuitJson, g.map, g.source)) ctx.log(`warning: a trace written by hand (${h.trace}) joins pads of ${h.instance}:${h.pin}, which generate joins itself; remove it from ${f.entry} (in KiCad it becomes copper on no net)`);
+  const errors = buildErrors(built.circuitJson);
+  const stop = blocking(errors);
+  const placement = Object.values(g.map.components).reduce((n, c) => ({ ...n, [c.placement]: (n[c.placement] ?? 0) + 1 }), {} as Record<string, number>);
+  const n = (t: string) => built.circuitJson.filter((e) => e.type === t).length;
+  const summary = `${netlist.components.length} components (${Object.entries(placement).map(([k, v]) => `${v} ${k}`).join(", ")}), ${netlist.nets.length} nets → ${n("pcb_trace")} traces, ${n("pcb_via")} vias in ${(built.build.build_ms / 1000).toFixed(1)} s${constraints.routing === "off" ? " (routing: off, placement only)" : ""}; ${errors.length} tscircuit error(s)`;
+  const data = { components: netlist.components.length, nets: netlist.nets.length, ...(notes.length ? { notes } : {}), placement, traces: n("pcb_trace"), vias: n("pcb_via"), build_ms: built.build.build_ms, errors: errors.map((e) => `${e.type}: ${e.message}`) };
+  if (stop.length) {
+    return { status: "failed", summary: `${summary}. Not routed: ${stop[0].message}. Move parts in ${f.layout} (or fix them in circuit.config.ts) and generate again`, data };
+  }
+  return { status: "succeeded", summary, data };
+};
+
+/** The current build, rebuilt first when the native source changed since it. */
+async function current(ctx: CapabilityContext, netlistDigest: string): Promise<Native | undefined> {
+  const root = ctx.project.root;
+  const native = readNative(root, ctx.module.native);
+  if (!native) return undefined;
+  if (native.build.sourceDigest === sourceDigest(root, ctx.module.native, native.build.sourceFiles)) return native;
+  ctx.log(`native source changed since the last build: rebuilding`);
+  return buildAndRecord(ctx, native.build.map, native.build.netlistDigest ?? netlistDigest, native.build.inputsDigest ?? "", refdesFor(ctx, netlistOf(ctx).netlist, false).assigned);
+}
+
+export const exportOutputs: CapabilityOperationFn = async (ctx) => {
+  if (isLocked(ctx.project.root, ctx.module.dir)) return exportLocked(ctx); // from KiCad (ops/kicad.ts)
+  const root = ctx.project.root;
+  const out = ctx.module.out;
+  const { netlist, digest } = netlistOf(ctx);
+  const native = await current(ctx, digest);
+  if (!native) return { status: "failed", summary: `no built board in ${ctx.module.native}/; run circuit:generate first` };
+  const { constraints } = constraintsOf(ctx, netlist);
+  const { circuitJson: cj, build } = native;
+  const stale = build.inputsDigest !== generateInputs(ctx, netlist);
+  if (stale) ctx.log(`layout.json, footprints.json or the circuit.config.ts constraints changed since generate; these outputs show the last generated layout. Run circuit:generate`);
+
+  // bodies: the part's own STEP, else a box from its package facts
+  const bodies = chooseBodies(ctx.project, netlist.components, ctx.module.native);
+  // what this export reads, before the bodies are pointed at their stripped copies (fingerprint.ts)
+  const inputs = exportInputs(root, ctx.module.native, boardFingerprint(ctx, netlist), ctx.constraints, bodies);
+  prepareBodies(ctx, bodies);
+  const { circuitJson: withBodies, used, labels } = applyBodies(cj, build.map, bodies, root);
+
+  // every output is made before any is written: a converter that throws leaves the last export's out/ as it was
+  // (core stages an export's out/ and swaps it in only when the export succeeds)
+  const fabrication = fabricationFiles(cj);
+  const { manifest, geometry, notes } = boardManifest(cj, build.map, netlist, constraints, build.sourceDigest, edgeFrames(ctx, netlist));
+  const glb = await boardGlb(withMeshes(withBodies, build.map, bodies), build.map);
+  const step = await boardStep(withBodies, build.map, labels);
+  const svgs = renders(cj);
+
+  for (const [path, text] of Object.entries(fabrication)) ctx.writeOutput(`${out}/${path}`, text);
+  const suppliers = supplierNumbers(root, netlist.components, projectOffers(ctx.project));
+  ctx.writeOutput(`${out}/bom.csv`, bomCsv(netlist, suppliers), "bill of materials by UHD instance, with supplier part numbers");
+  ctx.writeOutput(`${out}/pnp.csv`, pnpCsv(netlist, geometry, suppliers), "pick-and-place by UHD instance");
+  ctx.writeOutput(`${out}/board.manifest.json`, JSON.stringify(manifest, null, 2) + "\n", "geometry manifest");
+  ctx.writeOutput(`${out}/netlist.json`, JSON.stringify(laidOutNetlist(cj, build.map, netlist), null, 2) + "\n", "nets as laid out");
+  ctx.writeOutput(`${out}/board.glb`, glb.glb, "board with component bodies (glTF binary, metres, Y up)");
+  ctx.writeOutput(`${out}/board.step`, step, "board with component bodies (STEP, mm, board frame)");
+  for (const [name, svg] of Object.entries(svgs)) ctx.writeOutput(`${out}/${name}`, svg, "render");
+  const record: ExportRecord = { schema: EXPORT_SCHEMA, inputs };
+  ctx.writeOutput(exportFile(ctx.module.native), JSON.stringify(record, null, 2) + "\n", "export record: the inputs these outputs were made from");
+
+  // bodies chosen for board.glb that its converter could not load (it drew a box instead): named, not counted as bodies
+  const failed = new Set(glb.failed);
+  // applyBodies points each cad_component at the body's STEP, or at `${root}/${box path}`
+  const unloaded = bodies.filter((b) => (used[b.instance] === "part" || used[b.instance] === "box") && (failed.has(b.step ?? `${root}/${b.box?.path}`) || (!!b.mesh && failed.has(b.mesh.path)))).map((b) => b.instance);
+  for (const f of glb.failed) ctx.log(`warning: board.glb: could not load the body ${f}; the converter drew a box in its place`);
+  const count = (s: string) => Object.entries(used).filter(([i, u]) => u === s && !unloaded.includes(i)).length;
+  const summary = `exported ${netlist.components.length} components: Gerber + drill, BOM, PnP, GLB/STEP (${count("part")} part bodies, ${count("box")} package boxes${count("tscircuit") ? `, ${count("tscircuit")} tscircuit bodies` : ""}${count("none") ? `, ${count("none")} without a body` : ""}${unloaded.length ? `; board.glb could not load ${unloaded.length} bodies and drew boxes for ${unloaded.slice(0, 5).join(", ")}${unloaded.length > 5 ? ", …" : ""}` : ""}), manifest, netlist, renders`;
+  const data = { bodies: used, ...(unloaded.length ? { bodiesNotLoaded: unloaded, filesNotLoaded: glb.failed } : {}), notes, ...(stale ? { stale: "generate inputs changed since the last generate" } : {}) };
+  return { status: "succeeded", summary: stale ? `${summary}. Stale: generate inputs changed since the last generate; run circuit:generate` : summary, data };
+};
+
+export const extract: CapabilityOperationFn = async (ctx) => {
+  const root = ctx.project.root;
+  const { netlist, digest } = netlistOf(ctx);
+  const native = await current(ctx, digest);
+  if (!native) return { status: "failed", summary: `no built board in ${ctx.module.native}/; run circuit:generate first` };
+  const { constraints } = constraintsOf(ctx, netlist);
+  const { manifest, geometry } = boardManifest(native.circuitJson, native.build.map, netlist, constraints, native.build.sourceDigest, edgeFrames(ctx, netlist));
+  const def = ctx.module.definition;
+
+  // frames for the board's own exports and interfaces, from the manifest features of the same id
+  const frames: Record<string, GeometryFrame> = {};
+  const ids = new Set([...(def.exports ?? []).map((e) => e.id), ...def.interfaces.map((i) => i.id)]);
+  for (const [id, feature] of Object.entries(manifest.features)) if (ids.has(id)) frames[id] = feature.frame;
+  // a mechanical mounting interface of the board binds to its underside
+  for (const i of def.interfaces) if (i.domain === "mechanical" && !frames[i.id]) frames[i.id] = manifest.features.outline.frame;
+
+  const out = ctx.module.out;
+  const provenance = { tool: "tscircuit", toolVersion: geometry.toolVersion, sourceDigest: native.build.sourceDigest };
+  // the artifacts the manifest declares (core attaches them to the board at load: PB-1030), with this build's provenance
+  const candidates: ArtifactDef[] = declaredArtifacts({ dir: ctx.module.dir, out, native: ctx.module.native, module: def.id }, CIRCUIT_DECL, "tscircuit").map((a) => ({
+    ...a,
+    provenance: a.provenance?.generatedFrom ? { ...provenance, generatedFrom: a.provenance.generatedFrom } : { tool: "tscircuit", toolVersion: geometry.toolVersion },
+  }));
+  const artifacts = candidates.filter((a) => existsSync(join(root, a.filePath!)));
+  const facts: ExtractedFacts & { geometry: unknown } = {
+    frames,
+    artifacts,
+    // the layout itself, for re-binding steps and reports (not UHD)
+    geometry: {
+      outline: geometry.outline,
+      thickness_mm: geometry.thickness_mm,
+      layers: geometry.layers,
+      holes: geometry.holes,
+      components: Object.fromEntries(geometry.components.map((c) => [c.instance, { at: c.origin, center: c.center, rotation_deg: c.rotation_deg, side: c.side, frame: c.frame }])),
+      routing: geometry.routing,
+    },
+  };
+  return { status: "succeeded", summary: `${Object.keys(frames).length} frame(s) (${Object.keys(frames).join(", ")}), ${artifacts.length} artifact(s), ${geometry.components.length} placements`, data: facts };
+};
+
+export const check: CapabilityOperationFn = async (ctx) => {
+  const root = ctx.project.root;
+  const { netlist, digest } = netlistOf(ctx);
+  const f = files(ctx.module.native);
+  let constraints: BoardConstraints | undefined;
+  if (netlist.problems.length) return { status: "succeeded", summary: "board cannot be read", diagnostics: netlist.problems.map((m) => ({ code: "CIRCUIT_BOARD_UNREADABLE", severity: "error" as const, message: m, entity: { kind: "definition" as const, id: ctx.module.id } })) };
+  // the grouping's warnings: an unused export of a sub-module, a sub-module with no parts (docs/specs/nested-boards.md §11)
+  const grouping = (netlist.notes ?? []).map((m) => ({ code: "CIRCUIT_BOARD_GROUPING", severity: "warning" as const, message: m, entity: { kind: "definition" as const, id: ctx.module.id } }));
+  const locked = checkLocked(ctx, netlist); // model, handoff record and KiCad compared (ops/kicad.ts)
+  if (locked) return { status: "succeeded", summary: `locked: ${locked.filter((d) => d.severity === "error").length} error(s)`, diagnostics: [...locked, ...grouping] };
+  const read = constraintsOf(ctx, netlist);
+  constraints = read.constraints;
+  const notes = read.notes;
+  const diagnostics = await checkBoard({
+    native: readNative(root, ctx.module.native),
+    netlist,
+    netlistDigest: digest,
+    sourceDigest: sourceDigest(root, ctx.module.native, readNative(root, ctx.module.native)?.build.sourceFiles),
+    inputsDigest: generateInputs(ctx, netlist),
+    constraints,
+    constraintNotes: notes,
+    file: existsSync(join(root, f.gen)) ? f.gen : f.entry,
+    module: ctx.module.id,
+    overrides: readOverrides(root, ctx.module.native).overrides,
+    ...(existsSync(join(root, f.gen)) ? { generatedSource: readFileSync(join(root, f.gen), "utf8") } : {}),
+  });
+  // outputs made from other inputs than the current ones: a re-export would change them (fingerprint.ts)
+  if (existsSync(join(root, ctx.module.out, "board.step")) || existsSync(join(root, ctx.module.out, "board.glb"))) {
+    const recorded = readExportRecord(root, ctx.module.native);
+    const rerun = `run \`protoboard run circuit:export --module ${ctx.module.id}\``;
+    if (!recorded) diagnostics.push({ code: "CIRCUIT_STALE", severity: "warning", message: `${ctx.module.out}/ has no record of the inputs it was exported from (${exportFile(ctx.module.native)}): it was exported by an earlier provider, and a re-export may change board.step and board.glb; ${rerun}`, entity: { kind: "definition", id: ctx.module.id }, source: { file: ctx.module.out } });
+    else {
+      const now = exportInputs(root, ctx.module.native, boardFingerprint(ctx, netlist), ctx.constraints, chooseBodies(ctx.project, netlist.components, ctx.module.native));
+      const drift = exportDrift(recorded.inputs, now);
+      if (fingerprintFormatChanged(recorded.inputs)) diagnostics.push({ code: "CIRCUIT_FINGERPRINT_FORMAT", severity: "info", message: `${exportFile(ctx.module.native)} was written by an earlier provider, which fingerprinted the whole UHD module (a description or a price edit counted as a change); the board's own dependencies are fingerprinted now. A change to the board since that export cannot be told from the record, so it is not reported as stale; the next \`protoboard run circuit:export --module ${ctx.module.id}\` records the new format`, entity: { kind: "definition", id: ctx.module.id }, source: { file: exportFile(ctx.module.native) } });
+      if (drift.length) diagnostics.push({ code: "CIRCUIT_STALE", severity: "warning", message: `${ctx.module.out}/ was exported from other inputs than the current ones (${drift.join("; ")}): a re-export will change its outputs (board.step, board.glb and the rest); ${rerun}`, entity: { kind: "definition", id: ctx.module.id }, source: { file: exportFile(ctx.module.native) } });
+    }
+  }
+  diagnostics.push(...grouping);
+  // constraints generate would refuse (and fab-order keys the release would print wrong)
+  for (const m of read.problems) diagnostics.push({ code: "CIRCUIT_CONFIG_INVALID", severity: "error", message: `circuit.config.ts constraints: ${m}`, entity: { kind: "definition", id: ctx.module.id } });
+  const errors = diagnostics.filter((d) => d.severity === "error").length;
+  return { status: "succeeded", summary: errors ? `${errors} error(s)` : "board matches the UHD module; no tscircuit errors", diagnostics };
+};