@uxfront/layer-docs 0.2.1 → 0.4.0

package/storybook/index.ts

@@ -0,0 +1,362 @@
+/**
+ * `@uxfront/layer-docs/storybook` — the Storybook-side half of the docs embed
+ * contract.
+ *
+ * The docs page and the Storybook it embeds talk over `postMessage`, and they
+ * deploy independently. That makes the message names a contract between two
+ * repositories, so they live here — imported by both sides — rather than being
+ * retyped as string literals in a manager config, a preview config and a Vue
+ * component that can each drift on their own.
+ *
+ * This module is deliberately framework-free: no Vue, no Nuxt, no Storybook
+ * imports. It runs inside a Storybook manager or preview bundle, where none of
+ * those are guaranteed and the Storybook API surface differs per framework. The
+ * addon-specific work — flipping a dark-mode addon, updating a theme store —
+ * stays in the consumer's config and is reached through the `onTheme` callback.
+ *
+ * ## The two topologies
+ *
+ * A docs page embeds one of two Storybook surfaces, and the height signal takes
+ * a different route through each:
+ *
+ * - **`full` / `panel`** — the page embeds the Storybook *manager*
+ *   (`/?path=/story/…`). The preview iframe measures the story and posts
+ *   {@link DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE} up to the manager, which adds its
+ *   own chrome and padding and posts {@link DOCS_EMBED_HEIGHT_MESSAGE} to the
+ *   docs page.
+ * - **`preview`** — the page embeds `iframe.html` directly. No manager exists
+ *   to relay, so the component marks the URL with `{@link DOCS_EMBED_PARAM}=1`
+ *   and the preview bridge posts {@link DOCS_EMBED_HEIGHT_MESSAGE} straight to
+ *   its parent.
+ *
+ * Either way exactly one signal name reaches the docs page.
+ *
+ * ## The compat window
+ *
+ * A docs site that already ships its own branded message names sets
+ * `legacyNamespace`. Every bridge then **accepts both** names on the messages
+ * it receives and **emits both** on the messages it sends, so a stale deploy on
+ * either side keeps working. Handling is idempotent — the same theme or height
+ * applied twice is the same state — so a peer that understands both names
+ * simply acts on whichever arrives first with no visible difference.
+ *
+ * Drop the option once both sides are on the neutral names.
+ *
+ * @example Storybook manager config
+ * ```ts
+ * // .storybook/manager.ts
+ * import { installDocsEmbedManagerBridge } from "@uxfront/layer-docs/storybook";
+ *
+ * installDocsEmbedManagerBridge({
+ *   legacyNamespace: "acme",
+ *   onTheme: (theme) => applyManagerTheme(theme),
+ * });
+ * ```
+ *
+ * @example Storybook preview config
+ * ```ts
+ * // .storybook/preview.ts
+ * import { installDocsEmbedPreviewBridge } from "@uxfront/layer-docs/storybook";
+ *
+ * installDocsEmbedPreviewBridge({
+ *   legacyNamespace: "acme",
+ *   onTheme: (theme) => channel.emit(DARK_MODE_EVENT_NAME, theme === "dark"),
+ * });
+ * ```
+ */
+
+/** Docs page → Storybook: the colour mode the embedding page is displaying. */
+export const DOCS_EMBED_THEME_MESSAGE = "uxfront:docs-embed:theme";
+
+/** Storybook preview → Storybook manager: the measured height of the story. */
+export const DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE = "uxfront:docs-embed:preview-height";
+
+/** Storybook → docs page: the height the embedding iframe should be given. */
+export const DOCS_EMBED_HEIGHT_MESSAGE = "uxfront:docs-embed:height";
+
+/**
+ * URL flag the docs component appends when it embeds `iframe.html` directly.
+ * Its presence tells the preview bridge that no manager sits between it and the
+ * docs page, so it must post the final height itself.
+ */
+export const DOCS_EMBED_PARAM = "docsEmbed";
+
+/** Storybook's story container element in the preview iframe. */
+const STORYBOOK_ROOT_ID = "storybook-root";
+
+/** Storybook's preview iframe element inside the manager. */
+const STORYBOOK_PREVIEW_IFRAME_ID = "storybook-preview-iframe";
+
+/**
+ * Breathing room the manager adds around the measured story so the embedded
+ * frame does not clip against its own border.
+ */
+const DEFAULT_PADDING = 64;
+
+export type DocsEmbedTheme = "light" | "dark";
+
+/** Every message name accepted and emitted for one leg of the contract. */
+export interface DocsEmbedMessageNames {
+  /** Docs page → Storybook theme message. */
+  theme: readonly string[];
+  /** Preview → manager height message. */
+  previewHeight: readonly string[];
+  /** Storybook → docs page height message. */
+  height: readonly string[];
+}
+
+/**
+ * The message names in play, newest first.
+ *
+ * With no `legacyNamespace` that is one name per leg. With one — say `"acme"` —
+ * each leg also accepts and emits `acme:theme`, `acme:preview-height` and
+ * `acme:height`, which is the compat window described in the module docs.
+ */
+export function docsEmbedMessageNames(legacyNamespace?: string): DocsEmbedMessageNames {
+  const legacy = legacyNamespace?.trim();
+
+  if (!legacy) {
+    return {
+      theme: [DOCS_EMBED_THEME_MESSAGE],
+      previewHeight: [DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE],
+      height: [DOCS_EMBED_HEIGHT_MESSAGE],
+    };
+  }
+
+  return {
+    theme: [DOCS_EMBED_THEME_MESSAGE, `${legacy}:theme`],
+    previewHeight: [DOCS_EMBED_PREVIEW_HEIGHT_MESSAGE, `${legacy}:preview-height`],
+    height: [DOCS_EMBED_HEIGHT_MESSAGE, `${legacy}:height`],
+  };
+}
+
+/**
+ * Read a theme message, or `null` when the payload is not one of `names`.
+ *
+ * Anything that is not the string `"dark"` reads as `"light"`, matching how
+ * every receiver in the contract has always coerced it: a malformed payload
+ * lands on the default theme rather than throwing inside a message listener.
+ */
+export function readDocsEmbedTheme(data: unknown, names: readonly string[]): DocsEmbedTheme | null {
+  const message = asMessage(data);
+  if (!message || !names.includes(message.type)) return null;
+
+  return message.theme === "dark" ? "dark" : "light";
+}
+
+/**
+ * Read a height message, or `null` when the payload is not one of `names` or
+ * carries no usable height. Heights that are not finite positive numbers are
+ * rejected rather than written to a style attribute.
+ */
+export function readDocsEmbedHeight(data: unknown, names: readonly string[]): number | null {
+  const message = asMessage(data);
+  if (!message || !names.includes(message.type)) return null;
+
+  const { height } = message;
+  if (typeof height !== "number" || !Number.isFinite(height) || height <= 0) return null;
+
+  return height;
+}
+
+/**
+ * Height the manager reports for a story of `contentHeight`.
+ *
+ * `chromeHeight` is the manager UI wrapped around the preview — toolbar and
+ * addon panel — and is `0` in `full` mode, where none of it is visible.
+ */
+export function resolveDocsEmbedRelayHeight(options: {
+  contentHeight: number;
+  chromeHeight?: number;
+  padding?: number;
+}): number {
+  const { contentHeight, chromeHeight = 0, padding = DEFAULT_PADDING } = options;
+
+  return Math.max(0, chromeHeight) + contentHeight + padding;
+}
+
+export interface DocsEmbedManagerBridgeOptions {
+  /** Brand namespace to keep accepting and emitting during a migration. */
+  legacyNamespace?: string;
+  /** Padding added around the measured story. Defaults to 64. */
+  padding?: number;
+  /** Called with the theme the docs page is displaying. */
+  onTheme?: (theme: DocsEmbedTheme) => void;
+}
+
+/**
+ * Install the manager half: relay the docs page's theme down to the preview
+ * iframe, and relay the preview's measured height up to the docs page.
+ *
+ * Only relays height when the manager is itself framed — a Storybook opened
+ * directly has no docs page to report to. Returns a teardown function.
+ */
+export function installDocsEmbedManagerBridge(
+  options: DocsEmbedManagerBridgeOptions = {},
+): () => void {
+  const { legacyNamespace, padding = DEFAULT_PADDING, onTheme } = options;
+
+  const names = docsEmbedMessageNames(legacyNamespace);
+  const embedded = window !== window.parent;
+  const isFullMode = new URLSearchParams(window.location.search).has("full");
+
+  const onMessage = (event: MessageEvent) => {
+    const theme = readDocsEmbedTheme(event.data, names.theme);
+    if (theme) {
+      onTheme?.(theme);
+      const preview = previewIframe();
+      if (preview?.contentWindow) {
+        // Same document, so the origin is known — no reason to widen it to "*".
+        postAll(preview.contentWindow, names.theme, { theme }, window.location.origin);
+      }
+      return;
+    }
+
+    if (!embedded) return;
+
+    const contentHeight = readDocsEmbedHeight(event.data, names.previewHeight);
+    if (contentHeight === null) return;
+
+    let chromeHeight = 0;
+    if (!isFullMode) {
+      const preview = previewIframe();
+      // Chrome is measured, not assumed: without the preview element there is
+      // no honest number to send, so send nothing and keep the last height.
+      if (!preview) return;
+      chromeHeight = window.innerHeight - preview.offsetHeight;
+    }
+
+    const height = resolveDocsEmbedRelayHeight({ contentHeight, chromeHeight, padding });
+    postAll(window.parent, names.height, { height }, "*");
+  };
+
+  window.addEventListener("message", onMessage);
+
+  return () => window.removeEventListener("message", onMessage);
+}
+
+export interface DocsEmbedPreviewBridgeOptions {
+  /** Brand namespace to keep accepting and emitting during a migration. */
+  legacyNamespace?: string;
+  /**
+   * Extra height added when the docs page embeds this preview directly. Only
+   * applies to that topology; the manager owns padding in the relayed one.
+   */
+  padding?: number;
+  /** Called with the theme the docs page is displaying. */
+  onTheme?: (theme: DocsEmbedTheme) => void;
+}
+
+/**
+ * Install the preview half: receive the docs page's theme, and report the
+ * story's height to whichever parent is listening.
+ *
+ * Reports to the manager by default, or straight to the docs page when the URL
+ * carries {@link DOCS_EMBED_PARAM}. Returns a teardown function.
+ */
+export function installDocsEmbedPreviewBridge(
+  options: DocsEmbedPreviewBridgeOptions = {},
+): () => void {
+  const { legacyNamespace, padding = 0, onTheme } = options;
+
+  const names = docsEmbedMessageNames(legacyNamespace);
+  const teardown: Array<() => void> = [];
+
+  const onMessage = (event: MessageEvent) => {
+    const theme = readDocsEmbedTheme(event.data, names.theme);
+    if (theme) onTheme?.(theme);
+  };
+  window.addEventListener("message", onMessage);
+  teardown.push(() => window.removeEventListener("message", onMessage));
+
+  if (window !== window.parent) {
+    teardown.push(installHeightReporter(names, padding));
+  }
+
+  return () => {
+    for (const stop of teardown) stop();
+  };
+}
+
+/** Observe the story container and post its height whenever it changes. */
+function installHeightReporter(names: DocsEmbedMessageNames, padding: number): () => void {
+  const direct = new URLSearchParams(window.location.search).has(DOCS_EMBED_PARAM);
+  const target = direct ? names.height : names.previewHeight;
+
+  let lastHeight = 0;
+  const send = () => {
+    const root = document.getElementById(STORYBOOK_ROOT_ID);
+    if (!root) return;
+
+    // Through the manager, the relay re-measures the chrome around this exact
+    // box, so the story box is the right number. Embedded directly, the docs
+    // iframe shows this whole document — body padding included — so measure it.
+    const height = direct
+      ? Math.max(root.offsetHeight, document.documentElement.scrollHeight) + padding
+      : root.offsetHeight;
+
+    if (height === lastHeight) return;
+    lastHeight = height;
+    postAll(window.parent, target, { height }, "*");
+  };
+
+  let frame: number | undefined;
+  let resizeObserver: ResizeObserver | undefined;
+  let mutationObserver: MutationObserver | undefined;
+
+  const observe = () => {
+    const root = document.getElementById(STORYBOOK_ROOT_ID);
+    if (!root) {
+      // Storybook mounts the root asynchronously, and there is no event for it.
+      frame = requestAnimationFrame(observe);
+      return;
+    }
+
+    resizeObserver = new ResizeObserver(send);
+    resizeObserver.observe(root);
+    // A re-render that swaps content of the same height still changes what the
+    // story needs — the resize observer alone misses it.
+    mutationObserver = new MutationObserver(send);
+    mutationObserver.observe(root, { childList: true, subtree: true });
+    send();
+  };
+
+  if (document.readyState === "complete") {
+    observe();
+  } else {
+    window.addEventListener("load", observe);
+  }
+
+  return () => {
+    if (frame !== undefined) cancelAnimationFrame(frame);
+    window.removeEventListener("load", observe);
+    resizeObserver?.disconnect();
+    mutationObserver?.disconnect();
+  };
+}
+
+/** Post the same payload under every accepted name (the compat window). */
+function postAll(
+  target: Window,
+  names: readonly string[],
+  payload: Record<string, unknown>,
+  targetOrigin: string,
+): void {
+  for (const type of names) {
+    target.postMessage({ ...payload, type }, targetOrigin);
+  }
+}
+
+/** Narrow an untrusted `MessageEvent.data` to a typed message, or `null`. */
+function asMessage(data: unknown): { type: string; theme?: unknown; height?: unknown } | null {
+  if (typeof data !== "object" || data === null) return null;
+
+  const message = data as { type?: unknown; theme?: unknown; height?: unknown };
+  if (typeof message.type !== "string") return null;
+
+  return { type: message.type, theme: message.theme, height: message.height };
+}
+
+function previewIframe(): HTMLIFrameElement | null {
+  return document.getElementById(STORYBOOK_PREVIEW_IFRAME_ID) as HTMLIFrameElement | null;
+}

