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

package/CodeHighlighter/codeToFallbackProps.mjs

@@ -1,57 +1,362 @@
-import { stringOrHastToJsx } from "../pipeline/hastUtils/index.mjs";
-function toExtraSource(variantCode, fileName) {
-  return Object.entries(variantCode.extraFiles || {}).reduce((acc, [name, file]) => {
-    if (name !== fileName && typeof file === 'object' && file?.source) {
-      acc[name] = stringOrHastToJsx(file.source);
-    }
-    return acc;
-  }, {});
+import { hastToFallback } from "./fallbackFormat.mjs";
+import { getLanguageFromExtension } from "../pipeline/loaderUtils/getLanguageFromExtension.mjs";
+import { getVariantFileLineCounts } from "../useCode/sourceLineCounts.mjs";
+
+/** Per-variant → per-file line metadata threaded for the fallback. */
+
+/**
+ * Resolve a `language-{language}` hint for a file from its extension, used to
+ * scope the fallback `<code>` styling the same way the post-load tree is.
+ * Returns `undefined` when the name has no extension or it isn't recognized.
+ */
+function getLanguageFromFileName(fileName) {
+  if (!fileName) {
+    return undefined;
+  }
+  const dotIndex = fileName.lastIndexOf('.');
+  if (dotIndex === -1) {
+    return undefined;
+  }
+  return getLanguageFromExtension(fileName.slice(dotIndex));
 }
-export function codeToFallbackProps(variant, code, fileName, needsAllFiles = false, needsAllVariants = false) {
-  const variantCode = code?.[variant];
-  if (!variantCode || typeof variantCode === 'string') {
-    return {};
+
+/**
+ * Resolve the compact fallback for a file. Prefers the pre-extracted variant
+ * `fallback` (always emitted by the loader as a root fallback) and only derives
+ * one from the source for live/dev trees that never went through the loader.
+ *
+ * A plain-string source (an unparsed code block, e.g. `<CodeHighlighter>{code}`)
+ * is wrapped in a single focus frame so the fallback always has the same frame
+ * structure as the highlighted render — never a bare text node. `hastCompressed`
+ * payloads can't be decoded here (no DEFLATE dictionary), so without a variant
+ * `fallback` they yield `undefined`.
+ */
+function sourceToFallback(source, fallback) {
+  if (fallback) {
+    return fallback;
+  }
+  if (!source) {
+    return undefined;
+  }
+  if (typeof source === 'string') {
+    // Wrap the raw code in a single focus frame so the fallback always carries a
+    // frame, matching the highlighted render (`buildRootFallback` likewise emits
+    // frames with text children) — never a bare text node. The whole source is
+    // the visible window; collapse-to-empty demotes it like any other focus frame.
+    return [['span', 'frame', {
+      dataFrameType: 'focus'
+    }, source]];
   }
+  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;
+}
+
+/**
+ * Derive the compact `source`/`extraSource` fallbacks and the `language` hint
+ * for a single variant. Prefers the pre-extracted per-file fallbacks in
+ * `variantHasts` (server path) and otherwise derives them from the variant's
+ * own `source`/`fallback` (dev path). `language` comes from the variant's
+ * explicit `language` or the main file's extension and is only set when a
+ * `source` is present, mirroring how consumers gate the `language-{language}`
+ * class behind a rendered source.
+ */
+function deriveVariantSources(variantCode, variantHasts, variantLineCounts) {
   const fileNames = [variantCode.fileName, ...Object.keys(variantCode.extraFiles || {})].filter(name => Boolean(name));
+  const mainFile = variantCode.fileName || fileNames[0];
+
+  // Per-file line counts: prefer render-time windowing (`variantLineCounts`), else
+  // the counts the loader stored on the code (`VariantCode` / extra-file `totalLines`
+  // / `focusedLines`). So every file/variant carries its window, not just the main one.
+  const fileCounts = fileName => {
+    const threaded = variantLineCounts?.[fileName];
+    if (threaded) {
+      return threaded;
+    }
+    const file = variantCode.fileName === fileName ? variantCode : variantCode.extraFiles?.[fileName];
+    if (file && typeof file !== 'string' && file.totalLines !== undefined) {
+      return {
+        totalLines: file.totalLines,
+        focusedLines: file.focusedLines ?? file.totalLines,
+        collapsible: file.collapsible === true
+      };
+    }
+    // Last resort: count lines off the source (a plain string with no enhancers ⇒
+    // `focusedLines === totalLines`, matching `<Pre>`'s `getSourceLineCounts`). Guarded
+    // because a `hastCompressed` source can't be decoded without its dictionary (which
+    // the server strips before this runs) — the server passes `variantLineCounts`
+    // instead, so this branch only really fires client-side where the dictionary is on
+    // the code.
+    try {
+      const counts = getVariantFileLineCounts(variantCode, fileName);
+      // `totalLines === 0` means a hast with no `root.data` counts (not a real count).
+      return counts && counts.totalLines > 0 ? counts : undefined;
+    } catch {
+      return undefined;
+    }
+  };
   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);
-    }
-  } 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 => Boolean(fn)),
-            // TODO: use filesOrder if provided
-            source: vCode.source && stringOrHastToJsx(vCode.source),
-            extraSource: extraVariantExtraSource
+  let extraSource;
+  if (variantHasts) {
+    // Pre-extracted fallback data (server path).
+    if (mainFile && variantHasts[mainFile]) {
+      source = variantHasts[mainFile];
+    }
+    const extra = {};
+    for (const [fName, nodes] of Object.entries(variantHasts)) {
+      if (fName !== mainFile) {
+        extra[fName] = {
+          source: nodes,
+          ...fileCounts(fName)
+        };
+      }
+    }
+    if (Object.keys(extra).length > 0) {
+      extraSource = extra;
+    }
+  } else {
+    // No pre-extracted fallback data (e.g. dev mode). Prefer the variant's own
+    // `fallback`, falling back to deriving one from the source directly.
+    source = sourceToFallback(variantCode.source, variantCode.fallback);
+    const extra = {};
+    for (const [fName, fData] of Object.entries(variantCode.extraFiles || {})) {
+      if (typeof fData === 'object' && fData.source) {
+        const fb = sourceToFallback(fData.source, fData.fallback);
+        if (fb) {
+          extra[fName] = {
+            source: fb,
+            ...fileCounts(fName)
           };
         }
-        return acc;
-      }, {});
-      return {
-        fileNames,
-        source,
-        extraSource,
-        extraVariants
-      };
+      }
     }
