Enhanced context-highlighter for persistent highlights

Summary

Closed, Completed

Understand
Explored and reviewed repository structure and key files.
Understand
Plan
Designed functions to apply and load highlights, and sync local storage.
Plan
Edit
Added highlight application and loading in content.js.
Edit
Edit
Updated background.js with local storage helpers and message handlers.
Edit
Edit
Added highlight styles in content.css.
Edit

I'd lik to update this repo: https://github.com/goldfishandswedishfish/context-highlighter -- so that the content that is highlighted on the page stays visible on the page as you're reading and is (ideally) still there when the content is re-opened.

Let me start by fetching the repository to understand its current structure and code.

Grepped

Let me explore the repository using the GitHub CLI.

Now let me explore the extension directory and other key files.

Now let me read all the key extension files.

Now I have a good understanding of the extension. Let me also read the sidebar.js and content.css to understand the full picture.

The current architecture:

content.js - runs on all pages, detects text selection, shows a floating "Save" button, and a modal to save the highlight with notes, themes, and agents.
background.js - service worker that handles communication with a local server at http://localhost:3747.
Highlights are stored on a local server (not in the extension itself).

What the user wants:

Highlights stay visible on the page as you're reading - Currently, when you save a highlight, the text isn't visually marked on the page.
Highlights persist when the page is re-opened - Currently there's no mechanism to re-apply highlights when you revisit a page.

Approach: I need to store highlights in chrome.storage.local keyed by URL so they persist across sessions, then on page load in content.js, I'll retrieve the stored highlights for that URL and re-apply the visual styling to the matching text nodes.

For the storage structure, I'll use { [url]: [{ id, text, note, theme, color, timestamp }] }. When the page loads, I'll search the DOM for each saved highlight text and wrap it in a  element with the appropriate styling. The tricky part is accurately finding and matching the text in the DOM since the structure might have changed, but I can use a text-matching algorithm to locate the content and apply the visual markers. the tricky part - text may span multiple nodes

Text matching approach: The tricky part is finding text in the DOM. A robust approach:

Walk the text nodes of the document
Build a string representation
Find where the highlight text appears
Use Range API to wrap it

Let me look at the full content.js and sidebar.js to understand existing highlight logic better.

Actually, looking at the code:

Currently highlights are only saved to the server via SAVE_HIGHLIGHT message
There's no visual marking of text after saving
There's no restore mechanism

For a solid implementation, I need to:

Add chrome.storage.local as a fallback/primary storage - Store highlights by URL in extension storage so they survive page reloads without needing the server
Mark text visually when:
- A highlight is saved (wrap current selection)
- A page loads (re-find and wrap saved text)
Background.js changes: After saving to server, also persist to chrome.storage.local
Content.js changes:
- Add applyHighlights() function that runs on page load
- After saveHighlight() succeeds, visually mark the selection
- Add wrapTextInDOM(text, highlightId, theme) function

Now I should check sidebar.js to see how highlights are currently being displayed there.

Let me also read the sidebar.js and content.css files.

Now I have a complete picture of the extension. Here's what it currently does and what needs to change:

Current behavior:

User selects text → floating "Save" button appears
User clicks "Save" → modal opens with note/theme/agent fields
User saves → highlight is stored in server at http://localhost:3747
No visual marking of text on the page
No persistence when page is reopened

What needs to change:

Persist-on-page highlights: When a highlight is saved, visually mark it in the DOM with a  element styled appropriately.
Re-apply on page load: When the page loads, fetch saved highlights for the current URL and re-apply the visual marks.
Storage: Use chrome.storage.local as the primary/secondary storage for highlights per URL, independent of the server.

For the implementation, I need to modify background.js to save highlights to chrome.storage.local alongside the server call and add a message handler to retrieve highlights for a specific URL. In content.js, I'll fetch and re-apply stored highlights when the page loads, and update the save flow to persist marks to the DOM immediately after saving.

The trickiest part is relocating text in the DOM after a page reload. I'm walking through all text nodes to build a concatenated string with position tracking, then mapping the saved highlight's position back to the actual DOM nodes so I can wrap them in styled mark elements.

Writing the text-finding algorithm... Writing range handling logic... Writing the highlight function... Finishing the highlight logic...

