@samuelbradshaw/highlight-helper-js 0.9.0 → 1.0.0

package/highlight-helper.js

@@ -3,1100 +3,1340 @@
  * https://github.com/samuelbradshaw/highlight-helper-js
  */
 
-'use strict';
+(function () {
+  'use strict';
 
-/********************** Highlighter Initialization **********************/
+  /********************** Highlighter Initialization **********************/
 
-function Highlighter(options = _defaultOptions) {
-  for (const key of Object.keys(_defaultOptions)) {
-    options[key] = options[key] ?? _defaultOptions[key];
-  }
-  this._options = options;
-
-  // DOM references
-  this._annotatableContainer = null;
-  this._relativeAncestorElement = null;
-  this._annotatableParagraphs = null;
-  this._svgBackground = null;
-  this._svgActiveOverlay = null;
-  this._selectionHandles = null;
-
-  // Stylesheets
-  this._stylesheets = null;
-  this._generalStylesheet = null;
-  this._appearanceStylesheet = null;
-  this._highlightApiStylesheet = null;
-  this._selectionStylesheet = null;
-
-  // Data and state
-  this._annotatableParagraphIds = null;
-  this._hyperlinkElements = null;
-  this._hyperlinksByPosition = null;
-  this._highlightsById = null;
-
-  // Abort controller
-  this._controller = null;
-
-  const isInitialized = this._initializeHighlighter();
-  if (!isInitialized) return;
-
-  // Interaction state
-  this._activeHighlightId = undefined;
-  this._previousSelectionRange = undefined;
-  this._activeSelectionHandle = undefined;
-  this._dragAnchorNode = undefined;
-  this._dragAnchorOffset = undefined;
-  this._pointerType = undefined;
-  this._tapResult = undefined;
-  this._doubleTapTimeoutId = undefined;
-  this._longPressTimeoutId = undefined;
-  this._allowHyperlinkClick = false;
-
-  this._loadStyles();
-  this._loadEventListeners();
-
-  this._updateAppearanceStylesheet();
-  this._updateSelectionUi('appearance');
-  this.setOption('selectionHandles', this._options.selectionHandles);
-}
-
-Highlighter.prototype._initializeHighlighter = function (previousContainerSelector = null) {
-  const options = this._options;
-  if (!options.paragraphSelector.includes(options.containerSelector)) {
-    const paragraphSelectorList = options.paragraphSelector.split(',').map(selector => `${options.containerSelector} ${selector}`);
-    options.paragraphSelector = paragraphSelectorList.join(',');
-  }
-  this._annotatableContainer = document.querySelector(options.containerSelector);
-  this._annotatableParagraphs = this._annotatableContainer.querySelectorAll(options.paragraphSelector);
-  this._annotatableParagraphIds = Array.from(this._annotatableParagraphs, paragraph => paragraph.id);
-
-  // Handle cases where a highlighter already exists for the container, or one of its children or ancestors
-  const previousContainer = document.querySelector(previousContainerSelector) ?? this._annotatableContainer;
-  if (previousContainer.highlighter) {
-    previousContainer.highlighter.removeHighlighter();
-  } else if (this._annotatableContainer.closest('[data-hh-container]') || this._annotatableContainer.querySelector('[data-hh-container]')) {
-    console.error(`Unable to create Highlighter with container selector "${options.containerSelector}" (annotatable container can't be an child or ancestor of another annotatable container).`);
-    return false;
-  }
+  function Highlighter(containerSelector = 'body', paragraphSelector = ':is(h1, h2, h3, h4, h5, h6, p, ol, ul, dl)[id]') {
+    this._options = structuredClone(_defaultOptions);
 
-  // Get the closest ancestor element with `position: relative`, or the root element (this is used to calculate the position of selection handles and SVG highlights)
-  let ancestorElement = this._annotatableContainer;
-  while (ancestorElement) {
-    if (ancestorElement === document.documentElement || globalThis.getComputedStyle(ancestorElement).position === 'relative') {
-      this._relativeAncestorElement = ancestorElement;
-      break;
+    // Load container
+    this._containerSelector = containerSelector;
+    this._container = document.querySelector(containerSelector);
+    if (!this._container) {
+      return console.error(`Unable to create Highlighter with container selector "${containerSelector}" (element not found).`);
     }
-    ancestorElement = ancestorElement.parentElement;
-  }
 
-  // Abort controller can be used to cancel event listeners if the highlighter is removed
-  this._controller = new AbortController;
-
-  // Setting tabIndex -1 on <body> allows focus to be set programmatically (needed to initialize text selection in iOS Safari). It also prevents "tap to search" from interfering with text selection in Android Chrome.
-  document.body.tabIndex = -1;
-
-  // Set up SVG background and selection handles
-  this._svgBackground = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
-  this._svgActiveOverlay = document.createElementNS('http://www.w3.org/2000/svg', 'g');
-  this._svgActiveOverlay.dataset.activeOverlay = '';
-  this._svgBackground.appendChild(this._svgActiveOverlay);
-  this._svgBackground.classList.add('hh-svg-background');
-  this._annotatableContainer.appendChild(this._svgBackground);
-  this._annotatableContainer.insertAdjacentHTML('beforeend', `
-    <div class="hh-selection-handle" data-side="left" data-position="start" data-hh-ignore=""><div draggable="true"></div><div class="hh-selection-handle-content"></div></div>
-    <div class="hh-selection-handle" data-side="right" data-position="end" data-hh-ignore=""><div draggable="true"></div><div class="hh-selection-handle-content"></div></div>
-  `);
-  this._selectionHandles = this._annotatableContainer.getElementsByClassName('hh-selection-handle');
-
-  // Check for hyperlinks on the page
-  this._hyperlinkElements = this._annotatableContainer.getElementsByTagName('a');
-  this._hyperlinksByPosition = {}
-  for (let hyp = 0; hyp < this._hyperlinkElements.length; hyp++) {
-    this._hyperlinksByPosition[hyp] = {
-      'position': hyp,
-      'text': this._hyperlinkElements[hyp].innerHTML,
-      'url': this._hyperlinkElements[hyp].href,
-      'hyperlinkElement': this._hyperlinkElements[hyp],
+    // Handle cases where a highlighter already exists for the container, or one of its children or ancestors
+    if (this._container.highlighter) {
+      this._container.highlighter.removeHighlighter();
+    } else if (this._container.closest('[data-hh-container]') || this._container.querySelector('[data-hh-container]')) {
+      return console.error(`Unable to create Highlighter with container selector "${containerSelector}" (annotatable container can't be a child or ancestor of another annotatable container).`);
     }
-  }
 
-  this._highlightsById = {};
-  this._annotatableContainer.dataset.hhContainer = '';
-  this._annotatableContainer.highlighter = this;
-  _highlighters.push(this);
-
-  return true;
-}
-
-Highlighter.prototype._loadStyles = function () {
-  const options = this._options;
-
-  // Set up stylesheets
-  this._stylesheets = {}
-  this._generalStylesheet = addStylesheet(this._stylesheets, 'general');
-  this._appearanceStylesheet = addStylesheet(this._stylesheets, 'appearance');
-  this._highlightApiStylesheet = addStylesheet(this._stylesheets, 'highlight-api');
-  this._selectionStylesheet = addStylesheet(this._stylesheets, 'selection');
-  this._generalStylesheet.replaceSync(`
-    ${options.containerSelector} {
-      -webkit-tap-highlight-color: transparent;
-    }
-    .hh-wrapper-start, .hh-wrapper-end, .hh-selection-handle {
-      -webkit-user-select: none;
-      user-select: none;
-    }
-    .hh-selection-handle {
-      position: absolute;
-      width: 0px;
-      visibility: hidden;
-    }
-    [data-hh-pointer-down="true"] .hh-selection-handle {
-      visibility: hidden !important;
-    }
-    .hh-selection-handle-content {
-      position: absolute;
-      height: 100%;
-    }
-    .hh-selection-handle [draggable] {
-      position: absolute;
-      top: -0.3em;
-      width: 3.2em;
-      height: calc(100% + 1.3em);
-      background-color: transparent;
-      z-index: 1;
-    }
-    .hh-selection-handle[data-side="left"] [draggable] { right: -2em; }
-    .hh-selection-handle[data-side="right"] [draggable] { left: -2em; }
-    .hh-default-handle {
-      position: absolute;
-      width: 0.8em;
-      height: min(1.2em, 100%);
-      background-color: hsl(from var(--hh-color) h 80% 40% / 1);
-      outline: 0.1em solid hsla(0, 0%, 100%, 0.8);
-      outline-offset: -0.05em;
-      bottom: -0.2em;
-    }
-    .hh-selection-handle[data-side="left"] .hh-default-handle {
-      right: 0;
-      border-radius: 1em 0 0.6em 0.6em;
-    }
-    .hh-selection-handle[data-side="right"] .hh-default-handle {
-      left: 0;
-      border-radius: 0 1em 0.6em 0.6em;
-    }
-    .hh-svg-background {
-      position: absolute;
-      top: 0;
-      left: 0;
-      width: 100%;
-      overflow: visible;
-      z-index: -1;
-    }
-    .hh-svg-background g {
-      fill: transparent;
-      stroke: none;
-    }
-    mark[data-highlight-id] {
-      background-color: transparent;
-      color: inherit;
-    }
-  `);
-}
-
-Highlighter.prototype._loadEventListeners = function () {
-  const options = this._options;
-
-  // Selection change in document (new selection, change in selection range, or selection collapsing to a caret)
-  const respondToSelectionChange = (event) => {
-    const selection = this._getRestoredSelectionOrCaret(globalThis.getSelection());
-    const selectionRange = selection.type === 'None' ? null : selection.getRangeAt(0);
+    // Load annotatable paragraphs
+    this._paragraphSelector = paragraphSelector;
+    this._paragraphIds = [];
+    this._paragraphs = Array.from(this._container.querySelectorAll(paragraphSelector));
+    for (const paragraph of this._paragraphs) {
+      if (!paragraph.id) {
+        return console.error(`Unable to create Highlighter with paragraph selector "${paragraphSelector}" (each selected paragraph must have a valid ID).`);
+      } else if (this._paragraphIds.includes(paragraph.id)) {
+        return console.error(`Unable to create Highlighter with paragraph selector "${paragraphSelector}" (each selected paragraph's ID must be unique).`);
+      }
+      this._paragraphIds.push(paragraph.id);
+    }
 
-    // In "Mac (Designed for iPad)" apps (iPad app running on macOS – most recently tested with macOS Sequoia 15.3.1), in-app webviews have several quirks related to text selection. One of these is text selection collapsing to a caret more often than expected. This code attempts to restore the previous selection range if it unexpectedly collapses to a caret in these scenarios:
-    // 1. While dragging custom selection handles (happens randomly). TODO: Dragging custom selection handles in this environment is still sometimes a little jumpy.
-    // 2. Just after clicking to activate a highlight (happens if it's the first click after the page loads).
-    if (isWKWebView && !isTouchDevice && selection.type !== 'Range' && this._previousSelectionRange && (this._activeSelectionHandle || (this._previousSelectionRange.compareBoundaryPoints(Range.END_TO_START, selectionRange) <= 0 && this._previousSelectionRange.compareBoundaryPoints(Range.END_TO_END, selectionRange) >= 0))) {
-      selection.setBaseAndExtent(this._previousSelectionRange.startContainer, this._previousSelectionRange.startOffset, this._previousSelectionRange.endContainer, this._previousSelectionRange.endOffset);
+    // Abort controller can be used to cancel event listeners if the highlighter is removed
+    this._controller = new AbortController();
+
+    // Setting tabIndex -1 on <body> allows focus to be set programmatically (needed to initialize text selection in iOS Safari). It also prevents "tap to search" from interfering with text selection in Android Chrome.
+    document.body.tabIndex = -1;
+
+    // Set up additions (SVG background and selection handles)
+    this._container.insertAdjacentHTML('beforeend', `
+      <div data-hh-additions="">
+        <svg data-hh-svg-background=""><g data-hh-svg-active-overlay=""></g></svg>
+        <div data-hh-handle="" data-hh-side="left" data-hh-position="start" data-hh-ignore=""><div draggable="true"></div><div data-hh-handle-content=""></div></div>
+        <div data-hh-handle="" data-hh-side="right" data-hh-position="end" data-hh-ignore=""><div draggable="true"></div><div data-hh-handle-content=""></div></div>
+      </div>
+    `);
+    this._additionsDiv = this._container.querySelector('[data-hh-additions]');
+    this._svgBackground = this._additionsDiv.querySelector('[data-hh-svg-background]');
+    this._svgActiveOverlay = this._additionsDiv.querySelector('[data-hh-svg-active-overlay]');
+    this._dragHandles = this._additionsDiv.querySelectorAll('[data-hh-handle]');
+
+    // Check for hyperlinks on the page
+    this._hyperlinkElements = this._container.getElementsByTagName('a');
+    this._hyperlinksByIndex = {}
+    for (let hyp = 0; hyp < this._hyperlinkElements.length; hyp++) {
+      const hyperlink = this._hyperlinkElements[hyp];
+      hyperlink.dataset.hhIndex = hyp;
+      this._hyperlinksByIndex[hyp] = {
+        'index': hyp,
+        'text': hyperlink.innerHTML,
+        'url': hyperlink.href,
+        'hyperlinkElement': hyperlink,
+      }
     }
 
-    // Deactivate highlights when tapping or creating a selection outside of the previous selection range
-    if (!this._activeSelectionHandle && this._previousSelectionRange && (selection.type !== 'Range' || this._previousSelectionRange.comparePoint(selectionRange.startContainer, selectionRange.startOffset) === 1 || this._previousSelectionRange.comparePoint(selectionRange.endContainer, selectionRange.endOffset) === -1)) {
-      this.deactivateHighlights(false);
+    this._highlightsById = {};
+    this._wrapperElements = new Map();
+    this._container.dataset.hhContainer = '';
+    this._container.highlighter = this;
+    this._selectionState = {
+      activeHighlightId: null,
+      color: null,
+      style: null,
+      isResizing: false,
+      pointerType: null,
+      selection: globalThis.getSelection(),
+      changes: [],
+      rangeText: null,
+      rangeHtml: null,
+      rangeRect: null,
+      rangeLineRects: [],
+      rangeParagraphIds: null,
+      rangeObj: null,
+    };
+    this._isResizingSelection = false;
+    this._previousBoundsHash = null;
+    this._containerRect = null;
+    this._additionsRect = null;
+
+    this._loadStyles();
+    this._loadEventListeners();
+    this._updateColorStylesheet();
+    this._updateSelectionState();
+    for (const handle of this._dragHandles) {
+      handle.children[1].innerHTML = this._options.dragHandles[handle.dataset.hhSide] ?? '';
     }
+  }
 
-    if (selection.type === 'Range') {
-      // Clear tap result (prevents hh:tap event from being sent when long-pressing or dragging to select text)
-      this._tapResult = null;
+  Highlighter.prototype._loadStyles = function () {
+    // Set up stylesheets
+    this._stylesheets = {}
+    this._generalStylesheet = _addStylesheet(this._stylesheets, 'general');
+    this._colorStylesheet = _addStylesheet(this._stylesheets, 'color');
+    this._highlightStylesheet = _addStylesheet(this._stylesheets, 'highlight');
+    this._selectionStylesheet = _addStylesheet(this._stylesheets, 'selection');
+    this._generalStylesheet.replaceSync(`
+      ${this._containerSelector} {
+        -webkit-tap-highlight-color: transparent;
+      }
+      [data-hh-wrapper], [data-hh-additions], rt {
+        /* Disable selection on elements in the container that might be absolutely-positioned (reduces jumpy selection) */
+        -webkit-user-select: none;
+        user-select: none;
+      }
+      [data-hh-handle] {
+        position: absolute;
+        width: 0px;
+        visibility: hidden;
+      }
+      [data-hh-pointer-down="true"] [data-hh-handle] {
+        /* Hiding selection handle reduces jumpiness when dragging (and makes it easier to see the selection) */
+        visibility: hidden !important;
+      }
+      [data-hh-handle-content] {
+        position: absolute;
+        height: 100%;
+      }
+      [data-hh-handle] [draggable] {
+        position: absolute;
+        top: -0.3em;
+        width: 3.2em;
+        height: calc(100% + 1.3em);
+        background-color: transparent;
+        z-index: 1;
+      }
+      [data-hh-handle][data-hh-side="left"] [draggable] { right: -2em; }
+      [data-hh-handle][data-hh-side="right"] [draggable] { left: -2em; }
+      [data-hh-default-handle] {
+        position: absolute;
+        width: 0.8em;
+        height: min(1.2em, 100%);
+        background-color: hsl(from var(--hh-color) h 80% 40% / 1);
+        outline: 0.1em solid hsla(0, 0%, 100%, 0.8);
+        outline-offset: -0.05em;
+        bottom: -0.2em;
+      }
+      [data-hh-handle][data-hh-side="left"] [data-hh-default-handle] {
+        right: 0;
+        border-radius: 1em 0 0.6em 0.6em;
+      }
+      [data-hh-handle][data-hh-side="right"] [data-hh-default-handle] {
+        left: 0;
+        border-radius: 0 1em 0.6em 0.6em;
+      }
+      [data-hh-additions] {
+        position: absolute;
+        top: 0; left: 0;
+        overflow: visible;
+      }
+      [data-hh-svg-background] {
+        position: absolute;
+        top: 0; left: 0;
+        /* In mobile Chrome and Safari, if a user drags a text selection handle up to the very top of the page, it gets caught by the SVG background, causing text selection to jump to the bottom of the page. Setting pointer-events to none prevents this. */
+        pointer-events: none;
+        overflow: visible;
+        z-index: -1;
+      }
+      [data-hh-svg-background] g {
+        fill: transparent;
+        stroke: none;
+      }
+      mark[data-hh-highlight-id] {
+        print-color-adjust: exact;
+        background-color: transparent;
+        color: inherit;
+      }
+      .sr-only {
+        position: absolute;
+        width: 1px; height: 1px;
+        padding: 0; margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+      }
+    `);
+  }
+
+  Highlighter.prototype._loadEventListeners = function () {
+    const options = this._options;
+
+    // Selection change in document (new selection, change in selection range, or selection collapsing to a caret)
+    const respondToSelectionChange = (event) => {
+      const selection = this._getRestoredSelectionOrCaret(globalThis.getSelection());
+      const selectionRange = selection.type === 'None' ? null : selection.getRangeAt(0);
+      const selectionContainer = this._getSelectionContainer();
+      const selectionInThisContainer = selectionContainer === this._container;
+      const selectionInOtherContainer = selectionContainer !== null && !selectionInThisContainer;
+      if (selectionInOtherContainer) return;
+
+      // If the selection collapses to a caret inside the previous selection range, restore the range. This handles:
+      // 1. "Mac (Designed for iPad)" in-app webviews collapsing the selection just after clicking to activate a highlight, or randomly while dragging custom handles.
+      // 2. Android Chrome collapsing the selection when the user taps a form control (e.g. a <select>) outside the container while a highlight is active.
+      if (this._previousSelectionRange && selection.type === 'Caret') {
+        const caret = selectionRange;
+        const isCaretInPreviousRange = this._previousSelectionRange.comparePoint(caret.startContainer, caret.startOffset) === 0;
+        if (this._activeHandle || isCaretInPreviousRange) {
+          return this._restorePreviousSelectionRange();
+        }
+      }
+
+      // Mitigate a bug in Chrome (desktop and Android) where dragging a selection past the viewport edge jumps to everything before or after the selection anchor
+      if (this._previousSelectionRange && selection.focusNode.nodeType !== Node.TEXT_NODE) {
+        return this._restorePreviousSelectionRange();
+      }
 
-      if (this._annotatableContainer.contains(selection.anchorNode)) {
-        if (this._activeHighlightId || (options.pointerMode === 'live' || (options.pointerMode === 'auto' && this._pointerType === 'pen'))) {
-          this.createOrUpdateHighlight({ highlightId: this._activeHighlightId, });
+      // If the user taps away or creates a new selection range outside of the previous selection range, deactivate any active highlights (but don't clear the selection range that was just created)
+      this._detectSelectionResize(this._previousSelectionRange, selectionRange, selection.type);
+      if (!this._activeHandle && !this._isResizingSelection && this._previousSelectionRange) {
+        const isSelectionOutsidePreviousRange =
+          this._previousSelectionRange.comparePoint(selectionRange.startContainer, selectionRange.startOffset) === 1 ||
+          this._previousSelectionRange.comparePoint(selectionRange.endContainer, selectionRange.endOffset) === -1;
+        if (selection.type !== 'Range' || isSelectionOutsidePreviousRange) {
+          this.deactivateHighlights(false);
         }
-        this._previousSelectionRange = selectionRange.cloneRange();
       }
+
+      if (selection.type === 'Range') {
+        // Clear tap result (prevents hh:tap event from being sent when long-pressing or dragging to select text)
+        this._tapResult = null;
+
+        if (selectionInThisContainer) {
+          if (this._activeHighlightId) {
+            this.createOrUpdateHighlight({ highlightId: this._activeHighlightId });
+          }
+
+          const anchorCaret = new Range();
+          anchorCaret.setStart(selection.anchorNode, selection.anchorOffset);
+          anchorCaret.collapse(true);
+          this._previousSelectionDirection = anchorCaret.comparePoint(selection.focusNode, selection.focusOffset) === 1 ? 'forward' : 'backward';
+          this._previousSelectionRange = selectionRange.cloneRange();
+        }
+      }
+
+      this._updateSelectionState();
     }
+    document.addEventListener('selectionchange', (event) => respondToSelectionChange(event), { signal: this._controller.signal });
+
+    // Pointer down in container
+    const respondToPointerDown = (event) => {
+      const isSecondaryClick = (event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey);
+      if (!isSecondaryClick) this._container.dataset.hhPointerDown = 'true';
+      this._pointerType = event.pointerType;
+
+      // Pointer down on a selection handle
+      if (event.target?.closest('[data-hh-handle]')) {
+        if (!isSecondaryClick) {
+          this._activeHandle = event.target.parentElement.closest('[data-hh-handle]');
+          const handleClientRect = this._activeHandle.getBoundingClientRect();
+          const lineHeight = handleClientRect.bottom - handleClientRect.top;
+          this._activeHandle.dataset.hhDragYOffset = Math.max(0, event.clientY - handleClientRect.bottom + (lineHeight / 6));
+          const selectionRange = globalThis.getSelection().getRangeAt(0);
+          this._dragAnchorNode = this._activeHandle.dataset.hhPosition === 'start' ? selectionRange.endContainer : selectionRange.startContainer;
+          this._dragAnchorOffset = this._activeHandle.dataset.hhPosition === 'start' ? selectionRange.endOffset : selectionRange.startOffset;
+          this._container.addEventListener('pointermove', respondToHandleDrag, { signal: this._controller.signal });
+          this._updateSelectionState();
+        }
+        // Prevent default drag interaction (which would show a thumbnail and drag selected text)
+        return event.preventDefault();
+      }
 
-    this._updateSelectionUi('bounds');
-  }
-  document.addEventListener('selectionchange', (event) => respondToSelectionChange(event), { signal: this._controller.signal });
-
-  // Pointer down in annotatable container
-  const respondToPointerDown = (event) => {
-    const isSecondaryClick = (event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey);
-    if (!isSecondaryClick) this._annotatableContainer.dataset.hhPointerDown = 'true';
-    this._pointerType = event.pointerType;
-
-    // Pointer down on a selection handle
-    if (event.target?.closest('.hh-selection-handle')) {
-      if (!isSecondaryClick) {
-        this._activeSelectionHandle = event.target.parentElement.closest('.hh-selection-handle');
-        const selectionHandleClientRect = this._activeSelectionHandle.getBoundingClientRect();
-        const lineHeight = selectionHandleClientRect.bottom - selectionHandleClientRect.top;
-        this._activeSelectionHandle.dataset.dragYOffset = Math.max(0, event.clientY - selectionHandleClientRect.bottom + (lineHeight / 6));
-        const selectionRange = globalThis.getSelection().getRangeAt(0);
-        this._dragAnchorNode = this._activeSelectionHandle.dataset.position === 'start' ? selectionRange.endContainer : selectionRange.startContainer;
-        this._dragAnchorOffset = this._activeSelectionHandle.dataset.position === 'start' ? selectionRange.endOffset : selectionRange.startOffset;
-        this._annotatableContainer.addEventListener('pointermove', respondToSelectionHandleDrag, { signal: this._controller.signal });
-        this._updateSelectionUi('bounds');
-      }
-      // Prevent default drag interaction (which would show a thumbnail and drag selected text)
-      return event.preventDefault();
-    }
-
-    // Deactivate highlights and return on double-tap. This fixes a bug where double-tapping and holding a word in a highlight in iOS Safari caused the highlight to activate then shrink to the selected word.
-    if (this._doubleTapTimeoutId) {
-      return this.deactivateHighlights();
-    } else {
-      this._doubleTapTimeoutId = setTimeout(() => this._doubleTapTimeoutId = clearTimeout(this._doubleTapTimeoutId), 500);
+      // Deactivate highlights and return on double-tap. This fixes a bug where double-tapping and holding a word in a highlight in iOS Safari caused the highlight to activate then shrink to the selected word.
+      if (this._doubleTapTimeoutId) {
+        return this.deactivateHighlights();
+      } else {
+        this._doubleTapTimeoutId = setTimeout(() => this._doubleTapTimeoutId = clearTimeout(this._doubleTapTimeoutId), 500);
+      }
+
+      // Return if it's not a regular click
+      if (isSecondaryClick) return;
+
+      // Trigger a long-press event if the user doesn't lift their finger within the specified time
+      if (options.longPressTimeout) this._longPressTimeoutId = setTimeout(() => respondToLongPress(event), options.longPressTimeout);
+
+      this._tapResult = this._checkForTapTargets(event);
     }
+    this._container.addEventListener('pointerdown', (event) => respondToPointerDown(event), { signal: this._controller.signal });
 
-    // Return if it's not a regular click, or if the user is tapping away from an existing selection
-    if (this._previousSelectionRange || isSecondaryClick) return;
+    // Selection handle drag (this function is added as an event listener on pointerdown, and removed on pointerup)
+    const respondToHandleDrag = (event) => {
+      this._activeHandle.dataset.hhPointerXPosition = event.clientX;
+      this._activeHandle.dataset.hhPointerYPosition = event.clientY;
+      const selection = globalThis.getSelection();
+      const selectionRange = selection.getRangeAt(0);
+      const dragCaret = this._getCaretFromCoordinates(event.clientX, event.clientY - this._activeHandle.dataset.hhDragYOffset, true, false, true);
 
-    // Trigger a long-press event if the user doesn't lift their finger within the specified time
-    if (options.longPressTimeout) this._longPressTimeoutId = setTimeout(() => respondToLongPress(event), options.longPressTimeout);
+      // Return if there's no drag caret, if the drag caret is invalid, or if the drag caret and anchor caret have the same position
+      if (!dragCaret || dragCaret.startContainer.nodeType !== Node.TEXT_NODE || dragCaret.endContainer.nodeType !== Node.TEXT_NODE || (this._dragAnchorNode === dragCaret.endContainer && this._dragAnchorOffset === dragCaret.endOffset)) return;
 
-    this._tapResult = this._checkForTapTargets(event);
-  }
-  this._annotatableContainer.addEventListener('pointerdown', (event) => respondToPointerDown(event), { signal: this._controller.signal });
+      // Check if start and end selection handles switched positions
+      const dragPositionRelativeToSelectionStart = dragCaret.compareBoundaryPoints(Range.START_TO_END, selectionRange);
+      const dragPositionRelativeToSelectionEnd = dragCaret.compareBoundaryPoints(Range.END_TO_END, selectionRange);
+      if (this._activeHandle.dataset.hhPosition === 'start' && dragPositionRelativeToSelectionEnd === 1 || this._activeHandle.dataset.hhPosition === 'end' && dragPositionRelativeToSelectionStart === -1) {
+        for (const handle of this._dragHandles) {
+          handle.dataset.hhPosition = handle.dataset.hhPosition === 'start' ? 'end' : 'start';
+        }
+      }
 
-  // Selection handle drag (this function is added as an event listener on pointerdown, and removed on pointerup)
-  const respondToSelectionHandleDrag = (event) => {
-    this._activeSelectionHandle.dataset.pointerXPosition = event.clientX;
-    this._activeSelectionHandle.dataset.pointerYPosition = event.clientY;
-    const selection = globalThis.getSelection();
-    const selectionRange = selection.getRangeAt(0);
-    const dragCaret = this._getCaretFromCoordinates(event.clientX, event.clientY - this._activeSelectionHandle.dataset.dragYOffset, true, false, true);
+      // Update selection
+      selection.setBaseAndExtent(this._dragAnchorNode, this._dragAnchorOffset, dragCaret.endContainer, dragCaret.endOffset);
+    }
 
-    // Return if there's no drag caret, if the drag caret is invalid, or if the drag caret and anchor caret have the same position
-    if (!dragCaret || dragCaret.startContainer.nodeType !== Node.TEXT_NODE || dragCaret.endContainer.nodeType !== Node.TEXT_NODE || (this._dragAnchorNode === dragCaret.endContainer && this._dragAnchorOffset === dragCaret.endOffset)) return;
+    // Long press in container (triggered by setTimeout() in pointerdown event)
+    const respondToLongPress = (event) => {
+      respondToPointerUp(event, true);
+      this._tapResult = null;
+    }
 
-    // Check if start and end selection handles switched positions
-    const dragPositionRelativeToSelectionStart = dragCaret.compareBoundaryPoints(Range.START_TO_END, selectionRange);
-    const dragPositionRelativeToSelectionEnd = dragCaret.compareBoundaryPoints(Range.END_TO_END, selectionRange);
-    if (this._activeSelectionHandle.dataset.position === 'start' && dragPositionRelativeToSelectionEnd === 1 || this._activeSelectionHandle.dataset.position === 'end' && dragPositionRelativeToSelectionStart === -1) {
-      for (const selectionHandle of this._selectionHandles) {
-        selectionHandle.dataset.position = selectionHandle.dataset.position === 'start' ? 'end' : 'start';
+    // Pointer up in container
+    const respondToPointerUp = (event, isLongPress = false) => {
+      if (this._tapResult) {
+        this._tapResult.isLongPress = isLongPress;
+        this._container.dispatchEvent(new CustomEvent('hh:tap', { detail: this._tapResult, }));
       }
     }
+    this._container.addEventListener('pointerup', (event) => respondToPointerUp(event), { signal: this._controller.signal });
+
+    // Pointer up or cancel in window
+    const respondToWindowPointerUp = (event) => {
+      const selection = globalThis.getSelection();
+      if (selection.type === 'Range' && this._activeHighlightId && this._getSelectionContainer() === this._container) {
+        const adjustedSelectionRange = this._snapRangeToBoundaries(selection.getRangeAt(0), selection.anchorNode);
+
+        // Update the selection range if needed
+        // In Android Chrome, sometimes selection handles don't show when a selection is updated programmatically, so it's best to only update the selection if needed.
+        const selectionRange = selection.getRangeAt(0);
+        const rangesMatch = _rangesEqual(selectionRange, adjustedSelectionRange);
+        if (!rangesMatch) {
+          selection.setBaseAndExtent(adjustedSelectionRange.startContainer, adjustedSelectionRange.startOffset, adjustedSelectionRange.endContainer, adjustedSelectionRange.endOffset);
+        }
+      }
+      this._tapResult = null;
+      this._longPressTimeoutId = clearTimeout(this._longPressTimeoutId);
+      this._container.dataset.hhPointerDown = 'false';
+      if (this._activeHandle || this._isResizingSelection) {
+        this._activeHandle = null;
+        this._isResizingSelection = false;
+        this._updateSelectionState();
+        this._container.removeEventListener('pointermove', respondToHandleDrag);
+      }
+    }
+    globalThis.addEventListener('pointerup', (event) => respondToWindowPointerUp(event), { signal: this._controller.signal });
+    globalThis.addEventListener('pointercancel', (event) => respondToWindowPointerUp(event), { signal: this._controller.signal });
+
+    // Mouse move in container (for hh:hover events)
+    let rafId = null;
+    let latestMoveEvent = null;
+    const handleHoverEvent = (event) => {
+      const targets = this.getTargetsAtPoint(event.clientX, event.clientY);
+      const newHoverHash = [
+        ...targets.highlights.map(h => h.highlightId),
+        ...targets.wrappers.map(w => `${w.highlight.highlightId}:${w.position}`),
+        ...targets.hyperlinks.map(h => h.index),
+      ].sort().join('\u0000');
+      if (newHoverHash === this._hoverHash) return;
+      this._hoverHash = newHoverHash;
+      this._container.dispatchEvent(new CustomEvent('hh:hover', {
+        detail: {
+          ...targets,
+          selectionType: globalThis.getSelection().type,
+          activeHighlightId: this._activeHighlightId,
+          nativeEvent: event,
+        },
+      }));
+    };
+    this._container.addEventListener('mousemove', (event) => {
+      if (!options.enableHover) return;
+      latestMoveEvent = event;
+      rafId ??= requestAnimationFrame(() => { rafId = null; handleHoverEvent(latestMoveEvent); });
+    }, { signal: this._controller.signal });
+    this._container.addEventListener('mouseleave', (event) => {
+      if (!options.enableHover) return;
+      handleHoverEvent(event);
+    }, { signal: this._controller.signal });
 
-    // Update selection
-    selection.setBaseAndExtent(this._dragAnchorNode, this._dragAnchorOffset, dragCaret.endContainer, dragCaret.endOffset);
-  }
+    // Hyperlink click (for each hyperlink in container)
+    for (const hyperlinkElement of this._hyperlinkElements) {
+      hyperlinkElement.addEventListener('click', (event) => {
+        this.deactivateHighlights();
+        if (!this._allowHyperlinkClick) event.preventDefault();
+      }, { signal: this._controller.signal });
+    }
+
+    // Container resize (debounced)
+    let computedStyle = globalThis.getComputedStyle(this._container);
+    let previousWidth = Math.round(this._container.clientWidth - Number.parseInt(computedStyle.getPropertyValue('padding-left')) - Number.parseInt(computedStyle.getPropertyValue('padding-right')));
+    let previousHeight = Math.round(this._container.clientHeight - Number.parseInt(computedStyle.getPropertyValue('padding-top')) - Number.parseInt(computedStyle.getPropertyValue('padding-bottom')));
+    this._resizeObserver = new ResizeObserver(_debounce((entries) => {
+      for (const entry of entries) {
+        const width = Math.round(entry.contentBoxSize[0].inlineSize);
+        const height = Math.round(entry.contentBoxSize[0].blockSize);
+        // Respond to width changes (resize window, device rotation) and height changes (lazy-loaded images, dynamically-inserted elements)
+        if (width !== previousWidth || height !== previousHeight) {
+          if (options.drawingMode === 'svg') this.drawHighlights();
+          if (this._previousSelectionRange) this._updateSelectionState();
+          previousWidth = width;
+          previousHeight = height;
+        }
+      }
+    }, Math.floor(Object.keys(this._highlightsById).length / 20)));
+    this._resizeObserver.observe(this._container);
+
+    // Set drawing mode to mark elements temporarily when printing (highlights get offset in SVG drawing mode)
+    let previousDrawingMode = null;
+    globalThis.addEventListener('beforeprint', () => {
+      previousDrawingMode = this._options.drawingMode;
+      this.setOptions({ drawingMode: 'mark-elements' });
+      this.drawHighlights();
+    }, { signal: this._controller.signal });
+    globalThis.addEventListener('afterprint', () => {
+      this.setOptions({ drawingMode: previousDrawingMode });
+      this.drawHighlights();
+    }, { signal: this._controller.signal });
 
-  // Long press in annotatable container (triggered by setTimeout() in pointerdown event)
-  const respondToLongPress = (event) => {
-    respondToPointerUp(event, true);
-    this._tapResult = null;
   }
 
-  // Pointer up in annotatable container
-  const respondToPointerUp = (event, isLongPress = false) => {
-    if (this._tapResult) {
-      this._tapResult.isLongPress = isLongPress;
-      this._annotatableContainer.dispatchEvent(new CustomEvent('hh:tap', { detail: this._tapResult, }));
-      if (options.autoTapToActivate && this._tapResult?.targetFound && !isLongPress) {
-        if (this._tapResult.highlights.length === 1 && this._tapResult.hyperlinks.length === 0) {
-          return this.activateHighlight(this._tapResult.highlights[0].highlightId);
-        } else if (this._tapResult.highlights.length === 0 && this._tapResult.hyperlinks.length === 1) {
-          return this.activateHyperlink(this._tapResult.hyperlinks[0].position);
-        } else if (this._tapResult.highlights.length + this._tapResult.hyperlinks.length > 1) {
-          return this._annotatableContainer.dispatchEvent(new CustomEvent('hh:ambiguousaction', { detail: this._tapResult, }));
+
+  /********************** Public Methods **********************/
+
+  // Load highlights
+  Highlighter.prototype.loadHighlights = function (highlights) {
+    // Don't load highlights until the document is ready (otherwise, highlights may be offset)
+    if (document.readyState !== 'complete') return setTimeout(this.loadHighlights.bind(this), 10, highlights);
+    const startTimestamp = Date.now();
+
+    const highlightIdsToDraw = new Set();
+    const knownHighlightIds = new Set(Object.keys(this._highlightsById));
+    let addedCount = 0, updatedCount = 0;
+    for (const highlight of highlights) {
+      if (knownHighlightIds.has(highlight.highlightId)) {
+        knownHighlightIds.delete(highlight.highlightId);
+        const changedHighlightInfo = this._diffHighlight(highlight, this._highlightsById[highlight.highlightId]);
+        if (changedHighlightInfo) {
+          this.createOrUpdateHighlight(changedHighlightInfo, false, false);
+          highlightIdsToDraw.add(highlight.highlightId);
+          updatedCount++;
         }
+      } else {
+        this.createOrUpdateHighlight(highlight, false, false);
+        highlightIdsToDraw.add(highlight.highlightId);
+        addedCount++;
       }
     }
+    if (knownHighlightIds.size > 0) this.removeHighlights([...knownHighlightIds]);
+    this.drawHighlights(highlightIdsToDraw);
+
+    const container = this._container;
+    const eventDetail = {
+      addedCount: addedCount, removedCount: knownHighlightIds.size, updatedCount: updatedCount,
+      totalCount: Object.keys(this._highlightsById).length,
+    };
+
+    // Fire event after browser paint (for accurate loadTimeMs)
+    requestAnimationFrame(() => {
+      setTimeout(() => {
+        container.dispatchEvent(new CustomEvent('hh:highlightsload', { detail: {
+          ...eventDetail, loadTimeMs: Date.now() - startTimestamp,
+        } }));
+      }, 0);
+    });
   }
-  this._annotatableContainer.addEventListener('pointerup', (event) => respondToPointerUp(event), { signal: this._controller.signal });
 
-  // Pointer up or cancel in window
-  const respondToWindowPointerUp = (event) => {
-    const selection = globalThis.getSelection();
-    if (selection.type === 'Range' && this._activeHighlightId && this._annotatableContainer.contains(selection.anchorNode)) {
-      const adjustedSelectionRange = this._snapRangeToBoundaries(selection.getRangeAt(0), selection.anchorNode);
+  // Create a new highlight, or update an existing highlight when it changes
+  Highlighter.prototype.createOrUpdateHighlight = function (properties, draw = true, activate = true) {
+    const options = this._options;
+    const highlightId = properties.highlightId ?? this._activeHighlightId ?? _getNewHighlightId();
+    const appearanceChanges = [];
+    const boundsChanges = [];
 
-      // Update the selection range if needed
-      // In Android Chrome, sometimes selection handles don't show when a selection is updated programmatically, so it's best to only update the selection if needed.
-      const selectionRange = selection.getRangeAt(0);
-      if (!(
-        adjustedSelectionRange.startContainer === selectionRange.startContainer &&
-        adjustedSelectionRange.startOffset === selectionRange.startOffset &&
-        adjustedSelectionRange.endContainer === selectionRange.endContainer &&
-        adjustedSelectionRange.endOffset === selectionRange.endOffset)
-      ) {
-        selection.setBaseAndExtent(adjustedSelectionRange.startContainer, adjustedSelectionRange.startOffset, adjustedSelectionRange.endContainer, adjustedSelectionRange.endOffset);
-      }
-    }
-    this._tapResult = null;
-    this._longPressTimeoutId = clearTimeout(this._longPressTimeoutId);
-    this._annotatableContainer.dataset.hhPointerDown = 'false';
-    if (this._activeSelectionHandle) {
-      this._activeSelectionHandle = null;
-      this._updateSelectionUi('bounds');
-      this._annotatableContainer.removeEventListener('pointermove', respondToSelectionHandleDrag);
+    const oldHighlightInfo = this._highlightsById[highlightId];
+    const isNewHighlight = !oldHighlightInfo;
+
+    // If the highlight is currently active, ignore programmatic bounds changes (selection range takes priority)
+    if (highlightId === this._activeHighlightId) {
+      properties.startParagraphId = null;
+      properties.startParagraphOffset = null;
+      properties.endParagraphId = null;
+      properties.endParagraphOffset = null;
+    }
+
+    // Warn if color, style, or wrapper properties are invalid
+    if (properties.color && !Object.hasOwn(options.colorDefs, properties.color)) {
+      console.warn(`Highlight color "${properties.color}" is not defined in options (highlightId: ${highlightId}).`);
+    }
+    if (properties.style && !Object.hasOwn(options.styleDefs, properties.style)) {
+      console.warn(`Highlight style "${properties.style}" is not defined in options (highlightId: ${highlightId}).`);
+    }
+    if (properties.wrapper && !Object.hasOwn(options.wrapperDefs, properties.wrapper)) {
+      console.warn(`Highlight wrapper "${properties.wrapper}" is not defined in options (highlightId: ${highlightId}).`);
     }
-  }
-  globalThis.addEventListener('pointerup', (event) => respondToWindowPointerUp(event), { signal: this._controller.signal });
-  globalThis.addEventListener('pointercancel', (event) => respondToWindowPointerUp(event), { signal: this._controller.signal });
 
-  // Hyperlink click (for each hyperlink in annotatable container)
-  for (const hyperlinkElement of this._hyperlinkElements) {
-    hyperlinkElement.addEventListener('click', (event) => {
+    // Check which appearance properties changed
+    for (const key of ['color', 'style', 'wrapper', 'variables', 'readOnly']) {
+      if (isNewHighlight || (properties[key] != null && properties[key] !== oldHighlightInfo[key])) appearanceChanges.push(key);
+    }
+
+    // If the highlight was and still is read-only, return
+    if (oldHighlightInfo?.readOnly && (properties.readOnly == null || properties.readOnly === true)) {
       this.deactivateHighlights();
-      if (!this._allowHyperlinkClick) event.preventDefault();
-    }, { signal: this._controller.signal });
-  }
+      return;
+    }
 
-  // Annotatable container resize (debounced)
-  let computedStyle = globalThis.getComputedStyle(this._annotatableContainer);
-  let previousWidth = Math.round(this._annotatableContainer.clientWidth - Number.parseInt(computedStyle.getPropertyValue('padding-left')) - Number.parseInt(computedStyle.getPropertyValue('padding-right')));
-  this._resizeObserver = new ResizeObserver(debounce((entries) => {
-    for (const entry of entries) {
-      const width = Math.round(entry.contentBoxSize[0].inlineSize);
-      // Only respond if the annotatable content width changed
-      if (width !== previousWidth) {
-        if (options.drawingMode === 'svg') this.drawHighlights();
-        if (this._previousSelectionRange) this._updateSelectionUi('bounds');
-        previousWidth = width;
+    // Calculate the bounds of the highlight range, if it's changed
+    let adjustedSelectionRange, highlightRange;
+    let rangeText, rangeHtml, rangeParagraphIds;
+    let startParagraphId, startParagraphOffset, endParagraphId, endParagraphOffset;
+    const selection = this._getRestoredSelectionOrCaret(globalThis.getSelection());
+    if (selection.type === 'Range') adjustedSelectionRange = this._snapRangeToBoundaries(selection.getRangeAt(0));
+    if ((properties.startParagraphId ?? properties.startParagraphOffset ?? properties.endParagraphId ?? properties.endParagraphOffset != null) || (adjustedSelectionRange && !adjustedSelectionRange.collapsed)) {
+      let startNode, startOffset, endNode, endOffset;
+      if (properties.startParagraphId ?? properties.startParagraphOffset ?? properties.endParagraphId ?? properties.endParagraphOffset != null) {
+        startParagraphId = properties.startParagraphId ?? oldHighlightInfo?.startParagraphId;
+        startParagraphOffset = Number.parseInt(properties.startParagraphOffset ?? oldHighlightInfo?.startParagraphOffset);
+        endParagraphId = properties.endParagraphId ?? oldHighlightInfo?.endParagraphId;
+        endParagraphOffset = Number.parseInt(properties.endParagraphOffset ?? oldHighlightInfo?.endParagraphOffset);
+        ([ startNode, startOffset ] = this._getTextNodeAndOffset(document.getElementById(startParagraphId), startParagraphOffset, 'start'));
+        ([ endNode, endOffset ] = this._getTextNodeAndOffset(document.getElementById(endParagraphId), endParagraphOffset, 'end'));
+      } else if (adjustedSelectionRange) {
+        startNode = adjustedSelectionRange.startContainer;
+        startOffset = adjustedSelectionRange.startOffset;
+        endNode = adjustedSelectionRange.endContainer;
+        endOffset = adjustedSelectionRange.endOffset;
+        ([ startParagraphId, startParagraphOffset ] = this._getParagraphOffset(startNode, startOffset));
+        ([ endParagraphId, endParagraphOffset ] = this._getParagraphOffset(endNode, endOffset));
       }
-    }
-  }, Math.floor(Object.keys(this._highlightsById).length / 20)));
-  this._resizeObserver.observe(this._annotatableContainer);
-}
 
+      // Create a new highlight range
+      highlightRange = document.createRange();
+      highlightRange.setStart(startNode, startOffset);
+      highlightRange.setEnd(endNode, endOffset);
 
-/********************** Public Methods **********************/
+      // Check which bounds properties changed
+      const boundsValues = { startParagraphId, startParagraphOffset, endParagraphId, endParagraphOffset };
+      for (const key of Object.keys(boundsValues)) {
+        if (isNewHighlight || boundsValues[key] !== oldHighlightInfo[key]) boundsChanges.push(key);
+      }
 
-// Load highlights
-Highlighter.prototype.loadHighlights = function (highlights) {
-  // Don't load highlights until the document is ready (otherwise, highlights may be offset)
-  if (document.readyState !== 'complete') return setTimeout(this.loadHighlights.bind(this), 10, highlights);
-  const startTimestamp = Date.now();
+      // Set variables that depend on the range
+      ({ rangeHtml, rangeText } = this._getRangeContent(highlightRange, true, true));
+      let startParagraphIndex = this._paragraphIds.indexOf(startParagraphId);
+      let endParagraphIndex = this._paragraphIds.indexOf(endParagraphId);
+      if (startParagraphIndex === -1) startParagraphIndex = 0;
+      if (endParagraphIndex === -1) endParagraphIndex = this._paragraphIds.length - 1;
+      rangeParagraphIds = this._paragraphIds.slice(startParagraphIndex, endParagraphIndex + 1);
+    }
 
-  // Hide container (repeated DOM manipulations are faster if the container is hidden)
-  if (highlights.length > 1) {
-    let containerToHide = this._options.drawingMode === 'svg' ? this._svgBackground : this._annotatableContainer;
-    containerToHide.style.display = 'none';
-  }
+    // If there are no valid changes, return
+    // TODO: Checking for an empty highlight range ensures that regular highlights can't collapse and become invisible. However, there may be use cases where showing just a caret is desired (example: document draft demo).
+    if (!highlightRange || highlightRange.toString() === '' || appearanceChanges.length + boundsChanges.length === 0) {
+      return;
+    }
 
-  // Load read-only highlights first (read-only highlights change the DOM, affecting other highlights' ranges)
-  const sortedHighlights = highlights.sort((a,b) => a.readOnly === b.readOnly ? 0 : a.readOnly ? -1 : 1);
+    // Update saved highlight info
+    const newHighlightInfo = {
+      highlightId: highlightId,
+      color: properties.color ?? oldHighlightInfo?.color ?? _defaultColor,
+      style: properties.style ?? oldHighlightInfo?.style ?? _defaultStyle,
+      wrapper: properties.wrapper ?? oldHighlightInfo?.wrapper ?? null,
+      variables: properties.variables ?? oldHighlightInfo?.variables ?? {},
+      readOnly: properties.readOnly ?? oldHighlightInfo?.readOnly ?? false,
+      startParagraphId: startParagraphId ?? oldHighlightInfo?.startParagraphId,
+      startParagraphOffset: startParagraphOffset ?? oldHighlightInfo?.startParagraphOffset,
+      endParagraphId: endParagraphId ?? oldHighlightInfo?.endParagraphId,
+      endParagraphOffset: endParagraphOffset ?? oldHighlightInfo?.endParagraphOffset,
+      // Generated properties
+      rangeText: rangeText ?? oldHighlightInfo?.rangeText,
+      rangeHtml: rangeHtml ?? oldHighlightInfo?.rangeHtml,
+      rangeRect: oldHighlightInfo?.rangeRect ?? null,
+      rangeLineRects: oldHighlightInfo?.rangeLineRects ?? null,
+      rangeParagraphIds: rangeParagraphIds ?? oldHighlightInfo?.rangeParagraphIds,
+      rangeObj: highlightRange ?? oldHighlightInfo?.rangeObj,
+      resolvedDrawingMode: null,
+      escapedHighlightId: CSS.escape(highlightId),
+    };
+    this._highlightsById[highlightId] = newHighlightInfo;
+    newHighlightInfo.resolvedDrawingMode = this._getResolvedDrawingMode(newHighlightInfo);
 
-  const knownHighlightIds = Object.keys(this._highlightsById);
-  let addedCount = 0, updatedCount = 0;
-  for (const highlight of sortedHighlights) {
-    const highlightInfo = this._diffHighlight(highlight, this._highlightsById[highlight.highlightId]);
-    highlightInfo.highlightId = highlight.highlightId;
-    const knownHighlightIndex = knownHighlightIds.indexOf(highlightInfo.highlightId);
-    if (knownHighlightIndex > -1) {
-      knownHighlightIds.splice(knownHighlightIndex, 1);
-      if (Object.keys(highlightInfo).length > 1) {
-        this.createOrUpdateHighlight(highlightInfo, false); updatedCount++;
+    // Draw highlight if needed
+    if (draw) {
+      if (highlightId !== this._activeHighlightId || appearanceChanges.some(k => k === 'wrapper' || k === 'variables')) {
+        this.drawHighlights([highlightId]);
+      } else {
+        // If the highlight is active, just update the selection style (the highlight will be redrawn on deactivate)
+        this._updateSelectionState();
       }
+    }
+
+    // Activate highlight if needed
+    if (activate && highlightId !== this._activeHighlightId) {
+      this.activateHighlight(highlightId);
+    }
+
+    const detail = {
+      highlight: newHighlightInfo,
+      changes: appearanceChanges.concat(boundsChanges),
+    }
+    if (isNewHighlight) {
+      this._container.dispatchEvent(new CustomEvent('hh:highlightcreate', { detail: detail }));
     } else {
-      this.createOrUpdateHighlight(highlightInfo, false); addedCount++;
+      this._container.dispatchEvent(new CustomEvent('hh:highlightupdate', { detail: detail }));
     }
-  }
-  if (knownHighlightIds.length > 0) this.removeHighlights(knownHighlightIds);
-
-  (this._options.drawingMode === 'svg' ? this._svgBackground : this._annotatableContainer).style.display = '';
-  this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightsload', { detail: {
-    addedCount: addedCount, removedCount: knownHighlightIds.length, updatedCount: updatedCount,
-    totalCount: Object.keys(this._highlightsById).length,
-    timeToLoad: Date.now() - startTimestamp,
-  } }));
-}
-
-// Draw (or redraw) specified highlights, or all highlights on the page
-Highlighter.prototype.drawHighlights = function (highlightIds = Object.keys(this._highlightsById)) {
-  const options = this._options;
-
-  // Hide container (repeated DOM manipulations is faster if the container is hidden)
-  if (highlightIds.length > 1) {
-    let containerToHide = options.drawingMode === 'svg' ? this._svgBackground : this._annotatableContainer;
-    containerToHide.style.display = 'none';
-  }
 
-  for (const highlightId of highlightIds) {
-    const highlightInfo = this._highlightsById[highlightId];
-    let range = this._getCorrectedRangeObj(highlightId);
-    const rangeParagraphs = this._annotatableContainer.querySelectorAll(`#${highlightInfo.rangeParagraphIds.join(', #')}`);
-    const wasDrawnAsReadOnly = this._annotatableContainer.querySelector(`[data-highlight-id="${highlightId}"][data-read-only]`);
-
-    // Remove old highlight elements and styles
-    if (!wasDrawnAsReadOnly || !highlightInfo.readOnly) this._undrawHighlight(highlightInfo);
-    // Don't redraw a read-only highlight that's already drawn
-    if (wasDrawnAsReadOnly) continue;
-
-    // Draw highlights with mark elements
-    if (highlightInfo.readOnly || options.drawingMode === 'mark-elements') {
-      // Inject HTML <mark> elements
-      if (range.startOffset < range.startContainer.length) range.startContainer.splitText(range.startOffset);
-      if (range.endOffset > 0 && range.endOffset < range.endContainer.length) range.endContainer.splitText(range.endOffset);
-      const walker = this._getTextNodeWalker(range.commonAncestorContainer);
-      walker.currentNode = range.startContainer;
-      const relevantTextNodes = [];
-      let node;
-      while (node = walker.nextNode()) {
-        if (!node.parentElement.closest('rt, rp')) relevantTextNodes.push(node);
-        if (node === range.endContainer) break;
-      }
-      const overlappingHighlightIds = new Set();
-      const createStyledMark = () => {
-        const mark = document.createElement('mark');
-        mark.dataset.highlightId = highlightId;
-        if (highlightInfo.readOnly) mark.dataset.readOnly = '';
-        mark.dataset.color = highlightInfo.color;
-        mark.dataset.style = highlightInfo.style;
-        return mark;
-      };
-      for (let tn = 0; tn < relevantTextNodes.length; tn++) {
-        const textNode = relevantTextNodes[tn];
-        if (textNode.parentElement.dataset.highlightId) overlappingHighlightIds.add(textNode.parentElement.dataset.highlightId);
-        const styledMark = createStyledMark();
-        if (tn === 0) styledMark.dataset.start = '';
-        if (tn === relevantTextNodes.length - 1) styledMark.dataset.end = '';
-        textNode.before(styledMark);
-        styledMark.appendChild(textNode);
-        // Absorb adjacent elements without text into the mark element. This prevents unstyled gaps around CSS-rendered pseudoelement content (such as superscript footnote markers).
-        let prev = styledMark.previousSibling;
-        while (prev && prev.nodeType === Node.ELEMENT_NODE && prev.textContent === '') {
-          const toAbsorb = prev; prev = prev.previousSibling;
-          styledMark.prepend(toAbsorb);
-        }
-        if (tn < relevantTextNodes.length - 1) {
-          let next = styledMark.nextSibling;
-          while (next && next.nodeType === Node.ELEMENT_NODE && next.textContent === '') {
-            const toAbsorb = next; next = next.nextSibling;
-            styledMark.appendChild(toAbsorb);
+    return newHighlightInfo;
+  }
+
+  // Draw (or redraw) specified highlights, or all highlights on the page
+  Highlighter.prototype.drawHighlights = function (highlightIds = Object.keys(this._highlightsById)) {
+    if ((highlightIds.size ?? highlightIds.length) === 0) return;
+    const options = this._options;
+    this._containerRect = this._container.getBoundingClientRect();
+    this._additionsRect = this._additionsDiv.getBoundingClientRect();
+    const wrapperElements = this._wrapperElements;
+
+    // Collect highlights to draw (mark-elements first, since they cause DOM mutation)
+    let markHighlights = [], otherHighlights = [];
+    if (options.drawingMode === 'svg') {
+      // In SVG drawing mode, if any queued highlight has a changed wrapper, also queue SVG highlights from that point forward (prevents misaligned highlights if wrapper change causes text reflow)
+      let previousWrapperChanged = false;
+      const highlightIdSet = new Set(highlightIds);
+      const allHighlights = this.getHighlightInfo();
+      for (const highlightInfo of allHighlights) {
+        highlightInfo.resolvedDrawingMode = this._getResolvedDrawingMode(highlightInfo);
+        if (previousWrapperChanged && highlightInfo.resolvedDrawingMode === 'svg') {
+          otherHighlights.push(highlightInfo);
+        } else if (highlightIdSet.has(highlightInfo.highlightId)) {
+          if (!previousWrapperChanged) {
+            const wrapper = wrapperElements.get(`${highlightInfo.highlightId}:start`) ?? wrapperElements.get(`${highlightInfo.highlightId}:end`) ?? null;
+            if (this._getWrapperHash(highlightInfo) !== (wrapper?.dataset?.hhWrapperHash ?? '')) {
+              previousWrapperChanged = true;
+            }
           }
+          (highlightInfo.resolvedDrawingMode === 'mark-elements' ? markHighlights : otherHighlights).push(highlightInfo);
+        }
+      }
+    } else {
+      for (const highlightInfo of this.getHighlightInfo(highlightIds)) {
+        highlightInfo.resolvedDrawingMode = this._getResolvedDrawingMode(highlightInfo);
+        (highlightInfo.resolvedDrawingMode === 'mark-elements' ? markHighlights : otherHighlights).push(highlightInfo);
+      }
+    }
+    const sortedHighlights = markHighlights.concat(otherHighlights);
+
+    // Prepare wrappers
+    for (const highlightInfo of sortedHighlights) {
+      if (!highlightInfo.wrapper) continue;
+      const highlightId = highlightInfo.highlightId;
+      const wrapperDef = options.wrapperDefs[highlightInfo.wrapper];
+      for (const position of ['start', 'end']) {
+        if (!wrapperDef?.[position]) continue;
+        // Reuse previous wrapper element if it exists (to preserve its state if it was interacted with)
+        let wrapper = wrapperElements.get(`${highlightId}:${position}`) ?? null;
+        if (wrapper) {
+          wrapper.remove();
+        } else {
+          wrapper = document.createElement('span');
+          wrapper.dataset.hhPosition = position;
+          wrapper.dataset.hhHighlightId = highlightId;
+          wrapper.dataset.hhIgnore = '';
         }
+        wrapper.dataset.hhColor = highlightInfo.color;
+        wrapper.dataset.hhStyle = highlightInfo.style;
+        wrapper.dataset.hhWrapper = highlightInfo.wrapper;
+        wrapperElements.set(`${highlightId}:${position}`, wrapper);
       }
+    }
 
-      // Update highlight ranges that were invalidated by the DOM change
-      this._getCorrectedRangeObj(highlightId);
-      for (const overlappingHighlightId of overlappingHighlightIds) {
-        this._getCorrectedRangeObj(overlappingHighlightId);
+    // Undraw highlights that were previously drawn
+    this._undrawHighlights(sortedHighlights.map(h => h.highlightId));
+
+    // Cache paragraph and column geometry
+    const paragraphLineRectsCache = new Map();
+    const columnGeometryCache = new Map();
+
+    // Insert wrappers and update rects
+    for (const highlightInfo of sortedHighlights) {
+      const highlightId = highlightInfo.highlightId;
+      let range = this._getCorrectedRangeObj(highlightId);
+
+      // Insert wrappers
+      const wrapperDef = options.wrapperDefs[highlightInfo.wrapper];
+      if (wrapperDef) {
+        // Insert end wrapper first (avoids invalidating start node if start and end are in the same text node)
+        if (wrapperDef.end) {
+          range.endContainer.splitText(range.endOffset);
+          range.endContainer.after(wrapperElements.get(`${highlightId}:end`));
+        }
+        if (wrapperDef.start) range.insertNode(wrapperElements.get(`${highlightId}:start`));
+        range = this._getCorrectedRangeObj(highlightId, true);
+
+        // If current highlight is active, update selection range to match highlight range
+        if (highlightId === this._activeHighlightId) {
+          const selectionForWrapper = globalThis.getSelection();
+          const selectionRangeForWrapper = selectionForWrapper.type !== 'None' ? selectionForWrapper.getRangeAt(0) : null;
+          const rangesMatchForWrapper = _rangesEqual(selectionRangeForWrapper, range);
+          if (selectionRangeForWrapper && !rangesMatchForWrapper) {
+            selectionForWrapper.setBaseAndExtent(range.startContainer, range.startOffset, range.endContainer, range.endOffset);
+          }
+        }
       }
 
-    // Draw highlights with Custom Highlight API
-    } else if (options.drawingMode === 'highlight-api' && supportsHighlightApi) {
-      let highlightObj;
-      if (CSS.highlights.has(highlightId)) {
-        highlightObj = CSS.highlights.get(highlightId);
-        highlightObj.clear();
-      } else {
-        highlightObj = new Highlight();
-        CSS.highlights.set(highlightId, highlightObj);
-      }
-      highlightObj.add(range);
-      const styleTemplate = this._getStyleTemplate(highlightInfo.style, 'css', null);
-      const colorString = options.colors[highlightInfo.color];
-      this._highlightApiStylesheet.insertRule(`${options.containerSelector} ::highlight(${highlightInfo.escapedHighlightId}) { --hh-color: ${colorString}; ${styleTemplate} }`);
-      this._highlightApiStylesheet.insertRule(`${options.containerSelector} rt::highlight(${highlightInfo.escapedHighlightId}) { color: inherit; background-color: transparent; }`);
-      this._highlightApiStylesheet.insertRule(`${options.containerSelector} img::highlight(${highlightInfo.escapedHighlightId}) { color: inherit; background-color: transparent; }`);
-
-    // Draw highlights with SVG shapes
-    } else if (options.drawingMode === 'svg') {
-      const clientRects = this._getMergedClientRects(range, rangeParagraphs);
-      let group = document.createElementNS('http://www.w3.org/2000/svg', 'g');
-      group.dataset.highlightId = highlightId;
-      group.dataset.color = highlightInfo.color;
-      group.dataset.style = highlightInfo.style;
-      let svgContent = '';
-      for (const clientRect of clientRects) {
-        svgContent += this._getStyleTemplate(highlightInfo.style, 'svg', clientRect);
+      // Update range rects (after adding wrappers)
+      const rangeParagraphs = highlightInfo.rangeParagraphIds.map(id => document.getElementById(id));
+      const [rangeRect, rangeLineRects] = this._getRangeRects(range, rangeParagraphs, paragraphLineRectsCache, columnGeometryCache);
+      highlightInfo.rangeRect = rangeRect;
+      highlightInfo.rangeLineRects = rangeLineRects;
+
+      // Update wrapper variables
+      let wrapperRectChanged = false;
+      if (wrapperDef) {
+        for (const position of ['start', 'end']) {
+          const template = wrapperDef[position];
+          const wrapper = wrapperElements.get(`${highlightId}:${position}`);
+          if (!wrapper) continue;
+          const beforeRect = wrapper.getBoundingClientRect();
+          const wrapperTemplateHash = this._getWrapperTemplateHash(highlightInfo);
+          const wrapperHash = this._getWrapperHash(highlightInfo, wrapperTemplateHash);
+          if (wrapperHash !== wrapper.dataset.hhWrapperHash) {
+            const lineRect = position === 'start' ? highlightInfo.rangeLineRects[0] : highlightInfo.rangeLineRects.at(-1);
+            const innerHtml = this._applySubstitutions(template, highlightInfo.variables, highlightInfo.rangeRect, lineRect);
+            if (wrapperTemplateHash === wrapper.dataset.hhWrapperTemplateHash) {
+              this._updateWrapperInPlace(wrapper, innerHtml);
+            } else {
+              wrapper.innerHTML = innerHtml;
+              wrapper.dataset.hhWrapperTemplateHash = wrapperTemplateHash;
+            }
+            wrapper.dataset.hhWrapperHash = wrapperHash;
+          }
+          const afterRect = wrapper.getBoundingClientRect();
+          if (!_rectsEqual(beforeRect, afterRect)) wrapperRectChanged = true;
+        }
       }
-      group.innerHTML = svgContent;
-      this._svgBackground.appendChild(group);
-    }
 
-    // Update wrapper (for read-only highlights only)
-    if (highlightInfo.readOnly) {
-      if (highlightInfo.wrapper && (options.wrappers[highlightInfo.wrapper]?.start || options.wrappers[highlightInfo.wrapper]?.end)) {
-        const addWrapper = (edge, range, htmlString) => {
-          htmlString = `<span class="hh-wrapper-${edge}" data-highlight-id="${highlightId}" data-color="${highlightInfo.color}" data-style="${highlightInfo.style}" data-hh-ignore="">${htmlString}</span>`
-          for (const key of Object.keys(highlightInfo.wrapperVariables)) {
-            htmlString = htmlString.replaceAll(`{${key}}`, highlightInfo.wrapperVariables[key]);
+      // Update rects one more time if the wrapper width changed
+      if (wrapperRectChanged) {
+        for (const p of rangeParagraphs) {
+          paragraphLineRectsCache.delete(p.id);
+          let el = p.parentElement;
+          while (el) {
+            columnGeometryCache.delete(el);
+            if (el.hasAttribute('data-hh-container')) break;
+            el = el.parentElement;
           }
-          const template = document.createElement('template');
-          template.innerHTML = htmlString;
-          let htmlElement = template.content.firstChild;
-          range.insertNode(htmlElement);
         }
-        const startRange = highlightInfo.rangeObj;
-        const endRange = document.createRange(); endRange.setStart(highlightInfo.rangeObj.endContainer, highlightInfo.rangeObj.endOffset);
-        const wrapperInfo = options.wrappers[highlightInfo.wrapper];
-        addWrapper('start', startRange, wrapperInfo.start);
-        addWrapper('end', endRange, wrapperInfo.end);
-        rangeParagraphs.forEach(p => { p.normalize(); });
+        const [rangeRect, rangeLineRects] = this._getRangeRects(range, rangeParagraphs, paragraphLineRectsCache, columnGeometryCache);
+        highlightInfo.rangeRect = rangeRect;
+        highlightInfo.rangeLineRects = rangeLineRects;
       }
     }
-  }
 
-  // Show container
-  (options.drawingMode === 'svg' ? this._svgBackground : this._annotatableContainer).style.display = '';
-}
+    // Draw highlights
+    for (const highlightInfo of sortedHighlights) {
+      const highlightId = highlightInfo.highlightId;
+      const range = this._getCorrectedRangeObj(highlightId);
+
+      // Draw highlights with mark elements
+      const useMarkElements = highlightInfo.resolvedDrawingMode === 'mark-elements';
+      if (useMarkElements) {
+        // Inject HTML <mark> elements
+        if (range.startOffset < range.startContainer.length) range.startContainer.splitText(range.startOffset);
+        if (range.endOffset > 0 && range.endOffset < range.endContainer.length) range.endContainer.splitText(range.endOffset);
+        const walker = this._getTextNodeWalker(range.commonAncestorContainer);
+        walker.currentNode = range.startContainer;
+        const relevantTextNodes = [];
+        let node;
+        while (node = walker.nextNode()) {
+          if (node === range.endContainer && range.endOffset === 0) break;
+          if (!node.parentElement.closest('rt, rp')) relevantTextNodes.push(node);
+          if (node === range.endContainer) break;
+        }
+        const overlappingHighlightIds = new Set();
+        const createStyledMark = () => {
+          const mark = document.createElement('mark');
+          mark.dataset.hhHighlightId = highlightId;
+          mark.dataset.hhColor = highlightInfo.color;
+          mark.dataset.hhStyle = highlightInfo.style;
+          return mark;
+        };
+        for (let tn = 0; tn < relevantTextNodes.length; tn++) {
+          const textNode = relevantTextNodes[tn];
+          if (textNode.parentElement.dataset.hhHighlightId) overlappingHighlightIds.add(textNode.parentElement.dataset.hhHighlightId);
+          const styledMark = createStyledMark();
+          if (tn === 0 && tn === relevantTextNodes.length - 1) styledMark.dataset.hhPosition = 'start end';
+          else if (tn === 0) styledMark.dataset.hhPosition = 'start';
+          else if (tn === relevantTextNodes.length - 1) styledMark.dataset.hhPosition = 'end';
+          textNode.before(styledMark);
+          styledMark.appendChild(textNode);
+          // Absorb adjacent elements without text into the mark element. This prevents unstyled gaps around CSS-rendered pseudoelement content (such as superscript footnote markers).
+          let prev = styledMark.previousSibling;
+          while (prev && prev.nodeType === Node.ELEMENT_NODE && prev.textContent === '' && !prev.hasAttribute('data-hh-ignore')) {
+            const toAbsorb = prev; prev = prev.previousSibling;
+            styledMark.prepend(toAbsorb);
+          }
+          if (tn < relevantTextNodes.length - 1) {
+            let next = styledMark.nextSibling;
+            while (next && next.nodeType === Node.ELEMENT_NODE && next.textContent === '' && !next.hasAttribute('data-hh-ignore')) {
+              const toAbsorb = next; next = next.nextSibling;
+              styledMark.appendChild(toAbsorb);
+            }
+          }
+        }
 
-// Create a new highlight, or update an existing highlight when it changes
-Highlighter.prototype.createOrUpdateHighlight = function (attributes = {}, triggeredByUserAction = true) {
-  const options = this._options;
-  let highlightId = attributes.highlightId ?? this._activeHighlightId ?? options.highlightIdFunction();
-  const appearanceChanges = [];
-  const boundsChanges = [];
+        // Update highlight ranges that were invalidated by the DOM change
+        this._getCorrectedRangeObj(highlightId);
+        for (const overlappingHighlightId of overlappingHighlightIds) {
+          this._getCorrectedRangeObj(overlappingHighlightId);
+        }
 
-  const oldHighlightInfo = this._highlightsById[highlightId];
-  const isNewHighlight = !oldHighlightInfo;
+      // Draw highlights with CSS Highlight API
+      } else if (options.drawingMode === 'highlight-api') {
+        let cssHighlight;
+        if (CSS.highlights.has(highlightId)) {
+          cssHighlight = CSS.highlights.get(highlightId);
+          cssHighlight.clear();
+        } else {
+          cssHighlight = new Highlight();
+          CSS.highlights.set(highlightId, cssHighlight);
+        }
+        cssHighlight.add(range);
+
+      // Draw highlights with SVG shapes
+      } else if (options.drawingMode === 'svg') {
+        let group = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+        group.dataset.hhHighlightId = highlightId;
+        group.dataset.hhColor = highlightInfo.color;
+        group.dataset.hhStyle = highlightInfo.style;
+        let svgContent = '';
+        for (const lineRect of highlightInfo.rangeLineRects) {
+          svgContent += this._getStyleString(highlightInfo.style, 'svg', false, highlightInfo.variables, highlightInfo.rangeRect, lineRect);
+        }
+        group.innerHTML = svgContent;
+        this._svgBackground.appendChild(group);
+      }
+    }
 
-  // If a different highlight is active, deactivate it
-  if (this._activeHighlightId && highlightId !== this._activeHighlightId && triggeredByUserAction) {
-    this.deactivateHighlights();
+    this._rebuildHighlightStylesheet();
   }
 
-  // If the highlight is currently activate, ignore bounds changes that weren't initiated by the user
-  if (highlightId === this._activeHighlightId && !triggeredByUserAction) {
-    attributes.startParagraphId = null;
-    attributes.startParagraphOffset = null;
-    attributes.endParagraphId = null;
-    attributes.endParagraphOffset = null;
-  }
+  // Activate a highlight by ID
+  Highlighter.prototype.activateHighlight = function (highlightId) {
+    const highlightToActivate = this._highlightsById[highlightId];
+    if (!highlightToActivate || highlightId === this._activeHighlightId) return;
+    if (highlightToActivate.readOnly) {
+      // If the highlight is read-only, return events, but don't actually activate it
+      this._container.dispatchEvent(new CustomEvent('hh:highlightactivate', { detail: { highlight: highlightToActivate } }));
+      this._container.dispatchEvent(new CustomEvent('hh:highlightdeactivate', { detail: { highlight: highlightToActivate } }));
+      return;
+    }
+    const selection = globalThis.getSelection();
+    const highlightRange = this._getCorrectedRangeObj(highlightId);
+    this._activeHighlightId = highlightId;
+
+    // Update the selection range if needed
+    // In Android Chrome, sometimes selection handles don't show when a selection is updated programmatically, so it's best to only update the selection if needed.
+    let selectionRange = selection.type === 'Range' ? selection.getRangeAt(0) : null;
+    const rangesMatch = _rangesEqual(selectionRange, highlightRange);
+    if (!rangesMatch) {
+      selection.setBaseAndExtent(highlightRange.startContainer, highlightRange.startOffset, highlightRange.endContainer, highlightRange.endOffset);
+    }
 
-  // Warn if color, style, or wrapper attributes are invalid
-  if (attributes.color && !Object.hasOwn(options.colors, attributes.color)) {
-    console.warn(`Highlight color "${attributes.color}" is not defined in options (highlightId: ${highlightId}).`);
-  }
-  if (attributes.style && !Object.hasOwn(options.styles, attributes.style)) {
-    console.warn(`Highlight style "${attributes.style}" is not defined in options (highlightId: ${highlightId}).`);
-  }
-  if (attributes.wrapper && !Object.hasOwn(options.wrappers, attributes.wrapper)) {
-    console.warn(`Highlight wrapper "${attributes.wrapper}" is not defined in options (highlightId: ${highlightId}).`);
+    this._updateSelectionState();
+    this._container.dispatchEvent(new CustomEvent('hh:highlightactivate', { detail: { highlight: highlightToActivate } }));
   }
 
-  // Update defaults
-  if (options.rememberStyle && triggeredByUserAction) {
-    if (attributes.color) options.defaultColor = attributes.color;
-    if (attributes.style) options.defaultStyle = attributes.style;
-    if (attributes.wrapper) options.defaultWrapper = attributes.wrapper;
+  // Activate a link by index
+  Highlighter.prototype.activateHyperlink = function (index) {
+    this.deactivateHighlights();
+    this._allowHyperlinkClick = true;
+    this._hyperlinksByIndex[index].hyperlinkElement.click();
+    this._allowHyperlinkClick = false;
+  }
+
+  // Deactivate any highlights that are currently active/selected
+  Highlighter.prototype.deactivateHighlights = function (removeSelectionRanges = true, redraw = true) {
+    const deactivatedHighlight = this._highlightsById[this._activeHighlightId];
+    this._activeHighlightId = null;
+    this._previousSelectionRange = null;
+    if (removeSelectionRanges && this._getSelectionContainer() === this._container) {
+      const selection = globalThis.getSelection();
+      selection.collapseToStart();
+    }
+    this._updateSelectionState();
+    if (deactivatedHighlight) {
+      if (redraw) this.drawHighlights([deactivatedHighlight.highlightId]);
+      this._container.dispatchEvent(new CustomEvent('hh:highlightdeactivate', { detail: {
+        highlight: deactivatedHighlight,
+      }}));
+    }
   }
 
-  // Check which appearance properties changed
-  for (const key of ['color', 'style', 'wrapper', 'wrapperVariables', 'readOnly']) {
-    if (isNewHighlight || (attributes[key] != null && attributes[key] !== oldHighlightInfo[key])) appearanceChanges.push(key);
+  // Get the active highlight ID (if there is one)
+  Highlighter.prototype.getActiveHighlightId = function () {
+    return this._activeHighlightId;
   }
 
-  // If the highlight was and still is read-only, return
-  if (oldHighlightInfo?.readOnly && (attributes.readOnly == null || attributes.readOnly === true)) return this.deactivateHighlights();
-
-  // Calculate the bounds of the highlight range, if it's changed
-  let adjustedSelectionRange, highlightRange;
-  let rangeText, rangeHtml, rangeParagraphIds;
-  let startParagraphId, startParagraphOffset, endParagraphId, endParagraphOffset;
-  const selection = this._getRestoredSelectionOrCaret(globalThis.getSelection());
-  if (selection.type === 'Range') adjustedSelectionRange = this._snapRangeToBoundaries(selection.getRangeAt(0));
-  if ((attributes.startParagraphId ?? attributes.startParagraphOffset ?? attributes.endParagraphId ?? attributes.endParagraphOffset != null) || (adjustedSelectionRange && !adjustedSelectionRange.collapsed)) {
-    let startNode, startOffset, endNode, endOffset;
-    if (attributes.startParagraphId ?? attributes.startParagraphOffset ?? attributes.endParagraphId ?? attributes.endParagraphOffset != null) {
-      startParagraphId = attributes.startParagraphId ?? oldHighlightInfo?.startParagraphId;
-      startParagraphOffset = Number.parseInt(attributes.startParagraphOffset ?? oldHighlightInfo?.startParagraphOffset);
-      endParagraphId = attributes.endParagraphId ?? oldHighlightInfo?.endParagraphId;
-      endParagraphOffset = Number.parseInt(attributes.endParagraphOffset ?? oldHighlightInfo?.endParagraphOffset);
-      ([ startNode, startOffset ] = this._getTextNodeAndOffset(document.getElementById(startParagraphId), startParagraphOffset));
-      ([ endNode, endOffset ] = this._getTextNodeAndOffset(document.getElementById(endParagraphId), endParagraphOffset));
-    } else if (adjustedSelectionRange) {
-      startNode = adjustedSelectionRange.startContainer;
-      startOffset = adjustedSelectionRange.startOffset;
-      endNode = adjustedSelectionRange.endContainer;
-      endOffset = adjustedSelectionRange.endOffset;
-      ([ startParagraphId, startParagraphOffset ] = this._getParagraphOffset(startNode, startOffset));
-      ([ endParagraphId, endParagraphOffset ] = this._getParagraphOffset(endNode, endOffset));
-    }
-
-    // Create a new highlight range
-    highlightRange = document.createRange();
-    highlightRange.setStart(startNode, startOffset);
-    highlightRange.setEnd(endNode, endOffset);
-
-    // Check which bounds properties changed
-    const boundsValues = { startParagraphId, startParagraphOffset, endParagraphId, endParagraphOffset };
-    for (const key of Object.keys(boundsValues)) {
-      if (isNewHighlight || boundsValues[key] !== oldHighlightInfo[key]) boundsChanges.push(key);
-    }
-
-    // Set variables that depend on the range
-    const temporaryHtmlElement = document.createElement('div');
-    temporaryHtmlElement.appendChild(highlightRange.cloneContents());
-    for (const element of temporaryHtmlElement.querySelectorAll(`a, [data-highlight-id]:not([data-highlight-id="${highlightId}"])`)) element.outerHTML = element.innerHTML;
-    for (const element of temporaryHtmlElement.querySelectorAll(`[data-hh-ignore]`)) element.remove();
-    rangeText = temporaryHtmlElement.textContent;
-    rangeHtml = temporaryHtmlElement.innerHTML;
-    let startParagraphIndex = this._annotatableParagraphIds.indexOf(startParagraphId);
-    let endParagraphIndex = this._annotatableParagraphIds.indexOf(endParagraphId);
-    if (startParagraphIndex === -1) startParagraphIndex = 0;
-    if (endParagraphIndex === -1) endParagraphIndex = this._annotatableParagraphIds.length - 1;
-    rangeParagraphIds = this._annotatableParagraphIds.slice(startParagraphIndex, endParagraphIndex + 1);
-  }
+  // Get info for specified highlights, or all highlights on the page
+  Highlighter.prototype.getHighlightInfo = function (highlightIds = Object.keys(this._highlightsById), paragraphId = null) {
+    const highlights = Array.from(new Set(highlightIds)).map(id => this._highlightsById[id])
+      .filter(info => info && (!paragraphId || paragraphId === info.startParagraphId));
 
-  // If there are no valid changes, return
-  if (!highlightRange || highlightRange.toString() === '' || appearanceChanges.length + boundsChanges.length === 0) return;
-
-  // Update saved highlight info
-  const newHighlightInfo = {
-    highlightId: highlightId,
-    color: attributes.color ?? oldHighlightInfo?.color ?? options.defaultColor,
-    style: attributes.style ?? oldHighlightInfo?.style ?? options.defaultStyle,
-    wrapper: attributes.wrapper ?? oldHighlightInfo?.wrapper ?? options.defaultWrapper,
-    wrapperVariables: attributes.wrapperVariables ?? oldHighlightInfo?.wrapperVariables ?? {},
-    readOnly: attributes.readOnly ?? oldHighlightInfo?.readOnly ?? false,
-    startParagraphId: startParagraphId ?? oldHighlightInfo?.startParagraphId,
-    startParagraphOffset: startParagraphOffset ?? oldHighlightInfo?.startParagraphOffset,
-    endParagraphId: endParagraphId ?? oldHighlightInfo?.endParagraphId,
-    endParagraphOffset: endParagraphOffset ?? oldHighlightInfo?.endParagraphOffset,
-    // Read-only properties
-    escapedHighlightId: CSS.escape(highlightId),
-    rangeText: rangeText ?? oldHighlightInfo?.rangeText,
-    rangeHtml: rangeHtml ?? oldHighlightInfo?.rangeHtml,
-    rangeParagraphIds: rangeParagraphIds ?? oldHighlightInfo?.rangeParagraphIds,
-    rangeObj: highlightRange ?? oldHighlightInfo?.rangeObj,
+    // Sort highlights based on their order on the page
+    this._paragraphIdsMap ??= new Map(this._paragraphIds.map((id, i) => [id, i]));
+    const paragraphIdsMap = this._paragraphIdsMap;
+    highlights.sort((a, b) =>
+      (paragraphIdsMap.get(a.startParagraphId) - paragraphIdsMap.get(b.startParagraphId)) ||
+      (a.startParagraphOffset - b.startParagraphOffset)
+    );
+    return highlights;
   };
-  this._highlightsById[highlightId] = newHighlightInfo;
 
-  const detail = {
-    highlight: newHighlightInfo,
-    changes: appearanceChanges.concat(boundsChanges),
+  // Get highlights, wrappers, and hyperlinks at a given point
+  Highlighter.prototype.getTargetsAtPoint = function (clientX, clientY) {
+    const highlightIds = new Set();
+    const wrappers = [];
+    const hyperlinks = [];
+    const wrapperElements = new Set();
+    const targetElements = document.elementsFromPoint(clientX, clientY);
+    for (const element of targetElements) {
+      if (element === this._container) break;
+      if (element.matches('mark[data-hh-highlight-id]')) {
+        highlightIds.add(element.dataset.hhHighlightId);
+      }
+      const wrapper = element.closest('[data-hh-wrapper]');
+      if (wrapper && !wrapperElements.has(wrapper)) {
+        wrappers.push({
+          position: wrapper.dataset.hhPosition,
+          wrapperElement: wrapper,
+          highlight: this._highlightsById[wrapper.dataset.hhHighlightId],
+        });
+        wrapperElements.add(wrapper);
+      } else if (element.matches('a') && element.dataset.hhIndex) {
+        hyperlinks.push(this._hyperlinksByIndex[element.dataset.hhIndex]);
+      }
+    }
+    this._additionsRect = this._additionsDiv.getBoundingClientRect();
+    const x = clientX - this._additionsRect.left;
+    const y = clientY - this._additionsRect.top;
+    for (const highlightId of Object.keys(this._highlightsById)) {
+      if (highlightIds.has(highlightId)) continue;
+      const rangeLineRects = this._highlightsById[highlightId].rangeLineRects;
+      if (!rangeLineRects) continue;
+      for (const rect of rangeLineRects) {
+        const padding = rect.height / 8;
+        if (_isPointInRect(x, y, rect, padding)) { highlightIds.add(highlightId); break; }
+      }
+    }
+    return {
+      targetCount: highlightIds.size + wrappers.length + hyperlinks.length,
+      highlights: this.getHighlightInfo(highlightIds),
+      wrappers,
+      hyperlinks,
+    };
   }
 
-  if (triggeredByUserAction && !this._activeHighlightId) {
-    this.activateHighlight(highlightId);
-  } else if (this._activeHighlightId && highlightId === this._activeHighlightId && appearanceChanges.length > 0) {
-    this._updateSelectionUi('appearance');
-  } else if (highlightId !== this._activeHighlightId) {
-    this.drawHighlights([highlightId]);
+  // Update initialized options
+  Highlighter.prototype.setOptions = function (optionsToUpdate) {
+    const options = this._options;
+    for (const key in optionsToUpdate) {
+      if (['colorDefs', 'styleDefs', 'wrapperDefs'].includes(key) && optionsToUpdate[key] != null) {
+        options[key] = { ..._defaultOptions[key], ...options[key], ...optionsToUpdate[key] };
+      } else if (!Object.hasOwn(_defaultOptions, key)) {
+        console.warn(`Options key "${key}" is not recognized.`);
+      } else {
+        options[key] = optionsToUpdate[key] ?? options[key] ?? _defaultOptions[key];
+      }
+    }
+    if ('drawingMode' in optionsToUpdate || 'colorDefs' in optionsToUpdate) {
+      this._updateColorStylesheet();
+    }
+    if ('drawingMode' in optionsToUpdate || 'styleDefs' in optionsToUpdate) {
+      this.drawHighlights();
+    }
+    if ('dragHandles' in optionsToUpdate) {
+      for (const handle of this._dragHandles) {
+        handle.children[1].innerHTML = options.dragHandles[handle.dataset.hhSide] ?? '';
+      }
+    }
+    if ('enableHover' in optionsToUpdate && !optionsToUpdate.enableHover) this._hoverHash = null;
   }
 
-  if (isNewHighlight) {
-    this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightcreate', { detail: detail }));
-  } else {
-    this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightupdate', { detail: detail }));
-  }
-}
-
-// Activate a highlight by ID
-Highlighter.prototype.activateHighlight = function (highlightId) {
-  const highlightToActivate = this._highlightsById[highlightId];
-  if (highlightToActivate.readOnly) {
-    // If the highlight is read-only, return events, but don't actually activate it
-    this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightactivate', { detail: { highlight: highlightToActivate } }));
-    this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightdeactivate', { detail: { highlight: highlightToActivate } }));
-    return;
-  }
-  const selection = globalThis.getSelection();
-  const highlightRange = highlightToActivate.rangeObj.cloneRange();
-  this._activeHighlightId = highlightId;
-  this._updateSelectionUi('appearance');
-  this._updateSelectionUi('bounds');
-
-  // Update the selection range if needed
-  // In Android Chrome, sometimes selection handles don't show when a selection is updated programmatically, so it's best to only update the selection if needed.
-  let selectionRange = selection.type === 'Range' ? selection.getRangeAt(0) : null;
-  if (!selectionRange || !(
-    selectionRange.startContainer === highlightRange.startContainer &&
-    selectionRange.startOffset === highlightRange.startOffset &&
-    selectionRange.endContainer === highlightRange.endContainer &&
-    selectionRange.endOffset === highlightRange.endOffset)
-  ) {
-    selection.setBaseAndExtent(highlightRange.startContainer, highlightRange.startOffset, highlightRange.endContainer, highlightRange.endOffset);
+  // Get all of the initialized options
+  Highlighter.prototype.getOptions = function () {
+    return { ...this._options };
   }
 
-  this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightactivate', { detail: { highlight: highlightToActivate } }));
-}
-
-// Activate a link by position
-Highlighter.prototype.activateHyperlink = function (position) {
-  this.deactivateHighlights();
-  this._allowHyperlinkClick = true;
-  this._hyperlinksByPosition[position].hyperlinkElement.click();
-  this._allowHyperlinkClick = false;
-}
-
-// Deactivate any highlights that are currently active/selected
-Highlighter.prototype.deactivateHighlights = function (removeSelectionRanges = true) {
-  const deactivatedHighlight = this._highlightsById[this._activeHighlightId];
-  this._activeHighlightId = null;
-  this._previousSelectionRange = null;
-  const selection = globalThis.getSelection();
-  if (removeSelectionRanges && selection.anchorNode && this._annotatableContainer.contains(selection.anchorNode)) {
-    selection.collapseToStart();
+  // Get the current selection state. Returns the same object that arrives in the most recent hh:selectionchange event's detail.
+  Highlighter.prototype.getSelectionState = function () {
+    return { ...this._selectionState };
   }
-  this._updateSelectionUi('appearance');
-  if (deactivatedHighlight) {
-    this.drawHighlights([deactivatedHighlight.highlightId]);
-    this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightdeactivate', { detail: {
-      highlight: deactivatedHighlight,
-    }}));
-  }
-}
 
-// Remove the specified highlights, or all highlights on the page
-Highlighter.prototype.removeHighlights = function (highlightIds = Object.keys(this._highlightsById)) {
-  this.deactivateHighlights();
-  for (const highlightId of highlightIds) {
-    const highlightInfo = this._highlightsById[highlightId];
-    if (highlightInfo) {
+  // Remove the specified highlights, or all highlights on the page
+  Highlighter.prototype.removeHighlights = function (highlightIds = Object.keys(this._highlightsById)) {
+    this.deactivateHighlights();
+    this._undrawHighlights(highlightIds);
+    for (const highlightId of highlightIds) {
       delete this._highlightsById[highlightId];
-      this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightremove', { detail: {
+      this._container.dispatchEvent(new CustomEvent('hh:highlightremove', { detail: {
         highlightId: highlightId,
       }}));
-      this._undrawHighlight(highlightInfo);
     }
+    this._rebuildHighlightStylesheet();
   }
-}
 
-// Get the active highlight ID (if there is one)
-Highlighter.prototype.getActiveHighlightId = function () {
-  return this._activeHighlightId;
-}
+  // Remove this Highlighter instance and its highlights
+  Highlighter.prototype.removeHighlighter = function () {
+    this.loadHighlights([]);
+    this._additionsDiv.remove();
+    _removeStylesheets(this._stylesheets);
+    this._resizeObserver.disconnect();
+    this._controller.abort();
 
-// Get info for specified highlights, or all highlights on the page
-Highlighter.prototype.getHighlightInfo = function (highlightIds = Object.keys(this._highlightsById), paragraphId = null) {
-  let filteredHighlights = []
-  for (const highlightId of highlightIds) {
-    const highlightInfo = this._highlightsById[highlightId];
-    if (!paragraphId || paragraphId === highlightInfo.startParagraphId) {
-      filteredHighlights.push(highlightInfo);
-    }
+    delete this._container.dataset.hhContainer;
+    this._container.highlighter = undefined;
   }
-  // Sort highlights based on their order on the page
-  if (filteredHighlights.length > 0) {
-    filteredHighlights.sort((a, b) => {
-      return (this._annotatableParagraphIds.indexOf(a.startParagraphId) - this._annotatableParagraphIds.indexOf(b.startParagraphId)) || (a.startParagraphOffset - b.startParagraphOffset);
-    });
-  }
-  return filteredHighlights;
-}
-
-// Update one of the initialized options
-Highlighter.prototype.setOption = function (key, value) {
-  const options = this._options;
-  options[key] = value ?? options[key];
-  if (key === 'drawingMode' || key === 'styles') {
-    this._updateAppearanceStylesheet();
-    if (supportsHighlightApi) CSS.highlights.clear();
-    this.drawHighlights();
-  } else if (key === 'colors') {
-    this._updateAppearanceStylesheet();
-  } else if (key === 'containerSelector') {
-    this.removeHighlighter();
-    this._initializeHighlighter();
-    this._loadStyles();
-    this._loadEventListeners();
-    this._updateAppearanceStylesheet();
-    this._updateSelectionUi('appearance');
-    this.setOption('selectionHandles', options.selectionHandles);
-  } else if (key === 'paragraphSelector') {
-    this._initializeHighlighter();
-  } else if (key === 'selectionHandles') {
-    for (const selectionHandle of this._selectionHandles) {
-      selectionHandle.children[1].innerHTML = options.selectionHandles[selectionHandle.dataset.side] ?? '';
-    }
-  }
-}
 
-// Get all of the initialized options
-Highlighter.prototype.getOptions = function () {
-  return this._options;
-}
 
-// Remove this Highlighter instance and its highlights
-Highlighter.prototype.removeHighlighter = function () {
-  this.loadHighlights([]);
-  this._annotatableContainer.querySelectorAll('.hh-svg-background, .hh-selection-handle').forEach(el => el.remove())
-  removeStylesheets(this._stylesheets);
-  this._resizeObserver.disconnect();
-  this._controller.abort();
-
-  this._annotatableContainer.highlighter = undefined;
-  _highlighters = _highlighters.filter(h => h._annotatableContainer !== this._annotatableContainer);
-}
+  /********************** Private Methods **********************/
 
+  // Check if the tap hits any highlights, wrappers, or links
+  Highlighter.prototype._checkForTapTargets = function (pointerEvent) {
+    if (!pointerEvent) return;
+    const targets = this.getTargetsAtPoint(pointerEvent.clientX, pointerEvent.clientY);
+    return {
+      ...targets,
+      isLongPress: null,
+      selectionType: globalThis.getSelection().type,
+      activeHighlightId: this._activeHighlightId,
+      nativeEvent: pointerEvent,
+    };
+  }
 
-/********************** Private Methods **********************/
+  // Compare new highlight information to old highlight information, returning an object with the properties that changed
+  Highlighter.prototype._diffHighlight = function (newHighlightInfo, oldHighlightInfo) {
+    if (!oldHighlightInfo) return newHighlightInfo;
+    const changedHighlightInfo = { highlightId: newHighlightInfo.highlightId };
+    let hasChanges = false;
+    for (const key of Object.keys(newHighlightInfo)) {
+      const newVal = newHighlightInfo[key], oldVal = oldHighlightInfo[key];
+      const changed = (newVal !== null && typeof newVal === 'object') ? !_shallowEqual(newVal, oldVal ?? {}) : newVal != oldVal;
+      if (key !== 'highlightId' && Object.hasOwn(oldHighlightInfo, key) && changed) {
+        changedHighlightInfo[key] = newVal;
+        hasChanges = true;
+      }
+    }
+    return hasChanges ? changedHighlightInfo : null;
+  }
 
-// Check if the tap is in the range of an existing highlight or link
-Highlighter.prototype._checkForTapTargets = function (pointerEvent) {
-  if (!pointerEvent) return;
+  // Undraw the specified highlight
+  Highlighter.prototype._undrawHighlights = function (highlightIds = Object.keys(this._highlightsById)) {
+    const highlightIdsToNormalize = new Set(highlightIds);
+    const paragraphsToNormalize = new Set();
 
-  // Check for tapped highlights and hyperlinks
-  const tappedHighlights = [];
-  const tappedHyperlinks = [];
-  if (!pointerEvent.target.closest('[data-hh-ignore]')) {
-    for (const highlightId of Object.keys(this._highlightsById)) {
+    // Remove <mark> highlights and HTML wrappers; remove SVG highlights; collect paragraphs to normalize
+    for (const highlightId of highlightIds) {
       const highlightInfo = this._highlightsById[highlightId];
-      const highlightRange = highlightInfo.rangeObj;
-      for (const rangeRect of highlightRange.getClientRects()) {
-        if (this._isPointInRect(pointerEvent.clientX, pointerEvent.clientY, rangeRect, 5)) {
-          tappedHighlights.push(highlightInfo);
-          break;
+      if (!highlightInfo) continue;
+      // If removing a mark-elements highlight that's currently active, deactivate first to avoid an invalid selection range
+      if (highlightId === this._activeHighlightId && highlightInfo.resolvedDrawingMode === 'mark-elements') {
+        this.deactivateHighlights(true, false);
+      }
+      for (const element of this._container.querySelectorAll(`[data-hh-highlight-id="${highlightId}"]`)) {
+        if (element.matches('g')) {
+          element.remove();
+          continue;
+        }
+        if (element.parentElement?.dataset?.hhHighlightId) {
+          highlightIdsToNormalize.add(element.parentElement.dataset.hhHighlightId);
+        }
+        for (const childHighlight of element.querySelectorAll('[data-hh-highlight-id]')) {
+          highlightIdsToNormalize.add(childHighlight.dataset.hhHighlightId);
+        }
+        if (element.matches('mark')) {
+          element.replaceWith(...element.childNodes);
+        } else {
+          if (element.matches('[data-hh-wrapper]')) {
+            this._wrapperElements.delete(`${element.dataset.hhHighlightId}:${element.dataset.hhPosition}`);
+          }
+          element.remove();
         }
       }
+
+      // Collect paragraphs to normalize
+      paragraphsToNormalize.add(highlightInfo.startParagraphId);
+      paragraphsToNormalize.add(highlightInfo.endParagraphId);
     }
-    for (const hyperlinkInfo of Object.values(this._hyperlinksByPosition)) {
-      if (pointerEvent.target.closest('a') === hyperlinkInfo.hyperlinkElement) {
-        tappedHyperlinks.push(hyperlinkInfo);
+
+    // Normalize paragraphs, then recalculate ranges for all highlights
+    if (paragraphsToNormalize.size > 0) {
+      for (const paragraphId of paragraphsToNormalize) {
+        const paragraph = document.getElementById(paragraphId);
+        if (paragraph) paragraph.normalize();
+      }
+      // After normalizing, the highlight range is valid, but not correct. Passing true forces the range to be recalculated.
+      for (const highlightId of highlightIdsToNormalize) {
+        this._getCorrectedRangeObj(highlightId, true);
       }
     }
-  }
 
-  // Sort highlights (hyperlinks should already be sorted)
-  const tappedHighlightIds = [];
-  for (const highlightInfo of tappedHighlights) tappedHighlightIds.push(highlightInfo.highlightId);
-  const sortedTappedHighlights = this.getHighlightInfo(tappedHighlightIds);
-
-  return {
-    'targetFound': sortedTappedHighlights.length > 0 || tappedHyperlinks.length > 0,
-    'tapRange': this._getCaretFromCoordinates(pointerEvent.clientX, pointerEvent.clientY),
-    'pointerEvent': pointerEvent,
-    'highlights': sortedTappedHighlights,
-    'hyperlinks': tappedHyperlinks,
+    // Remove Highlight API highlights
+    // Instead of a global CSS.highlights.clear(), only clear CSS highlights in this Highlighter instance
+    if (supportsHighlightApi) {
+      for (const highlightId of highlightIds) {
+        CSS.highlights.delete(highlightId);
+      }
+    }
   }
-}
 
-// Compare new highlight information to old highlight information, returning an object with the properties that changed
-Highlighter.prototype._diffHighlight = function (newHighlightInfo, oldHighlightInfo) {
-  if (!oldHighlightInfo) return newHighlightInfo;
-  const changedHighlightInfo = {}
-  for (const key of Object.keys(newHighlightInfo)) {
-    if (Object.hasOwn(oldHighlightInfo, key) && oldHighlightInfo[key] !== newHighlightInfo[key]) {
-      changedHighlightInfo[key] = newHighlightInfo[key];
+  // Rebuild the per-highlight stylesheet from scratch using all active highlights
+  Highlighter.prototype._rebuildHighlightStylesheet = function () {
+    let cssText = '';
+    for (const highlightInfo of Object.values(this._highlightsById)) {
+      const resolvedMode = highlightInfo.resolvedDrawingMode;
+      if (resolvedMode === 'highlight-api' || resolvedMode === 'mark-elements') {
+        const styleString = this._getStyleString(highlightInfo.style, 'css', false, highlightInfo.variables, highlightInfo.rangeRect);
+        if (resolvedMode === 'highlight-api') {
+          const colorString = this._options.colorDefs[highlightInfo.color];
+          cssText += `${this._containerSelector} ::highlight(${highlightInfo.escapedHighlightId}) { --hh-color: ${colorString}; ${styleString} }\n`;
+          cssText += `${this._containerSelector} :is(rt, img)::highlight(${highlightInfo.escapedHighlightId}) { color: inherit; background-color: transparent; }\n`;
+        } else {
+          cssText += `mark[data-hh-highlight-id=${highlightInfo.escapedHighlightId}][data-hh-style] { ${styleString} }\n`;
+        }
+      }
     }
+    this._highlightStylesheet.replaceSync(cssText);
   }
-  return changedHighlightInfo;
-}
 
-// Undraw the specified highlight
-Highlighter.prototype._undrawHighlight = function (highlightInfo) {
-  const highlightId = highlightInfo.highlightId;
+  // Update selection background, handles, and state object
+  Highlighter.prototype._updateSelectionState = function () {
+    const options = this._options;
+    const selection = globalThis.getSelection();
 
-  // Remove <mark> highlights and HTML wrappers
-  const overlappingHighlightIds = new Set();
-  this._annotatableContainer.querySelectorAll(`[data-highlight-id="${highlightId}"]:not(g)`).forEach(element => {
-    if (element.parentElement.dataset.highlightId) {
-      overlappingHighlightIds.add(element.parentElement.dataset.highlightId);
-    }
-    for (const childHighlight of element.querySelectorAll('[data-highlight-id]')) {
-      overlappingHighlightIds.add(childHighlight.dataset.highlightId);
-    }
-    if (element.matches('mark')) {
-      element.outerHTML = element.innerHTML;
-    } else {
-      element.remove();
+    // If the selection starts in another container, let the other container handle it
+    const selectionContainer = this._getSelectionContainer();
+    if (selectionContainer && selectionContainer !== this._container) return;
+    this._containerRect = this._container.getBoundingClientRect();
+    this._additionsRect = this._additionsDiv.getBoundingClientRect();
+
+    // Get bounds hash
+    let selectionRange, boundsHash;
+    if (selection.type !== 'None') {
+      selectionRange = selection.getRangeAt(0);
+      const clientRects = selectionRange.getClientRects();
+      const firstRect = clientRects[0];
+      const lastRect = clientRects[clientRects.length - 1];
+      if (firstRect && lastRect) {
+        boundsHash = `${selection.type}-${Math.round(firstRect.top)},${Math.round(firstRect.left)},${Math.round(firstRect.right)}-${Math.round(lastRect.bottom)},${Math.round(lastRect.left)},${Math.round(lastRect.right)}`;
+      }
     }
-  });
 
-  // Redraw overlapping highlights
-  overlappingHighlightIds.delete(highlightId);
-  if (overlappingHighlightIds.size > 0) {
-    for (const overlappingHighlightId of overlappingHighlightIds) {
-      this._undrawHighlight(this._highlightsById[overlappingHighlightId]);
+    // Get active highlight properties
+    const activeHighlightId = this._activeHighlightId;
+    const highlightInfo = this._highlightsById[activeHighlightId] ?? null;
+    const isSvgActive = activeHighlightId && highlightInfo?.resolvedDrawingMode === 'svg';
+    const color = highlightInfo?.color ?? null;
+    const style = highlightInfo?.style ?? null;
+    const variables = highlightInfo?.variables ?? {};
+
+    // Check which properties changed
+    const isResizing = this._isResizingSelection;
+    const pointerType = this._pointerType;
+    const prev = this._selectionState;
+    const changes = [];
+    if (activeHighlightId !== prev.activeHighlightId) changes.push('activeHighlightId');
+    if (color !== prev.color) changes.push('color');
+    if (style !== prev.style) changes.push('style');
+    if (!_shallowEqual(variables, prev.variables ?? {})) changes.push('variables');
+    if (isResizing !== prev.isResizing) changes.push('isResizing');
+    if (pointerType !== prev.pointerType) changes.push('pointerType');
+    if (boundsHash != this._previousBoundsHash) changes.push('selection');
+    if (changes.length === 0) return;
+
+    // Get range metadata
+    let rangeText = null, rangeHtml = null, rangeParagraphIds = null, rangeObj = null;
+    let rangeRect = null, rangeParagraphs = [], rangeLineRects = [];
+    if (selectionRange) {
+      const startParagraph = this._closestValidParagraph(selectionRange.startContainer.parentElement);
+      const endParagraph = this._closestValidParagraph(selectionRange.endContainer.parentElement) ?? startParagraph;
+      if (startParagraph && endParagraph) {
+        if (startParagraph === endParagraph) {
+          rangeParagraphs = [startParagraph];
+        } else {
+          const startIdx = this._paragraphs.indexOf(startParagraph);
+          const endIdx = this._paragraphs.indexOf(endParagraph);
+          rangeParagraphs = this._paragraphs.slice(startIdx, endIdx + 1);
+        }
+        ([rangeRect, rangeLineRects] = this._getRangeRects(selectionRange, rangeParagraphs));
+      }
+      rangeParagraphIds = rangeParagraphs.map(p => p.id);
+      rangeObj = selectionRange;
+      ({ rangeHtml, rangeText } = this._getRangeContent(selectionRange, true, false));
     }
-    this.drawHighlights(overlappingHighlightIds);
-  }
 
-  // Normalize text nodes
-  const rangeParagraphs = this._annotatableContainer.querySelectorAll(`#${highlightInfo.startParagraphId}, #${highlightInfo.endParagraphId}`);
-  rangeParagraphs.forEach(p => p.normalize());
-  this._getCorrectedRangeObj(highlightId);
+    // Update selection state
+    this._selectionState = { activeHighlightId, color, style, variables, isResizing, pointerType, selection, changes, rangeText, rangeHtml, rangeRect: rangeRect, rangeLineRects, rangeParagraphIds, rangeObj };
+    this._previousBoundsHash = boundsHash;
 
-  // Remove SVG highlights
-  this._svgBackground.querySelectorAll(`g[data-highlight-id="${highlightId}"]`).forEach(element => {
-    element.remove();
-  });
+    // Draw SVG selection rects (SVG drawing mode only)
+    this._svgActiveOverlay.innerHTML = '';
+    if (isSvgActive) {
+      this._svgActiveOverlay.dataset.hhColor = color;
+      this._svgActiveOverlay.dataset.hhStyle = style;
+      let svgContent = '';
+      for (const lineRect of rangeLineRects) {
+        svgContent += this._getStyleString(highlightInfo.style, 'svg', true, highlightInfo.variables, highlightInfo.rangeRect, lineRect);
+      }
+      this._svgActiveOverlay.innerHTML = svgContent;
 
-  // Remove Highlight API highlights
-  if (supportsHighlightApi && CSS.highlights.has(highlightId)) {
-    const ruleIndexesToDelete = [];
-    for (let r = 0; r < this._highlightApiStylesheet.cssRules.length; r++) {
-      if (this._highlightApiStylesheet.cssRules[r].selectorText.includes(`::highlight(${highlightInfo.escapedHighlightId})`)) ruleIndexesToDelete.push(r);
+      // Bring active highlight to the front
+      const svgHighlight = this._svgBackground.querySelector(`g[data-hh-highlight-id="${activeHighlightId}"]`);
+      if (svgHighlight) this._svgBackground.appendChild(svgHighlight);
+      this._svgBackground.appendChild(this._svgActiveOverlay);
     }
-    for (const index of ruleIndexesToDelete.toReversed()) this._highlightApiStylesheet.deleteRule(index);
-    CSS.highlights.delete(highlightId);
-  }
-}
-
-// Update selection background and handles
-Highlighter.prototype._updateSelectionUi = function (changeType = 'appearance') {
-  const options = this._options;
-  const selection = globalThis.getSelection();
-  const selectionRange = selection.type === 'None' ? null : selection.getRangeAt(0);
-
-  // If the selection starts in another annotatable container, let the other container handle it
-  if (selection.anchorNode?.parentElement?.closest('[data-hh-container]') && !this._annotatableContainer.contains(selection.anchorNode)) return;
-
-  const highlightInfo = this._highlightsById[this._activeHighlightId] ?? null;
-  const color = highlightInfo?.color ?? null;
-  const style = highlightInfo?.style ?? null;
-  const colorString = options.colors[color] ?? (CSS.supports('color', 'AccentColor') ? 'AccentColor' : 'dodgerblue');
-
-  // Draw SVG selection rects (SVG drawing mode only)
-  this._svgActiveOverlay.innerHTML = '';
-  if (this._activeHighlightId && options.drawingMode === 'svg') {
-    let range = this._getCorrectedRangeObj(this._activeHighlightId);
-    const rangeParagraphs = this._annotatableContainer.querySelectorAll(`#${highlightInfo.rangeParagraphIds.join(', #')}`);
-    const clientRects = this._getMergedClientRects(range, rangeParagraphs);
-    this._svgActiveOverlay.dataset.color = color;
-    this._svgActiveOverlay.dataset.style = style;
-    let svgContent = '';
-    for (const clientRect of clientRects) {
-      svgContent += this._getStyleTemplate(highlightInfo.style, 'svg', clientRect, true);
-    }
-    this._svgActiveOverlay.innerHTML = svgContent;
-
-    // Bring active highlight to the front
-    const svgHighlight = this._svgBackground.querySelector(`g[data-highlight-id="${this._activeHighlightId}"]`);
-    if (svgHighlight) this._svgBackground.appendChild(svgHighlight);
-    this._svgBackground.appendChild(this._svgActiveOverlay);
-  }
 
-  if (changeType === 'appearance') {
-    this._annotatableContainer.style.setProperty('--hh-color', colorString);
-
-    // Hide the active highlight (and wrappers), and set a selection style that mimics the highlight. This avoids the need to redraw the highlight while actively editing it (especially important for <mark> highlights, because DOM manipulation around the selection can make the selection UI unstable).
-    if (this._activeHighlightId && options.drawingMode === 'svg') {
-      this._selectionStylesheet.replaceSync(`
-        ${options.containerSelector} g[data-highlight-id="${this._activeHighlightId}"][data-style] { display: none; }
-        ${options.containerSelector} .hh-wrapper-start[data-highlight-id="${this._activeHighlightId}"], .hh-wrapper-end[data-highlight-id="${this._activeHighlightId}"] { display: none; }
-        ${options.containerSelector} ::selection { background-color: transparent; }
-      `);
-    } else if (this._activeHighlightId) {
-      const styleTemplate = this._getStyleTemplate(style, 'css', null, true);
-      this._selectionStylesheet.replaceSync(`
-        ${options.containerSelector} ::highlight(${highlightInfo.escapedHighlightId}) { all: unset; }
-        ${options.containerSelector} mark[data-highlight-id="${this._activeHighlightId}"][data-style] { all: unset; }
-        ${options.containerSelector} .hh-wrapper-start[data-highlight-id="${this._activeHighlightId}"], .hh-wrapper-end[data-highlight-id="${this._activeHighlightId}"] { display: none; }
-        ${options.containerSelector} ::selection { --hh-color: ${colorString}; ${styleTemplate} }
-        ${options.containerSelector} rt::selection, ${options.containerSelector} img::selection { background-color: transparent; }
-      `);
-
-    // No active highlight (show the regular selection UI)
-    } else {
-      this._selectionStylesheet.replaceSync(`
-        ${options.containerSelector} ::selection { background-color: Highlight; color: inherit; }
-        ${options.containerSelector} rt::selection, ${options.containerSelector} img::selection { background-color: transparent; }
-      `);
+    // Update selection stylesheet
+    if (['activeHighlightId', 'color', 'style', 'variables'].some(ch => changes.includes(ch))) {
+      const colorString = options.colorDefs[color] ?? (supportsAccentColor ? 'AccentColor' : 'dodgerblue');
+      this._container.style.setProperty('--hh-color', colorString);
+
+      // Hide the active highlight (and wrappers), and set a selection style that mimics the highlight. This avoids the need to redraw the highlight while actively editing it (especially important for <mark> highlights, because DOM manipulation around the selection can make the selection UI unstable).
+      if (isSvgActive) {
+        this._selectionStylesheet.replaceSync(`
+          ${this._containerSelector} g[data-hh-highlight-id="${activeHighlightId}"][data-hh-style] { display: none; }
+          ${this._containerSelector} [data-hh-wrapper][data-hh-highlight-id="${activeHighlightId}"] { visibility: hidden; }
+          ${this._containerSelector} ::selection { background-color: transparent; }
+        `);
+      } else if (activeHighlightId) {
+        // Remove stale SVG highlight if a highlight switches from SVG to a different resolvedDrawingMode
+        for (const svgHighlight of this._svgBackground.querySelectorAll(`g[data-hh-highlight-id="${activeHighlightId}"]`)) {
+          svgHighlight.remove();
+        }
+        const styleString = this._getStyleString(style, 'css', true, highlightInfo.variables, highlightInfo.rangeRect);
+        this._selectionStylesheet.replaceSync(`
+          ${this._containerSelector} ::highlight(${highlightInfo.escapedHighlightId}) { all: unset; }
+          ${this._containerSelector} mark[data-hh-highlight-id="${activeHighlightId}"][data-hh-style] { all: unset; }
+          ${this._containerSelector} [data-hh-wrapper][data-hh-highlight-id="${activeHighlightId}"] { visibility: hidden; }
+          ${this._containerSelector} ::selection { --hh-color: ${colorString}; ${styleString} }
+          ${this._containerSelector} rt::selection, ${this._containerSelector} img::selection { background-color: transparent; }
+        `);
+
+      // No active highlight (show the regular selection UI)
+      } else {
+        this._selectionStylesheet.replaceSync(`
+          ${this._containerSelector} ::selection { background-color: Highlight; color: inherit; }
+          ${this._containerSelector} rt::selection, ${this._containerSelector} img::selection { background-color: transparent; }
+        `);
+      }
     }
 
-    // Send event
-    this._annotatableContainer.dispatchEvent(new CustomEvent('hh:selectionupdate', { detail: { color: color, style: style, }}));
-
-  } else if (changeType === 'bounds') {
     // Update selection handle location and visibility
-    if (selection.type === 'Range') {
-      const selectionRangeRects = selectionRange.getClientRects();
-      const startRect = selectionRangeRects[0];
-      const endRect = selectionRangeRects[selectionRangeRects.length - 1];
-      const relativeAncestorClientRect = this._relativeAncestorElement.getBoundingClientRect();
+    const showDragHandles =
+      (options.showDragHandles.includes('touch') || pointerType === 'mouse')
+      && (options.showDragHandles.includes('highlights') && activeHighlightId
+        || options.showDragHandles.includes('selection') && !activeHighlightId);
+    if (selection.type === 'Range' && showDragHandles) {
       const startNodeIsRtl = globalThis.getComputedStyle(selectionRange.startContainer.parentElement).direction === 'rtl';
       const endNodeIsRtl = globalThis.getComputedStyle(selectionRange.endContainer.parentElement).direction === 'rtl';
-
-      if (
-        (options.showCustomSelectionHandlesOnTouch || this._pointerType === 'mouse')
-        && ((options.showCustomSelectionHandlesForActiveHighlights && this._activeHighlightId)
-          || (options.showCustomSelectionHandlesForTextSelection && !this._activeHighlightId))
-      ) {
-        for (const selectionHandle of this._selectionHandles) {
-          let side;
-          if (selectionHandle.dataset.position === 'start') {
-            side = startNodeIsRtl ? 'right' : 'left';
-            selectionHandle.style.left = startRect[side] - relativeAncestorClientRect.left + 'px';
-            selectionHandle.style.height = startRect.height + 'px';
-            selectionHandle.style.top = startRect.top - relativeAncestorClientRect.top + 'px';
-          } else {
-            side = endNodeIsRtl ? 'left' : 'right';
-            selectionHandle.style.left = endRect[side] - relativeAncestorClientRect.left + 'px';
-            selectionHandle.style.height = endRect.height + 'px';
-            selectionHandle.style.top = endRect.top - relativeAncestorClientRect.top + 'px';
-          }
-          if (selectionHandle.dataset.side !== side) {
-            selectionHandle.dataset.side = side;
-            this.setOption('selectionHandles', options.selectionHandles);
-          }
+      for (const handle of this._dragHandles) {
+        let side;
+        const startRect = rangeLineRects[0];
+        const endRect = rangeLineRects.at(-1);
+        if (handle.dataset.hhPosition === 'start') {
+          side = startNodeIsRtl ? 'right' : 'left';
+          handle.style.left = startRect[side] + 'px';
+          handle.style.height = startRect.height + 'px';
+          handle.style.top = startRect.top + 'px';
+        } else {
+          side = endNodeIsRtl ? 'left' : 'right';
+          handle.style.left = endRect[side] + 'px';
+          handle.style.height = endRect.height + 'px';
+          handle.style.top = endRect.top + 'px';
+        }
+        if (handle.dataset.hhSide !== side) {
+          handle.dataset.hhSide = side;
+          this.setOptions({ dragHandles: options.dragHandles });
         }
-        this._setCustomSelectionHandleVisibility(true);
       }
+      this._setDragHandleVisibility(true);
     } else {
-      this._setCustomSelectionHandleVisibility(false);
+      this._setDragHandleVisibility(false);
     }
-  }
-}
 
-Highlighter.prototype._setCustomSelectionHandleVisibility = function (visible = this._selectionHandles[0].style.visibility === 'hidden') {
-  for (const selectionHandle of this._selectionHandles) {
-    selectionHandle.style.visibility = visible ? 'visible' : 'hidden';
+    // Send event
+    this._container.dispatchEvent(new CustomEvent('hh:selectionchange', { detail: this._selectionState }));
   }
-}
-
-// Update the selection or highlight range to stay within the annotatable container
-Highlighter.prototype._snapRangeToBoundaries = function (range, anchorNode = null) {
-  const options = this._options;
-  let startNode = range.startContainer;
-  let endNode = range.endContainer;
-  let startOffset = range.startOffset;
-  let endOffset = range.endOffset;
-
-  // Prevent the range from going outside of the annotatable container
-  if (!this._annotatableContainer.contains(range.commonAncestorContainer)) {
-    if (anchorNode && !this._annotatableContainer.contains(anchorNode)) {
-      // Range is from a selection, and the selection anchor is outside of the container
-      return range.cloneRange().collapse(true);
-    } else if (anchorNode === startNode || this._annotatableContainer.contains(startNode)) {
-      // Range starts in the container but ends outside
-      endNode = this._getLastTextNode(this._annotatableParagraphs[this._annotatableParagraphs.length - 1]);
-      endOffset = endNode.length;
-    } else if (anchorNode === endNode || this._annotatableContainer.contains(endNode)) {
-      // Range starts outside of the container but ends inside
-      startNode = this._getFirstTextNode(this._annotatableParagraphs[0]);
-      startOffset = 0;
+
+  Highlighter.prototype._setDragHandleVisibility = function (visible = this._dragHandles[0].style.visibility === 'hidden') {
+    for (const handle of this._dragHandles) {
+      handle.style.visibility = visible ? 'visible' : 'hidden';
     }
   }
 
-  // Prevent the range from starting or ending in an invalid text node
-  if (this._annotatableContainer.contains(range.commonAncestorContainer) && (this._shouldSkipTextNode(startNode) || this._shouldSkipTextNode(endNode))) {
-    if (this._shouldSkipTextNode(startNode)) {
-      startNode = this._getNextValidTextNode(startNode);
-      startOffset = 0;
-    }
-    if (this._shouldSkipTextNode(endNode)) {
-      endNode = this._getPreviousValidTextNode(endNode);
-      endOffset = endNode.length;
-    }
-    if (!startNode || !endNode || (startNode === endNode && startOffset === endOffset)) {
-      return range.cloneRange().collapse(true);
-    } else if (startNode === endNode && endOffset < startOffset) {
-      [startOffset, endOffset] = [endOffset, startOffset];
+  Highlighter.prototype._getSelectionContainer = function () {
+    const selection = globalThis.getSelection();
+    return selection.anchorNode?.parentElement?.closest('[data-hh-container]') ?? null;
+  }
+
+  // Update the selection or highlight range to stay within the container
+  Highlighter.prototype._snapRangeToBoundaries = function (range, anchorNode = null) {
+    const options = this._options;
+    let startNode = range.startContainer;
+    let endNode = range.endContainer;
+    let startOffset = range.startOffset;
+    let endOffset = range.endOffset;
+
+    // Prevent the range from going outside of the container
+    if (!this._container.contains(range.commonAncestorContainer)) {
+      if (anchorNode && !this._container.contains(anchorNode)) {
+        // Range is from a selection, and the selection anchor is outside of the container
+        return range.cloneRange().collapse(true);
+      } else if (anchorNode === startNode || this._container.contains(startNode)) {
+        // Range starts in the container but ends outside
+        endNode = this._getLastTextNode(this._paragraphs[this._paragraphs.length - 1]);
+        endOffset = endNode.length;
+      } else if (anchorNode === endNode || this._container.contains(endNode)) {
+        // Range starts outside of the container but ends inside
+        startNode = this._getFirstTextNode(this._paragraphs[0]);
+        startOffset = 0;
+      }
     }
-  }
 
-  // Snap to the nearest word
-  if (options.snapToWord) {
-    // If the range starts at the end of a text node, move it to start at the beginning of the following text node. This prevents the range from jumping across the text node boundary and selecting an extra word.
-    if (startOffset === startNode.textContent.length) {
+    // If the range starts at the end of a text node, move it to start at the beginning of the following text node
+    if (startOffset === startNode.textContent.length && this._activeHighlightId) {
       const walker = this._getTextNodeWalker(range.commonAncestorContainer);
       walker.currentNode = startNode;
       const nextTextNode = walker.nextNode();
@@ -1106,475 +1346,760 @@ Highlighter.prototype._snapRangeToBoundaries = function (range, anchorNode = nul
       }
     }
 
-    // Trim whitespace and dashes at range start and end
-    while (_reWhitespaceDash.test(startOffset < startNode.textContent.length && startNode.textContent[startOffset])) startOffset += 1;
-    while (endOffset > 0 && _reWhitespaceDash.test(endNode.textContent[endOffset - 1])) endOffset -= 1;
+    // Prevent the range from starting or ending in an invalid text node
+    const skipStart = this._shouldSkipTextNode(startNode);
+    const skipEnd = this._shouldSkipTextNode(endNode);
+    if (this._container.contains(range.commonAncestorContainer) && (skipStart || skipEnd)) {
+      if (skipStart) {
+        startNode = this._getNextValidTextNode(startNode);
+        startOffset = 0;
+      }
+      if (skipEnd) {
+        endNode = this._getPreviousValidTextNode(endNode);
+        endOffset = endNode.length;
+      }
+      if (!startNode || !endNode || (startNode === endNode && startOffset === endOffset)) {
+        return range.cloneRange().collapse(true);
+      } else if (startNode === endNode && endOffset < startOffset) {
+        [startOffset, endOffset] = [endOffset, startOffset];
+      }
+    }
+
+    // Snap to the nearest word
+    if (options.snapToWord) {
+      const startText = startNode.data;
+      const endText = endNode.data;
+      // Trim whitespace and dashes at range start and end
+      while (_reWhitespaceDash.test(startOffset < startText.length && startText[startOffset])) startOffset += 1;
+      while (endOffset > 0 && _reWhitespaceDash.test(endText[endOffset - 1])) endOffset -= 1;
+
+      // Expand range to word boundaries
+      while (startOffset > 0 && _reNonWhitespaceDash.test(startText[startOffset - 1])) startOffset -= 1;
+      while (endOffset < endText.length && _reNonWhitespaceDash.test(endText[endOffset])) endOffset += 1;
+    }
 
-    // Expand range to word boundaries
-    while (startOffset > 0 && _reNonWhitespaceDash.test(startNode.textContent[startOffset - 1])) startOffset -= 1;
-    while (endOffset < endNode.textContent.length && _reNonWhitespaceDash.test(endNode.textContent[endOffset])) endOffset += 1;
+    const newRange = document.createRange();
+    newRange.setStart(startNode, startOffset);
+    newRange.setEnd(endNode, endOffset);
+    return newRange;
   }
 
-  const newRange = document.createRange();
-  newRange.setStart(startNode, startOffset);
-  newRange.setEnd(endNode, endOffset);
-  return newRange;
-}
-
-// Get the character offset relative to the annotatable paragraph
-Highlighter.prototype._getParagraphOffset = function (referenceTextNode, referenceTextNodeOffset) {
-  const paragraph = referenceTextNode.parentElement.closest(this._options.paragraphSelector);
-  const walker = this._getTextNodeWalker(paragraph);
-  let currentOffset = 0;
-  let textNode;
-  while (textNode = walker.nextNode()) {
-    if (textNode === referenceTextNode) {
-      currentOffset += referenceTextNodeOffset;
-      break;
-    }
-    currentOffset += textNode.textContent.length;
+  // Get a character offset relative to the paragraph
+  Highlighter.prototype._getParagraphOffset = function (referenceTextNode, referenceTextNodeOffset) {
+    const paragraph = this._closestValidParagraph(referenceTextNode.parentElement);
+    const walker = this._getTextNodeWalker(paragraph);
+    let currentOffset = 0;
+    let textNode;
+    while (textNode = walker.nextNode()) {
+      if (textNode === referenceTextNode) {
+        currentOffset += referenceTextNodeOffset;
+        break;
+      }
+      currentOffset += textNode.length;
+    }
+    return [ paragraph.id, currentOffset ];
   }
-  return [ paragraph.id, currentOffset ];
-}
-
-// Get the character offset relative to the deepest relevant text node
-Highlighter.prototype._getTextNodeAndOffset = function (parentElement, targetOffset) {
-  let textNode, firstTextNode, currentOffset = 0;
-  const walker = this._getTextNodeWalker(parentElement);
-  while (textNode = walker.nextNode()) {
-    if (!firstTextNode) firstTextNode = walker.currentNode;
-    currentOffset += textNode.textContent.length;
-    if (currentOffset >= targetOffset) {
-      const relativeOffset = textNode.textContent.length - currentOffset + targetOffset
-      return [ textNode, relativeOffset ];
+
+  // Get the character offset relative to the deepest relevant text node
+  Highlighter.prototype._getTextNodeAndOffset = function (parentElement, targetOffset, position) {
+    let textNode, firstTextNode, currentOffset = 0;
+    const walker = this._getTextNodeWalker(parentElement);
+    while (textNode = walker.nextNode()) {
+      if (!firstTextNode) firstTextNode = textNode;
+      const nodeLength = textNode.length;
+      currentOffset += nodeLength;
+      if (currentOffset >= targetOffset) {
+        const relativeOffset = nodeLength - currentOffset + targetOffset;
+        // If the start offset is at the end of a text node, move it to the beginning of the next text node
+        if (position === 'start' && relativeOffset === nodeLength) {
+          const nextTextNode = walker.nextNode();
+          if (nextTextNode) return [ nextTextNode, 0 ];
+        }
+        return [ textNode, relativeOffset ];
+      }
+    }
+    // TODO: Direction isn't always accurate (maybe it resets when selection is cleared and set to a new range programmatically?)
+    const direction = globalThis.getSelection().direction;
+    if (direction == 'backward') {
+      return [ firstTextNode, 0 ];
+    } else {
+      const lastTextNode = walker.currentNode;
+      return [ lastTextNode, lastTextNode.length ];
     }
   }
-  // TODO: Direction isn't always accurate (maybe it resets when selection is cleared and set to a new range programmatically?)
-  const direction = globalThis.getSelection().direction;
-  if (direction == 'backward') {
-    return [ firstTextNode, 0 ];
-  } else {
-    const lastTextNode = walker.currentNode;
-    return [ lastTextNode, lastTextNode.textContent.length ];
+
+  // Get the first valid text node in an element
+  Highlighter.prototype._getFirstTextNode = function (element) {
+    const walker = this._getTextNodeWalker(element);
+    return walker.nextNode();
   }
-}
-
-// Get the first valid text node in an element
-Highlighter.prototype._getFirstTextNode = function (element) {
-  const walker = this._getTextNodeWalker(element);
-  return walker.nextNode();
-}
-
-// Get the last valid text node in an element
-Highlighter.prototype._getLastTextNode = function (element) {
-  const walker = this._getTextNodeWalker(element);
-  let lastNode = null, node;
-  while (node = walker.nextNode()) lastNode = node;
-  return lastNode;
-}
-
-// Get the previous valid text node in the annotatable container
-Highlighter.prototype._getNextValidTextNode = function (currentNode) {
-  const walker = this._getTextNodeWalker(this._annotatableContainer);
-  walker.currentNode = currentNode;
-  return walker.nextNode();
-}
-
-// Get the next valid text node in the annotatable container
-Highlighter.prototype._getPreviousValidTextNode = function (currentNode) {
-  const walker = this._getTextNodeWalker(this._annotatableContainer);
-  walker.currentNode = currentNode;
-  return walker.previousNode();
-}
-
-// Determine if text node should be skipped when snapping to word or calculating character offsets
-Highlighter.prototype._shouldSkipTextNode = function (textNode) {
-  const parentParagraph = textNode.parentNode.closest(this._options.paragraphSelector);
-  const hhIgnore = textNode.parentNode.closest('[data-hh-ignore]');
-  if (!parentParagraph || hhIgnore || textNode.textContent === '') return true;
-  return false;
-}
-
-// Get text node walker
-Highlighter.prototype._getTextNodeWalker = function (root) {
-  return document.createTreeWalker(root, NodeFilter.SHOW_TEXT, (node) => this._shouldSkipTextNode(node) ? NodeFilter.FILTER_SKIP : NodeFilter.FILTER_ACCEPT);
-}
-
-// Update appearance stylesheet (user-defined colors and styles)
-Highlighter.prototype._updateAppearanceStylesheet = function () {
-  const options = this._options;
-  this._appearanceStylesheet.replaceSync('');
-  for (const color of Object.keys(options.colors)) {
-    this._appearanceStylesheet.insertRule(`[data-color="${color}"] { --hh-color: ${options.colors[color]}; }`);
+
+  // Get the last valid text node in an element
+  Highlighter.prototype._getLastTextNode = function (element) {
+    const walker = this._getTextNodeWalker(element);
+    let lastNode = null, node;
+    while (node = walker.nextNode()) lastNode = node;
+    return lastNode;
   }
-  for (const style of Object.keys(options.styles)) {
-    const styleTemplate = this._getStyleTemplate(style, 'css', null);
-    this._appearanceStylesheet.insertRule(`mark[data-highlight-id][data-style="${style}"] { ${styleTemplate} }`);
+
+  // Get the next valid text node in the container
+  Highlighter.prototype._getNextValidTextNode = function (currentNode) {
+    const walker = this._getTextNodeWalker();
+    walker.currentNode = currentNode;
+    return walker.nextNode();
   }
-}
-
-// Get style template for a given highlight style
-Highlighter.prototype._getStyleTemplate = function (style, type, clientRect = null, active = false) {
-  const options = this._options;
-  style = Object.hasOwn(options.styles, style) ? style : options.defaultStyle;
-  let styleTemplate = options.styles[style]?.[type] ?? '';
-  if (active) {
-    styleTemplate = options.styles[style]?.[`${type}-active`] ?? styleTemplate;
+
+  // Get the previous valid text node in the container
+  Highlighter.prototype._getPreviousValidTextNode = function (currentNode) {
+    const walker = this._getTextNodeWalker();
+    walker.currentNode = currentNode;
+    return walker.previousNode();
   }
-  if (!styleTemplate) {
-    console.warn(`Highlight style "${style}" in options does not have a defined "${type}" value.`);
-    return;
+
+  // Determine if text node should be skipped when snapping to word or calculating character offsets
+  Highlighter.prototype._shouldSkipTextNode = function (textNode) {
+    const parentParagraph = this._closestValidParagraph(textNode.parentNode);
+    const ignoreParent = textNode.parentNode.closest('[data-hh-ignore]');
+    if (!parentParagraph || ignoreParent || textNode.textContent === '') return true;
+    return false;
   }
-  if (type === 'svg' && clientRect) {
-    const relativeAncestorClientRect = this._relativeAncestorElement.getBoundingClientRect();
-    styleTemplate = styleTemplate
-      .replaceAll('{x}', clientRect.x - relativeAncestorClientRect.x)
-      .replaceAll('{y}', clientRect.y - relativeAncestorClientRect.y)
-      .replaceAll('{width}', clientRect.width)
-      .replaceAll('{height}', clientRect.height)
-      .replaceAll('{top}', clientRect.top - relativeAncestorClientRect.top)
-      .replaceAll('{right}', clientRect.right - relativeAncestorClientRect.right)
-      .replaceAll('{bottom}', clientRect.bottom - relativeAncestorClientRect.bottom)
-      .replaceAll('{left}', clientRect.left - relativeAncestorClientRect.left);
+
+  // Get text node walker
+  Highlighter.prototype._getTextNodeWalker = function (root = this._container) {
+    if (!root) root = this._container;
+    return document.createTreeWalker(root, NodeFilter.SHOW_TEXT, (node) => this._shouldSkipTextNode(node) ? NodeFilter.FILTER_SKIP : NodeFilter.FILTER_ACCEPT);
   }
-  return styleTemplate;
-}
-
-// Restore the previous selection range in case the browser clears the selection
-Highlighter.prototype._getRestoredSelectionOrCaret = function (selection, pointerEvent = null) {
-  if (selection.type === 'None') {
-    if (this._previousSelectionRange) {
-      // iOS Safari deselects text when a button is tapped. This restores the selection.
-      selection.addRange(this._previousSelectionRange);
-    } else if (pointerEvent) {
-      // In most browsers, tapping or clicking somewhere on the page creates a selection of 0 character length (selection.type === "Caret"). iOS Safari instead clears the selection (selection.type === "None"). This restores a Caret selection if the selection type is None.
-      let range = this._getCaretFromCoordinates(pointerEvent.clientX, pointerEvent.clientY);
-      selection.addRange(range);
+
+  // Get the closest valid paragraph
+  Highlighter.prototype._closestValidParagraph = function (element) {
+    const parentParagraph = element ? element.closest(this._paragraphSelector) : null;
+    if (parentParagraph && this._container.contains(parentParagraph)) return parentParagraph;
+  }
+
+  // Update color stylesheet
+  Highlighter.prototype._updateColorStylesheet = function () {
+    const options = this._options;
+    let css = '';
+    for (const color of Object.keys(options.colorDefs)) {
+      css += `${this._containerSelector} [data-hh-color="${color}"] { --hh-color: ${options.colorDefs[color]}; }\n`;
     }
+    this._colorStylesheet.replaceSync(css);
   }
-  return selection;
-}
-
-// Fix highlight range if the DOM changed and made the previous highlight range invalid
-Highlighter.prototype._getCorrectedRangeObj = function (highlightId) {
-  const highlightInfo = this._highlightsById[highlightId];
-  const highlightRange = highlightInfo?.rangeObj;
-  if (highlightRange && (
-    highlightRange.startContainer.nodeType !== Node.TEXT_NODE || highlightRange.endContainer.nodeType !== Node.TEXT_NODE ||
-    highlightRange.startOffset > highlightRange.startContainer.textContent.length - 1 ||
-    highlightRange.endOffset > highlightRange.endContainer.textContent.length
-  )) {
-    const [ startNode, startOffset ] = this._getTextNodeAndOffset(document.getElementById(highlightInfo.startParagraphId), highlightInfo.startParagraphOffset);
-    const [ endNode, endOffset ] = this._getTextNodeAndOffset(document.getElementById(highlightInfo.endParagraphId), highlightInfo.endParagraphOffset);
-    highlightRange.setStart(startNode, startOffset);
-    highlightRange.setEnd(endNode, endOffset);
+
+  // Get the resolved drawing mode for a highlight
+  Highlighter.prototype._getResolvedDrawingMode = function (highlightInfo) {
+    const options = this._options;
+    if (options.drawingMode === 'mark-elements') return 'mark-elements';
+    const resolvedStyle = Object.hasOwn(options.styleDefs, highlightInfo.style) ? highlightInfo.style : _defaultStyle;
+    if ((options.drawingMode === 'svg' && !options.styleDefs[resolvedStyle]?.svg)
+      || (options.drawingMode === 'highlight-api' && !supportsHighlightApi)) {
+      return 'mark-elements';
+    }
+    return options.drawingMode;
   }
-  return highlightRange;
-}
-
-// Convert tap or click to a selection range
-// Adapted from https://stackoverflow.com/a/12924488/1349044
-Highlighter.prototype._getCaretFromCoordinates = function (clientX, clientY, checkAnnotatable = false, checkXDistance = false, checkYDistance = false) {
-  let range;
-  if (supportsCaretPositionFromPoint) {
-    let caretPosition = document.caretPositionFromPoint(clientX, clientY);
-    range = document.createRange();
-    range.setStart(caretPosition.offsetNode, caretPosition.offset);
-    range.collapse(true);
-  } else if (supportsCaretRangeFromPoint) {
-    range = document.caretRangeFromPoint(clientX, clientY);
+
+  Highlighter.prototype._getWrapperTemplateHash = function (highlightInfo) {
+    const wrapperDef = this._options.wrapperDefs[highlightInfo.wrapper];
+    const str = (highlightInfo.wrapper ?? '') + (wrapperDef?.start ?? '') + (wrapperDef?.end ?? '');
+    let h = 0;
+    for (let i = 0; i < str.length; i++) h = (Math.imul(31, h) + str.charCodeAt(i)) | 0;
+    return String(h);
   }
-  if (!range) return;
-  if (checkXDistance || checkYDistance) {
-    const maxDistance = 30;
-    const caretClientRect = range.getBoundingClientRect();
-    if (checkXDistance && Math.abs(clientX - caretClientRect.x) > maxDistance) return;
-    if (checkYDistance && Math.abs(clientY - caretClientRect.top) > maxDistance && Math.abs(clientY - caretClientRect.bottom) > maxDistance) return;
+
+  Highlighter.prototype._getWrapperHash = function (highlightInfo, templateHash = null) {
+    const wrapperDef = this._options.wrapperDefs[highlightInfo.wrapper];
+    const wrapperTemplate = (wrapperDef?.start ?? '') + (wrapperDef?.end ?? '');
+    let hash = templateHash ?? this._getWrapperTemplateHash(highlightInfo);
+    for (const key of Object.keys(highlightInfo.variables).sort()) {
+      hash += '\u0000' + key + '\u0001' + highlightInfo.variables[key];
+    }
+    if (highlightInfo.rangeRect && wrapperTemplate.includes('{range.')) {
+      const r = highlightInfo.rangeRect;
+      hash += '\u0002' + Math.round(r.x) + ',' + Math.round(r.y) + ',' + Math.round(r.width) + ',' + Math.round(r.height);
+    }
+    if (highlightInfo.rangeRect?.columnRect && wrapperTemplate.includes('{column.')) {
+      const c = highlightInfo.rangeRect.columnRect;
+      hash += '\u0004' + Math.round(c.x) + ',' + Math.round(c.y) + ',' + Math.round(c.width) + ',' + Math.round(c.height);
+    }
+    if (this._containerRect && wrapperTemplate.includes('{container.')) {
+      const c = this._containerRect;
+      hash += '\u0003' + Math.round(c.x) + ',' + Math.round(c.y) + ',' + Math.round(c.width) + ',' + Math.round(c.height);
+    }
+    return hash;
   }
-  if (checkAnnotatable && !range.startContainer.parentElement.closest(this._options.paragraphSelector)) return;
-  return range;
-}
-
-// Check if a point is in a DOMRect
-Highlighter.prototype._isPointInRect = function (x, y, rect, padding = 0) {
-  return (
-    x >= rect.x - padding && x <= rect.x + rect.width + padding &&
-    y >= rect.y - padding && y <= rect.y + rect.height + padding
-  )
-}
-
-// Get merged client rects from the highlight range
-Highlighter.prototype._getMergedClientRects = function (range, paragraphs) {
-  const unmergedRects = Array.from(range.getClientRects());
-  const mergedRects = [];
-
-  // Remove element rects (only text node rects are needed)
-  const ancestorElementsInRange = new Set();
-  for (const paragraph of paragraphs) {
-    let element = paragraph;
-    while (range.commonAncestorContainer.contains(element)) {
-      ancestorElementsInRange.add(element);
-      element = element.parentElement;
+
+  // Update wrapper children in-place (attributes and leaf text), preserving element identity for CSS transitions
+  Highlighter.prototype._updateWrapperInPlace = function (wrapper, newHtmlString) {
+    if (wrapper.children.length === 0) {
+      wrapper.innerHTML = newHtmlString;
+      return;
+    }
+    if (wrapper.innerHTML === newHtmlString) return;
+    const temp = document.createElement('div');
+    temp.innerHTML = newHtmlString;
+    const existingAll = wrapper.querySelectorAll('*');
+    const updatedAll = temp.querySelectorAll('*');
+    for (let i = 0; i < existingAll.length && i < updatedAll.length; i++) {
+      const existing = existingAll[i];
+      const updated = updatedAll[i];
+      for (const attr of updated.attributes) {
+        if (existing.getAttribute(attr.name) !== attr.value) existing.setAttribute(attr.name, attr.value);
+      }
+      if (!updated.children.length && existing.textContent !== updated.textContent) {
+        existing.textContent = updated.textContent;
+      }
     }
   }
-  for (let ur = unmergedRects.length - 1; ur >= 0; ur--) {
-    const rect = unmergedRects[ur];
-    for (const element of ancestorElementsInRange) {
-      const elementRect = element.getBoundingClientRect();
-      if (Math.round(elementRect.width) === Math.round(rect.width) && Math.round(elementRect.height) === Math.round(rect.height) && Math.round(elementRect.top) === Math.round(rect.top) && Math.round(elementRect.left) === Math.round(rect.left)) {
-        unmergedRects.splice(ur, 1);
-        break;
+
+  // Apply variable substitutions
+  Highlighter.prototype._applySubstitutions = function (str, variables = {}, rangeRect = null, lineRect = null) {
+    if (!str) return str;
+    const map = {};
+    const rectKeys = ['x', 'y', 'width', 'height', 'top', 'right', 'bottom', 'left'];
+    for (const key of Object.keys(variables)) map[`{${key}}`] = variables[key];
+    if (lineRect) for (const k of rectKeys) map[`{line.${k}}`] = lineRect[k];
+    if (rangeRect) for (const k of rectKeys) map[`{range.${k}}`] = rangeRect[k];
+    if (rangeRect?.columnRect) for (const k of rectKeys) map[`{column.${k}}`] = rangeRect.columnRect[k];
+    if (this._containerRect) for (const k of rectKeys) map[`{container.${k}}`] = this._containerRect[k];
+    return str.replace(/\{[^}]+\}/g, match => map[match] ?? match);
+  }
+
+  // Get style string for a given highlight style
+  Highlighter.prototype._getStyleString = function (style, type, active = false, variables = {}, rangeRect = null, lineRect = null) {
+    const options = this._options;
+    style = Object.hasOwn(options.styleDefs, style) ? style : _defaultStyle;
+    let styleString = options.styleDefs[style]?.[type] ?? '';
+    if (active) {
+      styleString = options.styleDefs[style]?.[`${type}Active`] ?? styleString;
+    }
+    if (styleString) {
+      styleString = this._applySubstitutions(styleString, variables, rangeRect, lineRect);
+    }
+    return styleString;
+  }
+
+  // Check if the text selection is being resized. If a new selection range is within 2 characters of the previous selection range, the selection is assumed to be resizing. There's not a reliable way to track dragging of a native OS selection handle from JavaScript, but this can be used as an approximation. It will also trigger when dragging a custom handle, and when expanding a selection with arrow keys.
+  Highlighter.prototype._detectSelectionResize = function (prevRange, newRange, selectionType) {
+    this._handleDragTimeoutId = clearTimeout(this._handleDragTimeoutId);
+    const rangesMatch = _rangesEqual(prevRange, newRange);
+    if (rangesMatch) return;
+    if (selectionType === 'Range' && prevRange && newRange) {
+      const expandedPrevRange = document.createRange();
+
+      if (prevRange.startOffset >= 2) {
+        expandedPrevRange.setStart(prevRange.startContainer, prevRange.startOffset - 2);
+      } else {
+        const prevTextNode = this._getPreviousValidTextNode(prevRange.startContainer);
+        expandedPrevRange.setStart(prevTextNode ?? prevRange.startContainer, prevTextNode ? Math.max(0, prevTextNode.length - 2) : prevRange.startOffset);
+      }
+
+      if (prevRange.endOffset <= prevRange.endContainer.length - 2) {
+        expandedPrevRange.setEnd(prevRange.endContainer, prevRange.endOffset + 2);
+      } else {
+        const nextTextNode = this._getNextValidTextNode(prevRange.endContainer);
+        expandedPrevRange.setEnd(nextTextNode ?? prevRange.endContainer, nextTextNode ? Math.min(2, nextTextNode.length) : prevRange.endOffset);
       }
+
+      this._isResizingSelection =
+        expandedPrevRange.isPointInRange(newRange.startContainer, newRange.startOffset) ||
+        expandedPrevRange.isPointInRange(newRange.endContainer, newRange.endOffset);
+
+    } else {
+      this._isResizingSelection = false;
+    }
+    if (this._isResizingSelection) {
+      // For most browsers: If we know the pointer is down, we can assume that the user is still resizing the selection. this._isResizingSelection will be set to false on pointerup.
+      if (this._container.dataset.hhPointerDown === 'true') return;
+
+      // For Android Chrome: Set this._isResizingSelection to false if it's been more than 400 milliseconds since the last selection change. Android doesn't send a pointerdown event when dragging the built-in text selection handle, so we can't rely on the the pointerup event to set this._isResizingSelection back to false. A side effect of this approach is that this._isResizingSelection may be set to false if a user pauses (finger still on the screen) while dragging the selection handle. If a custom popup menu is triggered based on this flag, it may briefly flicker each time the user pauses.
+      this._handleDragTimeoutId = setTimeout(() => {
+        this._isResizingSelection = false;
+        this._updateSelectionState();
+      }, 400);
     }
   }
 
-  // Loop through the highlight's paragraphs
-  for (const paragraph of paragraphs) {
+  // Restore the previous selection range in case the browser clears the selection
+  Highlighter.prototype._getRestoredSelectionOrCaret = function (selection, pointerEvent = null) {
+    if (selection.type === 'None') {
+      if (this._previousSelectionRange) {
+        // iOS Safari deselects text when a button is tapped. This restores the selection.
+        selection.addRange(this._previousSelectionRange);
+      } else if (pointerEvent) {
+        // In most browsers, tapping or clicking somewhere on the page creates a selection of 0 character length (selection.type === "Caret"). iOS Safari instead clears the selection (selection.type === "None"). This restores a Caret selection if the selection type is None.
+        let range = this._getCaretFromCoordinates(pointerEvent.clientX, pointerEvent.clientY);
+        selection.addRange(range);
+      }
+    }
+    return selection;
+  }
+
+  Highlighter.prototype._restorePreviousSelectionRange = function () {
+    const selection = globalThis.getSelection();
+    if (this._previousSelectionDirection === 'forward') {
+      selection.setBaseAndExtent(this._previousSelectionRange.startContainer, this._previousSelectionRange.startOffset, this._previousSelectionRange.endContainer, this._previousSelectionRange.endOffset);
+    } else {
+      selection.setBaseAndExtent(this._previousSelectionRange.endContainer, this._previousSelectionRange.endOffset, this._previousSelectionRange.startContainer, this._previousSelectionRange.startOffset);
+    }
+  }
+
+  // Fix highlight range if the DOM changed and made the previous highlight range invalid
+  Highlighter.prototype._getCorrectedRangeObj = function (highlightId, force = false) {
+    const highlightInfo = this._highlightsById[highlightId];
+    const highlightRange = highlightInfo?.rangeObj;
+    if (highlightRange && (
+      force || highlightRange.collapsed ||
+      highlightRange.startContainer.nodeType !== Node.TEXT_NODE || highlightRange.endContainer.nodeType !== Node.TEXT_NODE ||
+      highlightRange.startOffset >= highlightRange.startContainer.length ||
+      highlightRange.endOffset > highlightRange.endContainer.length
+    )) {
+      const [ startNode, startOffset ] = this._getTextNodeAndOffset(document.getElementById(highlightInfo.startParagraphId), highlightInfo.startParagraphOffset, 'start');
+      const [ endNode, endOffset ] = this._getTextNodeAndOffset(document.getElementById(highlightInfo.endParagraphId), highlightInfo.endParagraphOffset, 'end');
+      highlightRange.setStart(startNode, startOffset);
+      highlightRange.setEnd(endNode, endOffset);
+    }
+    return highlightRange;
+  }
+
+  // Convert tap or click to a selection range
+  // Adapted from https://stackoverflow.com/a/12924488/1349044
+  Highlighter.prototype._getCaretFromCoordinates = function (clientX, clientY, checkAnnotatable = false, checkXDistance = false, checkYDistance = false) {
+    let range;
+    if (supportsCaretPositionFromPoint) {
+      const caretPosition = document.caretPositionFromPoint(clientX, clientY);
+      if (!caretPosition) return;
+      range = document.createRange();
+      range.setStart(caretPosition.offsetNode, caretPosition.offset);
+      range.collapse(true);
+    } else if (supportsCaretRangeFromPoint) {
+      range = document.caretRangeFromPoint(clientX, clientY);
+    }
+    if (!range) return;
+    if (range.startContainer.parentElement?.closest('[data-hh-ignore]')) return;
+    if (checkXDistance || checkYDistance) {
+      const maxDistance = 30;
+      const caretClientRect = range.getBoundingClientRect();
+      if (checkXDistance && Math.abs(clientX - caretClientRect.x) > maxDistance) return;
+      if (checkYDistance && Math.abs(clientY - caretClientRect.top) > maxDistance && Math.abs(clientY - caretClientRect.bottom) > maxDistance) return;
+    }
+    if (checkAnnotatable && !this._closestValidParagraph(range.startContainer.parentElement)) return;
+    return range;
+  }
+
+  // Get line rectangles for a given paragraph
+  Highlighter.prototype._getParagraphLineRects = function (paragraph) {
     const paragraphRect = paragraph.getBoundingClientRect();
     const paragraphStyle = getComputedStyle(paragraph);
-    const snapTolerance = Math.max(Number.parseInt(paragraphStyle.fontSize) / 2, 4);
-    const topPadding = Number.parseInt(paragraphStyle.paddingTop);
-    const textIndent = Number.parseInt(paragraphStyle.textIndent);
+    const paragraphFontSize = Number.parseFloat(paragraphStyle.fontSize);
+    const snapTolerance = Math.max(paragraphFontSize / 2, 4);
 
-    // Build line positions from paragraph text nodes
     const linePositions = {};
     const lineBottomKeys = [];
-    const walker = this._getTextNodeWalker(paragraph);
     const textNodeRange = document.createRange();
+    const walker = this._getTextNodeWalker(paragraph);
     let textNode;
     while (textNode = walker.nextNode()) {
       // Skip text nodes in elements that are higher or lower than surrounding text
       if (textNode.parentElement.closest('sup, sub, rt')) continue;
+      const textNodeStyle = textNode.parentElement === paragraph ? paragraphStyle : getComputedStyle(textNode.parentElement);
+      const fontSize = Number.parseFloat(textNodeStyle.fontSize);
+      const lineHeight = Number.parseFloat(textNodeStyle.lineHeight) || (fontSize * 1.2);
       textNodeRange.selectNode(textNode);
       for (const rect of textNodeRange.getClientRects()) {
-        // Round to a nearby line position if close
-        const lineBottom = lineBottomKeys.find(b => Math.abs(b - rect.bottom) < snapTolerance) ?? rect.bottom;
+        const lineBottom = lineBottomKeys.find(b => {
+          if (Math.abs(b - rect.bottom) >= snapTolerance) return false;
+          const pos = linePositions[b];
+          return rect.left <= pos.maxRight + snapTolerance && rect.right >= pos.minLeft - snapTolerance;
+        }) ?? rect.bottom;
         if (!linePositions[lineBottom]) lineBottomKeys.push(lineBottom);
-        const pos = linePositions[lineBottom] ??= {
-          minLeft: rect.left, maxRight: rect.right,
-          highlightLeft: null, highlightRight: null,
-        };
+        const pos = linePositions[lineBottom] ??= { minLeft: rect.left, maxRight: rect.right, maxFontSize: fontSize, maxLineHeight: lineHeight };
         pos.minLeft = Math.min(pos.minLeft, rect.left);
         pos.maxRight = Math.max(pos.maxRight, rect.right);
+        pos.maxFontSize = Math.max(pos.maxFontSize, fontSize);
+        pos.maxLineHeight = Math.max(pos.maxLineHeight, lineHeight);
       }
     }
 
-    const lineBottoms = lineBottomKeys.sort((a, b) => a - b);
+    // Expand line rects to include pseudoelements, and snap to the paragraph's leading edge
+    const pseudoElemRects = _gatherPseudoElemRects(paragraph);
+    lineBottomKeys.sort((a, b) => a - b);
+    const lines = lineBottomKeys.map((lineBottom) => {
+      const pos = linePositions[lineBottom];
+      const centerY = lineBottom - pos.maxLineHeight / 2;
+      if (paragraphStyle.direction === 'ltr') {
+        pos.minLeft = this._snapToEdge(pseudoElemRects, pos.minLeft, 'left', centerY, paragraphRect.left, snapTolerance);
+      } else {
+        pos.maxRight = this._snapToEdge(pseudoElemRects, pos.maxRight, 'right', centerY, paragraphRect.right, snapTolerance);
+      }
+      return new DOMRect(pos.minLeft, lineBottom - pos.maxLineHeight, pos.maxRight - pos.minLeft, pos.maxLineHeight);
+    });
+
+    return { lines, snapTolerance, pseudoElemRects };
+  }
 
-    // Assign highlight range rects to matching line positions
-    for (const rect of unmergedRects) {
-      const centerY = rect.y + rect.height / 2;
-      for (let i = 0; i < lineBottoms.length; i++) {
-        const pos = linePositions[lineBottoms[i]];
-        // Skip rects that extend outside the line of text (such as absolutely-positioned elements)
-        if (rect.left >= pos.minLeft && rect.right <= pos.maxRight
-            && centerY > (lineBottoms[i - 1] ?? (paragraphRect.top + topPadding)) && centerY <= lineBottoms[i]) {
-          pos.highlightLeft = Math.min(pos.highlightLeft ?? rect.left, rect.left);
-          pos.highlightRight = Math.max(pos.highlightRight ?? rect.right, rect.right);
-          break;
+  // Get merged client rects from the highlight range
+  Highlighter.prototype._getRangeRects = function (range, paragraphs, paragraphLineRectsCache = new Map(), columnGeometryCache = new Map()) {
+    let rangeRectCoordinates = { top: Number.POSITIVE_INFINITY, bottom: Number.NEGATIVE_INFINITY, left: Number.POSITIVE_INFINITY, right: Number.NEGATIVE_INFINITY };
+    const rangeLineRects = [];
+    let columnRect = null;
+    const textNodeRange = document.createRange();
+    let prevParagraphBottom = Number.NEGATIVE_INFINITY;
+    for (const paragraph of paragraphs) {
+      let paragraphLineRects = paragraphLineRectsCache.get(paragraph.id);
+      if (!paragraphLineRects) {
+        paragraphLineRects = this._getParagraphLineRects(paragraph);
+        paragraphLineRectsCache.set(paragraph.id, paragraphLineRects);
+      }
+      const { lines, snapTolerance, pseudoElemRects } = paragraphLineRects;
+      // If the previous paragraph is below the current paragraph (such as in multi-column layouts), reset prevParagraphBottom
+      if (prevParagraphBottom > lines[0].bottom) prevParagraphBottom = Number.NEGATIVE_INFINITY;
+      const lineStates = lines.map((lineRect, i) => ({
+        topY: i === 0 ? prevParagraphBottom : lines[i - 1].bottom,
+        left: Infinity, right: -Infinity,
+      }));
+
+      // Per-highlight accumulators
+      const walker = this._getTextNodeWalker(paragraph);
+      let textNode;
+      while (textNode = walker.nextNode()) {
+        if (!range.intersectsNode(textNode)) {
+          if (range.comparePoint(textNode, 0) > 0) break;
+          continue;
+        }
+        const start = textNode === range.startContainer ? range.startOffset : 0;
+        const end = textNode === range.endContainer ? range.endOffset : textNode.length;
+        if (start > end) continue;
+        textNodeRange.setStart(textNode, start);
+        textNodeRange.setEnd(textNode, end);
+        const clientRects = textNodeRange.getClientRects();
+        let previousTextNodeLine = 0;
+        for (const rect of clientRects) {
+          const centerY = rect.y + rect.height / 2;
+          for (let i = previousTextNodeLine; i < lines.length; i++) {
+            const lineRect = lines[i];
+            // Skip rects that extend outside the line of text (such as absolutely-positioned elements).
+            // The 1px tolerance fixes an issue on Android Chrome where range rect coordinates aren't exact (sub-pixel precision)
+            if (rect.left >= lineRect.left - 1 && rect.right <= lineRect.right + 1
+                && centerY > lineStates[i].topY && centerY <= lineRect.bottom) {
+              const s = lineStates[i];
+              s.left = Math.min(s.left, rect.left);
+              s.right = Math.max(s.right, rect.right);
+              previousTextNodeLine = i;
+              break;
+            }
+          }
         }
       }
+
+      // Build a merged rect for each line
+      for (let i = 0; i < lines.length; i++) {
+        const s = lineStates[i];
+        if (s.left === Infinity) continue;
+        const lineRect = lines[i];
+        const centerY = lineRect.top + lineRect.height / 2;
+        s.left  = this._snapToEdge(pseudoElemRects, s.left,  'left',  centerY, lineRect.left,  snapTolerance);
+        s.right = this._snapToEdge(pseudoElemRects, s.right, 'right', centerY, lineRect.right, snapTolerance);
+        const top = lineRect.top - this._additionsRect.top;
+        const bottom = lineRect.bottom - this._additionsRect.top;
+        const left = s.left - this._additionsRect.left;
+        const right = s.right - this._additionsRect.left;
+        rangeRectCoordinates.left = Math.min(left, rangeRectCoordinates.left);
+        rangeRectCoordinates.right = Math.max(right, rangeRectCoordinates.right);
+        rangeRectCoordinates.top = Math.min(top, rangeRectCoordinates.top);
+        rangeRectCoordinates.bottom = Math.max(bottom, rangeRectCoordinates.bottom);
+        rangeLineRects.push(new DOMRect(left, top, right - left, lineRect.height));
+        if (!columnRect) {
+          columnRect = _getColumnRect(paragraph, (s.left + s.right) / 2, columnGeometryCache, this._additionsRect);
+        }
+      }
+
+      if (lines.length > 0) prevParagraphBottom = lines[lines.length - 1].bottom;
     }
 
-    // Create a merged rect for each relevant line
-    for (let i = 0; i < lineBottoms.length; i++) {
-      const bottom = lineBottoms[i];
-      const pos = linePositions[bottom];
-      if (pos.highlightLeft == null) continue;
-      const nearbyBottom = lineBottoms[i - 1] ?? lineBottoms[i + 1] ?? (paragraphRect.top + topPadding);
-      const height = Math.abs(bottom - nearbyBottom);
-      const top = bottom - height;
-      let left = Math.max(pos.minLeft, pos.highlightLeft);
-      let right = Math.min(pos.maxRight, pos.highlightRight);
+    // In a multi-column layout, clip rangeRect to the start column bounds
+    let rectTop = rangeRectCoordinates.top, rectBottom = rangeRectCoordinates.bottom;
+    if (columnRect && rangeLineRects.length > 0) {
+      let colTop = Infinity, colBottom = -Infinity;
+      for (const lr of rangeLineRects) {
+        const centerX = lr.left + lr.width / 2;
+        if (centerX >= columnRect.left && centerX <= columnRect.right) {
+          colTop = Math.min(colTop, lr.top);
+          colBottom = Math.max(colBottom, lr.bottom);
+        }
+      }
+      if (colTop !== Infinity) { rectTop = colTop; rectBottom = colBottom; }
+    }
+
+    const rangeRect = new DOMRect(rangeRectCoordinates.left, rectTop, rangeRectCoordinates.right - rangeRectCoordinates.left, rectBottom - rectTop);
+    rangeRect.columnRect = columnRect;
+    return [rangeRect, rangeLineRects];
+  }
+
+  // Find the left and right bounds of the nearest multi-column ancestor (or fall back to the nearest block-level ancestor)
+  function _getColumnRect(paragraph, probeX, columnGeometryCache = new Map(), additionsRect = null) {
+    let el = paragraph.parentElement;
+    let nearestMultiColumnBlock, nearestBlock, geometry;
+
+    while (el) {
+      if (columnGeometryCache.has(el)) {
+        geometry = columnGeometryCache.get(el);
+        break;
+      }
+      const style = getComputedStyle(el);
+      if (!nearestBlock && !style.display.startsWith('inline')) nearestBlock = el;
+      if (!nearestMultiColumnBlock && (style.columnWidth !== 'auto' || (style.columnCount !== 'auto' && parseInt(style.columnCount) > 1))) { nearestMultiColumnBlock = el; break; }
+      if (el.hasAttribute('data-hh-container')) break;
+      el = el.parentElement;
+    }
 
-      // Final adjustment to left and right bounds
-      if (paragraphStyle.direction === 'ltr' && paragraphStyle.textAlign === 'start') {
-        if (left - paragraphRect.left < snapTolerance) left = paragraphRect.left;
-        if (textIndent < 0) left += textIndent;
-      } else if (paragraphStyle.direction === 'rtl' && paragraphStyle.textAlign === 'start') {
-        if (paragraphRect.right - right < snapTolerance) right = paragraphRect.right;
-        if (textIndent < 0) right += textIndent;
+    el = nearestMultiColumnBlock ?? nearestBlock ?? el;
+    if (!geometry) {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      const insetLeft = (parseFloat(style.paddingLeft) || 0) + (parseFloat(style.borderLeftWidth) || 0);
+      const insetRight = (parseFloat(style.paddingRight) || 0) + (parseFloat(style.borderRightWidth) || 0);
+      const insetTop = (parseFloat(style.paddingTop) || 0) + (parseFloat(style.borderTopWidth) || 0);
+      const insetBottom = (parseFloat(style.paddingBottom) || 0) + (parseFloat(style.borderBottomWidth) || 0);
+      const contentLeft = rect.left + insetLeft;
+      const contentWidth = rect.width - insetLeft - insetRight;
+      const contentTop = rect.top + insetTop;
+      const contentHeight = rect.height - insetTop - insetBottom;
+      const gap = parseFloat(style.columnGap) || 0;
+      let cols = parseInt(style.columnCount);
+      if (isNaN(cols) || cols < 1) {
+        const cw = parseFloat(style.columnWidth);
+        cols = (!isNaN(cw) && cw > 0) ? Math.max(1, Math.floor((contentWidth + gap) / (cw + gap))) : 1;
       }
 
-      const width = right - left;
-      mergedRects.push(new DOMRect(left, top, width, height));
+      geometry = {
+        contentLeft, contentTop, contentHeight, cols, gap,
+        colWidth: (contentWidth - (cols - 1) * gap) / cols
+      };
+      columnGeometryCache.set(el, geometry);
     }
+
+    const { contentLeft, contentTop, contentHeight, cols, colWidth, gap } = geometry;
+    const unit = colWidth + gap;
+    const idx = Math.max(0, Math.min(cols - 1, Math.floor((probeX - contentLeft) / unit)));
+    const left = contentLeft + idx * unit;
+    return new DOMRect(left - (additionsRect?.left ?? 0), contentTop - (additionsRect?.top ?? 0), colWidth, contentHeight);
   }
 
-  return mergedRects;
-}
+  function _gatherPseudoElemRects(paragraph) {
+    const hasPseudoContent = (elem, pseudo) => { const c = getComputedStyle(elem, pseudo).content; return c !== 'none' && c !== 'normal'; };
+    const rects = [];
+    for (const el of paragraph.querySelectorAll(':empty:not([data-hh-ignore]):not([data-hh-ignore] *)')) {
+      if (!hasPseudoContent(el, '::before') && !hasPseudoContent(el, '::after')) continue;
+      const rect = el.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) rects.push(rect);
+    }
+    return rects;
+  }
+
+  Highlighter.prototype._snapToEdge = function (pseudoElemRects, initialValue, side, centerY, snapValue, snapTolerance = null) {
+    const snap = (v) => snapTolerance !== null && Math.abs(snapValue - v) < snapTolerance ? snapValue : v;
+    let edge = initialValue;
+    const probeX = side === 'left' ? edge - 1 : edge + 1;
+    const pseudoRect = pseudoElemRects.find(r => probeX >= r.left && probeX <= r.right && centerY >= r.top && centerY <= r.bottom);
+    if (pseudoRect) {
+      edge = snap(side === 'left' ? Math.min(edge, pseudoRect.left) : Math.max(edge, pseudoRect.right));
+    }
+    return edge;
+  };
+
+  // Get the HTML and text content of a range
+  Highlighter.prototype._getRangeContent = function (range, unwrapHighlights = false, unwrapHyperlinks = false) {
+    const tempDiv = document.createElement('div');
+    tempDiv.appendChild(range.cloneContents());
+    const unwrapSelectors = [];
+    if (unwrapHighlights) unwrapSelectors.push('[data-hh-highlight-id]');
+    if (unwrapHyperlinks) unwrapSelectors.push('a');
+    for (const element of tempDiv.querySelectorAll(unwrapSelectors.join(', '))) {
+      while (element.firstChild) element.before(element.firstChild);
+      element.remove();
+    }
+    const removeSelectors = ['[data-hh-ignore]', '.sr-only'];
+    for (const element of tempDiv.querySelectorAll(removeSelectors.join(','))) {
+      element.remove();
+    }
+    return { rangeHtml: tempDiv.innerHTML, rangeText: tempDiv.textContent };
+  };
 
 
-/********************** Utilities **********************/
+  /********************** Utilities **********************/
 
-// Add a CSS stylesheet to the document
-function addStylesheet(stylesheets, stylesheetKey) {
-  let stylesheet = stylesheets[stylesheetKey];
-  if (!stylesheet) {
-    if (supportsCssStylesheetApi) {
-      stylesheet = new CSSStyleSheet();
-      document.adoptedStyleSheets.push(stylesheet);
-    } else {
-      // For browsers that don't fully support the CSSStyleSheet API, such as Safari < 16.4.
-      // See https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet#browser_compatibility
-      stylesheet = document.createElement('style');
-      stylesheet.appendChild(document.createTextNode(''));
-      stylesheet.replaceSync = (newContent) => {
-        stylesheet.textContent = newContent;
-      }
-      stylesheet.insertRule = (newContent) => {
-        stylesheet.textContent += newContent;
+  // Add a CSS stylesheet to the document
+  function _addStylesheet(stylesheets, stylesheetKey) {
+    let stylesheet = stylesheets[stylesheetKey];
+    if (!stylesheet) {
+      if (supportsCssStylesheetApi) {
+        stylesheet = new CSSStyleSheet();
+        document.adoptedStyleSheets.push(stylesheet);
+      } else {
+        // For browsers that don't fully support the CSSStyleSheet API, such as Safari < 16.4.
+        // See https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleSheet#browser_compatibility
+        stylesheet = document.createElement('style');
+        stylesheet.replaceSync = (newContent) => {
+          stylesheet.textContent = newContent;
+        }
+        stylesheet.insertRule = (newContent) => {
+          stylesheet.textContent += newContent;
+        }
+        document.head.appendChild(stylesheet);
       }
-      document.head.appendChild(stylesheet);
+      stylesheets[stylesheetKey] = stylesheet;
     }
-    stylesheets[stylesheetKey] = stylesheet;
+    return stylesheet;
   }
-  return stylesheet;
-}
 
-// Remove CSS stylesheets (only those from the current Highlighter instance)
-function removeStylesheets(stylesheets) {
-  for (const stylesheet of Object.values(stylesheets)) {
+  // Remove CSS stylesheets (only those from the current Highlighter instance)
+  function _removeStylesheets(stylesheets) {
+    const sheets = Object.values(stylesheets);
     if (supportsCssStylesheetApi) {
-      const adoptedStylesheetIndex = document.adoptedStyleSheets.indexOf(stylesheet);
-      document.adoptedStyleSheets.splice(adoptedStylesheetIndex, 1);
+      const sheetsSet = new Set(sheets);
+      document.adoptedStyleSheets = document.adoptedStyleSheets.filter(s => !sheetsSet.has(s));
     } else {
-      stylesheet.remove();
+      for (const stylesheet of sheets) stylesheet.remove();
     }
   }
-}
-
-// Debounce a function to prevent it from being executed too frequently
-// Adapted from https://levelup.gitconnected.com/debounce-in-javascript-improve-your-applications-performance-5b01855e086
-function debounce(func, wait) {
-  let timeout;
-  return function executedFunction(...args) {
-    const later = () => {
+
+  // Debounce a function to prevent it from being executed too frequently
+  // Adapted from https://levelup.gitconnected.com/debounce-in-javascript-improve-your-applications-performance-5b01855e086
+  function _debounce(func, wait) {
+    let timeout;
+    return function executedFunction(...args) {
+      const later = () => {
+        clearTimeout(timeout);
+        func(...args);
+      };
       clearTimeout(timeout);
-      func(...args);
+      timeout = setTimeout(later, wait);
     };
-    clearTimeout(timeout);
-    timeout = setTimeout(later, wait);
-  };
-}
-
-// Default function for generating a highlight ID
-const _getNewHighlightId = () => {
-  return 'hh-' + Date.now().toString();
-}
-
-
-/********************** Constants **********************/
-
-// Keep track of all Highlighter instances
-let _highlighters = [];
-
-// Check browser type
-const isTouchDevice = navigator.maxTouchPoints > 0;
-const isWebKit = /^((?!Chrome|Firefox|Android|Samsung).)*AppleWebKit/i.test(navigator.userAgent);
-const isWKWebView = isWebKit && globalThis.webkit?.messageHandlers;
-const supportsCaretPositionFromPoint = document.caretPositionFromPoint;
-const supportsCaretRangeFromPoint = document.caretRangeFromPoint;
-const supportsCssStylesheetApi = CSSStyleSheet?.prototype?.replaceSync;
-const supportsHighlightApi = CSS.highlights;
-
-// Regex patterns for word boundary detection
-const _reWhitespaceDash = /\s|\p{Pd}/u;
-const _reNonWhitespaceDash = /[^\s|\p{Pd}]/u;
-
-// Default options
-const _defaultOptions = {
-  containerSelector: 'body',
-  paragraphSelector: 'h1[id], h2[id], h3[id], h4[id], h5[id], h6[id], p[id], ol[id], ul[id], dl[id], tr[id]',
-  colors: {
-    'red': 'hsl(360, 100%, 70%)',
-    'orange': 'hsl(30, 100%, 60%)',
-    'yellow': 'hsl(50, 100%, 60%)',
-    'green': 'hsl(80, 100%, 45%)',
-    'blue': 'hsl(180, 100%, 45%)',
-  },
-  styles: {
-    'fill': {
-      'css': 'background-color: hsl(from var(--hh-color) h s l / 50%);',
-      'svg': '<rect x="{x}" y="{y}" rx="4" style="fill: hsl(from var(--hh-color) h s l / 50%); width: calc({width}px + ({height}px / 6)); height: calc({height}px * 0.85); transform: translateX(calc({height}px / -12)) translateY(calc({height}px * 0.14));" />',
-      'css-active': 'background-color: hsl(from var(--hh-color) h s l / 80%);',
-      'svg-active': `
-        <rect x="{x}" y="{y}" rx="4" style="fill: hsl(from var(--hh-color) h s l / 80%); width: calc({width}px + ({height}px / 6)); height: calc({height}px * 0.85); transform: translateX(calc({height}px / -12)) translateY(calc({height}px * 0.14));" />
-      `,
-    },
-    'single-underline': {
-      'css': 'text-decoration: underline; text-decoration-color: var(--hh-color); text-decoration-thickness: 0.15em; text-underline-offset: 0.15em; text-decoration-skip-ink: none;',
-      'svg': '<rect x="{x}" y="{y}" style="fill: var(--hh-color); width: {width}px; height: calc({height}px / 12); transform: translateY(calc({height}px * 0.9));" />',
-      'css-active': 'background-color: hsl(from var(--hh-color) h s l / 25%); text-decoration: underline; text-decoration-color: var(--hh-color); text-decoration-thickness: 0.15em; text-underline-offset: 0.15em; text-decoration-skip-ink: none;',
-      'svg-active': `
-        <rect x="{x}" y="{y}" rx="4" style="fill: hsl(from var(--hh-color) h s l / 25%); width: calc({width}px + ({height}px / 6)); height: calc({height}px * 0.85); transform: translateX(calc({height}px / -12)) translateY(calc({height}px * 0.14));" />
-        <rect x="{x}" y="{y}" style="fill: var(--hh-color); width: {width}px; height: calc({height}px / 12); transform: translateY(calc({height}px * 0.9));" />
-      `,
+  }
+
+  // Default function for generating a highlight ID
+  function _getNewHighlightId() {
+    return 'hh-' + Date.now().toString();
+  }
+
+  // Check if two objects are roughly the same
+  function _shallowEqual(a, b) {
+    const keysA = Object.keys(a);
+    return keysA.length === Object.keys(b).length && keysA.every(k => a[k] == b[k]);
+  }
+
+  // Check if two rects are roughly the same
+  function _rectsEqual(rect1, rect2, epsilon = 0.001) {
+    return Math.abs(rect1.x - rect2.x) < epsilon &&
+           Math.abs(rect1.y - rect2.y) < epsilon &&
+           Math.abs(rect1.width - rect2.width) < epsilon &&
+           Math.abs(rect1.height - rect2.height) < epsilon;
+  }
+
+  // Check if two ranges are roughly the same
+  function _rangesEqual(range1, range2) {
+    return range1 && range2 && range1.compareBoundaryPoints(Range.START_TO_START, range2) === 0 && range1.compareBoundaryPoints(Range.END_TO_END, range2) === 0;
+  }
+
+  // Check if a point is in a DOMRect
+  function _isPointInRect(x, y, rect, padding = 0) {
+    return (
+      x >= rect.x - padding && x <= rect.x + rect.width + padding &&
+      y >= rect.y - padding && y <= rect.y + rect.height + padding
+    );
+  }
+
+
+  /********************** Constants **********************/
+
+  // Check browser type
+  const isTouchDevice = navigator.maxTouchPoints > 0;
+  const isWebKit = /^((?!Chrome|Firefox|Android|Samsung).)*AppleWebKit/i.test(navigator.userAgent);
+  const isWKWebView = isWebKit && globalThis.webkit?.messageHandlers;
+  const supportsCaretPositionFromPoint = document.caretPositionFromPoint;
+  const supportsCaretRangeFromPoint = document.caretRangeFromPoint;
+  const supportsCssStylesheetApi = CSSStyleSheet?.prototype?.replaceSync;
+  const supportsHighlightApi = CSS.highlights;
+  const supportsAccentColor = CSS.supports('color', 'AccentColor');
+
+  // Regex patterns for word boundary detection
+  const _reWhitespaceDash = /\s|\p{Pd}/u;
+  const _reNonWhitespaceDash = /[^\s|\p{Pd}]/u;
+
+  // Workaround to allow programmatic text selection on tap in iOS Safari
+  // See https://stackoverflow.com/a/79261423/1349044
+  if (isTouchDevice && isWebKit) {
+    const tempInput = document.createElement('input');
+    tempInput.style.position = 'fixed';
+    tempInput.style.top = 0;
+    tempInput.style.opacity = 0;
+    tempInput.style.height = 0;
+    tempInput.style.fontSize = '16px'; // Prevent page zoom on input focus
+    tempInput.inputMode = 'none'; // Don't show keyboard
+    tempInput.tabIndex = -1; // Prevent user from tabbing to input
+    tempInput.ariaHidden = 'true'; // Hide from screen readers
+    const initializeSelection = (event) => {
+      if (document.readyState !== 'complete') return setTimeout(initializeSelection, 20);
+      if (!tempInput.parentElement) document.body.append(tempInput);
+      tempInput.focus();
+      setTimeout(() => {
+        tempInput.blur();
+      }, 100);
+    }
+    initializeSelection();
+    document.addEventListener('visibilitychange', (event) => {
+      if (document.visibilityState === 'visible') initializeSelection();
+    });
+  }
+
+  // Default options
+  const _defaultColor = 'yellow';
+  const _defaultStyle = 'fill';
+  const _defaultOptions = {
+    drawingMode: 'svg',
+    snapToWord: false,
+    longPressTimeout: 500,
+    enableHover: false,
+    dragHandles: {
+      left: '<div data-hh-default-handle=""></div>',
+      right: '<div data-hh-default-handle=""></div>',
     },
-    'double-underline': {
-      'css': 'text-decoration: underline; text-decoration-color: var(--hh-color); text-decoration-style: double; text-decoration-skip-ink: none;',
-      'svg': '<rect x="{x}" y="{y}" style="fill: var(--hh-color); width: {width}px; height: calc({height}px / 15); transform: translateY(calc({height}px * 0.9));" /><rect x="{x}" y="{y}" style="fill: var(--hh-color); width: {width}px; height: calc({height}px / 15); transform: translateY(calc({height}px * 1.05));" />',
-      'css-active': 'background-color: hsl(from var(--hh-color) h s l / 25%); text-decoration: underline; text-decoration-color: var(--hh-color); text-decoration-style: double; text-decoration-skip-ink: none;',
-      'svg-active': `
-        <rect x="{x}" y="{y}" rx="4" style="fill: hsl(from var(--hh-color) h s l / 25%); width: calc({width}px + ({height}px / 6)); height: calc({height}px * 0.85); transform: translateX(calc({height}px / -12)) translateY(calc({height}px * 0.14));" />
-        <rect x="{x}" y="{y}" style="fill: var(--hh-color); width: {width}px; height: calc({height}px / 15); transform: translateY(calc({height}px * 0.9));" />
-        <rect x="{x}" y="{y}" style="fill: var(--hh-color); width: {width}px; height: calc({height}px / 15); transform: translateY(calc({height}px * 1.05));" />
-      `,
+    showDragHandles: ['highlights'],
+    colorDefs: {
+      'red': 'hsl(360, 100%, 70%)',
+      'orange': 'hsl(30, 100%, 60%)',
+      'yellow': 'hsl(50, 100%, 60%)',
+      'green': 'hsl(80, 100%, 45%)',
+      'blue': 'hsl(180, 100%, 45%)',
     },
-    'colored-text': {
-      'css': 'color: var(--hh-color);',
-      'svg': '',
+    styleDefs: {
+      'fill': {
+        css: 'background-color: hsl(from var(--hh-color) h s l / 50%);',
+        cssActive: 'background-color: hsl(from var(--hh-color) h s l / 80%);',
+        svg: '<rect x="{line.x}" y="{line.y}" style="fill: hsl(from var(--hh-color) h s l / 50%); width: {line.width}px; height: calc({line.height}px * 0.85); transform: translateY(calc({line.height}px * 0.15));" />',
+        svgActive: `
+          <rect x="{line.x}" y="{line.y}" style="fill: hsl(from var(--hh-color) h s l / 80%); width: {line.width}px; height: calc({line.height}px * 0.85); transform: translateY(calc({line.height}px * 0.15));" />
+        `,
+      },
+      'underline': {
+        css: 'text-decoration: underline; text-decoration-color: var(--hh-color); text-decoration-thickness: 0.15em; text-underline-offset: 0.15em; text-decoration-skip-ink: none;',
+        cssActive: 'background-color: hsl(from var(--hh-color) h s l / 25%); text-decoration: underline; text-decoration-color: var(--hh-color); text-decoration-thickness: 0.15em; text-underline-offset: 0.15em; text-decoration-skip-ink: none;',
+        svg: '<rect x="{line.x}" y="{line.y}" style="fill: var(--hh-color); width: {line.width}px; height: calc({line.height}px / 12); transform: translateY(calc({line.height}px * 0.95));" />',
+        svgActive: `
+          <rect x="{line.x}" y="{line.y}" rx="4" style="fill: hsl(from var(--hh-color) h s l / 25%); width: calc({line.width}px + ({line.height}px / 6)); height: calc({line.height}px * 0.85); transform: translateX(calc({line.height}px / -12)) translateY(calc({line.height}px * 0.15));" />
+          <rect x="{line.x}" y="{line.y}" style="fill: var(--hh-color); width: {line.width}px; height: calc({line.height}px / 12); transform: translateY(calc({line.height}px * 0.95));" />
+        `,
+      },
     },
-    'redacted': {
-      'css': 'background-color: transparent; color: transparent;',
-      'svg': '',
+    wrapperDefs: {
+      'screen-reader-label': {
+        start: '<span class="sr-only">{startLabel} </span>',
+        end: '<span class="sr-only"> {endLabel}</span>',
+      },
     },
-  },
-  wrappers: {},
-  selectionHandles: {
-    'left': '<div class="hh-default-handle"></div>',
-    'right': '<div class="hh-default-handle"></div>',
-  },
-  rememberStyle: true,
-  snapToWord: false,
-  autoTapToActivate: true,
-  longPressTimeout: 500,
-  pointerMode: 'auto',
-  drawingMode: 'svg',
-  defaultColor: 'yellow',
-  defaultStyle: 'fill',
-  defaultWrapper: 'none',
-  highlightIdFunction: _getNewHighlightId,
-  showCustomSelectionHandlesForActiveHighlights: true,
-  showCustomSelectionHandlesForTextSelection: false,
-  showCustomSelectionHandlesOnTouch: false,
-}
-
-// Workaround to allow programmatic text selection on tap in iOS Safari
-// See https://stackoverflow.com/a/79261423/1349044
-if (isTouchDevice && isWebKit) {
-  const tempInput = document.createElement('input');
-  tempInput.style.position = 'fixed';
-  tempInput.style.top = 0;
-  tempInput.style.opacity = 0;
-  tempInput.style.height = 0;
-  tempInput.style.fontSize = '16px'; // Prevent page zoom on input focus
-  tempInput.inputMode = 'none'; // Don't show keyboard
-  tempInput.tabIndex = -1; // Prevent user from tabbing to input
-  tempInput.ariaHidden = 'true'; // Hide from screen readers
-  const initializeSelection = (event) => {
-    if (document.readyState !== 'complete') return setTimeout(initializeSelection, 20);
-    if (!tempInput.parentElement) document.body.append(tempInput);
-    tempInput.focus();
-    setTimeout(() => {
-      tempInput.blur();
-    }, 100);
   }
-  initializeSelection();
-  document.addEventListener('visibilitychange', (event) => {
-    if (document.visibilityState === 'visible') initializeSelection();
-  });
-}
-
-// Make Highlighter available to JavaScript module (highlight-helper.mjs)
-globalThis.Highlighter = Highlighter;
+
+  // Make Highlighter available to JavaScript module (highlight-helper.mjs)
+  globalThis.Highlighter = Highlighter;
+
+})();