+    if (Object.keys(extra).length > 0) {
+      extraSource = extra;
+    }
+  }
+  const language = source ? variantCode.language ?? getLanguageFromFileName(mainFile) : undefined;
+  const mainCounts = source && mainFile ? fileCounts(mainFile) : undefined;
+  return {
+    fileNames,
+    source,
+    totalLines: mainCounts?.totalLines,
+    focusedLines: mainCounts?.focusedLines,
+    collapsible: mainCounts?.collapsible,
+    extraSource,
+    language
+  };
+}
+export function codeToFallbackProps(variant, code,
+// `fallbackUsesExtraFiles` / the selected file name are threaded in by both
+// call sites for signature parity, but the per-file gating now happens
+// upstream in `stripFallbackHastsFromCode` (which only hoists the allowed
+// files into `allFallbackHasts`), so the derivation below reads them off the
+// already-gated `allFallbackHasts` rather than re-applying the flags here.
+_fileName, _needsAllFiles = false, needsAllVariants = false, allFallbackHasts, allLineCounts) {
+  const variantCode = code?.[variant];
+  if (!variantCode || typeof variantCode === 'string') {
+    return {};
+  }
+  const {
+    fileNames,
+    source,
+    totalLines,
+    focusedLines,
+    collapsible,
+    extraSource,
+    language
+  } = deriveVariantSources(variantCode, allFallbackHasts?.[variant], allLineCounts?.[variant]);
+  if (needsAllVariants) {
+    const extraVariants = Object.entries(code || {}).reduce((acc, [name, vCode]) => {
+      if (name !== variant && vCode && typeof vCode !== 'string') {
+        const {
+          fileNames: evFileNames,
+          source: evSource,
+          totalLines: evTotalLines,
+          focusedLines: evFocusedLines,
+          collapsible: evCollapsible,
+          extraSource: evExtraSource,
+          language: evLanguage
+        } = deriveVariantSources(vCode, allFallbackHasts?.[name], allLineCounts?.[name]);
+        acc[name] = {
+          fileNames: evFileNames,
+          ...(evSource ? {
+            source: evSource
+          } : undefined),
+          ...(evTotalLines !== undefined ? {
+            totalLines: evTotalLines
+          } : undefined),
+          ...(evFocusedLines !== undefined ? {
+            focusedLines: evFocusedLines
+          } : undefined),
+          ...(evCollapsible !== undefined ? {
+            collapsible: evCollapsible
+          } : undefined),
+          ...(evLanguage ? {
+            language: evLanguage
+          } : undefined),
+          ...(evExtraSource ? {
+            extraSource: evExtraSource
+          } : undefined)
+        };
+      }
+      return acc;
+    }, {});
     return {
       fileNames,
-      source,
-      extraSource
+      ...(source ? {
+        source
+      } : undefined),
+      ...(totalLines !== undefined ? {
+        totalLines
+      } : undefined),
+      ...(focusedLines !== undefined ? {
+        focusedLines
+      } : undefined),
+      ...(collapsible !== undefined ? {
+        collapsible
+      } : undefined),
+      ...(language ? {
+        language
+      } : undefined),
+      ...(extraSource ? {
+        extraSource
+      } : undefined),
+      extraVariants
     };
   }
   return {
     fileNames,
-    source
+    ...(source ? {
+      source
+    } : undefined),
+    ...(totalLines !== undefined ? {
+      totalLines
+    } : undefined),
+    ...(focusedLines !== undefined ? {
+      focusedLines
+    } : undefined),
+    ...(collapsible !== undefined ? {
+      collapsible
+    } : undefined),
+    ...(language ? {
+      language
+    } : undefined),
+    ...(extraSource ? {
+      extraSource
+    } : undefined)
+  };
+}
+
+/**
+ * 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 function deriveFallbacksFromCode(code, variantName) {
+  const variant = code?.[variantName];
+  if (!variant || typeof variant === 'string') {
+    return undefined;
+  }
+  const fallbacks = {};
+  if (variant.fallback && variant.fileName) {
+    fallbacks[variant.fileName] = variant.fallback;
+  }
+  if (variant.extraFiles) {
+    for (const [fileName, fileData] of Object.entries(variant.extraFiles)) {
+      if (typeof fileData === 'object' && fileData.fallback) {
+        fallbacks[fileName] = fileData.fallback;
+      }
+    }
+  }
+  return Object.keys(fallbacks).length > 0 ? 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 function stripFallbackHastsFromCode(code, variantName, fallbackUsesExtraFiles, fallbackUsesAllVariants) {
+  if (!code) {
+    return {
+      strippedCode: {},
+      allFallbackHasts: {}
+    };
+  }
+  const allFallbackHasts = {};
+  const strippedCode = {};
+  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 = {};
+    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
   };
 }

package/CodeHighlighter/createClientProps.d.mts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { Code, CodeHighlighterBaseProps, CodeHighlighterClientProps } from "./types.mjs";
+import type { CompressedFallback } from "./fallbackFormat.mjs";
+export interface CreateClientPropsOptions<T extends {}> extends CodeHighlighterBaseProps<T> {
+  code?: Code;
+  fallback?: React.ReactNode;
+  skipFallback?: boolean;
+  processedGlobalsCode?: Array<Code>;
+  residualFallbacks?: CompressedFallback;
+}
+/**
+ * Assemble the props for the `'use client'` `CodeHighlighterClient` from the
+ * server/isomorphic props: rewrite the top-level URL to its hosted form, pre-render
+ * the `Content` element (functions can't cross the server-client boundary), and
+ * forward the loading `fallback` and compressed `residualFallbacks`.
+ */
+export declare function createClientProps<T extends {}>(props: CreateClientPropsOptions<T>): CodeHighlighterClientProps;

