@samuelbradshaw/highlight-helper-js 0.8.1 → 0.10.0

package/.github/workflows/publish.yml

@@ -17,18 +17,18 @@ jobs:
       - name: Update package.json
         run: npm version "${{ steps.get_version.outputs.RELEASE_VERSION }}" --no-git-tag-version
       - name: Commit package.json changes
-        uses: stefanzweifel/git-auto-commit-action@v6
+        uses: stefanzweifel/git-auto-commit-action@v7
         with:
           commit_message: "Update package.json version to ${{ steps.get_version.outputs.RELEASE_VERSION }}"
           branch: main
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: '20.x'
+          node-version: '24.x'
           registry-url: 'https://registry.npmjs.org'
       - name: Install dependencies
         run: npm ci
+      - name: Build
+        run: npm run build --if-present
       - name: Push to npmjs
         run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,16 +1,16 @@
-# Highlight Helper
+# HighlightHelper.js
 
-**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.
+**HighlightHelper.js** 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:
+Behind the scenes, HighlightHelper.js 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**.
+An HTML demo page that shows basic functionality can be found here: [HighlightHelper.js Demo](https://samuelbradshaw.github.io/highlight-helper-js/demo.html). Source code for the demo is in **demo.html**. HighlightHelper.js 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.
+*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 HighlightHelper.js.
 
 ### Documentation:
 - [Known issues](#known-issues)
@@ -28,7 +28,7 @@ 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** 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 HighlightHelper.js 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.
 
 
@@ -40,67 +40,82 @@ In the source of demo.html, you’ll see CSS styles, followed by the HTML body,
 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.
+3. Sets up logic to call HighlightHelper.js methods when buttons on the demo page are tapped, and
+4. Sets up listeners to respond to custom event messages that come back from HighlightHelper.js.
 
 
 ### <a name="installation-options"></a>Installation options
 
-You can download highlight-helper.js from GitHub and reference it from your HTML file:
+HighlightHelper.js is available as classic JavaScript (highlight-helper.js) or as a [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) (highlight-helper.mjs).
+
+#### Classic JavaScript
+
+Download highlight-helper.js from GitHub and reference it locally in your HTML file:
 ```html
 <script src="scripts/highlight-helper.js"></script>
 ```
 
-Or you can load it from [jsDelivr](https://www.jsdelivr.com/package/gh/samuelbradshaw/highlight-helper-js):
+Or load it from [jsDelivr](https://www.jsdelivr.com/package/gh/samuelbradshaw/highlight-helper-js) CDN:
 ```html
 <script src="https://cdn.jsdelivr.net/gh/samuelbradshaw/highlight-helper-js@main/highlight-helper.min.js"></script>
 ```
 
-Or you can install it using [npm](https://www.npmjs.com/package/@samuelbradshaw/highlight-helper-js):
+#### JavaScript Module
+
+Download highlight-helper.js and highlight-helper.mjs from GitHub and import as a JavaScript module:
+```javascript
+import { Highlighter } from './highlight-helper.mjs';
+```
+
+Or load it from [jsDelivr](https://www.jsdelivr.com/package/gh/samuelbradshaw/highlight-helper-js) CDN:
+```javascript
+import { Highlighter } from 'https://cdn.jsdelivr.net/gh/samuelbradshaw/highlight-helper-js@main/highlight-helper.min.mjs';
+```
+
+You can also install it using [npm](https://www.npmjs.com/package/@samuelbradshaw/highlight-helper-js):
 ```bash
 % cd /your/project/folder
 % npm i @samuelbradshaw/highlight-helper-js
 ```
 
-
 ## <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.
+- **loadHighlights(highlights)** – Load an array of existing highlights into HighlightHelper.js. 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).
+- **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 (HighlightHelper.js 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.
+- **setOptions(optionsToUpdate)** – Change one or more options. `optionsToUpdate` is an object with one or more of the option keys 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.
+Options can be provided when HighlightHelper.js is initialized. They can be updated after initialization using `setOptions()`.
 
 - **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.
+- **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). `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`.
+- **autoTapToActivate** – Whether HighlightHelper.js 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, HighlightHelper.js will send an `hh:tap` event with `isLongPress: true`. If this option is set to 0, HighlightHelper.js 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`.
+- **highlightIdFunction** – Identifier of a function that provides unique IDs for new highlights. Default: `_getNewHighlightId`.
 - **showCustomSelectionHandlesForActiveHighlights** – Whether custom selection handles should show for active highlights. Default: `true`.
 - **showCustomSelectionHandlesForTextSelection** – Whether custom selection handles should show for text selection. Default: `false`.
 - **showCustomSelectionHandlesOnTouch** – Whether custom selection handles should show on touch devices. Default: `false`.
@@ -108,23 +123,23 @@ Options can be provided when Highlight Helper is initialized. They can also be s
 
 ### <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:
+HighlightHelper.js 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:tap** – Sent when a user taps in the annotatable container (potentially trying to tap a highlight, wrapper, or link). This will only be sent if there isn’t currently an active highlight. Includes the location of the tap, and the highlight, wrapper, or hyperlink that was 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).
+- **hh:ambiguousaction** – Sent when a user taps on overlapping highlights, wrappers, and/or links. Includes the location of the tap, and the highlight(s), wrapper(s), and 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 HighlightHelper.js), 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.
+These are the attributes that HighlightHelper.js 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`.
@@ -133,11 +148,13 @@ These are the attributes that Highlight Helper stores for each highlight. You ca
 - **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.
+- **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).
+- **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 HighlightHelper.js).
 - **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.
+
+*If you have dynamic elements that need to be inserted into an annotatable paragraph temporarily, you can mark them with the `data-hh-ignore` attribute. HighlightHelper.js will skip over elements with this attribute when calculating character offsets and drawing highlights.

package/demo.html

@@ -2,7 +2,7 @@
 <html lang="en" translate="no">
   <head>
     <meta charset="utf-8">
-    <title>Text Selection Demo</title>
+    <title>HighlightHelper.js Demo</title>
     <meta name="viewport" content="width=device-width, user-scalable=yes, initial-scale=1.0">
     <meta name="google" content="notranslate">
     <style>
@@ -19,19 +19,19 @@
         --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; }
+      main { margin-right: 2em; }
       a { color: var(--gray-50); }
       button {
         cursor: pointer;
         user-select: none;
       }
-      
+
       #annotation-menu {
         font-family: "Helvetica", sans-serif;
         font-size: 0.8em;
@@ -54,7 +54,10 @@
           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-style"], button[name="hh-wrapper"] {
+            position: relative;
+            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);
@@ -68,10 +71,25 @@
         font-size: smaller;
         line-height: 0.5em;
         &::before {
-          content: attr(data-marker) / attr(data-accessibility-label);
+          content: attr(data-content) / attr(data-accessibility-label);
+        }
+      }
+      .note-container {
+        display: inline-block;
+        visibility: visible;
+        font-style: normal;
+        height: 1em;
+      }
+      .note {
+        position: absolute;
+        right: 0.5rem;
+        font-size: 1.2rem;
+        margin-top: -0.2rem;
+        &::before {
+          content: attr(data-content) / attr(data-accessibility-label);
         }
       }
-      
+
       #disambiguation-panel {
         color: inherit;
         background-color: inherit;
@@ -105,14 +123,13 @@
   </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>
+      <h1 id="title1">HighlightHelper.js Demo</h1>
+      <p id="p1"><b>HighlightHelper.js</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">
@@ -127,9 +144,10 @@
         <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-->
+        <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-content="a" data-accessibility-label="Footnote [a]"></span><span class="highlight-placeholder">…</span></button>
+        <button name="hh-wrapper" value="margin-note" title="Margin note"><span class="note-container"><span class="note" data-content="🙂" data-accessibility-label="Smile emoji"></span></span><span class="highlight-placeholder">…</span></button>
+        <button name="hh-wrapper" value="margin-note" title="Margin note"><span class="note-container"><span class="note" data-content="✅" data-accessibility-label="Checkmark emoji"></span></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>
@@ -164,8 +182,11 @@
       <div id="disambiguation-buttons"></div>
       <button id="disambiguation-cancel">Cancel</button>
     </dialog>
-    
-    <!-- Link to the Highlight Helper JavaScript file -->
+    <p>
+      ← <a href="https://github.com/samuelbradshaw/highlight-helper-js">Back to GitHub</a>
+    </p>
+
+    <!-- Link to the HighlightHelper.js JavaScript file -->
     <script src="highlight-helper.js"></script>
     <script>
       // Example highlights
@@ -173,20 +194,20 @@
         {
           highlightId: 'hh-1729991847207',
           color: 'green', style: 'fill',
-          startParagraphId: 'p1', startParagraphOffset: 25,
-          endParagraphId: 'p1', endParagraphOffset: 57,
+          startParagraphId: 'p1', startParagraphOffset: 27,
+          endParagraphId: 'p1', endParagraphOffset: 59,
         },
         {
           highlightId: 'hh-1729991847300',
-          color: 'blue', style: 'fill',
+          color: 'blue', style: 'fill', wrapper: 'margin-note',
+          wrapperVariables: { content: '🙂', accessibilityLabel: 'Smile emoji', },
           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,
+          color: 'red', style: 'single-underline', wrapper: 'footnote',
+          wrapperVariables: { content: 'a', accessibilityLabel: 'Footnote [a]', },
           startParagraphId: 'p2', startParagraphOffset: 119,
           endParagraphId: 'p2', endParagraphOffset: 127,
         },
@@ -199,14 +220,14 @@
         {
           highlightId: 'hh-1735379727958',
           color: 'yellow', style: 'fill',
-          startParagraphId: 'p1', startParagraphOffset: 246,
-          endParagraphId: 'p1', endParagraphOffset: 259,
+          startParagraphId: 'p1', startParagraphOffset: 248,
+          endParagraphId: 'p1', endParagraphOffset: 261,
         },
         {
           highlightId: 'hh-1735379721523',
           color: 'red', style: 'fill',
-          startParagraphId: 'p1', startParagraphOffset: 237,
-          endParagraphId: 'p1', endParagraphOffset: 250,
+          startParagraphId: 'p1', startParagraphOffset: 239,
+          endParagraphId: 'p1', endParagraphOffset: 252,
         },
         {
           highlightId: 'hh-1735479727958',
@@ -215,18 +236,19 @@
           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: '', },
+          'footnote': { start: '<span class="footnote-marker" data-content="{content}" data-accessibility-label="{accessibilityLabel}"></span>', end: '', },
+          'margin-note': { start: '<span class="note-container"><span class="note" data-content="{content}" data-accessibility-label="{accessibilityLabel}"></span></span>', end: '', },
         },
       });
       highlighter.loadHighlights(highlights);
