pythonnative 0.23.0__py3-none-any.whl → 0.25.0__py3-none-any.whl

pythonnative/hooks.py

@@ -4,12 +4,26 @@ Provides React-like hooks for managing state, effects, memoization,
 context, and navigation within function components decorated with
 [`component`][pythonnative.component]. Hooks must be called at the top
 level of a component (not inside conditionals or loops) so they map to
-the same slot across renders.
-
-Effects are queued during the render phase and flushed *after* the
-reconciler commits native-view mutations. This ordering guarantees that
-effect callbacks can safely measure layout or interact with the
-committed native tree.
+the same slot across renders. In dev mode the framework verifies this
+and raises [`HookOrderError`][pythonnative.diagnostics.HookOrderError]
+on a violation instead of silently cross-wiring state.
+
+Two effect phases exist, mirroring React:
+
+- [`use_layout_effect`][pythonnative.use_layout_effect] callbacks run
+  synchronously inside the commit, after native mutations and the
+  layout pass have been applied. They can measure committed frames and
+  issue imperative view commands before the user sees the new frame.
+- [`use_effect`][pythonnative.use_effect] callbacks (passive effects)
+  run after the layout effects, at the end of the same commit. An
+  effect may be an ``async def``; it runs as a task on the framework
+  loop and is cancelled when its dependencies change or the component
+  unmounts.
+
+The current hook state travels in a :mod:`contextvars` context rather
+than a plain global, so ``async def`` component bodies keep their hook
+identity across ``await`` boundaries even when several coroutine
+renders interleave on the event loop.
 
 Example:
     ```python
@@ -20,27 +34,83 @@ Example:
         count, set_count = pn.use_state(initial)
         return pn.Column(
             pn.Text(f"Count: {count}"),
-            pn.Button("+", on_click=lambda: set_count(count + 1)),
+            pn.Button("+", on_press=lambda: set_count(count + 1)),
         )
     ```
 """
 
 import asyncio
 import inspect
-import threading
 from contextlib import contextmanager
+from contextvars import ContextVar, Token
 from dataclasses import dataclass, field, replace
 from typing import Any, Awaitable, Callable, Dict, Generator, Generic, List, Optional, Tuple, TypeVar
 
+from . import diagnostics
 from .element import Element
+from .suspense import CoroDriver, Resource
 
 T = TypeVar("T")
 
 _SENTINEL = object()
 
-_hook_context: threading.local = threading.local()
+# The component whose body is currently executing. A ContextVar (not a
+# global or thread-local) so coroutine component bodies resume with the
+# right hook state after every ``await``, no matter how renders
+# interleave on the loop.
+_hook_context: "ContextVar[Optional[HookState]]" = ContextVar("pn_hook_state", default=None)
+
+# Depth of nested ``batch_updates`` blocks plus the trigger deferred by
+# the outermost block, per execution context.
+_batch_depth: "ContextVar[int]" = ContextVar("pn_batch_depth", default=0)
+_batch_pending: "ContextVar[Optional[List[Callable[[], None]]]]" = ContextVar("pn_batch_pending", default=None)
+
+# Whether state updates in the current execution context were marked as
+# transitions (see ``use_transition``). Transition updates defer their
+# re-render to a later loop turn so urgent updates stay responsive.
+_transition_var: "ContextVar[bool]" = ContextVar("pn_transition", default=False)
+
+
+# ======================================================================
+# Ref
+# ======================================================================
+
+
+class Ref(Generic[T]):
+    """Mutable container returned by [`use_ref`][pythonnative.use_ref].
+
+    A ``Ref`` holds one value on its ``current`` attribute. Mutating
+    ``current`` never triggers a re-render, which makes refs the right
+    place for timers, last-seen values, and imperative handles.
+
+    When a ``Ref`` is passed to a built-in element via the ``ref=``
+    prop, the reconciler populates ``current`` with the underlying
+    native view (``UIView`` on iOS, ``android.view.View`` on Android,
+    a Tk widget on desktop) after commit, and clears it back to
+    ``None`` on unmount. Composite components (e.g.
+    [`FlatList`][pythonnative.FlatList]) instead publish a typed
+    controller object on ``current`` via
+    [`use_imperative_handle`][pythonnative.use_imperative_handle].
+
+    Attributes:
+        current: The referenced value. ``None`` until populated.
+    """
+
+    __slots__ = ("current", "_pn_tag", "_pn_frame")
+
+    def __init__(self, initial: Optional[T] = None) -> None:
+        self.current: Optional[T] = initial
+        # Internal: the native view tag, populated by the reconciler
+        # when the ref is attached to a built-in element.
+        self._pn_tag: Optional[int] = None
+        # Internal: the last committed frame ``(x, y, w, h)``, mirrored
+        # by the layout pass so Python code can read measured geometry
+        # without a native round-trip.
+        self._pn_frame: Optional[Tuple[float, float, float, float]] = None
+
+    def __repr__(self) -> str:
+        return f"Ref({self.current!r})"
 
-_batch_context: threading.local = threading.local()
 
 # ======================================================================
 # Hook state container
@@ -53,44 +123,69 @@ class HookState:
     Each `@component` instance owns one `HookState`. Hooks are matched
     to slots by call order, so they must always be called in the same
     order across renders. Effects scheduled during render are deferred
-    into `_pending_effects` and flushed after the reconciler commits
-    native mutations, which guarantees effect callbacks can safely
-    interact with the committed native tree.
+    (layout effects into ``_pending_layout_effects``, passive effects
+    into ``_pending_effects``) and flushed by the reconciler in two
+    phases after native mutations commit.
 
     Attributes:
         states: One entry per `use_state` / `use_reducer` call.
         effects: One `(deps, cleanup)` tuple per `use_effect` call.
+        layout_effects: One `(deps, cleanup)` tuple per
+            `use_layout_effect` call.
         memos: One `(deps, value)` tuple per `use_memo` / `use_callback`.
-        refs: One mutable dict per `use_ref` call.
+        refs: One [`Ref`][pythonnative.Ref] per `use_ref` call.
     """
 
     __slots__ = (
         "states",
         "effects",
+        "layout_effects",
         "memos",
         "refs",
+        "resources",
         "state_index",
         "effect_index",
+        "layout_effect_index",
         "memo_index",
         "ref_index",
+        "resource_index",
+        "context_deps",
         "_trigger_render",
         "_pending_effects",
+        "_pending_layout_effects",
+        "_pending_effects_mark",
+        "_pending_layout_effects_mark",
         "_dirty",
         "_vnode",
         "_reconciler",
+        "_hook_log",
+        "_hook_signature",
+        "_component_name",
+        "_async_driver",
     )
 
     def __init__(self) -> None:
         self.states: List[Any] = []
         self.effects: List[Tuple[Any, Any]] = []
