[transitions] Prevent exit transitions from getting stuck

[ZeeshanTamboli]

Fix transitions that can get stuck in exiting when React reconnects effects or when a Modal’s portal container changes during an exit.

The transition completion timer/listener is rearmed after effects reconnect without repeating lifecycle callbacks such as onExit or onExiting.

Modal now retains its last resolved portal container while exiting. This prevents React from remounting the transition subtree before onExited fires, ensuring the Modal unmounts and releases its scroll lock. Subsequent opens use the latest container.

Added regression tests covering:

• Transition completion after effects reconnect.
• Portal container changes during an active exit.
• Lifecycle callbacks firing exactly once.
• Modal cleanup, unmounting, and reopening in the new container.

Fixes #32286.

[code-infra-dashboard]

Deploy preview

https://deploy-preview-48881--material-ui.netlify.app/

Bundle size

Bundle	Parsed size	Gzip size
@mui/material	🔺+167B(+0.03%)	🔺+51B(+0.03%)
@mui/lab	0B(0.00%)	0B(0.00%)
@mui/private-theming	0B(0.00%)	0B(0.00%)
@mui/system	0B(0.00%)	0B(0.00%)
@mui/utils	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[LukasTy]

Nice fix -- both halves are needed (the Transition change alone does not stop the portal remount, and the Modal change alone does not survive an effects reconnect). Two things before merging.

1. [P1] A reconnected effect can schedule completion for a superseded phase --

material-ui/packages/mui-material/src/internal/Transition.tsx

Lines 400 to 428 in ea3d35e

	return;
	}
	const prev = lastFiredStatusRef.current;
	const statusChanged = prev !== status;
	if (statusChanged) {
	lastFiredStatusRef.current = status;
	}
	const current = propsRef.current;
	if (status === 'entering') {
	if (statusChanged) {
	current.onEntering?.(isAppearingRef.current);
	}
	if (nextCallbackRef.current === null) {
	scheduleTransitionEnd('entered', 'entering');
	}
	} else if (status === 'exiting') {
	if (statusChanged) {
	current.onExiting?.();
	}
	if (nextCallbackRef.current === null) {
	scheduleTransitionEnd('exited', 'exiting');
	}
	} else if (status === 'entered' && statusChanged) {
	current.onEntered?.(isAppearingRef.current);
	} else if (status === 'exited' && statusChanged) {
	current.onExited?.();
	}
	}, [propsRef, scheduleTransitionEnd, status]);

Moving the scheduling outside the statusChanged guard means it runs against the rendered status, which is stale when the reconciliation effect starts a new phase in the same commit that effects reconnect. It arms completion for the phase that was just abandoned, and because nextCallbackRef.current is non-null by then, the real phase never gets its own timer.

Verified on this branch (React 19.2.8):

• exit in flight -> React.Activity hidden -> visible again with in={true} in the same commit: onExited fires once despite in={true}, onEnter/onEntering fire twice, and the status is still entering after the full timeout.
• enter in flight -> hidden -> visible with in={false}: mirror image -- spurious onEntered, onExit/onExiting twice, still exiting.

Both are correct on master, so this is a regression. It is not Activity-specific either -- a Suspense boundary that re-suspends and resolves disconnects effects the same way. For Modal, the erroneous onExited runs handleClose() and onTransitionExited while the modal is open, dropping the scroll lock and the manager registration.

Completion should only be scheduled when the rendered phase is still current:

if (nextCallbackRef.current === null && statusRef.current === status) {

Verified: fixes both directions, and the new restarts completion when effects reconnect while exiting test plus ~1500 tests across the transition-adjacent suites still pass.

Worth two more regression tests next to the existing one: reconnect while entering, and reconnect with in flipped -- the latter is what catches this.

2. [P2, pre-existing] Changing disablePortal during exit still loses the transition --

material-ui/packages/mui-material/src/Modal/useModal.ts

Lines 226 to 229 in ea3d35e

	// Changing a portal's container remounts its children. Keep an exiting transition in its
	// current container so it can finish and notify the modal that it is safe to unmount.
	const portalContainer =
	!open && hasTransition && !exited ? (lastMountNodeRef.current ?? container) : container;

Freezing container covers one source of portal remounts, but toggling disablePortal changes Portal topology and remounts the children too. With a 100ms exit and closeAfterTransition, neither direction ever fires onExited/onTransitionExited, so document.body.style.overflow stays hidden. true -> false also drops the Modal from the DOM; false -> true leaves the hidden Modal root mounted.

This reproduces on master too, so it is not introduced here -- but it is the same failure mode this PR is fixing, and the fix shape is the same: preserve the effective disablePortal alongside the resolved container until the exit completes. Reasonable to defer to a follow-up.

[ZeeshanTamboli]

[P1] A reconnected effect can schedule completion for a superseded phas

@LukasTy Fixed this. Makes sense.

[LukasTy]

Claude Opus 5 review

Fix looks right -- I re-ran the two reported repros plus reconnect-while-entering, a double in flip while hidden, and unmountOnExit + flip, all correct now. Three follow-ups.

1. [P1] The fix landed without a regression test -- Transition.test.tsx is unchanged since ea3d35e.

The existing restarts completion when effects reconnect while exiting test passed before this fix too, so nothing currently guards it. This one fails on ea3d35e (data-status stays entering) and passes on 559e8fa; verified in both the node and chromium projects, eslint and prettier clean:

it.skipIf(!('Activity' in React))(
  'does not complete the superseded phase when in flips on reconnect',
  () => {
    const handlers = {
      onEnter: spy(),
      onEntering: spy(),
      onEntered: spy(),
      onExit: spy(),
      onExiting: spy(),
      onExited: spy(),
    };

    function ActivityHarness(props: { in: boolean; mode: 'hidden' | 'visible' }) {
      return (
        <React.Activity mode={props.mode}>
          <TestHarness in={props.in} appear={false} timeout={100} handlers={handlers} />
        </React.Activity>
      );
    }

    const { setProps } = render(<ActivityHarness in mode="visible" />);
    setProps({ in: false, mode: 'visible' });
    expect(screen.getByTestId('target')).to.have.attribute('data-status', 'exiting');

    // Effects disconnect mid-exit, then reconnect in the same commit that `in` flips back.
    // The reconciliation effect starts entering before the lifecycle effect runs, so the
    // lifecycle effect must not schedule completion for the superseded exit.
    setProps({ in: false, mode: 'hidden' });
    clock.tick(50);
    setProps({ in: true, mode: 'visible' });
    clock.tick(100);

    expect(screen.getByTestId('target')).to.have.attribute('data-status', 'entered');
    expect(handlers.onEnter.callCount).to.equal(1);
    expect(handlers.onEntering.callCount).to.equal(1);
    expect(handlers.onEntered.callCount).to.equal(1);
    expect(handlers.onExited.callCount).to.equal(0);
  },
);

2. [P2] disablePortal toggled during exit -- still open, no reply yet.

Re-checked on 559e8fa: with a 100ms exit and closeAfterTransition, neither direction fires onExited/onTransitionExited, so document.body.style.overflow stays hidden. Confirmed it reproduces on master too, so it is pre-existing, not caused by this PR -- but it is the same failure mode, and the same fix shape applies (freeze the effective disablePortal alongside the resolved container). Fine to spin off as a follow-up issue; just want an explicit call rather than it going unnoticed.

3. [P3, minor] The re-arm restarts the phase from zero and re-invokes addEndListener.

Measured on this branch: addEndListener call count goes 1 -> 2 -> 3 across two reconnects (1 -> 3 for a single reconnect in StrictMode, since React double-invokes effects on Activity reveal). On master it stays at 1, so this is new. A user addEndListener that attaches a transitionend listener has no teardown hook, so dead listeners accumulate on the node. Relatedly, a reconnect every 60ms against a 100ms exit never completes -- still exiting after 1200ms, finishing only once the toggling stops.

Both are self-healing and need unusual input, so not a blocker. Flagging so the restart-from-zero semantics are a conscious trade-off rather than a surprise later.

[ZeeshanTamboli]

@LukasTy

Regarding P1:
I've added the suggested regression test. It fails without the statusRef.current === status guard and passes with the fix, so the superseded-phase case is now covered.

Regarding P2:
Agree this is related at the mechanism level: toggling disablePortal, like changing the portal container, can remount the subtree during an active exit and prevent transition completion. However, it is pre-existing and outside the original reproduction. We can do it separately,

Regarding P3:
Agreed. Reconnect currently re-arms completion from scratch because effect cleanup cancels the pending callback, and addEndListener does not provide a teardown contract. Consequently, the timeout restarts at its full duration and addEndListener can be invoked again, leaving previously registered listeners with cancelled callbacks. Avoiding that would require tracking the remaining duration and redesigning how listener completion survives effect disconnection. I'll treat that as a conscious limitation of this fix and document it as a known trade-off separately rather than expanding this PR.