Serve SPA routes as HTTP 200 on Cloudflare Pages

www/README.md

@@ -46,9 +46,12 @@ playground without a Rust toolchain.
 
 Content routes (Documents, Packages, Spec, Install, First program, Book, and
 the rest of the docs tree) are written as `dist/<path>/index.html` so those
-URLs are real pages. Unknown paths still use the `public/404.html` → `/?/path`
-bounce and `index.html` restore script. Custom domain: `public/CNAME` →
-`xo.run`. Wasm bindings stay in `public/echo-wasm/`.
+URLs are real pages. Unknown paths use `public/_redirects`
+(`/* /index.html 200`) so they are a rewrite, not HTTP 404. Crawlers and
+`curl` see 200. Existing static files still win. `public/404.html` remains
+the older browser bounce for hosts that still fall back to a 404 page;
+`index.html` restores `?/` paths from that bounce. Custom domain:
+`public/CNAME` → `xo.run`. Wasm bindings stay in `public/echo-wasm/`.
 
 `/robots.txt` is a static file. `/sitemap.xml` is emitted at build from the
 public catalog (`staticPages` and site chrome). Both use `https://xo.run`.

www/package.json

@@ -10,12 +10,13 @@
     "format": "oxfmt --check .",
     "lint": "oxlint . --ignore-pattern public/echo-wasm",
     "preview": "vite preview",
-    "test": "npm run test:docs && npm run test:prose && npm run test:std-ref && npm run test:try && npm run test:sitemap",
+    "test": "npm run test:docs && npm run test:prose && npm run test:std-ref && npm run test:try && npm run test:sitemap && npm run test:spa-redirects",
     "test:docs": "node scripts/verify-docs-pages.mjs",
     "test:std-ref": "node scripts/verify-std-reference.mjs",
     "test:prose": "node scripts/verify-prose.mjs",
     "test:try": "node scripts/verify-try.mjs",
     "test:sitemap": "node scripts/verify-sitemap.mjs",
+    "test:spa-redirects": "node scripts/verify-spa-redirects.mjs",
     "sync:tree-sitter": "node scripts/sync-tree-sitter.mjs",
     "postinstall": "npm run sync:tree-sitter"
   },

www/public/_redirects

@@ -0,0 +1,4 @@
+# SPA routes: rewrite unknown paths to the app shell with HTTP 200.
+# Existing static files still win. Without this, Cloudflare Pages serves
+# 404.html (browsers recover; crawlers and curl see HTTP 404).
+/*    /index.html   200

www/scripts/verify-spa-redirects.mjs

@@ -0,0 +1,39 @@
+/**
+ * Verifies Cloudflare Pages serves SPA routes as HTTP 200:
+ * - public/_redirects rewrites /* to /index.html with status 200
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const redirectsPath = path.join(root, "public", "_redirects");
+const source = readFileSync(redirectsPath, "utf8");
+
+const failures = [];
+
+function fail(message) {
+  failures.push(message);
+}
+
+const rewrite = source
+  .split("\n")
+  .map((line) => line.trim())
+  .filter((line) => line && !line.startsWith("#"))
+  .find((line) => {
+    const parts = line.split(/\s+/);
+    return parts[0] === "/*" && parts[1] === "/index.html" && parts[2] === "200";
+  });
+
+if (!rewrite) {
+  fail("public/_redirects must rewrite /* to /index.html with status 200");
+}
+
+if (failures.length > 0) {
+  for (const failure of failures) {
+    console.error(failure);
+  }
+  process.exit(1);
+}
+
+console.log("verify-spa-redirects: ok");