Bump to alpha2

Update test snapshots
Fix sandbox exports
2023-12-17 11:31:17 -06:00 · 2023-12-17 11:31:11 -06:00 · 2023-12-17 11:28:33 -06:00 · 2023-12-17 11:25:06 -06:00 · 2023-12-17 11:18:35 -06:00 · 2023-12-17 10:06:12 -06:00
166 changed files with 5552 additions and 10774 deletions
@@ -12,22 +12,14 @@ A clear and concise description of what the bug is.

 ### To Reproduce

-Share minimal reproduction. Examples of a minimal reproduction:
+Upload a ZIP or share a link to a repo representing the minimal reproduction. **_If you don't upload a minimal reproduction, you bug report will be closed._**

- PR with a failing test case
- ZIP file containing a minimal WXT project (be sure to include your lockfile!!)
+Steps to reproduce the behavior:

-> **_⚠️ If you don't upload a minimal reproduction, your issue will be closed until a reproduction is added._**
->
-> Why? https://antfu.me/posts/why-reproductions-are-required
-
-Steps to reproduce the bug using the reproduction:
-
-1. Install dependencies: `pnpm i`
-2. Start dev mode: `pnpm dev`
-3. Click this...
-4. Do that...
-5. Etc...
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error

 ### Expected behavior

@@ -4,7 +4,7 @@ runs:
  using: composite
  steps:
    - name: Setup PNPM
-      uses: pnpm/action-setup@v3
+      uses: pnpm/action-setup@v2
      with:
        version: 8
    - name: Setup NodeJS
@@ -9,7 +9,3 @@ updates:
    directory: '/' # Location of package manifests
    schedule:
      interval: 'monthly'
-  - package-ecosystem: 'github-actions'
-    directory: '/'
-    schedule:
-      interval: 'monthly'
@@ -14,7 +14,7 @@ jobs:
  publish:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - uses: docker/login-action@v3
        with:
@@ -5,14 +5,13 @@ on:
 jobs:
  validate:
    uses: './.github/workflows/validate.yml'
-    secrets: inherit

  publish:
    runs-on: ubuntu-22.04
    needs:
      - validate
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

@@ -11,8 +11,8 @@ jobs:
  sync:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v3
+      - uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v4
@@ -10,30 +10,30 @@ jobs:
  formatting:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - run: pnpm format:check
  lint:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - run: pnpm lint
  type-check:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - run: pnpm compile
  validate-demo:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
-      - run: pnpm tsc --noEmit
-        working-directory: demo
      - run: pnpm build:all
        working-directory: demo
+      - run: pnpm tsc --noEmit
+        working-directory: demo
      - run: pnpm wxt zip
        working-directory: demo
      - run: pnpm vitest run
@@ -41,17 +41,17 @@ jobs:
  tests:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - name: pnpm test:coverage
        run: pnpm test:coverage --reporter=default --reporter=hanging-process
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v3
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
  windows-tests:
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - run: pnpm test run
  template:
@@ -65,7 +65,7 @@ jobs:
          - vanilla
          - vue
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - run: pnpm pack
      - run: npm i
@@ -80,3 +80,6 @@ jobs:
        working-directory: templates/${{ matrix.template }}
      - run: pnpm build
        working-directory: templates/${{ matrix.template }}
+        env:
+          # Debug Vite 5's deprecated CJS support
+          VITE_CJS_TRACE: true
@@ -1,728 +1,5 @@
 # Changelog

