wxt 0.20.13 → 0.20.15

package/dist/utils/app-config.d.mts

@@ -0,0 +1,6 @@
+import { WxtAppConfig } from "./define-app-config.mjs";
+
+//#region src/utils/app-config.d.ts
+declare function useAppConfig(): WxtAppConfig;
+//#endregion
+export { useAppConfig };

package/dist/utils/app-config.mjs

@@ -1,4 +1,10 @@
 import appConfig from "virtual:app-config";
-export function useAppConfig() {
-  return appConfig;
+
+//#region src/utils/app-config.ts
+/** @module wxt/utils/app-config */
+function useAppConfig() {
+	return appConfig;
 }
+
+//#endregion
+export { useAppConfig };

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

@@ -0,0 +1,134 @@
+import { WxtLocationChangeEvent } from "./internal/custom-events.mjs";
+import { ContentScriptDefinition } from "../types.mjs";
+
+//#region src/utils/content-script-context.d.ts
+/**
+ * Implements [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * Used to detect and stop content script code when the script is invalidated.
+ *
+ * It also provides several utilities like `ctx.setTimeout` and `ctx.setInterval` that should be used in
+ * content scripts instead of `window.setTimeout` or `window.setInterval`.
+ *
+ * To create context for testing, you can use the class's constructor:
+ *
+ * ```ts
+ * import { ContentScriptContext } from 'wxt/utils/content-scripts-context';
+ *
+ * test("storage listener should be removed when context is invalidated", () => {
+ *   const ctx = new ContentScriptContext('test');
+ *   const item = storage.defineItem("local:count", { defaultValue: 0 });
+ *   const watcher = vi.fn();
+ *
+ *   const unwatch = item.watch(watcher);
+ *   ctx.onInvalidated(unwatch); // Listen for invalidate here
+ *
+ *   await item.setValue(1);
+ *   expect(watcher).toBeCalledTimes(1);
+ *   expect(watcher).toBeCalledWith(1, 0);
+ *
+ *   ctx.notifyInvalidated(); // Use this function to invalidate the context
+ *   await item.setValue(2);
+ *   expect(watcher).toBeCalledTimes(1);
+ * });
+ * ```
+ */
+declare class ContentScriptContext implements AbortController {
+  private readonly contentScriptName;
+  readonly options?: Omit<ContentScriptDefinition, "main"> | undefined;
+  private static SCRIPT_STARTED_MESSAGE_TYPE;
+  private id;
+  private abortController;
+  private locationWatcher;
+  constructor(contentScriptName: string, options?: Omit<ContentScriptDefinition, "main"> | undefined);
+  get signal(): AbortSignal;
+  abort(reason?: any): void;
+  get isInvalid(): boolean;
+  get isValid(): boolean;
+  /**
+   * Add a listener that is called when the content script's context is invalidated.
+   *
+   * @returns A function to remove the listener.
+   *
+   * @example
+   * browser.runtime.onMessage.addListener(cb);
+   * const removeInvalidatedListener = ctx.onInvalidated(() => {
+   *   browser.runtime.onMessage.removeListener(cb);
+   * })
+   * // ...
+   * removeInvalidatedListener();
+   */
+  onInvalidated(cb: () => void): () => void;
+  /**
+   * Return a promise that never resolves. Useful if you have an async function that shouldn't run
+   * after the context is expired.
+   *
+   * @example
+   * const getValueFromStorage = async () => {
+   *   if (ctx.isInvalid) return ctx.block();
+   *
+   *   // ...
+   * }
+   */
+  block<T>(): Promise<T>;
+  /**
+   * Wrapper around `window.setInterval` that automatically clears the interval when invalidated.
+   *
+   * Intervals can be cleared by calling the normal `clearInterval` function.
+   */
+  setInterval(handler: () => void, timeout?: number): number;
+  /**
+   * Wrapper around `window.setTimeout` that automatically clears the interval when invalidated.
+   *
+   * Timeouts can be cleared by calling the normal `setTimeout` function.
+   */
+  setTimeout(handler: () => void, timeout?: number): number;
+  /**
+   * Wrapper around `window.requestAnimationFrame` that automatically cancels the request when
+   * invalidated.
+   *
+   * Callbacks can be canceled by calling the normal `cancelAnimationFrame` function.
+   */
+  requestAnimationFrame(callback: FrameRequestCallback): number;
+  /**
+   * Wrapper around `window.requestIdleCallback` that automatically cancels the request when
+   * invalidated.
+   *
+   * Callbacks can be canceled by calling the normal `cancelIdleCallback` function.
+   */
+  requestIdleCallback(callback: IdleRequestCallback, options?: IdleRequestOptions): number;
+  /**
+   * Call `target.addEventListener` and remove the event listener when the context is invalidated.
+   *
+   * Listeners can be canceled by calling the normal `removeEventListener` function.
+   *
+   * Includes additional events useful for content scripts:
+   *
+   * - `"wxt:locationchange"` - Triggered when HTML5 history mode is used to change URL. Content
+   *   scripts are not reloaded when navigating this way, so this can be used to reset the content
+   *   script state on URL change, or run custom code.
+   *
+   * @example
+   * ctx.addEventListener(document, "visibilitychange", () => {
+   *   // ...
+   * });
+   * ctx.addEventListener(window, "wxt:locationchange", () => {
+   *   // ...
+   * });
+   */
+  addEventListener<TType extends keyof WxtWindowEventMap>(target: Window, type: TType, handler: (event: WxtWindowEventMap[TType]) => void, options?: AddEventListenerOptions): void;
+  addEventListener<TType extends keyof DocumentEventMap>(target: Document, type: TType, handler: (event: DocumentEventMap[TType]) => void, options?: AddEventListenerOptions): void;
+  addEventListener<TTarget extends EventTarget>(target: TTarget, ...params: Parameters<TTarget['addEventListener']>): void;
+  /**
+   * @internal
+   * Abort the abort controller and execute all `onInvalidated` listeners.
+   */
+  notifyInvalidated(): void;
+  stopOldScripts(): void;
+  verifyScriptStartedEvent(event: CustomEvent): boolean;
+  listenForNewerScripts(): void;
+}
+interface WxtWindowEventMap extends WindowEventMap {
+  'wxt:locationchange': WxtLocationChangeEvent;
+}
+//#endregion
+export { ContentScriptContext, WxtWindowEventMap };

package/dist/utils/content-script-context.mjs

@@ -1,176 +1,188 @@
-import { browser } from "wxt/browser";
-import { logger } from "../utils/internal/logger.mjs";
-import {
-  getUniqueEventName
-} from "./internal/custom-events.mjs";
+import { logger } from "./internal/logger.mjs";
+import { getUniqueEventName } from "./internal/custom-events.mjs";
 import { createLocationWatcher } from "./internal/location-watcher.mjs";
-export class ContentScriptContext {
-  constructor(contentScriptName, options) {
-    this.contentScriptName = contentScriptName;
-    this.options = options;
-    this.abortController = new AbortController();
-    if (this.isTopFrame) {
-      this.listenForNewerScripts({ ignoreFirstEvent: true });
-      this.stopOldScripts();
-    } else {
-      this.listenForNewerScripts();
-    }
-  }
-  static SCRIPT_STARTED_MESSAGE_TYPE = getUniqueEventName(
-    "wxt:content-script-started"
-  );
-  isTopFrame = window.self === window.top;
-  abortController;
-  locationWatcher = createLocationWatcher(this);
-  receivedMessageIds = /* @__PURE__ */ new Set();
-  get signal() {
-    return this.abortController.signal;
-  }
-  abort(reason) {
-    return this.abortController.abort(reason);
-  }
-  get isInvalid() {
-    if (browser.runtime.id == null) {
-      this.notifyInvalidated();
-    }
-    return this.signal.aborted;
-  }
-  get isValid() {
-    return !this.isInvalid;
-  }
-  /**
-   * Add a listener that is called when the content script's context is invalidated.
-   *
-   * @returns A function to remove the listener.
-   *
-   * @example
-   * browser.runtime.onMessage.addListener(cb);
-   * const removeInvalidatedListener = ctx.onInvalidated(() => {
-   *   browser.runtime.onMessage.removeListener(cb);
-   * })
-   * // ...
-   * removeInvalidatedListener();
-   */
-  onInvalidated(cb) {
-    this.signal.addEventListener("abort", cb);
-    return () => this.signal.removeEventListener("abort", cb);
-  }
-  /**
-   * Return a promise that never resolves. Useful if you have an async function that shouldn't run
-   * after the context is expired.
-   *
-   * @example
-   * const getValueFromStorage = async () => {
-   *   if (ctx.isInvalid) return ctx.block();
-   *
-   *   // ...
-   * }
-   */
-  block() {
-    return new Promise(() => {
-    });
-  }
-  /**
-   * Wrapper around `window.setInterval` that automatically clears the interval when invalidated.
-   *
-   * Intervals can be cleared by calling the normal `clearInterval` function.
-   */
-  setInterval(handler, timeout) {
-    const id = setInterval(() => {
-      if (this.isValid) handler();
-    }, timeout);
-    this.onInvalidated(() => clearInterval(id));
-    return id;
-  }
-  /**
-   * Wrapper around `window.setTimeout` that automatically clears the interval when invalidated.
-   *
-   * Timeouts can be cleared by calling the normal `setTimeout` function.
-   */
-  setTimeout(handler, timeout) {
-    const id = setTimeout(() => {
-      if (this.isValid) handler();
-    }, timeout);
-    this.onInvalidated(() => clearTimeout(id));
-    return id;
-  }
-  /**
-   * Wrapper around `window.requestAnimationFrame` that automatically cancels the request when
-   * invalidated.
-   *
-   * Callbacks can be canceled by calling the normal `cancelAnimationFrame` function.
-   */
-  requestAnimationFrame(callback) {
-    const id = requestAnimationFrame((...args) => {
-      if (this.isValid) callback(...args);
-    });
-    this.onInvalidated(() => cancelAnimationFrame(id));
-    return id;
-  }
-  /**
-   * Wrapper around `window.requestIdleCallback` that automatically cancels the request when
-   * invalidated.
-   *
-   * Callbacks can be canceled by calling the normal `cancelIdleCallback` function.
-   */
-  requestIdleCallback(callback, options) {
-    const id = requestIdleCallback((...args) => {
-      if (!this.signal.aborted) callback(...args);
-    }, options);
-    this.onInvalidated(() => cancelIdleCallback(id));
-    return id;
-  }
-  addEventListener(target, type, handler, options) {
-    if (type === "wxt:locationchange") {
-      if (this.isValid) this.locationWatcher.run();
-    }
-    target.addEventListener?.(
-      type.startsWith("wxt:") ? getUniqueEventName(type) : type,
-      handler,
-      {
-        ...options,
-        signal: this.signal
-      }
-    );
-  }
-  /**
-   * @internal
-   * Abort the abort controller and execute all `onInvalidated` listeners.
-   */
-  notifyInvalidated() {
-    this.abort("Content script context invalidated");
-    logger.debug(
-      `Content script "${this.contentScriptName}" context invalidated`
-    );
-  }
-  stopOldScripts() {
-    window.postMessage(
-      {
-        type: ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE,
-        contentScriptName: this.contentScriptName,
-        messageId: Math.random().toString(36).slice(2)
-      },
-      "*"
-    );
-  }
-  verifyScriptStartedEvent(event) {
-    const isScriptStartedEvent = event.data?.type === ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE;
-    const isSameContentScript = event.data?.contentScriptName === this.contentScriptName;
-    const isNotDuplicate = !this.receivedMessageIds.has(event.data?.messageId);
-    return isScriptStartedEvent && isSameContentScript && isNotDuplicate;
-  }
-  listenForNewerScripts(options) {
-    let isFirst = true;
-    const cb = (event) => {
-      if (this.verifyScriptStartedEvent(event)) {
-        this.receivedMessageIds.add(event.data.messageId);
-        const wasFirst = isFirst;
-        isFirst = false;
-        if (wasFirst && options?.ignoreFirstEvent) return;
-        this.notifyInvalidated();
-      }
-    };
-    addEventListener("message", cb);
-    this.onInvalidated(() => removeEventListener("message", cb));
-  }
-}
+import { browser } from "wxt/browser";
+
+//#region src/utils/content-script-context.ts
+/**
+* Implements [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+* Used to detect and stop content script code when the script is invalidated.
+*
+* It also provides several utilities like `ctx.setTimeout` and `ctx.setInterval` that should be used in
+* content scripts instead of `window.setTimeout` or `window.setInterval`.
+*
+* To create context for testing, you can use the class's constructor:
+*
+* ```ts
+* import { ContentScriptContext } from 'wxt/utils/content-scripts-context';
+*
+* test("storage listener should be removed when context is invalidated", () => {
+*   const ctx = new ContentScriptContext('test');
+*   const item = storage.defineItem("local:count", { defaultValue: 0 });
+*   const watcher = vi.fn();
+*
+*   const unwatch = item.watch(watcher);
+*   ctx.onInvalidated(unwatch); // Listen for invalidate here
+*
+*   await item.setValue(1);
+*   expect(watcher).toBeCalledTimes(1);
+*   expect(watcher).toBeCalledWith(1, 0);
+*
+*   ctx.notifyInvalidated(); // Use this function to invalidate the context
+*   await item.setValue(2);
+*   expect(watcher).toBeCalledTimes(1);
+* });
+* ```
+*/
+var ContentScriptContext = class ContentScriptContext {
+	static SCRIPT_STARTED_MESSAGE_TYPE = getUniqueEventName("wxt:content-script-started");
+	id;
+	abortController;
+	locationWatcher = createLocationWatcher(this);
+	constructor(contentScriptName, options) {
+		this.contentScriptName = contentScriptName;
+		this.options = options;
+		this.id = Math.random().toString(36).slice(2);
+		this.abortController = new AbortController();
+		this.stopOldScripts();
+		this.listenForNewerScripts();
+	}
+	get signal() {
+		return this.abortController.signal;
+	}
+	abort(reason) {
+		return this.abortController.abort(reason);
+	}
+	get isInvalid() {
+		if (browser.runtime?.id == null) this.notifyInvalidated();
+		return this.signal.aborted;
+	}
+	get isValid() {
+		return !this.isInvalid;
+	}
+	/**
+	* Add a listener that is called when the content script's context is invalidated.
+	*
+	* @returns A function to remove the listener.
+	*
+	* @example
+	* browser.runtime.onMessage.addListener(cb);
+	* const removeInvalidatedListener = ctx.onInvalidated(() => {
+	*   browser.runtime.onMessage.removeListener(cb);
+	* })
+	* // ...
+	* removeInvalidatedListener();
+	*/
+	onInvalidated(cb) {
+		this.signal.addEventListener("abort", cb);
+		return () => this.signal.removeEventListener("abort", cb);
+	}
+	/**
+	* Return a promise that never resolves. Useful if you have an async function that shouldn't run
+	* after the context is expired.
+	*
+	* @example
+	* const getValueFromStorage = async () => {
+	*   if (ctx.isInvalid) return ctx.block();
+	*
+	*   // ...
+	* }
+	*/
+	block() {
+		return new Promise(() => {});
+	}
+	/**
+	* Wrapper around `window.setInterval` that automatically clears the interval when invalidated.
+	*
+	* Intervals can be cleared by calling the normal `clearInterval` function.
+	*/
+	setInterval(handler, timeout) {
+		const id = setInterval(() => {
+			if (this.isValid) handler();
+		}, timeout);
+		this.onInvalidated(() => clearInterval(id));
+		return id;
+	}
+	/**
+	* Wrapper around `window.setTimeout` that automatically clears the interval when invalidated.
+	*
+	* Timeouts can be cleared by calling the normal `setTimeout` function.
+	*/
+	setTimeout(handler, timeout) {
+		const id = setTimeout(() => {
+			if (this.isValid) handler();
+		}, timeout);
+		this.onInvalidated(() => clearTimeout(id));
+		return id;
+	}
+	/**
+	* Wrapper around `window.requestAnimationFrame` that automatically cancels the request when
+	* invalidated.
+	*
+	* Callbacks can be canceled by calling the normal `cancelAnimationFrame` function.
+	*/
+	requestAnimationFrame(callback) {
+		const id = requestAnimationFrame((...args) => {
+			if (this.isValid) callback(...args);
+		});
+		this.onInvalidated(() => cancelAnimationFrame(id));
+		return id;
+	}
+	/**
+	* Wrapper around `window.requestIdleCallback` that automatically cancels the request when
+	* invalidated.
+	*
+	* Callbacks can be canceled by calling the normal `cancelIdleCallback` function.
+	*/
+	requestIdleCallback(callback, options) {
+		const id = requestIdleCallback((...args) => {
+			if (!this.signal.aborted) callback(...args);
+		}, options);
+		this.onInvalidated(() => cancelIdleCallback(id));
+		return id;
+	}
+	addEventListener(target, type, handler, options) {
+		if (type === "wxt:locationchange") {
+			if (this.isValid) this.locationWatcher.run();
+		}
+		target.addEventListener?.(type.startsWith("wxt:") ? getUniqueEventName(type) : type, handler, {
+			...options,
+			signal: this.signal
+		});
+	}
+	/**
+	* @internal
+	* Abort the abort controller and execute all `onInvalidated` listeners.
+	*/
+	notifyInvalidated() {
+		this.abort("Content script context invalidated");
+		logger.debug(`Content script "${this.contentScriptName}" context invalidated`);
+	}
+	stopOldScripts() {
+		document.dispatchEvent(new CustomEvent(ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE, { detail: {
+			contentScriptName: this.contentScriptName,
+			messageId: this.id
+		} }));
+		window.postMessage({
+			type: ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE,
+			contentScriptName: this.contentScriptName,
+			messageId: this.id
+		}, "*");
+	}
+	verifyScriptStartedEvent(event) {
+		const isSameContentScript = event.detail?.contentScriptName === this.contentScriptName;
+		const isFromSelf = event.detail?.messageId === this.id;
+		return isSameContentScript && !isFromSelf;
+	}
+	listenForNewerScripts() {
+		const cb = (event) => {
+			if (!(event instanceof CustomEvent) || !this.verifyScriptStartedEvent(event)) return;
+			this.notifyInvalidated();
+		};
+		document.addEventListener(ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE, cb);
+		this.onInvalidated(() => document.removeEventListener(ContentScriptContext.SCRIPT_STARTED_MESSAGE_TYPE, cb));
+	}
+};
+
+//#endregion
+export { ContentScriptContext };

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

@@ -0,0 +1,42 @@
+import { ContentScriptContext } from "../content-script-context.mjs";
+import { ContentScriptUi, ContentScriptUiOptions } from "./types.mjs";
+import * as wxt_browser0 from "wxt/browser";
+
+//#region src/utils/content-script-ui/iframe.d.ts
+/**
+ * Create a content script UI using an iframe.
+ *
+ * @see https://wxt.dev/guide/essentials/content-scripts.html#iframe
+ */
+declare function createIframeUi<TMounted>(ctx: ContentScriptContext, options: IframeContentScriptUiOptions<TMounted>): IframeContentScriptUi<TMounted>;
+interface IframeContentScriptUi<TMounted> extends ContentScriptUi<TMounted> {
+  /**
+   * The iframe added to the DOM.
+   */
+  iframe: HTMLIFrameElement;
+  /**
+   * A wrapper div that assists in positioning.
+   */
+  wrapper: HTMLDivElement;
+}
+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: wxt_browser0.HtmlPublicPath;
+  /**
+   * 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;
+  /**
+   * Callback executed before mounting the UI. Use this function to customize the iframe or wrapper
+   * elements before they are injected into the DOM. It is called every time `ui.mount()` is called.
+   */
+  onBeforeMount?: (wrapper: HTMLElement, iframe: HTMLIFrameElement) => void;
+};
+//#endregion
+export { IframeContentScriptUi, IframeContentScriptUiOptions, createIframeUi };

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

