@protoboardai/ext-frame-cad 0.0.0-stage → 0.2.0

package/lib/plate.ts

@@ -0,0 +1,233 @@
+/**
+ * Plates as a `cad` provider (docs/specs/tool-integrations.md §2–§4).
+ *
+ *   generate  UHD module + constraints → native design in <dir>/frame-cad/:
+ *             params.json (what the generator runs on) and frames.json (the
+ *             interface frames of the generated geometry)
+ *   export    params.json → build123d → standard outputs in <dir>/out/:
+ *             body.step, body.glb, body.manifest.json, body.dxf and
+ *             interfaces/<id>.glb
+ *   extract   frames.json → frames by interface id, plus the artifacts
+ *   check     model vs native design (frames, stale parameters) and native
+ *             design vs out/ (an export older than the design)
+ *
+ * The generator is deterministic for fixed params and build123d version, so
+ * export rebuilds exactly the body that generate measured.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ArtifactDef, ModuleDef } from "@deltarobotics/uhd";
+import { sha256, stableStringify, type CapabilityBinding, type OperationContext, type ProjectDiagnostic } from "@protoboardai/core";
+import { plateCadArtifacts } from "./artifacts.ts";
+import { buildParams, plateFiles, sameVec, type FramesFile, type PlateParams } from "./params.ts";
+import { runAsync } from "./run.ts";
+
+export const GENERATOR = fileURLToPath(new URL("../py/frame_cad.py", import.meta.url));
+export const python = () => process.env.PROTOBOARD_PYTHON || "python3";
+
+/** What generate and export need from their context (a capability context, or the frame-cad alias's). */
+export type Writer = Pick<OperationContext, "project" | "writeOutput" | "log">;
+
+/** A plate module and its provider directory. */
+export interface PlateTarget {
+  def: ModuleDef;
+  binding: Pick<CapabilityBinding, "dir" | "native" | "out" | "constraints" | "process" | "config">;
+}
+
+interface Signature {
+  area_mm2: number;
+  centroid: number[];
+  normal?: number[];
+}
+
+interface Generated {
+  toolVersion: string;
+  sourceDigest: string;
+  features: Record<string, Signature>;
+  frames: FramesFile;
+}
+
+type Outcome<T> = { ok: true; value: T } | { ok: false; summary: string; problems?: string[] };
+
+/** What the module currently binds, compared with what was generated: the re-binding worklist. */
+export function bindingDiff(def: ModuleDef, features: Record<string, Signature>, frames: FramesFile) {
+  const signatures: { interface: string; feature: string; bound?: Signature; generated?: Signature }[] = [];
+  const frameChanges: { interface: string; declared?: number[]; generated?: number[] }[] = [];
+  for (const i of def.interfaces) {
+    for (const ref of i.geometry?.refs ?? []) {
+      if (ref.kind !== "feature" || ref.artifact !== "cad_step") continue;
+      const now = features[ref.name];
+      const was = ref.signature;
+      const close = was && now && Math.abs(was.area_mm2 - now.area_mm2) <= 0.01 * Math.max(was.area_mm2, now.area_mm2, 1) && sameVec(was.centroid, now.centroid, 0.05);
+      if (!close) signatures.push({ interface: i.id, feature: ref.name, bound: was, generated: now });
+    }
+    const f = frames[i.id];
+    if (i.geometry?.frame && f && !(sameVec(i.geometry.frame.origin, f.origin) && sameVec(i.geometry.frame.normal, f.normal))) {
+      frameChanges.push({ interface: i.id, declared: i.geometry.frame.origin, generated: f.origin });
+    }
+  }
+  return { signatures, frames: frameChanges };
+}
+
+/** Run the generator on a params file into a fresh scratch folder; returns its summary and the folder. */
+async function runGenerator(root: string, paramsFile: string, name: string): Promise<Outcome<{ scratch: string; summary: Generated }>> {
+  const scratch = join(root, ".protoboard", "cache", "frame-cad", name);
+  rmSync(scratch, { recursive: true, force: true });
+  mkdirSync(scratch, { recursive: true });
+  const r = await runAsync(python(), [GENERATOR, paramsFile, scratch], { timeout: 300000, env: { ...process.env, PYTHONHASHSEED: "0" } });
+  if (r.ok) return { ok: true, value: { scratch, summary: JSON.parse(r.stdout.trim().split("\n").pop()!) as Generated } };
+  rmSync(scratch, { recursive: true, force: true });
+  return { ok: false, summary: `${name}: generator failed: ${r.error}` };
+}
+
+/** generate: write the params from the module and constraints, run the generator, keep the frames it measured. */
+export async function generatePlate(ctx: Writer, t: PlateTarget) {
+  const p = ctx.project;
+  const { def, binding: b } = t;
+  const files = plateFiles(b);
+  const { params, problems } = buildParams(def, def.id, b.constraints);
+  if (!params || problems.length) return { ok: false as const, summary: problems[0], problems };
+  ctx.writeOutput(files.params, stableStringify(params), `${def.id}: generator parameters from its interfaces and ${b.config}`);
+  const run = await runGenerator(p.root, join(p.root, files.params), params.name);
+  if (!run.ok) return run;
+  const { scratch, summary } = run.value;
+  ctx.writeOutput(files.frames, readFileSync(join(scratch, `${params.name}.frames.json`)), `${def.id}: interface frames of the generated geometry`);
+  rmSync(scratch, { recursive: true, force: true });
+  ctx.log(`${def.id}: ${Object.keys(summary.features).length} features; native design in ${b.native}`);
+  return {
+    ok: true as const,
+    value: {
+      module: def.id,
+      dir: b.dir,
+      native: b.native!,
+      toolVersion: summary.toolVersion,
+      sourceDigest: summary.sourceDigest,
+      features: summary.features,
+      frames: summary.frames,
+      rebind: bindingDiff(def, summary.features, summary.frames),
+    },
+  };
+}
+
+/** export: rebuild the body from the native params and write the standard outputs. */
+export async function exportPlate(ctx: Writer, t: PlateTarget) {
+  const p = ctx.project;
+  const { def, binding: b } = t;
+  const files = plateFiles(b);
+  if (b.process === "print") return { ok: false as const, summary: `${def.id}: ext-frame-cad cuts plates (DXF profiles for routing or waterjet); process "print" needs STL or 3MF, which it does not write. Use process "cut" or "machine" in ${b.config}` };
+  if (!existsSync(join(p.root, files.params))) return { ok: false as const, summary: `${def.id} has no native design (${files.params}); run \`protoboard run cad:generate --module ${def.id}\` first` };
+  const paramsBytes = readFileSync(join(p.root, files.params));
+  const params = JSON.parse(paramsBytes.toString("utf8")) as PlateParams;
+  const run = await runGenerator(p.root, join(p.root, files.params), params.name);
+  if (!run.ok) return run;
+  const { scratch, summary } = run.value;
+  const n = params.name;
+  ctx.writeOutput(`${b.out}/body.step`, readFileSync(join(scratch, `${n}.step`)), `${def.id}: body with one named sub-shape per interface feature`);
+  ctx.writeOutput(`${b.out}/body.glb`, readFileSync(join(scratch, `${n}.glb`)), `${def.id}: viewer mesh`);
+  ctx.writeOutput(`${b.out}/body.dxf`, readFileSync(join(scratch, `${n}.dxf`)), `${def.id}: cutting profiles`);
+  const interfaces = existsSync(join(scratch, "interfaces")) ? readdirSync(join(scratch, "interfaces")).sort() : [];
+  for (const f of interfaces) ctx.writeOutput(`${b.out}/interfaces/${f}`, readFileSync(join(scratch, "interfaces", f)), `${def.id}: ${f.replace(/\.glb$/, "")} geometry`);
+  // the generator's manifest, named for out/: it describes body.*, and records the design it was exported from
+  const manifest = JSON.parse(readFileSync(join(scratch, `${n}.manifest.json`), "utf8")) as Record<string, unknown> & { manufacturing?: Record<string, unknown> };
+  const standard = {
+    ...manifest,
+    artifact: "body",
+    params: `../${b.native!.split("/").pop()}/params.json`,
+    ...(manifest.manufacturing ? { manufacturing: { ...manifest.manufacturing, dxf: "body.dxf" } } : {}),
+    exportedFrom: { file: files.params, digest: sha256(paramsBytes) },
+  };
+  ctx.writeOutput(files.manifest, JSON.stringify(standard, null, 2) + "\n", `${def.id}: geometry manifest (features that carry interfaces, volume)`);
+  rmSync(scratch, { recursive: true, force: true });
+  ctx.log(`${def.id}: ${4 + interfaces.length} files in ${b.out}`);
+  return { ok: true as const, value: { module: def.id, out: b.out, volume_mm3: manifest.volume_mm3 as number, features: summary.features, interfaces: interfaces.map((f) => f.replace(/\.glb$/, "")) } };
+}
+
+const readJson = <T>(file: string): T | undefined => (existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as T) : undefined);
+
+/** extract: the generated frames by interface id, and the module's artifacts that exist. */
+export function extractPlate(root: string, t: PlateTarget) {
+  const { def, binding: b } = t;
+  const files = plateFiles(b);
+  const frames = readJson<FramesFile>(join(root, files.frames));
+  if (!frames) return { ok: false as const, summary: `${def.id} has no native design (${files.frames}); run \`protoboard run cad:generate --module ${def.id}\` first` };
+  const artifacts: ArtifactDef[] = plateCadArtifacts({ dir: b.dir, name: def.id, interfaces: Object.keys(frames) }).filter((a) => a.filePath && existsSync(join(root, a.filePath)));
+  return { ok: true as const, value: { frames, artifacts } };
+}
+
+const fmt = (v?: number[]) => (v ? `[${v.map((n) => Number(n.toFixed(3))).join(", ")}]` : "—");
+
+/**
+ * check: every interface frame equals the generated frame; the params the
+ * design was generated from are still what the interfaces and constraints
+ * give (otherwise the CAD is stale); and out/ was exported from the current
+ * params.
+ */
+export function plateDiagnostics(root: string, t: PlateTarget, source: ProjectDiagnostic["source"]): Omit<ProjectDiagnostic, "validator">[] {
+  const out: Omit<ProjectDiagnostic, "validator">[] = [];
+  const { def, binding: b } = t;
+  const files = plateFiles(b);
+  const entity = { kind: "definition" as const, id: def.id };
+  const generated = readJson<FramesFile>(join(root, files.frames));
+  if (!generated) {
+    out.push({ code: "FRAME_CAD_NOT_GENERATED", severity: "info", entity, message: `${def.id} has no generated frames (${files.frames}); run \`protoboard run cad:generate --module ${def.id}\``, source });
+    return out;
+  }
+  for (const [id, f] of Object.entries(generated)) {
+    const iface = def.interfaces.find((i) => i.id === id);
+    if (!iface) {
+      out.push({ code: "FRAME_CAD_UNKNOWN_INTERFACE", severity: "error", entity: { kind: "interface", id: `${def.id}:${id}` }, message: `generated frames name "${id}", which ${def.id} does not have (renamed or removed? regenerate)`, source });
+      continue;
+    }
+    const d = iface.geometry?.frame;
+    if (!d) {
+      out.push({ code: "FRAME_CAD_FRAME_MISSING", severity: "warning", entity: { kind: "interface", id: `${def.id}:${id}` }, message: `${id} has generated geometry but no frame in the model`, source });
+      continue;
+    }
+    const diffs = [
+      !sameVec(d.origin, f.origin) && `origin ${fmt(d.origin)} vs generated ${fmt(f.origin)}`,
+      !sameVec(d.normal, f.normal) && `normal ${fmt(d.normal)} vs generated ${fmt(f.normal)}`,
+      f.xAxis && d.xAxis && !sameVec(d.xAxis, f.xAxis) && `xAxis ${fmt(d.xAxis)} vs generated ${fmt(f.xAxis)}`,
+      (f.symmetryDeg ?? null) !== (d.symmetryDeg ?? null) && `symmetry ${d.symmetryDeg ?? "none"} vs generated ${f.symmetryDeg ?? "none"}`,
+    ].filter(Boolean);
+    if (diffs.length) {
+      out.push({
+        code: "FRAME_CAD_FRAME_MISMATCH",
+        severity: "error",
+        entity: { kind: "interface", id: `${def.id}:${id}` },
+        message: `${id}: ${diffs.join("; ")} — the model and the plate disagree; review, then \`protoboard run frame-cad-rebind --input module=${def.id}\``,
+        source,
+      });
+    }
+  }
+  const paramsFile = join(root, files.params);
+  if (existsSync(paramsFile)) {
+    const bytes = readFileSync(paramsFile);
+    const recorded = JSON.parse(bytes.toString("utf8")) as PlateParams;
+    const { params } = buildParams(def, def.id, b.constraints);
+    if (params && stableStringify(params) !== stableStringify(recorded)) {
+      const changed = [
+        ...params.interfaces.filter((i) => stableStringify(i) !== stableStringify(recorded.interfaces?.find((r) => r.id === i.id))).map((i) => i.id),
+        ...(stableStringify(params.plate) !== stableStringify(recorded.plate) ? ["plate"] : []),
+      ];
+      out.push({
+        code: "FRAME_CAD_STALE",
+        severity: "warning",
+        entity,
+        message: `${def.id}: the CAD was generated from different parameters (${changed.join(", ") || "interfaces"} changed); run \`protoboard run cad:generate --module ${def.id}\`, then cad:export`,
+        source,
+      });
+    }
+    const manifest = readJson<{ exportedFrom?: { digest?: string } }>(join(root, files.manifest));
+    if (manifest && manifest.exportedFrom?.digest !== sha256(bytes)) {
+      out.push({
+        code: "FRAME_CAD_EXPORT_STALE",
+        severity: "warning",
+        entity,
+        message: `${def.id}: ${b.out}/ was exported from other parameters than ${files.params}; run \`protoboard run cad:export --module ${def.id}\``,
+        source,
+      });
+    }
+  }
+  return out;
+}

