@protoboardai/ext-docs 0.0.0-stage → 0.2.0

package/lib/charts.ts

@@ -0,0 +1,241 @@
+/**
+ * Print charts as inline SVG: hairline grid, direct labels, one accent
+ * series, greys for context. Data drawn from test-data files carries the
+ * file's status; stand-in data is watermarked "STAND-IN DATA — not measured".
+ */
+import { formatNumber } from "./format.ts";
+import { esc } from "./html.ts";
+
+export const INK = "#1b1b1b";
+export const MUTED = "#6f6f6f";
+export const GRID = "#e4e4e4";
+export const ACCENT = "#ff5c00";
+export const SERIES = [ACCENT, "#1b1b1b", "#8c8c8c", "#c46a2c", "#4a6fa5"];
+
+export interface Axis {
+  label: string;
+  unit?: string;
+  min?: number;
+  max?: number;
+  ticks?: number;
+}
+
+export interface Series {
+  label: string;
+  points: [number, number][];
+  color?: string;
+  dashed?: boolean;
+  markers?: boolean;
+  /** Draw only markers (measured/source points). */
+  markersOnly?: boolean;
+  axis?: "y" | "y2";
+  /** Label placed at the last point (direct labelling). */
+  endLabel?: boolean;
+}
+
+export interface ChartBase {
+  width?: number;
+  height?: number;
+  /** "standin" | "measured" | "source" | "derived" — standin draws the watermark. */
+  status?: string;
+  /** Test id(s) the chart draws, for the verifier. */
+  testIds?: string[];
+  title?: string;
+}
+
+function niceTicks(min: number, max: number, count = 5): number[] {
+  const span = max - min || 1;
+  const step0 = span / count;
+  const mag = 10 ** Math.floor(Math.log10(step0));
+  const step = [1, 2, 2.5, 5, 10].map((m) => m * mag).find((s) => span / s <= count + 0.5) ?? mag * 10;
+  const out: number[] = [];
+  for (let v = Math.ceil(min / step - 1e-9) * step; v <= max + 1e-9; v += step) out.push(Number(v.toFixed(10)));
+  return out;
+}
+
+function niceMax(v: number): number {
+  if (v <= 0) return 1;
+  const mag = 10 ** Math.floor(Math.log10(v));
+  for (const m of [1, 1.2, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10]) if (m * mag >= v) return m * mag;
+  return 10 * mag;
+}
+
+const axisTitle = (a: Axis) => esc(a.unit ? `${a.label} (${a.unit})` : a.label);
+
+function watermark(w: number, h: number, status?: string): string {
+  if (status !== "standin") return "";
+  const cx = w / 2;
+  const cy = h / 2;
+  return `<g class="standin-mark" pointer-events="none">
+    <text x="${cx}" y="${cy}" transform="rotate(-18 ${cx} ${cy})" text-anchor="middle" dominant-baseline="middle"
+      font-size="${Math.min(22, w / 22)}" font-weight="700" fill="${ACCENT}" fill-opacity="0.13" letter-spacing="1.5">STAND-IN DATA — NOT MEASURED</text>
+    <rect x="${w / 2 - 58}" y="1" width="116" height="14" rx="2" fill="#fff" stroke="${ACCENT}" stroke-width="0.8"/>
+    <text x="${w / 2}" y="10.8" text-anchor="middle" font-size="7.2" font-weight="700" fill="${ACCENT}" letter-spacing="0.6">STAND-IN · NOT MEASURED</text>
+  </g>`;
+}
+
+function frame(w: number, h: number, body: string, base: ChartBase): string {
+  const data = base.testIds?.length ? ` data-test="${esc(base.testIds.join(" "))}"` : "";
+  return `<svg class="chart" viewBox="0 0 ${w} ${h}" width="${w}" height="${h}" data-status="${esc(base.status ?? "source")}"${data} xmlns="http://www.w3.org/2000/svg" font-family="inherit">${body}${watermark(w, h, base.status)}</svg>`;
+}
+
+export function lineChart(o: ChartBase & { x: Axis; y: Axis; y2?: Axis; series: Series[]; legend?: boolean; annotations?: { x: number; y: number; label: string; axis?: "y" | "y2" }[] }): string {
+  const W = o.width ?? 330;
+  const H = o.height ?? 190;
+  const m = { l: 40, r: o.y2 ? 40 : 14, t: 20, b: o.legend ? 44 : 32 };
+  const pw = W - m.l - m.r;
+  const ph = H - m.t - m.b;
+  const all = (ax: "y" | "y2") => o.series.filter((s) => (s.axis ?? "y") === ax).flatMap((s) => s.points);
+  const xs = o.series.flatMap((s) => s.points.map((p) => p[0]));
+  const xmin = o.x.min ?? Math.min(...xs);
+  const xmax = o.x.max ?? Math.max(...xs);
+  const range = (a: Axis, pts: [number, number][]) => [a.min ?? Math.min(0, ...pts.map((p) => p[1])), a.max ?? niceMax(Math.max(...pts.map((p) => p[1])))];
+  const [ymin, ymax] = range(o.y, all("y"));
+  const [y2min, y2max] = o.y2 ? range(o.y2, all("y2")) : [0, 1];
+  const sx = (v: number) => m.l + ((v - xmin) / (xmax - xmin || 1)) * pw;
+  const sy = (v: number, ax: "y" | "y2" = "y") => {
+    const [a, b] = ax === "y" ? [ymin, ymax] : [y2min, y2max];
+    return m.t + ph - ((v - a) / (b - a || 1)) * ph;
+  };
+  const parts: string[] = [];
+  // grid + ticks
+  for (const t of niceTicks(ymin, ymax, o.y.ticks ?? 5)) {
+    parts.push(`<line x1="${m.l}" x2="${m.l + pw}" y1="${sy(t)}" y2="${sy(t)}" stroke="${GRID}" stroke-width="0.5"/>`);
+    parts.push(`<text x="${m.l - 5}" y="${sy(t) + 2.6}" text-anchor="end" font-size="7" fill="${MUTED}">${formatNumber(t)}</text>`);
+  }
+  if (o.y2) {
+    for (const t of niceTicks(y2min, y2max, o.y2.ticks ?? 5)) {
+      parts.push(`<text x="${m.l + pw + 5}" y="${sy(t, "y2") + 2.6}" font-size="7" fill="${MUTED}">${formatNumber(t)}</text>`);
+    }
+  }
+  for (const t of niceTicks(xmin, xmax, o.x.ticks ?? 6)) {
+    parts.push(`<line x1="${sx(t)}" x2="${sx(t)}" y1="${m.t + ph}" y2="${m.t + ph + 3}" stroke="${MUTED}" stroke-width="0.5"/>`);
+    parts.push(`<text x="${sx(t)}" y="${m.t + ph + 12}" text-anchor="middle" font-size="7" fill="${MUTED}">${formatNumber(t)}</text>`);
+  }
+  parts.push(`<line x1="${m.l}" x2="${m.l + pw}" y1="${m.t + ph}" y2="${m.t + ph}" stroke="${INK}" stroke-width="0.7"/>`);
+  parts.push(`<text x="${m.l + pw / 2}" y="${m.t + ph + 24}" text-anchor="middle" font-size="7.2" fill="${INK}">${axisTitle(o.x)}</text>`);
+  parts.push(`<text x="${m.l - 34}" y="${m.t - 8}" font-size="7.2" fill="${INK}">${axisTitle(o.y)}</text>`);
+  if (o.y2) parts.push(`<text x="${m.l + pw + 34}" y="${m.t - 8}" text-anchor="end" font-size="7.2" fill="${INK}">${axisTitle(o.y2)}</text>`);
+  // series
+  const labels: { x: number; y: number; anchor: string; color: string; text: string }[] = [];
+  o.series.forEach((s, i) => {
+    const color = s.color ?? SERIES[i % SERIES.length];
+    const ax = s.axis ?? "y";
+    const pts = s.points.map(([x, y]) => `${sx(x).toFixed(1)},${sy(y, ax).toFixed(1)}`);
+    if (!s.markersOnly && pts.length > 1) {
+      parts.push(`<polyline points="${pts.join(" ")}" fill="none" stroke="${color}" stroke-width="${i === 0 ? 1.6 : 1.2}" stroke-linejoin="round"${s.dashed ? ' stroke-dasharray="4 2.5"' : ""}/>`);
+    }
+    if (s.markers || s.markersOnly) {
+      for (const [x, y] of s.points) parts.push(`<circle cx="${sx(x)}" cy="${sy(y, ax)}" r="2.4" fill="#fff" stroke="${color}" stroke-width="1.2"/>`);
+    }
+    if (!o.legend && s.endLabel !== false && s.points.length && s.label) {
+      const [x, y] = s.points[s.points.length - 1];
+      const px = sx(x);
+      const anchorEnd = px > m.l + pw - 60;
+      labels.push({ x: anchorEnd ? px - 4 : px + 4, y: sy(y, ax) - 5, anchor: anchorEnd ? "end" : "start", color, text: s.label });
+    }
+  });
+  if (o.legend) {
+    let lx = m.l;
+    o.series.forEach((s, i) => {
+      if (!s.label) return;
+      const color = s.color ?? SERIES[i % SERIES.length];
+      const y = H - 5;
+      parts.push(s.markersOnly ? `<circle cx="${lx + 5}" cy="${y - 2.5}" r="2.4" fill="#fff" stroke="${color}" stroke-width="1.2"/>` : `<line x1="${lx}" x2="${lx + 12}" y1="${y - 2.5}" y2="${y - 2.5}" stroke="${color}" stroke-width="1.6"${s.dashed ? ' stroke-dasharray="4 2.5"' : ""}/>`);
+      parts.push(`<text x="${lx + 16}" y="${y}" font-size="6.8" fill="${INK}">${esc(s.label)}</text>`);
+      lx += 26 + s.label.length * 4.3;
+    });
+  }
+  // direct labels, pushed apart vertically so they never overlap
+  labels.sort((a, b) => a.y - b.y);
+  for (let i = 1; i < labels.length; i++) if (labels[i].y - labels[i - 1].y < 9) labels[i].y = labels[i - 1].y + 9;
+  for (const l of labels) parts.push(`<text x="${l.x}" y="${l.y}" text-anchor="${l.anchor}" font-size="7" font-weight="600" fill="${l.color}">${esc(l.text)}</text>`);
+  for (const a of o.annotations ?? []) {
+    const x = sx(a.x);
+    const y = sy(a.y, a.axis ?? "y");
+    parts.push(`<circle cx="${x}" cy="${y}" r="2" fill="${INK}"/><text x="${x + 5}" y="${y + 10}" font-size="6.8" fill="${INK}">${esc(a.label)}</text>`);
+  }
+  return frame(W, H, parts.join(""), o);
+}
+
+export function barChart(
+  o: ChartBase & {
+    categories: string[];
+    series: { label: string; values: number[]; color?: string }[];
+    y: Axis;
+    stacked?: boolean;
+    /** Horizontal reference lines, e.g. a rating. */
+    refs?: { value: number; label: string }[];
+    valueLabels?: boolean;
+    decimals?: number;
+  },
+): string {
+  const W = o.width ?? 330;
+  const H = o.height ?? 190;
+  const legendH = o.series.length > 1 ? 14 : 0;
+  const m = { l: 40, r: 12, t: 20 + legendH, b: 34 };
+  const pw = W - m.l - m.r;
+  const ph = H - m.t - m.b;
+  const totals = o.categories.map((_, i) => (o.stacked ? o.series.reduce((s, x) => s + x.values[i], 0) : Math.max(...o.series.map((x) => x.values[i]))));
+  const ymax = o.y.max ?? niceMax(Math.max(...totals, ...(o.refs ?? []).map((r) => r.value)) * 1.08);
+  const sy = (v: number) => m.t + ph - (v / ymax) * ph;
+  const band = pw / o.categories.length;
+  const bw = o.stacked ? Math.min(34, band * 0.55) : Math.min(22, (band * 0.7) / o.series.length);
+  const parts: string[] = [];
+  for (const t of niceTicks(0, ymax, o.y.ticks ?? 5)) {
+    parts.push(`<line x1="${m.l}" x2="${m.l + pw}" y1="${sy(t)}" y2="${sy(t)}" stroke="${GRID}" stroke-width="0.5"/>`);
+    parts.push(`<text x="${m.l - 5}" y="${sy(t) + 2.6}" text-anchor="end" font-size="7" fill="${MUTED}">${formatNumber(t)}</text>`);
+  }
+  o.categories.forEach((c, i) => {
+    const cx = m.l + band * i + band / 2;
+    let base = 0;
+    o.series.forEach((s, k) => {
+      const v = s.values[i];
+      const color = s.color ?? SERIES[k % SERIES.length];
+      const x = o.stacked ? cx - bw / 2 : cx - (bw * o.series.length) / 2 + k * bw;
+      const y0 = o.stacked ? base : 0;
+      parts.push(`<rect x="${x.toFixed(1)}" y="${sy(y0 + v).toFixed(1)}" width="${(bw - (o.stacked ? 0 : 1.5)).toFixed(1)}" height="${Math.max(0, sy(y0) - sy(y0 + v)).toFixed(1)}" fill="${color}"/>`);
+      if (o.valueLabels && !o.stacked) parts.push(`<text x="${x + bw / 2}" y="${sy(v) - 3}" text-anchor="middle" font-size="6.6" fill="${INK}">${formatNumber(v, { d: o.decimals })}</text>`);
+      if (o.stacked) base += v;
+    });
+    if (o.valueLabels && o.stacked) parts.push(`<text x="${cx}" y="${sy(totals[i]) - 3}" text-anchor="middle" font-size="6.8" font-weight="600" fill="${INK}">${formatNumber(totals[i], { d: o.decimals })}</text>`);
+    const words = c.split(" ");
+    const lines = words.length > 1 && c.length > 12 ? [words.slice(0, Math.ceil(words.length / 2)).join(" "), words.slice(Math.ceil(words.length / 2)).join(" ")] : [c];
+    lines.forEach((ln, j) => parts.push(`<text x="${cx}" y="${m.t + ph + 11 + j * 8}" text-anchor="middle" font-size="7" fill="${INK}">${esc(ln)}</text>`));
+  });
+  for (const r of o.refs ?? []) {
+    parts.push(`<line x1="${m.l}" x2="${m.l + pw}" y1="${sy(r.value)}" y2="${sy(r.value)}" stroke="${INK}" stroke-width="0.8" stroke-dasharray="3 2"/>`);
+    parts.push(`<text x="${m.l + pw}" y="${sy(r.value) - 3}" text-anchor="end" font-size="6.8" fill="${INK}">${esc(r.label)}</text>`);
+  }
+  parts.push(`<line x1="${m.l}" x2="${m.l + pw}" y1="${m.t + ph}" y2="${m.t + ph}" stroke="${INK}" stroke-width="0.7"/>`);
+  parts.push(`<text x="${m.l - 34}" y="${m.t - 8}" font-size="7.2" fill="${INK}">${axisTitle(o.y)}</text>`);
+  if (o.series.length > 1) {
+    let lx = m.l;
+    o.series.forEach((s, k) => {
+      const color = s.color ?? SERIES[k % SERIES.length];
+      parts.push(`<rect x="${lx}" y="6" width="8" height="8" fill="${color}"/><text x="${lx + 11}" y="13" font-size="7" fill="${INK}">${esc(s.label)}</text>`);
+      lx += 18 + s.label.length * 4.6;
+    });
+  }
+  return frame(W, H, parts.join(""), o);
+}
+
+/** Horizontal utilisation bars (rails, budgets): value of capacity with a percentage. */
+export function meterChart(o: ChartBase & { rows: { label: string; value: number; capacity: number; unit: string; note?: string }[] }): string {
+  const W = o.width ?? 330;
+  const rowH = 36;
+  const H = o.rows.length * rowH + 4;
+  const bw = W - 44;
+  const parts: string[] = [];
+  o.rows.forEach((r, i) => {
+    const y = 4 + i * rowH;
+    const frac = r.capacity ? Math.min(1, r.value / r.capacity) : 0;
+    parts.push(`<text x="0" y="${y + 8}" font-size="7.6" font-weight="600" fill="${INK}">${esc(r.label)}</text>`);
+    parts.push(`<text x="${bw}" y="${y + 8}" font-size="6.8" text-anchor="end" fill="${MUTED}">${formatNumber(r.value)} of ${formatNumber(r.capacity)} ${esc(r.unit)}</text>`);
+    parts.push(`<rect x="0" y="${y + 12}" width="${bw}" height="8" fill="#efefef"/>`);
+    parts.push(`<rect x="0" y="${y + 12}" width="${(bw * frac).toFixed(1)}" height="8" fill="${frac > 0.8 ? "#c62828" : ACCENT}"/>`);
+    parts.push(`<text x="${bw + 5}" y="${y + 18.6}" font-size="7.4" font-weight="600" fill="${INK}">${r.capacity ? Math.round(frac * 100) + " %" : "n/a"}</text>`);
+    if (r.note) parts.push(`<text x="0" y="${y + 29}" font-size="6.4" fill="${MUTED}">${esc(r.note)}</text>`);
+  });
+  return frame(W, H, parts.join(""), o);
+}

