pythonnative 0.26.0__py3-none-any.whl → 0.27.0__py3-none-any.whl

pythonnative/gestures.py

@@ -1,4 +1,4 @@
-"""Native-backed gesture system.
+"""Native-backed gesture system with composition and arbitration.
 
 Attach gestures to any view-like element via the ``gestures=`` prop:
 
@@ -12,10 +12,6 @@ def Draggable():
     tx = pn.use_animated_value(0.0)
     ty = pn.use_animated_value(0.0)
 
-    def on_pan(event):
-        tx.set_value(event.translation_x)
-        ty.set_value(event.translation_y)
-
     def on_end(event):
         pn.Animated.spring(tx, to=0.0).start()
         pn.Animated.spring(ty, to=0.0).start()
@@ -23,7 +19,12 @@ def Draggable():
     return pn.Animated.View(
         pn.Text("Drag me"),
         style={"transform": [{"translate_x": tx}, {"translate_y": ty}], "padding": 24},
-        gestures=[gestures.Pan(on_change=on_pan, on_end=on_end)],
+        gestures=[
+            gestures.Pan(
+                on_change=pn.Animated.event(translation_x=tx, translation_y=ty),
+                on_end=on_end,
+            )
+        ],
     )
 ```
 
@@ -38,8 +39,32 @@ tag-based event channel. Recognition itself is native:
   [`GestureArbiter`][pythonnative.gestures.GestureArbiter] below.
 - **Desktop** feeds Tk pointer events into the same arbiter.
 
-All gestures attached to one view recognize *simultaneously*; there is
-no cross-gesture exclusivity arbitration yet.
+Composition
+-----------
+
+Gestures in a plain ``gestures=[...]`` list all recognize
+*simultaneously* (a press ripple plus a pan plus a pinch can all run at
+once). To control how gestures interact, wrap them in composition
+nodes, which nest arbitrarily:
+
+- [`Simultaneous`][pythonnative.gestures.Simultaneous]: members may all
+  activate together (the flat-list default, useful inside other nodes).
+- [`Race`][pythonnative.gestures.Race]: the first member to activate
+  wins; the rest fail for the remainder of the interaction.
+- [`Exclusive`][pythonnative.gestures.Exclusive]: priority order. A
+  member may only activate after every member listed *before* it has
+  failed. ``Exclusive(double_tap, single_tap)`` is the classic
+  double-tap-wins arrangement: the single tap fires only after the
+  double-tap window expires.
+
+```python
+gestures=[
+    gestures.Race(
+        gestures.Pan(on_change=drag),
+        gestures.LongPress(on_long_press=show_menu),
+    ),
+]
+```
 
 Every callback receives a [`GestureEvent`][pythonnative.gestures.GestureEvent]
 with position, translation, velocity, scale, and rotation populated as
@@ -49,8 +74,8 @@ appropriate for the gesture kind.
 from __future__ import annotations
 
 import math
-from dataclasses import dataclass
-from typing import Any, Callable, Dict, List, Literal, Optional, Sequence, Tuple
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Literal, Optional, Sequence, Set, Tuple
 
 __all__ = [
     "GestureState",
@@ -59,8 +84,13 @@ __all__ = [
     "LongPress",
     "Pan",
     "Swipe",
+    "Fling",
     "Pinch",
     "Rotation",
+    "Simultaneous",
+    "Race",
+    "Exclusive",
+    "GestureGroup",
     "GestureArbiter",
     "serialize_gestures",
 ]
@@ -88,7 +118,7 @@ class GestureEvent:
 
     Attributes:
         kind: Gesture kind (``"tap"``, ``"long_press"``, ``"pan"``,
-            ``"swipe"``, ``"pinch"``, ``"rotation"``).
+            ``"swipe"``, ``"fling"``, ``"pinch"``, ``"rotation"``).
         state: One of [`GestureState`][pythonnative.gestures.GestureState].
         x: Pointer x-position in the view's coordinate space (points).
         y: Pointer y-position in the view's coordinate space (points).
@@ -97,14 +127,14 @@ class GestureEvent:
         translation_y: Vertical displacement since the gesture
             activated (pan only).
         velocity_x: Horizontal pointer velocity in points/second
-            (pan and swipe).
+            (pan, swipe, and fling).
         velocity_y: Vertical pointer velocity in points/second
-            (pan and swipe).
+            (pan, swipe, and fling).
         scale: Pinch scale factor relative to activation (pinch only).
         rotation: Rotation in radians relative to activation
             (rotation only).
         pointer_count: Number of pointers currently down.
-        direction: Resolved swipe direction (swipe only).
+        direction: Resolved swipe/fling direction.
     """
 
     kind: str
@@ -291,6 +321,48 @@ class Swipe(_BaseGesture):
             super()._dispatch(event)
 
 
+@dataclass(frozen=True)
+class Fling(_BaseGesture):
+    """Recognize a quick multi-pointer directional flick.
+
+    Like [`Swipe`][pythonnative.gestures.Swipe] but with a pointer-count
+    requirement, mirroring React Native Gesture Handler's ``Fling``
+    (and iOS ``UISwipeGestureRecognizer`` with
+    ``numberOfTouchesRequired``). A two-finger downward fling is a
+    common dismiss gesture:
+
+    ```python
+    gestures.Fling(direction="down", n_pointers=2, on_fling=dismiss)
+    ```
+
+    Attributes:
+        on_fling: Called once on release with the resolved
+            ``direction`` and release velocity.
+        direction: Required direction, or ``"any"``.
+        n_pointers: Number of pointers that must participate.
+        min_velocity: Minimum release speed in points/second.
+    """
+
+    on_fling: Optional[GestureCallback] = None
+    direction: SwipeDirection = "any"
+    n_pointers: int = 1
+    min_velocity: float = 300.0
+    kind: str = "fling"
+
+    def _config(self) -> Dict[str, Any]:
+        return {
+            "direction": str(self.direction),
+            "n_pointers": int(self.n_pointers),
+            "min_velocity": float(self.min_velocity),
+        }
+
+    def _dispatch(self, event: GestureEvent) -> None:
+        if event.state == GestureState.ENDED and self.on_fling is not None:
+            self.on_fling(event)
+        else:
+            super()._dispatch(event)
+
+
 @dataclass(frozen=True)
 class Pinch(_BaseGesture):
     """Track a two-finger pinch; ``event.scale`` is relative to activation."""
@@ -309,34 +381,139 @@ GestureSpec = _BaseGesture
 """Any gesture descriptor accepted by the ``gestures=`` prop."""
 
 
+# ======================================================================
+# Composition nodes
+# ======================================================================
+
+
+@dataclass(frozen=True)
+class GestureGroup:
+    """A composition node relating child gestures (or nested groups).
+
+    Build instances with [`Simultaneous`][pythonnative.gestures.Simultaneous],
+    [`Race`][pythonnative.gestures.Race], or
+    [`Exclusive`][pythonnative.gestures.Exclusive] rather than directly.
+    """
+
+    mode: Literal["simultaneous", "race", "exclusive"]
+    children: Tuple[Any, ...] = field(default_factory=tuple)
+
+
+def Simultaneous(*gestures: Any) -> GestureGroup:
+    """Compose gestures that may all be active at the same time.
+
+    This matches the flat-list default; it exists so simultaneity can
+    be expressed *inside* [`Race`][pythonnative.gestures.Race] or
+    [`Exclusive`][pythonnative.gestures.Exclusive] nodes:
+
+    ```python
+    gestures.Race(
+        gestures.Simultaneous(gestures.Pinch(...), gestures.Rotation(...)),
+        gestures.Pan(...),
+    )
+    ```
+    """
+    return GestureGroup("simultaneous", tuple(gestures))
+
+
+def Race(*gestures: Any) -> GestureGroup:
+    """Compose gestures where only the first to activate wins.
+
+    As soon as one member activates, every other member fails for the
+    rest of the interaction (its in-progress recognition is abandoned
+    without firing callbacks).
+    """
+    return GestureGroup("race", tuple(gestures))
+
+
+def Exclusive(*gestures: Any) -> GestureGroup:
+    """Compose gestures by priority: earlier members outrank later ones.
+
+    A member may only activate once every member listed before it has
+    *failed*. ``Exclusive(double_tap, single_tap)`` delays the single
+    tap until the double-tap window has expired, then fires it; if the
+    second tap lands in time, only the double tap fires.
+    """
+    return GestureGroup("exclusive", tuple(gestures))
+
+
 def serialize_gestures(
     specs: Sequence[Any],
 ) -> Tuple[List[Dict[str, Any]], Dict[str, Callable[..., Any]]]:
-    """Split gesture descriptors into native config dicts and event routers.
+    """Flatten gesture descriptors into native config dicts and event routers.
+
+    Composition nodes ([`Simultaneous`][pythonnative.gestures.Simultaneous],
+    [`Race`][pythonnative.gestures.Race],
+    [`Exclusive`][pythonnative.gestures.Exclusive]) are flattened
+    depth-first; each resulting spec dict carries the relationship
+    metadata the recognizers need:
+
+    - ``"simultaneous"``: indices this gesture may be active alongside.
+    - ``"wait_for"``: indices that must *fail* before this gesture may
+      activate.
+
+    Two gestures that are not in each other's ``simultaneous`` sets
+    race: the first to activate causes the other to fail. Gestures in
+    the top-level list (outside any composition node) are mutually
+    simultaneous.
 
     Args:
         specs: The value of an element's ``gestures`` prop. Plain dicts
-            are passed through untouched (no callbacks to route).
+            are passed through with relationship metadata attached (no
+            callbacks to route).
 
     Returns:
         ``(clean_specs, events)`` where ``clean_specs`` is a list of
-        JSON-ish config dicts (one per gesture, in order) and
+        JSON-ish config dicts (one per leaf gesture, depth-first) and
         ``events`` maps ``"gesture:<i>"`` to a router that unpacks the
         native payload into a `GestureEvent` and invokes the right
         user callback.
     """
+    leaves: List[Any] = []
+    sim_pairs: Set[Tuple[int, int]] = set()
+    wait_pairs: Set[Tuple[int, int]] = set()  # (waiter, target)
+
+    def _flatten(node: Any) -> List[int]:
+        if isinstance(node, GestureGroup):
+            subtree_leaves: List[List[int]] = [_flatten(child) for child in node.children]
+            for a_i in range(len(subtree_leaves)):
+                for b_i in range(a_i + 1, len(subtree_leaves)):
+                    for a in subtree_leaves[a_i]:
+                        for b in subtree_leaves[b_i]:
+                            if node.mode == "simultaneous":
+                                sim_pairs.add((a, b))
+                            elif node.mode == "exclusive":
+                                # Later members wait for earlier ones.
+                                wait_pairs.add((b, a))
+            return [i for group in subtree_leaves for i in group]
+        leaves.append(node)
+        return [len(leaves) - 1]
+
+    top_level: List[List[int]] = [_flatten(node) for node in specs]
+    # Top-level entries are mutually simultaneous (flat-list default).
+    for a_i in range(len(top_level)):
+        for b_i in range(a_i + 1, len(top_level)):
+            for a in top_level[a_i]:
+                for b in top_level[b_i]:
+                    sim_pairs.add((a, b))
+
     clean: List[Dict[str, Any]] = []
     events: Dict[str, Callable[..., Any]] = {}
-    for i, spec in enumerate(specs):
-        if isinstance(spec, _BaseGesture):
-            clean.append(spec._to_spec())
+    for i, leaf in enumerate(leaves):
+        if isinstance(leaf, _BaseGesture):
+            spec = leaf._to_spec()
 
-            def _router(payload: Dict[str, Any], _spec: _BaseGesture = spec) -> None:
+            def _router(payload: Dict[str, Any], _spec: _BaseGesture = leaf) -> None:
                 _spec._dispatch(event_from_payload(payload))
 
             events[f"gesture:{i}"] = _router
-        elif isinstance(spec, dict):
-            clean.append(dict(spec))
+        elif isinstance(leaf, dict):
+            spec = dict(leaf)
+        else:
+            spec = {"kind": ""}
+        spec["simultaneous"] = sorted({b for a, b in sim_pairs if a == i} | {a for a, b in sim_pairs if b == i})
+        spec["wait_for"] = sorted({t for w, t in wait_pairs if w == i})
+        clean.append(spec)
     return clean, events
 
 
@@ -353,6 +530,10 @@ def serialize_gestures(
 EmitFn = Callable[[int, Dict[str, Any]], None]
 """``emit(gesture_index, payload)``: the arbiter's output channel."""
 
+# Internal (never user-visible) state used by recognizers to tell the
+# arbiter they can no longer succeed for this interaction.
+_FAILED = "__failed"
+
 
 class _VelocityTracker:
     """Estimate pointer velocity from recent samples (points/second)."""
@@ -397,6 +578,14 @@ class _Recognizer:
         payload.update(fields)
         self._emit_fn(self.index, payload)
 
+    def fail(self) -> None:
+        """Report that this gesture can no longer succeed this interaction."""
+        self._emit_fn(self.index, {"kind": self.kind(), "state": _FAILED})
+
+    def force_fail(self, t: float) -> None:
+        """Abandon recognition without emitting anything (lost a race)."""
+        self.cancel(t)
+
     def kind(self) -> str:
         return str(self.config.get("kind", ""))
 
@@ -440,17 +629,22 @@ class _TapRecognizer(_Recognizer):
         self._tap_count = 0
         self._last_tap_time = 0.0
         self._failed = False
+        # Deadline for the *next* tap of a multi-tap (or None).
+        self._gap_deadline: Optional[float] = None
 
     _MAX_TAP_DURATION_S = 0.4
     _MULTI_TAP_GAP_S = 0.3
 
     def down(self, pointers: Dict[int, Tuple[float, float]], t: float) -> None:
         if len(pointers) != 1:
-            self._failed = True
+            if not self._failed:
+                self._failed = True
+                self.fail()
             return
         if self._tap_count > 0 and t - self._last_tap_time > self._MULTI_TAP_GAP_S:
             self._tap_count = 0
         self._failed = False
+        self._gap_deadline = None
         self._down_pos = _centroid(pointers)
         self._down_time = t
 
@@ -460,6 +654,7 @@ class _TapRecognizer(_Recognizer):
         x, y = _centroid(pointers)
         if math.hypot(x - self._down_pos[0], y - self._down_pos[1]) > self._slop:
             self._failed = True
+            self.fail()
 
     def up(self, pointers: Dict[int, Tuple[float, float]], t: float, x: float, y: float) -> None:
         if self._failed or self._down_pos is None:
@@ -467,21 +662,36 @@ class _TapRecognizer(_Recognizer):
             return
         if t - self._down_time > self._MAX_TAP_DURATION_S:
             self._reset()
+            self.fail()
             return
         self._tap_count += 1
         self._last_tap_time = t
         if self._tap_count >= self._n_taps:
             self.emit(GestureState.ENDED, x=x, y=y)
             self._reset()
+        else:
+            # Waiting for the next tap; fail if it never arrives so
+            # gestures waiting on this one (Exclusive) can proceed.
+            self._gap_deadline = t + self._MULTI_TAP_GAP_S
         self._down_pos = None
 
     def cancel(self, t: float) -> None:
         self._reset()
 
+    def deadline(self) -> Optional[float]:
+        return self._gap_deadline
+
+    def poll(self, t: float) -> None:
+        if self._gap_deadline is not None and t >= self._gap_deadline:
+            self._gap_deadline = None
+            self._tap_count = 0
+            self.fail()
+
     def _reset(self) -> None:
         self._down_pos = None
         self._tap_count = 0 if self._tap_count >= self._n_taps else self._tap_count
         self._failed = False
+        self._gap_deadline = None
 
 
 class _LongPressRecognizer(_Recognizer):
@@ -506,10 +716,13 @@ class _LongPressRecognizer(_Recognizer):
             if self._active:
                 self.emit(GestureState.CANCELLED, x=x, y=y)
             self._reset()
+            self.fail()
 
     def up(self, pointers: Dict[int, Tuple[float, float]], t: float, x: float, y: float) -> None:
         if self._active:
             self.emit(GestureState.ENDED, x=x, y=y)
+        elif self._down_pos is not None:
+            self.fail()
         self._reset()
 
     def cancel(self, t: float) -> None:
@@ -604,6 +817,8 @@ class _PanRecognizer(_Recognizer):
             )
             self._reset()
         elif not pointers:
+            if not self._active and self._origin is not None:
+                self.fail()
             self._reset()
         elif self._active:
             self._rebase(pointers)
@@ -631,22 +846,30 @@ class _PanRecognizer(_Recognizer):
 
 
 class _SwipeRecognizer(_Recognizer):
+    """Directional flick recognizer; also serves ``fling`` (adds pointer count)."""
+
     def __init__(self, index: int, config: Dict[str, Any], emit: EmitFn) -> None:
         super().__init__(index, config, emit)
         self._direction = str(config.get("direction", "any"))
         self._min_velocity = float(config.get("min_velocity", 300.0))
+        self._n_pointers = max(1, int(config.get("n_pointers", 1)))
         self._velocity = _VelocityTracker()
         self._tracking = False
+        self._max_pointers = 0
 
     def down(self, pointers: Dict[int, Tuple[float, float]], t: float) -> None:
-        self._velocity.reset()
+        if not self._tracking:
+            self._velocity.reset()
+            self._tracking = True
+            self._max_pointers = 0
+        self._max_pointers = max(self._max_pointers, len(pointers))
         x, y = _centroid(pointers)
         self._velocity.add(x, y, t)
-        self._tracking = True
 
     def move(self, pointers: Dict[int, Tuple[float, float]], t: float) -> None:
         if not self._tracking:
             return
+        self._max_pointers = max(self._max_pointers, len(pointers))
         x, y = _centroid(pointers)
         self._velocity.add(x, y, t)
 
@@ -657,13 +880,15 @@ class _SwipeRecognizer(_Recognizer):
         self._velocity.add(x, y, t)
         vx, vy = self._velocity.velocity()
         speed = math.hypot(vx, vy)
-        if speed < self._min_velocity:
+        if speed < self._min_velocity or self._max_pointers < self._n_pointers:
+            self.fail()
             return
         if abs(vx) >= abs(vy):
             direction = "right" if vx > 0 else "left"
         else:
             direction = "down" if vy > 0 else "up"
         if self._direction not in ("any", direction):
+            self.fail()
             return
         self.emit(
             GestureState.ENDED,
@@ -672,10 +897,12 @@ class _SwipeRecognizer(_Recognizer):
             velocity_x=vx,
             velocity_y=vy,
             direction=direction,
+            pointer_count=self._max_pointers,
         )
 
     def cancel(self, t: float) -> None:
         self._tracking = False
+        self._max_pointers = 0
         self._velocity.reset()
 
 
@@ -720,6 +947,8 @@ class _PinchRecognizer(_Recognizer):
         if self._active and len(pointers) < 2:
             self.emit(GestureState.ENDED, x=x, y=y, scale=self._scale, pointer_count=len(pointers))
             self._reset()
+        elif not self._active and not pointers:
+            self.fail()
 
     def cancel(self, t: float) -> None:
         if self._active:
@@ -778,6 +1007,8 @@ class _RotationRecognizer(_Recognizer):
         if self._active and len(pointers) < 2:
             self.emit(GestureState.ENDED, x=x, y=y, rotation=self._rotation, pointer_count=len(pointers))
             self._reset()
+        elif not self._active and not pointers:
+            self.fail()
 
     def cancel(self, t: float) -> None:
         if self._active:
@@ -795,13 +1026,21 @@ _RECOGNIZERS: Dict[str, Any] = {
     "long_press": _LongPressRecognizer,
     "pan": _PanRecognizer,
     "swipe": _SwipeRecognizer,
+    "fling": _SwipeRecognizer,
     "pinch": _PinchRecognizer,
     "rotation": _RotationRecognizer,
 }
 
+# Arbitration states for one recognizer within one interaction.
+_POSSIBLE = "possible"
+_WAITING = "waiting"  # activation buffered, awaiting wait_for targets
+_ACTIVE = "active"
+_DONE = "done"
+_ST_FAILED = "failed"
+
 
 class GestureArbiter:
-    """Turn a raw pointer-event stream into gesture event payloads.
+    """Turn a raw pointer-event stream into arbitrated gesture payloads.
 
     One arbiter serves one view. The host backend feeds it normalized
     pointer events (positions in the view's coordinate space, times in
@@ -809,28 +1048,70 @@ class GestureArbiter:
     that forwards ``(gesture_index, payload)`` pairs to
     [`dispatch_event`][pythonnative.events.dispatch_event].
 
-    Long-press needs a timer: after each pointer event, hosts should
-    check [`next_deadline`][pythonnative.gestures.GestureArbiter.next_deadline]
+    Beyond running each gesture's state machine, the arbiter enforces
+    the relationships computed by
+    [`serialize_gestures`][pythonnative.gestures.serialize_gestures]:
+
+    - Two gestures not in each other's ``"simultaneous"`` sets race;
+      when one activates, the other is force-failed for the rest of
+      the interaction.
+    - A gesture with a ``"wait_for"`` set may only activate after all
+      of those gestures have failed. Its output (including a buffered
+      discrete completion, like a single tap waiting out a double-tap
+      window) is held and either flushed on failure of the targets or
+      discarded if a target succeeds.
+
+    Specs without relationship metadata (hand-built dicts) default to
+    fully simultaneous, matching pre-composition behavior.
+
+    Timing: after each pointer event, hosts should check
+    [`next_deadline`][pythonnative.gestures.GestureArbiter.next_deadline]
     and schedule a [`poll`][pythonnative.gestures.GestureArbiter.poll]
-    call for that time.
+    call for that time (long-press activation and multi-tap windows).
     """
 
+    _DISCRETE_KINDS = frozenset({"tap", "swipe", "fling"})
+
     def __init__(self, specs: Sequence[Dict[str, Any]], emit: EmitFn) -> None:
+        self._emit_out = emit
         self._pointers: Dict[int, Tuple[float, float]] = {}
         self._recognizers: List[_Recognizer] = []
+        self._indices: List[int] = []
+        self._sim: Dict[int, Optional[Set[int]]] = {}
+        self._wait_for: Dict[int, Set[int]] = {}
+        self._states: Dict[int, str] = {}
+        self._buffers: Dict[int, List[Dict[str, Any]]] = {}
+        self._last_t = 0.0
         for i, spec in enumerate(specs):
             recognizer_cls = _RECOGNIZERS.get(str(spec.get("kind", "")))
-            if recognizer_cls is not None:
-                self._recognizers.append(recognizer_cls(i, spec, emit))
+            if recognizer_cls is None:
+                continue
+            self._recognizers.append(recognizer_cls(i, spec, self._mediate))
+            self._indices.append(i)
+            sim = spec.get("simultaneous")
+            # None means "simultaneous with everything" (back-compat
+            # for hand-built spec dicts without metadata).
+            self._sim[i] = None if sim is None else set(int(s) for s in sim)
+            self._wait_for[i] = set(int(w) for w in spec.get("wait_for", ()) or ())
+            self._states[i] = _POSSIBLE
+
+    # -- pointer input ---------------------------------------------------
 
     def pointer_down(self, pointer_id: int, x: float, y: float, t: float) -> None:
         """Record a pointer press and advance every recognizer."""
+        self._last_t = t
+        if not self._pointers and not any(s == _WAITING for s in self._states.values()):
+            # Fresh interaction: clear per-interaction verdicts.
+            for i in self._indices:
+                self._states[i] = _POSSIBLE
+            self._buffers.clear()
         self._pointers[pointer_id] = (x, y)
         for recognizer in self._recognizers:
             recognizer.down(self._pointers, t)
 
     def pointer_move(self, pointer_id: int, x: float, y: float, t: float) -> None:
         """Record pointer travel and advance every recognizer."""
+        self._last_t = t
         if pointer_id not in self._pointers:
             return
         self._pointers[pointer_id] = (x, y)
@@ -839,18 +1120,25 @@ class GestureArbiter:
 
     def pointer_up(self, pointer_id: int, x: float, y: float, t: float) -> None:
         """Record a pointer release and advance every recognizer."""
+        self._last_t = t
         self._pointers.pop(pointer_id, None)
         for recognizer in self._recognizers:
             recognizer.up(self._pointers, t, x, y)
 
     def cancel(self, t: float) -> None:
         """Abort every in-flight gesture (e.g. touch stolen by a scroll parent)."""
+        self._last_t = t
         self._pointers.clear()
+        self._buffers.clear()
+        for i in self._indices:
+            if self._states[i] == _WAITING:
+                self._states[i] = _ST_FAILED
         for recognizer in self._recognizers:
             recognizer.cancel(t)
 
     def poll(self, t: float) -> None:
-        """Advance time-based recognizers (long-press activation)."""
+        """Advance time-based recognizers (long-press, multi-tap windows)."""
+        self._last_t = t
         for recognizer in self._recognizers:
             recognizer.poll(t)
 
@@ -868,6 +1156,130 @@ class GestureArbiter:
         """
         return any(isinstance(r, _PanRecognizer) and r.active for r in self._recognizers)
 
+    # -- arbitration -------------------------------------------------------
+
+    def _recognizer_for(self, index: int) -> Optional[_Recognizer]:
+        for r in self._recognizers:
+            if r.index == index:
+                return r
+        return None
+
+    def _is_simultaneous(self, a: int, b: int) -> bool:
+        sim_a = self._sim.get(a)
+        sim_b = self._sim.get(b)
+        if sim_a is None or sim_b is None:
+            return True
+        return b in sim_a and a in sim_b
+
+    def _mediate(self, index: int, payload: Dict[str, Any]) -> None:
+        state = payload.get("state")
+        current = self._states.get(index, _POSSIBLE)
+
+        if state == _FAILED:
+            if current in (_POSSIBLE, _WAITING):
+                self._set_failed(index, discard_buffer=True)
+            return
+
+        if current == _ST_FAILED:
+            return
+
+        if current == _ACTIVE:
+            self._emit_out(index, payload)
+            if state == GestureState.ENDED:
+                self._states[index] = _DONE
+                self._on_resolved(index, succeeded=True)
+            elif state == GestureState.CANCELLED:
+                self._states[index] = _ST_FAILED
+                self._on_resolved(index, succeeded=False)
+            return
+
+        if current == _WAITING:
+            # Recognition continues while the activation is parked;
+            # keep buffering so a flush replays the full stream.
+            self._buffers.setdefault(index, []).append(payload)
+            return
+
+        # current == _POSSIBLE: this payload is an activation attempt
+        # (BEGAN, or a discrete completion such as a tap's ENDED).
+        self._request_activation(index, payload)
+
+    def _request_activation(self, index: int, payload: Dict[str, Any]) -> None:
+        # Race check: blocked by any non-simultaneous gesture that has
+        # already activated (or completed) this interaction.
+        for j in self._indices:
+            if j == index:
+                continue
+            if self._states[j] in (_ACTIVE, _DONE) and not self._is_simultaneous(index, j):
+                self._set_failed(index, discard_buffer=True)
+                return
+
+        targets = [t for t in self._wait_for.get(index, ()) if t in self._states]
+        if any(self._states[t] in (_ACTIVE, _DONE) for t in targets):
+            self._set_failed(index, discard_buffer=True)
+            return
+        if any(self._states[t] in (_POSSIBLE, _WAITING) for t in targets):
+            self._states[index] = _WAITING
+            self._buffers.setdefault(index, []).append(payload)
+            return
+
+        self._activate(index, [payload])
+
+    def _activate(self, index: int, payloads: List[Dict[str, Any]]) -> None:
+        discrete_done = bool(payloads) and payloads[-1].get("state") in (
+            GestureState.ENDED,
+            GestureState.CANCELLED,
+        )
+        self._states[index] = _DONE if discrete_done else _ACTIVE
+        # Winning a race force-fails every unresolved non-simultaneous
+        # competitor before any output, so their recognizers stand down
+        # (no stray callbacks later in the interaction).
+        for j in self._indices:
+            if j == index:
+                continue
+            if self._states[j] in (_POSSIBLE, _WAITING) and not self._is_simultaneous(index, j):
+                recognizer = self._recognizer_for(j)
+                if recognizer is not None:
+                    recognizer.force_fail(self._last_t)
+                self._set_failed(j, discard_buffer=True)
+        for payload in payloads:
+            self._emit_out(index, payload)
+        if self._states[index] == _DONE:
+            self._on_resolved(index, succeeded=True)
+
+    def _set_failed(self, index: int, discard_buffer: bool) -> None:
+        if self._states.get(index) == _ST_FAILED:
+            return
+        self._states[index] = _ST_FAILED
+        if discard_buffer:
+            self._buffers.pop(index, None)
+        self._on_resolved(index, succeeded=False)
+
+    def _on_resolved(self, index: int, succeeded: bool) -> None:
+        """Re-evaluate gestures waiting on ``index`` after it resolves."""
+        for waiter in self._indices:
+            if self._states.get(waiter) != _WAITING:
+                continue
+            if index not in self._wait_for.get(waiter, ()):
+                continue
+            if succeeded:
+                recognizer = self._recognizer_for(waiter)
+                if recognizer is not None:
+                    recognizer.force_fail(self._last_t)
+                self._set_failed(waiter, discard_buffer=True)
+                continue
+            targets = [t for t in self._wait_for.get(waiter, ()) if t in self._states]
+            if any(self._states[t] in (_POSSIBLE, _WAITING) for t in targets):
+                continue  # still waiting on someone else
+            if any(self._states[t] in (_ACTIVE, _DONE) for t in targets):
+                recognizer = self._recognizer_for(waiter)
+                if recognizer is not None:
+                    recognizer.force_fail(self._last_t)
+                self._set_failed(waiter, discard_buffer=True)
+                continue
+            payloads = self._buffers.pop(waiter, [])
+            self._states[waiter] = _POSSIBLE
+            self._activate(waiter, payloads)
+
 
 # Re-exported via ``pythonnative.gestures`` for handler-side construction.
 def make_arbiter(specs: Sequence[Dict[str, Any]], emit: EmitFn) -> GestureArbiter: