@fluojs/react 0.1.0

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

@@ -0,0 +1,118 @@
+/** Exact React, React DOM, and Flight renderer version supported by the experimental RSC contract. */
+export declare const REACT_RSC_SUPPORTED_VERSION = "19.2.6";
+/** HTTP content type written for experimental React Flight payload responses. */
+export declare const REACT_RSC_FLIGHT_CONTENT_TYPE = "text/x-component; charset=utf-8";
+/** Stable diagnostic codes emitted by the experimental RSC compatibility and manifest checks. */
+export declare const REACT_RSC_DIAGNOSTIC_CODES: {
+    readonly emptyClientReferenceManifest: "react-rsc-empty-client-reference-manifest";
+    readonly emptyServerClientModuleMap: "react-rsc-empty-server-client-module-map";
+    readonly missingClientReferenceManifest: "react-rsc-missing-client-reference-manifest";
+    readonly missingServerClientModuleMap: "react-rsc-missing-server-client-module-map";
+    readonly unknownClientReference: "react-rsc-unknown-client-reference";
+    readonly unsupportedFlightRendererVersion: "react-rsc-unsupported-flight-renderer-version";
+    readonly unsupportedReactDomVersion: "react-rsc-unsupported-react-dom-version";
+    readonly unsupportedReactVersion: "react-rsc-unsupported-react-version";
+    readonly unsupportedRuntime: "react-rsc-unsupported-runtime";
+};
+/** Machine-readable diagnostic code produced by the experimental RSC contract. */
+export type ReactRscDiagnosticCode = (typeof REACT_RSC_DIAGNOSTIC_CODES)[keyof typeof REACT_RSC_DIAGNOSTIC_CODES];
+/** Actionable compatibility or build diagnostic produced instead of an expected configuration throw. */
+export type ReactRscDiagnostic = {
+    /** Stable machine-readable diagnostic code. */
+    readonly code: ReactRscDiagnosticCode;
+    /** Human-readable explanation of the unsupported condition. */
+    readonly message: string;
+    /** Build manifest path associated with the diagnostic, when applicable. */
+    readonly path?: string;
+};
+/** Runtime capabilities required by the experimental Flight response transport. */
+export type ReactRscRuntimeCapabilities = {
+    /** Application-facing runtime name included in unsupported-runtime diagnostics. */
+    readonly name: string;
+    /** Whether the runtime provides Web `ReadableStream` support. */
+    readonly webStreams: boolean;
+};
+/** Build-adapter capabilities required to connect RSC module graphs explicitly. */
+export type ReactRscBuildCapabilities = {
+    /** Whether the build adapter produced a client-reference manifest. */
+    readonly clientReferenceManifest: boolean;
+    /** Application-facing build adapter name included in diagnostics. */
+    readonly name: string;
+    /** Whether the build adapter produced an explicit server-to-client module map. */
+    readonly serverClientModuleMap: boolean;
+};
+/** Environment inputs checked before an application enables the experimental RSC path. */
+export type ReactRscEnvironmentOptions = {
+    /** Explicit build-adapter capabilities. */
+    readonly build: ReactRscBuildCapabilities;
+    /** Installed Flight renderer version, such as `react-server-dom-webpack`. */
+    readonly flightRendererVersion: string;
+    /** Installed `react-dom` version. */
+    readonly reactDomVersion: string;
+    /** Installed `react` version. */
+    readonly reactVersion: string;
+    /** Explicit runtime capabilities. */
+    readonly runtime: ReactRscRuntimeCapabilities;
+};
+/** Result of inspecting one experimental RSC runtime and build environment. */
+export type ReactRscSupportResult = {
+    readonly diagnostics: readonly [];
+    readonly ok: true;
+} | {
+    readonly diagnostics: readonly ReactRscDiagnostic[];
+    readonly ok: false;
+};
+/** Bundler-produced metadata for one client module export referenced by a Flight payload. */
+export type ReactRscClientReference = {
+    /** Whether the referenced module is loaded asynchronously. */
+    readonly async?: boolean;
+    /** Build chunks required to load the client reference. */
+    readonly chunks: readonly string[];
+    /** Bundler-specific module id consumed by the application-owned Flight renderer. */
+    readonly id: string;
+    /** Export name consumed from the referenced client module. */
+    readonly name: string;
+};
+/** Client-reference metadata keyed by an application-owned stable reference id. */
+export type ReactRscClientReferenceManifest = Readonly<Record<string, ReactRscClientReference>>;
+/** Server module exports mapped to keys in the client-reference manifest. */
+export type ReactRscServerClientModuleMap = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** Build output accepted by `createReactRscManifest(...)`. */
+export type ReactRscManifestInput = {
+    /** Client references produced by the application build adapter. */
+    readonly clientReferences: ReactRscClientReferenceManifest;
+    /** Server module exports mapped to client-reference keys. */
+    readonly serverClientModuleMap: ReactRscServerClientModuleMap;
+};
+/** Defensive RSC module graph snapshot passed to an application-owned Flight renderer. */
+export type ReactRscManifest = ReactRscManifestInput;
+/** Result of validating and snapshotting an experimental RSC manifest. */
+export type ReactRscManifestResult = {
+    readonly diagnostics: readonly [];
+    readonly manifest: ReactRscManifest;
+    readonly ok: true;
+} | {
+    readonly diagnostics: readonly ReactRscDiagnostic[];
+    readonly ok: false;
+};
+/** Encoded React Flight payload accepted by the experimental HTTP response helper. */
+export type ReactFlightPayload = string | Uint8Array | ReadableStream<Uint8Array>;
+/** Additional HTTP headers applied to an experimental Flight response. */
+export type ReactFlightResponseHeaders = Readonly<Record<string, string | readonly string[]>>;
+/** Options applied after ordinary fluo route success metadata for a Flight response. */
+export type ReactFlightResponseOptions = {
+    /** Additional response headers; the Flight `Content-Type` remains fixed. */
+    readonly headers?: ReactFlightResponseHeaders;
+    /** HTTP status overriding ordinary route success metadata. */
+    readonly status?: number;
+};
+/** Response entry returned from an ordinary fluo HTTP handler to emit an encoded Flight payload. */
+export type ReactFlightResponse = {
+    /** Additional response headers applied before the payload commits. */
+    readonly headers: ReactFlightResponseHeaders;
+    /** Encoded Flight payload or one-shot Flight stream. */
+    readonly payload: ReactFlightPayload;
+    /** Optional status overriding ordinary route success metadata. */
+    readonly status?: number;
+};
+//# sourceMappingURL=rsc-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-types.d.ts","sourceRoot":"","sources":["../../src/experimental/rsc-types.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,eAAO,MAAM,2BAA2B,WAAW,CAAC;AAEpD,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,oCAAoC,CAAC;AAE/E,iGAAiG;AACjG,eAAO,MAAM,0BAA0B;;;;;;;;;;CAU7B,CAAC;AAEX,kFAAkF;AAClF,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;AAE/E,wGAAwG;AACxG,MAAM,MAAM,kBAAkB,GAAG;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,2BAA2B,GAAG;IACxC,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,yBAAyB,GAAG;IACtC,sEAAsE;IACtE,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,0BAA0B,GAAG;IACvC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAC;IAC1C,6EAA6E;IAC7E,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,iCAAiC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;CAC/C,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhF,6FAA6F;AAC7F,MAAM,MAAM,uBAAuB,GAAG;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,mFAAmF;AACnF,MAAM,MAAM,+BAA+B,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC;AAEhG,6EAA6E;AAC7E,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvG,8DAA8D;AAC9D,MAAM,MAAM,qBAAqB,GAAG;IAClC,mEAAmE;IACnE,QAAQ,CAAC,gBAAgB,EAAE,+BAA+B,CAAC;IAC3D,6DAA6D;IAC7D,QAAQ,CAAC,qBAAqB,EAAE,6BAA6B,CAAC;CAC/D,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAErD,0EAA0E;AAC1E,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhF,sFAAsF;AACtF,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAElF,0EAA0E;AAC1E,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAE9F,wFAAwF;AACxF,MAAM,MAAM,0BAA0B,GAAG;IACvC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IAC9C,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,oGAAoG;AACpG,MAAM,MAAM,mBAAmB,GAAG;IAChC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,0BAA0B,CAAC;IAC7C,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC"}

