@protoboardai/ext-docs 0.0.0-stage → 0.2.1

package/lib/model.ts

@@ -0,0 +1,312 @@
+/**
+ * Loading a Protoboard project's system for documentation, and turning its
+ * assembly into renderable bodies. Everything here is read from the model at
+ * run time: `assemble()` placements and hardware, artifacts, manifests.
+ * Artifact paths resolve against each definition's artifact base (the
+ * project, the parts/catalog/<id> directory a catalog revision was vendored
+ * into, or an older pin's package), never against a repository.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { pathToFileURL } from "url";
+import type { ArtifactDef, GeometryFrame, GeometryManifest, ModuleDef } from "@deltarobotics/uhd";
+import type { ModuleLookup } from "@deltarobotics/uhd";
+import { applyMat4, assemble, bodyKey, multiplyMat4, type Assembly, type Mat4 } from "@deltarobotics/uhd";
+import { packageRoot, type Project } from "@protoboardai/core";
+import { packagePath, projectPath, type ServerRoots } from "./render/server.ts";
+import type { DocConfig } from "./types.ts";
+
+/** Project-relative folder of the documents and their spec (`docs/docspec.ts`). */
+export const DOCS_DIR = "docs";
+
+export interface LoadedSystem {
+  /** Project name, shown in the documents. */
+  name: string;
+  /** Absolute project root. */
+  root: string;
+  /** The documents folder: project-relative and absolute. */
+  docsDir: string;
+  absDocs: string;
+  system: ModuleDef;
+  lookup: ModuleLookup;
+  scenarios: { id: string; label: string; description: string; system: ModuleDef; lookup: ModuleLookup }[];
+  config: DocConfig;
+  /** What the doc server serves: the project, and packages by name. */
+  roots: ServerRoots;
+  /** The absolute file of an artifact path `def` declares (resolved against its origin), if it can be placed. */
+  file: (def: ModuleDef, filePath: string) => string | undefined;
+  /** The same file as a served path (server.ts). */
+  served: (def: ModuleDef, filePath: string) => string | undefined;
+  /** Folders that may hold a definition's sources.json and verification.json. */
+  evidenceDirs: (id: string) => string[];
+}
+
+interface ProjectScenario {
+  id: string;
+  label: string;
+  description?: string;
+  system?: ModuleDef;
+  overrides?: ModuleDef[];
+}
+
+/** The project's root system, its scenarios and `docs/docspec.ts`, with artifact and evidence resolution. */
+export async function loadSystem(p: Project, docsDir = DOCS_DIR): Promise<LoadedSystem> {
+  if (!p.rootDef) throw new Error("the project has no root system (protoboard.config.ts root)");
+  const system = p.rootDef;
+  const lookup: ModuleLookup = (id) => p.lookup(id);
+  const packages = new Map<string, string | undefined>();
+  const pkgRoot = (name: string) => {
+    if (!packages.has(name)) packages.set(name, packageRoot(p.root, name));
+    return packages.get(name);
+  };
+  // A definition's artifact base (core ArtifactBase): the project, a directory in it the
+  // catalog revision was vendored into (parts/catalog/<id>), or an installed package.
+  type Base = { kind: "project"; dir: string } | { kind: "package"; name: string; root: string };
+  const base = (def: ModuleDef): Base | undefined => {
+    const rec = p.definitions.get(def.id);
+    const ab = rec?.origin.artifactBase;
+    if (!ab || ab.kind === "project") return { kind: "project", dir: "" };
+    if (ab.kind === "vendored") return { kind: "project", dir: ab.dir };
+    const root = pkgRoot(ab.package);
+    return root ? { kind: "package", name: ab.package, root } : undefined;
+  };
+  const file = (def: ModuleDef, filePath: string) => {
+    const b = base(def);
+    return b ? join(b.kind === "project" ? join(p.root, b.dir) : b.root, filePath) : undefined;
+  };
+  const served = (def: ModuleDef, filePath: string) => {
+    const b = base(def);
+    return b ? (b.kind === "project" ? projectPath(b.dir ? `${b.dir}/${filePath}` : filePath) : packagePath(b.name, filePath)) : undefined;
+  };
+  const evidenceDirs = (id: string) => {
+    const rec = p.definitions.get(id);
+    const dirs = [join(p.root, "parts", "evidence", id)];
+    // evidence files vendored with the catalog revision (parts/catalog/<id>/…)
+    for (const e of rec?.origin.evidence ?? []) {
+      const dir = dirname(join(p.root, e.file));
+      if (!dirs.includes(dir)) dirs.push(dir);
+    }
+    // catalog parts vendored from a package keep their evidence at library/parts/<id> in it
+    if (rec?.origin.kind === "catalog" && rec.origin.package) {
+      const root = pkgRoot(rec.origin.package);
+      if (root) dirs.push(join(root, "library", "parts", id));
+    }
+    return dirs;
+  };
+
+  let scenarios: LoadedSystem["scenarios"] = [];
+  if (p.config.scenarios) {
+    const mod = (await import(pathToFileURL(join(p.root, p.config.scenarios.source)).href)) as Record<string, unknown>;
+    scenarios = ((mod[p.config.scenarios.export] as ProjectScenario[] | undefined) ?? []).map((s) => {
+      const overrides = new Map((s.overrides ?? []).map((d) => [d.id, d]));
+      return { id: s.id, label: s.label, description: s.description ?? "", system: s.system ?? system, lookup: (id: string) => overrides.get(id) ?? p.lookup(id) };
+    });
+  }
+  let config: DocConfig = {};
+  const spec = join(p.root, docsDir, "docspec.ts");
+  if (existsSync(spec)) config = ((await import(pathToFileURL(spec).href)) as { default?: DocConfig }).default ?? {};
+  return {
+    name: p.name,
+    root: p.root,
+    docsDir,
+    absDocs: join(p.root, docsDir),
+    system,
+    lookup,
+    scenarios,
+    config,
+    roots: { project: p.root, packageRoot: pkgRoot },
+    file,
+    served,
+    evidenceDirs,
+  };
+}
+
+/** The generator manifest for one of a module's CAD artifacts (the JSON artifact generated from it). */
+export function manifestFor(sys: LoadedSystem, def: ModuleDef, artifactId: string): GeometryManifest | undefined {
+  const art = (def.artifacts ?? []).find((a) => a.format === "json" && a.provenance?.generatedFrom === artifactId && a.filePath);
+  const f = art?.filePath ? sys.file(def, art.filePath) : undefined;
+  if (!f || !existsSync(f)) return undefined;
+  try {
+    return JSON.parse(readFileSync(f, "utf8")) as GeometryManifest;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Solid volume (mm³) of a module's generated CAD body: the `volume_mm3` its generator records (UHD systemMass input). */
+export const cadVolume = (sys: LoadedSystem) => (def: ModuleDef): number | undefined => manifestFor(sys, def, "cad_step")?.volume_mm3;
+
+// ---------------------------------------------------------------------------
+// Classification (drawing palette only; never shown as data)
+// ---------------------------------------------------------------------------
+
+/**
+ * UHD taxonomy paths (docs/taxonomy.md) and the drawing class of a part
+ * filed at or under them. Matched by whole segments, so
+ * `actuator.motor_controller` (an ESC) is not under `actuator.motor`.
+ */
+const TAXONOMY_CLASSES: [string, string][] = [
+  ["actuator.motor", "motor"],
+  ["actuator.motor_controller", "esc"],
+  ["mechanical.propeller", "prop"],
+  ["microcontroller.flight_controller", "fc"],
+  ["connectivity.wireless.video", "video"],
+  ["power.battery", "battery"],
+  ["sensor.gnss", "gnss"],
+  ["component.passive.capacitor", "capacitor"],
+];
+
+export function category(def: ModuleDef): string {
+  const id = def.id;
+  const tags = new Set(def.tags ?? []);
+  const paths = def.categories ?? [];
+  const cats = paths.join(" ");
+  if (tags.has("screw")) return "screw";
+  if (tags.has("nut")) return "nut";
+  if (tags.has("standoff")) return "standoff";
+  if (tags.has("spacer")) return "spacer";
+  if (id.includes("top-plate")) return "top_plate";
+  if (tags.has("frame") || cats.includes("structure") && id.includes("frame")) return "frame";
+  // taxonomy paths, in the definition's order: its first category is what it is
+  for (const path of paths) for (const [root, cls] of TAXONOMY_CLASSES) if (path === root || path.startsWith(`${root}.`)) return cls;
+  if (tags.has("receiver")) return "receiver";
+  // categories from before the UHD taxonomy (PB-849)
+  if (cats.includes("motor")) return "motor";
+  if (cats.includes("propeller") || tags.has("propeller")) return "prop";
+  if (cats.includes("esc")) return "esc";
+  if (cats.includes("flight_controller")) return "fc";
+  if (cats.includes("video")) return "video";
+  if (cats.includes("battery")) return "battery";
+  if (cats.includes("gnss")) return "gnss";
+  if (cats.includes("receiver")) return "receiver";
+  if (cats.includes("capacitor")) return "capacitor";
+  return "generic";
+}
+
+// ---------------------------------------------------------------------------
+// Artifacts
+// ---------------------------------------------------------------------------
+
+/** Body GLB for a module (or for one of its bodies, by the STEP/vendor artifact id). */
+export function glbFor(def: ModuleDef, bodyArtifact?: string): ArtifactDef | undefined {
+  const arts = def.artifacts ?? [];
+  if (bodyArtifact) return arts.find((a) => a.format === "glb" && (a.id === bodyArtifact || a.provenance?.generatedFrom === bodyArtifact));
+  return arts.find((a) => a.role === "body" && a.format === "glb");
+}
+
+/** Feature names in the manifest of the STEP a GLB was generated from (sub-shapes to hide or call out). */
+export function featureNames(sys: LoadedSystem, def: ModuleDef, glb?: ArtifactDef): string[] {
+  const src = glb?.provenance?.generatedFrom;
+  return src ? Object.keys(manifestFor(sys, def, src)?.features ?? {}) : [];
+}
+
+// ---------------------------------------------------------------------------
+// Scene bodies from the assembly
+// ---------------------------------------------------------------------------
+
+export interface SceneBody {
+  key: string;
+  path: string[];
+  def: ModuleDef;
+  glb?: string;
+  matrix: Mat4;
+  category: string;
+  features: string[];
+  vendor: boolean;
+  /** Link that placed it; "hint:<note>" for doc-config placements. */
+  via?: string;
+  /** Hardware only. */
+  harness?: string;
+  child?: string;
+  linkId?: string;
+}
+
+export interface SceneModel {
+  assembly: Assembly;
+  bodies: SceneBody[];
+  hardware: SceneBody[];
+  byKey: Map<string, SceneBody>;
+}
+
+export function buildScene(sys: LoadedSystem): SceneModel {
+  const fixed: Record<string, Mat4> = {};
+  for (const h of sys.config.placementHints ?? []) fixed[bodyKey(h.path)] = h.matrix;
+  const assembly = assemble(sys.system, sys.lookup, { root: sys.config.root ?? [], fixed });
+  const defs = new Map(assembly.instances.map((i) => [bodyKey(i.path), i.def]));
+  // A module with children is flattened into its leaves by assemble(), but one with its own body
+  // (a circuit board: its GLB carries every component) is drawn whole when a hint places it.
+  const walk = (d: ModuleDef, prefix: string[]) => {
+    for (const ref of d.children ?? []) {
+      const child = sys.lookup(ref.moduleDefId);
+      if (!child?.children?.length || child.kind === "harness") continue;
+      const path = [...prefix, ref.id];
+      if (glbFor(child) && fixed[bodyKey(path)]) defs.set(bodyKey(path), child);
+      walk(child, path);
+    }
+  };
+  walk(sys.system, []);
+  const bodies: SceneBody[] = [];
+  // a placed module with children (a designed board carrying its components) is not a leaf instance; it is a body when it has its own GLB
+  const defAt = (path: string[]): ModuleDef | undefined => {
+    let d: ModuleDef | undefined = sys.system;
+    for (const id of path) {
+      const ref: { moduleDefId: string } | undefined = d?.children?.find((c) => c.id === id);
+      d = ref ? sys.lookup(ref.moduleDefId) : undefined;
+    }
+    return d;
+  };
+  for (const p of assembly.placements) {
+    const leaf = defs.get(bodyKey(p.path));
+    const inner = leaf ? undefined : defAt(p.path);
+    const def = leaf ?? (inner && glbFor(inner, p.body) ? inner : undefined);
+    if (!def) continue;
+    const glb = glbFor(def, p.body);
+    const hint = (sys.config.placementHints ?? []).find((h) => bodyKey(h.path) === p.key);
+    bodies.push({
+      key: p.key,
+      path: p.path,
+      def,
+      glb: glb?.filePath ? sys.served(def, glb.filePath) : undefined,
+      matrix: p.matrix,
+      category: category(def),
+      features: featureNames(sys, def, glb),
+      vendor: Boolean(glb?.id.startsWith("cad_vendor")),
+      via: p.via ?? (hint ? `hint:${hint.note}` : undefined),
+    });
+  }
+  const counters = new Map<string, number>();
+  const hardware: SceneBody[] = assembly.hardware.map((h) => {
+    const base = `${h.harness}/${h.child}`;
+    const n = (counters.get(base) ?? 0) + 1;
+    counters.set(base, n);
+    const glb = glbFor(h.def);
+    return {
+      key: `${base}#${n}`,
+      path: [...h.harness.split("/"), h.child],
+      def: h.def,
+      glb: glb?.filePath ? sys.served(h.def, glb.filePath) : undefined,
+      matrix: h.matrix,
+      category: category(h.def),
+      features: featureNames(sys, h.def, glb),
+      vendor: false,
+      harness: h.harness,
+      child: h.child,
+      linkId: h.linkId,
+    };
+  });
+  const byKey = new Map([...bodies, ...hardware].map((b) => [b.key, b]));
+  return { assembly, bodies, hardware, byKey };
+}
+
+/** World position and direction of an interface frame on a placed body. */
+export function worldFrame(matrix: Mat4, frame: GeometryFrame): { origin: number[]; normal: number[] } {
+  const o = applyMat4(matrix, frame.origin);
+  const tip = applyMat4(matrix, [frame.origin[0] + frame.normal[0], frame.origin[1] + frame.normal[1], frame.origin[2] + frame.normal[2]]);
+  const n = [tip[0] - o[0], tip[1] - o[1], tip[2] - o[2]];
+  const len = Math.hypot(n[0], n[1], n[2]) || 1;
+  return { origin: o, normal: n.map((x) => x / len) };
+}
+
+export const translate = (v: number[]): Mat4 => [1, 0, 0, v[0], 0, 1, 0, v[1], 0, 0, 1, v[2], 0, 0, 0, 1];
+export const offsetMatrix = (m: Mat4, v: number[]): Mat4 => multiplyMat4(translate(v), m);
+export const matTranslation = (m: Mat4): number[] => [m[3], m[7], m[11]];

package/lib/package/assembly.ts

@@ -0,0 +1,268 @@
+/**
+ * The assembly guide of one Manufacturing Package unit (`package:assembly`):
+ * before you begin (sub-units, tools, materials), the kit with thumbnails,
+ * then one illustrated step per planned step (./plan.ts): the parts strip,
+ * an exploded line-art figure lettered like the strip (or, for connections,
+ * the routed cables drawn in the accent colour), actions, connections,
+ * torque, tools and notes, and a coverage table of every link the unit makes.
+ * Figures are rendered by the release (SectionContext.figure).
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { applyMat4 } from "@deltarobotics/uhd";
+import type { Block, Callout, KitItem, SectionContext, SectionFn, Step } from "@protoboardai/ext-release";
+import { unitBom } from "@protoboardai/ext-release/helpers";
+import type { BuiltContext } from "../context.ts";
+import { centerOf, shortName } from "../docs/assembly.ts";
+import { explode, ISO, renderBody, withOffset } from "../figures.ts";
+import { matTranslation, type SceneBody } from "../model.ts";
+import type { RenderBody } from "../render/renderer.ts";
+import { bodyGlb, noImage, slug, thumbnail, type UnitScope } from "./common.ts";
+import { unitPlan, type PlannedStep } from "./plan.ts";
+
+export const assembly: SectionFn = async (s) => {
+  const { project: p, unit: u, release } = s;
+  if (!p.rootDef) return undefined;
+  const { ctx, scope, steps, builds: buildList, variants } = await unitPlan(p, u);
+  const blocks: Block[] = [];
+  const builds = u.perProduct * release.build;
+  const subs = [...new Set(u.members.filter((m) => m.unit).map((m) => m.unit!))];
+  blocks.push({
+    kind: "paragraph",
+    text: `${u.kind === "root" ? `Final assembly of ${u.name}` : `One build of ${u.name}`}, in ${steps.length} step${steps.length === 1 ? "" : "s"}. Build ${builds} (${u.perProduct} per product × ${release.build}). Steps, parts, hardware and torques come from the model: mates and fastener stacks from assemble(), connections from the wiring checklist.${steps.some((x) => x.split) ? " A step marked as split is the part of a longer step that this unit does; the rest is in the unit named in it." : ""}`,
+  });
+
+  if (variants.length)
+    blocks.push({
+      kind: "note",
+      level: "caution",
+      text: `The ${buildList.length} builds are not all the same: ${variants.map((x) => `${x.field} ${x.values.map((y) => `${y.value} for ${y.build}`).join(", ")}`).join("; ")}. ${variants.every((x) => x.handled) ? "The steps that depend on it list each build." : "Not every step says which build gets what: check each build against the position it goes to."}`,
+    });
+  const later = steps.filter((x) => x.afterTest).map((x) => String(x.n));
+  if (later.length)
+    blocks.push({ kind: "paragraph", text: `${later.length === 1 ? `Step ${later[0]} comes` : `Steps ${later.slice(0, -1).join(", ")} and ${later[later.length - 1]} come`} after the bench test and configuration in the work order; the steps before ${later.length === 1 ? "it" : "them"} are done first.` });
+
+  // ---- before you begin
+  const rank = (t: string) => [/hex key/, /nut driver/, /spanner/].findIndex((r) => r.test(t)) >>> 0;
+  const tools = [...new Set(steps.flatMap((x) => x.tools))].sort((a, b) => rank(a) - rank(b) || parseFloat(a) - parseFloat(b) || (a < b ? -1 : a > b ? 1 : 0));
+  const materials = [...new Set(steps.flatMap((x) => x.materials))];
+  const before: string[] = [];
+  if (subs.length) before.push(`Bring the finished sub-units, each built and tested in its own folder: ${subs.map((id) => `${id} (units/${id}/)`).join(", ")}.`);
+  before.push(`Tools: ${tools.length ? tools.join(", ") : "none beyond hands"}${tools.length ? " (hex keys from each screw's socket, drivers and spanners from each nut's and standoff's across-flats)" : ""}.`);
+  if (materials.length) before.push(`Materials: ${materials.join(", ")}.`);
+  before.push("Figures: parts already assembled are drawn light; parts fitted in the step dark, exploded along each joint's axis in stacking order; hardware in the accent colour. Letters match the parts strip.");
+  blocks.push({ kind: "heading", text: "Before you begin" }, { kind: "list", items: before });
+
+  // ---- kit
+  blocks.push({ kind: "heading", text: "Kit" }, { kind: "kit", items: await kit(ctx, s), note: "Quantities per build, from the unit's bill of materials (bom.csv). Drawings are the parts' CAD, not to scale." });
+
+  // ---- steps
+  const out: Step[] = [];
+  const state = initialState(ctx, scope, steps);
+  for (const step of steps) out.push(await illustrated(ctx, s, scope, step, state));
+  if (out.length) blocks.push({ kind: "heading", text: "Steps" }, { kind: "steps", steps: out });
+  else blocks.push({ kind: "paragraph", text: "This unit makes no joints or connections: its parts arrive assembled." });
+
+  // ---- coverage
+  const rows = steps.flatMap((x) => [
+    ...x.plan.mates.map((m) => ({ link: m.linkId, what: "mate", by: m.harness ?? "", step: `${x.n} · ${x.title}` })),
+    ...x.plan.wiring.map((w) => ({ link: w.linkId, what: "connection", by: w.harness ?? "", step: `${x.n} · ${x.title}` })),
+  ]);
+  if (rows.length) {
+    blocks.push({ kind: "heading", text: "Coverage" });
+    blocks.push({ kind: "table", columns: [{ key: "link", label: "Link" }, { key: "what", label: "Kind" }, { key: "by", label: "Harness" }, { key: "step", label: "Step" }], rows, note: "Every mate and connection this unit makes, and the step that makes it. Links of sub-units are in their own guides." });
+  }
+  return { blocks };
+};
+
+/** Items laid out at the bench: what one build consumes directly (assemblies and kits opened, sub-units and boards whole). */
+async function kit(ctx: BuiltContext, s: SectionContext): Promise<KitItem[]> {
+  const rows = unitBom(s.project, s.unit);
+  const whole: string[] = [];
+  const by = new Map<string, { def: ModuleDef; qty: number; refs: string[]; unit?: string }>();
+  for (const r of rows) {
+    if (whole.some((w) => r.path.startsWith(w + "/"))) continue;
+    if (r.action === "build" && r.kind !== "unit") continue;
+    whole.push(r.path);
+    const def = s.project.lookup(r.definition);
+    if (!def) continue;
+    const x = by.get(def.id) ?? { def, qty: 0, refs: [], unit: r.kind === "unit" ? r.note : undefined };
+    x.qty += r.qty_per_unit;
+    x.refs.push(r.path);
+    by.set(def.id, x);
+  }
+  const items: KitItem[] = [];
+  for (const { def, qty, unit, refs } of by.values()) {
+    const th = unit ? await unitThumbnail(ctx, s, refs[0]) : await thumbnail(ctx, s, def);
+    items.push({ name: shortName(def), quantity: qty, ref: unit ?? def.id, ...(th ? { image: th.file } : { placeholder: noImage(ctx, def) }) });
+  }
+  return items;
+}
+
+/** A sub-unit as it arrives: its placed bodies, line art, in their assembled positions. */
+async function unitThumbnail(ctx: BuiltContext, s: SectionContext, path: string) {
+  const at = s.unit.kind === "root" ? path : `${s.unit.representative}/${path}`;
+  const bodies = [...ctx.scene.bodies, ...ctx.scene.hardware].filter((b) => b.glb && (b.path.join("/") === at || b.path.join("/").startsWith(at + "/")));
+  if (!bodies.length) return undefined;
+  return s.figure(`unit-thumb-${slug(at)}`, { width: 360, height: 360, mode: "lineart", lineScale: 1.25, bodies: bodies.map((b) => renderBody(b, "normal")), camera: { dir: ISO, margin: 0.08 } });
+}
+
+interface FigState {
+  /** Body keys drawn as already assembled. */
+  before: Set<string>;
+  hwBefore: Set<string>;
+  /** Sub-unit instance → its bodies and hardware keys (they arrive built and move as one). */
+  subBodies: Map<string, SceneBody[]>;
+}
+
+/**
+ * Before the first step: the unit's bodies that no step of this unit moves,
+ * except those of a sub-unit that a step mounts (they arrive with it).
+ */
+function initialState(ctx: BuiltContext, scope: UnitScope, steps: PlannedStep[]): FigState {
+  const scene = ctx.scene;
+  const moved = new Set(steps.flatMap((x) => [...x.plan.moving, ...x.plan.placed].map((b) => b.key)));
+  const hwMoved = new Set(steps.flatMap((x) => x.plan.hardware.map((h) => h.key)));
+  const subBodies = new Map<string, SceneBody[]>();
+  for (const b of [...scene.bodies, ...scene.hardware]) {
+    const sub = scope.subOf(b.path.join("/"));
+    if (sub) subBodies.set(sub, [...(subBodies.get(sub) ?? []), b]);
+  }
+  const mountedSubs = new Set([...subBodies.entries()].filter(([, bs]) => bs.some((b) => moved.has(b.key) || hwMoved.has(b.key))).map(([k]) => k));
+  const later = (b: SceneBody) => {
+    const sub = scope.subOf(b.path.join("/"));
+    return !!sub && mountedSubs.has(sub);
+  };
+  const inUnit = (b: SceneBody) => scope.inBuild(b.path.join("/")) && !b.via?.startsWith("hint:");
+  return {
+    before: new Set(scene.bodies.filter((b) => inUnit(b) && !moved.has(b.key) && !later(b)).map((b) => b.key)),
+    hwBefore: new Set(scene.hardware.filter((h) => scope.inBuild(h.path.join("/")) && !hwMoved.has(h.key) && !later(h)).map((h) => h.key)),
+    subBodies,
+  };
+}
+
+async function illustrated(ctx: BuiltContext, s: SectionContext, scope: UnitScope, x: PlannedStep, st: FigState): Promise<Step> {
+  const parts: NonNullable<Step["parts"]> = [];
+  for (const part of x.parts) {
+    const th = await thumbnail(ctx, s, part.def);
+    parts.push({ name: shortName(part.def), quantity: part.count, ref: part.def.id, letter: part.letter, accent: part.accent, ...(th ? { image: th.file } : {}) });
+  }
+  const figure = await stepFigure(ctx, s, scope, x, st);
+  const notes = [...x.notes];
+  if (x.split) notes.unshift({ level: "tip", text: `Split step: the doc spec's "${x.title}" also covers links made in another unit; this unit does the part listed here.` });
+  if (x.afterTest && !notes.some((n) => /after (the )?(bench )?test|after configuration/i.test(n.text))) notes.unshift({ level: "caution", text: `This step follows the bench test and configuration in the work order (${x.afterTest}).` });
+  return {
+    title: x.title,
+    actions: x.actions,
+    parts,
+    ...(figure ? { figure } : {}),
+    ...(x.connections.length
+      ? {
+          table: {
+            columns: [{ key: "name", label: "Link" }, { key: "from", label: "From" }, { key: "to", label: "To" }, { key: "x", label: "" }, { key: "term", label: "Termination" }],
+            rows: x.connections.map((c) => ({ name: c.name, from: c.from, to: c.to, x: c.crossover ? "× crossover" : "", term: c.termination })),
+          },
+        }
+      : {}),
+    ...(x.torque ? { torque: x.torque } : {}),
+    ...(x.tools.length ? { tools: x.tools } : {}),
+    ...(x.materials.length ? { materials: x.materials } : {}),
+    notes,
+    trace: x.trace,
+  };
+}
+
+/** The step's figure: exploded mates, or the routed cables of its connections; advances the state. */
+async function stepFigure(ctx: BuiltContext, s: SectionContext, scope: UnitScope, x: PlannedStep, st: FigState): Promise<Step["figure"] | undefined> {
+  const scene = ctx.scene;
+  const p = x.plan;
+  const spec = p.spec;
+  const cfg = ctx.sys.config;
+  const iso = cfg.camera?.dir ?? ISO;
+  const E = spec.explode ?? cfg.assembly?.explode ?? 16;
+  const name = `ag-${slug(s.unit.id)}-${String(x.n).padStart(2, "0")}-${slug(spec.id)}`;
+  const context = (exclude: Set<string>): RenderBody[] => [
+    ...scene.bodies.filter((b) => st.before.has(b.key) && !exclude.has(b.key)).map((b) => renderBody(b, "context")),
+    ...scene.hardware.filter((h) => st.hwBefore.has(h.key) && !exclude.has(h.key)).map((h) => renderBody(h, "context")),
+  ];
+  const advance = (keys: string[], hw: string[]) => {
+    for (const k of keys) st.before.add(k);
+    for (const k of hw) st.hwBefore.add(k);
+  };
+  const callouts = (anchors: Record<string, { x: number; y: number }>): Callout[] =>
+    x.parts.filter((pt) => pt.anchor && anchors[pt.anchor]).map((pt) => ({ ...anchors[pt.anchor!], label: pt.letter, accent: pt.accent }));
+
+  if (spec.figure !== "wiring" && spec.figure !== "none" && (p.mates.length || p.placed.length)) {
+    const ex = explode(scene, p.mates.map((m) => m.linkId), E);
+    // a sub-unit mounted here moves as one: its other bodies take the offset of the body the mate placed
+    const follow: SceneBody[] = [];
+    for (const [sub, bs] of st.subBodies) {
+      const off = bs.map((b) => ex.offsets.get(b.key)).find(Boolean);
+      if (!off) continue;
+      for (const b of bs) if (!ex.offsets.has(b.key) && !st.before.has(b.key) && !st.hwBefore.has(b.key) && !p.moving.includes(b) && !p.hardware.includes(b)) {
+        ex.offsets.set(b.key, off);
+        follow.push(b);
+      }
+      void sub;
+    }
+    const followKeys = new Set(follow.map((b) => b.key));
+    const bodies: RenderBody[] = context(followKeys);
+    const anchors: { id: string; p: number[] }[] = [];
+    for (const b of [...p.moving, ...follow.filter((f) => !f.harness)]) {
+      const off = ex.offsets.get(b.key);
+      bodies.push(withOffset(renderBody(b, "normal"), off));
+      anchors.push({ id: `body:${b.key}`, p: centerOf(b, off) });
+    }
+    for (const b of p.placed) {
+      const off = [0, 0, E * 1.6];
+      bodies.push(withOffset(renderBody(b, "normal"), off));
+      anchors.push({ id: `body:${b.key}`, p: centerOf(b, off) });
+    }
+    for (const h of [...p.hardware, ...follow.filter((f) => f.harness)]) {
+      const off = ex.offsets.get(h.key);
+      bodies.push(withOffset(renderBody(h, p.hardware.includes(h) ? "accent" : "normal"), off));
+      anchors.push({ id: `hw:${h.key}`, p: centerOf(h, off) });
+    }
+    const guides = [...ex.guides];
+    for (const b of p.placed) {
+      const c = matTranslation(b.matrix);
+      guides.push({ from: c, to: [c[0], c[1], c[2] + E * 1.6] });
+    }
+    advance([...p.moving, ...p.placed, ...follow.filter((f) => !f.harness)].map((b) => b.key), [...p.hardware, ...follow.filter((f) => f.harness)].map((h) => h.key));
+    if (!bodies.some((b) => b.glb)) return undefined;
+    const r = await s.figure(name, { width: 1900, height: 1000, mode: "lineart", bodies, guides, anchors, camera: { dir: spec.camera?.dir ?? iso, up: spec.camera?.up, margin: spec.camera?.margin ?? 0.1 } });
+    return { file: r.file, width: r.width, height: r.height, callouts: callouts(r.anchors), caption: p.mates.length ? `${x.title}: parts exploded along each joint's axis in stacking order; lettered as in the parts strip.` : `${x.title}: shown lifted above its seat.` };
+  }
+
+  if (spec.figure === "none" || !p.wiring.length) {
+    advance([...p.moving, ...p.placed].map((b) => b.key), p.hardware.map((h) => h.key));
+    return undefined;
+  }
+  // connections: the modules at the ends drawn dark (those already in place), the routed cables in the accent colour
+  const ends = new Set(x.ends);
+  const endBodies = scene.bodies.filter((b) => ends.has(b.path.join("/")) && st.before.has(b.key));
+  const shown = new Set(endBodies.map((b) => b.key));
+  // the camera fits the cables and the parts they join; the rest is context around them
+  const bodies: RenderBody[] = [...context(shown).map((b) => ({ ...b, fit: false })), ...endBodies.map((b) => renderBody(b, "normal"))];
+  const anchors: { id: string; p: number[] }[] = [];
+  let cables = 0;
+  for (const h of x.cables) {
+    const hp = scene.assembly.harnesses.find((x2) => x2.key === h);
+    const glb = hp ? bodyGlb(ctx, hp.def) : undefined;
+    if (!hp || !glb || !scope.inBuild(h)) continue;
+    cables++;
+    bodies.push({ key: `harness:${h}`, glb, matrix: hp.matrix, style: "accent", category: "generic" });
+    const frames = hp.def.interfaces.map((i) => i.geometry?.frame?.origin).filter((o): o is [number, number, number] => Array.isArray(o));
+    const mid: [number, number, number] = [0, 1, 2].map((k) => (frames.length ? frames.reduce((t, o) => t + o[k], 0) / frames.length : 0)) as [number, number, number];
+    anchors.push({ id: `harness:${h}`, p: applyMat4(hp.matrix, mid) });
+  }
+  advance(endBodies.map((b) => b.key), []);
+  if (!cables && !endBodies.some((b) => b.glb)) return undefined;
+  const r = await s.figure(name, { width: 1900, height: 1000, mode: "lineart", bodies, anchors, camera: { dir: spec.camera?.dir ?? [0.35, -0.5, 1.4], up: spec.camera?.up, margin: spec.camera?.margin ?? 0.08 } });
+  return {
+    file: r.file,
+    width: r.width,
+    height: r.height,
+    callouts: callouts(r.anchors),
+    caption: cables ? `${x.title}: the ${cables === 1 ? "cable" : `${cables} cables`} in the accent colour, routed as the model's harness CAD lays ${cables === 1 ? "it" : "them"}; the parts they join drawn dark.` : `${x.title}: the parts the connections join; pads and pins in the table.`,
+  };
+}