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

package/CodeHighlighter/types.d.mts

@@ -1,5 +1,6 @@
 import type { Root, RootData } from 'hast';
 import type { Delta } from 'jsondiffpatch';
+import type { FallbackNode, CompressedFallback } from "./fallbackFormat.mjs";
 export type Components = {
   [key: string]: React.ReactNode;
 };
@@ -11,9 +12,62 @@ type CodeMeta = {
   /** Flattened path for the file */
   path?: string;
 };
+/**
+ * Records the transforms available for a source. Each entry can provide a
+ * jsondiffpatch `delta` (the patch to apply against the source's parsed hast
+ * tree), an optional renamed `fileName`, and an optional `comments` map.
+ *
+ * When `comments` is present, it represents the post-transform comment map
+ * (1-indexed by line number in the transformed source) and is used as-is by
+ * `applyCodeTransformWithComments` instead of auto-shifting the caller's
+ * comments via the surviving `dataLn` mapping. Source transformers should
+ * only emit `comments` when they add or relocate lines; transforms that only
+ * wipe lines (replacing them with empty strings) are handled automatically.
+ *
+ * `hasDelta` indicates whether the entry actually produced a code-level
+ * difference. When `false` (or omitted), the entry is rename-only — it
+ * carries a renamed `fileName` (and optionally `comments`) but the
+ * transformed source is structurally identical to the original. Rename-only
+ * entries are excluded from `getAvailableTransforms` (so the toggle stays
+ * hidden when nothing meaningful changes) but still apply the rename when
+ * the user has the matching transform preference selected.
+ *
+ * `hasCollapse` indicates whether the inline `delta` (or the embedded delta
+ * matching this manifest entry) inserts a `.collapse` placeholder element.
+ * The runtime uses this flag to classify a transform swap as
+ * layout-affecting (phase 1: coordinated barrier so peers stay in lockstep)
+ * versus non-layout (phase 2: deferred until after phase 1 settles) without
+ * having to decompress the embedded hast payload on every selection
+ * change. Computed once during `splitTransformsForEmbed` and persisted on
+ * the manifest entry.
+ *
+ * `hasCollapseInFocus` is the focus-region-aware counterpart: it is `true`
+ * only when at least one `.collapse` placeholder lands inside the source
+ * region that is visible when the surrounding code block is *collapsed*
+ * (the lines covered by `data-frame-type` ∈ `'highlighted' | 'focus' |
+ * 'padding-top' | 'padding-bottom'`, falling back to the first frame when
+ * no emphasis frames exist — matching the runtime visibility rule in
+ * `<Pre>`). Consumers that opt into `transformLayoutShift: 'focus'` use
+ * this flag (instead of `hasCollapse`) while the block is collapsed, so a
+ * `.collapse` insertion outside the visible window doesn't force a
+ * coordinated barrier swap that the user wouldn't see anyway.
+ *
+ * After serialization (`output: 'hastJson' | 'hastCompressed'`), the deltas
+ * are moved inside the source's `HastRoot.data.transforms` so they ride
+ * along inside the compressed payload and never appear as plain JSON in the
+ * rendered HTML or in the demo module graph. In that mode the variant-level
+ * `transforms` field acts as a manifest — entries keep `fileName`,
+ * `comments` (when set), `hasDelta`, `hasCollapse`, and
+ * `hasCollapseInFocus` but `delta` is omitted. Consumers that need the
+ * delta should look it up inside the decompressed `root.data.transforms`.
+ */
 export type Transforms = Record<string, {
-  delta: Delta;
+  delta?: Delta;
   fileName?: string;
+  comments?: SourceComments;
+  hasDelta?: boolean;
+  hasCollapse?: boolean;
+  hasCollapseInFocus?: boolean;
 }>;
 export interface ExternalImportItem {
   name: string;
@@ -24,9 +78,25 @@ export type Externals = Record<string, ExternalImportItem[]>;
 export interface HastRoot extends Root {
   data?: RootData & {
     totalLines?: number;
+    /**
+     * Number of source lines visible inside the focused window when the code
+     * block is collapsed — the sum of frame sizes whose `data-frame-type` is
+     * `'highlighted'`, `'focus'`, `'padding-top'`, or `'padding-bottom'`.
+     * Equals `totalLines` when no emphasis directives are present (the whole
+     * source is the focused window). Set by `enhanceCodeEmphasis`.
+     */
+    focusedLines?: number;
     collapsible?: boolean;
     frameSize?: number;
     appliedEnhancers?: string[];
+    /**
+     * Transform deltas embedded in the hast root so they get compressed along
+     * with the tree and stay out of the rendered HTML / module graph. The
+     * variant-level `transforms` field is a `TransformManifest` (keys only)
+     * that mirrors `Object.keys(this.transforms)`. `hast-util-to-jsx-runtime`
+     * does not serialize `Root.data` to the DOM.
+     */
+    transforms?: Transforms;
   };
 }
 export type VariantSource = string | HastRoot | {
@@ -42,6 +112,15 @@ export type VariantExtraFiles = {
   [fileName: string]: string | {
     /** Source content for this file */
     source?: VariantSource;
+    /**
+     * Compact fallback for this extra file.
+     * See `VariantCode.fallback` for details.
+     */
+    fallback?: FallbackNode[];
+    /** Line counts for this file. See `VariantCode.totalLines` / `focusedLines`. */
+    totalLines?: number;
+    focusedLines?: number;
+    collapsible?: boolean;
     /** 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 */
@@ -76,6 +155,41 @@ 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[];
+  /**
+   * Staging-only highlighted-visible fallback, stored **sparsely**: a map from frame
+   * index to the highlighted `FallbackNode` for ONLY the frames visible on the initial
+   * (collapsed, `collapseToEmpty: false`) render. Off-screen frames are omitted — they
+   * are byte-identical to `fallback`'s plain output, so storing them would just
+   * duplicate `fallback` in the precompute. Computed at load time (where the source is
+   * still a live `HastRoot`, so no decompression) and carried in precomputed payloads
+   * alongside `fallback`. Under `highlightAt: 'init'` the server/client boundary
+   * `promoteCriticalFallback`s it over `fallback` so the first paint is highlighted with
+   * no client-side decompression, then deletes it: `fallbackCritical` must NEVER reach
+   * the `Content`/`ContentLoading` components. The promoted `fallback` has byte-identical
+   * text, so it stays a valid DEFLATE dictionary. See `resolveFallbackCritical`.
+   */
+  fallbackCritical?: {
+    [frameIndex: number]: FallbackNode;
+  };
+  /**
+   * Line counts for this variant's main source — the same for the full (highlighted)
+   * source and its `fallback`, since they're the same file. `totalLines` is the whole
+   * file; `focusedLines` is the collapsed-window size. The loader surfaces them
+   * with `collapsible` (notably for deferred plain-string sources, where the compact
+   * `fallback` drops `root.data` and a string can't recompute the metadata) so
+   * consumers can size and flag the `<code>` without re-deriving from counts.
+   */
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
   /** Additional files associated with this variant */
   extraFiles?: VariantExtraFiles;
   /** Prefix for metadata keys, e.g. /src */
@@ -106,6 +220,7 @@ export type Code = {
 export type CollapseMap = Record<number, Array<{
   offset: number;
   comments: string[];
+  boundary?: true;
 }>>;
 export type ControlledVariantExtraFiles = {
   [fileName: string]: {
@@ -133,14 +248,58 @@ export type ControlledCode = {
  * Base props passed to Content components for rendering code examples.
  * These props provide the necessary data for displaying code, previews, and metadata.
  */
-type BaseContentProps = CodeIdentityProps & Pick<CodeContentProps, 'code' | 'components' | 'variantType'>;
+type BaseContentProps = CodeIdentityProps & Pick<CodeContentProps, 'code' | 'components' | 'variantType'> & {
+  /**
+   * Render-time "collapse to empty": collapse the code block to an empty window so
+   * the whole block is hidden until the reader expands it. Runtime-only — it
+   * never changes the precomputed HAST, only how it's rendered.
+   */
+  collapseToEmpty?: boolean;
+  /**
+   * Whether the (collapsible) code block starts expanded. Runtime-only. Lives
+   * on `contentProps` rather than `useCode` opts so the loading fallback can
+   * see it too.
+   */
+  initialExpanded?: boolean;
+};
 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[]>;
+/**
+ * A framed fallback for one file: the compact `source` frames plus the file's
+ * loading metadata (`totalLines` whole-file, `focusedLines` collapsed-window,
+ * `collapsible` frame state). Carried per extra file so a `ContentLoading` can
+ * render the full framed code — with the right collapsed window — for every
+ * file/variant passed to the fallback, not just the displayed one. The main
+ * file's equivalent metadata lives on the variant as top-level fields alongside
+ * its top-level `source`.
+ */
+export type ContentLoadingFile = {
+  source: FallbackNode[];
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
+};
 export type ContentLoadingVariant = {
   fileNames?: string[];
-  source?: React.ReactNode;
-  extraSource?: {
-    [fileName: string]: React.ReactNode;
-  };
+  source?: FallbackNode[];
+  /** Loading metadata for the main `source` file. See {@link ContentLoadingFile}. */
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
+  /**
+   * Language hint for the rendered `source` (e.g. `'tsx'`, `'css'`). Derived
+   * from the variant's explicit `language` when set, otherwise from the
+   * selected file name's extension. Consumers typically forward this as a
+   * `language-{language}` class on the fallback `<code>` element so it picks
+   * up the same language-scoped styling as the post-load tree.
+   */
+  language?: string;
+  extraSource?: Record<string, ContentLoadingFile>;
 };
 export type BaseContentLoadingProps = ContentLoadingVariant & CodeIdentityProps & {
   extraVariants?: Record<string, ContentLoadingVariant>;
@@ -149,6 +308,34 @@ export type ContentLoadingProps<T extends {}> = BaseContentLoadingProps & T & {
   component: React.ReactNode;
   components?: Record<string, React.ReactNode>;
   initialFilename?: string;
+  /**
+   * Name of the variant currently selected for the fallback render — the
+   * same key passed to `codeToFallbackProps` and used to look up
+   * `component` / `components`. Consumers use this when labeling the main
+   * variant in the fallback UI or when generating per-file slugs.
+   */
+  initialVariant?: string;
+  /**
+   * Set when the surrounding `CodeHighlighter` uses `fallbackCollapsed`: the
+   * `source` here is only the collapsed window, and the hidden lines arrive
+   * later with the full content. A `ContentLoading` should disable any expand
+   * control while this is true — expanding would reveal nothing until the
+   * full content swaps in. `useCodeFallback` re-exposes it as `collapsed`.
+   */
+  fallbackCollapsed?: boolean;
+  /**
+   * Render-time "collapse to empty": the loading placeholder should paint an empty
+   * collapsed window (the whole block hidden until expanded), matching the
+   * hydrated render. `useCodeFallback` honors this by demoting collapsed-
+   * visible frame types in the returned `source`.
+   */
+  collapseToEmpty?: boolean;
+  /**
+   * Whether the block starts expanded. The loading placeholder uses it to
+   * paint the full content (not just the collapsed window) when the hydrated
+   * block will start expanded.
+   */
+  initialExpanded?: boolean;
 };
 export type LoadCodeMeta = (url: string) => Promise<Code>;
 export type LoadVariantMeta = (variantName: string, url: string) => Promise<VariantCode>;
@@ -160,9 +347,32 @@ export type LoadSource = (url: string) => Promise<{
   /** Comments extracted from the source code, keyed by line number */
   comments?: SourceComments;
 }>;
-export type TransformSource = (source: string, fileName: string) => Promise<Record<string, {
+/**
+ * Function that transforms a source file into one or more derived sources.
+ *
+ * @param source - The source code string to transform.
+ * @param fileName - File name (used for extension detection / diagnostics).
+ * @param comments - Optional comment map for `source`, keyed by 1-indexed
+ *   line number (the convention everywhere a `Code` is stored). Transformers
+ *   that want to shift comments manually should return a `comments` map
+ *   alongside each transformed source, using the same 1-indexed line scheme
+ *   relative to the returned source string.
+ * @returns A record keyed by transform name. Each entry must contain the
+ *   transformed `source` string, optionally a renamed `fileName`, and
+ *   optionally a `comments` map (1-indexed). The runtime applies `comments`
+ *   verbatim when present; when omitted, surviving lines' comments are
+ *   shifted automatically based on which source lines survived the transform.
+ *
+ *   Transformers that only **remove** lines should replace those lines with
+ *   empty strings rather than dropping them — the empty lines collapse
+ *   automatically at runtime and the auto-shift correctly maps the
+ *   surviving lines' comments. Only transformers that **add lines** or
+ *   completely replace the file need to return an explicit `comments` map.
+ */
+export type TransformSource = (source: string, fileName: string, comments?: SourceComments) => Promise<Record<string, {
   source: string;
   fileName?: string;
+  comments?: SourceComments;
 }> | undefined>;
 /**
  * Parses source code into a HAST tree with syntax highlighting.
@@ -213,6 +423,14 @@ export interface LoadFileOptions {
   disableTransforms?: boolean;
   /** Disable parsing source strings to AST */
   disableParsing?: boolean;
+  /**
+   * When parsing is skipped (`disableParsing`/deferred highlight) and the source
+   * stays a plain string, still derive a *framed* loading fallback from it —
+   * line-guttered plain-text HAST + enhancers → root fallback. Set by the loading
+   * fallback loader so the un-highlighted initial paint is framed (rendered code
+   * needs frames); left off for lazy variant loads that don't paint a fallback.
+   */
+  framePlainFallback?: boolean;
   /** Maximum recursion depth for loading nested extra files */
   maxDepth?: number;
   /** Set of already loaded file URLs to prevent circular dependencies */
@@ -296,8 +514,31 @@ export interface CodeLoadingProps {
   fallbackUsesExtraFiles?: boolean;
   /** Whether fallback content should include all variants */
   fallbackUsesAllVariants?: boolean;
+  /**
+   * Paint only the collapsed window in the `ContentLoading` fallback and defer
+   * each file's full fallback into the compressed payload. Shrinks the initial
+   * HTML of a collapsed block to its on-screen lines, but removes the hidden
+   * lines from the server-rendered markup — so it is **only** appropriate for
+   * content that will not be crawled (authenticated or internal pages). See the
+   * prop-compression pattern's "Splitting the Fallback by Visibility".
+   * @default false
+   */
+  fallbackCollapsed?: boolean;
   /** Enable controlled mode for external code state management */
   controlled?: boolean;
+  /**
+   * When the live-editing engine loads for an editable block:
+   *   - `'eager'` (default): load it as soon as the block is editable, and let
+   *     `CodeHighlighter` speculatively preload it on first render.
+   *   - `'interaction'`: defer the load until the reader hovers, focuses, or
+   *     clicks the code, and suppress the speculative preload — so a block the
+   *     reader never engages does not fetch the engine chunk at all.
+   *
+   * Only meaningful for editable blocks (a `CodeControllerContext` exposing
+   * `setCode`); ignored otherwise.
+   * @default 'eager'
+   */
+  editActivation?: 'eager' | 'interaction';
   /** Raw code string for simple use cases */
   children?: string;
   /**
@@ -368,7 +609,20 @@ export interface CodeClientRenderingProps {
  * Base props containing essential properties shared across CodeHighlighter components and helper functions.
  * This serves as the foundation for other CodeHighlighter-related interfaces.
  */
-export interface CodeHighlighterBaseProps<T extends {}> extends CodeIdentityProps, CodeContentProps, CodeLoadingProps, CodeFunctionProps, CodeRenderingProps<T> {}
+export interface CodeHighlighterBaseProps<T extends {}> extends CodeIdentityProps, CodeContentProps, CodeLoadingProps, CodeFunctionProps, CodeRenderingProps<T> {
+  /**
+   * Render-time "collapse to empty": collapse the code block to an empty window so
+   * the whole block is hidden until expanded. Threaded into `contentProps` and
+   * consumed by `useCode`/`<Pre>`. Runtime-only — the precomputed HAST is
+   * unchanged.
+   */
+  collapseToEmpty?: boolean;
+  /**
+   * Whether the (collapsible) code block starts expanded. Threaded into
+   * `contentProps` so both `useCode` and the loading fallback honor it.
+   */
+  initialExpanded?: boolean;
+}
 /**
  * Props for the client-side CodeHighlighter component.
  * Used when rendering happens in the browser with lazy loading and interactive features.
@@ -380,6 +634,16 @@ export interface CodeHighlighterClientProps extends CodeIdentityProps, CodeConte
    */
   highlightAfter?: 'init' | 'hydration' | 'idle';
   enhanceAfter?: 'init' | 'hydration' | 'idle';
+  /**
+   * The variant/file fallbacks a `ContentLoading` component never renders,
+   * consolidated into a single DEFLATE blob (see `compressResidualFallbacks`).
+   * The rendered subset crosses plain on `ContentLoading` props; this carries
+   * everything else compressed. Decompressed once on the client — using the
+   * hoisted rendered text as its preset dictionary — and scattered back onto
+   * `Code` before the content decodes. Absent when there is no residual worth
+   * compressing.
+   */
+  residualFallbacks?: CompressedFallback;
 }
 /**
  * Main props for the CodeHighlighter component.

package/CodeHighlighter/useCodeFallback.d.mts

@@ -0,0 +1,94 @@
+import * as React from 'react';
+import type { ContentLoadingVariant, HastRoot } from "./types.mjs";
+/**
+ * Render-time "collapse to empty" for the loading placeholder: demotes every
+ * collapsed-visible frame type in a fallback `HastRoot` to its hidden variant
+ * (matching `<Pre>`'s live rewrite) so the collapse CSS paints an empty window,
+ * and records `focusedLines: 0`. Mutates the freshly-decoded root in place.
+ */
+export declare function applyCollapseToEmptyToFallbackHast(root: HastRoot): HastRoot;
+/** A decoded extra-file fallback: the rendered `HastRoot` plus its line counts. */
+export interface UseCodeFallbackFile {
+  source: HastRoot;
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
+}
+export interface UseCodeFallbackResult {
+  source?: HastRoot;
+  fileNames?: string[];
+  extraSource?: Record<string, UseCodeFallbackFile>;
+  extraVariants?: Record<string, UseCodeFallbackVariantResult>;
+  /**
+   * `true` when the surrounding `CodeHighlighter` uses `fallbackCollapsed`, so
+   * `source` is only the collapsed window. A `ContentLoading` should disable any
+   * expand control while this is set — the hidden lines arrive with the full
+   * content, not the fallback.
+   */
+  collapsed?: boolean;
+  /**
+   * Line counts for the displayed file, threaded from the server (the compact
+   * `source` has dropped `root.data`, where they live). A `ContentLoading` mirrors
+   * them onto the fallback `<code>` as `data-total-lines` / `data-focused-lines` so
+   * it matches the hydrated `<Pre>`. `focusedLines` is the visible-window size —
+   * forced to 0 here when `collapseToEmpty` empties the painted window, so it stays
+   * consistent with the demoted `source`. `collapsible` is threaded separately
+   * from the enhancer/loader because counts alone cannot describe whether the
+   * collapsed frame structure has hidden content to expand into.
+   */
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
+  /**
+   * Ready-to-render `<code>` for the displayed file — the rendered `source` with
+   * `data-filename` / `data-collapsible` / `data-total-lines` / `data-focused-lines`
+   * and the `language-{language}` class already applied, matching `<Pre>`. Drop it
+   * into a `<pre>` so a `ContentLoading` needn't re-wire (or drift from) those
+   * attributes. `null` when there's no source to paint.
+   */
+  code?: React.ReactNode;
+}
+export interface UseCodeFallbackVariantResult {
+  fileNames?: string[];
+  source?: HastRoot;
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
+  extraSource?: Record<string, UseCodeFallbackFile>;
+}
+interface UseCodeFallbackProps extends ContentLoadingVariant {
+  initialVariant?: string;
+  initialFilename?: string;
+  extraVariants?: Record<string, ContentLoadingVariant>;
+  fallbackCollapsed?: boolean;
+  collapseToEmpty?: boolean;
+  totalLines?: number;
+  focusedLines?: number;
+  collapsible?: boolean;
+}
+/**
+ * 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 declare function useCodeFallback(props?: UseCodeFallbackProps): UseCodeFallbackResult;
+export {};

package/CodeHighlighter/useCodeFallback.mjs

@@ -0,0 +1,204 @@
+'use client';
+
+import * as React from 'react';
+import { fallbackToHast } from "./fallbackFormat.mjs";
+import { resolveCollapsedFrameType } from "../pipeline/parseSource/frameVisibility.mjs";
+import { isFrameSpan } from "../pipeline/parseSource/isFrameSpan.mjs";
+import { hastToJsx } from "../pipeline/hastUtils/index.mjs";
+import { CodeHighlighterFallbackContext } from "./CodeHighlighterFallbackContext.mjs";
+
+/**
+ * Render-time "collapse to empty" for the loading placeholder: demotes every
+ * collapsed-visible frame type in a fallback `HastRoot` to its hidden variant
+ * (matching `<Pre>`'s live rewrite) so the collapse CSS paints an empty window,
+ * and records `focusedLines: 0`. Mutates the freshly-decoded root in place.
+ */
+export function applyCollapseToEmptyToFallbackHast(root) {
+  for (const child of root.children) {
+    if (child.type !== 'element' || !isFrameSpan(child)) {
+      continue;
+    }
+    const frameType = typeof child.properties.dataFrameType === 'string' ? child.properties.dataFrameType : undefined;
+    const resolved = resolveCollapsedFrameType(frameType, true);
+    if (resolved === frameType) {
+      continue;
+    }
+    if (!resolved || resolved === 'normal') {
+      delete child.properties.dataFrameType;
+    } else {
+      child.properties.dataFrameType = resolved;
+    }
+  }
+  root.data = {
+    ...root.data,
+    focusedLines: 0
+  };
+  return root;
+}
+
+/** A decoded extra-file fallback: the rendered `HastRoot` plus its line counts. */
+
+function convertVariantSource(variant, collapseToEmpty = false) {
+  const rewrite = nodes => collapseToEmpty ? applyCollapseToEmptyToFallbackHast(nodes) : nodes;
+  // Collapse-to-empty empties every painted window, so report `focusedLines: 0` to
+  // match the demoted `source` (mirrors `<Pre>`'s `collapseToEmpty ? 0 : ...`).
+  const focused = value => collapseToEmpty ? 0 : value;
+  let source;
+  let extraSource;
+  if (variant.source) {
+    source = rewrite(fallbackToHast(variant.source));
+  }
+  if (variant.extraSource) {
+    extraSource = {};
+    for (const [fName, file] of Object.entries(variant.extraSource)) {
+      extraSource[fName] = {
+        source: rewrite(fallbackToHast(file.source)),
+        totalLines: file.totalLines,
+        focusedLines: focused(file.focusedLines),
+        collapsible: collapseToEmpty ? true : file.collapsible
+      };
+    }
+  }
+  return {
+    fileNames: variant.fileNames,
+    source,
+    totalLines: variant.totalLines,
+    focusedLines: focused(variant.focusedLines),
+    collapsible: collapseToEmpty ? true : variant.collapsible,
+    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) {
+  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). `extraSource` entries
+    // are `{ source, totalLines, focusedLines }` objects now, so hoist `.source`.
+    if (source || extraSource) {
+      const hasts = {};
+      if (source && mainFile) {
+        hasts[mainFile] = source;
+      }
+      if (extraSource) {
+        for (const [fName, file] of Object.entries(extraSource)) {
+          hasts[fName] = file.source;
+        }
+      }
+      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 = {};
+          const evMainFile = variant.fileNames?.[0];
+          if (evMainFile && variant.source) {
+            hasts[evMainFile] = variant.source;
+          }
+          if (variant.extraSource) {
+            for (const [fName, file] of Object.entries(variant.extraSource)) {
+              hasts[fName] = file.source;
+            }
+          }
+          if (Object.keys(hasts).length > 0) {
+            setFallbackHasts(name, hasts);
+          }
+        }
+      }
+    }
+  }, [setFallbackHasts, variantName, mainFile, source, extraSource, propsExtraVariants, ctxExtraVariants]);
+  if (!props) {
+    return {};
+  }
+  const collapseToEmpty = props.collapseToEmpty === true;
+
+  // Resolve extraVariants: prefer props, fall back to context
+  const allExtraVariants = propsExtraVariants || ctxExtraVariants;
+  let resolvedExtraVariants;
+  if (allExtraVariants) {
+    resolvedExtraVariants = {};
+    for (const [name, variant] of Object.entries(allExtraVariants)) {
+      resolvedExtraVariants[name] = convertVariantSource(variant, collapseToEmpty);
+    }
+  }
+  const converted = convertVariantSource(props, collapseToEmpty);
+  const {
+    totalLines,
+    focusedLines,
+    collapsible
+  } = converted;
+  // Build the displayed file's `<code>` once, here, so every ContentLoading paints
+  // identical attributes to `<Pre>` (created via `React.createElement` to keep this a
+  // `.ts` logic hook). `null` when there's nothing to paint. Extra files/variants
+  // carry their own `source` + counts on `extraSource` / `extraVariants` for the
+  // consumer to render the same way.
+  const code = converted.source ? /*#__PURE__*/React.createElement('code', {
+    className: props.language ? `language-${props.language}` : undefined,
+    'data-filename': props.fileNames?.[0],
+    'data-collapsible': collapsible ? '' : undefined,
+    'data-total-lines': totalLines,
+    'data-focused-lines': focusedLines
+  }, hastToJsx(converted.source)) : null;
+  return {
+    ...converted,
+    extraVariants: resolvedExtraVariants,
+    collapsed: props.fallbackCollapsed,
+    code
+  };
+}