feat: allow explicit only event handlers

[benedikt-bartscher]

Closes #7032

[greptile-apps]

Greptile Summary

The PR adds an opt-in mode in which only methods decorated with @rx.event are registered as State event handlers. The latest changes also make State configuration resolution local to the active registration or in-progress configuration load.

• Adds state_explicit_event_handlers configuration and documentation.
• Marks decorated functions so State discovery can distinguish handlers from ordinary public helpers.
• Replaces the process-global State flag cache with context-local configuration resolution.
• Adds coverage for reload ordering, post-config State declarations, failure rollback, and separate registration contexts.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the current context-local resolution and in-progress config publication address all three previously reported configuration-selection defects.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/config.py	Resolves State flags from the in-progress config load or active RegistrationContext, addressing stale, ordering-dependent, and cross-context selection.
packages/reflex-base/src/reflex_base/event/init.py	Marks functions processed by every supported event decorator form for explicit handler discovery.
reflex/state.py	Filters user-defined State handlers by the event marker when explicit mode is enabled while retaining existing behavior for built-in states.
tests/units/test_state.py	Covers explicit handler registration and the three previously reported configuration-selection failures.
tests/units/test_event.py	Verifies that plain, configured, and background event decorators all apply the event marker.

_{Reviews (6): Last reviewed commit: "Merge remote-tracking branch 'upstream/m..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 32 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing benedikt-bartscher:disable-implicit-event-handlers (689dc48) with main (2459ded)²}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (f3aef84) during the generation of this report, so 2459ded was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[cubic-dev-ai]

All reported issues were addressed across 8 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 8 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[masenf]

great, this gives us a lever and a chicken switch for eventually defaulting to requiring the decorator for event handlers.

need to ensure that reflex-enterprise's auth plugin and other integration points can still work with this new structure, but it seems like it would at first glance.

[abulvenz]

Might also become default one day, following the Zen of Python

Explicit is better than implicit.

[benedikt-bartscher]

yeah, i wanted to go the same route as i did with state_auto_setters.

1. introduce a flag to enable explicit mode - let feature stabilize and some projects adopt
2. change the default to explicit
3. drop implicit mode