@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/cli/commands/report/renderer.ts

@@ -1,13 +1,19 @@
 import { reportDataToDocument } from "./adapter";
 import { validateReportDocument } from "./contract";
 import { highlightInline, highlightStyleBlock } from "./highlight";
+import { escapeHTML, renderMarkdownSubset } from "./markdown";
+import { DARK_PALETTE, LIGHT_PALETTE, paletteCss, type ReportPalette } from "./palette";
 import type {
   ReportData,
   ReportDiagramSection,
   ReportDiffSection,
   ReportDocument,
   ReportKeyValue,
+  ReportMetric,
   ReportSection,
+  ReportStatus,
+  ReportStatusTone,
+  ReportTextSection,
   ReportValue,
 } from "./types";
 
@@ -24,11 +30,20 @@ const MERMAID_RUNTIME_ID = "mermaid-runtime";
 
 const CODE_BLOCK_SELECTOR = "pre.report-code";
 
+/** A report with more sections than this carries an index linking to each one. */
+const INDEX_THRESHOLD = 4;
+
 const carriesMermaid = (sections: ReportSection[]): boolean =>
   sections.some((section) => section.type === "diagram" && section.mermaid !== undefined);
 
-const carriesVisual = (sections: ReportSection[]): boolean =>
-  sections.some((section) => section.type === "diagram" || section.type === "diff");
+/** Diagrams, diffs, and Markdown text can all carry highlighted code. */
+const carriesCode = (sections: ReportSection[]): boolean =>
+  sections.some(
+    (section) =>
+      section.type === "diagram" ||
+      section.type === "diff" ||
+      (section.type === "text" && section.format === "markdown"),
+  );
 
 type RenderInput = ReportDocument | ReportData;
 
@@ -45,6 +60,70 @@ function valueToString(value: ReportValue): string {
   return String(value);
 }
 
