WebExtension architecture across browsers with Manifest V3

ShopTools AI retrieves store offers and tests available coupons on supported cart pages. Those tasks span different contexts: network data, extension controls and the retailer's DOM should not all belong to one process.

This is a reference architecture drawn from the project's source articles. It is not a map of every module in the current release or evidence that one package works in every browser. Verify platform capabilities separately.

Assign four distinct responsibilities

• The manifest declares permissions, entry points and allowed resources. Describe content-script access to pages separately from permission to call your API.
• The background layer retrieves the catalog, coordinates requests and stores preferences. It should not own the retailer's DOM.
• The content script locates permitted controls, observes totals and carries out the user's command. References to DOM nodes belong to the page context.
• The popup selects the store and presents state. Closing it should not destroy the only record of an unfinished operation.

State must survive a context stopping

Design MV3 background handlers to resume after a worker stops. Use process variables as an optimization, and persist information needed after restart with a schema version and an explicit validity period.

Separate response freshness from the stale fallback window. Coalesce identical requests with single flight. A quick cache read does not make an expired coupon current; eligibility and date filters still apply to cached records.

Match the retailer using its destination domain, not the tracker's address. Check the tab and store context before using a saved operation. When information is insufficient, end with an explicit failure rather than an endless loading state.

A shared core does not mean one archive

Matching rules, amount comparisons and message schemas can live in a shared core. Isolate browser API differences in thin adapters. A wrapper should settle an operation once, whether the underlying interface uses callbacks or promises.

Check capabilities rather than relying only on browser names. Do not turn an API failure into an empty successful response. Test background lifetime, permissions and packaging for each target platform.

For Safari, distinguish the container application from its extension. Installing the container, enabling the extension and granting site access are different stages. This does not establish that a particular package is published.

Build a verifiable release matrix

1. Record the source revision, shared-code version, platform manifest and identifiers. Track an application's build number separately.
2. Test updates from the previous package: settings need an explicit migration rule, while unknown data formats need a safe failure path.
3. On each platform, exercise popup opening, store detection, network failure, recovery after reload and denied page access.
4. Check long translated labels and operation without optional telemetry. Do not transfer a test result from one platform to another.

Keep server data from becoming executable code

In this reference design, executable logic stays in the package. Restrict remote configuration to validated data with local limits. Do not evaluate downloaded strings or load a remote script to repair a store integration.

A packaged archive, a successful local test and an update available to users are different outcomes. Before release, check current platform requirements, signing and publication status instead of relying on old instructions.