@mui/internal-docs-infra 0.11.1-canary.8 → 0.11.1

package/abstractCreateStream/types.d.mts

@@ -0,0 +1,34 @@
+import type * as React from 'react';
+import type { CreateChunkConfig } from "../CoordinatedLazy/types.mjs";
+/**
+ * Options bound by {@link createStreamFactory}. Extends the chunk config with
+ * an optional client provider (e.g. a `ChunkProvider` supplying client loaders,
+ * or a `PreloadProvider`) wrapped around the chunk.
+ *
+ * All loader functions on the config are expected to be dynamically imported by
+ * the caller's module, so they can be bundled (and never called) on the client;
+ * add `import 'server-only'` to a loader module to keep a sensitive loader off
+ * the client entirely.
+ */
+export interface AbstractCreateStreamOptions<T extends {} = {}, P = unknown, O = unknown> extends CreateChunkConfig<T, P, O> {
+  /** Client provider wrapped around the chunk (loaders, preload dedup, etc.). */
+  ClientProvider?: React.ComponentType<{
+    children: React.ReactNode;
+  }>;
+}
+/**
+ * Per-call metadata, injected by the build-time loader (mirrors
+ * `CreateDemoMeta`). `precompute` is the chunk's build-time data, rendered
+ * directly without a client fetch.
+ */
+export interface CreateStreamMeta<P = unknown, O = unknown> {
+  name?: string;
+  slug?: string;
+  displayName?: string;
+  /** Skip build-time precomputation for this call. */
+  skipPrecompute?: boolean;
+  /** Build-time precomputed value, rendered as the chunk's data. */
+  precompute?: P;
+  /** Default loader options for this call. */
+  loaderOptions?: O;
+}

package/abstractCreateStream/types.mjs

@@ -0,0 +1 @@
+export {};

package/abstractCreateTypes/TypeCode.mjs

@@ -4,6 +4,7 @@ import * as React from 'react';
 import { decompressHast, hastToJsx } from "../pipeline/hastUtils/index.mjs";
 import { useCodeComponents } from "../useCode/CodeComponentsContext.mjs";
 import { fallbackToHast, fallbackToText } from "../pipeline/hastUtils/fallbackFormat.mjs";
+import { requestIdle } from "../useCoordinated/scheduleTasks.mjs";
 /**
  * Find the children of the first `<code>` element in a parsed HAST tree.
  */
