@samuelbradshaw/highlight-helper-js 0.7.0

package/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+# From https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages#publishing-packages-to-the-npm-registry
+
+name: Publish Package to npmjs
+on:
+  release:
+    types: [published]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Samuel Bradshaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# Highlight Helper
+
+**Highlight Helper** is a JavaScript tool that enables highlighting or underlining text in an HTML page (such as a digital book or article). Highlighting text in an HTML document can be difficult, especially in cases where a highlight starts in one element but ends in another.
+
+Behind the scenes, Highlight Helper supports three different mechanisms for drawing highlights:
+
+1. [SVG shapes](https://developer.mozilla.org/en-US/docs/Web/SVG) drawn behind text (default).
+2. The [CSS Custom Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API) (experimental*).
+3. Inserted [HTML mark elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/mark).
+
+An HTML demo page that shows basic functionality can be found here: [Highlight Helper Demo](https://samuelbradshaw.github.io/highlight-helper-js/demo.html). Source code for the demo is in **demo.html**. Highlight Helper itself is in **highlight-helper.js**.
+
+*The Custom Highlight API requires Safari 17.2+ or Chrome 105+, and may hang when rendering a large number of highlights. Additionally, only a few CSS styles are supported (see [Styling Highlights](https://www.w3.org/TR/css-pseudo-4/#highlight-styling)). Browser support and loading speed will hopefully improve in the future. See also the [load test page](https://samuelbradshaw.github.io/highlight-helper-js/test-load.html) for Highlight Helper.
+
+### Documentation:
+- [Known issues](#known-issues)
+- [Getting started](#getting-started)
+- [Methods, options, and custom events](#methods-options-and-custom-events)
+    - [Methods](#methods)
+    - [Options](#options)
+    - [Custom events](#custom-events)
+- [Highlight attributes](#highlight-attributes)
+
+## <a name="known-issues"></a>Known issues
+
+There are a few known issues:
+
+- **Chrome on Android** doesn’t set focus (and therefore doesn’t show text selection handles) when text is programmatically selected (such as from a disambiguation panel), unless the selection is initiated directly by a user’s tap. However, if you’re working in a native app with a webview, you may be able to focus the webview from Android (see [StackOverflow](https://stackoverflow.com/a/6372903/1349044) and [GitHub](https://github.com/lawlsausage/save_gfy/pull/1)).
+- **Safari on iOS** doesn’t respect the text selection color set via CSS, so when a highlight is active for editing it has a blue overlay. However, if you’re working in a native app with a webview, you may be able to set colors natively with [tintColor](https://stackoverflow.com/a/60510743/1349044), [highlightView](https://developer.apple.com/documentation/uikit/uitextselectiondisplayinteraction/4195471-highlightview), and/or [handleViews](https://developer.apple.com/documentation/uikit/uitextselectiondisplayinteraction/4195470-handleviews).
+- **Safari on iOS** loses focus and doesn’t send a `visibilitychange` event if the device screen locks after a period of inactivity. This can cause selection handles to not show when unlocking your device and tapping on an existing highlight. Going to another app and back or manually triggering a `visibilitychange` event will allow Highlight Helper to set focus again. Focus will also be set again if the user long-presses to select text.
+- **Safari on iOS and macOS** doesn’t allow setting underline thickness on a ::highlight() pseudo-element, so underline highlights drawn by the Custom Highlight API are thin and hard to see (see [StackOverflow](https://stackoverflow.com/q/79060854/1349044) and [WebKit Bugzilla](https://bugs.webkit.org/show_bug.cgi?id=282027)). This will hopefully be fixed in a future version of Safari.
+
+
+## <a name="getting-started"></a>Getting started
+
+The easiest way to get started is to download demo.html and highlight-helper.js, open demo.html in a text editor and browser, and make changes to adapt it for your needs.
+
+In the source of demo.html, you’ll see CSS styles, followed by the HTML body, followed by JavaScript code. The JavaScript code does the following:
+1. Links to highlight-helper.js,
+2. Initializes a “Highlighter” instance with options,
+3. Pre-loads and draws a few existing highlights,
+3. Sets up logic to call Highlight Helper methods when buttons on the demo page are tapped, and
+4. Sets up listeners to respond to custom event messages that come back from Highlight Helper.
+
+All of the available methods, options, and custom events are documented below.
+
+
+## <a name="methods-options-and-custom-events"></a>Methods, options, and custom events
+
+### <a name="methods"></a>Methods
+
+- **loadHighlights(highlights)** – Load an array of existing highlights into Highlight Helper. Each highlight should have one or more of the properties described under “Highlight attributes” below. Omitted or invalid properties will fall back to previous or default values. If highlights are already loaded, this method will replace the loaded highlights by diffing for changes, then adding, removing, or updating individual highlights as needed.
+- **createOrUpdateHighlight(attributes, triggeredByUserAction)** – Create or update an individual highlight. `attributes` is an object with one or more of the properties described under “Highlight attributes” below. If a highlight ID isn’t passed in, the currently-active highlight will be updated, if there is one, otherwise a new highlight will be created. If it’s a new highlight and start and end bounds aren’t passed in, the highlight will be created based on selected text. `triggeredByUserAction` is an optional boolean (default: `true`). If this is set to false, the highlight won’t be activated after editing, and the color and style won’t be saved as the default for the next highlight.
+- **drawHighlights(highlightIds)** – Draw or redraw highlights on the page, given an array of highlight IDs. If no highlight IDs are passed, all highlights will be drawn. This shouldn’t need to be called frequently (Highlight Helper will usually draw or redraw highlights automatically).
+- **activateHighlight(highlightId)** – Activate a highlight for editing, given its `highlightId`. Only one highlight can be active at a time (because it’s tied to text selection, and there can only be one text selection on a page). Normally, a highlight activates automatically when the user taps it; however, if there are overlapping highlights or if `autoTapToActivate` is set to `false`, this will need to be called manually.
+- **activateHyperlink(position)** – Activate the specified hyperlink (i.e. open the link). `position` is the 0-based position of the link in the annotatable area of the page, relative to other links. Normally, a link opens automatically when the user taps it; however, if a highlight overlaps the hyperlink or if `autoTapToActivate` is set to `false`, this will need to be called manually.
+- **deactivateHighlights()** – Clear the text selection and deactivate any active highlights. Normally, highlights are deactivated automatically when the user taps away.
+- **removeHighlights(highlightIds)** – Remove the specified highlights. If `highlightIds` isn’t provided, all highlights will be removed.
+- **getActiveHighlightId()** – Get the ID of the currently-active highlight (if there is one).
+- **getHighlightInfo(highlightIds, paragraphId)** – Get highlight information for an array of highlight IDs. If no highlight IDs are passed, information for all relevant highlights will be returned. If `paragraphId` is provided, only highlights that start in the specified paragraph will be returned. Highlights will be sorted based on their position on the page.
+- **setOption(key, value)** – Change one of the initialized options. Available options are described below.
+- **getOptions()** – Get the initialized options, including defaults for any options that weren’t explicitly set.
+- **removeHighlighter()** – Removes the current Highlighter instance and all of its highlights from the page. If a new Highlighter instance is created with the same container (as defined by the `containerSelector` option), the previous instance for that container will be removed automatically (there can be multiple Highlighter instances on a page, but each one needs to have a different container).
+
+
+### <a name="options"></a>Options
+
+Options can be provided when Highlight Helper is initialized. They can also be set on demand using `setOption(key, value)` (described above). All of these settings are optional. If not specified, the default value for each option will be used.
+
+- **containerSelector** – CSS selector for the section of the page that should be annotatable. Default: `body`.
+- **paragraphSelector** – CSS selector for the paragraphs (or other block elements) on the page that should be annotatable. Each paragraph is expected to have an ID attribute in the HTML, which is used to keep track of where a highlight starts and ends. Default: `h1[id], h2[id], h3[id], h4[id], h5[id], h6[id], p[id], ol[id], ul[id], dl[id], tr[id]`.
+- **colors** – Object that describes available highlight colors. Keys are color names, and values are [CSS color values](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default: red, orange, yellow, green, blue (see full default values at the bottom of highlight-helper.js).
+- **styles** – Object that describes available highlight styles. Keys are style names, and there are four properties for each style: `css`, `svg`, `css-active` (optional), and `svg-active` (optional). `css` is a CSS string used for styling highlights in `highlight-api` and `mark-elements` drawing modes, as well as for read-only highlights. `svg` is an SVG string (one or more SVG shapes) to represent the highlight in `svg` drawing mode. `css-active` and `svg-active` are alternative styles to be used when a highlight is active. The CSS custom property `var(--hh-color)` can be used to reference the highlight color value. For SVG highlights, the following variables (if present) will be replaced with relevant values from the highlight’s DOMRect: `{x}`, `{y}`, `{width}`, `{height}`, `{top}`, `{bottom}`, `{left}`, `{right}`. Default: fill, single-underline, double-underline, colored-text, redacted (see full default values at the bottom of highlight-helper.js).
+- **wrappers** – Object that describes available highlight wrappers. Keys are wrapper names, and values are objects with two optional properties: `start` (HTML string to be inserted at the beginning of the highlight), and `end` (HTML string to be inserted at the end of the highlight). Only read-only highlights support wrappers. To avoid problems when calculating ranges and offsets, all [text nodes](https://developer.mozilla.org/en-US/docs/Web/API/Text) in the start and end wrappers will be removed (if text is needed, it should be rendered with CSS). `var(--hh-color)` can be used to reference the highlight color value. Variables surrounded by curly brackets will be replaced with variables stored in the `wrapperVariables` attribute of the highlight, if applicable. See default values at the bottom of highlight-helper.js.
+- **selectionHandles** – Object that describes custom selection handles that a user can drag to resize a selection or highlight. Because most touch devices have built-in selection handles, custom selection handles will only show when using a mouse or trackpad. There are two properties: `left` (HTML string to be used for the left selection handle) and `right` (HTML string to be used for the right selection handle). `var(--hh-color)` can be used to reference the highlight color value. See default values at the bottom of highlight-helper.js.
+- **rememberStyle** – Whether the most recent color, style, and wrapper should be remembered and used by default the next time the user creates a highlight. Boolean. Default: `true`.
+- **snapToWord** – Whether highlights should snap to the nearest word boundary. Spaces and dashes are considered word boundaries (this option may not work correctly in all languages). Boolean. Default: `false`.
+- **autoTapToActivate** – Whether Highlight Helper should automatically activate highlights and hyperlinks when they’re tapped. If set to false, you’ll need to listen for the `hh:tap` event and call `activateHighlight()` or `activateHyperlink()` manually when needed. Boolean. Default: `true`.
+- **longPressTimeout** – Duration in milliseconds before a tap turns into a long-press. On long-press, Highlight Helper will send an `hh:tap` event with `isLongPress: true`. If this option is set to 0, Highlight Helper will treat long-presses the same as regular taps, sending the `hh:tap` event after the user lifts their finger. If you have access to system APIs (such as in a mobile app), you may be able to get the system long-press duration to use for this value (which may vary based on accessibility settings). For example, Android has a [getLongPressTimeout()](https://developer.android.com/reference/kotlin/android/view/ViewConfiguration#getlongpresstimeout) method and iOS has a [minimumPressDuration](https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer/minimumpressduration) property. Default: `500`.
+- **pointerMode** – Mode for responding to pointer events. Options are `simple` (create highlights by selecting text, then tapping a color or style); `live` (create highlights immediately when selecting text, without needing to tap a button); and `auto` (`simple` for touch and mouse input, but `live` when a stylus or Apple Pencil is detected). Default: `auto`.
+- **drawingMode** – Mode for drawing highlights on the page. Options are `svg` (SVG shapes), `highlight-api` (Custom Highlight API), and `mark-elements` (inserted HTML mark elements). For faster performance, read-only highlights will always be drawn as mark elements, even if a different drawing mode is set. Default: `svg`.
+- **defaultColor** – Key of the default highlight color. Default: `yellow`.
+- **defaultStyle** – Key of the default highlight style. Default: `fill`.
+- **defaultWrapper** – Key of the default highlight wrapper. Default: `none`.
+- **highlightIdFunction** – Identifier of a function that provides unique IDs for new highlights. Default: `hhGetNewHighlightId`.
+
+
+### <a name="custom-events"></a>Custom events
+
+Highlight Helper sends [custom events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events) to the container element (defined in the `containerSelector` option) that can be listened for and responded to:
+
+- **hh:highlightsload** – Sent when an array of highlights loads. Includes the number of highlights added, removed, or updated, the total number of loaded highlights, and the time they took to load (in milliseconds).
+- **hh:highlightcreate** – Sent when a new highlight is created. Includes information about the highlight.
+- **hh:highlightupdate** – Sent when the highlight changes. Includes information about the highlight, and a list of the attributes that changed.
+- **hh:highlightremove** – Sent when a highlight is removed. Includes the ID of the removed highlight.
+- **hh:tap** – Sent when a user taps in the annotatable container (potentially trying to activate a highlight or link). This will only be sent if there isn’t currently an active highlight. Includes the location of the tap, the highlight(s) that were tapped, and the hyperlink(s) that were tapped, if any.
+- **hh:selectionupdate** – Sent when the selection color or style changes. Can be used to update custom selection UI, such as the color of selection handles. Includes the key of the color and style.
+- **hh:highlightactivate** – Sent when a highlight is activated. Includes information about the activated highlight.
+- **hh:highlightdeactivate** – Sent when a highlight is deactivated. Includes the ID of the deactivated highlight.
+- **hh:ambiguousaction** – Sent when a user taps on overlapping highlights or an overlapping highlight and link. Includes the location of the tap, the highlight(s) that were tapped, and the hyperlink(s) that were tapped. This event will not be sent if `autoTapToActivate` is set to `false`.
+- **selectionchange** – This is a [standard JavaScript event](https://developer.mozilla.org/en-US/docs/Web/API/Document/selectionchange_event) (not specific to Highlight Helper), but it’s worth mentioning here because it can be useful for adding custom selection UI around the selected text (such as a floating annotation menu). When this sends, you can call `window.getSelection()` to get the current [Selection object](https://developer.mozilla.org/en-US/docs/Web/API/Selection).
+
+
+## <a name="highlight-attributes"></a>Highlight attributes
+
+These are the attributes that Highlight Helper stores for each highlight. You can update a highlight by calling `createOrUpdateHighlight(attributes)`, where `attributes` is an object that includes the keys to be updated.
+
+- **highlightId** (read-only after creation) – The ID of the highlight.
+- **color** – The color of the highlight (key from the `colors` object in the initialized options). Example: `red`.
+- **style** – The style of the highlight (key from the `styles` object in the initialized options). Example: `single-underline`.
+- **wrapper** – The wrapper of the highlight (key from the `wrappers` object in the initialized options). More information about wrappers can be found above. Example: `none`.
+- **wrapperVariables** – Variables used in wrappers. Example: `{ marker: 'a', }`.
+- **readOnly** – Whether the highlight should be read-only (prevents a user from changing its color, bounds, or other attributes). Boolean. Example: `true`.
+- **startParagraphId** – ID of the paragraph where the highlight starts. Example: `p1`.
+- **startParagraphOffset** – Character offset where the highlight starts, relative to the beginning of the paragraph. Example: 12.
+- **endParagraphId** – ID of the paragraph where the highlight ends. Example: `p1`.
+- **endParagraphOffset** – Character offset where the highlight ends, relative to the beginning of the paragraph. Example: 14.
+- **escapedHighlightId** (read-only) – Escaped highlight ID used as a CSS identifier (this is used internally by Highlight Helper).
+- **rangeText** (read-only) – Text content in the highlighted range.
+- **rangeHtml** (read-only) – HTML content in the highlighted range.
+- **rangeParagraphIds** (read-only) – IDs of paragraphs in the highlighted range.
+- **rangeObj** (read-only) – The [Range](https://developer.mozilla.org/en-US/docs/Web/API/Range) object that represents where the highlight is drawn.

package/demo.html

@@ -0,0 +1,365 @@
+<!DOCTYPE html>
+<html lang="en" translate="no">
+  <head>
+    <meta charset="utf-8">
+    <title>Text Selection Demo</title>
+    <meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0">
+    <meta name="google" content="notranslate">
+    <style>
+      :root {
+        -webkit-text-size-adjust: 100%;
+        --page-bg: hsl(0, 0%, 100%);
+        --text-color: hsl(0, 0%, 0%);
+        --gray-90: hsl(0, 0%, 90%);
+        --gray-50: hsl(0, 0%, 50%);
+      }
+      @media (prefers-color-scheme: dark) { :root {
+        --page-bg: hsl(0, 0%, 17%);
+        --text-color: hsl(0, 0%, 95%);
+        --gray-90: hsl(0, 0%, 30%);
+        --gray-50: hsl(0, 0%, 70%);
+      }}
+      
+      body {
+        background-color: var(--page-bg);
+        color: var(--text-color);
+        line-height: 1.4;
+      }
+      img { width: 120px; height: 120px; float: right; }
+      a { color: var(--gray-50); }
+      button {
+        cursor: pointer;
+        user-select: none;
+      }
+      
+      #annotation-menu {
+        font-family: "Helvetica", sans-serif;
+        font-size: 0.8em;
+        .buttons-area {
+          display: grid;
+          grid-template-columns: 1fr 1fr 1fr 1fr 1fr;
+          gap: 0.6em;
+          overflow: scroll;
+          & > * {
+            background-color: var(--page-bg);
+            border: 0; border-radius: 0.4em;
+            padding: 0.6em 0.4em;
+            font-size: inherit;
+            white-space: nowrap;
+          }
+          input[type="text"] { width: 2em; padding: 0.1em 0.3em; border: 1px solid var(--gray-50); }
+          button[name="hh-color"] { color: var(--page-bg); }
+          button[name="hh-color"][value="red"] { background-color: hsl(352, 99%, 65%); }
+          button[name="hh-color"][value="orange"] { background-color: hsl(31, 99%, 58%); }
+          button[name="hh-color"][value="yellow"] { background-color: hsl(50, 98%, 61%); }
+          button[name="hh-color"][value="green"] { background-color: hsl(75, 70%, 49%); }
+          button[name="hh-color"][value="blue"] { background-color: hsl(182, 86%, 47%); }
+          button[name="hh-style"], button[name="hh-wrapper"] { color: inherit; border: 2px solid var(--gray-50); }
+          button[name="hh-remove"] { background-color: var(--gray-50); color: var(--page-bg); }
+          .highlight-placeholder {
+            background-color: var(--gray-90);
+            padding: 0 0.3em;
+          }
+        }
+      }
+      .footnote-marker {
+        display: inline-block;
+        vertical-align: super;
+        font-size: smaller;
+        line-height: 0.5em;
+        &::before {
+          content: attr(data-marker) / attr(data-accessibility-label);
+        }
+      }
+      
+      #disambiguation-panel {
+        color: inherit;
+        background-color: inherit;
+        width: 400px; max-width: 100%;
+        flex-direction: column;
+        gap: 0.5em;
+        box-sizing: border-box;
+        &[open] { display: flex; }
+        #disambiguation-buttons {
+          display: flex;
+          flex-direction: column;
+          & button {
+            display: inline-block;
+            border: none;
+            background-color: inherit;
+            color: inherit;
+            font-family: inherit;
+            font-size: inherit;
+            text-align: inherit;
+            margin-bottom: 1em;
+            & * {
+              display: inline;
+            }
+          }
+        }
+        &::backdrop {
+          background-color: hsla(0, 0%, 0%, 0.5);
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1 id="title1">Highlight Helper Demo</h1>
+      <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/4/41/CMYK_color_model.svg/180px-CMYK_color_model.svg.png">
+      <p id="p1"><b>Highlight Helper</b> enables highlighting or underlining text in an HTML page. Highlights are drawn via <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/SVG">SVG shapes</a>, the <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API">Custom Highlight API</a>, or <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/mark">HTML mark elements</a>. Highlights can be drawn across multiple paragraphs or <b>inline <i>style</i></b> elements—they can even overlap!</p>
+      <p id="p2">Select text, then choose a color and style. Tap away when you’re done. Tap to activate it again for editing. Secondary elements like images (right) and Japanese ruby/furigana (below) are highlighted around.</p>
+      <p id="p3">わたしニーファイは<ruby><rb>善</rb><rt>よ</rt></ruby>い<ruby><rb>両</rb><rt>りょう</rt></ruby><ruby><rb>親</rb><rt>しん</rt></ruby>から<ruby><rb>生</rb><rt>う</rt></ruby>まれたので，<ruby><rb>父</rb><rt>ちち</rt></ruby>が<ruby><rb>学</rb><rt>まな</rt></ruby>んだすべてのことの<ruby><rb>中</rb><rt>なか</rt></ruby>から<ruby><rb>幾</rb><rt>いく</rt></ruby>らかの<ruby><rb>教</rb><rt>おし</rt></ruby>えを<ruby><rb>受</rb><rt>う</rt></ruby>けた。</p>
+      <p id="p4" style="direction: rtl;">فِي الْبَدْءِ خَلَقَ اللهُ السَّمَاوَاتِ وَالأَرْضَ. وَكَانَتِ الأَرْضُ خَرِبَةً وَخَالِيَةً، وَعَلَى وَجْهِ الْغَمْرِ ظُلْمَةٌ، وَرُوحُ اللهِ يَرِفُّ عَلَى وَجْهِ الْمِيَاهِ. وَقَالَ اللهُ: «لِيَكُنْ نُورٌ»، فَكَانَ نُورٌ.</p>
+    </main>
+    
+    <hr>
+    <aside id="annotation-menu">
+      <div class="buttons-area">
+        <button name="hh-color" value="red">Red</button>
+        <button name="hh-color" value="orange">Orange</button>
+        <button name="hh-color" value="yellow">Yellow</button>
+        <button name="hh-color" value="green">Green</button>
+        <button name="hh-color" value="blue">Blue</button>
+        <button name="hh-style" value="fill" checked> Fill</button>
+        <button name="hh-style" value="single-underline"> Underline</button>
+        <button name="hh-style" value="double-underline"> Double underline</button>
+        <button name="hh-style" value="colored-text"> Colored text</button>
+        <button name="hh-style" value="redacted"> Redacted</button>
+        <button name="hh-remove">Remove</button>
+        <div></div>
+        <!--button name="hh-wrapper" value="none" title="No wrapper"><span class="highlight-placeholder">…</span></button>
+        <button name="hh-wrapper" value="footnote" title="Footnote"><span class="footnote-marker" data-marker="a" data-accessibility-label="Footnote"></span><span class="highlight-placeholder">…</span></button-->
+      </div>
+      <p>
+        <label><input type="checkbox" id="hh-remember-style" checked> Remember most recent color and style</label><br>
+        <label><input type="checkbox" id="hh-snap-to-word"> Snap highlights to the nearest word</label><br>
+      </p>
+      <p>
+        Pointer mode:<br>
+        <label><input type="radio" name="hh-pointer-mode" value="auto" checked> Auto (based on input device)</label><br>
+        <label><input type="radio" name="hh-pointer-mode" value="simple"> Simple</label><br>
+        <label><input type="radio" name="hh-pointer-mode" value="live"> Live</label><br>
+      </p>
+      <p>
+        Drawing mode:<br>
+        <label><input type="radio" name="hh-drawing-mode" value="svg" checked> SVG shapes</label><br>
+        <label><input type="radio" name="hh-drawing-mode" value="highlight-api"> Custom Highlight API</label><br>
+        <label><input type="radio" name="hh-drawing-mode" value="mark-elements"> HTML mark elements</label><br>
+      </p>
+      <b>Active highlight:</b>
+      <div id="snippet-container">
+        <div id="snippet">N/A</div>
+      </div>
+      <p id="highlight-info"></p>
+    </aside>
+    <dialog id="disambiguation-panel">
+      <h1>Select One</h1>
+      <div id="disambiguation-buttons"></div>
+      <button id="disambiguation-cancel">Cancel</button>
+    </dialog>
+    
+    <!-- Link to the Highlight Helper JavaScript file -->
+    <script src="highlight-helper.js"></script>
+    <script>
+      // Example highlights
+      let highlights = [
+        {
+          highlightId: 'hh-1729991847207',
+          color: 'green', style: 'fill',
+          startParagraphId: 'p1', startParagraphOffset: 25,
+          endParagraphId: 'p1', endParagraphOffset: 57,
+        },
+        {
+          highlightId: 'hh-1729991847300',
+          color: 'blue', style: 'fill',
+          startParagraphId: 'p2', startParagraphOffset: 27,
+          endParagraphId: 'p2', endParagraphOffset: 42,
+        },
+        {
+          highlightId: 'hh-1729991847468',
+          color: 'red', style: 'colored-text', wrapper: 'footnote',
+          wrapperVariables: { marker: 'a', accessibilityLabel: 'Footnote 1a', },
+          readOnly: true,
+          startParagraphId: 'p2', startParagraphOffset: 119,
+          endParagraphId: 'p2', endParagraphOffset: 127,
+        },
+        {
+          highlightId: 'hh-1729991847301',
+          color: 'orange', style: 'fill',
+          startParagraphId: 'p3', startParagraphOffset: 56,
+          endParagraphId: 'p3', endParagraphOffset: 65,
+        },
+        {
+          highlightId: 'hh-1735379727958',
+          color: 'yellow', style: 'fill',
+          startParagraphId: 'p1', startParagraphOffset: 246,
+          endParagraphId: 'p1', endParagraphOffset: 259,
+        },
+        {
+          highlightId: 'hh-1735379721523',
+          color: 'red', style: 'fill',
+          startParagraphId: 'p1', startParagraphOffset: 237,
+          endParagraphId: 'p1', endParagraphOffset: 250,
+        },
+        {
+          highlightId: 'hh-1735479727958',
+          color: 'yellow', style: 'fill',
+          startParagraphId: 'p4', startParagraphOffset: 191,
+          endParagraphId: 'p4', endParagraphOffset: 207,
+        },
+      ];
+      
+      // Initialize a Highlighter instance, then load highlights
+      const highlighter = new Highlighter({
+        containerSelector: 'main',
+        paragraphSelector: 'main [id]',
+        wrappers: {
+          'footnote': { start: '<span class="footnote-marker" data-marker="{marker}" data-accessibility-label="{accessibilityLabel}"></span>', end: '', },
+        },
+      });
+      highlighter.loadHighlights(highlights);
+      
+      // Call Highlight Helper methods when color, style, wrapper, or remove buttons on this demo page are tapped
+      const colorButtons = document.getElementsByName('hh-color');
+      for (const colorButton of colorButtons) {
+        colorButton.addEventListener('click', () => { highlighter.createOrUpdateHighlight({ color: colorButton.value }); });
+      }
+      const styleButtons = document.getElementsByName('hh-style');
+      for (const styleButton of styleButtons) {
+        styleButton.addEventListener('click', () => { highlighter.createOrUpdateHighlight({ style: styleButton.value }); });
+      }
+      const wrapperButtons = document.getElementsByName('hh-wrapper');
+      for (const wrapperButton of wrapperButtons) {
+        wrapperButton.addEventListener('click', () => { highlighter.createOrUpdateHighlight({ wrapper: wrapperButton.value }); });
+      }
+      const removeButton = document.getElementsByName('hh-remove')[0];
+      removeButton.addEventListener('click', () => { highlighter.removeHighlights([highlighter.getActiveHighlightId()]); });
+      document.addEventListener('keydown', respondToKeyPress);
+      function respondToKeyPress(event) {
+        if (event.key === 'Backspace') highlighter.removeHighlights([highlighter.getActiveHighlightId()]);
+      }
+      
+      // Call Highlight Helper methods when options are changed
+      const rememberStyleCheckbox = document.getElementById('hh-remember-style');
+      const snapToWordCheckbox = document.getElementById('hh-snap-to-word');
+      const pointerModeRadioButtons = document.getElementsByName('hh-pointer-mode');
+      const drawingModeRadioButtons = document.getElementsByName('hh-drawing-mode');
+      rememberStyleCheckbox.addEventListener('change', (event) => { highlighter.setOption('rememberStyle', event.currentTarget.checked); });
+      snapToWordCheckbox.addEventListener('change', (event) => { highlighter.setOption('snapToWord', event.currentTarget.checked); });
+      for (const pointerModeRadioButton of pointerModeRadioButtons) {
+        pointerModeRadioButton.addEventListener('change', (event) => {
+          let pointerMode = document.querySelector('[name="hh-pointer-mode"]:checked').value;
+          highlighter.setOption('pointerMode', pointerMode);
+        });
+      }
+      for (const drawingModeRadioButton of drawingModeRadioButtons) {
+        drawingModeRadioButton.addEventListener('change', (event) => {
+          let drawingMode = document.querySelector('[name="hh-drawing-mode"]:checked').value;
+          if (drawingMode === 'highlight-api' && !CSS.highlights) {
+            alert('Your browser doesn’t support the Custom Highlight API.');
+          } else {
+            highlighter.setOption('drawingMode', drawingMode);
+          }
+        });
+      }
+      
+      const container = document.querySelector(highlighter.getOptions().containerSelector);
+      const snippetDiv = document.getElementById('snippet');
+      const infoDiv = document.getElementById('highlight-info');
+      
+      // Respond to highlight update and highlight activate event
+      container.addEventListener('hh:highlightupdate', updateHighlightInfo);
+      container.addEventListener('hh:highlightactivate', updateHighlightInfo);
+      function updateHighlightInfo(event) {
+        clearHighlightInfo();
+        infoDiv.innerHTML = `
+          <b>Highlight:</b> ${event.detail.highlight.highlightId}<br>
+          <b>Color and style:</b> ${event.detail.highlight.color}, ${event.detail.highlight.style}<br>
+          <b>Wrapper:</b> ${event.detail.highlight.wrapper}, ${JSON.stringify(event.detail.highlight.wrapperVariables)}<br>
+          <b>Read-only:</b> ${event.detail.highlight.readOnly}<br>
+          <b>Start:</b> #${event.detail.highlight.startParagraphId}, offset ${event.detail.highlight.startParagraphOffset}<br>
+          <b>End:</b> #${event.detail.highlight.endParagraphId}, offset ${event.detail.highlight.endParagraphOffset}
+        `;
+        const annotatedParagraphs = container.querySelectorAll(`#${event.detail.highlight.rangeParagraphIds.join(', #')}`);
+        for (const annotatedParagraph of annotatedParagraphs) {
+          const snippetParagraph = annotatedParagraph.cloneNode(true);
+          snippetParagraph.id = `${snippetParagraph.id}_${event.detail.highlight.highlightId}`;
+          snippetDiv.append(snippetParagraph);
+        }
+        const snippetHighlights = [
+          {
+            highlightId: event.detail.highlight.highlightId + '_snippet',
+            readOnly: true,
+            color: event.detail.highlight.color, style: event.detail.highlight.style,
+            startParagraphId: `${event.detail.highlight.startParagraphId}_${event.detail.highlight.highlightId}`, startParagraphOffset: event.detail.highlight.startParagraphOffset,
+            endParagraphId: `${event.detail.highlight.endParagraphId}_${event.detail.highlight.highlightId}`, endParagraphOffset: event.detail.highlight.endParagraphOffset,
+          },
+        ];
+        const snippetHighlighter = new Highlighter({
+          containerSelector: '#snippet-container',
+          paragraphSelector: '#snippet [id]',
+        });
+        snippetHighlighter.loadHighlights(snippetHighlights);
+      }
+      
+      // Respond to highlight deactivate event
+      container.addEventListener('hh:highlightdeactivate', clearHighlightInfo);
+      function clearHighlightInfo(event) {
+        snippetDiv.innerHTML = '';
+        infoDiv.innerHTML = 'N/A';
+      }
+      
+      // Respond to ambiguous action events (when a user taps on overlapping highlights, or an overlapping link and highlight)
+      const disambiguationPanel = document.getElementById('disambiguation-panel');
+      const disambiguationButtonsDiv = document.getElementById('disambiguation-buttons');
+      const disambiguationCancelButton = document.getElementById('disambiguation-cancel');
+      disambiguationCancelButton.addEventListener('click', (event) => disambiguationPanel.close());
+      container.addEventListener('hh:ambiguousaction', handleAmbiguousAction);
+      function handleAmbiguousAction(event) {
+        disambiguationButtonsDiv.innerHTML = '';
+        for (const highlight of event.detail.highlights) {
+          let buttonStyle = highlighter.getOptions().styles[highlight.style]['css']
+          let buttonHtml = `
+            <button data-color="${highlight.color}" onclick="disambiguationPanel.close();highlighter.activateHighlight('${highlight.highlightId}');">
+              <span style="${buttonStyle}">${highlight.rangeHtml}</span>
+            </button>
+          `;
+          disambiguationButtonsDiv.insertAdjacentHTML('beforeend', buttonHtml);
+        }
+        for (const hyperlink of event.detail.hyperlinks) {
+          let buttonStyle = 'color: var(--gray-50); text-decoration: underline;'
+          let buttonHtml = `
+            <button onclick="disambiguationPanel.close();highlighter.activateHyperlink(${hyperlink.position});">
+              <span style="${buttonStyle}">${hyperlink.text}</span>
+            </button>
+          `;
+          disambiguationButtonsDiv.insertAdjacentHTML('beforeend', buttonHtml);
+        }
+        // TODO: Waiting 10 milliseconds before showing the disambiguation panel is a workaround for an issue in Android Chrome where a click event fires right after the pointerup event that triggered hh:ambiguousaction. If the click event happens to be at the same position as a button in the panel, the button will receive the click, dismissing the panel before the user sees it.
+        setTimeout(function() { disambiguationPanel.showModal(); }, 10);
+      }
+      
+      // Log events for debugging
+      container.addEventListener('hh:highlightcreate', console.info)
+      container.addEventListener('hh:highlightupdate', console.info)
+      container.addEventListener('hh:highlightremove', console.info)
+      container.addEventListener('hh:highlightsload', console.info)
+      container.addEventListener('hh:highlightactivate', console.info)
+      container.addEventListener('hh:highlightdeactivate', console.info)
+      container.addEventListener('hh:selectionupdate', console.info)
+      container.addEventListener('hh:ambiguousaction', console.info)
+      container.addEventListener('hh:tap', console.info)
+      
+//       snippetDiv.addEventListener('hh:highlightcreate', console.warn)
+//       snippetDiv.addEventListener('hh:highlightupdate', console.warn)
+//       snippetDiv.addEventListener('hh:highlightremove', console.warn)
+//       snippetDiv.addEventListener('hh:highlightsload', console.warn)
+//       snippetDiv.addEventListener('hh:highlightactivate', console.warn)
+//       snippetDiv.addEventListener('hh:highlightdeactivate', console.warn)
+//       snippetDiv.addEventListener('hh:selectionupdate', console.warn)
+//       snippetDiv.addEventListener('hh:ambiguousaction', console.warn)
+//       snippetDiv.addEventListener('hh:tap', console.warn)
+    </script>
+  </body>
+</html>