+        self.layout_effects: List[Tuple[Any, Any]] = []
         self.memos: List[Tuple[Any, Any]] = []
-        self.refs: List[dict] = []
+        self.refs: List[Ref] = []
+        # One ``(deps, Resource)`` per ``use_resource`` call.
+        self.resources: List[Tuple[Any, Resource]] = []
         self.state_index: int = 0
         self.effect_index: int = 0
+        self.layout_effect_index: int = 0
         self.memo_index: int = 0
         self.ref_index: int = 0
+        self.resource_index: int = 0
+        # Contexts read during the last completed render, keyed by
+        # ``id(context)``. The reconciler consults this when a
+        # Provider's value changes so consumers re-render even when a
+        # memoized ancestor skipped (reactive context).
+        self.context_deps: Dict[int, Any] = {}
         self._trigger_render: Optional[Callable[[], None]] = None
         self._pending_effects: List[Tuple[int, Callable, Any]] = []
+        self._pending_layout_effects: List[Tuple[int, Callable, Any]] = []
         # Cleared by the reconciler after each successful render.
         # ``use_state`` / ``use_reducer`` setters flip it to ``True``
         # whenever they actually mutate state, so [`memo`][pythonnative.memo]
@@ -104,28 +199,140 @@ class HookState:
         # again when it unmounts.
         self._vnode: Any = None
         self._reconciler: Any = None
-
-    def reset_index(self) -> None:
-        """Reset every per-hook cursor to ``0``.
-
-        Called by the reconciler at the start of every render pass so
-        the next render reads slots in the same order they were
-        written.
+        # Dev-mode hook-order guard: the sequence of hook kinds called
+        # during the in-flight render, and the signature captured from
+        # the first successful render.
+        self._hook_log: Optional[List[str]] = None
+        self._hook_signature: Optional[List[str]] = None
+        self._component_name: str = ""
+        # For ``async def`` components: the CoroDriver running the
+        # in-flight body, cancelled when a newer render supersedes it.
+        self._async_driver: Optional[CoroDriver] = None
+        # Effect-queue lengths at ``begin_render``, so a suspended
+        # render can be rolled back without double-queueing effects.
+        self._pending_effects_mark: int = 0
+        self._pending_layout_effects_mark: int = 0
+
+    def begin_render(self, component_name: str = "") -> None:
+        """Prepare for a render pass: reset cursors and the dev-mode hook log.
+
+        Called by the reconciler before each invocation of the
+        component body so the next render reads slots in the same
+        order they were written.
         """
         self.state_index = 0
         self.effect_index = 0
+        self.layout_effect_index = 0
         self.memo_index = 0
         self.ref_index = 0
+        self.resource_index = 0
+        self.context_deps = {}
+        if component_name:
+            self._component_name = component_name
+        self._hook_log = [] if diagnostics.is_dev() else None
+        self._pending_effects_mark = len(self._pending_effects)
+        self._pending_layout_effects_mark = len(self._pending_layout_effects)
+
+    def abort_render(self) -> None:
+        """Roll back a suspended render's effect queue.
+
+        A suspended body re-runs from the top on retry, so any effects
+        it queued before suspending would otherwise be queued twice.
+        """
+        del self._pending_effects[self._pending_effects_mark :]
+        del self._pending_layout_effects[self._pending_layout_effects_mark :]
+        self._hook_log = None
+
+    def finish_render(self) -> None:
+        """Finalize a successful render: lock in / verify the hook signature.
+
+        Only called when the component body returned without raising,
+        so a failed render never corrupts the signature.
+
+        Raises:
+            HookOrderError: In dev mode, when this render called fewer
+                hooks than the previous one.
+        """
+        log = self._hook_log
+        self._hook_log = None
+        if log is None:
+            return
+        if self._hook_signature is None:
+            self._hook_signature = log
+            return
+        if len(log) < len(self._hook_signature):
+            missing = self._hook_signature[len(log)]
+            raise diagnostics.HookOrderError(
+                f"{self._component_name or 'Component'} rendered fewer hooks than the previous "
+                f"render (expected {missing!r} at position {len(log) + 1}). Hooks must be called "
+                "unconditionally, in the same order, on every render."
+            )
+
+    def record_hook(self, kind: str) -> None:
+        """Record a hook call for the dev-mode order guard.
+
+        Raises:
+            HookOrderError: In dev mode, when the hook at this position
+                differs from (or extends past) the previous render.
+        """
+        log = self._hook_log
+        if log is None:
+            return
+        position = len(log)
+        log.append(kind)
+        signature = self._hook_signature
+        if signature is None:
+            return
+        if position >= len(signature):
+            raise diagnostics.HookOrderError(
+                f"{self._component_name or 'Component'} rendered more hooks than the previous "
+                f"render ({kind!r} at position {position + 1}). Hooks must be called "
+                "unconditionally, in the same order, on every render."
+            )
+        if signature[position] != kind:
+            raise diagnostics.HookOrderError(
+                f"{self._component_name or 'Component'} called {kind!r} at position "
+                f"{position + 1}, but the previous render called {signature[position]!r} there. "
+                "Hooks must be called unconditionally, in the same order, on every render."
+            )
+
+    def reset_hook_signature(self) -> None:
+        """Forget the recorded hook signature (used by Fast Refresh).
+
+        After a hot reload swaps in a new component body, the old
+        signature no longer applies; the next render records a fresh
+        one.
+        """
+        self._hook_signature = None
+
+    def flush_layout_effects(self) -> None:
+        """Run layout effects queued during render (commit phase, pre-paint)."""
+        pending = self._pending_layout_effects
+        self._pending_layout_effects = []
+        self._pending_layout_effects_mark = 0
+        for idx, effect_fn, deps in pending:
+            _, prev_cleanup = self.layout_effects[idx]
+            if callable(prev_cleanup):
+                try:
+                    prev_cleanup()
+                except Exception:
+                    pass
+            cleanup = _activate_effect(effect_fn)
+            self.layout_effects[idx] = (list(deps) if deps is not None else None, cleanup)
 
     def flush_pending_effects(self) -> None:
-        """Run effects queued during render, after native commit.
+        """Run passive effects queued during render, after native commit.
 
         For each pending effect, the previous cleanup is invoked first
         (if any), then the new effect callback. The new return value
-        becomes the next cleanup.
+        becomes the next cleanup. Effects that are ``async def`` (or
+        that return an awaitable) run as tasks on the framework loop;
+        their cleanup cancels the task, and a callable returned by the
+        coroutine runs as an additional cleanup once it completed.
         """
         pending = self._pending_effects
         self._pending_effects = []
