@fluojs/react 0.1.0

package/dist/experimental/server-functions-serialization.js

@@ -0,0 +1,158 @@
+const blockedObjectKeys = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** Result of parsing an untrusted value into the Server Function serialization subset. */
+
+function isPlainRecord(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function failure(path, reason) {
+  return {
+    ok: false,
+    path,
+    reason
+  };
+}
+function parseArray(value, context) {
+  if (context.ancestors.has(value)) {
+    return failure(context.path, 'Circular arrays are not serializable.');
+  }
+  context.ancestors.add(value);
+  const parsed = [];
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      context.ancestors.delete(value);
+      return failure(`${context.path}[${String(index)}]`, 'Sparse arrays are not serializable.');
+    }
+    const item = value[index];
+    const result = parseValue(item, {
+      ancestors: context.ancestors,
+      depth: context.depth + 1,
+      maxDepth: context.maxDepth,
+      path: `${context.path}[${String(index)}]`
+    });
+    if (!result.ok) {
+      context.ancestors.delete(value);
+      return result;
+    }
+    parsed.push(result.value);
+  }
+  context.ancestors.delete(value);
+  return {
+    ok: true,
+    value: Object.freeze(parsed)
+  };
+}
+function parseRecord(value, context) {
+  if (context.ancestors.has(value)) {
+    return failure(context.path, 'Circular objects are not serializable.');
+  }
+  if (Reflect.ownKeys(value).length !== Object.keys(value).length) {
+    return failure(context.path, 'Symbol and non-enumerable properties are not serializable.');
+  }
+  context.ancestors.add(value);
+  const parsed = {};
+  Object.setPrototypeOf(parsed, null);
+  for (const [key, item] of Object.entries(value)) {
+    if (blockedObjectKeys.has(key)) {
+      context.ancestors.delete(value);
+      return failure(`${context.path}.${key}`, 'Prototype-sensitive object keys are not allowed.');
+    }
+    const result = parseValue(item, {
+      ancestors: context.ancestors,
+      depth: context.depth + 1,
+      maxDepth: context.maxDepth,
+      path: `${context.path}.${key}`
+    });
+    if (!result.ok) {
+      context.ancestors.delete(value);
+      return result;
+    }
+    parsed[key] = result.value;
+  }
+  context.ancestors.delete(value);
+  return {
+    ok: true,
+    value: Object.freeze(parsed)
+  };
+}
+function parseValue(value, context) {
+  if (context.depth > context.maxDepth) {
+    return failure(context.path, `Serialization depth exceeds ${String(context.maxDepth)}.`);
+  }
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return {
+      ok: true,
+      value
+    };
+  }
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? {
+      ok: true,
+      value
+    } : failure(context.path, 'Only finite numbers are serializable.');
+  }
+  if (Array.isArray(value)) {
+    return parseArray(value, context);
+  }
+  if (isPlainRecord(value)) {
+    return parseRecord(value, context);
+  }
+  return failure(context.path, 'Only JSON-compatible primitives, arrays, and plain objects are serializable.');
+}
+
+/**
+ * Parses an untrusted argument list into an immutable JSON-compatible snapshot.
+ *
+ * @param value Unknown request argument value.
+ * @param maxDepth Maximum supported nesting depth.
+ * @returns A parsed argument list or a deterministic path and reason.
+ */
+export function parseReactServerFunctionArguments(value, maxDepth) {
+  if (!Array.isArray(value)) {
+    return failure('args', 'Server Function arguments must be an array.');
+  }
+  const parsed = parseArray(value, {
+    ancestors: new Set(),
+    depth: 0,
+    maxDepth,
+    path: 'args'
+  });
+  if (!parsed.ok) {
+    return parsed;
+  }
+  return Array.isArray(parsed.value) ? {
+    ok: true,
+    value: parsed.value
+  } : failure('args', 'Server Function arguments must be an array.');
+}
+
+/**
+ * Parses one untrusted action result into an immutable JSON-compatible snapshot.
+ *
+ * @param value Unknown action result.
+ * @param maxDepth Maximum supported nesting depth.
+ * @returns A parsed result or a deterministic path and reason.
+ */
+export function parseReactServerFunctionValue(value, maxDepth) {
+  return parseValue(value, {
+    ancestors: new Set(),
+    depth: 0,
+    maxDepth,
+    path: 'result'
+  });
+}
+
+/**
+ * Measures the UTF-8 JSON representation of an already parsed Server Function value.
+ *
+ * @param value JSON-compatible value produced by this module.
+ * @returns Encoded byte length.
+ */
+export function measureReactServerFunctionValue(value) {
+  const serialized = JSON.stringify(value);
+  return serialized === undefined ? 0 : new TextEncoder().encode(serialized).byteLength;
+}

