@fluojs/react 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+export { ReactClientNavigationError, ReactClientRouterContextError } from './client/errors.js';
+export type { ReactClientNavigationErrorCode } from './client/errors.js';
+export { useNavigation, useParams, usePathname, useRouter, useRouterState, useSearchParams, } from './client/hooks.js';
+export { Link } from './client/link.js';
+export type { LinkProps } from './client/link.js';
+export { ReactClientRouterProvider } from './client/provider.js';
+export { createReactRouteSnapshot } from './client/snapshot.js';
+export type { ReactClientRouterProviderProps, ReactNavigationSnapshot, ReactNavigationStatus, ReactNavigationType, ReactReadonlySearchParams, ReactRouteSnapshot, ReactRouteSnapshotInput, ReactRouter, } from './client/types.js';
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAC/F,YAAY,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,WAAW,EACX,SAAS,EACT,cAAc,EACd,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,YAAY,EACV,8BAA8B,EAC9B,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,GACZ,MAAM,mBAAmB,CAAC"}

package/dist/client.js

@@ -0,0 +1,5 @@
+export { ReactClientNavigationError, ReactClientRouterContextError } from './client/errors.js';
+export { useNavigation, useParams, usePathname, useRouter, useRouterState, useSearchParams } from './client/hooks.js';
+export { Link } from './client/link.js';
+export { ReactClientRouterProvider } from './client/provider.js';
+export { createReactRouteSnapshot } from './client/snapshot.js';

package/dist/decorators.d.ts

