@protoboardai/ext-docs 0.0.0-stage → 0.2.0

package/lib/docs/product.ts

@@ -0,0 +1,45 @@
+/**
+ * The datasheet's first page after the cover (PB-935): what the device is,
+ * its features, what it does and what it must meet, from the project's own
+ * statement (`docs/product.json` and the brief's requirements table;
+ * @protoboardai/core readProduct). These are the project's words, not model
+ * values, so they are not bound values. What the project has not stated is
+ * said on the page; nothing is written for it.
+ */
+import { PRODUCT_FILE, PRODUCT_PART_TEXT, readProduct, type ProductPart } from "@protoboardai/core";
+import { sec, sub, table } from "../blocks.ts";
+import { esc } from "../html.ts";
+
+const missing = (k: ProductPart) => `<p class="small muted"><i>${esc(PRODUCT_PART_TEXT[k].missing)} State it in <code>${esc(PRODUCT_FILE)}</code>.</i></p>`;
+
+/** The page, as flow blocks: the heading with the summary, then features, functions and requirements. */
+export function productPage(root: string, title: string, description?: string): string {
+  const p = readProduct(root);
+  const out: string[] = [];
+  out.push(
+    `<div class="block">${sec("00", "The product", esc(title))}${sub(PRODUCT_PART_TEXT.summary.title)}${p.summary ? `<p class="lead">${esc(p.summary)}</p>` : `${description ? `<p class="lead">${esc(description)}</p>` : ""}${missing("summary")}`}</div>`,
+  );
+  out.push(`<div class="block">${sub(PRODUCT_PART_TEXT.features.title)}${p.features.length ? `<ul class="plain">${p.features.map((f) => `<li>${esc(f)}</li>`).join("")}</ul>` : missing("features")}</div>`);
+  const by = p.functions.some((f) => f.by);
+  out.push(
+    `<div class="block">${sub(PRODUCT_PART_TEXT.functions.title)}${
+      p.functions.length ? table([{ h: "ID" }, { h: "Function" }, ...(by ? [{ h: "Done by" }] : [])], p.functions.map((f) => [esc(f.id ?? ""), esc(f.text), ...(by ? [esc(f.by ?? "")] : [])]), { cls: "dense", ...(p.functionsFrom && p.functionsFrom !== PRODUCT_FILE ? { foot: `From ${esc(p.functionsFrom)}.` } : {}) }) : missing("functions")
+    }</div>`,
+  );
+  const pass = p.requirements.some((r) => r.pass);
+  const ids = p.requirements.some((r) => r.id);
+  const unshown = p.requirements.filter((r) => !r.how).length;
+  out.push(
+    `<div class="block">${sub(PRODUCT_PART_TEXT.requirements.title)}${
+      p.requirements.length
+        ? table([...(ids ? [{ h: "ID" }] : []), { h: "Requirement" }, { h: "How it is shown" }, ...(pass ? [{ h: "Pass" }] : [])], p.requirements.map((r) => [...(ids ? [esc(r.id ?? "")] : []), esc(r.text), r.how ? esc(r.how) : `<span class="muted"><i>Not stated</i></span>`, ...(pass ? [esc(r.pass ?? "")] : [])]), {
+            cls: "dense",
+            // a table that fits a page moves to the next page whole rather than leave a row behind
+            split: p.requirements.length > 18,
+            foot: `From ${esc(p.requirementsFrom ?? "")}.${unshown ? ` ${unshown} of ${p.requirements.length} do not say how they are shown.` : ""}`,
+          })
+        : missing("requirements")
+    }</div>`,
+  );
+  return out.join("\n");
+}

package/lib/figures.ts

