pythonnative 0.36.0__py3-none-any.whl → 0.38.0__py3-none-any.whl

pythonnative/cli/pn.py

@@ -6,6 +6,9 @@ The console script `pn` (declared in `pyproject.toml`) dispatches to:
   ``app/``) into ``./name/``, or into the current directory when no name
   is given.
 - `pn doctor [platform]`: diagnose the local toolchain and config.
+- `pn deps [platform]`: resolve ``[requirements].packages`` for every
+  device target and report which wheels would be used (or why a package
+  can't be installed), without building anything.
 - `pn preview [component]`: render the app in a desktop (Tkinter) window
   with Fast Refresh, the fast inner dev loop, no device required.
 - `pn devices [platform]`: list connected devices, emulators, and
@@ -41,6 +44,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, TextIO
 
 from ..project import builder as builder_mod
+from ..project import deps as deps_mod
 from ..project import devices as devices_mod
 from ..project import doctor as doctor_mod
 from ..project.android import collect_logcat_filters
@@ -54,22 +58,29 @@ HOT_RELOAD_DEV_ROOT = "pythonnative_dev"
 # init
 # ======================================================================
 
-_MAIN_TEMPLATE = """import pythonnative as pn
+_MAIN_TEMPLATE = """from typing import TypedDict
+
+import pythonnative as pn
 
 Stack = pn.create_stack_navigator()
 
 
+class DetailParams(TypedDict):
+    count: int
+
+
 @pn.component
 def HomeScreen():
     count, set_count = pn.use_state(0)
     nav = pn.use_navigation()
+    theme = pn.use_theme()
     return pn.ScrollView(
         pn.Column(
-            pn.Text("Hello from PythonNative!", style={"font_size": 24, "bold": True}),
+            pn.Text("Hello from PythonNative!", style={"font_size": theme.font_size_title, "bold": True}),
             pn.Text(f"Tapped {count} times"),
             pn.Button("Tap me", on_press=lambda: set_count(count + 1)),
-            pn.Button("Open detail", on_press=lambda: nav.navigate("Detail", {"count": count})),
-            style={"spacing": 12, "padding": 16, "align_items": "stretch"},
+            pn.Button("Open detail", on_press=lambda: nav.navigate("Detail", count=count)),
+            style={"spacing": theme.spacing_large, "padding": 16, "align_items": "stretch"},
         )
     )
 
@@ -77,9 +88,9 @@ def HomeScreen():
 @pn.component
 def DetailScreen():
     nav = pn.use_navigation()
-    params = pn.use_route()
+    route = pn.use_route(DetailParams)
     return pn.Column(
-        pn.Text(f"Detail: count was {params.get('count', 0)}", style={"font_size": 20}),
+        pn.Text(f"Detail: count was {route.params['count']}", style={"font_size": 20}),
         pn.Button("Back", on_press=nav.go_back),
         style={"spacing": 12, "padding": 16},
     )
@@ -89,8 +100,8 @@ def DetailScreen():
 def App():
     return pn.NavigationContainer(
         Stack.Navigator(
-            Stack.Screen("Home", component=HomeScreen, options={"title": "Home"}),
-            Stack.Screen("Detail", component=DetailScreen, options={"title": "Detail"}),
+            Stack.Screen("Home", HomeScreen, title="Home"),
+            Stack.Screen("Detail", DetailScreen, title="Detail"),
         )
     )
 """
@@ -278,6 +289,56 @@ def app_id_command(args: argparse.Namespace) -> None:
     print(config.application_id if args.platform == "android" else config.bundle_id)
 
 
+# ======================================================================
+# deps
+# ======================================================================
+
+
+def deps_command(args: argparse.Namespace) -> None:
+    """Report how ``[requirements].packages`` resolve for each device target.
+
+    Runs pip in its cross-platform dry-run mode once per target (iOS
+    device, iOS Simulator, and one per Android ABI) and prints the
+    wheel each package would use, flagging binary wheels and their
+    source index. Exits non-zero when any target can't be satisfied,
+    so it doubles as a CI gate. ``--json`` emits the same data as a
+    machine-readable document.
+
+    Args:
+        args: Parsed namespace with optional ``platform``, ``json``, and
+            ``python`` (the interpreter to run pip with).
+    """
+    platform: Optional[str] = getattr(args, "platform", None)
+    as_json: bool = getattr(args, "json", False)
+    python: Optional[str] = getattr(args, "python", None)
+
+    config = _load_config_or_exit()
+    targets = deps_mod.targets_for(config, platform)
+    runner = builder_mod.SubprocessRunner()
+    if not as_json and config.requirements:
+        print(
+            f"Resolving {len(config.requirements)} requirement(s) for Python {config.python_version} "
+            f"across {len(targets)} target(s)...\n"
+        )
+    resolutions = deps_mod.resolve_all(config, targets, runner=runner, python=python)
+
+    if as_json:
+        print(
+            json.dumps(
+                {
+                    "python_version": config.python_version,
+                    "requirements": list(config.requirements),
+                    "targets": [res.to_dict() for res in resolutions],
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(deps_mod.format_report(resolutions, requirements=config.requirements))
+    if any(not res.ok for res in resolutions):
+        sys.exit(1)
+
+
 # ======================================================================
 # preview
 # ======================================================================
@@ -426,8 +487,18 @@ def run_project(args: argparse.Namespace) -> None:
     config = _load_config_or_exit()
     builder = builder_mod.Builder(config, log=print)
 
+    # Resolve third-party packages only for the destination being built
+    # (device wheels and Simulator wheels differ); prepare-only keeps both
+    # slices so the staged project builds for either in Xcode.
+    if prepare_only:
+        ios_sdks: tuple = deps_mod.IOS_SDKS
+    elif device is not None and device.kind == "device":
+        ios_sdks = ("iphoneos",)
+    else:
+        ios_sdks = ("iphonesimulator",)
+
     try:
-        prepared = builder.prepare(platform)
+        prepared = builder.prepare(platform, ios_sdks=ios_sdks)
     except builder_mod.BuildError as exc:
         print(f"Error: {exc}")
         sys.exit(1)
@@ -593,7 +664,11 @@ def build_project(args: argparse.Namespace) -> None:
         sys.exit(1)
 
     try:
-        prepared = builder.prepare(platform, release=not debug)
+        prepared = builder.prepare(
+            platform,
+            release=not debug,
+            ios_sdks=("iphonesimulator",) if debug else ("iphoneos",),
+        )
         if platform == "android":
             artifacts = builder.build_android(prepared, debug=debug)
         else:
@@ -1020,6 +1095,17 @@ def _build_parser() -> argparse.ArgumentParser:
     parser_doctor.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict checks to a platform")
     parser_doctor.set_defaults(func=doctor_command)
 
+    parser_deps = subparsers.add_parser(
+        "deps", help="Check which wheels [requirements].packages resolve to on each device target"
+    )
+    parser_deps.add_argument("platform", nargs="?", choices=["android", "ios"], help="Restrict to a platform")
+    parser_deps.add_argument("--json", action="store_true", help="Print a JSON report for scripting")
+    parser_deps.add_argument(
+        "--python",
+        help="Interpreter to run pip with (default: the one running pn; any version works, pip cross-resolves)",
+    )
+    parser_deps.set_defaults(func=deps_command)
+
     parser_preview = subparsers.add_parser("preview", help="Render the app in a desktop window")
     parser_preview.add_argument(
         "component",

pythonnative/components/_base.py

@@ -76,6 +76,37 @@ def _make_element(
     return Element(name, out, list(children), key=key)
 
 
+# ======================================================================
+# RefreshControl attachment
+# ======================================================================
+
+REFRESH_CONTROL_TYPE = "RefreshControl"
+"""Element type produced by [`RefreshControl`][pythonnative.RefreshControl]."""
+
+
+def _refresh_control_props(control: Optional[Element], *, owner: str) -> Optional[Dict[str, Any]]:
+    """Turn a ``RefreshControl`` element into the ``refresh_control`` wire prop.
+
+    Scroll containers hold their refresh control as a prop rather than
+    a child (the native side attaches a ``UIRefreshControl`` /
+    ``SwipeRefreshLayout`` to the scroll view itself), so the element
+    is unwrapped here into the flat dict the bridge and the event
+    extractor expect. Keeping it an element on the Python side means
+    users build it like every other piece of UI and get a clear error
+    if they pass the wrong thing.
+
+    Raises:
+        TypeError: If ``control`` is not a ``RefreshControl`` element.
+    """
+    if control is None:
+        return None
+    if not isinstance(control, Element) or control.type != REFRESH_CONTROL_TYPE:
+        raise TypeError(
+            f"{owner}(refresh_control=...) expects pn.RefreshControl(...), got {type(control).__name__}: {control!r}"
+        )
+    return dict(control.props)
+
+
 # ======================================================================
 # Rich text spans
 # ======================================================================

pythonnative/components/controls.py

@@ -2,7 +2,7 @@
 
 ``Switch``, ``Slider``, ``ProgressBar``, ``ActivityIndicator``,
 ``Checkbox``, ``SegmentedControl``, ``DatePicker``, ``Picker``, the
-``RefreshControl`` spec helper, and ``StatusBar``.
+``RefreshControl``, and ``StatusBar``.
 """
 
 from typing import Any, Callable, Dict, List, Literal, Optional
@@ -10,7 +10,7 @@ from typing import Any, Callable, Dict, List, Literal, Optional
 from ..element import Element
 from ..hooks import Ref
 from ..style import AccessibilityState, Color, StyleProp
-from ._base import _make_element
+from ._base import REFRESH_CONTROL_TYPE, _make_element
 
 
 def Switch(
@@ -426,13 +426,17 @@ def RefreshControl(
     refreshing: bool = False,
     on_refresh: Optional[Callable[[], Any]] = None,
     tint_color: Optional[Color] = None,
-) -> Dict[str, Any]:
-    """Pull-to-refresh spec for [`ScrollView`][pythonnative.ScrollView] / [`FlatList`][pythonnative.FlatList].
+) -> Element:
+    """Pull-to-refresh control for [`ScrollView`][pythonnative.ScrollView] and the list components.
 
-    Returns a plain dict that should be passed as the
-    ``refresh_control=`` prop. Modeled as a dict (not an
-    [`Element`][pythonnative.Element]) so the host scroll container can
-    hold one without it appearing as a child node.
+    Pass the result as the ``refresh_control=`` prop of a
+    [`ScrollView`][pythonnative.ScrollView],
+    [`FlatList`][pythonnative.FlatList], or
+    [`SectionList`][pythonnative.SectionList]. It is a regular
+    [`Element`][pythonnative.Element] (type ``"RefreshControl"``) built
+    like every other piece of UI; the scroll container attaches it to
+    its native scroll view rather than rendering it as a child, and
+    rejects anything else with a ``TypeError``.
 
     Args:
         refreshing: Drive the spinner's visibility from a use_state
@@ -443,8 +447,7 @@ def RefreshControl(
         tint_color: Color of the spinner.
 
     Returns:
-        Dict suitable for the ``refresh_control`` prop on a scroll
-        container.
+        An [`Element`][pythonnative.Element] of type ``"RefreshControl"``.
 
     Example:
         ```python
@@ -467,12 +470,12 @@ def RefreshControl(
             )
         ```
     """
-    spec: Dict[str, Any] = {"refreshing": bool(refreshing)}
-    if on_refresh is not None:
-        spec["on_refresh"] = on_refresh
-    if tint_color is not None:
-        spec["tint_color"] = tint_color
-    return spec
+    return _make_element(
+        REFRESH_CONTROL_TYPE,
+        refreshing=bool(refreshing),
+        on_refresh=on_refresh,
+        tint_color=tint_color,
+    )
 
 
 def StatusBar(

pythonnative/components/layout.py

@@ -12,7 +12,7 @@ from ..component import component
 from ..element import Element
 from ..hooks import Ref, use_keyboard_height, use_safe_area_insets, use_state
 from ..style import AccessibilityState, StyleProp, resolve_style
-from ._base import _make_element
+from ._base import _make_element, _refresh_control_props
 
 
 def View(
@@ -113,7 +113,16 @@ def View(
 def Column(
     *children: Element,
     style: StyleProp = None,
+    gestures: Optional[List[Any]] = None,
+    hit_slop: Optional[Union[float, Dict[str, float]]] = None,
     on_layout: Optional[Callable[[Dict[str, float]], None]] = None,
+    accessibility_label: Optional[str] = None,
+    accessibility_hint: Optional[str] = None,
+    accessibility_role: Optional[str] = None,
+    accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -123,12 +132,25 @@ def Column(
     ``flex_direction`` locked to ``"column"``. Use ``View`` directly if
     you need to switch between row and column at runtime.
 
+    Accepts every [`View`][pythonnative.View] prop (gestures, hit slop,
+    accessibility, ``test_id``); only ``flex_direction`` is fixed.
+
     Args:
         *children: Child elements stacked top to bottom.
         style: Style dict (or list of dicts).
+        gestures: Gesture descriptors recognized natively on this view.
+        hit_slop: Extra touch target beyond the bounds (see ``View``).
         on_layout: Callback invoked with
             ``{"x", "y", "width", "height"}`` after layout and on
             frame changes.
+        accessibility_label: Spoken description for screen readers.
+        accessibility_hint: Spoken extra detail (iOS only).
+        accessibility_role: Semantic role for assistive tech.
+        accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech.
+        accessibility_live_region: How AT announces dynamic changes
+            (Android only).
+        test_id: Stable identifier for UI tests.
         ref: Optional [`Ref`][pythonnative.Ref] for native-view access.
         key: Stable identity for keyed reconciliation.
 
@@ -139,9 +161,18 @@ def Column(
         "Column",
         *children,
         style=style,
-        on_layout=on_layout,
         ref=ref,
         key=key,
+        gestures=gestures,
+        hit_slop=hit_slop,
+        on_layout=on_layout,
+        accessibility_label=accessibility_label,
+        accessibility_hint=accessibility_hint,
+        accessibility_role=accessibility_role,
+        accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _forced={"flex_direction": "column"},
     )
 
@@ -149,7 +180,16 @@ def Column(
 def Row(
     *children: Element,
     style: StyleProp = None,
+    gestures: Optional[List[Any]] = None,
+    hit_slop: Optional[Union[float, Dict[str, float]]] = None,
     on_layout: Optional[Callable[[Dict[str, float]], None]] = None,
+    accessibility_label: Optional[str] = None,
+    accessibility_hint: Optional[str] = None,
+    accessibility_role: Optional[str] = None,
+    accessible: Optional[bool] = None,
+    accessibility_state: Optional[AccessibilityState] = None,
+    accessibility_live_region: Optional[Literal["none", "polite", "assertive"]] = None,
+    test_id: Optional[str] = None,
     ref: Optional[Ref] = None,
     key: Optional[str] = None,
 ) -> Element:
@@ -159,12 +199,25 @@ def Row(
     ``flex_direction`` locked to ``"row"``. Use ``View`` directly if you
     need to switch between row and column at runtime.
 
+    Accepts every [`View`][pythonnative.View] prop (gestures, hit slop,
+    accessibility, ``test_id``); only ``flex_direction`` is fixed.
+
     Args:
         *children: Child elements arranged left to right.
         style: Style dict (or list of dicts).
+        gestures: Gesture descriptors recognized natively on this view.
+        hit_slop: Extra touch target beyond the bounds (see ``View``).
         on_layout: Callback invoked with
             ``{"x", "y", "width", "height"}`` after layout and on
             frame changes.
+        accessibility_label: Spoken description for screen readers.
+        accessibility_hint: Spoken extra detail (iOS only).
+        accessibility_role: Semantic role for assistive tech.
+        accessible: Override whether the element is exposed to AT.
+        accessibility_state: Current widget state for assistive tech.
+        accessibility_live_region: How AT announces dynamic changes
+            (Android only).
+        test_id: Stable identifier for UI tests.
         ref: Optional [`Ref`][pythonnative.Ref] for native-view access.
         key: Stable identity for keyed reconciliation.
 
@@ -175,9 +228,18 @@ def Row(
         "Row",
         *children,
         style=style,
-        on_layout=on_layout,
         ref=ref,
         key=key,
+        gestures=gestures,
+        hit_slop=hit_slop,
+        on_layout=on_layout,
+        accessibility_label=accessibility_label,
+        accessibility_hint=accessibility_hint,
+        accessibility_role=accessibility_role,
+        accessible=accessible,
+        accessibility_state=accessibility_state,
+        accessibility_live_region=accessibility_live_region,
+        test_id=test_id,
         _forced={"flex_direction": "row"},
     )
 
@@ -219,7 +281,7 @@ def Spacer(
 
 def ScrollView(
     *children: Element,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     scroll_axis: Optional[Literal["vertical", "horizontal"]] = None,
     on_scroll: Optional[Callable[[Dict[str, float]], None]] = None,
     shows_scroll_indicator: bool = True,
@@ -240,11 +302,8 @@ def ScrollView(
 
     Args:
         *children: Child elements to scroll.
-        refresh_control: Optional pull-to-refresh spec, typically
-            constructed via
-            [`RefreshControl`][pythonnative.RefreshControl]. The dict
-            must have ``refreshing`` (bool) and ``on_refresh``
-            (callable).
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]
+            element attached to the scroll view for pull-to-refresh.
         scroll_axis: ``"vertical"`` (default) or ``"horizontal"``.
         on_scroll: Callback invoked with ``{"x": …, "y": …}`` content
             offsets as the user scrolls.
@@ -271,7 +330,7 @@ def ScrollView(
         style=style,
         ref=ref,
         key=key,
-        refresh_control=refresh_control,
+        refresh_control=_refresh_control_props(refresh_control, owner="ScrollView"),
         scroll_axis=scroll_axis,
         on_scroll=on_scroll,
         shows_scroll_indicator=False if shows_scroll_indicator is False else None,
@@ -326,7 +385,7 @@ def _SafeAreaContainer(
     for edge in _SAFE_AREA_EDGES:
         if edge not in selected:
             continue
-        inset = float(insets.get(edge, 0.0) or 0.0)
+        inset = float(getattr(insets, edge, 0.0) or 0.0)
         if inset > 0:
             resolved[f"padding_{edge}"] = _numeric_edge_padding(resolved, edge) + inset
     return Element("SafeAreaView", resolved, list(children))

pythonnative/components/lists.py

@@ -124,7 +124,7 @@ def _VirtualizedList(
     header: Optional[Element] = None,
     footer: Optional[Element] = None,
     empty: Optional[Element] = None,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     on_end_reached: Optional[Callable[[], Any]] = None,
     on_end_reached_threshold: Optional[float] = None,
     on_viewable_items_changed: Optional[Callable[[List[Dict[str, Any]]], None]] = None,
@@ -464,7 +464,7 @@ def FlatList(
     get_item_height: Optional[Callable[[Any, int], float]] = None,
     estimated_item_height: Optional[float] = None,
     separator_height: float = 0,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     horizontal: bool = False,
     num_columns: int = 1,
     list_header: Optional[Element] = None,
@@ -509,8 +509,8 @@ def FlatList(
         estimated_item_height: Starting extent estimate for rows whose
             true size isn't known yet (default 44).
         separator_height: Gap below each row, in points.
-        refresh_control: Optional pull-to-refresh spec from
-            [`RefreshControl`][pythonnative.RefreshControl].
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl]
+            element for pull-to-refresh.
         horizontal: Scroll horizontally (extents become widths).
         num_columns: Render items in a grid of this many columns.
         list_header: Element rendered once before all rows.
@@ -666,7 +666,7 @@ def SectionList(
     estimated_item_height: Optional[float] = None,
     section_header_height: Optional[float] = None,
     separator_height: float = 0,
-    refresh_control: Optional[Dict[str, Any]] = None,
+    refresh_control: Optional[Element] = None,
     list_header: Optional[Element] = None,
     list_footer: Optional[Element] = None,
     list_empty: Optional[Element] = None,
@@ -699,7 +699,7 @@ def SectionList(
         estimated_item_height: Starting estimate for unmeasured rows.
         section_header_height: Header extent in points, when known.
         separator_height: Gap below each item, in points.
-        refresh_control: Optional pull-to-refresh spec.
+        refresh_control: Optional [`RefreshControl`][pythonnative.RefreshControl] element.
         list_header: Element rendered once before everything.
         list_footer: Element rendered once after everything.
         list_empty: Element rendered when there are no sections.

pythonnative/gestures.py

@@ -34,10 +34,13 @@ configuration into plain dicts for the native handler (so prop diffing
 never compares closures) and routes the callbacks through the
 tag-based event channel. Recognition itself is native:
 
-- **iOS** attaches real ``UIGestureRecognizer`` instances.
-- **Android** feeds raw ``MotionEvent`` streams into the pure-Python
-  [`GestureArbiter`][pythonnative.gestures.GestureArbiter] below.
-- **Desktop** feeds Tk pointer events into the same arbiter.
+- **iOS** attaches real ``UIGestureRecognizer`` instances
+  (``PythonNativeKit``).
+- **Android** runs an equivalent recognizer set in Kotlin (the
+  ``pythonnative`` Gradle module) on top of ``MotionEvent`` streams.
+- **Desktop** feeds Tk pointer events into the pure-Python
+  [`GestureArbiter`][pythonnative.gestures.GestureArbiter] below, which
+  doubles as the executable specification for the native ports.
 
 Composition
 -----------
@@ -75,6 +78,7 @@ from __future__ import annotations
 
 import math
 from dataclasses import dataclass, field
+from enum import Enum
 from typing import Any, Callable, Dict, List, Literal, Optional, Sequence, Set, Tuple
 
 __all__ = [
@@ -96,16 +100,30 @@ __all__ = [
 ]
 
 
-class GestureState:
-    """States reported on [`GestureEvent.state`][pythonnative.gestures.GestureEvent]."""
+class GestureState(str, Enum):
+    """Lifecycle states reported on [`GestureEvent.state`][pythonnative.gestures.GestureEvent].
+
+    A ``str`` enum, so members compare equal to their wire value
+    (``GestureState.ENDED == "ended"``) and serialize as plain strings
+    across the native bridge, while callers get exhaustive
+    ``match`` support and autocomplete.
+
+    Attributes:
+        BEGAN: The gesture activated (first callback).
+        CHANGED: A continuous gesture updated (pan, pinch, rotation).
+        ENDED: The gesture completed successfully.
+        CANCELLED: The gesture was interrupted (lost arbitration, view
+            unmounted, pointer left the window).
+    """
 
     BEGAN = "began"
     CHANGED = "changed"
     ENDED = "ended"
     CANCELLED = "cancelled"
 
+    def __str__(self) -> str:
+        return self.value
 
-GestureStateName = Literal["began", "changed", "ended", "cancelled"]
 
 GestureCallback = Callable[["GestureEvent"], Any]
 
@@ -138,7 +156,7 @@ class GestureEvent:
     """
 
     kind: str
-    state: GestureStateName
+    state: GestureState
     x: float = 0.0
     y: float = 0.0
     translation_x: float = 0.0
@@ -150,6 +168,12 @@ class GestureEvent:
     pointer_count: int = 1
     direction: Optional[str] = None
 
+    def __post_init__(self) -> None:
+        # Payloads from the native bridge carry plain strings; coerce
+        # so ``event.state`` is always a ``GestureState`` member.
+        if not isinstance(self.state, GestureState):
+            object.__setattr__(self, "state", GestureState(self.state))
+
 
 _EVENT_FIELDS = frozenset(
     {
@@ -518,14 +542,14 @@ def serialize_gestures(
 
 
 # ======================================================================
-# Pure-Python recognition engine (Android + desktop backends)
+# Pure-Python recognition engine (desktop backend + reference semantics)
 # ======================================================================
 #
-# iOS uses real UIGestureRecognizers. Android and the desktop preview
-# receive raw pointer streams instead, which this arbiter turns into
-# the same GestureEvent payloads. Keeping it in pure Python makes the
-# state machines unit-testable with scripted event sequences and
-# guarantees identical semantics on both backends.
+# iOS and Android recognize natively. The desktop preview receives raw
+# Tk pointer streams instead, which this arbiter turns into the same
+# GestureEvent payloads. Keeping it in pure Python makes the state
+# machines unit-testable with scripted event sequences; the Kotlin
+# arbiter mirrors this file so the two stay in lockstep.
 
 EmitFn = Callable[[int, Dict[str, Any]], None]
 """``emit(gesture_index, payload)``: the arbiter's output channel."""
@@ -573,8 +597,8 @@ class _Recognizer:
         self.config = config
         self._emit_fn = emit
 
-    def emit(self, state: str, **fields: Any) -> None:
-        payload: Dict[str, Any] = {"kind": self.kind(), "state": state}
+    def emit(self, state: GestureState, **fields: Any) -> None:
+        payload: Dict[str, Any] = {"kind": self.kind(), "state": state.value}
         payload.update(fields)
         self._emit_fn(self.index, payload)