feat(rsc): expose server-reference reachability metadata

packages/plugin-rsc/README.md

@@ -32,6 +32,7 @@ npm create vite@latest -- --template rsc
 - [`./examples/ppr`](./examples/ppr) - Partial prerendering with a reusable static HTML shell and request-time RSC content.
 - [`./examples/no-ssr`](./examples/no-ssr) - RSC application without an SSR environment.
 - [`./examples/client-first`](./examples/client-first) - Experimental client-owned page that consumes RSC function results.
+- [`./examples/action-reachability`](./examples/action-reachability) - Cross-environment module reachability for a server action wrapped in an ordinary client-side object.
 - [`./examples/browser-mode`](./examples/browser-mode) - Advanced setup that runs both RSC and React client environments in the browser with custom module loading.
 - [`./examples/performance-track`](./examples/performance-track) - Minimal React Server Components performance track probe.
 - [`./examples/react-router`](./examples/react-router) - React Router RSC integration

packages/plugin-rsc/e2e/action-reachability.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from '@playwright/test'
+import { useFixture } from './fixture'
+import { waitForHydration } from './helper'
+
+test.describe('build', () => {
+  const f = useFixture({
+    root: 'examples/action-reachability',
+    mode: 'build',
+  })
+
+  test('executes a retained action through /a', async ({ page }) => {
+    // The production manifest redispatches the /b request through /a.
+    await page.goto(f.url('/a'))
+    await waitForHydration(page)
+    await page.getByRole('button', { name: 'Save action A' }).click()
+    await page.getByRole('link', { name: '/b' }).click()
+    await expect(
+      page.getByRole('heading', { name: 'This is page "b"' }),
+    ).toBeVisible()
+    await expect(
+      page.getByRole('button', { name: 'Run saved action' }),
+    ).toBeEnabled()
+
+    await page.getByRole('button', { name: 'Run saved action' }).click()
+    await expect(
+      page.getByText('Result: ACTION_A_OK:MIDDLEWARE_A'),
+    ).toBeVisible()
+    await expect(page).toHaveURL(f.url('/b'))
+    await expect(
+      page.getByRole('heading', { name: 'This is page "b"' }),
+    ).toBeVisible()
+  })
+})
+
+test.describe('dev', () => {
+  const f = useFixture({
+    root: 'examples/action-reachability',
+    mode: 'dev',
+  })
+
+  test('executes a retained action through /b', async ({ page }) => {
+    // Development has no route manifest, so the same request stays on /b.
+    await page.goto(f.url('/a'))
+    await waitForHydration(page)
+    await page.getByRole('button', { name: 'Save action A' }).click()
+    await page.getByRole('link', { name: '/b' }).click()
+    await expect(
+      page.getByRole('heading', { name: 'This is page "b"' }),
+    ).toBeVisible()
+    await expect(
+      page.getByRole('button', { name: 'Run saved action' }),
+    ).toBeEnabled()
+
+    await page.getByRole('button', { name: 'Run saved action' }).click()
+    await expect(
+      page.getByText('Result: ACTION_A_OK:MIDDLEWARE_B'),
+    ).toBeVisible()
+    await expect(page).toHaveURL(f.url('/b'))
+    await expect(
+      page.getByRole('heading', { name: 'This is page "b"' }),
+    ).toBeVisible()
+  })
+})

packages/plugin-rsc/examples/action-reachability/README.md