package/dist/experimental/rsc-types.js

@@ -0,0 +1,50 @@
+/** Exact React, React DOM, and Flight renderer version supported by the experimental RSC contract. */
+export const REACT_RSC_SUPPORTED_VERSION = '19.2.6';
+
+/** HTTP content type written for experimental React Flight payload responses. */
+export const REACT_RSC_FLIGHT_CONTENT_TYPE = 'text/x-component; charset=utf-8';
+
+/** Stable diagnostic codes emitted by the experimental RSC compatibility and manifest checks. */
+export const REACT_RSC_DIAGNOSTIC_CODES = {
+  emptyClientReferenceManifest: 'react-rsc-empty-client-reference-manifest',
+  emptyServerClientModuleMap: 'react-rsc-empty-server-client-module-map',
+  missingClientReferenceManifest: 'react-rsc-missing-client-reference-manifest',
+  missingServerClientModuleMap: 'react-rsc-missing-server-client-module-map',
+  unknownClientReference: 'react-rsc-unknown-client-reference',
+  unsupportedFlightRendererVersion: 'react-rsc-unsupported-flight-renderer-version',
+  unsupportedReactDomVersion: 'react-rsc-unsupported-react-dom-version',
+  unsupportedReactVersion: 'react-rsc-unsupported-react-version',
+  unsupportedRuntime: 'react-rsc-unsupported-runtime'
+};
+
+/** Machine-readable diagnostic code produced by the experimental RSC contract. */
+
+/** Actionable compatibility or build diagnostic produced instead of an expected configuration throw. */
+
+/** Runtime capabilities required by the experimental Flight response transport. */
+
+/** Build-adapter capabilities required to connect RSC module graphs explicitly. */
+
+/** Environment inputs checked before an application enables the experimental RSC path. */
+
+/** Result of inspecting one experimental RSC runtime and build environment. */
+
+/** Bundler-produced metadata for one client module export referenced by a Flight payload. */
+
+/** Client-reference metadata keyed by an application-owned stable reference id. */
+
+/** Server module exports mapped to keys in the client-reference manifest. */
+
+/** Build output accepted by `createReactRscManifest(...)`. */
+
+/** Defensive RSC module graph snapshot passed to an application-owned Flight renderer. */
+
+/** Result of validating and snapshotting an experimental RSC manifest. */
+
+/** Encoded React Flight payload accepted by the experimental HTTP response helper. */
+
+/** Additional HTTP headers applied to an experimental Flight response. */
+
+/** Options applied after ordinary fluo route success metadata for a Flight response. */
+
+/** Response entry returned from an ordinary fluo HTTP handler to emit an encoded Flight payload. */

