Adopt renderer-function teardown in dummy apps + docs (#3578) (#3585)

## Summary

Follow-up to #3209, after **PR #3576** (the renderer-function teardown
contract) merged into `main` as
`55fcdcf4af0629f32969dfa55f6fd71794ce200f`. This adopts the explicit `{
teardown }` wrapper contract across the in-tree dummy renderer functions
and documents the optional teardown wrapper return value. **None of
these change the public runtime contract** — they adopt it in-tree and
document it, exactly the checklist deferred in #3578.

> ✅ **Retargeted to main.** #3576 has landed, so #3585 is now based on
`main` and the head branch has been rebased onto `origin/main`.

Closes #3578.

## 1. In-tree dummy renderers → return `{ teardown }`

Each renderer function (3-arg `(props, railsContext, domNodeId)` form)
now captures its React root and returns `{ teardown: () => ... }` so
React on Rails unmounts it on Turbo/Turbolinks navigation (page unload)
or same-id node replacement instead of leaking it.

**Decision:** use the explicit `{ teardown }` wrapper, not a bare
callback. #3576 made the runtime/type contract explicit so legacy
3-argument render functions that happened to return a function are not
misclassified as cleanup callbacks.

**OSS modern** (`react_on_rails/spec/dummy/client/app/startup/`):

- `ManualRenderApp.jsx`
- `ReduxApp.client.jsx` — `module.hot` path now reuses the existing root
instead of creating a second root
- `ReduxSharedStoreApp.client.jsx` — `module.hot` path now reuses the
existing root instead of creating a second root

**OSS legacy React 16**
(`react_on_rails/spec/dummy/client/app-react16/startup/`):

- `ManualRenderApp.jsx`, `ReduxApp.client.jsx`,
`ReduxSharedStoreApp.client.jsx` — teardown unmounts via
`ReactDOM.unmountComponentAtNode(domNode)` (no root handle in the React
16/17 API)

**Pro auto-load**
(`react_on_rails_pro/spec/dummy/client/app/ror-auto-load-components/`):

- `ManualRenderApp.jsx`, `ReduxApp.client.jsx`,
`ReduxSharedStoreApp.client.jsx`, `ApolloGraphQLApp.client.jsx`,
`LazyApolloGraphQLApp.client.tsx`

**Pro loadable:**

- `loadable/loadable-client.imports-loadable.jsx` — returns a **promise
resolving to** `{ teardown }`, since the root is created inside
`loadableReady()`
- `@loadable/component` version confirmation: the Pro dummy app declares
`^5.16.3` and the lockfile resolves `5.16.7`, above the Promise API
floor (`5.12.0`).

### A note on the `module.hot` paths

The React 18 `createRoot` renderers (OSS modern Redux apps) now
re-render on the same root during hot reload, so HMR no longer leaks a
root or calls `createRoot` twice on the same node. The React 16/17
renderers re-render into the same container idempotently
(`ReactDOM.render`/`hydrate`), so there is no separate root to unmount
first — their HMR path is unchanged, and the teardown handles
unload/replacement cleanup.

## 2. Docs

- `docs/oss/core-concepts/render-functions.md` — the `LazyHydrate`
example captures the root and resolves to `{ teardown }`.
- `docs/oss/api-reference/view-helpers-api.md` — new **"Cleaning up on
Turbo/Turbolinks navigation"** subsection with a Turbo-navigation
example (React 18 + legacy) and the async best-effort caveat.
- `docs/oss/api-reference/javascript-api.md` — short reference note on
the `{ teardown }` return value.

## 3. Imperative `ReactOnRails.render(...)` — decision recorded

Flagged as out of scope in #3209 ("same family of problem; different
surface; deferred").

**Decision: document the caller's responsibility; do not auto-track.** I
added a `@remarks` block to the `render()` JSDoc in
`packages/react-on-rails/src/types/index.ts` stating that a root created
by this imperative API is **not** tracked internally and the caller must
`unmount()` it themselves (e.g. on `turbo:before-render`), or use a
renderer function for automatic cleanup.