@@ -50,10 +51,15 @@ export function TypeCode({
   const [isVisible, setIsVisible] = React.useState(effectiveMode !== 'visible');
   const [codeElement, setCodeElement] = React.useState(null);
 
-  // Synchronize visibility state when the effective mode changes.
-  React.useEffect(() => {
+  // Re-seed visibility state during render when the effective mode changes
+  // (the 'store previous prop value, set state during render' pattern). The
+  // IntersectionObserver effect still owns runtime true/false toggling because
+  // it runs after this render-time seed.
+  const [prevEffectiveMode, setPrevEffectiveMode] = React.useState(effectiveMode);
+  if (prevEffectiveMode !== effectiveMode) {
+    setPrevEffectiveMode(effectiveMode);
     setIsVisible(effectiveMode !== 'visible');
-  }, [effectiveMode]);
+  }
 
   // Convert compact fallback to HAST for rendering.
   const fallbackHastRoot = React.useMemo(() => fallback ? fallbackToHast(fallback) : undefined, [fallback]);
@@ -143,14 +149,9 @@ export function TypeCode({
     }
 
     // 'idle' and 'visible' both defer to idle time to avoid blocking the main thread.
-    if (typeof requestIdleCallback !== 'undefined') {
-      const id = requestIdleCallback(parse, {
-        timeout: 2000
-      });
-      return () => cancelIdleCallback(id);
-    }
-    const id = setTimeout(parse, 0);
-    return () => clearTimeout(id);
+    return requestIdle(parse, {
+      timeout: 2000
+    });
   }, [isVisible, hastJson, hastCompressed, effectiveMode, textDictionary]);
   const highlighted = React.useMemo(() => hast !== null ? hastToJsx(hast, components) : null, [hast, components]);
   const content = highlighted ?? fallbackJsx;

package/abstractCreateTypes/typesToJsx.mjs

@@ -157,6 +157,12 @@ function getOrCreateProcessor(enhancers) {
 /**
  * Deserialize a HAST input that may be a live tree, JSON string, or dictionary-compressed base64.
  * Returns the parsed tree and whether it's a fresh copy (no clone needed).
+ *
+ * This function decompresses using the **static dictionary only** (no textContent).
+ * It must only receive payloads that were compressed without a text dictionary.
+ * The deferred rendering path (`hastToJsxDeferred`) re-compresses with a text
+ * dictionary derived from the fallback HAST and passes the fallback as a prop
+ * so the client can reconstruct the same dictionary for decompression.
  */
 function deserializeHast(input) {
   if (typeof input === 'object' && input !== null) {
@@ -293,28 +299,43 @@ function hastToJsxDeferred(hastOrJson, components, enhancers, highlightAt) {
     return hastToJsxBase(hast, components);
   }
 
-  // Build links-only fallback from enhanced inner children
+  // Build links-only fallback from enhanced inner children.
+  // This is passed to the client component as a prop in compact format,
+  // serving two purposes:
+  // 1. Converted to HAST and rendered as the initial display until the full highlight is ready.
+  // 2. Its text is used as DEFLATE dictionary for decompression.
   const linksOnlyRoot = stripHighlightingSpans({
     type: 'root',
     children: [...codeElement.children]
   });
   const fallback = hastToFallback(linksOnlyRoot);
-  const textContent = fallbackToText(fallback);
 
-  // Serialize the enhanced HAST (post-enhancer) for the client.
-  // Compress using the fallback text as a DEFLATE dictionary.
-  // TypeCode derives the same text from the fallback prop
-  // to decompress on the client.
+  // Derive dictionary text from the fallback, then compress the full
+  // highlighted HAST with that dictionary. On the client, TypeCode
+  // calls fallbackToText(fallback) to reconstruct the same dictionary.
+  // Serialize the enhanced HAST (post-enhancer) for the client. DEFLATE-compressing it
+  // (with the fallback text as the dictionary) only shrinks the server→client wire, so
+  // do it ONLY on the server. On the client there is no wire — the JSON is consumed
+  // in-process by TypeCode — so skip the synchronous, main-thread compress and hand it
+  // the JSON directly; TypeCode reads `hastJson` without decompressing (it only rebuilds
+  // the DEFLATE dictionary from `fallback` when it actually has a `hastCompressed`
+  // payload). `typeof window` is the isomorphic server check.
   const enhancedJson = JSON.stringify(hast);
-  const hastCompressed = compressHast(enhancedJson, textContent);
+  const hastPayload = typeof window === 'undefined' ? {
+    hastCompressed: compressHast(enhancedJson, fallbackToText(fallback))
+  } : {
+    hastJson: enhancedJson
+  };
 
   // Find the <pre> element for wrapper props
   const preElement = findPreElement(hast);
   const PreComponent = components?.pre ?? 'pre';
 
-  // Build pre > TypeCode wrapper explicitly
+  // Build pre > TypeCode wrapper explicitly.
+  // fallback crosses the boundary as a serialized prop — no separate
+  // text dictionary string is needed.
   return /*#__PURE__*/React.createElement(PreComponent, hastPropsToReactProps(preElement?.properties), /*#__PURE__*/React.createElement(TypeCode, {
-    hastCompressed,
+    ...hastPayload,
     highlightAt,
     fallback,
     codeProps: hastPropsToReactProps(codeElement.properties)

package/cli/ensureDemoClients.mjs

@@ -1,9 +1,10 @@
-import { readFile, writeFile, readdir, access } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parseCreateFactoryCall } from "../pipeline/parseCreateFactoryCall/parseCreateFactoryCall.mjs";
 import { serializeFunctionArguments } from "../pipeline/parseCreateFactoryCall/serializeFunctionArguments.mjs";
+import { findDemoIndexFiles } from "./findDemoIndexFiles.mjs";
+import { fileExists, formatWithPrettier } from "./fileUtils/index.mjs";
 const CLIENT_FILE_NAME = 'client.ts';
-const INDEX_FILE_NAME = 'index.ts';
 const CLIENT_PROVIDER_IDENTIFIER = 'ClientProvider';
 const CLIENT_RELATIVE_IMPORT = './client';
 /**
@@ -171,117 +172,6 @@ function insertClientProviderImport(source, importsAndComments) {
   return `${source.slice(0, cursor)}\n${importLine}${source.slice(cursor)}`;
 }
 
-/**
- * Converts a Turbopack-style glob (e.g. `./app/**\/demos/*\/index.ts`) to a
- * RegExp that matches absolute filesystem paths. Mirrors the logic used by
- * `withDocsInfra` for webpack rule generation. Pass-through when the input is
- * already a RegExp (webpack-rule `test` regexes).
- */
-function patternToRegExp(pattern) {
-  if (pattern instanceof RegExp) {
-    return pattern;
-  }
-  const SEP = '\u0000SEP\u0000';
-  const NOT_SEP = '\u0000NOT_SEP\u0000';
-  const DOUBLE_STAR = '\u0000DOUBLE_STAR\u0000';
-  const body = pattern.replace(/^\.\//, '') // drop leading ./
-  .replace(/\*\*\//g, DOUBLE_STAR).replace(/\*/g, NOT_SEP).replace(/\./g, '\\.').replace(new RegExp(DOUBLE_STAR, 'g'), `(?:${NOT_SEP}${SEP})*`).replace(/\//g, SEP).replace(new RegExp(NOT_SEP, 'g'), '[^/\\\\]+').replace(new RegExp(SEP, 'g'), '[/\\\\]');
-  return new RegExp(`(?:^|[/\\\\])${body}$`);
-}
-
-/**
- * Finds the longest fixed-prefix directory in a glob pattern so we can avoid
- * walking the entire workspace. Webpack `test` regexes have no extractable
- * prefix, so we fall back to walking from `baseDir`.
- */
-function patternBaseDir(pattern, baseDir) {
-  if (pattern instanceof RegExp) {
-    return baseDir;
-  }
-  const stripped = pattern.replace(/^\.\//, '');
-  const segments = stripped.split('/');
-  const fixed = [];
-  for (const segment of segments) {
-    if (segment.includes('*')) {
-      break;
-    }
-    fixed.push(segment);
-  }
-  return path.join(baseDir, ...fixed);
-}
-async function findIndexFilesForPatterns(baseDir, patterns) {
-  // Map from absolute index.ts path → matching pattern (first wins).
-  const results = new Map();
-  // Group patterns by their fixed prefix to share filesystem walks.
-  const prefixes = new Map();
-  for (const pattern of patterns) {
-    const prefix = patternBaseDir(pattern, baseDir);
-    const existing = prefixes.get(prefix);
-    if (existing) {
-      existing.push(pattern);
-    } else {
-      prefixes.set(prefix, [pattern]);
-    }
-  }
-  const compiledPatterns = patterns.map(pattern => ({
-    pattern,
-    regex: patternToRegExp(pattern)
-  }));
-  await Promise.all(Array.from(prefixes.keys()).map(async prefix => {
-    const indexFiles = await collectIndexFiles(prefix);
-    for (const filePath of indexFiles) {
-      if (results.has(filePath)) {
-        continue;
-      }
-      for (const {
-        pattern,
-        regex
-      } of compiledPatterns) {
-        if (regex.test(filePath)) {
-          results.set(filePath, pattern);
-          break;
-        }
-      }
-    }
-  }));
-  return results;
-}
-async function collectIndexFiles(dir) {
-  const out = [];
-  let entries;
-  try {
-    entries = await readdir(dir, {
-      withFileTypes: true
-    });
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      return out;
-    }
-    throw error;
-  }
-  await Promise.all(entries.map(async entry => {
-    if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
-      return;
-    }
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      const sub = await collectIndexFiles(full);
-      out.push(...sub);
-    } else if (entry.isFile() && entry.name === INDEX_FILE_NAME) {
-      out.push(full);
-    }
-  }));
-  return out;
-}
-async function fileExists(filePath) {
-  try {
-    await access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Ensures every demo `index.ts` matched by the configured demo patterns has a
  * sibling `client.ts` and that the `index.ts` wires it up via `ClientProvider`.
@@ -306,7 +196,7 @@ export async function ensureDemoClients(options) {
   // Group requirements by import specifier so each pattern uses its declared value.
   const patterns = requirements.map(entry => entry.pattern);
   const requireClientByPattern = new Map(requirements.map(entry => [entry.pattern, entry.requireClient]));
-  const indexFiles = await findIndexFilesForPatterns(baseDir, patterns);
+  const indexFiles = await findDemoIndexFiles(baseDir, patterns);
   const updatedFiles = [];
   const errors = [];
   await Promise.all(Array.from(indexFiles.entries()).map(async ([indexPath, pattern]) => {
@@ -348,38 +238,4 @@ export async function ensureDemoClients(options) {
     updatedFiles,
     errors
   };
-}
-
-/**
- * Cached prettier module reference. Resolved lazily on first use so the
- * dependency stays optional — if the consumer doesn't have prettier installed,
- * we silently return the unformatted content.
- */
-
-let prettierModulePromise;
-async function loadPrettier() {
-  if (!prettierModulePromise) {
-    prettierModulePromise = import('prettier').catch(() => null);
-  }
-  return prettierModulePromise;
-}
-
-/**
- * Formats `content` with the project's prettier configuration for `filePath`.
- * Falls back to the original content when prettier is not installed or fails.
- */
-async function formatWithPrettier(content, filePath) {
-  const prettier = await loadPrettier();
-  if (!prettier) {
-    return content;
-  }
-  try {
-    const config = await prettier.resolveConfig(filePath);
-    return await prettier.format(content, {
-      ...config,
-      filepath: filePath
-    });
-  } catch {
-    return content;
-  }
 }

package/cli/ensureDemoPages.d.mts

@@ -0,0 +1,45 @@
+import type { DemoPageRequirement } from "./loadNextConfig.mjs";
+export interface EnsureDemoPagesOptions {
+  /** Workspace root used to resolve glob patterns. */
+  baseDir: string;
+  /** Patterns extracted from next.config that opted into `page.tsx` generation. */
+  requirements: DemoPageRequirement[];
+}
+export interface EnsureDemoPagesResult {
+  /** Total number of demo `index.ts` files matched across all patterns. */
+  demoCount: number;
+  /** Workspace-relative paths of files that were created. */
+  updatedFiles: string[];
+  /** Errors encountered during the run. */
+  errors: {
+    filePath: string;
+    message: string;
+  }[];
+}
+/**
+ * Generates the contents for an auto-created demo `page.tsx`. The page renders
+ * the demo's named export from the sibling `index.ts` inside a `Page` component,
+ * so the demo renders as its own route.
+ *
+ * Exported for tests and reuse.
+ */
+export declare function generatePageFileContent(exportName: string): string;
+/**
+ * Reads the demo's export name from a demo `index.ts` by reusing the same
+ * `create*` factory parser the precomputed code highlighter loader uses to load
+ * variants. Returns `null` when no named `export const X = create*(...)` is
+ * found (e.g. an anonymous default export), since a re-export page needs a name
+ * to import.
+ *
+ * Exported for tests.
+ */
+export declare function findDemoExportName(source: string, filePath: string): Promise<string | null>;
+/**
+ * Ensures every demo `index.ts` matched by the configured demo patterns has a
+ * sibling `page.tsx` that renders the demo as the route's default export.
+ *
+ * Existing `page.tsx`/`page.ts` files are left untouched so developers can
+ * customise the page (e.g. wrap the demo with additional layout). Returns the
+ * list of files that were created, plus any errors encountered.
+ */
+export declare function ensureDemoPages(options: EnsureDemoPagesOptions): Promise<EnsureDemoPagesResult>;

package/cli/ensureDemoPages.mjs

@@ -0,0 +1,99 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseAllCreateFactoryCalls } from "../pipeline/parseCreateFactoryCall/parseCreateFactoryCall.mjs";
+import { findDemoIndexFiles } from "./findDemoIndexFiles.mjs";
+import { fileExists, formatWithPrettier } from "./fileUtils/index.mjs";
+const PAGE_TS_FILE_NAME = 'page.ts';
+const PAGE_TSX_FILE_NAME = 'page.tsx';
+const UNKNOWN_EXPORT_NAME = 'unknown';
+/**
+ * Generates the contents for an auto-created demo `page.tsx`. The page renders
+ * the demo's named export from the sibling `index.ts` inside a `Page` component,
+ * so the demo renders as its own route.
+ *
+ * Exported for tests and reuse.
+ */
+export function generatePageFileContent(exportName) {
+  return [`import * as React from 'react';`, `import { ${exportName} } from '.';`, ``, `export default function Page() {`, `  return <${exportName} />;`, `}`, ``].join('\n');
+}
+
+/**
+ * Reads the demo's export name from a demo `index.ts` by reusing the same
+ * `create*` factory parser the precomputed code highlighter loader uses to load
+ * variants. Returns `null` when no named `export const X = create*(...)` is
+ * found (e.g. an anonymous default export), since a re-export page needs a name
+ * to import.
+ *
+ * Exported for tests.
+ */
+export async function findDemoExportName(source, filePath) {
+  const factories = await parseAllCreateFactoryCalls(source, filePath, {
+    allowExternalVariants: true
+  });
+  const exportName = Object.keys(factories).find(name => name !== UNKNOWN_EXPORT_NAME);
+  return exportName ?? null;
+}
+
+/**
+ * Ensures every demo `index.ts` matched by the configured demo patterns has a
+ * sibling `page.tsx` that renders the demo as the route's default export.
+ *
+ * Existing `page.tsx`/`page.ts` files are left untouched so developers can
+ * customise the page (e.g. wrap the demo with additional layout). Returns the
+ * list of files that were created, plus any errors encountered.
+ */
+export async function ensureDemoPages(options) {
+  const {
+    baseDir,
+    requirements
+  } = options;
+  if (requirements.length === 0) {
+    return {
+      demoCount: 0,
+      updatedFiles: [],
+      errors: []
+    };
+  }
+  const patterns = requirements.map(entry => entry.pattern);
+  const indexFiles = await findDemoIndexFiles(baseDir, patterns);
+  const updatedFiles = [];
+  const errors = [];
+  await Promise.all(Array.from(indexFiles.keys()).map(async indexPath => {
+    try {
+      const dir = path.dirname(indexPath);
+      const pageTsPath = path.join(dir, PAGE_TS_FILE_NAME);
+      const pageTsxPath = path.join(dir, PAGE_TSX_FILE_NAME);
+
+      // Only generate the page when neither a .ts nor .tsx page exists. Existing
+      // pages are left alone so developers can wrap the demo with extra layout.
+      const [pageTsExists, pageTsxExists] = await Promise.all([fileExists(pageTsPath), fileExists(pageTsxPath)]);
+      if (pageTsExists || pageTsxExists) {
+        return;
+      }
+      const indexSource = await readFile(indexPath, 'utf-8');
+      const exportName = await findDemoExportName(indexSource, indexPath);
+      if (!exportName) {
+        errors.push({
+          filePath: path.relative(baseDir, indexPath),
+          message: 'Could not determine the demo export name from a create* factory call.'
+        });
+        return;
+      }
+      const generated = generatePageFileContent(exportName);
+      const formatted = await formatWithPrettier(generated, pageTsxPath);
+      await writeFile(pageTsxPath, formatted, 'utf-8');
+      updatedFiles.push(path.relative(baseDir, pageTsxPath));
+    } catch (error) {
+      errors.push({
+        filePath: path.relative(baseDir, indexPath),
+        message: error?.message ?? String(error)
+      });
+    }
+  }));
+  updatedFiles.sort();
+  return {
+    demoCount: indexFiles.size,
+    updatedFiles,
+    errors
+  };
+}

package/cli/fileUtils/index.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Returns whether a path exists on disk. Used to decide whether an
+ * auto-generated sibling file (e.g. `client.ts`, `page.ts`) already exists so
+ * the validate passes never overwrite developer-authored files.
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Formats `content` with the project's prettier configuration for `filePath`.
+ * Falls back to the original content when prettier is not installed or fails.
+ */
+export declare function formatWithPrettier(content: string, filePath: string): Promise<string>;

package/cli/fileUtils/index.mjs

@@ -0,0 +1,48 @@
+import { access } from 'node:fs/promises';
+/**
+ * Returns whether a path exists on disk. Used to decide whether an
+ * auto-generated sibling file (e.g. `client.ts`, `page.ts`) already exists so
+ * the validate passes never overwrite developer-authored files.
+ */
+export async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Cached prettier module reference. Resolved lazily on first use so the
+ * dependency stays optional — if the consumer doesn't have prettier installed,
+ * formatting is skipped and the unformatted content is returned.
+ */
+
+let prettierModulePromise;
+async function loadPrettier() {
+  if (!prettierModulePromise) {
+    prettierModulePromise = import('prettier').catch(() => null);
+  }
+  return prettierModulePromise;
+}
+
+/**
+ * Formats `content` with the project's prettier configuration for `filePath`.
+ * Falls back to the original content when prettier is not installed or fails.
+ */
+export async function formatWithPrettier(content, filePath) {
+  const prettier = await loadPrettier();
+  if (!prettier) {
+    return content;
+  }
+  try {
+    const config = await prettier.resolveConfig(filePath);
+    return await prettier.format(content, {
+      ...config,
+      filepath: filePath
+    });
+  } catch {
+    return content;
+  }
+}

package/cli/findDemoIndexFiles.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Converts a Turbopack-style glob (e.g. `./app/**\/demos/*\/index.ts`) to a
+ * RegExp that matches absolute filesystem paths. Mirrors the logic used by
+ * `withDocsInfra` for webpack rule generation. Pass-through when the input is
+ * already a RegExp (webpack-rule `test` regexes).
+ */
+export declare function patternToRegExp(pattern: string | RegExp): RegExp;
+/**
+ * Walks the workspace once per fixed glob prefix and returns a map from each
+ * matched demo `index.ts` absolute path to the first pattern that matched it.
+ *
+ * Shared by `ensureDemoClients` and `ensureDemoPages` so demo discovery stays
+ * consistent between the `requireClient` and `requirePage` validate passes.
+ */
+export declare function findDemoIndexFiles(baseDir: string, patterns: (string | RegExp)[]): Promise<Map<string, string | RegExp>>;

package/cli/findDemoIndexFiles.mjs

@@ -0,0 +1,121 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+const INDEX_FILE_NAME = 'index.ts';
+
+/**
+ * Converts a Turbopack-style glob (e.g. `./app/**\/demos/*\/index.ts`) to a
+ * RegExp that matches absolute filesystem paths. Mirrors the logic used by
+ * `withDocsInfra` for webpack rule generation. Pass-through when the input is
+ * already a RegExp (webpack-rule `test` regexes).
+ */
+export function patternToRegExp(pattern) {
+  if (pattern instanceof RegExp) {
+    return pattern;
+  }
+  // Sentinels are wrapped in NUL bytes, which cannot occur in a file path or
+  // glob. That makes them un-forgeable: the two-pass token substitution below
+  // can never synthesize a sentinel by concatenating literal input with inserted
+  // replacement output (e.g. an input segment ending in "NOT_" fusing with a
+  // freshly-inserted separator). Built via fromCharCode so the source carries no
+  // literal NUL bytes.
+  const NUL = String.fromCharCode(0);
+  const SEP = `${NUL}SEP${NUL}`;
+  const NOT_SEP = `${NUL}NOT_SEP${NUL}`;
+  const DOUBLE_STAR = `${NUL}DOUBLE_STAR${NUL}`;
+  const body = pattern.replace(/^\.\//, '') // drop leading ./
+  .replace(/\*\*\//g, DOUBLE_STAR).replace(/\*/g, NOT_SEP).replace(/\./g, '\\.').replace(new RegExp(DOUBLE_STAR, 'g'), `(?:${NOT_SEP}${SEP})*`).replace(/\//g, SEP).replace(new RegExp(NOT_SEP, 'g'), '[^/\\\\]+').replace(new RegExp(SEP, 'g'), '[/\\\\]');
+  return new RegExp(`(?:^|[/\\\\])${body}$`);
+}
+
+/**
+ * Finds the longest fixed-prefix directory in a glob pattern so we can avoid
+ * walking the entire workspace. Webpack `test` regexes have no extractable
+ * prefix, so we fall back to walking from `baseDir`.
+ */
+function patternBaseDir(pattern, baseDir) {
+  if (pattern instanceof RegExp) {
+    return baseDir;
+  }
+  const stripped = pattern.replace(/^\.\//, '');
+  const segments = stripped.split('/');
+  const fixed = [];
+  for (const segment of segments) {
+    if (segment.includes('*')) {
+      break;
+    }
+    fixed.push(segment);
+  }
+  return path.join(baseDir, ...fixed);
+}
+async function collectIndexFiles(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = await readdir(dir, {
+      withFileTypes: true
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return out;
+    }
+    throw error;
+  }
+  await Promise.all(entries.map(async entry => {
+    if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+      return;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const sub = await collectIndexFiles(full);
+      out.push(...sub);
+    } else if (entry.isFile() && entry.name === INDEX_FILE_NAME) {
+      out.push(full);
+    }
+  }));
+  return out;
+}
+
+/**
+ * Walks the workspace once per fixed glob prefix and returns a map from each
+ * matched demo `index.ts` absolute path to the first pattern that matched it.
+ *
+ * Shared by `ensureDemoClients` and `ensureDemoPages` so demo discovery stays
+ * consistent between the `requireClient` and `requirePage` validate passes.
+ */
+export async function findDemoIndexFiles(baseDir, patterns) {
+  // Map from absolute index.ts path → matching pattern (first wins).
+  const results = new Map();
+  // Group patterns by their fixed prefix to share filesystem walks.
+  const prefixes = new Map();
+  for (const pattern of patterns) {
+    const prefix = patternBaseDir(pattern, baseDir);
+    const existing = prefixes.get(prefix);
+    if (existing) {
+      existing.push(pattern);
+    } else {
+      prefixes.set(prefix, [pattern]);
+    }
+  }
+  const compiledPatterns = patterns.map(pattern => ({
+    pattern,
+    regex: patternToRegExp(pattern)
+  }));
+  await Promise.all(Array.from(prefixes.keys()).map(async prefix => {
+    const indexFiles = await collectIndexFiles(prefix);
+    for (const filePath of indexFiles) {
+      if (results.has(filePath)) {
+        continue;
+      }
+      for (const {
+        pattern,
+        regex
+      } of compiledPatterns) {
+        if (regex.test(filePath)) {
+          results.set(filePath, pattern);
+          break;
+        }
+      }
+    }
+  }));
+  return results;
+}

package/cli/index.mjs

@@ -8,4 +8,4 @@ function getVersion() {
 }
 yargs().scriptName('docs-infra').usage('$0 <command> [args]').command(runValidate).command(runBrowser).demandCommand(1, 'You need at least one command before moving on').strict().help()
 // MUI_VERSION is set through the code-infra build command.
-.version("0.11.0" || getVersion()).parse(hideBin(process.argv));
+.version("0.11.1" || getVersion()).parse(hideBin(process.argv));