@@ -0,0 +1,43 @@
+# Cross-Environment Action Reachability
+
+This example demonstrates route-aware dispatch for a retained server action. Action A is reachable from route `/a`'s application graph but not from route `/b`'s graph. The browser can still retain its server reference, navigate to `/b`, and invoke it there.
+
+The example follows this sequence:
+
+1. Open `/a` and save action A in a shared browser module.
+2. Navigate to `/b`, retaining the saved server reference.
+3. Invoke action A through an explicit-ID action request to `/b`.
+
+| Mode        | Action executes through | Result                     | Rendered page |
+| ----------- | ----------------------- | -------------------------- | ------------- |
+| Production  | `/a` middleware         | `ACTION_A_OK:MIDDLEWARE_A` | `/b`          |
+| Development | `/b` middleware         | `ACTION_A_OK:MIDDLEWARE_B` | `/b`          |
+
+In production, a generated route-action manifest lets the RSC handler redispatch the action request through a route whose graph can load the action. This example enables manifest routing only in production, so development stays on the current route.
+
+## Application graphs
+
+For simplicity, the app routes and their graph roots are declared manually. Route `/a` reaches action A through a Client Component and an ordinary runtime return value:
+
+```text
+src/app/a/page.tsx
+  -> client.tsx ("use client")
+  -> action-indirect.ts returns actionA
+  -> action.tsx ("use server")
+```
+
+## Manifest generation
+
+During the RSC build, the manifest plugin traverses each route graph and records directly reachable server reference IDs and reachable client reference keys. During the client build, it calls the experimental `manager.getClientToServerReferenceReachability(this)` API to map those client references to server reference IDs. For each route, it unions the directly reachable IDs with the IDs reachable through its client references.
+
+After all environment builds finish, the plugin installs the mapping in the RSC output for runtime routing.
+
+## Request redispatch
+
+For the production scenario above, the RSC handler finds action A under `/a` in the manifest and creates a new action request for `/a`. That request re-enters `/a` middleware, so the action observes `MIDDLEWARE_A`. It also preserves `/b` as the render URL, so the response continues rendering page B.
+
+Development skips route-aware redispatch. The handler executes action A on `/b`, so the action observes `MIDDLEWARE_B`.
+
+## Protocol scope
+
+For simplicity, route-aware redispatch covers only hydrated action calls that carry an explicit action ID. Progressive multipart form actions still use the baseline `decodeAction()` path without manifest routing.

packages/plugin-rsc/examples/action-reachability/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@vitejs/plugin-rsc-examples-action-reachability",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "latest",
+    "@vitejs/plugin-rsc": "latest",
+    "rsc-html-stream": "^0.0.7",
+    "vite": "^8.1.5"
+  }
+}

packages/plugin-rsc/examples/action-reachability/route-action-manifest-plugin.ts