package/lib/run.ts

@@ -0,0 +1,24 @@
+/**
+ * Run a generator's Python without blocking: a build takes tens of seconds,
+ * and a synchronous child process holds the event loop of whatever shares the
+ * process (the dev server, a test runner's worker RPC) for all of it.
+ */
+import { spawn } from "node:child_process";
+
+export type RunResult = { ok: true; stdout: string } | { ok: false; error: string };
+
+/** `command args…` with stdout collected; on failure, the last line of stderr (or why it did not run). */
+export function runAsync(command: string, args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv; timeout?: number } = {}): Promise<RunResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"], timeout: options.timeout });
+    let stdout = "";
+    let stderr = "";
+    child.stdout!.setEncoding("utf8").on("data", (d: string) => (stdout += d));
+    child.stderr!.setEncoding("utf8").on("data", (d: string) => (stderr += d));
+    child.on("error", (e) => resolve({ ok: false, error: e.message.split("\n")[0] }));
+    child.on("close", (code, signal) => {
+      if (code === 0) resolve({ ok: true, stdout });
+      else resolve({ ok: false, error: stderr.trim().split("\n").pop() || `${command} exited with ${code ?? signal}` });
+    });
+  });
+}

package/ops/cad.ts

@@ -0,0 +1,78 @@
+/**
+ * The `cad` capability (tool-integrations §2–§4, PB-822, PB-836):
+ * `protoboard run cad:<generate|export|extract|check> --module <id>` on a
+ * module whose `cad.config.ts` names @protoboardai/ext-frame-cad. Two kinds of
+ * module: plates (mechanical metadata plate_thickness_mm; lib/plate.ts,
+ * shared with the `frame-cad` alias) and mounting hardware (tagged fastener
+ * and screw, nut, standoff or spacer; lib/hardware-cad.ts, shared with the
+ * `hardware-cad` alias).
+ */
+import type { CapabilityContext, CapabilityOperationFn, ExtractedFacts } from "@protoboardai/core";
+import { HARDWARE_KINDS, hardwareKind } from "../lib/hardware.ts";
+import { exportHardware, extractHardware, generateHardware, hardwareDiagnostics, type HardwareTarget } from "../lib/hardware-cad.ts";
+import { isPlateModule } from "../lib/params.ts";
+import { exportPlate, extractPlate, generatePlate, plateDiagnostics, type PlateTarget } from "../lib/plate.ts";
+
+type Target = { kind: "plate"; t: PlateTarget } | { kind: "hardware"; t: HardwareTarget };
+
+function target(ctx: CapabilityContext): Target | string {
+  const def = ctx.module.definition;
+  if (ctx.project.definitions.get(def.id)?.origin.kind !== "local") return `${def.id} is not a local definition; ext-frame-cad designs local modules only (derive a local variant)`;
+  const config = ctx.project.capabilities.find((b) => b.capability === "cad" && b.module === def.id)!.config;
+  const binding = { dir: ctx.module.dir, native: ctx.module.native, out: ctx.module.out, constraints: ctx.constraints, process: ctx.process, config };
+  if (isPlateModule(def)) return { kind: "plate", t: { def, binding } };
+  if (hardwareKind(def)) return { kind: "hardware", t: { def, binding } };
+  return `${def.id} is neither a plate (mechanical metadata plate_thickness_mm) nor mounting hardware (tags fastener and one of ${HARDWARE_KINDS.join(", ")}), so ext-frame-cad cannot design it`;
+}
+
+export const generate: CapabilityOperationFn = async (ctx) => {
+  const x = target(ctx);
+  if (typeof x === "string") return { status: "failed", summary: x };
+  if (x.kind === "hardware") {
+    const r = generateHardware(ctx, x.t);
+    if (!r.ok) return { status: "failed", summary: r.summary, ...(r.problems ? { data: { problems: r.problems } } : {}) };
+    return { status: "succeeded", summary: `${r.value.module}: ${r.value.kind} parameters in ${r.value.native}; run cad:export for the body`, data: { ...r.value, generator: "@protoboardai/ext-frame-cad/py/hardware_cad.py" } };
+  }
+  const t = x.t;
+  const r = await generatePlate(ctx, t);
+  if (!r.ok) return { status: "failed", summary: r.summary, ...(r.problems ? { data: { problems: r.problems } } : {}) };
+  const stale = r.value.rebind.signatures.length + r.value.rebind.frames.length;
+  return {
+    status: "succeeded",
+    summary: `${t.def.id}: ${Object.keys(r.value.features).length} features; ${stale ? `${stale} binding(s) changed: review, then run frame-cad-rebind after cad:export` : "all bindings still match"}`,
+    data: { ...r.value, generator: "@protoboardai/ext-frame-cad/py/frame_cad.py" },
+  };
+};
+
+export const exportOutputs: CapabilityOperationFn = async (ctx) => {
+  const x = target(ctx);
+  if (typeof x === "string") return { status: "failed", summary: x };
+  if (x.kind === "hardware") {
+    const r = await exportHardware(ctx, x.t);
+    if (!r.ok) return { status: "failed", summary: r.summary };
+    return { status: "succeeded", summary: `${r.value.module}: body.step, body.glb, body.manifest.json in ${r.value.out} (${r.value.volume_mm3} mm³)`, data: r.value };
+  }
+  const t = x.t;
+  const r = await exportPlate(ctx, t);
+  if (!r.ok) return { status: "failed", summary: r.summary };
+  return { status: "succeeded", summary: `${t.def.id}: body.step, body.glb, body.manifest.json, body.dxf and ${r.value.interfaces.length} interface GLBs in ${ctx.module.out}`, data: r.value };
+};
+
+export const extract: CapabilityOperationFn = (ctx) => {
+  const x = target(ctx);
+  if (typeof x === "string") return { status: "failed", summary: x };
+  const r = x.kind === "hardware" ? extractHardware(ctx.project.root, x.t) : extractPlate(ctx.project.root, x.t);
+  if (!r.ok) return { status: "failed", summary: r.summary };
+  const facts: ExtractedFacts = r.value;
+  return { status: "succeeded", summary: x.kind === "hardware" ? `${facts.artifacts!.length} artifacts (a fastener's place comes from its fastener stack)` : `${Object.keys(facts.frames!).length} frames, ${facts.artifacts!.length} artifacts; re-bind with frame-cad-rebind`, data: facts };
+};
+
+export const check: CapabilityOperationFn = (ctx) => {
+  const x = target(ctx);
+  if (typeof x === "string") {
+    return { status: "succeeded", summary: x, diagnostics: [{ code: "FRAME_CAD_NOT_A_PLATE", severity: "error", entity: { kind: "definition", id: ctx.module.id }, message: x }] };
+  }
+  const source = ctx.project.definitions.get(x.t.def.id)!.origin.source;
+  const diagnostics = x.kind === "hardware" ? hardwareDiagnostics(ctx.project.root, x.t, source) : plateDiagnostics(ctx.project.root, x.t, source);
+  return { status: "succeeded", summary: `${diagnostics.length} finding(s)`, diagnostics };
+};

