@mui/internal-docs-infra 0.12.1-canary.31 → 0.12.1-canary.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.12.1-canary.31",
+  "version": "0.12.1-canary.33",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -804,5 +804,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "7d0cdc53fd9c01aaf49798a4e8e30e6ffea53022"
+  "gitSha": "adffaff76b0a500634bfdd5960365616eb6d2137"
 }

package/pipeline/cacheUtils/constants.d.mts

@@ -2,4 +2,14 @@
  * Default root directory for docs-infra build caches. Sits alongside the marker
  * directories already written under `.next/cache/docs-infra`.
  */
-export declare const DEFAULT_CACHE_DIR = ".next/cache/docs-infra";
+export declare const DEFAULT_CACHE_DIR = ".next/cache/docs-infra";
+/**
+ * Version of the shape of cached *output*. Entries are validated by hashing their inputs, so a
+ * pipeline change that alters the output for unchanged input is invisible to that hash — and
+ * `.next/cache` survives between builds (`@mui/internal-netlify-cache` restores it), so a warm
+ * cache would keep serving output produced by the previous code.
+ *
+ * Bump this whenever such a change lands. Caches whose stored shape can change fold it into their
+ * `getCacheContent`, which makes existing entries hash as stale and be recomputed in place.
+ */
+export declare const CACHE_SCHEMA_VERSION = 1;

package/pipeline/cacheUtils/constants.mjs

@@ -2,4 +2,15 @@
  * Default root directory for docs-infra build caches. Sits alongside the marker
  * directories already written under `.next/cache/docs-infra`.
  */
-export const DEFAULT_CACHE_DIR = '.next/cache/docs-infra';
+export const DEFAULT_CACHE_DIR = '.next/cache/docs-infra';
+
+/**
+ * Version of the shape of cached *output*. Entries are validated by hashing their inputs, so a
+ * pipeline change that alters the output for unchanged input is invisible to that hash — and
+ * `.next/cache` survives between builds (`@mui/internal-netlify-cache` restores it), so a warm
+ * cache would keep serving output produced by the previous code.
+ *
+ * Bump this whenever such a change lands. Caches whose stored shape can change fold it into their
+ * `getCacheContent`, which makes existing entries hash as stale and be recomputed in place.
+ */
+export const CACHE_SCHEMA_VERSION = 1;

package/pipeline/cacheUtils/index.d.mts

@@ -5,5 +5,5 @@ export { saveFileCache } from "./saveFileCache.mjs";
 export { resolveCachePath } from "./resolveCachePath.mjs";
 export { withFileCache } from "./withFileCache.mjs";
 export type { FileCacheTask } from "./withFileCache.mjs";
-export { DEFAULT_CACHE_DIR } from "./constants.mjs";
+export { DEFAULT_CACHE_DIR, CACHE_SCHEMA_VERSION } from "./constants.mjs";
 export type { FileCacheRef, FileCacheEntry } from "./types.mjs";

package/pipeline/cacheUtils/index.mjs

@@ -4,4 +4,4 @@ export { loadFileCacheEntry } from "./loadFileCacheEntry.mjs";
 export { saveFileCache } from "./saveFileCache.mjs";
 export { resolveCachePath } from "./resolveCachePath.mjs";
 export { withFileCache } from "./withFileCache.mjs";
-export { DEFAULT_CACHE_DIR } from "./constants.mjs";
+export { DEFAULT_CACHE_DIR, CACHE_SCHEMA_VERSION } from "./constants.mjs";

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.mjs

@@ -2,6 +2,7 @@ import { getHastTextContent } from "../loadServerTypes/hastTypeUtils.mjs";
 import { calculateFrameRanges } from "../parseSource/calculateFrameRanges.mjs";
 import { calculateFrameIndent } from "./calculateFrameIndent.mjs";
 import { restructureFrames } from "../parseSource/restructureFrames.mjs";
