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

package/action.js

@@ -111,6 +111,7 @@ import {
   decodeActionResult,
   encodeActionArguments,
 } from "./internal/action-wire.js";
+import { clearNavigationCache } from "./internal/navigation-cache.js";
 
 export type { ActionArgument, ActionValue } from "./internal/action-wire.js";
 export {
@@ -264,6 +265,11 @@ export function createServerReference(id: string, name: string): ServerActionFun
       headers,
       body,
     });
+    // A route a navigation kept may no longer show what this action wrote, and
+    // which routes is the server's to know, so every kept route is asked for
+    // again. Whatever the status: an action that failed part-way may have
+    // written before it failed. See `./internal/navigation-cache.js`.
+    clearNavigationCache();
     if (!response.ok) {
       throw new ServerActionError(name, response.status);
     }

package/client.js

@@ -14,6 +14,13 @@
 // *before* `hydrateRoot`, so the first client render is synchronous and
 // matches the server's markup exactly.
 //
+// An application whose routes render as React Server Components, the default,
+// starts from neither: `hydrateFlight` in `./rsc-client.js` hydrates the Flight
+// payload its document carries. That is a separate entry so that this one,
+// which every other web application imports, never names React's Flight
+// client. The client is an optional peer that needs React 19.3, and a project
+// on React 19.2 does not install it (ubugeeei-prod/uf#992).
+//
 // # What "its loader data" means once the loader can defer
 //
 // It is a payload rather than a value: `internal/payload.js` writes the model
