@rsc-kit/core 0.20.6 → 0.20.8

package/dist/js/navigate.js

@@ -5,8 +5,10 @@
  * The Flight deserializer is injected by createViteRscApp to avoid
  * duplicate bundling of react-server-dom-webpack.
  */
-import { isStaleAssetError, loadDocumentOnce } from "./staleAssets";
+import { announceDocumentLoad, isStaleAssetError, loadDocumentOnce, } from "./staleAssets";
 import { isUpdated, markStale } from "./updateStore";
+import { navigationAbandoned, navigationCommitted, navigationReached, navigationStarted } from "./perf";
+import { preloadImages } from "./imagePreload";
 import { isSafeRedirect } from "../safeUrl.js";
 import { reportReachable } from "./onlineStore";
 import { clearSlots, setSlot } from "./slotStore";
@@ -18,6 +20,22 @@ let version = "";
 const navigating = new Set();
 let onNavigate = null;
 let onRestore = null;
+/**
+ * Re-render the whole document in place, for revalidate("all"): the page the
+ * visitor is on, not a page they went to. Without one registered, the
+ * navigation handler at depth 0 is used, which shows the tree as a page.
+ */
+let onReplaceRoot = null;
+/** Whether a navigation to the key would reveal a held page, asked without revealing it. */
+let isHeldPage = null;
+/** Drop the pages held behind the one on screen - after a mutation. */
+let dropHeld = null;
+/**
+ * Render a decoded page in the background, hidden, before the click - see
+ * warm(). Given the same tree the navigation will hand to onNavigate, so
+ * that the navigation is a reveal of work already done rather than a render.
+ */
+let onPrerender = null;
 /**
  * How stale a held page may be and still be revealed by a link.
  *
@@ -41,6 +59,33 @@ let interceptManifest = [];
 // The layout chain currently mounted, outermost first. Sent so the server can
 // skip re-rendering the layouts still on screen.
 let heldLayouts = [];
+/**
+ * The chain each page was shown under, by retention key.
+ *
+ * A held page revealed - the back button, or a link to the page just left -
+ * puts its layouts back on screen, and the chain has to say so. It used to
+ * keep the chain of the page being left: home, a category, back to home,
+ * then another category claimed the first category's layout as mounted. The
+ * server sent the page alone, and the client put it in the boundary that
+ * layout owns - inside the hidden category. The url changed and the page did
+ * not, and every tap after it did the same, until a reload. The demo froze
+ * on a phone within a dozen taps.
+ *
+ * Bounded like the payload cache: a key that is no longer held is never
+ * asked for, so the oldest can go.
+ */
+const chainOf = new Map();
+const MAX_CHAINS = 64;
+function rememberChain(key) {
+    chainOf.delete(key);
+    chainOf.set(key, heldLayouts);
+    while (chainOf.size > MAX_CHAINS) {
+        const oldest = chainOf.keys().next().value;
+        if (oldest === undefined)
+            break;
+        chainOf.delete(oldest);
+    }
+}
 /**
  * The boundary depth an interception was rendered at, while one is showing.
  *
@@ -60,7 +105,22 @@ let interceptedAtDepth = null;
  * screen with everything the user typed into it.
  */
 let interceptedOver = null;
+/**
+ * The url an interception was opened from, whichever way it was rendered -
+ * the page still on screen under the modal. Only stillShowing asks.
+ */
+let interceptedFrom = null;
 const DEFAULT_PREFETCH_TTL = 30_000;