+        self._pending_effects_mark = 0
         for idx, effect_fn, deps in pending:
             _, prev_cleanup = self.effects[idx]
             if callable(prev_cleanup):
@@ -133,16 +340,25 @@ class HookState:
                     prev_cleanup()
                 except Exception:
                     pass
-            cleanup = effect_fn()
+            cleanup = _activate_effect(effect_fn)
             self.effects[idx] = (list(deps) if deps is not None else None, cleanup)
 
     def cleanup_all_effects(self) -> None:
         """Run every outstanding cleanup function, then clear state.
 
-        Called when the component instance is unmounted by the
-        reconciler.
+        Layout-effect cleanups run before passive-effect cleanups,
+        matching the mount order in reverse. Also cancels in-flight
+        resources and any pending ``async def`` body. Called when the
+        component instance is unmounted by the reconciler.
         """
-        for i, (deps, cleanup) in enumerate(self.effects):
+        for i, (_deps, cleanup) in enumerate(self.layout_effects):
+            if callable(cleanup):
+                try:
+                    cleanup()
+                except Exception:
+                    pass
+            self.layout_effects[i] = (_SENTINEL, None)
+        for i, (_deps, cleanup) in enumerate(self.effects):
             if callable(cleanup):
                 try:
                     cleanup()
@@ -150,21 +366,39 @@ class HookState:
                     pass
             self.effects[i] = (_SENTINEL, None)
         self._pending_effects = []
+        self._pending_layout_effects = []
+        self._pending_effects_mark = 0
+        self._pending_layout_effects_mark = 0
+        for _deps, resource in self.resources:
+            try:
+                resource.cancel()
+            except Exception:
+                pass
+        self.resources = []
+        driver = self._async_driver
+        self._async_driver = None
+        if driver is not None:
+            driver.cancel()
 
 
 # ======================================================================
-# Thread-local context helpers
+# Context helpers
 # ======================================================================
 
 
 def _get_hook_state() -> Optional[HookState]:
     """Return the active `HookState`, or `None` if no render is in flight."""
-    return getattr(_hook_context, "current", None)
+    return _hook_context.get()
 
 
-def _set_hook_state(state: Optional[HookState]) -> None:
-    """Install `state` as the active `HookState` for the current thread."""
-    _hook_context.current = state
+def _set_hook_state(state: Optional[HookState]) -> "Token[Optional[HookState]]":
+    """Install `state` as the active `HookState`; returns the reset token."""
+    return _hook_context.set(state)
+
+
+def _reset_hook_state(token: "Token[Optional[HookState]]") -> None:
+    """Restore the hook state that was active before `_set_hook_state`."""
+    _hook_context.reset(token)
 
 
 def _deps_changed(prev: Any, current: Any) -> bool:
@@ -178,19 +412,126 @@ def _deps_changed(prev: Any, current: Any) -> bool:
     return any(p is not c and p != c for p, c in zip(prev, current))
 
 
