@protoboardai/ext-release 0.0.0-stage → 0.2.0

package/lib/cutlist.ts

@@ -0,0 +1,70 @@
+/**
+ * A wire harness's cut list from its UHD facts (tool-neutral): one row per
+ * conductor, from the ends' connector positions through the harness's
+ * internal conductor link, with the cable facts (`performance` kind cable:
+ * installed and supplied length, gauge) and build facts (`cable_build`:
+ * colour per position of the first end, lay, strip length).
+ */
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+import { toCsv } from "./util.ts";
+
+export interface CutRow {
+  conductor: number;
+  from: string;
+  to: string;
+  colour: string;
+  length_mm: number | null;
+  supplied_length_mm: number | null;
+  gauge_awg: number | null;
+  od_mm: number | null;
+  strip_mm: number | null;
+  lay: string;
+  note: string;
+}
+
+export const CUT_COLUMNS = ["conductor", "from", "to", "colour", "length_mm", "supplied_length_mm", "gauge_awg", "od_mm", "strip_mm", "lay", "note"];
+
+const params = (def: ModuleDef, type: string, kind?: string) =>
+  (def.traits ?? []).find((t) => t.type === type && (!kind || (t.params as Record<string, unknown> | undefined)?.kind === kind))?.params as Record<string, unknown> | undefined;
+const n = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/** True for a cable: a wire harness with conductors between connector ends. */
+export const isCable = (def: ModuleDef) => def.kind === "harness" && (def as { topology?: string }).topology === "wire";
+
+export function cutList(def: ModuleDef): CutRow[] {
+  const cable = params(def, "performance", "cable") ?? {};
+  const build = params(def, "cable_build") ?? {};
+  const wires = (def.links ?? []).find((l) => "self" in l.a && "self" in l.b);
+  const ends = (def.interfaces ?? []).filter((i) => i.slots?.length);
+  const a = wires ? ends.find((i) => i.id === wires.a.interfaceId) : ends[0];
+  const b = wires ? ends.find((i) => i.id === wires.b.interfaceId) : ends[1];
+  const count = n(cable.conductors) ?? a?.slots?.length ?? 0;
+  const pairs: [string, string][] = wires?.childLinks?.length
+    ? wires.childLinks.map((c) => [c.a, c.b])
+    : Array.from({ length: count }, (_, i) => [`p${i + 1}`, `p${i + 1}`]);
+  const label = (end: InterfaceDef | undefined, slot: string) => {
+    const s = end?.slots?.find((x) => x.id === slot);
+    return end ? `${end.name ?? end.id} ${s?.label ?? slot}` : slot;
+  };
+  const colours = Array.isArray(build.colors) ? (build.colors as string[]) : [];
+  const lay = [build.bundle, build.twist_pitch_mm ? `${build.twist_pitch_mm} mm pitch` : ""].filter(Boolean).join(", ");
+  const position = (slot: string, i: number) => {
+    const k = a?.slots?.findIndex((s) => s.id === slot) ?? -1;
+    return k >= 0 ? k : i;
+  };
+  return pairs.map(([x, y], i) => ({
+    conductor: i + 1,
+    from: label(a, x),
+    to: label(b, y),
+    colour: colours[position(x, i)] ?? "",
+    length_mm: n(cable.length_mm),
+    supplied_length_mm: n(cable.supplied_length_mm),
+    gauge_awg: n(cable.wire_gauge_awg),
+    od_mm: n(build.od_mm),
+    strip_mm: n(build.strip_mm),
+    lay,
+    note: i === 0 && typeof cable.length_basis === "string" ? `length ${cable.length_basis}` : "",
+  }));
+}
+
+export const cutListCsv = (def: ModuleDef) => toCsv(CUT_COLUMNS, cutList(def) as unknown as Record<string, unknown>[]);

package/lib/documents.ts

