html-bundle 6.4.0 → 6.5.0

package/README.md

@@ -46,9 +46,10 @@ $ npm run build
 ## CLI
 
 `--hmr`: boots up a static server and enables Hot Module Replacement. See [HMR](#hmr) for what is hot-patched in place versus reloaded.<br>
-`--secure`: creates a secure HTTP2 over HTTPS instance. This requires the files `localhost.pem` and `localhost-key.pem` in the root folder. You can generate them with [mkcert](https://github.com/FiloSottile/mkcert) for instance.<br>
+`--secure`: creates a secure HTTP2 over HTTPS instance. Plain HTTP requests to the same host and port redirect to HTTPS. This requires the files `localhost.pem` and `localhost-key.pem` in the root folder. You can generate them with [mkcert](https://github.com/FiloSottile/mkcert) for instance.<br>
 `--isCritical`: uses critical to extract and inline critical-path CSS to HTML.<br>
-`--handler`: path to your custom handler. Here, you can handle all non-supported files. You can get the filename via `process.argv[2]`.
+`--handler`: path to your custom handler. Here, you can handle all non-supported files. You can get the filename via `process.argv[2]`.<br>
+`--handlerConcurrency`: maximum number of handler processes running at once. Defaults to the available CPU count. For image-heavy handlers such as Sharp resizing, try 2, 4, 8, and the default value, then keep the fastest value that does not spike memory.
 
 ## HMR
 
@@ -112,6 +113,7 @@ Example:
 export default {
   secure: true,
   handler: "utils/staticFiles.js",
+  handlerConcurrency: 4,
   esbuild: {
     external: ["images"],
   },

package/dist/bundle.d.mts

@@ -17,6 +17,8 @@ export type Config = {
     isCritical?: boolean;
     hmr?: boolean;
     handler?: string;
+    handlerConcurrency?: number;
+    maxHandlerConcurrency?: number;
     host?: string;
     key?: Buffer;
     cert?: Buffer;

package/dist/bundle.mjs

@@ -4,9 +4,11 @@ import { readFile, rm, writeFile, readdir, lstat } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { sep } from "path";
+import { availableParallelism } from "os";
 import { glob } from "glob";
 import postcss from "postcss";
 import esbuild from "esbuild";
+import pLimit from "p-limit";
 import Beasties from "beasties";
 import { minify } from "html-minifier-terser";
 import { watch } from "chokidar";
@@ -25,6 +27,9 @@ const isSecure = process.argv.includes("--secure") || bundleConfig.secure; // us
 const handlerFile = process.argv.includes("--handler")
     ? process.argv[process.argv.indexOf("--handler") + 1]
     : bundleConfig.handler;
+const defaultHandlerConcurrency = availableParallelism();
+const handlerConcurrency = getHandlerConcurrency();
+const limitHandler = pLimit(handlerConcurrency);
 process.env.NODE_ENV = isHMR ? "development" : "production"; // just in case other tools are using it
 let timer = performance.now();
 let { plugins, options, file: postcssFile } = await getPostCSSConfig();
@@ -43,20 +48,19 @@ async function cleanupStaleInlineBundleFiles() {
     await Promise.all(staleFiles.map((file) => rm(file.replaceAll(sep, "/"), { force: true })));
 }
 async function build(files, firstRun = true) {
+    const handlerTasks = [];
     for (const file of files) {
         if (INLINE_BUNDLE_FILE.test(file)) {
             continue;
         }
         await createDir(file);
         if (!SUPPORTED_FILES.test(file)) {
+            if ((await lstat(file)).isDirectory())
+                continue;
             if (handlerFile) {
-                execFilePromise("node", [handlerFile, file]).then(({ stdout }) => {
-                    console.log("📋 Logging Handler: ", String(stdout));
-                });
+                handlerTasks.push(limitHandler(() => runHandler(file)));
             }
             else {
-                if ((await lstat(file)).isDirectory())
-                    continue;
                 await fileCopy(file);
             }
         }
@@ -84,6 +88,7 @@ async function build(files, firstRun = true) {
             await minifyHTML(file, getBuildPath(file));
         }
     }
+    await Promise.all(handlerTasks);
     console.log(`🚀 Build finished in ${(performance.now() - timer).toFixed(2)}ms ✨`);
     if (isHMR && firstRun) {
         const [dynamicRouter, server] = await createDefaultServer(isSecure);
@@ -215,11 +220,7 @@ async function build(files, firstRun = true) {
             else {
                 if (handlerFile) {
                     try {
-                        const { stdout } = await execFilePromise("node", [
-                            handlerFile,
-                            file,
-                        ]);
-                        console.log("📋 Logging Handler: ", String(stdout));
+                        await limitHandler(() => runHandler(file));
                     }
                     catch (err) {
                         console.error(err);
@@ -233,6 +234,30 @@ async function build(files, firstRun = true) {
         }
     }
 }
+function getHandlerConcurrency() {
+    const value = getArgValue("--handlerConcurrency") ??
+        getArgValue("--maxHandlerConcurrency") ??
+        bundleConfig.handlerConcurrency ??
+        bundleConfig.maxHandlerConcurrency ??
+        defaultHandlerConcurrency;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        return defaultHandlerConcurrency;
+    }
+    return parsed;
+}
+function getArgValue(name) {
+    const index = process.argv.indexOf(name);
+    return index === -1 ? undefined : process.argv[index + 1];
+}
+async function runHandler(file) {
+    if (!handlerFile)
+        return;
+    const { stdout } = await execFilePromise("node", [handlerFile, file]);
+    const output = String(stdout).trim();
+    if (output)
+        console.log("📋 Logging Handler: ", output);
+}
 async function minifyCSS(file, buildFile) {
     try {
         const fileText = await readFile(file, { encoding: "utf-8" });

package/dist/hmr-client.js

@@ -20,7 +20,27 @@ const ID = "__HMR_ID__";
 const SRC = "__HMR_SRC__";
 const REGION = '[data-hmr="__HMR_ID__"]';
 const CLIENT = 'script[data-hmr-client="__HMR_ID__"]';
-window.isHMR = true;
+// The client is injected as the first <head> module so its hub and public API
+// exist before the page's own scripts run. But `window.isHMR` must NOT be
+// observable while those scripts execute for the first time: user code commonly
+// branches on it to run one-time setup exactly once (e.g.
+// `if (!window.isHMR) createRouter()`), relying on the flag being false on the
+// pristine load and true on every hot re-run afterwards. Assigning it eagerly
+// here runs before the page scripts and breaks that contract, leaving one-time
+// init skipped (e.g. an SPA router never mounts, so its outlet stays empty).
+// Flag it only after the initial module scripts have executed:
+//   - initial load: readyState is "interactive"; set it on DOMContentLoaded,
+//     which fires after the page's own deferred/module scripts.
+//   - hot re-render / composed page registered post-load: readyState is
+//     "complete"; set it immediately, since we are already past the first load.
+if (document.readyState === "complete") {
+    window.isHMR = true;
+}
+else {
+    document.addEventListener("DOMContentLoaded", () => (window.isHMR = true), {
+        once: true,
+    });
+}
 // One hub per browsing context, created by whichever page loads first. Every
 // composed sub-page (index.html + fetched fragments) registers into it and stays
 // live, so a single shared EventSource dispatches every file's changes to the
@@ -55,39 +75,55 @@ function patch(message) {
         }
     }
     else {
-        patchFragment(message.html);
+        patchFragment(message);
     }
     window.scrollTo(0, previousScroll);
 }
-function patchFragment(htmlText) {
-    const incoming = parseHTML(htmlText);
+function patchFragment(message) {
+    const incoming = parseHTML(message.html);
     // hydro-js returns a DocumentFragment for multi-root markup but the element
     // itself for a single root — normalise to a flat list of top-level nodes.
-    const nextNodes = incoming.nodeType === Node.DOCUMENT_FRAGMENT_NODE ||
-        incoming.nodeType === Node.DOCUMENT_NODE
-        ? Array.from(incoming.childNodes)
-        : [incoming];
+    const nextNodes = topLevelNodes(incoming);
     const regions = Array.from(document.querySelectorAll(REGION));
+    if (!regions.length) {
+        hub.lastHTML.set(FILE, message.html);
+        return;
+    }
+    const previousText = message.previousHtml || hub.lastHTML.get(FILE);
+    const previousNodes = previousText
+        ? topLevelNodes(parseHTML(previousText))
+        : [];
     // Replace each existing region in place, drop the surplus, append the rest.
     regions.forEach((where, index) => {
         if (index < nextNodes.length) {
-            render(nextNodes[index], where, false);
+            const previousNode = previousNodes[index];
+            const nextNode = nextNodes[index];
+            if (previousNode && sameNodeIdentity(previousNode, nextNode)) {
+                patchNode(previousNode, nextNode, where);
+            }
+            else {
+                render(cloneForRender(nextNode), where, false);
+            }
         }
         else {
             where.remove();
         }
     });
     for (let rest = regions.length; rest < nextNodes.length; rest++) {
-        if (regions.length) {
-            const template = document.createElement("template");
-            nextNodes[regions.length - 1].after(template);
-            render(nextNodes[rest], template, false);
-            template.remove();
-        }
-        else {
-            render(nextNodes[rest], false, false);
-        }
+        const template = document.createElement("template");
+        const regionList = Array.from(document.querySelectorAll(REGION));
+        const lastRegion = regionList[regionList.length - 1];
+        lastRegion.after(template);
+        render(cloneForRender(nextNodes[rest]), template, false);
+        template.remove();
     }
+    hub.lastHTML.set(FILE, message.html);
+}
+function topLevelNodes(parsed) {
+    return parsed.nodeType === Node.DOCUMENT_FRAGMENT_NODE ||
+        parsed.nodeType === Node.DOCUMENT_NODE
+        ? Array.from(parsed.childNodes)
+        : [parsed];
 }
 function isFullDocument(htmlText) {
     const trimmed = htmlText.trimStart().toLowerCase();

package/dist/utils.d.mts

@@ -1,7 +1,7 @@
 import type { Config } from "./bundle.mjs";
 import type { Router } from "express-serve-static-core";
 import { type Server } from "http";
-import { type Server as HTTPSServer } from "https";
+import type { Server as HTTPSServer } from "https";
 import postcssrc from "postcss-load-config";
 import cssnano from "cssnano";
 import { parse, parseFragment } from "parse5";

package/dist/utils.mjs

@@ -1,8 +1,8 @@
 import { copyFile, mkdir, readFile } from "fs/promises";
 import path from "path";
 import http from "http";
-import https from "https";
 import express from "express";
+import httpolyglot from "httpolyglot";
 import postcssrc from "postcss-load-config";
 import cssnano from "cssnano";
 import { parse, parseFragment, serialize } from "parse5";
@@ -35,6 +35,17 @@ export let serverSentEvents;
 export async function createDefaultServer(isSecure) {
     const router = express.Router();
     const app = express();
+    if (isSecure) {
+        app.use((req, res, next) => {
+            const socket = req.socket;
+            if (socket.encrypted) {
+                next();
+                return;
+            }
+            const host = req.headers.host || getDefaultHost();
+            res.redirect(307, `https://${host}${req.originalUrl || req.url}`);
+        });
+    }
     app.use(router);
     app.use(express.static(path.join(process.cwd(), bundleConfig.build)));
     router.get("/hmr", (req, reply) => {
@@ -63,18 +74,25 @@ export async function createDefaultServer(isSecure) {
         });
         res.send(file);
     });
+    const secureOptions = isSecure
+        ? {
+            key: bundleConfig.key ||
+                (await readFile(path.join(process.cwd(), "localhost-key.pem"))),
+            cert: bundleConfig.cert ||
+                (await readFile(path.join(process.cwd(), "localhost.pem"))),
+        }
+        : undefined;
     return [
         router,
         isSecure
-            ? https.createServer({
-                key: bundleConfig.key ||
-                    (await readFile(path.join(process.cwd(), "localhost-key.pem"))),
-                cert: bundleConfig.cert ||
-                    (await readFile(path.join(process.cwd(), "localhost.pem"))),
-            }, app)
+            ? httpolyglot.createServer(secureOptions, app)
             : http.createServer({}, app),
     ];
 }
+function getDefaultHost() {
+    const host = bundleConfig.host === "::" ? "localhost" : bundleConfig.host;
+    return `${host}:${bundleConfig.port}`;
+}
 export async function getPostCSSConfig() {
     try {
         return await postcssrc({});
@@ -126,8 +144,7 @@ export function addHMRCode(html, file, ast) {
     if (html.includes("<!DOCTYPE html>") || html.includes("<html")) {
         DOM = ast || parse(html);
         const headNode = findElement(DOM, (e) => getTagName(e) === "head");
-        // Inject first in <head> so the client runs before the page's own scripts.
-        prependChild(headNode, script);
+        insertHeadClient(headNode, script);
     }
     else {
         DOM = ast || parseFragment(html);
@@ -157,3 +174,9 @@ function prependChild(parent, node) {
     node.parentNode = parent;
     parent.childNodes.unshift(node);
 }
+function insertHeadClient(parent, node) {
+    const children = parent.childNodes;
+    const lastBaseIndex = children.findLastIndex((child) => getTagName(child) === "base");
+    node.parentNode = parent;
+    children.splice(lastBaseIndex + 1, 0, node);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundle",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "A very simple bundler for HTML SFC",
   "bin": "./dist/bundle.mjs",
   "main": "./dist/bundle.mjs",
@@ -41,7 +41,7 @@
   },
   "bugs": "https://github.com/Krutsch/html-bundle/issues",
   "dependencies": {
-    "@web/parse5-utils": "^2.1.1",
+    "@web/parse5-utils": "^3.0.0",
     "await-spawn": "^4.0.2",
     "beasties": "^0.4.2",
     "chokidar": "^5.0.0",
@@ -50,8 +50,10 @@
     "express": "^5.2.1",
     "glob": "^13.0.6",
     "html-minifier-terser": "^7.2.0",
+    "httpolyglot": "^0.1.2",
     "hydro-js": "^1.9.0",
     "jiti": "^2.7.0",
+    "p-limit": "^7.3.0",
     "parse5": "^8.0.1",
     "postcss": "^8.5.16",
     "postcss-load-config": "^6.0.1"

package/src/bundle.mts

@@ -8,10 +8,12 @@ import { readFile, rm, writeFile, readdir, lstat } from "fs/promises";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { sep } from "path";
+import { availableParallelism } from "os";
 import { glob } from "glob";
 import postcss from "postcss";
 import express from "express";
 import esbuild, { type BuildOptions } from "esbuild";
+import pLimit from "p-limit";
 import Beasties, { type Options } from "beasties";
 import { minify, type Options as MinifyOptions } from "html-minifier-terser";
 import { watch } from "chokidar";
@@ -41,6 +43,9 @@ const isSecure = process.argv.includes("--secure") || bundleConfig.secure; // us
 const handlerFile = process.argv.includes("--handler")
   ? process.argv[process.argv.indexOf("--handler") + 1]
   : bundleConfig.handler;
+const defaultHandlerConcurrency = availableParallelism();
+const handlerConcurrency = getHandlerConcurrency();
+const limitHandler = pLimit(handlerConcurrency);
 
 process.env.NODE_ENV = isHMR ? "development" : "production"; // just in case other tools are using it
 let timer = performance.now();
@@ -66,6 +71,8 @@ async function cleanupStaleInlineBundleFiles() {
 }
 
 async function build(files: string[], firstRun = true) {
+  const handlerTasks: Promise<void>[] = [];
+
   for (const file of files) {
     if (INLINE_BUNDLE_FILE.test(file)) {
       continue;
@@ -74,12 +81,11 @@ async function build(files: string[], firstRun = true) {
     await createDir(file);
 
     if (!SUPPORTED_FILES.test(file)) {
+      if ((await lstat(file)).isDirectory()) continue;
+
       if (handlerFile) {
-        execFilePromise("node", [handlerFile, file]).then(({ stdout }) => {
-          console.log("📋 Logging Handler: ", String(stdout));
-        });
+        handlerTasks.push(limitHandler(() => runHandler(file)));
       } else {
-        if ((await lstat(file)).isDirectory()) continue;
         await fileCopy(file);
       }
     } else {
@@ -104,6 +110,7 @@ async function build(files: string[], firstRun = true) {
       await minifyHTML(file, getBuildPath(file));
     }
   }
+  await Promise.all(handlerTasks);
 
   console.log(
     `🚀 Build finished in ${(performance.now() - timer).toFixed(2)}ms ✨`,
@@ -262,11 +269,7 @@ async function build(files: string[], firstRun = true) {
       } else {
         if (handlerFile) {
           try {
-            const { stdout } = await execFilePromise("node", [
-              handlerFile,
-              file,
-            ]);
-            console.log("📋 Logging Handler: ", String(stdout));
+            await limitHandler(() => runHandler(file));
           } catch (err) {
             console.error(err);
           }
@@ -279,6 +282,35 @@ async function build(files: string[], firstRun = true) {
   }
 }
 
+function getHandlerConcurrency() {
+  const value =
+    getArgValue("--handlerConcurrency") ??
+    getArgValue("--maxHandlerConcurrency") ??
+    bundleConfig.handlerConcurrency ??
+    bundleConfig.maxHandlerConcurrency ??
+    defaultHandlerConcurrency;
+  const parsed = Number(value);
+
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return defaultHandlerConcurrency;
+  }
+
+  return parsed;
+}
+
+function getArgValue(name: string) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? undefined : process.argv[index + 1];
+}
+
+async function runHandler(file: string) {
+  if (!handlerFile) return;
+
+  const { stdout } = await execFilePromise("node", [handlerFile, file]);
+  const output = String(stdout).trim();
+  if (output) console.log("📋 Logging Handler: ", output);
+}
+
 async function minifyCSS(file: string, buildFile: string) {
   try {
     const fileText = await readFile(file, { encoding: "utf-8" });
@@ -521,6 +553,8 @@ export type Config = {
   isCritical?: boolean;
   hmr?: boolean;
   handler?: string;
+  handlerConcurrency?: number;
+  maxHandlerConcurrency?: number;
   host?: string;
   key?: Buffer;
   cert?: Buffer;

package/src/hmr-client.ts

@@ -72,7 +72,26 @@ const SRC = "__HMR_SRC__";
 const REGION = '[data-hmr="__HMR_ID__"]';
 const CLIENT = 'script[data-hmr-client="__HMR_ID__"]';
 
-window.isHMR = true;
+// The client is injected as the first <head> module so its hub and public API
+// exist before the page's own scripts run. But `window.isHMR` must NOT be
+// observable while those scripts execute for the first time: user code commonly
+// branches on it to run one-time setup exactly once (e.g.
+// `if (!window.isHMR) createRouter()`), relying on the flag being false on the
+// pristine load and true on every hot re-run afterwards. Assigning it eagerly
+// here runs before the page scripts and breaks that contract, leaving one-time
+// init skipped (e.g. an SPA router never mounts, so its outlet stays empty).
+// Flag it only after the initial module scripts have executed:
+//   - initial load: readyState is "interactive"; set it on DOMContentLoaded,
+//     which fires after the page's own deferred/module scripts.
+//   - hot re-render / composed page registered post-load: readyState is
+//     "complete"; set it immediately, since we are already past the first load.
+if (document.readyState === "complete") {
+  window.isHMR = true;
+} else {
+  document.addEventListener("DOMContentLoaded", () => (window.isHMR = true), {
+    once: true,
+  });
+}
 
 // One hub per browsing context, created by whichever page loads first. Every
 // composed sub-page (index.html + fetched fragments) registers into it and stays
@@ -111,41 +130,60 @@ function patch(message: HTMLMessage): void {
       dispatchEvent(new Event("popstate"));
     }
   } else {
-    patchFragment(message.html);
+    patchFragment(message);
   }
   window.scrollTo(0, previousScroll);
 }
 
-function patchFragment(htmlText: string): void {
-  const incoming = parseHTML(htmlText);
+function patchFragment(message: HTMLMessage): void {
+  const incoming = parseHTML(message.html);
   // hydro-js returns a DocumentFragment for multi-root markup but the element
   // itself for a single root — normalise to a flat list of top-level nodes.
-  const nextNodes: Node[] =
-    incoming.nodeType === Node.DOCUMENT_FRAGMENT_NODE ||
-    incoming.nodeType === Node.DOCUMENT_NODE
-      ? Array.from(incoming.childNodes)
-      : [incoming];
+  const nextNodes = topLevelNodes(incoming);
   const regions = Array.from(document.querySelectorAll(REGION));
 
+  if (!regions.length) {
+    hub.lastHTML.set(FILE, message.html);
+    return;
+  }
+
+  const previousText = message.previousHtml || hub.lastHTML.get(FILE);
+  const previousNodes = previousText
+    ? topLevelNodes(parseHTML(previousText))
+    : [];
+
   // Replace each existing region in place, drop the surplus, append the rest.
   regions.forEach((where, index) => {
     if (index < nextNodes.length) {
-      render(nextNodes[index], where, false);
+      const previousNode = previousNodes[index];
+      const nextNode = nextNodes[index];
+      if (previousNode && sameNodeIdentity(previousNode, nextNode)) {
+        patchNode(previousNode, nextNode, where);
+      } else {
+        render(cloneForRender(nextNode), where, false);
+      }
     } else {
       where.remove();
     }
   });
 
   for (let rest = regions.length; rest < nextNodes.length; rest++) {
-    if (regions.length) {
-      const template = document.createElement("template");
-      (nextNodes[regions.length - 1] as Element).after(template);
-      render(nextNodes[rest], template, false);
-      template.remove();
-    } else {
-      render(nextNodes[rest], false, false);
-    }
+    const template = document.createElement("template");
+    const regionList = Array.from(document.querySelectorAll(REGION));
+    const lastRegion = regionList[regionList.length - 1];
+    lastRegion.after(template);
+    render(cloneForRender(nextNodes[rest]), template, false);
+    template.remove();
   }
+
+  hub.lastHTML.set(FILE, message.html);
+}
+
+function topLevelNodes(parsed: Element | DocumentFragment | Text): Node[] {
+  return parsed.nodeType === Node.DOCUMENT_FRAGMENT_NODE ||
+    parsed.nodeType === Node.DOCUMENT_NODE
+    ? Array.from(parsed.childNodes)
+    : [parsed];
 }
 
 function isFullDocument(htmlText: string): boolean {

package/src/utils.mts

@@ -4,8 +4,9 @@ import type { Router } from "express-serve-static-core";
 import { copyFile, mkdir, readFile } from "fs/promises";
 import path from "path";
 import http, { type Server } from "http";
-import https, { type Server as HTTPSServer } from "https";
+import type { Server as HTTPSServer } from "https";
 import express from "express";
+import httpolyglot from "httpolyglot";
 import postcssrc from "postcss-load-config";
 import cssnano from "cssnano";
 import { parse, parseFragment, serialize } from "parse5";
@@ -57,6 +58,20 @@ export async function createDefaultServer(
 ): Promise<[Router, Server | HTTPSServer]> {
   const router = express.Router();
   const app = express();
+
+  if (isSecure) {
+    app.use((req, res, next) => {
+      const socket = req.socket as typeof req.socket & { encrypted?: boolean };
+      if (socket.encrypted) {
+        next();
+        return;
+      }
+
+      const host = req.headers.host || getDefaultHost();
+      res.redirect(307, `https://${host}${req.originalUrl || req.url}`);
+    });
+  }
+
   app.use(router);
   app.use(express.static(path.join(process.cwd(), bundleConfig.build)));
 
@@ -94,24 +109,30 @@ export async function createDefaultServer(
     res.send(file);
   });
 
+  const secureOptions = isSecure
+    ? {
+        key:
+          bundleConfig.key ||
+          (await readFile(path.join(process.cwd(), "localhost-key.pem"))),
+        cert:
+          bundleConfig.cert ||
+          (await readFile(path.join(process.cwd(), "localhost.pem"))),
+      }
+    : undefined;
+
   return [
     router,
     isSecure
-      ? https.createServer(
-          {
-            key:
-              bundleConfig.key ||
-              (await readFile(path.join(process.cwd(), "localhost-key.pem"))),
-            cert:
-              bundleConfig.cert ||
-              (await readFile(path.join(process.cwd(), "localhost.pem"))),
-          },
-          app,
-        )
+      ? httpolyglot.createServer(secureOptions!, app)
       : http.createServer({}, app),
   ];
 }
 
+function getDefaultHost() {
+  const host = bundleConfig.host === "::" ? "localhost" : bundleConfig.host;
+  return `${host}:${bundleConfig.port}`;
+}
+
 export async function getPostCSSConfig() {
   try {
     return await postcssrc({});
@@ -175,8 +196,7 @@ export function addHMRCode(
   if (html.includes("<!DOCTYPE html>") || html.includes("<html")) {
     DOM = ast || parse(html);
     const headNode = findElement(DOM as Node, (e) => getTagName(e) === "head");
-    // Inject first in <head> so the client runs before the page's own scripts.
-    prependChild(headNode as Node, script);
+    insertHeadClient(headNode as Node, script);
   } else {
     DOM = ast || parseFragment(html);
     prependChild(DOM as Node, script);
@@ -212,3 +232,13 @@ function prependChild(parent: Node, node: unknown) {
   (node as { parentNode?: unknown }).parentNode = parent;
   (parent as unknown as { childNodes: unknown[] }).childNodes.unshift(node);
 }
+
+function insertHeadClient(parent: Node, node: unknown) {
+  const children = (parent as unknown as { childNodes: Node[] }).childNodes;
+  const lastBaseIndex = children.findLastIndex(
+    (child) => getTagName(child) === "base",
+  );
+
+  (node as { parentNode?: unknown }).parentNode = parent;
+  children.splice(lastBaseIndex + 1, 0, node as Node);
+}

package/tests/bundle.test.mjs

@@ -133,6 +133,18 @@ test("addHMRCode injects fragment client before fragment scripts", async () => {
   );
 });
 
+test("addHMRCode injects full-document client after base and before scripts", async () => {
+  const { addHMRCode } = await import(pathToFileURL(utilsPath).href);
+
+  const html = addHMRCode(
+    '<!DOCTYPE html><html><head><base href="/"><script type="module">window.started = true;</script></head><body><main>Hi</main></body></html>',
+    "src/index.html",
+  );
+
+  assert.ok(html.indexOf('<base href="/">') < html.indexOf("data-hmr-client"));
+  assert.ok(html.indexOf("data-hmr-client") < html.indexOf("window.started"));
+});
+
 test("HMR full-document detection survives template-literal escaping", async () => {
   const { addHMRCode } = await import(pathToFileURL(utilsPath).href);
 
@@ -276,3 +288,110 @@ test("CLI honors a custom bundle.config.js src and build directories", async (t)
     { code: "ENOENT" },
   );
 });
+
+test("CLI removes development-only process.env.NODE_ENV branches in production", async (t) => {
+  const cwd = await mkdtemp(path.join(tmpdir(), "html-bundle-"));
+  t.after(() => rm(cwd, { force: true, recursive: true }));
+
+  await mkdir(path.join(cwd, "src"), { recursive: true });
+  await writeFile(
+    path.join(cwd, "src", "index.html"),
+    `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Fixture</title>
+    <script type="module">
+      if (process.env.NODE_ENV !== "production") {
+        window.__devOnly = "dev-only-hmr-hook";
+      }
+      window.__env = process.env.NODE_ENV;
+    </script>
+  </head>
+  <body><main>Hi</main></body>
+</html>`,
+  );
+
+  await execFilePromise(process.execPath, [bundlePath], { cwd });
+
+  const html = await readFile(path.join(cwd, "build", "index.html"), "utf8");
+  assert.doesNotMatch(html, /dev-only-hmr-hook/);
+  assert.doesNotMatch(html, /__devOnly/);
+  assert.match(html, /production/);
+});
+
+test("CLI limits concurrent handler processes and waits for them", async (t) => {
+  const cwd = await mkdtemp(path.join(tmpdir(), "html-bundle-"));
+  t.after(() => rm(cwd, { force: true, recursive: true }));
+
+  await mkdir(path.join(cwd, "src", "assets"), { recursive: true });
+  await writeFile(
+    path.join(cwd, "src", "index.html"),
+    `<!DOCTYPE html><html lang="en"><head><title>Fixture</title></head><body><main>Hi</main></body></html>`,
+  );
+
+  for (let index = 0; index < 5; index++) {
+    await writeFile(
+      path.join(cwd, "src", "assets", `image-${index}.raw`),
+      `image ${index}`,
+    );
+  }
+
+  await writeFile(
+    path.join(cwd, "handler.mjs"),
+    `import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const file = process.argv[2];
+const name = path.basename(file);
+const start = Date.now();
+await new Promise((resolve) => setTimeout(resolve, 120));
+const end = Date.now();
+
+await mkdir(path.join(process.cwd(), "build", "assets"), { recursive: true });
+await writeFile(
+  path.join(process.cwd(), "build", "assets", name),
+  await readFile(file),
+);
+await writeFile(
+  path.join(process.cwd(), "build", name + ".json"),
+  JSON.stringify({ name, start, end }),
+);
+`,
+  );
+
+  await execFilePromise(
+    process.execPath,
+    [bundlePath, "--handler", "handler.mjs", "--handlerConcurrency", "2"],
+    { cwd },
+  );
+
+  const records = [];
+  for (let index = 0; index < 5; index++) {
+    const name = `image-${index}.raw`;
+    const output = await readFile(
+      path.join(cwd, "build", "assets", name),
+      "utf8",
+    );
+    records.push(
+      JSON.parse(
+        await readFile(path.join(cwd, "build", name + ".json"), "utf8"),
+      ),
+    );
+    assert.equal(output, `image ${index}`);
+  }
+
+  const events = records
+    .flatMap(({ start, end }) => [
+      { time: start, delta: 1 },
+      { time: end, delta: -1 },
+    ])
+    .sort((a, b) => a.time - b.time || a.delta - b.delta);
+  let active = 0;
+  let maxActive = 0;
+  for (const event of events) {
+    active += event.delta;
+    maxActive = Math.max(maxActive, active);
+  }
+
+  assert.ok(maxActive <= 2, `expected max concurrency <= 2, got ${maxActive}`);
+});

package/tests/hmr-client.test.mjs

@@ -93,6 +93,32 @@ test("shared hub patches a full-document title change in place", async () => {
   assert.equal(document.querySelector("title").textContent, "After");
 });
 
+test("window.isHMR is hidden from the page's own initial scripts, then set for hot re-runs", async () => {
+  // Regression: the client is injected as the first <head> module so its hub and
+  // public API exist before the page's own scripts. It must NOT flip
+  // window.isHMR before those scripts run, or one-time guards such as
+  // `if (!window.isHMR) createRouter()` get skipped on the pristine load — the
+  // symptom being an SPA whose outlet never mounts (an almost-empty page).
+  const { window, document, loadPage } = await setup();
+  assert.equal(document.readyState, "interactive"); // pristine load, still parsing
+
+  loadPage("src/index.html", "idx1");
+  assert.notEqual(
+    window.isHMR,
+    true,
+    "isHMR must stay falsy while the page's own scripts run",
+  );
+
+  // DOMContentLoaded fires after those scripts; HMR mode is now observable so a
+  // subsequent hot re-execution can take the isHMR branch and skip re-init.
+  document.dispatchEvent(new window.Event("DOMContentLoaded"));
+  assert.equal(
+    window.isHMR,
+    true,
+    "isHMR is set once the initial load settles",
+  );
+});
+
 test("full-document insertion before a composed mount preserves fetched content", async () => {
   const { document, loadPage, reloadCount } = await setup();
   const before =
@@ -169,6 +195,81 @@ test("single-root fragment update patches only its own region", async () => {
   assert.equal(region.textContent, "New");
 });
 
+test("inactive fragment update does not append into the current document", async () => {
+  const { document, loadPage } = await setup();
+  document.body.innerHTML =
+    "<main><section id='active-route'>Checkbox route</section></main>";
+
+  loadPage("src/ssr.html", "ssr1");
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/ssr.html",
+    html: "<h1 data-hmr='ssr1'>Server-Side Rendering</h1><p data-hmr='ssr1'>SSR copy</p>",
+  });
+
+  assert.equal(document.querySelector('[data-hmr="ssr1"]'), null);
+  assert.equal(
+    document.body.textContent.includes("Server-Side Rendering"),
+    false,
+  );
+  assert.equal(
+    document.querySelector("#active-route")?.textContent,
+    "Checkbox route",
+  );
+});
+
+test("parent fragment update preserves a mounted child outlet", async () => {
+  const { document, loadPage } = await setup();
+  const previousHtml =
+    "<div data-hmr='doc1' class='layout'><aside>Old nav</aside><div data-outlet><h1>Getting started</h1><p>Parent default</p></div></div>";
+  const nextHtml =
+    "<div data-hmr='doc1' class='layout updated'><aside>New nav</aside><div data-outlet><h1>Getting started</h1><p>Parent default</p></div></div>";
+  document.body.innerHTML =
+    "<main><div data-hmr='doc1' class='layout'><aside>Old nav</aside><div data-outlet><h1 id='checkbox-route'>Checkbox route</h1><p>Child content</p></div></div></main>";
+
+  loadPage("src/documentation.html", "doc1");
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/documentation.html",
+    previousHtml,
+    html: nextHtml,
+  });
+
+  const region = document.querySelector('[data-hmr="doc1"]');
+  assert.match(region.className, /updated/);
+  assert.equal(region.querySelector("aside")?.textContent, "New nav");
+  assert.equal(
+    region.querySelector("#checkbox-route")?.textContent,
+    "Checkbox route",
+  );
+  assert.equal(
+    region
+      .querySelector("[data-outlet]")
+      ?.textContent.includes("Parent default"),
+    false,
+  );
+});
+
+test("fragment accept callback runs after a direct fragment patch", async () => {
+  const { document, loadPage } = await setup();
+  document.body.innerHTML = "<div data-hmr='app1'>Old</div>";
+  loadPage("src/app/index.html", "app1");
+
+  let accepted = false;
+  window.htmlBundleHMR.accept(() => {
+    accepted = true;
+  });
+
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/app/index.html",
+    html: "<div data-hmr='app1'>New</div>",
+  });
+
+  assert.equal(document.querySelector('[data-hmr="app1"]')?.textContent, "New");
+  assert.equal(accepted, true);
+});
+
 test("dispose runs before re-patch and data persists across updates", async () => {
   const { document, loadPage } = await setup();
   document.body.innerHTML = "<div data-hmr='app1'>Old</div>";

package/tests/hmr-server.test.mjs

@@ -3,15 +3,19 @@
 // normalised events the client depends on.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import http from "node:http";
+import https from "node:https";
 import { mkdtemp, mkdir, writeFile, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { promisify } from "node:util";
 
 const repoRoot = path.resolve(new URL("..", import.meta.url).pathname);
 const bundlePath = path.join(repoRoot, "dist", "bundle.mjs");
 const PORT = 5323;
+const SECURE_PORT = 5324;
+const execFilePromise = promisify(execFile);
 
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -84,6 +88,112 @@ async function until(predicate, ms = 6000) {
   return undefined;
 }
 
+async function writeLocalhostCertificate(cwd, t) {
+  try {
+    await execFilePromise("openssl", [
+      "req",
+      "-x509",
+      "-newkey",
+      "rsa:2048",
+      "-nodes",
+      "-keyout",
+      path.join(cwd, "localhost-key.pem"),
+      "-out",
+      path.join(cwd, "localhost.pem"),
+      "-subj",
+      "/CN=localhost",
+      "-days",
+      "1",
+      "-addext",
+      "subjectAltName=DNS:localhost,IP:127.0.0.1",
+    ]);
+    return true;
+  } catch {
+    t.skip("openssl is required to generate the HTTPS test certificate");
+    return false;
+  }
+}
+
+async function requestHttpRedirect(pathname) {
+  let lastError;
+  for (let attempt = 0; attempt < 40; attempt++) {
+    try {
+      return await new Promise((resolve, reject) => {
+        const req = http.get(
+          `http://127.0.0.1:${SECURE_PORT}${pathname}`,
+          (res) => {
+            res.resume();
+            resolve({
+              statusCode: res.statusCode,
+              location: res.headers.location,
+            });
+          },
+        );
+        req.on("error", reject);
+      });
+    } catch (error) {
+      lastError = error;
+      await wait(100);
+    }
+  }
+  throw lastError;
+}
+
+function requestHttps(pathname) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      {
+        hostname: "127.0.0.1",
+        port: SECURE_PORT,
+        path: pathname,
+        rejectUnauthorized: false,
+      },
+      (res) => {
+        res.setEncoding("utf8");
+        let body = "";
+        res.on("data", (chunk) => (body += chunk));
+        res.on("end", () => resolve({ statusCode: res.statusCode, body }));
+      },
+    );
+    req.on("error", reject);
+  });
+}
+
+test("secure HMR server redirects plain HTTP on the same port", async (t) => {
+  const cwd = await mkdtemp(path.join(tmpdir(), "html-bundle-secure-hmr-"));
+  t.after(() => rm(cwd, { force: true, recursive: true }));
+  await mkdir(path.join(cwd, "src"), { recursive: true });
+  if (!(await writeLocalhostCertificate(cwd, t))) return;
+
+  await writeFile(
+    path.join(cwd, "bundle.config.js"),
+    `export default { port: ${SECURE_PORT}, host: "127.0.0.1", deletePrev: true };\n`,
+  );
+  await writeFile(
+    path.join(cwd, "src", "index.html"),
+    `<!DOCTYPE html><html><head><title>Secure fixture</title></head><body><main>Secure fixture</main></body></html>`,
+  );
+
+  const server = spawn(process.execPath, [bundlePath, "--hmr", "--secure"], {
+    cwd,
+  });
+  t.after(() => server.kill("SIGKILL"));
+  server.stderr.on("data", () => {});
+
+  await waitForListening(server);
+
+  const redirect = await requestHttpRedirect("/quickstart/checkbox");
+  assert.equal(redirect.statusCode, 307);
+  assert.equal(
+    redirect.location,
+    `https://127.0.0.1:${SECURE_PORT}/quickstart/checkbox`,
+  );
+
+  const app = await requestHttps("/");
+  assert.equal(app.statusCode, 200);
+  assert.match(app.body, /Secure fixture/);
+});
+
 test("HMR server emits typed events and funnels module edits to owning pages", async (t) => {
   const cwd = await mkdtemp(path.join(tmpdir(), "html-bundle-hmr-"));
   t.after(() => rm(cwd, { force: true, recursive: true }));

package/types/static.d.ts

@@ -1 +1,12 @@
 declare module "critical";
+
+declare module "httpolyglot" {
+  import type { RequestListener, Server } from "node:http";
+  import type { ServerOptions } from "node:https";
+
+  const httpolyglot: {
+    createServer(options: ServerOptions, listener?: RequestListener): Server;
+  };
+
+  export default httpolyglot;
+}