package/lib/context.ts

@@ -0,0 +1,122 @@
+/**
+ * Build the document context for a project's system: model, assembly,
+ * checks, wiring (including sub-assemblies), scenarios, BOM, test data and
+ * the resolver.
+ */
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { checkSystem } from "@deltarobotics/uhd";
+import { isNet, wiringChecklist, type WiringStep } from "@deltarobotics/uhd";
+import { boardModules, type Project } from "@protoboardai/core";
+import { buildBom, type BomRow } from "./bom.ts";
+import { buildScene, loadSystem, type LoadedSystem } from "./model.ts";
+import { loadTestData } from "./testdata.ts";
+import { DERIVED } from "./derived.ts";
+import { instanceMap, makeResolver, type DocContext } from "./values.ts";
+
+export interface BuiltContext extends DocContext {
+  testErrors: string[];
+  /** The documents' BOM file as committed (`docs/<system-id>-bom.json`): what the documents publish. */
+  generatedBom?: BomRow[];
+  /** buildBom() from the live model, to detect a stale BOM file. */
+  liveBom: BomRow[];
+}
+
+/** Project-relative path of the BOM file the documents publish. */
+export const bomFile = (sys: LoadedSystem) => `${sys.docsDir}/${sys.system.id}-bom.json`;
+
+/**
+ * Wiring for the system and every sub-assembly that declares links (ids
+ * prefixed with the instance path). A circuit board (a module with Net
+ * interfaces) is not descended into: its links are its copper, made by the
+ * fab, not wired at the bench.
+ */
+export function fullWiring(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined): WiringStep[] {
+  const out: WiringStep[] = [...wiringChecklist(system, lookup)];
+  const visit = (d: ModuleDef, prefix: string[]) => {
+    for (const c of d.children ?? []) {
+      const def = lookup(c.moduleDefId);
+      if (!def || def.kind === "harness") continue;
+      const path = [...prefix, c.id];
+      // a circuit board (a module with Net interfaces, or drawn whole by a body of its own): its links are
+      // copper, made by the fab, not wired at the bench
+      if (def.interfaces.some(isNet) || (def.artifacts?.some((a) => a.role === "body" && a.format === "glb") && def.children?.length)) continue;
+      if (def.links?.length) {
+        for (const s of wiringChecklist(def, lookup)) {
+          if (s.domain === "mechanical") continue;
+          const p = path.join("/");
+          out.push({
+            ...s,
+            linkId: `${p}/${s.linkId}`,
+            a: `${p}/${s.a}`,
+            b: `${p}/${s.b}`,
+            harness: s.harness ? `${p}/${s.harness}` : undefined,
+            connections: s.connections.map((c2) => ({ ...c2, from: `${p}/${c2.from}`, to: `${p}/${c2.to}` })),
+          });
+        }
+      }
+      visit(def, path);
+    }
+  };
+  visit(system, []);
+  return out;
+}
+
+/**
+ * checkSystem on each circuit board below a system (a definition with Net
+ * interfaces), once per definition at its first instance: the root's check
+ * does not descend into a board's nets, so a fault on a board's copper is only
+ * seen by checking the board itself. Filtered as `protoboard check` does: the
+ * root's check covers the tree for unknown categories and passive overrides,
+ * and a board is powered from outside it (through its exports), so "unpowered"
+ * is not a finding on the board alone.
+ */
+export function boardChecks(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined) {
+  return boardModules(system, lookup as Parameters<typeof boardModules>[1]).map((b) => ({
+    path: b.path,
+    id: b.def.id,
+    diagnostics: checkSystem(b.def, lookup).diagnostics.filter((x) => !["unknown_category", "passive_override", "unpowered"].includes(x.rule)),
+  }));
+}
+
+/** checkSystem on a system plus each circuit board below it (`boardChecks`), board findings prefixed with the board's path. */
+export function checkWithBoards(system: ModuleDef, lookup: (id: string) => ModuleDef | undefined) {
+  const root = checkSystem(system, lookup);
+  const extra = boardChecks(system, lookup).flatMap(({ path: at, diagnostics }) =>
+    diagnostics.map((x) => ({ ...x, id: `${at}/${x.id}`, message: `${at}: ${x.message}`, refs: x.refs.map((r) => (r.startsWith("link:") ? `link:${at}/${r.slice(5)}` : `${at}/${r}`)) })),
+  );
+  return { ...root, diagnostics: [...root.diagnostics, ...extra] };
+}
+
+export async function buildContext(p: Project): Promise<BuiltContext> {
+  const sys = await loadSystem(p);
+  const scene = buildScene(sys);
+  // the system's own check; its boards' findings are in `boards` (the datasheet's rail table reads both)
+  const checks = checkSystem(sys.system, sys.lookup);
+  const wiring = fullWiring(sys.system, sys.lookup);
+  // each scenario's system and its boards (a board's own nets are checked on the board module, as protoboard check does)
+  const scenarioChecks = sys.scenarios.map((s) => ({ id: s.id, label: s.label, description: s.description, diagnostics: checkWithBoards(s.system, s.lookup).diagnostics }));
+  const boards = boardChecks(sys.system, sys.lookup);
+  const { tests, errors } = loadTestData(sys.absDocs, sys.docsDir);
+  const genPath = join(sys.root, bomFile(sys));
+  const generatedBom = existsSync(genPath) ? (JSON.parse(readFileSync(genPath, "utf8")) as BomRow[]) : undefined;
+  const liveBom = buildBom(sys.system, sys.lookup, sys.evidenceDirs);
+  const partial = {
+    sys,
+    scene,
+    bom: generatedBom ?? liveBom,
+    checks,
+    wiring,
+    scenarioChecks,
+    boards,
+    tests,
+    derived: { ...DERIVED },
+    instances: instanceMap(sys.system, sys.lookup),
+    testErrors: errors,
+    generatedBom,
+    liveBom,
+  };
+  makeResolver(partial as any);
+  return partial as unknown as BuiltContext;
+}

