docs(rsc): add manifest-based approach for viteRsc.import

Document the preferred implementation using static import functions
in a manifest file, which supports custom entryFileNames and enables
proper static analysis by bundlers.

Key additions:
- Manifest with static import functions (not dynamic lookups)
- Bidirectional support (RSC → SSR and SSR → RSC)
- Updated data flow showing entry injection after both scans
- Per-environment manifest generation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: hi-ogawa

packages/plugin-rsc/docs/notes/2026-01-16-vitersc-import.md

@@ -246,12 +246,205 @@ import.meta.viteRsc.importAsset('./entry.browser', { asset: 'client' }) // retur
 
 This avoids breaking changes and keeps each method's return type clear.
 
+## Manifest-Based Approach (Preferred)
+
+The initial implementation hardcoded output filenames (`${entryName}.js`), which breaks with custom `entryFileNames` config. A manifest approach solves this.
+
+### Problem with Hardcoded Filenames
+
+```ts
+// renderChunk - current implementation
+const targetFileName = `${entryName}.js` // ❌ Breaks with custom entryFileNames
+```
+
+Build order means RSC builds before SSR:
+
+```
+rsc (real) → client → ssr (real)
+     ↑                    ↑
+     RSC renderChunk      SSR output filenames known
+```
+
+### Solution: Manifest with Static Imports
+
+Generate a manifest file with **static import functions** that bundlers can analyze:
+
+```ts
+// __vite_rsc_env_imports_manifest.js (generated in buildApp after SSR build)
+export default {
+  '/abs/path/to/entry.ssr.tsx': () => import('../ssr/entry.ssr.js'),
+}
+```
+
+Transform emits manifest lookup:
+
+```ts
+// Original:
+await import.meta.viteRsc
+  .import('./entry.ssr', { environment: 'ssr' })
+  (
+    // Build transform to:
+    await import('./__vite_rsc_env_imports_manifest.js'),
+  )
+  .default['/abs/path/to/entry.ssr.tsx']()
+```
+
+### Why Static Import Functions?
+
+Dynamic imports like `import(manifest['key'])` break post-bundling and static analysis. By using functions with static import strings, bundlers can:
+
+- Analyze the dependency graph
+- Apply optimizations (tree-shaking, code-splitting)
+- Work correctly with further bundling
+
+### Implementation Changes
+
+**1. Transform (in RSC):**
+
+- Dev: unchanged (`globalThis.__VITE_ENVIRONMENT_RUNNER_IMPORT__`)
+- Build: emit manifest lookup instead of markers
+
+```ts
+// Build mode transform
+const manifestImport = `await import('./__vite_rsc_env_imports_manifest.js')`
+replacement = `(${manifestImport}).default[${JSON.stringify(resolvedId)}]()`
+```
+
+**2. Remove renderChunk:**
+
+- No longer needed for this feature (markers eliminated)
+
+**3. SSR generateBundle:**
+
+- Track output filenames for discovered entries
+
+```ts
+generateBundle(options, bundle) {
+  for (const [fileName, chunk] of Object.entries(bundle)) {
+    if (chunk.type === 'chunk' && chunk.isEntry) {
+      const resolvedId = chunk.facadeModuleId
+      if (resolvedId && resolvedId in manager.environmentImportMetaMap) {
+        manager.environmentImportOutputMap[resolvedId] = fileName
+      }
+    }
+  }
+}
+```
+
+**4. buildApp - writeEnvironmentImportsManifest:**
+
+- Generate manifest after SSR build completes
+- Calculate relative paths from manifest location to target chunks
+
+```ts
+function writeEnvironmentImportsManifest() {
+  const rscOutDir = config.environments.rsc.build.outDir
+  const manifestPath = path.join(
+    rscOutDir,
+    '__vite_rsc_env_imports_manifest.js',
+  )
+
+  let code = 'export default {\n'
+  for (const [resolvedId, meta] of Object.entries(
+    manager.environmentImportMetaMap,
+  )) {
+    const outputFileName = manager.environmentImportOutputMap[resolvedId]
+    const targetOutDir = config.environments[meta.targetEnv].build.outDir
+    const relativePath = normalizeRelativePath(
+      path.relative(rscOutDir, path.join(targetOutDir, outputFileName)),
+    )
+    code += `  ${JSON.stringify(resolvedId)}: () => import(${JSON.stringify(relativePath)}),\n`
+  }
+  code += '}\n'
+
+  fs.writeFileSync(manifestPath, code)
+}
+```
+
+### Bidirectional Support
+
+Both directions are supported:
+
+- **RSC → SSR**: `import('./entry.ssr', { environment: 'ssr' })` in RSC code
+- **SSR → RSC**: `import('./entry.rsc', { environment: 'rsc' })` in SSR code
+
+This is similar to "use client" / "use server" discovery - each scan phase can discover entries for other environments.
+
+**Key insight**: Entry injection must happen AFTER both scan phases but BEFORE real builds.
+
+### Data Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ RSC Scan                                                                │
+│   transform: discover viteRsc.import → populate environmentImportMetaMap│
+│   (discovers RSC → SSR imports)                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ SSR Scan                                                                │
+│   transform: discover viteRsc.import → populate environmentImportMetaMap│
+│   (discovers SSR → RSC imports)                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Inject Discovered Entries (in buildApp, after both scans)               │
+│   for each meta in environmentImportMetaMap:                            │
+│     inject meta.resolvedId into target environment's rollupOptions.input│
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ RSC Real Build                                                          │
+│   transform: emit manifest lookup code                                  │
+│   generateBundle: track resolvedId → outputFileName (for SSR → RSC)     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Client Build                                                            │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ SSR Real Build                                                          │
+│   transform: emit manifest lookup code                                  │
+│   generateBundle: track resolvedId → outputFileName (for RSC → SSR)     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────┐
+│ buildApp Post-Build                                                     │
+│   writeEnvironmentImportsManifest:                                      │
+│     - Write manifest to RSC output (for RSC → SSR imports)              │
+│     - Write manifest to SSR output (for SSR → RSC imports)              │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Manifest Per Source Environment
+
+Each source environment gets its own manifest with imports pointing to target environments:
+
+```ts
+// dist/rsc/__vite_rsc_env_imports_manifest.js (for RSC → SSR)
+export default {
+  '/abs/path/entry.ssr.tsx': () => import('../ssr/entry.ssr.js'),
+}
+
+// dist/ssr/__vite_rsc_env_imports_manifest.js (for SSR → RSC)
+export default {
+  '/abs/path/entry.rsc.tsx': () => import('../rsc/index.js'),
+}
+```
+
 ## Implementation Steps
 
