@protoboardai/ext-docs 0.0.0-stage → 0.2.0

package/lib/blocks.ts

@@ -0,0 +1,268 @@
+/**
+ * Shared document blocks: headings, tables, figures with vector callouts,
+ * admonitions, and the 2D pad-to-pad wiring diagram.
+ */
+import { relative } from "path";
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+import { resolveLeafEndpoint } from "@deltarobotics/uhd";
+import type { WiringStep } from "@deltarobotics/uhd";
+import { esc } from "./html.ts";
+import type { RenderResult } from "./render/renderer.ts";
+
+export const sec = (num: string, title: string, aside = "", attrs = "") =>
+  `<h1 class="sec" data-num="${esc(num)}" data-toc="${esc(title)}"${attrs}><span class="num">${esc(num)}</span>${esc(title)}${aside ? `<span class="aside">${aside}</span>` : ""}</h1>`;
+
+export const sub = (title: string) => `<h2 class="sub">${esc(title)}</h2>`;
+
+export interface Col {
+  h: string;
+  cls?: string;
+}
+
+export function table(cols: Col[], rows: (string | { group: string })[][] | string[][], opts: { cls?: string; split?: boolean; caption?: string; foot?: string } = {}): string {
+  const head = `<thead><tr>${cols.map((c) => `<th class="${c.cls ?? ""}">${c.h}</th>`).join("")}</tr></thead>`;
+  const body = (rows as any[])
+    .map((r) => {
+      if (!Array.isArray(r) && r.group) return `<tr class="group"><td colspan="${cols.length}">${esc(r.group)}</td></tr>`;
+      return `<tr>${(r as string[]).map((c, i) => `<td class="${cols[i]?.cls ?? ""}">${c}</td>`).join("")}</tr>`;
+    })
+    .join("");
+  const cls = [opts.cls, opts.split ? "split" : ""].filter(Boolean).join(" ");
+  return `<div class="tblock block"><div class="cont-note">${esc(opts.caption ?? "")} (continued)</div><table class="${cls}">${head}<tbody>${body}</tbody></table>${opts.foot ? `<div class="fn">${opts.foot}</div>` : ""}</div>`;
+}
+
+export const groupRow = (group: string) => ({ group });
+
+/** Image path relative to the document, with forward slashes on every system (a URL in the HTML; PB-1018). */
+export const rel = (docDir: string, file: string) => relative(docDir, file).split("\\").join("/");
+
+export function figure(o: { src: string; w: number; h: number; overlay?: string; caption?: string; num?: string; unit?: string; cls?: string; maxHeightMm?: number; widthPct?: number }): string {
+  const style = o.widthPct ? ` style="width:${o.widthPct}%;margin:0 auto"` : "";
+  return `<figure class="block ${o.cls ?? ""}"><div class="figwrap"${style}><img src="${esc(o.src)}" width="${o.w}" height="${o.h}" alt="${esc(o.caption ?? "")}">${
+    o.overlay ? `<svg class="overlay" viewBox="0 0 ${o.w} ${o.h}" preserveAspectRatio="none">${o.overlay}</svg>` : ""
+  }</div>${o.caption ? `<figcaption>${o.num ? `<b>Figure ${esc(o.num)}</b>` : ""}<span>${o.caption}</span>${o.unit ? `<span class="unit">(unit: ${esc(o.unit)})</span>` : ""}</figcaption>` : ""}</figure>`;
+}
+
+export interface CalloutItem {
+  anchor: string;
+  label: string;
+  accent?: boolean;
+  /** Text beside the bubble (named label); omit for number-only bubbles. */
+  text?: string;
+}
+
+/**
+ * Callout bubbles in columns at the figure's left and right edges, straight
+ * 0.5 pt leaders ending in a dot on the part. Sizes are in figure pixels,
+ * scaled from millimetres of the printed figure width.
+ */
+export function callouts(fig: RenderResult, items: CalloutItem[], displayWidthMm: number, opts: { edge?: number; side?: "auto" | "left" | "right" } = {}): string {
+  const k = fig.width / displayWidthMm; // px per printed mm
+  const R = 2.25 * k;
+  const edge = (opts.edge ?? 3) * k + R;
+  const placed = items
+    .map((it) => ({ it, a: fig.anchors[it.anchor] }))
+    // an anchor the renderer could not project (no body drawn around it) has no position
+    .filter((x) => x.a && Number.isFinite(x.a.x) && Number.isFinite(x.a.y))
+    .map((x) => ({ ...x, side: opts.side && opts.side !== "auto" ? opts.side : x.a.x < fig.width / 2 ? "left" : "right" }));
+  const out: string[] = [];
+  for (const side of ["left", "right"] as const) {
+    const col = placed.filter((p) => p.side === side).sort((a, b) => a.a.y - b.a.y);
+    const gap = 2.9 * R;
+    const ys = col.map((p) => Math.min(Math.max(p.a.y, R + 2), fig.height - R - 2));
+    for (let i = 1; i < ys.length; i++) if (ys[i] - ys[i - 1] < gap) ys[i] = ys[i - 1] + gap;
+    const over = ys.length ? ys[ys.length - 1] - (fig.height - R - 2) : 0;
+    if (over > 0) for (let i = 0; i < ys.length; i++) ys[i] -= over;
+    col.forEach((p, i) => {
+      const bx = side === "left" ? edge : fig.width - edge;
+      const by = ys[i];
+      const dx = p.a.x - bx;
+      const dy = p.a.y - by;
+      const len = Math.hypot(dx, dy) || 1;
+      const sx = bx + (dx / len) * R;
+      const sy = by + (dy / len) * R;
+      out.push(`<line class="co-leader" x1="${sx.toFixed(1)}" y1="${sy.toFixed(1)}" x2="${p.a.x.toFixed(1)}" y2="${p.a.y.toFixed(1)}" stroke-width="${(0.18 * k).toFixed(2)}"/>`);
+      out.push(`<circle class="co-dot" cx="${p.a.x.toFixed(1)}" cy="${p.a.y.toFixed(1)}" r="${(0.55 * k).toFixed(1)}"/>`);
+      out.push(`<circle class="co-bubble${p.it.accent ? " acc" : ""}" cx="${bx.toFixed(1)}" cy="${by.toFixed(1)}" r="${R.toFixed(1)}" stroke-width="${(0.18 * k).toFixed(2)}"/>`);
+      out.push(`<text class="co-num${p.it.accent ? " acc" : ""}" x="${bx.toFixed(1)}" y="${(by + 0.95 * k).toFixed(1)}" text-anchor="middle" font-size="${(2.6 * k).toFixed(1)}">${esc(p.it.label)}</text>`);
+      if (p.it.text) {
+        const tx = side === "left" ? bx + R + 1.2 * k : bx - R - 1.2 * k;
+        out.push(`<text class="co-label" x="${tx.toFixed(1)}" y="${(by - 1.4 * k).toFixed(1)}" text-anchor="${side === "left" ? "start" : "end"}" font-size="${(2.3 * k).toFixed(1)}">${esc(p.it.text)}</text>`);
+      }
+    });
+  }
+  return out.join("");
+}
+
+/** A dimension line between two anchors, offset perpendicular by `offsetMm` (printed mm), label bound to a query. */
+export function dimension(fig: RenderResult, a: string, b: string, labelSvg: (x: number, y: number, size: number, rot: number) => string, displayWidthMm: number, offsetMm = 6): string {
+  const A = fig.anchors[a];
+  const B = fig.anchors[b];
+  if (!A || !B) return "";
+  const k = fig.width / displayWidthMm;
+  const dx = B.x - A.x;
+  const dy = B.y - A.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const nx = -dy / len;
+  const ny = dx / len;
+  const o = offsetMm * k;
+  const a2 = { x: A.x + nx * o, y: A.y + ny * o };
+  const b2 = { x: B.x + nx * o, y: B.y + ny * o };
+  const sw = (0.15 * k).toFixed(2);
+  const arrow = (p: { x: number; y: number }, dir: number) => {
+    const ux = (dx / len) * dir;
+    const uy = (dy / len) * dir;
+    const s = 1.6 * k;
+    const w = 0.55 * k;
+    return `<path d="M${p.x},${p.y} L${p.x + ux * s - uy * w},${p.y + uy * s + ux * w} L${p.x + ux * s + uy * w},${p.y + uy * s - ux * w} Z" fill="#d94e00"/>`;
+  };
+  let rot = (Math.atan2(dy, dx) * 180) / Math.PI;
+  if (rot > 90) rot -= 180;
+  if (rot < -90) rot += 180;
+  const mx = (a2.x + b2.x) / 2 + nx * 1.4 * k;
+  const my = (a2.y + b2.y) / 2 + ny * 1.4 * k;
+  return [
+    `<line x1="${A.x}" y1="${A.y}" x2="${a2.x + nx * 1.2 * k}" y2="${a2.y + ny * 1.2 * k}" stroke="#d94e00" stroke-width="${sw}"/>`,
+    `<line x1="${B.x}" y1="${B.y}" x2="${b2.x + nx * 1.2 * k}" y2="${b2.y + ny * 1.2 * k}" stroke="#d94e00" stroke-width="${sw}"/>`,
+    `<line x1="${a2.x}" y1="${a2.y}" x2="${b2.x}" y2="${b2.y}" stroke="#d94e00" stroke-width="${sw}"/>`,
+    arrow(a2, 1),
+    arrow(b2, -1),
+    labelSvg(mx, my, 2.5 * k, rot),
+  ].join("");
+}
+
+// ---------------------------------------------------------------------------
+// Admonitions
+// ---------------------------------------------------------------------------
+
+const ICON = {
+  warning: `<svg viewBox="0 0 24 24"><path d="M12 2.5 1.8 21h20.4L12 2.5z" fill="none" stroke="#c62828" stroke-width="1.8" stroke-linejoin="round"/><path d="M12 9v5.5" stroke="#c62828" stroke-width="2" stroke-linecap="round"/><circle cx="12" cy="17.6" r="1.2" fill="#c62828"/></svg>`,
+  caution: `<svg viewBox="0 0 24 24"><path d="M12 2.5 1.8 21h20.4L12 2.5z" fill="none" stroke="#d94e00" stroke-width="1.8" stroke-linejoin="round"/><path d="M12 9v5.5" stroke="#d94e00" stroke-width="2" stroke-linecap="round"/><circle cx="12" cy="17.6" r="1.2" fill="#d94e00"/></svg>`,
+  tip: `<svg viewBox="0 0 24 24"><circle cx="12" cy="10" r="6.2" fill="none" stroke="#1b1b1b" stroke-width="1.7"/><path d="M9.3 17.5h5.4M10 21h4" stroke="#1b1b1b" stroke-width="1.7" stroke-linecap="round"/></svg>`,
+  info: `<svg viewBox="0 0 24 24"><rect x="3" y="3" width="18" height="18" rx="1" fill="none" stroke="#1b1b1b" stroke-width="1.7"/><path d="M12 10.5V17" stroke="#1b1b1b" stroke-width="2" stroke-linecap="round"/><circle cx="12" cy="7.4" r="1.2" fill="#1b1b1b"/></svg>`,
+};
+const NOTE_LABEL = { warning: "WARNING", caution: "CAUTION", tip: "TIP", info: "NOTE" };
+
+export function note(kind: keyof typeof ICON, html: string): string {
+  return `<div class="note ${kind}">${ICON[kind]}<div><b>${NOTE_LABEL[kind]}</b> ${html}</div></div>`;
+}
+
+// ---------------------------------------------------------------------------
+// Wiring diagram (pad to pad), for links without 3D geometry
+// ---------------------------------------------------------------------------
+
+export interface WireEnd {
+  module: string;
+  pad: string;
+  detail: string;
+}
+
+/** Split "stack:uart1 TX1" into module path, interface and pad label. */
+export function parseEnd(s: string): { path: string; iface: string; pad: string } {
+  const sp = s.indexOf(" ");
+  const head = sp < 0 ? s : s.slice(0, sp);
+  const pad = sp < 0 ? "" : s.slice(sp + 1);
+  const c = head.lastIndexOf(":");
+  return { path: head.slice(0, c), iface: head.slice(c + 1), pad };
+}
+
+/** Leaf module and pad label for a wiring end (follows exports through assemblies). */
+export function leafOf(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined, path: string, iface: string) {
+  const segs = path.split("/");
+  let owner = system;
+  for (const s of segs.slice(0, -1)) {
+    const ref = owner.children?.find((c) => c.id === s);
+    const d = ref && lookup(ref.moduleDefId);
+    if (!d) break;
+    owner = d;
+  }
+  const leaf = resolveLeafEndpoint(owner, { child: segs[segs.length - 1], interfaceId: iface }, lookup);
+  return leaf;
+}
+
+/**
+ * leafOf, or for an end that names no single interface (a link-scoped
+ * composition: `compose` gathers several pads under an id the module does not
+ * declare) the instance itself, with that id as a stand-in interface.
+ */
+export function endOf(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined, path: string, iface: string, name?: string) {
+  const leaf = leafOf(system, lookup, path, iface);
+  if (leaf) return leaf;
+  const segs = path.split("/");
+  let def: ModuleDef | undefined = system;
+  for (const s of segs) {
+    const ref: { moduleDefId: string } | undefined = def?.children?.find((c) => c.id === s);
+    def = ref ? lookup(ref.moduleDefId) : undefined;
+  }
+  if (!def) return undefined;
+  return { path: segs, def, iface: { id: iface, name: name ?? iface, domain: "electrical", exposed: true } as InterfaceDef };
+}
+
+export interface WireRow {
+  a: string;
+  b: string;
+  aDetail?: string;
+  bDetail?: string;
+  crossover?: boolean;
+  signal: string;
+}
+
+/** Two module columns with pad rows and straight wires; crossovers in accent. */
+export function wiringDiagram(o: { aTitle: string; bTitle: string; aSub?: string; bSub?: string; rows: WireRow[]; harness?: string }): string {
+  const W = 520;
+  const rowH = 17;
+  const head = 30;
+  const top = 8 + head + 6;
+  const H = top + o.rows.length * rowH + 18;
+  const boxW = 176;
+  const ax = 2;
+  const bx = W - 2 - boxW;
+  const parts: string[] = [];
+  const clip = (t: string, n: number) => (t.length > n ? t.slice(0, n - 1) + "…" : t);
+  const box = (x: number, title: string, subt?: string) =>
+    `<rect x="${x}" y="8" width="${boxW}" height="${H - 20}" fill="#fff" stroke="#1b1b1b" stroke-width="0.8"/>` +
+    `<rect x="${x}" y="8" width="${boxW}" height="${head}" fill="#1b1b1b"/>` +
+    `<text x="${x + 8}" y="22" font-size="9" font-weight="600" fill="#fff">${esc(clip(title, 30))}</text>` +
+    (subt ? `<text x="${x + 8}" y="33" font-size="6.4" fill="#bdbdbd">${esc(clip(subt, 44))}</text>` : "");
+  parts.push(box(ax, o.aTitle, o.aSub), box(bx, o.bTitle, o.bSub));
+  o.rows.forEach((r, i) => {
+    const y = top + i * rowH + rowH / 2;
+    const col = r.crossover ? "#ff5c00" : "#1b1b1b";
+    parts.push(`<rect x="${ax + boxW - 8}" y="${y - 3.5}" width="8" height="7" fill="${col}"/>`);
+    parts.push(`<rect x="${bx}" y="${y - 3.5}" width="8" height="7" fill="${col}"/>`);
+    parts.push(`<text x="${ax + boxW - 13}" y="${y + 3}" font-size="8" font-weight="600" text-anchor="end" fill="#1b1b1b">${esc(r.a)}</text>`);
+    if (r.aDetail) parts.push(`<text x="${ax + 8}" y="${y + 3}" font-size="6.4" fill="#6f6f6f">${esc(clip(r.aDetail, 30))}</text>`);
+    parts.push(`<text x="${bx + 13}" y="${y + 3}" font-size="8" font-weight="600" fill="#1b1b1b">${esc(r.b)}</text>`);
+    if (r.bDetail) parts.push(`<text x="${bx + boxW - 8}" y="${y + 3}" font-size="6.4" text-anchor="end" fill="#6f6f6f">${esc(clip(r.bDetail, 30))}</text>`);
+    parts.push(`<line x1="${ax + boxW}" y1="${y}" x2="${bx}" y2="${y}" stroke="${col}" stroke-width="${r.crossover ? 1.6 : 1.2}"/>`);
+    parts.push(`<text x="${W / 2}" y="${y - 3}" font-size="6.4" text-anchor="middle" fill="${r.crossover ? "#d94e00" : "#6f6f6f"}">${esc(r.signal)}${r.crossover ? " · crossover" : ""}</text>`);
+  });
+  if (o.harness) parts.push(`<text x="${W / 2}" y="${H - 4}" font-size="6.6" text-anchor="middle" fill="#6f6f6f">via ${esc(o.harness)}</text>`);
+  return `<svg class="wiring" viewBox="0 0 ${W} ${H}" width="100%" xmlns="http://www.w3.org/2000/svg" font-family="inherit">${parts.join("")}</svg>`;
+}
+
+export function wiringRows(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined, steps: WiringStep[]) {
+  // group by the pair of leaf modules
+  const groups = new Map<string, { a: ModuleDef; b: ModuleDef; aPath: string; bPath: string; rows: WireRow[]; harness?: string; links: string[] }>();
+  for (const s of steps) {
+    const ea = parseEnd(s.a);
+    const eb = parseEnd(s.b);
+    const la = leafOf(system, lookup, ea.path, ea.iface);
+    const lb = leafOf(system, lookup, eb.path, eb.iface);
+    if (!la || !lb) continue;
+    const key = `${la.path.join("/")}|${lb.path.join("/")}`;
+    const g = groups.get(key) ?? { a: la.def, b: lb.def, aPath: la.path.join("/"), bPath: lb.path.join("/"), rows: [], harness: s.harness, links: [] };
+    g.links.push(s.linkId);
+    if (s.connections.length) {
+      for (const c of s.connections) {
+        const pa = parseEnd(c.from);
+        const pb = parseEnd(c.to);
+        g.rows.push({ a: pa.pad || pa.iface, b: pb.pad || pb.iface, signal: s.name, crossover: c.crossover, aDetail: la.iface.name, bDetail: lb.iface.name });
+      }
+    } else {
+      g.rows.push({ a: String(la.iface.pin ?? la.iface.id), b: String(lb.iface.pin ?? lb.iface.id), signal: s.name, aDetail: la.iface.name, bDetail: lb.iface.name });
+    }
+    groups.set(key, g);
+  }
+  return [...groups.values()];
+}

