@internetarchive/bookreader 5.0.0-10-alpha-3 → 5.0.0-101

package/src/plugins/search/plugin.search.js

@@ -1,9 +1,6 @@
-/* global BookReader */
+// @ts-check
 /**
  * Plugin for Archive.org book search
- * NOTE: This script must be loaded AFTER `plugin.mobile_nav.js`
- * as it mutates mobile nav drawer
- *
  * Events fired at various points throughout search processing are published
  * on the document DOM element. These can be subscribed to using jQuery's event
  * binding method `$.fn.on`. All of the events are prefixed with a BookReader
@@ -23,447 +20,428 @@
  * @event BookReader:SearchCanceled - When no results found. Receives
  *   `instance`
  */
+import { poll } from '../../BookReader/utils.js';
+import { renderBoxesInPageContainerLayer } from '../../BookReader/PageContainer.js';
 import SearchView from './view.js';
+import { marshallSearchResults } from './utils.js';
+import { BookReaderPlugin } from '../../BookReaderPlugin.js';
+import { applyVariables } from '../../util/strings.js';
+/** @typedef {import('../../BookReader/PageContainer').PageContainer} PageContainer */
+/** @typedef {import('../../BookReader/BookModel').PageIndex} PageIndex */
+/** @typedef {import('../../BookReader/BookModel').LeafNum} LeafNum */
+/** @typedef {import('../../BookReader/BookModel').PageNumString} PageNumString */
+
+// @ts-ignore
+const BookReader = /** @type {typeof import('@/src/BookReader.js').default} */(window.BookReader);
+
+export class SearchPlugin extends BookReaderPlugin {
+  options = {
+    enabled: true,
+    preTag: '{{{',
+    postTag: '}}}',
+    /**
+     * @type {import('@/src/util/strings.js').StringWithVars}
+     * Provides the variables: `query`, `preTag`, and `postTag` (from these options)
+     */
+    searchInsideUrl: '/fulltext/inside.php?' + [
+      'q={{query|urlencode}}',
+      'pre_tag={{preTag|urlencode}}',
+      'post_tag={{postTag|urlencode}}',
+    ].join('&'),
+    /** @type {string} */
+    initialSearchTerm: null,
+    goToFirstResult: false,
+  }
 
-jQuery.extend(BookReader.defaultOptions, {
-  server: 'ia600609.us.archive.org',
-  bookId: '',
-  subPrefix: '',
-  bookPath: '',
-  enableSearch: true,
-  searchInsideUrl: '/fulltext/inside.php',
-  initialSearchTerm: null,
-});
-
-/** @override */
-BookReader.prototype.setup = (function (super_) {
-  return function (options) {
-    super_.call(this, options);
+  /**
+   * @override
+   * @param {Partial<SearchPlugin['options']>} options
+   **/
+  setup(options) {
+    super.setup(options);
 
     this.searchTerm = '';
+    /** @type {SearchInsideResults | null} */
     this.searchResults = null;
-    this.searchInsideUrl = options.searchInsideUrl;
-    this.enableSearch = options.enableSearch;
-
-    // Base server used by some api calls
-    this.bookId = options.bookId;
-    this.server = options.server;
-    this.subPrefix = options.subPrefix;
-    this.bookPath = options.bookPath;
-
+    this.searchInsideUrl = this.options.searchInsideUrl;
+    this.enabled = this.options.enabled;
     this.searchXHR = null;
-    this._cancelSearch.bind(this);
-    this.cancelSearchRequest.bind(this);
-
-    if (this.searchView) { return; }
-    this.searchView = new SearchView({
-      br: this,
-      searchCancelledCallback: () => {
-        this._cancelSearch();
-        this.trigger('SearchCanceled', { term: this.searchTerm, instance: this });
-      }
-    });
-  };
-})(BookReader.prototype.setup);
 
-/** @override */
-BookReader.prototype.init = (function (super_) {
-  return function () {
-    super_.call(this);
+    /** @type { {[pageIndex: number]: SearchInsideMatchBox[]} } */
+    this._searchBoxesByIndex = {};
+
+    if (this.enabled) {
+      this.searchView = new SearchView({
+        br: this.br,
+        searchCancelledCallback: () => {
+          this._cancelSearch();
+          this.br.trigger('SearchCanceled', { term: this.searchTerm, instance: this.br });
+        },
+      });
+    } else {
+      this.searchView = null;
+    }
+  }
 
-    if (this.options.enableSearch && this.options.initialSearchTerm) {
+  /** @override */
+  init() {
+    super.init();
+
+    if (!this.enabled) return;
+
+    this.searchView.init();
+    if (this.options.initialSearchTerm) {
+      /**
+       * this.search() take two parameter
+       * 1. this.options.initialSearchTerm - search term
+       * 2. {
+       *  goToFirstResult: this.options.goToFirstResult,
+       *  suppressFragmentChange: false // always want to change fragment in URL
+       * }
+       */
       this.search(
         this.options.initialSearchTerm,
-        { goToFirstResult: this.options.goToFirstResult, suppressFragmentChange: true }
+        { goToFirstResult: this.options.goToFirstResult, suppressFragmentChange: false },
       );
     }
-  };
-})(BookReader.prototype.init);
-
-/** @override */
-BookReader.prototype.buildToolbarElement = (function (super_) {
-  return function () {
-    const $el = super_.call(this);
-    if (!this.enableSearch) { return; }
+  }
+
+  /**
+   * @override
+   * @protected
+   * @param {JQuery<HTMLElement>} $toolbarElement
+   */
+  _configureToolbar($toolbarElement) {
+    if (!this.enabled) { return; }
     if (this.searchView.dom.toolbarSearch) {
-      $el.find('.BRtoolbarSectionInfo').after(this.searchView.dom.toolbarSearch);
+      $toolbarElement.find('.BRtoolbarSectionInfo').after(this.searchView.dom.toolbarSearch);
     }
-    return $el;
-  };
-})(BookReader.prototype.buildToolbarElement);
-
-/**
- * @typedef {object} SearchOptions
- * @property {boolean} goToFirstResult
- * @property {boolean} disablePopup
- * @property {(null|function)} error - @deprecated at v.5.0
- * @property {(null|function)} success - @deprecated at v.5.0
- */
-
-/**
- * Submits search request
- *
- * @param {string} term
- * @param {SearchOptions} overrides
- */
-BookReader.prototype.search = function(term = '', overrides = {}) {
-  /** @type {SearchOptions} */
-  const defaultOptions = {
-    goToFirstResult: false, /* jump to the first result (default=false) */
-    disablePopup: false,    /* don't show the modal progress (default=false) */
-    suppressFragmentChange: false, /* don't change the URL on initial load */
-    error: null,            /* optional error handler (default=null) */
-    success: null,          /* optional success handler (default=null) */
-
-  };
-  const options = jQuery.extend({}, defaultOptions, overrides);
-  this.suppressFragmentChange = options.suppressFragmentChange;
-
-  // strip slashes, since this goes in the url
-  this.searchTerm = term.replace(/\//g, ' ');
-
-  if (!options.suppressFragmentChange) {
-    this.trigger(BookReader.eventNames.fragmentChange);
+    return $toolbarElement;
   }
 
-  // Add quotes to the term. This is to compenstate for the backends default OR query
-  // term = term.replace(/['"]+/g, '');
-  // term = '"' + term + '"';
-
-  // Remove the port and userdir
-  const serverPath = this.server.replace(/:.+/, '');
-  const baseUrl = `https://${serverPath}${this.searchInsideUrl}?`;
-
-  // Remove subPrefix from end of path
-  let path = this.bookPath;
-  const subPrefixWithSlash = `/${this.subPrefix}`;
-  if (this.bookPath.length - this.bookPath.lastIndexOf(subPrefixWithSlash) == subPrefixWithSlash.length) {
-    path = this.bookPath.substr(0, this.bookPath.length - subPrefixWithSlash.length);
+  /**
+   * @override
+   * @param {import ("@/src/BookReader/PageContainer.js").PageContainer} pageContainer
+   */
+  _configurePageContainer(pageContainer) {
+    if (this.enabled && pageContainer.page && pageContainer.page.index in this._searchBoxesByIndex) {
+      const pageIndex = pageContainer.page.index;
+      const boxes = this._searchBoxesByIndex[pageIndex];
+      renderBoxesInPageContainerLayer(
+        'searchHiliteLayer',
+        boxes,
+        pageContainer.page,
+        pageContainer.$container[0],
+        boxes.map(b => `match-index-${b.matchIndex}`),
+      );
+    }
+    return pageContainer;
   }
 
-  const urlParams = {
-    item_id: this.bookId,
-    doc: this.subPrefix,
-    path,
-    q: term,
-  };
+  /**
+   * Submits search request
+   *
+   * @param {string} term
+   * @param {Partial<SearchOptions>} overrides
+   */
+  async search(term = '', overrides = {}) {
+    /** @type {SearchOptions} */
+    const defaultOptions = {
+      goToFirstResult: false, /* jump to the first result (default=false) */
+      disablePopup: false,    /* don't show the modal progress (default=false) */
+      suppressFragmentChange: false, /* don't change the URL on initial load */
+      error: null,            /* optional error handler (default=null) */
+      success: null,          /* optional success handler (default=null) */
+
+    };
+    const options = jQuery.extend({}, defaultOptions, overrides);
+    this.suppressFragmentChange = options.suppressFragmentChange;
+    this.searchCancelled = false;
+
+    // strip slashes, since this goes in the url
+    this.searchTerm = term.replace(/\//g, ' ');
+
+    if (!options.suppressFragmentChange) {
+      this.br.trigger(BookReader.eventNames.fragmentChange);
+    }
+
+    // Add quotes to the term. This is to compenstate for the backends default OR query
+    // term = term.replace(/['"]+/g, '');
+    // term = '"' + term + '"';
 
-  // NOTE that the API does not expect / (slashes) to be encoded. (%2F) won't work
-  const paramStr = $.param(urlParams).replace(/%2F/g, '/');
+    const url = applyVariables(this.options.searchInsideUrl, this.br.options.vars, {
+      query: term,
+      preTag: this.options.preTag,
+      postTag: this.options.postTag,
+    });
 
-  const url = `${baseUrl}${paramStr}`;
+    const callSearchResultsCallback = (searchInsideResults) => {
+      if (this.searchCancelled) {
+        return;
+      }
+      const responseHasError = searchInsideResults.error || !searchInsideResults.matches.length;
+      const hasCustomError = typeof options.error === 'function';
+      const hasCustomSuccess = typeof options.success === 'function';
+
+      if (responseHasError) {
+        console.error('Search Inside Response Error', searchInsideResults.error || 'matches.length == 0');
+        hasCustomError
+          ? options.error.call(this, searchInsideResults, options)
+          : this.BRSearchCallbackError(searchInsideResults);
+      } else {
+        hasCustomSuccess
+          ? options.success.call(this, searchInsideResults, options)
+          : this.BRSearchCallback(searchInsideResults, options);
+      }
+    };
+
+    this.br.trigger('SearchStarted', { term: this.searchTerm, instance: this.br });
+    callSearchResultsCallback(await $.ajax({
+      url: url,
+      cache: true,
+      xhrFields: {
+        withCredentials: this.br.protected,
+      },
+      beforeSend: xhr => { this.searchXHR = xhr; },
+    }));
+  }
 
-  const cleanup = () => {
+  /**
+   * cancels AJAX Call
+   * emits custom event
+   */
+  _cancelSearch() {
+    this.searchXHR?.abort();
+    this.searchView.clearSearchFieldAndResults(false);
+    this.searchTerm = '';
     this.searchXHR = null;
-    window.BRSearchInProgress = () => {};
-  };
+    this.searchCancelled = true;
+    this.searchResults = null;
+  }
 
-  const processSearchResults = (searchInsideResults) => {
-    if (!this.searchXHR) {
-      return;
-    }
-    const responseHasError = searchInsideResults.error || !searchInsideResults.matches.length;
-    const hasCustomError = typeof options.error === 'function';
-    const hasCustomSuccess = typeof options.success === 'function';
-
-    if (responseHasError) {
-      hasCustomError
-        ? options.error.call(this, searchInsideResults, options)
-        : this.BRSearchCallbackError(searchInsideResults, options);
-    } else {
-      hasCustomSuccess
-        ? options.success.call(this, searchInsideResults, options)
-        : this.BRSearchCallback(searchInsideResults, options);
+  /**
+   * External function to cancel search
+   * checks for term & xhr in flight before running
+   */
+  cancelSearchRequest() {
+    this.searchCancelled = true;
+    if (this.searchXHR !== null) {
+      this._cancelSearch();
+      this.searchView.toggleSearchPending();
+      this.br.trigger('SearchCanceled', { term: this.searchTerm, instance: this.br });
     }
-    cleanup();
-  };
-
-  const beforeSend = (xhr) => {
-    this.searchXHR = xhr;
-    window.BRSearchInProgress = processSearchResults;
-  };
-
-  this.trigger('SearchStarted', { term: this.searchTerm, instance: this });
-  return $.ajax({
-    url: url,
-    dataType: 'jsonp',
-    beforeSend,
-    jsonpCallback: 'BRSearchInProgress'
-  }).then(processSearchResults);
-};
-
-/**
- * cancels AJAX Call
- * emits custom event
- */
-BookReader.prototype._cancelSearch = function () {
-  this.searchXHR?.abort();
-  this.searchView.clearSearchFieldAndResults(false);
-  this.searchTerm = '';
-  this.searchXHR = null;
-  this.searchResults = [];
-  window.BRSearchInProgress = () => {};
-};
-
-/**
- * External function to cancel search
- * checks for term & xhr in flight before running
- */
-BookReader.prototype.cancelSearchRequest = function () {
-  if (this.searchXHR !== null) {
-    this._cancelSearch();
-    this.searchView.toggleSearchPending();
-    this.trigger('SearchCanceled', { term: this.searchTerm, instance: this });
   }
-};
-
-/**
-  * @typedef {object} SearchInsideMatchBox
-  * @property {number} page
-  * @property {number} r
-  * @property {number} l
-  * @property {number} b
-  * @property {number} t
-  * @property {HTMLDivElement} [div]
-  */
 
-/**
- * @typedef {object} SearchInsideMatch
- * @property {string} text
- * @property {Array<{ page: number, boxes: SearchInsideMatchBox[] }>} par
- */
+  /**
+   * Search Results return handler
+   * @param {SearchInsideResults} results
+   * @param {object} options
+   * @param {boolean} options.goToFirstResult
+   */
+  BRSearchCallback(results, options) {
+    marshallSearchResults(
+      results,
+      pageNum => this.br.book.getPageNum(this.br.book.leafNumToIndex(pageNum)),
+      this.options.preTag,
+      this.options.postTag,
+    );
+    this.searchResults = results || null;
+
+    this.updateSearchHilites();
+    this.br.removeProgressPopup();
+    if (options.goToFirstResult) {
+      this.jumpToMatch(0);
+    }
+    this.br.trigger('SearchCallback', { results, options, instance: this.br });
+  }
 
-/**
- * @typedef {object} SearchInsideResults
- * @property {string} error
- * @property {SearchInsideMatch[]} matches
- * @property {boolean} indexed
- */
+  /**
+   * Main search results error handler
+   * @param {SearchInsideResults} results
+   */
+  BRSearchCallbackError(results) {
+    this._BRSearchCallbackError(results);
+  }
 
-/**
- * Search Results return handler
- * @callback
- * @param {SearchInsideResults} results
- * @param {object} options
- * @param {boolean} options.goToFirstResult
- */
-BookReader.prototype.BRSearchCallback = function(results, options) {
-  this.searchResults = results || [];
-
-  this.updateSearchHilites();
-  this.removeProgressPopup();
-  if (options.goToFirstResult) {
-    const pageIndex = this._models.book.leafNumToIndex(results.matches[0].par[0].page);
-    this._searchPluginGoToResult(pageIndex);
+  /**
+   * @private draws search results error
+   * @param {SearchInsideResults} results
+   */
+  _BRSearchCallbackError(results) {
+    this.searchResults = results;
+    const payload = {
+      term: this.searchTerm,
+      results,
+      instance: this.br,
+    };
+    if (results.error) {
+      this.br.trigger('SearchCallbackError', payload);
+    } else if (0 == results.matches.length) {
+      if (false === results.indexed) {
+        this.br.trigger('SearchCallbackBookNotIndexed', payload);
+        return;
+      }
+      this.br.trigger('SearchCallbackEmpty', payload);
+    }
   }
-  this.trigger('SearchCallback', { results, options, instance: this });
-};
 
-/**
- * Main search results error handler
- * @callback
- * @param {SearchInsideResults} results
- */
-BookReader.prototype.BRSearchCallbackError = function(results) {
-  this._BRSearchCallbackError(results);
-};
+  /**
+   * updates search on-page highlights controller
+   */
+  updateSearchHilites() {
+    /** @type {SearchInsideMatch[]} */
+    const matches = this.searchResults?.matches || [];
+    /** @type { {[pageIndex: number]: SearchInsideMatchBox[]} } */
+    const boxesByIndex = {};
+
+    // Clear any existing svg layers
+    this.removeSearchHilites();
+
+    // Group by pageIndex
+    for (const match of matches) {
+      for (const box of match.par[0].boxes) {
+        const pageIndex = this.br.book.leafNumToIndex(box.page);
+        const pageBoxes = boxesByIndex[pageIndex] || (boxesByIndex[pageIndex] = []);
+        pageBoxes.push(box);
+      }
+    }
 
-/**
- * @private draws search results error
- * @callback
- * @param {SearchInsideResults} results
- * @param {jQuery} $el
- * @param {boolean} fade
- */
-BookReader.prototype._BRSearchCallbackError = function(results) {
-  this.searchResults = results;
-  const basePayload = {
-    term: this.searchTerm,
-    instance: this,
-  };
-  if (results.error) {
-    const payload = Object.assign({}, basePayload, { results });
-    this.trigger('SearchCallbackError', payload);
-  } else if (0 == results.matches.length) {
-    if (false === results.indexed) {
-      this.trigger('SearchCallbackBookNotIndexed', basePayload);
-      return;
+    // update any already created pages
+    for (const [pageIndexString, boxes] of Object.entries(boxesByIndex)) {
+      const pageIndex = parseFloat(pageIndexString);
+      const page = this.br.book.getPage(pageIndex);
+      const pageContainers = this.br.getActivePageContainerElementsForIndex(pageIndex);
+      for (const container of pageContainers) {
+        renderBoxesInPageContainerLayer('searchHiliteLayer', boxes, page, container, boxes.map(b => `match-index-${b.matchIndex}`));
+      }
     }
-    this.trigger('SearchCallbackEmpty', basePayload);
+
+    this._searchBoxesByIndex = boxesByIndex;
   }
-};
 
-/**
- * updates search on-page highlights controller
- */
-BookReader.prototype.updateSearchHilites = function() {
-  if (this.constMode2up == this.mode) {
-    this.updateSearchHilites2UP();
-    return;
+  /**
+   * remove search highlights
+   */
+  removeSearchHilites() {
+    $(this.br.getActivePageContainerElements()).find('.searchHiliteLayer').remove();
   }
-  this.updateSearchHilites1UP();
-};
 
-/**
- * update search on-page highlights in 1up mode
- */
-BookReader.prototype.updateSearchHilites1UP = function() {
-  const results = this.searchResults;
-  if (null == results) return;
-  results.matches?.forEach(match => {
-    match.par[0].boxes.forEach(box => {
-      const pageIndex = this.leafNumToIndex(box.page);
-      const pageIsInView = jQuery.inArray(pageIndex, this.displayedIndices) >= 0;
-      if (pageIsInView) {
-        if (!box.div) {
-          //create a div for the search highlight, and stash it in the box object
-          box.div = document.createElement('div');
-          $(box.div).prop('className', 'BookReaderSearchHilite').appendTo(this.$(`.pagediv${pageIndex}`));
-        }
-        const page = this._models.book.getPage(pageIndex);
-        const highlight = {
-          width: this._modes.mode1Up.physicalInchesToDisplayPixels((box.r - box.l) / page.ppi),
-          height: this._modes.mode1Up.physicalInchesToDisplayPixels((box.b - box.t) / page.ppi),
-          left: this._modes.mode1Up.physicalInchesToDisplayPixels(box.l / page.ppi),
-          top: this._modes.mode1Up.physicalInchesToDisplayPixels(box.t / page.ppi),
-        };
-        $(box.div).css(highlight);
-      } else {
-        if (box.div) {
-          $(box.div).remove();
-          box.div = null;
-        }
+  /**
+   * Goes to the page specified. If the page is not viewable, tries to load the page
+   * FIXME Most of this logic is IA specific, and should be less integrated into here
+   * or at least more configurable.
+   * @param {number} matchIndex
+   */
+  async jumpToMatch(matchIndex) {
+    const match = this.searchResults?.matches[matchIndex];
+    const book = this.br.book;
+    const pageIndex = book.leafNumToIndex(match.par[0].page);
+    const page = book.getPage(pageIndex);
+    const onNearbyPage = Math.abs(this.br.currentIndex() - pageIndex) < 3;
+    let makeUnviewableAtEnd = false;
+    if (!page.isViewable) {
+      const resp = await fetch('/services/bookreader/request_page?' + new URLSearchParams({
+        id: this.br.options.bookId,
+        subprefix: this.br.options.subPrefix,
+        leafNum: page.leafNum,
+      })).then(r => r.json());
+
+      for (const leafNum of resp.value) {
+        book.getPage(book.leafNumToIndex(leafNum)).makeViewable();
       }
-    });
-  });
-};
 
-/**
- * update search on-page highlights in 2up mode
- */
-BookReader.prototype.updateSearchHilites2UP = function() {
-  const results = this.searchResults;
-
-  if (results === null) return;
-
-  const { matches = [] } = results;
-  matches.forEach((match) => {
-    match.par[0].boxes.forEach(box => {
-      const pageIndex = this.leafNumToIndex(match.par[0].page);
-      const pageIsInView = jQuery.inArray(pageIndex, this.displayedIndices) >= 0;
-      const { isViewable } = this._models.book.getPage(pageIndex);
-
-      if (pageIsInView && isViewable) {
-        if (!box.div) {
-          //create a div for the search highlight, and stash it in the box object
-          box.div = document.createElement('div');
-          $(box.div).addClass('BookReaderSearchHilite')
-            .appendTo(this.refs.$brTwoPageView);
-        }
-        this.setHilightCss2UP(box.div, pageIndex, box.l, box.r, box.t, box.b);
-      } else {
-        // clear stale reference
-        if (box.div) {
-          $(box.div).remove();
-          box.div = null;
-        }
+      // not able to show page; make the page viewable anyways so that it can
+      // actually open. On IA, it has a fallback to a special error page.
+      if (!resp.value.length) {
+        book.getPage(pageIndex).makeViewable();
+        makeUnviewableAtEnd = true;
       }
-    });
-  });
-};
 
-/**
- * remove search highlights
- */
-BookReader.prototype.removeSearchHilites = function() {
-  const results = this.searchResults;
-  if (null == results || !results.matches) { return; }
-  results.matches.forEach(match => {
-    match.par[0].boxes.forEach(box => {
-      if (null != box.div) {
-        $(box.div).remove();
-        box.div = null;
+      // Trigger an update of book
+      this.br._modes.mode1Up.mode1UpLit.updatePages();
+      if (this.br.activeMode == this.br._modes.mode1Up) {
+        await this.br._modes.mode1Up.mode1UpLit.updateComplete;
       }
-    });
-  });
-};
+    }
+    /* this updates the URL */
+    if (!this.br._isIndexDisplayed(pageIndex)) {
+      this.suppressFragmentChange = false;
+      this.br.jumpToIndex(pageIndex);
+    }
 
-/**
- * @private
- * Goes to the page specified. If the page is not viewable, tries to load the page
- * FIXME Most of this logic is IA specific, and should be less integrated into here
- * or at least more configurable.
- * @param {PageIndex} pageIndex
- */
-BookReader.prototype._searchPluginGoToResult = async function (pageIndex) {
-  const { book } = this._models;
-  const page = book.getPage(pageIndex);
-  let makeUnviewableAtEnd = false;
-  if (!page.isViewable) {
-    const resp = await fetch('/services/bookreader/request_page?' + new URLSearchParams({
-      id: this.options.bookId,
-      subprefix: this.options.subPrefix,
-      leafNum: page.leafNum,
-    })).then(r => r.json());
-
-    for (const leafNum of resp.value) {
-      book.getPage(book.leafNumToIndex(leafNum)).makeViewable();
+    // Reset it to unviewable if it wasn't resolved
+    if (makeUnviewableAtEnd) {
+      book.getPage(pageIndex).makeViewable(false);
     }
 
-    // not able to show page; make the page viewable anyways so that it can
-    // actually open. On IA, it has a fallback to a special error page.
-    if (!resp.value.length) {
-      book.getPage(pageIndex).makeViewable();
-      makeUnviewableAtEnd = true;
+    // Scroll/flash in the ui
+    const $boxes = await poll(() => $(`rect.match-index-${match.matchIndex}`), { until: result => result.length > 0 });
+    if ($boxes.length) {
+      $boxes.css('animation', 'none');
+      $boxes[0].scrollIntoView({
+        // Only vertically center the highlight if we're in 1up or in full screen. In
+        // 2up, if we're not fullscreen, the whole body gets scrolled around to try to
+        // center the highlight 🙄 See:
+        // https://stackoverflow.com/questions/11039885/scrollintoview-causing-the-whole-page-to-move/11041376
+        // Note: nearest doesn't quite work great, because the ReadAloud toolbar is now
+        // full-width, and covers up the last line of the highlight.
+        block: this.br.constMode1up == this.br.mode || this.br.isFullscreenActive ? 'center' : 'nearest',
+        inline: 'center',
+        behavior: onNearbyPage ? 'smooth' : 'auto',
+      });
+      // wait for animation to start
+      await new Promise(resolve => setTimeout(resolve, 100));
+      $boxes.removeAttr("style");
     }
   }
-  /* this updates the URL */
-  this.suppressFragmentChange = false;
-  this.jumpToIndex(pageIndex);
 
-  // Reset it to unviewable if it wasn't resolved
-  if (makeUnviewableAtEnd) {
-    book.getPage(pageIndex).makeViewable(false);
+  /**
+   * Removes all search pins
+   */
+  removeSearchResults(suppressFragmentChange = false) {
+    this.removeSearchHilites(); //be sure to set all box.divs to null
+    this.searchTerm = null;
+    this.searchResults = null;
+    if (!suppressFragmentChange) {
+      this.br.trigger(BookReader.eventNames.fragmentChange);
+    }
   }
-};
+}
+BookReader?.registerPlugin('search', SearchPlugin);
 
 /**
- * Removes all search pins
+ * @typedef {object} SearchOptions
+ * @property {boolean} goToFirstResult
+ * @property {boolean} disablePopup
+ * @property {boolean} suppressFragmentChange
+ * @property {(null|function)} error (deprecated)
+ * @property {(null|function)} success (deprecated)
  */
-BookReader.prototype.removeSearchResults = function(suppressFragmentChange = false) {
-  this.removeSearchHilites(); //be sure to set all box.divs to null
-  this.searchTerm = null;
-  this.searchResults = null;
-  if (!suppressFragmentChange) {
-    this.trigger(BookReader.eventNames.fragmentChange);
-  }
-};
 
 /**
- * Returns true if a search highlight is currently being displayed
- * @returns {boolean}
+ * @typedef {object} SearchInsideMatchBox
+ * @property {number} page
+ * @property {number} r
+ * @property {number} l
+ * @property {number} b
+ * @property {number} t
+ * @property {HTMLDivElement} [div]
+ * @property {number} matchIndex This is a fake field! not part of the API response. The index of the match that contains this box in total search results matches.
  */
-BookReader.prototype.searchHighlightVisible = function() {
-  const results = this.searchResults;
-  let visiblePages = [];
-  if (null == results) return false;
-
-  if (this.constMode2up == this.mode) {
-    visiblePages = [this.twoPage.currentIndexL, this.twoPage.currentIndexR];
-  } else if (this.constMode1up == this.mode) {
-    visiblePages = [this.currentIndex()];
-  } else {
-    return false;
-  }
 
-  results.matches.some(match => {
-    return match.par[0].boxes.some(box => {
-      const pageIndex = this.leafNumToIndex(box.page);
-      if (jQuery.inArray(pageIndex, visiblePages) >= 0) {
-        return true;
-      }
-    });
-  });
+/**
+ * @typedef {object} SearchInsideMatch
+ * @property {number} matchIndex This is a fake field! Not part of the API response. It is added by the JS.
+ * @property {string} displayPageNumber (fake field) The page number as it should be displayed in the UI.
+ * @property {string} html (computed field) The html-escaped raw html to display in the UI.
+ * @property {string} text
+ * @property {Array<{ page: number, boxes: SearchInsideMatchBox[] }>} par
+ */
 
-  return false;
-};
+/**
+ * @typedef {object} SearchInsideResults
+ * @property {string} q
+ * @property {string} error
+ * @property {SearchInsideMatch[]} matches
+ * @property {boolean} indexed
+ */