@uniflowed/vite 0.0.0-alpha.34 → 0.0.0-alpha.37

package/internal/frontmatter.js

@@ -0,0 +1,33 @@
+// @noflow
+//
+// A document's YAML front matter, as `export const frontmatter`.
+//
+// Plain JavaScript, for the reason `index.js` gives: Vite imports this before
+// any transform runs.
+//
+// This is `remark-mdx-frontmatter` for the one format uf reads, and it replaces
+// that package for one reason. The package imported `toml` 3.0.0 at the top of
+// its module whether or not a document held any TOML, so every project uf
+// scaffolded installed a parser with two high advisories and failed its first
+// `uf audit` (#1009). The TOML half was never reachable from here either:
+// `remark-frontmatter` is given its default, which recognises YAML and nothing
+// else, so a `+++` block was never a front-matter node to parse.
+//
+// For YAML the output is the package's, through the same two helpers it used:
+// the first `yaml` node is parsed and defined as `frontmatter`, and a document
+// with none exports `undefined`.
+
+import { valueToEstree } from "estree-util-value-to-estree";
+import { define } from "unist-util-mdx-define";
+import { parse } from "yaml";
+
+/** The remark plugin: `export const frontmatter` from a document's YAML. */
+export default function remarkFrontmatterExport() {
+  return (tree, file) => {
+    const node = tree.children.find((child) => child.type === "yaml");
+    const data = node == null ? undefined : parse(node.value);
+    define(tree, file, {
+      frontmatter: valueToEstree(data, { preserveReferences: true }),
+    });
+  };
+}

package/internal/http.js

@@ -25,13 +25,18 @@
  * that accepts an upload should not need the whole thing buffered before it
  * starts.
  *
+ * `path` names the path and query to build it at, when that is not the one the
+ * request line carried — `uf dev` passes the one Vite's base middleware has
+ * already taken `app.router.basePath` off.
+ *
  * @param {import("node:http").IncomingMessage} incoming
  * @param {{server?: {https?: unknown}} | undefined} config the resolved Vite config
+ * @param {string} [path]
  */
