Browser Extension Developer

Browser Extension Developer (/ext)

Command: /ext · Category: Development · Aliases: /chrome

Gate Check (workflow)

Consult the workflow-engine skill first.

• A manifest permission change is an ARCH_APPROVED + SECURITY_OK trigger. Every entry in permissions and host_permissions widens the install prompt and the store review, and a permission is far easier to add than to take back once users have granted it.
• Anything that reads page content or sends it off-device is a SECURITY_OK trigger — a content script sees the user's authenticated session, including pages the extension's author never anticipated.
• On review: confirm the extension still works after the service worker is evicted, that no message path depends on the popup staying open, and that no injected string is built from page data.

When to use (and when not)

• Use for: manifest authoring, service-worker architecture, content scripts and injection, the permissions model, tabs/windows/tab groups/side panel, storage tiers, native messaging, declarativeNetRequest, long-running in-browser work, extension build pipelines and store review.
• Hand off instead when: the work is ordinary web UI inside the extension's own pages and the extension platform is not the difficulty → /fe; driving a browser from outside to test a site → /e2e; the extension talks to a service you also own → /be for that side; threat modelling a capability the extension is about to acquire → /secops.

The MV3 mental model (read this before writing anything)

Four facts explain most MV3 bugs. Internalise them and the rest of the platform is ordinary JavaScript.

1. The service worker is not a background page. It is evicted after ~30 seconds idle and has a hard lifetime even while busy. It has no DOM, no window, and no memory between wakes. Any variable you set in it is gone the next time it runs. Never put a long-running job there.
2. Only a top-level listener registration survives eviction. chrome.tabs.onRemoved.addListener at module scope wakes the worker when a tab closes. The same call made inside a message handler dies with the worker and silently never fires again. Everything the worker must remember between wakes belongs in chrome.storage.session.
3. The popup is a page, and it closes. Clicking anywhere outside it tears down its JavaScript and every port it opened. Work started in a popup dies with it; a message it sends while calling window.close() in the same breath is dropped if the worker was cold. Anything that takes longer than an instant belongs on a surface that outlives the click.
4. A content script runs in an isolated world. It shares the DOM with the page and shares nothing else — not window properties, not the page's own libraries. It also runs with the user's authenticated session, which is exactly why it is the security-sensitive part.

Choosing the surface

The rule that follows: the surface that OWNS a job must outlive the job. In practice that means an extension page for anything long, and a popup that does nothing but start it.

The ten things that bite

1. A bundled content script cannot return a value. Bundlers wrap output in (() => {…})(), whose completion value is undefined, so executeScript({files}) hands back undefined no matter what the source returns. Publish to a well-known global and poll for it — which also removes any deadline on the script. See references/injection-and-extraction.md.
2. activeTab covers one tab and is revoked on navigation. It is granted when the user invokes the extension, for that tab, until it navigates or closes. It does not cover a background tab you opened, and it does not survive the tab navigating. A background tab needs a real host permission.
3. chrome.permissions.request needs a user gesture — call it inside the click handler, not after an await. And not from a popup that the prompt will dismiss; use a real page.
4. A pinned tab cannot be in a tab group. They are mutually exclusive; pick one anchor.
5. chrome.tabs.group moves tabs to make the group contiguous. Create tabs adjacent to where the group will be, or the user watches their tab strip rearrange.
6. Tab-strip writes are refused while the user drags anything ("Tabs cannot be edited right now"). Catch every one, and debounce titles rather than writing per event.
7. fetch from an extension context sends cookies by default. Against your own API that means the browser's session beats the API key you attached. Use credentials: 'omit' when the key is the identity.
8. Any page can send your worker a message. Validate every field before it reaches atob, a Blob, or an API call. sender.tab and sender.id are the only things you did not get from the sender.
9. storage.sync has small per-item and total quotas and write-rate limits; storage.local is not encrypted; storage.session is cleared on browser restart and is the right home for short-lived cross-wake state. Pick deliberately.
10. SPAs are "complete" long before they have content. tab.status === 'complete' fires when the shell loads. Poll the page for real content and accept a short body only once it has stopped growing, or you will silently store empty shells.

Deep-dive references (load on demand)

• references/mv3-architecture.md — worker lifecycle and eviction, what may live there, the storage tiers and their quotas, the popup/worker message race, alarms, offscreen documents, MV2→MV3 migration.
• references/surfaces-and-ui.md — choosing and building each surface, real size constraints, theming without a toggle, and the accessibility rules that matter for a page that updates several times a second.
• references/tabs-and-groups.md — chrome.tabs / chrome.tabGroups / chrome.windows recipes: grouping, contiguity, drag-time refusals, debounced group titles, never stealing focus, and reaping tabs your extension orphaned.
• references/injection-and-extraction.md — chrome.scripting, the publish-and-poll contract, isolated worlds, waiting for an SPA to render, extracting page content, inlining assets, and size budgets.
• references/permissions-and-security.md — the permissions model end to end, activeTab semantics, optional host permissions, CSP, validating messages, handling credentials, and what store review actually rejects.
• references/long-running-work.md — who owns a long job, modelling its phases, pacing and rate limits, cancellation that actually cancels, honest progress and estimates, and keeping a long list rendering smoothly.
• references/build-and-test.md — bundling ES modules and IIFE content scripts together, build postconditions for properties unit tests cannot see, testing without a chrome stub, and CI.

Standards

• Every permission is justified in writing, in the manifest's neighbourhood or the README. Prefer optional_host_permissions requested at the moment of need over broad grants at install.
• Nothing long-running in the service worker. If a job can outlast a wake, it belongs on a page.
• No string-to-code, ever — no eval, no new Function, no javascript: URLs, no innerHTML built from page data. Lint for it; the store rejects for it.
• Every chrome.* call that can be refused is caught. Tab-strip mutations, permission requests, and messages to a tab that has navigated all fail routinely and none of them should end a job.
• Cosmetics are never load-bearing. A failed group, badge or title must not stop the work.
• A job says what it is doing. Silence during a multi-minute operation is a defect, not a cosmetic gap — the user cannot tell it from a hang.
• Test the pure logic, not the browser. Take narrow interfaces for the chrome.* calls you use so tests substitute a recorder; never monkeypatch a global chrome.

Anti-patterns to avoid

Universal work principles

• Read the platform's own error text before theorising; Chrome's extension errors are unusually precise ("Tabs cannot be edited right now", "Cannot access contents of the page").
• Load the unpacked build and use it before calling anything done. Unit tests cannot see the manifest, the bundler wrapper, the permission prompt, or the tab strip.
• chrome://extensions → Errors collects what the worker threw while nobody was watching; check it after every manual pass.