react-on-rails 17.0.0-rc.5 → 17.0.0-rc.7

package/README.md

@@ -81,11 +81,12 @@ ReactOnRails.register({
 
 ## Exports
 
-| Export Path             | Description                         |
-| ----------------------- | ----------------------------------- |
-| `react-on-rails`        | Full build with SSR utilities       |
-| `react-on-rails/client` | Client-only build (smaller, no SSR) |
-| `react-on-rails/types`  | TypeScript type exports             |
+| Export Path                  | Description                          |
+| ---------------------------- | ------------------------------------ |
+| `react-on-rails`             | Full build with SSR utilities        |
+| `react-on-rails/client`      | Client-only build (smaller, no SSR)  |
+| `react-on-rails/railsAction` | CSRF-aware typed Rails action caller |
+| `react-on-rails/types`       | TypeScript type exports              |
 
 ## Rails-Side Setup
 

package/lib/ClientRenderer.js

@@ -8,6 +8,7 @@ import { onPageUnloaded } from "./pageLifecycle.js";
 import { supportsRootApi, unmountComponentAtNode } from "./reactApis.cjs";
 import { isRendererTeardownResult } from "./rendererTeardown.js";
 import { buildRootErrorCallbackOptions } from "./rootErrorHandlers.js";
+import { convertToError } from "./errorUtils.js";
 import { isThenable } from "./isThenable.js";
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
 // Track all rendered roots for cleanup
@@ -16,8 +17,8 @@ const renderedRoots = new Map();
  * Invokes a renderer teardown, swallowing async rejections so a failing teardown cannot produce an
  * unhandled promise rejection. Synchronous throws propagate to the caller's try/catch. `domNodeId`
  * is included in the log so a failure can be traced to its mount.
- * MUST SYNC: A sibling helper exists in packages/react-on-rails-pro/src/ClientSideRenderer.ts. If you
- * change the error-handling logic or log format here, update that copy too.
+ * MIRROR OF: packages/react-on-rails-pro/src/ClientSideRenderer.ts (sibling helper). If you change
+ * the error-handling logic or log format here, update that copy too.
  */
 function invokeRendererTeardown(teardown, domNodeId) {
     if (!teardown)
@@ -39,6 +40,10 @@ function invokeRendererTeardown(teardown, domNodeId) {
  * abort cleanup of the remaining entries.
  */
 function teardownEntry(entry, domNodeId) {
+    if (entry.kind === 'scheduled') {
+        entry.cancel();
+        return;
+    }
     if (entry.kind === 'renderer') {
         invokeRendererTeardown(entry.teardown, domNodeId);
         return;
@@ -52,6 +57,15 @@ function teardownEntry(entry, domNodeId) {
         unmountComponentAtNode(entry.domNode);
     }
 }
+function teardownErrorLabel(entry, domNodeId) {
+    if (entry.kind === 'renderer') {
+        return `Error in renderer teardown for dom node "${domNodeId}":`;
+    }
+    if (entry.kind === 'scheduled') {
+        return `Error canceling scheduled render for dom node "${domNodeId}":`;
+    }
+    return `Error unmounting component for dom node "${domNodeId}":`;
+}
 function initializeStore(el, railsContext) {
     const name = el.getAttribute(REACT_ON_RAILS_STORE_ATTRIBUTE) || '';
     const props = el.textContent !== null ? JSON.parse(el.textContent) : {};
@@ -68,6 +82,103 @@ function forEachStore(railsContext) {
 function domNodeIdForEl(el) {
     return el.getAttribute('data-dom-id') || '';
 }
+function hydrateOnForEl(el) {
+    const hydrateOn = el.getAttribute('data-hydrate-on');
+    if (!hydrateOn || hydrateOn === 'immediate' || hydrateOn === 'visible' || hydrateOn === 'idle') {
+        return (hydrateOn || 'immediate');
+    }
+    console.warn(`[react-on-rails] Unsupported hydrate_on: ${hydrateOn}.`);
+    return 'immediate';
+}
+function hasObservableArea(element) {
+    const rects = element.getClientRects();
+    for (let index = 0; index < rects.length; index += 1) {
+        const rect = rects[index];
+        if (rect.width > 0 && rect.height > 0)
+            return true;
+    }
+    const boundingRect = element.getBoundingClientRect();
+    return boundingRect.width > 0 && boundingRect.height > 0;
+}
+function scheduleTimeout(callback, delay) {
+    const timeoutId = window.setTimeout(callback, delay);
+    return () => window.clearTimeout(timeoutId);
+}
+function scheduleWhenVisible(domNode, callback) {
+    if (typeof IntersectionObserver === 'undefined') {
+        console.warn('[react-on-rails] No IntersectionObserver.');
+        return scheduleTimeout(callback, 0);
+    }
+    if (!domNode.hasChildNodes() && !hasObservableArea(domNode)) {
+        return scheduleTimeout(callback, 0);
+    }
+    const observer = new IntersectionObserver((entries) => {
+        // Disconnect early if the target was removed outside Turbo navigation to avoid a
+        // leaked observer holding a live reference to a detached node.
+        const target = entries[0]?.target;
+        if (target && !target.isConnected) {
+            observer.disconnect();
+            callback();
+            return;
+        }
+        const isVisible = entries.some((entry) => entry.isIntersecting || entry.intersectionRatio > 0);
+        if (!isVisible)
+            return;
+        observer.disconnect();
+        callback();
+    }, { rootMargin: '200px 0px' });
+    observer.observe(domNode);
+    return () => {
+        observer.disconnect();
+    };
+}
+function scheduleWhenIdle(callback) {
+    const idleWindow = window;
+    if (typeof idleWindow.requestIdleCallback === 'function') {
+        const idleCallbackId = idleWindow.requestIdleCallback(callback, { timeout: 2000 });
+        return () => {
+            if (typeof idleWindow.cancelIdleCallback === 'function') {
+                idleWindow.cancelIdleCallback(idleCallbackId);
+            }
+        };
+    }
+    // Safari lacks requestIdleCallback; 50 ms defers past the current frame without a layout-blocking
+    // setTimeout(0) but still far enough before most long-idle periods (matching common polyfill defaults).
+    return scheduleTimeout(callback, 50);
+}
+function scheduleHydration(hydrateOn, domNode, callback) {
+    if (hydrateOn === 'visible') {
+        return scheduleWhenVisible(domNode, callback);
+    }
+    if (hydrateOn === 'idle') {
+        return scheduleWhenIdle(callback);
+    }
+    // Defensive: `renderElement` short-circuits for `immediate` before calling `scheduleHydration`, so
+    // this branch is normally unreachable; it acts as a safe fallback guard for future callers.
+    callback();
+    return () => { };
+}
+// Logs a normalized copy of the original thrown value, then returns a fresh ReactOnRails-prefixed
+// error for callers to throw/report. This must not mutate the original value: user code can throw
+// strings, null, cross-realm errors, or frozen Error instances, and delayed hydration catches run
+// inside scheduler callbacks where an error reporter that throws would escape the callback.
+function prepareRenderError(componentName, error) {
+    const originalError = convertToError(error);
+    console.error(originalError);
+    const renderError = new Error(`ReactOnRails encountered an error while rendering component: ${componentName}. See above error message.`);
+    renderError.cause = originalError;
+    if (typeof originalError.stack === 'string') {
+        renderError.stack = originalError.stack;
+    }
+    return renderError;
+}
+function raiseRenderError(componentName, error) {
+    throw prepareRenderError(componentName, error);
+}
+function reportRenderError(componentName, error) {
+    // prepareRenderError already logged the original error; do not log again (avoids the double-log).
+    prepareRenderError(componentName, error);
+}
 function delegateToRenderer(componentObj, props, railsContext, domNodeId, trace) {
     const { name, component, isRenderer } = componentObj;
     if (isRenderer) {
@@ -160,7 +271,9 @@ function trackRendererMount(domNodeId, domNode, result) {
  * delegates to a renderer registered by the user.
  */
 function renderElement(el, railsContext) {
-    // This must match lib/react_on_rails/helper.rb
+    // This must match the data-* attributes emitted by lib/react_on_rails/pro_helper.rb.
+    // Covered end-to-end by every spec/dummy client-rendering test (renaming either side fails
+    // loudly), so no MIRROR VALUES guard is added here.
     const name = el.getAttribute('data-component-name') || '';
     const domNodeId = domNodeIdForEl(el);
     const props = el.textContent !== null ? JSON.parse(el.textContent) : {};
@@ -173,10 +286,14 @@ function renderElement(el, railsContext) {
             // (e.g., for asynchronously loaded content)
             const existing = renderedRoots.get(domNodeId);
             if (existing) {
-                // Only skip if it's the exact same DOM node and it's still connected to the document.
-                // If the node was replaced (e.g., via innerHTML or Turbo), we need to unmount the old
-                // root and re-render to the new node to prevent memory leaks and ensure rendering works.
-                const sameNode = existing.domNode === domNode && existing.domNode.isConnected;
+                // Only skip if it's the exact same DOM node, it's still connected to the document, AND it has
+                // actually mounted. A `scheduled` entry has not mounted yet: if its node was detached and later
+                // reattached (e.g. Turbo cache restore or a DOM move), its IntersectionObserver was disconnected
+                // and will never re-observe, so we must fall through to cancel the stale schedule and re-schedule
+                // fresh rather than skip (which would leave the island permanently non-interactive).
+                // If the node was replaced (e.g., via innerHTML or Turbo), we likewise need to unmount/cancel the
+                // old entry and re-render to the new node to prevent memory leaks and ensure rendering works.
+                const sameNode = existing.kind !== 'scheduled' && existing.domNode === domNode && existing.domNode.isConnected;
                 if (sameNode) {
                     if (trace) {
                         console.log(`Skipping already rendered component: ${name} (dom id: ${domNodeId})`);
@@ -192,10 +309,7 @@ function renderElement(el, railsContext) {
                     // Surface the failure unconditionally (matching unmountAllComponents) so a teardown/unmount
                     // error on node replacement is as visible as one on page unload, using the same greppable
                     // labels. We still continue: the old mount may leak, but the new node must be rendered.
-                    const label = existing.kind === 'renderer'
-                        ? `Error in renderer teardown for dom node "${domNodeId}":`
-                        : `Error unmounting component for dom node "${domNodeId}":`;
-                    console.error(label, unmountError);
+                    console.error(teardownErrorLabel(existing, domNodeId), unmountError);
                 }
                 renderedRoots.delete(domNodeId);
             }
@@ -207,38 +321,62 @@ function renderElement(el, railsContext) {
                 trackRendererMount(domNodeId, domNode, delegation.result);
                 return;
             }
-            // Hydrate if the DOM node has content (server-rendered HTML)
-            // Since we skip already-rendered components above, this check now correctly
-            // identifies only server-rendered content, not previously client-rendered content
-            const shouldHydrate = !!domNode.innerHTML;
-            const reactElementOrRouterResult = createReactOutput({
-                componentObj,
-                props,
-                domNodeId,
-                trace,
-                railsContext,
-                shouldHydrate,
-            });
-            if (isServerRenderHash(reactElementOrRouterResult)) {
-                throw new Error(`\
+            const mountReactRoot = () => {
+                // Hydrate if the DOM node has content (server-rendered HTML)
+                // Since we skip already-rendered components above, this check now correctly
+                // identifies only server-rendered content, not previously client-rendered content
+                const shouldHydrate = !!domNode.innerHTML;
+                const reactElementOrRouterResult = createReactOutput({
+                    componentObj,
+                    props,
+                    domNodeId,
+                    trace,
+                    railsContext,
+                    shouldHydrate,
+                });
+                if (isServerRenderHash(reactElementOrRouterResult)) {
+                    throw new Error(`\
 You returned a server side type of react-router error: ${JSON.stringify(reactElementOrRouterResult)}
 You should return a React.Component always for the client side entry point.`);
-            }
-            else {
+                }
                 const root = reactHydrateOrRender(domNode, reactElementOrRouterResult, shouldHydrate, 
                 // Attach user-registered root error callbacks (and the dev-mode hydration-mismatch
                 // logger) to every root, enriched with this mount's component name and dom id.
                 buildRootErrorCallbackOptions({ componentName: name || undefined, domNodeId: domNodeId || undefined }, shouldHydrate));
                 // Track the root for cleanup
                 renderedRoots.set(domNodeId, { kind: 'react', root, domNode });
+            };
+            const hydrateOn = hydrateOnForEl(el);
+            if (hydrateOn === 'immediate') {
+                mountReactRoot();
+                return;
             }
+            let scheduledEntry;
+            const runScheduledRender = () => {
+                if (renderedRoots.get(domNodeId) !== scheduledEntry)
+                    return;
+                if (!domNode.isConnected) {
+                    renderedRoots.delete(domNodeId);
+                    return;
+                }
+                try {
+                    mountReactRoot();
+                }
+                catch (scheduledError) {
+                    renderedRoots.delete(domNodeId);
+                    reportRenderError(name, scheduledError);
+                }
+            };
+            scheduledEntry = {
+                kind: 'scheduled',
+                domNode,
+                cancel: scheduleHydration(hydrateOn, domNode, runScheduledRender),
+            };
+            renderedRoots.set(domNodeId, scheduledEntry);
         }
     }
     catch (e) {
-        const error = e;
-        console.error(error.message);
-        error.message = `ReactOnRails encountered an error while rendering component: ${name}. See above error message.`;
-        throw error;
+        raiseRenderError(name, e);
     }
 }
 /**
@@ -295,12 +433,7 @@ function unmountAllComponents() {
             teardownEntry(entry, domNodeId);
         }
         catch (error) {
-            // Use the same label as the async-rejection path so renderer-teardown failures are greppable
-            // whether the teardown threw synchronously (here) or rejected (invokeRendererTeardown).
-            const label = entry.kind === 'renderer'
-                ? `Error in renderer teardown for dom node "${domNodeId}":`
-                : `Error unmounting component for dom node "${domNodeId}":`;
-            console.error(label, error);
+            console.error(teardownErrorLabel(entry, domNodeId), error);
         }
     });
     renderedRoots.clear();

package/lib/StoreRegistry.d.ts

@@ -29,6 +29,10 @@ declare const _default: {
      * Internally used function to completely clear hydratedStores Map.
      */
     clearHydratedStores(): void;
+    /**
+     * Internally used function to completely clear registeredStoreGenerators Map.
+     */
+    clearStoreGenerators(): void;
     /**
      * Get a Map containing all registered store generators. Useful for debugging.
      * @returns Map where key is the component name and values are the store generators.

package/lib/StoreRegistry.js

@@ -33,6 +33,9 @@ export default {
         if (hydratedStores.has(name)) {
             return hydratedStores.get(name);
         }
+        if (!throwIfMissing) {
+            return undefined;
+        }
         const storeKeys = Array.from(hydratedStores.keys()).join(', ');
         if (storeKeys.length === 0) {
             const msg = `There are no stores hydrated and you are requesting the store ${name}.
@@ -42,12 +45,8 @@ This can happen if you are server rendering and either:
 2. You do not render redux_store_hydration_data anywhere on your page.`;
             throw new Error(msg);
         }
-        if (throwIfMissing) {
-            console.log('storeKeys', storeKeys);
-            throw new Error(`Could not find hydrated store with name '${name}'. ` +
-                `Hydrated store names include [${storeKeys}].`);
-        }
-        return undefined;
+        console.log('storeKeys', storeKeys);
+        throw new Error(`Could not find hydrated store with name '${name}'. Hydrated store names include [${storeKeys}].`);
     },
     /**
      * Internally used function to get the store creator that was passed to `register`.
@@ -77,6 +76,12 @@ This can happen if you are server rendering and either:
     clearHydratedStores() {
         hydratedStores.clear();
     },
+    /**
+     * Internally used function to completely clear registeredStoreGenerators Map.
+     */
+    clearStoreGenerators() {
+        registeredStoreGenerators.clear();
+    },
     /**
      * Get a Map containing all registered store generators. Useful for debugging.
      * @returns Map where key is the component name and values are the store generators.

package/lib/base/client.d.ts

@@ -16,6 +16,7 @@ interface Registries {
         getStoreGenerator: (name: string) => StoreGenerator;
         setStore: (name: string, store: Store) => void;
         clearHydratedStores: () => void;
+        clearStoreGenerators: () => void;
         storeGenerators: () => Map<string, StoreGenerator>;
         stores: () => Map<string, Store>;
     };

package/lib/base/client.js

@@ -2,23 +2,27 @@
  * @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";
-import createReactOutput from "../createReactOutput.js";
-import componentRegistrationMetric from "../componentRegistrationMetric.js";
-import { buildRootErrorCallbackOptions, getRootErrorHandlers, resetRootErrorHandlers, setRootErrorHandlers, } from "../rootErrorHandlers.js";
-const DEFAULT_OPTIONS = {
-    traceTurbolinks: false,
-    turbo: false,
-    debugMode: false,
-    logComponentRegistration: false,
-};
+import { createCoreCapability } from "../capabilities/core.js";
+// Pro-only methods that `createCoreCapability` includes as stubs but the historical base
+// surface omits. This list drives the runtime key-stripping in `createBaseClientObject`.
+// `satisfies readonly (keyof ReactOnRailsInternal)[]` makes a typo or a stale name a compile
+// error, and the `assertProOnlyMethodsMatchOmit` guard inside `createBaseClientObject` pins this
+// list to the `Omit<...>` in `BaseClientObjectType` so the runtime list and the exported type can
+// never drift.
+const PRO_ONLY_METHODS = [
+    'getOrWaitForComponent',
+    'getOrWaitForStore',
+    'getOrWaitForStoreGenerator',
+    'reactOnRailsStoreLoaded',
+    'streamServerRenderedReactComponent',
+    'serverRenderRSCReactComponent',
+    'addAsyncPropsCapabilityToComponentProps',
+    'getOrCreateAsyncPropsManager',
+];
 // Cache to track created objects and their registries
 let cachedObject = null;
 let cachedRegistries = null;
 export function createBaseClientObject(registries, currentObject = null) {
-    const { ComponentRegistry, StoreRegistry } = registries;
     // Error detection: currentObject is null but we have a cached object
     // This indicates webpack misconfiguration (multiple runtime chunks)
     if (currentObject === null && cachedObject !== null) {
@@ -60,168 +64,25 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
     if (cachedObject !== null) {
         return cachedObject;
     }
-    // Create and return new object
-    const obj = {
-        options: {},
-        isRSCBundle: false,
-        // ===================================================================
-        // STABLE METHOD IMPLEMENTATIONS - Core package implementations
-        // ===================================================================
-        authenticityToken() {
-            return Authenticity.authenticityToken();
-        },
-        authenticityHeaders(otherHeaders = {}) {
-            return Authenticity.authenticityHeaders(otherHeaders);
-        },
-        reactHydrateOrRender(domNode, reactElement, hydrate) {
-            // The component name is unknown on this low-level path; the dom id still ties errors to a mount.
-            const rootErrorCallbackOptions = buildRootErrorCallbackOptions({ domNodeId: domNode.id || undefined }, hydrate);
-            return reactHydrateOrRender(domNode, reactElement, hydrate, rootErrorCallbackOptions);
-        },
-        setOptions(newOptions) {
-            const { traceTurbolinks, turbo, debugMode, logComponentRegistration, rootErrorHandlers, ...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.prototype.hasOwnProperty.call(newOptions, 'rootErrorHandlers')) {
-                // MUST SYNC: sibling implementation exists in packages/react-on-rails/src/capabilities/core.ts.
-                // Validates and merges the handlers per key (partial updates keep previously registered
-                // callbacks); warns when the React runtime cannot support them. Store the merged result so
-                // `option('rootErrorHandlers')` reflects the effective registration.
-                if (typeof rootErrorHandlers === 'undefined') {
-                    resetRootErrorHandlers();
-                    this.options.rootErrorHandlers = undefined;
-                }
-                else {
-                    setRootErrorHandlers(rootErrorHandlers);
-                    this.options.rootErrorHandlers = getRootErrorHandlers();
-                }
-            }
-            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 };
-            resetRootErrorHandlers();
-        },
-        // ===================================================================
-        // 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 registrationMetric = componentRegistrationMetric(component);
-                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${registrationMetric.value} ${registrationMetric.label})`);
-                    });
-                }
-            }
-            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 reactHydrateOrRender(document.getElementById(domNodeId), reactElement, hydrate, buildRootErrorCallbackOptions({ componentName: name || undefined, domNodeId: domNodeId || undefined }, hydrate));
-        },
-        // ===================================================================
-        // CLIENT-SIDE RENDERING STUBS - To be overridden by createReactOnRails
-        // ===================================================================
-        reactOnRailsPageLoaded() {
-            throw new Error('ReactOnRails.reactOnRailsPageLoaded is not initialized. This is a bug in react-on-rails.');
-        },
-        reactOnRailsComponentLoaded(domId) {
-            void domId; // Mark as used
-            throw new Error('ReactOnRails.reactOnRailsComponentLoaded is not initialized. This is a bug in react-on-rails.');
-        },
-        // ===================================================================
-        // SSR STUBS - Will throw errors in client bundle, overridden in full
-        // ===================================================================
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        serverRenderReactComponent(...args) {
-            void args; // Mark as used
-            throw new Error('serverRenderReactComponent is not available in "react-on-rails/client". Import "react-on-rails" server-side.');
-        },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        handleError(...args) {
-            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.');
-        },
+    const assertProOnlyMethodsMatchOmit = true;
+    void assertProOnlyMethodsMatchOmit;
+    // Delegate the core method implementations to `createCoreCapability` (the canonical source),
+    // then re-shape to the historical base surface: strip the Pro-only stubs (using the shared
+    // `PRO_ONLY_METHODS` list that the drift guard above pins to `BaseClientObjectType`, so runtime
+    // and type can never drift) and add the client-side lifecycle stubs that `createReactOnRails`
+    // overrides at initialization.
+    const proOnlyMethods = new Set(PRO_ONLY_METHODS);
+    const core = createCoreCapability(registries);
+    const obj = Object.fromEntries(Object.entries(core).filter(([key]) => !proOnlyMethods.has(key)));
+    // ===================================================================
+    // CLIENT-SIDE RENDERING STUBS - To be overridden by createReactOnRails
+    // ===================================================================
+    obj.reactOnRailsPageLoaded = () => {
+        throw new Error('ReactOnRails.reactOnRailsPageLoaded is not initialized. This is a bug in react-on-rails.');
+    };
+    obj.reactOnRailsComponentLoaded = (domId) => {
+        void domId; // Mark as used
+        throw new Error('ReactOnRails.reactOnRailsComponentLoaded is not initialized. This is a bug in react-on-rails.');
     };
     // Cache the object and registries
     cachedObject = obj;

package/lib/base/full.js

@@ -2,35 +2,17 @@
  * @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`.
  */
+// This is a thin compatibility shim: the SSR implementations live in `capabilities/ssr.ts`
+// (`createSSRCapability`). This file composes them onto the base client object, preserving
+// the historical `createBaseFullObject` surface old Pro consumers rely on.
 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. ' +
-        'Browsers may not need it. 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.');
-}
+import { createSSRCapability } from "../capabilities/ssr.js";
 export function createBaseFullObject(registries, currentObject = null) {
     // Get or create client object (with caching logic)
     const clientObject = createBaseClientObject(registries, currentObject);
-    // Define SSR-specific functions with proper types
-    // This object acts as a type-safe specification of what we're adding to the base object
-    const reactOnRailsFullSpecificFunctions = {
-        handleError(options) {
-            return handleError(options);
-        },
-        serverRenderReactComponent(options) {
-            return serverRenderReactComponent(options);
-        },
-        prepareRenderResult(html, consoleReplayScript, hasErrors, renderingError) {
-            return buildLengthPrefixedResult(html, consoleReplayScript, {
-                hasErrors,
-                error: renderingError ?? undefined,
-            });
-        },
-    };
+    // Delegate the SSR-specific functions to `createSSRCapability` (the canonical source).
+    // Typed to ReactOnRailsFullSpecificFunctions so we add exactly the SSR surface, nothing more.
+    const reactOnRailsFullSpecificFunctions = createSSRCapability();
     // Type assertion is safe here because:
     // 1. We start with BaseClientObjectType (from createBaseClientObject)
     // 2. We add exactly the methods defined in ReactOnRailsFullSpecificFunctions