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

package/lib/artifacts.ts

@@ -0,0 +1,185 @@
+/**
+ * The files the build123d generators write, as UHD artifacts
+ * (`@protoboardai/ext-frame-cad/artifacts`). A module's source declares them
+ * with UHD's pure helpers (`withGeometry`, `feature`, `own`, `procedural`);
+ * the layout itself is this extension's knowledge, so it lives here, not in
+ * UHD (PB-801).
+ *
+ * The common layout, per generated body:
+ *   <name>.step            body with each interface as a named sub-shape (D1)
+ *   <name>.glb             the same, tessellated, for viewers
+ *   <name>.manifest.json   feature name -> signature (area, centroid, normal)
+ *   interfaces/<id>.glb    one artifact per interface (D2)
+ * and nothing for D3 (procedural), which viewers derive from parameters.
+ *
+ * Plate modules use the `cad` capability's layout instead (PB-822,
+ * tool-integrations §4): the same bodies as standard outputs in
+ * `<dir>/out/` (body.step, body.glb, body.manifest.json, body.dxf,
+ * interfaces/<id>.glb) and the native design in `<dir>/frame-cad/`.
+ */
+import type { ArtifactDef } from "@deltarobotics/uhd";
+
+export const FRAME_CAD_GENERATOR = "@protoboardai/ext-frame-cad py/frame_cad.py";
+export const HARDWARE_CAD_GENERATOR = "@protoboardai/ext-frame-cad py/hardware_cad.py";
+
+export interface CadOptions {
+  /** Project-relative directory holding the generated files. */
+  dir: string;
+  /** Base name of the generated body files. */
+  name: string;
+  /**
+   * The generator: a project-relative script (recorded as the source artifact's
+   * file), or a package-qualified name such as FRAME_CAD_GENERATOR (recorded
+   * as provenance only, with `generatorNote`).
+   */
+  generator: string;
+  tool: string;
+  /** Interfaces that have a per-interface artifact (D2). */
+  interfaces?: string[];
+  /** Extra id prefix when a module has several bodies (e.g. "camera"). */
+  prefix?: string;
+  /** Description of a generator that is not a project file (it ships in a package). */
+  generatorNote?: string;
+}
+
+const inPackage = (generator: string) => generator.startsWith("@") || generator.includes(" ");
+
+/** Body file paths of one generated body. */
+interface BodyFiles {
+  step: string;
+  glb: string;
+  manifest: string;
+  iface: (id: string) => string;
+}
+
+/** Source, STEP body, GLB body, manifest and per-interface GLBs for one generated body. */
+export function cadArtifacts(o: CadOptions): ArtifactDef[] {
+  return bodyArtifacts(o, { step: `${o.dir}/${o.name}.step`, glb: `${o.dir}/${o.name}.glb`, manifest: `${o.dir}/${o.name}.manifest.json`, iface: (id) => `${o.dir}/interfaces/${id}.glb` });
+}
+
+function bodyArtifacts(o: Omit<CadOptions, "dir">, f: BodyFiles): ArtifactDef[] {
+  const p = o.prefix ? `${o.prefix}_` : "";
+  const provenance = { generatedFrom: `cad_${p}source`, tool: o.tool };
+  const packaged = inPackage(o.generator);
+  return [
+    {
+      id: `cad_${p}source`,
+      name: `${o.name} generator`,
+      type: "cad",
+      role: "source",
+      format: o.generator.split(".").pop(),
+      ...(packaged ? { description: o.generatorNote ?? `Generated by ${o.generator}.` } : { filePath: o.generator }),
+    },
+    {
+      id: `cad_${p}step`,
+      name: `${o.name} (STEP)`,
+      type: "3d_model",
+      role: "body",
+      format: "step",
+      units: "mm",
+      filePath: f.step,
+      provenance,
+      description: "Body plus one named sub-shape per interface feature; features and signatures in the manifest.",
+    },
+    {
+      id: `cad_${p}glb`,
+      name: `${o.name} (GLB)`,
+      type: "3d_model",
+      role: "body",
+      format: "glb",
+      units: "m",
+      filePath: f.glb,
+      provenance: { ...provenance, generatedFrom: `cad_${p}step` },
+      description: "Viewer mesh of the STEP body (glTF metres, Y-up).",
+    },
+    {
+      id: `cad_${p}manifest`,
+      name: `${o.name} feature manifest`,
+      type: "cad",
+      role: "source",
+      format: "json",
+      filePath: f.manifest,
+      provenance: { ...provenance, generatedFrom: `cad_${p}step` },
+    },
+    ...(o.interfaces ?? []).map(
+      (id): ArtifactDef => ({
+        id: `cad_if_${id}`,
+        name: `${id} geometry`,
+        type: "3d_model",
+        role: "interface",
+        interfaceId: id,
+        format: "glb",
+        units: "m",
+        filePath: f.iface(id),
+        provenance: { ...provenance, generatedFrom: `cad_${p}step` },
+      }),
+    ),
+  ];
+}
+
+/** The native folder of this provider in a module's provider directory (`native` in the manifest). */
+export const FRAME_CAD_NATIVE = "frame-cad";
+
+/**
+ * Everything the `cad` capability writes for a plate module whose
+ * `cad.config.ts` is in `dir` (`protoboard run cad:generate` and
+ * `cad:export`, or the `frame-cad` alias): the standard outputs in
+ * `<dir>/out/` (body, manifest, per-interface GLBs, the cutting DXF) and the
+ * native design in `<dir>/frame-cad/` (the parameters the generator ran on
+ * and the frames it generated).
+ */
+export function plateCadArtifacts(o: { dir: string; name: string; interfaces: string[]; tool?: string }): ArtifactDef[] {
+  const tool = o.tool ?? "build123d 0.13.0";
+  const out = `${o.dir}/out`;
+  const native = `${o.dir}/${FRAME_CAD_NATIVE}`;
+  return [
+    ...bodyArtifacts(
+      {
+        name: o.name,
+        generator: FRAME_CAD_GENERATOR,
+        tool,
+        interfaces: o.interfaces,
+        generatorNote: `Generated by ${FRAME_CAD_GENERATOR} from ${native}/params.json (protoboard run cad:generate, then cad:export).`,
+      },
+      { step: `${out}/body.step`, glb: `${out}/body.glb`, manifest: `${out}/body.manifest.json`, iface: (id) => `${out}/interfaces/${id}.glb` },
+    ),
+    { id: "cad_params", name: `${o.name} generator parameters`, type: "cad", role: "source", format: "json", filePath: `${native}/params.json`, description: "Bolt patterns, frames and design values read from this module's interfaces and its cad.config.ts constraints." },
+    { id: "cad_frames", name: `${o.name} generated frames`, type: "cad", role: "source", format: "json", filePath: `${native}/frames.json`, provenance: { generatedFrom: "cad_source", tool } },
+    {
+      id: "cad_dxf",
+      name: `${o.name} (DXF)`,
+      type: "cad",
+      role: "drawing",
+      format: "dxf",
+      units: "mm",
+      filePath: `${out}/body.dxf`,
+      provenance: { generatedFrom: "cad_step", tool },
+      description: "Manufacturing profiles for CNC routing: the plate outline with every hole (layer plate) and any side-clamp plates (layer clamp_<interface>).",
+    },
+  ];
+}
+
+/**
+ * Everything the `cad` capability writes for a fastener module (screw, nut,
+ * spacer, standoff) whose `cad.config.ts` is in `dir` (`protoboard run
+ * cad:generate` and `cad:export`, or the `hardware-cad` alias): its nominal
+ * body as standard outputs in `<dir>/out/` and the parameters it was built
+ * from in `<dir>/frame-cad/params.json`.
+ */
+export function hardwareCadArtifacts(o: { dir: string; name: string; tool?: string }): ArtifactDef[] {
+  const tool = o.tool ?? "build123d 0.13.0";
+  const out = `${o.dir}/out`;
+  const native = `${o.dir}/${FRAME_CAD_NATIVE}`;
+  return [
+    ...bodyArtifacts(
+      {
+        name: o.name,
+        generator: HARDWARE_CAD_GENERATOR,
+        tool,
+        generatorNote: `Generated by ${HARDWARE_CAD_GENERATOR} from ${native}/params.json (protoboard run cad:generate, then cad:export; or hardware-cad).`,
+      },
+      { step: `${out}/body.step`, glb: `${out}/body.glb`, manifest: `${out}/body.manifest.json`, iface: (id) => `${out}/interfaces/${id}.glb` },
+    ),
+    { id: "cad_params", name: `${o.name} generator parameters`, type: "cad", role: "source", format: "json", filePath: `${native}/params.json`, description: "Kind, diameter, length and head or outer size read from this module." },
+  ];
+}

