@protoboardai/ext-tscircuit 0.0.0-stage → 0.2.1

package/lib/layout.ts

@@ -0,0 +1,236 @@
+/**
+ * Reading a built board (circuit JSON) back in UHD's terms: where each
+ * component instance sits, the frames of its mating faces, the outline and
+ * holes, and the nets as the copper actually joins them.
+ *
+ * Board frame throughout: mm, +X right and +Y up in the top view (tscircuit's
+ * PCB coordinates), +Z out of the top copper, z = 0 on the board's mid-plane
+ * (tscircuit's own 3D convention), so the top surface is z = +thickness/2.
+ */
+import type { GeometryFrame } from "@deltarobotics/uhd";
+import { getFullConnectivityMapFromCircuitJson } from "circuit-json-to-connectivity-map";
+import type { Side, Vec2 } from "./config.ts";
+import type { CircuitElement } from "./runtime.ts";
+import type { NameMap } from "./source.ts";
+
+type Vec3 = [number, number, number];
+const r4 = (v: number) => Math.round(v * 1e4) / 1e4;
+const v3 = (x: number, y: number, z: number): Vec3 => [r4(x), r4(y), r4(z)];
+
+/** tscircuit insertion directions, already rotated into the board frame. */
+const DIRECTION: Record<string, Vec3> = {
+  from_left: [-1, 0, 0],
+  from_right: [1, 0, 0],
+  from_top: [0, 1, 0],
+  from_bottom: [0, -1, 0],
+  from_above: [0, 0, 1],
+  from_below: [0, 0, -1],
+};
+
+export interface PlacedComponent {
+  instance: string;
+  /** tscircuit component name. */
+  name: string;
+  part: string;
+  /** Footprint origin as placed (pcbX/pcbY). */
+  origin: Vec2;
+  /** Pad and courtyard bounding-box centre (what pick-and-place machines take). */
+  center: Vec2;
+  rotation_deg: number;
+  side: Side;
+  /** Bounding box of pads and courtyard, rotated (board-aligned). */
+  size: Vec2;
+  /** The face that meets a mating part: the connector mouth, else the top (or bottom) of the body at its centre. */
+  frame: GeometryFrame & { source: "insertion_direction" | "inferred_from_cable_insertion_center" | "body_top" };
+}
+
+export interface BoardGeometry {
+  thickness_mm: number;
+  layers: number;
+  outline: Vec2[];
+  holes: { name: string; at: Vec2; diameter_mm: number }[];
+  keepouts: { center: Vec2; shape: string; width?: number; height?: number; radius?: number; layers: string[] }[];
+  components: PlacedComponent[];
+  routing: { traces: number; vias: number; wire_mm: number };
+  toolVersion?: string;
+}
+
+export const ofType = (cj: CircuitElement[], t: string) => cj.filter((e) => e.type === t);
+
+/** Placement, frames, outline and holes of a built board. */
+export function boardGeometry(cj: CircuitElement[], map: NameMap): BoardGeometry {
+  const board = ofType(cj, "pcb_board")[0];
+  if (!board) throw new Error("circuit JSON has no pcb_board");
+  const half = board.thickness / 2;
+  const sources = new Map(ofType(cj, "source_component").map((s) => [s.source_component_id, s]));
+  const outline: Vec2[] = board.outline
+    ? board.outline.map((p: { x: number; y: number }) => [r4(p.x), r4(p.y)] as Vec2)
+    : [
+        [board.center.x - board.width / 2, board.center.y - board.height / 2],
+        [board.center.x + board.width / 2, board.center.y - board.height / 2],
+        [board.center.x + board.width / 2, board.center.y + board.height / 2],
+        [board.center.x - board.width / 2, board.center.y + board.height / 2],
+      ];
+  const components: PlacedComponent[] = [];
+  for (const pc of ofType(cj, "pcb_component")) {
+    const name = sources.get(pc.source_component_id)?.name as string | undefined;
+    const m = name ? map.components[name] : undefined;
+    if (!name || !m) continue;
+    const side: Side = pc.layer === "bottom" ? "bottom" : "top";
+    const z = side === "bottom" ? -half : half;
+    const rot = ((pc.rotation ?? 0) * Math.PI) / 180;
+    const xAxis = v3(Math.cos(rot) * (side === "bottom" ? -1 : 1), Math.sin(rot), 0);
+    let frame: PlacedComponent["frame"];
+    const mouth = pc.cable_insertion_center as { x: number; y: number } | undefined;
+    if (mouth && pc.insertion_direction && DIRECTION[pc.insertion_direction]) {
+      frame = { origin: v3(mouth.x, mouth.y, z), normal: DIRECTION[pc.insertion_direction], xAxis, source: "insertion_direction" };
+    } else if (mouth && Math.hypot(mouth.x - pc.center.x, mouth.y - pc.center.y) > 1e-6) {
+      const d = Math.hypot(mouth.x - pc.center.x, mouth.y - pc.center.y);
+      frame = { origin: v3(mouth.x, mouth.y, z), normal: v3((mouth.x - pc.center.x) / d, (mouth.y - pc.center.y) / d, 0), xAxis, source: "inferred_from_cable_insertion_center" };
+    } else frame = { origin: v3(pc.center.x, pc.center.y, z), normal: [0, 0, side === "bottom" ? -1 : 1], xAxis, source: "body_top" };
+    components.push({
+      instance: m.instance,
+      name,
+      part: m.part,
+      origin: [r4(pc.display_offset_x ?? pc.center.x), r4(pc.display_offset_y ?? pc.center.y)],
+      center: [r4(pc.center.x), r4(pc.center.y)],
+      rotation_deg: r4((((pc.rotation ?? 0) % 360) + 360) % 360),
+      side,
+      size: [r4(pc.width), r4(pc.height)],
+      frame,
+    });
+  }
+  let wire = 0;
+  for (const t of ofType(cj, "pcb_trace")) {
+    for (let i = 1; i < (t.route ?? []).length; i++) {
+      const a = t.route[i - 1];
+      const b = t.route[i];
+      if (a.route_type === "wire" && b.route_type === "wire" && a.layer === b.layer) wire += Math.hypot(b.x - a.x, b.y - a.y);
+    }
+  }
+  return {
+    thickness_mm: board.thickness,
+    layers: board.num_layers,
+    outline,
+    holes: ofType(cj, "pcb_hole")
+      .filter((h) => !h.pcb_component_id)
+      .map((h, i) => ({ name: (h.name as string | undefined) ?? `hole_${i + 1}`, at: [r4(h.x), r4(h.y)] as Vec2, diameter_mm: h.hole_diameter })),
+    keepouts: ofType(cj, "pcb_keepout").map((k) => ({ center: [k.center.x, k.center.y] as Vec2, shape: k.shape, width: k.width, height: k.height, radius: k.radius, layers: k.layers })),
+    components,
+    routing: { traces: ofType(cj, "pcb_trace").length, vias: ofType(cj, "pcb_via").length, wire_mm: r4(wire) },
+    toolVersion: ofType(cj, "source_project_metadata")[0]?.software_used_string,
+  };
+}
+
+/**
+ * UHD pin (`<instance>:<interface>`) of every pcb_port that carries one, via
+ * the name map: component name → instance, pad number → interface.
+ */
+export function portPins(cj: CircuitElement[], map: NameMap): Map<string, string> {
+  const sources = new Map(ofType(cj, "source_component").map((s) => [s.source_component_id, s]));
+  const sourcePorts = new Map(ofType(cj, "source_port").map((s) => [s.source_port_id, s]));
+  const out = new Map<string, string>();
+  for (const p of ofType(cj, "pcb_port")) {
+    const sp = sourcePorts.get(p.source_port_id);
+    const sc = sp && sources.get(sp.source_component_id);
+    const m = sc && map.components[sc.name];
+    if (!m || sp.pin_number === undefined) continue;
+    const iface = m.ports[String(sp.pin_number)];
+    if (iface) out.set(p.pcb_port_id, `${m.instance}:${iface}`);
+  }
+  return out;
+}
+
+/**
+ * Traces written by hand (board.tsx, or an edited board.gen.tsx) that join pads of one pin
+ * (PB-1027, seen on a large field board): generate joins a pin's pads itself since 0.1.7 (padJoins), so such a trace
+ * duplicates its joins, and the converter writes it into KiCad as copper on no net. A trace is
+ * the generator's when the generated source (`generated`, board.gen.tsx as generate wrote it) has
+ * a `<trace from=… to=…>` of the same two selectors; each one there accounts for one in the build.
+ */
+export function handPadJoins(cj: CircuitElement[], map: NameMap, generated: string): { trace: string; instance: string; pin: string; ports: string[] }[] {
+  const sources = new Map(ofType(cj, "source_component").map((s) => [s.source_component_id, s.name as string]));
+  const sourcePorts = new Map(ofType(cj, "source_port").map((s) => [s.source_port_id, s]));
+  const pinOf = (id: string): { comp: string; pin: string } | undefined => {
+    const sp = sourcePorts.get(id);
+    const comp = sp && sources.get(sp.source_component_id);
+    if (!comp) return undefined;
+    const names = [String(sp.name ?? ""), ...((sp.port_hints as string[] | undefined) ?? [])];
+    const internal = names.map((n) => /^pin(\d+)_internal_\d+$/.exec(n)?.[1]).find(Boolean);
+    const pin = internal ?? (sp.pin_number !== undefined ? String(sp.pin_number) : names.map((n) => /^pin(\d+)$/.exec(n)?.[1]).find(Boolean));
+    return pin ? { comp, pin } : undefined;
+  };
+  // the generator's own traces, by "<from> to <to>" (tscircuit's display name of a trace)
+  const ours = new Map<string, number>();
+  for (const m of generated.matchAll(/<trace\s+from=("(?:[^"\\]|\\.)*")\s+to=("(?:[^"\\]|\\.)*")/g)) {
+    const key = `${JSON.parse(m[1])} to ${JSON.parse(m[2])}`;
+    ours.set(key, (ours.get(key) ?? 0) + 1);
+  }
+  const out: { trace: string; instance: string; pin: string; ports: string[] }[] = [];
+  for (const t of ofType(cj, "source_trace")) {
+    const ids = (t.connected_source_port_ids as string[] | undefined) ?? [];
+    if (ids.length < 2 || ((t.connected_source_net_ids as string[] | undefined) ?? []).length) continue;
+    const pins = ids.map(pinOf);
+    if (pins.some((p) => !p) || new Set(pins.map((p) => `${p!.comp}/${p!.pin}`)).size !== 1) continue;
+    const name = String(t.display_name ?? t.source_trace_id);
+    const left = ours.get(name) ?? 0;
+    if (left > 0) {
+      ours.set(name, left - 1);
+      continue;
+    }
+    const m = map.components[pins[0]!.comp];
+    out.push({ trace: name, instance: m?.instance ?? pins[0]!.comp, pin: m?.ports[pins[0]!.pin] ?? `pin${pins[0]!.pin}`, ports: ids.map((id) => String(sourcePorts.get(id)?.name ?? id)) });
+  }
+  return out;
+}
+
+/**
+ * Pins whose pads the copper does not join: a pin with several pads (a module's exposed ground
+ * pads, a thermal pad split into windows) is one tscircuit port on its first pad and an internal
+ * port (`pinN_internal_k`) on each other pad. Generate traces every internal port to the pin's net
+ * (source.ts); this finds, among `pins` (`<instance>:<interface>`, the pins on a UHD net), each
+ * whose pads lie in more than one copper piece.
+ */
+export function unjoinedPads(cj: CircuitElement[], map: NameMap, pins: Set<string>): { pin: string; pads: number; pieces: number; ports: string[] }[] {
+  const sources = new Map(ofType(cj, "source_component").map((s) => [s.source_component_id, s]));
+  const sourcePorts = new Map(ofType(cj, "source_port").map((s) => [s.source_port_id, s]));
+  const byPin = new Map<string, string[]>();
+  // SMD pads only: a pin's plated holes (a receptacle's shell stakes) are joined by the part's own metal
+  const smd = new Set(ofType(cj, "pcb_smtpad").map((p) => p.pcb_port_id));
+  for (const p of ofType(cj, "pcb_port")) {
+    if (!smd.has(p.pcb_port_id)) continue;
+    const sp = sourcePorts.get(p.source_port_id);
+    const m = sp && map.components[sources.get(sp.source_component_id)?.name];
+    if (!m) continue;
+    const n = sp.pin_number !== undefined ? String(sp.pin_number) : /^pin(\d+)_internal_\d+$/.exec(String(sp.name ?? ""))?.[1];
+    const iface = n !== undefined ? m.ports[n] : undefined;
+    if (!iface || !pins.has(`${m.instance}:${iface}`)) continue;
+    byPin.set(`${m.instance}:${iface}`, [...(byPin.get(`${m.instance}:${iface}`) ?? []), p.pcb_port_id]);
+  }
+  const multi = [...byPin].filter(([, ports]) => ports.length > 1);
+  if (!multi.length) return [];
+  const connectivity = getFullConnectivityMapFromCircuitJson(cj.filter((e) => e.type.startsWith("pcb_")) as never);
+  const out: { pin: string; pads: number; pieces: number; ports: string[] }[] = [];
+  for (const [pin, ports] of multi) {
+    const pieces = new Set(ports.map((id) => connectivity.getNetConnectedToId(id) ?? `alone:${id}`)).size;
+    if (pieces > 1) out.push({ pin, pads: ports.length, pieces, ports });
+  }
+  return out.sort((a, b) => a.pin.localeCompare(b.pin));
+}
+
+/**
+ * The nets as the copper joins them: groups of UHD pins connected by traces,
+ * vias, pads and pours. Built from pcb_* elements only: the connectivity
+ * map's full mode also merges the source intent (source_trace, source_net),
+ * which would make an unrouted net look connected (spike §4).
+ */
+export function copperNets(cj: CircuitElement[], map: NameMap): { nets: { pins: string[] }[]; present: Set<string> } {
+  const pins = portPins(cj, map);
+  const connectivity = getFullConnectivityMapFromCircuitJson(cj.filter((e) => e.type.startsWith("pcb_")) as never);
+  const groups = new Map<string, string[]>();
+  for (const [portId, pin] of pins) {
+    const net = connectivity.getNetConnectedToId(portId) ?? `alone:${portId}`;
+    groups.set(net, [...(groups.get(net) ?? []), pin]);
+  }
+  return { nets: [...groups.values()].filter((g) => g.length > 1).map((g) => ({ pins: [...new Set(g)].sort() })), present: new Set(pins.values()) };
+}

