@mui/internal-docs-infra 0.7.1-canary.1 → 0.7.1-canary.3

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.7.1-canary.1",
+  "version": "0.7.1-canary.3",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
+  "license": "MIT",
   "keywords": [
     "react",
     "react-component",
@@ -15,7 +16,6 @@
     "url": "git+https://github.com/mui/mui-public.git",
     "directory": "packages/docs-infra"
   },
-  "license": "MIT",
   "bugs": {
     "url": "https://github.com/mui/mui-public/issues"
   },
@@ -633,5 +633,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "9cb525c390188870205c3587ad12627e86bd5cda"
+  "gitSha": "ae05209d2cf5d9188b942dee401846b821f58130"
 }

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.mjs

@@ -1,3 +1,4 @@
+import { getHastTextContent } from "../loadServerTypes/hastTypeUtils.mjs";
 import { calculateFrameRanges } from "../parseSource/calculateFrameRanges.mjs";
 import { calculateFrameIndent } from "./calculateFrameIndent.mjs";
 import { restructureFrames } from "../parseSource/restructureFrames.mjs";
@@ -20,15 +21,32 @@ export const EMPHASIS_COMMENT_PREFIX = '@highlight';
  * @returns The extracted string (without quotes) or undefined if no quoted string found
  */
 function extractQuotedString(content) {
-  const match = content.match(/^["'](.*)["']$/);
+  const match = content.match(/^(["'])(.*)\1$/);
   if (match) {
-    return match[1];
+    return match[2];
   }
   // Also try to find quoted string anywhere in the content
-  const anyMatch = content.match(/["']([^"']+)["']/);
-  return anyMatch?.[1];
+  const anyMatch = content.match(/(["'])([^"']+)\1/);
+  return anyMatch?.[2];
 }
 
+/**
+ * Extracts all quoted strings from content.
+ * Supports both double quotes ("...") and single quotes ('...').
+ *
+ * @param content - The content to extract quoted strings from
+ * @returns Array of extracted strings (without quotes), empty if none found
+ */
+function extractAllQuotedStrings(content) {
+  const results = [];
+  const regex = /(["'])([^"']+)\1/g;
+  let match = regex.exec(content);
+  while (match) {
+    results.push(match[2]);
+    match = regex.exec(content);
+  }
+  return results;
+}
 /**
  * Extracts and removes the `@focus` keyword from content.
  *
@@ -61,7 +79,7 @@ function extractFocus(content) {
  * - 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: `@highlight-text "text to highlight"` or `@highlight-text "one" "two"`
  * - Text highlight focused: `@highlight-text @focus "text to highlight"`
  *
  * @param comments - Source comments keyed by line number
@@ -100,18 +118,18 @@ function parseEmphasisDirectives(comments) {
           focus
         });
       } else if (content.startsWith('-text')) {
-        // Text highlight: @highlight-text "text to highlight"
+        // Text highlight: @highlight-text "text" or @highlight-text "one" "two" "three"
         const afterText = content.slice('-text'.length).trim();
         const {
           focus,
           remaining: remainingText
         } = extractFocus(afterText);
-        const highlightText = extractQuotedString(remainingText);
-        if (highlightText) {
+        const highlightTexts = extractAllQuotedStrings(remainingText);
+        if (highlightTexts.length > 0) {
           directives.push({
             line,
             type: 'text',
-            highlightText,
+            highlightTexts,
             focus
           });
         }
@@ -179,21 +197,6 @@ function buildLineElementMap(node) {
   return map;
 }
 
-/**
- * Gets the text content of an element recursively.
- */
-function getElementText(element) {
-  let text = '';
-  for (const child of element.children || []) {
-    if (child.type === 'text') {
-      text += child.value;
-    } else if (child.type === 'element') {
-      text += getElementText(child);
-    }
-  }
-  return text;
-}
-
 /**
  * Checks if a line element contains only a comment with the given text.
  * A line is considered "comment-only" if it contains only whitespace, a .pl-c element,
@@ -222,7 +225,7 @@ function isCommentOnlyLine(lineElement, commentText) {
       const classNames = Array.isArray(className) ? className : [className];
       if (classNames.includes('pl-c')) {
         // This is a comment element - check if it contains the expected text
-        const text = getElementText(child);
+        const text = getHastTextContent(child);
         if (text.includes(commentText)) {
           hasMatchingComment = true;
         } else {
@@ -232,14 +235,14 @@ function isCommentOnlyLine(lineElement, commentText) {
       } else if (classNames.includes('pl-pse')) {
         // This is punctuation for special expressions (JSX braces for comments)
         // Check if it's just `{` or `}` which are used for JSX comment syntax
-        const text = getElementText(child);
+        const text = getHastTextContent(child);
         if (text !== '{' && text !== '}') {
           hasNonWhitespaceContent = true;
         }
         // Otherwise ignore - these are just JSX comment syntax
       } else {
         // Non-comment element - check if it has non-whitespace content
-        const text = getElementText(child);
+        const text = getHastTextContent(child);
         if (text.trim() !== '') {
           hasNonWhitespaceContent = true;
         }
@@ -272,14 +275,21 @@ function calculateEmphasizedLines(directives, lineElements) {
         description,
         strong,
         position: 'single',
+        lineHighlight: true,
         focus: directive.focus
       });
     } else if (directive.type === 'text') {
-      // Text highlight - emphasize specific text within the line
+      // Text highlight - emphasize specific text(s) within the line.
+      // Merge with any existing entry (e.g. when @highlight and @highlight-text
+      // map to the same line after comment removal).
+      const existing = emphasizedLines.get(directive.line);
+      // Concatenate highlight texts when multiple directives target the same line.
+      const mergedTexts = existing?.highlightTexts ? [...existing.highlightTexts, ...(directive.highlightTexts ?? [])] : directive.highlightTexts;
       emphasizedLines.set(directive.line, {
-        position: 'single',
-        highlightText: directive.highlightText,
-        focus: directive.focus
+        ...existing,
+        position: existing?.position ?? 'single',
+        highlightTexts: mergedTexts,
+        focus: directive.focus || existing?.focus
       });
     }
   }
@@ -325,16 +335,22 @@ function calculateEmphasizedLines(directives, lineElements) {
         // If this line is already emphasized (from an inner range), mark it as strong
         // since it's now nested inside multiple emphasis ranges, and preserve inner positions
         const meta = existing ? {
-          strong: true,
-          // Nested = always strong
+          // Nested ranges are strong unless the inner is a text highlight
+          strong: existing.highlightTexts ? strong : true,
           description: existing.description ?? (line === startLine ? description : undefined),
-          position: existing.position ?? position,
-          // Inner range position takes precedence
+          // Inner range position takes precedence, but 'single' from a standalone
+          // @highlight-text should be replaced by the multiline range's position
+          position: existing.position && existing.position !== 'single' ? existing.position : position,
+          highlightTexts: existing.highlightTexts,
+          // Preserve text highlights from @highlight-text
+          lineHighlight: true,
+          // Inside a multiline region = always line highlight
           focus: existing.focus || startDirective.focus
         } : {
           strong,
           description: line === startLine ? description : undefined,
           position,
+          lineHighlight: true,
           focus: startDirective.focus
         };
         emphasizedLines.set(line, meta);
@@ -345,65 +361,345 @@ function calculateEmphasizedLines(directives, lineElements) {
 }
 
 /**
- * Recursively wraps occurrences of a specific text within an element's children
- * with a span that has `data-hl` attribute.
+ * Like {@link getHastTextContent} but replaces any text inside a
+ * `data-hl` element with sentinel null characters so that those
+ * regions are invisible to the text search in `wrapTextInHighlightSpan`.
+ * This prevents nesting highlights when successive tokens overlap.
+ */
+function getSearchableText(node) {
+  if (node.type === 'text') {
+    return node.value;
+  }
+  if (node.type === 'element') {
+    if (node.properties?.dataHl !== undefined) {
+      return '\0'.repeat(getHastTextContent(node).length);
+    }
+    if (node.children) {
+      return node.children.map(getSearchableText).join('');
+    }
+  }
+  return '';
+}
+
+/**
+ * Injects a `data-hl` highlight span for a character range inside an
+ * element's children, without splitting the element itself.
+ * Used when a semantic element partially overlaps a match — the element
+ * stays intact and the highlight is placed inside it.
  *
- * @param children - The children array to process
- * @param textToHighlight - The text to find and wrap
- * @returns New children array with text wrapped in highlight spans
+ * Uses a plan-based approach (like {@link wrapTextInHighlightSpan}) to
+ * detect when the range produces multiple highlight fragments.  When the
+ * caller already provides a `part` value, every fragment inherits it.
+ * Otherwise, if multiple fragments are detected, `data-hl-part` values
+ * (`"start"`, `"middle"`, `"end"`) are computed locally.
+ *
+ * @param children - The children of the element to modify
+ * @param from - Start offset within the element's text content
+ * @param to - End offset within the element's text content
+ * @param part - Optional `data-hl-part` value inherited from the parent
  */
-function wrapTextInHighlightSpan(children, textToHighlight) {
-  const result = [];
-  for (const child of children) {
-    if (child.type === 'text') {
-      // Check if this text node contains the text to highlight
-      const text = child.value;
-      const index = text.indexOf(textToHighlight);
-      if (index !== -1) {
-        // Split the text and wrap the matched portion
-        const before = text.slice(0, index);
-        const after = text.slice(index + textToHighlight.length);
-        if (before) {
-          result.push({
-            type: 'text',
-            value: before
-          });
-        }
+function injectHighlightInChildren(children, from, to, part, strict, textToHighlight) {
+  const before = [];
+  const after = [];
+  const plan = [];
+  let currentGroup = [];
+  let offset = 0;
+  let pastRange = false;
+
+  // Precompute text lengths to avoid repeated recursive walks per child.
+  const childLengths = children.map(child => getHastTextContent(child).length);
+  function flushGroup() {
+    if (currentGroup.length > 0) {
+      plan.push({
+        kind: 'group',
+        nodes: currentGroup
+      });
+      currentGroup = [];
+    }
+  }
+  for (let i = 0; i < children.length; i += 1) {
+    const child = children[i];
+    const len = childLengths[i];
+    const childStart = offset;
+    const childEnd = offset + len;
+    offset = childEnd;
+    if (pastRange) {
+      after.push(child);
+      continue;
+    }
+    if (childEnd <= from) {
+      before.push(child);
+      continue;
+    }
+    if (childStart >= to) {
+      flushGroup();
+      after.push(child);
+      pastRange = true;
+      continue;
+    }
+    if (childStart >= from && childEnd <= to) {
+      currentGroup.push(child);
+      continue;
+    }
 
-        // Create highlighted span
-        result.push({
-          type: 'element',
-          tagName: 'span',
-          properties: {
-            dataHl: ''
-          },
-          children: [{
-            type: 'text',
-            value: textToHighlight
-          }]
+    // Straddling
+    const overlapFrom = Math.max(from, childStart) - childStart;
+    const overlapTo = Math.min(to, childEnd) - childStart;
+    if (child.type === 'text') {
+      const beforeText = child.value.slice(0, overlapFrom);
+      const matchedText = child.value.slice(overlapFrom, overlapTo);
+      const afterText = child.value.slice(overlapTo);
+      if (beforeText) {
+        flushGroup();
+        before.push({
+          type: 'text',
+          value: beforeText
         });
-        if (after) {
-          // Recursively process the remaining text in case there are more matches
-          const remainingChildren = wrapTextInHighlightSpan([{
-            type: 'text',
-            value: after
-          }], textToHighlight);
-          result.push(...remainingChildren);
-        }
+      }
+      if (matchedText) {
+        currentGroup.push({
+          type: 'text',
+          value: matchedText
+        });
+      }
+      if (afterText) {
+        flushGroup();
+        after.push({
+          type: 'text',
+          value: afterText
+        });
+        pastRange = true;
+      }
+    } else if (child.type === 'element' && child.children) {
+      // Nested element straddling — this is fragmentation across an element boundary
+      if (strict) {
+        throw new Error(`Base UI: @highlight-text "${textToHighlight}" straddles an element boundary. ` + 'In strict mode, highlighted text must not be fragmented across elements. ' + 'Adjust the highlighted text so it aligns with syntax token boundaries.');
+      }
+      flushGroup();
+      plan.push({
+        kind: 'inject',
+        element: child,
+        from: overlapFrom,
+        to: overlapTo
+      });
+      if (childEnd > to) {
+        pastRange = true;
+      }
+    } else {
+      currentGroup.push(child);
+    }
+  }
+  flushGroup();
+
+  // When the caller already supplied a part, every fragment inherits it.
+  // Otherwise, when multiple fragments exist, compute parts locally.
+  const needsParts = part === undefined && plan.length > 1;
+  const highlighted = [];
+  for (let i = 0; i < plan.length; i += 1) {
+    const item = plan[i];
+    let effectivePart = part;
+    if (needsParts) {
+      if (i === 0) {
+        effectivePart = 'start';
+      } else if (i === plan.length - 1) {
+        effectivePart = 'end';
       } else {
-        result.push(child);
+        effectivePart = 'middle';
+      }
+    }
+    if (item.kind === 'group') {
+      const props = {
+        dataHl: ''
+      };
+      if (effectivePart !== undefined) {
+        props.dataHlPart = effectivePart;
+      }
+      highlighted.push({
+        type: 'element',
+        tagName: 'span',
+        properties: props,
+        children: item.nodes
+      });
+    } else {
+      highlighted.push({
+        ...item.element,
+        children: injectHighlightInChildren(item.element.children, item.from, item.to, effectivePart, strict, textToHighlight)
+      });
+    }
+  }
+  return [...before, ...highlighted, ...after];
+}
+
+/**
+ * Wraps all occurrences of a specific text within a line's children in
+ * highlight spans with `data-hl`.
+ *
+ * Semantic element nodes (syntax-highlighting spans) are never split or
+ * cloned. When a match partially overlaps an element, the highlight span
+ * is injected *inside* the element via {@link injectHighlightInChildren}.
+ * When a match covers entire elements, a single wrapper `data-hl` span
+ * groups them all.
+ *
+ * If a match is fragmented (spans a partial element boundary), each
+ * fragment gets a `data-hl-part` attribute (`"start"`, `"middle"`, or
+ * `"end"`) so the segments can be styled together (e.g. border-radius).
+ *
+ * Already-highlighted nodes (`dataHl`) are excluded from matching so that
+ * successive calls for different tokens don't nest or double-highlight.
+ */
+function wrapTextInHighlightSpan(children, textToHighlight, strict) {
+  // Build searchable text, masking already-highlighted regions with sentinels.
+  const segments = children.map(getSearchableText);
+  const fullText = segments.join('');
+  const matchIndex = fullText.indexOf(textToHighlight);
+  if (matchIndex === -1) {
+    return children;
+  }
+  const matchEnd = matchIndex + textToHighlight.length;
+
+  // Classify each child relative to [matchIndex, matchEnd).
+  // "group" items are fully-contained nodes wrapped in a single data-hl span.
+  // "inject" items are elements that straddle a boundary — the highlight goes
+  // inside them, preserving the semantic element.
+
+  const before = [];
+  const after = [];
+  const plan = [];
+  let currentGroup = [];
+  let offset = 0;
+  let pastMatch = false;
+  function flushGroup() {
+    if (currentGroup.length > 0) {
+      plan.push({
+        kind: 'group',
+        nodes: currentGroup
+      });
+      currentGroup = [];
+    }
+  }
+  for (let i = 0; i < children.length; i += 1) {
+    const child = children[i];
+    const len = segments[i].length;
+    const childStart = offset;
+    const childEnd = offset + len;
+    offset = childEnd;
+    if (pastMatch) {
+      after.push(child);
+      continue;
+    }
+
+    // Entirely before match
+    if (childEnd <= matchIndex) {
+      before.push(child);
+      continue;
+    }
+
+    // Entirely after match
+    if (childStart >= matchEnd) {
+      flushGroup();
+      after.push(child);
+      pastMatch = true;
+      continue;
+    }
+
+    // Entirely within match
+    if (childStart >= matchIndex && childEnd <= matchEnd) {
+      currentGroup.push(child);
+      continue;
+    }
+
+    // Straddling a boundary
+    const overlapFrom = Math.max(matchIndex, childStart) - childStart;
+    const overlapTo = Math.min(matchEnd, childEnd) - childStart;
+    if (child.type === 'text') {
+      // Text nodes can be split freely — they carry no semantic class.
+      const beforeText = child.value.slice(0, overlapFrom);
+      const matchedText = child.value.slice(overlapFrom, overlapTo);
+      const afterText = child.value.slice(overlapTo);
+      if (beforeText) {
+        flushGroup();
+        before.push({
+          type: 'text',
+          value: beforeText
+        });
+      }
+      if (matchedText) {
+        currentGroup.push({
+          type: 'text',
+          value: matchedText
+        });
+      }
+      if (afterText) {
+        flushGroup();
+        after.push({
+          type: 'text',
+          value: afterText
+        });
+        pastMatch = true;
       }
     } else if (child.type === 'element' && child.children) {
-      // Recursively process element children
-      result.push({
-        ...child,
-        children: wrapTextInHighlightSpan(child.children, textToHighlight)
+      // Element nodes are never split — inject highlight inside them.
+      flushGroup();
+      plan.push({
+        kind: 'inject',
+        element: child,
+        from: overlapFrom,
+        to: overlapTo
+      });
+      if (childEnd > matchEnd) {
+        pastMatch = true;
+      }
+    } else {
+      currentGroup.push(child);
+    }
+  }
+  flushGroup();
+
+  // When multiple highlight pieces exist (due to element boundary straddling),
+  // mark each with data-hl-part so they can be styled as a group.
+  const needsParts = plan.length > 1;
+  if (strict && needsParts) {
+    throw new Error(`Base UI: @highlight-text "${textToHighlight}" straddles an element boundary. ` + 'In strict mode, highlighted text must not be fragmented across elements. ' + 'Adjust the highlighted text so it aligns with syntax token boundaries.');
+  }
+  const highlighted = [];
+  for (let i = 0; i < plan.length; i += 1) {
+    const item = plan[i];
+    let part;
+    if (needsParts) {
+      if (i === 0) {
+        part = 'start';
+      } else if (i === plan.length - 1) {
+        part = 'end';
+      } else {
+        part = 'middle';
+      }
+    }
+    if (item.kind === 'group') {
+      const props = {
+        dataHl: ''
+      };
+      if (part !== undefined) {
+        props.dataHlPart = part;
+      }
+      highlighted.push({
+        type: 'element',
+        tagName: 'span',
+        properties: props,
+        children: item.nodes
       });
     } else {
-      result.push(child);
+      const injectedChildren = injectHighlightInChildren(item.element.children, item.from, item.to, part, strict, textToHighlight);
+      highlighted.push({
+        ...item.element,
+        // Re-scan: the injected element may contain additional occurrences of the
+        // text beyond the just-highlighted region (e.g. repeated tokens in its tail).
+        children: wrapTextInHighlightSpan(injectedChildren, textToHighlight, strict)
+      });
     }
   }
-  return result;
+  return [...before, ...highlighted,
+  // Recursively process the remainder for additional occurrences
+  ...wrapTextInHighlightSpan(after, textToHighlight, strict)];
 }
 
 /**
@@ -416,7 +712,7 @@ function wrapTextInHighlightSpan(children, textToHighlight) {
  * @param emphasizedLines - Map of line numbers to their emphasis metadata
  * @returns Array of line elements that are highlighted, grouped by region
  */
-function applyEmphasisAndCollectHighlightedElements(node, emphasizedLines) {
+function applyEmphasisAndCollectHighlightedElements(node, emphasizedLines, options) {
   const highlightedLineElements = [];
   function traverse(n) {
     if (!('children' in n) || !n.children) {
@@ -433,10 +729,26 @@ function applyEmphasisAndCollectHighlightedElements(node, emphasizedLines) {
         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);
+          if (meta.highlightTexts) {
+            // For text highlight, wrap the specific text(s) in a span with data-hl
+            let children = child.children;
+            for (const text of meta.highlightTexts) {
+              children = wrapTextInHighlightSpan(children, text, options.strictHighlightText === true);
+            }
+            child.children = children;
+
+            // Only mark the line with data-hl when the line also has a line-level
+            // highlight (from @highlight, or from being inside a @highlight-start region).
+            // Standalone @highlight-text lines should not get line-level highlights.
+            if (meta.lineHighlight) {
+              child.properties.dataHl = meta.strong ? 'strong' : '';
+              if (meta.description) {
+                child.properties.dataHlDescription = meta.description;
+              }
+              if (meta.position) {
+                child.properties.dataHlPosition = meta.position;
+              }
+            }
           } else {
             // Use data-hl with optional "strong" value on the line
             child.properties.dataHl = meta.strong ? 'strong' : '';
@@ -585,7 +897,7 @@ export function createEnhanceCodeEmphasis(options = {}) {
     }
 
     // Step 4 (Traversal 2): Apply emphasis attributes AND collect highlighted elements
-    const highlightedElements = applyEmphasisAndCollectHighlightedElements(root, emphasizedLines);
+    const highlightedElements = applyEmphasisAndCollectHighlightedElements(root, emphasizedLines, options);
 
     // Step 5: Calculate indent levels per region (uses collected elements, no tree traversal)
     const regionIndentLevels = calculateRegionIndentLevels(highlightedElements, emphasizedLines);

package/pipeline/enhanceCodeTypes/enhanceChildren.mjs

@@ -1,3 +1,4 @@
+import { getHastTextContent } from "../loadServerTypes/hastTypeUtils.mjs";
 import { isLinkableSpan, isPropertySpan, isKeywordSpan, isCommentSpan, isSmiSpan, isStringLiteralSpan, getTextContent, getClassName, propPathToString } from "./hastUtils.mjs";
 import { createLinkElement, createPropRefElement, createParamRefElement, createValueRefElement } from "./createElements.mjs";
 import { currentOwner, buildPropHref, buildParamHref, finalizePendingDefaultExport, getResolvedValueExportAt, resetImportState, resetExportState, recordExport } from "./scanState.mjs";
@@ -1506,19 +1507,6 @@ function extractStringLiteralValue(node) {
   return `${quote}${raw}${quote}`;
 }
 
-/**
- * Recursively extracts all text content from an element, including nested elements.
- */
-function getDeepTextContent(node) {
-  if (node.type === 'text') {
-    return node.value;
-  }
-  if (node.type === 'element') {
-    return node.children.map(getDeepTextContent).join('');
-  }
-  return '';
-}
-
 /**
  * Checks whether a pl-s span is a template literal with interpolations.
  * Looks for a backtick pl-pds delimiter and pl-pse interpolation boundaries.
@@ -1601,7 +1589,7 @@ function extractTemplateLiteralTokens(node, state) {
 
     // Interpolation boundary: pl-pse wrapping `${` or `}`
     if (cls.includes('pl-pse')) {
-      const delimText = getDeepTextContent(child);
+      const delimText = getHastTextContent(child);
       if (delimText === '${') {
         inInterpolation = true;
         interpolationContentCount = 0;

package/pipeline/loadServerTypes/typeHighlighting.mjs

@@ -9,6 +9,7 @@
 import { unified } from 'unified';
 import transformHtmlCodeInline from "../transformHtmlCodeInline/index.mjs";
 import { starryNightGutter } from "../parseSource/addLineGutters.mjs";
+import { getHastTextContent } from "./hastTypeUtils.mjs";
 
 /**
  * Options for formatting inline types as HAST.
@@ -42,17 +43,6 @@ export function formatMultilineUnionHast(hast) {
   if (!codeElement || codeElement.type !== 'element') {
     return hast;
   }
-
-  // Helper to get text content from a node (needed for depth tracking)
-  const getTextContent = node => {
-    if (node.type === 'text') {
-      return node.value || '';
-    }
-    if (node.children) {
-      return node.children.map(getTextContent).join('');
-    }
-    return '';
-  };
   const children = codeElement.children || [];
 
   // Group children by top-level pipes (matching TableCode.tsx behavior)
@@ -62,7 +52,7 @@ export function formatMultilineUnionHast(hast) {
   let angleDepth = 0;
   let groupIndex = 0;
   children.forEach((child, index) => {
-    const nodeText = getTextContent(child);
+    const nodeText = getHastTextContent(child);
 
     // Track depth changes
     for (const char of nodeText) {

package/pipeline/parseSource/calculateFrameRanges.d.mts

@@ -8,10 +8,12 @@ export interface EmphasisMeta {
   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;
+  /** For text highlighting: the specific texts to highlight within the line */
+  highlightTexts?: string[];
   /** Whether this line's region is the focused region (for padding) */
   focus?: boolean;
+  /** Whether the line itself should receive data-hl (from @highlight or multiline region) */
+  lineHighlight?: boolean;
 }
 /**
  * A range of lines that forms a frame in the output.
@@ -41,6 +43,13 @@ export interface EnhanceCodeEmphasisOptions {
    * padding-top and ceil(remainder/2) for padding-bottom.
    */
   focusFramesMaxSize?: number;
+  /**
+   * When `true`, throws an error if a `@highlight-text` match has to be
+   * fragmented across element boundaries (producing `data-hl-part` spans).
+   * Wrapping multiple complete elements in a single `data-hl` span is still
+   * allowed — only boundary-straddling matches are rejected.
+   */
+  strictHighlightText?: boolean;
 }
 /**
  * Calculates frame ranges for the code block based on emphasized lines.

package/pipeline/parseSource/createFrame.mjs

@@ -6,7 +6,8 @@
  */
 export function createFrame(children, startLine, endLine, frameType, indentLevel) {
   const properties = {
-    className: 'frame'
+    className: 'frame',
+    dataLined: ''
   };
   if (startLine !== undefined && endLine !== undefined) {
     properties.dataFrameStartLine = startLine;

package/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.mjs

@@ -1,4 +1,5 @@
 import { visit } from 'unist-util-visit';
+import { getHastTextContent } from "../loadServerTypes/hastTypeUtils.mjs";
 import { loadCodeVariant } from "../loadCodeVariant/loadCodeVariant.mjs";
 import { createParseSource } from "../parseSource/index.mjs";
 import { TypescriptToJavascriptTransformer } from "../transformTypescriptToJavascript/index.mjs";
@@ -99,25 +100,15 @@ const JSX_LANGUAGES = new Set(['jsx', 'tsx']);
  * from MDX parsing. If the source ends with `>;`, the trailing `;` is removed.
  */
 function stripJsxExpressionSemicolon(source) {
+  if (source.endsWith('>;\n')) {
+    return source.slice(0, -2);
+  }
   if (source.endsWith('>;')) {
     return source.slice(0, -1);
   }
   return source;
 }
 
-/**
- * Extracts text content from HAST nodes
- */
-function extractTextContent(node) {
-  if (node.type === 'text') {
-    return node.value;
-  }
-  if (node.type === 'element' && node.children) {
-    return node.children.map(child => extractTextContent(child)).join('');
-  }
-  return '';
-}
-
 /**
  * Extracts code elements and filenames from semantic HTML structure
  * Handles both section/figure/dl and standalone dl structures
@@ -254,7 +245,7 @@ export const transformHtmlCodeBlock = () => {
 
             // Process each extracted element to extract comments and prepare variants
             const processElementForVariant = async (codeElement, filename, language, explicitVariantName, index) => {
-              let sourceCode = extractTextContent(codeElement);
+              let sourceCode = getHastTextContent(codeElement);
               const derivedFilename = filename || getFileName(codeElement);
 
               // Strip trailing semicolon from JSX expressions