@mui/internal-docs-infra 0.11.1-canary.17 → 0.11.1-canary.19

package/CodeHighlighter/CodeHighlighterClient.mjs

@@ -1025,7 +1025,15 @@ export function CodeHighlighterClient(props) {
     }
     let restored = residualMap ? scatterResidualFallbacks(base, residualMap) : base;
     if (!props.fallbackCollapsed) {
-      restored = scatterResidualFallbacks(restored, hoistedFallbackHasts);
+      // `preserveExisting`: never let the hoist overwrite a `fallback` already
+      // on the variant. A fully-loaded `hastCompressed` source carries its own
+      // source-paired (structured) `fallback`, which is the only valid DEFLATE
+      // dictionary. The hoist can be an un-highlighted *raw-string* fallback
+      // whose text keeps a trailing newline `buildRootFallback` drops, so
+      // overwriting the structured one makes `decodeHastSource` throw a
+      // dictionary mismatch. The hoist is the dictionary only when the variant's
+      // own was stripped, so apply it solely where one isn't already present.
+      restored = scatterResidualFallbacks(restored, hoistedFallbackHasts, true);
     }
     return restored;
   }, [residualMap, hoistedFallbackHasts, props.fallbackCollapsed]);

package/CodeHighlighter/buildStringFallback.d.mts

@@ -0,0 +1,29 @@
+import type { SourceComments, SourceEnhancers } from "./types.mjs";
+import { type FallbackNode } from "./fallbackFormat.mjs";
+export interface StringFallbackResult {
+  /** Compact, windowed fallback frames (text only — `.line` spans stripped). */
+  fallback: FallbackNode[];
+  /** Total source lines. */
+  totalLines: number;
+  /** Lines visible in the collapsed window (the sum of visible frame sizes). */
+  focusedLines: number;
+  /** Whether the enhanced frame structure has hidden content to expand into. */
+  collapsible: boolean;
+}
+/**
+ * Derive a *windowed* fallback for a plain-string source by running the same
+ * `sourceEnhancers` the live render uses over a cheap line-guttered HAST
+ * (`parsePlainText` — gutters, no syntax highlighting). The inline-string
+ * fallback path otherwise wraps the whole source in one un-windowed focus frame,
+ * so an oversized / `@focus` / `@highlight` block paints its full text before
+ * hydration then snaps to the collapsed window. Running the enhancers here makes
+ * the loading frames match the live render, and the resulting `root.data` carries
+ * the `totalLines` / `focusedLines` the compact fallback can't preserve.
+ *
+ * Synchronous by design — it runs at server fallback-prep time inside the
+ * (sync) `prepareInitialSource`. An enhancer that returns a promise is skipped
+ * (returns `undefined`) so the caller falls back to the naive single-frame wrap
+ * rather than blocking; the built-in `enhanceCodeEmphasis` is synchronous, so
+ * the common case windows.
+ */
+export declare function buildStringFallback(source: string, comments: SourceComments | undefined, fileName: string, sourceEnhancers: SourceEnhancers): StringFallbackResult | undefined;

package/CodeHighlighter/buildStringFallback.mjs

@@ -0,0 +1,42 @@
+import { buildRootFallback } from "./fallbackFormat.mjs";
+import { parsePlainText } from "../pipeline/parseSource/index.mjs";
+function isPromiseLike(value) {
+  return typeof value === 'object' && value !== null && typeof value.then === 'function';
+}
+
+/**
+ * Derive a *windowed* fallback for a plain-string source by running the same
+ * `sourceEnhancers` the live render uses over a cheap line-guttered HAST
+ * (`parsePlainText` — gutters, no syntax highlighting). The inline-string
+ * fallback path otherwise wraps the whole source in one un-windowed focus frame,
+ * so an oversized / `@focus` / `@highlight` block paints its full text before
+ * hydration then snaps to the collapsed window. Running the enhancers here makes
+ * the loading frames match the live render, and the resulting `root.data` carries
+ * the `totalLines` / `focusedLines` the compact fallback can't preserve.
+ *
+ * Synchronous by design — it runs at server fallback-prep time inside the
+ * (sync) `prepareInitialSource`. An enhancer that returns a promise is skipped
+ * (returns `undefined`) so the caller falls back to the naive single-frame wrap
+ * rather than blocking; the built-in `enhanceCodeEmphasis` is synchronous, so
+ * the common case windows.
+ */
+export function buildStringFallback(source, comments, fileName, sourceEnhancers) {
+  let root = parsePlainText(source);
+  for (const enhancer of sourceEnhancers) {
+    const result = enhancer(root, comments, fileName);
+    if (isPromiseLike(result)) {
+      return undefined;
+    }
+    root = result;
+  }
+  const data = root.data;
+  const totalLines = data?.totalLines ?? 0;
+  const focusedLines = data?.focusedLines ?? totalLines;
+  const collapsible = data?.collapsible === true;
+  return {
+    fallback: buildRootFallback(root),
+    totalLines,
+    focusedLines,
+    collapsible
+  };
+}

