Skip to content

BROWSER_DISTRIBUTION.md

Latest commit

 

History

History
102 lines (82 loc) · 4.74 KB

BROWSER_DISTRIBUTION.md

File metadata and controls

102 lines (82 loc) · 4.74 KB
Raw

Browser Distribution

This document is the authoritative map between Ghostify's shared source, browser packages, store listings, and release responsibilities.

Supported Channels

Channel Runtime Manifest source Package command Publication state
Chrome Web Store Chromium MV3 service worker dist/manifest.json npm run package:extension Published
Microsoft Edge Add-ons Chromium MV3 service worker dist/manifest.json npm run package:extension Published
Firefox Browser Add-ons (AMO) Firefox MV3 background script dist/manifest.json plus browser-targets/firefox/manifest.overlay.json npm run package:firefox Published

Chrome Web Store and Microsoft Edge Add-ons use the same built package format, but they are independent listings. Their published versions, review states, release dates, and post-install verification evidence must be recorded separately. A release being live in one store does not prove it is live in the other.

Shared-Code Contract

src/ owns runtime behavior for every browser. build.js writes shared bundles and package assets to dist/. Browser targets must not fork or copy runtime modules. A browser-specific difference belongs in a manifest overlay, package script, narrowly gated static behavior, validator, or release document.

dist/manifest.json remains the Chromium manifest. The Firefox manifest is generated by combining it with browser-targets/firefox/manifest.overlay.json. Never commit a generated Firefox manifest from tmp/firefox-extension/.

Firefox Differences

The Firefox package deliberately differs in these fields and behaviors:

  • background.scripts loads background.js; Firefox does not run the Chromium background.service_worker declaration.
  • browser_specific_settings.gecko.id is the permanent AMO identity: ghostify@ghostify-extension.vercel.app.
  • strict_min_version is Firefox 140. This covers Ghostify's required MAIN-world and origin-fallback support and Mozilla's built-in data declaration system.
  • The Android compatibility floor is Firefox 142 because Mozilla introduced the same data-declaration manifest field there later. The AMO package supports Firefox desktop and Firefox for Android from their respective minimum versions.
  • data_collection_permissions.required is none.
  • The Firefox icon map intentionally keeps the compact 16 and 128 entries. Chromium also declares a 48 entry, whose PNG dimensions are validated before packaging.
  • The Firefox package retains the Ghostify website host permission so its popup uses the same dynamic status.json date, color, and update title as Chromium. The display-only privileged request uses no credentials, custom headers, query parameters, or body.
  • The Firefox popup omits Chromium-specific store rating links. The shared Chromium popup routes ratings to the Chrome Web Store in Chrome and the Microsoft Edge Add-ons listing in Edge.

Changing the Gecko ID after the first AMO submission would create a different extension identity and is prohibited. Changes to the minimum version, data declaration, status behavior, host permissions, or background environment require compatibility and privacy review.

Build And Validation

npm run build
npm run validate:extension
npm run validate:firefox
npm run lint:firefox
npm run test:package

Package commands:

npm run package:extension
npm run package:firefox

The Firefox command creates an AMO upload ZIP, reviewer source ZIP, and SHA-256 checksum for each. These files are release artifacts and must not be committed.

npm run ci is the combined local gate for all maintained browser targets. npm run ci:chromium and npm run ci:firefox are independent channel gates. The Chromium gate does not download or run Firefox tooling. CI runs the channel gates and creates their artifacts in separate prerequisite and packaging jobs, so a Firefox-only validation, lint, or packaging failure cannot suppress a valid Chromium artifact.

Release Ownership

  • Chromium release preparation follows RELEASE_CHECKLIST.md.
  • Firefox release preparation follows docs/FIREFOX_RELEASE_CHECKLIST.md.
  • docs/QA_FIXTURES.md remains authoritative for live Meta smoke evidence.
  • Store upload, legal declarations, signing, and reviewer correspondence remain external/manual actions until explicitly performed by the maintainer.
  • Public documentation must distinguish package readiness from an approved, live store listing.

The GitHub Release workflow remains gated on an approved Chrome Web Store version. A raw AMO upload ZIP is not a Mozilla-signed XPI and must not be presented as an installable public Firefox release.