@webjsdev/server 0.8.62 → 0.8.64

package/src/ssr/head.js

@@ -0,0 +1,857 @@
+import { basePath, buildImportMap, importMapTag, vendorPreconnectOrigins } from '../importmap.js';
+import { withBasePath } from '../base-path.js';
+import { escapeAttr, escapeHtml } from './escape.js';
+import { withAssetHash } from '../asset-hash.js';
+import { jsonForScriptTag } from '../script-tag-json.js';
+import { vendorIntegrityFor } from '../importmap.js';
+import { publicEnvShim } from './env-shim.js';
+import { clientRouterEnabled } from './client-router-flag.js';
+
+// Which icon metadata ROUTES the app has (`app/icon.*`, `app/apple-icon.*`).
+// Set at boot and on each route rebuild from the route table, the same shape
+// as setClientRouterEnabled, so no opt has to thread through every render
+// path. Empty by default, which keeps an app that declares its icons (or has
+// neither route) byte-identical.
+//
+// This sits in head.js rather than in a module of its own the way the
+// client-router flag does: `wrapHead` is the only reader, and module state
+// belongs with the code that uses and writes it. The flag moved out only
+// because it has a second reader in render.js.
+/** @type {{ icon: boolean, apple: boolean }} */
+let _metadataIconRoutes = { icon: false, apple: false };
+
+/**
+ * Record the icon metadata routes the app defines.
+ *
+ * @param {Iterable<{ stem: string }> | null | undefined} metadataRoutes
+ *   The route table's `metadataRoutes`, or nullish to clear.
+ */
+export function setMetadataIconRoutes(metadataRoutes) {
+  const stems = new Set();
+  for (const r of metadataRoutes || []) if (r && r.stem) stems.add(r.stem);
+  _metadataIconRoutes = { icon: stems.has('icon'), apple: stems.has('apple-icon') };
+}
+
+/**
+ * The implicit `metadata.icons` an app's icon routes stand for, or null when
+ * it has none. Base-path prefixed, because that is where the routes are
+ * SERVED: the listener strips the base path before matching, so under
+ * `webjs.basePath` the route answers at `<basePath>/icon`. A user-authored
+ * `icons` URL is deliberately left alone (it may be cross-origin, and the
+ * author writes the path they mean), so only these framework-emitted ones
+ * are prefixed.
+ *
+ * No `type` or `sizes` is emitted. A metadata route picks its own content
+ * type at request time, which is the reason to use one, so declaring a type
+ * here could contradict the bytes; and `sizes` is unknowable without reading
+ * the response. Both are optional in HTML, and a browser sniffs the served
+ * content type.
+ *
+ * @returns {{ icon?: string, apple?: string } | null}
+ */
+function autoMetadataRouteIcons() {
+  const { icon, apple } = _metadataIconRoutes;
+  if (!icon && !apple) return null;
+  const bp = basePath();
+  /** @type {{ icon?: string, apple?: string }} */
+  const out = {};
+  if (icon) out.icon = withBasePath('/icon', bp);
+  if (apple) out.apple = withBasePath('/apple-icon', bp);
+  return out;
+}
+
+/**
+ * HTML-safe-escape a JSON string for embedding inside a
+ * `<script type="application/ld+json">` element.
+ *
+ * This is NOT the HTML-entity escaper (escapeHtml / escapeAttr). A
+ * JSON parser reads the raw character, so turning `<` into `&lt;`
+ * would CORRUPT the JSON. Instead we emit the Unicode escape form
+ * (`<`), which a JSON parser decodes back to the original
+ * character while making the literal byte sequence `</script>`
+ * impossible to form in the served HTML. So the embedded data parses
+ * back to the author's exact object, AND a value containing
+ * `</script><img onerror=...>` can never break out of the script tag.
+ *
+ * U+2028 / U+2029 are escaped too: they are valid inside a JSON
+ * string but are line terminators in HTML/JS contexts, and some
+ * consumers choke on them. Escaping keeps the block robust.
+ *
+ * @param {string} json  the `JSON.stringify` output
+ * @returns {string}
+ */
+export function escapeJsonLd(str) {
+  return String(str)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/**
+ * Serialize one schema.org object into a `<script type="application/ld+json">`
+ * block, HTML-safe-escaped via escapeJsonLd. Fails SAFE: a non-object
+ * input, or a circular reference that makes JSON.stringify throw, is
+ * skipped (returns the empty string) with a one-line warn, never breaking
+ * the whole render.
+ *
+ * @param {unknown} obj
+ * @returns {string}  the script tag, or '' to skip this element
+ */
+export function jsonLdScript(obj) {
+  if (!obj || typeof obj !== 'object') return '';
+  try {
+    const json = JSON.stringify(obj);
+    if (typeof json !== 'string') return '';
+    return `<script type="application/ld+json">${escapeJsonLd(json)}</script>`;
+  } catch (err) {
+    console.warn('[webjs] metadata.jsonLd: skipped an entry that could not be serialized:', err && err.message);
+    return '';
+  }
+}
+
+/** Re-exports for unit testing. */
+export const _escapeJsonLd = escapeJsonLd;
+export const _jsonLdScript = jsonLdScript;
+
+/**
+ * Decide whether a `<link rel="modulepreload">` href needs a
+ * `crossorigin="anonymous"` attribute. True for absolute URLs with
+ * an http(s) scheme (vendor packages from jspm.io etc.); false for
+ * same-origin paths like `/__webjs/core/index.js`. Browsers require
+ * crossorigin on cross-origin module preload, else the preload is
+ * wasted or double-fetched. Same-origin URLs must NOT have it for
+ * the same reason in reverse.
+ *
+ * Exported for tests; production callers use it via documentParts.
+ *
+ * @param {string} url
+ * @returns {string}  either ` crossorigin="anonymous"` or empty
+ */
+export function preloadCrossOriginAttr(url) {
+  return /^https?:\/\//i.test(url) ? ' crossorigin="anonymous"' : '';
+}
+
+/**
+ * Look up the SRI integrity hash for a vendor URL and format it as a
+ * `integrity="sha384-..."` attribute. Empty string for URLs without a
+ * known hash (framework files, user code, vendor URLs in live-API
+ * mode without a pin file).
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function integrityAttr(url) {
+  const hash = vendorIntegrityFor(url);
+  // Belt and suspenders: readPinFile already validates the integrity
+  // value end-to-end against /^sha(256|384|512)-[A-Za-z0-9+/=]+$/, so
+  // a valid hash has no HTML-special chars and escapeAttr is a no-op.
+  // But emission goes through the same attribute-injection-safe path
+  // as everything else in the SSR pipeline so a future regression in
+  // the validator doesn't bypass it.
+  return hash ? ` integrity="${escapeAttr(hash)}"` : '';
+}
+
+/**
+ * Strip leading head-bound tags (<script>, <style>, <link>) from a body
+ * string. Returns the collected tags + the remaining body. Mirrors what
+ * `hoistHeadTags` does but takes/returns plain strings (no head input)
+ * so it can be used with a user-provided <head>.
+ *
+ * @param {string} bodyHtml
+ * @returns {{ tags: string[], body: string }}
+ */
+export function collectHoistedHeadTags(bodyHtml) {
+  const tags = [];
+  // <script>…</script> and <style>…</style> are paired; <link …> and <meta …>
+  // are void. A plain HTML comment (<!-- … -->) is consumed but NOT hoisted, so
+  // a comment interleaved with head-bound tags (e.g. "<!-- Self-hosted fonts -->"
+  // between a favicon <link> and the stylesheet <link>) does not terminate
+  // the leading run and strand the stylesheet in <body>, which caused FOUC
+  // because a <link rel="stylesheet"> in <body> is not reliably
+  // render-blocking (#406). A <meta …> is treated the same way for the same
+  // reason: a <meta name="color-scheme"> between the theme <script> and the
+  // stylesheet <link> would otherwise terminate the run and strand the
+  // stylesheet AND a <link rel="icon"> in <body> (a favicon in <body> is
+  // ignored by browsers, so the icon silently never renders). The `(?!/?wj:)`
+  // guard exempts client-router markers (<!--wj:children:…-->,
+  // <!--/wj:children-->) so a layout that renders children directly after its
+  // head tags still terminates the run there rather than swallowing the marker.
+  // The void-tag matchers are QUOTE-AWARE ((?:[^>"']|"[^"]*"|'[^']*')*): a `>`
+  // inside a quoted attribute value (a description meta like
+  // content="Guides > API") must not terminate the tag early, which would hoist
+  // a truncated tag, leak the remainder as visible body text, and strand the
+  // stylesheet (the #406 FOUC this hoist exists to prevent).
+  const re =
+    /^\s*(<!--(?!\/?wj:)[\s\S]*?-->|<script[\s>][\s\S]*?<\/script>|<style[\s>][\s\S]*?<\/style>|<link\b(?:[^>"']|"[^"]*"|'[^']*')*>|<meta\b(?:[^>"']|"[^"]*"|'[^']*')*>)/i;
+  let remaining = bodyHtml;
+  // `body` only advances to just-past the LAST hoisted head tag. Comments
+  // are scanned through (so they don't terminate the run) but a comment that
+  // trails the final head tag stays in the body rather than being dropped.
+  let body = bodyHtml;
+  let m;
+  while ((m = re.exec(remaining)) !== null) {
+    const token = m[1];
+    remaining = remaining.slice(m[0].length);
+    if (!token.startsWith('<!--')) {
+      tags.push(token);
+      body = remaining;
+    }
+  }
+  return { tags, body };
+}
+
+/**
+ * Produce the `<!doctype…><body>` prefix. If `streaming` is true, injects
+ * the tiny client-side resolver that swaps Suspense fallback nodes for
+ * streamed-in real content.
+ *
+ * Also emits `<link rel="modulepreload">` for every component that rendered
+ * (breaks the ES-module waterfall without a bundler) and any user-declared
+ * `metadata.preload` entries.
+ *
+ * @param {{ metadata: Record<string,any>, moduleUrls: string[], dev: boolean, streaming: boolean, preloads?: string[], lazyComponents?: Record<string, string>, nonce?: string }} opts
+ */
+/**
+ * Extract leading `<script>`, `<style>`, and `<link>` tags from the body
+ * HTML and hoist them into `<head>`. Ensures blocking scripts (e.g.
+ * Tailwind runtime, theme bootstrap) run before any body content renders,
+ * and that `<link rel="icon">` / `<link rel="stylesheet">` land where
+ * browsers reliably honour them.
+ *
+ * @param {string} headHtml
+ * @param {string} bodyHtml
+ * @returns {{ head: string, body: string }}
+ */
+export function hoistHeadTags(headHtml, bodyHtml) {
+  // Shares the leading-run scanner (comment-skipping included) with the
+  // streaming path so both hoist identically. See collectHoistedHeadTags.
+  const { tags: hoisted, body: remaining } = collectHoistedHeadTags(bodyHtml);
+  if (!hoisted.length) return { head: headHtml, body: bodyHtml };
+  const newHead = headHtml.replace('</head>', hoisted.join('\n') + '\n</head>');
+  return { head: newHead, body: remaining };
+}
+
+/** Internal helper re-exported for unit testing. */
+export const _hoistHeadTags = hoistHeadTags;
+
+/**
+ * Serialize a Next.js-shaped viewport object into the comma-separated
+ * `content` string the meta tag expects. Recognised fields:
+ *   width, height, initialScale, minimumScale, maximumScale,
+ *   userScalable, viewportFit, interactiveWidget.
+ * Other fields (themeColor, colorScheme) live on their own meta tags
+ * and are handled by the caller: skipped here.
+ *
+ * @param {Record<string, unknown>} v
+ * @returns {string}
+ */
+export function serializeViewport(v) {
+  const parts = [];
+  /** @param {string} key @param {string} prop */
+  const push = (key, prop) => {
+    if (v[prop] !== undefined && v[prop] !== null && v[prop] !== '') {
+      parts.push(`${key}=${v[prop]}`);
+    }
+  };
+  push('width', 'width');
+  push('height', 'height');
+  push('initial-scale', 'initialScale');
+  push('minimum-scale', 'minimumScale');
+  push('maximum-scale', 'maximumScale');
+  if (v.userScalable === false) parts.push('user-scalable=no');
+  else if (v.userScalable === true) parts.push('user-scalable=yes');
+  push('viewport-fit', 'viewportFit');
+  push('interactive-widget', 'interactiveWidget');
+  return parts.join(',');
+}
+
+export function wrapHead(opts) {
+  // CSP nonce: if provided, all inline <script> tags get nonce="…" so they
+  // pass strict Content-Security-Policy headers. The nonce is extracted from
+  // the request's CSP header by the caller.
+  const n = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
+  // Sub-path deployment (issue #256): the boot script's per-route module
+  // specifiers and the dev reload `src` are framework-emitted same-origin
+  // absolute URLs, so prefix them with the base path (a no-op when empty).
+  // The lazy-loader import is a BARE specifier resolved through the importmap
+  // (whose target is already base-path-prefixed in importmap.js), so it is
+  // NOT prefixed here. The base path is the one set at boot via setBasePath
+  // (read from importmap.js's module state), the same value the importmap
+  // targets were prefixed with, so the boot specifiers and the map agree.
+  const bp = basePath();
+  // Content-hash asset URLs (issue #243): after base-path-prefixing, append
+  // `?v=<hash>` to a same-origin module specifier for immutable caching. A
+  // no-op in dev (so the boot script is byte-identical) and for a bare/
+  // cross-origin specifier; same compose order as the importmap targets
+  // (basePath then `?v`).
+  const fp = (u) => withAssetHash(withBasePath(u, bp), bp);
+
+  const moduleUrls = opts.moduleUrls;
+  const imports = moduleUrls
+    .map((u) => `import ${jsonForScriptTag(fp(u))};`)
+    .join('\n');
+
+  const rawLazyEntries = opts.lazyComponents && Object.keys(opts.lazyComponents).length
+    ? opts.lazyComponents
+    : null;
+  // The lazy map's values are same-origin module URLs `observeLazy` will
+  // dynamically import, so prefix them with the base path too (no-op when
+  // empty).
+  // The lazy map's values are same-origin module URLs `observeLazy` will
+  // dynamically import, so base-path-prefix AND content-hash them (#243), the
+  // same as the eager boot specifiers. `fp` is a pure no-op in dev and at the
+  // root mount with fingerprinting off, so the mapped map equals the raw one
+  // byte-for-byte there; only prod fingerprinting / a sub-path mount changes it.
+  const lazyEntries = rawLazyEntries
+    ? Object.fromEntries(
+        Object.entries(rawLazyEntries).map(([tag, u]) => [tag, fp(u)]),
+      )
+    : rawLazyEntries;
+  const lazyBoot = lazyEntries
+    ? `\nimport { observeLazy } from '@webjsdev/core/lazy-loader';\nobserveLazy(${jsonForScriptTag(lazyEntries)});`
+    : '';
+
+  const boot = (imports || lazyBoot) ? `<script type="module"${n}>\n${imports}${lazyBoot}\n</script>` : '';
+  const reload = opts.dev
+    ? `<script type="module"${n} src="${escapeAttr(withBasePath('/__webjs/reload.js', bp))}"></script>`
+    : '';
+  const suspenseBoot = opts.streaming
+    ? `<script${n}>(function(){` +
+      `function r(id){var t=document.querySelector('template[data-webjs-resolve="'+id+'"]');` +
+      `var b=document.getElementById(id);if(t&&b){b.replaceWith(t.content.cloneNode(true));t.remove();}}` +
+      `window.__webjsResolve=r;` +
+      `if(typeof MutationObserver!=='undefined'){` +
+      `new MutationObserver(function(ms){ms.forEach(function(m){m.addedNodes.forEach(function(n){` +
+      `if(n.nodeType===1&&n.tagName==='TEMPLATE'&&n.dataset.webjsResolve){r(n.dataset.webjsResolve);}` +
+      `});});}).observe(document.documentElement,{childList:true,subtree:true});}` +
+      `})()</script>`
+    : '';
+
+  const m = opts.metadata || {};
+  const metaTags = [];
+  // linkTags is populated by both the metadata emission below (icons,
+  // alternates, archives, etc.) AND by the preload block further down.
+  // Hoist the declaration so the metadata block can push into it.
+  const linkTags = [];
+  // scriptTags collects JSON-LD structured-data blocks (see m.jsonLd below).
+  const scriptTags = [];
+
+  // Tiny URL resolver against metadataBase. If metadataBase is set and a
+  // value looks like a relative URL (no scheme, no `//` prefix), resolve
+  // it. Otherwise return as-is. Used by og:image, twitter:image,
+  // alternates.canonical / languages / media.
+  const base = typeof m.metadataBase === 'string' ? m.metadataBase : '';
+  /** @param {unknown} v */
+  const absUrl = (v) => {
+    const s = String(v);
+    if (!base) return s;
+    if (/^https?:\/\//i.test(s) || s.startsWith('//') || s.startsWith('data:')) return s;
+    try {
+      return new URL(s, base).toString();
+    } catch {
+      return s;
+    }
+  };
+
+  if (m.description) metaTags.push(`<meta name="description" content="${escapeAttr(m.description)}">`);
+
+  // viewport: support string form (legacy), `metadata.viewport` object form,
+  // and the new Next.js 14+ `export const viewport = { … }` shape captured
+  // into `_viewport` by collectMetadata.
+  let viewportStr = '';
+  if (typeof m.viewport === 'string') {
+    viewportStr = m.viewport;
+  } else if (m.viewport && typeof m.viewport === 'object') {
+    viewportStr = serializeViewport(m.viewport);
+  } else if (m._viewport && typeof m._viewport === 'object') {
+    viewportStr = serializeViewport(m._viewport);
+  }
+  metaTags.push(`<meta name="viewport" content="${escapeAttr(viewportStr || 'width=device-width,initial-scale=1')}">`);
+
+  if (m.themeColor) metaTags.push(`<meta name="theme-color" content="${escapeAttr(m.themeColor)}">`);
+  if (m.colorScheme) metaTags.push(`<meta name="color-scheme" content="${escapeAttr(m.colorScheme)}">`);
+
+  // robots: { index, follow, googleBot, etc. }
+  if (m.robots) {
+    if (typeof m.robots === 'string') {
+      metaTags.push(`<meta name="robots" content="${escapeAttr(m.robots)}">`);
+    } else if (typeof m.robots === 'object') {
+      const parts = [];
+      if (m.robots.index === false) parts.push('noindex');
+      else if (m.robots.index === true) parts.push('index');
+      if (m.robots.follow === false) parts.push('nofollow');
+      else if (m.robots.follow === true) parts.push('follow');
+      if (m.robots.noarchive) parts.push('noarchive');
+      if (m.robots.nosnippet) parts.push('nosnippet');
+      if (m.robots.noimageindex) parts.push('noimageindex');
+      if (parts.length) {
+        metaTags.push(`<meta name="robots" content="${escapeAttr(parts.join(', '))}">`);
+      }
+      if (typeof m.robots.googleBot === 'string') {
+        metaTags.push(`<meta name="googlebot" content="${escapeAttr(m.robots.googleBot)}">`);
+      }
+    }
+  }
+
+  // keywords: string | string[]
+  if (m.keywords) {
+    const kws = Array.isArray(m.keywords) ? m.keywords.join(', ') : String(m.keywords);
+    if (kws) metaTags.push(`<meta name="keywords" content="${escapeAttr(kws)}">`);
+  }
+
+  // authors: Array<{ name, url? }> | { name, url? } | string
+  if (m.authors) {
+    const list = Array.isArray(m.authors) ? m.authors : [m.authors];
+    for (const a of list) {
+      if (!a) continue;
+      const name = typeof a === 'string' ? a : a.name;
+      if (!name) continue;
+      metaTags.push(`<meta name="author" content="${escapeAttr(name)}">`);
+      if (typeof a === 'object' && a.url) {
+        metaTags.push(`<link rel="author" href="${escapeAttr(absUrl(a.url))}">`);
+      }
+    }
+  }
+
+  // Singletons that map 1:1 to <meta name="…">.
+  for (const [field, metaName] of [
+    ['creator', 'creator'],
+    ['publisher', 'publisher'],
+    ['applicationName', 'application-name'],
+    ['generator', 'generator'],
+    ['referrer', 'referrer'],
+  ]) {
+    if (m[field]) {
+      metaTags.push(`<meta name="${metaName}" content="${escapeAttr(String(m[field]))}">`);
+    }
+  }
+  // ---- Long-tail metadata (the Next.js "everything else") ----
+
+  // appleWebApp: { capable, title, statusBarStyle, startupImage }
+  if (m.appleWebApp && typeof m.appleWebApp === 'object') {
+    if (m.appleWebApp.capable !== undefined) {
+      metaTags.push(
+        `<meta name="apple-mobile-web-app-capable" content="${m.appleWebApp.capable ? 'yes' : 'no'}">`,
+      );
+    }
+    if (m.appleWebApp.title) {
+      metaTags.push(`<meta name="apple-mobile-web-app-title" content="${escapeAttr(m.appleWebApp.title)}">`);
+    }
+    if (m.appleWebApp.statusBarStyle) {
+      metaTags.push(
+        `<meta name="apple-mobile-web-app-status-bar-style" content="${escapeAttr(m.appleWebApp.statusBarStyle)}">`,
+      );
+    }
+    // startupImage maps to <link rel="apple-touch-startup-image">.
+    if (m.appleWebApp.startupImage) {
+      const list = Array.isArray(m.appleWebApp.startupImage)
+        ? m.appleWebApp.startupImage
+        : [m.appleWebApp.startupImage];
+      for (const it of list) {
+        if (typeof it === 'string') {
+          linkTags.push(`<link rel="apple-touch-startup-image" href="${escapeAttr(absUrl(it))}">`);
+        } else if (it && it.url) {
+          const parts = [`rel="apple-touch-startup-image"`, `href="${escapeAttr(absUrl(it.url))}"`];
+          if (it.media) parts.push(`media="${escapeAttr(it.media)}"`);
+          linkTags.push(`<link ${parts.join(' ')}>`);
+        }
+      }
+    }
+  } else if (m.appleWebApp === true) {
+    metaTags.push(`<meta name="apple-mobile-web-app-capable" content="yes">`);
+  }
+
+  // formatDetection: { telephone, address, email, date, … }. All booleans.
+  // Disabled detection types append "type=no" to the content string.
+  if (m.formatDetection && typeof m.formatDetection === 'object') {
+    const parts = [];
+    for (const [k, v] of Object.entries(m.formatDetection)) {
+      if (v === false) parts.push(`${k}=no`);
+      else if (v === true) parts.push(`${k}=yes`);
+    }
+    if (parts.length) {
+      metaTags.push(`<meta name="format-detection" content="${escapeAttr(parts.join(', '))}">`);
+    }
+  }
+
+  // itunes: { appId, appArgument? }
+  if (m.itunes && typeof m.itunes === 'object' && m.itunes.appId) {
+    let content = `app-id=${m.itunes.appId}`;
+    if (m.itunes.appArgument) content += `, app-argument=${m.itunes.appArgument}`;
+    metaTags.push(`<meta name="apple-itunes-app" content="${escapeAttr(content)}">`);
+  }
+
+  for (const [field, metaName] of [
+    ['category', 'category'],
+    ['classification', 'classification'],
+    ['abstract', 'abstract'],
+  ]) {
+    if (m[field]) metaTags.push(`<meta name="${metaName}" content="${escapeAttr(String(m[field]))}">`);
+  }
+
+  // archives / assets / bookmarks: each is string | string[].
+  // Standard registered link relations.
+  for (const [field, rel] of [
+    ['archives', 'archives'],
+    ['assets', 'assets'],
+    ['bookmarks', 'bookmark'],
+  ]) {
+    if (m[field]) {
+      const list = Array.isArray(m[field]) ? m[field] : [m[field]];
+      for (const href of list) {
+        linkTags.push(`<link rel="${rel}" href="${escapeAttr(absUrl(href))}">`);
+      }
+    }
+  }
+
+  // `other` is the typed escape hatch for any arbitrary <meta name="…">
+  // entries Next.js (or future webjs) doesn't ship as a typed field.
+  // Values can be string, number, or string[] (emits multiple meta tags).
+  if (m.other && typeof m.other === 'object') {
+    for (const [name, v] of Object.entries(m.other)) {
+      const list = Array.isArray(v) ? v : [v];
+      for (const item of list) {
+        if (item == null) continue;
+        metaTags.push(`<meta name="${escapeAttr(name)}" content="${escapeAttr(String(item))}">`);
+      }
+    }
+  }
+
+  // verification: { google, yandex, yahoo, me }. Each is string OR string[].
+  // - google     → <meta name="google-site-verification">
+  // - yandex     → <meta name="yandex-verification">
+  // - yahoo      → <meta name="y_key">  (Yahoo's unusual canonical name)
+  // - me         → <meta name="me">     (IndieAuth / personal verification)
+  if (m.verification && typeof m.verification === 'object') {
+    const verifyKeys = {
+      google: 'google-site-verification',
+      yandex: 'yandex-verification',
+      yahoo: 'y_key',
+      me: 'me',
+    };
+    for (const [field, metaName] of Object.entries(verifyKeys)) {
+      const v = m.verification[field];
+      if (!v) continue;
+      const list = Array.isArray(v) ? v : [v];
+      for (const item of list) {
+        metaTags.push(`<meta name="${metaName}" content="${escapeAttr(String(item))}">`);
+      }
+    }
+    // `verification.other` allows arbitrary <meta name="…"> entries.
+    if (m.verification.other && typeof m.verification.other === 'object') {
+      for (const [name, v] of Object.entries(m.verification.other)) {
+        const list = Array.isArray(v) ? v : [v];
+        for (const item of list) {
+          metaTags.push(`<meta name="${escapeAttr(name)}" content="${escapeAttr(String(item))}">`);
+        }
+      }
+    }
+  }
+
+  if (m.openGraph && typeof m.openGraph === 'object') {
+    for (const [k, v] of Object.entries(m.openGraph)) {
+      const out = k === 'image' || k === 'url' ? absUrl(v) : String(v);
+      metaTags.push(`<meta property="og:${escapeAttr(k)}" content="${escapeAttr(out)}">`);
+    }
+  }
+
+  // Twitter card tags. Twitter falls back to og:* when these are absent
+  // but won't upgrade to summary_large_image without an explicit
+  // twitter:card entry.
+  if (m.twitter && typeof m.twitter === 'object') {
+    for (const [k, v] of Object.entries(m.twitter)) {
+      const out = k === 'image' ? absUrl(v) : String(v);
+      metaTags.push(`<meta name="twitter:${escapeAttr(k)}" content="${escapeAttr(out)}">`);
+    }
+  }
+
+  // Preload hints: page modules themselves + every discovered component
+  // module, then any custom `metadata.preload` entries (fonts, images, etc.)
+  // (linkTags array was declared earlier so the metadata block above can
+  // push icons / canonical / hreflang / archives / etc. into it.)
+  //
+  // Cross-origin URLs (vendor packages served from jspm.io etc.) MUST
+  // carry `crossorigin="anonymous"` on the preload link. Without it
+  // the browser either ignores the preload entirely or double-fetches
+  // (once for the preload as a non-CORS request, once for the actual
+  // module as a CORS request, defeating the optimization). Same-origin
+  // URLs get no attribute; adding `crossorigin=""` there would also
+  // double-fetch in some browsers because the preload becomes CORS
+  // but the import doesn't.
+  // CSP nonce on the preload link: under strict CSP (script-src
+  // 'nonce-...') the browser also gates modulepreload by the same
+  // policy. Without the attribute the preload is blocked and the
+  // import either falls back to a cold fetch or fails. Rails (via
+  // importmap-rails) applies nonce on every modulepreload tag for
+  // the same reason.
+  const noncePreload = opts.nonce ? ` nonce="${escapeAttr(opts.nonce)}"` : '';
+  // Core runtime modulepreload (#1118). Every module the boot imports pulls
+  // `@webjsdev/core`, but the boot script names only page and component URLs,
+  // so without this hint the browser discovers core only after one of those is
+  // fetched AND parsed: one full round trip into the load, which is exactly
+  // where the pre-boot click window lives on a cold, throttled connection.
+  //
+  // The href comes STRAIGHT from the importmap target (no `fp()` rewrite: the
+  // map's targets are already base-path-prefixed and content-hashed), so it is
+  // byte-identical to what the import resolves to. A differing href makes the
+  // browser treat the preload and the import as two resources and fetch core
+  // twice. That is why this copies the vendor loop below, not the module loop
+  // above. `vendorPreloadTargets` still excludes core deliberately; this hint
+  // is emitted from the head builder, not the vendor path.
+  //
+  // Gated on the boot actually shipping something. A fully elided page ships no
+  // boot module and must not be handed a preload for a runtime it never loads
+  // (#780), which also keeps it off `global-error.{js,ts}`, whose document is
+  // returned verbatim with no importmap and no boot script.
+  if (opts.moduleUrls.length || lazyEntries) {
+    const coreMap = buildImportMap();
+    const coreHref = coreMap.imports['@webjsdev/core'];
+    if (coreHref) {
+      const raw = coreMap.integrity ? coreMap.integrity[coreHref] : undefined;
+      const coreIntegrity = raw ? ` integrity="${escapeAttr(raw)}"` : '';
+      linkTags.push(
+        `<link rel="modulepreload" href="${escapeAttr(coreHref)}"` +
+        `${preloadCrossOriginAttr(coreHref)}${coreIntegrity}${noncePreload}>`,
+      );
+    }
+  }
+
+  // Sub-path deployment (issue #256): the modulepreload href is prefixed with
+  // the base path (a no-op when empty), but `crossorigin` / `integrity` are
+  // decided on the ORIGINAL url, so the integrity lookup still keys on the
+  // unprefixed map url and a cross-origin CDN url (never prefixed) keeps its
+  // crossorigin attribute.
+  // Content-hash (#243): the href additionally gets a `?v=<hash>` after the
+  // base-path prefix (a no-op in dev / for a cross-origin url), but
+  // `crossorigin` / `integrity` are still decided on the ORIGINAL url, so the
+  // integrity lookup keys on the unprefixed/unhashed map url and a cross-origin
+  // CDN url (never prefixed, never hashed) keeps its crossorigin attribute.
+  for (const url of opts.moduleUrls) {
+    linkTags.push(
+      `<link rel="modulepreload" href="${escapeAttr(fp(url))}"` +
+      `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
+    );
+  }
+  for (const url of opts.preloads || []) {
+    linkTags.push(
+      `<link rel="modulepreload" href="${escapeAttr(fp(url))}"` +
+      `${preloadCrossOriginAttr(url)}${integrityAttr(url)}${noncePreload}>`,
+    );
+  }
+  // Vendor modulepreload (#754): the npm CDN dependencies the page reaches,
+  // hinted up front to flatten the cross-origin waterfall. The href comes
+  // straight from the importmap target (byte-identical, no `fp()` rewrite, so
+  // the browser does not double-fetch) and carries the importmap's `integrity`.
+  // `preloadCrossOriginAttr` adds `crossorigin` for a cross-origin CDN url (a
+  // same-origin pinned `/__webjs/vendor/*` url gets none). Deduped against the
+  // app module/component preloads already emitted above.
+  const emittedPreloadHrefs = new Set([
+    ...opts.moduleUrls.map((u) => fp(u)),
+    ...(opts.preloads || []).map((u) => fp(u)),
+  ]);
+  for (const v of opts.vendorPreloads || []) {
+    if (emittedPreloadHrefs.has(v.href)) continue;
+    emittedPreloadHrefs.add(v.href);
+    const integrity = v.integrity ? ` integrity="${escapeAttr(v.integrity)}"` : '';
+    linkTags.push(
+      `<link rel="modulepreload" href="${escapeAttr(v.href)}"` +
+      `${preloadCrossOriginAttr(v.href)}${integrity}${noncePreload}>`,
+    );
+  }
+
+  if (Array.isArray(m.preload)) {
+    for (const p of m.preload) {
+      if (!p || !p.href) continue;
+      const attrs = Object.entries(p)
+        .map(([k, v]) => `${k}="${escapeAttr(String(v))}"`)
+        .join(' ');
+      linkTags.push(`<link rel="preload" ${attrs}>`);
+    }
+  }
+
+  // preconnect / dns-prefetch hints (issue #243). `metadata.preconnect` and
+  // `metadata.dnsPrefetch` each take a URL string, `{ url, crossorigin? }`, or
+  // an array of those. A preconnect warms DNS + TLS + TCP; dns-prefetch only
+  // resolves DNS (no crossorigin). The framework ALSO auto-emits ONE preconnect
+  // to the resolved vendor CDN origin for an unpinned cross-origin app, so the
+  // browser warms that connection before the importmap resolves. The author's
+  // declared origins are tracked so the auto one is not a duplicate.
+  /** @type {Set<string>} the origins the author already declared a preconnect to */
+  const declaredPreconnectOrigins = new Set();
+  /** @param {unknown} h @returns {{ url: string, crossorigin?: string|boolean } | null} */
+  const normalizeHint = (h) => {
+    if (typeof h === 'string') return h ? { url: h } : null;
+    if (h && typeof h === 'object' && typeof (/** @type {any} */ (h).url) === 'string') {
+      return /** @type {any} */ (h);
+    }
+    return null;
+  };
+  /** @param {unknown} value @returns {Array<{ url: string, crossorigin?: string|boolean }>} */
+  const toHints = (value) => {
+    if (value == null) return [];
+    const list = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const h of list) {
+      const n = normalizeHint(h);
+      if (n) out.push(n);
+    }
+    return out;
+  };
+  /** @param {string|boolean|undefined} co @returns {string} */
+  const crossoriginAttr = (co) => {
+    if (co === undefined || co === false) return '';
+    if (co === true || co === '') return ' crossorigin';
+    return ` crossorigin="${escapeAttr(String(co))}"`;
+  };
+  for (const h of toHints(m.preconnect)) {
+    try { declaredPreconnectOrigins.add(new URL(h.url).origin); } catch { declaredPreconnectOrigins.add(h.url); }
+    linkTags.push(`<link rel="preconnect" href="${escapeAttr(h.url)}"${crossoriginAttr(h.crossorigin)}>`);
+  }
+  for (const h of toHints(m.dnsPrefetch)) {
+    // dns-prefetch never carries crossorigin (it only resolves DNS).
+    linkTags.push(`<link rel="dns-prefetch" href="${escapeAttr(h.url)}">`);
+  }
+  // Auto vendor preconnect: warm the cross-origin vendor CDN connection for an
+  // unpinned app. Deduped against an author-declared preconnect to the same
+  // origin; emits none for a same-origin pinned app or one with no cross-origin
+  // vendors (vendorPreconnectOrigins returns []). crossorigin is required (the
+  // importmap fetches the module as a CORS request).
+  for (const origin of vendorPreconnectOrigins()) {
+    if (declaredPreconnectOrigins.has(origin)) continue;
+    linkTags.push(`<link rel="preconnect" href="${escapeAttr(origin)}" crossorigin>`);
+  }
+
+  // icons: { icon, apple, shortcut, other }. Each entry can be a string
+  // (URL), an object { url, sizes?, type? }, or an array of those.
+  //   - icon    → <link rel="icon">
+  //   - apple   → <link rel="apple-touch-icon">
+  //   - shortcut→ <link rel="shortcut icon">
+  //   - other   → <link rel="…" href="…"> using the entry's `rel` field
+  //
+  // With no `icons` declared, an `app/icon.*` / `app/apple-icon.*` metadata
+  // ROUTE is linked automatically (Next parity). Those routes served their
+  // bytes and nothing referenced them before, so writing the file that every
+  // other framework treats as "this is my favicon" produced a blank tab and no
+  // diagnostic. A declared `icons` SUPPRESSES the routes rather than merging
+  // with them, which is also what Next does: it merges static icon files only
+  // when the resolved metadata has no `icons` of its own. Suppressing matters
+  // here because the file is frequently a placeholder an app has outgrown, and
+  // an author who names their icons has said which ones they want.
+  const declaredOrRouteIcons = m.icons || autoMetadataRouteIcons();
+  if (declaredOrRouteIcons) {
+    const buckets = typeof declaredOrRouteIcons === 'string' || Array.isArray(declaredOrRouteIcons)
+      ? { icon: declaredOrRouteIcons }
+      : declaredOrRouteIcons;
+    /** @param {string} rel @param {unknown} entry */
+    const pushIcon = (rel, entry) => {
+      if (!entry) return;
+      const items = Array.isArray(entry) ? entry : [entry];
+      for (const it of items) {
+        if (!it) continue;
+        if (typeof it === 'string') {
+          linkTags.push(`<link rel="${rel}" href="${escapeAttr(absUrl(it))}">`);
+        } else if (typeof it === 'object' && it.url) {
+          const parts = [`rel="${rel}"`, `href="${escapeAttr(absUrl(it.url))}"`];
+          if (it.sizes) parts.push(`sizes="${escapeAttr(it.sizes)}"`);
+          if (it.type) parts.push(`type="${escapeAttr(it.type)}"`);
+          linkTags.push(`<link ${parts.join(' ')}>`);
+        }
+      }
+    };
+    pushIcon('icon', buckets.icon);
+    pushIcon('apple-touch-icon', buckets.apple);
+    pushIcon('shortcut icon', buckets.shortcut);
+    // `other` is the catch-all: array of { rel, url, ...attrs }.
+    if (buckets.other) {
+      const others = Array.isArray(buckets.other) ? buckets.other : [buckets.other];
+      for (const o of others) {
+        if (!o || !o.rel || !o.url) continue;
+        const parts = [`rel="${escapeAttr(o.rel)}"`, `href="${escapeAttr(absUrl(o.url))}"`];
+        if (o.sizes) parts.push(`sizes="${escapeAttr(o.sizes)}"`);
+        if (o.type) parts.push(`type="${escapeAttr(o.type)}"`);
+        linkTags.push(`<link ${parts.join(' ')}>`);
+      }
+    }
+  }
+
+  // manifest: a string URL → <link rel="manifest">
+  if (typeof m.manifest === 'string') {
+    linkTags.push(`<link rel="manifest" href="${escapeAttr(absUrl(m.manifest))}">`);
+  }
+
+  // alternates: { canonical, languages: { '<hreflang>': url }, media: { '<media>': url } }
+  // Mirrors Next.js's metadata.alternates surface. Relative values are resolved
+  // against metadataBase.
+  if (m.alternates && typeof m.alternates === 'object') {
+    if (m.alternates.canonical) {
+      linkTags.push(`<link rel="canonical" href="${escapeAttr(absUrl(m.alternates.canonical))}">`);
+    }
+    if (m.alternates.languages && typeof m.alternates.languages === 'object') {
+      for (const [hreflang, href] of Object.entries(m.alternates.languages)) {
+        linkTags.push(
+          `<link rel="alternate" hreflang="${escapeAttr(hreflang)}" href="${escapeAttr(absUrl(href))}">`,
+        );
+      }
+    }
+    if (m.alternates.media && typeof m.alternates.media === 'object') {
+      for (const [media, href] of Object.entries(m.alternates.media)) {
+        linkTags.push(
+          `<link rel="alternate" media="${escapeAttr(media)}" href="${escapeAttr(absUrl(href))}">`,
+        );
+      }
+    }
+    if (m.alternates.types && typeof m.alternates.types === 'object') {
+      // alternates.types: { 'application/rss+xml': '/rss.xml' }
+      for (const [type, href] of Object.entries(m.alternates.types)) {
+        linkTags.push(
+          `<link rel="alternate" type="${escapeAttr(type)}" href="${escapeAttr(absUrl(href))}">`,
+        );
+      }
+    }
+  }
+
+  // JSON-LD structured data (schema.org). `m.jsonLd` is a single object
+  // OR an array of objects. The author owns the schema.org shape; the
+  // framework only serializes and HTML-safe-escapes each object into a
+  // `<script type="application/ld+json">` block. A single object emits
+  // ONE script; an array emits one script PER element.
+  //
+  // The block is a NON-EXECUTABLE data island (type application/ld+json),
+  // so CSP script-src does not gate it and it carries NO nonce. Adding one
+  // would wrongly imply it is executable script.
+  if (m.jsonLd != null) {
+    const list = Array.isArray(m.jsonLd) ? m.jsonLd : [m.jsonLd];
+    for (const obj of list) {
+      const tag = jsonLdScript(obj);
+      if (tag) scriptTags.push(tag);
+    }
+  }
+
+  // Byte-identical to the pre-split template. Every hole is unconditional
+  // and carries its own newline, INCLUDING the csp-nonce meta, which renders
+  // as an EMPTY line when there is no nonce. Collapsing that into a
+  // conditional line makes the CSP-off document one newline shorter than the
+  // CSP-on one, and the framework guarantees the two render identically
+  // apart from the nonce itself.
+  const title = m.title || 'webjs app';
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<style${n}>@layer webjs-host{:where([data-wj-host]){display:block}:where([data-wj-host][hidden]:not([hidden='until-found'])){display:none}}</style>
+${opts.nonce ? `<meta name="csp-nonce" content="${escapeAttr(opts.nonce)}">` : ''}
+${metaTags.join('\n')}
+<title>${escapeHtml(title)}</title>
+${publicEnvShim({ dev: opts.dev, nonce: opts.nonce })}${clientRouterEnabled() ? '' : `\n<script${n}>window.__WEBJS_CLIENT_ROUTER__=false;</script>`}
+${importMapTag({ nonce: opts.nonce })}
+${linkTags.join('\n')}
+${scriptTags.length ? scriptTags.join('\n') + '\n' : ''}${boot}
+${reload}
+${suspenseBoot}
+</head>
+<body>
+`;
+}