Rationale: auto-tracking these roots in `renderedRoots` would be a
behavior change that risks **double-unmount** for callers that already
manage `unmount()` themselves, and #3209 explicitly deferred this
surface. Documentation-only, no behavior change. If we later want
tracked imperative renders, that can be a separate, opt-in API.

## Retarget/rebase status

- #3576 merged into `main` as `55fcdcf4af0629f32969dfa55f6fd71794ce200f`
on 2026-06-05.
- #3585 auto-closed when the old stacked base branch was deleted, then
was reopened and retargeted to `main`.
- The #3585 head branch was rebased onto latest `origin/main` and
force-pushed with lease; current rebased top commit is `667d1954`.

## Follow-up

Non-blocking review nits from the final green #3585 pass are tracked in
#3689 instead of delaying this PR. The `@loadable/component` Promise API
floor is recorded above, and the legacy React 16 dummy `props` mutation
cleanup is intentionally deferred because #3585 preserves existing
fixture behavior while adding teardown.

The intentionally deferred surface remains the imperative
`ReactOnRails.render(...)` API documented below; if tracked imperative
roots are desired later, that should be a separate opt-in API issue/PR.

## Acceptance criteria

- [x] All in-tree dummy renderer functions return `{ teardown }` that
unmounts their root (and the `module.hot` createRoot path reuses the
previous root instead of creating a new one).
- [x] Renderer-function docs show the optional `{ teardown }` return
value with a Turbo-navigation example.
- [x] A decision (documentation) is recorded for the imperative
`ReactOnRails.render(...)` path.

## Verification

- Rebased #3585 branch onto latest `origin/main` after #3576 merged; no
conflicts.
- `pnpm exec prettier --check ...changed files...` — clean
- `pnpm exec eslint --report-unused-disable-directives ...changed JS/TS
files...` — clean
- `pnpm --filter react-on-rails run type-check` — clean
- `pnpm --filter react-on-rails-pro run type-check` — clean
- `pnpm --dir react_on_rails_pro/spec/dummy exec tsc -p tsconfig.json
--noEmit --pretty false` — no new errors; still reports the 4
pre-existing `tests/strict-mode-support.test.tsx` unknown-prop errors
documented before
- `git diff --check origin/main...HEAD` — clean
- `pnpm run lint` — currently blocked by unrelated
`test/shakaperf/rsc-fouc` artifact lint errors on main; those files are
not touched by this PR.

No CHANGELOG entry: per the project changelog guidelines these are test
fixtures + docs + a JSDoc comment (not user-visible behavior), and #3576
already documents the user-facing contract.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Changes are limited to test fixtures, documentation, and JSDoc; public
teardown behavior was already introduced in the prior contract PR.
> 
> **Overview**
> Adopts the **optional `{ teardown }` wrapper** from the merged
renderer teardown contract across in-tree dummy **3-argument renderer
functions**, plus documentation and a JSDoc note—**no new runtime
behavior** in this PR.
> 
> **Dummy apps:** OSS React 16 and Pro auto-load/loadable client
startups now resolve the mount DOM node up front (throw if missing),
capture the React root (or legacy container), and **return `{ teardown:
() => root.unmount() }`** (or a **promise** that resolves to it for
`loadableReady`). That lets React on Rails unmount renderer-owned trees
on Turbo/Turbolinks navigation and same-id node replacement instead of
leaking roots.
> 
> **Docs:** `render-functions.md` and `view-helpers-api.md` document
optional teardown (React 18 + legacy examples, hydrate-vs-render notes,
async teardown best-effort in OSS). `javascript-api.md` briefly mentions
the return shape on 3-param renderers.
> 
> **Types:** `ReactOnRails.render()` JSDoc now states that **imperative
mounts are not auto-tracked**—callers must `unmount()` themselves or use
a renderer function with `{ teardown }` for automatic cleanup.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
200865b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Renderer functions and client entrypoints may return optional teardown
handlers so mounted React roots are unmounted cleanly during
Turbo/Turbolinks navigation or same-id node replacement.
  * Client startups now validate target DOM nodes before hydrating.