package/dist/experimental/rsc.d.ts

@@ -0,0 +1,11 @@
+export { inspectReactRscEnvironment } from './rsc-diagnostics.js';
+export { createReactFlightResponse } from './rsc-flight-response.js';
+export { createReactRscManifest } from './rsc-manifest.js';
+export type { ReactFlightPayload, ReactFlightResponse, ReactFlightResponseHeaders, ReactFlightResponseOptions, ReactRscBuildCapabilities, ReactRscClientReference, ReactRscClientReferenceManifest, ReactRscDiagnostic, ReactRscDiagnosticCode, ReactRscEnvironmentOptions, ReactRscManifest, ReactRscManifestInput, ReactRscManifestResult, ReactRscRuntimeCapabilities, ReactRscServerClientModuleMap, ReactRscSupportResult, } from './rsc-types.js';
+export { REACT_RSC_DIAGNOSTIC_CODES, REACT_RSC_FLIGHT_CONTENT_TYPE, REACT_RSC_SUPPORTED_VERSION, } from './rsc-types.js';
+export { createReactServerFunctionClient } from './server-functions-client.js';
+export { ReactServerFunctionClientError, ReactServerFunctionConfigurationError, } from './server-functions-errors.js';
+export { createReactServerFunctionRegistry } from './server-functions-server.js';
+export type { ReactServerFunctionClient, ReactServerFunctionClientOptions, ReactServerFunctionErrorCode, ReactServerFunctionFetch, ReactServerFunctionHandler, ReactServerFunctionReference, ReactServerFunctionRegistry, ReactServerFunctionRegistryOptions, ReactServerFunctionResponse, ReactServerFunctionValue, } from './server-functions-types.js';
+export { REACT_SERVER_FUNCTION_ERROR_CODES, REACT_SERVER_FUNCTION_REQUEST_HEADER, } from './server-functions-types.js';
+//# sourceMappingURL=rsc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rsc.d.ts","sourceRoot":"","sources":["../../src/experimental/rsc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,EACvB,+BAA+B,EAC/B,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,EAC3B,6BAA6B,EAC7B,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EACL,8BAA8B,EAC9B,qCAAqC,GACtC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iCAAiC,EAAE,MAAM,8BAA8B,CAAC;AACjF,YAAY,EACV,yBAAyB,EACzB,gCAAgC,EAChC,4BAA4B,EAC5B,wBAAwB,EACxB,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,EAC3B,kCAAkC,EAClC,2BAA2B,EAC3B,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,iCAAiC,EACjC,oCAAoC,GACrC,MAAM,6BAA6B,CAAC"}