@@ -0,0 +1,287 @@
+/**
+ * The package's documents: one per unit and section (PDF), the overview
+ * (00-overview.pdf, with the traceability appendix) and index.html, which
+ * holds all of it with navigation by unit and by section.
+ */
+import { readTemplate } from "@protoboardai/ext-docs/html";
+import type { ProductStatement } from "@protoboardai/core";
+import { blocksHtml, esc, sec, sub } from "./html.ts";
+import { productBlocks } from "./product.ts";
+import type { ReleaseManifest } from "./manifest.ts";
+import { SECTION_DOCS, SECTIONS, type Block, type PackageFile, type SectionContribution, type SectionId, type Unit } from "./types.ts";
+
+export interface Contributed extends SectionContribution {
+  extension: string;
+}
+
+export interface DocSet {
+  project: string;
+  title: string;
+  description?: string;
+  /** What the product is, as the project states it (docs/product.json): the first page. */
+  product: ProductStatement;
+  version: string;
+  date: string;
+  units: Unit[];
+  /** unit id → section → contributions in order. */
+  content: Map<string, Map<SectionId, Contributed[]>>;
+  /** unit id → figure (package path and size). */
+  figures: Map<string, { file: string; width: number; height: number; bodies: number }>;
+}
+
+/** Package path of a unit's document. */
+export const docPath = (u: Unit, s: SectionId) => `${u.folder}/${SECTION_DOCS[s].file}.pdf`;
+/** Document id: PROJECT-UNIT-CODE; a unit named after the project's module ("quadcopter-5in-arm") drops the repeated project prefix. */
+export const docId = (set: DocSet, u: Unit, s: SectionId | "overview") => {
+  const project = set.project.toUpperCase();
+  const unit = u.kind === "root" ? "SYS" : u.id.toUpperCase();
+  const short = unit.startsWith(`${project}-`) && unit.length > project.length + 1 ? unit.slice(project.length + 1) : unit;
+  return `${project}-${short}-${s === "overview" ? "OV" : SECTION_DOCS[s].code}`;
+};
+
+const heroBlock = (set: DocSet, u: Unit): Block[] => {
+  const f = set.figures.get(u.id);
+  return f ? [{ kind: "image", file: f.file, width: f.width, height: f.height, caption: `${u.name}, assembled from the model (${f.bodies} placed bodies${u.kind === "module" ? ", one build" : ""}).` }] : [];
+};
+
+/** The flow body of one unit document. */
+export function unitDocBody(set: DocSet, u: Unit, s: SectionId, img: (p: string) => string): string {
+  const parts = set.content.get(u.id)?.get(s) ?? [];
+  const main = parts.filter((c) => !c.title);
+  const titled = parts.filter((c) => c.title);
+  const head = `<div class="doc-head block"><span><b>${esc(u.name)}</b></span><span>${esc(u.kind === "root" ? "system (final assembly)" : u.folder)}</span><span>release ${esc(set.version)}</span>${u.kind !== "root" ? `<span>× ${u.perProduct} per product</span>` : ""}</div>`;
+  const out = [sec("1", SECTION_DOCS[s].title, esc(u.name)), head];
+  const blocks = [...(s === "spec" ? heroBlock(set, u) : []), ...main.flatMap((c) => c.blocks)];
+  out.push(blocks.length ? blocksHtml(blocks, img) : `<p class="muted block">No content was contributed to this section for this unit.</p>`);
+  titled.forEach((c, i) => out.push(sec(String(i + 2), c.title!, `<span class="muted">${esc(c.extension)}</span>`, ' data-break="before"'), blocksHtml(c.blocks, img)));
+  return out.join("\n");
+}
+
+const unitRow = (u: Unit) => ({ unit: u.id, name: u.name, qty: u.kind === "root" ? 1 : u.perProduct, into: u.parents.join(", ") || "—", folder: `${u.folder}/` });
+
+/** The overview's body: cover, product, units, order of work, totals, index of files, traceability appendix. */
+export function overviewBody(set: DocSet, m: ReleaseManifest, totals: { label: string; value: string; sub?: string }[], img: (p: string) => string): string {
+  const root = set.units.find((u) => u.kind === "root")!;
+  const hero = set.figures.get(root.id);
+  const words = set.title.split(" ");
+  const last = words.pop();
+  const cover = `<div class="coverpage" data-page="cover">
+  <div class="cover-top"><div class="grid-bg"></div>
+    <div class="cover-brand">PR<b>0</b>TOBOARD <span class="muted">·</span> UHD</div>
+    <div class="cover-rev"><span>Release ${esc(set.version)}</span><span>${esc(set.date)}</span><span>${esc(docId(set, root, "overview"))}</span></div>
+    <div class="cover-kicker">Manufacturing package · Overview</div>
+    <div class="cover-title">${esc(words.join(" "))} <span class="accent">${esc(last)}</span></div>
+    <div class="cover-sub">${esc(set.product.summary ?? set.description ?? "")}</div>
+    ${hero ? `<div class="cover-hero"><img src="${esc(img(hero.file))}" width="${hero.width}" height="${hero.height}" alt="${esc(set.title)}"></div><div class="cover-herocap">Assembled from the model: ${hero.bodies} placed bodies</div>` : ""}
+  </div>
+  <div class="cover-bottom">${blocksHtml([{ kind: "figures", items: totals }], img)}
+    <p class="small">Everything needed to order, make, assemble and check this product, laid out by unit. Start with the order of work below; index.html holds the whole package in one place.</p></div>
+  <div class="cover-foot"><span class="pg-brand">PR<b>0</b>TOBOARD · UHD</span><span>Generated from the UHD model of <code>${esc(set.project)}</code> by @protoboardai/ext-release</span><span class="right">Release ${esc(set.version)} · ${esc(set.date)}</span></div>
+</div>`;
+  const order: Block[] = [
+    {
+      kind: "list",
+      ordered: true,
+      items: [
+        "Order everything on system/ordering-list.csv (system/bom.pdf: ordering list) and place the fabrication orders in each unit's work order.",
+        ...set.units.filter((u) => u.kind !== "root").map((u) => `Build ${u.perProduct} × ${u.name} (${u.folder}/): work order, assembly guide, then the test plan.`),
+        `Final assembly (system/): assemble ${set.units.length > 1 ? "the units into the " : "the "}${root.name} and test it, in the order of the system work order's operations; it says where each check of the system test plan runs (the bench test and any configuration come before the steps that must follow them, such as fitting propellers).`,
+      ],
+    },
+  ];
+  const files: Block[] = [
+    {
+      kind: "table",
+      columns: [{ key: "path", label: "File" }, { key: "unit", label: "Unit" }, { key: "role", label: "Role" }, { key: "bytes", label: "Bytes", align: "right" }],
+      rows: [
+        ...[["00-overview.pdf", "this overview"], ["index.html", "the whole package, by unit and by section"], ["manifest.json", "release manifest: every file's digest"]].map(([path, role]) => ({ path, unit: "", role, bytes: "" })),
+        ...m.files.filter((f) => !f.path.startsWith("assets/")).map((f) => ({ path: f.path, unit: f.unit ?? "", role: f.role, bytes: f.bytes })),
+        // figures and fonts the documents use, one line per folder
+        ...[...new Set(m.files.filter((f) => f.path.startsWith("assets/")).map((f) => f.path.slice(0, f.path.lastIndexOf("/") + 1)))].map((dir) => {
+          const these = m.files.filter((f) => f.path.startsWith(dir) && !f.path.slice(dir.length).includes("/"));
+          return { path: `${dir} (${these.length} files)`, unit: "", role: [...new Set(these.map((f) => f.role))].join(", "), bytes: these.reduce((t, f) => t + f.bytes, 0) };
+        }),
+      ],
+      caption: "Files",
+      note: "Digests of every file are in manifest.json; the documents' own digests are only there, since a document cannot list its own.",
+    },
+  ];
+  return [
+    cover,
+    // the first page after the cover: what it is, its features, what it does, what it must meet (PB-935)
+    sec("1", "The product", esc(set.title)),
+    blocksHtml(productBlocks(set.product, set.description), img),
+    sec("2", "Units and how they fit", "", ' data-break="before"'),
+    blocksHtml(
+      [
+        { kind: "paragraph", text: "Each unit has its own folder with a spec sheet, bill of materials, work order, assembly guide and test plan. A unit is built separately and assembled into the unit above it; the system folder is final assembly." },
+        { kind: "table", columns: [{ key: "unit", label: "Unit" }, { key: "name", label: "Module" }, { key: "qty", label: "Per product", align: "right" }, { key: "into", label: "Assembled into" }, { key: "folder", label: "Folder" }], rows: set.units.map(unitRow) },
+      ],
+      img,
+    ),
+    sec("3", "Order of work"),
+    blocksHtml(order, img),
+    sec("4", "Index", "", ' data-break="before"'),
+    blocksHtml(files, img),
+    sec("A", "Traceability", "", ' data-break="before"'),
+    blocksHtml(traceability(m), img),
+  ].join("\n");
+}
+
+/** The release manifest in readable form (overview appendix and index.html page). */
+export function traceability(m: ReleaseManifest): Block[] {
+  const short = (d?: string) => (d ? d.replace(/^sha256:/, "").slice(0, 16) : "");
+  return [
+    {
+      kind: "keyvalues",
+      rows: [
+        { label: "Project", value: `${m.project.name} (root ${m.project.root})` },
+        { label: "Release", value: `${m.version} · ${m.date}` },
+        { label: "Source", value: m.source ? `git ${m.source.commit.slice(0, 12)}${m.source.dirty.length ? ` with ${m.source.dirty.length} uncommitted change(s)` : ""}` : "not a git work tree" },
+        { label: "Model", value: `${m.model.bundle} · ${short(m.model.digest)}` },
+        { label: "Framework", value: `@protoboardai/core ${m.framework.protoboard} · @deltarobotics/uhd ${m.framework.uhd.version ?? "?"}${m.framework.uhd.revision ? ` (${m.framework.uhd.revision.slice(0, 12)})` : ""}` },
+        { label: "Check", value: `${m.check.errors} errors, ${m.check.warnings} warnings, ${m.check.info} info at release time` },
+      ],
+    },
+    { kind: "heading", text: "Parts" },
+    {
+      kind: "table",
+      columns: [{ key: "id", label: "Part" }, { key: "tier", label: "Tier" }, { key: "rev", label: "Revision / source" }, { key: "digest", label: "Digest" }],
+      rows: m.parts.map((x) => ({ id: x.id, tier: x.tier, rev: x.revision !== undefined ? `${x.service ?? x.provider ?? "catalog"} rev ${x.revision}` : x.source, digest: short(x.digest) })),
+    },
+    { kind: "heading", text: "Provider outputs" },
+    {
+      kind: "table",
+      columns: [{ key: "module", label: "Module" }, { key: "cap", label: "Capability" }, { key: "provider", label: "Provider" }, { key: "tools", label: "Tools" }, { key: "record", label: "Operation record" }],
+      rows: m.outputs.map((o) => ({ module: o.module, cap: o.capability, provider: `${o.provider.id}@${o.provider.version}`, tools: o.tools.map((t) => t.detail ?? t.id).join(", "), record: o.record })),
+    },
+    ...(m.generated.length
+      ? ([
+          { kind: "heading", text: "Other generated files" },
+          { kind: "table", columns: [{ key: "path", label: "File" }, { key: "op", label: "Operation" }, { key: "record", label: "Record" }, { key: "digest", label: "Digest" }], rows: m.generated.map((g) => ({ path: g.path, op: `${g.extension} ${g.operation}`, record: g.record ?? "", digest: short(g.digest) })) },
+        ] as Block[])
+      : []),
+    ...(m.check.findings.length
+      ? ([
+          { kind: "heading", text: "Warnings at release time" },
+          { kind: "table", columns: [{ key: "code", label: "Code" }, { key: "message", label: "Finding" }], rows: m.check.findings.map((f) => ({ code: f.code, message: f.message })) },
+        ] as Block[])
+      : []),
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// index.html
+// ---------------------------------------------------------------------------
+
+const anchor = (u: Unit, s?: SectionId) => `u-${u.id}${s ? `-${s}` : ""}`;
+
+export function indexHtml(set: DocSet, m: ReleaseManifest, totals: { label: string; value: string; sub?: string }[], files: PackageFile[]): string {
+  const img = (p: string) => p;
+  const css = readTemplate("doc.css").replace(/__FONTS__/g, "assets/fonts");
+  const nav = [
+    `<a href="#overview">Overview</a>`,
+    `<div class="nav-h">By unit</div>`,
+    ...set.units.map((u) => `<a href="#${anchor(u)}">${esc(u.kind === "root" ? `system · ${u.name}` : `${u.id} · ${u.name}`)}</a><div class="nav-sub">${SECTIONS.map((s) => `<a href="#${anchor(u, s)}">${esc(SECTION_DOCS[s].title)}</a>`).join("")}</div>`),
+    `<div class="nav-h">By section</div>`,
+    ...SECTIONS.map((s) => `<a href="#s-${s}">${esc(SECTION_DOCS[s].title)}</a><div class="nav-sub">${set.units.map((u) => `<a href="#${anchor(u, s)}">${esc(u.id)}</a>`).join("")}</div>`),
+    `<div class="nav-h">Package</div>`,
+    `<a href="#files">Files</a>`,
+    `<a href="#traceability">Traceability</a>`,
+  ].join("\n");
+  const units = set.units
+    .map((u) => {
+      const unitFiles = files.filter((f) => f.unit === u.id && f.path.startsWith(`${u.folder}/files/`));
+      return `<section class="unit" id="${anchor(u)}">
+<h1 class="unit-h">${esc(u.name)} <span class="muted">${esc(u.kind === "root" ? "system/" : `${u.folder}/`)}${u.kind !== "root" ? ` · × ${u.perProduct} per product` : ""}</span></h1>
+<div class="doclinks">${SECTIONS.map((s) => `<a href="${docPath(u, s)}">${esc(SECTION_DOCS[s].file)}.pdf</a>`).join("")}<a href="${u.folder}/bom.csv">bom.csv</a>${u.kind === "root" ? `<a href="system/ordering-list.csv">ordering-list.csv</a>` : ""}</div>
+${SECTIONS.map((s) => `<article class="doc" id="${anchor(u, s)}"><h2 class="doc-h">${esc(SECTION_DOCS[s].title)}</h2>${docInner(set, u, s, img)}</article>`).join("\n")}
+<article class="doc"><h2 class="doc-h">Files</h2>${unitFiles.length ? `<ul class="plain">${unitFiles.map((f) => `<li><a href="${esc(f.path)}">${esc(f.path.slice(u.folder.length + 1))}</a> <span class="muted">${esc(f.description ?? f.role)}</span></li>`).join("")}</ul>` : `<p class="muted">No manufacturing files for this unit.</p>`}</article>
+</section>`;
+    })
+    .join("\n");
+  const bySection = SECTIONS.map((s) => `<p id="s-${s}" class="sec-index"><b>${esc(SECTION_DOCS[s].title)}:</b> ${set.units.map((u) => `<a href="#${anchor(u, s)}">${esc(u.id)}</a>`).join(" · ")}</p>`).join("");
+  const root = set.units.find((u) => u.kind === "root")!;
+  const hero = set.figures.get(root.id);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="@protoboardai/ext-release">
+<title>${esc(set.title)} — Manufacturing package ${esc(set.version)}</title>
+<style>${css}${INDEX_CSS}</style>
+</head>
+<body class="index">
+<header class="top"><span class="pg-mark"></span><span class="brand">PR<b>0</b>TOBOARD</span><span class="t">${esc(set.title)}</span><span class="muted">Manufacturing package · release ${esc(set.version)} · ${esc(set.date)}</span></header>
+<nav class="side">${nav}</nav>
+<main class="main">
+<section id="overview">
+<h1 class="unit-h">${esc(set.title)} <span class="muted">overview</span></h1>
+<div class="doclinks"><a href="00-overview.pdf">00-overview.pdf</a><a href="manifest.json">manifest.json</a></div>
+${hero ? `<img class="hero" src="${esc(hero.file)}" alt="${esc(set.title)}">` : ""}
+${blocksHtml(productBlocks(set.product, set.description), img)}
+${blocksHtml([{ kind: "figures", items: totals }], img)}
+${sub("Units")}
+${blocksHtml([{ kind: "table", columns: [{ key: "unit", label: "Unit" }, { key: "name", label: "Module" }, { key: "qty", label: "Per product", align: "right" }, { key: "into", label: "Assembled into" }, { key: "folder", label: "Folder" }], rows: set.units.map(unitRow) }], img)}
+${sub("By section")}
+${bySection}
+</section>
+${units}
+<section id="files"><h1 class="unit-h">Files</h1>${filesTable(m)}</section>
+<section id="traceability"><h1 class="unit-h">Traceability</h1>${blocksHtml(traceability(m), img)}</section>
+</main>
+</body>
+</html>
+`;
+}
+
+function docInner(set: DocSet, u: Unit, s: SectionId, img: (p: string) => string): string {
+  const parts = set.content.get(u.id)?.get(s) ?? [];
+  const blocks = [...parts.filter((c) => !c.title).flatMap((c) => c.blocks)];
+  return [
+    blocks.length ? blocksHtml(blocks, img) : `<p class="muted">No content was contributed to this section for this unit.</p>`,
+    ...parts.filter((c) => c.title).map((c) => `${sub(c.title!)}${blocksHtml(c.blocks, img)}`),
+  ].join("\n");
+}
+
+/** Screen layout for index.html over ext-docs' print theme. */
+const INDEX_CSS = `
+body.index { background: #fff; font-size: 9pt; }
+body.index .top { position: sticky; top: 0; z-index: 2; display: flex; align-items: baseline; gap: 4mm; padding: 3mm 6mm; background: #fff; border-bottom: 0.5pt solid var(--ink); }
+body.index .top .brand { font-family: var(--display); letter-spacing: .08em; }
+body.index .top .brand b { color: var(--accent); font-weight: 400; }
+body.index .top .t { font-family: var(--display); font-size: 11pt; }
+body.index .pg-mark { width: 2.4mm; height: 2.4mm; background: var(--accent); display: inline-block; align-self: center; }
+body.index nav.side { position: fixed; top: 13mm; bottom: 0; left: 0; width: 62mm; overflow-y: auto; padding: 4mm 5mm; border-right: 0.35pt solid var(--rule); font-size: 8pt; }
+body.index nav.side a { display: block; color: var(--ink); text-decoration: none; padding: .5mm 0; }
+body.index nav.side a:hover { color: var(--accent-ink); }
+body.index .nav-h { margin-top: 4mm; font-size: 6.8pt; letter-spacing: .1em; text-transform: uppercase; color: var(--muted); }
+body.index .nav-sub { padding-left: 3mm; border-left: 0.35pt solid var(--rule); margin-bottom: 1.5mm; }
+body.index .nav-sub a { color: var(--muted); }
+body.index main.main { margin-left: 66mm; padding: 6mm 8mm 30mm; max-width: 200mm; }
+body.index section { margin-bottom: 10mm; }
+body.index .unit-h { font-family: var(--display); font-weight: 400; font-size: 16pt; border-bottom: 0.6pt solid var(--ink); padding-bottom: 1.5mm; margin: 6mm 0 3mm; }
+body.index .unit-h .muted { font-family: var(--mono); font-size: 8pt; }
+body.index .doc-h { font-family: var(--display); font-weight: 400; font-size: 12pt; margin: 6mm 0 2mm; color: var(--ink); }
+body.index .doc-h::before { content: ""; display: inline-block; width: 2mm; height: 2mm; background: var(--accent); margin-right: 2mm; vertical-align: middle; }
+body.index .doclinks { display: flex; flex-wrap: wrap; gap: 2mm; margin-bottom: 3mm; }
+body.index .doclinks a { font-size: 7pt; border: 0.4pt solid var(--rule); padding: .4mm 1.6mm; color: var(--ink); text-decoration: none; }
+body.index .doclinks a:hover { border-color: var(--accent); }
+body.index img.hero { width: 100%; max-height: 110mm; object-fit: contain; margin: 2mm 0 4mm; }
+body.index .sec-index { margin: 1mm 0; }
+body.index main a { color: var(--accent-ink); }
+body.index table { font-size: 7.6pt; }
+body.index .cont-note { display: none; }
+body.index .step { break-inside: avoid; }
+body.index td.nw { white-space: nowrap; }
+body.index .part.noimg { grid-template-columns: auto; min-width: 0; }
+body.index .part.noimg .p-name { grid-column: 1; }
+body.index .step-no.wide { width: auto; min-width: 8.5mm; padding: 0 2.2mm; border-radius: 4.25mm; font-size: 9.5pt; }
+@media (max-width: 900px) { body.index nav.side { display: none; } body.index main.main { margin-left: 0; } }
+`;
+
+function filesTable(m: ReleaseManifest): string {
+  const rows = m.files.map((f) => `<tr><td><a href="${esc(f.path)}">${esc(f.path)}</a></td><td>${esc(f.unit ?? "")}</td><td>${esc(f.role)}</td><td class="num">${f.bytes}</td></tr>`).join("");
+  return `<table class="dense"><thead><tr><th>File</th><th>Unit</th><th>Role</th><th class="num">Bytes</th></tr></thead><tbody>${rows}</tbody></table>`;
+}

package/lib/glb.ts

@@ -0,0 +1,85 @@
+/**
+ * Overall size of a body from a provider's GLB standard output: the bounding
+ * box of every mesh's POSITION bounds (accessor min/max, which glTF requires)
+ * through the node transforms. glTF is Y-up in metres; the box is returned in
+ * the model's Z-up millimetres, as the providers export it (build123d writes
+ * the Z-up body under a root rotation, so the result is the body's own box).
+ */
+import { readFileSync } from "node:fs";
+
+type M = number[]; // column-major 4×4, as glTF stores it
+
+const I: M = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+const mul = (a: M, b: M): M => {
+  const o = new Array(16).fill(0);
+  for (let c = 0; c < 4; c++) for (let r = 0; r < 4; r++) for (let k = 0; k < 4; k++) o[c * 4 + r] += a[k * 4 + r] * b[c * 4 + k];
+  return o;
+};
+function trs(n: { matrix?: number[]; translation?: number[]; rotation?: number[]; scale?: number[] }): M {
+  if (n.matrix) return n.matrix;
+  const [x, y, z, w] = n.rotation ?? [0, 0, 0, 1];
+  const [sx, sy, sz] = n.scale ?? [1, 1, 1];
+  const [tx, ty, tz] = n.translation ?? [0, 0, 0];
+  return [
+    (1 - 2 * (y * y + z * z)) * sx, 2 * (x * y + z * w) * sx, 2 * (x * z - y * w) * sx, 0,
+    2 * (x * y - z * w) * sy, (1 - 2 * (x * x + z * z)) * sy, 2 * (y * z + x * w) * sy, 0,
+    2 * (x * z + y * w) * sz, 2 * (y * z - x * w) * sz, (1 - 2 * (x * x + y * y)) * sz, 0,
+    tx, ty, tz, 1,
+  ];
+}
+const apply = (m: M, p: number[]) => [0, 1, 2].map((r) => m[r] * p[0] + m[4 + r] * p[1] + m[8 + r] * p[2] + m[12 + r]);
+
+export interface GlbBox {
+  min: [number, number, number];
+  max: [number, number, number];
+  /** Extents along X, Y, Z (mm). */
+  size: [number, number, number];
+}
+
+interface Gltf {
+  scene?: number;
+  scenes?: { nodes?: number[] }[];
+  nodes?: { children?: number[]; mesh?: number; matrix?: number[]; translation?: number[]; rotation?: number[]; scale?: number[] }[];
+  meshes?: { primitives: { attributes: Record<string, number> }[] }[];
+  accessors?: { min?: number[]; max?: number[] }[];
+}
+
+/** The body's bounding box in mm (Z up), or undefined when the file is not a readable GLB. */
+export function glbBox(file: string): GlbBox | undefined {
+  let json: Gltf;
+  try {
+    const b = readFileSync(file);
+    if (b.readUInt32LE(0) !== 0x46546c67) return undefined; // "glTF"
+    const len = b.readUInt32LE(12);
+    json = JSON.parse(b.subarray(20, 20 + len).toString("utf8")) as Gltf;
+  } catch {
+    return undefined;
+  }
+  const lo = [Infinity, Infinity, Infinity];
+  const hi = [-Infinity, -Infinity, -Infinity];
+  const visit = (i: number, parent: M) => {
+    const n = json.nodes?.[i];
+    if (!n) return;
+    const m = mul(parent, trs(n));
+    for (const prim of n.mesh !== undefined ? (json.meshes?.[n.mesh]?.primitives ?? []) : []) {
+      const a = json.accessors?.[prim.attributes.POSITION];
+      if (!a?.min || !a.max) continue;
+      for (const x of [a.min[0], a.max[0]]) for (const y of [a.min[1], a.max[1]]) for (const z of [a.min[2], a.max[2]]) {
+        const p = apply(m, [x, y, z]);
+        for (let k = 0; k < 3; k++) {
+          lo[k] = Math.min(lo[k], p[k]);
+          hi[k] = Math.max(hi[k], p[k]);
+        }
+      }
+    }
+    for (const c of n.children ?? []) visit(c, m);
+  };
+  const scene = json.scenes?.[json.scene ?? 0];
+  for (const r of scene?.nodes ?? []) visit(r, I);
+  if (!Number.isFinite(lo[0])) return undefined;
+  // glTF Y-up metres → Z-up millimetres: X = x, Y = −z, Z = y
+  const r3 = (v: number) => Math.round(v * 1000 * 100) / 100;
+  const min: [number, number, number] = [r3(lo[0]), r3(-hi[2]), r3(lo[1])];
+  const max: [number, number, number] = [r3(hi[0]), r3(-lo[2]), r3(hi[1])];
+  return { min, max, size: [r3((hi[0] - lo[0])), r3((hi[2] - lo[2])), r3((hi[1] - lo[1]))] };
+}

package/lib/helpers.ts

@@ -0,0 +1,49 @@
+/**
+ * What section contributors share with the release (`@protoboardai/ext-release/helpers`):
+ * which custom modules a unit builds, how many per build, the files collected
+ * for them, a module's standard outputs, and the model-derived cut list and
+ * bill of materials. Providers import this when the release calls them, so
+ * it is only loaded where ext-release is installed.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { CapabilityBinding, Project } from "@protoboardai/core";
+import { unitModules } from "./collect.ts";
+import type { PackageFile, Unit } from "./types.ts";
+
+export { fileGroup, unitModules } from "./collect.ts";
+export { CUT_COLUMNS, cutList, cutListCsv, isCable, type CutRow } from "./cutlist.ts";
+export { classify, includedWith, orderingList, unitBom, type OrderLine, type UnitBomRow } from "./bom.ts";
+export { glbBox, type GlbBox } from "./glb.ts";
+export { unitLinks, type UnitLink } from "./sections/model.ts";
+export { toCsv } from "./util.ts";
+
+/** Instances of `module` in one build of the unit (the unit's own module counts once). */
+export function perBuild(unit: Unit, module: string): number {
+  const own = unit.kind !== "root" && unit.definition === module ? 1 : 0;
+  return own + unit.members.filter((m) => !m.unit && m.definition === module).reduce((s, m) => s + m.quantity, 0);
+}
+
+/** Files the release collected for a module in this unit (package paths under files/<group>/<module>/). */
+export function moduleFiles(files: PackageFile[], unit: Unit, module: string): PackageFile[] {
+  return files.filter((f) => f.unit === unit.id && new RegExp(`^${unit.folder}/files/[^/]+/${module.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`).test(f.path));
+}
+
+/** Unit-relative form of a package path ("files/mechanical/frame/frame.dxf"). */
+export const inUnit = (unit: Unit, path: string) => (path.startsWith(unit.folder + "/") ? path.slice(unit.folder.length + 1) : path);
+
+/** A JSON standard output of a bound module (`out/<file>`), if present and readable. */
+export function readOutput<T>(p: Project, b: CapabilityBinding, file: string): T | undefined {
+  const f = join(p.root, b.out, file);
+  if (!existsSync(f)) return undefined;
+  try {
+    return JSON.parse(readFileSync(f, "utf8")) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The unit's bound modules of one provider (the provider's own contributions). */
+export function providerModules(p: Project, unit: Unit, provider: string): CapabilityBinding[] {
+  return unitModules(p, unit).filter((b) => b.provider === provider);
+}

package/lib/html.ts

@@ -0,0 +1,126 @@
+/**
+ * Section content → HTML. The same markup goes into the paginated PDFs
+ * (ext-docs' page shell, flow paginator and print theme) and into index.html.
+ */
+import { esc } from "@protoboardai/ext-docs/html";
+import { callouts as calloutSvg, figure, note, sec, sub, table } from "@protoboardai/ext-docs/blocks";
+import type { Block, Callout, Cell, Column, KitItem, Step } from "./types.ts";
+
+/** Printed width of a full-width figure (mm): the A4 text block. Callout bubbles are sized against it. */
+const TEXT_WIDTH_MM = 178;
+
+const cell = (v: Cell) => (v === null || v === undefined ? "" : esc(String(v)));
+
+/** Blocks as flow blocks (each top-level element can move to the next page). `img` maps a package path to a URL relative to the document. */
+export function blocksHtml(blocks: Block[], img: (packagePath: string) => string): string {
+  return blocks.map((b) => blockHtml(b, img)).join("\n");
+}
+
+function blockHtml(b: Block, img: (p: string) => string): string {
+  switch (b.kind) {
+    case "heading":
+      return sub(b.text);
+    case "paragraph":
+      return `<p class="prose block${b.keep ? " keep-next" : ""}">${esc(b.text)}</p>`;
+    case "list":
+      return `<${b.ordered ? "ol" : "ul"} class="plain block">${b.items.map((i) => `<li>${esc(i)}</li>`).join("")}</${b.ordered ? "ol" : "ul"}>`;
+    case "keyvalues":
+      return table(
+        [{ h: "Item" }, { h: "Value" }],
+        b.rows.map((r) => [`<b>${esc(r.label)}</b>`, `${esc(r.value)}${r.note ? `<div class="muted small">${esc(r.note)}</div>` : ""}`]),
+        { cls: "dense kv" },
+      );
+    case "figures": {
+      const k = b.items.length > 4 ? " k6" : "";
+      return `<div class="kpis${k} block">${b.items.map((i) => `<div class="kpi"><div class="k-label">${esc(i.label)}</div><div class="k-value">${kpiValue(i.value)}</div>${i.sub ? `<div class="k-sub">${esc(i.sub)}</div>` : ""}</div>`).join("")}</div>`;
+    }
+    case "table": {
+      const cols = b.columns.map((c) => ({ h: esc(c.label), cls: [c.align === "right" ? "num" : "", c.nowrap ? "nw" : ""].filter(Boolean).join(" ") }));
+      const rows = b.rows.map((r) => ("group" in r && typeof r.group === "string" ? { group: r.group } : b.columns.map((c) => cell((r as Record<string, Cell>)[c.key]))));
+      return table(cols, rows as string[][], { split: true, cls: "dense", caption: b.caption, foot: b.note ? esc(b.note) : undefined });
+    }
+    case "note":
+      return note(b.level, esc(b.text));
+    case "steps":
+      return b.steps.map((s, i) => stepHtml(s, i + 1, img)).join("\n");
+    case "image":
+      return figure({ src: img(b.file), w: b.width ?? 2000, h: b.height ?? 1180, caption: esc(b.caption), widthPct: b.size === "small" ? 55 : b.callouts?.length || b.size === "full" ? undefined : 78, overlay: overlay(b.width ?? 2000, b.height ?? 1180, b.callouts) });
+    case "kit":
+      return kitHtml(b.items, img, b.note);
+  }
+}
+
+/** Lettered bubbles with leaders (ext-docs' callouts), for an image of `w` × `h` pixels. */
+function overlay(w: number, h: number, items?: Callout[]): string | undefined {
+  if (!items?.length) return undefined;
+  const anchors = Object.fromEntries(items.map((c, i) => [`c${i}`, { x: c.x, y: c.y }]));
+  return calloutSvg({ file: "", width: w, height: h, anchors, mmPerPx: 0 }, items.map((c, i) => ({ anchor: `c${i}`, label: c.label, accent: c.accent })), TEXT_WIDTH_MM);
+}
+
+/** Kit grid: five per row, blocks of 25 so a long kit flows onto the next page. */
+function kitHtml(items: KitItem[], img: (p: string) => string, foot?: string): string {
+  const cells = items.map(
+    (k) =>
+      `<div class="kit-item${k.image ? "" : " noimg"}">${k.image ? `<img src="${esc(img(k.image))}" alt="">` : `<div class="ph">${esc(k.placeholder ?? "no CAD")}</div>`}<div class="k-qty">×${k.quantity}</div><div class="k-name">${esc(k.name)}</div>${k.ref ? `<div class="k-id">${esc(k.ref)}</div>` : ""}</div>`,
+  );
+  const out: string[] = [];
+  for (let i = 0; i < cells.length; i += 25) out.push(`<div class="block"><div class="kit">${cells.slice(i, i + 25).join("")}</div>${i + 25 >= cells.length && foot ? `<p class="fn">${esc(foot)}</p>` : ""}</div>`);
+  return out.join("\n");
+}
+
+function stepTable(t: { columns: Column[]; rows: Record<string, Cell>[] }): string {
+  return table(
+    t.columns.map((c) => ({ h: esc(c.label), cls: [c.align === "right" ? "num" : "", c.nowrap ? "nw" : ""].filter(Boolean).join(" ") })),
+    t.rows.map((r) => t.columns.map((c) => cell(r[c.key]))),
+    { cls: "dense" },
+  );
+}
+
+/** Number and unit in separate spans, so the unit is set in the text face (as ext-docs does). */
+/** A figure's value with its unit set apart; a sum in several currencies ("12 USD + 3 EUR") sets each one apart. */
+function kpiValue(v: string): string {
+  const one = (x: string) => {
+    const nu = x.match(/^(.*\d)\s([^\d\s][^\d]*)$/);
+    return nu ? `<span class="n">${esc(nu[1])}</span>\u00a0<span class="u">${esc(nu[2])}</span>` : undefined;
+  };
+  const parts = v.split(" + ");
+  const each = parts.length > 1 ? parts.map(one) : [];
+  if (each.length && each.every((x) => x !== undefined)) return each.join(" + ");
+  return one(v) ?? esc(v);
+}
+
+function stepHtml(s: Step, n: number, img: (p: string) => string): string {
+  const meta = [
+    s.tools?.length ? `<span><b>Tools</b> ${esc(s.tools.join(", "))}</span>` : "",
+    s.materials?.length ? `<span><b>Materials</b> ${esc(s.materials.join(", "))}</span>` : "",
+    s.torque ? `<span><b>Torque</b> ${esc(s.torque)}</span>` : "",
+    s.inspect ? `<span><b>Inspect</b> ${esc(s.inspect)}</span>` : "",
+    s.test ? `<span><b>Then test</b> ${esc(s.test)}</span>` : "",
+  ].filter(Boolean);
+  const no = s.id ?? String(n);
+  const pictured = s.parts?.some((p) => p.image);
+  const part = (p: NonNullable<Step["parts"]>[number]) =>
+    `<div class="part${pictured ? "" : " noimg"}">${p.image ? `<img src="${esc(img(p.image))}" alt="">` : pictured ? `<span class="ph-s"></span>` : ""}<span class="p-qty">${p.letter ? `<span class="letter${p.accent ? " acc" : ""}">${esc(p.letter)}</span>` : ""}× ${p.quantity}</span><span class="p-name">${esc(p.name)}</span></div>`;
+  const fig = s.figure
+    ? figure({ src: img(s.figure.file), w: s.figure.width, h: s.figure.height, caption: s.figure.caption ? esc(s.figure.caption) : undefined, overlay: overlay(s.figure.width, s.figure.height, s.figure.callouts) })
+    : "";
+  // the head, parts and figure stay together; the rest may follow on the next page
+  const top = `<div class="step block${s.figure ? " step-top keep-next" : ""}">
+  <div class="step-head"><div class="step-no${no.length > 2 ? " wide" : ""}">${esc(no)}</div><h2 data-num="${esc(no)}">${esc(s.title)}</h2>${s.trace?.length ? `<div class="trace">${esc(s.trace.join(" · "))}</div>` : ""}</div>
+  ${s.parts?.length ? `<div class="parts">${s.parts.map(part).join("")}</div>` : ""}
+  ${fig}
+  ${!s.figure && s.actions?.length ? `<ol class="actions">${s.actions.map((a) => `<li>${esc(a)}</li>`).join("")}</ol>` : ""}
+  ${!s.figure && !s.table && meta.length ? `<div class="step-meta">${meta.join("")}</div>` : ""}
+  ${!s.figure && !s.table ? (s.notes ?? []).map((x) => note(x.level, esc(x.text))).join("") : ""}
+</div>`;
+  if (!s.figure && !s.table) return top;
+  const rest = [
+    s.figure && s.actions?.length ? `<div class="step-cont block"><ol class="actions">${s.actions.map((a) => `<li>${esc(a)}</li>`).join("")}</ol></div>` : "",
+    s.table ? stepTable(s.table) : "",
+    meta.length ? `<div class="step-cont block"><div class="step-meta">${meta.join("")}</div></div>` : "",
+    ...(s.notes ?? []).map((x) => `<div class="step-cont block">${note(x.level, esc(x.text))}</div>`),
+  ].filter(Boolean);
+  return [top, ...rest].join("\n").replace(/class="step-cont block">(?![\s\S]*class="step-cont block">)/, 'class="step-cont block step-end">');
+}
+
+export { esc, sec, sub };