fix: pre-bundle client packages to avoid duplicate React on cold start

[uhyo]

Summary

Fixes #128 — on a cold-started dev server (no .vite cache), React was loaded twice on the very first request, producing an Invalid hook call error before Vite auto-reloaded the page. On the second request (deps already optimized) the problem disappeared.

Root cause

@vitejs/plugin-rsc treats any package that declares react as a peer dependency as a "framework package." When a server component imports one, the plugin reaches it on the browser through a client-package-proxy virtual module that is generated at request time. The dependency optimizer's initial scan cannot follow that virtual module, so on a cold server the package — and the copy of React it pulls in — is only discovered once the page requests it.

That late discovery triggers a re-optimization pass, which leaves a second copy of React loaded on the first render before Vite reloads. The mismatched React instances break hooks (Invalid hook call → Cannot read properties of null (reading 'useState')).

This is not specific to @funstack/router (the package fsRoutes mode renders through) — any third-party "use client" component library imported from a server component hits the same wall.

Fix

Detect the project's directly-declared client packages — dependencies that list react in peerDependencies, the same heuristic @vitejs/plugin-rsc itself uses to decide what to proxy — and add them to the browser environment's optimizeDeps.include. They are then pre-bundled during the optimizer's initial pass, so React stays deduplicated to a single optimized chunk from the first request. No re-optimization, no duplicate React, no auto-reload.

Notes:

• Scoped to direct dependencies — those are the bare specifiers a server component can import and that Vite can resolve from the project root. A framework package nested inside another dependency is pre-bundled together with its parent. (Using the full transitive crawl instead surfaced internal deps like react-error-boundary that aren't resolvable from the user's root, causing Failed to resolve dependency warnings.)
• The react-in-peerDependencies key correctly excludes build plugins such as @vitejs/plugin-react (which peer-depends on vite, not react), so there are no false positives.
• The previous hardcoded @funstack/router special-case is removed — it is now auto-detected like any other client package, in all entry modes.

Verification

• Reproduced the cold-start Invalid hook call reliably before the fix (4/4 runs); after the fix multiple cold starts are clean (no error, no auto-reload) for both fsRoutes/@funstack/router and an arbitrary third-party-style "use client" package — with zero user config.
• Multi-entry and single-entry modes start without resolve warnings and render correctly.
• New unit tests for the detection (clientPackages.test.ts, fixture-based) plus an updated index.test.ts. Full unit suite, typecheck, lint, and format:check all pass.

🤖 Generated with Claude Code

---

Generated by Claude Code