@@ -0,0 +1,129 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { getPluginApi, type RscPluginManager } from '@vitejs/plugin-rsc'
+import { normalizePath, type Plugin } from 'vite'
+
+// TODO: A framework would derive these graph roots from the runtime route
+// convention. This example lists them again for simplicity.
+const routes = {
+  '/a': ['./src/app/root.tsx', './src/app/a/page.tsx'],
+  '/b': ['./src/app/root.tsx', './src/app/b/page.tsx'],
+}
+
+const ROUTE_ACTION_MANIFEST_ID = 'virtual:route-action-manifest'
+const ROUTE_ACTION_MANIFEST_FILE = '__route_action_manifest.js'
+
+export function routeActionManifestPlugin(): Plugin {
+  let manager: RscPluginManager
+  const routeClientReferenceKeys = new Map<string, Set<string>>()
+  const routeDirectServerReferenceIds = new Map<string, Set<string>>()
+  let routeActionManifest: Record<string, string[]> = {}
+
+  return {
+    name: 'route-action-manifest',
+    configResolved(config) {
+      manager = getPluginApi(config)!.manager
+    },
+    resolveId(source) {
+      if (source === ROUTE_ACTION_MANIFEST_ID) {
+        return this.environment.mode === 'build'
+          ? { id: source, external: true }
+          : '\0' + source
+      }
+    },
+    load(id) {
+      if (id === '\0' + ROUTE_ACTION_MANIFEST_ID) {
+        return 'export default null'
+      }
+    },
+    generateBundle() {
+      if (this.environment.name === 'rsc') {
+        // Collect each route's direct actions and reachable Client Components.
+        for (const [route, roots] of Object.entries(routes)) {
+          const clientReferenceKeys = new Set<string>()
+          const directServerReferenceIds = new Set<string>()
+          const visited = new Set<string>()
+          const queue = roots.map((source) =>
+            normalizePath(path.resolve(source)),
+          )
+          for (let index = 0; index < queue.length; index++) {
+            const id = queue[index]!
+            if (visited.has(id)) continue
+            visited.add(id)
+
+            const clientReference = manager.clientReferenceMetaMap[id]
+            if (clientReference) {
+              clientReferenceKeys.add(clientReference.referenceKey)
+            }
+
+            const serverReference = manager.serverReferences.metaMap.get(id)
+            if (serverReference) {
+              for (const exportName of serverReference.exportNames) {
+                directServerReferenceIds.add(
+                  `${serverReference.referenceKey}#${exportName}`,
+                )
+              }
+            }
+
+            const info = this.getModuleInfo(id)
+            if (info) {
+              queue.push(...info.importedIds, ...info.dynamicallyImportedIds)
+            }
+          }
+          routeClientReferenceKeys.set(route, clientReferenceKeys)
+          routeDirectServerReferenceIds.set(route, directServerReferenceIds)
+        }
+        return
+      }
+
+      if (this.environment.name !== 'client') return
+      // Join RSC route reachability with the final client graph relation.
+      const reachabilityByReferenceKey = new Map(
+        manager
+          .getClientToServerReferenceReachability(this)
+          .map((entry) => [entry.referenceKey, entry.serverReferenceIds]),
+      )
+      routeActionManifest = Object.fromEntries(
+        Object.keys(routes).map((route) => {
+          const actionIds = new Set(routeDirectServerReferenceIds.get(route))
+          for (const referenceKey of routeClientReferenceKeys.get(route) ??
+            []) {
+            for (const actionId of reachabilityByReferenceKey.get(
+              referenceKey,
+            ) ?? []) {
+              actionIds.add(actionId)
+            }
+          }
+          return [route, [...actionIds].sort()]
+        }),
+      )
+    },
+    // Leave the virtual import external, then point it at an ESM sidecar
+    // generated after the later client build.
+    renderChunk(code, chunk) {
+      if (code.includes(ROUTE_ACTION_MANIFEST_ID)) {
+        let relativePath = path.posix.relative(
+          path.posix.dirname(chunk.fileName),
+          ROUTE_ACTION_MANIFEST_FILE,
+        )
+        if (!relativePath.startsWith('.')) {
+          relativePath = './' + relativePath
+        }
+        return {
+          code: code.replaceAll(ROUTE_ACTION_MANIFEST_ID, relativePath),
+        }
+      }
+    },
+    buildApp: {
+      order: 'post',
+      async handler(builder) {
+        // The client graph is available only after the RSC output was emitted.
+        const outDir = builder.config.environments.rsc.build.outDir
+        await fs.promises.writeFile(
+          path.join(outDir, ROUTE_ACTION_MANIFEST_FILE),
+          `export default ${JSON.stringify(routeActionManifest, null, 2)}\n`,
+        )
+      },
+    },
+  }
+}

packages/plugin-rsc/examples/action-reachability/src/app/a/action-indirect.ts

@@ -0,0 +1,7 @@
+import { actionA } from './action.tsx'
+
+// Return the server reference through ordinary runtime value flow, which
+// import/export binding reconstruction cannot follow.
+export function getActionA() {
+  return actionA
+}

packages/plugin-rsc/examples/action-reachability/src/app/a/action.tsx

@@ -0,0 +1,7 @@
+'use server'
+
+import { getRequestContext } from '../request-context.ts'
+
+export async function actionA() {
+  return `ACTION_A_OK:${getRequestContext().middlewareTag}`
+}

packages/plugin-rsc/examples/action-reachability/src/app/a/client.tsx

