@uniflowed/router 0.0.0-alpha.4 → 0.0.0-alpha.40

package/internal/flight-browser.js

@@ -0,0 +1,228 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: React Server Components, in the browser.
+//
+// A route's tree reaches the browser as React's Flight payload
+// (ubugeeei-prod/uf#519), by one of two doors. The first page arrives inside
+// its document, as the chunks `./flight-chunks.js` describes, and is read here
+// while the document is still streaming so that `hydrateRoot` can start before
+// the slowest boundary has resolved. Every page after that is a `fetch` of the
+// route's payload URL (`./flight.js`), read the same way by React's own client.
+//
+// # The one hook React's Parcel client asks for
+//
+// `react-server-dom-parcel` resolves a client reference through a global
+// `parcelRequire`: `load(url)` for each chunk a reference names, then
+// `parcelRequire(id)` for the module, synchronously, once they have loaded. uf
+// has no Parcel; this module is that hook. A reference's id *is* its chunk's
+// URL — `@uniflowed/vite` writes it that way — so loading a chunk and
+// remembering its namespace under the same string is the whole of it.
+//
+// It imports same-origin URLs and nothing else. The payload comes from the
+// page's own origin, so a URL that points somewhere else is not a URL uf wrote,
+// and turning it into an `import()` would be letting bytes decide which script
+// runs.
+
+import { createFromFetch, createFromReadableStream } from "react-server-dom-parcel/client.browser";
+
+import { FLIGHT_CHUNK_ATTRIBUTE, flightChunkBytes } from "./flight-chunks.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.
+ *
+ * Once per page. Defined rather than assigned, for the reason
+ * `./boundaries.js` gives about its own global: a name a page already defined
+ * 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
+  // chunk it lives in. Declared and then given its properties, so the hook is
+  // built rather than merged into something that already existed.
+  function parcelRequire(id: string): ModuleNamespace {
+    const namespace = loaded.get(id);
+    if (namespace == null) {
+      throw new Error(
+        `@uniflowed/router: the client module ${id} was required before it loaded. React's ` +
+          "Flight client loads every chunk a reference names before it asks for the module.",
+      );
+    }
+    return namespace;
+  }
+  parcelRequire.load = (url: string): Promise<void> => {
+    const target = new URL(url, window.location.href);
+    if (target.origin !== window.location.origin) {
+      return Promise.reject(
+        new Error(
+          `@uniflowed/router: a payload named the client module ${url}, which is not on this ` +
+            "page's origin. uf writes same-origin chunk URLs only, so it is not loaded.",
+        ),
+      );
+    }
+    return import(target.href).then((namespace: ModuleNamespace) => {
+      loaded.set(url, namespace);
+    });
+  };
+  parcelRequire.extendImportMap = (): void => {
+    throw new Error("@uniflowed/router: a payload asked for an import map, which uf never writes");
+  };
+  parcelRequire.meta = { publicUrl: "", devServer: null };
+  Object.defineProperty(globalThis, "parcelRequire", {
+    value: parcelRequire,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** The parts of a `Document` the reader uses. */
+type DocumentLike = interface {
+  readonly querySelectorAll: (selector: string) => Iterable<ElementLike>,
+  readonly documentElement: mixed,
+};
+
+/** The parts of an `Element` the reader uses. */
+type ElementLike = interface {
+  readonly textContent: string | null,
+};
+
+/**
+ * The payload a document carries, as the byte stream React's client reads.
+ *
+ * Every chunk element already in the document is read at once, in document
+ * order, and a `MutationObserver` reads the ones the server has not written
+ * yet. The stream ends at the end marker and the observer is disconnected with
+ * it, so a prerendered document — every chunk already there — never installs
+ * one.
+ *
+ * `observe` is passed in rather than reached for, so the reader can be driven
+ * by a test with a document it mutates by hand; `domObserver` in
+ * `./payload-rows.js` is the browser's.
+ */
+export function documentPayload(
+  document: DocumentLike,
+  observe: ?(callback: () => void) => (() => void) | null,
+): ReadableStream<Uint8Array> {
+  const seen: WeakSet<ElementLike> = new WeakSet();
+  let stop: (() => void) | null = null;
+  let done = false;
+  return new ReadableStream({
+    start(controller) {
+      const sweep = () => {
+        if (done) {
+          return;
+        }
+        for (const element of document.querySelectorAll(`script[${FLIGHT_CHUNK_ATTRIBUTE}]`)) {
+          if (seen.has(element)) {
+            continue;
+          }
+          seen.add(element);
+          let bytes;
+          try {
+            bytes = flightChunkBytes(element.textContent ?? "null");
+          } catch (error) {
+            done = true;
+            stop?.();
+            controller.error(error);
+            return;
+          }
+          if (bytes == null) {
+            done = true;
+            stop?.();
+            controller.close();
+            return;
+          }
+          controller.enqueue(bytes);
+        }
+      };
+      sweep();
+      if (!done && observe != null) {
+        stop = observe(sweep);
+      }
+    },
+    cancel() {
+      done = true;
+      stop?.();
+    },
+  });
+}
+
+/** Read the payload a document carries into its root value. */
+export function readDocumentPayload(
+  document: DocumentLike,
+  observe: ?(callback: () => void) => (() => void) | null,
+): Promise<FlightRoot> {
+  requireServerComponentsReact(ENTRY);
+  return createFromReadableStream(documentPayload(document, observe));
+}
+
+/**
+ * Fetch `url`'s payload.
+ *
+ * A redirect is followed by `fetch`, and the route the payload is for is read
+ * back off the URL the answer came from — so a loader's `redirect()` during a
+ * navigation lands the history entry on the target, as a document request
+ * would have. Anything that is not a payload is handed back as a document to
+ * load instead of being fed to React's client.
+ *
+ * The status is not what decides, the content type is. A route that resolved
+ * to its not-found or error boundary is answered with a 404 or a 500 *and a
+ * payload*, and that payload is the page to show; what is not a payload — a
+ * static host's `404.html` for a file it does not have, a middleware's own
+ * 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), {
+      credentials: "same-origin",
+      headers: { accept: FLIGHT_CONTENT_TYPE },
+    });
+  } catch {
+    // A request that could not be made or followed: a dropped connection, or a
+    // redirect to another origin — a sign-in page — which `fetch` may not
+    // follow without CORS. The browser can still load the document, and a
+    // top-level navigation follows any redirect, so that is what the router
+    // does rather than leave the click doing nothing.
+    return { kind: "document", url };
+  }
+  const landed = new URL(response.url, window.location.href);
+  const document = documentPathOf(landed.pathname);
+  const type = response.headers.get("content-type") ?? "";
+  if (
+    landed.origin !== window.location.origin ||
+    document == null ||
+    !type.startsWith(FLIGHT_CONTENT_TYPE)
+  ) {
+    void response.body?.cancel();
+    // The URL the reader asked for when the redirect did not end on a payload,
+    // rather than the one it ended on. A middleware that answered with its
+    // sign-in page wrote a `next=` naming the payload URL; loading the document
+    // URL lets it see the document and name that instead.
+    return { kind: "document", url: document == null ? url : `${document}${landed.search}` };
+  }
+  return {
+    kind: "flight",
+    url: `${document}${landed.search}`,
+    root: createFromFetch(Promise.resolve(response)),
+  };
+}

package/internal/flight-chunks.js

@@ -0,0 +1,205 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a Flight payload, written into a document
+// and read back out of one.
+//
+// A document a server streams carries the payload the browser hydrates from,
+// beside the HTML rendered from it: every chunk React's Flight renderer wrote
+// is copied into a `<script type="application/json" data-uf-flight>` element
+// as the HTML streams, and the browser reads the elements back into the byte
+// stream React's Flight client consumes. This module is the encoding of one
+// chunk in each direction, and nothing else, so the writer (`./stream.js`) and
+// the reader (`./flight-browser.js`) cannot disagree about it.
+//
+// # `application/json`, and not a script that runs
+//
+// The obvious mechanism is an inline script that pushes each chunk into a
+// global. `./runtime.js` and `./payload-rows.js` have already made the case
+// against it for uf's documents: a script that runs is a script a content
+// security policy has to allow, and application data in a script element with
+// no type is application data handed to the JavaScript parser. A JSON script
+// runs nothing, and a `MutationObserver` notices each one as it lands.
+//
+// # Text, and bytes that are not text
+//
+// A payload is bytes. Almost all of it is UTF-8 text — rows of JSON — and it is
+// written as a JSON string, which is what makes it readable in a document. A
+// typed array a server component passed as a prop is a row of raw bytes that
+// need not be valid UTF-8, and a decoder that replaced them would hand React a
+// different array. So a run of bytes that does not decode strictly is written
+// as base64 instead, and the reader turns each element back into exactly the
+// bytes the writer was given.
+//
+// A chunk boundary can fall inside a multi-byte character, which is not an
+// invalid sequence and must not be treated as one: the writer keeps an
+// incomplete tail back and prepends it to the next chunk.
+
+/** The attribute every payload chunk element carries. */
+export const FLIGHT_CHUNK_ATTRIBUTE: string = "data-uf-flight";
+
+/** What one element holds: text, bytes that are not text, or the end. */
+export type FlightChunk = string | {| readonly bytes: string |} | null;
+
+/**
+ * An element's text: a JSON value with the three escapes an inline element
+ * needs.
+ *
+ * `<` so a payload holding `</script>` cannot close the element early, and
+ * U+2028 and U+2029 because JSON is sometimes read as JavaScript. The same
+ * escape `./payload.js` applies, for the same reasons.
+ */
+function elementJson(value: FlightChunk): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * 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;");
+}
+
+/**
+ * A writer's state: the bytes of an incomplete character, carried to the next
+ * chunk.
+ *
+ * One per document, made by [`createChunkEncoder`], because the carry is a fact
+ * about the stream and two documents must never share one.
+ */
+export type ChunkEncoder = {|
+  /** The elements for one chunk of payload bytes; possibly none. */
+  readonly encode: (bytes: Uint8Array) => string,
+  /** The elements for whatever is carried, and the end marker. */
+  readonly end: () => string,
+|};
+
+export function createChunkEncoder(nonce?: string | null): ChunkEncoder {
+  const strict = new TextDecoder("utf-8", { fatal: true });
+  let carry: Uint8Array = new Uint8Array(0);
+
+  function encode(bytes: Uint8Array): string {
+    const joined = concat(carry, bytes);
+    const complete = completeLength(joined);
+    carry = joined.slice(complete);
+    if (complete === 0) {
+      return "";
+    }
+    const body = joined.subarray(0, complete);
+    try {
+      return flightChunkElement(strict.decode(body), nonce);
+    } catch {
+      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) }, nonce);
+    return `${tail}${flightChunkElement(null, nonce)}`;
+  }
+
+  return { encode, end };
+}
+
+/**
+ * The bytes one element holds, or `null` for the end marker.
+ *
+ * Refuses anything that is not one of the three shapes the writer produces,
+ * rather than guessing: a document carrying some other value in an element
+ * with this attribute was not written by this module.
+ */
+export function flightChunkBytes(text: string): Uint8Array | null {
+  const value: mixed = JSON.parse(text);
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    return new TextEncoder().encode(value);
+  }
+  if (
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    typeof value.bytes === "string" &&
+    Object.keys(value).length === 1
+  ) {
+    return fromBase64(value.bytes);
+  }
+  throw new Error(`@uniflowed/router: a ${FLIGHT_CHUNK_ATTRIBUTE} element holds no payload chunk`);
+}
+
+/**
+ * How many leading bytes of `bytes` end on a character boundary.
+ *
+ * Walks back over at most three continuation bytes to the lead byte of the last
+ * character and keeps it back when the character is not yet whole. A byte that
+ * is not a valid lead at all is left in — the strict decoder is what says so,
+ * and holding it back would carry it forever.
+ */
+function completeLength(bytes: Uint8Array): number {
+  const length = bytes.length;
+  let at = length - 1;
+  let continuation = 0;
+  while (at >= 0 && continuation < 3 && (bytes[at] & 0xc0) === 0x80) {
+    at -= 1;
+    continuation += 1;
+  }
+  if (at < 0) {
+    return length;
+  }
+  const lead = bytes[at];
+  const needed = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+  return length - at >= needed ? length : at;
+}
+
+function concat(first: Uint8Array, second: Uint8Array): Uint8Array {
+  if (first.length === 0) {
+    return second;
+  }
+  const joined = new Uint8Array(first.length + second.length);
+  joined.set(first, 0);
+  joined.set(second, first.length);
+  return joined;
+}
+
+function base64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function fromBase64(text: string): Uint8Array {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}

