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

package/pipeline/loadServerTypesMeta/extractJSDocText.mjs

@@ -0,0 +1,60 @@
+/**
+ * Renders a `{@link symbol}` reference into markdown.
+ *
+ * A link is emitted only when `symbol` is documented on the current page (so a
+ * heading with a matching anchor exists). Otherwise the reference renders as a
+ * plain code span - this keeps references to internal helpers, or to symbols
+ * that live on another page, from producing dangling `#anchor` links that fail
+ * the docs link checker.
+ *
+ * When `documentedNames` is omitted every reference is linked (legacy behavior,
+ * used only when no documented-name set is threaded through).
+ */
+function renderJSDocLink(symbol, documentedNames) {
+  if (!documentedNames || documentedNames.has(symbol)) {
+    return `[\`${symbol}\`](#${symbol.toLowerCase()})`;
+  }
+  return `\`${symbol}\``;
+}
+
+/**
+ * Extracts text content from a JSDoc description array.
+ *
+ * typescript-api-extractor returns a description as an array of JSDoc nodes when
+ * the comment contains `{@link}` tags: plain-text nodes carry a `text` property,
+ * while link nodes carry the referenced symbol in `name.escapedText`. Link nodes
+ * are turned into markdown via {@link renderJSDocLink}, gated on `documentedNames`.
+ */
+export function extractJSDocText(nodes, documentedNames) {
+  return nodes.map(node => {
+    if (typeof node === 'object' && node !== null) {
+      // Regular text nodes have a 'text' property with content
+      if ('text' in node) {
+        const text = node.text;
+        if (typeof text === 'string' && text) {
+          return text;
+        }
+      }
+      // JSDocLink nodes (kind 325) have the symbol name in name.escapedText
+      if ('name' in node) {
+        const name = node.name;
+        if (name && typeof name.escapedText === 'string') {
+          return renderJSDocLink(name.escapedText, documentedNames);
+        }
+      }
+    }
+    return '';
+  }).join('');
+}
+
+/**
+ * Checks if an array looks like JSDoc description nodes from typescript-api-extractor.
+ * These have properties like 'pos', 'end', 'kind', 'text' from the TypeScript AST.
+ */
+export function isJSDocNodeArray(value) {
+  if (value.length === 0) {
+    return false;
+  }
+  const first = value[0];
+  return typeof first === 'object' && first !== null && 'pos' in first && 'end' in first && 'kind' in first;
+}

package/pipeline/loadServerTypesMeta/processTypes.mjs

@@ -3,55 +3,18 @@ import { fileURLToPath } from 'url';
 import { parseFromProgram } from 'typescript-api-extractor';
 import ts from 'typescript';
 import { createOptimizedProgram } from "./createOptimizedProgram.mjs";
+import { extractJSDocText, isJSDocNodeArray } from "./extractJSDocText.mjs";
 import { PerformanceTracker } from "./performanceTracking.mjs";
 import { nameMark } from "../loadPrecomputedCodeHighlighter/performanceLogger.mjs";
 
-/**
- * Extracts text content from a JSDoc description array.
- * typescript-api-extractor returns description as an array of JSDoc nodes
- * when the comment contains @link tags.
- */
-function extractJSDocText(nodes) {
-  return nodes.map(node => {
-    if (typeof node === 'object' && node !== null) {
-      // Regular text nodes have a 'text' property with content
-      if ('text' in node) {
-        const text = node.text;
-        if (typeof text === 'string' && text) {
-          return text;
-        }
-      }
-      // JSDocLink nodes (kind 325) have the symbol name in name.escapedText
-      // Convert {@link symbolName} to [`symbolName`](#symbolName) markdown link
-      if ('name' in node) {
-        const name = node.name;
-        if (name && typeof name.escapedText === 'string') {
-          return `[\`${name.escapedText}\`](#${name.escapedText.toLowerCase()})`;
-        }
-      }
-    }
-    return '';
-  }).join('');
-}
-
-/**
- * Checks if an array looks like JSDoc description nodes from typescript-api-extractor.
- * These have properties like 'pos', 'end', 'kind', 'text' from the TypeScript AST.
- */
-function isJSDocNodeArray(value) {
-  if (value.length === 0) {
-    return false;
-  }
-  const first = value[0];
-  return typeof first === 'object' && first !== null && 'pos' in first && 'end' in first && 'kind' in first;
-}
-
 /**
  * Strips functions from objects so they can cross the worker boundary.
  * Structured clone can't handle functions but handles everything else fine.
- * Also normalizes typescript-api-extractor JSDoc description arrays to strings.
+ * Also normalizes typescript-api-extractor JSDoc description arrays to strings,
+ * resolving `{@link}` references against `documentedNames` so only symbols with
+ * a heading on the page become anchor links.
  */