@@ -0,0 +1,24 @@
+'use client'
+
+import React from 'react'
+import { getSavedAction, setSavedAction } from '../saved-action.ts'
+import { getActionA } from './action-indirect.ts'
+
+export function ActionA() {
+  const [result, setResult] = React.useState('none')
+  const savedAction = getSavedAction()
+  const actionA = getActionA()
+  return (
+    <div>
+      <button onClick={() => actionA().then(setResult)}>Run action A</button>
+      <button onClick={() => setSavedAction(actionA)}>Save action A</button>
+      <button
+        disabled={!savedAction}
+        onClick={() => savedAction?.().then(setResult)}
+      >
+        Run saved action
+      </button>
+      <p>Result: {result}</p>
+    </div>
+  )
+}

packages/plugin-rsc/examples/action-reachability/src/app/a/middleware.ts

@@ -0,0 +1,5 @@
+import type { RouteMiddleware } from '../../framework/middleware.ts'
+import { runWithRequestContext } from '../request-context.ts'
+
+export const middleware: RouteMiddleware = (_request, next) =>
+  runWithRequestContext({ middlewareTag: 'MIDDLEWARE_A' }, next)

packages/plugin-rsc/examples/action-reachability/src/app/a/page.tsx

@@ -0,0 +1,10 @@
+import { ActionA } from './client.tsx'
+
+export function Page() {
+  return (
+    <main>
+      <h1>This is page "a"</h1>
+      <ActionA />
+    </main>
+  )
+}

packages/plugin-rsc/examples/action-reachability/src/app/b/action.tsx

@@ -0,0 +1,7 @@
+'use server'
+
+import { getRequestContext } from '../request-context.ts'
+
+export async function actionB() {
+  return `ACTION_B_OK:${getRequestContext().middlewareTag}`
+}

packages/plugin-rsc/examples/action-reachability/src/app/b/client.tsx

@@ -0,0 +1,23 @@
+'use client'
+
+import React from 'react'
+import { getSavedAction, setSavedAction } from '../saved-action.ts'
+import { actionB } from './action.tsx'
+
+export function ActionB() {
+  const [result, setResult] = React.useState('none')
+  const savedAction = getSavedAction()
+  return (
+    <div>
+      <button onClick={() => actionB().then(setResult)}>Run action B</button>
+      <button onClick={() => setSavedAction(actionB)}>Save action B</button>
+      <button
+        disabled={!savedAction}
+        onClick={() => savedAction?.().then(setResult)}
+      >
+        Run saved action
+      </button>
+      <p>Result: {result}</p>
+    </div>
+  )
+}

packages/plugin-rsc/examples/action-reachability/src/app/b/middleware.ts

@@ -0,0 +1,5 @@
+import type { RouteMiddleware } from '../../framework/middleware.ts'
+import { runWithRequestContext } from '../request-context.ts'
+
+export const middleware: RouteMiddleware = (_request, next) =>
+  runWithRequestContext({ middlewareTag: 'MIDDLEWARE_B' }, next)

packages/plugin-rsc/examples/action-reachability/src/app/b/page.tsx

@@ -0,0 +1,10 @@
+import { ActionB } from './client.tsx'
+
+export function Page() {
+  return (
+    <main>
+      <h1>This is page "b"</h1>
+      <ActionB />
+    </main>
+  )
+}

packages/plugin-rsc/examples/action-reachability/src/app/request-context.ts

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+type RequestContext = {
+  middlewareTag: string
+}
+
+const requestContextStorage = new AsyncLocalStorage<RequestContext>()
+
+export function runWithRequestContext<T>(
+  context: RequestContext,
+  callback: () => T,
+): T {
+  return requestContextStorage.run(context, callback)
+}
+
+export function getRequestContext(): RequestContext {
+  const context = requestContextStorage.getStore()
+  if (!context) throw new Error('Request context is not available')
+  return context
+}