package/dist/experimental/rsc.js

@@ -0,0 +1,8 @@
+export { inspectReactRscEnvironment } from './rsc-diagnostics.js';
+export { createReactFlightResponse } from './rsc-flight-response.js';
+export { createReactRscManifest } from './rsc-manifest.js';
+export { REACT_RSC_DIAGNOSTIC_CODES, REACT_RSC_FLIGHT_CONTENT_TYPE, REACT_RSC_SUPPORTED_VERSION } from './rsc-types.js';
+export { createReactServerFunctionClient } from './server-functions-client.js';
+export { ReactServerFunctionClientError, ReactServerFunctionConfigurationError } from './server-functions-errors.js';
+export { createReactServerFunctionRegistry } from './server-functions-server.js';
+export { REACT_SERVER_FUNCTION_ERROR_CODES, REACT_SERVER_FUNCTION_REQUEST_HEADER } from './server-functions-types.js';

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

@@ -0,0 +1,14 @@
+import { type ReactServerFunctionClient, type ReactServerFunctionClientOptions } from './server-functions-types.js';
+/**
+ * Creates a client callable that posts signed Server Function invocations to one explicit endpoint.
+ *
+ * @remarks
+ * The callable sends `Content-Type: application/json`, the non-simple request marker, and
+ * `credentials: 'same-origin'`. Browsers still own the `Origin` header; the matching server
+ * registry rejects missing or unapproved origins.
+ *
+ * @param options Explicit endpoint, signed reference, fetch transport, and response limits.
+ * @returns An async callable accepting only the documented JSON-compatible value subset.
+ */
+export declare function createReactServerFunctionClient(options: ReactServerFunctionClientOptions): ReactServerFunctionClient;
+//# sourceMappingURL=server-functions-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-client.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-client.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACtC,MAAM,6BAA6B,CAAC;AAmErC;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,gCAAgC,GACxC,yBAAyB,CAkE3B"}

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

