ci: budget the browser bundle size (#81)

Nothing measured dist/browser.js, the single CDN script every htmdx
artifact loads before it renders. The two hand-maintained figures in the
READMEs had already drifted apart and away from reality: ~145KB and
~147KB gzip documented against 156,247 measured.

The build now measures the written bundle against a committed budget and
fails when it grows past the ceiling. Raising a limit stays allowed, but
it happens in the diff with a stated reason instead of silently between
releases.

Author: vltansky

README.md

@@ -298,7 +298,7 @@ The authoring guidance ships with the runtime and is printed by `htmdx skill`, s
 
 ## Package
 
-- npm: `@wix/htmdx` · CDN entry: `dist/browser.js` (~145KB gzip) · module entries: `.`, `./react`, `./testing`, `./components`, `./components/builtins`, `./components/shadcn`
+- npm: `@wix/htmdx` · CDN entry: `dist/browser.js` (under 160KB gzip, [budgeted in CI](./packages/htmdx/build/bundle-budget.json)) · module entries: `.`, `./react`, `./testing`, `./components`, `./components/builtins`, `./components/shadcn`
 - custom element: `<htmdx-code>` · browser API: `window.Htmdx`
 - linting: [`validate()`](#validation-and-linting) · CLI: [`lint`, `compile`, `components`](#command-line) — `npx @wix/htmdx lint <files...>`
 - component contract: `dist/components.json`

adr/budget-the-browser-bundle-size.md

@@ -0,0 +1,112 @@
+# Budget the browser bundle size in CI
+
+- Status: proposed
+- Date: 2026-07-27
+
+## Context
+
+Every htmdx artifact is a plain HTML file whose only runtime is one CDN script,
+`dist/browser.js`. That bundle carries React, the built-in catalog, the shadcn/ui
+pack, and the theme, so it is the entire loading cost of an artifact and the one
+number that decides how a document feels when it opens.
+
+Nothing measures it. The build has an assertion plugin
+(`build/production-bundle-validation.js`) that rejects development artifacts in the
+bundle, but nothing observes how large the bundle is. `bench/` measures token cost
+of htmdx source against other formats; CI does not run it, and it says nothing about
+bytes.
+
+The absence is already visible. `README.md` documents the CDN entry as `~145KB
+gzip` and `packages/htmdx/README.md` says `~147KB gzip`; the published 4.10.0
+bundle is 519,890 bytes raw and 155,117 bytes gzipped. Two hand-maintained numbers
+disagree with each other and both understate reality, because nothing recomputes
+them and nothing fails when they drift.
+
+The growth vectors are ordinary work, not mistakes: a new built-in component, a
+Radix or `lucide-react` bump, a theme addition. Each is individually reasonable and
+none of them surface a size delta today.
+
+## Decision
+
+The build measures `dist/browser.js` and fails when it exceeds a committed budget.
+
+A pure helper, `build/bundle-budget.js`, takes measured byte counts and a budget and
+throws a message naming the file, the metric, the overage in bytes and percent, and
+the budget it exceeded. It follows `build/production-bundle-validation.js`: plain JS
+next to the build, no bundler coupling, unit-tested from `test/` over fixture inputs
+rather than over a real build.
+
+The vite browser config invokes it after the bundle is written, so the check sees the
+bytes that actually ship, sourcemap comment included. A breach fails
+`build:browser`, which fails `build:library`, which fails both CI jobs — the
+`test` job runs `yarn build` and the `e2e` job runs `yarn workspace @wix/htmdx
+build:library`.
+
+Two metrics are gated: raw bytes, which track parse and evaluation cost, and gzip at
+a pinned zlib level, which tracks transfer and is the unit the documentation and the
+ecosystem quote. Brotli is not measured at all. It is closer to what a CDN actually
+sends, but it moves with gzip, so gating it adds no signal, and compressing this
+bundle at brotli's default quality costs 772ms against gzip's 11ms — too much to
+spend on every build for a number nothing acts on.
+
+The budget lives in `build/bundle-budget.json` as a limit per metric plus a `note`
+recording what the limits were set from and why they last moved. Raising a limit is a
+normal, allowed act — the point is that it happens in the diff, under review, with a
+stated reason, instead of silently between releases.
+
+The gzip limit is 160 KiB exactly rather than a percentage above the measured size,
+because the README quotes it. A ceiling is a claim that stays true until the budget
+itself changes; a measured point value is a claim that goes stale on the next commit.
+
+Both README size figures are restated as that enforced ceiling and point at the
+budget file.
+
+## Alternatives
+
+- **`size-limit` with `@size-limit/file`** (v13.0.1, actively released). The
+  ecosystem default, and it adds estimated download time on a slow connection for
+  free. Rejected on fit: it brings two devDependencies and a separate CI step to
+  produce a number that `node:zlib` produces in roughly forty lines, its presets
+  earn their keep on multi-entry and code-split bundles rather than on a single
+  IIFE, and it would sit beside the existing build-assertion seam instead of
+  reusing it. This repo runs `knip` and `syncpack` over its dependency surface;
+  paying two dependencies to avoid one small file is the wrong trade here.
+- **Report the size without failing.** Zero friction, and precisely the regime that
+  produced two wrong numbers in the README. A number nobody is required to look at
+  does not prevent drift.
+- **Comment the size delta against the base branch on each PR.** Better ergonomics
+  than a hard failure, but it needs write-token plumbing, and fork PRs get nothing
+  — the same constraint that already excludes forks from the preview workflow. It
+  is an addition to a working gate, not a replacement for one.
+- **Measure in-browser time to `htmdx:ready` in the existing Playwright suite.**
+  Closer to what a reader experiences, and deferred rather than rejected. Wall-clock
+  timing on shared GitHub runners is noisy enough that the threshold has to be loose
+  enough to miss real regressions, and for a single blocking CDN script bytes are
+  the dominant term. Bytes first; timing when there is a question bytes cannot
+  answer.
+- **Budget every `dist/*.js` entry.** The other entries are consumed through a
+  bundler that tree-shakes them, so their raw size is a weak proxy for what a
+  consumer pays. Scoped out deliberately.
+
+## Consequences
+
+Growing the artifact runtime becomes a visible act. Dependency bumps and new
+built-ins that push past the ceiling fail CI and require the author to either reduce
+the growth or raise the budget with a reason in the same PR. The repo has no
+Renovate or Dependabot configuration, so bumps are deliberate and infrequent; the
+expected rate of budget conversations is low.
+
+The gated numbers are computed with `node:zlib` at a pinned level. They will not
+match byte-for-byte what unpkg or jsdelivr serve, which use their own compression
+settings. This is acceptable because the budget is a regression guardrail: it needs
+to be deterministic and to move with real size, not to equal a CDN's output. The
+budget file records the compression settings so the figure is never mistaken for a
+transfer guarantee.
+
+The budget can be rubber-stamped. Nothing prevents raising it reflexively, and the
+mitigation is social — the delta and the reason are in the diff. This is a speed
+bump on unnoticed growth, not a lock on the bundle size.
+
+Turbo caches the `build` task with `dist/**` as its output. A cache hit skips the
+check, but a hit means the inputs were identical, so the size is identical. No
+enforcement is lost.

packages/htmdx/README.md

@@ -389,8 +389,12 @@ The standard runtime script gives an artifact the full catalog:
 
 `dist/browser.js` bundles React, the built-in catalog (ExecutiveSummary,
 MetricStrip, charts, ...), the shadcn/ui pack (Card, Badge, Button, Tabs,
-Accordion), and the shadcn theme (~147KB gzip, including the static-render
-path that powers `compile()`).
+Accordion), and the shadcn theme, including the static-render path that powers
+`compile()`. It stays under 160KB gzip: the build measures the written bundle
+against
+[`build/bundle-budget.json`](https://github.com/wix-incubator/htmdx/blob/master/packages/htmdx/build/bundle-budget.json)
+and fails when it grows past the ceiling, so the figure cannot drift without a
+reviewed change to the budget.
 
 Authoring htmdx source instead of rendered markup is measurably cheaper for
 agents: the full single-file artifact is about 4.3x smaller in tokens than the

packages/htmdx/build/bundle-budget.d.ts

@@ -0,0 +1,20 @@
+export type BundleSizes = {
+  raw: number;
+  gzip: number;
+};
+
+export declare function measureBundle(contents: Uint8Array): BundleSizes;
+export declare function checkBudgetCoverage(
+  budgetedFileNames: readonly string[],
+  emittedFileNames: readonly string[],
+): void;
+export declare function formatBundleSizes(
+  fileName: string,
+  sizes: BundleSizes,
+  limits: BundleSizes,
+): string;
+export declare function checkBundleBudget(
+  fileName: string,
+  sizes: BundleSizes,
+  limits: BundleSizes,
+): void;

packages/htmdx/build/bundle-budget.js

@@ -0,0 +1,71 @@
+import { gzipSync } from 'node:zlib';
+
+// Pinned so the number is reproducible across machines and Node releases. It is
+// not what a CDN serves - unpkg and jsdelivr compress with their own settings -
+// and it does not have to be. The budget guards against growth, so the metric
+// only has to be deterministic and to move with the real size.
+const GZIP_LEVEL = 9;
+
+const METRIC_LABELS = {
+  raw: 'raw',
+  gzip: `gzip (zlib level ${GZIP_LEVEL})`,
+};
+
+export function measureBundle(contents) {
+  return {
+    raw: contents.length,
+    gzip: gzipSync(contents, { level: GZIP_LEVEL }).length,
+  };
+}
+
+export function formatBundleSizes(fileName, sizes, limits) {
+  const parts = Object.keys(METRIC_LABELS).map((metric) => {
+    const used = Math.round((sizes[metric] / limits[metric]) * 100);
+    return `${metric} ${bytes(sizes[metric])} (${used}% of ${bytes(limits[metric])})`;
+  });
+
+  return `${fileName}: ${parts.join(', ')}`;
+}
+
+// A budget keyed on a file the build no longer emits enforces nothing, and it
+// does it silently: the build stays green while the gate is gone. Renaming an
+// output has to fail loudly rather than switch the check off.
+export function checkBudgetCoverage(budgetedFileNames, emittedFileNames) {
+  const emitted = new Set(emittedFileNames);
+  const missing = [...budgetedFileNames].filter((fileName) => !emitted.has(fileName));
+
+  if (!missing.length) {
+    return;
+  }
+
+  throw new Error(
+    `build/bundle-budget.json budgets a file the build did not emit: ${missing.join(', ')}. ` +
+      `The build emitted: ${emittedFileNames.join(', ') || '(nothing)'}. ` +
+      'Point the budget at the current output name, or the size gate silently stops running.',
+  );
+}
+
+export function checkBundleBudget(fileName, sizes, limits) {
+  const breaches = Object.entries(METRIC_LABELS)
+    .filter(([metric]) => sizes[metric] > limits[metric])
+    .map(([metric, label]) => {
+      const over = sizes[metric] - limits[metric];
+      const percent = ((over / limits[metric]) * 100).toFixed(1);
+      return `${label}: ${bytes(sizes[metric])} bytes, ${bytes(over)} over the ${bytes(limits[metric])} budget (+${percent}%)`;
+    });
+
+  if (!breaches.length) {
+    return;
+  }
+
+  throw new Error(
+    `${fileName} exceeds its size budget:\n\n- ${breaches.join('\n\n- ')}\n\n` +
+      'Every htmdx artifact loads this bundle from a CDN, so the growth is paid on ' +
+      'every page open. Either bring it back under the budget, or raise the limit in ' +
+      'build/bundle-budget.json and record why in its note - in this change, not later.',
+  );
+}
+
+function bytes(value) {
+  return value.toLocaleString('en-US');
+}

packages/htmdx/build/bundle-budget.json

@@ -0,0 +1,10 @@
+{
+  "$comment": "Size ceilings for the bundle a browser downloads. Enforced by vite.browser.config.ts on every build:browser, so a breach fails CI. Raising a limit is allowed - record why in its note, in the same change. Bytes, measured on the written file; gzip is node:zlib at level 9, which is not what a CDN serves and does not need to be.",
+  "files": {
+    "browser.js": {
+      "raw": 550000,
+      "gzip": 163840,
+      "note": "Set from 4.10.0, which measured 521,378 raw and 156,247 gzip. The gzip limit is 160 KiB exactly, because README.md quotes it as the enforced ceiling."
+    }
+  }
+}

packages/htmdx/test/build-bundle-budget.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'vitest';
+import {
+  type BundleSizes,
+  checkBudgetCoverage,
+  checkBundleBudget,
+  formatBundleSizes,
+  measureBundle,
+} from '../build/bundle-budget.js';
+
+const LIMITS: BundleSizes = { raw: 500_000, gzip: 150_000 };
+
+describe('bundle budget build validation', () => {
+  test('accepts a bundle under both limits', () => {
+    expect(() =>
+      checkBundleBudget('browser.js', { raw: 499_999, gzip: 149_999 }, LIMITS),
+    ).not.toThrow();
+  });
+
+  test('accepts a bundle exactly at its limits', () => {
+    expect(() => checkBundleBudget('browser.js', { ...LIMITS }, LIMITS)).not.toThrow();
+  });
+
+  test('rejects a bundle over the raw limit alone', () => {
+    expect(() => checkBundleBudget('browser.js', { raw: 500_001, gzip: 149_999 }, LIMITS)).toThrow(
+      'raw',
+    );
+  });
+
+  test('rejects a bundle over the gzip limit alone', () => {
+    expect(() => checkBundleBudget('browser.js', { raw: 499_999, gzip: 150_001 }, LIMITS)).toThrow(
+      'gzip',
+    );
+  });
+
+  test('names the offending file', () => {
+    expect(() => checkBundleBudget('browser.js', { raw: 600_000, gzip: 150_000 }, LIMITS)).toThrow(
+      'browser.js',
+    );
+  });
+
+  test('reports the overage in bytes and percent', () => {
+    let message = '';
+    try {
+      checkBundleBudget('browser.js', { raw: 550_000, gzip: 150_000 }, LIMITS);
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toContain('50,000 over the 500,000 budget');
+    expect(message).toContain('+10.0%');
+  });
+
+  test('reports every breach in one failure, and how to resolve it', () => {
+    let message = '';
+    try {
+      checkBundleBudget('browser.js', { raw: 600_000, gzip: 160_000 }, LIMITS);
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toContain('raw');
+    expect(message).toContain('gzip');
+    expect(message).toContain('build/bundle-budget.json');
+  });
+
+  test('measures raw bytes and a smaller gzip figure', () => {
+    const sizes = measureBundle(Buffer.from('htmdx'.repeat(1000)));
+
+    expect(sizes.raw).toBe(5000);
+    expect(sizes.gzip).toBeGreaterThan(0);
+    expect(sizes.gzip).toBeLessThan(sizes.raw);
+  });
+
+  test('accepts a budget whose files the build emitted', () => {
+    expect(() =>
+      checkBudgetCoverage(['browser.js'], ['browser.js', 'browser.js.map']),
+    ).not.toThrow();
+  });
+
+  test('rejects a budget keyed on a file the build no longer emits', () => {
+    let message = '';
+    try {
+      checkBudgetCoverage(['browser.js'], ['runtime.js']);
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toContain('browser.js');
+    expect(message).toContain('runtime.js');
+    expect(message).toContain('silently stops running');
+  });
+
+  test('formats each metric against the share of budget it uses', () => {
+    expect(formatBundleSizes('browser.js', { raw: 250_000, gzip: 75_000 }, LIMITS)).toBe(
+      'browser.js: raw 250,000 (50% of 500,000), gzip 75,000 (50% of 150,000)',
+    );
+  });
+});