+def _activate_effect(effect_fn: Callable) -> Any:
+    """Invoke an effect callback, running coroutine effects as tasks.
+
+    Synchronous effects return their cleanup directly. When the effect
+    is an ``async def`` (or returns an awaitable), the coroutine runs
+    as a task on the framework loop and the returned cleanup cancels
+    it; if the coroutine already finished and returned a callable, that
+    callable runs as the cleanup instead.
+    """
+    result = effect_fn()
+    if not inspect.isawaitable(result):
+        return result
+
+    from .runtime import run_async
+
+    future = run_async(result)
+
+    def _observe(fut: Any) -> None:
+        # Surface unhandled async-effect crashes instead of letting the
+        # future's exception vanish unobserved: RedBox in dev mode,
+        # traceback in production.
+        if fut.cancelled():
+            return
+        exc = fut.exception()
+        if exc is None or isinstance(exc, asyncio.CancelledError):
+            return
+        if not diagnostics.report_error(exc, phase="async effect"):
+            import traceback
+
+            traceback.print_exception(type(exc), exc, exc.__traceback__)
+
+    future.add_done_callback(_observe)
+
+    def _cleanup() -> None:
+        if future.cancelled():
+            return
+        if future.done():
+            if future.exception() is None:
+                returned = future.result()
+                if callable(returned):
+                    try:
+                        returned()
+                    except Exception:
+                        pass
+            return
+        future.cancel()
+
+    return _cleanup
+
+
 # ======================================================================
-# Batching helpers
+# Batching and transition scheduling
 # ======================================================================
 
 
 def _schedule_trigger(trigger: Callable[[], None]) -> None:
     """Run ``trigger`` immediately, or defer it inside a `batch_updates` block."""
-    if getattr(_batch_context, "depth", 0) > 0:
-        _batch_context.pending_trigger = trigger
+    pending = _batch_pending.get()
+    if _batch_depth.get() > 0 and pending is not None:
+        if trigger not in pending:
+            pending.append(trigger)
     else:
         trigger()
 
 
+# Transition scheduling state. Deferred triggers (and the callbacks
+# that flip ``is_pending`` back off) run together on a later loop turn.
+_deferred_triggers: List[Callable[[], None]] = []
+_post_transition_callbacks: List[Callable[[], None]] = []
+_transition_flush_scheduled = False
+
+
+def _flush_transitions() -> None:
+    """Run every deferred transition render, then the completion callbacks."""
+    global _transition_flush_scheduled
+    _transition_flush_scheduled = False
+    triggers = list(_deferred_triggers)
+    _deferred_triggers.clear()
+    callbacks = list(_post_transition_callbacks)
+    _post_transition_callbacks.clear()
+    for trigger in triggers:
+        try:
+            trigger()
+        except Exception as exc:
+            if not diagnostics.report_error(exc, phase="transition"):
+                raise
+    for callback in callbacks:
+        try:
+            callback()
+        except Exception as exc:
+            if not diagnostics.report_error(exc, phase="transition"):
+                raise
+
+
+def _schedule_transition_flush() -> None:
+    """Ensure a transition flush is queued on the framework loop."""
+    global _transition_flush_scheduled
+    if _transition_flush_scheduled:
+        return
+    _transition_flush_scheduled = True
+    from .runtime import get_loop
+
+    get_loop().call_soon(_flush_transitions)
+
+
+def _defer_transition_trigger(trigger: Callable[[], None]) -> None:
+    if trigger not in _deferred_triggers:
+        _deferred_triggers.append(trigger)
+    _schedule_transition_flush()
+
+
+def _run_in_transition(fn: Callable[[], None]) -> None:
+    """Run ``fn`` with its state updates marked as transitions."""
+    token = _transition_var.set(True)
+    try:
+        fn()
+    finally:
+        _transition_var.reset(token)
+
+
 def _notify_state_changed(ctx: "HookState") -> None:
     """Mark ``ctx``'s component dirty and schedule a render after a state change.
 
@@ -199,7 +540,9 @@ def _notify_state_changed(ctx: "HookState") -> None:
     ``flush_dirty``, which re-renders only the components marked here
     rather than the whole app. The dirty mark is eager (so several
     setters coalesce), while the render trigger respects
-    [`batch_updates`][pythonnative.batch_updates].
+    [`batch_updates`][pythonnative.batch_updates] and defers to a later
+    loop turn inside a transition (see
+    [`use_transition`][pythonnative.use_transition]).
     """
     ctx._dirty = True
     reconciler = ctx._reconciler
@@ -207,7 +550,10 @@ def _notify_state_changed(ctx: "HookState") -> None:
     if reconciler is not None and vnode is not None:
         reconciler.mark_dirty(vnode)
     if ctx._trigger_render:
-        _schedule_trigger(ctx._trigger_render)
+        if _transition_var.get():
+            _defer_transition_trigger(ctx._trigger_render)
+        else:
+            _schedule_trigger(ctx._trigger_render)
 
 
 @contextmanager
