From 6c384823d8137582fb9a0703fff284acf526213e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Ahlert?= <andre@aex.partners>
Date: Thu, 9 Apr 2026 14:52:03 -0300
Subject: [PATCH] defer external script parsing until after DOMContentLoaded
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #533. External behavior files loaded via
<script type="text/hyperscript" src="..."> were being parsed before
plugins like hdb.js could register their commands, causing
"Unexpected Token: breakpoint" errors.

The fix separates fetch from parse: external files are still fetched
immediately for performance, but parsing is deferred until after
ready() fires, giving synchronous plugin scripts time to register.

Signed-off-by: André Ahlert <andre@aex.partners>
---
 src/_hyperscript.js        | 31 +++++++++++++++++++--------
 test/core/pluginLoading.js | 43 ++++++++++++++++++++++++++++++++++++++
 test/index.html            |  1 +
 3 files changed, 66 insertions(+), 9 deletions(-)
 create mode 100644 test/core/pluginLoading.js

diff --git a/src/_hyperscript.js b/src/_hyperscript.js
index c55c50ce7..91e8d6941 100644
--- a/src/_hyperscript.js
+++ b/src/_hyperscript.js
@@ -7628,31 +7628,44 @@
     function browserInit() {
         /** @type {HTMLScriptElement[]} */
         var scripts = Array.from(globalScope.document.querySelectorAll("script[type='text/hyperscript'][src]"))
-        Promise.all(
+
+        // Fetch external .hs files immediately so network latency overlaps
+        // with DOMContentLoaded. Parsing is deferred until after ready() so
+        // that plugins loaded via synchronous <script> tags (e.g. hdb.js)
+        // have a chance to register their commands before behavior files
+        // are evaluated. See https://github.com/bigskysoftware/_hyperscript/issues/533
+        var fetchedScripts = Promise.all(
             scripts.map(function (script) {
                 return fetch(script.src)
                     .then(function (res) {
                         return res.text();
                     });
             })
-        )
-        .then(script_values => script_values.forEach(sc => _hyperscript(sc)))
-        .then(() => ready(function () {
-            mergeMetaConfig();
-            runtime_.processNode(document.documentElement);
+        );
 
-            document.dispatchEvent(new Event("hyperscript:ready"));
+        ready(function () {
+            mergeMetaConfig();
 
+            // Register htmx:load listener immediately so dynamic swaps that
+            // occur while external .hs files are still being fetched are not missed.
             globalScope.document.addEventListener("htmx:load", function (/** @type {CustomEvent} */ evt) {
                 runtime_.processNode(evt.detail.elt);
             });
-        }));
+
+            fetchedScripts.then(function (script_values) {
+                script_values.forEach(function (sc) { _hyperscript(sc); });
+
+                runtime_.processNode(document.documentElement);
+
+                document.dispatchEvent(new Event("hyperscript:ready"));
+            });
+        });
 
         function ready(fn) {
             if (document.readyState !== "loading") {
                 setTimeout(fn);
             } else {
-                document.addEventListener("DOMContentLoaded", fn);
+                document.addEventListener("DOMContentLoaded", fn, { once: true });
             }
         }
 
diff --git a/test/core/pluginLoading.js b/test/core/pluginLoading.js
new file mode 100644
index 000000000..8c7abf683
--- /dev/null
+++ b/test/core/pluginLoading.js
@@ -0,0 +1,43 @@
+describe("plugin loading order", function () {
+
+    it("a command registered via addCommand is available to subsequently parsed scripts", function () {
+        var executed = false;
+
+        _hyperscript.addCommand("__testplugincmd", function (parser, runtime, tokens) {
+            if (!tokens.matchToken("__testplugincmd")) return;
+            return {
+                op: function (ctx) {
+                    executed = true;
+                    return runtime.findNext(this, ctx);
+                }
+            };
+        });
+
+        // Parse and execute a script that uses the plugin command directly.
+        _hyperscript("__testplugincmd");
+        executed.should.equal(true);
+    });
+
+    it("a feature registered via addFeature is available to subsequently parsed scripts", function () {
+        var installed = false;
+
+        _hyperscript.addFeature("__testpluginfeature", function (parser, runtime, tokens) {
+            if (!tokens.matchToken("__testpluginfeature")) return;
+            var name = tokens.requireTokenType("IDENTIFIER").value;
+            return {
+                install: function (target, source) {
+                    installed = true;
+                }
+            };
+        });
+
+        _hyperscript("__testpluginfeature myFeature");
+        installed.should.equal(true);
+    });
+
+    it("parsing a script with an unregistered command throws a parse error", function () {
+        var error = getParseErrorFor("on click __nonexistentcmd");
+        error.should.not.equal("");
+    });
+
+});
diff --git a/test/index.html b/test/index.html
index 254d88431..317c409fe 100644
--- a/test/index.html
+++ b/test/index.html
@@ -60,6 +60,7 @@ <h2>Mocha Test Suite</h2>
 		<script src="core/runtimeErrors.js"></script>
 		<script src="core/security.js"></script>
 		<script src="core/scoping.js"></script>
+		<script src="core/pluginLoading.js"></script>
 
 		<!-- features -->
 		<script src="features/on.js"></script>