@@ -0,0 +1,195 @@
+/**
+ * Figures from the assembly: hero, orthographic views, interface callouts,
+ * part thumbnails and exploded assembly steps. All placement comes from
+ * assemble(); explosion runs along each joint's structure-side normal, with
+ * parts ranked by where they sit on the joint (the fastenerStack positions and
+ * the mate gaps), so the exploded order is the stacking order.
+ */
+import type { InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+import { applyMat4, bodyKey, IDENTITY, type MateEdge } from "@deltarobotics/uhd";
+import type { RenderBody, RenderSpec } from "./render/renderer.ts";
+import { matTranslation, offsetMatrix, worldFrame, type SceneBody, type SceneModel } from "./model.ts";
+import type { CameraSpec } from "./types.ts";
+
+export const ISO: number[] = [1, -1.18, 0.82];
+
+export type Style = RenderBody["style"];
+
+export function renderBody(b: SceneBody, style: Style, extra: Partial<RenderBody> = {}): RenderBody {
+  return {
+    key: b.key,
+    glb: b.glb,
+    matrix: b.matrix,
+    style,
+    category: b.category,
+    hide: b.features,
+    vendor: b.vendor,
+    ...extra,
+  };
+}
+
+const sub = (a: number[], b: number[]) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const add = (a: number[], b: number[]) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const mul = (a: number[], s: number) => [a[0] * s, a[1] * s, a[2] * s];
+const dot = (a: number[], b: number[]) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+
+const isStructure = (iface: InterfaceDef) => iface.protocols?.some((p) => p.type === "bolt_pattern" && p.roles?.includes("structure"));
+
+/**
+ * Structure end and moving end of a mate (the moving end is the one the mate
+ * placed). When the scene placed neither body (no geometry, or vendor CAD not
+ * available), the end that is not the structure moves onto the one that is
+ * (a shield's component pattern onto the UNO's structure), and otherwise B
+ * onto A, along whose normal the mate's gap is measured.
+ */
+export function mateEnds(scene: SceneModel, e: MateEdge) {
+  const placedB = scene.byKey.get(bodyKey(e.b.path, e.b.frame.artifact))?.via === e.linkId;
+  const placedA = scene.byKey.get(bodyKey(e.a.path, e.a.frame.artifact))?.via === e.linkId;
+  // fastener stacks are measured from the structure-side frame
+  const structure = isStructure(e.b.iface) && !isStructure(e.a.iface) ? e.b : e.a;
+  const movesB = placedB || (!placedA && structure === e.a);
+  const moving = movesB ? e.b : e.a;
+  const fixed = movesB ? e.a : e.b;
+  return { moving, fixed, structure };
+}
+
+export interface Explosion {
+  offsets: Map<string, number[]>;
+  guides: { from: number[]; to: number[] }[];
+  /** Hardware keys in this explosion, grouped by harness child (for callouts). */
+  hardwareGroups: Map<string, SceneBody[]>;
+  moving: SceneBody[];
+}
+
+/**
+ * Explode the mates `links` (assemble linkIds). Bodies placed by those mates
+ * and the hardware on them move along the joint normal by stacking rank.
+ */
+export function explode(scene: SceneModel, links: string[], dist: number, dirOverride?: number[]): Explosion {
+  const offsets = new Map<string, number[]>();
+  const guides: Explosion["guides"] = [];
+  const hardwareGroups = new Map<string, SceneBody[]>();
+  const moving: SceneBody[] = [];
+  const mates = scene.assembly.mates.filter((m) => links.includes(m.linkId));
+
+  // group mates by structure frame (one joint = one structure pattern)
+  const joints = new Map<string, { mates: MateEdge[]; origin: number[]; normal: number[] }>();
+  for (const e of mates) {
+    const { structure } = mateEnds(scene, e);
+    const sKey = bodyKey(structure.path, structure.frame.artifact);
+    const sBody = scene.byKey.get(sKey);
+    if (!sBody) continue;
+    const wf = worldFrame(sBody.matrix, structure.frame);
+    const k = `${sKey}.${structure.iface.id}`;
+    const j = joints.get(k) ?? { mates: [], ...wf };
+    j.mates.push(e);
+    joints.set(k, j);
+  }
+
+  // parents first, so a joint on a body that itself moved carries that body's offset
+  const order = (k: string) => scene.bodies.findIndex((b) => k.startsWith(b.key + "."));
+  const sorted = [...joints.entries()].sort((a, b) => order(a[0]) - order(b[0]));
+  for (const [jk, j] of sorted) {
+    const structureKey = jk.slice(0, jk.lastIndexOf("."));
+    const base = offsets.get(structureKey) ?? [0, 0, 0];
+    const items: { body: SceneBody; pos: number; override?: boolean }[] = [];
+    for (const e of j.mates) {
+      const { moving: mv } = mateEnds(scene, e);
+      const key = bodyKey(mv.path, mv.frame.artifact);
+      const body = scene.byKey.get(key);
+      if (body && body.via === e.linkId) {
+        const wf = worldFrame(body.matrix, mv.frame);
+        items.push({ body, pos: dot(sub(wf.origin, j.origin), j.normal), override: Boolean(dirOverride) });
+        moving.push(body);
+      }
+      for (const h of scene.hardware.filter((x) => x.linkId === e.linkId)) {
+        items.push({ body: h, pos: dot(sub(matTranslation(h.matrix), j.origin), j.normal) });
+        const g = `${h.harness}/${h.child}`;
+        hardwareGroups.set(g, [...(hardwareGroups.get(g) ?? []), h]);
+      }
+    }
+    const ranked = items.filter((i) => !i.override);
+    const round = (x: number) => Math.round(x * 100) / 100;
+    const below = [...new Set(ranked.filter((i) => i.pos < -0.01).map((i) => round(i.pos)))].sort((a, b) => b - a);
+    const above = [...new Set(ranked.filter((i) => i.pos >= -0.01).map((i) => round(i.pos)))].sort((a, b) => a - b);
+    for (const it of items) {
+      let off: number[];
+      if (it.override) off = mul(dirOverride!, dist * 1.6);
+      else {
+        const p = round(it.pos);
+        const rank = p < -0.01 ? -(below.indexOf(p) + 1) : above.indexOf(p) + 1;
+        off = mul(j.normal, rank * dist);
+      }
+      offsets.set(it.body.key, add(base, off));
+    }
+    // guides: one dashed axis per hole through the exploded column
+    const holes = new Map<string, { base: number[]; ts: number[] }>();
+    for (const it of items) {
+      if (!it.body.harness) continue;
+      const p0 = matTranslation(it.body.matrix);
+      const t0 = dot(sub(p0, j.origin), j.normal);
+      const inPlane = sub(p0, mul(j.normal, t0));
+      const k = inPlane.map((x) => x.toFixed(1)).join(",");
+      const h = holes.get(k) ?? { base: add(inPlane, base), ts: [0] };
+      const off = sub(offsets.get(it.body.key) ?? [0, 0, 0], base);
+      h.ts.push(t0, t0 + dot(off, j.normal));
+      holes.set(k, h);
+    }
+    // the axis runs on to the exploded seat of the part the hardware holds
+    for (const it of items.filter((i) => !i.body.harness && !i.override)) {
+      const off = sub(offsets.get(it.body.key) ?? [0, 0, 0], base);
+      const t = it.pos + dot(off, j.normal);
+      for (const h of holes.values()) h.ts.push(t);
+    }
+    for (const h of holes.values()) {
+      const lo = Math.min(...h.ts) - 3;
+      const hi = Math.max(...h.ts) + 3;
+      guides.push({ from: add(h.base, mul(j.normal, lo)), to: add(h.base, mul(j.normal, hi)) });
+    }
+    // bodies without hardware (a prop on a shaft): axis from seat to exploded seat
+    for (const it of items.filter((i) => !i.body.harness)) {
+      const hasHw = items.some((i) => i.body.harness);
+      if (hasHw && !it.override) continue;
+      const e = j.mates.find((m) => scene.byKey.get(bodyKey(mateEnds(scene, m).moving.path, mateEnds(scene, m).moving.frame.artifact)) === it.body);
+      if (!e) continue;
+      const wf = worldFrame(it.body.matrix, mateEnds(scene, e).moving.frame);
+      const off = sub(offsets.get(it.body.key)!, base);
+      guides.push({ from: add(wf.origin, base), to: add(add(wf.origin, off), base) });
+    }
+  }
+  return { offsets, guides, hardwareGroups, moving };
+}
+
+export function withOffset(b: RenderBody, off?: number[]): RenderBody {
+  return off ? { ...b, matrix: offsetMatrix(b.matrix, off) } : b;
+}
+
+export function cameraOf(c: CameraSpec | undefined, fallback: CameraSpec): RenderSpec["camera"] {
+  return { ...fallback, ...(c ?? {}) } as RenderSpec["camera"];
+}
+
+/** Everything assembled, one style. */
+export function allBodies(scene: SceneModel, style: Style, hardwareStyle: Style = style): RenderBody[] {
+  return [...scene.bodies.map((b) => renderBody(b, style)), ...scene.hardware.map((h) => renderBody(h, hardwareStyle))];
+}
+
+/** A module on its own at its CAD origin (kit thumbnails). */
+export function isolated(def: ModuleDef, glb: string, features: string[], category: string, vendor: boolean): RenderBody[] {
+  return [{ key: def.id, glb, matrix: IDENTITY, style: "normal", category, hide: features, vendor }];
+}
+
+/** World origin of an interface frame on a placed instance ("frame.motor_mount_fl"). */
+export function interfaceAnchor(scene: SceneModel, spec: string): { p: number[]; body: SceneBody; iface: InterfaceDef } | undefined {
+  const dot = spec.lastIndexOf(".");
+  const path = spec.slice(0, dot);
+  const id = spec.slice(dot + 1);
+  for (const b of scene.bodies) {
+    if (b.path.join("/") !== path) continue;
+    const iface = b.def.interfaces.find((i) => i.id === id);
+    const frame = iface?.geometry?.frame;
+    if (!iface || !frame) continue;
+    if ((frame.artifact ?? undefined) !== (b.key.includes("#") ? b.key.split("#")[1] : frame.artifact)) continue;
+    return { p: applyMat4(b.matrix, frame.origin), body: b, iface };
+  }
+  return undefined;
+}

package/lib/format.ts

@@ -0,0 +1,221 @@
+/**
+ * Deterministic value formatting. The verifier re-formats every re-queried
+ * value with the same spec and compares strings, so all formatting of
+ * model values goes through `formatValue`.
+ *
+ * Format spec (the `f` string, `|`-separated):
+ *   d<n>        exactly n decimals          (d1 -> 22.2)
+ *   s<n>        n significant digits max    (s3 -> 171.9 -> 172)
+ *   si          scale by SI prefix          (400000 Hz -> 400 kHz)
+ *   u=<unit>    unit override               (u=g)
+ *   nounit      value only
+ *   pct         multiply by 100, unit %
+ *   hex         integer as 0x..
+ *   x           "×" join for arrays          ([45, 41, 6] -> 45 × 41 × 6)
+ *   upper       upper-case a string          (ccw -> CCW)
+ */
+
+export const NBSP = " ";
+
+const UNIT_DISPLAY: Record<string, string> = {
+  dimensionless: "",
+  C: "°C",
+  degC: "°C",
+  deg: "°",
+  ohm: "ohm",
+  mohm: "mohm",
+  "kbit/s": "kbit/s",
+  uF: "\u03bcF",
+  uA: "\u03bcA",
+};
+
+/** Characters the document fonts lack, mapped to look-alikes they have (µ → Greek mu, Σ → n-ary sum, Φ → Ø, Ω → ohm). */
+export function glyphSafe(s: string): string {
+  return s
+    .replace(/\u00b5/g, "\u03bc")
+    .replace(/\u03a3/g, "\u2211")
+    .replace(/[\u03a6\u03c6]/g, "\u00d8")
+    .replace(/\u03a9/g, " ohm")
+    .replace(/\u221d/g, "~")
+    .replace(/\u202f|\u2009/g, NBSP);
+}
+
+export function unitLabel(unit?: string): string {
+  if (!unit) return "";
+  return UNIT_DISPLAY[unit] ?? unit;
+}
+
+function groupThousands(s: string): string {
+  const [int, frac] = s.split(".");
+  const neg = int.startsWith("-");
+  const digits = neg ? int.slice(1) : int;
+  const grouped = digits.length > 4 ? digits.replace(/\B(?=(\d{3})+(?!\d))/g, " ") : digits;
+  return (neg ? "−" : "") + grouped + (frac ? "." + frac : "");
+}
+
+export function formatNumber(v: number, opts: { d?: number; s?: number } = {}): string {
+  if (!Number.isFinite(v)) return String(v);
+  let s: string;
+  if (opts.d !== undefined) s = v.toFixed(opts.d);
+  else if (opts.s !== undefined) {
+    const p = Number(v.toPrecision(opts.s));
+    s = String(p);
+    if (s.includes("e")) s = p.toFixed(0);
+  } else {
+    // default: up to 3 decimals, trailing zeros trimmed
+    s = String(Number(v.toFixed(3)));
+  }
+  return groupThousands(s);
+}
+
+const SI: [number, string][] = [
+  [1e9, "G"],
+  [1e6, "M"],
+  [1e3, "k"],
+];
+
+export interface FormatOpts {
+  d?: number;
+  s?: number;
+  si?: boolean;
+  unit?: string;
+  nounit?: boolean;
+  pct?: boolean;
+  hex?: boolean;
+  x?: boolean;
+  upper?: boolean;
+}
+
+export function parseFormat(f?: string): FormatOpts {
+  const o: FormatOpts = {};
+  for (const part of (f ?? "").split("|").filter(Boolean)) {
+    if (/^d\d+$/.test(part)) o.d = Number(part.slice(1));
+    else if (/^s\d+$/.test(part)) o.s = Number(part.slice(1));
+    else if (part === "si") o.si = true;
+    else if (part === "nounit") o.nounit = true;
+    else if (part === "pct") o.pct = true;
+    else if (part === "hex") o.hex = true;
+    else if (part === "x") o.x = true;
+    else if (part === "upper") o.upper = true;
+    else if (part.startsWith("u=")) o.unit = part.slice(2);
+    else throw new Error(`unknown format token "${part}"`);
+  }
+  return o;
+}
+
+/** Format a model value (number, [min,max] range, string, boolean, array) with its unit. */
+export function formatValue(value: unknown, unit?: string, f?: string): string {
+  const o = parseFormat(f);
+  let u = o.unit ?? unit;
+  const num = (n: number): string => {
+    let x = n;
+    if (o.pct) x = n * 100;
+    if (o.hex) return "0x" + Math.round(x).toString(16).toUpperCase().padStart(2, "0");
+    return formatNumber(x, o);
+  };
+  const withUnit = (s: string, unitStr = u) => {
+    const label = o.pct ? "%" : unitLabel(unitStr);
+    if (o.nounit || !label) return s;
+    return label === "°" ? s + label : s + NBSP + label;
+  };
+
+  if (value === undefined || value === null) return "—";
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (typeof value === "string") return glyphSafe(o.upper ? value.toUpperCase() : value);
+  if (typeof value === "number") {
+    if (o.si && u && !o.pct) {
+      for (const [k, p] of SI) {
+        if (Math.abs(value) >= k) return withUnit(formatNumber(value / k, o), p + u);
+      }
+    }
+    return withUnit(num(value));
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 2 && value.every((x) => typeof x === "number") && !o.x) {
+      const [a, b] = value as number[];
+      if (o.si && u) {
+        for (const [k, p] of SI) {
+          if (Math.abs(a) >= k) return withUnit(`${formatNumber(a / k, o)}–${formatNumber(b / k, o)}`, p + u);
+        }
+      }
+      return withUnit(`${num(a)}–${num(b)}`);
+    }
+    if (value.every((x) => typeof x === "number")) return withUnit((value as number[]).map(num).join(" × "));
+    return value.map((x) => (typeof x === "number" ? num(x) : String(x))).join(", ");
+  }
+  if (typeof value === "object") {
+    const o2 = value as Record<string, unknown>;
+    // {min, typ, max}: a range, or the typical value with its limits
+    if (typeof o2.min === "number" && typeof o2.max === "number") {
+      const r = withUnit(`${num(o2.min)}–${num(o2.max)}`);
+      return typeof o2.typ === "number" ? `${withUnit(num(o2.typ))} (${r})` : r;
+    }
+    // {length, width, height} and other all-number records: a size
+    const vals = Object.values(o2);
+    if (vals.length > 1 && vals.length <= 4 && vals.every((x) => typeof x === "number")) return withUnit((vals as number[]).map(num).join(" × "));
+  }
+  return JSON.stringify(value);
+}
+
+/** Unit symbols a key may end with (`weight_g`, `supply_V`), and how they are shown. */
+const KEY_UNITS = /_(mAh|Wh|mm|mm2|cm|m|g|kg|V|A|mA|uA|W|mW|ms|us|s|min|h|Hz|kHz|MHz|GHz|dBm|dB|C|degC|deg|ohm|mohm|uF|nF|pF|uH|in|pct|rpm|Nm|N|Bd|bps|kbps|Mbps|Gbps|ml|mL|l|L)$/;
+const KEY_UNIT_DISPLAY: Record<string, string> = { pct: "%", mm2: "mm²", Nm: "N·m", bps: "bit/s", kbps: "kbit/s", Mbps: "Mbit/s", Gbps: "Gbit/s", degC: "C", ml: "mL", l: "L" };
+
+/**
+ * Unit from a metadata key: its suffix (weight_g -> g, supply_V -> V,
+ * operating_temperature_C -> C), a ratio (kv_rpm_per_V -> rpm/V,
+ * density_g_cm3 -> g/cm³), a camel-case suffix (torqueNm -> N·m), or a key
+ * that names its quantity (rpm, baud_rate -> Bd, hole_count -> count).
+ */
+export function unitFromKey(key: string): string | undefined {
+  const per = key.match(/_([A-Za-z0-9]+)_per_([A-Za-z0-9]+)$/);
+  if (per) return `${unitFromKey(`_${per[1]}`) ?? per[1]}/${unitFromKey(`_${per[2]}`) ?? per[2]}`;
+  if (/_g_cm3$/.test(key)) return "g/cm³";
+  if (/[a-z]Nm$/.test(key)) return "N·m";
+  if (/^rpm$/i.test(key)) return "rpm";
+  if (/(^|_)baud(_rate)?$/i.test(key)) return "Bd";
+  if (/(^|_)count$|[a-z]Count$/.test(key)) return "count";
+  const m = key.match(KEY_UNITS);
+  if (!m) return undefined;
+  return KEY_UNIT_DISPLAY[m[1]] ?? m[1];
+}
+
+/** The nearest unit along a path of keys, last key first (`lowest_latency_ms.goggles_3` -> ms). */
+export function unitFromKeys(keys: string[]): string | undefined {
+  for (let i = keys.length - 1; i >= 0; i--) {
+    const u = unitFromKey(keys[i]);
+    if (u) return u;
+  }
+  return undefined;
+}
+
+const isNumeric = (value: unknown): boolean =>
+  typeof value === "number" ||
+  (Array.isArray(value) && value.length > 0 && value.every((x) => typeof x === "number")) ||
+  (!!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).length > 0 && Object.values(value).every((x) => typeof x === "number"));
+
+/**
+ * The unit a formatted value shows, as its values.json records it: the
+ * format's override (u=), its SI prefix (si: 6300 g shows as 6.3 kg) and %
+ * (pct) applied to the model's unit; "count" for a whole number with no unit
+ * (a count of mates, UARTs, props in a pack) and "dimensionless" for a
+ * fraction with none (a ratio). Undefined for text. A value
+ * shown without its unit (nounit, a table whose header names it) keeps it.
+ */
+export function displayUnit(value: unknown, unit?: string, f?: string): string | undefined {
+  if (!isNumeric(value)) return undefined;
+  const o = parseFormat(f);
+  if (o.pct) return "%";
+  if (o.hex) return unit ?? "dimensionless";
+  const u = o.unit ?? unit;
+  if (!u || u === "dimensionless") {
+    const whole = (typeof value === "number" ? [value] : Array.isArray(value) ? value : Object.values(value as object)) as number[];
+    // a whole number with no unit counts something; a fraction with none is a ratio (thrust-to-weight)
+    return whole.every((x) => Number.isInteger(x)) ? (u ?? "count") : "dimensionless";
+  }
+  if (o.si) {
+    const first = typeof value === "number" ? value : Array.isArray(value) ? (value[0] as number) : undefined;
+    if (first !== undefined) for (const [k, p] of SI) if (Math.abs(first) >= k) return unitLabel(p + u) || p + u;
+  }
+  return unitLabel(u) || u;
+}