@@ -231,18 +577,19 @@ def batch_updates() -> Generator[None, None, None]:
             set_name("hello")
         ```
     """
-    depth = getattr(_batch_context, "depth", 0)
-    _batch_context.depth = depth + 1
+    depth = _batch_depth.get()
+    depth_token = _batch_depth.set(depth + 1)
+    pending_token = None
     if depth == 0:
-        _batch_context.pending_trigger = None
+        pending_token = _batch_pending.set([])
     try:
         yield
     finally:
-        _batch_context.depth -= 1
-        if _batch_context.depth == 0:
-            trigger = _batch_context.pending_trigger
-            _batch_context.pending_trigger = None
-            if trigger is not None:
+        _batch_depth.reset(depth_token)
+        if pending_token is not None:
+            triggers = _batch_pending.get() or []
+            _batch_pending.reset(pending_token)
+            for trigger in triggers:
                 trigger()
 
 
@@ -278,13 +625,14 @@ def use_state(initial: Any = None) -> Tuple[Any, Callable]:
             count, set_count = pn.use_state(0)
             return pn.Button(
                 f"Count: {count}",
-                on_click=lambda: set_count(count + 1),
+                on_press=lambda: set_count(count + 1),
             )
         ```
     """
     ctx = _get_hook_state()
     if ctx is None:
         raise RuntimeError("use_state must be called inside a @component function")
+    ctx.record_hook("use_state")
 
     idx = ctx.state_index
     ctx.state_index += 1
@@ -343,14 +691,15 @@ def use_reducer(reducer: Callable[[Any, Any], Any], initial_state: Any) -> Tuple
         def Counter():
             count, dispatch = pn.use_reducer(reducer, 0)
             return pn.Row(
-                pn.Button("+", on_click=lambda: dispatch("increment")),
-                pn.Button("Reset", on_click=lambda: dispatch("reset")),
+                pn.Button("+", on_press=lambda: dispatch("increment")),
+                pn.Button("Reset", on_press=lambda: dispatch("reset")),
             )
         ```
     """
     ctx = _get_hook_state()
     if ctx is None:
         raise RuntimeError("use_reducer must be called inside a @component function")
+    ctx.record_hook("use_reducer")
 
     idx = ctx.state_index
     ctx.state_index += 1
@@ -384,12 +733,20 @@ def use_effect(effect: Callable, deps: Optional[list] = None) -> None:
     - `[]`: mount only.
     - `[a, b]`: when `a` or `b` change (compared by identity, then `==`).
 
-    `effect` may return a cleanup callable; the previous cleanup runs
-    before the next effect (and on unmount).
+    A synchronous `effect` may return a cleanup callable; the previous
+    cleanup runs before the next effect (and on unmount).
+
+    An **async** `effect` (an ``async def``) runs as a task on the
+    framework loop. When `deps` change or the component unmounts, the
+    in-flight task is cancelled (:class:`asyncio.CancelledError` is
+    raised at its current ``await``), giving async effects structured
+    cancellation for free. If the coroutine finishes and returns a
+    callable, that callable runs as the cleanup instead.
 
     Args:
-        effect: A zero-arg callable invoked after commit. Optionally
-            returns a cleanup callable.
+        effect: A zero-arg callable invoked after commit: either a
+            synchronous function (optionally returning a cleanup
+            callable) or an ``async def``.
         deps: Dependency list, or `None` to run on every render.
 
     Raises:
@@ -397,25 +754,27 @@ def use_effect(effect: Callable, deps: Optional[list] = None) -> None:
 
     Example:
         ```python
+        import asyncio
+
         import pythonnative as pn
 
         @pn.component
-        def Timer():
-            seconds, set_seconds = pn.use_state(0)
+        def Clock():
+            now, set_now = pn.use_state("")
 
-            def tick():
-                import threading
-                t = threading.Timer(1.0, lambda: set_seconds(seconds + 1))
-                t.start()
-                return t.cancel
+            async def tick():
+                while True:
+                    set_now(time.strftime("%H:%M:%S"))
+                    await asyncio.sleep(1)
 
-            pn.use_effect(tick, [seconds])
-            return pn.Text(f"Elapsed: {seconds}s")
+            pn.use_effect(tick, [])
+            return pn.Text(now)
         ```
     """
     ctx = _get_hook_state()
     if ctx is None:
         raise RuntimeError("use_effect must be called inside a @component function")
+    ctx.record_hook("use_effect")
 
     idx = ctx.effect_index
     ctx.effect_index += 1
@@ -430,6 +789,61 @@ def use_effect(effect: Callable, deps: Optional[list] = None) -> None:
         ctx._pending_effects.append((idx, effect, deps))
 
 
+def use_layout_effect(effect: Callable, deps: Optional[list] = None) -> None:
+    """Schedule a side effect that runs synchronously inside the commit.
+
+    Like [`use_effect`][pythonnative.use_effect], but the callback
+    fires *before* passive effects, immediately after native mutations
+    and the layout pass are applied. Use it when you need to measure a
+    committed frame (via a [`Ref`][pythonnative.Ref]) or issue an
+    imperative view command before the user sees the new frame, for
+    example scrolling a list into position on mount.
+
+    Prefer `use_effect` for everything else; layout effects block the
+    commit, so heavy work here delays the frame.
+
+    Args:
+        effect: A zero-arg callable invoked during commit. Optionally
+            returns a cleanup callable.
+        deps: Dependency list, or `None` to run on every render.
+
+    Raises:
+        RuntimeError: If called outside a `@component` function.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def AutoScrollList(items):
+            list_ref = pn.use_ref()
+
+            def scroll_to_bottom():
+                if list_ref.current is not None:
+                    list_ref.current.scroll_to_end(animated=False)
+
+            pn.use_layout_effect(scroll_to_bottom, [len(items)])
+            return pn.FlatList(items, render_item=Row, ref=list_ref)
+        ```
+    """
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_layout_effect must be called inside a @component function")
+    ctx.record_hook("use_layout_effect")
+
+    idx = ctx.layout_effect_index
+    ctx.layout_effect_index += 1
+
+    if idx >= len(ctx.layout_effects):
+        ctx.layout_effects.append((_SENTINEL, None))
+        ctx._pending_layout_effects.append((idx, effect, deps))
+        return
+
+    prev_deps, _prev_cleanup = ctx.layout_effects[idx]
+    if _deps_changed(prev_deps, deps):
+        ctx._pending_layout_effects.append((idx, effect, deps))
+
+
 def use_memo(factory: Callable[[], T], deps: list) -> T:
     """Return a memoized value that is recomputed only when `deps` change.
 
@@ -451,6 +865,7 @@ def use_memo(factory: Callable[[], T], deps: list) -> T:
     ctx = _get_hook_state()
     if ctx is None:
         raise RuntimeError("use_memo must be called inside a @component function")
+    ctx.record_hook("use_memo")
 
     idx = ctx.memo_index
     ctx.memo_index += 1
@@ -486,23 +901,26 @@ def use_callback(callback: Callable, deps: list) -> Callable:
     return use_memo(lambda: callback, deps)
 
 
-def use_ref(initial: Any = None) -> dict:
-    """Return a mutable ref dict ``{"current": initial}`` that persists across renders.
+def use_ref(initial: Optional[T] = None) -> Ref[T]:
+    """Return a [`Ref`][pythonnative.Ref] that persists across renders.
 
     Refs are useful for storing values that must survive renders without
     triggering them: timers, last-seen values, native handles, and so on.
 
-    The ``current`` key is also populated by the reconciler with the
+    ``ref.current`` is also populated by the reconciler with the
     underlying native view (`UIView` on iOS, `android.view.View` on
-    Android) when the ref is passed via the ``ref=`` prop on a built-in
-    element. This is how ``Animated.View`` obtains a handle to the
-    native view it animates without going through the reconciler.
+    Android, a Tk widget on desktop) when the ref is passed via the
+    ``ref=`` prop on a built-in element, and cleared to ``None`` when
+    that element unmounts. Composite components such as
+    [`FlatList`][pythonnative.FlatList] publish a typed controller
+    object instead (see
+    [`use_imperative_handle`][pythonnative.use_imperative_handle]).
 
     Args:
-        initial: Value placed at `ref["current"]` on first render.
+        initial: Value placed at ``ref.current`` on first render.
 
     Returns:
-        A dict with a single `"current"` key. Mutations to the dict do
+        A [`Ref`][pythonnative.Ref]. Mutations to ``ref.current`` do
         *not* trigger re-renders.
 
     Raises:
@@ -511,40 +929,153 @@ def use_ref(initial: Any = None) -> dict:
     ctx = _get_hook_state()
     if ctx is None:
         raise RuntimeError("use_ref must be called inside a @component function")
+    ctx.record_hook("use_ref")
 
     idx = ctx.ref_index
     ctx.ref_index += 1
 
     if idx >= len(ctx.refs):
-        ref: dict = {"current": initial}
+        ref: Ref[T] = Ref(initial)
         ctx.refs.append(ref)
         return ref
 
     return ctx.refs[idx]
 
 
+def use_imperative_handle(
+    ref: Optional[Ref],
+    factory: Callable[[], Any],
+    deps: Optional[list] = None,
+) -> None:
+    """Publish a controller object on ``ref.current``.
+
+    The composite-component counterpart to passing ``ref=`` to a
+    built-in element. Call it inside a component that accepts a
+    ``ref`` prop to expose a curated imperative API (rather than the
+    raw native view) to the parent. The handle is installed during the
+    commit's layout-effect phase and cleared back to ``None`` on
+    unmount.
+
+    Args:
+        ref: The [`Ref`][pythonnative.Ref] received via the component's
+            ``ref`` prop. ``None`` is allowed (the parent didn't
+            request a handle), in which case this is a no-op.
+        factory: Zero-arg callable returning the handle object.
+        deps: Dependency list controlling when the handle is rebuilt.
+            Defaults to ``[]`` semantics only if you pass ``[]``;
+            ``None`` rebuilds on every render, matching effects.
+
+    Raises:
+        RuntimeError: If called outside a `@component` function.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def VideoPlayer(source, ref=None):
+            pn.use_imperative_handle(ref, lambda: PlayerController(...), [source])
+            return pn.View(...)
+        ```
+    """
+
+    def _install() -> Optional[Callable[[], None]]:
+        if ref is None:
+            return None
+        ref.current = factory()
+
+        def _clear() -> None:
+            ref.current = None
+
+        return _clear
+
+    use_layout_effect(_install, deps)
+
+
 # ======================================================================
 # Async hooks
 # ======================================================================
 
 
-def use_async_effect(
-    effect: Callable[[], Awaitable[None]],
-    deps: Optional[list] = None,
-) -> None:
-    """Schedule an async effect that's cancelled on re-run / unmount.
+def use_resource(fetcher: Callable[[], Any], deps: Optional[list] = None) -> Resource[Any]:
+    """Start an async fetch and cache it across renders.
+
+    The fetch starts immediately (during render, not after commit) and
+    the resulting [`Resource`][pythonnative.Resource] is cached until
+    ``deps`` change, at which point the old fetch is cancelled and a
+    new one starts. Because results are cached, re-renders resolve
+    instantly; only genuinely new data suspends.
 
-    Like [`use_effect`][pythonnative.use_effect] but takes an
-    ``async def`` (or any zero-arg callable returning an awaitable).
-    The coroutine is scheduled on the framework runtime via
-    [`run_async`][pythonnative.runtime.run_async] after the native
-    commit. When ``deps`` change (or the component unmounts), the
-    in-flight future is cancelled.
+    Consume the resource with ``resource.read()`` (suspends the render
+    while pending; pair with a [`Suspense`][pythonnative.Suspense]
+    boundary) or ``await resource`` inside an ``async def`` component.
+    Errors raised by the fetcher re-raise at the read site, so an
+    enclosing [`ErrorBoundary`][pythonnative.ErrorBoundary] catches
+    failures declaratively.
 
     Args:
-        effect: A zero-arg callable returning an awaitable. Typically
-            an ``async def`` defined inside the component.
-        deps: Dependency list, or ``None`` to re-run on every render.
+        fetcher: Zero-arg ``async def`` (or plain callable) producing
+            the value. Synchronous fetchers resolve immediately and
+            never suspend.
+        deps: Dependency list controlling when to refetch. Defaults to
+            ``[]`` (fetch once per component instance).
+
+    Returns:
+        The cached [`Resource`][pythonnative.Resource].
+
+    Raises:
+        RuntimeError: If called outside a ``@component`` function.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+
+        @pn.component
+        async def UserCard(user_id):
+            user = await pn.use_resource(lambda: api.get_user(user_id), [user_id])
+            return pn.Text(user["name"])
+        ```
+    """
+    from .suspense import start_resource
+
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_resource must be called inside a @component function")
+    ctx.record_hook("use_resource")
+
+    idx = ctx.resource_index
+    ctx.resource_index += 1
+    deps = [] if deps is None else deps
+
+    if idx >= len(ctx.resources):
+        resource = start_resource(fetcher)
+        ctx.resources.append((list(deps), resource))
+        return resource
+
+    prev_deps, prev_resource = ctx.resources[idx]
+    if not _deps_changed(prev_deps, deps):
+        return prev_resource
+
+    prev_resource.cancel()
+    resource = start_resource(fetcher)
+    ctx.resources[idx] = (list(deps), resource)
+    return resource
+
+
+def use_transition() -> Tuple[bool, Callable[[Callable[[], None]], None]]:
+    """Return ``(is_pending, start_transition)`` for low-priority updates.
+
+    State updates made inside ``start_transition(fn)`` are marked as
+    *transitions*: instead of re-rendering synchronously, their render
+    is deferred to a later turn of the framework loop, so urgent
+    updates (typing, presses) queued in the meantime render first.
+    ``is_pending`` is ``True`` from the moment ``start_transition`` is
+    called until the deferred render has committed, which is exactly
+    when to show a lightweight busy indicator.
+
+    Returns:
+        A 2-tuple ``(is_pending, start_transition)``.
 
     Raises:
         RuntimeError: If called outside a ``@component`` function.
@@ -555,27 +1086,67 @@ def use_async_effect(
 
 
         @pn.component
-        def Posts(user_id):
-            posts, set_posts = pn.use_state([])
+        def Search():
+            query, set_query = pn.use_state("")
+            results_for, set_results_for = pn.use_state("")
+            is_pending, start_transition = pn.use_transition()
 
-            async def load():
-                set_posts(await api.get_posts(user_id))
+            def on_change(text):
+                set_query(text)  # urgent: keep the input responsive
+                start_transition(lambda: set_results_for(text))
 
-            pn.use_async_effect(load, [user_id])
-            return pn.FlatList(posts, render_item=...)
+            return pn.Column(
+                pn.TextInput(value=query, on_change=on_change),
+                pn.ActivityIndicator() if is_pending else Results(results_for),
+            )
         ```
     """
