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

package/pipeline/loadIsomorphicCodeVariant/decodeHastSource.mjs

@@ -0,0 +1,92 @@
+import { decompressHast } from "../hastUtils/index.mjs";
+import { fallbackToText, redistributeRootFallback } from "../../CodeHighlighter/fallbackFormat.mjs";
+/**
+ * WeakMap cache of decoded `HastRoot` keyed on the raw source payload
+ * object. Variant source payloads are stable references across renders
+ * (they live on the precomputed manifest / context), so identity-keying
+ * is safe and lets us amortize the decompress + `JSON.parse` cost across
+ * every consumer that reads the same variant during a render cycle.
+ */
+const decodedHastCache = new WeakMap();
+
+/**
+ * WeakMap cache of the DEFLATE dictionary text derived from a variant's
+ * root `fallback`. `fallbackToText` walks the whole fallback tree, so we
+ * memoize it per fallback array — the same array is reused for the variant's
+ * compressed source decode and any later re-decodes.
+ */
+const fallbackTextCache = new WeakMap();
+function getFallbackText(fallback) {
+  let text = fallbackTextCache.get(fallback);
+  if (text === undefined) {
+    text = fallbackToText(fallback);
+    fallbackTextCache.set(fallback, text);
+  }
+  return text;
+}
+function isHastRoot(value) {
+  return 'type' in value && value.type === 'root';
+}
+
+/**
+ * Resolves a `VariantSource` to a live `HastRoot`, sharing one decode per
+ * source payload across all consumers (`Pre`, `useFileNavigation`,
+ * `sourceLineCounts`, …). Decompresses `hastCompressed`, parses `hastJson`,
+ * and returns live HAST trees unchanged. Returns `null` for string sources
+ * or unrecognized shapes.
+ *
+ * When a variant-level `fallback` is provided, the compressed payload is
+ * decompressed using the fallback text as a DEFLATE dictionary (matching the
+ * encoder), and each `span.frame` of a freshly decoded tree gets its
+ * per-frame `data.fallback` restored via `redistributeRootFallback`. Live
+ * HAST trees are returned untouched — they already carry their per-frame
+ * fallback and are shared, read-only inputs.
+ *
+ * **The returned tree must be treated as read-only.** Multiple consumers
+ * share the same object; mutating it would leak across them. Callers that
+ * need to mutate the HAST (e.g. the enhancer pipeline in
+ * `useSourceEnhancing`) must clone before mutating, and should not use
+ * this cache.
+ */
+export function decodeHastSource(source, fallback) {
+  if (source == null || typeof source === 'string') {
+    return null;
+  }
+  const cached = decodedHastCache.get(source);
+  if (cached) {
+    return cached;
+  }
+  let root;
+  let decoded = false;
+  try {
+    if ('hastJson' in source) {
+      root = JSON.parse(source.hastJson);
+      decoded = true;
+    } else if ('hastCompressed' in source) {
+      const dictionary = fallback ? getFallbackText(fallback) : undefined;
+      root = JSON.parse(decompressHast(source.hastCompressed, dictionary));
+      decoded = true;
+    } else if (isHastRoot(source)) {
+      root = source;
+    } else {
+      return null;
+    }
+  } catch (error) {
+    // The "not a HAST source" cases (string / null / unrecognized shape) already
+    // returned `null` above — so reaching here means a present `hastJson` /
+    // `hastCompressed` payload failed to parse or decompress. That's a real bug
+    // (most often a missing or mismatched `fallback` dictionary for
+    // `hastCompressed`), so throw rather than returning `null`: a swallowed
+    // error here only resurfaces far away as a blank render or a `null.data`
+    // crash, which is what makes it hard to track down.
+    throw new Error(`Failed to decode the source HAST payload${'hastCompressed' in source ? ' — a hastCompressed payload needs a matching fallback dictionary' : ''}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  // Freshly decoded trees are owned by this cache, so it is safe to restore
+  // the per-frame `data.fallback` that was stripped before serialization.
+  // Live HAST inputs are shared and already carry their per-frame fallback.
+  if (decoded && fallback) {
+    redistributeRootFallback(root, fallback);
+  }
+  decodedHastCache.set(source, root);
+  return root;
+}

package/pipeline/loadIsomorphicCodeVariant/decodeSource.d.mts

@@ -0,0 +1,19 @@
+import type { VariantSource } from "../../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
+/**
+ * Decode a `VariantSource` into a form that carries no serialization: a plain
+ * string stays a string, while a serialized `hastCompressed` / `hastJson`
+ * payload (or a live `HastRoot`) resolves to a live `HastRoot`. The
+ * `{ hastJson }` / `{ hastCompressed }` shapes never leak out, so consumers can
+ * read the source as text (`stringOrHastToString`) or inspect / transform the
+ * HAST tree directly without handling a DEFLATE dictionary.
+ *
+ * Decoding reuses the shared `decodeHastSource` cache — so a source already
+ * decoded for rendering is not inflated again — then returns a
+ * `structuredClone` of the tree. The clone matters: `decodeHastSource` hands
+ * back a read-only tree shared with the live render, and the result here is
+ * handed to user code (the `transformVariant` hook), which must be able to
+ * mutate it without corrupting that shared tree. `fallback` is the DEFLATE
+ * dictionary for a `hastCompressed` source.
+ */
+export declare function decodeSource(source: VariantSource, fallback?: FallbackNode[]): VariantSource;

package/pipeline/loadIsomorphicCodeVariant/decodeSource.mjs

@@ -0,0 +1,25 @@
+import { decodeHastSource } from "./decodeHastSource.mjs";
+
+/**
+ * Decode a `VariantSource` into a form that carries no serialization: a plain
+ * string stays a string, while a serialized `hastCompressed` / `hastJson`
+ * payload (or a live `HastRoot`) resolves to a live `HastRoot`. The
+ * `{ hastJson }` / `{ hastCompressed }` shapes never leak out, so consumers can
+ * read the source as text (`stringOrHastToString`) or inspect / transform the
+ * HAST tree directly without handling a DEFLATE dictionary.
+ *
+ * Decoding reuses the shared `decodeHastSource` cache — so a source already
+ * decoded for rendering is not inflated again — then returns a
+ * `structuredClone` of the tree. The clone matters: `decodeHastSource` hands
+ * back a read-only tree shared with the live render, and the result here is
+ * handed to user code (the `transformVariant` hook), which must be able to
+ * mutate it without corrupting that shared tree. `fallback` is the DEFLATE
+ * dictionary for a `hastCompressed` source.
+ */
+export function decodeSource(source, fallback) {
+  if (typeof source === 'string') {
+    return source;
+  }
+  const root = decodeHastSource(source, fallback);
+  return root ? structuredClone(root) : source;
+}

package/pipeline/loadIsomorphicCodeVariant/decodeSourceToText.d.mts

@@ -0,0 +1,17 @@
+import type { VariantSource } from "../../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
+/**
+ * Decode a `VariantSource` to its plain text, reusing the shared
+ * `decodeHastSource` cache so a `hastCompressed` / `hastJson` payload that was
+ * already decoded for rendering is not inflated and parsed a second time.
+ *
+ * String sources are returned unchanged and need no `fallback`. For an encoded
+ * source, `fallback` supplies the DEFLATE dictionary required to decode a
+ * `hastCompressed` payload (the file's compact fallback text); omitting it for
+ * such a payload surfaces a descriptive error from `decodeHastSource` rather
+ * than a cryptic inflate failure.
+ *
+ * `null` / `undefined` sources resolve to an empty string so callers can treat
+ * a missing source the same as an empty file.
+ */
+export declare function decodeSourceToText(source: VariantSource | null | undefined, fallback?: FallbackNode[]): string;

package/pipeline/loadIsomorphicCodeVariant/decodeSourceToText.mjs

@@ -0,0 +1,26 @@
+import { toText } from 'hast-util-to-text';
+import { decodeHastSource } from "./decodeHastSource.mjs";
+
+/**
+ * Decode a `VariantSource` to its plain text, reusing the shared
+ * `decodeHastSource` cache so a `hastCompressed` / `hastJson` payload that was
+ * already decoded for rendering is not inflated and parsed a second time.
+ *
+ * String sources are returned unchanged and need no `fallback`. For an encoded
+ * source, `fallback` supplies the DEFLATE dictionary required to decode a
+ * `hastCompressed` payload (the file's compact fallback text); omitting it for
+ * such a payload surfaces a descriptive error from `decodeHastSource` rather
+ * than a cryptic inflate failure.
+ *
+ * `null` / `undefined` sources resolve to an empty string so callers can treat
+ * a missing source the same as an empty file.
+ */
+export function decodeSourceToText(source, fallback) {
+  if (source == null || typeof source === 'string') {
+    return source ?? '';
+  }
+  const root = decodeHastSource(source, fallback);
+  return root ? toText(root, {
+    whitespace: 'pre'
+  }) : '';
+}

package/pipeline/loadIsomorphicCodeVariant/diffHast.d.mts

@@ -1,3 +1,27 @@
 import type { Nodes } from 'hast';
-import { type ParseSource, type Transforms } from "../../CodeHighlighter/types.mjs";
-export declare function diffHast(source: string, parsedSource: Nodes, filename: string, transforms: Transforms, parseSource: ParseSource): Promise<Record<string, any>>;
+import { type SourceComments, type Transforms } from "../../CodeHighlighter/types.mjs";
+/**
+ * Async-friendly variant of {@link ParseSource}. The build-time diff path
+ * may wrap the synchronous highlighter with enhancers that need to run
+ * asynchronously, so `diffHast` accepts either return shape. `comments`
+ * is the post-transform comment map (1-indexed by line in the transformed
+ * source) when the transform repositions lines; wrappers that drive
+ * enhancers should prefer it over the source's own comment map so the
+ * enhanced frame structure aligns with the patched output.
+ */
+type AsyncParseSource = (source: string, fileName: string, language?: string, comments?: SourceComments) => Nodes | Promise<Nodes>;
+/**
+ * Diffs each transformed variant against `parsedSource` and returns
+ * a `Transforms` map where every entry carries a `delta`.
+ *
+ * NOTE: `parsedSource` is temporarily mutated for the duration of this
+ * call — `dataLn` properties are stripped from line spans before diffing
+ * (so the always-sequential gutter numbering doesn't leak into the
+ * delta) and restored in `finally`. Callers must not read from the tree
+ * concurrently, and must not invoke `diffHast` against the same
+ * `parsedSource` in parallel. Today's only caller (`loadSingleFile`)
+ * runs sequentially per variant, so the constraint is satisfied; if
+ * that ever changes, clone the source array once up front instead.
+ */
+export declare function diffHast(source: string, parsedSource: Nodes, filename: string, transforms: Transforms, parseSource: AsyncParseSource): Promise<Transforms>;
+export {};