package/lib/derived.ts

@@ -0,0 +1,181 @@
+/**
+ * Named derivations (`derived:<name>` queries). Each lists the model queries
+ * it reads, so a document can show the formula and inputs, and the verifier
+ * can recompute it. Derivations find modules by what they are (category),
+ * so they work for any system that has the parts, not just the quadcopter.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import { fullThrottle, thrustTests } from "@deltarobotics/uhd";
+import { massByDefinition, moduleMass, systemMass, type ModuleMass, type SystemMass } from "@deltarobotics/uhd";
+import { cadVolume, category } from "./model.ts";
+import type { DerivedDef, DocContext } from "./values.ts";
+
+/** System mass from the model (UHD systemMass): stated weights, else CAD volume × material density. */
+export function modelMass(ctx: DocContext): SystemMass {
+  return systemMass(ctx.sys.system, ctx.sys.lookup, cadVolume(ctx.sys));
+}
+
+/** Model queries a module's mass rests on. */
+function massInputs(def: ModuleDef, m?: ModuleMass): string[] {
+  if (!m) return [];
+  if (m.basis === "stated") return [`def:${def.id}:domains[domain=mechanical].weight_g`];
+  return [`def:${def.id}:domains[domain=mechanical].material.density_g_cm3`];
+}
+
+const motors = (ctx: DocContext) => ctx.scene.assembly.instances.filter((i) => i.kind === "module" && category(i.def) === "motor");
+const firstOf = (ctx: DocContext, cat: string) => ctx.scene.assembly.instances.find((i) => i.kind === "module" && category(i.def) === cat)?.def;
+
+export const DERIVED: Record<string, DerivedDef> = {
+  "mass.all_up": {
+    label: "All-up weight of parts with a mass in the model",
+    unit: "g",
+    formula: "systemMass: ∑ quantity × (weight_g, else CAD volume × material density) over every instance; instances with neither are listed, not guessed",
+    compute: (ctx) => {
+      const m = modelMass(ctx);
+      const groups = massByDefinition(m).filter((g) => g.mass);
+      return {
+        value: Number(m.totalG.toFixed(1)),
+        inputs: groups.flatMap((g) => massInputs(g.def, g.mass)),
+        note: m.missing.length ? `excludes ${m.missing.length} part(s) with no mass: ${m.missing.map((e) => e.def.name).join(", ")}; ${m.assumedG.toFixed(1)} g of it is computed from assumed material/geometry` : undefined,
+      };
+    },
+  },
+  "mass.assumed": {
+    label: "Part of the all-up weight computed from assumed material or nominal geometry",
+    unit: "g",
+    formula: "∑ systemMass entries whose material carries an assumption",
+    compute: (ctx) => {
+      const m = modelMass(ctx);
+      const groups = massByDefinition(m).filter((g) => g.mass?.assumed);
+      return { value: Number(m.assumedG.toFixed(1)), inputs: groups.flatMap((g) => massInputs(g.def, g.mass)) };
+    },
+  },
+  "mass.missing_count": {
+    label: "Parts without a mass in the model",
+    formula: "count (by quantity) of systemMass entries with no weight_g and no material + CAD volume",
+    compute: (ctx) => {
+      const m = modelMass(ctx);
+      return { value: m.missing.reduce((s, e) => s + e.quantity, 0), inputs: [], note: m.missing.map((e) => `${e.def.name} (${e.path})`).join(", ") };
+    },
+  },
+  "mass.module": {
+    label: "Mass of one module",
+    unit: "g",
+    formula: "weight_g if stated, else CAD body volume (generator manifest) × domains[mechanical].material.density_g_cm3",
+    compute: (ctx, args = []) => {
+      const def = ctx.sys.lookup(args[0] ?? "");
+      const m = def ? moduleMass(def, cadVolume(ctx.sys)) : undefined;
+      return {
+        value: m ? Number(m.massG.toFixed(m.massG < 1 ? 2 : 1)) : undefined,
+        inputs: def ? massInputs(def, m) : [],
+        note: m?.basis === "cad_volume" ? `${(m.volumeMm3! / 1000).toFixed(2)} cm³ × ${m.material!.density_g_cm3} g/cm³ (${m.material!.name})${m.assumed ? "; assumption: " + m.material!.assumption : ""}` : undefined,
+      };
+    },
+  },
+  "propulsion.motor_count": {
+    label: "Motors",
+    formula: "count of motor instances",
+    compute: (ctx) => ({ value: motors(ctx).length, inputs: [] }),
+  },
+  "propulsion.thrust_full_total": {
+    label: "Static thrust, all motors at full throttle",
+    unit: "g",
+    formula: "motors × thrust_g of the top (100 %) row of the first thrust table",
+    compute: (ctx) => {
+      const m = motors(ctx);
+      const d = m[0]?.def;
+      const t = d && thrustTests(d)[0];
+      const top = t ? fullThrottle(t) : undefined;
+      return {
+        value: top ? m.length * top.thrust_g : undefined,
+        inputs: d && top ? [`def:${d.id}:traits[type=performance].params.thrust_tests[0].rows[throttle_pct=${top.throttle_pct}].thrust_g`] : [],
+        note: t ? `manufacturer table with ${t.propeller} at ${t.supply_V} V (not the fitted propeller)` : "no thrust test in the motor model",
+      };
+    },
+  },
+  "propulsion.current_full_total": {
+    label: "Static current, all motors at full throttle",
+    unit: "A",
+    formula: "motors × current_A of the top (100 %) row of the first thrust table",
+    compute: (ctx) => {
+      const m = motors(ctx);
+      const d = m[0]?.def;
+      const t = d && thrustTests(d)[0];
+      const top = t ? fullThrottle(t) : undefined;
+      return {
+        value: top ? Number((m.length * top.current_A).toFixed(2)) : undefined,
+        inputs: d && top ? [`def:${d.id}:traits[type=performance].params.thrust_tests[0].rows[throttle_pct=${top.throttle_pct}].current_A`] : [],
+      };
+    },
+  },
+  "power.battery_c_ratio_peak": {
+    label: "Peak propulsion current / battery continuous rating",
+    formula: "checks propulsion_current totalPeak ÷ battery max_current",
+    compute: (ctx) => {
+      const d = ctx.checks.diagnostics.find((x) => x.rule === "propulsion_current");
+      const det = (d as any)?.details;
+      return {
+        value: det ? Number((det.totalPeak / det.cont).toFixed(3)) : undefined,
+        inputs: ["sys:checks.diagnostics[rule=propulsion_current].details.totalPeak", "sys:checks.diagnostics[rule=propulsion_current].details.cont"],
+      };
+    },
+  },
+  "power.battery_energy_Wh": {
+    label: "Battery energy",
+    unit: "Wh",
+    formula: "battery voltage × capacity",
+    compute: (ctx) => {
+      const b = firstOf(ctx, "battery");
+      const out = b?.interfaces.find((i) => i.parameters?.some((p) => p.id === "capacity"));
+      const v = out?.parameters?.find((p) => p.id === "voltage")?.value;
+      const c = out?.parameters?.find((p) => p.id === "capacity")?.value;
+      return {
+        value: v !== undefined && c !== undefined ? Number(((v * c) / 1000).toFixed(2)) : undefined,
+        inputs: b && out ? [`def:${b.id}:interfaces[id=${out.id}].parameters[id=voltage].value`, `def:${b.id}:interfaces[id=${out.id}].parameters[id=capacity].value`] : [],
+      };
+    },
+  },
+  frameDistance: {
+    label: "Distance between two interface frames in the assembly",
+    unit: "mm",
+    formula: "|placement(a) · a.frame.origin − placement(b) · b.frame.origin| from assemble()",
+    compute: (ctx, args = []) => {
+      const pts = args.map((spec) => {
+        const dot = spec.lastIndexOf(".");
+        const path = spec.slice(0, dot);
+        const id = spec.slice(dot + 1);
+        const body = ctx.scene.bodies.find((b) => b.path.join("/") === path && b.def.interfaces.some((i) => i.id === id && i.geometry?.frame));
+        const f = body?.def.interfaces.find((i) => i.id === id)?.geometry?.frame;
+        if (!body || !f) return undefined;
+        const m = body.matrix;
+        const o = f.origin;
+        return [m[0] * o[0] + m[1] * o[1] + m[2] * o[2] + m[3], m[4] * o[0] + m[5] * o[1] + m[6] * o[2] + m[7], m[8] * o[0] + m[9] * o[1] + m[10] * o[2] + m[11]];
+      });
+      const [a, b] = pts;
+      const inst = (spec: string) => {
+        const dot = spec.lastIndexOf(".");
+        const path = spec.slice(0, dot);
+        const id = spec.slice(dot + 1);
+        return `inst:${path}:interfaces[id=${id}].geometry.frame.origin`;
+      };
+      return {
+        value: a && b ? Number(Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]).toFixed(2)) : undefined,
+        inputs: args.map(inst),
+      };
+    },
+  },
+  diagCount: {
+    label: "Design-check diagnostics of one severity in a scenario",
+    formula: "count of checkSystem(scenario).diagnostics, plus each board below it, with the severity",
+    compute: (ctx, args = []) => {
+      const [scenario, severity] = args;
+      const s = ctx.scenarioChecks.find((x) => x.id === scenario);
+      return { value: s ? s.diagnostics.filter((d) => d.severity === severity).length : undefined, inputs: [`sys:scenarios[id=${scenario}].diagnostics`] };
+    },
+  },
+  "mech.hardware_count": {
+    label: "Fasteners and spacers placed by the assembly",
+    formula: "assemble().hardware.length",
+    compute: (ctx) => ({ value: ctx.scene.assembly.hardware.length, inputs: ["sys:assembly.hardware"] }),
+  },
+};