jamdesk 1.1.201 → 1.1.202

package/vendored/lib/snippet-compiler-isr.ts

@@ -6,6 +6,7 @@
  */
 
 import { transform } from '@babel/standalone';
+import { babelStripEventHandlers } from './strip-event-handlers';
 import { fetchSnippet } from './r2-content';
 
 interface CompiledSnippet {
@@ -52,7 +53,16 @@ export async function compileSnippetIsr(
   // Transpile JSX to JavaScript
   const transpiled = transform(source, {
     presets: ['react', 'typescript'],
-    plugins: [['transform-react-jsx', { runtime: 'automatic' }]],
+    // babelStripEventHandlers even though NOTHING calls compileSnippetIsr today
+    // (only clearSnippetCache/getSnippetCacheSize are imported elsewhere). This
+    // file is named as THE ISR snippet compiler, so it is exactly what someone
+    // reaches for next — and without the strip it silently reintroduces the
+    // HTTP 500 that lib/strip-event-handlers.ts exists to prevent. Two lines of
+    // insurance on a dead path beats rediscovering that incident.
+    plugins: [
+      babelStripEventHandlers,
+      ['transform-react-jsx', { runtime: 'automatic' }],
+    ],
     filename: snippetPath,
   });
 

package/vendored/lib/snippet-loader-isr.ts

@@ -19,12 +19,15 @@ import { injectPromptSources } from './inject-prompt-source';
 import { mdxSecurityOptions } from './mdx-security-options';
 import { remarkSvgNamespaceAttrs } from './remark-svg-namespace-attrs';
 import { remarkStyleStringToObject } from './remark-style-string-to-object';
+import { recmaStripEventHandlers, babelStripEventHandlers } from './strip-event-handlers';
 import {
   mdxEvalGuardPlugin,
   guardPropertyKey,
   KEY_GUARD_NAME,
   STRICT_MODE_PROLOGUE,
 } from './mdx-eval-guard';
+import { extractUtilityCandidates, MAX_UTILITY_CANDIDATES } from './user-utility-css';
+import { logger } from '../shared/logger';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type AnyComponent = React.ComponentType<any>;
@@ -32,6 +35,14 @@ type AnyComponent = React.ComponentType<any>;
 interface CompiledSnippet {
   exports: Record<string, AnyComponent>;
   isClientComponent: boolean;
+  /**
+   * Arbitrary-value Tailwind classes written in this snippet's own source.
+   * Carried on the compiled result so it rides the existing snippet cache —
+   * the classes an author writes live in the SNIPPET, not in the page that
+   * imports it, so a page-source-only scan would miss them entirely.
+   * See lib/user-utility-css.ts.
+   */
+  utilityCandidates: string[];
 }
 
 // In-memory cache for compiled snippet components
@@ -172,6 +183,12 @@ export function transpileJsx(source: string): string {
       // own identifiers, ahead of the JSX transform.
       mdxEvalGuardPlugin,
       onClickToHrefPlugin,
+      // The <span onClick={window.open}> → <a href> rewrite above keeps the
+      // author's navigation intent and always wins — it visits JSXElement,
+      // this visits the child JSXOpeningElement, and Babel reaches the parent
+      // first, so array order is not what decides it. Every handler that plugin
+      // does not claim is dropped here rather than 500-ing the including page.
+      babelStripEventHandlers,
       ['transform-react-jsx', { runtime: 'automatic', importSource: 'react' }],
     ],
     filename: 'snippet.tsx',
@@ -282,7 +299,13 @@ async function compilePlainMdxSnippet(
       // does on a page, and a snippet crash takes down every page that includes
       // it. The REHYPE pipeline is still deliberately omitted — see the note
       // above about D2 fences.
-      mdxOptions: { remarkPlugins: [remarkSvgNamespaceAttrs, remarkStyleStringToObject] },
+      // recmaStripEventHandlers for the same reason the page pipeline runs it:
+      // an author `on*` in a snippet is unserializable in RSC and 500s the
+      // whole page that includes it (see lib/strip-event-handlers.ts).
+      mdxOptions: {
+        remarkPlugins: [remarkSvgNamespaceAttrs, remarkStyleStringToObject],
+        recmaPlugins: [recmaStripEventHandlers],
+      },
     },
   });
   const PlainMdxSnippet: AnyComponent = () => content as React.ReactElement;
@@ -327,6 +350,7 @@ async function compileSnippet(
     const result: CompiledSnippet = {
       exports: { default: component },
       isClientComponent: false,
+      utilityCandidates: extractUtilityCandidates(source),
     };
     snippetComponentCache.set(cacheKey, { result, timestamp: Date.now() });
     return result;
@@ -378,7 +402,11 @@ async function compileSnippet(
     }
   }
 
-  const result: CompiledSnippet = { exports, isClientComponent };
+  const result: CompiledSnippet = {
+    exports,
+    isClientComponent,
+    utilityCandidates: extractUtilityCandidates(source),
+  };
 
   // Cache the result
   snippetComponentCache.set(cacheKey, { result, timestamp: Date.now() });
@@ -454,6 +482,71 @@ export async function loadSnippetsForIsr(
   return components;
 }
 
+/**
+ * Collect the arbitrary-value Tailwind classes used by a page — its own source
+ * plus every snippet it imports.
+ *
+ * Deliberately a separate pass rather than an extra return value from
+ * `loadSnippetsForIsr`: `compileSnippet` is cached per `project:path`, so by the
+ * time this runs during a page render every snippet is a cache hit and this
+ * costs a map lookup. Threading the candidates back through
+ * `loadSnippetsForIsr` would instead have changed a signature that
+ * `render-doc-page-parallel-helpers` and its tests both depend on.
+ *
+ * Never throws: a failure to collect styling candidates must not fail a render.
+ */
+export async function collectPageUtilityCandidates(
+  projectSlug: string,
+  mdxContent: string,
+  builtInComponents: Record<string, AnyComponent> = {},
+  // Snippet bodies live in R2, which only exists in ISR. Outside it every
+  // fetch here would throw from assertR2Configured and be swallowed below —
+  // dead work on the render critical path, and an R2-configured non-ISR
+  // environment would pull PRODUCTION snippet content into a local preview.
+  // The page's own source is still scanned either way, because the CLI dev
+  // workspace keeps project content outside the tree Tailwind scans, so
+  // skipping it would make dev render unstyled where prod renders correctly.
+  includeSnippets = true
+): Promise<string[]> {
+  const candidates = new Set<string>(extractUtilityCandidates(mdxContent));
+
+  if (includeSnippets) {
+    try {
+      const imports = extractSnippetImports(mdxContent);
+      await Promise.all(
+        imports.map(async (imp) => {
+          try {
+            const compiled = await compileSnippet(
+              projectSlug,
+              normalizeSnippetPath(imp.path),
+              builtInComponents
+            );
+            for (const c of compiled.utilityCandidates) candidates.add(c);
+          } catch {
+            // A snippet that fails to compile renders degraded anyway; its
+            // styling is not worth failing the page for.
+          }
+        })
+      );
+    } catch (error) {
+      // Not reachable today: extractSnippetImports and normalizeSnippetPath do
+      // not throw, and the Promise.all cannot reject because every element
+      // catches. Kept as a render-path guard — but logged, so a future change
+      // that does start throwing here is visible rather than silently costing
+      // every page its snippet styling.
+      logger.warn('[user-utility-css] snippet candidate scan failed', {
+        projectSlug,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  // The per-source cap inside extractUtilityCandidates does NOT bound this
+  // union: a page importing 10 snippets could otherwise reach the compiler with
+  // 10x the cap and build a cache key tens of KB long. Re-apply it to the merge.
+  return [...candidates].sort().slice(0, MAX_UTILITY_CANDIDATES);
+}
+
 /**
  * Clear the snippet component cache.
  */

package/vendored/lib/strip-event-handlers.ts

@@ -0,0 +1,159 @@
+import { visit } from 'estree-util-visit';
+import type { Program, Property } from 'estree-jsx';
+
+/**
+ * strip-event-handlers — removes author-written `on*` event-handler props from
+ * user MDX/JSX before it is rendered as a React Server Component.
+ *
+ * WHY this exists, and why it is NOT covered by the existing never-500 layers:
+ * a Server Component cannot pass a function across the RSC boundary. React
+ * throws `Event handlers cannot be passed to Client Component props` while
+ * SERIALIZING the flight payload — after every component has rendered
+ * successfully. That makes it invisible to both existing guards:
+ *
+ *   - `MdxRenderBoundary` (components/errors/MdxRenderBoundary.tsx) is a client
+ *     class boundary. It only catches throws during CLIENT render, so it cannot
+ *     stop a server-side serialization failure. The response is still HTTP 500.
+ *     Its `fallback` prop IS serialized alongside `children`, so the browser
+ *     shows "⚠ This content couldn't be displayed (page content)" while the
+ *     status is 500 — content degrades, the status does not.
+ *   - `recmaGuardExpressions` wraps author expressions in a try/catch IIFE, but
+ *     `onSubmit={() => …}` does not throw when EVALUATED — it returns a function
+ *     perfectly well. The guard hands that function straight to the serializer.
+ *
+ * So, exactly as the bare-`{x, y}` class before it, the only RSC-safe fix is to
+ * neutralize the construct at COMPILE time. Observed in production on
+ * 2026-08-31: one customer page rendering a snippet with `<form onSubmit={…}>`
+ * returned 500 for three weeks.
+ *
+ * WHAT is removed: any prop whose name matches `/^on[A-Z]/` — React's own
+ * event-handler naming convention, and the same test React applies when it
+ * decides a prop is an event handler. The element and all its other props and
+ * children render normally; only the dead handler goes. This loses nothing that
+ * ever worked: an author `on*` in server-rendered MDX has never been functional,
+ * it has only ever been a 500.
+ *
+ * Two plugins because user content reaches React down two different pipelines:
+ *   - `recmaStripEventHandlers` — the MDX compile path (page bodies and
+ *     plain-markdown snippets), operating on compiled `_jsx(tag, props)` calls.
+ *   - `babelStripEventHandlers` — the Babel path (`export`-style JSX snippets
+ *     and inline page components), operating on JSX attributes before the JSX
+ *     transform runs.
+ *
+ * RESIDUAL SCOPE — three shapes still reach the serializer and still 500. All
+ * three were reproduced against the real flight writer
+ * (`react-server-dom-webpack/server.edge` under `--conditions=react-server`):
+ *
+ *   1. A handler spread from an IDENTIFIER: `<form {...handlers} />`. Not
+ *      statically visible, so it survives. Note an object-LITERAL spread
+ *      (`<div {...{onClick: f}} />`) is NOT in this class — the MDX compiler
+ *      flattens it into the props ObjectExpression, where this plugin sees and
+ *      removes it like any other property.
+ *   2. A computed key: `<div {...{['on' + 'Click']: f}} />` — `propKeyName`
+ *      declines to guess at computed keys.
+ *   3. A function-valued prop whose name is NOT `on[A-Z]` — `render={() => …}`
+ *      or `children={() => …}`. These fail with a DIFFERENT React error
+ *      ("Functions cannot be passed directly to Client Components" /
+ *      "Functions are not valid as a child"), so they are a separate class
+ *      rather than a hole in this one. Stripping every function-valued prop
+ *      would close it, but would also strip callbacks that a purely
+ *      server-rendered inline component legitimately consumes without ever
+ *      serializing them — so that is deliberately NOT done here.
+ *
+ * None of the three has been observed in customer content; `on[A-Z]` is the
+ * shape authors actually reach for when they paste React into MDX.
+ */
+
+/**
+ * React's own rule for "this prop is an event handler": `on` followed by an
+ * uppercase letter. Deliberately NOT a fixed list of known DOM events — a
+ * custom `onFoo` on a component prop is just as unserializable as `onClick`,
+ * and a list would silently miss every event React adds later.
+ *
+ * The uppercase requirement is what keeps legitimate props safe: `once`, `only`
+ * and `onboarding` are ordinary words, not handlers.
+ */
+const EVENT_HANDLER_PROP = /^on[A-Z]/;
+
+export function isEventHandlerProp(name: string): boolean {
+  return EVENT_HANDLER_PROP.test(name);
+}
+
+/** JSX factory callees emitted by the MDX/React compilers. */
+const JSX_CALLEES = new Set(['_jsx', '_jsxs', '_jsxDEV']);
+
+/** The identifier/string name of a `_jsx` prop key (`onClick`, `data-v`, …). */
+function propKeyName(prop: Property): string | undefined {
+  const key = prop.key;
+  // A computed key (`{[expr]: fn}`) has no statically-known name, so it cannot
+  // be classified — left in place rather than guessed at.
+  if (prop.computed) return undefined;
+  if (key.type === 'Identifier') return key.name;
+  if (key.type === 'Literal' && typeof key.value === 'string') return key.value;
+  return undefined;
+}
+
+/**
+ * recma plugin — drops `on*` properties from every compiled `_jsx(tag, {…})`
+ * props object.
+ *
+ * Runs AFTER `recmaCompoundComponents` (so elements that plugin synthesizes are
+ * also cleaned) and BEFORE `recmaGuardExpressions` (no point wrapping an
+ * expression that is about to be deleted).
+ */
+export function recmaStripEventHandlers() {
+  return (tree: Program) => {
+    visit(tree, (node) => {
+      if (
+        node.type !== 'CallExpression' ||
+        node.callee.type !== 'Identifier' ||
+        !JSX_CALLEES.has(node.callee.name)
+      ) {
+        return;
+      }
+      const props = node.arguments[1];
+      if (!props || props.type !== 'ObjectExpression') return;
+
+      props.properties = props.properties.filter((prop) => {
+        // A SpreadElement here is an identifier spread (`{...handlers}`) — an
+        // object-literal spread was already flattened into this same properties
+        // list by the MDX compiler. Structural, so keep it (RESIDUAL SCOPE 1).
+        if (prop.type !== 'Property') return true;
+        const name = propKeyName(prop);
+        return !name || !isEventHandlerProp(name);
+      });
+    });
+  };
+}
+
+/**
+ * Babel plugin — drops `on*` JSX attributes before the JSX transform.
+ *
+ * Coexists with `onClickToHrefPlugin` in `transpileJsx`, which rewrites
+ * `<span onClick={() => window.open(url, '_self')}>` into `<a href>` to preserve
+ * the author's navigation intent. That rewrite always wins, and NOT because of
+ * plugin array order: it visits `JSXElement` while this visits the child
+ * `JSXOpeningElement`, and Babel reaches a parent before its child. Whatever it
+ * does not claim is stripped here instead of 500-ing. It is still listed after
+ * that plugin, so the guarantee survives if this ever moves to a `JSXElement`
+ * visitor.
+ */
+export function babelStripEventHandlers() {
+  return {
+    name: 'jd-strip-event-handlers',
+    visitor: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      JSXOpeningElement(path: any) {
+        path.node.attributes = path.node.attributes.filter(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (attr: any) =>
+            !(
+              attr.type === 'JSXAttribute' &&
+              attr.name?.type === 'JSXIdentifier' &&
+              isEventHandlerProp(attr.name.name)
+            ),
+        );
+      },
+    },
+  };
+}

package/vendored/lib/user-utility-css.ts

@@ -0,0 +1,250 @@
+import { stripFencedBlocks } from './preprocess-mdx';
+import { logger } from '../shared/logger';
+
+/**
+ * user-utility-css — generates CSS at render time for the Tailwind
+ * ARBITRARY-VALUE classes an author writes in their own MDX.
+ *
+ * WHY this is needed, and why only arbitrary values:
+ * Tailwind generates CSS for the class names it can see when the ISR app is
+ * BUILT. Customer MDX lives in R2 and is rendered long afterwards, so Tailwind
+ * never sees it. Standard utilities survive that gap by luck — `px-4`,
+ * `rounded-md`, `text-black` and friends are already in the bundle because a
+ * platform component happens to use them, and every standard class in the
+ * production customer page that prompted this was in fact present. Arbitrary
+ * values can NEVER survive it: `bg-[#ED8200]` has an infinite value space, so
+ * nothing can pre-generate it. That page rendered a `<button>` with padding and
+ * rounded corners and no background — it read as plain text.
+ *
+ * So this deliberately handles arbitrary values ONLY. That is not a shortcut:
+ * the utilities-only compiler entry used here provably CANNOT emit theme-backed
+ * utilities (`px-4` needs `--spacing`, `text-red-500` needs the color palette),
+ * and feeding it those candidates would burn work to produce nothing. Closing
+ * the standard-utility half is a different job — a build-time safelist — and is
+ * not needed while the bundle already covers them.
+ *
+ * WHY the output is safe to inject:
+ * Tailwind wraps its own output in `@layer utilities`, so a generated rule lands
+ * in exactly the layer it would have occupied had the build seen it. That
+ * matters here specifically: `app/globals.css` imports `themes/base.css`
+ * UNLAYERED, and unlayered rules beat layered ones regardless of specificity
+ * (see `components/mdx/markdown-classes.ts`). Emitting these rules unlayered
+ * would let an author's class silently outrank theme CSS. It does not.
+ */
+
+/**
+ * The whole stylesheet this compiles. Deliberately a literal with no `@import`:
+ * the compiler then never touches the filesystem, so nothing depends on
+ * Next.js tracing `node_modules/tailwindcss/*.css` into the serverless bundle
+ * (it traces JS imports, and a runtime `fs.readFile` is invisible to it — this
+ * would have failed in production and worked locally).
+ *
+ * The `@layer utilities` wrapper is ours rather than Tailwind's, and it is
+ * load-bearing — see the note on cascade layers in the file header.
+ *
+ * The `@theme` block declares ONLY breakpoints. Without it a responsive
+ * arbitrary value (`md:bg-[#ED8200]`) compiles to nothing and renders unstyled —
+ * failing exactly as silently as the bug this file exists to fix, since the
+ * variant needs `--breakpoint-*` to build its media query. Verified that adding
+ * it leaks no `:root` custom properties and no preflight into the output.
+ *
+ * These are Tailwind's defaults, duplicated here because the compiler gets no
+ * config. `tailwind.config.ts` does not override `screens`, and a test pins
+ * that — if it ever does, these must change with it.
+ *
+ * `@custom-variant dark` is the same problem, and it bites HARDER than the
+ * breakpoints did. `tailwind.config.ts` sets `darkMode: 'class'`, but the
+ * runtime compiler gets no config and so falls back to Tailwind's default
+ * `@media (prefers-color-scheme: dark)`. That does not merely fail to apply —
+ * it applies at the WRONG TIME: on the reader's OS preference rather than the
+ * site's theme toggle, so `dark:bg-[#0b0b0b]` would paint a dark background
+ * under light-theme text. Unlike every other gap in this file, that is worse
+ * than generating nothing. The selector below is byte-identical to what the
+ * build-time bundle emits (`dark\:hidden:is(.dark *)`), and a test pins the
+ * `darkMode` setting it mirrors.
+ *
+ * Nothing else from the theme is pulled in, which is why only arbitrary values
+ * can be generated.
+ */
+const UTILITIES_ENTRY = [
+  '@custom-variant dark (&:is(.dark *));',
+  '@theme {',
+  '  --breakpoint-sm: 40rem;',
+  '  --breakpoint-md: 48rem;',
+  '  --breakpoint-lg: 64rem;',
+  '  --breakpoint-xl: 80rem;',
+  '  --breakpoint-2xl: 96rem;',
+  '}',
+  '@layer utilities { @tailwind utilities; }',
+].join('\n');
+
+/**
+ * Class attributes in author MDX/JSX. Covers `class="…"`, `className="…"`,
+ * `className='…'` and `className={"…"}` / `{'…'}` / {`…`}. A className built
+ * from an expression is out of reach and is left alone — an author writing
+ * computed classes is already outside what a docs page can round-trip.
+ *
+ * Values deliberately allow newlines, because a formatted JSX `className`
+ * legitimately wraps across lines. The cost is that one unbalanced `class="` in
+ * prose would swallow everything up to the next quote anywhere in the document.
+ * That is bounded by truncating the captured VALUE (see MAX_ATTR_VALUE_LENGTH)
+ * rather than by bounding the regex: a bounded quantifier makes an over-long
+ * attribute fail to match AT ALL, so a page with a very long class list would
+ * silently get no styling instead of most of it.
+ */
+const CLASS_ATTR =
+  /(?<![-\w])class(?:Name)?\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*[`'"]([^`'"]*)[`'"]\s*\})/g;
+
+/** Caps: a page far past these is pathological, not authored. */
+export const MAX_UTILITY_CANDIDATES = 500;
+const MAX_CANDIDATE_LENGTH = 120;
+/**
+ * How much of one class attribute's value is scanned. Bounds a runaway match
+ * from an unbalanced quote while still letting a long-but-real class list
+ * contribute its leading classes — see the note on CLASS_ATTR.
+ */
+const MAX_ATTR_VALUE_LENGTH = 2000;
+
+/**
+ * A candidate must contain `[` to be worth compiling (see the file header), and
+ * must not carry characters that could break out of the `<style>` element it is
+ * injected into. Tailwind escapes its selectors and would reject these anyway,
+ * but rejecting them here means the guarantee does not depend on that.
+ */
+function isCompilableCandidate(token: string): boolean {
+  if (token.length > MAX_CANDIDATE_LENGTH) return false;
+  if (!token.includes('[')) return false;
+  return !/[<>"'`\s]/.test(token);
+}
+
+/**
+ * Pull arbitrary-value Tailwind candidates out of raw author source.
+ * Returns them sorted and de-duplicated so the cache key is stable.
+ */
+export function extractUtilityCandidates(source: string): string[] {
+  if (!source) return [];
+  const found = new Set<string>();
+
+  // A ```html fence demonstrating `class="bg-[#fff]"` is documentation, not
+  // markup to style. Uses the same strict fence regex the snippet-import
+  // scanner uses, so the two cannot disagree about what a code block is.
+  const scannable = stripFencedBlocks(source);
+
+  for (const match of scannable.matchAll(CLASS_ATTR)) {
+    const value = match[1] ?? match[2] ?? match[3];
+    if (!value) continue;
+    for (const token of value.slice(0, MAX_ATTR_VALUE_LENGTH).split(/\s+/)) {
+      if (isCompilableCandidate(token)) found.add(token);
+      if (found.size >= MAX_UTILITY_CANDIDATES) break;
+    }
+    if (found.size >= MAX_UTILITY_CANDIDATES) break;
+  }
+
+  return [...found].sort();
+}
+
+/**
+ * The entry above has no `@import`, `@plugin` or `@config`, so neither of the
+ * loaders Tailwind accepts is reachable. Both get this one, which throws rather
+ * than returning something empty so that a future edit which reintroduces a
+ * filesystem dependency fails loudly here instead of silently in production.
+ */
+async function refuseFilesystemLoad(): Promise<never> {
+  throw new Error('user-utility-css: the utilities entry must not load from disk');
+}
+
+/**
+ * Compiled-CSS cache, keyed by the exact candidate set.
+ *
+ * A Tailwind compiler ACCUMULATES candidates across `build()` calls — a second
+ * call still emits the first call's rules. Reusing one compiler across renders
+ * would therefore grow without bound and leak one project's classes into
+ * another project's page. So each distinct candidate set gets a FRESH compiler
+ * (~3ms) and only the finished CSS is cached.
+ */
+const cssCache = new Map<string, string>();
+const MAX_CACHE_ENTRIES = 500;
+
+/**
+ * Build the extra stylesheet for a page's arbitrary-value classes.
+ * Returns '' when there is nothing to generate.
+ */
+export async function buildUserUtilityCss(
+  candidates: string[]
+): Promise<string> {
+  if (candidates.length === 0) return '';
+
+  const key = candidates.join(' ');
+  const cached = cssCache.get(key);
+  if (cached !== undefined) return cached;
+
+  let css = '';
+  try {
+    // Imported lazily on purpose. Docs routes are force-dynamic, so a static
+    // import would pay Tailwind's ~23ms module load on EVERY cold start —
+    // including the majority of pages that carry no arbitrary-value class at
+    // all. The empty-candidates early return above means reaching this line
+    // already means there is real work to do.
+    const { compile } = await import('tailwindcss');
+    const compiler = await compile(UTILITIES_ENTRY, {
+      // Only ever used to resolve relative @imports, of which the entry has
+      // none. Pinned rather than process.cwd() so this cannot acquire a
+      // dependency on where the server happens to be started from.
+      base: '/',
+      loadStylesheet: refuseFilesystemLoad,
+      loadModule: refuseFilesystemLoad,
+    });
+    css = compiler.build(candidates);
+    // When nothing matched, Tailwind still emits a banner plus a bare
+    // `@layer utilities;` DECLARATION (semicolon, no block). Testing for the
+    // string '@layer' would pass on that and ship an empty <style>; the brace
+    // is what distinguishes a real rule block.
+    if (!/@layer[^;{]*\{/.test(css)) {
+      // Candidates existed but Tailwind matched none of them. Logged because
+      // this is otherwise INDISTINGUISHABLE from a page that simply has no
+      // arbitrary classes — both are an empty string and no log line. That is
+      // precisely how the responsive-variant gap (`md:bg-[#ED8200]` emitting
+      // nothing without `--breakpoint-*`) hid: the failure state was an
+      // ABSENCE of output, so nothing could alert on it. A future Tailwind
+      // upgrade or a new variant form that stops compiling now says so.
+      logger.warn('[user-utility-css] candidates matched no utilities', {
+        count: candidates.length,
+        sample: candidates.slice(0, 5),
+      });
+      css = '';
+    }
+    // Defence in depth for the `<style>` element this is injected into.
+    // `isCompilableCandidate` already rejects `<`, `>` and quotes, and Tailwind
+    // escapes what it emits — so reaching this branch should be impossible.
+    // Dropping the whole sheet rather than patching it keeps that an assertion
+    // instead of a sanitizer: a cosmetic loss, never a broken page.
+    if (/<\/|<!/.test(css)) {
+      logger.error('[user-utility-css] generated CSS contained markup; discarding');
+      css = '';
+    }
+  } catch (error) {
+    // Never let author styling break a page render — a missing background is a
+    // cosmetic loss, a throw here would be a 500.
+    logger.error('[user-utility-css] failed to compile author utilities', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    // Deliberately NOT cached. A thrown compile is the one outcome here that
+    // can be transient, and caching it would pin this page unstyled for the
+    // life of the process — silently, because the cache is checked before the
+    // logger, so it would never complain again. The empty result from the
+    // brace test above IS cached: that one is deterministic.
+    return '';
+  }
+
+  if (cssCache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = cssCache.keys().next().value;
+    if (oldest !== undefined) cssCache.delete(oldest);
+  }
+  cssCache.set(key, css);
+  return css;
+}
+
+/** Test seam — the cache is process-global and would otherwise leak between tests. */
+export function __clearUserUtilityCssCache(): void {
+  cssCache.clear();
+}