@mandujs/core 0.33.0 → 0.34.0

package/src/a11y/run-audit.ts

@@ -0,0 +1,394 @@
+/**
+ * @mandujs/core/a11y — accessibility audit runner (Phase 18.χ).
+ *
+ * # Design contract
+ *
+ * 1. **Zero runtime cost when unused.** axe-core (~1 MB) and jsdom are
+ *    declared as optional peer dependencies in `@mandujs/core` —
+ *    neither is pulled into user bundles. `runAudit` uses dynamic
+ *    `import()` for both, so the axe-core bytes never reach Node's
+ *    module graph unless the caller actually asked for an audit.
+ *
+ * 2. **Graceful degradation.** When axe-core is absent the runner
+ *    returns `outcome: "axe-missing"` with an actionable `note` rather
+ *    than throwing. CLI callers translate that into a single-line
+ *    informational message and exit 0 (quality is opt-in).
+ *
+ * 3. **DOM provider preference.** JSDOM is the canonical host because
+ *    axe-core was written against it. When jsdom is not installed we
+ *    try HappyDOM (Mandu already uses `@happy-dom/global-registrator`
+ *    as a dev-dep) which covers the 80% path. If neither provider is
+ *    available we return `axe-missing` with a note that names which
+ *    piece is missing — jsdom, HappyDOM, or both.
+ *
+ * 4. **Bounded work.** `maxFiles` caps the input list (default 500) so
+ *    a misconfigured project that prerenders 10k routes can't hang CI.
+ *    Each file is audited sequentially; axe-core is CPU-bound and
+ *    parallelising across Bun's event loop offers zero wall-clock win.
+ *
+ * 5. **Testable.** `axeLoader` / `domLoader` options short-circuit the
+ *    module resolution so `run-audit.test.ts` can inject deterministic
+ *    fakes without mutating Bun's module cache.
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { AUDIT_IMPACT_ORDER, impactAtLeast } from "./types";
+import type {
+  AuditImpact,
+  AuditNode,
+  AuditReport,
+  AuditViolation,
+  RunAuditOptions,
+} from "./types";
+import { getFixHint } from "./fix-hints";
+
+/** Minimal structural typing for the axe-core handle we actually use. */
+interface AxeLike {
+  run(context: unknown, options?: unknown): Promise<AxeRunResult>;
+}
+
+/** axe-core's result shape (only the fields we consume). */
+interface AxeRunResult {
+  violations: Array<{
+    id: string;
+    impact: AuditImpact | null;
+    help: string;
+    helpUrl?: string;
+    nodes: Array<{
+      target?: string[] | string;
+      failureSummary?: string;
+      html?: string;
+    }>;
+  }>;
+}
+
+/** Minimal structural typing for the DOM provider handle. */
+interface DomProvider {
+  kind: "jsdom" | "happy-dom";
+  fromHtml(html: string, url: string): Promise<{ window: unknown; dispose: () => void }>;
+}
+
+const DEFAULT_MAX_FILES = 500;
+const DEFAULT_MIN_IMPACT: AuditImpact = "minor";
+
+/**
+ * Zero every entry in an impact-count record. Returned by value so
+ * callers never mutate a shared singleton.
+ */
+function emptyImpactCounts(): Record<AuditImpact, number> {
+  return { minor: 0, moderate: 0, serious: 0, critical: 0 };
+}
+
+/**
+ * Resolve the axe-core module. Tries the caller-supplied loader first
+ * (test-only path), then falls back to dynamic `import("axe-core")`.
+ * Returns `null` when the package is not installed — NEVER throws.
+ */
+async function resolveAxe(options: RunAuditOptions): Promise<AxeLike | null> {
+  const tryLoad = async (loader: () => Promise<unknown>): Promise<AxeLike | null> => {
+    try {
+      const mod = await loader();
+      if (!mod) return null;
+      // axe-core exports `.default` under ESM/CJS interop. Accept either.
+      const candidate = (mod as { default?: unknown }).default ?? mod;
+      if (candidate && typeof (candidate as AxeLike).run === "function") {
+        return candidate as AxeLike;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  };
+
+  if (options.axeLoader) return tryLoad(options.axeLoader);
+  // @ts-ignore -- optional peer dependency, may not be resolvable at typecheck time
+  return tryLoad(() => import("axe-core"));
+}
+
+/**
+ * Resolve a DOM provider. Prefers jsdom; falls back to HappyDOM via
+ * `happy-dom`'s `Window` export (the same class Mandu's test harness
+ * already depends on).
+ */
+async function resolveDomProvider(options: RunAuditOptions): Promise<DomProvider | null> {
+  // Caller override — used exclusively by tests that inject a fake
+  // with a `.kind` field.
+  if (options.domLoader) {
+    try {
+      const mod = await options.domLoader();
+      if (mod && typeof mod === "object" && "kind" in mod && "fromHtml" in mod) {
+        return mod as DomProvider;
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  }
+
+  // Preferred path — jsdom.
+  try {
+    // @ts-ignore -- optional peer dependency, may not be resolvable at typecheck time
+    const jsdom = await import("jsdom");
+    const JSDOMCtor = (jsdom as { JSDOM?: new (html: string, opts?: unknown) => unknown }).JSDOM;
+    if (JSDOMCtor) {
+      return {
+        kind: "jsdom",
+        async fromHtml(html: string, url: string) {
+          const instance = new JSDOMCtor(html, { url });
+          const window = (instance as { window: unknown }).window;
+          return {
+            window,
+            dispose() {
+              const w = window as { close?: () => void };
+              if (typeof w.close === "function") {
+                try { w.close(); } catch { /* no-op */ }
+              }
+            },
+          };
+        },
+      };
+    }
+  } catch {
+    // jsdom not installed — fall through to HappyDOM.
+  }
+
+  // Fallback path — HappyDOM.
+  try {
+    // @ts-ignore -- optional peer dependency, may not be resolvable at typecheck time
+    const happy = await import("happy-dom");
+    const WindowCtor = (happy as { Window?: new (opts?: { url?: string; innerWidth?: number }) => unknown }).Window;
+    if (WindowCtor) {
+      return {
+        kind: "happy-dom",
+        async fromHtml(html: string, url: string) {
+          const window = new WindowCtor({ url, innerWidth: 1024 }) as {
+            document: { write: (html: string) => void; close: () => void };
+            close?: () => Promise<void>;
+          };
+          window.document.write(html);
+          window.document.close();
+          return {
+            window,
+            dispose() {
+              if (typeof window.close === "function") {
+                try { window.close(); } catch { /* no-op */ }
+              }
+            },
+          };
+        },
+      };
+    }
+  } catch {
+    // HappyDOM not installed — both providers exhausted.
+  }
+
+  return null;
+}
+
+/**
+ * Flatten axe-core's node shape into our slim `AuditNode`. axe emits
+ * `target` as either a string or `string[]` depending on iframe
+ * context; we normalize to a single selector chain joined by `>`.
+ */
+function normalizeNodes(
+  raw: AxeRunResult["violations"][number]["nodes"]
+): AuditNode[] {
+  const nodes: AuditNode[] = [];
+  for (const n of raw.slice(0, 10)) {
+    let target: string;
+    if (Array.isArray(n.target)) {
+      target = n.target.filter((s) => typeof s === "string").join(" > ");
+    } else if (typeof n.target === "string") {
+      target = n.target;
+    } else {
+      target = "(unknown)";
+    }
+    const html = typeof n.html === "string" && n.html.length > 300
+      ? n.html.slice(0, 297) + "..."
+      : n.html;
+    nodes.push({
+      target,
+      failureSummary: n.failureSummary ?? "",
+      ...(html ? { html } : {}),
+    });
+  }
+  return nodes;
+}
+
+/**
+ * Audit a single HTML file. Returns the violations discovered (already
+ * filtered by `minImpact`) or `null` when the file could not be read —
+ * caller decides whether to warn or abort.
+ */
+async function auditFile(
+  absFile: string,
+  axe: AxeLike,
+  dom: DomProvider,
+  minImpact: AuditImpact
+): Promise<AuditViolation[] | null> {
+  let html: string;
+  try {
+    html = await fs.readFile(absFile, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const pageUrl = "file://" + absFile.replace(/\\/g, "/");
+  let handle: { window: unknown; dispose: () => void };
+  try {
+    handle = await dom.fromHtml(html, pageUrl);
+  } catch {
+    return null;
+  }
+
+  try {
+    // axe-core accepts a `document` as context. Both jsdom and HappyDOM
+    // expose `.window.document`.
+    const w = handle.window as { document?: unknown };
+    const context = w.document ?? handle.window;
+    const result = await axe.run(context);
+    const out: AuditViolation[] = [];
+    for (const v of result.violations) {
+      if (!impactAtLeast(v.impact ?? null, minImpact)) continue;
+      out.push({
+        file: absFile,
+        rule: v.id,
+        impact: v.impact ?? null,
+        help: v.help,
+        helpUrl: v.helpUrl,
+        nodes: normalizeNodes(v.nodes),
+        ...(getFixHint(v.id) ? { fixHint: getFixHint(v.id)! } : {}),
+      });
+    }
+    return out;
+  } catch {
+    return null;
+  } finally {
+    handle.dispose();
+  }
+}
+
+/**
+ * Public entry. Run axe-core against every HTML file in `htmlFiles`
+ * and aggregate the results. See `./types.ts` for the full report
+ * shape; this function never throws — every failure mode is surfaced
+ * via `outcome` + `note`.
+ */
+export async function runAudit(
+  htmlFiles: string[],
+  options: RunAuditOptions = {}
+): Promise<AuditReport> {
+  const started = performance.now();
+  const minImpact = options.minImpact ?? DEFAULT_MIN_IMPACT;
+  const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+  const bounded = htmlFiles.slice(0, maxFiles);
+
+  const axe = await resolveAxe(options);
+  if (!axe) {
+    return {
+      outcome: "axe-missing",
+      filesScanned: 0,
+      violations: [],
+      impactCounts: emptyImpactCounts(),
+      minImpact,
+      note: "axe-core not installed — skipping audit (bun add -d axe-core jsdom)",
+      durationMs: 0,
+    };
+  }
+
+  const dom = await resolveDomProvider(options);
+  if (!dom) {
+    return {
+      outcome: "axe-missing",
+      filesScanned: 0,
+      violations: [],
+      impactCounts: emptyImpactCounts(),
+      minImpact,
+      note: "No DOM provider available — install jsdom (recommended) or happy-dom",
+      durationMs: 0,
+    };
+  }
+
+  const allViolations: AuditViolation[] = [];
+  const impactCounts = emptyImpactCounts();
+  let scanned = 0;
+
+  for (const file of bounded) {
+    const abs = path.resolve(file);
+    const perFile = await auditFile(abs, axe, dom, minImpact);
+    if (perFile === null) continue; // unreadable — counts as not scanned
+    scanned += 1;
+    for (const v of perFile) {
+      allViolations.push(v);
+      if (v.impact) impactCounts[v.impact] += 1;
+    }
+  }
+
+  return {
+    outcome: allViolations.length > 0 ? "violations" : "ok",
+    filesScanned: scanned,
+    violations: allViolations,
+    impactCounts,
+    minImpact,
+    durationMs: Math.round(performance.now() - started),
+  };
+}
+
+/**
+ * Pretty-print an audit report as a multi-line ASCII table suitable
+ * for CLI output. Separate from `runAudit` so JSON consumers stay
+ * unaffected by formatting concerns.
+ */
+export function formatAuditReport(report: AuditReport): string {
+  const lines: string[] = [];
+  lines.push("Accessibility audit (axe-core)");
+  lines.push("=".repeat(50));
+
+  if (report.outcome === "axe-missing") {
+    lines.push(report.note ?? "axe-core not installed — skipping audit");
+    lines.push("");
+    lines.push("  Install the optional peers to enable:");
+    lines.push("    bun add -d axe-core jsdom");
+    return lines.join("\n");
+  }
+
+  lines.push(
+    `  Files scanned: ${report.filesScanned}  ·  ` +
+      `Violations: ${report.violations.length}  ·  ` +
+      `Duration: ${report.durationMs}ms`
+  );
+  lines.push(
+    `  By impact: ` +
+      AUDIT_IMPACT_ORDER
+        .map((i) => `${i}=${report.impactCounts[i]}`)
+        .join("  ")
+  );
+  lines.push(`  Min impact: ${report.minImpact}`);
+  lines.push("");
+
+  if (report.outcome === "ok") {
+    lines.push("  No violations at or above minImpact. PASS.");
+    return lines.join("\n");
+  }
+
+  // Group by rule id so the table is navigable.
+  const byRule = new Map<string, AuditViolation[]>();
+  for (const v of report.violations) {
+    if (!byRule.has(v.rule)) byRule.set(v.rule, []);
+    byRule.get(v.rule)!.push(v);
+  }
+
+  for (const [rule, violations] of byRule) {
+    const first = violations[0];
+    const impact = first.impact ?? "unknown";
+    lines.push(`  [${impact.toUpperCase()}] ${rule}  —  ${first.help}`);
+    if (first.fixHint) lines.push(`     Fix: ${first.fixHint}`);
+    const totalNodes = violations.reduce((n, v) => n + v.nodes.length, 0);
+    lines.push(`     ${violations.length} file(s), ${totalNodes} node(s)`);
+    if (first.helpUrl) lines.push(`     Docs: ${first.helpUrl}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/a11y/types.ts

@@ -0,0 +1,125 @@
+/**
+ * @mandujs/core/a11y — audit result types.
+ *
+ * Phase 18.χ introduces a framework-level accessibility guardrail that
+ * runs axe-core against prerendered HTML and aggregates WCAG violations
+ * into a structured report. axe-core and jsdom are **optional peer
+ * dependencies** — we never install them for the user. When absent, the
+ * runner degrades gracefully to an `"axe-missing"` outcome instead of
+ * throwing or bundling ~1 MB of rules into every consumer.
+ *
+ * Severity mapping matches axe-core's `impact` scale verbatim so CI
+ * gates using `--audit-fail-on=<impact>` speak the same vocabulary as
+ * the axe documentation:
+ *
+ *   - `minor`    — nice-to-fix cosmetic a11y issue
+ *   - `moderate` — noticeable UX degradation
+ *   - `serious`  — significant barrier for users with disabilities
+ *   - `critical` — blocks assistive-tech users outright (default gate)
+ */
+
+/** axe-core impact scale (lowest → highest). */
+export type AuditImpact = "minor" | "moderate" | "serious" | "critical";
+
+/** Canonical ordering used by severity comparisons. */
+export const AUDIT_IMPACT_ORDER: readonly AuditImpact[] = [
+  "minor",
+  "moderate",
+  "serious",
+  "critical",
+] as const;
+
+/**
+ * Return `true` when `candidate` is at least as severe as `threshold`.
+ * Used by both the runner (severity filter) and the CLI gate
+ * (`--audit-fail-on`).
+ */
+export function impactAtLeast(candidate: AuditImpact | null | undefined, threshold: AuditImpact): boolean {
+  if (!candidate) return false;
+  const ci = AUDIT_IMPACT_ORDER.indexOf(candidate);
+  const ti = AUDIT_IMPACT_ORDER.indexOf(threshold);
+  return ci >= 0 && ti >= 0 && ci >= ti;
+}
+
+/** Per-node failure detail. Keeps payloads small — we intentionally
+ *  discard axe's full `any`/`all`/`none` check trees and keep only the
+ *  fields humans act on (selector + failure summary). */
+export interface AuditNode {
+  /** CSS selector chain axe-core emits (e.g. `html > body > div#root`). */
+  target: string;
+  /** axe's `failureSummary` — already-localized multi-line description. */
+  failureSummary: string;
+  /** Raw HTML snippet for the offending node (truncated to 300 chars). */
+  html?: string;
+}
+
+/** One WCAG violation emitted by axe-core, scoped to a single HTML file. */
+export interface AuditViolation {
+  /** Source HTML file (absolute path). */
+  file: string;
+  /** axe-core rule id, e.g. `color-contrast`, `label`, `image-alt`. */
+  rule: string;
+  /** Severity — may be `null` when axe fails to classify (rare). */
+  impact: AuditImpact | null;
+  /** One-line human-readable rule summary (`node.help`). */
+  help: string;
+  /** URL to axe-core's documentation for this rule. */
+  helpUrl?: string;
+  /** Offending DOM nodes. Capped at 10 to keep reports consumable. */
+  nodes: AuditNode[];
+  /** Phase 18.χ hint — short actionable fix recipe when we recognize the rule. */
+  fixHint?: string;
+}
+
+/**
+ * Audit outcome. The three arms are mutually exclusive:
+ *
+ *   - `ok`              — runner executed, zero violations ≥ minImpact.
+ *   - `violations`      — runner executed, at least one violation fired.
+ *   - `axe-missing`     — optional dep not installed; runner was a no-op.
+ *
+ * The `filesScanned` counter is always present so callers can print a
+ * meaningful summary ("audited 12 files, 0 violations") regardless of
+ * outcome.
+ */
+export interface AuditReport {
+  outcome: "ok" | "violations" | "axe-missing";
+  /** Number of HTML files actually fed to axe-core (0 when dep missing). */
+  filesScanned: number;
+  /** Aggregated violations across every file. Empty when `outcome !== "violations"`. */
+  violations: AuditViolation[];
+  /** Count of violations at each impact level. */
+  impactCounts: Record<AuditImpact, number>;
+  /** Effective severity filter applied during this run. */
+  minImpact: AuditImpact;
+  /** Optional human-readable note (e.g. why the runner skipped). */
+  note?: string;
+  /** Elapsed wallclock ms. Zero when runner was a no-op. */
+  durationMs: number;
+}
+
+/** Options accepted by `runAudit`. */
+export interface RunAuditOptions {
+  /**
+   * Minimum severity to include in the report. Violations below this
+   * threshold are dropped at aggregation time. Default `"minor"`.
+   */
+  minImpact?: AuditImpact;
+  /**
+   * Cap on files to audit. Prevents catastrophic CI runs on projects
+   * that accidentally prerender thousands of routes. Default `500`.
+   */
+  maxFiles?: number;
+  /**
+   * Override for axe-core module resolution. When undefined, the runner
+   * uses dynamic `import("axe-core")`. Tests inject a fixture instead
+   * of shimming the module resolver.
+   */
+  axeLoader?: () => Promise<unknown>;
+  /**
+   * Override for jsdom module resolution. Same contract as `axeLoader`;
+   * returning `null` forces the runner to fall back to HappyDOM which is
+   * already a transitive test-time dep for Mandu.
+   */
+  domLoader?: () => Promise<unknown>;
+}

package/src/bundler/analyzer.ts

@@ -79,6 +79,7 @@ import path from "path";
 import zlib from "zlib";
 
 import type { BundleManifest } from "./types";
+import type { BudgetReport } from "./budget";
 
 // ============================================================================
 // Types
@@ -439,21 +440,26 @@ export async function analyzeBundle(
  *
  * Returns the absolute paths of both files so the CLI can print them.
  * Callers that want JSON only can skip the HTML step via `{ htmlPath: null }`.
+ *
+ * Phase 18.φ — `opts.budget` is an optional pre-computed budget report
+ * that, when present, renders a budget-bar section in the HTML output
+ * and is serialised alongside `report.json` as `report.budget`.
  */
 export async function writeAnalyzeReport(
   rootDir: string,
   report: AnalyzeReport,
-  opts: { html?: boolean } = {}
+  opts: { html?: boolean; budget?: BudgetReport | null } = {}
 ): Promise<{ jsonPath: string; htmlPath: string | null }> {
   const outDir = path.join(rootDir, ".mandu", "analyze");
   await fs.mkdir(outDir, { recursive: true });
   const jsonPath = path.join(outDir, "report.json");
-  await fs.writeFile(jsonPath, JSON.stringify(report, null, 2), "utf8");
+  const jsonPayload = opts.budget ? { ...report, budget: opts.budget } : report;
+  await fs.writeFile(jsonPath, JSON.stringify(jsonPayload, null, 2), "utf8");
 
   let htmlPath: string | null = null;
   if (opts.html !== false) {
     htmlPath = path.join(outDir, "report.html");
-    await fs.writeFile(htmlPath, renderAnalyzeHtml(report), "utf8");
+    await fs.writeFile(htmlPath, renderAnalyzeHtml(report, opts.budget ?? null), "utf8");
   }
   return { jsonPath, htmlPath };
 }
@@ -475,7 +481,10 @@ export async function writeAnalyzeReport(
  *     toggles visibility. This keeps the report working even with JS
  *     disabled (you lose drill-down, but the island treemap still renders).
  */
-export function renderAnalyzeHtml(report: AnalyzeReport): string {
+export function renderAnalyzeHtml(
+  report: AnalyzeReport,
+  budget: BudgetReport | null = null
+): string {
   const { islands, shared, summary } = report;
 
   // ── Island-level treemap ─────────────────────────────────────────────────
@@ -585,6 +594,18 @@ export function renderAnalyzeHtml(report: AnalyzeReport): string {
     <div class="card"><div class="label">Dedupe savings</div><div class="value">${fmtBytes(summary.dedupeSavings)}</div></div>
   `;
 
+  // ── Phase 18.φ — Budget bar section ──────────────────────────────────────
+  //
+  // Renders one horizontal bar per island when a budget was evaluated,
+  // coloured by `BudgetStatus`: green (within), yellow (within 10% of
+  // limit), red (exceeded). The bar width is proportional to
+  // `island.gz / gzLimit` (or `raw / rawLimit` if gzLimit is null).
+  // When every axis is unconstrained the bar is hidden with a muted "—"
+  // placeholder. Matches the "red/yellow/green" spec in Phase 18.φ.
+  const budgetSection = budget
+    ? renderBudgetSection(budget)
+    : "";
+
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -621,6 +642,25 @@ export function renderAnalyzeHtml(report: AnalyzeReport): string {
   button.close { background: #1f2937; color: #e5e7eb; border: 1px solid #374151; padding: 4px 10px; border-radius: 3px; cursor: pointer; font-family: inherit; font-size: 11px; }
   button.close:hover { background: #374151; }
   .drill-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+  /* Phase 18.φ — budget bars */
+  .budget-row { display: grid; grid-template-columns: 180px 1fr 160px; gap: 10px; align-items: center; padding: 4px 0; border-bottom: 1px solid #1f2937; }
+  .budget-row:last-child { border-bottom: none; }
+  .budget-name { font-size: 12px; color: #e5e7eb; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .budget-meta { font-size: 11px; color: #94a3b8; text-align: right; font-variant-numeric: tabular-nums; }
+  .budget-bar-track { position: relative; height: 10px; background: #0f172a; border: 1px solid #1f2937; border-radius: 2px; overflow: hidden; }
+  .budget-bar-fill { height: 100%; border-radius: 2px; }
+  .budget-bar-fill.within { background: linear-gradient(90deg, #16a34a, #22c55e); }
+  .budget-bar-fill.within10 { background: linear-gradient(90deg, #ca8a04, #eab308); }
+  .budget-bar-fill.exceeded { background: linear-gradient(90deg, #b91c1c, #ef4444); }
+  .budget-bar-fill.unbounded { background: repeating-linear-gradient(45deg, #1f2937, #1f2937 4px, #0f172a 4px, #0f172a 8px); }
+  .budget-legend { display: inline-flex; gap: 14px; font-size: 11px; color: #94a3b8; margin-bottom: 10px; }
+  .budget-legend span::before { content: ""; display: inline-block; width: 10px; height: 10px; border-radius: 2px; margin-right: 5px; vertical-align: middle; }
+  .budget-legend .lg-within::before { background: #22c55e; }
+  .budget-legend .lg-within10::before { background: #eab308; }
+  .budget-legend .lg-exceeded::before { background: #ef4444; }
+  .budget-mode { display: inline-block; font-size: 10px; text-transform: uppercase; padding: 2px 6px; border-radius: 2px; border: 1px solid #374151; color: #cbd5e1; margin-left: 8px; letter-spacing: 0.04em; }
+  .budget-mode.error { background: #7f1d1d; border-color: #991b1b; color: #fecaca; }
+  .budget-mode.warning { background: #713f12; border-color: #854d0e; color: #fde68a; }
 </style>
 </head>
 <body>
@@ -632,6 +672,8 @@ export function renderAnalyzeHtml(report: AnalyzeReport): string {
   <h2>Summary</h2>
   <div class="cards">${summaryCards}</div>
 
+  ${budgetSection}
+
   <h2>Islands (click to drill in)</h2>
   <svg class="treemap" viewBox="0 0 ${VIEW_W} ${VIEW_H}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="Island bundle treemap">
     ${islandSvg || `<text x="20" y="30" fill="#64748b">No islands to display.</text>`}
@@ -703,6 +745,79 @@ export function renderAnalyzeHtml(report: AnalyzeReport): string {
 // Helpers — formatting + squarify
 // ============================================================================
 
+/**
+ * Phase 18.φ — render the budget-bar block. Colour-codes each island
+ * by {@link BudgetReport.BudgetStatus} and the project-wide total (when
+ * present). Islands without any applicable limit render a diagonal-
+ * hatched "unbounded" bar so the user sees the row but understands
+ * nothing is enforced. Self-contained: no JS, no external assets.
+ */
+function renderBudgetSection(budget: BudgetReport): string {
+  const modeClass = budget.mode === "error" ? "error" : "warning";
+  const rows = budget.islands
+    .map((i) => renderBudgetRow(i.name, i.raw, i.gz, i.rawLimit, i.gzLimit, i.status))
+    .join("");
+  const totalRow = budget.total
+    ? renderBudgetRow(
+        "<project total>",
+        budget.total.raw,
+        budget.total.gz,
+        budget.total.rawLimit,
+        budget.total.gzLimit,
+        budget.total.status
+      )
+    : "";
+  const exceedHeadline = budget.hasExceeded
+    ? ` · <span style="color:#fca5a5">${budget.exceededCount} over limit</span>`
+    : "";
+  return `
+  <h2>Bundle budget <span class="budget-mode ${modeClass}">${escText(budget.mode)}</span></h2>
+  <div class="budget-legend">
+    <span class="lg-within">within</span>
+    <span class="lg-within10">approaching (≥90%)</span>
+    <span class="lg-exceeded">exceeded</span>
+  </div>
+  <p class="muted" style="margin:0 0 10px">
+    ${budget.withinCount}/${budget.islandCount} islands within limits${exceedHeadline}
+  </p>
+  <div class="card" style="padding:12px 14px">
+    ${rows}
+    ${totalRow}
+  </div>`;
+}
+
+function renderBudgetRow(
+  name: string,
+  raw: number,
+  gz: number,
+  rawLimit: number | null,
+  gzLimit: number | null,
+  status: "within" | "within10" | "exceeded"
+): string {
+  // Prefer gz-axis progress bar when a gz limit exists (the 90%-of-the-
+  // time-useful axis); fall back to raw when only raw is constrained.
+  let pct = 0;
+  let barClass: string = status;
+  let meta: string;
+  if (gzLimit !== null) {
+    pct = Math.min(100, Math.max(0, (gz / Math.max(gzLimit, 1)) * 100));
+    meta = `${fmtBytes(gz)} / ${fmtBytes(gzLimit)} gz`;
+  } else if (rawLimit !== null) {
+    pct = Math.min(100, Math.max(0, (raw / Math.max(rawLimit, 1)) * 100));
+    meta = `${fmtBytes(raw)} / ${fmtBytes(rawLimit)} raw`;
+  } else {
+    barClass = "unbounded";
+    pct = 100;
+    meta = `${fmtBytes(gz)} gz · no limit`;
+  }
+  return `
+    <div class="budget-row">
+      <div class="budget-name" title="${escAttr(name)}">${escText(name)}</div>
+      <div class="budget-bar-track"><div class="budget-bar-fill ${barClass}" style="width:${pct.toFixed(1)}%"></div></div>
+      <div class="budget-meta">${meta}</div>
+    </div>`;
+}
+
 /** Human-readable byte formatter. Matches the style used by `printBundleStats`. */
 export function fmtBytes(n: number): string {
   if (!Number.isFinite(n) || n <= 0) return "0 B";