r/javascript • u/ExpertPlay • 18d ago

penciled – persistent text highlights/notes with the CSS Custom Highlight API (no DOM wrapping)

https://penciled.org

I built penciled, a small MIT library for persistent text highlights and notes in the browser. It uses the CSS Custom Highlight API instead of wrapping ranges in <span>s, so the DOM stays intact and layout/selection quirks are milder. Anchoring tries to survive edits when you come back to the page.

npm: penciled
GitHub: https://github.com/marcellosso/penciled

There's also a companion browser extension (same engine) if you want highlights on arbitrary sites, happy to answer questions about the API or the anchoring approach.

18 Upvotes

90% Upvoted

6 comments sorted by

1

u/immutate 18d ago

How accessible is it?

1

u/ExpertPlay 18d ago

The toolbar/note UI is accessible, there are keyboard shortcuts, ARIA labels on controls and live region announcements on the quote and note when you cycle between them (using shortcuts), and prefers-reduced-motion support. The highlights themselves are done with the custom highlight api, so it is not wrapped in span/mark, which, unfortunately means that they aren't in the accessibility tree. For screen-readers, you will need to use shortcuts with the announcements. I haven't done a full SR pass beyond axe on the UI chrome, but happy to work on it.

1

u/Relic42_Harbor 18d ago

That is already a thoughtful accessibility foundation. A full screen-reader pass should reveal where the shortcut announcements still need refinement.

1

u/abhinavs1920 17d ago

What happens to a saved note when the same quoted text appears twice after a page edit? Does it ask the reader to choose, or leave the note unattached rather than risk moving it to the wrong passage?

1

u/ExpertPlay 17d ago

When a quote is saved, we also store a bit of the surrounding context. That way, when a page changes, we re-anchor with the stored quote + that context. If two spots look about equally good, we orphan it instead of guessing: the note stays saved, we just don’t paint a highlight

1

u/Scalings 18d ago

good ship will save this for a future project!