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

package/CodeHighlighter/CodeHighlighterContext.d.mts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { type Code, type ControlledCode, type HastRoot } from "./types.mjs";
+import { type Code, type ControlledCode, type Fallbacks, type HastRoot } from "./types.mjs";
 import { type Selection } from "../CodeControllerContext/index.mjs";
 /**
  * One cached pre-parsed file. Stored per-fileName: each new write replaces
@@ -21,6 +21,62 @@ export interface CodeHighlighterContextType {
   availableTransforms?: string[];
   url?: string;
   deferHighlight?: boolean;
+  /**
+  /**
+   * Compact fallback data for the active variant, keyed by fileName.
+   * Used by `Pre` to both render the fallback and derive text dictionaries
+   * for decompressing `hastCompressed` payloads.
+   */
+  fallbacks?: Fallbacks;
+  /**
+   * Render-side readiness gate. `true` once the highlight trigger
+   * (`init` / `hydration` / `idle` / `visible`) has fired *and* the
+   * sync `parseCode` pass has resolved, so consumers like `<Pre>`
+   * can render the published `code` as highlighted HAST. While
+   * `false` they should render the un-highlighted fallback (plain
+   * text) — the published `code` may still contain precomputed HAST
+   * left over from SSR, so without this gate non-`init` demos would
+   * render highlighted spans on the first paint and defeat the
+   * deferred-highlighting trigger.
+   *
+   * Distinct from `deferHighlight`, which is the narrower
+   * "highlight pass is actively in flight" signal consumed by
+   * barrier gates (e.g. `useTransformManagement.awaitHighlight`)
+   * that must not block when no work is queued.
+   */
+  highlightReady?: boolean;
+  /**
+   * Echo of the `highlightAfter` prop on the surrounding
+   * `CodeHighlighter` / `CodeHighlighterClient`. Consumers such as
+   * `useCode` use this to skip transient highlighting-suppression
+   * gates that only matter when highlighting is asynchronous — in
+   * `'init'` mode the precomputed HAST already carries the highlight
+   * spans, so those gates would just cause a visible flash of
+   * unhighlighted content during variant swaps.
+   */
+  highlightAfter?: 'init' | 'hydration' | 'idle';
+  /**
+   * Echo of the `editActivation` prop on the surrounding `CodeHighlighter` /
+   * `CodeHighlighterClient`. `useCode` reads it from here and threads it down to
+   * `useEditable` (which defers the `contentEditable` attach when
+   * `'interaction'`), so the editing-activation strategy can be configured at
+   * the `CodeHighlighter` / demo level rather than inside the content subtree.
+   */
+  editActivation?: 'eager' | 'interaction';
+  /**
+   * Callback `useCode` threads down to `useEditable`'s `onActivate`, fired once
+   * when the block first engages for editing. `CodeHighlighterClient` supplies it
+   * to flip its per-block `activated` state (warming the live-editing engine,
+   * grammars, and worker) and to notify the `CodeControllerContext`.
+   */
+  onEditingActivated?: () => void;
+  /**
+   * Re-runs the full variant loader on the client and swaps in fresh data,
+   * keeping the current highlighted output visible until the new tree lands
+   * (stale-while-revalidate). Invalidates the pre-parsed HAST cache. A no-op for
+   * a block with no `url` to re-fetch from. Surfaced through `useCode`/`useDemo`.
+   */
+  refresh?: () => void;
   /**
    * Per-file pre-parsed HAST cache. Populated by `useSourceEditing` when the
    * editable supplies a worker-parsed result alongside a source change, and

package/CodeHighlighter/CodeHighlighterFallbackContext.d.mts

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

package/CodeHighlighter/CodeHighlighterFallbackContext.mjs

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

package/CodeHighlighter/CodeInitialSourceLoader.d.mts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import type { CodeHighlighterChunkContentProps } from "./CodeHighlighterChunk.mjs";
+/**
+ * The chunk's **server initial loader**: load just the initial source (a quick
+ * fallback paint) via `loadCodeFallback`, prepare the loading fallback + compressed
+ * residual from it, then **re-enter the chunk** with the initial in hand
+ * (`skipInitialLoad`, so it routes to the full server loader or the client - never
+ * back here). Dynamically imported by `CodeHighlighterChunk`.
+ */
+export default function CodeInitialSourceLoader(props: CodeHighlighterChunkContentProps): Promise<React.ReactElement>;