* **Documentation**
* Expanded API and core-concepts docs with examples for teardown return
values, hydration patterns, and sync/async teardown behavior.

* **Bug Fixes**
* Prevents leaked mounted React roots across navigations and
hot-reloads.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: justin808

docs/oss/api-reference/javascript-api.md

@@ -30,7 +30,10 @@ The best source of docs is the `interface ReactOnRails` in [types/index.ts](http
  * - 2 params, or any function with `.renderFunction = true`: Render-Function — called with (props, railsContext),
  *   returns a React component, `{ renderedHtml }` object, or Promise (Pro Node renderer only)
  * - 3 params: Renderer function — called with (props, railsContext, domNodeId),
- *   responsible for calling ReactDOM.render/hydrate directly (client-only)
+ *   responsible for calling ReactDOM.render/hydrate directly (client-only).
+ *   May optionally return a `{ teardown }` wrapper (or a promise resolving to one); React on Rails
+ *   runs it on Turbo/Turbolinks navigation or same-id node replacement to unmount the renderer's root
+ *   instead of leaking it. See the view-helpers renderer-function docs.
  *
  * Render-Functions can return:
  * - A React component (function or class) — used with `react_component`

docs/oss/api-reference/view-helpers-api.md

@@ -106,6 +106,59 @@ Why would you want to take over mounting yourself? One use case is code splittin
 > [!IMPORTANT]
 > **Renderer functions are strictly client-only.** There is no DOM on the server, so a renderer function cannot produce SSR output. React on Rails detects renderer functions at registration time and will throw a descriptive error like `Detected a renderer while server rendering component 'X'. See https://reactonrails.com/docs/core-concepts/render-functions for more information.` if you attempt to use one with `react_component(... prerender: true)`, `react_component_hash` (which forces prerendering), or `stream_react_component` (which is server-streaming only). For rendering that needs to run on the server, use a regular render function instead.
 
+#### Cleaning up on Turbo/Turbolinks navigation (optional teardown)
+
+Because a renderer function owns the React root it creates, React on Rails cannot unmount that root for you the way it does for the components it mounts itself. With [Turbo](https://turbo.hotwired.dev/) or Turbolinks, the page swaps without a full reload, so a renderer that never unmounts leaks its root (and any subscriptions or timers it holds) on every navigation.
+
+To opt in to cleanup, **return a teardown wrapper** — `{ teardown: () => void | Promise<void> }`, or a promise resolving to one — from the renderer. React on Rails stores it and runs it when the mount is torn down: on Turbo/Turbolinks navigation (when the framework swaps in the next page) or when the same `domNodeId` node is replaced. Returning nothing keeps the previous (leaky) behavior, so existing renderers are unaffected.
+
+```jsx
+import ReactDOMClient from 'react-dom/client';
+
+// Renderer function: 3 params, mounts itself, returns a teardown wrapper.
+const MyRenderer = (props, _railsContext, domNodeId) => {
+  const domNode = document.getElementById(domNodeId);
+  if (!domNode) {
+    throw new Error(`Missing DOM element with id: ${domNodeId}`);
+  }
+
+  // This example always creates a fresh root. See the hydration note below if your renderer
+  // needs to hydrate server-rendered markup.
+  const root = ReactDOMClient.createRoot(domNode);
+  root.render(<MyComponent {...props} />);
+
+  // Unmounted automatically on the next Turbo navigation (or same-id node replacement).
+  return { teardown: () => root.unmount() };
+};
+```
+
+> [!NOTE]
+> **Hydrating server-rendered markup?** `prerender` is not a prop React on Rails injects — the top-level `prerender:` render option only controls server rendering and is rejected for renderer functions (see the note above). If your client renderer also serves components that were rendered on the server through a separate server bundle (a server/client split), pass an application-level signal in the component's `props`, such as `serverRendered`, and branch on it. The in-repo dummy apps use their own fixture props for this decision; the custom flag here is just an example for renderers that need an explicit hydrate-vs-render signal. Remove that renderer-only flag before spreading props into your component: `const { serverRendered, ...componentProps } = props;`, then call `ReactDOMClient.hydrateRoot(domNode, <MyComponent {...componentProps} />)` when `serverRendered` is true.
+
+Under the React 16/17 legacy API there is no root handle, so unmount by container node instead:
+
+```jsx
+import ReactDOM from 'react-dom';
+
+const MyLegacyRenderer = (props, _railsContext, domNodeId) => {
+  const { serverRendered, ...componentProps } = props;
+  const domNode = document.getElementById(domNodeId);
+  if (!domNode) {
+    throw new Error(`Missing DOM element with id: ${domNodeId}`);
+  }
+
+  if (serverRendered) {
+    ReactDOM.hydrate(<MyComponent {...componentProps} />, domNode);
+  } else {
+    ReactDOM.render(<MyComponent {...componentProps} />, domNode);
+  }
+  return { teardown: () => ReactDOM.unmountComponentAtNode(domNode) };
+};
+```
+
+> [!NOTE]
+> Synchronous teardowns are always honored. An **async** teardown is best-effort in the open-source package: if a navigation or node replacement happens before the renderer resolves its teardown, that still-pending teardown may be dropped. React on Rails logs a `console.error` when this happens — search for `resolved after its mount was removed` (the teardown was dropped) or `Error resolving renderer teardown` (the render promise rejected) — so the dropped teardown is diagnosable rather than silent. React on Rails Pro's client renderer awaits the renderer and handles this race reliably.
+
 ---
 
 ### React Router

docs/oss/core-concepts/render-functions.md

@@ -6,20 +6,22 @@ This guide explains how render-functions work in React on Rails and how to use t
 
 Before diving into render-functions, it helps to know the three kinds of values you can register with `ReactOnRails.register`. React on Rails classifies each registered entry based on its shape, and the classification determines where it can run (server, client, or both) and which Ruby helpers can invoke it.
 
-| Type                  | Signature                                  | Server (SSR)    | Client | Detection rule                                                          |
-| --------------------- | ------------------------------------------ | --------------- | ------ | ----------------------------------------------------------------------- |
-| **React Component**   | `(props) => JSX` or class component        | Yes             | Yes    | `Function.length <= 1` and no `renderFunction` flag                     |
-| **Render Function**   | `(props, railsContext) => ...`             | Yes             | Yes    | `Function.length >= 2` **or** `fn.renderFunction === true`              |
-| **Renderer Function** | `(props, railsContext, domNodeId) => void` | **No — throws** | Yes    | A render function (detected first) with exactly `Function.length === 3` |
+| Type                  | Signature                                                  | Server (SSR)    | Client | Detection rule                                                          |
+| --------------------- | ---------------------------------------------------------- | --------------- | ------ | ----------------------------------------------------------------------- |
+| **React Component**   | `(props) => JSX` or class component                        | Yes             | Yes    | `Function.length <= 1` and no `renderFunction` flag                     |
+| **Render Function**   | `(props, railsContext) => ...`                             | Yes             | Yes    | `Function.length >= 2` **or** `fn.renderFunction === true`              |
+| **Renderer Function** | `(props, railsContext, domNodeId) => void \| { teardown }` | **No — throws** | Yes    | A render function (detected first) with exactly `Function.length === 3` |
 
 A few important points about the detection:
 
 - **The detection is based on `Function.length`** (the number of declared parameters). Destructured parameters count as 1 — `({ name }) => ...` has length 1.
 - **Render functions return** a React component, a React element, a server-render hash object, or a promise that resolves to one of those. See [Types of Render-Functions and Their Return Values](#types-of-render-functions-and-their-return-values) below.
-- **Renderer functions do not return anything meaningful.** They take control of mounting/hydration themselves by calling `ReactDOM.hydrateRoot` / `createRoot` against `domNodeId`. Because there is no DOM on the server, **registering a renderer function and then server-rendering it throws a descriptive error**. Renderer functions are strictly client-side.
+- **Renderer functions may optionally return a teardown wrapper** — `{ teardown: () => void | Promise<void> }`, or a promise resolving to one. They take control of mounting/hydration themselves by calling `ReactDOM.hydrateRoot` / `createRoot` against `domNodeId`. Because there is no DOM on the server, **registering a renderer function and then server-rendering it throws a descriptive error**. Renderer functions are strictly client-side.
 - **`fn.renderFunction = true` is an escape hatch** for render functions that don't need `railsContext` but still want to be treated as render functions (e.g., so they can return a hash). Without the flag, a one-parameter function is classified as a regular React component.
 
 ```jsx
+import ReactDOMClient from 'react-dom/client';
+
 // Regular React Component — 0 or 1 params, renders normally
 const HelloMessage = (props) => <div>Hello {props.name}</div>;
 
@@ -38,18 +40,24 @@ const HelloHash = (props) => {
 };
 HelloHash.renderFunction = true;
 
-// Renderer Function — 3 params, handles hydration itself, CLIENT ONLY
-const LazyHydrate = (props, railsContext, domNodeId) => {
-  // whenVisible is a hypothetical helper that resolves when the element scrolls into view
+// Renderer Function — 3 params, handles hydration itself, CLIENT ONLY.
+// Optionally return a { teardown } wrapper, or a promise resolving to one.
+// React on Rails runs it on Turbo/Turbolinks navigation or same-id replacement.
+const LazyHydrate = (props, _railsContext, domNodeId) =>
   whenVisible(domNodeId).then(() => {
-    const root = document.getElementById(domNodeId);
-    ReactDOM.hydrateRoot(root, <HelloMessage {...props} />);
+    const domNode = document.getElementById(domNodeId);
+    // Navigation may remove the node before visibility resolves, so there is no mounted root to clean up.
+    if (!domNode) return undefined;
+
+    const root = ReactDOMClient.hydrateRoot(domNode, <HelloMessage {...props} />);
+    return { teardown: () => root.unmount() };
   });
-};
 
 ReactOnRails.register({ HelloMessage, HelloWithContext, HelloHash, LazyHydrate });
 ```
 
+`whenVisible` is a hypothetical helper that resolves when the element scrolls into view. The `LazyHydrate` example uses a concise-body arrow, so it returns the `whenVisible(...).then(...)` promise. If navigation removes the node before hydration runs, the callback returns nothing because there is no mounted root to clean up. If you switch the renderer to a `{ }` block body, add an explicit `return` or React on Rails will not receive the teardown wrapper.
+
 The rest of this document focuses on **render functions** — the most flexible of the three types, with the richest set of return values. For renderer functions (client-side mounting control), see [Renderer Functions](../api-reference/view-helpers-api.md#renderer-functions-function-that-will-call-reactdomrender-or-reactdomhydrate) in the view helpers reference.
 
 ### Compatibility matrix: component types and Ruby helpers

packages/react-on-rails/src/types/index.ts

@@ -524,6 +524,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

react_on_rails/spec/dummy/client/app-react16/startup/ManualRenderApp.jsx

@@ -13,9 +13,21 @@ export default (props, _railsContext, domNodeId) => {
   );
 
   const domNode = document.getElementById(domNodeId);
+  if (!domNode) {
+    const renderMode = props.prerender ? 'hydrate' : 'render';
+    throw new Error(
+      `Cannot ${renderMode} ManualRenderApp because DOM element with id "${domNodeId}" was not found.`,
+    );
+  }
+
   if (props.prerender) {
     ReactDOM.hydrate(reactElement, domNode);
   } else {
     ReactDOM.render(reactElement, domNode);
   }
+
+  // Return a teardown wrapper so React on Rails unmounts this tree on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it. The React 16/17 API unmounts
+  // by container node rather than via a root handle.
+  return { teardown: () => ReactDOM.unmountComponentAtNode(domNode) };
 };

react_on_rails/spec/dummy/client/app-react16/startup/ReduxApp.client.jsx

@@ -23,10 +23,19 @@ import { wrapElementInStrictMode } from '../../app/strictModeSupport';
  *
  */
 export default (props, railsContext, domNodeId) => {
-  const render = props.prerender ? ReactDOM.hydrate : ReactDOM.render;
+  const { prerender } = props;
+  const render = prerender ? ReactDOM.hydrate : ReactDOM.render;
   // eslint-disable-next-line no-param-reassign
   delete props.prerender;
 
+  const domNode = document.getElementById(domNodeId);
+  if (!domNode) {
+    const renderMode = prerender ? 'hydrate' : 'render';
+    throw new Error(
+      `Cannot ${renderMode} ReduxApp because DOM element with id "${domNodeId}" was not found.`,
+    );
+  }
+
   const combinedReducer = combineReducers(reducers);
   const combinedProps = composeInitialState(props, railsContext);
 
@@ -39,14 +48,16 @@ export default (props, railsContext, domNodeId) => {
 
   // Provider uses this.props.children, so we're not typical React syntax.
   // This allows redux to add additional props to the HelloWorldContainer.
+  // The React 16/17 API re-renders into the same container idempotently, so hot reload reuses the
+  // existing tree (no separate root to unmount first).
   const renderApp = (Komponent) => {
     const element = wrapElementInStrictMode(
       <Provider store={store}>
         <Komponent />
       </Provider>,
     );
 
-    render(element, document.getElementById(domNodeId));
+    render(element, domNode);
   };
 
   renderApp(HelloWorldContainer);
@@ -57,4 +68,9 @@ export default (props, railsContext, domNodeId) => {
       renderApp(HelloWorldContainer);
     });
   }
+
+  // Return a teardown wrapper so React on Rails unmounts this tree on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it. The React 16/17 API unmounts
+  // by container node rather than via a root handle.
+  return { teardown: () => ReactDOM.unmountComponentAtNode(domNode) };
 };

react_on_rails/spec/dummy/client/app-react16/startup/ReduxSharedStoreApp.client.jsx

@@ -17,10 +17,19 @@ import { wrapElementInStrictMode } from '../../app/strictModeSupport';
  *  React will see that the state is the same and not do anything.
  */
 export default (props, _railsContext, domNodeId) => {
-  const render = props.prerender ? ReactDOM.hydrate : ReactDOM.render;
+  const { prerender } = props;
+  const render = prerender ? ReactDOM.hydrate : ReactDOM.render;
   // eslint-disable-next-line no-param-reassign
   delete props.prerender;
 
+  const domNode = document.getElementById(domNodeId);
+  if (!domNode) {
+    const renderMode = prerender ? 'hydrate' : 'render';
+    throw new Error(
+      `Cannot ${renderMode} ReduxSharedStoreApp because DOM element with id "${domNodeId}" was not found.`,
+    );
+  }
+
   // This is where we get the existing store.
   const store = ReactOnRails.getStore('SharedReduxStore');
 
@@ -29,13 +38,15 @@ export default (props, _railsContext, domNodeId) => {
 
   // Provider uses this.props.children, so we're not typical React syntax.
   // This allows redux to add additional props to the HelloWorldContainer.
+  // The React 16/17 API re-renders into the same container idempotently, so hot reload reuses the
+  // existing tree (no separate root to unmount first).
   const renderApp = (Component) => {
     const element = wrapElementInStrictMode(
       <Provider store={store}>
         <Component />
       </Provider>,
     );
-    render(element, document.getElementById(domNodeId));
+    render(element, domNode);
   };
 
   renderApp(HelloWorldContainer);
@@ -45,4 +56,9 @@ export default (props, _railsContext, domNodeId) => {
       renderApp(HelloWorldContainer);
     });
   }
+
+  // Return a teardown wrapper so React on Rails unmounts this tree on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it. The React 16/17 API unmounts
+  // by container node rather than via a root handle.
+  return { teardown: () => ReactDOM.unmountComponentAtNode(domNode) };
 };

react_on_rails_pro/spec/dummy/client/app/loadable/loadable-client.imports-loadable.jsx

@@ -7,16 +7,23 @@ import { HelmetProvider } from '@dr.pogodin/react-helmet';
 import ClientApp from './LoadableApp';
 import { wrapElementInStrictMode } from '../strictModeSupport';
 
-const App = (props, railsContext, domNodeId) => {
-  loadableReady(() => {
+const App = (props, railsContext, domNodeId) =>
+  // loadableReady resolves once the split chunks are present, then we hydrate. Returning the promise
+  // (which resolves to a teardown wrapper) lets React on Rails unmount this root on Turbo/Turbolinks
+  // navigation or same-id node replacement instead of leaking it. The callback form would discard it.
+  loadableReady().then(() => {
     const el = document.getElementById(domNodeId);
+    // Navigation may remove the node before chunks resolve; no root was mounted,
+    // so React on Rails treats undefined as no teardown.
+    if (!el) return undefined;
+
     const reactElement = wrapElementInStrictMode(
       <HelmetProvider>
         {React.createElement(ClientApp, { ...props, path: railsContext.pathname })}
       </HelmetProvider>,
     );
-    hydrateRoot(el, reactElement);
+    const root = hydrateRoot(el, reactElement);
+    return { teardown: () => root.unmount() };
   });
-};
 
 export default App;

react_on_rails_pro/spec/dummy/client/app/ror-auto-load-components/ApolloGraphQLApp.client.jsx

@@ -23,10 +23,20 @@ export default (_props, _railsContext, domNodeId) => {
     ssrForceFetchDelay: 100,
   });
   const el = document.getElementById(domNodeId);
+  if (!el) {
+    throw new Error(
+      `Cannot hydrate ApolloGraphQLApp because DOM element with id "${domNodeId}" was not found.`,
+    );
+  }
+
   const App = wrapElementInStrictMode(
     <ApolloProvider client={client}>
       <ApolloGraphQL />
     </ApolloProvider>,
   );
-  hydrateRoot(el, App);
+  const root = hydrateRoot(el, App);
+
+  // Return a teardown wrapper so React on Rails unmounts this root on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it.
+  return { teardown: () => root.unmount() };
 };

react_on_rails_pro/spec/dummy/client/app/ror-auto-load-components/LazyApolloGraphQLApp.client.tsx

@@ -16,9 +16,12 @@ export default (_props: unknown, _railsContext: RailsContext, domNodeId: string)
     throw new Error(`Missing DOM element with id: ${domNodeId}`);
   }
 
-  console.log('window.__SSR_COMPUTATION_CACHE', window.__SSR_COMPUTATION_CACHE);
   const ssrComputationCache = window.__SSR_COMPUTATION_CACHE;
   setSSRCache(ssrComputationCache);
   const App = wrapElementInStrictMode(<ApolloGraphQL />);
-  hydrateRoot(el, App);
+  const root = hydrateRoot(el, App);
+
+  // Return a teardown wrapper so React on Rails unmounts this root on Turbo/Turbolinks navigation
+  // (page unload) or same-id node replacement instead of leaking it.
+  return { teardown: () => root.unmount() };
 };