@@ -0,0 +1,80 @@
+import type { MetadataPropertyKey } from '@fluojs/core';
+type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
+type StandardMethodDecoratorFn = (value: Function, context: ClassMethodDecoratorContext) => void;
+type LegacyClassDecoratorFn = (target: Function) => void;
+type LegacyMethodDecoratorFn = (target: object, propertyKey: MetadataPropertyKey, descriptor?: PropertyDescriptor) => void;
+type ClassDecoratorLike = StandardClassDecoratorFn & LegacyClassDecoratorFn;
+type MethodDecoratorLike = StandardMethodDecoratorFn & LegacyMethodDecoratorFn;
+/**
+ * Additional render-facing metadata stored by `@Path(...)` for the future React renderer.
+ *
+ * @remarks
+ * These options are intentionally runtime-neutral. They are recorded for diagnostics and
+ * later rendering integration without changing HTTP route matching, route grammar, DTO
+ * binding, validation, or request dispatch.
+ */
+export type ReactPathOptions = Readonly<Record<string, unknown>>;
+/**
+ * React router marker metadata written by `@Router(...)`.
+ */
+export type ReactRouterMetadata = {
+    /** Marker that distinguishes React routers from plain HTTP controllers. */
+    readonly kind: 'router';
+    /** Base path also written to the HTTP controller metadata. */
+    readonly basePath: string;
+};
+/**
+ * React render metadata written by `@Path(...)`.
+ */
+export type ReactPathMetadata = {
+    /** Marker that distinguishes React page handlers from plain HTTP routes. */
+    readonly kind: 'path';
+    /** Route path also written to the HTTP `GET` metadata. */
+    readonly path: string;
+    /** Optional render-facing metadata for the future React rendering layer. */
+    readonly options?: ReactPathOptions;
+};
+/**
+ * Marks a class as a React router while writing equivalent HTTP controller metadata.
+ *
+ * @remarks
+ * `@Router(...)` is a lexical React facade over `@fluojs/http` `@Controller(...)`
+ * metadata. URL matching, route grammar, duplicate-route detection, guards,
+ * interceptors, middleware, DTO binding, and request lifecycle remain owned by
+ * the HTTP runtime.
+ *
+ * @param basePath Base path shared by React page handlers declared on the class.
+ * @returns A class decorator that writes HTTP controller metadata plus React router marker metadata.
+ */
+export declare function Router(basePath?: string): ClassDecoratorLike;
+/**
+ * Marks a method as a React page route while writing equivalent HTTP `GET` route metadata.
+ *
+ * @remarks
+ * `@Path(...)` is a lexical React facade over `@fluojs/http` `@Get(...)` metadata.
+ * React page paths inherit the HTTP route grammar: literal segments and full-segment
+ * `:param` placeholders only. The optional `options` value is metadata for future
+ * render integrations; it does not create a React-owned matcher or `routes: []` table.
+ *
+ * @param path Route path relative to the containing `@Router(...)` base path.
+ * @param options Optional render-facing metadata for the future React rendering layer.
+ * @returns A method decorator that writes HTTP `GET` metadata plus React path metadata.
+ */
+export declare function Path(path: string, options?: ReactPathOptions): MethodDecoratorLike;
+/**
+ * Reads React router marker metadata from a router class.
+ *
+ * @param routerToken Router class decorated with `@Router(...)`.
+ * @returns A defensive metadata snapshot, or `undefined` when the class is not a React router.
+ */
+export declare function getReactRouterMetadata(routerToken: Function): ReactRouterMetadata | undefined;
+/**
+ * Reads React render metadata from a router method.
+ *
+ * @param routerToken Router class containing the decorated method.
+ * @param propertyKey Method property key decorated with `@Path(...)`.
+ * @returns A defensive metadata snapshot, or `undefined` when the method is not a React page route.
+ */
+export declare function getReactPathMetadata(routerToken: Function, propertyKey: MetadataPropertyKey): ReactPathMetadata | undefined;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAIxD,KAAK,wBAAwB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC1F,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AACjG,KAAK,sBAAsB,GAAG,CAAC,MAAM,EAAE,QAAQ,KAAK,IAAI,CAAC;AACzD,KAAK,uBAAuB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,UAAU,CAAC,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAC3H,KAAK,kBAAkB,GAAG,wBAAwB,GAAG,sBAAsB,CAAC;AAC5E,KAAK,mBAAmB,GAAG,yBAAyB,GAAG,uBAAuB,CAAC;AAQ/E;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACrC,CAAC;AA4IF;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,QAAQ,SAAK,GAAG,kBAAkB,CAgBxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,mBAAmB,CAsBlF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,QAAQ,GAAG,mBAAmB,GAAG,SAAS,CAI7F;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,QAAQ,EACrB,WAAW,EAAE,mBAAmB,GAC/B,iBAAiB,GAAG,SAAS,CAK/B"}

package/dist/decorators.js

