feat: add app_wraps to VarData for Var-driven provider injection (#6447)

* feat: add app_wraps to VarData for Var-driven provider injection

Lets Vars declare app-level wrapper components in their VarData so the
compiler can mount providers (state context, event loop, upload, etc.)
based on what's actually used, instead of relying on hardcoded chains
or special-case logic. State/event-loop providers now ride along on
VarData.from_state and the events-hook helper, and UploadFilesProvider
is mounted when selected_files/upload_file is referenced — even without
an Upload component on the page. Layout renders the assembled chain so
AppWrap reduces to hooks + children.

* refactor: reach addEvents via module-level import instead of hook hoist

EventLoopProvider now populates a module-level addEvents in
$/utils/context, so JSX literals constructed outside the React-tree
hoist path (e.g. ErrorBoundary.onError) can dispatch events without
useContext(EventLoopContext) being lexically in scope. State and
event-loop providers ride along on event-invocation VarData.app_wraps
(and via _get_event_app_wraps) so they still mount in the app root.
connectErrors stays on useContext since it drives re-renders;
AppWrap is now a Fragment rendering the chain in its body.

* fix: don't memoize subtrees reactive only via no-arg event triggers

Per review: a no-arg handler (on_click=State.ping) surfaces only through
event_triggers and reaches addEvents via a module-level import, not a
hoisted hook. The inline callback carries no reactive data and never
drives a re-render, so wrapping it in a memo gains nothing. Drop the
event_triggers fast-path from the reactive-data check and let such
callbacks render in the page module. Handlers that reference state still
surface through the per-Var scan and memoize as before.

* fix: clear render cache on Component deepcopy to prevent dropped children

App._app_root deep-copies app-wrap components and rebinds their children
to assemble the provider chain. __copy__ already drops the render-path
caches for this reason, but copy.deepcopy preserved them, so a component
rendered during page compilation (e.g. a State/EventLoop/UploadFiles
provider injected via VarData.app_wraps) returned its stale, childless
_cached_render_result after children were appended. The page content
(children/Outlet) was silently dropped and the page rendered blank.

Add a __deepcopy__ that mirrors __copy__: the clone is for compile-time
mutation, so render caches are not carried over. Extract the shared cache
attr list to _COMPILE_CACHE_ATTRS. Regression test fails before the fix.

* perf: reuse fetched hooks across page-hook and app-wrap collection

The page collector already pulls _get_hooks_internal/_get_added_hooks for
page-hook aggregation; pass those dicts into the Var app-wrap scan instead of
re-fetching, so each component avoids a second (uncached) _get_added_hooks and
_get_event_app_wraps per compile. Event-trigger providers now surface solely
through the Var scan, dropping the event_triggers special-case in the
subclass-override app-wrap path.

* fix: mixed event/function dispatch must reach addEvents via module import

The mixed-dispatch path (_dispatch_mixed_event_var, used by
on_click=lambda: rx.cond(..., function_var, event_spec)) still emitted the
legacy hooks={Hooks.EVENTS: None} hook — const [addEvents, connectErrors]
= useContext(EventLoopContext) — but Imports.EVENTS no longer imports
EventLoopContext. The rendered component threw "ReferenceError:
EventLoopContext is not defined", crashing the page and failing the
test_event_chain_click integration tests.

Match the other dispatch sites: reach addEvents through the module-level
import and ride the state/event-loop providers on app_wraps via
get_event_app_wraps(). Drop the now-unused Hooks import. Regression test
covers the mixed-dispatch VarData.

* test: fix tab indentation in postcss config fixture string

* perf: share state/event-loop app-wrap providers as cached singletons

Construct StateProvider/EventLoopProvider once and reuse them instead of
rebuilding per state Var. This is now safe because consumers deep-copy before
rebinding children and the render-cache no longer survives deepcopy, so the
shared markers are never mutated; it lets the page-tree deepcopy and render
hash memoize them. VarData.add_state now routes through get_event_app_wraps()
for the single source of truth.

* test: assert upload provider stays out when no upload Vars are used

* refactor: centralize app-wrap merge dedup, raise on conflicting slots

Extract the per-(priority, tag) app-wrap merge rule into a shared
insert_app_wraps primitive used by both VarData.merge and the compiler's
page-wide collection, so the dedup logic lives in one place. Two
different wrappers claiming the same slot now raise instead of silently
keeping the first. Hash app_wraps as a frozenset so merge order no longer
affects VarData identity (a + b == b + a).

Author: FarhanAliRaza

news/6447.feature.md

@@ -0,0 +1 @@
+Event handlers attached to JSX literals built outside a component's render scope — such as an `ErrorBoundary`'s `onError` — can now dispatch events. `addEvents` is reached through a module-level import that `EventLoopProvider` populates on each render, so dispatch no longer depends on a `useContext` hook being hoisted into the calling scope. The state and event-loop providers, previously hard-coded in the layout template, are now injected around the app root by the compiler from the `app_wraps` declared on the `Var`s that use them.

packages/reflex-base/news/6447.feature.md

@@ -0,0 +1 @@
+`VarData` gained an `app_wraps` field so a `Var` can declare the app-level wrapper components it requires; the compiler injects them around the app root, deduped by `(priority, tag)`. This is how the state and event-loop providers now reach the React tree, since event dispatch reaches `addEvents` via a module-level import (`Imports.EVENTS`) rather than a hoisted hook. The still-reactive `connectErrors` value moves to its own `CONNECT_ERRORS` import/hook, and `Component` deep copies now drop the render cache so compile-time clones (e.g. the app-root wrapper chain) render their mutated children.

packages/reflex-base/src/reflex_base/compiler/templates.py

@@ -200,7 +200,7 @@ def app_root_template(
     return f"""
 {imports_str}
 {dynamic_imports_str}
-import {{ EventLoopProvider, StateProvider, defaultColorMode }} from "$/utils/context";
+import {{ defaultColorMode }} from "$/utils/context";
 import {{ ThemeProvider }} from '$/utils/react-theme';
 import {{ Layout as AppLayout }} from './_document';
 import {{ Outlet }} from 'react-router';
@@ -218,11 +218,7 @@ def app_root_template(
   }}, []);
 
   return jsx(ThemeProvider, {{defaultTheme: defaultColorMode, attribute: "class"}},
-    jsx(StateProvider, {{}},
-      jsx(EventLoopProvider, {{}},
-        jsx(AppWrap, {{}}, children)
-      )
-    )
+    jsx(AppWrap, {{}}, children)
   );
 }}
 
@@ -373,6 +369,24 @@ def context_template(
 
 export const isDevMode = {json.dumps(is_dev_mode)};
 
+// Module-level event dispatchers populated by ``EventLoopProvider`` on each
+// render. Components reach addEvents/connectErrors via this import instead of
+// hoisting ``useContext(EventLoopContext)`` so JSX literals (e.g.
+// ``ErrorBoundary.onError``) constructed in any JS scope can dispatch events
+// without depending on lexical hook hoisting.
+let _addEventsImpl = (events, args, event_actions) => {{
+  console.warn("addEvents called before EventLoopProvider mounted", events);
+}};
+let _connectErrorsImpl = [];
+
+export function addEvents(events, args, event_actions) {{
+  return _addEventsImpl(events, args, event_actions);
+}}
+
+export function getConnectErrors() {{
+  return _connectErrorsImpl;
+}}
+
 export function UploadFilesProvider({{ children }}) {{
   const [filesById, setFilesById] = useState({{}})
   refs["__clear_selected_files"] = (id) => setFilesById(filesById => {{
@@ -403,14 +417,19 @@ def context_template(
 
 export function EventLoopProvider({{ children }}) {{
   const dispatch = useContext(DispatchContext)
-  const [addEvents, connectErrors] = useEventLoop(
+  const [addEventsLocal, connectErrors] = useEventLoop(
     dispatch,
     initialEvents,
     clientStorage,
   )
+  // Populate the module-level dispatchers so JSX literals constructed
+  // outside the React-tree path (e.g. ``ErrorBoundary.onError``) can call
+  // ``addEvents`` without needing the events hook hoisted in their scope.
+  _addEventsImpl = addEventsLocal;
+  _connectErrorsImpl = connectErrors;
   return createElement(
     EventLoopContext.Provider,
-    {{ value: [addEvents, connectErrors] }},
+    {{ value: [addEventsLocal, connectErrors] }},
     children
   );
 }}

packages/reflex-base/src/reflex_base/components/component.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import contextlib
+import copy
 import dataclasses
 import enum
 import functools
@@ -279,6 +280,15 @@ def _finalize_fields(
         }
 
 
+_COMPILE_CACHE_ATTRS = (
+    "_cached_render_result",
+    "_vars_cache",
+    "_imports_cache",
+    "_hooks_internal_cache",
+    "_get_component_prop_property",
+)
+
+
 class BaseComponent(metaclass=BaseComponentMeta):
     """The base class for all Reflex components.
 
@@ -349,16 +359,36 @@ def __copy__(self) -> BaseComponent:
         new._clear_compile_caches()
         return new
 
+    def __deepcopy__(self, memo: dict[int, Any]) -> BaseComponent:
+        """Return a deep copy suitable for compile-time mutation.
+
+        Like :meth:`__copy__`, the clone exists for the compiler to mutate
+        (e.g. rebinding ``children`` while assembling the app-wrap chain in
+        ``App._app_root``), so the render-path caches populated on the
+        original are not carried over — otherwise ``render()`` on the mutated
+        clone would return the pre-mutation result. Unlike ``__copy__``,
+        nested mutable containers are deep-copied so the clone is fully
+        independent of the original.
+
+        Args:
+            memo: The deepcopy memo mapping object ids to their copies.
+
+        Returns:
+            A deep-copied instance with compile-time caches dropped.
+        """
+        new = self.__class__.__new__(self.__class__)
+        memo[id(self)] = new
+        new_dict = vars(new)
+        for key, value in vars(self).items():
+            if key in _COMPILE_CACHE_ATTRS:
+                continue
+            new_dict[key] = copy.deepcopy(value, memo)
+        return new
+
     def _clear_compile_caches(self) -> None:
         """Clear cached render/compiler artifacts after compile-time mutation."""
         attrs = cast("dict[str, Any]", vars(self))
-        for attr in (
-            "_cached_render_result",
-            "_vars_cache",
-            "_imports_cache",
-            "_hooks_internal_cache",
-            "_get_component_prop_property",
-        ):
+        for attr in _COMPILE_CACHE_ATTRS:
             attrs.pop(attr, None)
 
     def __eq__(self, value: Any) -> bool:
@@ -1970,14 +2000,16 @@ def _get_vars_hooks(self) -> dict[str, VarData | None]:
     def _get_events_hooks(self) -> dict[str, VarData | None]:
         """Get the hooks required by events referenced in this component.
 
+        Always empty: ``addEvents`` is reached via the module-level import
+        in ``Imports.EVENTS``, so events need no in-scope hook. The state/
+        event-loop providers they still depend on are mounted as app wraps
+        instead — carried on the event invocation's ``VarData.app_wraps``
+        and via :meth:`_get_event_app_wraps`.
+
         Returns:
-            The hooks for the events.
+            An empty dict.
         """
-        return (
-            {Hooks.EVENTS: VarData(position=Hooks.HookPosition.INTERNAL)}
-            if self.event_triggers
-            else {}
-        )
+        return {}
 
     def _get_hooks_internal(self) -> dict[str, VarData | None]:
         """Get the React hooks for this component managed by the framework.
@@ -2132,6 +2164,35 @@ def _get_app_wrap_components() -> dict[tuple[int, str], Component]:
         """
         return {}
 
+    def _get_event_app_wraps(self) -> dict[tuple[int, str], Component]:
+        """Return state/event-loop providers required by event triggers.
+
+        A component with event triggers calls ``addEvents`` at runtime,
+        which only does anything if ``StateProvider`` (supplies the
+        dispatch context) and ``EventLoopProvider`` (runs the websocket)
+        are mounted as ancestors. ``addEvents`` now comes from a
+        module-level import rather than an in-scope hook, so nothing drags
+        those providers into the tree on its own — this method requests
+        them explicitly as app wraps.
+
+        Kept separate from :meth:`_get_app_wrap_components` because
+        subclasses override that method to add their own app wraps; folding
+        these in would let such an override silently drop them.
+
+        Returns:
+            The state/event-loop provider entries (empty if no event
+            triggers are bound).
+        """
+        if not self.event_triggers:
+            return {}
+        # Lazy import: state_context imports from this module.
+        from reflex_base.components.state_context import get_event_app_wraps
+
+        return {
+            (priority, provider.tag or type(provider).__name__): provider
+            for priority, provider in get_event_app_wraps()
+        }
+
     def _get_all_app_wrap_components(
         self, *, ignore_ids: set[int] | None = None
     ) -> dict[tuple[int, str], Component]:

packages/reflex-base/src/reflex_base/components/state_context.py

@@ -0,0 +1,68 @@
+"""App-wrap components mounting the state and event-loop React providers.
+
+These wrap children in the ``StateProvider`` / ``EventLoopProvider`` JS
+functions emitted into ``utils/context.js`` by ``compile_contexts``. They are
+attached to the VarData returned by :meth:`reflex_base.vars.base.VarData.from_state`
+so the compiler picks them up through the generic Var-driven app-wrap pipeline,
+rather than the JS Layout template hard-coding them around every app.
+"""
+
+from __future__ import annotations
+
+from reflex_base.components.component import Component
+from reflex_base.constants import Dirs
+from reflex_base.constants.compiler import Hooks
+from reflex_base.vars.base import VarData
+
+
+class StateContextProvider(Component):
+    """App wrap that mounts the React state-context provider around children."""
+
+    library = f"$/{Dirs.CONTEXTS_PATH}"
+    tag = "StateProvider"
+
+
+class EventLoopContextProvider(Component):
+    """App wrap that mounts the websocket event-loop provider around children."""
+
+    library = f"$/{Dirs.CONTEXTS_PATH}"
+    tag = "EventLoopProvider"
+
+
+_event_app_wraps: tuple[tuple[int, Component], ...] | None = None
+
+
+def get_event_app_wraps() -> tuple[tuple[int, Component], ...]:
+    """Return state/event-loop providers required when events are dispatched.
+
+    ``StateProvider`` (100) wraps further out than ``EventLoopProvider`` (90)
+    because the latter reads ``DispatchContext`` from the former.
+
+    The two providers are created once and shared: they are immutable markers
+    deduped by ``(priority, tag)``, and every consumer (``App._app_root``)
+    deep-copies them before rebinding children, so the shared instances are
+    never mutated in place. Sharing also lets the page-tree deepcopy and the
+    render-hash memoize them instead of paying per state Var.
+
+    Returns:
+        ``(priority, provider)`` entries deduped by the compiler.
+    """
+    global _event_app_wraps
+    if _event_app_wraps is None:
+        _event_app_wraps = (
+            (100, StateContextProvider.create()),
+            (90, EventLoopContextProvider.create()),
+        )
+    return _event_app_wraps
+
+
+def get_events_hooks_var_data() -> VarData:
+    """Build the VarData advertising the state/event-loop app wraps.
+
+    Returns:
+        A new VarData carrying both providers as app_wraps.
+    """
+    return VarData(
+        position=Hooks.HookPosition.INTERNAL,
+        app_wraps=get_event_app_wraps(),
+    )

packages/reflex-base/src/reflex_base/constants/compiler.py

@@ -148,20 +148,34 @@ class CompileContext(str, Enum):
 class Imports(SimpleNamespace):
     """Common sets of import vars."""
 
+    # ``addEvents`` is a module-level callable populated by
+    # ``EventLoopProvider``; importing it sidesteps the lexical-scope
+    # constraint a ``useContext(EventLoopContext)`` hoist would impose.
     EVENTS = {
-        "react": [ImportVar(tag="useContext")],
-        f"$/{Dirs.CONTEXTS_PATH}": [ImportVar(tag="EventLoopContext")],
+        f"$/{Dirs.CONTEXTS_PATH}": [ImportVar(tag=CompileVars.ADD_EVENTS)],
         f"$/{Dirs.STATE_PATH}": [
             ImportVar(tag=CompileVars.TO_EVENT),
             ImportVar(tag=CompileVars.APPLY_EVENT_ACTIONS),
         ],
     }
 
+    # ``connectErrors`` is reactive — it drives connection-banner
+    # re-renders — so its consumers still go through ``useContext``.
+    CONNECT_ERRORS = {
+        "react": [ImportVar(tag="useContext")],
+        f"$/{Dirs.CONTEXTS_PATH}": [ImportVar(tag="EventLoopContext")],
+    }
+
 
 class Hooks(SimpleNamespace):
     """Common sets of hook declarations."""
 
+    # Kept for legacy callers that still key off this string; the
+    # compiler no longer auto-hoists it.
     EVENTS = f"const [{CompileVars.ADD_EVENTS}, {CompileVars.CONNECT_ERROR}] = useContext(EventLoopContext);"
+    CONNECT_ERRORS = (
+        f"const {CompileVars.CONNECT_ERROR} = useContext(EventLoopContext)[1];"
+    )
 
     class HookPosition(enum.Enum):
         """The position of the hook in the component."""

packages/reflex-base/src/reflex_base/event/__init__.py

@@ -29,7 +29,7 @@
 
 from reflex_base import constants
 from reflex_base.components.field import BaseField
-from reflex_base.constants.compiler import CompileVars, Hooks, Imports
+from reflex_base.constants.compiler import CompileVars, Imports
 from reflex_base.utils import format
 from reflex_base.utils.decorator import once
 from reflex_base.utils.exceptions import (
@@ -1080,14 +1080,14 @@ def _as_event_spec(
         """
         from reflex_components_core.core.upload import (
             DEFAULT_UPLOAD_ID,
-            upload_files_context_var_data,
+            get_upload_files_context_var_data,
         )
 
         upload_id = self.upload_id if self.upload_id is not None else DEFAULT_UPLOAD_ID
         upload_files_var = Var(
             _js_expr="filesById",
             _var_type=dict[str, Any],
-            _var_data=VarData.merge(upload_files_context_var_data),
+            _var_data=VarData.merge(get_upload_files_context_var_data()),
         ).to(ObjectVar)[LiteralVar.create(upload_id)]
         spec_args = [
             (
@@ -2098,11 +2098,14 @@ def _dispatch_mixed_event_var(event_like_var: Var) -> FunctionVar:
             _js_expr=f'typeof {alias_name} === "function"',
             _var_type=bool,
         )
+        # Lazy import: state_context → component → event (this module).
+        from reflex_base.components.state_context import get_event_app_wraps
+
         add_events = FunctionStringVar.create(
             CompileVars.ADD_EVENTS,
             _var_data=VarData(
                 imports=Imports.EVENTS,
-                hooks={Hooks.EVENTS: None},
+                app_wraps=get_event_app_wraps(),
             ),
         )
         dispatch_expr = ternary_operation(
@@ -2418,11 +2421,14 @@ def create(
             arg_def_expr = Var(_js_expr="args")
 
         if value.invocation is None:
+            # Lazy import: state_context → component → event (this module).
+            from reflex_base.components.state_context import get_event_app_wraps
+
             invocation = FunctionStringVar.create(
                 CompileVars.ADD_EVENTS,
                 _var_data=VarData(
                     imports=Imports.EVENTS,
-                    hooks={Hooks.EVENTS: None},
+                    app_wraps=get_event_app_wraps(),
                 ),
             )
         else:
@@ -2463,11 +2469,14 @@ def create(
                 _js_expr=f"{{{''.join(f'{statement};' for statement in statements)}}}",
             )
             if value.event_actions:
+                # Lazy import: state_context → component → event (this module).
+                from reflex_base.components.state_context import get_event_app_wraps
+
                 apply_event_actions = FunctionStringVar.create(
                     CompileVars.APPLY_EVENT_ACTIONS,
                     _var_data=VarData(
                         imports=Imports.EVENTS,
-                        hooks={Hooks.EVENTS: None},
+                        app_wraps=get_event_app_wraps(),
                     ),
                 )
                 return_expr = apply_event_actions.call(