package/CodeHighlighter/createClientProps.mjs

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import { replaceUrlPrefix } from "../pipeline/loaderUtils/applyUrlPrefix.mjs";
+import { resolveFallbackCritical } from "./resolveFallbackCritical.mjs";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Assemble the props for the `'use client'` `CodeHighlighterClient` from the
+ * server/isomorphic props: rewrite the top-level URL to its hosted form, pre-render
+ * the `Content` element (functions can't cross the server-client boundary), and
+ * forward the loading `fallback` and compressed `residualFallbacks`.
+ */
+export function createClientProps(props) {
+  const highlightAfter = props.highlightAfter === 'stream' ? 'init' : props.highlightAfter;
+  const enhanceAfter = props.enhanceAfter === 'stream' ? 'init' : props.enhanceAfter;
+
+  // Resolve the staging `fallbackCritical` on every variant of both carriers before
+  // they cross to the client: under `highlightAt: 'init'` (not `collapseToEmpty`)
+  // promote it over the plain `fallback` so the first paint is highlighted with no
+  // decompression, and always strip it so it never reaches `Content`/`ContentLoading`
+  // or bloats the payload. `code` and `precompute` are forwarded separately (the
+  // client seeds its `code` state from `precompute`), so both must be resolved.
+  const collapseToEmpty = props.collapseToEmpty ?? props.contentProps?.collapseToEmpty ?? false;
+  const code = resolveFallbackCritical(props.code, highlightAfter, collapseToEmpty);
+  const precompute = resolveFallbackCritical(props.precompute, highlightAfter, collapseToEmpty);
+
+  // Rewrite the top-level URL before it leaves the server. The client never
+  // receives `urlPrefix` (and shouldn't deal with `file://` URLs), so any
+  // local URL must be translated to its hosted form here. Variant-level URLs
+  // inside `code`/`precompute` are already rewritten upstream (by
+  // `loadIsomorphicCodeVariant` on the server, or by the demo factory for precomputed
+  // input).
+  const url = props.urlPrefix && props.url ? replaceUrlPrefix(props.url, props.urlPrefix) : props.url;
+  const contentProps = {
+    ...props.contentProps,
+    code: code || precompute,
+    components: props.components,
+    name: props.name,
+    slug: props.slug,
+    url,
+    variantType: props.variantType,
+    // Thread the render-time display flags into the content channel so both
+    // `useCode`/`<Pre>` and the loading fallback honor them. A top-level prop
+    // wins over one already present in `contentProps`.
+    ...(props.collapseToEmpty !== undefined ? {
+      collapseToEmpty: props.collapseToEmpty
+    } : undefined),
+    ...(props.initialExpanded !== undefined ? {
+      initialExpanded: props.initialExpanded
+    } : undefined)
+  };
+  return {
+    url,
+    code,
+    precompute,
+    components: props.components,
+    variants: props.variants,
+    variant: props.variant,
+    fileName: props.fileName,
+    initialVariant: props.initialVariant,
+    defaultVariant: props.defaultVariant,
+    highlightAfter: highlightAfter || 'idle',
+    enhanceAfter: enhanceAfter || 'idle',
+    skipFallback: props.skipFallback,
+    controlled: props.controlled,
+    editActivation: props.editActivation,
+    residualFallbacks: props.residualFallbacks,
+    name: props.name,
+    slug: props.slug,
+    // Use processedGlobalsCode if available, otherwise fall back to raw globalsCode
+    globalsCode: props.processedGlobalsCode || props.globalsCode,
+    // Note: it is important that we render components before passing them to the client
+    // otherwise we will get an error because functions can't be serialized
+    // On the client, in order to send data to these components, we have to set context
+    fallback: props.fallback,
+    children: /*#__PURE__*/_jsx(props.Content, {
+      ...contentProps
+    })
+  };
+}

package/CodeHighlighter/errors.d.mts

@@ -106,6 +106,12 @@ export declare class ErrorCodeHighlighterClientMissingUrlForVariants extends Err
 export declare class ErrorCodeHighlighterClientMissingData extends ErrorCodeHighlighterClientValidation {
   constructor();
 }
+export declare class ErrorCodeHighlighterClientMissingFallbackHoist extends ErrorCodeHighlighterClientValidation {
+  constructor();
+}
+export declare class ErrorCodeHighlighterClientDynamicContentRequiresFallback extends ErrorCodeHighlighterClientValidation {
+  constructor();
+}
 export declare class ErrorCodeHighlighterServerLoadVariantFailure extends ErrorCodeHighlighterServerLoader {
   constructor(url: string, error: Error);
 }

package/CodeHighlighter/errors.mjs

@@ -219,6 +219,16 @@ export class ErrorCodeHighlighterClientMissingData extends ErrorCodeHighlighterC
     super(`Missing data - CodeHighlighterClient requires either \`variants\`, \`components\`, or \`code\` to be provided.`);
   }
 }
