react-on-rails 16.6.0 → 16.7.0-rc.0

package/README.md

@@ -14,6 +14,14 @@ pnpm add react-on-rails
 
 **Using React on Rails Pro?** Install [`react-on-rails-pro`](https://www.npmjs.com/package/react-on-rails-pro) instead. The Pro package re-exports everything from this package plus Pro-exclusive features. The `react_on_rails_pro` gem requires the Pro npm package.
 
+## Need More Than OSS?
+
+If you want React Server Components, streaming SSR, fragment caching, or faster Node-based SSR, try [`react-on-rails-pro`](https://www.npmjs.com/package/react-on-rails-pro). It is free to evaluate in development, CI/CD, and staging; production licenses are required only for production deployments.
+
+- [Compare OSS vs Pro](https://reactonrails.com/docs/getting-started/oss-vs-pro/)
+- [Pro quick start](https://reactonrails.com/docs/getting-started/pro-quick-start/)
+- [React on Rails Pro overview](https://reactonrails.com/docs/pro/)
+
 ## Quick Start
 
 ### Register Components

package/lib/ReactOnRails.client.js

@@ -1,7 +1,19 @@
-import { createBaseClientObject } from "./base/client.js";
+import { createCoreCapability } from "./capabilities/core.js";
+import { createLifecycleCapability } from "./capabilities/lifecycle.js";
 import createReactOnRails from "./createReactOnRails.js";
+import ComponentRegistry from "./ComponentRegistry.js";
+import StoreRegistry from "./StoreRegistry.js";
+import { clientStartup } from "./clientStartup.js";
+const registries = { ComponentRegistry, StoreRegistry };
 const currentGlobal = globalThis.ReactOnRails || null;
-const ReactOnRails = createReactOnRails(createBaseClientObject, currentGlobal);
+const ReactOnRails = createReactOnRails([createCoreCapability(registries), createLifecycleCapability()], {
+    currentGlobal,
+    // Defer startup to the next tick so all synchronous <script> tags finish evaluating
+    // before we scan the DOM for components. Pro's proClientStartup runs synchronously
+    // because streaming hydration needs to attach listeners before the first paint.
+    startup: typeof window !== 'undefined' ? () => setTimeout(() => clientStartup(), 0) : null,
+    registries,
+});
 export * from "./types/index.js";
 export default ReactOnRails;
 //# sourceMappingURL=ReactOnRails.client.js.map

package/lib/ReactOnRails.full.js

@@ -1,7 +1,17 @@
-import { createBaseFullObject } from "./base/full.js";
+import { createCoreCapability } from "./capabilities/core.js";
+import { createLifecycleCapability } from "./capabilities/lifecycle.js";
+import { createSSRCapability } from "./capabilities/ssr.js";
 import createReactOnRails from "./createReactOnRails.js";
+import ComponentRegistry from "./ComponentRegistry.js";
+import StoreRegistry from "./StoreRegistry.js";
+import { clientStartup } from "./clientStartup.js";
+const registries = { ComponentRegistry, StoreRegistry };
 const currentGlobal = globalThis.ReactOnRails || null;
-const ReactOnRails = createReactOnRails(createBaseFullObject, currentGlobal);
+const ReactOnRails = createReactOnRails([createCoreCapability(registries), createLifecycleCapability(), createSSRCapability()], {
+    currentGlobal,
+    startup: typeof window !== 'undefined' ? () => setTimeout(() => clientStartup(), 0) : null,
+    registries,
+});
 export * from "./types/index.js";
 export default ReactOnRails;
 //# sourceMappingURL=ReactOnRails.full.js.map

package/lib/RenderUtils.js

@@ -1,13 +1,10 @@
+import sanitizeNonce from "./sanitizeNonce.js";
 // eslint-disable-next-line import/prefer-default-export -- only one export for now, but others may be added later
 export function wrapInScriptTags(scriptId, scriptBody, nonce) {
     if (!scriptBody) {
         return '';
     }
-    // Sanitize nonce to prevent attribute injection attacks.
-    // CSP nonces should be base64/base64url-like strings with optional trailing padding.
-    // NOTE: keep this logic in sync with sanitizeNonce() in react-on-rails-pro/src/utils.ts
-    const nonceWithAllowedCharsOnly = nonce?.replace(/[^a-zA-Z0-9+/=_-]/g, '');
-    const sanitizedNonce = nonceWithAllowedCharsOnly?.match(/^[a-zA-Z0-9+/_-]+={0,2}$/)?.[0];
+    const sanitizedNonce = sanitizeNonce(nonce);
     const nonceAttr = sanitizedNonce ? ` nonce="${sanitizedNonce}"` : '';
     return `
 <script id="${scriptId}"${nonceAttr}>

package/lib/base/client.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Use `capabilities/core.ts` instead. This file is kept for backward compatibility
+ * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/client`.
+ */
 import type { RegisteredComponent, ReactComponentOrRenderFunction, Store, StoreGenerator, ReactOnRailsInternal } from '../types/index.ts';
 interface Registries {
     ComponentRegistry: {
@@ -19,7 +23,7 @@ interface Registries {
  * Base client object type that includes all core ReactOnRails methods except Pro-specific ones.
  * Derived from ReactOnRailsInternal by omitting Pro-only methods.
  */
-export type BaseClientObjectType = Omit<ReactOnRailsInternal, 'getOrWaitForComponent' | 'getOrWaitForStore' | 'getOrWaitForStoreGenerator' | 'reactOnRailsStoreLoaded' | 'streamServerRenderedReactComponent' | 'serverRenderRSCReactComponent'>;
+export type BaseClientObjectType = Omit<ReactOnRailsInternal, 'getOrWaitForComponent' | 'getOrWaitForStore' | 'getOrWaitForStoreGenerator' | 'reactOnRailsStoreLoaded' | 'streamServerRenderedReactComponent' | 'serverRenderRSCReactComponent' | 'addAsyncPropsCapabilityToComponentProps' | 'getOrCreateAsyncPropsManager'>;
 export declare function createBaseClientObject(registries: Registries, currentObject?: BaseClientObjectType | null): BaseClientObjectType;
 export {};
 //# sourceMappingURL=client.d.ts.map

package/lib/base/client.js

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Use `capabilities/core.ts` instead. This file is kept for backward compatibility
+ * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/client`.
+ */
 import * as Authenticity from "../Authenticity.js";
 import buildConsoleReplay, { consoleReplay } from "../buildConsoleReplay.js";
 import reactHydrateOrRender from "../reactHydrateOrRender.js";
@@ -201,6 +205,11 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
             void args; // Mark as used
             throw new Error('handleError is not available in "react-on-rails/client". Import "react-on-rails" server-side.');
         },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prepareRenderResult(...args) {
+            void args; // Mark as used
+            throw new Error('prepareRenderResult is not available in "react-on-rails/client". Import "react-on-rails" server-side.');
+        },
     };
     // Cache the object and registries
     cachedObject = obj;

package/lib/base/full.d.ts

@@ -1,10 +1,14 @@
+/**
+ * @deprecated Use `capabilities/ssr.ts` instead. This file is kept for backward compatibility
+ * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/full`.
+ */
 import { createBaseClientObject, type BaseClientObjectType } from './client.ts';
 import type { ReactOnRailsInternal } from '../types/index.ts';
 /**
  * SSR-specific functions that extend the base client object to create a full object.
  * Typed explicitly to ensure type safety when mutating the base object.
  */
-export type ReactOnRailsFullSpecificFunctions = Pick<ReactOnRailsInternal, 'handleError' | 'serverRenderReactComponent'>;
+export type ReactOnRailsFullSpecificFunctions = Pick<ReactOnRailsInternal, 'handleError' | 'serverRenderReactComponent' | 'prepareRenderResult'>;
 /**
  * Full object type that includes all base methods plus real SSR implementations.
  * Derived from ReactOnRailsInternal by picking base methods and SSR methods.

package/lib/base/full.js

@@ -1,6 +1,11 @@
+/**
+ * @deprecated Use `capabilities/ssr.ts` instead. This file is kept for backward compatibility
+ * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/full`.
+ */
 import { createBaseClientObject } from "./client.js";
 import handleError from "../handleError.js";
 import serverRenderReactComponent from "../serverRenderReactComponent.js";
+import { buildLengthPrefixedResult } from "../serverRenderUtils.js";
 // Warn about bundle size when included in browser bundles
 if (typeof window !== 'undefined') {
     console.warn('Optimization opportunity: "react-on-rails" includes ~14KB of server-rendering code. ' +
@@ -19,6 +24,12 @@ export function createBaseFullObject(registries, currentObject = null) {
         serverRenderReactComponent(options) {
             return serverRenderReactComponent(options);
         },
+        prepareRenderResult(html, consoleReplayScript, hasErrors, renderingError) {
+            return buildLengthPrefixedResult(html, consoleReplayScript, {
+                hasErrors,
+                error: renderingError ?? undefined,
+            });
+        },
     };
     // Type assertion is safe here because:
     // 1. We start with BaseClientObjectType (from createBaseClientObject)

package/lib/base/full.rsc.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Use `capabilities/ssr.rsc.ts` instead. This file is kept for backward compatibility
+ * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/full`.
+ */
 import { createBaseClientObject, type BaseClientObjectType } from './client.ts';
 import type { BaseFullObjectType } from './full.ts';
 export type * from './full.ts';

package/lib/base/full.rsc.js

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Use `capabilities/ssr.rsc.ts` instead. This file is kept for backward compatibility
+ * with older versions of react-on-rails-pro that import from `react-on-rails/@internal/base/full`.
+ */
 import { createBaseClientObject } from "./client.js";
 export function createBaseFullObject(registries, currentObject = null) {
     // Get or create client object (with caching logic)
@@ -11,6 +15,9 @@ export function createBaseFullObject(registries, currentObject = null) {
         serverRenderReactComponent() {
             throw new Error('"serverRenderReactComponent" function is not supported in RSC bundle');
         },
+        prepareRenderResult() {
+            throw new Error('"prepareRenderResult" function is not supported in RSC bundle');
+        },
     };
     // Type assertion is safe here because:
     // 1. We start with BaseClientObjectType (from createBaseClientObject)

package/lib/capabilities/core.d.ts

@@ -0,0 +1,58 @@
+import type { ReactElement } from 'react';
+import type { RegisteredComponent, RenderReturnType, ReactComponentOrRenderFunction, AuthenticityHeaders, Store, StoreGenerator, ReactOnRailsOptions } from '../types/index.ts';
+export interface Registries {
+    ComponentRegistry: {
+        register: (components: Record<string, ReactComponentOrRenderFunction>) => void;
+        get: (name: string) => RegisteredComponent;
+        components: () => Map<string, RegisteredComponent>;
+    };
+    StoreRegistry: {
+        register: (storeGenerators: Record<string, StoreGenerator>) => void;
+        getStore: (name: string, throwIfMissing?: boolean) => Store | undefined;
+        getStoreGenerator: (name: string) => StoreGenerator;
+        setStore: (name: string, store: Store) => void;
+        clearHydratedStores: () => void;
+        storeGenerators: () => Map<string, StoreGenerator>;
+        stores: () => Map<string, Store>;
+    };
+}
+/**
+ * Creates the core capability containing all base ReactOnRails methods.
+ * These are the methods that exist in every bundle variant (client, full, node, RSC).
+ */
+export declare function createCoreCapability(registries: Registries): {
+    options: Partial<ReactOnRailsOptions>;
+    isRSCBundle: boolean;
+    authenticityToken(): string | null;
+    authenticityHeaders(otherHeaders?: Record<string, string>): AuthenticityHeaders;
+    reactHydrateOrRender(domNode: Element, reactElement: ReactElement, hydrate: boolean): RenderReturnType;
+    setOptions(newOptions: Partial<ReactOnRailsOptions>): void;
+    option<K extends keyof ReactOnRailsOptions>(key: K): ReactOnRailsOptions[K];
+    buildConsoleReplay(): string;
+    getConsoleReplayScript(): string;
+    resetOptions(): void;
+    register(components: Record<string, ReactComponentOrRenderFunction>): void;
+    registerStore(stores: Record<string, StoreGenerator>): void;
+    registerStoreGenerators(storeGenerators: Record<string, StoreGenerator>): void;
+    getStore(name: string, throwIfMissing?: boolean): Store | undefined;
+    getStoreGenerator(name: string): StoreGenerator;
+    setStore(name: string, store: Store): void;
+    clearHydratedStores(): void;
+    getComponent(name: string): RegisteredComponent;
+    registeredComponents(): Map<string, RegisteredComponent>;
+    storeGenerators(): Map<string, StoreGenerator>;
+    stores(): Map<string, Store>;
+    render(name: string, props: Record<string, string>, domNodeId: string, hydrate: boolean): RenderReturnType;
+    serverRenderReactComponent(...args: any[]): any;
+    handleError(...args: any[]): any;
+    prepareRenderResult(...args: any[]): any;
+    getOrWaitForComponent(): Promise<RegisteredComponent>;
+    getOrWaitForStore(): Promise<Store>;
+    getOrWaitForStoreGenerator(): Promise<StoreGenerator>;
+    reactOnRailsStoreLoaded(): Promise<void>;
+    streamServerRenderedReactComponent(...args: any[]): any;
+    serverRenderRSCReactComponent(...args: any[]): any;
+    addAsyncPropsCapabilityToComponentProps(...args: any[]): any;
+    getOrCreateAsyncPropsManager(...args: any[]): any;
+};
+//# sourceMappingURL=core.d.ts.map

package/lib/capabilities/core.js

@@ -0,0 +1,188 @@
+import * as Authenticity from "../Authenticity.js";
+import buildConsoleReplay, { consoleReplay } from "../buildConsoleReplay.js";
+import reactHydrateOrRender from "../reactHydrateOrRender.js";
+import createReactOutput from "../createReactOutput.js";
+const DEFAULT_OPTIONS = {
+    traceTurbolinks: false,
+    turbo: false,
+    debugMode: false,
+    logComponentRegistration: false,
+};
+/**
+ * Creates the core capability containing all base ReactOnRails methods.
+ * These are the methods that exist in every bundle variant (client, full, node, RSC).
+ */
+export function createCoreCapability(registries) {
+    const { ComponentRegistry, StoreRegistry } = registries;
+    return {
+        options: {},
+        isRSCBundle: false,
+        // ===================================================================
+        // STABLE METHOD IMPLEMENTATIONS - Core package implementations
+        // ===================================================================
+        authenticityToken() {
+            return Authenticity.authenticityToken();
+        },
+        authenticityHeaders(otherHeaders = {}) {
+            return Authenticity.authenticityHeaders(otherHeaders);
+        },
+        reactHydrateOrRender(domNode, reactElement, hydrate) {
+            return reactHydrateOrRender(domNode, reactElement, hydrate);
+        },
+        setOptions(newOptions) {
+            const { traceTurbolinks, turbo, debugMode, logComponentRegistration, ...rest } = newOptions;
+            if (typeof traceTurbolinks !== 'undefined') {
+                this.options.traceTurbolinks = traceTurbolinks;
+            }
+            if (typeof turbo !== 'undefined') {
+                this.options.turbo = turbo;
+            }
+            if (typeof debugMode !== 'undefined') {
+                this.options.debugMode = debugMode;
+                if (debugMode) {
+                    console.log('[ReactOnRails] Debug mode enabled');
+                }
+            }
+            if (typeof logComponentRegistration !== 'undefined') {
+                this.options.logComponentRegistration = logComponentRegistration;
+                if (logComponentRegistration) {
+                    console.log('[ReactOnRails] Component registration logging enabled');
+                }
+            }
+            if (Object.keys(rest).length > 0) {
+                throw new Error(`Invalid options passed to ReactOnRails.options: ${JSON.stringify(rest)}`);
+            }
+        },
+        option(key) {
+            return this.options[key];
+        },
+        buildConsoleReplay() {
+            return buildConsoleReplay();
+        },
+        getConsoleReplayScript() {
+            return consoleReplay();
+        },
+        resetOptions() {
+            this.options = { ...DEFAULT_OPTIONS };
+        },
+        // ===================================================================
+        // REGISTRY METHOD IMPLEMENTATIONS - Using provided registries
+        // ===================================================================
+        register(components) {
+            if (this.options.debugMode || this.options.logComponentRegistration) {
+                // Use performance.now() if available, otherwise fallback to Date.now()
+                const perf = typeof performance !== 'undefined' ? performance : { now: () => Date.now() };
+                const startTime = perf.now();
+                const componentNames = Object.keys(components);
+                console.log(`[ReactOnRails] Registering ${componentNames.length} component(s): ${componentNames.join(', ')}`);
+                ComponentRegistry.register(components);
+                const endTime = perf.now();
+                console.log(`[ReactOnRails] Component registration completed in ${(endTime - startTime).toFixed(2)}ms`);
+                // Log individual component details if in full debug mode
+                if (this.options.debugMode) {
+                    componentNames.forEach((name) => {
+                        const component = components[name];
+                        const size = component.toString().length;
+                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${size} chars)`);
+                    });
+                }
+            }
+            else {
+                ComponentRegistry.register(components);
+            }
+        },
+        registerStore(stores) {
+            this.registerStoreGenerators(stores);
+        },
+        registerStoreGenerators(storeGenerators) {
+            if (!storeGenerators) {
+                throw new Error('Called ReactOnRails.registerStoreGenerators with a null or undefined, rather than ' +
+                    'an Object with keys being the store names and the values are the store generators.');
+            }
+            StoreRegistry.register(storeGenerators);
+        },
+        getStore(name, throwIfMissing = true) {
+            return StoreRegistry.getStore(name, throwIfMissing);
+        },
+        getStoreGenerator(name) {
+            return StoreRegistry.getStoreGenerator(name);
+        },
+        setStore(name, store) {
+            StoreRegistry.setStore(name, store);
+        },
+        clearHydratedStores() {
+            StoreRegistry.clearHydratedStores();
+        },
+        getComponent(name) {
+            return ComponentRegistry.get(name);
+        },
+        registeredComponents() {
+            return ComponentRegistry.components();
+        },
+        storeGenerators() {
+            return StoreRegistry.storeGenerators();
+        },
+        stores() {
+            return StoreRegistry.stores();
+        },
+        render(name, props, domNodeId, hydrate) {
+            const componentObj = ComponentRegistry.get(name);
+            const reactElement = createReactOutput({ componentObj, props, domNodeId });
+            return this.reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate);
+        },
+        // ===================================================================
+        // SSR STUBS — overridden by createSSRCapability() in full/node bundles
+        // ===================================================================
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        serverRenderReactComponent(...args) {
+            void args;
+            throw new Error('serverRenderReactComponent is not available in the client bundle. Import "react-on-rails" server-side.');
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        handleError(...args) {
+            void args;
+            throw new Error('handleError is not available in the client bundle. Import "react-on-rails" server-side.');
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        prepareRenderResult(...args) {
+            void args;
+            throw new Error('prepareRenderResult is not available in the client bundle. Import "react-on-rails" server-side.');
+        },
+        // ===================================================================
+        // PRO STUBS — overridden by Pro capabilities in react-on-rails-pro
+        // ===================================================================
+        getOrWaitForComponent() {
+            throw new Error('getOrWaitForComponent requires the react-on-rails-pro package.');
+        },
+        getOrWaitForStore() {
+            throw new Error('getOrWaitForStore requires the react-on-rails-pro package.');
+        },
+        getOrWaitForStoreGenerator() {
+            throw new Error('getOrWaitForStoreGenerator requires the react-on-rails-pro package.');
+        },
+        reactOnRailsStoreLoaded() {
+            throw new Error('reactOnRailsStoreLoaded requires the react-on-rails-pro package.');
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        streamServerRenderedReactComponent(...args) {
+            void args;
+            throw new Error('streamServerRenderedReactComponent requires the react-on-rails-pro package.');
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        serverRenderRSCReactComponent(...args) {
+            void args;
+            throw new Error('serverRenderRSCReactComponent requires the react-on-rails-pro package.');
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        addAsyncPropsCapabilityToComponentProps(...args) {
+            void args;
+            throw new Error('addAsyncPropsCapabilityToComponentProps requires the react-on-rails-pro package.');
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getOrCreateAsyncPropsManager(...args) {
+            void args;
+            throw new Error('getOrCreateAsyncPropsManager requires the react-on-rails-pro package.');
+        },
+    };
+}
+//# sourceMappingURL=core.js.map

package/lib/capabilities/lifecycle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Core lifecycle capability.
+ * Provides the core (non-Pro) implementations for page/component loaded callbacks.
+ */
+export declare function createLifecycleCapability(): {
+    reactOnRailsPageLoaded(): Promise<void>;
+    reactOnRailsComponentLoaded(domId: string): Promise<void>;
+};
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/capabilities/lifecycle.js

@@ -0,0 +1,19 @@
+/* eslint-disable import/prefer-default-export -- named export for consistency with capability API */
+import { reactOnRailsPageLoaded } from "../clientStartup.js";
+import { reactOnRailsComponentLoaded } from "../ClientRenderer.js";
+/**
+ * Core lifecycle capability.
+ * Provides the core (non-Pro) implementations for page/component loaded callbacks.
+ */
+export function createLifecycleCapability() {
+    return {
+        reactOnRailsPageLoaded() {
+            reactOnRailsPageLoaded();
+            return Promise.resolve();
+        },
+        reactOnRailsComponentLoaded(domId) {
+            return reactOnRailsComponentLoaded(domId);
+        },
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/capabilities/ssr.d.ts

@@ -0,0 +1,11 @@
+import type { RenderParams, ErrorOptions, RenderingError } from '../types/index.ts';
+/**
+ * SSR capability.
+ * Provides server-side rendering methods (serverRenderReactComponent, handleError).
+ */
+export declare function createSSRCapability(): {
+    handleError(options: ErrorOptions): string | undefined;
+    serverRenderReactComponent(options: RenderParams): null | string | Promise<string>;
+    prepareRenderResult(html: string, consoleReplayScript: string, hasErrors: boolean, renderingError: RenderingError | null): string;
+};
+//# sourceMappingURL=ssr.d.ts.map

package/lib/capabilities/ssr.js

@@ -0,0 +1,31 @@
+/* eslint-disable import/prefer-default-export -- named export for consistency with capability API */
+import handleError from "../handleError.js";
+import serverRenderReactComponent from "../serverRenderReactComponent.js";
+import { buildLengthPrefixedResult } from "../serverRenderUtils.js";
+// Warn about bundle size when included in browser bundles
+if (typeof window !== 'undefined') {
+    console.warn('Optimization opportunity: this bundle includes ~14KB of server-rendering code that browsers may not need. ' +
+        'See https://forum.shakacode.com/t/how-to-use-different-versions-of-a-file-for-client-and-server-rendering/1352 ' +
+        '(Requires creating a free account). Click this for the stack trace.');
+}
+/**
+ * SSR capability.
+ * Provides server-side rendering methods (serverRenderReactComponent, handleError).
+ */
+export function createSSRCapability() {
+    return {
+        handleError(options) {
+            return handleError(options);
+        },
+        serverRenderReactComponent(options) {
+            return serverRenderReactComponent(options);
+        },
+        prepareRenderResult(html, consoleReplayScript, hasErrors, renderingError) {
+            return buildLengthPrefixedResult(html, consoleReplayScript, {
+                hasErrors,
+                error: renderingError ?? undefined,
+            });
+        },
+    };
+}
+//# sourceMappingURL=ssr.js.map

package/lib/capabilities/ssr.rsc.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SSR capability for RSC bundles.
+ * SSR methods throw because they are not supported in the RSC bundle.
+ */
+export declare function createSSRCapability(): {
+    handleError(): never;
+    serverRenderReactComponent(): never;
+    prepareRenderResult(): never;
+};
+//# sourceMappingURL=ssr.rsc.d.ts.map

package/lib/capabilities/ssr.rsc.js

@@ -0,0 +1,19 @@
+/* eslint-disable import/prefer-default-export -- named export for consistency with capability API */
+/**
+ * SSR capability for RSC bundles.
+ * SSR methods throw because they are not supported in the RSC bundle.
+ */
+export function createSSRCapability() {
+    return {
+        handleError() {
+            throw new Error('"handleError" function is not supported in RSC bundle');
+        },
+        serverRenderReactComponent() {
+            throw new Error('"serverRenderReactComponent" function is not supported in RSC bundle');
+        },
+        prepareRenderResult() {
+            throw new Error('"prepareRenderResult" function is not supported in RSC bundle');
+        },
+    };
+}
+//# sourceMappingURL=ssr.rsc.js.map

package/lib/createReactOnRails.d.ts

@@ -1,7 +1,20 @@
-import { createBaseClientObject, type BaseClientObjectType } from './base/client.ts';
-import { createBaseFullObject } from './base/full.ts';
+import type { Registries } from './capabilities/core.ts';
 import type { ReactOnRailsInternal } from './types/index.ts';
-type BaseObjectCreator = typeof createBaseClientObject | typeof createBaseFullObject;
-export default function createReactOnRails(baseObjectCreator: BaseObjectCreator, currentGlobal?: BaseClientObjectType | null): ReactOnRailsInternal;
-export {};
+export type { Registries };
+/**
+ * Assembles the ReactOnRails global object from an array of capabilities.
+ *
+ * Each capability is a partial implementation of ReactOnRailsInternal.
+ * Capabilities are merged in array order (last wins for overlapping keys).
+ *
+ * @param capabilities - Array of capability objects to merge.
+ * @param options.currentGlobal - Current globalThis.ReactOnRails value (for misconfiguration detection).
+ * @param options.startup - Callback invoked once on first initialization, after the global is set.
+ * @param options.registries - The registries used by the core capability (for mixing detection).
+ */
+export default function createReactOnRails(capabilities: Partial<ReactOnRailsInternal>[], options: {
+    currentGlobal: ReactOnRailsInternal | null;
+    startup: (() => void) | null;
+    registries: Registries;
+}): ReactOnRailsInternal;
 //# sourceMappingURL=createReactOnRails.d.ts.map

package/lib/createReactOnRails.js

@@ -1,68 +1,102 @@
-import { clientStartup, reactOnRailsPageLoaded } from "./clientStartup.js";
-import { reactOnRailsComponentLoaded } from "./ClientRenderer.js";
-import ComponentRegistry from "./ComponentRegistry.js";
-import StoreRegistry from "./StoreRegistry.js";
-export default function createReactOnRails(baseObjectCreator, currentGlobal = null) {
-    // Create base object with core registries, passing currentGlobal for caching/validation
-    const baseObject = baseObjectCreator({
-        ComponentRegistry,
-        StoreRegistry,
-    }, currentGlobal);
-    // Define core-specific functions with proper types
-    // This object acts as a type-safe specification of what we're adding/overriding on the base object
-    const reactOnRailsCoreSpecificFunctions = {
-        // Override base stubs with core implementations
-        reactOnRailsPageLoaded() {
-            reactOnRailsPageLoaded();
-            return Promise.resolve();
-        },
-        reactOnRailsComponentLoaded(domId) {
-            return reactOnRailsComponentLoaded(domId);
-        },
-        // Pro-only stubs (throw errors in core package)
-        getOrWaitForComponent() {
-            throw new Error('getOrWaitForComponent requires react-on-rails-pro package');
-        },
-        getOrWaitForStore() {
-            throw new Error('getOrWaitForStore requires react-on-rails-pro package');
-        },
-        getOrWaitForStoreGenerator() {
-            throw new Error('getOrWaitForStoreGenerator requires react-on-rails-pro package');
-        },
-        reactOnRailsStoreLoaded() {
-            throw new Error('reactOnRailsStoreLoaded requires react-on-rails-pro package');
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        streamServerRenderedReactComponent() {
-            throw new Error('streamServerRenderedReactComponent requires react-on-rails-pro package');
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        serverRenderRSCReactComponent() {
-            throw new Error('serverRenderRSCReactComponent requires react-on-rails-pro package');
-        },
-    };
-    // Type assertion is safe here because:
-    // 1. We start with BaseClientObjectType or BaseFullObjectType (from baseObjectCreator)
-    // 2. We add exactly the methods defined in ReactOnRailsCoreSpecificFunctions
-    // 3. ReactOnRailsInternal = Base + ReactOnRailsCoreSpecificFunctions
-    // TypeScript can't track the mutation, but we ensure type safety by explicitly typing
-    // the functions object above
-    const reactOnRails = baseObject;
-    // Assign core-specific functions to the ReactOnRails object using Object.assign
-    // This pattern ensures we add exactly what's defined in the type, nothing more, nothing less
-    Object.assign(reactOnRails, reactOnRailsCoreSpecificFunctions);
-    // Assign to global if not already assigned
-    if (!globalThis.ReactOnRails) {
-        globalThis.ReactOnRails = reactOnRails;
-        // Reset options to defaults (only on first initialization)
-        reactOnRails.resetOptions();
-        // Run client startup (only on first initialization)
-        if (typeof window !== 'undefined') {
-            setTimeout(() => {
-                clientStartup();
-            }, 0);
+// Module-level cache for singleton enforcement and validation
+let cachedObject = null;
+let cachedRegistries = null;
+/**
+ * Assembles the ReactOnRails global object from an array of capabilities.
+ *
+ * Each capability is a partial implementation of ReactOnRailsInternal.
+ * Capabilities are merged in array order (last wins for overlapping keys).
+ *
+ * @param capabilities - Array of capability objects to merge.
+ * @param options.currentGlobal - Current globalThis.ReactOnRails value (for misconfiguration detection).
+ * @param options.startup - Callback invoked once on first initialization, after the global is set.
+ * @param options.registries - The registries used by the core capability (for mixing detection).
+ */
+export default function createReactOnRails(capabilities, options) {
+    const { currentGlobal, startup, registries } = options;
+    // ===================================================================
+    // VALIDATION — preserved from base/client.ts
+    // ===================================================================
+    // Webpack misconfiguration detection: currentGlobal is null but we have a cached object.
+    // This indicates webpack's optimization.runtimeChunk is set to "true" or "multiple".
+    if (currentGlobal === null && cachedObject !== null) {
+        throw new Error(`\
+ReactOnRails was already initialized, but a new initialization was attempted without passing the existing global.
+This usually means Webpack's optimization.runtimeChunk is set to "true" or "multiple" instead of "single".
+
+Fix: Set optimization.runtimeChunk to "single" in your webpack configuration.
+See: https://github.com/shakacode/react_on_rails/issues/1558`);
+    }
+    // Cross-runtime detection: another bundle/runtime already initialized the global,
+    // but this module instance hasn't cached anything yet.
+    // In development with HMR/fast-refresh, webpack invalidates the module cache
+    // (resetting cachedObject to null) while globalThis.ReactOnRails persists from the
+    // previous load. The old base/client.ts code handled this gracefully by returning
+    // the existing global. We preserve that behavior in development and only throw in
+    // production where this genuinely indicates misconfiguration (multiple runtimes or
+    // mixed core/pro bundles).
+    if (currentGlobal !== null && cachedObject === null) {
+        if (process.env.NODE_ENV === 'production') {
+            throw new Error(`\
+ReactOnRails was already initialized by another bundle or runtime instance.
+This usually means multiple webpack runtimes or mixed core/pro bundles were loaded on the same page.
+
+Fix: Ensure only one ReactOnRails bundle initializes per page, and set optimization.runtimeChunk to "single".`);
+        }
+        // In development (HMR), accept the pre-existing global and re-cache it.
+        cachedObject = currentGlobal;
+        cachedRegistries = registries;
+        return cachedObject;
+    }
+    // Global contamination detection: currentGlobal exists but doesn't match cached object.
+    if (currentGlobal !== null && cachedObject !== null && currentGlobal !== cachedObject) {
+        throw new Error(`\
+ReactOnRails global object mismatch detected.
+The current global ReactOnRails object is different from the one created by this package.
+
+This usually means:
+1. You're mixing react-on-rails (core) with react-on-rails-pro
+2. Another library is interfering with the global ReactOnRails object
+
+Fix: Use only one package (core OR pro) consistently throughout your application.`);
+    }
+    // Registry mixing detection: different registries indicate core/pro package mixing.
+    if (cachedRegistries !== null) {
+        if (registries.ComponentRegistry !== cachedRegistries.ComponentRegistry ||
+            registries.StoreRegistry !== cachedRegistries.StoreRegistry) {
+            throw new Error(`\
+Cannot mix react-on-rails (core) with react-on-rails-pro.
+Different registries detected - the packages use incompatible registries.
+
+Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
         }
     }
+    // Return cached object if already initialized (all validation passed above).
+    // Merge only additive capabilities onto the existing object.
+    // The first capability is the core baseline, which includes client/pro stubs.
+    // Re-applying it during a later initialization can downgrade already-added methods
+    // (e.g., SSR/streaming/RSC) back to stubs.
+    if (cachedObject !== null) {
+        Object.assign(cachedObject, ...capabilities.slice(1));
+        return cachedObject;
+    }
+    // ===================================================================
+    // ASSEMBLY — merge all capabilities in order
+    // ===================================================================
+    const reactOnRails = Object.assign({}, ...capabilities);
+    // Cache the object and registries
+    cachedObject = reactOnRails;
+    cachedRegistries = registries;
+    // ===================================================================
+    // GLOBAL ASSIGNMENT — only on first initialization
+    // ===================================================================
+    globalThis.ReactOnRails = reactOnRails;
+    // Reset options to defaults
+    reactOnRails.resetOptions();
+    // Run startup callback
+    if (startup) {
+        startup();
+    }
     return reactOnRails;
 }
 //# sourceMappingURL=createReactOnRails.js.map

package/lib/pageLifecycle.js

@@ -50,21 +50,33 @@ function initializePageEventListeners() {
         return;
     }
     isPageLifecycleInitialized = true;
-    // Important: replacing this condition with `document.readyState !== 'loading'` is not valid
-    // As the core ReactOnRails needs to ensure that all component bundles are loaded and executed before hydrating them
-    // If the `document.readyState === 'interactive'`, it doesn't guarantee that deferred scripts are executed
-    // the `readyState` can be `'interactive'` while the deferred scripts are still being executed
-    // Which will lead to the error `"Could not find component registered with name <component name>"`
-    // It will happen if this line is reached before the component chunk is executed on browser and reached the line
-    // ReactOnRails.register({ Component });
-    // ReactOnRailsPro is resellient against that type of race conditions, but it won't wait for that state anyway
-    // As it immediately hydrates the components at the page as soon as its html and bundle is loaded on the browser
-    // See pageLifecycle.test.js for unit tests validating this logic
+    // Important: replacing this condition with `document.readyState !== 'loading'` is not valid for
+    // the core page-load sweep. During `interactive`, deferred/module scripts may still be executing,
+    // and a component chunk may not yet have reached `ReactOnRails.register({ Component })`.
+    // Starting hydration too early can trigger "Could not find component registered" errors.
+    //
+    // However, async or dynamically-injected scripts can start after DOMContentLoaded has already fired
+    // while the document is still `interactive`. In that case, waiting only for DOMContentLoaded can miss
+    // initialization entirely, so we recover on the later `complete` transition.
+    //
+    // ReactOnRailsPro's early hydration path is more resilient to the registration race because it can
+    // hydrate components as their HTML and bundles arrive, but this page lifecycle still powers the
+    // fallback page-load sweep. See pageLifecycle.test.js for regression coverage of both cases.
     if (document.readyState === 'complete') {
         setupPageNavigationListeners();
     }
     else {
-        document.addEventListener('DOMContentLoaded', setupPageNavigationListeners);
+        const initialPageLoadHandler = (event) => {
+            if (event.type === 'readystatechange' && document.readyState !== 'complete')
+                return;
+            document.removeEventListener('DOMContentLoaded', initialPageLoadHandler);
+            document.removeEventListener('readystatechange', initialPageLoadHandler);
+            setupPageNavigationListeners();
+        };
+        document.addEventListener('DOMContentLoaded', initialPageLoadHandler);
+        if (document.readyState === 'interactive') {
+            document.addEventListener('readystatechange', initialPageLoadHandler);
+        }
     }
 }
 export function onPageLoaded(callback) {

package/lib/sanitizeNonce.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sanitizes a CSP nonce to prevent attribute injection attacks.
+ *
+ * Policy: sanitize-then-validate. Characters outside the base64/base64url alphabet
+ * are stripped first, then the result is validated against the expected nonce pattern.
+ * If the sanitized value does not match, `undefined` is returned and no nonce
+ * attribute will be emitted — the render proceeds without a nonce rather than
+ * failing or logging potentially sensitive values. Note that if stripping yields
+ * a string that still matches the base64/base64url pattern, that stripped value
+ * is returned.
+ *
+ * CSP nonces should be base64 or base64url strings with optional trailing `=` padding.
+ */
+export default function sanitizeNonce(nonce?: string): string | undefined;
+//# sourceMappingURL=sanitizeNonce.d.ts.map

package/lib/sanitizeNonce.js

@@ -0,0 +1,18 @@
+/**
+ * Sanitizes a CSP nonce to prevent attribute injection attacks.
+ *
+ * Policy: sanitize-then-validate. Characters outside the base64/base64url alphabet
+ * are stripped first, then the result is validated against the expected nonce pattern.
+ * If the sanitized value does not match, `undefined` is returned and no nonce
+ * attribute will be emitted — the render proceeds without a nonce rather than
+ * failing or logging potentially sensitive values. Note that if stripping yields
+ * a string that still matches the base64/base64url pattern, that stripped value
+ * is returned.
+ *
+ * CSP nonces should be base64 or base64url strings with optional trailing `=` padding.
+ */
+export default function sanitizeNonce(nonce) {
+    const nonceWithAllowedCharsOnly = nonce?.replace(/[^a-zA-Z0-9+/=_-]/g, '');
+    return nonceWithAllowedCharsOnly?.match(/^[a-zA-Z0-9+/_-]+={0,2}$/)?.[0];
+}
+//# sourceMappingURL=sanitizeNonce.js.map

package/lib/scriptSanitizedVal.d.ts

@@ -1,3 +1,3 @@
-declare const _default: (val: string) => string;
-export default _default;
+declare const scriptSanitizedVal: (val: string) => string;
+export default scriptSanitizedVal;
 //# sourceMappingURL=scriptSanitizedVal.d.ts.map

package/lib/scriptSanitizedVal.js

@@ -1,6 +1,7 @@
-export default (val) => {
+const scriptSanitizedVal = (val) => {
     // Replace closing
     const re = /<\/\W*script/gi;
     return val.replace(re, '(/script');
 };
+export default scriptSanitizedVal;
 //# sourceMappingURL=scriptSanitizedVal.js.map

package/lib/serverRenderReactComponent.d.ts

@@ -1,5 +1,5 @@
-import type { RenderParams, RenderResult } from './types/index.ts';
-declare function serverRenderReactComponentInternal(options: RenderParams): null | string | Promise<RenderResult>;
+import type { RenderParams } from './types/index.ts';
+declare function serverRenderReactComponentInternal(options: RenderParams): null | string | Promise<string>;
 declare const serverRenderReactComponent: typeof serverRenderReactComponentInternal;
 export default serverRenderReactComponent;
 //# sourceMappingURL=serverRenderReactComponent.d.ts.map

package/lib/serverRenderReactComponent.js

@@ -5,7 +5,7 @@ import { isPromise, isServerRenderHash } from "./isServerRenderResult.js";
 import { consoleReplay } from "./buildConsoleReplay.js";
 import handleError from "./handleError.js";
 import { renderToString } from "./ReactDOMServer.cjs";
-import { createResultObject, convertToError, validateComponent } from "./serverRenderUtils.js";
+import { buildLengthPrefixedResult, convertToError, validateComponent } from "./serverRenderUtils.js";
 function processServerRenderHash(result, options) {
     const { redirectLocation, routeError } = result;
     const hasErrors = !!routeError;
@@ -88,12 +88,12 @@ async function createPromiseResult(renderState, options, throwJsErrors) {
             ? processServerRenderHash(asyncResult, options)
             : { ...renderState, result: asyncResult };
         const consoleReplayScript = consoleReplay(consoleHistory);
-        return createResultObject(finalRenderState.result, consoleReplayScript, finalRenderState);
+        return buildLengthPrefixedResult(finalRenderState.result, consoleReplayScript, finalRenderState);
     }
     catch (e) {
         const errorRenderState = handleRenderingError(e, { componentName: options.componentName, throwJsErrors });
         const consoleReplayScript = consoleReplay(consoleHistory);
-        return createResultObject(errorRenderState.result, consoleReplayScript, errorRenderState);
+        return buildLengthPrefixedResult(errorRenderState.result, consoleReplayScript, errorRenderState);
     }
 }
 function createFinalResult(renderState, options, throwJsErrors) {
@@ -102,7 +102,7 @@ function createFinalResult(renderState, options, throwJsErrors) {
         return createPromiseResult({ ...renderState, result }, options, throwJsErrors);
     }
     const consoleReplayScript = consoleReplay();
-    return JSON.stringify(createResultObject(result, consoleReplayScript, renderState));
+    return buildLengthPrefixedResult(result, consoleReplayScript, renderState);
 }
 function serverRenderReactComponentInternal(options) {
     const { name: componentName, domNodeId, trace, props, railsContext, renderingReturnsPromises, throwJsErrors, } = options;

package/lib/serverRenderUtils.d.ts

@@ -1,5 +1,25 @@
-import type { RegisteredComponent, RenderResult, RenderState, StreamRenderState, FinalHtmlResult } from './types/index.ts';
-export declare function createResultObject(html: FinalHtmlResult | null, consoleReplayScript: string, renderState: RenderState | StreamRenderState): RenderResult;
+import type { RegisteredComponent, RenderingError, FinalHtmlResult } from './types/index.ts';
+/**
+ * Builds the metadata object for the length-prefixed streaming protocol.
+ * This is the shared metadata builder used by both streaming and non-streaming paths.
+ * It contains everything EXCEPT the html content, which travels as raw bytes.
+ */
+type RenderMetadataSource = {
+    clientProps?: Record<string, unknown>;
+    hasErrors?: boolean;
+    error?: RenderingError;
+    isShellReady?: boolean;
+};
+export declare function buildRenderMetadata(consoleReplayScript: string, renderState: RenderMetadataSource): Record<string, unknown>;
+/**
+ * Builds a length-prefixed result string from html content and render state.
+ * Format: <metadata JSON>\t<content byte length hex>\n<raw html content>
+ *
+ * Used by the non-streaming rendering path. The streaming path uses
+ * buildRenderMetadata directly with Buffer operations for efficiency.
+ */
+export declare function buildLengthPrefixedResult(html: FinalHtmlResult | null, consoleReplayScript: string, renderState: RenderMetadataSource): string;
 export declare function convertToError(e: unknown): Error;
 export declare function validateComponent(componentObj: RegisteredComponent, componentName: string): void;
+export {};
 //# sourceMappingURL=serverRenderUtils.d.ts.map

package/lib/serverRenderUtils.js

@@ -1,8 +1,7 @@
-export function createResultObject(html, consoleReplayScript, renderState) {
+export function buildRenderMetadata(consoleReplayScript, renderState) {
     return {
-        html,
-        clientProps: renderState.clientProps,
         consoleReplayScript,
+        clientProps: renderState.clientProps,
         hasErrors: renderState.hasErrors,
         renderingError: renderState.error && {
             message: renderState.error.message,
@@ -11,8 +10,94 @@ export function createResultObject(html, consoleReplayScript, renderState) {
         isShellReady: 'isShellReady' in renderState ? renderState.isShellReady : undefined,
     };
 }
+function isCrossRealmError(e) {
+    return typeof e === 'object' && e !== null && Object.prototype.toString.call(e) === '[object Error]';
+}
+function stringifyThrownValue(e) {
+    if (isCrossRealmError(e)) {
+        return typeof e.message === 'string' ? e.message : Object.prototype.toString.call(e);
+    }
+    if (typeof e === 'object' && e !== null) {
+        try {
+            // JSON.stringify can return undefined without throwing, for example when toJSON returns undefined.
+            return JSON.stringify(e) ?? Object.prototype.toString.call(e);
+        }
+        catch {
+            return Object.prototype.toString.call(e);
+        }
+    }
+    return String(e);
+}
+/**
+ * Returns the UTF-8 byte length of a string.
+ * Uses native Buffer.byteLength when available (Node.js, Pro node renderer).
+ * Falls back to a pure-JS implementation for environments without Buffer (mini_racer).
+ */
+function utf8ByteLength(str) {
+    if (typeof Buffer !== 'undefined' && typeof Buffer.byteLength === 'function') {
+        return Buffer.byteLength(str, 'utf-8');
+    }
+    let bytes = 0;
+    for (let i = 0; i < str.length; i += 1) {
+        const code = str.charCodeAt(i);
+        if (code <= 0x7f) {
+            bytes += 1;
+        }
+        else if (code <= 0x7ff) {
+            bytes += 2;
+        }
+        else if (code >= 0xd800 && code <= 0xdbff) {
+            const next = i + 1 < str.length ? str.charCodeAt(i + 1) : 0;
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4; // valid surrogate pair
+                i += 1;
+            }
+            else {
+                bytes += 3; // lone high surrogate → U+FFFD
+            }
+        }
+        else {
+            bytes += 3; // BMP char (0x800-0xFFFF) or lone low surrogate
+        }
+    }
+    return bytes;
+}
+/**
+ * Builds a length-prefixed result string from html content and render state.
+ * Format: <metadata JSON>\t<content byte length hex>\n<raw html content>
+ *
+ * Used by the non-streaming rendering path. The streaming path uses
+ * buildRenderMetadata directly with Buffer operations for efficiency.
+ */
+export function buildLengthPrefixedResult(html, consoleReplayScript, renderState) {
+    // payloadType tells Ruby how to interpret the content bytes:
+    //   "string" — raw HTML, use as-is (the common case)
+    //   "object" — JSON-serialized value, needs JSON.parse (ServerRenderHash or null)
+    const metadataObj = buildRenderMetadata(consoleReplayScript, renderState);
+    let htmlStr;
+    if (typeof html === 'string') {
+        metadataObj.payloadType = 'string';
+        htmlStr = html;
+    }
+    else {
+        // Handles null, ServerRenderHashRenderedHtml objects, etc.
+        // JSON.stringify(null) → "null", which Ruby will JSON.parse back.
+        metadataObj.payloadType = 'object';
+        htmlStr = JSON.stringify(html);
+    }
+    const metadata = JSON.stringify(metadataObj);
+    const byteLength = utf8ByteLength(htmlStr);
+    return `${metadata}\t${byteLength.toString(16).padStart(8, '0')}\n${htmlStr}`;
+}
 export function convertToError(e) {
-    return e instanceof Error ? e : new Error(String(e));
+    if (e instanceof Error) {
+        return e;
+    }
+    const message = stringifyThrownValue(e);
+    // tsconfig uses es2020 libs, which do not type Error.cause even though supported runtimes provide it.
+    const error = new Error(message);
+    error.cause = e;
+    return error;
 }
 export function validateComponent(componentObj, componentName) {
     if (componentObj.isRenderer) {

package/lib/types/index.d.ts

@@ -77,6 +77,11 @@ type RenderFunctionSyncResult = ReactComponent | ServerRenderResult;
 type RenderFunctionAsyncResult = Promise<string | ServerRenderHashRenderedHtml | ReactComponent | ServerRenderResult>;
 type RenderFunctionResult = RenderFunctionSyncResult | RenderFunctionAsyncResult;
 type StreamableComponentResult = ReactElement | Promise<ReactElement | string>;
+type AsyncPropsManager = {
+    getProp: (propName: string) => Promise<unknown>;
+    setProp: (propName: string, propValue: unknown) => void;
+    endStream: () => void;
+};
 /**
  * Render-functions are used to create dynamic React components or server-rendered HTML with side effects.
  * They receive two arguments: props and railsContext.
@@ -119,11 +124,13 @@ export interface RegisteredComponent {
     isRenderer: boolean;
 }
 export type ItemRegistrationCallback<T> = (component: T) => void;
+export type GenerateRSCPayloadFunction = (componentName: string, props: unknown, railsContext: RailsContextWithServerComponentMetadata) => Promise<NodeJS.ReadableStream>;
 interface Params {
     props?: Record<string, unknown>;
     railsContext?: RailsContext;
     domNodeId?: string;
     trace?: boolean;
+    generateRSCPayload?: GenerateRSCPayloadFunction;
 }
 export interface RenderParams extends Params {
     name: string;
@@ -245,6 +252,9 @@ export type RSCPayloadStreamInfo = {
     componentName: string;
 };
 export type RSCPayloadCallback = (streamInfo: RSCPayloadStreamInfo) => void;
+export type WithAsyncProps<AsyncPropsType extends Record<string, unknown>, PropsType extends Record<string, unknown>> = PropsType & {
+    getReactOnRailsAsyncProp: <PropName extends keyof AsyncPropsType>(propName: PropName) => Promise<AsyncPropsType[PropName]>;
+};
 /** Contains the parts of the `ReactOnRails` API intended for internal use only. */
 export interface ReactOnRailsInternal extends ReactOnRails {
     /**
@@ -312,7 +322,7 @@ export interface ReactOnRailsInternal extends ReactOnRails {
     /**
      * Used by server rendering by Rails
      */
-    serverRenderReactComponent(options: RenderParams): null | string | Promise<RenderResult>;
+    serverRenderReactComponent(options: RenderParams): null | string | Promise<string>;
     /**
      * Used by server rendering by Rails
      */
@@ -325,6 +335,11 @@ export interface ReactOnRailsInternal extends ReactOnRails {
      * Used by Rails to catch errors in rendering
      */
     handleError(options: ErrorOptions): string | undefined;
+    /**
+     * Prepares a rendering result in the length-prefixed wire format for transport to Ruby.
+     * Used by the server_render_js Rails helper to format arbitrary JS evaluation results.
+     */
+    prepareRenderResult(html: string, consoleReplayScript: string, hasErrors: boolean, renderingError: RenderingError | null): string;
     /**
      * Used by Rails server rendering to replay console messages.
      * Returns the console replay script wrapped in script tags.
@@ -359,6 +374,27 @@ export interface ReactOnRailsInternal extends ReactOnRails {
      * Indicates if the RSC bundle is being used.
      */
     isRSCBundle: boolean;
+    /**
+     * Adds the getAsyncProp function to the component props object.
+     * Uses getOrCreateAsyncPropsManager internally to handle race conditions
+     * between initial render and update chunks.
+     *
+     * @param props - The component props to enhance
+     * @param sharedExecutionContext - Map scoped to the current HTTP request
+     * @returns An object containing the component props with getReactOnRailsAsyncProp added
+     */
+    addAsyncPropsCapabilityToComponentProps: <AsyncPropsType extends Record<string, unknown>, PropsType extends Record<string, unknown>>(props: PropsType, sharedExecutionContext: Map<string, unknown>) => {
+        props: WithAsyncProps<AsyncPropsType, PropsType>;
+    };
+    /**
+     * Gets or creates an AsyncPropsManager from the shared execution context.
+     * Implements lazy initialization to handle race conditions between
+     * the initial render request and update chunks.
+     *
+     * @param sharedExecutionContext - Map scoped to the current HTTP request
+     * @returns The AsyncPropsManager instance (existing or newly created)
+     */
+    getOrCreateAsyncPropsManager: (sharedExecutionContext: Map<string, unknown>) => AsyncPropsManager;
 }
 export type RenderStateHtml = FinalHtmlResult | Promise<FinalHtmlResult | ServerRenderResult>;
 export type RenderState = {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "react-on-rails",
-  "version": "16.6.0",
+  "version": "16.7.0-rc.0",
   "description": "react-on-rails JavaScript for react_on_rails Ruby gem",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shakacode/react_on_rails.git"
+    "url": "git+https://github.com/shakacode/react_on_rails.git",
+    "directory": "packages/react-on-rails"
   },
   "keywords": [
     "react",
@@ -40,10 +41,17 @@
     "./buildConsoleReplay": "./lib/buildConsoleReplay.js",
     "./ReactDOMServer": "./lib/ReactDOMServer.cjs",
     "./serverRenderReactComponent": "./lib/serverRenderReactComponent.js",
+    "./@internal/sanitizeNonce": "./lib/sanitizeNonce.js",
     "./@internal/base/client": "./lib/base/client.js",
     "./@internal/base/full": {
       "react-server": "./lib/base/full.rsc.js",
       "default": "./lib/base/full.js"
+    },
+    "./@internal/createReactOnRails": "./lib/createReactOnRails.js",
+    "./@internal/capabilities/core": "./lib/capabilities/core.js",
+    "./@internal/capabilities/ssr": {
+      "react-server": "./lib/capabilities/ssr.rsc.js",
+      "default": "./lib/capabilities/ssr.js"
     }
   },
   "peerDependencies": {
@@ -60,7 +68,7 @@
   "bugs": {
     "url": "https://github.com/shakacode/react_on_rails/issues"
   },
-  "homepage": "https://github.com/shakacode/react_on_rails#readme",
+  "homepage": "https://reactonrails.com/docs/",
   "scripts": {
     "build": "pnpm run clean && tsc",
     "build-watch": "pnpm run clean && tsc --watch",