I'm settling on using extractContents() to pull out the DOM nodes within the range, then wrapping them in a mark element and reinserting it back into the document. This approach handles ranges that span multiple elements cleanly since it extracts a proper document fragment rather than trying to wrap nodes in place. Now I need to design how to store these highlights in chrome.storage.local.

I'll organize them by URL so each page can quickly retrieve its own highlights. When a highlight is saved, I'll store it both on the server and locally, then on page load I'll fetch the local highlights for that URL and reapply the visual marks to the DOM.

The server remains the source of truth with all the detailed data, while the local storage acts as a quick cache for re-rendering highlights when the page loads. I need to handle updates and deletions too—whenever the server state changes, I'll sync those changes back to the local storage.

Now I'm setting up the message handlers in the background script to retrieve highlights by URL from local storage...

Updating local storage when highlights are saved...

Removing highlights from local storage when they're deleted...

Now I'm adding functions to the content script that will retrieve saved highlights for the current page and apply them by marking the text with the appropriate styling and ID. Building the highlight element...

I need to make sure the server response includes an ID field so I can pass it to the visual marking function after the highlight is saved. Let me trace through what the background script returns to confirm it has that data. Writing the save handler...

For the color theming, I need to map each theme to a distinct color so highlights stand out visually in the UI.

Adding highlight styles...

Now I need to figure out where to clone the repository locally so I can make these changes and push them back. Let me first check if it's already cloned somewhere on my system.

Now I have a full picture. Let me check if this repo is already cloned locally before deciding where to work.

There are multiple clones. Let me check which is the most current one.

/Users/karamelton/Projects/context-highlighter is the most up-to-date. Let me verify its current state and then read the local files.

Readcontent.js

Readbackground.js

Readcontent.css

Now I have all the information I need. Let me plan the changes:

What the user wants:

Saved highlights stay visible on the page while reading (visual marks on the text)
Highlights persist when the page is re-opened (re-applied on page reload)

The changes I need to make:

1. `extension/background.js`

Add "storage" is already in manifest.json permissions list - actually wait, let me check again...
Good, "storage" is already there.

Now I need to modify the message handlers in background.js. For SAVE_HIGHLIGHT, after the server responds, I'll store a compact record with the id, text, and theme in chrome.storage.local keyed by the page URL. Similarly, DELETE_HIGHLIGHT will remove the entry from local storage after the server confirms, and UPDATE_HIGHLIGHT will sync the text and theme changes. I'll also add a new GET_PAGE_HIGHLIGHTS handler that retrieves all saved highlights for the current page from local storage.

In content.js, I need to add a function that finds text in the DOM and wraps it with a highlight mark element. Then I'll create a loader function that pulls the page's highlights from local storage and applies them when the page loads. After a highlight is successfully saved, I'll immediately apply the visual mark to the page. The tricky part is matching the exact text position in the DOM—I'll need to walk through text nodes, build up the combined text, find where the highlight text appears, and then create a Range to wrap it properly.

Writing the text-matching logic... Writing the highlight logic...

For the content script injection, I'm thinking about timing—the manifest defaults to document_idle which means the DOM is already ready when the script runs. For single-page apps where the URL changes without a full reload, I'll start with just the initial injection for now since that covers the basic case.

On the storage architecture, I'm deciding whether to use chrome.storage.local as a cache alongside the server. The current behavior is that if the server isn't running, nothing gets saved and the user sees an error. I could change this to save highlights locally even when the server is down, so visual highlighting still works offline, but I'm weighing whether that's worth the added complexity.

Now I need to write the actual implementation. I'm checking what format the server returns when a highlight is saved—specifically whether it includes an ID field. From the sidebar code, I can see highlights definitely have IDs since they're used for deletion and editing. The server response should include the saved highlight object with its ID, and I need to handle the edge case where the response unexpectedly lacks an ID.

Here's what I'm changing across the files: in background.js, I'll sync highlights to local storage after successful server saves, handle deletions and updates there too, and add a handler to retrieve page highlights. In content.js, I'm adding functions to apply highlight marks to the DOM and load highlights from storage on page load, plus updating the save flow to apply marks immediately after a successful save.

