Serve viewer text selection from the canvas UI instead of a DOM text layer

Author: Balearica

scribe-ui/basic-viewer/pdf-viewer.js

@@ -1,5 +1,9 @@
 import scribe from '../../scribe.js';
 import { ScribeViewer } from '../viewer.js';
+// Both engines are imported so `ScribeViewer.customSelection` can toggle between them at runtime.
+// Import only one for a slimmer build.
+import '../js/selection/customSelectionEngine.js';
+import '../js/selection/domSelectionEngine.js';
 import { applyHighlight } from '../js/viewerHighlights.js';
 import { destroyContextMenu } from '../js/viewerCanvasInteraction.js';
 import {

scribe-ui/js/controls/debugMenu.js

@@ -1,4 +1,5 @@
 // Debug menu: developer-only tools, installed only when `DEBUG_MENU` in scribe-ui/devFlags.js is on and stripped from public builds.
+import { UiText } from '../viewerWordObjects.js';
 
 /** Bug glyph for the Debug section's rows. */
 const BUG_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">'
@@ -26,8 +27,33 @@ export function installDebugMenu(appMenu, viewer) {
   });
   appMenu.menuElem.appendChild(header);
 
-  // The overlay is built from this flag, so toggling it requires clearing the built text and re-rendering to apply.
+  // Off (the default) = the model-driven built-in engine; On = the DOM engine, whose invisible word spans sit under the browser's native selection.
   appMenu.addToggle(
+    'DOM-based text selection',
+    BUG_SVG,
+    () => !viewer.useCustomSelection,
+    () => {
+      viewer.setSelectionEngineDebug(viewer.useCustomSelection ? 'dom' : 'custom');
+      syncOverlayRow();
+    },
+  );
+
+  // Rebuild the text layer so the mode change reaches already-rendered pages.
+  appMenu.addToggle(
+    'Proof mode (word editing)',
+    BUG_SVG,
+    () => UiText.enableEditing,
+    () => {
+      UiText.enableEditing = !UiText.enableEditing;
+      viewer.state.displayMode = UiText.enableEditing ? 'proof' : 'invis';
+      viewer.destroyText(false);
+      viewer.displayPage(viewer.state.cp.n, false, true);
+    },
+  );
+
+  // The overlay is built from this flag, so toggling rebuilds the text layer to apply.
+  // Only the DOM engine has an overlay to disable (the built-in engine draws selection from the model), so this row is greyed and inert while the built-in engine is active.
+  const overlayRow = appMenu.addToggle(
     'Disable text overlay',
     BUG_SVG,
     () => viewer.textOverlayDisabledDebug,
@@ -38,11 +64,13 @@ export function installDebugMenu(appMenu, viewer) {
     },
   );
 
-  // The flag is read live on the next right-click, so toggling it needs no re-render.
-  appMenu.addToggle(
-    'Disable custom context menu',
-    BUG_SVG,
-    () => viewer.contextMenuDisabledDebug,
-    () => { viewer.contextMenuDisabledDebug = !viewer.contextMenuDisabledDebug; },
-  );
+  const syncOverlayRow = () => {
+    const inert = viewer.useCustomSelection;
+    overlayRow.item.style.opacity = inert ? '0.45' : '';
+    overlayRow.item.style.pointerEvents = inert ? 'none' : '';
+    overlayRow.item.title = inert ? 'DOM-based text selection only' : '';
+    overlayRow.item.tabIndex = inert ? -1 : 0;
+    overlayRow.sync();
+  };
+  syncOverlayRow();
 }

scribe-ui/js/controls/tools.js

@@ -40,7 +40,7 @@ const TB_PANEL_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24
  * @param {string} cfg.rootClass - The app's root class (for scoping the cursor rule).
  * @returns {{
  *   highlightElem: HTMLSpanElement, toolbarElem: HTMLSpanElement,
- *   getSelectedOverlayWords: () => Array<import('../viewerWordObjects.js').UiOcrWord>, updateCommentIcons: () => void,
+ *   updateCommentIcons: () => void,
  *   installBehaviors: () => (() => void)
  * }}
  */
@@ -64,8 +64,14 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
   const setTipColor = (c) => { if (tipPath && c) tipPath.style.fill = c; };
   setTipColor(highlightColor);
 
-  /** Toggle the highlighter cursor on the overlay words when highlight mode is active. */
+  /** Toggle the highlighter cursor over the page's text when highlight mode is active. */
   function updateHighlightCursorStyle() {
+    if (scribe.useCustomSelection) {
+      // No word elements to hang a cursor rule on: the selection engine sets the container's cursor.
+      scribe.textSel.cursorOverride = highlightMode ? HIGHLIGHT_CURSOR : null;
+      if (!highlightMode) scribe.scrollContainer.style.cursor = '';
+      return;
+    }
     if (!cursorStyleElem) {
       cursorStyleElem = document.createElement('style');
       document.head.appendChild(cursorStyleElem);
@@ -75,16 +81,11 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
       : '';
   }
 
-  /** UiOcrWord objects under the current browser text selection (via the HTML overlay). */
-  function getSelectedOverlayWords() {
-    return scribe.getWordsUnderTextSelection();
-  }
-
   function applyToSelection() {
-    const matchedWords = getSelectedOverlayWords();
+    const matchedWords = scribe.getWordsUnderTextSelection();
     if (matchedWords.length === 0 || !highlightColor) return false;
     applyHighlight(scribe, matchedWords, highlightColor, 0.5);
-    window.getSelection()?.removeAllRanges();
+    scribe.clearTextSelection();
     return true;
   }
 
@@ -643,6 +644,17 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
       cmtText.focus();
     };
 
