@protoboardai/ext-release 0.0.0-stage → 0.2.0

package/lib/release.ts

@@ -0,0 +1,279 @@
+/**
+ * `protoboard release`: the Manufacturing Package (release-package-and-evals.md
+ * §1–§3). Nothing is written unless every precondition holds; then the
+ * package is built in a staging folder (a temporary directory) and
+ * written to release/<version>/ through the operation's recorded writes.
+ *
+ * Order: configuration and units → preconditions → files collected from the
+ * standard outputs → sections from every extension (package:<section>, the
+ * release's own first) → figures, unit documents, overview, index.html →
+ * manifest.
+ */
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { loadEntry, probeTools, readProduct, stableStringify, uhdBundle, type LoadedExtension, type Project } from "@protoboardai/core";
+import { readFx } from "@protoboardai/ext-sourcing/lib/cost.ts";
+import { productDiagnostics } from "./product.ts";
+import { orderingList, orderTotals } from "./bom.ts";
+import { collectUnitFiles } from "./collect.ts";
+import { readReleaseConfig } from "./config.ts";
+import { docId, docPath, indexHtml, overviewBody, unitDocBody, type Contributed, type DocSet } from "./documents.ts";
+import { buildManifest, type ReleaseManifest } from "./manifest.ts";
+import { freshness, gitState, preconditions } from "./preconditions.ts";
+import { pdfDate, Renderer, shippableFont, stageFonts } from "./render.ts";
+import { SECTION_DOCS, SECTIONS, type PackageFile, type RenderedFigure, type SectionContext, type SectionDiagnostic, type SectionFn, type SectionId, type Unit } from "./types.ts";
+import { resolveUnits } from "./units.ts";
+import { byCode, posix, sha256 } from "./util.ts";
+
+export const RELEASE_DIR = "release";
+export const EXTENSION_ID = "@protoboardai/ext-release";
+
+export interface ReleaseOptions {
+  version?: string;
+  allowDirty?: boolean;
+  /** Write one package file (project-relative); the operation's recorded write. */
+  write: (path: string, content: Buffer, description?: string) => void;
+  log?: (line: string) => void;
+  /** Stop after the checks, writing nothing (`--input check=true`). */
+  checkOnly?: boolean;
+}
+
+export interface ReleaseResult {
+  status: "succeeded" | "failed";
+  summary: string;
+  diagnostics: SectionDiagnostic[];
+  version?: string;
+  dir?: string;
+  units?: { id: string; folder: string; perProduct: number }[];
+  documents?: { path: string; pages: number }[];
+  packageDigest?: string;
+  manifestDigest?: string;
+}
+
+const VERSION = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** The release date: SOURCE_DATE_EPOCH (seconds), else the source commit's date, else none. */
+function releaseDate(git?: { date: string }): string | undefined {
+  const epoch = process.env.SOURCE_DATE_EPOCH;
+  if (epoch && /^\d+$/.test(epoch)) return new Date(Number(epoch) * 1000).toISOString().replace(/\.000Z$/, "Z");
+  return git ? new Date(git.date).toISOString().replace(/\.000Z$/, "Z") : undefined;
+}
+
+/** Section entries of every loaded extension: the release's own first, then in configuration order. */
+function sectionEntries(p: Project, section: SectionId): { ext: LoadedExtension; entry: string }[] {
+  const exts = [...p.extensions].sort((a, b) => Number(b.manifest.id === EXTENSION_ID) - Number(a.manifest.id === EXTENSION_ID));
+  return exts.flatMap((ext) => (ext.manifest.operations ?? []).filter((o) => o.id === `package:${section}`).map((o) => ({ ext, entry: o.entry })));
+}
+
+const fail = (diagnostics: SectionDiagnostic[], summary?: string): ReleaseResult => {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  return { status: "failed", summary: summary ?? `release refused: ${errors.length} problem(s); first: ${errors[0]?.message ?? "?"}`, diagnostics };
+};
+
+export async function buildRelease(p: Project, opts: ReleaseOptions): Promise<ReleaseResult> {
+  const log = opts.log ?? (() => {});
+  const diagnostics: SectionDiagnostic[] = [];
+  if (!p.rootDef) return fail([{ code: "REL_NO_ROOT", severity: "error", message: "the project has no root system" }]);
+
+  // ---- configuration, units, preconditions
+  const cfg = await readReleaseConfig(p);
+  diagnostics.push(...cfg.diagnostics);
+  const { units, diagnostics: unitDiags } = resolveUnits(p, cfg.config.units ?? []);
+  diagnostics.push(...unitDiags);
+  const fresh = freshness(p);
+  diagnostics.push(...preconditions(p, fresh));
+  const version = opts.version ?? p.rootDef.version;
+  if (!version) diagnostics.push({ code: "REL_NO_VERSION", severity: "error", message: `no release version: pass --version <v> (the root module ${p.rootDef.id} states none)` });
+  else if (!VERSION.test(version)) diagnostics.push({ code: "REL_NO_VERSION", severity: "error", message: `release version "${version}" must be letters, digits, ".", "_" or "-"` });
+  // what the product is, as the project states it (docs/product.json): the first page reads it; what is missing is a warning
+  const product = readProduct(p.root);
+  diagnostics.push(...productDiagnostics(product));
+  // the release folder (and `releases/`, its earlier name) is the output, not a design input
+  const git = gitState(p.root, [RELEASE_DIR, "releases", "operations"]);
+  if (git?.dirty.length && !opts.allowDirty)
+    diagnostics.push({ code: "REL_DIRTY", severity: "error", message: `uncommitted changes in the project (${git.dirty.slice(0, 5).join(", ")}${git.dirty.length > 5 ? ", …" : ""}); commit them, or pass --allow-dirty (recorded in the manifest)` });
+  if (diagnostics.some((d) => d.severity === "error") || opts.checkOnly) {
+    return diagnostics.some((d) => d.severity === "error") ? fail(diagnostics) : { status: "succeeded", summary: `ready to release ${version}: ${units.length} unit(s), no blocking problems`, diagnostics };
+  }
+  const date = releaseDate(git);
+  const day = date ? date.slice(0, 10) : "undated";
+  const build = cfg.config.build ?? 1;
+  const outDir = `${RELEASE_DIR}/${version}`;
+  log(`release ${version}: ${units.map((u) => `${u.id}${u.kind !== "root" ? ` ×${u.perProduct}` : ""}`).join(", ")}`);
+
+  // ---- files from the standard outputs, and the model
+  const files: PackageFile[] = units.flatMap((u) => collectUnitFiles(p, u));
+  const bundle = await uhdBundle(p);
+  // machine-independent: artifact bases relative to the project
+  bundle.artifactBases = Object.fromEntries(Object.entries(bundle.artifactBases ?? {}).map(([k, v]) => [k, posix(relative(p.root, v)) || "."]));
+  const bundleFile: PackageFile = { path: "system/files/model/uhd-bundle.json", unit: "system", role: "model", content: Buffer.from(stableStringify(bundle)), description: "UHD bundle of the released system" };
+  files.push(bundleFile);
+
+  // ---- rendering: one Chrome for the figures (sections may ask for them) and the documents.
+  // Staging is outside the project and laid out like the package, so relative links print correctly.
+  const staging = mkdtempSync(join(tmpdir(), "protoboard-release-"));
+  const renderer = new Renderer(p, staging);
+  let manifest: ReleaseManifest;
+  const documents: { path: string; pages: number }[] = [];
+  try {
+    const fonts = stageFonts(staging);
+    const set: DocSet = { project: p.name, title: p.rootDef.name ?? p.rootDef.id, description: p.rootDef.description, product, version: version!, date: day, units, content: new Map(), figures: new Map() };
+    set.figures = await renderer.unitFigures(units);
+    for (const f of set.figures.values()) files.push({ path: f.file, role: "figure", content: readFileSync(join(staging, f.file)), description: "assembled unit, line art from the model's CAD" });
+    const figure = figureFn(renderer, staging, files, new Set([...set.figures.values()].map((f) => f.file)));
+
+    // ---- sections
+    const sections: ReleaseManifest["sections"] = [];
+    const releaseInfo = { version: version!, date: day, build, config: cfg.config };
+    for (const u of units) {
+      const bySection = new Map<SectionId, Contributed[]>();
+      for (const s of SECTIONS) {
+        const entries = sectionEntries(p, s);
+        const contributors = [...new Set(entries.map((e) => e.ext.manifest.id))];
+        // the release's own entry runs last, so its work order can number the operations the others contribute
+        const byEntry: Contributed[][] = entries.map(() => []);
+        const operations: SectionContext["operations"] = [];
+        const runOrder = entries.map((e, i) => ({ ...e, i })).sort((a, b) => Number(a.ext.manifest.id === EXTENSION_ID) - Number(b.ext.manifest.id === EXTENSION_ID));
+        for (const { ext, entry, i } of runOrder) {
+          const parts = byEntry[i];
+          const ctx: SectionContext = { project: p, section: s, unit: u, units, release: releaseInfo, files: files.filter((f) => f.unit === u.id), contributors, operations: ext.manifest.id === EXTENSION_ID ? operations : [], figure, log };
+          let got;
+          try {
+            const fn = await loadEntry<SectionFn>(ext, entry);
+            got = await fn(ctx);
+          } catch (e) {
+            diagnostics.push({ code: "REL_SECTION_FAILED", severity: "error", message: `${ext.manifest.id} package:${s} failed for unit ${u.id}: ${(e as Error).message.split("\n")[0]}` });
+            continue;
+          }
+          for (const c of (Array.isArray(got) ? got : got ? [got] : []).filter((c) => c.blocks?.length || c.files?.length || c.operations?.length)) {
+            for (const d of c.diagnostics ?? []) diagnostics.push({ ...d, message: `${ext.manifest.id} package:${s} (${u.id}): ${d.message}` });
+            for (const f of c.files ?? []) {
+              const problem = sectionFileProblem(p, u, f.path, f.from);
+              if (problem) {
+                diagnostics.push({ code: "REL_SECTION_FILE", severity: "error", message: `${ext.manifest.id} package:${s} (${u.id}): ${problem}` });
+                continue;
+              }
+              const path = `${u.folder}/${f.path}`;
+              if (files.some((x) => x.path === path)) {
+                diagnostics.push({ code: "REL_SECTION_FILE", severity: "error", message: `${ext.manifest.id} package:${s} (${u.id}): ${path} is already in the package` });
+                continue;
+              }
+              const bytes = f.from ? readFileSync(join(p.root, f.from)) : Buffer.isBuffer(f.content) ? f.content : Buffer.from(f.content ?? "");
+              files.push({ path, unit: u.id, role: f.role ?? "data", ...(f.from ? { from: f.from } : {}), content: bytes, ...(f.description ? { description: f.description } : {}) });
+            }
+            if (s === "work-order") for (const o of c.operations ?? []) operations.push({ ...o, extension: ext.manifest.id });
+            parts.push({ ...c, extension: ext.manifest.id });
+          }
+        }
+        const parts = byEntry.flat();
+        parts.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        bySection.set(s, parts);
+        sections.push({ unit: u.id, section: s, contributors: [...new Set(parts.map((c) => c.extension))] });
+      }
+      set.content.set(u.id, bySection);
+    }
+    await renderer.closeFigures();
+    if (diagnostics.some((d) => d.severity === "error")) return fail(diagnostics);
+
+    // ---- documents
+    const tools = toolDetails(p);
+    const stamp = pdfDate(date ?? "1970-01-01T00:00:00Z");
+    const overflow: string[] = [];
+    for (const u of units) {
+      for (const s of SECTIONS) {
+        const rel = docPath(u, s);
+        const up = "../".repeat(rel.split("/").length - 1);
+        const meta = { title: u.kind === "root" ? set.title : `${set.title}: ${u.name}`, docType: SECTION_DOCS[s].title, docId: docId(set, u, s), revision: version!, date: day, system: p.rootDef.id };
+        const r = await renderer.pdf(rel, meta, unitDocBody(set, u, s, (x) => up + x), `${up}assets/fonts`, stamp);
+        if (r.overflow.length) overflow.push(`${rel} p${r.overflow.join(",")}`);
+        files.push({ path: rel, unit: u.id, role: "document", content: r.pdf, description: SECTION_DOCS[s].title });
+        documents.push({ path: rel, pages: r.pages });
+        log(`${rel}: ${r.pages} page(s)`);
+      }
+    }
+    const lines = orderingList(p, units, cfg.config);
+    const t = orderTotals(lines, readFx(p.root).table);
+    const totals = [
+      { label: "Units", value: String(units.length), sub: units.map((u) => u.id).join(", ") },
+      { label: "Parts", value: String(t.pieces), sub: `${t.lines} ordering lines (${t.buy} buy, ${t.fabricate} make, ${t.included} included)` },
+      { label: "Cost estimate", value: t.costText || "—", sub: [`${t.priced} of ${t.buy} bought lines priced`, t.costNote].filter(Boolean).join("; ") },
+      { label: "Lead time", value: t.leadTimeWeeks !== null ? `${t.leadTimeWeeks} wk` : "—", sub: t.leadTimeWeeks !== null ? "longest offer lead time" : "no offer states one" },
+    ];
+    for (const f of fonts.files.filter((x) => shippableFont(x.file))) files.push({ path: `assets/fonts/${f.file}`, role: "asset", content: readFileSync(f.path), description: "Kode Mono (SIL Open Font License)" });
+    const draft = () => buildManifest({ p, version: version!, date: date ?? "", source: git ? { commit: git.commit, dirty: git.dirty } : null, build, units, bundle: bundleFile, fresh, files, tools, fonts: fonts.files.map((f) => ({ file: f.file, digest: sha256(readFileSync(f.path)) })), sections });
+    const ov = await renderer.pdf("00-overview.pdf", { title: set.title, docType: "Manufacturing package", docId: docId(set, units.find((u) => u.kind === "root")!, "overview"), revision: version!, date: day, system: p.rootDef.id }, overviewBody(set, draft(), totals, (x) => x), "assets/fonts", stamp);
+    if (ov.overflow.length) overflow.push(`00-overview.pdf p${ov.overflow.join(",")}`);
+    files.push({ path: "00-overview.pdf", role: "document", content: ov.pdf, description: "overview, order of work, index and traceability" });
+    documents.unshift({ path: "00-overview.pdf", pages: ov.pages });
+    files.push({ path: "index.html", role: "document", content: Buffer.from(indexHtml(set, draft(), totals, files)), description: "the whole package, by unit and by section" });
+    manifest = draft();
+    if (overflow.length) diagnostics.push({ code: "REL_PAGE_OVERFLOW", severity: "warning", message: `content overflows a page in ${overflow.join("; ")}` });
+  } finally {
+    await renderer.close();
+    rmSync(staging, { recursive: true, force: true });
+  }
+
+  // ---- write release/<version>/ (replacing an earlier build of the same version)
+  rmSync(join(p.root, outDir), { recursive: true, force: true });
+  const manifestBytes = Buffer.from(stableStringify(manifest));
+  for (const f of [...files].sort((a, b) => byCode(a.path, b.path))) opts.write(`${outDir}/${f.path}`, f.content, f.description);
+  opts.write(`${outDir}/manifest.json`, manifestBytes, "release manifest");
+  return {
+    status: "succeeded",
+    summary: `${outDir}: ${units.length} unit(s), ${documents.length} documents (${documents.reduce((s, d) => s + d.pages, 0)} pages), ${files.length + 1} files; package ${manifest.packageDigest.slice(7, 19)}`,
+    diagnostics,
+    version,
+    dir: outDir,
+    units: units.map((u) => ({ id: u.id, folder: u.folder, perProduct: u.perProduct })),
+    documents,
+    packageDigest: manifest.packageDigest,
+    manifestDigest: sha256(manifestBytes),
+  };
+}
+
+const FIGURE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * The figure callback sections get (SectionContext.figure): renders into
+ * staging/assets/images/<name>.png once per name and adds the file to the
+ * package. A name reused with another spec is a contributor's bug.
+ */
+function figureFn(renderer: Renderer, staging: string, files: PackageFile[], taken: Set<string>): SectionContext["figure"] {
+  const done = new Map<string, { spec: string; fig: RenderedFigure }>();
+  return async (name, spec) => {
+    if (!FIGURE_NAME.test(name)) throw new Error(`figure name "${name}" must be letters, digits, ".", "_" or "-"`);
+    const file = `assets/images/${name}.png`;
+    const key = stableStringify(spec);
+    const hit = done.get(name);
+    if (hit) {
+      if (hit.spec !== key) throw new Error(`figure "${name}" was already rendered from another spec`);
+      return hit.fig;
+    }
+    if (taken.has(file)) throw new Error(`figure "${name}" is taken by the release`);
+    const r = await renderer.figure(name, spec);
+    const fig: RenderedFigure = { file, width: r.width, height: r.height, anchors: r.anchors };
+    done.set(name, { spec: key, fig });
+    files.push({ path: file, role: "figure", content: readFileSync(join(staging, file)), description: "figure rendered from the model's CAD" });
+    return fig;
+  };
+}
+
+/** A contributed file must stay inside its unit folder and not take a document's name. */
+function sectionFileProblem(p: Project, u: Unit, path: string, from?: string): string | undefined {
+  const norm = posix(path);
+  if (!norm || norm.startsWith("/") || norm.split("/").includes("..")) return `file path ${path} must be relative to the unit folder`;
+  if (/\.pdf$/i.test(norm) && !norm.startsWith("files/")) return `${path}: PDFs at the unit level are the release's documents; put contributed files under files/`;
+  if (from && !existsSync(join(p.root, from))) return `${from} does not exist`;
+  return undefined;
+}
+
+/** Versions of the tools the release itself ran (Chrome for figures and PDFs). */
+function toolDetails(p: Project): { id: string; detail?: string }[] {
+  const ext = p.extensions.find((e) => e.manifest.id === EXTENSION_ID);
+  return ext ? probeTools([ext], { root: p.root }).map((t) => ({ id: t.id, ...(t.detail ? { detail: t.detail } : {}) })) : [];
+}
+
+/** Files under a directory, for tests and the CLI summary. */
+export const listTree = (abs: string, base = abs): string[] =>
+  !existsSync(abs) ? [] : readdirSync(abs, { withFileTypes: true }).flatMap((d) => (d.isDirectory() ? listTree(join(abs, d.name), base) : [posix(relative(base, join(abs, d.name)))])).sort(byCode);