package/lib/html.ts

@@ -0,0 +1,135 @@
+/**
+ * HTML building blocks for documents: escaping, value spans bound to model
+ * queries, markers, the page shell (CSS + pagination script).
+ *
+ * Every model value in a document is emitted by `doc.v(query, format)`:
+ *
+ *   <span class="v" data-q="def:…" data-f="d1" data-s="source">22.2 V</span><sup class="mk">A</sup>
+ *
+ * The verifier re-resolves each data-q against the live model, re-formats
+ * it with data-f and compares the text.
+ */
+import { readFileSync } from "fs";
+import { displayUnit, formatValue, glyphSafe } from "./format.ts";
+import type { DocContext, ResolvedValue, ValueStatus } from "./values.ts";
+
+export const esc = (s: unknown) =>
+  glyphSafe(String(s ?? ""))
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+export const MARKERS: Record<ValueStatus, { mark: string; label: string; help: string } | undefined> = {
+  source: undefined,
+  model: undefined,
+  measured: { mark: "M", label: "Measured", help: "from a test-data file with status measured" },
+  assumption: { mark: "A", label: "Assumption", help: "the model marks this value as an assumption (assumption trait)" },
+  derived: { mark: "D", label: "Derived", help: "computed from model values; formula in the provenance appendix" },
+  standin: { mark: "S", label: "Stand-in", help: "stand-in data derived from the model, not measured" },
+  gap: { mark: "—", label: "Not in model", help: "the model does not state this value (data gap)" },
+};
+
+export interface DocMeta {
+  title: string;
+  docType: string;
+  docId: string;
+  revision: string;
+  date: string;
+  system: string;
+}
+
+export interface RenderedValue extends ResolvedValue {
+  f?: string;
+  text: string;
+}
+
+export class Doc {
+  values = new Map<string, RenderedValue>();
+  statuses = new Set<ValueStatus>();
+  constructor(
+    public ctx: DocContext,
+    public meta: DocMeta,
+  ) {}
+
+  /** Resolve and format a value; records it for the provenance appendix and the verifier. */
+  text(q: string, f?: string): { text: string; r: ResolvedValue } {
+    const r = this.ctx.resolve(q);
+    const text = r.status === "gap" && (r.value === undefined || r.value === null) ? "—" : formatValue(r.value, r.unit, f);
+    const key = `${q}|${f ?? ""}`;
+    // the unit the text shows (values.json): the format's override, SI prefix and % applied
+    if (!this.values.has(key)) this.values.set(key, { ...r, unit: displayUnit(r.value, r.unit, f) ?? r.unit, f, text });
+    this.statuses.add(r.status);
+    return { text, r };
+  }
+
+  /** Inline value span with its status marker. */
+  v(q: string, f?: string, opts: { marker?: boolean; cls?: string } = {}): string {
+    const { text, r } = this.text(q, f);
+    const mk = MARKERS[r.status];
+    const title = [r.source && `Source: ${r.source}`, r.formula && `Formula: ${r.formula}`, r.note].filter(Boolean).join(" · ");
+    // number and unit in separate spans so display type can set the unit in the text face (textContent unchanged)
+    const nu = text.match(/^(.*\d)\u00a0([^\d]+)$/);
+    const inner = nu ? `<span class="n">${esc(nu[1])}</span>\u00a0<span class="u">${esc(nu[2])}</span>` : esc(text);
+    const span = `<span class="v${opts.cls ? " " + opts.cls : ""} st-${r.status}" data-q="${esc(q)}"${f ? ` data-f="${esc(f)}"` : ""} data-s="${r.status}"${title ? ` title="${esc(title)}"` : ""}>${inner}</span>`;
+    return opts.marker === false || !mk ? span : `${span}<sup class="mk mk-${r.status}">${mk.mark}</sup>`;
+  }
+
+  /** SVG <text> bound to a query (figures, callouts). */
+  svgText(q: string, f: string | undefined, attrs: string): string {
+    const { text, r } = this.text(q, f);
+    return `<text ${attrs} data-q="${esc(q)}"${f ? ` data-f="${esc(f)}"` : ""} data-s="${r.status}">${esc(text)}</text>`;
+  }
+
+  /** Where the marker legend goes; filled in once every value is known (fillLegends). */
+  legendPlaceholder(): string {
+    return `<div class="legend-slot"></div>`;
+  }
+
+  fillLegends(html: string): string {
+    return html.replace(/<div class="legend-slot"><\/div>/g, this.legend());
+  }
+
+  legend(): string {
+    const used = (Object.keys(MARKERS) as ValueStatus[]).filter((s) => MARKERS[s] && this.statuses.has(s));
+    if (!used.length) return "";
+    return `<div class="legend">${used
+      .map((s) => `<span><sup class="mk mk-${s}">${MARKERS[s]!.mark}</sup> ${esc(MARKERS[s]!.label)}: ${esc(MARKERS[s]!.help)}</span>`)
+      .join("")}<span>Unmarked values are cited from the part's sources (sources.json) or are design values of the model.</span></div>`;
+  }
+}
+
+const TEMPLATES = new URL("./templates/", import.meta.url);
+export const readTemplate = (name: string) => readFileSync(new URL(name, TEMPLATES), "utf8");
+
+/** Full HTML document around the flow blocks; `flow.js` paginates it in the browser. */
+export function shell(meta: DocMeta, body: string, opts: { fontsHref: string; extraCss?: string }): string {
+  const css = readTemplate("doc.css").replace(/__FONTS__/g, opts.fontsHref);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="generator" content="uhd-tech-docs (@protoboardai/ext-docs)">
+<meta name="uhd-system" content="${esc(meta.system)}">
+<meta name="uhd-doc-type" content="${esc(meta.docType)}">
+<meta name="uhd-doc-id" content="${esc(meta.docId)}">
+<title>${esc(meta.title)} — ${esc(meta.docType)}</title>
+<style>${css}${opts.extraCss ?? ""}</style>
+</head>
+<body>
+<template id="page-template">
+  <div class="page">
+    <header class="pg-head"><span class="pg-mark"></span><span class="pg-title">${esc(meta.title)}</span><span class="pg-type">${esc(meta.docType)}</span><span class="pg-id">${esc(meta.docId)}</span></header>
+    <main class="pg-body"></main>
+    <footer class="pg-foot"><span class="pg-brand">PR<b>0</b>TOBOARD · UHD</span><span class="pg-rev">${esc(meta.docId)} · Rev ${esc(meta.revision)} · ${esc(meta.date)}</span><span class="pg-num"></span></footer>
+  </div>
+</template>
+<div id="pages"></div>
+<section id="flow">
+${body}
+</section>
+<script id="flow-script">${readTemplate("flow.js")}</script>
+</body>
+</html>
+`;
+}