package/ops/frame-cad.ts

@@ -0,0 +1,46 @@
+import type { OperationFn } from "@protoboardai/core";
+import { generateThenExport } from "../lib/alias.ts";
+import { PROVIDER, plateBinding, plateModules } from "../lib/params.ts";
+import type { PlateTarget } from "../lib/plate.ts";
+
+export { GENERATOR, bindingDiff, python } from "../lib/plate.ts";
+
+/**
+ * frame-cad: the `cad` capability's generate and export for every plate
+ * module (or the named ones), in one operation. Each module needs a
+ * `cad.config.ts` naming @protoboardai/ext-frame-cad; its native design goes to
+ * `<dir>/frame-cad/` and its standard outputs to `<dir>/out/` by
+ * `cad:generate` and `cad:export` run for each module, each with its own
+ * operation record (lib/alias.ts), so the release can trace every `out/`.
+ * Returns the new signatures plus the bindings that no longer match
+ * (re-bind explicitly with frame-cad-rebind after reviewing them).
+ */
+export const frameCad: OperationFn = async (ctx) => {
+  const p = ctx.project;
+  const only = ctx.inputs.module?.split(",").map((s) => s.trim()).filter(Boolean);
+  const modules = plateModules(p, only);
+  if (!modules.length) return { status: "failed", summary: "no plate modules (local definitions with mechanical metadata plate_thickness_mm) in the project" };
+  const targets: PlateTarget[] = [];
+  const problems = modules.flatMap((m) => m.problems);
+  for (const { def } of modules.filter((m) => !m.problems.length)) {
+    const binding = plateBinding(p, def.id);
+    if (binding) targets.push({ def, binding });
+    else problems.push(`${def.id} has no cad.config.ts naming ${PROVIDER} (or it has a problem; see protoboard capabilities); add one in the module's folder: export default defineCapabilityConfig({ provider: "${PROVIDER}", process: "cut" })`);
+  }
+  if (problems.length) return { status: "failed", summary: problems[0], data: { problems } };
+
+  const run = await generateThenExport(p, targets.map((t) => t.def.id));
+  if (!run.ok) return { status: "failed", summary: run.summary, data: { module: run.module, problems: run.problems ?? [run.summary], steps: run.steps } };
+  type Generated = { module: string; features: Record<string, unknown>; rebind: { signatures: unknown[]; frames: unknown[] } };
+  const results = targets.map((t) => ({
+    ...(run.generated.get(t.def.id)!.data as Generated),
+    out: t.binding.out,
+    volume_mm3: (run.exported.get(t.def.id)!.data as { volume_mm3?: number }).volume_mm3,
+  }));
+  const stale = results.reduce((n, r) => n + r.rebind.signatures.length + r.rebind.frames.length, 0);
+  return {
+    status: "succeeded",
+    summary: `${results.map((r) => `${r.module} (${Object.keys(r.features).length} features)`).join(", ")}; ${stale ? `${stale} binding(s) changed: review, then run frame-cad-rebind` : "all bindings still match"}`,
+    data: { modules: results, generator: "@protoboardai/ext-frame-cad/py/frame_cad.py", steps: run.steps },
+  };
+};