@@ -0,0 +1,120 @@
+import { ReactServerFunctionClientError, ReactServerFunctionConfigurationError } from './server-functions-errors.js';
+import { parseReactServerFunctionArguments, parseReactServerFunctionValue } from './server-functions-serialization.js';
+import { REACT_SERVER_FUNCTION_ERROR_CODES, REACT_SERVER_FUNCTION_REQUEST_HEADER } from './server-functions-types.js';
+const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+const DEFAULT_MAX_SERIALIZATION_DEPTH = 32;
+function parsePositiveInteger(value, fallback, name) {
+  const parsed = value ?? fallback;
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new ReactServerFunctionConfigurationError(`${name} must be a positive safe integer.`);
+  }
+  return parsed;
+}
+function parseJson(text, status) {
+  try {
+    const parsed = JSON.parse(text);
+    return parsed;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new ReactServerFunctionClientError('Server Function response was not valid JSON.', status, text);
+    }
+    throw error;
+  }
+}
+function isResponseRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function readBoundedResponseText(response, maxResponseBytes) {
+  const reader = response.body?.getReader();
+  if (reader === undefined) {
+    return '';
+  }
+  const decoder = new TextDecoder();
+  let byteLength = 0;
+  let text = '';
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) {
+        return text + decoder.decode();
+      }
+      byteLength += chunk.value.byteLength;
+      if (byteLength > maxResponseBytes) {
+        await Promise.allSettled([reader.cancel()]);
+        throw new ReactServerFunctionClientError('Server Function response exceeds the configured byte limit.', response.status);
+      }
+      text += decoder.decode(chunk.value, {
+        stream: true
+      });
+    }
+  } catch (error) {
+    if (error instanceof ReactServerFunctionClientError) {
+      throw error;
+    }
+    throw new ReactServerFunctionClientError('Server Function response body could not be read.', response.status);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Creates a client callable that posts signed Server Function invocations to one explicit endpoint.
+ *
+ * @remarks
+ * The callable sends `Content-Type: application/json`, the non-simple request marker, and
+ * `credentials: 'same-origin'`. Browsers still own the `Origin` header; the matching server
+ * registry rejects missing or unapproved origins.
+ *
+ * @param options Explicit endpoint, signed reference, fetch transport, and response limits.
+ * @returns An async callable accepting only the documented JSON-compatible value subset.
+ */
+export function createReactServerFunctionClient(options) {
+  if (options.endpoint.trim().length === 0) {
+    throw new ReactServerFunctionConfigurationError('Server Function client endpoints must not be empty.');
+  }
+  if (options.reference.value.length === 0) {
+    throw new ReactServerFunctionConfigurationError('Server Function client references must not be empty.');
+  }
+  const maxResponseBytes = parsePositiveInteger(options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, 'maxResponseBytes');
+  const maxSerializationDepth = parsePositiveInteger(options.maxSerializationDepth, DEFAULT_MAX_SERIALIZATION_DEPTH, 'maxSerializationDepth');
+  if (maxSerializationDepth > 128) {
+    throw new ReactServerFunctionConfigurationError('maxSerializationDepth must not exceed 128.');
+  }
+  return async (...args) => {
+    const parsedArgs = parseReactServerFunctionArguments(args, maxSerializationDepth);
+    if (!parsedArgs.ok) {
+      throw new ReactServerFunctionClientError(`${REACT_SERVER_FUNCTION_ERROR_CODES.argumentSerializationFailed}: ${parsedArgs.path} ${parsedArgs.reason}`, 0);
+    }
+    let response;
+    try {
+      response = await options.fetch(options.endpoint, {
+        body: JSON.stringify({
+          action: options.reference.value,
+          args: parsedArgs.value
+        }),
+        credentials: 'same-origin',
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+          [REACT_SERVER_FUNCTION_REQUEST_HEADER]: '1'
+        },
+        method: 'POST'
+      });
+    } catch {
+      throw new ReactServerFunctionClientError('Server Function request failed before receiving an HTTP response.', 0);
+    }
+    const responseText = await readBoundedResponseText(response, maxResponseBytes);
+    const responseBody = parseJson(responseText, response.status);
+    if (!response.ok) {
+      throw new ReactServerFunctionClientError('Server Function request failed.', response.status, responseBody);
+    }
+    if (!isResponseRecord(responseBody) || !Object.hasOwn(responseBody, 'result')) {
+      throw new ReactServerFunctionClientError('Server Function response is missing a result.', response.status, responseBody);
+    }
+    const result = parseReactServerFunctionValue(responseBody.result, maxSerializationDepth);
+    if (!result.ok) {
+      throw new ReactServerFunctionClientError(`Server Function response is not safely serializable: ${result.path} ${result.reason}`, response.status, responseBody);
+    }
+    return result.value;
+  };
+}

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

