react-on-rails 17.0.0-rc.1 → 17.0.0-rc.2

package/lib/ClientRenderer.js

@@ -6,9 +6,56 @@ import { getRailsContext } from "./context.js";
 import { isServerRenderHash } from "./isServerRenderResult.js";
 import { onPageUnloaded } from "./pageLifecycle.js";
 import { supportsRootApi, unmountComponentAtNode } from "./reactApis.cjs";
+import { isRendererTeardownResult } from "./rendererTeardown.js";
 const REACT_ON_RAILS_STORE_ATTRIBUTE = 'data-js-react-on-rails-store';
+/** Narrows an unknown value to a thenable (has a callable `.then`) without assuming a native Promise. */
+function isThenable(value) {
+    return (value != null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
 // Track all rendered roots for cleanup
 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.
+ */
+function invokeRendererTeardown(teardown, domNodeId) {
+    if (!teardown)
+        return;
+    const maybePromise = teardown();
+    if (isThenable(maybePromise)) {
+        // Detect a thenable with `.then` (Promises/A+) but swallow the rejection via
+        // `Promise.resolve(...).catch(...)`: a non-native thenable may lack `.catch`, so calling it
+        // directly could itself throw or leave the rejection unhandled. This keeps a failing async
+        // teardown from surfacing as an unhandled promise rejection.
+        Promise.resolve(maybePromise).catch((error) => {
+            console.error(`Error in renderer teardown for dom node "${domNodeId}":`, error);
+        });
+    }
+}
+/**
+ * Tears down a single tracked entry: runs the renderer's teardown, or unmounts the React root.
+ * Synchronous errors are not caught here; callers wrap this in try/catch so one failure does not
+ * abort cleanup of the remaining entries.
+ */
+function teardownEntry(entry, domNodeId) {
+    if (entry.kind === 'renderer') {
+        invokeRendererTeardown(entry.teardown, domNodeId);
+        return;
+    }
+    if (supportsRootApi && entry.root && typeof entry.root === 'object' && 'unmount' in entry.root) {
+        // React 18+ Root API
+        entry.root.unmount();
+    }
+    else {
+        // React 16-17 legacy API
+        unmountComponentAtNode(entry.domNode);
+    }
+}
 function initializeStore(el, railsContext) {
     const name = el.getAttribute(REACT_ON_RAILS_STORE_ATTRIBUTE) || '';
     const props = el.textContent !== null ? JSON.parse(el.textContent) : {};
@@ -32,11 +79,85 @@ function delegateToRenderer(componentObj, props, railsContext, domNodeId, trace)
             console.log(`\
 DELEGATING TO RENDERER ${name} for dom node with id: ${domNodeId} with props, railsContext:`, props, railsContext);
         }
-        // Call the renderer function with the expected signature
-        component(props, railsContext, domNodeId);
-        return true;
+        // Call the renderer function with the expected signature. A renderer owns its own mount and may
+        // return nothing, a teardown wrapper, or a promise resolving to one. `component` is the registered
+        // component union, so `as RendererFunction` is a runtime-invariant assertion guarded by
+        // `isRenderer` (the registry only sets it for a 3-arg render function), not a structural
+        // narrowing.
+        if (typeof component !== 'function') {
+            throw new Error(`Registered renderer "${name}" must be a function.`);
+        }
+        const result = component(props, railsContext, domNodeId);
+        return { delegated: true, result };
+    }
+    return { delegated: false };
+}
+/**
+ * Records a renderer-function mount and captures its optional teardown. The renderer may return a
+ * teardown wrapper synchronously, or a promise resolving to one (async renderers). The entry is
+ * stored immediately so the replaced-node path can find it even before an async teardown resolves.
+ *
+ * Known limitation (core package): if the mount is unmounted or its node is replaced *before* an
+ * async renderer resolves its teardown, the still-pending teardown is dropped and that one mount
+ * leaks — the resolved teardown is discarded because the entry is no longer the active mount for
+ * this id (the `renderedRoots.get(domNodeId) === entry` guard below). The drop is an expected,
+ * documented core limitation, but it still leaves a renderer-owned mount uncleaned, so it is logged
+ * with `console.error` rather than silently ignored. Synchronous teardowns are unaffected. The Pro
+ * client renderer (`react-on-rails-pro`) awaits the renderer and re-checks the unmount state, so it
+ * runs the teardown even when a navigation races the resolve; prefer Pro if you depend on async
+ * renderer teardowns surviving fast navigations.
+ *
+ * Renderer results that ultimately do not include a teardown wrapper are left untracked:
+ * synchronous no-wrapper returns are not stored, and async results that resolve without a wrapper use
+ * only a temporary placeholder until the promise settles. Before this cleanup contract existed,
+ * renderer-owned mounts were never tracked, so repeated page-loaded calls re-invoked those legacy
+ * renderers; preserving that behavior keeps "return nothing" backward compatible.
+ */
+function trackRendererMount(domNodeId, domNode, result) {
+    if (isRendererTeardownResult(result)) {
+        renderedRoots.set(domNodeId, { kind: 'renderer', domNode, teardown: result.teardown });
+    }
+    else if (isThenable(result)) {
+        const entry = { kind: 'renderer', domNode, teardown: undefined };
+        renderedRoots.set(domNodeId, entry);
+        Promise.resolve(result)
+            .then((resolved) => {
+            if (!isRendererTeardownResult(resolved)) {
+                if (renderedRoots.get(domNodeId) === entry) {
+                    renderedRoots.delete(domNodeId);
+                }
+                return;
+            }
+            // Only attach if this exact entry is still the active mount for this id.
+            if (renderedRoots.get(domNodeId) === entry) {
+                entry.teardown = resolved.teardown;
+            }
+            else {
+                // The mount was unmounted or its node replaced before this async teardown resolved, so the
+                // entry is no longer the active mount and the teardown can't be attached — it is dropped
+                // and that one mount may leak on cleanup. This is the expected, documented best-effort core
+                // limitation, but the consequence is still a leak, so log it as an error. Pro avoids this
+                // race entirely.
+                console.error(`[react-on-rails] Renderer teardown for dom node "${domNodeId}" resolved after the ` +
+                    'page or node was already cleaned up; the teardown was dropped and that mount may ' +
+                    'leak. Use react-on-rails-pro for reliable async-renderer teardown on fast navigations.');
+            }
+        })
+            .catch((error) => {
+            const isStillActive = renderedRoots.get(domNodeId) === entry;
+            if (!isStillActive) {
+                return;
+            }
+            renderedRoots.delete(domNodeId);
+            // The renderer's own promise rejected: the render failed, so the component never mounted and
+            // no teardown was captured. Log it (rather than letting it surface as an unhandled rejection)
+            // so the failure is diagnosable; any partial mount the renderer created may leak on cleanup.
+            // If this placeholder was already removed by page unload or node replacement, the page/node is
+            // already being cleaned up, so suppress a stale rejection log from the abandoned renderer.
+            console.error(`Renderer for dom node "${domNodeId}" rejected; the component did not mount and no ` +
+                'teardown was captured. Any mount it created may leak on cleanup:', error);
+        });
     }
-    return false;
 }
 /**
  * Used for client rendering by ReactOnRails. Either calls ReactDOM.hydrate, ReactDOM.render, or
@@ -66,28 +187,28 @@ function renderElement(el, railsContext) {
                     }
                     return;
                 }
-                // DOM node was replaced (e.g., via async HTML injection) - clean up the old root
+                // DOM node was replaced (e.g., via async HTML injection) - clean up the old root or run
+                // the old renderer's teardown.
                 try {
-                    if (supportsRootApi &&
-                        existing.root &&
-                        typeof existing.root === 'object' &&
-                        'unmount' in existing.root) {
-                        existing.root.unmount();
-                    }
-                    else {
-                        unmountComponentAtNode(existing.domNode);
-                    }
+                    teardownEntry(existing, domNodeId);
                 }
                 catch (unmountError) {
-                    // Ignore unmount errors for replaced nodes
-                    if (trace) {
-                        console.log(`Error unmounting replaced component: ${name}`, unmountError);
-                    }
+                    // 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);
                 }
                 renderedRoots.delete(domNodeId);
             }
             const componentObj = ComponentRegistry.get(name);
-            if (delegateToRenderer(componentObj, props, railsContext, domNodeId, trace)) {
+            const delegation = delegateToRenderer(componentObj, props, railsContext, domNodeId, trace);
+            if (delegation.delegated) {
+                // The renderer owns its own mount; record it (with any teardown wrapper it returned) so it
+                // gets cleaned up on page unload or same-id node replacement.
+                trackRendererMount(domNodeId, domNode, delegation.result);
                 return;
             }
             // Hydrate if the DOM node has content (server-rendered HTML)
@@ -110,7 +231,7 @@ You should return a React.Component always for the client side entry point.`);
             else {
                 const root = reactHydrateOrRender(domNode, reactElementOrRouterResult, shouldHydrate);
                 // Track the root for cleanup
-                renderedRoots.set(domNodeId, { root, domNode });
+                renderedRoots.set(domNodeId, { kind: 'react', root, domNode });
             }
         }
     }
@@ -165,23 +286,22 @@ export function reactOnRailsComponentLoaded(domId) {
     return Promise.resolve();
 }
 /**
- * Unmount all rendered React components and clear roots.
- * This should be called on page unload to prevent memory leaks.
+ * Unmount all rendered React components, run all renderer-function teardowns, and clear roots.
+ * Registered with `onPageUnloaded` to run on the page-unload lifecycle (Turbo/Turbolinks
+ * soft-navigation page swap, not a native browser unload) to prevent memory leaks.
  */
 function unmountAllComponents() {
-    renderedRoots.forEach(({ root, domNode }) => {
+    renderedRoots.forEach((entry, domNodeId) => {
         try {
-            if (supportsRootApi && root && typeof root === 'object' && 'unmount' in root) {
-                // React 18+ Root API
-                root.unmount();
-            }
-            else {
-                // React 16-17 legacy API
-                unmountComponentAtNode(domNode);
-            }
+            teardownEntry(entry, domNodeId);
         }
         catch (error) {
-            console.error('Error unmounting component:', 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);
         }
     });
     renderedRoots.clear();

package/lib/ComponentRegistry.d.ts

@@ -1,20 +1,21 @@
-import type { RegisteredComponent, ReactComponentOrRenderFunction } from './types/index.ts';
+import type { RegisteredComponent, RegisteredComponentValue } from './types/index.ts';
+type RegisteredComponentEntry = RegisteredComponent<RegisteredComponentValue>;
 declare const _default: {
     /**
      * @param components { component1: component1, component2: component2, etc. }
      */
-    register(components: Record<string, ReactComponentOrRenderFunction>): void;
+    register(components: Record<string, RegisteredComponentValue>): void;
     /**
      * @param name
      * @returns { name, component, renderFunction, isRenderer }
      */
-    get(name: string): RegisteredComponent;
+    get(name: string): RegisteredComponentEntry;
     /**
      * Get a Map containing all registered components. Useful for debugging.
      * @returns Map where key is the component name and values are the
      * { name, component, renderFunction, isRenderer}
      */
-    components(): Map<string, RegisteredComponent>;
+    components(): Map<string, RegisteredComponentEntry>;
     /**
      * Pro-only method that waits for component registration
      * @param _name Component name to wait for

package/lib/base/client.d.ts

@@ -2,12 +2,13 @@
  * @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';
+import type { RegisteredComponent, RegisteredComponentValue, Store, StoreGenerator, ReactOnRailsInternal } from '../types/index.ts';
+type RegisteredComponentEntry = RegisteredComponent<RegisteredComponentValue>;
 interface Registries {
     ComponentRegistry: {
-        register: (components: Record<string, ReactComponentOrRenderFunction>) => void;
-        get: (name: string) => RegisteredComponent;
-        components: () => Map<string, RegisteredComponent>;
+        register: (components: Record<string, RegisteredComponentValue>) => void;
+        get: (name: string) => RegisteredComponentEntry;
+        components: () => Map<string, RegisteredComponentEntry>;
     };
     StoreRegistry: {
         register: (storeGenerators: Record<string, StoreGenerator>) => void;

package/lib/base/client.js

@@ -6,6 +6,7 @@ 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";
 const DEFAULT_OPTIONS = {
     traceTurbolinks: false,
     turbo: false,
@@ -134,8 +135,8 @@ Fix: Use only react-on-rails OR react-on-rails-pro, not both.`);
                 if (this.options.debugMode) {
                     componentNames.forEach((name) => {
                         const component = components[name];
-                        const size = component.toString().length;
-                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${size} chars)`);
+                        const registrationMetric = componentRegistrationMetric(component);
+                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${registrationMetric.value} ${registrationMetric.label})`);
                     });
                 }
             }

package/lib/capabilities/core.d.ts

@@ -1,10 +1,11 @@
 import type { ReactElement } from 'react';
-import type { RegisteredComponent, RenderReturnType, ReactComponentOrRenderFunction, AuthenticityHeaders, Store, StoreGenerator, ReactOnRailsOptions } from '../types/index.ts';
+import type { RegisteredComponent, RenderReturnType, RegisteredComponentValue, AuthenticityHeaders, Store, StoreGenerator, ReactOnRailsOptions } from '../types/index.ts';
+type RegisteredComponentEntry = RegisteredComponent<RegisteredComponentValue>;
 export interface Registries {
     ComponentRegistry: {
-        register: (components: Record<string, ReactComponentOrRenderFunction>) => void;
-        get: (name: string) => RegisteredComponent;
-        components: () => Map<string, RegisteredComponent>;
+        register: (components: Record<string, RegisteredComponentValue>) => void;
+        get: (name: string) => RegisteredComponentEntry;
+        components: () => Map<string, RegisteredComponentEntry>;
     };
     StoreRegistry: {
         register: (storeGenerators: Record<string, StoreGenerator>) => void;
@@ -31,22 +32,22 @@ export declare function createCoreCapability(registries: Registries): {
     buildConsoleReplay(): string;
     getConsoleReplayScript(): string;
     resetOptions(): void;
-    register(components: Record<string, ReactComponentOrRenderFunction>): void;
+    register(components: Record<string, RegisteredComponentValue>): 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>;
+    getComponent(name: string): RegisteredComponentEntry;
+    registeredComponents(): Map<string, RegisteredComponentEntry>;
     storeGenerators(): Map<string, StoreGenerator>;
     stores(): Map<string, Store>;
-    render(name: string, props: Record<string, string>, domNodeId: string, hydrate: boolean): RenderReturnType;
+    render(name: string, props: Record<string, unknown>, domNodeId: string, hydrate: boolean): RenderReturnType;
     serverRenderReactComponent(...args: any[]): any;
     handleError(...args: any[]): any;
     prepareRenderResult(...args: any[]): any;
-    getOrWaitForComponent(): Promise<RegisteredComponent>;
+    getOrWaitForComponent(): Promise<RegisteredComponentEntry>;
     getOrWaitForStore(): Promise<Store>;
     getOrWaitForStoreGenerator(): Promise<StoreGenerator>;
     reactOnRailsStoreLoaded(): Promise<void>;
@@ -55,4 +56,5 @@ export declare function createCoreCapability(registries: Registries): {
     addAsyncPropsCapabilityToComponentProps(...args: any[]): any;
     getOrCreateAsyncPropsManager(...args: any[]): any;
 };
+export {};
 //# sourceMappingURL=core.d.ts.map

package/lib/capabilities/core.js

@@ -2,6 +2,7 @@ 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";
 const DEFAULT_OPTIONS = {
     traceTurbolinks: false,
     turbo: false,
@@ -82,8 +83,8 @@ export function createCoreCapability(registries) {
                 if (this.options.debugMode) {
                     componentNames.forEach((name) => {
                         const component = components[name];
-                        const size = component.toString().length;
-                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${size} chars)`);
+                        const registrationMetric = componentRegistrationMetric(component);
+                        console.log(`[ReactOnRails] ✅ Registered: ${name} (${registrationMetric.value} ${registrationMetric.label})`);
                     });
                 }
             }

package/lib/componentRegistrationMetric.d.ts

@@ -0,0 +1,8 @@
+import type { RegisteredComponentValue } from './types/index.ts';
+type RegistrationMetric = {
+    label: string;
+    value: number;
+};
+export default function componentRegistrationMetric(component: RegisteredComponentValue): RegistrationMetric;
+export {};
+//# sourceMappingURL=componentRegistrationMetric.d.ts.map

package/lib/componentRegistrationMetric.js

@@ -0,0 +1,7 @@
+export default function componentRegistrationMetric(component) {
+    if (typeof component === 'function') {
+        return { label: 'source chars', value: component.toString().length };
+    }
+    return { label: 'export keys', value: Object.keys(component).length };
+}
+//# sourceMappingURL=componentRegistrationMetric.js.map

package/lib/createReactOutput.js

@@ -1,5 +1,20 @@
 import { createElement, isValidElement } from 'react';
 import { isServerRenderHash, isPromise } from "./isServerRenderResult.js";
+import { isRendererTeardownResult } from "./rendererTeardown.js";
+const unsupportedManualRendererMessage = (name) => `ReactOnRails.render() does not support renderer functions ("${name}"). ` +
+    'Use normal React on Rails component rendering so renderer teardowns are captured on navigation.';
+function isReactObjectComponentType(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    // React.memo, React.forwardRef, React.lazy, and related component types are non-callable
+    // objects tagged with React's element-type marker.
+    const typeMarker = value.$$typeof;
+    return typeof typeMarker === 'symbol' || typeof typeMarker === 'number';
+}
+function isReactComponentType(value) {
+    return typeof value === 'function' || typeof value === 'string' || isReactObjectComponentType(value);
+}
 function createReactElementFromRenderFunctionResult(renderFunctionResult, name, props) {
     if (isValidElement(renderFunctionResult)) {
         // If already a ReactElement, then just return it.
@@ -24,7 +39,7 @@ work if you return JSX. Update by wrapping the result JSX of ${name} in a fat ar
  * @returns {ReactElement}
  */
 export default function createReactOutput({ componentObj, props, railsContext, domNodeId, trace, shouldHydrate, }) {
-    const { name, component, renderFunction } = componentObj;
+    const { name, component, renderFunction, isRenderer } = componentObj;
     if (trace) {
         if (railsContext && railsContext.serverSide) {
             console.log(`RENDERED ${name} to dom node with id: ${domNodeId}`);
@@ -41,7 +56,26 @@ export default function createReactOutput({ componentObj, props, railsContext, d
         if (trace) {
             console.log(`${name} is a renderFunction`);
         }
+        // createReactOutput only handles render-functions that return a component or server-render hash.
+        // The 3-argument renderer form (which owns its own mount and may return a RendererTeardownResult)
+        // never reaches here on the supported paths: the client renderers delegate it earlier
+        // (`delegateToRenderer`) and return before this call, and server rendering rejects it upstream in
+        // validateComponent ("Detected a renderer while server rendering"). The only path that reaches
+        // here with a renderer is the manual public `ReactOnRails.render()` API, where renderers are
+        // unsupported because their teardown can't be tracked for cleanup. Reject it loudly and *before*
+        // invoking, rather than calling it with no domNodeId and rendering a half-wired, leak-prone result.
+        if (isRenderer) {
+            throw new Error(unsupportedManualRendererMessage(name));
+        }
+        if (typeof component !== 'function') {
+            throw new Error(`Registered render function "${name}" must be a function.`);
+        }
         const renderFunctionResult = component(props, railsContext);
+        // Defense-in-depth: a 2-argument render function isn't expected to return a teardown wrapper, but
+        // the public RenderFunction return type can't structurally exclude it, so reject that at runtime too.
+        if (isRendererTeardownResult(renderFunctionResult)) {
+            throw new Error(unsupportedManualRendererMessage(name));
+        }
         if (isServerRenderHash(renderFunctionResult)) {
             // We just return at this point, because calling function knows how to handle this case and
             // we can't call React.createElement with this type of Object.
@@ -51,6 +85,9 @@ export default function createReactOutput({ componentObj, props, railsContext, d
             // We just return at this point, because calling function knows how to handle this case and
             // we can't call React.createElement with this type of Object.
             return renderFunctionResult.then((result) => {
+                if (isRendererTeardownResult(result)) {
+                    throw new Error(unsupportedManualRendererMessage(name));
+                }
                 // If the result is a function, then it returned a React Component (even class components are functions).
                 if (typeof result === 'function') {
                     return createReactElementFromRenderFunctionResult(result, name, props);
@@ -60,7 +97,9 @@ export default function createReactOutput({ componentObj, props, railsContext, d
         }
         return createReactElementFromRenderFunctionResult(renderFunctionResult, name, props);
     }
-    // else
+    if (!isReactComponentType(component)) {
+        throw new Error(`Registered component "${name}" must be a function, string, or React object component type.`);
+    }
     return createElement(component, props);
 }
 //# sourceMappingURL=createReactOutput.js.map

package/lib/isRenderFunction.d.ts

@@ -1,9 +1,11 @@
-import { ReactComponentOrRenderFunction, RenderFunction } from './types/index.ts';
+import type { RegisteredComponentValue, RenderFunction, RendererFunction } from './types/index.ts';
+type AnyRenderFunction = RenderFunction | RendererFunction;
 /**
- * Used to determine we'll call be calling React.createElement on the component of if this is a
- * Render-Function used return a function that takes props to return a React element
+ * Used to determine whether we'll call React.createElement on the component or if this is a
+ * Render-Function used to return a function that takes props to return a React element
  * @param component
  * @returns {boolean}
  */
-export default function isRenderFunction(component: ReactComponentOrRenderFunction): component is RenderFunction;
+export default function isRenderFunction(component: RegisteredComponentValue): component is AnyRenderFunction;
+export {};
 //# sourceMappingURL=isRenderFunction.d.ts.map

package/lib/isRenderFunction.js

@@ -1,21 +1,25 @@
 /**
- * Used to determine we'll call be calling React.createElement on the component of if this is a
- * Render-Function used return a function that takes props to return a React element
+ * Used to determine whether we'll call React.createElement on the component or if this is a
+ * Render-Function used to return a function that takes props to return a React element
  * @param component
  * @returns {boolean}
  */
 export default function isRenderFunction(component) {
+    if (typeof component !== 'function') {
+        return false;
+    }
+    const callableComponent = component;
     // No for es5 or es6 React Component
     // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    if (component.prototype?.isReactComponent) {
+    if (callableComponent.prototype?.isReactComponent) {
         return false;
     }
-    if (component.renderFunction) {
+    if (callableComponent.renderFunction) {
         return true;
     }
     // If zero or one args, then we know that this is a regular function that will
     // return a React component
-    if (component.length >= 2) {
+    if (callableComponent.length >= 2) {
         return true;
     }
     return false;

package/lib/rendererTeardown.d.ts

@@ -0,0 +1,3 @@
+import type { RendererTeardownResult } from './types/index.ts';
+export declare function isRendererTeardownResult(value: unknown): value is RendererTeardownResult;
+//# sourceMappingURL=rendererTeardown.d.ts.map

package/lib/rendererTeardown.js

@@ -0,0 +1,9 @@
+// Shared type guard for RendererTeardownResult, extracted so OSS and Pro can import it without
+// duplicating the predicate or coupling Pro to ClientRenderer internals.
+// eslint-disable-next-line import/prefer-default-export -- single-export module; named export keeps the type guard's API tied to its predicate name.
+export function isRendererTeardownResult(value) {
+    return (value != null &&
+        typeof value === 'object' &&
+        typeof value.teardown === 'function');
+}
+//# sourceMappingURL=rendererTeardown.js.map

package/lib/serverRenderUtils.d.ts

@@ -1,4 +1,4 @@
-import type { RegisteredComponent, RenderingError, FinalHtmlResult } from './types/index.ts';
+import type { RegisteredComponent, RegisteredComponentValue, 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.
@@ -20,6 +20,6 @@ export declare function buildRenderMetadata(consoleReplayScript: string, renderS
  */
 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 declare function validateComponent(componentObj: RegisteredComponent<RegisteredComponentValue>, componentName: string): void;
 export {};
 //# sourceMappingURL=serverRenderUtils.d.ts.map

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement, ReactNode, Component, ComponentType } from 'react';
+import type { ReactElement, ReactNode, Component, ComponentType, ExoticComponent } from 'react';
 import type { PipeableStream } from 'react-dom/server';
 import type { Readable } from 'stream';
 /**
@@ -10,7 +10,7 @@ import type { Readable } from 'stream';
 type Store = {
     getState(): unknown;
 };
-type ReactComponent = ComponentType<any> | string;
+type ReactComponent = ComponentType<any> | ExoticComponent<any> | string;
 export type RailsContext = {
     componentRegistryTimeout: number;
     railsEnv: string;
@@ -76,6 +76,68 @@ type CreateReactOutputResult = CreateReactOutputSyncResult | CreateReactOutputAs
 type RenderFunctionSyncResult = ReactComponent | ServerRenderResult;
 type RenderFunctionAsyncResult = Promise<string | ServerRenderHashRenderedHtml | ReactComponent | ServerRenderResult>;
 type RenderFunctionResult = RenderFunctionSyncResult | RenderFunctionAsyncResult;
+type ReactComponentRenderFunctionResult = ReactComponent | Promise<ReactComponent>;
+/**
+ * Optional cleanup callback that a renderer function (the 3-argument form
+ * `(props, railsContext, domNodeId) => …`) may return inside a {@link RendererTeardownResult}.
+ * React on Rails invokes it when the mount is torn down — on Turbo/Turbolinks navigation (the
+ * framework's soft-navigation page swap, not a native browser unload) and when the same `domNodeId`
+ * node is replaced — so renderer-managed React roots, event listeners, and subscriptions are released
+ * instead of leaked. May be synchronous or asynchronous.
+ *
+ * @see RenderFunction
+ */
+type RendererTeardownReturn = void | Promise<void>;
+type RendererTeardown = () => RendererTeardownReturn;
+/**
+ * Object wrapper returned by a 3-argument renderer to opt into cleanup. The wrapper keeps teardown
+ * detection unambiguous: legacy renderers may have returned function components before this contract
+ * existed, so a bare function return is treated as no teardown.
+ */
+type RendererTeardownResult = {
+    teardown: RendererTeardown;
+};
+/**
+ * What the 3-argument renderer form may return for cleanup: nothing, or a
+ * {@link RendererTeardownResult}. Runtime cleanup only recognizes this explicit wrapper; legacy
+ * component/server-result returns from 3-argument renderers are ignored.
+ *
+ * Consumers discriminate this union at runtime by an object with a `teardown` function vs. a thenable
+ * (an async renderer, awaited/adopted before re-checking) vs. anything else (no teardown). The
+ * `void` arm is therefore treated as "no teardown," same as `undefined`.
+ */
+type RendererResult = void | RendererTeardownResult | Promise<void | RendererTeardownResult>;
+type RendererFunctionResult = RendererResult | RenderFunctionResult;
+interface RenderFunctionMarker {
+    renderFunction?: true;
+}
+/**
+ * The precise call signature of the 3-argument "renderer" form `(props, railsContext, domNodeId) =>
+ * …`. A renderer owns its own mount and may return nothing or a {@link RendererTeardownResult}
+ * (possibly async) to opt into cleanup. It also accepts the legacy {@link RenderFunctionResult}
+ * return shapes because older 3-argument renderers sometimes returned a component only to satisfy
+ * the old `RenderFunction` type; those non-teardown values are ignored at runtime. Shared by the
+ * core and Pro client renderers so the two cannot drift.
+ *
+ * @returns New renderer code should return `void` or `{ teardown }`. The broader legacy return
+ * shapes stay accepted only so existing 3-argument renderers remain type-compatible.
+ */
+interface RendererFunction extends RenderFunctionMarker {
+    (props?: Record<string, unknown>, railsContext?: RailsContext, domNodeId?: string): RendererFunctionResult;
+}
+/**
+ * A render function variant for APIs that require a React component result, such as
+ * Pro server-component wrappers. Unlike {@link RenderFunction}, this does not allow
+ * server-render hashes/HTML, and unlike {@link RendererFunction}, this does not allow
+ * renderer teardown results.
+ *
+ * Runtime render-function detection still follows the regular React on Rails
+ * convention: declare at least two parameters, or set `renderFunction = true`
+ * on one-argument functions.
+ */
+interface ReactComponentRenderFunction<Props = any> extends RenderFunctionMarker {
+    (props?: Props, railsContext?: RailsContext, domNodeId?: string): ReactComponentRenderFunctionResult;
+}
 type StreamableComponentResult = ReactElement | Promise<ReactElement | string>;
 type AsyncPropsManager = {
     getProp: (propName: string) => Promise<unknown>;
@@ -105,17 +167,34 @@ type AsyncPropsManager = {
  * // Option 2: Using renderFunction property
  * const anotherRenderFunction = (props) => { ... };
  * anotherRenderFunction.renderFunction = true;
+ *
+ * @remarks
+ * The 3-argument "renderer" form `(props, railsContext, domNodeId)` owns its own DOM
+ * rendering/hydration. Use {@link RendererFunction} for renderers that return nothing or an optional
+ * `{ teardown }` wrapper for cleanup. `RenderFunction` still accepts legacy 3-argument renderers
+ * that returned a component/server result only to satisfy the old type; React on Rails ignores those
+ * return values on the client renderer path.
  */
-interface RenderFunction {
+interface ServerRenderFunction extends RenderFunctionMarker {
+    (props?: any, railsContext?: RailsContext): RenderFunctionResult;
+}
+interface LegacyRendererRenderFunction extends RenderFunctionMarker {
     (props?: any, railsContext?: RailsContext, domNodeId?: string): RenderFunctionResult;
-    renderFunction?: true;
 }
-type ReactComponentOrRenderFunction = ReactComponent | RenderFunction;
+type RenderFunction = ServerRenderFunction | LegacyRendererRenderFunction;
+type ReactComponentOrRenderFunction = ReactComponent | RenderFunction | RendererFunction;
+type RegisteredComponentValue = ReactComponentOrRenderFunction | Record<string, unknown>;
 type PipeableOrReadableStream = PipeableStream | NodeJS.ReadableStream;
-export type { ReactComponentOrRenderFunction, ReactComponent, AuthenticityHeaders, RenderFunction, RenderFunctionResult, Store, StoreGenerator, CreateReactOutputResult, ServerRenderResult, ServerRenderHashRenderedHtml, CreateReactOutputSyncResult, CreateReactOutputAsyncResult, RenderFunctionSyncResult, RenderFunctionAsyncResult, StreamableComponentResult, PipeableOrReadableStream, };
-export interface RegisteredComponent {
+export type { ReactComponentOrRenderFunction, RegisteredComponentValue, ReactComponent, ReactComponentRenderFunction, AuthenticityHeaders, RenderFunction, RendererTeardown, RendererTeardownResult, RendererFunction, RenderFunctionResult, Store, StoreGenerator, CreateReactOutputResult, ServerRenderResult, ServerRenderHashRenderedHtml, CreateReactOutputSyncResult, CreateReactOutputAsyncResult, RenderFunctionSyncResult, RenderFunctionAsyncResult, ReactComponentRenderFunctionResult, StreamableComponentResult, PipeableOrReadableStream, };
+/**
+ * The generic defaults to the pre-object-registration component type so existing consumers that
+ * read `registeredComponent.component` stay source-compatible. Use
+ * `RegisteredComponent<RegisteredComponentValue>` when handling plain-object server_render_js
+ * registrations.
+ */
+export interface RegisteredComponent<ComponentValue extends RegisteredComponentValue = ReactComponentOrRenderFunction> {
     name: string;
-    component: ReactComponentOrRenderFunction;
+    component: ComponentValue;
     /**
      * Indicates if the registered component is a RenderFunction
      * @see RenderFunction for more details on its behavior and usage.
@@ -141,7 +220,7 @@ export interface RSCRenderParams extends Omit<RenderParams, 'railsContext'> {
     railsContext: RailsContextWithServerStreamingCapabilities;
 }
 export interface CreateParams extends Params {
-    componentObj: RegisteredComponent;
+    componentObj: RegisteredComponent<RegisteredComponentValue>;
     shouldHydrate?: boolean;
 }
 export interface ErrorOptions {
@@ -187,7 +266,7 @@ export interface ReactOnRails {
      * find you components for rendering.
      * @param components keys are component names, values are components
      */
-    register(components: Record<string, ReactComponentOrRenderFunction>): void;
+    register(components: Record<string, RegisteredComponentValue>): void;
     /** @deprecated Use registerStoreGenerators instead */
     registerStore(stores: Record<string, StoreGenerator>): void;
     /**
@@ -300,6 +379,17 @@ export interface ReactOnRailsInternal extends ReactOnRails {
      * ```
      * under React 18+.
      *
+     * @remarks
+     * **Cleanup is the caller's responsibility.** Unlike the components React on Rails mounts itself
+     * (which are unmounted automatically on Turbo/Turbolinks navigation and same-id node replacement),
+     * a root created by this imperative API is **not** tracked internally. The returned root is handed
+     * back to you, and you must call `unmount()` on it yourself — e.g. on a Turbo `turbo:before-render`
+     * / Turbolinks `turbolinks:before-render` event, or in your framework's teardown hook — to avoid
+     * leaking the root (and any subscriptions or timers it holds) across navigations. If you want
+     * automatic cleanup instead, register a renderer function (the 3-argument render-function form) and
+     * return a {@link RendererTeardownResult}; React on Rails tracks those mounts and runs the teardown for
+     * you.
+     *
      * @param name Name of your registered component
      * @param props Props to pass to your component
      * @param domNodeId HTML ID of the node the component will be rendered at
@@ -308,17 +398,17 @@ export interface ReactOnRailsInternal extends ReactOnRails {
      *   (see "What is a root?" in https://github.com/reactwg/react-18/discussions/5).
      *   Under React 16/17: Reference to your component's backing instance or `null` for stateless components.
      */
-    render(name: string, props: Record<string, string>, domNodeId: string, hydrate?: boolean): RenderReturnType;
+    render(name: string, props: Record<string, unknown>, domNodeId: string, hydrate?: boolean): RenderReturnType;
     /**
      * Get the component that you registered
      * @returns {name, component, renderFunction, isRenderer}
      */
-    getComponent(name: string): RegisteredComponent;
+    getComponent(name: string): RegisteredComponent<RegisteredComponentValue>;
     /**
      * Get the component that you registered, or wait for it to be registered
      * @returns {name, component, renderFunction, isRenderer}
      */
-    getOrWaitForComponent(name: string): Promise<RegisteredComponent>;
+    getOrWaitForComponent(name: string): Promise<RegisteredComponent<RegisteredComponentValue>>;
     /**
      * Used by server rendering by Rails
      */
@@ -353,7 +443,7 @@ export interface ReactOnRailsInternal extends ReactOnRails {
     /**
      * Get a Map containing all registered components. Useful for debugging.
      */
-    registeredComponents(): Map<string, RegisteredComponent>;
+    registeredComponents(): Map<string, RegisteredComponent<RegisteredComponentValue>>;
     /**
      * Get a Map containing all registered store generators. Useful for debugging.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-on-rails",
-  "version": "17.0.0-rc.1",
+  "version": "17.0.0-rc.2",
   "description": "react-on-rails JavaScript for react_on_rails Ruby gem",
   "main": "lib/ReactOnRails.full.js",
   "type": "module",
@@ -43,6 +43,7 @@
     "./ReactDOMServer": "./lib/ReactDOMServer.cjs",
     "./serverRenderReactComponent": "./lib/serverRenderReactComponent.js",
     "./@internal/sanitizeNonce": "./lib/sanitizeNonce.js",
+    "./@internal/rendererTeardown": "./lib/rendererTeardown.js",
     "./@internal/base/client": "./lib/base/client.js",
     "./@internal/base/full": {
       "react-server": "./lib/base/full.rsc.js",