@zvndev/darkmown 2.11.0 → 2.12.1

package/src/cli.js

@@ -490,11 +490,13 @@ function startDevServer({ cwd, log, warn, error }) {
  * Start the static preview server for an existing `dist/`. Throws `CliError`
  * when there is nothing built to serve.
  *
- * Preview mirrors production more closely than dev in two ways: project
+ * Preview mirrors production more closely than dev in three ways: project
  * `api/*.js` functions run on `/api/*` (same runner and `(request) => Response`
  * contract as dev — a project without `api/` falls straight through to static),
- * and compressible responses are brotli/gzip-negotiated off Accept-Encoding so
- * local weight checks see transfer sizes, not raw bytes.
+ * compressible responses are brotli/gzip-negotiated off Accept-Encoding so
+ * local weight checks see transfer sizes, not raw bytes, and static files carry
+ * validators (ETag/Last-Modified/Cache-Control) with conditional-request 304s,
+ * so a reload revalidates instead of re-downloading every asset.
  * @param {{ cwd: string, log: typeof console.log, error: typeof console.error }} io
  * @returns {Promise<{ command: "serve", server: import("node:http").Server, close: () => Promise<void> }>}
  */
@@ -518,7 +520,15 @@ function startPreviewServer({ cwd, log, error }) {
     // but never echoed — a stack trace leaks paths and internals to the client.
     handleApiRequest({ apiDir, req, res, acceptEncoding, discloseErrors: false })
       .then((handled) => {
-        if (!handled) serve(distRoot, req.url || "/", res, { acceptEncoding });
+        if (!handled) {
+          serve(distRoot, req.url || "/", res, {
+            acceptEncoding,
+            validators: {
+              ifNoneMatch: req.headers["if-none-match"],
+              ifModifiedSince: req.headers["if-modified-since"]
+            }
+          });
+        }
       })
       .catch((err) => {
         error(err instanceof Error && err.stack ? err.stack : String(err));

package/src/compiler/markdown.js

@@ -788,6 +788,13 @@ function bindingPlugin(mdInstance) {
  * wrapper container. The block must directly follow the element (no space), and
  * `{ … }` interpolation is unaffected (its content starts with a name, not `.`/`#`).
  * Issue #18.
+ *
+ * One image-only extension: `sizes="…"` (quoted, any content). The srcset
+ * variant wiring emits no `sizes` of its own — inventing one guesses the
+ * layout — so the AUTHOR supplies it here when the image is not full-width:
+ * `![hero](/h.jpg){sizes="(max-width: 640px) 100vw, 640px"}`. It passes through
+ * with or without a srcset, and markdown-it escapes the value on render. On a
+ * non-image target the token is ignored like any other unrecognized part.
  * @param {MarkdownIt} mdInstance
  * @returns {void}
  */
@@ -799,13 +806,18 @@ function attrsPlugin(mdInstance) {
       for (let i = 0; i < children.length; i++) {
         const tok = children[i];
         if (tok.type !== "text") continue;
-        const m = /^\{([.#][^}]*)\}/.exec(tok.content);
+        const m = /^\{((?:[.#]|sizes=")[^}]*)\}/.exec(tok.content);
         if (!m) continue;
         const target = attrTarget(children, i);
         if (!target) continue;
-        for (const part of m[1].split(/\s+/).filter(Boolean)) {
+        // `sizes` is one quoted token that may itself hold spaces, so it must
+        // be matched whole before the whitespace split. Anything else that is
+        // not `.class` / `#id` keeps its long-standing behavior: skipped.
+        for (const part of m[1].match(/sizes="[^"]*"|\S+/g) ?? []) {
           if (part[0] === ".") target.attrJoin("class", part.slice(1));
           else if (part[0] === "#") target.attrSet("id", part.slice(1));
+          else if (target.type === "image" && part.startsWith('sizes="'))
+            target.attrSet("sizes", part.slice(7, -1));
         }
         tok.content = tok.content.slice(m[0].length);
       }

package/src/compiler/page.js

@@ -183,24 +183,24 @@ export function compilePage(file, context, options = {}) {
   // (graceful, transition-free fallback) and only applies to same-origin
   // navigations where both the outgoing and incoming page opt in.
   //
-  // The default UA animation cross-fades the root: outgoing opacity 1→0 while
-  // incoming 0→1, both at once. Mid-navigation that leaves the two pages
-  // superimposed at ~50% opacity — headings ghost over headings. We override it
-  // with a directional fade+slide (old lifts up and out, new rises up and in) so
-  // the pages move past each other instead of stacking. Short + eased = peppy.
+  // The default is a quick out-then-in: the outgoing snapshot fades to 0 in
+  // 90ms, the incoming one fades in after an 80ms delay. A simultaneous
+  // cross-fade was measured on a real site and read as flicker: the incoming
+  // snapshot stacks over the outgoing one, so image-heavy pages double-expose
+  // (outgoing opaque, incoming ghosting through). Sequencing keeps at most a
+  // ~10ms overlap near background opacity, so nothing ever ghosts. The delay
+  // fills `both`, keeping the incoming snapshot invisible until its turn.
   const wantTransitions =
     compiled.meta.transitions === true || compiled.meta.transitions === "true";
   const transitions = wantTransitions
     ? `\n  <style>
     @view-transition { navigation: auto; }
-    ::view-transition-old(root) { animation: wd-nav-out 200ms cubic-bezier(0.4, 0, 1, 1) both; }
-    ::view-transition-new(root) { animation: wd-nav-in 200ms cubic-bezier(0, 0, 0.2, 1) both; }
-    @keyframes wd-nav-out { to { opacity: 0; transform: translateY(-1rem); } }
-    @keyframes wd-nav-in { from { opacity: 0; transform: translateY(1rem); } }
+    ::view-transition-old(root) { animation: wd-nav-out 90ms cubic-bezier(0.4, 0, 0.2, 1) both; }
+    ::view-transition-new(root) { animation: wd-nav-in 130ms cubic-bezier(0.4, 0, 0.2, 1) 80ms both; }
+    @keyframes wd-nav-out { to { opacity: 0; } }
+    @keyframes wd-nav-in { from { opacity: 0; } }
     @media (prefers-reduced-motion: reduce) {
-      ::view-transition-old(root), ::view-transition-new(root) { animation-duration: 1ms; }
-      @keyframes wd-nav-out { to { opacity: 0; } }
-      @keyframes wd-nav-in { from { opacity: 0; } }
+      ::view-transition-old(root), ::view-transition-new(root) { animation-duration: 1ms; animation-delay: 0ms; }
     }
   </style>`
     : "";

package/src/font-subset.js

@@ -28,6 +28,18 @@
 // The build is synchronous, the wasm API is not — that is the whole reason for
 // the child process. `buildSite` stays a sync API; one `spawnSync` per build
 // runs all pending subsets, and a fully cached build spawns nothing.
+//
+// FONT PRELOADS (2.12.0). The same pass ends by injecting
+// `<link rel="preload" as="font" crossorigin>` into every emitted page for the
+// fonts that page actually loads (found through its own linked stylesheets), so
+// the font fetch starts with the CSS instead of after it — the visible
+// swap-and-reflow on every load. A page preloads exactly the URL its rewritten
+// CSS leads with: the subset woff2 when subsetting ran, the original project
+// font when the toolchain is absent, the font was skipped, or the source was
+// already woff2. Remote srcs are never preloaded, a page whose stylesheets
+// declare no project fonts is left byte-identical, and re-running the pass over
+// the same dist (the incremental build's re-emitted HTML) never duplicates a
+// link.
 // ---------------------------------------------------------------------------
 
 import { spawnSync } from "node:child_process";
@@ -81,9 +93,37 @@ import { isAllowedInclude } from "./compiler/includes.js";
  * @property {string} [cacheFile] Absolute cache path, set once the hashes are known.
  */
 
+/**
+ * A project-local font an emitted stylesheet can preload. For a subsettable
+ * font this is the FontRef itself; an already-woff2 original carries a null
+ * `subsetUrl` (there is nothing to subset — it preloads as-is).
+ * @typedef {object} PreloadRef
+ * @property {string} url The url() target exactly as written in the CSS.
+ * @property {string} source Absolute path of the font file it resolves to.
+ * @property {string | null} subsetUrl Served URL of the subset, when subsettable.
+ */
+
+/**
+ * One preload link to inject into a page.
+ * @typedef {object} PreloadFont
+ * @property {string} href The URL the page's CSS leads with (subset or original).
+ * @property {string} type The MIME type for the href's extension.
+ */
+
 /** The formats hb-subset reads directly; woff2 inputs and remote URLs pass through. */
 const SUBSETTABLE_EXTENSIONS = new Set([".ttf", ".otf", ".woff"]);
 
+/** Already-encoded woff2: never subsetted, but preloaded as-is. */
+const WOFF2_ONLY = new Set([".woff2"]);
+
+/** The preload `type` for each preloadeable font extension. */
+const FONT_MIME = /** @type {Record<string, string>} */ ({
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf"
+});
+
 /** The cache root, relative to the project. Under node_modules, so already ignored. */
 const CACHE_DIR = "node_modules/.cache/darkmown-fonts";
 
@@ -101,6 +141,9 @@ const FONT_FACE_BLOCK = /@font-face\s*\{[^}]*\}/g;
 /** A url() target, double-quoted, single-quoted, or bare. */
 const URL_REF = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^)"'\s]+))\s*\)/g;
 
+/** A whole `<link …>` tag in emitted HTML. */
+const LINK_TAG = /<link\b[^>]*>/g;
+
 /** A numeric character reference: `&#65;` or `&#x2605;`. */
 const NUMERIC_ENTITY = /&#(x[0-9a-fA-F]+|X[0-9a-fA-F]+|\d+);/g;
 
@@ -139,14 +182,17 @@ export const BASE_CODEPOINTS = buildBaseCodepoints();
 
 /**
  * Subset every project-local font referenced by the emitted stylesheets and
- * rewrite the dist CSS to lead with the subset woff2.
+ * rewrite the dist CSS to lead with the subset woff2. Then inject one font
+ * `<link rel="preload" as="font" crossorigin>` per project font into every
+ * emitted page that loads it through its own linked stylesheets.
  *
  * Skips, none of them errors: remote/protocol-relative/data/relative URLs
- * (silently), already-woff2 sources (silently), URLs that escape or miss the
- * project (silently — a broken link is an authoring bug, not a subsetting one).
- * An unreadable font file, and one the toolchain fails on, get a hint naming
- * the file and ship as-is. With no `@font-face` in any emitted stylesheet the
- * pass is a no-op and never even scans the HTML.
+ * (silently), already-woff2 sources (silently — not subsetted, but preloaded
+ * as-is), URLs that escape or miss the project (silently — a broken link is an
+ * authoring bug, not a subsetting one). An unreadable font file, and one the
+ * toolchain fails on, get a hint naming the file and ship as-is. With no
+ * project-font reference in any emitted stylesheet the pass is a no-op and
+ * never even scans the HTML.
  * @param {Paths} paths
  * @param {{ cacheDir?: string, quiet?: boolean,
  *   runJobs?: (payload: { charset: number[], jobs: SubsetJob[] }) => SubsetResult }} [options]
@@ -165,122 +211,144 @@ export function subsetFonts(paths, options = {}) {
   // Pass 1: every local font any emitted stylesheet references, deduped by
   // source file (several @font-face blocks, and several stylesheets, can share
   // one font file — it is subsetted once and each reference is rewritten).
+  // `cssRefs` keeps the per-stylesheet list for the preload injection (pass 4):
+  // subsettable refs plus already-woff2 originals.
   /** @type {Map<string, FontRef>} */
   const fonts = new Map();
   /** @type {string[]} Every url() occurrence that resolved, for the rewrite map. */
   const occurrences = [];
   /** @type {string[]} */
   const cssFiles = [];
+  /** @type {Map<string, PreloadRef[]>} Stylesheet → its project fonts, in order. */
+  const cssRefs = new Map();
   for (const file of walk(paths.distRoot)) {
     if (!file.endsWith(".css")) continue;
     cssFiles.push(file);
     const css = fs.readFileSync(file, "utf8");
+    /** @type {PreloadRef[]} */
+    const refs = [];
     for (const url of fontUrlsInCss(css)) {
       const resolved = resolveFontUrl(paths, url);
-      if (!resolved) continue;
-      occurrences.push(url);
-      if (!fonts.has(resolved.source)) fonts.set(resolved.source, resolved);
+      if (resolved) {
+        occurrences.push(url);
+        if (!fonts.has(resolved.source)) fonts.set(resolved.source, resolved);
+        refs.push(resolved);
+        continue;
+      }
+      const woff2 = resolveWoff2FontUrl(paths, url);
+      if (woff2) refs.push(woff2);
     }
+    if (refs.length > 0) cssRefs.set(file, refs);
   }
-  if (fonts.size === 0) return stats;
+  if (fonts.size === 0 && cssRefs.size === 0) return stats;
 
-  // Pass 2: the charset — the base set plus every code point in the emitted
-  // pages. The scan reads the final HTML, so non-latin content flows into the
-  // union automatically; over-inclusion from markup is impossible to notice
-  // (tags are ASCII, which the base set already carries).
-  /** @type {string[]} */
-  const texts = [];
-  for (const file of walk(paths.distRoot)) {
-    if (file.endsWith(".html")) texts.push(fs.readFileSync(file, "utf8"));
-  }
-  const codepoints = charsetFromTexts(texts);
-  const charsetHash = hash(codepoints.join(","));
-
-  /** @type {SubsetJob[]} */
-  const pending = [];
-  /** @type {FontRef[]} */
-  const waiting = [];
-  /** @type {string[]} Project-relative paths of fonts with uncached work, for the absent-toolchain hint. */
-  const needingTools = [];
   /** Sources whose subset landed in dist this build (cache or fresh). */
   const emitted = new Set();
 
-  /**
-   * Materialize one subset: copy it from the cache to its served path.
-   * @param {FontRef} ref
-   */
-  const emitSubset = (ref) => {
-    fs.mkdirSync(path.dirname(ref.subsetDist), { recursive: true });
-    fs.copyFileSync(/** @type {string} */ (ref.cacheFile), ref.subsetDist);
-    emitted.add(ref.source);
-  };
-
-  for (const ref of fonts.values()) {
-    /** @type {Uint8Array} */
-    let bytes;
-    try {
-      bytes = fs.readFileSync(ref.source);
-    } catch {
-      hint(
-        `no woff2 subset for ${relPosix(paths, ref.source)} — the file could not be read. ` +
-          "The original font ships as-is."
-      );
-      continue;
+  if (fonts.size > 0) {
+    // Pass 2: the charset — the base set plus every code point in the emitted
+    // pages. The scan reads the final HTML, so non-latin content flows into the
+    // union automatically; over-inclusion from markup is impossible to notice
+    // (tags are ASCII, which the base set already carries).
+    /** @type {string[]} */
+    const texts = [];
+    for (const file of walk(paths.distRoot)) {
+      if (file.endsWith(".html")) texts.push(fs.readFileSync(file, "utf8"));
     }
-    ref.cacheFile = path.join(cacheDir, `${hash(bytes)}-${charsetHash}.woff2`);
-    if (fs.existsSync(ref.cacheFile)) {
-      emitSubset(ref);
-      stats.cached++;
-    } else {
-      pending.push({ source: ref.source, out: ref.cacheFile });
-      waiting.push(ref);
-      needingTools.push(relPosix(paths, ref.source));
+    const codepoints = charsetFromTexts(texts);
+    const charsetHash = hash(codepoints.join(","));
+
+    /** @type {SubsetJob[]} */
+    const pending = [];
+    /** @type {FontRef[]} */
+    const waiting = [];
+    /** @type {string[]} Project-relative paths of fonts with uncached work, for the absent-toolchain hint. */
+    const needingTools = [];
+
+    /**
+     * Materialize one subset: copy it from the cache to its served path.
+     * @param {FontRef} ref
+     */
+    const emitSubset = (ref) => {
+      fs.mkdirSync(path.dirname(ref.subsetDist), { recursive: true });
+      fs.copyFileSync(/** @type {string} */ (ref.cacheFile), ref.subsetDist);
+      emitted.add(ref.source);
+    };
+
+    for (const ref of fonts.values()) {
+      /** @type {Uint8Array} */
+      let bytes;
+      try {
+        bytes = fs.readFileSync(ref.source);
+      } catch {
+        hint(
+          `no woff2 subset for ${relPosix(paths, ref.source)} — the file could not be read. ` +
+            "The original font ships as-is."
+        );
+        continue;
+      }
+      ref.cacheFile = path.join(cacheDir, `${hash(bytes)}-${charsetHash}.woff2`);
+      if (fs.existsSync(ref.cacheFile)) {
+        emitSubset(ref);
+        stats.cached++;
+      } else {
+        pending.push({ source: ref.source, out: ref.cacheFile });
+        waiting.push(ref);
+        needingTools.push(relPosix(paths, ref.source));
+      }
     }
-  }
 
-  if (pending.length > 0) {
-    const result = runJobs({ charset: codepoints, jobs: pending });
-    if (result.unavailable) {
-      stats.unavailable = true;
-      hint(
-        `${needingTools.length} font${needingTools.length === 1 ? "" : "s"} could be subsetted ` +
-          `to woff2 (${needingTools.join(", ")}). Run \`npm i -D harfbuzzjs wawoff2\` ` +
-          "to subset fonts at build time."
-      );
-    } else {
-      const failed = new Map(result.failed.map((f) => [f.file, f.error]));
-      for (const ref of waiting) {
-        const error = failed.get(ref.source);
-        if (error !== undefined) {
-          hint(
-            `no woff2 subset for ${relPosix(paths, ref.source)} — the font could not be ` +
-              `subsetted (${error}). The original font ships as-is.`
-          );
-          continue;
+    if (pending.length > 0) {
+      const result = runJobs({ charset: codepoints, jobs: pending });
+      if (result.unavailable) {
+        stats.unavailable = true;
+        hint(
+          `${needingTools.length} font${needingTools.length === 1 ? "" : "s"} could be subsetted ` +
+            `to woff2 (${needingTools.join(", ")}). Run \`npm i -D harfbuzzjs wawoff2\` ` +
+            "to subset fonts at build time."
+        );
+      } else {
+        const failed = new Map(result.failed.map((f) => [f.file, f.error]));
+        for (const ref of waiting) {
+          const error = failed.get(ref.source);
+          if (error !== undefined) {
+            hint(
+              `no woff2 subset for ${relPosix(paths, ref.source)} — the font could not be ` +
+                `subsetted (${error}). The original font ships as-is.`
+            );
+            continue;
+          }
+          emitSubset(ref);
+          stats.subsetted++;
         }
-        emitSubset(ref);
-        stats.subsetted++;
       }
     }
-  }
 
-  // Pass 3: rewrite the emitted CSS. Only stylesheets that reference a
-  // successfully subsetted font change; everything else is untouched, and the
-  // source .skin files are never written.
-  if (emitted.size > 0) {
-    /** @type {Map<string, string>} url as written in the CSS → subset URL */
-    const subsetByUrl = new Map();
-    for (const url of occurrences) {
-      const resolved = resolveFontUrl(paths, url);
-      if (resolved && emitted.has(resolved.source)) subsetByUrl.set(url, resolved.subsetUrl);
-    }
-    for (const file of cssFiles) {
-      const css = fs.readFileSync(file, "utf8");
-      const rewritten = rewriteFontFaceCss(css, subsetByUrl);
-      if (rewritten !== css) fs.writeFileSync(file, rewritten);
+    // Pass 3: rewrite the emitted CSS. Only stylesheets that reference a
+    // successfully subsetted font change; everything else is untouched, and the
+    // source .skin files are never written.
+    if (emitted.size > 0) {
+      /** @type {Map<string, string>} url as written in the CSS → subset URL */
+      const subsetByUrl = new Map();
+      for (const url of occurrences) {
+        const resolved = resolveFontUrl(paths, url);
+        if (resolved && emitted.has(resolved.source)) subsetByUrl.set(url, resolved.subsetUrl);
+      }
+      for (const file of cssFiles) {
+        const css = fs.readFileSync(file, "utf8");
+        const rewritten = rewriteFontFaceCss(css, subsetByUrl);
+        if (rewritten !== css) fs.writeFileSync(file, rewritten);
+      }
     }
   }
 
+  // Pass 4: preload links. Every emitted page gets one
+  // `<link rel="preload" as="font" crossorigin>` per project font its OWN
+  // linked stylesheets declare, right after the last stylesheet link — the URL
+  // the page's CSS leads with (the subset woff2 when it exists, the original
+  // otherwise). Pages loading no project fonts stay byte-identical.
+  injectFontPreloads(paths, cssRefs, emitted);
+
   return stats;
 }
 
@@ -394,23 +462,193 @@ function fontUrlsInCss(css) {
   return urls;
 }
 
+/**
+ * Pass 4: inject font preload links into every emitted page. Each page
+ * preloads exactly the fonts its own linked stylesheets declare — the subset
+ * woff2 when subsetting emitted one, the original project font URL otherwise
+ * (toolchain absent, font skipped, or source already woff2) — and nothing
+ * else: a page whose stylesheets carry no project font stays byte-identical.
+ * @param {Paths} paths
+ * @param {Map<string, PreloadRef[]>} cssRefs Stylesheet → its project fonts.
+ * @param {Set<string>} emitted Sources whose subset landed in dist this build.
+ * @returns {void}
+ */
+function injectFontPreloads(paths, cssRefs, emitted) {
+  // The preload list per stylesheet: the URL its rewritten CSS leads with,
+  // deduped (a font referenced twice, and the subset reference a previous
+  // build's rewrite added beside the original, collapse to one link).
+  /** @type {Map<string, PreloadFont[]>} */
+  const perCss = new Map();
+  for (const [cssFile, refs] of cssRefs) {
+    /** @type {PreloadFont[]} */
+    const list = [];
+    /** @type {Set<string>} */
+    const seen = new Set();
+    for (const ref of refs) {
+      const href = ref.subsetUrl && emitted.has(ref.source) ? ref.subsetUrl : ref.url;
+      if (seen.has(href)) continue;
+      seen.add(href);
+      list.push({ href, type: fontMimeType(href) });
+    }
+    perCss.set(cssFile, list);
+  }
+
+  for (const file of walk(paths.distRoot)) {
+    if (!file.endsWith(".html")) continue;
+    const html = fs.readFileSync(file, "utf8");
+    /** @type {PreloadFont[]} */
+    const preloads = [];
+    /** @type {Set<string>} */
+    const seen = new Set();
+    for (const href of stylesheetHrefs(html)) {
+      const cssFile = resolveDistCss(paths.distRoot, href);
+      if (!cssFile) continue;
+      for (const font of perCss.get(cssFile) ?? []) {
+        if (seen.has(font.href)) continue;
+        seen.add(font.href);
+        preloads.push(font);
+      }
+    }
+    const rewritten = injectPreloadLinks(html, preloads);
+    if (rewritten !== html) fs.writeFileSync(file, rewritten);
+  }
+}
+
+/**
+ * Inject one `<link rel="preload" href="…" as="font" type="…" crossorigin>`
+ * per font, immediately after the LAST stylesheet link in the head (after the
+ * favicon link when the page has no stylesheet link, and not at all when it
+ * has neither). `crossorigin` is mandatory: font fetches are always CORS-mode,
+ * even same-origin, so a preload without it downloads the font twice.
+ * Idempotent — a preload already present (an earlier pass over the same dist)
+ * is never duplicated.
+ * @param {string} html The emitted page.
+ * @param {PreloadFont[]} preloads The fonts to preload, in order.
+ * @returns {string} The page, unchanged when there is nothing new to inject.
+ */
+export function injectPreloadLinks(html, preloads) {
+  const fresh = preloads.filter((font) => !html.includes(`rel="preload" href="${font.href}"`));
+  if (fresh.length === 0) return html;
+  const tags = fresh.map(
+    (font) => `  <link rel="preload" href="${font.href}" as="font" type="${font.type}" crossorigin>`
+  );
+  let anchorEnd = -1;
+  for (const match of html.matchAll(LINK_TAG)) {
+    if (/\brel="stylesheet"/.test(match[0])) anchorEnd = match.index + match[0].length;
+  }
+  if (anchorEnd === -1) {
+    for (const match of html.matchAll(LINK_TAG)) {
+      if (/\brel="icon"/.test(match[0])) {
+        anchorEnd = match.index + match[0].length;
+        break;
+      }
+    }
+  }
+  if (anchorEnd === -1) return html;
+  return `${html.slice(0, anchorEnd)}\n${tags.join("\n")}${html.slice(anchorEnd)}`;
+}
+
+/**
+ * The hrefs of every `<link rel="stylesheet">` in a page, in document order.
+ * @param {string} html
+ * @returns {string[]}
+ */
+function stylesheetHrefs(html) {
+  /** @type {string[]} */
+  const hrefs = [];
+  for (const match of html.matchAll(LINK_TAG)) {
+    if (!/\brel="stylesheet"/.test(match[0])) continue;
+    const href = /\bhref="([^"]*)"/.exec(match[0]);
+    if (href) hrefs.push(href[1]);
+  }
+  return hrefs;
+}
+
+/**
+ * Resolve a stylesheet href from an emitted page to its dist file, or null
+ * when it cannot name one (remote, protocol-relative, an un-decodable or
+ * escaping path, or simply not a .css file). The file need not exist — the
+ * caller's map lookup is the existence check.
+ * @param {string} distRoot
+ * @param {string} href
+ * @returns {string | null}
+ */
+function resolveDistCss(distRoot, href) {
+  if (!href.startsWith("/") || href.startsWith("//")) return null;
+  const clean = href.split(/[?#]/)[0];
+  if (!clean.endsWith(".css")) return null;
+  /** @type {string} */
+  let decoded;
+  try {
+    decoded = decodeURIComponent(clean);
+  } catch {
+    return null;
+  }
+  const file = path.normalize(path.join(distRoot, decoded));
+  if (!file.startsWith(distRoot + path.sep)) return null;
+  return file;
+}
+
+/**
+ * The preload `type` for a font URL, from its extension.
+ * @param {string} href
+ * @returns {string}
+ */
+function fontMimeType(href) {
+  const ext = path.posix.extname(href.split(/[?#]/)[0]).toLowerCase();
+  return FONT_MIME[ext] ?? "font/woff2";
+}
+
 /**
  * Resolve a url() target from an emitted `@font-face` to the project font file
  * it names, or null when it is not a subset candidate: anything not
  * leading-slash (remote, protocol-relative, `data:`, relative), a non-subsettable
  * extension (already-woff2 included), an un-decodable or escaping path, a
  * symlink (whose target could live anywhere on disk, whatever the link's own
- * path says), or a file that does not exist. `/__wd/media/<rel>` maps to the
- * shelf; every other absolute path maps to `site/pages`.
+ * path says), or a file that does not exist.
  * @param {Paths} paths
  * @param {string} url The raw url() target.
  * @returns {FontRef | null}
  */
 function resolveFontUrl(paths, url) {
+  return resolveProjectFont(paths, url, SUBSETTABLE_EXTENSIONS);
+}
+
+/**
+ * The preload-only variant: an already-woff2 project font is never subsetted,
+ * but it is still a font the page loads locally, so it earns a preload of its
+ * own URL. Same project-local rules as resolveFontUrl.
+ * @param {Paths} paths
+ * @param {string} url The raw url() target.
+ * @returns {PreloadRef | null}
+ */
+function resolveWoff2FontUrl(paths, url) {
+  const ref = resolveProjectFont(paths, url, WOFF2_ONLY);
+  return ref ? { url: ref.url, source: ref.source, subsetUrl: null } : null;
+}
+
+/**
+ * The shared project-local resolution behind resolveFontUrl and
+ * resolveWoff2FontUrl. `/__wd/media/<rel>` maps to the shelf; every other
+ * absolute path maps to `site/pages`. A symlink is never project-local,
+ * matching the asset-copy convention (`emitPageAssets` skips them entirely,
+ * and so does the image pre-pass): the lexical containment check reads the
+ * path as WRITTEN, so a link sitting inside the project could point anywhere
+ * on disk and the target's bytes would be read and published as a subset. An
+ * ancestor directory can be a symlink with the file itself plain, so the
+ * canonical (realpath) containment check `@include` uses runs too — a font
+ * whose real path escapes site/pages and site/_ is simply "not project-local"
+ * here.
+ * @param {Paths} paths
+ * @param {string} url The raw url() target.
+ * @param {Set<string>} extensions The extensions accepted by the caller.
+ * @returns {FontRef | null}
+ */
+function resolveProjectFont(paths, url, extensions) {
   if (!url.startsWith("/") || url.startsWith("//")) return null;
   const clean = url.split(/[?#]/)[0];
   const ext = path.posix.extname(clean).toLowerCase();
-  if (!SUBSETTABLE_EXTENSIONS.has(ext)) return null;
+  if (!extensions.has(ext)) return null;
   /** @type {string} */
   let decoded;
   try {
@@ -424,14 +662,6 @@ function resolveFontUrl(paths, url) {
   const source = path.normalize(path.join(base, rel));
   if (!source.startsWith(base + path.sep)) return null;
   if (!fs.existsSync(source)) return null;
-  // Symlinks are never subsetted, matching the asset-copy convention
-  // (`emitPageAssets` skips them entirely, and so does the image pre-pass):
-  // the lexical containment check above reads the path as WRITTEN, so a link
-  // sitting inside the project could point anywhere on disk and the target's
-  // bytes would be read and published as a subset. An ancestor directory can
-  // be a symlink with the file itself plain, so the canonical (realpath)
-  // containment check `@include` uses runs too — a font whose real path
-  // escapes site/pages and site/_ is simply "not project-local" here.
   if (fs.lstatSync(source).isSymbolicLink()) return null;
   if (!isAllowedInclude(source, paths, fsReader())) return null;
   const subsetUrl = `${clean.slice(0, clean.length - ext.length)}-subset.woff2`;