@@ -0,0 +1,17 @@
+import type { ReactServerFunctionHandler, ReactServerFunctionRegistryOptions } from './server-functions-types.js';
+/** Validated immutable configuration consumed by the Server Function request boundary. */
+export type ReactServerFunctionRegistryConfiguration = {
+    readonly actions: Readonly<Record<string, ReactServerFunctionHandler>>;
+    readonly allowedOrigins: ReadonlySet<string>;
+    readonly maxBodyBytes: number;
+    readonly maxResultBytes: number;
+    readonly maxSerializationDepth: number;
+};
+/**
+ * Parses and snapshots caller-owned registry options before references or requests are handled.
+ *
+ * @param options Untrusted registry configuration supplied at the application boundary.
+ * @returns Validated actions, origins, and transport limits.
+ */
+export declare function createReactServerFunctionRegistryConfiguration(options: ReactServerFunctionRegistryOptions): ReactServerFunctionRegistryConfiguration;
+//# sourceMappingURL=server-functions-configuration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-configuration.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-configuration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,0BAA0B,EAC1B,kCAAkC,EACnC,MAAM,6BAA6B,CAAC;AAMrC,0FAA0F;AAC1F,MAAM,MAAM,wCAAwC,GAAG;IACrD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC;IACvE,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;CACxC,CAAC;AAoCF;;;;;GAKG;AACH,wBAAgB,8CAA8C,CAC5D,OAAO,EAAE,kCAAkC,GAC1C,wCAAwC,CA+B1C"}

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

@@ -0,0 +1,68 @@
+import { ReactServerFunctionConfigurationError } from './server-functions-errors.js';
+import { isReactServerFunctionActionId } from './server-functions-reference.js';
+const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+const DEFAULT_MAX_RESULT_BYTES = 1024 * 1024;
+const DEFAULT_MAX_SERIALIZATION_DEPTH = 32;
+
+/** Validated immutable configuration consumed by the Server Function request boundary. */
+
+function configurationError(message) {
+  throw new ReactServerFunctionConfigurationError(message);
+}
+function parsePositiveInteger(value, fallback, name) {
+  const parsed = value ?? fallback;
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : configurationError(`${name} must be a positive safe integer.`);
+}
+function parseSerializationDepth(value) {
+  const parsed = parsePositiveInteger(value, DEFAULT_MAX_SERIALIZATION_DEPTH, 'maxSerializationDepth');
+  return parsed <= 128 ? parsed : configurationError('maxSerializationDepth must not exceed 128.');
+}
+function normalizeOrigin(origin) {
+  let parsed;
+  try {
+    parsed = new URL(origin);
+  } catch (error) {
+    if (error instanceof TypeError) {
+      return configurationError(`Server Function allowed origin "${origin}" is not a valid URL origin.`);
+    }
+    throw error;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:' || parsed.origin !== origin) {
+    return configurationError(`Server Function allowed origin "${origin}" must be an exact HTTP(S) origin.`);
+  }
+  return parsed.origin;
+}
+
+/**
+ * Parses and snapshots caller-owned registry options before references or requests are handled.
+ *
+ * @param options Untrusted registry configuration supplied at the application boundary.
+ * @returns Validated actions, origins, and transport limits.
+ */
+export function createReactServerFunctionRegistryConfiguration(options) {
+  const actions = {};
+  Object.setPrototypeOf(actions, null);
+  for (const [actionId, handler] of Object.entries(options.actions)) {
+    if (!isReactServerFunctionActionId(actionId)) {
+      return configurationError(`Server Function action id "${actionId}" must match [A-Za-z0-9_-] and contain 1 to 128 characters.`);
+    }
+    if (typeof handler !== 'function') {
+      return configurationError(`Server Function action "${actionId}" must map to a handler function.`);
+    }
+    actions[actionId] = handler;
+  }
+  if (Object.keys(actions).length === 0) {
+    return configurationError('Server Function registries must contain at least one action.');
+  }
+  const origins = new Set(options.allowedOrigins.map(normalizeOrigin));
+  if (origins.size === 0) {
+    return configurationError('Server Function registries must allow at least one exact HTTP(S) origin.');
+  }
+  return {
+    actions: Object.freeze(actions),
+    allowedOrigins: origins,
+    maxBodyBytes: parsePositiveInteger(options.maxBodyBytes, DEFAULT_MAX_BODY_BYTES, 'maxBodyBytes'),
+    maxResultBytes: parsePositiveInteger(options.maxResultBytes, DEFAULT_MAX_RESULT_BYTES, 'maxResultBytes'),
+    maxSerializationDepth: parseSerializationDepth(options.maxSerializationDepth)
+  };
+}

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