package/ops/hardware-cad.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OperationFn } from "@protoboardai/core";
+import { hardwareBinding, hardwareModules } from "../lib/hardware.ts";
+import { generateThenExport } from "../lib/alias.ts";
+import type { HardwareTarget } from "../lib/hardware-cad.ts";
+
+export { HARDWARE_GENERATOR } from "../lib/hardware-cad.ts";
+
+const readJson = <T>(file: string): T | undefined => (existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as T) : undefined);
+
+/**
+ * hardware-cad: the `cad` capability's generate and export for every
+ * mounting-hardware module (screws, nuts, standoffs, spacers), or the named
+ * ones, in one operation, as `frame-cad` is for plates. Each module needs a
+ * `cad.config.ts` naming @protoboardai/ext-frame-cad in its folder; its
+ * parameters go to `<dir>/frame-cad/params.json` and its body to
+ * `<dir>/out/` by `cad:generate` and `cad:export` run for each module, each
+ * with its own operation record (lib/alias.ts). Returns each body's volume with the volume it
+ * replaces (mass = volume × material density, so a change moves the system
+ * mass).
+ */
+export const hardwareCad: OperationFn = async (ctx) => {
+  const p = ctx.project;
+  const only = ctx.inputs.module?.split(",").map((s) => s.trim()).filter(Boolean);
+  const modules = hardwareModules(p, only);
+  if (!modules.length) return { status: "failed", summary: "no hardware modules (local definitions tagged fastener and screw, nut, standoff or spacer) in the project" };
+  const problems = modules.flatMap((m) => m.problems);
+  const targets: HardwareTarget[] = [];
+  for (const { def } of modules.filter((m) => !m.problems.length)) {
+    const binding = hardwareBinding(p, def.id);
+    if (binding) targets.push({ def, binding });
+    else problems.push(`${def.id} has no cad.config.ts naming @protoboardai/ext-frame-cad (or it has a problem; see protoboard capabilities); add one in a folder of its own: export default defineCapabilityConfig({ provider: "@protoboardai/ext-frame-cad", module: "${def.id}" })`);
+  }
+  if (problems.length) return { status: "failed", summary: problems[0], data: { problems } };
+
+  // the volume each body replaces, read before the export empties out/
+  const before = new Map(targets.map((t) => [t.def.id, readJson<{ volume_mm3?: number }>(join(p.root, t.binding.out, "body.manifest.json"))?.volume_mm3 ?? null]));
+  const run = await generateThenExport(p, targets.map((t) => t.def.id));
+  if (!run.ok) return { status: "failed", summary: run.summary, data: { module: run.module, problems: run.problems ?? [run.summary], steps: run.steps } };
+  type Generated = { kind: string };
+  type Exported = { out: string; toolVersion: string; volume_mm3: number };
+  const results = targets.map((t) => {
+    const gen = run.generated.get(t.def.id)!.data as Generated;
+    const exp = run.exported.get(t.def.id)!.data as Exported;
+    return { module: t.def.id, kind: gen.kind, dir: t.binding.dir, out: exp.out, toolVersion: exp.toolVersion, volume_mm3: exp.volume_mm3, previousVolume_mm3: before.get(t.def.id) ?? null };
+  });
+  const changed = results.filter((r) => r.previousVolume_mm3 !== null && r.previousVolume_mm3 !== r.volume_mm3);
+  return {
+    status: "succeeded",
+    summary: `${results.length} hardware bodies; ${changed.length ? `volume changed for ${changed.map((r) => r.module).join(", ")} (system mass moves)` : "volumes unchanged"}`,
+    data: { modules: results, generator: "@protoboardai/ext-frame-cad/py/hardware_cad.py", steps: run.steps },
+  };
+};

