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

package/CodeHighlighter/fallbackCompression.mjs

@@ -0,0 +1,253 @@
+import { compressHast, decompressHast } from "../pipeline/hastUtils/index.mjs";
+import { collapsedVisibleFallback, fallbackToText } from "./fallbackFormat.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.
+ */
+
+/**
+ * Residual blobs whose JSON is below this many bytes are left uncompressed —
+ * the DEFLATE + base64 framing would only grow such a small payload.
+ */
+export 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 function residualDictionaryText(rendered) {
+  let text = '';
+  for (const variantName of Object.keys(rendered).sort()) {
+    const files = rendered[variantName];
+    for (const fileName of Object.keys(files).sort()) {
+      text += fallbackToText(files[fileName]);
+    }
+  }
+  return text;
+}
+
+/**
+ * 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 function compressResidualFallbacks(residual, dictionaryText) {
+  if (Object.keys(residual).length === 0) {
+    return undefined;
+  }
+  const json = JSON.stringify(residual);
+  // Measure the encoded UTF-8 byte length (isomorphic via TextEncoder), not
+  // `json.length` — which counts UTF-16 code units and undercounts multibyte
+  // payloads, so a residual that genuinely exceeds the byte threshold would
+  // otherwise be wrongly left inline. For ASCII the two are identical.
+  if (new TextEncoder().encode(json).length < FALLBACK_COMPRESSION_MIN_BYTES) {
+    return undefined;
+  }
+  return {
+    fallbackCompressed: compressHast(json, dictionaryText)
+  };
+}
+
+/**
+ * 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 function decompressResidualFallbacks(blob, dictionaryText) {
+  return JSON.parse(decompressHast(blob.fallbackCompressed, dictionaryText));
+}
+
+/**
+ * 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 function extractResidualFallbacks(code) {
+  const wireCode = {};
+  const residual = {};
+  for (const [variantName, variant] of Object.entries(code)) {
+    if (!variant || typeof variant === 'string') {
+      wireCode[variantName] = variant;
+      continue;
+    }
+    const files = {};
+    let nextVariant = variant;
+
+    // Main file — only extractable when its fileName can key the map.
+    if (variant.fallback && variant.fileName) {
+      files[variant.fileName] = variant.fallback;
+      const {
+        fallback: omitted,
+        ...rest
+      } = variant;
+      nextVariant = rest;
+    }
+
+    // Extra files.
+    if (variant.extraFiles) {
+      let nextExtraFiles;
+      for (const [fileName, fileData] of Object.entries(variant.extraFiles)) {
+        if (typeof fileData === 'string' || !fileData.fallback) {
+          continue;
+        }
+        files[fileName] = fileData.fallback;
+        if (!nextExtraFiles) {
+          nextExtraFiles = {
+            ...variant.extraFiles
+          };
+        }
+        const {
+          fallback: omitted,
+          ...rest
+        } = fileData;
+        nextExtraFiles[fileName] = rest;
+      }
+      if (nextExtraFiles) {
+        nextVariant = {
+          ...nextVariant,
+          extraFiles: nextExtraFiles
+        };
+      }
+    }
+    wireCode[variantName] = nextVariant;
+    if (Object.keys(files).length > 0) {
+      residual[variantName] = files;
+    }
+  }
+  return {
+    wireCode,
+    residual
+  };
+}
+
+/**
+ * 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 function scatterResidualFallbacks(code, residual, preserveExisting = false) {
+  const restored = {};
+  for (const [variantName, variant] of Object.entries(code)) {
+    const files = residual[variantName];
+    if (!variant || typeof variant === 'string' || !files) {
+      restored[variantName] = variant;
+      continue;
+    }
+    let nextVariant = variant;
+    let nextExtraFiles;
+    for (const [fileName, fallback] of Object.entries(files)) {
+      if (fileName === variant.fileName) {
+        if (preserveExisting && nextVariant.fallback) {
+          continue;
+        }
+        nextVariant = {
+          ...nextVariant,
+          fallback
+        };
+      } else {
+        const fileData = variant.extraFiles?.[fileName];
+        if (fileData && typeof fileData === 'object') {
+          if (preserveExisting && fileData.fallback) {
+            continue;
+          }
+          if (!nextExtraFiles) {
+            nextExtraFiles = {
+              ...variant.extraFiles
+            };
+          }
+          nextExtraFiles[fileName] = {
+            ...fileData,
+            fallback
+          };
+        }
+      }
+    }
+    if (nextExtraFiles) {
+      nextVariant = {
+        ...nextVariant,
+        extraFiles: nextExtraFiles
+      };
+    }
+    restored[variantName] = nextVariant;
+  }
+  return restored;
+}
+
+/**
+ * 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 function collapseRenderedFallbacks(rendered, collapsesToEmpty) {
+  const collapsed = {};
+  for (const [variantName, files] of Object.entries(rendered)) {
+    const collapsedFiles = {};
+    for (const [fileName, fallback] of Object.entries(files)) {
+      collapsedFiles[fileName] = collapsedVisibleFallback(fallback, collapsesToEmpty?.(variantName, fileName) ?? false);
+    }
+    collapsed[variantName] = collapsedFiles;
+  }
+  return collapsed;
+}
+
+/**
+ * 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 function mergeResidualFallbacks(first, second) {
+  const merged = {};
+  for (const [variantName, files] of Object.entries(first)) {
+    merged[variantName] = {
+      ...files
+    };
+  }
+  for (const [variantName, files] of Object.entries(second)) {
+    merged[variantName] = {
+      ...merged[variantName],
+      ...files
+    };
+  }
+  return merged;
+}

package/CodeHighlighter/fallbackFormat.d.mts

@@ -0,0 +1,137 @@
+import type { Root as HastRoot } 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;
+/**
+ * A residual fallback that has been DEFLATE-compressed on its own. Mirrors the
+ * `{ hastCompressed }` shape of `VariantSource`.
+ *
+ * Used for the parts of a variant's fallback that the `ContentLoading`
+ * component never renders (extra files when the loading UI shows a single file,
+ * extra variants when it shows a single variant). Those residual fallbacks
+ * exist only as the DEFLATE dictionary for decompressing `hastCompressed`, so
+ * shipping them as plain `FallbackNode[]` text would be dead weight in the
+ * initial payload. They are compressed standalone — no preset text dictionary,
+ * so the blob is self-contained — and decompressed back to `FallbackNode[]`
+ * (via `decompressFallback`) only when the full content swaps in.
+ */
+export type CompressedFallback = {
+  fallbackCompressed: string;
+};
+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 declare function hastToFallback(root: HastRoot): FallbackNode[];
+/**
+ * Convert the compact `FallbackNode[]` format back into a HAST root.
+ */
+export declare function fallbackToHast(nodes: FallbackNode[]): HastRoot;
+/**
+ * Extract the text content from compact `FallbackNode[]` without
+ * converting back to HAST. Used to build DEFLATE dictionaries.
+ */
+export declare function fallbackToText(nodes: FallbackNode[]): string;
+/**
+ * Builds the variant-level root fallback from a final (post-enhancer) HAST
+ * root. Each `span.frame` becomes a compact frame element whose single text
+ * child is the frame's precomputed plain text (`frame.data.fallback`), so the
+ * result is directly renderable as the pre-hydration code block **and** can be
+ * redistributed back onto the decoded HAST's frames (see
+ * `redistributeRootFallback`).
+ *
+ * The frame's `data-lined` attribute is dropped (line spans don't exist in the
+ * fallback) while other frame attributes (e.g. `data-frame-type`) are kept so
+ * the fallback's layout matches the highlighted render. Non-frame top-level
+ * nodes (e.g. whitespace text between frames) are preserved in place.
+ */
+export declare function buildRootFallback(root: HastRoot): FallbackNode[];
+/**
+ * Whether a compact `fallback` already carries highlighting — i.e. at least one frame
+ * keeps nested token spans (array children) instead of flat plain text. True exactly for
+ * the promoted {@link promoteCriticalFallback} form; a plain {@link buildRootFallback} has
+ * a string child on every frame. `<Pre>` uses this to defer the decompressing decode ONLY
+ * when the first paint is already highlighted, so it never flashes plain → highlighted.
+ */
+export declare function fallbackIsHighlighted(fallback: FallbackNode[]): boolean;
+/**
+ * The **sparse** highlighted-visible fallback: a map from frame index to the
+ * highlighted `FallbackNode` for ONLY the frames visible on the initial collapsed
+ * render (`visibleFrames`). Off-screen frames are omitted — they flatten to exactly
+ * {@link buildRootFallback}'s plain output, so storing them would just duplicate
+ * `fallback` in the precompute. {@link promoteCriticalFallback} splices these back
+ * over the plain fallback for `highlightAt: 'init'` (paint highlighted on the first
+ * render, zero decompression). Frame indices count `span.frame` children only,
+ * matching `getInitialVisibleFrames`.
+ *
+ * The decoded `root` is shared/read-only; this only reads its frames (the synthetic
+ * visible frame reuses the frame's `children` array without mutating it, and
+ * `data-lined` is dropped via destructuring, not deletion).
+ */
+export declare function buildCriticalFallback(root: HastRoot, visibleFrames: {
+  [key: number]: boolean;
+}): {
+  [frameIndex: number]: FallbackNode;
+};
+/**
+ * Splice a sparse {@link buildCriticalFallback} diff back onto a plain `fallback`,
+ * replacing each visible frame (matched by index in document order) with its
+ * highlighted node. The result is the full highlighted-visible fallback; its text is
+ * byte-identical to `fallback` (the highlight spans only wrap the same characters), so
+ * it stays a valid DEFLATE dictionary — asserted by tests. Returns a new array; the
+ * input is not mutated.
+ */
+export declare function promoteCriticalFallback(fallback: FallbackNode[], critical: {
+  [frameIndex: number]: FallbackNode;
+}): FallbackNode[];
+/**
+ * Redistributes a root fallback (built by `buildRootFallback`) back onto the
+ * frames of a decoded HAST root, setting each frame's `data.fallback` to the
+ * corresponding fallback frame's text nodes (as HAST, not the compact form).
+ *
+ * Frames align 1:1 by position because the root fallback and the decoded HAST
+ * are both derived from the same final tree. Non-frame fallback entries (e.g.
+ * inter-frame whitespace) advance the cursor without being assigned. Mutates
+ * `root` in place and returns it.
+ */
+export declare function redistributeRootFallback(root: HastRoot, fallback: FallbackNode[]): HastRoot;
+/**
+ * Reduce a root fallback to the frames visible while the code block is
+ * collapsed — the contiguous focused window (`padding-top`, `highlighted` /
+ * `focus`, `padding-bottom`). Inter-frame nodes inside that window are kept so
+ * the slice renders with the same spacing as the full fallback.
+ *
+ * Matches the runtime rule in `Pre.tsx`: when a block has no emphasis frames
+ * (the whole source is the focused window) the first frame stands in. Returns
+ * the input unchanged when it has no frames at all.
+ *
+ * When `collapsesToEmpty` is `true` the source records `focusedLines === 0`
+ * (the `oversizedFocus: 'hide'` collapse-to-nothing case): the collapsed window
+ * is intentionally empty, so the first-frame fallback is skipped and an empty
+ * array is returned. Mirrors the runtime rule in `Pre.tsx` /
+ * `getInitialVisibleSourceLines`.
+ *
+ * Used by `fallbackCollapsed` to paint only the on-screen lines while the
+ * file's full fallback rides along compressed (see the prop-compression
+ * pattern's "Splitting the Fallback by Visibility").
+ */
+export declare function collapsedVisibleFallback(fallback: FallbackNode[], collapsesToEmpty?: boolean): FallbackNode[];