package/lib/render.ts

@@ -0,0 +1,203 @@
+/**
+ * Rendering through @protoboardai/ext-docs: one headless Chrome and one static
+ * server for the whole release (FigureRenderer), serving a staging folder in
+ * which every document is laid out as it is in the package.
+ *
+ *   - figures: each unit's assembled CAD (assemble() placements and fastener
+ *     hardware, filtered to the unit's instances), line art from the GLBs;
+ *   - documents: ext-docs' page shell and flow paginator, then printed to PDF.
+ *
+ * Chrome writes the print time into a PDF's /CreationDate and /ModDate; they
+ * are replaced by the release date (same length, so the xref table stays
+ * valid), which makes a rebuild byte-identical.
+ */
+import { copyFileSync, existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Project } from "@protoboardai/core";
+import { docFonts } from "@protoboardai/ext-docs/build";
+import { shell, type DocMeta } from "@protoboardai/ext-docs/html";
+import { buildScene, loadSystem, type SceneBody } from "@protoboardai/ext-docs/model";
+import { ISO, renderBody } from "@protoboardai/ext-docs/figures";
+import { FigureRenderer, type RenderResult, type RenderSpec } from "@protoboardai/ext-docs/renderer";
+import type { Unit } from "./types.ts";
+
+/** Fonts the package may carry: Kode Mono (SIL Open Font License). */
+const SHIPPABLE_FONT = /^KodeMono-.*\.(ttf|woff2)$/;
+
+export interface Fonts {
+  /** Each font staged, with the file it was read from. */
+  files: { file: string; path: string }[];
+}
+
+/** Copy the document fonts into the staging folder (assets/fonts): the bundled Kode Mono, or the files of the same name PROTOBOARD_DOC_FONTS gives. */
+export function stageFonts(staging: string): Fonts {
+  const dst = join(staging, "assets", "fonts");
+  mkdirSync(dst, { recursive: true });
+  const files = docFonts();
+  for (const f of files) copyFileSync(f.path, join(dst, f.file));
+  return { files };
+}
+export const shippableFont = (name: string) => SHIPPABLE_FONT.test(name);
+
+export class Renderer {
+  /** Pagination and printing: serves the staging folder. */
+  private r: FigureRenderer;
+  /** Figures: serves the project (GLBs resolve where they are), writing into staging/assets/images. */
+  private fig?: FigureRenderer;
+  private sys?: Awaited<ReturnType<typeof loadSystem>>;
+  constructor(
+    private p: Project,
+    private staging: string,
+  ) {
+    this.r = new FigureRenderer(join(staging, "assets", "images"), { project: staging, packageRoot: () => undefined });
+  }
+
+  private async figures(): Promise<FigureRenderer> {
+    this.sys ??= await loadSystem(this.p);
+    this.fig ??= new FigureRenderer(join(this.staging, "assets", "images"), this.sys.roots);
+    return this.fig;
+  }
+
+  /** Render one figure to assets/images/<name>.png in the staging folder. */
+  async figure(name: string, spec: RenderSpec): Promise<RenderResult> {
+    return (await this.figures()).render(name, spec);
+  }
+
+  /** A line-art figure of each unit with placed CAD bodies (`assets/images/unit-<id>.png`). */
+  async unitFigures(units: Unit[]): Promise<Map<string, { file: string; width: number; height: number; bodies: number }>> {
+    const out = new Map<string, { file: string; width: number; height: number; bodies: number }>();
+    if (!this.p.rootDef) return out;
+    const fig = await this.figures();
+    let scene;
+    try {
+      scene = buildScene(this.sys!);
+    } catch {
+      return out;
+    }
+    for (const u of units) {
+      const inUnit = (path: string) => u.kind === "root" || u.instances.some((i) => path === i || path.startsWith(i + "/"));
+      const bodies: SceneBody[] = [...scene.bodies.filter((b) => !b.via?.startsWith("hint:") && inUnit(b.path.join("/"))), ...scene.hardware.filter((h) => inUnit(h.path.join("/")))];
+      // one build: a module unit shows its representative instance only
+      const rep = (path: string) => path === u.representative || path.startsWith(u.representative + "/");
+      const shown = u.kind === "module" ? bodies.filter((b) => rep(b.path.join("/"))) : bodies;
+      if (!shown.filter((b) => b.glb).length) continue;
+      const res = await fig.render(`unit-${u.id}`, { width: 2000, height: 1180, mode: "lineart", bodies: shown.map((b) => renderBody(b, "normal")), camera: { dir: ISO, margin: 0.05 } });
+      out.set(u.id, { file: `assets/images/unit-${u.id}.png`, width: res.width, height: res.height, bodies: shown.length });
+    }
+    return out;
+  }
+
+  /** Write a document into the staging folder, paginate it, print it; returns the PDF bytes (dates normalised) and page count. */
+  async pdf(rel: string, meta: DocMeta, body: string, fontsHref: string, pdfDate: string): Promise<{ pdf: Buffer; pages: number; overflow: number[] }> {
+    const htmlRel = rel.replace(/\.pdf$/, ".print.html");
+    const abs = join(this.staging, htmlRel);
+    mkdirSync(join(abs, ".."), { recursive: true });
+    writeFileSync(abs, shell(meta, body, { fontsHref, extraCss: PRINT_CSS }));
+    const pag = await this.r.paginate(`project/${htmlRel}`);
+    writeFileSync(abs, pag.html);
+    const pdf = normalisePdf(await this.r.printPdf(`project/${htmlRel}`), pdfDate);
+    return { pdf, pages: pag.pages, overflow: pag.overflow };
+  }
+
+  /** Stop the figure renderer's Chrome (one Chrome at a time: the documents start their own). */
+  async closeFigures() {
+    await this.fig?.close();
+    this.fig = undefined;
+  }
+
+  async close() {
+    await this.fig?.close();
+    await this.r.close();
+  }
+}
+
+/** D:YYYYMMDDHHmmSS+00'00' from an ISO date-time. */
+export function pdfDate(iso: string): string {
+  const d = new Date(iso);
+  const t = Number.isNaN(d.getTime()) ? new Date(0) : d;
+  const p = (n: number, w = 2) => String(n).padStart(w, "0");
+  return `D:${p(t.getUTCFullYear(), 4)}${p(t.getUTCMonth() + 1)}${p(t.getUTCDate())}${p(t.getUTCHours())}${p(t.getUTCMinutes())}${p(t.getUTCSeconds())}+00'00'`;
+}
+
+/**
+ * Make Chrome's PDF depend only on the document: the creation and
+ * modification dates become the release date, and the tagged-PDF element ids
+ * (`nodeNNNNNNNN`) are renumbered in document order. Chrome takes them from
+ * a DOM node counter that depends on what the tab did before, and their
+ * relative order can change from run to run (the table header cells of a
+ * smart-bottle BOM came out in another order once, PB-809), so neither the
+ * numbers nor their ranks are stable; the order of the structure elements in
+ * the file is. The ID tree's name arrays are then sorted again and their
+ * limits reset. Every replacement keeps its length, so the xref offsets stay
+ * valid. A PDF whose ID tree cannot be rewritten in place falls back to
+ * renumbering the ids by rank, as before PB-809.
+ */
+export function normalisePdf(pdf: Buffer, date: string): Buffer {
+  let text = pdf.toString("latin1");
+  text = text.replace(/\/(CreationDate|ModDate) \(D:[0-9]{14}[^)]*\)/g, (m, key: string) => {
+    const value = `/${key} (${date})`;
+    return value.length === m.length ? value : m;
+  });
+  return Buffer.from(renumberElementIds(text), "latin1");
+}
+
+const ELEMENT_ID = /\/ID \((node\d+)\)/g;
+const ANY_ID = /\((node\d+)\)/g;
+const NAMES_LEAF = /\/Limits \[\((node\d+)\) \((node\d+)\)\]\n\/Names \[((?:\(node\d+\) \d+ \d+ R ?)+)\]/g;
+
+/**
+ * The fallback: ids renumbered by the rank of Chrome's number, which keeps the
+ * ID tree sorted and every id its length. Stable unless Chrome changes the
+ * relative order of its node counter, which document order also covers.
+ */
+export function renumberByRank(text: string): string {
+  const ids = [...new Set(text.match(/\(node\d+\)/g) ?? [])].sort((a, b) => Number(a.slice(5, -1)) - Number(b.slice(5, -1)));
+  const rank = new Map(ids.map((id, i) => [id, `(node${String(i + 1).padStart(id.length - 6, "0")})`]));
+  return text.replace(/\(node\d+\)/g, (m) => (rank.get(m)!.length === m.length ? rank.get(m)! : m));
+}
+
+function renumberElementIds(text: string): string {
+  const order: string[] = [];
+  for (const m of text.matchAll(ELEMENT_ID)) if (!order.includes(m[1])) order.push(m[1]);
+  if (!order.length) return renumberByRank(text);
+  const renamed = new Map(order.map((id, i) => [id, `node${String(i + 1).padStart(id.length - 4, "0")}`]));
+  if ([...renamed].some(([a, b]) => a.length !== b.length)) return renumberByRank(text);
+  // every reference (the ID tree, a table cell's /Headers) must name an element the file defines
+  if ([...text.matchAll(ANY_ID)].some((m) => !renamed.has(m[1]))) return renumberByRank(text);
+  const name = (id: string) => renamed.get(id)!;
+  const rename = (part: string) => part.replace(ANY_ID, (_m, id: string) => `(${name(id)})`);
+
+  // the ID tree's leaves, in file order: rename every entry, sort them all, and refill each leaf with as many as it had
+  const leaves = [...text.matchAll(NAMES_LEAF)];
+  const entries = leaves.flatMap((l) => [...l[3].matchAll(/\((node\d+)\) (\d+ \d+ R)/g)].map((e) => ({ id: name(e[1]), ref: e[2] })));
+  entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  let next = 0;
+  const rewritten = leaves.map((l) => {
+    const n = [...l[3].matchAll(/\(node\d+\)/g)].length;
+    const mine = entries.slice(next, (next += n));
+    const body = mine.map((e) => `(${e.id}) ${e.ref}`).join(" ") + (l[3].endsWith(" ") ? " " : "");
+    return { at: l.index!, from: l[0], to: `/Limits [(${mine[0].id}) (${mine[mine.length - 1].id})]\n/Names [${body}]` };
+  });
+  // a leaf that would change length (entries moved between leaves) would move bytes: renumber by rank then
+  if (rewritten.some((r) => r.to.length !== r.from.length)) return renumberByRank(text);
+  let out = "";
+  let last = 0;
+  for (const r of rewritten) {
+    out += rename(text.slice(last, r.at)) + r.to;
+    last = r.at + r.from.length;
+  }
+  return out + rename(text.slice(last));
+}
+
+/** Rules the release documents add to ext-docs' print theme. */
+export const PRINT_CSS = `
+table.kv td:first-child { width: 42mm; }
+.doc-head { display: flex; gap: 4mm; align-items: baseline; font-size: 6.4pt; color: var(--muted); text-transform: uppercase; letter-spacing: .06em; margin: -1mm 0 4mm; }
+.doc-head b { color: var(--ink); font-weight: 600; }
+.part .p-name { grid-column: 2; }
+td.nw, th.nw { white-space: nowrap; }
+.part.noimg { grid-template-columns: auto; min-width: 0; }
+.part.noimg .p-name { grid-column: 1; }
+.step-no.wide { width: auto; min-width: 8.5mm; padding: 0 2.2mm; border-radius: 4.25mm; font-size: 9.5pt; }
+.step .figwrap { margin-top: 1mm; }
+`;

package/lib/sections/baseline.ts

@@ -0,0 +1,164 @@
+/**
+ * The release's own contributions to every section, derived from the model
+ * and the collected files only. Other extensions add to the same sections
+ * (the circuit provider's board fabrication orders, ext-harness-cad's harness
+ * operations, ext-drone's flight-controller configuration); these are the
+ * parts every project has.
+ */
+import { sectionBom } from "./bom.ts";
+import { unitPlan } from "@protoboardai/ext-docs/plan";
+import { grams, unitDef, unitMass } from "./model.ts";
+import { testPlanSection } from "./testplan.ts";
+import { workOrderSection } from "./workorder.ts";
+import { resolveExports, type InterfaceDef } from "@deltarobotics/uhd";
+import { classify, originLabel, unitBom } from "../bom.ts";
+import { num } from "../util.ts";
+import type { Block, SectionFn, Unit } from "../types.ts";
+
+const EXTENSION = "@protoboardai/ext-release";
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** Voltage, current and clock an interface states ("5 V · 2 A"). */
+function rating(i: InterfaceDef): string {
+  const out: string[] = [];
+  for (const p of i.parameters ?? []) {
+    const v = p.value !== undefined ? num(p.value) : p.range ? `${num(p.range[0])}–${num(p.range[1])}` : undefined;
+    if (v === undefined) continue;
+    if (p.id === "voltage") out.push(`${v} V`);
+    else if (p.id === "max_current") out.push(`${v} ${p.unit === "mA" ? "mA" : "A"} max`);
+    else if (p.id === "clock_freq") out.push(`${p.value !== undefined && p.value >= 1e6 ? `${num(p.value / 1e6)} MHz` : p.value !== undefined ? `${num(p.value / 1e3)} kHz` : v}`);
+    else if (p.id === "i2c_address" && p.value !== undefined) out.push(`0x${p.value.toString(16).toUpperCase().padStart(2, "0")}`);
+  }
+  return out.join(" · ");
+}
+const unitRef = (u: Unit) => (u.kind === "root" ? "system/" : `${u.folder}/`);
+
+// ---------------------------------------------------------------------------
+// spec
+// ---------------------------------------------------------------------------
+
+export const spec: SectionFn = ({ project: p, unit: u, units }) => {
+  const def = unitDef(p, u);
+  const rows = unitBom(p, u);
+  const leaves = rows.filter((r) => r.action !== "build");
+  const mass = unitMass(p, u);
+  const custom = rows.filter((r) => r.action === "fabricate");
+  const blocks: Block[] = [];
+  if (def.description) blocks.push({ kind: "paragraph", text: def.description });
+  blocks.push({
+    kind: "figures",
+    items: [
+      { label: u.kind === "root" ? "Builds" : "Per product", value: u.kind === "root" ? "1" : `× ${u.perProduct}`, sub: u.kind === "root" ? "the product" : `assembled into ${u.parents.join(", ")}` },
+      { label: "Parts per build", value: String(leaves.reduce((s, r) => s + r.qty_per_unit, 0)), sub: plural(new Set(leaves.map((r) => r.definition)).size, "line item") },
+      { label: "Mass", value: mass.totalG ? grams(mass.totalG) : "—", sub: mass.missing.length ? `${plural(mass.missing.length, "instance")} without a mass not counted` : mass.assumedG ? `${grams(mass.assumedG)} from assumed materials` : "stated weights and CAD volume" },
+      { label: "Made here", value: String(custom.length), sub: custom.length ? custom.map((r) => r.item).join(", ") : "no custom parts" },
+    ],
+  });
+  const o = originLabel(p, def.id);
+  blocks.push({ kind: "heading", text: "Identity" });
+  blocks.push({
+    kind: "keyvalues",
+    rows: [
+      { label: "Module", value: def.id },
+      ...(u.kind !== "root" ? [{ label: u.kind === "module" ? "Every instance of" : "Instance", value: u.kind === "module" ? def.id : u.representative, note: u.kind === "module" ? u.instances.join(", ") : undefined }] : []),
+      ...(def.manufacturer ? [{ label: "Manufacturer", value: def.manufacturer }] : []),
+      ...(def.part_number ? [{ label: "Part number", value: def.part_number }] : []),
+      ...(def.version ? [{ label: "Version", value: def.version }] : []),
+      { label: "Source", value: `${o.tier} · ${o.origin}` },
+    ],
+  });
+  blocks.push({ kind: "heading", text: "What one build contains" });
+  blocks.push({
+    kind: "table",
+    columns: [
+      { key: "item", label: "Item" },
+      { key: "qty", label: "Qty", align: "right" },
+      { key: "kind", label: "Kind" },
+      { key: "ref", label: "Instance" },
+    ],
+    rows: u.members.filter((m) => m.depth === 0).map((m) => ({ item: m.name, qty: m.quantity, kind: m.unit ? `unit ${m.unit}` : classify(p, p.lookup(m.definition)!).kind, ref: m.path })),
+  });
+  const exported = new Map<string, InterfaceDef>();
+  try {
+    for (const e of resolveExports(def, p.lookup)) {
+      const i = e.childDef.interfaces.find((x) => x.id === e.from.interfaceId);
+      if (i) exported.set(e.id, i);
+    }
+  } catch {
+    // an unresolvable export is reported by protoboard check
+  }
+  const boundary = [
+    ...def.interfaces.filter((i) => i.exposed !== false).map((i) => ({ id: i.id, name: i.name ?? i.id, what: [i.domain, ...(i.protocols ?? []).map((x) => x.type)].filter(Boolean).join(" · "), rating: rating(i) })),
+    ...(def.exports ?? []).map((e) => ({ id: e.id, name: e.name ?? e.id, what: `${exported.get(e.id)?.protocols.map((x) => x.type).join(" · ") ?? ""} from ${"child" in e.from ? `${e.from.child}:` : ""}${e.from.interfaceId}`.trim(), rating: exported.has(e.id) ? rating(exported.get(e.id)!) : "" })),
+  ];
+  if (boundary.length) {
+    blocks.push({ kind: "heading", text: "Interfaces to the rest of the product" });
+    blocks.push({ kind: "table", columns: [{ key: "id", label: "Interface" }, { key: "name", label: "Name" }, { key: "what", label: "Kind / source" }, { key: "rating", label: "Rating" }], rows: boundary, note: "Ratings are the model's values for the interface (voltage, current, bus clock); an empty cell means the model states none." });
+  }
+  if (u.kind === "root" && units.length > 1) {
+    blocks.push({ kind: "heading", text: "Units" });
+    blocks.push({ kind: "table", columns: [{ key: "unit", label: "Unit" }, { key: "name", label: "Module" }, { key: "qty", label: "Per product", align: "right" }, { key: "folder", label: "Folder" }], rows: units.map((x) => ({ unit: x.id, name: x.name, qty: x.perProduct, folder: unitRef(x) })) });
+  }
+  if (mass.missing.length) blocks.push({ kind: "note", level: "tip", text: `Mass leaves out ${mass.missing.map((e) => e.path).slice(0, 8).join(", ")}${mass.missing.length > 8 ? ", …" : ""}: the model states no weight or material for them.` });
+  return { blocks };
+};
+
+// ---------------------------------------------------------------------------
+// bom
+// ---------------------------------------------------------------------------
+
+export const bom: SectionFn = (ctx) => sectionBom(ctx);
+
+// ---------------------------------------------------------------------------
+// work order (./workorder.ts) and test plan (./testplan.ts)
+// ---------------------------------------------------------------------------
+
+export const workOrder: SectionFn = (ctx) => workOrderSection(ctx);
+export const testPlan: SectionFn = (ctx) => testPlanSection(ctx);
+
+// ---------------------------------------------------------------------------
+// assembly
+// ---------------------------------------------------------------------------
+
+/**
+ * Plain steps from the same plan as the work order (ext-docs' unitPlan: the
+ * order, parts, actions, soldering of parts that ship with loose connectors,
+ * and connection tables), so "Assembly guide step N" in the work order is
+ * step N here. A richer contributor (ext-docs: the same steps illustrated)
+ * replaces it.
+ */
+export const assembly: SectionFn = async ({ project: p, unit: u, contributors }) => {
+  if (contributors.some((c) => c !== EXTENSION)) return undefined;
+  const rows = unitBom(p, u);
+  const kit = rows.filter((r) => r.level === 0 || r.kind === "unit");
+  const { steps: planned } = await unitPlan(p, u);
+  const blocks: Block[] = [
+    { kind: "heading", text: "Kit" },
+    { kind: "paragraph", text: `Check every item against the bill of materials (bom.pdf) before starting.${u.members.some((m) => m.unit) ? " Bring the finished sub-units listed; each has its own folder in this package." : ""}` },
+    { kind: "kit", items: kit.map((r) => ({ name: r.item, quantity: r.qty_per_unit, ref: r.path })) },
+  ];
+  const steps: Extract<Block, { kind: "steps" }>["steps"] = planned.map((st) => ({
+    title: st.title,
+    actions: st.actions,
+    ...(st.parts.length ? { parts: st.parts.map((pt) => ({ name: pt.def.name ?? pt.def.id, quantity: pt.count, ref: pt.def.id })) } : {}),
+    ...(st.connections.length
+      ? {
+          table: {
+            columns: [{ key: "name", label: "Link" }, { key: "from", label: "From" }, { key: "to", label: "To" }, { key: "x", label: "" }, { key: "term", label: "Termination" }],
+            rows: st.connections.map((c) => ({ name: c.name, from: c.from, to: c.to, x: c.crossover ? "× crossover" : "", term: c.termination })),
+          },
+        }
+      : {}),
+    ...(st.torque ? { torque: st.torque } : {}),
+    ...(st.tools.length ? { tools: st.tools } : {}),
+    ...(st.materials.length ? { materials: st.materials } : {}),
+    ...(st.notes.length ? { notes: st.notes } : {}),
+    trace: st.trace,
+  }));
+  if (steps.length) blocks.push({ kind: "heading", text: "Steps" }, { kind: "steps", steps });
+  else blocks.push({ kind: "paragraph", text: "This unit makes no joints: its parts are used as they come." });
+  return { blocks };
+};
+
+export const BASELINE: Record<string, SectionFn> = { spec, bom, "work-order": workOrder, assembly, "test-plan": testPlan };