@webjsdev/core 0.7.50 → 0.7.53

package/src/router-client/frames.js

@@ -0,0 +1,329 @@
+/**
+ * Client router: frames.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+import { FRAME_TOP } from './constants.js';
+import { warnOnce } from './diagnostics.js';
+import { outerHTMLForDiff } from './head-merge.js';
+
+/**
+ * Find the id of the innermost <webjs-frame> enclosing `el`, walking up
+ * through normal DOM and any shadow boundaries it crosses. Returns null
+ * if the element is not inside any frame.
+ *
+ * @param {Element | null} el
+ * @returns {string | null}
+ */
+export function activeFrameId(el) {
+  /** @type {Element | null} */
+  let cur = el;
+  while (cur) {
+    const frame = cur.closest('webjs-frame');
+    if (frame && frame.id) return frame.id;
+    // Cross shadow boundary upwards if necessary.
+    const root = cur.getRootNode();
+    if (root && /** @type any */ (root).host) {
+      cur = /** @type any */ (root).host;
+    } else {
+      break;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve which `<webjs-frame>` (if any) a trigger drives, honoring an
+ * explicit `data-webjs-frame` attribute before the closest-enclosing-frame
+ * default. Models Turbo's `data-turbo-frame` external targeting:
+ *
+ *   - `data-webjs-frame="<id>"` on (or above) the trigger drives the frame
+ *     with that id, resolved via `getElementById` in the CURRENT document.
+ *     This lets an EXTERNAL link / form (a sidebar, a filter form) drive a
+ *     content frame it is NOT DOM-nested in. If the id does not resolve to a
+ *     live `<webjs-frame>`, we warn ONCE and fall back to a normal full nav
+ *     (the fail-safe posture: never throw, never silently swap the wrong
+ *     region).
+ *   - `data-webjs-frame="_top"` forces a full-page navigation even when the
+ *     trigger is inside a frame, returning `null` so the swap escapes to the
+ *     layout-marker / full-body path.
+ *   - No `data-webjs-frame` keeps today's behavior: the innermost enclosing
+ *     frame via `activeFrameId`.
+ *
+ * Resolution precedence: explicit `data-webjs-frame` > closest enclosing
+ * frame. The attribute is read with `closest('[data-webjs-frame]')` so it
+ * may live on the trigger itself or any ancestor (e.g. a `<nav>` wrapping a
+ * set of links that all target one frame).
+ *
+ * @param {Element | null} trigger
+ * @returns {string | null}  A frame id to swap, or null for a full nav.
+ */
+export function resolveTargetFrameId(trigger) {
+  if (!trigger) return null;
+  const carrier = trigger.closest && trigger.closest('[data-webjs-frame]');
+  const explicit = carrier
+    ? (/** @type {HTMLElement} */ (carrier).dataset
+        ? /** @type {HTMLElement} */ (carrier).dataset.webjsFrame
+        : carrier.getAttribute('data-webjs-frame'))
+    : null;
+  if (explicit != null && explicit !== '') {
+    if (explicit === FRAME_TOP) {
+      // Break out: a full-page nav, never a frame swap.
+      return null;
+    }
+    // External targeting by id. Resolve in the current document.
+    const el = typeof document !== 'undefined' ? document.getElementById(explicit) : null;
+    if (el && el.tagName && el.tagName.toLowerCase() === 'webjs-frame') {
+      return explicit;
+    }
+    // Unresolvable id: warn once, fall back to a normal full nav so the
+    // click still works rather than swapping nothing or the wrong region.
+    warnOnce(
+      `webjs:frame-unresolved:${explicit}`,
+      `[webjs] data-webjs-frame="${explicit}" did not match a live <webjs-frame id="${explicit}">; performing a normal navigation instead.`,
+    );
+    return null;
+  }
+  // No explicit target: today's closest-enclosing-frame default.
+  return activeFrameId(trigger);
+}
+
+/**
+ * The live `<webjs-frame id>` element, or null when no frame with that id is
+ * in the document. Tag-checked on BOTH lookups, so an unrelated element with
+ * a colliding id never passes for a frame.
+ *
+ * The one definition of "this frame is live", shared by the busy lifecycle and
+ * by the prefetch cache's frame-entry validity check (#1407), so the two
+ * cannot drift on what liveness means.
+ *
+ * @param {string | null} frameId
+ * @returns {Element | null}
+ */
+export function liveFrameElement(frameId) {
+  if (!frameId || typeof document === 'undefined') return null;
+  let el = null;
+  try { el = document.querySelector(`webjs-frame#${CSS.escape(frameId)}`); }
+  catch { el = document.getElementById(frameId); }
+  if (!el || !el.tagName || el.tagName.toLowerCase() !== 'webjs-frame') return null;
+  return el;
+}
+
+/**
+ * The nav token that currently OWNS each frame's busy state. Under two rapid
+ * frame navs the router aborts the first; its `finally` would otherwise clear
+ * `aria-busy` that the SECOND nav already re-set, leaving the frame falsely
+ * idle while still loading (and an unbalanced busy-event stream). A clear only
+ * fires when its token still owns the frame, so the superseding nav's busy
+ * state survives the aborted nav's teardown.
+ *
+ * @type {WeakMap<Element, number>}
+ */
+export const frameBusyTokens = new WeakMap();
+
+/**
+ * Set `aria-busy="true"` on the live `<webjs-frame id>` element and announce
+ * the start of its load with a bubbling `webjs:frame-busy` event (detail
+ * `{ frameId, busy: true }`), mirroring Turbo's `frame.markAsBusy`. Stamps the
+ * nav `token` as the frame's busy owner (see `frameBusyTokens`). Returns the
+ * resolved frame element so `clearFrameBusy` can target the SAME node even if
+ * the swap later replaces the frame's id lookup (the element identity is stable
+ * across a child-only frame swap). Returns null when the frame is not in the
+ * live DOM (e.g. a stale external `data-webjs-frame` that slipped the
+ * resolve-time check), so nothing to mark.
+ *
+ * @param {string} frameId
+ * @param {number} token
+ * @returns {Element | null}
+ */
+export function markFrameBusy(frameId, token) {
+  const frame = liveFrameElement(frameId);
+  if (!frame) return null;
+  // Dispatch the `true` edge only on a real idle -> busy transition, so a nav
+  // that supersedes an in-flight one (frame already busy) does not emit a
+  // redundant `true`. The token always advances to the newest owner.
+  const wasBusy = frameBusyTokens.has(frame);
+  frameBusyTokens.set(frame, token);
+  frame.setAttribute('aria-busy', 'true');
+  if (!wasBusy) {
+    frame.dispatchEvent(new CustomEvent('webjs:frame-busy', {
+      bubbles: true,
+      detail: { frameId, busy: true },
+    }));
+  }
+  return frame;
+}
+
+/**
+ * Clear the busy state set by `markFrameBusy`: set `aria-busy="false"` and
+ * dispatch the matching `webjs:frame-busy` (detail `{ frameId, busy: false }`)
+ * so app code sees a symmetric start/finish pair. Mirrors Turbo's
+ * `frame.clearBusyState`. Operates on the element captured at start, so an
+ * abort / error clears the same node the start marked. A clear whose token no
+ * longer owns the frame (a newer nav re-set busy) is a stale teardown from a
+ * superseded nav and is skipped, so the live nav stays busy.
+ *
+ * @param {Element} frame
+ * @param {number} token
+ */
+export function clearFrameBusy(frame, token) {
+  if (frameBusyTokens.get(frame) !== token) return;
+  frameBusyTokens.delete(frame);
+  frame.setAttribute('aria-busy', 'false');
+  const frameId = frame.id || null;
+  frame.dispatchEvent(new CustomEvent('webjs:frame-busy', {
+    bubbles: true,
+    detail: { frameId, busy: false },
+  }));
+}
+
+/**
+ * The nav token that currently OWNS each form's submission-busy state. Same
+ * role as `frameBusyTokens` for frames: under two rapid submits the router
+ * aborts the first, and its `finally` would otherwise clear `aria-busy` /
+ * dispatch `webjs:submit-end` for a submission the SECOND submit already
+ * re-set, leaving the form falsely idle while still submitting (and an
+ * unbalanced start/end event stream). A clear only fires when its token still
+ * owns the form, so the superseding submit's busy state survives the aborted
+ * submit's teardown.
+ *
+ * @type {WeakMap<Element, number>}
+ */
+export const formBusyTokens = new WeakMap();
+
+/**
+ * Mark a submitting `<form>` busy: set the native `aria-busy="true"` (the
+ * readable "is this form submitting" primitive any component can poll) and
+ * dispatch a bubbling `webjs:submit-start` event (detail `{ form, url }`).
+ * Stamps `token` as the form's busy owner (see `formBusyTokens`). The `true`
+ * edge fires only on a real idle -> busy transition, so a submit that
+ * supersedes an in-flight one (form already busy) does not emit a redundant
+ * start; the token always advances to the newest owner. Returns the form so
+ * `clearFormBusy` targets the same node.
+ *
+ * @param {HTMLFormElement} form
+ * @param {number} token
+ * @param {string} url   Resolved action URL the submission targets.
+ * @returns {HTMLFormElement}
+ */
+export function markFormBusy(form, token, url) {
+  const wasBusy = formBusyTokens.has(form);
+  formBusyTokens.set(form, token);
+  form.setAttribute('aria-busy', 'true');
+  if (!wasBusy) {
+    form.dispatchEvent(new CustomEvent('webjs:submit-start', {
+      bubbles: true,
+      detail: { form, url },
+    }));
+  }
+  return form;
+}
+
+/**
+ * Clear the busy state set by `markFormBusy`: set `aria-busy="false"` and
+ * dispatch the matching `webjs:submit-end` (detail `{ form, url, ok }`, `ok` =
+ * the submission settled as a success / not an error outcome) so app code sees
+ * a symmetric start/finish pair. Operates on the element captured at start, so
+ * an abort / error clears the same node the start marked. A clear whose token
+ * no longer owns the form (a newer submit re-set busy) is a stale teardown
+ * from a superseded submit and is skipped, so the live submit stays busy.
+ *
+ * @param {HTMLFormElement} form
+ * @param {number} token
+ * @param {string} url
+ * @param {boolean} ok
+ */
+export function clearFormBusy(form, token, url, ok) {
+  if (formBusyTokens.get(form) !== token) return;
+  formBusyTokens.delete(form);
+  form.setAttribute('aria-busy', 'false');
+  const evt = new CustomEvent('webjs:submit-end', {
+    bubbles: true,
+    detail: { form, url, ok: !!ok },
+  });
+  // A successful submission swaps the page in place, and a full-body swap
+  // (or a swap whose region contained the form) detaches the form before
+  // this teardown runs. A bubbling event dispatched on a DISCONNECTED node
+  // never reaches a `document`-level listener, so a synchronous swap (the
+  // no-view-transition default) would silently drop `submit-end`. Dispatch
+  // on `document` when the form is no longer connected so the symmetric
+  // start/end pair always lands, regardless of swap timing.
+  if (form.isConnected) {
+    form.dispatchEvent(evt);
+  } else if (typeof document !== 'undefined') {
+    document.dispatchEvent(evt);
+  } else {
+    form.dispatchEvent(evt);
+  }
+}
+
+/**
+ * Apply the swap from a parsed incoming Document onto the live document.
+ * Picks the most-scoped match: explicit webjs-frame > deepest shared
+ * layout marker > full body swap.
+ *
+ * If the incoming page carries a different importmap from the current
+ * page (typical after a deploy that bumped a vendor pin), partial swap
+ * is unsafe: importmaps are immutable once applied, so the new page
+ * would resolve modules against the stale URLs. We fall back to a full
+ * page load via `location.assign(href)`. Mirrors Turbo's
+ * `tracked_element_mismatch` reload, applied specifically to
+ * importmaps. Called with `href = null` for revalidation flows (which
+ * never trigger a hard reload).
+ *
+ * Detection uses the `X-Webjs-Build` response header (read by the
+ * fetch path and passed in as `incomingBuild`), compared against the
+ * current page's `data-webjs-build`. The header is set on EVERY SSR
+ * response, including X-Webjs-Have partial responses that omit the
+ * head and importmap entirely, and it carries the PUBLISHED build id,
+ * which the server advertises only once the importmap is final. A hard
+ * reload fires only when both ids are present and differ (a real
+ * cross-deploy). An empty / absent id on either side means "version
+ * unknown" (a warming runtime-first-boot server, or a response that
+ * predates the header) and never triggers a reload, so the warmup
+ * window cannot wipe a half-filled form.
+ *
+ * @param {Document} doc
+ * @param {string | null} frameId
+ * @param {boolean} revalidating  Restore from cache; already-matched markers may stomp inflight state, signal helps loading templates skip.
+ * @param {string | null} [href]  Target URL for hard-reload fallback on importmap mismatch.
+ * @param {string | null} [incomingBuild]  X-Webjs-Build header from the response, or null.
+ */
+/**
+ * Compute the signature of all `data-webjs-track="reload"` elements
+ * in the head of `root`. Returns the concatenation of each element's
+ * `outerHTML`, in document order. Two documents with identical
+ * tracked-element sets produce identical signatures; any change in
+ * attributes, content, or set membership produces a different one.
+ *
+ * Mirrors hotwired/turbo's `head_snapshot.js` `trackedElementSignature`
+ * (the data-turbo-track="reload" mechanism). Used by applySwap as a
+ * generic opt-in next to the importmap-specific build hash.
+ *
+ * Returns the empty string when `root` has no head (e.g. an
+ * X-Webjs-Have partial response) or when no elements opt in.
+ *
+ * @param {Document | undefined} root
+ * @returns {string}
+ */
+export function trackedReloadSignature(root) {
+  if (!root || !root.head) return '';
+  const tracked = root.head.querySelectorAll('[data-webjs-track="reload"]');
+  if (!tracked.length) return '';
+  // Use outerHTMLForDiff so the CSP nonce (which rotates per
+  // request) is stripped before signature comparison. Without this,
+  // a nonced tracked script like `<script nonce="${cspNonce()}"
+  // data-webjs-track="reload" src="/build.js?v=42">` would mismatch
+  // every navigation and infinite-reload. Matches Turbo's
+  // head_snapshot.js elementWithoutNonce posture.
+  let sig = '';
+  for (const el of tracked) sig += outerHTMLForDiff(el);
+  return sig;
+}
+
+/* ====================================================================
+ * View Transitions (opt-in) + permanent-element persistence
+ * ==================================================================== */

package/src/router-client/head-merge.js

@@ -0,0 +1,344 @@
+/**
+ * Client router: head-merge.
+ *
+ * Moved verbatim out of the pre-split `router-client.js`; that barrel holds
+ * the router's full contract and the public entry points.
+ *
+ * @module
+ */
+import { META_KEY_CSP_NONCE } from './constants.js';
+
+/**
+ * Read the CSP nonce that the original page load published via
+ * `<meta name="csp-nonce" content="...">`. Returns empty string when
+ * no meta tag is present (apps without strict CSP).
+ *
+ * The meta tag is the contract: server emits it once at SSR time,
+ * client reads it for every dynamically-created script. The browser
+ * enforces CSP against the nonce the original page declared, NOT the
+ * per-request nonce on subsequent navigations. So we always apply
+ * THIS nonce, not the source-page nonce that arrived with the new
+ * head fragment.
+ *
+ * Mirrors hotwired/turbo's `getCspNonce` in src/util.js. Not cached:
+ * a single querySelector on document.head is cheap, and caching
+ * would break if the user (or a test) inserted the meta tag late.
+ *
+ * @returns {string}
+ */
+export function getCspNonce() {
+  if (typeof document === 'undefined') return '';
+  const meta = document.querySelector('meta[name="csp-nonce"]');
+  // Read the `content` attribute, not the `.nonce` IDL property.
+  // Turbo's getCspNonce in src/util.js falls back to `.nonce` first
+  // because it can be called against script/link elements (where
+  // browsers DO expose `.nonce` and additionally clear the
+  // `nonce` attribute on document load). The `<meta name="csp-nonce">`
+  // element WebJs targets has no `.nonce` IDL (only script + link
+  // elements do per HTML spec), so the only viable source is the
+  // `content` attribute.
+  return meta ? meta.getAttribute('content') || '' : '';
+}
+
+/**
+ * Create a `<script>` clone of `source` that's safe to insert into the
+ * live document under strict CSP. Copies every attribute EXCEPT
+ * nonce (the source's nonce is from the new page's per-request token,
+ * which the browser's CSP cache from the original page load will
+ * reject), then applies the cached nonce from the meta tag. Re-emits
+ * textContent so inline scripts execute as if first-loaded.
+ *
+ * @param {HTMLScriptElement} source
+ * @returns {HTMLScriptElement}
+ */
+export function cloneScriptWithCorrectNonce(source) {
+  const script = document.createElement('script');
+  for (const attr of source.attributes) {
+    if (attr.name === 'nonce') continue;
+    script.setAttribute(attr.name, attr.value);
+  }
+  const nonce = getCspNonce();
+  if (nonce) {
+    // Use setAttribute so the attribute is queryable
+    // (`getAttribute('nonce')`, outerHTML serialization, etc.).
+    // Per CSP3 the .nonce IDL property is the authoritative source
+    // for the CSP check, but real browsers reflect setAttribute into
+    // .nonce automatically. Test environments (linkedom) reflect only
+    // one direction, so we set the attribute.
+    script.setAttribute('nonce', nonce);
+  }
+  script.textContent = source.textContent;
+  return script;
+}
+
+/**
+ * Clone any head element while substituting the page-load CSP nonce
+ * for the source's per-request nonce. Used for `<link rel="modulepreload"
+ * nonce="...">` and any other nonce-carrying head element: browsers
+ * gate cross-origin module preload by script-src nonce too, so the
+ * per-request nonce from the new page's head would be blocked by the
+ * browser's CSP cache from the original page load.
+ *
+ * Returns a cloneNode(true) for elements without a nonce attribute,
+ * so non-CSP cases stay zero-cost.
+ *
+ * @param {Element} source
+ * @returns {Element}
+ */
+function cloneElementWithCorrectNonce(source) {
+  if (!source.hasAttribute('nonce')) return source.cloneNode(true);
+  const clone = /** @type {Element} */ (source.cloneNode(true));
+  const nonce = getCspNonce();
+  if (nonce) {
+    clone.setAttribute('nonce', nonce);
+  } else {
+    clone.removeAttribute('nonce');
+  }
+  return clone;
+}
+
+/**
+ * Return an `outerHTML` string suitable for head-diff comparison: strip
+ * any nonce attribute so per-request nonces don't cause every script in
+ * the head to look "changed" on every navigation. The original element
+ * is left untouched (we clone first).
+ *
+ * Mirrors hotwired/turbo's `elementWithoutNonce` pattern in
+ * src/core/drive/head_snapshot.js.
+ *
+ * @param {Element} el
+ * @returns {string}
+ */
+export function outerHTMLForDiff(el) {
+  // Strip nonce from ANY element type. SCRIPT obviously, but also LINK
+  // (modulepreload tags carry nonce per the recent CSP fix). Without
+  // this, per-request nonces on link tags would cause the diff to
+  // treat every preload as "changed", duplicating preloads on every
+  // navigation.
+  if (!el.hasAttribute('nonce')) return el.outerHTML;
+  const clone = /** @type {Element} */ (el.cloneNode(true));
+  clone.removeAttribute('nonce');
+  return clone.outerHTML;
+}
+
+/**
+ * Stable identity key for a `<meta>` that represents a single logical tag, so a
+ * PAGE-SCOPED meta can be reconciled across a soft-nav head merge (#1046). A
+ * meta with no identifying attribute returns null and is left to the add-only
+ * path (added but never removed), since its identity is ambiguous.
+ *
+ * @param {Element} m
+ * @returns {string | null}
+ */
+function metaIdentity(m) {
+  const name = m.getAttribute('name');
+  if (name) return 'name=' + name;
+  const property = m.getAttribute('property');
+  if (property) return 'property=' + property;
+  const httpEquiv = m.getAttribute('http-equiv');
+  if (httpEquiv) return 'http-equiv=' + httpEquiv;
+  if (m.hasAttribute('charset')) return 'charset';
+  return null;
+}
+
+/**
+ * Reconcile keyed `<meta>` tags across a soft-nav head merge (#1046). The
+ * add-only merge (`addNewHeadElements`) never removes a stale head element, so a
+ * PAGE-SCOPED meta the previous page added (a `view-transition` opt-in, a
+ * per-page `robots` / `theme-color` / `description`, an `og:*` property) leaked
+ * onto every later page. This pass gives each keyed meta the full add / update /
+ * remove treatment: a meta present in the incoming head is added or synced, and
+ * a live keyed meta ABSENT from the incoming head is removed.
+ *
+ * Safe against the `X-Webjs-Have` reduced-head optimization (#936): that
+ * optimization only omits the shared app STYLESHEET (already on the client), and
+ * this pass touches ONLY `<meta>` tags, never a stylesheet / link / script. The
+ * incoming head always carries the target page's complete meta set (charset,
+ * viewport, and the app-wide metas from the root layout appear in both heads, so
+ * they are preserved), so "absent from the incoming head" means "this page does
+ * not declare it", not "optimized away".
+ *
+ * A key may repeat (multiple `og:image`), so both sides are grouped into a LIST
+ * per key and reconciled as a set: an unchanged set is left alone, else the live
+ * copies are removed and the incoming set re-appended.
+ *
+ * @param {HTMLHeadElement} newHead
+ */
+function reconcileHeadMetas(newHead) {
+  // A HEADLESS fragment response (a `<webjs-frame>` subtree) has no `<head>`, so
+  // `parseHTML` leaves `newHead` empty. A real full head ALWAYS emits charset +
+  // viewport, so "no `<meta>` at all in the incoming head" means "this is a
+  // fragment, not a head to reconcile against". Skipping it here is what keeps a
+  // frame swap from stripping every live page-scoped meta (viewport, og:*, ...).
+  if (!newHead.querySelector('meta')) return;
+
+  /** @param {ParentNode} root @returns {Map<string, Element[]>} */
+  const group = (root) => {
+    const map = new Map();
+    for (const el of root.querySelectorAll('meta')) {
+      const key = metaIdentity(el);
+      if (!key || key === META_KEY_CSP_NONCE) continue;
+      const list = map.get(key);
+      if (list) list.push(el); else map.set(key, [el]);
+    }
+    return map;
+  };
+  const incoming = group(newHead);
+  const live = group(document.head);
+
+  // Add or replace each incoming key whose SET differs from the live set.
+  for (const [key, incEls] of incoming) {
+    const liveEls = live.get(key) || [];
+    const incKey = incEls.map(outerHTMLForDiff).join('\n');
+    const liveKey = liveEls.map(outerHTMLForDiff).join('\n');
+    if (incKey === liveKey) continue;
+    if (incEls.length === 1 && liveEls.length === 1) {
+      // The common case (one description / theme-color / robots per page):
+      // sync attributes IN PLACE so the live element keeps its DOM identity.
+      // An app script holding a reference (a theme manager caching
+      // meta[name=theme-color]) still points at the live tag after the nav,
+      // and there is no remove/append churn for a content-only change.
+      const cur = liveEls[0];
+      for (const a of [...cur.attributes]) cur.removeAttribute(a.name);
+      for (const a of incEls[0].attributes) cur.setAttribute(a.name, a.value);
+      continue;
+    }
+    // Multi-element sets (repeated og:image): no unambiguous element-to-element
+    // mapping exists, so replace the set wholesale.
+    for (const el of liveEls) el.remove();
+    for (const el of incEls) document.head.appendChild(cloneElementWithCorrectNonce(el));
+  }
+  // Remove a stale page-scoped key the incoming page does not declare at all.
+  for (const [key, liveEls] of live) {
+    if (!incoming.has(key)) for (const el of liveEls) el.remove();
+  }
+}
+
+export function addNewHeadElements(newHead) {
+  const newTitle = newHead.querySelector('title');
+  if (newTitle) document.title = newTitle.textContent || '';
+
+  const currentSet = new Set();
+  for (const el of document.head.children) currentSet.add(outerHTMLForDiff(el));
+
+  for (const el of newHead.children) {
+    if (el.tagName === 'SCRIPT' && el.getAttribute('type') === 'importmap') {
+      // Skip: partial swaps keep the outer layout mounted, so the
+      // existing importmap stays authoritative. Importmaps are
+      // immutable once a script has run (modern browsers ignore
+      // subsequent `<script type=importmap>`). Importmap-mismatch
+      // detection lives at the applySwap entry: a mismatch there
+      // triggers a full reload before we ever reach this loop.
+      continue;
+    }
+    if (el.tagName === 'BASE') continue;
+    if (el.tagName === 'TITLE') continue;
+    // A keyed <meta> is add/update/remove reconciled below (#1046), so skip it
+    // here to avoid appending a duplicate when its content changed.
+    if (el.tagName === 'META' && metaIdentity(el)) continue;
+    if (!currentSet.has(outerHTMLForDiff(el))) {
+      if (el.tagName === 'SCRIPT') {
+        document.head.appendChild(
+          cloneScriptWithCorrectNonce(/** @type {HTMLScriptElement} */ (el)),
+        );
+      } else {
+        document.head.appendChild(cloneElementWithCorrectNonce(el));
+      }
+    }
+  }
+
+  // Reconcile keyed <meta> tags so a stale page-scoped meta is removed, not
+  // leaked onto every later page (#1046).
+  reconcileHeadMetas(newHead);
+}
+
+/**
+ * Is `el` a stylesheet the head merge must never remove: a `<style>` or a
+ * `<link rel~="stylesheet">`. WebJs ALWAYS keeps these on a soft nav, with no
+ * opt-out, and that is a deliberate divergence from Turbo. Turbo removes a
+ * stylesheet absent from the new head when it is tagged
+ * `data-turbo-track="dynamic"`, which is sound in Turbo because a Turbo visit
+ * always compares a COMPLETE old head to a COMPLETE new head, so "absent" means
+ * "this page removed it". WebJs's `X-Webjs-Have` optimization returns a REDUCED
+ * head (the shared app stylesheet is omitted because the client already has it),
+ * so "absent from the incoming head" means "optimized away", NOT "removed". A
+ * dynamic-removal opt-out would therefore re-introduce #936 (it would strip a
+ * still-needed sheet on any partial response), and WebJs is Tailwind-first (one
+ * global sheet, no page-specific sheets to drop), so the knob would be unsafe
+ * and unused. Keeping every stylesheet is correct here; a genuinely changed one
+ * is dropped by the deploy-level hard reload (build-id mismatch), not a soft swap.
+ *
+ * @param {Element} el
+ * @returns {boolean}
+ */
+function isPersistentHeadStyle(el) {
+  if (el.tagName === 'STYLE') return true;
+  return el.tagName === 'LINK' &&
+    (el.getAttribute('rel') || '').toLowerCase().split(/\s+/).includes('stylesheet');
+}
+
+/** @param {HTMLHeadElement} newHead */
+export function mergeHead(newHead) {
+  const currentHead = document.head;
+
+  const newTitle = newHead.querySelector('title');
+  if (newTitle) document.title = newTitle.textContent || '';
+
+  const currentSet = new Set();
+  for (const el of currentHead.children) {
+    if (el.tagName === 'SCRIPT' && el.getAttribute('type') === 'importmap') continue;
+    if (el.tagName === 'BASE') continue;
+    currentSet.add(outerHTMLForDiff(el));
+  }
+
+  const newSet = new Set();
+  for (const el of newHead.children) {
+    if (el.tagName === 'SCRIPT' && el.getAttribute('type') === 'importmap') continue;
+    if (el.tagName === 'BASE') continue;
+    newSet.add(outerHTMLForDiff(el));
+  }
+
+  for (const el of [...currentHead.children]) {
+    if (el.tagName === 'SCRIPT' && el.getAttribute('type') === 'importmap') continue;
+    if (el.tagName === 'BASE') continue;
+    if (el.tagName === 'TITLE') continue;
+    // #936: NEVER remove a stylesheet or a `<style>` on a soft nav (Turbo's
+    // persistent-CSS model). The incoming head of a full-body-swap fallback can
+    // legitimately lack the app's `<link rel=stylesheet>` (a partial or mangled
+    // response, e.g. from a mid-parse empty-`have` prefetch): removing the live
+    // one there leaves the whole page unstyled until a manual refresh, the
+    // headline #936 symptom. Keeping it is safe: a genuinely stale sheet is
+    // dropped by the deploy-level hard reload (build-id mismatch), not here.
+    if (isPersistentHeadStyle(el)) continue;
+    // Never remove the CSP nonce meta: the incoming full-body response carries a
+    // FRESH per-request nonce, but the browser enforces CSP against the nonce the
+    // ORIGINAL page load declared (see `getCspNonce`), so the live one must stay
+    // (#1050). `outerHTMLForDiff` strips the nonce ATTRIBUTE but not the `content`
+    // it lives in on this meta, so without this it looks "changed" and is dropped.
+    if (el.tagName === 'META' && metaIdentity(el) === META_KEY_CSP_NONCE) continue;
+    if (!newSet.has(outerHTMLForDiff(el))) el.remove();
+  }
+
+  for (const el of newHead.children) {
+    if (el.tagName === 'SCRIPT' && el.getAttribute('type') === 'importmap') continue;
+    if (el.tagName === 'BASE') continue;
+    if (el.tagName === 'TITLE') continue;
+    // Do not append the incoming per-request csp-nonce meta (the live original is
+    // kept above), or the head would carry two and `getCspNonce` could read the
+    // wrong one (#1050).
+    if (el.tagName === 'META' && metaIdentity(el) === META_KEY_CSP_NONCE) continue;
+    if (!currentSet.has(outerHTMLForDiff(el))) {
+      if (el.tagName === 'SCRIPT') {
+        currentHead.appendChild(
+          cloneScriptWithCorrectNonce(/** @type {HTMLScriptElement} */ (el)),
+        );
+      } else {
+        currentHead.appendChild(cloneElementWithCorrectNonce(el));
+      }
+    }
+  }
+}
+
+/* ====================================================================
+ * Custom-element upgrade + script reactivation
+ * ==================================================================== */