package/internal/flight-ssr.js

@@ -0,0 +1,78 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: React Server Components, while HTML renders.
+//
+// The HTML renderer does not render a route's modules. It reads the payload
+// the Flight renderer wrote (`../rsc.js`) with React's own Flight client and
+// renders what comes out, so the document is the payload's tree and not a
+// second rendering of the same modules — which is what lets a Server Component
+// be a module that neither this graph nor the browser ever evaluates.
+//
+// # Where a client component's server copy comes from
+//
+// A client reference in a payload names a chunk URL, which is the browser's
+// module. HTML still has to be rendered from the component, on the server, so
+// `@uniflowed/vite` builds a server copy of every client module and hands the
+// renderer a table from the browser's URL to that copy. React's Parcel client
+// resolves references through a global `parcelRequire`, exactly as in the
+// browser (`./flight-browser.js`), and this module is that hook on a server.
+//
+// The same global serves one application per process, which is what a uf
+// server is. `meta.publicUrl` is empty because the URLs a reference names are
+// already absolute paths: React asks the document to preload each chunk while
+// it renders, and those tags are right exactly as the payload spells them.
+
+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 };
+
+/** 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.
+ *
+ * Idempotent over the same loader and replaced by a different one, so a dev
+ * server that rebuilds its table installs the new table rather than keeping a
+ * 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 {
+    const namespace = loaded.get(id);
+    if (namespace == null) {
+      throw new Error(
+        `@uniflowed/router: the client module ${id} was required before its server copy loaded`,
+      );
+    }
+    return namespace;
+  }
+  parcelRequire.load = (url: string): Promise<void> =>
+    load(url).then((namespace) => {
+      loaded.set(url, namespace);
+    });
+  parcelRequire.extendImportMap = (): void => {
+    throw new Error("@uniflowed/router: a payload asked for an import map, which uf never writes");
+  };
+  parcelRequire.meta = { publicUrl: "", devServer: null };
+  Object.defineProperty(globalThis, "parcelRequire", {
+    value: parcelRequire,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** 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

@@ -0,0 +1,158 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the names a Flight payload is spoken in.
+//
+// A route rendered by React Server Components travels as React's own Flight
+// payload (ubugeeei-prod/uf#519). `react-server-dom-parcel` writes it on the
+// server and reads it in the browser, and uf invents no format of its own —
+// the one uf used to have for loader data, `./payload.js`'s numbered rows, was
+// Flight-shaped precisely so that it could be replaced by this. What uf still
+// decides is two things around the payload: what its root value *is*, and the
+// URL a browser asks for one at. Every graph has to agree about both, so both
+// are here.
+//
+// Pure data and string functions, and type imports only: the module graph
+// that renders server components, the one that renders HTML and the browser's
+// all import this file, and none of them may be handed anything the others
+// could not evaluate.
+
+import type { Node } from "react";
+
+import type { RouteError, RouteParams, SearchParams } from "./routing.js";
+import type { Metadata, ResolvedRoute } from "./resolve.js";
+
+/**
+ * What a route resolved to, as the browser holds it.
+ *
+ * Everything a hook reads, and nothing that is a module. A resolved route
+ * carries the page, the layouts and the boundaries it loaded; none of those
+ * crosses, because what they rendered is already in the payload beside this
+ * value, and a component the browser does need crosses inside that tree as a
+ * client reference. So `useRoute()` and `useLoaderData()` read this, and
+ * `RouteView` renders the tree.
+ *
+ * `data` and `deferred` cross as Flight values. That is a narrower contract
+ * than the JSON the loader's answer used to be embedded as: Flight carries a
+ * `Date`, a `Map`, a `Set` and a promise, and it refuses a class instance by
+ * name rather than turning it into `{}` the way `JSON.stringify` did. A thrown
+ * error in `error` crosses the way React sends any error value — with its
+ * message in development and replaced by React's own sentence in a build.
+ */
+export type RouteState = {|
+  readonly pathname: string,
+  readonly search: string,
+  readonly path: string,
+  readonly params: RouteParams,
+  readonly searchParams: SearchParams,
+  /** What the loader returned, once it has. `undefined` while `deferred` is set. */
+  readonly data: mixed,
+  /** The loader still running, as a promise the browser can `use`. */
+  readonly deferred: ?Promise<mixed>,
+  readonly metadata: Metadata,
+  readonly viewTransition: ?string,
+  readonly status: 200 | 401 | 403 | 404 | 500,
+  readonly error: ?RouteError,
+|};
+
+/** Row 0 of a route's payload: the route, and the tree it rendered. */
+export type FlightRoot = {|
+  readonly route: RouteState,
+  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 {
+    pathname: resolved.pathname,
+    search: resolved.search,
+    path: resolved.path,
+    params: resolved.params,
+    searchParams: resolved.searchParams,
+    data: resolved.data,
+    deferred: resolved.deferred,
+    metadata: resolved.metadata,
+    viewTransition: resolved.viewTransition,
+    status: resolved.status,
+    error: resolved.error,
+  };
+}
+
+/**
+ * The last path segment of the URL a route's payload is fetched from.
+ *
+ * A path rather than a header, for the two reasons a header would have been
+ * wrong. A static host answers files, and a file has one name per URL: `uf
+ * build` writes `dist/guide/__uf.flight` beside `dist/guide/index.html`, and a
+ * host that has never heard of uf serves both. And a shared cache that ignores
+ * `Vary` would hand a browser a payload where it asked for a document, which is
+ * the class of bug `docs/security.md` records for RSC caches — a different URL
+ * cannot be confused with the document's by anything that caches by URL.
+ *
+ * A segment rather than an extension, so that `/` and `/index` stay two URLs
+ * with two payloads, and so that a middleware guarding `/dashboard` guards the
+ * payload of `/dashboard` by the path rule it already has.
+ */
+export const FLIGHT_SEGMENT: string = "__uf.flight";
+
+/** The content type a payload is answered with. */
+export const FLIGHT_CONTENT_TYPE: string = "text/x-component";
+
+/**
+ * The URL of `url`'s payload: its pathname with [`FLIGHT_SEGMENT`] appended,
+ * and its query string unchanged.
+ *
+ * `url` is a path and query, as the router holds one; a hash never reaches a
+ * server and is dropped.
+ */
+export function flightUrl(url: string): string {
+  const hash = url.indexOf("#");
+  const withoutHash = hash === -1 ? url : url.slice(0, hash);
+  const question = withoutHash.indexOf("?");
+  const pathname = question === -1 ? withoutHash : withoutHash.slice(0, question);
+  const search = question === -1 ? "" : withoutHash.slice(question);
+  const trimmed = pathname.replace(/\/+$/, "");
+  return `${trimmed}/${FLIGHT_SEGMENT}${search}`;
+}
+
+/**
+ * The document path a payload URL's pathname names, or `null` when the
+ * pathname is not a payload URL.
+ *
+ * `/__uf.flight` is the root's; `/guide/__uf.flight` is `/guide`'s. Anything
+ * else is `null`, and that includes a pathname that merely contains the segment
+ * somewhere in the middle — `/__uf.flight/x` is a URL some route may own.
+ */
+export function documentPathOf(pathname: string): string | null {
+  const suffix = `/${FLIGHT_SEGMENT}`;
+  if (!pathname.endsWith(suffix)) {
+    return null;
+  }
+  const document = pathname.slice(0, pathname.length - suffix.length);
+  return document === "" ? "/" : document;
+}