vite-plugin-react-server 1.1.20 → 1.2.0-alpha.0

package/plugin/types.ts

@@ -1,7 +1,9 @@
 import type { Readable } from "node:stream";
-import type { Worker } from "node:worker_threads";
+import type {
+  Worker,
+  Serializable as WorkerSerializable,
+} from "node:worker_threads";
 import type React from "react";
-import type { ExoticComponent, FragmentProps } from "react";
 import type {
   NormalizedOutputOptions,
   OutputBundle,
@@ -15,30 +17,52 @@ import type {
   Connect,
   Logger,
   Manifest,
+  Plugin,
   ResolveOptions,
   UserConfig,
   ViteDevServer,
 } from "vite";
+import type {
+  serializeResolvedConfig,
+  serializeResolvedUserConfig,
+} from "./helpers/serializeUserOptions.js";
+import type { AllowedDirectives, Program } from "./loader/directives/types.js";
+import type { RenderMetrics, StreamMetrics } from "./metrics/types.js";
+import type { HtmlWorkerOutputMessage } from "./worker/html/types.js";
+import type { RscChunkOutputMessage } from "./worker/rsc/types.js";
 import type { ReactServerDomEsmOptions } from "./worker/types.js";
+import type { LoaderConfig, TransformOptions } from "./loader/types.js";
+
+export type ReactStreamPluginFn<
+  R extends Record<string, unknown> = {
+    meta: ReactStreamPluginMeta;
+  }
+> = <Opt extends StreamPluginOptions = StreamPluginOptions>(
+  options: Opt
+) => Plugin<R>;
 
 export type OnEvent = (event: PluginEvent) => void;
 
+export type MessageHandler<
+  T extends HtmlWorkerOutputMessage | RscChunkOutputMessage =
+    | HtmlWorkerOutputMessage
+    | RscChunkOutputMessage
+> = (message: T) => void | Promise<unknown>;
+
 export type CreateInputNormalizerProps = {
   root: string;
   preserveModulesRoot?: string | undefined;
   removeExtension?: boolean | RegExp | string | ((path: string) => boolean);
   moduleBasePath: string | undefined;
+  moduleBaseURL: string | undefined;
 };
 export type Serializable =
-  | string
-  | number
-  | boolean
-  | null
-  | undefined
+  | WorkerSerializable
   | Serializable[]
   | SerializableRecord;
+
 export type SerializableRecord = {
-  [key: string]: Serializable | SerializableRecord;
+  [key: string]: Serializable;
 };
 
 // Track HMR state
@@ -84,13 +108,13 @@ export type NormalizerInput = unknown;
 
 export type InputNormalizer = (input: NormalizerInput) => [string, string];
 
-export interface HtmlContent {
+export type HtmlContent = {
   raw: string;
   transformed?: string;
   assets?: string[];
-}
+};
 
-export interface PartialPageData {
+export type PartialPageData = {
   route: string;
   html?: {
     raw: string;
@@ -98,10 +122,10 @@ export interface PartialPageData {
     assets?: string[];
   };
   rsc?: {
-    modules: any[];
+    modules: unknown[];
     content: string;
   };
-}
+};
 
 export type InputNormalizerWorker = (
   input: NormalizerInput
@@ -141,18 +165,27 @@ export type ResolvedUserConfig = Required<
       >;
   };
 
-export type SerializedUserConfig = Extract<
-  ResolvedUserConfig,
-  SerializableRecord
->;
+export type SerializedUserConfig<
+  T extends ResolvedUserConfig = ResolvedUserConfig
+> = ReturnType<typeof serializeResolvedUserConfig<T>>;
+
+export type SerializedUserOptions = {
+  [k in keyof ResolvedUserOptions]: Extract<
+    ResolvedUserOptions[k],
+    Serializable | Record<string, Serializable>
+  > extends infer X
+    ? X extends never
+      ? undefined
+      : X
+    : undefined;
+};
 
-export type SerializedUserOptions = Extract<
-  ResolvedUserOptions,
-  SerializableRecord
+export type SerializedResolvedConfig = ReturnType<
+  typeof serializeResolvedConfig
 >;
 
 // Client plugin options
-export interface StreamPluginOptionsClient {
+export type StreamPluginOptionsClient = {
   outDir?: string;
   build?: BuildConfig;
   assetsDir?: string;
@@ -162,109 +195,186 @@ export interface StreamPluginOptionsClient {
   moduleBaseURL?: string;
   clientComponents?: AliasOptions;
   cssFiles?: AliasOptions;
-}
+};
 
-export type ResolvedUserOptions<
-  T extends PagePropOpt = PagePropOpt,
-  InlineCSS extends InlineCssOpt = InlineCssOpt
-> = Required<
-  Pick<
-    StreamPluginOptions<T, InlineCSS>,
-    | "moduleBase"
-    | "moduleBasePath"
-    | "moduleBaseURL"
-    | "moduleRootPath"
-    | "projectRoot"
-    | "build"
-    | "Page"
-    | "Html"
-    | "CssCollector"
-    | "pageExportName"
-    | "propsExportName"
-    | "htmlWorkerPath"
-    | "rscWorkerPath"
-    | "loaderPath"
-    | "clientEntry"
-    | "serverEntry"
-    // | "moduleBaseExceptions"
-    | "pipeableStreamOptions"
-    | "onMetrics"
-    | "onEvent"
-    | "css"
-    | "normalizer"
-    | "moduleID"
-    | "publicOrigin"
-    | "verbose"
-  >
-> & {
-  props:
-    | undefined
-    | string
-    | ((url: string) => string)
-    | ((url: string) => Promise<string>);
-  build: NonNullable<Required<StreamPluginOptions<T, InlineCSS>["build"]>>;
-  css: NonNullable<Required<StreamPluginOptions<T, InlineCSS>["css"]>> & {
-    inlineCss: InlineCSS;
-  };
-  autoDiscover: {
-    moduleExtension: RegExp;
-    serverDirective: RegExp;
-    clientDirective: RegExp;
-    cssExtension: string;
-    jsonExtension: string;
-    htmlExtension: string;
-    rscExtension: string;
-    jsExtension: string;
-    modulePattern: (path: string) => boolean;
-    cssPattern: (path: string) => boolean;
-    jsonPattern: (path: string) => boolean;
-    clientComponents: (path: string) => boolean;
-    propsPattern: (path: string) => boolean;
-    pagePattern: (path: string) => boolean;
-    htmlPattern: (path: string) => boolean;
-    rscPattern: (path: string) => boolean;
-    serverFunctions: (path: string) => boolean;
-    cssModulePattern: (path: string) => boolean;
-    vendorPattern: (path: string) => boolean;
-    nodeOnly: (path: string) => boolean;
-    dotFiles: (path: string) => boolean;
-    virtualPattern: (path: string) => boolean;
-    isServerFunctionCode: (code: string) => boolean;
-    isClientComponentCode: (code: string) => boolean;
-  };
+export type StringKeys =
+  | "moduleBase"
+  | "moduleBasePath"
+  | "moduleBaseURL"
+  | "moduleRootPath"
+  | "projectRoot"
+  | "pageExportName"
+  | "propsExportName"
+  | "htmlWorkerPath"
+  | "rscWorkerPath"
+  | "loaderPath"
+  | "reactLoaderPath"
+  | "cssLoaderPath"
+  | "envLoaderPath"
+  | "clientEntry"
+  | "serverEntry"
+  | "publicOrigin";
+
+export type NumberKeys =
+  | "rscTimeout"
+  | "htmlWorkerStartupTimeout"
+  | "rscWorkerStartupTimeout";
+
+export type BooleanKeys = "verbose";
+
+export type NestedConfigKeys =
+  | "build"
+  | "autoDiscover"
+  | "loader"
+  | "css"
+  | "pipeableStreamOptions";
+
+export type EventKeys = "onMetrics" | "onEvent";
+
+export type NormalizerKeys = "normalizer" | "moduleID";
+
+export type ComponentKeys = "Html" | "Root";
+
+export type SourceURLKeys = "Page" | "props";
+
+export type OptKey =
+  | StringKeys
+  | NumberKeys
+  | BooleanKeys
+  | EventKeys
+  | NormalizerKeys
+  | ComponentKeys
+  | SourceURLKeys;
+
+export type AutoDiscoverConfig = {
+  modulePattern: RegExp;
+  serverPattern: RegExp;
+  clientPattern: RegExp;
+  pagePattern: RegExp;
+  propsPattern: RegExp;
+  cssPattern: RegExp;
+  jsonPattern: RegExp;
+  htmlPattern: RegExp;
+  cssModulePattern: RegExp;
+  vendorPattern: RegExp;
+  nodePattern: RegExp;
+  dotPattern: RegExp;
+  virtualPattern: RegExp;
+  rscPattern: RegExp;
 };
 
-export interface StreamMetrics {
-  chunks: number;
-  bytes: number;
-  backpressureCount: number;
-  drainCount: number;
-  errorCount: number;
-  duration: number;
-  startTime: number;
-}
+export type GenericModuleLoader = (
+  id: string
+) => Promise<Record<string, unknown>>;
 
-export interface RenderMetrics {
-  route: string;
-  htmlSize: number;
-  rscSize: number;
-  processingTime: number;
-  chunks: number;
-  chunkRate: number;
-  memoryUsage: NodeJS.MemoryUsage;
-  streamMetrics: StreamMetrics;
-  htmlSizes: Map<string, number>;
-  rscSizes: Map<string, number>;
-}
+export type BuildModuleLoader<
+  Opt extends Pick<
+    ResolvedUserOptions,
+    "pageExportName" | "propsExportName"
+  > = Pick<ResolvedUserOptions, "pageExportName" | "propsExportName">,
+  T extends PagePropOpt = PagePropOpt
+> = <
+  STR extends string,
+  ID extends string = STR extends `${infer I extends string}${string}${string}`
+    ? I
+    : never,
+  Special extends "?" | "#" | "" = STR extends `${string}${infer X extends
+    | "?"
+    | "#"}${string}`
+    ? X
+    : "",
+  Extra extends string = STR extends `${string}${string}${infer Y extends string}`
+    ? Y
+    : ""
+>(
+  moduleId: STR
+) => Promise<
+  STR extends `${ID}${Special}${Extra}`
+    ? `${Special}${Extra}` extends "?inline"
+      ? { default: string }
+      : Extra extends Opt["pageExportName"]
+      ? {
+          [k in Extra]: (props: T) => unknown;
+        }
+      : Extra extends Opt["propsExportName"]
+      ? {
+          [k in Extra]: T;
+        }
+      : Extra extends string
+      ? Special extends "#"
+        ? { [k in Extra]: unknown }
+        : Record<string, unknown>
+      : Record<string, unknown>
+    : Record<string, unknown>
+>;
+
+export type StreamError = {
+  code?: string;
+} & Error;
+
+export type ResolvedUserOptions = {
+  // Core required properties
+  projectRoot: string;
+  moduleBase: string;
+  moduleBasePath: string;
+  moduleBaseURL: string;
+  moduleRootPath: string;
+  publicOrigin: string;
+  pageExportName: string;
+  propsExportName: string;
+  htmlExportName: string;
+  rootExportName: string;
+  htmlWorkerPath: string;
+  rscWorkerPath: string;
+  loaderPath: string;
+  reactLoaderPath?: string;
+  cssLoaderPath?: string;
+  envLoaderPath?: string;
+  verbose: boolean;
+  rscTimeout: number;
+  htmlWorkerStartupTimeout: number;
+  rscWorkerStartupTimeout: number;
+  panicThreshold: "none" | "critical_errors" | "all_errors";
+
+  // Optional properties
+  onEvent?: (event: PluginEvent) => void;
+  props?: StreamPluginOptions["props"];
+  clientEntry?: string;
+  serverEntry?: string;
+
+  // Required complex properties
+  Page: StreamPluginOptions["Page"];
+  Html: StreamPluginOptions["Html"]; // Unresolved: can be string, function
+  Root: StreamPluginOptions["Root"]; // Unresolved: can be string, function
+  normalizer: InputNormalizer;
+  moduleID: ((id: string) => string) | undefined;
+  onMetrics: (metrics: RenderMetrics) => void;
+  pipeableStreamOptions: ReactServerDomEsmOptions;
+  autoDiscover: Required<AutoDiscoverConfig>;
+  loader: Required<LoaderConfig>;
+  build: Required<BuildConfig>;
+  css: RootOptions<boolean>;
+  components?: StreamPluginOptions["components"]; // Direct component overrides (optional)
+};
 
-export interface CssCollectorOptions<
-  InlineCSS extends InlineCssOpt = InlineCssOpt
-> {
+export type DirectiveOptions = Pick<
+  TransformOptions,
+  "verbose" | "panicThreshold" | "loader"
+> & {
+  loader: Pick<
+    Required<NonNullable<TransformOptions["loader"]>>,
+    "isServerFunctionCode" | "isClientComponentCode" | "getDirectiveType"
+  > & {
+    allowedDirectives: AllowedDirectives;
+  };
+};
+
+export type RootOptions<InlineCSS extends InlineCssOpt = InlineCssOpt> = {
   inlineCss?: InlineCSS;
   inlineThreshold?: number;
   inlinePatterns?: RegExp[];
   linkPatterns?: RegExp[];
-}
+};
 
 export type CssContent<InlineCSS extends InlineCssOpt = InlineCssOpt> =
   InlineCSS extends true
@@ -276,50 +386,38 @@ export type CssContent<InlineCSS extends InlineCssOpt = InlineCssOpt> =
     : never;
 
 /**
- * Boxed component type for the CssCollector
+ * Boxed component type for the Root
  */
-export type CssCollectorBoxedType<
-  _T extends PagePropOpt = PagePropOpt,
-  _InlineCSS extends InlineCssOpt = InlineCssOpt,
-  _As extends AsOpt = AsOpt
-> = <
-  T extends _T = _T,
-  InlineCSS extends _InlineCSS = _InlineCSS,
-  As extends _As = _As
->(
-  props: CssCollectorProps<T, InlineCSS, As>
-) => React.ReactElement;
+export type RootComponentType<
+  As extends AsOpt = AsOpt,
+  InlineCSS extends InlineCssOpt = InlineCssOpt,
+  PageProps extends PagePropOpt = PagePropOpt,
+  ReactType = any
+> = (props: RootProps<PageProps, InlineCSS, As>) => ReactType;
 
-export type CssCollectorProps<
-  T extends PagePropOpt = PagePropOpt,
+export type RootProps<
+  PageProps extends PagePropOpt = PagePropOpt,
   InlineCSS extends InlineCssOpt = InlineCssOpt,
   As extends AsOpt = AsOpt
 > = {
   as: As;
   cssFiles?: Map<string, CssContent<InlineCSS>>;
-  pageProps?: T;
-  Page: PageComponentType<T>;
+  pageProps?: PageProps;
+  Page: PageComponentType<PageProps>;
   id?: string;
-} & React.ComponentPropsWithoutRef<As>;
+};
 
-export type CssCollectorComponent = (
-  props: CssCollectorProps
-) => React.ReactElement;
+export type RootComponent = (props: RootProps) => React.ReactNode;
 
 /**
  * Boxed component type for the Html component
  */
-export type HtmlBoxedType<
-  _T extends PagePropOpt = PagePropOpt,
-  _InlineCSS extends InlineCssOpt = InlineCssOpt,
-  _As extends AsOpt = "div"
-> = <
-  T extends _T = _T,
-  InlineCSS extends _InlineCSS = _InlineCSS,
-  As extends _As = _As
->(
-  props: HtmlProps<T, InlineCSS, As> & { key?: string }
-) => React.ReactNode;
+export type HtmlComponentType<
+  T extends PagePropOpt = PagePropOpt,
+  InlineCSS extends InlineCssOpt = InlineCssOpt,
+  As extends AsOpt = AsOpt,
+  ReactType = any
+> = ((props: HtmlProps<T, InlineCSS, As>) => ReactType) | any;
 
 export type FileWriteEvent = {
   type: "file.write";
@@ -354,7 +452,7 @@ export type RouteErrorEvent = {
   type: "route.error";
   data: {
     route: string;
-    error: any;
+    error?: Error | null;
   };
 };
 
@@ -362,7 +460,7 @@ export type RoutePostponeEvent = {
   type: "route.postpone";
   data: {
     route: string;
-    reason: string;
+    reason?: string | null;
   };
 };
 
@@ -371,7 +469,7 @@ export type PropsLoadEvent = {
   data: {
     route: string;
     propsPath: string;
-    props: any;
+    props: unknown;
   };
 };
 
@@ -443,11 +541,15 @@ export type PluginEvent =
 
 export type PluginEventType = PluginEvent["type"];
 
-export interface StreamPluginOptions<
+export type StreamPluginOptions<
   T extends PagePropOpt = PagePropOpt,
   InlineCSS extends InlineCssOpt = InlineCssOpt,
-  As extends AsOpt = AsOpt
-> {
+  As extends AsOpt = AsOpt,
+  N1 extends string = PageName,
+  N2 extends string = PropsName,
+  N3 extends string = HtmlName,
+  N4 extends string = RootName
+> = {
   projectRoot?: string; // defaults to process.cwd()
   moduleBase: string; // defaults to 'src'
   moduleBasePath?: string; // defaults to '/'
@@ -455,77 +557,225 @@ export interface StreamPluginOptions<
   moduleRootPath?: string; // defaults to client's dist folder
   publicOrigin?: string; // defaults to window.location.origin in client & http://localhost:port in development
   clientEntry?: string;
-  serverEntry?: string;
+  serverEntry?: string; // Loader configuration
+  loader?: {
+    importServerPath?: string;
+    importClientPath?: string;
+    registerClientReferenceName?: string;
+    registerServerReferenceName?: string;
+    serverDirective?: RegExpOpt;
+    clientDirective?: RegExpOpt;
+    directivePattern?: RegExpOpt;
+    isServerFunctionCode?: (code: string, moduleId?: string) => boolean;
+    isClientComponentCode?: (code: string, moduleId?: string) => boolean;
+    allowedDirectives?: string[] | AllowedDirectives;
+    mode?: "development" | "production" | "test";
+    getDirectiveType?: (
+      directive: string,
+      moduleId?: string
+    ) => "client" | "server" | undefined;
+    parse?: (source: string) => Promise<{
+      ast: Program;
+      code: string;
+      map?: { url: string; start: number; end: number; lines: number } | null;
+    }>;
+  };
   // Auto-discovery (zero-config)
   autoDiscover?:
     | {
-        // default: /\.(m|c)?(j|t)sx?$/
-        moduleExtension?: RegExp;
-        // default: /^"use server"[\s;]*\n?/m
-        serverDirective?: RegExp;
-        // default: /^"use client"[\s;]*\n?/m
-        clientDirective?: RegExp;
-        // css extension
-        cssExtension?: string;
-        // json extension
-        jsonExtension?: string;
-        // html extension
-        htmlExtension?: string;
-        // rsc extension
-        rscExtension?: string;
-        // .js extension
-        jsExtension?: string;
-        // default: /\.(m|c)?(j|t)sx?$/
+        // CSS related
+        /**
+         * Pattern to match CSS files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   cssPattern: ".css$",
+         *   // Or RegExp pattern
+         *   cssPattern: /\.css$/
+         * }
+         */
+        cssPattern?: RegExpOpt;
+        /**
+         * Pattern to match CSS module files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   cssModulePattern: ".css\\.js$",
+         *   // Or RegExp pattern
+         *   cssModulePattern: /\.css\.js$/
+         * }
+         */
+        cssModulePattern?: RegExpOpt;
+
+        // Client/Server related
+        /**
+         * Pattern to match client component files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   clientPattern: ".client\\.(js|ts|jsx|tsx)$",
+         *   // Or RegExp pattern
+         *   clientPattern: /\.client\.(js|ts|jsx|tsx)$/
+         * }
+         */
+        clientPattern?: RegExpOpt;
+        /**
+         * Pattern to match server function files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   serverPattern: ".server\\.(js|ts|jsx|tsx)$",
+         *   // Or RegExp pattern
+         *   serverPattern: /\.server\.(js|ts|jsx|tsx)$/
+         * }
+         */
+        serverPattern?: RegExpOpt;
+
+        // HTML related
+        /**
+         * Pattern to match HTML files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   htmlPattern: ".html$",
+         *   // Or RegExp pattern
+         *   htmlPattern: /\.html$/
+         * }
+         */
+        htmlPattern?: RegExpOpt;
+
+        // JSON related
+        /**
+         * Pattern to match JSON files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   jsonPattern: ".json$",
+         *   // Or RegExp pattern
+         *   jsonPattern: /\.json$/
+         * }
+         */
+        jsonPattern?: RegExpOpt;
+
+        // JS/Module related
+
+        /**
+         * Pattern to match module files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   modulePattern: "\\.(js|ts|jsx|tsx)$",
+         *   // Or RegExp pattern
+         *   modulePattern: /\.(js|ts|jsx|tsx)$/
+         * }
+         */
         modulePattern?: RegExpOpt;
-        // default: [Pp]age.tsx
+
+        // RSC related
+        /**
+         * Pattern to match RSC files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   rscPattern: ".rsc$",
+         *   // Or RegExp pattern
+         *   rscPattern: /\.rsc$/
+         * }
+         */
+        rscPattern?: RegExpOpt;
+
+        // Page/Props related
+        /**
+         * Pattern to match page files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   pagePattern: "[Pp]age\\.(js|ts|jsx|tsx)$",
+         *   // Or RegExp pattern
+         *   pagePattern: /[Pp]age\.(js|ts|jsx|tsx)$/
+         * }
+         */
         pagePattern?: RegExpOpt;
-        // default: [Pp]rops.ts
+        /**
+         * Pattern to match props files. If not provided, uses default pattern.
+         * Provide either a string pattern or RegExp.
+         * @example ```ts
+         * autoDiscover: {
+         *   // String pattern
+         *   propsPattern: "[Pp]rops\\.(js|ts|jsx|tsx)$",
+         *   // Or RegExp pattern
+         *   propsPattern: /[Pp]rops\.(js|ts|jsx|tsx)$/
+         * }
+         */
         propsPattern?: RegExpOpt;
-        // default: "use client" and .client./\.(m|c)?(j|t)sx?$/
-        clientComponents?: RegExpOpt;
-        // default: "use server" and .server./\.(m|c)?(j|t)sx?$/
-        serverFunctions?: RegExpOpt;
-        // default: /\.css$/
-        cssPattern?: RegExpOpt;
-        // default: /\.json$/
-        jsonPattern?: RegExpOpt;
-        // default: /\.html$/
-        htmlPattern?: RegExpOpt;
-        // default: /\.css\.js/
-        cssModulePattern?: RegExpOpt;
-        // default: /node_modules|(_virtual)/
+
+        // Special patterns
+        /**
+         * Pattern to match dot files. No interpolation support.
+         * @example ```ts
+         * autoDiscover: {
+         *   dotFiles: /^\.[^/]+$/
+         * }
+         */
+        dotPattern?: RegExpOpt;
+        /**
+         * Pattern to match Node.js native modules. No interpolation support.
+         * @example ```ts
+         * autoDiscover: {
+         *   nodePattern: /.node/
+         * }
+         */
+        nodePattern?: RegExpOpt;
+        /**
+         * Pattern to match vendor files. No interpolation support.
+         * @example ```ts
+         * autoDiscover: {
+         *   vendorPattern: /node_modules|_virtual/
+         * }
+         */
         vendorPattern?: RegExpOpt;
-        // default: /\.node\.js$/
-        nodeOnly?: RegExpOpt;
-        // default: /\.node\.js$/
-        dotFiles?: RegExpOpt;
-        // default: /^\/_virtual\//
+        /**
+         * Pattern to match virtual files. No interpolation support.
+         * @example ```ts
+         * autoDiscover: {
+         *   virtualPattern: /^virtual:/
+         * }
+         */
         virtualPattern?: RegExpOpt;
-        // default: /\.rsc$/
-        rscPattern?: RegExpOpt;
-        // default serverDirective regex
-        isServerFunctionCode?: (code: string, moduleId?: string) => boolean;
-        // default clientDirective regex
-        isClientComponentCode?: (code: string, moduleId?: string) => boolean;
       }
     | undefined;
   // Manual configuration
-  Page: string | ((url: string) => string) | ((url: string) => Promise<string>);
-  props?:
-    | undefined
-    | string
-    | ((url: string) => string)
-    | ((url: string) => Promise<string>);
+  Page?: UrlOpt;
+  props?: UrlOpt;
   // Escape hatches
   htmlWorkerPath?: string;
   rscWorkerPath?: string;
   loaderPath?: string;
-  pageExportName?: string;
-  propsExportName?: string;
-  Html?: React.FC<HtmlProps<T, InlineCSS, As>> | typeof React.Fragment;
-  CssCollector?: CssCollectorBoxedType<T, InlineCSS>;
+  reactLoaderPath?: string;
+  cssLoaderPath?: string;
+  envLoaderPath?: string;
+  pageExportName?: N1;
+  propsExportName?: N2;
+  htmlExportName?: N3;
+  rootExportName?: N4;
+  Html?: UrlOpt;
+  Root?: UrlOpt;
+  // Direct component overrides (bypasses string resolution)
+  components?: {
+    Html?: React.FC<HtmlProps<T, InlineCSS, As>> | typeof React.Fragment;
+    Root?: RootComponentType;
+  };
   build?: BuildConfig;
-  css?: CssCollectorOptions<InlineCSS>;
+  css?: RootOptions<InlineCSS>;
   // moduleBaseExceptions?: string[];
   pipeableStreamOptions?: ReactServerDomEsmOptions;
   onMetrics?: (metrics: RenderMetrics) => void;
@@ -533,59 +783,72 @@ export interface StreamPluginOptions<
   normalizer?: InputNormalizer;
   moduleID?: (id: string) => string;
   verbose?: boolean;
-}
+  rscTimeout?: number; // Timeout in milliseconds for RSC operations
+  htmlWorkerStartupTimeout?: number; // Timeout in milliseconds for HTML worker startup
+  rscWorkerStartupTimeout?: number; // Timeout in milliseconds for RSC worker startup
+  panicThreshold?: "none" | "critical_errors" | "all_errors";
+};
 
 export type MultiPageHandlerOptions<
-  T extends PagePropOpt = PagePropOpt,
-  InlineCSS extends InlineCssOpt = InlineCssOpt
+  Opt extends ResolvedUserOptions = ResolvedUserOptions
 > = Omit<
-  CreateHandlerOptions<T, InlineCSS>,
+  CreateHandlerOptions<Opt>,
   | "pagePath"
   | "route"
   | "cssFiles"
   | "propsPath"
+  | "rootPath"
+  | "htmlPath"
   | "pageProps"
   | "PageComponent"
+  | "RootComponent"
+  | "HtmlComponent"
 >;
 
 export type CreateHandlerOptions<
-  T extends PagePropOpt = PagePropOpt,
-  InlineCSS extends InlineCssOpt = InlineCssOpt
+  Opt extends ResolvedUserOptions = ResolvedUserOptions
 > = Pick<
-  ResolvedUserOptions<T, InlineCSS>,
+  Opt,
   | "autoDiscover"
   | "css"
   | "pageExportName"
   | "propsExportName"
-  | "Html"
-  | "CssCollector"
+  | "rootExportName"
+  | "htmlExportName"
   | "moduleBase"
   | "moduleRootPath"
   | "moduleBasePath"
   | "moduleBaseURL"
   | "publicOrigin"
-  | "pipeableStreamOptions"
   | "onEvent"
   | "onMetrics"
   | "projectRoot"
   | "normalizer"
   | "moduleID"
+  | "verbose"
+  | "components"
 > & {
   logger: Logger;
-  loader: ModuleLoader;
+  loader: BuildModuleLoader | GenericModuleLoader;
   pagePath: string;
   propsPath?: string;
-  pageProps?: T;
-  PageComponent?: PageComponentType<T>;
+  rootPath?: string;
+  htmlPath?: string;
+  pageProps?: PagePropOpt;
+  PageComponent?: PageComponentType<PagePropOpt>;
+  RootComponent?: RootComponentType;
+  HtmlComponent?: HtmlComponentType<PagePropOpt>;
   route: string;
+  as?: AsOpt;
   manifest: Manifest;
   worker?: Worker;
   server?: ViteDevServer;
   importedCss?: Set<string>;
-  cssFiles: Map<string, CssContent<InlineCSS>>;
-  globalCss: Map<string, CssContent<InlineCSS>>;
+  cssFiles: Map<string, CssContent<InlineCssOpt>>;
+  globalCss: Map<string, CssContent<InlineCssOpt>>;
+  pipeableStreamOptions: ReactServerDomEsmOptions;
   build: Pick<
-    ResolvedUserOptions<T, InlineCSS>["build"],
+    ResolvedUserOptions["build"],
     | "outDir"
     | "pages"
     | "server"
@@ -596,36 +859,30 @@ export type CreateHandlerOptions<
   >;
 };
 
-export interface ResolvePageOptions {
+export type ResolvePageOptions = {
   pagePath: string;
   pageExportName: string;
   url: string;
-}
+};
 
-export interface ResolvePropsOptions {
+export type ResolvePropsOptions = {
   propsPath: string;
   propsExportName: string;
   url: string;
-}
-
-export type ModuleLoader = (
-  url: string,
-  context?: any,
-  defaultLoad?: any
-) => Promise<Record<string, any>>;
+};
 
-export interface BaseProps {
-  manifest: import("vite").Manifest;
+export type BaseProps = {
+  manifest: Manifest;
   children?: React.ReactNode;
   assets?: {
     css?: string[];
   };
-}
+};
 
 export type StreamResult =
   | {
       type: "success";
-      stream: any;
+      stream: PassThrough;
       assets?: {
         css?: string[];
       };
@@ -633,7 +890,7 @@ export type StreamResult =
   | { type: "error"; error: unknown }
   | { type: "skip" };
 
-export interface RouteConfig {
+export type RouteConfig = {
   path: string;
   // Define page/props paths using patterns
   pattern?: {
@@ -645,15 +902,15 @@ export interface RouteConfig {
     page: string; // e.g. "page/home/page"
     props: string; // e.g. "page/home/props"
   };
-}
+};
 
-export interface BuildOutput {
+export type BuildOutput = {
   dir?: string;
   rsc?: string;
   ext?: string;
-}
+};
 
-export interface BuildConfig {
+export type BuildConfig = {
   pages: string[] | (() => Promise<string[]> | string[]) | Promise<string[]>;
   assetsDir?: string;
   client?: string; // Output directory for client files
@@ -662,52 +919,27 @@ export interface BuildConfig {
   api?: string; // Output directory for API files
   outDir?: string;
   hash?: string;
+  preserveDirectives?: boolean;
   preserveModulesRoot?: boolean;
   rscOutputPath?: string; // defaults: `index.rsc`
   htmlOutputPath?: string; // defaults: `index.html`
   entryFile?: (n: PreRenderedChunk, ssr: boolean) => string;
   chunkFile?: (n: PreRenderedChunk, ssr: boolean) => string;
   assetFile?: (n: PreRenderedAsset, ssr: boolean) => string;
-}
-
-export interface RscResolver {
-  /**
-   * Get RSC data for static generation
-   * @param path - Route path (e.g. "/", "/about")
-   */
-  getRscData: (path: string) => Promise<{
-    Page: React.ComponentType;
-    props: any;
-  }>;
-}
+  extensionMap?: Record<string, string>;
+  moduleExtension?: string;
+  jsExtension?: string;
+  cssExtension?: string;
+  htmlExtension?: string;
+  jsonExtension?: string;
+  rscExtension?: string;
+  cssModuleExtension?: string;
+  nodeExtension?: string;
+};
 
 export type RequestHandler = Connect.NextHandleFunction;
 
-export interface SsrStreamOptions {
-  url: string;
-  controller: AbortController;
-  loader: (id: string) => Promise<any>;
-  Html: any;
-  options: StreamPluginOptions;
-  pageExportName: string;
-  propsExportName: string;
-  moduleGraph: any;
-  bootstrapModules?: string[];
-  importMap?: Record<string, string[]>;
-  clientComponents?: boolean;
-  onlyClientComponents?: boolean;
-}
-
-export type RscServerConfig = {
-  /** How to get RSC data (e.g. HTTP, direct import, etc) */
-  getRscComponent: (url: string) => React.Usable<React.ReactNode>;
-  /** Base URL for client assets */
-  clientBase?: string;
-  /** SSR stream rendering options */
-  ssrOptions?: SsrStreamOptions;
-};
-
-export interface RscServerModule {
+export type RscServerModule = {
   /**
    * Get RSC data for a route
    * @param path - Route path (e.g. "/", "/about")
@@ -717,23 +949,23 @@ export interface RscServerModule {
     /** Page component to render */
     Page: React.ComponentType;
     /** Props to pass to the page */
-    props: any;
+    props: unknown;
   }>;
-}
+};
 
-export interface RegisterComponentMessage {
+export type RegisterComponentMessage = {
   type: "REGISTER_COMPONENT";
   id: string;
   code: string;
-}
+};
 
 export type RscBuildResult = string[];
 
-export interface ReactStreamPluginMeta {
+export type ReactStreamPluginMeta = {
   timing: BuildTiming;
-}
+};
 
-export interface BuildTiming {
+export type BuildTiming = {
   start: number;
   configResolved?: number;
   buildStart?: number;
@@ -743,11 +975,13 @@ export interface BuildTiming {
   closeBundle?: number;
   render?: number;
   total?: number;
-}
+};
 
 export type ResolvedBuildPages = {
   propsMap: Map<string, string>;
   pageMap: Map<string, string>;
+  rootMap: Map<string, string>;
+  htmlMap: Map<string, string>;
   /**
    * ## routeMap
    *
@@ -769,7 +1003,10 @@ export type ResolvedBuildPages = {
    * urlMap.set("/", { props: "/props", page: "/page" });
    * ```
    */
-  urlMap: Map<string, { props?: string; page: string }>;
+  urlMap: Map<
+    string,
+    { props?: string; page: string; root?: string; html?: string }
+  >;
   errors: Error[];
 };
 
@@ -778,22 +1015,38 @@ export type ModuleId = string & { readonly __brand: unique symbol };
 export type PagePath = string & { readonly __brand: unique symbol };
 
 export type InlineCssOpt = undefined | boolean;
-export type PagePropOpt = Record<string, unknown> | undefined;
-export type RegExpOpt = RegExp | string | ((path: string) => boolean);
+export type PagePropOpt = Record<string, unknown>;
+export interface DeserializedRegExp {
+  source: string;
+  flags: string;
+  __isRegExp: boolean;
+}
+
+export type RegExpOpt = RegExp | string | DeserializedRegExp;
+export type UrlOpt =
+  | string
+  | ((url: string) => string)
+  | ((url: string) => Promise<string>);
+export type PageName = "Page";
+export type PropsName = "props";
+export type HtmlName = "Html";
+export type RootName = "Root";
 
 export type AsOpt =
-  | ExoticComponent<FragmentProps>
+  | React.ExoticComponent<React.FragmentProps>
   | Exclude<keyof React.JSX.IntrinsicElements, "symbol" | "object">;
-export type PageComponentType<T extends PagePropOpt = PagePropOpt> =
-  React.ComponentType<T & React.PropsWithChildren<{}>>;
+export type PageComponentType<
+  PageProps extends PagePropOpt = PagePropOpt,
+  ReactType = any
+> = (props: PageProps) => ReactType;
 
 export type HtmlProps<
-  T extends PagePropOpt = PagePropOpt,
+  PageProps extends PagePropOpt = PagePropOpt,
   InlineCSS extends InlineCssOpt = InlineCssOpt,
   As extends AsOpt = AsOpt
 > = {
-  pageProps?: T;
-  Page: PageComponentType<T>;
+  pageProps?: PageProps;
+  Page: PageComponentType<PageProps>;
   route: string;
   url: string;
   projectRoot: string;
@@ -803,16 +1056,16 @@ export type HtmlProps<
   moduleRootPath: string;
   cssFiles: Map<string, CssContent<InlineCSS>>;
   manifest: Manifest;
-  CssCollector: CssCollectorBoxedType<T, InlineCSS, As>;
+  Root: RootComponentType<As, InlineCSS, PageProps>;
   globalCss: Map<string, CssContent<InlineCSS>>;
-  as: As;
+  as?: As;
 };
 
-export interface PageAsset {
+export type PageAsset = {
   type: "css" | "js";
   path: string;
   parentUrl: string;
-}
+};
 
 type BaseCssProps = {
   as: string;
@@ -838,13 +1091,11 @@ export type StyleCssProps = BaseCssProps & {
   href?: never;
 };
 
-export type CssCollectorElementsProps<
-  InlineCSS extends InlineCssOpt = InlineCssOpt
-> = {
+export type CssProps<InlineCSS extends InlineCssOpt = InlineCssOpt> = {
   cssFiles: Map<string, CssContent<InlineCSS>>;
 };
 
-export interface HtmlRenderState {
+export type HtmlRenderState = {
   id: string;
   rscStream: PassThrough;
   htmlStream: PassThrough;
@@ -856,7 +1107,7 @@ export interface HtmlRenderState {
     "onError" | "onPostpone"
   >;
   streamState: StreamMetrics;
-}
+};
 
 export type RenderPagesResult =
   | {
@@ -910,7 +1161,7 @@ export type CreateHandlerResult<InlineCSS extends InlineCssOpt = InlineCssOpt> =
     | {
         type: "success";
         controller: AbortController;
-        stream: any;
+        stream: PassThrough;
         assets: {
           css: CssContent<InlineCSS>[];
           js: string[];
@@ -933,7 +1184,7 @@ export type ReactStaticEvent =
     };
 
 // Define LoaderContext interface locally
-export interface LoaderContext {
+export type LoaderContext = {
   format?: string;
   importAttributes?: Record<string, string>;
   conditions?: string[];
@@ -941,11 +1192,136 @@ export interface LoaderContext {
     targetEnvironment?: "client" | "server" | "browser";
   };
   url: string;
-  userOptions?: any; // Add userOptions to the context
-}
+  userOptions?: SerializedUserOptions; // Add userOptions to the context
+};
 // Add type declaration for import.meta.cssModules
 declare global {
   interface ImportMeta {
     cssModules?: Record<string, Record<string, string>>;
   }
 }
+
+export type VendorInteropConfig = {
+  react: string; // e.g. "react"
+  reactDOMServer: string; // e.g. "react-dom/server"
+};
+
+// Client Browser exports:
+// - createFromFetch
+// - createFromReadableStream
+// - createServerReference
+// - createTemporaryReferenceSet
+// - encodeReply
+// - registerServerReference
+export type RSCClientBrowserInteropConfig = {
+  createFromFetch: string;
+  createFromReadableStream: string;
+  createServerReference: string;
+  createTemporaryReferenceSet: string;
+  encodeReply: string;
+  registerServerReference: string;
+};
+
+// Client Node exports:
+// - createFromNodeStream
+// - createServerReference
+// - registerServerReference
+export type RSCClientNodeInteropConfig = {
+  createFromNodeStream: string;
+  createServerReference: string;
+  registerServerReference: string;
+};
+
+// Server Node exports:
+// - createTemporaryReferenceSet
+// - decodeAction
+// - decodeFormState
+// - decodeReply
+// - decodeReplyFromBusboy
+// - registerClientReference
+// - registerServerReference
+// - renderToPipeableStream
+// - unstable_prerenderToNodeStream
+export type RSCServerInteropConfig = {
+  createTemporaryReferenceSet: string;
+  decodeAction: string;
+  decodeFormState: string;
+  decodeReply: string;
+  decodeReplyFromBusboy: string;
+  registerClientReference: string;
+  registerServerReference: string;
+  renderToPipeableStream: string;
+  unstable_prerenderToNodeStream: string;
+};
+
+export type RSCInteropConfig = {
+  client: {
+    browser: {
+      production: string; // e.g. "react-server-dom-esm/client.browser"
+      development: string; // e.g. "react-server-dom-esm/client.browser"
+      test: string; // e.g. "react-server-dom-esm/client.browser"
+      exports: RSCClientBrowserInteropConfig;
+    };
+    node: {
+      production: string; // e.g. "react-server-dom-esm/client"
+      development: string; // e.g. "react-server-dom-esm/client.node"
+      test: string; // e.g. "react-server-dom-esm/client.node"
+      exports: RSCClientNodeInteropConfig;
+    };
+  };
+  server: {
+    production: string; // e.g. "react-server-dom-esm/server"
+    development: string; // e.g. "react-server-dom-esm/server.node"
+    test: string; // e.g. "react-server-dom-esm/server.node"
+    exports: RSCServerInteropConfig;
+  };
+};
+
+export type FlightTarget =
+  | "default"
+  | "webpack"
+  | "nextjs"
+  | "react-server-dom-esm"
+  | "react-server-dom-webpack"
+  | "react-server-dom-parcel";
+
+export type FlightConfig = {
+  rsc: RSCInteropConfig;
+  vendor: VendorInteropConfig;
+};
+
+// Import configuration from separate file
+export {
+  createFlightBindings,
+  defaultFlightBindings,
+} from "./config/flightBindings.js";
+
+export type ReactStreamOptionsFn<ReturnType = void> = <
+  PageProp extends PagePropOpt = PagePropOpt,
+  As extends AsOpt = AsOpt,
+  N1 extends string = PageName,
+  N2 extends string = PropsName,
+  Input extends StreamPluginOptions<
+    PageProp,
+    InlineCssOpt,
+    As,
+    N1,
+    N2
+  > = StreamPluginOptions<PageProp, InlineCssOpt, As, N1, N2>,
+  Output extends ReturnType = ReturnType
+>(
+  options: Input
+) => Output;
+
+export type ReactStreamHandlerFn<ReturnType> = <
+  Opt extends CreateHandlerOptions = CreateHandlerOptions
+>(
+  options: Opt
+) => ReturnType;
+
+export type ReactStreamResolvedOptionsFn<ReturnType = void> = (
+  options: ResolvedUserOptions
+) => ReturnType;
+
+// re-exorts
+export type { RenderMetrics, StreamMetrics };