feat: Add waitUntilLoaded to injectScript

Author: ion1

docs/guide/essentials/content-scripts.md

@@ -583,7 +583,13 @@ export default defineConfig({
 
 `injectScript` works by creating a `script` element on the page pointing to your script. This loads the script into the page's context so it runs in the main world.
 
-`injectScript` returns a promise, that when resolved, means the script has been evaluated by the browser and you can start communicating with it.
+`injectScript` returns a promise, that when resolved, means the `script` element has been added to the DOM. To additionally wait until the script has been evaluated by the browser and you can start communicating with it, set `waitUntilLoaded: true` in the options.
+
+```ts
+await injectScript('/example-main-world.js', {
+  waitUntilLoaded: true,
+});
+```
 
 :::warning Warning: `run_at` Caveat
 For MV3, `injectScript` is synchronous and the injected script will be evaluated at the same time as your the content script's `run_at`.

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

@@ -32,13 +32,27 @@ export async function injectScript(
     script.src = url;
   }
 
+  let loadedPromise: Promise<void> | undefined = undefined;
+  if (options?.waitUntilLoaded) {
+    loadedPromise = new Promise((resolve, reject) => {
+      script.onload = () => {
+        resolve();
+      };
+      script.onerror = () => {
+        reject(new Error(`Failed to load script: ${script.src}`));
+      };
+    });
+  }
+
   await options?.manipulateScript?.(script);
 
   (document.head ?? document.documentElement).append(script);
 
   if (!options?.keepInDom) {
     script.remove();
   }
+
+  await loadedPromise;
 }
 
 export interface InjectScriptOptions {
@@ -47,6 +61,12 @@ export interface InjectScriptOptions {
    * injected. To disable this behavior, set this flag to true.
    */
   keepInDom?: boolean;
+  /**
+   * By default, `injectScript` returns as soon as the `script` element has been
+   * added to the DOM. To additionally wait until the browser has loaded (or
+   * failed to load) the script, set this flag to true.
+   */
+  waitUntilLoaded?: boolean;
   /**
    * Manipulate the script element just before it is added to the DOM.
    *