+import { hasClassName } from "../parseSource/isFrameSpan.mjs";
 /**
  * The prefix used to identify emphasis comments in source code.
  * Comments starting with this prefix will be processed for emphasis.
@@ -494,7 +495,7 @@ function buildLineElementMap(node) {
       }
 
       // Check if this is a line element
-      if (child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+      if (child.tagName === 'span' && hasClassName(child, 'line') && typeof child.properties.dataLn === 'number') {
         map.set(child.properties.dataLn, child);
       }
 
@@ -530,9 +531,10 @@ function isCommentOnlyLine(lineElement, commentText) {
         hasNonWhitespaceContent = true;
       }
     } else if (child.type === 'element') {
-      const className = child.properties?.className;
-      const classNames = Array.isArray(className) ? className : [className];
-      if (classNames.includes('pl-c')) {
+      // Read once: this runs per token span, and both branches below test the
+      // same list.
+      const classNames = child.properties?.className;
+      if (classNames?.includes('pl-c')) {
         // This is a comment element - check if it contains the expected text
         const text = getHastTextContent(child);
         if (text.includes(commentText)) {
@@ -541,7 +543,7 @@ function isCommentOnlyLine(lineElement, commentText) {
           // Some other comment
           hasNonWhitespaceContent = true;
         }
-      } else if (classNames.includes('pl-pse')) {
+      } else if (classNames?.includes('pl-pse')) {
         // This is punctuation for special expressions (JSX braces for comments)
         // Check if it's just `{` or `}` which are used for JSX comment syntax
         const text = getHastTextContent(child);
@@ -1108,7 +1110,7 @@ function applyEmphasisAndCollectHighlightedElements(node, emphasizedLines, optio
       }
 
       // Check if this is a line element
-      if (child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+      if (child.tagName === 'span' && hasClassName(child, 'line') && typeof child.properties.dataLn === 'number') {
         const lineNumber = child.properties.dataLn;
         const meta = emphasizedLines.get(lineNumber);
         if (meta !== undefined) {
@@ -1242,7 +1244,7 @@ function reconcileLineAndFrameEmphasis(root, emphasizedLines) {
     const frameType = frame.properties?.dataFrameType;
     const isHighlightedFrame = frameType === 'highlighted' || frameType === 'highlighted-unfocused';
     for (const child of frame.children) {
-      if (child.type !== 'element' || child.tagName !== 'span' || child.properties?.className !== 'line' || typeof child.properties.dataLn !== 'number') {
+      if (child.type !== 'element' || child.tagName !== 'span' || !hasClassName(child, 'line') || typeof child.properties.dataLn !== 'number') {
         continue;
       }
       const meta = emphasizedLines.get(child.properties.dataLn);

package/pipeline/loadIsomorphicCodeVariant/applyCodeTransformWithComments.mjs

@@ -10,7 +10,7 @@
 
 import { patch, clone } from 'jsondiffpatch';
 import { findExpandingRanges } from "./findExpandingRanges.mjs";
-import { isFrameSpan } from "../parseSource/isFrameSpan.mjs";
+import { hasClassName, isFrameSpan } from "../parseSource/isFrameSpan.mjs";
 
 /**
  * Decodes a `VariantSource` to a live `HastRoot` (or `null` for string /
@@ -60,7 +60,7 @@ function renumberLines(root) {
     const children = frame.children;
     for (let i = 0; i < children.length; i += 1) {
       const child = children[i];
-      if (child.type === 'element' && child.properties != null && child.properties.className === 'line') {
+      if (child.type === 'element' && child.properties != null && hasClassName(child, 'line')) {
         lineNumber += 1;
         const previous = child.properties.dataLn;
         if (typeof previous === 'number') {
@@ -120,7 +120,7 @@ function markAddedLinesInPlace(root, ranges) {
     const children = frame.children;
     for (let i = 0; i < children.length; i += 1) {
       const child = children[i];
-      if (child.type !== 'element' || child.properties == null || child.properties.className !== 'line') {
+      if (child.type !== 'element' || child.properties == null || !hasClassName(child, 'line')) {
         continue;
       }
       const lineNumber = child.properties.dataLn;

package/pipeline/loadIsomorphicCodeVariant/diffHast.mjs

@@ -1,6 +1,7 @@
 import { create, patch } from 'jsondiffpatch';
 import { findExpandingRanges, hasExpandingRanges } from "./findExpandingRanges.mjs";
 import { getInitialVisibleSourceLines } from "./getInitialVisibleSourceLines.mjs";
+import { hasClassName } from "../parseSource/isFrameSpan.mjs";
 
 /**
  * Async-friendly variant of {@link ParseSource}. The build-time diff path
@@ -27,15 +28,12 @@ const differ = create({
     if (value === null || typeof value !== 'object') {
       return `idx:${index}`;
     }
+    // jsondiffpatch hands us `unknown`; the checks below validate the cast.
     const node = value;
-    if (node.type === 'element' && node.tagName === 'span') {
-      const cls = node.properties?.className;
-      const className = Array.isArray(cls) ? cls.join(' ') : cls;
-      // Collapse placeholders get a unique identity so jsondiffpatch
-      // can't morph a wiped line span into a placeholder in place.
-      if (className === 'collapse') {
-        return `collapse:${index}`;
-      }
+    // Collapse placeholders get a unique identity so jsondiffpatch
+    // can't morph a wiped line span into a placeholder in place.
+    if (node.type === 'element' && node.tagName === 'span' && hasClassName(node, 'collapse')) {
+      return `collapse:${index}`;
     }
     // Everything else (frames, lines, text) falls back to positional
     // identity — same as jsondiffpatch's default behavior — so we don't
@@ -63,7 +61,7 @@ function isEmptyLine(line) {
   return false;
 }
 function isLineElement(node) {
-  return !!node && node.type === 'element' && node.tagName === 'span' && node.properties != null && node.properties.className === 'line';
+  return !!node && node.type === 'element' && node.tagName === 'span' && node.properties != null && hasClassName(node, 'line');
 }
 
 /**
@@ -84,7 +82,7 @@ function stripLineNumbersInPlace(root) {
     const lines = frame.children;
     for (let i = 0; i < lines.length; i += 1) {
       const line = lines[i];
-      if (line.type === 'element' && line.properties != null && line.properties.className === 'line' && line.properties.dataLn !== undefined) {
+      if (line.type === 'element' && line.properties != null && hasClassName(line, 'line') && line.properties.dataLn !== undefined) {
         delete line.properties.dataLn;
       }
     }
@@ -187,7 +185,7 @@ function renumberLinesInPlace(root) {
     const children = frame.children;
     for (let i = 0; i < children.length; i += 1) {
       const child = children[i];
-      if (child.type === 'element' && child.properties != null && child.properties.className === 'line') {
+      if (child.type === 'element' && child.properties != null && hasClassName(child, 'line')) {
         lineNumber += 1;
         child.properties.dataLn = lineNumber;
       }
@@ -303,7 +301,7 @@ function makePlaceholder(count) {
     type: 'element',
     tagName: 'span',
     properties: {
-      className: 'collapse',
+      className: ['collapse'],
       dataLines: count
     },
     children

package/pipeline/loadIsomorphicCodeVariant/embedTransforms.d.mts

@@ -1,7 +1,7 @@
 import type { HastRoot, Transforms } from "../../CodeHighlighter/types.mjs";
 /**
  * Recursively walks a jsondiffpatch delta looking for any inserted hast
- * element with `className === 'collapse'`. Used to mark a manifest entry
+ * element whose `className` includes `'collapse'`. Used to mark a manifest entry
  * as layout-affecting (phase 1, coordinated barrier so peers stay in
  * lockstep) so the runtime doesn't have to decompress the embedded hast
  * payload on every selection change to classify the swap.
@@ -10,8 +10,9 @@ import type { HastRoot, Transforms } from "../../CodeHighlighter/types.mjs";
  * opcodes (`[value]` for insert, `[oldValue, 0, 0]` for delete, `_t: 'a'`
  * + `_N` keys for array ops). The collapse placeholder is only ever
  * produced by `compactCollapseInTreeInPlace` on the *transform* side of
- * the diff, so any hast element with className 'collapse' anywhere in
- * the delta tree is necessarily part of an insertion or in-place rewrite.
+ * the diff, so any hast element whose `className` includes `'collapse'`
+ * anywhere in the delta tree is necessarily part of an insertion or an
+ * in-place rewrite.
  */
 export declare function deltaContainsCollapse(delta: unknown): boolean;
 /**

package/pipeline/loadIsomorphicCodeVariant/embedTransforms.mjs

@@ -1,6 +1,8 @@
+import { hasClassName } from "../parseSource/isFrameSpan.mjs";
+
 /**
  * Recursively walks a jsondiffpatch delta looking for any inserted hast
- * element with `className === 'collapse'`. Used to mark a manifest entry
+ * element whose `className` includes `'collapse'`. Used to mark a manifest entry
  * as layout-affecting (phase 1, coordinated barrier so peers stay in
  * lockstep) so the runtime doesn't have to decompress the embedded hast
  * payload on every selection change to classify the swap.
@@ -9,22 +11,18 @@
  * opcodes (`[value]` for insert, `[oldValue, 0, 0]` for delete, `_t: 'a'`
  * + `_N` keys for array ops). The collapse placeholder is only ever
  * produced by `compactCollapseInTreeInPlace` on the *transform* side of
- * the diff, so any hast element with className 'collapse' anywhere in
- * the delta tree is necessarily part of an insertion or in-place rewrite.
+ * the diff, so any hast element whose `className` includes `'collapse'`
+ * anywhere in the delta tree is necessarily part of an insertion or an
+ * in-place rewrite.
  */
 export function deltaContainsCollapse(delta) {
   if (delta === null || typeof delta !== 'object') {
     return false;
   }
+  // The delta holds arbitrary values; the `type` check below validates the cast.
   const candidate = delta;
-  if (candidate.type === 'element') {
-    const cls = candidate.properties?.className;
-    if (cls === 'collapse') {
-      return true;
-    }
-    if (Array.isArray(cls) && cls.includes('collapse')) {
-      return true;
-    }
+  if (candidate.type === 'element' && hasClassName(candidate, 'collapse')) {
+    return true;
   }
   if (Array.isArray(delta)) {
     for (const item of delta) {

package/pipeline/loadIsomorphicCodeVariant/getInitialVisibleSourceLines.mjs

@@ -1,5 +1,5 @@
 import { COLLAPSED_VISIBLE_FRAME_TYPES } from "../parseSource/frameVisibility.mjs";
-import { isFrameSpan } from "../parseSource/isFrameSpan.mjs";
+import { hasClassName, isFrameSpan } from "../parseSource/isFrameSpan.mjs";
 
 /**
  * Returns the set of 1-indexed source line numbers that are visible when
@@ -35,7 +35,7 @@ export function getInitialVisibleSourceLines(tree) {
       hasVisibleEmphasisFrame = true;
     }
     for (const grandChild of frame.children) {
-      if (grandChild.type === 'element' && grandChild.properties?.className === 'line') {
+      if (grandChild.type === 'element' && hasClassName(grandChild, 'line')) {
         lineNumber += 1;
         if (frameVisible) {
           visible.add(lineNumber);
@@ -61,7 +61,7 @@ export function getInitialVisibleSourceLines(tree) {
       }
       const frame = child;
       for (const grandChild of frame.children) {
-        if (grandChild.type === 'element' && grandChild.properties?.className === 'line') {
+        if (grandChild.type === 'element' && hasClassName(grandChild, 'line')) {
           fallbackLine += 1;
           visible.add(fallbackLine);
         }

package/pipeline/loadServerTypes/hastTypeUtils.d.mts

@@ -6,12 +6,12 @@
  */
 import type { Root as HastRoot, Element } from 'hast';
 import { getHastTextContent, getShallowTextContent } from "../hastUtils/index.mjs";
+import { hasClassName } from "../parseSource/isFrameSpan.mjs";
 export { getHastTextContent, getShallowTextContent };
 /**
  * Checks if a HAST element has a specific CSS class.
- * Handles both string and array class representations.
  */
-export declare function hasClass(element: Element, className: string): boolean;
+export declare const hasClass: typeof hasClassName;
 /**
  * Checks if a HAST element is a span with class `line`.
  */

package/pipeline/loadServerTypes/hastTypeUtils.mjs

@@ -6,22 +6,13 @@
  */
 
 import { compressHast, getHastTextContent, getShallowTextContent } from "../hastUtils/index.mjs";
+import { hasClassName } from "../parseSource/isFrameSpan.mjs";
 export { getHastTextContent, getShallowTextContent };
 
 /**
  * Checks if a HAST element has a specific CSS class.
- * Handles both string and array class representations.
  */
-export function hasClass(element, className) {
-  const classes = element.properties?.className;
-  if (Array.isArray(classes)) {
-    return classes.includes(className);
-  }
-  if (typeof classes === 'string') {
-    return classes.split(' ').includes(className);
-  }
-  return false;
-}
+export const hasClass = hasClassName;
 
 /**
  * Checks if a HAST element is a span with class `line`.

package/pipeline/loadServerTypes/loadServerTypes.mjs

@@ -7,7 +7,7 @@ import { highlightTypesMeta } from "./highlightTypesMeta.mjs";
 import { syncTypes } from "../syncTypes/index.mjs";
 import { loadServerTypesText } from "../loadServerTypesText/index.mjs";
 import { resolveTypesCacheKey } from "../loadServerTypesText/resolveTypesCacheKey.mjs";
-import { withFileCache } from "../cacheUtils/index.mjs";
+import { CACHE_SCHEMA_VERSION, withFileCache } from "../cacheUtils/index.mjs";
 const functionName = 'Load Server Types';
 
 /** Cache namespace for the enhanced (highlighted) loadServerTypes result. */
@@ -66,6 +66,9 @@ export async function loadServerTypes(options) {
     ref: cacheRef,
     readOrigin: () => syncResult,
     getCacheContent: source => JSON.stringify({
+      // The cached value is hast, whose shape can change between releases — see
+      // CACHE_SCHEMA_VERSION. Dropping this lets a warm cache serve the old shape.
+      cacheSchemaVersion: CACHE_SCHEMA_VERSION,
       // Exclude allDependencies (re-attached fresh below) so a dep-list change does not needlessly
       // invalidate the cached highlighting, and the transient `updated` flag for hash stability.
       source: {

package/pipeline/loadServerTypesText/parseTypesMarkdown.mjs

@@ -76,6 +76,16 @@ function extractInlineCodeOrText(node) {
   return '';
 }
 
+/** Extract inline-code values from mdast phrasing content. */
+function extractInlineCodeValues(nodes) {
+  return nodes.flatMap(node => {
+    if (node.type === 'inlineCode') {
+      return node.value;
+    }
+    return 'children' in node ? extractInlineCodeValues(node.children) : [];
+  });
+}
+
 /**
  * A target for batch HAST conversion: a setter to assign the result and the mdast nodes to convert.
  */
@@ -533,6 +543,9 @@ export async function parseTypesMarkdown(content, ordering) {
   const allTypes = [];
   const descriptionTargets = [];
   const externalTypes = {};
+  const parsedVariantTypes = {};
+  const typeNameMap = {};
+  const parsedVariantTypeNameMapKeys = {};
 
   // Track current context
   let currentH3Name = null;
@@ -553,6 +566,7 @@ export async function parseTypesMarkdown(content, ordering) {
   let lastParamExampleName = null;
   let lastPropReferencesName = null;
   let lastParamReferencesName = null;
+  let metadataSection = null;
 
   // Helper to flush the current section
   const flushSection = () => {
@@ -697,6 +711,12 @@ export async function parseTypesMarkdown(content, ordering) {
     if (node.type === 'heading' && node.depth === 2) {
       flushSection();
       const text = extractText(node.children);
+      metadataSection = null;
+      if (text === 'Export Groups') {
+        metadataSection = 'export-groups';
+      } else if (text === 'Canonical Types') {
+        metadataSection = 'canonical-types';
+      }
       if (text === 'External Types') {
         inExternalTypes = true;
       } else if (text === 'Additional Types') {
@@ -712,6 +732,7 @@ export async function parseTypesMarkdown(content, ordering) {
     if (node.type === 'heading' && node.depth === 3) {
       flushSection();
       inExternalTypes = false;
+      metadataSection = null;
       currentH3Name = extractText(node.children);
       continue;
     }
@@ -722,6 +743,36 @@ export async function parseTypesMarkdown(content, ordering) {
       continue;
     }
 
+    // Handle generated metadata lists
+    if (node.type === 'list' && metadataSection) {
+      for (const item of node.children) {
+        const children = item.children.flatMap(child => child.type === 'paragraph' ? child.children : []);
+        const separatorIndex = children.findIndex(child => child.type === 'text' && child.value.includes(':'));
+        const namesBeforeSeparator = extractInlineCodeValues(children.slice(0, separatorIndex === -1 ? children.length : separatorIndex));
+        const namesAfterSeparator = separatorIndex === -1 ? [] : extractInlineCodeValues(children.slice(separatorIndex + 1));
+        if (metadataSection === 'export-groups') {
+          const variantName = namesBeforeSeparator[0];
+          if (variantName) {
+            parsedVariantTypes[variantName] = separatorIndex === -1 ? [variantName] : namesAfterSeparator;
+          }
+        } else {
+          const [canonicalName, ...variants] = namesBeforeSeparator;
+          if (!canonicalName || separatorIndex === -1) {
+            continue;
+          }
+          for (const flatName of namesAfterSeparator) {
+            typeNameMap[flatName] = canonicalName;
+          }
+          for (const variant of variants) {
+            const keys = parsedVariantTypeNameMapKeys[variant] ?? [];
+            keys.push(...namesAfterSeparator);
+            parsedVariantTypeNameMapKeys[variant] = keys;
+          }
+        }
+      }
+      continue;
+    }
+
     // Handle code blocks
     if (node.type === 'code') {
       if (inExternalTypes && currentExternalTypeName) {
@@ -833,97 +884,8 @@ export async function parseTypesMarkdown(content, ordering) {
 
   // Flush the last section
   flushSection();
-
-  // Parse metadata from human-readable sections instead of JSON comments
-  // The new format uses "## Export Groups" and "## Canonical Types" sections
-
-  // Parse Export Groups section
-  // Format: - `VariantName`: `Type1`, `Type2` (or just `- VariantName` if key equals single value)
-  let variantTypes = null;
-  const exportGroupsMatch = content.match(/## Export Groups\n([\s\S]*?)(?=\n## |$)/);
-  if (exportGroupsMatch) {
-    variantTypes = {};
-    const lines = exportGroupsMatch[1].trim().split('\n');
-    for (const line of lines) {
-      // Match: - `VariantName`: `Type1`, `Type2` OR - `VariantName`
-      const withValuesMatch = line.match(/^- `([^`]+)`:\s*(.+)$/);
-      const singleMatch = line.match(/^- `([^`]+)`$/);
-      if (withValuesMatch) {
-        const variantName = withValuesMatch[1];
-        // Extract all backtick-wrapped values
-        const values = withValuesMatch[2].match(/`([^`]+)`/g);
-        variantTypes[variantName] = values ? values.map(v => v.slice(1, -1)) : [];
-      } else if (singleMatch) {
-        // Key equals value - the variant name IS the single type
-        const variantName = singleMatch[1];
-        variantTypes[variantName] = [variantName];
-      }
-    }
-    // Only keep variantTypes if we found entries
-    if (Object.keys(variantTypes).length === 0) {
-      variantTypes = null;
-    }
-  }
-
-  // Parse Canonical Types section
-  // Format: - `CanonicalName` (`Variant1`, `Variant2`): `FlatName1`, `FlatName2`
-  // OR:     - `CanonicalName`: `FlatName1`, `FlatName2` (no variant annotation)
-  const typeNameMap = {};
-  let variantTypeNameMapKeys = null;
-  const canonicalTypesMatch = content.match(/## Canonical Types\n([\s\S]*?)(?=\n## |$)/);
-  if (canonicalTypesMatch) {
-    variantTypeNameMapKeys = {};
-    const lines = canonicalTypesMatch[1].trim().split('\n');
-    for (const line of lines) {
-      // Match: - `CanonicalName` (`Variant1`, `Variant2`): `FlatName1`, `FlatName2`
-      // OR:    - `CanonicalName`: `FlatName1`, `FlatName2`
-      const withVariantMatch = line.match(/^- `([^`]+)`\s+\(([^)]+)\):\s*(.+)$/);
-      const withoutVariantMatch = line.match(/^- `([^`]+)`:\s*(.+)$/);
-      let canonicalName;
-      let flatNamesStr;
-      let variants = [];
-      if (withVariantMatch) {
-        canonicalName = withVariantMatch[1];
-        // Extract variants from parentheses
-        const variantStr = withVariantMatch[2];
-        const variantMatches = variantStr.match(/`([^`]+)`/g);
-        variants = variantMatches ? variantMatches.map(v => v.slice(1, -1)) : [];
-        flatNamesStr = withVariantMatch[3];
-      } else if (withoutVariantMatch) {
-        canonicalName = withoutVariantMatch[1];
-        flatNamesStr = withoutVariantMatch[2];
-        // No variant annotation - applies to all variants
-      } else {
-        continue;
-      }
-
-      // Extract all flat names
-      const flatNameMatches = flatNamesStr.match(/`([^`]+)`/g);
-      const flatNames = flatNameMatches ? flatNameMatches.map(v => v.slice(1, -1)) : [];
-
-      // Build typeNameMap (flat name -> canonical name)
-      for (const flatName of flatNames) {
-        typeNameMap[flatName] = canonicalName;
-      }
-
-      // Build variantTypeNameMapKeys (variant -> list of keys)
-      // If no variants specified, we don't track variant-specific keys
-      if (variants.length > 0) {
-        for (const variant of variants) {
-          if (!variantTypeNameMapKeys[variant]) {
-            variantTypeNameMapKeys[variant] = [];
-          }
-          for (const flatName of flatNames) {
-            variantTypeNameMapKeys[variant].push(flatName);
-          }
-        }
-      }
-    }
-    // Only keep variantTypeNameMapKeys if we found entries
-    if (Object.keys(variantTypeNameMapKeys).length === 0) {
-      variantTypeNameMapKeys = null;
-    }
-  }
+  const variantTypes = Object.keys(parsedVariantTypes).length > 0 ? parsedVariantTypes : null;
+  const variantTypeNameMapKeys = Object.keys(parsedVariantTypeNameMapKeys).length > 0 ? parsedVariantTypeNameMapKeys : null;
 
   // Convert all description mdast nodes to HAST in parallel
   await convertDescriptions(descriptionTargets);

package/pipeline/loadServerTypesText/resolveTypesCacheKey.d.mts

@@ -13,7 +13,9 @@ export declare function resolveTypesCacheKey(typesMarkdownPath: string, rootCont
 /**
  * Builds the hash-validation content for the types.md parse cache. Includes the
  * ordering config because it changes `parseTypesMarkdown`'s output, so the cache is
- * invalidated when either the markdown or the ordering changes. The writer (syncTypes)
- * and reader (loadServerTypesText) must build this identically for their hashes to match.
+ * invalidated when either the markdown or the ordering changes, and CACHE_SCHEMA_VERSION
+ * because the parsed value embeds hast (descriptions), whose shape can change between
+ * releases. The writer (syncTypes) and reader (loadServerTypesText) must build this
+ * identically for their hashes to match.
  */
 export declare function buildTypesTextCacheContent(markdown: string, ordering?: OrderingConfig): string;

package/pipeline/loadServerTypesText/resolveTypesCacheKey.mjs

@@ -1,3 +1,4 @@
+import { CACHE_SCHEMA_VERSION } from "../cacheUtils/index.mjs";
 import { extractPrefixAndTitle } from "../loadServerPageIndex/extractPrefixAndTitle.mjs";
 /** Cache namespace for the types.md parse cache (TypesSourceData), mirroring the page-index cache. */
 export const TYPES_TEXT_CACHE_NAMESPACE = 'types-text';
@@ -21,9 +22,11 @@ export function resolveTypesCacheKey(typesMarkdownPath, rootContext) {
 /**
  * Builds the hash-validation content for the types.md parse cache. Includes the
  * ordering config because it changes `parseTypesMarkdown`'s output, so the cache is
- * invalidated when either the markdown or the ordering changes. The writer (syncTypes)
- * and reader (loadServerTypesText) must build this identically for their hashes to match.
+ * invalidated when either the markdown or the ordering changes, and CACHE_SCHEMA_VERSION
+ * because the parsed value embeds hast (descriptions), whose shape can change between
+ * releases. The writer (syncTypes) and reader (loadServerTypesText) must build this
+ * identically for their hashes to match.
  */
 export function buildTypesTextCacheContent(markdown, ordering) {
-  return `${JSON.stringify(ordering ?? null)}\n${markdown}`;
+  return `${CACHE_SCHEMA_VERSION}\n${JSON.stringify(ordering ?? null)}\n${markdown}`;
 }

package/pipeline/parseSource/addLineGutters.mjs

@@ -1,7 +1,7 @@
 // Example copied from https://github.com/wooorm/starry-night#example-adding-line-numbers
 
 import { createFrame } from "./createFrame.mjs";
-import { isFrameSpan } from "./isFrameSpan.mjs";
+import { hasClassName, isFrameSpan } from "./isFrameSpan.mjs";
 
 /**
  * Counts the number of lines in a HAST tree without mutating it.
@@ -154,7 +154,7 @@ export function starryNightGutter(tree, sourceLines, frameSize = 120) {
       const frame = replacement[frameIndex];
       if (frame.type === 'element' && frame.tagName === 'span' && isFrameSpan(frame)) {
         // Extract line range from child .line elements
-        const lineChildren = frame.children.filter(c => c.type === 'element' && c.properties?.className === 'line' && typeof c.properties.dataLn === 'number');
+        const lineChildren = frame.children.filter(c => c.type === 'element' && hasClassName(c, 'line') && typeof c.properties.dataLn === 'number');
         if (lineChildren.length > 0) {
           const startLine = Number(lineChildren[0].properties.dataLn) - 1;
           const endLine = Number(lineChildren[lineChildren.length - 1].properties.dataLn);
@@ -204,7 +204,7 @@ function createLine(children, line) {
     type: 'element',
     tagName: 'span',
     properties: {
-      className: 'line',
+      className: ['line'],
       dataLn: line
     },
     children

package/pipeline/parseSource/createFrame.mjs

@@ -6,7 +6,7 @@
  */
 export function createFrame(children, frameType, indentLevel, truncated) {
   const properties = {
-    className: 'frame',
+    className: ['frame'],
     dataLined: ''
   };
   if (frameType && frameType !== 'normal') {

package/pipeline/parseSource/isFrameSpan.d.mts

@@ -1,19 +1,14 @@
 import type { Element as HastElement } from 'hast';
 /**
- * Returns `true` when a HAST element carries the given class name, accepting
- * both shapes `className` can take:
+ * Returns `true` when a HAST element carries the given class name.
  *
- * - the string form (`className: 'frame'`), used by freshly parsed / live HAST
- *   (e.g. `createFrame`), and
- * - the array form (`className: ['frame']`), produced by `fallbackToHast` and by
- *   any HAST that round-trips through serialization.
- *
- * Matching only the string silently skips real fallback frames, so class checks
- * on HAST that may come from either path must go through this helper.
+ * `className` is always the array shape (`['frame']`): it is what the
+ * highlighter, `fallbackToHast` and any HAST that round-trips through
+ * serialization produce, and what the compression dictionary encodes.
  */
 export declare function hasClassName(element: HastElement, name: string): boolean;
 /**
  * Returns `true` when a HAST element is a code frame span — its `className`
- * includes `'frame'` in either the string or array shape (see {@link hasClassName}).
+ * includes `'frame'` (see {@link hasClassName}).
  */
 export declare function isFrameSpan(element: HastElement): boolean;

package/pipeline/parseSource/isFrameSpan.mjs

@@ -1,23 +1,17 @@
 /**
- * Returns `true` when a HAST element carries the given class name, accepting
- * both shapes `className` can take:
+ * Returns `true` when a HAST element carries the given class name.
  *
- * - the string form (`className: 'frame'`), used by freshly parsed / live HAST
- *   (e.g. `createFrame`), and
- * - the array form (`className: ['frame']`), produced by `fallbackToHast` and by
- *   any HAST that round-trips through serialization.
- *
- * Matching only the string silently skips real fallback frames, so class checks
- * on HAST that may come from either path must go through this helper.
+ * `className` is always the array shape (`['frame']`): it is what the
+ * highlighter, `fallbackToHast` and any HAST that round-trips through
+ * serialization produce, and what the compression dictionary encodes.
  */
 export function hasClassName(element, name) {
-  const className = element.properties?.className;
-  return className === name || Array.isArray(className) && className.includes(name);
+  return element.properties?.className?.includes(name) ?? false;
 }
 
 /**
  * Returns `true` when a HAST element is a code frame span — its `className`
- * includes `'frame'` in either the string or array shape (see {@link hasClassName}).
+ * includes `'frame'` (see {@link hasClassName}).
  */
 export function isFrameSpan(element) {
   return hasClassName(element, 'frame');

package/pipeline/parseSource/restructureFrames.mjs

@@ -1,5 +1,5 @@
 import { createFrame } from "./createFrame.mjs";
-import { isFrameSpan } from "./isFrameSpan.mjs";
+import { hasClassName, isFrameSpan } from "./isFrameSpan.mjs";
 import { redistributeFrameFallbacks } from "./redistributeFrameFallbacks.mjs";
 
 /**
@@ -15,7 +15,7 @@ import { redistributeFrameFallbacks } from "./redistributeFrameFallbacks.mjs";
  */
 
 function isCollapsedLinesPlaceholder(node) {
-  return node.type === 'element' && node.tagName === 'span' && node.properties != null && node.properties.className === 'collapse';
+  return node.type === 'element' && node.tagName === 'span' && node.properties != null && hasClassName(node, 'collapse');
 }
 
 /**
@@ -38,7 +38,7 @@ function flattenLineEntries(root) {
     const children = frame.children ?? [];
     for (let i = 0; i < children.length; i += 1) {
       const child = children[i];
-      if (child.type === 'element' && child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+      if (child.type === 'element' && child.tagName === 'span' && hasClassName(child, 'line') && typeof child.properties.dataLn === 'number') {
         const lineNumber = child.properties.dataLn;
         // Resolve any placeholders waiting on a following line.
         for (const pending of pendingNextAnchor) {
@@ -92,7 +92,7 @@ function collectFrameFallbacks(root) {
     let startLine = Infinity;
     let endLine = -Infinity;
     for (const child of frame.children) {
-      if (child.type === 'element' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+      if (child.type === 'element' && hasClassName(child, 'line') && typeof child.properties.dataLn === 'number') {
         const lineNumber = child.properties.dataLn;
         if (lineNumber < startLine) {
           startLine = lineNumber;

package/pipeline/transformMarkdownCode/transformMarkdownCode.mjs

@@ -255,7 +255,7 @@ export const transformMarkdownCode = (options = {}) => {
 
           // Add normalized language as class
           if (langFromMeta) {
-            codeHProperties.className = `language-${normalizeLanguage(langFromMeta)}`;
+            codeHProperties.className = [`language-${normalizeLanguage(langFromMeta)}`];
           }
 
           // Add all props as data attributes (in camelCase)
@@ -534,7 +534,7 @@ export const transformMarkdownCode = (options = {}) => {
 
                 // Add normalized language as class
                 if (block.actualLang) {
-                  codeHProperties.className = `language-${normalizeLanguage(block.actualLang)}`;
+                  codeHProperties.className = [`language-${normalizeLanguage(block.actualLang)}`];
                 }
 
                 // Add additional props as data attributes (in camelCase)
@@ -693,7 +693,7 @@ export const transformMarkdownCode = (options = {}) => {
 
             // Add normalized language as class
             if (block.actualLang) {
-              codeHProperties.className = `language-${normalizeLanguage(block.actualLang)}`;
+              codeHProperties.className = [`language-${normalizeLanguage(block.actualLang)}`];
             }
 
             // Add additional props as data attributes (in camelCase)