wxt 0.21.3 → 0.21.5

package/dist/{modules.mjs → modules/index.mjs}

@@ -1,6 +1,6 @@
-import { glob } from "tinyglobby";
 import { resolve } from "node:path";
-//#region src/modules.ts
+import { glob } from "tinyglobby";
+//#region src/modules/index.ts
 function defineWxtModule(module) {
 	if (typeof module === "function") return { setup: module };
 	return module;
@@ -102,16 +102,25 @@ function addViteConfig(wxt, viteConfig) {
 *
 * @example
 *   export default defineWxtModule((wxt) => {
-*     addWxtPlugin(wxt, 'wxt-module-analytics/client-plugin');
+*     addWxtPlugin(
+*       wxt,
+*       'wxt-module-analytics/background-plugin',
+*       (entrypoint) => entrypoint.type === 'background',
+*     );
 *   });
 *
 * @param wxt The wxt instance provided by the module's setup function.
 * @param plugin An import from an NPM module, or an absolute file path to the
 *   file to load at runtime.
+* @param apply Optional. Return `true` to load the plugin in the given
+*   entrypoint. Defaults to loading the plugin in every entrypoint.
 */
-function addWxtPlugin(wxt, plugin) {
+function addWxtPlugin(wxt, plugin, apply) {
 	wxt.hooks.hook("config:resolved", (wxt) => {
-		wxt.config.plugins.push(plugin);
+		wxt.config.plugins.push({
+			module: plugin,
+			apply
+		});
 	});
 }
 /**

package/dist/prepare.d.mts

@@ -0,0 +1,6 @@
+import { InlineConfig } from "./types.mjs";
+
+//#region src/prepare.d.ts
+declare function prepare(config: InlineConfig): Promise<void>;
+//#endregion
+export { prepare };

package/dist/prepare.mjs

@@ -0,0 +1,11 @@
+import { registerWxt, wxt } from "./internal/wxt.mjs";
+import { findEntrypoints } from "./internal/find-entrypoints.mjs";
+import { generateWxtDir } from "./internal/generate-wxt-dir.mjs";
+//#region src/prepare.ts
+async function prepare(config) {
+	await registerWxt("build", config);
+	wxt.logger.info("Generating types...");
+	await generateWxtDir(await findEntrypoints());
+}
+//#endregion
+export { prepare };

package/dist/testing/wxt-vitest-plugin.mjs

@@ -1,9 +1,9 @@
-import { tsconfigPaths } from "../core/builders/vite/plugins/tsconfigPaths.mjs";
-import { globals } from "../core/builders/vite/plugins/globals.mjs";
-import { extensionApiMock } from "../core/builders/vite/plugins/extensionApiMock.mjs";
-import { resolveAppConfig } from "../core/builders/vite/plugins/resolveAppConfig.mjs";
-import "../core/builders/vite/plugins/index.mjs";
-import { registerWxt, wxt } from "../core/wxt.mjs";
+import { addRuntimeEnvEntries } from "../internal/builders/vite/plugins/add-runtime-env-entries.mjs";
+import { extensionApiMock } from "../internal/builders/vite/plugins/extension-api-mock.mjs";
+import { resolveAppConfig } from "../internal/builders/vite/plugins/resolve-app-config.mjs";
+import { tsconfigPaths } from "../internal/builders/vite/plugins/tsconfig-paths.mjs";
+import "../internal/builders/vite/plugins/index.mjs";
+import { registerWxt, wxt } from "../internal/wxt.mjs";
 import UnimportPlugin from "unimport/unplugin";
 //#region src/testing/wxt-vitest-plugin.ts
 /**
@@ -26,7 +26,7 @@ import UnimportPlugin from "unimport/unplugin";
 async function WxtVitest(inlineConfig) {
 	await registerWxt("serve", inlineConfig ?? {});
 	const plugins = [
-		globals(wxt.config),
+		addRuntimeEnvEntries(wxt.config),
 		tsconfigPaths(wxt.config),
 		resolveAppConfig(wxt.config),
 		extensionApiMock(wxt.config)

package/dist/types.d.mts

@@ -19,13 +19,13 @@
  *     });
  *   });
  */import { ContentScriptContext } from "./utils/content-script-context.mjs";
-import { ManifestContentScript } from "./core/utils/types.mjs";
+import { ManifestContentScript } from "./internal-utils/type-utils.mjs";
 import { Hookable, NestedHooks } from "hookable";
 import { Import, UnimportOptions } from "unimport";
-import { PluginVisualizerOptions } from "@aklinker1/rollup-plugin-visualizer";
 import * as Nypm from "nypm";
 import { ResolvedConfig } from "c12";
 import { LogLevel } from "consola";
+import { PluginVisualizerOptions } from "@aklinker1/rollup-plugin-visualizer";
 import { Browser } from "@wxt-dev/browser";
 import * as vite from "vite";
 
@@ -544,8 +544,8 @@ interface WxtHooks {
    * Called when WXT has created Vite's config for the dev server. Useful if you
    * want to add plugins or update the vite config per entrypoint group.
    *
-   * @param viteConfig The config that will be used to build the entrypoints.
-   *   Can be updated by reference.
+   * @param config The config that will be used to build the entrypoints. Can be
+   *   updated by reference.
    */
   'vite:devServer:extendConfig': (config: vite.InlineConfig) => HookResult;
 }
@@ -634,6 +634,17 @@ interface Logger {
   success(...args: any[]): void;
   level: LogLevel;
 }
+/**
+ * The logger available at `wxt.logger` and `wxt.config.logger`. Extends
+ * {@link Logger} with a `warnOnce` which only logs a message once per process.
+ */
+interface WxtLogger extends Logger {
+  /**
+   * Same as {@link Logger.warn}, but only logs a given message once per process,
+   * even if called multiple times with the same arguments.
+   */
+  warnOnce(...args: any[]): void;
+}
 interface BaseEntrypointOptions {
   /**
    * List of target browsers to include this entrypoint in. Defaults to being
@@ -672,7 +683,7 @@ interface BaseScriptEntrypointOptions extends BaseEntrypointOptions {
    * the default IIFE variable name may conflict with an existing variable on
    * the target page. This applies to content scripts with world=MAIN, and
    * others, such as unlisted scripts, that could be dynamically injected into
-   * the page with a <script> tag.
+   * the page with a `<script>` tag.
    *
    * Available options:
    *
@@ -1077,7 +1088,7 @@ interface ConfigEnv {
   /**
    * Manifest version passed in from the CLI via the `--mv2` or `--mv3` flags.
    * When not passed, it depends on the target browser. See [the
-   * guide](https://wxt.dev/guide/key-concepts/multiple-browsers.html#target-manifest-version)
+   * guide](https://wxt.dev/guide/essentials/target-different-browsers.html#target-a-manifest-version)
    * for more details.
    */
   manifestVersion: 2 | 3;
@@ -1122,21 +1133,6 @@ interface WebExtConfig {
    *   default_directory: "/my/custom/dir",
    *   },
    *   }
-   *
-   * @default
-   * // Enable dev mode and allow content script sourcemaps
-   * {
-   *   devtools: {
-   *     synced_preferences_sync_disabled: {
-   *       skipContentScripts: false,
-   *     },
-   *   }
-   *   extensions: {
-   *     ui: {
-   *       developer_mode: true,
-   *     },
-   *   }
-   * }
    */
   chromiumPref?: Record<string, any>;
   /**
@@ -1299,7 +1295,7 @@ interface WxtHooks {
    * Called once all entrypoints have been grouped into their build groups.
    *
    * @param wxt The configured WXT object
-   * @param entrypoints The list of groups to build in each build step
+   * @param groups The list of groups to build in each build step
    */
   'entrypoints:grouped': (wxt: Wxt, groups: EntrypointGroup[]) => HookResult;
   /**
@@ -1307,7 +1303,7 @@ interface WxtHooks {
    * reference to add or remove public files.
    *
    * @param wxt The configured WXT object
-   * @param entrypoints The list of files that will be copied into the output
+   * @param files The list of files that will be copied into the output
    *   directory
    */
   'build:publicAssets': (wxt: Wxt, files: ResolvedPublicFile[]) => HookResult;
@@ -1381,16 +1377,47 @@ interface Wxt {
   hooks: Hookable<WxtHooks>;
   /** Alias for `wxt.hooks.hook(...)`. */
   hook: Hookable<WxtHooks>['hook'];
-  /** Alias for config.logger */
-  logger: Logger;
+  /** Alias for `config.logger`. */
+  logger: WxtLogger;
   /** Reload config file and update `wxt.config` with the result. */
   reloadConfig: () => Promise<void>;
   /** Package manager utilities. */
   pm: WxtPackageManager;
   /** If the dev server was started, it will be available. */
   server?: WxtDevServer;
-  /** The module in charge of executing all the build steps. */
+  /**
+   * The module in charge of executing all the build steps.
+   *
+   * To override the entire builder process, set this value in a module's
+   * `setup` function or during the `config:resolved` hook.
+   *
+   * ```ts
+   * wxt.build = new MyBuilder(wxt.config);
+   * ```
+   */
   builder: WxtBuilder;
+  /**
+   * Service responsible for discovering entrypoints in a project.
+   *
+   * To override how entrypoints are discovered, set this value in a module's
+   * `setup` function or during the `config:resolved` hook.
+   *
+   * ```ts
+   * wxt.entrypointFinder = new MyEntrypointFinder(wxt.config);
+   * ```
+   */
+  entrypointFinder: EntrypointFinder;
+  /**
+   * Service responsible for opening the browser during dev mode.
+   *
+   * To override how the browser is opened, set this value in a module's `setup`
+   * function or during the `config:resolved` hook.
+   *
+   * ```ts
+   * wxt.runner = new MyRunner(wxt.config);
+   * ```
+   */
+  runner: ExtensionRunner;
 }
 interface ResolvedConfig$1 {
   root: string;
@@ -1433,11 +1460,12 @@ interface ResolvedConfig$1 {
   targetBrowsers: TargetBrowser[];
   manifestVersion: TargetManifestVersion;
   env: ConfigEnv;
-  logger: Logger;
+  logger: WxtLogger;
   imports: WxtResolvedUnimportOptions;
   manifest: UserManifest;
   fsCache: FsCache;
   webExt: ResolvedConfig<WebExtConfig>;
+  /** @deprecated Use `wxt.runner` instead of `wxt.config.runner` */
   runner: ExtensionRunner;
   zip: {
     name?: string;
@@ -1507,13 +1535,27 @@ interface ResolvedConfig$1 {
   builtinModules: WxtModule<any>[];
   userModules: WxtModuleWithMetadata<any>[];
   /**
-   * An array of string to import plugins from. These paths should be resolvable
-   * by vite, and they should `export default defineWxtPlugin(...)`.
+   * Plugins registered via `addWxtPlugin`. Each entry's `module` should be
+   * resolvable by vite, and should `export default defineWxtPlugin(...)`. An
+   * optional `apply` function restricts which entrypoints the plugin loads in.
    *
    * @example
-   *   ['@wxt-dev/module-vue/plugin', 'wxt-module-google-analytics/plugin'];
+   *   [{ module: '@wxt-dev/module-vue/plugin' }];
+   */
+  plugins: Array<string | WxtPluginEntry>;
+}
+/**
+ * A plugin registered via `addWxtPlugin`, along with an optional `apply`
+ * function controlling which entrypoints it's loaded in.
+ */
+interface WxtPluginEntry {
+  /** Import path or absolute file path to the plugin module. */
+  module: string;
+  /**
+   * Return `true` to include the plugin in this entrypoint. When omitted, the
+   * plugin is included in every entrypoint.
    */
-  plugins: string[];
+  apply?: (entrypoint: Entrypoint) => boolean;
 }
 interface FsCache {
   set(key: string, value: string): Promise<void>;
@@ -1523,31 +1565,32 @@ interface ExtensionRunner {
   openBrowser(): Promise<void>;
   closeBrowser?(): Promise<void>;
   /** Whether or not this runner actually opens the browser. */
-  canOpen?(): boolean;
+  canOpen?(): Promise<boolean>;
 }
 type EslintGlobalsPropValue = boolean | 'readonly' | 'readable' | 'writable' | 'writeable';
+type EslintConfigVersion = 8 | 9;
 interface Eslintrc {
   /**
-   * When true, generates a file that can be used by ESLint to know which
-   * variables are valid globals.
+   * Determines if and in what format a config file will be generated to inform
+   * ESLint of unimport globals.
    *
-   * - `'auto'`: Check if eslint is installed, and if it is, generate a compatible
-   *   config file.
-   * - `true`: Same as `'auto'`.
-   * - `false`: Don't generate the file.
-   * - `8`: Generate a config file compatible with ESLint 8.
-   * - `9`: Generate a config file compatible with ESLint 9.
+   * - `true`: If eslint is installed, generate a compatible config file based on
+   *   the installed version.
+   * - `false`: Never generate the file.
+   * - `8`: Generate an eslintrc file compatible with ESLint &lte; 8.
+   * - `9`: Generate a flat config file compatible with ESLint &gte; 9.
+   * - `'auto'` (Deprecated): Same as `true`.
    *
-   * @default 'auto'
+   * @default true
    */
-  enabled?: 'auto' | boolean | 8 | 9;
+  enabled?: boolean | 'auto' | EslintConfigVersion;
   /**
    * File path to save the generated eslint config.
    *
    * Default depends on version of ESLint used:
    *
-   * - 9 and above: './.wxt/eslint-auto-imports.mjs'
-   * - 8 and below: './.wxt/eslintrc-auto-import.json'
+   * - &gte; 9: './.wxt/eslint-auto-imports.mjs'
+   * - &lte; 8: './.wxt/eslintrc-auto-import.json'
    */
   filePath?: string;
   /** @default true */
@@ -1555,7 +1598,7 @@ interface Eslintrc {
 }
 interface ResolvedEslintrc {
   /** False if disabled, otherwise the major version of ESLint installed */
-  enabled: false | 8 | 9;
+  enabled: false | EslintConfigVersion;
   /** Absolute path */
   filePath: string;
   globalsPropValue: EslintGlobalsPropValue;
@@ -1567,7 +1610,7 @@ type WxtUnimportOptions = Partial<UnimportOptions> & {
    * extended, fixes these lint errors.
    *
    * See
-   * [https://wxt.dev/guide/key-concepts/auto-imports.html#eslint](https://wxt.dev/guide/key-concepts/auto-imports.html#eslint)
+   * [https://wxt.dev/guide/essentials/config/auto-imports.html#eslint](https://wxt.dev/guide/essentials/config/auto-imports.html#eslint)
    */
   eslintrc?: Eslintrc;
 };
@@ -1700,5 +1743,12 @@ interface WxtDirFileEntry {
   /** Set to `true` to add a reference to this file in `.wxt/wxt.d.ts`. */
   tsReference?: boolean;
 }
+interface EntrypointFinder {
+  /**
+   * @returns A list of file paths (absolute or relative to
+   *   `wxt.config.rootDir`) to load as entrypoints for.
+   */
+  findEntrypoints(): Promise<EntrypointInfo[]> | EntrypointInfo[];
+}
 //#endregion
-export { BackgroundDefinition, BackgroundEntrypoint, BackgroundEntrypointOptions, BaseContentScriptEntrypointOptions, BaseEntrypoint, BaseEntrypointOptions, BaseScriptEntrypointOptions, BuildOutput, BuildStepOutput, ConfigEnv, ContentScriptDefinition, ContentScriptEntrypoint, CopiedPublicFile, Dependency, Entrypoint, EntrypointGroup, EntrypointInfo, EslintGlobalsPropValue, Eslintrc, ExtensionRunner, FirefoxDataCollectionPermissions, FirefoxDataCollectionType, FsCache, GeneratedPublicFile, GenericEntrypoint, HookResult, InlineConfig, IsolatedWorldContentScriptDefinition, IsolatedWorldContentScriptEntrypointOptions, Logger, MainWorldContentScriptDefinition, MainWorldContentScriptEntrypointOptions, OnContentScriptStopped, OptionsEntrypoint, OptionsEntrypointOptions, OutputAsset, OutputChunk, OutputFile, PerBrowserMap, PerBrowserOption, PopupEntrypoint, PopupEntrypointOptions, PrepareTsconfigs, PublicPathEntry, ReloadContentScriptPayload, ResolvedBasePublicFile, ResolvedConfig$1 as ResolvedConfig, ResolvedEslintrc, ResolvedPerBrowserOptions, ResolvedPublicFile, ServerInfo, SidepanelEntrypoint, SidepanelEntrypointOptions, TargetBrowser, TargetManifestVersion, ThemeIcon, UnlistedScriptDefinition, UnlistedScriptEntrypoint, UserConfig, UserManifest, UserManifestFn, WebExtConfig, Wxt, WxtBuilder, WxtBuilderServer, WxtCommand, WxtDevServer, WxtDirEntry, WxtDirFileEntry, WxtDirTypeReferenceEntry, WxtHooks, WxtModule, WxtModuleOptions, WxtModuleSetup, WxtModuleWithMetadata, WxtPackageManager, WxtPlugin, WxtResolvedUnimportOptions, WxtUnimportOptions, WxtViteConfig };
+export { BackgroundDefinition, BackgroundEntrypoint, BackgroundEntrypointOptions, BaseContentScriptEntrypointOptions, BaseEntrypoint, BaseEntrypointOptions, BaseScriptEntrypointOptions, BuildOutput, BuildStepOutput, ConfigEnv, ContentScriptDefinition, ContentScriptEntrypoint, CopiedPublicFile, Dependency, Entrypoint, EntrypointFinder, EntrypointGroup, EntrypointInfo, EslintConfigVersion, EslintGlobalsPropValue, Eslintrc, ExtensionRunner, FirefoxDataCollectionPermissions, FirefoxDataCollectionType, FsCache, GeneratedPublicFile, GenericEntrypoint, HookResult, InlineConfig, IsolatedWorldContentScriptDefinition, IsolatedWorldContentScriptEntrypointOptions, Logger, MainWorldContentScriptDefinition, MainWorldContentScriptEntrypointOptions, OnContentScriptStopped, OptionsEntrypoint, OptionsEntrypointOptions, OutputAsset, OutputChunk, OutputFile, PerBrowserMap, PerBrowserOption, PopupEntrypoint, PopupEntrypointOptions, PrepareTsconfigs, PublicPathEntry, ReloadContentScriptPayload, ResolvedBasePublicFile, ResolvedConfig$1 as ResolvedConfig, ResolvedEslintrc, ResolvedPerBrowserOptions, ResolvedPublicFile, ServerInfo, SidepanelEntrypoint, SidepanelEntrypointOptions, TargetBrowser, TargetManifestVersion, ThemeIcon, UnlistedScriptDefinition, UnlistedScriptEntrypoint, UserConfig, UserManifest, UserManifestFn, WebExtConfig, Wxt, WxtBuilder, WxtBuilderServer, WxtCommand, WxtDevServer, WxtDirEntry, WxtDirFileEntry, WxtDirTypeReferenceEntry, WxtHooks, WxtLogger, WxtModule, WxtModuleOptions, WxtModuleSetup, WxtModuleWithMetadata, WxtPackageManager, WxtPlugin, WxtPluginEntry, WxtResolvedUnimportOptions, WxtUnimportOptions, WxtViteConfig };

package/dist/utils/content-script-context.d.mts

@@ -141,4 +141,4 @@ interface WxtWindowEventMap extends WindowEventMap {
   'wxt:locationchange': WxtLocationChangeEvent;
 }
 //#endregion
-export { ContentScriptContext, WxtWindowEventMap };
+export { ContentScriptContext, type WxtLocationChangeEvent, WxtWindowEventMap };

package/dist/utils/content-script-ui/iframe.d.mts

@@ -6,6 +6,8 @@ import * as _$wxt_browser0 from "wxt/browser";
 /**
  * Create a content script UI using an iframe.
  *
+ * @param options - Iframe options. See {@link ContentScriptUiOptions} for shared
+ *   positioning, anchoring, `append`, and removal options.
  * @see https://wxt.dev/guide/essentials/content-scripts.html#iframe
  */
 declare function createIframeUi<TMounted>(ctx: ContentScriptContext, options: IframeContentScriptUiOptions<TMounted>): IframeContentScriptUi<TMounted>;
@@ -15,6 +17,11 @@ interface IframeContentScriptUi<TMounted> extends ContentScriptUi<TMounted> {
   /** A wrapper div that assists in positioning. */
   wrapper: HTMLDivElement;
 }
+/**
+ * {@inheritDoc wxt/utils/content-script-ui/types!ContentScriptUiOptions}
+ *
+ * @interface
+ */
 type IframeContentScriptUiOptions<TMounted> = ContentScriptUiOptions<TMounted> & {
   /**
    * The path to the HTML page that will be shown in the iframe. This string

package/dist/utils/content-script-ui/iframe.mjs

@@ -5,6 +5,8 @@ import { browser } from "wxt/browser";
 /**
 * Create a content script UI using an iframe.
 *
+* @param options - Iframe options. See {@link ContentScriptUiOptions} for shared
+*   positioning, anchoring, `append`, and removal options.
 * @see https://wxt.dev/guide/essentials/content-scripts.html#iframe
 */
 function createIframeUi(ctx, options) {

package/dist/utils/content-script-ui/integrated.d.mts

@@ -5,6 +5,8 @@ import { ContentScriptUi, ContentScriptUiOptions } from "./types.mjs";
 /**
  * Create a content script UI without any isolation.
  *
+ * @param options - Integrated UI options. See {@link ContentScriptUiOptions} for
+ *   shared positioning, anchoring, `append`, and removal options.
  * @see https://wxt.dev/guide/essentials/content-scripts.html#integrated
  */
 declare function createIntegratedUi<TMounted>(ctx: ContentScriptContext, options: IntegratedContentScriptUiOptions<TMounted>): IntegratedContentScriptUi<TMounted>;
@@ -17,6 +19,11 @@ interface IntegratedContentScriptUi<TMounted> extends ContentScriptUi<TMounted>
   /** A wrapper div that assists in positioning. */
   wrapper: HTMLElement;
 }
+/**
+ * {@inheritDoc wxt/utils/content-script-ui/types!ContentScriptUiOptions}
+ *
+ * @interface
+ */
 type IntegratedContentScriptUiOptions<TMounted> = ContentScriptUiOptions<TMounted> & {
   /**
    * Tag used to create the wrapper element.

package/dist/utils/content-script-ui/integrated.mjs

@@ -3,6 +3,8 @@ import { applyPosition, createMountFunctions, mountUi } from "./shared.mjs";
 /**
 * Create a content script UI without any isolation.
 *
+* @param options - Integrated UI options. See {@link ContentScriptUiOptions} for
+*   shared positioning, anchoring, `append`, and removal options.
 * @see https://wxt.dev/guide/essentials/content-scripts.html#integrated
 */
 function createIntegratedUi(ctx, options) {

package/dist/utils/content-script-ui/shadow-root.d.mts

@@ -8,6 +8,8 @@ import { ContentScriptUi, ContentScriptUiOptions } from "./types.mjs";
  *
  * > This function is async because it has to load the CSS via a network call.
  *
+ * @param options - Shadow root options. See {@link ContentScriptUiOptions} for
+ *   shared positioning, anchoring, `append`, and removal options.
  * @see https://wxt.dev/guide/essentials/content-scripts.html#shadow-root
  */
 declare function createShadowRootUi<TMounted>(ctx: ContentScriptContext, options: ShadowRootContentScriptUiOptions<TMounted>): Promise<ShadowRootContentScriptUi<TMounted>>;
@@ -26,6 +28,11 @@ interface ShadowRootContentScriptUi<TMounted> extends ContentScriptUi<TMounted>
   /** The shadow root performing the isolation. */
   shadow: ShadowRoot;
 }
+/**
+ * {@inheritDoc wxt/utils/content-script-ui/types!ContentScriptUiOptions}
+ *
+ * @interface
+ */
 type ShadowRootContentScriptUiOptions<TMounted> = ContentScriptUiOptions<TMounted> & {
   /**
    * The name of the custom component used to host the ShadowRoot. Must be

package/dist/utils/content-script-ui/shadow-root.mjs

@@ -11,6 +11,8 @@ import { createIsolatedElement } from "@webext-core/isolated-element";
 *
 * > This function is async because it has to load the CSS via a network call.
 *
+* @param options - Shadow root options. See {@link ContentScriptUiOptions} for
+*   shared positioning, anchoring, `append`, and removal options.
 * @see https://wxt.dev/guide/essentials/content-scripts.html#shadow-root
 */
 async function createShadowRootUi(ctx, options) {

package/dist/utils/content-script-ui/types.d.mts

@@ -3,6 +3,13 @@
 interface ContentScriptUi<TMounted> extends MountFunctions {
   mounted: TMounted | undefined;
 }
+/**
+ * Options shared by integrated, shadow root, and iframe UIs.
+ *
+ * `position` selects `"inline"`, `"overlay"`, or `"modal"` positioning.
+ * `zIndex` controls the positioning element's stacking level for overlays and
+ * modals. `alignment` is available for overlays.
+ */
 type ContentScriptUiOptions<TMounted> = ContentScriptPositioningOptions & ContentScriptAnchoredOptions & {
   /**
    * Callback called before the UI is removed from the webpage. Use to cleanup
@@ -20,19 +27,24 @@ type ContentScriptOverlayAlignment = 'top-left' | 'top-right' | 'bottom-left' |
  * modes](https://wxt.dev/content-script-ui-append.png)
  */
 type ContentScriptAppendMode = 'last' | 'first' | 'replace' | 'before' | 'after' | ((anchor: Element, ui: Element) => void);
+/** Inline positioning does not support `zIndex` or `alignment`. */
 interface ContentScriptInlinePositioningOptions {
+  /** Choose between `"inline"`, `"overlay"`, or `"modal"` positioning. */
   position: 'inline';
+  zIndex?: never;
+  alignment?: never;
 }
 interface ContentScriptOverlayPositioningOptions {
   position: 'overlay';
   /**
-   * The `z-index` used on the `wrapper` element. Set to a positive number to
+   * The `z-index` used on the positioning 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.
+   * When using `position: "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)
@@ -41,13 +53,17 @@ interface ContentScriptOverlayPositioningOptions {
    */
   alignment?: ContentScriptOverlayAlignment;
 }
+/**
+ * Modal positioning options.
+ *
+ * @property zIndex The `z-index` used on the `shadowHost` element. Set to a
+ *   positive number to show your UI over website content.
+ * @property alignment Only available when `position` is `"overlay"`.
+ */
 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;
+  alignment?: never;
 }
 /**
  * Choose between `"inline"`, `"overlay"`, or `"modal"` positions.

package/dist/utils/internal/custom-events.d.mts

@@ -1,9 +1,19 @@
 //#region src/utils/internal/custom-events.d.ts
+/**
+ * Fired on `window` as `wxt:locationchange` when a content script detects a
+ * same-document URL change.
+ */
 declare class WxtLocationChangeEvent extends Event {
+  /** The URL after the change. */
   readonly newUrl: URL;
+  /** The URL before the change. */
   readonly oldUrl: URL;
   static EVENT_NAME: string;
-  constructor(newUrl: URL, oldUrl: URL);
+  constructor(/** The URL after the change. */
+
+  newUrl: URL, /** The URL before the change. */
+
+  oldUrl: URL);
 }
 //#endregion
 export { WxtLocationChangeEvent };

package/dist/utils/internal/custom-events.mjs

@@ -1,5 +1,9 @@
 import { browser } from "wxt/browser";
 //#region src/utils/internal/custom-events.ts
+/**
+* Fired on `window` as `wxt:locationchange` when a content script detects a
+* same-document URL change.
+*/
 var WxtLocationChangeEvent = class WxtLocationChangeEvent extends Event {
 	static EVENT_NAME = getUniqueEventName("wxt:locationchange");
 	constructor(newUrl, oldUrl) {

package/dist/version.mjs

@@ -1,4 +1,4 @@
 //#region src/version.ts
-const version = "0.21.3";
+const version = "0.21.5";
 //#endregion
 export { version };

package/dist/virtual/background-entrypoint.mjs

@@ -69,8 +69,19 @@ async function reloadContentScriptMv3({ registration, contentScript }) {
 	if (registration === "runtime") await reloadRuntimeContentScriptMv3(contentScript);
 	else await reloadManifestContentScriptMv3(contentScript);
 }
+/**
+* Reloads of one script run one after another. Two reloads that overlap can
+* both read an empty registration list and both register, and the second
+* registration throws "Duplicate script ID".
+*/
+const manifestReloads = /* @__PURE__ */ new Map();
 async function reloadManifestContentScriptMv3(contentScript) {
 	const id = `wxt:${contentScript.js[0]}`;
+	const reload = (manifestReloads.get(id) ?? Promise.resolve()).then(() => reloadManifestContentScriptNow(id, contentScript));
+	manifestReloads.set(id, reload.catch(() => {}));
+	return reload;
+}
+async function reloadManifestContentScriptNow(id, contentScript) {
 	logger.log("Reloading content script:", contentScript);
 	const registered = await browser.scripting.getRegisteredContentScripts();
 	logger.debug("Existing scripts:", registered);

package/dist/{core/zip.d.mts → zip.d.mts}

@@ -1,6 +1,6 @@
-import { InlineConfig } from "../types.mjs";
+import { InlineConfig } from "./types.mjs";
 
-//#region src/core/zip.d.ts
+//#region src/zip.d.ts
 /**
  * Build and zip the extension for distribution.
  *

package/dist/{core/zip.mjs → zip.mjs}

@@ -1,19 +1,17 @@
-import { normalizePath } from "./utils/paths.mjs";
-import "./utils/index.mjs";
-import { safeFilename } from "./utils/strings.mjs";
-import { registerWxt, wxt } from "./wxt.mjs";
-import { findEntrypoints } from "./utils/building/find-entrypoints.mjs";
-import { formatDuration } from "./utils/time.mjs";
-import { printFileList } from "./utils/log/printFileList.mjs";
-import "./utils/log/index.mjs";
-import { getPackageJson } from "./utils/package.mjs";
-import { internalBuild } from "./utils/building/internal-build.mjs";
-import "./utils/building/index.mjs";
+import { normalizePath } from "./internal-utils/path-utils.mjs";
+import { safeFilename } from "./internal-utils/string-utils.mjs";
+import { formatDuration } from "./internal-utils/time-utils.mjs";
+import { registerWxt, wxt } from "./internal/wxt.mjs";
+import { findEntrypoints } from "./internal/find-entrypoints.mjs";
+import { printFileList } from "./internal-utils/log/print-file-list.mjs";
+import "./internal-utils/log/index.mjs";
+import { getPackageJson } from "./internal/package.mjs";
+import { internalBuild } from "./internal/internal-build.mjs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { glob } from "tinyglobby";
 import path from "node:path";
+import { glob } from "tinyglobby";
 import { createZip } from "@aklinker1/zero-zip";
-//#region src/core/zip.ts
+//#region src/zip.ts
 /**
 * Build and zip the extension for distribution.
 *