From 331661bbe9bdd39df0df78e593139eab2f99adc6 Mon Sep 17 00:00:00 2001
From: Lucio Paiva <luciopaiva@gmail.com>
Date: Mon, 15 Sep 2025 23:56:22 +0100
Subject: [PATCH] WIP

---
 CHANGELOG.md                       |  4 ++++
 chrome-extension/background.js     | 16 +++++++++++-----
 chrome-extension/content-script.js |  2 ++
 chrome-extension/manifest.json     |  9 +++++++++
 docs/src/content/docs/faq.mdx      | 16 ++++++++++++----
 5 files changed, 38 insertions(+), 9 deletions(-)
 create mode 100644 chrome-extension/content-script.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e2825be..cd6a03d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,8 @@
 
+# 3.3.0
+
+- use content scripts to inject scripts at `document_start`
+
 # 3.2.0
 
 - prefer `userScripts` over `scripting` (#71)
diff --git a/chrome-extension/background.js b/chrome-extension/background.js
index b7a5d1f..74f667e 100644
--- a/chrome-extension/background.js
+++ b/chrome-extension/background.js
@@ -13,11 +13,17 @@ browser.api.onSuspend(async () => {
     console.info("Extension suspended");
     analytics.event.suspended();
 });
-browser.api.onCommitted(async details => {
-    const { url, tabId, frameId } = details;
-    const metrics = await loader.loadScripts(url, tabId, frameId);
-    metrics.hasData && analytics.event.scriptsLoaded(metrics);
-    await storage.evictStale();
+
+chrome.runtime.onMessage.addListener(async (message, sender) => {
+    const url = message.href;
+    const tabId = sender.tab?.id;
+    const frameId = sender.frameId;
+
+    if (typeof url === "string" && typeof tabId === "number" && typeof frameId === "number") {
+        const metrics = await loader.loadScripts(url, tabId, frameId);
+        metrics.hasData && analytics.event.scriptsLoaded(metrics);
+        await storage.evictStale();
+    }
 });
 
 icon.initialize().then();
diff --git a/chrome-extension/content-script.js b/chrome-extension/content-script.js
new file mode 100644
index 0000000..78b2244
--- /dev/null
+++ b/chrome-extension/content-script.js
@@ -0,0 +1,2 @@
+
+chrome.runtime.sendMessage(location);
diff --git a/chrome-extension/manifest.json b/chrome-extension/manifest.json
index ceca9ae..3cc0266 100644
--- a/chrome-extension/manifest.json
+++ b/chrome-extension/manifest.json
@@ -22,6 +22,15 @@
     "default_title": "Witchcraft",
     "default_popup": "popup/popup.html"
   },
+  "content_scripts": [
+    {
+      "world": "ISOLATED",
+      "all_frames": true,
+      "run_at": "document_start",
+      "matches": ["<all_urls>"],
+      "js": ["content-script.js"]
+    }
+  ],
   "background": {
     "service_worker": "background.js",
     "type": "module"
diff --git a/docs/src/content/docs/faq.mdx b/docs/src/content/docs/faq.mdx
index ad8f174..4a2a5ec 100644
--- a/docs/src/content/docs/faq.mdx
+++ b/docs/src/content/docs/faq.mdx
@@ -2,7 +2,6 @@
 title: FAQ
 ---
 
-import { Badge } from '@astrojs/starlight/components';
 import { Aside } from '@astrojs/starlight/components';
 import { Code } from '@astrojs/starlight/components';
 
@@ -36,9 +35,18 @@ Unfortunately, no. See question above.
 
 ## When exactly my script gets loaded?
 
-As of v3.0, it is loaded when the <a href="https://developer.chrome.com/docs/extensions/reference/api/webNavigation#event-onCommitted">chrome.webNavigation.onCommitted</a> event is fired. The method <a href="https://developer.chrome.com/docs/extensions/reference/api/scripting#method-executeScript">chrome.scripting.executeScript</a> is then called to inject the JavaScript file into the current page with the option `injectImmediately` set.
-
-This means that the script is expected to be injected in the page before the <a href="https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded"><span class="code">DOMContentLoaded</span></a> event is fired. Unfortunately, tests show that this is not the case. Your script should not rely on being injected before that event.
+As of v3.3.0, it is loaded at `document_start` via a content script. This is the earliest moment you can inject a script into a page. At this point, the DOM is not fully built yet, so your script should not rely on DOM elements being present. If you need to wait for the DOM to be ready, you can listen for the `DOMContentLoaded` event inside your script, but first check `document.readyState` to see if the event has already fired:
+
+```js
+if (document.readyState === 'loading') {
+    // DOM is still loading, so let's wait for it
+    document.addEventListener('DOMContentLoaded', () => {
+        // DOM is ready now
+    });
+} else {
+    // DOM is already ready
+}
+```
 
 ## My script seems to be loading multiple times. What is wrong?