-## v0.17.3
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.2...v0.17.3)
-
-### 🚀 Enhancements
-
- **storage:** Guarantee `storage.getItems` returns values in the same order as requested ([b5f4d8c](https://github.com/wxt-dev/wxt/commit/b5f4d8c))
-
-### 🩹 Fixes
-
- Content scripts crash when using `storage.defineItem` ([77e6d1f](https://github.com/wxt-dev/wxt/commit/77e6d1f))
- **storage:** Revert #478 and run migrations when item is defined and properly wait for migrations before allowing read/writes ([#487](https://github.com/wxt-dev/wxt/pull/487), [#478](https://github.com/wxt-dev/wxt/issues/478))
-
-## v0.17.2
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.1...v0.17.2)
-
-### 🩹 Fixes
-
- Don't use sub-dependency binaries directly ([#482](https://github.com/wxt-dev/wxt/pull/482))
-
-## v0.17.1
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.0...v0.17.1)
-
-### 🩹 Fixes
-
- Content scripts not loading in dev mode ([3fbbe2c](https://github.com/wxt-dev/wxt/commit/3fbbe2c))
-
-### 📖 Documentation
-
- Lots of small typo fixes ([#480](https://github.com/wxt-dev/wxt/pull/480))
-
-### ❤️ Contributors
-
- Leo Shklovskii ([@leos](https://github.com/leos))
-
-## v0.17.0
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.11...v0.17.0)
-
-### 🚀 Enhancements
-
- **storage:** ⚠️  Improved support for default values on storage items ([#477](https://github.com/wxt-dev/wxt/pull/477))
-
-### 🩹 Fixes
-
- **storage:** ⚠️  Only run migrations when the extension is updated ([#478](https://github.com/wxt-dev/wxt/pull/478))
- Improve dev mode for content scripts registered at runtime ([#474](https://github.com/wxt-dev/wxt/pull/474))
-
-### 📖 Documentation
-
- **storage:** Update docs ([91fc41c](https://github.com/wxt-dev/wxt/commit/91fc41c))
-
-#### ⚠️ Breaking Changes
-
-`v0.17.0` introduces several breaking changes to `wxt/storage`.
-
-First, if you were using `defineItem` with versioning and no default value, you will need to add `defaultValue: null` to the options and update the first type parameter:
-
-```ts
-// < 0.17
-const item = storage.defineItem<number>("local:count", {
-  version: ...,
-  migrations: ...,
-})
-
-// >= 0.17
-const item = storage.defineItem<number | null>("local:count", {
-  defaultValue: null,
-  version: ...,
-  migrations: ...,
-})
-```
-
-The `defaultValue` property is now required if passing in the second options argument. 
-
-If you exclude the second options argument, it will default to being nullable, as before.
-
-```ts
-const item: WxtStorageItem<number | null> = storage.defineItem<number>("local:count");
-const value: number | null = await item.getValue();
-```
-
-> If you don't use typescript, there aren't any breaking changes, this is just a type change.
-
-For storage items that are not nullable, the `watch` callback types has improved and will use the default value instead of `null` when the value is missing:
-
-```ts
-// >=0.17
-const item = storage.defineItem<number>("local:count", { defaultValue: 0 });
-item.watch((newValue: number | null, oldValue: number | null) => {
-  // ...
-});
-
-// >=0.17
-const item = storage.defineItem<number>("local:count", { defaultValue: 0 });
-item.watch((newValue: number, oldValue: number) => {
-  // ...
-});
-```
-
-You can also access the default value directly off the item:
-
-```ts
-console.log(item.defaultValue); // 0
-```
-
-The second breaking change is that migrations for versioned items only run when the extension is updated. Before, they were ran whenever the storage item was created, in any entrypoint (background, popup, content script, etc). Now, in v0.17, storage items will only run migrations when the `browser.runtime.onInstalled` event is fired with `reason = "update"` in the background. See the updated docs to make sure they run correctly: https://wxt.dev/guide/storage.html#running-migrations. TLDR: you need to import all storage items into the background entrypoint for the `onInstalled` hook to fire properly and thus run the migrations.
-
-To keep the old behavior, call the new `migrate` function to run migrations as soon as an item is defined:
-
-```ts
-const item = storage.defineItem(...);
-item.migrate();
-```
-
-## v0.16.11
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.10...v0.16.11)
-
-### 🩹 Fixes
-
- Output main JS file for HTML entrypoints to chunks directory ([#473](https://github.com/wxt-dev/wxt/pull/473))
-
-### 🏡 Chore
-
- **e2e:** Remove log ([4fda203](https://github.com/wxt-dev/wxt/commit/4fda203))
-
-### 🤖 CI
-
- Fix codecov warning in release workflow ([7c6973f](https://github.com/wxt-dev/wxt/commit/7c6973f))
- Upgrade `pnpm/action-setup` to v3 ([905bfc7](https://github.com/wxt-dev/wxt/commit/905bfc7))
-
-## v0.16.10
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.9...v0.16.10)
-
-### 🚀 Enhancements
-
- Customize when content scripts are registered, in the manifest or at runtime ([#471](https://github.com/wxt-dev/wxt/pull/471))
-
-### 🩹 Fixes
-
- Don't assume react when importing JSX entrypoints during build ([#470](https://github.com/wxt-dev/wxt/pull/470))
- Respect `configFile` option ([#472](https://github.com/wxt-dev/wxt/pull/472))
-
-## v0.16.9
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.8...v0.16.9)
-
-### 🚀 Enhancements
-
- Support setting side panel options in HTML file ([#468](https://github.com/wxt-dev/wxt/pull/468))
-
-### 🩹 Fixes
-
- Fix order of ShadowRootUI hooks calling ([#459](https://github.com/wxt-dev/wxt/pull/459))
-
-### 📖 Documentation
-
- Add wrapper div to react's `createShadowRootUi` example ([bc24ea4](https://github.com/wxt-dev/wxt/commit/bc24ea4))
-
-### 🏡 Chore
-
- Simplify entrypoint types ([#464](https://github.com/wxt-dev/wxt/pull/464))
-
-### ❤️ Contributors
-
- Okou ([@ookkoouu](https://github.com/ookkoouu))
-
-## v0.16.8
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.7...v0.16.8)
-
-### 🩹 Fixes
-
- Watch files outside project root during development ([#454](https://github.com/wxt-dev/wxt/pull/454))
-
-### 📖 Documentation
-
- Add loading and error states for "Who's using WXT" section ([447a48f](https://github.com/wxt-dev/wxt/commit/447a48f))
-
-## v0.16.7
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.6...v0.16.7)
-
-### 🚀 Enhancements
-
- Generate ESLint globals file for auto-imports ([#450](https://github.com/wxt-dev/wxt/pull/450))
-
-### 🔥 Performance
-
- Upgrade Vite to 5.1 ([#452](https://github.com/wxt-dev/wxt/pull/452))
-
-### 📖 Documentation
-
- Add section about dev mode differences ([a0d1643](https://github.com/wxt-dev/wxt/commit/a0d1643))
- Remove anchor from content script ui examples ([87a62a1](https://github.com/wxt-dev/wxt/commit/87a62a1))
-
-### 🏡 Chore
-
- **e2e:** Use `wxt prepare` instead of `wxt build` when possible to speed up E2E tests ([#451](https://github.com/wxt-dev/wxt/pull/451))
-
-## v0.16.6
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.5...v0.16.6)
-
-### 🚀 Enhancements
-
- Add option to customize the analysis artifacts output ([#431](https://github.com/wxt-dev/wxt/pull/431))
-
-### 🩹 Fixes
-
- Use `insertBefore` on mounting content script UI ([ba85fdf](https://github.com/wxt-dev/wxt/commit/ba85fdf))
-
-### 💅 Refactors
-
- Use `Element.prepend` on mounting UI ([295f860](https://github.com/wxt-dev/wxt/commit/295f860))
-
-### 📖 Documentation
-
- Fix `createShadowRootUi` unmount calls ([946072f](https://github.com/wxt-dev/wxt/commit/946072f))
-
-### 🏡 Chore
-
- Enable skipped test since it works now ([6b8dfdf](https://github.com/wxt-dev/wxt/commit/6b8dfdf))
-
-### ❤️ Contributors
-
- Lionelhorn ([@Lionelhorn](https://github.com/Lionelhorn))
- Okou ([@ookkoouu](https://github.com/ookkoouu))
-
-## v0.16.5
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.4...v0.16.5)
-
-### 🩹 Fixes
-
- Support node 20 when running `wxt submit` ([e835502](https://github.com/wxt-dev/wxt/commit/e835502))
-
-### 📖 Documentation
-
- Remove "coming soon" from automated publishing feature ([2b374b9](https://github.com/wxt-dev/wxt/commit/2b374b9))
-
-## v0.16.4
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.3...v0.16.4)
-
-### 🚀 Enhancements
-
- Automatically convert MV3 `web_accessible_resources` to MV2 ([#423](https://github.com/wxt-dev/wxt/pull/423))
- Add option to customize the analysis output filename ([#426](https://github.com/wxt-dev/wxt/pull/426))
-
-### 🩹 Fixes
-
- Don't use immer for `transformManifest` ([#424](https://github.com/wxt-dev/wxt/pull/424))
- Exclude analysis files from the build summary ([#425](https://github.com/wxt-dev/wxt/pull/425))
-
-### 🏡 Chore
-
- Fix fake path in test data generator ([d0f1c70](https://github.com/wxt-dev/wxt/commit/d0f1c70))
-
-## v0.16.3
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.2...v0.16.3)
-
-### 🚀 Enhancements
-
- Hooks ([#419](https://github.com/wxt-dev/wxt/pull/419))
-
-### 🩹 Fixes
-
- **init:** Use `ungh` to prevent rate limits when loading templates ([37ad2c7](https://github.com/wxt-dev/wxt/commit/37ad2c7))
-
-### 📖 Documentation
-
- Fix typo of intuitive ([#415](https://github.com/wxt-dev/wxt/pull/415))
- Fix typo of opinionated ([#416](https://github.com/wxt-dev/wxt/pull/416))
-
-### 🏡 Chore
-
- Add dependabot for github actions ([#404](https://github.com/wxt-dev/wxt/pull/404))
- **deps-dev:** Bump happy-dom from 12.10.3 to 13.3.8 ([#411](https://github.com/wxt-dev/wxt/pull/411))
- **deps-dev:** Bump typescript from 5.3.2 to 5.3.3 ([#409](https://github.com/wxt-dev/wxt/pull/409))
- Register global `wxt` instance ([#418](https://github.com/wxt-dev/wxt/pull/418))
-
-### ❤️ Contributors
-
- Chen Hua ([@hcljsq](https://github.com/hcljsq))
- Florian Metz ([@Timeraa](http://github.com/Timeraa))
-
-## v0.16.2
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.1...v0.16.2)
-
-### 🩹 Fixes
-
- Don't crash background service worker when using `import.meta.url` ([#402](https://github.com/wxt-dev/wxt/pull/402))
-
-## v0.16.1
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.0...v0.16.1)
-
-### 🩹 Fixes
-
- Don't require config to run `wxt submit init` ([9318346](https://github.com/wxt-dev/wxt/commit/9318346))
-
-### 📖 Documentation
-
- Add premid extension to homepage ([#399](https://github.com/wxt-dev/wxt/pull/399))
-
-### 🏡 Chore
-
- **templates:** Upgrade to wxt `^0.16.0` ([f0b2a12](https://github.com/wxt-dev/wxt/commit/f0b2a12))
-
-### ❤️ Contributors
-
- Florian Metz ([@Timeraa](http://github.com/Timeraa))
-
-## v0.16.0
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.4...v0.16.0)
-
-### 🚀 Enhancements
-
- ⚠️  ESM background support ([#398](https://github.com/wxt-dev/wxt/pull/398))
-
-### 📖 Documentation
-
- Document how to opt into ESM ([1e12ce2](https://github.com/wxt-dev/wxt/commit/1e12ce2))
-
-### 🏡 Chore
-
- **deps-dev:** Bump lint-staged from 15.2.0 to 15.2.1 ([#395](https://github.com/wxt-dev/wxt/pull/395))
- **deps-dev:** Bump p-map from 7.0.0 to 7.0.1 ([#396](https://github.com/wxt-dev/wxt/pull/396))
- **deps-dev:** Bump @vitest/coverage-v8 from 1.0.1 to 1.2.2 ([#397](https://github.com/wxt-dev/wxt/pull/397))
-
-#### ⚠️ Breaking Changes
-
-In [#398](https://github.com/wxt-dev/wxt/pull/398), HTML pages' JS entrypoints in the output directory have been moved. Unless you're doing some kind of post-build work referencing files, you don't have to make any changes.
-
- Before:
-   ```
-   .output/
-     <target>/
-       chunks/
-         some-shared-chunk-<hash>.js
-         popup-<hash>.js
-       popup.html
-   ```
- After:
-   ```
-   .output/
-     <target>/
-       chunks/
-         some-shared-chunk-<hash>.js
-       popup.html
-       popup.js
-   ```
-
-This effects all HTML files, not just the Popup. The hash has been removed, and it's been moved to the root of the build target folder, not inside the `chunks/` directory. Moving files like this has not historically increased review times or triggered in-depth reviews when submitting updates to the stores.
-
-## v0.15.4
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.3...v0.15.4)
-
-### 🩹 Fixes
-
- **submit:** Load `.env.submit` automatically when running `wxt submit` and `wxt submit init` ([#391](https://github.com/wxt-dev/wxt/pull/391))
-
-## v0.15.3
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.2...v0.15.3)
-
-### 🩹 Fixes
-
- **dev:** Reload `<name>/index.html` entrypoints properly on save ([#390](https://github.com/wxt-dev/wxt/pull/390))
-
-## v0.15.2
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.1...v0.15.2)
-
-### 🚀 Enhancements
-
- Add `submit` command ([#370](https://github.com/wxt-dev/wxt/pull/370))
-
-### 🩹 Fixes
-
- **dev:** Resolve `script` and `link` aliases ([#387](https://github.com/wxt-dev/wxt/pull/387))
-
-### ❤️ Contributors
-
- Nenad Novaković ([@dvlden](https://github.com/dvlden))
-
-## v0.15.1
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.0...v0.15.1)
-
-### 🚀 Enhancements
-
- Allow passing custom preferences to chrome, enabling dev mode on `chrome://extensions` and allowing content script sourcemaps automatically ([#384](https://github.com/wxt-dev/wxt/pull/384))
-
-### 🩹 Fixes
-
- **security:** Upgrade to vite@5.0.12 to resolve CVE-2024-23331 ([39b76d3](https://github.com/wxt-dev/wxt/commit/39b76d3))
-
-### 📖 Documentation
-
- Fixed doc errors on the guide/extension-api page ([#383](https://github.com/wxt-dev/wxt/pull/383))
-
-### 🏡 Chore
-
- Fix vite version conflicts in demo extension ([98d2792](https://github.com/wxt-dev/wxt/commit/98d2792))
-
-### ❤️ Contributors
-
- 0x7a7a ([@0x7a7a](https://github.com/0x7a7a))
-
-## v0.15.0
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.7...v0.15.0)
-
-### 🚀 Enhancements
-
- **zip:** ⚠️  Add `includeSources` and rename `ignoredSources` to `excludeSources` ([#378](https://github.com/wxt-dev/wxt/pull/378))
-
-### 🩹 Fixes
-
- Generate missing sourcemap in `wxt:unimport` plugin ([#381](https://github.com/wxt-dev/wxt/pull/381))
- ⚠️  Move browser constants to `import.meta.env` ([#380](https://github.com/wxt-dev/wxt/pull/380))
- Enable inline sourcemaps by default during development ([#382](https://github.com/wxt-dev/wxt/pull/382))
-
-### 📖 Documentation
-
- Fix typo ([f9718a1](https://github.com/wxt-dev/wxt/commit/f9718a1))
-
-### 🏡 Chore
-
- Update contributor docs ([eb758bd](https://github.com/wxt-dev/wxt/commit/eb758bd))
-
-#### ⚠️ Breaking Changes
-
-Renamed `zip.ignoredSources` to `zip.excludeSources` in [#378](https://github.com/wxt-dev/wxt/pull/378)
-
-Renamed undocumented constants for detecting the build config at runtime in [#380](https://github.com/wxt-dev/wxt/pull/380). Now documented here: https://wxt.dev/guide/multiple-browsers.html#runtime
-
- `__BROWSER__` &rarr; `import.meta.env.BROWSER`
- `__COMMAND__` &rarr; `import.meta.env.COMMAND`
- `__MANIFEST_VERSION__` &rarr; `import.meta.env.MANIFEST_VERSION`
- `__IS_CHROME__` &rarr; `import.meta.env.CHROME`
- `__IS_FIREFOX__` &rarr; `import.meta.env.FIREFOX`
- `__IS_SAFARI__` &rarr; `import.meta.env.SAFARI`
- `__IS_EDGE__` &rarr; `import.meta.env.EDGE`
- `__IS_OPERA__` &rarr; `import.meta.env.OPERA`
-
-### ❤️ Contributors
-
- Nenad Novaković ([@dvlden](https://github.com/dvlden))
-
-## v0.14.7
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.6...v0.14.7)
-
-### 🩹 Fixes
-
- Improve error messages when importing and building entrypoints ([3b63a51](https://github.com/wxt-dev/wxt/commit/3b63a51))
- **storage:** Throw better error message when importing outside a extension environment ([35865ad](https://github.com/wxt-dev/wxt/commit/35865ad))
- Upgrade `web-ext-run` ([62ecb6f](https://github.com/wxt-dev/wxt/commit/62ecb6f))
-
-### 📖 Documentation
-
- Add `matches` to content script examples ([dab8efa](https://github.com/wxt-dev/wxt/commit/dab8efa))
- Fix incorrect sample code ([#372](https://github.com/wxt-dev/wxt/pull/372))
- Document defined constants for the build target ([68874e6](https://github.com/wxt-dev/wxt/commit/68874e6))
- Add missing `await` to `createShadowRootUi` examples ([fc45c37](https://github.com/wxt-dev/wxt/commit/fc45c37))
-
-### ❤️ Contributors
-
- 東奈比 ([@dongnaebi](http://github.com/dongnaebi))
-
-## v0.14.6
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.5...v0.14.6)
-
-### 🚀 Enhancements
-
- Restart dev mode when saving config ([#365](https://github.com/wxt-dev/wxt/pull/365))
- Add basic validation for entrypoint options ([#368](https://github.com/wxt-dev/wxt/pull/368))
-
-### 🩹 Fixes
-
- Add subdependency bin directory so `wxt build --analyze` works with PNPM ([#363](https://github.com/wxt-dev/wxt/pull/363))
- Sort build output files naturally ([#364](https://github.com/wxt-dev/wxt/pull/364))
-
-### 🤖 CI
-
- Check for type errors in demo before building ([4b005b4](https://github.com/wxt-dev/wxt/commit/4b005b4))
-
-## v0.14.5
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.4...v0.14.5)
-
-### 🚀 Enhancements
-
- Add `dev.reloadCommand` config ([#362](https://github.com/wxt-dev/wxt/pull/362))
-
-### 🩹 Fixes
-
- Disable reload dev command when 4 commands are already registered ([#361](https://github.com/wxt-dev/wxt/pull/361))
-
-## v0.14.4
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.3...v0.14.4)
-
-### 🩹 Fixes
-
- Allow requiring built-in node modules from ESM CLI ([#356](https://github.com/wxt-dev/wxt/pull/356))
-
-### 🏡 Chore
-
- Add unit tests for passing flags via the CLI ([#354](https://github.com/wxt-dev/wxt/pull/354))
-
-## v0.14.3
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.2...v0.14.3)
-
-### 🩹 Fixes
-
- Make `getArrayFromFlags` result can be undefined ([#352](https://github.com/wxt-dev/wxt/pull/352))
-
-### ❤️ Contributors
-
- Yuns ([@yunsii](http://github.com/yunsii))
-
-## v0.14.2
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.1...v0.14.2)
-
-### 🚀 Enhancements
-
- Add `filterEntrypoints` option to speed up development ([#344](https://github.com/wxt-dev/wxt/pull/344))
-
-### 🔥 Performance
-
- Only call `findEntrypoint` once per build ([#342](https://github.com/wxt-dev/wxt/pull/342))
-
-### 🩹 Fixes
-
- Improve error message and document use of imported variables outside an entrypoint's `main` function ([#346](https://github.com/wxt-dev/wxt/pull/346))
- Allow `browser.runtime.getURL` to include hashes and query params for HTML paths ([#350](https://github.com/wxt-dev/wxt/pull/350))
-
-### 📖 Documentation
-
- Fix typos and outdated ui function usage ([#347](https://github.com/wxt-dev/wxt/pull/347))
-
-### 🏡 Chore
-
- Update templates to `^0.14.0` ([70a4961](https://github.com/wxt-dev/wxt/commit/70a4961))
- Fix typo in function name ([a329e24](https://github.com/wxt-dev/wxt/commit/a329e24))
-
-### ❤️ Contributors
-
- Yuns ([@yunsii](http://github.com/yunsii))
- Armin
-
-## v0.14.1
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.0...v0.14.1)
-
-### 🩹 Fixes
-
- Use `Alt+R`/`Opt+R` to reload extension during development ([b6ab7a9](https://github.com/wxt-dev/wxt/commit/b6ab7a9))
-
-## v0.14.0
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.5...v0.14.0)
-
-### 🚀 Enhancements
-
- ⚠️  Refactor content script UI functions and add helper for "integrated" UIs ([#333](https://github.com/wxt-dev/wxt/pull/333))
-
-#### ⚠️ Breaking Changes
-
-`createContentScriptUi` and `createContentScriptIframe`, and some of their options, have been renamed:
-
- `createContentScriptUi({ ... })` &rarr; `createShadowRootUi({ ... })`
- `createContentScriptIframe({ ... })` &rarr; `createIframeUi({ ... })`
- `type: "inline" | "overlay" | "modal"` has been changed to `position: "inline" | "overlay" | "modal"`
- `onRemove` is now called ***before*** the UI is removed from the DOM, previously it was called after the UI was removed
- `mount` option has been renamed to `onMount`, to better match the related option, `onRemove`.
-
-## v0.13.5
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.4...v0.13.5)
-
-### 🩹 Fixes
-
- Strip path from `web_accessible_resources[0].matches` ([#332](https://github.com/wxt-dev/wxt/pull/332))
-
-### 📖 Documentation
-
- Add section about customizing other browser options during development ([8683bd4](https://github.com/wxt-dev/wxt/commit/8683bd4))
-
-### 🏡 Chore
-
- Update bug report template ([9a2cc18](https://github.com/wxt-dev/wxt/commit/9a2cc18))
-
-## v0.13.4
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.3...v0.13.4)
-
-### 🩹 Fixes
-
- Disable minification during development ([b7cdf15](https://github.com/wxt-dev/wxt/commit/b7cdf15))
-
-### 🏡 Chore
-
- Use `const` instead of `let` ([2770974](https://github.com/wxt-dev/wxt/commit/2770974))
-
-## v0.13.3
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.2...v0.13.3)
-
-### 🚀 Enhancements
-
- **DX:** Add `ctrl+E`/`cmd+E` shortcut to reload extension during development ([#322](https://github.com/wxt-dev/wxt/pull/322))
-
-### 🏡 Chore
-
- **deps-dev:** Bump tsx from 4.6.2 to 4.7.0 ([#320](https://github.com/wxt-dev/wxt/pull/320))
- **deps-dev:** Bump prettier from 3.1.0 to 3.1.1 ([#318](https://github.com/wxt-dev/wxt/pull/318))
- **deps-dev:** Bump vitepress from 1.0.0-rc.31 to 1.0.0-rc.34 ([#316](https://github.com/wxt-dev/wxt/pull/316))
- Refactor manifest generation E2E tests to unit tests ([#323](https://github.com/wxt-dev/wxt/pull/323))
-
-## v0.13.2
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.1...v0.13.2)
-
-### 🚀 Enhancements
-
- Add `isolateEvents` option to `createContentScripUi` ([#313](https://github.com/wxt-dev/wxt/pull/313))
-
-### 📖 Documentation
-
- Remove duplicate `entrypoints/` path ([76e63e2](https://github.com/wxt-dev/wxt/commit/76e63e2))
- Update unlisted pages/scripts description ([c99a281](https://github.com/wxt-dev/wxt/commit/c99a281))
- Update content script entrypoint docs ([1360eb7](https://github.com/wxt-dev/wxt/commit/1360eb7))
- Add example for setting up custom panels/panes in devtools ([#308](https://github.com/wxt-dev/wxt/pull/308))
- Use example tags to automate relevant example lists ([#311](https://github.com/wxt-dev/wxt/pull/311))
-
-### 🏡 Chore
-
- Update templates to `^0.13.0` ([#309](https://github.com/wxt-dev/wxt/pull/309))
- Upgrade template dependencies ([#310](https://github.com/wxt-dev/wxt/pull/310))
- Re-enable coverage ([#312](https://github.com/wxt-dev/wxt/pull/312))
-
-### ❤️ Contributors
-
- 冯不游
-
-## v0.13.1
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.0...v0.13.1)
-
-### 🩹 Fixes
-
- **storage:** Support multiple `:` characters in storage keys ([#303](https://github.com/wxt-dev/wxt/pull/303))
- Ship `vite/client` types internally for proper resolution using PNPM ([#304](https://github.com/wxt-dev/wxt/pull/304))
-
-### 📖 Documentation
-
- Reorder guide ([6421ab3](https://github.com/wxt-dev/wxt/commit/6421ab3))
- General fixes and improvements ([2ad099b](https://github.com/wxt-dev/wxt/commit/2ad099b))
-
-### 🏡 Chore
-
- Update `scripts/build.ts` show current build step in progress, not completed count ([#306](https://github.com/wxt-dev/wxt/pull/306))
-
-## v0.13.0
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.5...v0.13.0)
-
-### 🚀 Enhancements
-
- ⚠️  New `wxt/storage` APIs ([#300](https://github.com/wxt-dev/wxt/pull/300))
-
-#### ⚠️ Breaking Changes
-
- `wxt/storage` no longer relies on [`unstorage`](https://www.npmjs.com/package/unstorage). Some `unstorage` APIs, like `prefixStorage`, have been removed, while others, like `snapshot`, are methods on the new `storage` object. Most of the standard usage remains the same. See https://wxt.dev/guide/storage and https://wxt.dev/api/wxt/storage/ for more details ([#300](https://github.com/wxt-dev/wxt/pull/300))
-
-## v0.12.5
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.4...v0.12.5)
-
-### 🩹 Fixes
-
- Correct import in dev-only, noop background ([#298](https://github.com/wxt-dev/wxt/pull/298))
-
-## v0.12.4
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.3...v0.12.4)
-
-### 🩹 Fixes
-
- Disable Vite CJS warnings ([#296](https://github.com/wxt-dev/wxt/pull/296))
-
-## v0.12.3
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.2...v0.12.3)
-
-### 🩹 Fixes
-
- Correctly mock `webextension-polyfill` for Vitest ([#294](https://github.com/wxt-dev/wxt/pull/294))
-
-## v0.12.2
-
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.1...v0.12.2)
-
-### 🚀 Enhancements
-
- Support PNPM without hoisting dependencies ([#291](https://github.com/wxt-dev/wxt/pull/291))
-
 ## v0.12.1

 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.0...v0.12.1)
@@ -951,7 +228,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38

 ### 🏡 Chore

- Remove whitespace from generated `.wxt` files ([#211](https://github.com/wxt-dev/wxt/pull/211))
+- Remove whitespace from genearted `.wxt` files ([#211](https://github.com/wxt-dev/wxt/pull/211))
 - Upgrade templates to `wxt@^0.9.0` ([#214](https://github.com/wxt-dev/wxt/pull/214))
 - Update Vite dependency range to `^4.0.0 || ^5.0.0-0` ([f1e8084](https://github.com/wxt-dev/wxt/commit/f1e8084be89e512dde441b9197a99183c497f67d))

@@ -1459,8 +736,8 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - **deps-dev:** Bump vitest from 0.34.1 to 0.34.3 ([#99](https://github.com/wxt-dev/wxt/pull/99))
 - Increase E2E test timeout because GitHub Actions Window runner is slow ([2a0842b](https://github.com/wxt-dev/wxt/commit/2a0842b))
 - **deps-dev:** Bump vitepress from 1.0.0-rc.4 to 1.0.0-rc.10 ([#96](https://github.com/wxt-dev/wxt/pull/96))
- Fix test watcher restarting indefinitely ([2c7922c](https://github.com/wxt-dev/wxt/commit/2c7922c))
- Remove explicit icon config from templates ([93bfee0](https://github.com/wxt-dev/wxt/commit/93bfee0))
+- Fix test watcher restarting indefinetly ([2c7922c](https://github.com/wxt-dev/wxt/commit/2c7922c))
+- Remove explict icon config from templates ([93bfee0](https://github.com/wxt-dev/wxt/commit/93bfee0))
 - Use import aliases in Vue template ([#104](https://github.com/wxt-dev/wxt/pull/104))

 #### ⚠️ Breaking Changes
@@ -1520,7 +797,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - Branding and logo ([#60](https://github.com/wxt-dev/wxt/pull/60))
 - Simplify binary setup ([#62](https://github.com/wxt-dev/wxt/pull/62))
 - Add Solid template ([#63](https://github.com/wxt-dev/wxt/pull/63))
- Increase E2E test timeout to fix flakey test ([dfe424f](https://github.com/wxt-dev/wxt/commit/dfe424f))
+- Increate E2E test timeout to fix flakey test ([dfe424f](https://github.com/wxt-dev/wxt/commit/dfe424f))

 ### 🤖 CI

@@ -1796,7 +1073,7 @@ Initial release of WXT. Full support for production builds and initial toolkit f
 - Export and bootstrap the `/client` package ([5b07c95](https://github.com/wxt-dev/wxt/commit/5b07c95))
 - Resolve entrypoints based on filesystem ([a63f061](https://github.com/wxt-dev/wxt/commit/a63f061))
 - Separate output directories for each browser/manifest version ([f09ffbb](https://github.com/wxt-dev/wxt/commit/f09ffbb))
- Build entrypoints and output `manifest.json` ([1e7c738](https://github.com/wxt-dev/wxt/commit/1e7c738))
+- Build entrypoints and output `manfiest.json` ([1e7c738](https://github.com/wxt-dev/wxt/commit/1e7c738))
 - Automatically add CSS files to content scripts ([047ce04](https://github.com/wxt-dev/wxt/commit/047ce04))
 - Download and bundle remote URL imports ([523c7df](https://github.com/wxt-dev/wxt/commit/523c7df))
 - Generate type declarations and config for project types and auto-imports ([21debad](https://github.com/wxt-dev/wxt/commit/21debad))
@@ -57,17 +57,9 @@ pnpm test
 pnpm docs:dev
 ```

-## Updating Docs
-
-Documentation is written with VitePress, and is located in the `docs/` directory.
-
-The API reference is generated from JSDoc comments in the source code. If there's a typo or change you want to make in there, you'll need to update the source code instead of a file in the `docs/` directory.
-
 ## Testing

-WXT has unit and E2E tests. When making a change or adding a feature, make sure to update the tests or add new ones, if they exist.
-
-> If they don't exist, feel free to create them, but that's a lot for a one-time contributor. A maintainer might add them to your PR though.
+WXT has unit and E2E tests. When making a change or adding a feature, make sure to update the tests or add new ones.

 To run tests for a specific file, add the filename at the end of the test command:

@@ -108,7 +100,7 @@ Then run `npm i` again.
 To add a template, copy the vanilla template and give it a new name.

 ```sh
-cp -r templates/vanilla templates/<new-template-name>
+cp -r templates/vailla templates/<new-template-name>
 ```

 That's it. Once your template is merged, it will be available inside `wxt init` immediately. You don't need to release a new version of WXT to release a new template.
@@ -9,8 +9,9 @@
  <a href="https://www.npmjs.com/package/wxt" target="_blank"><img alt="npm" src="https://img.shields.io/npm/dm/wxt?labelColor=black&color=%234fa048"></a>
  <span> </span>
  <a href="https://github.com/wxt-dev/wxt/blob/main/LICENSE" target="_blank"><img alt="NPM" src="https://img.shields.io/npm/l/wxt?labelColor=black&color=%234fa048"></a>
-  <span> </span>
-  <a href="https://codecov.io/github/wxt-dev/wxt" target="_blank"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/wxt-dev/wxt?labelColor=black&color=%234fa048"></a>
+  <!-- Hide code coverage while it's broken -->
+  <!-- <span> </span>
+  <a href="https://codecov.io/github/wxt-dev/wxt" target="_blank"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/wxt-dev/wxt?labelColor=black&color=%234fa048"></a> -->
 </p>

 <p align="center">
@@ -55,11 +56,14 @@ Or see the [installation guide](https://wxt.dev/guide/installation.html) to get
 - 📂 File based entrypoints
 - 🚔 TypeScript
 - 🦾 Auto-imports
- 🤖 Automated publishing
+- ⬇️ Download and bundle remote URL imports
 - 🎨 Frontend framework agnostic: works with Vue, React, Svelte, etc
 - 🖍️ Quickly bootstrap a new project
 - 📏 Bundle analysis
- ⬇️ Download and bundle remote URL imports
+
+### Coming Soon
+
+- 🤖 Automated publishing

 ## Contributors

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-/**
- * A alias around `publish-extension` that is always installed on the path without having to install
- * `publish-browser-extension` as a direct dependency (like for PNPM, which doesn't link
- * sub-dependency binaries to "node_modules/.bin")
- */
-require('publish-browser-extension/cli');
@@ -19,11 +19,13 @@
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
-    "vitest": "^1.2.2"
+    "vitest": "^0.34.6",
+    "webextension-polyfill": "^0.10.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.34",
    "@types/react-dom": "^18.2.14",
+    "@types/webextension-polyfill": "^0.10.5",
    "sass": "^1.69.5",
    "wxt": "workspace:*"
  }
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import background from '../background';

 browser.i18n.getMessage = () => 'fake-message';
@@ -7,10 +7,6 @@ const logMock = vi.fn();
 console.log = logMock;

 describe('Background Entrypoint', () => {
-  beforeEach(() => {
-    fakeBrowser.reset();
-  });
-
  it("should log the extenion's runtime ID", () => {
    const id = 'some-id';
    fakeBrowser.runtime.id = id;
@@ -19,11 +15,4 @@ describe('Background Entrypoint', () => {

    expect(logMock).toBeCalledWith(id);
  });
-
-  it('should set the start time in storage', async () => {
-    background.main();
-    await new Promise((res) => setTimeout(res));
-
-    expect(await storage.getItem('session:startTime')).toBeDefined();
-  });
 });
@@ -1,42 +1,33 @@
 import messages from 'public/_locales/en/messages.json';

-export default defineBackground({
-  // type: 'module',
+export default defineBackground(() => {
+  console.log(browser.runtime.id);
+  logId();
+  console.log({
+    browser: __BROWSER__,
+    chrome: __IS_CHROME__,
+    firefox: __IS_FIREFOX__,
+    manifestVersion: __MANIFEST_VERSION__,
+    messages,
+  });

-  main() {
-    console.log(browser.runtime.id);
-    logId();
-    console.log({
-      url: import.meta.url,
-      browser: import.meta.env.BROWSER,
-      chrome: import.meta.env.CHROME,
-      firefox: import.meta.env.FIREFOX,
-      manifestVersion: import.meta.env.MANIFEST_VERSION,
-      messages,
-    });
+  // @ts-expect-error: should only accept entrypoints or public assets
+  browser.runtime.getURL('/');
+  browser.runtime.getURL('/background.js');
+  browser.runtime.getURL('/icon/128.png');

-    // @ts-expect-error: should only accept entrypoints or public assets
-    browser.runtime.getURL('/');
-    browser.runtime.getURL('/background.js');
-    browser.runtime.getURL('/icon/128.png');
-    browser.runtime.getURL('/example.html#hash');
-    browser.runtime.getURL('/example.html?query=param');
-    // @ts-expect-error: should only allow hashes/query params on HTML files
-    browser.runtime.getURL('/icon-128.png?query=param');
+  // @ts-expect-error: should only accept known message names
+  browser.i18n.getMessage('test');
+  browser.i18n.getMessage('prompt_for_name');
+  browser.i18n.getMessage('hello', 'Aaron');
+  browser.i18n.getMessage('bye', ['Aaron']);
+  browser.i18n.getMessage('@@extension_id');

-    // @ts-expect-error: should only accept known message names
-    browser.i18n.getMessage('test');
-    browser.i18n.getMessage('prompt_for_name');
-    browser.i18n.getMessage('hello', 'Aaron');
-    browser.i18n.getMessage('bye', ['Aaron']);
-    browser.i18n.getMessage('@@extension_id');
+  console.log('WXT MODE:', {
+    MODE: import.meta.env.MODE,
+    DEV: import.meta.env.DEV,
+    PROD: import.meta.env.PROD,
+  });

-    console.log('WXT MODE:', {
-      MODE: import.meta.env.MODE,
-      DEV: import.meta.env.DEV,
-      PROD: import.meta.env.PROD,
-    });
-
-    storage.setItem('session:startTime', Date.now());
-  },
+  storage.setItem('session:startTime', Date.now());
 });
@@ -2,9 +2,9 @@ export default defineContentScript({
  matches: ['*://*.google.com/*'],

  main(ctx) {
-    const ui = createIframeUi(ctx, {
+    const ui = createContentScriptIframe(ctx, {
      page: '/iframe-src.html',
-      position: 'overlay',
+      type: 'overlay',
      anchor: 'form[action="/search"]',
    });
    ui.mount();
@@ -6,12 +6,12 @@ export default defineContentScript({
  cssInjectionMode: 'ui',

  async main(ctx) {
-    const ui = await createShadowRootUi(ctx, {
+    const ui = await createContentScriptUi(ctx, {
      name: 'demo-ui',
-      position: 'inline',
+      type: 'inline',
      append: 'before',
      anchor: 'form[role=search]',
-      onMount: (container) => {
+      mount: (container) => {
        const app = document.createElement('div');
        app.textContent = 'Custom content script UI';
        container.append(app);
@@ -1,34 +0,0 @@
-<script lang="ts" setup>
-import { ref, onMounted, computed } from 'vue';
-
-const props = defineProps<{
-  tag?: string;
-}>();
-
-const examples = ref();
-onMounted(async () => {
-  const res = await fetch(
-    'https://raw.githubusercontent.com/wxt-dev/wxt-examples/main/examples.json',
-  );
-  examples.value = await res.json();
-});
-
-const filteredExamples = computed(() => {
-  if (props.tag == null) return examples.value;
-
-  return examples.value.filter((example) => {
-    return example.tags?.includes(props.tag);
-  });
-});
-</script>
-
-<template>
-  <ul>
-    <li v-if="examples == null">Loading...</li>
-    <template v-else>
-      <li v-for="example of filteredExamples">
-        <a :href="example.url" target="_blank">{{ example.name }}</a>
-      </li>
-    </template>
-  </ul>
-</template>
@@ -5,10 +5,6 @@ import useListExtensionDetails, {
 } from '../composables/useListExtensionDetails';

 // Add extension IDs here. Order doesn't matter, will be sorted by weekly active users
-// During the transition from chrome.google.com/webstore to
-// chromewebstore.google.com, queue.wxt.dev might return null for your
-// extension. If it does, use "<slug>/<id>" instead of just the ID. The slug
-// can be retrieved from the URL of the item on chromewebstore.google.com
 const chromeExtensionIds = [
  'ocfdgncpifmegplaglcnglhioflaimkd', // GitHub: Better Line Counts
  'mgmdkjcljneegjfajchedjpdhbadklcf', // Anime Skip Player
@@ -16,22 +12,18 @@ const chromeExtensionIds = [
  'elfaihghhjjoknimpccccmkioofjjfkf', // StayFree - Website Blocker & Web Analytics
  'okifoaikfmpfcamplcfjkpdnhfodpkil', // Doozy: Ai Made Easy
  'lknmjhcajhfbbglglccadlfdjbaiifig', // tl;dv - Record, Transcribe & ChatGPT for Google Meet
-  'youtube中文配音/oglffgiaiekgeicdgkdlnlkhliajdlja', // Youtube中文配音
-  'agjnjboanicjcpenljmaaigopkgdnihi', // PreMiD
 ];

-const { data, err, isLoading } = useListExtensionDetails(chromeExtensionIds);
+const { data } = useListExtensionDetails(chromeExtensionIds);
 const sortedExtensions = computed(() => {
  if (!data.value?.length) return [];

  return [...data.value]
-    .filter((item) => item != null)
    .map((item) => ({
      ...item,
      // Sort based on the user count weighted by the rating
      sortKey: ((item.rating ?? 5) / 5) * item.weeklyActiveUsers,
    }))
-    .filter((item) => !!item)
    .sort((l, r) => r.sortKey - l.sortKey);
 });

@@ -50,16 +42,7 @@ function getStoreUrl(extension: ChromeExtension) {
        Battle tested and ready for production. Explore chrome extensions made
        with WXT.
      </p>
-      <p v-if="isLoading" style="text-align: center; opacity: 50%">
-        Loading...
-      </p>
-      <p
-        v-else-if="err || sortedExtensions.length === 0"
-        style="text-align: center; opacity: 50%"
-      >
-        Failed to load extension details.
-      </p>
-      <ul v-else>
+      <ul>
        <li
          v-for="extension of sortedExtensions"
          :key="extension.id"
@@ -26,7 +26,6 @@ const query = `query ${operationName}($ids:[String!]!) {
 export default function (ids: string[]) {
  const data = ref<ChromeExtension[]>();
  const err = ref<unknown>();
-  const isLoading = ref(true);

  fetch('https://queue.wxt.dev/api', {
    method: 'POST',
@@ -37,7 +36,6 @@ export default function (ids: string[]) {
    }),
  })
    .then(async (res) => {
-      isLoading.value = false;
      const {
        data: { chromeExtensions },
      } = await res.json();
@@ -45,7 +43,6 @@ export default function (ids: string[]) {
      err.value = undefined;
    })
    .catch((error) => {
-      isLoading.value = false;
      console.error(error);
      data.value = undefined;
      err.value = error;
@@ -54,6 +51,5 @@ export default function (ids: string[]) {
  return {
    data,
    err,
-    isLoading,
  };
 }
@@ -84,19 +84,18 @@ export default defineConfig({
            { text: 'Installation', link: '/guide/installation.md' },
            { text: 'Configuration', link: '/guide/configuration.md' },
            { text: 'Entrypoints', link: '/guide/entrypoints.md' },
+            { text: 'Assets', link: '/guide/assets.md' },
+            { text: 'Multiple Browsers', link: '/guide/multiple-browsers.md' },
+            { text: 'Publishing', link: '/guide/publishing.md' },
+            { text: 'Auto-imports', link: '/guide/auto-imports.md' },
            { text: 'Manifest.json', link: '/guide/manifest.md' },
            { text: 'Extension APIs', link: '/guide/extension-apis.md' },
            { text: 'Storage', link: '/guide/storage.md' },
-            { text: 'Assets', link: '/guide/assets.md' },
            { text: 'Content Script UI', link: '/guide/content-script-ui.md' },
-            { text: 'Multiple Browsers', link: '/guide/multiple-browsers.md' },
-            { text: 'ES Modules', link: '/guide/esm.md' },
-            { text: 'Auto-imports', link: '/guide/auto-imports.md' },
-            { text: 'Vite', link: '/guide/vite.md' },
            { text: 'Remote Code', link: '/guide/remote-code.md' },
-            { text: 'Publishing', link: '/guide/publishing.md' },
            { text: 'Development', link: '/guide/development.md' },
            { text: 'Testing', link: '/guide/testing.md' },
+            { text: 'Vite', link: '/guide/vite.md' },
          ],
        },
        {
@@ -2,7 +2,6 @@ import DefaultTheme from 'vitepress/theme';
 import Icon from '../components/Icon.vue';
 import EntrypointPatterns from '../components/EntrypointPatterns.vue';
 import UsingWxtSection from '../components/UsingWxtSection.vue';
-import ExampleList from '../components/ExampleList.vue';
 import './custom.css';

 export default {
@@ -11,6 +10,5 @@ export default {
    ctx.app.component('Icon', Icon);
    ctx.app.component('EntrypointPatterns', EntrypointPatterns);
    ctx.app.component('UsingWxtSection', UsingWxtSection);
-    ctx.app.component('ExampleList', ExampleList);
  },
 };
@@ -16,7 +16,7 @@ For MV2, the background is added as a script to the background page. For MV3, th
 ## Definition

 :::warning
-The main function of the background **_CANNOT BE ASYNC_**. Event listeners must be added synchronously on background startup. If your main function returns a promise, WXT will log an error.
+The main function of the background **_CANNOT BE ASYNC_**. Event listeners must be added syncronously on background startup. If your main function returns a promise, WXT will log an error.
 :::

 ```ts
@@ -20,7 +20,7 @@ When creating content script entrypoints, they are automatically included in the
 ```ts
 export default defineContentScript({
  // Set manifest options
-  matches: string[],
+  matches: ['*://google.com/*', '*://duckduckgo.com/*'],
  excludeMatches: undefined | [],
  includeGlobs: undefined | [],
  excludeGlobs: undefined | [],
@@ -37,9 +37,6 @@ export default defineContentScript({
  // Configure how CSS is injected onto the page
  cssInjectionMode: undefined | "manifest" | "manual" | "ui",

-  // Configure how/when content script will be registered
-  registration: undefined | "manifest" | "runtime",
-
  main(ctx) {
    // Executed when content script is loaded
  },
@@ -93,7 +90,7 @@ To include CSS with your content script, import the CSS file at the top of your

 ```

-<srcDir>/
+<srcDir>
 └─ entrypoints/
   └─ overlay.content/
      ├─ index.ts
@@ -140,5 +137,3 @@ export default defineContentScript({
  },
 });
 ```
-
-See [Content Script UI](/guide/content-script-ui) for more info on creating UIs and including CSS in content scripts.
@@ -2,7 +2,7 @@

 WXT can build CSS entrypoints individually. CSS entrypoints are always unlisted.

-See [Content Script CSS](/entrypoints/content-scripts#css) documentation for the recommended approach to include CSS with a content script.
+See [Content Script CSS](/entrypoints/content-scripts#css) documentation for the recomended approach to include CSS with a content script.

 :::info
 If the recommended approach doesn't work for your use case, you can use any of the filename patterns below to build the styles separate from the JS and use the [`transformManifest` hook](/api/wxt/interfaces/InlineConfig#transformmanifest) to manually add your CSS file to the manifest.
@@ -13,12 +13,15 @@

 ## Definition

+Plain old HTML file.
+
 ```html
 <!doctype html>
 <html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Title</title>
    <!-- Set include/exclude if the page should be removed from some builds -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
@@ -28,13 +31,3 @@
  </body>
 </html>
 ```
-
-## Adding UI Elements
-
-Chrome extensions allow you to add panels and side panes to the devtools window.
-
-![DevTools window showing Elements panel and Styles sidebar pane.](https://developer.chrome.com/static/docs/extensions/how-to/devtools/extend-devtools/image/devtools-window-showing-e-9051f7f0347cd_1920.png)
-
-See the WXT's examples for a full walkthrough of extending the devtools window:
-
-<ExampleList tag="devtools" />
@@ -10,10 +10,10 @@ Firefox does not support sandboxed pages.

 <EntrypointPatterns
  :patterns="[
-    ['sandbox.html', 'sandbox.html'],
-    ['sandbox/index.html', 'sandbox.html'],
-    ['<name>.sandbox.html', '<name>.html` '],
-    ['<name>.sandbox/index.html', '<name>.html` '],
+    ['entrypoints/sandbox.html', 'sandbox.html'],
+    ['entrypoints/sandbox/index.html', 'sandbox.html'],
+    ['entrypoints/<name>.sandbox.html', '<name>.html` '],
+    ['entrypoints/<name>.sandbox/index.html', '<name>.html` '],
  ]"
 />

@@ -2,20 +2,18 @@

 [Chrome Docs](https://developer.chrome.com/docs/extensions/reference/sidePanel/) &bull; [Firefox Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars)

-In Chrome, side panels use the "side_panel" API, while Firefox uses the "sidebar_action" API.
-
 :::warning
-Chrome added support for sidepanels in Manifest V3, they are not available in Manifest V2.
+Chrome added support for sidepanels in Manifest V3, they are not available in Manfiest V2.
 :::

 ## Filenames

 <EntrypointPatterns
  :patterns="[
-    ['sidepanel.html', 'sidepanel.html'],
-    ['sidepanel/index.html', 'sidepanel.html'],
-    ['<name>.sidepanel.html', '<name>.html` '],
-    ['<name>.sidepanel/index.html', '<name>.html` '],
+    ['entrypoints/sidepanel.html', 'sidepanel.html'],
+    ['entrypoints/sidepanel/index.html', 'sidepanel.html'],
+    ['entrypoints/<name>.sidepanel.html', '<name>.html` '],
+    ['entrypoints/<name>.sidepanel/index.html', '<name>.html` '],
  ]"
 />

@@ -27,17 +25,7 @@ Chrome added support for sidepanels in Manifest V3, they are not available in Ma
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Default Side Panel Title</title>
-    <meta
-      name="manifest.default_icon"
-      content="{
-        16: '/icon-16.png',
-        24: '/icon-24.png',
-        ...
-      }"
-    />
-    <meta name="manifest.open_at_install" content="true|false" />
-    <meta name="manifest.browser_style" content="true|false" />
+    <title>Title</title>
    <!-- Set include/exclude if the page should be removed from some builds -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
@@ -1,6 +1,6 @@
 # Unlisted Pages

-HTML pages that are bundled and shipped with the extension, but are not included in the manifest.
+HTML pages that are built by Vite, but are not included in the manifest.

 ### Examples

@@ -1,6 +1,6 @@
 # Unlisted Scripts

-TypeScript files that are bundled and shipped with the extension, but are not included in the manifest.
+TypeScript files that are built, but are not included in the manifest.

 You are responsible for loading/running these scripts where needed.

@@ -2,6 +2,26 @@

 Simple walkthroughs to accomplish common tasks or patterns with WXT.

-<ExampleList />
+<script lang="ts" setup>
+import { ref, onMounted } from 'vue';
+
+const examples = ref()
+onMounted(async () => {
+    const res = await fetch("https://raw.githubusercontent.com/wxt-dev/wxt-examples/main/examples.json");
+    examples.value = await res.json();
+})
+
+</script>
+
+<ul>
+    <li v-if="examples == null">
+        Loading...
+    </li>
+    <template v-else>
+        <li v-for="example of examples">
+        <a :href="example.url" target="_blank">{{ example.name }}</a>
+        </li>
+    </template>
+</ul>

 > Full code available at [`wxt-dev/wxt-examples`](https://github.com/wxt-dev/wxt-examples)
@@ -14,9 +14,7 @@ Some WXT APIs can be used without importing them:
 - [`defineContentScript`](/api/wxt/sandbox/functions/defineContentScript) from `wxt/sandbox`
 - [`defineBackground`](/api/wxt/sandbox/functions/defineBackground) from `wxt/sandbox`
 - [`defineUnlistedScript`](/api/wxt/sandbox/functions/defineUnlistedScript) from `wxt/sandbox`
- [`createIntegratedUi`](/api/wxt/client/functions/createIntegratedUi) from `wxt/client`
- [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) from `wxt/client`
- [`createIframeUi`](/api/wxt/client/functions/createIframeUi) from `wxt/client`
+- [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi) from `wxt/client`
 - [`fakeBrowser`](/api/wxt/testing/variables/fakeBrowser) from `wxt/testing`

 And more!
@@ -65,7 +63,7 @@ import { defineConfig } from 'wxt';

 export default defineConfig({
  imports: {
-    // Add auto-imports for vue functions like createApp, ref, computed, watch, toRaw, etc...
+    // Add auto-imports for vue fuctions like createApp, ref, computed, watch, toRaw, etc...
    presets: ['vue'],
  },
 });
@@ -40,7 +40,7 @@ WXT's main goal is improving the development experience (DX) of creating web ext

 Opening a browser automatically makes it super easy to start and stop development without having to manually load the extension in your browser.

-Reloading each part of the extension individually improves your iteration speed while developing UIs. This is because reloading the entire extension on every change will close the popup and any tabs open to an extension page, like options. If you save a file associated with a UI and a content script while working on the UI, it will randomly close because it needed to reload the extension when the content script changed. This interrupts your development flow and is really annoying.
+Reloading each part of the extension individually improves your iteration speed while developing UIs. This is because reloading the entire extension on every change will close the popup and any tabs open to an extension page, like options. If you save a file associated with a UI and a content script while working on the UI, it will randomly close because it needed to reload the extension when the content script changed. This interupts your development flow and is really annoying.

 WXT solves this problem by reloading HTML pages and content scripts individually (when possible) to keep your UIs open while you develop them. This is a MV3 feature, so if you're developing a MV2 extension, you'll get the same dev experience as Plasmo.

@@ -1,6 +1,6 @@
 # Configuration

-WXT's behavior can be configured via the `wxt.config.ts` file. In this file, you can add Vite plugins, change the directory structure of your project, and set fields on your `manifest.json`.
+WXT's behavior can be configured via the `wxt.config.ts` file. In this file, you can add Vite plugins, change the directory strucutre of your project, and set fields on your `manifest.json`.

 ## Config File

@@ -51,6 +51,12 @@ export default defineConfig({
 });
 ```

+## Vite Config
+
+[Vite](https://vitejs.dev/) is the bundler used to build each entrypoint of your extension. Vite can be configured via the `vite` option.
+
+See [Vite's documentation](https://vitejs.dev/config/) for configuring the bundler.
+
 ## Frontend Frameworks

 Adding a framework like Vue, React, or Svelte is easy!
@@ -64,9 +70,9 @@ import { defineConfig } from 'wxt';
 import vue from '@vitejs/plugin-vue';

 export default defineConfig({
-  vite: () => ({
+  vite: {
    plugins: [vue()],
-  }),
+  },
 });
 ```

@@ -75,9 +81,9 @@ import { defineConfig } from 'wxt';
 import react from '@vitejs/plugin-react';

 export default defineConfig({
-  vite: () => ({
+  vite: {
    plugins: [react()],
-  }),
+  },
 });
 ```

@@ -86,14 +92,10 @@ import { defineConfig } from 'wxt';
 import { svelte } from '@sveltejs/vite-plugin-svelte';

 export default defineConfig({
-  vite: () => ({
+  vite: {
    plugins: [svelte()],
-  }),
+  },
 });
 ```

 :::
-
-:::info
-Internally, WXT runs `vite build` multiple times during a single build. It can't share the same instance of some plugins between each build, so a function is used to return completely new instances of each plugin for each build.
-:::
@@ -6,36 +6,35 @@ There are three ways to mount a UI inside a content script:

 Each has their own set of advantages and disadvantages.

-| Method      | Isolated Styles |   Isolated Events   | HMR | Use page's context |
-| ----------- | :-------------: | :-----------------: | :-: | :----------------: |
-| Integrated  |       ❌        |         ❌          | ❌  |         ✅         |
-| Shadow Root |       ✅        | ✅ (off by default) | ❌  |         ✅         |
-| IFrame      |       ✅        |         ✅          | ✅  |         ❌         |
+| Method     | Isolated Styles | HMR | Use page's context |
+| ---------- | :-------------: | :-: | :----------------: |
+| Integrated |       ❌        | ❌  |         ✅         |
+| ShadowRoot |       ✅        | ❌  |         ✅         |
+| IFrame     |       ✅        | ✅  |         ❌         |

 ## Integrated

 Integrated content script UIs are injected alongside the content of a page. This means that they are affected by CSS on that page.

+You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) property.
+
 :::code-group

 ```ts [Vanilla]
 // entrypoints/example-ui.content.ts
 export default defineContentScript({
-  matches: ['<all_urls>'],
-
  main(ctx) {
-    const ui = createIntegratedUi(ctx, {
-      position: 'inline',
-      onMount: (container) => {
-        // Append children to the container
-        const app = document.createElement('p');
-        app.textContent = '...';
-        container.append(app);
-      },
-    });
+    // Create the UI container
+    const container = document.createElement('div');

-    // Call mount to add the UI to the DOM
-    ui.mount();
+    // Add UI container to the page
+    const anchor = document.querySelector('#anchor');
+    anchore.append(container);
+
+    // Remove UI container when invalidated
+    ctx.onInvalidated(() => {
+      container.remove();
+    });
  },
 });
 ```
@@ -43,28 +42,25 @@ export default defineContentScript({
 ```ts [Vue]
 // entrypoints/example-ui.content/index.ts
 import { createApp } from 'vue';
-import App from './App.vue';

 export default defineContentScript({
-  matches: ['<all_urls>'],
-
  main(ctx) {
-    const ui = createIntegratedUi(ctx, {
-      position: 'inline',
-      onMount: (container) => {
-        // Create the app and mount it to the UI container
-        const app = createApp(App);
-        app.mount(container);
-        return app;
-      },
-      onRemove: (app) => {
-        // Unmount the app when the UI is removed
-        app.unmount();
-      },
-    });
+    // Create the UI container
+    const container = document.createElement('div');

-    // Call mount to add the UI to the DOM
-    ui.mount();
+    // Create the app and mount it to the UI container
+    const app = createApp(...);
+    app.mount(container);
+
+    // Add UI container to the page
+    const anchor = document.querySelector('#anchor');
+    anchore.append(container);
+
+    // Unmount the app and remove UI container when invalidated
+    ctx.onInvalidated(() => {
+      app.unmount();
+      container.remove();
+    });
  },
 });
 ```
@@ -72,57 +68,52 @@ export default defineContentScript({
 ```tsx [React]
 // entrypoints/example-ui.content/index.tsx
 import ReactDOM from 'react-dom/client';
-import App from './App.tsx';

 export default defineContentScript({
-  matches: ['<all_urls>'],
-
  main(ctx) {
-    const ui = createIntegratedUi(ctx, {
-      position: 'inline',
-      onMount: (container) => {
-        // Create a root on the UI container and render a component
-        const root = ReactDOM.createRoot(container);
-        root.render(<App />);
-        return root;
-      },
-      onRemove: (root) => {
-        // Unmount the root when the UI is removed
-        root.unmount();
-      },
-    });
+    // Create the UI container
+    const container = document.createElement('div');

-    // Call mount to add the UI to the DOM
-    ui.mount();
+    // Create a root on the UI container and render a component
+    const root = ReactDOM.createRoot(container);
+    root.render(...);
+
+    // Add UI container to the page
+    const anchor = document.querySelector('#anchor');
+    anchore.append(container);
+
+    // Unmount the root and remove UI container when invalidated
+    ctx.onInvalidated(() => {
+      root.unmount();
+      container.remove();
+    });
  },
 });
 ```

-```ts [Svelte]
+```ts [Svelete]
 // entrypoints/example-ui.content/index.ts
 import App from './App.svelte';

 export default defineContentScript({
-  matches: ['<all_urls>'],
-
  main(ctx) {
-    const ui = createIntegratedUi(ctx, {
-      position: 'inline',
-      onMount: (container) => {
-        // Create the Svelte app inside the UI container
-        const app = new App({
-          target: container,
-        });
-        return app;
-      },
-      onRemove: (app) => {
-        // Destroy the app when the UI is removed
-        app.$destroy();
-      },
+    // Create the UI container
+    const container = document.createElement('div');
+
+    // Create the Svelte app inside the UI container
+    const app = new App({
+      target: ui,
    });

-    // Call mount to add the UI to the DOM
-    ui.mount();
+    // Add UI container to the page
+    const anchor = document.querySelector('#anchor');
+    anchore.append(container);
+
+    // Destroy the app and remove UI container when invalidated
+    ctx.onInvalidated(() => {
+      app.$destroy();
+      container.remove();
+    });
  },
 });
 ```
@@ -132,63 +123,56 @@ export default defineContentScript({
 import { render } from 'solid-js/web';

 export default defineContentScript({
-  matches: ['<all_urls>'],
-
  main(ctx) {
-    const ui = createIntegratedUi(ctx, {
-      position: 'inline',
-      onMount: (container) => {
-        // Render your app to the UI container
-        const unmount = render(() => <div>...</div>, container);
-      },
-      onRemove: (unmount) => {
-        // Unmount the app when the UI is removed
-        unmount();
-      },
-    });
+    // Create the UI container
+    const container = document.createElement('div');

-    // Call mount to add the UI to the DOM
-    ui.mount();
+    // Render your app to the UI container
+    const unmount = render(() => ..., container)
+
+    // Add UI container to the page
+    const anchor = document.querySelector('#anchor');
+    anchore.append(container);
+
+    // Unmount the app and remove UI container when invalidated
+    ctx.onInvalidated(() => {
+      unmount();
+      container.remove();
+    });
  },
 });
 ```

 :::

-See the [API Reference](/api/wxt/client/functions/createIntegratedUi) for the complete list of options.
-
-You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/BaseContentScriptEntrypointOptions#cssinjectionmode) property. Usually, you'll want to leave it as `"manifest"`, the default, so the UI inherits its style from the website's CSS.
-
-## Shadow Root
+## ShadowRoot

 Often in web extensions, you don't want your content script's CSS affecting the page, or vise-versa. The [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) API is ideal for this.

-WXT's [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) abstracts all the `ShadowRoot` setup away, making it easy to create UIs with isolated CSS. It also supports an optional `isolateEvents` parameter to further isolate user interactions.
+WXT provides a helper function, [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi), that abstracts all the `ShadowRoot` setup away, making it easy to create UIs with isolated CSS.

-To use `createShadowRootUi`, follow these steps:
+To use `createContentScriptUi`, follow these steps:

 1. Import your CSS file at the top of your content script
-2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/BaseContentScriptEntrypointOptions#cssinjectionmode) inside `defineContentScript`
-3. Define your UI with `createShadowRootUi()`
+2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) inside `defineContentScript`
+3. Define your UI with `createContentScriptUi()`
 4. Mount the UI so it is visible to users

-:::code-group
-
-```ts [Vanilla]
+```ts
 // 1. Import the style
 import './style.css';

 export default defineContentScript({
-  matches: ['<all_urls>'],
  // 2. Set cssInjectionMode
  cssInjectionMode: 'ui',

  async main(ctx) {
    // 3. Define your UI
-    const ui = await createShadowRootUi(ctx, {
+    const ui = await createContentScriptUi(ctx, {
      name: 'example-ui',
-      position: 'inline',
-      onMount(container) {
+      anchor: '#anchor',
+      type: 'inline',
+      mount(container) {
        // Define how your UI will be mounted inside the container
        const app = document.createElement('p');
        app.textContent = 'Hello world!';
@@ -202,156 +186,91 @@ export default defineContentScript({
 });
 ```

+> `createContentScriptUi` will automatically remove the UI from the page when the content script is invalidated.
+
+See the [API Reference](/api/wxt/client/functions/createContentScriptUi) for the complete list of options.
+
+:::info TailwindCSS
+`createContentScriptUi` supports TailwindCSS out of the box! When importing the styles, just import the main CSS file containing the `@tailwind` directives, and everything will just work :+1:.
+:::
+
+When using a frontend framework for your UI, you'll need to unmount the app when the UI is removed. This is accomplished by returning an app reference from the `mount` option and by passing in a custom `onRemoved` option:
+
+:::code-group
+
 ```ts [Vue]
-// 1. Import the style
-import './style.css';
 import { createApp } from 'vue';
-import App from './App.vue';

-export default defineContentScript({
-  matches: ['<all_urls>'],
-  // 2. Set cssInjectionMode
-  cssInjectionMode: 'ui',
-
-  async main(ctx) {
-    // 3. Define your UI
-    const ui = await createShadowRootUi(ctx, {
-      name: 'example-ui',
-      position: 'inline',
-      onMount: (container) => {
-        // Define how your UI will be mounted inside the container
-        const app = createApp(App);
-        app.mount(container);
-        return app;
-      },
-      onRemove: (app) => {
-        // Unmount the app when the UI is removed
-        app?.unmount();
-      },
-    });
-
-    // 4. Mount the UI
-    ui.mount();
+const ui = createContentScriptUi(ctx, {
+  // ...
+  mount(container) {
+    const app = createApp(App);
+    app.mount(container);
+    return app;
+  },
+  onRemove(app) {
+    app.unmount();
  },
 });
 ```

 ```tsx [React]
-// 1. Import the style
-import './style.css';
 import ReactDOM from 'react-dom/client';
-import App from './App.tsx';

-export default defineContentScript({
-  matches: ['<all_urls>'],
-  // 2. Set cssInjectionMode
-  cssInjectionMode: 'ui',
-
-  async main(ctx) {
-    // 3. Define your UI
-    const ui = await createShadowRootUi(ctx, {
-      name: 'example-ui',
-      position: 'inline',
-      onMount: (container) => {
-        // Container is a body, and React warns when creating a root on the body, so create a wrapper div
-        const app = document.createElement('div');
-        container.append(app);
-
-        // Create a root on the UI container and render a component
-        const root = ReactDOM.createRoot(app);
-        root.render(<App />);
-        return root;
-      },
-      onRemove: (root) => {
-        // Unmount the root when the UI is removed
-        root?.unmount();
-      },
-    });
-
-    // 4. Mount the UI
-    ui.mount();
+const ui = createContentScriptUi(ctx, {
+  // ...
+  mount(container) {
+    const root = ReactDOM.createRoot(container);
+    root.render(...);
+    return root;
+  },
+  onRemove(root) {
+    root.unmount();
  },
 });
 ```

 ```ts [Svelte]
-// 1. Import the style
-import './style.css';
 import App from './App.svelte';

-export default defineContentScript({
-  matches: ['<all_urls>'],
-  // 2. Set cssInjectionMode
-  cssInjectionMode: 'ui',
-
-  async main(ctx) {
-    // 3. Define your UI
-    const ui = await createShadowRootUi(ctx, {
-      name: 'example-ui',
-      position: 'inline',
-      onMount: (container) => {
-        // Create the Svelte app inside the UI container
-        const app = new App({
-          target: container,
-        });
-        return app;
-      },
-      onRemove: (app) => {
-        // Destroy the app when the UI is removed
-        app?.$destroy();
-      },
-    });
-
-    // 4. Mount the UI
-    ui.mount();
+const ui = createContentScriptUi(ctx, {
+  // ...
+  mount(container) {
+    return new App({ target: container });
+  },
+  onRemove(app) {
+    app.$destry();
  },
 });
 ```

 ```tsx [Solid]
-// 1. Import the style
-import './style.css';
 import { render } from 'solid-js/web';

-export default defineContentScript({
-  matches: ['<all_urls>'],
-  // 2. Set cssInjectionMode
-  cssInjectionMode: 'ui',
-
-  async main(ctx) {
-    // 3. Define your UI
-    const ui = await createShadowRootUi(ctx, {
-      name: 'example-ui',
-      position: 'inline',
-      onMount: (container) => {
-        // Render your app to the UI container
-        const unmount = render(() => <div>...</div>, container);
-      },
-      onRemove: (unmount) => {
-        // Unmount the app when the UI is removed
-        unmount?.();
-      },
-    });
-
-    // 4. Mount the UI
-    ui.mount();
+const ui = createContentScriptUi(ctx, {
+  // ...
+  mount(container) {
+    return render(() => ..., container);
+  },
+  onRemove(unmount) {
+    unmount();
  },
 });
 ```

 :::

-See the [API Reference](/api/wxt/client/functions/createShadowRootUi) for the complete list of options.
+:::warning
+The `mount(container)` and `onRemove(app)` options passed into `createContentScriptUi` **_are different from_** the `ui.mount()` and `ui.remove()` functions available on the returned UI object.

-:::info TailwindCSS
-`createShadowRootUi` supports TailwindCSS out of the box! When importing the styles, just import the main CSS file containing the `@tailwind` directives, and everything will just work :+1:.
+You don't need to pass anything into `ui.mount()` and `ui.remove()` because **_you already defined how and where the UI will be mounted_** in the options passed into `createContentScriptUi`.
 :::

 ## IFrame

 If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page, **_HMR is supported_**.

-WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/createIframeUi), which simplifies setting up the IFrame.
+WXT provides a helper function, [`createContentScriptIframe`](/api/wxt/client/functions/createContentScriptUi), which simplifies setting up the IFrame.

 1. Create an HTML page that will be loaded into your IFrame
   ```html
@@ -368,7 +287,7 @@ WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/cre
     </body>
   </html>
   ```
-1. Add the page to the manifest's `web_accessible_resources`
+1. Add the page to the manifest's `web_accessible_resouces`
   ```ts
   // wxt.config.ts
   export default defineConfig({
@@ -386,23 +305,22 @@ WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/cre

   ```ts
   export default defineContentScript({
-     matches: ['<all_urls>'],
-
+     // ...
     async main(ctx) {
       // Define the UI
-       const ui = await createIframeUi(ctx, {
+       const ui = await createContentScriptIframe(ctx, {
         page: '/example-iframe.html',
-         position: 'inline',
-         onMount: (wrapper, iframe) => {
-           // Add styles to the iframe like width
-           iframe.width = 123;
-         },
+         anchor: '#anchor',
+         type: 'inline',
       });

+       // Add styles to the iframe like width
+       ui.iframe.width = 123;
+
       // Show UI to user
       ui.mount();
     },
   });
   ```

-See the [API Reference](/api/wxt/client/functions/createIframeUi) for the complete list of options.
+See the [API Reference](/api/wxt/client/functions/createContentScriptUi) for the complete list of options.
@@ -13,24 +13,6 @@ WXT's main goal is providing the best DX it possibly can. When running your exte
 | `wxt.config.ts`     |     |                       |                  | 🟡 See [#10](https://github.com/wxt-dev/wxt/issues/10) |
 | `web-ext.config.ts` |     |                       |                  | 🟡 See [#10](https://github.com/wxt-dev/wxt/issues/10) |

-## Dev Mode vs Production Builds
-
-There are some notable differences between the development and production versions of an extension. During development:
-
-1. **Content scripts are not listed in the `manifest.json`** when targeting MV3. Instead, the [`scripting`](https://developer.chrome.com/docs/extensions/reference/api/scripting) permission is used to register content scripts at runtime so they can be reloaded individually.
-
-   To get the list of content scripts during development, run the following in the background's console:
-
-   ```ts
-   await chrome.scripting.getRegisteredContentScripts();
-   ```
-
-2. **The CSP is modified to allow loading scripts from the dev server**. Make sure you're using Chrome v110 or above for HMR to work.
-
-3. If you don't include a background script/service worker, one will be created to perform various tasks in dev mode, mostly related to reloading different parts of the extension on change.
-
-For production builds, none of the above modifications will be applied, and you're extension/manifest will only include what you have defined.
-
 ## Configure Browser Startup

 WXT uses [`web-ext` by Mozilla](https://github.com/mozilla/web-ext) to automatically open a browser with the extension installed. You can configure the runner's behavior via the [`runner`](/api/wxt/interfaces/InlineConfig#runner) option, or in a separate gitignored file, `web-ext.config.ts`.
@@ -57,9 +39,7 @@ export default defineRunnerConfig({

 :::

-### Browser Binaries
-
-`web-ext`'s browser discovery is very limited. By default, it only guesses at where Chrome and Firefox are installed. If you've customized your install locations, you may need to tell `web-ext` where the binaries/executables are located using the [`binaries` option](/api/wxt/interfaces/ExtensionRunnerConfig#binaries). For other Chromium based browsers, like Edge or Opera, you'll need to explicitly list them in the `binaries` option as well, otherwise they will open in Chrome by default.
+`web-ext`'s browser discovery is very limitted. By default, it only guesses at where Chrome and Firefox are installed. If you've customized your install locations, you may need to tell `web-ext` where the binaries/executables are located using the [`binaries` option](/api/wxt/interfaces/ExtensionRunnerConfig#binaries). For other Chromium based browsers, like Edge or Opera, you'll need to explicitly list them in the `binaries` option as well, otherwise they will open in Chrome by default.

 ```ts
 // ~/web-ext.config.ts
@@ -77,30 +57,3 @@ export default defineRunnerConfig({
 :::tip
 When configuring browser binaries, it's helpful to put them in `~/web-ext.config.ts` instead of the project directory's `web-ext.config.ts` file. When placed in your home directory (`~/`), this config will be used by all WXT projects, so you only need to configure the binaries once.
 :::
-
-### Other options
-
-You can customize other options as well, like startup URLs, profiles, or additional command line arguments:
-
-```ts
-// web-ext.config.ts
-import { defineRunnerConfig } from 'wxt';
-
-export default defineRunnerConfig({
-  startUrls: ['https://google.com', 'https://duckduckgo.com'],
-  chromiumProfile: '/path/to/profile/to/use',
-  chromiumArgs: ['--window-size=400x300'],
-});
-```
-
-For a full list of options, see the [API Reference](/api/wxt/interfaces/ExtensionRunnerConfig).
-
-## Reload the Extension
-
-Normally, to manually reload an extension, you have to visit `chrome://extensions` and click the reload button for your extension.
-
-When running `wxt` command to start the dev server, WXT adds a keyboard shortcut, `ctrl+E` for Windows/Linux and `cmd+E` for Mac, that reloads the extension when pressed, without visiting `chrome://extensions`.
-
-:::info
-This shortcut is only available during development, and is not be added to your extension when running `wxt build` or `wxt-zip`.
-:::
@@ -58,7 +58,7 @@ See [`/entrypoints` folder](/entrypoints/background) documentation for a full li

 ## Entrypoint Options

-Some entrypoints, like content scripts, actions, or the background, can receive additional options.
+Some entrypoints, like content scripts, actions, or the background, can recieve additional options.

 In HTML files, options are listed as `meta` tags:

@@ -86,56 +86,3 @@ export default defineContentScript({
 :::info
 For a full list of entrypoints and each of their options, see the [`/entrypoints` folder](/entrypoints/background) documentation.
 :::
-
-### Side Effects
-
-You cannot use imported variables outside the `main` function is JS entrypoints. This includes options, as shown below:
-
-```ts
-// entrypoints/content.ts
-import { GOOGLE_MATCHES } from '~/utils/match-patterns';
-
-export default defineContentScript({
-  matches: GOOGLE_MATCHES,
-  main() {
-    // ...
-  },
-});
-```
-
-```
-$ wxt build
-wxt build
-
-WXT 0.14.1
-ℹ Building chrome-mv3 for production with Vite 5.0.5
-✖ Command failed after 360 ms
-
-[8:55:54 AM]  ERROR  entrypoints/content.ts: Cannot use imported variable "GOOGLE_MATCHES" before main function. See https://wxt.dev/guide/entrypoints.html#side-effects
-```
-
-This throws an error because WXT needs to import each entrypoint during the build process to extract its definition (containing the `match`, `run_at`, `include`/`exclude`, etc.) to render the `manifest.json` correctly. Before loading an entrypoint, a transformation is applied to remove all imports. This prevents imported modules (local or NPM) with side-effects from running during the build process, potentially throwing an error.
-
-:::details Why?
-
-When importing your entrypoint to get its definition, the file is imported in a **_node environment_**, and doesn't have access to the `window`, `chrome`, or `browser` globals a web extension usually has access to. If WXT doesn't remove all the imports from the file, the imported modules could try and access one of these variables, throwing an error.
-
-:::
-
-:::warning
-See [`wxt-dev/wxt#336`](https://github.com/wxt-dev/wxt/issues/336) to track the status of this bug.
-:::
-
-Usually, this error occurs when you try to extract options into a shared file or try to run code outside the `main` function. To fix the example from above, use literal values when defining an entrypoint instead of importing them:
-
-```ts
-import { GOOGLE_MATCHES } from '~/utils/match-patterns'; // [!code --]
-
-export default defineContentScript({
-  matches: GOOGLE_MATCHES, // [!code --]
-  matches: ['*//*.google.com/*'], // [!code ++]
-  main() {
-    // ...
-  },
-});
-```
@@ -1,38 +0,0 @@
-# ES Modules
-
-Configure entrypoints to use ESM at runtime.
-
-Currently, ESM entrypoints are opt-in, so you must configure each entrypoint with that in mind.
-
-## HTML Pages <Badge type="warning" text="≥0.0.1" />
-
-In general, you should always make HTML pages import ESM scripts, unless you need to support old browsers.
-
-To make a script ESM, add `type="module"`:
-
-<!-- prettier-ignore -->
-```html
-<script src="./main.ts"></script> <!-- [!code --] -->
-<script src="./main.ts" type="module"></script> <!-- [!code ++] -->
-```
-
-## Background <Badge type="warning" text="≥0.16.0" />
-
-In your background script, set `type: "module"`:
-
-```ts
-export default defineBackground({
-  type: 'module', // !code ++
-  main() {
-    // ...
-  },
-});
-```
-
-:::warning
-Only MV3 support ESM background scripts/service workers. When targeting MV2, the `type` option is ignored and the background is always bundled into a single file as IIFE.
-:::
-
-## Content Scripts
-
-Coming soon. Follow [Content Script ESM Support #357](https://github.com/wxt-dev/wxt/issues/357) for updates.
@@ -57,19 +57,21 @@ Here's a basic request/response example:
 // popup/main.ts
 const res = await browser.runtime.sendMessage('ping');

-console.log(res); // "pong"
+console.log('res'); // "pong"
 ```

 ```ts
 // background.ts
 export default defineBackground(() => {
-  browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
-    console.log(message); // "ping"
+  browser.runtime.onMessage.addEventListener(
+    (message, sender, sendResponse) => {
+      console.log(message); // "ping"

-    // Wait 1 second and respond with "pong"
-    setTimeout(() => sendResponse('pong'), 1000);
-    return true;
-  });
+      // Wait 1 second and respond with "pong"
+      setTimeout(() => sendResponse('pong'), 1000);
+      return true;
+    },
+  );
 });
 ```

@@ -133,7 +133,7 @@ The dev command will build the extension for development, open the browser, and
 When running the dev command, WXT will make several changes to your `manifest.json` to improve your development experience:

 - If missing, add a background script/service worker to enable fast reloads
- Add several `permissions` and `host_permissions` to enable HMR and fast reloads
+- Add serveral `permissions` and `host_permissions` to enable HMR and fast reloads
 - Modify the CSP to allow connections with the dev server
 - Remove `content_scripts` and register them at runtime so they can be easily reloaded when you save a file

@@ -145,6 +145,5 @@ If you're an experienced web extension developer and think the dev manifest look
 You're ready to build your web extension!

 - Learn how to [add entrypoints](./entrypoints) like the popup, options page, or content scripts
- Configure your entrypoints to [use ESM](./esm) at runtime
 - [Configure WXT](./configuration) by creating a `wxt.config.ts` file
- Checkout [example projects](https://github.com/wxt-dev/wxt-examples) to see how to perform common tasks with WXT
+- Checkout [example projects](https://github.com/wxt-dev/wxt-examples) to see how to perfom common tasks with WXT
@@ -7,7 +7,7 @@ head:

 # Introduction

-WXT is a free and open source framework for building web extensions in an conventional, intuitive, and safe way **_for all browsers_**.
+WXT is a free and open source framework for building web extensions in an conventional, intuative, and safe way **_for all browsers_**.

 WXT is based of [Nuxt](https://nuxt.com), and aims to provide the same great DX with TypeScript, auto-imports, and an opinionated project structure.

@@ -15,12 +15,12 @@ WXT is based of [Nuxt](https://nuxt.com), and aims to provide the same great DX

 ## Conventions

-WXT is an opinionated framework. This helps keep projects consistent and easy to pick up.
+WXT is an optionated framework. This helps keep projects consistent and easy to pick up.

 - **Generated manifest**: Based on your project's file structure
 - **Entrypoint configuration**: Configure entrypoints from the same file they're declare in
 - **Type-safety is a priority**: Out-of-the-box TypeScript support with improved browser API typing
- **Simple output file structure**: Output file paths minimize the path at runtime
+- **Simple output file structure**: Ouptut file paths minimize the path at runtime

 ## Development

@@ -1,13 +1,12 @@
 # Manifest.json

-The manifest.json is generated at build-time based on files in the `entrypoints/` directory and `wxt.config.ts`.
+The manifest.json is generated at build-time based on files in your `entrypoints` directory and your `wxt.config.ts`.

 ## Configuration

 While entrypoints are generated and added to the manifest at build-time, you can customize or add to your `manifest.json` in the config file.

 ```ts
-// wxt.config.tsentrypoint of your extension
 import { defineConfig } from 'wxt';

 export default defineConfig({
@@ -26,13 +25,11 @@ If not provided via the `manifest` config, the [manifest's `name`](https://devel

 ## `version` and `version_name`

-The [manifest's `version` and `version_name`](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) properties are based on the `version` field listed in your `package.json` or `wxt.config.ts`.
+The [manifest's `version` and `version_name`](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) fields are based on your package.json's `version` property.

- `version_name` is the exact string listed in your `package.json` or `wxt.config.ts` file
+- `version_name` is the exact string listed in your package.json
 - `version` is the string cleaned up, with any invalid suffixes removed

-If a version is not found, a warning is logged and the version defaults to `"0.0.0"`.
-
 ### Example

 ```json
@@ -121,7 +118,3 @@ export default defineConfig({
  },
 });
 ```
-
-See the official localization examples for more details:
-
-<ExampleList tag="i18n" />
@@ -32,7 +32,7 @@ Every project is different, so there's no one-solution-fits-all to migrating you

 ## Popular Tools/Frameworks

-Here's specific steps for other popular frameworks/build tools.
+Here's specific steps for other popuplar frameworks/build tools.

 ### `vite-plugin-web-extension`

@@ -1,6 +1,6 @@
 # Multiple Browsers

-You can build an extension for any combination of browser and manifest version. Different browsers and manifest versions support different APIs and entrypoints, so be sure to check that your extension functions as expected for each target.
+You can build an extension for any combination of browser and manifest verison. Different browsers and manifest versions support different APIs and entrypoints, so be sure to check that your extension functions as expected for each target.

 Separate build targets are written to their own output directories:

@@ -17,9 +17,11 @@ Separate build targets are written to their own output directories:

 To build for a specific browser, pass the `-b --browser` flag from the CLI:

-```sh
+```
+
 wxt --browser firefox
 wxt build --browser firefox
+
 ```

 By default, it will build for `chrome`. When excluding the [manifest version flags](#target-manifest-version), it will default to the commonly accepted manifest version for that browser.
@@ -45,7 +47,7 @@ wxt --mv2
 wxt build --mv2
 ```

-When the `-b --browser` flag is not passed, it defaults to `chrome`. So here, we're targeting MV2 for Chrome.
+When the `-b --browser` flag is not passed, it defaults to `chrome`. So here, we're targetting MV2 for Chrome.

 ## Customizing Entrypoints

@@ -110,24 +112,3 @@ export default defineContentScript({
 :::warning
 Only `defineBackground` and `defineContentScript` support per-browser options right now.
 :::
-
-## Runtime
-
-To determine the browser or manifest version at runtime, you can use any of the below variables:
-
- `import.meta.env.BROWSER`: A string, the target browser, usually equal to the `--browser` flag
- `import.meta.env.MANIFEST_VERSION`: A number, either `2` or `3`, depending on the manifest version targeted
- `import.meta.env.CHROME`: A boolean equivalent to `import.meta.env.BROWSER === "chrome"`
- `import.meta.env.FIREFOX`: A boolean equivalent to `import.meta.env.BROWSER === "firefox"`
- `import.meta.env.EDGE`: A boolean equivalent to `import.meta.env.BROWSER === "edge"`
- `import.meta.env.SAFARI`: A boolean equivalent to `import.meta.env.BROWSER === "safari"`
- `import.meta.env.OPERA`: A boolean equivalent to `import.meta.env.BROWSER === "opera"`
- `import.meta.env.COMMAND`: A string, `"serve"` when running `wxt` for development or `"build"` in all other cases.
-
-:::info
-These variables are constants defined at build time based on the build target. They do not actually detect which browser the code is running in.
-
-For example, if you build for `--browser chrome` and publish it on Edge, `import.meta.env.BROWSER` will be `"chrome"`, not `"edge"`. You have to build a separate ZIP for `--browser edge` before `import.meta.env.BROWSER` will be `"edge"`.
-
-If you need to know the actual browser your code is being ran on, you should use a [user agent parser](https://www.npmjs.com/package/ua-parser-js).
-:::
@@ -1,80 +1,106 @@
---
-outline: deep
---
-
 # Publishing

-WXT will help you ZIP your extensions and submit them to the stores for review.
+WXT offers several utilities that simplify the publishing process.

 ## First Time Publishing

-If you're publishing an extension to a store for the first time, you must manually navigate the process. WXT doesn't help you create listings, each store has unique steps and requirements that you need to familiarize yourself with.
+If you're publishing an extension to a store for the first time, it's recommended that you manually navigate the process. Each store has unique steps and requirements that you need to familiarize yourself with.

-For specific details about each store, see the stores sections below.
-
- [Chrome Web Store](#chrome-web-store)
- [Firefox Addon Store](#firefox-addon-store)
- [Edge Addons](#edge-addons)
-
-## Automation
-
-WXT provides two commands to help automate the release process:
-
- `wxt submit`: Submit new versions of your extension for review (and publish them automatically once approved)
- `wxt submit init`: Help setup all the required secrets and options for the `wxt submit` command
-
-To get started, run `wxt submit init` and follow the prompts. Once finished, you should have a `.env.submit` file! WXT will use this file to submit your updates.
-
-> In CI, make sure you add all the environment variables to the submit step.
-
-To release an update, build all the ZIPs you plan on releasing:
+Each store requires that a ZIP file be uploaded. You can generate these using the `wxt zip` command:

 ```sh
 wxt zip
 wxt zip -b firefox
+# etc
 ```

-Then run the `wxt submit` command, passing in all the ZIP files you want to release. In this case, we'll do a release for all 3 major stores: Chrome Web Store, Edge Addons, and Firefox Addons Store.
+Generated ZIP files are stored in the `.output` directory.

-If it's your first time running the command, you'll want to test your secrets by passing the `--dry-run` flag:
+## Automation

-```sh
-wxt submit --dry-run \
-  --chrome-zip .output/<your-extension>-<version>-chrome.zip \
-  --firefox-zip .output/<your-extension>-<version>-firefox.zip --firefox-sources-zip .output/<your-extension>-<version>-sources.zip \
-  --edge-zip .output/<your-extension>-<version>-chrome.zip
-```
+To automate releasing updates, use the [`publish-browser-extension`](https://www.npmjs.com/package/publish-browser-extension) package.

-If the dry run passes, remove the flag and do the actual release:
-
-```sh
-wxt submit \
-  --chrome-zip .output/<your-extension>-<version>-chrome.zip \
-  --firefox-zip .output/<your-extension>-<version>-firefox.zip --firefox-sources-zip .output/<your-extension>-<version>-sources.zip \
-  --edge-zip .output/<your-extension>-<version>-chrome.zip
-```
-
-:::tip
-If you only need to release to a single store, only pass that store's ZIP flag.
+:::info
+🚧 WXT plans to eventually incorporate the `publish-browser-extension` package into its own `wxt submit` command.
 :::

-:::tip
-See the [Firefox Addon Store](#firefox-addon-store) section for more details about the `--firefox-sources-zip` option.
-:::
+1. Install the necessary dependencies:
+
+   ```sh
+   pnpm add -D publish-browser-extension env-cmd
+   ```
+
+2. Add scripts to your `package.json` file:
+
+   ```json
+   {
+     "scripts": {
+       "submit": "env-cmd -f .env.submit -- publish-extension",
+       "submit:dry": "env-cmd -f .env.submit -- publish-extension --dry-run"
+     }
+   }
+   ```
+
+3. Create a `.env.submit` file and include the code below. If you're not publishing to certain stores, simply ignore their respective variables.
+
+   ```txt
+   CHROME_EXTENSION_ID=""
+   CHROME_CLIENT_ID=""
+   CHROME_CLIENT_SECRET=""
+   CHROME_REFRESH_TOKEN=""
+
+   FIREFOX_EXTENSION_ID=""
+   FIREFOX_JWT_ISSUER=""
+   FIREFOX_JWT_SECRET=""
+
+   EDGE_PRODUCT_ID=""
+   EDGE_CLIENT_ID=""
+   EDGE_CLIENT_SECRET=""
+   EDGE_ACCESS_TOKEN_URL=""
+   ```
+
+   > Each value will be filled in during the next step.
+
+4. Run `npx publish-extension --help` for assistance with filling out all the values. Insert the obtained values within the double quotes.
+
+5. ZIP all the targets you plan to publish, in this case Chrome and Firefox.
+
+   ```sh
+   wxt zip
+   wxt zip -b firefox
+   ```
+
+6. Test your credentials by running the `submit:dry` command:
+
+   ```sh
+   pnpm submit:dry \
+     --chrome-zip .output/your-extension-X.Y.Z-chrome.zip \
+     --firefox-zip .output/your-extension-X.Y.Z-firefox.zip \
+     --firefox-sources-zip .output/your-extension-X.Y.Z-sources.zip \
+     --edge-zip .output/your-extension-X.Y.Z-chrome.zip
+   ```
+
+7. Upload and submit your extension for review:
+
+   ```sh
+   pnpm submit \
+     --chrome-zip .output/your-extension-X.Y.Z-chrome.zip \
+     --firefox-zip .output/your-extension-X.Y.Z-firefox.zip \
+     --firefox-sources-zip .output/your-extension-X.Y.Z-sources.zip \
+     --edge-zip .output/your-extension-X.Y.Z-chrome.zip
+   ```

 ## GitHub Action

-Here's an example of a GitHub Action to automate submitting new versions of your extension for review. Ensure that you've added all required secrets used in the workflow to the repo's settings.
+Here's an example of a GitHub Action to automate submiting new versions of your extension for review. Ensure that you've added all required secrets used in the workflow to the repo's settings.

 ```yml
 # TODO
 ```

-## Stores
+## Chrome Web Store

-### Chrome Web Store
-
-> ✅ Supported &bull; [Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard) &bull; [Publishing Docs](https://developer.chrome.com/docs/webstore/publish/)
+✅ Automated &bull; [Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard) &bull; [Publishing Docs](https://developer.chrome.com/docs/webstore/publish/)

 To create a ZIP for Chrome:

@@ -82,15 +108,15 @@ To create a ZIP for Chrome:
 wxt zip
 ```

-### Firefox Addon Store
+## Firefox Addon Store

-> ✅ Supported &bull; [Developer Dashboard](https://addons.mozilla.org/developers/) &bull; [Publishing Docs](https://extensionworkshop.com/documentation/publish/submitting-an-add-on/)
+✅ Automated &bull; [Developer Dashboard](https://addons.mozilla.org/developers/) &bull; [Publishing Docs](https://extensionworkshop.com/documentation/publish/submitting-an-add-on/)

 Firefox requires you to upload a ZIP of your source code. This allows them to rebuild your extension and review the code in a readable way. More details can be found in [Firefox's docs](https://extensionworkshop.com/documentation/publish/source-code-submission/).

-WXT fully supports generating and automatically submitting a source code ZIP.
+WXT and `publish-browser-extension` both fully support generating and automatically submitting a source code ZIP.

-When you run `wxt zip -b firefox`, your sources are zipped into the `.output` directory alongside the extension. WXT will automatically exclude certain files such as config files, hidden files, and tests. However, it's important to manually check the ZIP to ensure it only contains the files necessary to rebuild your extension.
+When you run `wxt zip -b firefox`, your sources are zipped into the `.output` directory along with your built extension. WXT is configured to exclude certain files such as config files, hidden files, and tests. However, it's important to manually check the ZIP to ensure it only contains the files necessary to rebuild your extension.

 To customize which files are zipped, add the `zip` option to your config file.

@@ -126,34 +152,22 @@ yarn zip:firefox

 :::

-Make sure the build output is the exact same when running `wxt build -b firefox` in your main project and inside the zipped sources.
-
-:::warning
-If you use a `.env` files, they can effect the chunk hashes in the output directory. Either delete the .env file before running `wxt zip -b firefox`, or include it in your sources zip with the [`zip.includeSources`](/api/wxt/interfaces/InlineConfig#includesources) option. Be careful to not include any secrets in your `.env` files.
-
-See Issue [#377](https://github.com/wxt-dev/wxt/issues/377) for more details.
-:::
-
 Ensure that you have a `README.md` or `SOURCE_CODE_REVIEW.md` file with the above commands so that the Firefox team knows how to build your extension.

-### Safari
+## Safari

-> 🚧 Not supported yet
+🚧 Not automated at this time

-WXT does not currently support automated publishing for Safari. Safari extensions require a native MacOS or iOS app wrapper, which WXT does not create yet. For now, if you want to publish to Safari, follow this guide:
+:::warning
+🚧 WXT does not currently support automated publishing for Safari. Safari extensions require a native MacOS or iOS app wrapper, which WXT cannot create at this time. For now, if you want to publish to Safari, follow this guide:

- [Converting a web extension for Safari](https://developer.apple.com/documentation/safariservices/safari_web_extensions/converting_a_web_extension_for_safari) - "Convert your existing extension to a Safari web extension using Xcode’s command-line tool."
+https://developer.apple.com/documentation/safariservices/safari_web_extensions/distributing_your_safari_web_extension

-When running the `safari-web-extension-converter` CLI tool, pass the `.output/safari-mv2` or `.output/safari-mv3` directory, not your source code directory.
+:::

-```sh
-pnpm wxt build -b safari
-xcrun safari-web-extension-converter .output/safari-mv2
-```
+## Edge Addons

-### Edge Addons
-
-> ✅ Supported &bull; [Developer Dashboard](https://aka.ms/PartnerCenterLogin) &bull; [Publishing Docs](https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/publish-extension)
+✅ Automated &bull; [Developer Dashboard](https://aka.ms/PartnerCenterLogin) &bull; [Publishing Docs](https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/publish-extension)

 No need to create a specific ZIP for Edge. If you're already publishing to the Chrome Web Store, you can reuse your Chrome ZIP.

@@ -1,266 +1,36 @@
---
-outline: deep
---
-
 # Storage API

-WXT provides a simplified API to replace the `browser.storage.*` APIs. Use the `storage` auto-import from `wxt/storage` or import it manually to get started:
+WXT's storage API is powered by `unstorage`. See [their docs](https://unstorage.unjs.io/usage#usage-1) for more details.

-```ts
-import { storage } from 'wxt/storage';
-```
-
-[[toc]]
-
-## Basic Usage
-
-All storage keys must be prefixed by their storage area.
-
-```ts
-// ❌ This will throw an error
-await storage.getItem('installDate');
-
-// ✅ This is good
-await storage.getItem('local:installDate');
-```
-
-You can use `local:`, `session:`, `sync:`, or `managed:`.
-
-If you use TypeScript, you can add a type parameter to most methods to specify the expected type of the key's value:
-
-```ts
-await storage.getItem<number>('local:installDate');
-await storage.watch<number>(
-  'local:installDate',
-  (newInstallDate, oldInstallDate) => {
-    // ...
-  },
-);
-await storage.getMeta<{ v: number }>('local:installDate');
-```
-
-For a full list of methods available, see the [API reference](/api/wxt/storage/interfaces/WxtStorage).
-
-## Watchers
-
-To listen for storage changes, use the `storage.watch` function. It lets you setup a listener for a single key:
-
-```ts
-const unwatch = storage.watch<number>('local:counter', (newCount, oldCount) => {
-  console.log('Count changed:', { newCount, oldCount });
-});
-```
-
-To remove the listener, call the returned `unwatch` function:
-
-```ts
-const unwatch = storage.watch(...);
-
-// Some time later...
-unwatch();
-```
-
-## Metadata
-
-`wxt/storage` also supports setting metadata for keys, stored at `key + "$"`. Metadata is a collection of properties associated with a key. It might be a version number, last modified date, etc.
-
-[Other than versioning](#versioning), you are responsible for managing a field's metadata:
-
-```ts
-await Promise.all([
-  storage.setItem('local:preference', true),
-  storage.setMeta('local:preference', { lastModified: Date.now() }),
-]);
-```
-
-When setting different properties of metadata from multiple calls, the properties are combined instead of overwritten:
-
-```ts
-await storage.setMeta('local:preference', { lastModified: Date.now() });
-await storage.setMeta('local:preference', { v: 2 });
-
-await storage.getMeta('local:preference'); // { v: 2, lastModified: 1703690746007 }
-```
-
-You can remove all metadata associated with a key, or just specific properties:
-
-```ts
-// Remove all properties
-await storage.removeMeta('local:preference');
-
-// Remove one property
-await storage.removeMeta('local:preference', 'lastModified');
-
-// Remove multiple properties
-await storage.removeMeta('local:preference', ['lastModified', 'v']);
-```
-
-## Defining Storage Items
-
-Writing the key and type parameter for the same key over and over again can be annoying. As an alternative, you can use `storage.defineItem` to create a "storage item".
-
-Storage items contain the same APIs as the `storage` variable, but you can configure its type, default value, and more in a single place:
-
-```ts
-// utils/storage.ts
-const showChangelogOnUpdate = storage.defineItem<boolean>(
-  'local:showChangelogOnUpdate',
-  {
-    defaultValue: true,
-  },
-);
-```
-
-Now, instead of using the `storage` variable, you can use the helper functions on the storage item you created:
-
-```ts
-await showChangelogOnUpdate.getValue();
-await showChangelogOnUpdate.setValue(false);
-await showChangelogOnUpdate.removeValue();
-const unwatch = showChangelogOnUpdate.watch(() => {
-  // ...
-});
-```
-
-For a full list of properties and methods available, see the [API reference](/api/wxt/storage/interfaces/WxtStorageItem).
-
-### Versioning
-
-You can add versioning to storage items if you expect them to grow or change over time. When defining the first version of an item, start with version 1.
-
-For example, consider a storage item that stores a list of websites that are ignored by an extension.
+## Overview

 :::code-group

-```ts [v1]
-type IgnoredWebsiteV1 = string;
-
-export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>(
-  'local:ignoredWebsites',
-  {
-    defaultValue: [],
-    version: 1,
-  },
-);
+```ts [native]
+const { installDate } = await browser.storage.local.get('installDate');
+await browser.storage.local.set({ key: 'value' });
 ```

-<!-- prettier-ignore -->
-```ts [v2]
-import { nanoid } from 'nanoid'; // [!code ++]
-
-type IgnoredWebsiteV1 = string;
-interface IgnoredWebsiteV2 { // [!code ++]
-  id: string; // [!code ++]
-  website: string; // [!code ++]
-} // [!code ++]
-
-export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>( // [!code --]
-export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code ++]
-  'local:ignoredWebsites',
-  {
-    defaultValue: [],
-    version: 1, // [!code --]
-    version: 2, // [!code ++]
-    migrations: { // [!code ++]
-      // Ran when migrating from v1 to v2 // [!code ++]
-      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => { // [!code ++]
-        return websites.map((website) => ({ id: nanoid(), website })); // [!code ++]
-      }, // [!code ++]
-    }, // [!code ++]
-  },
-);
-```
-
-<!-- prettier-ignore -->
-```ts [v3]
-import { nanoid } from 'nanoid';
-
-type IgnoredWebsiteV1 = string;
-interface IgnoredWebsiteV2 {
-  id: string;
-  website: string;
-}
-interface IgnoredWebsiteV3 { // [!code ++]
-  id: string; // [!code ++]
-  website: string; // [!code ++]
-  enabled: boolean; // [!code ++]
-} // [!code ++]
-
-export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code --]
-export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV3[]>( // [!code ++]
-  'local:ignoredWebsites',
-  {
-    defaultValue: [],
-    version: 2, // [!code --]
-    version: 3, // [!code ++]
-    migrations: {
-      // Ran when migrating from v1 to v2
-      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => {
-        return websites.map((website) => ({ id: nanoid(), website }));
-      },
-      // Ran when migrating from v2 to v3 // [!code ++]
-      3: (websites: IgnoredWebsiteV2[]): IgnoredWebsiteV3[] => { // [!code ++]
-        return websites.map((website) => ({ ...website, enabled: true })); // [!code ++]
-      }, // [!code ++]
-    },
-  },
-);
+```ts [wxt/browser]
+const installDate = await storage.get('local:installDate');
+await storage.setItem('key', 'value');
 ```

 :::

-:::info
-Internally, this uses a metadata property called `v` to track the value's current version.
-:::
+Use the `"local:"`, `"session:"`, `"sync:"`, and `"managed:"` prefixes to specify which storage area to use.

-In this case, we thought that the ignored website list might change in the future, and were able to setup a versioned storage item from the start.
+## Customization

-Realistically, you won't know a item needs versioned until you need to change it's schema. Thankfully, it's simple to add versioning to an unversioned storage item.
+WXT also provides a driver for `unstorage`. To customize the `storage` object's setup, like removing the prefixes and using a single storage area, you can create your own storage:

-When a previous version isn't found, WXT assumes the version was `1`. That means you just need to set `version: 2` and add a migration for `2`, and it will just work!
-
-Lets look at the same ignored websites example from before, but start with an unversioned item this time:
-
-:::code-group
-
-```ts [Unversioned]
-export const ignoredWebsites = storage.defineItem<string[]>(
-  'local:ignoredWebsites',
-  {
-    defaultValue: [],
-  },
-);
-```
-
-<!-- prettier-ignore -->
-```ts [v2]
-import { nanoid } from 'nanoid'; // [!code ++]
-
-// Retroactively add a type for the first version // [!code ++]
-type IgnoredWebsiteV1 = string; // [!code ++]
-interface IgnoredWebsiteV2 { // [!code ++]
-  id: string; // [!code ++]
-  website: string; // [!code ++]
-} // [!code ++]
-
-export const ignoredWebsites = storage.defineItem<string[]>( // [!code --]
-export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code ++]
-  'local:ignoredWebsites',
-  {
-    defaultValue: [],
-    version: 2, // [!code ++]
-    migrations: { // [!code ++]
-      // Ran when migrating from v1 to v2 // [!code ++]
-      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => { // [!code ++]
-        return websites.map((website) => ({ id: nanoid(), website })); // [!code ++]
-      }, // [!code ++]
-    }, // [!code ++]
-  },
-);
+```ts
+// storage.ts
+export default createStorage({
+  driver: webExtensionDriver({ storageArea: 'local' }),
+});
 ```

+:::note
+`wxt/browser` re-exports all of `unstorage`, which is where `createStorage` comes from.
 :::
-
-### Running Migrations
-
-As soon as `storage.defineItem` is called, WXT checks if migrations need to be ran, and if so, runs them. Calls to get or update the storage item's value or metadata (`getValue`, `setValue`, `removeValue`, `getMeta`, etc) will automatically wait for the migration process to finish before actually reading or writing values.
@@ -1,25 +1,162 @@
 # Testing

-## Official Frameworks
+WXT provides several utils for writing tests.

-WXT officially supports [Vitest](https://vitest.dev/) for unit tests and either [Playwright](https://playwright.dev/) or [Puppeteer](https://pptr.dev/) for E2E tests against Chromium browsers.
+## Unit tests

-For details setting up each testing framework, see the official examples:
+If you're using auto-imports (enabled by default), [Vitest](https://vitest.dev/) is the only testing framework that supports them.

-<ExampleList tag="testing" />
+If you want to use a different testing library/framework (like Jest, mocha, node:test, etc), you can keep using it, but you have two options:

-### Unofficial Frameworks
+1. Switch to Vitest (recommended)
+2. Configure the testing library manually
+   - Disable auto-imports by setting `imports: false` in your `wxt.config.ts` file
+   - Manually add globals normally provided by WXT (like `__BROWSER__`) that you consume to the global scope before accessing them (`globalThis.__BROWSER__ = "chrome"`)

-Puppeteer and Playwright are the only E2E test runners that support Chrome Extensions. There are no other options at the time of writing.
+### Vitest Setup

-There are other options for unit tests however, like [Jest](https://jestjs.io/), [Mocha](https://mochajs.org/), or [`node:test`](https://nodejs.org/api/test.html). **_WXT does not claim to support any of them_** because none of them support all of WXT's features, like TypeScript or auto-imports.
+Install vitest and add the `WxtVitest` plugin to your `vitest.config.ts` file.

-If you want to try to use a different framework for unit tests, you will need to configure the environment manually:
+```sh
+pnpm i -D vitest
+```

- **Auto-imports**: Add `unimport` to your test environment or disable them by setting `imports: false` in your `wxt.config.ts` file
- **`browser` mock**: Mock the `webextension-polyfill` module globally with `wxt/dist/virtual/mock-browser.js`
- **[Remote Code Bundling](/guide/remote-code)**: If you use it, configure your environment to handle the `url:` module prefix
- **Global Variables**: If you consume them, manually define globals provided by WXT (like `import.meta.env.BROWSER`) by adding them to the global scope before accessing them (`import.meta.env.BROWSER = "chrome"`)
- **Import paths**: If you use the `@/` or `~/` path aliases, add them to your test environment
+```ts
+// <root>/vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { WxtVitest } from 'wxt/testing';

-[Here's how Vitest is configured](https://github.com/wxt-dev/wxt/blob/main/src/testing/wxt-vitest-plugin.ts) for reference.
+export default defineConfig({
+  plugins: [WxtVitest()],
+  test: {
+    server: {
+      deps: {
+        // Add any dependencies that import webextension-polyfill here, otherwise tests will attempt to import the real polyfill, breaking the
+        // TODO: Auto-detect these dependencies inside `WxtVitest` so maintaining this list manually isn't necessary
+        inline: [...],
+      },
+    },
+  },
+});
+```
+
+And that's it. You're ready to start writing tests.
+
+### Writing Tests
+
+Here's a very basic test, written with a few different testing libraries, with a few different approaches for mocking the `browser` global.
+
+:::code-group
+
+```ts [Vitest]
+import { describe, it, expect, vi } from 'vitest';
+
+function logRuntimeId() {
+  // Vitest automatically mocks "browser" with "fakeBrowser"
+  console.log(browser.runtime.id);
+}
+
+describe('logRuntimeId', () => {
+  it("should log the extension's runtime ID", () => {
+    // Set a known ID on fakeBrowser for the test
+    const id = 'some-runtime-id';
+    fakeBrowser.runtime.id = id;
+    const logSpy = vi.spyOn(console, 'log');
+
+    logRuntimeId();
+
+    expect(logSpy).toBeCalledWith(id);
+  });
+});
+```
+
+```ts [Jest - Manual Mock]
+import { fakeBrowser } from 'wxt/testing';
+import { browser } from 'wxt/browser';
+
+function logRuntimeId() {
+  console.log(browser.runtime.id);
+}
+
+// Manually mock
+jest.mock('wxt/browser', () => {
+  const { fakeBrowser } = require('wxt/testing');
+  return { browser: fakeBrowser };
+});
+
+describe('logRuntimeId', () => {
+  it("should log the extension's runtime ID", () => {
+    // Set a known ID on fakeBrowser for the test
+    const id = 'some-runtime-id';
+    fakeBrowser.runtime.id = id;
+    const logSpy = jest.spyOn(console, 'log');
+
+    logRuntimeId();
+
+    expect(logSpy).toBeCalledWith(id);
+  });
+});
+```
+
+```ts [node:test - Parameterized]
+import { describe, it, mock } from 'node:test';
+import { assert } from 'node:assert';
+import { fakeBrowser } from 'wxt/testing';
+import { browser } from 'wxt/browser';
+
+// Add browser as a parameter so fakeBrowser can be passed instead of browser
+function logRuntimeId(browser = browser) {
+  console.log(browser.runtime.id);
+}
+
+describe('logRuntimeId', () => {
+  it("should log the extension's runtime ID", () => {
+    // Set a known ID on fakeBrowser for the test
+    const id = 'some-runtime-id';
+    fakeBrowser.runtime.id = id;
+    console.log = mock.fn();
+
+    // pass in fakeBrowser during tests
+    logRuntimeId(fakeBrowser);
+
+    assert.deepStrictEqual(console.log.mock.calls[0].arguments, [id]);
+  });
+});
+```
+
+:::
+
+:::warning
+Without mocking the `browser` variable, you'll see errors like this:
+
+```
+This script should only be loaded in a browser extension.
+```
+
+:::
+
+WXT provides an in-memory, partial implementation of `browser`, [`fakeBrowser`](/api/wxt/testing/variables/fakeBrowser), from the [`@webext-core/fake-browser`](https://webext-core.aklinker1.io/guide/fake-browser/) package. `fakeBrowser` works with all testing frameworks/libraries. See their docs for a list of [implemented APIs](https://webext-core.aklinker1.io/guide/fake-browser/implemented-apis.html) and more example tests.
+
+## E2E Tests
+
+WXT does not provide any utils for running E2E tests. There are two libraries you can use to run E2E tests for any chrome extension.
+
+- [`playwright`](https://playwright.dev/docs/chrome-extensions) (recommended) - "A high-level API to automate web browsers"
+- [`puppeteer`](https://pptr.dev/guides/chrome-extensions) - "A high-level API to control headless Chrome over the DevTools Protocol"
+
+:::info
+Note that both only support running tests on Chrome.
+:::
+
+Before running tests with either of these tools, you must build the extension with `wxt build` and then load the extension from the output directory in a new tab.
+
+To test an extension's UI, like the popup or options page, you'll need to know the extension's ID to open the URL directly.
+
+> _chrome-extension://`browser.runtime.id`/popup.html_
+
+- Playwright provides an API to get your extension ID after it has been installed. [See their docs](https://playwright.dev/docs/chrome-extensions#testing).
+- Puppeteer requires you know the ID before installing the extension, so you can hard code it into the URLs you open. Follow [Chrome's guide](https://developer.chrome.com/docs/extensions/mv3/manifest/key/) to setup a consistent runtime id.
+
+:::info
+You cannot test popups in their normal popup window, you have to open them in a tab.
+:::
@@ -6,7 +6,7 @@ title: Next-gen Web Extension Framework
 hero:
  name: WXT
  text: Next-gen Web Extension Framework
-  tagline: An open source tool that makes Chrome Extension development faster than ever before.
+  tagline: An open source tool that makes Chrome Extension devlopment faster than ever before.
  image:
    src: /hero-logo.svg
    alt: WXT
@@ -47,9 +47,11 @@ features:
    details: Nuxt-like auto-imports to speed up development.
    link: /guide/auto-imports
    linkText: Read docs
-  - icon: 🤖
-    title: Automated Publishing
-    details: Automatically zip, upload, submit, and publish extensions.
+  - icon: ⬇️
+    title: Bundle Remote Code
+    details: Downloads and bundles remote code imported from URLs.
+    link: /guide/remote-code
+    linkText: Read docs
  - icon: 🎨
    title: Frontend Framework Agnostic
    details: Works with any front-end framework with a Vite plugin.
@@ -62,12 +64,10 @@ features:
    linkText: See templates
  - icon: 📏
    title: Bundle Analysis
-    details: Tools for analyzing the final extension bundle and minimizing your extension's size.
-  - icon: ⬇️
-    title: Bundle Remote Code
-    details: Downloads and bundles remote code imported from URLs.
-    link: /guide/remote-code
-    linkText: Read docs
+    details: Tools for analyizing the final extension bundle and minimizing your extension's size.
+  - icon: 🤖
+    title: Automated Publishing
+    details: 'Coming soon. Automatically zip, upload, and release extensions.'
 ---

 <section class="vp-doc">
@@ -1,92 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { TestProject } from '../utils';
-import { resetBundleIncrement } from '~/core/builders/vite/plugins';
-
-describe('Analysis', () => {
-  beforeEach(() => {
-    resetBundleIncrement();
-  });
-
-  it('should output a stats.html with no part files by default', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html');
-    project.addFile('entrypoints/options.html');
-    project.addFile(
-      'entrypoints/background.ts',
-      'export default defineBackground(() => {});',
-    );
-
-    await project.build({
-      analysis: {
-        enabled: true,
-      },
-    });
-
-    expect(await project.fileExists('stats.html')).toBe(true);
-    expect(await project.fileExists('.output/chrome-mv3/stats-0.json')).toBe(
-      false,
-    );
-  });
-
-  it('should save part files when requested', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html');
-    project.addFile('entrypoints/options.html');
-    project.addFile(
-      'entrypoints/background.ts',
-      'export default defineBackground(() => {});',
-    );
-
-    await project.build({
-      analysis: {
-        enabled: true,
-        keepArtifacts: true,
-      },
-    });
-
-    expect(await project.fileExists('stats.html')).toBe(true);
-    expect(await project.fileExists('stats-0.json')).toBe(true);
-    expect(await project.fileExists('stats-1.json')).toBe(true);
-  });
-
-  it('should support customizing the stats output directory', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html');
-    project.addFile('entrypoints/options.html');
-    project.addFile(
-      'entrypoints/background.ts',
-      'export default defineBackground(() => {});',
-    );
-
-    await project.build({
-      analysis: {
-        enabled: true,
-        outputFile: 'stats/bundle.html',
-      },
-    });
-
-    expect(await project.fileExists('stats/bundle.html')).toBe(true);
-  });
-
-  it('should place artifacts next to the custom output file', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html');
-    project.addFile('entrypoints/options.html');
-    project.addFile(
-      'entrypoints/background.ts',
-      'export default defineBackground(() => {});',
-    );
-
-    await project.build({
-      analysis: {
-        enabled: true,
-        outputFile: 'stats/bundle.html',
-        keepArtifacts: true,
-      },
-    });
-
-    expect(await project.fileExists('stats/bundle.html')).toBe(true);
-    expect(await project.fileExists('stats/bundle-0.json')).toBe(true);
-    expect(await project.fileExists('stats/bundle-1.json')).toBe(true);
-  });
-});
@@ -7,7 +7,7 @@ describe('Auto Imports', () => {
      const project = new TestProject();
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.prepare();
+      await project.build();

      expect(await project.serializeFile('.wxt/types/imports.d.ts'))
        .toMatchInlineSnapshot(`
@@ -20,15 +20,24 @@ describe('Auto Imports', () => {
            const InvalidMatchPattern: typeof import('wxt/sandbox')['InvalidMatchPattern']
            const MatchPattern: typeof import('wxt/sandbox')['MatchPattern']
            const browser: typeof import('wxt/browser')['browser']
-            const createIframeUi: typeof import('wxt/client')['createIframeUi']
-            const createIntegratedUi: typeof import('wxt/client')['createIntegratedUi']
-            const createShadowRootUi: typeof import('wxt/client')['createShadowRootUi']
+            const builtinDrivers: typeof import('wxt/storage')['builtinDrivers']
+            const createContentScriptIframe: typeof import('wxt/client')['createContentScriptIframe']
+            const createContentScriptUi: typeof import('wxt/client')['createContentScriptUi']
+            const createStorage: typeof import('wxt/storage')['createStorage']
            const defineBackground: typeof import('wxt/sandbox')['defineBackground']
            const defineConfig: typeof import('wxt')['defineConfig']
            const defineContentScript: typeof import('wxt/sandbox')['defineContentScript']
+            const defineDriver: typeof import('wxt/storage')['defineDriver']
            const defineUnlistedScript: typeof import('wxt/sandbox')['defineUnlistedScript']
            const fakeBrowser: typeof import('wxt/testing')['fakeBrowser']
+            const joinKeys: typeof import('wxt/storage')['joinKeys']
+            const normalizeBaseKey: typeof import('wxt/storage')['normalizeBaseKey']
+            const normalizeKey: typeof import('wxt/storage')['normalizeKey']
+            const prefixStorage: typeof import('wxt/storage')['prefixStorage']
+            const restoreSnapshot: typeof import('wxt/storage')['restoreSnapshot']
+            const snapshot: typeof import('wxt/storage')['snapshot']
            const storage: typeof import('wxt/storage')['storage']
+            const webExtensionDriver: typeof import('wxt/storage')['webExtensionDriver']
          }
          "
        `);
@@ -38,14 +47,14 @@ describe('Auto Imports', () => {
      const project = new TestProject();
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.prepare();
+      await project.build();

      expect(await project.serializeFile('.wxt/wxt.d.ts'))
        .toMatchInlineSnapshot(`
          ".wxt/wxt.d.ts
          ----------------------------------------
          // Generated by wxt
-          /// <reference types="wxt/vite-builder-env" />
+          /// <reference types="vite/client" />
          /// <reference types="./types/imports.d.ts" />
          /// <reference types="./types/paths.d.ts" />
          /// <reference types="./types/i18n.d.ts" />
@@ -63,7 +72,7 @@ describe('Auto Imports', () => {
      });
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.prepare();
+      await project.build();

      expect(await project.fileExists('.wxt/types/imports.d.ts')).toBe(false);
    });
@@ -75,7 +84,7 @@ describe('Auto Imports', () => {
      });
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.prepare();
+      await project.build();

      expect(
        await project.serializeFile('.wxt/wxt.d.ts'),
@@ -84,7 +93,7 @@ describe('Auto Imports', () => {
        ".wxt/wxt.d.ts
        ----------------------------------------
        // Generated by wxt
-        /// <reference types="wxt/vite-builder-env" />
+        /// <reference types="vite/client" />
        /// <reference types="./types/paths.d.ts" />
        /// <reference types="./types/i18n.d.ts" />
        /// <reference types="./types/globals.d.ts" />
@@ -93,82 +102,4 @@ describe('Auto Imports', () => {
      );
    });
  });
-
-  describe('eslintrc', () => {
-    it('should output the globals list for ESLint to consume', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/popup.html', `<html></html>`);
-
-      await project.prepare({
-        imports: {
-          eslintrc: {
-            enabled: true,
-          },
-        },
-      });
-
-      expect(await project.serializeFile('.wxt/eslintrc-auto-import.json'))
-        .toMatchInlineSnapshot(`
-          ".wxt/eslintrc-auto-import.json
-          ----------------------------------------
-          {
-            "globals": {
-              "ContentScriptContext": true,
-              "InvalidMatchPattern": true,
-              "MatchPattern": true,
-              "browser": true,
-              "createIframeUi": true,
-              "createIntegratedUi": true,
-              "createShadowRootUi": true,
-              "defineBackground": true,
-              "defineConfig": true,
-              "defineContentScript": true,
-              "defineUnlistedScript": true,
-              "fakeBrowser": true,
-              "storage": true
-            }
-          }
-          "
-        `);
-    });
-
-    it('should allow customizing the output', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/popup.html', `<html></html>`);
-
-      await project.prepare({
-        imports: {
-          eslintrc: {
-            enabled: true,
-            filePath: project.resolvePath('example.json'),
-            globalsPropValue: 'readonly',
-          },
-        },
-      });
-
-      expect(await project.serializeFile('example.json'))
-        .toMatchInlineSnapshot(`
-          "example.json
-          ----------------------------------------
-          {
-            "globals": {
-              "ContentScriptContext": "readonly",
-              "InvalidMatchPattern": "readonly",
-              "MatchPattern": "readonly",
-              "browser": "readonly",
-              "createIframeUi": "readonly",
-              "createIntegratedUi": "readonly",
-              "createShadowRootUi": "readonly",
-              "defineBackground": "readonly",
-              "defineConfig": "readonly",
-              "defineContentScript": "readonly",
-              "defineUnlistedScript": "readonly",
-              "fakeBrowser": "readonly",
-              "storage": "readonly"
-            }
-          }
-          "
-        `);
-    });
-  });
 });
@@ -1,99 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { TestProject } from '../utils';
-import { WxtHooks } from '~/types';
-
-const hooks: WxtHooks = {
-  ready: vi.fn(),
-  'build:before': vi.fn(),
-  'build:done': vi.fn(),
-  'build:manifestGenerated': vi.fn(),
-  'entrypoints:resolved': vi.fn(),
-  'entrypoints:grouped': vi.fn(),
-};
-
-function expectHooksToBeCalled(called: Record<keyof WxtHooks, boolean>) {
-  Object.keys(hooks).forEach((key) => {
-    const hookName = key as keyof WxtHooks;
-    const times = called[hookName] ? 1 : 0;
-    expect(
-      hooks[hookName],
-      `Expected "${hookName}" to be called ${times} time(s)`,
-    ).toBeCalledTimes(called[hookName] ? 1 : 0);
-  });
-}
-
-describe('Hooks', () => {
-  beforeEach(() => {
-    Object.values(hooks).forEach((fn) => fn.mockReset());
-  });
-
-  it('prepare should call hooks', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html', '<html></html>');
-
-    await project.prepare({ hooks });
-
-    expectHooksToBeCalled({
-      ready: true,
-      'build:before': false,
-      'build:done': false,
-      'build:manifestGenerated': false,
-      'entrypoints:grouped': false,
-      'entrypoints:resolved': true,
-    });
-  });
-
-  it('build should call hooks', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html', '<html></html>');
-
-    await project.build({ hooks });
-
-    expectHooksToBeCalled({
-      ready: true,
-      'build:before': true,
-      'build:done': true,
-      'build:manifestGenerated': true,
-      'entrypoints:grouped': true,
-      'entrypoints:resolved': true,
-    });
-  });
-
-  it('zip should call hooks', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html', '<html></html>');
-
-    await project.zip({ hooks });
-
-    expectHooksToBeCalled({
-      ready: true,
-      'build:before': true,
-      'build:done': true,
-      'build:manifestGenerated': true,
-      'entrypoints:grouped': true,
-      'entrypoints:resolved': true,
-    });
-  });
-
-  it('server.start should call hooks', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/popup.html', '<html></html>');
-
-    const server = await project.startServer({
-      hooks,
-      runner: {
-        disabled: true,
-      },
-    });
-    await server.stop();
-
-    expectHooksToBeCalled({
-      ready: true,
-      'build:before': true,
-      'build:done': true,
-      'build:manifestGenerated': true,
-      'entrypoints:grouped': true,
-      'entrypoints:resolved': true,
-    });
-  });
-});
@@ -1,7 +1,556 @@
 import { describe, it, expect } from 'vitest';
 import { TestProject } from '../utils';

+// TODO: move to unit tests to speed this up - this doesn't have to be in E2E tests
+
 describe('Manifest Content', () => {
+  describe('popup', () => {
+    const popupContent = (type?: 'browser_action' | 'page_action') => `
+      <html>
+        <head>
+          ${type == null ? '' : `<meta name="manifest.type" content="${type}">`}
+          <meta name="manifest.default_icon" content="{ '16': '/icon/16.png' }">
+          <title>Default Title</title>
+        </head>
+      </html>
+    `;
+
+    it('should include an action for mv3', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/popup.html', popupContent());
+
+      await project.build();
+
+      const manifest = await project.getOutputManifest();
+      expect(manifest.action).toEqual({
+        default_icon: { '16': '/icon/16.png' },
+        default_title: 'Default Title',
+        default_popup: 'popup.html',
+      });
+    });
+
+    it.each([
+      [undefined, 'browser_action'],
+      ['browser_action', 'browser_action'],
+      ['page_action', 'page_action'],
+    ] as const)(
+      'should include a browser_action for mv2',
+      async (type, expectedType) => {
+        const project = new TestProject();
+        project.addFile('entrypoints/popup.html', popupContent(type));
+
+        await project.build({ manifestVersion: 2 });
+
+        const manifest = await project.getOutputManifest(
+          '.output/chrome-mv2/manifest.json',
+        );
+        expect(manifest[expectedType]).toEqual({
+          default_icon: { '16': '/icon/16.png' },
+          default_title: 'Default Title',
+          default_popup: 'popup.html',
+        });
+      },
+    );
+  });
+
+  describe('options', () => {
+    const optionsContent = `
+      <html>
+        <head>
+          <meta name="manifest.open_in_tab" content="false">
+          <meta name="manifest.chrome_style" content="true">
+          <meta name="manifest.browser_style" content="true">
+        </head>
+      </html>
+    `;
+
+    it('should include a options_ui and chrome_style for chrome', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/options.html', optionsContent);
+
+      await project.build();
+      const manifest = await project.getOutputManifest();
+
+      expect(manifest.options_ui).toEqual({
+        open_in_tab: false,
+        chrome_style: true,
+        page: 'options.html',
+      });
+    });
+
+    it('should include a options_ui and browser_style for firefox', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/options.html', optionsContent);
+
+      await project.build({ browser: 'firefox' });
+      const manifest = await project.getOutputManifest(
+        '.output/firefox-mv2/manifest.json',
+      );
+
+      expect(manifest.options_ui).toEqual({
+        open_in_tab: false,
+        browser_style: true,
+        page: 'options.html',
+      });
+    });
+  });
+
+  describe('background', () => {
+    const backgroundContent = `
+      export default defineBackground({
+        persistent: true,
+        type: "module",
+        main: () => {},
+      })
+    `;
+
+    it.each(['chrome', 'safari'])(
+      'should include scripts and persistent for %s mv2',
+      async (browser) => {
+        const project = new TestProject();
+        project.addFile('entrypoints/background.ts', backgroundContent);
+
+        await project.build({ browser, manifestVersion: 2 });
+        const manifest = await project.getOutputManifest(
+          `.output/${browser}-mv2/manifest.json`,
+        );
+
+        expect(manifest.background).toEqual({
+          persistent: true,
+          scripts: ['background.js'],
+        });
+      },
+    );
+
+    it.each(['chrome', 'safari'])(
+      'should include a service worker and type for %s mv3',
+      async (browser) => {
+        const project = new TestProject();
+        project.addFile('entrypoints/background.ts', backgroundContent);
+
+        await project.build({ browser, manifestVersion: 3 });
+        const manifest = await project.getOutputManifest(
+          `.output/${browser}-mv3/manifest.json`,
+        );
+
+        expect(manifest.background).toEqual({
+          type: 'module',
+          service_worker: 'background.js',
+        });
+      },
+    );
+
+    it('should include a background script and type for firefox mv3', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/background.ts', backgroundContent);
+
+      await project.build({ browser: 'firefox', manifestVersion: 3 });
+      const manifest = await project.getOutputManifest(
+        '.output/firefox-mv3/manifest.json',
+      );
+
+      expect(manifest.background).toEqual({
+        type: 'module',
+        scripts: ['background.js'],
+      });
+    });
+
+    it('should include a background script and persistent for firefox mv2', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/background.ts', backgroundContent);
+
+      await project.build({ browser: 'firefox', manifestVersion: 2 });
+      const manifest = await project.getOutputManifest(
+        '.output/firefox-mv2/manifest.json',
+      );
+
+      expect(manifest.background).toEqual({
+        persistent: true,
+        scripts: ['background.js'],
+      });
+    });
+  });
+
+  describe('icons', () => {
+    it('should auto-discover icons with the correct name', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/unlisted.html');
+      project.addFile('public/icon-16.png');
+      project.addFile('public/icon/32.png');
+      project.addFile('public/icon@48w.png');
+      project.addFile('public/icon-64x64.png');
+      project.addFile('public/icon@96.png');
+      project.addFile('public/icons/128x128.png');
+
+      await project.build();
+      const manifest = await project.getOutputManifest();
+
+      expect(manifest.icons).toEqual({
+        '16': 'icon-16.png',
+        '32': 'icon/32.png',
+        '48': 'icon@48w.png',
+        '64': 'icon-64x64.png',
+        '96': 'icon@96.png',
+        '128': 'icons/128x128.png',
+      });
+    });
+
+    it('should return undefined when no icons are found', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/unlisted.html');
+      project.addFile('public/logo.png');
+      project.addFile('public/icon.jpeg');
+
+      await project.build();
+      const manifest = await project.getOutputManifest();
+
+      expect(manifest.icons).toBeUndefined();
+    });
+
+    it('should allow icons to be overwritten from the wxt.config.ts file', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/unlisted.html');
+      project.addFile('public/icon-16.png');
+      project.addFile('public/icon-32.png');
+      project.addFile('public/logo-16.png');
+      project.addFile('public/logo-32.png');
+      project.addFile('public/logo-48.png');
+
+      const icons = {
+        '16': 'logo-16.png',
+        '32': 'logo-32.png',
+        '48': 'logo-48.png',
+      };
+      project.setConfigFileConfig({
+        manifest: {
+          icons,
+        },
+      });
+
+      await project.build();
+      const manifest = await project.getOutputManifest();
+
+      expect(manifest.icons).toEqual(icons);
+    });
+  });
+
+  describe('content_scripts', () => {
+    it('should group content scripts and styles together based on their manifest properties', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/one.content/index.ts',
+        `import "./style.css";
+        export default defineContentScript({
+          matches: ["*://google.com/*"],
+          main: () => {},
+        })`,
+      );
+      project.addFile(
+        'entrypoints/one.content/style.css',
+        `body { color: red }`,
+      );
+      project.addFile(
+        'entrypoints/two.content/index.ts',
+        `import "./style.css";
+        export default defineContentScript({
+          matches: ["*://google.com/*"],
+          runAt: "document_end",
+          main: () => {},
+        })`,
+      );
+      project.addFile(
+        'entrypoints/two.content/style.css',
+        `body { color: green }`,
+      );
+      project.addFile(
+        'entrypoints/three.content/index.ts',
+        `import "./style.css";
+        export default defineContentScript({
+          matches: ["*://google.com/*"],
+          runAt: "document_end",
+          main: () => {},
+        })`,
+      );
+      project.addFile(
+        'entrypoints/three.content/style.css',
+        `body { color: blue }`,
+      );
+      project.addFile(
+        'entrypoints/four.content/index.ts',
+        `import "./style.css";
+        export default defineContentScript({
+          matches: ["*://duckduckgo.com/*"],
+          runAt: "document_end",
+          main: () => {},
+        })`,
+      );
+      project.addFile(
+        'entrypoints/four.content/style.css',
+        `body { color: yellow }`,
+      );
+
+      await project.build();
+
+      const manifest = await project.getOutputManifest();
+
+      expect(manifest.content_scripts).toContainEqual({
+        matches: ['*://duckduckgo.com/*'],
+        run_at: 'document_end',
+        css: ['content-scripts/four.css'],
+        js: ['content-scripts/four.js'],
+      });
+      expect(manifest.content_scripts).toContainEqual({
+        matches: ['*://google.com/*'],
+        run_at: 'document_end',
+        css: ['content-scripts/three.css', 'content-scripts/two.css'],
+        js: ['content-scripts/three.js', 'content-scripts/two.js'],
+      });
+      expect(manifest.content_scripts).toContainEqual({
+        matches: ['*://google.com/*'],
+        css: ['content-scripts/one.css'],
+        js: ['content-scripts/one.js'],
+      });
+    });
+
+    it('should add to any content scripts declared in wxt.config.ts', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/one.content/index.ts',
+        `export default defineContentScript({
+          matches: ["*://google.com/*"],
+          main: () => {},
+        })`,
+      );
+      project.addFile(
+        'entrypoints/two.content/style.css',
+        `body {
+          background-color: red;
+        }`,
+      );
+      project.setConfigFileConfig({
+        manifest: {
+          content_scripts: [
+            {
+              css: ['content-scripts/two.css'],
+              matches: ['*://*.google.com/*'],
+            },
+          ],
+        },
+      });
+
+      await project.build();
+
+      const manifest = await project.getOutputManifest();
+
+      expect(manifest.content_scripts).toContainEqual({
+        css: ['content-scripts/two.css'],
+        matches: ['*://*.google.com/*'],
+      });
+      expect(manifest.content_scripts).toContainEqual({
+        matches: ['*://google.com/*'],
+        js: ['content-scripts/one.js'],
+      });
+    });
+
+    it('should add a CSS entry when cssInjectionMode is undefined', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/content/style.css',
+        'body { background-color: red; }',
+      );
+      project.addFile(
+        'entrypoints/content/index.ts',
+        `import "./style.css";
+
+        export default defineContentScript({
+          matches: ["https://*.google.com/*"],
+
+          main() {},
+        });`,
+      );
+      await project.build();
+
+      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
+        .toMatchInlineSnapshot(`
+          ".output/chrome-mv3/manifest.json
+          ----------------------------------------
+          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"css":["content-scripts/content.css"],"js":["content-scripts/content.js"]}]}"
+        `);
+    });
+
+    it('should add a CSS entry when cssInjectionMode is "manifest"', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/content/style.css',
+        'body { background-color: red; }',
+      );
+      project.addFile(
+        'entrypoints/content/index.ts',
+        `import "./style.css";
+
+        export default defineContentScript({
+          matches: ["https://*.google.com/*"],
+          cssInjectionMode: "manifest",
+
+          main() {},
+        });`,
+      );
+      await project.build();
+
+      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
+        .toMatchInlineSnapshot(`
+          ".output/chrome-mv3/manifest.json
+          ----------------------------------------
+          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"css":["content-scripts/content.css"],"js":["content-scripts/content.js"]}]}"
+        `);
+    });
+
+    it('should not add an entry for CSS when cssInjectionMode is "manual"', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/content/style.css',
+        'body { background-color: red; }',
+      );
+      project.addFile(
+        'entrypoints/content/index.ts',
+        `import "./style.css";
+
+        export default defineContentScript({
+          matches: ["https://*.google.com/*"],
+          cssInjectionMode: "manual",
+
+          main() {},
+        });`,
+      );
+      await project.build();
+
+      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
+        .toMatchInlineSnapshot(`
+          ".output/chrome-mv3/manifest.json
+          ----------------------------------------
+          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}]}"
+        `);
+    });
+
+    it('should not add a content script entry for CSS when cssInjectionMode is "ui", but add a web_accessible_resources entry for MV2', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/content/style.css',
+        'body { background-color: red; }',
+      );
+      project.addFile(
+        'entrypoints/content/index.ts',
+        `import "./style.css";
+
+        export default defineContentScript({
+          matches: ["https://*.google.com/*"],
+          cssInjectionMode: "ui",
+
+          main() {},
+        });`,
+      );
+      await project.build({
+        manifestVersion: 2,
+      });
+
+      expect(await project.serializeFile('.output/chrome-mv2/manifest.json'))
+        .toMatchInlineSnapshot(`
+          ".output/chrome-mv2/manifest.json
+          ----------------------------------------
+          {"manifest_version":2,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}],"web_accessible_resources":["content-scripts/content.css"]}"
+        `);
+    });
+
+    it('should not add a content script entry for CSS when cssInjectionMode is "ui", but add a web_accessible_resources entry for MV3', async () => {
+      const project = new TestProject();
+      project.addFile(
+        'entrypoints/content/style.css',
+        'body { background-color: red; }',
+      );
+      project.addFile(
+        'entrypoints/content/index.ts',
+        `import "./style.css";
+
+        export default defineContentScript({
+          matches: ["https://*.google.com/*"],
+          cssInjectionMode: "ui",
+
+          main() {},
+        });`,
+      );
+      await project.build({
+        manifestVersion: 3,
+      });
+
+      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
+        .toMatchInlineSnapshot(`
+          ".output/chrome-mv3/manifest.json
+          ----------------------------------------
+          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}],"web_accessible_resources":[{"resources":["content-scripts/content.css"],"matches":["https://*.google.com/*"]}]}"
+        `);
+    });
+  });
+
+  it('should combine web accessible resources', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'entrypoints/content/style.css',
+      'body { background-color: red; }',
+    );
+    project.addFile(
+      'entrypoints/content/index.ts',
+      `import "./style.css";
+
+      export default defineContentScript({
+        matches: ["https://*.google.com/*"],
+        cssInjectionMode: "ui",
+
+        main() {},
+      });`,
+    );
+    project.setConfigFileConfig({
+      manifest: {
+        web_accessible_resources: [
+          { resources: ['one.png'], matches: ['https://one.com/*'] },
+        ],
+      },
+    });
+    await project.build();
+
+    expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
+      .toMatchInlineSnapshot(`
+        ".output/chrome-mv3/manifest.json
+        ----------------------------------------
+        {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","web_accessible_resources":[{"resources":["one.png"],"matches":["https://one.com/*"]},{"resources":["content-scripts/content.css"],"matches":["https://*.google.com/*"]}],"content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}]}"
+      `);
+  });
+
+  it('should respect the transformManifest option', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');
+    project.addFile(
+      'wxt.config.ts',
+      `import { defineConfig } from 'wxt';
+
+      export default defineConfig({
+        transformManifest(manifest) {
+          manifest.author = "Custom Author"
+        }
+      })`,
+    );
+
+    await project.build();
+
+    const output = await project.serializeFile(
+      '.output/chrome-mv3/manifest.json',
+    );
+    expect(output).toMatchInlineSnapshot(`
+      ".output/chrome-mv3/manifest.json
+      ----------------------------------------
+      {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","author":"Custom Author"}"
+    `);
+  });
+
  it.each([
    { browser: undefined, outDir: 'chrome-mv3', expected: undefined },
    { browser: 'chrome', outDir: 'chrome-mv3', expected: undefined },
@@ -30,4 +579,95 @@ describe('Manifest Content', () => {
      expect(safariManifest.background.persistent).toBe(expected);
    },
  );
+
+  describe('versions', () => {
+    it.each([
+      ['chrome', 3] as const,
+      ['safari', 2] as const,
+      ['edge', 3] as const,
+    ])(
+      'should include version_name on %s when it needs simplified',
+      async (browser, manifestVersion) => {
+        const project = new TestProject({
+          version: '1.0.0-alpha1',
+        });
+        project.addFile('entrypoints/unlisted.html');
+
+        await project.build({ browser, manifestVersion });
+        const manifest = await project.getOutputManifest(
+          `.output/${browser}-mv${manifestVersion}/manifest.json`,
+        );
+
+        expect(manifest.version).toBe('1.0.0');
+        expect(manifest.version_name).toBe('1.0.0-alpha1');
+      },
+    );
+
+    it.each([['firefox', 2] as const])(
+      "should not include a version_name on %s because the browser doesn't support it",
+      async (browser, manifestVersion) => {
+        const project = new TestProject({
+          version: '1.0.0-alpha1',
+        });
+        project.addFile('entrypoints/unlisted.html');
+
+        await project.build({ browser, manifestVersion });
+        const manifest = await project.getOutputManifest(
+          `.output/${browser}-mv${manifestVersion}/manifest.json`,
+        );
+
+        expect(manifest.version).toBe('1.0.0');
+        expect(manifest.version_name).toBeUndefined();
+      },
+    );
+
+    it.each([
+      ['chrome', 3] as const,
+      ['firefox', 2] as const,
+      ['safari', 3] as const,
+      ['edge', 3] as const,
+    ])(
+      'should not include the version_name if it is equal to version',
+      async (browser, manifestVersion) => {
+        const project = new TestProject({
+          version: '1.0.0.1',
+        });
+        project.addFile('entrypoints/unlisted.html');
+
+        await project.build({ browser, manifestVersion });
+        const manifest = await project.getOutputManifest(
+          `.output/${browser}-mv${manifestVersion}/manifest.json`,
+        );
+
+        expect(manifest.version).toBe('1.0.0.1');
+        expect(manifest.version_name).toBeUndefined();
+      },
+    );
+  });
+
+  it('should respect the action field in the manifest without a popup', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');
+    project.setConfigFileConfig({
+      manifest: {
+        action: {
+          default_title: 'Hello world',
+        },
+      },
+    });
+
+    await project.build();
+
+    expect(await project.getOutputManifest()).toMatchInlineSnapshot(`
+      {
+        "action": {
+          "default_title": "Hello world",
+        },
+        "description": "Example description",
+        "manifest_version": 3,
+        "name": "E2E Extension",
+        "version": "0.0.0",
+      }
+    `);
+  });
 });
@@ -227,169 +227,4 @@ describe('Output Directory Structure', () => {
      true,
    );
  });
-
-  it('should generate ESM background script when type=module', async () => {
-    const project = new TestProject();
-    project.addFile(
-      'utils/log.ts',
-      `export function logHello(name: string) {
-        console.log(\`Hello \${name}!\`);
-      }`,
-    );
-    project.addFile(
-      'entrypoints/background.ts',
-      `export default defineBackground({
-        type: "module",
-        main() {
-          logHello("background");
-        },
-      })`,
-    );
-    project.addFile(
-      'entrypoints/popup/index.html',
-      `<html>
-        <head>
-          <script type="module" src="./main.ts"></script>
-        </head>
-      </html>`,
-    );
-    project.addFile('entrypoints/popup/main.ts', `logHello('popup')`);
-
-    await project.build({
-      experimental: {
-        // Simplify the build output for comparison
-        includeBrowserPolyfill: false,
-      },
-      vite: () => ({
-        build: {
-          // Make output for snapshot readible
-          minify: false,
-        },
-      }),
-    });
-
-    expect(await project.serializeFile('.output/chrome-mv3/background.js'))
-      .toMatchInlineSnapshot(`
-        ".output/chrome-mv3/background.js
-        ----------------------------------------
-        import { l as logHello } from "./chunks/log-bezs0tt4.js";
-        function defineBackground(arg) {
-          if (typeof arg === "function")
-            return { main: arg };
-          return arg;
-        }
-        const definition = defineBackground({
-          type: "module",
-          main() {
-            logHello("background");
-          }
-        });
-        chrome;
-        function print(method, ...args) {
-          return;
-        }
-        var logger = {
-          debug: (...args) => print(console.debug, ...args),
-          log: (...args) => print(console.log, ...args),
-          warn: (...args) => print(console.warn, ...args),
-          error: (...args) => print(console.error, ...args)
-        };
-        try {
-          const res = definition.main();
-          if (res instanceof Promise) {
-            console.warn(
-              "The background's main() function return a promise, but it must be synchronous"
-            );
-          }
-        } catch (err) {
-          logger.error("The background crashed on startup!");
-          throw err;
-        }
-        "
-      `);
-  });
-
-  it('should generate IIFE background script when type=undefined', async () => {
-    const project = new TestProject();
-    project.addFile(
-      'utils/log.ts',
-      `export function logHello(name: string) {
-          console.log(\`Hello \${name}!\`);
-        }`,
-    );
-    project.addFile(
-      'entrypoints/background.ts',
-      `export default defineBackground({
-          main() {
-            logHello("background");
-          },
-        })`,
-    );
-    project.addFile(
-      'entrypoints/popup/index.html',
-      `<html>
-          <head>
-            <script type="module" src="./main.ts"></script>
-          </head>
-        </html>`,
-    );
-    project.addFile('entrypoints/popup/main.ts', `logHello('popup')`);
-
-    await project.build({
-      experimental: {
-        // Simplify the build output for comparison
-        includeBrowserPolyfill: false,
-      },
-      vite: () => ({
-        build: {
-          // Make output for snapshot readible
-          minify: false,
-        },
-      }),
-    });
-
-    expect(await project.serializeFile('.output/chrome-mv3/background.js'))
-      .toMatchInlineSnapshot(`
-        ".output/chrome-mv3/background.js
-        ----------------------------------------
-        (function() {
-          "use strict";
-          function defineBackground(arg) {
-            if (typeof arg === "function")
-              return { main: arg };
-            return arg;
-          }
-          function logHello(name) {
-            console.log(\`Hello \${name}!\`);
-          }
-          const definition = defineBackground({
-            main() {
-              logHello("background");
-            }
-          });
-          chrome;
-          function print(method, ...args) {
-            return;
-          }
-          var logger = {
-            debug: (...args) => print(console.debug, ...args),
-            log: (...args) => print(console.log, ...args),
-            warn: (...args) => print(console.warn, ...args),
-            error: (...args) => print(console.error, ...args)
-          };
-          try {
-            const res = definition.main();
-            if (res instanceof Promise) {
-              console.warn(
-                "The background's main() function return a promise, but it must be synchronous"
-              );
-            }
-          } catch (err) {
-            logger.error("The background crashed on startup!");
-            throw err;
-          }
-        })();
-        "
-      `);
-  });
 });
@@ -6,7 +6,7 @@ describe('TypeScript Project', () => {
    const project = new TestProject();
    project.addFile('entrypoints/unlisted.html');

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/types/globals.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -14,19 +14,16 @@ describe('TypeScript Project', () => {
      ----------------------------------------
      // Generated by wxt
      export {}
-      interface ImportMetaEnv {
-        readonly MANIFEST_VERSION: 2 | 3;
-        readonly BROWSER: string;
-        readonly CHROME: boolean;
-        readonly FIREFOX: boolean;
-        readonly SAFARI: boolean;
-        readonly EDGE: boolean;
-        readonly OPERA: boolean;
-        readonly COMMAND: "build" | "serve";
-        readonly ENTRYPOINT: string;
-      }
-      interface ImportMeta {
-        readonly env: ImportMetaEnv
+      declare global {
+        const __MANIFEST_VERSION__: 2 | 3;
+        const __BROWSER__: string;
+        const __IS_CHROME__: boolean;
+        const __IS_FIREFOX__: boolean;
+        const __IS_SAFARI__: boolean;
+        const __IS_EDGE__: boolean;
+        const __IS_OPERA__: boolean;
+        const __COMMAND__: "build" | "serve";
+        const __ENTRYPOINT__: string;
      }
      "
    `);
@@ -38,7 +35,7 @@ describe('TypeScript Project', () => {
    project.addFile('entrypoints/options.html');
    project.addFile('entrypoints/sandbox.html');

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/types/paths.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -52,10 +49,8 @@ describe('TypeScript Project', () => {
          | "/options.html"
          | "/popup.html"
          | "/sandbox.html"
-        type HtmlPublicPath = Extract<PublicPath, \`\${string}.html\`>
        export interface WxtRuntime extends Runtime.Static {
          getURL(path: PublicPath): string;
-          getURL(path: \`\${HtmlPublicPath}\${string}\`): string;
        }
      }
      "
@@ -103,7 +98,7 @@ describe('TypeScript Project', () => {
      },
    });

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/types/i18n.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -136,7 +131,7 @@ describe('TypeScript Project', () => {
            options?: GetMessageOptions,
          ): string;
          /**
-           * No message description.
+           * 
           *
           * "<browser.i18n.getUiLocale()>"
           */
@@ -225,14 +220,14 @@ describe('TypeScript Project', () => {
    const project = new TestProject();
    project.addFile('entrypoints/unlisted.html');

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/wxt.d.ts');
    expect(output).toMatchInlineSnapshot(`
      ".wxt/wxt.d.ts
      ----------------------------------------
      // Generated by wxt
-      /// <reference types="wxt/vite-builder-env" />
+      /// <reference types="vite/client" />
      /// <reference types="./types/imports.d.ts" />
      /// <reference types="./types/paths.d.ts" />
      /// <reference types="./types/i18n.d.ts" />
@@ -245,7 +240,7 @@ describe('TypeScript Project', () => {
    const project = new TestProject();
    project.addFile('entrypoints/unlisted.html');

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/tsconfig.json');
    expect(output).toMatchInlineSnapshot(`
@@ -289,7 +284,7 @@ describe('TypeScript Project', () => {
      srcDir: 'src',
    });

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/tsconfig.json');
    expect(output).toMatchInlineSnapshot(`
@@ -337,7 +332,7 @@ describe('TypeScript Project', () => {
      },
    });

-    await project.prepare();
+    await project.build();

    const output = await project.serializeFile('.wxt/tsconfig.json');
    expect(output).toMatchInlineSnapshot(`
@@ -107,29 +107,4 @@ describe('User Config', () => {
    });
    expect(withoutPolyfill).not.toBe(withPolyfill);
  });
-
-  it('should respect changing config files', async () => {
-    const project = new TestProject();
-    project.addFile(
-      'src/entrypoints/background.ts',
-      `export default defineBackground(
-        () => console.log('Hello background'),
-      );`,
-    );
-    project.addFile(
-      'test.config.ts',
-      `import { defineConfig } from 'wxt';
-      
-      export default defineConfig({
-        outDir: ".custom-output",
-        srcDir: "src",
-      });`,
-    );
-
-    await project.build({ configFile: 'test.config.ts' });
-
-    expect(
-      await project.fileExists('.custom-output/chrome-mv3/background.js'),
-    ).toBe(true);
-  });
 });
@@ -2,14 +2,7 @@ import { dirname, join, relative, resolve } from 'path';
 import fs from 'fs-extra';
 import glob from 'fast-glob';
 import { execaCommand } from 'execa';
-import {
-  InlineConfig,
-  UserConfig,
-  build,
-  createServer,
-  prepare,
-  zip,
-} from '../src';
+import { InlineConfig, UserConfig, build } from '../src';
 import { normalizePath } from '../src/core/utils/paths';
 import merge from 'lodash.merge';

@@ -70,41 +63,15 @@ export class TestProject {
    if (filename === 'wxt.config.ts') this.config = {};
  }

-  async prepare(config: InlineConfig = {}) {
-    await this.writeProjectToDisk();
-    await prepare({ ...config, root: this.root });
-  }
-
-  async build(config: InlineConfig = {}) {
-    await this.writeProjectToDisk();
-    await build({ ...config, root: this.root });
-  }
-
-  async zip(config: InlineConfig = {}) {
-    await this.writeProjectToDisk();
-    await zip({ ...config, root: this.root });
-  }
-
-  async startServer(config: InlineConfig = {}) {
-    await this.writeProjectToDisk();
-    const server = await createServer({ ...config, root: this.root });
-    await server.start();
-    return server;
-  }
-
  /**
-   * Call `path.resolve` relative to the project's root directory.
+   * Write the files to the test directory install dependencies, and build the project.
   */
-  resolvePath(...path: string[]): string {
-    return resolve(this.root, ...path);
-  }
-
-  private async writeProjectToDisk() {
+  async build(config: InlineConfig = {}) {
    if (this.config == null) this.setConfigFileConfig();

    for (const file of this.files) {
      const [name, content] = file;
-      const filePath = this.resolvePath(name);
+      const filePath = resolve(this.root, name);
      const fileDir = dirname(filePath);
      await fs.ensureDir(fileDir);
      await fs.writeFile(filePath, content ?? '', 'utf-8');
@@ -113,6 +80,7 @@ export class TestProject {
    await execaCommand('pnpm --ignore-workspace i --ignore-scripts', {
      cwd: this.root,
    });
+    await build({ ...config, root: this.root });
  }

  /**
@@ -147,13 +115,13 @@ export class TestProject {
    ignoreContentsOfFilenames?: string[],
  ): Promise<string> {
    const outputFiles = await glob('**/*', {
-      cwd: this.resolvePath(dir),
+      cwd: resolve(this.root, dir),
      ignore: ['**/node_modules', '**/.output'],
    });
    outputFiles.sort();
    const fileContents = [];
    for (const file of outputFiles) {
-      const path = this.resolvePath(dir, file);
+      const path = resolve(this.root, dir, file);
      const isContentIgnored = !!ignoreContentsOfFilenames?.find(
        (ignoredFile) => normalizePath(path).endsWith(ignoredFile),
      );
@@ -163,12 +131,12 @@ export class TestProject {
  }

  /**
-   * @param path An absolute path to a file or a path relative to the root.
+   * @param path An abosolute path to a file or a path relative to the root.
   * @param ignoreContents An optional boolean that, when true, causes this function to not print
   *                       the file contents.
   */
  async serializeFile(path: string, ignoreContents?: boolean): Promise<string> {
-    const absolutePath = this.resolvePath(path);
+    const absolutePath = resolve(this.root, path);
    return [
      normalizePath(relative(this.root, absolutePath)),
      ignoreContents ? '<contents-ignored>' : await fs.readFile(absolutePath),
@@ -176,12 +144,12 @@ export class TestProject {
  }

  fileExists(path: string): Promise<boolean> {
-    return fs.exists(this.resolvePath(path));
+    return fs.exists(resolve(this.root, path));
  }

  async getOutputManifest(
    path: string = '.output/chrome-mv3/manifest.json',
  ): Promise<any> {
-    return await fs.readJson(this.resolvePath(path));
+    return await fs.readJson(resolve(this.root, path));
  }
 }
@@ -1,7 +1,7 @@
 {
  "name": "wxt",
  "type": "module",
-  "version": "0.17.3",
+  "version": "0.12.2-alpha2",
  "description": "Next gen framework for developing web extensions",
  "engines": {
    "node": ">=18",
@@ -30,10 +30,7 @@
    "bin",
    "dist"
  ],
-  "bin": {
-    "wxt": "./bin/wxt.mjs",
-    "wxt-publish-extension": "./bin/wxt-publish-extension.cjs"
-  },
+  "bin": "./bin/wxt.mjs",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
@@ -79,13 +76,10 @@
        "types": "./dist/storage.d.cts",
        "default": "./dist/storage.cjs"
      }
-    },
-    "./vite-builder-env": {
-      "types": "./dist/vite-builder-env.d.ts"
    }
  },
  "scripts": {
-    "wxt": "tsx src/cli/index.ts",
+    "wxt": "tsx src/cli.ts",
    "build": "tsx scripts/build.ts",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
@@ -94,9 +88,9 @@
    "lint:package": "publint",
    "compile": "run-s -c compile:*",
    "compile:wxt": "tsc --noEmit",
-    "compile:virtual": "tsc --noEmit -p src/virtual",
+    "compile:virtual": "tsc --noEmit",
    "test": "vitest",
-    "test:coverage": "vitest run --coverage.enabled \"--coverage.include=src/**\" \"--coverage.exclude=src/core/utils/testing/**\" \"--coverage.exclude=**/*.d.ts\"",
+    "test:coverage": "vitest run --coverage",
    "prepare": "simple-git-hooks",
    "prepublish": "pnpm -s build",
    "docs:gen": "typedoc --options docs/typedoc.json",
@@ -106,10 +100,9 @@
    "sync-releases": "pnpx changelogen@latest gh release"
  },
  "dependencies": {
-    "@aklinker1/rollup-plugin-visualizer": "5.12.0",
    "@types/webextension-polyfill": "^0.10.5",
    "@webext-core/fake-browser": "^1.3.1",
-    "@webext-core/isolated-element": "^1.1.1",
+    "@webext-core/isolated-element": "^1.0.4",
    "@webext-core/match-patterns": "^1.0.3",
    "async-mutex": "^0.4.0",
    "c12": "^1.5.1",
@@ -117,28 +110,27 @@
    "chokidar": "^3.5.3",
    "consola": "^3.2.3",
    "defu": "^6.1.3",
-    "dequal": "^2.0.3",
    "esbuild": "^0.19.5",
    "fast-glob": "^3.3.1",
    "filesize": "^10.0.8",
    "fs-extra": "^11.1.1",
    "get-port": "^7.0.0",
    "giget": "^1.1.3",
-    "hookable": "^5.5.3",
+    "immer": "^10.0.3",
    "is-wsl": "^3.0.0",
    "jiti": "^1.21.0",
    "json5": "^2.2.3",
    "linkedom": "^0.16.1",
    "minimatch": "^9.0.3",
-    "natural-compare": "^1.4.0",
    "normalize-path": "^3.0.0",
    "ora": "^7.0.1",
    "picocolors": "^1.0.0",
    "prompts": "^2.4.2",
-    "publish-browser-extension": "^2.1.3",
+    "rollup-plugin-visualizer": "^5.9.2",
    "unimport": "^3.4.0",
-    "vite": "^5.1.3",
-    "web-ext-run": "^0.2.0",
+    "unstorage": "^1.9.0",
+    "vite": "^5.0.0",
+    "web-ext-run": "^0.1.0",
    "webextension-polyfill": "^0.10.0",
    "zip-dir": "^2.0.0"
  },
@@ -146,13 +138,12 @@
    "@faker-js/faker": "^8.3.1",
    "@types/fs-extra": "^11.0.4",
    "@types/lodash.merge": "^4.6.9",
-    "@types/natural-compare": "^1.4.3",
    "@types/node": "^20.10.3",
    "@types/normalize-path": "^3.0.2",
    "@types/prompts": "^2.4.9",
    "@vitest/coverage-v8": "^1.0.1",
    "execa": "^8.0.1",
-    "happy-dom": "^13.3.8",
+    "happy-dom": "^12.10.3",
    "lint-staged": "^15.2.0",
    "lodash.merge": "^4.6.2",
    "npm-run-all": "^4.1.5",
@@ -166,8 +157,8 @@
    "typedoc-plugin-markdown": "4.0.0-next.23",
    "typedoc-vitepress-theme": "1.0.0-next.3",
    "typescript": "^5.3.2",
-    "vitepress": "1.0.0-rc.34",
-    "vitest": "^1.2.2",
+    "vitepress": "1.0.0-rc.31",
+    "vitest": "^1.0.0",
    "vitest-mock-extended": "^1.3.1",
    "vue": "^3.3.10"
  },
@@ -29,9 +29,9 @@ const preset = {
 } satisfies tsup.Options;

 function spinnerPMap(configs: tsup.Options[]) {
-  let progress = 1;
+  let completed = 0;
  const updateSpinner = () => {
-    spinner.text = `${spinnerText} [${progress}/${configs.length}]`;
+    spinner.text = `${spinnerText} [${completed}/${configs.length}]`;
  };
  updateSpinner();

@@ -39,7 +39,7 @@ function spinnerPMap(configs: tsup.Options[]) {
    config,
    async (config) => {
      const res = await tsup.build(config);
-      progress++;
+      completed++;
      updateSpinner();
      return res;
    },
@@ -94,14 +94,9 @@ const config: tsup.Options[] = [
  {
    ...preset,
    entry: {
-      cli: 'src/cli/index.ts',
+      cli: 'src/cli.ts',
    },
    format: ['esm'],
-    banner: {
-      // Fixes dynamic require of nodejs modules. See https://github.com/wxt-dev/wxt/issues/355
-      // https://github.com/evanw/esbuild/issues/1921#issuecomment-1152991694
-      js: "import { createRequire } from 'module';const require = createRequire(import.meta.url);",
-    },
  },
 ];

@@ -111,9 +106,6 @@ await spinnerPMap(config).catch((err) => {
  process.exit(1);
 });

-// Copy "public" files that need shipped inside WXT
-await fs.copyFile('src/vite-builder-env.d.ts', 'dist/vite-builder-env.d.ts');
-
 spinner.clear().stop();

 const duration = Date.now() - startTime;
@@ -1,20 +1,11 @@
 import { fakeBrowser } from '@webext-core/fake-browser';
-import { describe, it, expect, beforeEach, vi, expectTypeOf } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { browser } from '~/browser';
-import { WxtStorageItem, storage } from '~/storage';
-
-/**
- * This works because fakeBrowser is synchronous, and is will finish any number of chained
- * calls within a single tick of the event loop, ie: a timeout of 0.
- */
-async function waitForMigrations() {
-  return new Promise((res) => setTimeout(res));
-}
+import { storage } from '~/storage';

 describe('Storage Utils', () => {
  beforeEach(() => {
    fakeBrowser.reset();
-    storage.unwatch();
  });

  describe.each(['local', 'sync', 'managed', 'session'] as const)(
@@ -24,86 +15,33 @@ describe('Storage Utils', () => {
        it('should return the value from the correct storage area', async () => {
          const expected = 123;
          await fakeBrowser.storage[storageArea].set({ count: expected });
-
-          const actual = await storage.getItem(`${storageArea}:count`);
-
-          expect(actual).toBe(expected);
-        });
-
-        it('should return the value if multiple : are use in the key', async () => {
-          const expected = 'value';
-          await fakeBrowser.storage[storageArea].set({ 'some:key': expected });
-
-          const actual = await storage.getItem(`${storageArea}:some:key`);
-
-          expect(actual).toBe(expected);
+          expect(await storage.getItem(`${storageArea}:count`)).toBe(expected);
        });

        it("should return null if the value doesn't exist", async () => {
-          const actual = await storage.getItem(`${storageArea}:count`);
-
-          expect(actual).toBeNull();
-        });
-
-        it('should return the default value if passed in options', async () => {
-          const expected = 0;
-          const actual = await storage.getItem(`${storageArea}:count`, {
-            defaultValue: expected,
-          });
-
-          expect(actual).toBe(expected);
+          expect(await storage.getItem(`${storageArea}:count`)).toBeNull();
        });
      });

      describe('getItems', () => {
-        it('should return an array of values', async () => {
+        it('should return an array of values in the same order as the keys passed in', async () => {
          const expected = [
            { key: `${storageArea}:count`, value: 234 },
            { key: `${storageArea}:installDate`, value: null },
-            { key: `${storageArea}:otherValue`, value: 345 },
-          ];
-          const params = [
-            expected[0].key,
-            expected[1].key,
-            {
-              key: expected[2].key,
-              options: { defaultValue: expected[2].value },
-            },
          ];
+          const keys = expected.map((item) => item.key);
          await fakeBrowser.storage[storageArea].set({
            count: expected[0].value,
          });

-          const actual = await storage.getItems(params);
+          const actual = await storage.getItems(keys);

          expect(actual).toEqual(expected);
        });
      });

-      describe('getMeta', () => {
-        it('should return item metadata from key+$', async () => {
-          const expected = { v: 1 };
-          await fakeBrowser.storage[storageArea].set({ count$: expected });
-
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual(expected);
-        });
-
-        it('should return an empty object if missing', async () => {
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual({});
-        });
-      });
-
      describe('setItem', () => {
-        it('should set the value in the correct storage area', async () => {
-          const key = `${storageArea}:count`;
-          const value = 321;
-
-          await storage.setItem(key, value);
-        });
+        it('should set the value in the correct storage area', () => {});

        it.each([undefined, null])(
          'should remove the item from storage when setting the value to %s',
@@ -119,736 +57,14 @@ describe('Storage Utils', () => {
        );
      });

-      describe('setItems', () => {
-        it('should set multiple items in storage', async () => {
-          const expected = [
-            { key: `${storageArea}:count`, value: 234 },
-            { key: `${storageArea}:installDate`, value: null },
-          ];
-          await fakeBrowser.storage[storageArea].set({
-            count: 123,
-            installDate: 321,
-          });
-
-          await storage.setItems(expected);
-          const actual = await storage.getItems(
-            expected.map((item) => item.key),
-          );
-
-          expect(actual).toHaveLength(2);
-          expected.forEach((item) => {
-            expect(actual).toContainEqual(item);
-          });
-        });
-      });
-
-      describe('setMeta', () => {
-        it('should set metadata at key+$', async () => {
-          const existing = { v: 1 };
-          await browser.storage[storageArea].set({ count$: existing });
-          const newValues = {
-            date: Date.now(),
-          };
-          const expected = { ...existing, ...newValues };
-
-          await storage.setMeta(`${storageArea}:count`, newValues);
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual(expected);
-        });
-
-        it.each([undefined, null])(
-          'should remove any properties set to %s',
-          async (version) => {
-            const existing = { v: 1 };
-            await browser.storage[storageArea].set({ count$: existing });
-            const expected = {};
-
-            await storage.setMeta(`${storageArea}:count`, { v: version });
-            const actual = await storage.getMeta(`${storageArea}:count`);
-
-            expect(actual).toEqual(expected);
-          },
-        );
-      });
-
      describe('removeItem', () => {
        it('should remove the key from storage', async () => {
          await fakeBrowser.storage[storageArea].set({ count: 456 });
-
          await storage.removeItem(`${storageArea}:count`);
-          const actual = await storage.getItem(`${storageArea}:count`);

-          expect(actual).toBeNull();
-        });
-
-        it('should not remove the metadata by default', async () => {
-          const expected = { v: 1 };
-          await fakeBrowser.storage[storageArea].set({
-            count$: expected,
-            count: 3,
-          });
-
-          await storage.removeItem(`${storageArea}:count`);
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual(expected);
-        });
-
-        it('should remove the metadata when requested', async () => {
-          await fakeBrowser.storage[storageArea].set({
-            count$: { v: 1 },
-            count: 3,
-          });
-
-          await storage.removeItem(`${storageArea}:count`, {
-            removeMeta: true,
-          });
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual({});
-        });
-      });
-
-      describe('removeItems', () => {
-        it('should remove multiple items', async () => {
-          const key1 = `${storageArea}:one`;
-          const key2 = `${storageArea}:two`;
-          const key3 = `${storageArea}:three`;
-          await fakeBrowser.storage[storageArea].set({
-            ['one']: '1',
-            ['two']: null,
-            ['two$']: { v: 1 },
-            ['three']: '1',
-            ['three$']: { v: 1 },
-          });
-
-          await storage.removeItems([
-            key1,
-            key2,
-            { key: key3, options: { removeMeta: true } },
-          ]);
-
-          expect(await storage.getItem(key1)).toBeNull();
-          expect(await storage.getItem(key2)).toBeNull();
-          expect(await storage.getMeta(key2)).toEqual({ v: 1 });
-          expect(await storage.getItem(key3)).toBeNull();
-          expect(await storage.getMeta(key3)).toEqual({});
-        });
-      });
-
-      describe('removeMeta', () => {
-        it('should remove all metadata', async () => {
-          await fakeBrowser.storage[storageArea].set({ count$: { v: 4 } });
-
-          await storage.removeMeta(`${storageArea}:count`);
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual({});
-        });
-
-        it('should only remove specific properties', async () => {
-          await fakeBrowser.storage[storageArea].set({
-            count$: { v: 4, d: Date.now() },
-          });
-
-          await storage.removeMeta(`${storageArea}:count`, ['d']);
-          const actual = await storage.getMeta(`${storageArea}:count`);
-
-          expect(actual).toEqual({ v: 4 });
-        });
-      });
-
-      describe('snapshot', () => {
-        it('should return a snapshot of the entire storage without area prefixes', async () => {
-          const expected = {
-            count: 1,
-            count$: { v: 2 },
-            example: 'test',
-          };
-
-          await fakeBrowser.storage[storageArea].set(expected);
-          const actual = await storage.snapshot(storageArea);
-
-          expect(actual).toEqual(expected);
-        });
-
-        it('should exclude specific properties and their metadata', async () => {
-          const input = {
-            count: 1,
-            count$: { v: 2 },
-            example: 'test',
-          };
-          const excludeKeys = ['count'];
-          const expected = {
-            example: 'test',
-          };
-
-          await fakeBrowser.storage[storageArea].set(input);
-          const actual = await storage.snapshot(storageArea, { excludeKeys });
-
-          expect(actual).toEqual(expected);
-        });
-      });
-
-      describe('restoreSnapshot', () => {
-        it('should restore a snapshot object by setting all values in storage', async () => {
-          const data = {
-            one: 'one',
-            two: 'two',
-          };
-          const existing = {
-            two: 'two-two',
-            three: 'three',
-          };
-          await fakeBrowser.storage[storageArea].set(existing);
-
-          await storage.restoreSnapshot(storageArea, data);
-          const actual = await storage.snapshot(storageArea);
-
-          expect(actual).toEqual({ ...existing, ...data });
-        });
-
-        it('should overwrite, not merge, any metadata keys in the snapshot', async () => {
-          const existing = {
-            count: 1,
-            count$: {
-              v: 2,
-            },
-          };
-          const data = {
-            count$: {
-              restoredAt: Date.now(),
-            },
-          };
-          const expected = {
-            ...existing,
-            count$: data.count$,
-          };
-          await fakeBrowser.storage[storageArea].set(existing);
-
-          await storage.restoreSnapshot(storageArea, data);
-          const actual = await storage.snapshot(storageArea);
-
-          expect(actual).toEqual(expected);
-        });
-      });
-
-      describe('watch', () => {
-        it('should not trigger if the changed key is different from the requested key', async () => {
-          const cb = vi.fn();
-
-          storage.watch(`${storageArea}:key`, cb);
-          await storage.setItem(`${storageArea}:not-the-key`, '123');
-
-          expect(cb).not.toBeCalled();
-        });
-
-        it("should not trigger if the value doesn't change", async () => {
-          const cb = vi.fn();
-          const value = '123';
-
-          await storage.setItem(`${storageArea}:key`, value);
-          storage.watch(`${storageArea}:key`, cb);
-          await storage.setItem(`${storageArea}:key`, value);
-
-          expect(cb).not.toBeCalled();
-        });
-
-        it('should call the callback when the value changes', async () => {
-          const cb = vi.fn();
-          const newValue = '123';
-          const oldValue = null;
-
-          storage.watch(`${storageArea}:key`, cb);
-          await storage.setItem(`${storageArea}:key`, newValue);
-
-          expect(cb).toBeCalledTimes(1);
-          expect(cb).toBeCalledWith(newValue, oldValue);
-        });
-
-        it('should remove the listener when calling the returned function', async () => {
-          const cb = vi.fn();
-
-          const unwatch = storage.watch(`${storageArea}:key`, cb);
-          unwatch();
-          await storage.setItem(`${storageArea}:key`, '123');
-
-          expect(cb).not.toBeCalled();
-        });
-      });
-
-      describe('unwatch', () => {
-        it('should remove all watch listeners', async () => {
-          const cb = vi.fn();
-
-          storage.watch(`${storageArea}:key`, cb);
-          storage.unwatch();
-          await storage.setItem(`${storageArea}:key`, '123');
-
-          expect(cb).not.toBeCalled();
+          expect(await browser.storage[storageArea].get()).toEqual({});
        });
      });
    },
  );
-
-  describe('defineItem', () => {
-    describe('versioning', () => {
-      it('should migrate values to the latest when a version upgrade is detected', async () => {
-        await fakeBrowser.storage.local.set({
-          count: 2,
-          count$: { v: 1 },
-        });
-        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-        const item = storage.defineItem<number, { v: number }>(`local:count`, {
-          defaultValue: 0,
-          version: 3,
-          migrations: {
-            2: migrateToV2,
-            3: migrateToV3,
-          },
-        });
-        await waitForMigrations();
-
-        const actualValue = await item.getValue();
-        const actualMeta = await item.getMeta();
-
-        expect(actualValue).toEqual(12);
-        expect(actualMeta).toEqual({ v: 3 });
-
-        expect(migrateToV2).toBeCalledTimes(1);
-        expect(migrateToV2).toBeCalledWith(2);
-
-        expect(migrateToV3).toBeCalledTimes(1);
-        expect(migrateToV3).toBeCalledWith(4);
-      });
-
-      it("should not run migrations if the value doesn't exist yet", async () => {
-        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-        const item = storage.defineItem<number, { v: number }>(`local:count`, {
-          defaultValue: 0,
-          version: 3,
-          migrations: {
-            2: migrateToV2,
-            3: migrateToV3,
-          },
-        });
-        await waitForMigrations();
-
-        const actualValue = await item.getValue();
-        const actualMeta = await item.getMeta();
-
-        expect(actualValue).toEqual(0);
-        expect(actualMeta).toEqual({});
-
-        expect(migrateToV2).not.toBeCalled();
-        expect(migrateToV3).not.toBeCalled();
-      });
-
-      it('should run the v2 migration when converting an unversioned item to a versioned one', async () => {
-        await fakeBrowser.storage.local.set({
-          count: 2,
-        });
-        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-
-        const item = storage.defineItem<number, { v: number }>(`local:count`, {
-          defaultValue: 0,
-          version: 2,
-          migrations: {
-            2: migrateToV2,
-          },
-        });
-        await waitForMigrations();
-
-        const actualValue = await item.getValue();
-        const actualMeta = await item.getMeta();
-
-        expect(actualValue).toEqual(4);
-        expect(actualMeta).toEqual({ v: 2 });
-
-        expect(migrateToV2).toBeCalledTimes(1);
-        expect(migrateToV2).toBeCalledWith(2);
-      });
-
-      it('should not run old migrations if the version is unchanged', async () => {
-        await fakeBrowser.storage.local.set({
-          count: 2,
-          count$: { v: 3 },
-        });
-        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-        storage.defineItem<number, { v: number }>(`local:count`, {
-          defaultValue: 0,
-          version: 3,
-          migrations: {
-            2: migrateToV2,
-            3: migrateToV3,
-          },
-        });
-        await waitForMigrations();
-
-        expect(migrateToV2).not.toBeCalled();
-        expect(migrateToV3).not.toBeCalled();
-      });
-
-      it('should skip missing migration functions', async () => {
-        await fakeBrowser.storage.local.set({
-          count: 2,
-          count$: { v: 0 },
-        });
-        const migrateToV1 = vi.fn((oldCount) => oldCount * 1);
-        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-        const item = storage.defineItem<number, { v: number }>(`local:count`, {
-          defaultValue: 0,
-          version: 3,
-          migrations: {
-            1: migrateToV1,
-            3: migrateToV3,
-          },
-        });
-        await waitForMigrations();
-
-        const actualValue = await item.getValue();
-        const actualMeta = await item.getMeta();
-
-        expect(actualValue).toEqual(6);
-        expect(actualMeta).toEqual({ v: 3 });
-
-        expect(migrateToV1).toBeCalledTimes(1);
-        expect(migrateToV1).toBeCalledWith(2);
-
-        expect(migrateToV3).toBeCalledTimes(1);
-        expect(migrateToV3).toBeCalledWith(2);
-      });
-
-      it('should throw an error if the new version is less than the previous version', async () => {
-        const prevVersion = 2;
-        const nextVersion = 1;
-        await fakeBrowser.storage.local.set({
-          count: 0,
-          count$: { v: prevVersion },
-        });
-
-        const item = storage.defineItem(`local:count`, {
-          defaultValue: 0,
-          version: nextVersion,
-        });
-        await waitForMigrations();
-
-        await expect(item.migrate()).rejects.toThrow(
-          'Version downgrade detected (v2 -> v1) for "local:count"',
-        );
-      });
-    });
-
-    describe('getValue', () => {
-      it('should return the value from storage', async () => {
-        const expected = 2;
-        const item = storage.defineItem<number>(`local:count`);
-        await fakeBrowser.storage.local.set({ count: expected });
-
-        const actual = await item.getValue();
-
-        expect(actual).toBe(expected);
-      });
-
-      it('should return null if missing', async () => {
-        const item = storage.defineItem<number>(`local:count`);
-
-        const actual = await item.getValue();
-
-        expect(actual).toBeNull();
-      });
-
-      it('should return the provided default value if missing', async () => {
-        const expected = 0;
-        const item = storage.defineItem(`local:count`, {
-          defaultValue: expected,
-        });
-
-        const actual = await item.getValue();
-
-        expect(actual).toEqual(expected);
-      });
-    });
-
-    describe('getMeta', () => {
-      it('should return the value from storage at key+$', async () => {
-        const expected = { v: 2 };
-        const item = storage.defineItem<number, { v: number }>(`local:count`);
-        await fakeBrowser.storage.local.set({ count$: expected });
-
-        const actual = await item.getMeta();
-
-        expect(actual).toBe(expected);
-      });
-
-      it('should return an empty object if missing', async () => {
-        const expected = {};
-        const item = storage.defineItem<number, { v: number }>(`local:count`);
-
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual(expected);
-      });
-    });
-
-    describe('setValue', () => {
-      it('should set the value in storage', async () => {
-        const expected = 1;
-        const item = storage.defineItem<number>(`local:count`);
-
-        await item.setValue(expected);
-        const actual = await item.getValue();
-
-        expect(actual).toBe(expected);
-      });
-
-      it.each([undefined, null])(
-        'should remove the value in storage when %s is passed in',
-        async (value) => {
-          const item = storage.defineItem<number>(`local:count`);
-
-          // @ts-expect-error: undefined is not assignable to null, but we're testing that case on purpose
-          await item.setValue(value);
-          const actual = await item.getValue();
-
-          expect(actual).toBeNull();
-        },
-      );
-    });
-
-    describe('setMeta', () => {
-      it('should set metadata at key+$', async () => {
-        const expected = { date: Date.now() };
-        const item = storage.defineItem<number, { date: number }>(
-          `local:count`,
-        );
-
-        await item.setMeta(expected);
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual(expected);
-      });
-
-      it('should add to metadata if already present', async () => {
-        const existing = { v: 2 };
-        const newFields = { date: Date.now() };
-        const expected = { ...existing, ...newFields };
-        const item = storage.defineItem<number, { date: number; v: number }>(
-          `local:count`,
-        );
-        await fakeBrowser.storage.local.set({
-          count$: existing,
-        });
-
-        await item.setMeta(newFields);
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual(expected);
-      });
-    });
-
-    describe('removeValue', () => {
-      it('should remove the key from storage', async () => {
-        const item = storage.defineItem(`local:count`);
-        await fakeBrowser.storage.local.set({ count: 456 });
-
-        await item.removeValue();
-        const actual = await item.getValue();
-
-        expect(actual).toBeNull();
-      });
-
-      it('should not remove the metadata by default', async () => {
-        const item = storage.defineItem(`local:count`);
-        const expected = { v: 1 };
-        await fakeBrowser.storage.local.set({
-          count$: expected,
-          count: 3,
-        });
-
-        await item.removeValue();
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual(expected);
-      });
-
-      it('should remove the metadata when requested', async () => {
-        const item = storage.defineItem(`local:count`);
-        await fakeBrowser.storage.local.set({
-          count$: { v: 1 },
-          count: 3,
-        });
-
-        await item.removeValue({ removeMeta: true });
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual({});
-      });
-    });
-
-    describe('removeMeta', () => {
-      it('should remove all metadata', async () => {
-        const item = storage.defineItem<number, { v: number }>(`local:count`);
-        await fakeBrowser.storage.local.set({ count$: { v: 4 } });
-
-        await item.removeMeta();
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual({});
-      });
-
-      it('should only remove specific properties', async () => {
-        const item = storage.defineItem<number, { v: number; d: number }>(
-          `local:count`,
-        );
-        await fakeBrowser.storage.local.set({
-          count$: { v: 4, d: Date.now() },
-        });
-
-        await item.removeMeta(['d']);
-        const actual = await item.getMeta();
-
-        expect(actual).toEqual({ v: 4 });
-      });
-    });
-
-    describe('watch', () => {
-      it("should not trigger if the changed key is different from the item's key", async () => {
-        const item = storage.defineItem(`local:key`);
-        const cb = vi.fn();
-
-        item.watch(cb);
-        await storage.setItem(`local:not-the-key`, '123');
-
-        expect(cb).not.toBeCalled();
-      });
-
-      it("should not trigger if the value doesn't change", async () => {
-        const item = storage.defineItem(`local:key`);
-        const cb = vi.fn();
-        const value = '123';
-
-        await item.setValue(value);
-        item.watch(cb);
-        await item.setValue(value);
-
-        expect(cb).not.toBeCalled();
-      });
-
-      it('should call the callback when the value changes', async () => {
-        const item = storage.defineItem(`local:key`);
-        const cb = vi.fn();
-        const newValue = '123';
-        const oldValue = null;
-
-        item.watch(cb);
-        await item.setValue(newValue);
-
-        expect(cb).toBeCalledTimes(1);
-        expect(cb).toBeCalledWith(newValue, oldValue);
-      });
-
-      it('should use the default value for the newValue when the item is removed', async () => {
-        const defaultValue = 'default';
-        const item = storage.defineItem<string>(`local:key`, {
-          defaultValue,
-        });
-        const cb = vi.fn();
-        const oldValue = '123';
-        await item.setValue(oldValue);
-
-        item.watch(cb);
-        await item.removeValue();
-
-        expect(cb).toBeCalledTimes(1);
-        expect(cb).toBeCalledWith(defaultValue, oldValue);
-      });
-
-      it("should use the default value for the oldItem when the item didn't exist in storage yet", async () => {
-        const defaultValue = 'default';
-        const item = storage.defineItem<string>(`local:key`, {
-          defaultValue,
-        });
-        const cb = vi.fn();
-        const newValue = '123';
-        await item.removeValue();
-
-        item.watch(cb);
-        await item.setValue(newValue);
-
-        expect(cb).toBeCalledTimes(1);
-        expect(cb).toBeCalledWith(newValue, defaultValue);
-      });
-
-      it('should remove the listener when calling the returned function', async () => {
-        const item = storage.defineItem(`local:key`);
-        const cb = vi.fn();
-
-        const unwatch = item.watch(cb);
-        unwatch();
-        await item.setValue('123');
-
-        expect(cb).not.toBeCalled();
-      });
-    });
-
-    describe('unwatch', () => {
-      it('should remove all watch listeners', async () => {
-        const item = storage.defineItem(`local:key`);
-        const cb = vi.fn();
-
-        item.watch(cb);
-        storage.unwatch();
-        await item.setValue('123');
-
-        expect(cb).not.toBeCalled();
-      });
-    });
-
-    describe('defaultValue', () => {
-      it('should return the default value when provided', () => {
-        const defaultValue = 123;
-        const item = storage.defineItem(`local:test`, {
-          defaultValue,
-        });
-
-        expect(item.defaultValue).toBe(defaultValue);
-      });
-
-      it('should return null when not provided', () => {
-        const item = storage.defineItem<number>(`local:test`);
-
-        expect(item.defaultValue).toBeNull();
-      });
-    });
-
-    describe('types', () => {
-      it('should define a nullable value when options are not passed', () => {
-        const item = storage.defineItem<number>(`local:test`);
-        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number | null, {}>>();
-      });
-
-      it('should define a non-null value when options are passed with a nullish default value', () => {
-        const item = storage.defineItem(`local:test`, {
-          defaultValue: 123,
-        });
-        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number, {}>>();
-      });
-
-      it('should define a nullable value when options are passed with null default value', () => {
-        const item = storage.defineItem<number | null>(`local:test`, {
-          defaultValue: null,
-        });
-        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number | null, {}>>();
-      });
-    });
-  });
 });
@@ -1,12 +1,13 @@
 import cac from 'cac';
+import { version } from '~/version';
 import { build, clean, createServer, initialize, prepare, zip } from '~/core';
-import {
-  createAliasedCommand,
-  getArrayFromFlags,
-  wrapAction,
-} from './cli-utils';
+import consola, { LogLevels } from 'consola';
+import { printHeader } from '~/core/utils/log';
+import { formatDuration } from '~/core/utils/time';

 const cli = cac('wxt');
+cli.help();
+cli.version(version);

 cli.option('--debug', 'enable debug mode');

@@ -16,13 +17,6 @@ cli
  .option('-c, --config <file>', 'use specified config file')
  .option('-m, --mode <mode>', 'set env mode')
  .option('-b, --browser <browser>', 'specify a browser')
-  .option(
-    '-e, --filter-entrypoint <entrypoint>',
-    'only build specific entrypoints',
-    {
-      type: [],
-    },
-  )
  .option('--mv3', 'target manifest v3')
  .option('--mv2', 'target manifest v2')
  .action(
@@ -34,7 +28,6 @@ cli
        manifestVersion: flags.mv3 ? 3 : flags.mv2 ? 2 : undefined,
        configFile: flags.config,
        debug: flags.debug,
-        filterEntrypoints: getArrayFromFlags(flags, 'filterEntrypoint'),
      });
      await server.start();
      return { isOngoing: true };
@@ -47,13 +40,6 @@ cli
  .option('-c, --config <file>', 'use specified config file')
  .option('-m, --mode <mode>', 'set env mode')
  .option('-b, --browser <browser>', 'specify a browser')
-  .option(
-    '-e, --filter-entrypoint <entrypoint>',
-    'only build specific entrypoints',
-    {
-      type: [],
-    },
-  )
  .option('--mv3', 'target manifest v3')
  .option('--mv2', 'target manifest v2')
  .option('--analyze', 'visualize extension bundle')
@@ -66,8 +52,9 @@ cli
        manifestVersion: flags.mv3 ? 3 : flags.mv2 ? 2 : undefined,
        configFile: flags.config,
        debug: flags.debug,
-        analysis: flags.analyze ? { enabled: true } : undefined,
-        filterEntrypoints: getArrayFromFlags(flags, 'filterEntrypoint'),
+        analysis: {
+          enabled: flags.analyze,
+        },
      });
    }),
  );
@@ -135,13 +122,43 @@ cli
    ),
  );

-// SUBMIT
-createAliasedCommand(
-  cli,
-  'submit',
-  'publish-extension',
-  'wxt-publish-extension',
-  'https://www.npmjs.com/publish-browser-extension',
-);
+cli.parse();

-export default cli;
+/**
+ * Wrap an action handler to add a timer, error handling, and maybe enable debug mode.
+ */
+function wrapAction(
+  cb: (
+    ...args: any[]
+  ) => void | { isOngoing?: boolean } | Promise<void | { isOngoing?: boolean }>,
+  options?: {
+    disableFinishedLog?: boolean;
+  },
+) {
+  return async (...args: any[]) => {
+    // Enable consola's debug mode globally at the start of all commands when the `--debug` flag is
+    // passed
+    const isDebug = !!args.find((arg) => arg?.debug);
+    if (isDebug) {
+      consola.level = LogLevels.debug;
+    }
+
+    const startTime = Date.now();
+    try {
+      printHeader();
+
+      const status = await cb(...args);
+
+      if (!status?.isOngoing && !options?.disableFinishedLog)
+        consola.success(
+          `Finished in ${formatDuration(Date.now() - startTime)}`,
+        );
+    } catch (err) {
+      consola.fail(
+        `Command failed after ${formatDuration(Date.now() - startTime)}`,
+      );
+      consola.error(err);
+      process.exit(1);
+    }
+  };
+}
@@ -1,380 +0,0 @@
-import { describe, it, vi, beforeEach, expect } from 'vitest';
-import { build } from '~/core/build';
-import { createServer } from '~/core/create-server';
-import { zip } from '~/core/zip';
-import { prepare } from '~/core/prepare';
-import { clean } from '~/core/clean';
-import { initialize } from '~/core/initialize';
-import { mock } from 'vitest-mock-extended';
-import consola from 'consola';
-
-vi.mock('~/core/build');
-const buildMock = vi.mocked(build);
-
-vi.mock('~/core/create-server');
-const createServerMock = vi.mocked(createServer);
-
-vi.mock('~/core/zip');
-const zipMock = vi.mocked(zip);
-
-vi.mock('~/core/prepare');
-const prepareMock = vi.mocked(prepare);
-
-vi.mock('~/core/clean');
-const cleanMock = vi.mocked(clean);
-
-vi.mock('~/core/initialize');
-const initializeMock = vi.mocked(initialize);
-
-consola.wrapConsole();
-
-const ogArgv = process.argv;
-
-function mockArgv(...args: string[]) {
-  process.argv = ['/bin/node', 'bin/wxt.mjs', ...args];
-}
-
-async function importCli() {
-  await import('~/cli');
-}
-
-describe('CLI', () => {
-  beforeEach(() => {
-    vi.resetModules();
-    process.argv = ogArgv;
-    createServerMock.mockResolvedValue(mock());
-  });
-
-  describe('dev', () => {
-    it('should not pass any config when no flags are passed', async () => {
-      mockArgv();
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({});
-    });
-
-    it('should respect passing a custom root', async () => {
-      mockArgv('path/to/root');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        root: 'path/to/root',
-      });
-    });
-
-    it('should respect a custom config file', async () => {
-      mockArgv('-c', './path/to/config.ts');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        configFile: './path/to/config.ts',
-      });
-    });
-
-    it('should respect passing a custom mode', async () => {
-      mockArgv('-m', 'development');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        mode: 'development',
-      });
-    });
-
-    it('should respect passing a custom browser', async () => {
-      mockArgv('-b', 'firefox');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        browser: 'firefox',
-      });
-    });
-
-    it('should pass correct filtered entrypoints', async () => {
-      mockArgv('-e', 'popup', '-e', 'options');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        filterEntrypoints: ['popup', 'options'],
-      });
-    });
-
-    it('should respect passing --mv2', async () => {
-      mockArgv('--mv2');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        manifestVersion: 2,
-      });
-    });
-
-    it('should respect passing --mv3', async () => {
-      mockArgv('--mv3');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        manifestVersion: 3,
-      });
-    });
-
-    it('should respect passing --debug', async () => {
-      mockArgv('--debug');
-      await importCli();
-
-      expect(createServerMock).toBeCalledWith({
-        debug: true,
-      });
-    });
-  });
-
-  describe('build', () => {
-    it('should not pass any config when no flags are passed', async () => {
-      mockArgv('build');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({});
-    });
-
-    it('should respect passing a custom root', async () => {
-      mockArgv('build', 'path/to/root');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        root: 'path/to/root',
-      });
-    });
-
-    it('should respect a custom config file', async () => {
-      mockArgv('build', '-c', './path/to/config.ts');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        configFile: './path/to/config.ts',
-      });
-    });
-
-    it('should respect passing a custom mode', async () => {
-      mockArgv('build', '-m', 'development');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        mode: 'development',
-      });
-    });
-
-    it('should respect passing a custom browser', async () => {
-      mockArgv('build', '-b', 'firefox');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        browser: 'firefox',
-      });
-    });
-
-    it('should pass correct filtered entrypoints', async () => {
-      mockArgv('build', '-e', 'popup', '-e', 'options');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        filterEntrypoints: ['popup', 'options'],
-      });
-    });
-
-    it('should respect passing --mv2', async () => {
-      mockArgv('build', '--mv2');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        manifestVersion: 2,
-      });
-    });
-
-    it('should respect passing --mv3', async () => {
-      mockArgv('build', '--mv3');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        manifestVersion: 3,
-      });
-    });
-
-    it('should include analysis in the build', async () => {
-      mockArgv('build', '--analyze');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        analysis: {
-          enabled: true,
-        },
-      });
-    });
-
-    it('should respect passing --debug', async () => {
-      mockArgv('build', '--debug');
-      await importCli();
-
-      expect(buildMock).toBeCalledWith({
-        debug: true,
-      });
-    });
-  });
-
-  describe('zip', () => {
-    it('should not pass any config when no flags are passed', async () => {
-      mockArgv('zip');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({});
-    });
-
-    it('should respect passing a custom root', async () => {
-      mockArgv('zip', 'path/to/root');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        root: 'path/to/root',
-      });
-    });
-
-    it('should respect a custom config file', async () => {
-      mockArgv('zip', '-c', './path/to/config.ts');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        configFile: './path/to/config.ts',
-      });
-    });
-
-    it('should respect passing a custom mode', async () => {
-      mockArgv('zip', '-m', 'development');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        mode: 'development',
-      });
-    });
-
-    it('should respect passing a custom browser', async () => {
-      mockArgv('zip', '-b', 'firefox');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        browser: 'firefox',
-      });
-    });
-
-    it('should respect passing --mv2', async () => {
-      mockArgv('zip', '--mv2');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        manifestVersion: 2,
-      });
-    });
-
-    it('should respect passing --mv3', async () => {
-      mockArgv('zip', '--mv3');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        manifestVersion: 3,
-      });
-    });
-
-    it('should respect passing --debug', async () => {
-      mockArgv('zip', '--debug');
-      await importCli();
-
-      expect(zipMock).toBeCalledWith({
-        debug: true,
-      });
-    });
-  });
-
-  describe('prepare', () => {
-    it('should not pass any config when no flags are passed', async () => {
-      mockArgv('prepare');
-      await importCli();
-
-      expect(prepareMock).toBeCalledWith({});
-    });
-
-    it('should respect passing a custom root', async () => {
-      mockArgv('prepare', 'path/to/root');
-      await importCli();
-
-      expect(prepareMock).toBeCalledWith({
-        root: 'path/to/root',
-      });
-    });
-
-    it('should respect a custom config file', async () => {
-      mockArgv('prepare', '-c', './path/to/config.ts');
-      await importCli();
-
-      expect(prepareMock).toBeCalledWith({
-        configFile: './path/to/config.ts',
-      });
-    });
-
-    it('should respect passing --debug', async () => {
-      mockArgv('prepare', '--debug');
-      await importCli();
-
-      expect(prepareMock).toBeCalledWith({
-        debug: true,
-      });
-    });
-  });
-
-  describe('clean', () => {
-    it('should not pass any config when no flags are passed', async () => {
-      mockArgv('clean');
-      await importCli();
-
-      expect(cleanMock).toBeCalledWith(undefined);
-    });
-
-    it('should respect passing a custom root', async () => {
-      mockArgv('clean', 'path/to/root');
-      await importCli();
-
-      expect(cleanMock).toBeCalledWith('path/to/root');
-    });
-  });
-
-  describe('init', () => {
-    it('should not pass any options when no flags are passed', async () => {
-      mockArgv('init');
-      await importCli();
-
-      expect(initializeMock).toBeCalledWith({});
-    });
-
-    it('should respect the provided folder', async () => {
-      mockArgv('init', 'path/to/folder');
-      await importCli();
-
-      expect(initializeMock).toBeCalledWith({
-        directory: 'path/to/folder',
-      });
-    });
-
-    it('should respect passing --template', async () => {
-      mockArgv('init', '-t', 'vue');
-      await importCli();
-
-      expect(initializeMock).toBeCalledWith({
-        template: 'vue',
-      });
-    });
-
-    it('should respect passing --pm', async () => {
-      mockArgv('init', '--pm', 'pnpm');
-      await importCli();
-
-      expect(initializeMock).toBeCalledWith({
-        packageManager: 'pnpm',
-      });
-    });
-  });
-});
@@ -1,102 +0,0 @@
-import { CAC, Command } from 'cac';
-import consola, { LogLevels } from 'consola';
-import { printHeader } from '~/core/utils/log';
-import { formatDuration } from '~/core/utils/time';
-import { ValidationError } from '~/core/utils/validation';
-import { registerWxt } from '~/core/wxt';
-
-/**
- * Wrap an action handler to add a timer, error handling, and maybe enable debug mode.
- */
-export function wrapAction(
-  cb: (
-    ...args: any[]
-  ) => void | { isOngoing?: boolean } | Promise<void | { isOngoing?: boolean }>,
-  options?: {
-    disableFinishedLog?: boolean;
-  },
-) {
-  return async (...args: any[]) => {
-    // Enable consola's debug mode globally at the start of all commands when the `--debug` flag is
-    // passed
-    const isDebug = !!args.find((arg) => arg?.debug);
-    if (isDebug) {
-      consola.level = LogLevels.debug;
-    }
-
-    const startTime = Date.now();
-    try {
-      printHeader();
-
-      const status = await cb(...args);
-
-      if (!status?.isOngoing && !options?.disableFinishedLog)
-        consola.success(
-          `Finished in ${formatDuration(Date.now() - startTime)}`,
-        );
-    } catch (err) {
-      consola.fail(
-        `Command failed after ${formatDuration(Date.now() - startTime)}`,
-      );
-      if (err instanceof ValidationError) {
-        // Don't log these errors, they've already been logged
-      } else {
-        consola.error(err);
-      }
-      process.exit(1);
-    }
-  };
-}
-
-/**
- * Array flags, when not passed, are either `undefined` or `[undefined]`. This function filters out
- * the
- */
-export function getArrayFromFlags<T>(
-  flags: any,
-  name: string,
-): T[] | undefined {
-  const array = [flags[name]].flat() as Array<T | undefined>;
-  const result = array.filter((item) => item != null) as T[];
-  return result.length ? result : undefined;
-}
-
-const aliasCommandNames = new Set<string>();
-/**
- * @param base Command to add this one to
- * @param name The command name to add
- * @param alias The CLI tool being aliased
- * @param bin The CLI tool binary name. Usually the same as the alias
- * @param docsUrl URL to the docs for the aliased CLI tool
- */
-export function createAliasedCommand(
-  base: CAC,
-  name: string,
-  alias: string,
-  bin: string,
-  docsUrl: string,
-) {
-  const aliasedCommand = base
-    .command(name, `Alias for ${alias} (${docsUrl})`)
-    .allowUnknownOptions()
-    .action(async () => {
-      try {
-        await registerWxt('build');
-
-        const args = process.argv.slice(
-          process.argv.indexOf(aliasedCommand.name) + 1,
-        );
-        const { execa } = await import('execa');
-        await execa(bin, args, {
-          stdio: 'inherit',
-        });
-      } catch {
-        // Let the other aliased CLI log errors, just exit
-        process.exit(1);
-      }
-    });
-  aliasCommandNames.add(aliasedCommand.name);
-}
-export function isAliasedCommand(command: Command | undefined): boolean {
-  return !!command && aliasCommandNames.has(command.name);
-}
@@ -1,19 +0,0 @@
-import cli from './commands';
-import { version } from '~/version';
-import { isAliasedCommand } from './cli-utils';
-
-// TODO: Remove. See https://github.com/wxt-dev/wxt/issues/277
-process.env.VITE_CJS_IGNORE_WARNING = 'true';
-
-// Grab the command that we're trying to run
-cli.parse(process.argv, { run: false });
-
-// If it's not an alias, add the help and version options, then parse again
-if (!isAliasedCommand(cli.matchedCommand)) {
-  cli.help();
-  cli.version(version);
-  cli.parse(process.argv, { run: false });
-}
-
-// Run the alias or command
-await cli.runMatchedCommand();
@@ -0,0 +1,214 @@
+/** @vitest-environment happy-dom */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createContentScriptIframe } from '~/client/content-scripts/content-script-iframe';
+import { ContentScriptContext } from '~/client/content-scripts/content-script-context';
+
+const createCtx = () => new ContentScriptContext('test');
+
+const fetch = vi.fn();
+
+describe('createContentScriptIframe', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="parent">
+        <p id="one">one</p>
+        <p id="two">two</p>
+        <p id="three"></p>
+      </div>
+    `;
+
+    window.fetch = fetch;
+    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
+  });
+
+  describe('mount', () => {
+    describe('append option', () => {
+      it.each([undefined, 'last' as const])(
+        'should append the element as the last child to the anchor when append=%s',
+        async (append) => {
+          const ui = await createContentScriptIframe(createCtx(), {
+            page: '/test.html',
+            type: 'inline',
+            anchor: '#parent',
+            append,
+          });
+          ui.mount();
+
+          expect(
+            document.querySelector('#parent > :nth-child(4)')?.tagName,
+          ).toEqual('DIV');
+        },
+      );
+
+      it('should append the element as the first child to the anchor when append=first', async () => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor: '#parent',
+          append: 'first',
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(1)')?.tagName,
+        ).toEqual('DIV');
+      });
+
+      it('should append the element normally when append=first but there are no other children', async () => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor: '#three',
+          append: 'first',
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#three > :nth-child(1)')?.tagName,
+        ).toEqual('DIV');
+      });
+
+      it('should replace the anchor with the element when append=replace', async () => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor: '#two',
+          append: 'replace',
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(2)')?.tagName,
+        ).toEqual('DIV');
+      });
+
+      it('should append the element after the anchor when append=before', async () => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor: '#two',
+          append: 'before',
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(2)')?.tagName,
+        ).toEqual('DIV');
+      });
+
+      it('should append the element after the anchor when append=after', async () => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor: '#two',
+          append: 'after',
+        });
+        ui.mount();
+
+        // Happy DOM doesn't work in this case, so we just make sure the element is added.
+        // expect(
+        //   document.querySelector('#parent > :nth-child(3)')?.tagName,
+        // ).toEqual('DIV');
+        expect(document.querySelector('DIV')).toBeDefined();
+      });
+
+      it('should apply a custom function', async () => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor: '#three',
+          append: (anchor, ui) => anchor.replaceWith(ui),
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(3)')?.tagName,
+        ).toEqual('DIV');
+      });
+    });
+
+    it('should default the anchor to the body when unset', async () => {
+      const ui = await createContentScriptIframe(createCtx(), {
+        page: '/test.html',
+        type: 'inline',
+      });
+      ui.mount();
+
+      expect(document.querySelector('body > :nth-child(2)')?.tagName).toEqual(
+        'DIV',
+      );
+    });
+
+    it.each(['#four', () => document.querySelector('#four')])(
+      "should throw an error if the anchor doesn't exist",
+      async (anchor) => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type: 'inline',
+          anchor,
+        });
+
+        expect(ui.mount).toThrow(
+          'Failed to mount content script UI: could not find anchor element',
+        );
+      },
+    );
+  });
+
+  describe('remove', () => {
+    it("should not fail if the ui hasn't been mounted", async () => {
+      const ui = await createContentScriptIframe(createCtx(), {
+        page: '/test.html',
+        type: 'inline',
+      });
+      ui.remove();
+    });
+
+    it('should automatically remove the UI when the context is invalidated', async () => {
+      const ctx = createCtx();
+      const ui = await createContentScriptIframe(ctx, {
+        page: '/test.html',
+        type: 'inline',
+      });
+      ui.mount();
+
+      expect(document.querySelector('.wxt-iframe-wrapper')).toBeDefined();
+
+      ctx.abort();
+      expect(document.querySelector('.wxt-iframe-wrapper')).toBeNull();
+    });
+  });
+
+  describe('type', () => {
+    it.each(['inline', 'overlay', 'modal'] as const)(
+      'should render type=%s',
+      async (type) => {
+        const ui = await createContentScriptIframe(createCtx(), {
+          page: '/test.html',
+          type,
+        });
+        ui.mount();
+
+        expect(document.querySelector('DIV')).toBeDefined();
+      },
+    );
+  });
+
+  describe('anchor', () => {
+    it.each([
+      () => '#two',
+      () => () => '#two',
+      () => document.querySelector('#two'),
+      () => () => document.querySelector('#two'),
+    ])('should render anchor=%s', async (getAnchor) => {
+      const ui = await createContentScriptIframe(createCtx(), {
+        page: '/test.html',
+        type: 'inline',
+        anchor: getAnchor(),
+      });
+      ui.mount();
+
+      expect(document.querySelector('DIV')).toBeDefined();
+    });
+  });
+});
@@ -0,0 +1,335 @@
+/** @vitest-environment happy-dom */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createContentScriptUi } from '~/client/content-scripts/content-script-ui';
+import { ContentScriptContext } from '~/client/content-scripts/content-script-context';
+import { createIsolatedElement } from '@webext-core/isolated-element';
+import { mock } from 'vitest-mock-extended';
+import { browser } from '~/browser';
+
+vi.mock('@webext-core/isolated-element', async () => {
+  const { vi } = await import('vitest');
+  return {
+    createIsolatedElement: vi.fn(),
+  };
+});
+const createIsolatedElementMock = vi.mocked(createIsolatedElement);
+
+const testApp = (container: Element) => {
+  const app = document.createElement('div');
+  app.textContent = 'App';
+  container.append(app);
+};
+
+const createCtx = () => new ContentScriptContext('test');
+
+const fetch = vi.fn();
+
+describe('createContentScriptUi', () => {
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="parent">
+        <p id="one">one</p>
+        <p id="two">two</p>
+        <p id="three"></p>
+      </div>
+    `;
+
+    window.fetch = fetch;
+    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
+
+    createIsolatedElementMock.mockImplementation(async (config) => {
+      const parentElement = document.createElement(config.name);
+      const isolatedElement = document.createElement('html');
+      parentElement.append(isolatedElement);
+
+      return {
+        isolatedElement,
+        parentElement: parentElement,
+        shadow: mock<ShadowRoot>({
+          querySelector: (selector: string) => {
+            if (selector === 'html') return isolatedElement;
+          },
+        }),
+      };
+    });
+  });
+
+  describe('css', () => {
+    it('should load the CSS for the current entrypoint when cssInjectionMode=ui', async () => {
+      fetch.mockResolvedValue({ text: () => Promise.resolve('body {}') });
+      const ctx = new ContentScriptContext('test', {
+        matches: [],
+        cssInjectionMode: 'ui',
+      });
+
+      await createContentScriptUi(ctx, {
+        name: 'test',
+        type: 'inline',
+        mount: testApp,
+      });
+
+      expect(fetch).toBeCalledTimes(1);
+      expect(fetch).toBeCalledWith(
+        `chrome-extension://${browser.runtime.id}/content-scripts/${__ENTRYPOINT__}.css`,
+      );
+      expect(createIsolatedElementMock).toBeCalledTimes(1);
+      expect(createIsolatedElementMock).toBeCalledWith(
+        expect.objectContaining({
+          css: {
+            textContent: 'body {}',
+          },
+        }),
+      );
+    });
+
+    it('should still load the UI when fetch fails to load CSS file when cssInjectionMode=ui', async () => {
+      const error = Error('Test fetch error');
+      fetch.mockRejectedValue(error);
+      const ctx = new ContentScriptContext('test', {
+        matches: [],
+        cssInjectionMode: 'ui',
+      });
+
+      await createContentScriptUi(ctx, {
+        name: 'test',
+        type: 'inline',
+        mount: testApp,
+      });
+
+      expect(fetch).toBeCalledTimes(1);
+      expect(fetch).toBeCalledWith(
+        `chrome-extension://${browser.runtime.id}/content-scripts/${__ENTRYPOINT__}.css`,
+      );
+      expect(createIsolatedElementMock).toBeCalledTimes(1);
+      expect(createIsolatedElementMock).toBeCalledWith(
+        expect.objectContaining({
+          css: {
+            textContent: '',
+          },
+        }),
+      );
+    });
+
+    it.each(['manifest', 'manual'] as const)(
+      'should not fetch CSS when cssInjectionMode=%s',
+      async (cssInjectionMode) => {
+        const ctx = new ContentScriptContext('test', {
+          matches: [],
+          cssInjectionMode,
+        });
+
+        await createContentScriptUi(ctx, {
+          name: 'test',
+          type: 'inline',
+          mount: testApp,
+        });
+
+        expect(fetch).not.toBeCalled();
+      },
+    );
+  });
+
+  describe('mount', () => {
+    describe('append option', () => {
+      it.each([undefined, 'last' as const])(
+        'should append the element as the last child to the anchor when append=%s',
+        async (append) => {
+          const ui = await createContentScriptUi(createCtx(), {
+            name: 'test-app',
+            type: 'inline',
+            anchor: '#parent',
+            append,
+            mount: testApp,
+          });
+          ui.mount();
+
+          expect(
+            document.querySelector('#parent > :nth-child(4)')?.tagName,
+          ).toEqual('TEST-APP');
+        },
+      );
+
+      it('should append the element as the first child to the anchor when append=first', async () => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type: 'inline',
+          anchor: '#parent',
+          append: 'first',
+          mount: testApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(1)')?.tagName,
+        ).toEqual('TEST-APP');
+      });
+
+      it('should append the element normally when append=first but there are no other children', async () => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type: 'inline',
+          anchor: '#three',
+          append: 'first',
+          mount: testApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#three > :nth-child(1)')?.tagName,
+        ).toEqual('TEST-APP');
+      });
+
+      it('should replace the anchor with the element when append=replace', async () => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type: 'inline',
+          anchor: '#two',
+          append: 'replace',
+          mount: testApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(2)')?.tagName,
+        ).toEqual('TEST-APP');
+      });
+
+      it('should append the element after the anchor when append=before', async () => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type: 'inline',
+          anchor: '#two',
+          append: 'before',
+          mount: testApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(2)')?.tagName,
+        ).toEqual('TEST-APP');
+      });
+
+      it('should append the element after the anchor when append=after', async () => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type: 'inline',
+          anchor: '#two',
+          append: 'after',
+          mount: testApp,
+        });
+        ui.mount();
+
+        // Happy DOM doesn't work in this case, so we just make sure the element is added.
+        // expect(
+        //   document.querySelector('#parent > :nth-child(3)')?.tagName,
+        // ).toEqual('TEST-APP');
+        expect(document.querySelector('test-app')).toBeDefined();
+      });
+
+      it('should apply a custom function', async () => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type: 'inline',
+          anchor: '#three',
+          append: (anchor, ui) => anchor.replaceWith(ui),
+          mount: testApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > :nth-child(3)')?.tagName,
+        ).toEqual('TEST-APP');
+      });
+    });
+
+    it('should default the anchor to the body when unset', async () => {
+      const ui = await createContentScriptUi(createCtx(), {
+        name: 'test-app',
+        type: 'inline',
+        mount: testApp,
+      });
+      ui.mount();
+
+      expect(document.querySelector('body > :nth-child(2)')?.tagName).toEqual(
+        'TEST-APP',
+      );
+    });
+
+    it.each(['#four', () => document.querySelector('#four')])(
+      "should throw an error if the anchor doesn't exist",
+      async (anchor) => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test',
+          type: 'inline',
+          anchor,
+          mount: testApp,
+        });
+
+        expect(ui.mount).toThrow(
+          'Failed to mount content script UI: could not find anchor element',
+        );
+      },
+    );
+  });
+
+  describe('remove', () => {
+    it("should not fail if the ui hasn't been mounted", async () => {
+      const ui = await createContentScriptUi(createCtx(), {
+        name: 'test-app',
+        type: 'inline',
+        mount: testApp,
+      });
+      ui.remove();
+    });
+
+    it('should automatically remove the UI when the context is invalidated', async () => {
+      const ctx = createCtx();
+      const ui = await createContentScriptUi(ctx, {
+        name: 'test-app',
+        type: 'inline',
+        mount: testApp,
+      });
+      ui.mount();
+
+      expect(document.querySelector('test-app')).toBeDefined();
+
+      ctx.abort();
+      expect(document.querySelector('test-app')).toBeNull();
+    });
+  });
+
+  describe('type', () => {
+    it.each(['inline', 'overlay', 'modal'] as const)(
+      'should render type=%s',
+      async (type) => {
+        const ui = await createContentScriptUi(createCtx(), {
+          name: 'test-app',
+          type,
+          mount: testApp,
+        });
+        ui.mount();
+
+        expect(document.querySelector('test-app')).toBeDefined();
+      },
+    );
+  });
+
+  describe('anchor', () => {
+    it.each([
+      () => '#two',
+      () => () => '#two',
+      () => document.querySelector('#two'),
+      () => () => document.querySelector('#two'),
+    ])('should render anchor=%s', async (getAnchor) => {
+      const ui = await createContentScriptUi(createCtx(), {
+        name: 'test-app',
+        type: 'inline',
+        anchor: getAnchor(),
+        mount: testApp,
+      });
+      ui.mount();
+
+      expect(document.querySelector('test-app')).toBeDefined();
+    });
+  });
+});
@@ -0,0 +1,83 @@
+import { browser } from '~/browser';
+import {
+  ContentScriptAnchoredOptions,
+  ContentScriptPositioningOptions,
+  applyContentScriptUiPosition,
+  mountContentScriptUiRoot,
+} from '../utils/content-script-ui';
+import { ContentScriptContext } from './content-script-context';
+
+/**
+ * Utility for mounting a content script UI inside an iframe. Automatically removed from the DOM
+ * when the content script's context is invalidated.
+ *
+ * See https://wxt.dev/entrypoints/content-scripts.html#iframe for full documentation.
+ *
+ * @example
+ * export default defineContentScript({
+ *   matches: ["*://*.google.com/*"],
+ *
+ *   main(ctx) {
+ *     const ui = await createContentScriptIframe(ctx, {
+ *       page: "/content-script-overlay.html",
+ *       type: "modal",
+ *     })
+ *     ui.mount();
+ *   }
+ * })
+ */
+export function createContentScriptIframe(
+  ctx: ContentScriptContext,
+  options: ContentScriptIframeOptions,
+): ContentScriptIframe {
+  const wrapper = document.createElement('div');
+  wrapper.classList.add('wxt-iframe-wrapper');
+  const iframe = document.createElement('iframe');
+  iframe.src = browser.runtime.getURL(options.page);
+  wrapper.appendChild(iframe);
+
+  const mount = () => {
+    applyContentScriptUiPosition(wrapper, iframe, options);
+    mountContentScriptUiRoot(wrapper, options);
+  };
+
+  const remove = () => {
+    wrapper.remove();
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    iframe,
+    wrapper,
+    mount,
+    remove,
+  };
+}
+
+export interface ContentScriptIframe {
+  /**
+   * The iframe added to the DOM.
+   */
+  iframe: HTMLIFrameElement;
+  /**
+   * A wrapper div that assists in positioning.
+   */
+  wrapper: HTMLDivElement;
+  /**
+   * Function that mounts or remounts the UI on the page.
+   */
+  mount: () => void;
+  /**
+   * Function that removes the UI from the webpage.
+   */
+  remove: () => void;
+}
+
+export type ContentScriptIframeOptions = ContentScriptPositioningOptions &
+  ContentScriptAnchoredOptions & {
+    /**
+     * The path to the unlisted HTML file to display in the iframe.
+     */
+    page: import('wxt/browser').PublicPath;
+  };
@@ -0,0 +1,173 @@
+import { createIsolatedElement } from '@webext-core/isolated-element';
+import { browser } from '~/browser';
+import { logger } from '~/sandbox/utils/logger';
+import { ContentScriptContext } from './content-script-context';
+import {
+  ContentScriptAnchoredOptions,
+  ContentScriptPositioningOptions,
+  applyContentScriptUiPosition,
+  mountContentScriptUiRoot,
+} from '../utils/content-script-ui';
+
+/**
+ * Utility for mounting content script UI's with isolated styles. Automatically removed from the DOM
+ * when the content script's context is invalidated.
+ *
+ * See https://wxt.dev/guide/content-script-ui.html for full documentation.
+ *
+ * @example
+ * // entrypoints/example-ui.content/index.ts
+ * import "./style.css"
+ *
+ * export default defineContentScript({
+ *   matches: ["*://*.google.com/*"],
+ *   cssInjectionMode: "ui",
+ *
+ *   async main(ctx) {
+ *     const ui = await createContentScriptUi(ctx, {
+ *       name: "example-overlay",
+ *       type: "modal",
+ *       mount(container) {
+ *         const app = document.createElement("div");
+ *         app.textContent = "Content Script UI";
+ *         container.append(app);
+ *       }
+ *     })
+ *     ui.mount();
+ *   }
+ * })
+ */
+export async function createContentScriptUi<TApp>(
+  ctx: ContentScriptContext,
+  options: ContentScriptUiOptions<TApp>,
+): Promise<ContentScriptUi<TApp>> {
+  const css = [options.css ?? ''];
+  if (ctx.options?.cssInjectionMode === 'ui') {
+    css.push(await loadCss());
+  }
+
+  const {
+    isolatedElement: uiContainer,
+    parentElement: shadowHost,
+    shadow,
+  } = await createIsolatedElement({
+    name: options.name,
+    css: {
+      textContent: css.join('\n').trim(),
+    },
+    mode: 'open',
+  });
+
+  let mounted: TApp;
+
+  const mount = () => {
+    // Mount UI inside shadow root
+    mounted = options.mount(uiContainer);
+
+    // Add shadow root element to DOM
+    mountContentScriptUiRoot(shadowHost, options);
+    applyContentScriptUiPosition(
+      shadowHost,
+      shadow.querySelector('html'),
+      options,
+    );
+  };
+
+  const remove = () => {
+    // Detatch shadow root from DOM
+    shadowHost.remove();
+    // Cleanup mounted state
+    options.onRemove?.(mounted);
+    // Remove children from uiContainer
+    while (uiContainer.lastChild)
+      uiContainer.removeChild(uiContainer.lastChild);
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    shadow,
+    shadowHost,
+    uiContainer,
+    mount,
+    remove,
+    mounted: mounted!,
+  };
+}
+
+/**
+ * Load the CSS for the current entrypoint.
+ */
+async function loadCss(): Promise<string> {
+  const url = browser.runtime.getURL(`/content-scripts/${__ENTRYPOINT__}.css`);
+  try {
+    const res = await fetch(url);
+    const css = await res.text();
+
+    // Replace :root selectors with :host since we're in a shadow root
+    return css.replaceAll(':root', ':host');
+  } catch (err) {
+    logger.warn(
+      `Failed to load styles @ ${url}. Did you forget to import the stylesheet in your entrypoint?`,
+      err,
+    );
+    return '';
+  }
+}
+
+export interface ContentScriptUi<TApp> {
+  /**
+   * The `HTMLElement` hosting the shadow root used to isolate the UI's styles. This is the element
+   * that get's added to the DOM. This element's style is not isolated from the webpage.
+   */
+  shadowHost: HTMLElement;
+  /**
+   * The container element inside the `ShadowRoot` whose styles are isolated. The UI is mounted
+   * inside this `HTMLElement`.
+   */
+  uiContainer: HTMLElement;
+  /**
+   * The shadow root performing the isolation.
+   */
+  shadow: ShadowRoot;
+  /**
+   * Custom data returned from the `options.mount` function.
+   */
+  mounted: TApp;
+  /**
+   * Function that mounts or remounts the UI on the page.
+   */
+  mount: () => void;
+  /**
+   * Function that removes the UI from the webpage.
+   */
+  remove: () => void;
+}
+
+export type ContentScriptUiOptions<TApp> = ContentScriptPositioningOptions &
+  ContentScriptAnchoredOptions & {
+    /**
+     * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
+     */
+    name: string;
+    /**
+     * Callback executed when mounting the UI. This function should create and append the UI to the
+     * `container` element. It is called every time `ui.mount()` is called
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    mount: (container: Element) => TApp;
+    /**
+     * Callback called when the UI is removed from the webpage. Use to cleanup your UI, like
+     * unmounting your vue or react apps.
+     */
+    onRemove?: (mounted: TApp) => void;
+    /**
+     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
+     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
+     * to pass those styles in here. This is for any additional styles not in the imported CSS.
+     *
+     * See https://wxt.dev/guide/content-script-ui.html for more info.
+     */
+    css?: string;
+  };
@@ -15,12 +15,10 @@ export class WxtLocationChangeEvent extends Event {
 * Returns an event name unique to the extension and content script that's running.
 */
 export function getUniqueEventName(eventName: string): string {
-  // During the build process, import.meta.env is not defined when importing
-  // entrypoints to get their metadata.
+  // During the build process, __ENTRYPOINT__ is not defined when importing entrypoints to get their
+  // metadata.
  const entrypointName =
-    typeof import.meta.env === 'undefined'
-      ? 'build'
-      : import.meta.env.ENTRYPOINT;
+    typeof __ENTRYPOINT__ === 'undefined' ? 'build' : __ENTRYPOINT__;

  return `${browser.runtime.id}:${entrypointName}:${eventName}`;
 }
@@ -1,2 +1,3 @@
 export * from './content-script-context';
-export * from './ui';
+export * from './content-script-ui';
+export * from './content-script-iframe';
@@ -1,407 +0,0 @@
-/** @vitest-environment happy-dom */
-import { describe, it, beforeEach, vi, expect } from 'vitest';
-import { createIntegratedUi, createIframeUi, createShadowRootUi } from '..';
-import { ContentScriptContext } from '../../content-script-context';
-
-function appendTestApp(container: HTMLElement) {
-  container.innerHTML = '<app>Hello world</app>';
-}
-
-const fetch = vi.fn();
-
-describe('Content Script UIs', () => {
-  let ctx: ContentScriptContext;
-
-  beforeEach(() => {
-    document.body.innerHTML = `
-      <div id="parent">
-        <p id="one">one</p>
-        <p id="two">two</p>
-        <p id="three"></p>
-      </div>
-    `;
-    window.fetch = fetch;
-    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
-    ctx = new ContentScriptContext('test');
-  });
-
-  describe('type', () => {
-    describe('integrated', () => {
-      it('should add a wrapper and custom UI to the page', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('div[data-wxt-integrated]'),
-        ).not.toBeNull();
-        expect(document.querySelector('app')).not.toBeNull();
-      });
-
-      it('should allow customizing the wrapper tag', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          tag: 'pre',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('pre[data-wxt-integrated]'),
-        ).not.toBeNull();
-        expect(document.querySelector('app')).not.toBeNull();
-      });
-    });
-
-    describe('iframe', () => {
-      it('should add a wrapper and iframe to the page', () => {
-        const ui = createIframeUi(ctx, {
-          page: '/page.html',
-          position: 'inline',
-        });
-        ui.mount();
-
-        expect(document.querySelector('div[data-wxt-iframe]')).toBeDefined();
-        expect(document.querySelector('iframe')).toBeDefined();
-      });
-    });
-
-    describe('shadow-root', () => {
-      it('should load a shadow root to the page', async () => {
-        const ui = await createShadowRootUi(ctx, {
-          position: 'inline',
-          name: 'test',
-          onMount(uiContainer) {
-            appendTestApp(uiContainer);
-          },
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('test[data-wxt-shadow-root]'),
-        ).not.toBeNull();
-        expect(ui.shadow.querySelector('app')).not.toBeNull();
-      });
-
-      it.each([
-        ['open', 'open'],
-        [undefined, 'open'],
-        ['closed', 'closed'],
-      ] as const)(
-        'should respect the shadow root mode (%s -> %s)',
-        async (input, expected) => {
-          const ui = await createShadowRootUi(ctx, {
-            position: 'inline',
-            name: 'test',
-            mode: input,
-            onMount: appendTestApp,
-          });
-
-          expect(ui.shadow.mode).toBe(expected);
-        },
-      );
-    });
-  });
-
-  describe('position', () => {
-    describe('inline', () => {
-      it('should wrap the UI in a simple div', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'inline',
-          page: '/page.html',
-        });
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe=""><iframe src="chrome-extension://test-extension-id/page.html"></iframe></div>"`,
-        );
-      });
-    });
-
-    describe('overlay', () => {
-      it('should wrap the UI in a positioned div when alignment=undefined', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'overlay',
-          page: '/page.html',
-        });
-        ui.mount();
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; left: 0px;"></iframe></div>"`,
-        );
-      });
-
-      it('should wrap the UI in a positioned div when alignment=top-left', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'overlay',
-          page: '/page.html',
-          alignment: 'top-left',
-        });
-        ui.mount();
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; left: 0px;"></iframe></div>"`,
-        );
-      });
-
-      it('should wrap the UI in a positioned div when alignment=top-right', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'overlay',
-          page: '/page.html',
-          alignment: 'top-right',
-        });
-        ui.mount();
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; right: 0px;"></iframe></div>"`,
-        );
-      });
-
-      it('should wrap the UI in a positioned div when alignment=bottom-right', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'overlay',
-          page: '/page.html',
-          alignment: 'bottom-right',
-        });
-        ui.mount();
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; bottom: 0px; right: 0px;"></iframe></div>"`,
-        );
-      });
-
-      it('should wrap the UI in a positioned div when alignment=bottom-left', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'overlay',
-          page: '/page.html',
-          alignment: 'bottom-left',
-        });
-        ui.mount();
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; bottom: 0px; left: 0px;"></iframe></div>"`,
-        );
-      });
-
-      it('should respect the provided zIndex', () => {
-        const zIndex = 123;
-        const ui = createIframeUi(ctx, {
-          position: 'overlay',
-          page: '/page.html',
-          zIndex,
-        });
-        ui.mount();
-
-        expect(ui.wrapper.style.zIndex).toBe(String(zIndex));
-      });
-    });
-
-    describe('modal', () => {
-      it('should wrap the UI in a div with a fixed position', () => {
-        const ui = createIframeUi(ctx, {
-          position: 'modal',
-          page: '/page.html',
-        });
-        ui.mount();
-
-        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
-          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: fixed; top: 0px; bottom: 0px; left: 0px; right: 0px;"></iframe></div>"`,
-        );
-      });
-
-      it('should respect the provided zIndex', () => {
-        const zIndex = 123;
-        const ui = createIframeUi(ctx, {
-          position: 'modal',
-          page: '/page.html',
-          zIndex,
-        });
-        ui.mount();
-
-        expect(ui.wrapper.style.zIndex).toBe(String(zIndex));
-      });
-    });
-  });
-
-  describe('anchor', () => {
-    describe('undefined', () => {
-      it('should append the element to the body', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('body > div[data-wxt-integrated]'),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('string', () => {
-      it('should append the element using the specified query selector', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          onMount: appendTestApp,
-          anchor: '#parent',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > div[data-wxt-integrated]'),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('Element', () => {
-      it('should append the element using the specified element', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          onMount: appendTestApp,
-          anchor: document.getElementById('parent'),
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > div[data-wxt-integrated]'),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('function', () => {
-      it('should append the element using the specified function', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          onMount: appendTestApp,
-          anchor: () => document.getElementById('parent'),
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > div[data-wxt-integrated]'),
-        ).not.toBeNull();
-      });
-    });
-
-    it('should throw an error when the anchor does not exist', () => {
-      const ui = createIntegratedUi(ctx, {
-        position: 'inline',
-        onMount: appendTestApp,
-        anchor: () => document.getElementById('i-do-not-exist'),
-      });
-
-      expect(ui.mount).toThrow();
-    });
-  });
-
-  describe('append', () => {
-    describe.each([undefined, 'last'] as const)('%s', (append) => {
-      it('should append the element as the last child of the anchor', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          anchor: '#parent',
-          append,
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector(
-            '#parent > div[data-wxt-integrated]:last-child',
-          ),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('first', () => {
-      it('should append the element as the last child of the anchor', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          anchor: '#parent',
-          append: 'first',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector(
-            '#parent > div[data-wxt-integrated]:first-child',
-          ),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('replace', () => {
-      it('should replace the the anchor', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          anchor: '#parent',
-          append: 'replace',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('body > div[data-wxt-integrated]'),
-        ).not.toBeNull();
-        expect(document.querySelector('#parent')).toBeNull();
-      });
-    });
-
-    describe('before', () => {
-      it('should append the UI before the anchor', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          anchor: '#one',
-          append: 'before',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector(
-            '#parent > div[data-wxt-integrated]:first-child',
-          ),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('after', () => {
-      it('should append the UI after the anchor', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          anchor: '#three',
-          append: 'after',
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector(
-            '#parent > div[data-wxt-integrated]:last-child',
-          ),
-        ).not.toBeNull();
-      });
-    });
-
-    describe('function', () => {
-      it('should append the UI using a function', () => {
-        const ui = createIntegratedUi(ctx, {
-          position: 'inline',
-          anchor: '#parent',
-          append: (anchor, ui) => {
-            anchor.replaceWith(ui);
-          },
-          onMount: appendTestApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('body > div[data-wxt-integrated]'),
-        ).not.toBeNull();
-        expect(document.querySelector('#parent')).toBeNull();
-      });
-    });
-  });
-});
@@ -1,247 +0,0 @@
-import { browser } from '~/browser';
-import { ContentScriptContext } from '..';
-import {
-  ContentScriptAnchoredOptions,
-  ContentScriptPositioningOptions,
-  IframeContentScriptUi,
-  IframeContentScriptUiOptions,
-  IntegratedContentScriptUi,
-  IntegratedContentScriptUiOptions,
-  ShadowRootContentScriptUi,
-  ShadowRootContentScriptUiOptions,
-} from './types';
-import { logger } from '~/sandbox/utils/logger';
-import { createIsolatedElement } from '@webext-core/isolated-element';
-export * from './types';
-
-/**
- * Create a content script UI without any isolation.
- *
- * @see https://wxt.dev/guide/content-script-ui.html#integrated
- */
-export function createIntegratedUi<TMounted>(
-  ctx: ContentScriptContext,
-  options: IntegratedContentScriptUiOptions<TMounted>,
-): IntegratedContentScriptUi<TMounted> {
-  const wrapper = document.createElement(options.tag || 'div');
-  wrapper.setAttribute('data-wxt-integrated', '');
-
-  let mounted: TMounted | undefined = undefined;
-  const mount = () => {
-    applyPosition(wrapper, undefined, options);
-    mountUi(wrapper, options);
-    mounted = options.onMount?.(wrapper);
-  };
-  const remove = () => {
-    options.onRemove?.(mounted);
-    wrapper.remove();
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    mounted,
-    wrapper,
-    mount,
-    remove,
-  };
-}
-
-/**
- * Create a content script UI using an iframe.
- *
- * @see https://wxt.dev/guide/content-script-ui.html#iframe
- */
-export function createIframeUi<TMounted>(
-  ctx: ContentScriptContext,
-  options: IframeContentScriptUiOptions<TMounted>,
-): IframeContentScriptUi<TMounted> {
-  const wrapper = document.createElement('div');
-  wrapper.setAttribute('data-wxt-iframe', '');
-  const iframe = document.createElement('iframe');
-  iframe.src = browser.runtime.getURL(options.page);
-  wrapper.appendChild(iframe);
-
-  let mounted: TMounted | undefined = undefined;
-  const mount = () => {
-    applyPosition(wrapper, iframe, options);
-    mountUi(wrapper, options);
-    mounted = options.onMount?.(wrapper, iframe);
-  };
-  const remove = () => {
-    options.onRemove?.(mounted);
-    wrapper.remove();
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    mounted,
-    iframe,
-    wrapper,
-    mount,
-    remove,
-  };
-}
-
-/**
- * Create a content script UI inside a [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot).
- *
- * > This function is async because it has to load the CSS via a network call.
- *
- * @see https://wxt.dev/guide/content-script-ui.html#shadowroot
- */
-export async function createShadowRootUi<TMounted>(
-  ctx: ContentScriptContext,
-  options: ShadowRootContentScriptUiOptions<TMounted>,
-): Promise<ShadowRootContentScriptUi<TMounted>> {
-  const css = [options.css ?? ''];
-  if (ctx.options?.cssInjectionMode === 'ui') {
-    const entryCss = await loadCss();
-    // Replace :root selectors with :host since we're in a shadow root
-    css.push(entryCss.replaceAll(':root', ':host'));
-  }
-
-  const {
-    isolatedElement: uiContainer,
-    parentElement: shadowHost,
-    shadow,
-  } = await createIsolatedElement({
-    name: options.name,
-    css: {
-      textContent: css.join('\n').trim(),
-    },
-    mode: options.mode ?? 'open',
-    isolateEvents: options.isolateEvents,
-  });
-  shadowHost.setAttribute('data-wxt-shadow-root', '');
-
-  let mounted: TMounted;
-
-  const mount = () => {
-    // Add shadow root element to DOM
-    mountUi(shadowHost, options);
-    applyPosition(shadowHost, shadow.querySelector('html'), options);
-    // Mount UI inside shadow root
-    mounted = options.onMount(uiContainer, shadow, shadowHost);
-  };
-
-  const remove = () => {
-    // Cleanup mounted state
-    options.onRemove?.(mounted);
-    // Detatch shadow root from DOM
-    shadowHost.remove();
-    // Remove children from uiContainer
-    while (uiContainer.lastChild)
-      uiContainer.removeChild(uiContainer.lastChild);
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    shadow,
-    shadowHost,
-    uiContainer,
-    mount,
-    remove,
-    mounted: mounted!,
-  };
-}
-
-function applyPosition(
-  root: HTMLElement,
-  positionedElement: HTMLElement | undefined | null,
-  options: ContentScriptPositioningOptions,
-): void {
-  // No positioning for inline UIs
-  if (options.position === 'inline') return;
-
-  if (options.zIndex != null) root.style.zIndex = String(options.zIndex);
-
-  root.style.overflow = 'visible';
-  root.style.position = 'relative';
-  root.style.width = '0';
-  root.style.height = '0';
-  root.style.display = 'block';
-
-  if (positionedElement) {
-    if (options.position === 'overlay') {
-      positionedElement.style.position = 'absolute';
-      if (options.alignment?.startsWith('bottom-'))
-        positionedElement.style.bottom = '0';
-      else positionedElement.style.top = '0';
-
-      if (options.alignment?.endsWith('-right'))
-        positionedElement.style.right = '0';
-      else positionedElement.style.left = '0';
-    } else {
-      positionedElement.style.position = 'fixed';
-      positionedElement.style.top = '0';
-      positionedElement.style.bottom = '0';
-      positionedElement.style.left = '0';
-      positionedElement.style.right = '0';
-    }
-  }
-}
-
-function getAnchor(options: ContentScriptAnchoredOptions): Element | undefined {
-  if (options.anchor == null) return document.body;
-
-  let resolved =
-    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
-  if (typeof resolved === 'string')
-    return document.querySelector<Element>(resolved) ?? undefined;
-  return resolved ?? undefined;
-}
-
-function mountUi(
-  root: HTMLElement,
-  options: ContentScriptAnchoredOptions,
-): void {
-  const anchor = getAnchor(options);
-  if (anchor == null)
-    throw Error(
-      'Failed to mount content script UI: could not find anchor element',
-    );
-
-  switch (options.append) {
-    case undefined:
-    case 'last':
-      anchor.append(root);
-      break;
-    case 'first':
-      anchor.prepend(root);
-      break;
-    case 'replace':
-      anchor.replaceWith(root);
-      break;
-    case 'after':
-      anchor.parentElement?.insertBefore(root, anchor.nextElementSibling);
-      break;
-    case 'before':
-      anchor.parentElement?.insertBefore(root, anchor);
-      break;
-    default:
-      options.append(anchor, root);
-      break;
-  }
-}
-
-/**
- * Load the CSS for the current entrypoint.
- */
-async function loadCss(): Promise<string> {
-  const url = browser.runtime.getURL(
-    `/content-scripts/${import.meta.env.ENTRYPOINT}.css`,
-  );
-  try {
-    const res = await fetch(url);
-    return await res.text();
-  } catch (err) {
-    logger.warn(
-      `Failed to load styles @ ${url}. Did you forget to import the stylesheet in your entrypoint?`,
-      err,
-    );
-    return '';
-  }
-}
@@ -1,217 +0,0 @@
-export interface IntegratedContentScriptUi<TMounted>
-  extends ContentScriptUi<TMounted> {
-  /**
-   * A wrapper div that assists in positioning.
-   */
-  wrapper: HTMLElement;
-}
-
-export interface IframeContentScriptUi<TMounted>
-  extends ContentScriptUi<TMounted> {
-  /**
-   * The iframe added to the DOM.
-   */
-  iframe: HTMLIFrameElement;
-  /**
-   * A wrapper div that assists in positioning.
-   */
-  wrapper: HTMLDivElement;
-}
-
-export interface ShadowRootContentScriptUi<TMounted>
-  extends ContentScriptUi<TMounted> {
-  /**
-   * The `HTMLElement` hosting the shadow root used to isolate the UI's styles. This is the element
-   * that get's added to the DOM. This element's style is not isolated from the webpage.
-   */
-  shadowHost: HTMLElement;
-  /**
-   * The container element inside the `ShadowRoot` whose styles are isolated. The UI is mounted
-   * inside this `HTMLElement`.
-   */
-  uiContainer: HTMLElement;
-  /**
-   * The shadow root performing the isolation.
-   */
-  shadow: ShadowRoot;
-}
-
-export interface ContentScriptUi<TMounted> {
-  /**
-   * Function that mounts or remounts the UI on the page.
-   */
-  mount: () => void;
-  /**
-   * Function that removes the UI from the webpage.
-   */
-  remove: () => void;
-  /**>
-   * Custom data returned from the `options.mount` function.
-   */
-  mounted: TMounted | undefined;
-}
-
-export type ContentScriptUiOptions<TMounted> = ContentScriptPositioningOptions &
-  ContentScriptAnchoredOptions & {
-    /**
-     * Callback called before the UI is removed from the webpage. Use to cleanup your UI, like
-     * unmounting your Vue or React apps.
-     */
-    onRemove?: (mounted: TMounted | undefined) => void;
-  };
-
-export type IntegratedContentScriptUiOptions<TMounted> =
-  ContentScriptUiOptions<TMounted> & {
-    /**
-     * Tag used to create the wrapper element.
-     *
-     * @default "div"
-     */
-    tag?: string;
-    /**
-     * Callback executed when mounting the UI. This function should create and append the UI to the
-     * `wrapper` element. It is called every time `ui.mount()` is called.
-     *
-     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
-     */
-    onMount: (wrapper: HTMLElement) => TMounted;
-  };
-
-export type IframeContentScriptUiOptions<TMounted> =
-  ContentScriptUiOptions<TMounted> & {
-    /**
-     * The path to the HTML page that will be shown in the iframe. This string is passed into
-     * `browser.runtime.getURL`.
-     */
-    page: PublicPath;
-    /**
-     * Callback executed when mounting the UI. Use this function to customize the iframe or wrapper
-     * element's appearance. It is called every time `ui.mount()` is called.
-     *
-     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
-     */
-    onMount?: (wrapper: HTMLElement, iframe: HTMLIFrameElement) => TMounted;
-  };
-
-export type ShadowRootContentScriptUiOptions<TMounted> =
-  ContentScriptUiOptions<TMounted> & {
-    /**
-     * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
-     */
-    name: string;
-    /**
-     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
-     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
-     * to pass those styles in here. This is for any additional styles not in the imported CSS.
-     */
-    css?: string;
-    /**
-     * ShadowRoot's mode.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode
-     * @default "open"
-     */
-    mode?: 'open' | 'closed';
-    /**
-     * When enabled, `event.stopPropagation` will be called on events trying to bubble out of the
-     * shadow root.
-     *
-     * - Set to `true` to stop the propagation of a default set of events,
-     *   `["keyup", "keydown", "keypress"]`
-     * - Set to an array of event names to stop the propagation of a custom list of events
-     */
-    isolateEvents?: boolean | string[];
-    /**
-     * Callback executed when mounting the UI. This function should create and append the UI to the
-     * `uiContainer` element. It is called every time `ui.mount()` is called.
-     *
-     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
-     */
-    onMount: (
-      uiContainer: HTMLElement,
-      shadow: ShadowRoot,
-      shadowHost: HTMLElement,
-    ) => TMounted;
-  };
-
-export type ContentScriptOverlayAlignment =
-  | 'top-left'
-  | 'top-right'
-  | 'bottom-left'
-  | 'bottom-right';
-
-/**
- * ![Visualization of different append modes](https://wxt.dev/content-script-ui-append.png)
- */
-export type ContentScriptAppendMode =
-  | 'last'
-  | 'first'
-  | 'replace'
-  | 'before'
-  | 'after'
-  | ((anchor: Element, ui: Element) => void);
-
-export interface ContentScriptInlinePositioningOptions {
-  position: 'inline';
-}
-
-export interface ContentScriptOverlayPositioningOptions {
-  position: 'overlay';
-  /**
-   * The `z-index` used on the `wrapper` element. Set to a positive number to show your UI over website
-   * content.
-   */
-  zIndex?: number;
-  /**
-   * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
-   * which corner is aligned with that 0x0 pixel space.
-   *
-   * ![Visualization of alignment options](https://wxt.dev/content-script-ui-alignment.png)
-   *
-   * @default "top-left"
-   */
-  alignment?: ContentScriptOverlayAlignment;
-}
-
-export interface ContentScriptModalPositioningOptions {
-  position: 'modal';
-  /**
-   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-   * content.
-   */
-  zIndex?: number;
-}
-
-/**
- * Choose between `"inline"`, `"overlay"`, or `"modal" `types.
- *
- * ![Visualization of different types](https://wxt.dev/content-script-ui-type.png)
- */
-export type ContentScriptPositioningOptions =
-  | ContentScriptInlinePositioningOptions
-  | ContentScriptOverlayPositioningOptions
-  | ContentScriptModalPositioningOptions;
-
-export interface ContentScriptAnchoredOptions {
-  /**
-   * A CSS selector, element, or function that returns one of the two. Along with `append`, the
-   * `anchor` dictates where in the page the UI will be added.
-   */
-  anchor?:
-    | string
-    | Element
-    | null
-    | undefined
-    | (() => string | Element | null | undefined);
-  /**
-   * In combination with `anchor`, decide how to add the UI to the DOM.
-   *
-   * - `"last"` (default) - Add the UI as the last child of the `anchor` element
-   * - `"first"` - Add the UI as the last child of the `anchor` element
-   * - `"replace"` - Replace the `anchor` element with the UI.
-   * - `"before"` - Add the UI as the sibling before the `anchor` element
-   * - `"after"` - Add the UI as the sibling after the `anchor` element
-   * - `(anchor, ui) => void` - Customizable function that let's you add the UI to the DOM
-   */
-  append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
-}
@@ -4,3 +4,12 @@
 * @module wxt/client
 */
 export * from './content-scripts';
+export {
+  ContentScriptOverlayAlignment,
+  ContentScriptAppendMode,
+  ContentScriptPositioningOptions,
+  ContentScriptAnchoredOptions,
+  ContentScriptInlinePositioningOptions,
+  ContentScriptOverlayPositioningOptions,
+  ContentScriptModalPositioningOptions,
+} from './utils/content-script-ui';
@@ -0,0 +1,163 @@
+export type ContentScriptOverlayAlignment =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+/**
+ * ![Visualization of different append modes](https://wxt.dev/content-script-ui-append.png)
+ */
+export type ContentScriptAppendMode =
+  | 'last'
+  | 'first'
+  | 'replace'
+  | 'before'
+  | 'after'
+  | ((anchor: Element, ui: Element) => void);
+
+export function mountContentScriptUiRoot(
+  root: HTMLElement,
+  options: ContentScriptAnchoredOptions,
+): void {
+  const anchor = getAnchor(options);
+  if (anchor == null)
+    throw Error(
+      'Failed to mount content script UI: could not find anchor element',
+    );
+
+  switch (options.append) {
+    case undefined:
+    case 'last':
+      anchor.append(root);
+      break;
+    case 'first':
+      if (anchor.firstChild) {
+        anchor.insertBefore(root, anchor.firstChild);
+      } else {
+        anchor.append(root);
+      }
+      break;
+    case 'replace':
+      anchor.replaceWith(root);
+      break;
+    case 'after':
+      anchor.replaceWith(anchor, root);
+      break;
+    case 'before':
+      anchor.replaceWith(root, anchor);
+      break;
+    default:
+      options.append(anchor, root);
+      break;
+  }
+}
+
+export interface ContentScriptInlinePositioningOptions {
+  type: 'inline';
+}
+
+export interface ContentScriptOverlayPositioningOptions {
+  type: 'overlay';
+  /**
+   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
+   * content.
+   */
+  zIndex?: number;
+  /**
+   * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
+   * which corner is aligned with that 0x0 pixel space.
+   *
+   * ![Visualization of alignment options](https://wxt.dev/content-script-ui-alignment.png)
+   *
+   * @default "top-left"
+   */
+  alignment?: ContentScriptOverlayAlignment;
+}
+
+export interface ContentScriptModalPositioningOptions {
+  type: 'modal';
+  /**
+   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
+   * content.
+   */
+  zIndex?: number;
+}
+
+/**
+ * Choose between `"inline"`, `"overlay"`, or `"modal" `types.
+ *
+ * ![Visualization of different types](https://wxt.dev/content-script-ui-type.png)
+ */
+export type ContentScriptPositioningOptions =
+  | ContentScriptInlinePositioningOptions
+  | ContentScriptOverlayPositioningOptions
+  | ContentScriptModalPositioningOptions;
+
+export function applyContentScriptUiPosition(
+  root: HTMLElement,
+  positionedElement: HTMLElement | undefined | null,
+  options: ContentScriptPositioningOptions,
+): void {
+  if (options.type !== 'inline') {
+    if (options.zIndex != null) root.style.zIndex = String(options.zIndex);
+
+    root.style.overflow = 'visible';
+    root.style.position = 'relative';
+    root.style.width = '0';
+    root.style.height = '0';
+    root.style.display = 'block';
+
+    if (positionedElement) {
+      if (options.type === 'overlay') {
+        positionedElement.style.position = 'absolute';
+        if (options.alignment?.startsWith('bottom-'))
+          positionedElement.style.bottom = '0';
+        else positionedElement.style.top = '0';
+
+        if (options.alignment?.endsWith('-right'))
+          positionedElement.style.right = '0';
+        else positionedElement.style.left = '0';
+      } else {
+        positionedElement.style.position = 'fixed';
+        positionedElement.style.top = '0';
+        positionedElement.style.bottom = '0';
+        positionedElement.style.left = '0';
+        positionedElement.style.right = '0';
+      }
+    }
+  }
+}
+
+function getAnchor(options: ContentScriptAnchoredOptions): Element | undefined {
+  if (options.anchor == null) return document.body;
+
+  let resolved =
+    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
+  if (typeof resolved === 'string')
+    return document.querySelector<Element>(resolved) ?? undefined;
+  return resolved ?? undefined;
+}
+
+export interface ContentScriptAnchoredOptions {
+  /**
+   * A CSS selector, element, or function that returns one of the two. Along with `append`, the
+   * `anchor` dictates where in the page the UI will be added.
+   */
+  anchor?:
+    | string
+    | Element
+    | null
+    | undefined
+    | (() => string | Element | null | undefined);
+  /**
+   * In combination with `anchor`, decide how to add the UI to the DOM.
+   *
+   * - `"last"` (default) - Add the UI as the last child of the `anchor` element
+   * - `"first"` - Add the UI as the last child of the `anchor` element
+   * - `"replace"` - Replace the `anchor` element with the UI.
+   * - `"before"` - Add the UI as the sibling before the `anchor` element
+   * - `"after"` - Add the UI as the sibling after the `anchor` element
+   * - `(anchor, ui) => void` - Customizable function that let's you add the UI to the DOM
+   */
+  append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
+}
@@ -1,6 +1,5 @@
 import { BuildOutput, InlineConfig } from '~/types';
-import { internalBuild } from './utils/building';
-import { registerWxt } from './wxt';
+import { getInternalConfig, internalBuild } from './utils/building';

 /**
 * Bundles the extension for production. Returns a promise of the build result. Discovers the `wxt.config.ts` file in
@@ -16,7 +15,6 @@ import { registerWxt } from './wxt';
 * })
 */
 export async function build(config?: InlineConfig): Promise<BuildOutput> {
-  await registerWxt('build', config);
-
-  return await internalBuild();
+  const internalConfig = await getInternalConfig(config ?? {}, 'build');
+  return await internalBuild(internalConfig);
 }
@@ -3,22 +3,19 @@ import {
  BuildStepOutput,
  Entrypoint,
  InlineConfig,
-  ResolvedConfig,
+  InternalConfig,
  UserConfig,
  VirtualEntrypointType,
  WxtBuilder,
  WxtBuilderServer,
 } from '~/types';
 import * as wxtPlugins from './plugins';
-import {
-  getEntrypointBundlePath,
-  isHtmlEntrypoint,
-} from '~/core/utils/entrypoints';
+import { getEntrypointBundlePath } from '~/core/utils/entrypoints';

-export async function createViteBuilder(
+export async function craeteViteBuilder(
  inlineConfig: InlineConfig,
  userConfig: UserConfig,
-  wxtConfig: Omit<ResolvedConfig, 'builder'>,
+  wxtConfig: Omit<InternalConfig, 'builder'>,
 ): Promise<WxtBuilder> {
  const vite = await import('vite');

@@ -43,14 +40,6 @@ export async function createViteBuilder(
    config.build ??= {};
    config.build.outDir = wxtConfig.outDir;
    config.build.emptyOutDir = false;
-    // Disable minification for the dev command
-    if (config.build.minify == null && wxtConfig.command === 'serve') {
-      config.build.minify = false;
-    }
-    // Enable inline sourcemaps for the dev command (so content scripts have sourcemaps)
-    if (config.build.sourcemap == null && wxtConfig.command === 'serve') {
-      config.build.sourcemap = 'inline';
-    }

    config.plugins ??= [];
    config.plugins.push(
@@ -66,10 +55,9 @@ export async function createViteBuilder(
      wxtPlugins.noopBackground(),
      wxtPlugins.globals(wxtConfig),
      wxtPlugins.excludeBrowserPolyfill(wxtConfig),
-      wxtPlugins.defineImportMeta(),
    );
    if (wxtConfig.analysis.enabled) {
-      config.plugins.push(wxtPlugins.bundleAnalysis(wxtConfig));
+      config.plugins.push(wxtPlugins.bundleAnalysis());
    }

    return config;
@@ -79,7 +67,23 @@ export async function createViteBuilder(
   * Return the basic config for building an entrypoint in [lib mode](https://vitejs.dev/guide/build.html#library-mode).
   */
  const getLibModeConfig = (entrypoint: Entrypoint): vite.InlineConfig => {
-    const entry = getRollupEntry(entrypoint);
+    let virtualEntrypointType: VirtualEntrypointType | undefined;
+    switch (entrypoint.type) {
+      case 'background':
+      case 'unlisted-script':
+        virtualEntrypointType = entrypoint.type;
+        break;
+      case 'content-script':
+        virtualEntrypointType =
+          entrypoint.options.world === 'MAIN'
+            ? 'content-script-main-world'
+            : 'content-script-isolated-world';
+        break;
+    }
+    const entry = virtualEntrypointType
+      ? `virtual:wxt-${virtualEntrypointType}?${entrypoint.inputPath}`
+      : entrypoint.inputPath;
+
    const plugins: NonNullable<vite.UserConfig['plugins']> = [
      wxtPlugins.entrypointGroupGlobals(entrypoint),
    ];
@@ -136,9 +140,6 @@ export async function createViteBuilder(
   * Return the basic config for building multiple entrypoints in [multi-page mode](https://vitejs.dev/guide/build.html#multi-page-app).
   */
  const getMultiPageConfig = (entrypoints: Entrypoint[]): vite.InlineConfig => {
-    const htmlEntrypoints = new Set(
-      entrypoints.filter(isHtmlEntrypoint).map((e) => e.name),
-    );
    return {
      mode: wxtConfig.mode,
      plugins: [
@@ -148,18 +149,14 @@ export async function createViteBuilder(
      build: {
        rollupOptions: {
          input: entrypoints.reduce<Record<string, string>>((input, entry) => {
-            input[entry.name] = getRollupEntry(entry);
+            input[entry.name] = entry.inputPath;
            return input;
          }, {}),
          output: {
            // Include a hash to prevent conflicts
            chunkFileNames: 'chunks/[name]-[hash].js',
-            entryFileNames: ({ name }) => {
-              // HTML main JS files go in the chunks folder
-              if (htmlEntrypoints.has(name)) return 'chunks/[name]-[hash].js';
-              // Scripts are output in the root folder
-              return '[name].js';
-            },
+            // Include a hash to prevent conflicts
+            entryFileNames: 'chunks/[name]-[hash].js',
            // We can't control the "name", so we need a hash to prevent conflicts
            assetFileNames: 'assets/[name]-[hash].[ext]',
          },
@@ -229,9 +226,6 @@ export async function createViteBuilder(
        async listen() {
          await viteServer.listen(info.port);
        },
-        async close() {
-          await viteServer.close();
-        },
        transformHtml(...args) {
          return viteServer.transformIndexHtml(...args);
        },
@@ -258,26 +252,3 @@ function getBuildOutputChunks(
  if (Array.isArray(result)) return result.flatMap(({ output }) => output);
  return result.output;
 }
-
-/**
- * Returns the input module ID (virtual or real file) for an entrypoint. The returned string should
- * be passed as an input to rollup.
- */
-function getRollupEntry(entrypoint: Entrypoint): string {
-  let virtualEntrypointType: VirtualEntrypointType | undefined;
-  switch (entrypoint.type) {
-    case 'background':
-    case 'unlisted-script':
-      virtualEntrypointType = entrypoint.type;
-      break;
-    case 'content-script':
-      virtualEntrypointType =
-        entrypoint.options.world === 'MAIN'
-          ? 'content-script-main-world'
-          : 'content-script-isolated-world';
-      break;
-  }
-  return virtualEntrypointType
-    ? `virtual:wxt-${virtualEntrypointType}?${entrypoint.inputPath}`
-    : entrypoint.inputPath;
-}
@@ -1,64 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { Window } from 'happy-dom';
-import { pointToDevServer } from '../devHtmlPrerender';
-import {
-  fakeDevServer,
-  fakeResolvedConfig,
-} from '~/core/utils/testing/fake-objects';
-import { normalizePath } from '~/core/utils/paths';
-import { resolve } from 'node:path';
-
-describe('Dev HTML Prerender Plugin', () => {
-  describe('pointToDevServer', () => {
-    it.each([
-      // File paths should be resolved
-      ['style.css', 'http://localhost:5173/entrypoints/popup/style.css'],
-      ['./style.css', 'http://localhost:5173/entrypoints/popup/style.css'],
-      ['../style.css', 'http://localhost:5173/entrypoints/style.css'],
-      ['~/assets/style.css', 'http://localhost:5173/assets/style.css'],
-      ['~~/assets/style.css', 'http://localhost:5173/assets/style.css'],
-      ['~local/style.css', 'http://localhost:5173/style.css'],
-      ['~absolute/style.css', 'http://localhost:5173/assets/style.css'],
-      ['~file', 'http://localhost:5173/example.css'],
-      // Absolute paths are loaded with the `/@fs/` base path
-      [
-        '~outside/test.css',
-        `http://localhost:5173/@fs${
-          process.platform === 'win32'
-            ? '/' + normalizePath(resolve('/some/non-root/test.css')) // "/D:/some/non-root/test.css"
-            : '/some/non-root/test.css'
-        }`,
-      ],
-      // URLs should not be changed
-      ['https://example.com/style.css', 'https://example.com/style.css'],
-    ])('should transform "%s" into "%s"', (input, expected) => {
-      const { document } = new Window({
-        url: 'http://localhost',
-      });
-      const root = '/some/root';
-      const config = fakeResolvedConfig({
-        root,
-        alias: {
-          '~local': '.',
-          '~absolute': `${root}/assets`,
-          '~file': `${root}/example.css`,
-          '~outside': `${root}/../non-root`,
-          '~~': root,
-          '~': root,
-        },
-      });
-      const server = fakeDevServer({
-        hostname: 'localhost',
-        port: 5173,
-        origin: 'http://localhost:5173',
-      });
-      const id = root + '/entrypoints/popup/index.html';
-
-      document.head.innerHTML = `<link rel="stylesheet" href="${input}" />`;
-      pointToDevServer(config, server, id, document as any, 'link', 'href');
-
-      const actual = document.querySelector('link')!;
-      expect(actual.getAttribute('href')).toBe(expected);
-    });
-  });
-});
@@ -1,25 +1,12 @@
 import type * as vite from 'vite';
-import { visualizer } from '@aklinker1/rollup-plugin-visualizer';
-import { ResolvedConfig } from '~/types';
-import path from 'node:path';
+import { visualizer } from 'rollup-plugin-visualizer';

 let increment = 0;

-export function bundleAnalysis(
-  config: Omit<ResolvedConfig, 'builder'>,
-): vite.Plugin {
+export function bundleAnalysis(): vite.Plugin {
  return visualizer({
+    emitFile: true,
    template: 'raw-data',
-    filename: path.resolve(
-      config.analysis.outputDir,
-      `${config.analysis.outputName}-${increment++}.json`,
-    ),
-  });
-}
-
-/**
- * @deprecated FOR TESTING ONLY.
- */
-export function resetBundleIncrement() {
-  increment = 0;
+    filename: `stats-${increment++}.json`,
+  }) as vite.Plugin;
 }
@@ -1,5 +1,5 @@
 import type * as vite from 'vite';
-import { Entrypoint, ResolvedConfig } from '~/types';
+import { Entrypoint, InternalConfig } from '~/types';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';

 /**
@@ -14,7 +14,7 @@ import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
 */
 export function cssEntrypoints(
  entrypoint: Entrypoint,
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.Plugin {
  return {
    name: 'wxt:css-entrypoint',
@@ -1,19 +0,0 @@
-/**
- * Overrides definitions for `import.meta.*`
- *
- * - `import.meta.url`: Without this, background service workers crash trying to access
- *   `document.location`, see https://github.com/wxt-dev/wxt/issues/392
- */
-export function defineImportMeta() {
-  return {
-    name: 'wxt:define',
-    config() {
-      return {
-        define: {
-          // This works for all extension contexts, including background service worker
-          'import.meta.url': 'self.location.href',
-        },
-      };
-    },
-  };
-}
@@ -1,9 +1,8 @@
 import type * as vite from 'vite';
-import { ResolvedConfig, WxtDevServer } from '~/types';
+import { InternalConfig } from '~/types';
 import { getEntrypointName } from '~/core/utils/entrypoints';
 import { parseHTML } from 'linkedom';
-import { dirname, relative, resolve } from 'node:path';
-import { normalizePath } from '~/core/utils/paths';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';

 // Cache the preamble script for all devHtmlPrerender plugins, not just one
 let reactRefreshPreamble = '';
@@ -12,7 +11,7 @@ let reactRefreshPreamble = '';
 * Pre-renders the HTML entrypoints when building the extension to connect to the dev server.
 */
 export function devHtmlPrerender(
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.PluginOption {
  const htmlReloadId = '@wxt/reload-html';
  const resolvedHtmlReloadId = resolve(
@@ -48,10 +47,25 @@ export function devHtmlPrerender(

        const { document } = parseHTML(code);

-        const _pointToDevServer = (querySelector: string, attr: string) =>
-          pointToDevServer(config, server, id, document, querySelector, attr);
-        _pointToDevServer('script[type=module]', 'src');
-        _pointToDevServer('link[rel=stylesheet]', 'href');
+        const pointToDevServer = (
+          querySelector: string,
+          attr: string,
+        ): void => {
+          document.querySelectorAll(querySelector).forEach((element) => {
+            const src = element.getAttribute(attr);
+            if (!src) return;
+
+            if (isAbsolute(src)) {
+              element.setAttribute(attr, server.origin + src);
+            } else if (src.startsWith('.')) {
+              const abs = resolve(dirname(id), src);
+              const pathname = relative(config.root, abs);
+              element.setAttribute(attr, `${server.origin}/${pathname}`);
+            }
+          });
+        };
+        pointToDevServer('script[type=module]', 'src');
+        pointToDevServer('link[rel=stylesheet]', 'href');

        // Add a script to add page reloading
        const reloader = document.createElement('script');
@@ -132,63 +146,3 @@ export function devHtmlPrerender(
    },
  ];
 }
-
-export function pointToDevServer(
-  config: Omit<ResolvedConfig, 'builder'>,
-  server: WxtDevServer,
-  id: string,
-  document: Document,
-  querySelector: string,
-  attr: string,
-) {
-  document.querySelectorAll(querySelector).forEach((element) => {
-    const src = element.getAttribute(attr);
-    if (!src || isUrl(src)) return;
-
-    let resolvedAbsolutePath: string | undefined;
-
-    // Check if src uses a project alias
-    const matchingAlias = Object.entries(config.alias).find(([key]) =>
-      src.startsWith(key),
-    );
-    if (matchingAlias) {
-      // Matches a import alias
-      const [alias, replacement] = matchingAlias;
-      resolvedAbsolutePath = resolve(
-        config.root,
-        src.replace(alias, replacement),
-      );
-    } else {
-      // Some file path relative to the HTML file
-      resolvedAbsolutePath = resolve(dirname(id), src);
-    }
-
-    // Apply the final file path
-    if (resolvedAbsolutePath) {
-      const relativePath = normalizePath(
-        relative(config.root, resolvedAbsolutePath),
-      );
-
-      if (relativePath.startsWith('.')) {
-        // Outside the config.root directory, serve the absolute path
-        let path = normalizePath(resolvedAbsolutePath);
-        // Add "/" to start of windows paths ("D:/some/path" -> "/D:/some/path")
-        if (!path.startsWith('/')) path = '/' + path;
-        element.setAttribute(attr, `${server.origin}/@fs${path}`);
-      } else {
-        // Inside the project, use relative path
-        const url = new URL(relativePath, server.origin);
-        element.setAttribute(attr, url.href);
-      }
-    }
-  });
-}
-
-function isUrl(str: string): boolean {
-  try {
-    new URL(str);
-    return true;
-  } catch {
-    return false;
-  }
-}
@@ -1,11 +1,11 @@
 import { Plugin } from 'vite';
-import { ResolvedConfig } from '~/types';
+import { InternalConfig } from '~/types';

 /**
 * Defines global constants about the dev server. Helps scripts connect to the server's web socket.
 */
 export function devServerGlobals(
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): Plugin {
  return {
    name: 'wxt:dev-server-globals',
@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { ResolvedConfig } from '~/types';
+import { InternalConfig } from '~/types';
 import { fetchCached } from '~/core/utils/network';

 /**
@@ -9,7 +9,7 @@ import { fetchCached } from '~/core/utils/network';
 * @example
 * import "url:https://google-tagmanager.com/gtag?id=XYZ";
 */
-export function download(config: Omit<ResolvedConfig, 'builder'>): Plugin {
+export function download(config: Omit<InternalConfig, 'builder'>): Plugin {
  return {
    name: 'wxt:download',
    resolveId(id) {
@@ -14,7 +14,7 @@ export function entrypointGroupGlobals(
      const define: vite.InlineConfig['define'] = {};
      let name = Array.isArray(entrypointGroup) ? 'html' : entrypointGroup.name;
      for (const global of getEntrypointGlobals(name)) {
-        define[`import.meta.env.${global.name}`] = JSON.stringify(global.value);
+        define[global.name] = JSON.stringify(global.value);
      }
      return {
        define,
@@ -1,4 +1,4 @@
-import { ResolvedConfig } from '~/types';
+import { InternalConfig } from '~/types';
 import type * as vite from 'vite';

 /**
@@ -7,7 +7,7 @@ import type * as vite from 'vite';
 * virtual module.
 */
 export function excludeBrowserPolyfill(
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.Plugin {
  const virtualId = 'virtual:wxt-webextension-polyfill-disabled';

@@ -1,16 +1,16 @@
 import type * as vite from 'vite';
-import { ResolvedConfig } from '~/types';
+import { InternalConfig } from '~/types';
 import { getGlobals } from '~/core/utils/globals';

 export function globals(
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.PluginOption {
  return {
    name: 'wxt:globals',
    config() {
      const define: vite.InlineConfig['define'] = {};
      for (const global of getGlobals(config)) {
-        define[`import.meta.env.${global.name}`] = JSON.stringify(global.value);
+        define[global.name] = JSON.stringify(global.value);
      }
      return {
        define,
@@ -9,7 +9,7 @@ export * from './noopBackground';
 export * from './cssEntrypoints';
 export * from './bundleAnalysis';
 export * from './globals';
-export * from './webextensionPolyfillMock';
+export * from './webextensionPolyfillAlias';
+export * from './webextensionPolyfillInlineDeps';
 export * from './excludeBrowserPolyfill';
 export * from './entrypointGroupGlobals';
-export * from './defineImportMeta';
@@ -1,5 +1,5 @@
 import type * as vite from 'vite';
-import { Entrypoint, ResolvedConfig } from '~/types';
+import { Entrypoint, InternalConfig } from '~/types';
 import { dirname, extname, resolve, join } from 'node:path';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
 import fs, { ensureDir } from 'fs-extra';
@@ -20,7 +20,7 @@ import { normalizePath } from '~/core/utils/paths';
 */
 export function multipageMove(
  entrypoints: Entrypoint[],
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.Plugin {
  return {
    name: 'wxt:multipage-move',
@@ -2,8 +2,9 @@ import { Plugin } from 'vite';
 import { VIRTUAL_NOOP_BACKGROUND_MODULE_ID } from '~/core/utils/constants';

 /**
- * In dev mode, if there's not a background script listed, we need to add one so that the web socket
- * connection is setup and the extension reloads HTML pages and content scripts correctly.
+ * In dev mode, if there's not a background script listed, we need to add one.
+ *
+ * This define's a virtual module that is basically just a noop.
 */
 export function noopBackground(): Plugin {
  const virtualModuleId = VIRTUAL_NOOP_BACKGROUND_MODULE_ID;
@@ -15,7 +16,7 @@ export function noopBackground(): Plugin {
    },
    load(id) {
      if (id === resolvedVirtualModuleId) {
-        return `import { defineBackground } from 'wxt/sandbox';\nexport default defineBackground(() => void 0)`;
+        return `import { defineBackground } from 'wxt/client';\nexport default defineBackground(() => void 0)`;
      }
    },
  };
@@ -1,8 +1,8 @@
-import { ResolvedConfig } from '~/types';
+import { InternalConfig } from '~/types';
 import type * as vite from 'vite';

 export function tsconfigPaths(
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.Plugin {
  return {
    name: 'wxt:aliases',
@@ -1,5 +1,6 @@
 import { createUnimport } from 'unimport';
-import { ResolvedConfig } from '~/types';
+import { InternalConfig } from '~/types';
+import { getUnimportOptions } from '~/core/utils/unimport';
 import type * as vite from 'vite';
 import { extname } from 'path';

@@ -16,9 +17,9 @@ const ENABLED_EXTENSIONS = new Set([
 * Inject any global imports defined by unimport
 */
 export function unimport(
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): vite.PluginOption {
-  const options = config.imports;
+  const options = getUnimportOptions(config);
  if (options === false) return [];

  const unimport = createUnimport(options);
@@ -35,11 +36,7 @@ export function unimport(
      // Don't transform non-js files
      if (!ENABLED_EXTENSIONS.has(extname(id))) return;

-      const injected = await unimport.injectImports(code, id);
-      return {
-        code: injected.code,
-        map: injected.s.generateMap({ hires: 'boundary', source: id }),
-      };
+      return unimport.injectImports(code, id);
    },
  };
 }
@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { ResolvedConfig, VirtualEntrypointType } from '~/types';
+import { InternalConfig, VirtualEntrypointType } from '~/types';
 import fs from 'fs-extra';
 import { resolve } from 'path';
 import { normalizePath } from '~/core/utils/paths';
@@ -9,7 +9,7 @@ import { normalizePath } from '~/core/utils/paths';
 */
 export function virtualEntrypoint(
  type: VirtualEntrypointType,
-  config: Omit<ResolvedConfig, 'builder'>,
+  config: Omit<InternalConfig, 'builder'>,
 ): Plugin {
  const virtualId = `virtual:wxt-${type}?`;
  const resolvedVirtualId = `\0${virtualId}`;
@@ -0,0 +1,28 @@
+import path from 'node:path';
+import type * as vite from 'vite';
+import { InternalConfig } from '~/types';
+
+/**
+ * Creates an alias to redirect "webextension-polyfill" imports to WXT's `fakeBrowser`.
+ *
+ * This should only be used during tests.
+ */
+export function webextensionPolyfillAlias(
+  config: Omit<InternalConfig, 'builder'>,
+): vite.PluginOption {
+  return {
+    name: 'wxt:webextension-polyfill-test-alias',
+    config() {
+      return {
+        resolve: {
+          alias: {
+            'webextension-polyfill': path.resolve(
+              config.root,
+              'node_modules/wxt/dist/virtual/mock-browser',
+            ),
+          },
+        },
+      };
+    },
+  };
+}
@@ -0,0 +1,24 @@
+import type * as vite from 'vite';
+
+/**
+ * Add all deps that import `webextension-polyfill` to `test.server.deps.inline`.
+ *
+ * TODO: Auto-detect non-wxt dependencies via `npm list`.
+ */
+export function webextensionPolyfillInlineDeps(): vite.PluginOption {
+  return {
+    name: 'wxt:testing-inline-deps',
+    config() {
+      const wxtModules = ['wxt/browser'];
+      return {
+        test: {
+          server: {
+            deps: {
+              inline: [...wxtModules],
+            },
+          },
+        },
+      };
+    },
+  };
+}
@@ -1,41 +0,0 @@
-import path from 'node:path';
-import type * as vite from 'vite';
-import { ResolvedConfig } from '~/types';
-
-/**
- * Mock `webextension-polyfill` by inlining all dependencies that import it and adding a custom
- * alias so that Vite resolves to a mocked version of the module.
- *
- * There are two ways to mark a module as inline:
- * 1. Use partial file paths ("wxt/dist/browser.js") in the `test.server.deps.inline` option.
- * 2. Use module names ("wxt" or "@webext-core/messaging") in the `ssr.noExternalize` option.
- *
- * This plugin uses the second approach since it's a little more intuative to understand.
- *
- * TODO: Detect non-wxt dependencies (like `@webext-core/*`) that import `webextension-polyfill` via
- * `npm list` and inline them automatically.
- */
-export function webextensionPolyfillMock(
-  config: Omit<ResolvedConfig, 'builder'>,
-): vite.PluginOption {
-  return {
-    name: 'wxt:testing-inline-deps',
-    config() {
-      return {
-        resolve: {
-          alias: {
-            // Alias to use a mocked version of the polyfill
-            'webextension-polyfill': path.resolve(
-              config.root,
-              'node_modules/wxt/dist/virtual/mock-browser',
-            ),
-          },
-        },
-        ssr: {
-          // Inline all WXT modules
-          noExternal: ['wxt'],
-        },
-      };
-    },
-  };
-}
@@ -2,12 +2,14 @@ import {
  BuildStepOutput,
  EntrypointGroup,
  InlineConfig,
+  InternalConfig,
  ServerInfo,
  WxtDevServer,
 } from '~/types';
 import {
  getEntrypointBundlePath,
-  isHtmlEntrypoint,
+  getEntrypointOutputFile,
+  resolvePerBrowserOption,
 } from '~/core/utils/entrypoints';
 import {
  getContentScriptCssFiles,
@@ -15,18 +17,15 @@ import {
 } from '~/core/utils/manifest';
 import {
  internalBuild,
+  getInternalConfig,
  detectDevChanges,
  rebuild,
-  findEntrypoints,
 } from '~/core/utils/building';
 import { createExtensionRunner } from '~/core/runners';
 import { consola } from 'consola';
 import { Mutex } from 'async-mutex';
 import pc from 'picocolors';
 import { relative } from 'node:path';
-import { registerWxt, wxt } from './wxt';
-import { unnormalizePath } from './utils/paths';
-import { mapWxtOptionsToRegisteredContentScript } from './utils/content-scripts';

 /**
 * Creates a dev server and pre-builds all the files that need to exist before loading the extension.
@@ -49,60 +48,28 @@ export async function createServer(
    origin,
  };

-  const buildAndOpenBrowser = async () => {
-    // Build after starting the dev server so it can be used to transform HTML files
-    server.currentOutput = await internalBuild();
-
-    // Add file watchers for files not loaded by the dev server. See
-    // https://github.com/wxt-dev/wxt/issues/428#issuecomment-1944731870
-    try {
-      server.watcher.add(getExternalOutputDependencies(server));
-    } catch (err) {
-      wxt.config.logger.warn('Failed to register additional file paths:', err);
-    }
-
-    // Open browser after everything is ready to go.
-    await runner.openBrowser();
-  };
-
-  /**
-   * Stops the previous runner, grabs the latest config, and recreates the runner.
-   */
-  const closeAndRecreateRunner = async () => {
-    await runner.closeBrowser();
-    await wxt.reloadConfig();
-    runner = await createExtensionRunner();
-  };
-
  // Server instance must be created first so its reference can be added to the internal config used
  // to pre-render entrypoints
  const server: WxtDevServer = {
    ...serverInfo,
-    get watcher() {
-      return builderServer.watcher;
-    },
-    get ws() {
-      return builderServer.ws;
-    },
-    currentOutput: undefined,
+    watcher: undefined as any, // Filled out later down below
+    ws: undefined as any, // Filled out later down below
+    currentOutput: undefined as any, // Filled out later down below
    async start() {
      await builderServer.listen();
-      wxt.logger.success(`Started dev server @ ${serverInfo.origin}`);
-      await buildAndOpenBrowser();
-    },
-    async stop() {
-      await runner.closeBrowser();
-      await builderServer.close();
-    },
-    async restart() {
-      await closeAndRecreateRunner();
-      await buildAndOpenBrowser();
+      config.logger.success(`Started dev server @ ${serverInfo.origin}`);
+
+      // Build after starting the dev server so it can be used to transform HTML files
+      server.currentOutput = await internalBuild(config);
+
+      // Open browser after everything is ready to go.
+      await runner.openBrowser(config);
    },
    transformHtml(url, html, originalUrl) {
      return builderServer.transformHtml(url, html, originalUrl);
    },
-    reloadContentScript(payload) {
-      server.ws.send('wxt:reload-content-script', payload);
+    reloadContentScript(contentScript) {
+      server.ws.send('wxt:reload-content-script', contentScript);
    },
    reloadPage(path) {
      server.ws.send('wxt:reload-page', path);
@@ -110,28 +77,34 @@ export async function createServer(
    reloadExtension() {
      server.ws.send('wxt:reload-extension');
    },
-    async restartBrowser() {
-      await closeAndRecreateRunner();
-      await runner.openBrowser();
-    },
  };

-  await registerWxt('serve', inlineConfig, server);
+  const getLatestConfig = () =>
+    getInternalConfig(inlineConfig ?? {}, 'serve', server);
+  let config = await getLatestConfig();

-  let [runner, builderServer] = await Promise.all([
-    createExtensionRunner(),
-    wxt.config.builder.createServer(server),
+  const [runner, builderServer] = await Promise.all([
+    createExtensionRunner(config),
+    config.builder.createServer(server),
  ]);

+  server.watcher = builderServer.watcher;
+  server.ws = builderServer.ws;
+
  // Register content scripts for the first time after the background starts up since they're not
  // listed in the manifest
  server.ws.on('wxt:background-initialized', () => {
-    if (server.currentOutput == null) return;
-    reloadContentScripts(server.currentOutput.steps, server);
+    reloadContentScripts(server.currentOutput.steps, config, server);
  });

  // Listen for file changes and reload different parts of the extension accordingly
-  const reloadOnChange = createFileReloader(server);
+  const reloadOnChange = createFileReloader({
+    server,
+    getLatestConfig,
+    updateConfig(newConfig) {
+      config = newConfig;
+    },
+  });
  server.watcher.on('all', reloadOnChange);

  return server;
@@ -146,51 +119,48 @@ async function getPort(): Promise<number> {
 * Returns a function responsible for reloading different parts of the extension when a file
 * changes.
 */
-function createFileReloader(server: WxtDevServer) {
+function createFileReloader(options: {
+  server: WxtDevServer;
+  getLatestConfig: () => Promise<InternalConfig>;
+  updateConfig: (config: InternalConfig) => void;
+}) {
+  const { server, getLatestConfig, updateConfig } = options;
  const fileChangedMutex = new Mutex();
  const changeQueue: Array<[string, string]> = [];

  return async (event: string, path: string) => {
-    await wxt.reloadConfig();
+    const config = await getLatestConfig();
+    updateConfig(config);

    // Here, "path" is a non-normalized path (ie: C:\\users\\... instead of C:/users/...)
-    if (path.startsWith(wxt.config.outBaseDir)) return;
+    if (path.startsWith(config.outBaseDir)) return;
    changeQueue.push([event, path]);

    await fileChangedMutex.runExclusive(async () => {
-      if (server.currentOutput == null) return;
-
-      const fileChanges = changeQueue
-        .splice(0, changeQueue.length)
-        .map(([_, file]) => file);
+      const fileChanges = changeQueue.splice(0, changeQueue.length);
      if (fileChanges.length === 0) return;

      const changes = detectDevChanges(fileChanges, server.currentOutput);
      if (changes.type === 'no-change') return;

-      if (changes.type === 'full-restart') {
-        wxt.logger.info('Config changed, restarting server...');
-        server.restart();
-        return;
-      }
-
-      if (changes.type === 'browser-restart') {
-        wxt.logger.info('Runner config changed, restarting browser...');
-        server.restartBrowser();
-        return;
-      }
-
      // Log the entrypoints that were effected
-      wxt.logger.info(
-        `Changed: ${Array.from(new Set(fileChanges))
-          .map((file) => pc.dim(relative(wxt.config.root, file)))
+      config.logger.info(
+        `Changed: ${Array.from(new Set(fileChanges.map((change) => change[1])))
+          .map((file) => pc.dim(relative(config.root, file)))
          .join(', ')}`,
      );
+      const rebuiltNames = changes.rebuildGroups
+        .flat()
+        .map((entry) => {
+          return pc.cyan(
+            relative(config.outDir, getEntrypointOutputFile(entry, '')),
+          );
+        })
+        .join(pc.dim(', '));

      // Rebuild entrypoints on change
-      const allEntrypoints = await findEntrypoints();
      const { output: newOutput } = await rebuild(
-        allEntrypoints,
+        config,
        // TODO: this excludes new entrypoints, so they're not built until the dev command is restarted
        changes.rebuildGroups,
        changes.cachedOutput,
@@ -201,23 +171,15 @@ function createFileReloader(server: WxtDevServer) {
      switch (changes.type) {
        case 'extension-reload':
          server.reloadExtension();
-          consola.success(`Reloaded extension`);
          break;
        case 'html-reload':
-          const { reloadedNames } = reloadHtmlPages(
-            changes.rebuildGroups,
-            server,
-          );
-          consola.success(`Reloaded: ${getFilenameList(reloadedNames)}`);
+          reloadHtmlPages(changes.rebuildGroups, server, config);
          break;
        case 'content-script-reload':
-          reloadContentScripts(changes.changedSteps, server);
-          const rebuiltNames = changes.rebuildGroups
-            .flat()
-            .map((entry) => entry.name);
-          consola.success(`Reloaded: ${getFilenameList(rebuiltNames)}`);
+          reloadContentScripts(changes.changedSteps, config, server);
          break;
      }
+      consola.success(`Reloaded: ${rebuiltNames}`);
    });
  };
 }
@@ -225,25 +187,35 @@ function createFileReloader(server: WxtDevServer) {
 /**
 * From the server, tell the client to reload content scripts from the provided build step outputs.
 */
-function reloadContentScripts(steps: BuildStepOutput[], server: WxtDevServer) {
-  if (wxt.config.manifestVersion === 3) {
+function reloadContentScripts(
+  steps: BuildStepOutput[],
+  config: InternalConfig,
+  server: WxtDevServer,
+) {
+  if (config.manifestVersion === 3) {
    steps.forEach((step) => {
-      if (server.currentOutput == null) return;
-
      const entry = step.entrypoints;
      if (Array.isArray(entry) || entry.type !== 'content-script') return;

-      const js = [getEntrypointBundlePath(entry, wxt.config.outDir, '.js')];
+      const js = [getEntrypointBundlePath(entry, config.outDir, '.js')];
      const cssMap = getContentScriptsCssMap(server.currentOutput, [entry]);
      const css = getContentScriptCssFiles([entry], cssMap);

      server.reloadContentScript({
-        registration: entry.options.registration,
-        contentScript: mapWxtOptionsToRegisteredContentScript(
-          entry.options,
-          js,
-          css,
+        allFrames: resolvePerBrowserOption(
+          entry.options.allFrames,
+          config.browser,
        ),
+        excludeMatches: resolvePerBrowserOption(
+          entry.options.excludeMatches,
+          config.browser,
+        ),
+        matches: resolvePerBrowserOption(entry.options.matches, config.browser),
+        runAt: resolvePerBrowserOption(entry.options.runAt, config.browser),
+        // @ts-expect-error: Chrome accepts this, not typed in webextension-polyfill (https://developer.chrome.com/docs/extensions/reference/scripting/#type-RegisteredContentScript)
+        world: resolvePerBrowserOption(entry.options.world, config.browser),
+        js,
+        css,
      });
    });
  } else {
@@ -254,51 +226,10 @@ function reloadContentScripts(steps: BuildStepOutput[], server: WxtDevServer) {
 function reloadHtmlPages(
  groups: EntrypointGroup[],
  server: WxtDevServer,
-): { reloadedNames: string[] } {
-  // groups might contain other files like background/content scripts, and we only care about the HTMl pages
-  const htmlEntries = groups.flat().filter(isHtmlEntrypoint);
-
-  htmlEntries.forEach((entry) => {
-    const path = getEntrypointBundlePath(entry, wxt.config.outDir, '.html');
+  config: InternalConfig,
+) {
+  groups.flat().forEach((entry) => {
+    const path = getEntrypointBundlePath(entry, config.outDir, '.html');
    server.reloadPage(path);
  });
-
-  return {
-    reloadedNames: htmlEntries.map((entry) => entry.name),
-  };
-}
-
-function getFilenameList(names: string[]): string {
-  return names
-    .map((name) => {
-      return pc.cyan(name);
-    })
-    .join(pc.dim(', '));
-}
-
-/**
- * Based on the current build output, return a list of files that are:
- * 1. Not in node_modules
- * 2. Not inside project root
- */
-function getExternalOutputDependencies(server: WxtDevServer) {
-  return (
-    server.currentOutput?.steps
-      .flatMap((step, i) => {
-        if (Array.isArray(step.entrypoints) && i === 0) {
-          // Dev server is already watching all HTML/esm files
-          return [];
-        }
-
-        return step.chunks.flatMap((chunk) => {
-          if (chunk.type === 'asset') return [];
-          return chunk.moduleIds;
-        });
-      })
-      .filter(
-        (file) => !file.includes('node_modules') && !file.startsWith('\x00'),
-      )
-      .map(unnormalizePath)
-      .filter((file) => !file.startsWith(wxt.config.root)) ?? []
-  );
 }
@@ -90,25 +90,26 @@ interface Template {

 async function listTemplates(): Promise<Template[]> {
  try {
-    const res = await fetch('https://ungh.cc/repos/wxt-dev/wxt/files/main');
+    const res = await fetch(
+      'https://api.github.com/repos/wxt-dev/wxt/contents/templates',
+      {
+        headers: {
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      },
+    );
    if (res.status >= 300)
      throw Error(`Request failed with status ${res.status} ${res.statusText}`);

-    const data = (await res.json()) as {
-      meta: {
-        sha: string;
-      };
-      files: Array<{
-        path: string;
-        mode: string;
-        sha: string;
-        size: number;
-      }>;
-    };
-    return data.files
-      .map((item) => item.path.match(/templates\/(.+)\/package\.json/)?.[1])
-      .filter((name) => name != null)
-      .map((name) => ({ name: name!, path: `templates/${name}` }))
+    const data = (await res.json()) as Array<{
+      type: 'file' | 'dir';
+      name: string;
+      path: string;
+    }>;
+    return data
+      .filter((item: any) => item.type === 'dir')
+      .map((item) => ({ name: item.name, path: item.path }))
      .sort((l, r) => {
        const lWeight = TEMPLATE_SORT_WEIGHT[l.name] ?? Number.MAX_SAFE_INTEGER;
        const rWeight = TEMPLATE_SORT_WEIGHT[r.name] ?? Number.MAX_SAFE_INTEGER;
@@ -1,11 +1,15 @@
 import { InlineConfig } from '~/types';
-import { findEntrypoints, generateTypesDir } from '~/core/utils/building';
-import { registerWxt, wxt } from './wxt';
+import {
+  findEntrypoints,
+  generateTypesDir,
+  getInternalConfig,
+} from '~/core/utils/building';

 export async function prepare(config: InlineConfig) {
-  await registerWxt('build', config);
-  wxt.logger.info('Generating types...');
+  const internalConfig = await getInternalConfig(config, 'build');

-  const entrypoints = await findEntrypoints();
-  await generateTypesDir(entrypoints);
+  internalConfig.logger.info('Generating types...');
+
+  const entrypoints = await findEntrypoints(internalConfig);
+  await generateTypesDir(entrypoints, internalConfig);
 }
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { createExtensionRunner } from '..';
-import { setFakeWxt } from '~/core/utils/testing/fake-objects';
+import { fakeInternalConfig } from '~/core/utils/testing/fake-objects';
 import { mock } from 'vitest-mock-extended';
 import { createSafariRunner } from '../safari';
 import { createWslRunner } from '../wsl';
@@ -26,62 +26,54 @@ const createWebExtRunnerMock = vi.mocked(createWebExtRunner);

 describe('createExtensionRunner', () => {
  it('should return a Safari runner when browser is "safari"', async () => {
-    setFakeWxt({
-      config: {
-        browser: 'safari',
-      },
+    const config = fakeInternalConfig({
+      browser: 'safari',
    });
    const safariRunner = mock<ExtensionRunner>();
    createSafariRunnerMock.mockReturnValue(safariRunner);

-    await expect(createExtensionRunner()).resolves.toBe(safariRunner);
+    await expect(createExtensionRunner(config)).resolves.toBe(safariRunner);
  });

  it('should return a WSL runner when `is-wsl` is true', async () => {
    isWslMock.mockResolvedValueOnce(true);
-    setFakeWxt({
-      config: {
-        browser: 'chrome',
-      },
+    const config = fakeInternalConfig({
+      browser: 'chrome',
    });
    const wslRunner = mock<ExtensionRunner>();
    createWslRunnerMock.mockReturnValue(wslRunner);

-    await expect(createExtensionRunner()).resolves.toBe(wslRunner);
+    await expect(createExtensionRunner(config)).resolves.toBe(wslRunner);
  });

  it('should return a manual runner when `runner.disabled` is true', async () => {
    isWslMock.mockResolvedValueOnce(false);
-    setFakeWxt({
-      config: {
-        browser: 'chrome',
-        runnerConfig: {
-          config: {
-            disabled: true,
-          },
+    const config = fakeInternalConfig({
+      browser: 'chrome',
+      runnerConfig: {
+        config: {
+          disabled: true,
        },
      },
    });
    const manualRunner = mock<ExtensionRunner>();
    createManualRunnerMock.mockReturnValue(manualRunner);

-    await expect(createExtensionRunner()).resolves.toBe(manualRunner);
+    await expect(createExtensionRunner(config)).resolves.toBe(manualRunner);
  });

  it('should return a web-ext runner otherwise', async () => {
-    setFakeWxt({
-      config: {
-        browser: 'chrome',
-        runnerConfig: {
-          config: {
-            disabled: undefined,
-          },
+    const config = fakeInternalConfig({
+      browser: 'chrome',
+      runnerConfig: {
+        config: {
+          disabled: undefined,
        },
      },
    });
    const manualRunner = mock<ExtensionRunner>();
    createWebExtRunnerMock.mockReturnValue(manualRunner);

-    await expect(createExtensionRunner()).resolves.toBe(manualRunner);
+    await expect(createExtensionRunner(config)).resolves.toBe(manualRunner);
  });
 });
@@ -1,16 +1,17 @@
-import { ExtensionRunner } from '~/types';
+import { InternalConfig, ExtensionRunner } from '~/types';
 import { createWslRunner } from './wsl';
 import { createWebExtRunner } from './web-ext';
 import { createSafariRunner } from './safari';
 import { createManualRunner } from './manual';
 import { isWsl } from '~/core/utils/wsl';
-import { wxt } from '../wxt';

-export async function createExtensionRunner(): Promise<ExtensionRunner> {
-  if (wxt.config.browser === 'safari') return createSafariRunner();
+export async function createExtensionRunner(
+  config: InternalConfig,
+): Promise<ExtensionRunner> {
+  if (config.browser === 'safari') return createSafariRunner();

  if (await isWsl()) return createWslRunner();
-  if (wxt.config.runnerConfig.config?.disabled) return createManualRunner();
+  if (config.runnerConfig.config?.disabled) return createManualRunner();

  return createWebExtRunner();
 }
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Aaron Klinker	4ac87bef44	Bump to alpha2	2023-12-17 11:31:17 -06:00
Aaron Klinker	4caaa1bc4d	Update test snapshots	2023-12-17 11:31:11 -06:00
Aaron Klinker	e46920b6a0	Fix sandbox exports	2023-12-17 11:28:33 -06:00
Aaron Klinker	6d4dae59c6	Update readme	2023-12-17 11:25:06 -06:00
Aaron Klinker	1f3616b056	Better organize and type the virtual modules to ensure PNP works	2023-12-17 11:18:35 -06:00
Aaron Klinker	78a146b1ca	Remove NPMRC from init	2023-12-17 10:06:12 -06:00
Aaron Klinker	8447f9aa7c	Release version for testing	2023-12-17 09:53:27 -06:00
Aaron Klinker	ee768f84bb	Remove wxt/client inline for vitest	2023-12-17 09:49:38 -06:00
Aaron Klinker	cfd4979a7a	Fix docs	2023-12-17 09:41:43 -06:00
Aaron Klinker	de5b4e16cd	cleanup	2023-12-17 09:32:55 -06:00
Aaron Klinker	5c696da6e2	Fix build	2023-12-17 09:30:28 -06:00
Aaron Klinker	2363144bb6	Cleanup	2023-12-17 09:15:05 -06:00
Aaron Klinker	9e2d11d8db	List imports by hand	2023-12-16 12:37:13 -06:00
Aaron Klinker	f2523c778f	Only export types for polyfill	2023-12-16 12:29:15 -06:00
Aaron Klinker	04a51581fc	Fix tests, don't auto-import `WebextensionPolyfill` namespace	2023-12-16 12:28:25 -06:00
Aaron Klinker	bb40db78e3	Import all dependencies from WXT	2023-12-16 12:20:15 -06:00