+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.`);
+  }
+}
+export class ErrorCodeHighlighterClientDynamicContentRequiresFallback extends ErrorCodeHighlighterClientValidation {
+  constructor() {
+    super(`Dynamic content requires a ContentLoading - The Content component loads asynchronously ` + `(e.g. via \`LazyContent\`), but no \`ContentLoading\` was provided to show while it loads, ` + `so the slot would flash empty. Provide a \`ContentLoading\` component, or render the content synchronously.`);
+  }
+}
 
 // === CONSOLE ERROR CLASSES ===
 

package/CodeHighlighter/fallbackCompression.d.mts

@@ -0,0 +1,96 @@
+import { type CompressedFallback } from "./fallbackFormat.mjs";
+import type { Code, Fallbacks } from "./types.mjs";
+/**
+ * The residual fallbacks a `ContentLoading` component never renders, grouped
+ * `variant → fileName → FallbackNode[]`. They exist only as the DEFLATE
+ * dictionary for decompressing `hastCompressed`, so they ride across the
+ * boundary as a single compressed blob rather than inline plain text.
+ */
+export type ResidualFallbacks = Record<string, Fallbacks>;
+/**
+ * Residual blobs whose JSON is below this many bytes are left uncompressed —
+ * the DEFLATE + base64 framing would only grow such a small payload.
+ */
+export declare const FALLBACK_COMPRESSION_MIN_BYTES = 128;
+/**
+ * Build the preset-dictionary text for the residual blob from the *rendered*
+ * fallbacks (the subset `ContentLoading` paints, already on the client as plain
+ * text). Priming the residual with this text lets DEFLATE backreference the
+ * rendered file — most valuable for a near-duplicate sibling like a TypeScript
+ * variant of a rendered JavaScript file.
+ *
+ * Deterministic across server and client: variants and files are visited in
+ * sorted key order so both sides build byte-identical dictionaries (a mismatch
+ * would otherwise fail the embedded checksum on decode).
+ */
+export declare function residualDictionaryText(rendered: ResidualFallbacks): string;
+/**
+ * Compress the residual fallbacks into a single self-describing blob. A single
+ * DEFLATE stream deduplicates text shared across the residual files and
+ * variants — and against the rendered subset too when `dictionaryText` is
+ * supplied (see `residualDictionaryText`).
+ *
+ * Returns `undefined` when there is nothing worth compressing (no residual, or
+ * a residual below the byte threshold), signalling the caller to keep the plain
+ * fallbacks inline.
+ */
+export declare function compressResidualFallbacks(residual: ResidualFallbacks, dictionaryText?: string): CompressedFallback | undefined;
+/**
+ * Reverse {@link compressResidualFallbacks}. `dictionaryText` must match what
+ * was used to compress; the embedded checksum throws on a mismatch rather than
+ * yielding a corrupt dictionary.
+ */
+export declare function decompressResidualFallbacks(blob: CompressedFallback, dictionaryText?: string): ResidualFallbacks;
+/**
+ * Pull every `fallback` off a (post-strip) `Code` into a `ResidualFallbacks`
+ * map, returning a `Code` with those fallbacks removed. After
+ * `stripFallbackHastsFromCode` has hoisted the rendered subset, every fallback
+ * still on `Code` is residual — so this needs no scope flags.
+ *
+ * Pure: the input is left untouched; only the variants that lose a fallback are
+ * shallow-cloned.
+ */
+export declare function extractResidualFallbacks(code: Code): {
+  wireCode: Code;
+  residual: ResidualFallbacks;
+};
+/**
+ * Scatter a decompressed `ResidualFallbacks` map back onto `Code`, restoring
+ * each `fallback` to the variant or extra file it came from — the inverse of
+ * {@link extractResidualFallbacks}. Reconstructs exactly the in-memory layout a
+ * non-consolidated payload would have had, so downstream consumers are unaware
+ * the residual ever travelled compressed.
+ *
+ * `preserveExisting` keeps any `fallback` already on the variant/extra file
+ * instead of overwriting it. The hoisted-fallback scatter passes `true`: the
+ * hoist is an *initial-paint* dictionary that, for an un-highlighted load, is a
+ * raw-string fallback whose text keeps a trailing newline that `buildRootFallback`
+ * drops — so it's the WRONG DEFLATE dictionary for a fully-loaded `hastCompressed`
+ * source, which already carries its own source-paired (structured) `fallback`.
+ * Overwriting that with the hoist makes `decodeHastSource` throw a dictionary
+ * mismatch. The hoist is only the dictionary when the variant's own was stripped,
+ * so apply it only where one isn't already present. The residual-blob scatter
+ * keeps the default (`false`): it always writes onto server-stripped, fallback-less
+ * variants, so there is nothing to preserve.
+ *
+ * Pure: only the variants that regain a fallback are shallow-cloned.
+ */
+export declare function scatterResidualFallbacks(code: Code, residual: ResidualFallbacks, preserveExisting?: boolean): Code;
+/**
+ * Reduce every fallback in a rendered-subset map to its collapsed window (see
+ * `collapsedVisibleFallback`). Used by `fallbackCollapsed` to hand
+ * `ContentLoading` only the on-screen lines while the full fallbacks ride along
+ * in the residual blob.
+ *
+ * `collapsesToEmpty(variantName, fileName)` reports the `oversizedFocus: 'hide'`
+ * collapse-to-nothing case (the source's `focusedLines === 0`): such files get
+ * an empty collapsed window so the loading UI matches the hydrated render
+ * instead of briefly painting the first frame.
+ */
+export declare function collapseRenderedFallbacks(rendered: ResidualFallbacks, collapsesToEmpty?: (variantName: string, fileName: string) => boolean): ResidualFallbacks;
+/**
+ * Deep-merge two residual maps (`variant → fileName → fallback`), with `b`
+ * winning on conflicts. Used to fold the rendered files' full fallbacks into
+ * the residual when `fallbackCollapsed` defers them.
+ */
+export declare function mergeResidualFallbacks(first: ResidualFallbacks, second: ResidualFallbacks): ResidualFallbacks;