package/dist/experimental/server-functions-server.d.ts

@@ -0,0 +1,14 @@
+import { type ReactServerFunctionRegistry, type ReactServerFunctionRegistryOptions } from './server-functions-types.js';
+/**
+ * Creates an experimental signed Server Function registry for an application-owned fluo POST route.
+ *
+ * @remarks
+ * The returned registry does not register a router. Mount `invoke(context)` in an ordinary
+ * `@Controller(...)` and `@Post(...)` method so fluo middleware, guards, interceptors, request
+ * scopes, observers, and error serialization remain authoritative.
+ *
+ * @param options Explicit actions, allowed origins, Web Crypto provider, HMAC secret, and limits.
+ * @returns A registry that issues signed references and invokes validated action calls.
+ */
+export declare function createReactServerFunctionRegistry(options: ReactServerFunctionRegistryOptions): ReactServerFunctionRegistry;
+//# sourceMappingURL=server-functions-server.d.ts.map

package/dist/experimental/server-functions-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-server.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-server.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,kCAAkC,EACxC,MAAM,6BAA6B,CAAC;AAwGrC;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,kCAAkC,GAC1C,2BAA2B,CA4D7B"}

package/dist/experimental/server-functions-server.js

@@ -0,0 +1,176 @@
+import { HttpException } from '@fluojs/http';
+import { createReactServerFunctionRegistryConfiguration } from './server-functions-configuration.js';
+import { ReactServerFunctionConfigurationError } from './server-functions-errors.js';
+import { createReactServerFunctionReferenceSigner } from './server-functions-reference.js';
+import { measureReactServerFunctionValue, parseReactServerFunctionArguments, parseReactServerFunctionValue } from './server-functions-serialization.js';
+import { REACT_SERVER_FUNCTION_ERROR_CODES, REACT_SERVER_FUNCTION_REQUEST_HEADER } from './server-functions-types.js';
+function getHeader(context, name) {
+  const target = name.toLowerCase();
+  for (const [headerName, value] of Object.entries(context.request.headers)) {
+    if (headerName.toLowerCase() === target && typeof value === 'string') {
+      return value;
+    }
+  }
+  return undefined;
+}
+function transportError(options) {
+  return new HttpException(options.status, options.message, {
+    code: options.code,
+    ...(options.meta === undefined ? {} : {
+      meta: options.meta
+    })
+  });
+}
+function measureRequestBody(context) {
+  if (context.request.rawBody !== undefined) {
+    return context.request.rawBody.byteLength;
+  }
+  try {
+    const serialized = JSON.stringify(context.request.body);
+    return serialized === undefined ? undefined : new TextEncoder().encode(serialized).byteLength;
+  } catch (error) {
+    if (error instanceof Error) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+function validateTransport(context, configuration) {
+  const bodySize = measureRequestBody(context);
+  if (bodySize !== undefined && bodySize > configuration.maxBodyBytes) {
+    throw transportError({
+      code: REACT_SERVER_FUNCTION_ERROR_CODES.payloadTooLarge,
+      message: 'Server Function request body exceeds the configured byte limit.',
+      meta: {
+        maxBodyBytes: configuration.maxBodyBytes
+      },
+      status: 413
+    });
+  }
+  const contentType = getHeader(context, 'content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+  if (contentType !== 'application/json') {
+    throw transportError({
+      code: REACT_SERVER_FUNCTION_ERROR_CODES.unsupportedMediaType,
+      message: 'Server Function requests require Content-Type application/json.',
+      status: 415
+    });
+  }
+  if (getHeader(context, REACT_SERVER_FUNCTION_REQUEST_HEADER) !== '1') {
+    throw transportError({
+      code: REACT_SERVER_FUNCTION_ERROR_CODES.csrfRejected,
+      message: 'Server Function request marker is missing or invalid.',
+      status: 403
+    });
+  }
+  const origin = getHeader(context, 'origin');
+  if (origin === undefined || !configuration.allowedOrigins.has(origin)) {
+    throw transportError({
+      code: REACT_SERVER_FUNCTION_ERROR_CODES.originRejected,
+      message: 'Server Function request origin is not allowed.',
+      status: 403
+    });
+  }
+}
+function isRequestRecord(value) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function parseRequestBody(body) {
+  if (!isRequestRecord(body)) {
+    throw transportError({
+      code: REACT_SERVER_FUNCTION_ERROR_CODES.invalidRequest,
+      message: 'Server Function request body must be a JSON object.',
+      status: 400
+    });
+  }
+  const keys = Object.keys(body).sort();
+  if (keys.length !== 2 || keys[0] !== 'action' || keys[1] !== 'args' || typeof body.action !== 'string') {
+    throw transportError({
+      code: REACT_SERVER_FUNCTION_ERROR_CODES.invalidRequest,
+      message: 'Server Function request body must contain only string action and array args fields.',
+      status: 400
+    });
+  }
+  return {
+    action: body.action,
+    args: body.args
+  };
+}
+
+/**
+ * Creates an experimental signed Server Function registry for an application-owned fluo POST route.
+ *
+ * @remarks
+ * The returned registry does not register a router. Mount `invoke(context)` in an ordinary
+ * `@Controller(...)` and `@Post(...)` method so fluo middleware, guards, interceptors, request
+ * scopes, observers, and error serialization remain authoritative.
+ *
+ * @param options Explicit actions, allowed origins, Web Crypto provider, HMAC secret, and limits.
+ * @returns A registry that issues signed references and invokes validated action calls.
+ */
+export function createReactServerFunctionRegistry(options) {
+  const configuration = createReactServerFunctionRegistryConfiguration(options);
+  const signer = createReactServerFunctionReferenceSigner(options.crypto, options.secret);
+  return Object.freeze({
+    async createReference(actionId) {
+      if (!Object.hasOwn(configuration.actions, actionId)) {
+        throw new ReactServerFunctionConfigurationError(`Cannot create a Server Function reference for unknown action "${actionId}".`);
+      }
+      return signer.createReference(actionId);
+    },
+    async invoke(context) {
+      validateTransport(context, configuration);
+      const request = parseRequestBody(context.request.body);
+      const actionId = await signer.verifyReference(request.action);
+      const handler = actionId === undefined ? undefined : configuration.actions[actionId];
+      if (handler === undefined) {
+        throw transportError({
+          code: REACT_SERVER_FUNCTION_ERROR_CODES.actionNotFound,
+          message: 'Server Function action was not found.',
+          status: 404
+        });
+      }
+      const args = parseReactServerFunctionArguments(request.args, configuration.maxSerializationDepth);
+      if (!args.ok) {
+        throw transportError({
+          code: REACT_SERVER_FUNCTION_ERROR_CODES.argumentSerializationFailed,
+          message: 'Server Function arguments are not safely serializable.',
+          meta: {
+            path: args.path,
+            reason: args.reason
+          },
+          status: 400
+        });
+      }
+      const result = parseReactServerFunctionValue(await handler(args.value, context), configuration.maxSerializationDepth);
+      if (!result.ok) {
+        throw transportError({
+          code: REACT_SERVER_FUNCTION_ERROR_CODES.resultSerializationFailed,
+          message: 'Server Function result is not safely serializable.',
+          meta: {
+            path: result.path,
+            reason: result.reason
+          },
+          status: 500
+        });
+      }
+      const resultBytes = measureReactServerFunctionValue(result.value);
+      if (resultBytes > configuration.maxResultBytes) {
+        throw transportError({
+          code: REACT_SERVER_FUNCTION_ERROR_CODES.resultTooLarge,
+          message: 'Server Function result exceeds the configured byte limit.',
+          meta: {
+            maxResultBytes: configuration.maxResultBytes
+          },
+          status: 500
+        });
+      }
+      return {
+        result: result.value
+      };
+    }
+  });
+}

package/dist/experimental/server-functions-types.d.ts

@@ -0,0 +1,86 @@
+import type { MaybePromise } from '@fluojs/core';
+import type { RequestContext } from '@fluojs/http';
+/** Header required on experimental Server Function POST requests to force a non-simple request. */
+export declare const REACT_SERVER_FUNCTION_REQUEST_HEADER = "x-fluo-react-action";
+/** Stable error codes emitted by the experimental Server Function transport boundary. */
+export declare const REACT_SERVER_FUNCTION_ERROR_CODES: {
+    readonly actionNotFound: "REACT_SERVER_FUNCTION_ACTION_NOT_FOUND";
+    readonly argumentSerializationFailed: "REACT_SERVER_FUNCTION_ARGUMENT_SERIALIZATION_FAILED";
+    readonly csrfRejected: "REACT_SERVER_FUNCTION_CSRF_REJECTED";
+    readonly invalidRequest: "REACT_SERVER_FUNCTION_INVALID_REQUEST";
+    readonly originRejected: "REACT_SERVER_FUNCTION_ORIGIN_REJECTED";
+    readonly payloadTooLarge: "REACT_SERVER_FUNCTION_PAYLOAD_TOO_LARGE";
+    readonly resultSerializationFailed: "REACT_SERVER_FUNCTION_RESULT_SERIALIZATION_FAILED";
+    readonly resultTooLarge: "REACT_SERVER_FUNCTION_RESULT_TOO_LARGE";
+    readonly unsupportedMediaType: "REACT_SERVER_FUNCTION_UNSUPPORTED_MEDIA_TYPE";
+};
+/** Machine-readable code emitted by the experimental Server Function transport. */
+export type ReactServerFunctionErrorCode = (typeof REACT_SERVER_FUNCTION_ERROR_CODES)[keyof typeof REACT_SERVER_FUNCTION_ERROR_CODES];
+/** JSON-compatible value accepted as a Server Function argument or result. */
+export type ReactServerFunctionValue = null | boolean | number | string | readonly ReactServerFunctionValue[] | {
+    readonly [key: string]: ReactServerFunctionValue;
+};
+/** Opaque, integrity-protected reference sent to a Server Function client. */
+export type ReactServerFunctionReference = {
+    /** Versioned signed reference value included in the action request body. */
+    readonly value: string;
+};
+/** Server-side action executed after transport and identity validation. */
+export type ReactServerFunctionHandler = (args: readonly ReactServerFunctionValue[], context: RequestContext) => MaybePromise<ReactServerFunctionValue>;
+/** Options for creating an integrity-protected Server Function registry. */
+export type ReactServerFunctionRegistryOptions = {
+    /** Stable action ids mapped to server-only handlers. */
+    readonly actions: Readonly<Record<string, ReactServerFunctionHandler>>;
+    /** Exact HTTP(S) origins allowed to invoke the action endpoint. */
+    readonly allowedOrigins: readonly string[];
+    /** Runtime Web Crypto provider used for HMAC-SHA-256 reference integrity. */
+    readonly crypto: Pick<Crypto, 'subtle'>;
+    /** Maximum accepted request body size in bytes. Defaults to 64 KiB. */
+    readonly maxBodyBytes?: number;
+    /** Maximum serialized action result size in bytes. Defaults to 1 MiB. */
+    readonly maxResultBytes?: number;
+    /** Maximum nested argument or result depth. Defaults to 32. */
+    readonly maxSerializationDepth?: number;
+    /** Application-owned HMAC secret containing at least 32 bytes. */
+    readonly secret: Uint8Array;
+};
+/** Successful value returned from a Server Function endpoint handler. */
+export type ReactServerFunctionResponse = {
+    /** Validated JSON-compatible action result. */
+    readonly result: ReactServerFunctionValue;
+};
+/** Registry mounted by an application-owned ordinary fluo HTTP POST controller. */
+export type ReactServerFunctionRegistry = {
+    /**
+     * Creates an integrity-protected client reference for one registered action.
+     *
+     * @param actionId Stable registered action id.
+     * @returns An opaque reference suitable for client transport.
+     */
+    readonly createReference: (actionId: string) => Promise<ReactServerFunctionReference>;
+    /**
+     * Validates and invokes one action from the active fluo request context.
+     *
+     * @param context Existing request context supplied to an ordinary HTTP controller method.
+     * @returns A JSON-compatible action response for normal dispatcher serialization.
+     */
+    readonly invoke: (context: RequestContext) => Promise<ReactServerFunctionResponse>;
+};
+/** Minimal application-owned fetch seam used by the experimental client callable. */
+export type ReactServerFunctionFetch = (input: string, init: RequestInit) => Promise<Response>;
+/** Options for creating one client-side callable Server Function reference. */
+export type ReactServerFunctionClientOptions = {
+    /** Explicit fluo HTTP endpoint that owns Server Function POST dispatch. */
+    readonly endpoint: string;
+    /** Application-owned fetch implementation used to perform the HTTP request. */
+    readonly fetch: ReactServerFunctionFetch;
+    /** Maximum accepted response body size in bytes. Defaults to 1 MiB. */
+    readonly maxResponseBytes?: number;
+    /** Maximum nested argument or result depth. Defaults to 32. */
+    readonly maxSerializationDepth?: number;
+    /** Signed reference issued by the matching server registry. */
+    readonly reference: ReactServerFunctionReference;
+};
+/** Callable client proxy that transports serializable arguments to one explicit action endpoint. */
+export type ReactServerFunctionClient = (...args: readonly ReactServerFunctionValue[]) => Promise<ReactServerFunctionValue>;
+//# sourceMappingURL=server-functions-types.d.ts.map

package/dist/experimental/server-functions-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-types.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,mGAAmG;AACnG,eAAO,MAAM,oCAAoC,wBAAwB,CAAC;AAE1E,yFAAyF;AACzF,eAAO,MAAM,iCAAiC;;;;;;;;;;CAUpC,CAAC;AAEX,mFAAmF;AACnF,MAAM,MAAM,4BAA4B,GACtC,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,OAAO,iCAAiC,CAAC,CAAC;AAE7F,8EAA8E;AAC9E,MAAM,MAAM,wBAAwB,GAChC,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,wBAAwB,EAAE,GACnC;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,wBAAwB,CAAA;CAAE,CAAC;AAEzD,8EAA8E;AAC9E,MAAM,MAAM,4BAA4B,GAAG;IACzC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,0BAA0B,GAAG,CACvC,IAAI,EAAE,SAAS,wBAAwB,EAAE,EACzC,OAAO,EAAE,cAAc,KACpB,YAAY,CAAC,wBAAwB,CAAC,CAAC;AAE5C,4EAA4E;AAC5E,MAAM,MAAM,kCAAkC,GAAG;IAC/C,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC;IACvE,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACxC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,2BAA2B,GAAG;IACxC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,2BAA2B,GAAG;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACtF;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACpF,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE/F,+EAA+E;AAC/E,MAAM,MAAM,gCAAgC,GAAG;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,4BAA4B,CAAC;CAClD,CAAC;AAEF,oGAAoG;AACpG,MAAM,MAAM,yBAAyB,GAAG,CACtC,GAAG,IAAI,EAAE,SAAS,wBAAwB,EAAE,KACzC,OAAO,CAAC,wBAAwB,CAAC,CAAC"}

package/dist/experimental/server-functions-types.js

@@ -0,0 +1,35 @@
+/** Header required on experimental Server Function POST requests to force a non-simple request. */
+export const REACT_SERVER_FUNCTION_REQUEST_HEADER = 'x-fluo-react-action';
+
+/** Stable error codes emitted by the experimental Server Function transport boundary. */
+export const REACT_SERVER_FUNCTION_ERROR_CODES = {
+  actionNotFound: 'REACT_SERVER_FUNCTION_ACTION_NOT_FOUND',
+  argumentSerializationFailed: 'REACT_SERVER_FUNCTION_ARGUMENT_SERIALIZATION_FAILED',
+  csrfRejected: 'REACT_SERVER_FUNCTION_CSRF_REJECTED',
+  invalidRequest: 'REACT_SERVER_FUNCTION_INVALID_REQUEST',
+  originRejected: 'REACT_SERVER_FUNCTION_ORIGIN_REJECTED',
+  payloadTooLarge: 'REACT_SERVER_FUNCTION_PAYLOAD_TOO_LARGE',
+  resultSerializationFailed: 'REACT_SERVER_FUNCTION_RESULT_SERIALIZATION_FAILED',
+  resultTooLarge: 'REACT_SERVER_FUNCTION_RESULT_TOO_LARGE',
+  unsupportedMediaType: 'REACT_SERVER_FUNCTION_UNSUPPORTED_MEDIA_TYPE'
+};
+
+/** Machine-readable code emitted by the experimental Server Function transport. */
+
+/** JSON-compatible value accepted as a Server Function argument or result. */
+
+/** Opaque, integrity-protected reference sent to a Server Function client. */
+
+/** Server-side action executed after transport and identity validation. */
+
+/** Options for creating an integrity-protected Server Function registry. */
+
+/** Successful value returned from a Server Function endpoint handler. */
+
+/** Registry mounted by an application-owned ordinary fluo HTTP POST controller. */
+
+/** Minimal application-owned fetch seam used by the experimental client callable. */
+
+/** Options for creating one client-side callable Server Function reference. */
+
+/** Callable client proxy that transports serializable arguments to one explicit action endpoint. */

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { Path, Router, getReactPathMetadata, getReactRouterMetadata, } from './decorators.js';
+export type { ReactPathMetadata, ReactPathOptions, ReactRouterMetadata } from './decorators.js';
+export { ReactModule } from './module.js';
+export type { ReactModuleOptions } from './module.js';
+export { renderReactResponse } from './render.js';
+export type { ReactReadableStream, ReactReadableStreamRenderOptions, ReactReadableStreamRenderer, ReactRenderContext, RenderReactResponseOptions, } from './render.js';
+export { createReactServerEntry } from './server-entry.js';
+export type { ReactAssetMap, ReactBootstrapAsset, ReactBootstrapScriptDescriptor, ReactRecoverableErrorContext, ReactRecoverableErrorHandler, ReactServerEntry, ReactServerEntryHeaders, ReactServerEntryOptions, } from './server-entry.js';
+export type { ReactScaffoldPhase } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,MAAM,EACN,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,mBAAmB,EACnB,gCAAgC,EAChC,2BAA2B,EAC3B,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,8BAA8B,EAC9B,4BAA4B,EAC5B,4BAA4B,EAC5B,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { Path, Router, getReactPathMetadata, getReactRouterMetadata } from './decorators.js';
+export { ReactModule } from './module.js';
+export { renderReactResponse } from './render.js';
+export { createReactServerEntry } from './server-entry.js';

package/dist/module.d.ts

@@ -0,0 +1,40 @@
+import { type Constructor, type Token } from '@fluojs/core';
+import type { Provider } from '@fluojs/di';
+import type { MiddlewareLike } from '@fluojs/http';
+import { type ModuleType } from '@fluojs/runtime';
+/**
+ * Options for registering React routers through the fluo module graph.
+ */
+export type ReactModuleOptions = {
+    /** React router or HTTP controller classes added to the existing HTTP handler source path. */
+    readonly controllers: readonly Constructor[];
+    /** Provider tokens exported from this dynamic React module. */
+    readonly exports?: readonly Token[];
+    /** Modules whose exported providers are visible to the registered React routers. */
+    readonly imports?: readonly ModuleType[];
+    /** Module-level middleware applied by the existing HTTP dispatcher to this module's routes. */
+    readonly middleware?: readonly MiddlewareLike[];
+    /** Providers local to this dynamic React module and visible to registered routers. */
+    readonly providers?: readonly Provider[];
+};
+/**
+ * Runtime-neutral module facade for registering React routers in fluo applications.
+ *
+ * @remarks
+ * `ReactModule.forRoot(...)` registers React routers through the same module/controller
+ * metadata consumed by `@fluojs/runtime` and `@fluojs/http`. It does not install a
+ * React-owned matcher, renderer, Vite integration, React Server Components hooks, or
+ * server functions. The stable root package owns runtime-neutral SSR contracts; future
+ * `@fluojs/react/vite`, `@fluojs/react/client`, and `@fluojs/react/experimental/rsc`
+ * subpaths own build assets, browser navigation, and RSC/server-function experiments.
+ */
+export declare class ReactModule {
+    /**
+     * Registers React routers and companion module metadata through the existing HTTP path.
+     *
+     * @param options React router controllers plus ordinary module imports, providers, exports, and middleware.
+     * @returns A runtime module type suitable for `@Module({ imports: [...] })`.
+     */
+    static forRoot(options: ReactModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAuC,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEvF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8FAA8F;IAC9F,QAAQ,CAAC,WAAW,EAAE,SAAS,WAAW,EAAE,CAAC;IAC7C,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,qBACa,WAAW;IACtB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;CAaxD"}

package/dist/module.js

@@ -0,0 +1,58 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Module } from '@fluojs/core';
+import { defineModule } from '@fluojs/runtime';
+
+/**
+ * Options for registering React routers through the fluo module graph.
+ */
+let _ReactModule;
+/**
+ * Runtime-neutral module facade for registering React routers in fluo applications.
+ *
+ * @remarks
+ * `ReactModule.forRoot(...)` registers React routers through the same module/controller
+ * metadata consumed by `@fluojs/runtime` and `@fluojs/http`. It does not install a
+ * React-owned matcher, renderer, Vite integration, React Server Components hooks, or
+ * server functions. The stable root package owns runtime-neutral SSR contracts; future
+ * `@fluojs/react/vite`, `@fluojs/react/client`, and `@fluojs/react/experimental/rsc`
+ * subpaths own build assets, browser navigation, and RSC/server-function experiments.
+ */
+class ReactModule {
+  static {
+    [_ReactModule, _initClass] = _applyDecs(this, [Module({})], []).c;
+  }
+  /**
+   * Registers React routers and companion module metadata through the existing HTTP path.
+   *
+   * @param options React router controllers plus ordinary module imports, providers, exports, and middleware.
+   * @returns A runtime module type suitable for `@Module({ imports: [...] })`.
+   */
+  static forRoot(options) {
+    class ReactRootModule extends _ReactModule {}
+    const definition = {
+      controllers: [...options.controllers],
+      ...(options.exports ? {
+        exports: [...options.exports]
+      } : {}),
+      ...(options.imports ? {
+        imports: [...options.imports]
+      } : {}),
+      ...(options.middleware ? {
+        middleware: [...options.middleware]
+      } : {}),
+      ...(options.providers ? {
+        providers: [...options.providers]
+      } : {})
+    };
+    return defineModule(ReactRootModule, definition);
+  }
+  static {
+    _initClass();
+  }
+}
+export { _ReactModule as ReactModule };

package/dist/render-stream.d.ts

@@ -0,0 +1,27 @@
+import { type FrameworkRequest, type FrameworkResponseStream } from '@fluojs/http';
+/** Minimal request abort surface used while React Web Streams are read. */
+export type ReactAbortSource = Pick<FrameworkRequest, 'isAborted' | 'signal'>;
+/**
+ * Throws when a request has been aborted through either supported HTTP abort surface.
+ *
+ * @param source Request abort source exposed by the active fluo request.
+ */
+export declare function throwIfReactRequestAborted(source: ReactAbortSource): void;
+/**
+ * Collects a React HTML stream for buffered hosts without committing partial bodies after abort.
+ *
+ * @param stream React Web Stream to collect.
+ * @param abortSource Request abort source checked before buffered response metadata is applied.
+ * @returns Fully collected HTML bytes.
+ */
+export declare function collectReadableStream(stream: ReadableStream<Uint8Array>, abortSource: ReactAbortSource): Promise<Uint8Array>;
+/**
+ * Pipes a React HTML stream into an already committed streaming response until close or abort.
+ *
+ * @param stream React Web Stream to pipe.
+ * @param target Response stream that receives HTML chunks.
+ * @param abortSource Request abort source checked between chunks.
+ * @returns A promise that resolves when piping stops and the target is closed.
+ */
+export declare function pipeReadableStream(stream: ReadableStream<Uint8Array>, target: FrameworkResponseStream, abortSource: ReactAbortSource): Promise<void>;
+//# sourceMappingURL=render-stream.d.ts.map

package/dist/render-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-stream.d.ts","sourceRoot":"","sources":["../src/render-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAOxG,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAC;AA+B9E;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAIzE;AAyBD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAuCrB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,MAAM,EAAE,uBAAuB,EAC/B,WAAW,EAAE,gBAAgB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgCf"}