package/CodeHighlighter/CodeInitialSourceLoader.mjs

@@ -0,0 +1,108 @@
+import * as React from 'react';
+import { CodeHighlighterChunk } from "./CodeHighlighterChunk.mjs";
+import { buildCodeHighlighterChunkProps } from "./buildCodeHighlighterChunkProps.mjs";
+import { prepareInitialSource } from "./prepareInitialSource.mjs";
+// Statically imported because this whole module is dynamically imported by
+// `CodeHighlighterChunk` (`() => import('./CodeInitialSourceLoader')`) only when
+// the render decision routes to the initial loader - so `loadCodeFallback` already
+// lives in this lazy chunk and never reaches the precomputed-content path.
+import { loadCodeFallback } from "../pipeline/loadIsomorphicCodeVariant/loadCodeFallback.mjs";
+import * as Errors from "./errors.mjs";
+
+/**
+ * The chunk's **server initial loader**: load just the initial source (a quick
+ * fallback paint) via `loadCodeFallback`, prepare the loading fallback + compressed
+ * residual from it, then **re-enter the chunk** with the initial in hand
+ * (`skipInitialLoad`, so it routes to the full server loader or the client - never
+ * back here). Dynamically imported by `CodeHighlighterChunk`.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export default async function CodeInitialSourceLoader(props) {
+  const {
+    data,
+    loading,
+    ...userProps
+  } = props;
+  const {
+    url,
+    initialVariant,
+    highlightAfter,
+    ContentLoading
+  } = userProps;
+  if (!url) {
+    throw new Errors.ErrorCodeHighlighterServerMissingUrl();
+  }
+  if (!initialVariant) {
+    throw new Errors.ErrorCodeHighlighterServerMissingVariant('initial');
+  }
+  let output = 'hastCompressed';
+  if (userProps.deferParsing === 'json') {
+    output = 'hastJson';
+  } else if (userProps.deferParsing === 'none') {
+    output = 'hast';
+  }
+  const {
+    code,
+    initialFilename,
+    initialSource,
+    initialExtraFiles,
+    processedGlobalsCode
+  } = await loadCodeFallback(url, initialVariant, data ?? userProps.code, {
+    shouldHighlight: highlightAfter === 'init',
+    fallbackUsesExtraFiles: userProps.fallbackUsesExtraFiles,
+    fallbackUsesAllVariants: userProps.fallbackUsesAllVariants,
+    sourceParser: userProps.sourceParser,
+    loadSource: userProps.loadSource,
+    loadVariantMeta: userProps.loadVariantMeta,
+    loadCodeMeta: userProps.loadCodeMeta,
+    sourceEnhancers: userProps.sourceEnhancers,
+    initialFilename: userProps.fileName,
+    variants: userProps.variants,
+    globalsCode: userProps.globalsCode,
+    output,
+    urlPrefix: userProps.urlPrefix
+  });
+
+  // Prepare the loading fallback + compressed residual from the loaded initial.
+  const {
+    fallback,
+    residualFallbacks,
+    codeForClient
+  } = prepareInitialSource({
+    ...userProps,
+    code,
+    initialVariant,
+    initialFilename,
+    initialSource,
+    initialExtraFiles,
+    ContentLoading: ContentLoading
+  });
+
+  // Re-enter the chunk with the initial in hand. `skipInitialLoad` prevents routing
+  // back here; the recomputed decision loads the full content on the server (when
+  // loader functions exist) or hands off to the client.
+  const {
+    controlled,
+    isInitial,
+    forceClient
+  } = buildCodeHighlighterChunkProps({
+    ...userProps,
+    code: codeForClient
+  });
+  return /*#__PURE__*/_jsx(CodeHighlighterChunk, {
+    preloaded: codeForClient,
+    controlled: controlled,
+    isInitial: isInitial,
+    forceClient: forceClient,
+    skipInitialLoad: true,
+    awaitServerLoad: highlightAfter !== 'stream',
+    userProps: {
+      ...userProps,
+      code: codeForClient,
+      fallback,
+      residualFallbacks,
+      processedGlobalsCode,
+      initialVariant
+    }
+  });
+}

