feat: cssHighlights helper — paint Range-based decorations without mutating DOM

Wraps the CSS Custom Highlights API for plugins that want to decorate
text (syntax highlighting, spell-check, find-and-replace, lint, search)
without splitText / innerHTML mutation that fights Etherpad's Ace
bookkeeping.

API:
  const reg = createCssHighlights();
  reg.setLineRanges(lineEl, [{start, end, cls}, ...]);  // per line
  reg.clearAll();                                        // global reset
  reg.removeLineRanges(lineEl);                          // single line

Each instance owns its own Highlight registry so multiple plugins can
coexist (recommend cls namespacing like 'myplugin-keyword').

Also exports buildRange / buildSegments / isSupported as pure helpers
for unit testing without a browser window.

setLineRanges no-ops gracefully when CSS.highlights is unavailable
(Chrome <105, Firefox <140, Safari <17.2).

Adds jsdom devDep + 11 unit tests covering buildSegments, buildRange
(single + multi-node + out-of-bounds), isSupported, and the registry
factory's setLineRanges/removeLineRanges/clearAll behavior with a stub
Highlight implementation.

README: new section under Logger explaining the 'don't mutate the DOM
Ace owns' lesson and the API.

Bumps 0.4.1 -> 0.5.0 (new helper export).

Author: JohnMcLear

README.md

