@uniflowed/router 0.0.0-alpha.35 → 0.0.0-alpha.39

package/internal/runtime.js

@@ -74,9 +74,16 @@ import {
 import { BoundaryReporter } from "./boundaries.js";
 import { routeBoundaries } from "./boundary-data.js";
 import { composeRoute, pageComponent } from "./compose.js";
-import { type FetchedFlight, fetchFlight } from "./flight-browser.js";
-import { type FlightRoot, type RouteState, routeState } from "./flight.js";
+import { type FetchedFlight, type FlightRoot, type RouteState, routeState } from "./flight.js";
 import { Head } from "./head.js";
+import { addressOf, applicationPathOf, canonicalAddress } from "./base-path.js";
+import {
+  clearNavigationCache,
+  flightNavigations,
+  keepsNavigations,
+  navigationKey,
+  routeNavigations,
+} from "./navigation-cache.js";
 import { hasClientPage, matchRoute, nearestBoundary } from "./routing.js";
 import type { RouteParams, SearchParams } from "./routing.js";
 import {
@@ -137,6 +144,15 @@ export type {
 
 export { resolveFailure, resolveMatch } from "./resolve.js";
 
+// `app.router.basePath` and `trailingSlash`, installed by the entry that starts
+// the application; see `./base-path.js`.
+export type { RoutingSettings, TrailingSlash } from "./base-path.js";
+export { basePath, installRouting } from "./base-path.js";
+
+// `app.rendering.staleTime`, installed by the same entry; see
+// `./navigation-cache.js`.
+export { installStaleTime } from "./navigation-cache.js";
+
 // ---------------------------------------------------------------------------
 // View transitions
 // ---------------------------------------------------------------------------
@@ -397,6 +413,40 @@ export function navigationMode(): Navigation {
   return installedNavigation;
 }
 
+/**
+ * How a page that React Server Components rendered fetches the next route's
+ * payload. `hydrateFlight` in `../rsc-client.js` installs it.
+ *
+ * Handed in rather than imported, because this module is in every
+ * application's bundle: one rendered from its modules, a single-page one, and
+ * the server's. The fetch reads its answer with React's Flight client,
+ * `react-server-dom-parcel`, which only an application that renders Server
+ * Components installs, and which needs React 19.3 while the rest of the router
+ * runs on 19.2.3 (ubugeeei-prod/uf#992). A bundler resolves every import it is
+ * shown, whether or not anything calls it, so an import here would put that
+ * package in every one of those bundles, or fail the build where it is absent.
+ */
+let installedFlightFetch: ((url: string) => Promise<FetchedFlight>) | null = null;
+
+/** Hand the router the payload fetch. Called once, by `hydrateFlight`, before the first render. */
+export function installFlightFetch(fetcher: (url: string) => Promise<FetchedFlight>): void {
+  installedFlightFetch = fetcher;
+}
+
+/** The next route's payload, through the fetch `hydrateFlight` installed. */
+function fetchFlight(url: string): Promise<FetchedFlight> {
+  if (installedFlightFetch == null) {
+    return Promise.reject(
+      new Error(
+        "@uniflowed/router: a page rendered from a Flight payload navigated before anything " +
+          "installed the payload fetch. `hydrateFlight` from `@uniflowed/router/rsc/client` " +
+          "installs it before it hydrates, so an entry that hydrates a payload has to call that.",
+      ),
+    );
+  }
+  return installedFlightFetch(url);
+}
+
 /** Register the generated route table. Called once by the client and server entries. */
 export function installRoutes(table: RouteTable): void {
   installedTable = table;
@@ -585,8 +635,12 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     if (!isBrowser()) {
       return;
     }
-    const target = new URL(to, window.location.href);
-    const next = target.pathname + target.search;
+    const target = new URL(addressOf(to), window.location.href);
+    // The application path the route table is asked about, and the address the
+    // history entry keeps: one URL, with and without `app.router.basePath`.
+    const applicationPath = applicationPathOf(target.pathname);
+    const next = (applicationPath ?? target.pathname) + target.search;
+    const address = target.pathname + target.search;
     // The browser's job in this application. `assign` and `replace` rather
     // than the history API, because the point is a document request: the
     // history entry, the scroll position, the `Referer` and the unload
@@ -605,8 +659,13 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     // screen that intercepts the URL renders a page of its own, so whether the
     // URL's ordinary page is in this bundle — the paragraph below — is not a
     // question this navigation has to ask.
+    // An address outside the base path is not this application's to render.
+    if (applicationPath == null) {
+      window.location.assign(target.href);
+      return;
+    }
     const origin = beneath(shown.current);
-    const intercepting = interceptingRoutes(origin.slots, target.pathname).length > 0;
+    const intercepting = interceptingRoutes(origin.slots, applicationPath).length > 0;
     // The half of the split that is not about bytes. A route whose page is not
     // in this bundle is not a route this router can render, and pretending
     // otherwise is the silent break: the navigation would resolve to nothing
@@ -615,7 +674,7 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     // link does when there is no JavaScript at all, and what the anchor
     // `Link` renders would have done on its own.
     if (!intercepting) {
-      const matched = matchRoute(routeTable().routes, target.pathname);
+      const matched = matchRoute(routeTable().routes, applicationPath);
       if (matched != null && !hasClientPage(matched.route)) {
         window.location.assign(target.href);
         return;
@@ -623,17 +682,21 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
     }
     setPending(true);
     try {
+      // An interception depends on the page it starts from, so it is resolved
+      // every time; any other navigation reads what this page kept while it is
+      // fresh. See `./navigation-cache.js`.
+      const key = navigationKey(target.pathname, target.search);
       const nextResolved =
         (intercepting ? await resolveInterception(routeTable(), origin, next) : null) ??
-        (await resolveMatch(routeTable(), next));
+        (await (routeNavigations.read(key) ?? keepRoute(key, resolveMatch(routeTable(), next))));
       // An intercepted entry remembers where it was intercepted from, so back
       // and forward can put the page underneath under it again. Every other
       // entry is written the way it always was.
       const state = historyStateFor(nextResolved);
       if (options?.replace === true) {
-        window.history.replaceState(state, "", next + target.hash);
+        window.history.replaceState(state, "", address + target.hash);
       } else {
-        window.history.pushState(state, "", next + target.hash);
+        window.history.pushState(state, "", address + target.hash);
       }
       const commit = () => {
         show(nextResolved);
@@ -698,7 +761,9 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       });
     };
     const onPopState = () => {
-      const next = window.location.pathname + window.location.search;
+      const next =
+        (applicationPathOf(window.location.pathname) ?? window.location.pathname) +
+        window.location.search;
       // Back or forward into an entry an interception wrote: the page it was
       // intercepted from, with the interception over it again. That page is
       // resolved afresh only when it is not already the one underneath, so
@@ -723,12 +788,16 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       // Back into a route this bundle has no page for. The history entry is
       // already the browser's — it moved before this listener ran — so the
       // document that belongs to it is what has to be fetched.
-      const matched = matchRoute(routeTable().routes, window.location.pathname);
+      const matched = matchRoute(
+        routeTable().routes,
+        applicationPathOf(window.location.pathname) ?? window.location.pathname,
+      );
       if (matched != null && !hasClientPage(matched.route)) {
         window.location.reload();
         return;
       }
-      resolveMatch(routeTable(), next).then(arrive);
+      const key = navigationKey(window.location.pathname, window.location.search);
+      (routeNavigations.read(key) ?? keepRoute(key, resolveMatch(routeTable(), next))).then(arrive);
     };
     window.addEventListener("popstate", onPopState);
     return () => {
@@ -748,11 +817,15 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       if (!isBrowser() || navigation === "document") {
         return;
       }
-      const target = new URL(to, window.location.href);
+      const target = new URL(addressOf(to), window.location.href);
+      const applicationPath = applicationPathOf(target.pathname);
+      if (applicationPath == null) {
+        return;
+      }
       // What the next render will need is decided the way the navigation will
       // decide it: a URL a slot on screen intercepts renders that slot's page,
       // so that is the module worth having, and the page the URL names is not.
-      const intercepting = interceptingRoutes(beneath(shown.current).slots, target.pathname);
+      const intercepting = interceptingRoutes(beneath(shown.current).slots, applicationPath);
       if (intercepting.length > 0) {
         await Promise.all(
           intercepting.flatMap((route) => [
@@ -762,11 +835,22 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
         );
         return;
       }
-      const matched = matchRoute(routeTable().routes, target.pathname);
+      const matched = matchRoute(routeTable().routes, applicationPath);
       const load = matched?.route.page;
       if (matched == null || load == null) {
         return;
       }
+      // With `app.rendering.staleTime` set, the whole route: its loader runs
+      // now, and the click, a later visit and the back button read what it
+      // answered while it is fresh. Otherwise only the modules it will need.
+      if (keepsNavigations()) {
+        const key = navigationKey(target.pathname, target.search);
+        await (
+          routeNavigations.read(key) ??
+          keepRoute(key, resolveMatch(routeTable(), applicationPath + target.search))
+        );
+        return;
+      }
       await Promise.all([
         loadOnce(load),
         ...matched.route.layouts.map((layout) => loadOnce(layout)),
@@ -784,6 +868,9 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
         window.location.reload();
         return;
       }
+      // Everything a navigation kept is older than what this asks for, so none
+      // of it is shown again; see `./navigation-cache.js`.
+      clearNavigationCache();
       // A refresh of an intercepted page refreshes both of its halves: the
       // page underneath, resolved again for its own URL, and the interception
       // resolved again over it. Resolving only the address bar's URL would
@@ -791,7 +878,11 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       const interception = shown.current.interception;
       const nextResolved =
         interception == null
-          ? await resolveMatch(routeTable(), window.location.pathname + window.location.search)
+          ? await resolveMatch(
+              routeTable(),
+              (applicationPathOf(window.location.pathname) ?? window.location.pathname) +
+                window.location.search,
+            )
           : ((await resolveInterception(
               routeTable(),
               await resolveMatch(
@@ -859,7 +950,9 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
     if (!isBrowser()) {
       return;
     }
-    const target = new URL(to, window.location.href);
+    // A payload URL is an address, so it keeps the base path; the server takes
+    // it off.
+    const target = new URL(addressOf(to), window.location.href);
     const next = target.pathname + target.search;
     // The browser's job in this application; `ModuleRouter` has the argument.
     if (navigation === "document") {
@@ -872,7 +965,14 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
     }
     setPending(true);
     try {
-      const fetched = await (takePrefetched(next) ?? fetchFlight(next));
+      // The route this page already has while it is fresh, then a prefetch
+      // still in hand, then the network. See `./navigation-cache.js`.
+      const key = navigationKey(target.pathname, target.search);
+      const fetched = await (
+        flightNavigations.read(key) ??
+        takePrefetched(next) ??
+        keepFlight(key, fetchFlight(next))
+      );
       // Not a payload: a redirect off this origin, or a host that has no payload
       // for this URL. The browser loads it as a document, which is what the
       // anchor would have done.
@@ -884,7 +984,11 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
       const nextRoot = await payload;
       // The URL the payload came from, which is a redirect's target when the
       // route redirected: the history entry is where the visitor ended up.
-      const landed = fetched.url + target.hash;
+      // In the trailing-slash policy's spelling: a payload URL names its
+      // document without the slash, and the history entry should be the
+      // address the server answers without a redirect.
+      const arrived = new URL(fetched.url, window.location.href);
+      const landed = canonicalAddress(arrived.pathname) + arrived.search + target.hash;
       if (options?.replace === true) {
         window.history.replaceState(null, "", landed);
       } else {
@@ -927,8 +1031,10 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
     const onPopState = () => {
       const next = window.location.pathname + window.location.search;
       // The history entry already moved; a payload that cannot be had for it is
-      // a document to load, and a reload is the browser's way to load it.
-      fetchFlight(next).then(
+      // a document to load, and a reload is the browser's way to load it. While
+      // this page keeps the route fresh, what it kept is what comes back.
+      const key = navigationKey(window.location.pathname, window.location.search);
+      (flightNavigations.read(key) ?? keepFlight(key, fetchFlight(next))).then(
         (fetched) => {
           if (fetched.kind === "document") {
             window.location.reload();
@@ -966,11 +1072,19 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
       if (!isBrowser() || navigation === "document") {
         return;
       }
-      const target = new URL(to, window.location.href);
+      const target = new URL(addressOf(to), window.location.href);
       if (target.origin !== window.location.origin) {
         return;
       }
-      await prefetchFlight(target.pathname + target.search);
+      const next = target.pathname + target.search;
+      // Kept for every navigation to it while it is fresh, when a project set
+      // `app.rendering.staleTime`; otherwise held for the one click after it.
+      if (keepsNavigations()) {
+        const key = navigationKey(target.pathname, target.search);
+        await (flightNavigations.read(key) ?? keepFlight(key, fetchFlight(next)));
+        return;
+      }
+      await prefetchFlight(next);
     },
     refresh: async () => {
       if (!isBrowser()) {
@@ -980,7 +1094,13 @@ component FlightRouter(flight: Promise<FlightRoot>, children: React.Node) {
         window.location.reload();
         return;
       }
-      const fetched = await fetchFlight(window.location.pathname + window.location.search);
+      // Everything a navigation kept is older than what this asks for, so none
+      // of it is shown again; see `./navigation-cache.js`.
+      clearNavigationCache();
+      const fetched = await keepFlight(
+        navigationKey(window.location.pathname, window.location.search),
+        fetchFlight(window.location.pathname + window.location.search),
+      );
       if (fetched.kind === "document") {
         window.location.reload();
         return;
@@ -1031,6 +1151,57 @@ const prefetchedFlights: Map<
   {| readonly fetched: Promise<FetchedFlight>, readonly at: number |},
 > = new Map();
 
+/**
+ * `fetched`, kept under `key` for as long as `app.rendering.staleTime` says,
+ * and forgotten again if it turns out not to be a route to show twice: a
+ * request that failed, an answer that was a document rather than a payload, or
+ * a payload React could not read.
+ */
+function keepFlight(key: string, fetched: Promise<FetchedFlight>): Promise<FetchedFlight> {
+  if (!keepsNavigations()) {
+    return fetched;
+  }
+  flightNavigations.store(key, fetched);
+  const forget = () => {
+    flightNavigations.forget(key, fetched);
+  };
+  void fetched.then((answer) => {
+    if (answer.kind === "document") {
+      forget();
+      return;
+    }
+    // A route that answered with its error or not-found boundary is shown this
+    // once: asked again, it may have recovered.
+    void answer.root.then((root) => {
+      if (root.route.status !== 200) {
+        forget();
+      }
+    }, forget);
+  }, forget);
+  return fetched;
+}
+
+/**
+ * `resolved`, kept under `key` for as long as `app.rendering.staleTime` says,
+ * and forgotten again if it did not resolve to a page: a loader that threw or
+ * redirected, or a route that answered with its error or not-found boundary.
+ */
+function keepRoute(key: string, resolved: Promise<ResolvedRoute>): Promise<ResolvedRoute> {
+  if (!keepsNavigations()) {
+    return resolved;
+  }
+  routeNavigations.store(key, resolved);
+  const forget = () => {
+    routeNavigations.forget(key, resolved);
+  };
+  void resolved.then((route) => {
+    if (route.status !== 200) {
+      forget();
+    }
+  }, forget);
+  return resolved;
+}
+
 function prefetchFlight(url: string): Promise<FetchedFlight> {
   const existing = prefetchedFlights.get(url);
   if (existing != null && Date.now() - existing.at < PREFETCH_LIFETIME_MS) {
@@ -1222,12 +1393,20 @@ component RenderedPage(data: mixed) {
   }
   const resolved = view.resolved;
   const Page = pageComponent(resolved.page);
+  // The route module's own export, looked up by route: `pageComponent` hands
+  // back its `default` or `Page` as it is, so this is the same component on
+  // every render of the same route. The React Compiler cannot see through the
+  // lookup and reports a component created during render. The block form,
+  // because the finding is on a JSX child and a `//` comment cannot stand
+  // between JSX children without becoming text.
+  // uf-lint-disable react-compiler/static-components
   return (
     <>
       <Page params={resolved.params} searchParams={resolved.searchParams} data={data} />
       {payloadElements(data)}
     </>
   );
+  // uf-lint-enable react-compiler/static-components
 }
 
 /**
@@ -1532,7 +1711,7 @@ export component Link(
     router.push(to, { replace, transition }).catch((error) => {
       // A failed navigation falls back to the browser doing it.
       console.error(error);
-      window.location.assign(to);
+      window.location.assign(addressOf(to));
     });
   };
 
@@ -1543,7 +1722,10 @@ export component Link(
   return (
     <a
       {...rest}
-      href={to}
+      // `to` is an application path; the anchor is the address, with the base
+      // path in front and the trailing-slash policy's spelling, so a link that
+      // works before hydration and for a right click goes where this one does.
+      href={addressOf(to)}
       className={className}
       onClick={drives ? handleClick : onClick}
       onMouseEnter={drives && prefetch === "intent" ? doPrefetch : undefined}

package/internal/server-route.js

@@ -23,6 +23,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
 import type { RouteState } from "./flight.js";
+import { requireServerComponentsReact } from "./react-version.js";
 
 const storage: AsyncLocalStorage<RouteState> = new AsyncLocalStorage();
 
@@ -38,8 +39,13 @@ export function withServerRoute<T>(route: RouteState, body: () => T): T {
  * route is to call a router hook from a server module that is not being
  * rendered by the router — a script, a route handler, a module evaluated at
  * import time — and each of those is a mistake worth a sentence.
+ *
+ * The React version is checked first. On a React older than 19.3 the Flight
+ * renderer that would have put the hook inside a route refuses to start, so the
+ * sentence worth reading is that one, not "outside a route".
  */
 export function serverRoute(caller: string): RouteState {
+  requireServerComponentsReact(`${caller}()`);
   const route = storage.getStore();
   if (route == null) {
     throw new Error(

package/internal/shell.js

@@ -0,0 +1,115 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the documents an HTML renderer answers with
+// that are not a route's own markup — uf's shell around that markup, and a
+// redirect.
+//
+// `../server.js` renders a route from its modules, and `../rsc-ssr.js` renders
+// one from the payload React Server Components wrote. They are two entries so
+// that the second, which loads React's Flight client, stays out of every bundle
+// that renders no Server Component (ubugeeei-prod/uf#992). Both write the same
+// documents around what they render, which is why those documents live here and
+// not in either entry.
+
+import type { PrerenderResult, RenderAssets, RenderResult } from "../server.js";
+import { addressOf } from "./base-path.js";
+import { ROOT_ID } from "./document.js";
+import type { RedirectError } from "./routing.js";
+import { type DocumentShell, bodyOfText } from "./stream.js";
+
+/** A redirect, as the finished document `prerender` answers with. */
+export async function redirectResult(document: RenderResult): Promise<PrerenderResult> {
+  return {
+    status: document.status,
+    headers: document.headers,
+    html: await document.text(),
+  };
+}
+
+export function redirectDocument(error: RedirectError): RenderResult {
+  // Under `app.router.basePath`, and in the trailing-slash policy's spelling:
+  // `redirect("/sign-in")` names an application path, and a browser follows
+  // an address.
+  const address = addressOf(error.to);
+  const target = escapeAttribute(address);
+  // A document rather than an empty body, because a redirect is still an answer
+  // a browser may be shown; it goes through the same three methods as a
+  // rendered one so that a host has one shape to write, not two.
+  const body = bodyOfText(
+    `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=${target}"><title>Redirecting</title></head><body><a href="${target}">Redirecting…</a></body></html>\n`,
+  );
+  return {
+    status: error.permanent ? 308 : 307,
+    headers: { Location: address },
+    pipe: body.pipe,
+    stream: body.stream,
+    text: body.text,
+  };
+}
+
+/**
+ * The document uf writes around the app's markup.
+ *
+ * The same two shapes `assemble` chose between, decided from the same evidence
+ * — whether the markup opens with `<html>` — but stated up front instead of
+ * afterwards, because a stream has no "afterwards" in which to splice a head.
+ * An app whose root layout renders `<html>` owns the whole document and the
+ * client hydrates `document`, so uf contributes only the tags that go before
+ * `</head>`. An app that renders only content is wrapped in a minimal shell
+ * around `<div id="uf-root">`, which is what the client hydrates instead.
+ *
+ * `internal/stream.js` picks between them on the opening bytes React writes;
+ * everything either shape is made of is here, so what a uf document contains is
+ * still readable in one place.
+ *
+ * # Why the shell is three strings and not one
+ *
+ * Because uf's own `<head>` has to still be open when React's head tags arrive.
+ * React hoists a `<title>`, a `<meta>` and a `<link>` into the head it wrote
+ * itself, and here it wrote none — so with one string this shell closed its
+ * head before the app had rendered a byte, and every `og:` tag and the
+ * `<link rel="canonical">` landed in the body, where a crawler ignores them.
+ * `open` is uf's head up to that point, `body` is the rest of it and the
+ * wrapper, and what goes between them is whatever `assembled` lifts out of the
+ * app's own markup. See ubugeeei-prod/uf#547.
+ *
+ * That is also why no `<title>` is written here any more. It was, from
+ * `resolved.metadata.title` — the same string `Head` renders — so a document
+ * carried two of them, one in each place, and only one was where a browser
+ * looks. Hoisting the rendered one leaves the metadata with a single source.
+ */
+export function shellFor(assets: RenderAssets, nonce?: string | null): DocumentShell {
+  const head = headTags(assets, nonce);
+  return {
+    head,
+    open: `<!doctype html>\n<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">`,
+    body: `${head}</head><body><div id="${ROOT_ID}">`,
+    close: `</div></body></html>\n`,
+  };
+}
+
+function headTags(assets: RenderAssets, nonce?: string | null): string {
+  let tags = "";
+  for (const href of assets.styles) {
+    tags += `<link rel="stylesheet" href="${escapeAttribute(href)}">`;
+  }
+  for (const href of assets.preloads) {
+    tags += `<link rel="modulepreload" href="${escapeAttribute(href)}">`;
+  }
+  // The nonce goes on the client entry even though it is `src` rather than
+  // inline, because a policy of `script-src 'nonce-…'` admits *no* script
+  // without one — a nonce policy is not an inline policy with an exception in
+  // it. A project whose policy also names `'self'` pays nothing for the
+  // attribute being here, and one whose policy is `'strict-dynamic'` needs it:
+  // that is the directive under which this script is the root of trust every
+  // chunk it imports inherits from.
+  const carried = nonce == null ? "" : ` nonce="${escapeAttribute(nonce)}"`;
+  for (const src of assets.scripts) {
+    tags += `<script type="module" src="${escapeAttribute(src)}"${carried}></script>`;
+  }
+  return tags;
+}
+
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}