diff --git a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx b/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
index 3c62f1d2a..da554295d 100644
--- a/docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx
+++ b/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>
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
index e6e9f12a0..b0f78e952 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx
+++ b/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>
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
index 42212fdf2..b027a33e8 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx
+++ b/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>
diff --git a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
index 8babec8af..db44881d7 100644
--- a/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx
+++ b/docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/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';
 
@@ -9,6 +11,7 @@ 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>
diff --git a/docs/app/docs-infra/components/code-highlighter/types.md b/docs/app/docs-infra/components/code-highlighter/types.md
index 5e9e550d1..1f3fa096e 100644
--- a/docs/app/docs-infra/components/code-highlighter/types.md
+++ b/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`
diff --git a/docs/app/docs-infra/components/page.mdx b/docs/app/docs-infra/components/page.mdx
index 078df971a..9074131d6 100644
--- a/docs/app/docs-infra/components/page.mdx
+++ b/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>
 
diff --git a/docs/components/DemoPerformanceContentLoading/DemoPerformanceContentLoading.tsx b/docs/components/DemoPerformanceContentLoading/DemoPerformanceContentLoading.tsx
index 5f948e41a..453f5c0da 100644
--- a/docs/components/DemoPerformanceContentLoading/DemoPerformanceContentLoading.tsx
+++ b/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>
diff --git a/packages/docs-infra/src/CodeHighlighter/CodeHighlighter.tsx b/packages/docs-infra/src/CodeHighlighter/CodeHighlighter.tsx
index b02c47d09..00616455e 100644
--- a/packages/docs-infra/src/CodeHighlighter/CodeHighlighter.tsx
+++ b/packages/docs-infra/src/CodeHighlighter/CodeHighlighter.tsx
@@ -18,7 +18,7 @@ import { CodeHighlighterClient } from './CodeHighlighterClient';
 import { maybeCodeInitialData } from '../pipeline/loadCodeVariant/maybeCodeInitialData';
 import { hasAllVariants } from '../pipeline/loadCodeVariant/hasAllCodeVariants';
 import { getFileNameFromUrl, getLanguageFromExtension } from '../pipeline/loaderUtils';
-import { codeToFallbackProps } from './codeToFallbackProps';
+import { codeToFallbackProps, stripFallbackHastsFromCode } from './codeToFallbackProps';
 import * as Errors from './errors';
 
 interface CodeInitialSourceLoaderProps<T extends {}> extends CodeHighlighterBaseProps<T> {
@@ -263,12 +263,22 @@ function renderWithInitialSource<T extends {}>(props: RenderWithInitialSourcePro
     fallbackUsesAllVariants,
   } = 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,
+  );
+
   const fallbackProps = codeToFallbackProps(
     initialVariant,
-    code,
+    strippedCode,
     initialFilename,
     fallbackUsesExtraFiles,
     fallbackUsesAllVariants,
+    allFallbackHasts,
   );
 
   // Get the component for the selected variant
@@ -282,6 +292,7 @@ function renderWithInitialSource<T extends {}>(props: RenderWithInitialSourcePro
     slug,
     url,
     initialFilename,
+    initialVariant,
     component,
     components,
     ...fallbackProps,
@@ -296,6 +307,7 @@ function renderWithInitialSource<T extends {}>(props: RenderWithInitialSourcePro
         <CodeHighlighterSuspense>
           {renderCodeHighlighter({
             ...props,
+            code: strippedCode,
             fallback,
             skipFallback: props.enhanceAfter === 'stream',
           })}
@@ -306,6 +318,7 @@ function renderWithInitialSource<T extends {}>(props: RenderWithInitialSourcePro
 
   return renderCodeHighlighter({
     ...props,
+    code: strippedCode,
     fallback,
   });
 }
diff --git a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx
index 25f7c038f..37c9721dd 100644
--- a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx
+++ b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterClient.tsx
@@ -2,13 +2,13 @@
 
 import * as React from 'react';
 import { useCodeContext } from '../CodeProvider/CodeContext';
-import { Code, CodeHighlighterClientProps, ControlledCode, VariantCode } from './types';
+import { Code, CodeHighlighterClientProps, ControlledCode, Fallbacks, VariantCode } from './types';
 import { CodeHighlighterContext, CodeHighlighterContextType } from './CodeHighlighterContext';
 import { maybeCodeInitialData } from '../pipeline/loadCodeVariant/maybeCodeInitialData';
 import { hasAllVariants } from '../pipeline/loadCodeVariant/hasAllCodeVariants';
 import { CodeHighlighterFallbackContext } from './CodeHighlighterFallbackContext';
 import { Selection, useControlledCode } from '../CodeControllerContext';
-import { codeToFallbackProps } from './codeToFallbackProps';
+import { codeToFallbackProps, stripFallbackHastsFromCode } from './codeToFallbackProps';
 import { mergeCodeMetadata } from '../pipeline/loadCodeVariant/mergeCodeMetadata';
 import * as Errors from './errors';
 
@@ -27,6 +27,7 @@ function useInitialData({
   isControlled,
   globalsCode,
   setProcessedGlobalsCode,
+  handleSetFallbackHasts,
 }: {
   variants: string[];
   variantName: string;
@@ -40,6 +41,7 @@ function useInitialData({
   isControlled: boolean;
   globalsCode?: Array<Code | string>;
   setProcessedGlobalsCode: React.Dispatch<React.SetStateAction<Array<Code> | undefined>>;
+  handleSetFallbackHasts: (variant: string, hasts: Fallbacks) => void;
 }) {
   const {
     sourceParser,
@@ -116,7 +118,17 @@ 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);
@@ -144,6 +156,7 @@ function useInitialData({
     globalsCode,
     setProcessedGlobalsCode,
     loadCodeFallback,
+    handleSetFallbackHasts,
   ]);
 }
 
@@ -848,6 +861,31 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
   const { url, highlightAfter, enhanceAfter, 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<Record<string, Fallbacks>>(
+    {},
+  );
+
+  // Track whether ContentLoading called useCodeFallback via callback.
+  const hookCalledRef = React.useRef(false);
+  const handleHookCalled = React.useCallback(() => {
+    hookCalledRef.current = true;
+  }, []);
+
+  // Stable callback for ContentLoading to hoist its fallbacks.
+  const handleSetFallbackHasts = React.useCallback((variant: string, hasts: Fallbacks) => {
+    setHoistedFallbackHasts((prev) => {
+      if (prev[variant] === hasts) {
+        return prev;
+      }
+      return { ...prev, [variant]: hasts };
+    });
+  }, []);
+
   useInitialData({
     variants,
     variantName,
@@ -861,6 +899,7 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
     isControlled,
     globalsCode: props.globalsCode,
     setProcessedGlobalsCode,
+    handleSetFallbackHasts,
   });
 
   // Use useSyncExternalStore to detect hydration
@@ -920,6 +959,18 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
     return regularCode ? hasAllVariants(variants, regularCode) : false;
   }, [activeCode, isEnhanceAllowed, controlled?.code, variants, props.code, code]);
 
+  // Whether the fallback branch will actually mount this render.
+  const isFallbackRendered = !!props.fallback && !props.skipFallback && !activeCodeReady;
+
+  // 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,
@@ -980,21 +1031,32 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
   // For fallback context, use the processed code or fall back to non-controlled code
   const codeForFallback = overlaidCode || (controlled?.code ? undefined : props.code || code);
 
+  // Build fallbacks for the active variant from hoisted data.
+  const activeFallbacks = React.useMemo(
+    () => hoistedFallbackHasts[variantName],
+    [hoistedFallbackHasts, variantName],
+  );
+
   const fallbackContext = React.useMemo(
-    () =>
-      codeToFallbackProps(
+    () => ({
+      extraVariants: codeToFallbackProps(
         variantName,
         codeForFallback,
         fileName,
         props.fallbackUsesExtraFiles,
         props.fallbackUsesAllVariants,
-      ),
+      ).extraVariants,
+      setFallbackHasts: handleSetFallbackHasts,
+      onHookCalled: handleHookCalled,
+    }),
     [
       variantName,
       codeForFallback,
       fileName,
       props.fallbackUsesExtraFiles,
       props.fallbackUsesAllVariants,
+      handleSetFallbackHasts,
+      handleHookCalled,
     ],
   );
 
@@ -1008,6 +1070,7 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
       availableTransforms: isControlled ? [] : availableTransforms,
       url: props.url,
       deferHighlight,
+      fallbacks: activeFallbacks,
     }),
     [
       overlaidCode,
@@ -1021,6 +1084,7 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
       availableTransforms,
       props.url,
       deferHighlight,
+      activeFallbacks,
     ],
   );
 
@@ -1028,6 +1092,12 @@ export function CodeHighlighterClient(props: CodeHighlighterClientProps) {
     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;
+  }
+
   const fallback = props.fallback;
   if (fallback && !props.skipFallback && !activeCodeReady) {
     return (
diff --git a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx
index c43d6de53..09629b0ad 100644
--- a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx
+++ b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterContext.tsx
@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { Code, ControlledCode } from './types';
+import { Code, ControlledCode, Fallbacks } from './types';
 import { Selection } from '../CodeControllerContext';
 
 export interface CodeHighlighterContextType {
@@ -12,6 +12,12 @@ 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;
 }
 
 export const CodeHighlighterContext = React.createContext<CodeHighlighterContextType | undefined>(
diff --git a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterFallbackContext.tsx b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterFallbackContext.tsx
index f8629b06b..e9afc7a29 100644
--- a/packages/docs-infra/src/CodeHighlighter/CodeHighlighterFallbackContext.tsx
+++ b/packages/docs-infra/src/CodeHighlighter/CodeHighlighterFallbackContext.tsx
@@ -1,9 +1,21 @@
 'use client';
 import * as React from 'react';
-import { ContentLoadingVariant } from './types';
+import type { Fallbacks, ContentLoadingVariant } from './types';
 
-export interface CodeHighlighterFallbackContext extends ContentLoadingVariant {
+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 const CodeHighlighterFallbackContext = React.createContext<
@@ -19,5 +31,3 @@ export function useCodeHighlighterFallbackContext() {
   }
   return context;
 }
-
-// TODO: rename to ContentMinimal
diff --git a/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.test.ts b/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.test.ts
index 0489f4ee4..29f0d2191 100644
--- a/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.test.ts
+++ b/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.test.ts
@@ -1,6 +1,17 @@
 import { describe, it, expect } from 'vitest';
-import { codeToFallbackProps } from './codeToFallbackProps';
-import type { Code } from './types';
+import { codeToFallbackProps, stripFallbackHastsFromCode } from './codeToFallbackProps';
+import type { Code, HastRoot } from './types';
+import type { FallbackNode } from './fallbackFormat';
+
+/** Minimal HAST root for testing */
+function hast(text: string): HastRoot {
+  return { type: 'root', children: [{ type: 'text', value: text }] };
+}
+
+/** Minimal compact fallback for testing */
+function fb(text: string): FallbackNode[] {
+  return [text];
+}
 
 describe('codeToFallbackProps', () => {
   describe('basic functionality', () => {
@@ -9,11 +20,11 @@ describe('codeToFallbackProps', () => {
       expect(codeToFallbackProps('string', { string: 'highlighted html' })).toEqual({});
     });
 
-    it('should return basic props with source and fileNames', () => {
+    it('should derive source from variant HastRoot when no allFallbackHasts provided', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello</div>;',
+          source: hast('const App = () => <div>Hello</div>;'),
         },
       };
 
@@ -21,164 +32,125 @@ describe('codeToFallbackProps', () => {
 
       expect(result).toEqual({
         fileNames: ['App.js'],
-        source: 'const App = () => <div>Hello</div>;',
+        source: fb('const App = () => <div>Hello</div>;'),
       });
     });
 
-    it('should handle variant without fileName', () => {
+    it('should derive source from variant HastRoot even when fallback field exists', () => {
       const code: Code = {
         javascript: {
-          fileName: undefined,
-          source: 'const App = () => <div>Hello</div>;',
+          fileName: 'App.js',
+          source: hast('full'),
+          fallback: fb('fallback'),
         },
       };
 
       const result = codeToFallbackProps('javascript', code);
 
-      expect(result).toEqual({
-        fileNames: [],
-        source: 'const App = () => <div>Hello</div>;',
-      });
+      // Without allFallbackHasts, source is derived from variant.source
+      expect(result.source).toEqual(fb('full'));
     });
-  });
 
-  describe('extraSource behavior', () => {
-    it('should not include main file in extraSource', () => {
+    it('should handle variant without fileName', () => {
       const code: Code = {
         javascript: {
-          fileName: 'App.js',
-          source: 'const App = () => <div>Hello</div>;',
-          extraFiles: {
-            'utils.js': {
-              source: 'export const utils = {};',
-            },
-          },
+          fileName: undefined,
+          source: hast('const App = () => <div>Hello</div>;'),
         },
       };
 
-      const result = codeToFallbackProps('javascript', code, undefined, true); // needsAllFiles=true
+      const result = codeToFallbackProps('javascript', code);
 
-      expect(result.extraSource).toEqual({
-        'utils.js': 'export const utils = {};',
+      expect(result).toEqual({
+        fileNames: [],
+        source: fb('const App = () => <div>Hello</div>;'),
       });
-      expect(result.extraSource).not.toHaveProperty('App.js');
     });
 
-    it('should exclude requested fileName from extraSource', () => {
+    it('should derive source from hastJson format (precomputed loader output)', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello</div>;',
-          extraFiles: {
-            'utils.js': {
-              source: 'export const utils = {};',
-            },
-            'config.js': {
-              source: 'export const config = {};',
-            },
-          },
+          source: { hastJson: JSON.stringify(hast('precomputed content')) },
         },
       };
 
-      const result = codeToFallbackProps('javascript', code, 'utils.js', true); // needsAllFiles=true
+      const result = codeToFallbackProps('javascript', code);
 
-      expect(result.extraSource).toEqual({
-        'config.js': 'export const config = {};',
+      expect(result).toEqual({
+        fileNames: ['App.js'],
+        source: fb('precomputed content'),
       });
-      expect(result.extraSource).not.toHaveProperty('utils.js');
-      expect(result.extraSource).not.toHaveProperty('App.js');
     });
-  });
 
-  describe('fileName parameter handling', () => {
-    it('should return specific file source when fileName is provided', () => {
+    it('should return no source for hastCompressed format (needs dictionary)', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello</div>;',
-          extraFiles: {
-            'utils.js': {
-              source: 'export const utils = {};',
-            },
-          },
+          source: { hastCompressed: 'base64data' },
         },
       };
 
-      const result = codeToFallbackProps('javascript', code, 'utils.js');
+      const result = codeToFallbackProps('javascript', code);
 
       expect(result).toEqual({
-        fileNames: ['App.js', 'utils.js'],
-        source: 'export const utils = {};',
+        fileNames: ['App.js'],
       });
     });
 
-    it('should return main source when fileName is not provided', () => {
+    it('should derive extraSource from hastJson format', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello</div>;',
+          source: { hastJson: JSON.stringify(hast('app')) },
           extraFiles: {
-            'utils.js': {
-              source: 'export const utils = {};',
-            },
+            'utils.js': { source: { hastJson: JSON.stringify(hast('utils')) } },
           },
         },
       };
 
-      const result = codeToFallbackProps('javascript', code);
+      const result = codeToFallbackProps('javascript', code, undefined, true);
 
-      expect(result).toEqual({
-        fileNames: ['App.js', 'utils.js'],
-        source: 'const App = () => <div>Hello</div>;',
-      });
+      expect(result.source).toEqual(fb('app'));
+      expect(result.extraSource).toEqual({ 'utils.js': fb('utils') });
     });
   });
 
-  describe('needsAllFiles handling', () => {
-    it('should include extraSource when needsAllFiles=true', () => {
+  describe('fileNames include extra files', () => {
+    it('should list extra file names', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello</div>;',
+          source: hast('app'),
           extraFiles: {
-            'utils.js': {
-              source: 'export const utils = {};',
-            },
+            'utils.js': { source: hast('utils') },
           },
         },
       };
 
       const result = codeToFallbackProps('javascript', code, undefined, true);
 
-      expect(result).toEqual({
-        fileNames: ['App.js', 'utils.js'],
-        source: 'const App = () => <div>Hello</div>;',
-        extraSource: {
-          'utils.js': 'export const utils = {};',
-        },
-      });
+      expect(result.fileNames).toEqual(['App.js', 'utils.js']);
+      // extraSource derived from extra file HastRoot when no allFallbackHasts
+      expect(result.extraSource).toEqual({ 'utils.js': fb('utils') });
     });
   });
 
   describe('needsAllVariants handling', () => {
-    it('should include extraVariants when needsAllVariants=true', () => {
+    it('should include extraVariants with fileNames only', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello JS</div>;',
+          source: hast('hello js'),
           extraFiles: {
-            'utils.js': {
-              source: 'export const utils = {};',
-            },
+            'utils.js': { source: hast('js utils') },
           },
         },
         typescript: {
           fileName: 'App.ts',
-          source: 'const App = () => <div>Hello TS</div>;',
+          source: hast('hello ts'),
           extraFiles: {
-            'utils.ts': {
-              source: 'export const utils: any = {};',
-            },
+            'utils.ts': { source: hast('ts utils') },
           },
         },
       };
@@ -187,17 +159,13 @@ describe('codeToFallbackProps', () => {
 
       expect(result).toEqual({
         fileNames: ['App.js', 'utils.js'],
-        source: 'const App = () => <div>Hello JS</div>;',
-        extraSource: {
-          'utils.js': 'export const utils = {};',
-        },
+        source: fb('hello js'),
+        extraSource: { 'utils.js': fb('js utils') },
         extraVariants: {
           typescript: {
             fileNames: ['App.ts', 'utils.ts'],
-            source: 'const App = () => <div>Hello TS</div>;',
-            extraSource: {
-              'utils.ts': 'export const utils: any = {};',
-            },
+            source: fb('hello ts'),
+            extraSource: { 'utils.ts': fb('ts utils') },
           },
         },
       });
@@ -207,11 +175,11 @@ describe('codeToFallbackProps', () => {
       const code: Code = {
         javascript: {
           fileName: 'App.js',
-          source: 'const App = () => <div>Hello JS</div>;',
+          source: hast('hello js'),
         },
         typescript: {
           fileName: 'App.ts',
-          source: 'const App = () => <div>Hello TS</div>;',
+          source: hast('hello ts'),
         },
       };
 
@@ -220,11 +188,117 @@ describe('codeToFallbackProps', () => {
       expect(result.extraVariants).toEqual({
         typescript: {
           fileNames: ['App.ts'],
-          source: 'const App = () => <div>Hello TS</div>;',
-          extraSource: {},
+          source: fb('hello ts'),
         },
       });
       expect(result.extraVariants).not.toHaveProperty('javascript');
     });
   });
 });
+
+describe('stripFallbackHastsFromCode', () => {
+  it('should strip main variant fallback and return it separately', () => {
+    const fallback = fb('fallback');
+    const code: Code = {
+      javascript: {
+        fileName: 'App.js',
+        source: { hastCompressed: 'abc' },
+        fallback,
+      },
+    };
+
+    const { strippedCode, allFallbackHasts } = stripFallbackHastsFromCode(code, 'javascript');
+
+    // fallback should be removed from Code
+    const variant = strippedCode.javascript;
+    expect(variant).toBeDefined();
+    expect(typeof variant === 'object' && variant !== null && 'fallback' in variant).toBe(false);
+
+    // Should be in the extracted map
+    expect(allFallbackHasts).toEqual({
+      javascript: { 'App.js': fallback },
+    });
+  });
+
+  it('should strip extra files when fallbackUsesExtraFiles is true', () => {
+    const fbMain = fb('main');
+    const fbExtra = fb('extra');
+    const code: Code = {
+      javascript: {
+        fileName: 'App.js',
+        source: { hastCompressed: 'abc' },
+        fallback: fbMain,
+        extraFiles: {
+          'utils.js': {
+            source: { hastCompressed: 'def' },
+            fallback: fbExtra,
+          },
+        },
+      },
+    };
+
+    const { strippedCode, allFallbackHasts } = stripFallbackHastsFromCode(
+      code,
+      'javascript',
+      true, // fallbackUsesExtraFiles
+    );
+
+    const variant = strippedCode.javascript as any;
+    expect(variant.fallback).toBeUndefined();
+    expect(variant.extraFiles['utils.js'].fallback).toBeUndefined();
+    expect(variant.extraFiles['utils.js'].source).toEqual({ hastCompressed: 'def' });
+
+    expect(allFallbackHasts).toEqual({
+      javascript: {
+        'App.js': fbMain,
+        'utils.js': fbExtra,
+      },
+    });
+  });
+
+  it('should strip all variants when fallbackUsesAllVariants is true', () => {
+    const fbJs = fb('js');
+    const fbTs = fb('ts');
+    const code: Code = {
+      javascript: {
+        fileName: 'App.js',
+        source: { hastCompressed: 'abc' },
+        fallback: fbJs,
+      },
+      typescript: {
+        fileName: 'App.ts',
+        source: { hastCompressed: 'def' },
+        fallback: fbTs,
+      },
+    };
+
+    const { strippedCode, allFallbackHasts } = stripFallbackHastsFromCode(
+      code,
+      'javascript',
+      false,
+      true, // fallbackUsesAllVariants
+    );
+
+    expect((strippedCode.javascript as any).fallback).toBeUndefined();
+    expect((strippedCode.typescript as any).fallback).toBeUndefined();
+
+    expect(allFallbackHasts).toEqual({
+      javascript: { 'App.js': fbJs },
+      typescript: { 'App.ts': fbTs },
+    });
+  });
+
+  it('should leave variants without fallback unchanged', () => {
+    const code: Code = {
+      javascript: {
+        fileName: 'App.js',
+        source: 'const x = 1;',
+      },
+    };
+
+    const { strippedCode, allFallbackHasts } = stripFallbackHastsFromCode(code, 'javascript');
+
+    expect(strippedCode).toEqual(code);
+    expect(allFallbackHasts).toEqual({});
+  });
+});
diff --git a/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.ts b/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.ts
index f5ae11ad8..7e58e6376 100644
--- a/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.ts
+++ b/packages/docs-infra/src/CodeHighlighter/codeToFallbackProps.ts
@@ -1,24 +1,38 @@
-import { BaseContentLoadingProps, Code, ContentLoadingVariant, VariantCode } from './types';
-import { stringOrHastToJsx } from '../pipeline/hastUtils';
-
-function toExtraSource(variantCode: VariantCode, fileName?: string) {
-  return Object.entries(variantCode.extraFiles || {}).reduce(
-    (acc, [name, file]) => {
-      if (name !== fileName && typeof file === 'object' && file?.source) {
-        acc[name] = stringOrHastToJsx(file.source);
-      }
-      return acc;
-    },
-    {} as Record<string, any>,
-  );
+import type {
+  BaseContentLoadingProps,
+  Code,
+  ContentLoadingVariant,
+  Fallbacks,
+  VariantSource,
+} from './types';
+import { hastToFallback, type FallbackNode } from './fallbackFormat';
+
+/**
+ * Derive a compact FallbackNode[] from a VariantSource when pre-extracted
+ * fallback data is not available (e.g. when the precompute loader does not
+ * pass compressWithFallbackDictionary).
+ */
+function sourceToFallback(source: VariantSource | undefined): FallbackNode[] | undefined {
+  if (!source || typeof source === 'string') {
+    return undefined;
+  }
+  if ('type' in source && source.type === 'root') {
+    return hastToFallback(source);
+  }
+  if ('hastJson' in source) {
+    return hastToFallback(JSON.parse(source.hastJson));
+  }
+  // hastCompressed cannot be decoded here without the dictionary
+  return undefined;
 }
 
 export function codeToFallbackProps(
   variant: string,
   code?: Code,
-  fileName?: string,
-  needsAllFiles = false,
+  _fileName?: string,
+  _needsAllFiles = false,
   needsAllVariants = false,
+  allFallbackHasts?: Record<string, Fallbacks>,
 ): BaseContentLoadingProps {
   const variantCode = code?.[variant];
   if (!variantCode || typeof variantCode === 'string') {
@@ -28,56 +42,176 @@ export function codeToFallbackProps(
   const fileNames = [variantCode.fileName, ...Object.keys(variantCode.extraFiles || {})].filter(
     (name): name is string => Boolean(name),
   );
-  let source;
 
-  if (fileName && fileName !== variantCode.fileName) {
-    const fileData = variantCode.extraFiles?.[fileName];
-    if (fileData && typeof fileData === 'object' && 'source' in fileData && fileData.source) {
-      source = stringOrHastToJsx(fileData.source);
+  // Derive source/extraSource from extracted fallbacks when provided
+  let source: FallbackNode[] | undefined;
+  let extraSource: Record<string, FallbackNode[]> | undefined;
+
+  const variantHasts = allFallbackHasts?.[variant];
+  if (variantHasts) {
+    const mainFile = variantCode.fileName || fileNames[0];
+    if (mainFile && variantHasts[mainFile]) {
+      source = variantHasts[mainFile];
+    }
+    const extra: Record<string, FallbackNode[]> = {};
+    for (const [fName, h] of Object.entries(variantHasts)) {
+      if (fName !== mainFile) {
+        extra[fName] = h;
+      }
+    }
+    if (Object.keys(extra).length > 0) {
+      extraSource = extra;
+    }
+  } else {
+    // No pre-extracted fallback data (e.g. dev mode). Derive from source directly.
+    source = sourceToFallback(variantCode.source);
+    const extra: Record<string, FallbackNode[]> = {};
+    for (const [fName, fData] of Object.entries(variantCode.extraFiles || {})) {
+      if (typeof fData === 'object' && fData.source) {
+        const fb = sourceToFallback(fData.source);
+        if (fb) {
+          extra[fName] = fb;
+        }
+      }
+    }
+    if (Object.keys(extra).length > 0) {
+      extraSource = extra;
     }
-  } else if (variantCode.source) {
-    source = stringOrHastToJsx(variantCode.source);
   }
 
-  if (needsAllVariants || needsAllFiles) {
-    const extraSource = toExtraSource(variantCode, fileName);
-
-    if (needsAllVariants) {
-      const extraVariants = Object.entries(code || {}).reduce(
-        (acc, [name, vCode]) => {
-          if (name !== variant && vCode && typeof vCode !== 'string') {
-            const extraVariantExtraSource = toExtraSource(vCode, vCode.fileName);
-
-            acc[name] = {
-              fileNames: [vCode.fileName, ...Object.keys(vCode.extraFiles || {})].filter(
-                (fn): fn is string => Boolean(fn),
-              ), // TODO: use filesOrder if provided
-              source: vCode.source && stringOrHastToJsx(vCode.source),
-              extraSource: extraVariantExtraSource,
-            };
+  if (needsAllVariants) {
+    const extraVariants = Object.entries(code || {}).reduce(
+      (acc, [name, vCode]) => {
+        if (name !== variant && vCode && typeof vCode !== 'string') {
+          const evFileNames = [vCode.fileName, ...Object.keys(vCode.extraFiles || {})].filter(
+            (fn): fn is string => Boolean(fn),
+          );
+          const evHasts = allFallbackHasts?.[name];
+          let evSource: FallbackNode[] | undefined;
+          let evExtraSource: Record<string, FallbackNode[]> | undefined;
+
+          if (evHasts) {
+            const evMainFile = vCode.fileName || evFileNames[0];
+            if (evMainFile && evHasts[evMainFile]) {
+              evSource = evHasts[evMainFile];
+            }
+            const evExtra: Record<string, FallbackNode[]> = {};
+            for (const [fName, h] of Object.entries(evHasts)) {
+              if (fName !== evMainFile) {
+                evExtra[fName] = h;
+              }
+            }
+            if (Object.keys(evExtra).length > 0) {
+              evExtraSource = evExtra;
+            }
+          } else {
+            evSource = sourceToFallback(vCode.source);
+            const evExtra: Record<string, FallbackNode[]> = {};
+            for (const [fName, fData] of Object.entries(vCode.extraFiles || {})) {
+              if (typeof fData === 'object' && fData.source) {
+                const fb = sourceToFallback(fData.source);
+                if (fb) {
+                  evExtra[fName] = fb;
+                }
+              }
+            }
+            if (Object.keys(evExtra).length > 0) {
+              evExtraSource = evExtra;
+            }
           }
-          return acc;
-        },
-        {} as Record<string, ContentLoadingVariant>,
-      );
-
-      return {
-        fileNames,
-        source,
-        extraSource,
-        extraVariants,
-      };
-    }
+
+          acc[name] = {
+            fileNames: evFileNames,
+            ...(evSource ? { source: evSource } : undefined),
+            ...(evExtraSource ? { extraSource: evExtraSource } : undefined),
+          };
+        }
+        return acc;
+      },
+      {} as Record<string, ContentLoadingVariant>,
+    );
 
     return {
       fileNames,
-      source,
-      extraSource,
+      ...(source ? { source } : undefined),
+      ...(extraSource ? { extraSource } : undefined),
+      extraVariants,
     };
   }
 
   return {
     fileNames,
-    source,
+    ...(source ? { source } : undefined),
+    ...(extraSource ? { extraSource } : 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 function stripFallbackHastsFromCode(
+  code: Code | undefined,
+  variantName: string,
+  fallbackUsesExtraFiles?: boolean,
+  fallbackUsesAllVariants?: boolean,
+): { strippedCode: Code; allFallbackHasts: Record<string, Fallbacks> } {
+  if (!code) {
+    return { strippedCode: {}, allFallbackHasts: {} };
+  }
+
+  const allFallbackHasts: Record<string, Fallbacks> = {};
+  const strippedCode: Code = {};
+  const variantsToProcess = fallbackUsesAllVariants ? Object.keys(code) : [variantName];
+  const variantsToProcessSet = new Set(variantsToProcess);
+
+  for (const [key, variant] of Object.entries(code)) {
+    if (!variant || typeof variant === 'string' || !variantsToProcessSet.has(key)) {
+      strippedCode[key] = variant;
+      continue;
+    }
+
+    const hasts: Fallbacks = {};
+    let changed = false;
+
+    // Main file
+    if (variant.fallback && variant.fileName) {
+      hasts[variant.fileName] = variant.fallback;
+      changed = true;
+    }
+
+    // Extra files
+    let strippedExtraFiles = variant.extraFiles;
+    if ((fallbackUsesExtraFiles || fallbackUsesAllVariants) && variant.extraFiles) {
+      const newExtraFiles = { ...variant.extraFiles };
+      for (const [fName, fData] of Object.entries(variant.extraFiles)) {
+        if (typeof fData !== 'string' && fData.fallback) {
+          hasts[fName] = fData.fallback;
+          const { fallback: omittedFallback, ...rest } = fData;
+          newExtraFiles[fName] = rest;
+          changed = true;
+        }
+      }
+      if (changed) {
+        strippedExtraFiles = newExtraFiles;
+      }
+    }
+
+    if (changed) {
+      const { fallback: omittedFallback, ...restVariant } = variant;
+      strippedCode[key] = { ...restVariant, extraFiles: strippedExtraFiles };
+    } else {
+      strippedCode[key] = variant;
+    }
+
+    if (Object.keys(hasts).length > 0) {
+      allFallbackHasts[key] = hasts;
+    }
+  }
+
+  return { strippedCode, allFallbackHasts };
+}
diff --git a/packages/docs-infra/src/CodeHighlighter/errors.ts b/packages/docs-infra/src/CodeHighlighter/errors.ts
index cf0368f3d..ce8a935a6 100644
--- a/packages/docs-infra/src/CodeHighlighter/errors.ts
+++ b/packages/docs-infra/src/CodeHighlighter/errors.ts
@@ -280,6 +280,15 @@ export class ErrorCodeHighlighterClientMissingData extends ErrorCodeHighlighterC
   }
 }
 
+export class ErrorCodeHighlighterClientMissingFallbackHoist extends ErrorCodeHighlighterClientValidation {
+  constructor() {
+    super(
+      `Missing fallback data - A ContentLoading component was provided but did not hoist fallback data. ` +
+        `Make sure your ContentLoading component calls \`useCodeFallback(props)\` and passes the component props.`,
+    );
+  }
+}
+
 // === CONSOLE ERROR CLASSES ===
 
 // Server console errors
diff --git a/packages/docs-infra/src/CodeHighlighter/fallbackFormat.test.ts b/packages/docs-infra/src/CodeHighlighter/fallbackFormat.test.ts
new file mode 100644
index 000000000..8d933d838
--- /dev/null
+++ b/packages/docs-infra/src/CodeHighlighter/fallbackFormat.test.ts
@@ -0,0 +1,283 @@
+import { describe, it, expect } from 'vitest';
+import type { Root as HastRoot } from 'hast';
+import { hastToFallback, fallbackToHast, fallbackToText } from './fallbackFormat';
+import type { FallbackNode } from './fallbackFormat';
+
+function hast(...children: HastRoot['children']): HastRoot {
+  return { type: 'root', children };
+}
+
+describe('hastToFallback', () => {
+  it('should convert text nodes to plain strings', () => {
+    const root = hast({ type: 'text', value: 'hello' });
+    expect(hastToFallback(root)).toEqual(['hello']);
+  });
+
+  it('should produce length-2 tuple for element with no class and no props', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: {},
+      children: [{ type: 'text', value: 'hi' }],
+    });
+    expect(hastToFallback(root)).toEqual([['span', 'hi']]);
+  });
+
+  it('should produce length-3 tuple for element with class only', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: { className: ['token', 'keyword'] },
+      children: [{ type: 'text', value: 'const' }],
+    });
+    expect(hastToFallback(root)).toEqual([['span', 'token keyword', 'const']]);
+  });
+
+  it('should produce length-4 tuple for element with class and props', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'a',
+      properties: { className: ['link'], href: '/foo' },
+      children: [{ type: 'text', value: 'click' }],
+    });
+    expect(hastToFallback(root)).toEqual([['a', 'link', { href: '/foo' }, 'click']]);
+  });
+
+  it('should produce length-4 tuple for element with props but no class', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'a',
+      properties: { href: '/bar' },
+      children: [{ type: 'text', value: 'link' }],
+    });
+    // classStr is '' but props exist, so length-4 with empty className
+    expect(hastToFallback(root)).toEqual([['a', '', { href: '/bar' }, 'link']]);
+  });
+
+  it('should inline single text child as string', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: {},
+      children: [{ type: 'text', value: 'only child' }],
+    });
+    const [node] = hastToFallback(root);
+    expect((node as [string, string])[1]).toBe('only child');
+  });
+
+  it('should use array for multiple children', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: {},
+      children: [
+        { type: 'text', value: 'a' },
+        { type: 'text', value: 'b' },
+      ],
+    });
+    expect(hastToFallback(root)).toEqual([['span', ['a', 'b']]]);
+  });
+
+  it('should handle empty children', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'br',
+      properties: {},
+      children: [],
+    });
+    expect(hastToFallback(root)).toEqual([['br', []]]);
+  });
+
+  it('should handle nested elements', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'div',
+      properties: {},
+      children: [
+        {
+          type: 'element',
+          tagName: 'span',
+          properties: { className: ['hl'] },
+          children: [{ type: 'text', value: 'nested' }],
+        },
+      ],
+    });
+    expect(hastToFallback(root)).toEqual([['div', [['span', 'hl', 'nested']]]]);
+  });
+
+  it('should join className arrays with spaces', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: { className: ['a', 'b', 'c'] },
+      children: [{ type: 'text', value: '' }],
+    });
+    expect(hastToFallback(root)).toEqual([['span', 'a b c', '']]);
+  });
+
+  it('should convert string className to string', () => {
+    const root = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: { className: 'solo' },
+      children: [{ type: 'text', value: 'x' }],
+    });
+    expect(hastToFallback(root)).toEqual([['span', 'solo', 'x']]);
+  });
+});
+
+describe('fallbackToHast', () => {
+  it('should convert plain string back to text node', () => {
+    expect(fallbackToHast(['hello'])).toEqual(hast({ type: 'text', value: 'hello' }));
+  });
+
+  it('should convert length-2 tuple back to element', () => {
+    const result = fallbackToHast([['span', 'hi']]);
+    expect(result).toEqual(
+      hast({
+        type: 'element',
+        tagName: 'span',
+        properties: {},
+        children: [{ type: 'text', value: 'hi' }],
+      }),
+    );
+  });
+
+  it('should convert length-3 tuple back to element with class', () => {
+    const result = fallbackToHast([['span', 'token keyword', 'const']]);
+    expect(result).toEqual(
+      hast({
+        type: 'element',
+        tagName: 'span',
+        properties: { className: ['token', 'keyword'] },
+        children: [{ type: 'text', value: 'const' }],
+      }),
+    );
+  });
+
+  it('should convert length-4 tuple back to element with class and props', () => {
+    const result = fallbackToHast([['a', 'link', { href: '/foo' }, 'click']]);
+    expect(result).toEqual(
+      hast({
+        type: 'element',
+        tagName: 'a',
+        properties: { className: ['link'], href: '/foo' },
+        children: [{ type: 'text', value: 'click' }],
+      }),
+    );
+  });
+
+  it('should handle array children in round-trip', () => {
+    const result = fallbackToHast([['div', ['a', 'b']]]);
+    expect(result).toEqual(
+      hast({
+        type: 'element',
+        tagName: 'div',
+        properties: {},
+        children: [
+          { type: 'text', value: 'a' },
+          { type: 'text', value: 'b' },
+        ],
+      }),
+    );
+  });
+});
+
+describe('hastToFallback → fallbackToHast round-trip', () => {
+  it('should round-trip text nodes', () => {
+    const original = hast({ type: 'text', value: 'hello world' });
+    expect(fallbackToHast(hastToFallback(original))).toEqual(original);
+  });
+
+  it('should round-trip element with class', () => {
+    const original = hast({
+      type: 'element',
+      tagName: 'span',
+      properties: { className: ['token', 'keyword'] },
+      children: [{ type: 'text', value: 'const' }],
+    });
+    expect(fallbackToHast(hastToFallback(original))).toEqual(original);
+  });
+
+  it('should round-trip element with class and props', () => {
+    const original = hast({
+      type: 'element',
+      tagName: 'a',
+      properties: { className: ['link'], href: '/foo' },
+      children: [{ type: 'text', value: 'click' }],
+    });
+    expect(fallbackToHast(hastToFallback(original))).toEqual(original);
+  });
+
+  it('should round-trip nested structure', () => {
+    const original = hast(
+      {
+        type: 'element',
+        tagName: 'span',
+        properties: { className: ['line'] },
+        children: [
+          {
+            type: 'element',
+            tagName: 'span',
+            properties: { className: ['token', 'keyword'] },
+            children: [{ type: 'text', value: 'const' }],
+          },
+          { type: 'text', value: ' ' },
+          {
+            type: 'element',
+            tagName: 'span',
+            properties: { className: ['token', 'variable'] },
+            children: [{ type: 'text', value: 'x' }],
+          },
+        ],
+      },
+      { type: 'text', value: '\n' },
+    );
+    expect(fallbackToHast(hastToFallback(original))).toEqual(original);
+  });
+
+  it('should round-trip bare element (no class, no props)', () => {
+    const original = hast({
+      type: 'element',
+      tagName: 'div',
+      properties: {},
+      children: [{ type: 'text', value: 'plain' }],
+    });
+    expect(fallbackToHast(hastToFallback(original))).toEqual(original);
+  });
+});
+
+describe('fallbackToText', () => {
+  it('should extract text from plain strings', () => {
+    expect(fallbackToText(['hello', ' ', 'world'])).toBe('hello world');
+  });
+
+  it('should extract text from length-2 tuples', () => {
+    expect(fallbackToText([['span', 'hi']])).toBe('hi');
+  });
+
+  it('should extract text from length-3 tuples', () => {
+    expect(fallbackToText([['span', 'token', 'const']])).toBe('const');
+  });
+
+  it('should extract text from length-4 tuples', () => {
+    expect(fallbackToText([['a', 'link', { href: '/' }, 'click']])).toBe('click');
+  });
+
+  it('should extract text from nested structures', () => {
+    const nodes: FallbackNode[] = [
+      ['span', [['span', 'kw', 'const'], ' x = ', ['span', 'num', '1']]],
+      '\n',
+    ];
+    expect(fallbackToText(nodes)).toBe('const x = 1\n');
+  });
+
+  it('should return empty string for empty input', () => {
+    expect(fallbackToText([])).toBe('');
+  });
+
+  it('should handle mixed text and elements', () => {
+    const nodes: FallbackNode[] = ['before ', ['span', 'mid'], ' after'];
+    expect(fallbackToText(nodes)).toBe('before mid after');
+  });
+});
diff --git a/packages/docs-infra/src/CodeHighlighter/fallbackFormat.ts b/packages/docs-infra/src/CodeHighlighter/fallbackFormat.ts
new file mode 100644
index 000000000..935534a65
--- /dev/null
+++ b/packages/docs-infra/src/CodeHighlighter/fallbackFormat.ts
@@ -0,0 +1,160 @@
+import type { Root as HastRoot, RootContent, Element as HastElement, Text as HastText } from 'hast';
+
+/**
+ * Compact serialization format for fallback HAST trees.
+ *
+ * A `FallbackNode` is either:
+ * - a plain string (text node), or
+ * - a variable-length tuple whose meaning is determined by length:
+ *   - `[tagName, children]`                                – no class, no props
+ *   - `[tagName, className, children]`                     – has class, no props
+ *   - `[tagName, className, properties, children]`         – has class and props
+ *   - `[tagName, className, properties, children, extra]`  – full
+ *
+ * Where:
+ *   - `tagName`    – HTML element name (e.g. `'span'`, `'a'`)
+ *   - `className`  – space-joined class string
+ *   - `properties` – remaining HTML properties (without `className`)
+ *   - `children`   – a single text string **or** an array of child `FallbackNode`s
+ *   - `extra`      – optional bag for anything else (data attributes, etc.)
+ *
+ * This eliminates the repeated `type`, `tagName`, `properties`, `children`,
+ * and `value` keys that make raw HAST costly in RSC payloads.
+ */
+export type FallbackNode = string | FallbackElement;
+
+export type FallbackElement =
+  | [tagName: string, children: string | FallbackNode[]]
+  | [tagName: string, className: string, children: string | FallbackNode[]]
+  | [
+      tagName: string,
+      className: string,
+      properties: Record<string, unknown>,
+      children: string | FallbackNode[],
+    ]
+  | [
+      tagName: string,
+      className: string,
+      properties: Record<string, unknown>,
+      children: string | FallbackNode[],
+      extra: Record<string, unknown>,
+    ];
+
+/**
+ * Convert a HAST root into the compact `FallbackNode[]` format.
+ */
+export function hastToFallback(root: HastRoot): FallbackNode[] {
+  return convertChildren(root.children as RootContent[]);
+}
+
+function convertChildren(children: RootContent[]): FallbackNode[] {
+  return children.map(convertNode);
+}
+
+function convertNode(node: RootContent): FallbackNode {
+  if (node.type === 'text') {
+    return (node as HastText).value;
+  }
+
+  if (node.type === 'element') {
+    const el = node as HastElement;
+    const { className, ...restProps } = el.properties || {};
+
+    let classStr = '';
+    if (className != null) {
+      classStr = Array.isArray(className) ? (className as string[]).join(' ') : String(className);
+    }
+
+    const props = Object.keys(restProps).length > 0 ? restProps : null;
+    const kids = el.children as RootContent[];
+
+    // Optimize single-text-child to inline string
+    let childValue: string | FallbackNode[];
+    if (kids.length === 1 && kids[0].type === 'text') {
+      childValue = (kids[0] as HastText).value;
+    } else {
+      childValue = convertChildren(kids);
+    }
+
+    // Variable-length tuple: omit trailing empty fields
+    if (props !== null) {
+      return [el.tagName, classStr, props, childValue];
+    }
+    if (classStr) {
+      return [el.tagName, classStr, childValue];
+    }
+    return [el.tagName, childValue];
+  }
+
+  // For any other node types (comment, doctype, etc.), skip
+  return '';
+}
+
+/**
+ * Convert the compact `FallbackNode[]` format back into a HAST root.
+ */
+export function fallbackToHast(nodes: FallbackNode[]): HastRoot {
+  return {
+    type: 'root',
+    children: nodes.map(nodeToHast) as RootContent[],
+  };
+}
+
+function nodeToHast(node: FallbackNode): RootContent {
+  if (typeof node === 'string') {
+    return { type: 'text', value: node } as HastText;
+  }
+
+  let tagName: string;
+  let classStr: string | undefined;
+  let props: Record<string, unknown> | undefined;
+  let children: string | FallbackNode[];
+  let extra: Record<string, unknown> | undefined;
+
+  if (node.length === 2) {
+    [tagName, children] = node;
+  } else if (node.length === 3) {
+    [tagName, classStr, children] = node;
+  } else if (node.length === 5) {
+    [tagName, classStr, props, children, extra] = node;
+  } else {
+    [tagName, classStr, props, children] = node;
+  }
+
+  const properties: Record<string, unknown> = { ...props, ...extra };
+  if (classStr) {
+    properties.className = classStr.split(' ');
+  }
+
+  const childNodes: RootContent[] =
+    typeof children === 'string'
+      ? [{ type: 'text', value: children } as HastText]
+      : children.map(nodeToHast);
+
+  return {
+    type: 'element',
+    tagName,
+    properties,
+    children: childNodes,
+  } as unknown as RootContent;
+}
+
+/**
+ * Extract the text content from compact `FallbackNode[]` without
+ * converting back to HAST. Used to build DEFLATE dictionaries.
+ */
+export function fallbackToText(nodes: FallbackNode[]): string {
+  return nodes.map(nodeText).join('');
+}
+
+function nodeText(node: FallbackNode): string {
+  if (typeof node === 'string') {
+    return node;
+  }
+  // children is always the last element (or second-to-last when extra is present)
+  const children = node.length === 5 ? node[3] : node[node.length - 1];
+  if (typeof children === 'string') {
+    return children;
+  }
+  return (children as FallbackNode[]).map(nodeText).join('');
+}
diff --git a/packages/docs-infra/src/CodeHighlighter/index.ts b/packages/docs-infra/src/CodeHighlighter/index.ts
index 9608e7adc..37a3ec65d 100644
--- a/packages/docs-infra/src/CodeHighlighter/index.ts
+++ b/packages/docs-infra/src/CodeHighlighter/index.ts
@@ -1 +1,3 @@
 export * from './CodeHighlighter';
