🏗️ Engineering Spec: SSG Integration Protocol

Objective: Upgrade the architecture from SPA (Single Page App) to SSG (Static Site Generation) using @wroud/vite-plugin-ssg. Goal: Achieve "Antigravity" performance (Zero JS First Paint) and perfect SEO structure for AI crawlers (GEO).

1. Architecture Analysis (Current vs. Target)

Feature	Current (SPA)	Target (SSG)
Build Output	One generic `index.html` + JS bundle.	Individual `index.html` for every route (e.g., `/blog/intro/index.html`).
Routing	`BrowserHistory` (Prod) / `HashHistory` (Sandbox).	`MemoryHistory` (Build-time) -> `BrowserHistory` (Hydration).
SEO Mechanism	Client-side Helmet (Googlebot executes JS).	Pre-rendered HTML tags (Title, Meta, Content) visible instantly.
Data Source	`useDocsDB` hydrates at runtime.	Node.js build process pre-fills HTML with registry data.

2. The Implementation Roadmap

To integrate SSG without breaking the AI Studio sandbox compatibility, we must perform a "Surgical Separation" of the entry points.

Phase A: The Entry Split

The current src/main.tsx handles both router creation and DOM mounting. This must be decoupled.

src/router.tsx (Shared Factory)
- Role: Exports a createRouter() function.
- Logic: Accepts a history instance as an argument. This allows the server to inject MemoryHistory and the client to inject BrowserHistory.
src/entry-client.tsx (Browser)
- Role: Replaces main.tsx for the browser.
- Change: Switches from ReactDOM.createRoot to ReactDOM.hydrateRoot. This is critical for React to "attach" to the pre-rendered HTML without flickering.
src/entry-server.tsx (Node/Build)
- Role: The rendering engine for the SSG plugin.
- Logic:
  - Exports a render(url) function.
  - Creates a router with MemoryHistory pointing to the url.
  - Waits for router.load().
  - Uses ReactDOMServer.renderToString to generate the HTML.
  - Extracts Helmet context to inject <head> tags.

Phase B: Route Discovery (The "Crawler" Script)

The SSG plugin needs to know which paths to generate. We do not need a crawler; we have the Registry.

Strategy: Create a function getRoutes() in vite.config.ts.
Logic: Import registry-docs.ts and registry-blog.ts. Map over the arrays to generate a list of strings: ['/', '/en', '/zh', '/en/docs/core/plan', ...].

Phase C: Data Hydration

Challenge: The server renders data from the registry. The client needs that same data to hydrate.
Solution: Since our "Database" is a static TypeScript file (src/mocks/content/index.ts), ensuring both Client and Server bundles include this file is sufficient. We do not need complex JSON serialization for the static content.

3. Risk Mitigation (Sandbox Compatibility)

SSG is a Build-Time process. It relies on Node.js APIs that do not exist in the AI Studio browser environment.

Protocol:
- vite dev: Must remain in SPA Mode. The index.html should point to entry-client.tsx (or main.tsx as dev entry).
- vite build: Activates the SSG plugin.
Guardrails: Use if (import.meta.env.SSR) checks to prevent browser-only code (like accessing window directly in the global scope) from crashing the build.

Status: Completed & Active. SSG Pipeline Established.

SSG Integration Plan