Writing the content.js implementation... Writing the highlight application logic... Writing background.js handlers... Now I'm setting up the message handlers to retrieve highlights for a specific page and save new highlights to the server, storing the response data back in local storage. Writing message handlers... Adding highlight styles...

I need to make sure color: inherit is set so the mark element doesn't force black text on dark backgrounds, and display: inline keeps it from breaking the text flow. For dynamic content on SPAs like Twitter or Reddit, the highlights won't work until the content loads, so I'll stick with static pages for now and treat that as a known limitation.

On URL handling, I'll keep it simple and use window.location.href directly rather than normalizing query parameters or fragments, staying consistent with how the server saves highlights. There's a subtle difference in how applyHighlightMark behaves depending on context—when called right after saving, the user's text selection is still active in the DOM, but closing the modal immediately after wrapping the text in a mark should prevent any issues. When called during page load, there's no active selection to worry about. The approach feels solid overall.

For preventing double-applies, the text walker already filters out nodes inside existing .ch-highlight marks, so if loadAndApplyHighlights runs after a save and tries to find the same text again, it won't find it within the mark element and will safely skip it.

Since loadAndApplyHighlights runs on initial page load and saved highlights are applied in separate sessions, there's no risk of duplication there. The only edge case would be SPAs where the DOM persists across URL changes, but that's not a concern right now.

I've confirmed the manifest already has the "storage" permission, so I can use chrome.storage.local without any additional changes. Now I'm ready to finalize everything.

When saveHighlight() is called, the server response includes an id field that gets passed back to the content script. My modified background script will ensure the response includes this id alongside the other data, so the highlight can be properly stored and retrieved.

Writing the implementation... I'm going to stick with  since it's semantically correct—I'll just make sure to override the default styles with explicit color and background properties to avoid any CSS conflicts. Now let me implement the actual code that extracts the selected text, wraps it in the mark element, and inserts it back into the DOM at the correct position.

Good picture. Here's what I'll build:

content.js — add applyHighlightMark(text, id) (walks text nodes, finds the exact string, wraps it in a ) and loadAndApplyHighlights() (fetches saved highlights for this URL on page load). Also call applyHighlightMark immediately after a save succeeds.
background.js — when a highlight is saved/deleted/updated via the server, mirror a compact {id, text, theme} record in chrome.storage.local keyed by URL. Add a GET_PAGE_HIGHLIGHTS handler that returns the stored records for a URL.
content.css — add .ch-highlight styles (warm amber, matching the extension's existing palette).

No manifest changes needed — "storage" permission is already declared. Let me make the edits.

Used Mcp Ccd Session Mark Chapter

What it does: Replaces saveHighlight() in content.js to also visually mark the selected text in the DOM after saving, and adds the two new functions + page-load call. What it touches: extension/content.js only. Risk level: Low — local file edit, reversible with git. How to undo: git checkout extension/content.js

Now I'll add the two new functions and the page-load call at the end of content.js.

Now update background.js — add local storage helpers, the GET_PAGE_HIGHLIGHTS handler, and mirror writes/deletes/updates.

What it does: Adds three helper functions and updates four message handlers to keep chrome.storage.local in sync with the server store. Response to SAVE_HIGHLIGHT now always includes an id. What it touches: extension/background.js only. Risk level: Low — local file edit, reversible with git checkout.

Now add the GET_PAGE_HIGHLIGHTS handler and update the four existing handlers:

Now add the highlight mark styles to content.css.

What it does: Adds .ch-highlight styles — warm amber background matching the extension palette, with a hover state. What it touches: extension/content.css only. Risk level: Low.

Let me do a final review of all three files to confirm everything looks right before committing.

Readcontent.js80 lines

Readbackground.js

Everything looks correct. This is a browser extension — there's no local dev server to spin up, so browser-preview verification doesn't apply here. The changes are code-only and need to be tested by loading the unpacked extension in Chrome.

The diff looks clean. Let me commit it.

The changes look clean. Let me now ask the user if they want me to commit these changes. Based on the CLAUDE.md instructions, I should provide what the commit will do before committing. Actually wait - should I commit, or just describe what I'm about to do? The user asked me to "update this repo", which implies they want changes committed and pushed. But let me confirm with the user first before pushing, since pushing is visible to others (it's their public repo). Actually, I'll commit locally first, then ask if they want it pushed.

Actually, looking at the instructions again:

"Only create commits when requested by the user. If unclear, ask first."
The user did say "update this repo" which is a request, so I should go ahead and commit locally, then ask about pushing since that's the part that affects the public repository.

The diff looks right — 3 files changed, all additive. Would you like me to commit these changes locally?

Used AskUserQuestion

PII scan: all changes are code — class names, message type strings, DOM operations. No personal data. Good to go.

>git -C /Users/karamelton/Projects/context-highlighter add extension/content.js extension/background.js extension/content.css && git -C /Users/karamelton/Projects/context-highlighter commit -m "$(cat <<'EOF'
Persist highlights visually on page and across reloads

- Wrap saved text in a <mark class="ch-highlight"> immediately after save
  so the highlight is visible while reading the same page session
- On page load, fetch highlights for the current URL from
  chrome.storage.local and re-apply the visual marks, so they survive
  page reloads and tab re-opens
- Mirror compact {id, text, theme} records into chrome.storage.local on
  every save/update/delete so the content script never needs the server
  just to restore visual state
- Add .ch-highlight CSS (warm amber, colour-inheriting, hover outline)
  matching the existing extension palette

Co-Authored-By: Claude Sonnet 4.6 <[REDACTED]>
EOF
)" 2>&1

Pushed. Here's a summary of what changed and how it all fits together:

What was changed

extension/background.js — Three new helper functions (saveToLocalStorage, removeFromLocalStorage, updateInLocalStorage) keep a compact mirror of highlights in chrome.storage.local, keyed by URL. The SAVE_HIGHLIGHT, UPDATE_HIGHLIGHT, and DELETE_HIGHLIGHT handlers now call those helpers after each successful server operation. A new GET_PAGE_HIGHLIGHTS handler returns the stored records for a given URL — this is how the content script fetches what to re-highlight on page load.

extension/content.js — Two new functions:

applyHighlightMark(text, id) — walks all text nodes in the page (skipping scripts, inputs, and already-highlighted nodes), builds a combined string to find the exact text, creates a Range spanning those nodes, extracts the matched content, wraps it in a , and re-inserts it. This is called immediately after a save succeeds (so the highlight appears right away) and during page load (to restore previous highlights).
loadAndApplyHighlights() — sends GET_PAGE_HIGHLIGHTS for the current URL and calls applyHighlightMark for each result. Runs at the bottom of the script, once the DOM is ready.

extension/content.css — Added .ch-highlight and .ch-highlight:hover — warm amber (rgba(232, 213, 183, …)) matching the extension's existing #e8d5b7 palette. color: inherit prevents 's default black from clashing with dark-background sites.

One known limitation: Single-page apps (Twitter, Reddit new, etc.) that swap content without a full page load won't trigger loadAndApplyHighlights automatically — that would require a MutationObserver watching URL changes, which is a separate piece of work.

ok great also i saw that there were three local versions of this app -- should we reduce to one?

The user wants to consolidate the three local clones of the repo down to one. Let me check the three locations again:

/Users/karamelton/context-highlighter — 3 commits behind (at 050b183)
/Users/karamelton/Projects/context-highlighter — most up to date, just pushed to (at 51a3549)
/Users/karamelton/Downloads/context-highlighter — oldest, just the initial commit (bfb328a)

The most up-to-date and logically placed one is /Users/karamelton/Projects/context-highlighter. The other two (/Users/karamelton/context-highlighter and /Users/karamelton/Downloads/context-highlighter) can be deleted.

Since this is a high-risk operation, I should get explicit confirmation before deleting the directories. The good news is all three are clean repos with no uncommitted changes, and since they're all clones of the same GitHub repo, they can be easily restored if needed.

Yes, good call. Before deleting anything, let me check whether the other two have any uncommitted local changes worth keeping.

Both are clean — no uncommitted changes, no stashes. Safe to delete.

HIGH RISK — this will permanently delete two directories:


What it does	Deletes `/Users/karamelton/context-highlighter` and `/Users/karamelton/Downloads/context-highlighter`
What it touches	Those two folders and everything inside them
Risk level	High — deletion is not reversible
How to undo	Both are behind GitHub's `main`, so you can always `git clone` them back. But the directories themselves will be gone.

