Hi, I'm Ishaan. I make Elsewhere, a reader that reads a book aloud and underlines each word as it is spoken. This post is about one decision the whole read-along rests on: the book's own markup is never changed to show where the voice is.

The obvious way, and why I dropped it

The obvious idea is to wrap each word in a span and swap a class on the current one. For a novel that is thousands of extra elements, and the book's own HTML is no longer the book's own HTML. A span can change line breaks, break a footnote link, or interfere with how the publisher styled a paragraph. And the word changes several times a second, so every change means touching the tree and hoping the layout holds still.

I wanted the text to stay exactly where the author's markup put it, so a line never jumps because a word got underlined.

Highlights that live outside the DOM

The CSS Custom Highlight API lets you register a Range and style it from CSS, with no element wrapped around it. You make a Highlight, put it in CSS.highlights under a name, and style that name with ::highlight().

The spoken word is one name, and the stylesheet gives it an underline:

::highlight(narration-word) { text-decoration-line: underline; text-decoration-thickness: 2px; text-underline-offset: 0.22em; } 

I use an underline in the accent colour, so it still reads for someone who cannot tell the colours apart. And there is no transition. It moves with the voice instead of easing after it.

Painting is a few lines, trimmed here from what I run:

const highlight = new Highlight(range) highlight.priority = WORD_PRIORITY CSS.highlights.set('narration-word', highlight) 

The same mechanism paints the sentence being read, the dimmer text around it, and the colours a reader picks when they mark a passage. None of them add a node to the page.

Finding the Range for a word

Each narrated passage comes with a start and end character for every word. A frame loop asks the audio element for its current time, looks up the word with a binary search, and turns that word's character offsets into a Range over the text nodes on screen.

Two details cost me an afternoon each.

One, the audible start of a word comes a little before the time stored for it. I measured about 40 ms on average, so the lookup adds 60 ms of lead and the underline lands on the word you are hearing.

Two, the Range is attached to text nodes, and the framework that renders the page will sometimes rewrite those nodes when the sentence highlight moves on. A Range can then collapse or slide onto other characters. So on each frame I compare the Range's text with the text it was painted over, and paint it again if they differ.

A priority bug I did not expect

The spoken word sits inside the sentence being narrated, and both are highlights. In Safari, the highest-priority highlight over a stretch of text decides its decoration outright. At the default priority the word's underline lost to the sentence's and never showed. Giving the word the top priority fixed it.

Pausing and tabs

The loop runs while audio plays and the tab is visible, and it cancels its frame on every way out. Paused, the word is painted once, and again after each seek, so it is never stale. Where a browser lacks the API, nothing is painted and the book still reads.

Try it

You can watch the underline move without making an account at https://listenelsewhere.com/try

Plainly, so nobody wastes an evening: Elsewhere opens DRM-free files, so Kindle store books will not open. The voice is a neural voice, not a human narrator. The tab has to stay open while narration is being made, and the app needs a connection (an exported audiobook plays offline).

I would like to hear from you. If you have used the Custom Highlight API, did you hit the priority quirk too, or find another way to keep a moving mark out of the DOM?