-      
-      // Call Highlight Helper methods when color, style, wrapper, or remove buttons on this demo page are tapped
+
+      // Call HighlightHelper.js 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 }); });
@@ -237,7 +259,13 @@
       }
       const wrapperButtons = document.getElementsByName('hh-wrapper');
       for (const wrapperButton of wrapperButtons) {
-        wrapperButton.addEventListener('click', () => { highlighter.createOrUpdateHighlight({ wrapper: wrapperButton.value }); });
+        const contentSpan = wrapperButton.querySelector('[data-content]');
+        wrapperButton.addEventListener('click', () => {
+          highlighter.createOrUpdateHighlight({
+            wrapper: wrapperButton.value === 'none' ? null : wrapperButton.value,
+            wrapperVariables: { content: contentSpan?.dataset?.content ?? '', accessibilityLabel: contentSpan?.dataset?.accessibilityLabel ?? '', },
+          });
+        });
       }
       const removeButton = document.getElementsByName('hh-remove')[0];
       removeButton.addEventListener('click', () => { highlighter.removeHighlights([highlighter.getActiveHighlightId()]); });
@@ -245,8 +273,8 @@
       function respondToKeyPress(event) {
         if (event.key === 'Backspace') highlighter.removeHighlights([highlighter.getActiveHighlightId()]);
       }
