@webjsdev/core 0.7.65 → 0.8.0

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());
+  }
+}

package/src/router-client/swap.js

@@ -11,8 +11,9 @@ import { collectBoundaries, planBoundarySwap } from './boundaries.js';
 import { reportFallback } from './diagnostics.js';
 import { blurOutgoingFocus, diffChildren, replaceBoundaryRange, resyncEnclosingHostSlots, swapMarkerRange } from './dom-differ.js';
 import { trackedReloadSignature } from './frames.js';
-import { addNewHeadElements, mergeHead } from './head-merge.js';
+import { addNewHeadElements, mergeHead, mergeHeadStylesheets } from './head-merge.js';
 import { morphLayoutChrome, planLayoutChrome } from './layout-chrome.js';
+import { primeLiveStylesheetKeys, releaseIncomingSheets, switchOffDepartedStylesheets } from './owned-styles.js';
 import { clearPrefetchRefused, prefetchClearAll } from './prefetch.js';
 import { snapshotCache } from './snapshot-cache.js';
 import { hardNavigate } from './state.js';
@@ -84,6 +85,13 @@ export let _swapCommit = Promise.resolve();
  *   history (a revalidation, a refresh, the popstate restore).
  */
 export function applySwap(doc, frameId, revalidating, href, incomingBuild, incomingSrc, refresh, recordHistoryNow) {
+  // The URL the incoming page came from, which its relative stylesheet hrefs
+  // resolve against, and the live sheets' keys taken NOW, while the document
+  // still has the outgoing page's URL: every commit point below records the
+  // new history entry before it merges the head (#1669).
+  let incomingBase = typeof location !== 'undefined' ? location.href : '';
+  if (href) { try { incomingBase = new URL(href, incomingBase).href; } catch { /* keep the live url */ } }
+  primeLiveStylesheetKeys();
   // SSR action seeding (#472): ingest the incoming page's seed payload BEFORE
   // its components are grafted into the live DOM and upgrade, so a
   // soft-navigated async component resolves from the seed instead of
@@ -279,7 +287,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
       // ADD-ONLY head merge: preserve runtime-generated head content
       // (Tailwind CSS injection, etc.) that the outer layout's scripts
       // already produced.
-      addNewHeadElements(doc.head);
+      addNewHeadElements(doc.head, { base: incomingBase, frame: true });
       // `diffChildren` -> `reconcileChildren` regrafts permanent elements
       // by node identity (it imports the incoming children first, then
       // swaps the live permanent node into the imported tree), so the live
@@ -288,6 +296,8 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
       // ALSO progressively streams a Suspense boundary gates its resolves on the
       // committed frame swap, not a stale prior _swapCommit (#1048).
       _swapCommit = runWithTransition(() => {
+        // The frame's incoming sheets loaded held; they apply with the swap.
+        releaseIncomingSheets();
         diffChildren(target, source);
         reactivateScripts(target);
         upgradeCustomElements(target);
@@ -334,7 +344,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     // commit point without a reader having to prove reachability first, which
     // is what stops the next person adding a commit point from omitting it.
     if (recordHistoryNow) recordHistoryNow();
-    swapFullBody(doc);
+    swapFullBody(doc, incomingBase, true);
     return;
   }
 
@@ -361,7 +371,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   if (plan && refresh === 'layouts' && !chrome) {
     ingestSeeds();
     if (recordHistoryNow) recordHistoryNow();
-    swapFullBody(doc);
+    swapFullBody(doc, incomingBase, true);
     return;
   }
 
@@ -375,11 +385,32 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
     if (recordHistoryNow) recordHistoryNow();
     const { mode, live, incoming } = plan;
     // ADD-ONLY head merge: the outer layout stays mounted, so its head-bound
-    // runtime state (Tailwind injection, etc.) must not be invalidated.
-    addNewHeadElements(doc.head);
+    // runtime state (Tailwind injection, etc.) must not be invalidated. It runs
+    // ahead of the commit, as the incoming sheets' load-before-swap copies
+    // already do (#1666, Turbo's order), so the new page's sheets apply from
+    // the swap's first frame.
+    // Its stylesheets wait for the commit (#1669, below).
+    addNewHeadElements(doc.head, { base: incomingBase, styles: false });
+    // A live element inside the range this swap replaces is on its way out,
+    // so a stylesheet link there does not count as one the page keeps.
+    /** @param {Element} el */
+    const leaving = (el) => !!(live.start.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)
+      && !!(live.end.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING);
     _swapCommit = runWithTransition(() => {
+      // Everything stylesheet-related happens inside the commit, so the
+      // outgoing page, and a view transition's capture of it, keep exactly the
+      // sheets that page used, and the crossing restyles once (#1669): the
+      // incoming sheets (loaded held, stylesheets.js) are adopted, switched
+      // back on or inserted, then released, before the new markup lands.
+      mergeHeadStylesheets(doc.head, { base: incomingBase, segment: plan.segment, leaving });
+      releaseIncomingSheets();
       if (mode === 'replace') replaceBoundaryRange(live, incoming);
       else swapMarkerRange(live, incoming, doc);
+      // The swapped range's own stylesheets go with it unless the incoming
+      // page links them, in its head or its body, on a replace and on a morph
+      // alike: the server re-rendered the whole range either way, so a sheet a
+      // searchParams change dropped is retired too.
+      switchOffDepartedStylesheets(plan.segment, doc, incomingBase);
       // No key sync is needed on the anchor's own comments: the plan's anchor
       // carries EQUAL live/incoming route-keys in every tier (a changed-key
       // REPLACE anchors at a parent already compared equal; the other tiers
@@ -438,7 +469,7 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
   // because the user is already viewing the page).
   ingestSeeds();   // committed: past both discard branches above
   if (recordHistoryNow) recordHistoryNow();
-  swapFullBody(doc);
+  swapFullBody(doc, incomingBase, false);
 }
 
 /**
@@ -460,9 +491,12 @@ export function applySwap(doc, frameId, revalidating, href, incomingBuild, incom
  * it only past their own discard branches.
  *
  * @param {Document} doc
+ * @param {string} incomingBase  the URL the incoming page came from
+ * @param {boolean} complete  the response rendered every layout (no X-Webjs-Have), so it can retire a departed section's sheets
  */
-function swapFullBody(doc) {
-  mergeHead(doc.head);
+function swapFullBody(doc, incomingBase, complete) {
+  // Its stylesheets wait for the commit, as on a boundary swap (#1669).
+  mergeHead(doc.head, { base: incomingBase, styles: false });
   // Persist permanent elements by node identity across the full-body
   // swap: move each live [data-webjs-permanent][id] node into the matching
   // position in the incoming body BEFORE replaceChildren reads it, so the
@@ -470,7 +504,13 @@ function swapFullBody(doc) {
   regraftPermanentElements(document.body, doc.body);
   const newChildren = [...doc.body.childNodes];
   const doSwap = () => {
+    // The whole body is replaced, so every live body link is leaving.
+    mergeHeadStylesheets(doc.head, { base: incomingBase, segment: '/', leaving: () => true });
+    releaseIncomingSheets();
     document.body.replaceChildren(...newChildren);
+    // Only a response known to be complete can say a section's sheet is gone:
+    // the background restore path's head can be a reduced one (#936).
+    if (complete) switchOffDepartedStylesheets('/', doc, incomingBase);
     reactivateScripts(document.body);
     upgradeCustomElements(document.body);
     blurOutgoingFocus();

package/src/sentinels.d.ts

@@ -0,0 +1,2 @@
+export const nothing: unique symbol;
+export const noChange: unique symbol;

package/src/sentinels.js

@@ -0,0 +1,4 @@
+/** Clear a rendered value using Lit's position-specific rules. */
+export const nothing = Symbol.for('webjs.nothing');
+/** Keep the previously committed value. */
+export const noChange = Symbol.for('webjs.noChange');

package/src/webjs-config.d.ts

@@ -94,7 +94,7 @@ export interface WebjsRegenerateRule {
   output: string;
   /** The shell command that rebuilds `output` (the same command prod uses in `start.before`, so dev and prod cannot diverge). */
   command: string;
-  /** Source files/directories whose newest mtime is compared to `output`'s; a newer one (or a missing output) triggers the rebuild. */
+  /** Source files/directories the output is built from. Every build records a fingerprint of the files under them (path, size, mtime) in `.webjs/regenerate.json`, and the output is rebuilt when that fingerprint, the command, or the output itself no longer matches the record, or the output is missing (#1672). `webjs regenerate` builds and records outside the dev server. */
   inputs?: string[];
 }