package/CodeHighlighter/CodeSourceLoader.d.mts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import type { CodeHighlighterChunkContentProps } from "./CodeHighlighterChunk.mjs";
+/**
+ * The chunk's full **server loader**: load every variant (highlighting them via the
+ * heavy `loadIsomorphicCodeVariant` pipeline), then render the `'use client'`
+ * `CodeHighlighterClient` with the loaded `Code`. Dynamically imported by
+ * `CodeHighlighterChunk`, so it (and the pipeline) only reach the bundle when the
+ * decision actually routes here. The prepared loading `fallback`/`residualFallbacks`
+ * ride through the user props.
+ */
+export default function CodeSourceLoader(props: CodeHighlighterChunkContentProps): Promise<React.ReactElement>;

package/CodeHighlighter/CodeSourceLoader.mjs

@@ -0,0 +1,128 @@
+import * as React from 'react';
+import { createClientProps } from "./createClientProps.mjs";
+import { CodeHighlighterClient } from "./CodeHighlighterClient.mjs";
+// `loadIsomorphicCodeVariant` is the heavy load/parse/transform pipeline. It is
+// imported statically here because this whole module is dynamically imported by
+// `CodeHighlighterChunk` (`() => import('./CodeSourceLoader')`) only when the
+// render decision routes to the server loader - so it already lives in this lazy
+// chunk and never reaches the path that renders precomputed content.
+import { loadIsomorphicCodeVariant } from "../pipeline/loadIsomorphicCodeVariant/loadIsomorphicCodeVariant.mjs";
+import * as Errors from "./errors.mjs";
+
+/**
+ * The chunk's full **server loader**: load every variant (highlighting them via the
+ * heavy `loadIsomorphicCodeVariant` pipeline), then render the `'use client'`
+ * `CodeHighlighterClient` with the loaded `Code`. Dynamically imported by
+ * `CodeHighlighterChunk`, so it (and the pipeline) only reach the bundle when the
+ * decision actually routes here. The prepared loading `fallback`/`residualFallbacks`
+ * ride through the user props.
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export default async function CodeSourceLoader(props) {
+  const {
+    data,
+    loading,
+    ...userProps
+  } = props;
+
+  // Start with the loaded code from the chunk's data (precompute/wire code), or
+  // load it via `loadCodeMeta` when nothing was provided.
+  let loadedCode = data ?? userProps.code ?? userProps.precompute;
+  if (!loadedCode) {
+    if (!userProps.loadCodeMeta) {
+      throw new Errors.ErrorCodeHighlighterServerMissingLoadCodeMeta();
+    }
+    if (!userProps.url) {
+      throw new Errors.ErrorCodeHighlighterServerMissingUrlForLoadCodeMeta();
+    }
+    try {
+      loadedCode = await userProps.loadCodeMeta(userProps.url);
+    } catch (error) {
+      throw new Errors.ErrorCodeHighlighterServerLoadCodeFailure(userProps.url, error);
+    }
+  }
+
+  // TODO: if props.variant is provided, we should only load that variant
+
+  // Process globalsCode: use already processed version if available, otherwise
+  // convert string URLs to Code objects.
+  let processedGlobalsCode = userProps.processedGlobalsCode;
+  if (!processedGlobalsCode && userProps.globalsCode && userProps.globalsCode.length > 0) {
+    const hasStringUrls = userProps.globalsCode.some(item => typeof item === 'string');
+    if (hasStringUrls && !userProps.loadCodeMeta) {
+      throw new Errors.ErrorCodeHighlighterServerMissingLoadCodeMetaForGlobals();
+    }
+
+    // Load all string URLs in parallel, keep Code objects as-is
+    const globalsPromises = userProps.globalsCode.map(async globalItem => {
+      if (typeof globalItem === 'string') {
+        try {
+          return await userProps.loadCodeMeta(globalItem);
+        } catch (error) {
+          throw new Errors.ErrorCodeHighlighterServerLoadGlobalsFailure(globalItem, error);
+        }
+      }
+      return globalItem;
+    });
+    processedGlobalsCode = await Promise.all(globalsPromises);
+  }
+  const variantNames = Object.keys(userProps.components || loadedCode || {});
+  const variantCodes = await Promise.all(variantNames.map(variantName => {
+    const variantCode = loadedCode[variantName];
+    const variantUrl = typeof variantCode === 'object' && variantCode?.url ? variantCode.url : userProps.url;
+
+    // Convert processedGlobalsCode to VariantCode | string for this specific variant
+    let resolvedGlobalsCode;
+    if (processedGlobalsCode && processedGlobalsCode.length > 0) {
+      resolvedGlobalsCode = [];
+      for (const codeObj of processedGlobalsCode) {
+        const targetVariant = codeObj[variantName];
+        if (targetVariant) {
+          resolvedGlobalsCode.push(targetVariant);
+        }
+      }
+    }
+    let output = 'hastCompressed';
+    if (userProps.deferParsing === 'json') {
+      output = 'hastJson';
+    } else if (userProps.deferParsing === 'none') {
+      output = 'hast';
+    }
+    return loadIsomorphicCodeVariant(variantUrl, variantName, variantCode, {
+      sourceParser: userProps.sourceParser,
+      loadSource: userProps.loadSource,
+      loadVariantMeta: userProps.loadVariantMeta,
+      sourceTransformers: userProps.sourceTransformers,
+      sourceEnhancers: userProps.sourceEnhancers,
+      globalsCode: resolvedGlobalsCode,
+      output,
+      urlPrefix: userProps.urlPrefix
+    }).then(variant => ({
+      name: variantName,
+      variant
+    })).catch(error => ({
+      error
+    }));
+  }));
+  const processedCode = {};
+  const errors = [];
+  for (const item of variantCodes) {
+    if ('error' in item) {
+      console.error(new Errors.ErrorCodeHighlighterServerLoadVariantFailure(userProps.url, item.error));
+      errors.push(item.error);
+    } else {
+      processedCode[item.name] = item.variant.code;
+    }
+  }
+  if (errors.length > 0) {
+    throw new Errors.ErrorCodeHighlighterServerLoadVariantsFailure(userProps.url, errors);
+  }
+  const clientProps = createClientProps({
+    ...userProps,
+    code: processedCode,
+    processedGlobalsCode
+  });
+  return /*#__PURE__*/_jsx(CodeHighlighterClient, {
+    ...clientProps
+  });
+}

