Understand extension contexts

An extension is several JavaScript environments, not one page with universal access.

The popup exists only while open. A content script runs in a web page with an isolated JavaScript world but shared DOM. The extension service worker handles browser events and may stop when idle. They communicate with messages and shared extension storage.

Each context owns different work. The popup owns short-lived user interaction. The content script is the only project context that touches the host page DOM. The service worker owns browser events such as commands and installation, but it has no DOM and must survive being terminated between events.

Isolation is not a complete trust boundary. A content script cannot directly read the page’s JavaScript variables, yet both worlds can read and mutate the same DOM. Values taken from page markup are untrusted. Extension storage is shared across contexts by default, so do not place secrets there and assume the content script cannot read them.

Messages cross execution boundaries and should look like a small internal protocol. Storage crosses lifetime boundaries and should hold state needed after a popup closes or worker restarts. Neither mechanism turns one context into another.

Draw Page Notes with context lifetimes and arrows for popup → storage, popup → content script, command → service worker, and worker → content script. Annotate every arrow with its payload and mark which data originated on an untrusted page.