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

package/pipeline/hastUtils/hastUtils.mjs

@@ -2,6 +2,18 @@ import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
 import { toText } from 'hast-util-to-text';
 import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
 import { decompressHast } from "./hastCompression.mjs";
+import { fallbackToText } from "./fallbackFormat.mjs";
+
+/**
+ * Resolve the DEFLATE dictionary text for a `hastCompressed` payload from a
+ * compact `fallback`. The loader compresses each file with its own fallback
+ * text as the dictionary (see `loadIsomorphicCodeVariant`), so the same
+ * fallback must be supplied here to decode it. Returns `undefined` when no
+ * fallback is given (payloads compressed without a dictionary).
+ */
+function fallbackDictionary(fallback) {
+  return fallback ? fallbackToText(fallback) : undefined;
+}
 export function hastToJsx(hast, components) {
   return toJsxRuntime(hast, {
     Fragment,
@@ -10,19 +22,19 @@ export function hastToJsx(hast, components) {
     components
   });
 }
-export function hastOrJsonToJsx(hastOrJson, components) {
+export function hastOrJsonToJsx(hastOrJson, components, fallback) {
   let hast;
   if ('hastJson' in hastOrJson) {
     try {
       hast = JSON.parse(hastOrJson.hastJson);
     } catch (error) {
-      throw new Error(`Failed to parse hastJson: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastJson: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else if ('hastCompressed' in hastOrJson) {
     try {
-      hast = JSON.parse(decompressHast(hastOrJson.hastCompressed));
+      hast = JSON.parse(decompressHast(hastOrJson.hastCompressed, fallbackDictionary(fallback)));
     } catch (error) {
-      throw new Error(`Failed to parse hastCompressed: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastCompressed: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else {
     hast = hastOrJson;
@@ -34,7 +46,7 @@ export function hastOrJsonToJsx(hastOrJson, components) {
     components
   });
 }
-export function stringOrHastToString(source) {
+export function stringOrHastToString(source, fallback) {
   if (typeof source === 'string') {
     return source;
   }
@@ -43,13 +55,13 @@ export function stringOrHastToString(source) {
     try {
       hast = JSON.parse(source.hastJson);
     } catch (error) {
-      throw new Error(`Failed to parse hastJson: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastJson: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else if ('hastCompressed' in source) {
     try {
-      hast = JSON.parse(decompressHast(source.hastCompressed));
+      hast = JSON.parse(decompressHast(source.hastCompressed, fallbackDictionary(fallback)));
     } catch (error) {
-      throw new Error(`Failed to parse hastCompressed: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastCompressed: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else {
     hast = source;
@@ -58,7 +70,7 @@ export function stringOrHastToString(source) {
     whitespace: 'pre'
   });
 }
-export function stringOrHastToJsx(source, highlighted, components) {
+export function stringOrHastToJsx(source, highlighted, components, fallback) {
   if (typeof source === 'string') {
     return source;
   }
@@ -67,13 +79,13 @@ export function stringOrHastToJsx(source, highlighted, components) {
     try {
       hast = JSON.parse(source.hastJson);
     } catch (error) {
-      throw new Error(`Failed to parse hastJson: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastJson: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else if ('hastCompressed' in source) {
     try {
-      hast = JSON.parse(decompressHast(source.hastCompressed));
+      hast = JSON.parse(decompressHast(source.hastCompressed, fallbackDictionary(fallback)));
     } catch (error) {
-      throw new Error(`Failed to parse hastCompressed: ${JSON.stringify(error)}`);
+      throw new Error(`Failed to parse hastCompressed: ${error instanceof Error ? error.message : String(error)}`);
     }
   } else {
     hast = source;

package/pipeline/hastUtils/index.d.mts

@@ -1,4 +1,5 @@
 export * from "./hastCompression.mjs";
 export * from "./hastUtils.mjs";
 export { getHastTextContent, getShallowTextContent } from "./getHastTextContent.mjs";
-export { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";
+export { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";
+export { frameFallbackFromSpans } from "./frameFallbackFromSpans.mjs";

package/pipeline/hastUtils/index.mjs

@@ -1,4 +1,5 @@
 export * from "./hastCompression.mjs";
 export * from "./hastUtils.mjs";
 export { getHastTextContent, getShallowTextContent } from "./getHastTextContent.mjs";
-export { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";
+export { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";
+export { frameFallbackFromSpans } from "./frameFallbackFromSpans.mjs";

package/pipeline/hastUtils/stripHighlightingSpans.d.mts

@@ -1,11 +1,15 @@
 import type { Root as HastRoot } from 'hast';
 /**
- * Strip all non-frame `<span>` elements from a HAST tree while preserving
+ * Strip all non-structural `<span>` elements from a HAST tree while preserving
  * semantic structure and text content. Produces a "links-only" version of the
  * tree suitable as a lightweight server-rendered fallback for deferred highlighting.
  *
- * - All `<span>` elements except frame spans: removed, children promoted
+ * - All `<span>` elements except frame and collapse spans: removed, children promoted
  * - Frame `<span>` elements (`frame`): preserved with their data attributes
+ *   (except `data-lined`, which is redundant once line spans are gone)
+ * - Collapse `<span>` elements (`collapse`): preserved with their `data-lines`
+ *   attribute so CSS can size the placeholder, keeping the fallback render's
+ *   height in sync with the fully-highlighted render
  * - `<a>` elements: preserved, children recursively processed
  * - text nodes: preserved, adjacent text nodes merged
  * - other elements (pre, code, etc.): preserved, children recursively processed

package/pipeline/hastUtils/stripHighlightingSpans.mjs

@@ -1,10 +1,16 @@
+import { hasClassName, isFrameSpan } from "../parseSource/isFrameSpan.mjs";
+
 /**
- * Strip all non-frame `<span>` elements from a HAST tree while preserving
+ * Strip all non-structural `<span>` elements from a HAST tree while preserving
  * semantic structure and text content. Produces a "links-only" version of the
  * tree suitable as a lightweight server-rendered fallback for deferred highlighting.
  *
- * - All `<span>` elements except frame spans: removed, children promoted
+ * - All `<span>` elements except frame and collapse spans: removed, children promoted
  * - Frame `<span>` elements (`frame`): preserved with their data attributes
+ *   (except `data-lined`, which is redundant once line spans are gone)
+ * - Collapse `<span>` elements (`collapse`): preserved with their `data-lines`
+ *   attribute so CSS can size the placeholder, keeping the fallback render's
+ *   height in sync with the fully-highlighted render
  * - `<a>` elements: preserved, children recursively processed
  * - text nodes: preserved, adjacent text nodes merged
  * - other elements (pre, code, etc.): preserved, children recursively processed
@@ -17,9 +23,8 @@ export function stripHighlightingSpans(root) {
     children: processChildren(root.children)
   };
 }
-function isFrameSpan(element) {
-  const className = element.properties?.className;
-  return className === 'frame' || Array.isArray(className) && className.includes('frame');
+function isCollapseSpan(element) {
+  return hasClassName(element, 'collapse');
 }
 function processChildren(children) {
   const flat = children.flatMap(node => {
@@ -27,24 +32,31 @@ function processChildren(children) {
       return [node];
     }
     const element = node;
-    if (element.tagName === 'span' && !isFrameSpan(element)) {
+    if (element.tagName === 'span' && !isFrameSpan(element) && !isCollapseSpan(element)) {
       // Unwrap highlighting spans: replace with recursively-processed children
       return processChildren(element.children);
     }
+    if (isCollapseSpan(element)) {
+      // Collapse placeholders carry one empty `<span/>` per collapsed
+      // line as a structural payload (consumer CSS sizes them by
+      // intrinsic layout). The children are inert: no recursion needed,
+      // and reusing the same element reference keeps downstream JSX
+      // caches (WeakMap-keyed) stable across re-renders.
+      return [element];
+    }
     // Keep semantic spans, links, and other elements — process their children
     const processed = {
       ...element,
       children: processChildren(element.children)
     };
-    // Strip data-lined and data-as-string from frame spans since line spans
-    // are removed and the raw source text is redundant in the fallback HAST.
+    // Strip data-lined from frame spans since line spans are removed in the
+    // fallback HAST.
     if (isFrameSpan(element) && processed.properties) {
       const {
         dataLined,
-        dataAsString,
         ...rest
       } = processed.properties;
-      if (dataLined !== undefined || dataAsString !== undefined) {
+      if (dataLined !== undefined) {
         processed.properties = rest;
       }
     }

package/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.mjs

@@ -297,13 +297,16 @@ function reportPreview(context, sourceCode, {
       if (options.wrapReturn && returnStatement) {
         const hasParens = hasReturnParens(sourceCode, returnStatement);
         if (hasParens) {
-          // Already `return (...)` — just insert the comment inside
+          // Already `return (...)` — just insert the comment inside. The focus
+          // sits one level deeper than the function body, so `@padding 2` keeps
+          // the `return (` line and the function signature/closing brace visible
+          // as context when collapsed.
           const lineStartOffset = sourceCode.getIndexFromLoc({
             line: firstNode.loc.start.line,
             column: 0
           });
           if (isSingleLine) {
-            return fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus\n`);
+            return fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus @padding 2\n`);
           }
           const lastLineStartOffset = sourceCode.getIndexFromLoc({
             line: lastNode.loc.end.line,
@@ -311,7 +314,7 @@ function reportPreview(context, sourceCode, {
           });
           const lastLine = sourceCode.lines[lastNode.loc.end.line - 1];
           const lastIndentation = lastLine.match(/^\s*/)?.[0] ?? '';
-          return [fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus-start\n`), fixer.insertTextAfterRange([lastLineStartOffset, lastLineStartOffset + lastLine.length], `\n${lastIndentation}// @focus-end`)];
+          return [fixer.insertTextBeforeRange([lineStartOffset, lineStartOffset], `${indentation}// @focus-start @padding 2\n`), fixer.insertTextAfterRange([lastLineStartOffset, lastLineStartOffset + lastLine.length], `\n${lastIndentation}// @focus-end`)];
         }
 
         // No parens — wrap `return <X>` into `return (\n  // comment\n  <X>\n)`
@@ -319,9 +322,9 @@ function reportPreview(context, sourceCode, {
         const returnIndentation = sourceCode.lines[returnStatement.loc.start.line - 1].match(/^\s*/)?.[0] ?? '';
         const innerIndentation = `${returnIndentation}  `;
         if (isSingleLine) {
-          return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`)];
+          return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${returnIndentation})`)];
         }
-        return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${returnIndentation})`)];
+        return [fixer.replaceTextRange([returnKeywordEnd, firstNode.range[0]], ` (\n${innerIndentation}// @focus-start @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${returnIndentation})`)];
       }
 
       // Non-wrapper: wrapReturn with implicit-return arrow — wrap expression in parens with comment.
@@ -332,9 +335,9 @@ function reportPreview(context, sourceCode, {
           const arrowIndentation = sourceCode.lines[arrowToken.loc.start.line - 1].match(/^\s*/)?.[0] ?? '';
           const innerIndentation = `${arrowIndentation}  `;
           if (isSingleLine) {
-            return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${arrowIndentation})`)];
+            return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${arrowIndentation})`)];
           }
-          return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus-start\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${arrowIndentation})`)];
+          return [fixer.replaceTextRange([arrowToken.range[1], firstNode.range[0]], ` (\n${innerIndentation}// @focus-start @padding 2\n${innerIndentation}`), fixer.insertTextAfterRange(lastNode.range, `\n${innerIndentation}// @focus-end\n${arrowIndentation})`)];
         }
       }
 

package/pipeline/loadIsomorphicCodeVariant/applyCodeTransform.d.mts

@@ -1,19 +1,37 @@
-import type { VariantSource, Transforms } from "../../CodeHighlighter/types.mjs";
+import type { VariantSource, Transforms, SourceComments } from "../../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
 /**
- * Applies a specific transform to a variant source and returns the transformed source
- * @param source - The original variant source (string, HastNodes, or hastJson object)
- * @param transforms - Object containing all available transforms
- * @param transformKey - The key of the specific transform to apply
- * @returns The transformed variant source in the same format as the input
+ * Applies a specific transform to a variant source and returns the transformed
+ * source plus a remapped copy of the supplied `comments` map. See
+ * {@link applyCodeTransformWithCommentsCore} for the full contract; this wrapper
+ * binds the built-in `decodeHastSource`.
+ *
  * @throws Error if the transform key doesn't exist or patching fails
  */
-export declare function applyCodeTransform(source: VariantSource, transforms: Transforms, transformKey: string): VariantSource;
+export declare function applyCodeTransformWithComments(source: VariantSource, transforms: Transforms, transformKey: string, comments?: SourceComments, fallback?: FallbackNode[]): {
+  source: VariantSource;
+  comments?: SourceComments;
+};
 /**
- * Applies multiple transforms to a variant source in sequence
- * @param source - The original variant source
- * @param transforms - Object containing all available transforms
- * @param transformKeys - Array of transform keys to apply in order
- * @returns The transformed variant source in the same format as the input
+ * Applies multiple transforms to a variant source in sequence, shifting
+ * comments through each hop. See {@link applyCodeTransformsWithCommentsCore};
+ * this wrapper binds the built-in `decodeHastSource`.
+ *
  * @throws Error if any transform key doesn't exist or patching fails
  */
-export declare function applyCodeTransforms(source: VariantSource, transforms: Transforms, transformKeys: string[]): VariantSource;
+export declare function applyCodeTransformsWithComments(source: VariantSource, transforms: Transforms, transformKeys: string[], comments?: SourceComments, fallback?: FallbackNode[]): {
+  source: VariantSource;
+  comments?: SourceComments;
+};
+/**
+ * Convenience wrapper around {@link applyCodeTransformWithComments} for
+ * callers that don't need the shifted comments map. Returns the transformed
+ * `VariantSource` directly.
+ */
+export declare function applyCodeTransform(source: VariantSource, transforms: Transforms, transformKey: string, fallback?: FallbackNode[]): VariantSource;
+/**
+ * Convenience wrapper around {@link applyCodeTransformsWithComments} for
+ * callers that don't need the shifted comments map. Returns the transformed
+ * `VariantSource` directly.
+ */
+export declare function applyCodeTransforms(source: VariantSource, transforms: Transforms, transformKeys: string[], fallback?: FallbackNode[]): VariantSource;

package/pipeline/loadIsomorphicCodeVariant/applyCodeTransform.mjs

@@ -1,65 +1,60 @@
-import { patch, clone } from 'jsondiffpatch';
+// Standalone (server/build) entry to the transform-application core. Binds the
+// concrete `decodeHastSource` so callers that don't inject one — the
+// `loadIsomorphicCodeVariant` pipeline, tests, and anything importing
+// `@mui/internal-docs-infra/pipeline/loadIsomorphicCodeVariant` — keep the
+// original API. The client-side `useCode/TransformEngine` instead imports the
+// core (`./applyCodeTransformWithComments`) directly and injects the shell's
+// already-loaded decoder, so the engine chunk never statically pulls
+// `decodeHastSource` (and its `hastDecompress` dependency).
+
+import { decodeHastSource } from "./decodeHastSource.mjs";
+import { frameFallbackFromSpans } from "../hastUtils/index.mjs";
+import { applyCodeTransformWithComments as applyCodeTransformWithCommentsCore, applyCodeTransformsWithComments as applyCodeTransformsWithCommentsCore } from "./applyCodeTransformWithComments.mjs";
+
+// The built-in hast helpers, bound once for callers that don't inject their own
+// (the `loadIsomorphicCodeVariant` server/build pipeline, tests, etc.).
+const builtinDeps = {
+  decode: decodeHastSource,
+  frameFallbackFromSpans
+};
+
 /**
- * Applies a specific transform to a variant source and returns the transformed source
- * @param source - The original variant source (string, HastNodes, or hastJson object)
- * @param transforms - Object containing all available transforms
- * @param transformKey - The key of the specific transform to apply
- * @returns The transformed variant source in the same format as the input
+ * Applies a specific transform to a variant source and returns the transformed
+ * source plus a remapped copy of the supplied `comments` map. See
+ * {@link applyCodeTransformWithCommentsCore} for the full contract; this wrapper
+ * binds the built-in `decodeHastSource`.
+ *
  * @throws Error if the transform key doesn't exist or patching fails
  */
-export function applyCodeTransform(source, transforms, transformKey) {
-  const transform = transforms[transformKey];
-  if (!transform) {
-    throw new Error(`Transform "${transformKey}" not found in transforms`);
-  }
-
-  // Determine the format of the source and apply the appropriate transform strategy
-  if (typeof source === 'string') {
-    // For string sources, deltas are typically line-array based (from transformSource)
-    const sourceLines = source.split('\n');
-    const patched = patch(sourceLines, transform.delta);
-    if (!Array.isArray(patched)) {
-      throw new Error(`Patch for transform "${transformKey}" did not return an array`);
-    }
-    return patched.join('\n');
-  }
-
-  // For Hast node sources, deltas are typically node-based (from diffHast)
-  let sourceRoot;
-  const isHastJson = 'hastJson' in source;
-  if (isHastJson) {
-    sourceRoot = JSON.parse(source.hastJson);
-  } else {
-    sourceRoot = source;
-  }
+export function applyCodeTransformWithComments(source, transforms, transformKey, comments, fallback) {
+  return applyCodeTransformWithCommentsCore(source, transforms, transformKey, builtinDeps, comments, fallback);
+}
 
-  // Apply the node-based delta
-  const patchedNodes = patch(clone(sourceRoot), transform.delta);
-  if (!patchedNodes) {
-    throw new Error(`Patch for transform "${transformKey}" returned null/undefined`);
-  }
+/**
+ * Applies multiple transforms to a variant source in sequence, shifting
+ * comments through each hop. See {@link applyCodeTransformsWithCommentsCore};
+ * this wrapper binds the built-in `decodeHastSource`.
+ *
+ * @throws Error if any transform key doesn't exist or patching fails
+ */
+export function applyCodeTransformsWithComments(source, transforms, transformKeys, comments, fallback) {
+  return applyCodeTransformsWithCommentsCore(source, transforms, transformKeys, builtinDeps, comments, fallback);
+}
 
-  // Return in the same format as the input
-  if (isHastJson) {
-    return {
-      hastJson: JSON.stringify(patchedNodes)
-    };
-  }
-  return patchedNodes;
+/**
+ * Convenience wrapper around {@link applyCodeTransformWithComments} for
+ * callers that don't need the shifted comments map. Returns the transformed
+ * `VariantSource` directly.
+ */
+export function applyCodeTransform(source, transforms, transformKey, fallback) {
+  return applyCodeTransformWithComments(source, transforms, transformKey, undefined, fallback).source;
 }
 
 /**
- * Applies multiple transforms to a variant source in sequence
- * @param source - The original variant source
- * @param transforms - Object containing all available transforms
- * @param transformKeys - Array of transform keys to apply in order
- * @returns The transformed variant source in the same format as the input
- * @throws Error if any transform key doesn't exist or patching fails
+ * Convenience wrapper around {@link applyCodeTransformsWithComments} for
+ * callers that don't need the shifted comments map. Returns the transformed
+ * `VariantSource` directly.
  */
-export function applyCodeTransforms(source, transforms, transformKeys) {
-  let currentSource = source;
-  for (const transformKey of transformKeys) {
-    currentSource = applyCodeTransform(currentSource, transforms, transformKey);
-  }
-  return currentSource;
+export function applyCodeTransforms(source, transforms, transformKeys, fallback) {
+  return applyCodeTransformsWithComments(source, transforms, transformKeys, undefined, fallback).source;
 }

package/pipeline/loadIsomorphicCodeVariant/applyCodeTransformWithComments.d.mts

@@ -0,0 +1,78 @@
+import type { ElementContent } from 'hast';
+import type { HastRoot, VariantSource, Transforms, SourceComments } from "../../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../../CodeHighlighter/fallbackFormat.mjs";
+/**
+ * Decodes a `VariantSource` to a live `HastRoot` (or `null` for string /
+ * unrecognized shapes).
+ */
+export type DecodeHastSource = (source: VariantSource | null | undefined, fallback?: FallbackNode[]) => HastRoot | null;
+/** Rebuilds a frame's lazy fallback from its post-transform spans. */
+export type FrameFallbackFromSpans = (spans: ElementContent[]) => ElementContent[];
+/**
+ * Hast helpers the transform core needs but must NOT import statically, so the
+ * client `useCode/TransformEngine` chunk doesn't pull `decodeHastSource` /
+ * `frameFallbackFromSpans` (and their `hastDecompress` dependency). The
+ * always-loaded `useCode` shell already has both and injects them; the
+ * standalone `applyCodeTransform` wrapper binds the built-ins for server/build
+ * callers.
+ */
+export interface TransformRuntimeDeps {
+  decode: DecodeHastSource;
+  frameFallbackFromSpans: FrameFallbackFromSpans;
+}
+/**
+ * Applies a specific transform to a variant source and returns the transformed source
+ * along with a remapped copy of the supplied `comments` map (when any) shifted to
+ * line up with the renumbered `dataLn` values in the transformed tree.
+ *
+ * **Return shape, by input shape:**
+ * - `string` input → `string` output.
+ * - HAST-backed input (`HastRoot`, `{ hastJson }`, or `{ hastCompressed }`)
+ *   that actually applies a delta → live `HastRoot` output, regardless of the
+ *   input wire shape. The serialized wire shapes are *not* re-emitted: every
+ *   downstream reader in this package funnels through `decodeHastSource`,
+ *   which accepts a live root directly, so re-stringifying / re-compressing
+ *   here would just be undone by the next consumer (and would defeat the
+ *   shared decode cache, which is keyed on payload identity). Callers
+ *   outside this package that need a serialized payload must re-encode
+ *   the returned root themselves.
+ * - Rename-only entries (`hasDelta: false`) and unknown-transform passthrough
+ *   return the original `source` object untouched (same shape and identity).
+ *
+ * @param source - The original variant source (string, `HastRoot`,
+ *   `{ hastJson }`, or `{ hastCompressed }`)
+ * @param transforms - Object containing all available transforms
+ * @param transformKey - The key of the specific transform to apply
+ * @param deps - Hast helpers (`decode`, `frameFallbackFromSpans`) injected so
+ *   this module never statically imports them; see {@link TransformRuntimeDeps}.
+ * @param comments - Optional 1-indexed comment map keyed by the source's original
+ *   line numbers. Returned shifted so each entry now sits on the line its
+ *   original source line occupies in the transformed tree; entries whose
+ *   source line was wiped by the transform are dropped.
+ * @returns `{ source, comments }` where `source` is the transformed variant
+ *   source (see "Return shape" above) and `comments` is the remapped map
+ *   (or `undefined` when no comments were passed).
+ * @throws Error if the transform key doesn't exist or patching fails
+ */
+export declare function applyCodeTransformWithComments(source: VariantSource, transforms: Transforms, transformKey: string, deps: TransformRuntimeDeps, comments?: SourceComments, fallback?: FallbackNode[]): {
+  source: VariantSource;
+  comments?: SourceComments;
+};
+/**
+ * Applies multiple transforms to a variant source in sequence. Comments are
+ * shifted by each transform in turn so the returned map lines up with the
+ * fully-transformed source.
+ *
+ * @param source - The original variant source
+ * @param transforms - Object containing all available transforms
+ * @param transformKeys - Array of transform keys to apply in order
+ * @param deps - Hast helpers (`decode`, `frameFallbackFromSpans`) injected so
+ *   this module never statically imports them; see {@link TransformRuntimeDeps}.
+ * @param comments - Optional 1-indexed comment map for the original source
+ * @returns `{ source, comments }` after applying every transform in order
+ * @throws Error if any transform key doesn't exist or patching fails
+ */
+export declare function applyCodeTransformsWithComments(source: VariantSource, transforms: Transforms, transformKeys: string[], deps: TransformRuntimeDeps, comments?: SourceComments, fallback?: FallbackNode[]): {
+  source: VariantSource;
+  comments?: SourceComments;
+};