perf(dashboard): lazy-load secondary marketing pages to shrink main bundle (#27)

PR #19 already split /app/* routes out of the entry chunk, but the
remaining public marketing pages were still eagerly imported in App.tsx
on the theory that "a homepage visitor might click any of them." In
practice, BlogPostPage / DocsPage / UseCaseDetailPage etc. are only
reachable after at least one click, so paying for their bytes on cold
load is wasted weight on the most-visited path.

This commit converts the secondary public pages to React.lazy() and
relies on Rollup's per-import code-splitting to peel them into their
own chunks. The first-paint JS that a homepage visitor downloads is
now meaningfully smaller; chunks for /pricing, /docs, /blog, /status,
/use-cases, /for-agents are fetched on demand when the visitor clicks
into those routes.

Bundle sizes (vite build), main entry + each new chunk:

| File                                | Before          | After           |
|-------------------------------------|-----------------|-----------------|
| index-*.js (main entry)             | 710.87 / 194.51 | 616.57 / 168.76 |
| PricingPage chunk                   | (in main)       |  14.43 /  3.87  |
| ForAgentsPage chunk                 | (in main)       |  11.43 /  3.53  |
| StatusPage chunk                    | (in main)       |   8.67 /  2.73  |
| BlogPage chunk                      | (in main)       |   2.22 /  0.97  |
| BlogPostPage chunk                  | (in main)       |   3.06 /  1.14  |
| DocsPage chunk                      | (in main)       |  10.48 /  4.49  |
| UseCasesPage chunk                  | (in main)       |   5.07 /  1.88  |
| UseCaseDetailPage chunk             | (in main)       |   9.63 /  2.90  |
| PublicShell chunk (extracted)       | (in main)       |   9.02 /  2.32  |
| posts content chunk                 | (in main)       |  22.68 /  9.95  |
| markdown renderer chunk             | (in main)       |   1.98 /  0.84  |

(All sizes in kB; pair is raw / gzip. Vite's 500 kB chunk-size warning
still fires on the main entry — most of the remaining bytes are react +
react-dom + react-router + MarketingPage's inlined USE_CASES dataset.
That's tracked separately.)

Net delta on cold load:
  raw:  710.87 → 616.57 kB  (-94.30 kB, -13.3%)
  gzip: 194.51 → 168.76 kB  (-25.75 kB, -13.2%)

SSG complication and how it's handled:

scripts/prerender.mjs renders public routes through renderToString at
build time so crawlers see real HTML, not an empty <div id="root">.
React.lazy() during renderToString resolves to the parent Suspense
fallback, NOT the page's content — so naively lazy-loading the public
pages would mean every pre-rendered HTML (/pricing, /docs, /blog/*,
/use-cases/*, …) ships only a <span aria-hidden> instead of the
marketing copy. That defeats the entire SEO/GEO setup.

Fix: src/entry-server.tsx now declares its own SSRRoutes with
synchronous imports for every public page. The SSR bundle is built by
Vite as a separate module graph (build({ ssr: 'src/entry-server.tsx' }))
and thrown away after prerender, so the static imports there don't bloat
the client output. The route table is duplicated between App.tsx (lazy)
and entry-server.tsx (static) — small cost, documented inline at the top
of entry-server.tsx, and Keep-In-Sync flagged for future route adds.

I first tried a unified App.tsx using `import.meta.env.SSR` to switch
between lazy and static imports inline. Vite emits a warning when a
module is both statically and dynamically imported and refuses to split
it — so that approach silently put every "lazy" page back into the main
bundle. Separate SSR entry is the only pattern that actually splits.

Verification:
- npm run build emits 116 static HTML files + 116 .md mirrors (unchanged).
- Pre-rendered HTML contains real content (no "Loading…" fallbacks):
  /pricing 36 kB, /docs 22 kB, /use-cases 73 kB, /blog 14 kB.
- npm test → 96 passed, 3 skipped (unchanged from baseline).
- tsc --noEmit clean.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

src/App.tsx

@@ -1,26 +1,51 @@
 import { lazy, Suspense } from 'react'
 import { BrowserRouter, Navigate, Route, Routes, useLocation } from 'react-router-dom'
 
-// Public marketing surfaces — eagerly imported. A marketing visitor might
-// click any of these from the homepage nav, so keeping them in the main
-// chunk avoids a network round-trip on first interaction. These are also
-// the routes that get statically pre-rendered by scripts/prerender.mjs.
+// Homepage — eagerly imported. It's the cold-load path and the most-visited
+// public surface, so it stays in the main entry chunk.
 import { MarketingPage } from './pages/MarketingPage'
-import { PricingPage } from './pages/PricingPage'
-import { ForAgentsPage } from './pages/ForAgentsPage'
-import { StatusPage } from './pages/StatusPage'
-import { BlogPage } from './pages/BlogPage'
-import { BlogPostPage } from './pages/BlogPostPage'
-import { DocsPage } from './pages/DocsPage'
-import { UseCasesPage } from './pages/UseCasesPage'
-import { UseCaseDetailPage } from './pages/UseCaseDetailPage'
 
 // Auth surfaces — eagerly imported. A marketing visitor can land on /login
 // directly (deep link, "Sign in" button), and the login form is small.
 import { LoginPage } from './pages/LoginPage'
 import { LoginCallbackPage } from './pages/LoginCallbackPage'
 import { ClaimPage } from './pages/ClaimPage'
 
+// Secondary public marketing surfaces — lazy-loaded on the client so Rollup
+// splits each one into its own chunk and a homepage visitor never pays for
+// the bytes of pages they didn't navigate to. A click on the nav fetches
+// the chunk on demand.
+//
+// SSR note: scripts/prerender.mjs uses src/entry-server.tsx, which defines
+// its OWN AppRoutes with synchronous imports — so renderToString sees real
+// components and the pre-rendered HTML contains every word of content.
+// React.lazy() during renderToString would otherwise resolve to the
+// Suspense fallback and ship empty HTML to crawlers, killing SEO.
+const PricingPage = lazy(() =>
+  import('./pages/PricingPage').then((m) => ({ default: m.PricingPage })),
+)
+const ForAgentsPage = lazy(() =>
+  import('./pages/ForAgentsPage').then((m) => ({ default: m.ForAgentsPage })),
+)
+const StatusPage = lazy(() =>
+  import('./pages/StatusPage').then((m) => ({ default: m.StatusPage })),
+)
+const BlogPage = lazy(() =>
+  import('./pages/BlogPage').then((m) => ({ default: m.BlogPage })),
+)
+const BlogPostPage = lazy(() =>
+  import('./pages/BlogPostPage').then((m) => ({ default: m.BlogPostPage })),
+)
+const DocsPage = lazy(() =>
+  import('./pages/DocsPage').then((m) => ({ default: m.DocsPage })),
+)
+const UseCasesPage = lazy(() =>
+  import('./pages/UseCasesPage').then((m) => ({ default: m.UseCasesPage })),
+)
+const UseCaseDetailPage = lazy(() =>
+  import('./pages/UseCaseDetailPage').then((m) => ({ default: m.UseCaseDetailPage })),
+)
+
 // Authenticated dashboard surfaces — lazy-loaded. These pages only render
 // behind AuthGate (token must be present), so a marketing visitor never
 // needs the bytes. Each React.lazy() call ends up in its own chunk; Rollup
@@ -104,23 +129,35 @@ function AppLoadingFallback() {
   )
 }
 
+// PublicLoadingFallback — shown while a lazy-loaded public marketing page
+// chunk is in flight (e.g. /pricing, /docs, /blog). We render an empty
+// span instead of "Loading…" text so a flash of loader copy never appears
+// over the layout for a sub-100ms chunk fetch on a warm cache.
+//
+// Note: this fallback only ever appears in the browser. The SSG path in
+// scripts/prerender.mjs uses src/entry-server.tsx, which declares its own
+// route tree with synchronous imports — so renderToString resolves real
+// content into every pre-rendered HTML file and crawlers never see this.
+function PublicLoadingFallback() {
+  return <span aria-hidden="true" />
+}
+
 // PricingPage and ForAgentsPage both wrap themselves in <PublicShell>, and
 // MarketingPage inlines its own nav. So routes mount the page directly —
 // no extra shell wrapper needed (would cause double nav rendering).
 
-// AppRoutes is the route tree without the surrounding router. Exported so
-// the SSR entry (src/entry-server.tsx) can mount it under <StaticRouter>
-// for build-time pre-rendering. The browser-side wrapper below stays the
-// same — this is just an extraction, no route changes.
+// AppRoutes is the browser-side route tree. The SSR entry
+// (src/entry-server.tsx) declares its own equivalent tree with synchronous
+// imports — see the comment at the top of that file for why.
 //
-// SSR note: scripts/prerender.mjs only renders public routes (see its
-// PRERENDER_ROUTES list — no /app/* paths). React.lazy resolves to a
-// Suspense fallback during SSR for unrendered chunks, but since SSG never
-// visits an /app route, the lazy components are never invoked server-side
-// and the build still emits 115 HTML files.
+// The outer <Suspense> here catches the lazy public pages (Pricing, Blog,
+// Docs, etc.) while their chunks load. The inner <Suspense> inside the
+// /app route handles the lazy /app/* pages — kept separate so a click in
+// /app doesn't blank the marketing shell.
 export function AppRoutes() {
   return (
-    <Routes>
+    <Suspense fallback={<PublicLoadingFallback />}>
+      <Routes>
         {/* ─── public marketing surfaces ─────────────────────────── */}
         <Route path="/" element={<MarketingPage />} />
         <Route path="/pricing" element={<PricingPage />} />
@@ -180,6 +217,7 @@ export function AppRoutes() {
 
         <Route path="*" element={<Navigate to="/" replace />} />
       </Routes>
+    </Suspense>
   )
 }
 

src/entry-server.tsx

@@ -6,19 +6,69 @@
  * fetch one of those files and see real content instead of an empty
  * <div id="root"></div>. That is the entire SEO/GEO fix.
  *
- * Keep this surface tiny — just `render(url)`. The route tree itself lives
- * in App.tsx and is shared with the browser entry. */
+ * Why this file has its own route tree instead of reusing App.tsx's:
+ *
+ * The browser-side App.tsx uses React.lazy() for every secondary marketing
+ * page (PricingPage, BlogPage, DocsPage, UseCasesPage, etc.) so Rollup
+ * splits them into separate chunks and the homepage cold-load doesn't
+ * carry their bytes. React.lazy is async by design — during renderToString
+ * it suspends and the parent <Suspense> renders the fallback, NOT the
+ * page's content. That would defeat SEO entirely: every pre-rendered HTML
+ * would contain only the loading fallback.
+ *
+ * To fix that without bundling all marketing pages into the client entry,
+ * this file re-declares AppRoutes with SYNCHRONOUS imports for the lazy
+ * pages. The SSR bundle (dist-ssr/entry-server.mjs) is built separately
+ * by Vite via `build({ ssr: 'src/entry-server.tsx' })` — its module graph
+ * is completely independent of the client bundle, so static imports here
+ * don't bloat the client output.
+ *
+ * Keep the route table here in sync with App.tsx's AppRoutes. The /app/*
+ * subtree is omitted because auth-gated pages are never pre-rendered. */
 
 import { StrictMode } from 'react'
+import { Navigate, Route, Routes } from 'react-router-dom'
 import { renderToString } from 'react-dom/server'
 import { StaticRouter } from 'react-router-dom/server'
-import { AppRoutes } from './App'
+
+// Public marketing pages — synchronous imports so renderToString resolves
+// every component to real HTML instead of a Suspense fallback.
+import { MarketingPage } from './pages/MarketingPage'
+import { PricingPage } from './pages/PricingPage'
+import { ForAgentsPage } from './pages/ForAgentsPage'
+import { StatusPage } from './pages/StatusPage'
+import { BlogPage } from './pages/BlogPage'
+import { BlogPostPage } from './pages/BlogPostPage'
+import { DocsPage } from './pages/DocsPage'
+import { UseCasesPage } from './pages/UseCasesPage'
+import { UseCaseDetailPage } from './pages/UseCaseDetailPage'
+
+// SSRRoutes — the SSG-only route tree. Mirrors the public surface of the
+// client AppRoutes (everything reachable without auth). The /app/* subtree
+// is intentionally omitted: scripts/prerender.mjs never pre-renders auth-
+// gated routes (they'd crash on localStorage anyway).
+function SSRRoutes() {
+  return (
+    <Routes>
+      <Route path="/" element={<MarketingPage />} />
+      <Route path="/pricing" element={<PricingPage />} />
+      <Route path="/for-agents" element={<ForAgentsPage />} />
+      <Route path="/status" element={<StatusPage />} />
+      <Route path="/blog" element={<BlogPage />} />
+      <Route path="/blog/:slug" element={<BlogPostPage />} />
+      <Route path="/docs" element={<DocsPage />} />
+      <Route path="/use-cases" element={<UseCasesPage />} />
+      <Route path="/use-cases/:slug" element={<UseCaseDetailPage />} />
+      <Route path="*" element={<Navigate to="/" replace />} />
+    </Routes>
+  )
+}
 
 export function render(url: string): string {
   return renderToString(
     <StrictMode>
       <StaticRouter location={url}>
-        <AppRoutes />
+        <SSRRoutes />
       </StaticRouter>
     </StrictMode>
   )