Preload every module a page loads, so imports fetch in parallel

PAGE_MODULES in shared.mjs lists the module set of the home, entry,
category and 404 pages, and baseHeadHtml emits a modulepreload for each,
so search.js, cards.mjs, shared.mjs, views.js and owes.js no longer wait
for a second and third round trip. data.js gets fetchpriority=high. A lib
test walks the real import graph from each page's entry scripts and fails
if a list drifts. Checked in Chromium: no page errors, no module fetched
twice.

Closes #154

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

site/build.mjs

@@ -14,7 +14,7 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { baseHeadHtml, commercialLabel, headAssetsHtml, esc, latestAllowedDate, OG_CARD_NAME, sponsorButtonHtml } from "./lib/shared.mjs";
+import { baseHeadHtml, commercialLabel, headAssetsHtml, esc, latestAllowedDate, OG_CARD_NAME, PAGE_MODULES, sponsorButtonHtml } from "./lib/shared.mjs";
 import { filmstripHtml, groupedEntriesHtml } from "./lib/cards.mjs";
 import { categoryPageHtml } from "./lib/category-page.mjs";
 import { filmstripPick, isAttributionLicence, previewCredit, thumbRelPath } from "./lib/thumbs.mjs";
@@ -210,7 +210,7 @@ function guideRowsHtml(guides, repo) {
 
 function headMetaHtml(site, stats, generatedAt, hasCard) {
   return [
-    baseHeadHtml({ site, title: site.title, description: site.tagline, url: site.siteUrl, hasCard, root: "./" }),
+    baseHeadHtml({ site, title: site.title, description: site.tagline, url: site.siteUrl, hasCard, root: "./", modules: PAGE_MODULES.home }),
     `<meta name="generator" content="site/build.mjs ${esc(generatedAt)}" />`,
     `<meta name="catalog:entries" content="${stats.total}" />`,
     `<script type="application/ld+json">${scriptJson(homeJsonLd({ site, generatedAt, total: stats.total }))}</script>`,
@@ -275,6 +275,7 @@ function notFoundHtml(site) {
       </p>
     </main>
     <script src="${esc(base)}/data.js" defer></script>
+    ${PAGE_MODULES.notFound.filter((m) => m !== "not-found.js").map((m) => `<link rel="modulepreload" href="${esc(base)}/${m}" />`).join("\n    ")}
     <script type="module" src="${esc(base)}/not-found.js"></script>
   </body>
 </html>

site/lib/category-page.mjs

@@ -1,6 +1,6 @@
 /** One category's page: every entry in it, both views, no JavaScript needed to see everything. Pure. */
 import { groupedEntriesHtml } from "./cards.mjs";
-import { baseHeadHtml, clipText, esc, PREVIEW_CREDIT_LINE, SEO_DESCRIPTION_MAX, SEO_TITLE_MAX, sponsorButtonHtml } from "./shared.mjs";
+import { baseHeadHtml, clipText, esc, PREVIEW_CREDIT_LINE, SEO_DESCRIPTION_MAX, SEO_TITLE_MAX, sponsorButtonHtml, PAGE_MODULES } from "./shared.mjs";
 
 export function categoryPageUrl(site, cat) {
   return `${String(site.siteUrl).replace(/\/+$/, "")}/category/${cat}/`;
@@ -24,7 +24,7 @@ export function categoryPageHtml({ cat, meta, entries, site, stamp, total, hasCa
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>${esc(clipText(title, SEO_TITLE_MAX))}</title>
     <meta name="description" content="${esc(description)}" />
-    ${baseHeadHtml({ site, title, description, url, hasCard, root: "../../" })}
+    ${baseHeadHtml({ site, title, description, url, hasCard, root: "../../", modules: PAGE_MODULES.category })}
   </head>
   <body>
     <a class="skip-link" href="#entry-grid">Skip to the list</a>

site/lib/entry-page.mjs

@@ -12,8 +12,7 @@ import {
   STATUS_NOTES,
   verifiedAge,
   sponsorButtonHtml,
-  PREVIEW_CREDIT_LINE,
-} from "./shared.mjs";
+  PREVIEW_CREDIT_LINE, PAGE_MODULES } from "./shared.mjs";
 import { thumbHtml } from "./cards.mjs";
 import { previewCredit } from "./thumbs.mjs";
 
@@ -121,7 +120,7 @@ export function entryPageHtml({ entry, leadHtml, restHtml, deprecatedReasonHtml,
     <title>${esc(seoTitle(entry.name, entry.license))}</title>
     <meta name="description" content="${esc(seoDescription(entry))}" />
     ${deprecated ? '<meta name="robots" content="noindex" />' : ""}
-    ${baseHeadHtml({ site, title, description: desc, url, type: "article", hasCard, root: "../../" })}
+    ${baseHeadHtml({ site, title, description: desc, url, type: "article", hasCard, root: "../../", modules: PAGE_MODULES.entry })}
     <script type="application/ld+json">${scriptJson(jsonLd(entry, site))}</script>
   </head>
   <body>

site/lib/lib.test.mjs

@@ -1074,6 +1074,28 @@ has("cards: title level option", entryCardHtml(cardBase, { root: "", repo: "http
 
 eq("search: q from the URL is capped", readState(`?q=${"a".repeat(5000)}`, { q: "" }, {}).q.length, MAX_QUERY);
 
+/* modulepreload lists match the import graph ---------------------------- */
+{
+  const { PAGE_MODULES } = await import("./shared.mjs");
+  const libDir = new URL("./", import.meta.url);
+  const publicDir = new URL("../public/", import.meta.url);
+  // dist name -> source file (build.mjs copies these four from site/lib).
+  const fromLib = { "search.js": "search.mjs", "owes.js": "owes.mjs", "cards.mjs": "cards.mjs", "shared.mjs": "shared.mjs" };
+  const src = (name) => nodeFs.readFileSync(fromLib[name] ? new URL(fromLib[name], libDir) : new URL(name, publicDir), "utf8");
+  const importsOf = (name) => [...src(name).matchAll(/^import[^;]*?from "\.\/([^"]+)";/gm)].map((m) => m[1]);
+  const closure = (roots) => {
+    const seen = new Set();
+    const walk = (n) => { if (seen.has(n)) return; seen.add(n); importsOf(n).forEach(walk); };
+    roots.forEach(walk);
+    return [...seen].sort();
+  };
+  const roots = { home: ["app.js", "shortlist.js"], entry: ["shortlist.js"], category: ["category.js", "shortlist.js"], notFound: ["not-found.js"] };
+  for (const [page, list] of Object.entries(roots)) {
+    eq(`modulepreload: ${page} list matches its imports`, [...PAGE_MODULES[page]].sort().join(","), closure(list).join(","));
+  }
+  has("modulepreload: head emits the links", baseHeadHtml({ site: { siteUrl: "https://s/", title: "T", tagline: "x" }, title: "T", description: "d", url: "https://s/", root: "../../", modules: ["a.js"] }), '<link rel="modulepreload" href="../../a.js" />');
+}
+
 /* report (keep last) ------------------------------------------------------ */
 if (failures.length) {
   console.error(`lib.test failed (${failures.length}):`);

site/lib/shared.mjs

@@ -198,6 +198,19 @@ export const PREVIEW_CREDIT_LINE = "Preview images belong to their publishers an
 /** Self-hosted fonts (site/public/fonts/, OFL). The body face and the mono face are preloaded; the italic is not. */
 export const FONT_FILES = ["fonts/public-sans.woff2", "fonts/ibm-plex-mono-400.woff2"];
 
+/**
+ * Every ES module each page type loads, entry scripts and their imports, as
+ * served from dist. The head preloads the whole set so the browser fetches
+ * them in parallel instead of discovering each import one round trip later.
+ * lib.test.mjs walks the real import graph and fails if a list drifts.
+ */
+export const PAGE_MODULES = {
+  home: ["app.js", "search.js", "cards.mjs", "shared.mjs", "views.js", "shortlist.js", "owes.js"],
+  entry: ["shortlist.js", "owes.js"],
+  category: ["category.js", "views.js", "shortlist.js", "owes.js"],
+  notFound: ["not-found.js", "search.js"],
+};
+
 /** Icon, font preloads and stylesheet, resolved against `root`. Every page type shares them. */
 export function headAssetsHtml(root = "./") {
   return [
@@ -218,7 +231,7 @@ export const OG_CARD_NAME = "og-card.png";
  * page's path back to the site root ("./", "../", "../../"): the icon, the
  * self-hosted font preloads and the stylesheet are resolved against it.
  */
-export function baseHeadHtml({ site, title, description, url, type = "website", hasCard, indent = "    ", root = "./" }) {
+export function baseHeadHtml({ site, title, description, url, type = "website", hasCard, indent = "    ", root = "./", modules = [] }) {
   const base = String(site.siteUrl).replace(/\/+$/, "");
   const card = `${base}/${OG_CARD_NAME}`;
   const cardMeta = hasCard
@@ -246,6 +259,7 @@ export function baseHeadHtml({ site, title, description, url, type = "website",
     `<meta property="og:description" content="${esc(description)}" />`,
     `<meta property="og:url" content="${esc(url)}" />`,
     ...cardMeta,
+    ...modules.map((m) => `<link rel="modulepreload" href="${esc(root)}${esc(m)}" />`),
     `<meta name="twitter:title" content="${esc(title)}" />`,
     `<meta name="twitter:description" content="${esc(description)}" />`,
     ...headAssetsHtml(root),

site/public/index.html

@@ -233,7 +233,7 @@ <h2 id="guides-title">Guides</h2>
       <span aria-hidden="true">↑</span> Search
     </button>
 
-    <script src="./data.js" defer></script>
+    <script src="./data.js" defer fetchpriority="high"></script>
     <script type="module" src="./app.js"></script>
     <script type="module" src="./shortlist.js"></script>
   </body>