feat(plugin-rsc): expose onClientReference callback in renderToReadableStream

Add an experimental `onClientReference` callback option to `renderToReadableStream`
that fires when a client reference is encountered during RSC rendering. The callback
provides the reference id, name, and resolved asset dependencies (JS/CSS files).

This enables use cases like:
- Tracking which client components are used in a render
- Collecting asset dependencies for preloading
- Debugging client reference resolution

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

Author: hi-ogawa

packages/plugin-rsc/e2e/basic.test.ts

@@ -237,6 +237,24 @@ function defineTest(f: Fixture) {
     expect(f.proc().stderr()).toBe('')
   })
 
+  test('onClientReference callback', async ({ page }) => {
+    const response = await page.request.get(f.url('__test_onClientReference'))
+    expect(response.ok()).toBe(true)
+    const data = await response.json()
+    expect(data).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          id: expect.any(String),
+          name: expect.any(String),
+          deps: expect.objectContaining({
+            js: expect.any(Array),
+            css: expect.any(Array),
+          }),
+        }),
+      ]),
+    )
+  })
+
   test('client component', async ({ page }) => {
     await page.goto(f.url())
     await waitForHydration(page)

packages/plugin-rsc/examples/basic/src/framework/entry.rsc.tsx

@@ -79,7 +79,19 @@ async function handleRequest({
 
   const rscPayload: RscPayload = { root: getRoot(), formState, returnValue }
   const rscOptions = { temporaryReferences }
-  const rscStream = renderToReadableStream<RscPayload>(rscPayload, rscOptions)
+  const debugClientReferences: unknown[] = []
+  const rscStream = renderToReadableStream<RscPayload>(rscPayload, {
+    ...rscOptions,
+    onClientReference(metadata) {
+      debugClientReferences.push(metadata)
+    },
+  })
+
+  // test `onClientReference` callback
+  if (renderRequest.url.pathname === '/__test_onClientReference') {
+    await rscStream.pipeTo(new WritableStream({ write() {} }))
+    return Response.json(debugClientReferences)
+  }
 
   // Respond RSC stream without HTML rendering as decided by `RenderRequest`
   if (renderRequest.isRsc) {

packages/plugin-rsc/src/core/rsc.ts

@@ -116,7 +116,12 @@ export function createServerDecodeClientManifest(): ModuleMap {
   )
 }
 
-export function createClientManifest(): BundlerConfig {
+export function createClientManifest(options?: {
+  /**
+   * @internal
+   */
+  onClientReference?: (metadata: { id: string; name: string }) => void
+}): BundlerConfig {
   const cacheTag = import.meta.env.DEV ? createReferenceCacheTag() : ''
 
   return new Proxy(
@@ -127,6 +132,7 @@ export function createClientManifest(): BundlerConfig {
         let [id, name] = $$id.split('#')
         tinyassert(id)
         tinyassert(name)
+        options?.onClientReference?.({ id, name })
         return {
           id: id + cacheTag,
           name,

packages/plugin-rsc/src/react/rsc.ts

@@ -13,12 +13,18 @@ export { loadServerAction, setRequireModule } from '../core/rsc'
 
 export function renderToReadableStream<T>(
   data: T,
-  options?: object,
+  options?: object & {
+    /**
+     * @internal
+     */
+    onClientReference?: (metadata: { id: string; name: string }) => void
+  },
 ): ReadableStream<Uint8Array> {
+  const { onClientReference, ...restOptions } = options || {}
   return ReactServer.renderToReadableStream(
     data,
-    createClientManifest(),
-    options,
+    createClientManifest({ onClientReference }),
+    restOptions,
   )
 }
 

packages/plugin-rsc/src/rsc.tsx

@@ -1,6 +1,9 @@
+import assetsManifest from 'virtual:vite-rsc/assets-manifest'
 import serverReferences from 'virtual:vite-rsc/server-references'
 import { setRequireModule } from './core/rsc'
+import type { ResolvedAssetDeps } from './plugin'
 import { toReferenceValidationVirtual } from './plugins/shared'
+import { renderToReadableStream as originalRenderToReadableStream } from './react/rsc'
 
 export {
   createClientManifest,
@@ -36,3 +39,29 @@ function initialize(): void {
     },
   })
 }
+
+export function renderToReadableStream<T>(
+  data: T,
+  options?: object & {
+    /**
+     * @experimental
+     */
+    onClientReference?: (metadata: {
+      id: string
+      name: string
+      deps: ResolvedAssetDeps
+    }) => void
+  },
+): ReadableStream<Uint8Array> {
+  const { onClientReference, ...restOptions } = options || {}
+  return originalRenderToReadableStream(data, {
+    ...restOptions,
+    onClientReference(metadata) {
+      const deps = assetsManifest.clientReferenceDeps[metadata.id] ?? {
+        js: [],
+        css: [],
+      }
+      onClientReference?.({ id: metadata.id, name: metadata.name, deps })
+    },
+  })
+}