@@ -0,0 +1,194 @@
+import { getStandardMetadataBag } from '@fluojs/core/internal';
+import { Controller, Get } from '@fluojs/http';
+const reactRouterMetadataKey = Symbol.for('fluo.react.router');
+const reactPathMetadataKey = Symbol.for('fluo.react.path');
+const legacyRouterMetadataStore = new WeakMap();
+const legacyPathMetadataStore = new WeakMap();
+
+/**
+ * Additional render-facing metadata stored by `@Path(...)` for the future React renderer.
+ *
+ * @remarks
+ * These options are intentionally runtime-neutral. They are recorded for diagnostics and
+ * later rendering integration without changing HTTP route matching, route grammar, DTO
+ * binding, validation, or request dispatch.
+ */
+
+/**
+ * React router marker metadata written by `@Router(...)`.
+ */
+
+/**
+ * React render metadata written by `@Path(...)`.
+ */
+
+function isStandardDecoratorContext(value) {
+  return typeof value === 'object' && value !== null && Reflect.get(value, 'kind') !== undefined;
+}
+function isStandardClassDecoratorContext(value) {
+  return isStandardDecoratorContext(value) && Reflect.get(value, 'kind') === 'class';
+}
+function isStandardMethodDecoratorContext(value) {
+  return isStandardDecoratorContext(value) && Reflect.get(value, 'kind') === 'method';
+}
+function isMetadataPropertyKey(value) {
+  return typeof value === 'string' || typeof value === 'symbol';
+}
+function cloneReactPathOptions(options) {
+  return options === undefined ? undefined : {
+    ...options
+  };
+}
+function createReactRouterMetadata(basePath) {
+  return {
+    basePath,
+    kind: 'router'
+  };
+}
+function createReactPathMetadata(path, options) {
+  const clonedOptions = cloneReactPathOptions(options);
+  if (clonedOptions === undefined) {
+    return {
+      kind: 'path',
+      path
+    };
+  }
+  return {
+    kind: 'path',
+    options: clonedOptions,
+    path
+  };
+}
+function cloneReactRouterMetadata(metadata) {
+  return createReactRouterMetadata(metadata.basePath);
+}
+function cloneReactPathMetadata(metadata) {
+  return createReactPathMetadata(metadata.path, metadata.options);
+}
+function getMetadataObject(metadata) {
+  return typeof metadata === 'object' && metadata !== null ? metadata : {};
+}
+function defineStandardReactRouterMetadata(metadata, value) {
+  Reflect.set(getMetadataObject(metadata), reactRouterMetadataKey, cloneReactRouterMetadata(value));
+}
+function getStandardReactPathMap(metadata) {
+  const bag = getMetadataObject(metadata);
+  const current = Reflect.get(bag, reactPathMetadataKey);
+  if (current instanceof Map) {
+    return current;
+  }
+  const created = new Map();
+  Reflect.set(bag, reactPathMetadataKey, created);
+  return created;
+}
+function defineStandardReactPathMetadata(metadata, propertyKey, value) {
+  getStandardReactPathMap(metadata).set(propertyKey, cloneReactPathMetadata(value));
+}
+function defineLegacyReactPathMetadata(target, propertyKey, value) {
+  let routeMap = legacyPathMetadataStore.get(target);
+  if (!routeMap) {
+    routeMap = new Map();
+    legacyPathMetadataStore.set(target, routeMap);
+  }
+  routeMap.set(propertyKey, cloneReactPathMetadata(value));
+}
+function isReactRouterMetadata(value) {
+  return typeof value === 'object' && value !== null && Reflect.get(value, 'kind') === 'router' && typeof Reflect.get(value, 'basePath') === 'string';
+}
+function isReactPathOptions(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isReactPathMetadata(value) {
+  const options = typeof value === 'object' && value !== null ? Reflect.get(value, 'options') : undefined;
+  return typeof value === 'object' && value !== null && Reflect.get(value, 'kind') === 'path' && typeof Reflect.get(value, 'path') === 'string' && (options === undefined || isReactPathOptions(options));
+}
+function getStandardReactRouterMetadata(routerToken) {
+  const value = getStandardMetadataBag(routerToken)?.[reactRouterMetadataKey];
+  return isReactRouterMetadata(value) ? value : undefined;
+}
+function getStandardReactPathMetadata(routerToken, propertyKey) {
+  const routeMap = getStandardMetadataBag(routerToken)?.[reactPathMetadataKey];
+  if (!(routeMap instanceof Map)) {
+    return undefined;
+  }
+  const value = routeMap.get(propertyKey);
+  return isReactPathMetadata(value) ? value : undefined;
+}
+
+/**
+ * Marks a class as a React router while writing equivalent HTTP controller metadata.
+ *
+ * @remarks
+ * `@Router(...)` is a lexical React facade over `@fluojs/http` `@Controller(...)`
+ * metadata. URL matching, route grammar, duplicate-route detection, guards,
+ * interceptors, middleware, DTO binding, and request lifecycle remain owned by
+ * the HTTP runtime.
+ *
+ * @param basePath Base path shared by React page handlers declared on the class.
+ * @returns A class decorator that writes HTTP controller metadata plus React router marker metadata.
+ */
+export function Router(basePath = '') {
+  const httpDecorator = Controller(basePath);
+  const metadata = createReactRouterMetadata(basePath);
+  const decorator = (target, context) => {
+    Reflect.apply(httpDecorator, undefined, context === undefined ? [target] : [target, context]);
+    if (isStandardClassDecoratorContext(context)) {
+      defineStandardReactRouterMetadata(context.metadata, metadata);
+      return;
+    }
+    legacyRouterMetadataStore.set(target, cloneReactRouterMetadata(metadata));
+  };
+  return decorator;
+}
+
+/**
+ * Marks a method as a React page route while writing equivalent HTTP `GET` route metadata.
+ *
+ * @remarks
+ * `@Path(...)` is a lexical React facade over `@fluojs/http` `@Get(...)` metadata.
+ * React page paths inherit the HTTP route grammar: literal segments and full-segment
+ * `:param` placeholders only. The optional `options` value is metadata for future
+ * render integrations; it does not create a React-owned matcher or `routes: []` table.
+ *
+ * @param path Route path relative to the containing `@Router(...)` base path.
+ * @param options Optional render-facing metadata for the future React rendering layer.
+ * @returns A method decorator that writes HTTP `GET` metadata plus React path metadata.
+ */
+export function Path(path, options) {
+  const httpDecorator = Get(path);
+  const metadata = createReactPathMetadata(path, options);
+  const decorator = (valueOrTarget, contextOrPropertyKey, descriptor) => {
+    Reflect.apply(httpDecorator, undefined, [valueOrTarget, contextOrPropertyKey, descriptor]);
+    if (isStandardMethodDecoratorContext(contextOrPropertyKey)) {
+      defineStandardReactPathMetadata(contextOrPropertyKey.metadata, contextOrPropertyKey.name, metadata);
+      return;
+    }
+    if (isMetadataPropertyKey(contextOrPropertyKey)) {
+      defineLegacyReactPathMetadata(valueOrTarget, contextOrPropertyKey, metadata);
+    }
+  };
+  return decorator;
+}
+
+/**
+ * Reads React router marker metadata from a router class.
+ *
+ * @param routerToken Router class decorated with `@Router(...)`.
+ * @returns A defensive metadata snapshot, or `undefined` when the class is not a React router.
+ */
+export function getReactRouterMetadata(routerToken) {
+  const metadata = legacyRouterMetadataStore.get(routerToken) ?? getStandardReactRouterMetadata(routerToken);
+  return metadata ? cloneReactRouterMetadata(metadata) : undefined;
+}
+
+/**
+ * Reads React render metadata from a router method.
+ *
+ * @param routerToken Router class containing the decorated method.
+ * @param propertyKey Method property key decorated with `@Path(...)`.
+ * @returns A defensive metadata snapshot, or `undefined` when the method is not a React page route.
+ */
+export function getReactPathMetadata(routerToken, propertyKey) {
+  const metadata = legacyPathMetadataStore.get(routerToken.prototype)?.get(propertyKey) ?? getStandardReactPathMetadata(routerToken, propertyKey);
+  return metadata ? cloneReactPathMetadata(metadata) : undefined;
+}

package/dist/experimental/rsc-diagnostics.d.ts

@@ -0,0 +1,13 @@
+import { type ReactRscEnvironmentOptions, type ReactRscSupportResult } from './rsc-types.js';
+/**
+ * Inspects whether an application-owned RSC runtime and build adapter satisfy the prototype contract.
+ *
+ * @remarks
+ * The experimental policy accepts only exact `19.2.6` versions. Version ranges and canary builds
+ * are rejected because React Flight renderer internals must remain aligned with React and React DOM.
+ *
+ * @param options Installed React versions plus explicit runtime and build-adapter capabilities.
+ * @returns A successful result or stable diagnostics for every unsupported boundary.
+ */
+export declare function inspectReactRscEnvironment(options: ReactRscEnvironmentOptions): ReactRscSupportResult;
+//# sourceMappingURL=rsc-diagnostics.d.ts.map

package/dist/experimental/rsc-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-diagnostics.d.ts","sourceRoot":"","sources":["../../src/experimental/rsc-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,0BAA0B,GAAG,qBAAqB,CAgDrG"}

package/dist/experimental/rsc-diagnostics.js

@@ -0,0 +1,58 @@
+import { REACT_RSC_DIAGNOSTIC_CODES, REACT_RSC_SUPPORTED_VERSION } from './rsc-types.js';
+
+/**
+ * Inspects whether an application-owned RSC runtime and build adapter satisfy the prototype contract.
+ *
+ * @remarks
+ * The experimental policy accepts only exact `19.2.6` versions. Version ranges and canary builds
+ * are rejected because React Flight renderer internals must remain aligned with React and React DOM.
+ *
+ * @param options Installed React versions plus explicit runtime and build-adapter capabilities.
+ * @returns A successful result or stable diagnostics for every unsupported boundary.
+ */
+export function inspectReactRscEnvironment(options) {
+  const diagnostics = [];
+  if (options.reactVersion !== REACT_RSC_SUPPORTED_VERSION) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.unsupportedReactVersion,
+      message: `Experimental RSC requires react@${REACT_RSC_SUPPORTED_VERSION} exactly; received "${options.reactVersion}".`
+    });
+  }
+  if (options.reactDomVersion !== REACT_RSC_SUPPORTED_VERSION) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.unsupportedReactDomVersion,
+      message: `Experimental RSC requires react-dom@${REACT_RSC_SUPPORTED_VERSION} exactly; received "${options.reactDomVersion}".`
+    });
+  }
+  if (options.flightRendererVersion !== REACT_RSC_SUPPORTED_VERSION) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.unsupportedFlightRendererVersion,
+      message: `Experimental RSC requires the Flight renderer at ${REACT_RSC_SUPPORTED_VERSION} exactly; received "${options.flightRendererVersion}".`
+    });
+  }
+  if (!options.runtime.webStreams) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.unsupportedRuntime,
+      message: `Runtime "${options.runtime.name}" cannot host experimental RSC because Web ReadableStream support is unavailable.`
+    });
+  }
+  if (!options.build.clientReferenceManifest) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.missingClientReferenceManifest,
+      message: `Build adapter "${options.build.name}" did not provide a client-reference manifest.`
+    });
+  }
+  if (!options.build.serverClientModuleMap) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.missingServerClientModuleMap,
+      message: `Build adapter "${options.build.name}" did not provide a server-to-client module map.`
+    });
+  }
+  return diagnostics.length === 0 ? {
+    diagnostics: [],
+    ok: true
+  } : {
+    diagnostics,
+    ok: false
+  };
+}