@@ -0,0 +1,19 @@
+/** Configuration failure detected before an experimental Server Function registry is used. */
+export declare class ReactServerFunctionConfigurationError extends Error {
+    readonly name = "ReactServerFunctionConfigurationError";
+}
+/** Client-side HTTP or serialization failure from an experimental Server Function call. */
+export declare class ReactServerFunctionClientError extends Error {
+    readonly status: number;
+    readonly responseBody?: unknown | undefined;
+    readonly name = "ReactServerFunctionClientError";
+    /**
+     * Creates a typed client error without converting a failed response into an action result.
+     *
+     * @param message Human-readable transport failure.
+     * @param status HTTP status, or zero when no valid HTTP response was available.
+     * @param responseBody Parsed response body when one was available.
+     */
+    constructor(message: string, status: number, responseBody?: unknown | undefined);
+}
+//# sourceMappingURL=server-functions-errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-errors.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-errors.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,qBAAa,qCAAsC,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,2CAA2C;CACzD;AAED,2FAA2F;AAC3F,qBAAa,8BAA+B,SAAQ,KAAK;IAYrD,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO;IAZjC,QAAQ,CAAC,IAAI,oCAAoC;IAEjD;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,OAAO,YAAA;CAIlC"}

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

@@ -0,0 +1,22 @@
+/** Configuration failure detected before an experimental Server Function registry is used. */
+export class ReactServerFunctionConfigurationError extends Error {
+  name = 'ReactServerFunctionConfigurationError';
+}
+
+/** Client-side HTTP or serialization failure from an experimental Server Function call. */
+export class ReactServerFunctionClientError extends Error {
+  name = 'ReactServerFunctionClientError';
+
+  /**
+   * Creates a typed client error without converting a failed response into an action result.
+   *
+   * @param message Human-readable transport failure.
+   * @param status HTTP status, or zero when no valid HTTP response was available.
+   * @param responseBody Parsed response body when one was available.
+   */
+  constructor(message, status, responseBody) {
+    super(message);
+    this.status = status;
+    this.responseBody = responseBody;
+  }
+}

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

@@ -0,0 +1,22 @@
+import type { ReactServerFunctionReference } from './server-functions-types.js';
+type ReferenceSigner = {
+    readonly createReference: (actionId: string) => Promise<ReactServerFunctionReference>;
+    readonly verifyReference: (reference: string) => Promise<string | undefined>;
+};
+/**
+ * Returns whether an action id is stable and safe to embed in the versioned reference format.
+ *
+ * @param value Candidate action id.
+ * @returns Whether the id matches the bounded reference grammar.
+ */
+export declare function isReactServerFunctionActionId(value: string): boolean;
+/**
+ * Creates the HMAC-SHA-256 action reference signer used by one registry.
+ *
+ * @param crypto Explicit runtime Web Crypto provider.
+ * @param secret Application-owned secret snapshot.
+ * @returns Reference issue and verification operations.
+ */
+export declare function createReactServerFunctionReferenceSigner(crypto: Pick<Crypto, 'subtle'>, secret: Uint8Array): ReferenceSigner;
+export {};
+//# sourceMappingURL=server-functions-reference.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-reference.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-reference.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAMhF,KAAK,eAAe,GAAG;IACrB,QAAQ,CAAC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACtF,QAAQ,CAAC,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9E,CAAC;AAyBF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CACtD,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,EAC9B,MAAM,EAAE,UAAU,GACjB,eAAe,CA4CjB"}

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

