@globalpayments/vega 2.90.0 → 2.92.0

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/container-block-search-strategy.js

@@ -0,0 +1,23 @@
+import { RTETextNode } from '../../../../../../dto/nodes/text-node';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Fallback strategy for generic container blocks whose concrete type is not
+ * known at compile time (RTEHtmlBlock, table blocks, extension-defined blocks, …).
+ *
+ * A block is treated as a container when its children array is non-empty and
+ * the first child is not an RTETextNode (i.e. children are blocks, not nodes).
+ */
+export class ContainerBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return (block.children != null && block.children.length > 0 && !(block.children[0] instanceof RTETextNode));
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block, recurse) {
+    return recurse(block.children);
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/list-item-block-search-strategy.js

@@ -0,0 +1,30 @@
+import { RTEListItemBlock } from '../../../../../../dto/blocks/list-item-block';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Handles RTEListItemBlock — a searchable leaf block that may also carry
+ * nested RTEListBlocks via its `nestList` property.
+ *
+ * Must be registered before TextBlockSearchStrategy because RTEListItemBlock
+ * extends RTETextBlock and would otherwise be matched by the parent class check.
+ */
+export class ListItemBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return block instanceof RTEListItemBlock;
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block, recurse) {
+    const listItemBlock = block;
+    const result = [listItemBlock];
+    if (listItemBlock.nestList && listItemBlock.nestList.length > 0) {
+      for (const nestedList of listItemBlock.nestList) {
+        result.push(...recurse(nestedList.children));
+      }
+    }
+    return result;
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/text-block-search-strategy.js

@@ -0,0 +1,20 @@
+import { RTETextBlock } from '../../../../../../dto/blocks/text-block';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Handles plain RTETextBlock (paragraph, heading, etc.) — a searchable leaf
+ * block whose text lives in its RTETextNode children.
+ */
+export class TextBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return block instanceof RTETextBlock;
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block) {
+    return [block];
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/find-replace-highlight-manager.js

@@ -0,0 +1,266 @@
+import stateEntityRenderingRegistry from '../../../../../slimmers/controllers/state-entity-rendering-registry';
+import { tryGetDocument } from '../../../../../../../utils/try-get-document';
+import { RTECodeBlockNode } from '../../../../../dto/nodes/code-block-node';
+import { VegaDarkModeStyleController } from '../../../../../../../helpers/theme/controllers/dark-mode-style-controller';
+// Light-mode values (used as CSS var() fall-backs).
+// Dark-mode values are registered via VegaDarkModeStyleController below.
+const HIGHLIGHT_BG_LIGHT = '255, 220, 0, 0.35';
+const HIGHLIGHT_ACTIVE_BG_LIGHT = '255, 150, 0, 0.5';
+// Dark-mode: brighter yellow/orange tones stand out on dark backgrounds.
+const HIGHLIGHT_BG_DARK = '255, 235, 0, 0.55';
+const HIGHLIGHT_ACTIVE_BG_DARK = '255, 190, 0, 0.7';
+// CSS var() expressions that auto-switch between light and dark.
+const HIGHLIGHT_BG = `rgba(var(--v-rte-find-highlight-bg, ${HIGHLIGHT_BG_LIGHT}))`;
+const HIGHLIGHT_ACTIVE_BG = `rgba(var(--v-rte-find-highlight-active-bg, ${HIGHLIGHT_ACTIVE_BG_LIGHT}))`;
+/**
+ * Manages highlights for the Find & Replace extension using a DOM overlay.
+ *
+ * Instead of modifying the RTE content tree (which causes re-renders, cursor
+ * jumping, and VegaChange events), this manager renders semi-transparent
+ * highlight rectangles in an absolutely-positioned overlay container.
+ *
+ * The overlay lives inside `.rich-text-editor-container` (the RTE's scroll
+ * container) so highlight divs scroll naturally with the text content.
+ * `pointer-events: none` ensures highlights don't interfere with user
+ * interaction (selection, typing, clicking).
+ *
+ * Position computation uses `Range.getClientRects()` on the actual text DOM
+ * nodes (resolved via `stateEntityRenderingRegistry.getDOMByEntity`).
+ */
+export class FindReplaceHighlightManager {
+  constructor() {
+    this.overlayContainer = null;
+    // Register dark-mode overrides so `html.dark { --v-rte-find-highlight-*: ... }` is generated.
+    // CSS variables cascade into shadow DOM and update automatically when html.dark is toggled.
+    VegaDarkModeStyleController.registerCustomDarkModeColor({
+      'rte-find-highlight-bg': HIGHLIGHT_BG_DARK,
+      'rte-find-highlight-active-bg': HIGHLIGHT_ACTIVE_BG_DARK,
+      'rte-find-highlight-blend': 'lighten',
+    });
+  }
+  /**
+   * Renders highlight overlays for all matches, with the active match
+   * visually distinct. Clears any existing highlights before applying.
+   *
+   * @typedef HTMLVegaRichTextEditorElement - The type of the host rich text editor element.
+   * @param {ReadonlyArray<FindMatch>} matches - All search results.
+   * @param {number} currentIndex - 0-based index of the active match (-1 = none).
+   * @param {HTMLVegaRichTextEditorElement} host - The RTE host element.
+   * @param {boolean} scrollToActive - Whether to scroll the active highlight into view.
+   */
+  apply(matches, currentIndex, host, scrollToActive = true) {
+    this.clear();
+    if (matches.length === 0) {
+      return;
+    }
+    const overlay = this.getOrCreateOverlay(host);
+    if (overlay) {
+      const overlayRect = overlay.getBoundingClientRect();
+      let activeHighlightDiv = null;
+      matches.forEach((match, matchIndex) => {
+        const isActive = matchIndex === currentIndex;
+        const bg = isActive ? HIGHLIGHT_ACTIVE_BG : HIGHLIGHT_BG;
+        match.nodes.forEach((nodePosition) => {
+          const highlightDiv = this.createHighlightRectangles(overlay, overlayRect, nodePosition, bg);
+          if (isActive && !activeHighlightDiv && highlightDiv) {
+            activeHighlightDiv = highlightDiv;
+          }
+        });
+      });
+      if (scrollToActive && activeHighlightDiv) {
+        activeHighlightDiv.scrollIntoView({ block: 'center', inline: 'nearest' });
+      }
+    }
+  }
+  /**
+   * Removes all highlight overlay elements.
+   * Safe to call multiple times or when no highlights are active.
+   */
+  clear() {
+    if (this.overlayContainer) {
+      this.overlayContainer.innerHTML = '';
+    }
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────────
+  /**
+   * Gets the existing overlay container or creates one inside the RTE's
+   * scroll container (`.rich-text-editor-container`).
+   *
+   * @typedef HTMLVegaRichTextEditorElement - The type of the host rich text editor element.
+   * @param {HTMLVegaRichTextEditorElement} host - The RTE host element.
+   * @returns {HTMLDivElement | null} The overlay container, or null in SSR environments.
+   */
+  getOrCreateOverlay(host) {
+    if (this.overlayContainer && this.overlayContainer.isConnected) {
+      return this.overlayContainer;
+    }
+    const safeDocument = tryGetDocument();
+    if (safeDocument) {
+      const scrollContainer = host.shadowRoot.querySelector('.rich-text-editor-container');
+      if (scrollContainer) {
+        // The overlay is appended as the last child (paints above content).
+        // Blend mode is controlled via CSS variable --v-rte-find-highlight-blend:
+        //   - Light (default): multiply (yellow darkens white bg, text readable)
+        //   - Dark (via html.dark override): lighten (yellow visible on dark bg,
+        //     white text unaffected since lighten(255, x) = 255)
+        // CSS vars cascade into shadow DOM and react to theme switches instantly.
+        const overlay = safeDocument.createElement('div');
+        overlay.style.position = 'absolute';
+        overlay.style.top = '0';
+        overlay.style.left = '0';
+        overlay.style.width = '100%';
+        overlay.style.height = '100%';
+        overlay.style.pointerEvents = 'none';
+        overlay.style.overflow = 'visible';
+        overlay.style.setProperty('mix-blend-mode', 'var(--v-rte-find-highlight-blend, multiply)');
+        scrollContainer.appendChild(overlay);
+        this.overlayContainer = overlay;
+        return overlay;
+      }
+    }
+    return null;
+  }
+  /**
+   * Creates absolutely-positioned highlight rectangles for a single node
+   * position within a match.
+   *
+   * Uses client rectangle extraction from `Range` to handle multi-line matches (where a
+   * single text range may produce multiple rectangles due to line wrapping).
+   *
+   * @param {HTMLDivElement} overlay - The overlay container.
+   * @param {DOMRect} overlayRect - The overlay's bounding client rect (for coordinate conversion).
+   * @param {NodePosition} nodePosition - The node and character offsets for this segment.
+   * @param {string} bg - The background color to apply.
+   * @returns {Nullable<HTMLDivElement>} The first created highlight div for this node segment.
+   */
+  createHighlightRectangles(overlay, overlayRect, nodePosition, bg) {
+    const domElement = stateEntityRenderingRegistry.getDOMByEntity(nodePosition.node);
+    if (!domElement) {
+      return null;
+    }
+    const range = this.buildRange(domElement, nodePosition);
+    if (!range) {
+      return null;
+    }
+    // eslint-disable-next-line spellcheck/spell-checker -- DOM API method name is fixed by platform.
+    const clientRectList = range.getClientRects();
+    const safeDocument = tryGetDocument();
+    let firstHighlightDiv = null;
+    if (safeDocument) {
+      for (let i = 0; i < clientRectList.length; i++) {
+        const rect = clientRectList[i];
+        if (rect.width === 0 || rect.height === 0) {
+          continue;
+        }
+        const div = safeDocument.createElement('div');
+        div.style.position = 'absolute';
+        div.style.top = `${rect.top - overlayRect.top}px`;
+        div.style.left = `${rect.left - overlayRect.left}px`;
+        div.style.width = `${rect.width}px`;
+        div.style.height = `${rect.height}px`;
+        div.style.backgroundColor = bg;
+        div.style.pointerEvents = 'none';
+        div.style.borderRadius = '2px';
+        overlay.appendChild(div);
+        if (!firstHighlightDiv) {
+          firstHighlightDiv = div;
+        }
+      }
+    }
+    return firstHighlightDiv;
+  }
+  /**
+   * Builds a DOM Range for the given node position.
+   *
+   * For standard text nodes (RTETextNode rendered as `<span>`), the first
+   * child is a Text node and offsets apply directly.
+   *
+   * For code block nodes (`<vega-code-block>` with shadow DOM), we traverse
+   * the shadow root's `<code>` element child spans to locate the correct
+   * text positions by accumulated character offset.
+   *
+   * @param {HTMLElement} domElement - The registered DOM element for the node.
+   * @param {NodePosition} nodePosition - The character offsets within the node.
+   * @returns {Nullable<Range>} A Range if successfully built, or null on failure.
+   */
+  buildRange(domElement, nodePosition) {
+    // <vega-code-block> wraps syntax-highlighted tokens inside a shadow root <code> element.
+    if (nodePosition.node instanceof RTECodeBlockNode) {
+      return this.buildCodeBlockRange(domElement, nodePosition);
+    }
+    // Standard text node: <span> with a direct Text child.
+    const textNode = domElement.firstChild;
+    if (!textNode) {
+      return null;
+    }
+    const safeDocument = tryGetDocument();
+    if (safeDocument) {
+      const range = safeDocument.createRange();
+      try {
+        range.setStart(textNode, nodePosition.startOffset);
+        range.setEnd(textNode, nodePosition.endOffset);
+        return range;
+      }
+      catch (_a) {
+        return null;
+      }
+    }
+    return null;
+  }
+  /**
+   * Builds a Range inside a `<vega-code-block>` shadow DOM element.
+   *
+   * `<vega-code-block>` renders its content inside a shadow root with a `<code>`
+   * element containing multiple child `<span>` nodes (one per syntax token).
+   * This method walks all Text nodes within that `<code>` element, accumulating
+   * character length until the positions corresponding to startOffset / endOffset
+   * are found.
+   *
+   * @param {HTMLElement} domElement - The `<vega-code-block>` host element.
+   * @param {NodePosition} nodePosition - The character offsets within the node.
+   * @returns {Range | null} A Range if successfully built, or null on failure.
+   */
+  buildCodeBlockRange(domElement, nodePosition) {
+    const shadowRoot = domElement.shadowRoot;
+    const codeEl = shadowRoot.querySelector('code');
+    if (!codeEl) {
+      return null;
+    }
+    const safeDocument = tryGetDocument();
+    if (safeDocument) {
+      const walker = safeDocument.createTreeWalker(codeEl, NodeFilter.SHOW_TEXT);
+      let accumulated = 0;
+      let startNode = null;
+      let startLocal = 0;
+      let endNode = null;
+      let endLocal = 0;
+      let current = walker.nextNode();
+      while (current) {
+        const len = current.textContent.length;
+        if (!startNode && accumulated + len > nodePosition.startOffset) {
+          startNode = current;
+          startLocal = nodePosition.startOffset - accumulated;
+        }
+        if (accumulated + len >= nodePosition.endOffset) {
+          endNode = current;
+          endLocal = nodePosition.endOffset - accumulated;
+          break;
+        }
+        accumulated += len;
+        current = walker.nextNode();
+      }
+      if (startNode && endNode) {
+        const range = safeDocument.createRange();
+        try {
+          range.setStart(startNode, startLocal);
+          range.setEnd(endNode, endLocal);
+          return range;
+        }
+        catch (_a) {
+          return null;
+        }
+      }
+    }
+    return null;
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/find-replace-state.js

@@ -0,0 +1,346 @@
+import { RTECodeBlock } from '../../../../../dto/blocks/code-block';
+import { CodeBlockSearchStrategy } from './block-search-strategies/code-block-search-strategy';
+import { ListItemBlockSearchStrategy } from './block-search-strategies/list-item-block-search-strategy';
+import { TextBlockSearchStrategy } from './block-search-strategies/text-block-search-strategy';
+import { ContainerBlockSearchStrategy } from './block-search-strategies/container-block-search-strategy';
+/**
+ * Sentinel character inserted into the flat text in place of a non-editable
+ * node (e.g. a token). It keeps surrounding searchable segments from bridging
+ * across the removed node — producing false matches — while never matching any
+ * user keyword. `\u0000` (NULL) does not appear in editable document text.
+ */
+const NON_EDITABLE_SENTINEL = '\u0000';
+/**
+ * Manages the in-memory state for a single Find & Replace session.
+ *
+ * One instance is created per editor host inside VegaRTEFindReplaceExtension
+ * during `initialExtensionAfterLoad`. It holds all search results, the
+ * current navigation index, and a per-block flat-text cache.
+ *
+ * Public API:
+ * - `search(content, keyword)` — run a search, replace current state using current options
+ * - `next()` / `prev()` — navigate through results
+ * - `getCurrentMatch()` / `getMatches()` / `getTotal()` / `getCurrentIndex()` — read state
+ * - `clear()` — reset everything
+ */
+export class FindReplaceState {
+  constructor() {
+    this.matches = [];
+    this.currentIndex = -1;
+    this.flatCache = new WeakMap();
+    this.cachedContent = null;
+    this.matchCase = false;
+    this.wholeWords = false;
+    /**
+     * Ordered strategy chain used to classify and traverse each block type.
+     * More specific types (RTEListItemBlock) must precede their parent class (RTETextBlock).
+     */
+    this.blockSearchStrategies = [
+      new CodeBlockSearchStrategy(),
+      new ListItemBlockSearchStrategy(),
+      new TextBlockSearchStrategy(),
+      new ContainerBlockSearchStrategy(),
+    ];
+  }
+  /**
+   * Runs a fresh search over the given content and replaces all previous results.
+   *
+   * The flat-text cache is invalidated whenever the content reference changes
+   * (i.e. after the user edits the document). When only the keyword or options
+   * change (user typing in the find input), the cache is reused.
+   *
+   * @param {VegaRTEContent} content - The root content DTO to search.
+   * @param {string} keyword - The search keyword entered by the user.
+   * Uses the currently stored `matchCase` and `wholeWords` options.
+   */
+  search(content, keyword) {
+    this.invalidateCacheIfNeeded(content);
+    if (!keyword) {
+      this.matches = [];
+      this.currentIndex = -1;
+      return;
+    }
+    const regex = this.buildRegExp(keyword, this.getFindOptions());
+    const blocks = this.collectSearchableBlocks(content.children);
+    const results = [];
+    for (const block of blocks) {
+      let cached = this.flatCache.get(block);
+      if (!cached) {
+        cached =
+          block instanceof RTECodeBlock
+            ? this.buildCodeBlockFlat(block)
+            : this.buildTextBlockFlat(block);
+        this.flatCache.set(block, cached);
+      }
+      const { flatText, segments } = cached;
+      if (!flatText) {
+        continue;
+      }
+      regex.lastIndex = 0;
+      let match;
+      while ((match = regex.exec(flatText)) !== null) {
+        // match[1] is always the keyword capture group. In wholeWords mode,
+        // match[0] may include a leading non-letter boundary char, so we
+        // compute the actual start from the end offset minus the keyword length.
+        const matchEnd = match.index + match[0].length;
+        const matchStart = matchEnd - match[1].length;
+        const nodes = this.flatOffsetToNodePositions(segments, matchStart, matchEnd);
+        if (nodes.length > 0) {
+          results.push({ block, nodes, matchText: match[1] });
+        }
+      }
+    }
+    this.matches = results;
+    this.currentIndex = results.length > 0 ? 0 : -1;
+  }
+  /**
+   * Advances to the next match, wrapping around to the first.
+   */
+  next() {
+    if (this.matches.length === 0) {
+      return;
+    }
+    this.currentIndex = (this.currentIndex + 1) % this.matches.length;
+  }
+  /**
+   * Moves to the previous match, wrapping around to the last.
+   */
+  prev() {
+    if (this.matches.length === 0) {
+      return;
+    }
+    this.currentIndex = (this.currentIndex - 1 + this.matches.length) % this.matches.length;
+  }
+  /**
+   * Sets the current index directly. Clamps to valid range.
+   *
+   * @param {number} index - The desired index.
+   */
+  setCurrentIndex(index) {
+    if (this.matches.length === 0) {
+      this.currentIndex = -1;
+      return;
+    }
+    this.currentIndex = Math.max(0, Math.min(index, this.matches.length - 1));
+  }
+  /**
+   * Returns the currently active match, or null if there are no results.
+   *
+   * @returns {FindMatch | null} The currently active match, or null if there are no results.
+   */
+  getCurrentMatch() {
+    var _a;
+    return (_a = this.matches[this.currentIndex]) !== null && _a !== void 0 ? _a : null;
+  }
+  /**
+   * Returns all matches from the last search.
+   *
+   * @returns {ReadonlyArray<FindMatch>} All matches from the last search.
+   */
+  getMatches() {
+    return this.matches;
+  }
+  /**
+   * Returns the total number of matches from the last search.
+   *
+   * @returns {number} The total number of matches.
+   */
+  getTotal() {
+    return this.matches.length;
+  }
+  /**
+   * Returns the 0-based index of the current match, or -1 when there are no results.
+   *
+   * @returns {number} The 0-based index, or -1 when there are no results.
+   */
+  getCurrentIndex() {
+    return this.currentIndex;
+  }
+  /**
+   * Resets only match results and navigation index.
+   * The flat-text cache and cached content reference are preserved so that
+   * a subsequent search on the same document (e.g. after a keyword change)
+   * can reuse the already-computed block flat texts.
+   */
+  clearResults() {
+    this.matches = [];
+    this.currentIndex = -1;
+  }
+  /**
+   * Resets all search state, including results, navigation index, and flat-text cache.
+   * Use this when the session ends (e.g. panel closed) or the host changes.
+   */
+  clear() {
+    this.matches = [];
+    this.currentIndex = -1;
+    this.flatCache = new WeakMap();
+    this.cachedContent = null;
+  }
+  /**
+   * Sets the matchCase search option.
+   *
+   * @param {boolean} enabled - Whether to enable case-sensitive matching.
+   */
+  setMatchCase(enabled) {
+    this.matchCase = enabled;
+  }
+  /**
+   * Sets the wholeWords search option.
+   *
+   * @param {boolean} enabled - Whether to enable whole-word matching.
+   */
+  setWholeWords(enabled) {
+    this.wholeWords = enabled;
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────────
+  /**
+   * Invalidates the flat-text cache when the content reference has changed.
+   * Since flushChanges always produces a new VegaRTEContent via clone(), a
+   * changed reference reliably indicates the document has been edited.
+   *
+   * @param {VegaRTEContent} content - The incoming content reference.
+   */
+  invalidateCacheIfNeeded(content) {
+    if (content !== this.cachedContent) {
+      this.flatCache = new WeakMap();
+      this.cachedContent = content;
+    }
+  }
+  /**
+   * Builds a RegExp from the keyword and search options.
+   *
+   * @param {string} keyword - The raw user input.
+   * @param {FindOptions} options - Search options.
+   * @returns {RegExp} The compiled regular expression.
+   */
+  buildRegExp(keyword, options) {
+    const escaped = this.escapeRegExp(keyword);
+    // eslint-disable-next-line spellcheck/spell-checker
+    let flags = 'gu';
+    if (!options.matchCase) {
+      flags += 'i';
+    }
+    if (options.wholeWords) {
+      // Aligned with CKEditor's findByTextCallback non-letter boundary group.
+      //
+      // The keyword is wrapped in a capturing group (match[1]) so the search
+      // loop can compute the exact start offset without lookbehind assertions
+      // (not supported in Safari < 16.4). The non-capturing prefix group
+      // `(?:^|nonLetter)` may consume one boundary char, which is why we
+      // derive matchStart as matchEnd - match[1].length rather than match.index.
+      const nonLetter = '[^a-zA-Z\u00C0-\u024F\u1E00-\u1EFF]';
+      const prefix = !new RegExp(`^${nonLetter}`).test(keyword) ? `(?:^|${nonLetter})` : '';
+      const suffix = !new RegExp(`${nonLetter}$`).test(keyword) ? `(?=${nonLetter}|$)` : '';
+      return new RegExp(`${prefix}(${escaped})${suffix}`, flags);
+    }
+    return new RegExp(`(${escaped})`, flags);
+  }
+  /**
+   * Escapes all regex special characters so the keyword is treated as literal text.
+   *
+   * @param {string} text - The raw input string.
+   * @returns {string} The escaped string safe for use in a RegExp constructor.
+   */
+  escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  /**
+   * Recursively collects all searchable leaf blocks (RTETextBlock and RTECodeBlock)
+   * from a block tree in document order.
+   *
+   * Each block is dispatched to the first matching BlockSearchStrategy.
+   *
+   * @param {RTEBlock[]} blocks - The block array to traverse.
+   * @returns {(RTETextBlock | RTECodeBlock)[]} Ordered list of searchable leaf blocks.
+   */
+  collectSearchableBlocks(blocks) {
+    const result = [];
+    const recurse = this.collectSearchableBlocks.bind(this);
+    for (const block of blocks) {
+      const strategy = this.blockSearchStrategies.find((s) => s.canHandle(block));
+      if (strategy) {
+        result.push(...strategy.collect(block, recurse));
+      }
+    }
+    return result;
+  }
+  /**
+   * Builds the flat text and segment table for a RTETextBlock.
+   *
+   * Non-editable child nodes (e.g. tokens, which render as read-only chips)
+   * are excluded from the searchable flat text. Each is replaced by a single
+   * sentinel character so that adjacent editable segments cannot bridge across
+   * the token to form a false match, while keeping segment offsets aligned.
+   *
+   * @param {RTETextBlock} block - The text block to flatten.
+   * @returns {BlockFlatCache} The flat text string and segment mapping.
+   */
+  buildTextBlockFlat(block) {
+    const segments = [];
+    const flatParts = [];
+    let cursor = 0;
+    for (const node of block.children) {
+      if (!node.isContentEditable()) {
+        flatParts.push(NON_EDITABLE_SENTINEL);
+        cursor += NON_EDITABLE_SENTINEL.length;
+        continue;
+      }
+      const len = node.text.length;
+      segments.push({ node, start: cursor, end: cursor + len });
+      flatParts.push(node.text);
+      cursor += len;
+    }
+    return {
+      flatText: flatParts.join(''),
+      segments,
+    };
+  }
+  /**
+   * Builds the flat text and segment table for a RTECodeBlock.
+   *
+   * @param {RTECodeBlock} block - The code block to flatten.
+   * @returns {BlockFlatCache} The flat text string and segment mapping.
+   */
+  buildCodeBlockFlat(block) {
+    const codeNode = block.children[0];
+    if (!codeNode) {
+      return { flatText: '', segments: [] };
+    }
+    const flatText = codeNode.text;
+    return {
+      flatText,
+      segments: [{ node: codeNode, start: 0, end: flatText.length }],
+    };
+  }
+  /**
+   * Maps a flat [matchStart, matchEnd) range back to individual node positions.
+   *
+   * @param {(TextSegment | CodeSegment)[]} segments - The segment table.
+   * @param {number} matchStart - Inclusive start in the flat text.
+   * @param {number} matchEnd - Exclusive end in the flat text.
+   * @returns {NodePosition[]} Ordered list of node-local positions spanning the match.
+   */
+  flatOffsetToNodePositions(segments, matchStart, matchEnd) {
+    const positions = [];
+    for (const segment of segments) {
+      if (segment.end <= matchStart) {
+        continue;
+      }
+      if (segment.start >= matchEnd) {
+        break;
+      }
+      const localStart = Math.max(0, matchStart - segment.start);
+      const localEnd = Math.min(segment.end, matchEnd) - segment.start;
+      positions.push({ node: segment.node, startOffset: localStart, endOffset: localEnd });
+    }
+    return positions;
+  }
+  /**
+   * Builds the current find options from the shared context.
+   *
+   * @returns {FindOptions} The options for the search engine.
+   */
+  getFindOptions() {
+    return { matchCase: this.matchCase, wholeWords: this.wholeWords };
+  }
+}