package/dist/experimental/rsc-flight-response.d.ts

@@ -0,0 +1,15 @@
+import { type ReactFlightPayload, type ReactFlightResponse, type ReactFlightResponseOptions } from './rsc-types.js';
+/**
+ * Creates an experimental Flight payload response for an ordinary fluo HTTP handler.
+ *
+ * @remarks
+ * The caller owns Flight encoding. Returning this entry from `@Get(...)`, `@Post(...)`, or
+ * `@Path(...)` keeps route matching, middleware, guards, interceptors, request scopes, and adapter
+ * response writing in the existing fluo HTTP dispatcher. A stream payload is consumed once.
+ *
+ * @param payload Application-encoded Flight bytes, text, or Web `ReadableStream`.
+ * @param options Optional status and headers applied after ordinary route success metadata.
+ * @returns A response entry recognized by the existing fluo HTTP dispatch response policy.
+ */
+export declare function createReactFlightResponse(payload: ReactFlightPayload, options?: ReactFlightResponseOptions): ReactFlightResponse;
+//# sourceMappingURL=rsc-flight-response.d.ts.map

package/dist/experimental/rsc-flight-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-flight-response.d.ts","sourceRoot":"","sources":["../../src/experimental/rsc-flight-response.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EAExB,KAAK,0BAA0B,EAChC,MAAM,gBAAgB,CAAC;AA6ExB;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,CAarB"}

