fix(core): preserve markup around ranged highlights

Author: atomiks

.changeset/lucky-clocks-thank.md

@@ -4,4 +4,6 @@
 
 fix: stop character-highlight ranges leaking across patterns, so an id-only annotation like `/foo/#a` no longer makes a later pattern inherit the previous pattern's range, and a range-ignored occurrence no longer consumes the whole token it lives in (#169)
 
-Note that an occurrence a range excludes is now split into its own span rather than left inside the surrounding token, so the emitted HTML around character ranges changes even where the visible highlighting does not.
+Range-excluded occurrences are counted without changing the token tree, so unhighlighted markup remains intact.
+
+Partial highlights inside transformer-generated elements preserve the surrounding semantic element instead of cloning it.

packages/core/src/chars/charsHighlighter.ts

@@ -1,17 +1,70 @@
 import type { Element } from 'hast';
+import { toString as hastToString } from 'hast-util-to-string';
 import type { CharsHighlighterOptions, CharsElement } from '../types';
 import { getElementsToHighlight } from './getElementsToHighlight';
-import { wrapHighlightedChars } from './wrapHighlightedChars';
-import { isElement } from '../utils';
+import {
+  wrapHighlightedChars,
+  wrapHighlightedCharsInRange,
+} from './wrapHighlightedChars';
+
+interface SelectedMatch {
+  chars: string;
+  start: number;
+  end: number;
+  element?: CharsElement;
+}
+
+function isAvailable(occupied: Uint8Array, start: number, end: number) {
+  for (let index = start; index < end; index++) {
+    if (occupied[index] === 1) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function findMatches(
+  source: string,
+  chars: string,
+  charsIndex: number,
+  occupied: Uint8Array,
+  options: CharsHighlighterOptions,
+): Array<SelectedMatch> {
+  const selectedMatches: Array<SelectedMatch> = [];
+  const currentRange = options.ranges[charsIndex] || [];
+  const counterId = `${chars}-${charsIndex}`;
+  let searchStart = 0;
+
+  while (searchStart <= source.length - chars.length) {
+    const matchStart = source.indexOf(chars, searchStart);
+    if (matchStart === -1) {
+      break;
+    }
+
+    const matchEnd = matchStart + chars.length;
+    if (!isAvailable(occupied, matchStart, matchEnd)) {
+      searchStart = matchStart + 1;
+      continue;
+    }
+
+    const occurrence = (options.counterMap.get(counterId) || 0) + 1;
+    options.counterMap.set(counterId, occurrence);
+    occupied.fill(1, matchStart, matchEnd);
+
+    if (currentRange.length === 0 || currentRange.includes(occurrence)) {
+      selectedMatches.push({ chars, start: matchStart, end: matchEnd });
+    }
+
+    searchStart = matchEnd;
+  }
+
+  return selectedMatches;
+}
 
 /**
- * Loops through the child nodes and finds the nodes that make up the chars.
- * If the chars cross node boundaries, those nodes are wrapped with
- * <mark data-highlighted-chars-mark>, and that node is passed to
- * onVisitHighlightedChars.
- *
- * If a node partially matches the chars, its content is replaced with the
- * matched part, and the left and/or right parts are cloned to sibling nodes.
+ * Finds each requested string in the line, then applies the selected matches
+ * without materializing range-excluded occurrences.
  */
 export function charsHighlighter(
   element: Element,
@@ -22,50 +75,52 @@ export function charsHighlighter(
     id: string | undefined,
   ) => void,
 ) {
-  const { ranges = [] } = options;
+  const source = hastToString(element);
+  const occupied = new Uint8Array(source.length);
+  const selectedMatches: Array<SelectedMatch> = [];
 
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: char matching is inherently branchy
-  charsList.forEach((chars, index) => {
+  charsList.forEach((chars, charsIndex) => {
     if (!chars) {
       return;
     }
 
-    const currentCharsRange = ranges[index] || [];
-    const id = `${chars}-${index}`;
-    let startIndex = 0;
-
-    while (true) {
-      const elementsToWrap = getElementsToHighlight(element, chars, startIndex);
-
-      if (elementsToWrap.length === 0) break;
+    selectedMatches.push(
+      ...findMatches(source, chars, charsIndex, occupied, options),
+    );
+  });
 
-      const matchStartIndex = element.children.indexOf(elementsToWrap[0]);
-      if (matchStartIndex === -1) break;
+  const matchesToApply = [...selectedMatches].sort(
+    (first, second) => second.start - first.start,
+  );
 
-      const occurrence = (options.counterMap.get(id) || 0) + 1;
-      const ignoreChars =
-        currentCharsRange.length > 0 && !currentCharsRange.includes(occurrence);
+  for (const match of matchesToApply) {
+    const target = getElementsToHighlight(element, match.start, match.end);
+    if (!target) {
+      continue;
+    }
 
-      const didWrap = wrapHighlightedChars(
-        element,
-        elementsToWrap,
-        chars,
+    if (target.type === 'elements') {
+      match.element = wrapHighlightedChars(
+        target.parent,
+        target.elements,
+        match.chars,
+        options,
+      );
+    } else {
+      match.element = wrapHighlightedCharsInRange(
+        target.parent,
+        target.childIndex,
+        target.start,
+        target.end,
+        match.chars,
         options,
-        ignoreChars,
-        onVisitHighlightedChars,
       );
-
-      if (!didWrap) break;
-
-      options.counterMap.set(id, occurrence);
-      startIndex = matchStartIndex;
     }
-  });
+  }
 
-  element.children.forEach((childNode) => {
-    if (!isElement(childNode)) return;
-    if (Object.hasOwn(childNode.properties, 'rehype-pretty-code-visited')) {
-      childNode.properties['rehype-pretty-code-visited'] = undefined;
+  for (const match of selectedMatches) {
+    if (match.element) {
+      onVisitHighlightedChars?.(match.element, options.idsMap.get(match.chars));
     }
-  });
+  }
 }