package/CodeHighlighter/buildCodeHighlighterChunkProps.d.mts

@@ -0,0 +1,47 @@
+import type { Code, CodeHighlighterProps } from "./types.mjs";
+/**
+ * The render-decision inputs for the chunk that drives `CodeHighlighter`,
+ * computed from its props. These feed the generic chunk decision
+ * (`resolveChunkRender` via `buildChunkRenderInputs`):
+ *
+ * - `preloaded` is the `Code` (build/precomputed input).
+ * - `controlled` forces the `content` mode (render the client directly).
+ * - `isInitial` reports that an initial paint is already in hand.
+ * - `forceClient` opts out of the server `Loader`/`InitialLoader`.
+ */
+export interface CodeHighlighterChunkProps {
+  /** The `Code` passed as the chunk's `preloaded` value. */
+  preloaded?: Code;
+  /**
+   * Every variant is already highlighted (or `CodeHighlighter` is in controlled
+   * editing mode) - render the client content directly, no loading.
+   */
+  controlled: boolean;
+  /**
+   * A partial code with an initial paint already in hand (enough to render the
+   * loading fallback now). Routes to loading the full content behind it, or, with
+   * no server loading, to the client.
+   */
+  isInitial: boolean;
+  /**
+   * No server loading is available for this render (no loading functions, or the
+   * caller forced the client), so the decision routes to a client/content branch.
+   */
+  forceClient: boolean;
+}
+/** The `CodeHighlighter` props this decision reads. */
+type BuildCodeHighlighterChunkPropsInput<T extends {}> = Pick<CodeHighlighterProps<T>, 'code' | 'precompute' | 'components' | 'variants' | 'variant' | 'initialVariant' | 'defaultVariant' | 'controlled' | 'forceClient' | 'highlightAfter' | 'fallbackUsesExtraFiles' | 'fallbackUsesAllVariants' | 'loadCodeMeta' | 'loadVariantMeta' | 'loadSource' | 'sourceParser' | 'sourceTransformers' | 'url' | 'fileName'>;
+/**
+ * Map `CodeHighlighter`'s props onto the generic chunk render-decision inputs.
+ * This replaces the bespoke `renderCodeHighlighter`/`renderWithInitialSource`
+ * branching: the returned values drive `resolveChunkRender`, which picks between
+ * rendering the client directly, loading the full content on the server, fetching
+ * an initial on the server, or letting the client drive - the same five outcomes
+ * `CodeHighlighter` chose by hand.
+ *
+ * Pure and synchronous (mirrors `maybeCodeInitialData`), so the same inputs decide
+ * identically on the server and the client's first render. Expects `code` already
+ * normalized (e.g. a string child folded into a `Default` variant).
+ */
+export declare function buildCodeHighlighterChunkProps<T extends {} = {}>(props: BuildCodeHighlighterChunkPropsInput<T>): CodeHighlighterChunkProps;
+export {};

package/CodeHighlighter/buildCodeHighlighterChunkProps.mjs

@@ -0,0 +1,61 @@
+import { hasAllVariants } from "../pipeline/loadIsomorphicCodeVariant/hasAllCodeVariants.mjs";
+import { maybeCodeInitialData } from "../pipeline/loadIsomorphicCodeVariant/maybeCodeInitialData.mjs";
+
+/**
+ * The render-decision inputs for the chunk that drives `CodeHighlighter`,
+ * computed from its props. These feed the generic chunk decision
+ * (`resolveChunkRender` via `buildChunkRenderInputs`):
+ *
+ * - `preloaded` is the `Code` (build/precomputed input).
+ * - `controlled` forces the `content` mode (render the client directly).
+ * - `isInitial` reports that an initial paint is already in hand.
+ * - `forceClient` opts out of the server `Loader`/`InitialLoader`.
+ */
+
+/** The `CodeHighlighter` props this decision reads. */
+
+/**
+ * Map `CodeHighlighter`'s props onto the generic chunk render-decision inputs.
+ * This replaces the bespoke `renderCodeHighlighter`/`renderWithInitialSource`
+ * branching: the returned values drive `resolveChunkRender`, which picks between
+ * rendering the client directly, loading the full content on the server, fetching
+ * an initial on the server, or letting the client drive - the same five outcomes
+ * `CodeHighlighter` chose by hand.
+ *
+ * Pure and synchronous (mirrors `maybeCodeInitialData`), so the same inputs decide
+ * identically on the server and the client's first render. Expects `code` already
+ * normalized (e.g. a string child folded into a `Default` variant).
+ */
+export function buildCodeHighlighterChunkProps(props) {
+  const code = props.code || props.precompute;
+  const variants = props.variants || Object.keys(props.components || code || {});
+  const initialKey = props.initialVariant || props.variant || props.defaultVariant || variants[0];
+
+  // Every variant already highlighted (or controlled editing) -> render the
+  // client directly with no loading.
+  const allVariantsLoaded = Boolean(code && hasAllVariants(variants, code, true));
+  const controlled = Boolean(props.controlled) || allVariantsLoaded;
+
+  // No loading functions (or the caller forced the client) -> the server cannot
+  // load, so route to a client/content branch.
+  const hasAnyLoaderFunction = Boolean(props.loadCodeMeta || props.loadVariantMeta || props.loadSource || props.sourceParser || props.sourceTransformers);
+  const forceClient = Boolean(props.forceClient) || !hasAnyLoaderFunction;
+
+  // An initial paint is in hand when, short of being fully loaded,
+  // `maybeCodeInitialData` validates enough to render the loading fallback now.
+  // Mirrors the server arguments `CodeHighlighter` passed it (no explicit
+  // `fileName`; highlight required only for `highlightAfter: 'init'`).
+  let isInitial = false;
+  if (!controlled) {
+    const {
+      initialData
+    } = maybeCodeInitialData(variants, initialKey, code, undefined, props.highlightAfter === 'init', props.fallbackUsesExtraFiles, props.fallbackUsesAllVariants);
+    isInitial = Boolean(initialData);
+  }
+  return {
+    preloaded: code,
+    controlled,
+    isInitial,
+    forceClient
+  };
+}

package/CodeHighlighter/buildStringFallback.d.mts

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

package/CodeHighlighter/buildStringFallback.mjs

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

package/CodeHighlighter/codeToFallbackProps.d.mts

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