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

package/internal/runtime.js

@@ -74,9 +74,9 @@ 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 { hasClientPage, matchRoute, nearestBoundary } from "./routing.js";
 import type { RouteParams, SearchParams } from "./routing.js";
 import {
@@ -137,6 +137,11 @@ 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";
+
 // ---------------------------------------------------------------------------
 // View transitions
 // ---------------------------------------------------------------------------
@@ -397,6 +402,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 +624,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 +648,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 +663,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;
@@ -631,9 +679,9 @@ component ModuleRouter(url: string, initial: ResolvedRoute, children: React.Node
       // 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 +746,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,7 +773,10 @@ 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;
@@ -748,11 +801,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,7 +819,7 @@ 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;
@@ -791,7 +848,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 +920,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") {
@@ -884,7 +947,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 {
@@ -966,7 +1033,7 @@ 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;
       }
@@ -1532,7 +1599,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 +1610,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,107 @@
+// @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): DocumentShell {
+  const head = headTags(assets);
+  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): 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)}">`;
+  }
+  for (const src of assets.scripts) {
+    tags += `<script type="module" src="${escapeAttribute(src)}"></script>`;
+  }
+  return tags;
+}
+
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}

package/internal/stream.js

@@ -851,7 +851,7 @@ function withPayload(
  * A document's chunks, with the Flight payload it was rendered from written
  * into it as it arrives.
  *
- * Three rules, and each is the answer to a way the obvious version is wrong.
+ * Four rules, and each is the answer to a way the obvious version is wrong.
  *
  * **Nothing before the head.** The first chunk this is handed is the whole
  * opening of the document — `assembled` does not let one go until the head is
@@ -862,9 +862,20 @@ function withPayload(
  * **Written as soon as it exists.** A payload row usually exists before the
  * HTML rendered from it — React's client reads the row, then the boundary
  * renders — so waiting for the next HTML chunk would put the browser's copy
- * behind the markup it hydrates. Each HTML chunk is followed by whatever
- * payload is waiting, and a payload that arrives while the HTML is idle is
- * written then, without a chunk of HTML to follow.
+ * behind the markup it hydrates. Each HTML chunk that ends between elements is
+ * followed by whatever payload is waiting, and a payload that arrives while the
+ * HTML is idle there is written then, without a chunk of HTML to follow.
+ *
+ * **Only between elements.** React hands its HTML on through a fixed-size
+ * buffer, so a chunk can end anywhere: inside a tag, an attribute's value, a
+ * comment, a character reference or an inline `<script>`. A payload element
+ * written after such a chunk is not an element. It is part of the attribute,
+ * the comment or the text it landed in, the browser never reads it, and React's
+ * client closes the payload with rows missing, which is the "Connection closed"
+ * a page reports instead of hydrating. So a waiting payload goes out only where
+ * the HTML written so far ends between elements, which [`advanced`] follows
+ * from chunk to chunk, and otherwise waits for the HTML that finishes what is
+ * open.
  *
  * **`</body></html>` waits for the end of the payload.** The HTML can finish
  * first — the last boundary's markup is rendered from rows that are already
@@ -917,12 +928,13 @@ async function* interleaved(
     }
   })();
 
-  let opened = false;
+  // Nothing written yet, and nothing may go before the head.
+  let boundary: Boundary = NOTHING_WRITTEN;
   let closing = "";
   try {
     let next = chunks.next();
     while (true) {
-      if (opened && written !== "") {
+      if (boundary.safe && written !== "") {
         const out = written;
         written = "";
         yield out;
@@ -945,8 +957,8 @@ async function* interleaved(
       }
       if (text !== "") {
         yield text;
+        boundary = advanced(boundary, text);
       }
-      opened = true;
       next = chunks.next();
     }
     while (!ended || written !== "") {
@@ -972,6 +984,54 @@ async function* interleaved(
   }
 }
 
+/** Where the HTML written so far leaves the next payload element. */
+type Boundary = {|
+  /** Whether a payload element may be written now. */
+  readonly safe: boolean,
+  /** The `script` or `style` element the HTML is inside, if it is inside one. */
+  readonly rawText: string | null,
+  /** A tag, or a comment, the HTML has started and not yet finished. */
+  readonly open: string,
+|};
+
+const NOTHING_WRITTEN: Boundary = { safe: false, rawText: null, open: "" };
+
+/**
+ * `boundary`, once `html` has been written after it.
+ *
+ * A payload element may follow HTML that ends with a `>` outside a `<script>`
+ * and a `<style>`. The test can be that short because React wrote the HTML: it
+ * escapes `<` and `>` in text and in attribute values, so a `>` it wrote closes
+ * a tag or a comment, and HTML that ends any other way ends inside one, or
+ * inside a character reference or a run of text. What React does not escape is
+ * the content of an inline script or stylesheet, where a `>` is code, so an
+ * opening `<script>` or `<style>` is followed to its closing tag. A tag split
+ * across two chunks is carried in `open` and read whole with the next one.
+ */
+function advanced(boundary: Boundary, html: string): Boundary {
+  const text = boundary.open + html;
+  let rawText = boundary.rawText;
+  const tags = /<(\/?)(script|style)(?=[\s/>])[^>]*>/gi;
+  let tag = tags.exec(text);
+  while (tag != null) {
+    const name = tag[2].toLowerCase();
+    if (tag[1] === "/") {
+      if (rawText === name) {
+        rawText = null;
+      }
+    } else if (rawText == null) {
+      rawText = name;
+    }
+    tag = tags.exec(text);
+  }
+  const start = text.lastIndexOf("<");
+  return {
+    safe: rawText == null && text.endsWith(">"),
+    rawText,
+    open: start > text.lastIndexOf(">") ? text.slice(start) : "",
+  };
+}
+
 /**
  * The prelude of a static prerender, whichever stream this build produced.
  *