Chrome-prep program: DOM-guard, leaf utils, typed monoliths, feature split, capability seam (2.5.0)

[perdrizat]

Tracking issue for the chrome-prep program — the architectural runway for the Chrome port (stage 3), executed Firefox-first so every arc leaves the extension strictly better on its own.

Plan of record: CHROME_PREP.md (living checklist; on branch chrome-prep until merged). Ships as 2.5.0; 3.0.0 stays reserved for the first AMO release after this program and its follow-up audit round (maintainer decision 2026-07-10). Successor to the page-modules arc (#2, shipped as 2.4.0).

Origin: an auditor-volunteered phase plan, adjudicated with corrections — one security-boundary trap excluded (the lib/backup.js restore validators stay independent, per standing decision of record), one scope reduction (divergence audit + targeted wrappers instead of blanket browser.* indirection), stale already-shipped items dropped.

Binding maintainer directives

1. Principled harness design (C3): E2E/UAT move to real UI/gesture driving — no test handle in production code. Accepted consequence: a flaky synthesized-drag E2E test for a while. Payoff: every globalThis bridge assignment retires, including the dual-scope survivors — zero bridges repo-wide.
2. Real JSDoc for the monoliths (C3): quality typedefs, no any-cast escape hatches; budgeted as a big effort deliberately.

Arcs

• C0 — design decisions of record: Chrome context menus (the in-tile action row is the Chrome interaction; Firefox's dynamic menu is progressive enhancement) and theme (prefers-color-scheme source; browser.theme as Firefox bonus).
• C1 — background DOM-guard: lint/test guard forbidding DOM access in lib/** outside the thumbnail-image.js swap seam + audit pass.
• C2 — leaf utilities: el() DOM-builder + textContent normalization (~37 sites, Stage-H review §8), page-side color helper. Restore validators explicitly excluded.
• C3 — type the monoliths + principled harness + bridge endgame: full JSDoc on newTab.js/fx-newTab.js, dead-queue + dead-guard retirement, harness off page-globals, all globalThis bridges deleted.
• C4 — split the monoliths into cohesive feature modules (grid, site, cell, drag-drop, transformation, updater, undo; drawer, wallpaper, theme, startup, message glue).
• C5 — capability-seam completion: browser./chrome. divergence audit artifact, in-house namespace normalization (no polyfill dep), targeted wrappers (menus, theme, search, capture, action) — background in lib/platform.js, page in its own capability leaf.
• C6 — two-target manifest authoring: manifest.base.json + per-browser overlays merged by a sync-version.mjs-sibling script; no bundler, source == shipped on both targets.
• C gate: full suite + full UAT + audit + boot-timing re-check + 2.5.0 bump + docs sweep + review round.

What the Chrome port then reduces to

Fork the seam implementations (namespace, search, theme-degrade, menus-absent), write the OffscreenCanvas thumbnail-image.js, add the Chrome manifest overlay — a bounded, reviewable fork of a handful of files.