+    /**
+     * The highlighted word under an event's pointer.
+     * @param {MouseEvent} event
+     */
+    const highlightWordAt = (event) => {
+      // The custom engine has no word spans, so hit-test the highlight by page geometry rather than event.target.
+      if (scribe.useCustomSelection) return scribe.textSel.hitTestHighlight(event.clientX, event.clientY)?.kw ?? null;
+      const wordEl = /** @type {Element} */ (event.target).closest('.scribe-word');
+      return wordEl ? /** @type {any} */ (wordEl)._scribeObj : null;
+    };
+
     /** Resolve the card target under an event: a comment mark, a note mark, or a commented word. */
     const cmtTargetFromEvent = (event) => {
       if (!(event.target instanceof Element)) return null;
@@ -659,8 +671,7 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
         const annot = (scribe.doc.annotations.pages[n] || []).filter((a) => a.type === 'text')[Number(noteEl.dataset.noteIdx)];
         return annot ? { kind: 'note', annot, n } : null;
       }
-      const wordEl = event.target.closest('.scribe-word');
-      const kw = wordEl && /** @type {any} */ (wordEl)._scribeObj;
+      const kw = highlightWordAt(event);
       if (kw && kw.highlightGroupId && kw.highlightComment) {
         return {
           kind: 'highlight', kw, groupId: kw.highlightGroupId, n: kw.word.line.page.n,
@@ -671,6 +682,19 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
 
     const cmtOver = (event) => { const t = cmtTargetFromEvent(event); if (t) cmtShow(t); };
     const cmtOut = (event) => { if (cmtTargetFromEvent(event)) cmtScheduleHide(); };
+    // With no word spans, the pointer crosses no element boundary over the text,
+    // so a hovered commented highlight must be sampled on pointer move rather than delegated from mouseover.
+    let cmtMoveRaf = null;
+    const cmtMove = (event) => {
+      if (cmtMoveRaf !== null) return;
+      const { clientX, clientY, target } = event;
+      cmtMoveRaf = requestAnimationFrame(() => {
+        cmtMoveRaf = null;
+        const t = cmtTargetFromEvent({ clientX, clientY, target });
+        if (t) cmtShow(t);
+        else if (cmtTarget && cmtTarget.kind === 'highlight') cmtScheduleHide();
+      });
+    };
     const cmtPress = (event) => {
       if (!(event.target instanceof Element)) return;
       const el = event.target.closest('.scribe-hl-cmark, .scribe-note-icon');
@@ -683,12 +707,10 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
         return;
       }
       // Gate on the color, not the comment: the card's footer is the only place to recolor or delete an uncommented highlight.
-      const wordEl = event.target.closest('.scribe-word');
-      const kw = wordEl && /** @type {any} */ (wordEl)._scribeObj;
+      const kw = highlightWordAt(event);
       if (!kw || !kw.highlightColor) return;
       // A drag that leaves a text selection is a selection gesture, not a click on the object.
-      const sel = window.getSelection();
-      if (sel && !sel.isCollapsed) return;
+      if (scribe.hasTextSelection()) return;
       event.stopPropagation();
       cmtPin({
         kind: 'highlight', kw, groupId: kw.highlightGroupId || null, n: kw.word.line.page.n,
@@ -704,6 +726,7 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
     };
     scribe.elem.addEventListener('mouseover', cmtOver);
     scribe.elem.addEventListener('mouseout', cmtOut);
+    if (scribe.useCustomSelection) scribe.elem.addEventListener('mousemove', cmtMove);
     scribe.elem.addEventListener('click', cmtPress);
     scribe.elem.addEventListener('focusin', cmtOver);
     scribe.elem.addEventListener('focusout', cmtOut);
@@ -888,6 +911,7 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
       commentObserver.disconnect();
       scribe.elem.removeEventListener('mouseover', cmtOver);
       scribe.elem.removeEventListener('mouseout', cmtOut);
+      scribe.elem.removeEventListener('mousemove', cmtMove);
       scribe.elem.removeEventListener('click', cmtPress);
       scribe.elem.removeEventListener('focusin', cmtOver);
       scribe.elem.removeEventListener('focusout', cmtOut);
@@ -914,7 +938,6 @@ export function createHighlightTool(scribe, rootElem, { colors, defaultColor, ro
   return {
     highlightElem,
     toolbarElem,
-    getSelectedOverlayWords,
     updateCommentIcons,
     installBehaviors,
   };

scribe-ui/js/selection/customSelectionEngine.js

@@ -0,0 +1,18 @@
+import { ScribeViewer } from '../../viewer.js';
+import { TextSelection } from '../viewerTextSelection.js';
+
+/**
+ * Importing this module is the build-time opt-in for the custom (DOM-less) selection engine.
+ * Import both this and `domSelectionEngine.js` to defer the choice to runtime via `ScribeViewer.customSelection`.
+ */
+ScribeViewer.registerSelectionEngine({
+  kind: 'custom',
+  /** @param {ScribeViewer} viewer */
+  attach(viewer) {
+    const textSel = new TextSelection(viewer);
+    viewer.textSel = textSel;
+    return textSel;
+  },
+});
+
+export { TextSelection };