package/lib/models.ts

@@ -0,0 +1,284 @@
+/**
+ * Component bodies for board.glb and board.step. In order of preference:
+ *
+ *   1. the part's own UHD body artifact (STEP), placed on its footprint by the
+ *      part's mounting frame (the face that meets the board), without the
+ *      interface feature shapes UHD bodies carry (see stepfile.ts)
+ *   2. a box from the part's package body facts (UHD `dimensions_mm`),
+ *      written here as a small STEP solid
+ *   3. nothing from us: tscircuit's own generated body for built-in
+ *      footprints, or no body (reported)
+ *
+ * The models are set on the built circuit JSON (cad_component) just before
+ * the 3D exporters run, so the native source never carries model paths.
+ */
+import { join, relative, sep } from "node:path";
+import type { BoardComponent, Project } from "@protoboardai/core";
+import type { CircuitElement } from "./runtime.ts";
+import type { NameMap } from "./source.ts";
+
+export type BodySource = "part" | "box" | "tscircuit" | "none";
+
+export interface ComponentBody {
+  instance: string;
+  source: BodySource;
+  /** Absolute path of the STEP model used. */
+  step?: string;
+  /** Machine-independent name of the model, for outputs: `<part>#<artifact>`, or the box's project-relative path. */
+  label?: string;
+  /** Artifact id when the part's own body was used. */
+  artifact?: string;
+  /** Project-relative path of a generated box model, when one is needed. */
+  box?: { path: string; size: [number, number, number] };
+  /** Named sub-shapes to strip from the part's STEP: the part's interface ids (UHD feature shapes). */
+  strip?: string[];
+  /** Project-relative path of the stripped copy, when stripping removes anything. */
+  stripped?: string;
+  /** Mount origin offset in the model's own frame (mm), applied on placement. */
+  mountOrigin?: [number, number, number];
+  /**
+   * A mesh body (GLB or OBJ) for a part with no STEP artifact: board.glb uses it, board.step
+   * the package box when the part states its size. `units` is the file's ("m" for UHD GLBs,
+   * which are glTF metres, +Y up).
+   */
+  mesh?: { format: "glb" | "obj"; path: string; label: string; units?: string; mount?: [number, number, number] };
+}
+
+/** Choose the body for each component. Box models and stripped copies are named here; writing them is the caller's. */
+export function chooseBodies(p: Project, components: BoardComponent[], nativeDir: string): ComponentBody[] {
+  return components.map((c) => {
+    for (const b of c.bodies) {
+      if (b.format !== "step") continue;
+      const art = p.artifacts.find((a) => a.definition === c.part && a.id === b.artifact);
+      if (art?.resolved && art.present === true) {
+        const strip = (p.lookup(c.part)?.interfaces ?? []).map((i) => i.id);
+        return { instance: c.instance, source: "part", step: art.resolved, label: `${c.part}#${b.artifact}`, artifact: b.artifact, strip, stripped: `${nativeDir}/models/${c.part}-${b.artifact}.step`, ...(b.mount ? { mountOrigin: b.mount.origin } : {}) };
+      }
+    }
+    // no STEP: a GLB or OBJ body for board.glb (board.step falls back to the package box)
+    let mesh: ComponentBody["mesh"];
+    for (const b of c.bodies) {
+      if (b.format !== "glb" && b.format !== "obj") continue;
+      const art = p.artifacts.find((a) => a.definition === c.part && a.id === b.artifact);
+      if (art?.resolved && art.present === true) {
+        mesh = { format: b.format, path: art.resolved, label: `${c.part}#${b.artifact}`, ...(b.units ? { units: b.units } : {}), ...(b.mount ? { mount: b.mount.origin } : {}) };
+        break;
+      }
+    }
+    const s = c.package?.size_mm;
+    if (s?.length && s.width && s.height) {
+      const size: [number, number, number] = [s.length, s.width, s.height];
+      const path = `${nativeDir}/models/box-${size.join("x")}.step`;
+      return { instance: c.instance, source: mesh ? "part" : "box", label: path, box: { path, size }, ...(mesh ? { mesh, artifact: mesh.label.split("#")[1] } : {}) };
+    }
+    return mesh ? { instance: c.instance, source: "part", mesh, artifact: mesh.label.split("#")[1] } : { instance: c.instance, source: "none" };
+  });
+}
+
+/**
+ * Point each component's cad_component at its chosen model. Returns the
+ * patched circuit JSON (a copy), per instance what was used, and the label
+ * of each model file (absolute path → label) for outputs that name models.
+ *
+ * A cad_component's position is where the model's own origin goes: the
+ * footprint origin on the board surface (z = ±thickness/2), moved by the
+ * part's mount origin when it has one.
+ */
+export function applyBodies(cj: CircuitElement[], map: NameMap, bodies: ComponentBody[], root: string): { circuitJson: CircuitElement[]; used: Record<string, BodySource>; labels: Record<string, string> } {
+  const out = cj.map((e) => ({ ...e }));
+  const byInstance = new Map(bodies.map((b) => [b.instance, b]));
+  const sources = new Map(out.filter((e) => e.type === "source_component").map((s) => [s.source_component_id, s]));
+  const pcbOf = new Map(out.filter((e) => e.type === "pcb_component").map((c) => [c.pcb_component_id, c]));
+  const used: Record<string, BodySource> = {};
+  const labels: Record<string, string> = {};
+  for (const cad of out.filter((e) => e.type === "cad_component")) {
+    const name = sources.get(cad.source_component_id)?.name as string | undefined;
+    const m = name ? map.components[name] : undefined;
+    if (!m) continue;
+    const body = byInstance.get(m.instance);
+    const step = body?.step ?? (body?.box ? `${root}/${body.box.path}` : undefined);
+    if (!body || (!step && !body.mesh)) {
+      used[m.instance] = cad.model_jscad || cad.footprinter_string || cad.model_step_url || cad.model_glb_url ? "tscircuit" : "none";
+      continue;
+    }
+    for (const k of ["model_obj_url", "model_stl_url", "model_glb_url", "model_gltf_url", "model_wrl_url", "model_jscad", "footprinter_string", "model_step_url"]) delete cad[k];
+    // a mesh with no size to box: board.glb draws the mesh (withMeshes), board.step has no body for it
+    if (step) {
+      cad.model_step_url = step;
+      labels[step] = body.label ?? body.box?.path ?? body.instance;
+    }
+    cad.show_as_bounding_box = false;
+    // tscircuit puts a cad_component at the pads' bounding-box centre and infers the model's origin from
+    // its contact faces; both differ from the footprint origin for a part whose pads are not centred on
+    // it (a module with its antenna end bare, a USB-C receptacle). The model's own origin (its mounting
+    // point, or the box's bottom centre) goes to the footprint origin instead, stated explicitly: where
+    // tscircuit placed it (pcbX/pcbY), else the pads' centre less their offset from the origin.
+    cad.model_origin_position = { x: 0, y: 0, z: 0 };
+    const pcb = pcbOf.get(cad.pcb_component_id);
+    if (pcb && typeof pcb.display_offset_x === "number" && typeof pcb.display_offset_y === "number") cad.position = { ...cad.position, x: pcb.display_offset_x, y: pcb.display_offset_y };
+    else if (m.padCentre) {
+      const a = ((cad.rotation?.z ?? 0) * Math.PI) / 180;
+      const flip = (cad.position?.z ?? 0) < 0 ? -1 : 1;
+      const [cx, cy] = [m.padCentre[0] * flip, m.padCentre[1]];
+      cad.position = { ...cad.position, x: cad.position.x - (cx * Math.cos(a) - cy * Math.sin(a)), y: cad.position.y - (cx * Math.sin(a) + cy * Math.cos(a)) };
+    }
+    const o = body.step ? body.mountOrigin : undefined;
+    if (o && (o[0] || o[1] || o[2])) {
+      // the model's mount point goes to the footprint origin on the board surface
+      const a = ((cad.rotation?.z ?? 0) * Math.PI) / 180;
+      const flip = (cad.position?.z ?? 0) < 0 ? -1 : 1;
+      cad.position = { x: cad.position.x - (o[0] * Math.cos(a) - o[1] * Math.sin(a)) * flip, y: cad.position.y - (o[0] * Math.sin(a) + o[1] * Math.cos(a)), z: cad.position.z - o[2] * flip };
+    }
+    used[m.instance] = body.source;
+  }
+  return { circuitJson: out, used, labels };
+}
+
+/**
+ * A rectangular body as an ISO 10303-21 (AP214) solid: length along X, width
+ * along Y, height up +Z from z = 0, centred on the origin in X and Y (the
+ * face at z = 0 is the one that sits on the board).
+ */
+export function boxStep(name: string, [l, w, h]: [number, number, number]): string {
+  const lines: string[] = [];
+  let id = 0;
+  const add = (s: string) => {
+    lines.push(`#${++id}=${s};`);
+    return `#${id}`;
+  };
+  const f = (v: number) => {
+    const s = (Math.round(v * 1e6) / 1e6).toString();
+    return s.includes(".") || s.includes("e") ? s.toUpperCase() : `${s}.`;
+  };
+  const pt = (p: number[]) => add(`CARTESIAN_POINT('',(${p.map(f).join(",")}))`);
+  const dir = (d: number[]) => add(`DIRECTION('',(${d.map(f).join(",")}))`);
+
+  const ctx = add("APPLICATION_CONTEXT('automotive design')");
+  add(`APPLICATION_PROTOCOL_DEFINITION('international standard','automotive_design',2000,${ctx})`);
+  const pctx = add(`PRODUCT_CONTEXT('',${ctx},'mechanical')`);
+  const product = add(`PRODUCT('${name}','${name}','',(${pctx}))`);
+  const formation = add(`PRODUCT_DEFINITION_FORMATION('','',${product})`);
+  const dctx = add(`PRODUCT_DEFINITION_CONTEXT('part definition',${ctx},'design')`);
+  const pdef = add(`PRODUCT_DEFINITION('design','',${formation},${dctx})`);
+  const shape = add(`PRODUCT_DEFINITION_SHAPE('','',${pdef})`);
+  const len = add("(LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.))");
+  const ang = add("(NAMED_UNIT(*) PLANE_ANGLE_UNIT() SI_UNIT($,.RADIAN.))");
+  const sol = add("(NAMED_UNIT(*) SI_UNIT($,.STERADIAN.) SOLID_ANGLE_UNIT())");
+  const unc = add(`UNCERTAINTY_MEASURE_WITH_UNIT(LENGTH_MEASURE(1.E-07),${len},'distance_accuracy_value','confusion accuracy')`);
+  const gctx = add(`(GEOMETRIC_REPRESENTATION_CONTEXT(3) GLOBAL_UNCERTAINTY_ASSIGNED_CONTEXT((${unc})) GLOBAL_UNIT_ASSIGNED_CONTEXT((${len},${ang},${sol})) REPRESENTATION_CONTEXT('Context #1','3D Context with UNIT and UNCERTAINTY'))`);
+
+  // vertices: index = x + 2y + 4z over the box corners
+  const corner = (i: number) => [(i & 1 ? 0.5 : -0.5) * l, (i & 2 ? 0.5 : -0.5) * w, i & 4 ? h : 0];
+  const vertex = Array.from({ length: 8 }, (_, i) => add(`VERTEX_POINT('',${pt(corner(i))})`));
+  const edges = new Map<string, string>();
+  const edge = (a: number, b: number): { ref: string; forward: boolean } => {
+    const [s, e] = a < b ? [a, b] : [b, a];
+    const key = `${s}-${e}`;
+    if (!edges.has(key)) {
+      const ps = corner(s);
+      const pe = corner(e);
+      const d = pe.map((v, k) => v - ps[k]);
+      const n = Math.hypot(...d);
+      const line = add(`LINE('',${pt(ps)},${add(`VECTOR('',${dir(d.map((v) => v / n))},${f(n)})`)})`);
+      edges.set(key, add(`EDGE_CURVE('',${vertex[s]},${vertex[e]},${line},.T.)`));
+    }
+    return { ref: edges.get(key)!, forward: a < b };
+  };
+  // faces: corners counter-clockwise seen from outside, with the outward normal
+  const faces: [number[], number[], number[]][] = [
+    [[0, 2, 3, 1], [0, 0, -1], [1, 0, 0]],
+    [[4, 5, 7, 6], [0, 0, 1], [1, 0, 0]],
+    [[0, 1, 5, 4], [0, -1, 0], [1, 0, 0]],
+    [[2, 6, 7, 3], [0, 1, 0], [-1, 0, 0]],
+    [[0, 4, 6, 2], [-1, 0, 0], [0, 1, 0]],
+    [[1, 3, 7, 5], [1, 0, 0], [0, -1, 0]],
+  ];
+  const faceRefs = faces.map(([loop, normal, ref]) => {
+    const oriented = loop.map((a, i) => {
+      const e = edge(a, loop[(i + 1) % 4]);
+      return add(`ORIENTED_EDGE('',*,*,${e.ref},${e.forward ? ".T." : ".F."})`);
+    });
+    const bound = add(`FACE_OUTER_BOUND('',${add(`EDGE_LOOP('',(${oriented.join(",")}))`)},.T.)`);
+    const plane = add(`PLANE('',${add(`AXIS2_PLACEMENT_3D('',${pt(corner(loop[0]))},${dir(normal)},${dir(ref)})`)})`);
+    return add(`ADVANCED_FACE('',(${bound}),${plane},.T.)`);
+  });
+  const solid = add(`MANIFOLD_SOLID_BREP('${name}',${add(`CLOSED_SHELL('',(${faceRefs.join(",")}))`)})`);
+  const axis = add(`AXIS2_PLACEMENT_3D('',${pt([0, 0, 0])},${dir([0, 0, 1])},${dir([1, 0, 0])})`);
+  const rep = add(`ADVANCED_BREP_SHAPE_REPRESENTATION('${name}',(${axis},${solid}),${gctx})`);
+  add(`SHAPE_DEFINITION_REPRESENTATION(${shape},${rep})`);
+
+  return [
+    "ISO-10303-21;",
+    "HEADER;",
+    `FILE_DESCRIPTION(('${name}: box from package body facts'),'2;1');`,
+    `FILE_NAME('${name}.step','1970-01-01T00:00:00',(''),(''),'@protoboardai/ext-tscircuit','','');`,
+    "FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }'));",
+    "ENDSEC;",
+    "DATA;",
+    ...lines,
+    "ENDSEC;",
+    "END-ISO-10303-21;",
+    "",
+  ].join("\n");
+}
+
+/**
+ * board.glb's copy of the bodied circuit JSON: a component whose body is a mesh (a part with a GLB
+ * or OBJ body and no STEP) gets the mesh instead of its package box. A UHD GLB is glTF: metres,
+ * +Y up, so it is scaled to millimetres and its +Y is the board normal; the part's mount origin
+ * (mm, part frame) goes to the footprint origin as for a STEP body.
+ */
+export function withMeshes(cj: CircuitElement[], map: NameMap, bodies: ComponentBody[]): CircuitElement[] {
+  const byInstance = new Map(bodies.map((b) => [b.instance, b]));
+  const sources = new Map(cj.filter((e) => e.type === "source_component").map((s) => [s.source_component_id, s.name as string]));
+  return cj.map((e) => {
+    if (e.type !== "cad_component") return e;
+    const mesh = byInstance.get(map.components[sources.get(e.source_component_id) ?? ""]?.instance ?? "")?.mesh;
+    if (!mesh) return e;
+    const { model_step_url: _step, ...rest } = e;
+    const metres = mesh.units === "m" || (mesh.format === "glb" && mesh.units === undefined);
+    const out: CircuitElement = { ...rest, [mesh.format === "glb" ? "model_glb_url" : "model_obj_url"]: mesh.path, model_unit_to_mm_scale_factor: metres ? 1000 : 1, ...(mesh.format === "glb" ? { model_board_normal_direction: "y+" } : {}), model_origin_position: { x: 0, y: 0, z: 0 }, show_as_bounding_box: false };
+    const o = mesh.mount;
+    if (o && (o[0] || o[1] || o[2])) {
+      const a = ((e.rotation?.z ?? 0) * Math.PI) / 180;
+      const flip = (e.position?.z ?? 0) < 0 ? -1 : 1;
+      out.position = { x: e.position.x - (o[0] * Math.cos(a) - o[1] * Math.sin(a)) * flip, y: e.position.y - (o[0] * Math.sin(a) + o[1] * Math.cos(a)), z: e.position.z - o[2] * flip };
+    }
+    return out;
+  });
+}
+
+/** A tscircuit `cadModel` prop: the model file relative to the board's source folder, and how it sits on the board. */
+export interface CadModelProp {
+  stepUrl?: string;
+  glbUrl?: string;
+  objUrl?: string;
+  modelOriginPosition?: { x: number; y: number; z: number };
+  modelUnitToMmScale?: number;
+  modelBoardNormalDirection?: "y+";
+}
+
+/**
+ * The `cadModel` generate writes for each component whose part has a body artifact: the STEP
+ * (the stripped copy in models/ when stripping removed anything), else the GLB or OBJ. Paths are
+ * relative to the native folder with forward slashes, so they mean the same on every OS and on
+ * every machine; the provider's exports resolve them against that folder (and set absolute paths
+ * on a copy of the circuit JSON, applyBodies). Package boxes are export's own and not written here.
+ */
+export function cadModels(root: string, nativeDir: string, bodies: ComponentBody[]): Record<string, CadModelProp> {
+  const rel = (abs: string) => {
+    const r = relative(join(root, nativeDir), abs).split(sep).join("/");
+    return r.startsWith(".") ? r : `./${r}`;
+  };
+  const origin = (o?: [number, number, number]) => (o && (o[0] || o[1] || o[2]) ? { modelOriginPosition: { x: o[0], y: o[1], z: o[2] } } : {});
+  const out: Record<string, CadModelProp> = {};
+  for (const b of bodies) {
+    if (b.source !== "part") continue;
+    if (b.step) out[b.instance] = { stepUrl: rel(b.step), ...origin(b.mountOrigin) };
+    else if (b.mesh) {
+      const metres = b.mesh.units === "m" || (b.mesh.format === "glb" && b.mesh.units === undefined);
+      out[b.instance] = { [b.mesh.format === "glb" ? "glbUrl" : "objUrl"]: rel(b.mesh.path), ...origin(b.mesh.mount), ...(metres ? { modelUnitToMmScale: 1000 } : {}), ...(b.mesh.format === "glb" ? { modelBoardNormalDirection: "y+" as const } : {}) };
+    }
+  }
+  return out;
+}