+/**
+ * How long a payload the host marked `public` is kept.
+ *
+ * The same build-time bytes for everyone, so the only way it changes is a
+ * deploy, and the version handshake catches that on the tap. Thirty seconds
+ * was Next's figure for a dynamic page; its static pages are held five
+ * minutes, and a landing page read for a minute before the tap on Sign in
+ * was, at thirty, an expired entry and a round trip on a phone.
+ */
+const STATIC_PREFETCH_TTL = 300_000;
 /**
  * How many prefetched payloads are kept. Entries carry a TTL but were only
  * dropped when read again, so a long session hovering its way through a big
@@ -119,6 +179,7 @@ export function seedStaticChain(url) {
     if (!segments)
         return false;
     heldLayouts = segments.chain;
+    rememberChain(retentionKey(url, null));
     return true;
 }
 /**
@@ -207,6 +268,7 @@ async function tellWorkerServerBuild(build) {
  */
 export function setHeldLayouts(chain) {
     heldLayouts = chain;
+    rememberChain(retentionKey(window.location.href, null));
 }
 export function getHeldLayouts() {
     return heldLayouts;
@@ -214,6 +276,34 @@ export function getHeldLayouts() {
 export function setNavigateHandler(fn) {
     onNavigate = fn;
 }
+export function setReplaceRootHandler(fn) {
+    onReplaceRoot = fn;
+}
+export function setHeldHandlers(held, drop) {
+    isHeldPage = held;
+    dropHeld = drop;
+}
+/**
+ * Everything the router holds about pages other than the one on screen,
+ * dropped: prefetched payloads, and pages kept behind this one.
+ *
+ * After an action that revalidated. The list a link prefetched before the
+ * mutation still shows the table without the new row - visit() landed on
+ * it with no request made, and a reload showed the row. What was fetched
+ * before a write is not a cache of what is true after it; the pages held
+ * for the back button are from before it too.
+ */
+export function forgetOtherPages() {
+    for (const [key, controller] of prefetchControllers) {
+        controller.abort();
+        prefetchControllers.delete(key);
+    }
+    cache.clear();
+    dropHeld?.();
+}
+export function setPrerenderHandler(fn) {
+    onPrerender = fn;
+}
 /**
  * How the router reveals a page that is still mounted behind the current one.
  *
@@ -480,6 +570,7 @@ export async function navigate(url, opts) {
     // advice. Not for a restore: going back to a page still held asks the
     // server for nothing.
     if (!opts?.restore && isUpdated()) {
+        announceDocumentLoad(url, "newer-build");
         window.location.href = url;
         return;
     }
@@ -488,12 +579,14 @@ export async function navigate(url, opts) {
     }
     // External URLs can't be fetched (CORS) — go directly to full page navigation
     if (isExternalUrl(url)) {
+        announceDocumentLoad(url, "external");
         window.location.href = url;
         return;
     }
     // A route.ts answers with a Response, not a page: a download, a redirect
     // that decides where someone belongs, a sign-out. The browser goes there.
     if (isApiRoute(url)) {
+        announceDocumentLoad(url, "api-route");
         window.location.href = url;
         return;
     }
@@ -504,6 +597,7 @@ export async function navigate(url, opts) {
     }
     // Abort any in-flight navigation
     activeController?.abort();
+    navigationStarted(url);
     // Not window.stop(). It used to be called here while the document was
     // still loading, to free a single-threaded server for the new request -
     // and it cancels every load the page has in flight: the client chunks a
@@ -538,6 +632,7 @@ export async function navigate(url, opts) {
         retentionKey(url, null) === retentionKey(interceptedOver, null)) {
         clearSlots();
         interceptedOver = null;
+        interceptedFrom = null;
         interceptedAtDepth = null;
         if (opts?.replace) {
             history.replaceState({ rscUrl: url }, "", url);
@@ -546,6 +641,7 @@ export async function navigate(url, opts) {
             history.pushState({ rscUrl: url }, "", url);
         }
         window.dispatchEvent(new CustomEvent("rsc-navigate", { detail: url }));
+        navigationCommitted();
         return;
     }
     // Not when the target is the page already showing: asking for this page
@@ -568,8 +664,14 @@ export async function navigate(url, opts) {
         onRestore?.(activityKey, opts?.restore ? undefined : revealWithin)) {
         // A restored tree carries its own slot contents, so the flag only has to
         // reflect whether what is now showing is an intercepted view.
-        if (!interceptSlot)
+        if (!interceptSlot) {
             interceptedAtDepth = null;
+            interceptedFrom = null;
+        }
+        // Its layouts are the ones on screen now - see chainOf.
+        const chain = chainOf.get(activityKey);
+        if (chain)
+            heldLayouts = chain;
         // opts?.replace, not opts.replace: this branch used to be reachable only
         // with opts.restore set, so opts was always there. A link reaches it now
         // with nothing passed at all.
@@ -580,6 +682,7 @@ export async function navigate(url, opts) {
             history.pushState({ rscUrl: url }, "", url);
         }
         window.dispatchEvent(new CustomEvent("rsc-navigate", { detail: url }));
+        navigationCommitted();
         return;
     }
     // A prefetched payload was rendered against the chain held at prefetch time.
@@ -651,6 +754,7 @@ export async function navigate(url, opts) {
             const contentType = response.headers.get("Content-Type") ?? "";
             if (staticPayloadSuffix === null &&
                 !contentType.includes("text/x-component")) {
+                announceDocumentLoad(url, `not-a-payload:${response.status}:${contentType.split(";")[0]}`);
                 window.location.href = url;
                 return;
             }
@@ -673,6 +777,7 @@ export async function navigate(url, opts) {
         let tree;
         try {
             tree = await treePromise;
+            navigationReached("decoded");
         }
         catch (error) {
             // A navigation another one overtook: its request was aborted, and
@@ -714,6 +819,7 @@ export async function navigate(url, opts) {
         }
         if (nextLayouts !== null)
             heldLayouts = nextLayouts;
+        rememberChain(activityKey);
         // The answer is one region, not a piece of the page: the host rendered
         // only the interceptor because the page underneath is already mounted and
         // still correct. Putting it in the slot leaves that page — and everything
@@ -721,6 +827,7 @@ export async function navigate(url, opts) {
         if (slotPayload !== null) {
             setSlot(slotPayload, tree);
             interceptedOver = interceptedOver ?? previousUrl;
+            interceptedFrom = interceptedFrom ?? previousUrl;
             interceptedAtDepth = null;
             return;
         }
@@ -729,6 +836,8 @@ export async function navigate(url, opts) {
         clearSlots();
         interceptedOver = null;
         interceptedAtDepth = interceptSlot ? segmentDepth : null;
+        interceptedFrom = interceptSlot ? (interceptedFrom ?? previousUrl) : null;
+        navigationReached("applied");
         onNavigate?.(tree, activityKey, segmentDepth);
         if (!opts?.preserveScroll && !interceptSlot) {
             // Wait for React to commit the DOM update before scrolling.
@@ -740,11 +849,13 @@ export async function navigate(url, opts) {
         window.dispatchEvent(new CustomEvent("rsc-navigate", { detail: url }));
     }
     catch (err) {
+        navigationAbandoned();
         if (err instanceof DOMException && err.name === "AbortError")
             return;
         // A chunk the deploy no longer serves: the browser would have loaded the
         // document, and the new names with it. Do what it would have done.
         if (isStaleAssetError(err)) {
+            announceDocumentLoad(url, `stale-asset:${String(err?.message ?? err).slice(0, 120)}`);
             window.location.href = url;
             return;
         }
@@ -768,12 +879,51 @@ export async function navigate(url, opts) {
  * is the same apply path a navigation uses — without a request, a url change
  * or a history entry.
  */
+/**
+ * Whether the page an action was invoked from is the one on screen.
+ *
+ * The one underneath, when an interception is showing: a modal opened after
+ * the submit sits over the same page.
+ */
+export function stillShowing(url) {
+    const key = retentionKey(url, null);
+    const now = retentionKey(window.location.pathname + window.location.search, null);
+    return key === now || (interceptedFrom !== null && key === retentionKey(interceptedFrom, null));
+}
+/**
+ * Put what an action re-rendered on screen.
+ *
+ * `from` is the url the action was invoked on - what the host rendered the
+ * trees for. A tap that left the page while the action was in flight has
+ * changed what is showing, and a document rendered for the page before
+ * cannot go under the url after: "Add to cart", then the brand link at
+ * once, showed the home page and then, when the answer landed, the product
+ * again under `/`. The write still happened, and the page on screen was
+ * fetched before it - so that page is asked for again, whole, instead.
+ */
+export function applyRevalidations(from, revalidated) {
+    // What was fetched or held before the write is from before it.
+    forgetOtherPages();
+    if (!stillShowing(from)) {
+        void refresh("all");
+        return;
+    }
+    for (const [target, tree] of Object.entries(revalidated)) {
+        applyRevalidated(target, tree);
+    }
+}
 export function applyRevalidated(target, tree) {
     const url = window.location.pathname + window.location.search;
     const key = retentionKey(url, null);
     if (target === "all") {
-        // Depth 0 replaces the root, which is what re-rendering the layouts means.
-        onNavigate?.(tree, key, 0);
+        // The whole document again, in place. Not a navigation to this url:
+        // the visible entry may be keyed by the url the document loaded with,
+        // and showing the tree under the current one made a second entry and
+        // remounted the app under it.
+        if (onReplaceRoot)
+            onReplaceRoot(tree);
+        else
+            onNavigate?.(tree, key, 0);
         return;
     }
     if (target === "page") {
@@ -801,6 +951,9 @@ export function applyRevalidated(target, tree) {
  */
 export async function refresh(target = "page") {
     const url = window.location.pathname + window.location.search;
+    // Asked because the data moved on; what was fetched or held before is
+    // from before.
+    forgetOtherPages();
     if (target !== "page" && target !== "all") {
         const response = await fetch(payloadUrl(url), {
             headers: {
@@ -903,7 +1056,20 @@ function restoreScroll(positions) {
     };
     apply(1);
 }
-export function prefetch(url, cacheForMs) {
+/**
+ * Fetch a page's payload ahead of the navigation that may ask for it.
+ *
+ * `intent` is the difference between a link that came into view and one the
+ * visitor is about to follow: a hover that settled, a touch. Only then is the
+ * payload decoded on arrival - decoding is what loads the client chunks the
+ * page names, and a viewport prefetch that decoded put the sign-in page's
+ * thirty chunks onto a landing page for every phone visitor. A touch leads
+ * its click by 100-300 ms, about a round trip, and a tap that found the
+ * bytes here but not the chunks spent that round trip after the click
+ * instead of before it: the tap-to-paint that was "not zero" beside Next,
+ * whose prefetch decodes as it lands.
+ */
+export function prefetch(url, cacheForMs, intent = false) {
     // Never a route.ts: fetching one runs it, and a hover is not a click.
     if (isApiRoute(url))
         return;
@@ -911,6 +1077,11 @@ export function prefetch(url, cacheForMs) {
     // in view, was a 14 KB payload for the page already on screen.
     if (retentionKey(url, null) === retentionKey(window.location.href, null))
         return;
+    // Nor a page still held behind this one, which a navigation would reveal
+    // rather than fetch: the page just left, whose link is on every page,
+    // was one wasted payload per navigation.
+    if (!matchIntercept(url) && isHeldPage?.(retentionKey(url, null), revealWithin))
+        return;
     // Nor anything, once this page is known to be the previous build: the
     // next navigation is a document load, and a payload it would not use is
     // a 409 for nothing - one per tap, measured.
@@ -920,20 +1091,73 @@ export function prefetch(url, cacheForMs) {
         return;
     const ttl = cacheForMs ?? DEFAULT_PREFETCH_TTL;
     const interceptSlot = matchIntercept(url);
+    const held = { intent, explicitTtl: cacheForMs !== undefined };
     if (interceptSlot) {
         // Intercepted route — only prefetch the intercepted variant
         const currentUrl = window.location.pathname + window.location.search;
         const cacheKey = retentionKeyFor(url, interceptSlot);
-        prefetchUrl(cacheKey, url, ttl, interceptSlot, currentUrl);
+        prefetchUrl(cacheKey, url, ttl, interceptSlot, currentUrl, held);
     }
     else {
-        prefetchUrl(url, url, ttl);
+        prefetchUrl(retentionKeyFor(url, null), url, ttl, undefined, undefined, held);
     }
 }
-function prefetchUrl(cacheKey, url, ttl, interceptSlot, refererUrl) {
+/**
+ * Do the click's work now: decode the held payload, which loads the chunks
+ * it names, and render the page hidden so the click is a reveal.
+ *
+ * The numbers this came from, on an iPhone with everything prefetched: a
+ * first visit to the landing page was 107 ms from tap to paint, 4 of them
+ * decoding and 87 rendering; a page still held from a visit before was
+ * 15 ms, a reveal. The render is the page's size on the phone's CPU, and
+ * nothing in the payload's path shrinks it - but it can be paid before the
+ * finger lifts. A touch leads its click by 100-300 ms; a settled hover, by
+ * 200 or more. React renders a hidden Activity at idle priority, so the
+ * work yields to scrolling, and the navigation then hands the boundary the
+ * same tree it prerendered: React bails out of the whole subtree and flips
+ * it visible.
+ *
+ * Only a segment at depth 1 or more, rendered against the chain held now: a
+ * whole document replaces the root, and a slot is a region of a page not on
+ * screen yet. A prefetch that landed on a redirect - a guarded link, on a
+ * landing page all of them - warms the destination it prefetched instead:
+ * the tap on Sign in decoded the login page and loaded its chunks after the
+ * click, 154 ms of a 225 ms tap.
+ */
+function warm(entry, cacheKey) {
+    // The tree is read by the navigation that takes the entry, and a decode
+    // that fails - a chunk the deploy no longer serves - fails there, where it
+    // is handled. Here the rejection has nobody to reach.
+    entry.body
+        .then((text) => {
+        if (entry.redirectTo) {
+            const destination = cache.get(retentionKeyFor(entry.redirectTo, matchIntercept(entry.redirectTo)));
+            if (destination)
+                warm(destination, retentionKeyFor(entry.redirectTo, matchIntercept(entry.redirectTo)));
+            return;
+        }
+        if (text === null)
+            return;
+        // The page about to show: its pictures ahead of every other page's.
+        preloadImages(text, "high");
+        return entry.tree.then((tree) => {
+            if (entry.slot !== null ||
+                entry.segmentDepth === 0 ||
+                !isUsable(entry, claimedChain(null)) ||
+                cache.get(cacheKey) !== entry)
+                return;
+            onPrerender?.(tree, cacheKey, entry.segmentDepth);
+        });
+    })
+        .catch(() => { });
+}
+function prefetchUrl(cacheKey, url, ttl, interceptSlot, refererUrl, held = { intent: false, explicitTtl: false }) {
     const chain = claimedChain(interceptSlot ?? null);
     const existing = cache.get(cacheKey);
     if (existing && existing.expiresAt > Date.now()) {
+        // Fetched as it came into view, undecoded; the touch says decode it.
+        if (held.intent)
+            warm(existing, cacheKey);
         return;
     }
     // A navigation is already fetching it; the answer is on its way.
@@ -994,8 +1218,21 @@ function prefetchUrl(cacheKey, url, ttl, interceptSlot, refererUrl) {
         else if (local) {
             entry.layouts = local.chain;
         }
-        // The bytes, not the page: decoding is the navigation's, see CacheEntry.
-        return response.text();
+        // Marked public: the build's bytes, the same for everyone, and held
+        // for as long as Next holds a static page - unless the link said how
+        // long. A deploy is caught by the version handshake, not by the clock.
+        if (!held.explicitTtl &&
+            /\bpublic\b/.test(response.headers.get("Cache-Control") ?? "")) {
+            entry.expiresAt = Math.max(entry.expiresAt, Date.now() + STATIC_PREFETCH_TTL);
+        }
+        // The bytes, not the page: decoding is the navigation's, see CacheEntry
+        // - unless the visitor is already on the way, see prefetch(). The
+        // pictures the page shows are asked for now, though: on a phone they
+        // take longer than the touch-to-click a hidden render has.
+        return response.text().then((text) => {
+            preloadImages(text);
+            return text;
+        });
     })
         .catch(() => {
         entry.failed = true;
@@ -1010,6 +1247,8 @@ function prefetchUrl(cacheKey, url, ttl, interceptSlot, refererUrl) {
         }
     });
     cache.set(cacheKey, entry);
+    if (held.intent)
+        warm(entry, cacheKey);
 }
 /**
  * Drop a prefetch that is still in flight — the pointer left the link.