npm - html-bundle - Versions diffs - 6.3.1 → 6.4.0 - Mend

html-bundle 6.3.1 → 6.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/.github/dependabot.yml +5 -5
package/README.md +34 -3
package/dist/bundle.mjs +69 -18
package/dist/hmr-client.d.ts +40 -0
package/dist/hmr-client.js +446 -0
package/dist/utils.d.mts +14 -2
package/dist/utils.mjs +45 -178
package/package.json +3 -1
package/src/bundle.mts +67 -18
package/src/hmr-client.ts +577 -0
package/src/utils.mts +61 -186
package/tests/bundle.test.mjs +62 -10
package/tests/hmr-client.test.mjs +245 -0
package/tests/hmr-server.test.mjs +175 -0
package/tsconfig.json +1 -1

package/src/utils.mts CHANGED Viewed

@@ -9,15 +9,24 @@ import express from "express";
 import postcssrc from "postcss-load-config";
 import cssnano from "cssnano";
 import { parse, parseFragment, serialize } from "parse5";
-import {
-  createScript,
-  getTagName,
-  findElement,
-  appendChild,
-} from "@web/parse5-utils";
+import { createScript, getTagName, findElement } from "@web/parse5-utils";
 export const bundleConfig = await getBundleConfig();
+// The HMR client runtime is authored in src/hmr-client.ts and compiled by tsc to
+// dist/hmr-client.js alongside this module (a real file, so its code is never
+// mangled by template-literal escaping). Read it once and substitute the per-page
+// tokens on demand in buildHMRClient().
+let hmrClientTemplate = "";
+try {
+  hmrClientTemplate = await readFile(
+    new URL("./hmr-client.js", import.meta.url),
+    "utf-8",
+  );
+} catch {
+  // Only needed when --hmr is active; addHMRCode tolerates an empty template.
+}
 export function fileCopy(file: string) {
   return copyFile(file, getBuildPath(file));
 }
@@ -32,10 +41,17 @@ export function getBuildPath(file: string) {
   return file.replace(`${bundleConfig.src}/`, `${bundleConfig.build}/`);
 }
+// Every change the watcher detects is normalised into one of these events. The
+// client dispatches on `type`, so the server never needs the old .ts->.js file
+// renaming: module edits are delivered as "html" updates for the owning page(s).
+export type HMREvent =
+  | { type: "html"; file: string; html?: string; previousHtml?: string }
+  | { type: "css"; file: string }
+  | { type: "asset"; file: string }
+  | { type: "full-reload"; file: string };
 const CONNECTIONS = new Set<any>(); // In order to send the HMR information
-export let serverSentEvents:
-  | undefined
-  | (({ file, html }: { file: string; html?: string }) => void);
+export let serverSentEvents: undefined | ((event: HMREvent) => void);
 export async function createDefaultServer(
   isSecure: boolean,
 ): Promise<[Router, Server | HTTPSServer]> {
@@ -55,17 +71,14 @@ export async function createDefaultServer(
       CONNECTIONS.delete(reply);
     });
-    serverSentEvents = (data) => {
-      if (/\.(jsx?|tsx?)$/.test(data.file)) {
-        data.file = data.file.replace(".ts", ".js").replace(".jsx", ".js");
-      }
+    serverSentEvents = (event) => {
       CONNECTIONS.forEach((rep) => {
         if (rep.destroyed || rep.writableEnded) {
           CONNECTIONS.delete(rep);
           return;
         }
-        rep.write(`data: ${JSON.stringify(data)}\n\n`);
+        rep.write(`data: ${JSON.stringify(event)}\n\n`);
       });
     };
   });