@@ -101,6 +108,8 @@ import {
   hasClientPage,
   installNavigation,
   installRoutes,
+  installRouting,
+  installStaleTime,
   matchRoute,
   resolveFailure,
   resolveMatch,
@@ -108,7 +117,8 @@ import {
 import { DATA_ID, ROOT_ID } from "./internal/document.js";
 import { decodePayload } from "./internal/payload.js";
 import { createPayloadReader, domObserver } from "./internal/payload-rows.js";
-import { installBrowserModules, readDocumentPayload } from "./internal/flight-browser.js";
+import { prepareDocumentForHydration } from "./internal/prepare-document.js";
+import { type TrailingSlash, addressOf, applicationPathOf } from "./internal/base-path.js";
 
 /**
  * Hydrate the current document.
@@ -124,6 +134,9 @@ export async function hydrate(options: {|
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
   readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+  readonly staleTime?: number,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -136,15 +149,19 @@ export async function hydrate(options: {|
   // `app.rendering.navigation` existed and what a hand-written entry still
   // means: the default is the behaviour, not the absence of one.
   installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
+  installStaleTime(options.staleTime ?? 0);
+  // The route table has no base path in it, and the address bar does.
+  const applicationPath = applicationPathOf(window.location.pathname) ?? window.location.pathname;
 
   // Before the loader data is read and before `resolveMatch` is called: both
   // would go looking for a page module that is not in this bundle.
-  const matched = matchRoute(table.routes, window.location.pathname);
+  const matched = matchRoute(table.routes, applicationPath);
   if (matched != null && !hasClientPage(matched.route)) {
     return;
   }
 
-  const url = window.location.pathname + window.location.search;
+  const url = applicationPath + window.location.search;
   // Row 0 of the payload, and the reader that will fill in the rows it refers
   // to. Both before `hydrateRoot`, and in this order: `decodePayload` is what
   // tells the reader which rows the page is waiting for, and `watch` is what
@@ -218,106 +235,6 @@ export async function hydrate(options: {|
   }
 }
 
-/**
- * Hydrate a document React Server Components rendered.
- *
- * [`hydrate`] resolves the route from its modules and renders it again over the
- * server's markup. This one resolves nothing and imports no route module: the
- * document carries the Flight payload its tree was rendered from, React's own
- * client reads it, and the tree the browser hydrates is the tree the server
- * rendered — a Server Component is markup and a reference, and a client
- * component is the one kind of module this page loads. See
- * ubugeeei-prod/uf#519.
- *
- * The payload is read while the document is still arriving. Row 0 is in the
- * shell, so hydration starts as soon as the module script runs, and every row
- * after it lands in a later chunk that the reader picks up as it is parsed — so
- * a boundary the server completes after hydration began resolves then, with no
- * second request.
- *
- * Everything else is [`hydrate`]'s, for the reasons written there: the
- * navigation mode is installed before the first render, the development
- * hydration report captures the server's markup before React repairs it, and
- * Strict Mode wraps the root.
- */
-export async function hydrateFlight(options: {|
-  readonly App: React.ComponentType<AppProps>,
-  readonly strictMode?: boolean,
-  readonly navigation?: Navigation,
-|}): Promise<void> {
-  installNavigation(options.navigation ?? "client");
-  installBrowserModules();
-  const flight = readDocumentPayload(document, domObserver(document));
-
-  const url = window.location.pathname + window.location.search;
-  const { App } = options;
-  const container = document.getElementById(ROOT_ID) ?? document;
-  prepareDocumentForHydration(document);
-
-  let recovery = null;
-  let restoreDevHead = null;
-  if (import.meta.hot != null) {
-    const { captureServerMarkup, hydrationErrorHandler, prepareDevHeadForHydration } =
-      await import("./internal/hydration.js");
-    restoreDevHead = prepareDevHeadForHydration(document);
-    recovery = hydrationErrorHandler(container, captureServerMarkup(container), document);
-  }
-
-  const tree = <App url={url} flight={flight} />;
-
-  startTransition(() => {
-    hydrateRoot(
-      container,
-      options.strictMode === true ? <StrictMode>{tree}</StrictMode> : tree,
-      recovery == null ? undefined : { onRecoverableError: recovery },
-    );
-    if (restoreDevHead != null) {
-      setTimeout(restoreDevHead, 250);
-    }
-  });
-
-  if (import.meta.hot != null) {
-    const { reportDevtools } = await import("./internal/devtools.js");
-    reportDevtools(window);
-  }
-}
-
-function prepareDocumentForHydration(document: Document): void {
-  const head = document.head;
-  const envelope = head.querySelector('meta[name="uf:render"]');
-  if (envelope != null && head.firstChild !== envelope) {
-    head.insertBefore(envelope, head.firstChild);
-  }
-  moveLayoutMetaAfterRouteHead(head, head.querySelector("meta[charset]"));
-  moveLayoutMetaAfterRouteHead(head, head.querySelector('meta[name="viewport"]'));
-  document.getElementById("_R_")?.remove();
-  normalizeReactFormActions(document);
-}
-
-function moveLayoutMetaAfterRouteHead(head: HTMLHeadElement, meta: Element | null): void {
-  if (meta == null) {
-    return;
-  }
-  const colorScheme = head.querySelector('meta[name="color-scheme"]');
-  if (colorScheme != null && colorScheme !== meta) {
-    head.insertBefore(meta, colorScheme);
-    return;
-  }
-  head.appendChild(meta);
-}
-
-const SERVER_FORM_PLACEHOLDER = "javascript:throw new Error('React form unexpectedly submitted.')";
-const CLIENT_FORM_PLACEHOLDER =
-  "javascript:throw new Error('A React form was unexpectedly submitted. If you called form.submit() manually, consider using form.requestSubmit() instead. If you\\'re trying to use event.stopPropagation() in a submit event handler, consider also calling event.preventDefault().')";
-
-function normalizeReactFormActions(document: Document): void {
-  for (const form of document.querySelectorAll("form")) {
-    if (form.getAttribute("action") === SERVER_FORM_PLACEHOLDER) {
-      form.setAttribute("action", CLIENT_FORM_PLACEHOLDER);
-    }
-  }
-}
-
 /**
  * Render the current route into an empty shell.
  *
@@ -354,6 +271,9 @@ export async function render(options: {|
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
   readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+  readonly staleTime?: number,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -362,14 +282,18 @@ export async function render(options: {|
   };
   installRoutes(table);
   installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
+  installStaleTime(options.staleTime ?? 0);
 
-  const url = window.location.pathname + window.location.search;
+  const url =
+    (applicationPathOf(window.location.pathname) ?? window.location.pathname) +
+    window.location.search;
   let resolved;
   try {
     resolved = await resolveMatch(table, url);
   } catch (error) {
     if (error instanceof RedirectError) {
-      window.location.replace(error.to);
+      window.location.replace(addressOf(error.to));
       return;
     }
     // The error boundary, chosen the same way the server chooses it. A throw

package/index.js

@@ -73,6 +73,7 @@ export {
   RouteView,
   RouterProvider,
   UnauthorizedError,
+  basePath,
   buildRoute,
   forbidden,
   hasClientPage,

package/internal/base-path.js

@@ -0,0 +1,175 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: `app.router.basePath` and
+// `app.router.trailingSlash`, as the router reads them.
+//
+// The route table has no base in it — `/guide` is `/guide` whether the site is
+// served at `/` or at `/docs` — and the browser's address bar has one. This
+// module is the one place those two spellings meet: a `Link` and a navigation
+// turn an application path into the address, and hydration, `popstate` and a
+// refresh turn the address back into an application path before the table is
+// asked. Every other part of the router speaks application paths.
+//
+// The policy decides the spelling of a path a link writes, so that a page is
+// linked by the address its server answers without a redirect. The server's
+// half — the `308` for the other spelling, and the `404` outside the base — is
+// `@uniflowed/server`'s `internal/routing.js`.
+//
+// # Installed, like navigation
+//
+// Module state beside `installNavigation`, set once by the entry that started
+// the application: `virtual:uf/client` in the browser and `virtual:uf/server`
+// in the graph that renders documents. `@uniflowed/vite` writes both calls from
+// `uf.config.js`, so a dev server and a build link the same way. A test that
+// installs nothing gets the root and `"ignore"`, which is what every
+// application had before the setting existed.
+
+/** Which spelling of a path is the page; see `app.router.trailingSlash`. */
+export type TrailingSlash = "never" | "always" | "ignore";
+
+/** What an entry installs. */
+export type RoutingSettings = {|
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
+|};
+
+let installedBase: string = "";
+let installedSlash: TrailingSlash = "ignore";
+
+/**
+ * Say where this application is served and how its paths are spelled. Called
+ * once, by the entry that starts it.
+ */
+export function installRouting(settings: RoutingSettings): void {
+  installedBase = normalizeBase(settings.basePath ?? "");
+  installedSlash = settings.trailingSlash ?? "ignore";
+}
+
+/**
+ * The path this application is served under: `""` at the root, `"/docs"`
+ * otherwise.
+ *
+ * For code that builds an absolute address the router did not build for it —
+ * a middleware's `Response.redirect(new URL(`${basePath()}/sign-in`, request.url))`
+ * — because a route handler and a middleware are handed the application path,
+ * and an address built from `/sign-in` alone leaves the base behind.
+ */
+export function basePath(): string {
+  return installedBase;
+}
+
+/** How this application spells a path. */
+export function trailingSlash(): TrailingSlash {
+  return installedSlash;
+}
+
+/**
+ * The address for an application path: the base in front, the policy's
+ * spelling, the query and the fragment kept.
+ *
+ * Only a path that starts with a single `/` is an application path. Anything
+ * else — `https://…`, `//cdn…`, `mailto:`, `?page=2`, `#top`, `../up` — is
+ * returned as it was written, because the browser resolves it against the
+ * address that is already there.
+ */
+export function addressOf(to: string): string {
+  if (!to.startsWith("/") || to.startsWith("//")) {
+    return to;
+  }
+  const { path, rest } = splitPath(to);
+  return `${installedBase}${spellPath(path, installedSlash, installedBase !== "")}${rest}`;
+}
+
+/**
+ * The application path for an address's pathname, or `null` when the address
+ * is outside the base.
+ *
+ * `/docs/guide` is `/guide` under `/docs`, and `/docs` and `/docs/` are both
+ * `/`. `/docsx` is not under `/docs`: a base is whole segments.
+ */
+export function applicationPathOf(pathname: string): string | null {
+  if (installedBase === "") {
+    return pathname;
+  }
+  if (pathname === installedBase) {
+    return "/";
+  }
+  if (pathname.startsWith(`${installedBase}/`)) {
+    return pathname.slice(installedBase.length);
+  }
+  return null;
+}
+
+/**
+ * A browser pathname in this application's spelling: the base kept, the
+ * application path under it spelled by the policy. A pathname outside the
+ * base is returned as it was.
+ *
+ * For an address the router read back rather than wrote — the document path a
+ * payload URL names has lost its trailing slash, and the history entry a
+ * navigation writes should be the address the server answers without a
+ * redirect.
+ */
+export function canonicalAddress(pathname: string): string {
+  const application = applicationPathOf(pathname);
+  if (application == null) {
+    return pathname;
+  }
+  const spelled = spellPath(application, installedSlash, installedBase !== "");
+  return `${installedBase}${spelled}`;
+}
+
+/**
+ * `path` in `policy`'s spelling.
+ *
+ * The root of an application at the root is `/` whatever the policy says. The
+ * root of an application under a base is the base itself — `/docs` — unless
+ * the policy is `"always"`, which spells it `/docs/`. A path whose last segment
+ * looks like a file keeps what it was written with, because `/robots.txt/` is
+ * not a page.
+ */
+export function spellPath(path: string, policy: TrailingSlash, underBase: boolean): string {
+  let end = path.length;
+  while (end > 0 && path.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  const trimmed = path.slice(0, end);
+  if (trimmed === "") {
+    return policy === "always" || !underBase ? "/" : "";
+  }
+  if (policy === "ignore" || looksLikeAFile(trimmed)) {
+    return path;
+  }
+  return policy === "always" ? `${trimmed}/` : trimmed;
+}
+
+/** Whether a path's last segment has an extension. */
+function looksLikeAFile(path: string): boolean {
+  const last = path.slice(path.lastIndexOf("/") + 1);
+  return last.includes(".");
+}
+
+function splitPath(to: string): {| readonly path: string, readonly rest: string |} {
+  let end = to.length;
+  for (let index = 0; index < to.length; index += 1) {
+    const code = to.charCodeAt(index);
+    // `?` and `#`.
+    if (code === 63 || code === 35) {
+      end = index;
+      break;
+    }
+  }
+  return { path: to.slice(0, end), rest: to.slice(end) };
+}
+
+/**
+ * A base as `uf_config` accepts one, with a trailing slash forgiven: `""`,
+ * `"/"` and absent are the root.
+ */
+function normalizeBase(base: string): string {
+  let end = base.length;
+  while (end > 0 && base.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  return base.slice(0, end);
+}

package/internal/compose.js

@@ -412,6 +412,11 @@ component SlotView(slot: ResolvedSlot, pathname: string, searchParams: SearchPar
   const at = slot.intercepted?.pathname ?? pathname;
   const query = slot.intercepted?.searchParams ?? searchParams;
   const Page = pageComponent(page);
+  // The slot module's own export, looked up by slot: `pageComponent` hands back
+  // its `default` or `Page` as it is, so this is the same component on every
+  // render of the same slot. The React Compiler cannot see through the lookup
+  // and reports a component created during render.
+  // uf-lint-disable-next-line react-compiler/static-components
   let element: React.Node = <Page params={slot.params} searchParams={query} data={undefined} />;
   const templateContext = {
     pathname: at,
@@ -425,6 +430,10 @@ component SlotView(slot: ResolvedSlot, pathname: string, searchParams: SearchPar
         continue;
       }
       const Fallback = loadingComponent(boundary.module);
+      // The same lookup as `Page` above: `loadingComponent` hands back the
+      // boundary module's own export as it is, so this is the same component
+      // on every render of that boundary.
+      // uf-lint-disable-next-line react-compiler/static-components
       element = <Suspense fallback={<Fallback />}>{element}</Suspense>;
     }
     const errorBoundary = slot.errorBoundary;
@@ -439,6 +448,9 @@ component SlotView(slot: ResolvedSlot, pathname: string, searchParams: SearchPar
     if (depth > 0) {
       const Layout = layoutComponent(slot.layouts[depth - 1]);
       element = (
+        // The layout module's own export, looked up by depth, for the same
+        // reason as `Page` above.
+        // uf-lint-disable-next-line react-compiler/static-components
         <Layout {...slotsAt(slot.slots, depth, { pathname, searchParams })} params={slot.params}>
           {element}
         </Layout>

package/internal/error-view.js

@@ -78,6 +78,10 @@ component RouteErrorView(module: ?ErrorModule, error: RouteError, reset: () => v
     return <DefaultRouteError error={error} reset={reset} />;
   }
   const Boundary = errorComponent(module);
+  // The error module's own export, looked up by route, for the same reason as
+  // the page component in `compose.js`: the same component on every render of
+  // that route, through a lookup the compiler cannot see into.
+  // uf-lint-disable-next-line react-compiler/static-components
   return <Boundary error={error} reset={reset} />;
 }
 

package/internal/flight-browser.js

@@ -26,11 +26,21 @@
 import { createFromFetch, createFromReadableStream } from "react-server-dom-parcel/client.browser";
 
 import { FLIGHT_CHUNK_ATTRIBUTE, flightChunkBytes } from "./flight-chunks.js";
-import { FLIGHT_CONTENT_TYPE, type FlightRoot, documentPathOf, flightUrl } from "./flight.js";
+import {
+  FLIGHT_CONTENT_TYPE,
+  type FetchedFlight,
+  type FlightRoot,
+  documentPathOf,
+  flightUrl,
+} from "./flight.js";
+import { requireServerComponentsReact } from "./react-version.js";
 
 /** A module namespace, as far as the loader looks into one. */
 type ModuleNamespace = { +[string]: mixed };
 
+/** The entry a refusal names: the one an application reaches this module through. */
+const ENTRY = "@uniflowed/router/rsc/client";
+
 /**
  * Install the module hook React's Flight client resolves references through.
  *
@@ -39,6 +49,7 @@ type ModuleNamespace = { +[string]: mixed };
  * as an accessor cannot be assigned to, and hydration must not throw over it.
  */
 export function installBrowserModules(): void {
+  requireServerComponentsReact(ENTRY);
   const loaded: Map<string, ModuleNamespace> = new Map();
   // A function with three properties, which is the shape React's Parcel client
   // calls: `parcelRequire(id)` for a module, `parcelRequire.load(url)` for the
@@ -156,27 +167,10 @@ export function readDocumentPayload(
   document: DocumentLike,
   observe: ?(callback: () => void) => (() => void) | null,
 ): Promise<FlightRoot> {
+  requireServerComponentsReact(ENTRY);
   return createFromReadableStream(documentPayload(document, observe));
 }
 
-/** What fetching a route's payload turned into. */
-export type FetchedFlight =
-  | {|
-      readonly kind: "flight",
-      /** The route the server answered for: a redirect's target, when there was one. */
-      readonly url: string,
-      readonly root: Promise<FlightRoot>,
-    |}
-  | {|
-      /**
-       * The answer was not a payload: a redirect off this origin, or a host
-       * that had no payload for the URL. The browser should load `url` as a
-       * document.
-       */
-      readonly kind: "document",
-      readonly url: string,
-    |};
-
 /**
  * Fetch `url`'s payload.
  *
@@ -193,6 +187,10 @@ export type FetchedFlight =
  * refusal — is a document, whatever its status.
  */
 export async function fetchFlight(url: string): Promise<FetchedFlight> {
+  // Outside the `try` below, which answers every failure to fetch with a
+  // document load: too old a React is not a network failure, and a navigation
+  // that quietly reloaded the page would hide it.
+  requireServerComponentsReact(ENTRY);
   let response: Response;
   try {
     response = await fetch(flightUrl(url), {

package/internal/flight-chunks.js

@@ -55,9 +55,33 @@ function elementJson(value: FlightChunk): string {
     .replace(/\u2029/g, "\\u2029");
 }
 
-/** The element for one chunk, or the end marker for `null`. */
-export function flightChunkElement(chunk: FlightChunk): string {
-  return `<script type="application/json" ${FLIGHT_CHUNK_ATTRIBUTE}>${elementJson(chunk)}</script>`;
+/**
+ * The element for one chunk, or the end marker for `null`.
+ *
+ * `nonce` is this response's, and it is carried even though the element is
+ * `application/json` and therefore a data block the browser never executes.
+ * Two reasons, and neither is "in case the spec changes". A uf document's
+ * invariant is that every `<script>` in it carries the nonce — that is what
+ * `packages/router/streaming.test.js` pins, and an invariant with an exception
+ * in it is one a reader has to check every new script against. And these are
+ * written as text into a stream rather than rendered by React, so unlike the
+ * payload rows in `./runtime.js` there is no second render on the client to
+ * disagree with; the attribute costs a comparison nobody makes.
+ */
+export function flightChunkElement(chunk: FlightChunk, nonce?: string | null): string {
+  const carried = nonce == null ? "" : ` nonce="${escapeNonce(nonce)}"`;
+  return `<script type="application/json"${carried} ${FLIGHT_CHUNK_ATTRIBUTE}>${elementJson(chunk)}</script>`;
+}
+
+/**
+ * A nonce, as an attribute value.
+ *
+ * uf's own nonces are base64 and hold none of these, so this is about the one a
+ * project supplied: the value reaches a document that a browser parses as
+ * HTML, and a `"` in it would end the attribute and open whatever follows.
+ */
+function escapeNonce(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
 
 /**
@@ -74,7 +98,7 @@ export type ChunkEncoder = {|
   readonly end: () => string,
 |};
 
-export function createChunkEncoder(): ChunkEncoder {
+export function createChunkEncoder(nonce?: string | null): ChunkEncoder {
   const strict = new TextDecoder("utf-8", { fatal: true });
   let carry: Uint8Array = new Uint8Array(0);
 
@@ -87,17 +111,17 @@ export function createChunkEncoder(): ChunkEncoder {
     }
     const body = joined.subarray(0, complete);
     try {
-      return flightChunkElement(strict.decode(body));
+      return flightChunkElement(strict.decode(body), nonce);
     } catch {
-      return flightChunkElement({ bytes: base64(body) });
+      return flightChunkElement({ bytes: base64(body) }, nonce);
     }
   }
 
   function end(): string {
     const rest = carry;
     carry = new Uint8Array(0);
-    const tail = rest.length === 0 ? "" : flightChunkElement({ bytes: base64(rest) });
-    return `${tail}${flightChunkElement(null)}`;
+    const tail = rest.length === 0 ? "" : flightChunkElement({ bytes: base64(rest) }, nonce);
+    return `${tail}${flightChunkElement(null, nonce)}`;
   }
 
   return { encode, end };

package/internal/flight-ssr.js

@@ -25,6 +25,7 @@
 import { createFromReadableStream } from "react-server-dom-parcel/client.edge";
 
 import type { FlightRoot } from "./flight.js";
+import { requireServerComponentsReact } from "./react-version.js";
 
 /** A module namespace, as far as the hook looks into one. */
 type ModuleNamespace = { +[string]: mixed };
@@ -32,6 +33,9 @@ type ModuleNamespace = { +[string]: mixed };
 /** The server copy of the client module at a browser chunk URL. */
 export type ClientModuleLoader = (url: string) => Promise<ModuleNamespace>;
 
+/** The entry a refusal names: the one an application reaches this module through. */
+const ENTRY = "@uniflowed/router/rsc/ssr";
+
 /**
  * Install the module hook React's Flight client resolves references through.
  *
@@ -40,6 +44,7 @@ export type ClientModuleLoader = (url: string) => Promise<ModuleNamespace>;
  * stale one.
  */
 export function installServerModules(load: ClientModuleLoader): void {
+  requireServerComponentsReact(ENTRY);
   const loaded: Map<string, ModuleNamespace> = new Map();
   // The browser's hook, on a server; `./flight-browser.js` has the shape.
   function parcelRequire(id: string): ModuleNamespace {
@@ -68,5 +73,6 @@ export function installServerModules(load: ClientModuleLoader): void {
 
 /** Read a payload into its root value, as React's client does in the browser. */
 export function readPayload(stream: ReadableStream<Uint8Array>): Promise<FlightRoot> {
+  requireServerComponentsReact(ENTRY);
   return createFromReadableStream(stream);
 }

package/internal/flight.js

@@ -60,6 +60,32 @@ export type FlightRoot = {|
   readonly tree: Node,
 |};
 
+/**
+ * What fetching a route's payload turned into.
+ *
+ * Declared here rather than beside the fetch in `./flight-browser.js`, because
+ * the router's navigation names this type and must not import React's Flight
+ * client: `./runtime.js` is in every application's bundle, and that client is
+ * only in the bundles of applications that render Server Components
+ * (ubugeeei-prod/uf#992).
+ */
+export type FetchedFlight =
+  | {|
+      readonly kind: "flight",
+      /** The route the server answered for: a redirect's target, when there was one. */
+      readonly url: string,
+      readonly root: Promise<FlightRoot>,
+    |}
+  | {|
+      /**
+       * The answer was not a payload: a redirect off this origin, or a host
+       * that had no payload for the URL. The browser should load `url` as a
+       * document.
+       */
+      readonly kind: "document",
+      readonly url: string,
+    |};
+
 /** The part of a resolved route that crosses to the browser. */
 export function routeState(resolved: ResolvedRoute): RouteState {
   return {