pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native_views/__init__.py

@@ -0,0 +1,375 @@
+"""The view backend the reconciler commits to.
+
+The reconciler talks to exactly one object, obtained from
+[`get_registry`][pythonnative.native_views.get_registry], through a
+small protocol: ``apply_mutations`` (one ordered batch of
+create/update/insert/destroy/frame ops per commit, see
+`pythonnative.mutations`), ``resolve_view``, ``measure_intrinsic``,
+``command``, and the animation hooks. Two implementations exist:
+
+- [`BridgeBackend`][pythonnative.native_views.bridge_backend.BridgeBackend]
+  (iOS, Android, and the browser preview): serializes each commit and
+  hands it to the native runtime through the bridge; the Swift and
+  Kotlin component managers, or the preview page's DOM applier, own
+  every platform view. Python holds no native objects.
+- [`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry]
+  (tests and SDK handler introspection): maps element type names to
+  Python [`ViewHandler`][pythonnative.native_views.base.ViewHandler]
+  implementations and owns the tag table itself.
+
+Platform selection happens lazily on first use, so this package
+imports on any platform. Tests install a mock with
+[`set_registry`][pythonnative.native_views.set_registry].
+"""
+
+import math
+import sys
+import threading
+import time
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+from ..mutations import CreateOp, DestroyOp, InsertOp, Mutation, SetFrameOp, UpdateOp
+from .base import ViewHandler
+
+# ======================================================================
+# Tripwire log rate limiter
+# ======================================================================
+#
+# Defensive NaN/Inf guards in ``set_frame`` and ``_apply_transform`` log
+# a single line per occurrence. That's fine for one-off events, but
+# ``Animated.View`` drives transforms at ~60 Hz; once an
+# ``Animated.Value`` enters a stuck NaN state (e.g., a spring tick
+# corrupted across a Fast Refresh), the tripwire would otherwise emit
+# thousands of identical lines per second and drown the dev console.
+#
+# We instead log the first occurrence immediately, then suppress
+# further messages with the same ``label`` for
+# ``_TRIPWIRE_RATE_LIMIT_S`` seconds, and append a
+# ``(+N similar in last Xs)`` suffix to the next message that escapes
+# the window. The first sample plus a count is enough to diagnose; the
+# bounded log keeps the dev console usable.
+
+_TRIPWIRE_RATE_LIMIT_S: float = 1.0
+_TRIPWIRE_LOG_LOCK = threading.Lock()
+_TRIPWIRE_LAST_LOG_TIME: Dict[str, float] = {}
+_TRIPWIRE_SUPPRESSED_COUNT: Dict[str, int] = {}
+
+
+def _tripwire_log(label: str, message: str) -> None:
+    """Emit ``message`` to stderr, rate-limited per ``label``.
+
+    The first call for a given ``label`` always emits. Calls within
+    ``_TRIPWIRE_RATE_LIMIT_S`` seconds are silently counted. The next
+    call after the window appends ``(+N similar in last Xs)`` and
+    resets the counter.
+    """
+    now = time.monotonic()
+    write = False
+    suppressed = 0
+    with _TRIPWIRE_LOG_LOCK:
+        last = _TRIPWIRE_LAST_LOG_TIME.get(label)
+        if last is None or now - last >= _TRIPWIRE_RATE_LIMIT_S:
+            write = True
+            suppressed = _TRIPWIRE_SUPPRESSED_COUNT.get(label, 0)
+            _TRIPWIRE_SUPPRESSED_COUNT[label] = 0
+            _TRIPWIRE_LAST_LOG_TIME[label] = now
+        else:
+            _TRIPWIRE_SUPPRESSED_COUNT[label] = _TRIPWIRE_SUPPRESSED_COUNT.get(label, 0) + 1
+    if not write:
+        return
+    if suppressed > 0:
+        message = f"{message} (+{suppressed} similar in last {_TRIPWIRE_RATE_LIMIT_S:g}s)"
+    try:
+        print(message, file=sys.stderr, flush=True)
+    except Exception:
+        pass
+
+
+class ViewRecord:
+    """One live native view tracked by the tag table."""
+
+    __slots__ = ("tag", "type_name", "view", "handler")
+
+    def __init__(self, tag: int, type_name: str, view: Any, handler: ViewHandler) -> None:
+        self.tag = tag
+        self.type_name = type_name
+        self.view = view
+        self.handler = handler
+
+
+class NativeViewRegistry:
+    """Map element type names to handlers and tags to live native views.
+
+    The reconciler depends only on this protocol: ``apply_mutations``,
+    ``resolve_view``, ``measure_intrinsic``, and ``command``.
+    Implementations may host real platform handlers (Android/iOS/
+    browser) or mocks for tests.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: Dict[str, ViewHandler] = {}
+        self._records: Dict[int, ViewRecord] = {}
+
+    def register(self, type_name: str, handler: ViewHandler) -> None:
+        """Register `handler` to service elements of type `type_name`.
+
+        Args:
+            type_name: The element type name (e.g., `"Text"`).
+            handler: A `ViewHandler` instance for the active platform.
+        """
+        self._handlers[type_name] = handler
+
+    def handler_for(self, type_name: str) -> Optional[ViewHandler]:
+        """Return the handler registered for ``type_name``, if any."""
+        return self._handlers.get(type_name)
+
+    # ------------------------------------------------------------------
+    # Tag table
+    # ------------------------------------------------------------------
+
+    def resolve_view(self, tag: int) -> Any:
+        """Return the native view registered under ``tag``, or ``None``."""
+        record = self._records.get(tag)
+        return record.view if record is not None else None
+
+    def record_for(self, tag: int) -> Optional[ViewRecord]:
+        """Return the full [`ViewRecord`][pythonnative.native_views.ViewRecord] for ``tag``."""
+        return self._records.get(tag)
+
+    def live_view_count(self) -> int:
+        """Number of views currently tracked (test/diagnostic helper)."""
+        return len(self._records)
+
+    # ------------------------------------------------------------------
+    # The commit channel
+    # ------------------------------------------------------------------
+
+    def apply_mutations(self, ops: Sequence[Mutation]) -> None:
+        """Apply one commit transaction.
+
+        Ops are applied strictly in order. Failures are isolated per
+        op: a handler exception is logged (rate-limited) and the
+        remaining ops still apply, so one bad prop can't desync the
+        whole native tree.
+
+        Args:
+            ops: Ordered mutations emitted by the reconciler.
+        """
+        for op in ops:
+            try:
+                self._apply_one(op)
+            except Exception as exc:
+                _tripwire_log(
+                    f"apply:{type(op).__name__}",
+                    f"[PN] apply_mutations: {type(op).__name__} failed: {type(exc).__name__}: {exc!r}",
+                )
+
+    def _apply_one(self, op: Mutation) -> None:
+        if isinstance(op, CreateOp):
+            handler = self._handlers.get(op.type_name)
+            if handler is None:
+                raise ValueError(f"Unknown element type: {op.type_name!r}")
+            view = handler.create(op.tag, op.props)
+            self._records[op.tag] = ViewRecord(op.tag, op.type_name, view, handler)
+            return
+        if isinstance(op, UpdateOp):
+            record = self._records.get(op.tag)
+            if record is not None:
+                record.handler.update(record.view, op.changed_props)
+            return
+        if isinstance(op, InsertOp):
+            parent = self._records.get(op.parent_tag)
+            child = self._records.get(op.child_tag)
+            if parent is not None and child is not None:
+                parent.handler.insert_child(parent.view, child.view, op.index)
+            return
+        if isinstance(op, DestroyOp):
+            record = self._records.pop(op.tag, None)
+            if record is not None:
+                record.handler.destroy(record.view)
+            return
+        if isinstance(op, SetFrameOp):
+            self._apply_frame(op)
+            return
+        raise TypeError(f"Unknown mutation op: {op!r}")
+
+    def _apply_frame(self, op: SetFrameOp) -> None:
+        record = self._records.get(op.tag)
+        if record is None:
+            return
+        # Tripwire: log non-finite layout values so we can diagnose
+        # crashes like iOS `CALayerInvalidGeometry` without losing the
+        # repro. Handlers are responsible for clamping before applying.
+        # Rate-limited via ``_tripwire_log`` to avoid floods when an
+        # animated value is stuck at NaN.
+        try:
+            finite = (
+                math.isfinite(op.x) and math.isfinite(op.y) and math.isfinite(op.width) and math.isfinite(op.height)
+            )
+        except (TypeError, ValueError):
+            finite = False
+        if not finite:
+            _tripwire_log(
+                "set_frame:nan",
+                f"[set_frame:nan] type={record.type_name!r} x={op.x!r} y={op.y!r} w={op.width!r} h={op.height!r}",
+            )
+        record.handler.set_frame(record.view, op.x, op.y, op.width, op.height)
+
+    # ------------------------------------------------------------------
+    # Imperative escape hatches (resolved through the tag table)
+    # ------------------------------------------------------------------
+
+    def measure_intrinsic(
+        self,
+        tag: int,
+        max_width: float,
+        max_height: float,
+    ) -> Tuple[float, float]:
+        """Return the natural ``(width, height)`` of a content-sized view.
+
+        Used by the layout engine for leaves whose intrinsic size
+        depends on their content (text, buttons, images).
+        """
+        record = self._records.get(tag)
+        if record is None:
+            return (0.0, 0.0)
+        return record.handler.measure_intrinsic(record.view, max_width, max_height)
+
+    def command(self, tag: int, name: str, args: Optional[Dict[str, Any]] = None) -> Any:
+        """Execute an imperative command against the view for ``tag``.
+
+        Args:
+            tag: Target view tag.
+            name: Command name (handler-specific, e.g.
+                ``"scroll_to_offset"``).
+            args: Optional command arguments.
+
+        Returns:
+            The handler's command result, or ``None`` when the tag is
+            unknown.
+        """
+        record = self._records.get(tag)
+        if record is None:
+            return None
+        return record.handler.command(record.view, name, args or {})
+
+    def set_animated_property(self, tag: int, prop_name: str, value: Any) -> None:
+        """Apply one Python-driven animation frame to the view for ``tag``."""
+        record = self._records.get(tag)
+        if record is not None:
+            record.handler.set_animated_property(record.view, prop_name, value)
+
+    def start_animation(self, tag: int, anim_id: int, prop_name: str, spec: Dict[str, Any]) -> bool:
+        """Start a natively-driven animation on the view for ``tag``.
+
+        Returns:
+            Whether the platform accepted the animation (``False``
+            means the caller should drive it from the Python ticker).
+        """
+        record = self._records.get(tag)
+        if record is None:
+            return False
+        return bool(record.handler.start_animation(record.view, anim_id, prop_name, spec))
+
+    def cancel_animation(self, tag: int, anim_id: int) -> Any:
+        """Cancel a natively-driven animation; returns the presentation value if known."""
+        record = self._records.get(tag)
+        if record is None:
+            return None
+        return record.handler.cancel_animation(record.view, anim_id)
+
+
+# ======================================================================
+# Singleton registry
+# ======================================================================
+
+_registry: Any = None
+
+
+def _install_sdk_handlers(registry: Any) -> None:
+    """Copy decorator-registered SDK handlers + entry-point plugins.
+
+    Imported lazily so unit tests that never touch the SDK don't pay the
+    entry-point discovery cost. Only meaningful for the Python-handler
+    registry (tests); on the bridge platforms the native runtime owns
+    component managers and Python handlers are recorded but never run.
+    """
+    try:
+        from ..sdk._components import install_into_registry as _sdk_install
+    except Exception:
+        return
+    try:
+        _sdk_install(registry)
+    except Exception:
+        # A misbehaving plugin must not break PythonNative's startup.
+        pass
+
+
+def _create_backend() -> Any:
+    """Build the backend for the active platform.
+
+    iOS, Android, and the browser preview (``PN_PLATFORM=web``) get the
+    bridge backend. Anywhere else (plain unit tests) there is no
+    renderer at all, so the registry is empty: tests inject a
+    ``pythonnative.testing.FakeBackend`` with ``set_registry`` and a
+    stray commit raises a clear "unknown element type" rather than
+    silently importing a platform module.
+    """
+    from ..utils import IS_NATIVE
+
+    if IS_NATIVE:
+        from .bridge_backend import BridgeBackend
+
+        return BridgeBackend()
+    registry = NativeViewRegistry()
+    _install_sdk_handlers(registry)
+    return registry
+
+
+def get_registry() -> Any:
+    """Return the process-wide view backend, creating it on first use.
+
+    Returns:
+        A [`BridgeBackend`][pythonnative.native_views.bridge_backend.BridgeBackend]
+        on every bridge platform, otherwise a `NativeViewRegistry`
+        holding every decorator-registered SDK handler and any handlers
+        exposed by third-party packages via the
+        [`pythonnative.handlers`][pythonnative.sdk.ENTRY_POINT_GROUP]
+        entry point group.
+    """
+    global _registry
+    if _registry is not None:
+        return _registry
+    _registry = _create_backend()
+    return _registry
+
+
+def refresh_registry() -> Any:
+    """Re-run SDK handler installation against the existing backend.
+
+    Call this after registering a new component at runtime if the
+    registry has already been instantiated. This is mostly useful in
+    REPL sessions and tests; the normal flow is "register, then call
+    [`get_registry`][pythonnative.native_views.get_registry]" and the
+    handlers come along automatically.
+    """
+    registry = get_registry()
+    _install_sdk_handlers(registry)
+    return registry
+
+
+def set_registry(registry: Any) -> None:
+    """Install a custom backend (primarily for testing).
+
+    Replaces the lazy singleton so subsequent
+    [`get_registry`][pythonnative.native_views.get_registry] calls
+    return `registry`. Pass a mock to drive the reconciler from
+    unit tests without touching real native APIs. Pass ``None`` to
+    reset the singleton; the next ``get_registry`` call will then
+    rebuild it from scratch.
+
+    Args:
+        registry: The replacement backend, or ``None`` to clear.
+    """
+    global _registry
+    _registry = registry

pythonnative/native_views/base.py

@@ -0,0 +1,316 @@
+"""Shared base classes and utilities for native-view handlers.
+
+Provides the [`ViewHandler`][pythonnative.native_views.base.ViewHandler]
+protocol implemented by Android and iOS handlers, plus the
+[`parse_color_int`][pythonnative.native_views.base.parse_color_int]
+helper shared across platforms.
+
+Layout itself is *not* a handler responsibility. The pure-Python flex
+engine in ``pythonnative.layout`` owns sizing and positioning;
+handlers receive computed frames via
+[`set_frame`][pythonnative.native_views.base.ViewHandler.set_frame] and
+optionally expose an intrinsic-size hook via
+[`measure_intrinsic`][pythonnative.native_views.base.ViewHandler.measure_intrinsic]
+for content-sized leaves (text, buttons, images).
+"""
+
+import math
+import re
+from typing import Any, Dict, Optional, Tuple, Union
+
+
+class ViewHandler:
+    """Protocol implemented by every native-view handler.
+
+    A `ViewHandler` knows how to create, update, re-parent, and destroy
+    native views of one element type. The reconciler never calls a
+    handler directly; it emits a batch of mutation ops
+    (`pythonnative.mutations`) that the
+    [`NativeViewRegistry`][pythonnative.native_views.NativeViewRegistry]
+    applies by dispatching to handlers. Handlers never need to know
+    about `Element` or `VNode`.
+
+    Event contract: props delivered to
+    [`create`][pythonnative.native_views.base.ViewHandler.create] /
+    [`update`][pythonnative.native_views.base.ViewHandler.update]
+    contain **no Python callables**. The set of event names wired on
+    the element arrives under the ``_pn_events`` key (see
+    [`event_names`][pythonnative.events.event_names]); handlers wire
+    platform listeners once at create time and forward firings through
+    [`dispatch_event`][pythonnative.events.dispatch_event] using the
+    tag passed to ``create``.
+
+    Subclasses must override ``create`` and ``update``. Container
+    handlers override the child-management methods; leaf handlers can
+    leave them as no-ops. Handlers whose intrinsic size depends on
+    content (text, buttons, images) override
+    [`measure_intrinsic`][pythonnative.native_views.base.ViewHandler.measure_intrinsic].
+    """
+
+    def create(self, tag: int, props: Dict[str, Any]) -> Any:
+        """Create a fresh native view and apply initial *visual* props.
+
+        Layout-related props (``width``, ``height``, ``flex``, ``padding``,
+        etc.) are consumed by the layout engine and applied via
+        [`set_frame`][pythonnative.native_views.base.ViewHandler.set_frame],
+        so handlers should ignore them here.
+
+        Args:
+            tag: The reconciler-assigned identity for this view. Used
+                when dispatching events back into Python.
+            props: Initial props dict (callable-free; event names under
+                ``_pn_events``).
+
+        Returns:
+            The platform-native view object.
+
+        Raises:
+            NotImplementedError: Subclasses must override.
+        """
+        raise NotImplementedError
+
+    def update(self, native_view: Any, changed_props: Dict[str, Any]) -> None:
+        """Apply only the *visual* props that changed since the last render.
+
+        Args:
+            native_view: The platform-native view to mutate.
+            changed_props: Props whose values changed (a value of
+                `None` indicates the prop was removed).
+
+        Raises:
+            NotImplementedError: Subclasses must override.
+        """
+        raise NotImplementedError
+
+    def insert_child(self, parent: Any, child: Any, index: int) -> None:
+        """Ensure `child` sits at `index` among `parent`'s children.
+
+        Must be **move-aware**: when `child` is already attached to
+        `parent`, reposition it instead of attaching twice. Handlers
+        should clamp `index` to the current child count. No-op for
+        leaf handlers.
+        """
+
+    def remove_child(self, parent: Any, child: Any) -> None:
+        """Remove `child` from `parent` without destroying it. No-op for leaf handlers."""
+
+    def destroy(self, native_view: Any) -> None:
+        """Release platform resources owned by ``native_view``.
+
+        Called exactly once when the reconciler unmounts the view.
+        The default is a no-op; override to detach listeners, cancel
+        in-flight work, or destroy widgets that the platform doesn't
+        garbage-collect.
+        """
+
+    def set_frame(self, native_view: Any, x: float, y: float, width: float, height: float) -> None:
+        """Position and size ``native_view`` relative to its parent.
+
+        Coordinates are in points and relative to the parent's content
+        origin. Default no-op so handlers that don't need explicit
+        positioning (e.g., `Modal`) can opt out.
+
+        Args:
+            native_view: The platform-native view.
+            x: X-coordinate (points) of the view's top-left corner
+                relative to its parent's content origin.
+            y: Y-coordinate (points) of the view's top-left corner.
+            width: View width in points.
+            height: View height in points.
+        """
+
+    def measure_intrinsic(
+        self,
+        native_view: Any,
+        max_width: float,
+        max_height: float,
+    ) -> Tuple[float, float]:
+        """Return the natural ``(width, height)`` of a content-sized view.
+
+        Used by the layout engine for leaves whose size depends on
+        their content (text, buttons, images). Either ``max_width`` or
+        ``max_height`` may be `math.inf` to indicate no constraint.
+
+        The default implementation returns ``(0, 0)``; override for
+        leaves whose size depends on their content. Container handlers
+        leave this alone; the engine sizes containers by laying out
+        their children.
+
+        Args:
+            native_view: The platform-native view to measure.
+            max_width: Maximum width in points (or `math.inf`).
+            max_height: Maximum height in points (or `math.inf`).
+
+        Returns:
+            ``(width, height)`` in points.
+        """
+        return (0.0, 0.0)
+
+    def command(self, native_view: Any, name: str, args: Dict[str, Any]) -> Any:
+        """Execute an imperative command (e.g. ``"scroll_to_offset"``).
+
+        Commands are the escape hatch for one-shot imperative actions
+        that don't fit declarative props: scrolling, focusing,
+        flashing indicators. Unknown commands should be ignored.
+
+        Args:
+            native_view: The platform-native view.
+            name: Command name.
+            args: Command arguments.
+
+        Returns:
+            An optional command-specific result.
+        """
+        return None
+
+    def set_animated_property(self, native_view: Any, prop_name: str, value: Any) -> None:
+        """Apply one frame of a Python-driven animation immediately.
+
+        This is the fallback path used by
+        animations the platform cannot drive natively. ``prop_name``
+        is one of ``opacity``, ``background_color``, ``translate_x``,
+        ``translate_y``, ``scale``, ``scale_x``, ``scale_y``,
+        ``rotate``.
+        """
+
+    def start_animation(
+        self,
+        native_view: Any,
+        anim_id: int,
+        prop_name: str,
+        spec: Dict[str, Any],
+    ) -> bool:
+        """Start a natively-driven animation, if the platform supports it.
+
+        ``spec`` describes the animation::
+
+            {"kind": "timing", "from": 0.0, "to": 1.0,
+             "duration_ms": 300.0, "easing": "ease_in_out"}
+            {"kind": "spring", "from": ..., "to": ...,
+             "stiffness": 100.0, "damping": 10.0, "mass": 1.0,
+             "initial_velocity": 0.0}
+
+        Implementations must invoke
+        ``pythonnative.animated.native_animation_completed(anim_id, finished)``
+        when the animation completes or is cancelled.
+
+        Returns:
+            ``True`` when the animation was started natively. ``False``
+            tells the caller to fall back to the Python ticker (the
+            default).
+        """
+        return False
+
+    def cancel_animation(self, native_view: Any, anim_id: int) -> Any:
+        """Cancel a natively-driven animation.
+
+        Returns:
+            The property's current (presentation) value when the
+            platform can read it, else ``None``.
+        """
+        return None
+
+
+# ======================================================================
+# Color parsing
+# ======================================================================
+
+
+def parse_color_int(color: Union[str, int]) -> int:
+    """Parse a color value into a signed 32-bit ARGB int.
+
+    Accepts `"#RRGGBB"`, `"#AARRGGBB"`, or a raw integer. Java APIs
+    such as `setBackgroundColor` expect a signed 32-bit int, so values
+    with a high alpha byte (e.g., `0xFF......`) must be converted to
+    their negative two's-complement equivalent.
+
+    Args:
+        color: Hex string (with or without leading `#`) or an int.
+
+    Returns:
+        Signed 32-bit ARGB int suitable for Android's color APIs.
+    """
+    if isinstance(color, int):
+        val = color
+    else:
+        c = color.strip().lstrip("#")
+        if len(c) == 6:
+            c = "FF" + c
+        val = int(c, 16)
+    if val > 0x7FFFFFFF:
+        val -= 0x100000000
+    return val
+
+
+# ======================================================================
+# Text helpers shared by every backend's Text handler
+# ======================================================================
+
+_WORD_START = re.compile(r"(?<!\S)(\S)")
+
+
+def transform_text(text: Any, mode: Optional[str]) -> str:
+    """Apply a ``text_transform`` style value to ``text``.
+
+    Runs in Python before the string is handed to the native label, so
+    the displayed text and the intrinsic measurement agree on every
+    backend. ``"capitalize"`` upper-cases the first character of each
+    whitespace-separated word and leaves the rest untouched (matching
+    CSS / React Native rather than ``str.title()``, which would
+    lower-case the remainder). Unknown modes and ``"none"`` return the
+    text unchanged.
+    """
+    s = "" if text is None else str(text)
+    if mode == "uppercase":
+        return s.upper()
+    if mode == "lowercase":
+        return s.lower()
+    if mode == "capitalize":
+        return _WORD_START.sub(lambda m: m.group(1).upper(), s)
+    return s
+
+
+def transform_spans(spans: Any, mode: Optional[str]) -> Any:
+    """Return ``spans`` with `transform_text` applied to each span's ``text``.
+
+    Rich text is flattened into one native string, so a run-by-run
+    transform matches what a single-string transform would produce for
+    ``uppercase`` / ``lowercase``. ``capitalize`` is evaluated per span,
+    which is also how CSS treats inline boxes.
+    """
+    if not mode or mode == "none" or not isinstance(spans, list):
+        return spans
+    out = []
+    for span in spans:
+        if isinstance(span, dict) and "text" in span:
+            copy = dict(span)
+            copy["text"] = transform_text(span.get("text"), mode)
+            out.append(copy)
+        else:
+            out.append(span)
+    return out
+
+
+def shadow_offset_xy(value: Any) -> Tuple[float, float]:
+    """Coerce a ``shadow_offset`` / ``text_shadow_offset`` value to ``(dx, dy)``."""
+    if isinstance(value, dict):
+        return (float(value.get("width", 0) or 0), float(value.get("height", 0) or 0))
+    if isinstance(value, (tuple, list)) and len(value) >= 2:
+        return (float(value[0]), float(value[1]))
+    return (0.0, 0.0)
+
+
+TEXT_SHADOW_STYLE_KEYS = ("text_shadow_color", "text_shadow_offset", "text_shadow_radius")
+"""Style keys that together describe a text shadow."""
+
+
+# ======================================================================
+# Helpers shared by Android and iOS measure callbacks
+# ======================================================================
+
+
+def _safe_max(value: float, fallback: float = 1e6) -> float:
+    """Clamp ``math.inf`` to a large finite value for native measure calls."""
+    if not math.isfinite(value):
+        return fallback
+    return max(0.0, value)