@mui/internal-docs-infra 0.12.1-canary.2 → 0.12.1-canary.21

package/pipeline/syncPageIndex/mergeMetadataMarkdown.mjs

@@ -5,56 +5,34 @@ import { markdownToMetadata, metadataToMarkdown } from "./metadataToMarkdown.mjs
  */
 
 /**
- * Merges new page metadata with existing markdown content, preserving the order
- * of pages from the existing markdown when available, unless the file contains
- * only the autogeneration marker (no editable section), in which case pages are
- * sorted alphabetically by title.
- *
- * Pages are matched by their `path` property (e.g., './button/page.mdx'), not by slug.
- * This allows multiple pages to have the same slug (anchor) while still being treated
- * as distinct pages.
- *
- * @param existingMarkdown - The existing markdown content (or undefined if none exists)
- * @param newMetadata - The new metadata to merge in
- * @param options - Optional configuration
- * @param options.preserveUnlisted - If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed.
- * @param options.indexWrapperComponent - Optional component name to wrap the autogenerated content (e.g., 'PagesIndex')
- * @returns The updated markdown content with merged metadata
- *
- * @example
- * ```ts
- * const existingMarkdown = `# Components
- * - Button - ([Outline](#button), [Contents](./button/page.mdx)) - A button
- * - Checkbox - ([Outline](#checkbox), [Contents](./checkbox/page.mdx)) - A checkbox
- * `;
+ * Result of merging new metadata into existing markdown: the normalized
+ * `PagesMetadata` that renders to the merged markdown, plus the rendering options
+ * needed to reproduce that markdown.
+ */
+
+/**
+ * Merges new page metadata with existing markdown content and returns the
+ * normalized `PagesMetadata` (and rendering options) without serializing to markdown.
  *
- * const newMetadata = {
- *   title: 'Components',
- *   pages: [
- *     { slug: 'checkbox', path: './checkbox/page.mdx', title: 'Checkbox', description: 'Updated checkbox' },
- *     { slug: 'button', path: './button/page.mdx', title: 'Button', description: 'Updated button' },
- *     { slug: 'input', path: './input/page.mdx', title: 'Input', description: 'New input' },
- *   ],
- * };
+ * This is the in-memory source of truth that {@link mergeMetadataMarkdown} renders.
+ * `syncPageIndex` reuses it to pre-populate the page-index cache, so the cached
+ * value matches a fresh read of the rendered markdown.
  *
- * const result = await mergeMetadataMarkdown(existingMarkdown, newMetadata);
- * // Result preserves Button, Checkbox order from existing markdown, adds Input at the end
- * ```
+ * See {@link mergeMetadataMarkdown} for the ordering and merge semantics.
  */