-      
-      // Call Highlight Helper methods when options are changed
+
+      // Call HighlightHelper.js 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');
@@ -275,11 +303,11 @@
       selectionHandlesTextSelectionCheckbox.addEventListener('change', (event) => { highlighter.setOption('showCustomSelectionHandlesForTextSelection', event.currentTarget.checked); });
       const selectionHandlesOnTouchCheckbox = document.getElementById('hh-selection-handles-touch');
       selectionHandlesOnTouchCheckbox.addEventListener('change', (event) => { highlighter.setOption('showCustomSelectionHandlesOnTouch', event.currentTarget.checked); });
-      
+
       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);
@@ -297,6 +325,9 @@
         for (const annotatedParagraph of annotatedParagraphs) {
           const snippetParagraph = annotatedParagraph.cloneNode(true);
           snippetParagraph.id = `${snippetParagraph.id}_${event.detail.highlight.highlightId}`;
+          for (const wrapperEl of snippetParagraph.querySelectorAll('[data-highlight-id]')) {
+            wrapperEl.dataset.highlightId = wrapperEl.dataset.highlightId + '_snippet';
+          }
           snippetDiv.append(snippetParagraph);
         }
         const snippetHighlights = [
@@ -314,15 +345,23 @@
         });
         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)
+
+      // Respond to tap
+      container.addEventListener('hh:tap', respondToTap);
+      function respondToTap(event) {
+        if (event.detail.wrappers.length === 1) {
+          highlighter.activateHighlight(event.detail.wrappers[0].highlightInfo.highlightId);
+        }
+      }
+
+      // Respond to ambiguous action events (when a user taps on overlapping highlights, wrappers, and/or links)
       const disambiguationPanel = document.getElementById('disambiguation-panel');
       const disambiguationButtonsDiv = document.getElementById('disambiguation-buttons');
       const disambiguationCancelButton = document.getElementById('disambiguation-cancel');