@@ -102,7 +115,17 @@ export async function createDefaultServer(
 export async function getPostCSSConfig() {
   try {
     return await postcssrc({});
-  } catch {
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // postcssrc throws "No PostCSS Config found" when the project is zero-config;
+    // that is expected, so stay silent. Any other failure (e.g. a broken config
+    // or a TypeScript config that cannot be loaded) would otherwise silently
+    // degrade the build to cssnano-only, so surface it.
+    if (!/No PostCSS Config found/i.test(message)) {
+      console.error(
+        `\u26A0\uFE0F  Could not load your PostCSS config \u2013 falling back to cssnano only. ${message}`,
+      );
+    }
     return { plugins: [cssnano], options: {}, file: "" };
   }
 }
@@ -141,25 +164,27 @@ export function addHMRCode(
   if (!htmlIdMap.has(file)) {
     htmlIdMap.set(file, randomText());
   }
+  const id = htmlIdMap.get(file);
   const script = createScript(
-    { type: "module" },
-    getHMRCode(file, htmlIdMap.get(file), bundleConfig.src),
+    { type: "module", "data-hmr-client": id },
+    buildHMRClient(file, id, bundleConfig.src),
   );
   let DOM;
   if (html.includes("<!DOCTYPE html>") || html.includes("<html")) {
     DOM = ast || parse(html);
     const headNode = findElement(DOM as Node, (e) => getTagName(e) === "head");
-    appendChild(headNode, script);
+    // Inject first in <head> so the client runs before the page's own scripts.
+    prependChild(headNode as Node, script);
   } else {
     DOM = ast || parseFragment(html);
-    appendChild(DOM, script);
+    prependChild(DOM as Node, script);
   }
   //@ts-ignore
   DOM.childNodes.forEach((node) =>
-    node.attrs?.push({ name: "data-hmr", value: htmlIdMap.get(file) }),
+    node.attrs?.push({ name: "data-hmr", value: id }),
   );
   return serialize(DOM as any);
@@ -169,171 +194,21 @@ function randomText() {
   return Math.random().toString(32).slice(2);
 }
-function getHMRCode(file: string, id: string, src: string) {
-  return `import { render, html, $, $$, setShouldSetReactivity } from "hydro-js";
-  window.isHMR = true;
-  window.lastCalled = new Map();
-  window.htmlBundleHMRConnections ||= new Map();
-  window.htmlBundleHMRActiveId = "${id}";
-  let shouldReconnect = true;
-  let reconnectTimer;
-  for (const [hmrId, eventSource] of window.htmlBundleHMRConnections) {
-    if (hmrId !== "${id}") {
-      eventSource.close();
-      window.htmlBundleHMRConnections.delete(hmrId);
-      delete window["eventsource" + hmrId];
-    }
-  }
-  function closeEventSource() {
-    const eventSource = window.eventsource${id};
-    if (eventSource) {
-      eventSource.close();
-      window.htmlBundleHMRConnections.delete("${id}");
-      delete window.eventsource${id};
-    }
-  }
-  function connectEventSource() {
-    closeEventSource();
-    shouldReconnect = true;
-    const eventSource = new EventSource("/hmr");
-    window.eventsource${id} = eventSource;
-    window.htmlBundleHMRConnections.set("${id}", eventSource);
-    eventSource.addEventListener('error', () => {
-      eventSource.close();
-      if (window.eventsource${id} === eventSource) {
-        window.htmlBundleHMRConnections.delete("${id}");
-        delete window.eventsource${id};
-      }
-      if (shouldReconnect && window.htmlBundleHMRActiveId === "${id}") {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = setTimeout(connectEventSource, 1000);
-      }
-    });
-    eventSource.addEventListener("message", ({ data }) => {
-      if (window.lastScroll == null) {
-        window.lastScroll = window.scrollY;
-      }
-      const dataObj = JSON.parse(data);
-      const file = "${file}";
-      if (file === dataObj.file && "html" in dataObj) {
-        let newHTML;
-        try {
-          newHTML = html\`\${dataObj.html}\`
-        } catch {
-          setShouldSetReactivity(false);
-          newHTML = html\`\${dataObj.html}\`
-          setShouldSetReactivity(true);
-        }
-        if (dataObj.html.startsWith('<!DOCTYPE html>') || dataObj.html.startsWith('<html')) {
-          document.head.remove(); // Don't try to diff the head – just re-run the scripts
-          // Restore Scroll
-          window.addEventListener("afterRouting", () => {
-            window.scrollTo(0, window.lastScroll);
-            delete window.lastScroll;
-          }, { once: true })
-          render(newHTML, document.documentElement, false);
-        } else {
-          const hmrID = "${id}";
-          const hmrElems = Array.from(newHTML.childNodes);
-          const hmrWheres = Array.from($$(\`[data-hmr="\${hmrID}"]\`))
-          // render new elements for old elements. Then, remove rest old elements and add add new elements after the last old one
-          hmrWheres.forEach((where, index) => {
-            if (index < hmrElems.length) {
-              render(hmrElems[index], where, false);
-            } else {
-              where.remove();
-            }
-          });
-          for (let rest = hmrWheres.length; rest < hmrElems.length; rest++) {
-            if (hmrWheres.length) {
-              const template = document.createElement('template');
-              hmrElems[hmrWheres.length - 1].after(template);
-              render(hmrElems[rest], template, false);
-              template.remove();
-            } else {
-              render(hmrElems[rest], false, false)
-            }
-          }
-        }
-        $$('link[rel="stylesheet"][href]').forEach(link => {
-          link.setAttribute("href", link.getAttribute("href") + "?v=" + String(Math.random().toFixed(4)).slice(2));
-        })
-        if (dataObj.html.includes("<script")) updateElem("script");
-        if (dataObj.file === \`${src}/index.html\`) {
-          dispatchEvent(new Event("popstate"));
-        }
-      } else if (dataObj.file.endsWith(".css")) {
-        const now = performance.now();
-        if (!window.lastCalled.has(dataObj.file) || now - window.lastCalled.get(dataObj.file) > 100) {
-          $$('link[rel="stylesheet"][href]').forEach(link => {
-            link.setAttribute("href", link.getAttribute("href") + "?v=" + String(Math.random().toFixed(4)).slice(2));
-          })
-          window.lastCalled.set(dataObj.file, now)
-        }
-      } else if (dataObj.file.endsWith(".js")) {
-        const now = performance.now();
-        if (!window.lastCalled.has(dataObj.file) || now - window.lastCalled.get(dataObj.file) > 100) {
-          $$('link[rel="stylesheet"][href]').forEach(link => {
-            link.setAttribute("href", link.getAttribute("href") + "?v=" + String(Math.random().toFixed(4)).slice(2));
-          })
-          updateElem("script");
-          window.lastCalled.set(dataObj.file, now)
-        }
-      }
-      function updateElem(type) {
-        const hmrId = "${id}";
-        const noSrcFile = dataObj.file.replace(\`${src}/\`, '');
-        const attr = type === "script" ? "src" : "href";
-        const elem = $(\`[data-hmr="\${hmrId}"] \${type}[\${attr}^="\${noSrcFile}"]\`); // could be $(\`\${type}[data-hmr="\${hmrId}"][\${attr}^="\${noSrcFile}"]\`) ?
-        if (elem) {
-          updateOne(type, attr, elem)
-        } else {
-          for(const e of $$(\`[data-hmr="\${hmrId}"] \${type}\`)) {
-            updateOne(type, attr, e);
-          }
-        }
-      }
-      function updateOne(type, attr, elem) {
-        const clone = document.createElement(type);
-        for (const key of elem.getAttributeNames()) {
-          clone.setAttribute(key, elem.getAttribute(key));
-        }
-        const attrVal = elem.getAttribute(attr);
-        if (attrVal) clone.setAttribute(attr, attrVal + "?v=" + String(Math.random().toFixed(4)).slice(2));
-        render(clone, elem, false);
-      }
-    });
-  }
-  window.addEventListener("pagehide", () => {
-    shouldReconnect = false;
-    clearTimeout(reconnectTimer);
-    if (window.htmlBundleHMRActiveId === "${id}") {
-      delete window.htmlBundleHMRActiveId;
-    }
-    closeEventSource();
-  }, { once: true });
+// Produce the per-page HMR client by substituting tokens into the shared runtime
+// template (src/hmr-client.ts). The runtime is injected as an inline module so
+// esbuild bundles hydro-js for it, but it coordinates through a single global hub
+// so every composed page shares one EventSource and patches its own region.
+function buildHMRClient(file: string, id: string, src: string) {
+  return hmrClientTemplate
+    .replaceAll("__HMR_FILE__", file)
+    .replaceAll("__HMR_ID__", id)
+    .replaceAll("__HMR_SRC__", src);
+}
-  if (!window.eventsource${id}) {
-    connectEventSource();
-  }
-`;
+function prependChild(parent: Node, node: unknown) {
+  // Insert as the first child so the HMR client runs before the page's own
+  // scripts — required for window.htmlBundleHMR.dispose()/data to be usable on
+  // initial load.
+  (node as { parentNode?: unknown }).parentNode = parent;
+  (parent as unknown as { childNodes: unknown[] }).childNodes.unshift(node);
 }

package/tests/bundle.test.mjs CHANGED Viewed

@@ -89,23 +89,75 @@ test("addHMRCode injects stable HMR wiring", async () => {
   );
   const fragment = addHMRCode("<main>Hi</main>", "src/fragment.html");
-  assert.match(fullDocument, /<script type="module">/);
+  assert.match(fullDocument, /<script type="module" data-hmr-client="[^\"]+">/);
   assert.match(fullDocument, /new EventSource\("\/hmr"\)/);
-  assert.match(
-    fullDocument,
-    /window\.htmlBundleHMRConnections \|\|= new Map\(\)/,
-  );
-  assert.match(fullDocument, /window\.addEventListener\("pagehide"/);
-  assert.match(fullDocument, /eventSource\.close\(\)/);
+  // Single shared hub + public opt-in API replace the old per-page globals.
+  assert.match(fullDocument, /window\.__htmlBundleHMR/);
+  assert.match(fullDocument, /window\.htmlBundleHMR = \{/);
+  assert.match(fullDocument, /hub\.register\(FILE, ID/);
+  assert.match(fullDocument, /"pagehide"/);
+  assert.match(fullDocument, /\.close\(\)/);
   assert.match(fullDocument, /data-hmr="[^"]+"/);
+  assert.match(fullDocument, /function patchDocument\(/);
+  assert.match(fullDocument, /function patchScript\(/);
+  // Single-root fragments must be normalised (hydro-js returns the element, not
+  // a DocumentFragment) so patching targets the right nodes.
+  assert.match(fullDocument, /Node\.DOCUMENT_FRAGMENT_NODE/);
+  // tsc formats the tagged template with a space (`html `...``), so allow it.
+  assert.match(fullDocument, /html\s*`\$\{htmlText\}`/);
+  assert.doesNotMatch(fullDocument, /document\.head\.remove\(\)/);
+  assert.doesNotMatch(fullDocument, /DOMParser/);
+  // The client is injected first in <head> so it runs before the page's own
+  // scripts (needed for window.htmlBundleHMR.dispose()/data on initial load).
   assert.ok(
     fullDocument.indexOf("<head>") <
-      fullDocument.indexOf('<script type="module">'),
+      fullDocument.indexOf('<script type="module" data-hmr-client='),
   );
-  assert.match(fragment, /^<main data-hmr="[^"]+">Hi<\/main>/);
+  assert.match(fragment, /<main data-hmr="[^"]+">Hi<\/main>/);
   assert.match(fragment, /new EventSource\("\/hmr"\)/);
-  assert.match(fragment, /window\.htmlBundleHMRActiveId ===/);
+  assert.match(fragment, /hub\.register\(FILE, ID/);
+});
+test("addHMRCode injects fragment client before fragment scripts", async () => {
+  const { addHMRCode } = await import(pathToFileURL(utilsPath).href);
+  const fragment = addHMRCode(
+    '<script type="module">window.htmlBundleHMR.dispose(() => {});</script><main>Hi</main>',
+    "src/scripted-fragment.html",
+  );
+  assert.ok(
+    fragment.indexOf("data-hmr-client") <
+      fragment.indexOf("window.htmlBundleHMR.dispose"),
+  );
+});
+test("HMR full-document detection survives template-literal escaping", async () => {
+  const { addHMRCode } = await import(pathToFileURL(utilsPath).href);
+  const doc = addHMRCode(
+    "<!DOCTYPE html><html><head></head><body>x</body></html>",
+    "src/detect.html",
+  );
+  const code = doc.match(/data-hmr-client="[^"]+">([\s\S]*?)<\/script>/)[1];
+  const start = code.indexOf("function isFullDocument");
+  const end = code.indexOf("function parseHTML");
+  const fnText = code.slice(start, end);
+  const isFullDocument = new Function(`${fnText}\n return isFullDocument;`)();
+  // Real payloads emitted by the server (parse5 + html-minifier-terser).
+  assert.equal(
+    isFullDocument("<!DOCTYPE html><html><body></body></html>"),
+    true,
+  );
+  assert.equal(
+    isFullDocument("<!doctype html><html><body></body></html>"),
+    true,
+  );
+  assert.equal(isFullDocument('<html lang="en"><body></body></html>'), true);
+  // Fragments must still take the fragment path.
+  assert.equal(isFullDocument("<main>fragment</main>"), false);
 });
 test("getBuildPath maps src paths into the build directory", async () => {

package/tests/hmr-client.test.mjs ADDED Viewed

@@ -0,0 +1,245 @@
+// Client-runtime tests for the compiled HMR client (dist/hmr-client.js, built
+// from src/hmr-client.ts).
+//
+// The runtime is a real browser module, so we exercise it under happy-dom with
+// the real hydro-js: replace its `hydro-js` import with injected deps, load it
+// per page via `new Function`, then drive it through the shared hub the same way
+// the browser's EventSource would.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { Window } from "happy-dom";
+const repoRoot = path.resolve(new URL("..", import.meta.url).pathname);
+const clientPath = path.join(repoRoot, "dist", "hmr-client.js");
+const clientSrc = await readFile(clientPath, "utf8");
+// Fresh DOM, globals and hub per test so state never leaks between cases.
+async function setup() {
+  const w = new Window({ url: "http://localhost:5000/" });
+  globalThis.window = w;
+  globalThis.document = w.document;
+  globalThis.Node = w.Node;
+  globalThis.HTMLHtmlElement = w.HTMLHtmlElement;
+  globalThis.HTMLElement = w.HTMLElement;
+  globalThis.Event = w.Event;
+  globalThis.performance = w.performance ?? { now: () => Date.now() };
+  globalThis.dispatchEvent = w.dispatchEvent
+    ? w.dispatchEvent.bind(w)
+    : () => {};
+  w.scrollTo = () => {};
+  let eventSourceCount = 0;
+  globalThis.EventSource = class {
+    constructor() {
+      eventSourceCount++;
+    }
+    addEventListener() {}
+    close() {}
+  };
+  let reloadCount = 0;
+  w.location.reload = () => {
+    reloadCount++;
+  };
+  globalThis.__hydro = await import("hydro-js");
+  function loadPage(file, id, src = "src") {
+    const code = clientSrc
+      .replace(
+        'import { render as hydroRender, html, setShouldSetReactivity } from "hydro-js";',
+        "const { render: hydroRender, html, setShouldSetReactivity } = globalThis.__hydro;",
+      )
+      .replaceAll("__HMR_FILE__", file)
+      .replaceAll("__HMR_ID__", id)
+      .replaceAll("__HMR_SRC__", src);
+    // eslint-disable-next-line no-new-func
+    new Function(code)();
+  }
+  return {
+    window: w,
+    document: w.document,
+    loadPage,
+    eventSourceCount: () => eventSourceCount,
+    reloadCount: () => reloadCount,
+  };
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const FULL_BEFORE =
+  "<!DOCTYPE html><html><head><title>Before</title></head><body><main class='center'></main></body></html>";
+const FULL_AFTER =
+  "<!DOCTYPE html><html><head><title>After</title></head><body><main class='center'></main></body></html>";
+test("shared hub patches a full-document title change in place", async () => {
+  const { document, loadPage } = await setup();
+  document.documentElement.innerHTML =
+    "<head><title>Before</title></head><body><main class='center'></main></body>";
+  loadPage("src/index.html", "idx1");
+  assert.ok(window.__htmlBundleHMR, "hub is created");
+  assert.equal(typeof window.htmlBundleHMR.dispose, "function");
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/index.html",
+    previousHtml: FULL_BEFORE,
+    html: FULL_AFTER,
+  });
+  assert.equal(document.querySelector("title").textContent, "After");
+});
+test("full-document insertion before a composed mount preserves fetched content", async () => {
+  const { document, loadPage, reloadCount } = await setup();
+  const before =
+    "<!DOCTYPE html><html><head><title>Fixture</title></head><body><noscript>Enable JS</noscript><main class='center'></main></body></html>";
+  const after =
+    "<!DOCTYPE html><html><head><title>Fixture</title></head><body><p id='new-copy'>New copy</p><noscript>Enable JS</noscript><main class='center'></main></body></html>";
+  document.documentElement.innerHTML =
+    "<head><title>Fixture</title></head><body><noscript>Enable JS</noscript><main class='center'><picture><img src='@public/splash.webp'></picture></main></body>";
+  loadPage("src/index.html", "idx1");
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/index.html",
+    previousHtml: before,
+    html: after,
+  });
+  assert.equal(document.querySelector("#new-copy")?.textContent, "New copy");
+  assert.ok(document.querySelector("main.center img"));
+  assert.equal(reloadCount(), 0);
+});
+test("same-tag insertion before a composed mount preserves fetched content", async () => {
+  const { document, loadPage } = await setup();
+  const before =
+    "<!DOCTYPE html><html><head><title>Fixture</title></head><body><main class='center'></main></body></html>";
+  const after =
+    "<!DOCTYPE html><html><head><title>Fixture</title></head><body><main id='banner'>New copy</main><main class='center'></main></body></html>";
+  document.documentElement.innerHTML =
+    "<head><title>Fixture</title></head><body><main class='center'><picture><img src='@public/splash.webp'></picture></main></body>";
+  loadPage("src/index.html", "idx1");
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/index.html",
+    previousHtml: before,
+    html: after,
+  });
+  assert.equal(document.querySelector("#banner")?.textContent, "New copy");
+  assert.ok(document.querySelector("main.center img"));
+});
+test("full-reload events trigger a debounced page reload", async () => {
+  const { loadPage, reloadCount } = await setup();
+  loadPage("src/index.html", "idx1");
+  window.__htmlBundleHMR.dispatch({
+    type: "full-reload",
+    file: "src/@shared/workerCode.ts",
+  });
+  window.__htmlBundleHMR.dispatch({
+    type: "full-reload",
+    file: "src/@shared/workerCode.ts",
+  });
+  await wait(30);
+  assert.equal(reloadCount(), 1);
+});
+test("single-root fragment update patches only its own region", async () => {
+  const { document, loadPage } = await setup();
+  document.body.innerHTML =
+    "<main class='center'><div data-hmr='app1'>Old</div></main>";
+  loadPage("src/app/index.html", "app1");
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/app/index.html",
+    html: "<main data-hmr='app1'>New</main>",
+  });
+  const region = document.querySelector('[data-hmr="app1"]');
+  assert.equal(region.textContent, "New");
+});
+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>";
+  loadPage("src/app/index.html", "app1");
+  let disposed = false;
+  window.htmlBundleHMR.dispose(() => {
+    disposed = true;
+  });
+  window.htmlBundleHMR.data.persisted = 42;
+  window.__htmlBundleHMR.dispatch({
+    type: "html",
+    file: "src/app/index.html",
+    html: "<div data-hmr='app1'>New</div>",
+  });
+  assert.equal(disposed, true);
+  assert.equal(window.htmlBundleHMR.data.persisted, 42);
+});
+test("css event cache-busts stylesheet links", async () => {
+  const { document, loadPage } = await setup();
+  document.documentElement.innerHTML =
+    '<head><link rel="stylesheet" href="@public/base.css"></head><body></body>';
+  loadPage("src/index.html", "idx1");
+  window.__htmlBundleHMR.dispatch({
+    type: "css",
+    file: "src/@public/base.css",
+  });
+  const href = document.querySelector("link").getAttribute("href");
+  assert.match(href, /^@public\/base\.css\?v=\d+$/);
+});
+test("asset event cache-busts the matching element", async () => {
+  const { document, loadPage } = await setup();
+  document.body.innerHTML = '<img src="@public/splash.webp">';
+  loadPage("src/index.html", "idx1");
+  window.__htmlBundleHMR.dispatch({
+    type: "asset",
+    file: "src/@public/splash.webp",
+  });
+  const src = document.querySelector("img").getAttribute("src");
+  assert.match(src, /^@public\/splash\.webp\?v=\d+$/);
+});
+test("a change to an unregistered page is a safe no-op", async () => {
+  const { document, loadPage } = await setup();
+  document.documentElement.innerHTML =
+    "<head><title>Before</title></head><body></body>";
+  loadPage("src/index.html", "idx1");
+  assert.doesNotThrow(() =>
+    window.__htmlBundleHMR.dispatch({
+      type: "html",
+      file: "src/never.html",
+      html: "<div></div>",
+    }),
+  );
+  assert.equal(document.querySelector("title").textContent, "Before");
+});
+test("all composed pages share exactly one EventSource", async () => {
+  const { loadPage, eventSourceCount } = await setup();
+  loadPage("src/index.html", "idx1");
+  loadPage("src/app/index.html", "app1");
+  loadPage("src/link/index.html", "lnk1");
+  assert.equal(eventSourceCount(), 1);
+});