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

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,7 @@ import {
   hasClientPage,
   installNavigation,
   installRoutes,
+  installRouting,
   matchRoute,
   resolveFailure,
   resolveMatch,
@@ -108,7 +116,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 +133,8 @@ export async function hydrate(options: {|
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
   readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -136,15 +147,18 @@ 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 });
+  // 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 +232,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 +268,8 @@ export async function render(options: {|
   readonly errors: RouteTable["errors"],
   readonly strictMode?: boolean,
   readonly navigation?: Navigation,
+  readonly basePath?: string,
+  readonly trailingSlash?: TrailingSlash,
 |}): Promise<void> {
   const table: RouteTable = {
     routes: options.routes,
@@ -362,14 +278,17 @@ export async function render(options: {|
   };
   installRoutes(table);
   installNavigation(options.navigation ?? "client");
+  installRouting({ basePath: options.basePath, trailingSlash: options.trailingSlash });
 
-  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/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-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 {

package/internal/prepare-document.js

@@ -0,0 +1,49 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: a server's document, made ready for React to
+// hydrate.
+//
+// Where a server wrote the head's metadata, an element React leaves behind, and
+// the placeholder action React writes into a form whose action is a function
+// (its server and its client spell that placeholder differently): none of these
+// comes from a route, and each would be reported as a mismatch. So each is put
+// right before `hydrateRoot` compares the markup with the tree. Both ways of
+// hydrating do it — `hydrate` in `../client.js`, for a route rendered from its
+// modules, and `hydrateFlight` in `../rsc-client.js`, for one React Server
+// Components rendered — so the code lives here rather than in either entry.
+
+export 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);
+    }
+  }
+}

package/internal/react-version.js

@@ -0,0 +1,77 @@
+// @flow
+//
+// Internal to `@uniflowed/router`: the React that React Server Components need.
+//
+// The router installs beside React 19.2.3, the React that Expo SDK 57 and React
+// Native 0.87 ship. Matching a URL, the native route table and a route rendered
+// from its modules need nothing newer (ubugeeei-prod/uf#992). React Server
+// Components do. They render through `react-server-dom-parcel`, React's own
+// Flight renderer and client, which is released with React and requires the
+// React it was released with: 19.3. So that package is an optional peer, and
+// every module that loads it asks here first.
+//
+// # Why a check at run time
+//
+// A peer range cannot say it. The router has one range for `react`, and that
+// range has to admit 19.2.3 for a native app, while an optional peer that is
+// absent is never compared with anything. The failure is also not where the
+// mistake is: React's Flight client imports against React 19.2 and fails later,
+// inside a render, in terms of React's internals. So each entry that loads
+// Flight refuses before it does anything, and names the React it found and the
+// one it needs.
+//
+// It is a call rather than a statement at module scope, because no shipped
+// module runs anything when it is imported
+// (`crates/uf_lib/tests/package_surface.rs`).
+
+import * as React from "react";
+
+/** The oldest React that React Server Components render on. */
+export const SERVER_COMPONENTS_REACT: string = "19.3.0";
+
+/**
+ * Why `entry` cannot run on React `installed`, or `null` when it can.
+ *
+ * The release numbers are compared and a prerelease tag is ignored, so a 19.3
+ * canary counts as 19.3: React names a canary after the release it leads to.
+ */
+export function serverComponentsRefusal(entry: string, installed: string): string | null {
+  const found = releaseOf(installed);
+  const needed = releaseOf(SERVER_COMPONENTS_REACT);
+  if (found != null && needed != null && !isBefore(found, needed)) {
+    return null;
+  }
+  return (
+    `@uniflowed/router: ${entry} needs React ${SERVER_COMPONENTS_REACT} or newer for React ` +
+    `Server Components, and the React it loaded is ${installed}. Install react, react-dom and ` +
+    "react-server-dom-parcel at ^19.3.0, or set `app.rsc: false` in uf.config.js to render " +
+    "routes from their modules, which the router supports from React 19.2.3."
+  );
+}
+
+/**
+ * Refuse, with [`serverComponentsRefusal`]'s sentence, unless the React this
+ * module loaded can render React Server Components.
+ */
+export function requireServerComponentsReact(entry: string): void {
+  const refusal = serverComponentsRefusal(entry, React.version);
+  if (refusal != null) {
+    throw new Error(refusal);
+  }
+}
+
+/** `[major, minor, patch]` of a version, or `null` when it does not start with one. */
+function releaseOf(version: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  return match == null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/** Whether release `a` comes before release `b`. */
+function isBefore(a: [number, number, number], b: [number, number, number]): boolean {
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) {
+      return a[index] < b[index];
+    }
+  }
+  return false;
+}