package/CodeHighlighter/codeToFallbackProps.d.mts

@@ -1,5 +1,8 @@
 import type { BaseContentLoadingProps, Code, Fallbacks } from "./types.mjs";
-export declare function codeToFallbackProps(variant: string, code?: Code, _fileName?: string, _needsAllFiles?: boolean, needsAllVariants?: boolean, allFallbackHasts?: Record<string, Fallbacks>): BaseContentLoadingProps;
+import { type SourceLineCounts } from "../useCode/sourceLineCounts.mjs";
+/** Per-variant → per-file line metadata threaded for the fallback. */
+export type LineCountsByVariant = Record<string, Record<string, SourceLineCounts>>;
+export declare function codeToFallbackProps(variant: string, code?: Code, _fileName?: string, _needsAllFiles?: boolean, needsAllVariants?: boolean, allFallbackHasts?: Record<string, Fallbacks>, allLineCounts?: LineCountsByVariant): BaseContentLoadingProps;
 /**
  * Read a variant's per-file fallbacks straight off its `VariantCode` `fallback`
  * fields (main + extra files), returning a `Fallbacks` map keyed by file name.

package/CodeHighlighter/codeToFallbackProps.mjs

@@ -1,5 +1,8 @@
 import { hastToFallback } from "./fallbackFormat.mjs";
 import { getLanguageFromExtension } from "../pipeline/loaderUtils/getLanguageFromExtension.mjs";
+import { getVariantFileLineCounts } from "../useCode/sourceLineCounts.mjs";
+
+/** Per-variant → per-file line metadata threaded for the fallback. */
 
 /**
  * Resolve a `language-{language}` hint for a file from its extension, used to
@@ -23,9 +26,10 @@ function getLanguageFromFileName(fileName) {
  * one from the source for live/dev trees that never went through the loader.
  *
  * A plain-string source (an unparsed code block, e.g. `<CodeHighlighter>{code}`)
- * becomes a single text node so the fallback renders the raw code before
- * highlighting. `hastCompressed` payloads can't be decoded here (no DEFLATE
- * dictionary), so without a variant `fallback` they yield `undefined`.
+ * is wrapped in a single focus frame so the fallback always has the same frame
+ * structure as the highlighted render — never a bare text node. `hastCompressed`
+ * payloads can't be decoded here (no DEFLATE dictionary), so without a variant
+ * `fallback` they yield `undefined`.
  */
 function sourceToFallback(source, fallback) {
   if (fallback) {
@@ -35,8 +39,13 @@ function sourceToFallback(source, fallback) {
     return undefined;
   }
   if (typeof source === 'string') {
-    // A `FallbackNode` string is a text node — render the raw code as-is.
-    return [source];
+    // Wrap the raw code in a single focus frame so the fallback always carries a
+    // frame, matching the highlighted render (`buildRootFallback` likewise emits
+    // frames with text children) — never a bare text node. The whole source is
+    // the visible window; collapse-to-empty demotes it like any other focus frame.
+    return [['span', 'frame', {
+      dataFrameType: 'focus'
+    }, source]];
   }
   if ('type' in source && source.type === 'root') {
     return hastToFallback(source);
@@ -57,9 +66,40 @@ function sourceToFallback(source, fallback) {
  * `source` is present, mirroring how consumers gate the `language-{language}`
  * class behind a rendered source.
  */
-function deriveVariantSources(variantCode, variantHasts) {
+function deriveVariantSources(variantCode, variantHasts, variantLineCounts) {
   const fileNames = [variantCode.fileName, ...Object.keys(variantCode.extraFiles || {})].filter(name => Boolean(name));
   const mainFile = variantCode.fileName || fileNames[0];
+
+  // Per-file line counts: prefer render-time windowing (`variantLineCounts`), else
+  // the counts the loader stored on the code (`VariantCode` / extra-file `totalLines`
+  // / `focusedLines`). So every file/variant carries its window, not just the main one.
+  const fileCounts = fileName => {
+    const threaded = variantLineCounts?.[fileName];
+    if (threaded) {
+      return threaded;
+    }
+    const file = variantCode.fileName === fileName ? variantCode : variantCode.extraFiles?.[fileName];
+    if (file && typeof file !== 'string' && file.totalLines !== undefined) {
+      return {
+        totalLines: file.totalLines,
+        focusedLines: file.focusedLines ?? file.totalLines,
+        collapsible: file.collapsible === true
+      };
+    }
+    // Last resort: count lines off the source (a plain string with no enhancers ⇒
+    // `focusedLines === totalLines`, matching `<Pre>`'s `getSourceLineCounts`). Guarded
+    // because a `hastCompressed` source can't be decoded without its dictionary (which
+    // the server strips before this runs) — the server passes `variantLineCounts`
+    // instead, so this branch only really fires client-side where the dictionary is on
+    // the code.
+    try {
+      const counts = getVariantFileLineCounts(variantCode, fileName);
+      // `totalLines === 0` means a hast with no `root.data` counts (not a real count).
+      return counts && counts.totalLines > 0 ? counts : undefined;
+    } catch {
+      return undefined;
+    }
+  };
   let source;
   let extraSource;
   if (variantHasts) {
@@ -70,7 +110,10 @@ function deriveVariantSources(variantCode, variantHasts) {
     const extra = {};
     for (const [fName, nodes] of Object.entries(variantHasts)) {
       if (fName !== mainFile) {
-        extra[fName] = nodes;
+        extra[fName] = {
+          source: nodes,
+          ...fileCounts(fName)
+        };
       }
     }
     if (Object.keys(extra).length > 0) {
@@ -85,7 +128,10 @@ function deriveVariantSources(variantCode, variantHasts) {
       if (typeof fData === 'object' && fData.source) {
         const fb = sourceToFallback(fData.source, fData.fallback);
         if (fb) {
-          extra[fName] = fb;
+          extra[fName] = {
+            source: fb,
+            ...fileCounts(fName)
+          };
         }
       }
     }
@@ -94,9 +140,13 @@ function deriveVariantSources(variantCode, variantHasts) {
     }
   }
   const language = source ? variantCode.language ?? getLanguageFromFileName(mainFile) : undefined;
+  const mainCounts = source && mainFile ? fileCounts(mainFile) : undefined;
   return {
     fileNames,
     source,
+    totalLines: mainCounts?.totalLines,
+    focusedLines: mainCounts?.focusedLines,
+    collapsible: mainCounts?.collapsible,
     extraSource,
     language
   };
@@ -107,7 +157,7 @@ export function codeToFallbackProps(variant, code,
 // upstream in `stripFallbackHastsFromCode` (which only hoists the allowed
 // files into `allFallbackHasts`), so the derivation below reads them off the
 // already-gated `allFallbackHasts` rather than re-applying the flags here.
-_fileName, _needsAllFiles = false, needsAllVariants = false, allFallbackHasts) {
+_fileName, _needsAllFiles = false, needsAllVariants = false, allFallbackHasts, allLineCounts) {
   const variantCode = code?.[variant];
   if (!variantCode || typeof variantCode === 'string') {
     return {};
@@ -115,23 +165,38 @@ _fileName, _needsAllFiles = false, needsAllVariants = false, allFallbackHasts) {
   const {
     fileNames,
     source,
+    totalLines,
+    focusedLines,
+    collapsible,
     extraSource,
     language
-  } = deriveVariantSources(variantCode, allFallbackHasts?.[variant]);
+  } = deriveVariantSources(variantCode, allFallbackHasts?.[variant], allLineCounts?.[variant]);
   if (needsAllVariants) {
     const extraVariants = Object.entries(code || {}).reduce((acc, [name, vCode]) => {
       if (name !== variant && vCode && typeof vCode !== 'string') {
         const {
           fileNames: evFileNames,
           source: evSource,
+          totalLines: evTotalLines,
+          focusedLines: evFocusedLines,
+          collapsible: evCollapsible,
           extraSource: evExtraSource,
           language: evLanguage
-        } = deriveVariantSources(vCode, allFallbackHasts?.[name]);
+        } = deriveVariantSources(vCode, allFallbackHasts?.[name], allLineCounts?.[name]);
         acc[name] = {
           fileNames: evFileNames,
           ...(evSource ? {
             source: evSource
           } : undefined),
+          ...(evTotalLines !== undefined ? {
+            totalLines: evTotalLines
+          } : undefined),
+          ...(evFocusedLines !== undefined ? {
+            focusedLines: evFocusedLines
+          } : undefined),
+          ...(evCollapsible !== undefined ? {
+            collapsible: evCollapsible
+          } : undefined),
           ...(evLanguage ? {
             language: evLanguage
           } : undefined),
@@ -147,6 +212,15 @@ _fileName, _needsAllFiles = false, needsAllVariants = false, allFallbackHasts) {
       ...(source ? {
         source
       } : undefined),
+      ...(totalLines !== undefined ? {
+        totalLines
+      } : undefined),
+      ...(focusedLines !== undefined ? {
+        focusedLines
+      } : undefined),
+      ...(collapsible !== undefined ? {
+        collapsible
+      } : undefined),
       ...(language ? {
         language
       } : undefined),
@@ -161,6 +235,15 @@ _fileName, _needsAllFiles = false, needsAllVariants = false, allFallbackHasts) {
     ...(source ? {
       source
     } : undefined),
+    ...(totalLines !== undefined ? {
+      totalLines
+    } : undefined),
+    ...(focusedLines !== undefined ? {
+      focusedLines
+    } : undefined),
+    ...(collapsible !== undefined ? {
+      collapsible
+    } : undefined),
     ...(language ? {
       language
     } : undefined),

package/CodeHighlighter/createClientProps.mjs

@@ -25,7 +25,16 @@ export function createClientProps(props) {
     name: props.name,
     slug: props.slug,
     url,
-    variantType: props.variantType
+    variantType: props.variantType,
+    // Thread the render-time display flags into the content channel so both
+    // `useCode`/`<Pre>` and the loading fallback honor them. A top-level prop
+    // wins over one already present in `contentProps`.
+    ...(props.collapseToEmpty !== undefined ? {
+      collapseToEmpty: props.collapseToEmpty
+    } : undefined),
+    ...(props.initialExpanded !== undefined ? {
+      initialExpanded: props.initialExpanded
+    } : undefined)
   };
   return {
     url,

package/CodeHighlighter/fallbackCompression.d.mts

@@ -61,16 +61,33 @@ export declare function extractResidualFallbacks(code: Code): {
  * non-consolidated payload would have had, so downstream consumers are unaware
  * the residual ever travelled compressed.
  *
+ * `preserveExisting` keeps any `fallback` already on the variant/extra file
+ * instead of overwriting it. The hoisted-fallback scatter passes `true`: the
+ * hoist is an *initial-paint* dictionary that, for an un-highlighted load, is a
+ * raw-string fallback whose text keeps a trailing newline that `buildRootFallback`
+ * drops — so it's the WRONG DEFLATE dictionary for a fully-loaded `hastCompressed`
+ * source, which already carries its own source-paired (structured) `fallback`.
+ * Overwriting that with the hoist makes `decodeHastSource` throw a dictionary
+ * mismatch. The hoist is only the dictionary when the variant's own was stripped,
+ * so apply it only where one isn't already present. The residual-blob scatter
+ * keeps the default (`false`): it always writes onto server-stripped, fallback-less
+ * variants, so there is nothing to preserve.
+ *
  * Pure: only the variants that regain a fallback are shallow-cloned.
  */
-export declare function scatterResidualFallbacks(code: Code, residual: ResidualFallbacks): Code;
+export declare function scatterResidualFallbacks(code: Code, residual: ResidualFallbacks, preserveExisting?: boolean): Code;
 /**
  * Reduce every fallback in a rendered-subset map to its collapsed window (see
  * `collapsedVisibleFallback`). Used by `fallbackCollapsed` to hand
  * `ContentLoading` only the on-screen lines while the full fallbacks ride along
  * in the residual blob.
+ *
+ * `collapsesToEmpty(variantName, fileName)` reports the `oversizedFocus: 'hide'`
+ * collapse-to-nothing case (the source's `focusedLines === 0`): such files get
+ * an empty collapsed window so the loading UI matches the hydrated render
+ * instead of briefly painting the first frame.
  */
-export declare function collapseRenderedFallbacks(rendered: ResidualFallbacks): ResidualFallbacks;
+export declare function collapseRenderedFallbacks(rendered: ResidualFallbacks, collapsesToEmpty?: (variantName: string, fileName: string) => boolean): ResidualFallbacks;
 /**
  * Deep-merge two residual maps (`variant → fileName → fallback`), with `b`
  * winning on conflicts. Used to fold the rendered files' full fallbacks into

package/CodeHighlighter/fallbackCompression.mjs

@@ -146,9 +146,21 @@ export function extractResidualFallbacks(code) {
  * non-consolidated payload would have had, so downstream consumers are unaware
  * the residual ever travelled compressed.
  *
+ * `preserveExisting` keeps any `fallback` already on the variant/extra file
+ * instead of overwriting it. The hoisted-fallback scatter passes `true`: the
+ * hoist is an *initial-paint* dictionary that, for an un-highlighted load, is a
+ * raw-string fallback whose text keeps a trailing newline that `buildRootFallback`
+ * drops — so it's the WRONG DEFLATE dictionary for a fully-loaded `hastCompressed`
+ * source, which already carries its own source-paired (structured) `fallback`.
+ * Overwriting that with the hoist makes `decodeHastSource` throw a dictionary
+ * mismatch. The hoist is only the dictionary when the variant's own was stripped,
+ * so apply it only where one isn't already present. The residual-blob scatter
+ * keeps the default (`false`): it always writes onto server-stripped, fallback-less
+ * variants, so there is nothing to preserve.
+ *
  * Pure: only the variants that regain a fallback are shallow-cloned.
  */
-export function scatterResidualFallbacks(code, residual) {
+export function scatterResidualFallbacks(code, residual, preserveExisting = false) {
   const restored = {};
   for (const [variantName, variant] of Object.entries(code)) {
     const files = residual[variantName];
@@ -160,6 +172,9 @@ export function scatterResidualFallbacks(code, residual) {
     let nextExtraFiles;
     for (const [fileName, fallback] of Object.entries(files)) {
       if (fileName === variant.fileName) {
+        if (preserveExisting && nextVariant.fallback) {
+          continue;
+        }
         nextVariant = {
           ...nextVariant,
           fallback
@@ -167,6 +182,9 @@ export function scatterResidualFallbacks(code, residual) {
       } else {
         const fileData = variant.extraFiles?.[fileName];
         if (fileData && typeof fileData === 'object') {
+          if (preserveExisting && fileData.fallback) {
+            continue;
+          }
           if (!nextExtraFiles) {
             nextExtraFiles = {
               ...variant.extraFiles
@@ -195,13 +213,18 @@ export function scatterResidualFallbacks(code, residual) {
  * `collapsedVisibleFallback`). Used by `fallbackCollapsed` to hand
  * `ContentLoading` only the on-screen lines while the full fallbacks ride along
  * in the residual blob.
+ *
+ * `collapsesToEmpty(variantName, fileName)` reports the `oversizedFocus: 'hide'`
+ * collapse-to-nothing case (the source's `focusedLines === 0`): such files get
+ * an empty collapsed window so the loading UI matches the hydrated render
+ * instead of briefly painting the first frame.
  */
-export function collapseRenderedFallbacks(rendered) {
+export function collapseRenderedFallbacks(rendered, collapsesToEmpty) {
   const collapsed = {};
   for (const [variantName, files] of Object.entries(rendered)) {
     const collapsedFiles = {};
     for (const [fileName, fallback] of Object.entries(files)) {
-      collapsedFiles[fileName] = collapsedVisibleFallback(fallback);
+      collapsedFiles[fileName] = collapsedVisibleFallback(fallback, collapsesToEmpty?.(variantName, fileName) ?? false);
     }
     collapsed[variantName] = collapsedFiles;
   }

package/CodeHighlighter/fallbackFormat.d.mts

@@ -86,8 +86,14 @@ export declare function redistributeRootFallback(root: HastRoot, fallback: Fallb
  * (the whole source is the focused window) the first frame stands in. Returns
  * the input unchanged when it has no frames at all.
  *
+ * When `collapsesToEmpty` is `true` the source records `focusedLines === 0`
+ * (the `oversizedFocus: 'hide'` collapse-to-nothing case): the collapsed window
+ * is intentionally empty, so the first-frame fallback is skipped and an empty
+ * array is returned. Mirrors the runtime rule in `Pre.tsx` /
+ * `getInitialVisibleSourceLines`.
+ *
  * Used by `fallbackCollapsed` to paint only the on-screen lines while the
  * file's full fallback rides along compressed (see the prop-compression
  * pattern's "Splitting the Fallback by Visibility").
  */
-export declare function collapsedVisibleFallback(fallback: FallbackNode[]): FallbackNode[];
+export declare function collapsedVisibleFallback(fallback: FallbackNode[], collapsesToEmpty?: boolean): FallbackNode[];

package/CodeHighlighter/fallbackFormat.mjs

@@ -1,4 +1,5 @@
 import { COLLAPSED_VISIBLE_FRAME_TYPES } from "../pipeline/parseSource/frameVisibility.mjs";
+import { isFrameSpan } from "../pipeline/parseSource/isFrameSpan.mjs";
 
 /**
  * Compact serialization format for fallback HAST trees.
@@ -155,10 +156,6 @@ function nodeText(node) {
   }
   return children.map(nodeText).join('');
 }
-function isFrameSpan(element) {
-  const className = element.properties?.className;
-  return className === 'frame' || Array.isArray(className) && className.includes('frame');
-}
 
 /**
  * Collects the plain text of a frame from its `.line` spans and the newline
@@ -291,11 +288,20 @@ function fallbackFrameType(frame) {
  * (the whole source is the focused window) the first frame stands in. Returns
  * the input unchanged when it has no frames at all.
  *
+ * When `collapsesToEmpty` is `true` the source records `focusedLines === 0`
+ * (the `oversizedFocus: 'hide'` collapse-to-nothing case): the collapsed window
+ * is intentionally empty, so the first-frame fallback is skipped and an empty
+ * array is returned. Mirrors the runtime rule in `Pre.tsx` /
+ * `getInitialVisibleSourceLines`.
+ *
  * Used by `fallbackCollapsed` to paint only the on-screen lines while the
  * file's full fallback rides along compressed (see the prop-compression
  * pattern's "Splitting the Fallback by Visibility").
  */
-export function collapsedVisibleFallback(fallback) {
+export function collapsedVisibleFallback(fallback, collapsesToEmpty = false) {
+  if (collapsesToEmpty) {
+    return [];
+  }
   let firstFrame = -1;
   let firstVisible = -1;
   let lastVisible = -1;

package/CodeHighlighter/mergeComments.mjs

@@ -76,5 +76,5 @@ function warnOnIndexingMismatch(input, mine) {
   if (Object.keys(other).length === 0) {
     return;
   }
-  console.warn('mergeComments: inputs appear to use different line-indexing conventions ' + '(one contains a `0` key, the other does not). Both inputs must use the ' + 'same convention or markers will land on the wrong lines. The repository ' + "convention is 1-indexed; convert with `convertCommentsToOneIndexed` if you're emitting 0-indexed comments.");
+  console.warn('mergeComments: inputs appear to use different line-indexing conventions ' + '(one contains a `0` key, the other does not). Comments are 1-indexed everywhere ' + '(a `0` key means something emitted 0-indexed comments); both inputs must be ' + '1-indexed or markers will land on the wrong lines.');
 }