@mui/internal-docs-infra 0.11.1-canary.13 → 0.11.1-canary.14

package/CodeHighlighter/CodeHighlighter.mjs

@@ -6,7 +6,8 @@ import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/mayb
 import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
 import { getFileNameFromUrl, getLanguageFromExtension } from "../pipeline/loaderUtils/index.mjs";
 import { replaceUrlPrefix } from "../pipeline/loaderUtils/applyUrlPrefix.mjs";
-import { codeToFallbackProps } from "./codeToFallbackProps.mjs";
+import { codeToFallbackProps, stripFallbackHastsFromCode } from "./codeToFallbackProps.mjs";
+import { collapseRenderedFallbacks, compressResidualFallbacks, extractResidualFallbacks, mergeResidualFallbacks, residualDictionaryText } from "./fallbackCompression.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
@@ -45,6 +46,7 @@ function createClientProps(props) {
     enhanceAfter: enhanceAfter || 'idle',
     skipFallback: props.skipFallback,
     controlled: props.controlled,
+    residualFallbacks: props.residualFallbacks,
     name: props.name,
     slug: props.slug,
     // Use processedGlobalsCode if available, otherwise fall back to raw globalsCode
@@ -198,14 +200,44 @@ function renderWithInitialSource(props) {
     code,
     initialFilename,
     fallbackUsesExtraFiles,
-    fallbackUsesAllVariants
+    fallbackUsesAllVariants,
+    fallbackCollapsed
   } = props;
 
+  // Strip fallbackHast entries from Code — they move to ContentLoading props
+  // as source/extraSource instead of being serialized on Code.
+  const {
+    strippedCode,
+    allFallbackHasts
+  } = stripFallbackHastsFromCode(code, initialVariant, fallbackUsesExtraFiles, fallbackUsesAllVariants);
+
   // Rewrite the top-level URL before it reaches the loading fallback so the
   // browser never sees `file://` URLs. See `createClientProps` for the same
   // rewrite on the regular client path.
   const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
-  const fallbackProps = codeToFallbackProps(initialVariant, code, initialFilename, fallbackUsesExtraFiles, fallbackUsesAllVariants);
+
+  // `fallbackCollapsed` paints only each file's collapsed window in the loading
+  // UI; the full fallbacks defer into the blob. Otherwise the loading UI gets
+  // the full rendered subset, as usual.
+  const contentLoadingHasts = fallbackCollapsed ? collapseRenderedFallbacks(allFallbackHasts) : allFallbackHasts;
+  const fallbackProps = codeToFallbackProps(initialVariant, strippedCode, initialFilename, fallbackUsesExtraFiles, fallbackUsesAllVariants, contentLoadingHasts);
+
+  // Consolidate every fallback the loading UI won't render into a single DEFLATE
+  // blob, primed with the rendered (collapsed, when `fallbackCollapsed`) text so
+  // it dedupes against what's already on the client. That's everything still on
+  // `strippedCode` after hoisting — plus, when `fallbackCollapsed`, each
+  // rendered file's *full* fallback (the loading UI only painted its collapsed
+  // window, so the rest must travel here). The blob crosses once; `wireCode`
+  // carries no inline fallbacks, and the client scatters them back after the
+  // rendered text hoists. When there's nothing worth compressing, keep the
+  // plain inline fallbacks unchanged.
+  const {
+    wireCode,
+    residual
+  } = extractResidualFallbacks(strippedCode);
+  const fullResidual = fallbackCollapsed ? mergeResidualFallbacks(residual, allFallbackHasts) : residual;
+  const residualFallbacks = compressResidualFallbacks(fullResidual, residualDictionaryText(contentLoadingHasts));
+  const codeForClient = residualFallbacks ? wireCode : strippedCode;
 
   // Get the component for the selected variant
   const component = props.components?.[initialVariant];
@@ -221,7 +253,12 @@ function renderWithInitialSource(props) {
     initialFilename,
     initialVariant,
     component,
-    components
+    components,
+    // Signals the ContentLoading that `source` is only the collapsed window,
+    // so it can disable any expand control until the full content swaps in.
+    ...(fallbackCollapsed ? {
+      fallbackCollapsed: true
+    } : undefined)
   };
   const fallback = /*#__PURE__*/_jsx(ContentLoading, {
     ...contentProps
@@ -232,6 +269,9 @@ function renderWithInitialSource(props) {
       children: /*#__PURE__*/_jsx(CodeHighlighterSuspense, {
         children: renderCodeHighlighter({
           ...props,
+          code: codeForClient,
+          precompute: residualFallbacks ? codeForClient : props.precompute,
+          residualFallbacks,
           fallback,
           skipFallback: props.enhanceAfter === 'stream'
         })
@@ -240,6 +280,9 @@ function renderWithInitialSource(props) {
   }
   return renderCodeHighlighter({
     ...props,
+    code: codeForClient,
+    precompute: residualFallbacks ? codeForClient : props.precompute,
+    residualFallbacks,
     fallback
   });
 }

package/CodeHighlighter/CodeHighlighterClient.mjs

@@ -7,9 +7,11 @@ import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/mayb
 import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
 import { CodeHighlighterFallbackContext } from "./CodeHighlighterFallbackContext.mjs";
 import { useControlledCode } from "../CodeControllerContext/index.mjs";
-import { codeToFallbackProps } from "./codeToFallbackProps.mjs";
+import { codeToFallbackProps, deriveFallbacksFromCode, stripFallbackHastsFromCode } from "./codeToFallbackProps.mjs";
+import { decompressResidualFallbacks, residualDictionaryText, scatterResidualFallbacks } from "./fallbackCompression.mjs";
 import { mergeCodeMetadata } from "../pipeline/loadIsomorphicCodeVariant/mergeCodeMetadata.mjs";
 import { getAvailableTransforms } from "../pipeline/loadIsomorphicCodeVariant/getAvailableTransforms.mjs";
+import { useCoordinatedLazy } from "../useCoordinated/useCoordinatedLazy.mjs";
 import * as Errors from "./errors.mjs";
 import { jsx as _jsx } from "react/jsx-runtime";
 const DEBUG = false; // Set to true for debugging purposes
@@ -26,7 +28,8 @@ function useInitialData({
   fallbackUsesAllVariants,
   isControlled,
   globalsCode,
-  setProcessedGlobalsCode
+  setProcessedGlobalsCode,
+  handleSetFallbackHasts
 }) {
   const {
     sourceParser,
@@ -88,14 +91,22 @@ function useInitialData({
       if ('error' in loaded) {
         console.error(new Errors.ErrorCodeHighlighterClientLoadFallbackFailure(loaded.error));
       } else {
-        setCode(loaded.code);
+        // Strip fallbacks from code and hoist them directly
+        const {
+          strippedCode,
+          allFallbackHasts
+        } = stripFallbackHastsFromCode(loaded.code, variantName, fallbackUsesExtraFiles, fallbackUsesAllVariants);
+        setCode(strippedCode);
+        for (const [variant, hasts] of Object.entries(allFallbackHasts)) {
+          handleSetFallbackHasts(variant, hasts);
+        }
         // Store processed globalsCode from loadCodeFallback result
         if (loaded.processedGlobalsCode) {
           setProcessedGlobalsCode(loaded.processedGlobalsCode);
         }
       }
     })();
-  }, [initialData, reason, needsFallback, variantName, code, setCode, highlightAfter, url, sourceParser, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, fallbackUsesExtraFiles, fallbackUsesAllVariants, fileName, variants, globalsCode, setProcessedGlobalsCode, loadCodeFallback]);
+  }, [initialData, reason, needsFallback, variantName, code, setCode, highlightAfter, url, sourceParser, loadSource, loadVariantMeta, loadCodeMeta, sourceEnhancers, fallbackUsesExtraFiles, fallbackUsesAllVariants, fileName, variants, globalsCode, setProcessedGlobalsCode, loadCodeFallback, handleSetFallbackHasts]);
   return {
     fallbackPending
   };
@@ -777,6 +788,40 @@ export function CodeHighlighterClient(props) {
     fallbackUsesExtraFiles,
     fallbackUsesAllVariants
   } = props;
+
+  // ── Fallback hoisting ──
+  // State for fallbacks hoisted from ContentLoading via useCodeFallback.
+  // Content is stripped from Code on the server and passed to ContentLoading
+  // as source/extraSource props. ContentLoading hoists them back here so
+  // CodeHighlighterClient can derive text dictionaries for decompression.
+  const [hoistedFallbackHasts, setHoistedFallbackHasts] = React.useState({});
+
+  // Track whether ContentLoading called useCodeFallback via callback.
+  const hookCalledRef = React.useRef(false);
+  // Whether the fallback (ContentLoading) has mounted at least once. Until it
+  // has, we force it to mount even when the code is already ready, so its
+  // `useCodeFallback` effect can hoist the root fallback (the DEFLATE
+  // dictionary needed to decompress `hastCompressed`). Without this, a
+  // server-rendered, fully-loaded highlighter would skip the fallback branch
+  // entirely and Content could never decode the compressed HAST.
+  const [fallbackMounted, setFallbackMounted] = React.useState(false);
+  const handleHookCalled = React.useCallback(() => {
+    hookCalledRef.current = true;
+    setFallbackMounted(true);
+  }, []);
+
+  // Stable callback for ContentLoading to hoist its fallbacks.
+  const handleSetFallbackHasts = React.useCallback((variant, hasts) => {
+    setHoistedFallbackHasts(prev => {
+      if (prev[variant] === hasts) {
+        return prev;
+      }
+      return {
+        ...prev,
+        [variant]: hasts
+      };
+    });
+  }, []);
   const {
     fallbackPending
   } = useInitialData({
@@ -791,9 +836,31 @@ export function CodeHighlighterClient(props) {
     fallbackUsesAllVariants,
     isControlled,
     globalsCode: props.globalsCode,
-    setProcessedGlobalsCode
+    setProcessedGlobalsCode,
+    handleSetFallbackHasts
   });
 
+  // Reverse the server-side residual consolidation. The blob is primed with the
+  // rendered subset's text, which only reaches the client via the hoist — so we
+  // wait for `hoistedFallbackHasts[variantName]` (the rendered initial variant,
+  // hoisted atomically) before decompressing. Residual files are hidden until a
+  // post-hoist swap, so deferring costs nothing; if the hoist never arrives the
+  // existing fallback-hoist check throws anyway.
+  const residualFallbacks = props.residualFallbacks;
+  const renderedHoist = hoistedFallbackHasts[variantName];
+  const residualMap = React.useMemo(() => {
+    if (!residualFallbacks || !renderedHoist) {
+      return undefined;
+    }
+    return decompressResidualFallbacks(residualFallbacks, residualDictionaryText(hoistedFallbackHasts));
+  }, [residualFallbacks, renderedHoist, hoistedFallbackHasts]);
+
+  // Scatter the residual back onto whichever code carries it. Memoized so the
+  // freshly-cloned code keeps a stable identity until the residual or its base
+  // changes (the downstream merges/parses are keyed on it).
+  const resolvedPropsCode = React.useMemo(() => props.code && residualMap ? scatterResidualFallbacks(props.code, residualMap) : props.code, [props.code, residualMap]);
+  const resolvedStateCode = React.useMemo(() => code && residualMap ? scatterResidualFallbacks(code, residualMap) : code, [code, residualMap]);
+
   // Use useSyncExternalStore to detect hydration
   const subscribe = React.useCallback(() => () => {}, []);
   const getSnapshot = React.useCallback(() => true, []);
@@ -843,6 +910,20 @@ export function CodeHighlighterClient(props) {
     const regularCode = props.code || code;
     return regularCode ? hasAllVariants(variants, regularCode) : false;
   }, [activeCode, isEnhanceAllowed, controlled?.code, variants, props.code, code]);
+
+  // Whether the fallback branch will actually mount this render. A fallback
+  // that exists but hasn't hoisted yet is forced to mount once (regardless of
+  // `activeCodeReady`) so `useCodeFallback` can hoist the root fallback.
+  const isFallbackRendered = !!props.fallback && !props.skipFallback && (!activeCodeReady || !fallbackMounted);
+
+  // Validate that ContentLoading calls useCodeFallback(props).
+  // Child effects fire before parent effects, so hookCalledRef is
+  // guaranteed to be set by the time this effect runs.
+  React.useEffect(() => {
+    if (isFallbackRendered && !hookCalledRef.current) {
+      throw new Errors.ErrorCodeHighlighterClientMissingFallbackHoist();
+    }
+  }, [isFallbackRendered]);
   useAllVariants({
     readyForContent,
     variants,
@@ -859,7 +940,7 @@ export function CodeHighlighterClient(props) {
   // Merge globalsCode with internal state code (fetched data) - this should be stable once ready
   const stateCodeWithGlobals = useGlobalsCodeMerging({
     url,
-    code,
+    code: resolvedStateCode,
     // Only use internal state, not props.code
     globalsCode: props.globalsCode,
     processedGlobalsCode,
@@ -870,7 +951,7 @@ export function CodeHighlighterClient(props) {
 
   // For props.code (controlled), always re-merge when it changes (don't cache in state)
   const propsCodeWithGlobals = usePropsCodeGlobalsMerging({
-    code: props.code,
+    code: resolvedPropsCode,
     globalsCode: props.globalsCode,
     processedGlobalsCode,
     variants
@@ -912,6 +993,14 @@ export function CodeHighlighterClient(props) {
   // their stored-preference resolution doesn't pay the deltas latency.
   const deferHighlight = deferHighlightForParsing || availableTransforms.length > 0 && waitingForTransformedCode;
 
+  // Declare this block to the page-wide layout-shift gate. While any block is
+  // still mid-swap, `useCoordinated` holds its layout-shifting commits, so the
+  // first transform/variant change lands as one unified update instead of a
+  // cascade as blocks swap in at staggered idle times. Settled once the block
+  // has finished its initial fallback→content swap (no longer rendering the
+  // fallback, and not mid-highlight); released on unmount.
+  useCoordinatedLazy(!isFallbackRendered && !deferHighlight);
+
   // Per-highlighter pre-parsed HAST cache. Lives in a ref so the same Map
   // instance is shared across renders without becoming a React dep. The
   // editable populates it via `useSourceEditing` (which reads it from
@@ -931,8 +1020,29 @@ export function CodeHighlighterClient(props) {
   const overlaidCode = parsedControlledCode || transformedCode || codeWithGlobals;
 
   // For fallback context, use the processed code or fall back to non-controlled code
-  const codeForFallback = overlaidCode || (controlled?.code ? undefined : props.code || code);
-  const fallbackContext = React.useMemo(() => activeCodeReady ? undefined : codeToFallbackProps(variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants), [activeCodeReady, variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants]);
+  const codeForFallback = overlaidCode || (controlled?.code ? undefined : resolvedPropsCode || resolvedStateCode);
+
+  // Resolve the active variant's fallbacks from the two places one can cross
+  // the server→client boundary: the hoisted copy (from a `ContentLoading`
+  // component, which had it stripped off `Code`) and the variant's own
+  // `fallback` field on `Code` (present without a `ContentLoading`, or scattered
+  // back from the residual blob). For most files only one is populated. When
+  // both are — a `fallbackCollapsed` block hoists the *visible* window but
+  // scatters the *full* fallback onto `Code` — the `Code` copy must win, since
+  // the full text is the DEFLATE dictionary `hastCompressed` needs. So merge
+  // with the derived (`Code`) copy taking precedence.
+  const activeFallbacks = React.useMemo(() => {
+    const merged = {
+      ...hoistedFallbackHasts[variantName],
+      ...deriveFallbacksFromCode(codeForFallback, variantName)
+    };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+  }, [hoistedFallbackHasts, variantName, codeForFallback]);
+  const fallbackContext = React.useMemo(() => ({
+    extraVariants: codeToFallbackProps(variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants).extraVariants,
+    setFallbackHasts: handleSetFallbackHasts,
+    onHookCalled: handleHookCalled
+  }), [variantName, codeForFallback, fileName, props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants, handleSetFallbackHasts, handleHookCalled]);
   const context = React.useMemo(() => ({
     code: overlaidCode,
     // Use processed/transformed code
@@ -945,14 +1055,21 @@ export function CodeHighlighterClient(props) {
     availableTransforms: controlled?.code ? [] : availableTransforms,
     url: props.url,
     deferHighlight,
+    fallbacks: activeFallbacks,
     highlightReady,
     highlightAfter,
     preParsedCache
-  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, controlled?.code, availableTransforms, props.url, deferHighlight, highlightReady, highlightAfter, preParsedCache]);
+  }), [overlaidCode, controlled?.setCode, selection, controlled?.selection, controlled?.setSelection, controlled?.components, props.components, controlled?.code, availableTransforms, props.url, deferHighlight, activeFallbacks, highlightReady, highlightAfter, preParsedCache]);
   if (!props.variants && !props.components && !activeCode) {
     throw new Errors.ErrorCodeHighlighterClientMissingData();
   }
 
+  // Reset only when fallback is actually rendered so the flag isn't sticky across cycles.
+  // The child's effect will set it again if useCodeFallback(props) is called.
+  if (isFallbackRendered) {
+    hookCalledRef.current = false;
+  }
+
   // If this CodeHighlighter is nested inside another CodeHighlighter that is
   // currently rendering its fallback, hold our own fallback->full transition
   // until the outer one swaps. Otherwise, when the outer swaps from its
@@ -964,7 +1081,7 @@ export function CodeHighlighterClient(props) {
   const outerFallbackContext = React.useContext(CodeHighlighterFallbackContext);
   const isNestedInsideOuterFallback = outerFallbackContext !== undefined;
   const fallback = props.fallback;
-  if (fallback && !props.skipFallback && (!activeCodeReady || isNestedInsideOuterFallback)) {
+  if (fallback && !props.skipFallback && (!activeCodeReady || isNestedInsideOuterFallback || !fallbackMounted)) {
     return /*#__PURE__*/_jsx(CodeHighlighterFallbackContext.Provider, {
       value: fallbackContext,
       children: fallback

package/CodeHighlighter/CodeHighlighterContext.d.mts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { type Code, type ControlledCode, type HastRoot } from "./types.mjs";
+import { type Code, type ControlledCode, type Fallbacks, type HastRoot } from "./types.mjs";
 import { type Selection } from "../CodeControllerContext/index.mjs";
 /**
  * One cached pre-parsed file. Stored per-fileName: each new write replaces
@@ -21,6 +21,13 @@ export interface CodeHighlighterContextType {
   availableTransforms?: string[];
   url?: string;
   deferHighlight?: boolean;
+  /**
+  /**
+   * Compact fallback data for the active variant, keyed by fileName.
+   * Used by `Pre` to both render the fallback and derive text dictionaries
+   * for decompressing `hastCompressed` payloads.
+   */
+  fallbacks?: Fallbacks;
   /**
    * Render-side readiness gate. `true` once the highlight trigger
    * (`init` / `hydration` / `idle` / `visible`) has fired *and* the

package/CodeHighlighter/CodeHighlighterFallbackContext.d.mts

@@ -1,7 +1,19 @@
 import * as React from 'react';
-import { type ContentLoadingVariant } from "./types.mjs";
-export interface CodeHighlighterFallbackContext extends ContentLoadingVariant {
+import type { Fallbacks, ContentLoadingVariant } from "./types.mjs";
+export interface CodeHighlighterFallbackContext {
   extraVariants?: Record<string, ContentLoadingVariant>;
+  /**
+   * Callback used by `useCodeFallback` to hoist fallback data
+   * back to `CodeHighlighterClient` so it can derive text dictionaries
+   * for decompressing `hastCompressed` payloads.
+   */
+  setFallbackHasts?: (variantName: string, hasts: Fallbacks) => void;
+  /**
+   * Callback invoked by `useCodeFallback` in an effect to signal that
+   * the hook was used. Allows the parent to detect when a ContentLoading
+   * component forgets to call the hook.
+   */
+  onHookCalled?: () => void;
 }
 export declare const CodeHighlighterFallbackContext: React.Context<CodeHighlighterFallbackContext | undefined>;
 export declare function useCodeHighlighterFallbackContext(): CodeHighlighterFallbackContext;

package/CodeHighlighter/CodeHighlighterFallbackContext.mjs

@@ -9,6 +9,4 @@ export function useCodeHighlighterFallbackContext() {
     throw new Error('CodeHighlighterFallbackContext is missing. `useCodeHighlighterFallbackContext` must be used within a `CodeHighlighter` component.');
   }
   return context;
-}
-
-// TODO: rename to ContentMinimal
+}

package/CodeHighlighter/codeToFallbackProps.d.mts

@@ -1,2 +1,28 @@
-import { type BaseContentLoadingProps, type Code } from "./types.mjs";
-export declare function codeToFallbackProps(variant: string, code?: Code, fileName?: string, needsAllFiles?: boolean, needsAllVariants?: boolean): BaseContentLoadingProps;
+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;
+/**
+ * Read a variant's per-file fallbacks straight off its `VariantCode` `fallback`
+ * fields (main + extra files), returning a `Fallbacks` map keyed by file name.
+ *
+ * The fallback crosses the server→client boundary exactly once: either on the
+ * `VariantCode` (no `ContentLoading`) or — after `stripFallbackHastsFromCode`
+ * moves it — on the `ContentLoading` props. This reads the former location, so
+ * the client can resolve the DEFLATE dictionary for `hastCompressed` without a
+ * hoist when there's no `ContentLoading`. Returns `undefined` when the variant
+ * carries no fallback (a string variant, a live-HAST source, or one whose
+ * fallbacks were stripped for a `ContentLoading` component) — in which case the
+ * hoisted copy is used instead.
+ */
+export declare function deriveFallbacksFromCode(code: Code | undefined, variantName: string): Fallbacks | undefined;
+/**
+ * Strip `fallback` entries from a `Code` object and return the
+ * stripped Code alongside the extracted fallbacks grouped by variant → fileName.
+ *
+ * Used on the server to separate the fallback data from the Code
+ * so Code is sent to CodeHighlighterClient without fallbacks, and
+ * the data is passed to ContentLoading as source/extraSource props.
+ */
+export declare function stripFallbackHastsFromCode(code: Code | undefined, variantName: string, fallbackUsesExtraFiles?: boolean, fallbackUsesAllVariants?: boolean): {
+  strippedCode: Code;
+  allFallbackHasts: Record<string, Fallbacks>;
+};