@uniqbit/mate-core 0.15.5 → 0.16.0-canary.0

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

@@ -4,6 +4,7 @@ import type { SavingsEntry, SpendingEntry, ToolStatus } from "./types";
 
 export interface CollectorDeps {
   spawn?: typeof spawnSync;
+  now?: () => Date;
 }
 
 function spawnCmd(cmd: string, args: string[], opts: { cwd: string }, deps: CollectorDeps) {
@@ -21,14 +22,28 @@ function parseJson<T>(output: string): T | null {
   }
 }
 
+function reportSince(days: number, deps: CollectorDeps): string {
+  const since = new Date(deps.now?.() ?? new Date());
+  since.setDate(since.getDate() - days);
+  return since.toISOString().slice(0, 10);
+}
+
+function utcDateFromEpochSeconds(value: unknown): string | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) return null;
+  const date = new Date(value * 1000);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10);
+}
+
+function finiteNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
 // ccusage JSON: { daily: [{ period, totalCost, totalTokens, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, modelBreakdowns: [{ modelName, cost, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens }] }], totals: { totalCost, totalTokens, ... } }
 export async function collectCcusageSpending(
   days: number,
   deps: CollectorDeps = {},
 ): Promise<{ entries: SpendingEntry[]; status: ToolStatus; friendlyError?: string }> {
-  const since = new Date();
-  since.setDate(since.getDate() - days);
-  const sinceStr = since.toISOString().slice(0, 10);
+  const sinceStr = reportSince(days, deps);
 
   // Try bunx first, then npx
   const runners = [
@@ -96,7 +111,7 @@ export async function collectCcusageSpending(
   };
 }
 
-// tokensave gain JSON: { saved_tokens, calls, usd }
+/** tokensave gain --history JSON: [{ day, saved_tokens, calls, usd }] */
 export async function collectTokenSaveSavings(
   repoPath: string,
   days: number,
@@ -104,7 +119,7 @@ export async function collectTokenSaveSavings(
 ): Promise<{ entry: SavingsEntry | null; status: ToolStatus }> {
   const result = spawnCmd(
     "tokensave",
-    ["gain", "--json", "--range", `${days}d`],
+    ["gain", "--history", "--json", "--range", "all"],
     { cwd: repoPath },
     deps,
   );
@@ -116,37 +131,58 @@ export async function collectTokenSaveSavings(
     };
   }
 
-  const data = parseJson<{ saved_tokens?: number; calls?: number; usd?: number }>(result.stdout);
-  if (!data) {
+  const data = parseJson<
+    Array<{ day?: number; saved_tokens?: number; calls?: number; usd?: number } | null>
+  >(result.stdout);
+  if (!data || !Array.isArray(data) || data.length === 0) {
     return {
       entry: null,
       status: { name: "tokensave", enabled: false, status: "no data" },
     };
   }
 
+  const sinceStr = reportSince(days, deps);
+  let matchingDays = 0;
+  let tokensSaved = 0;
+  let calls = 0;
+  let costSaved = 0;
+  for (const day of data) {
+    const date = utcDateFromEpochSeconds(day?.day);
+    if (!date || date < sinceStr) continue;
+    matchingDays++;
+    tokensSaved += finiteNumber(day?.saved_tokens);
+    calls += finiteNumber(day?.calls);
+    costSaved += finiteNumber(day?.usd);
+  }
+
+  if (matchingDays === 0) {
+    return {
+      entry: null,
+      status: { name: "tokensave", enabled: false, status: "no window data" },
+    };
+  }
+
   return {
     entry: {
       tool: "tokensave",
-      tokensSaved: data.saved_tokens ?? 0,
-      calls: data.calls ?? 0,
-      costSaved: data.usd ?? 0,
-      efficiency:
-        (data.calls ?? 0) > 0
-          ? `${formatEfficiency(data.saved_tokens ?? 0, data.calls ?? 0)}`
-          : "N/A",
+      tokensSaved,
+      calls,
+      costSaved,
+      efficiency: calls > 0 ? formatEfficiency(tokensSaved, calls) : "N/A",
     },
     status: { name: "tokensave", enabled: true, status: "ok" },
   };
 }
 
-// rtk gain JSON: { summary: { total_saved, total_commands, avg_savings_pct } }
+/** rtk gain --daily JSON: { daily: [{ date, saved_tokens, commands }] } */
 export async function collectRTKSavings(
   repoPath: string,
+  days: number,
   deps: CollectorDeps = {},
 ): Promise<{ entry: SavingsEntry | null; status: ToolStatus }> {
   const result = spawnCmd(
     "rtk",
-    ["gain", "--project", "--format", "json"],
+    ["gain", "--project", "--daily", "--format", "json"],
     { cwd: repoPath },
     deps,
   );
@@ -159,81 +195,42 @@ export async function collectRTKSavings(
   }
 
   const data = parseJson<{
-    summary?: { total_saved?: number; total_commands?: number; avg_savings_pct?: number };
+    daily?: Array<{ date?: string; saved_tokens?: number; commands?: number } | null>;
   }>(result.stdout);
-  if (!data || !data.summary) {
+  if (!data || !Array.isArray(data.daily) || data.daily.length === 0) {
     return {
       entry: null,
       status: { name: "rtk", enabled: false, status: "no data" },
     };
   }
 
-  const s = data.summary;
-  return {
-    entry: {
-      tool: "rtk",
-      tokensSaved: s.total_saved ?? 0,
-      calls: s.total_commands ?? 0,
-      costSaved: 0,
-      efficiency:
-        (s.total_commands ?? 0) > 0
-          ? `${formatEfficiency(s.total_saved ?? 0, s.total_commands ?? 0)}`
-          : "N/A",
-    },
-    status: { name: "rtk", enabled: true, status: "ok" },
-  };
-}
-
-// headroom savings JSON: { windows: { last_7_days: { tokens_saved, cost_usd, calls } } }
-export async function collectHeadroomSavings(
-  days: number,
-  deps: CollectorDeps = {},
-): Promise<{ entry: SavingsEntry | null; status: ToolStatus }> {
-  const result = spawnCmd(
-    "headroom",
-    ["savings", "--json", "--days", String(days)],
-    { cwd: process.cwd() },
-    deps,
-  );
-
-  if (result.error || result.status !== 0) {
-    return {
-      entry: null,
-      status: { name: "headroom", enabled: false, status: "not enabled" },
-    };
-  }
-
-  const data = parseJson<{
-    windows?: Record<string, { tokens_saved?: number; cost_usd?: number; calls?: number }>;
-  }>(result.stdout);
-  if (!data || !data.windows) {
-    return {
-      entry: null,
-      status: { name: "headroom", enabled: false, status: "no data" },
-    };
+  const sinceStr = reportSince(days, deps);
+  let matchingDays = 0;
+  let tokensSaved = 0;
+  let calls = 0;
+  for (const day of data.daily) {
+    if (typeof day?.date !== "string" || day.date < sinceStr) continue;
+    matchingDays++;
+    tokensSaved += finiteNumber(day?.saved_tokens);
+    calls += finiteNumber(day?.commands);
   }
 
-  const key = `last_${days}_days`;
-  const window = data.windows[key] ?? data.windows["last_7_days"] ?? data.windows["all_time"];
-  if (!window) {
+  if (matchingDays === 0) {
     return {
       entry: null,
-      status: { name: "headroom", enabled: false, status: "no window data" },
+      status: { name: "rtk", enabled: false, status: "no window data" },
     };
   }
 
   return {
     entry: {
-      tool: "headroom",
-      tokensSaved: window.tokens_saved ?? 0,
-      calls: window.calls ?? 0,
-      costSaved: window.cost_usd ?? 0,
-      efficiency:
-        (window.calls ?? 0) > 0
-          ? `${formatEfficiency(window.tokens_saved ?? 0, window.calls ?? 0)}`
-          : "N/A",
+      tool: "rtk",
+      tokensSaved,
+      calls,
+      costSaved: 0,
+      efficiency: calls > 0 ? formatEfficiency(tokensSaved, calls) : "N/A",
     },
-    status: { name: "headroom", enabled: true, status: "ok" },
+    status: { name: "rtk", enabled: true, status: "ok" },
   };
 }
 
@@ -253,7 +250,6 @@ export function mergeResults(
   tokensaveWorking: SavingsEntry | null,
   tokensaveCompanion: SavingsEntry | null,
   rtkEntry: SavingsEntry | null,
-  headroomEntry: SavingsEntry | null,
 ): {
   spending: SpendingEntry[];
   savings: SavingsEntry[];
@@ -279,9 +275,7 @@ export function mergeResults(
     };
   }
 
-  const savings: SavingsEntry[] = [mergedTokensave, rtkEntry, headroomEntry].filter(
-    Boolean,
-  ) as SavingsEntry[];
+  const savings: SavingsEntry[] = [mergedTokensave, rtkEntry].filter(Boolean) as SavingsEntry[];
   const totalSavings = savings.reduce((sum, e) => sum + e.costSaved, 0);
 
   return {

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

@@ -1,5 +1,7 @@
 import {
   REPORT_DOCUMENT_VERSION,
+  type ReportDiagramSection,
+  type ReportDiffSection,
   type ReportDocument,
   type ReportKeyValue,
   type ReportMetric,
@@ -114,6 +116,32 @@ function validateStatuses(value: unknown, path: string, issues: ReportValidation
   return true;
 }
 
+const DIAGRAM_PAYLOADS = ["mermaid", "text"] as const;
+
+/** A diagram carries exactly one payload; an empty or non-string payload counts as absent. */
+function validateDiagram(
+  value: Record<string, unknown>,
+  path: string,
+  issues: ReportValidationIssue[],
+): void {
+  const supplied = DIAGRAM_PAYLOADS.filter((key) => value[key] !== undefined);
+  for (const key of supplied) {
+    if (typeof value[key] !== "string" || (value[key] as string).trim() === "") {
+      issues.push({ path: `${path}.${key}`, message: "must be a non-empty string" });
+    }
+  }
+  if (supplied.length === 1) return;
+
+  const name = typeof value.id === "string" && value.id.trim() !== "" ? value.id : path;
+  issues.push({
+    path,
+    message:
+      supplied.length === 0
+        ? `section "${name}" must carry exactly one of mermaid or text, but carries neither`
+        : `section "${name}" must carry exactly one of mermaid or text, but carries both`,
+  });
+}
+
 function validateSection(value: unknown, path: string, issues: ReportValidationIssue[]): void {
   if (!isRecord(value)) {
     issues.push({ path, message: "must be an object" });
@@ -182,10 +210,19 @@ function validateSection(value: unknown, path: string, issues: ReportValidationI
         issues.push({ path: `${path}.content`, message: "must be a string" });
       }
       return;
+    case "diagram":
+      validateDiagram(value, path, issues);
+      return;
+    case "diff":
+      if (typeof value.patch !== "string") {
+        issues.push({ path: `${path}.patch`, message: "must be a string" });
+      }
+      return;
     default:
       issues.push({
         path: `${path}.type`,
-        message: "must be one of metadata, metrics, key-value, table, statuses, or text",
+        message:
+          "must be one of metadata, metrics, key-value, table, statuses, text, diagram, or diff",
       });
   }
 }
@@ -248,6 +285,8 @@ export function parseReportDocument(json: string): ReportDocument {
 }
 
 export type {
+  ReportDiagramSection,
+  ReportDiffSection,
   ReportDocument,
   ReportKeyValue,
   ReportMetric,

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

@@ -0,0 +1,27 @@
+import { normalizeLanguage, renderNodesToHtml, renderTokens, tokenize } from "@tanstack/highlight";
+import { createThemeCss } from "@tanstack/highlight/theme";
+import githubLight from "@tanstack/highlight/themes/github-light";
+
+/** Sole boundary against `@tanstack/highlight`, so an upstream API break stays a single-file fix. */
+
+/** Language every unknown or unsupported candidate resolves to. */
+export const PLAIN_LANGUAGE = "plaintext";
+
+export function resolveHighlightLanguage(candidate: string | undefined): string {
+  return normalizeLanguage(candidate);
+}
+
+/**
+ * Class-annotated inline markup for one fragment, escaped and without a block wrapper.
+ * An unknown language yields plain escaped text carrying no token classes.
+ */
+export function highlightInline(code: string, language: string | undefined): string {
+  const resolved = resolveHighlightLanguage(language);
+  const { tokens } = tokenize(code, { lang: resolved });
+  return renderNodesToHtml(renderTokens(tokens));
+}
+
+/** Token colours as an inlinable stylesheet; carries no script, font, or external reference. */
+export function highlightStyleBlock(codeBlockSelector: string): string {
+  return createThemeCss({ light: githubLight, codeBlockSelector });
+}

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

@@ -4,7 +4,6 @@ import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-con
 import { ensureUnambiguousCompanion } from "../shared/companion-selection";
 import {
   collectCcusageSpending,
-  collectHeadroomSavings,
   collectRTKSavings,
   collectTokenSaveSavings,
   mergeResults,
@@ -135,12 +134,16 @@ export async function runReportCommand(
           .map((a) => a.trim())
           .filter(Boolean)
       : [];
+    const reportNow = new Date();
+    const collectorDeps: CollectorDeps = {
+      spawn: deps.spawn,
+      now: deps.now ?? (() => reportNow),
+    };
 
     const tokensaveEnabled = enabledCapabilities.includes("tokensave");
-    const headroomEnabled = enabledCapabilities.includes("headroom");
     const rtkEnabled = enabledCapabilities.includes("rtk");
 
-    const ccusageResult = await collectCcusageSpending(options.days, deps);
+    const ccusageResult = await collectCcusageSpending(options.days, collectorDeps);
     if (ccusageResult.friendlyError) console.warn(ccusageResult.friendlyError);
 
     let tokensaveWorking: Awaited<ReturnType<typeof collectTokenSaveSavings>> = {
@@ -155,26 +158,21 @@ export async function runReportCommand(
       entry: null,
       status: { name: "rtk", enabled: false, status: "not enabled" },
     };
-    let headroomResult: Awaited<ReturnType<typeof collectHeadroomSavings>> = {
-      entry: null,
-      status: { name: "headroom", enabled: false, status: "not enabled" },
-    };
 
     if (tokensaveEnabled) {
       [tokensaveWorking, tokensaveCompanion] = await Promise.all([
-        collectTokenSaveSavings(workingRepoPath, options.days, deps),
-        collectTokenSaveSavings(companionPath, options.days, deps),
+        collectTokenSaveSavings(workingRepoPath, options.days, collectorDeps),
+        collectTokenSaveSavings(companionPath, options.days, collectorDeps),
       ]);
     }
-    if (rtkEnabled) rtkResult = await collectRTKSavings(workingRepoPath, deps);
-    if (headroomEnabled) headroomResult = await collectHeadroomSavings(options.days, deps);
+    if (rtkEnabled)
+      rtkResult = await collectRTKSavings(workingRepoPath, options.days, collectorDeps);
 
     const merged = mergeResults(
       ccusageResult.entries,
       tokensaveWorking.entry,
       tokensaveCompanion.entry,
       rtkResult.entry,
-      headroomResult.entry,
     );
     const reportData: ReportData = {
       days: options.days,
@@ -185,12 +183,7 @@ export async function runReportCommand(
       enabledCapabilities,
       spending: merged.spending,
       savings: merged.savings,
-      toolStatus: [
-        ccusageResult.status,
-        tokensaveWorking.status,
-        rtkResult.status,
-        headroomResult.status,
-      ],
+      toolStatus: [ccusageResult.status, tokensaveWorking.status, rtkResult.status],
       totalSpending: merged.totalSpending,
       totalSavings: merged.totalSavings,
       netSpend: merged.netSpend,

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

@@ -1,13 +1,45 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
 import { reportDataToDocument } from "./adapter";
 import { validateReportDocument } from "./contract";
+import { highlightInline, highlightStyleBlock } from "./highlight";
 import type {
   ReportData,
+  ReportDiagramSection,
+  ReportDiffSection,
   ReportDocument,
   ReportKeyValue,
   ReportSection,
   ReportValue,
 } from "./types";
 
+const MERMAID_RUNTIME_PATH = join(
+  import.meta.dirname,
+  "../../../templates/report-assets/mermaid.min.js",
+);
+
+const MERMAID_RUNTIME_ID = "mermaid-runtime";
+
+const CODE_BLOCK_SELECTOR = "pre.report-code";
+
+let mermaidRuntime: string | undefined;
+
+/** A literal `</script` inside the bundle would close the inline element, so it is neutralised. */
+function readMermaidRuntime(): string {
+  mermaidRuntime ??= readFileSync(MERMAID_RUNTIME_PATH, "utf8").replaceAll(
+    "</script",
+    String.raw`<\/script`,
+  );
+  return mermaidRuntime;
+}
+
+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");
+
 type RenderInput = ReportDocument | ReportData;
 
 function isReportDocument(input: RenderInput): input is ReportDocument {
@@ -82,9 +114,19 @@ function sectionMarkdown(section: ReportSection): string {
         : "No data available.";
     case "text":
       return section.content;
+    case "diagram":
+      return section.mermaid === undefined
+        ? fence("", section.text)
+        : fence("mermaid", section.mermaid);
+    case "diff":
+      return section.patch.trim() ? fence("diff", section.patch) : "No data available.";
   }
 }
 
+function fence(language: string, content: string): string {
+  return `\`\`\`${language}\n${content}\n\`\`\``;
+}
+
 export function renderMarkdown(input: RenderInput): string {
   const data = normalize(input);
   const sections: string[] = [`# ${data.title}\n`];
@@ -153,6 +195,130 @@ function renderHTMLKeyValues(items: ReportKeyValue[]): string {
     : emptyHTML("No metadata available.");
 }
 
+type DiffLineKind = "add" | "del" | "context" | "hunk";
+
+interface DiffLine {
+  kind: DiffLineKind;
+  text: string;
+}
+
+interface DiffFile {
+  path?: string;
+  lines: DiffLine[];
+}
+
+const DIFF_METADATA_PREFIXES = [
+  "index ",
+  "old mode ",
+  "new mode ",
+  "new file mode ",
+  "deleted file mode ",
+  "similarity index ",
+  "dissimilarity index ",
+  "rename from ",
+  "rename to ",
+  "copy from ",
+  "copy to ",
+  "Binary files ",
+  "GIT binary patch",
+];
+
+function gitHeaderPath(line: string): string | undefined {
+  const rest = line.slice("diff --git ".length).trim();
+  const paired = /^a\/(.+?) b\/(.+)$/.exec(rest);
+  return paired ? paired[2] : rest || undefined;
+}
+
+/** Strips the `a/` or `b/` prefix and the optional trailing timestamp git may append. */
+function fileHeaderPath(value: string): string | undefined {
+  const path = value.split("\t")[0].trim();
+  if (path === "" || path === "/dev/null") return undefined;
+  return path.replace(/^[ab]\//, "");
+}
+
+function diffLineKind(line: string): DiffLineKind {
+  if (line.startsWith("+")) return "add";
+  if (line.startsWith("-")) return "del";
+  return "context";
+}
+
+/** `---`/`+++` only head a file outside a hunk; inside one they are ordinary changed lines. */
+function parseUnifiedDiff(patch: string): DiffFile[] {
+  const files: DiffFile[] = [];
+  let current: DiffFile | undefined;
+  let inHunk = false;
+
+  const open = (path?: string): DiffFile => {
+    const file: DiffFile = { path, lines: [] };
+    files.push(file);
+    return file;
+  };
+
+  for (const line of patch.replace(/\n+$/, "").split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      current = open(gitHeaderPath(line));
+      inHunk = false;
+      continue;
+    }
+    if (!inHunk && (line.startsWith("--- ") || line.startsWith("+++ "))) {
+      const path = fileHeaderPath(line.slice(4));
+      if (current === undefined) current = open(path);
+      else current.path ??= path;
+      continue;
+    }
+    if (line.startsWith("@@")) {
+      current ??= open();
+      current.lines.push({ kind: "hunk", text: line });
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk && DIFF_METADATA_PREFIXES.some((prefix) => line.startsWith(prefix))) continue;
+    if (line === "" && current === undefined) continue;
+    current ??= open();
+    current.lines.push({ kind: diffLineKind(line), text: line });
+  }
+
+  return files.filter((file) => file.lines.length > 0);
+}
+
+function diffLanguage(path: string | undefined): string | undefined {
+  if (path === undefined) return undefined;
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1) : undefined;
+}
+
+function renderHTMLDiffLine(line: DiffLine, language: string | undefined): string {
+  if (line.kind === "hunk") {
+    return `<div class="diff-line diff-hunk">${escapeHTML(line.text)}</div>`;
+  }
+  const glyph = /^[+\- ]/.test(line.text) ? line.text.slice(0, 1) : "";
+  const content = line.text.slice(glyph.length);
+  return `<div class="diff-line diff-${line.kind}"><span class="diff-glyph">${escapeHTML(glyph)}</span><span class="diff-code">${highlightInline(content, language)}</span></div>`;
+}
+
+function renderHTMLDiff(section: ReportDiffSection): string {
+  const files = section.patch.trim() === "" ? [] : parseUnifiedDiff(section.patch);
+  if (files.length === 0) return emptyHTML("No diff available.");
+
+  return files
+    .map((file) => {
+      const language = diffLanguage(file.path);
+      const heading =
+        file.path === undefined ? "" : `<p class="diff-file">${escapeHTML(file.path)}</p>`;
+      const lines = file.lines.map((line) => renderHTMLDiffLine(line, language)).join("");
+      return `<div class="diff-file-group">${heading}<div class="report-diff">${lines}</div></div>`;
+    })
+    .join("");
+}
+
+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>`;
+}
+
 function renderHTMLSectionBody(section: ReportSection): string {
   switch (section.type) {
     case "metadata":
@@ -186,6 +352,10 @@ function renderHTMLSectionBody(section: ReportSection): string {
       return section.content
         ? `<p class="report-text">${escapeHTML(section.content).replaceAll("\n", "<br>")}</p>`
         : emptyHTML("No text available.");
+    case "diagram":
+      return renderHTMLDiagram(section);
+    case "diff":
+      return renderHTMLDiff(section);
   }
 }
 
@@ -210,6 +380,13 @@ export function renderHTML(input: RenderInput): string {
     ? ` data-working-repository="${escapeHTML(legacy.workingRepoPath)}" data-companion-repository="${escapeHTML(legacy.companionRepoPath)}"`
     : "";
 
+  const visualStyles = carriesVisual(data.sections)
+    ? `\n  <style>${highlightStyleBlock(CODE_BLOCK_SELECTOR)}${VISUAL_SECTION_CSS}</style>`
+    : "";
+  const diagramRuntime = carriesMermaid(data.sections)
+    ? `\n  <script id="${MERMAID_RUNTIME_ID}">${readMermaidRuntime()}</script>\n  <script>mermaid.initialize({ startOnLoad: true, securityLevel: "strict" });</script>`
+    : "";
+
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -241,7 +418,7 @@ export function renderHTML(input: RenderInput): string {
       table { width: 100%; }
       th, td { color: #000; }
     }
-  </style>
+  </style>${visualStyles}
 </head>
 <body>
   <main class="report" data-report-version="${data.version}"${repositoryAttributes}>
@@ -253,11 +430,31 @@ export function renderHTML(input: RenderInput): string {
     </header>
     ${renderHTMLSection(summary)}
     ${data.sections.map(renderHTMLSection).join("\n    ")}
-  </main>
+  </main>${diagramRuntime}
 </body>
 </html>`;
 }
 
+const VISUAL_SECTION_CSS = `
+    pre.report-code { background: #f7f9fb; border: 1px solid #e8edf1; border-radius: 10px; margin: 0; overflow-x: auto; padding: 14px 16px; }
+    .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; }
+    .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-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; }
+    @media print {
+      pre.report-code, .report-diff { border-color: #999; }
+      .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" }>;
 
 export { escapeHTML };