-export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, options = {}) {
+export async function mergeMetadataPages(existingMarkdown, newMetadata, options = {}) {
   const {
     indexWrapperComponent,
-    path,
     preserveExistingTitleAndSlug
   } = options;
 
-  // If no existing markdown, just convert the new metadata
-  // Use the provided wrapper unless it's null (which means remove)
+  // If no existing markdown, just use the new metadata.
+  // Use the provided wrapper unless it's null (which means remove).
   if (!existingMarkdown) {
-    return metadataToMarkdown(newMetadata, {
-      indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent,
-      path
-    });
+    return {
+      metadata: newMetadata,
+      indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent
+    };
   }
 
   // Parse the existing markdown to get the current order
@@ -62,10 +40,10 @@ export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, optio
 
   // If parsing failed, just use the new metadata
   if (!existingMetadata) {
-    return metadataToMarkdown(newMetadata, {
-      indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent,
-      path
-    });
+    return {
+      metadata: newMetadata,
+      indexWrapperComponent: indexWrapperComponent === null ? undefined : indexWrapperComponent
+    };
   }
 
   // Determine effective wrapper component:
@@ -160,11 +138,63 @@ export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, optio
     // Preserve the existing pageMetadata (e.g., robots config) from the current file
     pageMetadata: existingMetadata.pageMetadata
   };
-
-  // Preserve the alphabetical sorting marker if it was present
-  return metadataToMarkdown(mergedMetadata, {
-    editableMarker: requestsAlphabeticalSort ? alphabeticalSortMarker : undefined,
+  return {
+    metadata: mergedMetadata,
     indexWrapperComponent: effectiveWrapper,
+    // Preserve the alphabetical sorting marker if it was present
+    editableMarker: requestsAlphabeticalSort ? alphabeticalSortMarker : undefined
+  };
+}
+
+/**
+ * Merges new page metadata with existing markdown content, preserving the order
+ * of pages from the existing markdown when available, unless the file contains
+ * only the autogeneration marker (no editable section), in which case pages are
+ * sorted alphabetically by title.
+ *
+ * Pages are matched by their `path` property (e.g., './button/page.mdx'), not by slug.
+ * This allows multiple pages to have the same slug (anchor) while still being treated
+ * as distinct pages.
+ *
+ * @param existingMarkdown - The existing markdown content (or undefined if none exists)
+ * @param newMetadata - The new metadata to merge in
+ * @param options - Optional configuration
+ * @param options.preserveUnlisted - If true, pages in existing markdown that aren't in newMetadata will be preserved. If false (default), they are removed.
+ * @param options.indexWrapperComponent - Optional component name to wrap the autogenerated content (e.g., 'PagesIndex')
+ * @returns The updated markdown content with merged metadata
+ *
+ * @example
+ * ```ts
+ * const existingMarkdown = `# Components
+ * - Button - ([Outline](#button), [Contents](./button/page.mdx)) - A button
+ * - Checkbox - ([Outline](#checkbox), [Contents](./checkbox/page.mdx)) - A checkbox
+ * `;
+ *
+ * const newMetadata = {
+ *   title: 'Components',
+ *   pages: [
+ *     { slug: 'checkbox', path: './checkbox/page.mdx', title: 'Checkbox', description: 'Updated checkbox' },
+ *     { slug: 'button', path: './button/page.mdx', title: 'Button', description: 'Updated button' },
+ *     { slug: 'input', path: './input/page.mdx', title: 'Input', description: 'New input' },
+ *   ],
+ * };
+ *
+ * const result = await mergeMetadataMarkdown(existingMarkdown, newMetadata);
+ * // Result preserves Button, Checkbox order from existing markdown, adds Input at the end
+ * ```
+ */
+export async function mergeMetadataMarkdown(existingMarkdown, newMetadata, options = {}) {
+  const {
+    path
+  } = options;
+  const {
+    metadata,
+    indexWrapperComponent,
+    editableMarker
+  } = await mergeMetadataPages(existingMarkdown, newMetadata, options);
+  return metadataToMarkdown(metadata, {
+    editableMarker,
+    indexWrapperComponent,
     path
   });
 }

package/pipeline/syncPageIndex/metadataToMarkdown.d.mts

@@ -1,6 +1,6 @@
 import type { Root } from 'mdast';
 import type { ExtractedMetadata } from "../transformMarkdownMetadata/types.mjs";
-import { type Audience } from "../../createSitemap/types.mjs";
+import type { Audience } from "../../createSitemap/types.mjs";
 export interface PageMetadata extends ExtractedMetadata {
   /** The slug/path for this page (e.g., 'button', 'checkbox') */
   slug: string;
@@ -66,6 +66,20 @@ export interface PagesMetadata {
   /** Name of a React component that wraps the autogenerated index content */
   indexWrapperComponent?: string;
 }
+/**
+ * Resolves the page metadata embedded in an autogenerated index, falling back to
+ * the default (private, non-indexed) metadata when none is provided.
+ *
+ * Shared between rendering (`metadataToMarkdownAst`) and cache pre-population in
+ * `syncPageIndex` so the cached read-model matches a fresh parse of the rendered file.
+ */
+export declare function resolveIndexPageMetadata(pageMetadata?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Collapses runs of whitespace to single spaces and trims, the way the parser normalizes
+ * paragraph text. Shared so cache pre-population (which builds the read-model from in-memory
+ * metadata) produces the same description/title strings a fresh parse of the markdown would.
+ */
+export declare function collapseInlineWhitespace(text: string): string;
 /**
  * Options for metadataToMarkdown and metadataToMarkdownAst functions
  */

package/pipeline/syncPageIndex/metadataToMarkdown.mjs

@@ -45,6 +45,35 @@ function astNodesToMarkdown(nodes) {
   }
   return result;
 }
+/**
+ * Resolves the page metadata embedded in an autogenerated index, falling back to
+ * the default (private, non-indexed) metadata when none is provided.
+ *
+ * Shared between rendering (`metadataToMarkdownAst`) and cache pre-population in
+ * `syncPageIndex` so the cached read-model matches a fresh parse of the rendered file.
+ */
+export function resolveIndexPageMetadata(pageMetadata) {
+  if (pageMetadata && Object.keys(pageMetadata).length > 0) {
+    return pageMetadata;
+  }
+  return {
+    robots: {
+      index: false
+    },
+    other: {
+      audience: 'private'
+    }
+  };
+}
+
+/**
+ * Collapses runs of whitespace to single spaces and trims, the way the parser normalizes
+ * paragraph text. Shared so cache pre-population (which builds the read-model from in-memory
+ * metadata) produces the same description/title strings a fresh parse of the markdown would.
+ */
+export function collapseInlineWhitespace(text) {
+  return text.replace(/[ \t\n\r]+/g, ' ').trim();
+}
 
 /**
  * Options for metadataToMarkdown and metadataToMarkdownAst functions
@@ -834,14 +863,7 @@ export function metadataToMarkdownAst(data, options = {}) {
       value: `</${indexWrapperComponent}>`
     });
   }
-  const metadataObj = pageMetadata && Object.keys(pageMetadata).length > 0 ? pageMetadata : {
-    robots: {
-      index: false
-    },
-    other: {
-      audience: 'private'
-    }
-  };
+  const metadataObj = resolveIndexPageMetadata(pageMetadata);
   const typeAnnotation = "/** @type {import('@mui/internal-docs-infra/createSitemap/types').NextMetadata} */";
   const metadataCode = `export const metadata =\n  ${typeAnnotation} (${serializeJsValue(metadataObj, 1)});`;
   // Output as raw MDX/JSX code (mdxjsEsm node type)
@@ -1559,7 +1581,7 @@ function extractPlainTextFromNode(node) {
     // For paragraph nodes, replace sequences of regular whitespace (spaces, tabs, newlines)
     // with a single space, but preserve non-breaking spaces and other special whitespace
     if (node.type === 'paragraph') {
-      return extractedText.replace(/[ \t\n\r]+/g, ' ').trim();
+      return collapseInlineWhitespace(extractedText);
     }
     return extractedText;
   }
@@ -1596,7 +1618,7 @@ function extractTextFromNode(node) {
     // For paragraph nodes, replace sequences of regular whitespace (spaces, tabs, newlines)
     // with a single space, but preserve non-breaking spaces and other special whitespace
     if (node.type === 'paragraph') {
-      return extractedText.replace(/[ \t\n\r]+/g, ' ').trim();
+      return collapseInlineWhitespace(extractedText);
     }
     return extractedText;
   }

package/pipeline/syncPageIndex/syncPageIndex.d.mts

@@ -86,6 +86,18 @@ export interface SyncPageIndexOptions {
    * @default false
    */
   preserveExistingTitleAndSlug?: boolean;
+  /**
+   * Directory for the sha256-validated JSON cache of page indexes. When set, each
+   * index written is also cached at `{cacheDir}/pages-index/{route}.json`, leaving
+   * it warm for the next cold `loadServerPageIndex` read. When unset, no cache is written.
+   */
+  cacheDir?: string;
+  /**
+   * Root context directory used to derive the cache key/route. Must match the
+   * `rootContext` used by `loadServerPageIndex` for cache keys to align.
+   * @default process.cwd()
+   */
+  rootContext?: string;
 }
 /**
  * Updates the parent directory's index file with metadata from a page.

package/pipeline/syncPageIndex/syncPageIndex.mjs

@@ -1,8 +1,11 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { basename, dirname, resolve, relative, join } from 'node:path';
 import * as lockfile from 'proper-lockfile';
-import { mergeMetadataMarkdown } from "./mergeMetadataMarkdown.mjs";
-import { markdownToMetadata } from "./metadataToMarkdown.mjs";
+import { mergeMetadataPages } from "./mergeMetadataMarkdown.mjs";
+import { markdownToMetadata, metadataToMarkdown, resolveIndexPageMetadata } from "./metadataToMarkdown.mjs";
+import { enrichPageIndex } from "../loadServerPageIndex/enrichPageIndex.mjs";
+import { resolvePageIndexCacheKey, PAGE_INDEX_CACHE_NAMESPACE } from "../loadServerPageIndex/resolvePageIndexCacheKey.mjs";
+import { saveFileCache } from "../cacheUtils/index.mjs";
 /**
  * Converts a kebab-case string to Title Case
  * @example kebabToTitleCase('my-component') -> 'My Component'
@@ -75,6 +78,74 @@ function shouldIncludePath(path, include, exclude) {
   // Path doesn't match any include pattern
   return false;
 }
+async function savePageIndexCache({
+  cacheDir,
+  indexPath,
+  rootContext,
+  markdown,
+  metadata,
+  defaultPageMetadata = true
+}) {
+  const cacheMetadata = {
+    ...metadata,
+    pageMetadata: defaultPageMetadata ? resolveIndexPageMetadata(metadata.pageMetadata) : metadata.pageMetadata
+  };
+  await saveFileCache({
+    cacheDir,
+    namespace: PAGE_INDEX_CACHE_NAMESPACE,
+    cacheKey: resolvePageIndexCacheKey(indexPath, rootContext)
+  }, markdown, enrichPageIndex(cacheMetadata, indexPath, rootContext));
+}
+
+/**
+ * Merges the incoming metadata into the source pages (keyed by path, matching
+ * mergeMetadataMarkdown's logic) and renders the index markdown exactly as it is
+ * persisted. Shared by the writer and the `errorIfOutOfDate` validation path so the two
+ * always agree on what the index should contain - otherwise validation could render
+ * differently from the writer and flag an up-to-date file (or miss a stale one).
+ */
+async function renderIndexPages(sourceMarkdown, sourcePages, metadataArray, {
+  indexTitle,
+  indexWrapperComponent,
+  preserveExistingTitleAndSlug,
+  relativeIndexPath
+}) {
+  // Build a map keyed by path (not slug) to match mergeMetadataMarkdown's logic.
+  const updatedPagesMap = new Map();
+  // First, add all source pages.
+  for (const page of sourcePages) {
+    updatedPagesMap.set(page.path, page);
+  }
+  // Then update/add the new metadata items.
+  for (const metaItem of metadataArray) {
+    updatedPagesMap.set(metaItem.path, metaItem);
+  }
+  // The COMPLETE list of pages that should exist.
+  const allPages = Array.from(updatedPagesMap.values());
+
+  // mergeMetadataPages preserves the order from sourceMarkdown and returns the normalized
+  // metadata that renders to finalMarkdown - reused by the writer to populate the cache
+  // without re-parsing what it just wrote.
+  const merged = await mergeMetadataPages(sourceMarkdown, {
+    title: indexTitle,
+    pages: allPages
+  }, {
+    indexWrapperComponent,
+    preserveExistingTitleAndSlug
+  });
+  const finalMarkdown = await metadataToMarkdown(merged.metadata, {
+    editableMarker: merged.editableMarker,
+    indexWrapperComponent: merged.indexWrapperComponent,
+    // Only include path in the comment when baseDir is set (otherwise it's an absolute path).
+    path: relativeIndexPath
+  });
+  return {
+    allPages,
+    merged,
+    finalMarkdown
+  };
+}
+
 /**
  * Updates the parent directory's index file with metadata from a page.
  *
@@ -115,7 +186,9 @@ export async function syncPageIndex(options) {
     markerDir = false,
     errorIfOutOfDate = false,
     indexWrapperComponent,
-    preserveExistingTitleAndSlug
+    preserveExistingTitleAndSlug,
+    cacheDir,
+    rootContext = process.cwd()
   } = options;
 
   // Validate that either metadata or metadataList is provided
@@ -186,13 +259,29 @@ export async function syncPageIndex(options) {
   // Step 2: Parse existing content and check if our specific page needs updating
   const existingMarkdown = existingContent.trim() ? existingContent : undefined;
   let existingPages = [];
+  let existingMetadata = null;
   if (existingMarkdown) {
-    const parsed = await markdownToMetadata(existingMarkdown);
-    if (parsed) {
-      existingPages = parsed.pages;
+    existingMetadata = await markdownToMetadata(existingMarkdown);
+    if (existingMetadata) {
+      existingPages = existingMetadata.pages;
     }
   }
 
+  // Refresh the page-index cache from the committed markdown for the "nothing to write"
+  // exits, so the next cold loadServerPageIndex read stays warm without re-parsing.
+  const saveExistingIndexCache = async () => {
+    if (cacheDir && existingMetadata) {
+      await savePageIndexCache({
+        cacheDir,
+        indexPath,
+        rootContext,
+        markdown: existingContent,
+        metadata: existingMetadata,
+        defaultPageMetadata: false
+      });
+    }
+  };
+
   // Step 3: Check if any of our metadata items need updating
   let needsUpdate = false;
   for (const metaItem of metadataArray) {
@@ -213,14 +302,36 @@ export async function syncPageIndex(options) {
     }
   }
   if (!needsUpdate) {
-    // All pages are already up-to-date, no need to acquire lock or write
+    await saveExistingIndexCache();
+
+    // All pages are already up-to-date, no need to acquire lock or write the index.
     return;
   }
 
-  // If errorIfOutOfDate is true, throw an error instead of updating
+  // If errorIfOutOfDate is true, the writer would refuse to touch the file. The coarse
+  // per-page comparison above compares the raw in-memory metadata, which contains fields
+  // that never reach the persisted index (volatile AST node positions, or metadata that
+  // mergeMetadataPages fills in from the existing markdown). Those produce false positives.
+  // Determine whether the index is genuinely out of date by rendering the exact markdown
+  // the writer would produce and comparing it to what is committed on disk. Only fail when
+  // the rendered output actually differs. This is validation only - it never writes, so it
+  // works from the pre-lock read (existingMarkdown/existingPages) rather than re-reading
+  // under a lock like the writer does.
   if (errorIfOutOfDate) {
-    const relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : indexPath;
-    throw new Error(`Index file is out of date: ${relativeIndexPath}\n` + `Please run the validation command (or next build) locally and commit the updated index files.`);
+    const relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : undefined;
+    const {
+      finalMarkdown
+    } = await renderIndexPages(existingMarkdown, existingPages, metadataArray, {
+      indexTitle,
+      indexWrapperComponent,
+      preserveExistingTitleAndSlug,
+      relativeIndexPath
+    });
+    if (existingContent !== finalMarkdown) {
+      throw new Error(`Index file is out of date: ${relativeIndexPath ?? indexPath}\n` + `Please run the validation command (or next build) locally and commit the updated index files.`);
+    }
+    await saveExistingIndexCache();
+    return;
   }
 
   // Step 4: Ensure the file exists before locking (proper-lockfile requires an existing file)
@@ -266,39 +377,24 @@ export async function syncPageIndex(options) {
       }
     }
 
-    // For batch updates, merge the metadata items with existing pages
-    // Build a map keyed by path (not slug) to match mergeMetadataMarkdown's logic
-    const updatedPagesMap = new Map();
-
-    // First, add all current pages
-    for (const page of currentPages) {
-      updatedPagesMap.set(page.path, page);
-    }
-
-    // Then update/add the new metadata items
-    for (const metaItem of metadataArray) {
-      updatedPagesMap.set(metaItem.path, metaItem);
-    }
-
-    // Convert back to array - this is the COMPLETE list of pages that should exist
-    const allPages = Array.from(updatedPagesMap.values());
-
-    // Store for parent update
-    mergedPages = allPages;
-
-    // Re-merge with the latest content, passing the COMPLETE list of pages
-    // mergeMetadataMarkdown will preserve the order from currentMarkdown
-    // Only include path in the comment when baseDir is set (otherwise it's an absolute path)
+    // Re-merge with the latest content re-read under the lock, passing the COMPLETE list
+    // of pages. The returned normalized metadata is reused below to populate the cache
+    // without re-parsing what we just wrote.
     const relativeIndexPath = baseDir ? relative(resolve(baseDir), indexPath) : undefined;
-    const finalMarkdown = await mergeMetadataMarkdown(currentMarkdown, {
-      title: indexTitle,
-      pages: allPages
-    }, {
+    const {
+      allPages,
+      merged,
+      finalMarkdown
+    } = await renderIndexPages(currentMarkdown, currentPages, metadataArray, {
+      indexTitle,
       indexWrapperComponent,
-      path: relativeIndexPath,
-      preserveExistingTitleAndSlug
+      preserveExistingTitleAndSlug,
+      relativeIndexPath
     });
 
+    // Store for parent update
+    mergedPages = allPages;
+
     // Defensive check
     if (!finalMarkdown || !finalMarkdown.trim()) {
       throw new Error(`Cannot write empty content to ${indexPath}`);
@@ -307,7 +403,23 @@ export async function syncPageIndex(options) {
     // Step 7: Write only if the final content differs from what's currently on disk
     if (currentContent !== finalMarkdown) {
       await writeFile(indexPath, finalMarkdown, 'utf-8');
+    }
 
+    // Pre-populate the page-index cache from the in-memory merged metadata so the
+    // next cold loadServerPageIndex read skips parsing. The cached read-model must
+    // match enrichPageIndex(markdownToMetadata(finalMarkdown)); resolveIndexPageMetadata
+    // mirrors the default metadata block that metadataToMarkdown embeds when rendering,
+    // so a fresh parse and this build agree. Fails fast on a write error.
+    if (cacheDir) {
+      await savePageIndexCache({
+        cacheDir,
+        indexPath,
+        rootContext,
+        markdown: finalMarkdown,
+        metadata: merged.metadata
+      });
+    }
+    if (currentContent !== finalMarkdown) {
       // Create a marker file unless explicitly disabled
       if (markerDir) {
         // Compute relative path for marker (always compute, not used for comments)
@@ -399,7 +511,9 @@ export async function syncPageIndex(options) {
         exclude,
         onlyUpdateIndexes,
         markerDir,
-        errorIfOutOfDate
+        errorIfOutOfDate,
+        cacheDir,
+        rootContext
       });
     }
   }

package/pipeline/syncTypes/generateTypesMarkdown.d.mts

@@ -1,5 +1,5 @@
-import { type TypesMeta } from "../loadServerTypesMeta/index.mjs";
-import { type OrganizeTypesResult } from "../loadServerTypesText/organizeTypesByExport.mjs";
+import type { TypesMeta } from "../loadServerTypesMeta/index.mjs";
+import type { OrganizeTypesResult } from "../loadServerTypesText/organizeTypesByExport.mjs";
 /**
  * Options for generating types markdown.
  */

package/pipeline/syncTypes/syncTypes.d.mts

@@ -62,6 +62,13 @@ export interface SyncTypesOptions {
    * Each entry has a `pattern` (regex string) and `replacement` string.
    */
   descriptionReplacements?: DescriptionReplacement[];
+  /**
+   * Directory for the sha256-validated JSON cache of the types pipeline. When set, after
+   * writing types.md syncTypes pre-populates `{cacheDir}/types-text/{route}.json` with the
+   * parsed `TypesSourceData`, leaving it warm for the next cold `loadServerTypesText` read.
+   * @default undefined (disabled)
+   */
+  cacheDir?: string;
 }
 /**
  * Syncs types for a component/hook/function.

package/pipeline/syncTypes/syncTypes.mjs

@@ -7,6 +7,9 @@ import { loadServerTypesMeta } from "../loadServerTypesMeta/index.mjs";
 import { namespaceParts as defaultNamespacePartsOrder } from "../loadServerTypesText/order.mjs";
 import { generateTypesMarkdown } from "./generateTypesMarkdown.mjs";
 import { syncPageIndex } from "../syncPageIndex/index.mjs";
+import { normalizeTypesSourceDataForCache } from "../loadServerTypesText/normalizeTypesSourceDataForCache.mjs";
+import { TYPES_TEXT_CACHE_NAMESPACE, resolveTypesCacheKey, buildTypesTextCacheContent } from "../loadServerTypesText/resolveTypesCacheKey.mjs";
+import { saveFileCache } from "../cacheUtils/index.mjs";
 const functionName = 'Sync Types';
 /**
  * Helper to process a single TypesMeta and add it to parts, exports, or types.
@@ -174,7 +177,8 @@ export async function syncTypes(options) {
   const {
     typesMarkdownPath,
     rootContext,
-    updateParentIndex
+    updateParentIndex,
+    cacheDir
   } = options;
 
   // Derive relative path for logging
@@ -242,6 +246,30 @@ export async function syncTypes(options) {
     updated = true;
   }
 
+  // Pre-populate the types.md parse cache from the in-memory meta-derived data — no re-parse.
+  // Normalize it to the same JSON shape loadServerTypesText would cache after parsing the
+  // generated markdown, so cache hits and cold parses are byte-for-byte equivalent. This runs even
+  // when types.md is already up to date so validation can warm the parse cache. Fails fast on a
+  // write error.
+  if (cacheDir) {
+    const typesTextData = normalizeTypesSourceDataForCache({
+      exports: organizedExports,
+      additionalTypes: organizedAdditionalTypes,
+      variantOnlyAdditionalTypes: organizedVariantOnlyAdditionalTypes,
+      externalTypes,
+      typeNameMap: typeNameMap ?? {},
+      variantTypeNames,
+      variantTypeNameMaps,
+      allDependencies: [typesMarkdownPath],
+      updated: false
+    });
+    await saveFileCache({
+      cacheDir,
+      namespace: TYPES_TEXT_CACHE_NAMESPACE,
+      cacheKey: resolveTypesCacheKey(typesMarkdownPath, rootContext)
+    }, buildTypesTextCacheContent(markdown, options.ordering), typesTextData);
+  }
+
   // Track allDependencies locally so we can add typesMarkdownPath in production
   const dependencies = [...allDependencies];
   if (process.env.NODE_ENV === 'production') {
@@ -283,6 +311,8 @@ export async function syncTypes(options) {
         markerDir: updateParentIndex.markerDir,
         onlyUpdateIndexes: updateParentIndex.onlyUpdateIndexes ?? false,
         errorIfOutOfDate: updateParentIndex.errorIfOutOfDate,
+        cacheDir: updateParentIndex.cacheDir,
+        rootContext,
         // Auto-generated title/slug from types should not override user-set values
         preserveExistingTitleAndSlug: true
       });

package/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.mjs

@@ -301,7 +301,7 @@ export const transformHtmlCodeBlock = (options = {}) => {
 
               // Parse the source to extract @highlight comments
               // When displayComments is true, we only collect comments but don't strip them
-              const parseResult = await parseImportsAndComments(sourceCode, derivedFilename || 'code.txt', {
+              const parseResult = parseImportsAndComments(sourceCode, derivedFilename || 'code.txt', {
                 removeCommentsWithPrefix: displayComments ? undefined : [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX, ...IGNORE_COMMENT_PREFIXES],
                 notableCommentsPrefix: [EMPHASIS_COMMENT_PREFIX, FOCUS_COMMENT_PREFIX]
               });