package/lib/hardware-cad.ts

@@ -0,0 +1,127 @@
+/**
+ * Mounting hardware as a `cad` provider (tool-integrations §2–§4, PB-836):
+ * a local fastener module (a screw, nut, standoff or spacer) whose
+ * `cad.config.ts` names @protoboardai/ext-frame-cad gets its nominal body the
+ * same way a plate does.
+ *
+ *   generate  module sizes → native design <dir>/frame-cad/params.json
+ *   export    params.json → build123d (py/hardware_cad.py) → standard
+ *             outputs <dir>/out/body.step, body.glb, body.manifest.json
+ *   extract   the module's artifacts that exist (no interface frames: a
+ *             fastener's position comes from the fastener stack)
+ *   check     params still what the module says; out/ exported from them
+ *
+ * `protoboard run hardware-cad` is the alias of generate then export for
+ * every bound hardware module, as `frame-cad` is for plates.
+ */
+import { existsSync, mkdirSync, readFileSync, 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 ProjectDiagnostic } from "@protoboardai/core";
+import { hardwareCadArtifacts } from "./artifacts.ts";
+import { buildHardwareParams, type HardwareParams } from "./hardware.ts";
+import { python, type Writer } from "./plate.ts";
+import { runAsync } from "./run.ts";
+
+export const HARDWARE_GENERATOR = fileURLToPath(new URL("../py/hardware_cad.py", import.meta.url));
+
+/** A hardware module and its provider directory. */
+export interface HardwareTarget {
+  def: ModuleDef;
+  binding: Pick<CapabilityBinding, "dir" | "native" | "out" | "config">;
+}
+
+/** Native params and the standard outputs' manifest of a bound hardware module. */
+export function hardwareFiles(b: Pick<CapabilityBinding, "native" | "out">) {
+  return { params: `${b.native}/params.json`, manifest: `${b.out}/body.manifest.json` };
+}
+
+type Outcome<T> = { ok: true; value: T } | { ok: false; summary: string; problems?: string[] };
+
+/** generate: the generator parameters from the module's sizes, into the native folder. */
+export function generateHardware(ctx: Writer, t: HardwareTarget): Outcome<{ module: string; kind: string; native: string; params: HardwareParams }> {
+  const { def, binding: b } = t;
+  const { params, problems } = buildHardwareParams(def, def.id);
+  if (!params || problems.length) return { ok: false, summary: problems[0], problems };
+  const files = hardwareFiles(b);
+  ctx.writeOutput(files.params, stableStringify(params), `${def.id}: generator parameters from its sizes`);
+  ctx.log(`${def.id}: ${params.part.kind}; native design in ${b.native}`);
+  return { ok: true, value: { module: def.id, kind: params.part.kind, native: b.native!, params } };
+}
+
+/** export: build the nominal body from the native params and write the standard outputs. */
+export async function exportHardware(ctx: Writer, t: HardwareTarget): Promise<Outcome<{ module: string; out: string; volume_mm3: number; previousVolume_mm3: number | null; toolVersion: string }>> {
+  const p = ctx.project;
+  const { def, binding: b } = t;
+  const files = hardwareFiles(b);
+  if (!existsSync(join(p.root, files.params))) return { ok: false, 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 HardwareParams;
+  const before = readJson<{ volume_mm3?: number }>(join(p.root, files.manifest))?.volume_mm3 ?? null;
+  const scratch = join(p.root, ".protoboard", "cache", "hardware-cad", params.name);
+  rmSync(scratch, { recursive: true, force: true });
+  mkdirSync(scratch, { recursive: true });
+  const run = await runAsync(python(), [HARDWARE_GENERATOR, join(p.root, files.params), scratch], { timeout: 300000, env: { ...process.env, PYTHONHASHSEED: "0" } });
+  if (!run.ok) {
+    rmSync(scratch, { recursive: true, force: true });
+    return { ok: false, summary: `${def.id}: generator failed: ${run.error}` };
+  }
+  const summary = JSON.parse(run.stdout.trim().split("\n").pop()!) as { toolVersion: string; volume_mm3: number };
+  const n = params.name;
+  ctx.writeOutput(`${b.out}/body.step`, readFileSync(join(scratch, `${n}.step`)), `${def.id}: nominal body`);
+  ctx.writeOutput(`${b.out}/body.glb`, readFileSync(join(scratch, `${n}.glb`)), `${def.id}: viewer mesh`);
+  const manifest = JSON.parse(readFileSync(join(scratch, `${n}.manifest.json`), "utf8")) as Record<string, unknown>;
+  const standard = { ...manifest, artifact: "body", params: `../${b.native!.split("/").pop()}/params.json`, exportedFrom: { file: files.params, digest: sha256(paramsBytes) } };
+  ctx.writeOutput(files.manifest, JSON.stringify(standard, null, 2) + "\n", `${def.id}: geometry manifest (volume)`);
+  rmSync(scratch, { recursive: true, force: true });
+  ctx.log(`${def.id}: ${summary.volume_mm3} mm³ in ${b.out}`);
+  return { ok: true, value: { module: def.id, out: b.out, volume_mm3: summary.volume_mm3, previousVolume_mm3: before, toolVersion: summary.toolVersion } };
+}
+
+const readJson = <T>(file: string): T | undefined => (existsSync(file) ? (JSON.parse(readFileSync(file, "utf8")) as T) : undefined);
+
+/** extract: no frames (a fastener is placed by its fastener stack), and the module's artifacts that exist. */
+export function extractHardware(root: string, t: HardwareTarget): Outcome<{ frames: Record<string, never>; artifacts: ArtifactDef[] }> {
+  const { def, binding: b } = t;
+  if (!existsSync(join(root, hardwareFiles(b).params))) return { ok: false, summary: `${def.id} has no native design (${hardwareFiles(b).params}); run \`protoboard run cad:generate --module ${def.id}\` first` };
+  const artifacts = hardwareCadArtifacts({ dir: b.dir, name: def.id }).filter((a) => a.filePath && existsSync(join(root, a.filePath)));
+  return { ok: true, value: { frames: {}, artifacts } };
+}
+
+/**
+ * check: the params the body was made from are still the module's sizes
+ * (otherwise the body, and the mass computed from its volume, are stale),
+ * and out/ was exported from those params.
+ */
+export function hardwareDiagnostics(root: string, t: HardwareTarget, source: ProjectDiagnostic["source"]): Omit<ProjectDiagnostic, "validator">[] {
+  const { def, binding: b } = t;
+  const files = hardwareFiles(b);
+  const entity = { kind: "definition" as const, id: def.id };
+  const out: Omit<ProjectDiagnostic, "validator">[] = [];
+  const { params, problems } = buildHardwareParams(def, def.id);
+  if (!params) {
+    out.push({ code: "HARDWARE_CAD_PARAMS", severity: "error", entity, message: `${def.id}: ${problems.join("; ")}`, source });
+    return out;
+  }
+  const paramsFile = join(root, files.params);
+  if (!existsSync(paramsFile)) {
+    out.push({ code: "HARDWARE_CAD_NOT_GENERATED", severity: "info", entity, message: `${def.id} has no native design (${files.params}); run \`protoboard run cad:generate --module ${def.id}\`, then cad:export`, source });
+    return out;
+  }
+  const bytes = readFileSync(paramsFile);
+  if (stableStringify(params) !== stableStringify(JSON.parse(bytes.toString("utf8")))) {
+    out.push({
+      code: "HARDWARE_CAD_STALE",
+      severity: "warning",
+      entity,
+      message: `${def.id}: its sizes changed since its CAD was generated (${files.params}); run \`protoboard run cad:generate --module ${def.id}\`, then cad:export (or \`protoboard run hardware-cad --input module=${def.id}\`)`,
+      source,
+    });
+  }
+  const manifest = readJson<{ exportedFrom?: { digest?: string } }>(join(root, files.manifest));
+  if (manifest && manifest.exportedFrom?.digest !== sha256(bytes)) {
+    out.push({ code: "HARDWARE_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/hardware.ts

@@ -0,0 +1,100 @@
+/**
+ * UHD fastener module → hardware-cad parameters.
+ *
+ * A hardware module is a local definition tagged `fastener` and one of
+ * `screw`, `nut`, `standoff`, `spacer` (the tags UHD's fastener stacks use).
+ * It is designed through the `cad` capability (lib/hardware-cad.ts) when a
+ * `cad.config.ts` in its folder names this provider. Its thread or bore interface states `fastener_diameter` and `length`; its
+ * mechanical metadata states the rest: `head_diameter_mm` and
+ * `head_height_mm` for a screw, `outer_mm` (across flats, or the tube
+ * diameter) for the others, and `bore_mm` when the maker states the bore of
+ * a nut, standoff or spacer (otherwise the generator's nominal bore). Nothing
+ * else is read, and nothing is assumed: a missing size is a problem, not a
+ * default.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { CapabilityBinding, Project } from "@protoboardai/core";
+import { mechanical } from "./params.ts";
+
+export const HARDWARE_PARAMS_SCHEMA = "protoboard.hardware-cad.params/v0";
+
+export const HARDWARE_KINDS = ["screw", "nut", "standoff", "spacer"] as const;
+export type HardwareKind = (typeof HARDWARE_KINDS)[number];
+
+export interface HardwareParams {
+  schema: typeof HARDWARE_PARAMS_SCHEMA;
+  module: string;
+  name: string;
+  part: {
+    kind: HardwareKind;
+    diameter: number;
+    length: number;
+    head_diameter: number | null;
+    head_height: number | null;
+    outer: number | null;
+    /** The bore the maker states (nut, standoff, spacer); absent: the generator's nominal bore. */
+    bore?: number;
+  };
+}
+
+const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
+
+export function hardwareKind(def: ModuleDef): HardwareKind | undefined {
+  const tags = def.tags ?? [];
+  return tags.includes("fastener") ? HARDWARE_KINDS.find((k) => tags.includes(k)) : undefined;
+}
+
+/** Local, used definitions that are hardware modules (optionally only the named ones). */
+export function hardwareModules(p: Project, only?: string[]): { def: ModuleDef; problems: string[] }[] {
+  if (only?.length) {
+    return only.map((id) => {
+      const rec = p.definitions.get(id);
+      if (!rec) return { def: { id, interfaces: [] } as unknown as ModuleDef, problems: [`no definition "${id}" in the project`] };
+      if (rec.origin.kind !== "local") return { def: rec.def, problems: [`${id} is a ${rec.origin.kind} definition; its CAD comes with it (hardware-cad generates local modules only)`] };
+      if (!hardwareKind(rec.def)) return { def: rec.def, problems: [`${id} is not tagged fastener plus one of ${HARDWARE_KINDS.join(", ")}`] };
+      return { def: rec.def, problems: [] };
+    });
+  }
+  const used = new Set(p.instances.map((i) => i.definition));
+  return [...p.definitions.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .filter(([id, rec]) => used.has(id) && rec.origin.kind === "local" && hardwareKind(rec.def))
+    .map(([, rec]) => ({ def: rec.def, problems: [] }));
+}
+
+/** The module's cad binding to this provider (its `cad.config.ts`), when it has a usable one. */
+export function hardwareBinding(p: Project, id: string): CapabilityBinding | undefined {
+  return p.capabilities.find((b) => b.capability === "cad" && b.module === id && b.provider === "@protoboardai/ext-frame-cad" && !b.problem && b.native);
+}
+
+export function buildHardwareParams(def: ModuleDef, name: string): { params?: HardwareParams; problems: string[] } {
+  const kind = hardwareKind(def);
+  if (!kind) return { problems: [`${def.id}: not a hardware module (tags fastener plus ${HARDWARE_KINDS.join("|")})`] };
+  const param = (id: string) =>
+    def.interfaces
+      .map((i) => i.parameters?.find((x) => x.id === id))
+      .find((x) => x?.value !== undefined)?.value;
+  const meta = mechanical(def);
+  const diameter = num(param("fastener_diameter"));
+  const length = num(param("length"));
+  const headDiameter = num(meta.head_diameter_mm);
+  const headHeight = num(meta.head_height_mm);
+  const outer = num(meta.outer_mm);
+  const bore = num(meta.bore_mm);
+  const problems: string[] = [];
+  if (diameter === undefined) problems.push(`${def.id}: no interface states fastener_diameter`);
+  if (length === undefined) problems.push(`${def.id}: no interface states length`);
+  if (kind === "screw" && (headDiameter === undefined || headHeight === undefined)) problems.push(`${def.id}: a screw needs mechanical metadata head_diameter_mm and head_height_mm`);
+  if (kind !== "screw" && outer === undefined) problems.push(`${def.id}: a ${kind} needs mechanical metadata outer_mm`);
+  if (bore !== undefined && (kind === "screw" || bore >= outer!)) problems.push(`${def.id}: bore_mm ${bore} ${kind === "screw" ? "does not apply to a screw" : `is not inside outer_mm ${outer}`}`);
+  if (problems.length) return { problems };
+  return {
+    problems,
+    params: {
+      schema: HARDWARE_PARAMS_SCHEMA,
+      module: def.id,
+      name,
+      part: { kind, diameter: diameter!, length: length!, head_diameter: headDiameter ?? null, head_height: headHeight ?? null, outer: outer ?? null, ...(bore !== undefined ? { bore } : {}) },
+    },
+  };
+}

package/lib/params.ts

@@ -0,0 +1,255 @@
+/**
+ * UHD module → frame-cad parameters.
+ *
+ * A "plate module" is a local custom structure whose mechanical domain
+ * metadata states `plate_thickness_mm`. Its bolt-pattern interfaces with
+ * frames are the whole input: where each pattern sits (frame origin and axes,
+ * module coordinates, mm, Z up, origin on the plate underside) and what it is
+ * (shape, spacing, hole count, fastener). Optional design values are the
+ * constraints in the module's `cad.config.ts` (see DEFAULTS); they are this
+ * provider's, so they stay out of the UHD module. Nothing about a particular
+ * vehicle is hard-coded; the defaults are the reference quadcopter's design
+ * values.
+ */
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+import type { CapabilityBinding, Project } from "@protoboardai/core";
+
+export const PARAMS_SCHEMA = "protoboard.frame-cad.params/v0";
+
+type Vec3 = [number, number, number];
+
+export type Placement = "holes_top" | "holes_bottom" | "pad" | "clamp";
+
+export interface PlateInterface {
+  id: string;
+  shape: "square" | "rectangle" | "circle";
+  spacing: number;
+  spacing_y: number | null;
+  hole_count: number;
+  fastener_d: number;
+  placement: Placement;
+  /** Frame origin XY as declared (module coordinates, mm); Z follows from the placement and height. */
+  origin: [number, number];
+  normal: Vec3;
+  x_axis: Vec3;
+  symmetry: number | null;
+  /** pad: pad height above the plate top; clamp: frame origin height above the plate top. */
+  height: number;
+  /** World XY hole centres for plate patterns (UHD boltPatternHoles convention). */
+  holes: [number, number][];
+}
+
+export interface PlateParams {
+  schema: typeof PARAMS_SCHEMA;
+  module: string;
+  name: string;
+  plate: {
+    thickness: number;
+    margin: number;
+    corner_radius: number;
+    arm_width: number;
+    arm_slot_width: number;
+    hub_extra: number;
+    pad_margin: number;
+    pad_center_relief: number;
+    hole_clearance: number;
+    clamp_wall: number;
+    clamp_margin: number;
+    outline: { x: [number, number]; y: [number, number] } | null;
+    slots: { center: [number, number]; size: [number, number] }[];
+  };
+  interfaces: PlateInterface[];
+}
+
+/**
+ * Design defaults (mm) and the `cad.config.ts` constraints that override them.
+ * Holes are fastener diameter + 2 × hole_clearance (M3 → Ø3.2).
+ */
+export const DEFAULTS = {
+  margin: 3, // outline margin around core holes and clamps          (margin_mm)
+  corner_radius: 1.5, // vertical edge fillet                          (corner_radius_mm)
+  arm_width: 14, // arm to each raised pad                              (arm_width_mm)
+  arm_slot_width: 5, // lightening slot down each arm; 0 = none         (arm_slot_width_mm)
+  hub_extra: 1, // hub disc radius beyond the pad                       (hub_extra_mm)
+  pad_margin: 3, // pad radius beyond the pattern                       (pad_margin_mm)
+  pad_height: 0.5, // raised pad: its own planar mating face            (pad_height_mm)
+  pad_center_relief: 3.5, // centre hole in circle pads (shaft/circlip)  (pad_center_relief_mm)
+  hole_clearance: 0.1, // radial clearance over the fastener            (hole_clearance_mm)
+  clamp_wall: 2, // side-plate thickness                                (clamp_wall_mm)
+  clamp_margin: 4, // side-plate width = spacing + margin; top = origin + spacing/2 + margin (clamp_margin_mm)
+} as const;
+
+const num = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+
+export function mechanical(def: ModuleDef): Record<string, unknown> {
+  return ((def.domains ?? []).find((d) => d.domain === "mechanical")?.metadata ?? {}) as Record<string, unknown>;
+}
+
+export const isPlateModule = (def: ModuleDef) => num(mechanical(def).plate_thickness_mm) !== undefined;
+
+/** Local, used definitions that are plate modules (optionally only the named ones). */
+export function plateModules(p: Project, only?: string[]): { def: ModuleDef; problems: string[] }[] {
+  const used = new Set(p.instances.map((i) => i.definition));
+  const out: { def: ModuleDef; problems: string[] }[] = [];
+  if (only?.length) {
+    for (const id of only) {
+      const rec = p.definitions.get(id);
+      if (!rec) out.push({ def: { id, interfaces: [] } as unknown as ModuleDef, problems: [`no definition "${id}" in the project`] });
+      else if (rec.origin.kind !== "local") out.push({ def: rec.def, problems: [`${id} is a ${rec.origin.kind} definition; frame-cad generates local custom modules only (derive a local variant)`] });
+      else if (!isPlateModule(rec.def)) out.push({ def: rec.def, problems: [`${id} has no mechanical metadata plate_thickness_mm, so it is not a plate module`] });
+      else out.push({ def: rec.def, problems: [] });
+    }
+    return out;
+  }
+  for (const [id, rec] of [...p.definitions.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    if (used.has(id) && rec.origin.kind === "local" && isPlateModule(rec.def)) out.push({ def: rec.def, problems: [] });
+  }
+  return out;
+}
+
+export const PROVIDER = "@protoboardai/ext-frame-cad";
+
+/** The module's cad binding to this provider (its `cad.config.ts`), when it has a usable one. */
+export function plateBinding(p: Project, id: string): CapabilityBinding | undefined {
+  return p.capabilities.find((b) => b.capability === "cad" && b.module === id && b.provider === PROVIDER && !b.problem && b.native);
+}
+
+/**
+ * Where a bound plate module's files are (tool-integrations §4): the native
+ * design in `<dir>/frame-cad/` (params.json, frames.json), the standard
+ * outputs in `<dir>/out/` (body.step, body.glb, body.manifest.json, body.dxf,
+ * interfaces/<id>.glb).
+ */
+export function plateFiles(b: Pick<CapabilityBinding, "native" | "out">) {
+  return { params: `${b.native}/params.json`, frames: `${b.native}/frames.json`, manifest: `${b.out}/body.manifest.json` };
+}
+
+const param = (i: InterfaceDef, id: string) => {
+  const v = i.parameters?.find((x) => x.id === id);
+  return v?.value ?? (v?.range ? (v.range[0] + v.range[1]) / 2 : undefined);
+};
+const norm = (v: Vec3): Vec3 => {
+  const l = Math.hypot(...v);
+  return [v[0] / l, v[1] / l, v[2] / l];
+};
+const cross = (a: Vec3, b: Vec3): Vec3 => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const r6 = (n: number) => Math.round(n * 1e6) / 1e6 + 0;
+
+/** Local hole positions of a pattern (same convention as UHD boltPatternHoles). */
+function localHoles(shape: string, spacing: number, sy: number, count: number): [number, number][] {
+  if (shape === "circle") {
+    return Array.from({ length: count }, (_, k) => {
+      const a = (2 * Math.PI * k) / count;
+      return [(Math.cos(a) * spacing) / 2, (Math.sin(a) * spacing) / 2];
+    });
+  }
+  return [
+    [-spacing / 2, -sy / 2],
+    [spacing / 2, -sy / 2],
+    [spacing / 2, sy / 2],
+    [-spacing / 2, sy / 2],
+  ];
+}
+
+/** Generator parameters from the module's interfaces and its config's constraints (design values). */
+export function buildParams(def: ModuleDef, name: string, constraints: Record<string, unknown> = {}): { params?: PlateParams; problems: string[] } {
+  const meta = mechanical(def);
+  const fc = constraints;
+  const T = num(meta.plate_thickness_mm);
+  const problems: string[] = [];
+  if (T === undefined || T <= 0) return { problems: [`${def.id}: mechanical metadata plate_thickness_mm must be a positive number`] };
+  const opt = (key: keyof typeof DEFAULTS) => num(fc[`${key}_mm`]) ?? DEFAULTS[key];
+  const padIds = Array.isArray(fc.pads) ? (fc.pads as string[]) : undefined;
+  const clampHeight = num(fc.clamp_height_mm);
+
+  const interfaces: PlateInterface[] = [];
+  for (const i of def.interfaces) {
+    const trait = i.traits?.find((t) => t.type === "bolt_pattern");
+    const isPattern = trait || i.protocols.some((p) => p.type === "bolt_pattern");
+    if (!isPattern) continue;
+    const frame = i.geometry?.frame;
+    if (!frame) {
+      problems.push(`${def.id}.${i.id}: bolt pattern has no frame, so it cannot be placed (add geometry.frame)`);
+      continue;
+    }
+    const shape = (trait?.params?.shape as PlateInterface["shape"]) ?? "square";
+    const spacing = param(i, "hole_spacing");
+    const d = param(i, "fastener_diameter");
+    if (spacing === undefined || d === undefined) {
+      problems.push(`${def.id}.${i.id}: needs hole_spacing and fastener_diameter parameters`);
+      continue;
+    }
+    const sy = param(i, "hole_spacing_y") ?? null;
+    const count = param(i, "hole_count") ?? 4;
+    const n = norm(frame.normal);
+    let x = norm(frame.xAxis ?? (Math.abs(n[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0]));
+    const y = cross(n, x);
+    x = cross(y, n);
+    const o = frame.origin;
+    let placement: Placement;
+    let height = 0;
+    if (Math.abs(n[2]) > 0.999) {
+      const pad = padIds ? padIds.includes(i.id) : shape === "circle" && n[2] > 0;
+      if (pad) {
+        placement = "pad";
+        height = num(fc.pad_height_mm) ?? DEFAULTS.pad_height;
+      } else placement = n[2] > 0 ? "holes_top" : "holes_bottom";
+    } else if (Math.abs(n[2]) < 1e-3 && Math.abs(x[2]) < 1e-3) {
+      placement = "clamp";
+      height = clampHeight ?? o[2] - T;
+      if (!(sy && sy > 0)) problems.push(`${def.id}.${i.id}: a side clamp (horizontal normal) needs hole_spacing_y, the clamped width`);
+    } else {
+      problems.push(`${def.id}.${i.id}: frame normal [${n.map((v) => v.toFixed(2))}] is neither vertical nor horizontal; frame-cad generates plates and vertical side clamps only`);
+      continue;
+    }
+    const holes = placement === "clamp" ? [] : localHoles(shape, spacing, sy ?? spacing, count).map(([hx, hy]) => [r6(o[0] + hx * x[0] + hy * y[0]), r6(o[1] + hx * x[1] + hy * y[1])] as [number, number]);
+    interfaces.push({
+      id: i.id,
+      shape,
+      spacing,
+      spacing_y: sy,
+      hole_count: count,
+      fastener_d: d,
+      placement,
+      origin: [o[0], o[1]],
+      normal: [r6(n[0]), r6(n[1]), r6(n[2])],
+      x_axis: [r6(x[0]), r6(x[1]), r6(x[2])],
+      symmetry: frame.symmetryDeg ?? null,
+      height: r6(height),
+      holes,
+    });
+  }
+  if (!interfaces.length) problems.push(`${def.id}: no bolt-pattern interfaces with frames; nothing to generate`);
+  const outline = fc.outline_mm as { x: [number, number]; y: [number, number] } | undefined;
+  const slots = (fc.slots_mm ?? []) as { center: [number, number]; size: [number, number] }[];
+  return {
+    problems,
+    params: {
+      schema: PARAMS_SCHEMA,
+      module: def.id,
+      name,
+      plate: {
+        thickness: T,
+        margin: opt("margin"),
+        corner_radius: opt("corner_radius"),
+        arm_width: opt("arm_width"),
+        arm_slot_width: opt("arm_slot_width"),
+        hub_extra: opt("hub_extra"),
+        pad_margin: opt("pad_margin"),
+        pad_center_relief: opt("pad_center_relief"),
+        hole_clearance: opt("hole_clearance"),
+        clamp_wall: opt("clamp_wall"),
+        clamp_margin: opt("clamp_margin"),
+        outline: outline ?? null,
+        slots,
+      },
+      interfaces,
+    },
+  };
+}
+
+/** Frames as the generator writes them: interface id → frame. */
+export type FramesFile = Record<string, { origin: Vec3; normal: Vec3; xAxis?: Vec3; symmetryDeg?: number }>;
+
+export const sameVec = (a: number[] | undefined, b: number[] | undefined, tol = 0.01) =>
+  !!a && !!b && a.length === b.length && a.every((v, k) => Math.abs(v - b[k]) <= tol);