website: prerender to static HTML for no-JS crawlers/agents

DECISIONS.md

@@ -160,6 +160,28 @@ for this reason (2026-08-26), which also required an org-level `members_can_crea
 to be enabled - a broader-scoped, org-wide change that was called out and confirmed separately
 before touching it, since it wasn't implied by "make this one repo public."
 
+**The website prerenders to static HTML at build time, not just client-side React.** Before this,
+`dist/index.html` shipped an empty `<div id="root">` - fine for a browser, but a no-JS crawler
+(and some AI agents fetching the page) got nothing. Next.js was considered instead of fixing this
+in Vite, since SSR is its headline feature - but `release-website.yml` deploys to GitHub Pages,
+which only serves static files with no Node process behind it. Next's SSR/ISR/server-actions
+advantages need a server to run on, so on Pages it would run in `output: 'export'` (fully static)
+mode anyway - the same static-HTML output Vite already produces, just with the App Router's
+routing/data-fetching machinery for a site that has exactly one page and no `react-router`. That
+would have been a full framework migration for a capability Vite can add directly.
+
+The fix: `vite.ssr.config.ts` builds `src/entry-server.tsx` (a `renderToString(<App/>)` wrapper) to
+`dist-ssr/`, and `scripts/prerender.mjs` inlines that HTML into `dist/index.html`'s `#root`, then
+deletes `dist-ssr/` - it's a build-time intermediate, not a deploy artifact. `src/main.tsx` now
+hydrates when `#root` already has children (a real build/preview load) and falls back to a normal
+`createRoot().render()` when it's empty (`vite dev`, which serves `index.html` unprerendered).
+`vite.ssr.config.ts` only carries the `react()` plugin, not `virtualConsoleVitePlugin` or
+`tailwindcss()` - the console plugin unconditionally emits its own client chunk on `command ===
+'build'`, which breaks when pointed at a non-HTML SSR entry, and neither plugin's output (injected
+`<script>`/`<style>` tags, compiled CSS) is used by a build whose only output is an HTML string.
+`release-website.yml` needed no changes - `pnpm run build` still ends with static files in
+`website/dist`, just with real markup already in them.
+
 ## Where to find the rest
 
 - [README.md](README.md) - installation, configuration, and the `replEnabled: false` escape hatch

website/package.json

@@ -1,14 +1,14 @@
 {
     "name": "virtual-console-website",
     "private": true,
-    "version": "0.1.3",
+    "version": "0.1.4-alpha.0",
     "type": "module",
     "scripts": {
         "dev": "vite",
-        "build": "tsc -b && vite build",
+        "build": "tsc -b && vite build && vite build --config vite.ssr.config.ts --ssr src/entry-server.tsx --outDir dist-ssr && node scripts/prerender.mjs",
         "preview": "vite preview",
         "typecheck": "tsc -b --noEmit",
-        "clean": "rm -rf dist .vite"
+        "clean": "rm -rf dist dist-ssr .vite"
     },
     "dependencies": {
         "@codehacks/virtual-console": "0.7.9-alpha.0",

website/scripts/prerender.mjs

@@ -0,0 +1,24 @@
+// Runs after the client and SSR builds: renders the app to an HTML string
+// and inlines it into dist/index.html's #root, so the page has real content
+// before any JS runs (crawlers, AI agents, no-JS clients). See DECISIONS.md.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const websiteDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const distDir = path.join(websiteDir, 'dist');
+const ssrDir = path.join(websiteDir, 'dist-ssr');
+
+const { render } = await import(path.join(ssrDir, 'entry-server.js'));
+const appHtml = render();
+
+const indexPath = path.join(distDir, 'index.html');
+const template = fs.readFileSync(indexPath, 'utf-8');
+const withMarkup = template.replace('<div id="root"></div>', `<div id="root">${appHtml}</div>`);
+
+if (withMarkup === template) {
+    throw new Error(`prerender: did not find '<div id="root"></div>' placeholder in ${indexPath}`);
+}
+
+fs.writeFileSync(indexPath, withMarkup);
+fs.rmSync(ssrDir, { recursive: true, force: true });

website/src/entry-server.tsx

@@ -0,0 +1,6 @@
+import { renderToString } from 'react-dom/server';
+import App from './App';
+
+export function render(): string {
+    return renderToString(<App />);
+}

website/src/main.tsx

@@ -3,8 +3,19 @@ import ReactDOM from 'react-dom/client';
 import App from './App';
 import './index.css';
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
+const rootEl = document.getElementById('root')!;
+const app = (
     <React.StrictMode>
         <App />
     </React.StrictMode>
 );
+
+// The build's prerender step (see scripts/prerender.mjs) fills #root with
+// real markup, so a production/preview load must hydrate it rather than
+// throw it away and render from scratch. In dev, index.html is served as-is
+// (no prerender step runs), so #root starts empty and needs a normal render.
+if (rootEl.hasChildNodes()) {
+    ReactDOM.hydrateRoot(rootEl, app);
+} else {
+    ReactDOM.createRoot(rootEl).render(app);
+}

website/vite.ssr.config.ts

@@ -0,0 +1,12 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+// Separate from vite.config.ts because virtualConsoleVitePlugin only makes
+// sense for the client build (it injects a script/style into index.html and
+// emits its own client chunk) - pointing --ssr at that config makes Vite
+// try to bundle its virtual client module as an entry, which fails. This
+// build's only output is entry-server.tsx's renderToString, so it needs
+// nothing but the JSX transform. See scripts/prerender.mjs.
+export default defineConfig({
+    plugins: [react()]
+});