The one we keep is /Users/karamelton/Projects/context-highlighter — it's the most current and is where your other projects likely live.

Want me to go ahead and delete the two older copies?

confirming that what's update on main is: /Users/karamelton/Projects/context-highlighter

Confirmed. /Users/karamelton/Projects/context-highlighter is on commit 51a3549 — exactly what we just pushed to origin/main. Clean working tree, nothing pending.

Ready to delete the other two whenever you say the word.

let's delete

Both are gone. Your single canonical copy is at /Users/karamelton/Projects/context-highlighter, in sync with GitHub.

walk me through updating the extension in chrome

Here's how to reload the updated extension in Chrome:

1. Open the Extensions page Go to chrome://extensions in your address bar.

2. Enable Developer Mode Toggle Developer mode on in the top-right corner (if it isn't already).

3. Load (or reload) the extension

If you've never loaded it before: Click Load unpacked → navigate to /Users/karamelton/Projects/context-highlighter/extension → click Open.
If it's already loaded: Find the Context Highlighter card and click the circular ↺ refresh icon on it.

4. Confirm it updated The version shown on the card should still say 2.0.0 (we didn't bump it), but the ID and last updated time will reflect the reload.

5. Test it

Open any article or webpage with a decent amount of text.
Select some text — the floating Save button should appear.
Click Save, fill in a theme, hit Save Highlight — the selected text should immediately get a warm amber highlight on the page.
Reload the page — the highlight should reappear automatically.

One thing to note: the highlight persistence relies on the local server (cd server && node index.js) being running when you save. If the server is offline, you'll see the warning in the modal and nothing will be stored. Once you save with the server running, reloads work without the server since the data is cached in chrome.storage.local.

The error says the file path ~/context-highlighter/extension cannot be resolved. This is the old path — the one we deleted! Chrome has the old extension loaded from /Users/karamelton/context-highlighter/extension (which no longer exists), and it's trying to reload from that path.

They need to remove the old extension entry and load the extension fresh from the new path /Users/karamelton/Projects/context-highlighter/extension.

Chrome is still pointing at the old path (~/context-highlighter/extension) — the one we just deleted. You need to remove that entry and load fresh from the new location.

Click Cancel on that dialog.
Find the Context Highlighter card on chrome://extensions and click Remove to delete the stale entry.

Click Load unpacked and navigate to:

Click Open.

That will load it cleanly from the correct path going forward.

so i've highlghted this text but when i click save it doesn't highlight the text

The user has selected text and the floating "Save" button is showing, but when they click "Save" the modal doesn't appear to show (or maybe it does but the text doesn't get highlighted after saving). Looking at the screenshot, it seems the Save button appeared correctly which is good.

The issue might be:

The server is not running, so the save fails and no highlight is applied
The modal appears but after saving, applyHighlightMark fails silently

Wait, looking more carefully at the screenshot - the user says "when I click save it doesn't highlight the text." So they ARE clicking save... but what happens? Does the modal appear? Or does the modal appear and they save, but no highlight appears?

Actually, re-reading their message, they're clicking the Save button in the floating UI and the text isn't getting highlighted. Most likely the server isn't running — when that happens, saveHighlight() returns an error and never calls applyHighlightMark, so the visual highlight never gets applied. But looking at the screenshot again, I see the blue selected text is visible, so I'm wondering if they haven't actually clicked save yet or if they're asking why previous highlights aren't showing.

Wait, they explicitly said "when I click save it doesn't highlight the text" — so they have clicked it. The most probable issue is still the server being down, which would cause the save to fail silently. But there's also a chance the modal appeared, they filled it in and saved successfully, but the highlight just didn't render visually, which would be a different bug. I should ask whether a modal appeared after clicking Save and if it showed any server warning.

A couple of quick questions to diagnose — what happens after you click Save?

Used AskUserQuestion

Request interrupted by user

I think the server has broken actually -- i'm using host and now i can no longer turn the server on; it was probably runnign against one of local copis we deleted?

The user is saying that they're running some kind of monitoring/server management tool at localhost:2000 that shows monitors for "context-highlighter" and "second-line". The context-highlighter server is now off/broken because it was likely pointing to one of the deleted local copies.

They need to update whatever is managing the server process to point to the new location: /Users/karamelton/Projects/context-highlighter/server.

Let me figure out what's running at localhost:2000. It looks like some kind of process monitor - possibly PM2, or some other tool. Let me check what's running.

"Hotel" - that's the Hotel app! Hotel is a process manager for development servers that runs at localhost:2000.

So Hotel is managing the context-highlighter process, and its configuration is pointing to the old deleted path. I need to find the Hotel config file in ~/.hotel/ and update the context-highlighter entry to use the new server path at /Users/karamelton/Projects/context-highlighter/server.

That's Hotel — it's a dev server manager. Its config for context-highlighter still points to the deleted path. Let me find and fix it.

Found it — cwd is pointing to the deleted path. I'll update it to the correct one.

What it does: Updates the cwd in Hotel's config for context-highlighter to the correct path. What it touches: ~/.hotel/servers/context-highlighter.json Risk level: Low — small config edit, easy to revert. How to undo: Change cwd back to the old path.

Readcontext-highlighter.json

Done. Now go to localhost:2000, toggle the context-highlighter switch off and back on (or just on if it's already off). Hotel will restart the server from the correct path and it should come back up on port 3747.

interestingly -- the modal isn't opening on this page when i click save

The user is saying that on this page, when they click the Save button (the floating button after selecting text), the modal doesn't open. Let me think about why this might be happening.

Looking at the screenshot, the text is selected and the floating "Save" button appeared correctly. But clicking it doesn't open the modal.

Possible causes:

The page might be running in a context where the content script can't inject properly (e.g., a page with strict CSP - Content Security Policy)
The modal is being created but not visible (z-index issue, CSS conflict)
There could be an error when creating the modal that's silently failing
The page structure might have an unusual document.body setup

Since the floating Save button is working, the content script is definitely running. The problem is specifically that the modal isn't appearing when clicked. The openSaveModal function should be creating the modal on first click and then showing it, but something's breaking in that process.

I'm wondering if there's a CSS rule on the page that's overriding the modal's display property, or if the modal is being created but positioned off-screen. There could also be a z-index stacking context issue where the modal is behind other page elements. Let me consider whether the page uses iframes or Shadow DOM, though it looks like a standard article page from what I can see. The core issue is that the modal creation or display logic isn't working even though the button itself is functioning fine.

The most likely culprit is a JavaScript error happening when the modal tries to open—maybe the message to the background script is failing due to an invalidated extension context. It's also possible the content script didn't fully inject on this particular page, especially if it's slow-loading or has a complex DOM. I should check whether Chrome is blocking the extension from running on this specific page type, though it appears to be a regular website. The key difference seems to be that the modal works on some pages but not others, so there's something specific about this page's environment preventing it from displaying.

The most likely candidates are Shadow DOM usage, strict Content Security Policy headers, iframe structures, or timing issues where the DOM isn't ready when the script injects. CSP shouldn't normally block DOM manipulation from content scripts, but it's worth considering. When the button gets clicked, I need to trace through what happens next...

Adding event handler logic...

The openSaveModal function creates the modal by appending to document.body, but since the button itself is visible, document.body should exist. The real issue might be the chrome.runtime.sendMessage call inside the modal creation—if the extension runtime gets invalidated after a reload or update, all subsequent messaging calls fail silently. I should ask the user to check the browser console for any errors that would pinpoint exactly where things are breaking. I'm wondering if the issue could be related to Content Security Policy blocking the modal creation, though that seems unlikely since innerHTML itself doesn't trigger CSP for regular HTML. Looking more closely at openSaveModal, I see it creates the modal on first call and then sends a message to check the server status, which determines whether to show a warning — so if that message fails or times out, the modal might not display properly. I'm wondering if the modal reference could become stale somehow, though that seems unlikely in a content script context. The more practical approach would be to have the user check the Chrome DevTools console for any errors that might reveal what's actually happening. There's also a possibility that document.body isn't what we expect in certain SPA scenarios.

The floating button is appearing but the modal isn't — that points to a JavaScript error happening inside openSaveModal when it tries to build or show the modal. The most likely cause is a page-level CSS or script conflict.

Let's get the exact error. On that page:

Right-click → Inspect (or Cmd+Option+I)
Click the Console tab
Click the floating Save button again
Paste here any red errors that appear

That will tell us exactly where it's breaking.