@@ -330,7 +369,11 @@
       container.addEventListener('hh:ambiguousaction', handleAmbiguousAction);
       function handleAmbiguousAction(event) {
         disambiguationButtonsDiv.innerHTML = '';
-        for (const highlight of event.detail.highlights) {
+        const highlightIds = new Set();
+        for (const highlight of event.detail.highlights) highlightIds.add(highlight.highlightId);
+        for (const wrapper of event.detail.wrappers) highlightIds.add(wrapper.highlightInfo.highlightId);
+        const highlights = highlighter.getHighlightInfo(highlightIds);
+        for (const highlight of highlights) {
           let buttonStyle = highlighter.getOptions().styles[highlight.style]['css']
           let buttonHtml = `
             <button data-color="${highlight.color}" onclick="disambiguationPanel.close();highlighter.activateHighlight('${highlight.highlightId}');">
@@ -351,7 +394,20 @@
         // 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);
       }
-      
+
+      // Update margin note position when a highlight with a start wrapper is active
+      function updateMarginNotePosition(event) {
+        const activeHighlightId = highlighter.getActiveHighlightId();
+        if (!activeHighlightId) return;
+        const note = container.querySelector(`.hh-wrapper-start[data-highlight-id="${activeHighlightId}"] .note`);
+        if (!note) return;
+        const selection = getSelection();
+        const startRect = selection.type === 'Range' ? selection.getRangeAt(0).getBoundingClientRect() : null;
+        if (startRect) note.style.top = (startRect.top + window.scrollY - 1) + 'px';
+      }
+      container.addEventListener('hh:highlightactivate', updateMarginNotePosition);
+      document.addEventListener('selectionchange', updateMarginNotePosition);
+
       // Log events for debugging
       container.addEventListener('hh:highlightcreate', console.info)
       container.addEventListener('hh:highlightupdate', console.info)
@@ -362,16 +418,6 @@
       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>