-export async function toRequest(incoming, config) {
+export async function toRequest(incoming, config, path) {
   const host = incoming.headers.host ?? "localhost";
   const protocol = config?.server?.https == null ? "http" : "https";
-  const url = new URL(incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${host}`);
+  const url = new URL(path ?? incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${host}`);
 
   const headers = new Headers();
   for (const [name, value] of Object.entries(incoming.headers)) {
@@ -52,6 +57,20 @@ export async function toRequest(incoming, config) {
   return new Request(url, init);
 }
 
+/**
+ * A Node request as a `Request` that carries its address and nothing else.
+ *
+ * For the questions asked about a URL alone — `app.router`'s redirects and
+ * headers, in front of Vite's own middleware — which must not wrap the body a
+ * later middleware turns into the `Request` the application reads.
+ *
+ * @param {import("node:http").IncomingMessage} incoming
+ */
+export function toAddressRequest(incoming) {
+  const host = incoming.headers.host ?? "localhost";
+  return new Request(new URL(incoming.originalUrl ?? incoming.url ?? "/", `http://${host}`));
+}
+
 /**
  * Write a `Response` to a Node response.
  *

package/internal/module-graph.js

@@ -0,0 +1,134 @@
+// @noflow
+//
+// Plain JavaScript: the driver imports it, and the driver runs before any Flow
+// loader exists.
+//
+// The module graph `uf build --analyze` reads: every module each bundle was
+// built from, what it imports, and which chunk its rendered code went into.
+//
+// What the graph means — which route a module belongs to, the chain of imports
+// behind it, what it weighs — is uf's, in `crates/uf_bundle/src/analysis.rs`.
+// This file writes down only what the bundler knows and uf cannot, and that
+// split is the reason the graph is a file at all: a builder other than this
+// one that writes the same file gets the same analysis.
+//
+//   {
+//     "version": 1,
+//     "builds": [{
+//       "environment": "client",
+//       "entries": ["virtual:uf/client"],
+//       "modules": [{ "id": "app/$page.js", "imports": ["app/Counter.js"], "dynamicImports": [] }],
+//       "chunks": [{
+//         "file": "assets/index-3f2a.js",
+//         "facade": "virtual:uf/client",
+//         "modules": [{ "id": "virtual:uf/client", "code": "…" }]
+//       }]
+//     }]
+//   }
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Where the driver writes the graph, in the build's metadata directory. */
+export const MODULE_GRAPH_FILE = "uf-module-graph.json";
+
+const VERSION = 1;
+
+/**
+ * A plugin that records the graph of every bundle it takes part in, and the
+ * means to write what it recorded.
+ *
+ * `isReference(file)` says whether an absolute file is a client reference: an
+ * entry the browser loads because a server component named it, rather than on
+ * every page. Its chunk still carries it as the facade, and it is left out of
+ * `entries`, which is the list of what every page of a bundle loads.
+ */
+export function createModuleGraphCollector(root, { isReference = () => false } = {}) {
+  const builds = [];
+  const graph = () => ({ version: VERSION, builds });
+  return {
+    plugin: {
+      name: "uf:module-graph",
+      // Last, so the bundle it reads is one every other plugin has finished.
+      enforce: "post",
+      generateBundle(_options, bundle) {
+        builds.push(describeBundle(this, root, bundle, isReference));
+      },
+    },
+    graph,
+    write(file) {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${JSON.stringify(graph())}\n`);
+    },
+  };
+}
+
+/** One bundle, as `generateBundle` sees it. */
+function describeBundle(context, root, bundle, isReference) {
+  const ids = typeof context.getModuleIds === "function" ? [...context.getModuleIds()] : [];
+  const modules = ids
+    .map((id) => {
+      const info = context.getModuleInfo(id);
+      return {
+        id: moduleId(root, id),
+        imports: (info?.importedIds ?? []).map((imported) => moduleId(root, imported)),
+        dynamicImports: (info?.dynamicallyImportedIds ?? []).map((imported) =>
+          moduleId(root, imported),
+        ),
+      };
+    })
+    .sort(byKey("id"));
+  const entries = new Set();
+  const chunks = [];
+  for (const output of Object.values(bundle)) {
+    if (output.type !== "chunk") {
+      continue;
+    }
+    const facade = output.isEntry ? (output.facadeModuleId ?? null) : null;
+    if (facade != null && !isReference(facade.split("?")[0])) {
+      entries.add(moduleId(root, facade));
+    }
+    chunks.push({
+      file: output.fileName,
+      facade: facade == null ? null : moduleId(root, facade),
+      // A module the bundler left no code for was still walked through to
+      // reach what it imports, so it stays in `modules` above; it has nothing
+      // to weigh, so it is not in the chunk.
+      modules: Object.entries(output.modules ?? {})
+        .map(([id, rendered]) => ({ id: moduleId(root, id), code: rendered?.code ?? "" }))
+        .filter((module) => module.code !== ""),
+    });
+  }
+  return {
+    environment: context.environment?.name ?? "client",
+    entries: [...entries].sort(),
+    modules,
+    chunks: chunks.sort(byKey("file")),
+  };
+}
+
+/**
+ * A module id as the analysis spells it: relative to the project root with
+ * `/`, without the `\0` a resolved virtual module carries, and with its query.
+ *
+ * Relative even when it climbs out of the root, as a workspace package does,
+ * because an absolute path would make two machines' reports of the same build
+ * disagree.
+ */
+export function moduleId(root, id) {
+  const bare = id.startsWith("\0") ? id.slice(1) : id;
+  const at = bare.indexOf("?");
+  const file = at === -1 ? bare : bare.slice(0, at);
+  if (!path.isAbsolute(file)) {
+    return bare;
+  }
+  const relative = path.relative(root, file);
+  if (path.isAbsolute(relative)) {
+    return bare;
+  }
+  return `${relative.split(path.sep).join("/")}${at === -1 ? "" : bare.slice(at)}`;
+}
+
+function byKey(key) {
+  return (a, b) => (a[key] < b[key] ? -1 : a[key] > b[key] ? 1 : 0);
+}

package/internal/routes.js

@@ -1653,10 +1653,11 @@ export function clientModuleSource(appEntry, options = {}) {
   const strictMode = options.strictMode === true ? ", strictMode: true" : "";
   const navigation = options.navigation === "document" ? ', navigation: "document"' : "";
   const mount = options.mount === "render" ? "render" : "hydrate";
+  const routing = routingArgumentSource(options.routing);
   return `import { ${mount} } from "@uniflowed/router/client";
 import { routes, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-${mount}({ App, routes, notFound, errors${strictMode}${navigation} });
+${mount}({ App, routes, notFound, errors${strictMode}${navigation}${routing} });
 `;
 }
 
@@ -1714,16 +1715,18 @@ ${mount}({ App, routes, notFound, errors${strictMode}${navigation} });
  * shorter proof of the paragraph above: the copy the router dispatches and
  * renders with is by construction the copy the host is handed.
  */
-export function serverModuleSource(appEntry) {
+export function serverModuleSource(appEntry, routing = routingRulesOf({})) {
   return `import {
   createActionDispatcher,
   createDispatcher,
   createMiddlewareRunner,
   createRenderer,
+  installRouting,
 } from "@uniflowed/router/server";
 import { routes, handlers, middleware, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import { actions } from ${JSON.stringify(VIRTUAL.actions)};
 import App from ${JSON.stringify(appEntry)};
+${routingExportSource(routing)}installRouting(routing);
 export { routes, handlers, middleware, notFound, errors };
 export { beginRequest } from "@uniflowed/router/server";
 const renderer = createRenderer({ App, routes, notFound, errors });
@@ -1735,3 +1738,53 @@ export const callAction = createActionDispatcher({ actions });
 export const runMiddleware = createMiddlewareRunner({ middleware });
 `;
 }
+
+/**
+ * `app.router.redirects`, `rewrites` and `headers`, as the bundle carries them.
+ *
+ * Three lists and nothing else, each present, so a host reads `routing` the one
+ * way whatever the project wrote. Validation is not here: `uf_config` refuses a
+ * rule it cannot read when the file is loaded, with a sentence per spelling,
+ * and `@uniflowed/server`'s `internal/routing.js` is what interprets one.
+ *
+ * @param {{redirects?: unknown[], rewrites?: unknown[], headers?: unknown[]} | undefined} router
+ */
+export function routingRulesOf(router) {
+  const policy = router?.trailingSlash;
+  return {
+    redirects: Array.isArray(router?.redirects) ? router.redirects : [],
+    rewrites: Array.isArray(router?.rewrites) ? router.rewrites : [],
+    headers: Array.isArray(router?.headers) ? router.headers : [],
+    basePath: typeof router?.basePath === "string" ? router.basePath.replace(/\/+$/, "") : "",
+    trailingSlash: policy === "never" || policy === "always" ? policy : "ignore",
+  };
+}
+
+/**
+ * `basePath` and `trailingSlash` as arguments to a client entry's call, or
+ * nothing for a project at the root with the default policy — so a default
+ * project's entry is the module it has always been.
+ *
+ * @param {{basePath?: string, trailingSlash?: string} | undefined} routing
+ */
+export function routingArgumentSource(routing) {
+  const basePath = routing?.basePath ?? "";
+  const trailingSlash = routing?.trailingSlash ?? "ignore";
+  let source = "";
+  if (basePath !== "") source += `, basePath: ${JSON.stringify(basePath)}`;
+  if (trailingSlash !== "ignore") source += `, trailingSlash: ${JSON.stringify(trailingSlash)}`;
+  return source;
+}
+
+/**
+ * The `routing` export of `virtual:uf/server`.
+ *
+ * On the bundle rather than read from `uf.config.js` where a host starts, so a
+ * served build answers with the rules it was built with — `uf start` of last
+ * week's build, and every `--adapter` artefact, carry their own.
+ *
+ * @param {ReturnType<typeof routingRulesOf>} routing
+ */
+export function routingExportSource(routing) {
+  return `export const routing = ${JSON.stringify(routing)};\n`;
+}

package/internal/serve.js

@@ -156,8 +156,13 @@ async function cacheFor(declared, createCacheStore, where) {
  * @param {{store?: string, storeDir?: string} | undefined} declared
  * @param {{root: string, build: string | null}} where
  */
-async function providerFor(declared, { root, build }) {
-  const named = declared?.store ?? "memory";
+async function providerFor(declared, { root, build, regenerates }) {
+  // A build that regenerates pages keeps what it regenerated on disk unless the
+  // project named a store. A restart that took every regenerated page back to
+  // the build's copy would be a server whose pages went back in time, which is
+  // the one thing regeneration is for not doing. `"memory"`, said out loud, is
+  // still memory.
+  const named = declared?.store ?? (regenerates === true ? "filesystem" : "memory");
   if (named === "memory") return null;
   if (build == null) {
     throw new Error(
@@ -213,7 +218,81 @@ export async function loadBuild({ root, outDir, serverDir }) {
   const entry = await import(pathToFileURL(entryFile).href);
   await deployment();
   const build = await buildIdentity(root, serverDir);
-  return { entry, assets: assetsFromManifest(manifest), distDir, root, build };
+  const regeneration = await readRegeneration(path.resolve(root, serverDir));
+  return {
+    entry,
+    assets: await documentAssetsFor(path.resolve(root, serverDir), manifest),
+    distDir,
+    root,
+    build,
+    regeneration,
+  };
+}
+
+/** What `uf build` records a document's tags in, beside the server bundle. */
+export const DOCUMENT_ASSETS_FILE = "uf-document-assets.json";
+
+/**
+ * The tags a served document needs: the ones `uf build` recorded, or — for a
+ * build from before it recorded them — the client manifest's.
+ *
+ * Recorded rather than recomputed, because the client manifest is no longer the
+ * whole answer. An application React Server Components render links the
+ * stylesheets its rsc graph emitted and the ones each client module's chunk
+ * carries, and neither is reachable from the client entry the manifest is walked
+ * from — so a server that recomputed the tags rendered every page without the
+ * stylesheets its prerendered pages had. `uf start`, `uf preview`, `--adapter`
+ * and `--compile` all read them from here.
+ *
+ * @param {string} serverDir absolute path of the server bundle's directory
+ * @param {object} manifest the client build's Vite manifest
+ */
+export async function documentAssetsFor(serverDir, manifest) {
+  const file = path.join(serverDir, DOCUMENT_ASSETS_FILE);
+  let recorded;
+  try {
+    recorded = await readFile(file, "utf8");
+  } catch {
+    return assetsFromManifest(manifest);
+  }
+  try {
+    return JSON.parse(recorded);
+  } catch {
+    throw new Error(`uf: ${file} is not the JSON \`uf build\` writes; run \`uf build\` again`);
+  }
+}
+
+/**
+ * The file beside the server bundle that names the pages a build regenerates.
+ *
+ * Written by `driver.js`'s build, and only for a build that has such a page.
+ */
+export const REGENERATION_FILE = "regenerate.json";
+
+/**
+ * Where a regenerated page's document goes, under the build's output directory.
+ *
+ * Somewhere no static half answers the page's own URL, which is the point: a
+ * file at `dist/posts/a/index.html` would be served by every host before the
+ * server saw the request, forever, whatever the page's lifetime said.
+ */
+export const REGENERATED_DIRECTORY = "__uf/regenerate";
+
+/**
+ * The pages this build regenerates, or `undefined` for a build that has none.
+ *
+ * `undefined` rather than an empty manifest, so a build with nothing to
+ * regenerate serves exactly as every build did before regeneration existed.
+ */
+export async function readRegeneration(serverDir) {
+  let text;
+  try {
+    text = await readFile(path.join(serverDir, REGENERATION_FILE), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+  return JSON.parse(text);
 }
 
 /**
@@ -303,8 +382,15 @@ async function readable(file, message) {
  * the rest moved to `@uniflowed/server`. `uf build --adapter` calls it too,
  * at build time, and bakes the answer into what it emits.
  */
-export function assetsFromManifest(manifest) {
-  const entry = Object.values(manifest).find((chunk) => chunk.isEntry);
+export function assetsFromManifest(manifest, base = "") {
+  // `client` by name first. An application React Server Components render
+  // gives the client build one entry per client module as well, and the
+  // document's script is the application's entry, not whichever of those the
+  // manifest happens to list first.
+  const chunks = Object.values(manifest);
+  const entry =
+    chunks.find((chunk) => chunk.isEntry && chunk.name === "client") ??
+    chunks.find((chunk) => chunk.isEntry);
   if (entry == null) throw new Error("uf: the client manifest has no entry chunk");
 
   const styles = new Set(entry.css ?? []);
@@ -332,10 +418,12 @@ export function assetsFromManifest(manifest) {
   };
   collectPreloads(entry);
 
+  // Under `app.router.basePath` when there is one: a prerendered document is
+  // written outside Vite's HTML transform, so nothing else would put it there.
   return {
-    scripts: [`/${entry.file}`],
-    styles: [...styles].map((file) => `/${file}`),
-    preloads: [...preloads].map((file) => `/${file}`),
+    scripts: [`${base}/${entry.file}`],
+    styles: [...styles].map((file) => `${base}/${file}`),
+    preloads: [...preloads].map((file) => `${base}/${file}`),
   };
 }
 
@@ -437,7 +525,7 @@ export async function beginRequest(entry, request) {
  *
  * @param {{entry: object, assets: object, cache?: object, root?: string, build?: string | null}} build
  */
-export function createApplicationHandler({ entry, assets, cache, root, build }) {
+export function createApplicationHandler({ entry, assets, cache, root, build, regeneration }) {
   const ready = deployment().then(
     async ({ createFetchHandler, createCacheStore, nodeCapabilities }) =>
       createFetchHandler({
@@ -446,7 +534,12 @@ export function createApplicationHandler({ entry, assets, cache, root, build })
         cache: await cacheFor(cache, createCacheStore, {
           root: root ?? process.cwd(),
           build: build ?? null,
+          regenerates: regeneration != null,
         }),
+        // The pages this build regenerates, from the manifest beside the server
+        // bundle. Absent for a build with none, which then serves exactly as it
+        // did before regeneration existed.
+        ...(regeneration == null ? {} : { regeneration }),
         // `uf preview` and `uf start` are a Node process with a socket, which is
         // what a deployed `--adapter node` build is too — so a route handler
         // that streams events answers the same way in the preview it is checked
@@ -482,16 +575,115 @@ export function createStaticHandler({ root }) {
  * project whose handler path collides with a file in `public/` behaves one way
  * when it is checked and the other way when it is deployed.
  *
- * @param {{entry: object, assets: object, distDir: string, cache?: object, root?: string, build?: string | null}} build
+ * It is `@uniflowed/server/node`'s own `createServeHandler`, the one a deployed
+ * `server.js` runs, rather than the two halves composed a second time here.
+ * That one also hands the application the build's files when the static half
+ * has nothing, which is how a regenerated page starts from the document the
+ * build wrote; a composition of its own here would be a `uf start` whose
+ * regenerated pages rendered on their first request while a deployment's did
+ * not.
+ *
+ * It is handed the bundle's `routing` too, so `app.router`'s redirects answer
+ * before the files and its headers go on whatever answers, here exactly as in
+ * a deployment. `uf preview` puts the same two in front of Vite's file
+ * middleware as well; see [`answerRouting`].
+ *
+ * @param {{entry: object, assets: object, distDir: string, cache?: object, root?: string, build?: string | null, regeneration?: object}} build
  */
-export function createServeHandler({ entry, assets, distDir, cache, root, build }) {
-  const serveStatic = createStaticHandler({ root: distDir });
-  const application = createApplicationHandler({ entry, assets, cache, root, build });
+export function createServeHandler({ entry, assets, distDir, cache, root, build, regeneration }) {
+  const application = createApplicationHandler({ entry, assets, cache, root, build, regeneration });
+  const ready = deployment().then(({ createServeHandler: create }) =>
+    create({ staticDir: distDir, handle: application, routing: entry.routing }),
+  );
   return async function handle(request) {
-    return (await serveStatic(request)) ?? (await application(request));
+    return (await ready)(request);
   };
 }
 
+/**
+ * Whether `routing` has anything to say in front of a file server.
+ *
+ * Redirects and headers are the two that do; a rewrite is the application's.
+ * Asked before a middleware is mounted at all, so a project with no rules pays
+ * nothing per request under `uf dev` or `uf preview`.
+ *
+ * @param {{redirects?: unknown[], headers?: unknown[]} | undefined} routing
+ */
+export function answersInFrontOfFiles(routing) {
+  return (
+    (routing?.redirects?.length ?? 0) > 0 ||
+    (routing?.headers?.length ?? 0) > 0 ||
+    (routing?.basePath ?? "") !== "" ||
+    (routing?.trailingSlash ?? "ignore") !== "ignore"
+  );
+}
+
+/**
+ * `app.router`'s headers and redirects, for a door whose files Vite serves.
+ *
+ * `uf dev` and `uf preview` mount this in front of Vite's own middleware:
+ * the headers are pinned on the Node response, so they survive the
+ * `writeHead` Vite's file server writes its own with, and a redirect is
+ * answered before any file is looked for. `true` when it answered.
+ *
+ * @param {object} routing the bundle's `routing`
+ * @param {Request} request the address alone; see `toAddressRequest`
+ * @param {import("node:http").ServerResponse} response
+ */
+export async function answerRouting(routing, request, response) {
+  const { admit, headersFor, pinHeaders, send: write } = await deployment();
+  pinHeaders(response, headersFor(routing, request));
+  // A request outside the base path, the other spelling of a path, or a
+  // redirect rule: answered here, before Vite's own base middleware would
+  // answer the first in its words rather than uf's.
+  const admitted = admit(routing, request);
+  if (admitted.kind !== "answer") return false;
+  await write(response, admitted.response);
+  return true;
+}
+
+/**
+ * A request [`answerRouting`] let through, spelled so Vite's own middleware
+ * recognises it.
+ *
+ * Vite serves under its `base` with the trailing slash, `/docs/`, and its base
+ * middleware answers every other path with a 404 of its own, the bare `/docs`
+ * included. But `/docs` is the application's root under `app.router.basePath`,
+ * and the only spelling of it unless the trailing-slash policy is `"always"`,
+ * which has already answered `/docs` with a `308` by the time this is asked.
+ * So a request for exactly the base goes on to Vite as `/docs/`, which Vite
+ * takes the base off and hands on as the root. The application is handed the
+ * root either way.
+ *
+ * @param {{basePath?: string} | undefined} routing the bundle's `routing`
+ * @param {import("node:http").IncomingMessage} request
+ */
+export function forViteBase(routing, request) {
+  const base = routing?.basePath ?? "";
+  const url = request.url ?? "/";
+  if (base === "") return;
+  const queryAt = url.indexOf("?");
+  const pathname = queryAt === -1 ? url : url.slice(0, queryAt);
+  if (pathname === base) {
+    request.url = `${base}/${queryAt === -1 ? "" : url.slice(queryAt)}`;
+  }
+}
+
+/**
+ * `app.router.rewrites` for this request, for `uf dev`: the rewritten request,
+ * or `null`.
+ *
+ * `@uniflowed/server`'s `rewriteFor`, which `createFetchHandler` asks for every
+ * other front door at the same point — after the files, before the guard.
+ *
+ * @param {object | undefined} routing the bundle's `routing`
+ * @param {Request} request
+ */
+export async function rewriteRouting(routing, request) {
+  const { rewriteFor } = await deployment();
+  return rewriteFor(routing, request);
+}
+
 /**
  * Whether a file server may answer this request, or uf has to go first.
  *

package/internal/server-components.js

@@ -0,0 +1,109 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// What a project needs before its routes can render as React Server Components.
+//
+// `@uniflowed/router` installs beside React 19.2.3, the React that Expo SDK 57
+// and React Native 0.87 ship, and lists `react-server-dom-parcel` as an optional
+// peer (ubugeeei-prod/uf#992). An application rendered from its modules
+// (`app.rsc: false`) needs nothing more. One whose routes render as Server
+// Components, which is the default, needs that package and the React it was
+// released with. Without the package a build fails on an unresolved import
+// somewhere inside the router, and on too old a React it fails later, inside a
+// render, in terms of React's internals. So `uf:flow` asks here once, while Vite
+// reads its configuration, and stops with one sentence that says what the
+// project has and what to change.
+//
+// The router's own Server Components entries refuse the same React at run time
+// (`packages/router/internal/react-version.js`). This is the earlier half of the
+// same rule, for a project that builds with uf.
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The oldest React, and `react-server-dom-parcel`, that Server Components render on. */
+export const SERVER_COMPONENTS_REACT = "19.3.0";
+
+/**
+ * What stops the project at `root` from rendering React Server Components, as a
+ * sentence, or `null` when nothing does.
+ *
+ * Both packages are resolved the way the router's own imports resolve them: from
+ * the `@uniflowed/router` the project resolves, or from the one this package
+ * depends on when the project names none. A prerelease tag is ignored, so a 19.3
+ * canary counts as 19.3.
+ *
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function serverComponentsProblem(root) {
+  const router =
+    resolveFrom(path.join(root, "package.json"), "@uniflowed/router/package.json") ??
+    resolveFrom(fileURLToPath(import.meta.url), "@uniflowed/router/package.json") ??
+    path.join(root, "package.json");
+  const react = versionOf(resolveFrom(router, "react/package.json"));
+  const flight = versionOf(resolveFrom(router, "react-server-dom-parcel/package.json"));
+
+  const found = [];
+  if (react == null) {
+    found.push("no react");
+  } else if (!isRecentEnough(react)) {
+    found.push(`React ${react}`);
+  }
+  if (flight == null) {
+    found.push("no react-server-dom-parcel");
+  } else if (!isRecentEnough(flight)) {
+    found.push(`react-server-dom-parcel ${flight}`);
+  }
+  if (found.length === 0) {
+    return null;
+  }
+  return (
+    "uf: routes render as React Server Components unless `app.rsc` is false, and that needs " +
+    `react-server-dom-parcel and React ${SERVER_COMPONENTS_REACT} or newer. This project has ` +
+    `${found.join(" and ")}. 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."
+  );
+}
+
+/** Where `specifier` resolves from the file at `from`, or `null`. */
+function resolveFrom(from, specifier) {
+  try {
+    return createRequire(from).resolve(specifier);
+  } catch {
+    return null;
+  }
+}
+
+/** The `version` in the manifest at `file`, or `null`. */
+function versionOf(file) {
+  if (file == null) {
+    return null;
+  }
+  try {
+    const { version } = JSON.parse(fs.readFileSync(file, "utf8"));
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether `version` is at least `SERVER_COMPONENTS_REACT`, ignoring a prerelease tag. */
+function isRecentEnough(version) {
+  const found = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  if (found == null) {
+    return false;
+  }
+  const needed = SERVER_COMPONENTS_REACT.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const part = Number(found[index + 1]);
+    if (part !== needed[index]) {
+      return part > needed[index];
+    }
+  }
+  return true;
+}