docs: add Vercel Analytics and Speed Insights to the VitePress site

CLAUDE.md

@@ -114,3 +114,5 @@ VitePress 1.x site deployed to Vercel (`vercel.json` pins the build command/outp
 **Diagrams are mermaid**, through `vitepress-plugin-mermaid` (already wired: the config is wrapped in `withMermaid`). Write them as ` ```mermaid ` fences. Three constraints that are easy to rediscover the hard way: the config must **not** set `mermaid.theme` (the plugin picks `default`/`dark` from VitePress' `isDark` and re-renders on toggle; setting it freezes diagrams in one theme); mermaid's CJS-only transitive deps (`dayjs`) need `vite.optimizeDeps.include` or the dev server fails to boot; and `.mermaid` label `line-height` must be pinned to 1.25 in `custom.css` or multi-line labels overflow the shapes mermaid measured them into. Check a new diagram in **both** themes and at mobile width.
 
 **Branding** lives in `docs/public/` (`logo-mark.svg` — the mark: a Node.js hexagon holding the two directions of an RPC — `favicon.png`, `logo.png` for `og:image`, `robots.txt`, `llms.txt`) and `docs/.vitepress/theme/custom.css` (Node.js green `#5FA04E` on ink `#1B1C1E`, applied by overriding VitePress CSS variables — the Pinia/Vite pattern, layout untouched). Light-theme `--vp-c-brand-1/-2` are **darkened** greens because `#5FA04E` fails WCAG AA as link text on white. The raster assets are generated from the mark by `node scripts/brand.js` (macOS `qlmanage`; re-run it after changing `logo-mark.svg`).
+
+**Analytics** is Vercel Web Analytics + Speed Insights, wired in `docs/.vitepress/theme/index.ts` via `enhanceApp`. Both use the **framework-agnostic** `inject()`/`injectSpeedInsights()` entrypoints rather than the `@vercel/*/vue` components, because those declare a `vue-router` peer and VitePress ships its own router; the imports are dynamic and guarded by `import.meta.env.SSR` so nothing reaches the SSR pass of `docs:build`. Analytics picks up VitePress' pushState navigations by itself, Speed Insights does not — its `setRoute` is chained onto `router.onAfterRouteChange` (chained, not replaced). Both are devDependencies (docs-only, like `vitepress` itself — the zero-dependency guarantee is about `dependencies`), and data only flows once Web Analytics and Speed Insights are enabled on the Vercel project.

docs/.vitepress/theme/index.ts

@@ -7,4 +7,29 @@ import './custom.css';
 // layout and components stay the default theme, the look comes from CSS variables.
 export default {
   extends: DefaultTheme,
+  enhanceApp({ router }) {
+    // Vercel Web Analytics + Speed Insights. The framework-agnostic `inject`
+    // entrypoints are used rather than the `/vue` components: those require
+    // `vue-router`, which VitePress does not use (it ships its own router).
+    // Both are browser-only, so they are imported dynamically to stay out of
+    // the SSR build that `pnpm docs:build` runs.
+    if (import.meta.env.SSR) return;
+    void import('@vercel/analytics').then(({ inject }) => {
+      // `mode: 'auto'` logs to the console on localhost and only sends data
+      // from the deployed site; the injected script picks up VitePress'
+      // pushState navigations on its own, so no per-route call is needed.
+      inject({ mode: 'auto', framework: 'vitepress' });
+    });
+    void import('@vercel/speed-insights').then(({ injectSpeedInsights }) => {
+      const insights = injectSpeedInsights({ framework: 'vitepress' });
+      if (!insights) return;
+      // Speed Insights does need the route pushed to it by hand. Chain onto any
+      // existing handler instead of replacing it.
+      const previous = router.onAfterRouteChange;
+      router.onAfterRouteChange = (to) => {
+        insights.setRoute(to);
+        return previous?.call(router, to);
+      };
+    });
+  },
 } satisfies Theme;

package.json

@@ -140,6 +140,8 @@
     "@trpc/client": "^11.18.0",
     "@trpc/server": "^11.18.0",
     "@types/node": "^22.10.0",
+    "@vercel/analytics": "^2.0.1",
+    "@vercel/speed-insights": "^2.0.0",
     "c8": "^10.1.3",
     "esbuild": "^0.28.1",
     "express": "^5.2.1",