-    from .runtime import run_async
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_transition must be called inside a @component function")
 
-    def _sync_effect() -> Callable[[], None]:
-        future = run_async(effect())
+    is_pending, set_pending = use_state(False)
 
-        def _cancel() -> None:
-            future.cancel()
+    def start_transition(fn: Callable[[], None]) -> None:
+        set_pending(True)
+        _run_in_transition(fn)
+        _post_transition_callbacks.append(lambda: set_pending(False))
+        _schedule_transition_flush()
 
-        return _cancel
+    start = use_callback(start_transition, [])
+    return is_pending, start
+
+
+def use_deferred_value(value: Any) -> Any:
+    """Return a copy of ``value`` that lags behind during fast updates.
+
+    The returned value updates in a deferred (transition-priority)
+    render after the urgent render that changed ``value`` has
+    committed. Pass the deferred value to expensive subtrees (a
+    filtered list, a chart) so the urgent part of the UI stays
+    responsive while the expensive part catches up a beat later.
+
+    Args:
+        value: The latest value.
+
+    Returns:
+        The previous value while a newer one is still being adopted,
+        then the latest value.
+
+    Raises:
+        RuntimeError: If called outside a ``@component`` function.
+    """
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_deferred_value must be called inside a @component function")
+
+    deferred, set_deferred = use_state(value)
+
+    def _adopt() -> None:
+        _run_in_transition(lambda: set_deferred(value))
 
-    use_effect(_sync_effect, deps)
+    use_effect(_adopt, [value])
+    return deferred
 
 
 @dataclass(frozen=True)