@@ -1,29 +1,44 @@
-import { browser } from "wxt/browser";
 import { applyPosition, createMountFunctions, mountUi } from "./shared.mjs";
-export function createIframeUi(ctx, options) {
-  const wrapper = document.createElement("div");
-  const iframe = document.createElement("iframe");
-  iframe.src = browser.runtime.getURL(options.page);
-  wrapper.appendChild(iframe);
-  let mounted = void 0;
-  const mount = () => {
-    applyPosition(wrapper, iframe, options);
-    mountUi(wrapper, options);
-    mounted = options.onMount?.(wrapper, iframe);
-  };
-  const remove = () => {
-    options.onRemove?.(mounted);
-    wrapper.remove();
-    mounted = void 0;
-  };
-  const mountFunctions = createMountFunctions({ mount, remove }, options);
-  ctx.onInvalidated(remove);
-  return {
-    get mounted() {
-      return mounted;
-    },
-    iframe,
-    wrapper,
-    ...mountFunctions
-  };
+import { browser } from "wxt/browser";
+
+//#region src/utils/content-script-ui/iframe.ts
+/** @module wxt/utils/content-script-ui/iframe */
+/**
+* Create a content script UI using an iframe.
+*
+* @see https://wxt.dev/guide/essentials/content-scripts.html#iframe
+*/
+function createIframeUi(ctx, options) {
+	const wrapper = document.createElement("div");
+	const iframe = document.createElement("iframe");
+	iframe.src = browser.runtime.getURL(options.page);
+	wrapper.appendChild(iframe);
+	let mounted;
+	const mount = () => {
+		applyPosition(wrapper, iframe, options);
+		options.onBeforeMount?.(wrapper, iframe);
+		mountUi(wrapper, options);
+		mounted = options.onMount?.(wrapper, iframe);
+	};
+	const remove = () => {
+		options.onRemove?.(mounted);
+		wrapper.remove();
+		mounted = void 0;
+	};
+	const mountFunctions = createMountFunctions({
+		mount,
+		remove
+	}, options);
+	ctx.onInvalidated(remove);
+	return {
+		get mounted() {
+			return mounted;
+		},
+		iframe,
+		wrapper,
+		...mountFunctions
+	};
 }
+
+//#endregion
+export { createIframeUi };