// ZPWRCHROME — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zpwrchrome is a single-author Chrome MV3 extension built around the MRU (most-recently-used) tab primitive. The service worker tracks tab activation in chrome.storage.session across windows; the toolbar popup renders 12 categories with fzf fuzzy filtering; a Tampermonkey-equivalent userscript engine runs in Chrome's native USER_SCRIPT world via chrome.userScripts; and a frecency-ranked chrome.history search replaces Chrome's built-in chrome://history page on Cmd+Y. 6,959 JS lines + 1,104 CSS lines + 22,708 test lines · 54 commands · 19 message handlers · 2948 tests passing.

~SUBSYSTEM BREAKDOWN

Every JS surface in the repo, by role. Pure helpers in lib/util.js + lib/fzf.js carry zero chrome.* references so they unit-test headless and so scripts/build-modal.mjs can inline them into the content-script modal between UTIL_INLINE_START/END and FZF_INLINE_START/END markers.

#TOP FILES BY SIZE

Sorted descending. modal/content.template.js is the source; modal/content.js is generated (fonts + fzf + util inlined) and excluded from this table.

%ARCHITECTURE

Three processes, six storage planes. Chrome hosts the extension; the extension's SW (one process) talks to a Rust native messaging host (one process per request, plus detached download worker processes that outlive their parent). All persistent state lives in chrome.storage or on the filesystem under ~/.cache/zpwrchrome/ — nothing relies on the SW staying alive.

@EXECUTION PIPELINE

Three persistence stores: chrome.storage.session for MRU (survives SW restart, not browser restart), chrome.storage.local for scenes / userscripts / GM bags / fire log, and the Chrome-managed chrome.history + chrome.sessions APIs for browsing history and recently-closed tabs.

    chrome.tabs events            background.js (SW)                  chrome.storage
   onActivated  ────────────▶  pushMru / dropFromMru  ────────▶  .session
   onRemoved                                                              (MRU array)
   onReplaced                                                              .local
                              command dispatcher                       scenes
                              message API (popup/modal)                userscripts
                              userscripts registration                 fire-log ring
                              history-list (frecency)                  GM bags
                                       │
                                       │ runtime.sendMessage / tabs.sendMessage
                                       ▼
              popup.html/.js                          modal/content.js (shadow DOM)
              ───────────────                         ─────────────────────────────
              12 categories                            10 categories (dormant since v0.4.16)
              fzf filter                              10 categories
              keyboard nav                            same protocol kinds

              scripts-manager/manager.html
              ────────────────────────────
              Tampermonkey-style dashboard
              4 tabs · sortable table · firelog reader

&MESSAGE PROTOCOL

19 message kinds handled by the service worker. Popup sends 18 kinds; modal sends 19. tests/protocol.test.js guards against orphans on either side.

• activatepopup/modal → SW. Switch to a tab by id + focus its window.
• close-tabpopup/modal → SW. Close an open tab; refresh.
• gm:deleteValueuserscript shim → SW. Per-script chrome.storage.local bag delete.
• gm:fireuserscript shim → SW. Beacon appended to the fire log at script load.
• gm:getValueuserscript shim → SW. Per-script chrome.storage.local bag read.
• gm:listValuesuserscript shim → SW. List keys in the per-script bag.
• gm:notificationuserscript shim → SW. chrome.notifications.create proxy.
• gm:openInTabuserscript shim → SW. chrome.tabs.create proxy (also used by history-row Enter in the modal).
• gm:setClipboarduserscript shim → SW. Inject navigator.clipboard.writeText() into the active tab.
• gm:setValueuserscript shim → SW. Per-script chrome.storage.local bag write.
• history-deletepopup/modal → SW. chrome.history.deleteUrl for every visit of a URL.
• history-listpopup/modal → SW. chrome.history.search up to 5000 results, frecency-sorted before return.
• listpopup/modal → SW. Returns MRU tab list + 25 most-recently-closed sessions.
• open-scripts-managermodal → SW. Opens scripts-manager/manager.html in a new tab.
• restorepopup/modal → SW. Restore a closed session by sessionId.
• scenes-deletepopup/modal → SW. Drop a scene by slug.
• scenes-listpopup/modal → SW. Returns persisted scenes from chrome.storage.local.
• scenes-restorepopup/modal → SW. Open a new window populated from a scene by slug.
• scenes-savepopup/modal → SW. Snapshot the active window's tabs as a named scene.

$KEYBOARD COMMANDS

Chrome MV3 caps commands with default-suggested keys at 4; everything else is user-bound at chrome://extensions/shortcuts. Currently 4 default-keyed (_execute_action=Alt+T, switch-previous-tab=Command+E, open-history=Command+Y, pass-fill=Command+Shift+L), 50 user-bound, 54 total.

%POPUP CATEGORIES

The popup (popup.html/popup.css/popup.js) renders 12 categories with fzf scoring against title + host. Each category is jumpable via Cmd+1..Cmd+0 (where Cmd+0 = History, the 10th slot). The modal mirrors the same list since v0.4.15.

• All Tabs⌘1
• Current Window⌘2
• Pinned⌘3
• Audible⌘4
• Muted⌘5
• Recently Closed⌘6
• Scenes⌘7
• Tree (by opener)⌘8
• Minimap⌘9
• History⌘0
• Pass⌘P
• Tech⌘K

^HISTORY — FRECENCY FORMULA

chrome.history.search({ text: "", maxResults: 5000, startTime: 0 }) returns visits in lastVisitTime-desc order, which over-promotes one-off pages. background.js:history-list re-ranks by frecency before returning to popup/modal. Each result carries its frecency field forward so the fzf sort uses it as a tiebreaker.

  // lib/util.js — pure, unit-tested, inlined into modal via UTIL_INLINE
  export function frecencyScore(item, nowMs = Date.now()) {
    if (!item) return 0;
    const visits = (item.visitCount || 0) + 2 * (item.typedCount || 0);
    if (visits <= 0) return 0;
    const last = item.lastVisitTime || 0;
    if (last <= 0) return visits;
    const hoursAgo = Math.max(0, (nowMs - last) / 3_600_000);
    return visits / (hoursAgo + 2);
  }

!PERMISSIONS

18 declared. tests/static.test.js enforces every declared permission is actually used in background.js or popup.js — no dead permissions.

*TESTS

Plain node:test. Zero dependencies. 2948 cases across 181 files in ~1s. CI matrix: Node 20 + 22 on ubuntu-latest.

?KEY DESIGN DECISIONS