[docs-infra] Improve Code Prop Compression

docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx

@@ -6,12 +6,12 @@ import styles from './CodeContent.module.css';
 
 import '../../../../../docs-infra/components/code-highlighter/demos/syntax.css';
 
-export function CodeContentLoading(props: ContentLoadingProps<{}>) {
+export function CodeContentLoading(_props: ContentLoadingProps<{}>) {
   return (
     <div>
       {/* @focus-start */}
       <div className={styles.code}>
-        <pre className={styles.codeBlock}>{props.source}</pre>
+        <pre className={styles.codeBlock} />
       </div>
       {/* @focus-end */}
     </div>

docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx

@@ -2,6 +2,8 @@
 
 import * as React from 'react';
 import type { ContentLoadingProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useCodeFallback } from '@mui/internal-docs-infra/CodeHighlighter';
+import { hastToJsx } from '@mui/internal-docs-infra/pipeline/hastUtils';
 import { Tabs } from '@/components/Tabs';
 import styles from '../DemoContent.module.css';
 import loadingStyles from './DemoContentLoading.module.css';
@@ -10,6 +12,7 @@ import '../syntax.css';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
   // @focus-start
+  const { source, extraSource } = useCodeFallback(props);
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -47,11 +50,11 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
             </div>
           </div>
           <div className={styles.code}>
-            <pre className={styles.codeBlock}>{props.source}</pre>
+            <pre className={styles.codeBlock}>{source ? hastToJsx(source) : null}</pre>
           </div>
           <div className={loadingStyles.extraFiles}>
-            {Object.keys(props.extraSource || {}).map((slug) => (
-              <pre key={slug}>{props.extraSource?.[slug]}</pre>
+            {Object.keys(extraSource || {}).map((slug) => (
+              <pre key={slug}>{extraSource?.[slug] ? hastToJsx(extraSource[slug]) : null}</pre>
             ))}
           </div>
         </div>

docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx

@@ -2,6 +2,8 @@
 
 import * as React from 'react';
 import type { ContentLoadingProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useCodeFallback } from '@mui/internal-docs-infra/CodeHighlighter';
+import { hastToJsx } from '@mui/internal-docs-infra/pipeline/hastUtils';
 import { Tabs } from '@/components/Tabs';
 import { Select } from '@/components/Select';
 import styles from '../DemoContent.module.css';
@@ -15,6 +17,7 @@ const variantNames: Record<string, string | undefined> = {
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
   // @focus-start
+  const { source, extraSource, extraVariants } = useCodeFallback(props);
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -39,7 +42,7 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
 
   return (
     <div>
-      {Object.keys(props.extraSource || {}).map((slug) => (
+      {Object.keys(extraSource || {}).map((slug) => (
         <span key={slug} id={slug} className={styles.fileRefs} />
       ))}
       <div className={styles.container}>
@@ -58,28 +61,31 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
                 </div>
               )}
               <div className={styles.headerActions}>
-                {Object.keys(props.extraVariants || {}).length >= 1 && (
+                {Object.keys(extraVariants || {}).length >= 1 && (
                   <Select items={variants} value={variants[0]?.value} disabled={true} />
                 )}
               </div>
             </div>
           </div>
           <div className={styles.code}>
-            <pre className={styles.codeBlock}>{props.source}</pre>
+            <pre className={styles.codeBlock}>{source ? hastToJsx(source) : null}</pre>
           </div>
           <div className={loadingStyles.extraFiles}>
-            {Object.keys(props.extraSource || {}).map((slug) => (
-              <pre key={slug}>{props.extraSource?.[slug]}</pre>
+            {Object.keys(extraSource || {}).map((slug) => (
+              <pre key={slug}>{extraSource?.[slug] ? hastToJsx(extraSource[slug]) : null}</pre>
             ))}
           </div>
           <div className={loadingStyles.extraVariants}>
-            {Object.keys(props.extraVariants || {}).map((slug) => (
+            {Object.keys(extraVariants || {}).map((slug) => (
               <div key={slug} className={loadingStyles.extraVariant}>
                 <span>{slug}</span>
                 <pre>
-                  {Object.keys(props.extraVariants?.[slug].extraSource || {}).map((key) => (
+                  {Object.keys(extraVariants?.[slug].extraSource || {}).map((key) => (
                     <div key={key}>
-                      <strong>{key}:</strong> {props.extraVariants?.[slug]?.extraSource?.[key]}
+                      <strong>{key}:</strong>{' '}
+                      {extraVariants?.[slug]?.extraSource?.[key]
+                        ? hastToJsx(extraVariants[slug].extraSource![key])
+                        : null}
                     </div>
                   ))}
                 </pre>

docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx

@@ -2,13 +2,16 @@
 
 import * as React from 'react';
 import type { ContentLoadingProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useCodeFallback } from '@mui/internal-docs-infra/CodeHighlighter';
+import { hastToJsx } from '@mui/internal-docs-infra/pipeline/hastUtils';
 import { Tabs } from '@/components/Tabs';
 import styles from '../DemoContent.module.css';
 
 import '../syntax.css';
 
 export function DemoContentLoading(props: ContentLoadingProps<object>) {
   // @focus-start
+  const { source } = useCodeFallback(props);
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -46,7 +49,7 @@ export function DemoContentLoading(props: ContentLoadingProps<object>) {
             </div>
           </div>
           <div className={styles.code}>
-            <pre className={styles.codeBlock}>{props.source}</pre>
+            <pre className={styles.codeBlock}>{source ? hastToJsx(source) : null}</pre>
           </div>
         </div>
       </div>

docs/app/docs-infra/components/code-highlighter/types.md

@@ -145,15 +145,51 @@ type ReturnValue = HastRoot | Promise<HastRoot>;
 type ReturnValue = Promise<Record<string, { source: string; fileName?: string }> | undefined>;
 ```
 
+### useCodeFallback
+
+Hook for `ContentLoading` components to hoist fallback data
+to `CodeHighlighterClient` for text-dictionary derivation.
+
+On the server-rendered path, Code is stripped of `fallback` entries
+and the data arrives on ContentLoading as `source`/`extraSource` props
+in compact `FallbackNode[]` format. This hook converts them back to
+`HastRoot` for rendering and hoists the compact form for dictionaries.
+
+On the client-loaded path, `useInitialData` already hoists directly,
+so this hook simply passes props through.
+
+**useCodeFallback Parameters:**
+
+| Parameter | Type                   | Default | Description |
+| :-------- | :--------------------- | :------ | :---------- |
+| props     | `UseCodeFallbackProps` | -       | -           |
+
+**useCodeFallback Return Value:**
+
+```tsx
+type ReturnValue = UseCodeFallbackResult;
+```
+
 ## Additional Types
 
+### UseCodeFallbackResult
+
+```typescript
+type UseCodeFallbackResult = {
+  source?: HastRoot;
+  fileNames?: string[];
+  extraSource?: Record<string, HastRoot>;
+  extraVariants?: Record<string, UseCodeFallbackVariantResult>;
+};
+```
+
 ### BaseContentLoadingProps
 
 ```typescript
 type BaseContentLoadingProps = {
   fileNames?: string[];
-  source?: React.ReactNode;
-  extraSource?: { [fileName: string]: React.ReactNode };
+  source?: FallbackNode[];
+  extraSource?: Record<string, FallbackNode[]>;
   /** Display name for the code example, used for identification and titles */
   name?: string;
   /** URL-friendly identifier for deep linking and navigation */
@@ -541,6 +577,7 @@ type ContentLoadingProps<T extends {}> = ContentLoadingVariant &
     component: React.ReactNode;
     components?: Record<string, React.ReactNode>;
     initialFilename?: string;
+    initialVariant?: string;
   };
 ```
 
@@ -549,8 +586,8 @@ type ContentLoadingProps<T extends {}> = ContentLoadingVariant &
 ```typescript
 type ContentLoadingVariant = {
   fileNames?: string[];
-  source?: React.ReactNode;
-  extraSource?: { [fileName: string]: React.ReactNode };
+  source?: FallbackNode[];
+  extraSource?: Record<string, FallbackNode[]>;
 };
 ```
 
@@ -607,6 +644,16 @@ type ExternalImportItem = {
 type Externals = { [key: string]: ExternalImportItem[] };
 ```
 
+### Fallbacks
+
+Record of `fileName → compact fallback` extracted from variants.
+Used as the DEFLATE dictionary for `hastCompressed` decompression and
+as the visual fallback before full highlighting loads.
+
+```typescript
+type Fallbacks = { [key: string]: FallbackNode[] };
+```
+
 ### HastRoot
 
 ```typescript
@@ -640,6 +687,21 @@ type LoadFallbackCodeOptions = {
    * @default 'hast'
    */
   output?: 'hast' | 'hastJson' | 'hastCompressed';
+  /**
+   * When `true` and `output` is `'hastCompressed'`, the text content of
+   * the fallback HAST is used as a DEFLATE dictionary during compression,
+   * producing smaller payloads. The resulting `fallbackHast` is included
+   * on the variant so it can travel via context to the client and be used
+   * to reconstruct the same dictionary for decompression.
+   *
+   * Set this to `true` only when a `ContentLoading` component is present,
+   * since the compressed data can only be decompressed when the fallbackHast
+   * is available in the `CodeHighlighterFallbackContext`.
+   *
+   * When `false` (the default), only the static shared dictionary is used.
+   * @default false
+   */
+  compressWithFallbackDictionary?: boolean;
   /** Function to load code metadata from a URL */
   loadCodeMeta?: LoadCodeMeta;
   /** Function to load specific variant metadata */
@@ -682,6 +744,21 @@ type LoadFileOptions = {
    * @default 'hast'
    */
   output?: 'hast' | 'hastJson' | 'hastCompressed';
+  /**
+   * When `true` and `output` is `'hastCompressed'`, the text content of
+   * the fallback HAST is used as a DEFLATE dictionary during compression,
+   * producing smaller payloads. The resulting `fallbackHast` is included
+   * on the variant so it can travel via context to the client and be used
+   * to reconstruct the same dictionary for decompression.
+   *
+   * Set this to `true` only when a `ContentLoading` component is present,
+   * since the compressed data can only be decompressed when the fallbackHast
+   * is available in the `CodeHighlighterFallbackContext`.
+   *
+   * When `false` (the default), only the static shared dictionary is used.
+   * @default false
+   */
+  compressWithFallbackDictionary?: boolean;
 };
 ```
 
@@ -706,6 +783,21 @@ type LoadVariantOptions = {
    * @default 'hast'
    */
   output?: 'hast' | 'hastJson' | 'hastCompressed';
+  /**
+   * When `true` and `output` is `'hastCompressed'`, the text content of
+   * the fallback HAST is used as a DEFLATE dictionary during compression,
+   * producing smaller payloads. The resulting `fallbackHast` is included
+   * on the variant so it can travel via context to the client and be used
+   * to reconstruct the same dictionary for decompression.
+   *
+   * Set this to `true` only when a `ContentLoading` component is present,
+   * since the compressed data can only be decompressed when the fallbackHast
+   * is available in the `CodeHighlighterFallbackContext`.
+   *
+   * When `false` (the default), only the static shared dictionary is used.
+   * @default false
+   */
+  compressWithFallbackDictionary?: boolean;
   /** Promise resolving to a source parser for syntax highlighting */
   sourceParser?: Promise<ParseSource>;
   /** Function to load raw source code and dependencies */
@@ -771,6 +863,14 @@ type VariantCode = {
   url?: string;
   /** Main source content for this variant */
   source?: VariantSource;
+  /**
+   * Compact fallback (highlighting spans removed) for the main source.
+   * Converted from HAST via `hastToFallback` for smaller RSC payloads.
+   * Used as the visual fallback before full highlighting loads, and its text
+   * content (via `fallbackToText`) serves as the DEFLATE dictionary for
+   * decompressing `hastCompressed` payloads.
+   */
+  fallback?: FallbackNode[];
   /** Additional files associated with this variant */
   extraFiles?: VariantExtraFiles;
   /** Prefix for metadata keys, e.g. /src */
@@ -803,6 +903,7 @@ type VariantExtraFiles = {
     | string
     | {
         source?: VariantSource;
+        fallback?: FallbackNode[];
         language?: string;
         transforms?: Transforms;
         skipTransforms?: boolean;
@@ -821,5 +922,5 @@ type VariantSource = string | HastRoot | { hastJson: string } | { hastCompressed
 
 ## Export Groups
 
-- `CodeHighlighter`
-- `CodeHighlighterTypes`: `Components`, `Transforms`, `ExternalImportItem`, `Externals`, `HastRoot`, `VariantSource`, `VariantExtraFiles`, `VariantCode`, `Code`, `ControlledVariantExtraFiles`, `ControlledVariantCode`, `ControlledCode`, `ContentProps`, `ContentLoadingVariant`, `BaseContentLoadingProps`, `ContentLoadingProps`, `LoadCodeMeta`, `LoadVariantMeta`, `LoadSource`, `TransformSource`, `ParseSource`, `SourceTransformer`, `SourceTransformers`, `SourceComments`, `SourceEnhancer`, `SourceEnhancers`, `LoadFileOptions`, `LoadVariantOptions`, `LoadFallbackCodeOptions`, `CodeIdentityProps`, `CodeContentProps`, `CodeLoadingProps`, `CodeFunctionProps`, `CodeRenderingProps`, `CodeClientRenderingProps`, `CodeHighlighterBaseProps`, `CodeHighlighterClientProps`, `CodeHighlighterProps`
+- `CodeHighlighter`: `useCodeFallback`, `UseCodeFallbackResult`, `CodeHighlighter`
+- `CodeHighlighterTypes`: `Components`, `Transforms`, `ExternalImportItem`, `Externals`, `HastRoot`, `VariantSource`, `VariantExtraFiles`, `VariantCode`, `Code`, `ControlledVariantExtraFiles`, `ControlledVariantCode`, `ControlledCode`, `ContentProps`, `Fallbacks`, `ContentLoadingVariant`, `BaseContentLoadingProps`, `ContentLoadingProps`, `LoadCodeMeta`, `LoadVariantMeta`, `LoadSource`, `TransformSource`, `ParseSource`, `SourceTransformer`, `SourceTransformers`, `SourceComments`, `SourceEnhancer`, `SourceEnhancers`, `LoadFileOptions`, `LoadVariantOptions`, `LoadFallbackCodeOptions`, `CodeIdentityProps`, `CodeContentProps`, `CodeLoadingProps`, `CodeFunctionProps`, `CodeRenderingProps`, `CodeClientRenderingProps`, `CodeHighlighterBaseProps`, `CodeHighlighterClientProps`, `CodeHighlighterProps`

docs/app/docs-infra/components/page.mdx

@@ -62,6 +62,9 @@ It supports both static code blocks and interactive demos with component preview
     - Parameters: root, comments, fileName
   - TransformSource
     - Parameters: source, fileName
+  - useCodeFallback
+    - Parameters: props
+- Types: UseCodeFallbackResult
 
 </details>
 

docs/components/DemoPerformanceContentLoading/DemoPerformanceContentLoading.tsx

@@ -2,12 +2,15 @@
 
 import * as React from 'react';
 import type { ContentLoadingProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useCodeFallback } from '@mui/internal-docs-infra/CodeHighlighter';
+import { hastToJsx } from '@mui/internal-docs-infra/pipeline/hastUtils';
 import { Tabs } from '@/components/Tabs';
 import styles from '../../app/docs-infra/components/code-highlighter/demos/DemoContent.module.css';
 
 import '../../app/docs-infra/components/code-highlighter/demos/syntax.css';
 
 export function DemoPerformanceContentLoading(props: ContentLoadingProps<object>) {
+  const { source } = useCodeFallback(props);
   const tabs = React.useMemo(
     () =>
       props.fileNames?.map((name) => ({
@@ -45,7 +48,7 @@ export function DemoPerformanceContentLoading(props: ContentLoadingProps<object>
             </div>
           </div>
           <div className={styles.code}>
-            <pre className={styles.codeBlock}>{props.source}</pre>
+            <pre className={styles.codeBlock}>{source ? hastToJsx(source) : null}</pre>
           </div>
         </div>
       </div>