@akanjs/devkit 3.1.2-rc.4 → 3.2.0-rc.1

package/preview/PreviewView.ts

@@ -5,7 +5,8 @@ export interface PreviewProbeOptions {
   width?: number;
   height?: number;
   engine?: PreviewEngine;
-  /** Bounds the whole probe: a dev server that is recovering takes the connection and never answers. */
+  startTimeoutMs?: number;
+  /** Bounds the probe once the browser is up: a dev server that is recovering takes the connection and never answers. */
   timeoutMs?: number;
   /** Waited after the load, so the errors effects throw land before the page is read. */
   settleMs?: number;
@@ -45,6 +46,10 @@ interface PageRead {
 // Bun.WebView rather than a downloaded browser: on macOS its webkit backend needs no Chromium at all.
 // It is experimental, so its whole surface stays behind this adapter; a Bun minor that changes it breaks one file.
 export class PreviewView {
+  /** A view's first navigation includes the browser's start, which took ~35 s on a cold CI runner. */
+  static readonly startTimeoutMs = 120_000;
+  static readonly #stalled = new Set<PreviewEngine>();
+
   static get available() {
     return PreviewView.isAvailable();
   }
@@ -66,15 +71,31 @@ export class PreviewView {
       width = 1280,
       height = 800,
       engine = PreviewChrome.backend,
+      startTimeoutMs = PreviewView.startTimeoutMs,
       timeoutMs = 30_000,
       settleMs = 0,
     }: PreviewProbeOptions = {},
   ): Promise<PreviewProbeResult> {
     const logs: string[] = [];
-    const deadline = Date.now() + timeoutMs;
-    const within = <T>(work: Promise<T>, what: string) => PreviewView.#within(work, deadline, `${what} ${url}`);
     const view = PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) });
     try {
+      //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
+      const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
+      const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
+      await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled).then(
+        () => PreviewView.#stalled.delete(engine),
+        (error: unknown) => {
+          if (error === stalled) PreviewView.#stalled.add(engine);
+          throw error;
+        },
+      );
+      const deadline = Date.now() + timeoutMs;
+      const within = <T>(work: Promise<T>, what: string) =>
+        PreviewView.#within(
+          work,
+          deadline,
+          new Error(`Timed out ${what} ${url}; the dev server may be rebuilding or stuck.`),
+        );
       let page = await PreviewView.#load(view, url, settleMs, within);
       //? Right after a save the first load can render nothing (`[rscClient] module not loaded`); the next one has it.
       if (page.empty) {
@@ -126,13 +147,10 @@ export class PreviewView {
     return response?.status ?? null;
   }
 
-  static async #within<T>(work: Promise<T>, deadline: number, what: string): Promise<T> {
+  static async #within<T>(work: Promise<T>, deadline: number, expiry: Error): Promise<T> {
     let timer: ReturnType<typeof setTimeout> | undefined;
     const expired = new Promise<never>((_, reject) => {
-      timer = setTimeout(
-        () => reject(new Error(`Timed out ${what}; the dev server may be rebuilding or stuck.`)),
-        Math.max(0, deadline - Date.now()),
-      );
+      timer = setTimeout(() => reject(expiry), Math.max(0, deadline - Date.now()));
     });
     try {
       return await Promise.race([work, expired]);

package/preview/previewView.test.ts

@@ -1,9 +1,42 @@
 import { describe, expect, test } from "bun:test";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { PreviewChrome } from "./PreviewChrome";
 import { PreviewView } from "./PreviewView";
 
 const serve = (html: string, status = 200) =>
   Bun.serve({ port: 0, fetch: () => new Response(html, { status, headers: { "content-type": "text/html" } }) });
 
+const browserTestMs = PreviewView.startTimeoutMs + 30_000;
+const slowChromeRuns = PreviewView.isAvailable("chrome") && process.platform !== "win32";
+
+const withSlowChrome = async (body: string, startSeconds = 3) => {
+  const dir = await mkdtemp(path.join(tmpdir(), "akan-slow-chrome-"));
+  const chrome = path.join(dir, "chrome");
+  await writeFile(chrome, `#!/bin/sh\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`);
+  await chmod(chrome, 0o755);
+  const script = `const { PreviewView } = await import(${JSON.stringify(path.join(import.meta.dir, "PreviewView.ts"))});\n${body}`;
+  //? Chrome is spawned once per process, so only a fresh process takes the slow executable.
+  const child = Bun.spawn([process.execPath, "-e", script], {
+    env: { ...process.env, [PreviewChrome.pathEnvKey]: chrome },
+    stdout: "pipe",
+    stderr: "pipe",
+    timeout: PreviewView.startTimeoutMs + 15_000,
+  });
+  try {
+    const [out, err, code] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ]);
+    return { code, out: out.trim(), err };
+  } finally {
+    child.kill();
+    await rm(dir, { recursive: true, force: true });
+  }
+};
+
 describe("PreviewView", () => {
   test("reports whether this Bun build can drive a headless page at all", () => {
     expect(typeof PreviewView.available).toBe("boolean");
@@ -29,7 +62,7 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
   );
 
   test.skipIf(!PreviewView.available)(
@@ -56,7 +89,7 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
   );
 
   test.skipIf(!PreviewView.available)(
@@ -71,6 +104,57 @@ describe("PreviewView", () => {
         server.stop(true);
       }
     },
-    30_000,
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "starts the page's bound once the browser is up, however long Chrome takes to spawn",
+    async () => {
+      const server = serve("<!doctype html><title>Up</title><body>up</body>");
+      try {
+        const { code, out, err } = await withSlowChrome(
+          `const probe = await PreviewView.probe("http://localhost:${server.port}/", { engine: "chrome", timeoutMs: 1_500 });
+console.log(probe.text);`,
+        );
+        expect(out || err).toBe("up");
+        expect(code).toBe(0);
+      } finally {
+        server.stop(true);
+      }
+    },
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "gives a later page only its own bound for a browser that missed its start, and recovers once it is up",
+    async () => {
+      const { code, out, err } = await withSlowChrome(
+        `const open = () =>
+  PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
+    () => "opened",
+    (error) => error.message,
+  );
+console.log(await open());
+console.log(await open());
+let late = await open();
+for (let tries = 0; late !== "opened" && tries < 100; tries++) late = await open();
+console.log(late);
+Bun.WebView.closeAll();
+await Bun.sleep(500);
+console.log(await open());
+Bun.WebView.closeAll();`,
+        6,
+      );
+      expect(out || err).toBe(
+        [
+          "Timed out starting the chrome browser after 1.5 s.",
+          "Timed out starting the chrome browser after 1 s.",
+          "opened",
+          "Timed out starting the chrome browser after 1.5 s.",
+        ].join("\n"),
+      );
+      expect(code).toBe(0);
+    },
+    browserTestMs,
   );
 });

package/routeJsBudget.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { RouteJsBudget, type RouteJsSize } from "./routeJsBudget";
+import { tempDirs, writeText as write } from "./testHelpers";
+
+const makeTempRoot = tempDirs("akan-route-js-");
+const size = (routeId: string, brotliKB: number): RouteJsSize => ({
+  routeId,
+  files: 1,
+  rawBytes: brotliKB * 3 * 1024,
+  brotliBytes: brotliKB * 1024,
+});
+
+describe("RouteJsBudget", () => {
+  test("measures a route by the brotli sidecar of each file it loads, and a file with none by its raw bytes", async () => {
+    const artifactDir = await makeTempRoot();
+    await write(path.join(artifactDir, "client/rsc.js"), "r".repeat(3000));
+    await write(path.join(artifactDir, "client/rsc.js.br"), "b".repeat(900));
+    await write(path.join(artifactDir, "client/chunks/tiny.js"), "t".repeat(200));
+    await write(path.join(artifactDir, "client/memo.js"), "m".repeat(5000));
+    await write(path.join(artifactDir, "client/memo.js.br"), "b".repeat(1200));
+
+    const sizes = await RouteJsBudget.measure(artifactDir, {
+      "/:lang": ["/_akan/client/rsc.js", "/_akan/client/chunks/tiny.js"],
+      "/:lang/memo": ["/_akan/client/rsc.js", "/_akan/client/chunks/tiny.js", "/_akan/client/memo.js"],
+    });
+
+    expect(sizes).toEqual([
+      { routeId: "/:lang/memo", files: 3, rawBytes: 8200, brotliBytes: 2300 },
+      { routeId: "/:lang", files: 2, rawBytes: 3200, brotliBytes: 1100 },
+    ]);
+  });
+
+  test("fails only a route past its entry plus the larger of 1% and 4KB, and leaves a route without one to the report", () => {
+    const budget = RouteJsBudget.parse(
+      JSON.stringify({ routeJsBrotliKB: { "/:lang": 100, "/:lang/memo": 120, "/:lang/feed": 500 } }),
+    );
+    const sizes = [
+      { ...size("/:lang", 100), brotliBytes: 100 * 1024 + 4096 },
+      { ...size("/:lang/memo", 120), brotliBytes: 120 * 1024 + 4097 },
+      { ...size("/:lang/feed", 500), brotliBytes: 500 * 1024 + 5000 },
+      size("/x", 900),
+    ];
+
+    expect(RouteJsBudget.limitOf(500)).toBe(500 * 1024 + 5120);
+    expect(budget.overages(sizes)).toEqual([
+      { routeId: "/:lang/memo", brotliBytes: 120 * 1024 + 4097, budgetKB: 120, limitBytes: 120 * 1024 + 4096 },
+    ]);
+    expect(budget.unbudgeted(sizes)).toEqual(["/x"]);
+  });
+
+  test("an update adds a new route, lowers an entry the route fits under, never raises one, and drops a gone route", () => {
+    const committed = RouteJsBudget.parse(
+      JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang": 100, "/:lang/memo": 120, "/:lang/gone": 50 } }),
+    );
+    const updated = committed.tightenedBy(
+      [
+        { ...size("/:lang", 90), brotliBytes: 90 * 1024 - 300 },
+        size("/:lang/memo", 130),
+        size("/:lang/new", 70),
+        size("/:lang/Zeta", 10),
+      ],
+      "local",
+    );
+
+    expect(Object.fromEntries(updated.kbByRoute)).toEqual({
+      "/:lang": 90,
+      "/:lang/memo": 120,
+      "/:lang/new": 70,
+      "/:lang/Zeta": 10,
+    });
+    expect(updated.stringify()).toBe(
+      `{\n  "env": "local",\n  "routeJsBrotliKB": {\n    "/:lang": 90,\n    "/:lang/Zeta": 10,\n    "/:lang/memo": 120,\n    "/:lang/new": 70\n  }\n}\n`,
+    );
+  });
+
+  test("names the environment a budget was recorded for when the build is for another", () => {
+    const budget = RouteJsBudget.parse(JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang": 100 } }));
+
+    expect(budget.envNote("main")).toBe("");
+    expect(budget.envNote("local")).toBe(" (recorded for main, built for local)");
+    expect(RouteJsBudget.parse(JSON.stringify({ routeJsBrotliKB: {} })).envNote("local")).toBe("");
+  });
+
+  test("refuses a file that is not a map of route ids to whole KB", () => {
+    expect(() => RouteJsBudget.parse("{", "apps/shop/akan.budget.json")).toThrow(
+      "apps/shop/akan.budget.json is not valid JSON.",
+    );
+    for (const text of ["{}", '{"routeJsBrotliKB":[]}', '{"routeJsBrotliKB":{"/":1.5}}', '{"routeJsBrotliKB":{"/":0}}'])
+      expect(() => RouteJsBudget.parse(text)).toThrow('"routeJsBrotliKB" maps each route id to a whole number of KB.');
+    expect(() => RouteJsBudget.parse('{"env":1,"routeJsBrotliKB":{}}')).toThrow('"env" names the environment');
+  });
+
+  describe("check", () => {
+    const sizes = [{ ...size("/:lang/memo", 120), brotliBytes: 130 * 1024 }, size("/:lang/new", 70)];
+    const setup = async (text?: string) => {
+      const budgetPath = path.join(await makeTempRoot(), "akan.budget.json");
+      if (text !== undefined) await write(budgetPath, text);
+      return { budgetPath, source: "apps/shop/akan.budget.json", environment: "local" };
+    };
+
+    test("enforce fails a route over its limit and a file it cannot read", async () => {
+      const over = await setup(JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang/memo": 120 } }));
+      await expect(RouteJsBudget.check(sizes, { ...over, mode: "enforce" })).rejects.toThrow(
+        "1 route over the JS budget in apps/shop/akan.budget.json (recorded for main, built for local):",
+      );
+      const broken = await setup("{");
+      await expect(RouteJsBudget.check(sizes, { ...broken, mode: "enforce" })).rejects.toThrow("is not valid JSON");
+    });
+
+    test("report warns of an overage and a file it cannot read, and fails neither", async () => {
+      const over = await setup(JSON.stringify({ env: "main", routeJsBrotliKB: { "/:lang/memo": 120 } }));
+      expect(await RouteJsBudget.check(sizes, { ...over, mode: "report" })).toEqual({
+        summary:
+          "1 route(s) over apps/shop/akan.budget.json (recorded for main, built for local), reported only: /:lang/memo",
+        warnings: [
+          {
+            file: "apps/shop/akan.budget.json",
+            message:
+              "/:lang/memo loads 133,120 bytes brotli, over its limit of 126,976 (recorded for main, built for local); akan build fails on it",
+            fix: "shrink what the route loads, or raise its entry by hand in the same change",
+          },
+        ],
+      });
+      const broken = await setup("{");
+      expect(await RouteJsBudget.check(sizes, { ...broken, mode: "report" })).toEqual({
+        summary: "apps/shop/akan.budget.json is not valid JSON, not checked",
+        warnings: [
+          {
+            file: "apps/shop/akan.budget.json",
+            message: "apps/shop/akan.budget.json is not valid JSON; akan build fails on it",
+            fix: "correct it, or rewrite it with akan build <app> --update-budget",
+          },
+        ],
+      });
+      expect(await RouteJsBudget.check(sizes, { ...(await setup()), mode: "report" })).toEqual({
+        summary: "no akan.budget.json",
+      });
+      const within = await setup(JSON.stringify({ routeJsBrotliKB: { "/:lang/memo": 130 } }));
+      expect(await RouteJsBudget.check(sizes, { ...within, mode: "report" })).toEqual({
+        summary: "within apps/shop/akan.budget.json, 1 route(s) without an entry",
+      });
+    });
+
+    test("update writes the file for this build's environment, rewriting one it cannot read", async () => {
+      const broken = await setup("{");
+      expect(await RouteJsBudget.check(sizes, { ...broken, mode: "update" })).toEqual({
+        summary: "apps/shop/akan.budget.json rewritten (apps/shop/akan.budget.json is not valid JSON)",
+      });
+      const written = RouteJsBudget.parse(await Bun.file(broken.budgetPath).text());
+      expect(written.env).toBe("local");
+      expect(Object.fromEntries(written.kbByRoute)).toEqual({ "/:lang/memo": 130, "/:lang/new": 70 });
+    });
+
+    test("update keeps an entry its route outgrew, and still fails the route", async () => {
+      const over = await setup(JSON.stringify({ routeJsBrotliKB: { "/:lang/memo": 120 } }));
+      await expect(RouteJsBudget.check(sizes, { ...over, mode: "update" })).rejects.toThrow("/:lang/memo");
+      expect(RouteJsBudget.parse(await Bun.file(over.budgetPath).text()).kbByRoute.get("/:lang/memo")).toBe(120);
+    });
+  });
+
+  test("names each route over budget, its limit, and how to resolve it", () => {
+    expect(
+      RouteJsBudget.formatOverages(
+        [{ routeId: "/:lang/memo", brotliBytes: 128_000, budgetKB: 120, limitBytes: 126_976 }],
+        "apps/shop/akan.budget.json",
+        " (recorded for main, built for local)",
+      ),
+    ).toBe(
+      [
+        "1 route over the JS budget in apps/shop/akan.budget.json (recorded for main, built for local):",
+        "  /:lang/memo: 128,000 bytes brotli, over its limit of 126,976 (120KB + the larger of 1% and 4KB)",
+        "Shrink what the route loads. If the growth is intended, raise its entry by hand in the same change.",
+      ].join("\n"),
+    );
+  });
+});

package/routeJsBudget.ts

@@ -0,0 +1,222 @@
+import path from "node:path";
+import { toError } from "akanjs/common";
+import { FontPruner } from "./frontendBuild/fontPruner";
+import { JsonFormatter } from "./jsonFormatter";
+
+export interface RouteJsSize {
+  routeId: string;
+  files: number;
+  rawBytes: number;
+  brotliBytes: number;
+}
+
+export interface RouteJsOverage {
+  routeId: string;
+  brotliBytes: number;
+  budgetKB: number;
+  limitBytes: number;
+}
+
+export type RouteJsBudgetMode = "enforce" | "update" | "report" | "off";
+
+export interface RouteJsBudgetWarning {
+  file: string;
+  message: string;
+  fix: string;
+}
+
+export interface RouteJsBudgetStatus {
+  summary: string;
+  warnings?: RouteJsBudgetWarning[];
+}
+
+export interface RouteJsBudgetCheck {
+  mode: Exclude<RouteJsBudgetMode, "off">;
+  budgetPath: string;
+  source: string;
+  environment: string;
+}
+
+export class RouteJsBudget {
+  static readonly fileName = "akan.budget.json";
+  static readonly section = "routeJsBrotliKB";
+  static readonly tableRows = 10;
+  //? BundleSizeGate's slack: bundles inline `AKAN_PUBLIC_*`, so a local build measures over 1KB off a `--env main` one.
+  static readonly #relativeSlack = 0.01;
+  static readonly #absoluteSlack = 4096;
+
+  //? A file under 1 KB has no `.br` sidecar (precompressArtifacts skips it), so it is served, and counted, raw.
+  static async measure(artifactDir: string, modulesByRoute: Record<string, string[]>): Promise<RouteJsSize[]> {
+    const sizeByUrl = new Map<string, { raw: number; brotli: number }>();
+    const sizeOf = async (url: string) => {
+      const file = path.join(artifactDir, url.replace(/^\/_akan\//, ""));
+      const raw = Bun.file(file).size;
+      const sidecar = Bun.file(`${file}.br`);
+      return { raw, brotli: (await sidecar.exists()) ? sidecar.size : raw };
+    };
+    for (const url of new Set(Object.values(modulesByRoute).flat())) sizeByUrl.set(url, await sizeOf(url));
+    return Object.entries(modulesByRoute)
+      .map(([routeId, urls]) => ({
+        routeId,
+        files: urls.length,
+        rawBytes: urls.reduce((total, url) => total + (sizeByUrl.get(url)?.raw ?? 0), 0),
+        brotliBytes: urls.reduce((total, url) => total + (sizeByUrl.get(url)?.brotli ?? 0), 0),
+      }))
+      .sort((a, b) => b.brotliBytes - a.brotliBytes || RouteJsBudget.#byCodeUnit(a.routeId, b.routeId));
+  }
+
+  static async load(filePath: string, source = filePath): Promise<RouteJsBudget | null> {
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) return null;
+    return RouteJsBudget.parse(await file.text(), source);
+  }
+
+  //? `report` runs inside `akan verify`, where an overage or a broken file is no code error to fix in the edit loop.
+  static async check(
+    sizes: RouteJsSize[],
+    { mode, budgetPath, source, environment }: RouteJsBudgetCheck,
+  ): Promise<RouteJsBudgetStatus> {
+    const { committed, unreadable } = await RouteJsBudget.#loadFor(mode, budgetPath, source);
+    const budget = mode === "update" ? (committed ?? new RouteJsBudget()).tightenedBy(sizes, environment) : committed;
+    if (mode === "update" && budget) await Bun.write(budgetPath, budget.stringify());
+    const overages = budget?.overages(sizes) ?? [];
+    const envNote = committed?.envNote(environment) ?? "";
+    if (overages.length && mode !== "report") throw new Error(RouteJsBudget.formatOverages(overages, source, envNote));
+    const unbudgeted = budget?.unbudgeted(sizes).length ?? 0;
+    if (mode === "update") return { summary: `${source} ${unreadable ? `rewritten (${unreadable})` : "updated"}` };
+    if (unreadable)
+      return {
+        summary: `${unreadable}, not checked`,
+        warnings: [
+          {
+            file: source,
+            message: `${unreadable}; akan build fails on it`,
+            fix: "correct it, or rewrite it with akan build <app> --update-budget",
+          },
+        ],
+      };
+    if (!budget) return { summary: `no ${RouteJsBudget.fileName}` };
+    if (overages.length)
+      return {
+        summary: `${overages.length} route(s) over ${source}${envNote}, reported only: ${overages.map(({ routeId }) => routeId).join(", ")}`,
+        warnings: overages.map(({ routeId, brotliBytes, limitBytes }) => ({
+          file: source,
+          message: `${routeId} loads ${RouteJsBudget.#bytes(brotliBytes)} bytes brotli, over its limit of ${RouteJsBudget.#bytes(limitBytes)}${envNote}; akan build fails on it`,
+          fix: "shrink what the route loads, or raise its entry by hand in the same change",
+        })),
+      };
+    return { summary: `within ${source}${envNote}${unbudgeted ? `, ${unbudgeted} route(s) without an entry` : ""}` };
+  }
+
+  static async #loadFor(mode: RouteJsBudgetCheck["mode"], budgetPath: string, source: string) {
+    try {
+      return { committed: await RouteJsBudget.load(budgetPath, source), unreadable: null };
+    } catch (error) {
+      if (mode === "enforce") throw error;
+      return { committed: null, unreadable: toError(error).message.replace(/\.$/, "") };
+    }
+  }
+
+  static parse(text: string, source = RouteJsBudget.fileName): RouteJsBudget {
+    let json: unknown;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`${source} is not valid JSON.`);
+    }
+    const record =
+      typeof json === "object" && json !== null && !Array.isArray(json) ? (json as Record<string, unknown>) : {};
+    const section = record[RouteJsBudget.section];
+    const entries = typeof section === "object" && section !== null && !Array.isArray(section) ? section : null;
+    if (!entries || !Object.values(entries).every((kb) => Number.isInteger(kb) && (kb as number) > 0))
+      throw new Error(`${source}: "${RouteJsBudget.section}" maps each route id to a whole number of KB.`);
+    if (record.env !== undefined && typeof record.env !== "string")
+      throw new Error(`${source}: "env" names the environment the entries were measured for.`);
+    return new RouteJsBudget(new Map(Object.entries(entries as Record<string, number>)), record.env);
+  }
+
+  static kbOf(bytes: number) {
+    return Math.ceil(bytes / 1024);
+  }
+
+  static limitOf(budgetKB: number) {
+    const bytes = budgetKB * 1024;
+    return bytes + Math.max(Math.ceil(bytes * RouteJsBudget.#relativeSlack), RouteJsBudget.#absoluteSlack);
+  }
+
+  static formatTable(sizes: RouteJsSize[]): string[] {
+    const shown = sizes.slice(0, RouteJsBudget.tableRows);
+    const width = Math.max(...shown.map(({ routeId }) => routeId.length));
+    const { formatBytes } = FontPruner;
+    return [
+      "Route JS, largest first (brotli / raw):",
+      ...shown.map(
+        ({ routeId, brotliBytes, rawBytes }) =>
+          `  ${routeId.padEnd(width)}  ${formatBytes(brotliBytes).padStart(8)}  ${formatBytes(rawBytes).padStart(8)}`,
+      ),
+      ...(sizes.length > shown.length ? [`  …and ${sizes.length - shown.length} more`] : []),
+    ];
+  }
+
+  static formatOverages(overages: RouteJsOverage[], source: string, envNote = ""): string {
+    const bytes = RouteJsBudget.#bytes;
+    return [
+      `${overages.length} route${overages.length === 1 ? "" : "s"} over the JS budget in ${source}${envNote}:`,
+      ...overages.map(
+        ({ routeId, brotliBytes, budgetKB, limitBytes }) =>
+          `  ${routeId}: ${bytes(brotliBytes)} bytes brotli, over its limit of ${bytes(limitBytes)} (${budgetKB}KB + the larger of 1% and 4KB)`,
+      ),
+      "Shrink what the route loads. If the growth is intended, raise its entry by hand in the same change.",
+    ].join("\n");
+  }
+
+  static #bytes(value: number) {
+    return value.toLocaleString("en-US");
+  }
+
+  static #byCodeUnit(a: string, b: string) {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+
+  constructor(
+    readonly kbByRoute: ReadonlyMap<string, number> = new Map(),
+    readonly env?: string,
+  ) {}
+
+  overages(sizes: RouteJsSize[]): RouteJsOverage[] {
+    return sizes.flatMap(({ routeId, brotliBytes }) => {
+      const budgetKB = this.kbByRoute.get(routeId);
+      if (budgetKB === undefined) return [];
+      const limitBytes = RouteJsBudget.limitOf(budgetKB);
+      return brotliBytes > limitBytes ? [{ routeId, brotliBytes, budgetKB, limitBytes }] : [];
+    });
+  }
+
+  envNote(environment: string) {
+    return this.env && this.env !== environment ? ` (recorded for ${this.env}, built for ${environment})` : "";
+  }
+
+  unbudgeted(sizes: RouteJsSize[]): string[] {
+    return sizes.filter(({ routeId }) => !this.kbByRoute.has(routeId)).map(({ routeId }) => routeId);
+  }
+
+  tightenedBy(sizes: RouteJsSize[], env?: string): RouteJsBudget {
+    return new RouteJsBudget(
+      new Map(
+        sizes.map(({ routeId, brotliBytes }) => {
+          const measured = RouteJsBudget.kbOf(brotliBytes);
+          return [routeId, Math.min(this.kbByRoute.get(routeId) ?? measured, measured)];
+        }),
+      ),
+      env ?? this.env,
+    );
+  }
+
+  stringify(): string {
+    const entries = [...this.kbByRoute].sort(([a], [b]) => RouteJsBudget.#byCodeUnit(a, b));
+    return JsonFormatter.stringify(
+      { ...(this.env ? { env: this.env } : {}), [RouteJsBudget.section]: Object.fromEntries(entries) },
+      RouteJsBudget.fileName,
+    );
+  }
+}