@mui/internal-docs-infra 0.5.1-canary.0 → 0.6.1-canary.0

package/cli/index.mjs

@@ -7,4 +7,4 @@ function getVersion() {
 }
 yargs().scriptName('docs-infra').usage('$0 <command> [args]').command(runValidate).demandCommand(1, 'You need at least one command before moving on').strict().help()
 // MUI_VERSION is set through the code-infra build command.
-.version("0.5.0" || getVersion()).parse(hideBin(process.argv));
+.version("0.6.0" || getVersion()).parse(hideBin(process.argv));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.5.1-canary.0",
+  "version": "0.6.1-canary.0",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "keywords": [
@@ -452,6 +452,16 @@
         "default": "./pipeline/loadServerSource/index.mjs"
       }
     },
+    "./pipeline/enhanceCodeEmphasis": {
+      "import": {
+        "types": "./pipeline/enhanceCodeEmphasis/index.d.mts",
+        "default": "./pipeline/enhanceCodeEmphasis/index.mjs"
+      },
+      "default": {
+        "types": "./pipeline/enhanceCodeEmphasis/index.d.mts",
+        "default": "./pipeline/enhanceCodeEmphasis/index.mjs"
+      }
+    },
     "./pipeline/parseSource": {
       "import": {
         "types": "./pipeline/parseSource/index.d.mts",
@@ -506,5 +516,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "df142b55588e09b911db8be848c133b0ebad1cc0"
+  "gitSha": "cad146f1682e0cb63baeeab28454423d77ef7c89"
 }

package/pipeline/enhanceCodeEmphasis/calculateFrameIndent.d.mts

@@ -0,0 +1,12 @@
+import type { Element } from 'hast';
+/**
+ * Calculates the shared indent level for a set of line elements.
+ *
+ * Finds the minimum leading whitespace across all non-empty lines,
+ * then divides by the indent size (2 spaces) and floors to get
+ * the indent level.
+ *
+ * @param lineElements - Array of HAST line elements to analyze
+ * @returns The shared indent level (e.g., 2 for 4 leading spaces with 2-space indent)
+ */
+export declare function calculateFrameIndent(lineElements: Element[]): number;

package/pipeline/enhanceCodeEmphasis/calculateFrameIndent.mjs

@@ -0,0 +1,62 @@
+const INDENT_SIZE = 2;
+
+/**
+ * Counts leading spaces in an element by walking the HAST tree.
+ *
+ * Returns the number of leading space characters before the first
+ * non-space character, or -1 if the line is empty/whitespace-only.
+ * Only counts space characters. Tab indentation is not supported
+ * since the input is HAST output from starry-night which uses spaces.
+ */
+function countLeadingSpaces(element) {
+  let spaces = 0;
+  function walk(node) {
+    for (const child of node.children) {
+      if (child.type === 'text') {
+        for (const char of child.value) {
+          if (char === ' ') {
+            spaces += 1;
+          } else {
+            return true;
+          }
+        }
+      } else if (child.type === 'element') {
+        if (walk(child)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  const foundNonSpace = walk(element);
+  return foundNonSpace ? spaces : -1;
+}
+
+/**
+ * Calculates the shared indent level for a set of line elements.
+ *
+ * Finds the minimum leading whitespace across all non-empty lines,
+ * then divides by the indent size (2 spaces) and floors to get
+ * the indent level.
+ *
+ * @param lineElements - Array of HAST line elements to analyze
+ * @returns The shared indent level (e.g., 2 for 4 leading spaces with 2-space indent)
+ */
+export function calculateFrameIndent(lineElements) {
+  let minLeadingSpaces = Infinity;
+  for (const element of lineElements) {
+    const leadingSpaces = countLeadingSpaces(element);
+
+    // Skip empty/whitespace-only lines
+    if (leadingSpaces === -1) {
+      continue;
+    }
+    if (leadingSpaces < minLeadingSpaces) {
+      minLeadingSpaces = leadingSpaces;
+    }
+  }
+  if (minLeadingSpaces === Infinity) {
+    return 0;
+  }
+  return Math.floor(minLeadingSpaces / INDENT_SIZE);
+}

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.d.mts

@@ -1,13 +1,16 @@
 import type { SourceEnhancer } from "../../CodeHighlighter/types.mjs";
+import type { EnhanceCodeEmphasisOptions } from "../parseSource/calculateFrameRanges.mjs";
+export type { EmphasisMeta, EnhanceCodeEmphasisOptions, FrameRange } from "../parseSource/calculateFrameRanges.mjs";
 /**
  * The prefix used to identify emphasis comments in source code.
  * Comments starting with this prefix will be processed for emphasis.
  */
 export declare const EMPHASIS_COMMENT_PREFIX = "@highlight";
 /**
- * Source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
+ * and restructures frames around highlighted regions.
  *
- * Supports four patterns:
+ * Supports five patterns:
  *
  * 1. **Single line emphasis** - emphasizes the line containing the comment:
  *    ```jsx
@@ -37,12 +40,30 @@ export declare const EMPHASIS_COMMENT_PREFIX = "@highlight";
  *    <h1>Heading 1</h1> {/* @highlight-text "Heading 1" *\/}
  *    ```
  *
+ * 5. **Focus override** - mark a region for padding focus:
+ *    ```jsx
+ *    <h1>Heading 1</h1> {/* @highlight @focus *\/}
+ *    ```
+ *
  * Emphasized lines receive a `data-hl` attribute on their `<span class="line">` element.
+ * When highlights exist, frames are restructured with `data-frame-type` attributes
+ * (`highlighted`, `padding-top`, `padding-bottom`, or omitted for normal).
+ * Highlighted frames also receive `data-frame-indent` with the shared indent level.
+ *
+ * @param options - Optional configuration for padding frames
+ * @returns A `SourceEnhancer` function
+ *
+ * @example
+ * ```ts
+ * import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
  *
- * @param root - The HAST root node to enhance
- * @param comments - Comments extracted from the source code, keyed by line number
- * @param _fileName - The name of the file being processed (unused)
- * @returns The enhanced HAST root node with emphasis attributes added
+ * const enhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 5, focusFramesMaxSize: 8 })];
+ * ```
+ */
+export declare function createEnhanceCodeEmphasis(options?: EnhanceCodeEmphasisOptions): SourceEnhancer;
+/**
+ * Default source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Uses no padding frames by default. Use `createEnhanceCodeEmphasis` for configurable padding.
  *
  * @example
  * ```ts

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.mjs

@@ -1,3 +1,6 @@
+import { calculateFrameRanges } from "../parseSource/calculateFrameRanges.mjs";
+import { calculateFrameIndent } from "./calculateFrameIndent.mjs";
+import { restructureFrames } from "../parseSource/restructureFrames.mjs";
 /**
  * The prefix used to identify emphasis comments in source code.
  * Comments starting with this prefix will be processed for emphasis.
@@ -8,19 +11,15 @@ export const EMPHASIS_COMMENT_PREFIX = '@highlight';
  * Parsed emphasis directive from a comment.
  */
 
-/**
- * Metadata for an emphasized line.
- */
-
 /**
  * Extracts a quoted string from content.
  * Supports both double quotes ("...") and single quotes ('...').
+ * Escaped quotes within the string are not supported.
  *
  * @param content - The content to extract the quoted string from
  * @returns The extracted string (without quotes) or undefined if no quoted string found
  */
 function extractQuotedString(content) {
-  // Match either double-quoted or single-quoted string
   const match = content.match(/^["'](.*)["']$/);
   if (match) {
     return match[1];
@@ -30,14 +29,40 @@ function extractQuotedString(content) {
   return anyMatch?.[1];
 }
 
+/**
+ * Extracts and removes the `@focus` keyword from content.
+ *
+ * @param content - The content to check for `@focus`
+ * @returns An object with `focus` boolean and the `remaining` content with `@focus` removed
+ */
+function extractFocus(content) {
+  // Match @focus only as a standalone token (not inside quotes)
+  const match = content.match(/(^|\s)@focus(\s|$)/);
+  if (!match) {
+    return {
+      focus: false,
+      remaining: content
+    };
+  }
+  const start = match.index + match[1].length;
+  const remaining = (content.slice(0, start) + content.slice(start + '@focus'.length)).trim();
+  return {
+    focus: true,
+    remaining
+  };
+}
+
 /**
  * Parses emphasis comments and returns structured directives.
  *
  * Supported formats:
  * - Single line: `@highlight` or `@highlight "description"`
+ * - Single line focused: `@highlight @focus` or `@highlight @focus "description"`
  * - Multiline start: `@highlight-start` or `@highlight-start "description"`
+ * - Multiline start focused: `@highlight-start @focus` or `@highlight-start @focus "description"`
  * - Multiline end: `@highlight-end`
  * - Text highlight: `@highlight-text "text to highlight"`
+ * - Text highlight focused: `@highlight-text @focus "text to highlight"`
  *
  * @param comments - Source comments keyed by line number
  * @returns Array of parsed emphasis directives
@@ -63,31 +88,46 @@ function parseEmphasisDirectives(comments) {
       } else if (content.startsWith('-start')) {
         // Start of multiline emphasis: @highlight-start or @highlight-start "description"
         const afterStart = content.slice('-start'.length).trim();
-        const description = extractQuotedString(afterStart);
+        const {
+          focus,
+          remaining: remainingStart
+        } = extractFocus(afterStart);
+        const description = extractQuotedString(remainingStart);
         directives.push({
           line,
           type: 'start',
-          description
+          description,
+          focus
         });
       } else if (content.startsWith('-text')) {
         // Text highlight: @highlight-text "text to highlight"
         const afterText = content.slice('-text'.length).trim();
-        const highlightText = extractQuotedString(afterText);
+        const {
+          focus,
+          remaining: remainingText
+        } = extractFocus(afterText);
+        const highlightText = extractQuotedString(remainingText);
         if (highlightText) {
           directives.push({
             line,
             type: 'text',
-            highlightText
+            highlightText,
+            focus
           });
         }
       } else {
         // Single line emphasis: @highlight or @highlight "description"
         const afterHighlight = content.trim();
-        const description = extractQuotedString(afterHighlight) || undefined;
+        const {
+          focus,
+          remaining: remainingSingle
+        } = extractFocus(afterHighlight);
+        const description = extractQuotedString(remainingSingle) || undefined;
         directives.push({
           line,
           type: 'single',
-          description
+          description,
+          focus
         });
       }
     }
@@ -231,13 +271,15 @@ function calculateEmphasizedLines(directives, lineElements) {
       emphasizedLines.set(directive.line, {
         description,
         strong,
-        position: 'single'
+        position: 'single',
+        focus: directive.focus
       });
     } else if (directive.type === 'text') {
       // Text highlight - emphasize specific text within the line
       emphasizedLines.set(directive.line, {
         position: 'single',
-        highlightText: directive.highlightText
+        highlightText: directive.highlightText,
+        focus: directive.focus
       });
     }
   }
@@ -286,11 +328,14 @@ function calculateEmphasizedLines(directives, lineElements) {
           strong: true,
           // Nested = always strong
           description: existing.description ?? (line === startLine ? description : undefined),
-          position: existing.position ?? position // Inner range position takes precedence
+          position: existing.position ?? position,
+          // Inner range position takes precedence
+          focus: existing.focus || startDirective.focus
         } : {
           strong,
           description: line === startLine ? description : undefined,
-          position
+          position,
+          focus: startDirective.focus
         };
         emphasizedLines.set(line, meta);
       }
@@ -362,52 +407,113 @@ function wrapTextInHighlightSpan(children, textToHighlight) {
 }
 
 /**
- * Recursively finds and modifies line elements in a HAST tree.
+ * Single-pass traversal that applies emphasis attributes to line elements
+ * AND collects leading whitespace for indent calculation on highlighted lines.
+ *
+ * This merges what would otherwise be two separate traversals into one.
  *
  * @param node - The node to process
  * @param emphasizedLines - Map of line numbers to their emphasis metadata
+ * @returns Array of line elements that are highlighted, grouped by region
  */
-function addEmphasisToLines(node, emphasizedLines) {
-  if (!('children' in node) || !node.children) {
-    return;
-  }
-  for (let i = 0; i < node.children.length; i += 1) {
-    const child = node.children[i];
-    if (child.type !== 'element') {
-      continue;
+function applyEmphasisAndCollectHighlightedElements(node, emphasizedLines) {
+  const highlightedLineElements = [];
+  function traverse(n) {
+    if (!('children' in n) || !n.children) {
+      return;
     }
+    for (let i = 0; i < n.children.length; i += 1) {
+      const child = n.children[i];
+      if (child.type !== 'element') {
+        continue;
+      }
 
-    // Check if this is a line element
-    if (child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
-      const lineNumber = child.properties.dataLn;
-      const meta = emphasizedLines.get(lineNumber);
-      if (meta !== undefined) {
-        if (meta.highlightText) {
-          // For text highlight, wrap the specific text in a span with data-hl
-          // Don't add data-hl to the line itself
-          child.children = wrapTextInHighlightSpan(child.children, meta.highlightText);
-        } else {
-          // Use data-hl with optional "strong" value on the line
-          child.properties.dataHl = meta.strong ? 'strong' : '';
-          if (meta.description) {
-            child.properties.dataHlDescription = meta.description;
-          }
-          if (meta.position) {
-            child.properties.dataHlPosition = meta.position;
+      // Check if this is a line element
+      if (child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+        const lineNumber = child.properties.dataLn;
+        const meta = emphasizedLines.get(lineNumber);
+        if (meta !== undefined) {
+          if (meta.highlightText) {
+            // For text highlight, wrap the specific text in a span with data-hl
+            // Don't add data-hl to the line itself
+            child.children = wrapTextInHighlightSpan(child.children, meta.highlightText);
+          } else {
+            // Use data-hl with optional "strong" value on the line
+            child.properties.dataHl = meta.strong ? 'strong' : '';
+            if (meta.description) {
+              child.properties.dataHlDescription = meta.description;
+            }
+            if (meta.position) {
+              child.properties.dataHlPosition = meta.position;
+            }
           }
+
+          // Collect this line element for indent calculation
+          highlightedLineElements.push(child);
         }
       }
+
+      // Recurse into children (for frames containing lines)
+      traverse(child);
+    }
+  }
+  traverse(node);
+  return highlightedLineElements;
+}
+
+/**
+ * Groups highlighted line elements by their highlight regions and calculates
+ * the indent level for each region.
+ *
+ * @param highlightedElements - Line elements that are highlighted, in order
+ * @param emphasizedLines - The emphasis metadata map
+ * @returns Map from region index to indent level
+ */
+function calculateRegionIndentLevels(highlightedElements, emphasizedLines) {
+  const regionIndentLevels = new Map();
+  if (highlightedElements.length === 0) {
+    return regionIndentLevels;
+  }
+
+  // Group elements by consecutive regions
+  const sortedLines = Array.from(emphasizedLines.keys()).sort((a, b) => a - b);
+  let regionIndex = 0;
+  let regionElements = [];
+  let prevLine = -1;
+
+  // Build a quick lookup from lineNumber to element
+  const elementByLine = new Map();
+  for (const el of highlightedElements) {
+    const ln = el.properties?.dataLn;
+    elementByLine.set(ln, el);
+  }
+  for (const line of sortedLines) {
+    const el = elementByLine.get(line);
+    if (!el) {
+      continue;
+    }
+    if (prevLine >= 0 && line !== prevLine + 1) {
+      // Gap: close current region
+      regionIndentLevels.set(regionIndex, calculateFrameIndent(regionElements));
+      regionIndex += 1;
+      regionElements = [];
     }
+    regionElements.push(el);
+    prevLine = line;
+  }
 
-    // Recurse into children (for frames containing lines)
-    addEmphasisToLines(child, emphasizedLines);
+  // Close the last region
+  if (regionElements.length > 0) {
+    regionIndentLevels.set(regionIndex, calculateFrameIndent(regionElements));
   }
+  return regionIndentLevels;
 }
 
 /**
- * Source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Creates a source enhancer that adds emphasis to code lines based on `@highlight` comments
+ * and restructures frames around highlighted regions.
  *
- * Supports four patterns:
+ * Supports five patterns:
  *
  * 1. **Single line emphasis** - emphasizes the line containing the comment:
  *    ```jsx
@@ -437,12 +543,66 @@ function addEmphasisToLines(node, emphasizedLines) {
  *    <h1>Heading 1</h1> {/* @highlight-text "Heading 1" *\/}
  *    ```
  *
+ * 5. **Focus override** - mark a region for padding focus:
+ *    ```jsx
+ *    <h1>Heading 1</h1> {/* @highlight @focus *\/}
+ *    ```
+ *
  * Emphasized lines receive a `data-hl` attribute on their `<span class="line">` element.
+ * When highlights exist, frames are restructured with `data-frame-type` attributes
+ * (`highlighted`, `padding-top`, `padding-bottom`, or omitted for normal).
+ * Highlighted frames also receive `data-frame-indent` with the shared indent level.
  *
- * @param root - The HAST root node to enhance
- * @param comments - Comments extracted from the source code, keyed by line number
- * @param _fileName - The name of the file being processed (unused)
- * @returns The enhanced HAST root node with emphasis attributes added
+ * @param options - Optional configuration for padding frames
+ * @returns A `SourceEnhancer` function
+ *
+ * @example
+ * ```ts
+ * import { createEnhanceCodeEmphasis } from '@mui/internal-docs-infra/pipeline/enhanceCodeEmphasis';
+ *
+ * const enhancers = [createEnhanceCodeEmphasis({ paddingFrameMaxSize: 5, focusFramesMaxSize: 8 })];
+ * ```
+ */
+export function createEnhanceCodeEmphasis(options = {}) {
+  return (root, comments) => {
+    if (!comments || Object.keys(comments).length === 0) {
+      return root;
+    }
+
+    // Step 1: Parse directives from comments (no tree traversal)
+    const directives = parseEmphasisDirectives(comments);
+    if (directives.length === 0) {
+      return root;
+    }
+
+    // Step 2 (Traversal 1): Build line element map
+    const lineElements = buildLineElementMap(root);
+
+    // Step 3: Calculate which lines are emphasized (no tree traversal)
+    const emphasizedLines = calculateEmphasizedLines(directives, lineElements);
+    if (emphasizedLines.size === 0) {
+      return root;
+    }
+
+    // Step 4 (Traversal 2): Apply emphasis attributes AND collect highlighted elements
+    const highlightedElements = applyEmphasisAndCollectHighlightedElements(root, emphasizedLines);
+
+    // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal)
+    const regionIndentLevels = calculateRegionIndentLevels(highlightedElements, emphasizedLines);
+
+    // Step 6: Calculate frame ranges (pure math, no tree traversal)
+    const totalLines = root.data?.totalLines ?? lineElements.size;
+    const frameRanges = calculateFrameRanges(emphasizedLines, totalLines, options);
+
+    // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
+    restructureFrames(root, frameRanges, regionIndentLevels);
+    return root;
+  };
+}
+
+/**
+ * Default source enhancer that adds emphasis to code lines based on `@highlight` comments.
+ * Uses no padding frames by default. Use `createEnhanceCodeEmphasis` for configurable padding.
  *
  * @example
  * ```ts
@@ -451,19 +611,4 @@ function addEmphasisToLines(node, emphasizedLines) {
  * const enhancers = [enhanceCodeEmphasis];
  * ```
  */
-export const enhanceCodeEmphasis = (root, comments) => {
-  if (!comments || Object.keys(comments).length === 0) {
-    return root;
-  }
-  const directives = parseEmphasisDirectives(comments);
-  if (directives.length === 0) {
-    return root;
-  }
-  const lineElements = buildLineElementMap(root);
-  const emphasizedLines = calculateEmphasizedLines(directives, lineElements);
-  if (emphasizedLines.size === 0) {
-    return root;
-  }
-  addEmphasisToLines(root, emphasizedLines);
-  return root;
-};
+export const enhanceCodeEmphasis = createEnhanceCodeEmphasis();

package/pipeline/parseSource/addLineGutters.mjs

@@ -1,5 +1,7 @@
 // Example copied from https://github.com/wooorm/starry-night#example-adding-line-numbers
 
+import { createFrame } from "./createFrame.mjs";
+
 /**
  * Counts the number of lines in a HAST tree without mutating it.
  * Uses the same logic as starryNightGutter but only returns the count.
@@ -94,7 +96,7 @@ export function starryNightGutter(tree, sourceLines, frameSize = 120) {
 
         // Check if we need to create a frame (only if sourceLines provided, otherwise keep everything in one frame)
         if (sourceLines && lineNumber % frameSize === 0) {
-          replacement.push(createFrame(frameLines, sourceLines, frameStartLine, lineNumber));
+          replacement.push(createFrame(frameLines, frameStartLine, lineNumber));
           frameLines = [];
           frameStartLine = lineNumber + 1;
         }
@@ -125,7 +127,7 @@ export function starryNightGutter(tree, sourceLines, frameSize = 120) {
 
   // Add any remaining lines as the final frame
   if (frameLines.length > 0) {
-    replacement.push(createFrame(frameLines, sourceLines, frameStartLine, lineNumber));
+    replacement.push(createFrame(frameLines, frameStartLine, lineNumber));
   }
 
   // If there are multiple frames and sourceLines provided, add dataAsString to each frame
@@ -158,21 +160,4 @@ function createLine(children, line) {
     },
     children
   };
-}
-function createFrame(frameChildren, sourceLines, startLine, endLine) {
-  const properties = {
-    className: 'frame'
-  };
-
-  // Store line range information if provided (for dataAsString generation)
-  if (sourceLines && startLine !== undefined && endLine !== undefined) {
-    properties.dataFrameStartLine = startLine;
-    properties.dataFrameEndLine = endLine;
-  }
-  return {
-    type: 'element',
-    tagName: 'span',
-    properties,
-    children: frameChildren
-  };
 }

package/pipeline/parseSource/calculateFrameRanges.d.mts

@@ -0,0 +1,59 @@
+/**
+ * Metadata for an emphasized line.
+ */
+export interface EmphasisMeta {
+  /** Optional description for this emphasis */
+  description?: string;
+  /** Position: 'single' for single-line, 'start'/'end' for multiline range bounds, undefined for middle */
+  position?: 'single' | 'start' | 'end';
+  /** Whether this is a strong emphasis (description ended with !) */
+  strong?: boolean;
+  /** For text highlighting: the specific text to highlight within the line */
+  highlightText?: string;
+  /** Whether this line's region is the focused region (for padding) */
+  focus?: boolean;
+}
+/**
+ * A range of lines that forms a frame in the output.
+ */
+export interface FrameRange {
+  /** First line number (1-based, inclusive) */
+  startLine: number;
+  /** Last line number (1-based, inclusive) */
+  endLine: number;
+  /** The type of frame */
+  type: 'normal' | 'padding-top' | 'highlighted' | 'highlighted-unfocused' | 'padding-bottom' | 'comment';
+}
+/**
+ * Options for the enhance code emphasis factory.
+ */
+export interface EnhanceCodeEmphasisOptions {
+  /**
+   * Maximum number of padding lines above and below the focused highlight region.
+   * Padding frames provide surrounding context for the highlighted code.
+   * Set to 0 or omit to disable padding frames.
+   */
+  paddingFrameMaxSize?: number;
+  /**
+   * Maximum total number of lines in the focus area (padding-top + highlighted + padding-bottom).
+   * When set, padding sizes are reduced so the total focus area fits within this limit.
+   * The remainder after subtracting the highlighted size is split: floor(remainder/2) for
+   * padding-top and ceil(remainder/2) for padding-bottom.
+   */
+  focusFramesMaxSize?: number;
+}
+/**
+ * Calculates frame ranges for the code block based on emphasized lines.
+ *
+ * This is a pure function that operates on line numbers — no HAST traversal.
+ * It groups consecutive highlighted lines into regions, determines the focused
+ * region (first by default, or the one with `focus: true`), computes padding
+ * for the focused region, and returns an ordered array of frame ranges covering
+ * all lines 1 through totalLines.
+ *
+ * @param emphasizedLines - Map of line numbers to their emphasis metadata
+ * @param totalLines - Total number of lines in the code block
+ * @param options - Optional padding configuration
+ * @returns Ordered array of frame ranges covering all lines
+ */
+export declare function calculateFrameRanges(emphasizedLines: Map<number, EmphasisMeta>, totalLines: number, options?: EnhanceCodeEmphasisOptions): FrameRange[];

package/pipeline/parseSource/calculateFrameRanges.mjs

@@ -0,0 +1,209 @@
+/**
+ * Metadata for an emphasized line.
+ */
+
+/**
+ * A range of lines that forms a frame in the output.
+ */
+
+/**
+ * A contiguous region of highlighted lines.
+ */
+
+/**
+ * Options for the enhance code emphasis factory.
+ */
+
+/**
+ * Groups consecutive emphasized line numbers into highlight regions.
+ *
+ * @param emphasizedLines - Map of line numbers to their emphasis metadata
+ * @returns Sorted array of highlight regions
+ */
+function groupHighlightRegions(emphasizedLines) {
+  if (emphasizedLines.size === 0) {
+    return [];
+  }
+  const sortedLines = Array.from(emphasizedLines.keys()).sort((a, b) => a - b);
+  const regions = [];
+  let regionStart = sortedLines[0];
+  let regionEnd = sortedLines[0];
+  let hasFocus = emphasizedLines.get(sortedLines[0])?.focus ?? false;
+  for (let i = 1; i < sortedLines.length; i += 1) {
+    const line = sortedLines[i];
+    if (line === regionEnd + 1) {
+      // Consecutive line, extend current region
+      regionEnd = line;
+      if (emphasizedLines.get(line)?.focus) {
+        hasFocus = true;
+      }
+    } else {
+      // Gap found, close current region and start a new one
+      regions.push({
+        startLine: regionStart,
+        endLine: regionEnd,
+        index: regions.length,
+        focused: hasFocus
+      });
+      regionStart = line;
+      regionEnd = line;
+      hasFocus = emphasizedLines.get(line)?.focus ?? false;
+    }
+  }
+
+  // Close the last region
+  regions.push({
+    startLine: regionStart,
+    endLine: regionEnd,
+    index: regions.length,
+    focused: hasFocus
+  });
+  return regions;
+}
+
+/**
+ * Determines the focused region index.
+ * Returns the region explicitly marked with `focus: true`, or the first region.
+ *
+ * @param regions - Highlight regions
+ * @returns The index of the focused region
+ */
+function determineFocusedRegionIndex(regions) {
+  const focusedIndex = regions.findIndex(r => r.focused);
+  return focusedIndex >= 0 ? focusedIndex : 0;
+}
+
+/**
+ * Calculates padding sizes for the focused highlight region.
+ *
+ * @param region - The focused highlight region
+ * @param prevRegionEnd - End line of the previous highlight region (or 0)
+ * @param nextRegionStart - Start line of the next highlight region (or totalLines + 1)
+ * @param options - Padding configuration options
+ * @returns Padding sizes [paddingTop, paddingBottom]
+ */
+function calculatePadding(region, prevRegionEnd, nextRegionStart, options) {
+  const {
+    paddingFrameMaxSize = 0,
+    focusFramesMaxSize
+  } = options;
+  if (paddingFrameMaxSize <= 0) {
+    return [0, 0];
+  }
+  const highlightSize = region.endLine - region.startLine + 1;
+  let paddingTop = paddingFrameMaxSize;
+  let paddingBottom = paddingFrameMaxSize;
+
+  // Apply focusFramesMaxSize constraint
+  if (focusFramesMaxSize !== undefined) {
+    const remaining = focusFramesMaxSize - highlightSize;
+    if (remaining <= 0) {
+      return [0, 0];
+    }
+    paddingTop = Math.min(paddingTop, Math.floor(remaining / 2));
+    paddingBottom = Math.min(paddingBottom, Math.ceil(remaining / 2));
+  }
+
+  // Clamp to available lines before the highlight (don't overlap previous region)
+  const availableBefore = region.startLine - 1 - prevRegionEnd;
+  paddingTop = Math.min(paddingTop, Math.max(0, availableBefore));
+
+  // Clamp to available lines after the highlight (don't overlap next region)
+  const availableAfter = nextRegionStart - 1 - region.endLine;
+  paddingBottom = Math.min(paddingBottom, Math.max(0, availableAfter));
+  return [paddingTop, paddingBottom];
+}
+
+/**
+ * Calculates frame ranges for the code block based on emphasized lines.
+ *
+ * This is a pure function that operates on line numbers — no HAST traversal.
+ * It groups consecutive highlighted lines into regions, determines the focused
+ * region (first by default, or the one with `focus: true`), computes padding
+ * for the focused region, and returns an ordered array of frame ranges covering
+ * all lines 1 through totalLines.
+ *
+ * @param emphasizedLines - Map of line numbers to their emphasis metadata
+ * @param totalLines - Total number of lines in the code block
+ * @param options - Optional padding configuration
+ * @returns Ordered array of frame ranges covering all lines
+ */
+export function calculateFrameRanges(emphasizedLines, totalLines, options = {}) {
+  if (totalLines <= 0) {
+    return [];
+  }
+  const regions = groupHighlightRegions(emphasizedLines);
+  if (regions.length === 0) {
+    return [{
+      startLine: 1,
+      endLine: totalLines,
+      type: 'normal'
+    }];
+  }
+  const focusedIndex = determineFocusedRegionIndex(regions);
+
+  // Calculate padding for the focused region
+  const focusedRegion = regions[focusedIndex];
+  const prevRegionEnd = focusedIndex > 0 ? regions[focusedIndex - 1].endLine : 0;
+  const nextRegionStart = focusedIndex < regions.length - 1 ? regions[focusedIndex + 1].startLine : totalLines + 1;
+  const [paddingTop, paddingBottom] = calculatePadding(focusedRegion, prevRegionEnd, nextRegionStart, options);
+
+  // Build frame ranges by iterating through all regions
+  const frames = [];
+  let currentLine = 1;
+  for (let i = 0; i < regions.length; i += 1) {
+    const region = regions[i];
+    const isFocused = i === focusedIndex;
+    if (isFocused && paddingTop > 0) {
+      // Normal lines before padding-top
+      const paddingTopStart = region.startLine - paddingTop;
+      if (currentLine < paddingTopStart) {
+        frames.push({
+          startLine: currentLine,
+          endLine: paddingTopStart - 1,
+          type: 'normal'
+        });
+      }
+      // Padding-top frame
+      frames.push({
+        startLine: paddingTopStart,
+        endLine: region.startLine - 1,
+        type: 'padding-top'
+      });
+    } else if (currentLine < region.startLine) {
+      // Normal lines before this region
+      frames.push({
+        startLine: currentLine,
+        endLine: region.startLine - 1,
+        type: 'normal'
+      });
+    }
+
+    // Highlighted frame (focused gets 'highlighted', others get 'highlighted-unfocused')
+    frames.push({
+      startLine: region.startLine,
+      endLine: region.endLine,
+      type: isFocused ? 'highlighted' : 'highlighted-unfocused'
+    });
+    currentLine = region.endLine + 1;
+    if (isFocused && paddingBottom > 0) {
+      // Padding-bottom frame
+      frames.push({
+        startLine: currentLine,
+        endLine: currentLine + paddingBottom - 1,
+        type: 'padding-bottom'
+      });
+      currentLine = currentLine + paddingBottom;
+    }
+  }
+
+  // Remaining normal lines after all regions
+  if (currentLine <= totalLines) {
+    frames.push({
+      startLine: currentLine,
+      endLine: totalLines,
+      type: 'normal'
+    });
+  }
+  return frames;
+}

package/pipeline/parseSource/createFrame.d.mts

@@ -0,0 +1,9 @@
+import type { Element, ElementContent } from 'hast';
+import type { FrameRange } from "./calculateFrameRanges.mjs";
+/**
+ * Creates a HAST frame element (`span.frame`) with the given children and optional metadata.
+ *
+ * Used by both `addLineGutters` (initial frame creation) and `restructureFrames`
+ * (splitting/rebuilding frames for highlighting or comment extraction).
+ */
+export declare function createFrame(children: Array<ElementContent>, startLine?: number, endLine?: number, frameType?: FrameRange['type'], indentLevel?: number): Element;

package/pipeline/parseSource/createFrame.mjs

@@ -0,0 +1,29 @@
+/**
+ * Creates a HAST frame element (`span.frame`) with the given children and optional metadata.
+ *
+ * Used by both `addLineGutters` (initial frame creation) and `restructureFrames`
+ * (splitting/rebuilding frames for highlighting or comment extraction).
+ */
+export function createFrame(children, startLine, endLine, frameType, indentLevel) {
+  const properties = {
+    className: 'frame'
+  };
+  if (startLine !== undefined && endLine !== undefined) {
+    properties.dataFrameStartLine = startLine;
+    properties.dataFrameEndLine = endLine;
+  }
+  if (frameType && frameType !== 'normal') {
+    properties.dataFrameType = frameType;
+  }
+
+  // Set indent level on highlighted frames (focused or unfocused)
+  if ((frameType === 'highlighted' || frameType === 'highlighted-unfocused') && indentLevel !== undefined) {
+    properties.dataFrameIndent = indentLevel;
+  }
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties,
+    children
+  };
+}

package/pipeline/parseSource/restructureFrames.d.mts

@@ -0,0 +1,15 @@
+import type { HastRoot } from "../../CodeHighlighter/types.mjs";
+import type { FrameRange } from "./calculateFrameRanges.mjs";
+/**
+ * Restructures the HAST frame tree based on computed frame ranges.
+ *
+ * This function flattens all existing frame children into a single ordered array,
+ * then redistributes them into new frames based on the provided frame ranges.
+ * It's a flat iteration (not a deep recursive traversal) since the HAST structure
+ * is always Root → Frame(s) → Line(s).
+ *
+ * @param root - The HAST root node to restructure (mutated in place)
+ * @param frameRanges - Ordered array of frame ranges
+ * @param regionIndentLevels - Map of highlighted region index to indent level
+ */
+export declare function restructureFrames(root: HastRoot, frameRanges: FrameRange[], regionIndentLevels: Map<number, number>): void;

package/pipeline/parseSource/restructureFrames.mjs

@@ -0,0 +1,100 @@
+import { createFrame } from "./createFrame.mjs";
+
+/**
+ * Represents a line element and its trailing newline text node (if any).
+ */
+
+/**
+ * Flattens all line elements from existing frames into a single ordered array.
+ * This is a flat iteration over root.children (frames) and their direct children
+ * (lines + newline text nodes). Not a deep recursive traversal.
+ *
+ * @param root - The HAST root node
+ * @returns Ordered array of line entries
+ */
+function flattenLineEntries(root) {
+  const entries = [];
+  for (const frame of root.children) {
+    if (frame.type !== 'element' || frame.tagName !== 'span') {
+      continue;
+    }
+    const children = frame.children ?? [];
+    for (let i = 0; i < children.length; i += 1) {
+      const child = children[i];
+      if (child.type === 'element' && child.tagName === 'span' && child.properties?.className === 'line' && typeof child.properties.dataLn === 'number') {
+        const entry = {
+          lineNumber: child.properties.dataLn,
+          element: child
+        };
+
+        // Check if the next child is a trailing newline text node
+        const next = children[i + 1];
+        if (next && next.type === 'text' && /^[\r\n]+$/.test(next.value)) {
+          entry.trailingNewline = next;
+          i += 1; // Skip the newline in the next iteration
+        }
+        entries.push(entry);
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * Restructures the HAST frame tree based on computed frame ranges.
+ *
+ * This function flattens all existing frame children into a single ordered array,
+ * then redistributes them into new frames based on the provided frame ranges.
+ * It's a flat iteration (not a deep recursive traversal) since the HAST structure
+ * is always Root → Frame(s) → Line(s).
+ *
+ * @param root - The HAST root node to restructure (mutated in place)
+ * @param frameRanges - Ordered array of frame ranges
+ * @param regionIndentLevels - Map of highlighted region index to indent level
+ */
+export function restructureFrames(root, frameRanges, regionIndentLevels) {
+  // Step 1: Flatten all lines from existing frames
+  const lineEntries = flattenLineEntries(root);
+
+  // Build a lookup from line number to entry for O(1) access
+  const lineEntryMap = new Map();
+  for (const entry of lineEntries) {
+    lineEntryMap.set(entry.lineNumber, entry);
+  }
+
+  // Step 2: Track which highlighted region index each frame range belongs to
+  let highlightedRegionIndex = 0;
+
+  // Step 3: Build new frames
+  const newFrames = [];
+  for (const range of frameRanges) {
+    const children = [];
+    for (let line = range.startLine; line <= range.endLine; line += 1) {
+      const entry = lineEntryMap.get(line);
+      if (!entry) {
+        continue;
+      }
+      children.push(entry.element);
+
+      // Always add trailing newline when present to preserve original line breaks
+      if (entry.trailingNewline) {
+        children.push(entry.trailingNewline);
+      }
+    }
+
+    // Only create frame if it has children
+    if (children.length > 0) {
+      const isHighlighted = range.type === 'highlighted' || range.type === 'highlighted-unfocused';
+      const indentLevel = isHighlighted ? regionIndentLevels.get(highlightedRegionIndex) : undefined;
+      newFrames.push(createFrame(children, range.startLine, range.endLine, range.type, indentLevel));
+    }
+
+    // Increment region index after each highlighted frame (focused or unfocused)
+    if (range.type === 'highlighted' || range.type === 'highlighted-unfocused') {
+      highlightedRegionIndex += 1;
+    }
+  }
+
+  // Step 4: Replace root children
+  root.children = newFrames;
+}

package/useCode/Pre.mjs

@@ -146,6 +146,8 @@ export function Pre({
           className: "frame",
           "data-frame": index,
           "data-lined": shouldRenderHast ? '' : undefined,
+          "data-frame-type": child.properties.dataFrameType ? String(child.properties.dataFrameType) : undefined,
+          "data-frame-indent": child.properties.dataFrameIndent != null ? String(child.properties.dataFrameIndent) : undefined,
           ref: observeFrame,
           children: renderCode(child.children, shouldRenderHast, child.properties?.dataAsString ? String(child.properties?.dataAsString) : undefined)
         }, index);