@webjsdev/core 0.7.65 → 0.9.0

package/src/router-client/owned-styles.js

@@ -0,0 +1,372 @@
+/**
+ * Stylesheets owned by a layout boundary (#1669).
+ *
+ * The server hoists the `<link rel="stylesheet">` at the start of a nested
+ * layout's or page's output into `<head>`, tagged `data-wj-style-owner` with
+ * the segment of the `wj:children` range it was rendered in. This module is
+ * the client half: it switches such a sheet OFF when a soft navigation
+ * replaces that range and the incoming page no longer carries the file, and
+ * back ON when a later page (or a back / forward restore) carries it again.
+ *
+ * Why OFF and not removed. Every framework the router takes cues from puts a
+ * route's sheet in the head and dedupes by href, but they split on what a
+ * departed route's sheet should do: Next, React Float, TanStack and SvelteKit
+ * keep it, Remix and Astro remove it, and Turbo removes it only when the link
+ * opts in with `data-turbo-track="dynamic"`. Keeping it costs real time here,
+ * since a disjoint section's sheet can carry hundreds of `:has()` rules every
+ * element insertion is checked against. Removing it would leave a back /
+ * forward restore painting before the sheet reloads, because a restore applies
+ * synchronously so the browser can replay the scroll offset (#1428). A
+ * disabled sheet is in neither bind: the browser skips it in matching and
+ * invalidation, and turning it back on is synchronous because it is already
+ * parsed. The `data-wj-style-off` marker records the state in the DOM, so a
+ * snapshot serializes it and a restore knows which sheets were off.
+ *
+ * Why it cannot reintroduce #936. A sheet is switched off ONLY when the range
+ * that owns it is SWAPPED (replaced, or morphed in place), never because the
+ * incoming head lacks it in general: a reduced `X-Webjs-Have` response omits
+ * what the client already has, and reading that absence as "no longer needed"
+ * is what left the page unstyled there. Everything inside a swapped range was
+ * re-rendered by the server, so the incoming head carries every owned sheet
+ * that range still needs. A sheet with no owner (the root layout's, or one an
+ * app writes into its head) is never touched.
+ */
+import { segmentWithin } from './boundaries.js';
+import { PRELOAD_ATTR, relIsStylesheet } from './constants.js';
+
+/** The server's tag naming a hoisted stylesheet's owner segment. */
+export const OWNER_ATTR = 'data-wj-style-owner';
+/** Marks an owned stylesheet the router has switched off. */
+export const OFF_ATTR = 'data-wj-style-off';
+/**
+ * Marks a link loading under `media="not all"` so it is fetched without
+ * applying, and holds the author's own media (empty for none) until it is
+ * released. The dev refresh (`dev-styles.js`) reads the same attribute.
+ */
+export const HELD_MEDIA_ATTR = 'data-wj-style-media';
+
+/** The query the dev refresh re-requests a sheet under (`dev-styles.js`). */
+const DEV_REFRESH_PARAM = '__webjs_dev';
+
+/**
+ * Is `el` a `<link>` naming a stylesheet (`rel` has `stylesheet`, not
+ * `alternate`) with an href.
+ * @param {Element} el
+ */
+export function isStylesheetLink(el) {
+  return el.tagName === 'LINK' && !!el.getAttribute('href') && relIsStylesheet(el);
+}
+
+/**
+ * The media a link applies under: the author's, also while the link is held
+ * under `not all`.
+ * @param {Element} el
+ */
+function authoredMedia(el) {
+  return ((el.hasAttribute(HELD_MEDIA_ATTR) ? el.getAttribute(HELD_MEDIA_ATTR) : el.getAttribute('media')) || '').trim();
+}
+
+/**
+ * The identity of a stylesheet link: its URL resolved against `base`, with the
+ * dev refresh's cache-buster stripped (so a sheet the dev refresh re-requested
+ * still matches the bare href the next response carries), plus the `media` it
+ * applies under (a print copy and a screen copy of one file are two sheets).
+ * The server's hoist keys sheets the same way.
+ * @param {Element} el
+ * @param {string} base
+ * @returns {string | null}
+ */
+function keyFor(el, base) {
+  const href = el.getAttribute('href');
+  if (!href) return null;
+  try {
+    const url = new URL(href, base);
+    url.searchParams.delete(DEV_REFRESH_PARAM);
+    const media = authoredMedia(el);
+    return media && media !== 'all' ? `${url.href} ${media}` : url.href;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The key of each live link, taken against the URL the document had when the
+ * router first saw it. A swap records the new history entry before it merges
+ * the head, so by then `document.baseURI` is the NEW page's, and resolving a
+ * live relative href against it would name a different file.
+ * @type {WeakMap<Element, string>}
+ */
+const liveKeys = new WeakMap();
+
+/**
+ * Record the key of every live stylesheet the router has not seen yet,
+ * against the current `document.baseURI`. Called when the router enables and
+ * at the start of every swap, before the history entry moves.
+ */
+export function primeLiveStylesheetKeys() {
+  if (typeof document === 'undefined' || !document.head) return;
+  for (const el of document.querySelectorAll('link[href]')) {
+    if (liveKeys.has(el) || !isStylesheetLink(el)) continue;
+    const key = keyFor(el, document.baseURI);
+    if (key) liveKeys.set(el, key);
+  }
+}
+
+/** @param {Element} el */
+function liveKey(el) {
+  let key = liveKeys.get(el);
+  if (!key) {
+    key = keyFor(el, document.baseURI) || '';
+    if (key) liveKeys.set(el, key);
+  }
+  return key || null;
+}
+
+/**
+ * Hold a link under `media="not all"`: it is fetched but does not apply, the
+ * standard way to load a stylesheet without applying it (a `disabled` link is
+ * never fetched at all). The author's media is kept in `HELD_MEDIA_ATTR`.
+ * @param {Element} link
+ */
+export function holdMedia(link) {
+  if (link.hasAttribute(HELD_MEDIA_ATTR)) return;
+  link.setAttribute(HELD_MEDIA_ATTR, link.getAttribute('media') || '');
+  link.setAttribute('media', 'not all');
+}
+
+/**
+ * Give a held link its own media back. Firefox and WebKit give the link a new
+ * sheet object when its media changes, so a caller that disables the sheet
+ * does it after this.
+ * @param {Element} link
+ */
+export function releaseMedia(link) {
+  if (!link.hasAttribute(HELD_MEDIA_ATTR)) return;
+  const media = link.getAttribute(HELD_MEDIA_ATTR);
+  link.removeAttribute(HELD_MEDIA_ATTR);
+  if (media) link.setAttribute('media', media);
+  else link.removeAttribute('media');
+}
+
+/** Links with a settle listener pending, so one is never added twice. */
+const settling = new WeakSet();
+
+/**
+ * Switch a link off or on.
+ *
+ * A sheet still loading has no `sheet` yet. It is neither removed (a back /
+ * forward restore would then paint before a reload) nor left to apply: a
+ * stylesheet takes effect when it loads, a rendering frame can fall before
+ * its `load` task, and the departed section's rules would paint for that
+ * frame. So it is held (`holdMedia`) and, when it loads, released and then
+ * disabled if it is still marked off. Switching it back on releases it at
+ * once, so a link that already failed to load never keeps `not all`.
+ * @param {HTMLLinkElement} link
+ * @param {boolean} off
+ */
+function setOff(link, off) {
+  if (off) link.setAttribute(OFF_ATTR, '');
+  else link.removeAttribute(OFF_ATTR);
+  if (!off) {
+    releaseMedia(link);
+    if (link.sheet) link.sheet.disabled = false;
+    return;
+  }
+  if (link.sheet) { link.sheet.disabled = true; return; }
+  holdMedia(link);
+  if (settling.has(link)) return;
+  settling.add(link);
+  const settle = () => {
+    link.removeEventListener('load', settle);
+    link.removeEventListener('error', settle);
+    settling.delete(link);
+    if (!link.hasAttribute(OFF_ATTR)) return;
+    releaseMedia(link);
+    if (link.sheet) link.sheet.disabled = true;
+  };
+  link.addEventListener('load', settle);
+  link.addEventListener('error', settle);
+}
+
+/**
+ * Put an owned stylesheet link where a full load would have it: after the
+ * last owned sheet of its own boundary or an enclosing one, else before the
+ * first owned sheet, else at the end of the head. Root to leaf, so the
+ * cascade does not depend on how the page was reached. The router's
+ * temporary copies are placed the same way, which is what lets the head
+ * merge adopt a copy as the real link without moving it.
+ * @param {Element} node
+ * @param {string} owner
+ */
+export function placeOwnedLink(node, owner) {
+  /** @type {Element | null} */
+  let after = null;
+  /** @type {Element | null} */
+  let firstOwned = null;
+  for (const el of document.head.querySelectorAll(`link[${OWNER_ATTR}]`)) {
+    // The router's temporary copies count too (they carry their owner), so
+    // two sheets one navigation brings keep their relative order.
+    if (el === node || !isStylesheetLink(el)) continue;
+    if (!firstOwned) firstOwned = el;
+    if (segmentWithin(owner, /** @type {string} */ (el.getAttribute(OWNER_ATTR)))) after = el;
+  }
+  if (after) after.after(node);
+  else if (firstOwned) firstOwned.before(node);
+  else document.head.appendChild(node);
+}
+
+/**
+ * Start merging one incoming head's stylesheets into the live document.
+ * Returns a `merge(el, clone)` that answers true when it handled `el`, so the
+ * caller does not append it. The live links are read once, here, and kept
+ * current as the merge inserts. Called inside the swap commit, so whatever it
+ * switches on or adds takes effect with the swap and not before it.
+ *
+ * For each incoming stylesheet:
+ * - The live document already links the file, in its head or in a part of
+ *   its body this swap keeps (`leaving` says which elements are on their way
+ *   out): no second copy, since two links to one URL are two active sheets.
+ *   An owned one that was off is switched back on. Its owner is the outermost
+ *   boundary still on screen that links it: a sheet a layout and a page under
+ *   it both link stays the layout's while the layout is held (a reduced
+ *   response re-rendered only the page), and is handed to the incoming owner
+ *   once the old one is gone (the swap replaces it, or the sheet was off), so
+ *   a later swap of the new owner's range can retire it.
+ * - The incoming link is one a snapshot recorded as off, or one of the
+ *   router's temporary copies a snapshot captured: nothing to do.
+ * - The router's temporary copy of the file is loading (stylesheets.js): it
+ *   is adopted as the page's own link, where it already sits.
+ * - An incoming OWNED sheet with neither is inserted root to leaf
+ *   (`placeOwnedLink`), the order a full load puts them in.
+ * - Anything else is left to the caller's append.
+ *
+ * In `frame` mode (a frame swap whose response turned out to be a whole
+ * page) nothing owned is switched on, re-owned, adopted or inserted: the page
+ * around the frame decides which sheets apply, and a frame swap never
+ * switches one off either.
+ *
+ * @param {{ base?: string | null, frame?: boolean, segment?: string | null, leaving?: (el: Element) => boolean }} [opts]
+ *   `base` is the URL the incoming document came from, which its relative
+ *   hrefs resolve against; `segment` is the range this swap replaces (`/` for
+ *   a full-body swap), whose owners are on their way out.
+ * @returns {(el: Element, clone: (el: Element) => Element) => boolean}
+ */
+export function stylesheetMerge(opts = {}) {
+  const base = opts.base || (typeof document !== 'undefined' ? document.baseURI : '');
+  /** @type {Map<string, HTMLLinkElement>} */
+  const live = new Map();
+  /** The router's load-before-swap copies (stylesheets.js), by key. */
+  /** @type {Map<string, HTMLLinkElement>} */
+  const copies = new Map();
+  for (const el of document.querySelectorAll('link[href]')) {
+    if (!isStylesheetLink(el)) continue;
+    const inHead = el.parentNode === document.head;
+    if (!inHead && opts.leaving && opts.leaving(el)) continue;
+    const key = liveKey(el);
+    if (!key) continue;
+    const into = el.hasAttribute(PRELOAD_ATTR) ? (inHead ? copies : null) : live;
+    if (into && !into.has(key)) into.set(key, /** @type {HTMLLinkElement} */ (el));
+  }
+  return (incoming, clone) => {
+    // A link a snapshot recorded as off, or one of the router's temporary
+    // load-before-swap copies a snapshot captured mid-navigation: neither is
+    // a sheet that page used, so neither is appended or switched on.
+    if (incoming.hasAttribute(OFF_ATTR) || incoming.hasAttribute(PRELOAD_ATTR)) return true;
+    const key = keyFor(incoming, base);
+    if (!key) return false;
+    const owner = incoming.getAttribute(OWNER_ATTR);
+    const existing = live.get(key);
+    if (existing) {
+      if (opts.frame) return true;
+      const wasOff = existing.hasAttribute(OFF_ATTR);
+      if (wasOff) setOff(existing, false);
+      const held = existing.getAttribute(OWNER_ATTR);
+      if (owner && held !== null && held !== owner) {
+        // The held owner stays only while it is on screen and encloses the
+        // incoming one: a layout this response did not re-render. A held
+        // owner the swap replaces, one whose sheet was off, or one inside the
+        // incoming owner gives way.
+        const heldStays = !wasOff
+          && !(opts.segment != null && segmentWithin(held, opts.segment))
+          && segmentWithin(owner, held);
+        if (!heldStays) existing.setAttribute(OWNER_ATTR, owner);
+      }
+      return true;
+    }
+    const copy = opts.frame ? null : copies.get(key);
+    if (copy) {
+      for (const attr of incoming.attributes) {
+        if (attr.name === 'href' || attr.name === 'nonce') continue;
+        // The copy is still held: its media goes into the held slot, and is
+        // put back when the commit releases the incoming sheets.
+        if (attr.name === 'media' && copy.hasAttribute(HELD_MEDIA_ATTR)) copy.setAttribute(HELD_MEDIA_ATTR, attr.value);
+        else copy.setAttribute(attr.name, attr.value);
+      }
+      copy.removeAttribute(PRELOAD_ATTR);
+      copies.delete(key);
+      live.set(key, copy);
+      return true;
+    }
+    if (!owner) return false;
+    if (opts.frame) return true;
+    const node = /** @type {HTMLLinkElement} */ (clone(incoming));
+    // Absolute, so the inserted link names the file the response meant
+    // whatever the document's URL is when it is next read.
+    try { node.setAttribute('href', new URL(/** @type {string} */ (incoming.getAttribute('href')), base).href); } catch { /* keep as authored */ }
+    placeOwnedLink(node, owner);
+    liveKeys.set(node, key);
+    live.set(key, node);
+    return true;
+  };
+}
+
+/**
+ * Let the incoming page's sheets apply: release every held link that is not
+ * switched off, meaning the router's load-before-swap copies (stylesheets.js)
+ * and the ones the merge adopted. Called inside the swap commit, so the
+ * outgoing page, and a view transition's capture of it, never paint with the
+ * incoming page's CSS.
+ */
+export function releaseIncomingSheets() {
+  if (typeof document === 'undefined' || !document.head) return;
+  for (const el of document.head.querySelectorAll(`link[${HELD_MEDIA_ATTR}]`)) {
+    if (!el.hasAttribute(OFF_ATTR)) releaseMedia(el);
+  }
+}
+
+/**
+ * Switch off every owned stylesheet whose boundary sits at or below the
+ * swapped `segment` and that the incoming page does not link, in its head or
+ * its body. Called inside the swap commit of the boundary tiers, a replace or
+ * a morph (the server re-rendered everything inside that range, so the
+ * incoming page carries every owned sheet the range still uses), and of a
+ * full-body swap whose response is known to be complete. Never from a frame
+ * swap, nor from a full-body swap whose head can be a reduced one that omits
+ * what the client already has (#936).
+ *
+ * @param {string} segment  The segment of the range being swapped.
+ * @param {ParentNode | null} incoming  The incoming document (head and body).
+ * @param {string | null} [base]  The URL the incoming document came from.
+ */
+export function switchOffDepartedStylesheets(segment, incoming, base) {
+  if (typeof document === 'undefined' || !document.head) return;
+  const from = base || document.baseURI;
+  const carried = new Set();
+  if (incoming) {
+    for (const el of incoming.querySelectorAll('link[href]')) {
+      // A snapshot taken mid-navigation can hold the router's temporary copy
+      // of the NEXT page's sheet; it does not mean the page used it.
+      if (!isStylesheetLink(el) || el.hasAttribute(OFF_ATTR) || el.hasAttribute(PRELOAD_ATTR)) continue;
+      const key = keyFor(el, from);
+      if (key) carried.add(key);
+    }
+  }
+  for (const el of document.head.querySelectorAll(`link[${OWNER_ATTR}]`)) {
+    if (el.hasAttribute(PRELOAD_ATTR) || el.hasAttribute(OFF_ATTR) || el.hasAttribute('disabled') || !isStylesheetLink(el)) continue;
+    const owner = /** @type {string} */ (el.getAttribute(OWNER_ATTR));
+    if (!segmentWithin(owner, segment)) continue;
+    const key = liveKey(el);
+    if (key && carried.has(key)) continue;
+    setOff(/** @type {HTMLLinkElement} */ (el), true);
+  }
+}

package/src/router-client/prefetch.js

@@ -92,10 +92,9 @@ function prefetchRefusedRecently(key) {
  * dev live-reload path, where an edit can add or remove a `Suspense` boundary
  * and so start or stop the route streaming. Only an edit to a file the browser
  * does NOT download arrives there; anything that SHIPS takes a full reload
- * instead. A `loading.{js,ts}` reloads either way, though for two different
- * reasons: editing or deleting one reloads because it can never be elided and
- * so always ships, while ADDING one reloads because a brand-new file is in no
- * set the previous build produced.
+ * instead. A `loading.{js,ts}` is a route module, so editing one arrives here
+ * like a page edit (it never ships, #1686), while ADDING one reloads because a
+ * brand-new file is in no set the previous build produced.
  *
  * NEITHER form of `revalidate` clears them, which is a cost/benefit call rather
  * than an impossibility. It is the post-MUTATION api an app calls after an RPC
@@ -662,6 +661,9 @@ export function onPrefetchIntent(e) {
   prefetchHoverTimer = setTimeout(() => {
     prefetchHoverTimer = null;
     prefetchHoverAnchor = null;
+    // A navigation during the dwell can swap the hovered link out of the
+    // page; a link nobody can click any more warms nothing.
+    if (!anchor.isConnected) return;
     // Resolved at FIRE time, so it sees the document a click at this moment
     // would (a soft nav during the dwell can change which frame encloses it).
     prefetch(href, resolveTargetFrameId(anchor));

package/src/router-client/root-attrs.js

@@ -0,0 +1,43 @@
+/**
+ * `<html>` and `<body>` attributes follow the server across a soft navigation
+ * (#1686). The root layout owns them (`<html class=${theme}>`, `<body
+ * class=...>`), and a Next.js developer expects a changed theme cookie to
+ * show once the action or navigation lands, as it does when the root layout
+ * re-renders there. The swap replaces content inside `<body>`, so without
+ * this the attributes stayed as the first load left them until a reload.
+ *
+ * Only attributes the SERVER rendered are touched: the server lists their
+ * names in `data-wj-html` / `data-wj-body`, so an attribute a script sets in
+ * the browser (a theme bootstrap writing `data-theme` from localStorage) is
+ * never removed. A response that did not render the root layout (a reduced
+ * `X-Webjs-Have` fragment) carries no list and changes nothing.
+ */
+
+const MARKS = /** @type {const} */ ([['documentElement', 'data-wj-html'], ['body', 'data-wj-body']]);
+
+/** @param {string | null} v */
+const names = (v) => (v || '').split(/\s+/).filter(Boolean);
+
+/**
+ * Bring the live `<html>` and `<body>` attributes in line with an incoming
+ * page's, for the attributes its server rendered.
+ * @param {Document} doc the parsed incoming page
+ */
+export function syncRootAttributes(doc) {
+  if (typeof document === 'undefined' || !doc) return;
+  for (const [key, mark] of MARKS) {
+    const incoming = /** @type {Element | null} */ (/** @type any */ (doc)[key]);
+    const live = /** @type {Element | null} */ (/** @type any */ (document)[key]);
+    if (!incoming || !live || !incoming.hasAttribute(mark)) continue;
+    const next = names(incoming.getAttribute(mark));
+    for (const n of names(live.getAttribute(mark))) {
+      if (!next.includes(n)) live.removeAttribute(n);
+    }
+    for (const n of next) {
+      const v = incoming.getAttribute(n);
+      if (v === null) live.removeAttribute(n);
+      else if (live.getAttribute(n) !== v) live.setAttribute(n, v);
+    }
+    live.setAttribute(mark, next.join(' '));
+  }
+}

package/src/router-client/stream.js

@@ -8,6 +8,7 @@
  */
 import { warnDropped } from './diagnostics.js';
 import { upgradeTree } from './upgrade.js';
+import { navigate } from './navigator.js';
 
 /**
  * Forward streamed Suspense resolver templates from the fetched body to
@@ -155,6 +156,12 @@ export function applyStreamedResolve(id, content) {
   const tpl = document.createElement('template');
   tpl.innerHTML = content;
   const inserted = [...tpl.content.childNodes];
+  // A boundary whose content threw redirect() on the server streams a marker
+  // (#1686): follow it the way a first load follows its refresh.
+  for (const n of inserted) {
+    const to = n.nodeType === 1 ? /** @type {Element} */ (n).getAttribute('data-webjs-redirect') : null;
+    if (to) { navigate(to, { replace: true }); return; }
+  }
   boundary.replaceWith(tpl.content);
   // Upgrade any custom elements now that they are connected (belt-and-braces:
   // a connected, defined element upgrades on insertion, but a fragment that was

package/src/router-client/stylesheets.js

@@ -0,0 +1,191 @@
+// @ts-check
+/**
+ * Stylesheets a navigation brings with it are loaded BEFORE the swap (#1666).
+ *
+ * A soft navigation parses the response and applies it in the same task, so a
+ * `<link rel="stylesheet">` the incoming page carries starts loading only once
+ * it is in the live document, and the new content paints for a frame or more
+ * without it: a flash of the page in the wrong styles. Turbo Drive closes the
+ * same gap by appending each new head stylesheet and awaiting its `load`
+ * before it renders, Remix v2 preloads a route's links and awaits them before
+ * it commits the transition, and the Next.js app router holds a commit until
+ * new route CSS has loaded.
+ *
+ * WebJs reads the BODY as well as the head, because a section's stylesheet can
+ * only ride the body on a soft navigation: only the root layout may write
+ * `<head>`, and the `X-Webjs-Have` short-circuit never re-renders it, so a
+ * nested layout or a page that needs a stylesheet emits its link inline. On a
+ * frame navigation only the frame's own subtree is read, since nothing else in
+ * the response is swapped in.
+ *
+ * The router adds no stylesheet state of its own; it only bridges the load
+ * gap, Remix's preload-then-render shape. Each stylesheet the live document
+ * does not already link gets a TEMPORARY copy in `<head>`, marked
+ * `data-webjs-preload-style`, and the swap waits for it. Once the swap has
+ * committed, `releaseIncomingStylesheets` removes each copy as soon as the
+ * page's own link to the same file has loaded (from the HTTP cache by then),
+ * so some copy of the sheet applies on every frame and none outlives it. A
+ * copy whose file the swapped-in page does not link is removed at once, and
+ * so is every copy of a navigation that was superseded or discarded. A sheet
+ * that fails or stalls never holds a navigation hostage: an `error` resolves
+ * the wait, and so does a timeout, Turbo's 2 seconds.
+ */
+import { PRELOAD_ATTR, relIsStylesheet } from './constants.js';
+import { HELD_MEDIA_ATTR, OWNER_ATTR, holdMedia, placeOwnedLink } from './owned-styles.js';
+import { getCspNonce } from './head-merge.js';
+
+/** How long a navigation waits for one stylesheet before it swaps anyway. */
+export const STYLESHEET_TIMEOUT_MS = 2000;
+
+/** The attribute that marks the router's temporary copies (defined in the leaf). */
+export { PRELOAD_ATTR };
+
+/**
+ * Is `el` a stylesheet that applies now: a `<link>` whose `rel` names
+ * `stylesheet` but not `alternate` (an alternate sheet is off until chosen),
+ * that is not `disabled`, has an `href`, and has no `media` query that does
+ * not match.
+ * @param {Element} el
+ */
+function isActiveStylesheet(el) {
+  if (!relIsStylesheet(el)) return false;
+  if (el.hasAttribute('disabled') || !el.getAttribute('href')) return false;
+  // A held link (owned-styles.js) applies under its author's media once released.
+  const media = el.hasAttribute(HELD_MEDIA_ATTR) ? el.getAttribute(HELD_MEDIA_ATTR) : el.getAttribute('media');
+  if (media && typeof matchMedia === 'function') {
+    try { if (!matchMedia(media).matches) return false; } catch { /* an unparseable query applies to nothing */ return false; }
+  }
+  return true;
+}
+
+/**
+ * Resolve when `link` has loaded or failed, or after `timeout` ms.
+ * @param {HTMLLinkElement} link
+ * @param {number} timeout
+ * @returns {Promise<void>}
+ */
+function waitForLoad(link, timeout) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      link.removeEventListener('load', done);
+      link.removeEventListener('error', done);
+      resolve();
+    };
+    const timer = setTimeout(done, timeout);
+    link.addEventListener('load', done);
+    link.addEventListener('error', done);
+  });
+}
+
+/**
+ * @typedef {{ ready: Promise<void>, copies: HTMLLinkElement[] }} IncomingStylesheets
+ */
+
+/**
+ * Start loading every stylesheet the incoming page links that the live
+ * document does not, through a temporary copy in `<head>`. Returns `null` when
+ * there is nothing new, so the caller swaps in the same task as before and a
+ * navigation that brings no stylesheet costs no extra time. Otherwise returns
+ * the copies and a promise that settles when all of them have loaded, failed
+ * or timed out; pass the result to `releaseIncomingStylesheets` once the swap
+ * has committed, or once the navigation is abandoned.
+ *
+ * @param {Document} doc  The parsed incoming page.
+ * @param {string | null | undefined} baseUrl  The URL `doc` was fetched from,
+ *   which a relative `href` in it resolves against.
+ * @param {string | null} [frameId]  On a frame navigation, the frame being
+ *   swapped: only its subtree in `doc` is read.
+ * @param {number} [timeout]
+ * @returns {IncomingStylesheets | null}
+ */
+export function loadIncomingStylesheets(doc, baseUrl, frameId, timeout = STYLESHEET_TIMEOUT_MS) {
+  if (typeof document === 'undefined' || !doc || !document.head) return null;
+  /** @type {ParentNode | null} */
+  let scope = doc;
+  if (frameId) {
+    try { scope = doc.querySelector(`webjs-frame#${CSS.escape(frameId)}`); } catch { scope = null; }
+  }
+  if (!scope) return null;
+  const base = baseUrl || document.baseURI;
+  /** @param {string} href */
+  const resolve = (href) => {
+    try { return new URL(href, base).href; } catch { return null; }
+  };
+  // What the page already links. Another navigation's temporary copies do
+  // not count: they are released on that navigation's own schedule.
+  const live = new Set();
+  for (const el of document.querySelectorAll('link[href]')) {
+    if (el.hasAttribute(PRELOAD_ATTR) || !isActiveStylesheet(el)) continue;
+    const href = /** @type {HTMLLinkElement} */ (el).href;
+    if (href) live.add(href);
+  }
+  const nonce = getCspNonce();
+  /** @type {HTMLLinkElement[]} */
+  const copies = [];
+  /** @type {Promise<void>[]} */
+  const waits = [];
+  for (const el of scope.querySelectorAll('link[href]')) {
+    if (!isActiveStylesheet(el)) continue;
+    const href = resolve(/** @type {string} */ (el.getAttribute('href')));
+    if (!href || live.has(href)) continue;
+    live.add(href);
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.setAttribute(PRELOAD_ATTR, '');
+    // The attributes that change how the file is fetched and applied travel
+    // with it, so the copy loads exactly what the page asked for. The nonce is
+    // the LIVE page's: the browser checks CSP against the nonce of the original
+    // page load, never a later response's (#1050).
+    for (const name of ['media', 'crossorigin', 'integrity', 'referrerpolicy']) {
+      const value = el.getAttribute(name);
+      if (value) link.setAttribute(name, value);
+    }
+    if (nonce) link.setAttribute('nonce', nonce);
+    link.href = href;
+    // Loaded without applying: the outgoing page, and a view transition's
+    // capture of it, must not paint with the incoming CSS. The swap commit
+    // releases it (owned-styles.js `releaseIncomingSheets`).
+    holdMedia(link);
+    copies.push(link);
+    waits.push(waitForLoad(link, timeout));
+    // A sheet a layout owns (#1669) goes where the page's own link belongs,
+    // so the head merge can adopt this copy as that link instead of adding a
+    // second one; any other copy goes at the end of the head.
+    const owner = el.getAttribute(OWNER_ATTR);
+    if (owner) {
+      link.setAttribute(OWNER_ATTR, owner);
+      placeOwnedLink(link, owner);
+    } else {
+      document.head.appendChild(link);
+    }
+  }
+  if (!copies.length) return null;
+  return { ready: Promise.all(waits).then(() => undefined), copies };
+}
+
+/**
+ * Remove the temporary copies `loadIncomingStylesheets` made. Each one stays
+ * until the live document's own link to the same file has loaded (or failed,
+ * or the timeout passes), so the sheet applies on every frame of the handoff;
+ * a copy with no such link (a discarded response, a frame swap that did not
+ * bring the file, a superseded navigation) goes at once.
+ *
+ * @param {IncomingStylesheets | null} incoming
+ * @param {number} [timeout]
+ */
+export function releaseIncomingStylesheets(incoming, timeout = STYLESHEET_TIMEOUT_MS) {
+  if (!incoming || typeof document === 'undefined') return;
+  for (const copy of incoming.copies) {
+    // Gone already, or adopted by the head merge as the page's own link.
+    if (!copy.isConnected || !copy.hasAttribute(PRELOAD_ATTR)) continue;
+    /** @type {HTMLLinkElement | null} */
+    let twin = null;
+    for (const el of document.querySelectorAll('link[href]')) {
+      if (el === copy || el.hasAttribute(PRELOAD_ATTR) || !isActiveStylesheet(el)) continue;
+      if (/** @type {HTMLLinkElement} */ (el).href === copy.href) { twin = /** @type {HTMLLinkElement} */ (el); break; }
+    }
+    if (!twin || twin.sheet) { copy.remove(); continue; }
+    waitForLoad(twin, timeout).then(() => copy.remove());
+  }
+}