@txco/react-router 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# @txco/react-router
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [React Router](https://reactrouter.com) preset for
+[Thanks, Computer](https://www.thanks.computer) (txco). After
+`react-router build`, it writes a **Web ABI build** beside your `build/`:
+
+- a copy of `build/client` as `public/`;
+- a route-aware SPA fallback and a catch-all, as `ops/`;
+- a `txco-web.json` manifest.
+
+`txco apply` installs the build into a stack.
+
+```sh
+npm install -D @txco/react-router
+```
+
+React Router 7 and 8, in framework mode.
+
+## Usage
+
+```ts
+// react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+import txco from "@txco/react-router";
+
+export default {
+  ssr: false, // SPA mode: the client renders every page
+  prerender: ["/about"], // optional: pages served as files
+  presets: [txco()],
+} satisfies Config;
+```
+
+Bind the build to a stack in your workspace's `txco.yaml`. The path is
+relative to the workspace root, and must lie outside `OPS/`:
+
+```yaml
+stacks:
+  web:
+    abi: txco-web
+```
+
+Then build, check and deploy:
+
+```sh
+react-router build            # writes build/ as usual, and txco-web/
+txco web check txco-web       # installs it on a scratch chassis and probes it
+txco apply                    # or: txco push web
+```
+
+Gitignore `txco-web/`. It's all build output, and the fallback ops embed the
+app shell, asset hashes included, so they change on every build.
+
+## How a request is answered
+
+1. **A file**, such as a prerendered page (`/about` → `about/index.html`), an
+   asset, or a `.data` file, is served before your stack runs.
+2. **Your own ops** in the stack run next.
+3. **The preset's ops** go last:
+   - a navigation to a path your routes know (`/users/42` for
+     `users/:id`) gets the app shell with status 200;
+   - any other navigation gets the shell with status 404, and the client
+     renders its error boundary;
+   - everything else, such as a missing asset or a POST, gets a plain 404.
+
+The matcher comes from React Router's own route table: params (`:id`),
+optional segments (`:lang?`, `beta?`), a final splat (`*`) and `basename`.
+It's case-insensitive unless a route sets `caseSensitive`. A splat route
+makes every path known. A route the matcher can't express makes every
+navigation get the shell with 200.
+
+When `/` is prerendered, React Router writes the shell as
+`__spa-fallback.html`, and the preset uses that.
+
+## Server rendering
+
+With `ssr: true`, React Router builds a server, and no chassis runs one yet.
+The preset deploys what was prerendered, gives every other page the 404 page,
+and warns. For an app the client renders, set `ssr: false`.
+
+## Options
+
+| Option       | Default        | Meaning |
+| ------------ | -------------- | ------- |
+| `out`        | `"txco-web"`   | The Web ABI directory to write, relative to the project root. It must be a directory of its own, outside `OPS/` and `build/`. |
+| `routeAware` | `true`         | `false` gives every page path the shell with 200. |
+| `immutable`  | `["assets/"]`  | The `public/` prefixes cached for a year. |
+| `scope`      | `900000`       | The navigation ops' scope. The catch-all goes 900 above it. |
+
+## License
+
+MIT

package/dist/build.d.ts

@@ -0,0 +1,43 @@
+import { type NavMode } from "@txco/web-abi/producer";
+import { type RouteManifest } from "./routes.js";
+export declare const NAME = "@txco/react-router";
+export declare const VERSION = "0.1.0";
+export interface TxcoOptions {
+    /** The Web ABI directory to write, relative to the project root. Default "txco-web". */
+    out?: string;
+    /**
+     * Give an unknown page path the shell with 404, from the route table.
+     * false answers every page path with the shell and 200. Default true.
+     */
+    routeAware?: boolean;
+    /** The public/ prefixes cached for a year. Default: Vite's assetsDir (`assets/`). */
+    immutable?: string[];
+    /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+    scope?: number;
+}
+export interface BuildInput {
+    /** The project root (Vite's root). */
+    root: string;
+    /** reactRouterConfig.buildDirectory: client output is <it>/client. */
+    buildDirectory: string;
+    /** Vite's base (where the assets are served). */
+    base: string;
+    /** Vite's build.assetsDir. */
+    assetsDir: string;
+    /** reactRouterConfig.basename (where the routes are). */
+    basename: string;
+    /** reactRouterConfig.ssr. */
+    ssr: boolean;
+    routes: RouteManifest;
+    options: TxcoOptions;
+    log: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+export interface BuildResult {
+    mode: NavMode;
+    ops: string[];
+    manifest: Record<string, unknown>;
+}
+export declare function writeBuild(i: BuildInput): Promise<BuildResult>;

package/dist/build.js

@@ -0,0 +1,81 @@
+// Writes the Web ABI build from React Router's finished output. Called from
+// the preset's buildEnd; takes plain inputs, so it's tested without a build.
+import { readFile, rm, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { copyPublic, listFiles, looksHashed, publicPrefix, renderOps, writeManifest, writeOps, } from "@txco/web-abi/producer";
+import { routesMatcher } from "./routes.js";
+export const NAME = "@txco/react-router";
+export const VERSION = "0.1.0";
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+const exists = (p) => stat(p).then(() => true, () => false);
+export async function writeBuild(i) {
+    const warn = (msg) => i.log.warn(`[txco] ${msg}`);
+    const clientDir = resolve(i.root, i.buildDirectory, "client");
+    if (!(await exists(clientDir)))
+        throw new Error(`[txco] React Router's client build isn't at ${clientDir}`);
+    const out = resolve(i.root, i.options.out ?? "txco-web");
+    const { prefix, external } = publicPrefix(i.base);
+    if (external)
+        warn(`base is ${i.base}: the assets load from there, and the pages are deployed at the root`);
+    await rm(out, { recursive: true, force: true });
+    const { skipped } = await copyPublic(clientDir, out, prefix);
+    if (skipped.length > 0)
+        warn(`build/client has ${skipped.length} dot path(s) (${skipped.slice(0, 3).join(", ")}); they never deploy`);
+    const readPage = async (name) => {
+        const html = await readFile(join(clientDir, name), "utf8").catch(() => null);
+        return html === null ? null : { name, html };
+    };
+    let mode;
+    let page = null;
+    let routes;
+    const notes = [];
+    if (i.ssr) {
+        // No chassis runs a server yet: deploy what was prerendered.
+        warn("ssr: true needs a server, and no chassis runs one yet: only the prerendered pages deploy. For an SPA, set ssr: false.");
+        mode = "404";
+        notes.push("A server-rendered React Router app: only its prerendered pages deploy until a runner exists.");
+    }
+    else {
+        // In SPA mode the shell is __spa-fallback.html when "/" is prerendered.
+        page = (await readPage("__spa-fallback.html")) ?? (await readPage("index.html"));
+        if (!page)
+            throw new Error(`[txco] an ssr: false build needs its shell (index.html or __spa-fallback.html) in ${clientDir}`);
+        const matcher = i.options.routeAware === false ? null : routesMatcher(i.routes, i.basename);
+        if (matcher) {
+            mode = "routes";
+            routes = matcher;
+            notes.push("The route set comes from React Router's route table.");
+        }
+        else {
+            mode = "spa";
+            if (i.options.routeAware !== false)
+                notes.push("A route couldn't be expressed as a matcher, so unknown pages get 200 too.");
+        }
+    }
+    if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+        warn(`${page.name} is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+    }
+    const ops = renderOps({ mode, scope: i.options.scope, producer: NAME, page, routes, notes });
+    await writeOps(out, ops);
+    const files = await listFiles(join(out, "public"));
+    const assets = i.assetsDir.replace(/^\/+|\/+$/g, "");
+    const immutable = i.options.immutable ?? (assets && files.some((f) => f.startsWith(`${prefix}${assets}/`)) ? [`${prefix}${assets}/`] : []);
+    for (const p of immutable) {
+        const unhashed = files.filter((f) => f.startsWith(p) && !looksHashed(f.split("/").pop()));
+        if (unhashed.length > 0) {
+            warn(`${unhashed.length} file(s) under the immutable prefix ${p} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+        }
+    }
+    const manifest = {
+        abi: 1,
+        ...(immutable.length > 0 ? { immutable } : {}),
+        "x-producer": { name: NAME, version: VERSION },
+        "x-react-router": { ssr: i.ssr, mode, routes: Object.keys(i.routes).length },
+    };
+    await writeManifest(out, manifest);
+    const shown = relative(process.cwd(), out) || ".";
+    i.log.info(`[txco] Web ABI build (${mode}) at ${shown}: ${files.length} public file(s), ${Object.keys(ops).length} op(s). ` +
+        `Next: \`txco web check ${shown}\`, bind it in txco.yaml (stacks: <name>: abi: ${shown}), then \`txco apply\`.`);
+    return { mode, ops: Object.keys(ops).sort(), manifest };
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type TxcoOptions } from "./build.js";
+import type { RouteManifest } from "./routes.js";
+export type { TxcoOptions } from "./build.js";
+export { routeRegex, routesMatcher } from "./routes.js";
+interface ResolvedConfig {
+    buildDirectory: string;
+    basename: string;
+    ssr: boolean;
+    routes: RouteManifest;
+}
+interface BuildEndArgs {
+    buildManifest?: {
+        routes: RouteManifest;
+    };
+    reactRouterConfig: ResolvedConfig;
+    viteConfig: {
+        root: string;
+        base: string;
+        build: {
+            assetsDir: string;
+        };
+        logger: {
+            info(msg: string): void;
+            warn(msg: string): void;
+        };
+    };
+}
+export interface Preset {
+    name: string;
+    reactRouterConfig?: (args: {
+        reactRouterUserConfig: unknown;
+    }) => {
+        buildEnd: (args: BuildEndArgs) => Promise<void>;
+    };
+    reactRouterConfigResolved?: (args: {
+        reactRouterConfig: ResolvedConfig;
+    }) => Promise<void>;
+}
+export default function txco(options?: TxcoOptions): Preset;

package/dist/index.js

@@ -0,0 +1,53 @@
+// @txco/react-router: a React Router preset that writes a Web ABI build for
+// Thanks, Computer (txco) after `react-router build`:
+//
+//   txco-web/
+//     txco-web.json   the manifest
+//     public/         a copy of build/client
+//     ops/            the route-aware SPA fallback and the catch-all
+//
+//   // react-router.config.ts
+//   import type { Config } from "@react-router/dev/config";
+//   import txco from "@txco/react-router";
+//   export default { ssr: false, presets: [txco()] } satisfies Config;
+//
+// `txco apply` installs it into the stack txco.yaml binds it to.
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { checkOutDir } from "@txco/web-abi/producer";
+import { NAME, writeBuild } from "./build.js";
+export { routeRegex, routesMatcher } from "./routes.js";
+export default function txco(options = {}) {
+    return {
+        name: NAME,
+        // Fail before a long build: the preset wipes and rewrites `out`.
+        async reactRouterConfigResolved({ reactRouterConfig }) {
+            const root = process.cwd();
+            const out = resolve(root, options.out ?? "txco-web");
+            const build = resolve(root, reactRouterConfig.buildDirectory);
+            const problems = checkOutDir({
+                dir: out,
+                protect: [root, build],
+                notInside: [build],
+                entries: await readdir(out).catch(() => null),
+            });
+            if (problems.length > 0)
+                throw new Error(`[txco] ${problems.join("\n")}`);
+        },
+        reactRouterConfig: () => ({
+            async buildEnd({ buildManifest, reactRouterConfig, viteConfig }) {
+                await writeBuild({
+                    root: viteConfig.root,
+                    buildDirectory: reactRouterConfig.buildDirectory,
+                    base: viteConfig.base,
+                    assetsDir: viteConfig.build.assetsDir,
+                    basename: reactRouterConfig.basename,
+                    ssr: reactRouterConfig.ssr,
+                    routes: buildManifest?.routes ?? reactRouterConfig.routes,
+                    options,
+                    log: viteConfig.logger,
+                });
+            },
+        }),
+    };
+}

package/dist/routes.d.ts

@@ -0,0 +1,26 @@
+/** One entry of React Router's flat RouteManifest. */
+export interface RouteEntry {
+    id: string;
+    parentId?: string;
+    path?: string;
+    index?: boolean;
+    caseSensitive?: boolean;
+}
+export type RouteManifest = Record<string, RouteEntry>;
+/** Every route's full path pattern (joined up its parentId chain), deduped. */
+export declare function routePaths(routes: RouteManifest): {
+    path: string;
+    caseSensitive: boolean;
+}[];
+/**
+ * One route path as a regex source matching a request path (leading "/",
+ * an optional trailing "/"). React Router's syntax: `:param`, `:param?`,
+ * a static `segment?`, and a final `*`. null for anything else.
+ */
+export declare function routeRegex(path: string, caseSensitive?: boolean): string | null;
+/**
+ * The anchored matcher for every route, under `basename`, with "/" escaped
+ * for txcl's /…/ literal. null when a route can't be translated (the caller
+ * then answers every navigation with the shell and 200).
+ */
+export declare function routesMatcher(routes: RouteManifest, basename?: string): string | null;

package/dist/routes.js

@@ -0,0 +1,75 @@
+// React Router's route table as one RE2 matcher, for the route-aware SPA
+// fallback: a navigation to a path a route knows gets the shell with 200,
+// any other the shell with 404. Pure, so it's unit-tested.
+/** Every route's full path pattern (joined up its parentId chain), deduped. */
+export function routePaths(routes) {
+    const seen = new Map();
+    for (const r of Object.values(routes)) {
+        const parts = [];
+        let caseSensitive = false;
+        for (let cur = r, n = 0; cur && n < 100; cur = cur.parentId ? routes[cur.parentId] : undefined, n++) {
+            if (cur.path)
+                parts.unshift(cur.path.replace(/^\/+|\/+$/g, ""));
+            if (cur.caseSensitive)
+                caseSensitive = true;
+        }
+        const path = parts.filter(Boolean).join("/");
+        seen.set(path, (seen.get(path) ?? false) || caseSensitive);
+    }
+    return [...seen].map(([path, caseSensitive]) => ({ path, caseSensitive })).sort((a, b) => a.path.localeCompare(b.path));
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * One route path as a regex source matching a request path (leading "/",
+ * an optional trailing "/"). React Router's syntax: `:param`, `:param?`,
+ * a static `segment?`, and a final `*`. null for anything else.
+ */
+export function routeRegex(path, caseSensitive = false) {
+    const segs = path.split("/").filter(Boolean);
+    let re = "";
+    for (let i = 0; i < segs.length; i++) {
+        const seg = segs[i];
+        if (seg === "*") {
+            if (i !== segs.length - 1)
+                return null;
+            re += "(?:/.*)?";
+        }
+        else if (/^:[A-Za-z0-9_-]+\?$/.test(seg)) {
+            re += "(?:/[^/]+)?";
+        }
+        else if (/^:[A-Za-z0-9_-]+$/.test(seg)) {
+            re += "/[^/]+";
+        }
+        else if (seg.includes(":") || seg.includes("*")) {
+            return null; // a param or splat inside a segment: not React Router syntax
+        }
+        else if (seg.endsWith("?")) {
+            re += `(?:/${escapeRe(seg.slice(0, -1))})?`;
+        }
+        else {
+            re += `/${escapeRe(seg)}`;
+        }
+    }
+    re += "/?";
+    return caseSensitive ? re : `(?i:${re})`;
+}
+/**
+ * The anchored matcher for every route, under `basename`, with "/" escaped
+ * for txcl's /…/ literal. null when a route can't be translated (the caller
+ * then answers every navigation with the shell and 200).
+ */
+export function routesMatcher(routes, basename = "/") {
+    // React Router matches basename case-insensitively (stripBasename).
+    const base = basename.replace(/^\/+|\/+$/g, "");
+    const prefix = base ? `(?i:/${escapeRe(base)})` : "";
+    const alts = [];
+    for (const { path, caseSensitive } of routePaths(routes)) {
+        const re = routeRegex(path, caseSensitive);
+        if (re === null)
+            return null;
+        alts.push(prefix + re);
+    }
+    if (alts.length === 0)
+        return null;
+    return `^(?:${alts.join("|")})$`.replace(/\//g, "\\/");
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@txco/react-router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React Router preset for Thanks, Computer (txco): after `react-router build`, writes a Web ABI build — build/client as public/, a route-aware SPA fallback as ops/, and txco-web.json — for `txco apply` to install.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": [
+    "react-router",
+    "react-router-preset",
+    "remix",
+    "spa",
+    "txco",
+    "thanks-computer",
+    "web-abi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoremLabs/thanks-computer.git",
+    "directory": "sdk/react-router"
+  },
+  "homepage": "https://github.com/LoremLabs/thanks-computer/tree/master/sdk/react-router#readme",
+  "bugs": "https://github.com/LoremLabs/thanks-computer/issues",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@txco/web-abi": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@react-router/dev": "^7.0.0 || ^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/build.ts

@@ -0,0 +1,136 @@
+// Writes the Web ABI build from React Router's finished output. Called from
+// the preset's buildEnd; takes plain inputs, so it's tested without a build.
+import { readFile, rm, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+
+import {
+  copyPublic,
+  listFiles,
+  looksHashed,
+  publicPrefix,
+  renderOps,
+  writeManifest,
+  writeOps,
+  type NavMode,
+} from "@txco/web-abi/producer";
+
+import { routesMatcher, type RouteManifest } from "./routes.js";
+
+export const NAME = "@txco/react-router";
+export const VERSION = "0.1.0";
+/** An op answer is capped at 4 MiB (--op-payload-max), base64 included. */
+const PAGE_WARN_BYTES = 1 << 20;
+
+export interface TxcoOptions {
+  /** The Web ABI directory to write, relative to the project root. Default "txco-web". */
+  out?: string;
+  /**
+   * Give an unknown page path the shell with 404, from the route table.
+   * false answers every page path with the shell and 200. Default true.
+   */
+  routeAware?: boolean;
+  /** The public/ prefixes cached for a year. Default: Vite's assetsDir (`assets/`). */
+  immutable?: string[];
+  /** The navigation op's scope; the catch-all goes 900 above it. Default 900000. */
+  scope?: number;
+}
+
+export interface BuildInput {
+  /** The project root (Vite's root). */
+  root: string;
+  /** reactRouterConfig.buildDirectory: client output is <it>/client. */
+  buildDirectory: string;
+  /** Vite's base (where the assets are served). */
+  base: string;
+  /** Vite's build.assetsDir. */
+  assetsDir: string;
+  /** reactRouterConfig.basename (where the routes are). */
+  basename: string;
+  /** reactRouterConfig.ssr. */
+  ssr: boolean;
+  routes: RouteManifest;
+  options: TxcoOptions;
+  log: { info(msg: string): void; warn(msg: string): void };
+}
+
+export interface BuildResult {
+  mode: NavMode;
+  ops: string[];
+  manifest: Record<string, unknown>;
+}
+
+const exists = (p: string) => stat(p).then(() => true, () => false);
+
+export async function writeBuild(i: BuildInput): Promise<BuildResult> {
+  const warn = (msg: string) => i.log.warn(`[txco] ${msg}`);
+  const clientDir = resolve(i.root, i.buildDirectory, "client");
+  if (!(await exists(clientDir))) throw new Error(`[txco] React Router's client build isn't at ${clientDir}`);
+  const out = resolve(i.root, i.options.out ?? "txco-web");
+  const { prefix, external } = publicPrefix(i.base);
+  if (external) warn(`base is ${i.base}: the assets load from there, and the pages are deployed at the root`);
+
+  await rm(out, { recursive: true, force: true });
+  const { skipped } = await copyPublic(clientDir, out, prefix);
+  if (skipped.length > 0) warn(`build/client has ${skipped.length} dot path(s) (${skipped.slice(0, 3).join(", ")}); they never deploy`);
+
+  const readPage = async (name: string) => {
+    const html = await readFile(join(clientDir, name), "utf8").catch(() => null);
+    return html === null ? null : { name, html };
+  };
+
+  let mode: NavMode;
+  let page = null;
+  let routes: string | undefined;
+  const notes: string[] = [];
+  if (i.ssr) {
+    // No chassis runs a server yet: deploy what was prerendered.
+    warn("ssr: true needs a server, and no chassis runs one yet: only the prerendered pages deploy. For an SPA, set ssr: false.");
+    mode = "404";
+    notes.push("A server-rendered React Router app: only its prerendered pages deploy until a runner exists.");
+  } else {
+    // In SPA mode the shell is __spa-fallback.html when "/" is prerendered.
+    page = (await readPage("__spa-fallback.html")) ?? (await readPage("index.html"));
+    if (!page) throw new Error(`[txco] an ssr: false build needs its shell (index.html or __spa-fallback.html) in ${clientDir}`);
+    const matcher = i.options.routeAware === false ? null : routesMatcher(i.routes, i.basename);
+    if (matcher) {
+      mode = "routes";
+      routes = matcher;
+      notes.push("The route set comes from React Router's route table.");
+    } else {
+      mode = "spa";
+      if (i.options.routeAware !== false) notes.push("A route couldn't be expressed as a matcher, so unknown pages get 200 too.");
+    }
+  }
+  if (page && Buffer.byteLength(page.html) > PAGE_WARN_BYTES) {
+    warn(`${page.name} is ${Buffer.byteLength(page.html)} bytes; the op that serves it is capped at 4 MiB, base64 included`);
+  }
+
+  const ops = renderOps({ mode, scope: i.options.scope, producer: NAME, page, routes, notes });
+  await writeOps(out, ops);
+
+  const files = await listFiles(join(out, "public"));
+  const assets = i.assetsDir.replace(/^\/+|\/+$/g, "");
+  const immutable =
+    i.options.immutable ?? (assets && files.some((f) => f.startsWith(`${prefix}${assets}/`)) ? [`${prefix}${assets}/`] : []);
+  for (const p of immutable) {
+    const unhashed = files.filter((f) => f.startsWith(p) && !looksHashed(f.split("/").pop()!));
+    if (unhashed.length > 0) {
+      warn(`${unhashed.length} file(s) under the immutable prefix ${p} carry no content hash (${unhashed.slice(0, 3).join(", ")}), so a change to them wouldn't reach a browser for a year`);
+    }
+  }
+
+  const manifest: Record<string, unknown> = {
+    abi: 1,
+    ...(immutable.length > 0 ? { immutable } : {}),
+    "x-producer": { name: NAME, version: VERSION },
+    "x-react-router": { ssr: i.ssr, mode, routes: Object.keys(i.routes).length },
+  };
+  await writeManifest(out, manifest);
+
+  const shown = relative(process.cwd(), out) || ".";
+  i.log.info(
+    `[txco] Web ABI build (${mode}) at ${shown}: ${files.length} public file(s), ${Object.keys(ops).length} op(s). ` +
+      `Next: \`txco web check ${shown}\`, bind it in txco.yaml (stacks: <name>: abi: ${shown}), then \`txco apply\`.`,
+  );
+  return { mode, ops: Object.keys(ops).sort(), manifest };
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+// @txco/react-router: a React Router preset that writes a Web ABI build for
+// Thanks, Computer (txco) after `react-router build`:
+//
+//   txco-web/
+//     txco-web.json   the manifest
+//     public/         a copy of build/client
+//     ops/            the route-aware SPA fallback and the catch-all
+//
+//   // react-router.config.ts
+//   import type { Config } from "@react-router/dev/config";
+//   import txco from "@txco/react-router";
+//   export default { ssr: false, presets: [txco()] } satisfies Config;
+//
+// `txco apply` installs it into the stack txco.yaml binds it to.
+import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
+
+import { checkOutDir } from "@txco/web-abi/producer";
+
+import { NAME, writeBuild, type TxcoOptions } from "./build.js";
+import type { RouteManifest } from "./routes.js";
+
+export type { TxcoOptions } from "./build.js";
+export { routeRegex, routesMatcher } from "./routes.js";
+
+// The parts of React Router's types the preset reads, declared here so the
+// package needs no React Router at build time. They match @react-router/dev's
+// Preset and BuildEndHook (v7 and v8).
+interface ResolvedConfig {
+  buildDirectory: string;
+  basename: string;
+  ssr: boolean;
+  routes: RouteManifest;
+}
+interface BuildEndArgs {
+  buildManifest?: { routes: RouteManifest };
+  reactRouterConfig: ResolvedConfig;
+  viteConfig: {
+    root: string;
+    base: string;
+    build: { assetsDir: string };
+    logger: { info(msg: string): void; warn(msg: string): void };
+  };
+}
+export interface Preset {
+  name: string;
+  reactRouterConfig?: (args: { reactRouterUserConfig: unknown }) => { buildEnd: (args: BuildEndArgs) => Promise<void> };
+  reactRouterConfigResolved?: (args: { reactRouterConfig: ResolvedConfig }) => Promise<void>;
+}
+
+export default function txco(options: TxcoOptions = {}): Preset {
+  return {
+    name: NAME,
+
+    // Fail before a long build: the preset wipes and rewrites `out`.
+    async reactRouterConfigResolved({ reactRouterConfig }) {
+      const root = process.cwd();
+      const out = resolve(root, options.out ?? "txco-web");
+      const build = resolve(root, reactRouterConfig.buildDirectory);
+      const problems = checkOutDir({
+        dir: out,
+        protect: [root, build],
+        notInside: [build],
+        entries: await readdir(out).catch(() => null),
+      });
+      if (problems.length > 0) throw new Error(`[txco] ${problems.join("\n")}`);
+    },
+
+    reactRouterConfig: () => ({
+      async buildEnd({ buildManifest, reactRouterConfig, viteConfig }) {
+        await writeBuild({
+          root: viteConfig.root,
+          buildDirectory: reactRouterConfig.buildDirectory,
+          base: viteConfig.base,
+          assetsDir: viteConfig.build.assetsDir,
+          basename: reactRouterConfig.basename,
+          ssr: reactRouterConfig.ssr,
+          routes: buildManifest?.routes ?? reactRouterConfig.routes,
+          options,
+          log: viteConfig.logger,
+        });
+      },
+    }),
+  };
+}

package/src/routes.ts

@@ -0,0 +1,80 @@
+// React Router's route table as one RE2 matcher, for the route-aware SPA
+// fallback: a navigation to a path a route knows gets the shell with 200,
+// any other the shell with 404. Pure, so it's unit-tested.
+
+/** One entry of React Router's flat RouteManifest. */
+export interface RouteEntry {
+  id: string;
+  parentId?: string;
+  path?: string;
+  index?: boolean;
+  caseSensitive?: boolean;
+}
+
+export type RouteManifest = Record<string, RouteEntry>;
+
+/** Every route's full path pattern (joined up its parentId chain), deduped. */
+export function routePaths(routes: RouteManifest): { path: string; caseSensitive: boolean }[] {
+  const seen = new Map<string, boolean>();
+  for (const r of Object.values(routes)) {
+    const parts: string[] = [];
+    let caseSensitive = false;
+    for (let cur: RouteEntry | undefined = r, n = 0; cur && n < 100; cur = cur.parentId ? routes[cur.parentId] : undefined, n++) {
+      if (cur.path) parts.unshift(cur.path.replace(/^\/+|\/+$/g, ""));
+      if (cur.caseSensitive) caseSensitive = true;
+    }
+    const path = parts.filter(Boolean).join("/");
+    seen.set(path, (seen.get(path) ?? false) || caseSensitive);
+  }
+  return [...seen].map(([path, caseSensitive]) => ({ path, caseSensitive })).sort((a, b) => a.path.localeCompare(b.path));
+}
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * One route path as a regex source matching a request path (leading "/",
+ * an optional trailing "/"). React Router's syntax: `:param`, `:param?`,
+ * a static `segment?`, and a final `*`. null for anything else.
+ */
+export function routeRegex(path: string, caseSensitive = false): string | null {
+  const segs = path.split("/").filter(Boolean);
+  let re = "";
+  for (let i = 0; i < segs.length; i++) {
+    const seg = segs[i];
+    if (seg === "*") {
+      if (i !== segs.length - 1) return null;
+      re += "(?:/.*)?";
+    } else if (/^:[A-Za-z0-9_-]+\?$/.test(seg)) {
+      re += "(?:/[^/]+)?";
+    } else if (/^:[A-Za-z0-9_-]+$/.test(seg)) {
+      re += "/[^/]+";
+    } else if (seg.includes(":") || seg.includes("*")) {
+      return null; // a param or splat inside a segment: not React Router syntax
+    } else if (seg.endsWith("?")) {
+      re += `(?:/${escapeRe(seg.slice(0, -1))})?`;
+    } else {
+      re += `/${escapeRe(seg)}`;
+    }
+  }
+  re += "/?";
+  return caseSensitive ? re : `(?i:${re})`;
+}
+
+/**
+ * The anchored matcher for every route, under `basename`, with "/" escaped
+ * for txcl's /…/ literal. null when a route can't be translated (the caller
+ * then answers every navigation with the shell and 200).
+ */
+export function routesMatcher(routes: RouteManifest, basename = "/"): string | null {
+  // React Router matches basename case-insensitively (stripBasename).
+  const base = basename.replace(/^\/+|\/+$/g, "");
+  const prefix = base ? `(?i:/${escapeRe(base)})` : "";
+  const alts: string[] = [];
+  for (const { path, caseSensitive } of routePaths(routes)) {
+    const re = routeRegex(path, caseSensitive);
+    if (re === null) return null;
+    alts.push(prefix + re);
+  }
+  if (alts.length === 0) return null;
+  return `^(?:${alts.join("|")})$`.replace(/\//g, "\\/");
+}