+export { useCodeFallback } from './useCodeFallback';
+export type { UseCodeFallbackResult } from './useCodeFallback';
diff --git a/packages/docs-infra/src/CodeHighlighter/types.ts b/packages/docs-infra/src/CodeHighlighter/types.ts
index a64364220..89608ceda 100644
--- a/packages/docs-infra/src/CodeHighlighter/types.ts
+++ b/packages/docs-infra/src/CodeHighlighter/types.ts
@@ -1,5 +1,6 @@
 import type { Root, RootData } from 'hast';
 import type { Delta } from 'jsondiffpatch';
+import type { FallbackNode } from './fallbackFormat';
 
 export type Components = { [key: string]: React.ReactNode };
 
@@ -39,6 +40,11 @@ export type VariantExtraFiles = {
     | {
         /** Source content for this file */
         source?: VariantSource;
+        /**
+         * Compact fallback for this extra file.
+         * See `VariantCode.fallback` for details.
+         */
+        fallback?: FallbackNode[];
         /** Language for syntax highlighting (e.g., 'tsx', 'css'). Derived from fileName extension if not provided. */
         language?: string;
         /** Transformations that can be applied to this file */
@@ -63,6 +69,14 @@ export type VariantCode = CodeMeta & {
   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 */
@@ -104,10 +118,17 @@ type BaseContentProps = CodeIdentityProps &
   Pick<CodeContentProps, 'code' | 'components' | 'variantType'>;
 
 export type ContentProps<T extends {}> = BaseContentProps & T;
+/**
+ * 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.
+ */
+export type Fallbacks = Record<string, FallbackNode[]>;
+
 export type ContentLoadingVariant = {
   fileNames?: string[];
-  source?: React.ReactNode;
-  extraSource?: { [fileName: string]: React.ReactNode };
+  source?: FallbackNode[];
+  extraSource?: Record<string, FallbackNode[]>;
 };
 export type BaseContentLoadingProps = ContentLoadingVariant &
   CodeIdentityProps & {
@@ -118,6 +139,7 @@ export type ContentLoadingProps<T extends {}> = BaseContentLoadingProps &
     component: React.ReactNode;
     components?: Record<string, React.ReactNode>;
     initialFilename?: string;
+    initialVariant?: string;
   };
 
 export type LoadCodeMeta = (url: string) => Promise<Code>;
@@ -194,6 +216,21 @@ export interface 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;
 }
 
 /**
diff --git a/packages/docs-infra/src/CodeHighlighter/useCodeFallback.ts b/packages/docs-infra/src/CodeHighlighter/useCodeFallback.ts
new file mode 100644
index 000000000..6db92096e
--- /dev/null
+++ b/packages/docs-infra/src/CodeHighlighter/useCodeFallback.ts
@@ -0,0 +1,156 @@
+'use client';
+
+import * as React from 'react';
+import type { ContentLoadingVariant, Fallbacks, HastRoot } from './types';
+import { fallbackToHast } from './fallbackFormat';
+import { CodeHighlighterFallbackContext } from './CodeHighlighterFallbackContext';
+
+export interface UseCodeFallbackResult {
+  source?: HastRoot;
+  fileNames?: string[];
+  extraSource?: Record<string, HastRoot>;
+  extraVariants?: Record<string, UseCodeFallbackVariantResult>;
+}
+
+export interface UseCodeFallbackVariantResult {
+  fileNames?: string[];
+  source?: HastRoot;
+  extraSource?: Record<string, HastRoot>;
+}
+
+interface UseCodeFallbackProps extends ContentLoadingVariant {
+  initialVariant?: string;
+  initialFilename?: string;
+  extraVariants?: Record<string, ContentLoadingVariant>;
+}
+
+function convertVariantSource(variant: ContentLoadingVariant): UseCodeFallbackVariantResult {
+  let source: HastRoot | undefined;
+  let extraSource: Record<string, HastRoot> | undefined;
+  if (variant.source) {
+    source = fallbackToHast(variant.source);
+  }
+  if (variant.extraSource) {
+    extraSource = {};
+    for (const [fName, nodes] of Object.entries(variant.extraSource)) {
+      extraSource[fName] = fallbackToHast(nodes);
+    }
+  }
+  return { fileNames: variant.fileNames, source, extraSource };
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * function MyContentLoading(props: ContentLoadingProps<{}>) {
+ *   const { source, extraSource } = useCodeFallback(props);
+ *   return (
+ *     <div>
+ *       {source && hastToJsx(source)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useCodeFallback(props?: UseCodeFallbackProps): UseCodeFallbackResult {
+  const ctx = React.useContext(CodeHighlighterFallbackContext);
+  const { setFallbackHasts, onHookCalled } = ctx || {};
+  const variantName = props?.initialVariant;
+  const mainFile = props?.initialFilename || props?.fileNames?.[0];
+  const source = props?.source;
+  const extraSource = props?.extraSource;
+  const propsExtraVariants = props?.extraVariants;
+  const ctxExtraVariants = ctx?.extraVariants;
+
+  // Signal to parent that useCodeFallback was called with props.
+  // Only fires when props are provided — calling without props is the
+  // exact misuse we want to detect. Child effects fire before parent
+  // effects, so the flag is set before the parent's validation runs.
+  const hasProps = !!props;
+  React.useEffect(() => {
+    if (hasProps) {
+      onHookCalled?.();
+    }
+  }, [hasProps, onHookCalled]);
+
+  // Hoist fallback data to CodeHighlighterClient via effect (not during render).
+  // Deps use individual fields to avoid re-running when the props object identity changes.
+  React.useEffect(() => {
+    if (!setFallbackHasts || !variantName) {
+      return;
+    }
+
+    // Hoist main variant source/extraSource (compact format)
+    if (source || extraSource) {
+      const hasts: Fallbacks = {};
+      if (source && mainFile) {
+        hasts[mainFile] = source;
+      }
+      if (extraSource) {
+        Object.assign(hasts, extraSource);
+      }
+      if (Object.keys(hasts).length > 0) {
+        setFallbackHasts(variantName, hasts);
+      }
+    }
+
+    // Hoist extra variant fallbacks
+    const allExtraVariants = propsExtraVariants || ctxExtraVariants;
+    if (allExtraVariants) {
+      for (const [name, variant] of Object.entries(allExtraVariants)) {
+        if (variant.source) {
+          const hasts: Fallbacks = {};
+          const evMainFile = variant.fileNames?.[0];
+          if (evMainFile && variant.source) {
+            hasts[evMainFile] = variant.source;
+          }
+          if (variant.extraSource) {
+            Object.assign(hasts, variant.extraSource);
+          }
+          if (Object.keys(hasts).length > 0) {
+            setFallbackHasts(name, hasts);
+          }
+        }
+      }
+    }
+  }, [
+    setFallbackHasts,
+    variantName,
+    mainFile,
+    source,
+    extraSource,
+    propsExtraVariants,
+    ctxExtraVariants,
+  ]);
+
+  if (!props) {
+    return {};
+  }
+
+  // Resolve extraVariants: prefer props, fall back to context
+  const allExtraVariants = propsExtraVariants || ctxExtraVariants;
+  let resolvedExtraVariants: Record<string, UseCodeFallbackVariantResult> | undefined;
+
+  if (allExtraVariants) {
+    resolvedExtraVariants = {};
+    for (const [name, variant] of Object.entries(allExtraVariants)) {
+      resolvedExtraVariants[name] = convertVariantSource(variant);
+    }
+  }
+
+  return {
+    ...convertVariantSource(props),
+    extraVariants: resolvedExtraVariants,
+  };
+}
diff --git a/packages/docs-infra/src/abstractCreateTypes/typesToJsx.ts b/packages/docs-infra/src/abstractCreateTypes/typesToJsx.ts
index 84d34a06f..c0f66b80b 100644
--- a/packages/docs-infra/src/abstractCreateTypes/typesToJsx.ts
+++ b/packages/docs-infra/src/abstractCreateTypes/typesToJsx.ts
@@ -427,6 +427,12 @@ type SerializedHastInput = HastNodes | { hastJson: string } | { hastCompressed:
 /**
  * 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: SerializedHastInput): { hast: HastNodes; freshCopy: boolean } {
   if (typeof input === 'object' && input !== null) {
@@ -562,12 +568,20 @@ function hastToJsxDeferred(
     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] as HastRoot['children'],
   });
   const fallback = hastToFallback(linksOnlyRoot);
+
+  // 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.
   const textContent = fallbackToText(fallback);
 
   // Serialize the enhanced HAST (post-enhancer) for the client.
@@ -581,7 +595,9 @@ function hastToJsxDeferred(
   const preElement = findPreElement(hast);
   const PreComponent = (components?.pre ?? 'pre') as React.ElementType;
 
-  // 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 React.createElement(
     PreComponent,
     hastPropsToReactProps(preElement?.properties),
diff --git a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeFallback.ts b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeFallback.ts
index 27357e2a6..5d6de23ef 100644
--- a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeFallback.ts
+++ b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeFallback.ts
@@ -407,6 +407,7 @@ export async function loadCodeFallback(
       disableParsing: !shouldHighlight, // Only parse if highlighting is needed
       globalsCode: resolvedGlobalsCode, // Pass resolved globalsCode
       output,
+      compressWithFallbackDictionary: true,
     });
 
     currentMark = performanceMeasure(
@@ -489,6 +490,7 @@ export async function loadCodeFallback(
             disableTransforms: true,
             disableParsing: !shouldHighlight,
             output,
+            compressWithFallbackDictionary: true,
             globalsCode:
               globalsCodeObjects && globalsCodeObjects.length > 0
                 ? (() => {
diff --git a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts
index 8639adb73..2be3a9e12 100644
--- a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts
+++ b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts
@@ -285,11 +285,11 @@ describe('loadCodeVariant', () => {
             ],
           },
         ],
-      });
+      }); // Should have basic HAST node
       expect(result.code.fileName).toBeUndefined();
-      expect(result.dependencies).toEqual([]);
+      expect(result.dependencies).toEqual([]); // No URL, so no dependencies
       expect(mockParseSource).not.toHaveBeenCalled(); // No language, so parseSource not used
-      expect(mockLoadSource).not.toHaveBeenCalled();
+      expect(mockLoadSource).not.toHaveBeenCalled(); // No loading needed
     });
 
     it('should parse source when language is provided but no fileName or URL', async () => {
@@ -316,7 +316,7 @@ describe('loadCodeVariant', () => {
 
       expect(result.code.source).toEqual(mockParsedSource); // Should be parsed
       expect(result.code.language).toBe('typescript');
-      expect(result.code.fileName).toBeUndefined(); // No fileName available
+      expect(result.code.fileName).toBeUndefined();
       expect(result.dependencies).toEqual([]); // No URL, so no dependencies
       expect(mockParseSource).toHaveBeenCalledWith('const x = 1;', '', 'typescript'); // Parse with empty fileName
       expect(mockLoadSource).not.toHaveBeenCalled(); // No loading needed
diff --git a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts
index b7155ce56..1f761d591 100644
--- a/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts
+++ b/packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts
@@ -1,5 +1,8 @@
 import * as path from 'path-module';
+import { toText } from 'hast-util-to-text';
 import { compressHastAsync } from '../hastUtils';
+import { stripHighlightingSpans } from '../hastUtils/stripHighlightingSpans';
+import { hastToFallback } from '../../CodeHighlighter/fallbackFormat';
 import { transformSource } from './transformSource';
 import { diffHast } from './diffHast';
 import { getFileNameFromUrl, getLanguageFromExtension, normalizeLanguage } from '../loaderUtils';
@@ -19,6 +22,7 @@ import type {
   Externals,
   HastRoot,
 } from '../../CodeHighlighter/types';
+import type { FallbackNode } from '../../CodeHighlighter/fallbackFormat';
 import { performanceMeasure } from '../loadPrecomputedCodeHighlighter/performanceLogger';
 import { starryNightGutter } from '../parseSource/addLineGutters';
 
@@ -180,6 +184,7 @@ async function loadSingleFile(
   variantComments?: SourceComments,
 ): Promise<{
   source: VariantSource;
+  fallback?: FallbackNode[];
   transforms?: Transforms;
   extraFiles?: VariantExtraFiles;
   extraDependencies?: string[];
@@ -189,6 +194,7 @@ async function loadSingleFile(
   const { disableTransforms = false, disableParsing = false } = options;
 
   let finalSource = source;
+  let finalFallback: FallbackNode[] | undefined;
   let extraFilesFromSource: VariantExtraFiles | undefined;
   let extraDependenciesFromSource: string[] | undefined;
   let externalsFromSource: Externals | undefined;
@@ -389,8 +395,18 @@ async function loadSingleFile(
       }
 
       if (options.output === 'hastCompressed' && process.env.NODE_ENV === 'production') {
-        const hastCompressed = await compressHastAsync(JSON.stringify(finalSource));
-        finalSource = { hastCompressed };
+        const json = JSON.stringify(finalSource);
+        if (options.compressWithFallbackDictionary) {
+          // Use the fallback text as a DEFLATE dictionary for better compression.
+          // The fallback travels via context so the client can rebuild the dictionary.
+          const strippedHast = stripHighlightingSpans(finalSource);
+          const textContent = toText(strippedHast, { whitespace: 'pre' });
+          finalFallback = hastToFallback(strippedHast);
+          finalSource = { hastCompressed: await compressHastAsync(json, textContent) };
+        } else {
+          // Compress with the static shared dictionary only.
+          finalSource = { hastCompressed: await compressHastAsync(json) };
+        }
 
         currentMark = performanceMeasure(
           currentMark,
@@ -416,6 +432,7 @@ async function loadSingleFile(
 
   return {
     source: finalSource!,
+    fallback: finalFallback,
     transforms: finalTransforms,
     extraFiles: extraFilesFromSource,
     extraDependencies: extraDependenciesFromSource,
@@ -572,6 +589,7 @@ async function loadExtraFiles(
 
     processedExtraFiles[normalizedFileName] = {
       source: result.source,
+      ...(result.fallback && { fallback: result.fallback }),
       ...(extraFileLanguage && { language: extraFileLanguage }),
       ...(result.transforms && { transforms: result.transforms }),
       ...(metadata !== undefined && { metadata }),
@@ -757,6 +775,7 @@ export async function loadCodeVariant(
   // If we don't have a fileName and no URL, we can still parse if we have language
   if (!fileName && !url) {
     let finalSource: VariantSource | undefined = variant.source;
+    let finalFallback: FallbackNode[] | undefined;
 
     // Parse the source if we have language and sourceParser
     if (typeof finalSource === 'string' && language && sourceParser && !disableParsing) {
@@ -791,10 +810,28 @@ export async function loadCodeVariant(
       );
     }
 
+    // Apply output format conversion (same as loadSingleFile path).
+    if (finalSource && typeof finalSource === 'object' && 'type' in finalSource) {
+      if (options.output === 'hastCompressed' && process.env.NODE_ENV === 'production') {
+        const json = JSON.stringify(finalSource);
+        if (options.compressWithFallbackDictionary) {
+          const strippedHast = stripHighlightingSpans(finalSource);
+          const textContent = toText(strippedHast, { whitespace: 'pre' });
+          finalFallback = hastToFallback(strippedHast);
+          finalSource = { hastCompressed: await compressHastAsync(json, textContent) };
+        } else {
+          finalSource = { hastCompressed: await compressHastAsync(json) };
+        }
+      } else if (options.output === 'hastJson' || options.output === 'hastCompressed') {
+        finalSource = { hastJson: JSON.stringify(finalSource) };
+      }
+    }
+
     const finalVariant: VariantCode = {
       ...variant,
       language,
       source: finalSource,
+      ...(finalFallback ? { fallback: finalFallback } : {}),
     };
 
     return {
@@ -1100,6 +1137,7 @@ export async function loadCodeVariant(
     ...variant,
     language,
     source: mainFileResult.source,
+    ...(mainFileResult.fallback && { fallback: mainFileResult.fallback }),
     transforms: mainFileResult.transforms,
     extraFiles: Object.keys(allExtraFiles).length > 0 ? allExtraFiles : undefined,
     externals: Object.keys(allExternals).length > 0 ? Object.keys(allExternals) : undefined,
diff --git a/packages/docs-infra/src/pipeline/loadServerTypes/hastTypeUtils.ts b/packages/docs-infra/src/pipeline/loadServerTypes/hastTypeUtils.ts
index 5983d391f..0b93c8851 100644
--- a/packages/docs-infra/src/pipeline/loadServerTypes/hastTypeUtils.ts
+++ b/packages/docs-infra/src/pipeline/loadServerTypes/hastTypeUtils.ts
@@ -509,16 +509,17 @@ export function serializeHastRoot(hast: HastRoot): SerializedHastRoot {
 }
 
 /** Converts a HastRoot to a dictionary-compressed, base64-encoded wrapper. */
-export function compressHastRoot(hast: HastRoot): SerializedHastCompressed {
-  return { hastCompressed: compressHast(JSON.stringify(hast)) };
+export function compressHastRoot(hast: HastRoot, textContent?: string): SerializedHastCompressed {
+  return { hastCompressed: compressHast(JSON.stringify(hast), textContent) };
 }
 
 /** Returns the appropriate serializer function for the given output format. */
 export function resolveSerializer(
   output: TypesOutputFormat,
+  textContent?: string,
 ): (hast: HastRoot) => HastRoot | SerializedHastRoot | SerializedHastCompressed {
   if (output === 'hastCompressed') {
-    return compressHastRoot;
+    return (hast: HastRoot) => compressHastRoot(hast, textContent);
   }
   if (output === 'hastJson') {
     return serializeHastRoot;
diff --git a/packages/docs-infra/src/useCode/Pre.tsx b/packages/docs-infra/src/useCode/Pre.tsx
index 446409b41..7e3b2edbc 100644
--- a/packages/docs-infra/src/useCode/Pre.tsx
+++ b/packages/docs-infra/src/useCode/Pre.tsx
@@ -4,6 +4,8 @@ import * as React from 'react';
 import { toText } from 'hast-util-to-text';
 import { ElementContent } from 'hast';
 import type { HastRoot, VariantSource } from '../CodeHighlighter/types';
+import type { FallbackNode } from '../CodeHighlighter/fallbackFormat';
+import { fallbackToText } from '../CodeHighlighter/fallbackFormat';
 import { hastToJsx, decompressHast } from '../pipeline/hastUtils';
 
 const hastChildrenCache = new WeakMap<ElementContent[], React.ReactNode>();
@@ -75,6 +77,7 @@ export function Pre({
   ref,
   shouldHighlight,
   hydrateMargin = '200px 0px 200px 0px',
+  fallback,
 }: {
   children: VariantSource;
   className?: string;
@@ -82,7 +85,14 @@ export function Pre({
   ref?: React.Ref<HTMLPreElement>;
   shouldHighlight?: boolean;
   hydrateMargin?: string;
+  fallback?: FallbackNode[];
 }): React.ReactNode {
+  // Derive text dictionary from fallback for decompression.
+  const textDictionary = React.useMemo(
+    () => (fallback ? fallbackToText(fallback) : undefined),
+    [fallback],
+  );
+
   const hast = React.useMemo(() => {
     if (typeof children === 'string') {
       return null;
@@ -93,11 +103,11 @@ export function Pre({
     }
 
     if ('hastCompressed' in children) {
-      return JSON.parse(decompressHast(children.hastCompressed)) as HastRoot;
+      return JSON.parse(decompressHast(children.hastCompressed, textDictionary)) as HastRoot;
     }
 
     return children;
-  }, [children]);
+  }, [children, textDictionary]);
 
   const [visibleFrames, setVisibleFrames] = React.useState<{ [key: number]: boolean }>(() =>
     getInitialVisibleFrames(hast),
diff --git a/packages/docs-infra/src/useCode/useCode.ts b/packages/docs-infra/src/useCode/useCode.ts
index cd8252da1..1ad2182d2 100644
--- a/packages/docs-infra/src/useCode/useCode.ts
+++ b/packages/docs-infra/src/useCode/useCode.ts
@@ -164,6 +164,7 @@ export function useCode<T extends {} = {}>(
     saveVariantToLocalStorage: variantSelection.saveVariantToLocalStorage,
     hashVariant: variantSelection.hashVariant,
     sourceEnhancers,
+    fallbacks: context?.fallbacks,
   });
 
   // Sub-hook: Copy Functionality
diff --git a/packages/docs-infra/src/useCode/useFileNavigation.tsx b/packages/docs-infra/src/useCode/useFileNavigation.tsx
index 585e8d7b3..1e8f82b1a 100644
--- a/packages/docs-infra/src/useCode/useFileNavigation.tsx
+++ b/packages/docs-infra/src/useCode/useFileNavigation.tsx
@@ -2,12 +2,14 @@ import * as React from 'react';
 import type { Root as HastRoot } from 'hast';
 import { decompressHast } from '../pipeline/hastUtils';
 import type {
+  Fallbacks,
   VariantCode,
   VariantSource,
   Code,
   SourceEnhancers,
   SourceComments,
 } from '../CodeHighlighter/types';
+import { fallbackToText } from '../CodeHighlighter/fallbackFormat';
 import { useUrlHashState } from '../useUrlHashState';
 import { countLines } from '../pipeline/parseSource/addLineGutters';
 import { getLanguageFromExtension } from '../pipeline/loaderUtils/getLanguageFromExtension';
@@ -113,6 +115,10 @@ interface UseFileNavigationProps {
    * Enhancers receive the HAST root, comments extracted from source, and filename.
    */
   sourceEnhancers?: SourceEnhancers;
+  /**
+   * Compact fallback data for the active variant, keyed by filename.
+   */
+  fallbacks?: Fallbacks;
 }
 
 export interface UseFileNavigationResult {
@@ -145,6 +151,7 @@ export function useFileNavigation({
   saveVariantToLocalStorage,
   hashVariant,
   sourceEnhancers,
+  fallbacks,
 }: UseFileNavigationProps): UseFileNavigationResult {
   // Keep selectedFileName as untransformed filename for internal tracking
   const [selectedFileNameInternal, setSelectedFileNameInternal] = React.useState<
@@ -472,6 +479,7 @@ export function useFileNavigation({
     fileName: selectedFileName,
     comments: selectedFileComments,
     sourceEnhancers,
+    fallback: selectedFileNameInternal ? fallbacks?.[selectedFileNameInternal] : undefined,
   });
 
   const selectedFileComponent = React.useMemo(() => {
@@ -511,6 +519,7 @@ export function useFileNavigation({
           language={language}
           ref={preRef}
           shouldHighlight={shouldHighlight}
+          fallback={selectedFileNameInternal ? fallbacks?.[selectedFileNameInternal] : undefined}
         >
           {sourceToRender}
         </Pre>
@@ -531,6 +540,7 @@ export function useFileNavigation({
     selectedVariantKey,
     sourceEnhancers,
     selectedFileNameInternal,
+    fallbacks,
   ]);
 
   const selectedFileLines = React.useMemo(() => {
@@ -549,7 +559,10 @@ export function useFileNavigation({
       if ('hastJson' in selectedFile) {
         hastSelectedFile = JSON.parse(selectedFile.hastJson);
       } else if ('hastCompressed' in selectedFile) {
-        hastSelectedFile = JSON.parse(decompressHast(selectedFile.hastCompressed));
+        const fb = selectedFileNameInternal ? fallbacks?.[selectedFileNameInternal] : undefined;
+        hastSelectedFile = JSON.parse(
+          decompressHast(selectedFile.hastCompressed, fb ? fallbackToText(fb) : undefined),
+        );
       } else {
         hastSelectedFile = selectedFile;
       }
@@ -573,7 +586,7 @@ export function useFileNavigation({
     }
 
     return 0;
-  }, [selectedFile]);
+  }, [selectedFile, selectedFileNameInternal, fallbacks]);
 
   // Convert files for the return interface
   const files = React.useMemo(() => {
@@ -620,6 +633,7 @@ export function useFileNavigation({
             language={selectedVariant.language}
             ref={preRef}
             shouldHighlight={shouldHighlight}
+            fallback={selectedVariant.fileName ? fallbacks?.[selectedVariant.fileName] : undefined}
           >
             {selectedVariant.source}
           </Pre>
@@ -658,6 +672,7 @@ export function useFileNavigation({
               language={language ?? getLanguageFromFileName(fileName)}
               ref={preRef}
               shouldHighlight={shouldHighlight}
+              fallback={fallbacks?.[fileName]}
             >
               {source}
             </Pre>
@@ -676,6 +691,7 @@ export function useFileNavigation({
     shouldHighlight,
     preClassName,
     preRef,
+    fallbacks,
   ]);
 
   // Create a wrapper for selectFileName that handles transformed filenames and URL updates
diff --git a/packages/docs-infra/src/useCode/useSourceEnhancing.ts b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
index c533eca1c..9f26a2ba5 100644
--- a/packages/docs-infra/src/useCode/useSourceEnhancing.ts
+++ b/packages/docs-infra/src/useCode/useSourceEnhancing.ts
@@ -9,6 +9,8 @@ import type {
   VariantSource,
   HastRoot as TypedHastRoot,
 } from '../CodeHighlighter/types';
+import type { FallbackNode } from '../CodeHighlighter/fallbackFormat';
+import { fallbackToText } from '../CodeHighlighter/fallbackFormat';
 
 /**
  * Type guard to check if a source value is a HAST root node.
@@ -28,7 +30,10 @@ function isHastRoot(source: unknown): source is HastRoot {
  * @param source - The source to resolve (can be HAST, hastJson, hastCompressed, or string)
  * @returns The resolved HastRoot or null if the source cannot be resolved
  */
-function resolveHastRoot(source: VariantSource | undefined): HastRoot | null {
+function resolveHastRoot(
+  source: VariantSource | undefined,
+  textDictionary?: string,
+): HastRoot | null {
   if (!source) {
     return null;
   }
@@ -42,7 +47,7 @@ function resolveHastRoot(source: VariantSource | undefined): HastRoot | null {
   }
 
   if ('hastCompressed' in source) {
-    return JSON.parse(decompressHast(source.hastCompressed)) as HastRoot;
+    return JSON.parse(decompressHast(source.hastCompressed, textDictionary)) as HastRoot;
   }
 
   if (isHastRoot(source)) {
@@ -86,6 +91,8 @@ export interface UseSourceEnhancingProps {
   comments: SourceComments | undefined;
   /** Array of enhancer functions to apply */
   sourceEnhancers?: SourceEnhancers;
+  /** Fallback data for deriving the DEFLATE decompression dictionary */
+  fallback?: FallbackNode[];
 }
 
 export interface UseSourceEnhancingResult {
@@ -136,6 +143,7 @@ export function useSourceEnhancing({
   fileName,
   comments,
   sourceEnhancers,
+  fallback,
 }: UseSourceEnhancingProps): UseSourceEnhancingResult {
   // Track previous values to detect changes
   const [prevSource, setPrevSource] = React.useState(source);
@@ -173,7 +181,8 @@ export function useSourceEnhancing({
       return undefined;
     }
 
-    const resolvedHastRoot = resolveHastRoot(source);
+    const textDictionary = fallback ? fallbackToText(fallback) : undefined;
+    const resolvedHastRoot = resolveHastRoot(source, textDictionary);
     if (!resolvedHastRoot) {
       // Can't enhance non-HAST sources
       setEnhancedSource(source);
@@ -203,7 +212,7 @@ export function useSourceEnhancing({
     return () => {
       cancelled = true;
     };
-  }, [source, fileName, comments, sourceEnhancers]);
+  }, [source, fileName, comments, sourceEnhancers, fallback]);
 
   return {
     enhancedSource,