@@ -704,7 +1275,7 @@ class MutationCall(Generic[T]):
     Example:
         ```python
         # Fire-and-forget:
-        save_button.on_click = lambda: mutate(post)
+        save_button.on_press = lambda: mutate(post)
 
         # Or await for the result:
         async def submit():
@@ -721,7 +1292,10 @@ class MutationCall(Generic[T]):
         self._future = future
 
     def __await__(self) -> Any:
-        return asyncio.wrap_future(self._future).__await__()
+        future = self._future
+        if isinstance(future, asyncio.Future):
+            return future.__await__()
+        return asyncio.wrap_future(future).__await__()
 
     def cancel(self) -> bool:
         """Cancel the underlying mutation. Returns whether cancellation succeeded."""
@@ -760,7 +1334,7 @@ def use_mutation(
             state, save = pn.use_mutation(api.create_post)
 
             return pn.Column(
-                pn.Button("Save", on_click=lambda: save(post)),
+                pn.Button("Save", on_press=lambda: save(post)),
                 pn.Text("Saving…") if state.loading else pn.Text(""),
                 pn.Text(str(state.error)) if state.error else pn.Text(""),
             )
@@ -952,6 +1526,10 @@ class Context:
     via [`use_context`][pythonnative.use_context]. Use
     [`Provider`][pythonnative.Provider] to set the value for a subtree.
 
+    Context is *reactive*: when a Provider's value changes, every
+    component that read the context on its last render re-renders,
+    even if a memoized ancestor skipped its own re-render.
+
     Attributes:
         default: The value returned when no `Provider` ancestor exists.
     """
@@ -989,6 +1567,9 @@ def use_context(context: Context) -> Any:
     """Read the current value of `context` from the nearest `Provider`.
 
     If no enclosing `Provider` exists, returns the context's default.
+    The component is registered as a subscriber: when the nearest
+    Provider's value changes, the component re-renders even if a
+    memoized ancestor skipped.
 
     Args:
         context: The `Context` to read from.
@@ -1002,7 +1583,10 @@ def use_context(context: Context) -> Any:
     ctx = _get_hook_state()
     if ctx is None:
         raise RuntimeError("use_context must be called inside a @component function")
-    return context._current()
+    ctx.record_hook("use_context")
+    value = context._current()
+    ctx.context_deps[id(context)] = value
+    return value
 
 
 # ======================================================================
@@ -1013,10 +1597,14 @@ def use_context(context: Context) -> Any:
 def Provider(context: "Context", value: Any, *children: Element) -> Element:
     """Provide ``value`` for ``context`` to all descendants of ``children``.
 
-    Accepts any number of children (varargs). Multiple children are
-    grouped under an internal [`Fragment`][pythonnative.Fragment] so
-    they all share the same provided value without an extra wrapping
-    native view.
+    Accepts any number of children (varargs). A Provider contributes no
+    native view of its own; its children mount directly into the
+    surrounding native parent.
+
+    When ``value`` differs from the previous render (identity, then
+    ``==``), every descendant that read the context via
+    [`use_context`][pythonnative.use_context] re-renders, including
+    descendants of memoized components that skipped.
 
     Args:
         context: The [`Context`][pythonnative.hooks.Context] to set.
@@ -1044,13 +1632,7 @@ def Provider(context: "Context", value: Any, *children: Element) -> Element:
             )
         ```
     """
-    if not children:
-        kids: List[Element] = []
-    elif len(children) == 1:
-        kids = [children[0]]
-    else:
-        kids = [Element("__Fragment__", {}, list(children))]
-    return Element("__Provider__", {"__context__": context, "__value__": value}, kids)
+    return Element("__Provider__", {"__context__": context, "__value__": value}, list(children))
 
 
 def memo(component_fn: Callable[..., Element]) -> Callable[..., Element]:
@@ -1123,7 +1705,7 @@ class NavigationHandle:
             nav = pn.use_navigation()
             return pn.Button(
                 "Open Detail",
-                on_click=lambda: nav.navigate("Detail", {"id": 42}),
+                on_press=lambda: nav.navigate("Detail", {"id": 42}),
             )
         ```
     """
@@ -1180,6 +1762,71 @@ def use_navigation() -> NavigationHandle:
     return handle
 
 
+def use_back_handler(handler: Callable[[], bool]) -> None:
+    """Intercept the system back action for this screen.
+
+    On Android this handles the hardware back button and predictive
+    back gesture; in the desktop preview it handles the Escape key.
+    iOS has no system back button, so the handler never fires there
+    (swipe-back is controlled by the navigation stack instead).
+
+    Handlers registered later run first, so a component mounted on top
+    of existing content (a modal, a confirmation sheet) takes priority
+    over handlers that were already mounted. Return ``True`` to consume
+    the event and stop both remaining handlers and the platform's
+    default behavior (popping the screen); return ``False`` to pass it
+    along.
+
+    The latest ``handler`` closure from the most recent render is
+    always the one invoked; registration order is fixed at mount, so
+    re-renders never change priority.
+
+    Args:
+        handler: Zero-arg callable returning ``True`` if it consumed
+            the back action.
+
+    Raises:
+        RuntimeError: If called outside a `@component` function.
+
+    Example:
+        ```python
+        import pythonnative as pn
+
+        @pn.component
+        def Editor():
+            dirty, set_dirty = pn.use_state(False)
+            pn.use_back_handler(lambda: dirty)  # block back while dirty
+            ...
+        ```
+    """
+    ctx = _get_hook_state()
+    if ctx is None:
+        raise RuntimeError("use_back_handler must be called inside a @component function")
+
+    latest: Ref[Callable[[], bool]] = use_ref(handler)
+    latest.current = handler
+
+    def _register() -> Optional[Callable[[], None]]:
+        reconciler = ctx._reconciler
+        if reconciler is None or not hasattr(reconciler, "register_back_handler"):
+            return None
+
+        def _trampoline() -> bool:
+            fn = latest.current
+            if fn is None:
+                return False
+            try:
+                return bool(fn())
+            except Exception as exc:
+                if not diagnostics.report_error(exc, phase="back handler"):
+                    raise
+                return True
+
+        return reconciler.register_back_handler(_trampoline)
+
+    use_effect(_register, [])
+
+
 # ======================================================================
 # @component decorator
 # ======================================================================