+const TONE_WORDS: Record<Exclude<ReportStatusTone, "neutral">, readonly string[]> = {
+  ok: [
+    "ok",
+    "pass",
+    "passed",
+    "passing",
+    "success",
+    "succeeded",
+    "done",
+    "complete",
+    "completed",
+    "healthy",
+    "ready",
+    "up",
+    "yes",
+  ],
+  warn: [
+    "warn",
+    "warning",
+    "stale",
+    "degraded",
+    "pending",
+    "partial",
+    "skipped",
+    "outdated",
+    "deprecated",
+  ],
+  error: [
+    "error",
+    "fail",
+    "failed",
+    "failing",
+    "failure",
+    "missing",
+    "broken",
+    "down",
+    "invalid",
+    "blocked",
+    "critical",
+    "no",
+  ],
+  info: ["info", "new", "changed", "running", "in progress", "queued", "note"],
+};
+
+/** The explicit tone when present, else the tone of a well-known status word, else neutral. */
+export function inferTone(item: ReportStatus): ReportStatusTone {
+  if (item.tone !== undefined) return item.tone;
+  const word = item.status.trim().toLowerCase();
+  for (const [tone, words] of Object.entries(TONE_WORDS)) {
+    if (words.includes(word)) return tone as ReportStatusTone;
+  }
+  return "neutral";
+}
+
+/** Period, generation time, context, then metadata, as one line of parts. */
+function headerParts(data: ReportDocument): string[] {
+  return [
+    ...(data.period ? [data.period] : []),
+    `Generated ${data.generatedAt}`,
+    ...(data.context ? [data.context] : []),
+    ...data.metadata.map((item) => `${item.label}: ${valueToString(item.value)}`),
+  ];
+}
+
 function renderTable(headers: string[], rows: string[][]): string {
   if (rows.length === 0) return `| ${headers.join(" | ")} |`;
 
@@ -57,17 +136,6 @@ function renderTable(headers: string[], rows: string[][]): string {
   return [renderRow(headers), divider, ...rows.map(renderRow)].join("\n");
 }
 
-function renderKeyValueTable(rows: ReportKeyValue[]): string {
-  return renderTable(
-    ["Field", "Value"],
-    rows.map((row) => [row.label, valueToString(row.value)]),
-  );
-}
-
-function printSection(title: string, body: string): string {
-  return `${title}\n\n${body}\n`;
-}
-
 function emptyTableMessage(title: string): string {
   const normalized = title.toLowerCase();
   return normalized === "spending" || normalized === "savings"
@@ -75,16 +143,34 @@ function emptyTableMessage(title: string): string {
     : "No data available.";
 }
 
+const withDetail = (value: string, detail: string | undefined): string =>
+  detail ? `${value} — ${detail}` : value;
+
+function markdownList(lines: string[]): string {
+  return lines.length ? lines.map((line) => `- ${line}`).join("\n") : "No data available.";
+}
+
+function markdownKeyValues(items: ReportKeyValue[]): string {
+  return markdownList(items.map((item) => `**${item.label}:** ${valueToString(item.value)}`));
+}
+
+function markdownMetrics(items: ReportMetric[]): string {
+  return markdownList(
+    items.map((item) => `**${item.label}:** ${withDetail(valueToString(item.value), item.detail)}`),
+  );
+}
+
+function withCaption(body: string, caption: string | undefined): string {
+  return caption ? `${body}\n\n${caption}` : body;
+}
+
 function sectionMarkdown(section: ReportSection): string {
   switch (section.type) {
     case "metadata":
     case "key-value":
-      return renderKeyValueTable(section.items);
+      return markdownKeyValues(section.items);
     case "metrics":
-      return renderTable(
-        ["Metric", "Value"],
-        section.items.map((item) => [item.label, valueToString(item.value)]),
-      );
+      return markdownMetrics(section.items);
     case "table":
       return section.rows.length
         ? renderTable(
@@ -93,23 +179,24 @@ function sectionMarkdown(section: ReportSection): string {
           )
         : emptyTableMessage(section.title);
     case "statuses":
-      return section.items.length
-        ? renderTable(
-            ["Status", "Value"],
-            section.items.map((item) => [
-              item.label,
-              item.detail ? `${item.status}: ${item.detail}` : item.status,
-            ]),
-          )
-        : "No data available.";
+      return markdownList(
+        section.items.map(
+          (item) =>
+            `[${inferTone(item)}] **${item.label}:** ${withDetail(item.status, item.detail)}`,
+        ),
+      );
     case "text":
       return section.content;
     case "diagram":
-      return section.mermaid === undefined
-        ? fence("", section.text)
-        : fence("mermaid", section.mermaid);
+      return withCaption(
+        section.mermaid === undefined ? fence("", section.text) : fence("mermaid", section.mermaid),
+        section.caption,
+      );
     case "diff":
-      return section.patch.trim() ? fence("diff", section.patch) : "No data available.";
+      return withCaption(
+        section.patch.trim() ? fence("diff", section.patch) : "No data available.",
+        section.caption,
+      );
   }
 }
 
@@ -119,25 +206,12 @@ function fence(language: string, content: string): string {
 
 export function renderMarkdown(input: RenderInput): string {
   const data = normalize(input);
-  const sections: string[] = [`# ${data.title}\n`];
-  const metadata = [...data.metadata];
-  if (data.period) metadata.unshift({ label: "Period", value: data.period });
-  if (data.context) metadata.push({ label: "Context", value: data.context });
-  sections.push(renderKeyValueTable(metadata));
-  sections.push(
-    "\n" +
-      printSection(
-        "## Summary",
-        renderTable(
-          ["Metric", "Value"],
-          data.summary.map((item) => [item.label, valueToString(item.value)]),
-        ),
-      ),
-  );
+  const parts: string[] = [`# ${data.title}`, headerParts(data).join(" · ")];
+  if (data.summary.length) parts.push(`## Summary\n\n${markdownMetrics(data.summary)}`);
   for (const section of data.sections) {
-    sections.push(printSection(`## ${section.title}`, sectionMarkdown(section)));
+    parts.push(`## ${section.title}\n\n${sectionMarkdown(section)}`);
   }
-  return sections.join("\n");
+  return `${parts.join("\n\n")}\n`;
 }
 
 export function renderJSON(input: RenderInput): string {
@@ -145,44 +219,86 @@ export function renderJSON(input: RenderInput): string {
   return JSON.stringify(normalize(input), null, 2);
 }
 
-function escapeHTML(value: string): string {
-  return value.replace(/[&<>"']/g, (character) => {
-    switch (character) {
-      case "&":
-        return "&amp;";
-      case "<":
-        return "&lt;";
-      case ">":
-        return "&gt;";
-      case '"':
-        return "&quot;";
-      default:
-        return "&#39;";
-    }
-  });
+function emptyHTML(message: string): string {
+  return `<p class="empty">${escapeHTML(message)}</p>`;
 }
 
-function renderHTMLTable(headers: string[], rows: string[][]): string {
-  const headerHTML = headers.map((header) => `<th scope="col">${escapeHTML(header)}</th>`).join("");
-  const rowsHTML = rows.length
-    ? rows
-        .map((row) => `<tr>${row.map((value) => `<td>${escapeHTML(value)}</td>`).join("")}</tr>`)
-        .join("")
-    : "";
-  return `<div class="table-wrap"><table><thead><tr>${headerHTML}</tr></thead><tbody>${rowsHTML}</tbody></table></div>`;
+/** Every non-empty cell is a number, or a numeric-looking string such as `$12.50` or `1.2M`. */
+const NUMERIC_TEXT = /^[-+]?[$€£]?\d[\d,.]*\s?[KMBT%]?(?:\/[a-z]+)?$/i;
+const PLACEHOLDER_TEXT = new Set(["", "N/A", "n/a", "-", "—"]);
+
+function isNumericColumn(rows: ReportValue[][], column: number): boolean {
+  const cells = rows
+    .map((row) => row[column])
+    .filter(
+      (cell) => cell !== null && !(typeof cell === "string" && PLACEHOLDER_TEXT.has(cell.trim())),
+    );
+  if (cells.length === 0) return false;
+  return (
+    cells.every((cell) => typeof cell === "number") ||
+    cells.every((cell) => typeof cell === "string" && NUMERIC_TEXT.test(cell.trim()))
+  );
 }
 
-function emptyHTML(message: string): string {
-  return `<p class="empty">${escapeHTML(message)}</p>`;
+function renderHTMLTable(columns: string[], rows: ReportValue[][]): string {
+  const numeric = columns.map((_, index) => isNumericColumn(rows, index));
+  const numClass = (index: number): string => (numeric[index] ? ' class="num"' : "");
+  const headerHTML = columns
+    .map((column, index) => `<th scope="col"${numClass(index)}>${escapeHTML(column)}</th>`)
+    .join("");
+  const rowsHTML = rows
+    .map(
+      (row) =>
+        `<tr>${row.map((value, index) => `<td${numClass(index)}>${escapeHTML(valueToString(value))}</td>`).join("")}</tr>`,
+    )
+    .join("");
+  return `<div class="table-wrap"><table><thead><tr>${headerHTML}</tr></thead><tbody>${rowsHTML}</tbody></table></div>`;
 }
 
 function renderHTMLKeyValues(items: ReportKeyValue[]): string {
-  return items.length
-    ? renderHTMLTable(
-        ["Field", "Value"],
-        items.map((item) => [item.label, valueToString(item.value)]),
-      )
-    : emptyHTML("No metadata available.");
+  if (items.length === 0) return emptyHTML("No metadata available.");
+  const rows = items
+    .map(
+      (item) =>
+        `<div><dt>${escapeHTML(item.label)}</dt><dd>${escapeHTML(valueToString(item.value))}</dd></div>`,
+    )
+    .join("");
+  return `<dl class="report-kv">${rows}</dl>`;
+}
+
+function renderHTMLTiles(items: ReportMetric[]): string {
+  const tiles = items
+    .map((item) => {
+      const detail = item.detail ? `<p class="tile-detail">${escapeHTML(item.detail)}</p>` : "";
+      return `<div class="tile"><p class="tile-value">${escapeHTML(valueToString(item.value))}</p><p class="tile-label">${escapeHTML(item.label)}</p>${detail}</div>`;
+    })
+    .join("");
+  return `<div class="report-tiles">${tiles}</div>`;
+}
+
+function renderHTMLStatuses(items: ReportStatus[]): string {
+  const rows = items
+    .map((item) => {
+      const detail = item.detail
+        ? `<span class="status-detail">${escapeHTML(item.detail)}</span>`
+        : "";
+      return `<li class="status" data-tone="${inferTone(item)}"><span class="tone-marker" aria-hidden="true"></span><span class="status-label">${escapeHTML(item.label)}</span><span class="status-value">${escapeHTML(item.status)}</span>${detail}</li>`;
+    })
+    .join("");
+  return `<ul class="report-statuses">${rows}</ul>`;
+}
+
+function renderHTMLText(section: ReportTextSection): string {
+  if (!section.content) return emptyHTML("No text available.");
+  return section.format === "markdown"
+    ? `<div class="report-text report-markdown">${renderMarkdownSubset(section.content)}</div>`
+    : `<p class="report-text">${escapeHTML(section.content).replaceAll("\n", "<br>")}</p>`;
+}
+
+function renderHTMLCaption(caption: string | undefined): string {
+  return caption
+    ? `<div class="report-caption report-markdown">${renderMarkdownSubset(caption)}</div>`
+    : "";
 }
 
 type DiffLineKind = "add" | "del" | "context" | "hunk";
@@ -302,11 +418,27 @@ function renderHTMLDiff(section: ReportDiffSection): string {
     .join("");
 }
 
+/** A `classDef`, `style`, or `linkStyle` line that paints with a fixed colour. */
+const FIXED_COLOUR_LINE = /^\s*(?:classDef|style|linkStyle)\s.*\b(?:fill|stroke|color)\s*:/;
+
+/**
+ * The dark copy drops fixed colours: a light fill authored for a white page would
+ * otherwise sit under the dark scheme's light text and hide every label.
+ */
+function darkMermaidSource(source: string): string {
+  return source
+    .split("\n")
+    .filter((line) => !FIXED_COLOUR_LINE.test(line))
+    .join("\n");
+}
+
 function renderHTMLDiagram(section: ReportDiagramSection): string {
   if (section.mermaid === undefined) {
     return `<pre class="report-code report-diagram-text">${escapeHTML(section.text)}</pre>`;
   }
-  return `<div class="report-diagram"><pre class="mermaid">${escapeHTML(section.mermaid)}</pre></div>`;
+  const dark = darkMermaidSource(section.mermaid);
+  const darkAttribute = dark === section.mermaid ? "" : ` data-dark-source="${escapeHTML(dark)}"`;
+  return `<div class="report-diagram"><pre class="mermaid"${darkAttribute}>${escapeHTML(section.mermaid)}</pre></div>`;
 }
 
 function renderHTMLSectionBody(section: ReportSection): string {
@@ -316,36 +448,22 @@ function renderHTMLSectionBody(section: ReportSection): string {
       return renderHTMLKeyValues(section.items);
     case "metrics":
       return section.items.length
-        ? renderHTMLTable(
-            ["Metric", "Value"],
-            section.items.map((item) => [item.label, valueToString(item.value)]),
-          )
+        ? renderHTMLTiles(section.items)
         : emptyHTML("No metrics available.");
     case "table":
       return section.rows.length
-        ? renderHTMLTable(
-            section.columns,
-            section.rows.map((row) => row.map(valueToString)),
-          )
+        ? renderHTMLTable(section.columns, section.rows)
         : emptyHTML(emptyTableMessage(section.title));
     case "statuses":
       return section.items.length
-        ? renderHTMLTable(
-            ["Status", "Value"],
-            section.items.map((item) => [
-              item.label,
-              item.detail ? `${item.status}: ${item.detail}` : item.status,
-            ]),
-          )
+        ? renderHTMLStatuses(section.items)
         : emptyHTML("No status data available.");
     case "text":
-      return section.content
-        ? `<p class="report-text">${escapeHTML(section.content).replaceAll("\n", "<br>")}</p>`
-        : emptyHTML("No text available.");
+      return renderHTMLText(section);
     case "diagram":
-      return renderHTMLDiagram(section);
+      return renderHTMLDiagram(section) + renderHTMLCaption(section.caption);
     case "diff":
-      return renderHTMLDiff(section);
+      return renderHTMLDiff(section) + renderHTMLCaption(section.caption);
   }
 }
 
@@ -353,28 +471,136 @@ function renderHTMLSection(section: ReportSection): string {
   return `<section id="${escapeHTML(section.id)}"><h2>${escapeHTML(section.title)}</h2>${renderHTMLSectionBody(section)}</section>`;
 }
 
+function renderHTMLIndex(sections: ReportSection[]): string {
+  if (sections.length <= INDEX_THRESHOLD) return "";
+  const links = sections
+    .map(
+      (section) => `<li><a href="#${escapeHTML(section.id)}">${escapeHTML(section.title)}</a></li>`,
+    )
+    .join("");
+  return `\n    <nav class="report-index interactive-only" aria-label="Sections"><ol>${links}</ol></nav>`;
+}
+
+/** The kit's symbol: the Ink bar follows the text colour, the three blocks the accent. */
+const MATE_SYMBOL = `<svg class="report-symbol" viewBox="0 0 256 256" width="28" height="28" aria-hidden="true" focusable="false"><path fill="currentColor" d="M36 16H144V240H36A20 20 0 0 1 16 220V36A20 20 0 0 1 36 16Z"/><path class="report-symbol-accent" d="M160 16H220A20 20 0 0 1 240 36V80H160Z M160 96H240V160H160Z M160 176H240V220A20 20 0 0 1 220 240H160Z"/></svg>`;
+
+const PRINT_ICON = `<svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="M6 9V3h12v6"/><path d="M6 18H4a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-2"/><path d="M6 14h12v7H6z"/></svg>`;
+
+const PRINT_LABEL = "Print / Save as PDF";
+
+/** Mermaid theme variables for one report palette; notes stay neutral, not mermaid yellow. */
+function mermaidThemeVariables(palette: ReportPalette, darkMode: boolean): Record<string, unknown> {
+  return {
+    darkMode,
+    background: palette.bg,
+    primaryColor: palette.surface,
+    primaryTextColor: palette.ink,
+    primaryBorderColor: palette.accent,
+    secondaryColor: palette.hunkBg,
+    tertiaryColor: palette.bg,
+    lineColor: palette.muted,
+    textColor: palette.ink,
+    noteBkgColor: palette.hunkBg,
+    noteBorderColor: palette.rule,
+    noteTextColor: palette.ink,
+    fontFamily: "system-ui, -apple-system, Segoe UI, sans-serif",
+    fontSize: "14px",
+  };
+}
+
+const NODE_SHAPES = ["rect", "polygon", "circle", "ellipse", "path"];
+
+/** Node classes an author can apply with `class` or `:::` instead of fixing a colour. */
+function mermaidClassCss(palette: ReportPalette): string {
+  const classes: [name: string, fill: string, stroke: string][] = [
+    ["added", palette.addBg, palette.ok],
+    ["changed", palette.hunkBg, palette.info],
+    ["removed", palette.delBg, palette.error],
+  ];
+  return classes
+    .map(([name, fill, stroke]) => {
+      const selector = NODE_SHAPES.map((shape) => `.node.${name} ${shape}`).join(", ");
+      return `${selector} { fill: ${fill} !important; stroke: ${stroke} !important; }`;
+    })
+    .join(" ");
+}
+
+/**
+ * Draws every diagram twice, in the light and the dark palette, one diagram at a time.
+ * CSS then shows the copy for the active scheme and always the light copy in print, so
+ * neither a scheme switch nor printing has to wait for a redraw. A diagram that fails
+ * to render keeps showing its escaped source.
+ */
+const MERMAID_INIT = `(() => {
+    const mermaid = window.mermaid;
+    if (!mermaid) return;
+    const variants = ${JSON.stringify([
+      {
+        scheme: "light",
+        themeVariables: mermaidThemeVariables(LIGHT_PALETTE, false),
+        themeCSS: mermaidClassCss(LIGHT_PALETTE),
+      },
+      {
+        scheme: "dark",
+        themeVariables: mermaidThemeVariables(DARK_PALETTE, true),
+        themeCSS: mermaidClassCss(DARK_PALETTE),
+      },
+    ])};
+    const draw = async (sources, id) => {
+      const drawn = [];
+      for (const { scheme, themeVariables, themeCSS } of variants) {
+        mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "base", themeVariables, themeCSS });
+        const { svg } = await mermaid.render(id + "-" + scheme, sources[scheme]);
+        const figure = document.createElement("div");
+        figure.className = "diagram-" + scheme;
+        figure.innerHTML = svg;
+        drawn.push(figure);
+      }
+      return drawn;
+    };
+    (async () => {
+      const nodes = [...document.querySelectorAll(".report-diagram pre.mermaid")];
+      for (const [index, node] of nodes.entries()) {
+        const id = "report-diagram-" + index;
+        try {
+          const sources = { light: node.textContent, dark: node.dataset.darkSource ?? node.textContent };
+          node.after(...(await draw(sources, id)));
+          node.hidden = true;
+        } catch {
+          for (const scheme of ["light", "dark"]) document.getElementById("d" + id + "-" + scheme)?.remove();
+        }
+      }
+    })();
+  })();`;
+
+/**
+ * Runs before the styles apply: `?scheme=light` or `?scheme=dark` pins the colour scheme
+ * through `data-scheme` on `<html>`; any other value leaves the browser preference in charge.
+ */
+const SCHEME_SCRIPT = `(function () {
+    var scheme = new URLSearchParams(location.search).get("scheme");
+    if (scheme === "light" || scheme === "dark") document.documentElement.dataset.scheme = scheme;
+  })();`;
+
 export function renderHTML(input: RenderInput): string {
   const data = normalize(input);
   const legacy = isReportDocument(input) ? undefined : input;
-  const metadata = [...data.metadata];
-  if (data.period) metadata.unshift({ label: "Period", value: data.period });
-  if (data.context) metadata.push({ label: "Context", value: data.context });
-  const summary: ReportMetricsSection = {
-    id: "summary",
-    title: "Summary",
-    type: "metrics",
-    items: data.summary,
-  };
 
   const repositoryAttributes = legacy
     ? ` data-working-repository="${escapeHTML(legacy.workingRepoPath)}" data-companion-repository="${escapeHTML(legacy.companionRepoPath)}"`
     : "";
 
-  const visualStyles = carriesVisual(data.sections)
+  const meta = headerParts(data)
+    .map((part) => `<span>${escapeHTML(part)}</span>`)
+    .join("");
+  const summary = data.summary.length
+    ? `\n    <section id="summary" class="report-summary" aria-label="Summary">${renderHTMLTiles(data.summary)}</section>`
+    : "";
+  const codeStyles = carriesCode(data.sections)
     ? `\n  <style>${highlightStyleBlock(CODE_BLOCK_SELECTOR)}${VISUAL_SECTION_CSS}</style>`
     : "";
   const diagramRuntime = carriesMermaid(data.sections)
-    ? `\n  <script id="${MERMAID_RUNTIME_ID}" src="${MERMAID_RUNTIME_URL}" integrity="${MERMAID_RUNTIME_INTEGRITY}" crossorigin="anonymous"></script>\n  <script>window.mermaid?.initialize({ startOnLoad: true, securityLevel: "strict" });</script>`
+    ? `\n  <script id="${MERMAID_RUNTIME_ID}" src="${MERMAID_RUNTIME_URL}" integrity="${MERMAID_RUNTIME_INTEGRITY}" crossorigin="anonymous"></script>\n  <script>${MERMAID_INIT}</script>`
     : "";
 
   return `<!doctype html>
@@ -382,67 +608,144 @@ export function renderHTML(input: RenderInput): string {
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <script id="report-scheme">${SCHEME_SCRIPT}</script>
   <title>${escapeHTML(data.title)}</title>
   <style>
-    :root { color-scheme: light; font-family: system-ui, sans-serif; background: #f4f6f8; color: #18212b; }
-    body { margin: 0; }
-    .report { max-width: 1120px; margin: 0 auto; padding: 32px 20px 56px; }
-    header, section { background: #fff; border: 1px solid #dce2e8; border-radius: 14px; margin-bottom: 20px; padding: 24px; box-shadow: 0 8px 24px rgb(24 33 43 / 6%); }
-    h1, h2 { margin-top: 0; }
-    h1 { margin-bottom: 8px; }
-    h2 { font-size: 1.15rem; }
-    .eyebrow { color: #536273; font-size: .8rem; font-weight: 700; letter-spacing: .08em; text-transform: uppercase; }
-    .print-control { background: #18212b; border: 0; border-radius: 8px; color: #fff; cursor: pointer; padding: 10px 14px; }
-    .table-wrap { overflow-x: auto; }
-    table { border-collapse: collapse; min-width: 100%; }
-    th, td { border-bottom: 1px solid #e8edf1; padding: 10px 12px; text-align: left; vertical-align: top; }
-    th { color: #536273; font-size: .8rem; text-transform: uppercase; }
-    .empty { color: #536273; margin: 0; }
-    @media (max-width: 640px) { .report { padding: 16px 12px 32px; } header, section { padding: 16px; } }
-    @media print {
-      :root, body { background: #fff; color: #000; }
-      .report { max-width: none; padding: 0; }
-      header, section { border: 0; border-radius: 0; box-shadow: none; margin-bottom: 16px; padding: 0; }
-      .print-control, .interactive-only { display: none !important; }
-      .table-wrap { overflow: visible; }
-      table { width: 100%; }
-      th, td { color: #000; }
-    }
-  </style>${visualStyles}
+    ${paletteCss()}
+    ${REPORT_CSS}
+  </style>${codeStyles}
 </head>
 <body>
   <main class="report" data-report-version="${data.version}"${repositoryAttributes}>
-    <header>
-      <p class="eyebrow">Mate report</p>
-      <h1>${escapeHTML(data.title)}</h1>
-      ${renderHTMLKeyValues(metadata)}
-      <button class="print-control interactive-only" type="button" onclick="window.print()">Print / Save as PDF</button>
-    </header>
-    ${renderHTMLSection(summary)}
+    <header class="report-header">
+      <div class="report-heading">
+        ${MATE_SYMBOL}
+        <h1>${escapeHTML(data.title)}</h1>
+        <button class="print-control interactive-only" type="button" aria-label="${PRINT_LABEL}" title="${PRINT_LABEL}" onclick="window.print()">${PRINT_ICON}</button>
+      </div>
+      <p class="report-meta">${meta}</p>
+    </header>${summary}${renderHTMLIndex(data.sections)}
     ${data.sections.map(renderHTMLSection).join("\n    ")}
   </main>${diagramRuntime}
 </body>
 </html>`;
 }
 
+const MONO = "ui-monospace, SFMono-Regular, Menlo, monospace";
+
+const REPORT_CSS = `
+    html { background: var(--bg); color: var(--ink); font-family: system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.5; }
+    body { margin: 0; }
+    a { color: var(--accent); }
+    .report { max-width: 1040px; margin: 0 auto; padding: 40px 24px 64px; }
+    .report-heading { align-items: center; display: flex; gap: 12px; }
+    .report-symbol { color: var(--ink); flex: none; }
+    .report-symbol-accent { fill: var(--accent); }
+    h1 { flex: 1; font-size: 1.6rem; font-weight: 650; letter-spacing: -.01em; line-height: 1.2; margin: 0; }
+    .report-meta { color: var(--muted); font-size: .85rem; margin: 8px 0 0 40px; }
+    .report-meta span + span::before { content: "·"; padding: 0 .5em; }
+    .print-control { align-items: center; background: transparent; border: 0; border-radius: 8px; color: var(--muted); cursor: pointer; display: inline-flex; flex: none; height: 36px; justify-content: center; padding: 0; width: 36px; }
+    .print-control:hover, .print-control:focus-visible { color: var(--accent); }
+    .print-control:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    section { margin-top: 40px; }
+    h2 { border-bottom: 1px solid var(--rule); color: var(--muted); font-size: .75rem; font-variant: small-caps; font-weight: 650; letter-spacing: .08em; margin: 0 0 16px; padding-bottom: 8px; text-transform: uppercase; }
+    .report-tiles { display: grid; gap: 24px; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); }
+    .tile { border-top: 1px solid var(--rule); padding-top: 12px; }
+    .tile p { margin: 0; }
+    .tile-value { font-size: 1.6rem; font-variant-numeric: tabular-nums; font-weight: 650; line-height: 1.2; }
+    .tile-label { color: var(--muted); font-size: .85rem; margin-top: 4px !important; }
+    .tile-detail { color: var(--muted); font-size: .8rem; }
+    .report-index ol { display: flex; flex-wrap: wrap; gap: 4px 20px; list-style: none; margin: 32px 0 0; padding: 0; }
+    .report-index a { font-size: .85rem; text-decoration: none; }
+    .report-index a:hover { text-decoration: underline; }
+    .report-kv { display: grid; gap: 8px 24px; grid-template-columns: minmax(140px, max-content) 1fr; margin: 0; }
+    .report-kv div { display: contents; }
+    .report-kv dt { color: var(--muted); }
+    .report-kv dd { margin: 0; overflow-wrap: anywhere; }
+    .report-statuses { list-style: none; margin: 0; padding: 0; }
+    .status { align-items: baseline; border-bottom: 1px solid var(--rule); display: flex; flex-wrap: wrap; gap: 4px 12px; padding: 8px 0; }
+    .status:last-child { border-bottom: 0; }
+    .status-label { font-weight: 600; }
+    .status-value { color: var(--tone); margin-left: auto; text-align: right; }
+    .status-detail { color: var(--muted); flex-basis: 100%; font-size: .85rem; padding-left: 22px; }
+    .tone-marker { align-self: center; background: var(--tone); display: inline-block; flex: none; height: 10px; width: 10px; }
+    .status[data-tone="ok"] { --tone: var(--ok); }
+    .status[data-tone="ok"] .tone-marker { border-radius: 50%; }
+    .status[data-tone="neutral"] { --tone: var(--neutral); }
+    .status[data-tone="neutral"] .tone-marker { background: transparent; border: 2px solid var(--tone); border-radius: 50%; box-sizing: border-box; }
+    .status[data-tone="warn"] { --tone: var(--warn); }
+    .status[data-tone="warn"] .tone-marker { clip-path: polygon(50% 0, 100% 100%, 0 100%); }
+    .status[data-tone="error"] { --tone: var(--error); }
+    .status[data-tone="info"] { --tone: var(--info); }
+    .status[data-tone="info"] .tone-marker { transform: rotate(45deg) scale(.85); }
+    .table-wrap { overflow-x: auto; }
+    table { border-collapse: collapse; min-width: 100%; }
+    th, td { border-bottom: 1px solid var(--rule); padding: 8px 12px; text-align: left; vertical-align: top; }
+    th:first-child, td:first-child { padding-left: 0; }
+    th:last-child, td:last-child { padding-right: 0; }
+    th { color: var(--muted); font-size: .75rem; font-weight: 650; letter-spacing: .04em; text-transform: uppercase; }
+    tbody tr:last-child td { border-bottom: 0; }
+    .num { font-variant-numeric: tabular-nums; text-align: right; }
+    .report-text { margin: 0; max-width: 72ch; }
+    .report-markdown > :first-child { margin-top: 0; }
+    .report-markdown > :last-child { margin-bottom: 0; }
+    .report-markdown h3, .report-markdown h4, .report-markdown h5, .report-markdown h6 { font-size: 1rem; margin: 20px 0 8px; }
+    .report-markdown code { background: var(--surface); border-radius: 4px; font-family: ${MONO}; font-size: .88em; padding: .1em .3em; }
+    .report-markdown pre code { background: none; padding: 0; }
+    .report-caption { color: var(--muted); font-size: .9rem; margin-top: 12px; max-width: 72ch; }
+    .empty { color: var(--muted); margin: 0; }
+    @media (max-width: 640px) {
+      .report { padding: 24px 16px 40px; }
+      .report-meta { margin-left: 0; }
+      .report-kv { grid-template-columns: 1fr; gap: 2px; }
+      .report-kv dd { margin-bottom: 8px; }
+    }
+    @media print {
+      .report { max-width: none; padding: 0; }
+      section { margin-top: 24px; }
+      .report-header, h2, .diff-file { break-after: avoid-page; }
+      .report-markdown :is(h3, h4, h5, h6) { break-after: avoid-page; }
+      .report-markdown :is(ul, ol) { break-inside: avoid-page; }
+      .report-caption { break-before: avoid-page; }
+      tr, .tile, .status, .report-kv dt, .report-kv dd, .report-markdown li, .report-diagram { break-inside: avoid-page; }
+      .report-kv dt { break-after: avoid-page; }
+      thead { display: table-header-group; }
+      p, li { orphans: 3; widows: 3; }
+      .print-control, .interactive-only, .report-index { display: none !important; }
+      .table-wrap { overflow: visible; }
+      table { width: 100%; }
+      .tone-marker { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+    }`;
+
 const VISUAL_SECTION_CSS = `
-    pre.report-code { background: #f7f9fb; border: 1px solid #e8edf1; border-radius: 10px; margin: 0; overflow-x: auto; padding: 14px 16px; }
+    pre.report-code { background: var(--surface); border: 1px solid var(--rule); border-radius: 8px; font-family: ${MONO}; font-size: .82rem; margin: 0; overflow-x: auto; padding: 14px 16px; }
+    .report-markdown pre.report-code { margin: 12px 0; }
     .report-diagram { max-width: 100%; overflow-x: auto; }
     .report-diagram svg { height: auto; max-width: 100%; }
-    .report-diagram .mermaid { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .82rem; margin: 0; white-space: pre; }
+    .report-diagram svg * { filter: none !important; }
+    .report-diagram .diagram-dark { display: none; }
+    @media screen and (prefers-color-scheme: dark) {
+      :root:not([data-scheme="light"]) .report-diagram .diagram-light { display: none; }
+      :root:not([data-scheme="light"]) .report-diagram .diagram-dark { display: block; }
+    }
+    :root[data-scheme="dark"] .report-diagram .diagram-light { display: none; }
+    :root[data-scheme="dark"] .report-diagram .diagram-dark { display: block; }
+    .report-diagram .mermaid { font-family: ${MONO}; font-size: .82rem; margin: 0; white-space: pre; }
     .diff-file-group + .diff-file-group { margin-top: 18px; }
-    .diff-file { color: #536273; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .8rem; font-weight: 700; margin: 0 0 8px; }
-    .report-diff { border: 1px solid #e8edf1; border-radius: 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .82rem; overflow-x: auto; padding: 6px 0; }
+    .diff-file { color: var(--muted); font-family: ${MONO}; font-size: .8rem; font-weight: 650; margin: 0 0 8px; }
+    .report-diff { border: 1px solid var(--rule); border-radius: 8px; font-family: ${MONO}; font-size: .82rem; overflow-x: auto; padding: 6px 0; }
     .diff-line { -webkit-print-color-adjust: exact; min-width: max-content; padding: 0 12px; print-color-adjust: exact; white-space: pre; }
     .diff-glyph { display: inline-block; user-select: none; width: 1ch; }
-    .diff-add { background: #e6ffec; }
-    .diff-del { background: #ffebe9; }
-    .diff-hunk { background: #eef2f6; color: #536273; }
+    .diff-add { background: var(--add-bg); }
+    .diff-del { background: var(--del-bg); }
+    .diff-hunk { background: var(--hunk-bg); color: var(--muted); }
     @media print {
       pre.report-code, .report-diff { border-color: #999; }
+      .report-diagram { background: #fff; }
+      .report-diagram svg { max-height: 90vh; }
+      .report-diagram .diagram-light { display: block !important; }
+      .report-diagram .diagram-dark { display: none !important; }
       .report-diagram, .report-diff, pre.report-code { overflow: visible; }
-      .diff-line { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
       .diff-hunk { color: #333; }
     }`;
-
-type ReportMetricsSection = Extract<ReportSection, { type: "metrics" }>;