feat(rsc): add resolved-id proxy for virtual modules + document ?direct limitation

[hi-ogawa]

Summary

• Add vitePluginResolvedIdProxy() to enable virtual use client modules
• Add e2e tests for virtual modules (use client, CSS)
• Document Vite's ?direct query limitation for virtual CSS modules

The problem

Virtual modules in Vite use \0 prefix for resolved IDs (e.g., \0virtual:test-virtual-client). However, when RSC generates client reference imports, these \0-prefixed IDs cannot be used directly in import specifiers.

The fix

The resolved-id proxy encodes \0 so it can be used in import specifiers:

withResolvedIdProxy("\0virtual:test-virtual-client")
  => "virtual:vite-rsc/resolved-id/%00virtual%3Atest-virtual-client"

The vitePluginResolvedIdProxy() then resolves these back to the original \0-prefixed IDs. This enables virtual use client modules to work correctly in RSC.

---

Side note: Virtual CSS and ?direct limitation

During this work, we investigated why virtual CSS modules don't work with SSR <link> tags in dev mode.

How Vite's ?direct works

When a browser requests <link href="xxx.css">, Vite middleware injects ?direct query. The CSS plugin checks this to return raw CSS instead of a JS wrapper.

Why virtual CSS breaks

Standard virtual module plugins use exact string matching:

resolveId(source) {
  if (source === 'virtual:my.css') return `\0${source}`  // won't match "virtual:my.css?direct"
}

For real files, Vite retries with query stripped. Virtual modules don't benefit from this fallback.

Workaround for users

Make virtual CSS plugins query-aware:

resolveId(source) {
  const clean = source.split('?')[0]
  if (clean === 'virtual:my.css') {
    return `\0${clean}${source.slice(clean.length)}`  // preserve ?direct
  }
}
load(id) {
  const clean = id.split('?')[0]
  if (clean === '\0virtual:my.css') return `.my { color: red; }`
}

E2E test matrix

	Query-aware	Exact-match
Server CSS (via <link>)	✅ works	❌ dev fails
Client CSS (via JS import)	✅ works	✅ works

This is a Vite limitation. Proper fix would require Vite to provide query-aware virtual module helpers or apply query-stripping fallback to virtual modules.

---

🤖 Generated with Claude Code