-1. [ ] Add `environmentImportMetaMap` to RscPluginManager
-2. [ ] Clean up `import.ts`: add imports, parameterize with manager
-3. [ ] Implement transform to discover and track imports
-4. [ ] Add `buildStart` hook to emit discovered entries in target environment
-5. [ ] Implement renderChunk to resolve markers
-6. [ ] Test with basic example
-7. [ ] Update documentation
+1. [x] Add `environmentImportMetaMap` to RscPluginManager
+2. [x] Clean up `import-environment.ts`: add imports, parameterize with manager
+3. [x] Implement transform to discover and track imports
+4. [x] Inject discovered entries into target environment's input
+5. [ ] **Fix**: Move entry injection to AFTER both scans (currently after RSC scan only)
+6. [ ] Update transform to emit manifest lookup (build mode)
+7. [ ] Remove renderChunk marker replacement
+8. [ ] Add `environmentImportOutputMap` to track resolvedId → outputFileName
+9. [ ] Add generateBundle hook to populate output map (in both RSC and SSR)
+10. [ ] Add `writeEnvironmentImportsManifest` in buildApp (per source environment)
+11. [ ] Test with basic example (RSC → SSR)
+12. [ ] Test bidirectional (SSR → RSC) if applicable
+13. [ ] Update documentation