package/lib/bom.ts

@@ -0,0 +1,126 @@
+/**
+ * The bill of materials the documents publish: the system tree walked
+ * (children × quantity, through assemblies, groups and harnesses), one row
+ * per part (per part and MPN for a series passive placed at several values,
+ * from `ChildModuleRef.overrides`) with its primary manufacturer source and its verification
+ * summary, so every line can be traced. Moved with the documents generator
+ * from UHD's scripts/bom.ts; evidence comes from the project's evidence
+ * folders (model.ts `evidenceDirs`). `tech-docs` writes it to
+ * `docs/<system-id>-bom.json`, and `tech-docs-verify` checks it against the
+ * live model. (The project's plain BOM export is ext-hardware's `bom`.)
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { ModuleLookup } from "@deltarobotics/uhd";
+import { formatPassive, placementPart } from "@protoboardai/core";
+
+export interface BomRow {
+  line: number;
+  partId: string;
+  name: string;
+  manufacturer?: string;
+  partNumber?: string;
+  /** A passive's value as placed, e.g. "4.7 kΩ ±1 %". */
+  value?: string;
+  quantity: number;
+  /** Units per retail pack, when the part is sold in packs. */
+  packQuantity?: number;
+  buy: "purchase" | "included" | "fabricate";
+  includedWith?: string;
+  usedBy: string[];
+  source?: string;
+  verification?: string;
+  assumptions: number;
+  openGaps: number;
+}
+
+function trait(def: ModuleDef, type: string, key: string): unknown {
+  for (const t of def.traits ?? []) {
+    const params = t.params as Record<string, unknown> | undefined;
+    if (t.type === type && params && key in params) return params[key];
+  }
+  return undefined;
+}
+
+function evidence(dirs: string[], def?: ModuleDef): { source?: string; verification?: string; assumptions: number; openGaps: number } {
+  const find = (name: string) => dirs.map((d) => join(d, name)).find((f) => existsSync(f));
+  // system-level hardware without a research folder cites its supplier listing in a usage_note
+  let source: string | undefined = def?.traits?.find((t) => t.type === "usage_note" && typeof t.params?.source === "string")?.params?.source as string | undefined;
+  const sources = find("sources.json");
+  if (sources) {
+    const rows = JSON.parse(readFileSync(sources, "utf8")) as Array<Record<string, unknown>>;
+    source = String((rows.find((r) => r.authority === "manufacturer") ?? rows[0])?.url ?? "");
+  }
+  const verification = find("verification.json");
+  if (!verification) {
+    const count = (type: string) => def?.traits?.filter((t) => t.type === type).length ?? 0;
+    return { source, assumptions: count("assumption"), openGaps: count("data_gap") };
+  }
+  const v = JSON.parse(readFileSync(verification, "utf8"));
+  return {
+    source,
+    // older records state an audit without counts ({ by, result }); a self-audit
+    // (PB-862: audit.independent false) is not shown as an audit
+    verification: v.audit
+      ? `${v.audit.independent === false ? "self-audited" : "audited"}${typeof v.audit.checked === "number" ? ` ${v.audit.confirmed}/${v.audit.checked}` : ""}`
+      : "not audited",
+    assumptions: v.assumptions?.length ?? 0,
+    openGaps: v.data_gaps?.length ?? 0,
+  };
+}
+
+/** `evidenceDirs(id)`: the folders that may hold a part's sources.json and verification.json. */
+/** A module designed in the project: it carries its native design (an artifact with role "source"). */
+export const designed = (def: ModuleDef) => (def.artifacts ?? []).some((a) => a.role === "source");
+
+export function buildBom(system: ModuleDef, lookup: ModuleLookup, evidenceDirs: (id: string) => string[]): BomRow[] {
+  const rows = new Map<string, BomRow>();
+
+  const visit = (def: ModuleDef, multiplier: number, path: string) => {
+    for (const ref of def.children ?? []) {
+      const child = lookup(ref.moduleDefId);
+      if (!child) throw new Error(`${path}/${ref.id}: unknown module ${ref.moduleDefId}`);
+      const qty = multiplier * (ref.quantity ?? 1);
+      const childPath = path ? `${path}/${ref.id}` : ref.id;
+      if (child.children?.length) {
+        // assemblies, groups and harness kits: their contents are the line items. A module designed in the project
+        // (it has a native design: a board, a housing with its inserts) is made, so it is a line item too, with its parts
+        if (designed(child)) add(child, ref, qty, childPath, "fabricate");
+        visit(child, qty, childPath);
+        continue;
+      }
+      add(child, ref, qty, childPath);
+    }
+  };
+  const add = (child: ModuleDef, ref: { overrides?: Record<string, unknown> }, qty: number, childPath: string, buyAs?: BomRow["buy"]) => {
+      const includedWith = trait(child, "usage_note", "included_with") as string | undefined;
+      const custom = /\(custom\)/i.test(child.manufacturer ?? "");
+      const placed = placementPart(child, ref.overrides);
+      const value = placed.value ? formatPassive(placed.value) : undefined;
+      const key = `${child.id}\u0000${placed.mpn ?? value ?? ""}`;
+      const row = rows.get(key) ?? {
+        line: 0,
+        partId: child.id,
+        name: child.name,
+        manufacturer: child.manufacturer,
+        partNumber: placed.mpn,
+        ...(value ? { value } : {}),
+        quantity: 0,
+        packQuantity: trait(child, "performance", "pack_quantity") as number | undefined,
+        buy: buyAs ?? (custom ? "fabricate" : includedWith ? "included" : "purchase"),
+        includedWith,
+        usedBy: [],
+        ...evidence(evidenceDirs(child.id), child),
+      };
+      row.quantity += qty;
+      row.usedBy.push(childPath);
+      rows.set(key, row);
+  };
+  visit(system, 1, "");
+
+  const order = { purchase: 0, fabricate: 1, included: 2 };
+  return [...rows.values()]
+    .sort((a, b) => order[a.buy] - order[b.buy] || a.name.localeCompare(b.name) || (a.partNumber ?? "").localeCompare(b.partNumber ?? ""))
+    .map((row, i) => ({ ...row, line: i + 1 }));
+}

