feat: Make injectScript return the created script element

It can be used to e.g. send messages to the script in the form of custom
events. The script can add an event listener for them via
`document.currentScript`.

Author: ion1

docs/guide/essentials/content-scripts.md

@@ -614,6 +614,37 @@ export default defineUnlistedScript(() => {
 });
 ```
 
+`injectScript` returns the created script element. It can be used to e.g. send messages to the script in the form of custom events. The script can add an event listener for them via `document.currentScript`. An example:
+
+```ts
+// entrypoints/example.content.ts
+export default defineContentScript({
+  matches: ['*://*/*'],
+  async main() {
+    const { script } = await injectScript('/example-main-world.js');
+
+    script.dispatchEvent(
+      new CustomEvent('greeting', {
+        detail: 'Hello there',
+      }),
+    );
+  },
+});
+```
+
+```ts
+// entrypoints/example-main-world.ts
+export default defineUnlistedScript(() => {
+  const script = document.currentScript;
+
+  script?.addEventListener('greeting', (event) => {
+    if (event instanceof CustomEvent) {
+      console.log(event.detail);
+    }
+  });
+});
+```
+
 ## Mounting UI to dynamic element
 
 In many cases, you may need to mount a UI to a DOM element that does not exist at the time the web page is initially loaded. To handle this, use the `autoMount` API to automatically mount the UI when the target element appears dynamically and unmount it when the element disappears. In WXT, the `anchor` option is used to target the element, enabling automatic mounting and unmounting based on its appearance and removal.

packages/wxt/src/utils/inject-script.ts

@@ -15,11 +15,13 @@ export type ScriptPublicPath = Extract<
  *
  * Make sure to add the injected script to your manifest's
  * `web_accessible_resources`.
+ *
+ * @returns A result object containing the created script element.
  */
 export async function injectScript(
   path: ScriptPublicPath,
   options?: InjectScriptOptions,
-): Promise<void> {
+): Promise<InjectScriptResult> {
   // @ts-expect-error: getURL is defined per-project, but not inside the package
   const url = browser.runtime.getURL(path);
   const script = document.createElement('script');
@@ -43,6 +45,10 @@ export async function injectScript(
   }
 
   await loadedPromise;
+
+  return {
+    script,
+  };
 }
 
 function makeLoadedPromise(script: HTMLScriptElement): Promise<void> {
@@ -82,3 +88,12 @@ export interface InjectScriptOptions {
    */
   modifyScript?: (script: HTMLScriptElement) => Promise<void> | void;
 }
+
+export interface InjectScriptResult {
+  /**
+   * The created script element. It can be used to e.g. send messages to the
+   * script in the form of custom events. The script can add an event listener
+   * for them via `document.currentScript`.
+   */
+  script: HTMLScriptElement;
+}