fix(docs): serialize prerender so large pages aren't truncated (#44)

The SPA prerender defaults to os.cpus().length concurrency. Several routes
race through the in-process render server at once, and under that load a large
response body stream is cut at the first ~64KiB chunk before res.text() drains
it. Any page over 64KiB (e.g. /islands/charts, /reference/manifest) is then
written truncated, losing its trailing hydration <script> and shipping as dead,
non-interactive HTML. Which page loses the race varies per build and worsens on
high-core CD runners, so it slipped past local builds into production.

Set prerender.concurrency to 1 to remove the race, and add a postbuild guard
that fails the build if any prerendered page is missing its closing </html>.

Author: lukaisailovic

apps/docs/scripts/postbuild.mjs

@@ -2,7 +2,7 @@
 // static-asset serving expects `index.html` both for `/` and as the single-page-app
 // fallback (`not_found_handling: "single-page-application"`). Materialize the shell as
 // index.html so the home route and client-side navigation both resolve on Workers.
-import { copyFileSync, existsSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -54,7 +54,19 @@ function toLocation(indexHtmlPath) {
   return `${SITE_ORIGIN}/${route}`;
 }
 
-const locations = findIndexHtmlPaths(publicDir).map(toLocation).toSorted();
+const indexHtmlPaths = findIndexHtmlPaths(publicDir);
+
+// Guard against silently truncated prerenders: a complete page ends with `</html>`, and the
+// hydration-bootstrap <script> sits just before it, so this one check proves the page (and
+// its ability to hydrate) shipped whole. Fail the build rather than deploy dead HTML.
+const truncated = indexHtmlPaths.filter((p) => !readFileSync(p, "utf8").trimEnd().endsWith("</html>"));
+if (truncated.length > 0) {
+  console.error(`postbuild: ${truncated.length} prerendered page(s) are truncated (missing </html>):`);
+  for (const p of truncated) console.error(`  ✘ ${relative(publicDir, p)}`);
+  process.exit(1);
+}
+
+const locations = indexHtmlPaths.map(toLocation).toSorted();
 const urls = locations.map((loc) => `  <url><loc>${loc}</loc></url>`).join("\n");
 const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">

apps/docs/vite.config.ts

@@ -47,6 +47,13 @@ export default defineConfig({
           crawlLinks: true,
         },
       },
+      // Prerender each route one at a time. The default concurrency (os.cpus().length)
+      // races several routes through the in-process render server at once, and under that
+      // load a large response's body stream gets cut at the first ~64KiB chunk before
+      // `res.text()` drains it — so a >64KiB page (e.g. islands/charts) is silently written
+      // truncated, losing its trailing hydration <script> and shipping as dead HTML. Which
+      // page loses the race varies per build. Serial prerender removes the race.
+      prerender: { concurrency: 1 },
       pages: [
         { path: "/" },
         ...docPaths.map((path) => ({ path })),