@@ -0,0 +1,76 @@
+import { ReactServerFunctionConfigurationError } from './server-functions-errors.js';
+const actionIdPattern = /^[A-Za-z0-9_-]{1,128}$/;
+const referencePattern = /^v1:([A-Za-z0-9_-]{1,128}):([a-f0-9]{64})$/;
+const signaturePrefix = 'fluo.react.server-function.v1:';
+function toHex(value) {
+  let result = '';
+  for (const byte of new Uint8Array(value)) {
+    result += byte.toString(16).padStart(2, '0');
+  }
+  return result;
+}
+function fromHex(value) {
+  if (value.length % 2 !== 0) {
+    return undefined;
+  }
+  const result = new Uint8Array(value.length / 2);
+  for (let index = 0; index < value.length; index += 2) {
+    const byte = Number.parseInt(value.slice(index, index + 2), 16);
+    if (!Number.isInteger(byte)) {
+      return undefined;
+    }
+    result[index / 2] = byte;
+  }
+  return result;
+}
+
+/**
+ * Returns whether an action id is stable and safe to embed in the versioned reference format.
+ *
+ * @param value Candidate action id.
+ * @returns Whether the id matches the bounded reference grammar.
+ */
+export function isReactServerFunctionActionId(value) {
+  return actionIdPattern.test(value);
+}
+
+/**
+ * Creates the HMAC-SHA-256 action reference signer used by one registry.
+ *
+ * @param crypto Explicit runtime Web Crypto provider.
+ * @param secret Application-owned secret snapshot.
+ * @returns Reference issue and verification operations.
+ */
+export function createReactServerFunctionReferenceSigner(crypto, secret) {
+  if (secret.byteLength < 32) {
+    throw new ReactServerFunctionConfigurationError('Server Function HMAC secrets must contain at least 32 bytes.');
+  }
+  const encoder = new TextEncoder();
+  const secretSnapshot = new Uint8Array(secret);
+  const key = crypto.subtle.importKey('raw', secretSnapshot, {
+    hash: 'SHA-256',
+    name: 'HMAC'
+  }, false, ['sign', 'verify']);
+  return {
+    async createReference(actionId) {
+      const signature = await crypto.subtle.sign('HMAC', await key, encoder.encode(`${signaturePrefix}${actionId}`));
+      return Object.freeze({
+        value: `v1:${actionId}:${toHex(signature)}`
+      });
+    },
+    async verifyReference(reference) {
+      const match = referencePattern.exec(reference);
+      const actionId = match?.[1];
+      const signatureHex = match?.[2];
+      if (actionId === undefined || signatureHex === undefined) {
+        return undefined;
+      }
+      const signature = fromHex(signatureHex);
+      if (signature === undefined) {
+        return undefined;
+      }
+      const valid = await crypto.subtle.verify('HMAC', await key, signature, encoder.encode(`${signaturePrefix}${actionId}`));
+      return valid ? actionId : undefined;
+    }
+  };
+}

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

@@ -0,0 +1,37 @@
+import type { ReactServerFunctionValue } from './server-functions-types.js';
+type SerializationFailure = {
+    readonly ok: false;
+    readonly path: string;
+    readonly reason: string;
+};
+type SerializationSuccess<T> = {
+    readonly ok: true;
+    readonly value: T;
+};
+/** Result of parsing an untrusted value into the Server Function serialization subset. */
+export type ReactServerFunctionSerializationResult<T> = SerializationSuccess<T> | SerializationFailure;
+/**
+ * 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 declare function parseReactServerFunctionArguments(value: unknown, maxDepth: number): ReactServerFunctionSerializationResult<readonly ReactServerFunctionValue[]>;
+/**
+ * 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 declare function parseReactServerFunctionValue(value: unknown, maxDepth: number): ReactServerFunctionSerializationResult<ReactServerFunctionValue>;
+/**
+ * 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 declare function measureReactServerFunctionValue(value: ReactServerFunctionValue): number;
+export {};
+//# sourceMappingURL=server-functions-serialization.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-functions-serialization.d.ts","sourceRoot":"","sources":["../../src/experimental/server-functions-serialization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAI5E,KAAK,oBAAoB,GAAG;IAC1B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,KAAK,oBAAoB,CAAC,CAAC,IAAI;IAC7B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,sCAAsC,CAAC,CAAC,IAChD,oBAAoB,CAAC,CAAC,CAAC,GACvB,oBAAoB,CAAC;AA+GzB;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf,sCAAsC,CAAC,SAAS,wBAAwB,EAAE,CAAC,CAgB7E;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf,sCAAsC,CAAC,wBAAwB,CAAC,CAOlE;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAGvF"}