Make DebugKit toolbar robust with JS frameworks like HTMX, Boost

josbeir · josbeir · commit 2ed4ce691b22 · 2025-09-13T14:58:16.000+02:00
- Persist toolbar iframe across body swaps using a MutationObserver on &lt;body&gt;
- Update iframe src with latest X-DEBUGKIT-ID from AJAX responses
- Prevent duplicate message event listeners and double XHR proxying
- Streamline injection logic for efficiency and reliability
diff --git a/webroot/js/inject-iframe.js b/webroot/js/inject-iframe.js
@@ -34,13 +34,20 @@ if (elem) {
     }
   };
 
-  const onReady = () => {
+  let observer;
+
+  function injectDebugKitIframe() {
     if (!win.debugKitId) {
       return;
     }
+
     const { body } = doc;
 
-    // Cannot use css text, because of CSP compatibility.
+    // Remove the old iframe if it exists (in case of ajax swaps).
+    if (iframe && iframe.parentNode) {
+      iframe.parentNode.removeChild(iframe);
+    }
+
     iframe = doc.createElement('iframe');
     iframe.style.position = 'fixed';
     iframe.style.bottom = 0;
@@ -51,24 +58,42 @@ if (elem) {
     iframe.style.zIndex = 99999;
     iframe.height = 40;
     iframe.width = 40;
-    iframe.src = `${window.debugKitBaseUrl}debug-kit/toolbar/${window.debugKitId}`;
-
+    iframe.src = `${window.debugKitBaseUrl}debug-kit/toolbar/${window.debugKitId}`;;
     body.appendChild(iframe);
     bodyOverflow = body.style.overflow;
+    if (!win.debugKitMessageListenerApplied) {
+      window.addEventListener('message', onMessage, false);
+      win.debugKitMessageListenerApplied = true;
+    }
+  }
 
-    window.addEventListener('message', onMessage, false);
+  const onReady = () => {
+    injectDebugKitIframe();
+    if (!observer) {
+      observer = new MutationObserver(() => {
+        if (!doc.body.querySelector('iframe[src*="debug-kit/toolbar/"]')) {
+          injectDebugKitIframe();
+        }
+      });
+      if (doc.body) {
+        observer.observe(doc.body, { childList: true });
+      }
+    }
   };
 
   const logAjaxRequest = (original) => function ajaxRequest() {
     if (this.readyState === 4 && this.getResponseHeader('X-DEBUGKIT-ID')) {
+      const newId = this.getResponseHeader('X-DEBUGKIT-ID');
+      window.debugKitId = newId;
       const params = {
-        requestId: this.getResponseHeader('X-DEBUGKIT-ID'),
+        requestId: newId,
         status: this.status,
         date: new Date(),
         method: this._arguments && this._arguments[0],
         url: this._arguments && this._arguments[1],
         type: this.getResponseHeader('Content-Type'),
       };
+
       iframe.contentWindow.postMessage(`ajax-completed$$${JSON.stringify(params)}`, window.location.origin);
     }
     if (original) {
@@ -78,32 +103,48 @@ if (elem) {
   };
 
   const proxyAjaxOpen = () => {
+    if (window.XMLHttpRequest.prototype._debugKitOpenProxied) {
+      return;
+    }
     const proxied = window.XMLHttpRequest.prototype.open;
     window.XMLHttpRequest.prototype.open = function ajaxCall(...args) {
       this._arguments = args;
       return proxied.apply(this, [].slice.call(args));
     };
+    window.XMLHttpRequest.prototype._debugKitOpenProxied = true;
   };
 
   const proxyAjaxSend = () => {
+    if (window.XMLHttpRequest.prototype._debugKitSendProxied) {
+      return;
+    }
     const proxied = window.XMLHttpRequest.prototype.send;
     window.XMLHttpRequest.prototype.send = function ajaxCall(...args) {
       this.onreadystatechange = logAjaxRequest(this.onreadystatechange);
       return proxied.apply(this, [].slice.call(args));
     };
+    window.XMLHttpRequest.prototype._debugKitSendProxied = true;
   };
 
   // Bind on ready callbacks to DOMContentLoaded (native js)
   // Since the body is already loaded (DOMContentLoaded), the event is not triggered.
   if (doc.addEventListener) {
     // This ensures that all event listeners get applied only once.
     if (!win.debugKitListenersApplied) {
-      // Add support for turbo DOMContentLoaded alternative
-      // see https://turbo.hotwired.dev/reference/events#turbo%3Aload
-      const loadedEvent = typeof Turbo !== 'undefined' && Turbo !== null ? 'turbo:load' : 'DOMContentLoaded';
-      doc.addEventListener(loadedEvent, onReady, false);
-      doc.addEventListener(loadedEvent, proxyAjaxOpen, false);
-      doc.addEventListener(loadedEvent, proxyAjaxSend, false);
+      doc.addEventListener('DOMContentLoaded', onReady, false);
+      if (!win.debugKitAjaxProxied) {
+        doc.addEventListener('DOMContentLoaded', proxyAjaxOpen, false);
+        doc.addEventListener('DOMContentLoaded', proxyAjaxSend, false);
+        if (doc.readyState === 'interactive' || doc.readyState === 'complete') {
+          proxyAjaxOpen();
+          proxyAjaxSend();
+        }
+        win.debugKitAjaxProxied = true;
+      }
+      doc.addEventListener('DOMContentLoaded', onReady, false);
+      if (doc.readyState === 'interactive' || doc.readyState === 'complete') {
+        onReady();
+      }
       win.debugKitListenersApplied = true;
     }
   } else {
