Make DebugKit toolbar robust with JS frameworks like HTMX, Boost

josbeir · josbeir · commit 09e4234d1f05 · 2025-09-13T17:27:08.000+02:00
- Persist toolbar iframe across body by placing it in a shadowRoot element instead of &lt;body&gt;
- Streamline injection logic for efficiency and reliability
- Handle potential error by logging it to the console
diff --git a/webroot/js/inject-iframe.js b/webroot/js/inject-iframe.js
@@ -7,40 +7,46 @@ if (elem) {
 
 ((win, doc) => {
   let iframe;
-  let bodyOverflow;
+  let shadowHost;
+  let shadowRoot;
 
   const onMessage = (event) => {
+    if (!iframe) return;
     if (event.data === 'collapse') {
       iframe.height = 40;
       iframe.width = 40;
-      doc.body.style.overflow = bodyOverflow;
       return;
     }
     if (event.data === 'toolbar') {
       iframe.height = 40;
       iframe.width = '100%';
-      doc.body.style.overflow = bodyOverflow;
       return;
     }
     if (event.data === 'expand') {
       iframe.width = '100%';
       iframe.height = '100%';
-      doc.body.style.overflow = 'hidden';
     }
     if (event.data === 'error') {
       iframe.width = '40%';
       iframe.height = '40%';
-      doc.body.style.overflow = bodyOverflow;
     }
   };
 
-  const onReady = () => {
+  function injectDebugKitIframe() {
     if (!win.debugKitId) {
       return;
     }
-    const { body } = doc;
 
-    // Cannot use css text, because of CSP compatibility.
+    if (!shadowHost) {
+      shadowHost = doc.getElementById('debugkit-shadow-host');
+      if (!shadowHost) {
+        shadowHost = doc.createElement('div');
+        shadowHost.id = 'debugkit-shadow-host';
+        doc.documentElement.appendChild(shadowHost);
+      }
+      shadowRoot = shadowHost.shadowRoot || shadowHost.attachShadow({ mode: 'open' });
+    }
+
     iframe = doc.createElement('iframe');
     iframe.style.position = 'fixed';
     iframe.style.bottom = 0;
@@ -52,12 +58,10 @@ if (elem) {
     iframe.height = 40;
     iframe.width = 40;
     iframe.src = `${window.debugKitBaseUrl}debug-kit/toolbar/${window.debugKitId}`;
-
-    body.appendChild(iframe);
-    bodyOverflow = body.style.overflow;
+    shadowRoot.appendChild(iframe);
 
     window.addEventListener('message', onMessage, false);
-  };
+  }
 
   const logAjaxRequest = (original) => function ajaxRequest() {
     if (this.readyState === 4 && this.getResponseHeader('X-DEBUGKIT-ID')) {
@@ -69,7 +73,13 @@ if (elem) {
         url: this._arguments && this._arguments[1],
         type: this.getResponseHeader('Content-Type'),
       };
-      iframe.contentWindow.postMessage(`ajax-completed$$${JSON.stringify(params)}`, window.location.origin);
+
+      if (iframe && iframe.contentWindow) {
+        iframe.contentWindow.postMessage(`ajax-completed$$${JSON.stringify(params)}`, window.location.origin);
+      }
+      else {
+        console.warn('DebugKit iframe not found.');
+      }
     }
     if (original) {
       return original.apply(this, [].slice.call(arguments));
@@ -93,21 +103,26 @@ if (elem) {
     };
   };
 
-  // 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);
-      win.debugKitListenersApplied = true;
+  let listenersSetup = false;
+  function setupDebugKitListeners() {
+    if (listenersSetup) return;
+    // Set up AJAX proxying
+    proxyAjaxOpen();
+    proxyAjaxSend();
+
+    // Set up ready handler
+    if (doc.readyState === 'loading') {
+      doc.addEventListener('DOMContentLoaded', injectDebugKitIframe, false);
+    } else {
+      injectDebugKitIframe();
     }
+    listenersSetup = true;
+  }
+
+  if (doc.addEventListener) {
+    setupDebugKitListeners();
   } else {
     throw new Error('Unable to add event listener for DebugKit. Please use a browser'
-            + ' that supports addEventListener().');
+      + ' that supports addEventListener().');
   }
 })(window, document);