package/test/brand-palette.ts

@@ -0,0 +1,235 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Shared test preset for consumers of `@uxfront/layer-docs`.
+ *
+ * The layer ships a palette-free Tailwind base and expects the consumer to own
+ * the single Tailwind entry: one CSS file that imports the layer's base and
+ * then declares the brand `@theme`. Two invariants make that arrangement work,
+ * and both fail silently, so both get a guard here rather than a comment in
+ * three repos:
+ *
+ * 1. **The consumer's CSS entry is a Tailwind entry.** A `@theme` block only
+ *    compiles into real `:root` custom properties when the file it lives in is
+ *    part of a Tailwind pass. If it stops being one, the block ships to the
+ *    browser verbatim, browsers discard the unknown at-rule, and every
+ *    `*-primary` utility falls back to black/transparent site-wide.
+ *    Guarded by {@link describeBrandPaletteCss} — source-level, no build.
+ *
+ * 2. **Exactly one Tailwind pass reaches the bundle.** A second entry (a bare
+ *    `@import "tailwindcss"` in the consumer, or a layer that registers its own
+ *    base in `css:` alongside the consumer's) re-emits every base utility a
+ *    second time. Guarded by {@link describeSingleTailwindPass} — reads the
+ *    compiled output, so it needs a prior `nuxt build`.
+ *
+ * @example
+ * ```ts
+ * // apps/docs/test/brand-palette-css.test.ts
+ * import { describeBrandPaletteCss } from "@uxfront/layer-docs/test";
+ *
+ * describeBrandPaletteCss({
+ *   entry: new URL("../app/assets/css/main.css", import.meta.url),
+ *   scale: "teal",
+ * });
+ * ```
+ */
+
+/** Resolve a `file:` URL or a plain path to an absolute filesystem path. */
+function toPath(target: string | URL): string {
+  return typeof target === "string" ? target : fileURLToPath(target);
+}
+
+export interface BrandPaletteCssOptions {
+  /**
+   * The consumer's CSS entry — the file registered in `nuxt.config.ts`'s
+   * `css: []`. Pass `new URL("../app/assets/css/main.css", import.meta.url)`.
+   */
+  entry: string | URL;
+  /**
+   * Tailwind colour scale the brand palette defines, without the `--color-`
+   * prefix (`"teal"`, `"violet"`, `"purple"`). Must match `ui.colors.primary`
+   * in the consumer's `app.config.ts`.
+   */
+  scale: string;
+}
+
+/**
+ * Source-level guard for invariant 1: the brand palette compiles at all.
+ *
+ * Cheap — reads one file, runs in the default unit-test job, and catches the
+ * regression without a build. It cannot see invariant 2; that needs
+ * {@link describeSingleTailwindPass}.
+ */
+export function describeBrandPaletteCss(options: BrandPaletteCssOptions): void {
+  const { entry, scale } = options;
+
+  // A Tailwind pass reached via the layer's base CSS, which owns the single
+  // `@import "tailwindcss"`. Importing `tailwindcss` directly here would also
+  // make the file an entry, but it would open a SECOND pass — the exact
+  // regression invariant 2 guards — so only the layer import is accepted.
+  const LAYER_BASE_IMPORT = /@import\s+["']@uxfront\/layer-docs\/[^"']*main\.css["']/;
+
+  describe(`brand palette CSS entrypoint (${scale})`, () => {
+    const css = readFileSync(toPath(entry), "utf8");
+
+    it("imports the layer's base CSS so it is part of the single Tailwind pass", () => {
+      expect(css).toMatch(LAYER_BASE_IMPORT);
+    });
+
+    it("imports the layer base before the first @theme block", () => {
+      const importIndex = css.search(LAYER_BASE_IMPORT);
+      // Match the block opener specifically, not the `@theme` word in a
+      // leading docblock comment.
+      const themeIndex = css.search(/@theme\s+static\s*\{/);
+      expect(importIndex).toBeGreaterThanOrEqual(0);
+      expect(themeIndex).toBeGreaterThanOrEqual(0);
+      expect(importIndex).toBeLessThan(themeIndex);
+    });
+
+    it(`defines the ${scale} scale and maps it onto --ui-primary`, () => {
+      expect(css).toMatch(new RegExp(`@theme\\s+static\\s*\\{[\\s\\S]*--color-${scale}\\s*:`));
+      expect(css).toMatch(new RegExp(`--ui-primary\\s*:\\s*var\\(\\s*--color-${scale}\\s*\\)`));
+    });
+
+    // The OG card accent is resolved from this same declaration at build time
+    // (`utils/accent.ts`), because satori has no custom properties. The two
+    // assertions above already pin the declaration's existence; this one pins
+    // that it is *readable as a literal* — a value written as `var(...)` or a
+    // relative colour would parse here and then render as nothing in satori.
+    it(`declares --color-${scale} as a literal colour the OG renderer can use`, () => {
+      const declared = new RegExp(`--color-${scale}\\s*:\\s*([^;}]+)`).exec(css)?.[1]?.trim();
+      expect(declared).toBeDefined();
+      expect(declared).not.toMatch(/var\(|hsl\(\s*from|oklch\(\s*from|rgb\(\s*from/);
+    });
+  });
+}
+
+export interface SingleTailwindPassOptions {
+  /**
+   * Directory holding the built assets — usually
+   * `new URL("../.output/public/_nuxt", import.meta.url)`.
+   */
+  output: string | URL;
+  /**
+   * Tailwind colour scale the brand palette defines, without the `--color-`
+   * prefix. Asserts the palette survived into the compiled bundle.
+   */
+  scale: string;
+  /**
+   * Extra base utilities to assert on, appended to {@link BASE_UTILITIES}.
+   * Each entry is a full class selector, e.g. `".text-5xl"`.
+   */
+  utilities?: string[];
+}
+
+/**
+ * Ubiquitous unwrapped utilities the layer and Nuxt UI always emit. In a
+ * single-pass build each appears exactly once; a second pass makes them 2, and
+ * a bundle the layer base never reached makes them 0.
+ */
+const BASE_UTILITIES = [".relative", ".absolute", ".flex", ".grid", ".hidden", ".block"];
+
+/**
+ * Responsive utilities emitted inside `@media` blocks. Asserting these as well
+ * as {@link BASE_UTILITIES} is not redundancy — the two halves duplicate
+ * independently, and a base-only probe reports a duplicating build as clean.
+ *
+ * Measured on the same layer, same config, differing only in the Vite build
+ * used by `@nuxt/vite-builder`:
+ *
+ * | build            | `.flex` | `.lg\:hidden` |
+ * |------------------|---------|---------------|
+ * | rollup (vite 7)  | 2       | 2             |
+ * | rolldown         | 1       | **2**         |
+ * | single pass      | 1       | 1             |
+ *
+ * Rolldown collapses the duplicated top-level rules and leaves the `@media`-
+ * wrapped ones — so the consumer on rolldown still shipped ~63 KB of duplicate
+ * responsive CSS while every base-utility count read 1.
+ *
+ * All three are emitted by this layer's own components (`AppHeader`,
+ * `AppSubHeader`, `DocsAsideRightBottom`), so every consumer of the layer has
+ * them regardless of its own markup.
+ */
+const VARIANT_UTILITIES = [".lg\\:hidden", ".lg\\:block", ".max-lg\\:hidden"];
+
+/**
+ * Compiled-output guard for invariant 2: exactly one Tailwind pass in the
+ * shipped stylesheet.
+ *
+ * **What this guards is payload, not layout.** A second pass emits a
+ * byte-for-byte duplicate of the stylesheet — measured at +212 KB raw /
+ * +26.7 KB gzip (+94%) on a consumer's render-blocking `entry.css`, on every
+ * page for every visitor (UXF-118). It does *not*, on the evidence gathered
+ * there, break the cascade: the duplicate pass observed was a complete superset
+ * of the first and emitted wholly after it, so the last `sm:`/`lg:` variant
+ * still landed after the last conflicting base and won by source order.
+ * Computed-style A/B across 4 pages × 4 viewports found zero rendering
+ * difference.
+ *
+ * That rescue is incidental, not designed — a non-superset second pass, or a
+ * different emission order, and the cascade does break. But the guard should
+ * describe what it actually measures, so nobody re-derives a rendering
+ * emergency from a payload regression.
+ *
+ * Two deliberate choices in what it asserts:
+ *
+ * - **Both unwrapped and `@media`-wrapped utilities** ({@link BASE_UTILITIES}
+ *   and {@link VARIANT_UTILITIES}). They duplicate independently; a base-only
+ *   probe reported a duplicating build as clean.
+ * - **`=== 1`, not `<= 1`.** The same assertion then catches the opposite
+ *   failure — a consumer that never registered a CSS entry importing the layer
+ *   base, and so ships no utilities at all.
+ *
+ * Requires a prior `nuxt build` / `nuxt generate`. Keep these in
+ * `*.build.test.ts` files excluded from the default unit run.
+ */
+export function describeSingleTailwindPass(options: SingleTailwindPassOptions): void {
+  const { output, scale, utilities = [] } = options;
+
+  describe("compiled CSS: single Tailwind pass", () => {
+    const css = readEntryCss(toPath(output));
+    const assertedUtilities = [...BASE_UTILITIES, ...VARIANT_UTILITIES, ...utilities];
+
+    it("emits each utility exactly once (no duplicate Tailwind pass, and the layer base did reach the bundle)", () => {
+      const counts = Object.fromEntries(assertedUtilities.map((u) => [u, countUtility(css, u)]));
+      const expected = Object.fromEntries(assertedUtilities.map((u) => [u, 1]));
+      expect(counts).toEqual(expected);
+    });
+
+    it(`compiles the ${scale} scale and the --ui-primary mapping into the bundle`, () => {
+      expect(css).toMatch(new RegExp(`--color-${scale}\\s*:`));
+      expect(css).toMatch(new RegExp(`--ui-primary\\s*:\\s*var\\(\\s*--color-${scale}\\s*\\)`));
+    });
+  });
+}
+
+/** Read the built `entry.*.css`, comments stripped so counts reflect rules only. */
+function readEntryCss(outputDir: string): string {
+  if (!existsSync(outputDir)) {
+    throw new Error(
+      `Compiled output not found at ${outputDir}. Build the app first ` +
+        `(nuxt build) before running the compiled-output guard.`,
+    );
+  }
+  const entries = readdirSync(outputDir)
+    .filter((file) => /^entry\..*\.css$/.test(file))
+    .sort();
+  if (entries.length === 0) {
+    throw new Error(`No entry.*.css found in ${outputDir}. Build the app first (nuxt build).`);
+  }
+  return readFileSync(`${outputDir}/${entries.at(-1)}`, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+/** Count how many times a utility is emitted as its own class selector. */
+function countUtility(css: string, utility: string): number {
+  const escaped = utility.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // A leading `.` immediately followed by the class name, not part of a longer
+  // variant selector such as `.sm\:text-5xl` (there the class is preceded by an
+  // escaped colon, so `.text-5xl` never appears) and not a prefix of a longer
+  // utility such as `.flex-col`.
+  const pattern = new RegExp(`(?<![\\w\\\\:-])${escaped}(?![\\w-])`, "g");
+  return (css.match(pattern) ?? []).length;
+}