-function stripFunctions(value, visited = new WeakMap()) {
+function stripFunctions(value, documentedNames, visited = new WeakMap()) {
   // Primitives, null, undefined - return as-is
   if (value === null || value === undefined || typeof value !== 'object') {
     return value;
@@ -66,13 +29,13 @@ function stripFunctions(value, visited = new WeakMap()) {
   if (Array.isArray(value)) {
     // Normalize JSDoc description arrays to strings
     if (isJSDocNodeArray(value)) {
-      return extractJSDocText(value);
+      return extractJSDocText(value, documentedNames);
     }
     const result = [];
     visited.set(value, result);
     for (const item of value) {
       if (typeof item !== 'function') {
-        result.push(stripFunctions(item, visited));
+        result.push(stripFunctions(item, documentedNames, visited));
       }
     }
     return result;
@@ -84,12 +47,45 @@ function stripFunctions(value, visited = new WeakMap()) {
   for (const key of Object.keys(value)) {
     const propValue = value[key];
     if (typeof propValue !== 'function') {
-      result[key] = stripFunctions(propValue, visited);
+      result[key] = stripFunctions(propValue, documentedNames, visited);
     }
   }
   return result;
 }
 
+/**
+ * Collects every symbol name documented on this page - all exports and resolved
+ * types across all variants. `{@link}` references are linked only when they hit
+ * this set, since those are the names that get a heading (and thus an anchor).
+ */
+function collectDocumentedNames(variantData) {
+  const names = new Set();
+  const addName = name => {
+    if (!name) {
+      return;
+    }
+    names.add(name);
+    // Namespaced exports (e.g. "Menu.Root") are also referenced by their flat
+    // ("MenuRoot") and leaf ("Root") forms in {@link} comments.
+    if (name.includes('.')) {
+      names.add(name.replaceAll('.', ''));
+      names.add(name.slice(name.lastIndexOf('.') + 1));
+    }
+  };
+  for (const variant of Object.values(variantData)) {
+    for (const node of variant.allTypes) {
+      addName(node.name);
+    }
+    if (variant.typeNameMap) {
+      for (const [flatName, dottedName] of Object.entries(variant.typeNameMap)) {
+        addName(flatName);
+        addName(dottedName);
+      }
+    }
+  }
+  return names;
+}
+
 /**
  * Recursively collects all source file dependencies of a given source file.
  * This walks the import graph starting from the given file and collects all
@@ -391,7 +387,8 @@ export async function processTypes(request) {
     }
 
     // Strip functions so data can cross worker boundary (structured clone can't handle functions)
-    const serializedVariantData = stripFunctions(variantData);
+    const documentedNames = collectDocumentedNames(variantData);
+    const serializedVariantData = stripFunctions(variantData, documentedNames);
     return {
       success: true,
       variantData: serializedVariantData,

package/pipeline/loadServerTypesText/order.mjs

@@ -8,7 +8,7 @@
 
 export const cssVariables = [];
 export const dataAttributes = ['data-checked', 'data-unchecked', 'data-open', 'data-closed', 'data-panel-open', 'data-popup-open', 'data-popup-side', 'data-list-empty', 'data-pressed', 'data-selected', 'data-highlighted', 'data-dragging', 'data-orientation', 'data-disabled', 'data-readonly', 'data-required', 'data-valid', 'data-invalid', 'data-dirty', 'data-touched', 'data-uncentered', 'data-anchor-hidden', '__EVERYTHING_ELSE__', 'data-starting-style', 'data-ending-style'];
-export const props = ['aria-label', 'aria-labelledby', 'name', 'label', 'defaultChecked', 'checked', 'onCheckedChange', 'indeterminate', 'defaultValue', 'value', 'onValueChange', 'onValueCommitted', 'allValues', 'defaultInputValue', 'inputValue', 'onInputValueChange', 'defaultOpen', 'open', 'onOpenChange', 'defaultPressed', 'pressed', 'onPressedChange', 'onPressedCommitted', 'snapPoints', 'defaultSnapPoint', 'snapPoint', 'onSnapPointChange', 'onClick', 'closeOnClick', 'errors', 'hidden', 'hiddenUntilFound', 'autoHighlight', 'keepHighlight', 'highlightItemOnHover', '__EVERYTHING_ELSE__', 'step', 'smallStep', 'largeStep', 'minStepsBetweenValues', 'min', 'max', 'allowWheelScrub', 'format', 'autoFocus', 'container', 'align', 'alignOffset', 'side', 'sideOffset', 'arrowPadding', 'anchor', 'collisionAvoidance', 'collisionBoundary', 'collisionPadding', 'sticky', 'positionMethod', 'trackAnchor', 'trackCursorAxis', 'initialFocus', 'finalFocus', 'match', 'forceShow', 'disabled', 'readOnly', 'required', 'valid', 'invalid', 'openOnHover', 'delay', 'closeDelay', 'timeout', 'disableHoverablePopup', 'loop', 'orientation', 'inputRef', 'validate', 'validationMode', 'validationDebounceTime', 'id', 'children', 'className', 'style', 'keepMounted', 'render'];
+export const props = ['aria-label', 'aria-labelledby', 'name', 'label', 'defaultChecked', 'checked', 'onCheckedChange', 'indeterminate', 'defaultValue', 'value', 'onValueChange', 'onValueCommitted', 'allValues', 'defaultInputValue', 'inputValue', 'onInputValueChange', 'defaultOpen', 'open', 'onOpenChange', 'collapseToEmpty', 'showCollapsedFocus', 'initialExpanded', 'initialCollapsed', 'defaultPressed', 'pressed', 'onPressedChange', 'onPressedCommitted', 'snapPoints', 'defaultSnapPoint', 'snapPoint', 'onSnapPointChange', 'onClick', 'closeOnClick', 'errors', 'hidden', 'hiddenUntilFound', 'autoHighlight', 'keepHighlight', 'highlightItemOnHover', '__EVERYTHING_ELSE__', 'step', 'smallStep', 'largeStep', 'minStepsBetweenValues', 'min', 'max', 'allowWheelScrub', 'format', 'autoFocus', 'container', 'align', 'alignOffset', 'side', 'sideOffset', 'arrowPadding', 'anchor', 'collisionAvoidance', 'collisionBoundary', 'collisionPadding', 'sticky', 'positionMethod', 'trackAnchor', 'trackCursorAxis', 'initialFocus', 'finalFocus', 'match', 'forceShow', 'disabled', 'readOnly', 'required', 'valid', 'invalid', 'openOnHover', 'delay', 'closeDelay', 'timeout', 'disableHoverablePopup', 'loop', 'orientation', 'inputRef', 'validate', 'validationMode', 'validationDebounceTime', 'id', 'children', 'className', 'style', 'keepMounted', 'render'];
 
 // Namespace member parts order (for sorting ComponentName.Part members)
 // These define the order of parts within a component's namespace

package/pipeline/loadServerTypesText/parseTypesMarkdown.mjs

@@ -13,9 +13,11 @@ import { organizeTypesByExport } from "./organizeTypesByExport.mjs";
 
 /**
  * Decode HTML entities commonly found in markdown.
+ * `&` is unescaped LAST to avoid double-unescaping inputs like `<`,
+ * which should decode to `&lt;` rather than `<`.
  */
 function decodeHtmlEntities(text) {
-  return text.replace(/&quot;/g, '"').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&#39;/g, "'").replace(/&apos;/g, "'").replace(/“/g, '"') // Left double quote
+  return text.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&#39;/g, "'").replace(/&apos;/g, "'").replace(/&amp;/g, '&').replace(/“/g, '"') // Left double quote
   .replace(/”/g, '"'); // Right double quote
 }
 

package/pipeline/loaderUtils/index.d.mts

@@ -1,5 +1,4 @@
 export * from "./parseImportsAndComments.mjs";
-export * from "./convertCommentsToOneIndexed.mjs";
 export * from "./resolveModulePath.mjs";
 export * from "./rewriteImports.mjs";
 export * from "./processRelativeImports.mjs";

package/pipeline/loaderUtils/index.mjs

@@ -1,5 +1,4 @@
 export * from "./parseImportsAndComments.mjs";
-export * from "./convertCommentsToOneIndexed.mjs";
 export * from "./resolveModulePath.mjs";
 export * from "./rewriteImports.mjs";
 export * from "./processRelativeImports.mjs";

package/pipeline/loaderUtils/parseImportsAndComments.d.mts

@@ -58,7 +58,11 @@ export interface ImportsAndComments {
   externals: Record<string, ExternalImport>;
   /** The processed code with comments removed (if comment processing was requested) */
   code?: string;
-  /** Map of line numbers to arrays of comment content (if comment processing was requested) */
+  /**
+   * Map of 1-indexed output line numbers (in `code`, after comment removal) to arrays of
+   * comment content (if comment processing was requested). 1-indexed is the canonical
+   * `Code` convention, matching the HAST `dataLn` gutter the enhancers read.
+   */
   comments?: Record<number, string[]>;
 }
 /**

package/pipeline/loaderUtils/parseImportsAndComments.mjs

@@ -304,10 +304,14 @@ function scanForImports(sourceCode, importDetector, isMdxFile, removeCommentsWit
           // Collect comments if they're notable (all stripped comments when no prefix specified, or notable comments when prefix specified)
           const shouldCollect = shouldStrip && !notableCommentsPrefix || isNotable;
           if (shouldCollect) {
-            if (!comments[commentStartOutputLine]) {
-              comments[commentStartOutputLine] = [];
+            // Record the comment 1-indexed: `Code` comments are always 1-indexed (the
+            // convention the enhancers match against the `dataLn` line gutter). `outputLine`
+            // is tracked 0-indexed internally, so add one at the point of storage.
+            const commentLine = commentStartOutputLine + 1;
+            if (!comments[commentLine]) {
+              comments[commentLine] = [];
             }
-            comments[commentStartOutputLine].push(...stripCommentMarkers(commentText));
+            comments[commentLine].push(...stripCommentMarkers(commentText));
           }
           if (shouldStrip) {
             anyCommentStripped = true;
@@ -350,10 +354,14 @@ function scanForImports(sourceCode, importDetector, isMdxFile, removeCommentsWit
           // Collect comments if they're notable (all stripped comments when no prefix specified, or notable comments when prefix specified)
           const shouldCollect = shouldStrip && !notableCommentsPrefix || isNotable;
           if (shouldCollect) {
-            if (!comments[commentStartOutputLine]) {
-              comments[commentStartOutputLine] = [];
+            // Record the comment 1-indexed: `Code` comments are always 1-indexed (the
+            // convention the enhancers match against the `dataLn` line gutter). `outputLine`
+            // is tracked 0-indexed internally, so add one at the point of storage.
+            const commentLine = commentStartOutputLine + 1;
+            if (!comments[commentLine]) {
+              comments[commentLine] = [];
             }
-            comments[commentStartOutputLine].push(...stripCommentMarkers(commentText));
+            comments[commentLine].push(...stripCommentMarkers(commentText));
           }
           if (shouldStrip) {
             anyCommentStripped = true;
@@ -526,10 +534,12 @@ function scanForImports(sourceCode, importDetector, isMdxFile, removeCommentsWit
     // Collect comments if they're notable (all stripped comments when no prefix specified, or notable comments when prefix specified)
     const shouldCollect = shouldStrip && !notableCommentsPrefix || isNotable;
     if (shouldCollect) {
-      if (!comments[commentStartOutputLine]) {
-        comments[commentStartOutputLine] = [];
+      // Record 1-indexed (the `Code` convention); see the other recording sites above.
+      const commentLine = commentStartOutputLine + 1;
+      if (!comments[commentLine]) {
+        comments[commentLine] = [];
       }
-      comments[commentStartOutputLine].push(...stripCommentMarkers(commentText));
+      comments[commentLine].push(...stripCommentMarkers(commentText));
     }
     if (shouldStrip) {
       anyCommentStripped = true;

package/pipeline/loaderUtils/resolveModulePath.mjs

@@ -44,7 +44,26 @@ export const VALUE_IMPORT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mdx', '.
 /**
  * Static asset extensions that should NOT be resolved as JS modules
  */
-const STATIC_ASSET_EXTENSIONS = ['.css', '.scss', '.sass', '.less', '.json', '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.woff', '.woff2', '.ttf', '.eot', '.otf'];
+const STATIC_ASSET_EXTENSIONS = ['.css', '.scss', '.json', '.svg', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.woff2'];
+
+/**
+ * Asset extensions that are intentionally unsupported.
+ * Importing one of these throws so the issue surfaces at build time.
+ */
+const UNSUPPORTED_ASSET_EXTENSIONS = ['.sass',
+// use '.scss' instead
+'.less',
+// legacy
+'.ico',
+// legacy
+'.woff',
+// legacy, use '.woff2' (https://web.dev/articles/font-best-practices#use_woff2)
+'.eot',
+// legacy
+'.ttf',
+// desktop font format
+'.otf' // desktop font format
+];
 
 /**
  * Checks if a file path or import path represents a static asset
@@ -601,6 +620,9 @@ export async function resolveImportResult(importResult, readDirectory, options =
     url,
     includeTypeDefs
   }] of Object.entries(importResult)) {
+    if (UNSUPPORTED_ASSET_EXTENSIONS.some(ext => importPath.endsWith(ext))) {
+      throw new Error(`Unsupported import extension: "${importPath}".`);
+    }
     if (isStaticAsset(importPath)) {
       // Static asset - use url as-is
       staticAssets.push(url);

package/pipeline/parseCreateFactoryCall/parseCreateFactoryCall.d.mts

@@ -5,7 +5,19 @@ import type { Externals } from "../../CodeHighlighter/types.mjs";
  * Parse options for create* factory call parsing
  */
 export interface ParseOptions {
+  /**
+   * Only extract metadata (url + options), skipping variant-import resolution.
+   * Treats the call as `create*(url, options?)`. Implies {@link ParseOptions.noVariants}.
+   */
   metadataOnly?: boolean;
+  /**
+   * The factory has no variants argument: its call shape is `create*(url, options?)`
+   * (e.g. `createStream`), so the argument after `url` is the options
+   * object rather than variants. Use this (with `replacePrecomputeValue`) to build
+   * a precompute loader for a no-variants factory. Unlike `metadataOnly`, variant
+   * resolution is simply not applicable rather than intentionally skipped.
+   */
+  noVariants?: boolean;
   allowExternalVariants?: boolean;
   allowMultipleFactories?: boolean;
 }

package/pipeline/parseCreateFactoryCall/parseCreateFactoryCall.mjs

@@ -603,21 +603,23 @@ async function processCreateFactoryMatch(match, code, filePath, parseOptions, im
   // Validate URL argument
   validateUrlArgument(urlArg, functionName, filePath);
 
-  // Validate variants argument (skip in metadata-only mode)
+  // Validate variants argument (skip when there is no variants argument)
   const {
-    metadataOnly = false
+    metadataOnly = false,
+    noVariants = false
   } = parseOptions;
-  if (!metadataOnly && structuredVariants !== undefined) {
+  const skipVariants = metadataOnly || noVariants;
+  if (!skipVariants && structuredVariants !== undefined) {
     validateVariantsArgument(structuredVariants, functionName, filePath);
   }
 
   // Extract URL (typically import.meta.url)
   const url = urlArg.trim();
 
-  // Resolve variants using structured data (skip in metadata-only mode)
+  // Resolve variants using structured data (skip when there is no variants argument)
   let variants;
   let namedExports;
-  if (!metadataOnly) {
+  if (!skipVariants) {
     if (structuredVariants !== undefined) {
       // Use regular variants argument
       const variantsResult = parseVariantsArgumentFromStructured(structuredVariants, importMap, namedExportsMap, functionName, filePath);
@@ -786,12 +788,14 @@ function findFirstCreateFactoryCall(code, filePath, parseOptions = {}, startInde
 
   // Validate the function follows the convention
   const {
-    metadataOnly = false
+    metadataOnly = false,
+    noVariants = false
   } = parseOptions;
-  if (metadataOnly) {
-    // For metadata-only mode: expect 1-2 arguments (url, options?)
+  const skipVariants = metadataOnly || noVariants;
+  if (skipVariants) {
+    // No variants argument: expect 1-2 arguments (url, options?)
     if (structured.length < 1 || structured.length > 2) {
-      throw new Error(`Invalid ${functionName} call in ${filePath}. ` + `Expected 1-2 arguments (url, options?) but got ${structured.length} arguments. ` + `In metadata-only mode, functions should follow: create*(url, options?)`);
+      throw new Error(`Invalid ${functionName} call in ${filePath}. ` + `Expected 1-2 arguments (url, options?) but got ${structured.length} arguments. ` + `For a no-variants factory, calls should follow: create*(url, options?)`);
     }
   } else if (hasGenerics && structured.length <= 2) {
     // When generics are present AND we have 1-2 arguments, expect (url, options?)
@@ -804,8 +808,8 @@ function findFirstCreateFactoryCall(code, filePath, parseOptions = {}, startInde
   }
 
   // Handle different argument patterns based on mode
-  if (metadataOnly) {
-    // Metadata-only mode: expect 1-2 arguments (url, options?)
+  if (skipVariants) {
+    // No variants argument: expect 1-2 arguments (url, options?)
     if (structured.length === 1) {
       const [urlArg] = structured;
       return {
@@ -847,7 +851,7 @@ function findFirstCreateFactoryCall(code, filePath, parseOptions = {}, startInde
         argumentsEndIndex: endIndex
       };
     }
-  } else if (!metadataOnly && hasGenerics && structured.length === 1) {
+  } else if (!skipVariants && hasGenerics && structured.length === 1) {
     // Generics-only mode (non-metadata): expect 1 argument (url) - use generics as variants
     const [urlArg] = structured;
     return {
@@ -865,7 +869,7 @@ function findFirstCreateFactoryCall(code, filePath, parseOptions = {}, startInde
       argumentsStartIndex: parenIndex + 1,
       argumentsEndIndex: endIndex
     };
-  } else if (!metadataOnly && structured.length >= 2) {
+  } else if (!skipVariants && structured.length >= 2) {
     // Normal mode: expect 2-3 arguments (url, variants, options?)
     if (structured.length === 2) {
       const [urlArg, secondArg] = structured;

package/pipeline/parseSource/addLineGutters.mjs

@@ -1,6 +1,7 @@
 // Example copied from https://github.com/wooorm/starry-night#example-adding-line-numbers
 
 import { createFrame } from "./createFrame.mjs";
+import { isFrameSpan } from "./isFrameSpan.mjs";
 
 /**
  * Counts the number of lines in a HAST tree without mutating it.
@@ -127,26 +128,59 @@ export function starryNightGutter(tree, sourceLines, frameSize = 120) {
     replacement.push(createFrame(frameLines));
   }
 
-  // If there are multiple frames and sourceLines provided, add dataAsString to each frame.
-  // Every frame except the last covers `frameSize` source lines, each of which
-  // was followed by a newline separator in the original source, so its text
-  // ends with a trailing '\n'. The final frame only carries a trailing newline
-  // if the source itself ends with one. Without this trailing '\n', the
-  // plain-text fallback and the highlighted render disagree by exactly one
-  // newline per non-final frame, which causes a layout shift during lazy
-  // hydration when a frame toggles between the two.
-  if (replacement.length > 1 && sourceLines) {
+  // When `sourceLines` is provided, attach a precomputed `fallback` hast to
+  // every frame (including single-frame output).
+  //
+  // `frame.data.fallback` is a basic hast node array (single `{ type: 'text' }`
+  // node) carrying the same text the highlighted hast would render. It is set
+  // here, before the enhancer pipeline runs, so enhancers can read and keep it
+  // in sync. Enhancers only modify spans (never the plain-text output), so a
+  // frame's fallback stays valid unless the frame is restructured — in which
+  // case `restructureFrames` shifts the corresponding lines between frames.
+  //
+  // Downstream, these per-frame fallbacks are collected into the variant-level
+  // root fallback and also let the renderer skip running
+  // `stripHighlightingSpans` per frame at render time. Every frame except the
+  // last covers `frameSize` source lines, each of which was followed by a
+  // newline separator in the original source, so its text ends with a trailing
+  // '\n'. The final frame only carries a trailing newline if the source itself
+  // ends with one. Without this trailing '\n', the plain-text fallback and the
+  // highlighted render disagree by exactly one newline per non-final frame,
+  // which causes a layout shift during lazy hydration when a frame toggles
+  // between the two.
+  if (sourceLines) {
     const lastIndex = replacement.length - 1;
     for (let frameIndex = 0; frameIndex < replacement.length; frameIndex += 1) {
       const frame = replacement[frameIndex];
-      if (frame.type === 'element' && frame.tagName === 'span' && frame.properties?.className === 'frame') {
+      if (frame.type === 'element' && frame.tagName === 'span' && isFrameSpan(frame)) {
         // Extract line range from child .line elements
         const lineChildren = frame.children.filter(c => c.type === 'element' && c.properties?.className === 'line' && typeof c.properties.dataLn === 'number');
         if (lineChildren.length > 0) {
           const startLine = Number(lineChildren[0].properties.dataLn) - 1;
           const endLine = Number(lineChildren[lineChildren.length - 1].properties.dataLn);
           const joined = sourceLines.slice(startLine, endLine).join('\n');
-          frame.properties.dataAsString = frameIndex < lastIndex ? `${joined}\n` : joined;
+          // Non-final frames are always followed by more content, so their text
+          // ends with the line separator. The final frame's text ends with a
+          // newline only when the source itself does — mirroring the highlighted
+          // render, whose last `.line` span is then followed by a trailing `\n`
+          // text node. `sourceLines` has one more entry than `lineNumber` exactly
+          // when the source ended with a newline (the empty segment after it
+          // never became a line). This keeps the plain-text fallback the same
+          // height as the highlighted render (no hydration jump) AND makes the
+          // root fallback dictionary an exact match for the raw source text.
+          const sourceEndsWithNewline = sourceLines.length > lineNumber;
+          const text = frameIndex < lastIndex || sourceEndsWithNewline ? `${joined}\n` : joined;
+          // Cast to `ElementData` because `hast-util-from-parse5` augments
+          // it with a required `position` field (upstream bug — should be
+          // optional). We're not running through that parser here, so the
+          // field never exists at runtime.
+          if (!frame.data) {
+            frame.data = {};
+          }
+          frame.data.fallback = [{
+            type: 'text',
+            value: text
+          }];
         }
       }
     }

package/pipeline/parseSource/calculateFrameRanges.d.mts

@@ -66,6 +66,23 @@ export interface EnhanceCodeEmphasisOptions {
    * @default 12
    */
   focusFramesMaxSize?: number;
+  /**
+   * How to handle a focused region that exceeds `focusFramesMaxSize`.
+   *
+   * - `'truncate'` (default) — keep the first `focusFramesMaxSize` lines visible
+   *   as a window and hide the overflow.
+   * - `'hide'` — produce no visible-window frame at all: the block collapses to
+   *   nothing (`focusedLines === 0`) while staying `collapsible`, so the collapsed
+   *   state is empty and expanding reveals the whole source.
+   *
+   * Applies to every focus trigger — an oversized `@highlight` region, an
+   * oversized `@focus` / `@focus-start` region, and the auto-focus-from-line-1
+   * case (no emphasis comments) when the source exceeds `focusFramesMaxSize`.
+   * Regions that fit within `focusFramesMaxSize` are unaffected.
+   *
+   * @default 'truncate'
+   */
+  oversizedFocus?: 'truncate' | 'hide';
   /**
    * When `true`, throws an error if a `@highlight-text` match has to be
    * fragmented across element boundaries (producing `data-hl-part` spans).
@@ -79,6 +96,11 @@ export interface EnhanceCodeEmphasisOptions {
    * use this to visually shift collapsible regions horizontally when
    * surrounding context lines are hidden. Off by default since most demos
    * don't need it and it bloats the rendered HTML.
+   *
+   * Indent and padding are alternatives for conveying surrounding context.
+   * Combining this with the `paddingFrameMaxSize` option throws (configure one
+   * or the other); a per-region `@padding` directive in the source is allowed
+   * and ignored while this is set.
    * @default false
    */
   emitFrameIndent?: boolean;