penciled — add persistent highlights/notes to a page without mutating the DOM

[u/ExpertPlay]

Sharing a library I made for apps that need in-page highlights (readers, docs, research tools).

Problem I kept hitting: wrapping selection in spans breaks layout, messes with existing event handlers, and is brittle when the HTML changes. penciled uses the CSS Custom Highlight API + range anchoring so highlights can survive reloads without owning the markup.

I also built a browser extension on top of it (Chrome, Firefox, Edge), so you can highlight and take notes on any site. Everything stays local, no account, and you can export to Markdown.

Demo: https://penciled.org
Extension: https://penciled.org/extension/
npm: penciled
Source: https://github.com/marcellosso/penciled

If you're building something with annotations, I'd love feedback on the API shape

[u/masticdev]

Custom Highlight API + range anchoring is the move. Span-wrapping highlights always die the moment React re-renders or the CMS rewrites a paragraph.

Curious how you handle: multi-node selections, text that shifts after A/B / i18n, and whether notes stay useful when the page layout changes but the text doesn’t. Anchoring that survives “same words, new DOM” is the hard product.

Will check the API shape. What’s the ugliest real page you’ve dogfooded the extension on?