package/ops/package.ts

@@ -0,0 +1,96 @@
+/**
+ * Contributions to the Manufacturing Package (@protoboardai/ext-release section
+ * contract) for the plates this provider designs: the cut order of each
+ * plate in its unit's work order (process, material, stock thickness and
+ * size, quantities by DXF layer, hole sizes, the smallest feature the
+ * router bit must cut, what the DXF leaves out, edge finish), and the
+ * inspection of what the cut order asks for in the test plan. Values come
+ * from the module (material, interfaces), its cad.config.ts, the generator
+ * parameters (frame-cad/params.json) and the standard outputs (out/).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { CapabilityBinding, Project } from "@protoboardai/core";
+import type { Block, SectionContext, SectionFn } from "@protoboardai/ext-release";
+import { glbBox, perBuild, providerModules, readOutput } from "@protoboardai/ext-release/helpers";
+import { DEFAULTS, mechanical, PROVIDER } from "../lib/params.ts";
+
+interface Manifest {
+  dxf?: string;
+  layers?: string[];
+  quantities?: Record<string, number>;
+  notInDxf?: string[];
+  thickness_mm?: Record<string, number>;
+}
+
+const n = (v: number, d = 1) => String(Number(v.toFixed(d)));
+
+/** What the cut order needs for one plate module. */
+export function cutOrder(p: Project, b: CapabilityBinding) {
+  const def = p.definitions.get(b.module!)!.def;
+  const m = readOutput<{ manufacturing?: Manifest }>(p, b, "body.manifest.json")?.manufacturing ?? {};
+  const c = { ...DEFAULTS, ...Object.fromEntries(Object.entries(b.constraints).map(([k, v]) => [k.replace(/_mm$/, ""), v])) } as Record<string, unknown>;
+  const mat = mechanical(def).material ?? (def.domains?.find((d) => d.domain === "mechanical") as { material?: unknown } | undefined)?.material;
+  const material = typeof mat === "object" && mat ? ((mat as { name?: string }).name ?? "") : typeof mat === "string" ? mat : "";
+  const params = b.native && existsSync(join(p.root, b.native, "params.json")) ? (JSON.parse(readFileSync(join(p.root, b.native, "params.json"), "utf8")) as { interfaces?: { fastener_d: number; hole_count: number; placement: string }[] }) : undefined;
+  const clearance = Number(c.hole_clearance ?? DEFAULTS.hole_clearance);
+  const holes = new Map<number, number>();
+  for (const i of params?.interfaces ?? []) if (i.placement !== "clamp") holes.set(i.fastener_d, (holes.get(i.fastener_d) ?? 0) + i.hole_count);
+  const slots = (Array.isArray(c.slots) ? (c.slots as { size: [number, number] }[]) : []).map((s) => Math.min(...s.size));
+  const armSlot = Number(c.arm_slot_width ?? 0);
+  const smallest = Math.min(...[...slots, ...(armSlot > 0 ? [armSlot] : [])].filter((x) => x > 0));
+  const box = glbBox(join(p.root, b.out, "body.glb"));
+  return { def, m, material, holes, clearance, smallest: Number.isFinite(smallest) ? smallest : undefined, corner: Number(c.corner_radius ?? DEFAULTS.corner_radius), box, carbon: /carbon/i.test(material) };
+}
+
+export const workOrder: SectionFn = ({ project: p, unit, release }: SectionContext) => {
+  const plates = providerModules(p, unit, PROVIDER).filter((b) => b.process === "cut");
+  if (!plates.length) return undefined;
+  const builds = unit.perProduct * release.build;
+  const blocks: Block[] = [{ kind: "paragraph", text: "Plates cut from sheet on a CNC router. Send the shop the DXF (one layer per profile) and the STEP for reference, with the values below. Quantities are for every build of this unit; order the shop's minimum or a spare if a plate is critical." }];
+  for (const b of plates) {
+    const o = cutOrder(p, b);
+    const per = perBuild(unit, o.def.id);
+    const layers = o.m.layers ?? [];
+    blocks.push({ kind: "heading", text: o.def.name ?? o.def.id });
+    blocks.push({
+      kind: "keyvalues",
+      rows: [
+        { label: "Process", value: "CNC routing from sheet", note: `${b.config}: process cut` },
+        { label: "Material", value: o.material || "not stated in the model: state it on the order" },
+        ...Object.entries(o.m.thickness_mm ?? {}).map(([k, t]) => ({ label: `Stock: ${k}`, value: `${t} mm sheet`, note: "a stock thickness the shop lists; check before ordering" })),
+        ...(o.box ? [{ label: "Plate size", value: `${n(o.box.size[0])} × ${n(o.box.size[1])} mm overall`, note: "bounding box of the body, clamps included; nest on the shop's sheet" }] : []),
+        { label: "Quantity", value: layers.map((l) => `${(o.m.quantities?.[l] ?? 1) * per * builds} × ${l}`).join(", ") || `${per * builds}`, note: `${per} per build × ${builds} build${builds === 1 ? "" : "s"}` },
+        ...[...o.holes].map(([d, count]) => ({ label: `Holes M${n(d)}`, value: `Ø${n(d + 2 * o.clearance, 2)} mm, ${count} per plate`, note: `fastener + 2 × ${o.clearance} mm clearance (hole_clearance_mm); hold the routing tolerance inside it` })),
+        ...(o.smallest ? [{ label: "Router bit", value: `≤ ${n(o.smallest)} mm`, note: `the narrowest slot; inside corners take the bit's radius (outline corners ${o.corner} mm)` }] : []),
+        { label: "Files", value: `files/mechanical/${o.def.id}/${o.def.id}.dxf (layers ${layers.join(", ") || "—"}), ${o.def.id}.step` },
+        ...(o.m.notInDxf ?? []).map((x) => ({ label: "Not in the DXF", value: x, note: "agree with the shop how it is made, and record it" })),
+        { label: "Edges", value: o.carbon ? "chamfer or sand every edge and hole, then seal the cut edges (thin CA or epoxy)" : "deburr every edge and hole", ...(o.carbon ? { note: "carbon edges fray and cut wires" } : {}) },
+        { label: "Marking", value: "the release version on each plate" },
+      ],
+    });
+  }
+  return { title: "Cut parts", order: 30, blocks };
+};
+
+export const testPlan: SectionFn = ({ project: p, unit }: SectionContext) => {
+  const plates = providerModules(p, unit, PROVIDER).filter((b) => b.process === "cut");
+  if (!plates.length) return undefined;
+  const rows = plates.flatMap((b) => {
+    const o = cutOrder(p, b);
+    const name = o.def.name ?? o.def.id;
+    return [
+      ...[...o.holes].map(([d]) => ({ check: `Hole size M${n(d)}: ${name}`, how: `Pin gauge Ø${n(d + 2 * o.clearance, 2)} mm`, pass: `every M${n(d)} hole takes the gauge; the screw passes without force` })),
+      { check: `Edges: ${name}`, how: "Visual and by touch", pass: o.carbon ? "edges chamfered or sanded and sealed; no fraying or delamination" : "no burrs" },
+      { check: `Edge distance: ${name}`, how: "Visual around every hole", pass: "no breakout or crack between a hole and the edge" },
+    ];
+  });
+  return {
+    title: "Cut parts",
+    order: 30,
+    blocks: [
+      { kind: "paragraph", text: "With the first-article inspection, before the plates are used: what the cut order asked for.", keep: true },
+      { kind: "table", columns: [{ key: "check", label: "Check" }, { key: "how", label: "How" }, { key: "pass", label: "Pass" }], rows },
+    ],
+  };
+};