@@ -290,6 +290,43 @@ log.info('loaded');
 log.warn('something');
 ```
 
+### `cssHighlights()` — paint Range-based decorations without mutating Ace's DOM
+
+Use cases: syntax highlighting, spell-check squiggles, find-and-replace highlights, lint indicators, "search-in-pad" UIs.
+
+The trap: any plugin that calls `splitText` / `insertBefore` / `innerHTML =` to inject decorative `<span>`s into a line div is mutating DOM that Etherpad's Ace owns. Ace tracks each line's text nodes, attribute spans, and `_magicdom_dirtiness.knownHTML`. Mutating that DOM mid-edit fights its bookkeeping — broken caret on active-line typing, broken changeset application from collaborators, stuck stale decorations.
+
+The fix: register character ranges with the browser's [CSS Custom Highlights API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API) and let the browser composite the paint via `::highlight()` CSS rules. **The DOM stays exactly as Ace wrote it** — Ace's bookkeeping never sees your decorations.
+
+```js
+// Client-side (static/js/index.js)
+const {createCssHighlights} = require('ep_plugin_helpers/css-highlights');
+
+const reg = createCssHighlights();
+
+// Whenever a line should re-paint (acePostWriteDomLineHTML, MutationObserver,
+// aceEditEvent, language change, …):
+reg.setLineRanges(lineEl, [
+  {start: 0,  end: 5,  cls: 'my-keyword'},
+  {start: 12, end: 18, cls: 'my-string'},
+]);
+
+// On a global state reset (e.g. user changed language):
+reg.clearAll();
+```
+
+```css
+/* static/css/editor.css — applied inside the inner ace iframe */
+::highlight(my-keyword) { color: #d73a49; font-weight: bold; }
+::highlight(my-string)  { color: #032f62; }
+```
+
+**Returns:** `setLineRanges(lineEl, ranges)`, `removeLineRanges(lineEl)`, `clearAll()`, plus `buildRange` / `buildSegments` exposed as pure helpers for unit testing without a browser window.
+
+Each instance owns its own Highlight registry — multiple plugins can use this helper side-by-side without colliding (as long as their `cls` names don't clash; namespacing like `myplugin-keyword` is recommended).
+
+`setLineRanges` no-ops gracefully on browsers that lack `CSS.highlights` (Chrome < 105, Firefox < 140, Safari < 17.2). The host editor still works; just no decoration paint.
+
 ## Client vs Server imports
 
 Etherpad bundles client-side JS with esbuild. To avoid pulling Node.js modules into the browser bundle:

css-highlights.js

@@ -0,0 +1,163 @@
+'use strict';
+
+// cssHighlights — wrapper around the CSS Custom Highlights API for plugins
+// that want to paint Range-based decorations *without mutating the editor's
+// DOM*. Use cases: syntax highlighting, spell-check squiggles, find-and-
+// replace highlights, lint indicators, "search-in-pad" UIs.
+//
+// Why not splitText / inject <span>: Etherpad's Ace tracks every line's
+// internal state (text nodes, attribute spans, _magicdom_dirtiness.knownHTML).
+// Mutating the DOM that Ace owns fights its bookkeeping — broken caret on
+// active-line typing, broken collab changeset application, stuck stale
+// decorations. Range-based highlights register with the browser; the DOM
+// itself stays exactly as Ace wrote it.
+//
+// CSS Custom Highlights ships in Chrome 105+, Safari 17.2+, Firefox 140+.
+// On older browsers `setLineRanges` no-ops gracefully — host editor still
+// works, just without the decoration paint.
+//
+// Usage (client-side; this module loads in the browser pad bundle):
+//
+//   const {createCssHighlights} = require('ep_plugin_helpers/css-highlights');
+//   const reg = createCssHighlights();
+//
+//   // Whenever a line should re-paint:
+//   reg.setLineRanges(lineEl, [
+//     {start: 0,  end: 5,  cls: 'my-keyword'},
+//     {start: 12, end: 18, cls: 'my-string'},
+//   ]);
+//
+//   // CSS:
+//   //   ::highlight(my-keyword) { color: #d73a49; }
+//   //   ::highlight(my-string)  { color: #032f62; }
+//
+// On language change / state reset:
+//   reg.clearAll();
+//
+// A line that the host removes from the DOM has its WeakMap entry GC'd
+// automatically; no explicit cleanup needed.
+
+const isSupported = (win) => {
+  if (!win || !win.Highlight) return false;
+  if (!win.CSS || !win.CSS.highlights) return false;
+  return typeof win.CSS.highlights.set === 'function';
+};
+
+const buildSegments = (lineEl, win) => {
+  const doc = lineEl.ownerDocument;
+  const walker = doc.createTreeWalker(lineEl, win.NodeFilter.SHOW_TEXT);
+  const segs = [];
+  let pos = 0;
+  let n;
+  while ((n = walker.nextNode())) {
+    const len = n.nodeValue.length;
+    segs.push({node: n, start: pos, len});
+    pos += len;
+  }
+  return segs;
+};
+
+// Build a DOM Range covering the [start, end) character offsets within the
+// line's flattened text. Returns null if the bounds fall outside the line.
+const buildRange = (doc, segs, start, end) => {
+  let startNode = null;
+  let startOff = 0;
+  let endNode = null;
+  let endOff = 0;
+  for (const seg of segs) {
+    const segEnd = seg.start + seg.len;
+    if (!startNode && start >= seg.start && start <= segEnd) {
+      startNode = seg.node;
+      startOff = start - seg.start;
+    }
+    // We break the moment endNode is set, so by the time we reach this
+    // condition again endNode is guaranteed null.
+    if (end > seg.start && end <= segEnd) {
+      endNode = seg.node;
+      endOff = end - seg.start;
+      break;
+    }
+  }
+  if (!startNode || !endNode) return null;
+  const range = doc.createRange();
+  try {
+    range.setStart(startNode, startOff);
+    range.setEnd(endNode, endOff);
+  } catch (_e) {
+    return null;
+  }
+  return range;
+};
+
+const createCssHighlights = () => {
+  // Per-instance state so plugins don't share Highlight registries.
+  const lineRanges = new WeakMap();
+  const classHighlights = new Map();
+
+  const getOrCreateHighlight = (win, cls) => {
+    let h = classHighlights.get(cls);
+    if (h) return h;
+    h = new win.Highlight();
+    win.CSS.highlights.set(cls, h);
+    classHighlights.set(cls, h);
+    return h;
+  };
+
+  const removeLineRanges = (lineEl) => {
+    const map = lineRanges.get(lineEl);
+    if (!map) return;
+    for (const [cls, arr] of map) {
+      const h = classHighlights.get(cls);
+      if (!h) continue;
+      for (const r of arr) {
+        try { h.delete(r); } catch (_e) { /* stale range */ }
+      }
+    }
+    lineRanges.delete(lineEl);
+  };
+
+  const setLineRanges = (lineEl, tokenRanges) => {
+    if (!lineEl) return;
+    const win = lineEl.ownerDocument && lineEl.ownerDocument.defaultView;
+    if (!isSupported(win)) {
+      removeLineRanges(lineEl);
+      return;
+    }
+    removeLineRanges(lineEl);
+    if (!tokenRanges || !tokenRanges.length) return;
+    const segs = buildSegments(lineEl, win);
+    if (!segs.length) return;
+    const newMap = new Map();
+    for (const tr of tokenRanges) {
+      if (!tr || tr.start >= tr.end || !tr.cls) continue;
+      const range = buildRange(lineEl.ownerDocument, segs, tr.start, tr.end);
+      if (!range) continue;
+      const h = getOrCreateHighlight(win, tr.cls);
+      h.add(range);
+      let arr = newMap.get(tr.cls);
+      if (!arr) {
+        arr = [];
+        newMap.set(tr.cls, arr);
+      }
+      arr.push(range);
+    }
+    if (newMap.size > 0) lineRanges.set(lineEl, newMap);
+  };
+
+  const clearAll = () => {
+    for (const h of classHighlights.values()) {
+      try { h.clear(); } catch (_e) { /* ignore */ }
+    }
+  };
+
+  return {setLineRanges, removeLineRanges, clearAll, buildRange, buildSegments};
+};
+
+module.exports = {
+  createCssHighlights,
+  cssHighlights: createCssHighlights,
+  // Pure helpers exposed for unit testing without a browser window.
+  buildRange,
+  buildSegments,
+  isSupported,
+};

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ep_plugin_helpers",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Shared factory functions to eliminate boilerplate across Etherpad plugins",
   "author": {
     "name": "John McLear",
@@ -37,6 +37,7 @@
     "eslint": "^10.3.0",
     "eslint-config-etherpad": "^4.0.5",
     "mocha": "^11.0.0",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "jsdom": "^25.0.1"
   }
 }