From e71a2d43f4c2e5240f7862bc3cee2d5720669460 Mon Sep 17 00:00:00 2001
From: okcodes <80954089+okcodes@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:42:30 -0600
Subject: [PATCH 1/2] website: prerender to static HTML so no-JS clients get
 real content

Renders the app to a string at build time via a separate SSR entry and
inlines it into dist/index.html's #root, instead of shipping an empty
div for client-side React to fill in. Lets crawlers and AI agents that
don't execute JS see the actual page content. Chose this over migrating
to Next.js since the site deploys to GitHub Pages (static hosting only),
where Next's SSR/ISR advantages aren't available anyway. See
DECISIONS.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 DECISIONS.md                  | 22 ++++++++++++++++++++++
 website/package.json          |  4 ++--
 website/scripts/prerender.mjs | 24 ++++++++++++++++++++++++
 website/src/entry-server.tsx  |  6 ++++++
 website/src/main.tsx          | 13 ++++++++++++-
 website/vite.ssr.config.ts    | 12 ++++++++++++
 6 files changed, 78 insertions(+), 3 deletions(-)
 create mode 100644 website/scripts/prerender.mjs
 create mode 100644 website/src/entry-server.tsx
 create mode 100644 website/vite.ssr.config.ts

diff --git a/DECISIONS.md b/DECISIONS.md
index bffeca9..58b7f67 100644
--- a/DECISIONS.md
+++ b/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
diff --git a/website/package.json b/website/package.json
index 2e6e42c..420751e 100644
--- a/website/package.json
+++ b/website/package.json
@@ -5,10 +5,10 @@
     "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",
diff --git a/website/scripts/prerender.mjs b/website/scripts/prerender.mjs
new file mode 100644
index 0000000..2dcedec
--- /dev/null
+++ b/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 });
diff --git a/website/src/entry-server.tsx b/website/src/entry-server.tsx
new file mode 100644
index 0000000..6d5a412
--- /dev/null
+++ b/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 />);
+}
diff --git a/website/src/main.tsx b/website/src/main.tsx
index 9dbd147..5643d76 100644
--- a/website/src/main.tsx
+++ b/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);
+}
diff --git a/website/vite.ssr.config.ts b/website/vite.ssr.config.ts
new file mode 100644
index 0000000..badf054
--- /dev/null
+++ b/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()]
+});

From 242ea51915f70ea8414600cd3555cb358279866b Mon Sep 17 00:00:00 2001
From: okcodes <80954089+okcodes@users.noreply.github.com>
Date: Sun, 6 Sep 2026 06:48:46 -0600
Subject: [PATCH 2/2] bump website to v0.1.4-alpha.0

---
 website/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/package.json b/website/package.json
index 420751e..d9c3f4e 100644
--- a/website/package.json
+++ b/website/package.json
@@ -1,7 +1,7 @@
 {
     "name": "virtual-console-website",
     "private": true,
-    "version": "0.1.3",
+    "version": "0.1.4-alpha.0",
     "type": "module",
     "scripts": {
         "dev": "vite",