package/ops/rebind.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OperationFn } from "@protoboardai/core";
+import { plateBinding, plateFiles, plateModules, sameVec, type FramesFile } from "../lib/params.ts";
+
+interface Signature {
+  area_mm2: number;
+  centroid: number[];
+  normal?: number[];
+}
+
+const vec = (v: number[]) => `[${v.map((n) => String(Number(n.toFixed(3)) + 0)).join(", ")}]`;
+const sig = (s: Signature) => `{ area_mm2: ${s.area_mm2}, centroid: ${vec(s.centroid)}${s.normal ? `, normal: ${vec(s.normal)}` : ""} }`;
+const parseVec = (s: string) => s.split(",").map((x) => Number(x.trim()));
+
+/**
+ * The part of a module source that holds this module's geometry: the
+ * `withGeometry(` call whose artifacts name the generated body. Several
+ * modules may share a file (frame and top plate), so re-binding is scoped to
+ * that call and never touches another module's literals.
+ */
+function geometryBlock(text: string, cadName: string): [number, number] | undefined {
+  const starts = [...text.matchAll(/withGeometry\(/g)].map((m) => m.index!);
+  const blocks = starts.map((s, k) => [s, starts[k + 1] ?? text.length] as [number, number]);
+  const hits = blocks.filter(([a, b]) => text.slice(a, b).includes(`name: "${cadName}"`));
+  if (hits.length === 1) return hits[0];
+  return blocks.length === 1 ? blocks[0] : undefined;
+}
+
+/**
+ * frame-cad-rebind: explicit re-binding after a reviewed change (the step
+ * `cad:extract` leaves to the user, tool-integrations §8). Copies the
+ * exported feature signatures (out/body.manifest.json) into the module's
+ * `feature("<id>", { … })` literals and the generated frame origins (the
+ * native frame-cad/frames.json) into `<id>: { frame: { origin: [...] … } }`,
+ * in the module's own source file. Every change is returned; nothing else in
+ * the file is touched.
+ */
+export const rebind: OperationFn = (ctx) => {
+  const p = ctx.project;
+  const only = ctx.inputs.module?.split(",").map((s) => s.trim()).filter(Boolean);
+  const targets = plateModules(p, only);
+  const blocked = targets.flatMap((t) => t.problems);
+  if (blocked.length) return { status: "failed", summary: blocked[0] };
+  const changes: { module: string; file: string; interface: string; what: "signature" | "frame origin"; from: string; to: string }[] = [];
+  const edited = new Map<string, string>();
+  let rebound = 0;
+  for (const { def } of targets) {
+    const binding = plateBinding(p, def.id);
+    const files = binding && plateFiles(binding);
+    const manifestFile = files && join(p.root, files.manifest);
+    const framesFile = files && join(p.root, files.frames);
+    if (!manifestFile || !framesFile || !existsSync(manifestFile) || !existsSync(framesFile)) {
+      if (only?.length) return { status: "failed", summary: `${def.id} has no generated and exported CAD${binding ? ` in ${binding.dir}` : " (no cad.config.ts)"}; run \`protoboard run cad:generate --module ${def.id}\` and cad:export first` };
+      continue;
+    }
+    const features = (JSON.parse(readFileSync(manifestFile, "utf8")) as { features: Record<string, Signature> }).features;
+    const frames = JSON.parse(readFileSync(framesFile, "utf8")) as FramesFile;
+    const file = p.definitions.get(def.id)!.origin.source.file;
+    let text = edited.get(file) ?? readFileSync(join(p.root, file), "utf8");
+    const block = geometryBlock(text, def.id);
+    if (!block) return { status: "failed", summary: `${file}: cannot find the withGeometry(...) call for ${def.id} (artifacts named "${def.id}"); re-bind by hand from ${files.manifest}` };
+    let body = text.slice(block[0], block[1]);
+    body = body.replace(/feature\("([^"]+)", (\{ area_mm2: [^}]*\})/g, (all, name: string, old: string) => {
+      const now = features[name];
+      if (!now) return all;
+      const next = sig(now);
+      const was = /area_mm2: ([\d.e+-]+), centroid: \[([^\]]*)\]/.exec(old);
+      if (was && Math.abs(Number(was[1]) - now.area_mm2) < 1e-6 && sameVec(parseVec(was[2]), now.centroid, 1e-6)) return all;
+      changes.push({ module: def.id, file, interface: name, what: "signature", from: old, to: next });
+      return `feature("${name}", ${next}`;
+    });
+    for (const [id, f] of Object.entries(frames)) {
+      const re = new RegExp(`(\\b${id}:\\s*\\{\\s*frame:\\s*\\{\\s*origin:\\s*)\\[([^\\]]*)\\]`);
+      body = body.replace(re, (all, head: string, old: string) => {
+        if (sameVec(parseVec(old), f.origin, 1e-6)) return all;
+        changes.push({ module: def.id, file, interface: id, what: "frame origin", from: `[${old}]`, to: vec(f.origin) });
+        return `${head}${vec(f.origin)}`;
+      });
+    }
+    text = text.slice(0, block[0]) + body + text.slice(block[1]);
+    edited.set(file, text);
+    rebound++;
+  }
+  for (const [file, text] of edited) {
+    if (changes.some((c) => c.file === file)) ctx.writeOutput(file, text, "re-bound geometry literals");
+  }
+  for (const c of changes) ctx.log(`${c.module}.${c.interface} ${c.what}: ${c.from} -> ${c.to}`);
+  return {
+    status: "succeeded",
+    summary: changes.length ? `${changes.length} literal(s) re-bound in ${[...new Set(changes.map((c) => c.file))].join(", ")}` : `${rebound} module(s) checked; nothing to re-bind`,
+    data: { changes },
+  };
+};