package/lib/build.ts

@@ -0,0 +1,202 @@
+/**
+ * Build technical documents for a Protoboard project's system (the
+ * uhd-tech-docs skill; `protoboard run tech-docs`). Moved from UHD's
+ * scripts/docs/build.ts (PB-801) and made to read a project instead of a
+ * library system folder.
+ *
+ * Writes into the project's docs/:
+ *   <system-id>-datasheet.html / .pdf / .values.json
+ *   <system-id>-assembly-guide.html / .pdf / .values.json
+ *   <system-id>-bom.json   the BOM the documents publish (bom.ts)
+ *   images/                figures rendered from the GLB artifacts (cached by content)
+ *   test-data/             stand-in (and measured) test data
+ *   .review/<doc>/         page PNGs for visual review (gitignored)
+ *   assets/fonts/          fonts copied at build time (gitignored)
+ *
+ * Every value is a query into the model (values.ts); run verify.ts afterwards.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { execFileSync } from "child_process";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import type { Project } from "@protoboardai/core";
+import { bomFile, buildContext, type BuiltContext } from "./context.ts";
+import { Doc, shell, type DocMeta } from "./html.ts";
+import { FigureRenderer } from "./render/renderer.ts";
+import { projectPath } from "./render/server.ts";
+import { buildDatasheet, provenanceSection } from "./docs/datasheet.ts";
+import { buildAssemblyGuide, assemblyProvenance } from "./docs/assembly.ts";
+import { imgPath, type BuildEnv } from "./docs/common.ts";
+import { writeStandins } from "./standin.ts";
+
+export const DOC_TYPES = {
+  datasheet: { suffix: "datasheet", title: "Datasheet", code: "DS" },
+  assembly: { suffix: "assembly-guide", title: "Assembly guide", code: "AG" },
+} as const;
+export type DocType = keyof typeof DOC_TYPES;
+
+/** Kode Mono (SIL Open Font License 1.1), shipped in this package: `fonts/`, with its licence. */
+export const BUNDLED_FONTS = fileURLToPath(new URL("../fonts/", import.meta.url));
+
+/** The font files documents use: Kode Mono, its Bold for display text. */
+export const DOC_FONT = /^KodeMono-.*\.ttf$/;
+
+/**
+ * The folder named by $PROTOBOARD_DOC_FONTS (or the older $UHD_DOC_FONTS), if
+ * any: a file there replaces the bundled Kode Mono file of the same name.
+ * Documents need none of it.
+ */
+export const fontsDir = (): string | undefined => process.env.PROTOBOARD_DOC_FONTS || process.env.UHD_DOC_FONTS || undefined;
+
+/**
+ * The document font files, by name, each with where it is read from: the
+ * bundled Kode Mono, with any file of the same name in $PROTOBOARD_DOC_FONTS
+ * taking its place. The default never depends on
+ * another checkout, so every machine without the variable renders the same
+ * documents (PB-809).
+ */
+export function docFonts(): { file: string; path: string }[] {
+  const byName = new Map<string, string>();
+  for (const dir of [BUNDLED_FONTS, fontsDir()]) {
+    if (!dir || !existsSync(dir)) continue;
+    for (const f of readdirSync(dir).sort()) if (DOC_FONT.test(f)) byName.set(f, join(dir, f));
+  }
+  return [...byName.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([file, path]) => ({ file, path }));
+}
+
+/** Fonts are copied next to the documents at build time (not committed). */
+function copyFonts(docDir: string): boolean {
+  const dst = join(docDir, "assets", "fonts");
+  mkdirSync(dst, { recursive: true });
+  writeFileSync(join(docDir, "assets", ".gitignore"), "# Fonts are copied in at build time: Kode Mono from @protoboardai/ext-docs.\nfonts/\n");
+  const env = fontsDir();
+  if (env && !existsSync(env)) console.warn(`fonts: PROTOBOARD_DOC_FONTS=${env} not found; using the bundled Kode Mono only`);
+  const fonts = docFonts();
+  for (const f of fonts) copyFileSync(f.path, join(dst, f.file));
+  return fonts.length > 0;
+}
+
+export interface BuildResult {
+  type: DocType;
+  /** Project-relative files. */
+  html: string;
+  pdf?: string;
+  values: string;
+  pages: number;
+  overflow: number[];
+  boundValues: number;
+}
+
+export interface BuildReport {
+  docs: BuildResult[];
+  /** Project-relative files this build wrote and the documents use (images, test data, BOM). */
+  files: string[];
+  standins: { written: string[]; kept: string[] };
+  figures: { rendered: number; reused: number };
+  fonts: boolean;
+}
+
+export async function buildDocs(p: Project, opts: { only?: DocType; pdf?: boolean; standins?: boolean; log?: (line: string) => void } = {}): Promise<BuildReport> {
+  const log = opts.log ?? ((l: string) => console.log(l));
+  let ctx: BuiltContext = await buildContext(p);
+  let standins = { written: [] as string[], kept: [] as string[] };
+  if (opts.standins !== false) {
+    standins = await writeStandins(ctx);
+    if (standins.written.length || standins.kept.length) log(`test data: stand-ins ${standins.written.join(", ") || "none"}; measured ${standins.kept.join(", ") || "none"}`);
+    ctx = await buildContext(p);
+  }
+  if (ctx.testErrors.length) throw new Error(`test data invalid:\n  ${ctx.testErrors.join("\n  ")}`);
+  const docDir = ctx.sys.absDocs;
+  mkdirSync(docDir, { recursive: true });
+  // the BOM the documents publish is the live model's; verify compares the committed file with the model again
+  // (the context is rebuilt from the written file: its value resolver reads the BOM it was built with, and a stale file
+  // would leave the document's bound BOM values one model behind its tables)
+  const bomPath = join(ctx.sys.root, bomFile(ctx.sys));
+  const liveJson = JSON.stringify(ctx.liveBom, null, 2) + "\n";
+  const stale = !existsSync(bomPath) || readFileSync(bomPath, "utf8") !== liveJson;
+  writeFileSync(bomPath, liveJson);
+  if (stale) ctx = await buildContext(p);
+  ctx = { ...ctx, generatedBom: ctx.liveBom, bom: ctx.liveBom };
+  const imgDir = join(docDir, "images");
+  mkdirSync(imgDir, { recursive: true });
+  writeFileSync(join(docDir, ".gitignore"), "# build byproducts (@protoboardai/ext-docs)\n.review/\nimages/.render-cache.json\n");
+  const fonts = copyFonts(docDir);
+  const r = new FigureRenderer(imgDir, ctx.sys.roots);
+  const date = new Date().toISOString().slice(0, 10);
+  const results: BuildResult[] = [];
+  const docServed = projectPath(ctx.sys.docsDir);
+  try {
+    for (const type of Object.keys(DOC_TYPES) as DocType[]) {
+      if (opts.only && opts.only !== type) continue;
+      const t = DOC_TYPES[type];
+      const meta: DocMeta = {
+        title: ctx.sys.config.title ?? ctx.sys.system.name,
+        docType: t.title,
+        docId: `${ctx.sys.config.docId ?? ctx.sys.system.id.toUpperCase()}-${t.code}`,
+        revision: ctx.sys.config.revision ?? "A",
+        date,
+        system: ctx.sys.name,
+      };
+      const doc = new Doc(ctx, meta);
+      const env: BuildEnv = { ctx, doc, r, docDir, docRel: ctx.sys.docsDir, img: imgPath(docDir), counters: { fig: 0 } };
+      const body = type === "datasheet" ? (await buildDatasheet(env)) + provenanceSection(env) : (await buildAssemblyGuide(env)) + assemblyProvenance(env);
+      const name = `${ctx.sys.system.id}-${t.suffix}`;
+      const html = doc.fillLegends(shell(meta, body, { fontsHref: "assets/fonts" }));
+      const htmlPath = join(docDir, `${name}.html`);
+      writeFileSync(htmlPath, html);
+      const pag = await r.paginate(`${docServed}/${name}.html`);
+      writeFileSync(htmlPath, pag.html);
+      writeFileSync(
+        join(docDir, `${name}.values.json`),
+        JSON.stringify(
+          {
+            document: `${name}.html`,
+            system: ctx.sys.system.id,
+            project: ctx.sys.name,
+            docId: meta.docId,
+            generated: date,
+            values: [...doc.values.values()].map((v) => ({ q: v.q, f: v.f, text: v.text, status: v.status, unit: v.unit, source: v.source, formula: v.formula, inputs: v.inputs, note: v.note })),
+          },
+          null,
+          1,
+        ) + "\n",
+      );
+      let pdfRel: string | undefined;
+      if (opts.pdf !== false) {
+        const pdfPath = join(docDir, `${name}.pdf`);
+        writeFileSync(pdfPath, await r.printPdf(`${docServed}/${name}.html`));
+        pdfRel = `${ctx.sys.docsDir}/${name}.pdf`;
+        const review = join(docDir, ".review", name);
+        rmSync(review, { recursive: true, force: true });
+        mkdirSync(review, { recursive: true });
+        try {
+          execFileSync("pdftoppm", ["-r", "70", "-png", pdfPath, join(review, "page")]);
+        } catch {
+          console.warn("pdftoppm not available: no review PNGs");
+        }
+      }
+      results.push({
+        type,
+        html: `${ctx.sys.docsDir}/${name}.html`,
+        pdf: pdfRel,
+        values: `${ctx.sys.docsDir}/${name}.values.json`,
+        pages: pag.pages,
+        overflow: pag.overflow,
+        boundValues: doc.values.size,
+      });
+      log(`${name}: ${pag.pages} pages, ${doc.values.size} bound values${pag.overflow.length ? `, OVERFLOW on pages ${pag.overflow.join(", ")}` : ""}`);
+    }
+  } finally {
+    log(`figures: ${r.rendered} rendered, ${r.reused} reused`);
+    await r.close();
+  }
+  // files only: a project may keep its own pictures in a subfolder (docs/images/viewer)
+  const rel = (dir: string) => (existsSync(join(docDir, dir)) ? readdirSync(join(docDir, dir), { withFileTypes: true }).filter((f) => f.isFile() && !f.name.startsWith(".")).map((f) => f.name).sort().map((f) => `${ctx.sys.docsDir}/${dir}/${f}`) : []);
+  return {
+    docs: results,
+    files: [bomFile(ctx.sys), ...rel("images"), ...rel("test-data")],
+    standins,
+    figures: { rendered: r.rendered, reused: r.reused },
+    fonts,
+  };
+}