package/dist/experimental/rsc-flight-response.js

@@ -0,0 +1,76 @@
+import { collectReadableStream, pipeReadableStream, throwIfReactRequestAborted } from '../render-stream.js';
+import { REACT_RSC_FLIGHT_CONTENT_TYPE } from './rsc-types.js';
+const responseWriterKey = Symbol.for('fluo.http.responseWriter');
+function cloneHeaders(headers) {
+  const snapshot = {};
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    snapshot[name] = typeof value === 'string' ? value : [...value];
+  }
+  return snapshot;
+}
+function clonePayload(payload) {
+  return payload instanceof Uint8Array ? new Uint8Array(payload) : payload;
+}
+function isBufferedPayload(payload) {
+  return typeof payload === 'string' || payload instanceof Uint8Array;
+}
+function applyFlightResponseMetadata(entry, context) {
+  context.applySuccessResponseMetadata();
+  if (entry.status !== undefined) {
+    context.response.setStatus(entry.status);
+  }
+  for (const [name, value] of Object.entries(entry.headers)) {
+    if (name.toLowerCase() === 'content-type') {
+      continue;
+    }
+    context.response.setHeader(name, typeof value === 'string' ? value : [...value]);
+  }
+  context.response.setHeader('Content-Type', REACT_RSC_FLIGHT_CONTENT_TYPE);
+}
+async function writeReactFlightResponse(entry, context) {
+  throwIfReactRequestAborted(context.requestContext.request);
+  if (isBufferedPayload(entry.payload)) {
+    applyFlightResponseMetadata(entry, context);
+    await context.response.send(entry.payload);
+    return;
+  }
+  const responseStream = context.response.stream;
+  if (!responseStream) {
+    const body = await collectReadableStream(entry.payload, context.requestContext.request);
+    throwIfReactRequestAborted(context.requestContext.request);
+    applyFlightResponseMetadata(entry, context);
+    await context.response.send(body);
+    return;
+  }
+  applyFlightResponseMetadata(entry, context);
+  context.response.committed = true;
+  responseStream.flush?.();
+  await pipeReadableStream(entry.payload, responseStream, context.requestContext.request);
+}
+
+/**
+ * Creates an experimental Flight payload response for an ordinary fluo HTTP handler.
+ *
+ * @remarks
+ * The caller owns Flight encoding. Returning this entry from `@Get(...)`, `@Post(...)`, or
+ * `@Path(...)` keeps route matching, middleware, guards, interceptors, request scopes, and adapter
+ * response writing in the existing fluo HTTP dispatcher. A stream payload is consumed once.
+ *
+ * @param payload Application-encoded Flight bytes, text, or Web `ReadableStream`.
+ * @param options Optional status and headers applied after ordinary route success metadata.
+ * @returns A response entry recognized by the existing fluo HTTP dispatch response policy.
+ */
+export function createReactFlightResponse(payload, options = {}) {
+  const entry = {
+    headers: cloneHeaders(options.headers),
+    payload: clonePayload(payload),
+    ...(options.status !== undefined ? {
+      status: options.status
+    } : {})
+  };
+  Object.defineProperty(entry, responseWriterKey, {
+    enumerable: false,
+    value: context => writeReactFlightResponse(entry, context)
+  });
+  return entry;
+}

