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/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 })
+    },
+  })
+}