react-doctor/activity-wraps-effect-heavy-subtree

Audit whether Effects inside a toggleable Activity should pause while hidden; Activity preserves DOM and state while cleaning up and later recreating Effects

Validation prompt

Confirm the detector match and collect the required evidence before deciding whether an edit is warranted.

Fires only on React 19.2+ when a JSX element resolving to React's Activity/unstable_Activity (named import, alias like unstable_Activity as UA, or <React.Activity> where the namespace object is React's default import or * as React binding) has a mode prop whose value is a NON-static, toggleable expression such as mode={open ? "visible" : "hidden"}, AND it wraps at least one capitalized same-file child component (collected from JSXOpeningElement JSXIdentifier names, excluding the locally-bound Activity name) whose function body contains one or more useEffect/useLayoutEffect calls.

Suppress when: suppress when: (1) mode is a static literal (mode="hidden", mode="visible", mode={"hidden"}) or absent (default visible), since a pinned boundary has no hide/show cycle; (2) the wrapped child is a member-expression tag like <Charts.Bar />, which is skipped during child collection (the trailing identifier is never looked up) even when a same-file Bar helper with effects exists, because such children resolve through an external namespace; (3) the boundary element ITSELF is a member-expression like <Calendar.Activity> whose namespace object (import * as Calendar from "./calendar") is not React's default/* as React binding: the detector rejects it at boundary detection so it never fires even though its same-file <Entry /> child is effectful; (4) the wrapped component is imported from another module (v1 is same-file only); (5) the children have no effect hooks; or (6) the tag is a user component named Activity imported from a non-react module. Toggling the effects intentionally on hide/show (a subscription that genuinely should pause while hidden) is benign-by-design and should be suppressed.

Evidence boundary

The diagnostic proves only that the detector’s modeled source pattern matched. It does not prove runtime impact, product intent, rendered failure, or that one remediation is correct.

Establish the environment, repository policy, exceptions, and required rendered or runtime evidence before deciding the occurrence.

Record one outcome:

• Confirmed failure: The required evidence establishes the violation.
• Rejected: A documented exception or false-positive predicate applies.
• Needs evidence: Named evidence can still be collected.
• Unavailable: Required evidence cannot be collected in this run.
• Waived with evidence: An authorized, scoped exception applies to an established failure.
• Observation: The review records an optional tradeoff without claiming a defect.

A waiver records its scope, authority, evidence, and review condition. It is not a pass or false positive.

Default severity is registry metadata. Use the occurrence’s JSON severity after repository configuration when ordering real findings.

Fix prompt

Apply this candidate correction only after the required evidence confirms the risk.

Keep Effects inside the Activity when their subscriptions or synchronization should stop while hidden and restart when visible. Lift only work that must remain active while the UI is hidden, or pre-resolve Suspense-compatible data above the boundary when that ownership is correct. Do not describe the cycle as a subtree remount: Activity preserves component state and DOM while cleaning up and recreating Effects. See https://react.dev/reference/react/Activity

Repository-wide copy prompt

Use this repository-wide prompt only after validating each occurrence. For one occurrence, use the guidance above.