Written 2026-10-15 for the next agent or person picking this up. Read AGENTS.md first (rules of the road, testing, the holodeck); this file is the state of play and the open questions.
- Branch:
feature/v1-rewrite. At the original handoff, 19 commits ahead ofmaster, all pushed, with PR #22 open: #22. The continuation below adds local, uncommitted changes. - CI: green at the original handoff (unit tests on Node 22 and 24, headless e2e on Chrome for Testing, packaged zip artifact). Not rerun remotely for the local continuation.
- Tests: 57 unit tests (
make test), 94 e2e checks (make e2e), both green locally after the continuations. Syntax checks (make check, now including content scripts) also pass. - Nothing is published.
masteris still the 2021 Manifest V2 "URL Notes" app, which no longer loads. The store listing kit (STORE_LISTING.md,promo/store/) is ready but unused. - The owner (Jonathan) has loaded the branch unpacked in Brave and used it. Feedback so far has all been folded in.
Code review found that automatic panel refreshes used the same capture-enabled request as a popup opening, and pending drafts relied on a tab's current URL even after navigation. Fixed in src/popup.js:
- Only the initial popup lookup requests a capture. Panel navigation and storage refreshes explicitly pass
capture: false; the toolbar-click service-worker handler still captures for the panel. - Drafts carry the displayed page's URL and title, which the worker resolves through the existing canonical identity rules. Saves wait for any in-flight draft and drain newer text before changing pages.
- A failed save leaves the text dirty so blur can retry it. Actions that depend on saving stop on a failed save.
- Refresh responses are versioned so a late result cannot replace a newer page. Typing during a lookup is preserved. Panel events are scoped to its window and current note.
- Eleven additional browser checks cover passive captures, save failure and retry, navigation with a held save response, and out-of-order page lookups. Browser tests ran with
HOLODECK=/private/tmp/page-notes-holodeckand blocked external DNS, using only the existing text fixtures.
This continuation did not publish or update the remote PR.
Implemented the owner's screenshot feedback, also local and uncommitted:
src/lib/explorer.jsandsrc/explorer.cssprovide a shared Sites → Pages → Notes browser. All notes uses columns at wider sizes; the sidebar uses collapsible site/page groups and an inline preview of dated entries, stickies and captures. Search includes sticky text and quoted anchors. Selection does not open tabs; Open page and Full details are explicit actions sent to the worker viaopenNote.- The sidebar has a back arrow beside the title to browse saved pages, and a return-to-current-page control. Opening the panel on a browser/extension page starts in the library. Full details now includes stickies too.
- Warm paper colors, folded-corner pins and a persistent on-page control distinguish stickies.
stickyVisibilitystores a global local preference and broadcasts show/hide changes to existing layers; no new host permissions or passive injection. Picking or jumping to a sticky reveals the layer again. Hiding flushes an open sticky's pending edit. The sidebar empty-sticky hint now spans the full row. - Red toolbar badges count entries plus stickies, with a descriptive tooltip. Capture-only pages keep a neutral dot. The popup/sidebar shows a saved-note banner with a brief arrival highlight that respects reduced motion.
- A one-time service-worker startup migration cleans unread counters from existing LinkedIn note titles and index rows. It preserves canonical identity, timestamps, entries and original capture titles. Tests cover the transformation and storage migration.
- Validation: 57 unit tests, 94 e2e checks, syntax checks and whitespace checks passed. Light/dark and narrow/wide previews were inspected. To regenerate them:
HOLODECK=/private/tmp/page-notes-holodeck E2E_SCREENSHOTS=/private/tmp/page-notes-preview make e2e.
Reload the unpacked extension and refresh existing page tabs to pick up the new in-page layer. Naming, release, drag/selection anchoring and shared review remain open.
Owner feedback from use: the sidebar back arrow looped, and the docked sidebar could not be dismissed. Also local and uncommitted:
- Back is a hierarchy, never a toggle.
src/lib/explorer.jstracks a level (0 sites, 1 pages of a site, 2 a page) exposed throughroot.dataset.level, withup(),focus({ host, id }),depth()and anonNavigatecallback. The narrow layout shows one level at a time; the wide one keeps three columns. The trail is a breadcrumb of buttons. In the sidebar the header arrow lands on the current site's page list, the library arrow climbs one level and hides at the top, and returning to the page is a separate footer action (#return-to-page). "All notes" in the footer goes to the root. - Sidebar close.
#close-viewin the panel header and library header callswindow.close(), which closes the side panel. In sidebar mode the worker now clears the action popup (chrome.action.setPopup({ popup: '' })) so the icon toggles the panel; a popup would otherwise take the click. Esc does not close the panel (a stray Esc while writing must not), only the popup and the widget. - Launch modes.
settings.launchis'popup' | 'sidebar' | 'floating'(LAUNCH_MODESinsettings.js);openInSidePanel: truemigrates to'sidebar'inmergeSettings.applyLaunchMode()in the worker sets the popup and the side panel behaviour;chrome.action.onClickedcaptures the page and, in floating mode, injects the layer and sendspn:widget. On browser or extension pages in floating mode it opens the side panel instead. Options has a three-way card selector. - Floating widget in
src/content/layer.js: a draggable.fab(icon, sticky count) and a draggable.widgetwindow holding an iframe ofsrc/panel.html?embed=1, both in the shadow root, positions remembered through the worker messagewidgetLayout(widget:layoutin storage.local). The page cannot see into the frame. Clicking the icon again toggles the widget; Esc on the page or in the frame closes it; the frame asks the layer to close withpostMessage({ type: 'pn:widget-close' }), accepted only from the frame's window and the extension origin.src/panel.htmlandimg/icon32.pngare web-accessible for this. - Embed mode in
popup.js:EMBEDfrom the query string, body getsembed; bound tochrome.tabs.getCurrent(), follows in-page navigations of that tab, never captures (the worker did on the click), anddismiss()replaceswindow.close(). - Owner reported floating mode not working after the above. The in-page mechanism was verified in a real headless Brave (a patched copy of the extension with a host permission on the fixture standing in for the activeTab grant; see the approach in the scratch script described here: inject, send
pn:widget, probe the shadow root, connect to the frame target): the button appears, the frame loads the embedded panel bound to the tab, a second click closes it, and aframe-src 'none'CSP does not block the frame. Two upstream causes were fixed:annotate.jsreused a layer orphaned by an extension reload (itschrome.runtime.idis gone, so the worker could never reach it); it now asksalive()and reboots, andboot()removes stale hosts. And the side panel fallback for non-web pages lost the click gesture behindawait loadSettings(); the mode is now cached in the worker (launchMode, warmed at every worker start) andchrome.sidePanel.openis called synchronously. A failed launch marks the tab's badge with!and explains in the icon tooltip. If it still fails for the owner, ask which page and whether the badge showed!. - Pages listed by site. Across all sites the page list has a heading per site, sorted by host; the column label and the sidebar library header name the level (All notes with counts, the site, or the page and its site).
Owner's ask: link any page to any other across sites (GitHub profile to LinkedIn profile), with a type-search-filter widget over the pages with notes. Local and uncommitted:
- Model (
notes.js):note.linksis a list of the other pages' canonical keys, symmetric, written on both notes bylinkNotes/unlinkNotes(pure, tested). Keys resolve to ids withnoteId(key), so the frontmatter linelinks: [github:user:jontsai]round-trips and survives import;mergeNotesunions links;indexEntrycarries alinkscount.store.jskeeps a note that only holds a link (a note is "empty" only without entries, reminder, captures, stickies and links). - Worker:
link({ id | url | tabId, otherId }, creating the note for a never-noted page),unlink,links(resolved index rows, a deleted other side comes back asmissingwith its key),currentreturnslinked,deleteNoteremoves the page from the pages it was linked to. Each has e2e checks. - Picker (
src/lib/picker.js):createPagePicker({ exclude, onPick, onClose }), a combobox over the index: loads once, filters on every typed word across title, site, URL and the latest note (matchRows, tested), arrows/Enter/Esc, mouse. Esc stops propagation so it does not close the popup or widget. Used in the popup/sidebar "Linked pages" section (#add-link), the explorer preview ("+ Link a page") and nowhere else yet; it is the widget to reuse for any choose-a-page need. - UI: "Linked pages" card in popup, sidebar and widget; click a linked page to show it in the library (sidebar) or open its details (popup), ↗ opens the page, ✕ unlinks. The explorer preview lists links and navigates to them (
explorer.show(id)); the details page lists them read-only. Obsidian-style[[wikilinks]]in the Markdown body would be a natural follow-up; keys in frontmatter were chosen to keep the round-trip lossless.
Owner's asks: use the extension in several browser profiles with notes synced through the iCloud Drive vault folder (each profile on its own schedule, files readable by any browser; SQLite was floated for speed), and send stickies to someone as a flat file with compression and encryption, no server.
- Format decision: Markdown files stay the storage format. SQLite in iCloud Drive with two writers is a corruption hazard and needs a WASM dependency; speed comes from a metadata-only scan instead.
src/lib/vault.js(pure, tested):syncFolder(folder, store, state)lists{ name, mtime, size }, reads a file only when mtime or size changed, compares by FNV hash before parsing (cloud drives re-stamp mtimes), merges withmergeNotes, and writes a file only when it differs from the note's serialization, so profiles converge without ping-pong. Local changes made while the vault was unreachable are caught by comparing the recorded hash with the note's current serialization. Deletions propagate both ways through the per-profile state (vault:state,{ files: { name: { id, mtime, size, hash } } }). A note's file follows its title (old name removed). Capture-only notes get no file.memoryFolderis the test and e2e seam (syncVaultacceptsargs.folderand returns the folder and state);handleFolderwraps a FileSystemDirectoryHandle. - Worker:
persistwrites through the adapter and records the file;deleteNoteremoves the file;syncVaultis serialised and runs from a per-profile alarm (vault:sync, every 5 minutes), at startup, on "Sync now", after re-allowing access, and at most once a minute when the popup or panel looks at a page.vault:statusholds the last result and report;currentreturns it so the popup can show the once-per-session "Allow" banner (#vault-hint, callsrequestPermissionfrom the page, thensyncVault). Permission cannot be requested from the worker. - Sharing:
src/lib/share.js(pure, tested in node 22+):sharePayload(stickies, entries optional),encodeShare/decodeShare(JSON → deflate-raw via CompressionStream → optional PBKDF2-SHA256 (250k) + AES-256-GCM with random salt and iv → base64 at 76 columns, wrapped in BEGIN/END lines, headerpagenotes/1 deflate aes-gcm|none),inspectShare,applyShare(stickies by id, entries by minute+text, idempotent). Worker:shareExport { id, passphrase, includeEntries },shareImport { text, passphrase, url? }resolving the page by the recipient's rules and creating the note if needed. UI: "Share…" and "Import…" in the stickies card (popup, sidebar, widget), copy or download.pagenotes.txt; Settings imports a file. Anchors travel with the stickies; on a page that differs they show as orphans. - Event-driven sync (owner's follow-up).
FileSystemObserveris available in this Brave (Chromium 155) in extension pages but not in service workers; verified in the holodeck. So:observeHandle(handle, onChanges)andchangeCollectorinvault.js(pure, tested), the side panel / widget page (popup.js) and Settings (options.js) watch the vault folder while open and ask the worker for a scoped sync (syncVault { only: [names] }), whichsyncFolderhonours bystat-ing just those files and handling reported deletions, skipping the write-out of unrelated notes. The worker has the same watch code (watchVault, re-armed on every wake) which is a no-op until a browser exposes the API to workers. The 5-minute alarm and the once-a-minute look-at-a-page sync remain the safety net. e2e drives the real observer over the origin-private file system to pin the record shape. - Tests: 74 unit, 167 e2e checks (launch modes and the popup/behaviour pair, legacy migration,
widgetLayout, the embedded page's Esc, the layer's button and window including drag by synthetic pointer events, and the sidebar's hierarchical navigation and close control).
A Manifest V3 extension, vanilla JavaScript, no build step, no dependencies, no server. One note per page, with page identity from URL rules so a note on a PR shows on its Files tab. Features, all shipped on the branch:
- Editor that is today's entry, autosaving; earlier entries edit in place.
- Captures: on every popup open, the page's title, metadata and text are stored locally as history; changed-since-last-visit diff.
- Profile insights: a text-based LinkedIn parser and consistency analysis (overlapping roles, two current roles, backwards dates, short stints, gaps, truncation, stated years, edits between visits), a one-line card grouped by employer.
- Stickies: comments anchored to page elements (css path rooted at a stable id, text quote with context, structural path), an in-page layer in a shadow root, pick mode, feedback export as a numbered list with quotes.
- Reminders and snoozed tabs as one-click chips; selection capture from the context menu.
- Side panel: the same view beside the page, following the active tab.
- Markdown with YAML frontmatter: zip export with captures, import with merge, Obsidian vault folder connection.
- Options page: all notes with search, reminders, backup and vault, settings with a rules tester.
- Name: decided 2026-10-17.
nameis "Marginalia (Page Notes)" andshort_nameis "Marginalia" inmanifest.json; code reads them at runtime, the short name for compact spots (on-page pins, widget bar, badge tooltip, empty header) and the full name for titles and the store. Both plain names are taken in the Chrome Web Store (a "Page Notes" with 10k+ users; a "Marginalia" study-notes extension; Marginalia Search), so the combined name is deliberate: brand Marginalia, discoverable as page notes. User-visible format tokens were renamed before any file existed: share envelope-----BEGIN/END MARGINALIA-----, headermarginalia/1, file suffix.marginalia.txt, frontmatterapp: marginalia. Internal keys (IndexedDBpage-notes,data-page-notes,__pageNotesLayer,pn:messages, storage keys) stay as they are by rule. The repo staysnotes-chrome-extension; the owner's iCloud Drive vault folder ishtk_marginalia(renamed frombrowser_noteson 2026-10-17; each profile reconnects after a rename, since Chromium keeps directory handles by path) and nothing in code depends on it. - Site names stay in titles. Only leading unread counters like "(3)" are stripped. The owner asked for this explicitly.
- Every capture is a user action. No background content scripts, no passive collection, nothing transmitted. Per-site "always show stickies" is an explicit opt-in through optional host permissions requested from the popup. This is a product rule.
- Insights are questions, never verdicts. Findings are
askorinfowith neutral wording. Never infer intent or protected characteristics. Never reference the owner's private hiring repository anywhere in this codebase. - No live LinkedIn, ever, in tests or development. Parsers are built against
test/fixtures/*.txtonly. LinkedIn's bot detection is strong and the owner forbade it. - Notes in
chrome.storage.local, settings in sync (sync is capped at 100 KB total). src/lib/url.jsis a copy of the Organize Tabs module. Keep in sync by hand until hacktoolkit/organize-tabs-chrome-extension#12 extracts it.- UX bar: "smart, responsive, minimal clicking, avoid forms, autosave, automagic", polish at the level of Airbnb, Figma, Gusto. The shared token system is
src/ui.css; refine it, do not replace it.
- The name (above).
- Merge and release: tag
v1.0.0, GitHub Release with the CI zip, bump the submodule in hacktoolkit/chrome-extensions, upload to the Chrome Web Store usingSTORE_LISTING.md. Permissions that will draw review questions:scripting,notifications,unlimitedStorage,sidePanel, and the optional host permissions; justifications are in the kit. - Stickies polish once used for real: drag to reposition, a sticky on a text selection rather than a whole element, export to a shareable page.
- Options now has a responsive saved-page explorer; the remaining settings sections still use the original card layout.
- A second site parser (GitHub profile, Crunchbase) would follow the
extractorForpattern insrc/lib/profile.js, fixture first.
make test # unit, seconds
make e2e # headless browser, every feature, about 3 minutes
make dev # the holodeck: throwaway Brave profile with the extension loaded
make screenshots # README images and 1280x800 store screenshots
make package # zip for the store- The holodeck (
~/.holodeck/) is the only place browser tests run. Never test against a real profile. SeeAGENTS.md. - Google Chrome's branded build ignores
--load-extension; use Brave or Chrome for Testing (CI installs the latter via@puppeteer/browsers). - The e2e suite blocks DNS (
MAP * ~NOTFOUND, EXCLUDE 127.0.0.1) and serves a fixture page plussrc/from a local http server so the in-page layer runs in a real DOM with a stubbedchrome.*. Captures in e2e are supplied throughargs.snapshotbecauseactiveTabneeds a real click. - Pushing to hacktoolkit repos from the owner's machine needs the
jontsaiSSH key explicitly:GIT_SSH_COMMAND="ssh -i ~/.ssh/jontsai-dataro-id_ed25519 -o IdentitiesOnly=yes" git push .... The agent offers another account's key first. - Chain shell commands carefully:
make e2e 2>&1 | grep ...exits with grep's status, so&& git commitafter it commits on failure. Write the log to a file and test forALL PASSED.
manifest.json MV3, module service worker, popup, side panel, options, commands
src/background.js every operation: messages, badge, reminders, snooze, capture, stickies, layer injection
src/lib/notes.js note model, today's entry, captures, stickies, Markdown round-trip, feedback export (tested)
src/lib/profile.js LinkedIn parser, consistency analysis, edit detection, text diff (tested)
src/lib/anchor.js how a sticky finds its element again (tested on a fake DOM)
src/lib/url.js URL identity rules, copied from Organize Tabs (tested)
src/lib/store.js storage.local notes and index (serialised writes), Obsidian vault handle
src/lib/settings.js settings in sync with local fallback
src/lib/zip.js minimal zip writer (tested)
src/lib/ui.js el/send/fmt shared by the pages
src/content/ annotate.js bootstrap + layer.js (shadow-root pins, popover, pick mode)
src/popup.* the note for the current page; src/panel.html is the same view for the side panel
src/note.* one note in full: insights, changes, entries, captures
src/options.* all notes, reminders, backup and vault, settings, help
scripts/e2e.mjs headless browser suite; scripts/dev.mjs holodeck; scripts/screenshots.mjs
test/ node --test suites and LinkedIn text fixtures
STORE_LISTING.md store copy, permission justifications, privacy answers
This extension is one of the Hacktoolkit Chrome extensions (collection repo: hacktoolkit/chrome-extensions, see its AGENTS.md):
- organize-tabs-chrome-extension: v2.1.0 in the store; reference implementation. Open: PR #13 (one-line
ui.cssfix), issue #12 (share the URL rules module). - skeleton-chrome-extension: the template new extensions start from; this extension was built on it.
- paywall-xray-chrome-extension: next candidate for modernisation; not publishable to the store.
Blog posts about the Organize Tabs rebuild are at https://www.jontsai.com/2026/10/10/organize-tabs-2-0 and https://www.jontsai.com/2026/10/11/building-organize-tabs-2-0-with-claude-code and describe the working process the owner likes: review first, constraints from use, real browser tests, an adversarial review before shipping.