package/dist/experimental/rsc-manifest.d.ts

@@ -0,0 +1,13 @@
+import { type ReactRscManifestInput, type ReactRscManifestResult } from './rsc-types.js';
+/**
+ * Validates and snapshots an application-owned RSC client-reference manifest and module map.
+ *
+ * @remarks
+ * This seam is bundler-neutral and does not scan files, generate chunks, load React internals, or
+ * model Server Functions. An application build adapter must provide both explicit inputs.
+ *
+ * @param input Client references and server module mappings produced by the application build.
+ * @returns A defensive manifest snapshot or stable diagnostics for invalid mappings.
+ */
+export declare function createReactRscManifest(input: ReactRscManifestInput): ReactRscManifestResult;
+//# sourceMappingURL=rsc-manifest.d.ts.map

package/dist/experimental/rsc-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-manifest.d.ts","sourceRoot":"","sources":["../../src/experimental/rsc-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAE5B,MAAM,gBAAgB,CAAC;AA4ExB;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAa3F"}

package/dist/experimental/rsc-manifest.js

@@ -0,0 +1,88 @@
+import { REACT_RSC_DIAGNOSTIC_CODES } from './rsc-types.js';
+function cloneClientReferences(clientReferences) {
+  const snapshot = {};
+  Object.setPrototypeOf(snapshot, null);
+  for (const [referenceId, reference] of Object.entries(clientReferences)) {
+    snapshot[referenceId] = {
+      ...(reference.async !== undefined ? {
+        async: reference.async
+      } : {}),
+      chunks: [...reference.chunks],
+      id: reference.id,
+      name: reference.name
+    };
+  }
+  return snapshot;
+}
+function cloneServerClientModuleMap(serverClientModuleMap) {
+  const snapshot = {};
+  Object.setPrototypeOf(snapshot, null);
+  for (const [serverModuleId, exportMappings] of Object.entries(serverClientModuleMap)) {
+    const exportSnapshot = {};
+    Object.setPrototypeOf(exportSnapshot, null);
+    for (const [exportName, clientReferenceId] of Object.entries(exportMappings)) {
+      exportSnapshot[exportName] = clientReferenceId;
+    }
+    snapshot[serverModuleId] = exportSnapshot;
+  }
+  return snapshot;
+}
+function validateManifest(input) {
+  const diagnostics = [];
+  if (Object.keys(input.clientReferences).length === 0) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.emptyClientReferenceManifest,
+      message: 'The experimental RSC client-reference manifest must contain at least one reference.',
+      path: 'clientReferences'
+    });
+  }
+  if (Object.keys(input.serverClientModuleMap).length === 0) {
+    diagnostics.push({
+      code: REACT_RSC_DIAGNOSTIC_CODES.emptyServerClientModuleMap,
+      message: 'The experimental RSC server-to-client module map must contain at least one server module.',
+      path: 'serverClientModuleMap'
+    });
+  }
+  for (const [serverModuleId, exportMappings] of Object.entries(input.serverClientModuleMap)) {
+    for (const [exportName, clientReferenceId] of Object.entries(exportMappings)) {
+      if (Object.hasOwn(input.clientReferences, clientReferenceId)) {
+        continue;
+      }
+      diagnostics.push({
+        code: REACT_RSC_DIAGNOSTIC_CODES.unknownClientReference,
+        message: `Server module "${serverModuleId}" export "${exportName}" maps to unknown client reference "${clientReferenceId}".`,
+        path: `serverClientModuleMap.${serverModuleId}.${exportName}`
+      });
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * Validates and snapshots an application-owned RSC client-reference manifest and module map.
+ *
+ * @remarks
+ * This seam is bundler-neutral and does not scan files, generate chunks, load React internals, or
+ * model Server Functions. An application build adapter must provide both explicit inputs.
+ *
+ * @param input Client references and server module mappings produced by the application build.
+ * @returns A defensive manifest snapshot or stable diagnostics for invalid mappings.
+ */
+export function createReactRscManifest(input) {
+  const diagnostics = validateManifest(input);
+  if (diagnostics.length > 0) {
+    return {
+      diagnostics,
+      ok: false
+    };
+  }
+  const manifest = {
+    clientReferences: cloneClientReferences(input.clientReferences),
+    serverClientModuleMap: cloneServerClientModuleMap(input.serverClientModuleMap)
+  };
+  return {
+    diagnostics: [],
+    manifest,
+    ok: true
+  };
+}